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 documentation 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 B<--link-doc=>I<package>
  75
  76 Make the documentation directory of all packages acted on be a symlink to
  77 the documentation directory of I<package>. This has no effect when acting on
  78 I<package> itself, or if the documentation directory to be created already
  79 exists when B<dh_installdocs> is run. To comply with policy, I<package> must
  80 be a binary package that comes from the same source package.
  81
  82 debhelper will try to avoid installing files into linked documentation
  83 directories that would cause conflicts with the linked package. The B<-A>
  84 option will have no effect on packages with linked documentation
  85 directories, and copyright, changelog, README.Debian, and TODO files will
  86 not be installed.
  87
  88 (An older method to accomplish the same thing, which is still supported,
  89 is to make the documentation directory of a package be a dangling symlink,
  90 before calling dh_installdocs.)
  91
  92 =item I<file ...>
  93
  94 Install these files as documentation into the first package acted on. (Or
  95 in all packages if B<-A> is specified).
  96
  97 =back
  98
  99 =head1 EXAMPLES
 100
 101 This is an example of a debian/package.docs file:
 102
 103   README
 104   TODO
 105   debian/notes-for-maintainers.txt
 106   docs/manual.txt
 107   docs/manual.pdf
 108   docs/manual-html/
 109
 110 =head1 NOTES
 111
 112 Note that dh_installdocs will happily copy entire directory hierarchies if
 113 you ask it to (similar to cp -a). If it is asked to install a
 114 directory, it will install the complete contents of the directory.
 115
 116 Note that this command is not idempotent. L<dh_prep(1)> should be called
 117 between invocations of this command. Otherwise, it may cause multiple
 118 instances of the same text to be added to maintainer scripts.
 119
 120 =cut
 121
 122 my %docdir_created;
 123 # Create documentation directories on demand. This allows us to use dangling
 124 # symlinks for linked documentation directories unless additional files need
 125 # to be installed.
 126 sub ensure_docdir {
 127         my $package=shift;
 128         return if $docdir_created{$package};
 129         my $tmp=tmpdir($package);
 130
 131         my $target;
 132         if ($dh{LINK_DOC} && $dh{LINK_DOC} ne $package) {
 133                 $target="$tmp/usr/share/doc/$dh{LINK_DOC}";
 134         }
 135         else {
 136                 $target="$tmp/usr/share/doc/$package";
 137         }
 138
 139         # If this is a symlink, leave it alone.
 140         if (! -d $target && ! -l $target) {
 141                 doit("install","-g",0,"-o",0,"-d",$target);
 142         }
 143         $docdir_created{$package}=1;
 144 }
 145
 146 init(options => {
 147         "link-doc=s" => \$dh{LINK_DOC},
 148 });
 149
 150 foreach my $package (@{$dh{DOPACKAGES}}) {
 151         next if is_udeb($package);
 152
 153         my $tmp=tmpdir($package);
 154         my $file=pkgfile($package,"docs");
 155         my $link_doc=($dh{LINK_DOC} && $dh{LINK_DOC} ne $package);
 156
 157         if ($link_doc) {
 158                 # Make sure that the parent directory exists.
 159                 if (! -d "$tmp/usr/share/doc" && ! -l "$tmp/usr/share/doc") {
 160                         doit("install","-g",0,"-o",0,"-d","$tmp/usr/share/doc");
 161                 }
 162                 # Create symlink to another documentation directory if
 163                 # necessary.
 164                 if (! -d "$tmp/usr/share/doc/$package" &&
 165                     ! -l "$tmp/usr/share/doc/$package") {
 166                         doit("ln", "-sf", $dh{LINK_DOC}, "$tmp/usr/share/doc/$package");
 167                         # Policy says that if you make your documentation
 168                         # directory a symlink, then you have to depend on
 169                         # the target.
 170                         addsubstvar($package, "misc:Depends", $dh{LINK_DOC});
 171                 }
 172         }
 173         else {
 174                 ensure_docdir($package);
 175         }
 176
 177         my @docs;
 178
 179         if ($file) {
 180                 @docs=filearray($file, ".");
 181         }
 182
 183         if (($package eq $dh{FIRSTPACKAGE} || ($dh{PARAMS_ALL} && ! $link_doc)) && @ARGV) {
 184                 push @docs, @ARGV;
 185         }
 186
 187         if (@docs) {
 188                 my $exclude = '';
 189                 if ($dh{EXCLUDE_FIND}) {
 190                         $exclude .= ' -and ! \( '.$dh{EXCLUDE_FIND}.' \)';
 191                 }
 192                 if (! compat(4)) {
 193                         # ignore empty files in subdirs
 194                         $exclude .= ' -and ! -empty';
 195                 }
 196                 foreach my $doc (@docs) {
 197                         next if excludefile($doc);
 198                         next if -e $doc && ! -s $doc && ! compat(4); # ignore empty files
 199                         ensure_docdir($package);
 200                         if (-d $doc && length $exclude) {
 201                                 my $basename = basename($doc);
 202                                 my $dir = ($basename eq '.') ? $doc : "$doc/..";
 203                                 my $pwd=`pwd`;
 204                                 chomp $pwd;
 205                                 complex_doit("cd '$dir' && find '$basename' \\( -type f -or -type l \\)$exclude -exec cp --parents -dp {} $pwd/$tmp/usr/share/doc/$package \\;");
 206                         }
 207                         else {
 208                                 doit("cp", "-a", $doc, "$tmp/usr/share/doc/$package");
 209                         }
 210                 }
 211                 doit("chown","-R","0:0","$tmp/usr/share/doc");
 212                 doit("chmod","-R","go=rX","$tmp/usr/share/doc");
 213                 doit("chmod","-R","u+rw","$tmp/usr/share/doc");
 214         }
 215
 216         # .Debian is correct, according to policy, but I'm easy.
 217         my $readme_debian=pkgfile($package,'README.Debian');
 218         if (! $readme_debian) {
 219                 $readme_debian=pkgfile($package,'README.debian');
 220         }
 221         if (! $link_doc && $readme_debian && ! excludefile($readme_debian)) {
 222                 ensure_docdir($package);
 223                 doit("install","-g",0,"-o",0,"-m","644","-p","$readme_debian",
 224                         "$tmp/usr/share/doc/$package/README.Debian");
 225         }
 226
 227         my $todo=pkgfile($package,'TODO');
 228         if (! $link_doc && $todo && ! excludefile($todo)) {
 229                 ensure_docdir($package);
 230                 if (isnative($package)) {
 231                         doit("install","-g",0,"-o",0,"-m","644","-p",$todo,
 232                                 "$tmp/usr/share/doc/$package/TODO");
 233                 }
 234                 else {
 235                         doit("install","-g",0,"-o",0,"-m","644","-p",$todo,
 236                                 "$tmp/usr/share/doc/$package/TODO.Debian");
 237                 }
 238         }
 239
 240         # If the "directory" is a dangling symlink, then don't install
 241         # the copyright file. This is useful for multibinary packages
 242         # that share a doc directory.
 243         if (! $link_doc && (! -l "$tmp/usr/share/doc/$package" || -d "$tmp/usr/share/doc/$package")) {
 244                 # Support debian/package.copyright, but if not present, fall
 245                 # back on debian/copyright for all packages, not just the
 246                 # main binary package.
 247                 my $copyright=pkgfile($package,'copyright');
 248                 if (! $copyright && -e "debian/copyright") {
 249                         $copyright="debian/copyright";
 250                 }
 251                 if ($copyright && ! excludefile($copyright)) {
 252                         ensure_docdir($package);
 253                         doit("install","-g",0,"-o",0,"-m","644","-p",$copyright,
 254                                 "$tmp/usr/share/doc/$package/copyright");
 255                 }
 256         }
 257
 258         # Handle doc-base files. There are two filename formats, the usual
 259         # plus an extended format (debian/package.*).
 260         my %doc_ids;
 261
 262         opendir(DEB,"debian/") || error("can't read debian directory: $!");
 263         # If this is the main package, we need to handle unprefixed filenames.
 264         # For all packages, we must support both the usual filename format plus
 265         # that format with a period an something appended.
 266         my $regexp="\Q$package\E\.";
 267         if ($package eq $dh{MAINPACKAGE}) {
 268                 $regexp="(|$regexp)";
 269         }
 270         foreach my $fn (grep {/^${regexp}doc-base(\..*)?$/} readdir(DEB)) {
 271                 # .EX are example files, generated by eg, dh-make
 272                 next if $fn=~/\.EX$/;
 273                 next if excludefile($fn);
 274                 # Parse the file to get the doc id.
 275                 open (IN, "debian/$fn") || die "Cannot read debian/$fn.";
 276                 while (<IN>) {
 277                         s/\s*$//;
 278                         if (/^Document\s*:\s*(.*)/) {
 279                                 $doc_ids{$fn}=$1;
 280                                 last;
 281                         }
 282                 }
 283                 if (! exists $doc_ids{$fn}) {
 284                         warning("Could not parse $fn for doc-base Document id; skipping");
 285                 }
 286                 close IN;
 287         }
 288         closedir(DEB);
 289
 290         if (%doc_ids) {
 291                 if (! -d "$tmp/usr/share/doc-base/") {
 292                         doit("install","-g",0,"-o",0,"-d","$tmp/usr/share/doc-base/");
 293                 }
 294         }
 295         foreach my $fn (keys %doc_ids) {
 296                 doit("install","-g",0,"-o",0,"-m644","-p","debian/$fn",
 297                      "$tmp/usr/share/doc-base/$doc_ids{$fn}");
 298         }
 299 }
 300
 301 =head1 SEE ALSO
 302
 303 L<debhelper(7)>
 304
 305 This program is a part of debhelper.
 306
 307 =head1 AUTHOR
 308
 309 Joey Hess <joeyh@debian.org>
 310
 311 =cut