Bug#659044: debhelper: dh_installdocs --link-doc needs preinst changes for working upgrades

Package: debhelper
Version: 8.0.0
Severity: wishlist
Tags: patch

Hi folks,

I just converted a patch to use dh_installdocs --link-doc to store the
documentation in just one of my binary packages instead of duplicating
them in multiple packages.

However, it turns out that when you do this for an existing package,
dpkg is not smart enough to handle the upgrade correctly. This means
that, if you upgrade from a version without the link to a version with
the link, the symlink does not get created, but instead you just get an
empty documentation directory.

Apparently supporting upgrades in this case needs a preinst script that
removes the (then-empty) old documentation directory, so dpkg can unpack
the symlink in its place.

At the very least, this requirement should be documented in the
dh_installdocs manpage (especially since dpkg is silent about this).

Ideally, however, dh_installdocs should allow automatically create this
preinst hook, to make this work. I've created a patch against debhelper
git master implementing this, which I've included below. I'm not sure if
the actual hook used is the best one (is silently creating a
.dpkg-backup directory a good idea?), perhaps some one can comment.
Also, the --upgrade-link-doc option might not be the best name, not
sure.

See also these bugreports for the dpkg side of this:

- http://bugs.debian.org/cgi-bin/bugr...i?bugb6203
- http://bugs.debian.org/316935
- http://bugs.debian.org/406715
- http://bugs.debian.org/182747

However, it does not seem likely to me that this will (can) be fixed in
dpkg...

Gr.

Matthijs


Here's the patch:

Subject: [PATCH] add dh_installdocs --upgrade-link-doc option


dh_installdocs | 21 +++++++++++++++++++++
1 files changed, 21 insertions(+), 0 deletions(-)

diff --git a/dh_installdocs b/dh_installdocs
index 104b796..8c59868 100755
a/dh_installdocs
+++ b/dh_installdocs
@@ -91,10 +91,26 @@ 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.

+If there are previous versions of the linking packages that did not
+contain the link, you should also pass B<--upgrade-link-doc> as well to
+make upgrades work properly.
+
(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>.)

+=item B<--upgrade-link-doc=>I<version>
+
+In addition to creating a link for the documentation directory, also
+generate a preinst script that removes the old directory (making a
+backup if it is not empty) on upgrades. This makes sure that dpkg can
+actually create the symlink (it will silently ignore the symlink if a
+directory already exists).
+
+The version number passed is the first version package version that
+contains the symlink. The preinst script will run for upgrades from any
+versions before this one.
+
=item I<file> ...

Install these files as documentation into the first package acted on. (Or
@@ -151,6 +167,7 @@ sub ensure_docdir {

init(options => {
"link-doc=s" => \$dh{LINK_DOC},
+ "upgrade-link-doc=s" => \$dh{UPGRADE_LINK_DOC},
});

foreach my $package (@{$dh{DOPACKAGES}}) {
@@ -175,6 +192,10 @@ foreach my $package (@{$dh{DOPACKAGES}}) {
# the target.
addsubstvar($package, "misc:Depends", $dh{LINK_DOC});
}
+
+ if ($dh{UPGRADE_LINK_DOC}) {
+ autoscript($package,"preinst","preinst-rmdocdir","s!#PACKAGE#!$package!g;s!#VERSION#!$dh{UPGRADE_LINK_DOC}!g");
+ }
}
else {
ensure_docdir($package);
1.7.7.3



To UNSUBSCRIBE, email to debian-bugs-dist-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org