diff options
Diffstat (limited to 'bpkg/pkg-status.cli')
| -rw-r--r-- | bpkg/pkg-status.cli | 149 |
1 files changed, 125 insertions, 24 deletions
diff --git a/bpkg/pkg-status.cli b/bpkg/pkg-status.cli index 24e1dc8..084b7a3 100644 --- a/bpkg/pkg-status.cli +++ b/bpkg/pkg-status.cli @@ -25,17 +25,20 @@ namespace bpkg or, if <ver> is specified, package versions. If no packages were specified, then \cb{pkg-status} prints the status of all the held packages (which are the packages that were explicitly built; see - \l{bpkg-pkg-build(1)}). Additionally, the status of immediate or all - dependencies of the above packages can be printed by specifying the - \c{\b{--immediate}|\b{-i}} or \c{\b{--recursive}|\b{-r}} options, - respectively. Note that the status is written to \cb{stdout}, not - \cb{stderr}. - - The status output format is regular with components separated with - spaces. Each line starts with the package name (and version, if - specified) followed by one of the status words listed below. Some of + \l{bpkg-pkg-build(1)}). The latter mode can be modified to print the + status of all the packages by specifying the \c{\b{--all}|\b{-a}} option. + Additionally, the status of immediate or all dependencies of the above + packages can be printed by specifying the \c{\b{--immediate}|\b{-i}} or + \c{\b{--recursive}|\b{-r}} options, respectively. Note that the status is + written to \cb{stdout}, not \cb{stderr}. + + The default output format (see the \cb{--stdout-format} common option) is + regular with components separated with spaces. Each line starts with the + package name followed by one of the status words listed below. Some of them can be optionally followed by '\cb{,}' (no spaces) and a sub-status - word. + word. Lines corresponding to dependencies from linked configurations will + additionally mention the configuration directory in square brackets after + the package name. \dl| @@ -81,13 +84,17 @@ namespace bpkg package may or may not be available from the system and that its version is unknown. - Similarly, if only the package name was specified, then the \cb{fetched}, - \cb{unpacked}, \cb{configured}, and \cb{broken} status words are followed - by the version of the package. If newer versions are available, then the - package version is followed by the \cb{available} status word and the - list of newer versions. To instead see a list of all versions, including - the older ones, specify the \c{\b{--old-available}|\b{-o}} option. In - this case the currently selected version is printed in '\cb{()}'. + The \cb{fetched}, \cb{unpacked}, \cb{configured}, and \cb{broken} status + words are followed by the version of the package. If the package version + was specified, then the \cb{unknown} status word is also followed by the + version. + + If the status is \cb{fetched}, \cb{unpacked}, \cb{configured}, or + \cb{broken} and newer versions are available, then the package version is + followed by the \cb{available} status word and the list of newer + versions. To instead see a list of all versions, including the older + ones, specify the \c{\b{--old-available}|\b{-o}} option. In this case the + currently selected version is printed in '\cb{()}'. If the package name was specified with the version, then only the status (such as, \cb{configured}, \cb{available}, etc.) of this version is @@ -109,22 +116,22 @@ namespace bpkg libbar unknown bpkg status libbar/1.0.0 - libbar/1.0.0 unknown + libbar unknown 1.0.0 bpkg status libfoo/1.0.0 - !libfoo/1.0.0 configured !1.0.0 + !libfoo configured !1.0.0 bpkg status libfoo/1.1.0 - libfoo/1.1.0 available 1.1.0 + libfoo available 1.1.0 bpkg status --system libfoo/1.1.0 - libfoo/1.1.0 available 1.1.0 sys:1.1.0 + libfoo available 1.1.0 sys:1.1.0 bpkg status libfoo !libfoo configured !1.0.0 available 1.1.0 1.1.1 bpkg status libfoo/1.1.1 libbar - libfoo/1.1.1 available 1.1.1 + libfoo available 1.1.1 libbar unknown \ @@ -132,7 +139,7 @@ namespace bpkg \ bpkg status libfoo/1.0.0 - libfoo/1.0.0 unknown + libfoo unknown 1.0.0 bpkg status libfoo libfoo available 1.1.0 1.1.1 @@ -143,9 +150,93 @@ namespace bpkg \ bpkg status libfoo - !libfoo configured,system * available 1.1.0 1.1.1 + !libfoo configured,system !* available 1.1.0 1.1.1 + \ + + Another example of the status output this time including dependencies: + + \ + bpkg status -r libbaz + !libbaz configured 1.0.0 + libfoo configured 1.0.0 + bison [.bpkg/host/] configured 1.0.0 + libbar configured 2.0.0 \ + If the output format is \cb{json}, then the output is a JSON array of + objects which are the serialized representation of the following C++ + \cb{struct} \cb{package_status}: + + \ + struct available_version + { + string version; + bool system; + bool dependency; + }; + + struct package_status + { + string name; + optional<string> configuration; + optional<string> constraint; + string status; + optional<string> sub_status; + optional<string> version; + bool hold_package; + bool hold_version; + vector<available_version> available_versions; + vector<package_status> dependencies; + }; + \ + + For example: + + \ + [ + { + \"name\": \"hello\", + \"status\": \"configured\", + \"version\": \"1.0.0\", + \"hold_package\": true, + \"available_versions\": [ + { + \"version\": \"1.0.1\" + }, + { + \"version\": \"2.0.0\" + } + ], + \"dependencies\": [ + { + \"name\": \"libhello\", + \"status\": \"configured\", + \"version\": \"1.0.2\", + } + ] + } + ] + \ + + See the JSON OUTPUT section in \l{bpkg-common-options(1)} for details on + the overall properties of this format and the semantics of the + \cb{struct} serialization. + + In \cb{package_status}, the \cb{configuration} member contains the + absolute directory of a linked configuration if this package resides in a + linked configuration. The \cb{constraint} member is present only if the + \cb{--constraint} option is specified. The \cb{version} member is absent + if the \cb{status} member is \cb{unknown} or \cb{available} and no + package version is specified on the command line. If the \cb{sub_status} + member is \cb{system}, then the \cb{version} member can be special + \cb{*}. The \cb{dependencies} member is present only if the + \cb{--immediate|-i} or \cb{--recursive|-r} options are specified. + + In \cb{available_version}, if the \cb{system} member is \cb{true}, then + this version is available from the system, in which case the \cb{version} + member can be special \cb{?} or \cb{*}. If the \cb{dependency} member is + \cb{true}, then this version is only available as a dependency from + prerequisite repositories of other repositories. " } @@ -153,6 +244,16 @@ namespace bpkg { "\h|PKG-STATUS OPTIONS|" + bool --all|-a + { + "Print the status of all the packages, not just held." + } + + bool --link + { + "Also print the status of held/all packages from linked configurations." + } + bool --immediate|-i { "Also print the status of immediate dependencies." |