1bpkg-pkg-build(1)           General Commands Manual          bpkg-pkg-build(1)
2
3
4

NAME

6       bpkg-pkg-build - build package
7

SYNOPSIS

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

DESCRIPTION

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
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
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
67       example:
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-
84       unpack(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
93       information 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,
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
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

PKG-BUILD PACKAGE OPTIONS

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
139       --upgrade|-u
140              Upgrade  packages to the latest available version that satisfies
141              all the constraints.
142
143       --patch|-p
144              Upgrade packages to the latest available patch version that sat‐
145              isfies all the constraints.
146
147       --immediate|-i
148              Also upgrade or patch immediate dependencies.
149
150       --recursive|-r
151              Also upgrade or patch all dependencies, recursively.
152
153       --upgrade-immediate
154              Upgrade immediate dependencies.
155
156       --patch-immediate
157              Patch immediate dependencies.
158
159       --upgrade-recursive
160              Upgrade all dependencies, recursively.
161
162       --patch-recursive
163              Patch all dependencies, recursively.
164
165       --dependency
166              Build,  upgrade,  or  downgrade a package as a dependency rather
167              than to hold.
168
169       --keep-out
170              Keep output directories of external  packages  between  upgrades
171              and downgrades.  Refer to bpkg-pkg-disfigure(1) for details.
172

PKG-BUILD GLOBAL OPTIONS

174       --yes|-y
175              Assume the answer to all prompts is yes.
176
177       --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
182       --keep-unused|-K
183              Don't drop dependency packages that were automatically built but
184              will no longer be used.
185
186       --update-dependent|-U
187              Update without confirmation dependent packages that  are  recon‐
188              figured due to their dependencies being upgraded or downgraded.
189
190       --leave-dependent|-L
191              Don't  offer  to update dependent packages that are reconfigured
192              due to their dependencies being upgraded or downgraded.
193
194       --configure-only|-c
195              Configure all the packages but don't update.
196
197       --print-only|-p
198              Print to stdout what would be done without actually  doing  any‐
199              thing.
200
201       --plan header
202              Print  the  plan  (even if --yes is specified) and start it with
203              the header line (unless it is empty).
204
205       --no-fetch
206              Don't fetch repositories specified as part of the build command.
207
208       --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
213       --directory|-d dir
214              Assume configuration is in dir rather than in the current  work‐
215              ing directory.
216

COMMON OPTIONS

218       The  common  options are summarized below with a more detailed descrip‐
219       tion available in bpkg-common-options(1).
220
221       -v     Print essential underlying commands being executed.
222
223       -V     Print all underlying commands being executed.
224
225       --quiet|-q
226              Run quietly, only printing error messages.
227
228       --verbose level
229              Set the diagnostics verbosity to level between 0 and 6.
230
231       --jobs|-j num
232              Number of jobs to perform in parallel.
233
234       --no-result
235              Don't print informational messages about the outcome of perform‐
236              ing a command.
237
238       --no-progress
239              Suppress  progress  indicators for long-lasting operations, such
240              as network transfers, building, etc.
241
242       --build path
243              The build program to be used to build packages.
244
245       --build-option opt
246              Additional option to be passed to the build program.
247
248       --fetch path
249              The fetch program to be used to download resources.
250
251       --fetch-option opt
252              Additional option to be passed to the fetch program.
253
254       --fetch-timeout sec
255              The fetch and fetch-like (for example, git) program timeout.
256
257       --git path
258              The git program to be used to fetch git repositories.
259
260       --git-option opt
261              Additional common option to be passed to the git program.
262
263       --sha256 path
264              The sha256 program to be used to calculate SHA256 sums.
265
266       --sha256-option opt
267              Additional option to be passed to the sha256 program.
268
269       --tar path
270              The tar program to be used to extract package archives.
271
272       --tar-option opt
273              Additional option to be passed to the tar program.
274
275       --openssl path
276              The openssl program to be used for crypto operations.
277
278       --openssl-option opt
279              Additional option to be passed to the openssl program.
280
281       --auth type
282              Types of repositories to authenticate.
283
284       --trust fingerprint
285              Trust repository certificate with a SHA256 fingerprint.
286
287       --trust-yes
288              Assume the answer to all authentication prompts is yes.
289
290       --trust-no
291              Assume the answer to all authentication prompts is no.
292
293       --pager path
294              The pager program to be used to show long text.
295
296       --pager-option opt
297              Additional option to be passed to the pager program.
298
299       --options-file file
300              Read additional options from file.
301
302       --default-options dir
303              The directory to load additional default options files from.
304
305       --no-default-options
306              Don't load default options files.
307

DEFAULT OPTIONS FILES

309       See  bpkg-default-options-files(1)  for  an  overview  of  the  default
310       options  files. For the pkg-build command the search start directory is
311       the configuration directory. The following options files  are  searched
312       for in each directory and, if found, loaded in the order listed:
313
314       bpkg.options
315       bpkg-pkg-build.options
316
317       The  following  pkg-build  command  options  cannot be specified in the
318       default options files:
319
320       --directory|-d
321

BUGS

323       Send bug reports to the users@build2.org mailing list.
324
326       Copyright (c) 2014-2019 Code Synthesis Ltd
327
328       Permission is granted to copy, distribute and/or modify  this  document
329       under the terms of the MIT License.
330
331
332
333bpkg 0.12.0                      November 2019               bpkg-pkg-build(1)
Impressum