1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
|
// file : bpkg/pkg-build.cli
// license : MIT; see accompanying LICENSE file
include <bpkg/configuration.cli>;
"\section=1"
"\name=bpkg-pkg-build"
"\summary=build package"
namespace bpkg
{
{
"<options>
<cfg-var>
<pkg-spec> <flags> <scheme> <pkg> <ver-spec>
<version> <version-constraint>
<file>
<dir>
<rep-loc>",
"\h|SYNOPSIS|
\c{\b{bpkg pkg-build}|\b{build} [<options>] [\b{--upgrade}|\b{-u} | \b{--patch}|\b{-p}]\n
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ [<cfg-var>... \b{--}] <pkg-spec>...\n
\b{bpkg pkg-build}|\b{build} [<options>] \ \b{--upgrade}|\b{-u} | \b{--patch}|\b{-p}\n
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ [<cfg-var>... \b{--}]}
\c{<pkg-spec> = [<flags>](([<scheme>\b{:}]<pkg>[<ver-spec>])\b{,}...[\b{@}<rep-loc>] | \n
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ [\b{@}]<rep-loc> \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ | \n
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ <file> \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ | \n
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ <dir>\b{/})\n
<flags>\ \ \ \ \ \ = \b{?}\n
<scheme> \ \ \ \ = \b{sys}\n
<ver-spec>\ \ \ = \b{/}<version> | <version-constraint>}
\h|DESCRIPTION|
The \cb{pkg-build} command builds one or more packages including all
their dependencies. Besides building new packages, this command is also
used to upgrade or downgrade packages that are already present in the
configuration. And unless the \c{\b{--keep-unused}|\b{-K}} option is
specified, \cb{pkg-build} will also drop dependency packages that would
otherwise no longer be used.
The first form (one or more packages are specified) builds new or
upgrades (by default or if \cb{--upgrade} is specified) or patches (if
\cb{--patch} is specified) the specified packages. The second form (no
arguments but either \cb{--upgrade} or \cb{--patch} is specified)
upgrades or patches all the held packages in the configuration (see
below for details on held package).
In both forms specifying the \c{\b{--immediate}|\b{-i}} or
\c{\b{--recursive}|\b{-r}} option causes \cb{pkg-build} to also upgrade
or patch the immediate or all dependencies of the specified (first form)
or held (second form) packages, respectively. Note also that in the first
form these options can only be specified with an explicit \cb{--upgrade}
or \cb{--patch}.
Each package can be specified as just the name (<pkg>) with optional
version specification (<ver-spec>), in which case the source code for the
package will be automatically fetched from one of the configured
repositories. See the \l{bpkg-rep-add(1)} and \l{bpkg-rep-fetch(1)}
commands for more information on package repositories. The version
specification (<ver-spec>) can be either the exact version in the
\c{\b{/}\i{version}} form or the version constraint as described in
\l{bpkg#package-version-constraint Package Version Constraint}. If
<ver-spec> is not specified, then the latest available version will be
built. To downgrade, the desired version must be specified
explicitly. For example:
\
bpkg build foo libfoo/1.2.3 \"bar < 2.0.0\"
\
Alternatively, the package repository location (<rep-loc>) can be
specified as part of the build command. In this case, if <ver-spec> is
not specified, then the latest available from this repository version
will be built. For example:
\
bpkg build foo,libfoo/1.2.3@https://git.example.org/foo.git#master
\
If only the location is specified, then the latest versions of all the
packages available directly from this repository will be built (note that
this does not include packages available from complement repositories).
The \cb{@} delimiter can be omitted if the location is a URL. For
example:
\
bpkg build https://git.example.org/foo.git#master
bpkg build @/path/to/repository/
\
A package name (<pkg>) can be prefixed with a package scheme
(<scheme>). Currently the only recognized scheme is \cb{sys} which
instructs \cb{pkg-build} to configure the package as available from the
system rather than building it from source. If the system package version
(<ver-spec>) is not specified or is '\cb{/*}', then it is considered to
be unknown but satisfying any version constraint. If specified,
<ver-spec> may not be a version constraint. If the version is not
explicitly specified, then at least a stub package must be available from
one of the repositories.
Finally, a package can be specified as either the path to the package
archive (<file>) or to the package directory (<dir>\cb{/}; note that it
must end with a directory separator). See the \l{bpkg-pkg-fetch(1)} and
\l{bpkg-pkg-unpack(1)} commands for more information on the semantics of
specifying the package as an archive or a directory.
Additional configuration variables (<cfg-var>), if any, should be
specified before packages (<pkg-spec>) and should be separated with
\cb{--}. Such variables are effective only when configuring and only for
packages that were explicitly specified on the command line (they can
also be specified to only apply to specific packages using the argument
grouping mechanism discussed below). See \l{bpkg-pkg-configure(1)} for
more information on configuration variables.
By default a package that is specified explicitly on the command line is
built to \i{hold}: it will not be considered for automatic removal if it
no longer has any dependents. Only versions from repositories that were
added to the configuration (\l{bpkg-rep-add(1)}) are considered as
available for build to hold.
Alternatively, a package can be built (or, more commonly,
upgraded/downgraded) as a \i{dependency} by specifying the \cb{?} flag
(<flags>) or the \cb{--dependency} option. Such a package will only be
added to the configuration if it actually has any dependents and once no
longer used, it will be automatically dropped. Only versions from
prerequisite repositories of dependent packages are considered as
available for build as a dependency.
Packages (both built to hold and as dependencies) that are specified with
an explicit package version (<ver-spec>) or as an archive or directory,
will have their versions held, that is, they will not be automatically
upgraded.
As an illustration, let's assume in the following example that the stable
repository contains packages \cb{foo} \cb{1.0.0} as well as
\cb{libfoo} \cb{1.0.0} and \cb{1.1.0} while testing \- \cb{libfoo}
\cb{2.0.0}, that testing is complemented by stable, and that \cb{foo}
depends on \cb{libfoo >= 1.0.0}:
\
bpkg fetch https://example.org/1/testing
bpkg build foo # build foo 1.0.0 to hold
# build libfoo 1.1.0 as dependency
bpkg build ?libfoo/1.0.0 # downgrade libfoo 1.0.0 as dependency,
# also hold version 1.0.0
bpkg build ?libfoo/2.0.0 # error: 2.0.0 unavailable in dependent's
# (foo) repository (stable)
bpkg build libfoo/2.0.0 # upgrade libfoo 2.0.0 to hold,
# also hold version 2.0.0
\
"
}
class pkg_build_pkg_options
{
"\h|PKG-BUILD PACKAGE OPTIONS|
The following options (as well as additional configuration variables) can
be grouped to apply to a specific \ci{pkg-spec} as well as specified
globally, in which case they apply to all the specified packages (see
\l{bpkg-argument-grouping(1)} for details)."
// NOTE: if adding a new option here, don't forget to also update
// {validate,merge,compare,print}_options() in pkg-build.cxx!
bool --upgrade|-u
{
"Upgrade packages to the latest available version that satisfies all the
constraints."
}
bool --patch|-p
{
"Upgrade packages to the latest available patch version that satisfies
all the constraints."
}
bool --immediate|-i
{
"Also upgrade or patch immediate dependencies."
}
bool --recursive|-r
{
"Also upgrade or patch all dependencies, recursively."
}
// Sometimes we may want to upgrade/patch the package itself but to
// patch/upgrade its dependencies.
//
bool --upgrade-immediate
{
"Upgrade immediate dependencies."
}
bool --patch-immediate
{
"Patch immediate dependencies."
}
bool --upgrade-recursive
{
"Upgrade all dependencies, recursively."
}
bool --patch-recursive
{
"Patch all dependencies, recursively."
}
bool --dependency
{
"Build, upgrade, or downgrade a package as a dependency rather than to
hold."
}
bool --keep-out
{
"Keep output directories of external packages between upgrades and
downgrades. Refer to \l{bpkg-pkg-disfigure(1)} for details."
}
dir_path --checkout-root
{
"<dir>",
"Check out packages that come from version control-based repositories
into the specified directory rather than into the configuration
directory. Refer to the \cb{--output-root} option in
\l{bpkg-pkg-checkout(1)} for details."
}
bool --checkout-purge
{
"Remove the checked out package (source) directories when the packages
are purged. Refer to the \cb{--output-purge} option in
\l{bpkg-pkg-checkout(1)} for details."
}
};
class pkg_build_options: configuration_options,
pkg_build_pkg_options
{
"\h|PKG-BUILD GLOBAL OPTIONS|"
bool --yes|-y
{
"Assume the answer to all prompts is \cb{yes}."
}
string --for|-f
{
"<operation>",
"Instead of the default \cb{update} build system operation, perform the
\cb{update-for-}<operation> variant where <operation> is normally
\cb{install} or \cb{test}."
}
bool --keep-unused|-K
{
"Don't drop dependency packages that were automatically built but will no
longer be used."
}
bool --update-dependent|-U
{
"Update without confirmation dependent packages that are reconfigured
due to their dependencies being upgraded or downgraded."
}
bool --leave-dependent|-L
{
"Don't offer to update dependent packages that are reconfigured due to
their dependencies being upgraded or downgraded."
}
bool --configure-only|-c
{
"Configure all the packages but don't update."
}
bool --print-only
{
"Print to \cb{stdout} what would be done without actually doing
anything."
}
string --plan
{
"<header>",
"Print the plan (even if \cb{--yes} is specified) and start it with the
<header> line (unless it is empty)."
};
bool --no-fetch
{
"Don't fetch repositories specified as part of the build command."
}
bool --fetch-shallow
{
"Don't re-fetch complement and prerequisite repositories of repositories
specified as part of the build command. Refer to the \cb{--shallow}
option in \l{bpkg-rep-fetch(1)} for details."
}
};
"
\h|DEFAULT OPTIONS FILES|
See \l{bpkg-default-options-files(1)} for an overview of the default
options files. For the \cb{pkg-build} command the search start
directory is the configuration directory. The following options files are
searched for in each directory and, if found, loaded in the order listed:
\
bpkg.options
bpkg-pkg-build.options
\
The following \cb{pkg-build} command options cannot be specified in the
default options files:
\
--directory|-d
\
"
}
|