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