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