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 =cut
 175
 176 # Stash this away before init modifies it.
 177 my @ARGV_orig=@ARGV;
 178
 179 # python-support is enabled by default, at least for now
 180 # (and comes first so python-central loads later and can disable it).
 181 unshift @ARGV, "--with=python-support";
 182
 183 init(options => {
 184         "until=s" => \$dh{UNTIL},
 185         "after=s" => \$dh{AFTER},
 186         "before=s" => \$dh{BEFORE},
 187         "remaining" => \$dh{REMAINING},
 188         "with=s" => sub {
 189                 my ($option,$value)=@_;
 190                 push @{$dh{WITH}},$value;
 191         },
 192         "without=s" => sub {
 193                 my ($option,$value)=@_;
 194                 @{$dh{WITH}} = grep { $_ ne $value } @{$dh{WITH}};
 195         },
 196 });
 197 inhibit_log();
 198
 199 # Definitions of sequences.
 200 my %sequences;
 201 $sequences{build} = [qw{
 202         dh_testdir
 203         dh_auto_configure
 204         dh_auto_build
 205         dh_auto_test
 206 }],
 207 $sequences{clean} = [qw{
 208         dh_testdir
 209         dh_auto_clean
 210         dh_clean
 211 }];
 212 $sequences{install} = [@{$sequences{build}}, qw{
 213         dh_testroot
 214         dh_prep
 215         dh_installdirs
 216         dh_auto_install
 217
 218         dh_install
 219         dh_installdocs
 220         dh_installchangelogs
 221         dh_installexamples
 222         dh_installman
 223
 224         dh_installcatalogs
 225         dh_installcron
 226         dh_installdebconf
 227         dh_installcatalogs
 228         dh_installemacsen
 229         dh_installifupdown
 230         dh_installinfo
 231         dh_installinit
 232         dh_installmenu
 233         dh_installmime
 234         dh_installmodules
 235         dh_installlogcheck
 236         dh_installlogrotate
 237         dh_installpam
 238         dh_installppp
 239         dh_installudev
 240         dh_installwm
 241         dh_installxfonts
 242         dh_bugfiles
 243         dh_lintian
 244         dh_gconf
 245         dh_icons
 246         dh_perl
 247         dh_scrollkeeper
 248         dh_usrlocal
 249
 250         dh_link
 251         dh_compress
 252         dh_fixperms
 253 }];
 254 my @b=qw{
 255         dh_installdeb
 256         dh_gencontrol
 257         dh_md5sums
 258         dh_builddeb
 259 };
 260 $sequences{'binary-indep'} = [@{$sequences{install}}, @b];
 261 $sequences{binary} = [@{$sequences{install}}, qw{
 262         dh_strip
 263         dh_makeshlibs
 264         dh_shlibdeps
 265 }, @b];
 266 $sequences{'binary-arch'} = [@{$sequences{binary}}];
 267
 268 # sequence addon interface
 269 sub _insert {
 270         my $offset=shift;
 271         my $existing=shift;
 272         my $new=shift;
 273         foreach my $sequence (keys %sequences) {
 274                 my @list=@{$sequences{$sequence}};
 275                 next unless grep $existing, @list;
 276                 my @new;
 277                 foreach my $command (@list) {
 278                         if ($command eq $existing) {
 279                                 push @new, $new if $offset < 0;
 280                                 push @new, $command;
 281                                 push @new, $new if $offset > 0;
 282                         }
 283                         else {
 284                                 push @new, $command;
 285                         }
 286                 }
 287                 $sequences{$sequence}=\@new;
 288         }
 289 }
 290 sub insert_before {
 291         _insert(-1, @_);
 292 }
 293 sub insert_after {
 294         _insert(1, @_);
 295 }
 296 sub remove_command {
 297         my $command=shift;
 298         foreach my $sequence (keys %sequences) {
 299                 $sequences{$sequence}=[grep { $_ ne $command } @{$sequences{$sequence}}];
 300         }
 301
 302 }
 303 foreach my $addon (@{$dh{WITH}}) {
 304         my $mod="Debian::Debhelper::Sequence::$addon";
 305         $mod=~s/-/_/g;
 306         eval "use $mod";
 307         if ($@) {
 308                 error("--with $addon not supported or failed to load module $mod");
 309         }
 310 }
 311
 312 # Get the sequence of commands to run.
 313 if (! @ARGV) {
 314         error "specify a sequence to run";
 315 }
 316 my $sequence=shift;
 317 if ($sequence eq 'debian/rules' ||
 318     $sequence =~ /^override_dh_/) {
 319         # make -B causes the rules file to be run as a target
 320         # and support completly empty override targets
 321         exit 0
 322 }
 323 elsif (! exists $sequences{$sequence}) {
 324         error "Unknown sequence $sequence (choose from: ".
 325                 join(" ", sort keys %sequences).")";
 326 }
 327 my @sequence=@{$sequences{$sequence}};
 328
 329 # The list of all packages that can be acted on.
 330 my @packages=@{$dh{DOPACKAGES}};
 331
 332 # Get the options to pass to commands in the sequence.
 333 # Filter out options intended only for this program.
 334 my @options;
 335 if ($sequence eq 'binary-arch') {
 336         push @options, "-a";
 337         # as an optimisation, remove from the list any packages
 338         # that are not arch dependent
 339         my %arch_packages = map { $_ => 1 } getpackages("arch");
 340         @packages = grep { $arch_packages{$_} } @packages;
 341 }
 342 elsif ($sequence eq 'binary-indep') {
 343         push @options, "-i";
 344         # ditto optimisation for arch indep
 345         my %indep_packages = map { $_ => 1 } getpackages("indep");
 346         @packages = grep { $indep_packages{$_} } @packages;
 347 }
 348 while (@ARGV_orig) {
 349         my $opt=shift @ARGV_orig;
 350         next if $opt eq $sequence;
 351         if ($opt =~ /^--?(after|until|before|with|without)$/) {
 352                 shift @ARGV_orig;
 353                 next;
 354         }
 355         elsif ($opt =~ /^--?(no-act|remaining|(after|until|before|with|without)=)/) {
 356                 next;
 357         }
 358         push @options, $opt;
 359 }
 360
 361 # Figure out at what point in the sequence to start for each package.
 362 my %logged;
 363 my %startpoint;
 364 foreach my $package (@packages) {
 365         my @log=load_log($package, \%logged);
 366         if ($dh{AFTER}) {
 367                 # Run commands in the sequence that come after the
 368                 # specified command.
 369                 $startpoint{$package}=command_pos($dh{AFTER}, @sequence) + 1;
 370                 # Write a dummy log entry indicating that the specified
 371                 # command was, in fact, run. This handles the case where
 372                 # no commands remain to run after it, communicating to
 373                 # future dh instances that the specified command should not
 374                 # be run again.
 375                 write_log($sequence[$startpoint{$package}-1], $package);
 376         }
 377         elsif ($dh{REMAINING}) {
 378                 # Start at the beginning so all remaining commands will get
 379                 # run.
 380                 $startpoint{$package}=0;
 381         }
 382         else {
 383                 # Find the last logged command that is in the sequence, and
 384                 # continue with the next command after it. If no logged
 385                 # command is in the sequence, we're starting at the beginning..
 386                 $startpoint{$package}=0;
 387 COMMAND:        foreach my $command (reverse @log) {
 388                         foreach my $i (0..$#sequence) {
 389                                 if ($command eq $sequence[$i]) {
 390                                         $startpoint{$package}=$i+1;
 391                                         last COMMAND;
 392                                 }
 393                         }
 394                 }
 395         }
 396 }
 397
 398 # Figure out what point in the sequence to go to.
 399 my $stoppoint=$#sequence;
 400 if ($dh{UNTIL}) {
 401         $stoppoint=command_pos($dh{UNTIL}, @sequence);
 402 }
 403 elsif ($dh{BEFORE}) {
 404         $stoppoint=command_pos($dh{BEFORE}, @sequence) - 1;
 405 }
 406
 407 # Now run the commands in the sequence.
 408 foreach my $i (0..$stoppoint) {
 409         # Figure out which packages need to run this command.
 410         my @exclude;
 411         foreach my $package (@packages) {
 412                 if ($startpoint{$package} > $i ||
 413                     $logged{$package}{$sequence[$i]}) {
 414                         push @exclude, $package;
 415                 }
 416         }
 417
 418         if (@exclude eq @packages) {
 419                 # Command already done for all packages.
 420                 next;
 421         }
 422
 423         run($sequence[$i], \@packages, \@exclude, @options);
 424 }
 425
 426 sub run {
 427         my $command=shift;
 428         my @packages=@{shift()};
 429         my @exclude=@{shift()};
 430         my @options=@_;
 431
 432         # If some packages are excluded, add flags
 433         # to prevent them from being acted on.
 434         push @options, map { "-N$_" } @exclude;
 435
 436         # Check for override targets in debian/rules and
 437         # run them instead of running the command directly.
 438         my $override_command;
 439         if (rules_explicit_target("override_".$command)) {
 440                 $override_command=$command;
 441                 # This passes the options through to commands called
 442                 # inside the target.
 443                 $ENV{DH_INTERNAL_OPTIONS}=join(" ", @options);
 444                 $command="debian/rules";
 445                 @options="override_".$override_command;
 446         }
 447
 448         # 3 space indent lines the command being run up under the
 449         # sequence name after "dh ".
 450         print "   ".escape_shell($command, @options)."\n";
 451
 452         if (! $dh{NO_ACT}) {
 453                 my $ret=system($command, @options);
 454                 if ($ret >> 8 != 0) {
 455                         exit $ret >> 8;
 456                 }
 457                 elsif ($ret) {
 458                         exit 1;
 459                 }
 460
 461                 if (defined $override_command) {
 462                         delete $ENV{DH_INTERNAL_OPTIONS};
 463                         # Need to handle logging for overriden commands here,
 464                         # because the actual debhelper command may not have
 465                         # been run by the rules file target.
 466                         my %packages=map { $_ => 1 } @packages;
 467                         map { delete $packages{$_} } @exclude;
 468                         write_log($override_command, keys %packages);
 469                 }
 470         }
 471 }
 472
 473 {
 474 my %targets;
 475 my $rules_parsed;
 476
 477 sub rules_explicit_target {
 478         # Checks if a specified target exists as an explicit target
 479         # in debian/rules.
 480         my $target=shift;
 481
 482         if (! $rules_parsed) {
 483                 my $processing_targets = 0;
 484                 my $not_a_target = 0;
 485                 open(MAKE, "LC_ALL=C make -Rrnpsf debian/rules debhelper-fail-me 2>/dev/null |");
 486                 while (<MAKE>) {
 487                         if ($processing_targets) {
 488                                 if (/^# Not a target:/) {
 489                                         $not_a_target = 1;
 490                                 }
 491                                 else {
 492                                         if (!$not_a_target && /^([^#:]+)::?/) {
 493                                                 # Target is defined.
 494                                                 # NOTE: if it is a depenency
 495                                                 # of .PHONY it will be
 496                                                 # defined too but that's ok.
 497                                                 $targets{$1} = 1;
 498                                         }
 499                                         # "Not a target:" is always followed by
 500                                         # a target name, so resetting this one
 501                                         # here is safe.
 502                                         $not_a_target = 0;
 503                                 }
 504                         } elsif (/^# Files$/) {
 505                                 $processing_targets = 1;
 506                         }
 507                 }
 508                 close MAKE;
 509                 $rules_parsed = 1;
 510         }
 511
 512         return exists $targets{$target};
 513 }
 514
 515 }
 516
 517 =head1 SEE ALSO
 518
 519 L<debhelper(7)>
 520
 521 This program is a part of debhelper.
 522
 523 =head1 AUTHOR
 524
 525 Joey Hess <joeyh@debian.org>
 526
 527 =cut