diff options
Diffstat (limited to 'bpkg/pkg-bindist.cli')
| -rw-r--r-- | bpkg/pkg-bindist.cli | 220 |
1 files changed, 214 insertions, 6 deletions
diff --git a/bpkg/pkg-bindist.cli b/bpkg/pkg-bindist.cli index f3c3899..cdbb10c 100644 --- a/bpkg/pkg-bindist.cli +++ b/bpkg/pkg-bindist.cli @@ -1,6 +1,8 @@ // file : bpkg/pkg-bindist.cli // license : MIT; see accompanying LICENSE file +include <map>; + include <bpkg/configuration.cli>; "\section=1" @@ -155,7 +157,7 @@ namespace bpkg If empty value is specified, then no build metadata is included. By default, the build metadata is the \cb{ID} and \cb{VERSION_ID} components from \cb{os-release(5)}, for example, \cb{debian10} in - version \cb{1.2.3-0~debian10}." + version \cb{1.2.3-0~debian10}. See also \cb{--os-release-*}." } string --debian-section @@ -218,11 +220,194 @@ namespace bpkg } }; + class pkg_bindist_archive_options + { + "\h|ARCHIVE DESCRIPTION| + + The installation archive binary packages are generated by invoking the + \cb{build2} build system on the required packages directly in their + \cb{bpkg} configuration locations and installing them into the binary + package directory using the \cb{config.install.chroot} mechanism. Then + this directory is packaged with \cb{tar} or \cb{zip} to produce one or + more binary package archives. The installation directory layout and + the package archives to generate can be specified with the + \cb{--archive-install-*} and \cb{--archive-type} options (also 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: + + \c{\i{package}-\i{version}-\i{build_metadata}} + + Where \ci{package} is the package name and \ci{version} is the \cb{bpkg} + package version. Unless overridden with the \cb{--archive-build-meta} + option, \ci{build_metadata} has the following form: + + \c{\i{cpu}-\i{os}[-\i{langrt}...]} + + Where \ci{cpu} is the target CPU (for example, \cb{x86_64}), \ci{os} is + the \cb{ID} and \cb{VERSION_ID} components from \cb{os-release(5)} (or + equivalent, for example, \cb{debian11} or \cb{windows10}), and + \ci{langrt} are the language runtimes as mapped by the + \cb{--archive-lang*} options (for example, \cb{gcc12}, \cb{msvc17.4}). + + For example, given the following invocation on Debian 11: + + \ + 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, \cb{gcc12} or \cb{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 \cb{--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 \cb{--archive-build-meta}, 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 + \cb{tar} or \cb{zip}. You can use the \cb{--strip-components} \cb{tar} + option to remove the top-level package directory (the same can be + achieved for \cb{zip} archives by using \cb{bsdtar} on Windows). For + example, to unpack the package contents so that they end up in + \cb{/usr/local/}: + + \ + sudo tar -xf libhello-1.2.3-x86_64-debian11-gcc12.tar.xz \ + -C / --strip-components=1 + \ + + The installation archive package can be generated for a target other than + the host by specifying the target triplet with the \cb{--architecture} + option. In this case the \cb{bpkg} configuration is assumed to be + appropriately configured for cross-compiling to the specified target. You + will also need to explicitly specify the \cb{--archive-install-root} + option (or \cb{--archive-install-config}) as well as the + \cb{--os-release-id} option (and likely want to specify other + \cb{--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 \ + ... + \ + " + + "\h|PKG-BINDIST ARCHIVE OPTIONS|" + + bool --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 \cb{--keep-output}." + } + + strings --archive-type + { + "<ext>", + "Archive type to create specified as a file extension, for example, + \cb{tar.xz}, \cb{tar.gz}, \cb{tar}, \cb{zip}. Repeat this option to + generate multiple archive types. If unspecified, then a default type + appropriate for the target operating system is used, currently \cb{zip} + for Windows and \cb{tar.xz} for POSIX. Note, however, that these + defaults may change in the future." + } + + std::map<string, string> --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 + \cb{--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)." + } + + std::map<string, string> --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)." + } + + string --archive-build-meta + { + "<data>", + "Alternative build metadata to include after the version in the binary + package directory and file names. If empty value is specified, then no + build metadata is included." + } + + dir_path --archive-install-root + { + "<d>", + "Alternative installation root directory. The default is \cb{/usr/local/} + on POSIX and \c{\b{C:\\}\i{project}\b{\\}} on Windows, where + \ci{project} is the \l{bpkg#manifest-package-project \cb{project}} + package manifest value." + } + + bool --archive-install-config + { + "Use the installation directory layout (\cb{config.install.*} variables) + as configured instead of overriding them with defaults appropriate for + the target operating system. Note that this includes + \cb{config.install.private} and \cb{config.bin.rpath} if needed for a + private installation. Note also that the \cb{config.install.root} value + is still overridden with the \cb{--archive-install-root} option value + if specified." + } + }; + // NOTE: remember to add the corresponding `--class-doc ...=exclude-base` // (both in bpkg/ and doc/) if adding a new base class. // class pkg_bindist_options: configuration_options, - pkg_bindist_debian_options + pkg_bindist_debian_options, + pkg_bindist_archive_options { "\h|PKG-BINDIST COMMON OPTIONS|" @@ -230,10 +415,11 @@ namespace bpkg { "<name>", "Alternative system/distribution package manager to generate the binary - package for. The valid <name> values are \cb{debian} (Debian and - alike, such as Ubuntu, etc) and \cb{fedora} (Fedora and alike, - such as RHEL, CentOS, etc). Note that some package managers may - only be supported when running on certain host operating systems." + package for. The valid <name> values are \cb{debian} (Debian and alike, + such as Ubuntu, etc), \cb{fedora} (Fedora and alike, such as RHEL, + CentOS, etc), and \cb{archive} (installation archive on any operating + system). Note that some package managers may only be supported when + running on certain host operating systems." } string --architecture @@ -293,6 +479,28 @@ namespace bpkg used to generate the binary package. This is primarily useful for troubleshooting." } + + string --os-release-id + { + "<v>", + "Override the \cb{ID} component in \cb{os-release(5)} or equivalent. + Note that unlike the rest of the \cb{--os-release-*} options, this + option suppresses automatic detection of the host operating system + inormation." + } + + string --os-release-version-id + { + "<v>", + "Override the \cb{VERSION_ID} component in \cb{os-release(5)} or + equivalent." + } + + string --os-release-name + { + "<v>", + "Override the \cb{NAME} component in \cb{os-release(5)} or equivalent." + } }; " |