home | help 
bpkg(1) 		     General Commands Manual			 bpkg(1)

NAME
     bpkg - package dependency manager

SYNOPSIS
     bpkg --help
     bpkg --version
     bpkg help [command | topic]
     bpkg [common-options] command [command-options] command-args

DESCRIPTION
     The  build2 package dependency manager is used to manipulate build configu-
     rations, packages, and repositories using a set of commands that are summa-
     rized below.

     For a detailed description of any command or help topic, use the help  com-
     mand  or  see the corresponding man page (the man pages have the bpkg- pre-
     fix, for example bpkg-help(1)). Note also that command-options and command-
     args can be specified in any order and common-options can be  specified  as
     part of command-options.

     A bpkg build configuration is a directory that contains packages built with
     similar settings. For example, a configuration can be for a specific target
     (i686, x86_64), compiler (clang, gcc) compile options (-O3, -g), and so on.
     Configurations  are  relatively cheap and can be created and thrown away as
     needed. Configurations can be moved and copied by simply moving and copying
     the directories. Note, however, that a move or copy may render  some  pack-
     ages  out-of-date. In the build2 build system terms a bpkg build configura-
     tion is an amalgamation that contains packages as	subprojects  (see  bpkg-
     cfg-create(1) for details).

     Build  configurations can be linked with each other so that while a package
     is built in one configuration, some of its dependencies  can  be  built  in
     linked configurations (see bpkg-cfg-create(1) for details).

     A bpkg package is an archive or directory (potentially in a version control
     system) that contains a build2 project plus the package manifest file. bpkg
     can either use package archives/directories directly from the filesystem or
     it can fetch them from repositories.

     A	bpkg repository is a collection of packages as well as information about
     prerequisite and complement repositories. Archive,  directory  and  version
     control-based repositories are supported. A repository is identified by its
     location  which  can  be a local filesystem path or a URL. See bpkg-reposi-
     tory-types(1) for details on the repository structures and URL formats.

     If the same version of a package is available from  multiple  repositories,
     then  they  are assumed to contain identical package content. In such cases
     bpkg prefers local repositories over remote and among local repositories it
     prefers the ones with external packages (see bpkg-pkg-unpack(1) for details
     on external packages).

     A typical bpkg workflow would consist of the following steps.

     Create Configuration
	    bpkg create cc		     \
	      config.cxx=clang++	     \
	      config.cc.coptions=-O3	     \
	      config.install.root=/usr/local \
	      config.install.sudo=sudo

     Add Source Repositories
	    bpkg add https://pkg.cppget.org/1/stable
	    bpkg add https://example.org/foo.git

	    Repeat this command to add more repositories.

     Fetch Available Packages List
	    bpkg fetch

     Fetch and Build Packages
	    bpkg build foo bar

     Drop Package
	    If some packages are no longer needed, we can remove them  from  the
	    configuration.

	    bpkg drop foo

     Refresh Available Packages List
	    bpkg fetch

     Upgrade Packages
	    bpkg build bar

     Install Packages
	    bpkg install bar

COMMANDS
     help [topic]
	    bpkg-help(1) - show help for a command or help topic

     cfg-create|create
	    bpkg-cfg-create(1) - create configuration

     cfg-info
	    bpkg-cfg-info(1) - print configuration information

     cfg-link|link
	    bpkg-cfg-link(1) - link configuration

     cfg-unlink|unlink
	    bpkg-cfg-unlink(1) - unlink configuration

     rep-info
	    bpkg-rep-info(1) - print repository information

     rep-add|add
	    bpkg-rep-add(1) - add repository to configuration

     rep-remove|remove
	    bpkg-rep-remove(1) - remove repository from configuration

     rep-list|list
	    bpkg-rep-list(1) - list repositories in configuration

     rep-fetch|fetch
	    bpkg-rep-fetch(1) - fetch list of available packages

     rep-create
	    bpkg-rep-create(1) - create repository

     pkg-status|status
	    bpkg-pkg-status(1) - print package status

     pkg-build|build
	    bpkg-pkg-build(1) - build package

     pkg-drop|drop
	    bpkg-pkg-drop(1) - drop package

     pkg-install|install
	    bpkg-pkg-install(1) - install package

     pkg-uninstall|uninstall
	    bpkg-pkg-uninstall(1) - uninstall package

     pkg-update|update
	    bpkg-pkg-update(1) - update package

     pkg-test|test
	    bpkg-pkg-test(1) - test package

     pkg-clean|clean
	    bpkg-pkg-clean(1) - clean package

     pkg-bindist|bindist
	    bpkg-pkg-bindist(1) - generate binary distribution package

     pkg-verify
	    bpkg-pkg-verify(1) - verify package archive

     pkg-fetch
	    bpkg-pkg-fetch(1) - fetch package archive

     pkg-unpack
	    bpkg-pkg-unpack(1) - unpack package archive

     pkg-checkout
	    bpkg-pkg-checkout(1) - check out package version

     pkg-configure
	    bpkg-pkg-configure(1) - configure package

     pkg-disfigure
	    bpkg-pkg-disfigure(1) - disfigure package

     pkg-purge
	    bpkg-pkg-purge(1) - purge package

HELP TOPICS
     common-options
	    bpkg-common-options(1) - details on common options

     default-options-files
	    bpkg-default-options-files(1) - specifying default options

     repository-types
	    bpkg-repository-types(1) - repository types, structure, and URLs

     repository-signing
	    bpkg-repository-signing(1) - how to sign repository

     argument-grouping
	    bpkg-argument-grouping(1) - argument grouping facility

COMMON OPTIONS
     The  common  options  are summarized below with a more detailed description
     available in bpkg-common-options(1).

     -v     Print essential underlying commands being executed.

     -V     Print all underlying commands being executed.

     --quiet|-q
	    Run quietly, only printing error messages.

     --verbose level
	    Set the diagnostics verbosity to level between 0 and 6.

     --stdout-format format
	    Representation format to use for printing to stdout.

     --jobs|-j num
	    Number of jobs to perform in parallel.

     --no-result
	    Don't print informational messages about the outcome of performing a
	    command or some of its parts.

     --structured-result fmt
	    Write the result of performing a command in a structured form.

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

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

     --diag-color
	    Use color in diagnostics.

     --no-diag-color
	    Don't use color in diagnostics.

     --build path
	    The build program to be used to build packages.

     --build-option opt
	    Additional option to be passed to the build program.

     --fetch path
	    The fetch program to be used to download resources (packages, repos-
	    itory metadata, etc).

     --fetch-option opt
	    Additional option to be passed to the fetch program.

     --fetch-timeout sec
	    The fetch and fetch-like (for example, git) program timeout.

     --offline
	    Do not attempt to download resources (packages, repository metadata,
	    etc), instead taking them from the local fetch  cache  if  available
	    and failing otherwise.

     --no-fetch-cache
	    Disable  local caching of downloaded resources (packages, repository
	    metadata, etc).

     --fetch-cache mode
	    Comma-separated list of local fetch cache modes.

     --fetch-cache-path dir
	    The directory of the local fetch cache.

     --fetch-cache-session id
	    The local fetch cache session.

     --sqlite-synchronous mode
	    Filesystem synchronization mode for the fetch cache  and  configura-
	    tion SQLite databases.

     --pkg-proxy url
	    HTTP  proxy  server  to  use  when	fetching  package  manifests and
	    archives from remote pkg repositories.

     --git path
	    The git program to be used to fetch git repositories.

     --git-option opt
	    Additional common option to be passed to the git program.

     --sha256 path
	    The sha256 program to be used to calculate SHA256 sums.

     --sha256-option opt
	    Additional option to be passed to the sha256 program.

     --tar path
	    The tar program to be used to extract package archives.

     --tar-option opt
	    Additional option to be passed to the tar program.

     --openssl path
	    The openssl program to be used for crypto operations.

     --openssl-option opt
	    Additional option to be passed to the openssl program.

     --auth type
	    Types of repositories to authenticate.

     --trust fingerprint
	    Trust repository certificate with a SHA256 fingerprint.

     --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 a git repository URL prefix (up).

     --pager path
	    The pager program to be used to show long text.

     --pager-option opt
	    Additional option to be passed to the pager program.

     --options-file file
	    Read additional options from 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.

EXIT STATUS
     0
	    Success.

     1
	    Fatal error.

     2
	    Recoverable error which is likely to disappear if the command is re-
	    executed.

ENVIRONMENT
     The BPKG_DEF_OPT environment variable is used to suppress	loading  of  de-
     fault  options  files in nested bpkg invocations. Its values are false or 0
     to suppress and true or 1 to load.

     The BPKG_FETCH_CACHE, BPKG_FETCH_CACHE_PATH,  and	BPKG_FETCH_CACHE_SESSION
     environment  variables  can  be used to control local caching of downloaded
     resources (packages, repository metadata, etc).  See the description of the
     --fetch-cache* options in bpkg-common-options(1) for details on  their  se-
     mantics.

     The  BUILD2_SQLITE_SYNCHRONOUS  environment  variable can be used to select
     the filesystem synchronization mode for the fetch cache  and  configuration
     SQLite databases. See the description of the --sqlite-synchronous option in
     bpkg-common-options(1)  for  the  list of valid values and details on their
     semantics.

     Commands executed by bpkg while the current and linked build  configuration
     databases are open will have the BPKG_OPEN_CONFIGS environment variable set
     to the space-separated, "-quoted list of absolute and normalized configura-
     tion  directory  paths.  This can be used by build system hooks and/or pro-
     grams that they execute.

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(1)
home | help