<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>
</sect>
- <sect>
+ <sect id="maintainer">
<heading>The maintainer of a package</heading>
<p>
- Every package must have a Debian maintainer (the
- maintainer may be one person or a group of people
- reachable from a common email address, such as a mailing
- list). The maintainer is responsible for ensuring that
- the package is placed in the appropriate distributions.
- </p>
-
- <p>
- The maintainer must be specified in the
- <tt>Maintainer</tt> control field with their correct name
- and a working email address. If one person maintains
- several packages, they should try to avoid having
- different forms of their name and email address in
+ Every package must have a maintainer. The maintainer may be one
+ person or a group of people reachable from a common email
+ address, such as a mailing list. The maintainer is responsible
+ for maintaining the Debian packaging files, evaluating and
+ responding appropriately to reported bugs, uploading new
+ versions of the package (either directly or through a sponsor),
+ ensuring that the package is placed in the appropriate archive
+ area and included in Debian releases as appropriate for the
+ stability and utility of the package, and requesting removal of
+ the package from the Debian distribution if it is no longer
+ useful or maintainable.
+ </p>
+
+ <p>
+ The maintainer must be specified in the <tt>Maintainer</tt>
+ control field with their correct name and a working email
+ address. The email address given in the <tt>Maintainer</tt>
+ control field must accept mail from those role accounts in
+ Debian used to send automated mails regarding the package. This
+ includes non-spam mail from the bug-tracking system, all mail
+ from the Debian archive maintenance software, and other role
+ accounts or automated processes that are commonly agreed on by
+ the project.<footnote>
+ A sample implementation of such a whitelist written for the
+ Mailman mailing list management software is used for mailing
+ lists hosted by alioth.debian.org.
+ </footnote>
+ If one person or team maintains several packages, they should
+ use the same form of their name and email address in
the <tt>Maintainer</tt> fields of those packages.
</p>
</p>
<p>
- If the maintainer of a package quits from the Debian
- project, "Debian QA Group"
- <email>packages@qa.debian.org</email> takes over the
- maintainer-ship of the package until someone else
- volunteers for that task. These packages are called
- <em>orphaned packages</em>.<footnote>
- The detailed procedure for doing this gracefully can
- be found in the Debian Developer's Reference,
- see <ref id="related">.
- </footnote>
+ If the maintainer of the package is a team of people with a
+ shared email address, the <tt>Uploaders</tt> control field must
+ be present and must contain at least one human with their
+ personal email address. See <ref id="f-Uploaders"> for the
+ syntax of that field.
+ </p>
+
+ <p>
+ If the maintainer of a package no longer has time or desire to
+ maintain a package, it should be orphaned according to the
+ procedure described in the Debian Developer's Reference
+ (see <ref id="related">). The maintainer then
+ becomes <tt>Debian QA Group <packages@qa.debian.org></tt>.
+ These packages are considered maintained by the Debian project
+ as a whole until someone else volunteers to take over
+ maintenance.
</p>
</sect>
<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>
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>
putting the name in round brackets and moving it to the
end, and bringing the email address forward).
</p>
+
+ <p>
+ See <ref id="maintainer"> for additional requirements and
+ information about package maintainers.
+ </p>
</sect1>
<sect1 id="f-Uploaders">
<heading><tt>Uploaders</tt></heading>
<p>
- List of the names and email addresses of co-maintainers of
- the package, if any. If the package has other maintainers
- beside the one named in the
- <qref id="f-Maintainer">Maintainer field</qref>, their names
- and email addresses should be listed here. The format of each
- entry is the same as that of the Maintainer field, and
- multiple entries must be comma separated. This is an optional
- field.
+ List of the names and email addresses of co-maintainers of the
+ package, if any. If the package has other maintainers besides
+ the one named in the <qref id="f-Maintainer">Maintainer
+ field</qref>, their names and email addresses should be listed
+ here. The format of each entry is the same as that of the
+ Maintainer field, and multiple entries must be comma
+ separated.
+ </p>
+
+ <p>
+ This is normally an optional field, but if
+ the <tt>Maintainer</tt> control field names a group of people
+ and a shared email address, the <tt>Uploaders</tt> field must
+ be present and must contain at least one human with their
+ personal email address.
</p>
<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
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>
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>
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>shilbs</tt>
+ the <qref id="sharedlibs-shlibdeps"><tt>shlibs</tt>
system</qref> or via symbols files (see
<manref name="deb-symbols" section="5">).
</p>
(<prgn>ld</prgn>) when compiling packages, as it will only look for
<file>libgdbm.so</file> when compiling dynamically.
</p>
+
+ <p>
+ If the package provides Ada Library Information
+ (<file>*.ali</file>) files for use with GNAT, these files must be
+ installed read-only (mode 0444) so that GNAT will not attempt to
+ recompile them. This overrides the normal file mode requirements
+ given in <ref id="permissions-owners">.
+ </p>
</sect>
<sect id="sharedlibs-intradeps">
<p>
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