diff options
Diffstat (limited to 'bpkg/pkg-build.cli')
| -rw-r--r-- | bpkg/pkg-build.cli | 278 |
1 files changed, 262 insertions, 16 deletions
diff --git a/bpkg/pkg-build.cli b/bpkg/pkg-build.cli index e5a6118..a365082 100644 --- a/bpkg/pkg-build.cli +++ b/bpkg/pkg-build.cli @@ -1,7 +1,7 @@ // file : bpkg/pkg-build.cli // license : MIT; see accompanying LICENSE file -include <bpkg/configuration.cli>; +include <bpkg/common.cli>; "\section=1" "\name=bpkg-pkg-build" @@ -95,12 +95,20 @@ namespace bpkg A package name (<pkg>) can be prefixed with a package scheme (<scheme>). Currently the only recognized scheme is \cb{sys} which instructs \cb{pkg-build} to configure the package as available from the - system rather than building it from source. If the system package version - (<ver-spec>) is not specified or is '\cb{/*}', then it is considered to - be unknown but satisfying any version constraint. If specified, - <ver-spec> may not be a version constraint. If the version is not - explicitly specified, then at least a stub package must be available from - one of the repositories. + system rather than building it from source. + + The system package version (<ver-spec>) may not be a version constraint + but may be the special '\cb{/*}' value, which indicates that the version + should be considered unknown but satisfying any version constraint. If + unspecified, then \cb{pkg-build} will attempt to query the system package + manager for the installed version unless the system package manager is + unsupported or this functionality is disabled with \cb{--sys-no-query}, + in which case the '\cb{/*}' <ver-spec> is assumed. If the system package + manager is supported, then the automatic installation of an available + package can be requested with the \cb{--sys-install} option. Note that if + the version is not explicitly specified, then at least a stub package + must be available from one of the repositories unless the + \cb{--sys-no-stub} option is specified. Finally, a package can be specified as either the path to the package archive (<file>) or to the package directory (<dir>\cb{/}; note that it @@ -111,10 +119,11 @@ namespace bpkg Additional configuration variables (<cfg-var>), if any, should be specified before packages (<pkg-spec>) and should be separated with \cb{--}. Such variables are effective only when configuring and only for - packages that were explicitly specified on the command line (they can - also be specified to only apply to specific packages using the argument - grouping mechanism discussed below). See \l{bpkg-pkg-configure(1)} for - more information on configuration variables. + packages that were explicitly specified on the command line (unless + global overrides). They can also be specified to only apply to specific + packages using the argument grouping mechanism discussed below. See + \l{bpkg-pkg-configure(1)} for more information on configuration + variables. By default a package that is specified explicitly on the command line is built to \i{hold}: it will not be considered for automatic removal if it @@ -156,6 +165,17 @@ namespace bpkg bpkg build libfoo/2.0.0 # upgrade libfoo 2.0.0 to hold, # also hold version 2.0.0 \ + + A package can be built in one of the linked configurations instead of the + current (or host/build system module, for build-time dependencies) + configuration by specifying one of the \cb{--config-*} options (see + \l{bpkg-cfg-create(1)} for background on linked configurations). For + example: + + \ + bpkg build foo { --config-name=alt-host }+ ?bison + \ + " } @@ -183,18 +203,44 @@ namespace bpkg all the constraints." } + bool --deorphan + { + "Replace orphaned packages with the best matching available package + versions which satisfy all the constraints. + + It may happen that a built package no longer has the corresponding + package available in the repository it came from (for example, as a + result of \l{bpkg-rep-fetch(1)} or \l{bpkg-rep-remove(1)}). Such a + package is called an \i{orphan}. Without the \cb{--deorphan} option, + upgrading, downgrading, or patching an orphan will leave it unchanged + if a more suitable version of the package is not available. If the + \cb{--deorphan} option is specified, then an orphan will be replaced + with a non-orphan. In this case, if \cb{--upgrade}, \cb{--patch}, or + the package version is specified, then the new version is selected + accordingly. Otherwise, the closest version to the orphaned version is + selected using the following preference order: + (1) same version, revision, and iteration, + (2) latest iteration of same version and revision, + (3) later revision of same version, + (4) later patch of same version, + (5) later minor of same version, + (6) latest available version, including earlier + (see \l{bpkg#package-version Package Version} for details)." + } + bool --immediate|-i { - "Also upgrade or patch immediate dependencies." + "Also upgrade, patch, or deorphan immediate dependencies." } bool --recursive|-r { - "Also upgrade or patch all dependencies, recursively." + "Also upgrade, patch, or deorphan all dependencies, recursively." } // Sometimes we may want to upgrade/patch the package itself but to - // patch/upgrade its dependencies. + // patch/upgrade its dependencies. Also we may want to deorphan + // dependencies, potentially upgrading/patching the package itself. // bool --upgrade-immediate { @@ -206,6 +252,11 @@ namespace bpkg "Patch immediate dependencies." } + bool --deorphan-immediate + { + "Deorphan immediate dependencies." + } + bool --upgrade-recursive { "Upgrade all dependencies, recursively." @@ -216,6 +267,11 @@ namespace bpkg "Patch all dependencies, recursively." } + bool --deorphan-recursive + { + "Deorphan all dependencies, recursively." + } + bool --dependency { "Build, upgrade, or downgrade a package as a dependency rather than to @@ -228,6 +284,12 @@ namespace bpkg downgrades. Refer to \l{bpkg-pkg-disfigure(1)} for details." } + bool --disfigure + { + "Disfigure packages between upgrades and downgrades effectively + causing a from-scratch reconfiguration." + } + dir_path --checkout-root { "<dir>", @@ -243,16 +305,41 @@ namespace bpkg are purged. Refer to the \cb{--output-purge} option in \l{bpkg-pkg-checkout(1)} for details." } + + strings --config-name + { + "<name>", + "Name of the linked configuration to build this package(s) in. By + default, the package is built in the current configuration. Repeat + this option to specify multiple configurations." + } + + vector<uint64_t> --config-id + { + "<num>", + "Numeric id of the linked configuration to build this package(s) in. By + default, the package is built in the current configuration. Repeat this + option to specify multiple configurations." + } + + vector<uuid> --config-uuid + { + "<uuid>", + "UUID of the linked configuration to build this package(s) in. By + default, the package is built in the current configuration. Repeat this + this option to specify multiple configurations." + } }; - class pkg_build_options: configuration_options, + class pkg_build_options: common_options, pkg_build_pkg_options { "\h|PKG-BUILD GLOBAL OPTIONS|" bool --yes|-y { - "Assume the answer to all prompts is \cb{yes}." + "Assume the answer to all prompts is \cb{yes}. Note that this excludes + the system package manager prompts; see \cb{--sys-yes} for details." } string --for|-f @@ -310,6 +397,165 @@ namespace bpkg specified as part of the build command. Refer to the \cb{--shallow} option in \l{bpkg-rep-fetch(1)} for details." } + + strings --mask-repository + { + "<rep>", + "For the duration of the command execution pretend the specified + repository was removed as if by performing the \cb{rep-remove} + command. The repository can be specified either as a repository name or + as a repository location (URL or a directory path). Note that the + repository's complement and prerequisite repositories are also + considered masked, recursively, unless they are complements and/or + prerequisites of other unmasked repositories. Repeat this option to + mask multiple repositories." + } + + strings --mask-repository-uuid + { + "<v>", + "For the duration of the command execution pretend the specified + repository was removed from the specified configuration. Similar to + \cb{--mask-repository} but only masks the repository in a single + configuration. The option value is a key-value pair in the form: + + \c{\i{config-uuid}\b{=}\i{rep}} + + Repeat this option to mask multiple repositories." + } + + bool --no-refinement + { + "Don't try to refine the configuration by offering to drop any unused + dependencies that were potentially left behind on the previous + \cb{pkg-build} or \cb{pkg-drop} command execution if the command + is otherwise a noop (performs no new package builds, upgrades, etc)." + } + + bool --no-move + { + "Don't move dependency packages between configurations. In this mode the + \cb{--config-*} options specify packages' current rather than new + locations." + } + + uint16_t --noop-exit + { + "<code>", + + "Exit with the specified error code if the command execution is a noop + (performs no new package builds, upgrades, etc)." + } + + string --rebuild-checksum + { + "<sum>", + + "Hash the names, versions, and configurations of all the packages that + would be built. If the resulting checksum matches the specified, then + exit without building anything (potentially with a special error code + specified with the \cb{--noop-exit} option). Otherwise, proceed to + build as normal. In both cases, print the resulting checksum to + \cb{stdout}." + } + + uint16_t --no-private-config + { + "<code>", + + "If no configuration of a suitable type is linked to build a + build-time dependency, instead of automatically creating a private + configuration of this type, exit with the specified error code + printing to \cb{stdout} the dependency chain starting from the + build-time dependency (together with its constraint, if present) + and ending with the top-level dependent (together with their + configuration directories), one entry per line. For example: + + \ + yacc ^1.0.0 + libbar/1.0.0 /path/to/libbar/cfg/ + libfoo/1.0.0 /path/to/libfoo/cfg/ + \ + + See \l{bpkg-cfg-create(1)} for details on linked configurations." + } + + bool --sys-no-query + { + "Do not query the system package manager for the installed versions of + packages specified with the \cb{sys} scheme." + } + + bool --sys-install + { + "Instruct the system package manager to install available versions of + packages specified with the \cb{sys} scheme that are not already + installed. See also the \cb{--sys-no-fetch}, \cb{--sys-yes}, and + \cb{--sys-sudo} options." + } + + bool --sys-no-fetch + { + "Do not fetch the system package manager metadata before querying for + available versions of packages specified with the \cb{sys} scheme. + This option only makes sense together with \cb{--sys-install}." + } + + bool --sys-no-stub + { + "Do no require a stub for packages specified with the \cb{sys} scheme. + Note that this option has effect only if the system package manager + interactions are supported and not disabled." + } + + bool --sys-yes + { + "Assume the answer to the system package manager prompts is \cb{yes}. + Note that system package manager interactions may break your system + and you should normally only use this option on throw-away setups + (test virtual machines, etc)." + } + + string --sys-sudo = "sudo" + { + "<prog>", + + "The \cb{sudo} program to use for system package manager interactions + that normally require administrative privileges (fetch package + metadata, install packages, etc). If unspecified, \cb{sudo} is used + by default. Pass empty or the special \cb{false} value to disable the + use of the \cb{sudo} program. Note that the \cb{sudo} program is + normally only needed if the system package installation is enabled + with the \cb{--sys-install} option." + } + + string --sys-distribution + { + "<name>", + "Alternative system/distribution package manager to interact with. 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 --sys-architecture + { + "<name>", + "Alternative architecture to use when interacting with the system + package manager. The valid <name> values are system/distribution + package manager-specific. If unspecified, the host architecture + is used." + } + + dir_paths --directory|-d + { + "<dir>", + "Assume current configuration is in <dir> rather than in the current + working directory. Repeat this option to specify multiple current + configurations. If multiple configurations are specified, they need not + belong to the same linked configuration cluster." + } }; " |