From 46842f6cf74d085ced382dd0c187f6a7a578913c Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Thu, 22 Mar 2018 10:57:35 +0200 Subject: Update pkg-build documentation --- bpkg/pkg-build.cli | 119 ++++++++++++++++++++++++++++++++++++++++++----------- 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 { { " - + ", "\h|SYNOPSIS| - \c{\b{bpkg pkg-build}|\b{build} [] ( | [\b{@}] | | /)...} + \c{\b{bpkg pkg-build}|\b{build} [] [\b{--upgrade}|\b{-u} | \b{--patch}|\b{-p}] ...\n + \b{bpkg pkg-build}|\b{build} [] \ \b{--upgrade}|\b{-u} | \b{--patch}|\b{-p}} - \c{ = [\b{:}][\b{/}][\b{,}...\b{@}]\n - \ \ = [\b{?}]\b{sys}} + \c{ = [](([\b{:}][\b{/}])\b{,}...[\b{@}] | \n + \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ [\b{@}] \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ | \n + \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ | \n + \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \b{/})\n + \ \ \ \ = \b{?}\n + \ \ = \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 () with optional package version () in which case the source code for the package @@ -62,16 +82,13 @@ namespace bpkg bpkg build @/path/to/repository/ \ - A package name () can also be prefixed with a package scheme - (:). Currently the only recognized scheme is \cb{sys:} which + A package name () can be prefixed with a package 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 () 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 () or to the package directory (\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 () 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 + () 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 () 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 -- cgit v1.1