Merge branch 'master' into bug504880-rra

[debian/debian-policy.git] / policy.sgml

diff --git a/policy.sgml b/policy.sgml
index e8c22f41edcc1e38c4a773a931ad0cbcb5672b0e..a7747eca93e3def70e3ea3612d72ff02c3a6a998 100644 (file)
--- a/policy.sgml
+++ b/policy.sgml
@@ -1079,10 +1079,10 @@
        </p>
 
        <p>
        </p>
 
        <p>

-         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.
+         Sometimes, unpacking one package requires that another package
+         be first unpacked <em>and</em> configured.  In this case, the
+         dependent package must specify this dependency in
+         the <tt>Pre-Depends</tt> control field.

        </p>
 
        <p>
        </p>
 
        <p>


@@ -3758,111 +3758,173 @@ Checksums-Sha256:
        </heading>
 
        <p>
        </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 preceded
+         by <var>new-</var> are the scripts from the new version of a
+         package being installed, upgraded to, or downgraded to.  Script
+         names preceded by <var>old-</var> are the scripts from the old
+         version of a package that is being upgraded from or downgraded
+         from.
+       </p>

 
        <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>
            <item>

-               <var>postinst</var> <tt>abort-remove</tt>
+             The package will not yet be unpacked, so
+             the <prgn>preinst</prgn> script cannot rely on any files
+             included in its package.  Only essential packages and
+             pre-dependencies (<tt>Pre-Depends</tt>) 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.

            </item>
            </item>

+
+           <tag><var>old-preinst</var> <tt>abort-upgrade</tt>
+             <var>new-version</var></tag>

            <item>
            <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 <tt>postrm
+             upgrade</tt> action failed.  The unpacked files may be
+             partly from the new version or partly missing, so the script
+             cannot not rely on files included in the package.  Package
+             dependencies may not be available.  Pre-dependencies will be
+             at least unpacked following the same rules as above, except
+             they may be only "Half-Installed" if an upgrade of the
+             pre-dependency failed.

            </item>
            </item>

-         </list>
+         </taglist>
+       </p>

 
        <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>
            <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>
            </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>
            <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, dependencies may not be configured or even fully
+             unpacked in some error situations.<footnote>
+               For example, suppose packages foo and bar are installed
+               with foo depending on bar.  If an upgrade of bar were
+               started and then aborted, and then an attempt to remove
+               foo failed because its <prgn>prerm</prgn> script failed,
+               foo's <tt>postinst abort-remove</tt> would be called with
+               bar only "Half-Installed".
+             </footnote>

            </item>
            </item>

-         </list>
+         </taglist>
+       </p>

 
        <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>
            <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" due to a partial upgrade.

            </item>
            </item>

+
+           <tag><var>new-prerm</var> <tt>failed-upgrade</tt>
+             <var>old-version</var></tag>

            <item>
            <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, and all
+             the same constraints as for <tt>preinst upgrade</tt> apply.

            </item>
            </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>
            <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 or replaced.  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>
            </item>

+
+           <tag><var>new-postrm</var> <tt>failed-upgrade</tt>
+             <var>old-version</var></tag>

            <item>
            <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>
            </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>
            <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>
            </item>

-         </list>
+         </taglist>

        </p>
        </p>

-
+      </sect>

 
       <sect id="unpackphase">
        <heading>Details of unpack phase of installation or upgrade</heading>
 
       <sect id="unpackphase">
        <heading>Details of unpack phase of installation or upgrade</heading>


@@ -4540,11 +4602,13 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
        </p>
 
        <p>
        </p>
 
        <p>

-         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.
+         Since <tt>Depends</tt> only places requirements on the order in
+         which packages are configured, packages in an installation run
+         are usually all unpacked first and all configured later.  This
+         allows multiple packages to be upgraded in one unpack and
+         configure step even if some packages being upgraded have
+         versioned dependencies on the upgraded versions of other
+         packages involved in the installation run.

        </p>
 
        <p>
        </p>
 
        <p>


@@ -4554,16 +4618,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
          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.
+         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>
        </p>
 
        <p>


@@ -4588,19 +4651,17 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
 
              <p>
                The <tt>Depends</tt> field should also be used if the
 
              <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.  (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>).
+               <prgn>postinst</prgn> or <prgn>prerm</prgn> scripts
+               require the depended-on package to be unpacked or
+               configured in order to run.  In the case of <tt>postinst
+               configure</tt>, 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> or other <prgn>postinst</prgn>
+               actions, the package dependencies will be at least
+               unpacked or "Half-Installed".
+             </p>

            </item>
 
            <tag><tt>Recommends</tt></tag>
            </item>
 
            <tag><tt>Recommends</tt></tag>


@@ -4659,11 +4720,11 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
              </p>
 
              <p>
              </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.  However, unlike
+               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
                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


@@ -4757,13 +4818,13 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
        <heading>Conflicting binary packages - <tt>Conflicts</tt></heading>
 
        <p>
        <heading>Conflicting binary packages - <tt>Conflicts</tt></heading>
 
        <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 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
-         system at the same time.
+          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 unpacked on the system at the same time.  This
+         is a stronger restriction than <tt>Breaks</tt>, which only
+         prevents both packages from being configured at the same time.
+         Conflicting packages cannot be unpacked on the system at the
+         same time.

        </p>
 
        <p>
        </p>
 
        <p>


@@ -5505,6 +5566,14 @@ Replaces: mail-transport-agent
        (<prgn>ld</prgn>) when compiling packages, as it will only look for
        <file>libgdbm.so</file> when compiling dynamically.
       </p>
        (<prgn>ld</prgn>) when compiling packages, as it will only look for
        <file>libgdbm.so</file> when compiling dynamically.
       </p>

+
+      <p>
+       If the package provides Ada Library Information
+       (<file>*.ali</file>) files for use with GNAT, these files must be
+       installed read-only (mode 0444) so that GNAT will not attempt to
+       recompile them.  This overrides the normal file mode requirements
+       given in <ref id="permissions-owners">.
+      </p>

       </sect>
 
       <sect id="sharedlibs-intradeps">
       </sect>
 
       <sect id="sharedlibs-intradeps">


@@ -8063,7 +8132,7 @@ endscript
        </p>
       </sect>
 
        </p>
       </sect>
 

-      <sect>
+      <sect id="permissions-owners">

        <heading>Permissions and owners</heading>
 
        <p>
        <heading>Permissions and owners</heading>
 
        <p>