<!-- include version information so we don't have to hard code it
within the document -->
<!entity % versiondata SYSTEM "version.ent"> %versiondata;
+<!-- current Debian changes file format -->
+<!entity changesversion "1.8">
]>
<debiandoc>
<item>
must not require a package outside of <em>main</em>
for compilation or execution (thus, the package must
- not declare a "Depends", "Recommends", or
- "Build-Depends" relationship on a non-<em>main</em>
- package),
+ 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),
</item>
<item>
must not be so buggy that we refuse to support them,
</p>
<p>
- Sometimes, a package requires another package to be installed
- <em>and</em> configured before it can be installed. In this
+ 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.
</p>
The <tt>build</tt> target should perform all the
configuration and compilation of the package.
If a package has an interactive pre-build
- configuration routine, the Debianized source package
+ configuration routine, the Debian source package
must either be built after this has taken place (so
that the binary package can be built without rerunning
the configuration) or the configuration routine
These fields are used by <prgn>dpkg-gencontrol</prgn> to
generate control files for binary packages (see below), by
<prgn>dpkg-genchanges</prgn> to generate the
- <tt>.changes</tt> file to accompany the upload, and by
+ <file>.changes</file> file to accompany the upload, and by
<prgn>dpkg-source</prgn> when it creates the
<file>.dsc</file> source control file as part of a source
archive. Many fields are permitted to span multiple lines in
<p>
The <file>DEBIAN/control</file> file contains the most vital
- (and version-dependent) information about a binary package.
+ (and version-dependent) information about a binary package. It
+ consists of a single paragraph.
</p>
<p>
<heading>Debian source control files -- <tt>.dsc</tt></heading>
<p>
- This file contains a series of fields, identified and
- separated just like the fields in the control file of
- a binary package. The fields are listed below; their
- syntax is described above, in <ref id="pkg-controlfields">.
+ This file consists of a single paragraph, possibly surrounded by
+ a PGP signature. The fields of that paragraph are listed below.
+ Their syntax is described above, in <ref id="pkg-controlfields">.
<list compact="compact">
<item><qref id="f-Format"><tt>Format</tt></qref> (mandatory)</item>
<heading>Debian changes files -- <file>.changes</file></heading>
<p>
- The .changes files are used by the Debian archive maintenance
- software to process updates to packages. They contain one
- paragraph which contains information from the
- <tt>debian/control</tt> file and other data about the
- source package gathered via <tt>debian/changelog</tt>
- and <tt>debian/rules</tt>.
+ The <file>.changes</file> files are used by the Debian archive
+ maintenance software to process updates to packages. They
+ consist of a single paragraph, possibly surrounded by a PGP
+ signature. That paragraph contains information from the
+ <file>debian/control</file> file and other data about the
+ source package gathered via <file>debian/changelog</file>
+ and <file>debian/rules</file>.
+ </p>
+
+ <p>
+ <file>.changes</file> files have a format version that is
+ incremented whenever the documented fields or their meaning
+ change. This document describes format &changesversion;.
</p>
<p>
It is optional; if it isn't present then the
<var>upstream_version</var> may not contain a hyphen.
This format represents the case where a piece of
- software was written specifically to be turned into a
- Debian package, and so there is only one "debianisation"
- of it and therefore no revision indication is required.
+ software was written specifically to be a Debian
+ package, where the Debian package source must always
+ be identical to the pristine source and therefore no
+ revision indication is required.
</p>
<p>
<heading><tt>Format</tt></heading>
<p>
- This field specifies a format revision for the file.
- The most current format described in the Policy Manual
- is version <strong>1.5</strong>. The syntax of the
- format value is the same as that of a package version
- number except that no epoch or Debian revision is allowed
- - see <ref id="f-Version">.
+ In <qref id="debianchangesfiles"><file>.changes</file></qref>
+ files, this field declares the format version of that file.
+ The syntax of the field value is the same as that of
+ a <qref id="f-Version">package version number</qref> except
+ that no epoch or Debian revision is allowed. The format
+ described in this document is <tt>&changesversion;</tt>.
+ </p>
+
+ <p>
+ In <qref id="debiansourcecontrolfiles"><file>.dsc</file>
+ Debian source control</qref> files, this field declares the
+ format of the source package. The field value is used by
+ programs acting on a source package to interpret the list of
+ files in the source package and determine how to unpack it.
+ The syntax of the field value is a numeric major revision, a
+ period, a numeric minor revision, and then an optional subtype
+ after whitespace, which if specified is an alphanumeric word
+ in parentheses. The subtype is optional in the syntax but may
+ be mandatory for particular source format revisions.
+ <footnote>
+ The source formats currently supported by the Debian archive
+ software are <tt>1.0</tt>, <tt>3.0 (native)</tt>,
+ and <tt>3.0 (quilt)</tt>.
+ </footnote>
</p>
</sect1>
must match the list of files in the <tt>Files</tt> field.
</p>
</sect1>
-
</sect>
<sect>
<p>
Broadly speaking the <prgn>preinst</prgn> is called before
- (a particular version of) a package is installed, and the
+ (a particular version of) a package is unpacked, and the
<prgn>postinst</prgn> afterwards; the <prgn>prerm</prgn>
before (a version of) a package is removed and the
<prgn>postrm</prgn> afterwards.
behavior which, though deterministic, is hard for the
system administrator to understand. It can easily
lead to "missing" programs if, for example, a package
- is installed which overwrites a file from another
+ is unpacked which overwrites a file from another
package, and is then removed again.<footnote>
Part of the problem is due to what is arguably a
bug in <prgn>dpkg</prgn>.
If there was a conflicting package we go and do the
removal actions (described below), starting with the
removal of the conflicting package's files (any that
- are also in the package being installed have already
+ are also in the package being unpacked have already
been removed from the conflicting package's file list,
and so do not get removed now).
</item>
</p>
<p>
- For this reason packages in an installation run are usually
- all unpacked first and all configured later; this gives
- later versions of packages with dependencies on later
- versions of other packages the opportunity to have their
- dependencies satisfied.
+ 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.
</p>
- <p>
- In case of circular dependencies, since installation or
- removal order honoring the dependency order can't be
- established, dependency loops are broken at some point
- (based on rules below), and some packages may not be able to
- rely on their dependencies being present when being
- installed 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, so as to ensure that
- all postinst scripts run with the dependencies properly
- configured if this is possible. Otherwise the breaking point
- is arbitrary.
- </p>
-
<p>
- The <tt>Depends</tt> field thus allows package maintainers
- to impose an order in which packages should be configured.
+ If there is a circular dependency among packages being installed
+ or removed, installation or removal order honoring the
+ dependency order is impossible, requiring the dependency loop be
+ 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.
</p>
<p>
This declares an absolute dependency. A package will
not be configured unless all of the packages listed in
its <tt>Depends</tt> field have been correctly
- configured.
+ configured (unless there is a circular dependency as
+ described above).
</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. Note, however, that the
- <prgn>postrm</prgn> cannot rely on any non-essential
- packages to be present during the <tt>purge</tt>
- phase.
+ 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>).
</item>
<tag><tt>Recommends</tt></tag>
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.
+ 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
+ <tt>Pre-Depends</tt>, the installation will be aborted.
+ </p>
+
+ <p>
+ <tt>Pre-Depends</tt> are also required if the
+ <prgn>preinst</prgn> script depends on the named package.
+ It is best to avoid this situation if possible.
</p>
<p>
installation would hamper the ability of the system to
continue with any upgrade that might be in progress.
</p>
-
- <p>
- <tt>Pre-Depends</tt> are also required if the
- <prgn>preinst</prgn> script depends on the named
- package. It is best to avoid this situation if
- possible.
- </p>
</item>
</taglist>
</p>
<p>
When one binary package declares that it breaks another,
<prgn>dpkg</prgn> will refuse to allow the package which
- declares <tt>Breaks</tt> be installed unless the broken
+ declares <tt>Breaks</tt> be unpacked unless the broken
package is deconfigured first, and it will refuse to
allow the broken package to be reconfigured.
</p>
version of an (implicit or explicit) dependency which violates
an assumption or reveals a bug in earlier versions of the broken
package, or which takes over a file from earlier versions of the
- broken package. This use of <tt>Breaks</tt> will inform
- higher-level package management tools that broken package must
- be upgraded before the new one.
+ package named in <tt>Breaks</tt>. This use of <tt>Breaks</tt>
+ will inform higher-level package management tools that the
+ broken package must be upgraded before the new one.
</p>
<p>
<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 installed on the system at the
+ 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
</p>
<p>
- If one package is to be installed, the other must be removed
- first. If the package being installed is marked as replacing
+ If one package is to be unpacked, the other must be removed
+ first. If the package being unpacked is marked as replacing
(see <ref id="replaces">, but note that <tt>Breaks</tt> should
normally be used in this case) the one on the system, or the one
on the system is marked as deselected, or both packages are
<tt>Conflicts</tt> should be used
<list>
<item>when two packages provide the same file and will
- continue to do so (but be aware that this is often an error
- that should be fixed rather than using <tt>Conflicts</tt> --
- see, for example, <ref id="binaries">),</item>
+ continue to do so,</item>
<item>in conjunction with <tt>Provides</tt> when only one
package providing a given virtual facility may be installed
at a time (see <ref id="virtual">),</item>
that must prevent both packages from being unpacked at the
same time, not just configured.</item>
</list>
+ Be aware that adding <tt>Conflicts</tt> is normally not the best
+ solution when two packages provide the same files. Depending on
+ the reason for that conflict, using alternatives or renaming the
+ files is often a better approach. See, for
+ example, <ref id="binaries">.
</p>
<p>
breakage). In other words, if a version number is specified,
this is a request to ignore all <tt>Provides</tt> for that
package name and consider only real packages. The package
- manager will assume that a package which package which provides
- that virtual package is not of the "right" version.
- A <tt>Provides</tt> field may not contain version numbers, and
- the version number of the concrete package which provides a
- particular virtual package will not be considered when
- considering a dependency on or conflict with the virtual package
- name.<footnote>
+ manager will assume that a package providing that virtual
+ package is not of the "right" version. A <tt>Provides</tt>
+ field may not contain version numbers, and the version number of
+ the concrete package which provides a particular virtual package
+ will not be considered when considering a dependency on or
+ conflict with the virtual package name.<footnote>
It is possible that a future release of <prgn>dpkg</prgn> may
add the ability to specify a version number for each virtual
package it provides. This feature is not yet present,
package and will be taken over by the new package.
Normally, <tt>Breaks</tt> should be used in conjunction
with <tt>Replaces</tt>.<footnote>
- To see why <tt>Breaks</tt> is required in addition
- to <tt>Provides</tt>, consider the
- case of a file in the package <package>foo</package> being
-
taken over by the package <package>foo-data</package>.
+ To see why <tt>Breaks</tt> is normally needed in addition
+ to <tt>Replaces</tt>, consider the case of a file in the
+ package <package>foo</package> being taken over by the
+ package <package>foo-data</package>.
<tt>Replaces</tt> will allow <package>foo-data</package> to
be installed and take over that file. However,
without <tt>Breaks</tt>, nothing
<example compact="compact">
Replaces: foo (<< 1.2-3)
Breaks: foo (<< 1.2-3)
- </example compact="compact">
+ </example>
in its control file. The new version of the
package <package>foo</package> would normally have the field
- <example>
+ <example compact="compact">
Depends: foo-data (>= 1.2-3)
</example>
(or possibly <tt>Recommends</tt> or even <tt>Suggests</tt> if
Conflicts: mail-transport-agent
Replaces: mail-transport-agent
</example>
- ensuring that only one MTA can be installed at any one
+ ensuring that only one MTA can be unpacked at any one
time. See <ref id="virtual"> for more information about this
example.
</sect1>
<footnote>
<p>
During install or upgrade, the preinst is called before
- the new files are installed, so calling "ldconfig" is
+ the new files are unpacked, so calling "ldconfig" is
pointless. The preinst of an existing package can also be
called if an upgrade fails. However, this happens during
the critical time when a shared libs may exist on-disk
<ref id="conflicts">) to ensure that the user only installs one
development version at a time (as different development versions are
likely to have the same header files in them, which would cause a
- filename clash if both were installed).
+ filename clash if both were unpacked).
</p>
<p>
<p>
Packages distributed under the Apache license (version 2.0), the
- Artistic license, the GNU GPL (version 2 or 3), the GNU LGPL
- (versions 2, 2.1, or 3), and the GNU FDL (versions 1.2 or 1.3)
- should refer to the corresponding files
+ Artistic license, the GNU GPL (versions 1, 2, or 3), the GNU
+ LGPL (versions 2, 2.1, or 3), and the GNU FDL (versions 1.2 or
+ 1.3) should refer to the corresponding files
under <file>/usr/share/common-licenses</file>,<footnote>
<p>
In particular,
<file>/usr/share/common-licenses/Apache-2.0</file>,
<file>/usr/share/common-licenses/Artistic</file>,
+ <file>/usr/share/common-licenses/GPL-1</file>,
<file>/usr/share/common-licenses/GPL-2</file>,
<file>/usr/share/common-licenses/GPL-3</file>,
<file>/usr/share/common-licenses/LGPL-2</file>,
<p>
The <prgn>DEBIAN</prgn> directory will not appear in the
file system archive of the package, and so won't be installed
- by <prgn>dpkg</prgn> when the package is installed.
+ by <prgn>dpkg</prgn> when the package is unpacked.
</p>
<p>
</sect>
<sect id="pkg-sourcetree">
- <heading>The Debianised source tree</heading>
+ <heading>The Debian package source tree</heading>
<p>
The source archive scheme described later is intended to
- allow a Debianised source tree with some associated control
- information to be reproduced and transported easily. The
- Debianised source tree is a version of the original program
- with certain files added for the benefit of the
- Debianisation process, and with any other changes required
+ allow a Debian package source tree with some associated
+ control information to be reproduced and transported easily.
+ The Debian package source tree is a version of the original
+ program with certain files added for the benefit of the
+ packaging process, and with any other changes required
made to the rest of the source code and installation
scripts.
</p>
<p>
The extra files created for Debian are in the subdirectory
- <file>debian</file> of the top level of the Debianised source
- tree. They are described below.
+ <file>debian</file> of the top level of the Debian package
+ source tree. They are described below.
</p>
<sect1 id="pkg-debianrules">
</item>
<tag>
- Debianisation diff -
+ Debian package diff -
<file>
<var>package</var>_<var>upstream_version-revision</var>.diff.gz
</file>
<item><p>Apply the diff using <tt>patch -p0</tt>.</p>
</item>
<item><p>Untar the tarfile again if you want a copy of the original
- source code alongside the Debianised version.</p>
+ source code alongside the Debian version.</p>
</item>
</enumlist>
<p>
The source packaging tools manage the changes between the
- original and Debian
ised source using <prgn>diff</prgn> and
+ original and Debian source using <prgn>diff</prgn> and
<prgn>patch</prgn>. Turning the original source tree as
- included in the <file>.orig.tar.gz</file> into the debianised
- source must not involve any changes which cannot be
+ included in the <file>.orig.tar.gz</file> into the Debian
+ package source must not involve any changes which cannot be
handled by these tools. Problematic changes which cause
<prgn>dpkg-source</prgn> to halt with an error when
building the source package are:
projects / debian / debian-policy.git / blobdiff