5 dh - debhelper command sequencer
10 use Debian::Debhelper::Dh_Lib;
14 B<dh> I<sequence> [B<--with> I<addon>[B<,>I<addon> ...]] [B<--list>] [S<I<debhelper options>>]
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
31 target. The override target can then run the command with additional options,
32 or run entirely different commands instead. See examples below. (Note that to
33 use this feature, you should Build-Depend on debhelper 7.0.50 or above.)
39 =item B<--with> I<addon>[B<,>I<addon> ...]
41 Add the debhelper commands specified by the given addon to appropriate places
42 in the sequence of commands that is run. This option can be repeated more
43 than once, or multiple addons can be listed, separated by commas.
44 This is used when there is a third-party package that provides
45 debhelper commands. See the F<PROGRAMMING> file for documentation about
46 the sequence addon interface.
48 =item B<--without> I<addon>
50 The inverse of B<--with>, disables using the given addon.
52 =item B<--list>, B<-l>
54 List all available addons.
58 Prints commands that would run for a given sequence, but does not run them.
62 Other options passed to B<dh> are passed on to each command it runs. This
63 can be used to set an option like B<-v> or B<-X> or B<-N>, as well as for more
68 To see what commands are included in a sequence, without actually doing
71 dh binary-arch --no-act
73 This is a very simple rules file, for packages where the default sequences of
74 commands work with no additional options.
80 Often you'll want to pass an option to a specific debhelper command. The
81 easy way to do with is by adding an override target for that command.
90 override_dh_installdocs:
91 dh_installdocs README TODO
93 Sometimes the automated L<dh_auto_configure(1)> and L<dh_auto_build(1)>
94 can't guess what to do for a strange package. Here's how to avoid running
95 either and instead run your own commands.
101 override_dh_auto_configure:
104 override_dh_auto_build:
105 make universe-explode-in-delight
107 Another common case is wanting to do something manually before or
108 after a particular debhelper command is run.
114 override_dh_fixperms:
116 chmod 4755 debian/foo/usr/bin/foo
118 Python tools are not run by dh by default, due to the continual change
119 in that area. (Before compatability level v9, dh does run B<dh_pysupport>.)
120 Here is how to use B<dh_python2>.
126 If your package uses autotools and you want to freshen F<config.sub> and
127 F<config.guess> with newer versions from the B<autotools-dev> package
128 at build time, you can use some commands provided in B<autotools-dev>
129 that automate it, like this.
133 dh $@ --with autotools_dev
135 Here is how to force use of Perl's B<Module::Build> build system,
136 which can be necessary if debhelper wrongly detects that the package
141 dh $@ --buildsystem=perl_build
143 To patch your package using quilt, you can tell B<dh> to use quilt's B<dh>
144 sequence addons like this:
150 Here is an example of overriding where the B<dh_auto_>I<*> commands find
151 the package's source, for a package where the source is located in a
156 dh $@ --sourcedirectory=src
158 And here is an example of how to tell the B<dh_auto_>I<*> commands to build
159 in a subdirectory, which will be removed on B<clean>.
163 dh $@ --builddirectory=build
165 If your package can be built in parallel, you can support parallel building
166 as follows. Then B<dpkg-buildpackage -j> will work.
172 Here is a way to prevent B<dh> from running several commands that you don't
173 want it to run, by defining empty override targets for each command.
179 # Commands not to run:
180 override_dh_auto_test override_dh_compress override_dh_fixperms:
182 Sometimes, you may need to make an override target only run commands when a
183 particular package is being built. This can be accomplished using
184 L<dh_listpackages(1)> to test what is being built. For example:
190 override_dh_fixperms:
192 ifneq (,$(filter foo, $(shell dh_listpackages)))
193 chmod 4755 debian/foo/usr/bin/foo
196 Finally, remember that you are not limited to using override targets in the
197 rules file when using B<dh>. You can also explicitly define any of the regular
198 rules file targets when it makes sense to do so. A common reason to do this
199 is when your package needs different B<build-arch> and B<build-indep> targets.
200 For example, a package with a long document build process can put it in
212 Note that in the example above, dh will arrange for "debian/rules build"
213 to call your build-indep and build-arch targets. You do not need to
214 explicitly define those dependencies in the rules file when using dh with
215 compatibility level v9. This example would be more complicated with
216 earlier compatibility levels.
220 If you're curious about B<dh>'s internals, here's how it works under the hood.
222 Each debhelper command will record when it's successfully run in
223 F<debian/package.debhelper.log>. (Which B<dh_clean> deletes.) So B<dh> can tell
224 which commands have already been run, for which packages, and skip running
225 those commands again.
227 Each time B<dh> is run, it examines the log, and finds the last logged command
228 that is in the specified sequence. It then continues with the next command
229 in the sequence. The B<--until>, B<--before>, B<--after>, and B<--remaining>
230 options can override this behavior.
232 A sequence can also run dependent targets in debian/rules. For
233 example, the "binary" sequence runs the "install" target.
235 B<dh> uses the B<DH_INTERNAL_OPTIONS> environment variable to pass information
236 through to debhelper commands that are run inside override targets. The
237 contents (and indeed, existence) of this environment variable, as the name
238 might suggest, is subject to change at any time.
240 =head1 DEPRECATED OPTIONS
242 The following options are deprecated. It's much
243 better to use override targets instead.
247 =item B<--until> I<cmd>
249 Run commands in the sequence until and including I<cmd>, then stop.
251 =item B<--before> I<cmd>
253 Run commands in the sequence before I<cmd>, then stop.
255 =item B<--after> I<cmd>
257 Run commands in the sequence that come after I<cmd>.
261 Run all commands in the sequence that have yet to be run.
265 In the above options, I<cmd> can be a full name of a debhelper command, or
266 a substring. It'll first search for a command in the sequence exactly
267 matching the name, to avoid any ambiguity. If there are multiple substring
268 matches, the last one in the sequence will be used.
272 # Stash this away before init modifies it.
276 # python-support was enabled by default before v9.
277 # (and comes first so python-central loads later and can disable it).
278 unshift @ARGV, "--with=python-support";
282 "until=s" => \$dh{UNTIL},
283 "after=s" => \$dh{AFTER},
284 "before=s" => \$dh{BEFORE},
285 "remaining" => \$dh{REMAINING},
287 my ($option,$value)=@_;
288 push @{$dh{WITH}},split(",", $value);
291 my ($option,$value)=@_;
292 @{$dh{WITH}} = grep { $_ ne $value } @{$dh{WITH}};
294 "l" => \&list_addons,
295 "list" => \&list_addons,
297 # Disable complaints about unknown options; they are passed on to
298 # the debhelper commands.
299 ignore_unknown_options => 1,
300 # Bundling does not work well since there are unknown options.
307 # If make is using a jobserver, but it is not available
308 # to this process, clean out MAKEFLAGS. This avoids
309 # ugly warnings when calling make.
310 if (is_make_jobserver_unavailable()) {
311 clean_jobserver_makeflags();
314 # Process the sequence parameter.
317 # From v8, the sequence is the very first parameter.
318 $sequence=shift @ARGV_orig;
319 if (defined $sequence && $sequence=~/^-/) {
320 error "Unknown sequence $sequence (options should not come before the sequence)";
324 # Before v8, the sequence could be at any position in the parameters,
325 # so was what was left after parsing.
327 if (defined $sequence) {
328 @ARGV_orig=grep { $_ ne $sequence } @ARGV_orig;
331 if (! defined $sequence) {
332 error "specify a sequence to run";
334 # make -B causes the rules file to be run as a target.
335 # Also support completly empty override targets.
336 # Note: it's not safe to use rules_explicit_target before this check,
337 # since it causes dh to be run.
338 my $dummy_target="debhelper-fail-me";
339 if ($sequence eq 'debian/rules' ||
340 $sequence =~ /^override_dh_/ ||
341 $sequence eq $dummy_target) {
346 # Definitions of sequences.
404 if (! getpackages("arch")) {
413 $sequences{clean} = [qw{
418 $sequences{'build-indep'} = [@bd];
419 $sequences{'build-arch'} = [@bd];
421 # From v9, sequences take standard rules targets into account.
422 $sequences{build} = [@bd_minimal, rules("build-arch"), rules("build-indep")];
423 $sequences{'install-indep'} = [rules("build-indep"), @i];
424 $sequences{'install-arch'} = [rules("build-arch"), @i];
425 $sequences{'install'} = [rules("build"), rules("install-arch"), rules("install-indep"), @i];
426 $sequences{'binary-indep'} = [rules("install-indep"), @b];
427 $sequences{'binary-arch'} = [rules("install-arch"), @ba, @b];
428 $sequences{binary} = [rules("install"), rules("binary-arch"), rules("binary-indep")];
431 $sequences{build} = [@bd];
432 $sequences{'install'} = [@{$sequences{build}}, @i];
433 $sequences{'install-indep'} = [@{$sequences{'build-indep'}}, @i];
434 $sequences{'install-arch'} = [@{$sequences{'build-arch'}}, @i];
435 $sequences{binary} = [@{$sequences{install}}, @ba, @b];
436 $sequences{'binary-indep'} = [@{$sequences{'install-indep'}}, @b];
437 $sequences{'binary-arch'} = [@{$sequences{'install-arch'}}, @ba, @b];
440 # Additional command options
443 # sequence addon interface
448 foreach my $sequence (keys %sequences) {
449 my @list=@{$sequences{$sequence}};
450 next unless grep $existing, @list;
452 foreach my $command (@list) {
453 if ($command eq $existing) {
454 push @new, $new if $offset < 0;
456 push @new, $new if $offset > 0;
462 $sequences{$sequence}=\@new;
473 foreach my $sequence (keys %sequences) {
474 $sequences{$sequence}=[grep { $_ ne $command } @{$sequences{$sequence}}];
481 unshift @{$sequences{$sequence}}, $command;
483 sub add_command_options {
485 push @{$command_opts{$command}}, @_;
487 sub remove_command_options {
490 # Remove only specified options
491 if (my $opts = $command_opts{$command}) {
492 foreach my $opt (@_) {
493 $opts = [ grep { $_ ne $opt } @$opts ];
495 $command_opts{$command} = $opts;
499 # Clear all additional options
500 delete $command_opts{$command};
508 eval q{use File::Spec};
509 my $path = File::Spec->catdir($inc, "Debian/Debhelper/Sequence");
511 for my $module_path (glob "$path/*.pm") {
512 my $name = basename($module_path);
520 for my $name (sort keys %addons) {
527 # Load addons, which can modify sequences.
528 foreach my $addon (@{$dh{WITH}}) {
529 my $mod="Debian::Debhelper::Sequence::$addon";
533 error("unable to load addon $addon: $@");
537 if (! exists $sequences{$sequence}) {
538 error "Unknown sequence $sequence (choose from: ".
539 join(" ", sort keys %sequences).")";
541 my @sequence=optimize_sequence(@{$sequences{$sequence}});
543 # The list of all packages that can be acted on.
544 my @packages=@{$dh{DOPACKAGES}};
546 # Get the options to pass to commands in the sequence.
547 # Filter out options intended only for this program.
549 if ($sequence eq 'build-arch' ||
550 $sequence eq 'install-arch' ||
551 $sequence eq 'binary-arch') {
553 # as an optimisation, remove from the list any packages
554 # that are not arch dependent
555 my %arch_packages = map { $_ => 1 } getpackages("arch");
556 @packages = grep { $arch_packages{$_} } @packages;
558 elsif ($sequence eq 'build-indep' ||
559 $sequence eq 'install-indep' ||
560 $sequence eq 'binary-indep') {
562 # ditto optimisation for arch indep
563 my %indep_packages = map { $_ => 1 } getpackages("indep");
564 @packages = grep { $indep_packages{$_} } @packages;
567 my $opt=shift @ARGV_orig;
568 if ($opt =~ /^--?(after|until|before|with|without)$/) {
572 elsif ($opt =~ /^--?(no-act|remaining|(after|until|before|with|without)=)/) {
576 push @options, "-O".$opt;
579 if ($options[$#options]=~/^-O--/) {
580 $options[$#options].="=".$opt;
583 $options[$#options].=$opt;
588 # Figure out at what point in the sequence to start for each package.
591 foreach my $package (@packages) {
592 my @log=load_log($package, \%logged);
594 # Run commands in the sequence that come after the
596 $startpoint{$package}=command_pos($dh{AFTER}, @sequence) + 1;
597 # Write a dummy log entry indicating that the specified
598 # command was, in fact, run. This handles the case where
599 # no commands remain to run after it, communicating to
600 # future dh instances that the specified command should not
602 write_log($sequence[$startpoint{$package}-1], $package);
604 elsif ($dh{REMAINING}) {
605 # Start at the beginning so all remaining commands will get
607 $startpoint{$package}=0;
610 # Find the last logged command that is in the sequence, and
611 # continue with the next command after it. If no logged
612 # command is in the sequence, we're starting at the beginning..
613 $startpoint{$package}=0;
614 COMMAND: foreach my $command (reverse @log) {
615 foreach my $i (0..$#sequence) {
616 if ($command eq $sequence[$i]) {
617 $startpoint{$package}=$i+1;
625 # Figure out what point in the sequence to go to.
626 my $stoppoint=$#sequence;
628 $stoppoint=command_pos($dh{UNTIL}, @sequence);
630 elsif ($dh{BEFORE}) {
631 $stoppoint=command_pos($dh{BEFORE}, @sequence) - 1;
634 # Now run the commands in the sequence.
635 foreach my $i (0..$stoppoint) {
636 # Figure out which packages need to run this command.
638 foreach my $package (@packages) {
639 if ($startpoint{$package} > $i ||
640 $logged{$package}{$sequence[$i]}) {
641 push @exclude, $package;
645 if (@exclude eq @packages) {
646 # Command already done for all packages.
650 run($sequence[$i], \@packages, \@exclude, @options);
655 my @packages=@{shift()};
656 my @exclude=@{shift()};
659 # If some packages are excluded, add flags
660 # to prevent them from being acted on.
661 push @options, map { "-N$_" } @exclude;
663 # Check for override targets in debian/rules and
664 # run them instead of running the command directly.
665 my $override_command;
666 my $has_explicit_target = rules_explicit_target("override_".$command);
668 my $rules_target = rules_target($command);
669 if (defined $rules_target) {
670 # Don't pass DH_ environment variables, since this is
671 # a fresh invocation of debian/rules and any sub-dh
673 $override_command=$command;
674 delete $ENV{DH_INTERNAL_OPTIONS};
675 delete $ENV{DH_INTERNAL_OVERRIDE};
676 $command="debian/rules";
677 @options=$rules_target;
679 elsif (defined $has_explicit_target) {
680 $override_command=$command;
681 # Check if target isn't noop
682 if ($has_explicit_target) {
683 # This passes the options through to commands called
685 $ENV{DH_INTERNAL_OPTIONS}=join("\x1e", @options);
686 $ENV{DH_INTERNAL_OVERRIDE}=$command;
687 $command="debian/rules";
688 @options="override_".$override_command;
695 # Pass additional command options if any
696 unshift @options, @{$command_opts{$command}} if exists $command_opts{$command};
699 if (defined $command) {
700 # 3 space indent lines the command being run up under the
701 # sequence name after "dh ".
702 print " ".escape_shell($command, @options)."\n";
705 print " ", "# Skipping ", $override_command, " - empty override", "\n";
709 if (defined $command) {
710 my $ret=system($command, @options);
712 if ($ret >> 8 != 0) {
720 if (defined $override_command) {
721 # Update log for overridden command now that it has
722 # finished successfully.
723 # (But avoid logging for dh_clean since it removes
725 if ($override_command ne 'dh_clean') {
726 my %packages=map { $_ => 1 } @packages;
727 map { delete $packages{$_} } @exclude;
728 write_log($override_command, keys %packages);
729 commit_override_log(keys %packages);
732 delete $ENV{DH_INTERNAL_OPTIONS};
733 delete $ENV{DH_INTERNAL_OVERRIDE};
738 sub optimize_sequence {
742 # commands can appear multiple times when sequences are
743 # inlined together; only the first should be needed
745 if (! $seen{$command}) {
747 push @sequence, $command;
750 foreach my $command (@_) {
751 my $rules_target=rules_target($command);
752 if (defined $rules_target &&
753 ! defined rules_explicit_target($rules_target)) {
754 # inline the sequence for this implicit target
755 $add->($_) foreach optimize_sequence(@{$sequences{$rules_target}});
766 if ($command =~ /^debian\/rules\s+(.*)/) {
775 return "debian/rules ".join(" ", @_);
782 sub rules_explicit_target {
783 # Checks if a specified target exists as an explicit target
785 # undef is returned if target does not exist, 0 if target is noop
786 # and 1 if target has dependencies or executes commands.
789 if (! $rules_parsed) {
790 my $processing_targets = 0;
791 my $not_a_target = 0;
793 open(MAKE, "LC_ALL=C make -Rrnpsf debian/rules $dummy_target 2>/dev/null |");
795 if ($processing_targets) {
796 if (/^# Not a target:/) {
800 if (!$not_a_target && /^([^#:]+)::?\s*(.*)$/) {
801 # Target is defined. NOTE: if it is a depenency of
802 # .PHONY it will be defined too but that's ok.
803 # $2 contains target dependencies if any.
804 $current_target = $1;
805 $targets{$current_target} = ($2) ? 1 : 0;
808 if (defined $current_target) {
810 # Check if target has commands to execute
811 if (/^#\s*(commands|recipe) to execute/) {
812 $targets{$current_target} = 1;
817 $current_target = undef;
821 # "Not a target:" is always followed by
822 # a target name, so resetting this one
827 elsif (/^# Files$/) {
828 $processing_targets = 1;
835 return $targets{$target};
840 sub warn_deprecated {
841 foreach my $deprecated ('until', 'after', 'before', 'remaining') {
842 if (defined $dh{uc $deprecated}) {
843 warning("The --$deprecated option is deprecated. Use override targets instead.");
852 foreach my $i (0..$#sequence) {
853 if ($command eq $sequence[$i]) {
859 foreach my $i (0..$#sequence) {
860 if ($sequence[$i] =~ /\Q$command\E/) {
865 error "command specification \"$command\" does not match any command in the sequence"
876 This program is a part of debhelper.
880 Joey Hess <joeyh@debian.org>