dpkg/doc/diversions.text

(These messages have been edited to conform to the terminology
eventually decided on, and to make them give better and clearer
examples.)

------- start of digest (2 messages) (RFC 934 encapsulation) -------
Resent-Message-Id: <m0tcceI-0002c6C@chiark.chu.cam.ac.uk>
Resent-From: ijackson (Ian Jackson)
Resent-To: ian
From: ian@chiark.chu.cam.ac.uk (Ian Jackson)
To: Debian developers list <debian-devel@pixar.com>
Subject: `diverting' dpkg for a particular file
Date: Wed, 17 Jan 96 18:31 GMT

I'm almost finished with the implementation of a feature for dpkg that
will allow the sysadmin or package maintainer to prevent dpkg from
overwriting a particular file.

Instead, whenever dpkg finds a package containing that file it
`redirects' the reference to an alternative name.

Eg, if you were to `divert' /usr/sbin/smail to /usr/sbin/smail.real
then any package containing /usr/sbin/smail would have the file placed
as /usr/sbin/smail.real instead.  The feature will work during package
removal, as well.

There's provision for a single package to be named which is allowed to
provide a version of the file which will installed under the original
name.

This feature shouldn't be mixed with the conffiles update mechanism,
as this is unlikely to produce useful results and likely to produce
confusion on the part of the user at the very least and possibly on
the part of dpkg too :-).

No package should contain a file whose name is the diverted name of
another file; dpkg will spot this and balk if such a package is
installed when the diversion is in place, or if a diversion is set up
which involves overwriting an existing file whether managed by dpkg
or not (this latter check only happens if dpkg-divert is given the
--rename option which makes it actually rename any copy of the file
found in the filesystem).

Only one diversion for a particular file is allowed, and you can't
divert A to B and then B to C.

[...]

This feature is intended to be used sparingly; a system administrator
can use it to keep a locally-installed version of a piece of system
software that has to live in a particular place.

A package should preferably only use it if the package's main function
is to replace the file in question (whether or not the diverted - ie,
replaced, in this case - version of the file needs to be available);
otherwise a sysadmin might find that the feature wasn't available to
them when they wanted to install their own version of the file because
a package had already done so.

It's possible that I might introduce a facility that would allow
*requests* for redirection of files to be redirected themselves, by
using a special 2nd-level redirection option.

Ian.
------------------------------
To: debian-devel@Pixar.com
Subject: Re: `overriding' dpkg for a particular file

[...]
Forgive me for being perhaps rather baseic, but here are two examples,
diagrammatically:

1. Administrator wants to replace a Debian-provided program with
   their own version, or wants to put a wrapper around it:
                                            ____________________
     smail.deb___________                  /                    \
     |  ...              |                |\____________________/|
     | /usr/sbin/smail --+----.           |                      |
     |  ...              |     \          | /                    |
     |___________________|      \         | /usr                 |
                                 \        | /usr/sbin            |
                                  `-------> /usr/sbin/smail.real |
                                  .-------> /usr/sbin/smail      |
      ~/stuff/smail/wrapper.c    /        |                      |
      ~/stuff/smail/wrapper ----'          \____________________/

     # dpkg-divert --divert /usr/sbin/smail.real /usr/sbin/smail
     # cp ~fred/stuff/smail/wrapper /usr/sbin/smail

2. Package maintainer wants to provide an `improved' version of a
   file in another package.

     fileutils.deb_______                   ____________________
     |  ...              |                 /                    \
     | /bin/ls ----------+----.           |\____________________/|
     |  ...              |     \          |                      |
     |___________________|      \         | /                    |
                                 \        | /bin                 |
     colour-ls.deb_______         `-------> /bin/ls.mono         |
     |  ...              |       .--------> /bin/ls              |
     | /bin/ls ----------+------'         |                      |
     |  ...              |                 \____________________/
     |...................|
     |preinst:           |
     | case "$1" in install)
     |  dpkg-divert --rename --divert /bin/ls.mono \
     |              --package colour-ls /bin/ls ;;
     | esac              |
     |...................|
     |postrm:            |
     | case "$1" in remove|abort-install)
     |   dpkg-divert --remove --rename --divert /bin/ls.mono \
     |               --package colour-ls /bin/ls ;;
     | esac              |
     |___________________|

We need a name that applies to `/usr/sbin/smail.real' and
`/bin/ls.mono', the filenames, in both situations, and another name
to apply to `/usr/sbin/smail' and `/bin/ls'.

Raul Miller writes ("Re: `overriding' dpkg for a particular file"):
[...]
> Also, it would be nice to see either some documentation or some sort
> of warning about the case where the file is a directory.

If the file is a directory there will be no good effect.  This is
because the redirection would affect only the entry for the directory
itself in the packages whose instances if it were being redirected,
and would not affect any of the files in it.

The most likely result is that dpkg will fail to install the package
because one of the directories where it has files doesn't exist.  It
would probably create the `diverted' name of the directory, fail, and
then clean it up.

Ian.
------- end -------