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