<enumlist>
<item>Russ Allbery</item>
<item>Bill Allombert</item>
- <item>Andrew McMillan</item>
- <item>Manoj Srivastava</item>
- <item>Colin Watson</item>
+ <item>Andreas Barth</item>
+ <item>Jonathan Nieder</item>
</enumlist>
</p>
<p>
Essential is defined as the minimal set of functionality that
must be available and usable on the system at all times, even
- when packages are in an unconfigured (but unpacked) state.
+ when packages are in the "Unpacked" state.
Packages are tagged <tt>essential</tt> for a system using the
<tt>Essential</tt> control field. The format of the
<tt>Essential</tt> control field is described in <ref
installed together. If <prgn>update-alternatives</prgn>
is not used, then each package must use
<tt>Conflicts</tt> to ensure that other packages are
- de-installed. (In this case, it may be appropriate to
+ removed. (In this case, it may be appropriate to
specify a conflict against earlier versions of something
that previously did not use
<prgn>update-alternatives</prgn>; this is an exception to
<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.<footnote>
- If the developer uploading the package is not one of the usual
- maintainers of the package (as listed in
+ should be the details of the person who prepared this release of
+ the package. They are <em>not</em> necessarily those of the
+ uploader or usual package maintainer.<footnote>
+ In the case of a sponsored upload, the uploader signs the
+ files, but the changelog maintainer name and address are those
+ of the person who prepared this release. If the preparer of
+ the release is not one of the usual maintainers of the package
+ (as listed in
the <qref id="f-Maintainer"><tt>Maintainer</tt></qref>
or <qref id="f-Uploaders"><tt>Uploaders</tt></qref> control
fields of the package), the first line of the changelog is
<p>
The following targets are required and must be implemented
by <file>debian/rules</file>: <tt>clean</tt>, <tt>binary</tt>,
- <tt>binary-arch</tt>, <tt>binary-indep</tt>, and <tt>build</tt>.
+ <tt>binary-arch</tt>, <tt>binary-indep</tt>, <tt>build</tt>,
+ <tt>build-arch</tt> and <tt>build-indep</tt>.
These are the targets called by <prgn>dpkg-buildpackage</prgn>.
</p>
any target that these targets depend on must also be
non-interactive.
</p>
+ <p>
+ For packages in the main archive, no required targets
+ may attempt network access.
+ </p>
<p>
The targets are as follows:
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
+ package. This is used Debian QA
tools to help with quality control and maintenance of the
distribution as a whole.
</p>
composed of US-ASCII characters excluding control characters,
space, and colon (i.e., characters in the ranges 33-57 and
59-126, inclusive). Field names must not begin with the comment
- character, <tt>#</tt>.
+ character, <tt>#</tt>, nor with the hyphen character, <tt>-</tt>.
</p>
<p>
the field name is <tt>Package</tt> and the field value
<tt>libc6</tt>.
</p>
-
+ <p> Empty field values are only permitted in source package control files
+ (<file>debian/control</file>). Such fields are ignored.
+ </p>
<p>
A paragraph must not contain more than one instance of a
particular field name.
file. These tools are responsible for removing the line
breaks from such fields when using fields from
<file>debian/control</file> to generate other control files.
+ They are also responsible for discarding empty fields.
</p>
<p>
<item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
<item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
<item><qref id="f-VCS-fields"><tt>Vcs-Browser</tt>, <tt>Vcs-Git</tt>, et al.</qref></item>
+ <item><qref id="f-Dgit"><tt>Dgit</tt></qref></item>
<item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
<item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
<item><qref id="f-Package-List"><tt>Package-List</tt></qref> (recommended)</item>
<p>
The special value <tt>byhand</tt> for the section in a
<tt>.changes</tt> file indicates that the file in question
- is not an ordinary package file and must by installed by
+ is not an ordinary package file and must be installed by
hand by the distribution maintainers. If the section is
<tt>byhand</tt> the priority should be <tt>-</tt>.
</p>
this value is assumed for paragraphs lacking this field.
</p>
</sect1>
+
+ <sect1 id="f-Dgit">
+ <heading><tt>Dgit</tt></heading>
+
+ <p>
+ Folded field containing a single git commit hash, presented in
+ full, followed optionally by whitespace and other data to be
+ defined in future extensions.
+ </p>
+
+ <p>
+ Declares that the source package corresponds exactly to a
+ referenced commit in a Git repository available at the canonical
+ location called <em>dgit-repos</em>, used by <prgn>dgit</prgn>, a
+ bidirectional gateway between the Debian archive and Git. The
+ commit is reachable from at least one reference whose name matches
+ <tt>refs/dgit/*</tt>. See the manual page of <prgn>dgit</prgn> for
+ further details.
+ </p>
+ </sect1>
</sect>
<sect>
pre-dependencies (<tt>Pre-Depends</tt>) may be assumed to be
available. Pre-dependencies will have been configured at
least once, but at the time the <prgn>preinst</prgn> is
- called they may only be in an unpacked or "Half-Configured"
+ called they may only be in an "Unpacked" or "Half-Configured"
state if a previous version of the pre-dependency was
completely configured and has not been removed since then.
</item>
partly from the new version or partly missing, so the script
cannot rely on files included in the package. Package
dependencies may not be available. Pre-dependencies will be
- at least unpacked following the same rules as above, except
+ at least "Unpacked" following the same rules as above, except
they may be only "Half-Installed" if an upgrade of the
pre-dependency failed.<footnote>
This can happen if the new version of the package no
<var>most-recently-configured-version</var></tag>
<item>
The files contained in the package will be unpacked. All
- package dependencies will at least be unpacked. If there
+ package dependencies will at least be "Unpacked". If there
are no circular dependencies involved, all package
dependencies will be configured. For behavior in the case
of circular dependencies, see the discussion
will have previously been configured and not removed.
However, dependencies may not be configured or even fully
unpacked in some error situations.<footnote>
- For example, suppose packages foo and bar are installed
+ For example, suppose packages foo and bar are "Installed"
with foo depending on bar. If an upgrade of bar were
started and then aborted, and then an attempt to remove
foo failed because its <prgn>prerm</prgn> script failed,
at least "Half-Installed". All package dependencies will at
least be "Half-Installed" and will have previously been
configured and not removed. If there was no error, all
- dependencies will at least be unpacked, but these actions
+ dependencies will at least be "Unpacked", but these actions
may be called in various error states where dependencies are
only "Half-Installed" due to a partial upgrade.
</item>
The <prgn>postrm</prgn> script is called after the package's
files have been removed or replaced. The package
whose <prgn>postrm</prgn> is being called may have
- previously been deconfigured and only be unpacked, at which
+ previously been deconfigured and only be "Unpacked", at which
point subsequent package changes do not consider its
dependencies. Therefore, all <prgn>postrm</prgn> actions
may only rely on essential packages and must gracefully skip
<item>
<enumlist>
<item>
- If a version of the package is already installed, call
+ If a version of the package is already "Installed", call
<example compact="compact">
<var>old-prerm</var> upgrade <var>new-version</var>
</example>
<item>
Otherwise, if the package had some configuration
files from a previous version installed (i.e., it
- is in the "configuration files only" state):
+ is in the "Config-Files" state):
<example compact="compact">
<var>new-preinst</var> install <var>old-version</var>
</example>
If the error-unwind fails, the package is in a
"Half-Installed" phase, and requires a
reinstall. If the error unwind works, the
- package is in a not installed state.
+ package is in the "Not-Installed" state.
</item>
</enumlist>
</item>
</item>
<item>
It is noted in the status database as being in a
- sane state, namely not installed (any conffiles
+ sane state, namely "Not-Installed" (any conffiles
it may have are ignored, rather than being
removed by <prgn>dpkg</prgn>). Note that
disappearing packages do not have their prerm
<item>
<p>
The new package's status is now sane, and recorded as
- "unpacked".
+ "Unpacked".
</p>
<p>
<p>
No attempt is made to unwind after errors during
configuration. If the configuration fails, the package is in
- a "Failed Config" state, and an error message is generated.
+ a "Half-Configured" state, and an error message is generated.
</p>
<p>
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,
- if any one of the alternative packages is installed, that
- part of the dependency is considered to be satisfied.
+ that part of the dependency can be satisfied by any one of
+ the alternative packages.
</p>
<p>
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 in the "Half-Configured"
+ package(s) are only in the "Unpacked" or the "Half-Configured"
state, 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
+ previously-configured and currently "Unpacked" or
"Half-Configured" versions must satisfy any version
clause in the <tt>Pre-Depends</tt> field.
</p>
<prgn>dpkg</prgn> does not know of any files it still
contains, it is considered to have "disappeared". It will
be marked as not wanted on the system (selected for
- removal) and not installed. Any <tt>conffile</tt>s
+ 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
exceptions to the FHS apply:
<enumlist>
+ <item>
+ <p>
+ The FHS requirement that architecture-independent
+ application-specific static files be located in
+ <file>/usr/share</file> is relaxed to a suggestion.
+
+ In particular, a subdirectory of <file>/usr/lib</file> may
+ be used by a package (or a collection of packages) to hold a
+ mixture of architecture-independent and
+ architecture-dependent files. However, when a directory is
+ entirely composed of architecture-independent files, it
+ should be located in <file>/usr/share</file>.
+ </p>
+ </item>
<item>
<p>
The optional rules related to user specific
<footnote>
This is necessary in order to reserve the directories for
use in cross-installation of library packages from other
- architectures, as part of the planned deployment of
- <tt>multiarch</tt>.
+ architectures, as part of <tt>multiarch</tt>.
+ </footnote>
+ </p>
+ <p>
+ The requirement for C and C++ headers files to be
+ accessible through the search path
+ <file>/usr/include/</file> is amended, permitting files to
+ be accessible through the search path
+ <file>/usr/include/<var>triplet</var></file> where
+ <tt><var>triplet</var></tt> is as above. <footnote>
+ This is necessary for architecture-dependant headers
+ file to coexist in a <tt>multiarch</tt> setup.
</footnote>
</p>
<p>
stable release of Debian supports <file>/run</file>.
</p>
</item>
- <item>
+ <item>
+ <p>
+ The <file>/sys</file> directory in the root filesystem is
+ additionally allowed. <footnote>This directory is used as
+ mount point to mount virtual filesystems to get access to
+ kernel information.</footnote>
+ </p>
+ </item>
+ <item>
<p>
- The following directories in the root filesystem are
- additionally allowed: <file>/sys</file> and
- <file>/selinux</file>. <footnote>These directories
- are used as mount points to mount virtual filesystems
- to get access to kernel information.</footnote>
+ The <file>/var/www</file> directory is additionally allowed.
</p>
- </item>
+ </item>
+ <item>
+ <p>
+ The requirement for <file>/usr/local/lib<qual></file>
+ to exist if <file>/lib<qual></file> or
+ <file>/usr/lib<qual></file> exists (where
+ <file>lib<qual></file> is a variant of
+ <file>lib</file> such as <file>lib32</file> or
+ <file>lib64</file>) is removed.
+ </p>
+ </item>
<item>
<p>
On GNU/Hurd systems, the following additional
</item>
<tag>65535:</tag>
+ <item>
+ <p>
+ This value <em>must not</em> be used, because it was
+ the error return sentinel value when <tt>uid_t</tt>
+ was 16 bits.
+ </p>
+ </item>
+
+ <tag>65536-4294967293:</tag>
+ <item>
+ <p>
+ Dynamically allocated user accounts. By
+ default <prgn>adduser</prgn> will not allocate UIDs
+ and GIDs in this range, to ease compatibility with
+ legacy systems where <tt>uid_t</tt> is still 16
+ bits.
+ </p>
+ </item>
+
+ <tag>4294967294:</tag>
+ <item>
+ <p>
+ <tt>(uid_t)(-2) == (gid_t)(-2)</tt> <em>must not</em> be
+ used, because it is used as the anonymous, unauthenticated
+ user by some NFS implementations.
+ </p>
+ </item>
+
+ <tag>4294967295:</tag>
<item>
<p>
<tt>(uid_t)(-1) == (gid_t)(-1)</tt> <em>must
renamed. If a consensus cannot be reached, <em>both</em>
programs must be renamed.
</p>
-
+ <p>
+ Binary executables must not be statically linked with the GNU C
+ library, since this prevents the binary from benefiting from
+ fixes and improvements to the C library without being rebuilt
+ and complicates security updates. This requirement may be
+ relaxed for binary executables whose intended purpose is to
+ diagnose and fix the system in situations where the GNU C
+ library may not be usable (such as system recovery shells or
+ utilities like ldconfig) or for binary executables where the
+ security benefits of static linking outweigh the drawbacks.
+ </p>
<p>
By default, when a package is being built, any binaries
created should include debugging information, as well as
would point to <file>/srv/run</file> rather than the intended
target.
</footnote>
+ Symbolic links must not traverse above the root directory.
</p>
<p>
</p>
<p>
- A symbolic link pointing to a compressed file should always
+ A symbolic link pointing to a compressed file (in the sense
+ that it is meant to be uncompressed with <prgn>unzip</prgn>
+ or <prgn>zless</prgn> etc.) should always
have the same file extension as the referenced file. (For
example, if a file <file>foo.gz</file> is referenced by a
symbolic link, the filename of the link has to end with
package is purged.
</item>
</list>
- Obsolete configuration files without local changes may be
- removed by the package during upgrade.
+ Obsolete configuration files without local changes should be
+ removed by the package during upgrade.<footnote>
+ The <prgn>dpkg-maintscript-helper</prgn> tool, available from the
+ <package>dpkg</package> package, can help for this task.</footnote>
</p>
<p>
</p>
</sect1>
</sect>
+
+ <sect id="filenames">
+ <heading>File names</heading>
+
+ <p>
+ The name of the files installed by binary packages in the system PATH
+ (namely <tt>/bin</tt>, <tt>/sbin</tt>, <tt>/usr/bin</tt>,
+ <tt>/usr/sbin</tt> and <tt>/usr/games</tt>) must be encoded in
+ ASCII.
+ </p>
+
+ <p>
+ The name of the files and directories installed by binary packages
+ outside the system PATH must be encoded in UTF-8 and should be
+ restricted to ASCII when it is possible to do so.
+ </p>
+ </sect>
</chapt>
Cgi-bin executable files are installed in the
directory
<example compact="compact">
-/usr/lib/cgi-bin/<var>cgi-bin-name</var>
+/usr/lib/cgi-bin
</example>
- or a subdirectory of that directory, and should be
- referred to as
+ or a subdirectory of that directory, and the script
<example compact="compact">
-http://localhost/cgi-bin/<var>cgi-bin-name</var>
+/usr/lib/cgi-bin/.../<var>cgi-bin-name</var>
</example>
- (possibly with a subdirectory name
- before <var>cgi-bin-name</var>).
- </item>
-
- <item>
- <p>Access to HTML documents</p>
-
- <p>
- HTML documents for a package are stored in
- <file>/usr/share/doc/<var>package</var></file>
- and can be referred to as
+ should be referred to as
<example compact="compact">
-http://localhost/doc/<var>package</var>/<var>filename</var>
+http://localhost/cgi-bin/.../<var>cgi-bin-name</var>
</example>
- </p>
+ </item>
- <p>
- The web server should restrict access to the document
- tree so that only clients on the same host can read
- the documents. If the web server does not support such
- access controls, then it should not provide access at
- all, or ask about providing access during installation.
- </p>
+ <item>
+ <p>(Deleted)</p>
</item>
<item>
<package>doc-base</package> package. If access to the
web document root is unavoidable then use
<example compact="compact">
-/var/www
+/var/www/html
</example>
as the Document Root. This might be just a symbolic
link to the location where the system administrator
</p>
</sect>
- <sect>
+ <sect id="docs-additional">
<heading>Additional documentation</heading>
<p>
- Any additional documentation that comes with the package may
- be installed at the discretion of the package maintainer.
- Plain text documentation should be installed in the directory
- <file>/usr/share/doc/<var>package</var></file>, where
- <var>package</var> is the name of the package, and
- compressed with <tt>gzip -9</tt> unless it is small.
- </p>
+ Any additional documentation that comes with the package may be
+ installed at the discretion of the package maintainer. It is
+ often a good idea to include text information files
+ (<file>README</file>s, FAQs, and so forth) that come with the
+ source package in the binary package. However, you don't need
+ to install the instructions for building and installing the
+ package, of course!
+ </p>
+
+ <p>
+ Plain text documentation should be compressed with <tt>gzip
+ -9</tt> unless it is small.
+ </p>
+
+ <p>
+ If a package comes with large amounts of documentation that many
+ users of the package will not require, you should create a
+ separate binary package to contain it so that it does not take
+ up disk space on the machines of users who do not need or want
+ it installed. As a special case of this rule, shared library
+ documentation of any appreciable size should always be packaged
+ with the library development package (<ref id="sharedlibs-dev">)
+ or in a separate documentation package, since shared libraries
+ are frequently installed as dependencies of other packages by
+ users who have little interest in documentation of the library
+ itself. The documentation package for the
+ package <var>package</var> is conventionally
+ named <var>package</var>-doc
+ (or <var>package</var>-doc-<var>language-code</var> if there are
+ separate documentation packages for multiple languages).
+ </p>
<p>
- If a package comes with large amounts of documentation which
- many users of the package will not require you should create
- a separate binary package to contain it, so that it does not
- take up disk space on the machines of users who do not need
- or want it installed.</p>
+ Additional documentation included in the package should be
+ installed under <file>/usr/share/doc/<var>package</var></file>.
+ If the documentation is packaged separately,
+ as <var>package</var>-doc for example, it may be installed under
+ either that path or into the documentation directory for the
+ separate documentation package
+ (<file>/usr/share/doc/<var>package</var>-doc</file> in this
+ example). However, installing the documentation into the
+ documentation directory of the main package is preferred since
+ it is independent of the packaging method and will be easier for
+ users to find.
+ </p>
<p>
- It is often a good idea to put text information files
- (<file>README</file>s, changelogs, and so forth) that come with
- the source package in <file>/usr/share/doc/<var>package</var></file>
- in the binary package. However, you don't need to install
- the instructions for building and installing the package, of
- course!</p>
+ Any separate package providing documentation must still install
+ standard documentation files in its
+ own <file>/usr/share/doc</file> directory as specified in the
+ rest of this policy. See, for example, <ref id="copyrightfile">
+ and <ref id="changelogs">.
+ </p>
<p>
Packages must not require the existence of any files in
<file>/usr/share/doc/</file> in order to function
<footnote>
- The system administrator should be able to
- delete files in <file>/usr/share/doc/</file> without causing
- any programs to break.
- </footnote>.
- Any files that are referenced by programs but are also
- useful as stand alone documentation should be installed under
- <file>/usr/share/<var>package</var>/</file> with symbolic links from
- <file>/usr/share/doc/<var>package</var></file>.
+ The system administrator should be able to delete files
+ in <file>/usr/share/doc/</file> without causing any programs
+ to break.
+ </footnote>. Any files that are used or read by programs but
+ are also useful as stand alone documentation should be installed
+ elsewhere, such as
+ under <file>/usr/share/<var>package</var>/</file>, and then
+ included via symbolic links
+ in <file>/usr/share/doc/<var>package</var></file>.
</p>
<p>
</p>
</footnote>
</p>
-
- <p>
- Former Debian releases placed all additional documentation
- in <file>/usr/doc/<var>package</var></file>. This has been
- changed to <file>/usr/share/doc/<var>package</var></file>,
- and packages must not put documentation in the directory
- <file>/usr/doc/<var>package</var></file>. <footnote>
- At this phase of the transition, we no longer require a
- symbolic link in <file>/usr/doc/</file>. At a later point,
- policy shall change to make the symbolic links a bug.
- </footnote>
- </p>
</sect>
<sect>
via HTML.</p>
<p>
- If your package comes with extensive documentation in a
+ If the package comes with extensive documentation in a
markup format that can be converted to various other formats
you should if possible ship HTML versions in a binary
- package, in the directory
- <file>/usr/share/doc/<var>appropriate-package</var></file> or
- its subdirectories.<footnote>
- The rationale: The important thing here is that HTML
- docs should be available in <em>some</em> package, not
- necessarily in the main binary package.
+ package.<footnote>
+ Rationale: The important thing here is that HTML
+ documentation should be available from <em>some</em>
+ binary package.
</footnote>
+ The documentation must be installed as specified in
+ <ref id="docs-additional">.
</p>
<p>
projects / debian / debian-policy.git / blobdiff