home | help 
bdep-common-options(1)	     General Commands Manual	  bdep-common-options(1)

NAME
     bdep-common-options - details on common options

SYNOPSIS
     bdep [common-options] ...

DESCRIPTION
     The  common  options  control behavior that is common to all or most of the
     bdep commands. They can be specified either before the  command  or  after,
     together with the command-specific options.

COMMON OPTIONS
     -v     Print  essential underlying commands being executed. This is equiva-
	    lent to --verbose 2.

     -V     Print all underlying commands being executed. This is equivalent  to
	    --verbose 3.

     --quiet|-q
	    Run  quietly,  only  printing  error messages. This is equivalent to
	    --verbose 0.

     --verbose level
	    Set the diagnostics verbosity to level between 0 and 6. Level 0 dis-
	    ables any non-error messages while level 6 produces lots of informa-
	    tion, with level 1 being the default. The following additional types
	    of diagnostics are produced at each level:

	    1.	High-level information messages.

	    2.	Essential underlying commands being executed.

	    3.	All underlying commands being executed.

	    4.	Information that could be helpful to the user.

	    5.	Information that could be helpful to the developer.

	    6.	Even more detailed information.

     --stdout-format format
	    Representation format to use for printing to  stdout.  Valid  values
	    for  this  option  are lines (default) and json. See the JSON OUTPUT
	    section below for details on the json format.

     --jobs|-j num
	    Number of jobs to perform in parallel. If this option is not  speci-
	    fied  or  specified  with  the 0 value, then the number of available
	    hardware threads is used. If the specified value is  negative,  then
	    the  number  of  available hardware threads reduced by this value is
	    used. This option is also propagated when executing package  manager
	    commands  such  as bpkg-pkg-update(1), bpkg-pkg-test(1), etc., which
	    in turn propagate it to the build system.

     --progress
	    Display progress indicators for  long-lasting  operations,	such  as
	    network  transfers,  building,  etc.  If  printing to a terminal the
	    progress is displayed by default for low verbosity levels. Use --no-
	    progress to suppress.

     --no-progress
	    Suppress progress indicators for long-lasting  operations,	such  as
	    network transfers, building, etc.

     --diag-color
	    Use  color	in  diagnostics.  If printing to a terminal the color is
	    used by default provided the terminal is not  dumb.  Use  --no-diag-
	    color to suppress.

     --no-diag-color
	    Don't use color in diagnostics.

     --bpkg path
	    The  package manager program to be used for build configuration man-
	    agement.  This should be the path to the bpkg  executable.	You  can
	    also specify additional options that should be passed to the package
	    manager program with --bpkg-option.

	    If	the  package  manager  program is not explicitly specified, then
	    bdep will by default use bpkg plus an executable suffix if	one  was
	    specified  when building bdep. So, for example, if bdep name was set
	    to bdep-1.0, then it will look for bpkg-1.0.

     --bpkg-option opt
	    Additional option to be passed to the package manager  program.  See
	    --bpkg  for  more information on the package manager program. Repeat
	    this option to specify multiple package manager options.

     --build path
	    The build program to be used to build packages. This should  be  the
	    path to the build2 b executable. You can also specify additional op-
	    tions  that  should  be passed to the build program with --build-op-
	    tion.

	    If the build program is not explicitly specified, then bdep will  by
	    default  use  b  plus an executable suffix if one was specified when
	    building bdep. So, for example, if bdep name was  set  to  bdep-1.0,
	    then it will look for b-1.0.

     --build-option opt
	    Additional option to be passed to the build program. See --build for
	    more information on the build program. Repeat this option to specify
	    multiple build options.

     --curl path
	    The  curl  program	to  be used for network operations. You can also
	    specify additional options that should be passed to the curl program
	    with --curl-option.

	    If the curl program is not explicitly specified, then bdep will  use
	    curl by default. Note that this program will also be used by the un-
	    derlying bpkg invocations unless overridden.

     --curl-option opt
	    Additional	option	to be passed to the curl program. See --curl for
	    more information on the curl program. Repeat this option to  specify
	    multiple curl options.

	    Note that these options will also be used by the underlying bpkg in-
	    vocations provided that curl is used.

     --offline
	    Do not attempt to download resources (packages, repository metadata,
	    etc),  instead  taking  them from the local fetch cache if available
	    and failing otherwise. See bpkg-common-options(1) for details on the
	    offline mode.

     --no-fetch-cache
	    Disable local caching of download  resources  (packages,  repository
	    metadata,  etc).  By  default  these are cached in a permanent local
	    cache. See bpkg-common-options(1) for details on the fetch cache.

     --fetch-cache mode
	    Comma-separated list of local fetch cache modes. See bpkg-common-op-
	    tions(1) for details on the available modes. Note that  the  default
	    for  bdep  is to enable sharing of cached source directories for de-
	    pendencies during the configuration creation.

     --fetch-cache-session id
	    The local fetch cache session. Specifying the same session id across
	    multiple bdep invocations  allows  eliminating  repeated  up-to-date
	    checks  of	repository  metadata.  Any  value, such as UUID, that is
	    guaranteed not to clash with previous sessions can be used as a ses-
	    sion id. See bpkg-common-options(1) for details on the fetch cache.

     --sqlite-synchronous mode
	    Filesystem synchronization mode for  the  project  SQLite  database.
	    Valid  values  are	off,  normal (default), full, and extra. See the
	    SQLite documentation on the synchronous pragma for details. See also
	    the BUILD2_SQLITE_SYNCHRONOUS environment variable.

	    Note that WAL (Write-Ahead Logging) journaling mode is used for  the
	    project  database.	Note  also that this option is not passed to the
	    underlying bpkg commands (use --bpkg-option for that).

     --pager path
	    The pager program to be used to show long text. Commonly used  pager
	    programs  are less and more. You can also specify additional options
	    that should be passed to the pager program with  --pager-option.  If
	    an	empty  string  is  specified as the pager program, then no pager
	    will be used. If the pager program is not explicitly specified, then
	    bdep will try to use less. If it is not  available,  then  no  pager
	    will be used.

     --pager-option opt
	    Additional option to be passed to the pager program. See --pager for
	    more information on the pager program. Repeat this option to specify
	    multiple pager options.

     --options-file file
	    Read  additional  options  from file. Each option should appear on a
	    separate line optionally followed by space or equal sign (=) and  an
	    option  value.  Empty  lines  and lines starting with # are ignored.
	    Option values can be enclosed in double (") or single (') quotes  to
	    preserve  leading  and  trailing  whitespaces  as well as to specify
	    empty values. If the  value  itself  contains  trailing  or  leading
	    quotes,  enclose it with an extra pair of quotes, for example '"x"'.
	    Non-leading and non-trailing quotes are interpreted as being part of
	    the option value.

	    The semantics of providing options in a file is equivalent	to  pro-
	    viding the same set of options in the same order on the command line
	    at	the  point  where  the --options-file option is specified except
	    that the shell escaping and quoting is not required. Repeat this op-
	    tion to specify more than one options file.

     --default-options dir
	    The directory to load additional default options files from.

     --no-default-options
	    Don't load default options files.

JSON OUTPUT
     Commands that support the JSON output specify their formats as a serialized
     representation of a C++ struct or an array thereof. For example:

     struct package
     {
       string name;
     };

     struct configuration
     {
       uint64_t 	id;
       string		path;
       optional<string> name;
       bool		default;
       vector<package>	packages;
     };

     An example of the serialized JSON representation of struct configuration:

     {
       "id": 1,
       "path": "/tmp/hello-gcc",
       "name": "gcc",
       "default": true,
       "packages": [
	 {
	   "name": "hello"
	 }
       ]
     }

     This sections provides details on the overall properties  of  such  formats
     and the semantics of the struct serialization.

     The  order  of members in a JSON object is fixed as specified in the corre-
     sponding struct. While new members may be added in the future  (and  should
     be  ignored by older consumers), the semantics of the existing members (in-
     cluding whether the top-level entry is an object or array) may not change.

     An object member is required unless its type is optional<>, bool,	or  vec-
     tor<>  (array).  For bool members absent means false.  For vector<> members
     absent means empty. An empty top-level array is always present.

     For example, the following JSON text is a	possible  serialization  of  the
     above struct configuration:

     {
       "id": 1,
       "path": "/tmp/hello-gcc"
     }

DEFAULT OPTIONS FILES
     See  bdep-default-options-files(1)  for  an overview of the default options
     files. The following common options cannot be specified in the default  op-
     tions files:

     --fetch-cache-session

BUGS
     Send bug reports to the users@build2.org mailing list.

COPYRIGHT
     Copyright (c) 2014-2026 the build2 authors.

     Permission is granted to copy, distribute and/or modify this document under
     the terms of the MIT License.

bdep 0.18.0			   April 2026		  bdep-common-options(1)
home | help