1bpkg-pkg-build(1) General Commands Manual bpkg-pkg-build(1)
2
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 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 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 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 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 bpkg build foo libfoo/1.2.3 "bar < 2.0.0"
55 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 bpkg build foo,libfoo/1.2.3@https://git.example.org/foo.git#master
62 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 bpkg build https://git.example.org/foo.git#master
70 bpkg build @/path/to/repository/
71 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.
76 The system package version (ver-spec) may not be a version constraint
78 but may be the special '/*' value, which indicates that the version
79 should be considered unknown but satisfying any version constraint. If
80 unspecified, then pkg-build will attempt to query the system package
81 manager for the installed version unless the system package manager is
82 unsupported or this functionality is disabled with --sys-no-query, in
83 which case the '/*' ver-spec is assumed. If the system package manager
84 is supported, then the automatic installation of an available package
85 can be requested with the --sys-install option. Note that if the ver‐
86 sion is not explicitly specified, then at least a stub package must be
87 available from one of the repositories unless the --sys-no-stub option
88 is specified.
89 Finally, a package can be specified as either the path to the package
91 archive (file) or to the package directory (dir/; note that it must end
92 with a directory separator). See the bpkg-pkg-fetch(1) and bpkg-pkg-un‐
93 pack(1) commands for more information on the semantics of specifying
94 the package as an archive or a directory.
95 Additional configuration variables (cfg-var), if any, should be speci‐
97 fied before packages (pkg-spec) and should be separated with --. Such
98 variables are effective only when configuring and only for packages
99 that were explicitly specified on the command line (unless global over‐
100 rides). They can also be specified to only apply to specific packages
101 using the argument grouping mechanism discussed below. See bpkg-pkg-
102 configure(1) for more information on configuration variables.
103 By default a package that is specified explicitly on the command line
105 is built to hold: it will not be considered for automatic removal if it
106 no longer has any dependents. Only versions from repositories that were
107 added to the configuration (bpkg-rep-add(1)) are considered as avail‐
108 able for build to hold.
109 Alternatively, a package can be built (or, more commonly, up‐
111 graded/downgraded) as a dependency by specifying the ? flag (flags) or
112 the --dependency option. Such a package will only be added to the con‐
113 figuration if it actually has any dependents and once no longer used,
114 it will be automatically dropped. Only versions from prerequisite
115 repositories of dependent packages are considered as available for
116 build as a dependency.
117 Packages (both built to hold and as dependencies) that are specified
119 with an explicit package version (ver-spec) or as an archive or direc‐
120 tory, will have their versions held, that is, they will not be automat‐
121 ically upgraded.
122 As an illustration, let's assume in the following example that the sta‐
124 ble repository contains packages foo 1.0.0 as well as libfoo 1.0.0 and
125 1.1.0 while testing – libfoo 2.0.0, that testing is complemented by
126 stable, and that foo depends on libfoo >= 1.0.0:
127 bpkg fetch https://example.org/1/testing
129 bpkg build foo # build foo 1.0.0 to hold
131 # build libfoo 1.1.0 as dependency
132 bpkg build ?libfoo/1.0.0 # downgrade libfoo 1.0.0 as dependency,
134 # also hold version 1.0.0
135 bpkg build ?libfoo/2.0.0 # error: 2.0.0 unavailable in dependent's
137 # (foo) repository (stable)
138 bpkg build libfoo/2.0.0 # upgrade libfoo 2.0.0 to hold,
140 # also hold version 2.0.0
141 A package can be built in one of the linked configurations instead of
143 the current (or host/build system module, for build-time dependencies)
144 configuration by specifying one of the --config-* options (see bpkg-
145 cfg-create(1) for background on linked configurations). For example:
146 bpkg build foo { --config-name=alt-host }+ ?bison
148
150 The following options (as well as additional configuration variables)
151 can be grouped to apply to a specific pkg-spec as well as specified
152 globally, in which case they apply to all the specified packages (see
153 bpkg-argument-grouping(1) for details).
154 --upgrade|-u
156 Upgrade packages to the latest available version that satisfies
157 all the constraints.
158 --patch|-p
160 Upgrade packages to the latest available patch version that sat‐
161 isfies all the constraints.
162 --deorphan
164 Replace orphaned packages with the best matching available pack‐
165 age versions which satisfy all the constraints.
166 It may happen that a built package no longer has the correspond‐
168 ing package available in the repository it came from (for exam‐
169 ple, as a result of bpkg-rep-fetch(1) or bpkg-rep-remove(1)).
170 Such a package is called an orphan. Without the --deorphan op‐
171 tion, upgrading, downgrading, or patching an orphan will leave
172 it unchanged if a more suitable version of the package is not
173 available. If the --deorphan option is specified, then an orphan
174 will be replaced with a non-orphan. In this case, if --upgrade,
175 --patch, or the package version is specified, then the new ver‐
176 sion is selected accordingly. Otherwise, the closest version to
177 the orphaned version is selected using the following preference
178 order: (1) same version, revision, and iteration, (2) latest it‐
179 eration of same version and revision, (3) later revision of same
180 version, (4) later patch of same version, (5) later minor of
181 same version, (6) latest available version, including earlier
182 (see Package Version (#package-version) for details).
183 --immediate|-i
185 Also upgrade, patch, or deorphan immediate dependencies.
186 --recursive|-r
188 Also upgrade, patch, or deorphan all dependencies, recursively.
189 --upgrade-immediate
191 Upgrade immediate dependencies.
192 --patch-immediate
194 Patch immediate dependencies.
195 --deorphan-immediate
197 Deorphan immediate dependencies.
198 --upgrade-recursive
200 Upgrade all dependencies, recursively.
201 --patch-recursive
203 Patch all dependencies, recursively.
204 --deorphan-recursive
206 Deorphan all dependencies, recursively.
207 --dependency
209 Build, upgrade, or downgrade a package as a dependency rather
210 than to hold.
211 --keep-out
213 Keep output directories of external packages between upgrades
214 and downgrades. Refer to bpkg-pkg-disfigure(1) for details.
215 --disfigure
217 Disfigure packages between upgrades and downgrades effectively
218 causing a from-scratch reconfiguration.
219 --checkout-root dir
221 Check out packages that come from version control-based reposi‐
222 tories into the specified directory rather than into the config‐
223 uration directory. Refer to the --output-root option in bpkg-
224 pkg-checkout(1) for details.
225 --checkout-purge
227 Remove the checked out package (source) directories when the
228 packages are purged. Refer to the --output-purge option in bpkg-
229 pkg-checkout(1) for details.
230 --config-name name
232 Name of the linked configuration to build this package(s) in. By
233 default, the package is built in the current configuration. Re‐
234 peat this option to specify multiple configurations.
235 --config-id num
237 Numeric id of the linked configuration to build this package(s)
238 in. By default, the package is built in the current configura‐
239 tion. Repeat this option to specify multiple configurations.
240 --config-uuid uuid
242 UUID of the linked configuration to build this package(s) in. By
243 default, the package is built in the current configuration. Re‐
244 peat this this option to specify multiple configurations.
245
247 --yes|-y
248 Assume the answer to all prompts is yes. Note that this excludes
249 the system package manager prompts; see --sys-yes for details.
250 --for|-f operation
252 Instead of the default update build system operation, perform
253 the update-for-operation variant where operation is normally in‐
254 stall or test.
255 --keep-unused|-K
257 Don't drop dependency packages that were automatically built but
258 will no longer be used.
259 --update-dependent|-U
261 Update without confirmation dependent packages that are recon‐
262 figured due to their dependencies being upgraded or downgraded.
263 --leave-dependent|-L
265 Don't offer to update dependent packages that are reconfigured
266 due to their dependencies being upgraded or downgraded.
267 --configure-only|-c
269 Configure all the packages but don't update.
270 --print-only
272 Print to stdout what would be done without actually doing any‐
273 thing.
274 --plan header
276 Print the plan (even if --yes is specified) and start it with
277 the header line (unless it is empty).
278 --no-fetch
280 Don't fetch repositories specified as part of the build command.
281 --fetch-shallow
283 Don't re-fetch complement and prerequisite repositories of
284 repositories specified as part of the build command. Refer to
285 the --shallow option in bpkg-rep-fetch(1) for details.
286 --mask-repository rep
288 For the duration of the command execution pretend the specified
289 repository was removed as if by performing the rep-remove com‐
290 mand. The repository can be specified either as a repository
291 name or as a repository location (URL or a directory path). Note
292 that the repository's complement and prerequisite repositories
293 are also considered masked, recursively, unless they are comple‐
294 ments and/or prerequisites of other unmasked repositories. Re‐
295 peat this option to mask multiple repositories.
296 --mask-repository-uuid v
298 For the duration of the command execution pretend the specified
299 repository was removed from the specified configuration. Similar
300 to --mask-repository but only masks the repository in a single
301 configuration. The option value is a key-value pair in the form:
302 config-uuid=rep
304 Repeat this option to mask multiple repositories.
306 --no-refinement
308 Don't try to refine the configuration by offering to drop any
309 unused dependencies that were potentially left behind on the
310 previous pkg-build or pkg-drop command execution if the command
311 is otherwise a noop (performs no new package builds, upgrades,
312 etc).
313 --no-move
315 Don't move dependency packages between configurations. In this
316 mode the --config-* options specify packages' current rather
317 than new locations.
318 --noop-exit code
320 Exit with the specified error code if the command execution is a
321 noop (performs no new package builds, upgrades, etc).
322 --rebuild-checksum sum
324 Hash the names, versions, and configurations of all the packages
325 that would be built. If the resulting checksum matches the spec‐
326 ified, then exit without building anything (potentially with a
327 special error code specified with the --noop-exit option). Oth‐
328 erwise, proceed to build as normal. In both cases, print the re‐
329 sulting checksum to stdout.
330 --no-private-config code
332 If no configuration of a suitable type is linked to build a
333 build-time dependency, instead of automatically creating a pri‐
334 vate configuration of this type, exit with the specified error
335 code printing to stdout the dependency chain starting from the
336 build-time dependency (together with its constraint, if present)
337 and ending with the top-level dependent (together with their
338 configuration directories), one entry per line. For example:
339 yacc ^1.0.0
341 libbar/1.0.0 /path/to/libbar/cfg/
342 libfoo/1.0.0 /path/to/libfoo/cfg/
343 See bpkg-cfg-create(1) for details on linked configurations.
345 --sys-no-query
347 Do not query the system package manager for the installed ver‐
348 sions of packages specified with the sys scheme.
349 --sys-install
351 Instruct the system package manager to install available ver‐
352 sions of packages specified with the sys scheme that are not al‐
353 ready installed. See also the --sys-no-fetch, --sys-yes, and
354 --sys-sudo options.
355 --sys-no-fetch
357 Do not fetch the system package manager metadata before querying
358 for available versions of packages specified with the sys
359 scheme. This option only makes sense together with --sys-in‐
360 stall.
361 --sys-no-stub
363 Do no require a stub for packages specified with the sys scheme.
364 Note that this option has effect only if the system package man‐
365 ager interactions are supported and not disabled.
366 --sys-yes
368 Assume the answer to the system package manager prompts is yes.
369 Note that system package manager interactions may break your
370 system and you should normally only use this option on throw-
371 away setups (test virtual machines, etc).
372 --sys-sudo prog
374 The sudo program to use for system package manager interactions
375 that normally require administrative privileges (fetch package
376 metadata, install packages, etc). If unspecified, sudo is used
377 by default. Pass empty or the special false value to disable the
378 use of the sudo program. Note that the sudo program is normally
379 only needed if the system package installation is enabled with
380 the --sys-install option.
381 --sys-distribution name
383 Alternative system/distribution package manager to interact
384 with. The valid name values are debian (Debian and alike, such
385 as Ubuntu, etc) and fedora (Fedora and alike, such as RHEL, Cen‐
386 tOS, etc). Note that some package managers may only be supported
387 when running on certain host operating systems.
388 --sys-architecture name
390 Alternative architecture to use when interacting with the system
391 package manager. The valid name values are system/distribution
392 package manager-specific. If unspecified, the host architecture
393 is used.
394 --directory|-d dir
396 Assume current configuration is in dir rather than in the cur‐
397 rent working directory. Repeat this option to specify multiple
398 current configurations. If multiple configurations are speci‐
399 fied, they need not belong to the same linked configuration
400 cluster.
401
403 The common options are summarized below with a more detailed descrip‐
404 tion available in bpkg-common-options(1).
405 -v Print essential underlying commands being executed.
407 -V Print all underlying commands being executed.
409 --quiet|-q
411 Run quietly, only printing error messages.
412 --verbose level
414 Set the diagnostics verbosity to level between 0 and 6.
415 --stdout-format format
417 Representation format to use for printing to stdout.
418 --jobs|-j num
420 Number of jobs to perform in parallel.
421 --no-result
423 Don't print informational messages about the outcome of perform‐
424 ing a command or some of its parts.
425 --structured-result fmt
427 Write the result of performing a command in a structured form.
428 --progress
430 Display progress indicators for long-lasting operations, such as
431 network transfers, building, etc.
432 --no-progress
434 Suppress progress indicators for long-lasting operations, such
435 as network transfers, building, etc.
436 --diag-color
438 Use color in diagnostics.
439 --no-diag-color
441 Don't use color in diagnostics.
442 --build path
444 The build program to be used to build packages.
445 --build-option opt
447 Additional option to be passed to the build program.
448 --fetch path
450 The fetch program to be used to download resources.
451 --fetch-option opt
453 Additional option to be passed to the fetch program.
454 --fetch-timeout sec
456 The fetch and fetch-like (for example, git) program timeout.
457 --pkg-proxy url
459 HTTP proxy server to use when fetching package manifests and ar‐
460 chives from remote pkg repositories.
461 --git path
463 The git program to be used to fetch git repositories.
464 --git-option opt
466 Additional common option to be passed to the git program.
467 --sha256 path
469 The sha256 program to be used to calculate SHA256 sums.
470 --sha256-option opt
472 Additional option to be passed to the sha256 program.
473 --tar path
475 The tar program to be used to extract package archives.
476 --tar-option opt
478 Additional option to be passed to the tar program.
479 --openssl path
481 The openssl program to be used for crypto operations.
482 --openssl-option opt
484 Additional option to be passed to the openssl program.
485 --auth type
487 Types of repositories to authenticate.
488 --trust fingerprint
490 Trust repository certificate with a SHA256 fingerprint.
491 --trust-yes
493 Assume the answer to all authentication prompts is yes.
494 --trust-no
496 Assume the answer to all authentication prompts is no.
497 --git-capabilities up=pc
499 Protocol capabilities (pc) for a git repository URL prefix (up).
500 --pager path
502 The pager program to be used to show long text.
503 --pager-option opt
505 Additional option to be passed to the pager program.
506 --options-file file
508 Read additional options from file.
509 --default-options dir
511 The directory to load additional default options files from.
512 --no-default-options
514 Don't load default options files.
515 --keep-tmp
517 Don't remove the bpkg's temporary directory at the end of the
518 command execution and print its path at the verbosity level 2 or
519 higher.
520
522 See bpkg-default-options-files(1) for an overview of the default op‐
523 tions files. For the pkg-build command the search start directory is
524 the configuration directory. The following options files are searched
525 for in each directory and, if found, loaded in the order listed:
526 bpkg.options
528 bpkg-pkg-build.options
529 The following pkg-build command options cannot be specified in the de‐
531 fault options files:
532 --directory|-d
534
536 Send bug reports to the users@build2.org mailing list.
537
539 Copyright (c) 2014-2023 the build2 authors.
540 Permission is granted to copy, distribute and/or modify this document
542 under the terms of the MIT License.
543bpkg 0.16.0 June 2023 bpkg-pkg-build(1)