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 # If make was using a jobserver, but it is not available, clean out
 229 # MAKEFLAGS so that further make invocations can start a new job
 230 # server.
 231 if (is_make_jobserver_unavailable()) {
 232         clean_jobserver_makeflags();
 233 }
 234
 235 # Definitions of sequences.
 236 my %sequences;
 237 $sequences{build} = [qw{
 238         dh_testdir
 239         dh_auto_configure
 240         dh_auto_build
 241         dh_auto_test
 242 }],
 243 $sequences{clean} = [qw{
 244         dh_testdir
 245         dh_auto_clean
 246         dh_clean
 247 }];
 248 $sequences{install} = [@{$sequences{build}}, qw{
 249         dh_testroot
 250         dh_prep
 251         dh_installdirs
 252         dh_auto_install
 253
 254         dh_install
 255         dh_installdocs
 256         dh_installchangelogs
 257         dh_installexamples
 258         dh_installman
 259
 260         dh_installcatalogs
 261         dh_installcron
 262         dh_installdebconf
 263         dh_installemacsen
 264         dh_installifupdown
 265         dh_installinfo
 266         dh_installinit
 267         dh_installmenu
 268         dh_installmime
 269         dh_installmodules
 270         dh_installlogcheck
 271         dh_installlogrotate
 272         dh_installpam
 273         dh_installppp
 274         dh_installudev
 275         dh_installwm
 276         dh_installxfonts
 277         dh_bugfiles
 278         dh_lintian
 279         dh_gconf
 280         dh_icons
 281         dh_perl
 282         dh_usrlocal
 283
 284         dh_link
 285         dh_compress
 286         dh_fixperms
 287 }];
 288 my @b=qw{
 289         dh_installdeb
 290         dh_gencontrol
 291         dh_md5sums
 292         dh_builddeb
 293 };
 294 $sequences{'binary-indep'} = [@{$sequences{install}}, @b];
 295 $sequences{binary} = [@{$sequences{install}}, qw{
 296         dh_strip
 297         dh_makeshlibs
 298         dh_shlibdeps
 299 }, @b];
 300 $sequences{'binary-arch'} = [@{$sequences{binary}}];
 301
 302 # Additional command options
 303 my %command_opts;
 304
 305 # sequence addon interface
 306 sub _insert {
 307         my $offset=shift;
 308         my $existing=shift;
 309         my $new=shift;
 310         foreach my $sequence (keys %sequences) {
 311                 my @list=@{$sequences{$sequence}};
 312                 next unless grep $existing, @list;
 313                 my @new;
 314                 foreach my $command (@list) {
 315                         if ($command eq $existing) {
 316                                 push @new, $new if $offset < 0;
 317                                 push @new, $command;
 318                                 push @new, $new if $offset > 0;
 319                         }
 320                         else {
 321                                 push @new, $command;
 322                         }
 323                 }
 324                 $sequences{$sequence}=\@new;
 325         }
 326 }
 327 sub insert_before {
 328         _insert(-1, @_);
 329 }
 330 sub insert_after {
 331         _insert(1, @_);
 332 }
 333 sub remove_command {
 334         my $command=shift;
 335         foreach my $sequence (keys %sequences) {
 336                 $sequences{$sequence}=[grep { $_ ne $command } @{$sequences{$sequence}}];
 337         }
 338
 339 }
 340 sub add_command {
 341         my $command=shift;
 342         my $sequence=shift;
 343         unshift @{$sequences{$sequence}}, $command;
 344 }
 345 sub add_command_options {
 346         my $command=shift;
 347         push @{$command_opts{$command}}, @_;
 348 }
 349 sub remove_command_options {
 350         my $command=shift;
 351         if (@_) {
 352                 # Remove only specified options
 353                 if (my $opts = $command_opts{$command}) {
 354                         foreach my $opt (@_) {
 355                                 $opts = [ grep { $_ ne $opt } @$opts ];
 356                         }
 357                         $command_opts{$command} = $opts;
 358                 }
 359         }
 360         else {
 361                 # Clear all additional options
 362                 delete $command_opts{$command};
 363         }
 364 }
 365
 366 if ($dh{LIST}) {
 367         my %addons;
 368
 369         for my $inc (@INC) {
 370                 eval q{use File::Spec};
 371                 my $path = File::Spec->catdir($inc, "Debian/Debhelper/Sequence");
 372                 if (-d $path) {
 373                         for my $module_path (glob "$path/*.pm") {
 374                                 my $name = basename($module_path);
 375                                 $name =~ s/\.pm$//;
 376                                 $name =~ s/_/-/g;
 377                                 $addons{$name} = 1;
 378                         }
 379                 }
 380         }
 381
 382         for my $name (sort keys %addons) {
 383                 print "$name\n";
 384         }
 385
 386         exit 0;
 387 }
 388
 389 foreach my $addon (@{$dh{WITH}}) {
 390         my $mod="Debian::Debhelper::Sequence::$addon";
 391         $mod=~s/-/_/g;
 392         eval "use $mod";
 393         if ($@) {
 394                 error("unable to load addon $addon: $@");
 395         }
 396 }
 397
 398 # Get the sequence of commands to run.
 399 if (! @ARGV) {
 400         error "specify a sequence to run";
 401 }
 402 my $sequence=shift;
 403 if ($sequence eq 'debian/rules' ||
 404     $sequence =~ /^override_dh_/) {
 405         # make -B causes the rules file to be run as a target
 406         # and support completly empty override targets
 407         exit 0
 408 }
 409 elsif (! exists $sequences{$sequence}) {
 410         error "Unknown sequence $sequence (choose from: ".
 411                 join(" ", sort keys %sequences).")";
 412 }
 413 my @sequence=@{$sequences{$sequence}};
 414
 415 # The list of all packages that can be acted on.
 416 my @packages=@{$dh{DOPACKAGES}};
 417
 418 # Get the options to pass to commands in the sequence.
 419 # Filter out options intended only for this program.
 420 my @options;
 421 if ($sequence eq 'binary-arch') {
 422         push @options, "-a";
 423         # as an optimisation, remove from the list any packages
 424         # that are not arch dependent
 425         my %arch_packages = map { $_ => 1 } getpackages("arch");
 426         @packages = grep { $arch_packages{$_} } @packages;
 427 }
 428 elsif ($sequence eq 'binary-indep') {
 429         push @options, "-i";
 430         # ditto optimisation for arch indep
 431         my %indep_packages = map { $_ => 1 } getpackages("indep");
 432         @packages = grep { $indep_packages{$_} } @packages;
 433 }
 434 while (@ARGV_orig) {
 435         my $opt=shift @ARGV_orig;
 436         next if $opt eq $sequence;
 437         if ($opt =~ /^--?(after|until|before|with|without)$/) {
 438                 shift @ARGV_orig;
 439                 next;
 440         }
 441         elsif ($opt =~ /^--?(no-act|remaining|(after|until|before|with|without)=)/) {
 442                 next;
 443         }
 444         push @options, $opt;
 445 }
 446
 447 # Figure out at what point in the sequence to start for each package.
 448 my %logged;
 449 my %startpoint;
 450 foreach my $package (@packages) {
 451         my @log=load_log($package, \%logged);
 452         if ($dh{AFTER}) {
 453                 # Run commands in the sequence that come after the
 454                 # specified command.
 455                 $startpoint{$package}=command_pos($dh{AFTER}, @sequence) + 1;
 456                 # Write a dummy log entry indicating that the specified
 457                 # command was, in fact, run. This handles the case where
 458                 # no commands remain to run after it, communicating to
 459                 # future dh instances that the specified command should not
 460                 # be run again.
 461                 write_log($sequence[$startpoint{$package}-1], $package);
 462         }
 463         elsif ($dh{REMAINING}) {
 464                 # Start at the beginning so all remaining commands will get
 465                 # run.
 466                 $startpoint{$package}=0;
 467         }
 468         else {
 469                 # Find the last logged command that is in the sequence, and
 470                 # continue with the next command after it. If no logged
 471                 # command is in the sequence, we're starting at the beginning..
 472                 $startpoint{$package}=0;
 473 COMMAND:        foreach my $command (reverse @log) {
 474                         foreach my $i (0..$#sequence) {
 475                                 if ($command eq $sequence[$i]) {
 476                                         $startpoint{$package}=$i+1;
 477                                         last COMMAND;
 478                                 }
 479                         }
 480                 }
 481         }
 482 }
 483
 484 # Figure out what point in the sequence to go to.
 485 my $stoppoint=$#sequence;
 486 if ($dh{UNTIL}) {
 487         $stoppoint=command_pos($dh{UNTIL}, @sequence);
 488 }
 489 elsif ($dh{BEFORE}) {
 490         $stoppoint=command_pos($dh{BEFORE}, @sequence) - 1;
 491 }
 492
 493 # Now run the commands in the sequence.
 494 foreach my $i (0..$stoppoint) {
 495         # Figure out which packages need to run this command.
 496         my @exclude;
 497         foreach my $package (@packages) {
 498                 if ($startpoint{$package} > $i ||
 499                     $logged{$package}{$sequence[$i]}) {
 500                         push @exclude, $package;
 501                 }
 502         }
 503
 504         if (@exclude eq @packages) {
 505                 # Command already done for all packages.
 506                 next;
 507         }
 508
 509         run($sequence[$i], \@packages, \@exclude, @options);
 510 }
 511
 512 sub run {
 513         my $command=shift;
 514         my @packages=@{shift()};
 515         my @exclude=@{shift()};
 516         my @options=@_;
 517
 518         # If some packages are excluded, add flags
 519         # to prevent them from being acted on.
 520         push @options, map { "-N$_" } @exclude;
 521
 522         # Check for override targets in debian/rules and
 523         # run them instead of running the command directly.
 524         my $override_command;
 525         if (rules_explicit_target("override_".$command)) {
 526                 $override_command=$command;
 527                 # This passes the options through to commands called
 528                 # inside the target.
 529                 $ENV{DH_INTERNAL_OPTIONS}=join("\x1e", @options);
 530                 $command="debian/rules";
 531                 @options="override_".$override_command;
 532         }
 533         else {
 534                 # Pass additional command options if any
 535                 unshift @options, @{$command_opts{$command}} if exists $command_opts{$command};
 536         }
 537
 538         # 3 space indent lines the command being run up under the
 539         # sequence name after "dh ".
 540         print "   ".escape_shell($command, @options)."\n";
 541
 542         if (! $dh{NO_ACT}) {
 543                 my $ret=system($command, @options);
 544                 if ($ret >> 8 != 0) {
 545                         exit $ret >> 8;
 546                 }
 547                 elsif ($ret) {
 548                         exit 1;
 549                 }
 550
 551                 if (defined $override_command) {
 552                         delete $ENV{DH_INTERNAL_OPTIONS};
 553                         # Need to handle logging for overriden commands here,
 554                         # because the actual debhelper command may not have
 555                         # been run by the rules file target.
 556                         # (But avoid logging for dh_clean since it removes
 557                         # the log earlier.)
 558                         if ($override_command ne 'dh_clean') {
 559                                 my %packages=map { $_ => 1 } @packages;
 560                                 map { delete $packages{$_} } @exclude;
 561                                 write_log($override_command, keys %packages);
 562                         }
 563                 }
 564         }
 565 }
 566
 567 {
 568 my %targets;
 569 my $rules_parsed;
 570
 571 sub rules_explicit_target {
 572         # Checks if a specified target exists as an explicit target
 573         # in debian/rules.
 574         my $target=shift;
 575
 576         if (! $rules_parsed) {
 577                 my $processing_targets = 0;
 578                 my $not_a_target = 0;
 579                 open(MAKE, "LC_ALL=C make -Rrnpsf debian/rules debhelper-fail-me 2>/dev/null |");
 580                 while (<MAKE>) {
 581                         if ($processing_targets) {
 582                                 if (/^# Not a target:/) {
 583                                         $not_a_target = 1;
 584                                 }
 585                                 else {
 586                                         if (!$not_a_target && /^([^#:]+)::?/) {
 587                                                 # Target is defined.
 588                                                 # NOTE: if it is a depenency
 589                                                 # of .PHONY it will be
 590                                                 # defined too but that's ok.
 591                                                 $targets{$1} = 1;
 592                                         }
 593                                         # "Not a target:" is always followed by
 594                                         # a target name, so resetting this one
 595                                         # here is safe.
 596                                         $not_a_target = 0;
 597                                 }
 598                         } elsif (/^# Files$/) {
 599                                 $processing_targets = 1;
 600                         }
 601                 }
 602                 close MAKE;
 603                 $rules_parsed = 1;
 604         }
 605
 606         return exists $targets{$target};
 607 }
 608
 609 }
 610
 611 =head1 SEE ALSO
 612
 613 L<debhelper(7)>
 614
 615 This program is a part of debhelper.
 616
 617 =head1 AUTHOR
 618
 619 Joey Hess <joeyh@debian.org>
 620
 621 =cut