</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>
<heading>Variable substitutions: <file>debian/substvars</file></heading>
<p>
- When <prgn>dpkg-gencontrol</prgn>,
- <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
- generate control files, they perform variable substitutions
- on their output just before writing it. Variable
+ When <prgn>dpkg-gencontrol</prgn>
+ generates <qref id="binarycontrolfiles">binary package control
+ files</qref> (<file>DEBIAN/control</file>), it performs variable
+ substitutions on its output just before writing it. Variable
substitutions have the form <tt>${<var>variable</var>}</tt>.
The optional file <file>debian/substvars</file> contains
variable substitutions to be used; variables can also be set
directly from <file>debian/rules</file> using the <tt>-V</tt>
- option to the source packaging commands, and certain
- predefined variables are also available.
+ option to the source packaging commands, and certain predefined
+ variables are also available.
</p>
<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>
- <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>
- <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>
+
+ <tag><var>old-preinst</var> <tt>abort-upgrade</tt>
+ <var>new-version</var></tag>
<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>
- </list>
+ </taglist>
+ </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>
- <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>
+
+ <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>
- <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>
- </list>
+ </taglist>
+ </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>
- <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>
+
+ <tag><var>new-prerm</var> <tt>failed-upgrade</tt>
+ <var>old-version</var></tag>
<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>
+ </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>
- <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>
+
+ <tag><var>new-postrm</var> <tt>failed-upgrade</tt>
+ <var>old-version</var></tag>
<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>
+
+ <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>
- <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>
- </list>
+ </taglist>
</p>
-
+ </sect>
<sect id="unpackphase">
<heading>Details of unpack phase of installation or upgrade</heading>
</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>
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>
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>
</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
<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>
(<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">
</p>
</sect>
- <sect>
+ <sect id="permissions-owners">
<heading>Permissions and owners</heading>
<p>
projects / debian / debian-policy.git / blobdiff