home | help 
bpkg-common-options(1)	     General Commands Manual	  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 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  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 speci-
	    fied format.  Not all commands support producing  structured  result
	    and valid fmt values are command-specific. Consult the command docu-
	    mentation 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 op-
	    tions  that  should  be passed to the build program with --build-op-
	    tion.

	    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, repos-
	    itory  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 pro-
	    gram  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  dis-
	    cover  if  one of the above programs is available and use that. Cur-
	    rently, 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 op-
	    tion.  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 rec-
	    ognized 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 direc-
	    tories  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  reposi-
	    tory 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  de-
	    faults 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 al-
	    low 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 vari-
	    able.

	    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  di-
	    rectory  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 ses-
	    sion  id.  The  cache  session  can  also  be  specified  with   the
	    BPKG_FETCH_CACHE_SESSION environment variable.

     --sqlite-synchronous mode
	    Filesystem	synchronization  mode for the fetch cache and configura-
	    tion SQLite databases. 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 the WAL (Write-Ahead Logging) journaling mode is used  for
	    the  fetch	cache  database and the rollback journaling mode for the
	    configuration databases.

     --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 secu-
	    rity, 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 dis-
	    cover if one of the above programs is available and use  that.  Cur-
	    rently,  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 pro-
	    gram 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 applic-
	    able 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 opera-
	    tions.

	    An unqualified value that contains a colon can be specified as qual-
	    ified 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 op-
	    tionally  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  au-
	    thenticated. 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 cer-
	    tificate 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  sup-
	    port),  smart (support for shallow clone, but not for fetching unad-
	    vertised 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  capa-
	    bilities.

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

     --keep-tmp
	    Don't  remove  the bpkg's temporary directory at the end of the com-
	    mand 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  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 bpkg-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.

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