<tt><url name="/doc/developers-reference/"
id="http://www.debian.org/doc/developers-reference/"></tt>.
</p>
+
+ <p>
+ Finally, a <qref id="copyrightformat">specification for
+ machine-readable copyright files</qref> is maintained as part of
+ the <package>debian-policy</package> package using the same
+ procedure as the other policy documents. Use of this format is
+ optional.
+ </p>
</sect>
<sect id="definitions">
<item>
must not require or recommend a package outside
of <em>main</em> for compilation or execution (thus, the
- package must not declare a "Depends", "Recommends", or
- "Build-Depends" relationship on a non-<em>main</em>
- package),
+ package must not declare a "Pre-Depends", "Depends",
+ "Recommends", "Build-Depends", or "Build-Depends-Indep"
+ relationship on a non-<em>main</em> package),
</item>
<item>
must not be so buggy that we refuse to support them,
</tag>
<item>
<p>
- A package may also provide both of the targets
+ 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
perform all the configuration and compilation required for
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>).
- The <tt>build</tt> target should depend on those of the
- targets <tt>build-arch</tt> and <tt>build-indep</tt> that
- are provided in the rules file.<footnote>
+ </p>
+
+ <p>
+ If <tt>build-arch</tt> or <tt>build-indep</tt> targets are
+ provided in the rules file, 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
</p>
<p>
- Each paragraph consists of a series of data fields; each
- field consists of the field name, followed by a colon and
- then the data/value associated with that field. The field
- name is composed of printable ASCII characters (i.e.,
- characters that have values between 33 and 126, inclusive)
- except colon and must not with a begin with #. The
- field ends at the end of the line or at the end of the
- last continuation line (see below). Horizontal whitespace
- (spaces and tabs) may occur immediately before or after the
- value and is ignored there; it is conventional to put a
- single space after the colon. For example, a field might
- be:
+ Each paragraph consists of a series of data fields. Each field
+ consists of the field name followed by a colon and then the
+ data/value associated with that field. The field name is
+ 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>.
+ </p>
+
+ <p>
+ The field ends at the end of the line or at the end of the last
+ continuation line (see below). Horizontal whitespace (spaces
+ and tabs) may occur immediately before or after the value and is
+ ignored there; it is conventional to put a single space after
+ the colon. For example, a field might be:
<example compact="compact">
Package: libc6
</example>
<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>
</list>
</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>
<p>
This file consists of a single paragraph, possibly surrounded by
a PGP signature. The fields of that paragraph are listed below.
- Their syntax is described above, in <ref id="pkg-controlfields">.
+ Their syntax is described above, in <ref id="controlsyntax">.
<list compact="compact">
<item><qref id="f-Format"><tt>Format</tt></qref> (mandatory)</item>
<heading><tt>DM-Upload-Allowed</tt></heading>
<p>
- The most recent version of a package uploaded to unstable or
- experimental must include the field <tt>DM-Upload-Allowed:
- yes</tt> in the source section of its source control file for
- the Debian archive to accept uploads signed with a key in the
- Debian Maintainer keyring. See the General
+ 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.
<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>
Relationships may be restricted to a certain set of
architectures. This is indicated in brackets after each
individual package name and the optional version specification.
- The brackets enclose a list of Debian architecture names
+ The brackets enclose a non-empty list of Debian architecture names
in the format described in <ref id="arch-spec">,
separated by whitespace. Exclamation marks may be prepended to
each of the names. (It is not permitted for some names to be
</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
</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>
<heading>File System Structure</heading>
<p>
- The location of all installed files and directories must
- comply with the Filesystem Hierarchy Standard (FHS),
- version 2.3, with the exceptions noted below, and except
- where doing so would violate other terms of Debian
- Policy. The following exceptions to the FHS apply:
+ The location of all files and directories must comply with the
+ Filesystem Hierarchy Standard (FHS), version 2.3, with the
+ exceptions noted below, and except where doing so would
+ violate other terms of Debian Policy. The following
+ exceptions to the FHS apply:
<enumlist>
<item>
<item>
<p>
The following directories in the root filesystem are
- additionally allowed: <file>/sys</file>
- and <file>/selinux</file>.
- <footnote>
- The <file>/sys</file> and <file>/selinux</file>
- directories are mount points where
- virtual filesystems are mounted which provide access
- to kernel information.
- </footnote>
- </p>
+ 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>
+ </p>
</item>
<item>
<p>
<p>
Packages must not include files or directories
- under <file>/run</file>, or under the <file>/var/run</file>
- or <file>/var/lock</file> paths that are replaced with
- symlinks or bind mounts to <file>/run</file> for backwards
- compatibility.
- </p>
-
- <p>
- Packages should use <file>/run</file> in preference
- to <file>/var/run</file> and <file>/run/lock</file> in
- preference to <file>/var/lock</file>.
+ under <file>/run</file>, or under the
+ older <file>/var/run</file> and <file>/var/lock</file> paths.
+ The latter paths will normally be symlinks or other
+ redirections to <file>/run</file> for backwards compatibility.
</p>
</sect1>
</sect>
<p>
You may wish to restrict your script to SUSv3 features plus the
above set when possible so that it may use <file>/bin/sh</file>
- as its interpreter. If your script works with <prgn>dash</prgn>
- (originally called <prgn>ash</prgn>), it probably complies with
- the above requirements, but if you are in doubt, use
- <file>/bin/bash</file>.
+ as its interpreter. Checking your script
+ with <prgn>checkbashisms</prgn> from
+ the <package>devscripts</package> package or running your script
+ with an alternate shell such as <prgn>posh</prgn> may help
+ uncover violations of the above requirements. If in doubt
+ whether a script complies with these requirements,
+ use <file>/bin/bash</file>.
</p>
<p>
You should not use the copyright file as a general <file>README</file>
file. If your package has such a file it should be
installed in <file>/usr/share/doc/<var>package</var>/README</file> or
- <file>README.Debian</file> or some other appropriate place.</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>
+
+ <p>
+ A specification for a standard, machine-readable format
+ for <file>debian/copyright</file> files is maintained as part
+ of the <package>debian-policy</package> package. This
+ document may be found in the <file>copyright-format</file>
+ files in the <package>debian-policy</package> package. It is
+ also available from the Debian web mirrors at
+ <tt><url name="/doc/packaging-manuals/copyright-format/1.0/"
+ id="http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/"></tt>.
+ </p>
+
+ <p>
+ Use of this format is optional.
+ </p>
+ </sect1>
</sect>
<sect>
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 take no
- special action to gain root privilege, so that for
- most packages it will have to be invoked as root to
- start with.</p>
+ 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>
dpkg-divert --package smailwrapper --remove --rename \
--divert /usr/sbin/smail.real /usr/sbin/smail
fi
- </example> where <tt>1.02-2</tt> is the version at which the
+ </example> where <tt>1.0-2</tt> is the version at which the
diversion was first added to the package. The postrm should not
remove the diversion on upgrades both because there's no reason to
remove the diversion only to immediately re-add it and since the
projects / debian / debian-policy.git / blobdiff