diff options
Diffstat (limited to 'dh_installdocs')
| -rwxr-xr-x | dh_installdocs | 447 |
1 files changed, 447 insertions, 0 deletions
diff --git a/dh_installdocs b/dh_installdocs new file mode 100755 index 0000000..2e4529d --- /dev/null +++ b/dh_installdocs @@ -0,0 +1,447 @@ +#!/usr/bin/perl + +=encoding UTF-8 + +=head1 NAME + +dh_installdocs - install documentation into package build directories + +=cut + +use strict; +use warnings; +use Debian::Debhelper::Dh_Lib; + +our $VERSION = DH_BUILTIN_VERSION; + +=head1 SYNOPSIS + +B<dh_installdocs> [S<I<debhelper options>>] [B<-A>] [B<-X>I<item>] [S<I<file> ...>] + +=head1 DESCRIPTION + +B<dh_installdocs> is a debhelper program that is responsible for installing +documentation into F<usr/share/doc/package> in package build directories. + +In compat 10 and earlier, L<dh_install(1)> may be a better tool for handling +the upstream documentation, when upstream's own build system installs all the desired documentation +correctly. In this case, B<dh_installdocs> is still useful for installing +packaging related documentation (e.g. the F<debian/copyright> file). + +From debhelper compatibility level 11 on, B<dh_install> will fall back to +looking in F<debian/tmp> for files, if it does not find them in the current +directory (or wherever you've told it to look using B<--sourcedir>). + +In compat 11 and later, B<dh_installdocs> offers many of the features that +L<dh_install(1)> also has. Furthermore, B<dh_installdocs> also supports +the B<nodoc> build profile to exclude documentation (regardless of compat +level). + +=head1 FILES + +=over 4 + +=item debian/I<package>.docs + +List documentation files to be installed into I<package>. + +Supports substitution variables in compat 13 and later as +documented in L<debhelper(7)>. + +=item F<debian/copyright> + +The copyright file is installed into all packages, unless a more +specific copyright file is available. + +=item debian/I<package>.copyright + +=item debian/I<package>.README.Debian + +=item debian/I<package>.TODO + +Each of these files is automatically installed if present for a +I<package>. + +=item F<debian/README.Debian> + +=item F<debian/TODO> + +These files are installed into the first binary package listed in +debian/control. + +Note that F<README.debian> files are also installed as F<README.Debian>, +and F<TODO> files will be installed as F<TODO.Debian> in non-native packages. + +=item debian/I<package>.doc-base + +Installed as doc-base control files. Note that the doc-id will be +determined from the B<Document:> entry in the doc-base control file in +question. In the event that multiple doc-base files in a single source +package share the same doc-id, they will be installed to +usr/share/doc-base/package instead of usr/share/doc-base/doc-id. + +=item debian/I<package>.doc-base.* + +If your package needs to register more than one document, you need +multiple doc-base files, and can name them like this. In the event +that multiple doc-base files of this style in a single source package +share the same doc-id, they will be installed to +usr/share/doc-base/package-* instead of usr/share/doc-base/doc-id. + +Please be aware that this deduplication is currently done in memory +only, so for now it requires B<dh_installdocs> to be called no more +than once during the package build. Calling B<dh_installdocs +-p>I<package> in combination with using +F<debian/>I<package>F<.doc-base.*> files can lead to uninstallable +packages. See L<https://bugs.debian.org/980903> for details. + +=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<item>, B<--exclude=>I<item> + +Exclude files that contain I<item> anywhere in their filename from +being installed. Note that this includes doc-base files. + +=item B<--sourcedir=>I<dir> + +Look in the specified directory for files to be installed. This option +requires compat 11 or later (it is silently ignored in compat 10 or earlier). + +Note that this is not the same as the B<--sourcedirectory> option used +by the B<dh_auto_>I<*> commands. You rarely need to use this option, since +B<dh_installman> automatically looks for files in F<debian/tmp> in debhelper +compatibility level 11 and above. + +=item B<--doc-main-package=>I<main-package> + +Set the main package for a documentation package. This is used to +install the documentation of the documentation package in F<< +/usr/share/doc/I<main-package> >> as recommended by the Debian policy +manual 3.9.7 in ยง12.3. + +In compat 11 (or later), this option is only useful if debhelper's +auto-detection of the main package is wrong. The option can also be +used to silence a warning from debhelper when the auto-detection fails +but the default happens to be correct. + +This option cannot be used when B<dh_installdocs> is instructed to act +on multiple packages. If you need this option, you will generally +need to combine it with B<-p> to ensure exactly one package is acted +on. + +Please keep in mind that some documentation (the copyright file, +README.Debian, etc.) will be unaffected by this option. + +=item B<--link-doc=>I<package> + +Make the documentation directory of all packages acted on be a symlink to +the documentation directory of I<package>. This has no effect when acting on +I<package> itself, or if the documentation directory to be created already +exists when B<dh_installdocs> is run. To comply with policy, I<package> 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<copyright>, F<changelog>, F<README.Debian>, and F<TODO> 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<dh_installdocs>.) + +Please note that this option only applies to the documentation +directory for the package itself. When the package ships +documentation for another package (e.g. see B<--doc-main-package>), it +will not use a symlink for the documentation of the other package. + + +B<CAVEAT 1>: If a previous version of the package was built without this +option and is now built with it (or vice-versa), it requires a "dir to +symlink" (or "symlink to dir") migration. Since debhelper has no +knowledge of previous versions, you have to enable this migration +itself. + +This can be done by providing a "debian/I<package>.maintscript" file +and using L<dh_installdeb(1)> to provide the relevant maintainer +script snippets. + +B<CAVEAT 2>: The use of B<--link-doc> should only be done when the +packages have same "architecture" type. A link from an architecture +independent package to an architecture dependent package (or vice +versa) will not work. Since compat 10, debhelper will actively reject +unsupported combinations. + +=item I<file> ... + +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<debian/package.docs> file: + + README + TODO + debian/notes-for-maintainers.txt + docs/manual.txt + docs/manual.pdf + docs/manual-html/ + +=head1 NOTES + +Note that B<dh_installdocs> will happily copy entire directory hierarchies if +you ask it to (similar to B<cp -a>). If it is asked to install a +directory, it will install the complete contents of the directory. + +=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 $target && ! -l $target) { + install_dir($target); + } + $docdir_created{$package}=1; +} + +init(options => { + "link-doc=s" => \$dh{LINK_DOC}, + "sourcedir=s" => \$dh{SOURCEDIR}, + 'doc-main-package=s' => \$dh{DOC_MAIN_PACKAGE}, +}); + +my $called_getpackages = 0; +my $default_error_handler = compat(10) ? \&glob_expand_error_handler_reject_nomagic_warn_discard : \&glob_expand_error_handler_reject; +my $nodocs = is_build_profile_active('nodoc') || get_buildoption('nodoc') ? 1 : 0; +# We cannot assume documentation is built under nodoc, but if it is we must flag it as handled +# or dh_missing might make noise. +$default_error_handler = \&glob_expand_error_handler_silently_ignore if $nodocs; + +if (@{$dh{DOPACKAGES}} > 1 and $dh{DOC_MAIN_PACKAGE}) { + error('--doc-main-package should be used with -p<doc-pkg>'); +} + +if ($dh{DOC_MAIN_PACKAGE}) { + assert_opt_is_known_package($dh{DOC_MAIN_PACKAGE}, '--doc-main-package'); +} + +foreach my $package (getpackages()) { + 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); + my $skip_install = process_pkg($package) ? 0 : 1; + my @search_dirs = ('.'); + my $error_handler = $skip_install ? \&glob_expand_error_handler_silently_ignore : $default_error_handler; + @search_dirs = ($dh{SOURCEDIR} // '.', default_sourcedir($package)) if not compat(10); + + if (not $skip_install) { + if ($link_doc) { + getpackages('both') unless $called_getpackages++; + + if (package_binary_arch($package) ne package_binary_arch($dh{LINK_DOC})) { + if (compat(9)) { + warning("WARNING: --link-doc between architecture all and not all packages breaks binNMUs"); + } else { + error("--link-doc not allowed between ${package} and $dh{LINK_DOC} (one is arch:all and the other not)"); + } + } + # Make sure that the parent directory exists. + if (!-d "$tmp/usr/share/doc" && !-l "$tmp/usr/share/doc") { + install_dir("$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") { + make_symlink_raw_target($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} (= \${binary:Version})"); + } + } else { + ensure_docdir($package); + } + } + + my @docs; + + if ($file) { + @docs = filearray($file, \@search_dirs, $error_handler); + } + + if (($package eq $dh{FIRSTPACKAGE} || ($dh{PARAMS_ALL} && !$link_doc)) && @ARGV) { + push @docs, @ARGV; + } + + log_installed_files($package, @docs); + + next if $skip_install; + + if (not $nodocs and @docs) { + my $exclude = ' -and ! -empty'; + my $target_package = compute_doc_main_package($package); + if (not defined($target_package)) { + warning("Cannot auto-detect main package for ${package}. If the default is wrong, please use --doc-main-package"); + $target_package = $package; + } elsif ($dh{PARAMS_ALL} and $package ne $target_package and not $dh{DOC_MAIN_PACKAGE}) { + warning("Not using auto-detected $target_package as main doc package for $package: With -A/--all, this would cause file-conflicts."); + $target_package = $package; + } + if ($dh{EXCLUDE_FIND}) { + $exclude .= ' -and ! \( '.$dh{EXCLUDE_FIND}.' \)'; + } + my $target_dir = "${tmp}/usr/share/doc/${target_package}"; + install_dir($target_dir) unless -l $target_dir; + + foreach my $doc (@docs) { + next if excludefile($doc); + next if -f $doc && ! -s _; # 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; + # Gracefully handling tmpdir being absolute (-P/...) + my $docdir = $target_dir =~ m{^/} ? $target_dir : "${pwd}/${target_dir}"; + complex_doit("cd '$dir' && " . + "find '$basename' \\( -type f -or -type l \\)$exclude -print0 | LC_ALL=C sort -z | " . + "xargs -0 -I {} cp --reflink=auto --parents -dp {} $docdir"); + } + else { + doit("cp", '--reflink=auto', "-a", $doc, $target_dir); + } + } + doit("chown","-R","0:0","$tmp/usr/share/doc") if should_use_root(); + doit("chmod","-R","u+rw,go=rX","$tmp/usr/share/doc"); + } + + # .Debian is correct, according to policy, but I'm easy. + my $readme_debian=pkgfile($package,'README.Debian'); + if (! $readme_debian) { + $readme_debian=pkgfile($package,'README.debian'); + } + if (! $link_doc && $readme_debian && ! excludefile($readme_debian)) { + ensure_docdir($package); + install_file($readme_debian, + "$tmp/usr/share/doc/$package/README.Debian"); + } + + my $todo=pkgfile($package,'TODO'); + if (! $link_doc && $todo && ! excludefile($todo)) { + ensure_docdir($package); + if (isnative($package)) { + install_file($todo, "$tmp/usr/share/doc/$package/TODO"); + } + else { + install_file($todo, + "$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 (! $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. + my $copyright=pkgfile($package,'copyright'); + if (! $copyright && -e "debian/copyright") { + $copyright="debian/copyright"; + } + if ($copyright && ! excludefile($copyright)) { + ensure_docdir($package); + install_file($copyright, + "$tmp/usr/share/doc/$package/copyright"); + } + } + + next if $nodocs; + + # Handle doc-base files. There are two filename formats, the usual + # plus an extended format (debian/package.*). + my %doc_ids; + + opendir(DEB,"debian/") || error("can't read debian directory: $!"); + # 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}) { + $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(my $fd, '<', "debian/$fn") || die "Cannot read debian/$fn."; + while (<$fd>) { + 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($fd); + } + closedir(DEB); + + if (%doc_ids) { + install_dir("$tmp/usr/share/doc-base/"); + } + foreach my $fn (keys %doc_ids) { + # To avoid issues with duplicated document IDs, we will always + # install to usr/share/doc-base/<packagename>.<doc_id> instead + # of just usr/share/doc-base/<packagename> or just + # usr/share/doc-base/<doc_id>. See #525821 and #980903. + install_file("debian/$fn", + "$tmp/usr/share/doc-base/$package.$doc_ids{$fn}"); + } +} + +=head1 SEE ALSO + +L<debhelper(7)> + +This program is a part of debhelper. + +=head1 AUTHOR + +Joey Hess <joeyh@debian.org> + +=cut |