summaryrefslogtreecommitdiffstats
path: root/debhelper.pod
blob: 9b00ec7ea8df405a498e77fc72dc9ba66156a6a6 (plain)
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
=encoding UTF-8

=head1 NAME

debhelper - the debhelper tool suite

=head1 SYNOPSIS

B<dh_>I<*> [B<-v>] [B<-a>] [B<-i>] [B<--no-act>] [B<-p>I<package>] [B<-N>I<package>] [B<-P>I<tmpdir>]

=head1 DESCRIPTION

Debhelper is used to help you build a Debian package. The philosophy behind
debhelper is to provide a collection of small, simple, and easily
understood tools that are used in F<debian/rules> to automate various common
aspects of building a package. This means less work for you, the packager.
It also, to some degree means that these tools can be changed if Debian
policy changes, and packages that use them will require only a rebuild to
comply with the new policy.

A typical F<debian/rules> file that uses debhelper will call several debhelper
commands in sequence, or use L<dh(1)> to automate this process. Examples of
rules files that use debhelper are in F</usr/share/doc/debhelper/examples/>

To create a new Debian package using debhelper, you can just copy one of
the sample rules files and edit it by hand. Or you can try the B<dh-make>
package, which contains a L<dh_make|dh_make(1)> command that partially
automates the process. For a more gentle introduction, the B<maint-guide> Debian 
package contains a tutorial about making your first package using debhelper.

Except where the tool explicitly denotes otherwise, all of the debhelper
tools assume that they run from the root directory of an unpacked source
package.  This is so they can locate find files like F<debian/control>
when needed.

=head1 DEBHELPER COMMANDS

Here is the list of debhelper commands you can use. See their man
pages for additional documentation.

=over 4

#LIST#

=back

=head2 Deprecated Commands

A few debhelper commands are deprecated and should not be used.

=over 4

#LIST_DEPRECATED#

=back

=head2 Other Commands

If a program's name starts with B<dh_>, and the program is not on the above
lists, then it is not part of the debhelper package, but it should still
work like the other programs described on this page.

=head1 DEBHELPER CONFIG FILES

Many debhelper commands make use of files in F<debian/> to control what they
do. Besides the common F<debian/changelog> and F<debian/control>, which are
in all packages, not just those using debhelper, some additional files can
be used to configure the behavior of specific debhelper commands. These
files are typically named debian/I<package>.foo (where I<package> of course,
is replaced with the package that is being acted on).

For example, B<dh_installdocs> uses files named F<debian/package.docs> to list
the documentation files it will install. See the man pages of individual
commands for details about the names and formats of the files they use.
Generally, these files will list files to act on, one file per line. Some
programs in debhelper use pairs of files and destinations or slightly more
complicated formats.

Note for the first (or only) binary package listed in
F<debian/control>, debhelper will use F<debian/foo> when there's no
F<debian/I<package>.foo> file.  However, it is often a good idea to keep
the F<I<package>.> prefix as it is more explicit.  The primary exception
to this are files that debhelper by default installs in every binary
package when it does not have a package prefix (such as
F<debian/copyright> or F<debian/changelog>).

In some rare cases, you may want to have different versions of these files
for different architectures or OSes. If files named debian/I<package>.foo.I<ARCH>
or debian/I<package>.foo.I<OS> exist, where I<ARCH> and I<OS> are the same as the
output of "B<dpkg-architecture -qDEB_HOST_ARCH>" /
"B<dpkg-architecture -qDEB_HOST_ARCH_OS>",
then they will be used in preference to other, more general files.

Mostly, these config files are used to specify lists of various types of
files. Documentation or example files to install, files to move, and so on.
When appropriate, in cases like these, you can use standard shell wildcard
characters (B<?> and B<*> and B<[>I<..>B<]> character classes) in the files.
You can also put comments in these files; lines beginning with B<#> are
ignored.

The syntax of these files is intentionally kept very simple to make them
easy to read, understand, and modify.

=head2 Substitutions in debhelper config files

In compatibility level 13 and later, it is possible to use simple
substitutions in debhelper config files for the following tools:

=over 4

=item *

dh_clean

=item *

dh_install

=item *

dh_installcatalogs

=item *

dh_installdeb

=item *

dh_installdirs

=item *

dh_installdocs

=item *

dh_installexamples

=item *

dh_installinfo

=item *

dh_installman

=item *

dh_installwm

=item *

dh_link

=item *

dh_missing

=item *

dh_ucf

=back

All substitution variables are of the form I<${foo}> and the braces
are mandatory.  Variable names are case-sensitive and consist of
alphanumerics (a-zA-Z0-9), hyphens (-), underscores (_), and colons (:).
The first character must be an alphanumeric.

If you need a literal dollar sign that cannot trigger a substitution,
you can either use the B<${Dollar}> substitution or the sequence B<${}>.

The following expansions are available:

=over 4

=item B<DEB_HOST_*>, B<DEB_BUILD_*>, B<DEB_TARGET_*>

Expands to the relevant L<dpkg-architecture(1)> value (similar to
I<dpkg-architecture -qVARIABLE_HERE>).

When in doubt, the B<DEB_HOST_*> variant is the one that will work both
for native and cross builds.

For performance reasons, debhelper will attempt to resolve these
names from the environment first before consulting
L<dpkg-architecture(1)>.  This is mostly mentioned for completeness
as it will not matter for most cases.

=item B<Dollar>

Expands to a single literal B<$>-symbol.  This symbol will I<never>
be considered part of a substitution variable.  That is:

   # Triggers an error
   ${NO_SUCH_TOKEN}
   # Expands to the literal value "${NO_SUCH_TOKEN}"
   ${Dollar}{NO_SUCH_TOKEN}

This variable equivalent to the sequence B<${}> and the two can be
used interchangeably.

=item B<Newline>, B<Space>, B<Tab>

Expands to a single ASCII newline, space and tab respectively.

This can be useful if you need to include a literal whitespace
character (e.g. space) where it would otherwise be stripped or
used as a separator.

=item B<< env:I<NAME> >>

Expands to the environment variable I<NAME>.  The environment
variable must be set (but can be set to the empty string).

=back

Note that all variables must expand to a defined value.  As an example,
if debhelper sees I<${env:FOO}>, then it will insist that the environment
variable I<FOO> is set (it can be set to the empty string).

=head3 Substitution limits

To avoid infinite loops and resource exhaustion, debhelper will stop
with an error if the text contains many substitution variables (50) or
they expand beyond a certain size (4096 characters or 3x length of
the original input - whichever is bigger).

=head2 Executable debhelper config files

If you need additional flexibility, many of the debhelper tools
(e.g. L<dh_install(1)>) support executing a config file as a script.

To use this feature, simply mark the config file as executable
(e.g. B<< chmod +x debian/I<package>.install >>) and the tool will
attempt to execute it and use the output of the script.  In many
cases, you can use L<dh-exec(1)> as interpreter of the config file to
retain most of the original syntax while getting the additional
flexibility you need.


When using executable debhelper config files, please be aware of the
following:

=over 4

=item *

The executable config file B<must> exit with success (i.e. its return
code should indicate success).

=item *

In compatibility level 13+, the output will be subject to substitutions
(see L</Substitutions in debhelper config files>) where the tool
support these.  Remember to be careful if your generator I<also> provides
substitutions as this can cause unnecessary confusion.

Otherwise, the output will be used exactly as-is.  Notably, debhelper
will I<not> expand wildcards or strip comments or strip whitespace
in the output.

=back

If you need the package to build on a file system where you cannot
disable the executable bit, then you can use L<dh-exec(1)> and its
B<strip-output> script.

=head1 SHARED DEBHELPER OPTIONS

The following command line options are supported by all debhelper programs.

=over 4

=item B<-v>, B<--verbose>

Verbose mode: show all commands that modify the package build directory.

=item B<--no-act>

Do not really do anything. If used with -v, the result is that the command
will output what it would have done.

=item B<-a>, B<--arch>

Act on architecture dependent packages that should be built for the
B<DEB_HOST_ARCH> architecture.

=item B<-i>, B<--indep>

Act on all architecture independent packages.

=item B<-p>I<package>, B<--package=>I<package>

Act on the package named I<package>. This option may be specified multiple
times to make debhelper operate on a given set of packages.

=item B<-s>, B<--same-arch>

Deprecated alias of B<-a>.

This option is removed in compat 12.

=item B<-N>I<package>, B<--no-package=>I<package>

Do not act on the specified package even if an B<-a>, B<-i>, or B<-p> option lists
the package as one that should be acted on.

=item B<--remaining-packages>

Do not act on the packages which have already been acted on by this debhelper
command earlier (i.e. if the command is present in the package debhelper log).
For example, if you need to call the command with special options only for a
couple of binary packages, pass this option to the last call of the command to
process the rest of packages with default settings. 

=item B<-P>I<tmpdir>, B<--tmpdir=>I<tmpdir>

Use I<tmpdir> for package build directory. The default is debian/I<package>

=item B<--mainpackage=>I<package>

This little-used option changes the package which debhelper considers the
"main package", that is, the first one listed in F<debian/control>, and the
one for which F<debian/foo> files can be used instead of the usual
F<debian/package.foo> files.

=item B<-O=>I<option>|I<bundle>

This is used by L<dh(1)> when passing user-specified options to all the
commands it runs. If the command supports the specified option or option
bundle, it will take effect. If the command does not support the option (or
any part of an option bundle), it will be ignored.

=back

=head1 COMMON DEBHELPER OPTIONS

The following command line options are supported by some debhelper programs.
See the man page of each program for a complete explanation of what each
option does.

=over 4

=item B<-n>

Do not modify F<postinst>, F<postrm>, etc. scripts.

=item B<-X>I<item>, B<--exclude=>I<item>

Exclude an item from processing. This option may be used multiple times,
to exclude more than one thing. The I<item> is typically part of a
filename, and any file containing the specified text will be excluded.

=item B<-A>, B<--all>

Makes files or other items that are specified on the command line take effect
in ALL packages acted on, not just the first.

=back

=head1 BUILD SYSTEM OPTIONS

The following command line options are supported by all of the B<dh_auto_>I<*>
debhelper programs. These programs support a variety of build systems,
and normally heuristically determine which to use, and how to use them.
You can use these command line options to override the default behavior.
Typically these are passed to L<dh(1)>, which then passes them to all the 
B<dh_auto_>I<*> programs.

=over 4

=item B<-S>I<buildsystem>, B<--buildsystem=>I<buildsystem>

Force use of the specified I<buildsystem>, instead of trying to auto-select
one which might be applicable for the package.

Pass B<none> as I<buildsystem> to disable auto-selection.

=item B<-D>I<directory>, B<--sourcedir=>I<directory>, B<--sourcedirectory=>I<directory>

Assume that the original package source tree is at the specified
I<directory> rather than the top level directory of the Debian
source package tree.

B<Warning>: The B<--sourcedir> variant matches a similar named option in
B<dh_install> and B<dh_missing> (etc.) for historical reasons.  While they
have a similar name, they have very distinct purposes and in some cases
it can cause errors when this variant is passed to B<dh> (when then passes
it on to all tools).

=item B<-B>[I<directory>], B<--builddir>[I<=directory>], B<--builddirectory>[I<=directory>]

Enable out of source building and use the specified I<directory> as the build
directory. If I<directory> parameter is omitted, a default build directory
will be chosen.

If this option is not specified, building will be done in source by default
unless the build system requires or prefers out of source tree building.
In such a case, the default build directory will be used even if
B<--builddirectory> is not specified.

If the build system prefers out of source tree building but still
allows in source building, the latter can be re-enabled by passing a build
directory path that is the same as the source directory path.

=item B<--parallel>, B<--no-parallel>

Control whether parallel builds should be used if underlying build
system supports them.  The number of parallel jobs is controlled by
the B<DEB_BUILD_OPTIONS> environment variable (L<Debian Policy,
section 4.9.1>) at build time. It might also be subject to a build
system specific limit.

If neither option is specified, debhelper currently defaults to
B<--parallel> in compat 10 (or later) and B<--no-parallel> otherwise.

As an optimization, B<dh> will try to avoid passing these options to
subprocesses, if they are unnecessary and the only options passed.
Notably this happens when B<DEB_BUILD_OPTIONS> does not have a
I<parallel> parameter (or its value is 1).

=item B<--max-parallel=>I<maximum>

This option implies B<--parallel> and allows further limiting the number of
jobs that can be used in a parallel build. If the package build is known to
only work with certain levels of concurrency, you can set this to the maximum
level that is known to work, or that you wish to support.

Notably, setting the maximum to 1 is effectively the same as using
B<--no-parallel>.

=item B<--reload-all-buildenv-variables>

By default, L<dh(1)> will compute several environment (e.g. by using
L<dpkg-buildflags(1)>) and cache them to avoid having all B<dh_auto_*>
tool recompute them.

When passing this option, the concrete B<dh_auto_*> tool will ignore
the cache from L<dh(1)> and retrigger a rebuild of these variables.
This is useful in the very rare case where the package need to do
multiple builds but with different B<...FLAGS> options.  A concrete
example would be needing to change the B<-O> parameter in B<CFLAGS> in
the second build:

    export DEB_CFLAGS_MAINT_APPEND=-O3

    %:
        dh $@

    override_dh_auto_configure:
        dh_auto_configure -Bbuild-deb ...
        DEB_CFLAGS_MAINT_APPEND=-Os dh_auto_configure \
           --reload-all-buildenv-variables -Bbuild-udeb ...

Without B<--reload-all-buildenv-variables> in the second call to
L<dh_auto_configure(1)>, the change in B<DEB_CFLAGS_MAINT_APPEND>
would be ignored as L<dh_auto_configure(1)> would use the cached value
of B<CFLAGS> set by L<dh(1)>.

This option is only available with B<< debhelper (>= 12.7~) >> when
the package uses compatibility level 9 or later.

=item B<--list>, B<-l>

List all build systems supported by debhelper on this system. The list
includes both default and third party build systems (marked as such). Also
shows which build system would be automatically selected, or which one
is manually specified with the B<--buildsystem> option.

=back

=head1 COMPATIBILITY LEVELS

From time to time, major non-backwards-compatible changes need to be made
to debhelper, to keep it clean and well-designed as needs change and its
author gains more experience. To prevent such major changes from breaking
existing packages, the concept of debhelper compatibility levels was 
introduced. You must tell debhelper which compatibility level it should use, and
it modifies its behavior in various ways.

In current debhelper, you can specify the compatibility level in
F<debian/control> by adding a Build-Depends on the debhelper-compat package.
For example, to use v#RECOMMENDED_COMPAT# mode, ensure F<debian/control> has:

  Build-Depends: debhelper-compat (= #RECOMMENDED_COMPAT#)

This also serves as an appropriate versioned build dependency on a sufficient
version of the debhelper package, so you do not need to specify a separate
versioned build dependency on the debhelper package unless you need a specific
point release of debhelper (such as for the introduction of a new feature or
bugfix within a compatibility level).

Note that debhelper does not provide debhelper-compat for experimental or beta
compatibility levels; packages experimenting with those compatibility levels
should use F<debian/compat> or B<DH_COMPAT>.

Prior versions of debhelper required specifying the compatibility level in the
file F<debian/compat>, and current debhelper still supports this for backward
compatibility, though a package may not specify a compatibility level via
multiple methods at once. To use this method, F<debian/compat> should contain
the compatibility level as a single number, and no other content. If you
specify the compatibility level by this method, your package will also need a
versioned build dependency on a version of the debhelper package equal to (or
greater than) the compatibility level your package uses. So, if you specify
compatibility level #RECOMMENDED_COMPAT# in F<debian/compat>, ensure
F<debian/control> has:

  Build-Depends: debhelper (>= #RECOMMENDED_COMPAT#~)

Unless otherwise indicated, all debhelper documentation assumes that you
are using the most recent compatibility level, and in most cases does not
indicate if the behavior is different in an earlier compatibility level, so
if you are not using the most recent compatibility level, you're advised to
read below for notes about what is different in earlier compatibility
levels.

=head2 Supported compatibility levels

These are the available compatibility levels:

=over 4

=item v5

This is the lowest supported compatibility level.

If you are upgrading from an earlier compatibility level, please
review L<debhelper-obsolete-compat(7)>.

This mode is deprecated.

=item v6

Changes from v5 are:

=over 8

=item -

Commands that generate maintainer script fragments will order the
fragments in reverse order for the F<prerm> and F<postrm> scripts.

=item -

B<dh_installwm> will install a slave manpage link for F<x-window-manager.1.gz>,
if it sees the man page in F<usr/share/man/man1> in the package build
directory.

=item -

B<dh_builddeb> did not previously delete everything matching
B<DH_ALWAYS_EXCLUDE>, if it was set to a list of things to exclude, such as
B<CVS:.svn:.git>. Now it does.

=item -

B<dh_installman> allows overwriting existing man pages in the package build
directory. In previous compatibility levels it silently refuses to do this.

=back

This mode is deprecated.

=item v7

Changes from v6 are:

=over 8

=item -

B<dh_install>, will fall back to looking for files in F<debian/tmp> if it doesn't
find them in the current directory (or wherever you tell it look using
B<--sourcedir>). This allows B<dh_install> to interoperate with B<dh_auto_install>,
which installs to F<debian/tmp>, without needing any special parameters.

=item -

B<dh_clean> will read F<debian/clean> and delete files listed there.

=item -

B<dh_clean> will delete toplevel F<*-stamp> files.

=item -

B<dh_installchangelogs> will guess at what file is the upstream changelog if
none is specified.

=back

This mode is deprecated.

=item v8

Changes from v7 are:

=over 8

=item -

Commands will fail rather than warning when they are passed unknown options.

=item -

B<dh_makeshlibs> will run B<dpkg-gensymbols> on all shared libraries that it
generates shlibs files for. So B<-X> can be used to exclude libraries.
Also, libraries in unusual locations that B<dpkg-gensymbols> would not
have processed before will be passed to it, a behavior change that 
can cause some packages to fail to build.

=item -

B<dh> requires the sequence to run be specified as the first parameter, and
any switches come after it. Ie, use "B<dh $@ --foo>", not "B<dh --foo $@>".

=item -

B<dh_auto_>I<*> prefer to use Perl's B<Module::Build> in preference to F<Makefile.PL>.

=back

This mode is deprecated.

=item v9

Changes from v8 are:

=over 8

=item - 

Multiarch support. In particular, B<dh_auto_configure> passes
multiarch directories to autoconf in --libdir and --libexecdir.

=item -

dh is aware of the usual dependencies between targets in debian/rules.
So, "dh binary" will run any build, build-arch, build-indep, install,
etc targets that exist in the rules file. There's no need to define an
explicit binary target with explicit dependencies on the other targets.

=item -

B<dh_strip> compresses debugging symbol files to reduce the installed
size of -dbg packages.

=item -

B<dh_auto_configure> does not include the source package name
in --libexecdir when using autoconf.

=item -

B<dh> does not default to enabling --with=python-support

(Obsolete: As the B<dh_pysupport> tool was removed from Debian
stretch.  Since debhelper/10.3, B<dh> no longer enables this sequence
add-on regardless of compat level)

=item -

All of the B<dh_auto_>I<*> debhelper programs and B<dh> set
environment variables listed by B<dpkg-buildflags>, unless
they are already set.

=item -

B<dh_auto_configure> passes B<dpkg-buildflags> CFLAGS, CPPFLAGS, and
LDFLAGS to perl F<Makefile.PL> and F<Build.PL>

=item -

B<dh_strip> puts separated debug symbols in a location based on their
build-id.

=item -

Executable debhelper config files are run and their output used as the
configuration.

=back

This mode is deprecated.

=item v10

Changes from v9 are:

=over 8

=item -

B<dh_installinit> will no longer install a file named debian/I<package>
as an init script.

=item -

B<dh_installdocs> will error out if it detects links created with
--link-doc between packages of architecture "all" and non-"all" as it
breaks binNMUs.

=item -

B<dh_installdeb> no longer installs a maintainer-provided
debian/I<package>.shlibs file.  This is now done by B<dh_makeshlibs>
instead.

=item -

B<dh_installwm> refuses to create a broken package if no man page
can be found (required to register for the x-window-manager alternative).

=item -

Debhelper will default to B<--parallel> for all buildsystems that
support parallel building.  This can be disabled by using either
B<--no-parallel> or passing B<--max-parallel> with a value of 1.

=item -

The B<dh> command will not accept any of the deprecated "manual
sequence control" parameters (B<--before>, B<--after>, etc.).  Please
use override targets instead.

B<Retroactively applied to earlier compat levels>: B<dh> no longer
accepts any of these since debhelper/12.4.

=item -

The B<dh> command will no longer use log files to track which commands
have been run.  The B<dh> command I<still> keeps track of whether it
already ran the "build" sequence and skip it if it did.

The main effects of this are:

=over 4

=item -

With this, it is now easier to debug the I<install> or/and I<binary>
sequences because they can now trivially be re-run (without having to
do a full "clean and rebuild" cycle)

=item -

The main caveat is that B<dh_*> now only keeps track of what happened
in a single override target.  When all the calls to a given B<dh_cmd>
command happens in the same override target everything will work as
before.

Example of where it can go wrong:

  override_dh_foo:
    dh_foo -pmy-pkg

  override_dh_bar:
    dh_bar
    dh_foo --remaining

In this case, the call to B<dh_foo --remaining> will I<also> include
I<my-pkg>, since B<dh_foo -pmy-pkg> was run in a separate override
target.  This issue is not limited to B<--remaining>, but also includes
B<-a>, B<-i>, etc.

=back

=item -

The B<dh_installdeb> command now shell-escapes the lines in the
F<maintscript> config file.  This was the original intent but it did
not work properly and packages have begun to rely on the incomplete
shell escaping (e.g. quoting file names).

=item -

The B<dh_installinit> command now defaults to
B<--restart-after-upgrade>.  For packages needing the previous
behaviour, please use B<--no-restart-after-upgrade>.

=item -

The B<autoreconf> sequence is now enabled by default.  Please pass
B<--without autoreconf> to B<dh> if this is not desirable for a given
package

=item -

The B<systemd> sequence is now enabled by default.  Please pass
B<--without systemd> to B<dh> if this is not desirable for a given
package.

=item -

B<Retroactively removed>: B<dh> no longer creates the package build
directory when skipping running debhelper commands. This will not
affect packages that only build with debhelper commands, but it may
expose bugs in commands not included in debhelper.

This compatibility feature had a bug since its inception in
debhelper/9.20130516 that made it fail to apply in compat 9 and
earlier.  As there has been no reports of issues caused by this bug in
those ~5 years, this item have been removed rather than fixed.

=back

=item v11

This mode is discouraged.

The compat 11 is discouraged for new packages as it suffers from
feature interaction between L<dh_installinit> and L<dh_installsystemd>
causing services to not run correctly in some cases.  Please consider
using compatibility mode 10 or 12 instead.  More details about the
issue are available in Debian#887904 and
L<https://lists.debian.org/debian-release/2019/04/msg01442.html>.

Changes from v10 are:

=over 8

=item -

B<dh_installinit> no longer installs F<service> or F<tmpfile> files,
nor generates maintainer scripts for those files.  Please use the new
B<dh_installsystemd> helper.

=item -

The B<dh_systemd_enable> and B<dh_systemd_start> helpers have been
replaced by the new B<dh_installsystemd> helper.  For the same reason,
the B<systemd> sequence for B<dh> has also been removed.  If you need
to disable the B<dh_installsystemd> helper tool, please use an empty
override target.

Please note that the B<dh_installsystemd> tool has a slightly
different behaviour in some cases (e.g. when using the B<--name>
parameter).

=item -

B<dh_installdirs> no longer creates debian/I<package> directories
unless explicitly requested (or it has to create a subdirectory in
it).

The vast majority of all packages will be unaffected by this change.

=item -

The B<makefile> buildsystem now passes B<INSTALL="install
--strip-program=true"> to L<make(1)>.  Derivative buildsystems
(e.g. B<configure> or B<cmake>) are unaffected by this change.

=item -

The B<autoconf> buildsystem now passes B<--runstatedir=/run> to
F<./configure>.

=item -

The B<cmake> buildsystem now passes
B<-DCMAKE_INSTALL_RUNSTATEDIR=/run> to L<cmake(1)>.

=item -

B<dh_installman> will now prefer detecting the language from the
path name rather than the extension.

=item -

B<dh_auto_install> will now only create the destination
directory it needs.  Previously, it would create the package build
directory for all packages.  This will not affect packages that only
build with debhelper commands, but it may expose bugs in commands not
included in debhelper.

=item -

The helpers B<dh_installdocs>, B<dh_installexamples>, B<dh_installinfo>,
and B<dh_installman> now error out if their config has a pattern that
does not match anything or reference a path that does not exist.

Known exceptions include building with the B<nodoc> profile, where the
above tools will silently permit failed matches where the patterns
are used to specify documentation.

=item -

The helpers B<dh_installdocs>, B<dh_installexamples>, B<dh_installinfo>,
and B<dh_installman> now accept the parameter B<--sourcedir> with same
meaning as B<dh_install>. Furthermore, they now also fall back to
F<debian/tmp> like B<dh_install>.

Migration note: A bug in debhelper 11 up to 11.1.5 made
B<dh_installinfo> incorrectly ignore B<--sourcedir>.

=item -

The B<perl-makemaker> and B<perl-build> build systems no longer pass
B<-I.> to perl.  Packages that still need this behaviour can emulate
it by using the B<PERL5LIB> environment variable.  E.g. by adding
B<export PERL5LIB=.> in their debian/rules file (or similar).

=item -

The B<PERL_USE_UNSAFE_INC> environment variable is no longer set by
B<dh> or any of the B<dh_auto_*> tools.  It was added as a temporary
work around to avoid a lot of packages failing to build at the same
time.

Note this item will eventually become obsolete as upstream intends
to drop support for the B<PERL_USE_UNSAFE_INC> environment variable.
When perl drops support for it, then this variable will be removed
retroactively from existing compat levels as well.

=item -

The B<dh_makeshlibs> helper will now exit with an error if objdump
returns a non-zero exit from analysing a given file.

=item -

The B<dh_installdocs> and B<dh_installexamples> tools may now install
I<most> of the documentation in a different path to comply with the
recommendation from Debian policy ยง12.3 (since version 3.9.7).

Note that if a given source package only contains a single binary
package in F<debian/control> or none of the packages are I<-doc>
packages, then this change is not relevant for that source package and
you can skip to the next change.

By default, these tools will now attempt to determine a "main package
for the documentation" (called a I<doc-main-package> from here on) for
every I<-doc> package.  If they find such a I<doc-main-package>, they
will now install the documentation into the path F<<
/usr/share/doc/I<doc-main-package> >> in the given doc package.
I.e. the path can change but the documentation is still shipped in the
I<-doc> package.

The B<--doc-main-package> option can be used when the auto-detection
is insufficient or to reset the path to its previous value if there is
a reason to diverge from Debian policy recommendation.

Some documentation will not be affected by this change.  These
exceptions include the copyright file, changelog files, README.Debian,
etc.  These files will still be installed in the path F<<
/usr/share/doc/I<package> >>.

=item -

The B<dh_strip> and B<dh_shlibdeps> tools no longer uses filename
patterns to determine which files to process.  Instead, they open the
file and look for an ELF header to determine if a given file is an
shared object or an ELF executable.

This change may cause the tools to process more files than previously.

=back

=item v12

Changes from v11 are:

=over 8

=item -

The B<dh_makeshlibs> tool now generates shlibs files with versioned
dependency by default.  This means that B<-VUpstream-Version>
(a.k.a. B<-V>) is now the default.

If an unversioned dependency in the shlibs file is wanted, this can be
obtained by passing B<-VNone> instead.  However, please see
L<dh_makeshlibs(1)> for the caveat of unversioned dependencies.

=item -

The B<-s> (B<--same-arch>) option is removed.  Please use B<-a> (B<--arch>) instead.

=item -

Invoking B<dh_clean -k> now causes an error instead of a deprecation
warning.

=item -

The B<--no-restart-on-upgrade> option in B<dh_installinit> has been removed.
Please use the new name B<--no-stop-on-upgrade>

=item -

There was a bug in the B<doit> (and similar) functions from
L<Debian::Debhelper::Dh_Lib> that made them spawn a shell in one
particular circumstance.  This bug is now removed and will cause
helpers that rely on the bug to fail with a "command not found"-error.

=item -

The B<--list-missing> and B<--fail-missing> in B<dh_install> has been
removed.  Please use B<dh_missing> and its corresponding options,
which can also see the files installed by other helpers.

=item -

The B<dh_installinit> helper no longer installs configuration for
the upstart init system.  Instead, it will abort the build if it
finds an old upstart configuration file.  The error is there to
remind the package maintainer to ensure the proper removal of the
conffiles shipped in previous versions of the package (if any).

=item -

The B<dh_installdeb> tool will do basic validation of some
L<dpkg-maintscript-helper(1)> commands and will error out if the
commands appear to be invalid.

=item -

The B<dh_missing> tool will now default to B<--list-missing>.

=item -

The B<dh_makeshlibs> tool will now only pass libraries to L<dpkg-gensymbols(1)>
if the ELF binary has a SONAME (containing ".so").

=item -

The B<dh_compress> tool no longer compresses examples (i.e. anything installed
in F<</usr/share/doc/I<package>/examples>>.)

=item -

The standard sequence in B<dh> now includes B<dh_dwz> and
B<dh_installinitramfs> by default.  This makes the B<dwz> and
B<installinitramfs> sequences obsolete and they will now fail with an
error.  If you want to skip these commands, then please insert an
empty override target for them in F<debian/rules>
(e.g. I<override_dh_dwz:>)

=item -

The build systems B<meson> and B<autoconf> no longer explicitly set
the B<--libexecdir> variable and thus relies on the build system
default - which should be B</usr/libexec> (per FHS 3.0, adopted in
Debian Policy 4.1.5).

If a particular upstream package does not use the correct default, the
parameter can often be passed manually via L<dh_auto_configure(1)>.  E.g.
via the following example:

    override_dh_auto_configure:
    	dh_auto_configure -- --libexecdir=/usr/libexec

Note the B<--> before the B<--libexecdir> parameter.

=item -

The B<dh_installdeb> tool no longer installs the maintainer provided
F<conffiles> file.  The file has mostly been obsolete since
compatibility level 3, where B<dh_installdeb> began to automatically
compute the resulting F<conffiles> control file.

=item -

The B<dh_installsystemd> tool no longer relies on B<dh_installinit> for
handling systemd services that have a sysvinit alternative.  Both tools
must now be used in such a case to ensure the service is properly started
under both sysvinit and systemd.

If you have an override for B<dh_installinit> (e.g. to call it with
B<--no-start>) then you will probably need one for
B<dh_installsystemd> as well now.

This change makes B<dh_installinit> inject a I<misc:Pre-Depends> for
B<< init-system-helpers (>= 1.54~) >>.  Please ensure that the package
lists B<${misc:Pre-Depends}> in its B<Pre-Depends> field before
upgrading to compat 12.

=item -

The third-party B<dh_golang> tool (from B<dh-golang> package) now defaults on
honoring B<DH_GOLANG_EXCLUDES> variable for source installation in -dev
packages and not only during the building process. Please set
B<DH_GOLANG_EXCLUDES_ALL> to false to revert to the previous behaviour. See
B<Debian::Debhelper::Buildsystem::golang(3pm)> for details and examples.

=item -

B<dh_installsystemduser> is now included in the B<dh> standard
sequence by default.

=item -

The B<python-distutils> buildsystem is now removed.  Please use the
third-party build system B<pybuild> instead.

=back

=item v13

This is the recommended mode of operation.

Changes from v12 are:

=over 8

=item -

The B<meson+ninja> build system now uses B<meson test> instead of
B<ninja test> when running the test suite.  Any override of
B<dh_auto_test> that passes extra parameters to upstream test runner
should be reviewed as B<meson test> is not command line compatible
with B<ninja test>.

=item -

All debhelper like tools based on the official debhelper library
(including B<dh> and the official B<dh_*> tools) no longer accepts
abbreviated command parameters.  At the same time, B<dh> now
optimizes out calls to redundant B<dh_*> helpers even when passed
long command line options.

=item -

The ELF related debhelper tools (B<dh_dwz>, B<dh_strip>,
B<dh_makeshlibs>, B<dh_shlibdeps>) are now only run for arch dependent
packages by default (i.e. they are excluded from B<*-indep> targets
and are passed B<-a> by default). If you need them for B<*-indep>
targets, you can add an explicit Build-Depends on
B<dh-sequence-elf-tools>.

=item -

The third-party B<gradle> build system (from B<gradle-debian-helper>
package) now runs the upstream-provided test suite automatically.  To
suppress such behavior, override B<dh_auto_test>.

=item -

The B<dh_installman> tool now aborts if it sees conflicting
definitions of a manpage.  This typically happens if the upstream
build system is installing a compressed version and the package lists
an uncompressed version of the manpage in F<<
debian/I<package>.manpages >>.  Often the easiest fix is to remove the
manpage from F<< debian/I<package>.manpages >> (assuming both versions
are identical).

=item -

The B<dh_auto_*> helpers now reset the environment variables B<HOME>
and common B<XDG_*> variable.  Please see description of the
environment variables in L</ENVIRONMENT> for how this is handled.

I<This feature changed between debhelper 13 and debhelper 13.2.>

=item -

The B<dh> command will now error if an override or hook target for an
obsolete command are present in F<debian/rules>
(e.g. B<override_dh_systemd_enable:>).

=item -

The B<dh_missing> command will now default to B<--fail-missing>.  This
can be reverted to a non-fatal warning by explicitly passing
B<--list-missing> like it was in compat 12.

If you do not want the warning either, please omit the call to
B<dh_missing>.  If you use the B<dh> command sequencer, then you can
do this by inserting an empty override target in the
F<debian/rules> file of the relevant package.  As an example:

    # Disable dh_missing
    override_dh_missing:

=item -

The B<dh> command sequencer now runs B<dh_installtmpfiles> in the
default sequence.  The B<dh_installtmpfiles> takes over handling of
tmpfiles.d configuration files.  Related functionality in
B<dh_installsystemd> is now disabled.

Note that B<dh_installtmpfiles> responds to
F<< debian/I<package>.tmpfiles >> where B<dh_installsystemd> used
a name without the trailing "s".

=item -

Many B<dh_*> tools now support limited variable expansion via the
B<${foo}> syntax.  In many cases, this can be used to reference paths
that contain either spaces or L<dpkg-architecture(1)> values.  While
this can reduce the need for L<dh-exec(1)> in some cases, it is B<not>
a replacement L<dh-exec(1)> in general.  If you need filtering,
renaming, etc., the package will still need L<dh-exec(1)>.

Please see L</Substitutions in debhelper config files> for syntax and
available substitution variables.  To B<dh_*> tool writers, substitution
expansion occurs as a part of the B<filearray> and B<filedoublearray>
functions.

=item -

The B<dh> command sequencer will now skip all hook and override targets
for B<dh_auto_test>, B<dh_dwz> and B<dh_strip> when B<DEB_BUILD_OPTIONS>
lists the relevant B<nocheck> / B<nostrip> options.

Any package relying on these targets to always be run should instead
move relevant logic out of those targets.  E.g. non-test related
packaging code from B<override_dh_auto_test> would have to be moved to
B<execute_after_dh_auto_build> or B<execute_before_dh_auto_install>.

=item -

The B<cmake> buildsystem now passes B<-DCMAKE_SKIP_INSTALL_ALL_DEPENDENCY=ON>
to L<cmake(1)> to speed up automatic installation process. If for some reason
you need previous behavior, override the flag:

    dh_auto_configure -- -DCMAKE_SKIP_INSTALL_ALL_DEPENDENCY=OFF ...

=back

=item v14

This compatibility level is still open for development; use with caution.

Changes from v13 are:

=over 8

=item -

The B<cmake> buildsystem now passes B<-DCMAKE_SKIP_RPATH=ON>
and B<-DCMAKE_BUILD_RPATH_USE_ORIGIN=ON> to L<cmake(1)> to avoid some reproducibility
issues.

This can cause issues with running binaries directly from the build directories
as they might now require a manually set B<LD_LIBRARY_PATH>.  If you need to
override this change, we recommend that you try to pass the
B<-DCMAKE_SKIP_RPATH=OFF> option first to see if that fixes the problem (leaving
B<CMAKE_BUILD_RPATH_USE_ORIGIN> at its new default).  This should undo the need for
B<LD_LIBRARY_PATH> and avoid the reproducibility issues on Linux, where B<$ORIGIN>
is supported by the runtime linkers.

=item -

The tool B<dh_installsysusers> is now included in the default sequence.

=back

=back

=head1 NOTES

=head2 Multiple binary package support

If your source package generates more than one binary package, debhelper
programs will default to acting on all binary packages when run. If your
source package happens to generate one architecture dependent package, and
another architecture independent package, this is not the correct behavior,
because you need to generate the architecture dependent packages in the
binary-arch F<debian/rules> target, and the architecture independent packages
in the binary-indep F<debian/rules> target.

To facilitate this, as well as give you more control over which packages
are acted on by debhelper programs, all debhelper programs accept the
B<-a>, B<-i>, B<-p>, and B<-s> parameters. These parameters are cumulative. 
If none are given, debhelper programs default to acting on all packages listed
in the control file, with the exceptions below.

First, any package whose B<Architecture> field in B<debian/control> does not
match the B<DEB_HOST_ARCH> architecture will be excluded
(L<Debian Policy, section 5.6.8>).

Also, some additional packages may be excluded based on the contents of the
B<DEB_BUILD_PROFILES> environment variable and B<Build-Profiles> fields in
binary package stanzas in B<debian/control>, according to the draft policy at
L<https://wiki.debian.org/BuildProfileSpec>.

=head3 Interaction between package selections and Build-Profiles

Build-Profiles affect which packages are included in the package
selections mechanisms in debhelper.  Generally, the package selections
are described from the assumption that all packages are enabled.  This
section describes how the selections react when a package is disabled
due to the active Build-Profiles (or lack of active Build-Profiles).

=over 4

=item -a/--arch, -i/--indep OR no selection options (a raw "dh_X" call)

The package disabled by Build-Profiles is silently excluded from the
selection.

Note you will receive a warning if I<all> packages related to these
selections are disabled.  In that case, it generally does not make
sense to do the build in the first place.

=item -N I<package> / --no-package I<package>

The option is accepted and effectively does nothing.

=item -p I<package> / --package I<package>

The option is accepted, but debhelper will not act on the package.

=back

Note that it does not matter whether a package is enabled or disabled
by default.

=head2 Automatic generation of Debian install scripts

Some debhelper commands will automatically generate parts of Debian
maintainer scripts. If you want these automatically generated things
included in your existing Debian maintainer scripts, then you need to add
B<#DEBHELPER#> to your scripts, in the place the code should be added.
B<#DEBHELPER#> will be replaced by any auto-generated code when you run
B<dh_installdeb>.

If a script does not exist at all and debhelper needs to add something to
it, then debhelper will create the complete script.

All debhelper commands that automatically generate code in this way let it
be disabled by the -n parameter (see above).

Note that the inserted code will be shell code, so you cannot directly use
it in a Perl script. If you would like to embed it into a Perl script, here
is one way to do that (note that I made sure that $1, $2, etc are set with
the set command):

  my $temp="set -e\nset -- @ARGV\n" . << 'EOF';
  #DEBHELPER#
  EOF
  if (system($temp)) {
     my $exit_code = ($? >> 8) & 0xff;
     my $signal = $? & 0x7f;
     if ($exit_code) {
         die("The debhelper script failed with error code: ${exit_code}");
     } else {
         die("The debhelper script was killed by signal: ${signal}");
     }
  }

=head2 Automatic generation of miscellaneous dependencies.

Some debhelper commands may make the generated package need to depend on
some other packages. For example, if you use L<dh_installdebconf(1)>, your
package will generally need to depend on debconf. Or if you use
L<dh_installxfonts(1)>, your package will generally need to depend on a
particular version of xutils. Keeping track of these miscellaneous
dependencies can be annoying since they are dependent on how debhelper does
things, so debhelper offers a way to automate it.

All commands of this type, besides documenting what dependencies may be
needed on their man pages, will automatically generate a substvar called
B<${misc:Depends}>. If you put that token into your F<debian/control> file, it
will be expanded to the dependencies debhelper figures you need. 

This is entirely independent of the standard B<${shlibs:Depends}> generated by
L<dh_makeshlibs(1)>, and the B<${perl:Depends}> generated by L<dh_perl(1)>.
You can choose not to use any of these, if debhelper's guesses don't match
reality.

=head2 Package build directories

By default, all debhelper programs assume that the temporary directory used
for assembling the tree of files in a package is debian/I<package>.

Sometimes, you might want to use some other temporary directory. This is
supported by the B<-P> flag. For example, "B<dh_installdocs -Pdebian/tmp>", will
use B<debian/tmp> as the temporary directory. Note that if you use B<-P>, the 
debhelper programs can only be acting on a single package at a time. So if 
you have a package that builds many binary packages, you will need to also 
use the B<-p> flag to specify which binary package the debhelper program will
act on.

=head2 udebs

Debhelper includes support for udebs. To create a udeb with debhelper,
add "B<Package-Type: udeb>" to the package's stanza in F<debian/control>.
Debhelper will try to create udebs that comply with debian-installer
policy, by making the generated package files end in F<.udeb>, not
installing any documentation into a udeb, skipping over
F<preinst>, F<postrm>, F<prerm>, and F<config> scripts, etc.

=head1 ENVIRONMENT

This section describes some of the environment variables that influences
the behaviour of debhelper or which debhelper interacts with.

It is important to note that these must be actual environment variables in
order to affect the behaviour of debhelper (not simply F<Makefile> variables).
To specify them properly in F<debian/rules>, be sure to "B<export>" them. For
example, "B<export DH_VERBOSE>".

=over 4

=item B<DH_VERBOSE>

Set to B<1> to enable verbose mode. Debhelper will output every command it
runs. Also enables verbose build logs for some build systems like autoconf.

=item B<DH_QUIET>

Set to B<1> to enable quiet mode. Debhelper will not output commands calling
the upstream build system nor will dh print which subcommands are called
and depending on the upstream build system might make that more quiet, too.
This makes it easier to spot important messages but makes the output quite
useless as buildd log.
Ignored if DH_VERBOSE is also set.

=item B<DH_COMPAT>

Temporarily specifies what compatibility level debhelper should run at,
overriding any value specified via Build-Depends on debhelper-compat or via the
F<debian/compat> file.

=item B<DH_NO_ACT>

Set to B<1> to enable no-act mode.

=item B<DH_OPTIONS>

All debhelper tools will parse command line arguments listed in this variable
before any command option (as if they had been prepended to the command
line arguments).  Unfortunately, some third-party provided tools may not
support this variable and will ignore these command line arguments.

When using L<dh(1)>, it can be passed options that will be passed on to each
debhelper command, which is generally better than using DH_OPTIONS.

=item B<DH_ALWAYS_EXCLUDE>

If set, this adds the value the variable is set to to the B<-X> options of all
commands that support the B<-X> option. Moreover, B<dh_builddeb> will B<rm -rf>
anything that matches the value in your package build tree.

This can be useful if you are doing a build from a CVS source tree, in
which case setting B<DH_ALWAYS_EXCLUDE=CVS> will prevent any CVS directories
from sneaking into the package you build. Or, if a package has a source
tarball that (unwisely) includes CVS directories, you might want to export
B<DH_ALWAYS_EXCLUDE=CVS> in F<debian/rules>, to make it take effect wherever
your package is built.

Multiple things to exclude can be separated with colons, as in
B<DH_ALWAYS_EXCLUDE=CVS:.svn>

=item B<DH_EXTRA_ADDONS>

If set, this adds the specified dh addons to be run in the appropriate places
in the sequence of commands. This is equivalent to specifying the addon to run
with the --with flag in the debian/rules file. Any --without calls specifying
an addon in this environment variable will not be run.

This is intended to be used by downstreams or specific local configurations
that require a debhelper addon to be run during multiple builds without
having to patch a large number of rules file. If at all possible, this should
be avoided in favor of a --with flag in the rules file.

=item B<DH_COLORS>, B<DPKG_COLORS>

These variables can be used to control whether debhelper commands should use
colors in their textual output.  Can be set to "always", "auto" (the default),
or "never".

Note that B<DPKG_COLOR> also affects a number of dpkg related tools and
debhelper uses it on the assumption that you want the same color setting for
dpkg and debhelper.  In the off-hand chance you want different color setting
for debhelper, you can use B<DH_COLORS> instead or in addition to
B<DPKG_COLORS>.

=item B<NO_COLOR>

If no explicit request for color has been given (e.g. B<DH_COLORS> and
B<DPKG_COLORS> are both unset), the presence of this environment variable
cause the default color setting to be "never".

The variable is defined according to L<https://no-color.org/>.  In this
project, the environment variables (such as B<DH_COLORS>) are considered
an explicit request for color.

=item B<CFLAGS>, B<CPPFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>, B<GCJFLAGS>, B<FFLAGS>, B<FCFLAGS>, B<LDFLAGS>

By default (in any non-deprecated compat level), debhelper will automatically
set these flags by using L<dpkg-buildflags(1)>, when they are unset.  If you
need to change the default flags, please use the features from
L<dpkg-buildflags(1)> to do this (e.g. B<DEB_BUILD_MAINT_OPTIONS=hardening=all>
or B<DEB_CPPFLAGS_MAINT_APPEND=-DCUSTOM_MACRO=true>) rather than setting the
concrete variable directly.

=item B<HOME>, B<XDG_*>

In compat 13 and later, these environment variables are reset before invoking
the upstream build system via the B<dh_auto_*> helpers.  The variables B<HOME>
(all B<dh_auto_*> helpers) and B<XDG_RUNTIME_DIR> (B<dh_auto_test> only) will
be set to a writable directory. All remaining variables and B<XDG_RUNTIME_DIR>
(except for during B<dh_auto_test>) will be cleared.

The B<HOME> directory will be created as an empty directory but it will be
reused between calls to B<dh_auto_*>.  Any content will persist until
explicitly deleted or B<dh_clean>.

=item B<DEB_BUILD_OPTIONS>

Please see L</Supported flags in DEB_BUILD_OPTIONS> for this environment
variable.

Please note that this variable should I<not> be altered by package maintainers
inside F<debian/rules> to change the behaviour of debhelper.  Instead, where
the package maintainer need these features, they should look disabling the
relevant feature directly (e.g. by overriding the concrete tools).

=item B<DEB_MAINT_BUILD_OPTIONS>

This is a dpkg specific environment variable (see e.g. L<dpkg-buildflags(1)>).
The debhelper tool suite silently ignores it.

It is documented here because it has a similar name to B<DEB_BUILD_OPTIONS>,
which make some people mistakenly assume that debhelper will also react to this
variable.

=back

=head2 Supported flags in DEB_BUILD_OPTIONS

The debhelper tool suite reacts to the following flags in B<DEB_BUILD_OPTIONS>.

=over 4

=item B<dherroron=obsolete-compat-levels>

I<This is a debhelper specific value.>

When B<dherroron> is present and set to B<obsolete-compat-levels>, then
debhelper tools will promote deprecation warnings for usage of old soon
to be removed compat levels into errors.

This is useful for automated checking for code relying on deprecated
compat levels that is scheduled for removal.

This option is intended for testing purposes; not production builds.

=item B<nostrip>

I<This value will change the content of the debs being built.  The .deb
packages built when this is set is therefore not bit-for-bit reproducible
with a regular build in the general case.>

This value will cause the official debhelper tools will skip actions and
helpers that either remove, detach or deduplicate debugging symbols in
ELF binaries.

This value affects L<dh_dwz(1)> and L<dh_strip(1)>.

=item B<nocheck>

This value will cause the official debhelper build systems to skip runs
of upstream test suites.

Package maintainers looking to avoid running the upstream tests should
B<not> rely on this.  Instead, they can add an empty override target
to skip B<dh_auto_test>.

This value affects L<dh_auto_test(1)>.

=item B<nodoc>

I<This value will change the content of the debs being built.  The .deb
packages built when this is set is therefore not bit-for-bit reproducible
with a regular build in the general case.>

This value will cause several debhelper tools to skip installation of
documentation such as manpages or upstream provided documentation.
Additionally, the tools will also ignore if declared documentation is
"missing" on the assumption that the documentation has not been built.

This value effects tools I<like> L<dh_installdocs(1)>, which I<knows>
it is working with documentation.

=item B<noautodbgsym>, B<noddebs>

I<The official name is autodbgsym.  The noddebs variant is accepted
for historical reasons.>

This value causes debhelper to skip the generation of automatically
generated debug symbol packages.

This value affects L<dh_strip(1)>.

=item B<parallel=N>

This value enables debhelper to use up to B<N> threads or processes
(subject to parameters like B<--no-parallel> and B<--max-parallel=M>).
Not all debhelper tools work with parallel tasks and may silently
ignore the request.

This value affects many debhelper tools.  Most notably B<dh_auto_*>,
which will attempt to run the underlying upstream build system with
that number of threads.

=item B<terse>

This value will cause the official debhelper build systems to configure
upstream builds to be terse (i.e. reduce verbosity in their output).
This is subject to the upstream and the debhelper build system
supporting such features.

This value affects most B<dh_auto_*> tools.

=back

Unknown flags are silently ignored.

Note third-party debhelper-like tools or third-party provided build systems
may or may not react to the above flags.  This tends to depend on
implementation details of the tool.

=head1 SEE ALSO

=over 4

=item F</usr/share/doc/debhelper/examples/>

A set of example F<debian/rules> files that use debhelper.

=item L<http://joeyh.name/code/debhelper/>

Debhelper web site.

=back

=head1 AUTHOR

Joey Hess <joeyh@debian.org>

=cut