distributed in some other way or is intended for local use
only.
</p>
+
+ <p>
+ udebs (stripped-down binary packages used by the Debian Installer) do
+ not comply with all of the requirements discussed here. See the
+ <url name="Debian Installer internals manual"
+ id="http://d-i.alioth.debian.org/doc/internals/ch03.html"> for more
+ information about them.
+ </p>
</sect>
<sect>
<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>
The Debian archive maintainers provide the authoritative
list of sections. At present, they are:
- <em>admin</em>, <em>cli-mono</em>, <em>comm</em>, <em>database</em>,
- <em>devel</em>, <em>debug</em>, <em>doc</em>, <em>editors</em>,
- <em>education</em>, <em>electronics</em>, <em>embedded</em>,
- <em>fonts</em>, <em>games</em>, <em>gnome</em>, <em>graphics</em>,
- <em>gnu-r</em>, <em>gnustep</em>, <em>hamradio</em>, <em>haskell</em>,
- <em>httpd</em>, <em>interpreters</em>, <em>introspection</em>,
- <em>java</em>, <em>kde</em>, <em>kernel</em>, <em>libs</em>,
- <em>libdevel</em>, <em>lisp</em>, <em>localization</em>,
- <em>mail</em>, <em>math</em>, <em>metapackages</em>, <em>misc</em>,
- <em>net</em>, <em>news</em>, <em>ocaml</em>, <em>oldlibs</em>,
- <em>otherosfs</em>, <em>perl</em>, <em>php</em>, <em>python</em>,
- <em>ruby</em>, <em>science</em>, <em>shells</em>, <em>sound</em>,
- <em>tex</em>, <em>text</em>, <em>utils</em>, <em>vcs</em>,
- <em>video</em>, <em>web</em>, <em>x11</em>, <em>xfce</em>,
- <em>zope</em>. The additional section <em>debian-installer</em>
+admin,
+cli-mono,
+comm,
+database,
+debug,
+devel,
+doc,
+editors,
+education,
+electronics,
+embedded,
+fonts,
+games,
+gnome,
+gnu-r,
+gnustep,
+graphics,
+hamradio,
+haskell,
+httpd,
+interpreters,
+introspection,
+java,
+kde,
+kernel,
+libdevel,
+libs,
+lisp,
+localization,
+mail,
+math,
+metapackages,
+misc,
+net,
+news,
+ocaml,
+oldlibs,
+otherosfs,
+perl,
+php,
+python,
+ruby,
+science,
+shells,
+sound,
+tasks,
+tex,
+text,
+utils,
+vcs,
+video,
+web,
+x11,
+xfce,
+zope.
+ The additional section <em>debian-installer</em>
contains special packages used by the installer and is not used
for normal Debian packages.
</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
The package installation scripts should avoid producing
output which is unnecessary for the user to see and
should rely on <prgn>dpkg</prgn> to stave off boredom on
- the part of a user installing many packages. This means,
- amongst other things, using the <tt>--quiet</tt> option on
- <prgn>install-info</prgn>.
+ the part of a user installing many packages. This means,
+ amongst other things, not passing the <tt>--verbose</tt>
+ option to <prgn>update-alternatives</prgn>.
</p>
<p>
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
/closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i
</example>
Then all of the bug numbers listed will be closed by the
- archive maintenance script (<prgn>katie</prgn>) using the
+ archive maintenance software (<prgn>dak</prgn>) using the
<var>version</var> of the changelog entry.
</footnote>
This information is conveyed via the <tt>Closes</tt> field
<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:
</p>
</item>
- <tag><tt>build-arch</tt> (optional),
- <tt>build-indep</tt> (optional)
+ <tag><tt>build-arch</tt> (required),
+ <tt>build-indep</tt> (required)
</tag>
<item>
<p>
- A package may also provide one or both of the targets
- <tt>build-arch</tt> and <tt>build-indep</tt>.
- The <tt>build-arch</tt> target, if provided, should
+ The <tt>build-arch</tt> target must
perform all the configuration and compilation required for
producing all architecture-dependant binary packages
(those packages for which the body of the
<tt>Architecture</tt> field in <tt>debian/control</tt> is
not <tt>all</tt>). Similarly, the <tt>build-indep</tt>
- target, if provided, should perform all the configuration
+ target must perform all the configuration
and compilation required for producing all
architecture-independent binary packages (those packages
for which the body of the <tt>Architecture</tt> field
in <tt>debian/control</tt> is <tt>all</tt>).
- </p>
-
- <p>
- If <tt>build-arch</tt> or <tt>build-indep</tt> targets are
- provided in the rules file, the <tt>build</tt> target
+ The <tt>build</tt> target
should either depend on those targets or take the same
actions as invoking those targets would perform.<footnote>
- The intent of this split is so that binary-only builds
- need not install the dependencies required for
- the <tt>build-indep</tt> target. However, this is not
- yet used in practice since <tt>dpkg-buildpackage
- -B</tt>, and therefore the autobuilders,
- invoke <tt>build</tt> rather than <tt>build-arch</tt>
- due to the difficulties in determining whether the
- optional <tt>build-arch</tt> target exists.
+ This split allows binary-only builds to not install the
+ dependencies required for the <tt>build-indep</tt>
+ target and skip any resource-intensive build tasks that
+ are only required when building architecture-independent
+ binary packages.
</footnote>
</p>
- <p>
- If one or both of the targets <tt>build-arch</tt> and
- <tt>build-indep</tt> are not provided, then invoking
- <file>debian/rules</file> with one of the not-provided
- targets as arguments should produce a exit status code
- of 2. Usually this is provided automatically by make
- if the target is missing.
- </p>
-
<p>
The <tt>build-arch</tt> and <tt>build-indep</tt> targets
must not do anything that might require root privilege.
<p>
The architectures we build on and build for are determined
by <prgn>make</prgn> variables using the
- utility <qref id="pkg-dpkg-architecture"><prgn>dpkg-architecture</prgn></qref>.
+ utility <prgn>dpkg-architecture</prgn>.
You can determine the Debian architecture and the GNU style
architecture specification string for the build architecture as
well as for the host architecture. The build architecture is
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.
<item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
<item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
<item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
- <item><qref id="f-DM-Upload-Allowed"><tt>DM-Upload-Allowed</tt></qref></item>
<item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
<item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
<item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
<item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</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>
</list>
</p>
<item><qref id="binarydeps"><tt>Depends</tt> et al</qref></item>
<item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
<item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
+ <item><qref id="built-using"><tt>Built-Using</tt></qref></item>
+ <item><qref id="f-Package-Type"><tt>Package-Type</tt></qref></item>
</list>
</p>
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-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
<item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
<item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
+ <item><qref id="built-using"><tt>Built-Using</tt></qref></item>
</list>
</p>
</sect>
<item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
<item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
<item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
- <item><qref id="f-DM-Upload-Allowed"><tt>DM-Upload-Allowed</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>
<item><qref id="f-Checksums"><tt>Checksums-Sha1</tt>
- and <tt>Checksums-Sha256</tt></qref> (recommended)</item>
+ and <tt>Checksums-Sha256</tt></qref> (mandatory)</item>
<item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
</list>
</p>
<item><qref id="f-Closes"><tt>Closes</tt></qref></item>
<item><qref id="f-Changes"><tt>Changes</tt></qref> (mandatory)</item>
<item><qref id="f-Checksums"><tt>Checksums-Sha1</tt>
- and <tt>Checksums-Sha256</tt></qref> (recommended)</item>
+ and <tt>Checksums-Sha256</tt></qref> (mandatory)</item>
<item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
</list>
</p>
<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>
</p>
<p>
- In the <file>.dsc</file> file, these fields should list all
+ In the <file>.dsc</file> file, these fields list all
files that make up the source package. In
- the <file>.changes</file> file, these fields should list all
+ the <file>.changes</file> file, these fields list all
files being uploaded. The list of files in these fields
must match the list of files in the <tt>Files</tt> field.
</p>
</sect1>
- <sect1 id="f-DM-Upload-Allowed">
+ <sect1>
<heading><tt>DM-Upload-Allowed</tt></heading>
<p>
- Indicates that Debian Maintainers may upload this package to
- the Debian archive. The only valid value is <tt>yes</tt>. If
- the field <tt>DM-Upload-Allowed: yes</tt> is present in the
- source section of the source control file of the most recent
- version of a package in unstable or experimental, the Debian
- archive will accept uploads of this package signed with a key
- in the Debian Maintainer keyring. See the General
- Resolution <url id="http://www.debian.org/vote/2007/vote_003"
- name="Endorse the concept of Debian Maintainers"> for more
- details.
+ Obsolete, see <qref id="f-DM-Upload-Allowed">below</qref>.
+ </p>
+ </sect1>
+
+ <sect1 id="f-VCS-fields">
+ <heading>Version Control System (VCS) fields</heading>
+
+ <p>
+ Debian source packages are increasingly developed using VCSs. The
+ purpose of the following fields is to indicate a publicly accessible
+ repository where the Debian source package is developed.
+
+ <taglist>
+ <tag><tt>Vcs-Browser</tt></tag>
+ <item>
+ <p>
+ URL of a web interface for browsing the repository.
+ </p>
+ </item>
+
+ <tag>
+ <tt>Vcs-Arch</tt>, <tt>Vcs-Bzr</tt> (Bazaar), <tt>Vcs-Cvs</tt>,
+ <tt>Vcs-Darcs</tt>, <tt>Vcs-Git</tt>, <tt>Vcs-Hg</tt>
+ (Mercurial), <tt>Vcs-Mtn</tt> (Monotone), <tt>Vcs-Svn</tt>
+ (Subversion)
+ </tag>
+ <item>
+ <p>
+ The field name identifies the VCS. The field's value uses the
+ version control system's conventional syntax for describing
+ repository locations and should be sufficient to locate the
+ repository used for packaging. Ideally, it also locates the
+ branch used for development of new versions of the Debian
+ package.
+ </p>
+ <p>
+ In the case of Git, the value consists of a URL, optionally
+ followed by the word <tt>-b</tt> and the name of a branch in
+ the indicated repository, following the syntax of the
+ <tt>git clone</tt> command. If no branch is specified, the
+ packaging should be on the default branch.
+ </p>
+ <p>
+ More than one different VCS may be specified for the same
+ package.
+ </p>
+ </item>
+ </taglist>
+ </p>
+ </sect1>
+
+ <sect1 id="f-Package-List">
+ <heading><tt>Package-List</tt></heading>
+
+ <p>
+ Multiline field listing all the packages that can be built from
+ the source package, considering every architecture. The first line
+ of the field value is empty. Each one of the next lines describes
+ one binary package, by listing its name, type, section and priority
+ separated by spaces. Fifth and subsequent space-separated items
+ may be present and parsers must allow them. See the
+ <qref id="f-Package-Type">Package-Type</qref> field for a list of
+ package types.
+ </p>
+ </sect1>
+
+ <sect1 id="f-Package-Type">
+ <heading><tt>Package-Type</tt></heading>
+
+ <p>
+ Simple field containing a word indicating the type of package:
+ <tt>deb</tt> for binary packages and <tt>udeb</tt> for micro binary
+ packages. Other types not defined here may be indicated. In
+ source package control files, the <tt>Package-Type</tt> field
+ should be omitted instead of giving it a value of <tt>deb</tt>, as
+ 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>
+ <sect id="obsolete-control-data-fields">
+ <heading>Obsolete fields</heading>
+
+ <p>
+ The following fields have been obsoleted and may be found in packages
+ conforming with previous versions of the Policy.
+ </p>
+
+ <sect1 id="f-DM-Upload-Allowed">
+ <heading><tt>DM-Upload-Allowed</tt></heading>
+
+ <p>
+ Indicates that Debian Maintainers may upload this package to
+ the Debian archive. The only valid value is <tt>yes</tt>. This
+ field was used to regulate uploads by Debian Maintainers, See the
+ General Resolution <url id="http://www.debian.org/vote/2007/vote_003"
+ name="Endorse the concept of Debian Maintainers"> for more details.
+ </p>
+ </sect1>
+
+ </sect>
+
</chapt>
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>,
+ programs <prgn>ldconfig</prgn>, <prgn>start-stop-daemon</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 be in the
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>
<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 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).
+ <tt>=</tt>, <tt>>=</tt> and <tt>>></tt> for strictly
+ earlier, earlier or equal, exactly equal, later or equal and
+ strictly later, respectively. The deprecated
+ forms <tt><</tt> and <tt>></tt> were confusingly used to
+ mean earlier/later or equal, rather than strictly earlier/later,
+ and must not appear in new packages (though <prgn>dpkg</prgn>
+ still supports them with a warning).
</p>
<p>
</p>
<p>
- For binary relationship fields, the architecture restriction
+ For binary relationship fields and the <tt>Built-Using</tt>
+ field, the architecture restriction
syntax is only supported in the source package control
file <file>debian/control</file>. When the corresponding binary
package control file is generated, the relationship will either
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
</taglist>
</p>
</sect>
+
+ <sect id="built-using">
+ <heading>Additional source packages used to build the binary
+ - <tt>Built-Using</tt>
+ </heading>
+
+ <p>
+ Some binary packages incorporate parts of other packages when built
+ but do not have to depend on those packages. Examples include
+ linking with static libraries or incorporating source code from
+ another package during the build. In this case, the source packages
+ of those other packages are a required part of the complete source
+ (the binary package is not reproducible without them).
+ </p>
+
+ <p>
+ A <tt>Built-Using</tt> field must list the corresponding source
+ package for any such binary package incorporated during the build
+ <footnote>
+ <tt>Build-Depends</tt> in the source package is not adequate since
+ it (rightfully) does not document the exact version used in the
+ build.
+ </footnote>,
+ including an "exactly equal" ("=") version relation on the version
+ that was used to build that binary package<footnote>
+ The archive software might reject packages that refer to
+ non-existent sources.
+ </footnote>.
+ </p>
+
+ <p>
+ A package using the source code from the gcc-4.6-source
+ binary package built from the gcc-4.6 source package would
+ have this field in its control file:
+ <example compact="compact">
+Built-Using: gcc-4.6 (= 4.6.0-11)
+ </example>
+ </p>
+
+ <p>
+ A package including binaries from grub2 and loadlin would
+ have this field in its control file:
+ <example compact="compact">
+Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
+ </example>
+ </p>
+ </sect>
</chapt>
<p>
To determine the <var>soversion</var>, look at
the <tt>SONAME</tt> of the library, stored in the
- ELF <tt>SONAME</tt> attribute. it is usually of the
+ ELF <tt>SONAME</tt> attribute. It is usually of the
form <tt><var>name</var>.so.<var>major-version</var></tt> (for
example, <tt>libz.so.1</tt>). The version part is the part
which comes after <tt>.so.</tt>, so in that example it
whether new library interfaces are available and can be called).
To allow these dependencies to be constructed, shared libraries
must provide either a <file>symbols</file> file or
- a <file>shlibs</file> file, which provide information on the
- package dependencies required to ensure the presence of this
- library. Any package which uses a shared library must use these
- files to determine the required dependencies when it is built.
- </p>
-
- <p>
- These two mechanisms differ in the degree of detail that they
- provide. A <file>symbols</file> file documents every symbol
- that is part of the library ABI and, for each, the version of
- the package in which it was introduced. This permits detailed
- analysis of the symbols used by a particular package and
- construction of an accurate dependency, but it requires the
- package maintainer to track more information about the shared
- library. A <file>shlibs</file> file, in contrast, only
- documents the last time the library ABI changed in any way. It
- only provides information about the library as a whole, not
- individual symbols. When a package is built using a shared
- library with only a <file>shlibs</file> file, the generated
- dependency will require a version of the shared library equal to
- or newer than the version of the last ABI change. This
- generates unnecessarily restrictive dependencies compared
+ a <file>shlibs</file> file. These provide information on the
+ package dependencies required to ensure the presence of
+ interfaces provided by this library. Any package with binaries
+ or libraries linking to a shared library must use these files to
+ determine the required dependencies when it is built. Other
+ packages which use a shared library (for example using
+ <tt>dlopen()</tt>) should compute appropriate dependencies
+ using these files at build time as well.
+ </p>
+
+ <p>
+ The two mechanisms differ in the degree of detail that they
+ provide. A <file>symbols</file> file documents, for each symbol
+ exported by a library, the minimal version of the package any
+ binary using this symbol will need. This is typically the
+ version of the package in which the symbol was introduced. This
+ information permits detailed analysis of the symbols used by a
+ particular package and construction of an accurate dependency,
+ but it requires the package maintainer to track more information
+ about the shared library.
+ </p>
+
+ <p>
+ A <file>shlibs</file> file, in contrast, only documents the last
+ time the library ABI changed in any way. It only provides
+ information about the library as a whole, not individual
+ symbols. When a package is built using a shared library with
+ only a <file>shlibs</file> file, the generated dependency will
+ require a version of the shared library equal to or newer than
+ the version of the last ABI change. This generates
+ unnecessarily restrictive dependencies compared
to <file>symbols</file> files if none of the symbols used by the
package have changed. This, in turn, may make upgrades
needlessly complex and unnecessarily restrict use of the package
</p>
<p>
- <file>shlibs<file> files also have a flawed representation of
+ <file>shlibs</file> files also only support a limited range of
library SONAMEs, making it difficult to use <file>shlibs</file>
- files in some unusual corner cases.
+ files in some unusual corner cases.<footnote>
+ A <file>shlibs</file> file represents an SONAME as a library
+ name and version number, such as <tt>libfoo VERSION</tt>,
+ instead of recording the actual SONAME. If the SONAME doesn't
+ match one of the two expected formats
+ (<tt>libfoo-VERSION.so</tt> or <tt>libfoo.so.VERSION</tt>), it
+ cannot be represented.
+ </footnote>
</p>
<p>
required by <file>symbols</file> files is not too difficult to
maintain. However, maintaining exhaustive symbols information
for a C++ library can be quite onerous, so <file>shlibs</file>
- files may be more appropriate for most C++ libraries. udebs
- must also use <file>shlibs</file>, since the udeb infrastructure
- does not use <file>symbols</file>.
+ files may be more appropriate for most C++ libraries. Libraries
+ with a corresponding udeb must also provide
+ a <file>shlibs</file> file, since the udeb infrastructure does
+ not use <file>symbols</file> files.
</p>
<sect1 id="dpkg-shlibdeps">
binaries, libraries, or loadable modules. If you have
multiple binary packages, you will need to
call <prgn>dpkg-shlibdeps</prgn> on each one which contains
- compiled libraries or binaries, using the <tt>-T</tt> option
- to the <tt>dpkg</tt> utilities to specify a
- different <file>substvars</file> file for each binary
- package.<footnote>
+ compiled libraries or binaries. For example, you could use
+ the <tt>-T</tt> option to the <tt>dpkg</tt> utilities to
+ specify a different <file>substvars</file> file for each
+ binary package.<footnote>
Again, <prgn>dh_shlibdeps</prgn>
and <prgn>dh_gencontrol</prgn> will handle everything except
the addition of the variable to the control file for you if
linked <em>indirectly</em> to <tt>foo</tt>, and the dynamic
linker will load them automatically when it
loads <tt>libbar</tt>. A package should depend on the
- libraries it directly uses, but not the libraries it
- indirectly uses. The dependencies for the libraries used
+ libraries it directly uses, but not the libraries it only uses
+ indirectly. The dependencies for the libraries used
directly will automatically pull in the indirectly-used
libraries. <prgn>dpkg-shlibdeps</prgn> will handle this logic
automatically, but package maintainers need to be aware of
<p>
There are two types of ABI changes: ones that are
backward-compatible and ones that are not. An ABI change is
- backward-compatible if any binary was linked with the previous
- version of the shared library will still work correctly with
- the new version of the shared library. Adding new symbols to
- the shared library is a backward-compatible change. Removing
- symbols from the shared library is not. Changing the behavior
- of a symbol may or may not be backward-compatible depending on
- the change; for example, changing a function to accept a new
- enum constant not previously used by the library is generally
+ backward-compatible if any reasonable program or library that
+ was linked with the previous version of the shared library
+ will still work correctly with the new version of the shared
+ library.<footnote>
+ An example of an "unreasonable" program is one that uses
+ library interfaces that are documented as internal and
+ unsupported. If the only programs or libraries affected by
+ a change are "unreasonable" ones, other techniques, such as
+ declaring <tt>Breaks</tt> relationships with affected
+ packages or treating their usage of the library as bugs in
+ those packages, may be appropriate instead of changing the
+ SONAME. However, the default approach is to change the
+ SONAME for any change to the ABI that could break a program.
+ </footnote>
+ Adding new symbols to the shared library is a
+ backward-compatible change. Removing symbols from the shared
+ library is not. Changing the behavior of a symbol may or may
+ not be backward-compatible depending on the change; for
+ example, changing a function to accept a new enum constant not
+ previously used by the library is generally
backward-compatible, but changing the members of a struct that
is passed into library functions is generally not unless the
library takes special precautions to accept old versions of
</p>
<p>
- A common example of when a change to the is required is a
- function that takes an enum or struct argument that controls
- what the function does. For example:
+ A common example of when a change to the dependency version
+ is required is a function that takes an enum or struct
+ argument that controls what the function does. For example:
<example>
enum library_op { OP_FOO, OP_BAR };
int library_do_operation(enum library_op);
<p>
<file>symbols</file> files for a shared library are normally
- provided by the shared library package, but there are
- several override paths that are checked first in case that
- information is wrong or missing. The following list gives
- them in the order in which they are read
+ provided by the shared library package as a control file,
+ but there are several override paths that are checked first
+ in case that information is wrong or missing. The following
+ list gives them in the order in which they are read
by <prgn>dpkg-shlibdeps</prgn> The first one that contains
the required information is used.
<list>
recent version of the shared library that changed the
behavior of that symbol, whether by adding it, changing its
function signature (the parameters, their types, or the
- return type), or its behavior in a way that is visible to a
- caller. <var>id-of-dependency-template</var> is an optional
+ return type), or changing its behavior in a way that is
+ visible to a caller.
+ <var>id-of-dependency-template</var> is an optional
field that references
an <var>alternative-dependency-template</var>; see below for
a full description.
compressBound@ZLIB_1.2.0 1:1.2.0
</example>
Packages using only <tt>compress</tt> would then get a
- dependency of <tt>zlib1g (>= 1:1.1.4)</tt>, but packages
+ dependency on <tt>zlib1g (>= 1:1.1.4)</tt>, but packages
using <tt>compressBound</tt> would get a dependency
- of <tt>zlib1g (>= 1:1.2.0)</tt>.
+ on <tt>zlib1g (>= 1:1.2.0)</tt>.
</p>
<p>
<heading>The <tt>shlibs</tt> system</heading>
<p>
- The <tt>shlibs</tt> system is an simpler alternative to
+ The <tt>shlibs</tt> system is a simpler alternative to
the <tt>symbols</tt> system for declaring dependencies for
shared libraries. It may be more appropriate for C++
libraries and other cases where tracking individual symbols is
The <file>shlibs</file> control files for all the
packages currently installed on the system. These are
normally found
- in <file>/var/lib/dpkg/info/*.symbols</file>, but
+ in <file>/var/lib/dpkg/info/*.shlibs</file>, but
packages should not rely on this and instead should
use <tt>dpkg-query --control-path <var>package</var>
shlibs</tt> if for some reason these files need to be
library was in version <tt>1:1.2.3.3.dfsg-1</tt>, then
the <tt>shlibs</tt> entry for this library could say:
<example compact="compact">
- libz 1 zlib1g (>= 1:1.2.3.3.dfsg-1)
+ libz 1 zlib1g (>= 1:1.2.3.3.dfsg)
</example>
This version restriction must be new enough that any binary
built against the current version of the library will work
As zlib1g also provides a udeb containing the shared
library, there would also be a second line:
<example compact="compact">
- udeb: libz 1 zlib1g-udeb (>= 1:1.2.3.3.dfsg-1)
+ udeb: libz 1 zlib1g-udeb (>= 1:1.2.3.3.dfsg)
</example>
</p>
</sect2>
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>
in <file>/run</file> should be stored on a temporary
file system.
</p>
+ <p>
+ Packages must not assume the <file>/run</file>
+ directory exists or is usable without a dependency
+ on <tt>initscripts (>= 2.88dsf-13.3)</tt> until the
+ 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
</p>
<p>
- Packages which provide the ability to view/show/play,
- compose, edit or print MIME types should register themselves
- as such following the current MIME support policy.
+ Packages which provide programs to view/show/play, compose, edit or
+ print MIME types should register them as such by placing a file in
+ <manref name="mailcap" section="5"> format (RFC 1524) in the directory
+ <file>/usr/lib/mime/packages/</file>. The file name should be the
+ binary package's name.
</p>
<p>
The <package>mime-support</package> package provides the
- <prgn>update-mime</prgn> program which allows packages to
- register programs that can show, compose, edit or print
- MIME types.
- </p>
-
- <p>
- Packages containing such programs must register them
- with <prgn>update-mime</prgn> as documented in <manref
- name="update-mime" section="8">. They should <em>not</em> depend
- on, recommend, or suggest <prgn>mime-support</prgn>. Instead,
- they should just put something like the following in the
- <tt>postinst</tt> and <tt>postrm</tt> scripts:
-
- <example>
- if [ -x /usr/sbin/update-mime ]; then
- update-mime
- fi
- </example>
+ <prgn>update-mime</prgn> program, which integrates these
+ registrations in the <file>/etc/mailcap</file> file, using dpkg
+ triggers<footnote>
+ Creating, modifying or removing a file in
+ <file>/usr/lib/mime/packages/</file> using maintainer scripts will
+ not activate the trigger. In that case, it can be done by calling
+ <tt>dpkg-trigger --no-await /usr/lib/mime/packages</tt> from
+ the maintainer script after creating, modifying, or removing
+ the file.
+ </footnote>.
+ Packages using this facility <em>should not</em> depend on,
+ recommend, or suggest <prgn>mime-support</prgn>.
</p>
-
</sect>
<sect>
</p>
</sect>
+ <sect id="alternateinit">
+ <heading>Alternate init systems</heading>
+ <p>
+ A number of other init systems are available now in Debian that
+ can be used in place of <package>sysvinit</package>. Alternative
+ init implementations must support running SysV init scripts as
+ described at <ref id="sysvinit"> for compatibility.
+ </p>
+ <p>
+ Packages may integrate with these replacement init systems by
+ providing implementation-specific configuration information about
+ how and when to start a service or in what order to run certain
+ tasks at boot time. However, any package integrating with other
+ init systems must also be backwards-compatible with
+ <package>sysvinit</package> by providing a SysV-style init script
+ with the same name as and equivalent functionality to any
+ init-specific job, as this is the only start-up configuration
+ method guaranteed to be supported by all init implementations. An
+ exception to this rule is scripts or jobs provided by the init
+ implementation itself; such jobs may be required for an
+ implementation-specific equivalent of the <file>/etc/rcS.d/</file>
+ scripts and may not have a one-to-one correspondence with the init
+ scripts.
+ </p>
+ <sect1 id="upstart">
+ <heading>Event-based boot with upstart</heading>
+
+ <p>
+ Packages may integrate with the <prgn>upstart</prgn> event-based
+ boot system by installing job files in the
+ <file>/etc/init</file> directory. SysV init scripts for which
+ an equivalent upstart job is available must query the output of
+ the command <prgn>initctl version</prgn> for the string
+ <tt>upstart</tt> and avoid running in favor of the native
+ upstart job, using a test such as this:
+ <example compact="compact">
+if [ "$1" = start ] && which initctl >/dev/null && initctl version | grep -q upstart
+then
+ exit 1
+fi
+ </example>
+ </p>
+ <p>
+ Because packages shipping upstart jobs may be installed on
+ systems that are not using upstart, maintainer scripts must
+ still use the common <prgn>update-rc.d</prgn> and
+ <prgn>invoke-rc.d</prgn> interfaces for configuring runlevels
+ and for starting and stopping services. These maintainer
+ scripts must not call the upstart <prgn>start</prgn>,
+ <prgn>restart</prgn>, <prgn>reload</prgn>, or <prgn>stop</prgn>
+ interfaces directly. Instead, implementations of
+ <prgn>invoke-rc.d</prgn> must detect when upstart is running and
+ when an upstart job with the same name as an init script is
+ present, and perform the requested action using the upstart job
+ instead of the init script.
+ </p>
+ <p>
+ Dependency-based boot managers for SysV init scripts, such as
+ <prgn>startpar</prgn>, may avoid running a given init script
+ entirely when an equivalent upstart job is present, to avoid
+ unnecessary forking of no-op init scripts. In this case, the
+ boot manager should integrate with upstart to detect when the
+ upstart job in question is started or stopped to know when the
+ dependency has been satisfied.
+ </p>
+ </sect1>
+ </sect>
+
</chapt>
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>
The <prgn>install-info</prgn> program maintains a directory of
- installed info documents in <file>/usr/share/info/dir</file> for
- the use of info readers.<footnote>
- It was previously necessary for packages installing info
- documents to run <prgn>install-info</prgn> from maintainer
- scripts. This is no longer necessary. The installation
- system now uses dpkg triggers.
- </footnote>
- This file must not be included in packages. Packages containing
- info documents should depend on <tt>dpkg (>= 1.15.4) |
- install-info</tt> to ensure that the directory file is properly
- rebuilt during partial upgrades from Debian 5.0 (lenny) and
- earlier.
+ installed info documents in <file>/usr/share/info/dir</file> for the
+ use of info readers. This file must not be included in packages
+ other than <package>install-info</package>.
+ </p>
+
+ <p>
+ <prgn>install-info</prgn> is automatically invoked when
+ appropriate using dpkg triggers. Packages other than
+ <package>install-info</package> <em>should not</em> invoke
+ <prgn>install-info</prgn> directly and <em>should not</em>
+ depend on, recommend, or suggest <package>install-info</package>
+ for this purpose.
+ </p>
+
+ <p>
+ Info readers requiring the <file>/usr/share/info/dir</file> file
+ should depend on <package>install-info</package>.
</p>
<p>
</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>
- 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>
+ 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>
+ 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>
<file>README.Debian</file> or some other appropriate place.
</p>
+ <p>
+ All copyright files must be encoded in UTF-8.
+ </p>
+
<sect1 id="copyrightformat">
<heading>Machine-readable copyright information</heading>
<prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and the way
they interact with packages.</p>
- <p>
- It also documents the interaction between
- <prgn>dselect</prgn>'s core and the access method scripts it
- uses to actually install the selected packages, and describes
- how to create a new access method.</p>
-
<p>
This manual does not go into detail about the options and
usage of the package building and installation tools. It
<p>
The utility programs which are provided with <prgn>dpkg</prgn>
- for managing various system configuration and similar issues,
- such as <prgn>update-rc.d</prgn> and
- <prgn>install-info</prgn>, are not described in detail here -
- please see their man pages.
+ not described in detail here, are documented in their man pages.
</p>
<p>
<heading>Binary packages (from old Packaging Manual)</heading>
<p>
- The binary package has two main sections. The first part
- consists of various control information files and scripts used
- by <prgn>dpkg</prgn> when installing and removing. See <ref
- id="pkg-controlarea">.
- </p>
-
- <p>
- The second part is an archive containing the files and
- directories to be installed.
+ See <manref name="deb" section="5"> and <ref id="pkg-controlarea">.
</p>
- <p>
- In the future binary packages may also contain other
- components, such as checksums and digital signatures. The
- format for the archive is described in full in the
- <file>deb(5)</file> man page.
- </p>
-
-
<sect id="pkg-bincreating"><heading>Creating package files -
<prgn>dpkg-deb</prgn>
</heading>
</heading>
<p>
- <prgn>dpkg-buildpackage</prgn> is a script which invokes
- <prgn>dpkg-source</prgn>, the <file>debian/rules</file>
- targets <tt>clean</tt>, <tt>build</tt> and
- <tt>binary</tt>, <prgn>dpkg-genchanges</prgn> and
- <prgn>gpg</prgn> (or <prgn>pgp</prgn>) to build a signed
- source and binary package upload.
- </p>
-
- <p>
- It is usually invoked by hand from the top level of the
- built or unbuilt source directory. It may be invoked with
- no arguments; useful arguments include:
- <taglist compact="compact">
- <tag><tt>-uc</tt>, <tt>-us</tt></tag>
- <item>
- <p>
- Do not sign the <tt>.changes</tt> file or the
- source package <tt>.dsc</tt> file, respectively.</p>
- </item>
- <tag><tt>-p<var>sign-command</var></tt></tag>
- <item>
- <p>
- Invoke <var>sign-command</var> instead of finding
- <tt>gpg</tt> or <tt>pgp</tt> on the <prgn>PATH</prgn>.
- <var>sign-command</var> must behave just like
- <prgn>gpg</prgn> or <tt>pgp</tt>.</p>
- </item>
- <tag><tt>-r<var>root-command</var></tt></tag>
- <item>
- <p>
- When root privilege is required, invoke the command
- <var>root-command</var>. <var>root-command</var>
- should invoke its first argument as a command, from
- the <prgn>PATH</prgn> if necessary, and pass its
- second and subsequent arguments to the command it
- calls. If no <var>root-command</var> is supplied
- then <var>dpkg-buildpackage</var> will use
- the <prgn>fakeroot</prgn> command, which is sufficient
- to build most packages without actually requiring root
- privileges.</p>
- </item>
- <tag><tt>-b</tt>, <tt>-B</tt></tag>
- <item>
- <p>
- Two types of binary-only build and upload - see
- <manref name="dpkg-source" section="1">.
- </p>
- </item>
- </taglist>
+ See <manref name="dpkg-buildpackage" section="1">.
</p>
</sect1>
</heading>
<p>
- This program is usually called by package-independent
- automatic building scripts such as
- <prgn>dpkg-buildpackage</prgn>, but it may also be called
- by hand.
- </p>
-
- <p>
- It is usually called in the top level of a built source
- tree, and when invoked with no arguments will print out a
- straightforward <file>.changes</file> file based on the
- information in the source package's changelog and control
- file and the binary and source packages which should have
- been built.
+ See <manref name="dpkg-genchanges" section="1">.
</p>
</sect1>
-
<sect1 id="pkg-dpkg-parsechangelog">
<heading>
<prgn>dpkg-parsechangelog</prgn> - produces parsed
</heading>
<p>
- This program is used internally by
- <prgn>dpkg-source</prgn> et al. It may also occasionally
- be useful in <file>debian/rules</file> and elsewhere. It
- parses a changelog, <file>debian/changelog</file> by default,
- and prints a control-file format representation of the
- information in it to standard output.
+ See <manref name="dpkg-parsechangelog" section="1">.
</p>
</sect1>
</heading>
<p>
- This program can be used manually, but is also invoked by
- <tt>dpkg-buildpackage</tt> or <file>debian/rules</file> to set
- environment or make variables which specify the build and host
- architecture for the package building process.
+ See <manref name="dpkg-architecture" section="1">.
</p>
</sect1>
</sect>
there is a time, after it has been diverted but before
<prgn>dpkg</prgn> has installed the new version, when the file
does not exist.</p>
+
+ <p>
+ Do not attempt to divert a conffile, as <prgn>dpkg</prgn> does not
+ handle it well.
+ </p>
</appendix>
</book>
projects / debian / debian-policy.git / blobdiff