- <p>
- This target is optional, but providing it if
- possible is a good idea.
- </p>
- </item>
- </taglist>
-
- <p>
- The <tt>build</tt>, <tt>binary</tt> and
- <tt>clean</tt> targets must be invoked with a current
- directory of the package's top-level directory.
- </p>
-
-
- <p>
- Additional targets may exist in <file>debian/rules</file>,
- either as published or undocumented interfaces or for the
- package's internal use.
- </p>
-
- <p>
- The architecture we build on and build for is determined by make
- variables via dpkg-architecture (see <ref id="pkg-dpkgarch">). You can
- get the Debian architecture and the GNU style architecture
- specification string for the build machine as well as the host
- machine. Here is a list of supported make variables:
- <list compact="compact">
- <item>
- <p><tt>DEB_*_ARCH</tt> (the Debian architecture)</p>
- </item>
- <item>
- <p><tt>DEB_*_GNU_TYPE</tt> (the GNU style architecture
- specification string)</p>
- </item>
- <item>
- <p><tt>DEB_*_GNU_CPU</tt> (the CPU part of DEB_*_GNU_TYPE)</p>
- </item>
- <item>
- <p><tt>DEB_*_GNU_SYSTEM</tt> (the System part of
- DEB_*_GNU_TYPE)</p>
- </list>
- </p>
-
- <p>
- where <tt>*</tt> is either <tt>BUILD</tt> for specification of
- the build machine or <tt>HOST</tt> for specification of the machine
- we build for.
- </p>
-
- <p>
- Backward compatibility can be provided in the rules file
- by setting the needed variables to suitable default
- values, please refer to the documentation of
- dpkg-architecture for details.
- </p>
-
- <p>
- It is important to understand that the <tt>DEB_*_ARCH</tt>
- string does only determine which Debian architecture we
- build on resp. for. It should not be used to get the CPU
- or System information, the GNU style variables should be
- used for that.
- </p>
- </sect1>
-
-
- <sect1><heading><file>debian/control</file>
- </heading>
-
- <p>
- This file contains version-independent details about the
- source package and about the binary packages it creates.
- </p>
-
- <p>
- It is a series of sets of control fields, each
- syntactically similar to a binary package control file.
- The sets are separated by one or more blank lines. The
- first set is information about the source package in
- general; each subsequent set describes one binary package
- that the source tree builds.
- </p>
-
- <p>
- The syntax and semantics of the fields are described below
- in <ref id="pkg-controlfields">.
- </p>
-
- <p>
- The general (binary-package-independent) fields are:
- <list compact="compact">
- <item>
- <p><qref id="pkg-f-Source"><tt>Source</tt></qref> (mandatory)</p>
- </item>
- <item>
- <p><qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref></p>
- </item>
- <item>
- <p>
- <qref id="pkg-f-classification"><tt>Section</tt> and
- <tt>Priority</tt></qref>
- (classification, mandatory)
- </p>
- </item>
- <item>
- <p>
- <qref id="relationships"><tt>Build-Depends</tt> et
- al.</qref> (source package interrelationships)
- </p>
- </item>
- <item>
- <p>
- <qref id="pkg-f-Standards-Version"><tt>Standards-Version</tt></qref>
- </p>
- </item>
- </list>
-
- <p>
- The per-binary-package fields are:
- <list compact="compact">
- <item>
- <p><qref id="pkg-f-Package"><tt>Package</tt></qref> (mandatory)</p>
- </item>
- <item>
- <p>
- <qref id="pkg-f-Architecture"><tt>Architecture</tt></qref>
- (mandatory)</p>
- </item>
- <item>
- <p><qref id="descriptions"><tt>Description</tt></qref></p>
- </item>
- <item>
- <p>
- <qref id="pkg-f-classification"><tt>Section</tt> and
- <tt>Priority</tt></qref> (classification)</p>
- </item>
- <item>
- <p><qref id="pkg-f-Essential"><tt>Essential</tt></qref></p>
- </item>
- <item>
- <p>
- <qref id="relationships"><tt>Depends</tt> et
- al.</qref> (binary package interrelationships)
- </p>
- </item>
- </list>
-
- <p>
- These fields are used by <prgn>dpkg-gencontrol</prgn> to
- generate control files for binary packages (see below), by
- <prgn>dpkg-genchanges</prgn> to generate the
- <tt>.changes</tt> 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.
- </p>
-
- <p>
- The fields here may contain variable references - their
- values will be substituted by
- <prgn>dpkg-gencontrol</prgn>, <prgn>dpkg-genchanges</prgn>
- or <prgn>dpkg-source</prgn> when they generate output
- control files. See <ref id="pkg-srcsubstvars"> for details.
- </p>
-
- <p> <sect2><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>
- </sect2>
-
- </sect1>
-
- <sect1 id="pkg-dpkgchangelog"><heading><file>debian/changelog</file>
- </heading>
-
- <p>
- This file records the changes to the Debian-specific parts of the
- package
- <footnote>
- Though there is nothing stopping an author who is also
- the Debian maintainer from using it for all their
- changes, it will have to be renamed if the Debian and
- upstream maintainers become different
- people.
- </footnote>.
- </p>
-
- <p>
- It has a special format which allows the package building
- tools to discover which version of the package is being
- built and find out other release-specific information.
- </p>
-
- <p>
- That format is a series of entries like this:
- <example>
- <var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
-
- * <var>change details</var>
- <var>more change details</var>
- * <var>even more change details</var>
-
- -- <var>maintainer name and email address</var> <var>date</var>
- </example>
- </p>
-
- <p>
- <var>package</var> and <var>version</var> are the source
- package name and version number.
- </p>
-
- <p>
- <var>distribution(s)</var> lists the distributions where
- this version should be installed when it is uploaded - it
- is copied to the <tt>Distribution</tt> field in the
- <tt>.changes</tt> file. See <ref id="pkg-f-Distribution">.
- </p>
-
- <p>
- <var>urgency</var> is the value for the <tt>Urgency</tt>
- field in the <file>.changes</file> file for the upload. See
- <ref id="pkg-f-Urgency">. It is not possible to specify an
- urgency containing commas; commas are used to separate
- <tt><var>keyword</var>=<var>value</var></tt> settings in
- the <prgn>dpkg</prgn> changelog format (though there is
- currently only one useful <var>keyword</var>,
- <tt>urgency</tt>).
- </p>
-
- <p>
- The change details may in fact be any series of lines
- starting with at least two spaces, but conventionally each
- change starts with an asterisk and a separating space and
- continuation lines are indented so as to bring them in
- line with the start of the text above. Blank lines may be
- used here to separate groups of changes, if desired.
- </p>
-
- <p>
- The maintainer name and email address should <em>not</em>
- necessarily be those of the usual package maintainer.
- They should be the details of the person doing
- <em>this</em> version. The information here will be
- copied to the <file>.changes</file> file, and then later used
- to send an acknowledgement when the upload has been
- installed.
- </p>
-
- <p>
- The <var>date</var> should be in RFC822 format
- <footnote>
- This is generated by the <prgn>822-date</prgn>
- program.
- </footnote>; it should include the timezone specified
- numerically, with the timezone name or abbreviation
- optionally present as a comment.
- </p>
-
- <p>
- The first "title" line with the package name should start
- at the left hand margin; the "trailer" line with the
- maintainer and date details should be preceded by exactly
- one space. The maintainer details and the date must be
- separated by exactly two spaces.
- </p>
-
- <p>
- An Emacs mode for editing this format is available: it is
- called <tt>debian-changelog-mode</tt>. You can have this
- mode selected automatically when you edit a Debian
- changelog by adding a local variables clause to the end of
- the changelog.
- </p>
-
- <sect2><heading>Defining alternative changelog formats
- </heading>
-
- <p>
- It is possible to use a different format to the standard
- one, by providing a parser for the format you wish to
- use.
- </p>
-
- <p>
- In order to have <tt>dpkg-parsechangelog</tt> run your
- parser, you must include a line within the last 40 lines
- of your file matching the Perl regular expression:
- <tt>\schangelog-format:\s+([0-9a-z]+)\W</tt> The part in
- parentheses should be the name of the format. For
- example, you might say:
- <example>
- @@@ changelog-format: joebloggs @@@
- </example>
- Changelog format names are non-empty strings of alphanumerics.
- </p>
-
- <p>
- If such a line exists then <tt>dpkg-parsechangelog</tt>
- will look for the parser as
- <file>/usr/lib/dpkg/parsechangelog/<var>format-name</var></file>
- or
- <file>/usr/local/lib/dpkg/parsechangelog/<var>format-name</var></file>;
- it is an error for it not to find it, or for it not to
- be an executable program. The default changelog format
- is <tt>dpkg</tt>, and a parser for it is provided with
- the <tt>dpkg</tt> package.
- </p>
-
- <p>
- The parser will be invoked with the changelog open on
- standard input at the start of the file. It should read
- the file (it may seek if it wishes) to determine the
- information required and return the parsed information
- to standard output in the form of a series of control
- fields in the standard format. By default it should
- return information about only the most recent version in
- the changelog; it should accept a
- <tt>-v<var>version</var></tt> option to return changes
- information from all versions present <em>strictly
- after</em> <var>version</var>, and it should then be an
- error for <var>version</var> not to be present in the
- changelog.
- </p>
-
- <p>
- The fields are:
- <list compact="compact">
- <item>
- <p><qref id="pkg-f-Source"><tt>Source</tt></qref></p>
- </item>
- <item>
- <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
- </item>
- <item>
- <p>
- <qref id="pkg-f-Distribution"><tt>Distribution</tt></qref>
- (mandatory)
- </p>
- </item>
- <item>
- <p><qref id="pkg-f-Urgency"><tt>Urgency</tt></qref> (mandatory)</p>
- </item>
- <item>
- <p>
- <qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref>
- (mandatory)
- </p>
- </item>
- <item>
- <p><qref id="pkg-f-Date"><tt>Date</tt></qref></p>
- </item>
- <item>
- <p>
- <qref id="pkg-f-Changes"><tt>Changes</tt></qref>
- (mandatory)
- </p>
- </item>
- </list>
-
- <p>
- If several versions are being returned (due to the use
- of <tt>-v</tt>), the urgency value should be of the
- highest urgency code listed at the start of any of the
- versions requested followed by the concatenated
- (space-separated) comments from all the versions
- requested; the maintainer, version, distribution and
- date should always be from the most recent version.
- </p>
-
- <p>
- For the format of the <tt>Changes</tt> field see <ref
- id="pkg-f-Changes">.
- </p>
-
- <p>
- If the changelog format which is being parsed always or
- almost always leaves a blank line between individual
- change notes these blank lines should be stripped out,
- so as to make the resulting output compact.
- </p>
-
- <p>
- If the changelog format does not contain date or package
- name information this information should be omitted from
- the output. The parser should not attempt to synthesise
- it or find it from other sources.
- </p>
-
- <p>
- If the changelog does not have the expected format the
- parser should exit with a nonzero exit status, rather
- than trying to muddle through and possibly generating
- incorrect output.
- </p>
-
- <p>
- A changelog parser may not interact with the user at
- all.</p></sect2>
- </sect1>
-
-<!-- FIXME: section pkg-srcsubstvars is the same as srcsubstvars -->
-
- <sect1 id="pkg-srcsubstvars"><heading><file>debian/substvars</file>
- and variable substitutions
- </heading>
-
- <p>
- When <prgn>dpkg-gencontrol</prgn>,
- <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
- generate control files they do variable substitutions on
- their output just before writing it. Variable
- substitutions have the form
- <tt>${<var>variable-name</var>}</tt>. The optional file
- <file>debian/substvars</file> contains variable substitutions
- to be used; variables can also be set directly from
- <file>debian/rules</file> using the <tt>-V</tt> option to the
- source packaging commands, and certain predefined
- variables are available.
- </p>
-
- <p>
- This file is usually generated and modified dynamically by
- <file>debian/rules</file> targets, in which case it must be
- removed by the <tt>clean</tt> target.
- </p>
-
- <p>
- See <manref name="dpkg-source" section="1"> for full
- details about source variable substitutions, including the
- format of <file>debian/substvars</file>.</p>
- </sect1>
-
- <sect1><heading><file>debian/files</file>
- </heading>
-
- <p>
- This file is not a permanent part of the source tree; it
- is used while building packages to record which files are
- being generated. <prgn>dpkg-genchanges</prgn> uses it
- when it generates a <file>.changes</file> file.
- </p>
-
- <p>
- It should not exist in a shipped source package, and so it
- (and any backup files or temporary files such as
- <file>files.new</file>
- <footnote>
- <file>files.new</file> is used as a temporary file by
- <prgn>dpkg-gencontrol</prgn> and
- <prgn>dpkg-distaddfile</prgn> - they write a new
- version of <file>files</file> here before renaming it,
- to avoid leaving a corrupted copy if an error
- occurs
- </footnote>) should be removed by the
- <tt>clean</tt> target. It may also be wise to
- ensure a fresh start by emptying or removing it at the
- start of the <tt>binary</tt> target.
- </p>
-
- <p>
- <prgn>dpkg-gencontrol</prgn> adds an entry to this file
- for the <file>.deb</file> file that will be created by
- <prgn>dpkg-deb</prgn> from the control file that it
- generates, so for most packages all that needs to be done
- with this file is to delete it in <tt>clean</tt>.
- </p>
-
- <p>
- If a package upload includes files besides the source
- package and any binary packages whose control files were
- made with <prgn>dpkg-gencontrol</prgn> then they should be
- placed in the parent of the package's top-level directory
- and <prgn>dpkg-distaddfile</prgn> should be called to add
- the file to the list in <file>debian/files</file>.</p>
- </sect1>
-
- <sect1><heading><file>debian/tmp</file>
- </heading>
-
- <p>
- This is the canonical temporary location for the
- construction of binary packages by the <tt>binary</tt>
- target. The directory <file>tmp</file> serves as the root of
- the filesystem tree as it is being constructed (for
- example, by using the package's upstream makefiles install
- targets and redirecting the output there), and it also
- contains the <tt>DEBIAN</tt> subdirectory. See <ref
- id="pkg-bincreating">.
- </p>
-
- <p>
- If several binary packages are generated from the same
- source tree it is usual to use several
- <file>debian/tmp<var>something</var></file> directories, for
- example <file>tmp-a</file> or <file>tmp-doc</file>.
- </p>
-
- <p>
- Whatever <file>tmp</file> directories are created and used by
- <tt>binary</tt> must of course be removed by the
- <tt>clean</tt> target.</p></sect1>
- </sect>
-
-
- <sect id="pkg-sourcearchives"><heading>Source packages as archives
- </heading>
-
- <p>
- As it exists on the FTP site, a Debian source package
- consists of three related files. You must have the right
- versions of all three to be able to use them.
- </p>
-
- <p>
- <taglist>
- <tag>Debian source control file - <tt>.dsc</tt></tag>
- <item>
-
- <p>
- This file contains a series of fields, identified and
- separated just like the fields in the control file of
- a binary package. The fields are listed below; their
- syntax is described above, in <ref id="pkg-controlfields">.
- <list compact="compact">
- <item>
- <p><qref id="pkg-f-Source"><tt>Source</tt></qref></p>
- </item>
- <item>
- <p><qref id="versions"><tt>Version</tt></qref></p>
- </item>
- <item>
- <p><qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref></p>
- </item>
- <item>
- <p><qref id="pkg-f-Binary"><tt>Binary</tt></qref></p>
- </item>
- <item>
- <p><qref id="pkg-f-Architecture"><tt>Architecture</tt></qref></p>
- </item>
- <item>
- <p>
- <qref id="relationships"><tt>Build-Depends</tt> et
- al.</qref> (source package interrelationships)
- </p>
- </item>
- <item>
- <p>
- <qref id="pkg-f-Standards-Version"><tt>Standards-Version</tt></qref></p>
- </item>
- <item>
- <p><qref id="pkg-f-Files"><tt>Files</tt></qref></p>
- </item>
- </list>
-
- <p>
- The source package control file is generated by
- <prgn>dpkg-source</prgn> 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, as described below.</p>
- </item>
-
- <tag>
- Original source archive -
- <file>
- <var>package</var>_<var>upstream-version</var>.orig.tar.gz
- </file>
- </tag>
-
- <item>
-
- <p>
- This is a compressed (with <tt>gzip -9</tt>)
- <prgn>tar</prgn> file containing the source code from
- the upstream authors of the program. The tarfile
- unpacks into a directory
- <file><var>package</var>-<var>upstream-version</var>.orig</file>,
- and does not contain files anywhere other than in
- there or in its subdirectories.</p>
- </item>
-
- <tag>
- Debianisation diff -
- <file>
- <var>package</var>_<var>upstream_version-revision</var>.diff.gz
- </file>
- </tag>
- <item>
-
- <p>
- This is a unified context diff (<tt>diff -u</tt>)
- giving the changes which are required to turn the
- original source into the Debian source. These changes
- may only include editing and creating plain files.
- The permissions of files, the targets of symbolic
- links and the characteristics of special files or
- pipes may not be changed and no files may be removed
- or renamed.
- </p>
-
- <p>
- All the directories in the diff must exist, except the
- <file>debian</file> subdirectory of the top of the source
- tree, which will be created by
- <prgn>dpkg-source</prgn> if necessary when unpacking.
- </p>
-
- <p>
- The <prgn>dpkg-source</prgn> program will
- automatically make the <file>debian/rules</file> file
- executable (see below).</p></item>
- </taglist>
-
-
- <p>
- If there is no original source code - for example, if the
- package is specially prepared for Debian or the Debian
- maintainer is the same as the upstream maintainer - the
- format is slightly different: then there is no diff, and the
- tarfile is named
- <file><var>package</var>_<var>version</var>.tar.gz</file> and
- contains a directory
- <file><var>package</var>-<var>version</var></file>.
- </p>
- </sect>
-
- <sect><heading>Unpacking a Debian source package without
- <prgn>dpkg-source</prgn>
- </heading>
-
- <p>
- <tt>dpkg-source -x</tt> is the recommended way to unpack a
- Debian source package. However, if it is not available it
- is possible to unpack a Debian source archive as follows:
- <enumlist compact="compact">
- <item>
- <p>
- Untar the tarfile, which will create a <file>.orig</file>
- directory.</p>
- </item>
- <item>
- <p>Rename the <file>.orig</file> directory to
- <file><var>package</var>-<var>version</var></file>.</p>
- </item>
- <item>
- <p>
- Create the subdirectory <file>debian</file> at the top of
- the source tree.</p>
- </item>
- <item><p>Apply the diff using <tt>patch -p0</tt>.</p>
- </item>
- <item><p>Untar the tarfile again if you want a copy of the original
- source code alongside the Debianised version.</p>
- </item>
- </enumlist>
-
- <p>
- It is not possible to generate a valid Debian source archive
- without using <prgn>dpkg-source</prgn>. In particular,
- attempting to use <prgn>diff</prgn> directly to generate the
- <file>.diff.gz</file> file will not work.
- </p>
-
- <sect1><heading>Restrictions on objects in source packages
- </heading>
-
- <p>
- The source package may not contain any hard links
- <footnote>
- This is not currently detected when building source
- packages, but only when extracting
- them.
- </footnote>
- <footnote>
- Hard links may be permitted at some point in the
- future, but would require a fair amount of
- work.
- </footnote>, device special files, sockets or setuid or
- setgid files.
- <footnote>
- Setgid directories are allowed.
- </footnote>
- </p>
-
- <p>
- The source packaging tools manage the changes between the
- original and Debianised source using <prgn>diff</prgn> and
- <prgn>patch</prgn>. Turning the original source tree as
- included in the <file>.orig.tar.gz</file> into the debianised
- source must not involve any changes which cannot be
- handled by these tools. Problematic changes which cause
- <prgn>dpkg-source</prgn> to halt with an error when
- building the source package are:
- <list compact="compact">
- <item><p>Adding or removing symbolic links, sockets or pipes.</p>
- </item>
- <item><p>Changing the targets of symbolic links.</p>
- </item>
- <item><p>Creating directories, other than <file>debian</file>.</p>
- </item>
- <item><p>Changes to the contents of binary files.</p></item>
- </list> Changes which cause <prgn>dpkg-source</prgn> to
- print a warning but continue anyway are:
- <list compact="compact">
- <item>
- <p>
- Removing files, directories or symlinks.
- <footnote>
- Renaming a file is not treated specially - it is
- seen as the removal of the old file (which
- generates a warning, but is otherwise ignored),
- and the creation of the new one.
- </footnote>
- </p>
- </item>
- <item>
- <p>
- Changed text files which are missing the usual final
- newline (either in the original or the modified
- source tree).
- </p>
- </item>
- </list>
- Changes which are not represented, but which are not detected by
- <prgn>dpkg-source</prgn>, are:
- <list compact="compact">
- <item><p>Changing the permissions of files (other than
- <file>debian/rules</file>) and directories.</p></item>
- </list>
- </p>
-
- <p>
- The <file>debian</file> directory and <file>debian/rules</file>
- are handled specially by <prgn>dpkg-source</prgn> - before
- applying the changes it will create the <file>debian</file>
- directory, and afterwards it will make
- <file>debian/rules</file> world-exectuable.
- </p>
- </sect1>
- </sect>
- </appendix>
-
- <appendix id="pkg-controlfields"><heading>Control files and their
- fields (from old Packaging Manual)
- </heading>
-
- <p>
- Many of the tools in the <prgn>dpkg</prgn> suite manipulate
- data in a common format, known as control files. Binary and
- source packages have control data as do the <file>.changes</file>
- files which control the installation of uploaded files, and
- <prgn>dpkg</prgn>'s internal databases are in a similar
- format.
- </p>
-
- <sect><heading>Syntax of control files
- </heading>
-
- <p>
- A file consists of one or more paragraphs of fields. The
- paragraphs are separated by blank lines. Some control files
- only allow one paragraph; others allow several, in which
- case each paragraph often refers to a different package.
- </p>
-
- <p>
- Each paragraph is a series of fields and values; each field
- consists of a name, followed by a colon and the value. It
- ends at the end of the line. Horizontal whitespace (spaces
- and tabs) may occur before or after the value and is ignored
- there; it is conventional to put a single space after the
- colon.
- </p>
-
- <p>
- Some fields' values may span several lines; in this case
- each continuation line <em>must</em> start with a space or
- tab. Any trailing spaces or tabs at the end of individual
- lines of a field value are ignored.
- </p>
-
- <p>
- Except where otherwise stated only a single line of data is
- allowed and whitespace is not significant in a field body.
- Whitespace may never appear inside names (of packages,
- architectures, files or anything else), version numbers or
- in between the characters of multi-character version
- relationships.
- </p>
-
- <p>
- Field names are not case-sensitive, but it is usual to
- capitalise 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.
- </p>
-
- <p>
- It is important to note that there are several fields which
- are optional as far as <prgn>dpkg</prgn> and the related
- tools are concerned, but which must appear in every Debian
- package, or whose omission may cause problems.
- </p>
- </sect>
-
- <sect><heading>List of fields
- </heading>
-
- <sect1 id="pkg-f-Package"><heading><tt>Package</tt>
- </heading>
-
- <p>
- The name of the binary package. Package names consist of
- the alphanumerics and <tt>+</tt> <tt>-</tt> <tt>.</tt>
- (plus, minus and full stop).
- <footnote>
- The characters <tt>@</tt> <tt>:</tt> <tt>=</tt>
- <tt>%</tt> <tt>_</tt> (at, colon, equals, percent
- and underscore) used to be legal and are still
- accepted when found in a package file, but may not be
- used in new packages.
- </footnote>
- </p>
-
- <p>
- They must be at least two characters and must start with
- an alphanumeric. In current versions of dpkg they are
- sort of case-sensitive<footnote>
- This is a bug.
- </footnote>; use lowercase package names unless
- the package you're building (or referring to, in other
- fields) is already using uppercase.
- </p>
- </sect1>
-
- <sect1 id="pkg-f-Version"><heading><tt>Version</tt>
- </heading>
-
- <p>
- This lists the source or binary package's version number -
- see <ref id="versions">.
- </p>
-
- </sect1>
-
- <sect1 id="pkg-f-Architecture"><heading><tt>Architecture</tt>
- </heading>
-
- <p>
- This is the architecture string; it is a single word for
- the Debian architecture.
- </p>
-
- <p>
- <prgn>dpkg</prgn> will check the declared architecture of
- a binary package against its own compiled-in value before
- it installs it.
- </p>
-
- <p>
- The special value <tt>all</tt> indicates that the package
- is architecture-independent.
- </p>
-
- <p>
- In the main <file>debian/control</file> file in the source
- package, or in the source package control file
- <file>.dsc</file>, a list of architectures (separated by
- spaces) is also allowed, as is the special value
- <tt>any</tt>. A list indicates that the source will build
- an architecture-dependent package, and will only work
- correctly on the listed architectures. <tt>any</tt>
- indicates that though the source package isn't dependent
- on any particular architecture and should compile fine on
- any one, the binary package(s) produced are not
- architecture-independent but will instead be specific to
- whatever the current build architecture is.
- </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 being uploaded too the special
- entry <tt>source</tt> is also present.
- </p>
-
- <p>
- See <ref id="pkg-debianrules"> for information how to get the
- architecture for the build process.
- </p>
- </sect1>
-
- <sect1 id="pkg-f-Maintainer"><heading><tt>Maintainer</tt>
- </heading>
-
- <p>
- The package maintainer's name and email address. The name
- should come first, then the email address inside angle
- brackets <tt><></tt> (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>
- In a <file>.changes</file> file or parsed changelog data this
- contains the name and email address of the person
- responsible for the particular version in question - this
- may not be the package's usual maintainer.
- </p>
-
- <p>
- This field is usually optional in as far as the
- <prgn>dpkg</prgn> are concerned, but its absence when
- building packages usually generates a warning.</p>
- </sect1>
-
- <sect1 id="pkg-f-Source"><heading><tt>Source</tt>
- </heading>
-
- <p>
- This field identifies the source package name.
- </p>
-
- <p>
- In a main source control information or a
- <file>.changes</file> or <file>.dsc</file> file or parsed
- changelog data this may contain only the name of the
- source package.
- </p>
-
- <p>
- In the control file of a binary package (or in a
- <file>Packages</file> file) it may be followed by a version
- number in parentheses.
- <footnote>
- It is usual to leave a space after the package name if
- a version number is specified.
- </footnote> This version number may be omitted (and is, by
- <prgn>dpkg-gencontrol</prgn>) if it has the same value as
- the <tt>Version</tt> 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>
- </sect1>
-
- <sect1><heading>Package interrelationship fields:
- <tt>Depends</tt>, <tt>Pre-Depends</tt>,
- <tt>Recommends</tt> <tt>Suggests</tt>, <tt>Conflicts</tt>,
- <tt>Provides</tt>, <tt>Replaces</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="pkg-f-Description"><heading><tt>Description</tt>
- </heading>
-
- <p>
- In a binary package <tt>Packages</tt> file or main source
- control file this field contains a description of the
- binary package, in a special format. See <ref
- id="descriptions"> for details.
- </p>
-
- <p>
- In a <file>.changes</file> file it contains a summary of the
- descriptions for the packages being uploaded. 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="pkg-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 the
- <file>Packages</file> file) or in a per-package fields
- paragraph of a main source control data file.
- </p>
-
- <p>
- If set to <tt>yes</tt> then <prgn>dpkg</prgn> and
- <prgn>dselect</prgn> will refuse to remove the package
- (though it can be upgraded and/or replaced). The other
- possible value is <tt>no</tt>, which is the same as not
- having the field at all.</p>
- </sect1>
-
- <sect1 id="pkg-f-classification"><heading><tt>Section</tt> and
- <tt>Priority</tt>
- </heading>
-
- <p>
- These two fields classify the package. The
- <tt>Priority</tt> represents how important that it is that
- the user have it installed; the <tt>Section</tt>
- represents an application area into which the package has
- been classified.
- </p>
-
- <p>
- When they appear in the <file>debian/control</file> file these
- fields give values for the section and priority subfields
- of the <tt>Files</tt> field of the <file>.changes</file> file,
- and give defaults for the section and priority of the
- binary packages.
- </p>
-
- <p>
- The section and priority are represented, though not as
- separate fields, in the information for each file in the
- <qref id="pkg-f-Files"><tt>-File</tt></qref>field of a
- <file>.changes</file> file. The section value in a
- <file>.changes</file> file is used to decide where to install
- a package in the FTP archive.
- </p>
-
- <p>
- These fields are not used by by <prgn>dpkg</prgn> proper,
- but by <prgn>dselect</prgn> when it sorts packages and
- selects defaults.
- </p>
-
- <p>
- These fields can appear in binary package control files,
- in which case they provide a default value in case the
- <file>Packages</file> files are missing the information.
- <prgn>dpkg</prgn> and <prgn>dselect</prgn> will only use
- the value from a <file>.deb</file> file if they have no other
- information; a value listed in a <file>Packages</file> file
- will always take precedence. By default
- <prgn>dpkg-gencontrol</prgn> does not include the section
- and priority in the control file of a binary package - use
- the <tt>-isp</tt>, <tt>-is</tt> or <tt>-ip</tt> options to
- achieve this effect.</p>
- </sect1>
-
- <sect1 id="pkg-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="pkg-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="pkg-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> (Debian source control) file each
- line contains the MD5 checksum, size and filename of the
- tarfile 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 section
- and priority are the values of the corresponding fields in
- the main source control file - see <ref
- id="pkg-f-classification">. 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="pkg-f-Standards-Version"><heading><tt>Standards-Version</tt>
- </heading>