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 separate 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. Note that this includes doc-base files.
  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 EXAMPLES
  77
  78 This is an example of a debian/package.docs file:
  79
  80   README
  81   TODO
  82   debian/notes-for-maintainers.txt
  83   docs/manual.txt
  84   docs/manual.pdf
  85   docs/manual-html/
  86
  87 =head1 NOTES
  88
  89 Note that dh_installdocs will happily copy entire directory hierarchies if
  90 you ask it to (similar to cp -a). If it is asked to install a
  91 directory, it will install the complete contents of the directory.
  92
  93 Note that this command is not idempotent. L<dh_prep(1)> should be called
  94 between invocations of this command. Otherwise, it may cause multiple
  95 instances of the same text to be added to maintainer scripts.
  96
  97 =cut
  98
  99 init();
 100
 101 foreach my $package (@{$dh{DOPACKAGES}}) {
 102         next if is_udeb($package);
 103
 104         my $tmp=tmpdir($package);
 105         my $file=pkgfile($package,"docs");
 106
 107         # If this is a symlink, leave it alone.
 108         if ( ! -d "$tmp/usr/share/doc/$package" &&
 109              ! -l "$tmp/usr/share/doc/$package") {
 110                 doit("install","-g",0,"-o",0,"-d","$tmp/usr/share/doc/$package");
 111         }
 112
 113         my @docs;
 114
 115         if ($file) {
 116                 @docs=filearray($file, ".");
 117         }
 118
 119         if (($package eq $dh{FIRSTPACKAGE} || $dh{PARAMS_ALL}) && @ARGV) {
 120                 push @docs, @ARGV;
 121         }
 122
 123         if (@docs) {
 124                 my $exclude = '';
 125                 if ($dh{EXCLUDE_FIND}) {
 126                         $exclude .= ' -and ! \( '.$dh{EXCLUDE_FIND}.' \)';
 127                 }
 128                 if (! compat(4)) {
 129                         # ignore empty files in subdirs
 130                         $exclude .= ' -and ! -empty';
 131                 }
 132                 foreach my $doc (@docs) {
 133                         next if excludefile($doc);
 134                         next if -e $doc && ! -s $doc && ! compat(4); # ignore empty files
 135                         if (-d $doc && length $exclude) {
 136                                 my $basename = basename($doc);
 137                                 my $dir = ($basename eq '.') ? $doc : "$doc/..";
 138                                 my $pwd=`pwd`;
 139                                 chomp $pwd;
 140                                 complex_doit("cd '$dir' && find '$basename' \\( -type f -or -type l \\)$exclude -exec cp --parents -dp {} $pwd/$tmp/usr/share/doc/$package \\;");
 141                         }
 142                         else {
 143                                 doit("cp", "-a", $doc, "$tmp/usr/share/doc/$package");
 144                         }
 145                 }
 146                 doit("chown","-R","0:0","$tmp/usr/share/doc");
 147                 doit("chmod","-R","go=rX","$tmp/usr/share/doc");
 148                 doit("chmod","-R","u+rw","$tmp/usr/share/doc");
 149         }
 150
 151         # .Debian is correct, according to policy, but I'm easy.
 152         my $readme_debian=pkgfile($package,'README.Debian');
 153         if (! $readme_debian) {
 154                 $readme_debian=pkgfile($package,'README.debian');
 155         }
 156         if ($readme_debian && ! excludefile($readme_debian)) {
 157                 doit("install","-g",0,"-o",0,"-m","644","-p","$readme_debian",
 158                         "$tmp/usr/share/doc/$package/README.Debian");
 159         }
 160
 161         my $todo=pkgfile($package,'TODO');
 162         if ($todo && ! excludefile($todo)) {
 163                 if (isnative($package)) {
 164                         doit("install","-g",0,"-o",0,"-m","644","-p",$todo,
 165                                 "$tmp/usr/share/doc/$package/TODO");
 166                 }
 167                 else {
 168                         doit("install","-g",0,"-o",0,"-m","644","-p",$todo,
 169                                 "$tmp/usr/share/doc/$package/TODO.Debian");
 170                 }
 171         }
 172
 173         # If the "directory" is a dangling symlink, then don't install
 174         # the copyright file. This is useful for multibinary packages
 175         # that share a doc directory.
 176         if (-d "$tmp/usr/share/doc/$package") {
 177                 # Support debian/package.copyright, but if not present, fall
 178                 # back on debian/copyright for all packages, not just the
 179                 # main binary package.
 180                 my $copyright=pkgfile($package,'copyright');
 181                 if (! $copyright && -e "debian/copyright") {
 182                         $copyright="debian/copyright";
 183                 }
 184                 if ($copyright && ! excludefile($copyright)) {
 185                                 doit("install","-g",0,"-o",0,"-m","644","-p",$copyright,
 186                                         "$tmp/usr/share/doc/$package/copyright");
 187                 }
 188         }
 189
 190         # Handle doc-base files. There are two filename formats, the usual
 191         # plus an extended format (debian/package.*).
 192         my %doc_ids;
 193
 194         opendir(DEB,"debian/") || error("can't read debian directory: $!");
 195         # If this is the main package, we need to handle unprefixed filenames.
 196         # For all packages, we must support both the usual filename format plus
 197         # that format with a period an something appended.
 198         my $regexp="\Q$package\E\.";
 199         if ($package eq $dh{MAINPACKAGE}) {
 200                 $regexp="(|$regexp)";
 201         }
 202         foreach my $fn (grep {/^${regexp}doc-base(\..*)?$/} readdir(DEB)) {
 203                 # .EX are example files, generated by eg, dh-make
 204                 next if $fn=~/\.EX$/;
 205                 next if excludefile($fn);
 206                 # Parse the file to get the doc id.
 207                 open (IN, "debian/$fn") || die "Cannot read debian/$fn.";
 208                 while (<IN>) {
 209                         if (/^Document:\s+([-+.a-z0-9]+)/) {
 210                                 $doc_ids{$fn}=$1;
 211                                 last;
 212                         }
 213                 }
 214                 close IN;
 215         }
 216         closedir(DEB);
 217
 218         if (%doc_ids) {
 219                 if (! -d "$tmp/usr/share/doc-base/") {
 220                         doit("install","-g",0,"-o",0,"-d","$tmp/usr/share/doc-base/");
 221                 }
 222         }
 223         foreach my $fn (keys %doc_ids) {
 224                 doit("install","-g",0,"-o",0,"-m644","-p","debian/$fn",
 225                      "$tmp/usr/share/doc-base/$doc_ids{$fn}");
 226                 if (! $dh{NOSCRIPTS}) {
 227                         autoscript($package,"postinst","postinst-doc-base",
 228                                 "s/#DOC-ID#/$doc_ids{$fn}/",
 229                         );
 230                         autoscript($package,"prerm","prerm-doc-base",
 231                                 "s/#DOC-ID#/$doc_ids{$fn}/",
 232                         );
 233                 }
 234         }
 235 }
 236
 237 =head1 SEE ALSO
 238
 239 L<debhelper(7)>
 240
 241 This program is a part of debhelper.
 242
 243 =head1 AUTHOR
 244
 245 Joey Hess <joeyh@debian.org>
 246
 247 =cut