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