From 597318a1bfcc38339ec181c3215b9cd5d1aba7ee Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Sun, 15 Aug 2010 12:28:23 -0700 Subject: [PATCH] Update maintainer script dependency language Based on review and feedback from Steve Langasek. --- policy.sgml | 86 ++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 59 insertions(+), 27 deletions(-) diff --git a/policy.sgml b/policy.sgml index c5976e3..8a70ebf 100644 --- a/policy.sgml +++ b/policy.sgml @@ -1106,7 +1106,7 @@

Sometimes, unpacking one package requires that another package be first unpacked and configured. In this case, the - dependent package must specify this dependency in + depending package must specify this dependency in the Pre-Depends control field.

@@ -3835,11 +3835,11 @@ Checksums-Sha256: the preinst script cannot rely on any files included in its package. Only essential packages and pre-dependencies (Pre-Depends) may be assumed to be - available. Pre-dependencies will be at least unpacked. - They may be only unpacked or "Half-Configured", not - completely configured, but only if a previous version of the - pre-dependency was completely configured and the - pre-dependency had not been removed since then. + available. Pre-dependencies will have been configured at + least once, but at the time the preinst is + called they may only be in an unpacked or "Half-Configured" + state if a previous version of the pre-dependency was + completely configured and has not been removed since then. old-preinst abort-upgrade @@ -3872,7 +3872,9 @@ Checksums-Sha256: 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. + dependencies will be configured. For behavior in the case + of circular dependencies, see the discussion + in . old-postinst abort-upgrade @@ -3899,6 +3901,13 @@ Checksums-Sha256: foo's postinst abort-remove would be called with bar only "Half-Installed". + The postinst should still attempt any actions + for which its dependencies are required, since they will + normally be available, but consider the correct error + handling approach if those actions fail. Aborting + the postinst action if commands or facilities + from the package dependencies are not available is often the + best approach.

@@ -3954,8 +3963,22 @@ Checksums-Sha256: previously been deconfigured and only be unpacked, at which point subsequent package changes do not consider its dependencies. Therefore, all postrm actions - may only rely on essential packages and cannot assume that - the package's dependencies are available. + may only rely on essential packages and must gracefully skip + any actions that require the package's dependencies if those + dependencies are unavailable. + This is often done by checking whether the command or + facility the postrm intends to call is + available before calling it. For example: + +if [ "$1" = purge ] && [ -e /usr/share/debconf/confmodule ]; then + . /usr/share/debconf/confmodule + db_purge +fi + + in postrm purges the debconf + configuration for the package + if debconf is installed. + new-postrm failed-upgrade @@ -4683,15 +4706,16 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any] 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 postinst - script, then the cycle will be broken at that package; this - ensures that all postinst 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 postinst scripts. + configured before they themselves are 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 postinst script, then the cycle will be broken + at that package; this ensures that all postinst + 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 postinst + scripts.

@@ -4718,15 +4742,23 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any] The Depends field should also be used if the postinst or prerm scripts require the depended-on package to be unpacked or - configured in order to run. In the case of postinst - configure, 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 prerm or other postinst - actions, the package dependencies will normally be at - least unpacked, but they may be only "Half-Installed" if a - previous upgrade of the dependency failed. + configured in order to run, or if the dependend-on package + is desirable for cleanup done by postrm. In + the case of postinst configure, 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 prerm or + other postinst actions, the package + dependencies will normally be at least unpacked, but they + may be only "Half-Installed" if a previous upgrade of the + dependency failed. In the case of postrm, + there are no guarantees, but the depended-on package is + more likely to be available if the package declares a + dependency (particularly for postrm remove). + The postrm script must cleanly skip actions + that require a dependency if that dependency isn't + available.

-- 2.39.2