policy/ap-pkg-diversions.rst

   1 Diversions - overriding a package's version of a file (from old Packaging Manual)
   2 =================================================================================
   3
   4 It is possible to have ``dpkg`` not overwrite a file when it reinstalls
   5 the package it belongs to, and to have it put the file from the package
   6 somewhere else instead.
   7
   8 This can be used locally to override a package's version of a file, or
   9 by one package to override another's version (or provide a wrapper for
  10 it).
  11
  12 Before deciding to use a diversion, read
  13 :doc:`ap-pkg-alternatives` to see if you really want a
  14 diversion rather than several alternative versions of a program.
  15
  16 There is a diversion list, which is read by ``dpkg``, and updated by a
  17 special program ``dpkg-divert``. Please see dpkg-divert(8) for full
  18 details of its operation.
  19
  20 When a package wishes to divert a file from another, it should call
  21 ``dpkg-divert`` in its preinst to add the diversion and rename the
  22 existing file. For example, supposing that a ``smailwrapper`` package
  23 wishes to install a wrapper around ``/usr/sbin/smail``:
  24
  25 ::
  26
  27     dpkg-divert --package smailwrapper --add --rename \
  28         --divert /usr/sbin/smail.real /usr/sbin/smail
  29
  30 The ``--package smailwrapper`` ensures that ``smailwrapper``'s copy of
  31 ``/usr/sbin/smail`` can bypass the diversion and get installed as the
  32 true version. It's safe to add the diversion unconditionally on upgrades
  33 since it will be left unchanged if it already exists, but
  34 ``dpkg-divert`` will display a message. To suppress that message, make
  35 the command conditional on the version from which the package is being
  36 upgraded:
  37
  38 ::
  39
  40     if [ upgrade != "$1 || dpkg --compare-versions "$2" lt 1.0-2; then
  41         dpkg-divert --package smailwrapper --add --rename \
  42             --divert /usr/sbin/smail.real /usr/sbin/smail
  43     fi
  44
  45 where ``1.0-2`` is the version at which the diversion was first added to
  46 the package. Running the command during abort-upgrade is pointless but
  47 harmless.
  48
  49 The postrm has to do the reverse:
  50
  51 ::
  52
  53     if [ remove = "$1" -o abort-install = "$1" -o disappear = "$1; then
  54         dpkg-divert --package smailwrapper --remove --rename \
  55             --divert /usr/sbin/smail.real /usr/sbin/smail
  56     fi
  57
  58 If the diversion was added at a particular version, the postrm should
  59 also handle the failure case of upgrading from an older version (unless
  60 the older version is so old that direct upgrades are no longer
  61 supported):
  62
  63 ::
  64
  65     if [ abort-upgrade = "$1 && dpkg --compare-versions "$2" lt 1.0-2; then
  66         dpkg-divert --package smailwrapper --remove --rename \
  67             --divert /usr/sbin/smail.real /usr/sbin/smail
  68     fi
  69
  70 where ``1.0-2`` is the version at which the diversion was first added to
  71 the package. The postrm should not remove the diversion on upgrades both
  72 because there's no reason to remove the diversion only to immediately
  73 re-add it and since the postrm of the old package is run after unpacking
  74 so the removal of the diversion will fail.
  75
  76 Do not attempt to divert a file which is vitally important for the
  77 system's operation - when using ``dpkg-divert`` there is a time, after
  78 it has been diverted but before ``dpkg`` has installed the new version,
  79 when the file does not exist.
  80
  81 Do not attempt to divert a conffile, as ``dpkg`` does not handle it
  82 well.
  83