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
31 upgrades (by default or if --upgrade is specified) or patches (if
32 --patch is specified) the specified packages. The second form (no argu‐
33 ments but either --upgrade or --patch is specified) upgrades or patches
34 all the held packages in the configuration (see below for details on
35 held package).
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
67 example:
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-
84 unpack(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
93 information 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,
102 upgraded/downgraded) as a dependency by specifying the ? flag (flags)
103 or the --dependency option. Such a package will only be added to the
104 configuration if it actually has any dependents and once no longer
105 used, 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
134 The following options (as well as additional configuration variables)
135 can be grouped to apply to a specific pkg-spec as well as specified
136 globally, in which case they apply to all the specified packages (see
137 bpkg-argument-grouping(1) for details).
138 --upgrade|-u
140 Upgrade packages to the latest available version that satisfies
141 all the constraints.
142 --patch|-p
144 Upgrade packages to the latest available patch version that sat‐
145 isfies all the constraints.
146 --immediate|-i
148 Also upgrade or patch immediate dependencies.
149 --recursive|-r
151 Also upgrade or patch all dependencies, recursively.
152 --upgrade-immediate
154 Upgrade immediate dependencies.
155 --patch-immediate
157 Patch immediate dependencies.
158 --upgrade-recursive
160 Upgrade all dependencies, recursively.
161 --patch-recursive
163 Patch all dependencies, recursively.
164 --dependency
166 Build, upgrade, or downgrade a package as a dependency rather
167 than to hold.
168 --keep-out
170 Keep output directories of external packages between upgrades
171 and downgrades. Refer to bpkg-pkg-disfigure(1) for details.
172
174 --yes|-y
175 Assume the answer to all prompts is yes.
176 --for|-f operation
178 Instead of the default update build system operation, perform
179 the update-for-operation variant where operation is normally
180 install or test.
181 --keep-unused|-K
183 Don't drop dependency packages that were automatically built but
184 will no longer be used.
185 --update-dependent|-U
187 Update without confirmation dependent packages that are recon‐
188 figured due to their dependencies being upgraded or downgraded.
189 --leave-dependent|-L
191 Don't offer to update dependent packages that are reconfigured
192 due to their dependencies being upgraded or downgraded.
193 --configure-only|-c
195 Configure all the packages but don't update.
196 --print-only|-p
198 Print to stdout what would be done without actually doing any‐
199 thing.
200 --plan header
202 Print the plan (even if --yes is specified) and start it with
203 the header line (unless it is empty).
204 --no-fetch
206 Don't fetch repositories specified as part of the build command.
207 --fetch-shallow
209 Don't re-fetch complement and prerequisite repositories of
210 repositories specified as part of the build command. Refer to
211 the --shallow option in bpkg-rep-fetch(1) for details.
212 --directory|-d dir
214 Assume configuration is in dir rather than in the current work‐
215 ing directory.
216
218 The common options are summarized below with a more detailed descrip‐
219 tion available in bpkg-common-options(1).
220 -v Print essential underlying commands being executed.
222 -V Print all underlying commands being executed.
224 --quiet|-q
226 Run quietly, only printing error messages.
227 --verbose level
229 Set the diagnostics verbosity to level between 0 and 6.
230 --jobs|-j num
232 Number of jobs to perform in parallel.
233 --no-result
235 Don't print informational messages about the outcome of perform‐
236 ing a command.
237 --no-progress
239 Suppress progress indicators for long-lasting operations, such
240 as network transfers, building, etc.
241 --build path
243 The build program to be used to build packages.
244 --build-option opt
246 Additional option to be passed to the build program.
247 --fetch path
249 The fetch program to be used to download resources.
250 --fetch-option opt
252 Additional option to be passed to the fetch program.
253 --fetch-timeout sec
255 The fetch and fetch-like (for example, git) program timeout.
256 --pkg-proxy url
258 HTTP proxy server to use when fetching package manifests and ar‐
259 chives from remote pkg repositories.
260 --git path
262 The git program to be used to fetch git repositories.
263 --git-option opt
265 Additional common option to be passed to the git program.
266 --sha256 path
268 The sha256 program to be used to calculate SHA256 sums.
269 --sha256-option opt
271 Additional option to be passed to the sha256 program.
272 --tar path
274 The tar program to be used to extract package archives.
275 --tar-option opt
277 Additional option to be passed to the tar program.
278 --openssl path
280 The openssl program to be used for crypto operations.
281 --openssl-option opt
283 Additional option to be passed to the openssl program.
284 --auth type
286 Types of repositories to authenticate.
287 --trust fingerprint
289 Trust repository certificate with a SHA256 fingerprint.
290 --trust-yes
292 Assume the answer to all authentication prompts is yes.
293 --trust-no
295 Assume the answer to all authentication prompts is no.
296 --pager path
298 The pager program to be used to show long text.
299 --pager-option opt
301 Additional option to be passed to the pager program.
302 --options-file file
304 Read additional options from file.
305 --default-options dir
307 The directory to load additional default options files from.
308 --no-default-options
310 Don't load default options files.
311
313 See bpkg-default-options-files(1) for an overview of the default
314 options files. For the pkg-build command the search start directory is
315 the configuration directory. The following options files are searched
316 for in each directory and, if found, loaded in the order listed:
317 bpkg.options
319 bpkg-pkg-build.options
320 The following pkg-build command options cannot be specified in the
322 default options files:
323 --directory|-d
325
327 Send bug reports to the users@build2.org mailing list.
328
330 Copyright (c) 2014-2020 the build2 authors.
331 Permission is granted to copy, distribute and/or modify this document
333 under the terms of the MIT License.
334bpkg 0.13.0 July 2020 bpkg-pkg-build(1)