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 configurations, packages, and repositories using a set of commands that are summarized below.

For a detailed description of any command or help topic, use the help command or see the corresponding man page (the man pages have the bpkg- prefix, 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 packages out-of-date. In the build2 build system terms a bpkg build configuration 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-repository-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, repository 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 configuration 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 command 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 default 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 semantics.

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 configuration directory paths. This can be used by build system hooks and/or programs 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.