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 --progress
64 Display progress indicators for long-lasting operations, such as
65 network transfers, building, etc. If printing to a terminal the
66 progress is displayed by default for low verbosity levels. Use
67 --no-progress to suppress.
68 --no-progress
70 Suppress progress indicators for long-lasting operations, such
71 as network transfers, building, etc.
72 --build path
74 The build program to be used to build packages. This should be
75 the path to the build2 b executable. You can also specify addi‐
76 tional options that should be passed to the build program with
77 --build-option.
78 If the build program is not explicitly specified, then bpkg will
80 by default use b plus an executable suffix if one was specified
81 when building bpkg. So, for example, if bpkg name was set to
82 bpkg-1.0, then it will look for b-1.0.
83 --build-option opt
85 Additional option to be passed to the build program. See --build
86 for more information on the build program. Repeat this option to
87 specify multiple build options.
88 --fetch path
90 The fetch program to be used to download resources. Currently,
91 bpkg recognizes curl, wget, and fetch. Note that the last compo‐
92 nent of path must contain one of these names as a substring in
93 order for bpkg to recognize which program is being used. You can
94 also specify additional options that should be passed to the
95 fetch program with --fetch-option.
96 If the fetch program is not specified, then bpkg will try to
98 discover if one of the above programs is available and use that.
99 Currently, bpkg has the following preference order: wget 1.16 or
100 higher (supports --show-progress), curl, wget, and fetch.
101 --fetch-option opt
103 Additional option to be passed to the fetch program. See --fetch
104 for more information on the fetch program. Repeat this option to
105 specify multiple fetch options.
106 --fetch-timeout sec
108 The fetch and fetch-like (for example, git) program timeout.
109 While the exact semantics of the value depends on the program
110 used, at a minimum it specifies in seconds the maximum time that
111 can be spent without any network activity.
112 Specifically, it is translated to the --max-time option for curl
114 and to the --timeout option for wget and fetch. For git over
115 HTTP/HTTPS this semantics is achieved using the
116 http.lowSpeedLimit=1 http.lowSpeedTime=sec configuration values
117 (the git:// and ssh:// protocols currently do not support time‐
118 outs).
119 See --fetch and --git for more information on the fetch pro‐
121 grams.
122 --pkg-proxy url
124 HTTP proxy server to use when fetching package manifests and ar‐
125 chives from remote pkg repositories. If specified, the proxy url
126 must be in the http://host[:port] form. If port is omitted, 80
127 is used by default.
128 Note that to allow caching, the proxied https:// URLs are con‐
130 verted to http:// in order to prevent the fetch program from
131 tunneling (which is the standard approach for proxying HTTPS).
132 If both HTTP and HTTPS repositories are used, it is assumed that
133 the proxy server can figure out which URLs need to be converted
134 back to https:// based on the request information (for example,
135 host name). For security, this mechanism should only be used
136 with signed repositories or when the proxy is located inside a
137 trusted network.
138 --git path
140 The git program to be used to fetch git repositories. You can
141 also specify additional options that should be passed to the git
142 program with --git-option.
143 If the git program is not explicitly specified, then bpkg will
145 use git by default.
146 --git-option opt
148 Additional common option to be passed to the git program. Note
149 that the common options are the ones that precede the git com‐
150 mand. See --git for more information on the git program. Repeat
151 this option to specify multiple git options.
152 --sha256 path
154 The sha256 program to be used to calculate SHA256 sums. Cur‐
155 rently, bpkg recognizes sha256, sha256sum, and shasum. Note that
156 the last component of path must contain one of these names as a
157 substring in order for bpkg to recognize which program is being
158 used. You can also specify additional options that should be
159 passed to the sha256 program with --sha256-option.
160 If the sha256 program is not specified, then bpkg will try to
162 discover if one of the above programs is available and use that.
163 Currently, bpkg has the following preference order: sha256,
164 sha256sum, and shasum.
165 --sha256-option opt
167 Additional option to be passed to the sha256 program. See
168 --sha256 for more information on the sha256 program. Repeat this
169 option to specify multiple sha256 options.
170 --tar path
172 The tar program to be used to extract package archives. For ex‐
173 ample, gtar or bsdtar. You can also specify additional options
174 that should be passed to the tar program with --tar-option. If
175 the tar program is not explicitly specified, then bpkg will use
176 tar by default.
177 --tar-option opt
179 Additional option to be passed to the tar program. See --tar for
180 more information on the tar program. Repeat this option to spec‐
181 ify multiple tar options.
182 --openssl path
184 The openssl program to be used for crypto operations. You can
185 also specify additional options that should be passed to the
186 openssl program with --openssl-option. If the openssl program is
187 not explicitly specified, then bpkg will use openssl by default.
188 The --openssl* values can be optionally qualified with the
190 openssl command in the command:value form. This makes the value
191 only applicable to the specific command, for example:
192 bpkg rep-create \
194 --openssl pkeyutl:/path/to/openssl \
195 --openssl-option pkeyutl:-engine \
196 --openssl-option pkeyutl:pkcs11 \
197 ...
198 Note that for openssl versions prior to 3.0.0 bpkg uses the
200 rsautl command instead of pkeyutl for the data signing and re‐
201 covery operations.
202 An unqualified value that contains a colon can be specified as
204 qualified with an empty command, for example, --openssl
205 :C:\bin\openssl. To see openssl commands executed by bpkg, use
206 the verbose mode (-v option).
207 --openssl-option opt
209 Additional option to be passed to the openssl program. See
210 --openssl for more information on the openssl program. The val‐
211 ues can be optionally qualified with the openssl command, as
212 discussed in --openssl. Repeat this option to specify multiple
213 openssl options.
214 --auth type
216 Types of repositories to authenticate. Valid values for this op‐
217 tion are none, remote, all. By default only remote repositories
218 are authenticated. You can request authentication of local
219 repositories by passing all or disable authentication completely
220 by passing none.
221 --trust fingerprint
223 Trust repository certificate with a SHA256 fingerprint. Such a
224 certificate is trusted automatically, without prompting the user
225 for a confirmation. Repeat this option to trust multiple cer‐
226 tificates.
227 Note that by default openssl prints a SHA1 fingerprint and to
229 obtain a SHA256 one you will need to pass the -sha256 option,
230 for example:
231 openssl x509 -sha256 -fingerprint -noout -in cert.pem
233 --trust-yes
235 Assume the answer to all authentication prompts is yes.
236 --trust-no
238 Assume the answer to all authentication prompts is no.
239 --pager path
241 The pager program to be used to show long text. Commonly used
242 pager programs are less and more. You can also specify addi‐
243 tional options that should be passed to the pager program with
244 --pager-option. If an empty string is specified as the pager
245 program, then no pager will be used. If the pager program is not
246 explicitly specified, then bpkg will try to use less. If it is
247 not available, then no pager will be used.
248 --pager-option opt
250 Additional option to be passed to the pager program. See --pager
251 for more information on the pager program. Repeat this option to
252 specify multiple pager options.
253 --options-file file
255 Read additional options from file. Each option should appear on
256 a separate line optionally followed by space or equal sign (=)
257 and an option value. Empty lines and lines starting with # are
258 ignored. Option values can be enclosed in double (") or single
259 (') quotes to preserve leading and trailing whitespaces as well
260 as to specify empty values. If the value itself contains trail‐
261 ing or leading quotes, enclose it with an extra pair of quotes,
262 for example '"x"'. Non-leading and non-trailing quotes are in‐
263 terpreted as being part of the option value.
264 The semantics of providing options in a file is equivalent to
266 providing the same set of options in the same order on the com‐
267 mand line at the point where the --options-file option is speci‐
268 fied except that the shell escaping and quoting is not required.
269 Repeat this option to specify more than one options file.
270 --default-options dir
272 The directory to load additional default options files from.
273 --no-default-options
275 Don't load default options files.
276 --keep-tmp
278 Don't remove the bpkg's temporary directory at the end of the
279 command execution and print its path at the verbosity level 2 or
280 higher. This option is primarily useful for troubleshooting.
281
283 Commands that support the JSON output specify their formats as a seri‐
284 alized representation of a C++ struct or an array thereof. For example:
285 struct package
287 {
288 string name;
289 };
290 struct configuration
292 {
293 uint64_t id;
294 string path;
295 optional<string> name;
296 bool default;
297 vector<package> packages;
298 };
299 An example of the serialized JSON representation of struct configura‐
301 tion:
302 {
304 "id": 1,
305 "path": "/tmp/hello-gcc",
306 "name": "gcc",
307 "default": true,
308 "packages": [
309 {
310 "name": "hello"
311 }
312 ]
313 }
314 This sections provides details on the overall properties of such for‐
316 mats and the semantics of the struct serialization.
317 The order of members in a JSON object is fixed as specified in the cor‐
319 responding struct. While new members may be added in the future (and
320 should be ignored by older consumers), the semantics of the existing
321 members (including whether the top-level entry is an object or array)
322 may not change.
323 An object member is required unless its type is optional<>, bool, or
325 vector<> (array). For bool members absent means false. For vector<>
326 members absent means empty. An empty top-level array is always present.
327 For example, the following JSON text is a possible serialization of the
329 above struct configuration:
330 {
332 "id": 1,
333 "path": "/tmp/hello-gcc"
334 }
335
337 Send bug reports to the users@build2.org mailing list.
338
340 Copyright (c) 2014-2022 the build2 authors.
341 Permission is granted to copy, distribute and/or modify this document
343 under the terms of the MIT License.
344bpkg 0.15.0 July 2022 bpkg-common-options(1)