diff options
Diffstat (limited to 'bpkg/pkg-bindist.cli')
| -rw-r--r-- | bpkg/pkg-bindist.cli | 290 |
1 files changed, 290 insertions, 0 deletions
diff --git a/bpkg/pkg-bindist.cli b/bpkg/pkg-bindist.cli new file mode 100644 index 0000000..dbbf9c3 --- /dev/null +++ b/bpkg/pkg-bindist.cli @@ -0,0 +1,290 @@ +// file : bpkg/pkg-bindist.cli +// license : MIT; see accompanying LICENSE file + +include <bpkg/configuration.cli>; + +"\section=1" +"\name=bpkg-pkg-bindist" +"\summary=generate binary distribution package" + +namespace bpkg +{ + { + "<options> <dir> <vars> <pkg>", + + "\h|SYNOPSIS| + + \c{\b{bpkg pkg-bindist}|\b{bindist} [\b{--output-root}|\b{-o} <dir>] [<options>] [<vars>] <pkg>...} + + \h|DESCRIPTION| + + The \cb{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 \l{bpkg-pkg-build(1)} or + \l{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 + \c{\b{--output-root}|\b{-o}} option. + + Underneath, this command roughly performs the following steps: First it + installs the specified packages similar to the \l{bpkg-pkg-install(1)} + command except that it may override the installation locations (via the + \cb{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 \cb{manifest} files. Finally, it invokes + the distribution-specified command to produce the binary package. Unless + overrident with the \cb{--architecture} and \cb{--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 \cb{config.*}) can be passed to the build system during + the installation step. See 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 \cb{--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. + " + } + + // Place distribution-specific options into separate classes in case one day + // we want to only pass their own options to each implementation. + // + class pkg_bindist_debian_options + { + "\h|DEBIAN DESCRIPTION| + + The Debian binary packages are generated by producing the standard + \cb{debian/control}, \cb{debian/rules}, and other package metadata files + and then invoking \cb{dpkg-buildpackage(1)} to build the binary package + from that. In particular, the \cb{debian/rules} implemenation is based on + the \cb{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 \cb{dh} targets to invoke the + \cb{build2} build system on the required packages directly in their + \cb{bpkg} configuration locations. Typical invocation: + + \ + bpkg build libhello + bpkg test libhello + bpkg bindist -o /tmp/output/ libhello + \ + + Note that the \cb{dpkg-dev} (or \cb{build-essential}) and \cb{debhelper} + Debian packages must be installed before invocation. + + See \l{bpkg#bindist-mapping-debian-produce Debian Package Mapping for + Production} for details on \cb{bpkg} to Debian package name and version + mapping. + " + + "\h|PKG-BINDIST DEBIAN OPTIONS|" + + bool --debian-prepare-only + { + "Prepare all the package metadata files (\cb{control}, \cb{rules}, etc) + but do not invoke \cb{bpkg-buildpackage} to generate the binary + package, printing its command line instead unless requested to be + quiet. Implies \cb{--keep-output}." + } + + string --debian-buildflags = "assign" + { + "<mode>", + "Package build flags (\cb{dpkg-buildflags}) usage mode. Valid <mode> + values are \cb{assign} (use the build flags instead of configured), + \cb{append} (use the build flags in addition to configured, putting + them last), \cb{prepend} (use the build flags in addition to + configured, putting them first), and \cb{ignore} (ignore build + flags). The default mode is \cb{assign}. Note that compiler mode + options, if any, are used as configured." + } + + strings --debian-maint-option + { + "<o>", + "Alternative options to specify in the \cb{DEB_BUILD_MAINT_OPTIONS} + variable of the \cb{rules} file. To specify multiple maintainer options + repeat this option and/or specify them as a single value separated + with spaces." + } + + strings --debian-build-option + { + "<o>", + "Additional option to pass to the \cb{dpkg-buildpackage} program. Repeat + this option to specify multiple build options." + } + + string --debian-build-meta + { + "<data>", + "Alternative build metadata to include in the binary package version. + 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}." + } + + string --debian-section + { + "<v>", + "Alternative \cb{Section} \cb{control} file field value for the main + binary package. The default is either \cb{libs} or \cb{devel}, + depending on the package type." + } + + string --debian-priority + { + "<v>", + "Alternative \cb{Priority} \cb{control} file field value. The default + is \cb{optional}." + } + + string --debian-maintainer + { + "<v>", + "Alternative \cb{Maintainer} \cb{control} file field value. The + default is the \cb{package-email} value from package \cb{manifest}." + } + + string --debian-architecture + { + "<v>", + "Alternative \cb{Architecture} \cb{control} file field value for + the main binary package. The default is \cb{any}." + } + + string --debian-main-langdep + { + "<v>", + "Override the language runtime dependencies (such as \cb{libc6}, + \cb{libstdc++6}, etc) in the \cb{Depends} \cb{control} file field + value of the main binary package." + } + + string --debian-dev-langdep + { + "<v>", + "Override the language runtime dependencies (such as \cb{libc-dev}, + \cb{libstdc++-dev}, etc) in the \cb{Depends} \cb{control} file field + value of the development (\cb{-dev}) binary package." + } + + string --debian-main-extradep + { + "<v>", + "Extra dependencies to add to the \cb{Depends} \cb{control} file field + value of the main binary package." + } + + string --debian-dev-extradep + { + "<v>", + "Extra dependencies to add to the \cb{Depends} \cb{control} file field + value of the development (\cb{-dev}) binary package." + } + }; + + // 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 + { + "\h|PKG-BINDIST COMMON OPTIONS|" + + string --distribution + { + "<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." + } + + string --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." + } + + string --recursive + { + "<mode>", + "Bundle dependencies of the specified packages. The <mode> value can be + either \cb{auto}, in which case only the required files from each + dependency package are bundled, or \cb{full}, in which case all the + files are bundled. Specifically, in the \cb{auto} mode any required + files, for example, shared libraries, are pulled implicitly by the + \cb{install} build system operation, for example, as part of + installing an executable from one of the specified packages. In + contrast, in the \cb{full} mode, each dependency package is + installed explicitly and completely, as if they were specified + as additional package on the command line. See also the \cb{--private} + option." + } + + bool --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 \cb{/usr/}. + See the \cb{config.install.private} configuration variable + documentation in the build system manual for details. This option only + makes sense together with \cb{--recursive}." + } + + dir_path --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." + } + + bool --wipe-output + { + "Wipe the output root directory (either specified with \ci{--output-root} + or system package manager-specific) clean before using it to generate + the binary package." + } + + bool --keep-output + { + "Keep intermediate files in the output root directory (either specified + with \ci{--output-root} or system package manager-specific) that were + used to generate the binary package. This is primarily useful for + troubleshooting." + } + }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bpkg-default-options-files(1)} for an overview of the default + options files. For the \cb{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 \cb{pkg-bindist} command options cannot be specified in the + default options files: + + \ + --directory|-d + \ + " +} |