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