Re: Bug#504880: Disambiguate "installed" for packages
Colin Watson <cjwatson@debian.org> writes:
> The policy manual currently uses the word "installed" in a couple of
> different ways when referring to packages. Sometimes it's speaking quite
> loosely, and in this sense is talking about something roughly equivalent
> to 'dpkg --install'. However, in some other cases it's using a sense of
> the word which I believe derives from dpkg's internal state machine, and
> which corresponds to 'dpkg --unpack'. On quite a number of occasions
> I've helped to explain this to people who were confused as a result: for
> instance, unless you realise the second sense, the definition of
> Conflicts is quite difficult to read.
> I suggest that the second sense should be written as "unpacked" rather
> than "installed". Although this breaks the correspondence with dpkg's
> internal state machine, it brings the policy manual into line with the
> verbs used on dpkg's command line, which I think correspond much more
> reliably to how people think of the operation or state in question.
This bug and its corresponding patch have grown rather far beyond Colin's
intention, since we uncovered a lot of other issues during the discussion
around exactly what dependency scripts can assume. I finally had a chance
to read over Ian Jackson's reply in detail and try to incorporate it into
this patch. Here is the result.
This adds new information to the "Summary of ways maintainer scripts are
called" section (6.5) stating exactly what maintainer scripts can depend
on when various actions are called. Since we worked that out over the
course of the discussion, I don't want to lose that information, since
that's been opaque to me for years and would greatly benefit from being
documented.
This patch also, based on Ian's analysis, makes clear that postrm cannot
rely on dependencies being available even for cases other than purge and
is more explicit in several cases about what dependencies do for you. It
has a new "should" discouraging circular dependencies.
Please review in detail, as this is the first documentation we'll have of
several hairy assumptions involved in maintainer script dependencies.
diff --git a/policy.sgml b/policy.sgml
index 847f716..7fc9ad1 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -1079,8 +1079,8 @@
</p>
<p>
- Sometimes, a package requires another package to be installed
- <em>and</em> configured before it can be installed. In this
+ Sometimes, a package requires another package to be unpacked
+ <em>and</em> configured before it can be unpacked. In this
case, you must specify a <tt>Pre-Depends</tt> entry for
the package.
</p>
@@ -3674,7 +3674,7 @@ Checksums-Sha256:
<p>
Broadly speaking the <prgn>preinst</prgn> is called before
- (a particular version of) a package is installed, and the
+ (a particular version of) a package is unpacked, and the
<prgn>postinst</prgn> afterwards; the <prgn>prerm</prgn>
before (a version of) a package is removed and the
<prgn>postrm</prgn> afterwards.
@@ -3758,111 +3758,166 @@ Checksums-Sha256:
</heading>
<p>
- <list compact="compact">
- <item>
- <var>new-preinst</var> <tt>install</tt>
- </item>
- <item>
- <var>new-preinst</var> <tt>install</tt> <var>old-version</var>
- </item>
- <item>
- <var>new-preinst</var> <tt>upgrade</tt> <var>old-version</var>
- </item>
- <item>
- <var>old-preinst</var> <tt>abort-upgrade</tt>
- <var>new-version</var>
- </item>
- </list>
+ What follows is a summary of all the ways in which maintainer
+ scripts may be called along with what facilities those scripts
+ may rely on being available at that time. Script names
+ preceeded by <var>new-</var> are the scripts from the new
+ version of a package being installed or upgraded. Script names
+ preceeded by <var>old-</var> are the scripts from the old
+ version of a package that is being upgraded to a new version.
+ </p>
<p>
- <list compact="compact">
- <item>
- <var>postinst</var> <tt>configure</tt>
- <var>most-recently-configured-version</var>
- </item>
- <item>
- <var>old-postinst</var> <tt>abort-upgrade</tt>
- <var>new-version</var>
- </item>
- <item>
- <var>conflictor's-postinst</var> <tt>abort-remove</tt>
- <tt>in-favour</tt> <var>package</var>
- <var>new-version</var>
- </item>
+ The <prgn>preinst</prgn> script may be called in the following
+ ways:
+ <taglist>
+ <tag><var>new-preinst</var> <tt>install</tt></tag>
+ <tag><var>new-preinst</var> <tt>install</tt>
+ <var>old-version</var></tag>
+ <tag><var>new-preinst</var> <tt>upgrade</tt>
+ <var>old-version</var></tag>
<item>
- <var>postinst</var> <tt>abort-remove</tt>
+ Only essential packages and pre-dependencies
+ (<tt>Pre-Depends</tt>) may be assumed to be available.
+ Pre-dependencies will either be configured or will be
+ "Unpacked" or "Half-Configured" but previously had been
+ configured and was never removed. The package will not yet
+ be unpacked, so the <prgn>preinst</prgn> script cannot rely
+ on any files included in its package.
</item>
+
+ <tag><var>old-preinst</var> <tt>abort-upgrade</tt>
+ <var>new-version</var></tag>
<item>
- <var>deconfigured's-postinst</var>
- <tt>abort-deconfigure</tt> <tt>in-favour</tt>
- <var>failed-install-package</var> <var>version</var>
- [<tt>removing</tt> <var>conflicting-package</var>
- <var>version</var>]
+ Called during error handling of an upgrade that failed after
+ unpacking the new package because the
+ old <prgn>postrm</prgn> failed during the upgrade action.
+ Depending on the severity and nature of the error, the
+ package's dependencies, including pre-dependencies, may be
+ only "Half-Installed" or "Unpacked" and are not necessarily
+ configured, and the files for the old package may not yet be
+ unpacked.
</item>
- </list>
+ </taglist>
+ </p>
<p>
- <list compact="compact">
- <item>
- <var>prerm</var> <tt>remove</tt>
- </item>
- <item>
- <var>old-prerm</var> <tt>upgrade</tt>
- <var>new-version</var>
- </item>
- <item>
- <var>new-prerm</var> <tt>failed-upgrade</tt>
- <var>old-version</var>
- </item>
+ The <prgn>postinst</prgn> script may be called in the following
+ ways:
+ <taglist>
+ <tag><var>postinst</var> <tt>configure</tt>
+ <var>most-recently-configured-version</var></tag>
<item>
- <var>conflictor's-prerm</var> <tt>remove</tt>
- <tt>in-favour</tt> <var>package</var>
- <var>new-version</var>
+ The files contained in the package will be unpacked. All
+ package dependencies will at least be unpacked. If there
+ are no circular dependencies involved, all package
+ dependencies will be configured.
</item>
+
+ <tag><var>old-postinst</var> <tt>abort-upgrade</tt>
+ <var>new-version</var></tag>
+ <tag><var>conflictor's-postinst</var> <tt>abort-remove</tt>
+ <tt>in-favour</tt> <var>package</var>
+ <var>new-version</var></tag>
+ <tag><var>postinst</var> <tt>abort-remove</tt></tag>
+ <tag><var>deconfigured's-postinst</var>
+ <tt>abort-deconfigure</tt> <tt>in-favour</tt>
+ <var>failed-install-package</var> <var>version</var>
+ [<tt>removing</tt> <var>conflicting-package</var>
+ <var>version</var>]</tag>
<item>
- <var>deconfigured's-prerm</var> <tt>deconfigure</tt>
- <tt>in-favour</tt> <var>package-being-installed</var>
- <var>version</var> [<tt>removing</tt>
- <var>conflicting-package</var>
- <var>version</var>]
+ The files contained in the package will be unpacked. All
+ package dependencies will at least be "Half-Installed" and
+ will have previously been configured and not removed.
+ However, depending on the nature and severity of the error,
+ dependencies may not be configured or even fully unpacked.
</item>
- </list>
+ </taglist>
+ </p>
<p>
- <list compact="compact">
- <item>
- <var>postrm</var> <tt>remove</tt>
- </item>
- <item>
- <var>postrm</var> <tt>purge</tt>
- </item>
- <item>
- <var>old-postrm</var> <tt>upgrade</tt>
- <var>new-version</var>
- </item>
+ The <prgn>prerm</prgn> script may be called in the following
+ ways:
+ <taglist>
+ <tag><var>prerm</var> <tt>remove</tt></tag>
+ <tag><var>old-prerm</var>
+ <tt>upgrade</tt><var>new-version</var></tag>
+ <tag><var>conflictor's-prerm</var> <tt>remove</tt>
+ <tt>in-favour</tt> <var>package</var>
+ <var>new-version</var></tag>
+ <tag><var>deconfigured's-prerm</var> <tt>deconfigure</tt>
+ <tt>in-favour</tt> <var>package-being-installed</var>
+ <var>version</var> [<tt>removing</tt>
+ <var>conflicting-package</var> <var>version</var>]</tag>
<item>
- <var>new-postrm</var> <tt>failed-upgrade</tt>
- <var>old-version</var>
+ The package whose <prgn>prerm</prgn> is being called will be
+ at least "Half-Installed". All package dependencies will at
+ least be "Half-Installed" and will have previously been
+ configured and not removed. If there was no error, all
+ dependencies will at least be unpacked, but these actions
+ may be called in various error states where dependencies are
+ only "Half-Installed".
</item>
+
+ <tag><var>new-prerm</var> <tt>failed-upgrade</tt>
+ <var>old-version</var></tag>
<item>
- <var>new-postrm</var> <tt>abort-install</tt>
+ Called during error handling when <tt>prerm upgrade</tt>
+ fails. The new package will not yet be unpacked. Since
+ this is the first action taken during a package upgrade,
+ only essential packages and pre-dependencies may be relied
+ on. Pre-dependencies will either be configured or will be
+ "Unpacked" or "Half-Configured" but previously had been
+ configured and was never removed.
</item>
+ </taglist>
+ </p>
+
+ <p>
+ The <prgn>postrm</prgn> script may be called in the following
+ ways:
+ <taglist>
+ <tag><var>postrm</var> <tt>remove</tt></tag>
+ <tag><var>postrm</var> <tt>purge</tt></tag>
+ <tag><var>old-postrm</var> <tt>upgrade</tt>
+ <var>new-version</var></tag>
+ <tag><var>disappearer's-postrm</var> <tt>disappear</tt>
+ <var>overwriter</var> <var>overwriter-version</var></tag>
<item>
- <var>new-postrm</var> <tt>abort-install</tt>
- <var>old-version</var>
+ The <prgn>postrm</prgn> script is called after the package's
+ files have been removed. The package
+ whose <prgn>postrm</prgn> is being called may have
+ previously been deconfigured and only be unpacked, at which
+ point subsequent package changes do not consider its
+ dependencies. Therefore, all <prgn>postrm</prgn> actions
+ may only rely on essential packages and cannot assume that
+ the package's dependencies are available.
</item>
+
+ <tag><var>new-postrm</var> <tt>failed-upgrade</tt>
+ <var>old-version</var></tag>
<item>
- <var>new-postrm</var> <tt>abort-upgrade</tt>
- <var>old-version</var>
+ Called when the old <tt>postrm upgrade</tt> action fails.
+ The new package will be unpacked, but only essential
+ packages and pre-dependencies can be relied on.
+ Pre-dependencies will either be configured or will be
+ "Unpacked" or "Half-Configured" but previously had been
+ configured and was never removed.
</item>
+
+ <tag><var>new-postrm</var> <tt>abort-install</tt></tag>
+ <tag><var>new-postrm</var> <tt>abort-install</tt>
+ <var>old-version</var></tag>
+ <tag><var>new-postrm</var> <tt>abort-upgrade</tt>
+ <var>old-version</var></tag>
<item>
- <var>disappearer's-postrm</var> <tt>disappear</tt>
- <var>overwriter</var>
- <var>overwriter-version</var>
+ Called before unpackaging the new package as part of the
+ error handling of <prgn>preinst</prgn> failures. May assume
+ the same state as <prgn>preinst</prgn> can assume.
</item>
- </list>
+ </taglist>
</p>
-
+ </sect>
<sect id="unpackphase">
<heading>Details of unpack phase of installation or upgrade</heading>
@@ -4064,7 +4119,7 @@ Checksums-Sha256:
behavior which, though deterministic, is hard for the
system administrator to understand. It can easily
lead to "missing" programs if, for example, a package
- is installed which overwrites a file from another
+ is unpacked which overwrites a file from another
package, and is then removed again.<footnote>
Part of the problem is due to what is arguably a
bug in <prgn>dpkg</prgn>.
@@ -4200,7 +4255,7 @@ Checksums-Sha256:
If there was a conflicting package we go and do the
removal actions (described below), starting with the
removal of the conflicting package's files (any that
- are also in the package being installed have already
+ are also in the package being unpacked have already
been removed from the conflicting package's file list,
and so do not get removed now).
</item>
@@ -4540,31 +4595,29 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
</p>
<p>
- For this reason packages in an installation run are usually
- all unpacked first and all configured later; this gives
- later versions of packages with dependencies on later
- versions of other packages the opportunity to have their
- dependencies satisfied.
+ Since <tt>Depends</tt> only places requirements on the
+ configuration step, packages in an installation run are usually
+ all unpacked first and all configured later. This makes it
+ easier to satisfy all dependencies when multiple packages are
+ being upgraded.
</p>
- <p>
- In case of circular dependencies, since installation or
- removal order honoring the dependency order can't be
- established, dependency loops are broken at some point
- (based on rules below), and some packages may not be able to
- rely on their dependencies being present when being
- installed or removed, depending on which side of the break
- of the circular dependency loop they happen to be on. If one
- of the packages in the loop has no postinst script, then the
- cycle will be broken at that package, so as to ensure that
- all postinst scripts run with the dependencies properly
- configured if this is possible. Otherwise the breaking point
- is arbitrary.
- </p>
-
<p>
- The <tt>Depends</tt> field thus allows package maintainers
- to impose an order in which packages should be configured.
+ If there is a circular dependency among packages being installed
+ or removed, installation or removal order honoring the
+ dependency order is impossible, requiring the dependency loop be
+ broken at some point and the dependency requirements violated
+ for at least one package. Packages involved in circular
+ dependencies may not be able to rely on their dependencies being
+ configured when being configured depending on which side of the
+ break of the circular dependency loop they happen to be on. If
+ one of the packages in the loop has no <prgn>postinst</prgn>
+ script, then the cycle will be broken at that package; this
+ ensures that all <prgn>postinst</prgn> scripts are run with
+ their dependencies properly configured if this is possible.
+ Otherwise the breaking point is arbitrary. Packages should
+ therefore avoid circular dependencies where possible,
+ particularly if they have <prgn>postinst</prgn> scripts.
</p>
<p>
@@ -4576,7 +4629,8 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
This declares an absolute dependency. A package will
not be configured unless all of the packages listed in
its <tt>Depends</tt> field have been correctly
- configured.
+ configured (unless there is a circular dependency as
+ described above).
</p>
<p>
@@ -4588,12 +4642,16 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
<p>
The <tt>Depends</tt> field should also be used if the
- <prgn>postinst</prgn>, <prgn>prerm</prgn> or
- <prgn>postrm</prgn> scripts require the package to be
- present in order to run. Note, however, that the
- <prgn>postrm</prgn> cannot rely on any non-essential
- packages to be present during the <tt>purge</tt>
- phase.
+ <prgn>postinst</prgn> or <prgn>prerm</prgn> scripts
+ require the package to be unpacked or configured in order
+ to run. In the case of <prgn>postinst</prgn>, the
+ depended-on packages will be unpacked and configured
+ first. (If both packages are involved in a dependency
+ loop, this might not work as expected; see the explanation
+ a few paragraphs back.) In the case
+ of <prgn>prerm</prgn>, the package dependencies will be at
+ least unpacked or "Half-Installed".
+ </p>
</item>
<tag><tt>Recommends</tt></tag>
@@ -4652,11 +4710,21 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
</p>
<p>
- When the package declaring a pre-dependency is about
- to be <em>configured</em>, the pre-dependency will be
- treated as a normal <tt>Depends</tt>, that is, it will
- be considered satisfied only if the depended-on
- package has been correctly configured.
+ When the package declaring a pre-dependency is about to
+ be <em>configured</em>, the pre-dependency will be treated
+ as a normal <tt>Depends</tt>. It will be considered
+ satisfied only if the depended-on package has been
+ correctly configured. However, unlike
+ with <tt>Depends</tt>, <tt>Pre-Depends</tt> does not
+ permit circular dependencies to be broken. If a circular
+ dependency is encountered while attempting to honor
+ <tt>Pre-Depends</tt>, the installation will be aborted.
+ </p>
+
+ <p>
+ <tt>Pre-Depends</tt> are also required if the
+ <prgn>preinst</prgn> script depends on the named package.
+ It is best to avoid this situation if possible.
</p>
<p>
@@ -4665,13 +4733,6 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
installation would hamper the ability of the system to
continue with any upgrade that might be in progress.
</p>
-
- <p>
- <tt>Pre-Depends</tt> are also required if the
- <prgn>preinst</prgn> script depends on the named
- package. It is best to avoid this situation if
- possible.
- </p>
</item>
</taglist>
</p>
@@ -4696,7 +4757,7 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
<p>
When one binary package declares that it breaks another,
<prgn>dpkg</prgn> will refuse to allow the package which
- declares <tt>Breaks</tt> be installed unless the broken
+ declares <tt>Breaks</tt> be unpacked unless the broken
package is deconfigured first, and it will refuse to
allow the broken package to be reconfigured.
</p>
@@ -4749,7 +4810,7 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
<p>
When one binary package declares a conflict with another
using a <tt>Conflicts</tt> field, <prgn>dpkg</prgn> will
- refuse to allow them to be installed on the system at the
+ refuse to allow them to be unpacked on the system at the
same time. This is a stronger restriction than <tt>Breaks</tt>,
which just prevents both packages from being configured at the
same time. Conflicting packages cannot be unpacked on the
@@ -4757,8 +4818,8 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
</p>
<p>
- If one package is to be installed, the other must be removed
- first. If the package being installed is marked as replacing
+ If one package is to be unpacked, the other must be removed
+ first. If the package being unpacked is marked as replacing
(see <ref id="replaces">, but note that <tt>Breaks</tt> should
normally be used in this case) the one on the system, or the one
on the system is marked as deselected, or both packages are
@@ -5039,7 +5100,7 @@ Provides: mail-transport-agent
Conflicts: mail-transport-agent
Replaces: mail-transport-agent
</example>
- ensuring that only one MTA can be installed at any one
+ ensuring that only one MTA can be unpacked at any one
time. See <ref id="virtual"> for more information about this
example.
</sect1>
@@ -5338,7 +5399,7 @@ Replaces: mail-transport-agent
<footnote>
<p>
During install or upgrade, the preinst is called before
- the new files are installed, so calling "ldconfig" is
+ the new files are unpacked, so calling "ldconfig" is
pointless. The preinst of an existing package can also be
called if an upgrade fails. However, this happens during
the critical time when a shared libs may exist on-disk
@@ -5483,7 +5544,7 @@ Replaces: mail-transport-agent
<ref id="conflicts">) to ensure that the user only installs one
development version at a time (as different development versions are
likely to have the same header files in them, which would cause a
- filename clash if both were installed).
+ filename clash if both were unpacked).
</p>
<p>
@@ -9774,7 +9835,7 @@ END-INFO-DIR-ENTRY
<p>
The <prgn>DEBIAN</prgn> directory will not appear in the
file system archive of the package, and so won't be installed
- by <prgn>dpkg</prgn> when the package is installed.
+ by <prgn>dpkg</prgn> when the package is unpacked.
</p>
<p>
--
Russ Allbery (rra@debian.org) <http://www.eyrie.org/~eagle/>
Reply to: