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 equivalent 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 disables any non-error messages while level 6 produces lots of information, 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 specified 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 management. 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 options that should be passed to the build program with --build-option. 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 underlying 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 invocations 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-options(1) for details on the available modes. Note that the default for bdep is to enable sharing of cached source directories for dependencies 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 session 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 providing 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 option 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 corresponding struct. While new members may be added in the future (and should be ignored by older consumers), the semantics of the existing members (including 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 vector<> (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 options 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.