File: debhelper.pod

package info (click to toggle)
debhelper 12.1.1
  • links: PTS, VCS
  • area: main
  • in suites: buster
  • size: 4,072 kB
  • sloc: perl: 10,850; makefile: 120; sh: 8
file content (1172 lines) | stat: -rw-r--r-- 39,567 bytes parent folder | download | duplicates (2)
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
=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 tool explicitly denotes otherwise, all of the debhelper
tools assumes that they run from 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 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 *

The output will be used exactly as it is.  Notably, debhelper will
I<not> expand wildcards or strip comments 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<--ignore=>I<file>

Ignore the specified file. This can be used if F<debian/> contains a debhelper
config file that a debhelper command should not act on. Note that
F<debian/compat>, F<debian/control>, and F<debian/changelog> can't be ignored, but
then, there should never be a reason to ignore those files.

For example, if upstream ships a F<debian/init> that you don't want
B<dh_installinit> to install, use B<--ignore=debian/init>

=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.

=item B<-D>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.

=item B<-B>[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<--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

=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.

=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

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

This is the recommended mode of operation.

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 compatibility level is still open for development; use with caution.

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>.

=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

The following environment variables can influence the behavior of debhelper.
It is important to note that these must be actual environment variables in
order to function properly (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>

Anything in this variable will be prepended to the command line arguments
of all debhelper commands.

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.

=back

=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