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.
--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.
--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.
ENVIRONMENT
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.
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.
BUGS
Send bug reports to the
users@build2.org mailing list.