diff options
| -rw-r--r-- | bpkg/pkg-build.cli | 119 | ||||
| -rw-r--r-- | bpkg/pkg-build.cxx | 12 |
2 files changed, 106 insertions, 25 deletions
diff --git a/bpkg/pkg-build.cli b/bpkg/pkg-build.cli index 80abc60..b7a75dc 100644 --- a/bpkg/pkg-build.cli +++ b/bpkg/pkg-build.cli @@ -12,23 +12,43 @@ namespace bpkg { { "<options> - <pkg-spec> <scheme> <pkg> <ver> + <pkg-spec> <flags> <scheme> <pkg> <ver> <file> <dir> <rep-loc>", "\h|SYNOPSIS| - \c{\b{bpkg pkg-build}|\b{build} [<options>] (<pkg-spec> | [\b{@}]<rep-loc> | <file> | <dir>/)...} + \c{\b{bpkg pkg-build}|\b{build} [<options>] [\b{--upgrade}|\b{-u} | \b{--patch}|\b{-p}] <pkg-spec>...\n + \b{bpkg pkg-build}|\b{build} [<options>] \ \b{--upgrade}|\b{-u} | \b{--patch}|\b{-p}} - \c{<pkg-spec> = [<scheme>\b{:}]<pkg>[\b{/}<ver>][\b{,}...\b{@}<rep-loc>]\n - <scheme> \ \ = [\b{?}]\b{sys}} + \c{<pkg-spec> = [<flags>](([<scheme>\b{:}]<pkg>[\b{/}<ver>])\b{,}...[\b{@}<rep-loc>] | \n + \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ [\b{@}]<rep-loc> \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ | \n + \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ <file> \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ | \n + \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ <dir>\b{/})\n + <flags>\ \ \ \ = \b{?}\n + <scheme> \ \ = \b{sys}} \h|DESCRIPTION| - The \cb{pkg-build} command builds one or more packages including all their - prerequisites. Besides building new packages, this command is also used to - upgrade or downgrade packages that already exists in the configuration. + The \cb{pkg-build} command builds one or more packages including all + their prerequisites. Besides building new packages, this command is also + used to upgrade or downgrade packages that are already present in the + configuration. + + The first form (one or more packages are specified) builds new or + upgrades (by default or if \cb{--upgrade} is specified) or patches (if + \cb{--patch} is specified) the specified packages. The second form (no + arguments but either \cb{--upgrade} or \cb{--patch} is specified) + upgrades or patches all the held packages in the configuration (see + below for details on held package). + + In both forms specifying the \c{\b{--immediate}|\b{-i}} or + \c{\b{--recursive}|\b{-r}} option causes \cb{pkg-build} to also upgrade + or patch the immediate or all dependencies of the specified (first form) + or held (second form) packages, respectively. Note also that in the first + form these options can only be specified with an explicit \cb{--upgrade} + or \cb{--patch}. Each package can be specified as just the name (<pkg>) with optional package version (<ver>) in which case the source code for the package @@ -62,16 +82,13 @@ namespace bpkg bpkg build @/path/to/repository/ \ - A package name (<pkg>) can also be prefixed with a package scheme - (<scheme>:). Currently the only recognized scheme is \cb{sys:} which + 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>) is not specified, then it is considered to be unknown but satisfying any dependency constraint. Such a version is displayed as - \cb{*}. In certain cases you may want to indicate that a certain package - is available from the system but only add it to the configuration if it - is required by other packages being built. In this case you can use the - \cb{?sys:} system scheme variant. + '\cb{*}'. 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 @@ -79,24 +96,78 @@ namespace bpkg \l{bpkg-pkg-unpack(1)} commands for more information on the semantics of specifying the package as an archive or a directory. - Packages that are specified explicitly on the command line will be - \i{held}, that is, they will not be considered for automatic removal if - they no longer have any dependents. Packages that are specified with the - explicit package version (<ver>) or as an archive or directory, will, in - addition, have their versions held, that is, they will not be - automatically upgraded. + 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 + no longer has any dependents. Only versions from repositories that were + added to the configuration (\l{bpkg-rep-add(1)}) are considered as + available for build to hold. + + Alternatively, a package can be built (or, more commonly, + upgraded/downgraded) as a \i{dependency} by specifying the \cb{?} flag + (<flags>) or the \cb{--dependency} option. Such a package will only be + added to the configuration if it actually has any dependents and once no + longer used, it will be automatically dropped. Only versions from + prerequisite repositories of dependent packages are considered as + available for build as a dependency. + + Packages (both built to hold and as dependents) that are specified with + an explicit package version (<ver>) or as an archive or directory, + will have their versions held, that is, they will not be automatically + upgraded. + + As an illustration, let's assume in the following example that the stable + repository contains packages \cb{foo} \cb{1.0.0} as well as + \cb{libfoo} \cb{1.0.0} and \cb{1.1.0} while testing \- \cb{libfoo} + \cb{2.0.0}, that testing is complemented by stable, and that \cb{foo} + depends on \cb{libfoo >= 1.0.0}: - The \cb{pkg-build} command also supports several options (described - below) that allow you to control the amount of work that will be done." + \ + bpkg fetch https://example.org/1/testing + + bpkg build foo # build foo 1.0.0 to hold + # build libfoo 1.1.0 as dependency + + bpkg build ?libfoo/1.0.0 # downgrade libfoo 1.0.0 as dependency, + # also hold version 1.0.0 + + bpkg build ?libfoo/2.0.0 # error: 2.0.0 unavailable in dependent's + # (foo) repository (stable) + + bpkg build libfoo/2.0.0 # upgrade libfoo 2.0.0 to hold, + # also hold version 2.0.0 + \ + " } class pkg_build_pkg_options { "\h|PKG-BUILD PACKAGE OPTIONS| - The following options can be grouped to apply to a specific package as - well as specified globally, in which case they apply to all the specified - packages." + The following options can be grouped to apply to a specific \ci{pkg-spec} + as well as specified globally, in which case they apply to all the + specified packages." + + bool --upgrade|-u + { + "Upgrade packages to the latest available version that satisfies all the + constraints." + } + + bool --patch|-p + { + "Upgrade packages to the latest available patch version that satisfies + all the constraints." + } + + bool --immediate|-i + { + "Also upgrade or patch immediate dependencies." + } + + bool --recursive|-r + { + "Also upgrade or patch all dependencies, recursively." + } bool --dependency { diff --git a/bpkg/pkg-build.cxx b/bpkg/pkg-build.cxx index b884fba..4b703b4 100644 --- a/bpkg/pkg-build.cxx +++ b/bpkg/pkg-build.cxx @@ -1186,6 +1186,16 @@ namespace bpkg const dir_path& c (o.directory ()); l4 ([&]{trace << "configuration: " << c;}); + // The --immediate or --recursive option can only be specified with an + // explicit --upgrade or --patch. + // + if (const char* n = (o.immediate () ? "--immediate" : + o.recursive () ? "--recursive" : nullptr)) + { + if (!o.upgrade () && !o.patch ()) + fail << n << " requires explicit --upgrade|-u or --patch|-p"; + } + if (o.drop_prerequisite () && o.keep_prerequisite ()) fail << "both --drop-prerequisite|-D and --keep-prerequisite|-K " << "specified" << @@ -2043,7 +2053,7 @@ namespace bpkg // Almost forgot, there is one more thing: when we upgrade or downgrade a // package, it may change the list of its prerequisites. Which means we // may end up with packages that are no longer necessary and it would be - // nice to offer to drop those. This, howeve, is a tricky business and is + // nice to offer to drop those. This, however, is a tricky business and is // the domain of pkg_drop(). For example, a prerequisite may still have // other dependents (so it looks like we shouldn't be dropping it) but // they are all from the "drop set" (so we should offer to drop it after |