Raphael Hertzog <hert...@debian.org> writes:
> We don't want that, feel free to reword that part to frighten people
> that would like to use it just because that sentence says you can rely
> on it. :)
I re-read this whole section while applying your patch and decided that
the wording of the whole section could be improved, so I reworded it in
multiple places. Could everyone review the following, both for accuracy
and for the recommendations that it makes? Note that this adds a "should"
requirement that packagers avoid circular dependencies, particularly if a
postinst script is present.
Inline below is just the new part, including a modification of Raphael's
addition. Attached is the complete patch against the current version of
Policy.
diff --git a/policy.sgml b/policy.sgml
index f5c6818..f4c16ab 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -4273,31 +4273,30 @@ Build-Depends: foo [!i386] | bar [!amd64]
</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.
- </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 unpacked when being
- unpacked 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.
+ 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>
+ 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 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
+ <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>
@@ -4309,7 +4308,8 @@ Build-Depends: foo [!i386] | bar [!amd64]
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>
@@ -4323,10 +4323,17 @@ Build-Depends: foo [!i386] | bar [!amd64]
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.
+ present in order to run. (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>postinst</prgn> and <prgn>postrm</prgn>, the
+ depended-on packages will be unpacked and configured
+ first. (Note, however, that the <prgn>postrm</prgn>
+ cannot rely on any non-essential packages to be present
+ during the <tt>purge</tt> phase.) In the case of
+ <prgn>prerm</prgn>, the depended-on package will at least
+ be unpacked (it might be configured too, but you can't
+ rely on this unless you use <tt>Pre-Depends</tt>).
</item>
<tag><tt>Recommends</tt></tag>
@@ -4389,7 +4396,17 @@ Build-Depends: foo [!i386] | bar [!amd64]
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.
+ 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>
@@ -4398,13 +4415,6 @@ Build-Depends: foo [!i386] | bar [!amd64]
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>
--
Russ Allbery (r...@debian.org) <http://www.eyrie.org/~eagle/>
diff --git a/policy.sgml b/policy.sgml
index 36f51aa..423b960 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -1034,8 +1034,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>
@@ -3456,7 +3456,7 @@ Package: libc6
<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.
@@ -3835,7 +3835,7 @@ Package: libc6
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>.
@@ -3971,7 +3971,7 @@ Package: libc6
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>
@@ -4267,31 +4267,30 @@ Build-Depends: foo [!i386] | bar [!amd64]
</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 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
+ <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>
@@ -4303,7 +4302,8 @@ Build-Depends: foo [!i386] | bar [!amd64]
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>
@@ -4317,10 +4317,17 @@ Build-Depends: foo [!i386] | bar [!amd64]
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.
+ present in order to run. (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>postinst</prgn> and <prgn>postrm</prgn>, the
+ depended-on packages will be unpacked and configured
+ first. (Note, however, that the <prgn>postrm</prgn>
+ cannot rely on any non-essential packages to be present
+ during the <tt>purge</tt> phase.) In the case of
+ <prgn>prerm</prgn>, the depended-on package will at least
+ be unpacked (it might be configured too, but you can't
+ rely on this unless you use <tt>Pre-Depends</tt>).
</item>
<tag><tt>Recommends</tt></tag>
@@ -4383,7 +4390,17 @@ Build-Depends: foo [!i386] | bar [!amd64]
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.
+ 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>
@@ -4392,13 +4409,6 @@ Build-Depends: foo [!i386] | bar [!amd64]
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>
@@ -4429,7 +4439,7 @@ Build-Depends: foo [!i386] | bar [!amd64]
<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>
@@ -4470,13 +4480,13 @@ Build-Depends: foo [!i386] | bar [!amd64]
<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.
</p>
<p>
- If one package is to be installed, the other must be removed
- first - if the package being installed is marked as
+ 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">) the one on the system,
or the one on the system is marked as deselected, or both
packages are marked <tt>Essential</tt>, then
@@ -4671,7 +4681,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.
</sect1>
</sect>
@@ -4903,7 +4913,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
@@ -5039,7 +5049,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>
@@ -9298,7 +9308,7 @@ install-info --quiet --remove /usr/share/info/foobar.info
<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>
