Bug#379150: Documentation for Breaks in dpkg
Package: debian-policy
Version: 3.7.2.1
Severity: wishlist
Tags: patch
As I report in #379140 (against dpkg), I have implemented Breaks in
dpkg. The attached patch is the corresponding change to the manual.
It would probably not be wise to apply this patch until we have
settled on a deployment plan for Breaks in Debian; as I say in
#379140, I hope to get around to that this weekend.
Regards,
Ian.
diff -ru orig/debian-policy-3.7.2.1/debian/changelog debian-policy-3.7.2.1/debian/changelog
--- orig/debian-policy-3.7.2.1/debian/changelog 2006-06-20 06:20:13.000000000 +0100
+++ debian-policy-3.7.2.1/debian/changelog 2006-07-21 18:58:36.000000000 +0100
@@ -1,3 +1,9 @@
+debian-policy (3.7.2.1-0iwj1) unstable; urgency=low
+
+ * Document new `Breaks' dependency field.
+
+ -- Ian Jackson <iwj@ubuntu.com> Fri, 21 Jul 2006 18:58:32 +0100
+
debian-policy (3.7.2.1) unstable; urgency=low
* Bug fix: "debian-policy: s/control are/&a/; s/stats/status/;
Only in debian-policy-3.7.2.1/debian: changelog~
diff -ru orig/debian-policy-3.7.2.1/policy.sgml debian-policy-3.7.2.1/policy.sgml
--- orig/debian-policy-3.7.2.1/policy.sgml 2006-06-20 06:20:13.000000000 +0100
+++ debian-policy-3.7.2.1/policy.sgml 2006-07-21 18:56:52.000000000 +0100
@@ -2546,7 +2546,8 @@
<sect1>
<heading>Package interrelationship fields:
<tt>Depends</tt>, <tt>Pre-Depends</tt>,
- <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Conflicts</tt>,
+ <tt>Recommends</tt>, <tt>Suggests</tt>,
+ <tt>Breaks</tt>, <tt>Conflicts</tt>,
<tt>Provides</tt>, <tt>Replaces</tt>, <tt>Enhances</tt>
</heading>
@@ -3319,8 +3320,8 @@
<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>
+ [<tt>removing</tt> <var>conflicting-package</var>
+ <var>version</var>]
</item>
</list>
@@ -3345,9 +3346,9 @@
<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>version</var> [<tt>removing</tt>
<var>conflicting-package</var>
- <var>version</var>
+ <var>version</var>]
</item>
</list>
@@ -3428,11 +3429,30 @@
</item>
<item>
- If a "conflicting" package is being removed at the same time:
+ If a "conflicting" package is being removed at the same time,
+ or if any package will be broken (due to <tt>Breaks</tt>):
<enumlist>
<item>
- If any packages depended on that conflicting
- package and <tt>--auto-deconfigure</tt> is
+ If <tt>--auto-deconfigure</tt> is
+ specified, call, for each package to be deconfigured
+ due to <tt>Breaks</tt>:
+ <example compact="compact">
+<var>deconfigured's-prerm</var> deconfigure \
+ in-favour <var>package-being-installed</var> <var>version</var>
+ </example>
+ Error unwind:
+ <example compact="compact">
+<var>deconfigured's-postinst</var> abort-deconfigure \
+ in-favour <var>package-being-installed-but-failed</var> <var>version</var>
+ </example>
+ The deconfigured packages are marked as
+ requiring configuration, so that if
+ <tt>--install</tt> is used they will be
+ configured again if possible.
+ </item>
+ <item>
+ If any packages depended on a conflicting
+ package being removed and <tt>--auto-deconfigure</tt> is
specified, call, for each such package:
<example compact="compact">
<var>deconfigured's-prerm</var> deconfigure \
@@ -3451,7 +3471,7 @@
configured again if possible.
</item>
<item>
- To prepare for removal of the conflicting package, call:
+ To prepare for removal of each conflicting package, call:
<example compact="compact">
<var>conflictor's-prerm</var> remove \
in-favour <var>package</var> <var>new-version</var>
@@ -3945,16 +3965,19 @@
<p>
This is done using the <tt>Depends</tt>, <tt>Pre-Depends</tt>,
- <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt> and
- <tt>Conflicts</tt> control file fields.
+ <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
+ <tt>Breaks</tt> and <tt>Conflicts</tt> control file fields.
</p>
<p>
- These six fields are used to declare a dependency
+ These seven fields are used to declare a dependency
relationship by one package on another. Except for
- <tt>Enhances</tt>, they appear in the depending (binary)
- package's control file. (<tt>Enhances</tt> appears in the
- recommending package's control file.)
+ <tt>Enhances</tt> and <tt>Breaks</tt>, they appear in the
+ depending (binary) package's control file.
+ (<tt>Enhances</tt> appears in the recommending package's
+ control file, and <tt>Breaks</tt> appears in the version of
+ depended-on package which causes the named package to
+ break).
</p>
<p>
@@ -3991,7 +4014,7 @@
point, 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
- dependcy loop they happen to be on.
+ dependency loop they happen to be on.
</p>
<p>
@@ -4122,6 +4145,46 @@
</p>
</sect>
+ <sect id="breaks">
+ <heading>Packages which break other packages - <tt>Breaks</tt></heading>
+
+ <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
+ package is deconfigured first, and it will refuse to
+ allow the broken package to be reconfigured.
+ </p>
+
+ <p>
+ A package will not be regarded as causing breakage merely
+ because its configuration files are still installed; it must
+ be at least half-installed.
+ </p>
+
+ <p>
+ A special exception is made for packages which declare that
+ they break their own package name or a virtual package which
+ they provide (see below): this does not count as a real
+ breakage.
+ </p>
+
+ <p>
+ Normally a <tt>Breaks</tt> entry will have an "earlier than"
+ version clause; such a <tt>Breaks</tt> is introduced in the
+ version of an (implicit or explicit) dependency which
+ violates an assumption or reveals a bug in earlier versions
+ of the broken package. This use of <tt>Breaks</tt> will
+ inform higher-level package management tools that broken
+ package must be upgraded before the new one.
+ </p>
+
+ <p>
+ If the breaking package also overwrites some files from the
+ older package, it should use <tt>Replaces</tt> (not
+ <tt>Conflicts</tt>) to ensure this goes smoothly.
+ </sect>
+
<sect id="conflicts">
<heading>Conflicting binary packages - <tt>Conflicts</tt></heading>
@@ -4167,7 +4230,8 @@
"earlier than" version clause. This would prevent
<prgn>dpkg</prgn> from upgrading or installing the package
which declared such a conflict until the upgrade or removal
- of the conflicted-with package had been completed.
+ of the conflicted-with package had been completed. Instead,
+ <tt>Breaks</tt> should be used.
</p>
</sect>
@@ -4178,7 +4242,7 @@
As well as the names of actual ("concrete") packages, the
package relationship fields <tt>Depends</tt>,
<tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
- <tt>Pre-Depends</tt>, <tt>Conflicts</tt>,
+ <tt>Pre-Depends</tt>, <tt>Breaks</tt>, <tt>Conflicts</tt>,
<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
<tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>
may mention "virtual packages".
@@ -4214,16 +4278,16 @@
</p>
<p>
- If a dependency or a conflict has a version number attached
+ If a relationship field has a version number attached
then only real packages will be considered to see whether
the relationship is satisfied (or the prohibition violated,
- for a conflict) - it is assumed that a real package which
- provides the virtual package is not of the "right" version.
- So, a <tt>Provides</tt> field may not contain version
- numbers, and the version number of the concrete package
- which provides a particular virtual package will not be
- looked at when considering a dependency on or conflict with
- the virtual package name.
+ for a conflict or breakage) - it is assumed that a real
+ package which provides the virtual package is not of the
+ "right" version. So, a <tt>Provides</tt> field may not
+ contain version numbers, and the version number of the
+ concrete package which provides a particular virtual package
+ will not be looked at when considering a dependency on or
+ conflict with the virtual package name.
</p>
<p>
@@ -7345,7 +7409,7 @@
<prgn>dpkg-statoverride</prgn> is a replacement for the
deprecated <tt>suidmanager</tt> package. Packages which
previously used <tt>suidmanager</tt> should have a
- <tt>Conflicts: suidmanager (<< 0.50)</tt> entry (or even
+ <tt>Breaks: suidmanager (<< 0.50)</tt> entry (or even
<tt>(<< 0.52)</tt>), and calls to <tt>suidregister</tt>
and <tt>suidunregister</tt> should now be simply removed
from the maintainer scripts.
Only in debian-policy-3.7.2.1: policy.sgml~
Reply to: