File: //usr/share/doc/debian-policy/policy.html/ch-controlfields.html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>5. Control files and their fields — Debian Policy Manual v4.6.0.1</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/nature.css" />
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="6. Package maintainer scripts and installation procedure" href="ch-maintainerscripts.html" />
<link rel="prev" title="4. Source packages" href="ch-source.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="ch-maintainerscripts.html" title="6. Package maintainer scripts and installation procedure"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="ch-source.html" title="4. Source packages"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Debian Policy Manual v4.6.0.1</a> »</li>
<li class="nav-item nav-item-this"><a href=""><span class="section-number">5. </span>Control files and their fields</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="control-files-and-their-fields">
<h1><span class="section-number">5. </span>Control files and their fields<a class="headerlink" href="#control-files-and-their-fields" title="Permalink to this headline">¶</a></h1>
<p>The package management system manipulates data represented in a common
format, known as <em>control data</em>, stored in <em>control files</em>. Control
files are used for source packages, binary packages and the <code class="docutils literal notranslate"><span class="pre">.changes</span></code>
files which control the installation of uploaded files. <a class="footnote-reference brackets" href="#id16" id="id1">1</a></p>
<section id="syntax-of-control-files">
<span id="s-controlsyntax"></span><h2><span class="section-number">5.1. </span>Syntax of control files<a class="headerlink" href="#syntax-of-control-files" title="Permalink to this headline">¶</a></h2>
<p>A control file consists of one or more paragraphs of fields. <a class="footnote-reference brackets" href="#id17" id="id2">2</a> The
paragraphs are separated by empty lines. Parsers may accept lines
consisting solely of spaces and tabs as paragraph separators, but
control files should use empty lines. Some control files allow only one
paragraph; others allow several, in which case each paragraph usually
refers to a different package. (For example, in source packages, the
first paragraph refers to the source package, and later paragraphs refer
to binary packages generated from the source.) The ordering of the
paragraphs in control files is significant.</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 US-ASCII characters
excluding control characters, space, and colon (i.e., characters in the
ranges U+0021 (<code class="docutils literal notranslate"><span class="pre">!</span></code>) through U+0039 (<code class="docutils literal notranslate"><span class="pre">9</span></code>), and U+003B (<code class="docutils literal notranslate"><span class="pre">;</span></code>) through
U+007E (<code class="docutils literal notranslate"><span class="pre">~</span></code>), inclusive). Field names must not begin with the comment
character (U+0023 <code class="docutils literal notranslate"><span class="pre">#</span></code>), nor with the hyphen character (U+002D <code class="docutils literal notranslate"><span class="pre">-</span></code>).</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:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Package</span><span class="p">:</span> <span class="n">libc6</span>
</pre></div>
</div>
<p>the field name is <code class="docutils literal notranslate"><span class="pre">Package</span></code> and the field value <code class="docutils literal notranslate"><span class="pre">libc6</span></code>.</p>
<p>Empty field values are only permitted in source package control files
(<code class="docutils literal notranslate"><span class="pre">debian/control</span></code>). Such fields are ignored.</p>
<p>A paragraph must not contain more than one instance of a particular
field name.</p>
<p>There are three types of fields:</p>
<dl class="simple">
<dt>simple</dt><dd><p>The field, including its value, must be a single line. Folding of
the field is not permitted. This is the default field type if the
definition of the field does not specify a different type.</p>
</dd>
<dt>folded</dt><dd><p>The value of a folded field is a logical line that may span several
lines. The lines after the first are called continuation lines and
must start with a space or a tab. Whitespace, including any
newlines, is not significant in the field values of folded fields. <a class="footnote-reference brackets" href="#id18" id="id3">3</a></p>
</dd>
<dt>multiline</dt><dd><p>The value of a multiline field may comprise multiple continuation
lines. The first line of the value, the part on the same line as the
field name, often has special significance or may have to be empty.
Other lines are added following the same syntax as the continuation
lines of the folded fields. Whitespace, including newlines, is
significant in the values of multiline fields.</p>
</dd>
</dl>
<p>Whitespace must not appear inside names (of packages, architectures,
files or anything else) or version numbers, or between the characters of
multi-character version relationships.</p>
<p>The presence and purpose of a field, and the syntax of its value, may
differ between types of control files.</p>
<p>Field names are not case-sensitive, but it is usual to capitalize the
field names using mixed case as shown below. Field values are
case-sensitive unless the description of the field says otherwise.</p>
<p>Paragraph separators (empty lines), and lines consisting only of U+0020
SPACE and U+0009 TAB, are not allowed within field values or between
fields. Empty lines in field values are usually escaped by representing
them by a U+0020 SPACE followed by a U+002E (<code class="docutils literal notranslate"><span class="pre">.</span></code>).</p>
<p>Lines starting with U+0023 (<code class="docutils literal notranslate"><span class="pre">#</span></code>), without any preceding whitespace,
are comment lines that are only permitted in source package control
files (<code class="docutils literal notranslate"><span class="pre">debian/control</span></code>). These comment lines are ignored, even
between two continuation lines. They do not end logical lines.</p>
<p>All control files must be encoded in UTF-8.</p>
</section>
<section id="source-package-control-files-debian-control">
<span id="s-sourcecontrolfiles"></span><h2><span class="section-number">5.2. </span>Source package control files – <code class="docutils literal notranslate"><span class="pre">debian/control</span></code><a class="headerlink" href="#source-package-control-files-debian-control" title="Permalink to this headline">¶</a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">debian/control</span></code> file contains the most vital (and
version-independent) information about the source package and about the
binary packages it creates.</p>
<p>The first paragraph of the control file contains information about the
source package in general. The subsequent paragraphs each describe a
binary package that the source tree builds. Each binary package built
from this source package has a corresponding paragraph, except for any
automatically-generated debug packages that do not require one.</p>
<p>The fields in the general paragraph (the first one, for the source
package) are:</p>
<ul class="simple">
<li><p><a class="reference internal" href="#s-f-source"><span class="std std-ref">Source</span></a> (mandatory)</p></li>
<li><p><a class="reference internal" href="#s-f-maintainer"><span class="std std-ref">Maintainer</span></a> (mandatory)</p></li>
<li><p><a class="reference internal" href="#s-f-uploaders"><span class="std std-ref">Uploaders</span></a></p></li>
<li><p><a class="reference internal" href="#s-f-section"><span class="std std-ref">Section</span></a> (recommended)</p></li>
<li><p><a class="reference internal" href="#s-f-priority"><span class="std std-ref">Priority</span></a> (recommended)</p></li>
<li><p><a class="reference internal" href="ch-relationships.html#s-sourcebinarydeps"><span class="std std-ref">Build-Depends et al</span></a></p></li>
<li><p><a class="reference internal" href="#s-f-standards-version"><span class="std std-ref">Standards-Version</span></a> (mandatory)</p></li>
<li><p><a class="reference internal" href="#s-f-homepage"><span class="std std-ref">Homepage</span></a></p></li>
<li><p><a class="reference internal" href="#s-f-vcs-fields"><span class="std std-ref">Version Control System (VCS) fields</span></a></p></li>
<li><p><a class="reference internal" href="#s-f-testsuite"><span class="std std-ref">Testsuite</span></a></p></li>
<li><p><a class="reference internal" href="#s-f-rules-requires-root"><span class="std std-ref">Rules-Requires-Root</span></a></p></li>
</ul>
<p>The fields in the binary package paragraphs are:</p>
<ul class="simple">
<li><p><a class="reference internal" href="#s-f-package"><span class="std std-ref">Package</span></a> (mandatory)</p></li>
<li><p><a class="reference internal" href="#s-f-architecture"><span class="std std-ref">Architecture</span></a> (mandatory)</p></li>
<li><p><a class="reference internal" href="#s-f-section"><span class="std std-ref">Section</span></a> (recommended)</p></li>
<li><p><a class="reference internal" href="#s-f-priority"><span class="std std-ref">Priority</span></a> (recommended)</p></li>
<li><p><a class="reference internal" href="#s-f-essential"><span class="std std-ref">Essential</span></a></p></li>
<li><p><a class="reference internal" href="ch-relationships.html#s-binarydeps"><span class="std std-ref">Depends et al</span></a></p></li>
<li><p><a class="reference internal" href="#s-f-description"><span class="std std-ref">Description</span></a> (mandatory)</p></li>
<li><p><a class="reference internal" href="#s-f-homepage"><span class="std std-ref">Homepage</span></a></p></li>
<li><p><a class="reference internal" href="ch-relationships.html#s-built-using"><span class="std std-ref">Built-Using</span></a></p></li>
<li><p><a class="reference internal" href="#s-f-package-type"><span class="std std-ref">Package-Type</span></a></p></li>
</ul>
<p>The syntax and semantics of the fields are described below.</p>
<p>These fields are used by <code class="docutils literal notranslate"><span class="pre">dpkg-gencontrol</span></code> to generate control files
for binary packages (see below), by <code class="docutils literal notranslate"><span class="pre">dpkg-genchanges</span></code> to generate the
<code class="docutils literal notranslate"><span class="pre">.changes</span></code> file to accompany the upload, and by <code class="docutils literal notranslate"><span class="pre">dpkg-source</span></code> when
it creates the <code class="docutils literal notranslate"><span class="pre">.dsc</span></code> source control file as part of a source archive.
Some fields are folded in <code class="docutils literal notranslate"><span class="pre">debian/control</span></code>, but not in any other
control file. These tools are responsible for removing the line breaks
from such fields when using fields from <code class="docutils literal notranslate"><span class="pre">debian/control</span></code> to generate
other control files. They are also responsible for discarding empty
fields.</p>
<p>The fields here may contain variable references - their values will be
substituted by <code class="docutils literal notranslate"><span class="pre">dpkg-gencontrol</span></code>, <code class="docutils literal notranslate"><span class="pre">dpkg-genchanges</span></code> or
<code class="docutils literal notranslate"><span class="pre">dpkg-source</span></code> when they generate output control files. See
<a class="reference internal" href="ch-source.html#s-substvars"><span class="std std-ref">Variable substitutions: debian/substvars</span></a> for details.</p>
</section>
<section id="binary-package-control-files-debian-control">
<span id="s-binarycontrolfiles"></span><h2><span class="section-number">5.3. </span>Binary package control files – <code class="docutils literal notranslate"><span class="pre">DEBIAN/control</span></code><a class="headerlink" href="#binary-package-control-files-debian-control" title="Permalink to this headline">¶</a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">DEBIAN/control</span></code> file contains the most vital (and
version-dependent) information about a binary package. It consists of a
single paragraph.</p>
<p>The fields in this file are:</p>
<ul class="simple">
<li><p><a class="reference internal" href="#s-f-package"><span class="std std-ref">Package</span></a> (mandatory)</p></li>
<li><p><a class="reference internal" href="#s-f-source"><span class="std std-ref">Source</span></a></p></li>
<li><p><a class="reference internal" href="#s-f-version"><span class="std std-ref">Version</span></a> (mandatory)</p></li>
<li><p><a class="reference internal" href="#s-f-section"><span class="std std-ref">Section</span></a> (recommended)</p></li>
<li><p><a class="reference internal" href="#s-f-priority"><span class="std std-ref">Priority</span></a> (recommended)</p></li>
<li><p><a class="reference internal" href="#s-f-architecture"><span class="std std-ref">Architecture</span></a> (mandatory)</p></li>
<li><p><a class="reference internal" href="#s-f-essential"><span class="std std-ref">Essential</span></a></p></li>
<li><p><a class="reference internal" href="ch-relationships.html#s-binarydeps"><span class="std std-ref">Depends et al</span></a></p></li>
<li><p><a class="reference internal" href="#s-f-installed-size"><span class="std std-ref">Installed-Size</span></a></p></li>
<li><p><a class="reference internal" href="#s-f-maintainer"><span class="std std-ref">Maintainer</span></a> (mandatory)</p></li>
<li><p><a class="reference internal" href="#s-f-description"><span class="std std-ref">Description</span></a> (mandatory)</p></li>
<li><p><a class="reference internal" href="#s-f-homepage"><span class="std std-ref">Homepage</span></a></p></li>
<li><p><a class="reference internal" href="ch-relationships.html#s-built-using"><span class="std std-ref">Built-Using</span></a></p></li>
</ul>
</section>
<section id="debian-source-control-files-dsc">
<span id="s-debiansourcecontrolfiles"></span><h2><span class="section-number">5.4. </span>Debian source control files – <code class="docutils literal notranslate"><span class="pre">.dsc</span></code><a class="headerlink" href="#debian-source-control-files-dsc" title="Permalink to this headline">¶</a></h2>
<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 <a class="reference internal" href="#s-controlsyntax"><span class="std std-ref">Syntax of control files</span></a>.</p>
<ul class="simple">
<li><p><a class="reference internal" href="#s-f-format"><span class="std std-ref">Format</span></a> (mandatory)</p></li>
<li><p><a class="reference internal" href="#s-f-source"><span class="std std-ref">Source</span></a> (mandatory)</p></li>
<li><p><a class="reference internal" href="#s-f-binary"><span class="std std-ref">Binary</span></a></p></li>
<li><p><a class="reference internal" href="#s-f-architecture"><span class="std std-ref">Architecture</span></a></p></li>
<li><p><a class="reference internal" href="#s-f-version"><span class="std std-ref">Version</span></a> (mandatory)</p></li>
<li><p><a class="reference internal" href="#s-f-maintainer"><span class="std std-ref">Maintainer</span></a> (mandatory)</p></li>
<li><p><a class="reference internal" href="#s-f-uploaders"><span class="std std-ref">Uploaders</span></a></p></li>
<li><p><a class="reference internal" href="#s-f-homepage"><span class="std std-ref">Homepage</span></a></p></li>
<li><p><a class="reference internal" href="#s-f-vcs-fields"><span class="std std-ref">Version Control System (VCS) fields</span></a></p></li>
<li><p><a class="reference internal" href="#s-f-testsuite"><span class="std std-ref">Testsuite</span></a></p></li>
<li><p><a class="reference internal" href="#s-f-dgit"><span class="std std-ref">Dgit</span></a></p></li>
<li><p><a class="reference internal" href="#s-f-standards-version"><span class="std std-ref">Standards-Version</span></a> (mandatory)</p></li>
<li><p><a class="reference internal" href="ch-relationships.html#s-sourcebinarydeps"><span class="std std-ref">Build-Depends et al</span></a></p></li>
<li><p><a class="reference internal" href="#s-f-package-list"><span class="std std-ref">Package-List</span></a> (recommended)</p></li>
<li><p><a class="reference internal" href="#s-f-checksums"><span class="std std-ref">Checksums-Sha1 and Checksums-Sha256</span></a>
(mandatory)</p></li>
<li><p><a class="reference internal" href="#s-f-files"><span class="std std-ref">Files</span></a> (mandatory)</p></li>
</ul>
<p>The Debian source control file is generated by <code class="docutils literal notranslate"><span class="pre">dpkg-source</span></code> when it
builds the source archive, from other files in the source package,
described above. When unpacking, it is checked against the files and
directories in the other parts of the source package.</p>
</section>
<section id="debian-changes-files-changes">
<span id="s-debianchangesfiles"></span><h2><span class="section-number">5.5. </span>Debian changes files – <code class="docutils literal notranslate"><span class="pre">.changes</span></code><a class="headerlink" href="#debian-changes-files-changes" title="Permalink to this headline">¶</a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">.changes</span></code> files are used by the Debian archive maintenance
software to process updates to packages. They consist of a single
paragraph, possibly surrounded by a PGP signature. That paragraph
contains information from the <code class="docutils literal notranslate"><span class="pre">debian/control</span></code> file and other data
about the source package gathered via <code class="docutils literal notranslate"><span class="pre">debian/changelog</span></code> and
<code class="docutils literal notranslate"><span class="pre">debian/rules</span></code>.</p>
<p><code class="docutils literal notranslate"><span class="pre">.changes</span></code> files have a format version that is incremented whenever
the documented fields or their meaning change. This document describes
format 1.8.</p>
<p>The fields in this file are:</p>
<ul class="simple">
<li><p><a class="reference internal" href="#s-f-format"><span class="std std-ref">Format</span></a> (mandatory)</p></li>
<li><p><a class="reference internal" href="#s-f-date"><span class="std std-ref">Date</span></a> (mandatory)</p></li>
<li><p><a class="reference internal" href="#s-f-source"><span class="std std-ref">Source</span></a> (mandatory)</p></li>
<li><p><a class="reference internal" href="#s-f-binary"><span class="std std-ref">Binary</span></a> (mandatory)</p></li>
<li><p><a class="reference internal" href="#s-f-architecture"><span class="std std-ref">Architecture</span></a> (mandatory)</p></li>
<li><p><a class="reference internal" href="#s-f-version"><span class="std std-ref">Version</span></a> (mandatory)</p></li>
<li><p><a class="reference internal" href="#s-f-distribution"><span class="std std-ref">Distribution</span></a> (mandatory)</p></li>
<li><p><a class="reference internal" href="#s-f-urgency"><span class="std std-ref">Urgency</span></a> (recommended)</p></li>
<li><p><a class="reference internal" href="#s-f-maintainer"><span class="std std-ref">Maintainer</span></a> (mandatory)</p></li>
<li><p><a class="reference internal" href="#s-f-changed-by"><span class="std std-ref">Changed-By</span></a></p></li>
<li><p><a class="reference internal" href="#s-f-description"><span class="std std-ref">Description</span></a> (mandatory)</p></li>
<li><p><a class="reference internal" href="#s-f-closes"><span class="std std-ref">Closes</span></a></p></li>
<li><p><a class="reference internal" href="#s-f-changes"><span class="std std-ref">Changes</span></a> (mandatory)</p></li>
<li><p><a class="reference internal" href="#s-f-checksums"><span class="std std-ref">Checksums-Sha1 and Checksums-Sha256</span></a>
(mandatory)</p></li>
<li><p><a class="reference internal" href="#s-f-files"><span class="std std-ref">Files</span></a> (mandatory)</p></li>
</ul>
</section>
<section id="list-of-fields">
<span id="s-controlfieldslist"></span><h2><span class="section-number">5.6. </span>List of fields<a class="headerlink" href="#list-of-fields" title="Permalink to this headline">¶</a></h2>
<section id="source">
<span id="s-f-source"></span><h3><span class="section-number">5.6.1. </span><code class="docutils literal notranslate"><span class="pre">Source</span></code><a class="headerlink" href="#source" title="Permalink to this headline">¶</a></h3>
<p>This field identifies the source package name.</p>
<p>In <code class="docutils literal notranslate"><span class="pre">debian/control</span></code> or a <code class="docutils literal notranslate"><span class="pre">.dsc</span></code> file, this field must contain only
the name of the source package.</p>
<p>In a binary package control file or a <code class="docutils literal notranslate"><span class="pre">.changes</span></code> file, the source
package name may be followed by a version number in parentheses. <a class="footnote-reference brackets" href="#id19" id="id4">4</a>
This version number may be omitted (and is, by <code class="docutils literal notranslate"><span class="pre">dpkg-gencontrol</span></code>) if
it has the same value as the <code class="docutils literal notranslate"><span class="pre">Version</span></code> field of the binary package in
question. The field itself may be omitted from a binary package control
file when the source package has the same name and version as the binary
package.</p>
<p>Package names (both source and binary, see
<a class="reference internal" href="#s-f-package"><span class="std std-ref">Package</span></a>) must consist only of lower case
letters (<code class="docutils literal notranslate"><span class="pre">a-z</span></code>), digits (<code class="docutils literal notranslate"><span class="pre">0-9</span></code>), plus (<code class="docutils literal notranslate"><span class="pre">+</span></code>) and minus (<code class="docutils literal notranslate"><span class="pre">-</span></code>)
signs, and periods (<code class="docutils literal notranslate"><span class="pre">.</span></code>). They must be at least two characters long
and must start with an alphanumeric character.</p>
</section>
<section id="maintainer">
<span id="s-f-maintainer"></span><h3><span class="section-number">5.6.2. </span><code class="docutils literal notranslate"><span class="pre">Maintainer</span></code><a class="headerlink" href="#maintainer" title="Permalink to this headline">¶</a></h3>
<p>The package maintainer’s name and email address. The name must come
first, then the email address inside angle brackets <code class="docutils literal notranslate"><span class="pre"><></span></code> (in RFC822
format).</p>
<p>If the maintainer’s name contains a full stop then the whole field will
not work directly as an email address due to a misfeature in the syntax
specified in RFC822; a program using this field as an address must check
for this and correct the problem if necessary (for example by putting
the name in round brackets and moving it to the end, and bringing the
email address forward).</p>
<p>See <a class="reference internal" href="ch-binary.html#s-maintainer"><span class="std std-ref">The maintainer of a package</span></a> for additional requirements and
information about package maintainers.</p>
</section>
<section id="uploaders">
<span id="s-f-uploaders"></span><h3><span class="section-number">5.6.3. </span><code class="docutils literal notranslate"><span class="pre">Uploaders</span></code><a class="headerlink" href="#uploaders" title="Permalink to this headline">¶</a></h3>
<p>List of the names and email addresses of co-maintainers of the package,
if any. If the package has other maintainers besides the one named in
the <a class="reference internal" href="#s-f-maintainer"><span class="std std-ref">Maintainer field</span></a>, their names and email
addresses should be listed here. The format of each entry is the same as
that of the Maintainer field, and multiple entries must be comma
separated.</p>
<p>This is normally an optional field, but if the <code class="docutils literal notranslate"><span class="pre">Maintainer</span></code> control
field names a group of people and a shared email address, the
<code class="docutils literal notranslate"><span class="pre">Uploaders</span></code> field must be present and must contain at least one human
with their personal email address.</p>
<p>The Uploaders field in <code class="docutils literal notranslate"><span class="pre">debian/control</span></code> can be folded.</p>
</section>
<section id="changed-by">
<span id="s-f-changed-by"></span><h3><span class="section-number">5.6.4. </span><code class="docutils literal notranslate"><span class="pre">Changed-By</span></code><a class="headerlink" href="#changed-by" title="Permalink to this headline">¶</a></h3>
<p>The name and email address of the person who prepared this version of
the package, usually a maintainer. The syntax is the same as for the
<a class="reference internal" href="#s-f-maintainer"><span class="std std-ref">Maintainer field</span></a>.</p>
</section>
<section id="section">
<span id="s-f-section"></span><h3><span class="section-number">5.6.5. </span><code class="docutils literal notranslate"><span class="pre">Section</span></code><a class="headerlink" href="#section" title="Permalink to this headline">¶</a></h3>
<p>This field specifies an application area into which the package has been
classified. See <a class="reference internal" href="ch-archive.html#s-subsections"><span class="std std-ref">Sections</span></a>.</p>
<p>When it appears in the <code class="docutils literal notranslate"><span class="pre">debian/control</span></code> file, it gives the value for
the subfield of the same name in the <code class="docutils literal notranslate"><span class="pre">Files</span></code> field of the <code class="docutils literal notranslate"><span class="pre">.changes</span></code>
file. It also gives the default for the same field in the binary
packages.</p>
</section>
<section id="priority">
<span id="s-f-priority"></span><h3><span class="section-number">5.6.6. </span><code class="docutils literal notranslate"><span class="pre">Priority</span></code><a class="headerlink" href="#priority" title="Permalink to this headline">¶</a></h3>
<p>This field represents how important it is that the user have the package
installed. See <a class="reference internal" href="ch-archive.html#s-priorities"><span class="std std-ref">Priorities</span></a>.</p>
<p>When it appears in the <code class="docutils literal notranslate"><span class="pre">debian/control</span></code> file, it gives the value for
the subfield of the same name in the <code class="docutils literal notranslate"><span class="pre">Files</span></code> field of the <code class="docutils literal notranslate"><span class="pre">.changes</span></code>
file. It also gives the default for the same field in the binary
packages.</p>
</section>
<section id="package">
<span id="s-f-package"></span><h3><span class="section-number">5.6.7. </span><code class="docutils literal notranslate"><span class="pre">Package</span></code><a class="headerlink" href="#package" title="Permalink to this headline">¶</a></h3>
<p>The name of the binary package.</p>
<p>Binary package names must follow the same syntax and restrictions as
source package names. See <a class="reference internal" href="#s-f-source"><span class="std std-ref">Source</span></a> for the
details.</p>
</section>
<section id="architecture">
<span id="s-f-architecture"></span><h3><span class="section-number">5.6.8. </span><code class="docutils literal notranslate"><span class="pre">Architecture</span></code><a class="headerlink" href="#architecture" title="Permalink to this headline">¶</a></h3>
<p>Depending on context and the control file used, the <code class="docutils literal notranslate"><span class="pre">Architecture</span></code>
field can include the following sets of values:</p>
<ul class="simple">
<li><p>A unique single word identifying a Debian machine architecture as
described in <a class="reference internal" href="ch-customized-programs.html#s-arch-spec"><span class="std std-ref">Architecture specification strings</span></a>.</p></li>
<li><p>An architecture wildcard identifying a set of Debian machine
architectures, see <a class="reference internal" href="ch-customized-programs.html#s-arch-wildcard-spec"><span class="std std-ref">Architecture wildcards</span></a>.
<code class="docutils literal notranslate"><span class="pre">any</span></code> matches all Debian machine architectures and is the most
frequently used.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">all</span></code>, which indicates an architecture-independent package.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">source</span></code>, which indicates a source package.</p></li>
</ul>
<p>In the main <code class="docutils literal notranslate"><span class="pre">debian/control</span></code> file in the source package, this field
may contain the special value <code class="docutils literal notranslate"><span class="pre">all</span></code>, the special architecture wildcard
<code class="docutils literal notranslate"><span class="pre">any</span></code>, or a list of specific and wildcard architectures separated by
spaces. If <code class="docutils literal notranslate"><span class="pre">all</span></code> or <code class="docutils literal notranslate"><span class="pre">any</span></code> appears, that value must be the entire
contents of the field. Most packages will use either <code class="docutils literal notranslate"><span class="pre">all</span></code> or <code class="docutils literal notranslate"><span class="pre">any</span></code>.</p>
<p>Specifying a specific list of architectures indicates that the source
will build an architecture-dependent package only on architectures
included in the list. Specifying a list of architecture wildcards
indicates that the source will build an architecture-dependent package
on only those architectures that match any of the specified architecture
wildcards. Specifying a list of architectures or architecture wildcards
other than <code class="docutils literal notranslate"><span class="pre">any</span></code> is for the minority of cases where a program is not
portable or is not useful on some architectures. Where possible, the
program should be made portable instead.</p>
<p>In the Debian source control file <code class="docutils literal notranslate"><span class="pre">.dsc</span></code>, this field contains a list
of architectures and architecture wildcards separated by spaces. When
the list contains the architecture wildcard <code class="docutils literal notranslate"><span class="pre">any</span></code>, the only other
value allowed in the list is <code class="docutils literal notranslate"><span class="pre">all</span></code>.</p>
<p>The list may include (or consist solely of) the special value <code class="docutils literal notranslate"><span class="pre">all</span></code>.
In other words, in <code class="docutils literal notranslate"><span class="pre">.dsc</span></code> files unlike the <code class="docutils literal notranslate"><span class="pre">debian/control</span></code>, <code class="docutils literal notranslate"><span class="pre">all</span></code>
may occur in combination with specific architectures. The
<code class="docutils literal notranslate"><span class="pre">Architecture</span></code> field in the Debian source control file <code class="docutils literal notranslate"><span class="pre">.dsc</span></code> is
generally constructed from the <code class="docutils literal notranslate"><span class="pre">Architecture</span></code> fields in the
<code class="docutils literal notranslate"><span class="pre">debian/control</span></code> in the source package.</p>
<p>Specifying only <code class="docutils literal notranslate"><span class="pre">any</span></code> indicates that the source package isn’t
dependent on any particular architecture and should compile fine on any
one. The produced binary package(s) will be specific to whatever the
current build architecture is.</p>
<p>Specifying only <code class="docutils literal notranslate"><span class="pre">all</span></code> indicates that the source package will only
build architecture-independent packages.</p>
<p>Specifying <code class="docutils literal notranslate"><span class="pre">any</span> <span class="pre">all</span></code> indicates that the source package isn’t dependent
on any particular architecture. The set of produced binary packages will
include at least one architecture-dependent package and one
architecture-independent package.</p>
<p>Specifying a list of architectures or architecture wildcards indicates
that the source will build an architecture-dependent package, and will
only work correctly on the listed or matching architectures. If the
source package also builds at least one architecture-independent
package, <code class="docutils literal notranslate"><span class="pre">all</span></code> will also be included in the list.</p>
<p>In a <code class="docutils literal notranslate"><span class="pre">.changes</span></code> file, the <code class="docutils literal notranslate"><span class="pre">Architecture</span></code> field lists the
architecture(s) of the package(s) currently being uploaded. This will be
a list; if the source for the package is also being uploaded, the
special entry <code class="docutils literal notranslate"><span class="pre">source</span></code> is also present. <code class="docutils literal notranslate"><span class="pre">all</span></code> will be present if any
architecture-independent packages are being uploaded. Architecture
wildcards such as <code class="docutils literal notranslate"><span class="pre">any</span></code> must never occur in the <code class="docutils literal notranslate"><span class="pre">Architecture</span></code> field
in the <code class="docutils literal notranslate"><span class="pre">.changes</span></code> file.</p>
<p>See <a class="reference internal" href="ch-source.html#s-debianrules"><span class="std std-ref">Main building script: debian/rules</span></a> for information on how to get
the architecture for the build process.</p>
</section>
<section id="essential">
<span id="s-f-essential"></span><h3><span class="section-number">5.6.9. </span><code class="docutils literal notranslate"><span class="pre">Essential</span></code><a class="headerlink" href="#essential" title="Permalink to this headline">¶</a></h3>
<p>This is a boolean field which may occur only in the control file of a
binary package or in a per-package fields paragraph of a source package
control file.</p>
<p>If set to <code class="docutils literal notranslate"><span class="pre">yes</span></code> then the package management system will refuse to
remove the package (upgrading and replacing it is still possible). The
other possible value is <code class="docutils literal notranslate"><span class="pre">no</span></code>, which is the same as not having the
field at all.</p>
</section>
<section id="package-interrelationship-fields-depends-pre-depends-recommends-suggests-breaks-conflicts-provides-replaces-enhances">
<span id="s5-6-10"></span><h3><span class="section-number">5.6.10. </span>Package interrelationship fields: <code class="docutils literal notranslate"><span class="pre">Depends</span></code>, <code class="docutils literal notranslate"><span class="pre">Pre-Depends</span></code>, <code class="docutils literal notranslate"><span class="pre">Recommends</span></code>, <code class="docutils literal notranslate"><span class="pre">Suggests</span></code>, <code class="docutils literal notranslate"><span class="pre">Breaks</span></code>, <code class="docutils literal notranslate"><span class="pre">Conflicts</span></code>, <code class="docutils literal notranslate"><span class="pre">Provides</span></code>, <code class="docutils literal notranslate"><span class="pre">Replaces</span></code>, <code class="docutils literal notranslate"><span class="pre">Enhances</span></code><a class="headerlink" href="#package-interrelationship-fields-depends-pre-depends-recommends-suggests-breaks-conflicts-provides-replaces-enhances" title="Permalink to this headline">¶</a></h3>
<p>These fields describe the package’s relationships with other packages.
Their syntax and semantics are described in
<a class="reference internal" href="ch-relationships.html"><span class="doc">Declaring relationships between packages</span></a>.</p>
</section>
<section id="standards-version">
<span id="s-f-standards-version"></span><h3><span class="section-number">5.6.11. </span><code class="docutils literal notranslate"><span class="pre">Standards-Version</span></code><a class="headerlink" href="#standards-version" title="Permalink to this headline">¶</a></h3>
<p>The most recent version of the standards (the policy manual and
associated texts) with which the package complies. See
<a class="reference internal" href="ch-source.html#s-standardsversion"><span class="std std-ref">Standards conformance</span></a>.</p>
<p>The version number has four components: major and minor version number
and major and minor patch level. When the standards change in a way that
requires every package to change the major number will be changed.
Significant changes that will require work in many packages will be
signaled by a change to the minor number. The major patch level will be
changed for any change to the meaning of the standards, however small;
the minor patch level will be changed when only cosmetic, typographical
or other edits are made which neither change the meaning of the document
nor affect the contents of packages.</p>
<p>Thus only the first three components of the policy version are
significant in the <em>Standards-Version</em> control field, and so either
these three components or all four components may be specified. <a class="footnote-reference brackets" href="#id20" id="id5">5</a></p>
</section>
<section id="version">
<span id="s-f-version"></span><h3><span class="section-number">5.6.12. </span><code class="docutils literal notranslate"><span class="pre">Version</span></code><a class="headerlink" href="#version" title="Permalink to this headline">¶</a></h3>
<p>The version number of a package. The format is:
<code class="docutils literal notranslate"><span class="pre">[epoch:]upstream_version[-debian_revision]</span></code>.</p>
<p>The three components here are:</p>
<dl>
<dt><code class="docutils literal notranslate"><span class="pre">epoch</span></code></dt><dd><p>This is a single (generally small) unsigned integer. It may be
omitted, in which case zero is assumed.</p>
<p>Epochs can help when the upstream version numbering scheme
changes, but they must be used with care. You should not change
the epoch, even in experimental, without getting consensus on
debian-devel first.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">upstream_version</span></code></dt><dd><p>This is the main part of the version number. It is usually the
version number of the original (“upstream”) package from which the
<code class="docutils literal notranslate"><span class="pre">.deb</span></code> file has been made, if this is applicable. Usually this
will be in the same format as that specified by the upstream
author(s); however, it may need to be reformatted to fit into the
package management system’s format and comparison scheme.</p>
<p>The comparison behavior of the package management system with
respect to the <code class="docutils literal notranslate"><span class="pre">upstream_version</span></code> is described below. The
<code class="docutils literal notranslate"><span class="pre">upstream_version</span></code> portion of the version number is mandatory.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">upstream_version</span></code> must contain only alphanumerics <a class="footnote-reference brackets" href="#id21" id="id6">6</a> and
the characters <code class="docutils literal notranslate"><span class="pre">.</span></code> <code class="docutils literal notranslate"><span class="pre">+</span></code> <code class="docutils literal notranslate"><span class="pre">-</span></code> <code class="docutils literal notranslate"><span class="pre">~</span></code> (full stop, plus, hyphen,
tilde) and should start with a digit. If there is no
<code class="docutils literal notranslate"><span class="pre">debian_revision</span></code> then hyphens are not allowed.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">debian_revision</span></code></dt><dd><p>This part of the version number specifies the version of the Debian
package based on the upstream version. It must contain only
alphanumerics and the characters <code class="docutils literal notranslate"><span class="pre">+</span></code> <code class="docutils literal notranslate"><span class="pre">.</span></code> <code class="docutils literal notranslate"><span class="pre">~</span></code> (plus, full stop,
tilde) and is compared in the same way as the <code class="docutils literal notranslate"><span class="pre">upstream_version</span></code> is.</p>
<p>It is optional; if it isn’t present then the <code class="docutils literal notranslate"><span class="pre">upstream_version</span></code>
must not contain a hyphen. This format represents the case where a
piece of software was written specifically to be a Debian package,
where the Debian package source must always be identical to the
pristine source and therefore no revision indication is required.</p>
<p>It is conventional to restart the <code class="docutils literal notranslate"><span class="pre">debian_revision</span></code> at <code class="docutils literal notranslate"><span class="pre">1</span></code>
each time the <code class="docutils literal notranslate"><span class="pre">upstream_version</span></code> is increased.</p>
<p>The package management system will break the version number apart
at the last hyphen in the string (if there is one) to determine
the <code class="docutils literal notranslate"><span class="pre">upstream_version</span></code> and <code class="docutils literal notranslate"><span class="pre">debian_revision</span></code>. The absence of a
<code class="docutils literal notranslate"><span class="pre">debian_revision</span></code> is equivalent to a <code class="docutils literal notranslate"><span class="pre">debian_revision</span></code> of
<code class="docutils literal notranslate"><span class="pre">0</span></code>.</p>
</dd>
</dl>
<p>When comparing two version numbers, first the epoch of each are
compared, then the <code class="docutils literal notranslate"><span class="pre">upstream_version</span></code> if epoch is equal, and then
<code class="docutils literal notranslate"><span class="pre">debian_revision</span></code> if <code class="docutils literal notranslate"><span class="pre">upstream_version</span></code> is also equal. epoch is compared
numerically. The <code class="docutils literal notranslate"><span class="pre">upstream_version</span></code> and <code class="docutils literal notranslate"><span class="pre">debian_revision</span></code> parts are
compared by the package management system using the following algorithm:</p>
<p>The strings are compared from left to right.</p>
<p>First the initial part of each string consisting entirely of non-digit
characters is determined. These two parts (one of which may be empty)
are compared lexically. If a difference is found it is returned. The
lexical comparison is a comparison of ASCII values modified so that all
the letters sort earlier than all the non-letters and so that a tilde
sorts before anything, even the end of a part. For example, the
following parts are in sorted order from earliest to latest: <code class="docutils literal notranslate"><span class="pre">~~</span></code>,
<code class="docutils literal notranslate"><span class="pre">~~a</span></code>, <code class="docutils literal notranslate"><span class="pre">~</span></code>, the empty part, <code class="docutils literal notranslate"><span class="pre">a</span></code>. <a class="footnote-reference brackets" href="#id22" id="id7">7</a></p>
<p>Then the initial part of the remainder of each string which consists
entirely of digit characters is determined. The numerical values of
these two parts are compared, and any difference found is returned as
the result of the comparison. For these purposes an empty string (which
can only occur at the end of one or both version strings being compared)
counts as zero.</p>
<p>These two steps (comparing and removing initial non-digit strings and
initial digit strings) are repeated until a difference is found or both
strings are exhausted.</p>
<section id="epochs-should-be-used-sparingly">
<h4><span class="section-number">5.6.12.1. </span>Epochs should be used sparingly<a class="headerlink" href="#epochs-should-be-used-sparingly" title="Permalink to this headline">¶</a></h4>
<p>Note that the purpose of epochs is to cope with situations where the
upstream version numbering scheme changes and to allow us to leave
behind serious mistakes.
If you think that increasing the epoch is the right solution,
you should consult debian-devel and get consensus before doing so
(even in experimental).</p>
<p>Epochs should not be used when a package needs to be rolled back.
In that case, use the <code class="docutils literal notranslate"><span class="pre">+really</span></code> convention: for example, if you
uploaded <code class="docutils literal notranslate"><span class="pre">2.3-3</span></code> and now you need to go backwards to upstream 2.2,
call your reverting upload something like <code class="docutils literal notranslate"><span class="pre">2.3+really2.2-1</span></code>.
Eventually, when we upload upstream 2.4, the +really part can go away.</p>
<p>Epochs are also not intended to cope with version
numbers containing strings of letters which the package management
system cannot interpret (such as <code class="docutils literal notranslate"><span class="pre">ALPHA</span></code> or <code class="docutils literal notranslate"><span class="pre">pre-</span></code>), or with silly
orderings. <a class="footnote-reference brackets" href="#id23" id="id8">8</a></p>
</section>
</section>
<section id="description">
<span id="s-f-description"></span><h3><span class="section-number">5.6.13. </span><code class="docutils literal notranslate"><span class="pre">Description</span></code><a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h3>
<p>In a source or binary control file, the <code class="docutils literal notranslate"><span class="pre">Description</span></code> field contains a
description of the binary package, consisting of two parts, the synopsis
or the short description, and the long description. It is a multiline
field with the following format:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Description</span><span class="p">:</span> <span class="n">single</span> <span class="n">line</span> <span class="n">synopsis</span>
<span class="n">extended</span> <span class="n">description</span> <span class="n">over</span> <span class="n">several</span> <span class="n">lines</span>
</pre></div>
</div>
<p>The lines in the extended description can have these formats:</p>
<ul class="simple">
<li><p>Those starting with a single space are part of a paragraph.
Successive lines of this form will be word-wrapped when displayed.
The leading space will usually be stripped off. The line must contain
at least one non-whitespace character.</p></li>
<li><p>Those starting with two or more spaces. These will be displayed
verbatim. If the display cannot be panned horizontally, the
displaying program will line wrap them “hard” (i.e., without taking
account of word breaks). If it can they will be allowed to trail off
to the right. None, one or two initial spaces may be deleted, but the
number of spaces deleted from each line will be the same (so that you
can have indenting work correctly, for example). The line must
contain at least one non-whitespace character.</p></li>
<li><p>Those containing a single space followed by a single full stop
character. These are rendered as blank lines. This is the <em>only</em> way
to get a blank line. <a class="footnote-reference brackets" href="#id24" id="id9">9</a></p></li>
<li><p>Those containing a space, a full stop and some more characters. These
are for future expansion. Do not use them.</p></li>
</ul>
<p>Do not use tab characters. Their effect is not predictable.</p>
<p>See <a class="reference internal" href="ch-binary.html#s-descriptions"><span class="std std-ref">The description of a package</span></a> for further information on
this.</p>
<p>In a <code class="docutils literal notranslate"><span class="pre">.changes</span></code> file, the <code class="docutils literal notranslate"><span class="pre">Description</span></code> field contains a summary of
the descriptions for the packages being uploaded. For this case, the
first line of the field value (the part on the same line as
<code class="docutils literal notranslate"><span class="pre">Description:</span></code>) is always empty. It is a multiline field, with one
line per package. Each line is indented by one space and contains the
name of a binary package, a space, a hyphen (<code class="docutils literal notranslate"><span class="pre">-</span></code>), a space, and the
short description line from that package.</p>
</section>
<section id="distribution">
<span id="s-f-distribution"></span><h3><span class="section-number">5.6.14. </span><code class="docutils literal notranslate"><span class="pre">Distribution</span></code><a class="headerlink" href="#distribution" title="Permalink to this headline">¶</a></h3>
<p>In a <code class="docutils literal notranslate"><span class="pre">.changes</span></code> file or parsed changelog output this contains the
(space-separated) name(s) of the distribution(s) where this version of
the package should be installed. Valid distributions are determined by
the archive maintainers. <a class="footnote-reference brackets" href="#id25" id="id10">10</a> The Debian archive software only
supports listing a single distribution. Migration of packages to other
distributions is handled outside of the upload process.</p>
</section>
<section id="date">
<span id="s-f-date"></span><h3><span class="section-number">5.6.15. </span><code class="docutils literal notranslate"><span class="pre">Date</span></code><a class="headerlink" href="#date" title="Permalink to this headline">¶</a></h3>
<p>This field includes the date the package was built or last edited. It
must be in the same format as the date in a <code class="docutils literal notranslate"><span class="pre">debian/changelog</span></code> entry.</p>
<p>The value of this field is usually extracted from the
<code class="docutils literal notranslate"><span class="pre">debian/changelog</span></code> file - see <a class="reference internal" href="ch-source.html#s-dpkgchangelog"><span class="std std-ref">Debian changelog: debian/changelog</span></a>).</p>
</section>
<section id="format">
<span id="s-f-format"></span><h3><span class="section-number">5.6.16. </span><code class="docutils literal notranslate"><span class="pre">Format</span></code><a class="headerlink" href="#format" title="Permalink to this headline">¶</a></h3>
<p>In <a class="reference external" href="#s-debianchangesfiles"><code class="docutils literal notranslate"><span class="pre">.changes</span></code></a> files, this field declares the format version of
that file. The syntax of the field value is the same as that of a
<a class="reference internal" href="#s-f-version"><span class="std std-ref">package version number</span></a> except that no epoch or
Debian revision is allowed. The format described in this document is
1.8.</p>
<p>In <a class="reference external" href="#s-debiansourcecontrolfiles"><code class="docutils literal notranslate"><span class="pre">.dsc</span></code> Debian source control</a> files, this field declares the format of the source
package. The field value is used by programs acting on a source
package to interpret the list of files in the source package and
determine how to unpack it. The syntax of the field value is a numeric
major revision, a period, a numeric minor revision, and then an
optional subtype after whitespace, which if specified is an
alphanumeric word in parentheses. The subtype is optional in the
syntax but may be mandatory for particular source format revisions.
<a class="footnote-reference brackets" href="#id26" id="id11">11</a></p>
</section>
<section id="urgency">
<span id="s-f-urgency"></span><h3><span class="section-number">5.6.17. </span><code class="docutils literal notranslate"><span class="pre">Urgency</span></code><a class="headerlink" href="#urgency" title="Permalink to this headline">¶</a></h3>
<p>This is a description of how important it is to upgrade to this version
from previous ones. It consists of a single keyword taking one of the
values <code class="docutils literal notranslate"><span class="pre">low</span></code>, <code class="docutils literal notranslate"><span class="pre">medium</span></code>, <code class="docutils literal notranslate"><span class="pre">high</span></code>, <code class="docutils literal notranslate"><span class="pre">emergency</span></code>, or <code class="docutils literal notranslate"><span class="pre">critical</span></code>
<a class="footnote-reference brackets" href="#id27" id="id12">12</a> (not case-sensitive) followed by an optional commentary
(separated by a space) which is usually in parentheses. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Urgency</span><span class="p">:</span> <span class="n">low</span> <span class="p">(</span><span class="n">HIGH</span> <span class="k">for</span> <span class="n">users</span> <span class="n">of</span> <span class="n">diversions</span><span class="p">)</span>
</pre></div>
</div>
<p>The value of this field is usually extracted from the
<code class="docutils literal notranslate"><span class="pre">debian/changelog</span></code> file - see <a class="reference internal" href="ch-source.html#s-dpkgchangelog"><span class="std std-ref">Debian changelog: debian/changelog</span></a>.</p>
</section>
<section id="changes">
<span id="s-f-changes"></span><h3><span class="section-number">5.6.18. </span><code class="docutils literal notranslate"><span class="pre">Changes</span></code><a class="headerlink" href="#changes" title="Permalink to this headline">¶</a></h3>
<p>This multiline field contains the human-readable changes data,
describing the differences between the last version and the current one.</p>
<p>The first line of the field value (the part on the same line as
<code class="docutils literal notranslate"><span class="pre">Changes:</span></code>) is always empty. The content of the field is expressed as
continuation lines, with each line indented by at least one space. Blank
lines must be represented by a line consisting only of a space and a
full stop (<code class="docutils literal notranslate"><span class="pre">.</span></code>).</p>
<p>The value of this field is usually extracted from the
<code class="docutils literal notranslate"><span class="pre">debian/changelog</span></code> file - see <a class="reference internal" href="ch-source.html#s-dpkgchangelog"><span class="std std-ref">Debian changelog: debian/changelog</span></a>.</p>
<p>Each version’s change information should be preceded by a “title” line
giving at least the version, distribution(s) and urgency, in a
human-readable way.</p>
<p>If data from several versions is being returned the entry for the most
recent version should be returned first, and entries should be separated
by the representation of a blank line (the “title” line may also be
followed by the representation of a blank line).</p>
</section>
<section id="binary">
<span id="s-f-binary"></span><h3><span class="section-number">5.6.19. </span><code class="docutils literal notranslate"><span class="pre">Binary</span></code><a class="headerlink" href="#binary" title="Permalink to this headline">¶</a></h3>
<p>This folded field is a list of binary packages. Its syntax and meaning
varies depending on the control file in which it appears.</p>
<p>When it appears in the <code class="docutils literal notranslate"><span class="pre">.dsc</span></code> file, it lists binary packages which a
source package can produce, separated by commas <a class="footnote-reference brackets" href="#id28" id="id13">13</a>. The source
package does not necessarily produce all of these binary packages for
every architecture. The source control file doesn’t contain details of
which architectures are appropriate for which of the binary packages.</p>
<p>When it appears in a <code class="docutils literal notranslate"><span class="pre">.changes</span></code> file, it lists the names of the binary
packages being uploaded, separated by whitespace (not commas).</p>
</section>
<section id="installed-size">
<span id="s-f-installed-size"></span><h3><span class="section-number">5.6.20. </span><code class="docutils literal notranslate"><span class="pre">Installed-Size</span></code><a class="headerlink" href="#installed-size" title="Permalink to this headline">¶</a></h3>
<p>This field appears in the control files of binary packages, and in the
<code class="docutils literal notranslate"><span class="pre">Packages</span></code> files. It gives an estimate of the total amount of disk
space required to install the named package. Actual installed size may
vary based on block size, file system properties, or actions taken by
package maintainer scripts.</p>
<p>The disk space is given as the integer value of the estimated installed
size in bytes, divided by 1024 and rounded up.</p>
</section>
<section id="files">
<span id="s-f-files"></span><h3><span class="section-number">5.6.21. </span><code class="docutils literal notranslate"><span class="pre">Files</span></code><a class="headerlink" href="#files" title="Permalink to this headline">¶</a></h3>
<p>This field contains a list of files with information about each one. The
exact information and syntax varies with the context.</p>
<p>In all cases, Files is a multiline field. The first line of the field
value (the part on the same line as <code class="docutils literal notranslate"><span class="pre">Files:</span></code>) is always empty. The
content of the field is expressed as continuation lines, one line per
file. Each line must be indented by one space and contain a number of
sub-fields, separated by spaces, as described below.</p>
<p>In the <code class="docutils literal notranslate"><span class="pre">.dsc</span></code> file, each line contains the MD5 checksum, size and
filename of the tar file and (if applicable) diff file which make up the
remainder of the source package. <a class="footnote-reference brackets" href="#id29" id="id14">14</a> For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Files</span><span class="p">:</span>
<span class="n">c6f698f19f2a2aa07dbb9bbda90a2754</span> <span class="mi">571925</span> <span class="n">example_1</span><span class="o">.</span><span class="mf">2.</span><span class="n">orig</span><span class="o">.</span><span class="n">tar</span><span class="o">.</span><span class="n">gz</span>
<span class="mi">938512</span><span class="n">f08422f3509ff36f125f5873ba</span> <span class="mi">6220</span> <span class="n">example_1</span><span class="o">.</span><span class="mi">2</span><span class="o">-</span><span class="mf">1.</span><span class="n">diff</span><span class="o">.</span><span class="n">gz</span>
</pre></div>
</div>
<p>The exact forms of the filenames are described in
<a class="reference internal" href="ap-pkg-sourcepkg.html#s-pkg-sourcearchives"><span class="std std-ref">Source packages as archives</span></a>.</p>
<p>In the <code class="docutils literal notranslate"><span class="pre">.changes</span></code> file this contains one line per file being uploaded.
Each line contains the MD5 checksum, size, section and priority and the
filename. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Files</span><span class="p">:</span>
<span class="mi">4</span><span class="n">c31ab7bfc40d3cf49d7811987390357</span> <span class="mi">1428</span> <span class="n">text</span> <span class="n">extra</span> <span class="n">example_1</span><span class="o">.</span><span class="mi">2</span><span class="o">-</span><span class="mf">1.</span><span class="n">dsc</span>
<span class="n">c6f698f19f2a2aa07dbb9bbda90a2754</span> <span class="mi">571925</span> <span class="n">text</span> <span class="n">extra</span> <span class="n">example_1</span><span class="o">.</span><span class="mf">2.</span><span class="n">orig</span><span class="o">.</span><span class="n">tar</span><span class="o">.</span><span class="n">gz</span>
<span class="mi">938512</span><span class="n">f08422f3509ff36f125f5873ba</span> <span class="mi">6220</span> <span class="n">text</span> <span class="n">extra</span> <span class="n">example_1</span><span class="o">.</span><span class="mi">2</span><span class="o">-</span><span class="mf">1.</span><span class="n">diff</span><span class="o">.</span><span class="n">gz</span>
<span class="mi">7</span><span class="n">c98fe853b3bbb47a00e5cd129b6cb56</span> <span class="mi">703542</span> <span class="n">text</span> <span class="n">extra</span> <span class="n">example_1</span><span class="o">.</span><span class="mi">2</span><span class="o">-</span><span class="mi">1</span><span class="n">_i386</span><span class="o">.</span><span class="n">deb</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="#s-f-section"><span class="std std-ref">section</span></a> and <a class="reference internal" href="#s-f-priority"><span class="std std-ref">priority</span></a> are the
values of the corresponding fields in the main source control file. If
no section or priority is specified then <code class="docutils literal notranslate"><span class="pre">-</span></code> should be used, though
section and priority values must be specified for new packages to be
installed properly.</p>
<p>The special value <code class="docutils literal notranslate"><span class="pre">byhand</span></code> for the section in a <code class="docutils literal notranslate"><span class="pre">.changes</span></code> file
indicates that the file in question is not an ordinary package file and
must be installed by hand by the distribution maintainers. If the
section is <code class="docutils literal notranslate"><span class="pre">byhand</span></code> the priority should be <code class="docutils literal notranslate"><span class="pre">-</span></code>.</p>
<p>If a new Debian revision of a package is being shipped and no new
original source archive is being distributed the <code class="docutils literal notranslate"><span class="pre">.dsc</span></code> must still
contain the <code class="docutils literal notranslate"><span class="pre">Files</span></code> field entry for the original source archive
<code class="docutils literal notranslate"><span class="pre">package_upstream-version.orig.tar.gz</span></code>, but the <code class="docutils literal notranslate"><span class="pre">.changes</span></code> file
should leave it out. In this case the original source archive on the
distribution site must match exactly, byte-for-byte, the original source
archive which was used to generate the <code class="docutils literal notranslate"><span class="pre">.dsc</span></code> file and diff which are
being uploaded.</p>
</section>
<section id="closes">
<span id="s-f-closes"></span><h3><span class="section-number">5.6.22. </span><code class="docutils literal notranslate"><span class="pre">Closes</span></code><a class="headerlink" href="#closes" title="Permalink to this headline">¶</a></h3>
<p>A space-separated list of bug report numbers that the upload governed by
the .changes file closes.</p>
</section>
<section id="homepage">
<span id="s-f-homepage"></span><h3><span class="section-number">5.6.23. </span><code class="docutils literal notranslate"><span class="pre">Homepage</span></code><a class="headerlink" href="#homepage" title="Permalink to this headline">¶</a></h3>
<p>The URL of the web site for this package, preferably (when applicable)
the site from which the original source can be obtained and any
additional upstream documentation or information may be found. The
content of this field is a simple URL without any surrounding characters
such as <code class="docutils literal notranslate"><span class="pre"><></span></code>.</p>
</section>
<section id="checksums-sha1-and-checksums-sha256">
<span id="s-f-checksums"></span><h3><span class="section-number">5.6.24. </span><code class="docutils literal notranslate"><span class="pre">Checksums-Sha1</span></code> and <code class="docutils literal notranslate"><span class="pre">Checksums-Sha256</span></code><a class="headerlink" href="#checksums-sha1-and-checksums-sha256" title="Permalink to this headline">¶</a></h3>
<p>These multiline fields contain a list of files with a checksum and size
for each one. Both <code class="docutils literal notranslate"><span class="pre">Checksums-Sha1</span></code> and <code class="docutils literal notranslate"><span class="pre">Checksums-Sha256</span></code> have the
same syntax and differ only in the checksum algorithm used: SHA-1 for
<code class="docutils literal notranslate"><span class="pre">Checksums-Sha1</span></code> and SHA-256 for <code class="docutils literal notranslate"><span class="pre">Checksums-Sha256</span></code>.</p>
<p><code class="docutils literal notranslate"><span class="pre">Checksums-Sha1</span></code> and <code class="docutils literal notranslate"><span class="pre">Checksums-Sha256</span></code> are multiline fields. The
first line of the field value (the part on the same line as
<code class="docutils literal notranslate"><span class="pre">Checksums-Sha1:</span></code> or <code class="docutils literal notranslate"><span class="pre">Checksums-Sha256:</span></code>) is always empty. The
content of the field is expressed as continuation lines, one line per
file. Each line consists of the checksum, a space, the file size, a
space, and the file name. For example (from a <code class="docutils literal notranslate"><span class="pre">.changes</span></code> file):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Checksums</span><span class="o">-</span><span class="n">Sha1</span><span class="p">:</span>
<span class="mi">1</span><span class="n">f418afaa01464e63cc1ee8a66a05f0848bd155c</span> <span class="mi">1276</span> <span class="n">example_1</span><span class="o">.</span><span class="mi">0</span><span class="o">-</span><span class="mf">1.</span><span class="n">dsc</span>
<span class="n">a0ed1456fad61116f868b1855530dbe948e20f06</span> <span class="mi">171602</span> <span class="n">example_1</span><span class="o">.</span><span class="mf">0.</span><span class="n">orig</span><span class="o">.</span><span class="n">tar</span><span class="o">.</span><span class="n">gz</span>
<span class="mf">5e86</span><span class="n">ecf0671e113b63388dac81dd8d00e00ef298</span> <span class="mi">6137</span> <span class="n">example_1</span><span class="o">.</span><span class="mi">0</span><span class="o">-</span><span class="mf">1.</span><span class="n">debian</span><span class="o">.</span><span class="n">tar</span><span class="o">.</span><span class="n">gz</span>
<span class="mi">71</span><span class="n">a0ff7da0faaf608481195f9cf30974b142c183</span> <span class="mi">548402</span> <span class="n">example_1</span><span class="o">.</span><span class="mi">0</span><span class="o">-</span><span class="mi">1</span><span class="n">_i386</span><span class="o">.</span><span class="n">deb</span>
<span class="n">Checksums</span><span class="o">-</span><span class="n">Sha256</span><span class="p">:</span>
<span class="n">ac9d57254f7e835bed299926fd51bf6f534597cc3fcc52db01c4bffedae81272</span> <span class="mi">1276</span> <span class="n">example_1</span><span class="o">.</span><span class="mi">0</span><span class="o">-</span><span class="mf">1.</span><span class="n">dsc</span>
<span class="mi">0</span><span class="n">d123be7f51e61c4bf15e5c492b484054be7e90f3081608a5517007bfb1fd128</span> <span class="mi">171602</span> <span class="n">example_1</span><span class="o">.</span><span class="mf">0.</span><span class="n">orig</span><span class="o">.</span><span class="n">tar</span><span class="o">.</span><span class="n">gz</span>
<span class="n">f54ae966a5f580571ae7d9ef5e1df0bd42d63e27cb505b27957351a495bc6288</span> <span class="mi">6137</span> <span class="n">example_1</span><span class="o">.</span><span class="mi">0</span><span class="o">-</span><span class="mf">1.</span><span class="n">debian</span><span class="o">.</span><span class="n">tar</span><span class="o">.</span><span class="n">gz</span>
<span class="mi">3</span><span class="n">bec05c03974fdecd11d020fc2e8250de8404867a8a2ce865160c250eb723664</span> <span class="mi">548402</span> <span class="n">example_1</span><span class="o">.</span><span class="mi">0</span><span class="o">-</span><span class="mi">1</span><span class="n">_i386</span><span class="o">.</span><span class="n">deb</span>
</pre></div>
</div>
<p>In the <code class="docutils literal notranslate"><span class="pre">.dsc</span></code> file, these fields list all files that make up the
source package. In the <code class="docutils literal notranslate"><span class="pre">.changes</span></code> file, these fields list all files
being uploaded. The list of files in these fields must match the list of
files in the <code class="docutils literal notranslate"><span class="pre">Files</span></code> field.</p>
</section>
<section id="dm-upload-allowed">
<span id="s5-6-25"></span><h3><span class="section-number">5.6.25. </span><code class="docutils literal notranslate"><span class="pre">DM-Upload-Allowed</span></code><a class="headerlink" href="#dm-upload-allowed" title="Permalink to this headline">¶</a></h3>
<p>Obsolete, see <a class="reference internal" href="#s-f-dm-upload-allowed"><span class="std std-ref">below</span></a>.</p>
</section>
<section id="version-control-system-vcs-fields">
<span id="s-f-vcs-fields"></span><h3><span class="section-number">5.6.26. </span>Version Control System (VCS) fields<a class="headerlink" href="#version-control-system-vcs-fields" title="Permalink to this headline">¶</a></h3>
<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.</p>
<dl>
<dt><code class="docutils literal notranslate"><span class="pre">Vcs-Browser</span></code></dt><dd><p>URL of a web interface for browsing the repository.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">Vcs-<type></span></code></dt><dd><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>The following values for <type> are supported, with the corresponding
VCS indicated in parentheses if it isn’t obvious:</p>
<ul class="simple">
<li><p>Arch</p></li>
<li><p>Bzr (Bazaar)</p></li>
<li><p>Cvs (CVS)</p></li>
<li><p>Darcs</p></li>
<li><p>Git</p></li>
<li><p>Hg (Mercurial)</p></li>
<li><p>Mtn (Monotone)</p></li>
<li><p>Svn (Subversion)</p></li>
</ul>
<p>In the case of Git, the value must have the following syntax:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">url</span><span class="o">></span> <span class="p">[</span> <span class="s2">" -b "</span> <span class="o"><</span><span class="n">branch</span><span class="o">></span> <span class="p">]</span> <span class="p">[</span> <span class="s2">" ["</span> <span class="o"><</span><span class="n">path</span><span class="o">></span> <span class="s2">"]"</span> <span class="p">]</span>
</pre></div>
</div>
<p>where the portions enclosed in brackets are optional and the portions
enclosed in double quotes are literal strings. <code class="docutils literal notranslate"><span class="pre"><url></span></code> indicates
the repository. If the <code class="docutils literal notranslate"><span class="pre"><branch></span></code> stanza is present, it names a
branch in the indicated repository. If no branch is specified, the
packaging should be on the default branch. If the <code class="docutils literal notranslate"><span class="pre"><path></span></code> stanza
is present, it specifies the relative path to the top of the packaging
tree (the parent directory of the <code class="docutils literal notranslate"><span class="pre">debian</span></code> directory). If no path
is specified, it defaults to <code class="docutils literal notranslate"><span class="pre">.</span></code> (the top level of the indicated
repository and branch).</p>
<p>For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Vcs</span><span class="o">-</span><span class="n">Git</span><span class="p">:</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">example</span><span class="o">.</span><span class="n">org</span><span class="o">/</span><span class="n">repo</span> <span class="o">-</span><span class="n">b</span> <span class="n">debian</span> <span class="p">[</span><span class="n">p</span><span class="o">/</span><span class="n">package</span><span class="p">]</span>
</pre></div>
</div>
<p>indicates a subdirectory named <code class="docutils literal notranslate"><span class="pre">p/package</span></code> in the <code class="docutils literal notranslate"><span class="pre">debian</span></code> branch
of the repository at <code class="docutils literal notranslate"><span class="pre">https://example.org/repo</span></code>.</p>
<p>In the case of Mercurial, the value must have the following syntax:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">url</span><span class="o">></span> <span class="p">[</span> <span class="s2">" -b "</span> <span class="o"><</span><span class="n">branch</span><span class="o">></span> <span class="p">]</span>
</pre></div>
</div>
<p>This is interpreted the same way as the Git syntax except a path
within the repository is not supported.</p>
<p>A package control file must not have more than one <code class="docutils literal notranslate"><span class="pre">Vcs-<type></span></code>
field. If the package is maintained in multiple version control
systems, the maintainer should specify the one that they would
prefer other people to use as the basis for proposing changes to
the package.</p>
</dd>
</dl>
<p>For both fields, any URLs given should use a scheme that provides
confidentiality (<code class="docutils literal notranslate"><span class="pre">https</span></code>, for example, rather than <code class="docutils literal notranslate"><span class="pre">http</span></code> or <code class="docutils literal notranslate"><span class="pre">git</span></code>)
if the VCS repository supports it.</p>
</section>
<section id="package-list">
<span id="s-f-package-list"></span><h3><span class="section-number">5.6.27. </span><code class="docutils literal notranslate"><span class="pre">Package-List</span></code><a class="headerlink" href="#package-list" title="Permalink to this headline">¶</a></h3>
<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 <a class="reference internal" href="#s-f-package-type"><span class="std std-ref">Package-Type</span></a>
field for a list of package types.</p>
</section>
<section id="package-type">
<span id="s-f-package-type"></span><h3><span class="section-number">5.6.28. </span><code class="docutils literal notranslate"><span class="pre">Package-Type</span></code><a class="headerlink" href="#package-type" title="Permalink to this headline">¶</a></h3>
<p>Simple field containing a word indicating the type of package: <code class="docutils literal notranslate"><span class="pre">deb</span></code>
for binary packages and <code class="docutils literal notranslate"><span class="pre">udeb</span></code> for micro binary packages. Other types
not defined here may be indicated. In source package control files, the
<code class="docutils literal notranslate"><span class="pre">Package-Type</span></code> field should be omitted instead of giving it a value of
<code class="docutils literal notranslate"><span class="pre">deb</span></code>, as this value is assumed for paragraphs lacking this field.</p>
</section>
<section id="dgit">
<span id="s-f-dgit"></span><h3><span class="section-number">5.6.29. </span><code class="docutils literal notranslate"><span class="pre">Dgit</span></code><a class="headerlink" href="#dgit" title="Permalink to this headline">¶</a></h3>
<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 <code class="docutils literal notranslate"><span class="pre">dgit</span></code>, a bidirectional gateway between the
Debian archive and Git. The commit is reachable from at least one
reference whose name matches <code class="docutils literal notranslate"><span class="pre">refs/dgit/*</span></code>. See the manual page of
<code class="docutils literal notranslate"><span class="pre">dgit</span></code> for further details.</p>
</section>
<section id="testsuite">
<span id="s-f-testsuite"></span><h3><span class="section-number">5.6.30. </span><code class="docutils literal notranslate"><span class="pre">Testsuite</span></code><a class="headerlink" href="#testsuite" title="Permalink to this headline">¶</a></h3>
<p>Simple field containing a comma-separated list of values allowing test
execution environments to discover packages which provide tests.</p>
<p>This field is automatically added to Debian source control files
(<code class="docutils literal notranslate"><span class="pre">.dsc</span></code>) by <code class="docutils literal notranslate"><span class="pre">dpkg</span></code>, with the value <code class="docutils literal notranslate"><span class="pre">autopkgtest</span></code>, when a
<code class="docutils literal notranslate"><span class="pre">debian/tests/control</span></code> file is present in the source package. This
field may also be used in source package control files
(<code class="docutils literal notranslate"><span class="pre">debian/control</span></code>) if needed in other situations.</p>
</section>
<section id="rules-requires-root">
<span id="s-f-rules-requires-root"></span><h3><span class="section-number">5.6.31. </span><code class="docutils literal notranslate"><span class="pre">Rules-Requires-Root</span></code><a class="headerlink" href="#rules-requires-root" title="Permalink to this headline">¶</a></h3>
<p>Simple field that defines if the source package requires access to
root (or fakeroot) during selected targets in the <a class="reference internal" href="ch-source.html#s-debianrules"><span class="std std-ref">Main building
script: debian/rules</span></a>.</p>
<p>The field can consist of exactly one of the following three items:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">no</span></code>: Declares that neither root nor fakeroot is required.
Package builders (e.g. dpkg-buildpackage) may choose to invoke any
target in <code class="docutils literal notranslate"><span class="pre">debian/rules</span></code> with an unprivileged user.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">binary-targets</span></code> (default): Declares that the package will need
the root (or fakeroot) when either of the <code class="docutils literal notranslate"><span class="pre">binary</span></code>,
<code class="docutils literal notranslate"><span class="pre">binary-arch</span></code> or <code class="docutils literal notranslate"><span class="pre">binary-indep</span></code> targets are called. This is
how every tool behaved before this field was defined.</p></li>
<li><p>A space separated list of keywords described below. These keywords
must always contain a forward slash, which sets them apart from the
other possible values of <code class="docutils literal notranslate"><span class="pre">Rules-Requires-Root</span></code>. When this list
is provided, the builder must provide a “gain root command” (as
defined in <a class="reference internal" href="ch-source.html#s-debianrules-gainrootapi"><span class="std std-ref">debian/rules and Rules-Requires-Root</span></a>) <em>or</em> pretend that the value was set
to <code class="docutils literal notranslate"><span class="pre">binary-targets</span></code>, and both the builder and the package’s
<code class="docutils literal notranslate"><span class="pre">debian/rules</span></code> script must downgrade accordingly (see below).</p></li>
</ul>
</div></blockquote>
<p>If the package builder supports the <code class="docutils literal notranslate"><span class="pre">Rules-Requires-Root</span></code> field and
wants to enable the feature, then it must set the environment variable
<code class="docutils literal notranslate"><span class="pre">DEB_RULES_REQUIRES_ROOT</span></code> when invoking the package building script
<code class="docutils literal notranslate"><span class="pre">debian/rules</span></code>. The value of <code class="docutils literal notranslate"><span class="pre">DEB_RULES_REQUIRES_ROOT</span></code> should be
one of:</p>
<blockquote>
<div><ul class="simple">
<li><p>The value of <code class="docutils literal notranslate"><span class="pre">Rules-Requires-Root</span></code> if the builder can support
that value. The builder may trim unnecessary whitespace used to
format the field for readability.</p></li>
<li><p>The value <code class="docutils literal notranslate"><span class="pre">binary-targets</span></code> if it cannot support the value of
<code class="docutils literal notranslate"><span class="pre">Rules-Requires-Root</span></code>.</p></li>
</ul>
</div></blockquote>
<p>A compliant builder may also leave <code class="docutils literal notranslate"><span class="pre">DEB_RULES_REQUIRES_ROOT</span></code> unset
or set it to <code class="docutils literal notranslate"><span class="pre">binary-targets</span></code> if it has been requested to test
whether the package it builds correctly implements the fall-back for
legacy builders.</p>
<section id="remarks">
<h4><span class="section-number">5.6.31.1. </span>Remarks<a class="headerlink" href="#remarks" title="Permalink to this headline">¶</a></h4>
<p>All packages and builders must support <code class="docutils literal notranslate"><span class="pre">binary-targets</span></code> as this was
the historical behaviour prior to the introduction of this field.</p>
<p>Any tool (particularly older versions of them) may be unaware of this
field and behave like the field was set to <code class="docutils literal notranslate"><span class="pre">binary-targets</span></code>. The
package build must gracefully cope with this and produce a
semantically equivalent result.</p>
<p>This field intentionally does not enable a package to request a true
root over fakeroot.</p>
</section>
<section id="definition-of-the-keywords">
<h4><span class="section-number">5.6.31.2. </span>Definition of the keywords<a class="headerlink" href="#definition-of-the-keywords" title="Permalink to this headline">¶</a></h4>
<p>The keywords have the format <code class="docutils literal notranslate"><span class="pre"><namespace>/<case></span></code>, where:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre"><namespace></span></code> must consist entirely of printable ASCII characters
except for any whitespace and the forward slash (<code class="docutils literal notranslate"><span class="pre">/</span></code>). It must
consist of at least 2 characters.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">/</span></code> (between <code class="docutils literal notranslate"><span class="pre"><namespace></span></code> and <code class="docutils literal notranslate"><span class="pre"><case></span></code>) is a single ASCII
forward slash.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre"><case></span></code> must consist entirely of printable ASCII characters
except for any whitespace. It must consist of at least 2
characters.</p></li>
</ul>
</div></blockquote>
<p>These keywords define where the package build script <code class="docutils literal notranslate"><span class="pre">debian/rules</span></code>,
or the tools called by that script, will need access to root or
fakeroot.</p>
<p>In addition to the keywords defined in the next section, each tool or
package may define keywords within a namespace named after that tool
or package. The package or tool is considered to own that namespace.</p>
<p>A tool is permitted to use the “gain root command” to do something under
(fake)root if and only if the tool defines an appropriate keyword in its
namespace, and the package lists that keyword in <code class="docutils literal notranslate"><span class="pre">Rules-Requires-Root</span></code>.</p>
<p>All tools must ignore keywords under namespaces they do not know or
own. A tool may emit a warning, or abort with an error, if it finds
unknown keywords in namespaces it owns, but it is not required to do
this for all keywords in the namespace.</p>
</section>
<section id="provided-keywords">
<h4><span class="section-number">5.6.31.3. </span>Provided keywords<a class="headerlink" href="#provided-keywords" title="Permalink to this headline">¶</a></h4>
<p>The following keywords are defined:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">dpkg/target-subcommand</span></code>: declares that there exists a command
that the <code class="docutils literal notranslate"><span class="pre">debian/rules</span></code> file must run under (fake)root</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">dpkg/target/foo</span></code>: declares that the additional, package-specific
target <code class="docutils literal notranslate"><span class="pre">foo</span></code> (that is, not one of the targets specified in
<a class="reference internal" href="ch-source.html#s-debianrules"><span class="std std-ref">Main building script: debian/rules</span></a>) must be
run under (fake)root</p></li>
</ul>
</div></blockquote>
<p>This list is intentionally incomplete. You should consult the
documentation of the tool or package in question for which keywords it
defines and when they are needed.</p>
</section>
</section>
</section>
<section id="user-defined-fields">
<span id="s5-7"></span><h2><span class="section-number">5.7. </span>User-defined fields<a class="headerlink" href="#user-defined-fields" title="Permalink to this headline">¶</a></h2>
<p>Additional user-defined fields may be added to the source package
control file. Such fields will be ignored, and not copied to (for
example) binary or Debian source control files or upload control files.</p>
<p>If you wish to add additional unsupported fields to these output files
you should use the mechanism described here.</p>
<p>Fields in the main source control information file with names starting
<code class="docutils literal notranslate"><span class="pre">X</span></code>, followed by one or more of the letters <code class="docutils literal notranslate"><span class="pre">BCS</span></code> and a hyphen
<code class="docutils literal notranslate"><span class="pre">-</span></code>, will be copied to the output files. Only the part of the field
name after the hyphen will be used in the output file. Where the letter
<code class="docutils literal notranslate"><span class="pre">B</span></code> is used the field will appear in binary package control files,
where the letter <code class="docutils literal notranslate"><span class="pre">S</span></code> is used in Debian source control files and where
<code class="docutils literal notranslate"><span class="pre">C</span></code> is used in upload control (<code class="docutils literal notranslate"><span class="pre">.changes</span></code>) files.</p>
<p>For example, if the main source information control file contains the
field</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">XBS</span><span class="o">-</span><span class="n">Comment</span><span class="p">:</span> <span class="n">I</span> <span class="n">stand</span> <span class="n">between</span> <span class="n">the</span> <span class="n">candle</span> <span class="ow">and</span> <span class="n">the</span> <span class="n">star</span><span class="o">.</span>
</pre></div>
</div>
<p>then the binary and Debian source control files will contain the field</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Comment</span><span class="p">:</span> <span class="n">I</span> <span class="n">stand</span> <span class="n">between</span> <span class="n">the</span> <span class="n">candle</span> <span class="ow">and</span> <span class="n">the</span> <span class="n">star</span><span class="o">.</span>
</pre></div>
</div>
</section>
<section id="obsolete-fields">
<span id="s-obsolete-control-data-fields"></span><h2><span class="section-number">5.8. </span>Obsolete fields<a class="headerlink" href="#obsolete-fields" title="Permalink to this headline">¶</a></h2>
<p>The following fields have been obsoleted and may be found in packages
conforming with previous versions of the Policy.</p>
<section id="s-f-dm-upload-allowed">
<span id="id15"></span><h3><span class="section-number">5.8.1. </span><code class="docutils literal notranslate"><span class="pre">DM-Upload-Allowed</span></code><a class="headerlink" href="#s-f-dm-upload-allowed" title="Permalink to this headline">¶</a></h3>
<p>Indicates that Debian Maintainers may upload this package to the Debian
archive. The only valid value is <code class="docutils literal notranslate"><span class="pre">yes</span></code>. This field was used to
regulate uploads by Debian Maintainers, See the General Resolution
<a class="reference external" href="https://www.debian.org/vote/2007/vote_003">Endorse the concept of Debian
Maintainers</a> for more
details.</p>
<dl class="footnote brackets">
<dt class="label" id="id16"><span class="brackets"><a class="fn-backref" href="#id1">1</a></span></dt>
<dd><p><code class="docutils literal notranslate"><span class="pre">dpkg</span></code>’s internal databases are in a similar format.</p>
</dd>
<dt class="label" id="id17"><span class="brackets"><a class="fn-backref" href="#id2">2</a></span></dt>
<dd><p>The paragraphs are also sometimes referred to as stanzas.</p>
</dd>
<dt class="label" id="id18"><span class="brackets"><a class="fn-backref" href="#id3">3</a></span></dt>
<dd><p>This folding method is similar to RFC 5322, allowing control files
that contain only one paragraph and no multiline fields to be read by
parsers written for RFC 5322.</p>
</dd>
<dt class="label" id="id19"><span class="brackets"><a class="fn-backref" href="#id4">4</a></span></dt>
<dd><p>It is customary to leave a space after the package name if a version
number is specified.</p>
</dd>
<dt class="label" id="id20"><span class="brackets"><a class="fn-backref" href="#id5">5</a></span></dt>
<dd><p>In the past, people specified the full version number in the
Standards-Version field, for example “2.3.0.0”. Since minor
patch-level changes don’t introduce new policy, it was thought it
would be better to relax policy and only require the first 3
components to be specified, in this example “2.3.0”. All four
components may still be used if someone wishes to do so.</p>
</dd>
<dt class="label" id="id21"><span class="brackets"><a class="fn-backref" href="#id6">6</a></span></dt>
<dd><p>Alphanumerics are <code class="docutils literal notranslate"><span class="pre">A-Za-z0-9</span></code> only.</p>
</dd>
<dt class="label" id="id22"><span class="brackets"><a class="fn-backref" href="#id7">7</a></span></dt>
<dd><p>One common use of <code class="docutils literal notranslate"><span class="pre">~</span></code> is for upstream pre-releases. For example,
<code class="docutils literal notranslate"><span class="pre">1.0~beta1~svn1245</span></code> sorts earlier than <code class="docutils literal notranslate"><span class="pre">1.0~beta1</span></code>, which sorts
earlier than <code class="docutils literal notranslate"><span class="pre">1.0</span></code>.</p>
</dd>
<dt class="label" id="id23"><span class="brackets"><a class="fn-backref" href="#id8">8</a></span></dt>
<dd><p>The author of this manual has heard of a package whose versions went
<code class="docutils literal notranslate"><span class="pre">1.1</span></code>, <code class="docutils literal notranslate"><span class="pre">1.2</span></code>, <code class="docutils literal notranslate"><span class="pre">1.3</span></code>, <code class="docutils literal notranslate"><span class="pre">1</span></code>, <code class="docutils literal notranslate"><span class="pre">2.1</span></code>, <code class="docutils literal notranslate"><span class="pre">2.2</span></code>, <code class="docutils literal notranslate"><span class="pre">2</span></code> and so
forth.</p>
</dd>
<dt class="label" id="id24"><span class="brackets"><a class="fn-backref" href="#id9">9</a></span></dt>
<dd><p>Completely empty lines will not be rendered as blank lines. Instead,
they will cause the parser to think you’re starting a whole new
record in the control file, and will therefore likely abort with an
error.</p>
</dd>
<dt class="label" id="id25"><span class="brackets"><a class="fn-backref" href="#id10">10</a></span></dt>
<dd><p>Example distribution names in the Debian archive used in <code class="docutils literal notranslate"><span class="pre">.changes</span></code>
files are:</p>
<dl class="simple">
<dt><em>unstable</em></dt><dd><p>This distribution value refers to the <em>developmental</em> part of the
Debian distribution tree. Most new packages, new upstream
versions of packages and bug fixes go into the <em>unstable</em>
directory tree.</p>
</dd>
<dt><em>experimental</em></dt><dd><p>The packages with this distribution value are deemed by their
maintainers to be high risk. Oftentimes they represent early beta
or developmental packages from various sources that the
maintainers want people to try, but are not ready to be a part of
the other parts of the Debian distribution tree.</p>
</dd>
</dl>
<p>Others are used for updating stable releases or for security uploads.
More information is available in the Debian Developer’s Reference,
section “The Debian archive”.</p>
</dd>
<dt class="label" id="id26"><span class="brackets"><a class="fn-backref" href="#id11">11</a></span></dt>
<dd><p>The source formats currently supported by the Debian archive software
are <code class="docutils literal notranslate"><span class="pre">1.0</span></code>, <code class="docutils literal notranslate"><span class="pre">3.0</span> <span class="pre">(native)</span></code>, and <code class="docutils literal notranslate"><span class="pre">3.0</span> <span class="pre">(quilt)</span></code>.</p>
</dd>
<dt class="label" id="id27"><span class="brackets"><a class="fn-backref" href="#id12">12</a></span></dt>
<dd><p>Other urgency values are supported with configuration changes in the
archive software but are not used in Debian. The urgency affects how
quickly a package will be considered for inclusion into the
<code class="docutils literal notranslate"><span class="pre">testing</span></code> distribution and gives an indication of the importance of
any fixes included in the upload. <code class="docutils literal notranslate"><span class="pre">Emergency</span></code> and <code class="docutils literal notranslate"><span class="pre">critical</span></code> are
treated as synonymous.</p>
</dd>
<dt class="label" id="id28"><span class="brackets"><a class="fn-backref" href="#id13">13</a></span></dt>
<dd><p>A space after each comma is conventional.</p>
</dd>
<dt class="label" id="id29"><span class="brackets"><a class="fn-backref" href="#id14">14</a></span></dt>
<dd><p>That is, the parts which are not the <code class="docutils literal notranslate"><span class="pre">.dsc</span></code>.</p>
</dd>
</dl>
</section>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">5. Control files and their fields</a><ul>
<li><a class="reference internal" href="#syntax-of-control-files">5.1. Syntax of control files</a></li>
<li><a class="reference internal" href="#source-package-control-files-debian-control">5.2. Source package control files – <code class="docutils literal notranslate"><span class="pre">debian/control</span></code></a></li>
<li><a class="reference internal" href="#binary-package-control-files-debian-control">5.3. Binary package control files – <code class="docutils literal notranslate"><span class="pre">DEBIAN/control</span></code></a></li>
<li><a class="reference internal" href="#debian-source-control-files-dsc">5.4. Debian source control files – <code class="docutils literal notranslate"><span class="pre">.dsc</span></code></a></li>
<li><a class="reference internal" href="#debian-changes-files-changes">5.5. Debian changes files – <code class="docutils literal notranslate"><span class="pre">.changes</span></code></a></li>
<li><a class="reference internal" href="#list-of-fields">5.6. List of fields</a><ul>
<li><a class="reference internal" href="#source">5.6.1. <code class="docutils literal notranslate"><span class="pre">Source</span></code></a></li>
<li><a class="reference internal" href="#maintainer">5.6.2. <code class="docutils literal notranslate"><span class="pre">Maintainer</span></code></a></li>
<li><a class="reference internal" href="#uploaders">5.6.3. <code class="docutils literal notranslate"><span class="pre">Uploaders</span></code></a></li>
<li><a class="reference internal" href="#changed-by">5.6.4. <code class="docutils literal notranslate"><span class="pre">Changed-By</span></code></a></li>
<li><a class="reference internal" href="#section">5.6.5. <code class="docutils literal notranslate"><span class="pre">Section</span></code></a></li>
<li><a class="reference internal" href="#priority">5.6.6. <code class="docutils literal notranslate"><span class="pre">Priority</span></code></a></li>
<li><a class="reference internal" href="#package">5.6.7. <code class="docutils literal notranslate"><span class="pre">Package</span></code></a></li>
<li><a class="reference internal" href="#architecture">5.6.8. <code class="docutils literal notranslate"><span class="pre">Architecture</span></code></a></li>
<li><a class="reference internal" href="#essential">5.6.9. <code class="docutils literal notranslate"><span class="pre">Essential</span></code></a></li>
<li><a class="reference internal" href="#package-interrelationship-fields-depends-pre-depends-recommends-suggests-breaks-conflicts-provides-replaces-enhances">5.6.10. Package interrelationship fields: <code class="docutils literal notranslate"><span class="pre">Depends</span></code>, <code class="docutils literal notranslate"><span class="pre">Pre-Depends</span></code>, <code class="docutils literal notranslate"><span class="pre">Recommends</span></code>, <code class="docutils literal notranslate"><span class="pre">Suggests</span></code>, <code class="docutils literal notranslate"><span class="pre">Breaks</span></code>, <code class="docutils literal notranslate"><span class="pre">Conflicts</span></code>, <code class="docutils literal notranslate"><span class="pre">Provides</span></code>, <code class="docutils literal notranslate"><span class="pre">Replaces</span></code>, <code class="docutils literal notranslate"><span class="pre">Enhances</span></code></a></li>
<li><a class="reference internal" href="#standards-version">5.6.11. <code class="docutils literal notranslate"><span class="pre">Standards-Version</span></code></a></li>
<li><a class="reference internal" href="#version">5.6.12. <code class="docutils literal notranslate"><span class="pre">Version</span></code></a><ul>
<li><a class="reference internal" href="#epochs-should-be-used-sparingly">5.6.12.1. Epochs should be used sparingly</a></li>
</ul>
</li>
<li><a class="reference internal" href="#description">5.6.13. <code class="docutils literal notranslate"><span class="pre">Description</span></code></a></li>
<li><a class="reference internal" href="#distribution">5.6.14. <code class="docutils literal notranslate"><span class="pre">Distribution</span></code></a></li>
<li><a class="reference internal" href="#date">5.6.15. <code class="docutils literal notranslate"><span class="pre">Date</span></code></a></li>
<li><a class="reference internal" href="#format">5.6.16. <code class="docutils literal notranslate"><span class="pre">Format</span></code></a></li>
<li><a class="reference internal" href="#urgency">5.6.17. <code class="docutils literal notranslate"><span class="pre">Urgency</span></code></a></li>
<li><a class="reference internal" href="#changes">5.6.18. <code class="docutils literal notranslate"><span class="pre">Changes</span></code></a></li>
<li><a class="reference internal" href="#binary">5.6.19. <code class="docutils literal notranslate"><span class="pre">Binary</span></code></a></li>
<li><a class="reference internal" href="#installed-size">5.6.20. <code class="docutils literal notranslate"><span class="pre">Installed-Size</span></code></a></li>
<li><a class="reference internal" href="#files">5.6.21. <code class="docutils literal notranslate"><span class="pre">Files</span></code></a></li>
<li><a class="reference internal" href="#closes">5.6.22. <code class="docutils literal notranslate"><span class="pre">Closes</span></code></a></li>
<li><a class="reference internal" href="#homepage">5.6.23. <code class="docutils literal notranslate"><span class="pre">Homepage</span></code></a></li>
<li><a class="reference internal" href="#checksums-sha1-and-checksums-sha256">5.6.24. <code class="docutils literal notranslate"><span class="pre">Checksums-Sha1</span></code> and <code class="docutils literal notranslate"><span class="pre">Checksums-Sha256</span></code></a></li>
<li><a class="reference internal" href="#dm-upload-allowed">5.6.25. <code class="docutils literal notranslate"><span class="pre">DM-Upload-Allowed</span></code></a></li>
<li><a class="reference internal" href="#version-control-system-vcs-fields">5.6.26. Version Control System (VCS) fields</a></li>
<li><a class="reference internal" href="#package-list">5.6.27. <code class="docutils literal notranslate"><span class="pre">Package-List</span></code></a></li>
<li><a class="reference internal" href="#package-type">5.6.28. <code class="docutils literal notranslate"><span class="pre">Package-Type</span></code></a></li>
<li><a class="reference internal" href="#dgit">5.6.29. <code class="docutils literal notranslate"><span class="pre">Dgit</span></code></a></li>
<li><a class="reference internal" href="#testsuite">5.6.30. <code class="docutils literal notranslate"><span class="pre">Testsuite</span></code></a></li>
<li><a class="reference internal" href="#rules-requires-root">5.6.31. <code class="docutils literal notranslate"><span class="pre">Rules-Requires-Root</span></code></a><ul>
<li><a class="reference internal" href="#remarks">5.6.31.1. Remarks</a></li>
<li><a class="reference internal" href="#definition-of-the-keywords">5.6.31.2. Definition of the keywords</a></li>
<li><a class="reference internal" href="#provided-keywords">5.6.31.3. Provided keywords</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#user-defined-fields">5.7. User-defined fields</a></li>
<li><a class="reference internal" href="#obsolete-fields">5.8. Obsolete fields</a><ul>
<li><a class="reference internal" href="#s-f-dm-upload-allowed">5.8.1. <code class="docutils literal notranslate"><span class="pre">DM-Upload-Allowed</span></code></a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="ch-source.html"
title="previous chapter"><span class="section-number">4. </span>Source packages</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="ch-maintainerscripts.html"
title="next chapter"><span class="section-number">6. </span>Package maintainer scripts and installation procedure</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/ch-controlfields.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="ch-maintainerscripts.html" title="6. Package maintainer scripts and installation procedure"
>next</a> |</li>
<li class="right" >
<a href="ch-source.html" title="4. Source packages"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Debian Policy Manual v4.6.0.1</a> »</li>
<li class="nav-item nav-item-this"><a href=""><span class="section-number">5. </span>Control files and their fields</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.2.0.
</div>
</body>
</html>