[debhelper-devel] [debhelper] 01/01: c11: Auto-detect main pkg for doc pkgs (§12.3)
Niels Thykier
nthykier at moszumanska.debian.org
Thu Aug 31 19:34:33 UTC 2017
This is an automated email from the git hooks/post-receive script.
nthykier pushed a commit to branch master
in repository debhelper.
commit dcf44506a11132d376119384318b4b6250a17d94
Author: Niels Thykier <niels at thykier.net>
Date: Thu Aug 31 19:33:40 2017 +0000
c11: Auto-detect main pkg for doc pkgs (§12.3)
Signed-off-by: Niels Thykier <niels at thykier.net>
---
debhelper.pod | 16 ++++++++++++++++
debian/changelog | 5 +++++
dh_installdocs | 40 +++++++++++++++++++++++++++++++++++++---
dh_installexamples | 37 +++++++++++++++++++++++++++++++++----
lib/Debian/Debhelper/Dh_Lib.pm | 24 ++++++++++++++++++++++++
5 files changed, 115 insertions(+), 7 deletions(-)
diff --git a/debhelper.pod b/debhelper.pod
index e41453c..7ec88bb 100644
--- a/debhelper.pod
+++ b/debhelper.pod
@@ -1,3 +1,5 @@
+=encoding UTF-8
+
=head1 NAME
debhelper - the debhelper tool suite
@@ -706,6 +708,20 @@ command and fail with a "command not found" error.
The B<dh_makeshlibs> helper will now exit with an error if objdump
returns failure code from analysing objdump.
+=item -
+
+The B<dh_installdocs> and B<dh_installexamples> tools will now
+attempt to guess the "main package" for a given documentation
+package (e.g. I<pkg-doc> will have I<pkg> as main package).
+
+When a main package is detected, I<most> documentation will be
+installed into F<< /usr/share/doc/I<main-pkg> >> as recommended
+by Debian policy §12.3 since 3.9.7. Notably exceptions include
+the copyright file and the changelog file.
+
+The B<--doc-main-package> option can be used when the auto-detection
+is insufficient.
+
=back
=back
diff --git a/debian/changelog b/debian/changelog
index bc657a7..48e2f4d 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -36,6 +36,11 @@ debhelper (10.7.3) UNRELEASED; urgency=medium
* dh_strip: Disable parallelism when --dbg-package is used as it
causes non-deterministic failures in some cases. Thanks to
Helmut Grohne for reporting the issue. (Closes: #872007)
+ * dh_installdocs: Auto-detect "main package" for documentation
+ packages in compat 11 to assist with Debian policy §12.3. This
+ auto-detection can be overrules with the new --doc-main-package.
+ (Closes: #824221)
+ * dh_installexamples: Ditto.
[ Adam Conrad ]
* dh_gencontrol: Change the synopsis of dbgsym packages so it
diff --git a/dh_installdocs b/dh_installdocs
index 06da53b..273b29d 100755
--- a/dh_installdocs
+++ b/dh_installdocs
@@ -1,5 +1,7 @@
#!/usr/bin/perl
+=encoding UTF-8
+
=head1 NAME
dh_installdocs - install documentation into package build directories
@@ -95,6 +97,26 @@ acted on.
Exclude files that contain I<item> anywhere in their filename from
being installed. Note that this includes doc-base files.
+=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 (notably, the copyright
+file and the package changelog) 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
@@ -182,6 +204,7 @@ sub ensure_docdir {
init(options => {
"link-doc=s" => \$dh{LINK_DOC},
"sourcedir=s" => \$dh{SOURCEDIR},
+ 'doc-main-package=s' => \$dh{DOC_MAIN_PACKAGE},
});
my $called_getpackages = 0;
@@ -191,6 +214,10 @@ my $nodocs = is_build_profile_active('nodoc') || get_buildoption('nodoc') ? 1 :
# 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>');
+}
+
foreach my $package (getpackages()) {
next if is_udeb($package);
@@ -248,9 +275,17 @@ foreach my $package (getpackages()) {
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;
+ }
if ($dh{EXCLUDE_FIND}) {
$exclude .= ' -and ! \( '.$dh{EXCLUDE_FIND}.' \)';
}
+ my $target_dir = "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
@@ -260,14 +295,13 @@ foreach my $package (getpackages()) {
my $dir = ($basename eq '.') ? $doc : "$doc/..";
my $pwd=`pwd`;
chomp $pwd;
- my $docdir = "$pwd/$tmp/usr/share/doc/$package";
+ my $docdir = "${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,
- "$tmp/usr/share/doc/$package");
+ doit("cp", '--reflink=auto', "-a", $doc, "${tmp}/${target_dir}");
}
}
doit("chown","-R","0:0","$tmp/usr/share/doc");
diff --git a/dh_installexamples b/dh_installexamples
index 3b3d50b..ac8b6f5 100755
--- a/dh_installexamples
+++ b/dh_installexamples
@@ -1,5 +1,7 @@
#!/usr/bin/perl
+=encoding UTF-8
+
=head1 NAME
dh_installexamples - install example files into package build directories
@@ -51,6 +53,23 @@ by the B<dh_auto_>I<*> commands. You rarely need to use this option, since
B<dh_installexamples> 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_installexamples> 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.
+
=item B<-X>I<item>, B<--exclude=>I<item>
Exclude files that contain I<item> anywhere in their filename from
@@ -73,6 +92,7 @@ directory, it will install the complete contents of the directory.
init(options => {
"sourcedir=s" => \$dh{SOURCEDIR},
+ 'doc-main-package=s' => \$dh{DOC_MAIN_PACKAGE},
});
# PROMISE: DH NOOP WITHOUT pkgfile-logged(examples)
@@ -84,6 +104,10 @@ my $nodocs = is_build_profile_active('nodoc') || get_buildoption('nodoc') ? 1 :
# 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>');
+}
+
foreach my $package (getpackages()) {
next if is_udeb($package);
@@ -109,7 +133,13 @@ foreach my $package (getpackages()) {
next if $skip_install or $nodocs;
if (@examples) {
- install_dir("$tmp/usr/share/doc/$package/examples");
+ 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;
+ }
+ my $target_dir = "usr/share/doc/${target_package}/examples";
+ install_dir($target_dir);
my $exclude = '';
if ($dh{EXCLUDE_FIND}) {
@@ -124,11 +154,10 @@ foreach my $package (getpackages()) {
chomp($pwd=`pwd`) if not defined($pwd);
complex_doit("cd '$dir' && " .
"find '$basename' -type f$exclude -print0 | LC_ALL=C sort -z | " .
- "xargs -0 -I {} cp --reflink=auto --parents -dp {} $pwd/$tmp/usr/share/doc/$package/examples");
+ "xargs -0 -I {} cp --reflink=auto --parents -dp {} ${pwd}/${target_dir}");
}
else {
- doit("cp", '--reflink=auto', "-a", $example,
- "$tmp/usr/share/doc/$package/examples");
+ doit("cp", '--reflink=auto', "-a", $example, "${tmp}/${target_dir}");
}
}
}
diff --git a/lib/Debian/Debhelper/Dh_Lib.pm b/lib/Debian/Debhelper/Dh_Lib.pm
index 85654f1..e840b9d 100644
--- a/lib/Debian/Debhelper/Dh_Lib.pm
+++ b/lib/Debian/Debhelper/Dh_Lib.pm
@@ -64,6 +64,7 @@ our (@EXPORT, %dh);
&glob_expand_error_handler_warn_and_discard &glob_expand
&glob_expand_error_handler_silently_ignore DH_BUILTIN_VERSION
&print_and_complex_doit &default_sourcedir &qx_cmd
+ &compute_doc_main_package
);
# The Makefile changes this if debhelper is installed in a PREFIX.
@@ -1989,5 +1990,28 @@ sub on_items_in_parallel {
*on_selected_pkgs_in_parallel = \&on_items_in_parallel;
+sub compute_doc_main_package {
+ my ($doc_package) = @_;
+ # if explicitly set, then choose that.
+ return $dh{DOC_MAIN_PACKAGE} if $dh{DOC_MAIN_PACKAGE};
+ # In compat 10 (and earlier), there is no auto-detection
+ return $doc_package if compat(10);
+ my $target_package = $doc_package;
+ # If it is not a -doc package, then docs should be installed
+ # under its own package name.
+ return $doc_package if $target_package !~ s/-doc$//;
+ # FOO-doc hosts the docs for FOO; seems reasonable
+ return $target_package if exists($package_types{$target_package});
+ if ($doc_package =~ m/^lib./) {
+ # Special case, "libFOO-doc" can host docs for "libFOO-dev"
+ my $lib_dev = "${target_package}-dev";
+ return $lib_dev if exists($package_types{$lib_dev});
+ # Technically, we could go look for a libFOO<something>-dev,
+ # but atm. it is presumed to be that much of a corner case
+ # that it warrents an override.
+ }
+ # We do not know; make that clear to the caller
+ return;
+}
1
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debhelper/debhelper.git
More information about the debhelper-devel
mailing list