NAME

bpkg-common-options – details on common options

SYNOPSIS

bpkg [common-options] ...

DESCRIPTION

The common options control behavior that is common to all or most of the bpkg 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:

High-level information messages.
Essential underlying commands being executed.
All underlying commands being executed.
Information that could be helpful to the user.
Information that could be helpful to the developer.
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. This option is also propagated when performing build system operations such as update, test, etc.

--no-result

Don't print informational messages about the outcome of performing a command or some of its parts. Note that if this option is specified, then for certain long-running command parts progress is displayed instead, unless suppressed with --no-progress.

--structured-result fmt

Write the result of performing a command in a structured form. In this mode, instead of printing to stderr informational messages about the outcome of performing a command or some of its parts, bpkg writes to stdout a machine-readable result description in the specified format. Not all commands support producing structured result and valid fmt values are command-specific. Consult the command documentation for details.

--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.

--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 bpkg will by default use b plus an executable suffix if one was specified when building bpkg. So, for example, if bpkg name was set to bpkg-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.

--fetch path

The fetch program to be used to download resources (packages, repository metadata, etc). Currently, bpkg recognizes curl, wget, and fetch. Note that the last component of path must contain one of these names as a substring in order for bpkg to recognize which program is being used. You can also specify additional options that should be passed to the fetch program with --fetch-option.

If the fetch program is not specified, then bpkg will try to discover if one of the above programs is available and use that. Currently, bpkg has the following preference order: curl, wget, and fetch.

--fetch-option opt

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

--fetch-timeout sec

The fetch and fetch-like (for example, git) program timeout. While the exact semantics of the value depends on the program used, at a minimum it specifies in seconds the maximum time that can be spent without any network activity.

Specifically, it is translated to the --max-time option for curl and to the --timeout option for wget and fetch. For git over HTTP/HTTPS this semantics is achieved using the http.lowSpeedLimit=1 http.lowSpeedTime=sec configuration values (the git:// and ssh:// protocols currently do not support timeouts).

See --fetch and --git for more information on the fetch programs.

--offline

Do not attempt to download resources (packages, repository metadata, etc), instead taking them from the local fetch cache if available and failing otherwise. Note that no up-to-date checks of cached repository metadata are performed when offline. This mode can also be enabled by setting the BPKG_FETCH_CACHE environment variable, see the --fetch-cache option description for details.

--no-fetch-cache

Disable local caching of downloaded resources (packages, repository metadata, etc). By default these are cached in a persistent local cache. For the location of the cache, see the --fetch-cache-path option. The local cache can also be disabled by setting the BPKG_FETCH_CACHE environment variable to 0 or false.

Note that if this option or environment variable is specified during the configuration creation (cfg-create(1)), its value is saved in the configuration and used as the default in the subsequent bpkg commands involving this configuration.

--fetch-cache mode

Comma-separated list of local fetch cache modes. The currently recognized modes are src/no-src, trust/no-trust, and offline, with their semantics described below. The local cache mode can also be specified with the BPKG_FETCH_CACHE environment variable. Its value has the same format as this option.

The src/no-src mode enables/disables sharing of cached source directories for dependencies. If disabled, then private copies are made in the build configuration directories. The default for bpkg is to disable sharing, which is also the behavior if the fetch cache is disabled (--no-fetch-cache).

The trust/no-trust mode enabled/disables caching of the repository authentication answers given by the user. The default is to enable caching. See bpkg-repository-signing(1) for background on repository authentication.

The offline mode is equivalent to specifying the --offline option.

Note that if this option and/or environment variable is specified during the configuration creation (cfg-create(1)), the effective src and trust modes are saved in the configuration and used as the defaults in the subsequent bpkg commands involving this configuration.

--fetch-cache-path dir

The directory of the local fetch cache. Ideally, this directory should be on the same filesystem (UNIX) or volume (Windows) as the build configuration directories that will rely on this cache to allow the use of hard links. Failing that, the implementation will resort to copying, which may result in sub-optimal performance and inability to accurately track usage. The location of the cache can also be specified with the BPKG_FETCH_CACHE_PATH environment variable.

If not explicitly specified, then the cache location is split across two directories: The non-precious data (packages and repository metadata) is placed into $XDG_CACHE_HOME/build2/ or $HOME/.cache/build2/ on UNIX and into %LOCALAPPDATA%\build2\cache\ on Windows. The semi-precious data (shared source directories) is placed into the .build2/cache/ subdirectory of the user's home directory on all platforms. You can safely remove the non-precious data and while you won't lose any information if the semi-precious data is removed, you may end up with broken builds that will require manual repair.

Note that if the cache location is explicitly specified with this option or the environment variable, then both types of data are placed into the specified directory. Note also that while there is currently no way to impose a size limit on the cache, outdated cache entries are periodically removed.

--fetch-cache-session id

The local fetch cache session. Specifying the same session id across multiple bpkg 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. The cache session can also be specified with the BPKG_FETCH_CACHE_SESSION environment variable.

--pkg-proxy url

HTTP proxy server to use when fetching package manifests and archives from remote pkg repositories. If specified, the proxy url must be in the http://host[:port] form. If port is omitted, 80 is used by default.

Note that to allow caching, the proxied https:// URLs are converted to http:// in order to prevent the fetch program from tunneling (which is the standard approach for proxying HTTPS). If both HTTP and HTTPS repositories are used, it is assumed that the proxy server can figure out which URLs need to be converted back to https:// based on the request information (for example, host name). For security, this mechanism should only be used with signed repositories or when the proxy is located inside a trusted network.

--git path

The git program to be used to fetch git repositories. You can also specify additional options that should be passed to the git program with --git-option.

If the git program is not explicitly specified, then bpkg will use git by default.

--git-option opt

Additional common option to be passed to the git program. Note that the common options are the ones that precede the git command. See --git for more information on the git program. Repeat this option to specify multiple git options.

--sha256 path

The sha256 program to be used to calculate SHA256 sums. Currently, bpkg recognizes sha256, sha256sum, and shasum. Note that the last component of path must contain one of these names as a substring in order for bpkg to recognize which program is being used. You can also specify additional options that should be passed to the sha256 program with --sha256-option.

If the sha256 program is not specified, then bpkg will try to discover if one of the above programs is available and use that. Currently, bpkg has the following preference order: sha256, sha256sum, and shasum.

--sha256-option opt

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

--tar path

The tar program to be used to extract package archives. For example, gtar or bsdtar. You can also specify additional options that should be passed to the tar program with --tar-option. If the tar program is not explicitly specified, then bpkg will use tar by default.

--tar-option opt

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

--openssl path

The openssl program to be used for crypto operations. You can also specify additional options that should be passed to the openssl program with --openssl-option. If the openssl program is not explicitly specified, then bpkg will use openssl by default.

The --openssl* values can be optionally qualified with the openssl command in the command:value form. This makes the value only applicable to the specific command, for example:

bpkg rep-create                      \
  --openssl pkeyutl:/path/to/openssl \
  --openssl-option pkeyutl:-engine   \
  --openssl-option pkeyutl:pkcs11    \
  ...

Note that for openssl versions prior to 3.0.0 bpkg uses the rsautl command instead of pkeyutl for the data signing and recovery operations.

An unqualified value that contains a colon can be specified as qualified with an empty command, for example, --openssl :C:\bin\openssl. To see openssl commands executed by bpkg, use the verbose mode (-v option).

--openssl-option opt

Additional option to be passed to the openssl program. See --openssl for more information on the openssl program. The values can be optionally qualified with the openssl command, as discussed in --openssl. Repeat this option to specify multiple openssl options.

--auth type

Types of repositories to authenticate. Valid values for this option are none, remote, all. By default only remote repositories are authenticated. You can request authentication of local repositories by passing all or disable authentication completely by passing none.

--trust fingerprint

Trust repository certificate with a SHA256 fingerprint. Such a certificate is trusted automatically, without prompting the user for a confirmation. Repeat this option to trust multiple certificates. See bpkg-repository-signing(1) for background.

Note that by default openssl prints a SHA1 fingerprint and to obtain a SHA256 one you will need to pass the -sha256 option, for example:

openssl x509 -sha256 -fingerprint -noout -in cert.pem

--trust-yes

Assume the answer to all authentication prompts is yes. See bpkg-repository-signing(1) for background.

--trust-no

Assume the answer to all authentication prompts is no. See bpkg-repository-signing(1) for background.

--git-capabilities up=pc

Protocol capabilities (pc) for a git repository URL prefix (up). Valid values for the capabilities are dumb (no shallow clone support), smart (support for shallow clone, but not for fetching unadvertised commits), unadv (support for shallow clone and for fetching unadvertised commits). For example:

bpkg build https://example.org/foo.git#master \
  --git-capabilities https://example.org=smart

See bpkg-repository-types(1) for details on the git protocol capabilities.

--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 bpkg 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.

--keep-tmp

Don't remove the bpkg's temporary directory at the end of the command execution and print its path at the verbosity level 2 or higher. This option is primarily useful for troubleshooting.

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 bpkg-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.