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