aboutsummaryrefslogtreecommitdiff
path: root/bpkg/common.cli
blob: 4537961b4d28289e9bdc3d03ca56c095dd519f40 (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
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
// file      : bpkg/common.cli
// license   : MIT; see accompanying LICENSE file

include <set>;

include <bpkg/types.hxx>;
include <bpkg/options-types.hxx>;

"\section=1"
"\name=bpkg-common-options"
"\summary=details on common options"

namespace bpkg
{
  {
    "<common-options>",

    "\h|SYNOPSIS|

     \c{\b{bpkg} [<common-options>] ...}

     \h|DESCRIPTION|

     The common options control behavior that is common to all or most of the
     \cb{bpkg} commands. They can be specified either before the command or
     after, together with the command-specific options."
  }

  class common_options = 0
  {
    "\h|COMMON OPTIONS|"

    // Retain this note only in the summary.
    //
    {
      "",
      "The common options are summarized below with a more detailed description
       available in \l{bpkg-common-options(1)}.",
      ""
    }

    bool -v
    {
      "Print essential underlying commands being executed. This is equivalent
       to \cb{--verbose 2}."
    }

    bool -V
    {
      "Print all underlying commands being executed. This is equivalent to
       \cb{--verbose 3}."
    }

    bool --quiet|-q
    {
      "Run quietly, only printing error messages. This is equivalent
       to \cb{--verbose 0}."
    }

    uint16_t --verbose = 1
    {
      "<level>",
      "Set the diagnostics verbosity to <level> between 0 and 6. Level 0
       disables any non-error messages while level 6 produces lots of
       information, with level 1 being the default. The following additional
       types of diagnostics are produced at each level:

       \ol|

       \li|High-level information messages.|

       \li|Essential underlying commands being executed.|

       \li|All underlying commands being executed.|

       \li|Information that could be helpful to the user.|

       \li|Information that could be helpful to the developer.|

       \li|Even more detailed information.||"
    }

    size_t --jobs|-j
    {
      "<num>",
      "Number of jobs to perform in parallel. If this option is not
       specified or specified with the \c{0} value, then the number of
       available hardware threads is used. This option is also propagated
       when performing build system operations such as \cb{update},
       \cb{test}, etc."
    }

    // In the future we may also have --structured-result, similar to the
    // build system.
    //
    bool --no-result
    {
      "Don't print informational messages about the outcome of performing
       a command."
    }

    // When it comes to external programs (such as curl, git, etc), if stderr
    // is not a terminal, the logic is actually tri-state: With --no-progress
    // we suppress any progress. With --progress (which we may add in the
    // future), we request full progress. Finally, without any --*progress
    // options we let the external program decide what to do: it may do
    // something intelligent (like curl) and produce non-terminal-friendly
    // progress (such as status lines printed periodically) or it may disable
    // progress all together (like git). Of course, it may also do no
    // detection and dump non-terminal-unfriendly progress in which case we
    // should probably do the detection ourselves and suppress it.
    //
    bool --no-progress
    {
      "Suppress progress indicators for long-lasting operations, such as
       network transfers, building, etc."
    }

    path --build
    {
      "<path>",
      "The build program to be used to build packages. This should be the path
       to the build2 \cb{b} executable. You can also specify additional options
       that should be passed to the build program with \cb{--build-option}.

       If the build program is not explicitly specified, then \cb{bpkg} will
       by default use \cb{b} plus an executable suffix if one was specified
       when building \cb{bpkg}. So, for example, if \cb{bpkg} name was set
       to \cb{bpkg-1.0}, then it will look for \cb{b-1.0}."
    }

    strings --build-option
    {
      "<opt>",
      "Additional option to be passed to the build program. See \cb{--build}
       for more information on the build program. Repeat this option to specify
       multiple build options."
    }

    path --fetch
    {
      "<path>",
      "The fetch program to be used to download resources. Currently,
       \cb{bpkg} recognizes \cb{curl}, \cb{wget}, and \cb{fetch}. Note that
       the last component of <path> must contain one of these names as a
       substring in order for \cb{bpkg} to recognize which program is being
       used. You can also specify additional options that should be passed
       to the fetch program with \cb{--fetch-option}.

       If the fetch program is not specified, then \cb{bpkg} will try to
       discover if one of the above programs is available and use that.
       Currently, \cb{bpkg} has the following preference order: \cb{wget}
       1.16 or higher (supports \cb{--show-progress}), \cb{curl},
       \cb{wget}, and \cb{fetch}."
    }

    strings --fetch-option
    {
      "<opt>",
      "Additional option to be passed to the fetch program. See \cb{--fetch}
       for more information on the fetch program. Repeat this option to
       specify multiple fetch options."
    }

    size_t --fetch-timeout
    {
      "<sec>",
      "The fetch and fetch-like (for example, \cb{git}) program timeout.
       While the exact semantics of the value depends on the program used,
       at a minimum it specifies in seconds the maximum time that can be
       spent without any network activity.

       Specifically, it is translated to the \cb{--max-time} option for
       \cb{curl} and to the \cb{--timeout} option for \cb{wget} and
       \cb{fetch}. For \cb{git} over HTTP/HTTPS this semantics is achieved
       using the \cb{http.lowSpeedLimit}=\i{1} \cb{http.lowSpeedTime}=\i{sec}
       configuration values (the \cb{git://} and \cb{ssh://} protocols
       currently do not support timeouts).

       See \cb{--fetch} and \cb{--git} for more information on the fetch
       programs."
    }

    butl::url --pkg-proxy
    {
      "<url>",
      "HTTP proxy server to use when fetching package manifests and archives
       from remote \cb{pkg} repositories. If specified, the proxy <url> must
       be in the \c{\b{http://}\i{host}[\b{:}\i{port}]} form. If \ci{port} is
       omitted, 80 is used by default.

       Note that to allow caching, the proxied \cb{https://} URLs are
       converted to \cb{http://} in order to prevent the fetch program from
       tunneling (which is the standard approach for proxying HTTPS). If both
       HTTP and HTTPS repositories are used, it is assumed that the proxy
       server can figure out which URLs need to be converted back to
       \cb{https://} based on the request information (for example, host
       name). For security, this mechanism should only be used with signed
       repositories or when the proxy is located inside a trusted network."
    }

    path --git = "git"
    {
      "<path>",
      "The git program to be used to fetch git repositories. You can also
       specify additional options that should be passed to the git program
       with \cb{--git-option}.

       If the git program is not explicitly specified, then \cb{bpkg} will use
       \cb{git} by default."
    }

    strings --git-option
    {
      "<opt>",
      "Additional common option to be passed to the git program. Note that
       the common options are the ones that precede the \cb{git} command.
       See \cb{--git} for more information on the git program. Repeat this
       option to specify multiple git options."
    }

    path --sha256
    {
      "<path>",
      "The sha256 program to be used to calculate SHA256 sums. Currently,
       \cb{bpkg} recognizes \cb{sha256}, \cb{sha256sum}, and \cb{shasum}.
       Note that the last component of <path> must contain one of these names
       as a substring in order for \cb{bpkg} to recognize which program is
       being used. You can also specify additional options that should be
       passed to the sha256 program with \cb{--sha256-option}.

       If the sha256 program is not specified, then \cb{bpkg} will try to
       discover if one of the above programs is available and use that.
       Currently, \cb{bpkg} has the following preference order: \cb{sha256},
       \cb{sha256sum}, and \cb{shasum}."
    }

    strings --sha256-option
    {
      "<opt>",
      "Additional option to be passed to the sha256 program. See \cb{--sha256}
       for more information on the sha256 program. Repeat this option to
       specify multiple sha256 options."
    }

    path --tar
    {
      "<path>",
      "The tar program to be used to extract package archives. For example,
       \cb{gtar} or \cb{bsdtar}. You can also specify additional options that
       should be passed to the tar program with \cb{--tar-option}. If the tar
       program is not explicitly specified, then \cb{bpkg} will use \cb{tar}
       by default."
    }

    strings --tar-option
    {
      "<opt>",
      "Additional option to be passed to the tar program. See \cb{--tar} for
       more information on the tar program. Repeat this option to specify
       multiple tar options."
    }

    // NOTE: when adding support for a new openssl command, don't forget to
    // update the openssl_commands qualifier list.
    //
    qualified_option<openssl_commands, path> --openssl = "openssl"
    {
      "<path>",
      "The openssl program to be used for crypto operations. You can also
       specify additional options that should be passed to the openssl
       program with \cb{--openssl-option}. If the openssl program is not
       explicitly specified, then \cb{bpkg} will use \cb{openssl} by default.

       The \cb{--openssl*} values can be optionally qualified with the openssl
       command in the \c{\i{command}\b{:}\i{value}} form. This makes the value
       only applicable to the specific command, for example:

       \
       bpkg rep-create                     \
         --openssl rsautl:/path/to/openssl \
         --openssl-option rsautl:-engine   \
         --openssl-option rsautl:pkcs11    \
         ...
       \

       An unqualified value that contains a colon can be specified as
       qualified with an empty command, for example, \cb{--openssl
       :C:\\bin\\openssl}. To see openssl commands executed by \cb{bpkg}, use
       the verbose mode (\cb{-v} option)."
    }

    qualified_option<openssl_commands, strings> --openssl-option
    {
      "<opt>",
      "Additional option to be passed to the openssl program. See
       \cb{--openssl} for more information on the openssl program.
       The values can be optionally qualified with the openssl command,
       as discussed in \cb{--openssl}. Repeat this option to specify
       multiple openssl options."
    }

    bpkg::auth --auth = bpkg::auth::remote
    {
      "<type>",
      "Types of repositories to authenticate. Valid values for this option are
       \cb{none}, \cb{remote}, \cb{all}. By default only remote repositories
       are authenticated. You can request authentication of local repositories
       by passing \cb{all} or disable authentication completely by passing
       \cb{none}."
    }

    std::set<string> --trust
    {
      "<fingerprint>",
      "Trust repository certificate with a SHA256 <fingerprint>. Such a
       certificate is trusted automatically, without prompting the user for
       a confirmation. Repeat this option to trust multiple certificates.

       Note that by default \cb{openssl} prints a SHA1 fingerprint and to
       obtain a SHA256 one you will need to pass the \cb{-sha256} option,
       for example:

       \
       openssl x509 -sha256 -fingerprint -noout -in cert.pem
       \
      "
    }

    // Note that if a command for which one can specify these options also
    // have --yes/--no (for all prompts), then those values should be
    // propagated to these ones.
    //
    bool --trust-yes
    {
      "Assume the answer to all authentication prompts is \cb{yes}."
    }

    bool --trust-no
    {
      "Assume the answer to all authentication prompts is \cb{no}."
    }

    string --pager // String to allow empty value.
    {
      "<path>",
      "The pager program to be used to show long text. Commonly used pager
       programs are \cb{less} and \cb{more}. You can also specify additional
       options that should be passed to the pager program with
       \cb{--pager-option}. If an empty string is specified as the pager
       program, then no pager will be used. If the pager program is not
       explicitly specified, then \cb{bpkg} will try to use \cb{less}. If it
       is not available, then no pager will be used."
    }

    strings --pager-option
    {
      "<opt>",
      "Additional option to be passed to the pager program. See \cb{--pager}
       for more information on the pager program. Repeat this option to
       specify multiple pager options."
    }

    // The following option is "fake" in that it is actually handled by
    // argv_file_scanner. We have it here for documentation.
    //
    string --options-file
    {
      "<file>",
      "Read additional options from <file>. Each option should appear on a
       separate line optionally followed by space or equal sign (\cb{=}) and
       an option value. Empty lines and lines starting with \cb{#} are
       ignored. Option values can be enclosed in double (\cb{\"}) or single
       (\cb{'}) quotes to preserve leading and trailing whitespaces as well as
       to specify empty values. If the value itself contains trailing or
       leading quotes, enclose it with an extra pair of quotes, for example
       \cb{'\"x\"'}. Non-leading and non-trailing quotes are interpreted as
       being part of the option value.

       The semantics of providing options in a file is equivalent to providing
       the same set of options in the same order on the command line at the
       point where the \cb{--options-file} option is specified except that
       the shell escaping and quoting is not required. Repeat this option
       to specify more than one options file."
    }

    dir_path --default-options
    {
      "<dir>",
      "The directory to load additional default options files from."
    }

    bool --no-default-options
    {
      "Don't load default options files."
    }
  };
}