1bpkg-common-options(1) General Commands Manual bpkg-common-options(1)
2
6 bpkg-common-options - details on common options
7
9 bpkg [common-options] ...
10
12 The common options control behavior that is common to all or most of
13 the bpkg commands. They can be specified either before the command or
14 after, together with the command-specific options.
15
17 -v Print essential underlying commands being executed. This is
18 equivalent to --verbose 2.
19 -V Print all underlying commands being executed. This is equivalent
21 to --verbose 3.
22 --quiet|-q
24 Run quietly, only printing error messages. This is equivalent to
25 --verbose 0.
26 --verbose level
28 Set the diagnostics verbosity to level between 0 and 6. Level 0
29 disables any non-error messages while level 6 produces lots of
30 information, with level 1 being the default. The following addi‐
31 tional types of diagnostics are produced at each level:
32 1. High-level information messages.
34 2. Essential underlying commands being executed.
36 3. All underlying commands being executed.
38 4. Information that could be helpful to the user.
40 5. Information that could be helpful to the developer.
42 6. Even more detailed information.
44 --stdout-format format
46 Representation format to use for printing to stdout. Valid val‐
47 ues for this option are lines (default) and json. See the JSON
48 OUTPUT section below for details on the json format.
49 --jobs|-j num
51 Number of jobs to perform in parallel. If this option is not
52 specified or specified with the 0 value, then the number of
53 available hardware threads is used. This option is also propa‐
54 gated when performing build system operations such as update,
55 test, etc.
56 --no-result
58 Don't print informational messages about the outcome of perform‐
59 ing a command or some of its parts. Note that if this option is
60 specified, then for certain long-running command parts progress
61 is displayed instead, unless suppressed with --no-progress.
62 --structured-result fmt
64 Write the result of performing a command in a structured form.
65 In this mode, instead of printing to stderr informational mes‐
66 sages about the outcome of performing a command or some of its
67 parts, bpkg writes to stdout a machine-readable result descrip‐
68 tion in the specified format. Not all commands support produc‐
69 ing structured result and valid fmt values are command-specific.
70 Consult the command documentation for details.
71 --progress
73 Display progress indicators for long-lasting operations, such as
74 network transfers, building, etc. If printing to a terminal the
75 progress is displayed by default for low verbosity levels. Use
76 --no-progress to suppress.
77 --no-progress
79 Suppress progress indicators for long-lasting operations, such
80 as network transfers, building, etc.
81 --diag-color
83 Use color in diagnostics. If printing to a terminal the color is
84 used by default provided the terminal is not dumb. Use --no-
85 diag-color to suppress.
86 --no-diag-color
88 Don't use color in diagnostics.
89 --build path
91 The build program to be used to build packages. This should be
92 the path to the build2 b executable. You can also specify addi‐
93 tional options that should be passed to the build program with
94 --build-option.
95 If the build program is not explicitly specified, then bpkg will
97 by default use b plus an executable suffix if one was specified
98 when building bpkg. So, for example, if bpkg name was set to
99 bpkg-1.0, then it will look for b-1.0.
100 --build-option opt
102 Additional option to be passed to the build program. See --build
103 for more information on the build program. Repeat this option to
104 specify multiple build options.
105 --fetch path
107 The fetch program to be used to download resources. Currently,
108 bpkg recognizes curl, wget, and fetch. Note that the last compo‐
109 nent of path must contain one of these names as a substring in
110 order for bpkg to recognize which program is being used. You can
111 also specify additional options that should be passed to the
112 fetch program with --fetch-option.
113 If the fetch program is not specified, then bpkg will try to
115 discover if one of the above programs is available and use that.
116 Currently, bpkg has the following preference order: curl, wget,
117 and fetch.
118 --fetch-option opt
120 Additional option to be passed to the fetch program. See --fetch
121 for more information on the fetch program. Repeat this option to
122 specify multiple fetch options.
123 --fetch-timeout sec
125 The fetch and fetch-like (for example, git) program timeout.
126 While the exact semantics of the value depends on the program
127 used, at a minimum it specifies in seconds the maximum time that
128 can be spent without any network activity.
129 Specifically, it is translated to the --max-time option for curl
131 and to the --timeout option for wget and fetch. For git over
132 HTTP/HTTPS this semantics is achieved using the
133 http.lowSpeedLimit=1 http.lowSpeedTime=sec configuration values
134 (the git:// and ssh:// protocols currently do not support time‐
135 outs).
136 See --fetch and --git for more information on the fetch pro‐
138 grams.
139 --pkg-proxy url
141 HTTP proxy server to use when fetching package manifests and ar‐
142 chives from remote pkg repositories. If specified, the proxy url
143 must be in the http://host[:port] form. If port is omitted, 80
144 is used by default.
145 Note that to allow caching, the proxied https:// URLs are con‐
147 verted to http:// in order to prevent the fetch program from
148 tunneling (which is the standard approach for proxying HTTPS).
149 If both HTTP and HTTPS repositories are used, it is assumed that
150 the proxy server can figure out which URLs need to be converted
151 back to https:// based on the request information (for example,
152 host name). For security, this mechanism should only be used
153 with signed repositories or when the proxy is located inside a
154 trusted network.
155 --git path
157 The git program to be used to fetch git repositories. You can
158 also specify additional options that should be passed to the git
159 program with --git-option.
160 If the git program is not explicitly specified, then bpkg will
162 use git by default.
163 --git-option opt
165 Additional common option to be passed to the git program. Note
166 that the common options are the ones that precede the git com‐
167 mand. See --git for more information on the git program. Repeat
168 this option to specify multiple git options.
169 --sha256 path
171 The sha256 program to be used to calculate SHA256 sums. Cur‐
172 rently, bpkg recognizes sha256, sha256sum, and shasum. Note that
173 the last component of path must contain one of these names as a
174 substring in order for bpkg to recognize which program is being
175 used. You can also specify additional options that should be
176 passed to the sha256 program with --sha256-option.
177 If the sha256 program is not specified, then bpkg will try to
179 discover if one of the above programs is available and use that.
180 Currently, bpkg has the following preference order: sha256,
181 sha256sum, and shasum.
182 --sha256-option opt
184 Additional option to be passed to the sha256 program. See
185 --sha256 for more information on the sha256 program. Repeat this
186 option to specify multiple sha256 options.
187 --tar path
189 The tar program to be used to extract package archives. For ex‐
190 ample, gtar or bsdtar. You can also specify additional options
191 that should be passed to the tar program with --tar-option. If
192 the tar program is not explicitly specified, then bpkg will use
193 tar by default.
194 --tar-option opt
196 Additional option to be passed to the tar program. See --tar for
197 more information on the tar program. Repeat this option to spec‐
198 ify multiple tar options.
199 --openssl path
201 The openssl program to be used for crypto operations. You can
202 also specify additional options that should be passed to the
203 openssl program with --openssl-option. If the openssl program is
204 not explicitly specified, then bpkg will use openssl by default.
205 The --openssl* values can be optionally qualified with the
207 openssl command in the command:value form. This makes the value
208 only applicable to the specific command, for example:
209 bpkg rep-create \
211 --openssl pkeyutl:/path/to/openssl \
212 --openssl-option pkeyutl:-engine \
213 --openssl-option pkeyutl:pkcs11 \
214 ...
215 Note that for openssl versions prior to 3.0.0 bpkg uses the
217 rsautl command instead of pkeyutl for the data signing and re‐
218 covery operations.
219 An unqualified value that contains a colon can be specified as
221 qualified with an empty command, for example, --openssl
222 :C:\bin\openssl. To see openssl commands executed by bpkg, use
223 the verbose mode (-v option).
224 --openssl-option opt
226 Additional option to be passed to the openssl program. See
227 --openssl for more information on the openssl program. The val‐
228 ues can be optionally qualified with the openssl command, as
229 discussed in --openssl. Repeat this option to specify multiple
230 openssl options.
231 --auth type
233 Types of repositories to authenticate. Valid values for this op‐
234 tion are none, remote, all. By default only remote repositories
235 are authenticated. You can request authentication of local
236 repositories by passing all or disable authentication completely
237 by passing none.
238 --trust fingerprint
240 Trust repository certificate with a SHA256 fingerprint. Such a
241 certificate is trusted automatically, without prompting the user
242 for a confirmation. Repeat this option to trust multiple cer‐
243 tificates.
244 Note that by default openssl prints a SHA1 fingerprint and to
246 obtain a SHA256 one you will need to pass the -sha256 option,
247 for example:
248 openssl x509 -sha256 -fingerprint -noout -in cert.pem
250 --trust-yes
252 Assume the answer to all authentication prompts is yes.
253 --trust-no
255 Assume the answer to all authentication prompts is no.
256 --git-capabilities up=pc
258 Protocol capabilities (pc) for a git repository URL prefix (up).
259 Valid values for the capabilities are dumb (no shallow clone
260 support), smart (support for shallow clone, but not for fetching
261 unadvertised commits), unadv (support for shallow clone and for
262 fetching unadvertised commits). For example:
263 bpkg build https://example.org/foo.git#master \
265 --git-capabilities https://example.org=smart
266 See bpkg-repository-types(1) for details on the git protocol ca‐
268 pabilities.
269 --pager path
271 The pager program to be used to show long text. Commonly used
272 pager programs are less and more. You can also specify addi‐
273 tional options that should be passed to the pager program with
274 --pager-option. If an empty string is specified as the pager
275 program, then no pager will be used. If the pager program is not
276 explicitly specified, then bpkg will try to use less. If it is
277 not available, then no pager will be used.
278 --pager-option opt
280 Additional option to be passed to the pager program. See --pager
281 for more information on the pager program. Repeat this option to
282 specify multiple pager options.
283 --options-file file
285 Read additional options from file. Each option should appear on
286 a separate line optionally followed by space or equal sign (=)
287 and an option value. Empty lines and lines starting with # are
288 ignored. Option values can be enclosed in double (") or single
289 (') quotes to preserve leading and trailing whitespaces as well
290 as to specify empty values. If the value itself contains trail‐
291 ing or leading quotes, enclose it with an extra pair of quotes,
292 for example '"x"'. Non-leading and non-trailing quotes are in‐
293 terpreted as being part of the option value.
294 The semantics of providing options in a file is equivalent to
296 providing the same set of options in the same order on the com‐
297 mand line at the point where the --options-file option is speci‐
298 fied except that the shell escaping and quoting is not required.
299 Repeat this option to specify more than one options file.
300 --default-options dir
302 The directory to load additional default options files from.
303 --no-default-options
305 Don't load default options files.
306 --keep-tmp
308 Don't remove the bpkg's temporary directory at the end of the
309 command execution and print its path at the verbosity level 2 or
310 higher. This option is primarily useful for troubleshooting.
311
313 Commands that support the JSON output specify their formats as a seri‐
314 alized representation of a C++ struct or an array thereof. For example:
315 struct package
317 {
318 string name;
319 };
320 struct configuration
322 {
323 uint64_t id;
324 string path;
325 optional<string> name;
326 bool default;
327 vector<package> packages;
328 };
329 An example of the serialized JSON representation of struct configura‐
331 tion:
332 {
334 "id": 1,
335 "path": "/tmp/hello-gcc",
336 "name": "gcc",
337 "default": true,
338 "packages": [
339 {
340 "name": "hello"
341 }
342 ]
343 }
344 This sections provides details on the overall properties of such for‐
346 mats and the semantics of the struct serialization.
347 The order of members in a JSON object is fixed as specified in the cor‐
349 responding struct. While new members may be added in the future (and
350 should be ignored by older consumers), the semantics of the existing
351 members (including whether the top-level entry is an object or array)
352 may not change.
353 An object member is required unless its type is optional<>, bool, or
355 vector<> (array). For bool members absent means false. For vector<>
356 members absent means empty. An empty top-level array is always present.
357 For example, the following JSON text is a possible serialization of the
359 above struct configuration:
360 {
362 "id": 1,
363 "path": "/tmp/hello-gcc"
364 }
365
367 Send bug reports to the users@build2.org mailing list.
368
370 Copyright (c) 2014-2023 the build2 authors.
371 Permission is granted to copy, distribute and/or modify this document
373 under the terms of the MIT License.
374bpkg 0.16.0 June 2023 bpkg-common-options(1)