<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>
</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 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>).
- 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>
- 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.
+ The <tt>build</tt> target
+ should either depend on those targets or take the same
+ actions as invoking those targets would perform.<footnote>
+ 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>
<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="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>
</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>
<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-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-Checksums"><tt>Checksums-Sha1</tt>
<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>
</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>
</sect>
<sect>
<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
</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>
as its interpreter. Checking your script
with <prgn>checkbashisms</prgn> from
the <package>devscripts</package> package or running your script
- with <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>.
+ 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>
<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>
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>
projects / debian / debian-policy.git / blobdiff