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