NAME
bpkg-pkg-bindist – generate binary distribution package
SYNOPSIS
bpkg pkg-bindist|bindist
[--output-root|-o dir] [options] [vars]
pkg...
DESCRIPTION
The pkg-bindist command generates a binary
distribution package for the specified package. If additional packages are
specified, then they are bundled in the same distribution package. All the
specified packages must have been previously configured with bpkg-pkg-build(1) or bpkg-pkg-configure(1).
For some system package managers a directory for intermediate files and
subdirectories as well as the resulting binary package may have to be
specified explicitly with the --output-root|-o
option.
Underneath, this command roughly performs the following steps: First it
installs the specified packages similar to the bpkg-pkg-install(1)
command except that it may override the installation locations (via the
config.install.* variables) to match the distribution's
layout. Then it generates any necessary distribution package metadata files
based on the information from the package manifest
files. Finally, it invokes the distribution-specific command to produce the
binary package. Unless overridden with the
--architecture and --distribution
options, the binary package is generated for the host architecture using the
host's standard system package manager. Additional command line variables
(vars, normally config.*) can be
passed to the build system during the installation step. See the following
distribution-specific description sections below for details and invocation
examples:
The specified packages may have dependencies and the default behavior is
to not bundle them but rather to specify them as dependencies in the
corresponding distribution package metadata, if applicable. This default
behavior can be overridden with the --recursive option
(see the option description for the available modes). Note, however, that
dependencies that are satisfied by system packages are always specified as
dependencies in the distribution package metadata (if applicable).
PKG-BINDIST OPTIONS
See the following sections below for distribution-specific options:
COMMON OPTIONS
The common options are summarized below with a more detailed description
available in bpkg-common-options(1).
DEBIAN DESCRIPTION
The Debian binary packages are generated by producing the standard
debian/control, debian/rules, and
other package metadata files and then invoking
dpkg-buildpackage(1) to build the binary package from
that. In particular, the debian/rules implemenation is
based on the dh(1) command sequencer. While this
approach is normally used to build packages from source, this implementation
"pretends" that this is what's happening by overriding a number of
dh targets to invoke the build2
build system on the required packages directly in their
bpkg configuration locations.
The dpkg-dev (or build-essential)
and debhelper Debian packages must be installed before
invocation. Typical invocation:
bpkg build libhello bpkg test libhello bpkg bindist -o /tmp/output/ libhello
Unless the --recursive option
auto or full modes are specified,
dependencies of the specified package are translated to dependencies in the
resulting binary package using names and versions that refer to packages
that would be generated by the pkg-bindist command
(called "non-native" packages). If instead you would like certain
dependencies to refer to binary packages provided by the distribution
(called "native" packages), then you need to arrange for them to be built as
system (see bpkg-pkg-build(1) for
details). For example, if our libhello has a dependency
on libsqlite3 and we would like the binary package for
libhello to refer to libsqlite3 from
Debian (or alike), then the pkg-build command would need
to be (--sys-install is optional):
bpkg build --sys-install libhello ?sys:libsqlite3
Such a package with native dependencies can then be installed (including
any missing native dependencies) using the apt or
apt-get install command. Note that
the specified .deb file must include a directory
separator (/) in order to be recognized as a file rather than a
package name. For example:
sudo apt-get install ./libhello_1.2.3-0~debian11_amd64.deb \
./libhello-dev_1.2.3-0~debian11_amd64.deb
See Debian
Package Mapping for Production for details on bpkg
to Debian package name and version mapping.
PKG-BINDIST DEBIAN OPTIONS
FEDORA DESCRIPTION
The Fedora binary packages are generated by producing the standard RPM
spec file and then invoking rpmbuild(8) to build the
binary package from that. While this approach is normally used to build
packages from source, this implementation "pretends" that this is what's
happening by overriding a number of RPM spec file sections to invoke the
build2 build system on the required packages directly in
their bpkg configuration locations.
The rpmdevtools Fedora package must be installed
before invocation. Typical invocation:
bpkg build libhello bpkg test libhello bpkg bindist libhello
The resulting binary packages are placed into the standard
rpmbuild output directory (normally
~/rpmbuild/RPMS/arch/).
Unless the --recursive option
auto or full modes are specified,
dependencies of the specified package are translated to dependencies in the
resulting binary package using names and versions that refer to packages
that would be generated by the pkg-bindist command
(called "non-native" packages). If instead you would like certain
dependencies to refer to binary packages provided by the distribution
(called "native" packages), then you need to arrange for them to be built as
system (see bpkg-pkg-build(1) for
details). For example, if our libhello has a dependency
on libsqlite3 and we would like the binary package for
libhello to refer to sqlite-libs
from Fedora (or alike), then the pkg-build command would
need to be (--sys-install is optional):
bpkg build --sys-install libhello ?sys:libsqlite3
Such a package with native dependencies can then be installed (including
any missing native dependencies) using the dnf install
command. For example:
sudo dnf install libhello-1.2.3-1.fc35.x86_64.rpm \
libhello-devel-1.2.3-1.fc35.x86_64.rpm
See Fedora
Package Mapping for Production for details on bpkg
to Fedora package name and version mapping.
PKG-BINDIST FEDORA OPTIONS
ARCHIVE DESCRIPTION
The installation archive binary packages are generated by invoking the
build2 build system on the required packages directly in
their bpkg configuration locations and installing them
into the binary package directory using the
config.install.chroot mechanism. Then this directory is
packaged with tar or zip to produce
one or more binary package archives.
The generation of installation archive packages is never the default and
should be requested explicitly with the
--distribution=archive option. The installation
directory layout and the package archives to generate can be specified with
the --archive-install-* and
--archive-type options (refer to their documentation for
defaults).
The binary package directory (the top-level directory inside the archive) as well as the archive file base (the file name without the extension) are the same and have the following form:
package-version-build_metadata
Where package is the package name and
version is the bpkg package version.
Unless overridden with the --archive-build-meta option,
build_metadata has the following form:
cpu-os[-langrt...]
Where cpu is the target CPU (for example,
x86_64 or aarch64; omitted if
--archive-no-cpu is specified), os
is the ID and VERSION_ID components
from os-release(5) (or equivalent, for example,
debian11 or windows10; omitted if
--archive-no-os is specified), and
langrt are the language runtimes as mapped by the
--archive-lang* options (for example,
gcc12 or msvc17.4).
For example, given the following invocation on Debian 11 running on
x86_64:
bpkg build libhello bpkg test libhello bpkg bindist \ -o /tmp/output/ \ --distribution=archive \ --archive-lang cc=gcc12 \ libhello
We will end up with the package archive in the following form:
libhello-1.2.3-x86_64-debian11-gcc12.tar.xz
The recommended language runtime id format is the runtime name followed
by the version, for example, gcc12 or
msvc17.4. Note that its purpose is not to provide a
precise specification of requirements but rather to help the user of a
binary package to pick the appropriate variant. Refer to the
--archive-lang* options documentation for details on the
mapping semantics.
Instead of mapping languages individually you can specify entire build
metadata as a single value with the --archive-build-meta
(it is also possible to add additional metadata; see the option
documentation for details). For example:
bpkg bindist \ -o /tmp/output/ \ --distribution=archive \ --archive-build-meta=x86_64-linux-glibc libhello
This will produce the package archive in the following form:
libhello-1.2.3-x86_64-linux-glibc.tar.xz
To install the binary package from archive simply unpack it using
tar or zip. You can use the
--strip-components tar option to
remove the top-level package directory (the same can be achieved for
zip archives by using bsdtar on
Windows). For example, to unpack the package contents so that they end up in
/usr/local/:
sudo tar -xf libhello-1.2.3-x86_64-debian11-gcc12.tar.xz \ -C / --strip-components=1
If you expect the binary package to be unpacked into a directory other
than its original installation directory
(--archive-install-root), then it's recommended to make
it relocatable by specifying the
config.install.relocatable=true configuration variable.
For example:
bpkg bindist \ ... \ config.install.relocatable=true \ libhello
Note that not all source packages support relocatable installation (see Rolocatable Installation for details).
Another mechanism that can useful when generating archive packages is the
ability to filter the files being installed. This, for example, can be used
to create binary packages that don't contain any development-related files.
See Installation
Filtering for details. See also the --archive-split
option.
The installation archive package can be generated for a target other than
the host by specifying the target triplet with the
--architecture option. In this case the
bpkg configuration is assumed to be appropriately
configured for cross-compiling to the specified target. You will also need
to explicitly specify the --archive-install-root option
(or --archive-install-config) as well as the
--os-release-id option (and likely want to specify other
--os-release-* options). For example, for
cross-compiling from Linux to Windows using the MinGW GCC toolchain:
bpkg bindist \ --distribution=archive \ --architecture=x86_64-w64-mingw32 \ --os-release-id=windows \ --os-release-name=Windows \ --os-release-version-id=10 \ --archive-install-root / \ --archive-lang cc=mingw_w64_gcc12 \ ...
PKG-BINDIST ARCHIVE OPTIONS
STRUCTURED RESULT
Instead of printing to stderr the list of generated
binary packages in a format more suitable for human consumption, the
pkg-bindist command can be instructed to write it to
stdout in a machine-readable form by specifying the
--structured-result option. Currently, the only
recognized format value for this option is json with the
output being a JSON object that is a serialized representation of the
following C++ struct bindist_result:
struct os_release
{
string name_id; // ID
vector<string> like_ids; // ID_LIKE
optional<string> version_id; // VERSION_ID
optional<string> variant_id; // VARIANT_ID
optional<string> name; // NAME
optional<string> version_codename; // VERSION_CODENAME
optional<string> variant; // VARIANT
};
struct file
{
string type;
string path;
optional<string> system_name;
};
struct package
{
string name;
string version;
optional<string> system_version;
vector<file> files;
};
struct bindist_result
{
string distribution; // --distribution or auto-detected
string architecture; // --architecture or auto-detected
os_release os_release; // --os-release-* or auto-detected
optional<string> recursive; // --recursive
bool private; // --private
bool dependent_config; // See --allow-dependent-config
package package;
vector<package> dependencies; // Only in --recursive=separate
};
For example:
{
"distribution": "debian",
"architecture": "amd64",
"os_release": {
"name_id": "debian",
"version_id": "11",
"name": "Debian GNU/Linux"
},
"package": {
"name": "libfoo",
"version": "2.5.0-b.23",
"system_version": "2.5.0~b.23-0~debian11",
"files": [
{
"type": "main.deb",
"path": "/tmp/libfoo_2.5.0~b.23-0~debian11_amd64.deb",
"system_name": "libfoo"
},
{
"type": "dev.deb",
"path": "/tmp/libfoo-dev_2.5.0~b.23-0~debian11_amd64.deb",
"system_name": "libfoo-dev"
},
...
]
}
}
See the JSON OUTPUT section in bpkg-common-options(1)
for details on the overall properties of this format and the semantics of
the struct serialization.
The file::type member is a distribution-specific
value that classifies the file. For the debian
distribution the possible values are main.deb,
dev.deb, doc.deb,
common.deb, dbgsym.deb,
changes (.changes file), and
buildid (.buildid file); see Debian
Package Mapping for Production for background. For the
fedora distribution the possible values are
main.rpm, devel.rpm,
static.rpm, doc.rpm,
common.rpm, and debuginfo.rpm; see
Fedora
Package Mapping for Production for background. For the
archive distribution this is the archive type
(--archive-type), for example,
tar.xz or zip, potentially prefixed
with key if the --archive-split
functionality is used, for example, dev.tar.xz.
The package::system_version and/or
file::system_name members are absent if not applicable
to the distribution. The file::system_name member is
also absent if the file is not a binary package (for example,
.changes and .buildid files in the
debian distribution).
DEFAULT OPTIONS FILES
See bpkg-default-options-files(1)
for an overview of the default options files. For the
pkg-bindist command the search start directory is the
configuration directory. The following options files are searched for in
each directory and, if found, loaded in the order listed:
bpkg.options bpkg-pkg-bindist.options
The following pkg-bindist command options cannot be
specified in the default options files:
--directory|-d
BUGS
Send bug reports to the users@build2.org mailing list.