</sect>
- <sect>
+ <sect id="dependencies">
<heading>Dependencies</heading>
<p>
fields<footnote>
The paragraphs are also sometimes referred to as stanzas.
</footnote>.
- The paragraphs are separated by blank lines. Some control
+ 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.)
+ 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. It ends at
- the end of the (logical) line. Horizontal whitespace
+ then the data/value associated with that field. The field
+ name is composed of printable ASCII characters (i.e.,
+ characters that have values between 33 and 126, inclusive)
+ except colon and must not with a begin with #. The
+ field ends at the end of the line or at the end of the
+ last continuation line (see below). Horizontal whitespace
(spaces and tabs) may occur immediately before or after the
value and is ignored there; it is conventional to put a
single space after the colon. For example, a field might
</p>
<p>
- Many fields' values may span several lines; in this case
- each continuation line must start with a space or a tab.
- Any trailing spaces or tabs at the end of individual
- lines of a field value are ignored.
+ There are three types of fields:
+ <taglist>
+ <tag>simple</tag>
+ <item>
+ 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.
+ </item>
+ <tag>folded</tag>
+ <item>
+ 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.<footnote>
+ 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.
+ </footnote>
+ </item>
+ <tag>multiline</tag>
+ <item>
+ 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 the folded fields. Whitespace, including newlines,
+ is significant in the values of multiline fields.
+ </item>
+ </taglist>
</p>
<p>
- In fields where it is specified that lines may not wrap,
- only a single line of data is allowed and whitespace is not
- significant in a field body. Whitespace must not appear
+ 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.
</p>
<p>
- Blank lines, or lines consisting only of spaces and tabs,
- are not allowed within field values or between fields - that
- would mean a new paragraph.
+ Paragraph separators (empty lines) and lines consisting only of
+ spaces and tabs are not allowed within field values or between
+ fields. Empty lines in field values are usually escaped by
+ representing them by a space followed by a dot.
+ </p>
+
+ <p>
+ Lines starting with # without any preceding whitespace are comments
+ lines that are only permitted in source package control files
+ (<file>debian/control</file>). These comment lines are ignored, even
+ between two continuation lines. They do not end logical lines.
</p>
<p>
<item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
<item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
<item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
- <item><qref id="f-DM-Upload-Allowed"<tt>DM-Upload-Allowed</tt></qref></item>
+ <item><qref id="f-DM-Upload-Allowed"><tt>DM-Upload-Allowed</tt></qref></item>
<item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
<item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
<item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
<file>.changes</file> file to accompany the upload, and by
<prgn>dpkg-source</prgn> when it creates the
<file>.dsc</file> source control file as part of a source
- archive. Many fields are permitted to span multiple lines in
- <file>debian/control</file> but not in any other control
+ archive. Some fields are folded in <file>debian/control</file>,
+ but not in any other control
file. These tools are responsible for removing the line
breaks from such fields when using fields from
<file>debian/control</file> to generate other control files.
when they generate output control files.
See <ref id="substvars"> for details.
</p>
-
- <p>
- In addition to the control file syntax described <qref
- id="controlsyntax">above</qref>, this file may also contain
- comment lines starting with <tt>#</tt> without any preceding
- whitespace. All such lines are ignored, even in the middle of
- continuation lines for a multiline field, and do not end a
- multiline field.
- </p>
-
</sect>
<sect id="binarycontrolfiles">
<item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
<item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
<item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
- <item><qref id="f-DM-Upload-Allowed"<tt>DM-Upload-Allowed</tt></qref></item>
+ <item><qref id="f-DM-Upload-Allowed"><tt>DM-Upload-Allowed</tt></qref></item>
<item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
<item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
<item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
</p>
<p>
- Any parser that interprets the Uploaders field in
- <file>debian/control</file> must permit it to span multiple
- lines. Line breaks in an Uploaders field that spans multiple
- lines are not significant and the semantics of the field are
- the same as if the line breaks had not been present.
+ The Uploaders field in <file>debian/control</file> can be folded.
</p>
</sect1>
<p>
In the source package control file <file>.dsc</file>, this
- field may contain either the architecture
- wildcard <tt>any</tt> or a list of architectures and
- architecture wildcards separated by spaces. If a list is
- given, it may include (or consist solely of) the special
+ field contains a list of architectures and architecture
+ wildcards separated by spaces. When the list contains the
+ architecture wildcard <tt>any</tt>, the only other value
+ allowed in the list is <tt>all</tt>.
+ </p>
+
+ <p>
+ The list may include (or consist solely of) the special
value <tt>all</tt>. In other words, in <file>.dsc</file>
files unlike the <file>debian/control</file>, <tt>all</tt> may
occur in combination with specific architectures.
</p>
<p>
- Specifying <tt>any</tt> indicates that the source package
+ Specifying only <tt>any</tt> 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 either be specific to whatever the current build
- architecture is or will be architecture-independent.
+ will be specific to whatever the current build architecture is.
</p>
<p>
Specifying only <tt>all</tt> indicates that the source package
- will only build architecture-independent packages. If this is
- the case, <tt>all</tt> must be used rather than <tt>any</tt>;
- <tt>any</tt> implies that the source package will build at
- least one architecture-dependent package.
+ will only build architecture-independent packages.
+ </p>
+
+ <p>
+ Specifying <tt>any all</tt> indicates that the source package
+ isn't dependent on any particular architecture. The set of
+ produced binary packages will include at least one
+ architecture-dependant package and one architecture-independent
+ package.
</p>
<p>
<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 main source control data file.
+ paragraph of a source package control file.
</p>
<p>
In a source or binary control file, the <tt>Description</tt>
field contains a description of the binary package, consisting
of two parts, the synopsis or the short description, and the
- long description. The field's format is as follows:
+ long description. It is a multiline field with the following
+ format:
</p>
<p>
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 <tt>Description:</tt>) is
- always empty. The content of the field is expressed as
- continuation lines, one line per package. Each line 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 (<tt>-</tt>), a space, and the
short description line from that package.
<heading><tt>Changes</tt></heading>
<p>
- This field contains the human-readable changes data, describing
+ This multiline field contains the human-readable changes data, describing
the differences between the last version and the current one.
</p>
<heading><tt>Binary</tt></heading>
<p>
- This field is a list of binary packages. Its syntax and
+ This folded field is a list of binary packages. Its syntax and
meaning varies depending on the control file in which it
appears.
</p>
packages which a source package can produce, separated by
commas<footnote>
A space after each comma is conventional.
- </footnote>. It may span multiple lines. The source package
+ </footnote>. 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
<p>
When it appears in a <file>.changes</file> file, it lists the
names of the binary packages being uploaded, separated by
- whitespace (not commas). It may span multiple lines.
+ whitespace (not commas).
</p>
</sect1>
and <tt>Checksums-Sha256</tt></heading>
<p>
- These fields contain a list of files with a checksum and size
+ These multiline fields contain a list of files with a checksum and size
for each one. Both <tt>Checksums-Sha1</tt>
and <tt>Checksums-Sha256</tt> have the same syntax and differ
only in the checksum algorithm used: SHA-1
specification subject to the rules in <ref
id="controlsyntax">, and must appear where it's necessary to
disambiguate; it is not otherwise significant. All of the
- relationship fields may span multiple lines. For
+ relationship fields can only be folded in source package control files. For
consistency and in case of future changes to
<prgn>dpkg</prgn> it is recommended that a single space be
used after a version relationship and before a version
number; it is also conventional to put a single space after
each comma, on either side of each vertical bar, and before
- each open parenthesis. When wrapping a relationship field, it
+ each open parenthesis. When opening a continuation line in a relationship field, it
is conventional to do so after a comma and before the space
following that comma.
</p>
installation would hamper the ability of the system to
continue with any upgrade that might be in progress.
</p>
+
+ <p>
+ You should not specify a <tt>Pre-Depends</tt> entry for a
+ package before this has been discussed on the
+ <tt>debian-devel</tt> mailing list and a consensus about
+ doing that has been reached. See <ref id="dependencies">.
+ </p>
</item>
</taglist>
</p>
<file>/lib/<var>triplet</var></file> and
<file>/usr/lib/<var>triplet</var></file>, where
<tt><var>triplet</var></tt> is the value returned by
- <tt>dpkg-architecture -qDEB_HOST_GNU_TYPE</tt> for the
+ <tt>dpkg-architecture -qDEB_HOST_MULTIARCH</tt> for the
architecture of the package. Packages may <em>not</em>
install files to any <var>triplet</var> path other
than the one matching the architecture of that package;
for instance, an <tt>Architecture: amd64</tt> package
containing 32-bit x86 libraries may not install these
- libraries to <file>/usr/lib/i486-linux-gnu</file>.
+ libraries to <file>/usr/lib/i386-linux-gnu</file>.
<footnote>
This is necessary in order to reserve the directories for
use in cross-installation of library packages from other
<item>
If the window manager complies with <url
- id="http://www.freedesktop.org/Standards/wm-spec"
+ id="http://www.freedesktop.org/wiki/Specifications/wm-spec"
name="The Window Manager Specification Project">,
- written by the <url id="http://www.freedesktop.org/"
+ written by the <url id="http://www.freedesktop.org/wiki/"
name="Free Desktop Group">, add 40 points.
</item>
policy (such as for <ref id="appdefaults">).
</p>
</sect1>
-
- <sect1>
- <heading>The OSF/Motif and OpenMotif libraries</heading>
-
- <p>
- <em>Programs that require the non-DFSG-compliant OSF/Motif or
- OpenMotif libraries</em><footnote>
- OSF/Motif and OpenMotif are collectively referred to as
- "Motif" in this policy document.
- </footnote>
- should be compiled against and tested with LessTif (a free
- re-implementation of Motif) instead. If the maintainer
- judges that the program or programs do not work
- sufficiently well with LessTif to be distributed and
- supported, but do so when compiled against Motif, then two
- versions of the package should be created; one linked
- statically against Motif and with <tt>-smotif</tt>
- appended to the package name, and one linked dynamically
- against Motif and with <tt>-dmotif</tt> appended to the
- package name.
- </p>
-
- <p>
- Both Motif-linked versions are dependent
- upon non-DFSG-compliant software and thus cannot be
- uploaded to the <em>main</em> distribution; if the
- software is itself DFSG-compliant it may be uploaded to
- the <em>contrib</em> distribution. While known existing
- versions of Motif permit unlimited redistribution of
- binaries linked against the library (whether statically or
- dynamically), it is the package maintainer's
- responsibility to determine whether this is permitted by
- the license of the copy of Motif in their possession.
- </p>
- </sect1>
</sect>
<sect id="perl">
<!-- Local variables: -->
<!-- indent-tabs-mode: t -->
<!-- End: -->
-<!-- vim:set ai et sts=2 sw=2 tw=76: -->
+<!-- vim:set ai sts=2 sw=2 tw=76: -->
projects / debian / debian-policy.git / blobdiff