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
|
// file : bdep/common.cli
// license : MIT; see accompanying LICENSE file
include <bdep/types.hxx>;
include <bdep/options-types.hxx>;
"\section=1"
"\name=bdep-common-options"
"\summary=details on common options"
namespace bdep
{
{
"<common-options>",
"\h|SYNOPSIS|
\c{\b{bdep} [<common-options>] ...}
\h|DESCRIPTION|
The common options control behavior that is common to all or most of the
\cb{bdep} 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{bdep-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.||"
}
bdep::stdout_format --stdout-format = bdep::stdout_format::lines
{
"<format>",
"Representation format to use for printing to \cb{stdout}. Valid values
for this option are \cb{lines} (default) and \cb{json}. See the JSON
OUTPUT section below for details on the \cb{json} format."
}
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 executing package manager commands such as \l{bpkg-pkg-update(1)},
\l{bpkg-pkg-test(1)}, etc., which in turn propagate it to the build
system."
}
// 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, 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 --progress
{
"Display progress indicators for long-lasting operations, such as
network transfers, building, etc. If printing to a terminal the
progress is displayed by default for low verbosity levels. Use
\cb{--no-progress} to suppress."
}
bool --no-progress
{
"Suppress progress indicators for long-lasting operations, such as
network transfers, building, etc."
}
path --bpkg
{
"<path>",
"The package manager program to be used for build configuration
management. This should be the path to the \cb{bpkg} executable. You
can also specify additional options that should be passed to the
package manager program with \cb{--bpkg-option}.
If the package manager program is not explicitly specified, then
\cb{bdep} will by default use \cb{bpkg} plus an executable suffix if
one was specified when building \cb{bdep}. So, for example, if
\cb{bdep} name was set to \cb{bdep-1.0}, then it will look for
\cb{bpkg-1.0}."
}
strings --bpkg-option
{
"<opt>",
"Additional option to be passed to the package manager program. See
\cb{--bpkg} for more information on the package manager program.
Repeat this option to specify multiple package manager options."
}
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{bdep} will
by default use \cb{b} plus an executable suffix if one was specified
when building \cb{bdep}. So, for example, if \cb{bdep} name was set
to \cb{bdep-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 --curl = "curl"
{
"<path>",
"The curl program to be used for network operations. You can also
specify additional options that should be passed to the curl program
with \cb{--curl-option}.
If the curl program is not explicitly specified, then \cb{bdep} will use
\cb{curl} by default."
}
strings --curl-option
{
"<opt>",
"Additional option to be passed to the curl program. See \cb{--curl} for
more information on the curl program. Repeat this option to specify
multiple curl options."
}
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{bdep} 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."
}
};
{
"",
"
\h|JSON OUTPUT|
Commands that support the JSON output specify their formats as a
serialized representation of a C++ \cb{struct} or an array thereof. For
example:
\
struct package
{
string name;
};
struct configuration
{
uint64_t id;
string path;
optional<string> name;
bool default;
vector<package> packages;
};
\
An example of the serialized JSON representation of \cb{struct}
\cb{configuration}:
\
{
\"id\": 1,
\"path\": \"/tmp/hello-gcc\",
\"name\": \"gcc\",
\"default\": true,
\"packages\": [
{
\"name\": \"hello\"
}
]
}
\
This sections provides details on the overall properties of such formats
and the semantics of the \cb{struct} serialization.
The order of members in a JSON object is fixed as specified in the
corresponding \cb{struct}. While new members may be added in the
future (and should be ignored by older consumers), the semantics of the
existing members (including whether the top-level entry is an object or
array) may not change.
An object member is required unless its type is \cb{optional<>},
\cb{bool}, or \cb{vector<>} (array). For \cb{bool} members absent means
\cb{false}. For \cb{vector<>} members absent means empty. An empty
top-level array is always present.
For example, the following JSON text is a possible serialization of
the above \cb{struct} \cb{configuration}:
\
{
\"id\": 1,
\"path\": \"/tmp/hello-gcc\"
}
\
"
}
}
|