X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=dh_installdocs;h=104b796ea460a44701639cad9cf696a4d2255633;hb=18a0da8092ea9f3dc48bca92b36f592af25a608d;hp=7af380947bd1a27853ea870896b286052c3dca76;hpb=307194e33ae1856238c94a07818d9dfd4712f52f;p=debhelper.git diff --git a/dh_installdocs b/dh_installdocs index 7af3809..104b796 100755 --- a/dh_installdocs +++ b/dh_installdocs @@ -1,89 +1,266 @@ #!/usr/bin/perl -w -# -# Reads debian/docs, installs all files listed there into -# /usr/share/doc/$PACKAGE -# Also installs the debian/copyright and debian/README.debian and debian/TODO -# and handles debian/doc-base. +=head1 NAME + +dh_installdocs - install documentation into package build directories + +=cut + +use strict; use Debian::Debhelper::Dh_Lib; -init(); -foreach $PACKAGE (@{$dh{DOPACKAGES}}) { - $TMP=tmpdir($PACKAGE); - $file=pkgfile($PACKAGE,"docs"); +=head1 SYNOPSIS + +B [S>] [B<-A>] [B<-X>I] [S ...>] + +=head1 DESCRIPTION + +B is a debhelper program that is responsible for installing +documentation into F in package build directories. + +=head1 FILES + +=over 4 + +=item debian/I.docs + +List documentation files to be installed into I. + +=item F + +The copyright file is installed into all packages, unless a more +specific copyright file is available. + +=item debian/I.copyright + +=item debian/I.README.Debian + +=item debian/I.TODO + +Each of these files is automatically installed if present for a +I. + +=item F + +=item F + +These files are installed into the first binary package listed in +debian/control. + +Note that F files are also installed as F, +and F files will be installed as F in non-native packages. + +=item debian/I.doc-base + +Installed as doc-base control files. Note that the doc-id will be +determined from the B entry in the doc-base control file in +question. + +=item debian/I.doc-base.* + +If your package needs to register more than one document, you need multiple +doc-base files, and can name them like this. + +=back + +=head1 OPTIONS + +=over 4 + +=item B<-A>, B<--all> + +Install all files specified by command line parameters in ALL packages +acted on. + +=item B<-X>I, B<--exclude=>I + +Exclude files that contain I anywhere in their filename from +being installed. Note that this includes doc-base files. + +=item B<--link-doc=>I + +Make the documentation directory of all packages acted on be a symlink to +the documentation directory of I. This has no effect when acting on +I itself, or if the documentation directory to be created already +exists when B is run. To comply with policy, I must +be a binary package that comes from the same source package. + +debhelper will try to avoid installing files into linked documentation +directories that would cause conflicts with the linked package. The B<-A> +option will have no effect on packages with linked documentation +directories, and F, F, F, and F files will +not be installed. + +(An older method to accomplish the same thing, which is still supported, +is to make the documentation directory of a package be a dangling symlink, +before calling B.) + +=item I ... + +Install these files as documentation into the first package acted on. (Or +in all packages if B<-A> is specified). + +=back + +=head1 EXAMPLES + +This is an example of a F file: + + README + TODO + debian/notes-for-maintainers.txt + docs/manual.txt + docs/manual.pdf + docs/manual-html/ + +=head1 NOTES + +Note that B will happily copy entire directory hierarchies if +you ask it to (similar to B). If it is asked to install a +directory, it will install the complete contents of the directory. + +Note that this command is not idempotent. L should be called +between invocations of this command. Otherwise, it may cause multiple +instances of the same text to be added to maintainer scripts. + +=cut + +my %docdir_created; +# Create documentation directories on demand. This allows us to use dangling +# symlinks for linked documentation directories unless additional files need +# to be installed. +sub ensure_docdir { + my $package=shift; + return if $docdir_created{$package}; + my $tmp=tmpdir($package); + + my $target; + if ($dh{LINK_DOC} && $dh{LINK_DOC} ne $package) { + $target="$tmp/usr/share/doc/$dh{LINK_DOC}"; + } + else { + $target="$tmp/usr/share/doc/$package"; + } # If this is a symlink, leave it alone. - if ( ! -d "$TMP/usr/share/doc/$PACKAGE" && - ! -l "$TMP/usr/share/doc/$PACKAGE") { - doit("install","-g",0,"-o",0,"-d","$TMP/usr/share/doc/$PACKAGE"); + if (! -d $target && ! -l $target) { + doit("install","-g",0,"-o",0,"-d",$target); + } + $docdir_created{$package}=1; +} + +init(options => { + "link-doc=s" => \$dh{LINK_DOC}, +}); + +foreach my $package (@{$dh{DOPACKAGES}}) { + next if is_udeb($package); + + my $tmp=tmpdir($package); + my $file=pkgfile($package,"docs"); + my $link_doc=($dh{LINK_DOC} && $dh{LINK_DOC} ne $package); + + if ($link_doc) { + # Make sure that the parent directory exists. + if (! -d "$tmp/usr/share/doc" && ! -l "$tmp/usr/share/doc") { + doit("install","-g",0,"-o",0,"-d","$tmp/usr/share/doc"); + } + # Create symlink to another documentation directory if + # necessary. + if (! -d "$tmp/usr/share/doc/$package" && + ! -l "$tmp/usr/share/doc/$package") { + doit("ln", "-sf", $dh{LINK_DOC}, "$tmp/usr/share/doc/$package"); + # Policy says that if you make your documentation + # directory a symlink, then you have to depend on + # the target. + addsubstvar($package, "misc:Depends", $dh{LINK_DOC}); + } + } + else { + ensure_docdir($package); } - undef @docs; + my @docs; if ($file) { - @docs=filearray($file); + @docs=filearray($file, "."); } - if (($PACKAGE eq $dh{FIRSTPACKAGE} || $dh{PARAMS_ALL}) && @ARGV) { + if (($package eq $dh{FIRSTPACKAGE} || ($dh{PARAMS_ALL} && ! $link_doc)) && @ARGV) { push @docs, @ARGV; } if (@docs) { - doit("cp", "-a",@docs,"$TMP/usr/share/doc/$PACKAGE/"); - doit("chown","-R","0.0","$TMP/usr/share/doc"); - doit("chmod","-R","go=rX","$TMP/usr/share/doc"); - doit("chmod","-R","u+rw","$TMP/usr/share/doc"); + my $exclude = ''; + if ($dh{EXCLUDE_FIND}) { + $exclude .= ' -and ! \( '.$dh{EXCLUDE_FIND}.' \)'; + } + if (! compat(4)) { + # ignore empty files in subdirs + $exclude .= ' -and ! -empty'; + } + foreach my $doc (@docs) { + next if excludefile($doc); + next if -e $doc && ! -s $doc && ! compat(4); # ignore empty files + ensure_docdir($package); + if (-d $doc && length $exclude) { + my $basename = basename($doc); + my $dir = ($basename eq '.') ? $doc : "$doc/.."; + my $pwd=`pwd`; + chomp $pwd; + complex_doit("cd '$dir' && find '$basename' \\( -type f -or -type l \\)$exclude -exec cp --parents -dp {} $pwd/$tmp/usr/share/doc/$package \\;"); + } + else { + doit("cp", "-a", $doc, "$tmp/usr/share/doc/$package"); + } + } + doit("chown","-R","0:0","$tmp/usr/share/doc"); + doit("chmod","-R","go=rX","$tmp/usr/share/doc"); + doit("chmod","-R","u+rw","$tmp/usr/share/doc"); } # .Debian is correct, according to policy, but I'm easy. - $readme_debian=pkgfile($PACKAGE,'README.Debian'); + my $readme_debian=pkgfile($package,'README.Debian'); if (! $readme_debian) { - $readme_debian=pkgfile($PACKAGE,'README.debian'); + $readme_debian=pkgfile($package,'README.debian'); } - if ($readme_debian) { + if (! $link_doc && $readme_debian && ! excludefile($readme_debian)) { + ensure_docdir($package); doit("install","-g",0,"-o",0,"-m","644","-p","$readme_debian", - "$TMP/usr/share/doc/$PACKAGE/README.Debian"); + "$tmp/usr/share/doc/$package/README.Debian"); } - $todo=pkgfile($PACKAGE,'TODO'); - if ($todo) { - if (isnative($PACKAGE)) { + my $todo=pkgfile($package,'TODO'); + if (! $link_doc && $todo && ! excludefile($todo)) { + ensure_docdir($package); + if (isnative($package)) { doit("install","-g",0,"-o",0,"-m","644","-p",$todo, - "$TMP/usr/share/doc/$PACKAGE/TODO"); + "$tmp/usr/share/doc/$package/TODO"); } else { doit("install","-g",0,"-o",0,"-m","644","-p",$todo, - "$TMP/usr/share/doc/$PACKAGE/TODO.Debian"); + "$tmp/usr/share/doc/$package/TODO.Debian"); } } # If the "directory" is a dangling symlink, then don't install # the copyright file. This is useful for multibinary packages # that share a doc directory. - if (-d "$TMP/usr/share/doc/$PACKAGE") { + if (! $link_doc && (! -l "$tmp/usr/share/doc/$package" || -d "$tmp/usr/share/doc/$package")) { # Support debian/package.copyright, but if not present, fall # back on debian/copyright for all packages, not just the # main binary package. - $copyright=pkgfile($PACKAGE,'copyright'); + my $copyright=pkgfile($package,'copyright'); if (! $copyright && -e "debian/copyright") { $copyright="debian/copyright"; } - if ($copyright) { - doit("install","-g",0,"-o",0,"-m","644","-p",$copyright, - "$TMP/usr/share/doc/$PACKAGE/copyright"); + if ($copyright && ! excludefile($copyright)) { + ensure_docdir($package); + doit("install","-g",0,"-o",0,"-m","644","-p",$copyright, + "$tmp/usr/share/doc/$package/copyright"); } } - # Add in the /usr/doc compatability symlinks code. - if (! $dh{NOSCRIPTS}) { - autoscript($PACKAGE,"postinst","postinst-doc", - "s/#PACKAGE#/$PACKAGE/g", - ); - autoscript($PACKAGE,"prerm","prerm-doc", - "s/#PACKAGE#/$PACKAGE/g", - ); - } - # Handle doc-base files. There are two filename formats, the usual # plus an extended format (debian/package.*). my %doc_ids; @@ -92,38 +269,49 @@ foreach $PACKAGE (@{$dh{DOPACKAGES}}) { # If this is the main package, we need to handle unprefixed filenames. # For all packages, we must support both the usual filename format plus # that format with a period an something appended. - my $regexp="\Q$PACKAGE\E\."; - if ($PACKAGE eq $dh{MAINPACKAGE}) { + my $regexp="\Q$package\E\."; + if ($package eq $dh{MAINPACKAGE}) { $regexp="(|$regexp)"; } foreach my $fn (grep {/^${regexp}doc-base(\..*)?$/} readdir(DEB)) { + # .EX are example files, generated by eg, dh-make + next if $fn=~/\.EX$/; + next if excludefile($fn); # Parse the file to get the doc id. open (IN, "debian/$fn") || die "Cannot read debian/$fn."; while () { - if (/^Document:\s+(.*)(\s+)?/) { + s/\s*$//; + if (/^Document\s*:\s*(.*)/) { $doc_ids{$fn}=$1; last; } } + if (! exists $doc_ids{$fn}) { + warning("Could not parse $fn for doc-base Document id; skipping"); + } close IN; } closedir(DEB); if (%doc_ids) { - if (! -d "$TMP/usr/share/doc-base/") { - doit("install","-g",0,"-o",0,"-d","$TMP/usr/share/doc-base/"); + if (! -d "$tmp/usr/share/doc-base/") { + doit("install","-g",0,"-o",0,"-d","$tmp/usr/share/doc-base/"); } } foreach my $fn (keys %doc_ids) { doit("install","-g",0,"-o",0,"-m644","-p","debian/$fn", - "$TMP/usr/share/doc-base/$doc_ids{$fn}"); - if (! $dh{NOSCRIPTS}) { - autoscript($PACKAGE,"postinst","postinst-doc-base", - "s/#DOC-ID#/$doc_ids{$fn}/", - ); - autoscript($PACKAGE,"prerm","prerm-doc-base", - "s/#DOC-ID#/$doc_ids{$fn}/", - ); - } + "$tmp/usr/share/doc-base/$doc_ids{$fn}"); } } + +=head1 SEE ALSO + +L + +This program is a part of debhelper. + +=head1 AUTHOR + +Joey Hess + +=cut