dh

   1 #!/usr/bin/perl -w
   2
   3 =head1 NAME
   4
   5 dh - debhelper command sequencer
   6
   7 =cut
   8
   9 use strict;
  10 use Debian::Debhelper::Dh_Lib;
  11
  12 =head1 SYNOPSIS
  13
  14 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>>]
  15
  16 =head1 DESCRIPTION
  17
  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".
  21
  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.
  26
  27 Each debhelper command will record when it's successfully run in
  28 debian/package.debhelper.log. (Which dh_clean deletes.) So dh can tell
  29 which commands have already been run, for which packages, and skip running
  30 those commands again.
  31
  32 Each time dh is run, it examines the log, and finds the last logged command
  33 that is in the specified sequence. It then continues with the next command
  34 in the sequence. The B<--until>, B<--before>, B<--after>, and B<--remaining>
  35 options can override this behavior.
  36
  37 If debian/rules contains a target with a name like "override_I<dh_command>",
  38 then when it gets to that command in the sequence, dh will run that
  39 target from the rules file, rather than running the actual command. The
  40 override target can then run the command with additional options, or run
  41 entirely different commands instead. (Note that to use this feature,
  42 you should Build-Depend on debhelper 7.0.50 or above.)
  43
  44 =head1 OPTIONS
  45
  46 =over 4
  47
  48 =item B<--with> I<addon>[,I<addon>,...]
  49
  50 Add the debhelper commands specified by the given addon to appropriate places
  51 in the sequence of commands that is run. This option can be repeated more
  52 than once, or multiple addons can be listed, separated by commas.
  53 This is used when there is a third-party package that provides
  54 debhelper commands. See the PROGRAMMING file for documentation about
  55 the sequence addon interface.
  56
  57 =item B<--without> I<addon>
  58
  59 The inverse of --with, disables using the given addon.
  60
  61 =item B<--until> I<cmd>
  62
  63 Run commands in the sequence until and including I<cmd>, then stop.
  64
  65 =item B<--before> I<cmd>
  66
  67 Run commands in the sequence before I<cmd>, then stop.
  68
  69 =item B<--after> I<cmd>
  70
  71 Run commands in the sequence that come after I<cmd>.
  72
  73 =item B<--remaining>
  74
  75 Run all commands in the sequence that have yet to be run.
  76
  77 =back
  78
  79 All other options passed to dh are passed on to each command it runs. This
  80 can be used to set an option like "-v" or "-X" or "-N", as well as for more
  81 specialised options.
  82
  83 =head1 COMMAND SPECIFICATION
  84
  85 I<cmd> can be a full name of a debhelper command, or a substring. It'll first
  86 search for a command in the sequence exactly matching the name, to avoid any
  87 ambiguity. If there are multiple substring matches, the last one in the
  88 sequence will be used.
  89
  90 =cut
  91
  92 sub command_pos {
  93         my $command=shift;
  94         my @sequence=@_;
  95
  96         foreach my $i (0..$#sequence) {
  97                 if ($command eq $sequence[$i]) {
  98                         return $i;
  99                 }
 100         }
 101
 102         my @matches;
 103         foreach my $i (0..$#sequence) {
 104                 if ($sequence[$i] =~ /\Q$command\E/) {
 105                         push @matches, $i;
 106                 }
 107         }
 108         if (! @matches) {
 109                 error "command specification \"$command\" does not match any command in the sequence"
 110         }
 111         else {
 112                 return pop @matches;
 113         }
 114 }
 115
 116 =head1 EXAMPLES
 117
 118 To see what commands are included in a sequence, without actually doing
 119 anything:
 120
 121         dh binary-arch --no-act
 122
 123 This is a very simple rules file, for packages where the default sequences of
 124 commands work with no additional options.
 125
 126         #!/usr/bin/make -f
 127         %:
 128                 dh $@
 129
 130 Often you'll want to pass an option to a specific debhelper command. The
 131 easy way to do with is by adding an override target for that command.
 132
 133         #!/usr/bin/make -f
 134         %:
 135                 dh $@
 136
 137         override_dh_strip:
 138                 dh_strip -Xfoo
 139
 140         override_dh_installdocs:
 141                 dh_installdocs README TODO
 142
 143 Sometimes the automated dh_auto_configure and dh_auto_build can't guess
 144 what to do for a strange package. Here's how to avoid running either
 145 and instead run your own commands.
 146
 147         #!/usr/bin/make -f
 148         %:
 149                 dh $@
 150
 151         override_dh_auto_configure:
 152                 ./mondoconfig
 153
 154         override_dh_auto_build:
 155                 make universe-explode-in-delight
 156
 157 Another common case is wanting to do something manually before or
 158 after a particular debhelper command is run.
 159
 160         #!/usr/bin/make -f
 161         %:
 162                 dh $@
 163
 164         override_dh_fixperms:
 165                 dh_fixperms
 166                 chmod 4755 debian/foo/usr/bin/foo
 167
 168 If your package is a python package, dh will use dh_pysupport by
 169 default. This is how to use dh_pycentral instead.
 170
 171         #!/usr/bin/make -f
 172         %:
 173                 dh --with python-central $@
 174
 175 To patch your package using quilt, you can tell dh to use quilt's dh
 176 sequence addons like this:
 177
 178         #!/usr/bin/make -f
 179         %:
 180                 dh --with quilt $@
 181
 182 Here is an example of overriding where the dh_auto_* commands find
 183 the package's source, for a package where the source is located in a
 184 subdirectory. It also forces use of perl's Module::Build build system,
 185 which can be necessary if debhelper wrongly detects that the package
 186 uses MakeMaker.
 187
 188         #!/usr/bin/make -f
 189         %:
 190                 dh --sourcedirectory=src --buildsystem=perl_build $@
 191
 192 =cut
 193
 194 # Stash this away before init modifies it.
 195 my @ARGV_orig=@ARGV;
 196
 197 # python-support is enabled by default, at least for now
 198 # (and comes first so python-central loads later and can disable it).
 199 unshift @ARGV, "--with=python-support";
 200
 201 # Disable complaints about unknown options for both dh and the commands
 202 # it runs. This is done because dh accepts and passes on options that may
 203 # be specific to only some debhelper commands.
 204 $ENV{DH_IGNORE_UNKNOWN_OPTIONS}=1;
 205
 206 init(options => {
 207         "until=s" => \$dh{UNTIL},
 208         "after=s" => \$dh{AFTER},
 209         "before=s" => \$dh{BEFORE},
 210         "remaining" => \$dh{REMAINING},
 211         "with=s" => sub {
 212                 my ($option,$value)=@_;
 213                 push @{$dh{WITH}},split(",", $value);
 214         },
 215         "without=s" => sub {
 216                 my ($option,$value)=@_;
 217                 @{$dh{WITH}} = grep { $_ ne $value } @{$dh{WITH}};
 218         },
 219 });
 220 inhibit_log();
 221
 222 # Definitions of sequences.
 223 my %sequences;
 224 $sequences{build} = [qw{
 225         dh_testdir
 226         dh_auto_configure
 227         dh_auto_build
 228         dh_auto_test
 229 }],
 230 $sequences{clean} = [qw{
 231         dh_testdir
 232         dh_auto_clean
 233         dh_clean
 234 }];
 235 $sequences{install} = [@{$sequences{build}}, qw{
 236         dh_testroot
 237         dh_prep
 238         dh_installdirs
 239         dh_auto_install
 240
 241         dh_install
 242         dh_installdocs
 243         dh_installchangelogs
 244         dh_installexamples
 245         dh_installman
 246
 247         dh_installcatalogs
 248         dh_installcron
 249         dh_installdebconf
 250         dh_installcatalogs
 251         dh_installemacsen
 252         dh_installifupdown
 253         dh_installinfo
 254         dh_installinit
 255         dh_installmenu
 256         dh_installmime
 257         dh_installmodules
 258         dh_installlogcheck
 259         dh_installlogrotate
 260         dh_installpam
 261         dh_installppp
 262         dh_installudev
 263         dh_installwm
 264         dh_installxfonts
 265         dh_bugfiles
 266         dh_lintian
 267         dh_gconf
 268         dh_icons
 269         dh_perl
 270         dh_usrlocal
 271
 272         dh_link
 273         dh_compress
 274         dh_fixperms
 275 }];
 276 my @b=qw{
 277         dh_installdeb
 278         dh_gencontrol
 279         dh_md5sums
 280         dh_builddeb
 281 };
 282 $sequences{'binary-indep'} = [@{$sequences{install}}, @b];
 283 $sequences{binary} = [@{$sequences{install}}, qw{
 284         dh_strip
 285         dh_makeshlibs
 286         dh_shlibdeps
 287 }, @b];
 288 $sequences{'binary-arch'} = [@{$sequences{binary}}];
 289
 290 # sequence addon interface
 291 sub _insert {
 292         my $offset=shift;
 293         my $existing=shift;
 294         my $new=shift;
 295         foreach my $sequence (keys %sequences) {
 296                 my @list=@{$sequences{$sequence}};
 297                 next unless grep $existing, @list;
 298                 my @new;
 299                 foreach my $command (@list) {
 300                         if ($command eq $existing) {
 301                                 push @new, $new if $offset < 0;
 302                                 push @new, $command;
 303                                 push @new, $new if $offset > 0;
 304                         }
 305                         else {
 306                                 push @new, $command;
 307                         }
 308                 }
 309                 $sequences{$sequence}=\@new;
 310         }
 311 }
 312 sub insert_before {
 313         _insert(-1, @_);
 314 }
 315 sub insert_after {
 316         _insert(1, @_);
 317 }
 318 sub remove_command {
 319         my $command=shift;
 320         foreach my $sequence (keys %sequences) {
 321                 $sequences{$sequence}=[grep { $_ ne $command } @{$sequences{$sequence}}];
 322         }
 323
 324 }
 325 sub add_command {
 326         my $command=shift;
 327         my $sequence=shift;
 328         unshift @{$sequences{$sequence}}, $command;
 329 }
 330 foreach my $addon (@{$dh{WITH}}) {
 331         my $mod="Debian::Debhelper::Sequence::$addon";
 332         $mod=~s/-/_/g;
 333         eval "use $mod";
 334         if ($@) {
 335                 error("--with $addon not supported or failed to load module $mod");
 336         }
 337 }
 338
 339 # Get the sequence of commands to run.
 340 if (! @ARGV) {
 341         error "specify a sequence to run";
 342 }
 343 my $sequence=shift;
 344 if ($sequence eq 'debian/rules' ||
 345     $sequence =~ /^override_dh_/) {
 346         # make -B causes the rules file to be run as a target
 347         # and support completly empty override targets
 348         exit 0
 349 }
 350 elsif (! exists $sequences{$sequence}) {
 351         error "Unknown sequence $sequence (choose from: ".
 352                 join(" ", sort keys %sequences).")";
 353 }
 354 my @sequence=@{$sequences{$sequence}};
 355
 356 # The list of all packages that can be acted on.
 357 my @packages=@{$dh{DOPACKAGES}};
 358
 359 # Get the options to pass to commands in the sequence.
 360 # Filter out options intended only for this program.
 361 my @options;
 362 if ($sequence eq 'binary-arch') {
 363         push @options, "-a";
 364         # as an optimisation, remove from the list any packages
 365         # that are not arch dependent
 366         my %arch_packages = map { $_ => 1 } getpackages("arch");
 367         @packages = grep { $arch_packages{$_} } @packages;
 368 }
 369 elsif ($sequence eq 'binary-indep') {
 370         push @options, "-i";
 371         # ditto optimisation for arch indep
 372         my %indep_packages = map { $_ => 1 } getpackages("indep");
 373         @packages = grep { $indep_packages{$_} } @packages;
 374 }
 375 while (@ARGV_orig) {
 376         my $opt=shift @ARGV_orig;
 377         next if $opt eq $sequence;
 378         if ($opt =~ /^--?(after|until|before|with|without)$/) {
 379                 shift @ARGV_orig;
 380                 next;
 381         }
 382         elsif ($opt =~ /^--?(no-act|remaining|(after|until|before|with|without)=)/) {
 383                 next;
 384         }
 385         push @options, $opt;
 386 }
 387
 388 # Figure out at what point in the sequence to start for each package.
 389 my %logged;
 390 my %startpoint;
 391 foreach my $package (@packages) {
 392         my @log=load_log($package, \%logged);
 393         if ($dh{AFTER}) {
 394                 # Run commands in the sequence that come after the
 395                 # specified command.
 396                 $startpoint{$package}=command_pos($dh{AFTER}, @sequence) + 1;
 397                 # Write a dummy log entry indicating that the specified
 398                 # command was, in fact, run. This handles the case where
 399                 # no commands remain to run after it, communicating to
 400                 # future dh instances that the specified command should not
 401                 # be run again.
 402                 write_log($sequence[$startpoint{$package}-1], $package);
 403         }
 404         elsif ($dh{REMAINING}) {
 405                 # Start at the beginning so all remaining commands will get
 406                 # run.
 407                 $startpoint{$package}=0;
 408         }
 409         else {
 410                 # Find the last logged command that is in the sequence, and
 411                 # continue with the next command after it. If no logged
 412                 # command is in the sequence, we're starting at the beginning..
 413                 $startpoint{$package}=0;
 414 COMMAND:        foreach my $command (reverse @log) {
 415                         foreach my $i (0..$#sequence) {
 416                                 if ($command eq $sequence[$i]) {
 417                                         $startpoint{$package}=$i+1;
 418                                         last COMMAND;
 419                                 }
 420                         }
 421                 }
 422         }
 423 }
 424
 425 # Figure out what point in the sequence to go to.
 426 my $stoppoint=$#sequence;
 427 if ($dh{UNTIL}) {
 428         $stoppoint=command_pos($dh{UNTIL}, @sequence);
 429 }
 430 elsif ($dh{BEFORE}) {
 431         $stoppoint=command_pos($dh{BEFORE}, @sequence) - 1;
 432 }
 433
 434 # Now run the commands in the sequence.
 435 foreach my $i (0..$stoppoint) {
 436         # Figure out which packages need to run this command.
 437         my @exclude;
 438         foreach my $package (@packages) {
 439                 if ($startpoint{$package} > $i ||
 440                     $logged{$package}{$sequence[$i]}) {
 441                         push @exclude, $package;
 442                 }
 443         }
 444
 445         if (@exclude eq @packages) {
 446                 # Command already done for all packages.
 447                 next;
 448         }
 449
 450         run($sequence[$i], \@packages, \@exclude, @options);
 451 }
 452
 453 sub run {
 454         my $command=shift;
 455         my @packages=@{shift()};
 456         my @exclude=@{shift()};
 457         my @options=@_;
 458
 459         # If some packages are excluded, add flags
 460         # to prevent them from being acted on.
 461         push @options, map { "-N$_" } @exclude;
 462
 463         # Check for override targets in debian/rules and
 464         # run them instead of running the command directly.
 465         my $override_command;
 466         if (rules_explicit_target("override_".$command)) {
 467                 $override_command=$command;
 468                 # This passes the options through to commands called
 469                 # inside the target.
 470                 $ENV{DH_INTERNAL_OPTIONS}=join("\x1e", @options);
 471                 $command="debian/rules";
 472                 @options="override_".$override_command;
 473         }
 474
 475         # 3 space indent lines the command being run up under the
 476         # sequence name after "dh ".
 477         print "   ".escape_shell($command, @options)."\n";
 478
 479         if (! $dh{NO_ACT}) {
 480                 my $ret=system($command, @options);
 481                 if ($ret >> 8 != 0) {
 482                         exit $ret >> 8;
 483                 }
 484                 elsif ($ret) {
 485                         exit 1;
 486                 }
 487
 488                 if (defined $override_command) {
 489                         delete $ENV{DH_INTERNAL_OPTIONS};
 490                         # Need to handle logging for overriden commands here,
 491                         # because the actual debhelper command may not have
 492                         # been run by the rules file target.
 493                         # (But avoid logging for dh_clean since it removes
 494                         # the log earlier.)
 495                         if ($override_command ne 'dh_clean') {
 496                                 my %packages=map { $_ => 1 } @packages;
 497                                 map { delete $packages{$_} } @exclude;
 498                                 write_log($override_command, keys %packages);
 499                         }
 500                 }
 501         }
 502 }
 503
 504 {
 505 my %targets;
 506 my $rules_parsed;
 507
 508 sub rules_explicit_target {
 509         # Checks if a specified target exists as an explicit target
 510         # in debian/rules.
 511         my $target=shift;
 512
 513         if (! $rules_parsed) {
 514                 my $processing_targets = 0;
 515                 my $not_a_target = 0;
 516                 open(MAKE, "LC_ALL=C make -Rrnpsf debian/rules debhelper-fail-me 2>/dev/null |");
 517                 while (<MAKE>) {
 518                         if ($processing_targets) {
 519                                 if (/^# Not a target:/) {
 520                                         $not_a_target = 1;
 521                                 }
 522                                 else {
 523                                         if (!$not_a_target && /^([^#:]+)::?/) {
 524                                                 # Target is defined.
 525                                                 # NOTE: if it is a depenency
 526                                                 # of .PHONY it will be
 527                                                 # defined too but that's ok.
 528                                                 $targets{$1} = 1;
 529                                         }
 530                                         # "Not a target:" is always followed by
 531                                         # a target name, so resetting this one
 532                                         # here is safe.
 533                                         $not_a_target = 0;
 534                                 }
 535                         } elsif (/^# Files$/) {
 536                                 $processing_targets = 1;
 537                         }
 538                 }
 539                 close MAKE;
 540                 $rules_parsed = 1;
 541         }
 542
 543         return exists $targets{$target};
 544 }
 545
 546 }
 547
 548 =head1 SEE ALSO
 549
 550 L<debhelper(7)>
 551
 552 This program is a part of debhelper.
 553
 554 =head1 AUTHOR
 555
 556 Joey Hess <joeyh@debian.org>
 557
 558 =cut