aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2015-11-13 16:08:15 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2015-11-13 16:08:15 +0200
commit0c940ac57cc521b81f7691cd8cec39de6e45f8aa (patch)
treea8ce702f82f635eb637a8f83a842eb2deefb7572
parent4bc4b97397d1e6dc00ea89a8ff7690a072a21f4e (diff)
Update pkg-status command documentation
-rw-r--r--bpkg/pkg-status-options.cli101
-rw-r--r--bpkg/pkg-status.cxx18
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 <bpkg/configuration-options.cli>;
-/*
"\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 <pkg>[/<ver>]"
+{
+"<options> <pkg> <ver>",
+
+"\h|SYNOPSIS|
+
+\c{\b{bpkg pkg-status} [<options>] <pkg>[/<ver>]}
+
+\h|DESCRIPTION|
+
+The \cb{pkg-status} command prints the status of the specified package or, if
+<ver> 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 <ver> 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);