bpkg-common-options(1)

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:

    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.

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

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

--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. 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: wget 1.16 or higher (supports --show-progress), 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.

--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 rsautl:/path/to/openssl \
      --openssl-option rsautl:-engine   \
      --openssl-option rsautl:pkcs11    \
      ...
    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. 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.

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

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

COPYRIGHT
Copyright (c) 2014-2019 Code Synthesis Ltd Permission is granted to copy, distribute and/or modify this document under the terms of the MIT License.