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