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