aboutsummaryrefslogtreecommitdiff
path: root/bpkg/pkg-status.cli
blob: 999e3c365e21def42ebefa20a86398eb5f56578c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
// file      : bpkg/pkg-status.cli
// copyright : Copyright (c) 2014-2019 Code Synthesis Ltd
// license   : MIT; see accompanying LICENSE file

include <bpkg/configuration.cli>;

"\section=1"
"\name=bpkg-pkg-status"
"\summary=print package status"

namespace bpkg
{
  {
    "<options> <pkg> <ver>",

    // NOTE: remember to update <dep-spec> in bdep-status if changing the
    //       argument format.
    //
    "\h|SYNOPSIS|

     \c{\b{bpkg pkg-status}|\b{status} [<options>] [<pkg>[\b{/}<ver>]...]}

     \h|DESCRIPTION|

     The \cb{pkg-status} command prints the status of the specified packages
     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
     them can be optionally followed by '\cb{,}' (no spaces) and a sub-status
     word.

     \dl|

     \li|\cb{unknown}

         Package is not part of the configuration nor available from any of the
         repositories.|

     \li|\cb{available}

         Package is not part of the configuration but is available from 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.|

     \li|\cb{configured}

         Package is part of the configuration and is configured. May be
         followed by the \cb{system} sub-status indicating a package coming
         from the system. The version of such a system package (described
         below) may be the special '\cb{*}' value indicating a wildcard
         version.|

     \li|\cb{broken}

         Package is part of the configuration and is broken (broken packages
         can only be purged; see \l{bpkg-pkg-purge(1)}).||

     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. Versions that are only available for up/down-grading are
     printed in '\cb{[]}' (such version are only available as dependencies
     from prerequisite repositories of other repositories). If the
     \cb{--system} option is specified, then the last version in this list may
     have the \cb{sys:} prefix indicating an available system version. Such a
     system version may be the special '\cb{?}' value indicating that a
     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{()}'.

     If the package name was specified with the version, then only the status
     (such as, \cb{configured}, \cb{available}, etc.) of this version is
     considered.

     If a package is being held, then its name is printed prefixed with
     '\cb{!}'. Similarly, if a package version is being held, then the version
     is printed prefixed with '\cb{!}'. Held packages and held versions were
     selected by the user and are not automatically dropped and upgraded,
     respectively.

     Below are some examples, assuming the configuration has \cb{libfoo}
     \cb{1.0.0} configured and held (both package and version) as well as
     \cb{libfoo} \cb{1.1.0} and \cb{1.1.1} available from source and
     \cb{1.1.0} from the system.

     \
     bpkg status libbar
     libbar unknown

     bpkg status libbar/1.0.0
     libbar/1.0.0 unknown

     bpkg status libfoo/1.0.0
     !libfoo/1.0.0 configured !1.0.0

     bpkg status libfoo/1.1.0
     libfoo/1.1.0 available 1.1.0

     bpkg status --system libfoo/1.1.0
     libfoo/1.1.0 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
     libbar unknown
     \

     Assuming now that we dropped \cb{libfoo} from the configuration:

     \
     bpkg status libfoo/1.0.0
     libfoo/1.0.0 unknown

     bpkg status libfoo
     libfoo available 1.1.0 1.1.1
     \

     And assuming now that we built \cb{libfoo} as a system package with
     the wildcard version:

     \
     bpkg status libfoo
     !libfoo configured,system * available 1.1.0 1.1.1
     \

     "
  }

  class pkg_status_options: configuration_options
  {
    "\h|PKG-STATUS OPTIONS|"

    bool --immediate|-i
    {
      "Also print the status of immediate dependencies."
    }

    bool --recursive|-r
    {
      "Also print the status of all dependencies, recursively."
    }

    bool --old-available|-o
    {
      "Print old available versions."
    }

    bool --constraint
    {
      "Print version constraints for dependencies."
    }

    bool --system
    {
      "Check the availability of packages from the system."
    }

    bool --no-hold
    {
      "Don't print the package or version hold status."
    }

    bool --no-hold-package
    {
      "Don't print the package hold status."
    }

    bool --no-hold-version
    {
      "Don't print the version hold status."
    }
  };
}