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 arelines
(default) andjson
. See the JSON OUTPUT section below for details on thejson
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 asupdate
,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 tostdout
a machine-readable result description in the specified format. Not all commands support producing structured result and validfmt
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 useb
plus an executable suffix if one was specified when buildingbpkg
. So, for example, ifbpkg
name was set tobpkg-1.0
, then it will look forb-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. Currently,
bpkg
recognizescurl
,wget
, andfetch
. Note that the last component ofpath
must contain one of these names as a substring in order forbpkg
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
, andfetch
. --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 forcurl
and to the--timeout
option forwget
andfetch
. Forgit
over HTTP/HTTPS this semantics is achieved using thehttp.lowSpeedLimit
=1http.lowSpeedTime
=sec configuration values (thegit://
andssh://
protocols currently do not support timeouts).See
--fetch
and--git
for more information on the fetch programs. --pkg-proxy
url
- HTTP proxy server to use when fetching package manifests and archives
from remote
pkg
repositories. If specified, the proxyurl
must be in thehttp://host[:port]
form. Ifport
is omitted, 80 is used by default.Note that to allow caching, the proxied
https://
URLs are converted tohttp://
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 tohttps://
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 usegit
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
recognizessha256
,sha256sum
, andshasum
. Note that the last component ofpath
must contain one of these names as a substring in order forbpkg
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
, andshasum
. --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
orbsdtar
. 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, thenbpkg
will usetar
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, thenbpkg
will useopenssl
by default.The
--openssl*
values can be optionally qualified with the openssl command in thecommand: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 to3.0.0
bpkg
uses thersautl
command instead ofpkeyutl
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 bybpkg
, 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 passingall
or disable authentication completely by passingnone
. --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.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
. --trust-no
- Assume the answer to all authentication prompts is
no
. --git-capabilities
up
=pc
- Protocol capabilities (
pc
) for agit
repository URL prefix (up
). Valid values for the capabilities aredumb
(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 thegit
protocol capabilities. --pager
path
- The pager program to be used to show long text. Commonly used pager
programs are
less
andmore
. 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, thenbpkg
will try to useless
. 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" }
BUGS
Send bug reports to the users@build2.org mailing list.