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
|
// file : bpkg/pkg-bindist.cli
// license : MIT; see accompanying LICENSE file
include <bpkg/configuration.cli>;
"\section=1"
"\name=bpkg-pkg-bindist"
"\summary=generate binary distribution package"
namespace bpkg
{
{
"<options> <dir> <vars> <pkg>",
"\h|SYNOPSIS|
\c{\b{bpkg pkg-bindist}|\b{bindist} [\b{--output-root}|\b{-o} <dir>] [<options>] [<vars>] <pkg>...}
\h|DESCRIPTION|
The \cb{pkg-bindist} command generates a binary distribution package for
the specified package. If additional packages are specified, then they
are bundled in the same distribution package. All the specified packages
must have been previously configured with \l{bpkg-pkg-build(1)} or
\l{bpkg-pkg-configure(1)}. For some system package managers a directory
for intermediate files and subdirectories as well as the resulting binary
package may have to be specified explicitly with the
\c{\b{--output-root}|\b{-o}} option.
Underneath, this command roughly performs the following steps: First it
installs the specified packages similar to the \l{bpkg-pkg-install(1)}
command except that it may override the installation locations (via the
\cb{config.install.*} variables) to match the distribution's layout. Then
it generates any necessary distribution package metadata files based on
the information from the package \cb{manifest} files. Finally, it invokes
the distribution-specified command to produce the binary package. Unless
overrident with the \cb{--architecture} and \cb{--distribution} options,
the binary package is generated for the host architecture using the
host's standard system package manager. Additional command line variables
(<vars>, normally \cb{config.*}) can be passed to the build system during
the installation step. See distribution-specific description sections
below for details and invocation examples.
The specified packages may have dependencies and the default behavior is
to not bundle them but rather to specify them as dependencies in the
corresponding distribution package metadata, if applicable. This default
behavior can be overridden with the \cb{--recursive} option (see the
option description for the available modes). Note, however, that
dependencies that are satisfied by system packages are always specified
as dependencies in the distribution package metadata.
"
}
// Place distribution-specific options into separate classes in case one day
// we want to only pass their own options to each implementation.
//
class pkg_bindist_debian_options
{
"\h|DEBIAN DESCRIPTION|
The Debian binary packages are generated by producing the standard
\cb{debian/control}, \cb{debian/rules}, and other package metadata files
and then invoking \cb{dpkg-buildpackage(1)} to build the binary package
from that. In particular, the \cb{debian/rules} implemenation is based on
the \cb{dh(1)} command sequencer. While this approach is normally used to
build packages from source, this implementation \"pretends\" that this is
what's happening by overriding a number of \cb{dh} targets to invoke the
\cb{build2} build system on the required packages directly in their
\cb{bpkg} configuration locations. Typical invocation:
\
bpkg build libhello
bpkg test libhello
bpkg bindist -o /tmp/output/ libhello
\
Note that the \cb{dpkg-dev} (or \cb{build-essential}) and \cb{debhelper}
Debian packages must be installed before invocation.
See \l{bpkg#bindist-mapping-debian-produce Debian Package Mapping for
Production} for details on \cb{bpkg} to Debian package name and version
mapping.
"
"\h|PKG-BINDIST DEBIAN OPTIONS|"
bool --debian-prepare-only
{
"Prepare all the package metadata files (\cb{control}, \cb{rules}, etc)
but do not invoke \cb{bpkg-buildpackage} to generate the binary
package, printing its command line instead unless requested to be
quiet. Implies \cb{--keep-output}."
}
string --debian-buildflags = "assign"
{
"<mode>",
"Package build flags (\cb{dpkg-buildflags}) usage mode. Valid <mode>
values are \cb{assign} (use the build flags instead of configured),
\cb{append} (use the build flags in addition to configured, putting
them last), \cb{prepend} (use the build flags in addition to
configured, putting them first), and \cb{ignore} (ignore build
flags). The default mode is \cb{assign}. Note that compiler mode
options, if any, are used as configured."
}
strings --debian-maint-option
{
"<o>",
"Alternative options to specify in the \cb{DEB_BUILD_MAINT_OPTIONS}
variable of the \cb{rules} file. To specify multiple maintainer options
repeat this option and/or specify them as a single value separated
with spaces."
}
strings --debian-build-option
{
"<o>",
"Additional option to pass to the \cb{dpkg-buildpackage} program. Repeat
this option to specify multiple build options."
}
string --debian-build-meta
{
"<data>",
"Alternative build metadata to include in the binary package version.
If empty value is specified, then no build metadata is included. By
default, the build metadata is the \cb{ID} and \cb{VERSION_ID}
components from \cb{os-release(5)}, for example, \cb{debian10} in
version \cb{1.2.3-0~debian10}."
}
string --debian-section
{
"<v>",
"Alternative \cb{Section} \cb{control} file field value for the main
binary package. The default is either \cb{libs} or \cb{devel},
depending on the package type."
}
string --debian-priority
{
"<v>",
"Alternative \cb{Priority} \cb{control} file field value. The default
is \cb{optional}."
}
string --debian-maintainer
{
"<v>",
"Alternative \cb{Maintainer} \cb{control} file field value. The
default is the \cb{package-email} value from package \cb{manifest}."
}
string --debian-architecture
{
"<v>",
"Alternative \cb{Architecture} \cb{control} file field value for
the main binary package. The default is \cb{any}."
}
string --debian-main-langdep
{
"<v>",
"Override the language runtime dependencies (such as \cb{libc6},
\cb{libstdc++6}, etc) in the \cb{Depends} \cb{control} file field
value of the main binary package."
}
string --debian-dev-langdep
{
"<v>",
"Override the language runtime dependencies (such as \cb{libc-dev},
\cb{libstdc++-dev}, etc) in the \cb{Depends} \cb{control} file field
value of the development (\cb{-dev}) binary package."
}
string --debian-main-extradep
{
"<v>",
"Extra dependencies to add to the \cb{Depends} \cb{control} file field
value of the main binary package."
}
string --debian-dev-extradep
{
"<v>",
"Extra dependencies to add to the \cb{Depends} \cb{control} file field
value of the development (\cb{-dev}) binary package."
}
};
// NOTE: remember to add the corresponding `--class-doc ...=exclude-base`
// (both in bpkg/ and doc/) if adding a new base class.
//
class pkg_bindist_options: configuration_options,
pkg_bindist_debian_options
{
"\h|PKG-BINDIST COMMON OPTIONS|"
string --distribution
{
"<name>",
"Alternative system/distribution package manager to generate the binary
package for. The valid <name> values are \cb{debian} (Debian and
alike, such as Ubuntu, etc) and \cb{fedora} (Fedora and alike,
such as RHEL, CentOS, etc). Note that some package managers may
only be supported when running on certain host operating systems."
}
string --architecture
{
"<name>",
"Alternative architecture to generate the binary package for. The
valid <name> values are system/distribution package manager-specific.
If unspecified, the host architecture is used."
}
string --recursive
{
"<mode>",
"Bundle dependencies of the specified packages. The <mode> value can be
either \cb{auto}, in which case only the required files from each
dependency package are bundled, or \cb{full}, in which case all the
files are bundled. Specifically, in the \cb{auto} mode any required
files, for example, shared libraries, are pulled implicitly by the
\cb{install} build system operation, for example, as part of
installing an executable from one of the specified packages. In
contrast, in the \cb{full} mode, each dependency package is
installed explicitly and completely, as if they were specified
as additional package on the command line. See also the \cb{--private}
option."
}
bool --private
{
"Enable the private installation subdirectory functionality using the
package name as the private subdirectory. This is primarily useful
when bundling dependencies, such as shared libraries, of an executable
that is being installed into a shared location, such as \cb{/usr/}.
See the \cb{config.install.private} configuration variable
documentation in the build system manual for details. This option only
makes sense together with \cb{--recursive}."
}
dir_path --output-root|-o
{
"<dir>",
"Directory for intermediate files and subdirectories as well as the
resulting binary package. Note that this option may be required for
some system package managers and may not be specified for others."
}
bool --wipe-output
{
"Wipe the output root directory (either specified with \ci{--output-root}
or system package manager-specific) clean before using it to generate
the binary package."
}
bool --keep-output
{
"Keep intermediate files in the output root directory (either specified
with \ci{--output-root} or system package manager-specific) that were
used to generate the binary package. This is primarily useful for
troubleshooting."
}
};
"
\h|DEFAULT OPTIONS FILES|
See \l{bpkg-default-options-files(1)} for an overview of the default
options files. For the \cb{pkg-bindist} 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-bindist.options
\
The following \cb{pkg-bindist} command options cannot be specified in the
default options files:
\
--directory|-d
\
"
}
|