[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Bug#42634: PROPOSAL] Automatic migration to /usr/share/doc

Ian proposes the following wrt /usr/doc vs /usr/share/doc:

> * Any dpkg bug in this area be fixed.  If I can figure out what people
> claim the bug is I'll fix it.  (I won't build an NMU, but we seem to
> have no shortage of people willing to do dpkg NMUs.)

The bug was explained to me in the second message attached below.

> * Existing packages which use /usr/share/doc, and all new packages
> which do so, should be made to contain a predepends on the base-files
> I mention below.
> 
> * Base-files should be changed.  The preinst should check to see if
> both exist, and:
>  - if they do and have different contents it could print a warning.
>  - if only /usr/doc exists it should be renamed to /usr/share/doc and
>    a symlink left behind
>  - if only /usr/doc exists but /usr/share is a different fs, it
>    should make the reverse symlink.

This is very similar to what I have proposed (which I have reincluded below
as the first attachment).  I was completely shot down, of course (the most
constructive comment was the example in the second attachment that
exercises the behaviour that I find unexpected in dpkg).

> The effect would be that people who installed preemptive packages from
> unstable would have both a /usr/share/doc and a /usr/doc until all the
> packages were migrated (or they moved them themselves); other people
> would get a nice transition if they had different filesystems, or
> could move it themselves if a mount point is involved.

I agree completely.  The only non-resolved issue (as usual) is downgrading...

Best,
	Kristoffer
-- 
Kristoffer Høgsbro Rose, phd, prof.associé  <http://www.ens-lyon.fr/~krisrose>
addr. LIP, Ecole Normale Supérieure de Lyon, 46 Allée d'Italie, F-69364 Lyon 7
phone +33(0)4 7272 8642, fax +33(0)4 7272 8080   <Kristoffer.Rose@ENS-Lyon.FR>
pgp f-p: A4D3 5BD7 3EC5 7CA2 924E D21D 126B B8E0   <krisrose@{debian,tug}.org>
--

debian-policy [PROPOSAL]: /usr/doc -> /usr/share/doc should be a symlink

I propose that the "transition" of /usr/doc to /usr/share/doc be done with
the following three changes to Policy:

1. REQUIRE that /usr/doc is a symlink to the FHS directory /usr/share/doc.

2. REQUIRE that packages

   - DO NOT create both /usr/doc/P and /usr/share/doc/P,
   - DO NOT depend on /usr/doc not being a symlink,

   and file critical bugs against packages violating any of these.

3. REQUIRE that packages

   - DO NOT use the path /usr/doc,
   - STORE their documentation in /usr/share/doc/P,

   and file normal bugs against packages violating any of these.

Change the base-files package in the following way:

A. Move all files in /usr/doc to /usr/share/doc.

B. Add /usr/sbin/fix-FHS-compliance (attached) and execute it in postinst:

As far as I can see everything will then work with the release-critical
parts being fixed and everything else migrating at its own pace.

Here are the advantages of this scheme:

* Completely transparent to users, packages, etc.

* Just one inode used.

* Potato will be FHS-compliant except for the non-authorized single symbolic
  link, and the upgrade path is trivial with the script above.

* dpkg is not bothered by a directory which is a symbolic link when it does
  not have to create it. (I already use the same idea locally for /usr/src
  and it works flawlessly: dpkg manages directories inside /usr/src without 
  any problems.)  Recall that

    $ ls -dl /usr/src
    lrwxrwxrwx  1 root    root        22 Jun 16  1998 /usr/src -> share/src
    $ test -d /usr/src && echo OK
    OK

  demonstrates that such a symbolic link is interpreted as a directory so
  scripts etc. should work as usual unless they explicitly test for a
  symbolic link (which is unlikely).

* Once no package depends on /usr/doc it can be quietly removed.

Best,
	Kristoffer

PS. The script is called fix-FHS-compliance because it could eventually
include more than just the /usr/doc issue.				--Kris
-- 
Kristoffer Høgsbro Rose, phd, prof.associé  <http://www.ens-lyon.fr/~krisrose>
addr. LIP, Ecole Normale Supérieure de Lyon, 46 Allée d'Italie, F-69364 Lyon 7
phone +33(0)4 7272 8642, fax +33(0)4 7272 8080   <Kristoffer.Rose@ENS-Lyon.FR>
pgp f-p: A4D3 5BD7 3EC5 7CA2 924E D21D 126B B8E0   <krisrose@{debian,tug}.org>
--

--iSloINJvAk
Content-Type: text/plain
Content-Description: fix-FHS-compliance
Content-Disposition: inline;
	filename="fix-FHS-compliance"
Content-Transfer-Encoding: 7bit

#!/bin/bash
#
# Debian FHS migration script.

# Currently only ensures that /usr/doc has migrated to /usr/share/doc.

echo -n "Checking that /usr/doc -> share/doc is in place..."

# Exit quietly if /usr/doc is already the right symbolic link.
cd /usr
if [ -L doc ]
then
  target="`ls -ld doc | sed -n 's/.* -> //p'`"
  if [ "$target" = "share/doc" ]; then
    echo "ok."
    exit
  fi
fi
# (The rest is only executed if we did not run already.)

# Check that /usr/share/doc exists.
if [ ! -d /usr/share/doc ]
then
  echo "failed."
  echo "Error: /usr/share/doc does not exist!  Please reinstall base-files."
  exit 1
fi

# Exit noisily if they are already identical (since the symlink is bad).
usrdocfiles=`ls -1 /usr/doc`
usrsharedocfiles=`ls -1 /usr/share/doc`
if [ "$usrdocfiles" = "$usrsharedocfiles" ]
   && diff -rq /usr/doc /usr/share/doc
then
  echo "ok."
  echo "Warning: /usr/doc and /usr/share/doc seem to be identical but"
  echo "         /usr/doc is not a relative symlink to share/doc."
  echo "         You should fix this."
  exit
fi

# We must migrate (or fail).
echo "no."
echo -n "Migrating /usr/doc -> share/doc..."

# Fail noisily if /usr/doc is a mount point.
if mount | fgrep -q ' /usr/doc '
then
  echo "failed."
  echo "Error: /usr/doc is a mount point! Please undo that and rerun"
  echo "       the /usr/sbin/fix-FHS-compliance script."
  exit 1
fi   


# Check that there are no duplicates between the directories.
dups=""
for d in $usrdocfiles
do
  dups="$dups"`expr " $usrsharedocfiles " : " $d "`
done
if [ -n "$dups" ]
then
  echo "failed."
  echo "Error: The following packages have files in both /usr/doc and
/usr/share/doc:"
  echo "       $dups"
  echo "       This should not happen and cannot be handled by this script."
  echo "       We propose you remove these buggy packages and rerun the"
  echo "       /usr/sbin/fix-FHS-compliance script."
  exit 1
fi

# We have a go for migration!  Copy /usr/doc/* to /usr/share/doc/*.
cd /usr/doc
for d in $usrdocfiles
do
  cp -a $d /usr/share/doc/$d
done

# Check that all data was correctly copied or fail.
cd /usr/doc
for d in $usrdocfiles
do
  if ! diff -rq $d /usr/share/doc/$d >/dev/null 2>&1
  then
    echo "failed."
    echo "Error: Could not copy /usr/doc/* to /usr/share/doc/*."
    echo -n "Cleaning up..."
    cd /usr/share/doc
    for d in $usrdocfiles
    do
      rm -fr $d
    done
    echo "done."
    exit 1
  fi
done

# Now remove the old /usr/doc directory and make the symlink.
cd /usr
rm -fr doc
if [ -d /usr/doc ]
then
  echo "failed."
  echo "Error: Could not remove /usr/doc!"
  echo "       Your system may be in a very bad state - sorry."
  exit 1
fi
ln -s share/doc doc
if [ ! -L doc ]
then
  echo "failed."
  echo "Error: Could not create symlink /usr/doc -> share/doc!"
  echo "       Your system may be in a very bad state - sorry."
  exit 1
fi

# We're done.
echo "done."
exit

--iSloINJvAk--
--- Begin Message --- 
On Tue, Aug 03, 1999 at 12:05:39PM +0200, Kristoffer.Rose@ENS-Lyon.FR wrote:
> I am happy to tell you that we agree completely on the behaviour of dpkg on 
> your example.  But you are ignoring a very important aspect of my proposal: 
> THIS ONLY HAPPENS FOR DIRECTORIES INTERNAL TO PACKAGES.  It happens because 
> olddir is actually REMOVED by the deinstallation.

This doesn't seem to be the case.

* Create three packages:
	test1 version 1.0 mimicing your average /usr/doc-using package
	test1 version 2.0 mimicing your average /usr/share/doc-using package
	test3 version 1.0 mimicing base-files

test1 1.0 has a file /my_usr/doc/test1/copyright,
          and depends on test3

test1 2.0 has a file /my_usr/share/doc/test1/copyright,
          and depends on test3

test3 1.0 has a file /my_usr/doc/copyright/GPL,
          and a file /my_usr/share/doc/test3/copyright

* dpkg --install test3_1.0_all.deb

* mv /my_usr/doc/copyright /my_usr/share/doc/
* rmdir /my_usr/doc
* ln -s /my_usr/share/doc /my_usr/doc

* dpkg --install test1_1.0_all.deb
* dpkg --install test1_2.0_all.deb

* ls -l /my_usr/doc/test1 -> empty
* ls -l /my_usr/share/doc/test1 -> empty
* dpkg -L test1 | grep my_usr/share/doc -> not empty

The packages are available as:

    http://www.debian.org/~ajt/test1_1.0_all.deb
    http://www.debian.org/~ajt/test1_2.0_all.deb
    http://www.debian.org/~ajt/test3_1.0_all.deb

Possibly I'm just misunderstanding what you're suggesting should be done
though. Can you give a sequence of commands that does whatever you're
suggesting, and still has those three packages survive unscathed?

Cheers,
aj

-- 
Anthony Towns <aj@humbug.org.au> <http://azure.humbug.org.au/~aj/>
I don't speak for anyone save myself. PGP encrypted mail preferred.

 ``The thing is: trying to be too generic is EVIL. It's stupid, it 
        results in slower code, and it results in more bugs.''
                                        -- Linus Torvalds

Attachment: pgp17h0OrTkGe.pgp
Description: PGP signature


--- End Message ---
Reply to: