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