Use ASCII RS for separating options in DH_INTERNAL_OPTIONS.

[debhelper.git] / dh

diff --git a/dh b/dh
index 0b85ce95f283f998212a4e61ce2ecb959ef71761..c34a5a0273e952f359e8b92cf14c19ab7f73c24b 100755 (executable)
--- a/dh
+++ b/dh
@@ -11,7 +11,7 @@ use Debian::Debhelper::Dh_Lib;
 
 =head1 SYNOPSIS
 
 
 =head1 SYNOPSIS
 

-B<dh> sequence [B<--until> I<cmd>] [B<--before> I<cmd>] [B<--after> I<cmd>] [B<--remaining>] [B<--with> I<addon>] [S<I<debhelper options>>]
+B<dh> sequence [B<--with> I<addon>[,I<addon>,...]] [B<--until> I<cmd>] [B<--before> I<cmd>] [B<--after> I<cmd>] [B<--remaining>] [S<I<debhelper options>>]

 
 =head1 DESCRIPTION
 
 
 =head1 DESCRIPTION
 


@@ -34,10 +34,30 @@ that is in the specified sequence. It then continues with the next command
 in the sequence. The B<--until>, B<--before>, B<--after>, and B<--remaining>
 options can override this behavior.
 
 in the sequence. The B<--until>, B<--before>, B<--after>, and B<--remaining>
 options can override this behavior.
 

+If debian/rules contains a target with a name like "override_I<dh_command>",
+then when it gets to that command in the sequence, dh will run that
+target from the rules file, rather than running the actual command. The
+override target can then run the command with additional options, or run
+entirely different commands instead. (Note that to use this feature,
+you should Build-Depend on debhelper 7.0.50 or above.)
+

 =head1 OPTIONS
 
 =over 4
 
 =head1 OPTIONS
 
 =over 4
 

+=item B<--with> I<addon>[,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 PROGRAMMING file for documentation about
+the sequence addon interface.
+
+=item B<--without> I<addon>
+
+The inverse of --with, disables using the given addon.
+

 =item B<--until> I<cmd>
 
 Run commands in the sequence until and including I<cmd>, then stop.
 =item B<--until> I<cmd>
 
 Run commands in the sequence until and including I<cmd>, then stop.


@@ -54,14 +74,6 @@ Run commands in the sequence that come after I<cmd>.
 
 Run all commands in the sequence that have yet to be run.
 
 
 Run all commands in the sequence that have yet to be run.
 

-=item B<--with> 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, and is used when there is a third-party package that provides
-debhelper commands. See "SEQUENCE ADDONS" below for documentation about what
-such packages should do to be supported by --with.
-

 =back
 
 All other options passed to dh are passed on to each command it runs. This
 =back
 
 All other options passed to dh are passed on to each command it runs. This


@@ -75,28 +87,6 @@ search for a command in the sequence exactly matching the name, to avoid any
 ambiguity. If there are multiple substring matches, the last one in the
 sequence will be used.
 
 ambiguity. If there are multiple substring matches, the last one in the
 sequence will be used.
 

-=head1 SEQUENCE ADDONS
-
-When B<--with> I<addon> is used, dh loads the perl module
-Debian::Debhelper::Sequence::I<addon>. Two functions are provided to let
-the module add its commands to sequences:
-
-=over 4
-
-=item Debian::Debhelper::Dh_Lib::insert_before(existing_command, new_command)
-
-Insert I<new_command> in sequences before I<existing_command>.
-
-=item Debian::Debhelper::Dh_Lib::insert_after(existing_command, new_command)
-
-Insert I<new_command> in sequences after I<existing_command>.
-
-=item Debian::Debhelper::Dh_Lib::remove_command(existing_command)
-
-Remove I<existing_command> from the list of commands to run.
-
-=back
-

 =cut
 
 sub command_pos {
 =cut
 
 sub command_pos {


@@ -137,90 +127,82 @@ commands work with no additional options.
        %:
                dh $@
 
        %:
                dh $@
 

-This is a simple rules file that is a good starting place for customisation.
-(It's also available in F</usr/share/doc/debhelper/examples/rules.simple>
-
+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
        #!/usr/bin/make -f

+       %:
+               dh $@

 
 

-       build: build-stamp
-       build-stamp:
-               dh build
-               touch build-stamp
+       override_dh_strip:
+               dh_strip -Xfoo
+               
+       override_dh_installdocs:
+               dh_installdocs README TODO

 
 

-       clean:
-               dh clean
+Sometimes the automated dh_auto_configure and dh_auto_build can't guess
+what to do for a strange package. Here's how to avoid running either
+and instead run your own commands.

 
 

-       install: build install-stamp
-       install-stamp:
-               dh install
-               touch install-stamp
+       #!/usr/bin/make -f
+       %:
+               dh $@

 
 

-       binary-arch: install
-               dh binary-arch
+       override_dh_auto_configure:
+               ./mondoconfig

 
 

-       binary-indep: install
-               dh binary-indep
+       override_dh_auto_build:
+               make universe-explode-in-delight

 
 

-       binary: binary-arch binary-indep
+Another common case is wanting to do something manually before or
+after a particular debhelper command is run.

 
 

-Often you'll want to pass an option to ./configure. This uses dh to run all
-commands before L<dh_auto_configure(1)>, then runs that command by hand,
-and then finishes up by running the rest of the sequence. You could also
-run ./configure by hand, instead of bothering with using dh_auto_configure.
-And if necessary, you can add commands to run automake, etc here too.
+       #!/usr/bin/make -f
+       %:
+               dh $@

 
 

-       build: build-stamp
-       build-stamp:
-               dh build --before configure
-               dh_auto_configure -- --kitchen-sink=yes
-               dh build --after configure
-               touch build-stamp
+       override_dh_fixperms:
+               dh_fixperms
+               chmod 4755 debian/foo/usr/bin/foo

 
 

-Here's how to skip two automated in a row (configure and build), and
-instead run the commands by hand.
+If your package is a python package, dh will use dh_pysupport by
+default. This is how to use dh_pycentral instead.

 
 

-       build: build-stamp
-       build-stamp:
-               dh build --before configure
-               ./mondoconfig
-               make universe-explode-in-delight
-               dh build --after build
-               touch build-stamp
+       #!/usr/bin/make -f
+       %:
+               dh --with python-central $@

 
 

-Another common case is wanting to run some code manually after a particular
-debhelper command is run.
+To patch your package using quilt, you can tell dh to use quilt's dh
+sequence addons like this:
+       
+       #!/usr/bin/make -f
+       %:
+               dh --with quilt $@

 
 

-       install: build install-stamp
-       install-stamp:
-               dh install --until dh_fixperms
-               # dh_fixperms has run, now override it for one program
-               chmod 4755 debian/foo/usr/bin/foo
-               # and continue
-               dh install --after dh_fixperms
-               touch install-stamp
-
-It's also fine to run debhelper commands early. Just make sure that at
-least dh_prep is run from the sequence first, and be sure to use the
-B<--remaining> option to ensure that commands that normally come before
-those in the sequence are still run.
-
-       install: build install-stamp
-       install-stamp:
-               dh install --until dh_prep
-               dh_installdocs README TODO
-               dh_installchangelogs Changes
-               dh install --remaining
-               touch install-stamp
+Here is an example of overriding where the dh_auto_* commands find
+the package's source, for a package where the source is located in a
+subdirectory. It also forces use of perl's Module::Build build system,
+which can be necessary if debhelper wrongly detects that the package
+uses MakeMaker.

 
 

-        binary-arch: install
-                dh_strip -X foo
-                dh binary-arch --remaining
+       #!/usr/bin/make -f
+       %:
+               dh --sourcedirectory=src --buildsystem=perl_build $@

 
 =cut
 
 # Stash this away before init modifies it.
 my @ARGV_orig=@ARGV;
 
 
 =cut
 
 # Stash this away before init modifies it.
 my @ARGV_orig=@ARGV;
 

+# python-support is enabled by default, at least for now
+# (and comes first so python-central loads later and can disable it).
+unshift @ARGV, "--with=python-support";
+               
+# Disable complaints about unknown options for both dh and the commands
+# it runs. This is done because dh accepts and passes on options that may
+# be specific to only some debhelper commands.
+$ENV{DH_IGNORE_UNKNOWN_OPTIONS}=1;
+

 init(options => {
        "until=s" => \$dh{UNTIL},
        "after=s" => \$dh{AFTER},
 init(options => {
        "until=s" => \$dh{UNTIL},
        "after=s" => \$dh{AFTER},


@@ -228,7 +210,11 @@ init(options => {
        "remaining" => \$dh{REMAINING},
        "with=s" => sub {
                my ($option,$value)=@_;
        "remaining" => \$dh{REMAINING},
        "with=s" => sub {
                my ($option,$value)=@_;

-               push @{$dh{WITH}},$value;
+               push @{$dh{WITH}},split(",", $value);
+       },
+       "without=s" => sub {
+               my ($option,$value)=@_;
+               @{$dh{WITH}} = grep { $_ ne $value } @{$dh{WITH}};

        },
 });
 inhibit_log();
        },
 });
 inhibit_log();


@@ -276,12 +262,11 @@ $sequences{install} = [@{$sequences{build}}, qw{
        dh_installudev
        dh_installwm
        dh_installxfonts
        dh_installudev
        dh_installwm
        dh_installxfonts

+       dh_bugfiles

        dh_lintian
        dh_lintian

-       dh_desktop

        dh_gconf
        dh_icons
        dh_perl
        dh_gconf
        dh_icons
        dh_perl

-       dh_scrollkeeper

        dh_usrlocal
 
        dh_link
        dh_usrlocal
 
        dh_link


@@ -302,9 +287,6 @@ $sequences{binary} = [@{$sequences{install}}, qw{
 }, @b];
 $sequences{'binary-arch'} = [@{$sequences{binary}}];
 
 }, @b];
 $sequences{'binary-arch'} = [@{$sequences{binary}}];
 

-# --with python-support is enabled by default, at least for now
-unshift @{$dh{WITH}}, "python-support";
-

 # sequence addon interface
 sub _insert {
        my $offset=shift;
 # sequence addon interface
 sub _insert {
        my $offset=shift;


@@ -354,7 +336,13 @@ if (! @ARGV) {
        error "specify a sequence to run";
 }
 my $sequence=shift;
        error "specify a sequence to run";
 }
 my $sequence=shift;

-if (! exists $sequences{$sequence}) {
+if ($sequence eq 'debian/rules' ||
+    $sequence =~ /^override_dh_/) {
+       # make -B causes the rules file to be run as a target
+       # and support completly empty override targets
+       exit 0
+}      
+elsif (! exists $sequences{$sequence}) {

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


@@ -382,11 +370,11 @@ elsif ($sequence eq 'binary-indep') {
 while (@ARGV_orig) {
        my $opt=shift @ARGV_orig;
        next if $opt eq $sequence;
 while (@ARGV_orig) {
        my $opt=shift @ARGV_orig;
        next if $opt eq $sequence;

-       if ($opt =~ /^--?(after|until|before|with)$/) {
+       if ($opt =~ /^--?(after|until|before|with|without)$/) {

                shift @ARGV_orig;
                next;
        }
                shift @ARGV_orig;
                next;
        }

-       elsif ($opt =~ /^--?(no-act|remaining|(after|until|before|with)=)/) {
+       elsif ($opt =~ /^--?(no-act|remaining|(after|until|before|with|without)=)/) {

                next;
        }
        push @options, $opt;
                next;
        }
        push @options, $opt;


@@ -396,7 +384,7 @@ while (@ARGV_orig) {
 my %logged;
 my %startpoint;
 foreach my $package (@packages) {
 my %logged;
 my %startpoint;
 foreach my $package (@packages) {

-       my @log=loadlog($package);
+       my @log=load_log($package, \%logged);

        if ($dh{AFTER}) {
                # Run commands in the sequence that come after the
                # specified command.
        if ($dh{AFTER}) {
                # Run commands in the sequence that come after the
                # specified command.


@@ -406,7 +394,7 @@ foreach my $package (@packages) {
                # no commands remain to run after it, communicating to
                # future dh instances that the specified command should not
                # be run again.
                # no commands remain to run after it, communicating to
                # future dh instances that the specified command should not
                # be run again.

-               writelog($package, $sequence[$startpoint{$package}-1]);
+               write_log($sequence[$startpoint{$package}-1], $package);

        }
        elsif ($dh{REMAINING}) {
                # Start at the beginning so all remaining commands will get
        }
        elsif ($dh{REMAINING}) {
                # Start at the beginning so all remaining commands will get


@@ -453,21 +441,32 @@ foreach my $i (0..$stoppoint) {
                # Command already done for all packages.
                next;
        }
                # Command already done for all packages.
                next;
        }

-       elsif (! @exclude) {
-               # Run command for all packages.
-               run($sequence[$i], @options);
-       }
-       else {
-               # Run command for only a subset of packages.
-               run($sequence[$i], @options,
-                       map { "-N$_" } @exclude);
-       }
+
+       run($sequence[$i], \@packages, \@exclude, @options);

 }
 
 sub run {
        my $command=shift;
 }
 
 sub run {
        my $command=shift;

+       my @packages=@{shift()};
+       my @exclude=@{shift()};

        my @options=@_;
        
        my @options=@_;
        

+       # If some packages are excluded, add flags
+       # to prevent them from being acted on.
+       push @options, map { "-N$_" } @exclude;
+
+       # Check for override targets in debian/rules and
+       # run them instead of running the command directly.
+       my $override_command;
+       if (rules_explicit_target("override_".$command)) {
+               $override_command=$command;
+               # This passes the options through to commands called
+               # inside the target.
+               $ENV{DH_INTERNAL_OPTIONS}=join("\x1e", @options);
+               $command="debian/rules";
+               @options="override_".$override_command;
+       }
+

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


@@ -480,32 +479,65 @@ sub run {
                elsif ($ret) {
                        exit 1;
                }
                elsif ($ret) {
                        exit 1;
                }

+
+               if (defined $override_command) {
+                       delete $ENV{DH_INTERNAL_OPTIONS};
+                       # Need to handle logging for overriden commands here,
+                       # because the actual debhelper command may not have
+                       # been run by the rules file target.
+                       # (But avoid logging for dh_clean since it removes
+                       # the log earlier.)
+                       if ($override_command ne 'dh_clean') {
+                               my %packages=map { $_ => 1 } @packages;
+                               map { delete $packages{$_} } @exclude;
+                               write_log($override_command, keys %packages);
+                       }
+               }

        }
 }
 
        }
 }
 

-sub loadlog {
-       my $package=shift;
-       my $ext=pkgext($package);
+{
+my %targets;
+my $rules_parsed;
+
+sub rules_explicit_target {
+       # Checks if a specified target exists as an explicit target
+       # in debian/rules. 
+       my $target=shift;

        
        

-       my @log;
-       open(LOG, "<", "debian/${ext}debhelper.log") || return;
-       while (<LOG>) {
-               chomp;
-               push @log, $_;
-               $logged{$package}{$_}=1;
+       if (! $rules_parsed) {  
+               my $processing_targets = 0;
+               my $not_a_target = 0;
+               open(MAKE, "LC_ALL=C make -Rrnpsf debian/rules debhelper-fail-me 2>/dev/null |");
+               while (<MAKE>) {
+                       if ($processing_targets) {
+                               if (/^# Not a target:/) {
+                                       $not_a_target = 1;
+                               }
+                               else {
+                                       if (!$not_a_target && /^([^#:]+)::?/) {
+                                               # Target is defined.
+                                               # NOTE: if it is a depenency
+                                               # of .PHONY it will be
+                                               # defined too but that's ok.
+                                               $targets{$1} = 1;
+                                       }
+                                       # "Not a target:" is always followed by
+                                       # a target name, so resetting this one
+                                       # here is safe.
+                                       $not_a_target = 0;
+                               }
+                       } elsif (/^# Files$/) {
+                               $processing_targets = 1;
+                       }
+               }
+               close MAKE;
+               $rules_parsed = 1;

        }
        }

-       close LOG;
-       return @log;
+
+       return exists $targets{$target};

 }
 }

-               
-sub writelog {
-       my $package=shift;
-       my $cmd=shift;
-       my $ext=pkgext($package);
-       
-       open(LOG, ">>", "debian/${ext}debhelper.log") || error("failed to write to log");
-       print LOG $cmd."\n";
-       close LOG;
+

 }
 
 =head1 SEE ALSO
 }
 
 =head1 SEE ALSO