dh_install

   1 #!/usr/bin/perl -w
   2
   3 =head1 NAME
   4
   5 dh_install - install files into package build directories
   6
   7 =cut
   8
   9 use strict;
  10 use File::Find;
  11 use Debian::Debhelper::Dh_Lib;
  12
  13 =head1 SYNOPSIS
  14
  15 B<dh_install> [B<-X>I<item>] [B<--autodest>] [B<--sourcedir=>I<dir>] [S<I<debhelper options>>] [S<I<file|dir> ... I<destdir>>]
  16
  17 =head1 DESCRIPTION
  18
  19 B<dh_install> is a debhelper program that handles installing files into package
  20 build directories. There are many B<dh_install>I<*> commands that handle installing
  21 specific types of files such as documentation, examples, man pages, and so on,
  22 and they should be used when possible as they often have extra intelligence for
  23 those particular tasks. B<dh_install>, then, is useful for installing everything
  24 else, for which no particular intelligence is needed. It is a replacement for
  25 the old B<dh_movefiles> command.
  26
  27 This program may be used in one of two ways. If you just have a file or two
  28 that the upstream Makefile does not install for you, you can run B<dh_install>
  29 on them to move them into place. On the other hand, maybe you have a large
  30 package that builds multiple binary packages. You can use the upstream
  31 F<Makefile> to install it all into F<debian/tmp>, and then use B<dh_install> to copy
  32 directories and files from there into the proper package build directories.
  33
  34 From debhelper compatibility level 7 on, B<dh_install> will fall back to
  35 looking in F<debian/tmp> for files, if it doesn't find them in the current
  36 directory (or whereever you've told it to look using B<--sourcedir>).
  37
  38 =head1 FILES
  39
  40 =over 4
  41
  42 =item debian/I<package>.install
  43
  44 List the files to install into each package and the directory they should be
  45 installed to. The format is a set of lines, where each line lists a file or
  46 files to install, and at the end of the line tells the directory it should be
  47 installed in. The name of the files (or directories) to install should be given
  48 relative to the current directory, while the installation directory is given
  49 relative to the package build directory. You may use wildcards in the names of
  50 the files to install (in v3 mode and above).
  51
  52 Note that if you list exactly one filename or wildcard-pattern on a line by
  53 itself, with no explicit destination, then B<dh_install>
  54 will automatically guess the destination to use, the same as if the
  55 --autodest option were used.
  56
  57 =back
  58
  59 =head1 OPTIONS
  60
  61 =over 4
  62
  63 =item B<--list-missing>
  64
  65 This option makes B<dh_install> keep track of the files it installs, and then at
  66 the end, compare that list with the files in the source directory. If any of
  67 the files (and symlinks) in the source directory were not installed to
  68 somewhere, it will warn on stderr about that.
  69
  70 This may be useful if you have a large package and want to make sure that
  71 you don't miss installing newly added files in new upstream releases.
  72
  73 Note that files that are excluded from being moved via the B<-X> option are not
  74 warned about.
  75
  76 =item B<--fail-missing>
  77
  78 This option is like B<--list-missing>, except if a file was missed, it will
  79 not only list the missing files, but also fail with a nonzero exit code.
  80
  81 =item B<-X>I<item>, B<--exclude=>I<item>
  82
  83 Exclude files that contain I<item> anywhere in their filename from
  84 being installed.
  85
  86 =item B<--sourcedir=>I<dir>
  87
  88 Look in the specified directory for files to be installed.
  89
  90 Note that this is not the same as the B<--sourcedirectory> option used
  91 by the B<dh_auto_>I<*> commands. You rarely need to use this option, since
  92 B<dh_install> automatically looks for files in F<debian/tmp> in debhelper
  93 compatibility level 7 and above.
  94
  95 =item B<--autodest>
  96
  97 Guess as the destination directory to install things to. If this is
  98 specified, you should not list destination directories in
  99 F<debian/package.install> files or on the command line. Instead, B<dh_install>
 100 will guess as follows:
 101
 102 Strip off F<debian/tmp> (or the sourcedir if one is given) from the front of
 103 the filename, if it is present, and install into the dirname of the
 104 filename. So if the filename is F<debian/tmp/usr/bin>, then that directory
 105 will be copied to F<debian/package/usr/>. If the filename is
 106 F<debian/tmp/etc/passwd>, it will be copied to F<debian/package/etc/>.
 107
 108 =item I<file|dir> ... I<destdir>
 109
 110 Lists files (or directories) to install and where to install them to.
 111 The files will be installed into the first package F<dh_install> acts on.
 112
 113 =back
 114
 115 =cut
 116
 117 init(options => {
 118         "autodest" => \$dh{AUTODEST},
 119         "list-missing" => \$dh{LIST_MISSING},
 120         "fail-missing" => \$dh{FAIL_MISSING},
 121         "sourcedir=s" => \$dh{SOURCEDIR},
 122 });
 123
 124 my @installed;
 125
 126 my $srcdir = '.';
 127 $srcdir = $dh{SOURCEDIR} if defined $dh{SOURCEDIR};
 128
 129 foreach my $package (getpackages()) {
 130         # Look at the install files for all packages to handle
 131         # list-missing/fail-missing, but skip really installing for
 132         # packages that are not being acted on.
 133         my $skip_install=! grep { $_ eq $package } @{$dh{DOPACKAGES}};
 134
 135         my $tmp=tmpdir($package);
 136         my $file=pkgfile($package,"install");
 137
 138         my @install;
 139         if ($file) {
 140                 @install=filedoublearray($file); # no globbing here; done below
 141         }
 142
 143         if (($package eq $dh{FIRSTPACKAGE} || $dh{PARAMS_ALL}) && @ARGV) {
 144                 push @install, [@ARGV];
 145         }
 146
 147         # Support for -X flag.
 148         my $exclude = '';
 149         if ($dh{EXCLUDE_FIND}) {
 150                 $exclude = '! \( '.$dh{EXCLUDE_FIND}.' \)';
 151         }
 152
 153         foreach my $set (@install) {
 154                 my $dest;
 155                 my $tmpdest=0;
 156
 157                 if (! defined $dh{AUTODEST} && @$set > 1) {
 158                         $dest=pop @$set;
 159                 }
 160
 161                 my @filelist;
 162                 foreach my $glob (@$set) {
 163                         my @found = glob "$srcdir/$glob";
 164                         if (! compat(6)) {
 165                                 # Fall back to looking in debian/tmp.
 166                                 if (! @found || ! (-e $found[0] || -l $found[0])) {
 167                                         @found = glob "debian/tmp/$glob";
 168                                 }
 169                         }
 170                         push @filelist, @found;
 171                 }
 172
 173                 if (! compat(4)) { # check added in v5
 174                         if (! @filelist && ! $skip_install) {
 175                                 error("$package missing files (@$set), aborting");
 176                         }
 177                 }
 178
 179                 foreach my $src (@filelist) {
 180                         next if excludefile($src);
 181
 182                         push @installed, $src;
 183                         next if $skip_install;
 184
 185                         if (! defined $dest) {
 186                                 # Guess at destination directory.
 187                                 $dest=$src;
 188                                 $dest=~s/^(.*\/)?\Q$srcdir\E\///;
 189                                 $dest=~s/^(.*\/)?debian\/tmp\///;
 190                                 $dest=dirname("/".$dest);
 191                                 $tmpdest=1;
 192                         }
 193
 194                         # Make sure the destination directory exists.
 195                         if (! -e "$tmp/$dest") {
 196                                 doit("install","-d","$tmp/$dest");
 197                         }
 198
 199                         if (-d $src && $exclude) {
 200                                 my $basename = basename($src);
 201                                 my $dir = ($basename eq '.') ? $src : "$src/..";
 202                                 my $pwd=`pwd`;
 203                                 chomp $pwd;
 204                                 complex_doit("cd '$dir' && find '$basename' $exclude \\( -type f -or -type l \\) -exec cp --parents -dp {} $pwd/$tmp/$dest/ \\;");
 205                                 # cp is annoying so I need a separate pass
 206                                 # just for empty directories
 207                                 complex_doit("cd '$dir' && find '$basename' $exclude \\( -type d -and -empty \\) -exec cp --parents -a {} $pwd/$tmp/$dest/ \\;");
 208                         }
 209                         else {
 210                                 doit("cp", "-a", $src, "$tmp/$dest/");
 211                         }
 212
 213                         if ($tmpdest) {
 214                                 $dest=undef;
 215                         }
 216                 }
 217         }
 218 }
 219
 220 if ($dh{LIST_MISSING} || $dh{FAIL_MISSING}) {
 221         # . as srcdir makes no sense, so this is a special case.
 222         if ($srcdir eq '.') {
 223                 $srcdir='debian/tmp';
 224         }
 225
 226         my @missing;
 227         my $installed=join("|", map {
 228                 # Kill any extra slashes, for robustness.
 229                 y:/:/:s;
 230                 s:/+$::;
 231                 s:^(\./)*::;
 232                 "\Q$_\E\/.*|\Q$_\E";
 233         } @installed);
 234         $installed=qr{^($installed)$};
 235         find(sub {
 236                 -f || -l || return;
 237                 $_="$File::Find::dir/$_";
 238                 if (! /$installed/ && ! excludefile($_)) {
 239                         my $file=$_;
 240                         $file=~s/^\Q$srcdir\E\///;
 241                         push @missing, $file;
 242                 }
 243         }, $srcdir);
 244         if (@missing) {
 245                 warning "$_ exists in $srcdir but is not installed to anywhere" foreach @missing;
 246                 if ($dh{FAIL_MISSING}) {
 247                         error("missing files, aborting");
 248                 }
 249         }
 250 }
 251
 252 =head1 LIMITATIONS
 253
 254 B<dh_install> cannot rename files or directories, it can only install them
 255 with the names they already have into wherever you want in the package
 256 build tree.
 257
 258 =head1 SEE ALSO
 259
 260 L<debhelper(7)>
 261
 262 This program is a part of debhelper.
 263
 264 =head1 AUTHOR
 265
 266 Joey Hess <joeyh@debian.org>
 267
 268 =cut