dh_installdocs

   1 #!/usr/bin/perl -w
   2
   3 =head1 NAME
   4
   5 dh_installdocs - install documentation into package build directories
   6
   7 =cut
   8
   9 use strict;
  10 use Debian::Debhelper::Dh_Lib;
  11
  12 =head1 SYNOPSIS
  13
  14 B<dh_installdocs> [S<I<debhelper options>>] [B<-A>] [B<-n>] [B<-X>I<item>] [S<I<file ...>>]
  15
  16 =head1 DESCRIPTION
  17
  18 dh_installdocs is a debhelper program that is responsible for installing
  19 documentation into usr/share/doc/package in package build directories.
  20
  21 dh_installdocs automatically installs debian/copyright if it exists. If
  22 dh_installdocs is acting on multiple packages, debian/copyright files will be
  23 installed into all packages. However, if you need to have seperate copyright
  24 files for different binary packages, you can use files named
  25 debian/package.copyright.
  26
  27 Any filenames specified as parameters will be installed into the first
  28 package dh_installdocs is told to act on. By default, this is the first
  29 binary package in debian/control, but if you use B<-p>, B<-i>, or B<-a> flags, it
  30 will be the first package specified by those flags.
  31
  32 Also, debian/README.Debian (or debian/README.debian) and debian/TODO, if
  33 they exist, will be installed into the first binary package listed in
  34 debian/control, if dh_installdocs is acting on that package. Note that
  35 debian/TODO will be installed named TODO.Debian, if the package is not a
  36 debian native package. Also note that README.debian is installed as
  37 README.Debian, for consistency. Note that debian/package.README.Debian and
  38 debian/package.TODO can be used to specify files for subpackages.
  39
  40 Files named debian/package.docs can list other files to be installed.
  41
  42 Files named debian/package.doc-base, will be installed as doc-base control
  43 files, and will make this program automatically generate the postinst and
  44 prerm commands needed to interface with the doc-base package. Note that the
  45 doc-id will be determined from the "Document:" entry in the
  46 doc-base control file in question.
  47
  48 If your package needs to register more than one document, you need multiple
  49 files. To accomplish this, you can use files named debian/package.doc-base.*
  50
  51 =head1 OPTIONS
  52
  53 =over 4
  54
  55 =item B<-A>, B<--all>
  56
  57 Install all files specified by command line parameters in ALL packages
  58 acted on.
  59
  60 =item B<-n>, B<--noscripts>
  61
  62 Do not modify postinst/prerm scripts.
  63
  64 =item B<-Xitem>, B<--exclude=item>
  65
  66 Exclude files that contain "item" anywhere in their filename from
  67 being installed.
  68
  69 =item I<file ...>
  70
  71 Install these files as documentation into the first package acted on. (Or
  72 in all packages if B<-A> is specified).
  73
  74 =back
  75
  76 =head1 NOTES
  77
  78 Note that dh_installdocs will happily copy entire directory hierarchies if
  79 you ask it to (similar to cp -a). If it is asked to install a
  80 directory, it will install the complete contents of the directory.
  81
  82 Note that this command is not idempotent. "dh_clean B<-k>" should be called
  83 between invocations of this command. Otherwise, it may cause multiple
  84 instances of the same text to be added to maintainer scripts.
  85
  86 =cut
  87
  88 init();
  89
  90 foreach my $package (@{$dh{DOPACKAGES}}) {
  91         next if is_udeb($package);
  92
  93         my $tmp=tmpdir($package);
  94         my $file=pkgfile($package,"docs");
  95
  96         # If this is a symlink, leave it alone.
  97         if ( ! -d "$tmp/usr/share/doc/$package" &&
  98              ! -l "$tmp/usr/share/doc/$package") {
  99                 doit("install","-g",0,"-o",0,"-d","$tmp/usr/share/doc/$package");
 100         }
 101
 102         my @docs;
 103
 104         if ($file) {
 105                 @docs=filearray($file, ".");
 106         }
 107
 108         if (($package eq $dh{FIRSTPACKAGE} || $dh{PARAMS_ALL}) && @ARGV) {
 109                 push @docs, @ARGV;
 110         }
 111
 112         if (@docs) {
 113                 my $exclude = '';
 114                 if ($dh{EXCLUDE_FIND}) {
 115                         $exclude = ' -and ! \( '.$dh{EXCLUDE_FIND}.' \)';
 116                 }
 117                 foreach my $doc (@docs) {
 118                         next if excludefile($doc);
 119                         if (-d $doc && $exclude) {
 120                             my ($dir_basename) = basename($doc);
 121                             # Pity there's no cp --exclude ..
 122                             my $pwd=`pwd`;
 123                             chomp $pwd;
 124                             complex_doit("cd $doc/.. && find $dir_basename -type f$exclude -exec cp --parents -dp {} $pwd/$tmp/usr/share/doc/$package \\;");
 125                         }
 126                         else {
 127                                 doit("cp","-a",$doc,"$tmp/usr/share/doc/$package");
 128                         }
 129                 }
 130                 doit("chown","-R","0:0","$tmp/usr/share/doc");
 131                 doit("chmod","-R","go=rX","$tmp/usr/share/doc");
 132                 doit("chmod","-R","u+rw","$tmp/usr/share/doc");
 133         }
 134
 135         # .Debian is correct, according to policy, but I'm easy.
 136         my $readme_debian=pkgfile($package,'README.Debian');
 137         if (! $readme_debian) {
 138                 $readme_debian=pkgfile($package,'README.debian');
 139         }
 140         if ($readme_debian && ! excludefile($readme_debian)) {
 141                 doit("install","-g",0,"-o",0,"-m","644","-p","$readme_debian",
 142                         "$tmp/usr/share/doc/$package/README.Debian");
 143         }
 144
 145         my $todo=pkgfile($package,'TODO');
 146         if ($todo && ! excludefile($todo)) {
 147                 if (isnative($package)) {
 148                         doit("install","-g",0,"-o",0,"-m","644","-p",$todo,
 149                                 "$tmp/usr/share/doc/$package/TODO");
 150                 }
 151                 else {
 152                         doit("install","-g",0,"-o",0,"-m","644","-p",$todo,
 153                                 "$tmp/usr/share/doc/$package/TODO.Debian");
 154                 }
 155         }
 156
 157         # If the "directory" is a dangling symlink, then don't install
 158         # the copyright file. This is useful for multibinary packages
 159         # that share a doc directory.
 160         if (-d "$tmp/usr/share/doc/$package") {
 161                 # Support debian/package.copyright, but if not present, fall
 162                 # back on debian/copyright for all packages, not just the
 163                 # main binary package.
 164                 my $copyright=pkgfile($package,'copyright');
 165                 if (! $copyright && -e "debian/copyright") {
 166                         $copyright="debian/copyright";
 167                 }
 168                 if ($copyright && ! excludefile($copyright)) {
 169                                 doit("install","-g",0,"-o",0,"-m","644","-p",$copyright,
 170                                         "$tmp/usr/share/doc/$package/copyright");
 171                 }
 172         }
 173
 174         # Handle doc-base files. There are two filename formats, the usual
 175         # plus an extended format (debian/package.*).
 176         my %doc_ids;
 177
 178         opendir(DEB,"debian/") || error("can't read debian directory: $!");
 179         # If this is the main package, we need to handle unprefixed filenames.
 180         # For all packages, we must support both the usual filename format plus
 181         # that format with a period an something appended.
 182         my $regexp="\Q$package\E\.";
 183         if ($package eq $dh{MAINPACKAGE}) {
 184                 $regexp="(|$regexp)";
 185         }
 186         foreach my $fn (grep {/^${regexp}doc-base(\..*)?$/} readdir(DEB)) {
 187                 # .EX are example files, generated by eg, dh-make
 188                 next if $fn=~/\.EX$/;
 189                 # Parse the file to get the doc id.
 190                 open (IN, "debian/$fn") || die "Cannot read debian/$fn.";
 191                 while (<IN>) {
 192                         if (/^Document:\s+(.*)(\s+)?/) {
 193                                 $doc_ids{$fn}=$1;
 194                                 last;
 195                         }
 196                 }
 197                 close IN;
 198         }
 199         closedir(DEB);
 200
 201         if (%doc_ids) {
 202                 if (! -d "$tmp/usr/share/doc-base/") {
 203                         doit("install","-g",0,"-o",0,"-d","$tmp/usr/share/doc-base/");
 204                 }
 205         }
 206         foreach my $fn (keys %doc_ids) {
 207                 doit("install","-g",0,"-o",0,"-m644","-p","debian/$fn",
 208                      "$tmp/usr/share/doc-base/$doc_ids{$fn}");
 209                 if (! $dh{NOSCRIPTS}) {
 210                         autoscript($package,"postinst","postinst-doc-base",
 211                                 "s/#DOC-ID#/$doc_ids{$fn}/",
 212                         );
 213                         autoscript($package,"prerm","prerm-doc-base",
 214                                 "s/#DOC-ID#/$doc_ids{$fn}/",
 215                         );
 216                 }
 217         }
 218 }
 219
 220 =head1 SEE ALSO
 221
 222 L<debhelper(7)>
 223
 224 This program is a part of debhelper.
 225
 226 =head1 AUTHOR
 227
 228 Joey Hess <joeyh@debian.org>
 229
 230 =cut