From 0c940ac57cc521b81f7691cd8cec39de6e45f8aa Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Fri, 13 Nov 2015 16:08:15 +0200 Subject: Update pkg-status command documentation --- bpkg/pkg-status-options.cli | 101 ++++++++++++++++++++++++++++++++++++++++---- bpkg/pkg-status.cxx | 18 ++++---- 2 files changed, 101 insertions(+), 18 deletions(-) diff --git a/bpkg/pkg-status-options.cli b/bpkg/pkg-status-options.cli index 6eabf4d..dbc040a 100644 --- a/bpkg/pkg-status-options.cli +++ b/bpkg/pkg-status-options.cli @@ -4,21 +4,104 @@ include ; -/* "\section=1" "\name=bpkg-pkg-status" +"\summary=print package status" -"\h{SYNOPSIS} +"\project=bpkg" //@@ command line +"\version=0.1.0" //@@ command line +"\date=12 November 2015" //@@ command line; release date -bpkg pkg-status [/]" +{ +" ", + +"\h|SYNOPSIS| + +\c{\b{bpkg pkg-status} [] [/]} + +\h|DESCRIPTION| + +The \cb{pkg-status} command prints the status of the specified package or, if + is specified, package version. Note that the status is written to +\cb{STDOUT}, not \cb{STDERR}. + +The status format is regular. First always comes one of the following status +words: + +\dl| + +\li|\cb{unknown} + + package is not part of the configuration nor available in one of the + repositories| + +\li|\cb{available} + + package is not part of the configuration but is available in one of the + repositories| + +\li|\cb{fetched} + + package is part of the configuration and is fetched| + +\li|\cb{unpacked} + + package is part of the configuration and is unpacked| -"\h{DESCRIPTION} +\li|\cb{configured} -The \cb{pkg-status} command prints the status of the specified -package or, if is specified, package version. Note that the -status is written to \cb{STDOUT}, not \cb{STDERR}. -@@ TODO: output form and possible status values." -*/ + package is part of the configuration and is configured|| + + +If only the package name was specified without the package version, then the +\cb{available} status word is followed by the list of available versions. + +Similarly, if only the package name was specified, then the \cb{fetched}, +\cb{unpacked}, and \cb{configured} status words are followed by the version +of the package. After the possible package version, these status words may +be followed by one or more sub-status words. Currently, these can be +\cb{hold_package} (package should not be automatically dropped) and +\cb{hold_version} (package should not be automatically upgraded). Finally, +if only the package name was specified and newer versions are available +in the repositories, then the sub-status words are followed by '\cb{;}', +the \cb{available} status word, and the list of newer versions. + +Below are some examples, assuming the configuration has libfoo 1.0.0 +configured and held as well as libfoo 1.1.0 and 1.1.1 available from a +repository. + +\ +bpkg pkg-status libbar +unknown + +bpkg pkg-status libbar/1.0.0 +unknown + +bpkg pkg-status libfoo/1.0.0 +configured hold_package + +bpkg pkg-status libfoo/1.1.0 +available + +bpkg pkg-status libfoo +configured 1.0.0 hold_package; available 1.1.0 1.1.1 +\ + +Assuming now that we dropped libfoo from the configuration: + +\ +bpkg pkg-status libfoo/1.0.0 +unknown + +bpkg pkg-status libfoo/1.1.0 +available + +bpkg pkg-status libfoo +available 1.1.0 1.1.1 +\ + +\h|OPTIONS|" +} namespace bpkg { diff --git a/bpkg/pkg-status.cxx b/bpkg/pkg-status.cxx index c31e834..f83b610 100644 --- a/bpkg/pkg-status.cxx +++ b/bpkg/pkg-status.cxx @@ -66,17 +66,17 @@ namespace bpkg query q (query::id.name == n); - // If we found an existing package, then only look for versions - // greater than what already exists. + // If the user specified the version, then only look for that + // specific version. // - if (p != nullptr) - q = q && query::id.version > p->version; - else if (!v.empty ()) - // - // Otherwise, if the user specified the version, then only look for - // that specific version. - // + if (!v.empty ()) q = q && query::id.version == v; + // + // Otherwise, if we found an existing package, then only look for + // versions greater than what already exists. + // + else if (p != nullptr) + q = q && query::id.version > p->version; q += order_by_version_desc (query::id.version); -- cgit v1.1