<tt>/usr/share/common-licenses/GPL</tt> in the Debian GNU/Linux
distribution or on the World Wide Web at
<url id="http://www.gnu.org/copyleft/gpl.html"
- name="The GNU General Public Licence">. You can also obtain it by writing to the
- Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- Boston, MA 02111-1307, USA.
+ name="The GNU General Public Licence">. You can also
+ obtain it by writing to the Free Software Foundation, Inc.,
+ 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
</p>
</copyright>
</titlepag>
interfaces not changing, and the package
management software authors need to ensure
compatibility with these interface
- definitions. (Control file and and changelog file
+ definitions. (Control file and changelog file
formats are examples.)
</p>
</item>
<em>may</em>, and the adjectives <em>required</em>,
<em>recommended</em> and <em>optional</em>, are used to
distinguish the significance of the various guidelines in
- this policy document. Packages that do not conform the the
+ this policy document. Packages that do not conform to the
guidelines denoted by <em>must</em> (or <em>required</em>)
will generally not be considered acceptable for the Debian
distribution. Non-conformance with guidelines denoted by
<p>
Every package must be accompanied by a verbatim copy of
its copyright and distribution license in the file
- <tt>/usr/share/doc/<em><package-name></em>/copyright</tt>
+ <tt>/usr/share/doc/<em><package></em>/copyright</tt>
(see <ref id="copyrightfile"> for further details).
</p>
<p>
<item>
<p>
These packages provide a reasonably small but not too
- limited character-mode system. This is what will
- install by default if the user doesn't select anything
+ limited character-mode system. This is what will be
+ installed by default if the user doesn't select anything
else. It doesn't include many large applications, but
it does include Emacs (this is more of a piece of
infrastructure than an application) and a reasonable
<sect>
<heading>Source packages</heading>
- <sect1>
+ <sect1 id="standardsversion">
<heading>Standards conformance</heading>
<p>
<p>
Many of the tools in the package management suite manipulate
- data in a common format, known as control files. Binary and
- source packages have control data as do the <tt>.changes</tt>
- files which control the installation of uploaded files, and
- <prgn>dpkg</prgn>'s internal databases are in a similar
+ data represented in a common format, known as <em>control
+ data</em>. The data is often stored in <em>control
+ files</em>. Binary and source packages have control files,
+ and the <tt>.changes</tt> files which control the installation
+ of uploaded files are also in control file format.
+ <prgn>Dpkg</prgn>'s internal databases are in a similar
format.
</p>
- <sect><heading>Syntax of control files</heading>
+ <sect id="controlsyntax"><heading>Syntax of control files</heading>
<p>
- A file consists of one or more paragraphs of fields. The
- paragraphs are separated by blank lines. Some control files
- only allow one paragraph; others allow several, in which
- case each paragraph often refers to a different package.
+ A control file consists of one or more paragraphs of fields.
+ The paragraphs are separated by blank lines. Some control
+ files allow only one paragraph; others allow several, in
+ which case each paragraph usually refers to a different
+ package. (For example, in source packages, the first
+ paragraph refers to the source package, and later paragraphs
+ refer to binary packages generated from the source.)
</p>
<p>
- Each paragraph is a series of fields and values; each field
- consists of a name, followed by a colon and the value. It
- ends at the end of the line. Horizontal whitespace (spaces
- and tabs) may occur immediately before or after the value
- and is ignored there; it is conventional to put a single
- space after the colon.
+ Each paragraph consists of a series of data fields; each
+ field consists of the field name, followed by a colon and
+ then the data/value associated with that field. It ends at
+ the end of the line. Horizontal whitespace (spaces and
+ tabs) may occur immediately before or after the value and is
+ ignored there; it is conventional to put a single space
+ after the colon. For example, a field might be:
+ <example>
+ Package: libc6
+ </example>
+ the field name is <tt>Package</tt> and the field value
+ <tt>libc6</tt>.
</p>
<p>
<p>
Except where otherwise stated only a single line of data is
allowed and whitespace is not significant in a field body.
- Whitespace may never appear inside names (of packages,
- architectures, files or anything else), version numbers or
- in between the characters of multi-character version
+ Whitespace must not appear inside names (of packages,
+ architectures, files or anything else) or version numbers,
+ or between the characters of multi-character version
relationships.
</p>
would mean a new paragraph.
</p>
- <p>
- It is important to note that there are several fields which
- are optional as far as <prgn>dpkg</prgn> and the related
- tools are concerned, but which must appear in every Debian
- package, or whose omission may cause problems. When writing
- the control files for Debian packages you <em>must</em> read
- the Debian policy manual in conjunction with the details
- below and the list of fields for the particular file.</p>
</sect>
<sect><heading>List of fields</heading>
<p>
This list here is not supposed to be exhaustive. Most fields
- are dealt with elsewhere in this document and in the
- dpkg documentation.
+ are dealt with elsewhere in this document.
</p>
<sect1 id="f-Package"><heading><tt>Package</tt>
</heading>
<p>
They must be at least two characters long and must start
- with an alphanumeric character. The use of lowercase
- package names is strongly recommended unless the package
- you're building (or referring to, in other fields) is
- already using uppercase.</p>
+ with an alphanumeric character and not be all digits. The
+ use of lowercase package names is strongly recommended
+ unless the package you're building (or referring to, in
+ other fields) is already using uppercase.</p>
</sect1>
<sect1 id="f-Version"><heading><tt>Version</tt>
complies. This is updated manually when editing the
source package to conform to newer standards; it can
sometimes be used to tell when a package needs attention.
+ Its format is described above; see
+ <ref id="standardsversion">.
</p>
-
- <p>
- Its format is the same as that of a version number except
- that no epoch or Debian revision is allowed - see <ref
- id="versions">.</p>
</sect1>
In a <tt>.changes</tt> file or parsed changelog output
this contains the (space-separated) name(s) of the
distribution(s) where this version of the package should
- be or was installed. Distribution names follow the rules
- for package names. (See <ref id="f-Package">).
- </p>
-
- <p>
+ be installed. Valid distributions are determined by the
+ archive maintainers.
<footnote>
- Current distribution values are:
+ Current distribution names are:
<taglist>
<tag><em>stable</em></tag>
<item>
<p>
This is the current `released' version of Debian
- GNU/Linux. Once the
- distribution is <em>stable</em> only major bug fixes
- are allowed. When changes are made to this
- distribution, the release number is increased
- (for example: 1.2r1 becomes 1.2r2 then 1.2r3, etc).
+ GNU/Linux. Once the distribution is
+ <em>stable</em> only security fixes and other
+ major bug fixes are allowed. When changes are
+ made to this distribution, the release number is
+ increased (for example: 2.2r1 becomes 2.2r2 then
+ 2.2r3, etc).
</p>
</item>
</p>
</item>
+ <tag><em>testing</em></tag>
+ <item>
+ <p>
+ This distribution value refers to the
+ <em>testing</em> part of the Debian distribution
+ tree. It receives its packages from the
+ unstable distribution after a short time lag to
+ ensure that there are no major issues with the
+ unstable packages. It is less prone to breakage
+ than unstable, but still risky. It is not
+ possible to upload packages directly to
+ <em>testing</em>.
+ </p>
+ </item>
+
<tag><em>frozen</em></tag>
<item>
<p>
- From time to time, the <em>unstable</em>
+ From time to time, the <em>frozen</em>
distribution enters a state of `code-freeze' in
anticipation of release as a <em>stable</em>
version. During this period of testing only
fixes for existing or newly-discovered bugs will
- be allowed.
+ be allowed. The exact details of this stage are
+ determined by the Release Manager.
</p>
</item>
<tag><em>experimental</em></tag>
<item>
<p>
- The packages with this distribution value are deemed
- by their maintainers to be high risk. Oftentimes they
- represent early beta or developmental packages from
- various sources that the maintainers want people to
- try, but are not ready to be a part of the other parts
- of the Debian distribution tree. Download at your own
+ The packages with this distribution value are
+ deemed by their maintainers to be high
+ risk. Oftentimes they represent early beta or
+ developmental packages from various sources that
+ the maintainers want people to try, but are not
+ ready to be a part of the other parts of the
+ Debian distribution tree. Download at your own
risk.
</p>
</item>
</taglist>
- There are several sections in each
- distribution. Currently, these sections are:
-
- <taglist>
- <tag><em>main</em></tag>
- <item>
- <p>
- The packages in this section are those in the
- main Debian distribution. They are all free
- (according to the Debian free software
- guidelines) and meet any other criteria for
- inclusion described in this manual.</p>
- </item>
- <tag><em>contrib</em></tag>
- <item>
- <p>
- The packages in this section do not meet the
- criteria for inclusion in the main Debian
- distribution as defined by this manual, but are
- otherwise free, as defined by the Debian free
- software guidelines.</p>
- </item>
-
- <tag><em>non-free</em></tag>
- <item>
- <p>
- Packages in <em>non-free</em> do not meet the
- criteria of free software, as defined by the
- Debian free software guidelines. Again, use your
- best judgment in downloading from this
- Distribution.</p>
- </item>
-
- </taglist> You should list <em>all</em> distributions that
- the package should be installed into. Except in unusual
- circumstances, installations to <em>stable</em> should also
- go into <em>frozen</em> (if it exists) and
- <em>unstable</em>. Likewise, installations into
- <em>frozen</em> should also go into <em>unstable</em>.
+ You should list <em>all</em> distributions that the
+ package should be installed into.
</footnote>
</p>
</sect1>
</sect>
</chapt>
- <chapt id="versions"><heading>Version numbering </heading>
+ <chapt id="versions"><heading>Version numbering</heading>
<p>
- Every package has a version number, in its <tt>Version</tt>
- control file field.
+ Every package has a version number recorded in its
+ <tt>Version</tt> control file field.
</p>
<p>
<p>
The version number format is:
- &lsqb<var>epoch</var><tt>:</tt>]<var>upstream-version</var>[<tt>-</tt><var>debian-revision</var>]
+ &lsqb<var>epoch</var><tt>:</tt>]<var>upstream_version</var>[<tt>-</tt><var>debian_revision</var>]
</p>
<p>
<p>
This is a single (generally small) unsigned integer. It
may be omitted, in which case zero is assumed. If it is
- omitted then the <var>upstream-version</var> may not
+ omitted then the <var>upstream_version</var> may not
contain any colons.
</p>
</item>
- <tag><var>upstream-version</var></tag>
+ <tag><var>upstream_version</var></tag>
<item>
<p>
- This is the main part of the version. It is usually the
- version number of the original (`upstream') package from
- which the <tt>.deb</tt> file has been made, if this is
- applicable. Usually this will be in the same format as
- that specified by the upstream author(s); however, it
- may need to be reformatted to fit into the package
- management system's format and comparison scheme.
+ This is the main part of the version number. It is
+ usually the version number of the original (`upstream')
+ package from which the <tt>.deb</tt> file has been made,
+ if this is applicable. Usually this will be in the same
+ format as that specified by the upstream author(s);
+ however, it may need to be reformatted to fit into the
+ package management system's format and comparison
+ scheme.
</p>
<p>
The comparison behavior of the package management system
- with respect to the <var>upstream-version</var> is
- described below. The <var>upstream-version</var>
+ with respect to the <var>upstream_version</var> is
+ described below. The <var>upstream_version</var>
portion of the version number is mandatory.
</p>
<p>
- The <var>upstream-version</var> may contain only
- alphanumerics and the characters <tt>.</tt> <tt>+</tt>
- <tt>-</tt> <tt>:</tt> (full stop, plus, hyphen, colon)
- and should start with a digit. If there is no
- <var>debian-revision</var> then hyphens are not allowed;
+ The <var>upstream_version</var> may contain only
+ alphanumerics
+ <footnote>
+ <p>Alphanumerics are <tt>A-Za-z0-9</tt> only.</p>
+ </footnote>
+ and the characters <tt>.</tt> <tt>+</tt> <tt>-</tt>
+ <tt>:</tt> (full stop, plus, hyphen, colon) and should
+ start with a digit. If there is no
+ <var>debian_revision</var> then hyphens are not allowed;
if there is no <var>epoch</var> then colons are not
allowed.</p>
</item>
- <tag><var>debian-revision</var></tag>
+ <tag><var>debian_revision</var></tag>
<item>
<p>
- This part of the version represents the version of the
- modifications that were made to the package to make it a
- Debian binary package. It is in the same format as the
- <var>upstream-version</var> and is compared in the same
- way.
+ This part of the version number specifies the version of
+ the Debian package based on the upstream version. It
+ may contain only alphanumerics and the characters
+ <tt>+</tt> and <tt>.</tt> (plus and full stop) and is
+ compared in the same way as the
+ <var>upstream_version</var> is.
</p>
<p>
It is optional; if it isn't present then the
- <var>upstream-version</var> may not contain a hyphen.
+ <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 binary package, and so there is only one
- `debianization' of it and therefore no revision
- indication is required.
+ Debian package, and so there is only one `debianization'
+ of it and therefore no revision indication is required.
</p>
<p>
It is conventional to restart the
- <var>debian-revision</var> at <tt>1</tt> each time the
- <var>upstream-version</var> is increased.
+ <var>debian_revision</var> at <tt>1</tt> each time the
+ <var>upstream_version</var> is increased.
</p>
<p>
- The package management system will break the
- <var>upstream-version</var> and
- <var>debian-revision</var> apart at the last hyphen in
- the string. The absence of a <var>debian-revision</var>
- compares earlier than the presence of one (but note that
- the <var>debian-revision</var> is the least significant
- part of the version number).
- </p>
-
- <p>
- The <var>debian-revision</var> may contain only
- alphanumerics and the characters <tt>+</tt> and
- <tt>.</tt> (plus and full stop).
+ The package management system will break the version
+ number apart at the last hyphen in the string (if there
+ is one) to determine the <var>upstream_version</var> and
+ <var>debian_revision</var>. The absence of a
+ <var>debian_revision</var> compares earlier than the
+ presence of one (but note that the
+ <var>debian_revision</var> is the least significant part
+ of the version number).
</p>
</item>
</taglist>
- The <var>upstream-version</var> and <var>debian-revision</var>
+ The <var>upstream_version</var> and <var>debian_revision</var>
parts are compared by the package management system using the
same algorithm:
</p>
</p>
<p>
- These two steps are repeated (chopping initial non-digit
- strings and initial digit strings off from the start) until a
+ These two steps (comparing and removing initial non-digit
+ strings and initial digit strings) are repeated until a
difference is found or both strings are exhausted.
</p>
<p>
Note that the purpose of epochs is to allow us to leave behind
mistakes in version numbering, and to cope with situations
- where the version numbering changes. It is <em>not</em> there
- to cope with version numbers containing strings of letters
- which the package management system cannot interpret (such as
- <tt>ALPHA</tt> or <tt>pre-</tt>), or with silly orderings (the
- author of this manual has heard of a package whose versions
- went <tt>1.1</tt>, <tt>1.2</tt>, <tt>1.3</tt>, <tt>1</tt>,
- <tt>2.1</tt>, <tt>2.2</tt>, <tt>2</tt> and so forth).
+ where the version numbering scheme changes. It is
+ <em>not</em> intended to cope with version numbers containing
+ strings of letters which the package management system cannot
+ interpret (such as <tt>ALPHA</tt> or <tt>pre-</tt>), or with
+ silly orderings (the author of this manual has heard of a
+ package whose versions went <tt>1.1</tt>, <tt>1.2</tt>,
+ <tt>1.3</tt>, <tt>1</tt>, <tt>2.1</tt>, <tt>2.2</tt>,
+ <tt>2</tt> and so forth).
</p>
<p>
too.</p>
<p>
- Note, that other version formats based on dates which are
+ Note that other version formats based on dates which are
parsed correctly by the package management system should
<em>not</em> be changed.</p>
<sect id="timestamps"><heading>Time Stamps</heading>
<p>
- Maintainers are encouraged to preserve the modification
- times of the upstream source files in a package, as far as
- is reasonably possible. Even though this is optional, this
- is still a good idea.
+ Maintainers should preserve the modification times of the
+ upstream source files in a package, as far as is reasonably
+ possible.
<footnote>
<p>
The rationale is that there is some information conveyed
</sect>
<sect id="debianrules"><heading><tt>debian/rules</tt> - the
- main building script </heading>
+ main building script</heading>
<p>
This file must be an executable makefile, and contains the
package-specific recipes for compiling the package and
- building binary package(s) out of the source.
+ building binary package(s) from the source.
</p>
<p>
Since an interactive <tt>debian/rules</tt> script makes it
impossible to auto-compile that package and also makes it
hard for other people to reproduce the same binary
- package, all <strong>required targets</strong> MUST be
+ package, all <em>required targets</em> MUST be
non-interactive. At a minimum, required targets are the
ones called by <prgn>dpkg-buildpackage</prgn>, namely,
<em>clean</em>, <em>binary</em>, <em>binary-arch</em>,
</p>
<p>
- The targets which must be present are:
+ The required and optional targets are as follows:
<taglist>
<tag><tt>build</tt></tag>
<item>
<p>
- This should perform all non-interactive
- configuration and compilation of the package. If a
- package has an interactive pre-build configuration
- routine, the Debianised source package should be
- built after this has taken place, so that it can be
- built without rerunning the configuration.
+ This should perform all non-interactive configuration
+ and compilation of the package. If a package has an
+ interactive pre-build configuration routine, the
+ Debianized 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 modified to become
+ non-interactive. (The latter is preferable if there
+ are architecture-specific features detected by the
+ configuration routine.)
</p>
<p>
</p>
<p>
- The <prgn>build</prgn> target may need to run
- <prgn>clean</prgn> first - see below.
+ The <prgn>build</prgn> target may need to run the
+ <prgn>clean</prgn> target first - see below.
</p>
<p>
- When a package has a configuration routine that
- takes a long time, or when the makefiles are poorly
- designed, or when <prgn>build</prgn> needs to run
- <prgn>clean</prgn> first, it is a good idea to
+ When a package has a configuration and build routine
+ which takes a long time, or when the makefiles are
+ poorly designed, or when <prgn>build</prgn> needs to
+
run <prgn>clean</prgn> first, it is a good idea to
<tt>touch build</tt> when the build process is
complete. This will ensure that if <tt>debian/rules
- build</tt> is run again it will not rebuild the
- whole program.
+ build</tt> is run again it will not rebuild the whole
+ program.
+ <footnote>
+ <p>
+ Another common way to do this is for <prgn>build</prgn>
+ to depend on <prgn>build-stamp</prgn> and to do
+ nothing else, and for the <prgn>build-stamp</prgn>
+ target to do the building and to <tt>touch
+ build-stamp</tt> on completion. This is
+ especially useful if the build routine creates a
+ file or directory called <tt>build</tt>; in such a
+ case, <prgn>build</prgn> will need to be listed as
+ a phony target (i.e., as a dependency of the
+ <tt>.PHONY</tt> target). See the documentation of
+ <prgn>make</prgn> for more information on phony
+ targets.
+ </p>
+ </footnote>
</p>
</item>
<item>
<p>
The <prgn>binary</prgn> target must be all that is
- necessary for the user to build the binary
- package. All these targets are required to be
- non-interactive. It is split into two parts:
- <prgn>binary-arch</prgn> builds the packages' output
- files which are specific to a particular
+ necessary for the user to build the binary package(s)
+ produced from this source package. All of these
+ targets are required to be non-interactive. It is
+ split into two parts: <prgn>binary-arch</prgn> builds
+ the binary packages which are specific to a particular
architecture, and <prgn>binary-indep</prgn> builds
those which are not.
</p>
</p>
<p>
- Both <prgn>binary-*</prgn> targets should depend on
+ Each <prgn>binary-*</prgn> target should depend on
the <prgn>build</prgn> target, above, so that the
package is built if it has not been already. It
should then create the relevant binary package(s),
</p>
<p>
- If one of the <prgn>binary-*</prgn> targets has
- nothing to do (this will be always be the case if
- the source generates only a single binary package,
- whether architecture-dependent or not) it
- <em>must</em> still exist, and must always
- succeed.
+ Both the <prgn>binary-arch</prgn> and
+ <prgn>binary-indep</prgn> targets <em>must</em> exist.
+ If one of them has nothing to do (which will always be
+ the case if the source generates only a single binary
+ package, whether architecture-dependent or not), it
+ must still exist and must always succeed.
</p>
<p>
The <prgn>binary</prgn> targets must be invoked as
root.
+ <footnote>
+ <p>
+ The <prgn>fakeroot</prgn> package often allows one
+ to build a package correctly even without being
+ root.
+ </p>
+ </footnote>
</p>
</item>
<item>
<p>
- This must undo any effects that the
- <prgn>build</prgn> and <prgn>binary</prgn> targets
- may have had, except that it should leave alone any
- output files created in the parent directory by a
- run of <prgn>binary</prgn>. This target must be
- non-interactive.
+ This must undo any effects that the <prgn>build</prgn>
+ and <prgn>binary</prgn> targets may have had, except
+ that it should leave alone any output files created in
+ the parent directory by a run of a <prgn>binary</prgn>
+ target. This target must be non-interactive.
</p>
<p>
- If a <prgn>build</prgn> file is touched at the end
- of the <prgn>build</prgn> target, as suggested
- above, it should be removed as the first thing that
- <prgn>clean</prgn> does, so that running
+ If a <prgn>build</prgn> file is touched at the end of
+ the <prgn>build</prgn> target, as suggested above, it
+ should be removed as the first action that
+ <prgn>clean</prgn> performs, so that running
<prgn>build</prgn> again after an interrupted
<prgn>clean</prgn> doesn't think that everything is
already done.
<p>
The <prgn>build</prgn>, <prgn>binary</prgn> and
- <prgn>clean</prgn> targets must be invoked with a current
- directory of the package's top-level directory.
+ <prgn>clean</prgn> targets must be invoked with the current
+ directory being the package's top-level directory.
</p>
</p>
<p>
- The architecture we build on and build for is determined by
- make variables via dpkg-architecture. You can get the Debian
- architecture and the GNU style architecture specification
- string for the build machine as well as the host
- machine. Here is a list of supported make variables:
+ The architectures we build on and build for are determined
+ by <prgn>make</prgn> variables using the utility
+ <prgn>dpkg-architecture</prgn>. You can determine the
+ Debian architecture and the GNU style architecture
+ specification string for the build machine (the machine type
+ we are building on) as well as for the host machine (the
+ machine type we are building for). Here is a list of
+ supported <prgn>make</prgn> variables:
<list compact="compact">
<item>
<p><tt>DEB_*_ARCH</tt> (the Debian architecture)</p>
specification string)</p>
</item>
<item>
- <p><tt>DEB_*_GNU_CPU</tt> (the CPU part of DEB_*_GNU_TYPE)</p>
+ <p><tt>DEB_*_GNU_CPU</tt> (the CPU part of
+ <tt>DEB_*_GNU_TYPE</tt>)</p>
</item>
<item>
<p><tt>DEB_*_GNU_SYSTEM</tt> (the System part of
- DEB_*_GNU_TYPE)</p>
+ <tt>DEB_*_GNU_TYPE</tt>)</p>
</list>
- </p>
-
- <p>
where <tt>*</tt> is either <tt>BUILD</tt> for specification of
- the build machine or <tt>HOST</tt> for specification of the machine
- we build for.
+ the build machine or <tt>HOST</tt> for specification of the
+ host machine.
</p>
<p>
Backward compatibility can be provided in the rules file
by setting the needed variables to suitable default
- values, please refer to the documentation of
- dpkg-architecture for details.
+ values; please refer to the documentation of
+ <prgn>dpkg-architecture</prgn> for details.
</p>
<p>
Though there is nothing stopping an author who is also
the Debian maintainer from using it for all their
changes, it will have to be renamed if the Debian and
- upstream maintainers become different
- people.
+ upstream maintainers become different people. In such a
+ case, however, it might be better to maintain the
+ package as a non-native package.
</p>
</footnote>.
</p>
<p>
That format is a series of entries like this:
<example>
- <var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
+<var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
- * <var>change details</var>
- <var>more change details</var>
- * <var>even more change details</var>
+ * <var>change details</var>
+ <var>more change details</var>
+ * <var>even more change details</var>
- -- <var>maintainer name and email address</var> <var>date</var>
+ -- <var>maintainer name and email address</var> <var>date</var>
</example>
</p>
<prgn>dpkg</prgn> changelog format (though there is
currently only one useful <var>keyword</var>,
<tt>urgency</tt>).
+ <footnote>
+ <p>
+ Usual urgency values are <tt>low</tt>, <tt>medium</tt>,
+ <tt>high</tt> and <tt>critical</tt>. They have an
+ effect on how quickly a package will be considered for
+ inclusion into the <tt>testing</tt> distribution, and
+ give an indication of the importance of any fixes
+ included in this upload.
+ </p>
+ </footnote>
</p>
<p>
</p>
<p>
- The maintainer name and email address need <em>not</em>
- necessarily be those of the usual package maintainer.
- They should be the details of the person doing
- <em>this</em> version. The information here will be
- copied to the <tt>.changes</tt> file, and then later used
- to send an acknowledgement when the upload has been
- installed.
+ If this upload resolves bugs recorded in the Bug Tracking
+ System (BTS), they may be automatically closed on the
+ inclusion of this package into the Debian archive by
+ including the string: <tt>closes: Bug#<var>nnnnn</var></tt>
+ in the change details.
+ <footnote>
+ <p>
+ To be precise, the string should match the following
+ Perl regular expression:
+ <tt>/closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i</tt>
+ Then all of the bug numbers listed will be closed by the
+ archive maintenance script (<prgn>katie</prgn>), or in
+ the case of an NMU, marked as fixed.
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ The maintainer name and email address used in the changelog
+ should be the details of the person uploading <em>this</em>
+ version. They are <em>not</em> necessarily those of the
+ usual package maintainer. The information here will be
+ copied to the <tt>Changed-By</tt> field in the
+ <tt>.changes</tt> file, and then later used to send an
+ acknowledgement when the upload has been installed.
</p>
<p>
</p>
</footnote>; it should include the time zone specified
numerically, with the time zone name or abbreviation
- optionally present as a comment.
+ optionally present as a comment in parentheses.
</p>
<p>
<p>
When <prgn>dpkg-gencontrol</prgn>,
<prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
- generate control files they do variable substitutions on
- their output just before writing it. Variable
+ generate control files they perform variable substitutions
+ on their output just before writing it. Variable
substitutions have the form
<tt>${<var>variable-name</var>}</tt>. The optional file
- <tt>debian/substvars</tt> contains variable substitutions
- to be used; variables can also be set directly from
+ <tt>debian/substvars</tt> contains variable substitutions to
+ be used; variables can also be set directly from
<tt>debian/rules</tt> using the <tt>-V</tt> option to the
- source packaging commands, and certain predefined
- variables are available.
+ source packaging commands, and certain predefined variables
+ are also available.
</p>
<p>
- The is usually generated and modified dynamically by
- <tt>debian/rules</tt> targets; in this case it must be
- removed by the <prgn>clean</prgn> target.
+ The <tt>debian/substvars</tt> file is usually generated and
+ modified dynamically by <tt>debian/rules</tt> targets; in
+ this case it must be removed by the <prgn>clean</prgn>
+ target.
</p>
<p>
</p>
<p>
- <prgn>dpkg-gencontrol</prgn> adds an entry to this file
- for the <tt>.deb</tt> file that will be created by
- <prgn>dpkg-deb</prgn> from the control file that it
- generates, so for most packages all that needs to be done
- with this file is to delete it in <prgn>clean</prgn>.
+ When <prgn>dpkg-gencontrol</prgn> is run for a binary
+ package, it adds an entry to <tt>debian/files</tt> for the
+ <tt>.deb</tt> file that will be created when <prgn>dpkg-deb
+ --build</prgn> is run for that binary package. So for most
+ packages all that needs to be done with this file is to
+ delete it in the <prgn>clean</prgn> target.
</p>
<p>
packages, but only when extracting
them.
</p>
- </footnote>
- <footnote>
<p>
Hard links may be permitted at some point in the
future, but would require a fair amount of
</p>
<p>
- These scripts should be the files <tt>preinst</tt>,
+ These scripts are the files <tt>preinst</tt>,
<tt>postinst</tt>, <tt>prerm</tt> and <tt>postrm</tt> in the
control area of the package. They must be proper executable
- files; if they are scripts (which is recommended) they must
+ 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 not world-writable.
</p>
well.
</p>
- <p>
- It is necessary for the error recovery procedures that the
- scripts be idempotent: i.e., invoking the same script several
- times in the same situation should do no harm. If the first
- call failed, or aborted half way through for some reason,
- the second call should merely do the things that were left
- undone the first time, if any, and exit with a success
- status.
- </p>
-
<p>
When a package is upgraded a combination of the scripts from
- the old and new packages is called in amongst the other
- steps of the upgrade procedure. If your scripts are going
- to be at all complicated you need to be aware of this, and
- may need to check the arguments to your scripts.
+ the old and new packages is called during the upgrade
+ procedure. If your scripts are going to be at all
+ complicated you need to be aware of this, and may need to
+ check the arguments to your scripts.
</p>
<p>
<prgn>postrm</prgn> afterwards.
</p>
- <p> Programs called from maintainer scripts should not
- normally have a path prepended to them. Before installation
- is started the package management system checks to see if
- the programs <prgn>ldconfig</prgn>,
+ <p>
+ Programs called from maintainer scripts should not normally
+ have a path prepended to them. Before installation is
+ started, the package management system checks to see if the
+ programs <prgn>ldconfig</prgn>,
<prgn>start-stop-daemon</prgn>, <prgn>install-info</prgn>,
and <prgn>update-rc.d</prgn> can be found via the
<tt>PATH</tt> environment variable. Those programs, and any
- other program that one would expect to on the <tt>PATH</tt>,
- should thus be invoked without an absolute
+ other program that one would expect to be on the
+ <tt>PATH</tt>, should thus be invoked without an absolute
pathname. Maintainer scripts should also not reset the
- <tt>PATH</tt>, though they might choose to modify it by pre-
- or appending package-specific directories. These
+ <tt>PATH</tt>, though they might choose to modify it by
+ prepending or appending package-specific directories. These
considerations really apply to all shell scripts.</p>
</sect>
+
<sect>
<heading>Maintainer scripts Idempotency</heading>
<p>
- It is very important to make maintainer scripts
- idempotent.
- <footnote>
+ It is necessary for the error recovery procedures that the
+ scripts be idempotent. This means that if it is run
+ successfully, and then it is called again, it doesn't bomb
+ out or cause any harm, but just ensures that everything is
+ the way it ought to be. If the first call failed, or
+ aborted half way through for some reason, the second call
+ should merely do the things that were left undone the first
+ time, if any, and exit with a success status if everything
+ is OK.
+ <footnote>
<p>
- That means that if it runs successfully or fails
- and then you call it again it doesn't bomb out,
- but just ensures that everything is the way it
- ought to be.
+ This is so that if an error occurs, the user interrupts
+ <prgn>dpkg</prgn> or some other unforeseen circumstance
+ happens you don't leave the user with a badly-broken
+ package when <prgn>dpkg</prgn> attempts to repeat the
+ action.
</p>
- </footnote> This is so that if an error occurs, the
- user interrupts <prgn>dpkg</prgn> or some other
- unforeseen circumstance happens you don't leave the
- user with a badly-broken package.
+ </footnote>
</p>
</sect>
+
<sect>
<heading>Controlling terminal for maintainer scripts</heading>
</item>
<item>
<p><var>old-postinst</var> <tt>abort-upgrade</tt>
- <var>new version</var></p>
+ <var>new-version</var></p>
</item>
<item>
<p><var>conflictor's-postinst</var> <tt>abort-remove</tt>
The procedure on installation/upgrade/overwrite/disappear
(i.e., when running <tt>dpkg --unpack</tt>, or the unpack
stage of <tt>dpkg --install</tt>) is as follows. In each
- case if an error occurs the actions are, in general, run
- backwards - this means that the maintainer scripts are run
- with different arguments in reverse order. These are the
- `error unwind' calls listed below.
+ case, if a major error occurs (unless listed below) the
+ actions are, in general, run backwards - this means that the
+ maintainer scripts are run with different arguments in
+ reverse order. These are the `error unwind' calls listed
+ below.
<enumlist>
<item>
<example>
<var>new-preinst</var> install
</example>
- Error unwind versions, respectively:
+ Error unwind actions, respectively:
<example>
<var>new-postrm</var> abort-upgrade <var>old-version</var>
<var>new-postrm</var> abort-install <var>old-version</var>
The new package's files are unpacked, overwriting any
that may be on the system already, for example any
from the old version of the same package or from
- another package (backups of the old files are left
- around, and if anything goes wrong the package
+ another package. Backups of the old files are kept
+ temporarily, and if anything goes wrong the package
management system will attempt to put them back as
- part of the error unwind).
+ part of the error unwind.
</p>
<p>
It is an error for a package to contains files which
are on the system in another package, unless
<tt>Replaces</tt> is used (see <ref id="replaces">).
- Currently the <tt>--force-overwrite</tt> flag is
+ <!--
+ The following paragraph is not currently the case:
+ Currently the <tt>- - force-overwrite</tt> flag is
enabled, downgrading it to a warning, but this may not
always be the case.
+ -->
</p>
<p>
<p>
Packages which overwrite each other's files produce
- behavior which though deterministic is hard for the
+ 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
</p>
<p>
- A directory will never be replaced by a symbolic links
+ A directory will never be replaced by a symbolic link
to a directory or vice versa; instead, the existing
state (symlink or not) will be left alone and
<prgn>dpkg</prgn> will follow the symlink if there is
<p>Any packages all of whose files have been overwritten during the
installation, and which aren't required for
dependencies, are considered to have been removed.
- For each such package,
+ For each such package
<enumlist>
<item>
<p><prgn>dpkg</prgn> calls:
<item>
<p>
The new package's status is now sane, and recorded as
- `unpacked'. Here is another point of no return - if
- the conflicting package's removal fails we do not
- unwind the rest of the installation; the conflicting
- package is left in a half-removed limbo.
+ `unpacked'.
+ </p>
+
+ <p>
+ Here is another point of no return - if the
+ conflicting package's removal fails we do not unwind
+ the rest of the installation; the conflicting package
+ is left in a half-removed limbo.
</p>
</item>
+
<item>
<p>
If there was a conflicting package we go and do the
<p>
When we configure a package (this happens with <tt>dpkg
--install</tt>, or with <tt>--configure</tt>), we first
- update the conffiles and then call:
+ update any <tt>conffile</tt>s and then call:
<example>
<var>postinst</var> configure <var>most-recently-configured-version</var>
</example>
</item>
<item>
<p>
- The package's files are removed (except conffiles).
+ The package's files are removed (except <tt>conffile</tt>s).
</p>
</item>
<item>
</example></p>
</item>
<item>
- <p>All the maintainer scripts except the postrm are removed.
+ <p>
+ All the maintainer scripts except the <tt>postrm</tt>
+ are removed.
</p>
<p>
If we aren't purging the package we stop here. Note
- that packages which have no postrm and no conffiles
- are automatically purged when removed, as there is no
- difference except for the <prgn>dpkg</prgn>
- status.</p>
+ that packages which have no <tt>postrm</tt> and no
+ <tt>conffile</tt>s are automatically purged when
+ removed, as there is no difference except for the
+ <prgn>dpkg</prgn> status.</p>
</item>
<item>
<p>
</item>
</enumlist>
No attempt is made to unwind after errors during
- removal.</p>
+ removal.
+ </p>
</sect>
</chapt>
<chapt id="relationships"><heading>Declaring relationships between
- packages </heading>
+ packages</heading>
<p>
Packages can declare in their control file that they have
</p>
<p>
- This is done using the <tt>Depends</tt>, <tt>Recommends</tt>,
- <tt>Suggests</tt>, <tt>Enhances</tt>, <tt>Conflicts</tt>,
- <tt>Provides</tt> and <tt>Replaces</tt> control file fields.
+ This is done using the <tt>Depends</tt>, <tt>Pre-Depends</tt>,
+ <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
+ <tt>Conflicts</tt>, <tt>Provides</tt> and <tt>Replaces</tt>
+ control file fields.
</p>
<p>
<p>
This is done using the <tt>Build-Depends</tt>,
- <tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt>, and
+ <tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt> and
<tt>Build-Conflicts-Indep</tt> control file fields.
</p>
control file 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 symbols <tt>|</tt> (pipe symbols). In such
- a case, the presence of any one of the alternative packages
- is installed, that part of the dependency is considered to
- be satisfied.
+ by vertical bar (pipe) symbols <tt>|</tt>. In such a case,
+ if any one of the alternative packages is installed, that
+ part of the dependency is considered to be satisfied.
</p>
<p>
- All the fields except <tt>Provides</tt> may restrict their
- applicability to particular versions of each named package.
- This is done in parentheses after each individual package
- name; the parentheses should contain a relation from the
- list below followed by a version number, in the format
+ All of the fields except for <tt>Provides</tt> may restrict
+ their applicability to particular versions of each named
+ package. This is done in parentheses after each individual
+ package name; the parentheses should contain a relation from
+ the list below followed by a version number, in the format
described in <ref id="versions">.
</p>
The relations allowed are <tt><<</tt>, <tt><=</tt>,
<tt>=</tt>, <tt>>=</tt> and <tt>>></tt> for
strictly earlier, earlier or equal, exactly equal, later or
- equal and strictly later, respectively. The forms
- <tt><</tt> and <tt>></tt> were used to mean
+ equal and strictly later, respectively. The deprecated
+ forms <tt><</tt> and <tt>></tt> were used to mean
earlier/later or equal, rather than strictly earlier/later,
so they should not appear in new packages (though
<prgn>dpkg</prgn> still supports them).
<p>
Whitespace may appear at any point in the version
- specification, and must appear where it's necessary to
+ specification subject to the rules in <ref
+ id="controlsyntax">, and must appear where it's necessary to
disambiguate; it is not otherwise significant. For
consistency and in case of future changes to
<prgn>dpkg</prgn> it is recommended that a single space be
used after a version relationship and before a version
- number; it is usual also to put a single space after each
- comma, on either side of each vertical bar, and before each
- open parenthesis.
+ number; it is also conventional to put a single space after
+ each comma, on either side of each vertical bar, and before
+ each open parenthesis.
</p>
<p>
- For example:
+ For example, a list of dependencies might appear as:
<example>
- Package: metamail
- Version: 2.7-3
- Depends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh
+ Package: mutt
+ Version: 1.3.17-1
+ Depends: libc6 (>= 2.2.1), exim | mail-transport-agent
</example>
</p>
(<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
<tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>)
may be restricted to a certain set of architectures. This
- is done in brackets after each individual package name and
+ is indicated in brackets after each individual package name and
the optional version specification. The brackets enclose a
list of Debian architecture names separated by whitespace.
Exclamation marks may be prepended to each of the names.
</p>
<p>
- All but <tt>Pre-Depends</tt> and <tt>Conflicts</tt>
- (discussed below) take effect <em>only</em> when a package
- is to be configured. They do not prevent a package being on
- the system in an unconfigured state while its dependencies
- are unsatisfied, and it is possible to replace a package
- whose dependencies are satisfied and which is properly
- installed with a different version whose dependencies are
- not and cannot be satisfied; when this is done the depending
- package will be left unconfigured (since attempts to
- configure it will give errors) and will not function
- properly.
+ A <tt>Depends</tt> field takes effect <em>only</em> when a
+ package is to be configured. It does not prevent a package
+ being on the system in an unconfigured state while its
+ dependencies are unsatisfied, and it is possible to replace
+ a package whose dependencies are satisfied and which is
+ properly installed with a different version whose
+ dependencies are not and cannot be satisfied; when this is
+ done the depending package will be left unconfigured (since
+ attempts to configure it will give errors) and will not
+ function properly. If it is necessary, a
+ <tt>Pre-Depends</tt> field can be used, which has a partial
+ effect even when a package is being unpacked, as explained
+ in detail below. (The other three dependency fields,
+ <tt>Recommends</tt>, <tt>Suggests</tt> and
+ <tt>Enhances</tt>, are only used by the various front-ends
+ to <prgn>dpkg</prgn> such as <prgn>dselect</prgn>.)
</p>
<p>
</p>
<p>
- Thus <tt>Depends</tt> allows package maintainers to impose
- an order in which packages should be configured.
+ The <tt>Depends</tt> field thus allows package maintainers
+ to impose an order in which packages should be configured.
+ </p>
+
+ <p>
+ The meaning of the five dependency fields is as follows:
<taglist>
<tag><tt>Depends</tt></tag>
<item>
- <p>This declares an absolute dependency.
+ <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.
</p>
<p>
The <tt>Depends</tt> field should be used if the
depended-on package is required for the depending
package to provide a significant amount of
- functionality.</p>
+ functionality.
+ </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.
</item>
<tag><tt>Recommends</tt></tag>
also forces <prgn>dpkg</prgn> to complete installation
of the packages named before even starting the
installation of the package which declares the
- Pre-dependency.
+ pre-dependency, as follows:
</p>
<p>
- <tt>Pre-Depends</tt> should be used sparingly,
- preferably only by packages whose premature upgrade or
- installation would hamper the ability of the system to
- continue with any upgrade that might be in progress.
+ When a package declaring a pre-dependency is about to
+ be <em>unpacked</em> the pre-dependency can be
+ satisfied if the depended-on package is either fully
+ configured, <em>or even if</em> the depended-on
+ package(s) are only unpacked or half-configured,
+ provided that they have been configured correctly at
+ some point in the past (and not removed or partially
+ removed since). In this case, both the
+ previously-configured and currently unpacked or
+ half-configured versions must satisfy any version
+ clause in the <tt>Pre-Depends</tt> field.
</p>
<p>
- When the package declaring it is being configured, a
- <tt>Pre-Dependency</tt> will be considered satisfied
- only if the depending package has been correctly
- configured, just as if an ordinary <tt>Depends</tt>
- had been used.
+ 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.
</p>
<p>
- However, when a package declaring a Pre-dependency is
- being unpacked the predependency can be satisfied even
- if the depended-on package(s) are only unpacked or
- half-configured, provided that they have been
- configured correctly at some point in the past (and
- not removed or partially removed since). In this case
- both the previously-configured and currently unpacked
- or half-configured versions must satisfy any version
- clause in the <tt>Pre-Depends</tt> field.
+ <tt>Pre-Depends</tt> should be used sparingly,
+ preferably only by packages whose premature upgrade or
+ 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.
</item>
</taglist>
</p>
</p>
- <sect id="conflicts"><heading>Alternative binary packages -
- <tt>Conflicts</tt> and <tt>Replaces</tt>
- </heading>
+ <sect id="conflicts"><heading>Conflicting binary packages -
+ <tt>Conflicts</tt></heading>
<p>
When one binary package declares a conflict with another
- <prgn>dpkg</prgn> will refuse to allow them to be installed
- on the system at the same time.
+ using a <tt>Conflicts</tt> field, <prgn>dpkg</prgn> will
+ refuse to allow them to be installed on the system at the
+ same time.
</p>
<p>
If one package is to be installed, the other must be removed
first - if the package being installed is marked as
- replacing (<ref id="replaces">) the one on the system, or
- the one on the system is marked as deselected, or both
+ replacing (see <ref id="replaces">) the one on the system,
+ or the one on the system is marked as deselected, or both
packages are marked <tt>Essential</tt>, then
<prgn>dpkg</prgn> will automatically remove the package
which is causing the conflict, otherwise it will halt the
- installation of the new package with an error. This
- mechanism specifically doesn't work when the installed
- package is <tt>Essential</tt>, but the new package is not.
+ installation of the new package with an error. This
+ mechanism is specifically designed to produce an error when
+ the installed package is <tt>Essential</tt>, but the new
+ package is not.
</p>
-
<p>
A package will not cause a conflict merely because its
configuration files are still installed; it must be at least
prevent their installation, and allows a package to conflict
with others providing a replacement for it. You use this
feature when you want the package in question to be the only
- package providing something.
+ package providing some feature.
</p>
<p>
<p>
As well as the names of actual (`concrete') packages, the
package relationship fields <tt>Depends</tt>,
+ <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
+ <tt>Pre-Depends</tt>, <tt>Conflicts</tt>,
<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
- <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Conflicts</tt>,
- <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt> may
- mention virtual packages.
+ <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>
+ may mention `virtual packages'.
</p>
<p>
- A virtual package is one which appears in the
+ 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
packages which provide it. This is so that, for example,
supposing we have
<example>
- Package: vm
- Depends: emacs
+ Package: foo
+ Depends: bar
</example>
- and someone else releases an xemacs package they can say
+ and someone else releases an enhanced version of the
+ <tt>bar</tt> package (for example, a non-US variant), they
+ can say:
<example>
- Package: xemacs
- Provides: emacs
- </example> and all will work in the interim (until a purely
- virtual package name is decided on and the <tt>emacs</tt>
- and <tt>vm</tt> packages are changed to use it).
+ Package: bar-plus
+ Provides: bar
+ </example>
+ and the <tt>bar-plus</tt> package will now also satisfy the
+ dependency for the <tt>foo</tt> package.
</p>
<p>
</p>
<p>
- If you want to specify which of a set of real packages should be the
- default to satisfy a particular dependency on a virtual package, you
- should list the real package as an alternative before the virtual.
+ If you want to specify which of a set of real packages
+ should be the default to satisfy a particular dependency on
+ a virtual package, you should list the real package as an
+ alternative before the virtual one.
</p>
</sect>
- <sect id="replaces"><heading><tt>Replaces</tt> - overwriting
- files and replacing packages
- </heading>
-
- <p>
- The <tt>Replaces</tt> control file field has two purposes,
- which come into play in different situations.
- </p>
+ <sect id="replaces"><heading>Overwriting files and replacing
+ packages - <tt>Replaces</tt></heading>
<p>
- Virtual packages (<ref id="virtual">) are not considered
- when looking at a <tt>Replaces</tt> field - the packages
- declared as being replaced must be mentioned by their real
- names.
+ The <tt>Replaces</tt> control file field has two distinct
+ purposes, which come into play in different situations.
</p>
- <sect1><heading>Overwriting files in other packages
- </heading>
+ <sect1><heading>Overwriting files in other packages</heading>
<p>
Firstly, as mentioned before, it is usually an error for a
package to contain files which are on the system in
- another package, though currently the
- <tt>--force-overwrite</tt> flag is enabled by default,
- downgrading the error to a warning,
+ another package.
</p>
<p>
- If the overwriting package declares that it replaces the
- one containing the file being overwritten then
- <prgn>dpkg</prgn> will proceed, and replace the file from
- the old package with that from the new. The file will no
- longer be listed as `owned' by the old package.
+ However, if the overwriting package declares that it
+ <tt>Replaces</tt> the one containing the file being
+ overwritten, then <prgn>dpkg</prgn> will replace the file
+ from the old package with that from the new. The file
+ will no longer be listed as `owned' by the old package.
</p>
<p>
If a package is completely replaced in this way, so that
<prgn>dpkg</prgn> does not know of any files it still
- contains, it is considered to have disappeared. It will
+ contains, it is considered to have `disappeared'. It will
be marked as not wanted on the system (selected for
- removal) and not installed. Any conffiles details noted
- in the package will be ignored, as they will have been
- taken over by the replacing package(s). The package's
- <prgn>postrm</prgn> script will be run to allow the
- package to do any final cleanup required. See <ref
- id="mscriptsinstact">.
+ removal) and not installed. Any <tt>conffile</tt>s
+ details noted for the package will be ignored, as they
+ will have been taken over by the overwriting package. The
+ package's <prgn>postrm</prgn> script will be run with a
+ special argument to allow the package to do any final
+ cleanup required. See <ref id="mscriptsinstact">.
</p>
<p>
- In the future <prgn>dpkg</prgn> will discard files which
- would overwrite those from an already installed package
- which declares that it replaces the package being
- installed. This is so that you can install an older
- version of a package without problems.
+ If an installed package, <tt>foo</tt> say, declares that
+ it replaces another, <tt>bar</tt>, and an attempt is made
+ to install <tt>bar</tt>, <prgn>dpkg</prgn> will discard
+ files in the <tt>bar</tt> package which would overwrite
+ those already present in <tt>foo</tt>. This is so that
+ you can install an older version of a package without
+ problems.
</p>
<p>
- This usage of <tt>Replaces</tt> only takes effect when
- both packages are at least partially on the system at
- once, so that it can only happen if they do not conflict
- or if the conflict has been overridden.</p>
+ For this usage of <tt>Replaces</tt>, virtual packages (see
+ <ref id="virtual">) are not considered when looking at a
+ <tt>Replaces</tt> field - the packages declared as being
+ replaced must be mentioned by their real names.
+ </p>
+
+ <p>
+ Furthermore, this usage of <tt>Replaces</tt> only takes
+ effect when both packages are at least partially on the
+ system at once, so that it can only happen if they do not
+ conflict or if the conflict has been overridden.
+ </p>
+
</sect1>
<sect1><heading>Replacing whole packages, forcing their
- removal
- </heading>
+ removal</heading>
<p>
Secondly, <tt>Replaces</tt> allows the packaging system to
resolve which package should be removed when there is a
conflict - see <ref id="conflicts">. This usage only
takes effect when the two packages <em>do</em> conflict,
- so that the two effects do not interfere with each other.
+ so that the two usages of this field do not interfere with
+ each other.
</p>
+
+ <p>
+ In this situation, the package declared as being replaced
+ can be a virtual package, so for example, all mail
+ transport agents (MTAs) would have the following fields in
+ their control files:
+ <example>
+Provides: mail-transport-agent
+Conflicts: mail-transport-agent
+Replaces: mail-transport-agent
+ </example>
+ ensuring that only one MTA can be installed at any one
+ time.
</sect1>
</sect>
<p>
A source package may declare a dependency or a conflict on a
- binary package. This is done with the control file fields
- <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
- <tt>Build-Conflicts</tt>, and
- <tt>Build-Conflicts-Indep</tt>. Their semantics are that
- the dependencies and conflicts they define must be satisfied
- (as defined earlier for binary packages), when one of the
- targets in <tt>debian/rules</tt> that the particular field
- applies to is invoked.
+ binary package, indicating which packages are required to be
+ present on the system in order to build the binary packages
+ from the source package. This is done with the control file
+ fields <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
+ <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>.
+ The dependencies and conflicts they define must be satisfied
+ (as defined earlier for binary packages) in order to invoke
+ the targets in <tt>debian/rules</tt>, as follows:
<taglist>
<tag><tt>Build-Depends</tt>, <tt>Build-Conflicts</tt></tag>
<item>
<p>
The <tt>Build-Depends</tt> and
- <tt>Build-Conflicts</tt> fields apply to the targets
+ <tt>Build-Conflicts</tt> fields must be satisfied when
+ any of the following targets is invoked:
<tt>build</tt>, <tt>binary</tt>, <tt>binary-arch</tt>
and <tt>binary-indep</tt>.
</p>
<item>
<p>
The <tt>Build-Depends-Indep</tt> and
- <tt>Build-Conflicts-Indep</tt> fields apply to the
- targets <tt>binary</tt> and <tt>binary-indep</tt>.
+ <tt>Build-Conflicts-Indep</tt> fields must be
+ satisfied when any of the following targets is
+ invoked: <tt>binary</tt> and <tt>binary-indep</tt>.
</p>
</item>
</taglist>
</heading>
<p>
- <prgn>dpkg</prgn> can do a certain amount of automatic
- handling of package configuration files.
+ This chapter has been superseded by <ref id="config files">.
</p>
- <p>
- Whether this mechanism is appropriate depends on a number of
- factors, but basically there are two approaches to any
- particular configuration file.
- </p>
- <p>
- The easy method is to ship a best-effort configuration in the
- package, and use <prgn>dpkg</prgn>'s conffile mechanism to
- handle updates. If the user is unlikely to want to edit the
- file, but you need them to be able to without losing their
- changes, and a new package with a changed version of the file
- is only released infrequently, this is a good approach.
- </p>
-
- <p>
- The hard method is to build the configuration file from
- scratch in the <prgn>postinst</prgn> script, and to take the
- responsibility for fixing any mistakes made in earlier
- versions of the package automatically. This will be
- appropriate if the file is likely to need to be different on
- each system.
- </p>
-
-
- <chapt id="sharedlibs"><heading>Shared libraries
- </heading>
+ <chapt id="sharedlibs"><heading>Shared libraries</heading>
<p>
Packages containing shared libraries must be constructed with
a little care to make sure that the shared library is always
available. This is especially important for packages whose
- shared libraries are vitally important, such as the libc.
+ shared libraries are vitally important, such as the C library
+ (currently <tt>libc6</tt>).
</p>
<p>
- Firstly, your package should install the shared libraries
- under their normal names. For example, the
- <prgn>libgdbm1</prgn> package should install
- <tt>libgdbm.so.1.7.3</tt> as
+ Firstly, the package should install the shared libraries under
+ their normal names. For example, the <tt>libgdbmg1</tt>
+ package should install <tt>libgdbm.so.1.7.3</tt> as
<tt>/usr/lib/libgdbm.so.1.7.3</tt>. The files should not be
- renamed or re-linked by any prerm or postrm scripts;
- <prgn>dpkg</prgn> will take care of renaming things safely
- without affecting running programs, and attempts to interfere
- with this are likely to lead to problems.
+ renamed or re-linked by any <prgn>prerm</prgn> or
+ <prgn>postrm</prgn> scripts; <prgn>dpkg</prgn> will take care
+ of renaming things safely without affecting running programs,
+ and attempts to interfere with this are likely to lead to
+ problems.
</p>
<p>
- Secondly, your package should include the symlink that
+ Secondly, the package should include the symbolic link that
<prgn>ldconfig</prgn> would create for the shared libraries.
- For example, the <prgn>libgdbm1</prgn> package should include
- a symlink from <tt>/usr/lib/libgdbm.so.1</tt> to
- <tt>libgdbm.so.1.7.3</tt>. This is needed so that
- <prgn>ld.so</prgn> can find the library in between the time
- <prgn>dpkg</prgn> installs it and <prgn>ldconfig</prgn> is run
- in the <prgn>postinst</prgn> script. Furthermore, older
- versions of the package management system required the library
- must be placed before the symlink pointing to it in the
- <tt>.deb</tt> file. This is so that by the time
- <prgn>dpkg</prgn> comes to install the symlink (overwriting
- the previous symlink pointing at an older version of the
- library) the new shared library is already in place.
- Unfortunately, this was not not always possible, since it
- highly depends on the behavior of the file system. Some
- file systems (such as reiserfs) will reorder the files so it
- doesn't matter in what order you create them. Starting with
- release <tt>1.7.0</tt> <prgn>dpkg</prgn> will reorder the
- files itself when building a package.
+ For example, the <prgn>libgdbmg1</prgn> package should include
+ a symbolic link from <tt>/usr/lib/libgdbm.so.1</tt> to
+ <tt>libgdbm.so.1.7.3</tt>. 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
+ time that <prgn>dpkg</prgn> installs it and the time that
+ <prgn>ldconfig</prgn> is run in the <prgn>postinst</prgn>
+ script.
+ <footnote>
+ <p>
+ The package management system requires the library to be
+ placed before the symbolic link pointing to it in the
+ <tt>.deb</tt> file. This is so that when
+ <prgn>dpkg</prgn> comes to install the symlink
+ (overwriting the previous symlink pointing at an older
+ version of the library), the new shared library is already
+ in place. In the past, this was achieved by creating the
+ library in the temporary packaging directory before
+ creating the symlink. Unfortunately, this was not always
+ effective, since the building of the tar file in the
+ <tt>.deb</tt> depended on the behavior of the underlying
+ file system. Some file systems (such as reiserfs) reorder
+ the files so that the order of creation is forgotten.
+ Starting with release <tt>1.7.0</tt>, <prgn>dpkg</prgn>
+ will reorder the files itself as necessary when building a
+ package. Thus it is no longer important to concern
+ oneself with the order of file creation.
+ </p>
+ </footnote>
</p>
<p>
- Thirdly, the development package should contain a symlink for
- the shared library without a version number. For example, the
- <tt>libgdbm1-dev</tt> package should include a symlink from
- <tt>/usr/lib/libgdm.so</tt> to <tt>libgdm.so.1.7.3</tt>. This
- symlink is needed by <prgn>ld</prgn> when compiling packages
- as it will only look for <tt>libgdm.so</tt> and
- <tt>libgdm.a</tt> when compiling dynamically or statically,
- respectively.
+ Thirdly, the associated development package should contain a
+ symlink for the shared library without a version number. For
+ example, the <tt>libgdbmg1-dev</tt> package should include a
+ symlink from <tt>/usr/lib/libgdbm.so</tt> to
+ <tt>libgdbm.so.1.7.3</tt>. This symlink is needed by the
+ linker (<prgn>ld</prgn>) when compiling packages, as it will
+ only look for <tt>libgdbm.so</tt> when compiling dynamically.
</p>
<p>
- Any package installing shared libraries in a directory that's listed
- in <tt>/etc/ld.so.conf</tt> or in one of the default library
- directories of <prgn>ld.so</prgn> (currently, these are <tt>/usr/lib</tt>
- and <tt>/lib</tt>) must call <prgn>ldconfig</prgn> in its <prgn>postinst</prgn>
- script if and only if the first argument is `configure'. However, it
- is important not to call <prgn>ldconfig</prgn> in the postrm or preinst
- scripts in the case where the package is being upgraded (see <ref
- id="unpackphase">), as <prgn>ldconfig</prgn> will see the temporary names
- that <prgn>dpkg</prgn> uses for the files while it is
- installing them and will make the shared library links point
- to them, just before <prgn>dpkg</prgn> continues the
- installation and removes the links!
+ Any package installing shared libraries in a directory that is
+ listed in <tt>/etc/ld.so.conf</tt> or in one of the default
+ library directories of the dynamic linker (currently, these
+ are <tt>/usr/lib</tt> and <tt>/lib</tt>) must call
+ <prgn>ldconfig</prgn> in its <prgn>postinst</prgn> script if
+ and only if the first argument is `configure'. However, it is
+ important not to call <prgn>ldconfig</prgn> in the postrm or
+ preinst scripts in the case where the package is being
+ upgraded (see <ref id="unpackphase">), as
+ <prgn>ldconfig</prgn> will see the temporary names that
+ <prgn>dpkg</prgn> uses for the files while it is installing
+ them and will make the shared library links point to them,
+ just before <prgn>dpkg</prgn> continues the installation and
+ removes the links!
</p>
<sect id="shlibs"><heading>The <tt>shlibs</tt> File Format
permissions 2775 (group-writable and set-group-id) and be
owned by <tt>root.staff</tt>.</p>
</sect1>
+ <sect1>
+ <heading>The system-wide mail directory</heading>
+ <p>
+ The system-wide mail directory is <tt>/var/mail</tt>. This
+ directory is part of the base system and should not owned
+ by any particular mail agents. The use of the old
+ location <tt>/var/spool/mail</tt> is deprecated, even
+ though the spool may still be physically located there.
+ To maintain partial upgrade compatibility for systems
+ which have <tt>/var/spool/mail</tt> as their physical mail
+ spool, packages using <tt>/var/mail</tt> must depend on
+ either <package>libc6</package> (>= 2.1.3-13), or on
+ <package>base-files</package> (>= 2.2.0), or on later
+ versions of either one of these packages.
+ </p>
+ </sect1>
+
</sect>
+
+
<sect>
<heading>Users and groups</heading>
<p>
If a certain job has to be executed more frequently than
daily, the package should install a file
- <tt>/etc/cron.d/<var>package-name</var></tt>. This file uses
+ <tt>/etc/cron.d/<var>package</var></tt>. This file uses
the same syntax as <tt>/etc/crontab</tt> and is processed by
<prgn>cron</prgn> automatically. The file must also be
treated as a configuration file. (Note, that entries in the
<p>
You should follow the directions in the <em>Debian Packaging
- Manual</em> for putting the shared library in its package,
- and you must include a <tt>shlibs</tt> control area
- file with details of the dependencies for packages which
- use the library.</p>
+ Manual</em> (or other documentation of the Debian
+ packaging tools) for putting the shared library in its
+ package, and you must include a <tt>shlibs</tt> control area
+ file with details of the dependencies for packages which use
+ the library.</p>
<p>
Shared libraries should not be installed
</sect>
</chapt>
- <chapt>
+ <chapt id="customized-programs">
<heading>Customized programs</heading>
<sect id="arch-spec">
</enumlist></p></sect>
- <sect>
+ <sect id="mail-transport-agents">
<heading>Mail transport, delivery and user agents</heading>
<p>
serious brain damage!</p>
<p>
- The mail spool is <tt>/var/spool/mail</tt> and the interface
+ The mail spool is <tt>/var/mail</tt> and the interface
to send a mail message is <tt>/usr/sbin/sendmail</tt> (as
- per the FHS). The mail spool is part of the base system
- and not part of the MTA package.</p>
+ per the FHS). On older systems, the mail spool may be
+ physically located in /var/spool/mail, but all access to the
+ mail spool should be via the /var/mail symlink. The mail
+ spool is part of the base system and not part of the MTA
+ package.
+ </p>
<p>
All Debian MUAs, MTAs, MDAs and other mailbox accessing
<item>
BDF fonts should be converted to PCF fonts with the
<tt>bdftopcf</tt> utility (available in the
- <tt>xutils</tt> package, <tt>gzip</tt>ped, and
+ <tt>xutils</tt> package), <tt>gzip</tt>ped, and
placed in a directory that corresponds to their
resolution:
<list>
</p>
</sect>
+ <sect>
+ <heading>Perl programs and modules</heading>
+ <p>
+ Perl programs and modules should follow the current Perl
+ policy as defined in the file found on
+ <ftpsite>ftp.debian.org</ftpsite> in
+ <ftppath>/debian/doc/package-developer/perl-policy.txt.gz</ftppath>
+ or your local mirror. In addition, it is included in the
+ <tt>debian-policy</tt> package.
+ </p>
+ </sect>
<sect>
<heading>Emacs lisp programs</heading>
<p>
Every package must be accompanied by a verbatim copy of its
copyright and distribution license in the file
- /usr/share/doc/<package-name>/copyright. This file must
+ /usr/share/doc/<package>/copyright. This file must
neither be compressed nor be a symbolic link.</p>
<p>
<p>
- /usr/share/doc/<package-name> may be a symbolic link to a
+ /usr/share/doc/<package> may be a symbolic link to a
directory in /usr/share/doc only if two packages both come from
the same source and the first package has a "Depends"
relationship on the second. These rules are important
projects / debian / debian-policy.git / blobdiff