1bpkg-pkg-build(1) General Commands Manual bpkg-pkg-build(1)
2
3
4
6 bpkg-pkg-build - build package
7
9 bpkg pkg-build|build [options] [--upgrade|-u | --patch|-p]
10 [cfg-var... --] pkg-spec...
11 bpkg pkg-build|build [options] --upgrade|-u | --patch|-p
12 [cfg-var... --]
13
14 pkg-spec = [flags](([scheme:]pkg[ver-spec]),...[@rep-loc] |
15 [@]rep-loc |
16 file |
17 dir/)
18 flags = ?
19 scheme = sys
20 ver-spec = /version | version-constraint
21
23 The pkg-build command builds one or more packages including all their
24 dependencies. Besides building new packages, this command is also used
25 to upgrade or downgrade packages that are already present in the con‐
26 figuration. And unless the --keep-unused|-K option is specified, pkg-
27 build will also drop dependency packages that would otherwise no longer
28 be used.
29
30 The first form (one or more packages are specified) builds new or up‐
31 grades (by default or if --upgrade is specified) or patches (if --patch
32 is specified) the specified packages. The second form (no arguments but
33 either --upgrade or --patch is specified) upgrades or patches all the
34 held packages in the configuration (see below for details on held pack‐
35 age).
36
37 In both forms specifying the --immediate|-i or --recursive|-r option
38 causes pkg-build to also upgrade or patch the immediate or all depen‐
39 dencies of the specified (first form) or held (second form) packages,
40 respectively. Note also that in the first form these options can only
41 be specified with an explicit --upgrade or --patch.
42
43 Each package can be specified as just the name (pkg) with optional ver‐
44 sion specification (ver-spec), in which case the source code for the
45 package will be automatically fetched from one of the configured repos‐
46 itories. See the bpkg-rep-add(1) and bpkg-rep-fetch(1) commands for
47 more information on package repositories. The version specification
48 (ver-spec) can be either the exact version in the /version form or the
49 version constraint as described in Package Version Constraint (#pack‐
50 age-version-constraint). If ver-spec is not specified, then the latest
51 available version will be built. To downgrade, the desired version must
52 be specified explicitly. For example:
53
54 bpkg build foo libfoo/1.2.3 "bar < 2.0.0"
55
56 Alternatively, the package repository location (rep-loc) can be speci‐
57 fied as part of the build command. In this case, if ver-spec is not
58 specified, then the latest available from this repository version will
59 be built. For example:
60
61 bpkg build foo,libfoo/1.2.3@https://git.example.org/foo.git#master
62
63 If only the location is specified, then the latest versions of all the
64 packages available directly from this repository will be built (note
65 that this does not include packages available from complement reposito‐
66 ries). The @ delimiter can be omitted if the location is a URL. For ex‐
67 ample:
68
69 bpkg build https://git.example.org/foo.git#master
70 bpkg build @/path/to/repository/
71
72 A package name (pkg) can be prefixed with a package scheme (scheme).
73 Currently the only recognized scheme is sys which instructs pkg-build
74 to configure the package as available from the system rather than
75 building it from source. If the system package version (ver-spec) is
76 not specified or is '/*', then it is considered to be unknown but sat‐
77 isfying any version constraint. If specified, ver-spec may not be a
78 version constraint. If the version is not explicitly specified, then at
79 least a stub package must be available from one of the repositories.
80
81 Finally, a package can be specified as either the path to the package
82 archive (file) or to the package directory (dir/; note that it must end
83 with a directory separator). See the bpkg-pkg-fetch(1) and bpkg-pkg-un‐
84 pack(1) commands for more information on the semantics of specifying
85 the package as an archive or a directory.
86
87 Additional configuration variables (cfg-var), if any, should be speci‐
88 fied before packages (pkg-spec) and should be separated with --. Such
89 variables are effective only when configuring and only for packages
90 that were explicitly specified on the command line (they can also be
91 specified to only apply to specific packages using the argument group‐
92 ing mechanism discussed below). See bpkg-pkg-configure(1) for more in‐
93 formation on configuration variables.
94
95 By default a package that is specified explicitly on the command line
96 is built to hold: it will not be considered for automatic removal if it
97 no longer has any dependents. Only versions from repositories that were
98 added to the configuration (bpkg-rep-add(1)) are considered as avail‐
99 able for build to hold.
100
101 Alternatively, a package can be built (or, more commonly, up‐
102 graded/downgraded) as a dependency by specifying the ? flag (flags) or
103 the --dependency option. Such a package will only be added to the con‐
104 figuration if it actually has any dependents and once no longer used,
105 it will be automatically dropped. Only versions from prerequisite
106 repositories of dependent packages are considered as available for
107 build as a dependency.
108
109 Packages (both built to hold and as dependencies) that are specified
110 with an explicit package version (ver-spec) or as an archive or direc‐
111 tory, will have their versions held, that is, they will not be automat‐
112 ically upgraded.
113
114 As an illustration, let's assume in the following example that the sta‐
115 ble repository contains packages foo 1.0.0 as well as libfoo 1.0.0 and
116 1.1.0 while testing – libfoo 2.0.0, that testing is complemented by
117 stable, and that foo depends on libfoo >= 1.0.0:
118
119 bpkg fetch https://example.org/1/testing
120
121 bpkg build foo # build foo 1.0.0 to hold
122 # build libfoo 1.1.0 as dependency
123
124 bpkg build ?libfoo/1.0.0 # downgrade libfoo 1.0.0 as dependency,
125 # also hold version 1.0.0
126
127 bpkg build ?libfoo/2.0.0 # error: 2.0.0 unavailable in dependent's
128 # (foo) repository (stable)
129
130 bpkg build libfoo/2.0.0 # upgrade libfoo 2.0.0 to hold,
131 # also hold version 2.0.0
132
133 A package can be built in one of the linked configurations instead of
134 the current (or host/build system module, for build-time dependencies)
135 configuration by specifying one of the --config-* options (see bpkg-
136 cfg-create(1) for background on linked configurations). For example:
137
138 bpkg build foo { --config-name=alt-host }+ ?bison
139
141 The following options (as well as additional configuration variables)
142 can be grouped to apply to a specific pkg-spec as well as specified
143 globally, in which case they apply to all the specified packages (see
144 bpkg-argument-grouping(1) for details).
145
146 --upgrade|-u
147 Upgrade packages to the latest available version that satisfies
148 all the constraints.
149
150 --patch|-p
151 Upgrade packages to the latest available patch version that sat‐
152 isfies all the constraints.
153
154 --immediate|-i
155 Also upgrade or patch immediate dependencies.
156
157 --recursive|-r
158 Also upgrade or patch all dependencies, recursively.
159
160 --upgrade-immediate
161 Upgrade immediate dependencies.
162
163 --patch-immediate
164 Patch immediate dependencies.
165
166 --upgrade-recursive
167 Upgrade all dependencies, recursively.
168
169 --patch-recursive
170 Patch all dependencies, recursively.
171
172 --dependency
173 Build, upgrade, or downgrade a package as a dependency rather
174 than to hold.
175
176 --keep-out
177 Keep output directories of external packages between upgrades
178 and downgrades. Refer to bpkg-pkg-disfigure(1) for details.
179
180 --disfigure
181 Disfigure packages between upgrades and downgrades effectively
182 causing a from-scratch reconfiguration.
183
184 --checkout-root dir
185 Check out packages that come from version control-based reposi‐
186 tories into the specified directory rather than into the config‐
187 uration directory. Refer to the --output-root option in bpkg-
188 pkg-checkout(1) for details.
189
190 --checkout-purge
191 Remove the checked out package (source) directories when the
192 packages are purged. Refer to the --output-purge option in bpkg-
193 pkg-checkout(1) for details.
194
195 --config-name name
196 Name of the linked configuration to build this package(s) in. By
197 default, the package is built in the current configuration. Re‐
198 peat this option to specify multiple configurations.
199
200 --config-id num
201 Numeric id of the linked configuration to build this package(s)
202 in. By default, the package is built in the current configura‐
203 tion. Repeat this option to specify multiple configurations.
204
205 --config-uuid uuid
206 UUID of the linked configuration to build this package(s) in. By
207 default, the package is built in the current configuration. Re‐
208 peat this this option to specify multiple configurations.
209
211 --yes|-y
212 Assume the answer to all prompts is yes.
213
214 --for|-f operation
215 Instead of the default update build system operation, perform
216 the update-for-operation variant where operation is normally in‐
217 stall or test.
218
219 --keep-unused|-K
220 Don't drop dependency packages that were automatically built but
221 will no longer be used.
222
223 --update-dependent|-U
224 Update without confirmation dependent packages that are recon‐
225 figured due to their dependencies being upgraded or downgraded.
226
227 --leave-dependent|-L
228 Don't offer to update dependent packages that are reconfigured
229 due to their dependencies being upgraded or downgraded.
230
231 --configure-only|-c
232 Configure all the packages but don't update.
233
234 --print-only
235 Print to stdout what would be done without actually doing any‐
236 thing.
237
238 --plan header
239 Print the plan (even if --yes is specified) and start it with
240 the header line (unless it is empty).
241
242 --no-fetch
243 Don't fetch repositories specified as part of the build command.
244
245 --fetch-shallow
246 Don't re-fetch complement and prerequisite repositories of
247 repositories specified as part of the build command. Refer to
248 the --shallow option in bpkg-rep-fetch(1) for details.
249
250 --no-refinement
251 Don't try to refine the configuration by offering to drop any
252 unused dependencies that were potentially left behind on the
253 previous pkg-build or pkg-drop command execution if the command
254 is otherwise a noop (performs no new package builds, upgrades,
255 etc).
256
257 --no-move
258 Don't move dependency packages between configurations. In this
259 mode the --config-* options specify packages' current rather
260 than new locations.
261
262 --noop-exit code
263 Exit with the specified error code if the command execution is a
264 noop (performs no new package builds, upgrades, etc).
265
266 --rebuild-checksum sum
267 Hash the names and versions of all the packages that would be
268 built. If the resulting checksum matches the specified, then
269 exit without building anything (potentially with a special error
270 code specified with the --noop-exit option). Otherwise, proceed
271 to build as normal. In both cases, print the resulting checksum
272 to stdout.
273
274 --no-private-config code
275 If no configuration of a suitable type is linked to build a
276 build-time dependency, instead of automatically creating a pri‐
277 vate configuration of this type, exit with the specified error
278 code printing to stdout the dependency chain starting from the
279 build-time dependency (together with its constraint, if present)
280 and ending with the top-level dependent (together with their
281 configuration directories), one entry per line. For example:
282
283 yacc ^1.0.0
284 libbar/1.0.0 /path/to/libbar/cfg/
285 libfoo/1.0.0 /path/to/libfoo/cfg/
286
287 See bpkg-cfg-create(1) for details on linked configurations.
288
289 --directory|-d dir
290 Assume current configuration is in dir rather than in the cur‐
291 rent working directory. Repeat this option to specify multiple
292 current configurations. If multiple configurations are speci‐
293 fied, they need not belong to the same linked configuration
294 cluster.
295
297 The common options are summarized below with a more detailed descrip‐
298 tion available in bpkg-common-options(1).
299
300 -v Print essential underlying commands being executed.
301
302 -V Print all underlying commands being executed.
303
304 --quiet|-q
305 Run quietly, only printing error messages.
306
307 --verbose level
308 Set the diagnostics verbosity to level between 0 and 6.
309
310 --jobs|-j num
311 Number of jobs to perform in parallel.
312
313 --no-result
314 Don't print informational messages about the outcome of perform‐
315 ing a command or some of its parts.
316
317 --no-progress
318 Suppress progress indicators for long-lasting operations, such
319 as network transfers, building, etc.
320
321 --build path
322 The build program to be used to build packages.
323
324 --build-option opt
325 Additional option to be passed to the build program.
326
327 --fetch path
328 The fetch program to be used to download resources.
329
330 --fetch-option opt
331 Additional option to be passed to the fetch program.
332
333 --fetch-timeout sec
334 The fetch and fetch-like (for example, git) program timeout.
335
336 --pkg-proxy url
337 HTTP proxy server to use when fetching package manifests and ar‐
338 chives from remote pkg repositories.
339
340 --git path
341 The git program to be used to fetch git repositories.
342
343 --git-option opt
344 Additional common option to be passed to the git program.
345
346 --sha256 path
347 The sha256 program to be used to calculate SHA256 sums.
348
349 --sha256-option opt
350 Additional option to be passed to the sha256 program.
351
352 --tar path
353 The tar program to be used to extract package archives.
354
355 --tar-option opt
356 Additional option to be passed to the tar program.
357
358 --openssl path
359 The openssl program to be used for crypto operations.
360
361 --openssl-option opt
362 Additional option to be passed to the openssl program.
363
364 --auth type
365 Types of repositories to authenticate.
366
367 --trust fingerprint
368 Trust repository certificate with a SHA256 fingerprint.
369
370 --trust-yes
371 Assume the answer to all authentication prompts is yes.
372
373 --trust-no
374 Assume the answer to all authentication prompts is no.
375
376 --pager path
377 The pager program to be used to show long text.
378
379 --pager-option opt
380 Additional option to be passed to the pager program.
381
382 --options-file file
383 Read additional options from file.
384
385 --default-options dir
386 The directory to load additional default options files from.
387
388 --no-default-options
389 Don't load default options files.
390
392 See bpkg-default-options-files(1) for an overview of the default op‐
393 tions files. For the pkg-build command the search start directory is
394 the configuration directory. The following options files are searched
395 for in each directory and, if found, loaded in the order listed:
396
397 bpkg.options
398 bpkg-pkg-build.options
399
400 The following pkg-build command options cannot be specified in the de‐
401 fault options files:
402
403 --directory|-d
404
406 Send bug reports to the users@build2.org mailing list.
407
409 Copyright (c) 2014-2021 the build2 authors.
410
411 Permission is granted to copy, distribute and/or modify this document
412 under the terms of the MIT License.
413
414
415
416bpkg 0.14.0 October 2021 bpkg-pkg-build(1)