path: root/dh

#!/usr/bin/perl

=head1 NAME

dh - debhelper command sequencer

=cut

use strict;
use warnings;
use constant {
	'UNSKIPPABLE_CLI_OPTIONS_BUILD_SYSTEM' => q(-S|--buildsystem|-D|--sourcedir(?:ectory)?|-B|--builddir(?:ectory)?),
};
use Debian::Debhelper::Dh_Lib;
use Debian::Debhelper::SequencerUtil;

our $VERSION = DH_BUILTIN_VERSION;

=head1 SYNOPSIS

B<dh> I<sequence> [B<--with> I<addon>[B<,>I<addon> ...]] [B<--list>] [S<I<debhelper options>>]

=head1 DESCRIPTION

B<dh> runs a sequence of debhelper commands. The supported I<sequence>s
correspond to the targets of a F<debian/rules> file: B<build-arch>,
B<build-indep>, B<build>, B<clean>, B<install-indep>, B<install-arch>,
B<install>, B<binary-arch>, B<binary-indep>, and B<binary>.

=head1 OVERRIDE TARGETS

A F<debian/rules> file using B<dh> can override the command that is run
at any step in a sequence, by defining an override target.

To override I<dh_command>, add a target named B<override_>I<dh_command> to
the rules file. When it would normally run I<dh_command>, B<dh> will
instead call that target. The override target can then run the command with
additional options, or run entirely different commands instead. See
examples below.

Override targets can also be defined to run only when building
architecture dependent or architecture independent packages.
Use targets with names like B<override_>I<dh_command>B<-arch>
and B<override_>I<dh_command>B<-indep>.
(Note that to use this feature, you should Build-Depend on
debhelper 8.9.7 or above.)

=head1 OPTIONS

=over 4

=item B<--with> I<addon>[B<,>I<addon> ...]

Add the debhelper commands specified by the given addon to appropriate places
in the sequence of commands that is run. This option can be repeated more
than once, or multiple addons can be listed, separated by commas.
This is used when there is a third-party package that provides
debhelper commands. See the F<PROGRAMMING> file for documentation about
the sequence addon interface.

A B<Build-Depends> relation on the package B<dh-sequence->I<addon>
implies a B<--with> I<addon>. This avoids the need for an explicit
B<--with> in F<debian/rules> that only duplicates what is already
declared via the build dependencies in F<debian/control>.  Note that
only relations in the B<Build-Depends> field are considered
(i.e. B<Build-Depends-Indep> and B<Build-Depends-Arch> are
deliberately unsupported).  Please keep in mind that B<dh> insists on
"simple" relations (e.g. a relation like "B<dh-sequence->I<addon> |
B<some-other-pkg>" will I<not> imply B<--with> I<addon>).

=item B<--without> I<addon>

The inverse of B<--with>, disables using the given addon. This option
can be repeated more than once, or multiple addons to disable can be
listed, separated by commas.

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

List all available addons.

When called only with this option, B<dh> can be called from any
directory (i.e. it does not need access to files from a source
package).

=item B<--no-act>

Prints commands that would run for a given sequence, but does not run them.

Note that dh normally skips running commands that it knows will do nothing.
With --no-act, the full list of commands in a sequence is printed.

=back

Other options passed to B<dh> are passed on to each command it runs. This
can be used to set an option like B<-v> or B<-X> or B<-N>, as well as for more
specialised options.

=head1 EXAMPLES

To see what commands are included in a sequence, without actually doing
anything:

	dh binary-arch --no-act

This is a very simple rules file, for packages where the default sequences of
commands work with no additional options.

	#!/usr/bin/make -f
	%:
		dh $@

Often you'll want to pass an option to a specific debhelper command. The
easy way to do with is by adding an override target for that command.

	#!/usr/bin/make -f
	%:
		dh $@

	override_dh_strip:
		dh_strip -Xfoo

	override_dh_auto_configure:
		dh_auto_configure -- --with-foo --disable-bar

Sometimes the automated L<dh_auto_configure(1)> and L<dh_auto_build(1)>
can't guess what to do for a strange package. Here's how to avoid running
either and instead run your own commands.

	#!/usr/bin/make -f
	%:
		dh $@

	override_dh_auto_configure:
		./mondoconfig

	override_dh_auto_build:
		make universe-explode-in-delight

Another common case is wanting to do something manually before or
after a particular debhelper command is run.

	#!/usr/bin/make -f
	%:
		dh $@

	override_dh_fixperms:
		dh_fixperms
		chmod 4755 debian/foo/usr/bin/foo

Python tools are not run by dh by default, due to the continual change
in that area. Here is how to use B<dh_python2>.

	#!/usr/bin/make -f
	%:
		dh $@ --with python2

Here is how to force use of Perl's B<Module::Build> build system,
which can be necessary if debhelper wrongly detects that the package
uses MakeMaker.

	#!/usr/bin/make -f
	%:
		dh $@ --buildsystem=perl_build

Here is an example of overriding where the B<dh_auto_>I<*> commands find
the package's source, for a package where the source is located in a
subdirectory.

	#!/usr/bin/make -f
	%:
		dh $@ --sourcedirectory=src

And here is an example of how to tell the B<dh_auto_>I<*> commands to build
in a subdirectory, which will be removed on B<clean>.

	#!/usr/bin/make -f
	%:
		dh $@ --builddirectory=build

If your package can be built in parallel, please either use compat 10 or
pass B<--parallel> to dh. Then B<dpkg-buildpackage -j> will work.

	#!/usr/bin/make -f
	%:
		dh $@ --parallel

If your package cannot be built reliably while using multiple threads,
please pass B<--no-parallel> to dh (or the relevant B<dh_auto_>I<*>
command):


	#!/usr/bin/make -f
	%:
		dh $@ --no-parallel

Here is a way to prevent B<dh> from running several commands that you don't
want it to run, by defining empty override targets for each command.

	#!/usr/bin/make -f
	%:
		dh $@

	# Commands not to run:
	override_dh_auto_test override_dh_compress override_dh_fixperms:

A long build process for a separate documentation package can
be separated out using architecture independent overrides.
These will be skipped when running build-arch and binary-arch sequences.

	#!/usr/bin/make -f
	%:
		dh $@

	override_dh_auto_build-indep:
		$(MAKE) -C docs

	# No tests needed for docs
	override_dh_auto_test-indep:

	override_dh_auto_install-indep:
		$(MAKE) -C docs install

Adding to the example above, suppose you need to chmod a file, but only
when building the architecture dependent package, as it's not present
when building only documentation.

	override_dh_fixperms-arch:
		dh_fixperms
		chmod 4755 debian/foo/usr/bin/foo

=head1 INTERNALS

If you're curious about B<dh>'s internals, here's how it works under the hood.

In compat 10 (or later), B<dh> creates a stamp file
F<debian/debhelper-build-stamp> after the build step(s) are complete
to avoid re-running them.  It is possible to avoid the stamp file by
passing B<--without=build-stamp> to B<dh>.  This makes "no clean"
builds behave more like what some people expect at the expense of
possibly running the build and test twice (the second time as root or
under L<fakeroot(1)>).

Inside an override target, B<dh_*> commands will create a log file
F<debian/package.debhelper.log> to keep track of which packages the
command(s) have been run for.  These log files are then removed once
the override target is complete.

In compat 9 or earlier, each debhelper command will record
when it's successfully run in F<debian/package.debhelper.log>. (Which
B<dh_clean> deletes.) So B<dh> can tell which commands have already
been run, for which packages, and skip running those commands again.

Each time B<dh> is run (in compat 9 or earlier), it examines the log,
and finds the last logged command that is in the specified
sequence. It then continues with the next command in the sequence.

A sequence can also run dependent targets in debian/rules.  For
example, the "binary" sequence runs the "install" target.

B<dh> uses the B<DH_INTERNAL_OPTIONS> environment variable to pass information
through to debhelper commands that are run inside override targets. The
contents (and indeed, existence) of this environment variable, as the name
might suggest, is subject to change at any time.

Commands in the B<build-indep>, B<install-indep> and B<binary-indep>
sequences are passed the B<-i> option to ensure they only work on
architecture independent packages, and commands in the B<build-arch>,
B<install-arch> and B<binary-arch> sequences are passed the B<-a>
option to ensure they only work on architecture dependent packages.

=cut

# Stash this away before init modifies it.
my @ARGV_orig=@ARGV;
my (@addons, @addon_requests);

inhibit_log();

init(options => {
		"until=s" => \$dh{UNTIL},
		"after=s" => \$dh{AFTER},
		"before=s" => \$dh{BEFORE},
		"remaining" => \$dh{REMAINING},
		"with=s" => sub {
			my ($option, $value) = @_;
			push(@addon_requests, map { "+${_}" } split(",", $value));
		},
		"without=s" => sub {
			my ($option, $value) = @_;
			push(@addon_requests, map { "-${_}" } split(",", $value));
		},
		"l" => \&list_addons,
		"list" => \&list_addons,
	},
	# Disable complaints about unknown options; they are passed on to
	# the debhelper commands.
	ignore_unknown_options => 1,
	# Bundling does not work well since there are unknown options.
	bundling => 0,
);
set_buildflags();
reject_obsolete_params();

# If make is using a jobserver, but it is not available
# to this process, clean out MAKEFLAGS. This avoids
# ugly warnings when calling make.
if (is_make_jobserver_unavailable()) {
	clean_jobserver_makeflags();
}

# Process the sequence parameter.
my $sequence;
if (! compat(7)) {
	# From v8, the sequence is the very first parameter.
	$sequence=shift @ARGV_orig;
	if (defined $sequence && $sequence=~/^-/) {
		error "Unknown sequence $sequence (options should not come before the sequence)";
	}
}
else {
	# Before v8, the sequence could be at any position in the parameters,
	# so was what was left after parsing.
	$sequence=shift;
	if (defined $sequence) {
		@ARGV_orig=grep { $_ ne $sequence } @ARGV_orig;
	}
}
if (! defined $sequence) {
	error "specify a sequence to run";
}
# make -B causes the rules file to be run as a target.
# Also support completely empty override targets.
# Note: it's not safe to use rules_explicit_target before this check,
# since it causes dh to be run.
if ($sequence eq 'debian/rules' ||
    $sequence =~ /^override_dh_/ ||
    $sequence eq DUMMY_TARGET) {
	exit 0;
}


# Definitions of sequences.
my $build_stamp_file = 'debian/debhelper-build-stamp';
my %sequences;
my @bd_minimal = qw{
	dh_testdir
};
my @bd = (@bd_minimal, qw{
	dh_update_autotools_config
	dh_auto_configure
	dh_auto_build
	dh_auto_test
});
my @i = (qw{
	dh_testroot
	dh_prep
	dh_installdirs
	dh_auto_install

	dh_install
	dh_installdocs
	dh_installchangelogs
	dh_installexamples
	dh_installman

	dh_installcatalogs
	dh_installcron
	dh_installdebconf
	dh_installemacsen
	dh_installifupdown
	dh_installinfo
	dh_installinit
},
   (!compat(10) ? qw(dh_installsystemd) : qw()),
   (!compat(11) ? qw(dh_installsystemduser) : qw()),

qw{
	dh_installmenu
	dh_installmime
	dh_installmodules
	dh_installlogcheck
	dh_installlogrotate
	dh_installpam
	dh_installppp
	dh_installudev
	dh_installgsettings
},
   (!compat(11) ? qw(dh_installinitramfs) : qw()),
qw{
	dh_bugfiles
	dh_ucf
	dh_lintian
	dh_gconf
	dh_icons
	dh_perl
	dh_usrlocal

	dh_link
	dh_installwm
	dh_installxfonts
	dh_strip_nondeterminism
	dh_compress
	dh_fixperms
	dh_missing
});
my @ba=(
	(!compat(11) ? qw(dh_dwz) : qw()),
qw{
	dh_strip
	dh_makeshlibs
	dh_shlibdeps
});
if (! getpackages("arch")) {
	@ba=();
}
my @b=qw{
	dh_installdeb
	dh_gencontrol
	dh_md5sums
	dh_builddeb
};
$sequences{clean} = [@bd_minimal, qw{
	dh_auto_clean
	dh_clean
}];
$sequences{'build-indep'} = [@bd];
$sequences{'build-arch'} = [@bd];
$sequences{build} = [to_rules_target("build-arch"), to_rules_target("build-indep")];
$sequences{'install-indep'} = [to_rules_target("build-indep"), @i];
$sequences{'install-arch'} = [to_rules_target("build-arch"), @i];
$sequences{'install'} = [to_rules_target("build"), to_rules_target("install-arch"), to_rules_target("install-indep")];
$sequences{'binary-indep'} = [to_rules_target("install-indep"), @b];
$sequences{'binary-arch'} = [to_rules_target("install-arch"), @ba, @b];
$sequences{binary} = [to_rules_target("install"), to_rules_target("binary-arch"), to_rules_target("binary-indep")];

# Additional command options
my %command_opts;

# sequence addon interface
sub _insert {
	my ($offset, $existing, $new) = @_;
	foreach my $sequence (keys %sequences) {
		my @list=@{$sequences{$sequence}};
		next unless grep $existing, @list;
		my @new;
		foreach my $command (@list) {
			if ($command eq $existing) {
				push @new, $new if $offset < 0;
				push @new, $command;
				push @new, $new if $offset > 0;
			}
			else {
				push @new, $command;
			}
		}
		$sequences{$sequence}=\@new;
	}
}
sub insert_before {
	_insert(-1, @_);
}
sub insert_after {
	_insert(1, @_);
}
sub remove_command {
	my ($command) = @_;
	foreach my $sequence (keys %sequences) {
		$sequences{$sequence}=[grep { $_ ne $command } @{$sequences{$sequence}}];
	}

}
sub add_command {
	my ($command, $sequence) = @_;
	unshift @{$sequences{$sequence}}, $command;
}
sub add_command_at_end {
	my ($command, $sequence) = @_;
	push(@{$sequences{$sequence}}, $command);
}
sub add_command_options {
	my $command=shift;
	push @{$command_opts{$command}}, @_;
}
sub remove_command_options {
	my ($command, @cmd_options) = @_;
	if (@cmd_options) {
		# Remove only specified options
		if (my $opts = $command_opts{$command}) {
			foreach my $opt (@cmd_options) {
				$opts = [ grep { $_ ne $opt } @$opts ];
			}
			$command_opts{$command} = $opts;
		}
	}
	else {
		# Clear all additional options
		delete $command_opts{$command};
	}
}

sub list_addons {
	my %addons;

	for my $inc (@INC) {
		require File::Spec;
		my $path = File::Spec->catdir($inc, "Debian/Debhelper/Sequence");
		if (-d $path) {
			for my $module_path (glob "$path/*.pm") {
				my $name = basename($module_path);
				$name =~ s/\.pm$//;
				$name =~ s/_/-/g;
				$addons{$name} = 1;
			}
		}
	}

	for my $name (sort keys %addons) {
		print "$name\n";
	}

	exit 0;
}

sub _compute_addons {
	my (@addon_requests_from_args) = @_;
	my (@enabled_addons, %disabled_addons, %enabled);
	my @addon_requests;

	# Order is important; DH_EXTRA_ADDONS must come before everything
	# else; then comes built-in and finally argument provided add-ons
	# requests.
	push(@addon_requests,  map { "+${_}" } split(",", $ENV{DH_EXTRA_ADDONS}))
		if $ENV{DH_EXTRA_ADDONS};
	if (not compat(9, 1)) {
		# Enable autoreconf'ing by default in compat 10 or later.
		push(@addon_requests, '+autoreconf');

		# Enable systemd support by default in compat 10 or later.
		# - compat 11 injects the dh_installsystemd tool directly in the
		#   sequence instead of using a --with sequence.
		push(@addon_requests, '+systemd') if compat(10, 1);
		push(@addon_requests, '+build-stamp');
	}
	push(@addon_requests, map { "+${_}" } Debian::Debhelper::Dh_Lib::bd_dh_sequences());
	push(@addon_requests, @addon_requests_from_args);

	# Removing disabled add-ons are expensive (O(N) per time), so we
	# attempt to make removals in bulk.  Note that we have to be order
	# preserving (due to #885580), so there is a limit to how "smart"
	# we can be.
	my $flush_disable_cache = sub {
		@enabled_addons = grep { not exists($disabled_addons{$_}) } @enabled_addons;
		for my $addon (keys(%disabled_addons)) {
			delete($enabled{$addon});
		}
		%disabled_addons = ();
	};

	for my $request (@addon_requests) {
		if ($request =~ s/^[+]//) {
			$flush_disable_cache->() if %disabled_addons;
			push(@enabled_addons, $request) if not $enabled{$request}++;
		} elsif ($request =~ s/^-//) {
			$disabled_addons{$request} = 1;
		} else {
			error("Internal error: Invalid add-on request: $request (Missing +/- prefix)");
		}
	}

	$flush_disable_cache->() if %disabled_addons;
	return @enabled_addons;
}

@addons = _compute_addons(@addon_requests);

# Load addons, which can modify sequences.
foreach my $addon (@addons) {
	my $mod="Debian::Debhelper::Sequence::$addon";
	$mod=~s/-/_/g;
	eval "use $mod";
	if ($@) {
		error("unable to load addon $addon: $@");
	}
}

if (! exists $sequences{$sequence}) {
	error "Unknown sequence $sequence (choose from: ".
		join(" ", sort keys %sequences).")";
}

# The list of all packages that can be acted on.
my @packages=@{$dh{DOPACKAGES}};
my @arch_packages = getpackages("arch");
my @indep_packages = getpackages("indep");
my %sequence2packages = (
	'build-arch'   => \@arch_packages,
	'install-arch' => \@arch_packages,
	'binary-arch'  => \@arch_packages,

	'build-indep'   => \@indep_packages,
	'install-indep' => \@indep_packages,
	'binary-indep'  => \@indep_packages,

	'clean'   => \@packages,
	'build'   => \@packages,
	'install' => \@packages,
	'binary'  => \@packages,
);

my %completed_sequences;

# Get the options to pass to commands in the sequence.
# Filter out options intended only for this program.
my (@options, %seen_options);
my ($unoptimizable_user_option, $unoptimizable_option_bundle) = (0, 0);

if ($sequence eq 'build-arch' ||
    $sequence eq 'install-arch' ||
    $sequence eq 'binary-arch') {
	push @options, "-a";
	# as an optimisation, remove from the list any packages
	# that are not arch dependent
	@packages = @{$sequence2packages{$sequence}};
}
elsif ($sequence eq 'build-indep' ||
       $sequence eq 'install-indep' ||
       $sequence eq 'binary-indep') {
	push @options, "-i";
	# ditto optimisation for arch indep
	@packages = @{$sequence2packages{$sequence}};
}
while (@ARGV_orig) {
	my $opt=shift @ARGV_orig;
	if ($opt =~ /^--?(after|until|before|with|without)$/) {
		shift @ARGV_orig;
		next;
	}
	elsif ($opt =~ /^--?(no-act|remaining|(after|until|before|with|without)=)/) {
		next;
	}
	elsif ($opt=~/^-/) {
		if (not @options and $opt eq '--parallel' or $opt eq '--no-parallel') {
			my $max_parallel;
			# Ignore the option if it is the default for the given
			# compat level.
			next if compat(9) and $opt eq '--no-parallel';
			next if not compat(9) and $opt eq '--parallel';
			# Having an non-empty "@options" hurts performance quite a
			# bit.  At the same time, we want to promote the use of
			# --(no-)parallel, so "tweak" the options a bit if there
			# is no reason to include this option.
			$max_parallel = get_buildoption('parallel') // 1;
			next if $max_parallel == 1;
		}
		if ($opt =~ m/^(--[^=]++)(?:=.*)?$/ or $opt =~ m/^(-[^-])$/) {
			my $optname = $1;
			if (length($optname) > 2 and (compat(12, 1) or m/^-[^-][^=]/)) {
				# We cannot optimize bundled options but we can optimize a single
				# short option with an explicit parameter (-B=F is ok, -BF is not)
				# In compat 12 or earlier, we also punt on long options due to
				# auto-abbreviation.
				$unoptimizable_option_bundle = 1
			}
			$seen_options{$optname} = 1;
		} else {
			$unoptimizable_user_option = 1;
		}
		push @options, "-O".$opt;
	}
	elsif (@options) {
		if ($options[$#options]=~/^-O--/) {
			$options[$#options].="=".$opt;
		}
		else {
			$unoptimizable_user_option = 1;
			$options[$#options].=$opt;
		}
	}
	else {
		error "Unknown parameter: $opt";
	}
}

# Figure out at what point in the sequence to start for each package.
my (%logged, %startpoint, %stamp_file);

if ( -f $build_stamp_file and not compat(9)) {
	open(my $fd, '<', $build_stamp_file) or error("open($build_stamp_file, ro) failed: $!");
	while (my $line = <$fd>) {
		chomp($line);
		$stamp_file{$line} = 1;
	}
	close($fd);
	my $build_indep_target_done = 1;
	my $build_arch_target_done = 1;
	for my $pkg (@{$sequence2packages{'build-arch'}}) {
		if (not $stamp_file{$pkg}) {
			$build_arch_target_done = 0;
			last;
		}
	}
	for my $pkg (@{$sequence2packages{'build-indep'}}) {
		if (not $stamp_file{$pkg}) {
			$build_indep_target_done = 0;
			last;
		}
	}
	$completed_sequences{'build-arch'} = 1 if $build_arch_target_done;
	$completed_sequences{'build-indep'} = 1 if $build_indep_target_done;
	$completed_sequences{'build'} = 1 if $build_indep_target_done and $build_arch_target_done;
}

# In compat <= 8, the sequences are always inlined (those versions do not
# recurse into debian/rules anyway).  In compat 9+, we never inline an
# existing rules target.
my ($rules_targets, $full_sequence) = unpack_sequence(\%sequences,
														$sequence,
														(!compat(8) ? 0 : 1),
														\%completed_sequences
														);
my $stoppoint = $#{$full_sequence};

if (compat(9)) {
	foreach my $package (@packages) {
		my @log = load_log($package, \%logged);
		# Find the last logged command that is in the sequence, and
		# continue with the next command after it. If no logged
		# command is in the sequence, we're starting at the beginning..
		$startpoint{$package} = 0;
		COMMAND:
		foreach my $command (reverse @log) {
			foreach my $i (0 .. $#{$full_sequence}) {
				if ($command eq $full_sequence->[$i]) {
					$startpoint{$package} = $i + 1;
					last COMMAND;
				}
			}
		}
	}
} else {
	foreach my $package (@packages) {
		$startpoint{$package} = 0;
	}
}

for my $rules_command (@{$rules_targets}) {
	my $rules_target = extract_rules_target_name($rules_command)
		// error("Internal error: $rules_command was not a rules target!?");
	# Don't pass DH_ environment variables, since this is
	# a fresh invocation of debian/rules and any sub-dh commands.
	delete($ENV{DH_INTERNAL_OPTIONS});
	delete($ENV{DH_INTERNAL_OVERRIDE});
	run("debian/rules", $rules_target);
	my $override_packages = $sequence2packages{$rules_target} // \@packages;
	for my $package (@{$override_packages}) {
		my (undef, $seq) = unpack_sequence(\%sequences, $rules_target, 1);
		COMMAND: for my $c (reverse(@{$seq})) {
			for my $j (0 .. $#{$full_sequence}) {
				if ($c eq $full_sequence->[$j]) {
					# Unfortunately, we do not guarantee any order
					# between the run targets.  Assuming e.g.
					# "install-arch" and "build" are opague targets
					# then we could process "install-arch" first and
					# then "build".  In this case, it is important
					# that we do not "reset" the starting point for
					# "arch" packages.  Otherwise, we might repeat
					# part of the "install-arch" sequence when we
					# should not.
					$startpoint{$package} = $j + 1 if $j + 1 > $startpoint{$package};
					last COMMAND;
				}
			}
		}
	}
}

# Now run the commands in the sequence.
foreach my $i (0..$stoppoint) {
	my $command = $full_sequence->[$i];

	# Figure out which packages need to run this command.
	my @todo;
	my @opts=@options;
	foreach my $package (@packages) {
		if ($startpoint{$package} > $i ||
		    $logged{$package}{$full_sequence->[$i]}) {
			push @opts, "-N$package";
		}
		else {
			push @todo, $package;
		}
	}
	next unless @todo;

	my $rules_target = extract_rules_target_name($command);
	error("Internal error: $command is a rules target, but it is not supported to be!?") if defined($rules_target);

	if (my $stamp_file = stamp_target($command)) {
		my %seen;
		print "   create-stamp ".escape_shell($stamp_file)."\n";

		next if $dh{NO_ACT};
		open(my $fd, '+>>', $stamp_file) or error("open($stamp_file, rw) failed: $!");
		# Seek to the beginning
		seek($fd, 0, 0) or error("seek($stamp_file) failed: $!");
		while (my $line = <$fd>) {
			chomp($line);
			$seen{$line} = 1;
		}
		for my $pkg (grep { not exists $seen{$_} } @todo) {
			print {$fd} "$pkg\n";
		}
		close($fd) or error("close($stamp_file) failed: $!");
		next;
	}

	# Check for override targets in debian/rules, and run instead of
	# the usual command. (The non-arch-specific override is tried first,
	# for simplest semantics; mixing it with arch-specific overrides
	# makes little sense.)
	my @oldtodo=@todo;
	foreach my $override_type (undef, "arch", "indep") {
		@todo = run_override($override_type, $command, \@todo, @opts);
	}
	next unless @todo;

	next if can_skip($command, @todo);

	# No need to run the command for any packages handled by the
	# override targets.
	my %todo=map { $_ => 1 } @todo;
	foreach my $package (@oldtodo) {
		if (! $todo{$package}) {
			push @opts, "-N$package";
		}
	}

	run($command, @opts);
}

sub run {
	my ($command, @options) = @_;

	# Include additional command options if any
	unshift @options, @{$command_opts{$command}}
		if exists $command_opts{$command};

	# 3 space indent lines the command being run up under the
	# sequence name after "dh ".
	if (!$dh{QUIET}) {
		print "   ".escape_shell($command, @options)."\n";
	}

	return if $dh{NO_ACT};

	my $ret=system { $command } $command, @options;
	if ($ret >> 8 != 0) {
		exit $ret >> 8;
	}
	elsif ($ret) {
		exit 1;
	}
}

# Tries to run an override target for a command. Returns the list of
# packages that it was unable to run an override target for.
sub run_override {
	my ($override_type, $command, $packages, @options) = @_;

	my $override="override_$command".
		(defined $override_type ? "-".$override_type : "");

	# Check which packages are of the right architecture for the
	# override_type.
	my (@todo, @rest);
	my $has_explicit_target = rules_explicit_target($override);

	if (defined $override_type) {
		foreach my $package (@{$packages}) {
			my $isall=package_is_arch_all($package);
			if (($override_type eq 'indep' && $isall) ||
				($override_type eq 'arch' && !$isall)) {
				push @todo, $package;
			} else {
				push @rest, $package;
				push @options, "-N$package";
			}
		}
	}
	else {
		@todo=@{$packages};
	}

	return @{$packages} unless defined $has_explicit_target; # no such override
	return @rest if ! $has_explicit_target; # has empty override
	return @rest unless @todo; # has override, but no packages to act on

	if (defined $override_type) {
		# Ensure appropriate -a or -i option is passed when running
		# an arch-specific override target.
		my $opt=$override_type eq "arch" ? "-a" : "-i";
		push @options, $opt unless grep { $_ eq $opt } @options;
	}

	# Discard any override log files before calling the override
	# target
	if (not compat(9)) {
		my @files = glob('debian/*.debhelper.log');
		rm_files(@files) if @files;
	}
	# This passes the options through to commands called
	# inside the target.
	$ENV{DH_INTERNAL_OPTIONS}=join("\x1e", @options);
	$ENV{DH_INTERNAL_OVERRIDE}=$command;
	run("debian/rules", $override);
	delete $ENV{DH_INTERNAL_OPTIONS};
	delete $ENV{DH_INTERNAL_OVERRIDE};

	# Update log for overridden command now that it has
	# finished successfully.
	# (But avoid logging for dh_clean since it removes
	# the log earlier.)
	if (! $dh{NO_ACT} && $command ne 'dh_clean' && compat(9)) {
		write_log($command, @todo);
		commit_override_log(@todo);
	}

	# Override targets may introduce new helper files.  Strictly
	# speaking this *shouldn't* be necessary, but lets make no
	# assumptions.
	Debian::Debhelper::Dh_Lib::dh_clear_unsafe_cache();

	return @rest;
}

sub stamp_target {
	my ($command) = @_;
	if ($command =~ s/^create-stamp\s+//) {
		return $command;
	}
	return;
}


sub reject_obsolete_params {
	foreach my $deprecated ('until', 'after', 'before', 'remaining') {
		if (defined $dh{uc $deprecated}) {
			error("The --$deprecated option is not supported any longer (#932537). Use override targets instead.");
		}
	}
}

my %skipinfo;
sub can_skip {
	my ($command, @packages) = @_;

	return 0 if $dh{NO_ACT} and not $ENV{DH_INTERNAL_TEST_CAN_SKIP};

	return 0 if $unoptimizable_user_option ||
		(exists $ENV{DH_OPTIONS} && length $ENV{DH_OPTIONS});

	return 0 if exists($command_opts{$command})
		and @{$command_opts{$command}};

	if (! defined $skipinfo{$command}) {
		$skipinfo{$command}=[extract_skipinfo($command)];
	}
	my @skipinfo=@{$skipinfo{$command}};
	return 0 unless @skipinfo;
	return 1 if scalar(@skipinfo) == 1 and $skipinfo[0] eq 'always-skip';
	my ($all_pkgs, $had_cli_options);

	foreach my $skipinfo (@skipinfo) {
		my $type = 'pkgfile';
		my $need = $skipinfo;
		if ($skipinfo=~/^([a-zA-Z0-9-_]+)\((.*)\)$/) {
			($type, $need) = ($1, $2);
		}
		if ($type eq 'tmp') {
			foreach my $package (@packages) {
				my $tmp = tmpdir($package);
				return 0 if -e "$tmp/$need";
			}
		} elsif ($type eq 'pkgfile' or $type eq 'pkgfile-logged') {
			my $pkgs;
			if ($type eq 'pkgfile') {
				$pkgs = \@packages;
			} else {
				$all_pkgs //= [ getpackages() ];
				$pkgs = $all_pkgs;
			}
			# Use the secret bulk check call
			return 0 if pkgfile($pkgs, $need) ne '';
		} elsif ($type eq 'cli-options') {
			$had_cli_options = 1;
			# If cli-options is empty, we know the helper does not
			# react to any thing and can always be skipped.
			next if $need =~ m/^\s*$/;
			# Long options are subject to abbreviations so it is
			# very difficult to implement this optimization with
			# long options.
			return 0 if $unoptimizable_option_bundle;
			$need =~ s/(?:^|\s)BUILDSYSTEM(?:\s|$)/${\UNSKIPPABLE_CLI_OPTIONS_BUILD_SYSTEM}/;
			my @behavior_options = split(qr/\Q|\E/, $need);
			for my $opt (@behavior_options) {
				return 0 if exists($seen_options{$opt});
			}
		} elsif ($type eq 'buildsystem') {
			require Debian::Debhelper::Dh_Buildsystems;
			my $system = Debian::Debhelper::Dh_Buildsystems::load_buildsystem(undef, $need);
			return 0 if defined($system);
		} else {
			# Unknown hint - make no assumptions
			return 0;
		}
	}
	return 0 if not $had_cli_options and %seen_options;
	return 1;
}


=head1 SEE ALSO

L<debhelper(7)>

This program is a part of debhelper.

=head1 AUTHOR

Joey Hess <joeyh@debian.org>

=cut