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
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
|
// file : bpkg/pkg-bindist.cli
// license : MIT; see accompanying LICENSE file
include <map>;
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-specific command to produce the binary package. Unless
overridden 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 the following distribution-specific
description sections below for details and invocation examples:
\l{#debian DEBIAN DESCRIPTION}
\l{#fedora FEDORA DESCRIPTION}
\l{#archive ARCHIVE DESCRIPTION}
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 (if applicable).
"
}
// 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_common_options: configuration_options
{
"\h|PKG-BINDIST OPTIONS|
See the following sections below for distribution-specific options:
\l{#debian-options PKG-BINDIST DEBIAN OPTIONS}
\l{#fedora-options PKG-BINDIST FEDORA OPTIONS}
\l{#archive-options PKG-BINDIST ARCHIVE 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), \cb{fedora} (Fedora and alike, such as RHEL,
CentOS, etc), and \cb{archive} (installation archive on any operating
system). 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 = "none"
{
"<mode>",
"Bundle or generate 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, \cb{full}, in which case
all the files are bundled, or \cb{separate}, in which case a separate
binary package is generated for each non-system dependency. It can
also be \cb{none} which is equivalent to not specifying this option
(primarily useful for overriding a previously-specified value).
Specifically, in the \cb{auto} mode any required files, such as 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. The
\cb{separate} mode is equivalent to invoking the \cb{pkg-bindist}
command on each dependency package. 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 the \cb{--recursive} option \cb{auto} and \cb{full} modes."
}
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."
}
bool --allow-dependent-config
{
"Allow configuration that is imposed by dependent packages. Normally
this is undesirable because the resulting binary packages become
configured specificaly for particular dependent packages."
}
string --os-release-id
{
"<v>",
"Override the \cb{ID} component in \cb{os-release(5)} or equivalent.
Note that unlike the rest of the \cb{--os-release-*} options, this
option suppresses automatic detection of the host operating system
information."
}
string --os-release-version-id
{
"<v>",
"Override the \cb{VERSION_ID} component in \cb{os-release(5)} or
equivalent."
}
string --os-release-name
{
"<v>",
"Override the \cb{NAME} component in \cb{os-release(5)} or equivalent."
}
};
class pkg_bindist_debian_options
{
"\h#debian|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.
The \cb{dpkg-dev} (or \cb{build-essential}) and \cb{debhelper} Debian
packages must be installed before invocation. Typical invocation:
\
bpkg build libhello
bpkg test libhello
bpkg bindist -o /tmp/output/ libhello
\
Unless the \cb{--recursive} option \cb{auto} or \cb{full} modes are
specified, dependencies of the specified package are translated to
dependencies in the resulting binary package using names and versions
that refer to packages that would be generated by the \cb{pkg-bindist}
command (called \"non-native\" packages). If instead you would like
certain dependencies to refer to binary packages provided by the
distribution (called \"native\" packages), then you need to arrange for
them to be built as system (see \l{bpkg-pkg-build(1)} for details). For
example, if our \cb{libhello} has a dependency on \cb{libsqlite3} and we
would like the binary package for \cb{libhello} to refer to
\cb{libsqlite3} from Debian (or alike), then the \cb{pkg-build} command
would need to be (\cb{--sys-install} is optional):
\
bpkg build --sys-install libhello ?sys:libsqlite3
\
Such a package with native dependencies can then be installed (including
any missing native dependencies) using the \cb{apt} or \cb{apt-get}
\cb{install} command. Note that the specified \cb{.deb} file must include
a directory separator (\c{/}) in order to be recognized as a file rather
than a package name. For example:
\
sudo apt-get install ./libhello_1.2.3-0~debian11_amd64.deb \
./libhello-dev_1.2.3-0~debian11_amd64.deb
\
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#debian-options|PKG-BINDIST DEBIAN OPTIONS|"
bool --debian-prepare-only
{
"Prepare all the package metadata files (\cb{control}, \cb{rules}, etc)
but do not invoke \cb{dpkg-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 or additional build metadata to include in the binary
package version. If the specified value starts/ends with \cb{+} then
the value (with \cb{+} removed) is added after/before the default
metadata. Otherwise it is used as is instead of the default metadata.
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}. See also \cb{--os-release-*}."
}
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, normally \cb{all} (architecture-independent).
The default is \cb{any} (architecture-dependent)."
}
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."
}
};
class pkg_bindist_fedora_options
{
"\h#fedora|FEDORA DESCRIPTION|
The Fedora binary packages are generated by producing the standard RPM
spec file and then invoking \cb{rpmbuild(8)} to build the binary package
from that. 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 RPM spec file sections to invoke the \cb{build2}
build system on the required packages directly in their \cb{bpkg}
configuration locations.
The \cb{rpmdevtools} Fedora package must be installed before invocation.
Typical invocation:
\
bpkg build libhello
bpkg test libhello
bpkg bindist libhello
\
The resulting binary packages are placed into the standard \cb{rpmbuild}
output directory (normally \c{\b{~/rpmbuild/RPMS/}\i{arch}\b{/}}).
Unless the \cb{--recursive} option \cb{auto} or \cb{full} modes are
specified, dependencies of the specified package are translated to
dependencies in the resulting binary package using names and versions
that refer to packages that would be generated by the \cb{pkg-bindist}
command (called \"non-native\" packages). If instead you would like
certain dependencies to refer to binary packages provided by the
distribution (called \"native\" packages), then you need to arrange for
them to be built as system (see \l{bpkg-pkg-build(1)} for details). For
example, if our \cb{libhello} has a dependency on \cb{libsqlite3} and we
would like the binary package for \cb{libhello} to refer to
\cb{sqlite-libs} from Fedora (or alike), then the \cb{pkg-build} command
would need to be (\cb{--sys-install} is optional):
\
bpkg build --sys-install libhello ?sys:libsqlite3
\
Such a package with native dependencies can then be installed (including
any missing native dependencies) using the \cb{dnf install} command.
For example:
\
sudo dnf install libhello-1.2.3-1.fc35.x86_64.rpm \
libhello-devel-1.2.3-1.fc35.x86_64.rpm
\
See \l{bpkg#bindist-mapping-fedora-produce Fedora Package Mapping for
Production} for details on \cb{bpkg} to Fedora package name and version
mapping.
"
"\h#fedora-options|PKG-BINDIST FEDORA OPTIONS|"
bool --fedora-prepare-only
{
"Prepare the RPM spec file but do not invoke \cb{rpmbuild} to generate
the binary package, printing its command line instead unless requested
to be quiet."
}
string --fedora-buildflags = "assign"
{
"<mode>",
"Package build flags (\cb{%{build_*flags\}} macros) 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 --fedora-build-option
{
"<o>",
"Additional option to pass to the \cb{rpmbuild} program. If specified,
these options must be consistent with the query options
(\cb{--fedora-query-option}) to result in identical macro
expansions. Repeat this option to specify multiple build options."
}
strings --fedora-query-option
{
"<o>",
"Additional option to pass to the \cb{rpm} program. This program is used
to query RPM macro values which affect the binary package. If
specified, these options must be consistent with the build options
(\cb{--fedora-build-option}) to result in identical macro expansions.
Repeat this option to specify multiple query options."
}
string --fedora-dist-tag
{
"<tag>",
"Alternative or additional distribution tag to use in the binary package
release. If the specified value starts/ends with \cb{+} then the value
(with \cb{+} removed) is added after/before the default distribution
tag. Otherwise it is used as is instead of the default tag. If empty
value is specified, then no distribution tag is included. The default
is a value that identifies the distribution being used to build the
package, for example, \cb{fc35} for Fedora 35 or \cb{el8} for RHEL 8."
}
string --fedora-packager
{
"<v>",
"Alternative \cb{Packager} RPM spec file directive value. The default is
the \cb{package-email} value from package \cb{manifest}. If empty value
is specified, then the \cb{Packager} directive is omitted from the spec
file."
}
string --fedora-build-arch
{
"<v>",
"\cb{BuildArch} RPM spec file directive value for the main binary
package, normally \cb{noarch} (architecture-independent). By default
the directive is omitted, assuming that the package is
architecture-dependent."
}
strings --fedora-main-langreq
{
"<v>",
"Override the language runtime dependencies (such as \cb{glibc},
\cb{libstdc++}, etc) of the main binary package by replacing the
corresponding \cb{Requires} RPM spec file directives. If empty value is
specified then no language runtime dependencies are specified. Repeat
this option to specify multiple language runtime dependencies."
}
strings --fedora-devel-langreq
{
"<v>",
"Override the language runtime dependencies (such as \cb{glibc-devel},
\cb{libstdc++-devel}, etc) of the development (\cb{-devel}) binary
package by replacing the corresponding \cb{Requires} RPM spec file
directives. If empty value is specified then no language runtime
dependencies are specified. Repeat this option to specify multiple
language runtime dependencies."
}
strings --fedora-stat-langreq
{
"<v>",
"Override the language runtime dependencies (such as \cb{glibc-static},
\cb{libstdc++-static}, etc) of the static libraries (\cb{-static})
binary package by replacing the corresponding \cb{Requires} RPM spec
file directives. If empty value is specified then no language runtime
dependencies are specified. Repeat this option to specify multiple
language runtime dependencies."
}
strings --fedora-main-extrareq
{
"<v>",
"Extra dependency to add to the main binary package as an additional
\cb{Requires} RPM spec file directive. Repeat this option to specify
multiple extra dependencies."
}
strings --fedora-devel-extrareq
{
"<v>",
"Extra dependency to add to the development (\cb{-devel}) binary package
as an additional \cb{Requires} RPM spec file directive. Repeat this
option to specify multiple extra dependencies."
}
strings --fedora-stat-extrareq
{
"<v>",
"Extra dependency to add to the static libraries (\cb{-static}) binary
package as an additional \cb{Requires} RPM spec file directive. Repeat
this option to specify multiple extra dependencies."
}
};
class pkg_bindist_archive_options
{
"\h#archive|ARCHIVE DESCRIPTION|
The installation archive binary packages are generated by invoking the
\cb{build2} build system on the required packages directly in their
\cb{bpkg} configuration locations and installing them into the binary
package directory using the \cb{config.install.chroot} mechanism. Then
this directory is packaged with \cb{tar} or \cb{zip} to produce one or
more binary package archives.
The generation of installation archive packages is never the default and
should be requested explicitly with the \cb{--distribution=archive}
option. The installation directory layout and the package archives to
generate can be specified with the \cb{--archive-install-*} and
\cb{--archive-type} options (refer to their documentation for defaults).
The binary package directory (the top-level directory inside the
archive) as well as the archive file base (the file name without
the extension) are the same and have the following form:
\c{\i{package}-\i{version}-\i{build_metadata}}
Where \ci{package} is the package name and \ci{version} is the \cb{bpkg}
package version. Unless overridden with the \cb{--archive-build-meta}
option, \ci{build_metadata} has the following form:
\c{\i{cpu}-\i{os}[-\i{langrt}...]}
Where \ci{cpu} is the target CPU (for example, \cb{x86_64} or
\cb{aarch64}; omitted if \cb{--archive-no-cpu} is specified), \ci{os} is
the \cb{ID} and \cb{VERSION_ID} components from \cb{os-release(5)} (or
equivalent, for example, \cb{debian11} or \cb{windows10}; omitted if
\cb{--archive-no-os} is specified), and \ci{langrt} are the language
runtimes as mapped by the \cb{--archive-lang*} options (for example,
\cb{gcc12} or \cb{msvc17.4}).
For example, given the following invocation on Debian 11 running on
\cb{x86_64}:
\
bpkg build libhello
bpkg test libhello
bpkg bindist \
-o /tmp/output/ \
--distribution=archive \
--archive-lang cc=gcc12 \
libhello
\
We will end up with the package archive in the following form:
\
libhello-1.2.3-x86_64-debian11-gcc12.tar.xz
\
The recommended language runtime id format is the runtime name followed
by the version, for example, \cb{gcc12} or \cb{msvc17.4}. Note that its
purpose is not to provide a precise specification of requirements but
rather to help the user of a binary package to pick the appropriate
variant. Refer to the \cb{--archive-lang*} options documentation for
details on the mapping semantics.
Instead of mapping languages individually you can specify entire build
metadata as a single value with the \cb{--archive-build-meta} (it is also
possible to add additional metadata; see the option documentation for
details). For example:
\
bpkg bindist \
-o /tmp/output/ \
--distribution=archive \
--archive-build-meta=x86_64-linux-glibc
libhello
\
This will produce the package archive in the following form:
\
libhello-1.2.3-x86_64-linux-glibc.tar.xz
\
To install the binary package from archive simply unpack it using
\cb{tar} or \cb{zip}. You can use the \cb{--strip-components} \cb{tar}
option to remove the top-level package directory (the same can be
achieved for \cb{zip} archives by using \cb{bsdtar} on Windows). For
example, to unpack the package contents so that they end up in
\cb{/usr/local/}:
\
sudo tar -xf libhello-1.2.3-x86_64-debian11-gcc12.tar.xz \
-C / --strip-components=1
\
If you expect the binary package to be unpacked into a directory other
than its original installation directory (\cb{--archive-install-root}),
then it's recommended to make it relocatable by specifying the
\cb{config.install.relocatable=true} configuration variable. For example:
\
bpkg bindist \
... \
config.install.relocatable=true \
libhello
\
Note that not all source packages support relocatable installation (see
\l{b#install-reloc Rolocatable Installation} for details).
Another mechanism that can useful when generating archive packages is the
ability to filter the files being installed. This, for example, can be
used to create binary packages that don't contain any development-related
files. See \l{b#install-filter Installation Filtering} for details. See
also the \cb{--archive-split} option.
The installation archive package can be generated for a target other than
the host by specifying the target triplet with the \cb{--architecture}
option. In this case the \cb{bpkg} configuration is assumed to be
appropriately configured for cross-compiling to the specified target. You
will also need to explicitly specify the \cb{--archive-install-root}
option (or \cb{--archive-install-config}) as well as the
\cb{--os-release-id} option (and likely want to specify other
\cb{--os-release-*} options). For example, for cross-compiling from Linux
to Windows using the MinGW GCC toolchain:
\
bpkg bindist \
--distribution=archive \
--architecture=x86_64-w64-mingw32 \
--os-release-id=windows \
--os-release-name=Windows \
--os-release-version-id=10 \
--archive-install-root / \
--archive-lang cc=mingw_w64_gcc12 \
...
\
"
"\h#archive-options|PKG-BINDIST ARCHIVE OPTIONS|"
bool --archive-prepare-only
{
"Prepare all the package contents but do not create the binary package
archive, printing its directory instead unless requested to be quiet.
Implies \cb{--keep-output}."
}
strings --archive-type
{
"<ext>",
"Archive type to create specified as a file extension, for example,
\cb{tar.xz}, \cb{tar.gz}, \cb{tar}, \cb{zip}. Repeat this option to
generate multiple archive types. If unspecified, then a default type
appropriate for the target operating system is used, currently \cb{zip}
for Windows and \cb{tar.xz} for POSIX. Note, however, that these
defaults may change in the future."
}
std::multimap<string, string> --archive-lang
{
"<ln>=<rt>",
"Map interface language name <ln> to runtime id <rt>. If no mapping is
found for an interface language in this map, then fallback to the
\cb{--archive-lang-impl} map. If still no mapping is found, then
fail. If the information about an interface language is unimportant and
should be ignored, then empty runtime id can be specified. Note that
the mapping specified with this option is only considered if the
package type is a library (for other package types all languages used
are implementation). Note also that multiple runtime ids specified for
the same language are combined except for an empty id, which is treated
as a request to clear previous entries."
}
std::multimap<string, string> --archive-lang-impl
{
"<ln>=<rt>",
"Map implementation language name <ln> to runtime id <rt>. If no mapping
is found for an implementation language in this map, then assume
the information about this implementation language is unimportant
and ignore it (examples of such cases include static linking as well
as a language runtime that is always present). See \cb{--archive-lang}
for background."
}
bool --archive-no-cpu
{
"Assume the package is CPU architecture-independent and omit it from
the binary package directory name and archive file base."
}
bool --archive-no-os
{
"Assume the package is operating system-independent and omit it from
the binary package directory name and archive file base."
}
string --archive-build-meta
{
"<data>",
"Alternative or additional build metadata to include after the version
in the binary package directory and file names. If the specified value
starts/ends with \cb{+} then the value (with \cb{+} removed) is added
after/before the default metadata. Otherwise it is used as is instead
of the default metadata. If empty value is specified, then no build
metadata is included."
}
dir_path --archive-install-root
{
"<d>",
"Alternative installation root directory. The default is \cb{/usr/local/}
on POSIX and \c{\b{C:\\}\i{project}\b{\\}} on Windows, where
\ci{project} is the \l{bpkg#manifest-package-project \cb{project}}
package manifest value."
}
bool --archive-install-config
{
"Use the installation directory layout (\cb{config.install.*} variables)
as configured instead of overriding them with defaults appropriate for
the target operating system. Note that this includes
\cb{config.install.private} and \cb{config.bin.rpath} if needed for a
private installation. Note also that the \cb{config.install.root} value
is still overridden with the \cb{--archive-install-root} option value
if specified."
}
std::map<string, string> --archive-split
{
"<key>=<filt>",
"Split the installation into multiple binary packages. Specifically,
for each <key>=<filt> pair, perform the \cb{install} operation with
\c{\b{config.install.filter=}\i{filt}} and package the resulting files
as \ci{package-key-version-build_metadata} omitting the \ci{-key} part
if <key> is empty. Note that wildcard patterns in <filt> must be
quoted. See \l{b#install-filter Installation Filtering} for background."
}
};
"
\h|STRUCTURED RESULT|
Instead of printing to \cb{stderr} the list of generated binary packages in
a format more suitable for human consumption, the \cb{pkg-bindist} command
can be instructed to write it to \cb{stdout} in a machine-readable form by
specifying the \cb{--structured-result} option. Currently, the only
recognized format value for this option is \cb{json} with the output being
a JSON object that is a serialized representation of the following C++
struct \cb{bindist_result}:
\
struct os_release
{
string name_id; // ID
vector<string> like_ids; // ID_LIKE
optional<string> version_id; // VERSION_ID
optional<string> variant_id; // VARIANT_ID
optional<string> name; // NAME
optional<string> version_codename; // VERSION_CODENAME
optional<string> variant; // VARIANT
};
struct file
{
string type;
string path;
optional<string> system_name;
};
struct package
{
string name;
string version;
optional<string> system_version;
vector<file> files;
};
struct bindist_result
{
string distribution; // --distribution or auto-detected
string architecture; // --architecture or auto-detected
os_release os_release; // --os-release-* or auto-detected
optional<string> recursive; // --recursive
bool private; // --private
bool dependent_config; // See --allow-dependent-config
package package;
vector<package> dependencies; // Only in --recursive=separate
};
\
For example:
\
{
\"distribution\": \"debian\",
\"architecture\": \"amd64\",
\"os_release\": {
\"name_id\": \"debian\",
\"version_id\": \"11\",
\"name\": \"Debian GNU/Linux\"
},
\"package\": {
\"name\": \"libfoo\",
\"version\": \"2.5.0-b.23\",
\"system_version\": \"2.5.0~b.23-0~debian11\",
\"files\": [
{
\"type\": \"main.deb\",
\"path\": \"/tmp/libfoo_2.5.0~b.23-0~debian11_amd64.deb\",
\"system_name\": \"libfoo\"
},
{
\"type\": \"dev.deb\",
\"path\": \"/tmp/libfoo-dev_2.5.0~b.23-0~debian11_amd64.deb\",
\"system_name\": \"libfoo-dev\"
},
...
]
}
}
\
See the JSON OUTPUT section in \l{bpkg-common-options(1)} for details on
the overall properties of this format and the semantics of the \cb{struct}
serialization.
The \cb{file::type} member is a distribution-specific value that classifies
the file. For the \cb{debian} distribution the possible values are
\cb{main.deb}, \cb{dev.deb}, \cb{doc.deb}, \cb{common.deb},
\cb{dbgsym.deb}, \cb{changes} (\cb{.changes} file), and \cb{buildid}
(\cb{.buildid} file); see \l{bpkg#bindist-mapping-debian-produce Debian
Package Mapping for Production} for background. For the \cb{fedora}
distribution the possible values are \cb{main.rpm}, \cb{devel.rpm},
\cb{static.rpm}, \cb{doc.rpm}, \cb{common.rpm}, and \cb{debuginfo.rpm}; see
\l{bpkg#bindist-mapping-fedora-produce Fedora Package Mapping for
Production} for background. For the \cb{archive} distribution this is the
archive type (\cb{--archive-type}), for example, \cb{tar.xz} or \cb{zip},
potentially prefixed with \ci{key} if the \cb{--archive-split}
functionality is used, for example, \cb{dev.tar.xz}.
The \cb{package::system_version} and/or \cb{file::system_name} members are
absent if not applicable to the distribution. The \cb{file::system_name}
member is also absent if the file is not a binary package (for example,
\cb{.changes} and \cb{.buildid} files in the \cb{debian} distribution).
"
// 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: pkg_bindist_common_options,
pkg_bindist_debian_options,
pkg_bindist_fedora_options,
pkg_bindist_archive_options {};
"
\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
\
"
}
|