<item>
must not require a package outside of <em>main</em>
for compilation or execution (thus, the package must
- not declare a <tt>Pre-Depends</tt>, <tt>Depends</tt>,
- <tt>Recommends</tt>, <tt>Build-Depends</tt>,
- or <tt>Build-Depends-Indep</tt> relationship on a
- non-<em>main</em> package unless a package
- in <em>main</em> is listed as an alternative),
+ not declare a "Depends", "Recommends", or
+ "Build-Depends" relationship on a non-<em>main</em>
+ package),
</item>
<item>
must not be so buggy that we refuse to support them,
in the <tt>.deb</tt> file format.
</p>
+ <p>
+ A <tt>.deb</tt> package contains two sets of files: a set of files
+ to install on the system when the package is installed, and a set
+ of files that provide additional metadata about the package or
+ which are executed when the package is installed or removed. This
+ second set of files is called <em>control information files</em>.
+ Among those files are the package maintainer scripts
+ and <file>control</file>, the <qref id="binarycontrolfiles">binary
+ package control file</qref> that contains the control fields for
+ the package. Other control information files
+ include <qref id="sharedlibs-shlibdeps">the <file>shlibs</file>
+ file</qref> used to store shared library dependency information
+ and the <file>conffiles</file> file that lists the package's
+ configuration files (described in <ref id="config-files">).
+ </p>
+
+ <p>
+ There is unfortunately a collision of terminology here between
+ control information files and files in the Debian control file
+ format. Throughout this document, a <em>control file</em> refers
+ to a file in the Debian control file format. These files are
+ documented in <ref id="controlfields">. Only files referred to
+ specifically as <em>control information files</em> are the files
+ included in the control information file member of
+ the <file>.deb</file> file format used by binary packages. Most
+ control information files are not in the Debian control file
+ format.
+ </p>
+
<sect>
<heading>The package name</heading>
<p>
In general, Debian packages should use the same version
- numbers as the upstream sources.
- </p>
-
- <p>
- However, in some cases where the upstream version number is
- based on a date (e.g., a development "snapshot" release) the
- package management system cannot handle these version
- numbers without epochs. For example, dpkg will consider
- "96May01" to be greater than "96Dec24".
+ numbers as the upstream sources. However, upstream version
+ numbers based on some date formats (sometimes used for
+ development or "snapshot" releases) will not be ordered
+ correctly by the package management software. For
+ example, <prgn>dpkg</prgn> will consider "96May01" to be
+ greater than "96Dec24".
</p>
<p>
To prevent having to use epochs for every new upstream
- version, the date based portion of the version number
- should be changed to the following format in such cases:
- "19960501", "19961224". It is up to the maintainer whether
- they want to bother the upstream maintainer to change
- the version numbers upstream, too.
+ version, the date-based portion of any upstream version number
+ should be given in a way that sorts correctly: four-digit year
+ first, followed by a two-digit numeric month, followed by a
+ two-digit numeric date, possibly with punctuation between the
+ components.
</p>
<p>
- Note that other version formats based on dates which are
- parsed correctly by the package management system should
- <em>not</em> be changed.
- </p>
-
- <p>
- Native Debian packages (i.e., packages which have been
- written especially for Debian) whose version numbers include
- dates should always use the "YYYYMMDD" format.
+ Native Debian packages (i.e., packages which have been written
+ especially for Debian) whose version numbers include dates
+ should also follow these rules. If punctuation is desired
+ between the date components, remember that hyphen (<tt>-</tt>)
+ cannot be used in native package versions. Period
+ (<tt>.</tt>) is normally a good choice.
</p>
</sect1>
<heading>The description of a package</heading>
<p>
- Every Debian package must have an extended description
- stored in the appropriate field of the control record.
- The technical information about the format of the
+ Every Debian package must have a <tt>Description</tt> control
+ field which contains a synopsis and extended description of the
+ package. Technical information about the format of the
<tt>Description</tt> field is in <ref id="f-Description">.
</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>
must be available and usable on the system at all times, even
when packages are in an unconfigured (but unpacked) state.
Packages are tagged <tt>essential</tt> for a system using the
- <tt>Essential</tt> control file field. The format of the
+ <tt>Essential</tt> control field. The format of the
<tt>Essential</tt> control field is described in <ref
id="f-Essential">.
</p>
<p>
Packages which use the Debian Configuration Management
- Specification may contain an additional
- <prgn>config</prgn> script and a <tt>templates</tt>
- file in their control archive<footnote>
- The control.tar.gz inside the .deb.
- See <manref name="deb" section="5">.
- </footnote>.
- The <prgn>config</prgn> script might be run before the
- <prgn>preinst</prgn> script, and before the package is unpacked
- or any of its dependencies or pre-dependencies are satisfied.
- Therefore it must work using only the tools present in
- <em>essential</em> packages.<footnote>
+ Specification may contain the additional control information
+ files <file>config</file>
+ and <file>templates</file>. <file>config</file> is an
+ additional maintainer script used for package configuration,
+ and <file>templates</file> contains templates used for user
+ prompting. The <prgn>config</prgn> script might be run before
+ the <prgn>preinst</prgn> script and before the package is
+ unpacked or any of its dependencies or pre-dependencies are
+ satisfied. Therefore it must work using only the tools
+ present in <em>essential</em> packages.<footnote>
<package>Debconf</package> or another tool that
implements the Debian Configuration Management
Specification will also be installed, and any
<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>Optional upstream source location: <file>debian/watch</file></heading>
<p>
- This is an optional, recommended control file for the
- <tt>uscan</tt> utility which defines how to automatically
- scan ftp or http sites for newly available updates of the
- package. This is used by <url id="
- http://dehs.alioth.debian.org/"> and other Debian QA tools
- to help with quality control and maintenance of the
+ This is an optional, recommended configuration file for the
+ <tt>uscan</tt> utility which defines how to automatically scan
+ ftp or http sites for newly available updates of the
+ package. This is used
+ by <url id="http://dehs.alioth.debian.org/"> and other Debian QA
+ tools to help with quality control and maintenance of the
distribution as a whole.
</p>
</p>
<p>
- These scripts are the files <prgn>preinst</prgn>,
- <prgn>postinst</prgn>, <prgn>prerm</prgn> and
- <prgn>postrm</prgn> in the control area of the package.
- They must be proper executable files; if they are scripts
- (which is recommended), they must start with the usual
- <tt>#!</tt> convention. They should be readable and
+ These scripts are the control information
+ files <prgn>preinst</prgn>, <prgn>postinst</prgn>, <prgn>prerm</prgn>
+ and <prgn>postrm</prgn>. They must be proper executable files;
+ if they are scripts (which is recommended), they must start with
+ the usual <tt>#!</tt> convention. They should be readable and
executable by anyone, and must not be world-writable.
</p>
they exit with a zero status if everything went well.
</p>
- Additionally, packages interacting with users using
- <tt>debconf</tt> in the <prgn>postinst</prgn> script should
- install a <prgn>config</prgn> script in the control area,
- see <ref id="maintscriptprompt"> for details.
- </p>
+ <p>
+ Additionally, packages interacting with users
+ using <prgn>debconf</prgn> in the <prgn>postinst</prgn> script
+ should install a <prgn>config</prgn> script as a control
+ information file. See <ref id="maintscriptprompt"> for details.
+ </p>
<p>
When a package is upgraded a combination of the scripts from
</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>
In the <tt>Depends</tt>, <tt>Recommends</tt>,
<tt>Suggests</tt>, <tt>Pre-Depends</tt>,
<tt>Build-Depends</tt> and <tt>Build-Depends-Indep</tt>
- control file fields of the package, which declare
+ control fields of the package, which declare
dependencies on other packages, the package names listed may
also include lists of alternative package names, separated
by vertical bar (pipe) symbols <tt>|</tt>. In such a case,
<p>
This is done using the <tt>Depends</tt>, <tt>Pre-Depends</tt>,
<tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
- <tt>Breaks</tt> and <tt>Conflicts</tt> control file fields.
+ <tt>Breaks</tt> and <tt>Conflicts</tt> control fields.
<tt>Breaks</tt> is described in <ref id="breaks">, and
<tt>Conflicts</tt> is described in <ref id="conflicts">. The
rest are described below.
</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>
example, <ref id="binaries">.
</p>
+ <p>
+ Neither <tt>Breaks</tt> nor <tt>Conflicts</tt> should be used
+ unless two packages cannot be installed at the same time or
+ installing them both causes one of them to be broken or
+ unusable. Having similar functionality or performing the same
+ tasks as another package is not sufficient reason to
+ declare <tt>Breaks</tt> or <tt>Conflicts</tt> with that package.
+ </p>
+
<p>
A <tt>Conflicts</tt> entry may have an "earlier than" version
clause if the reason for the conflict is corrected in a later
<p>
A <em>virtual package</em> is one which appears in the
- <tt>Provides</tt> control file field of another package.
- The effect is as if the package(s) which provide a
- particular virtual package name had been listed by name
- everywhere the virtual package name appears. (See also <ref
- id="virtual_pkg">)
+ <tt>Provides</tt> control field of another package. The effect
+ is as if the package(s) which provide a particular virtual
+ package name had been listed by name everywhere the virtual
+ package name appears. (See also <ref id="virtual_pkg">)
</p>
<p>
<p>
Packages can declare in their control file that they should
- overwrite files in certain other packages, or completely
- replace other packages. The <tt>Replaces</tt> control file
- field has these two distinct purposes.
+ overwrite files in certain other packages, or completely replace
+ other packages. The <tt>Replaces</tt> control field has these
+ two distinct purposes.
</p>
<sect1><heading>Overwriting files in other packages</heading>
<p>
This is done using the <tt>Build-Depends</tt>,
<tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt> and
- <tt>Build-Conflicts-Indep</tt> control file fields.
+ <tt>Build-Conflicts-Indep</tt> control fields.
</p>
<p>
<p>
There is no Build-Depends-Arch; this role is essentially
met with Build-Depends. Anyone building the
- <tt>build-indep</tt> and binary-indep<tt></tt> targets is
+ <tt>build-indep</tt> and <tt>binary-indep</tt> targets is
assumed to be building the whole package, and therefore
installation of all build dependencies is required.
</p>
</p>
<p>
- Packages involving shared libraries should be split up into
- several binary packages. This section mostly deals with how
- this separation is to be accomplished; rules for files within
- the shared library packages are in <ref id="libraries"> instead.
+ This section deals only with public shared libraries: shared
+ libraries that are placed in directories searched by the dynamic
+ linker by default or which are intended to be linked against
+ normally and possibly used by other, independent packages. Shared
+ libraries that are internal to a particular package or that are
+ only loaded as dynamic modules are not covered by this section and
+ are not subject to its requirements.
</p>
- <sect id="sharedlibs-runtime">
- <heading>Run-time shared libraries</heading>
+ <p>
+ A shared library is identified by the <tt>SONAME</tt> attribute
+ stored in its dynamic section. When a binary is linked against a
+ shared library, the <tt>SONAME</tt> of the shared library is
+ recorded in the binary's <tt>NEEDED</tt> section so that the
+ dynamic linker knows that library must be loaded at runtime. The
+ shared library file's full name (which usually contains additional
+ version information not needed in the <tt>SONAME</tt>) is
+ therefore normally not referenced directly. Instead, the shared
+ library is loaded by its <tt>SONAME</tt>, which exists on the file
+ system as a symlink pointing to the full name of the shared
+ library. This symlink must be provided by the
+ package. <ref id="sharedlibs-runtime"> describes how to do this.
+ <footnote>
+ This is a convention of shared library versioning, but not a
+ requirement. Some libraries use the <tt>SONAME</tt> as the full
+ library file name instead and therefore do not need a symlink.
+ Most, however, encode additional information about
+ backwards-compatible revisions as a minor version number in the
+ file name. The <tt>SONAME</tt> itself only changes when
+ binaries linked with the earlier version of the shared library
+ may no longer work, but the filename may change with each
+ release of the library. See <ref id="sharedlibs-runtime"> for
+ more information.
+ </footnote>
+ </p>
<p>
- The run-time shared library needs to be placed in a package
- whose name changes whenever the shared object version
- changes.<footnote>
- <p>
- Since it is common place to install several versions of a
- package that just provides shared libraries, it is a
- good idea that the library package should not
- contain any extraneous non-versioned files, unless they
- happen to be in versioned directories.</p>
- </footnote>
- The most common mechanism is to place it in a package
- called
- <package><var>libraryname</var><var>soversion</var></package>,
- where <file><var>soversion</var></file> is the version number
- in the soname of the shared library<footnote>
- The soname is the shared object name: it's the thing
- that has to match exactly between building an executable
- and running it for the dynamic linker to be able run the
- program. For example, if the soname of the library is
- <file>libfoo.so.6</file>, the library package would be
- called <file>libfoo6</file>.
- </footnote>.
- Alternatively, if it would be confusing to directly append
- <var>soversion</var> to <var>libraryname</var> (e.g. because
- <var>libraryname</var> itself ends in a number), you may use
- <package><var>libraryname</var>-<var>soversion</var></package> and
- <package><var>libraryname</var>-<var>soversion</var>-dev</package>
- instead.
+ When linking a binary or another shared library against a shared
+ library, the <tt>SONAME</tt> for that shared library is not yet
+ known. Instead, the shared library is found by looking for a file
+ matching the library name with <tt>.so</tt> appended. This file
+ exists on the file system as a symlink pointing to the shared
+ library.
</p>
<p>
- If you have several shared libraries built from the same
- source tree you may lump them all together into a single
- shared library package, provided that you change all of
- their sonames at once (so that you don't get filename
- clashes if you try to install different versions of the
- combined shared libraries package).
+ Shared libraries are normally split into several binary packages.
+ The <tt>SONAME</tt> symlink is installed by the runtime shared
+ library package, and the bare <tt>.so</tt> symlink is installed in
+ the development package since it's only used when linking binaries
+ or shared libraries. However, there are some exceptions for
+ unusual shared libraries or for shared libraries that are also
+ loaded as dynamic modules by other programs.
</p>
+ <p>
+ This section is primarily concerned with how the separation of
+ shared libraries into multiple packages should be done and how
+ dependencies on and between shared library binary packages are
+ managed in Debian. <ref id="libraries"> should be read in
+ conjunction with this section and contains additional rules for
+ the files contained in the shared library packages.
+ </p>
+
+ <sect id="sharedlibs-runtime">
+ <heading>Run-time shared libraries</heading>
+
+ <p>
+ The run-time shared library must be placed in a package
+ whose name changes whenever the <tt>SONAME</tt> of the shared
+ library changes. This allows several versions of the shared
+ library to be installed at the same time, allowing installation
+ of the new version of the shared library without immediately
+ breaking binaries that depend on the old version. Normally, the
+ run-time shared library and its <tt>SONAME</tt> symlink should
+ be placed in a package named
+ <package><var>libraryname</var><var>soversion</var></package>,
+ where <var>soversion</var> is the version number in
+ the <tt>SONAME</tt> of the shared library.
+ See <ref id="shlibs"> for detailed information on how to
+ determine this version. Alternatively, if it would be confusing
+ to directly append <var>soversion</var>
+ to <var>libraryname</var> (if, for example, <var>libraryname</var>
+ itself ends in a number), you should use
+ <package><var>libraryname</var>-<var>soversion</var></package>
+ instead.
+ </p>
+
+ <p>
+ If you have several shared libraries built from the same source
+ tree, you may lump them all together into a single shared
+ library package provided that all of their <tt>SONAME</tt>s will
+ always change together. Be aware that this is not normally the
+ case, and if the <tt>SONAME</tt>s do not change together,
+ upgrading such a merged shared library package will be
+ unnecessarily difficult because of file conflicts with the old
+ version of the package. When in doubt, always split shared
+ library packages so that each binary package installs a single
+ shared library.
+ </p>
+
+ <p>
+ Every time the shared library ABI changes in a way that may
+ break binaries linked against older versions of the shared
+ library, the <tt>SONAME</tt> of the library and the
+ corresponding name for the binary package containing the runtime
+ shared library should change. Normally, this means
+ the <tt>SONAME</tt> should change any time an interface is
+ removed from the shared library or the signature of an interface
+ (the number of parameters or the types of parameters that it
+ takes, for example) is changed. This practice is vital to
+ allowing clean upgrades from older versions of the package and
+ clean transitions between the old ABI and new ABI without having
+ to upgrade every affected package simultaneously.
+ </p>
+
+ <p>
+ The <tt>SONAME</tt> and binary package name need not, and indeed
+ normally should not, change if new interfaces are added but none
+ are removed or changed, since this will not break binaries
+ linked against the old shared library. Correct versioning of
+ dependencies on the newer shared library by binaries that use
+ the new interfaces is handled via
+ the <qref id="sharedlibs-shlibdeps"><tt>shlibs</tt>
+ system</qref> or via symbols files (see
+ <manref name="deb-symbols" section="5">).
+ </p>
+
<p>
The package should install the shared libraries under
their normal names. For example, the <package>libgdbm3</package>
</p>
<p>
- The run-time library package should include the symbolic link that
- <prgn>ldconfig</prgn> would create for the shared libraries.
- For example, the <package>libgdbm3</package> package should include
- a symbolic link from <file>/usr/lib/libgdbm.so.3</file> to
+ The run-time library package should include the symbolic link for
+ the <tt>SONAME</tt> that <prgn>ldconfig</prgn> would create for
+ the shared libraries. For example,
+ the <package>libgdbm3</package> package should include a symbolic
+ link from <file>/usr/lib/libgdbm.so.3</file> to
<file>libgdbm.so.3.0.0</file>. This is needed so that the dynamic
linker (for example <prgn>ld.so</prgn> or
<prgn>ld-linux.so.*</prgn>) can find the library between the
(<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>
When packages are being built,
any <file>debian/shlibs</file> files are copied into the
- control file area of the temporary build directory and
- given the name <file>shlibs</file>. These files give
- details of any shared libraries included in the same
- package.<footnote>
+ control information file area of the temporary build
+ directory and given the name <file>shlibs</file>. These
+ files give details of any shared libraries included in the
+ same package.<footnote>
An example may help here. Let us say that the source
package <tt>foo</tt> generates two binary
packages, <tt>libfoo2</tt> and <tt>foo-runtime</tt>.
It is usual to call this file <file>debian/shlibs</file> (but if
you have multiple binary packages, you might want to call it
<file>debian/shlibs.<var>package</var></file> instead). Then
- let <file>debian/rules</file> install it in the control area:
+ let <file>debian/rules</file> install it in the control
+ information file area:
<example compact="compact">
install -m644 debian/shlibs debian/tmp/DEBIAN
</example>
install -m644 debian/shlibs.<var>package</var> debian/<var>package</var>/DEBIAN/shlibs
</example>
An alternative way of doing this is to create the
- <file>shlibs</file> file in the control area directly from
- <file>debian/rules</file> without using a <file>debian/shlibs</file>
- file at all,<footnote>
+ <file>shlibs</file> file in the control information file area
+ directly from <file>debian/rules</file> without using
+ a <file>debian/shlibs</file> file at all,<footnote>
This is what <prgn>dh_makeshlibs</prgn> in
the <package>debhelper</package> suite does. If your package
also has a udeb that provides a shared
for C files) will need to be compiled twice, for the normal
case.
</p>
+
<p>
- You must specify the gcc option <tt>-D_REENTRANT</tt>
- when building a library (either static or shared) to make
- the library compatible with LinuxThreads.
+ Libraries should be built with threading support and to be
+ thread-safe if the library supports this.
</p>
<p>
</p>
</sect>
- <sect>
+ <sect id="permissions-owners">
<heading>Permissions and owners</heading>
<p>
<p>
These two files are managed through the <prgn>dpkg</prgn>
- "alternatives" mechanism. Thus every package providing an
- editor or pager must call the
- <prgn>update-alternatives</prgn> script to register these
- programs.
+ "alternatives" mechanism. Every package providing an editor or
+ pager must call the <prgn>update-alternatives</prgn> script to
+ register as an alternative for <file>/usr/bin/editor</file>
+ or <file>/usr/bin/pager</file> as appropriate. The alternative
+ should have a slave alternative
+ for <file>/usr/share/man/man1/editor.1.gz</file>
+ or <file>/usr/share/man/man1/pager.1.gz</file> pointing to the
+ corresponding manual page.
</p>
<p>
<example compact="compact">
/usr/lib/cgi-bin/<var>cgi-bin-name</var>
</example>
- and should be referred to as
+ or a subdirectory of that directory, and should be
+ referred to as
<example compact="compact">
http://localhost/cgi-bin/<var>cgi-bin-name</var>
</example>
-
+ (possibly with a subdirectory name
+ before <var>cgi-bin-name</var>).
</item>
<item>
this so programs should not fail if <prgn>newaliases</prgn>
cannot be found. Note that because of this, all MTA
packages must have <tt>Provides</tt>, <tt>Conflicts</tt> and
- <tt>Replaces: mail-transport-agent</tt> control file
- fields.
+ <tt>Replaces: mail-transport-agent</tt> control fields.
</p>
<p>
<p>
Packages that provide an X server that, directly or
indirectly, communicates with real input and display
- hardware should declare in their control data that they
- provide the virtual package <tt>xserver</tt>.<footnote>
+ hardware should declare in their <tt>Provides</tt> control
+ field that they provide the virtual
+ package <tt>xserver</tt>.<footnote>
This implements current practice, and provides an
actual policy for usage of the <tt>xserver</tt>
virtual package which appears in the virtual packages
<p>
Packages that provide a terminal emulator for the X Window
- System which meet the criteria listed below should declare
- in their control data that they provide the virtual
- package <tt>x-terminal-emulator</tt>. They should also
- register themselves as an alternative for
+ System which meet the criteria listed below should declare in
+ their <tt>Provides</tt> control field that they provide the
+ virtual package <tt>x-terminal-emulator</tt>. They should
+ also register themselves as an alternative for
<file>/usr/bin/x-terminal-emulator</file>, with a priority of
- 20.
+ 20. That alternative should have a slave alternative
+ for <file>/usr/share/man/man1/x-terminal-emulator.1.gz</file>
+ pointing to the corresponding manual page.
</p>
<p>
<p>
Packages that provide a window manager should declare in
- their control data that they provide the virtual package
- <tt>x-window-manager</tt>. They should also register
- themselves as an alternative for
+ their <tt>Provides</tt> control field that they provide the
+ virtual package <tt>x-window-manager</tt>. They should also
+ register themselves as an alternative for
<file>/usr/bin/x-window-manager</file>, with a priority
calculated as follows:
<list compact="compact">
configuration, add 10 points; otherwise add none.
</item>
</list>
+ That alternative should have a slave alternative
+ for <file>/usr/share/man/man1/x-window-manager.1.gz</file>
+ pointing to the corresponding manual page.
</p>
</sect1>
<item>
Font packages must declare a dependency on
- <tt>xfonts-utils</tt> in their control
- data.
+ <tt>xfonts-utils</tt> in their <tt>Depends</tt>
+ or <tt>Pre-Depends</tt> control field.
</item>
<item>
<p>
It is possible to put other files in the package control
- area, but this is not generally a good idea (though they
- will largely be ignored).
+ information file area, but this is not generally a good idea
+ (though they will largely be ignored).
</p>
<p>
- Here is a brief list of the control info files supported by
- <prgn>dpkg</prgn> and a summary of what they're used for.
+ Here is a brief list of the control information files supported
+
by <prgn>dpkg</prgn> and a summary of what they're used for.
</p>
<p>
<tag><tt>Package_Revision</tt></tag>
<item>
The Debian revision part of the package version was
- at one point in a separate control file field. This
+ at one point in a separate control field. This
field went through several names.
</item>
</heading>
<p>
- A package may contain a control area file called
+ A package may contain a control information file called
<tt>conffiles</tt>. This file should be a list of filenames
of configuration files needing automatic handling, separated
by newlines. The filenames should be absolute pathnames,
projects / debian / debian-policy.git / blobdiff