From: Russ Allbery Date: Tue, 20 Jul 2010 18:15:21 +0000 (-0700) Subject: Add detailed breakdown of what maintainer scripts can assume X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=fbb31b2b86fc2ae07f9c28927dabb283cd0b119b;p=debian%2Fdebian-policy.git Add detailed breakdown of what maintainer scripts can assume For each possible action in a maintainer script, state what the maintainer script can assume in that case. Remove references to using Pre-Depends for controlling what's available during package removal. Be clear that no postrm actions can rely on dependencies being available. Remove references saying that prerm can rely on dependencies being configured. Based on extensive analysis by Ian Jackson. --- diff --git a/policy.sgml b/policy.sgml index e8c22f4..1cb71c2 100644 --- a/policy.sgml +++ b/policy.sgml @@ -3758,111 +3758,166 @@ Checksums-Sha256:

- - - new-preinst install - - - new-preinst install old-version - - - new-preinst upgrade old-version - - - old-preinst abort-upgrade - new-version - - + 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 new- are the scripts from the new + version of a package being installed or upgraded. Script names + preceeded by old- are the scripts from the old + version of a package that is being upgraded to a new version. +

- - - postinst configure - most-recently-configured-version - - - old-postinst abort-upgrade - new-version - - - conflictor's-postinst abort-remove - in-favour package - new-version - + The preinst script may be called in the following + ways: + + new-preinst install + new-preinst install + old-version + new-preinst upgrade + old-version - postinst abort-remove + Only essential packages and pre-dependencies + (Pre-Depends) 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 preinst script cannot rely + on any files included in its package. + + old-preinst abort-upgrade + new-version - deconfigured's-postinst - abort-deconfigure in-favour - failed-install-package version - [removing conflicting-package - version] + Called during error handling of an upgrade that failed after + unpacking the new package because the + old postrm 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. - + +

- - - prerm remove - - - old-prerm upgrade - new-version - - - new-prerm failed-upgrade - old-version - + The postinst script may be called in the following + ways: + + postinst configure + most-recently-configured-version - conflictor's-prerm remove - in-favour package - new-version + 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. + + old-postinst abort-upgrade + new-version + conflictor's-postinst abort-remove + in-favour package + new-version + postinst abort-remove + deconfigured's-postinst + abort-deconfigure in-favour + failed-install-package version + [removing conflicting-package + version] - deconfigured's-prerm deconfigure - in-favour package-being-installed - version [removing - conflicting-package - version] + 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. - + +

- - - postrm remove - - - postrm purge - - - old-postrm upgrade - new-version - + The prerm script may be called in the following + ways: + + prerm remove + old-prerm + upgradenew-version + conflictor's-prerm remove + in-favour package + new-version + deconfigured's-prerm deconfigure + in-favour package-being-installed + version [removing + conflicting-package version] - new-postrm failed-upgrade - old-version + The package whose prerm 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". + + new-prerm failed-upgrade + old-version - new-postrm abort-install + Called during error handling when prerm upgrade + 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. + +

+ +

+ The postrm script may be called in the following + ways: + + postrm remove + postrm purge + old-postrm upgrade + new-version + disappearer's-postrm disappear + overwriter overwriter-version - new-postrm abort-install - old-version + The postrm script is called after the package's + files have been removed. The package + whose postrm 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 postrm actions + may only rely on essential packages and cannot assume that + the package's dependencies are available. + + new-postrm failed-upgrade + old-version - new-postrm abort-upgrade - old-version + Called when the old postrm upgrade 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. + + new-postrm abort-install + new-postrm abort-install + old-version + new-postrm abort-upgrade + old-version - disappearer's-postrm disappear - overwriter - overwriter-version + Called before unpackaging the new package as part of the + error handling of preinst failures. May assume + the same state as preinst can assume. - +

- + Details of unpack phase of installation or upgrade @@ -4554,16 +4609,15 @@ 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 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; 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 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.

@@ -4588,19 +4642,16 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]

The Depends field should also be used if the - postinst, prerm or - postrm scripts require the package to be - 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 - postinst and postrm, the + postinst or prerm scripts + require the package to be unpacked or configured in order + to run. In the case of postinst, the depended-on packages will be unpacked and configured - first. (Note, however, that the postrm - cannot rely on any non-essential packages to be present - during the purge phase.) In the case of - prerm, the depended-on package will at least - be unpacked (it might be configured too, but you can't - rely on this unless you use Pre-Depends). + 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, the package dependencies will be at + least unpacked or "Half-Installed". +

Recommends @@ -4659,11 +4710,11 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]

- When the package declaring a pre-dependency is about - to be configured, the pre-dependency will be - treated as a normal Depends, that is, it will - be considered satisfied only if the depended-on - package has been correctly configured. However, unlike + When the package declaring a pre-dependency is about to + be configured, the pre-dependency will be treated + as a normal Depends. It will be considered + satisfied only if the depended-on package has been + correctly configured. However, unlike with Depends, Pre-Depends does not permit circular dependencies to be broken. If a circular dependency is encountered while attempting to honor