bpkg-pkg-bindist(1) bpkg 0.19.0-a.0.z

# 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:

DEBIAN DESCRIPTION

FEDORA DESCRIPTION

ARCHIVE DESCRIPTION

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:

PKG-BINDIST DEBIAN OPTIONS

PKG-BINDIST FEDORA OPTIONS

PKG-BINDIST ARCHIVE OPTIONS

`--distribution` `name`
  Alternative system/distribution package manager to generate the binary package for. The valid `name` values are `debian` (Debian and alike, such as Ubuntu, etc), `fedora` (Fedora and alike, such as RHEL, CentOS, etc), and `archive` (installation archive on any operating system). Note that some package managers may only be supported when running on certain host operating systems.
`--architecture` `name`
  Alternative architecture to generate the binary package for. The valid `name` values are system/distribution package manager-specific. If unspecified, the host architecture is used.
`--recursive` `mode`
  Bundle or generate dependencies of the specified packages. The `mode` value can be either `auto`, in which case only the required files from each dependency package are bundled, `full`, in which case all the files are bundled, or `separate`, in which case a separate binary package is generated for each non-system dependency. It can also be `none` which is equivalent to not specifying this option (primarily useful for overriding a previously-specified value).

  Specifically, in the `auto` mode any required files, such as shared libraries, are pulled implicitly by the `install` build system operation, for example, as part of installing an executable from one of the specified packages. In contrast, in the `full` mode, each dependency package is installed explicitly and completely, as if they were specified as additional package on the command line. The `separate` mode is equivalent to invoking the `pkg-bindist` command on each dependency package. See also the `--private` option.

  The `mode` value can also be prefixed with the package name in the `[?]pkg=mode` form in order to specify the mode on the per-package basis. Specifically, if the package name starts with `?`, then the mode applies to the package itself (which only makes sense for dependencies) and otherwise – only to this package's dependencies, recursively (until and unless overridden with another package-specific mode).

`--private`
  Enable the private installation subdirectory functionality using the package name as the private subdirectory. This is primarily useful when bundling dependencies, such as shared libraries, of an executable that is being installed into a shared location, such as `/usr/`. See the `config.install.private` configuration variable documentation in the build system manual for details. This option only makes sense together with the `--recursive` option `auto` and `full` modes.
`--output-root`|`-o` `dir`
  Directory for intermediate files and subdirectories as well as the resulting binary package. Note that this option may be required for some system package managers and may not be specified for others.
`--wipe-output`
  Wipe the output root directory (either specified with `--output-root` or system package manager-specific) clean before using it to generate the binary package.
`--keep-output`
  Keep intermediate files in the output root directory (either specified with `--output-root` or system package manager-specific) that were used to generate the binary package. This is primarily useful for troubleshooting.
`--allow-dependent-config`
  Allow configuration that is imposed by dependent packages. Normally this is undesirable because the resulting binary packages become configured specificaly for particular dependent packages.
`--os-release-id` `v`
  Override the `ID` component in `os-release(5)` or equivalent. Note that unlike the rest of the `--os-release-*` options, this option suppresses automatic detection of the host operating system information.
`--os-release-version-id` `v`
  Override the `VERSION_ID` component in `os-release(5)` or equivalent.
`--os-release-name` `v`
  Override the `NAME` component in `os-release(5)` or equivalent.
`--directory`|`-d` `dir`
  Assume configuration is in `dir` rather than in the current working directory.

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

# 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

`--debian-prepare-only`
  Prepare all the package metadata files (`control`, `rules`, etc) but do not invoke `dpkg-buildpackage` to generate the binary package, printing its command line instead unless requested to be quiet. Implies `--keep-output`.
`--debian-buildflags` `mode`
  Package build flags (`dpkg-buildflags`) usage mode. Valid `mode` values are `assign` (use the build flags instead of configured), `append` (use the build flags in addition to configured, putting them last), `prepend` (use the build flags in addition to configured, putting them first), and `ignore` (ignore build flags). The default mode is `assign`. Note that compiler mode options, if any, are used as configured.
`--debian-maint-option` `o`
  Alternative options to specify in the `DEB_BUILD_MAINT_OPTIONS` variable of the `rules` file. To specify multiple maintainer options repeat this option and/or specify them as a single value separated with spaces.
`--debian-build-option` `o`
  Additional option to pass to the `dpkg-buildpackage` program. Repeat this option to specify multiple build options.
`--debian-build-meta` `data`
  Alternative or additional build metadata to include in the binary package version. If the specified value starts/ends with `+` then the value (with `+` removed) is added after/before the default metadata. Otherwise it is used as is instead of the default metadata. If empty value is specified, then no build metadata is included. By default, the build metadata is the `ID` and `VERSION_ID` components from `os-release(5)`, for example, `debian10` in version `1.2.3-0~debian10`. See also `--os-release-*`.
`--debian-section` `v`
  Alternative `Section` `control` file field value for the main binary package. The default is either `libs` or `devel`, depending on the package type.
`--debian-priority` `v`
  Alternative `Priority` `control` file field value. The default is `optional`.
`--debian-maintainer` `v`
  Alternative `Maintainer` `control` file field value. The default is the `package-email` value from package `manifest`.
`--debian-architecture` `v`
  Alternative `Architecture` `control` file field value for the main binary package, normally `all` (architecture-independent). The default is `any` (architecture-dependent).
`--debian-main-langdep` `v`
  Override the language runtime dependencies (such as `libc6`, `libstdc++6`, etc) in the `Depends` `control` file field value of the main binary package.
`--debian-dev-langdep` `v`
  Override the language runtime dependencies (such as `libc-dev`, `libstdc++-dev`, etc) in the `Depends` `control` file field value of the development (`-dev`) binary package.
`--debian-main-extradep` `v`
  Extra dependencies to add to the `Depends` `control` file field value of the main binary package.
`--debian-dev-extradep` `v`
  Extra dependencies to add to the `Depends` `control` file field value of the development (`-dev`) binary package.
`--debian-no-debug`
  Don't generate the debug information (`-dbgsym`) binary package.

# 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

`--fedora-prepare-only`
  Prepare the RPM spec file but do not invoke `rpmbuild` to generate the binary package, printing its command line instead unless requested to be quiet.
`--fedora-buildflags` `mode`
  Package build flags (`%{build_*flags}` macros) usage mode. Valid `mode` values are `assign` (use the build flags instead of configured), `append` (use the build flags in addition to configured, putting them last), `prepend` (use the build flags in addition to configured, putting them first), and `ignore` (ignore build flags). The default mode is `assign`. Note that compiler mode options, if any, are used as configured.
`--fedora-build-option` `o`
  Additional option to pass to the `rpmbuild` program. If specified, these options must be consistent with the query options (`--fedora-query-option`) to result in identical macro expansions. Repeat this option to specify multiple build options.
`--fedora-query-option` `o`
  Additional option to pass to the `rpm` program. This program is used to query RPM macro values which affect the binary package. If specified, these options must be consistent with the build options (`--fedora-build-option`) to result in identical macro expansions. Repeat this option to specify multiple query options.
`--fedora-dist-tag` `tag`
  Alternative or additional distribution tag to use in the binary package release. If the specified value starts/ends with `+` then the value (with `+` removed) is added after/before the default distribution tag. Otherwise it is used as is instead of the default tag. If empty value is specified, then no distribution tag is included. The default is a value that identifies the distribution being used to build the package, for example, `fc35` for Fedora 35 or `el8` for RHEL 8.
`--fedora-packager` `v`
  Alternative `Packager` RPM spec file directive value. The default is the `package-email` value from package `manifest`. If empty value is specified, then the `Packager` directive is omitted from the spec file.
`--fedora-build-arch` `v`
  `BuildArch` RPM spec file directive value for the main binary package, normally `noarch` (architecture-independent). By default the directive is omitted, assuming that the package is architecture-dependent.
`--fedora-main-langreq` `v`
  Override the language runtime dependencies (such as `glibc`, `libstdc++`, etc) of the main binary package by replacing the corresponding `Requires` RPM spec file directives. If empty value is specified then no language runtime dependencies are specified. Repeat this option to specify multiple language runtime dependencies.
`--fedora-devel-langreq` `v`
  Override the language runtime dependencies (such as `glibc-devel`, `libstdc++-devel`, etc) of the development (`-devel`) binary package by replacing the corresponding `Requires` RPM spec file directives. If empty value is specified then no language runtime dependencies are specified. Repeat this option to specify multiple language runtime dependencies.
`--fedora-stat-langreq` `v`
  Override the language runtime dependencies (such as `glibc-static`, `libstdc++-static`, etc) of the static libraries (`-static`) binary package by replacing the corresponding `Requires` RPM spec file directives. If empty value is specified then no language runtime dependencies are specified. Repeat this option to specify multiple language runtime dependencies.
`--fedora-main-extrareq` `v`
  Extra dependency to add to the main binary package as an additional `Requires` RPM spec file directive. Repeat this option to specify multiple extra dependencies.
`--fedora-devel-extrareq` `v`
  Extra dependency to add to the development (`-devel`) binary package as an additional `Requires` RPM spec file directive. Repeat this option to specify multiple extra dependencies.
`--fedora-stat-extrareq` `v`
  Extra dependency to add to the static libraries (`-static`) binary package as an additional `Requires` RPM spec file directive. Repeat this option to specify multiple extra dependencies.
`--fedora-no-debug`
  Don't generate the debug information (`-debuginfo`) binary package.

# 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

`--archive-prepare-only`
  Prepare all the package contents but do not create the binary package archive, printing its directory instead unless requested to be quiet. Implies `--keep-output`.
`--archive-type` `ext`
  Archive type to create specified as a file extension, for example, `tar.xz`, `tar.gz`, `tar`, `zip`. Repeat this option to generate multiple archive types. If unspecified, then a default type appropriate for the target operating system is used, currently `zip` for Windows and `tar.xz` for POSIX. Note, however, that these defaults may change in the future.
`--archive-lang` `ln`=`rt`
  Map interface language name `ln` to runtime id `rt`. If no mapping is found for an interface language in this map, then fallback to the `--archive-lang-impl` map. If still no mapping is found, then fail. If the information about an interface language is unimportant and should be ignored, then empty runtime id can be specified. Note that the mapping specified with this option is only considered if the package type is a library (for other package types all languages used are implementation). Note also that multiple runtime ids specified for the same language are combined except for an empty id, which is treated as a request to clear previous entries.
`--archive-lang-impl` `ln`=`rt`
  Map implementation language name `ln` to runtime id `rt`. If no mapping is found for an implementation language in this map, then assume the information about this implementation language is unimportant and ignore it (examples of such cases include static linking as well as a language runtime that is always present). See `--archive-lang` for background.
`--archive-no-cpu`
  Assume the package is CPU architecture-independent and omit it from the binary package directory name and archive file base.
`--archive-no-os`
  Assume the package is operating system-independent and omit it from the binary package directory name and archive file base.
`--archive-build-meta` `data`
  Alternative or additional build metadata to include after the version in the binary package directory and file names. If the specified value starts/ends with `+` then the value (with `+` removed) is added after/before the default metadata. Otherwise it is used as is instead of the default metadata. If empty value is specified, then no build metadata is included.
`--archive-install-root` `d`
  Alternative installation root directory. The default is `/usr/local/` on POSIX and `C:\project\` on Windows, where `project` is the `project` package manifest value.
`--archive-install-config`
  Use the installation directory layout (`config.install.*` variables) as configured instead of overriding them with defaults appropriate for the target operating system. Note that this includes `config.install.private` and `config.bin.rpath` if needed for a private installation. Note also that the `config.install.root` value is still overridden with the `--archive-install-root` option value if specified.
`--archive-strip-comps` `num`
  Number of leftmost directory components to strip from the installation root directory path for the installed files before archiving. Note that this option doesn't affect the `config.install.root` variable. Rather, it alters the layout of the top-level directory inside the archive after the installation. As a result, this option should normally only be used if the installation is relocatable (in a sense, this option relocates the installation during the archive creation rather than, more typically, archive extraction).
`--archive-split` `key`=`filt`
  Split the installation into multiple binary packages. Specifically, for each `key`=`filt` pair, perform the `install` operation with `config.install.filter=filt` and package the resulting files as `package-key-version-build_metadata` omitting the `-key` part if `key` is empty. Note that wildcard patterns in `filt` must be quoted. See Installation Filtering for background.

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