diff options
Diffstat (limited to 'bpkg/pkg-build.cli')
| -rw-r--r-- | bpkg/pkg-build.cli | 190 |
1 files changed, 171 insertions, 19 deletions
diff --git a/bpkg/pkg-build.cli b/bpkg/pkg-build.cli index ba9bf47..a365082 100644 --- a/bpkg/pkg-build.cli +++ b/bpkg/pkg-build.cli @@ -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 @@ -194,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 { @@ -217,6 +252,11 @@ namespace bpkg "Patch immediate dependencies." } + bool --deorphan-immediate + { + "Deorphan immediate dependencies." + } + bool --upgrade-recursive { "Upgrade all dependencies, recursively." @@ -227,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 @@ -293,7 +338,8 @@ namespace bpkg 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 @@ -352,6 +398,32 @@ namespace bpkg 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 @@ -360,6 +432,13 @@ namespace bpkg 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>", @@ -368,6 +447,18 @@ namespace bpkg (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>", @@ -389,11 +480,72 @@ namespace bpkg See \l{bpkg-cfg-create(1)} for details on linked configurations." } - bool --no-move + bool --sys-no-query { - "Don't move dependency packages between configurations. In this mode the - \cb{--config-*} options specify packages' current rather than new - locations." + "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 @@ -401,7 +553,7 @@ namespace bpkg "<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 must + configurations. If multiple configurations are specified, they need not belong to the same linked configuration cluster." } }; |