+
+ <sect1 id="f-Priority">
+ <heading><tt>Priority</tt></heading>
+
+ <p>
+ This field represents how important that it is that the user
+ have the package installed. See <ref id="priorities">.
+ </p>
+
+ <p>
+ When it appears in the <file>debian/control</file> file,
+ it gives the value for the subfield of the same name in
+ the <tt>Files</tt> field of the <file>.changes</file> file.
+ It also gives the default for the same field in the binary
+ packages.
+ </p>
+ </sect1>
+
+ <sect1 id="f-Package">
+ <heading><tt>Package</tt></heading>
+
+ <p>
+ The name of the binary package.
+ </p>
+
+ <p>
+ Package names must consist only of lower case letters
+ (<tt>a-z</tt>), digits (<tt>0-9</tt>), plus (<tt>+</tt>)
+ and minus (<tt>-</tt>) signs, and periods (<tt>.</tt>).
+ They must be at least two characters long and must start
+ with an alphanumeric character.
+ </p>
+ </sect1>
+
+ <sect1 id="f-Architecture">
+ <heading><tt>Architecture</tt></heading>
+
+ <p>
+ Depending on context and the control file used, the
+ <tt>Architecture</tt> field can include the following sets of
+ values:
+ <list>
+ <item>A unique single word identifying a Debian machine
+ architecture, see <ref id="arch-spec">.
+ <item><tt>all</tt>, which indicates an
+ architecture-independent package.
+ <item><tt>any</tt>, which indicates a package available
+ for building on any architecture.
+ <item><tt>source</tt>, which indicates a source package.
+ </list>
+ </p>
+
+ <p>
+ In the main <file>debian/control</file> file in the source
+ package, or in the source package control file
+ <file>.dsc</file>, one may specify a list of architectures
+ separated by spaces, or the special values <tt>any</tt> or
+ <tt>all</tt>.
+ </p>
+
+ <p>
+ Specifying <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 be specific to whatever the current build architecture
+ is.<footnote>
+ This is the most often used setting, and is recommended
+ for new packages that aren't <tt>Architecture: all</tt>.
+ </footnote>
+ </p>
+
+ <p>
+ Specifying a list of architectures indicates that the source
+ will build an architecture-dependent package, and will only
+ work correctly on the listed architectures.<footnote>
+ This is a setting used for a minority of cases where the
+ program is not portable. Generally, it should not be used
+ for new packages.
+ </footnote>
+ </p>
+
+ <p>
+ In a <file>.changes</file> file, the <tt>Architecture</tt>
+ 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 <tt>source</tt> is also present.
+ </p>
+
+ <p>
+ See <ref id="debianrules"> for information how to get the
+ architecture for the build process.
+ </p>
+ </sect1>
+
+ <sect1 id="f-Essential">
+ <heading><tt>Essential</tt></heading>
+
+ <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.
+ </p>
+
+ <p>
+ If set to <tt>yes</tt> then the package management system
+ will refuse to remove the package (upgrading and replacing
+ it is still possible). The other possible value is <tt>no</tt>,
+ which is the same as not having the field at all.
+ </p>
+ </sect1>
+
+ <sect1>
+ <heading>Package interrelationship fields:
+ <tt>Depends</tt>, <tt>Pre-Depends</tt>,
+ <tt>Recommends</tt>, <tt>Suggests</tt>,
+ <tt>Breaks</tt>, <tt>Conflicts</tt>,
+ <tt>Provides</tt>, <tt>Replaces</tt>, <tt>Enhances</tt>
+ </heading>
+
+ <p>
+ These fields describe the package's relationships with
+ other packages. Their syntax and semantics are described
+ in <ref id="relationships">.</p>
+ </sect1>
+
+ <sect1 id="f-Standards-Version">
+ <heading><tt>Standards-Version</tt></heading>
+
+ <p>
+ The most recent version of the standards (the policy
+ manual and associated texts) with which the package
+ complies.
+ </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 the all
+ four components may be specified.<footnote>
+ 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.
+ </footnote>
+ </p>
+
+ </sect1>
+
+ <sect1 id="f-Version">
+ <heading><tt>Version</tt></heading>
+
+ <p>
+ The version number of a package. The format is:
+ [<var>epoch</var><tt>:</tt>]<var>upstream_version</var>[<tt>-</tt><var>debian_revision</var>]
+ </p>
+
+ <p>
+ The three components here are:
+ <taglist>
+ <tag><var>epoch</var></tag>
+ <item>
+ <p>
+ This is a single (generally small) unsigned integer. It
+ may be omitted, in which case zero is assumed. If it is
+ omitted then the <var>upstream_version</var> may not
+ contain any colons.
+ </p>
+
+ <p>
+ It is provided to allow mistakes in the version numbers
+ of older versions of a package, and also a package's
+ previous version numbering schemes, to be left behind.
+ </p>
+ </item>
+
+ <tag><var>upstream_version</var></tag>
+ <item>
+ <p>
+ This is the main part of the version number. It is
+ usually the version number of the original ("upstream")
+ package from which the <file>.deb</file> 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 <var>upstream_version</var> is
+ described below. The <var>upstream_version</var>
+ portion of the version number is mandatory.
+ </p>
+
+ <p>
+ The <var>upstream_version</var> may contain only
+ alphanumerics<footnote>
+ Alphanumerics are <tt>A-Za-z0-9</tt> only.
+ </footnote>
+ and the characters <tt>.</tt> <tt>+</tt> <tt>-</tt>
+ <tt>:</tt> <tt>~</tt> (full stop, plus, hyphen, colon,
+ tilde) and should start with a digit. If there is no
+ <var>debian_revision</var> then hyphens are not allowed;
+ if there is no <var>epoch</var> then colons are not
+ allowed.
+ </p>
+ </item>
+
+ <tag><var>debian_revision</var></tag>
+ <item>
+ <p>
+ This part of the version number specifies the version of
+ the Debian package based on the upstream version. It
+ may contain only alphanumerics and the characters
+ <tt>+</tt> <tt>.</tt> <tt>~</tt> (plus, full stop,
+ tilde) and is compared in the same way as the
+ <var>upstream_version</var> is.
+ </p>
+
+ <p>
+ It is optional; if it isn't present then the
+ <var>upstream_version</var> may not contain a hyphen.
+ This format represents the case where a piece of
+ software was written specifically to be turned into a
+ Debian package, and so there is only one "debianisation"
+ of it and therefore no revision indication is required.
+ </p>
+
+ <p>
+ It is conventional to restart the
+ <var>debian_revision</var> at <tt>1</tt> each time the
+ <var>upstream_version</var> 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 <var>upstream_version</var> and
+ <var>debian_revision</var>. The absence of a
+ <var>debian_revision</var> compares earlier than the
+ presence of one (but note that the
+ <var>debian_revision</var> is the least significant part
+ of the version number).
+ </p>
+ </item>
+ </taglist>
+ </p>
+
+ <p>
+ The <var>upstream_version</var> and <var>debian_revision</var>
+ parts are compared by the package management system using the
+ same 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: <tt>~~</tt>, <tt>~~a</tt>, <tt>~</tt>, the empty part,
+ <tt>a</tt>.<footnote>
+ One common use of <tt>~</tt> is for upstream pre-releases.
+ For example, <tt>1.0~beta1~svn1245</tt> sorts earlier than
+ <tt>1.0~beta1</tt>, which sorts earlier than <tt>1.0</tt>.
+ </footnote>
+ </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>
+
+ <p>
+ Note that the purpose of epochs is to allow us to leave behind
+ mistakes in version numbering, and to cope with situations
+ where the version numbering scheme changes. It is
+ <em>not</em> intended to cope with version numbers containing
+ strings of letters which the package management system cannot
+ interpret (such as <tt>ALPHA</tt> or <tt>pre-</tt>), or with
+ silly orderings (the author of this manual has heard of a
+ package whose versions went <tt>1.1</tt>, <tt>1.2</tt>,
+ <tt>1.3</tt>, <tt>1</tt>, <tt>2.1</tt>, <tt>2.2</tt>,
+ <tt>2</tt> and so forth).
+ </p>
+ </sect1>
+
+ <sect1 id="f-Description">
+ <heading><tt>Description</tt></heading>
+
+ <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:
+ </p>
+
+ <p>
+<example>
+ Description: <single line synopsis>
+ <extended description over several lines>
+</example>
+ </p>
+
+ <p>
+ The lines in the extended description can have these formats:
+ </p>
+
+ <p><list>
+
+ <item>
+ 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.
+ </item>
+
+ <item>
+ 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).
+ </item>
+
+ <item>
+ 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<footnote>
+ 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.
+ </footnote>.
+ </item>
+
+ <item>
+ Those containing a space, a full stop and some more characters.
+ These are for future expansion. Do not use them.
+ </item>
+
+ </list></p>
+
+ <p>
+ Do not use tab characters. Their effect is not predictable.
+ </p>
+
+ <p>
+ See <ref id="descriptions"> for further information on this.
+ </p>
+
+ <p>
+ In a <file>.changes</file> file, the <tt>Description</tt> field
+ contains a summary of the descriptions for the packages being
+ uploaded.
+ </p>
+
+ <p>
+ The part of the field before the first newline is empty;
+ thereafter each line has the name of a binary package and
+ the summary description line from that binary package.
+ Each line is indented by one space.
+ </p>
+
+ </sect1>
+
+ <sect1 id="f-Distribution">
+ <heading><tt>Distribution</tt></heading>
+
+ <p>
+ In a <file>.changes</file> 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.<footnote>
+ Current distribution names are:
+ <taglist compact="compact">
+ <tag><em>stable</em></tag>
+ <item>
+ This is the current "released" version of Debian
+ GNU/Linux. Once the distribution is
+ <em>stable</em> only security fixes and other
+ major bug fixes are allowed. When changes are
+ made to this distribution, the release number is
+ increased (for example: 2.2r1 becomes 2.2r2 then
+ 2.2r3, etc).
+ </item>
+
+ <tag><em>unstable</em></tag>
+ <item>
+ This distribution value refers to the
+ <em>developmental</em> part of the Debian
+ distribution tree. New packages, new upstream
+ versions of packages and bug fixes go into the
+ <em>unstable</em> directory tree. Download from
+ this distribution at your own risk.
+ </item>
+
+ <tag><em>testing</em></tag>
+ <item>
+ This distribution value refers to the
+ <em>testing</em> part of the Debian distribution
+ tree. It receives its packages from the
+ unstable distribution after a short time lag to
+ ensure that there are no major issues with the
+ unstable packages. It is less prone to breakage
+ than unstable, but still risky. It is not
+ possible to upload packages directly to
+ <em>testing</em>.
+ </item>
+
+ <tag><em>frozen</em></tag>
+ <item>
+ From time to time, the <em>testing</em>
+ distribution enters a state of "code-freeze" in
+ anticipation of release as a <em>stable</em>
+ version. During this period of testing only
+ fixes for existing or newly-discovered bugs will
+ be allowed. The exact details of this stage are
+ determined by the Release Manager.
+ </item>
+
+ <tag><em>experimental</em></tag>
+ <item>
+ 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. Download at your own
+ risk.
+ </item>
+ </taglist>
+
+ <p>
+ You should list <em>all</em> distributions that the
+ package should be installed into.
+ </p>
+
+ <p>
+ More information is available in the Debian Developer's
+ Reference, section "The Debian archive".
+ </p>
+ </footnote>
+ </p>
+ </sect1>
+
+ <sect1 id="f-Date">
+ <heading><tt>Date</tt></heading>
+
+ <p>
+ This field includes the date the package was built or last edited.
+ </p>
+
+ <p>
+ The value of this field is usually extracted from the
+ <file>debian/changelog</file> file - see
+ <ref id="dpkgchangelog">).
+ </p>
+ </sect1>
+
+ <sect1 id="f-Format">
+ <heading><tt>Format</tt></heading>
+
+ <p>
+ This field specifies a format revision for the file.
+ The most current format described in the Policy Manual
+ is version <strong>1.5</strong>. The syntax of the
+ format value is the same as that of a package version
+ number except that no epoch or Debian revision is allowed
+ - see <ref id="f-Version">.
+ </p>
+ </sect1>
+
+ <sect1 id="f-Urgency">
+ <heading><tt>Urgency</tt></heading>
+
+ <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 <tt>low</tt>,
+ <tt>medium</tt>, <tt>high</tt>, <tt>emergency</tt>, or
+ <tt>critical</tt><footnote>
+ 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 <tt>testing</tt> distribution and
+ gives an indication of the importance of any fixes included
+ in the upload. <tt>Emergency</tt> and <tt>critical</tt> are
+ treated as synonymous.
+ </footnote> (not case-sensitive) followed by an optional
+ commentary (separated by a space) which is usually in
+ parentheses. For example:
+
+ <example>
+ Urgency: low (HIGH for users of diversions)
+ </example>
+
+ </p>
+
+ <p>
+ The value of this field is usually extracted from the
+ <file>debian/changelog</file> file - see
+ <ref id="dpkgchangelog">.
+ </p>
+ </sect1>
+
+ <sect1 id="f-Changes">
+ <heading><tt>Changes</tt></heading>
+
+ <p>
+ This field contains the human-readable changes data, describing
+ the differences between the last version and the current one.
+ </p>
+
+ <p>
+ There should be nothing in this field before the first
+ newline; all the subsequent lines must be indented by at
+ least one space; blank lines must be represented by a line
+ consisting only of a space and a full stop.
+ </p>
+
+ <p>
+ The value of this field is usually extracted from the
+ <file>debian/changelog</file> file - see
+ <ref id="dpkgchangelog">).
+ </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 blank line).
+ </p>
+ </sect1>
+
+ <sect1 id="f-Binary">
+ <heading><tt>Binary</tt></heading>
+
+ <p>
+ This field is a list of binary packages.
+ </p>
+
+ <p>
+ When it appears in the <file>.dsc</file> file it is the list
+ of binary packages which a source package can produce. It
+ 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 <file>.changes</file> file it lists the
+ names of the binary packages actually being uploaded.
+ </p>
+
+ <p>
+ The syntax is a list of binary packages separated by
+ commas<footnote>
+ A space after each comma is conventional.
+ </footnote>. Currently the packages must be separated using
+ only spaces in the <file>.changes</file> file.
+ </p>
+ </sect1>
+
+ <sect1 id="f-Installed-Size">
+ <heading><tt>Installed-Size</tt></heading>
+
+ <p>
+ This field appears in the control files of binary
+ packages, and in the <file>Packages</file> files. It gives
+ the total amount of disk space required to install the
+ named package.
+ </p>
+
+ <p>
+ The disk space is represented in kilobytes as a simple
+ decimal number.
+ </p>
+ </sect1>
+
+ <sect1 id="f-Files">
+ <heading><tt>Files</tt></heading>
+
+ <p>
+ This field contains a list of files with information about
+ each one. The exact information and syntax varies with
+ the context. In all cases the part of the field
+ contents on the same line as the field name is empty. The
+ remainder of the field is one line per file, each line
+ being indented by one space and containing a number of
+ sub-fields separated by spaces.
+ </p>
+
+ <p>
+ In the <file>.dsc</file> 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<footnote>
+ That is, the parts which are not the <tt>.dsc</tt>.
+ </footnote>.
+ The exact forms of the filenames are described
+ in <ref id="pkg-sourcearchives">.
+ </p>
+
+ <p>
+ In the <file>.changes</file> file this contains one line per
+ file being uploaded. Each line contains the MD5 checksum,
+ size, section and priority and the filename.
+ The <qref id="f-Section">section</qref>
+ and <qref id="f-Priority">priority</qref>
+ are the values of the corresponding fields in
+ the main source control file. If no section or priority is
+ specified then <tt>-</tt> should be used, though section
+ and priority values must be specified for new packages to
+ be installed properly.
+ </p>
+
+ <p>
+ The special value <tt>byhand</tt> for the section in a
+ <tt>.changes</tt> file indicates that the file in question
+ is not an ordinary package file and must by installed by
+ hand by the distribution maintainers. If the section is
+ <tt>byhand</tt> the priority should be <tt>-</tt>.
+ </p>
+
+ <p>
+ If a new Debian revision of a package is being shipped and
+ no new original source archive is being distributed the
+ <tt>.dsc</tt> must still contain the <tt>Files</tt> field
+ entry for the original source archive
+ <file><var>package</var>-<var>upstream-version</var>.orig.tar.gz</file>,
+ but the <file>.changes</file> 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
+ <file>.dsc</file> file and diff which are being uploaded.</p>
+ </sect1>
+
+ <sect1 id="f-Closes">
+ <heading><tt>Closes</tt></heading>
+
+ <p>
+ A space-separated list of bug report numbers that the upload
+ governed by the .changes file closes.
+ </p>
+ </sect1>
+
+ <sect1 id="f-Homepage">
+ <heading><tt>Homepage</tt></heading>
+
+ <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
+ <tt><></tt>.
+ </p>
+ </sect1>
+
+ </sect>
+
+ <sect>
+ <heading>User-defined fields</heading>
+
+ <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
+ source package 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 <tt>X</tt>, followed by one or more of
+ the letters <tt>BCS</tt> and a hyphen <tt>-</tt>, 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 <tt>B</tt> is used the field
+ will appear in binary package control files, where the
+ letter <tt>S</tt> is used in source package control
+ files and where <tt>C</tt> is used in upload control
+ (<tt>.changes</tt>) files.
+ </p>
+
+ <p>
+ For example, if the main source information control file
+ contains the field
+ <example>
+ XBS-Comment: I stand between the candle and the star.
+ </example>
+ then the binary and source package control files will contain the
+ field
+ <example>
+ Comment: I stand between the candle and the star.
+ </example>
+ </p>
+
+ </sect>
+