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. 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 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 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 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 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 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 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 bpkg fetch https://example.org/1/testing
120 bpkg build foo # build foo 1.0.0 to hold
122 # build libfoo 1.1.0 as dependency
123 bpkg build ?libfoo/1.0.0 # downgrade libfoo 1.0.0 as dependency,
125 # also hold version 1.0.0
126 bpkg build ?libfoo/2.0.0 # error: 2.0.0 unavailable in dependent's
128 # (foo) repository (stable)
129 bpkg build libfoo/2.0.0 # upgrade libfoo 2.0.0 to hold,
131 # also hold version 2.0.0
132 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 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 --upgrade|-u
147 Upgrade packages to the latest available version that satisfies
148 all the constraints.
149 --patch|-p
151 Upgrade packages to the latest available patch version that sat‐
152 isfies all the constraints.
153 --immediate|-i
155 Also upgrade or patch immediate dependencies.
156 --recursive|-r
158 Also upgrade or patch all dependencies, recursively.
159 --upgrade-immediate
161 Upgrade immediate dependencies.
162 --patch-immediate
164 Patch immediate dependencies.
165 --upgrade-recursive
167 Upgrade all dependencies, recursively.
168 --patch-recursive
170 Patch all dependencies, recursively.
171 --dependency
173 Build, upgrade, or downgrade a package as a dependency rather
174 than to hold.
175 --keep-out
177 Keep output directories of external packages between upgrades
178 and downgrades. Refer to bpkg-pkg-disfigure(1) for details.
179 --disfigure
181 Disfigure packages between upgrades and downgrades effectively
182 causing a from-scratch reconfiguration.
183 --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 --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 --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 --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 --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 --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 --keep-unused|-K
220 Don't drop dependency packages that were automatically built but
221 will no longer be used.
222 --update-dependent|-U
224 Update without confirmation dependent packages that are recon‐
225 figured due to their dependencies being upgraded or downgraded.
226 --leave-dependent|-L
228 Don't offer to update dependent packages that are reconfigured
229 due to their dependencies being upgraded or downgraded.
230 --configure-only|-c
232 Configure all the packages but don't update.
233 --print-only
235 Print to stdout what would be done without actually doing any‐
236 thing.
237 --plan header
239 Print the plan (even if --yes is specified) and start it with
240 the header line (unless it is empty).
241 --no-fetch
243 Don't fetch repositories specified as part of the build command.
244 --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 --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 --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 --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 --rebuild-checksum sum
267 Hash the names, versions, and configurations of all the packages
268 that would be built. If the resulting checksum matches the spec‐
269 ified, then exit without building anything (potentially with a
270 special error code specified with the --noop-exit option). Oth‐
271 erwise, proceed to build as normal. In both cases, print the re‐
272 sulting checksum to stdout.
273 --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 yacc ^1.0.0
284 libbar/1.0.0 /path/to/libbar/cfg/
285 libfoo/1.0.0 /path/to/libfoo/cfg/
286 See bpkg-cfg-create(1) for details on linked configurations.
288 --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 -v Print essential underlying commands being executed.
301 -V Print all underlying commands being executed.
303 --quiet|-q
305 Run quietly, only printing error messages.
306 --verbose level
308 Set the diagnostics verbosity to level between 0 and 6.
309 --stdout-format format
311 Representation format to use for printing to stdout.
312 --jobs|-j num
314 Number of jobs to perform in parallel.
315 --no-result
317 Don't print informational messages about the outcome of perform‐
318 ing a command or some of its parts.
319 --progress
321 Display progress indicators for long-lasting operations, such as
322 network transfers, building, etc.
323 --no-progress
325 Suppress progress indicators for long-lasting operations, such
326 as network transfers, building, etc.
327 --build path
329 The build program to be used to build packages.
330 --build-option opt
332 Additional option to be passed to the build program.
333 --fetch path
335 The fetch program to be used to download resources.
336 --fetch-option opt
338 Additional option to be passed to the fetch program.
339 --fetch-timeout sec
341 The fetch and fetch-like (for example, git) program timeout.
342 --pkg-proxy url
344 HTTP proxy server to use when fetching package manifests and ar‐
345 chives from remote pkg repositories.
346 --git path
348 The git program to be used to fetch git repositories.
349 --git-option opt
351 Additional common option to be passed to the git program.
352 --sha256 path
354 The sha256 program to be used to calculate SHA256 sums.
355 --sha256-option opt
357 Additional option to be passed to the sha256 program.
358 --tar path
360 The tar program to be used to extract package archives.
361 --tar-option opt
363 Additional option to be passed to the tar program.
364 --openssl path
366 The openssl program to be used for crypto operations.
367 --openssl-option opt
369 Additional option to be passed to the openssl program.
370 --auth type
372 Types of repositories to authenticate.
373 --trust fingerprint
375 Trust repository certificate with a SHA256 fingerprint.
376 --trust-yes
378 Assume the answer to all authentication prompts is yes.
379 --trust-no
381 Assume the answer to all authentication prompts is no.
382 --pager path
384 The pager program to be used to show long text.
385 --pager-option opt
387 Additional option to be passed to the pager program.
388 --options-file file
390 Read additional options from file.
391 --default-options dir
393 The directory to load additional default options files from.
394 --no-default-options
396 Don't load default options files.
397 --keep-tmp
399 Don't remove the bpkg's temporary directory at the end of the
400 command execution and print its path at the verbosity level 2 or
401 higher.
402
404 See bpkg-default-options-files(1) for an overview of the default op‐
405 tions files. For the pkg-build command the search start directory is
406 the configuration directory. The following options files are searched
407 for in each directory and, if found, loaded in the order listed:
408 bpkg.options
410 bpkg-pkg-build.options
411 The following pkg-build command options cannot be specified in the de‐
413 fault options files:
414 --directory|-d
416
418 Send bug reports to the users@build2.org mailing list.
419
421 Copyright (c) 2014-2022 the build2 authors.
422 Permission is granted to copy, distribute and/or modify this document
424 under the terms of the MIT License.
425bpkg 0.15.0 July 2022 bpkg-pkg-build(1)