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
|
// file : bpkg/common.cli
// copyright : Copyright (c) 2014-2017 Code Synthesis Ltd
// 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.||"
}
// 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."
}
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}."
}
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://} protocol currently does not
support timeouts).
See \cb{--fetch} and \cb{--git} for more information on the fetch
programs."
}
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."
}
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 = "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."
}
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."
}
strings --openssl-option
{
"<opt>",
"Additional option to be passed to the openssl program. See
\cb{--openssl} for more information on the openssl program. 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 appearing on a
separate line optionally followed by space 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. You can repeat this
option to specify more than one options file."
}
};
}
|