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