14
B<dh> sequence [B<--with> I<addon>[,I<addon>,...]] [B<--list>] [B<--until> I<cmd>] [B<--before> I<cmd>] [B<--after> I<cmd>] [B<--remaining>] [S<I<debhelper options>>]
14
B<dh> I<sequence> [B<--with> I<addon>[B<,>I<addon> ...]] [B<--list>] [B<--until> I<cmd>] [B<--before> I<cmd>] [B<--after> I<cmd>] [B<--remaining>] [S<I<debhelper options>>]
18
dh runs a sequence of debhelper commands. The supported sequences
19
correspond to the targets of a debian/rules file: "build", "clean",
20
"install", "binary-arch", "binary-indep", and "binary".
22
Commands in the binary-indep sequence are passed the "-i" option to ensure
23
they only work on binary independent packages, and commands in the
24
binary-arch sequences are passed the "-a" option to ensure they only work
25
on architecture dependent packages.
27
If debian/rules contains a target with a name like "override_I<dh_command>",
28
then when it would normally run I<dh_command>, dh will instead call that
18
B<dh> runs a sequence of debhelper commands. The supported I<sequence>s
19
correspond to the targets of a F<debian/rules> file: B<build-arch>,
20
B<build-indep>, B<build>, B<clean>, B<install-indep>, B<install-arch>,
21
B<install>, B<binary-arch>, B<binary-indep>, and B<binary>.
23
Commands in the B<build-indep>, B<install-indep> and B<binary-indep>
24
sequences are passed the B<-i> option to ensure they only work on
25
architecture independent packages, and commands in the B<build-arch>,
26
B<install-arch> and B<binary-arch> sequences are passed the B<-a>
27
option to ensure they only work on architecture dependent packages.
29
If F<debian/rules> contains a target with a name like B<override_>I<dh_command>,
30
then when it would normally run I<dh_command>, B<dh> will instead call that
29
31
target. The override target can then run the command with additional options,
30
32
or run entirely different commands instead. See examples below. (Note that to
31
33
use this feature, you should Build-Depend on debhelper 7.0.50 or above.)
37
=item B<--with> I<addon>[,I<addon>,...]
39
=item B<--with> I<addon>[B<,>I<addon> ...]
39
41
Add the debhelper commands specified by the given addon to appropriate places
40
42
in the sequence of commands that is run. This option can be repeated more
41
43
than once, or multiple addons can be listed, separated by commas.
42
44
This is used when there is a third-party package that provides
43
debhelper commands. See the PROGRAMMING file for documentation about
45
debhelper commands. See the F<PROGRAMMING> file for documentation about
44
46
the sequence addon interface.
46
48
=item B<--without> I<addon>
48
The inverse of --with, disables using the given addon.
50
The inverse of B<--with>, disables using the given addon.
50
52
=item B<--list>, B<-l>
76
All other options passed to dh are passed on to each command it runs. This
77
can be used to set an option like "-v" or "-X" or "-N", as well as for more
78
All other options passed to B<dh> are passed on to each command it runs. This
79
can be used to set an option like B<-v> or B<-X> or B<-N>, as well as for more
78
80
specialised options.
80
82
In the above options, I<cmd> can be a full name of a debhelper command, or
161
163
chmod 4755 debian/foo/usr/bin/foo
163
If your package is a python package, dh will use dh_pysupport by
164
default. This is how to use dh_pycentral instead.
165
If your package is a Python package, B<dh> will use B<dh_pysupport> by
166
default. This is how to use B<dh_pycentral> instead.
166
168
#!/usr/bin/make -f
168
170
dh $@ --with python-central
170
If your package uses autotools and you want to freshen config.sub and
171
config.guess with newer versions from the autotools-dev package
172
at build time, you can use some commands provided in autotools-dev
172
If your package uses autotools and you want to freshen F<config.sub> and
173
F<config.guess> with newer versions from the B<autotools-dev> package
174
at build time, you can use some commands provided in B<autotools-dev>
173
175
that automate it, like this.
175
177
#!/usr/bin/make -f
177
179
dh $@ --with autotools_dev
179
Here is how to force use of perl's Module::Build build system,
181
Here is how to force use of Perl's B<Module::Build> build system,
180
182
which can be necessary if debhelper wrongly detects that the package
185
187
dh $@ --buildsystem=perl_build
187
To patch your package using quilt, you can tell dh to use quilt's dh
189
To patch your package using quilt, you can tell B<dh> to use quilt's B<dh>
188
190
sequence addons like this:
190
192
#!/usr/bin/make -f
192
194
dh $@ --with quilt
194
Here is an example of overriding where the dh_auto_* commands find
196
Here is an example of overriding where the B<dh_auto_>I<*> commands find
195
197
the package's source, for a package where the source is located in a
200
202
dh $@ --sourcedirectory=src
202
And here is an example of how to tell the dh_auto_* commands to build
203
in a subdirectory, which will be removed on clean.
204
And here is an example of how to tell the B<dh_auto_>I<*> commands to build
205
in a subdirectory, which will be removed on B<clean>.
205
207
#!/usr/bin/make -f
207
209
dh $@ --builddirectory=build
209
211
If your package can be built in parallel, you can support parallel building
210
as follows. Then I<dpkg-buildpackage -j> will work.
212
as follows. Then B<dpkg-buildpackage -j> will work.
212
214
#!/usr/bin/make -f
216
Here is a way to prevent dh from running several commands that you don't
218
Here is a way to prevent B<dh> from running several commands that you don't
217
219
want it to run, by defining empty override targets for each command.
219
221
#!/usr/bin/make -f
234
236
override_dh_fixperms:
236
ifneq (,$(findstring foo, $(shell dh_listpackages)))
238
ifneq (,$(filter foo, $(shell dh_listpackages)))
237
239
chmod 4755 debian/foo/usr/bin/foo
240
242
Finally, remember that you are not limited to using override targets in the
241
rules file when using dh. You can also explicitly define any of the regular
243
rules file when using B<dh>. You can also explicitly define any of the regular
242
244
rules file targets when it makes sense to do so. A common reason to do this
243
is if your package needs different build-arch and build-indep targets. For
245
is if your package needs different B<build-arch> and B<build-indep> targets. For
244
246
example, a package with a long document build process can put it in
245
build-indep to avoid build daemons redundantly building the documentation.
247
B<build-indep> to avoid build daemons redundantly building the documentation.
247
249
#!/usr/bin/make -f
259
If you're curious about dh's internals, here's how it works under the hood.
261
If you're curious about B<dh>'s internals, here's how it works under the hood.
261
263
Each debhelper command will record when it's successfully run in
262
debian/package.debhelper.log. (Which dh_clean deletes.) So dh can tell
264
F<debian/package.debhelper.log>. (Which B<dh_clean> deletes.) So B<dh> can tell
263
265
which commands have already been run, for which packages, and skip running
264
266
those commands again.
266
Each time dh is run, it examines the log, and finds the last logged command
268
Each time B<dh> is run, it examines the log, and finds the last logged command
267
269
that is in the specified sequence. It then continues with the next command
268
270
in the sequence. The B<--until>, B<--before>, B<--after>, and B<--remaining>
269
271
options can override this behavior.
271
dh uses the DH_INTERNAL_OPTIONS environment variable to pass information
273
B<dh> uses the B<DH_INTERNAL_OPTIONS> environment variable to pass information
272
274
through to debhelper commands that are run inside override targets. The
273
275
contents (and indeed, existence) of this environment variable, as the name
274
276
might suggest, is subject to change at any time.
374
$sequences{'install'} = [@{$sequences{build}}, @i];
375
$sequences{'install-indep'} = [@{$sequences{'build-indep'}}, @i];
376
$sequences{'install-arch'} = [@{$sequences{'build-arch'}}, @i];
376
$sequences{'binary-indep'} = [@{$sequences{install}}, @b];
377
$sequences{binary} = [@{$sequences{install}}, qw{
382
$sequences{'binary-arch'} = [@{$sequences{binary}}];
388
$sequences{binary} = [@{$sequences{install}}, @ba, @b];
389
$sequences{'binary-indep'} = [@{$sequences{'install-indep'}}, @b];
390
$sequences{'binary-arch'} = [@{$sequences{'install-arch'}}, @ba, @b];
384
392
# Additional command options
385
393
my %command_opts;
514
522
# Get the options to pass to commands in the sequence.
515
523
# Filter out options intended only for this program.
517
if ($sequence eq 'binary-arch') {
525
if ($sequence eq 'build-arch' ||
526
$sequence eq 'install-arch' ||
527
$sequence eq 'binary-arch') {
518
528
push @options, "-a";
519
529
# as an optimisation, remove from the list any packages
520
530
# that are not arch dependent
521
531
my %arch_packages = map { $_ => 1 } getpackages("arch");
522
532
@packages = grep { $arch_packages{$_} } @packages;
524
elsif ($sequence eq 'binary-indep') {
534
elsif ($sequence eq 'build-indep' ||
535
$sequence eq 'install-indep' ||
536
$sequence eq 'binary-indep') {
525
537
push @options, "-i";
526
538
# ditto optimisation for arch indep
527
539
my %indep_packages = map { $_ => 1 } getpackages("indep");
635
647
# This passes the options through to commands called
636
648
# inside the target.
637
649
$ENV{DH_INTERNAL_OPTIONS}=join("\x1e", @options);
650
# Prevent commands called inside the target from
652
$ENV{DH_INHIBIT_LOG}=$command;
638
653
$command="debian/rules";
639
654
@options="override_".$override_command;
670
685
if (defined $override_command) {
671
686
delete $ENV{DH_INTERNAL_OPTIONS};
672
# Need to handle logging for overriden commands here,
673
# because the actual debhelper command may not have
674
# been run by the rules file target.
687
delete $ENV{DH_INHIBIT_LOG};
688
# Update log for overridden command now that it has
689
# finished successfully.
675
690
# (But avoid logging for dh_clean since it removes
676
691
# the log earlier.)
677
692
if ($override_command ne 'dh_clean') {
added
removed
dh
