File: sbuild.1.in

package info (click to toggle)
sbuild 0.81.2
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, sid
  • size: 1,756 kB
  • sloc: perl: 15,954; sh: 1,413; sql: 797; python: 401; makefile: 306; lisp: 304
file content (1665 lines) | stat: -rw-r--r-- 78,548 bytes parent folder | download
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
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
.\" Copyright © 1998       James Troup <james@nocrew.org>
.\" Copyright © 2005-2009  Roger Leigh <rleigh@debian.org>
.\" Copyright © 2008       Simon McVittie <smcv@debian.org>
.\"
.\" This program is free software: you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation, either version 2 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
.\" General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program.  If not, see
.\" <http://www.gnu.org/licenses/>.
.so defs.man
.TH SBUILD 1 "\*[RELEASE_DATE]" "Version \*[VERSION]" "Debian sbuild"
.SH NAME
sbuild \- build debian packages from source
.SH SYNOPSIS
.B sbuild
.RB [ \-h \[or] \-\-help " \[or] " \-V \[or] \-\-version ]
.RB [ \-v \[or] \-\-verbose " \[or] " \-q \[or] \-\-quiet ]
.RB [ \-D \[or] \-\-debug ]
.RB [ \-A \[or] \-\-arch\-all ]
.RB [ \-\-archive=\fIarchive\fP ]
.RB [ \-d \[or] \-\-dist=\fIdistribution\fP ]
.RB [ \-c \[or] \-\-chroot=\fIchroot\fP ]
.RB [ \-\-chroot-mode=\fIschroot|sudo|autopkgtest|unshare\fP ]
.RB [ \-\-arch=\fIarchitecture\fP ]
.RB [ \-\-arch\-any " \[or] " \-\-no\-arch\-any ]
.RB [ \-\-build=\fIarchitecture\fP ]
.RB [ \-\-host=\fIarchitecture\fP ]
.RB [ \-\-profiles=\fIprofile[,...]\fP ]
.RB [ \-s \[or] \-\-source ]
.RB [ \-\-force\-orig\-source ]
.RB [ \-\-make\-binNMU=\fIchangelog-entry\fP ]
.RB [ \-\-binNMU=\fINMU-version\fP ]
.RB [ \-\-append\-to\-version=\fIstring\fP ]
.RB [ \-\-binNMU\-timestamp=\fItimestamp\fP ]
.RB [ \-\-binNMU\-changelog=\fIchangelog\fP ]
.RB [ \-\-build\-dir=\fIdirectory\fP ]
.RB [ \-\-add-depends=\fIdependency\fP ]
.RB [ \-\-add-conflicts=\fIdependency\fP ]
.RB [ \-\-add-depends\-arch=\fIdependency\fP ]
.RB [ \-\-add-conflicts\-arch=\fIdependency\fP ]
.RB [ \-\-add-depends\-indep=\fIdependency\fP ]
.RB [ \-\-add-conflicts\-indep=\fIdependency\fP ]
.RB [ \-m \[or] \-\-maintainer=\fImaintainer\fP ]
.RB [ \-e \[or] \-\-uploader=\fIuploader\fP ]
.RB [ \-k \[or] \-\-keyid=\fIkey-id\fP ]
.RB [ \-\-source\-only\-changes ]
.RB [ \-\-no\-source\-only\-changes ]
.RB [ \-j \[or] \-\-jobs=\fIn\fP ]
.RB [ \-\-debbuildopt=\fIoption\fP ]
.RB [ \-\-debbuildopts=\fIoptions\fP ]
.RB [ \-\-dpkg-source-opt=\fIoptions\fP ]
.RB [ \-\-dpkg-source-opts=\fIoptions\fP ]
.RB [ \-\-dpkg-file-suffix=\fIsuffix\fP ]
.RB [ \-p \[or] \-\-purge=\fPpurge-mode\fP ]
.RB [ \-\-purge\-build=\fPpurge-mode\fP ]
.RB [ \-\-purge\-deps=\fPpurge-mode\fP ]
.RB [ \-\-purge\-session=\fPpurge-mode\fP ]
.RB [ \-b \[or] \-\-batch]
.RB [ \-n \[or] \-\-nolog ]
.RB [ \-\-clean\-source ]
.RB [ \-\-no\-clean\-source ]
.RB [ \-\-run\-lintian ]
.RB [ \-\-no\-run\-lintian ]
.RB [ \-\-lintian\-opt=\fIoptions\fP ]
.RB [ \-\-lintian\-opts=\fIoptions\fP ]
.RB [ \-\-run\-piuparts ]
.RB [ \-\-no\-run\-piuparts ]
.RB [ \-\-piuparts\-opt=\fIoptions\fP ]
.RB [ \-\-piuparts\-opts=\fIoptions\fP ]
.RB [ \-\-piuparts\-root\-arg=\fIoptions\fP ]
.RB [ \-\-piuparts\-root\-args=\fIoptions\fP ]
.RB [ \-\-run\-autopkgtest ]
.RB [ \-\-no\-run\-autopkgtest ]
.RB [ \-\-autopkgtest\-opt=\fIoptions\fP ]
.RB [ \-\-autopkgtest\-opts=\fIoptions\fP ]
.RB [ \-\-autopkgtest\-root\-arg=\fIoptions\fP ]
.RB [ \-\-autopkgtest\-root\-args=\fIoptions\fP ]
.RB [ \-\-pre\-build\-commands=\fIstring\fP ]
.RB [ \-\-chroot\-setup\-commands=\fIstring\fP ]
.RB [ \-\-chroot\-update\-failed\-commands=\fIstring\fP ]
.RB [ \-\-build\-deps\-failed\-commands=\fIstring\fP ]
.RB [ \-\-starting\-build\-commands=\fIstring\fP ]
.RB [ \-\-finished\-build\-commands=\fIstring\fP ]
.RB [ \-\-build\-failed\-commands=\fIstring\fP ]
.RB [ \-\-chroot\-cleanup\-commands=\fIstring\fP ]
.RB [ \-\-post\-build\-commands=\fIstring\fP ]
.RB [ \-\-post\-build\-failed\-commands=\fIstring\fP ]
.RB [ \-\-anything\-failed\-commands=\fIstring\fP ]
.RB [ \-\-log\-external\-command\-output ]
.RB [ \-\-log\-external\-command\-error ]
.RB [ \-\-setup\-hook=\fIhook-script\fP ]
.RB [ \-\-build\-dep\-resolver=\fIresolver\fP ]
.RB [ \-\-resolve\-alternatives \[or] \-\-no\-resolve\-alternatives ]
.RB [ \-\-extra\-package=\fIpackage.deb\fP ]
.RB [ \-\-extra\-repository=\fIspec\fP ]
.RB [ \-\-extra\-repository\-key=\fIfile.asc\fP ]
.RB [ \-\-build\-path=\fIstring\fP ]
.RB [ \-\-autopkgtest-virt-server=\fIschroot|lxc|chroot|qemu|ssh\fP ]
.RB [ \-\-autopkgtest\-virt\-server\-opt=\fIstring\fP ]
.RB [ \-\-autopkgtest\-virt\-server\-opts=\fIoptions\fP ]
.RB [ \-\-purge\-extra\-packages\fP ]
.RB [ \-\-bd\-uninstallable\-explainer=\fIdose3|apt|none\fP ]
.RB [ PACKAGE [ .dsc ]]
.SH DESCRIPTION
\fBsbuild\fR rebuilds Debian binary packages from the corresponding Debian
source, installing any missing source dependencies.  The build takes place in a
dedicated clean build environment, rather than on the host system. For an
overview of the supported chroot backends see the section \fBCHROOT MODES\fR.
.PP
\fBsbuild\fR can fetch the Debian source over a network, or it can use
locally available sources.
.PP
sbuild is given a packages to process as the argument \fBPACKAGE[.dsc]\fR.
This argument is in the form of either a debianized package source directory, a
source package name along with a version in the form \fIpackage_version\fP, a
source package name, or a .dsc file. If no arguments are given, the current
working directory is passed as an argument.
.PP
For arguments given as source directories, dpkg-source is first run to produce
a source .dsc file. Then, the package is built using the .dsc produced. For
arguments in the form \fIpackage_version\fP or \fIpackage\fP, apt is used to
download the source package. For arguments given as a .dsc file, sbuild builds
the source packages directly. For .dsc files in remote locations, the source
packages are downloaded first, then built.
.PP
It is also possible to run external commands with sbuild. See the section
\fBEXTERNAL COMMANDS\fR for more on this.
.PP
\fBsbuild\fR mails the build logs to a user.  It is configured by the
configuration files \fI/etc/sbuild/sbuild.conf\fP and \fI~/.sbuildrc\fP.  An
example sbuildrc is available in
\fI/usr/share/doc/sbuild/examples/example.sbuildrc\fP.
A custom path to a configuration file can also be specified through setting the
\fBSBUILD_CONFIG\fP environment variable to the path of an additional
configuration file.
.PP
You can build either using a local package with its .dsc file or a
remote one by specifying an explicit dpkg version.
.SH OPTIONS
Options set on the command line overwrite settings made in the configuration
file.
.TP
.BR \-h ", " \-\-help
Display this manual.
.TP
.BR \-V ", " \-\-version
Print version information.
.TP
.BR "\-\-add\-depends=\fIdependency\fP"
.TP
.BR "\-\-add\-conflicts=\fIdependency\fP"
.TP
.BR "\-\-add\-depends\-arch=\fIdependency\fP"
.TP
.BR "\-\-add\-conflicts\-arch=\fIdependency\fP"
.TP
.BR "\-\-add\-depends\-indep=\fIdependency\fP"
.TP
.BR "\-\-add\-conflicts\-indep=\fIdependency\fP"
These options add a build dependencies to the source package being built, in
addition to the build dependency information specified in debian/control.
These dependencies will be concatenated directly to the Build-Depends,
Build-Conflicts, Build-Depends-Arch, Build-Conflicts-Arch, Build-Depends-Indep
and Build-Conflicts-Indep dependencies, respectively.  The options may be used
any number of times to add multiple dependencies.  The format is identical to
the format used in debian/control.
These command line options append to the \fBMANUAL_DEPENDS\fP, \fBMANUAL_CONFLICTS\fP, \fBMANUAL_DEPENDS_ARCH\fP, \fBMANUAL_CONFLICTS_ARCH\fP, \fBMANUAL_DEPENDS_INDEP\fP and \fBMANUAL_CONFLICTS_INDEP\fP configuration variables, respectively. See
.BR sbuild.conf (5)
for more information.
.TP
.BR "\-\-arch=\fIarchitecture\fP"
Build using the architecture specified.  A chroot named
\fI$distribution\-$arch-sbuild\fP or \fI$distribution\-arch\fP is searched for,
in that order of preference.  The chroot must be installed and configured
appropriately to build as that architecture, e.g. using
\fIpersonality=linux32\fP to build i386 packages on an amd64 system.  Note that
this option is equivalent to "\-\-host=architecture \-\-build=architecture".
This command line option sets the \fBHOST_ARCH\fP and \fBBUILD_ARCH\fP configuration variables. See
.BR sbuild.conf (5)
for more information.
.TP
.BR "\-\-host=\fIarchitecture\fP"
Build using the host architecture specified.  If $host and $build don't match, a
chroot named \fI$distribution\-$build\-$host\-sbuild\fP or \fI$distribution\-$build\-$host\fP
is searched for, falling back to \fI$distribution\-$build\-sbuild\fP or
\fI$distribution\-$build\fP, in that order of preference.  This option is only
useful for cross-building when used together with \-\-build.
This command line option sets the \fBHOST_ARCH\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR "\-\-build=\fIarchitecture\fP"
Build using the build architecture specified.  This option is only useful for
cross-building when used together with \-\-host.  If \-\-build is not specified,
the default system architecture is assumed.
This command line option sets the \fBBUILD_ARCH\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-A ", " "\-\-arch\-all"
Also build Architecture: all packages. This option is the opposite of
\-\-no\-arch\-all.
See the section
.BR "BUILD ARTIFACTS"
for more information.
This command line option sets the \fBBUILD_ARCH_ALL\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR "\-\-no\-arch\-all"
Do not build Architecture: all packages. This is the default behaviour. This
option is the opposite of \-\-arch\-all.
See the section
.BR "BUILD ARTIFACTS"
for more information.
This command line option sets the \fBBUILD_ARCH_ALL\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR "\-\-arch\-any"
Build Architecture: any packages. This is the default behavior. This option is
the opposite of \-\-no\-arch\-any.
See the section
.BR "BUILD ARTIFACTS"
for more information.
This command line option sets the \fBBUILD_ARCH_ANY\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR "\-\-no\-arch\-any"
Do not build Architecture: any packages. This option is the opposite
of \-\-arch\-any and only useful when used together with \-\-arch\-all
or \-\-source.
See the section
.BR "BUILD ARTIFACTS"
for more information.
This command line option sets the \fBBUILD_ARCH_ANY\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-b ", " "\-\-batch"
Operate in batchmode, i.e. write a build-progress file during execution
and files on shutdown to facilitate a clean restart.
This command line option sets the \fBBATCH_MODE\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-c ", " "\-\-chroot=\fIchroot\fP"
Specifies the chroot to use. The effect of this option depends on the selected
chroot mode.  With the \fBschroot\fP chroot mode, this option specifies the
schroot name or alias to use. If not specified, the default is the first of
schroot name or alias that matches \fI$distribution\-$arch\-sbuild\fP,
\fI$distribution\-sbuild\fP, \fI$distribution\-$arch\fP or \fI$distribution\fP
that exists.  With the \fBsudo\fP chroot mode, this option specifies the chroot
directory to use.  The directory is either expected in /etc/sbuild/chroot (in
buildd sbuild mode) or in the build directory (see \-\-build\-dir), prefixed with "chroot-" (in
user sbuild mode, the default). If not specified, the default is to search for
a directory in the respective locations named in the same way as for the
schroot mode.  With the \fBunshare\fP chroot mode, if this option is a path,
then it specifies the location of the chroot tarball directly. Otherwise, a
tarball with equal basename from ~/.cache/sbuild will be used. If not
specified, the default is to search for a tarball named in the same way as for
the schroot mode under ~/.cache/sbuild.  With the \fBautopkgtest\fP chroot mode
this option has no effect.  The --autopkgtest-virt-server-opts are used to pick
the chroot in autopkgtest chroot mode.
This command line option sets the \fBCHROOT\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR "\-\-chroot-mode=\fIschroot|sudo|autopkgtest|unshare\fP"
Select the desired chroot mode. Four values are possible: schroot (the
default), sudo (which uses sudo to execute chroot in a directory from
/etc/sbuild/chroot or ./chroot), autopkgtest which uses the autopkgtest-virt-* binaries
(selectable via the \-\-autopkgtest-virt-server option) and unshare (which uses linux
namespaces for chroot and doesn't require superuser privileges).
See the section
.BR "CHROOT MODES"
for more information.
This command line option sets the \fBCHROOT_MODE\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-d ", " "\-\-dist=\fIdistribution\fP"
Explicitly set the distribution for the package build. This will be selecting
the correct chroot to use and also sets the value of the Distribution field in
the created .changes file. Setting this option is necessary when giving sbuild
a .dsc file or a plain source package name to build. In the latter case it
specifies the distribution the source package is fetched from.
This command line option sets the \fBDISTRIBUTION\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-archive=\fIarchive\fP
Communicate with specified archive.
This command line option sets the \fBARCHIVE\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-D ", " "\-\-debug"
Enable debug output.
.TP
.BR "\-\-apt\-clean"
.TQ
.BR "\-\-no\-apt\-clean"
Run (or do not run) apt-get clean in the chroot before executing the build,
overriding the default setting.
This command line option sets the \fBAPT_CLEAN\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR "\-\-apt\-update"
.TQ
.BR "\-\-no\-apt\-update"
Run (or do not run) apt-get update in the chroot before executing the build,
overriding the default setting.
This option has no effect on updating the internal sbuild apt repository, the
repository for extra packages (see --extra-package) and the repositories given
via --extra-repository. These are always updated. Thus, this option only
influences updates of the default repositories of the chroot.
This command line option sets the \fBAPT_UPDATE\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR "\-\-apt\-upgrade"
.TQ
.BR "\-\-no\-apt\-upgrade"
Run (or do not run) apt-get upgrade in the chroot before executing the build,
overriding the default setting.
This command line option sets the \fBAPT_UPGRADE\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR "\-\-apt\-distupgrade"
.TQ
.BR "\-\-no\-apt\-distupgrade"
Run (or do not run) apt-get distupgrade in the chroot before executing the build,
overriding the default setting.
This command line option sets the \fBAPT_DISTUPGRADE\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-m ", " "\-\-maintainer=\fImaintainer\fP"
Specify the identity to use for GPG signing packages, and also used as the
maintainer for binary NMUs.  This does not normally require setting (it
defaults to the uploader).
This command line option sets the \fBMAINTAINER_NAME\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-e ", " "\-\-uploader=\fIuploader\fP"
Passed to dpkg\-genchanges and is used to set the Changed\-by: field in
the .changes file(s).
This command line option sets the \fBUPLOADER_NAME\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-k ", " "\-\-keyid=\fIkey-id\fP"
Passed to debsign and is used to set the key to sign the .changes
file(s).  Default is not using any key and not signing the .changes file(s).
This command line option sets the \fBKEY_ID\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-source\-only\-changes
.TQ
.BR "\-\-no\-source\-only\-changes
In addition to the .changes file generated by dpkg-buildpackage, also produce
(or don't produce) a .changes file suitable for a source-only upload. If
requested by \-\-keyid, this .changes file will also be signed by debsign.
This command line option sets
the \fBSOURCE_ONLY_CHANGES\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-j ", " "\-\-jobs=\fIn\fP"
Number of jobs to run simultaneously.  Passed through to dpkg\-buildpackage.
This command line option appends the appropriate \fB-j\fP option to the \fBDPKG_BUILDPACKAGE_USER_OPTIONS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-debbuildopt=\fIoption\fP
Pass the specified option directly to dpkg\-buildpackage in addition to the
options already passed by sbuild. This option can be passed multiple times
(once per dpkg-buildpackage option) and can be freely mixed with the
\-\-debbuildopts option. Options will be passed to dpkg-buildpackage in the
order that the \-\-debbuildopt and \-\-debbuildopts options are given on the
command line.
This command line option appends to the \fBDPKG_BUILDPACKAGE_USER_OPTIONS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-debbuildopts=\fIoptions\fP
Pass the specified options directly to dpkg\-buildpackage in addition to the
options already passed by sbuild. The argument will be split by whitespaces and
the resulting array passed to the dpkg\-buildpackage invocation. If any options
contain spaces, use \-\-debbuildopt for them.  This option can be passed
multiple times and can be freely mixed with the \-\-debbuildopt option. Options
will be passed to dpkg\-buildpackage in the order that the \-\-debbuildopt and
\-\-debbuildopts options are given on the command line.
This command line option appends to the \fBDPKG_BUILDPACKAGE_USER_OPTIONS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-dpkg\-source\-opt=\fIoptions\fP
Pass the specified option directly to dpkg-source in addition to the options
already passed by sbuild. This is only used when creating a source package from
a Debianized source directory. This option can be passed multiple times (once
per dpkg-source option) and can be freely mixed with the \-\-dpkg\-source\-opts
option. Options will be passed to dpkg-source in the order that the
\-\-dpkg\-source\-opt and \-\-dpkg\-source\-opts options are given on the
command line.
This command line option appends to the \fBDPKG_SOURCE_OPTIONS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.br
\fBNOTE:\fR The '\fI-b\fP', '\fI--before-build\fP' and '\fI--after-build\fP'
options will always be passed to dpkg-source, respectively.
.TP
.BR \-\-dpkg\-source\-opts=\fIoptions\fP
Pass the specified options directly to dpkg\-source in addition to the options
already passed by sbuild. The argument will be split by whitespaces and the
resulting array passed to the dpkg\-source invocation. This is only used when
creating a source package from a Debianized source directory. If any options
contain spaces, use \-\-dpkg\-source\-opt for them.  This option can be passed
multiple times and can be freely mixed with the \-\-dpkg\-source\-opt option.
Options will be passed to dpkg\-source in the order that the
\-\-dpkg\-source\-opt and \-\-dpkg\-source\-opts options are given on the
command line.
This command line option appends to the \fBDPKG_SOURCE_OPTIONS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.br
\fBNOTE:\fR The '\fI-b\fP', '\fI--before-build\fP' and '\fI--after-build\fP'
options will always be passed to dpkg-source, respectively.
.TP
.BR "\-\-dpkg-file-suffix=\fIsuffix\fP"
Add the suffix to the filename of the changes and buildinfo files generated by
dpkg.
.br
\fBNOTE:\fR This option is ignored if dpkg-dev in the build environment is too
old to support it. At least dpkg-dev 1.18.11 is required.
.TP
.BR "\-\-mail\-log\-to=\fIemail-address\fP"
Send the build log to the specified email address.
This command line option sets the \fBMAILTO\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR "\-\-mailfrom=\fIemail-address\fP"
Email address used as the sender address for build logs.
This command line option sets the \fBMAILFROM\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-n ", " "\-\-nolog"
Do not create a package log file in the \fI$log_dir\fP directory and no build
log file, but print everything to stdout. Also do not send any log mails.
This command line option sets the \fBNOLOG\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-profiles=\fIprofile[,...]\fP"
Specify the profile(s) we build, as a comma-separated list. Defaults to the
space separated list of profiles in the \fBDEB_BUILD_PROFILES\fP environment
variable when building natively or the \fBcross\fP and \fBnocheck\fP profiles
when cross-building.
This command line option sets the \fBBUILD_PROFILES\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-p ", " "\-\-purge=\fIpurge-mode\fP"
Convenience option to set \fIpurge-mode\fR for build directory, build
dependencies and session.
This command line option sets the \fBPURGE_BUILD_DEPS\fP, \fBPURGE_BUILD_DIRECTORY\fP and \fBPURGE_SESSION\fP configuration variables. See
.BR sbuild.conf (5)
for more information.
.TP
.BR "\-\-purge\-build=\fIpurge-mode\fP"
\fIpurge-mode\fR determines if the build directory will be deleted after a
build. Possible values are \fBalways\fR (default), \fBnever\fR, and
\fBsuccessful\fR.
This command line option sets the \fBPURGE_BUILD_DIRECTORY\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR "\-\-purge\-deps=\fIpurge-mode\fP"
\fIpurge-mode\fR determines if the build dependencies will be removed after a
build. Possible values are \fBalways\fR (default), \fBnever\fR, and
\fBsuccessful\fR.
This command line option sets the \fBPURGE_BUILD_DEPS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR "\-\-purge\-session=\fIpurge-mode\fP"
Purge the schroot session following a build.  This is useful in conjunction
with the \fI\-\-purge\-build\fP and \fI\-\-purge\-deps\fP options when using
snapshot chroots, since by default the snapshot will be deleted.  Possible
values are \fBalways\fR (default), \fBnever\fR, and \fBsuccessful\fR.
This command line option sets the \fBPURGE_SESSION\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-s ", " "\-\-source"
Build the source package in addition to the other requested build artifacts. By
default, the dsc will not be rewritten because the source package is the input
to sbuild, not its output. Even when running from an unpacked source tree
sbuild will first build the source package using dpkg-source and then pass that
on to the sbuild machinery. Use this option only when you know what you are
doing. This will rewrite the original dsc passed to sbuild.
See the section
.BR "BUILD ARTIFACTS"
for more information.
This command line option sets the \fBBUILD_SOURCE\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR "\-\-no-source"
Don't rebuild the source package. This is the default. It is the opposite of
\-\-source.
See the section
.BR "BUILD ARTIFACTS"
for more information.
This command line option sets the \fBBUILD_SOURCE\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR "\-\-force\-orig\-source"
When used with in conjunction with \-s, this option forces the inclusion of the
orig.tar.gz file in the generated .changes file, even in cases where it would
not normally be included, i.e. use dpkg\-buildpackage \-sa.
This command line option sets the \fBFORCE_ORIG_SOURCE\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR "\-\-use\-snapshot"
Installs the latest snapshot gcc compiler from the \fIgcc-snapshot\fP package,
and alters the build environment to use the snapshot compiler for the build.
Specifically, this option appends \fI/usr/lib/gcc-snapshot/lib\fP to the value
of the \fBLD_LIBRARY_PATH\fP configuration variable and
\fI/usr/lib/gcc-snapshot/bin\fP to the value of the \fBPATH\fP configuration
variable.  It also sets the \fBGCC_SNAPSHOT\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-v ", " "\-\-verbose"
Be verbose, i.e. all information goes to stdout as well as to the log files.
.TP
.BR \-q ", " "\-\-quiet"
Be quiet.  This is the opposite of \-\-verbose.
.TP
.BR "\-\-make\-binNMU=\fIchangelog-entry\fP"
With this option, \fBsbuild\fR will create a new changelog entry in
debian/changelog of every package built. The version number will be in the
format for binary-only NMUs (see \-\-binNMU); the maintainer is set to the
maintainer name configured for \fBsbuild\fR. \fIchangelog-entry\fR will be used
as the changelog entry following \[lq]Binary-only non-maintainer upload for
ARCH -- no source changes\[rq]. Please note that the versions in the
\fIPACKAGE_VERSION[.dsc]\fR arguments still have to be the unmodified (non-NMU
ones) so that the sources can be found. The version number in log files and
mails will be modified by \fBsbuild\fR automatically.
The \-\-append\-to\-version option has a similar effect but allows one to
specify an arbitrary version suffix instead of a custom changelog entry. To
have a custom version suffix and a custom changelog entry, use \-\-make\-binNMU
and \-\-append\-to\-version at the same time with \-\-binNMU=0.
This option is incompatible with \-\-binNMU\-changelog.
This option implies --no-arch-all.
This command line option sets the \fBBIN_NMU\fP configuration variable and sets the \fBBIN_NMU_VERSION\fP configuration variable to 1 if it was not set yet, for example by the --binNMU option. See
.BR sbuild.conf (5)
for more information.
.TP
.BR "\-\-binNMU=\fINMU-version\fP"
The version number of the binary NMU.  This option only has an effect if
combined with \-\-make\-binNMU and/or with \-\-append\-to\-version.
\fIversion\fP is a single number for the (+b\fIn\fR) format
used for binary NMUs.
If the argument is the empty string or zero, then the +b\fIn\fR suffix will not
be appended.
The +b\fIn\fR suffix will be appended after the string given via \-\-append\-to\-version.
This option is incompatible with \-\-binNMU\-changelog.
This command line option sets the \fBBIN_NMU_VERSION\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR "\-\-append\-to\-version=\fIstring\fP"
This option is similar to \-\-make\-binNMU except that it allows the user to
specify an arbitrary string to be appended to the version number (immediately
before the '+' in the Debian revision if \-\-make\-binNMU is also provided).
To pass an arbitrary changelog text as well, combine this option with
\-\-make\-binNMU but be aware that this will also add the +b\fIn\fR suffix
unless you also pass \-\-binNMU=0 to disable it.
This option is incompatible with \-\-binNMU\-changelog.
This option implies --no-arch-all.
This command line option sets the \fBAPPEND_TO_VERSION\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR "\-\-binNMU\-timestamp=\fItimestamp\fP"
Set the timestamp of the new binNMU changelog entry. By default, the time of
the build will be used to generate the binNMU changelog timestamp. This option
allows one to use a custom timestamp instead. The timestamp is either given as
an integer in Unix time or as a string in the format compatible with Debian
changelog entries (i.e. as it is generated by date -R).
This option is incompatible with \-\-binNMU\-changelog.
This command line option sets the \fBBIN_NMU_TIMESTAMP\fP configuration
variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR "\-\-binNMU\-changelog=\fIchangelog\fP"
Set the complete content of a binary-only changelog entry. This option allows
full customization of the new changelog entry. It is up to the user to make
sure that the changelog entry is well-formed. The argument has to include
all necessary newlines. Leading and trailing newlines will be stripped.
Sbuild will not interpret any backslash escapes.
This option is incompatible with \-\-make\-binNMU, \-\-binNMU,
\-\-append\-to\-version and \-\-binNMU\-timestamp.
This command line option sets the \fBBIN_NMU_CHANGELOG\fP configuration
variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR "\-\-build\-dir=\fIdirectory\fP"
Set the output directory for the build artifacts created by dpkg-buildpackage
and the log file. By default, the current directory is used or, when sbuild is
executed from within an unpacked source directory, the parent directory.
This command line option sets the \fBBUILD_DIR\fP configuration
variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-clean\-source
When executing sbuild from within an unpacked source tree, execute the
debian/rules clean target. This is the default and might require some of the
build dependencies installed on the host.
This command line option sets the \fBCLEAN_SOURCE\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-no\-clean\-source
When executing sbuild from within an unpacked source tree, do not run the
debian/rules clean target before building the source package. Only set this if
you start from a clean checkout and you know what you are doing.
This command line option sets the \fBCLEAN_SOURCE\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-run\-lintian
Run lintian after a successful build.
This command line option sets the \fBRUN_LINTIAN\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-no\-run\-lintian
Don't run lintian after a successful build.  If sbuild is configured to run
lintian by default, this option will prevent lintian being run.
This command line option sets the \fBRUN_LINTIAN\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-lintian\-opt=\fIoptions\fP
Pass the specified option directly to lintian in addition to the options
already passed by sbuild. This option can be passed multiple times (once per
lintian option) and can be freely mixed with the \-\-lintian\-opts option.
Options will be passed to lintian in the order that the \-\-lintian\-opt and
\-\-lintian\-opts options are given on the command line.
This command line option appends to the \fBLINTIAN_OPTIONS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-lintian\-opts=\fIoptions\fP
Pass the specified options directly to lintian in addition to the options
already passed by sbuild. The argument will be split by whitespaces and the
resulting array passed to the lintian invocation. If any options contain
spaces, use \-\-lintian\-opt for them.  This option can be passed multiple
times and can be freely mixed with the \-\-lintian\-opts option. Options will
be passed to lintian in the order that the \-\-lintian\-opt and
\-\-lintian\-opts options are given on the command line.
This command line option appends to the \fBLINTIAN_OPTIONS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-run\-piuparts
Run piuparts after a successful build.
This command line option sets the \fBRUN_PIUPARTS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-no\-run\-piuparts
Don't run piuparts after a successful build.  If sbuild is configured to run
piuparts by default, this option will prevent piuparts being run.
This command line option sets the \fBRUN_PIUPARTS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-piuparts\-opt=\fIoptions\fP
Pass the specified option directly to piuparts in addition to the options
already passed by sbuild. This option can be passed multiple times (once per
piuparts option) and can be freely mixed with the \-\-piuparts\-opts option.
Options will be passed to piuparts in the order that the \-\-piuparts\-opt and
\-\-piuparts\-opts options are given on the command line.
Certain percent escapes are supported. To write a literal percent sign, escape
it with another percent sign. See the section
.BR "OPTION STRING PERCENT ESCAPES"
for more information.
This command line option appends to the \fBPIUPARTS_OPTIONS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-piuparts\-opts=\fIoptions\fP
Pass the specified options directly to piuparts in addition to the options
already passed by sbuild. The argument will be split by whitespaces and the
resulting array passed to the piuparts invocation. If any options contain
spaces, use \-\-piuparts\-opt for them.  This option can be passed multiple
times and can be freely mixed with the \-\-piuparts\-opts option. Options will
be passed to piuparts in the order that the \-\-piuparts\-opt and
\-\-piuparts\-opts options are given on the command line.
Certain percent escapes are supported. To write a literal percent sign, escape
it with another percent sign. See the section
.BR "OPTION STRING PERCENT ESCAPES"
for more information.
This command line option appends to the \fBPIUPARTS_OPTIONS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-piuparts\-root\-arg=\fIoptions\fP
Add an argument that is used to launch piuparts as root. Without this option,
the default is to use "sudo --" to launch piuparts. If an empty string is
supplied, then piuparts is launched without any prefixed command.  This option
can be specified multiple times.  This command line option appends to the
\fBPIUPARTS_ROOT_ARGS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-piuparts\-root\-args=\fIoptions\fP
Add arguments that are used to launch piuparts as root.  Without this option,
the default is to use "sudo --" to launch piuparts. If an empty string is
supplied, then piuparts is launched without any prefixed command.  The argument
will be split by whitespaces. To pass options containing whitespaces use the
option \-\-piuparts\-root\-arg.  This command line option appends to the
\fBPIUPARTS_ROOT_ARGS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-run\-autopkgtest
Run autopkgtest after a successful build.  This command line option sets the
\fBRUN_AUTOPKGTEST\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-no\-run\-autopkgtest
Don't run autopkgtest after a successful build.  If sbuild is configured to run
autopkgtest by default, this option will prevent autopkgtest being run.  This
command line option sets the \fBRUN_AUTOPKGTEST\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-autopkgtest\-opt=\fIoptions\fP
Pass the specified option directly to autopkgtest in addition to the options
already passed by sbuild. This option can be passed multiple times (once per
autopkgtest option) and can be freely mixed with the \-\-autopkgtest\-opts
option.  Options will be passed to autopkgtest in the order that the
\-\-autopkgtest\-opt and \-\-autopkgtest\-opts options are given on the command
line.
Certain percent escapes are supported. To write a literal percent sign, escape
it with another percent sign. See the section
.BR "OPTION STRING PERCENT ESCAPES"
for more information.
This command line option appends to the \fBAUTOPKGTEST_OPTIONS\fP
configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-autopkgtest\-opts=\fIoptions\fP
Pass the specified options directly to autopkgtest in addition to the options
already passed by sbuild. The argument will be split by whitespaces and the
resulting array passed to the autopkgtest invocation. If any options contain
spaces, use \-\-autopkgtest\-opt for them.  This option can be passed multiple
times and can be freely mixed with the \-\-autopkgtest\-opts option. Options
will be passed to autopkgtest in the order that the \-\-autopkgtest\-opt and
\-\-autopkgtest\-opts options are given on the command line.
Certain percent escapes are supported. To write a literal percent sign, escape
it with another percent sign. See the section
.BR "OPTION STRING PERCENT ESCAPES"
for more information.
This command line
option appends to the \fBAUTOPKGTEST_OPTIONS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-autopkgtest\-root\-arg=\fIoptions\fP
Add an argument that is used to launch autopkgtest as root. Without this
option, the default is to use "sudo --" to launch autopkgtest. If an empty
string is supplied, then autopkgtest is launched without any prefixed command.
This option can be specified multiple times.  This command line option appends
to the
\fBAUTOPKGTEST_ROOT_ARGS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-autopkgtest\-root\-args=\fIoptions\fP
Add arguments that are used to launch autopkgtest as root.  Without this
option, the default is to use "sudo --" to launch autopkgtest. If an empty
string is supplied, then autopkgtest is launched without any prefixed command.
The argument will be split by whitespaces. To pass options containing
whitespaces use the option \-\-autopkgtest\-root\-arg.  This command line
option appends to the \fBAUTOPKGTEST_ROOT_ARGS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-pre\-build\-commands=\fIstring\fP
This is the earliest external command which is run right after the chroot
session has been initialized and before anything else is done (like installing
the build dependencies). The command is run outside of the chroot. This option
can be used multiple times to add multiple commands. Certain percent escapes
are supported. To write a literal percent sign, escape it with another percent
sign. See the section
.BR "EXTERNAL COMMANDS"
for more information.
This command line option appends to the \fBEXTERNAL_COMMANDS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-chroot\-setup\-commands=\fIstring\fP
Run these commands after the chroot and variables have been setup but before
dependencies are installed. The command is run as root inside of the chroot.
This option can be used multiple times to add multiple commands. Certain
percent escapes are supported. To write a literal percent sign, escape it with
another percent sign. See the
section
.BR "EXTERNAL COMMANDS"
for more information.
This command line option appends to the \fBEXTERNAL_COMMANDS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-chroot\-update\-failed\-commands=\fIstring\fP
Run these commands after any of 'apt-get update', 'apt-get upgrade' or 'apt-get
dist-upgrade' failed.
This hook is not run for updates of the internal sbuild apt repository, the
repository for extra packages (see --extra-package) and the repositories given
via --extra-repository.
The environment is intact, and the failure can be
investigated. Especially %SBUILD_SHELL is useful here. This option can be used
multiple times to add multiple commands. Certain percent escapes are supported.
To write a literal percent sign, escape it with another percent sign.See the
section
.BR "EXTERNAL COMMANDS"
for more information.
This command line option appends to the \fBEXTERNAL_COMMANDS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-build\-deps\-failed\-commands=\fIstring\fP
These commands are run if installing the build dependencies has failed directly
after the failed attempt. The environment is intact, and the failure can be
investigated.  Especially %SBUILD_SHELL is useful here. The command is run as
root inside the chroot. This option can be used multiple times to add multiple
commands. Certain percent escapes are supported. To write a literal percent
sign, escape it with another percent sign. See the section
.BR "EXTERNAL COMMANDS"
for more information.
This command line option appends to the \fBEXTERNAL_COMMANDS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-starting\-build\-commands=\fIstring\fP
Run these commands after dependencies are installed, just before the package
build with dpkg-buildpackage starts. The command is run as the root user
inside the chroot. This option can be used multiple times to add
multiple commands. Certain percent escapes are supported. To write a literal
percent sign, escape it with another percent sign. See the section
.BR "EXTERNAL COMMANDS"
for more information.
This command line option appends to the \fBEXTERNAL_COMMANDS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-finished\-build\-commands=\fIstring\fP
Run these commands immediately after the timed package build finishes.  The
command is run as the root user inside the chroot.  This
option can be used multiple times to add multiple commands. Certain percent
escapes are supported. To write a literal percent sign, escape it with another
percent sign. See the section
.BR "EXTERNAL COMMANDS"
for more information.
This command line option appends to the \fBEXTERNAL_COMMANDS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-build\-failed\-commands=\fIstring\fP
These commands are run if dpkg-buildpackage has failed directly after the
failed attempt. The environment is intact, and the failure can be investigated.
Especially %SBUILD_SHELL is useful here. The command is run as the root
user inside the chroot. This option can be used multiple times
to add multiple commands. Certain percent escapes are supported. To write a
literal percent sign, escape it with another percent sign. See the section
.BR "EXTERNAL COMMANDS"
for more information.
This command line option appends to the \fBEXTERNAL_COMMANDS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-chroot\-cleanup\-commands=\fIstring\fP
Run these commands when a chroot is cleaned up, before build directory is
purged.  The command is run as root inside the chroot. This option can be used
multiple times to add multiple commands. Certain percent escapes are supported.
To write a literal percent sign, escape it with another percent sign. See the
section
.BR "EXTERNAL COMMANDS"
for more information.
This command line option appends to the \fBEXTERNAL_COMMANDS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-post\-build\-commands=\fIstring\fP
Run this command after a successful build. The command is run outside of the
chroot. This option can be used multiple times to add multiple commands.
Certain percent escapes are supported. To write a literal percent sign, escape
it with another percent sign. See the section
.TP
.BR \-\-post\-build\-failed\-commands=\fIstring\fP
Exactly like the above, but when a build fails.
.BR "EXTERNAL COMMANDS"
for more information.
This command line option appends to the \fBEXTERNAL_COMMANDS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-anything\-failed\-commands=\fIstring\fP
Run these commands for all the \fI\-\-xxx\-failed\-commands\fP options.
Especially %SBUILD_SHELL is useful here. This option can be used multiple times
to add multiple commands. Certain percent escapes are supported. To write a
literal percent sign, escape it with another percent sign. See the section
.BR "EXTERNAL COMMANDS"
for more information.
This command line option appends to the \fBEXTERNAL_COMMANDS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-log\-external\-command\-output
Write output from external commands to the build log.
This command line option sets the \fBLOG_EXTERNAL_COMMAND_OUTPUT\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-log\-external\-command\-error
Write error output from external commands to the build log.
This command line option sets the \fBLOG_EXTERNAL_COMMAND_ERROR\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR "\-\-setup\-hook=\fIhook-script\fP" " " \fBDEPRECATED\fP
This option is deprecated. Use of this option will add \fIhook-script\fP to the
external commands to run via \fIchroot-setup-commands\fP.
This command line option sets the \fBCHROOT_SETUP_SCRIPT\fP configuration variable and appends to the \fBEXTERNAL_COMMANDS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR "\-\-build\-dep\-resolver=\fIresolver\fP"
Use the specified resolver to handle selecting the build dependencies.
Supported resolvers are \fIapt\fP (the default), \fIaptitude\fP, \fIaspcud\fP,
\fIxapt\fP, and \fInull\fP.  The apt resolver is the most appropriate resolver
for most users, for building for unstable, stable and other distributions.  If
alternative build dependencies are used (excluding architecture restrictions),
only the first alternative will be used; the others will be ignored.  The
aptitude resolver is very similar, but smarter and slower, and it will consider
all alternatives by default; it is suited to more complex situations, such as
building packages for the experimental distribution, where packages need
installing from multiple suites (\fIunstable\fP and \fIexperimental\fP).  Due
to performance and other issues (bug #139615), aptitude is not recommended for
use by default.  If the dependency situation is so complex that neither apt nor
aptitude are able to find a solution, then you can use the aspcud resolver.
This resolver uses apt-cudf to ask aspcud, a real solver (in the math sense),
to find a solution to the installation problem. Since aspcud uses a real solver
(an ASP solver) it will always find a solution if one exists. The solution
found by the aspcud resolver can be refined by changing the default
optimization criteria through the --aspcud-criteria option.  The xapt resolver
is intended only for cross-building, and is a temporary transitional feature
which will be removed following the complete introduction of multi-arch
support. Finally, the null resolver is a dummy solver which does not install,
upgrade or remove any packages. This allows one to completely control package
installation via hooks.
This command line option sets the \fBBUILD_DEP_RESOLVER\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-aspcud\-criteria=\fIcriteria\fP
Optimization criteria in extended MISC 2012 syntax passed to aspcud through
apt-cudf.  Optimization criteria are separated by commas, sorted by decreasing
order of priority and are prefixed with a polarity (+ to maximize and - to
minimize).  The default criteria is \fB-removed,-changed,-new\fP which first
minimizes the number of removed packages, then the number of changed packages
(up or downgrades) and then the number of new packages. A common task is to
minimize the number of packages from experimental.  To do this you can add a
criteria like \fB-count(solution,APT-Release:=/a=experimental/)\fP to the
default criteria.  This will then minimize the number of packages in the
solution which contain the string \fIa=experimental\fP in the \fIAPT-Release\fP
field of the EDSP output created by apt. For more help on how to write
optimization criteria, see the
.BR apt-cudf (1)
man page. Specifically the help on the --criteria option.
This command line option sets the \fBASPCUD_CRITERIA\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-resolve\-alternatives
Allow the use of alternatives in Build-Depends, Build-Depends-Arch and
Build-Depends-Indep.  This is the default for the aptitude dependency resolver.
This command line option sets the \fBRESOLVE_ALTERNATIVES\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-no\-resolve\-alternatives
Do not allow the use of alternatives in Build-Depends, Build-Depends-Arch and
Build-Depends-Indep.  Note that alternatives for the same package
(e.g. different versions) are still allowed.  This is the default for the
apt and xapt dependency resolvers.
This command line option sets the \fBRESOLVE_ALTERNATIVES\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-extra\-package=\fIpackage.deb|directory\fP
Make \fIpackage.deb\fP available for build-dependency resolution, by
adding it to a temporary archive created by sbuild.  This makes it
easier to build packages against locally-built build dependencies,
without waiting for those packages to enter the main archive, or going
through the hassle of maintaining a local archive and making it
accessible inside the chroot.  \fIpackage.deb\fP is copied into the
chroot, so it can refer to any path on the host system.
If a directory is passed instead of a regular file, then all regular files
inside that directory with a filename that ends in \fI.deb\fP will be added in
the same fashion as it is done for individual packages.
This option can be specified multiple times.
This command line option appends to the \fBEXTRA_PACKAGES\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-extra\-repository=\fIspec\fP
Add a repository to the list of apt sources during the package build.
The repository specification is a line suitable for an apt
.BR sources.list (5)
file. For instance, you might use
.nh
.B \-\-extra\-repository="deb http://deb.debian.org/debian experimental main"
.hy
to allow packages in the experimental distribution to fulfill
build-dependencies. Note that the build chroot must already trust the
key of this repository or a key must be given with the
.nh
.B \-\-extra\-repository-key
.hy
flag (see
.BR apt-secure (8)).
This command line option appends to the \fBEXTRA_REPOSITORIES\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-extra\-repository-key=\fIfile.asc\fP
Add \fIfile.asc\fP to the list of trusted keys inside the chroot. The key is
read from the filename given, and added to the trusted keys. For more
information, see
.BR apt-secure (8).
This flag is particularly useful if the target in
.nh
.B --extra-repository
.hy
is not signed
with a key that's trusted by the base chroot.
This command line option appends to the \fBEXTRA_REPOSITORY_KEYS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-build\-path=\fIstring\fP
By default the package is built in a path of the following format
/build/packagename-XXXXXX/packagename-version/ where XXXXXX is a random ascii
string. This option allows one to specify a custom path where the package is
built inside the chroot. The sbuild user in the chroot must have permissions to
create the path. Common writable locations are subdirectories of /tmp or
/build. Using /tmp might be dangerous, because (depending on the chroot
mode) the /tmp inside the chroot might be a world writable location that can
be accessed by processes outside the chroot. The directory /build can only be
accessed by the sbuild user and group and should be a safe location.  The
buildpath must be an empty directory because the last component of the path
will be removed after the build is finished.  Notice that depending on the
chroot mode (see --chroot-mode), some locations inside the chroot might be
bind mounts that are shared with other sbuild instances. You must avoid using
these shared locations as the build path or otherwise concurrent runs of sbuild
will likely fail. With the default schroot chroot mode, the directory /build
is shared between multiple schroot sessions. You can change this behaviour in
/etc/schroot/sbuild/fstab. The behaviour of other chroot modes will vary.
This command line option sets the \fBBUILD_PATH\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-autopkgtest-virt-server=\fIschroot|lxc|chroot|qemu|ssh\fP
The autopkgtest virtualization server. Can be specified with or without the autopkgtest-virt-
prefix.  For instance, the following set of command line options will use the
autopkgtest-virt-schroot chroot mode for a package build:
.nh
.B \-\-chroot-mode=autopkgtest \-\-autopkgtest\-virt\-server=schroot \-\-autopkgtest-virt-server-opt=unstable-amd64-sbuild
.hy
This command line option sets the \fBAUTOPKGTEST_VIRT_SERVER\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-autopkgtest-virt-server-opt=\fIstring\fP
Pass the specified option directly to the respective autopkgtest-virt-* virtualization
server in addition to the options already passed by sbuild. This option can be
passed multiple times (once per autopkgtest-virt-* option) and can be freely mixed with
the \-\-autopkgtest-virt-server\-opts option.  Options will be passed to the respective
autopkgtest-virt-* virtualization server in the order that the \-\-autopkgtest-virt-server\-opt
and \-\-autopkgtest-virt-server\-opts options are given on the command line.  See the
manual pages of the respective autopkgtest-virt-* commands for more information.
Certain percent escapes are supported. To write a literal percent sign, escape
it with another percent sign. See the section
.BR "OPTION STRING PERCENT ESCAPES"
for more information.
This command line option appends to the \fBAUTOPKGTEST_VIRT_SERVER_OPTIONS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-autopkgtest\-virt\-server\-opts=\fIoptions\fP
Pass the specified options directly to the respective autopkgtest-virt-* virtualization
server in addition to the options already passed by sbuild. The argument will
be split by whitespaces and the resulting array passed to the autopkgtest-virt-*
invocation. If any options contain spaces, use \-\-autopkgtest\-virt\-server\-opt for
them.  This option can be passed multiple times and can be freely mixed with
the \-\-autopkgtest\-virt\-server\-opts option. Options will be passed to the
respective autopkgtest-virt-* virtualization server in the order that the
\-\-autopkgtest\-virt\-server\-opt and \-\-autopkgtest\-virt\-server\-opts options are given on
the command line. See the manual pages of the respective autopkgtest\-virt\-* commands
for more information.
Certain percent escapes are supported. To write a literal percent sign, escape
it with another percent sign. See the section
.BR "OPTION STRING PERCENT ESCAPES"
for more information.
This command line option appends to the \fBAUTOPKGTEST_VIRT_SERVER_OPTIONS\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-sbuild-mode=\fImode\fP
Behaviour changes for use in a buildd environment.
This command line option sets the \fBSBUILD_MODE\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-stats\-dir=\fIdirectory\fP
Directory for writing build statistics to.
This command line option sets the \fBSTATS_DIR\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-purge\-extra\-packages\fP
This is an experimental option. Only use when you know what you are doing.
Source packages must be buildable with only their build dependencies, all
packages marked as Essential:yes, the build-essential package and their
transitive dependencies installed. But by default, most chroots will also
include Priority:required packages and apt as well as their transitive
dependencies. This option will try to remove all additional packages that are
not strictly required for the build right after build dependencies were
installed. This currently works best with the aspcud resolver. The apt resolver
will not make as much effort to remove all unneeded packages and will keep all
providers of a virtual package and all packages from any dependency alternative
that happen to be installed. The aptitude and xapt resolver do not implement
this feature yet. The removed packages are not (yet) added again after the
build finished. This can have undesirable side effects like lintian not working
(because there is no apt to install its dependencies) or bare chroots becoming
totally unusable after apt was removed from them. Thus, this option should only
be used with throw-away chroots like schroot provides them where the original
state is automatically restored after each build. This command line option sets
the \fBPURGE_EXTRA_PACKAGES\fP configuration variable. See
.BR sbuild.conf (5)
for more information.
.TP
.BR \-\-bd\-uninstallable\-explainer=\fIdose3|apt|none\fP
If the build dependencies cannot be satisfied by the chosen resolver, sbuild
will run the selected method to give a better explanation why the build
dependencies cannot be installed. Possible arguments for this option are dose3
(the default), apt and none. To disable this feature, pass none or the empty string.
Depending on the resolver, the dose3 explainer might report a dependency
situation as satisfiable even if the chosen resolver found it to be
unsatisfiable. This is especially likely to happen if the apt resolver (the
default) is used. Such disparities can have two reasons: either the
understanding of the involved dependency situation of the apt and dose3 solver
differs (this is a bug) or the apt solver was unable to find a solution if the
dependency situation is not trivial (for example if it involves packages from
multiple repositories). In the former case, please report the disparity as a
bug against the resolvers. In the latter case, use a resolver that is more
likely to find a solution like the aptitude or aspcud resolvers. Especially the
aspcud resolver should find a solution if and only if the dose3 solver also
finds one. This command line option sets the \fBBD_UNINSTALLABLE_EXPLAINER\fP
configuration variable. See
.BR sbuild.conf (5)
for more information.
.SH CHROOT MODES
The main purpose of sbuild is to build Debian packages in a clean chroot
environment. Provisioning and managing these chroot environments is not done by
sbuild itself but by multiple backends. The default backend (or chroot mode) is
schroot which is an suid binary that allows regular users to enter a chroot
environment. But sbuild also allows one to build packages in a qemu virtual
machine, lxc, lxd or on a remote host reached by ssh using the autopkgtest
backend. The backend can be chosen using the \f[CB]--chroot-mode\fP command
line argument or the \fI$chroot_mode\fP configuration parameter.
.TP
.BR schroot
The default and recommended chroot mode. It is also used on Debian buildd
machines.  The easiest way to set up sbuild for use with the schroot backend is
by using sbuild-createchroot which will also write out the necessary schroot
configuration files in /etc. To use the chroots, the current user has to be
added to the sbuild group, for example by running sbuild-adduser.  Updating
these schroot backends can be done using sbuild-update. See the respective man
pages for more information about how to use these programs.  Schroot supports
chroots from directories, tarballs, filesystem images and block devices.
Schroot provides ephemeral chroots either by unpacking a tarball into a
temporary directory, by using an overlay filesystem for directory chroots or by
using btrfs or lvm snapshots. Chroots usable by schroot are defined by
configuration files in /etc/schroot/chroot.d/. When building for a specific
distribution and architecture, sbuild will choose the chroot that is named (or
has the alias) \fI$distribution\-$arch-sbuild\fP, \fI$distribution\-sbuild\fP,
\fI$distribution\-$arch\fP or \fI$distribution\fP, in that order of preference.
The used chroot name can be overridden using the \-c or \-\-chroot options.
.TP
.BR sudo
This chroot mode is deprecated and only provided for backwards compatibility
and testing purposes. It operates by plainly entering the chosen chroot
directory using "sudo chroot". Thus, this backend also does not provide
ephemeral chroots. The sudo chroot mode searches for a symlink or directory
located at \fI/etc/sbuild/chroot/\fP or in the current directory, prefixed with
\fIchroot\-\fP. The expected names are resolved in the same order as for the
schroot chroot mode and can be overridden using the \-c or \-\-chroot options.
.TP
.BR autopkgtest
This is an experimental chroot mode that allows one to build packages in any
chroot supported by autopkgtest. This allows one to build packages in lxc or
lxd containers, a qemu virtual machine or on a remote host via ssh. Which
autopkgtest server to use is determined via the
\f[CB]--autopkgtest-virt-server\fP option. Since autopkgtest (in contrast to
schroot) does not maintain a registry of available containers or (virtual)
machines, it is necessary to manually specify them using the
\f[CB]--autopkgtest-virt-server-opts=\fP command line argument. To avoid having
to manually type the right container or machine name every time when sbuild is
executed, percent escapes are permitted.
.TP
.BR unshare
This is an experimental backend that allows one to build packages inside
chroots provided by arbitrary tarballs. This allows one to set up an arbitrary
build environment without having to become root. Building packages with schroot
also doesn't require sudo (schroot is suid root) but setting up and updating
chroots requires superuser permissions. The unshare backend only makes use of
two small suid binaries (newuidmap and newgidmap) and only requires root once
for enabling unprivileged userns clones (Debian carries a patch against the
Linux kernel that disables this feature by default). So after setting
kernel.unprivileged_userns_clone=1 /etc/sysctl.d/, this backend allows
arbitrary tarballs containing chroot environments to be used for package
building. The default tarball location is in ~/.cache/sbuild/. The expected
names are resolved in the same order as for the schroot chroot mode and can be
overridden using the \-c or \-\-chroot options.
.SH BUILD ARTIFACTS
Sbuild is meant to be used to build architecture specific binary packages from
a given source package. In addition, sbuild is also able to generate
architecture independent binary packages as well as to rebuild the original
source package that was used as input. In summary, sbuild is able to build
architecture specific binary packages, architecture independent binary packages
and source packages. What ends up being built is determined by the
configuration variables \fBBUILD_ARCH_ANY\fR, \fBBUILD_ARCH_ALL\fR and
\fBBUILD_SOURCE\fR, respectively. See
.BR sbuild.conf (5)
for a detailed explanation of these configuration variables.
.PP
By default, during native compilation, \fBBUILD_ARCH_ANY\fR and
\fBBUILD_ARCH_ALL\fR are set to true while \fBBUILD_SOURCE\fR is set to false.
During cross-compilation, \fBBUILD_ARCH_ALL\fR defaults to false.  This
behaviour can be changed either by using command line options or by modifying
the configuration variables in your \fI~/.sbuildrc\fP. The relevant command
line options to change the values of \fBBUILD_ARCH_ANY\fR, \fBBUILD_ARCH_ALL\fR
and \fBBUILD_SOURCE\fR are \f[CB]--arch-any/--no-arch-any\fP,
\f[CB]--arch-all/--no-arch-all\fP and \f[CB]--source/--no-source\fP,
respectively.
.PP
The values of \fBBUILD_ARCH_ANY\fR, \fBBUILD_ARCH_ALL\fR and \fBBUILD_SOURCE\fR
change the parameter that dpkg-buildpackage is called with. The following table
displays the argument passed to dpkg-buildpackage in the last column depending
on the configuration options in the first three columns.
.PP
.if t \{\
.ft CW
\}
.TS
l l l l.
\fBBUILD_ARCH_ANY\fR	\fBBUILD_ARCH_ALL\fR	\fBBUILD_SOURCE\fR	dpkg-buildpackage flag
_
false	false	false	invalid
false	false	true	-S
false	true	false	-A
false	true	true	-g
true	false	false	-B
true	false	true	-G
true	true	false	-b
true	true	true	no option
.TE
.if t \{\
.in
.ft P
\}
.SH EXTERNAL COMMANDS
Support to run external commands during an sbuild run is provided. A set of
external commands can be run at various stages of a build. Providing commands to
run is done through the appropriate options given on the command line and
through the use of the configuration files. In the configuration file, the list
of commands to run are placed in a hash of arrays of arrays of strings
corresponding to the commands to run.
.PP
There are several sets of commands. All command are run inside the chroot as
root except for the  \fIpre/post\-build\-\fP commands which are run as the user
running sbuild outside of the chroot. To run an external command as another
user than the root user, prefix your command with \fIrunuser -u sbuild --\fP.
.PP
Here is a summary of the ordering, user, internal/external to chroot for each
command hook
.PP
The following table shows each command hook in the context of the tasks sbuild
performs. The column \fIroot\fP shows whether the command is run as root (yes)
or not (no).  The column \fIchroot\fP shows whether the command is run inside
our outside the chroot. The working directory inside the chroot is the one
marked with \f[CB]<<BUILDDIR>>\fR inside the log. By default, this is a
directory of the format \f[CB]/build/packagename-XXXXXX/\f[R] where
\f[CB]XXXXXX\fR is a random ascii string.  Otherwise, it is the directory set
by \f[CB]--build-path\fR or by the \f[CB]BUILD_PATH\fR configuration option.
The working directory outside of the chroot is $HOME. The remaining columns
show the percent escapes that are defined in each command.  Percent escapes
that are available in all commands (\fB%%\fR, \fB%a\fR, \fB%b\fR, \fB%s\fR) are
omitted.  The value \fImaybe\fP in the column for the \fB%d\fR and \fB%p\fR
escapes means that the value can not relied upon to be defined in these stages.
More specifically, these escapes will not be defined at these points if the
user specified a source package name without a version on the command line. In
that case, the version will only become known after the source package has been
retrieved in the "Fetch and unpack source package" stage.
.PP
.if t \{\
.ft CW
\}
.TS
l l l l l l.
command/action	root	chroot	%c	%e	%d,%p
_
Initialise chroot session
\f[CB]\-\-pre\-build\-commands\fP	no	outside	no	yes	maybe
Setup the chroot and variables
\f[CB]\-\-chroot\-setup\-commands\fP	yes	inside	no	no	maybe
Update and upgrade packages
\f[CB]\-\-chroot\-update\-failed\-commands\fP	yes	inside	no	no	maybe
Fetch and unpack source package
Install Dependencies
\f[CB]\-\-build\-deps\-failed\-commands\fP	yes	inside	no	no	yes
\f[CB]\-\-starting\-build\-commands\fP	yes	inside	no	no	yes
Run dpkg-buildpackage
\f[CB]\-\-build\-failed\-commands\fP	yes	inside	no	no	yes
\f[CB]\-\-finished\-build\-commands\fP	yes	inside	no	no	yes
Run lintian (if configured)
\f[CB]\-\-chroot\-cleanup\-commands\fP	yes	inside	yes	no	yes
Cleanup build files and dependencies
Run piuparts (if configured)
Run autopkgtest (if configured)
Close schroot session
\f[CB]\-\-post\-build\-commands\fP	no	outside	yes	yes	yes
\f[CB]\-\-post\-build\-failed\-commands\fP	no	outside	yes	yes	yes
.TE
.if t \{\
.in
.ft P
\}
.PP
The commands can be given in the configuration files. They can be given as
strings or as a list of arguments. For example, to run "foo" and "bar" with
arguments before a build starts, specifying the "foo" command as a list and
"bar" as a string, one could do this:
.PP
\f[CB]$external_commands = {\fP
.br
\f[CB]    "pre-build-commands" => [\fP
.br
\f[CB]        ['foo', 'arg1', 'arg2'],\fP
.br
\f[CB]        'bar arg1 arg2 arg3',\fP
.br
\f[CB]    ],
.br
\f[CB]};\fP
.PP
Hash keys for commands to run at other stages have the same name as their
corresponding command-line option name without the preceding '--'.
.PP
Here's an example of how to do the same with the previous example, except using
the \fI\-\-pre\-build\-commands\fP option.
.PP
\f[CB]$ sbuild \\\fP
.br
\f[CB]      \-\-pre\-build\-commands='foo arg1 arg2' \\\fP
.br
\f[CB]      \-\-pre\-build\-commands='bar arg1 arg2 arg3'\fP
.PP
Note that all these commands are executed through the shell in "/bin/sh". If
specifying the command as a list in the config file, very few shell facilities
are supported: no redirection, no command concatenation with ; and so on. When
passing a string (in the config file or on the commandline), the string is
passed as-is to the shell. So all shell facilities are available, given that
you escape everything properly, as you would in an interactive shell.
.PP
Besides running external commands, sbuild can also detect the use of certain
percent escapes given as arguments. These are used to allow for a command to be
supplied with a certain argument depending on the escape given.
For example, it could be possible to have an external command be given the
path to a .changes file.
.PP
Here is a listing of keywords and a description of what it's converted to.
.TP
\fB%%\fR
Used to escape a '\fI%\fP'.
.TP
\fB%d\fR, \fB%SBUILD_DSC\fR
These escapes are converted to the absolute path to a package's .dsc file.
.TP
\fB%c\fR, \fB%SBUILD_CHANGES\fR
These escapes are converted to the absolute path to a package's source .changes
file. This is the .changes file generated by the dpkg-buildpackage invocation
and not the source-only .changes file that might've been produced additionally
via --source-only-changes. This variable is only set after the build is
finished, i.e in \f[CB]\-\-chroot\-cleanup\-commands\fP,
\f[CB]\-\-post\-build\-commands\fP, and
\f[CB]\-\-post\-build\-failed\-commands\fP.
.TP
\fB%a\fR, \fB%SBUILD_HOST_ARCH\fR
These escapes are converted to the debian name of the architecture the build 
is being built for (e.g amd64, armhf).
.TP
\fB%e\fR, \fB%SBUILD_CHROOT_EXEC\fR
These escapes are converted to a command which can be executed on a host and
can be given arguments which will then be executed inside the chroot. Standard
input and output of the process started inside the chroot are connected to the
program executed on the host. Thus, this command can also be used to copy data
into the chroot and out of the chroot. The working directory of the process
started inside the chroot is the root directory of the chroot. The process is
started as the root user.  This variable is not set if the external command is
run inside the chroot.  Thus this escape is only available for
\f[CB]\-\-pre\-build\-commands\fP,
\f[CB]\-\-post\-build\-commands\fP, and
\f[CB]\-\-post\-build\-failed\-commands\fP.
.TP
\fB%b\fR, \fB%SBUILD_BUILD_DIR\fR
These escapes are converted to the absolute path to the build directory inside
the chroot.
.TP
\fB%p\fR, \fB%SBUILD_PKGBUILD_DIR\fR
These escapes are converted to the absolute path to the package build directory
inside the chroot.
.TP
\fB%s\fR, \fB%SBUILD_SHELL\fR
This is converted to a command to spawn an interactive "bash" shell
.TP
\fB%SBUILD_BUILD_ARCH\fR
This escape is converted to the Debian name of the architecture that the build
is being run on (e.g amd64, armhf).
.PP
Percent escapes are only substituted when an appropriate value is defined for
them. At other times, it is left unchanged. In practice this means that there
are only two escapes that are not available in all external commands: \fB%c\fR
and \fB%e\fR. For example, a .changes file is only defined at the end of a
build, so using \fI%c\fR will only be substituted for post-build-commands and post-build-failed-commands.
.PP
Here's an example of using an escape to run a program foo on a .changes file
after a build is done.
.PP
\f[CB]$ sbuild \-\-post\-build\-commands \\\fP
.br
\f[CB]      'foo %SBUILD_CHANGES'\fP
.PP
And here's an example that will spawn an interactive shell to investigate the
problem whenever the build failed:
.PP
\f[CB]$ sbuild \-\-build\-failed\-commands '%SBUILD_SHELL'\fP
.PP
The following example would copy a file from the host into the chroot:
.PP
\f[CB]$ sbuild \-\-pre\-build\-commands \\\fP
.br
\f[CB]      'cat blub.txt | %SBUILD_CHROOT_EXEC sh -c "cat > blub.txt"'\fP
.PP
One final note, external commands are processed in the order they are given.
Also, the commands given in a configuration file are processed first, then the
commands given through the command line options.
.SH OPTION STRING PERCENT ESCAPES
Besides for external command strings, percent escapes can also be used in
custom options passed to piuparts, autopkgtest and the chosen autopkgtest-virt server.
This is for example useful for communicating the right chroot backend to
piuparts or autopkgtest depending on the distribution or architecture the
source package was built for.
.PP
Here is a listing of keywords and a description of what it's converted to.
.TP
\fB%%\fR
Used to escape a '\fI%\fP'.
.TP
\fB%a\fR, \fB%SBUILD_HOST_ARCH\fR
These escapes are converted to the debian name of the architecture the build 
is being built for (e.g amd64, armhf).
.TP
\fB%r\fR, \fB%SBUILD_DISTRIBUTION\fR
The distribution that the source package was built for. This is the value
recorded in debian/changelog or the value passed via the --dist option.
Mnemonic: the \fBr\fR is the first letter in "release".
.PP
Here is an example that will run piuparts with the right schroot chroot:
.PP
\f[CB]$ sbuild \-\-run\-piuparts \\\fP
.br
\f[CB]      \-\-piuparts\-opts="--schroot=%r-%a-sbuild"
.PP
Or an example of running autopkgtest with the right schroot chroot:
.PP
\f[CB]$ sbuild \-\-run\-autopkgtest \-\-autopkgtest-root-args= \\\fP
.br
\f[CB]      \-\-autopkgtest\-opts="-- schroot %r-%a-sbuild"
.PP
To achieve the same effect via the configuration file, add the following:
.PP
\f[CB]$autopkgtest_root_args = '';\fP
.br
\f[CB]$piuparts_opts = [ '--schroot=%r-%a-sbuild' ];\fP
.br
\f[CB]$autopkgtest_opts = [ '--', 'schroot', '%r-%a-sbuild' ];\fP
.PP
The --autopkgtest-root-args option and the $autopkgtest_root_args configuration
variable are set to the empty string because the default is to run autopkgtest
with "sudo --" in front of it which is not needed with the schroot autopkgtest
backend.
.PP
.SH LOCAL ARCHIVE
The apt and aptitude resolvers create a local archive for installing build
dependencies.  This is an internal implementation detail of the build
dependency resolver, which is not user configurable, and is intended to be
entirely transparent to the user.  The local archive exists only transiently
during the package build.  It does not persist across builds, and it is only
used to store the dummy dependency packages created for a single build.
.PP
The dependency resolvers do the following:
.IP \[bu]
Create a dummy dependency package.  This contains the Build-Depends (and
optionally Build-Depends-Arch and Build-Depends-Indep) as Depends, and
Build-Conflicts (and optionally Build-Conflicts-Arch and Build-Conflicts-Indep)
as Conflicts.
.IP \[bu]
Install the dummy dependency package into the local archive,
.IP \[bu]
Generate the \fIPackages\fP, \fISources\fP and \fIRelease\fP files.
.IP \[bu]
Write a \fIsources.list\fP file for the local archive into
\fI/etc/apt/sources.list.d\fP.
.IP \[bu]
Inject the lists directly into \fI/var/lib/apt/lists\fP.  This step is to save
running updating all apt sources which is undesirable during a build; apt and
aptitude do not support updating a single source at present.
.IP \[bu]
Regenerate the apt caches to ensure everything is in sync.
.IP \[bu]
Install the dummy dependency package with apt or aptitude; the dummy package is
pulled from the local apt archive, while all its dependencies are pulled from
the regular configured apt sources.
.PP
At the end of the build, the local archive is removed, along with the rest of
the build tree.
.SH EXAMPLES
Before you use sbuild for the first time, you have to do some setup depending
on the chroot mode you are using. The default chroot mode is schroot. To use
sbuild with the schroot backend, you need to add your user to the sbuild group
and create a schroot chroot. The latter can be accomplished by using
sbuild-createchroot(8). After this one time setup,
you can now use sbuild to build packages like this:
.PP
\f[CR]% \f[CB]sbuild \-d unstable bash\fP\fP
.PP
Or on a .dsc:
.PP
\f[CR]% \f[CB]sbuild \-d unstable bash.dsc\fP\fP
.PP
Or from within an unpacked source package (the -d parameter is not necessary
here because the distribution is inferred from debian/changelog):
.PP
\f[CR]% \f[CB]sbuild\fP\fP
.SH ENVIRONMENT VARIABLES
The following environment variables are used by \fBsbuild\fR:
.IP "HOME"
The home directory of the user.
.IP "LOGNAME"
Used in lockfiles.
.IP "SBUILD_CONFIG"
Path to an additional configuration file on top of the system wide and user
specific ones.
.SH FILES
.TP
.I /etc/sbuild/sbuild.conf
Configuration, maintained by the system administrator.  This may be used to
override the defaults.
.TP
.I /etc/sbuild/chroot
Directory containing symbolic links to chroots.  This is only used for sudo
chroot access; schroot access uses the schroot chroot configuration.
.TP
.I ~/.sbuildrc
User-specific configuration. A custom path to a configuration file can also be
specified through setting the \fBSBUILD_CONFIG\fP environment variable to the
path of an additional configuration file.
.TP
.I /var/lib/sbuild
Build trees, archive signing keys, build statistics and lock files.
.SH AUTHORS
Roman Hodek <Roman.Hodek@informatik.uni\-erlangen.de>.
.PP
\fBsbuild\fR is based on debbuild, written by James Troup
<james@nocrew.org> and has been modified by
.nf
Ben Collins <bcollins@debian.org>,
Ryan Murray <rmurray@debian.org>,
Francesco Paolo Lovergine <frankie@debian.org>,
Michael Banck <mbanck@debian.org>, and
Roger Leigh <rleigh@debian.org>
.fi
.SH COPYRIGHT
.nf
Copyright \[co] 1998-2000 Roman Hodek <roman\@hodek.net>
Copyright \[co] 1998-1999 James Troup <troup\@debian.org>
Copyright \[co] 2003-2006 Ryan Murray <rmurray\@debian.org>
Copyright \[co] 2001-2003 Rick Younie <younie\@debian.org>
Copyright \[co] 2003-2004 Francesco Paolo Lovergine <frankie\@debian.org>
Copyright \[co] 2005      Michael Banck <mbanck\@debian.org>
Copyright \[co] 2005-2009 Roger Leigh <rleigh\@debian.org>
.fi
.SH "SEE ALSO"
.BR sbuild.conf (5),
.BR sbuild\-abort (1),
.BR sbuild\-adduser (8),
.BR sbuild\-apt (1),
.BR sbuild\-checkpackages (1),
.BR sbuild\-createchroot (8),
.BR sbuild\-distupgrade (1),
.BR sbuild\-hold (1),
.BR sbuild\-setup (7).
.BR sbuild\-shell (1),
.BR sbuild\-unhold (1),
.BR sbuild\-update (1),
.BR sbuild\-upgrade (1),
.BR schroot (1),
.\"#
.\"# The following sets edit modes for GNU EMACS
.\"# Local Variables:
.\"# mode:nroff
.\"# fill-column:79
.\"# End: