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
|
// file : bpkg/pkg-build.cli
// copyright : Copyright (c) 2014-2018 Code Synthesis Ltd
// license : MIT; see accompanying LICENSE file
include <bpkg/configuration.cli>;
"\section=1"
"\name=bpkg-pkg-build"
"\summary=build package"
namespace bpkg
{
{
"<options>
<pkg-spec> <flags> <scheme> <pkg> <ver>
<file>
<dir>
<rep-loc>",
"\h|SYNOPSIS|
\c{\b{bpkg pkg-build}|\b{build} [<options>] [\b{--upgrade}|\b{-u} | \b{--patch}|\b{-p}] <pkg-spec>...\n
\b{bpkg pkg-build}|\b{build} [<options>] \ \b{--upgrade}|\b{-u} | \b{--patch}|\b{-p}}
\c{<pkg-spec> = [<flags>](([<scheme>\b{:}]<pkg>[\b{/}<ver>])\b{,}...[\b{@}<rep-loc>] | \n
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ [\b{@}]<rep-loc> \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ | \n
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ <file> \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ | \n
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ <dir>\b{/})\n
<flags>\ \ \ \ = \b{?}\n
<scheme> \ \ = \b{sys}}
\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
package version (<ver>) 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. If <ver> 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
\
Alternatively, the package repository location (<rep-loc>) can be
specified as part of the build command. In this case, if <ver> 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>) is not specified, then it is considered to be unknown but
satisfying any dependency constraint. Such a version is displayed as
'\cb{*}'.
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.
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>) 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 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."
}
};
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|-p
{
"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."
}
};
}
|