Copyright © 1996,1997,1998 Ian Jackson
and Christian Schwarz.
</copyrightsummary>
+ <p>
+ These are the copyright dates of the original Policy manual.
+ Since then, this manual has been updated by many others. No
+ comprehensive collection of copyright notices for subsequent
+ work exists.
+ </p>
+
<p>
This manual is free software; you may redistribute it and/or
modify it under the terms of the GNU General Public License
is used by, a significant number of packages, and
therefore should not be changed without peer
review. Package maintainers can then rely on this
- interfaces not changing, and the package
- management software authors need to ensure
- compatibility with these interface
- definitions. (Control file and changelog file
- formats are examples.)
+ interface not changing, and the package management
+ software authors need to ensure compatibility with
+ this interface definition. (Control file and
+ changelog file formats are examples.)
</item>
<tag>Chosen Convention</tag>
<item>
The Debian Free Software Guidelines (DFSG) form our
definition of "free software". These are:
<taglist>
- <tag>Free Redistribution
+ <tag>1. Free Redistribution
</tag>
<item>
The license of a Debian component may not restrict any
sources. The license may not require a royalty or
other fee for such sale.
</item>
- <tag>Source Code
+ <tag>2. Source Code
</tag>
<item>
The program must include source code, and must allow
distribution in source code as well as compiled form.
</item>
- <tag>Derived Works
+ <tag>3. Derived Works
</tag>
<item>
The license must allow modifications and derived
works, and must allow them to be distributed under the
same terms as the license of the original software.
</item>
- <tag>Integrity of The Author's Source Code
+ <tag>4. Integrity of The Author's Source Code
</tag>
<item>
The license may restrict source-code from being
Project encourages all authors to not restrict any
files, source or binary, from being modified.)
</item>
- <tag>No Discrimination Against Persons or Groups
+ <tag>5. No Discrimination Against Persons or Groups
</tag>
<item>
The license must not discriminate against any person
or group of persons.
</item>
- <tag>No Discrimination Against Fields of Endeavor
+ <tag>6. No Discrimination Against Fields of Endeavor
</tag>
<item>
The license must not restrict anyone from making use
used in a business, or from being used for genetic
research.
</item>
- <tag>Distribution of License
+ <tag>7. Distribution of License
</tag>
<item>
The rights attached to the program must apply to all
for execution of an additional license by those
parties.
</item>
- <tag>License Must Not Be Specific to Debian
+ <tag>8. License Must Not Be Specific to Debian
</tag>
<item>
The rights attached to the program must not depend on
rights as those that are granted in conjunction with
the Debian system.
</item>
- <tag>License Must Not Contaminate Other Software
+ <tag>9. License Must Not Contaminate Other Software
</tag>
<item>
The license must not place restrictions on other
that all other programs distributed on the same medium
must be free software.
</item>
- <tag>Example Licenses
+ <tag>10. Example Licenses
</tag>
<item>
The "GPL," "BSD," and "Artistic" licenses are examples of
<heading>Copyright considerations</heading>
<p>
- Every package must be accompanied by a verbatim copy of
- its copyright and distribution license in the file
+ Every package must be accompanied by a verbatim copy of its
+ copyright information and distribution license in the file
<file>/usr/share/doc/<var>package</var>/copyright</file>
(see <ref id="copyrightfile"> for further details).
</p>
<em>ruby</em>, <em>science</em>, <em>shells</em>, <em>sound</em>,
<em>tex</em>, <em>text</em>, <em>utils</em>, <em>vcs</em>,
<em>video</em>, <em>web</em>, <em>x11</em>, <em>xfce</em>,
- <em>zope</em>.
+ <em>zope</em>. The additional section <em>debian-installer</em>
+ contains special packages used by the installer and is not used
+ for normal Debian packages.
+ </p>
+
+ <p>
+ For more information about the sections and their definitions,
+ see the <url id="http://packages.debian.org/unstable/"
+ name="list of sections in unstable">.
</p>
</sect>
</p>
<p>
- The <var>date</var> must be in RFC822 format<footnote>
+ The <var>date</var> has the following format<footnote>
This is generated by <tt>date -R</tt>.
- </footnote>; it must include the time zone specified
- numerically, with the time zone name or abbreviation
- optionally present as a comment in parentheses.
+ </footnote> (compatible and with the same semantics of
+ RFC 2822 and RFC 5322):
+ <example>day-of-week, dd month yyyy hh:mm:ss +zzzz</example>
+ where:
+ <list compact="compact">
+ <item>day-of week is one of: Mon, Tue, Wed, Thu, Fri, Sat, Sun</item>
+ <item>dd is a one- or two-digit day of the month (01-31)</item>
+ <item>month is one of: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec</item>
+ <item>yyyy is the four-digit year (e.g. 2010)</item>
+ <item>hh is the two-digit hour (00-23</item>
+ <item>mm is the two-digit minutes (00-59)</item>
+ <item>ss is the two-digit seconds (00-60)</item>
+ <item>
+ +zzzz or -zzzz is the the time zone offset from Coordinated Universal
+ Time (UTC). "+" indicates that the time is ahead of (i.e., east of) UTC
+ and "-" indicates that the time is behind (i.e., west of) UTC. The
+ first two digits indicate the hour difference from UTC and the last
+ two digits indicate the number of additional minutes difference from
+ UTC. The last two digits must be in the range 00-59.
+ </item>
+ </list>
</p>
<p>
<sect id="dpkgcopyright">
<heading>Copyright: <file>debian/copyright</file></heading>
<p>
- Every package must be accompanied by a verbatim copy of
- its copyright and distribution license in the file
+ Every package must be accompanied by a verbatim copy of its
+ copyright information and distribution license in the file
<file>/usr/share/doc/<var>package</var>/copyright</file>
(see <ref id="copyrightfile"> for further details). Also see
- <ref id="pkgcopyright"> for further considerations relayed
+ <ref id="pkgcopyright"> for further considerations related
to copyrights for packages.
</p>
</sect>
<p>
It must start with the line <tt>#!/usr/bin/make -f</tt>,
so that it can be invoked by saying its name rather than
- invoking <prgn>make</prgn> explicitly.
+ invoking <prgn>make</prgn> explicitly. That is, invoking
+ either of <tt>make -f debian/rules <em>args...</em></tt>
+ or <tt>./debian/rules <em>args...</em></tt> must result in
+ identical behavior.
</p>
<p>
Since an interactive <file>debian/rules</file> script makes it
impossible to auto-compile that package and also makes it
hard for other people to reproduce the same binary
- package, all <em>required targets</em> MUST be
+ package, all <em>required targets</em> must be
non-interactive. At a minimum, required targets are the
ones called by <prgn>dpkg-buildpackage</prgn>, namely,
<em>clean</em>, <em>binary</em>, <em>binary-arch</em>,
<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>
</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.
+ Package names (both source and binary,
+ see <ref id="f-Package">) 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>
<heading><tt>Priority</tt></heading>
<p>
- This field represents how important that it is that the user
+ This field represents how important it is that the user
have the package installed. See <ref id="priorities">.
</p>
</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.
+ Binary package names must follow the same syntax and
+ restrictions as source package names. See <ref id="f-Source">
+ for the details.
</p>
</sect1>
<tt>Architecture</tt> field can include the following sets of
values:
<list>
- <item>A unique single word identifying a Debian machine
- architecture as described in <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.
+ <item>
+ A unique single word identifying a Debian machine
+ architecture as described in <ref id="arch-spec">.
+ </item>
+ <item>
+ An architecture wildcard identifying a set of Debian
+ machine architectures, see <ref id="arch-wildcard-spec">.
+ <tt>any</tt> matches all Debian machine architectures
+ and is the most frequently used.
+ </item>
+ <item>
+ <tt>all</tt>, which indicates an
+ architecture-independent package.
+ </item>
+ <item>
+ <tt>source</tt>, which indicates a source package.
+ </item>
</list>
</p>
<p>
In the main <file>debian/control</file> file in the source
- package, this field may contain the special value
- <tt>any</tt>, the special value <tt>all</tt>, or a list of
- architectures separated by spaces. If <tt>any</tt> or
- <tt>all</tt> appear, they must be the entire contents of the
- field. Most packages will use either <tt>any</tt> or
- <tt>all</tt>. Specifying a specific list of architectures is
- for the minority of cases where a program is not portable or
- is not useful on some architectures, and where possible the
- program should be made portable instead.
+ package, this field may contain the special
+ value <tt>all</tt>, the special architecture
+ wildcard <tt>any</tt>, or a list of specific and wildcard
+ architectures separated by spaces. If <tt>all</tt>
+ or <tt>any</tt> appears, that value must be the entire
+ contents of the field. Most packages will use
+ either <tt>all</tt> or <tt>any</tt>.
+ </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 <tt>any</tt> 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 source package control file <file>.dsc</file>, this
- field may contain either the special value <tt>any</tt> or a
- list of architectures separated by spaces. If a list is given,
- it 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. The
- <tt>Architecture</tt> field in the source package control file
- <file>.dsc</file> is generally constructed from the
- <tt>Architecture</tt> fields in the
- <file>debian/control</file> in the source package.
+ 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
+ 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.
+ The <tt>Architecture</tt> field in the source package control
+ file <file>.dsc</file> is generally constructed from
+ the <tt>Architecture</tt> fields in
+ the <file>debian/control</file> in the source package.
</p>
<p>
</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. If the source
- package also builds at least one architecture-independent
- package, <tt>all</tt> will also be included in the list.
+ 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, <tt>all</tt> will
+ also be included in the list.
</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
+ 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. <tt>all</tt> will be
present if any architecture-independent packages are being
- uploaded. <tt>any</tt> may never occur in the
- <tt>Architecture</tt> field in the <file>.changes</file>
- file.
+ uploaded. Architecture wildcards such as <tt>any</tt> must
+ never occur in the <tt>Architecture</tt> field in
+ the <file>.changes</file> file.
</p>
<p>
- See <ref id="debianrules"> for information how to get the
- architecture for the build process.
+ See <ref id="debianrules"> for information on how to get
+ the architecture for the build process.
</p>
</sect1>
<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>
+ field, and so either these three components or 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
<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).
+ silly orderings.<footnote>
+ 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.
+ </footnote>
</p>
</sect1>
</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.
+ In a <file>.changes</file> file, the <tt>Description</tt>
+ 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
+ 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.
</p>
-
</sect1>
<sect1 id="f-Distribution">
distribution(s) where this version of the package should
be installed. Valid distributions are determined by the
archive maintainers.<footnote>
- Current distribution names are:
+ Example distribution names in the Debian archive used in
+ <file>.changes</file> files 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.
+ 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.
</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.
+ 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.
</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".
+ 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>
</footnote>
+ The Debian archive software only supports listing a single
+ distribution. Migration of packages to other distributions is
+ handled outside of the upload process.
</p>
</sect1>
</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.
+ The first line of the field value (the part on the same line
+ as <tt>Changes:</tt>) 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 (<tt>.</tt>).
</p>
<p>
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).
+ representation of a blank line).
</p>
</sect1>
<heading><tt>Binary</tt></heading>
<p>
- This field is a list of binary packages.
+ This 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 <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.
+ When it appears in the <file>.dsc</file> file, it lists binary
+ 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
+ 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.
+ 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.
</p>
</sect1>
<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.
+ This field appears in the control files of binary packages,
+ and in the <file>Packages</file> 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 represented in kilobytes as a simple
- decimal number.
+ The disk space is given as the integer value of the estimated
+ installed size in bytes, divided by 1024 and rounded up.
</p>
</sect1>
<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.
+ 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 <tt>Files:</tt>)
+ 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 <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>.
+ 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>. For example:
+ <example>
+Files:
+ c6f698f19f2a2aa07dbb9bbda90a2754 571925 example_1.2.orig.tar.gz
+ 938512f08422f3509ff36f125f5873ba 6220 example_1.2-1.diff.gz
+ </example>
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.
+ size, section and priority and the filename. For example:
+ <example>
+Files:
+ 4c31ab7bfc40d3cf49d7811987390357 1428 text extra example_1.2-1.dsc
+ c6f698f19f2a2aa07dbb9bbda90a2754 571925 text extra example_1.2.orig.tar.gz
+ 938512f08422f3509ff36f125f5873ba 6220 text extra example_1.2-1.diff.gz
+ 7c98fe853b3bbb47a00e5cd129b6cb56 703542 text extra example_1.2-1_i386.deb
+ </example>
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.
+ 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>
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>,
+ <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
<heading>Controlling terminal for maintainer scripts</heading>
<p>
- The maintainer scripts are guaranteed to run with a
- controlling terminal and can interact with the user.
- Because these scripts may be executed with standard output
- redirected into a pipe for logging purposes, Perl scripts
- should set unbuffered output by setting <tt>$|=1</tt> so
- that the output is printed immediately rather than being
- buffered.
+ Maintainer scripts are not guaranteed to run with a controlling
+ terminal and may not be able to interact with the user. They
+ must be able to fall back to noninteractive behavior if no
+ controlling terminal is available. Maintainer scripts that
+ prompt via a program conforming to the Debian Configuration
+ Management Specification (see <ref id="maintscriptprompt">) may
+ assume that program will handle falling back to noninteractive
+ behavior.
+ </p>
+
+ <p>
+ For high-priority prompts without a reasonable default answer,
+ maintainer scripts may abort if there is no controlling
+ terminal. However, this situation should be avoided if at all
+ possible, since it prevents automated or unattended installs.
+ In most cases, users will consider this to be a bug in the
+ package.
</p>
</sect>
+
<sect id="exitstatus">
<heading>Exit status</heading>
</example>
If this works, then the old-version is
"Installed", if not, the old version is in a
- "Failed-Config" state.
+ "Half-Configured" state.
</item>
</enumlist>
</item>
If this fails, the package is left in a
"Half-Installed" state, which requires a
reinstall. If it works, the packages is left in
- a "Config Files" state.
+ a "Config-Files" state.
</item>
<item>
Otherwise (i.e., the package was completely purged):
<var>new-postrm</var> abort-install
</example>
If the error-unwind fails, the package is in a
- "Half Installed" phase, and requires a
+ "Half-Installed" phase, and requires a
reinstall. If the error unwind works, the
package is in a not installed state.
</item>
<example compact="compact">
<var>old-preinst</var> abort-upgrade <var>new-version</var>
</example>
- If this fails, the old version is left in an
- "Half Installed" state. If it works, dpkg now
+ If this fails, the old version is left in a
+ "Half-Installed" state. If it works, dpkg now
calls:
<example compact="compact">
<var>new-postrm</var> abort-upgrade <var>old-version</var>
</example>
- If this fails, the old version is left in an
- "Half Installed" state. If it works, dpkg now
+ If this fails, the old version is left in a
+ "Half-Installed" state. If it works, dpkg now
calls:
<example compact="compact">
<var>old-postinst</var> abort-upgrade <var>new-version</var>
</example>
</p>
<p>
- If this fails, the package is in a "Failed-Config"
+ If this fails, the package is in a "Half-Configured"
state, or else it remains "Installed".
</p>
</item>
bar</tt> on all other architectures.
</p>
+ <p>
+ All fields that specify build-time relationships may also be
+ restricted to a certain set of architectures using architecture
+ wildcards. The syntax for declaring such restrictions is the
+ same as declaring restrictions using a certain set of
+ architectures without architecture wildcards. For example:
+ <example compact="compact">
+Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
+ </example>
+ is equivalent to <tt>foo</tt> on architectures using the Linux
+ kernel and any cpu, <tt>bar</tt> on architectures using any
+ kernel and an i386 cpu, and <tt>baz</tt> on any architecture
+ using a kernel other than Linux.
+ </p>
+
<p>
Note that the binary package relationship fields such as
<tt>Depends</tt> appear in one of the binary package
be <em>unpacked</em> the pre-dependency can be
satisfied if the depended-on package is either fully
configured, <em>or even if</em> the depended-on
- package(s) are only unpacked or half-configured,
- provided that they have been configured correctly at
- some point in the past (and not removed or partially
- removed since). In this case, both the
+ package(s) are only unpacked or in the "Half-Configured"
+ state, provided that they have been configured
+ correctly at some point in the past (and not removed
+ or partially removed since). In this case, both the
previously-configured and currently unpacked or
- half-configured versions must satisfy any version
+ "Half-Configured" versions must satisfy any version
clause in the <tt>Pre-Depends</tt> field.
</p>
<p>
A package will not be regarded as causing breakage merely
because its configuration files are still installed; it must
- be at least half-installed.
+ be at least "Half-Installed".
</p>
<p>
<p>
A package will not cause a conflict merely because its
configuration files are still installed; it must be at least
- half-installed.
+ "Half-Installed".
</p>
<p>
</p>
<p>
- If you are creating a udeb for use in the Debian Installer, you
- will need to specify that <prgn>dpkg-shlibdeps</prgn> should use
- the dependency line of type <tt>udeb</tt> by adding
- <tt>-tudeb</tt> as option<footnote>
+ If you are creating a udeb for use in the Debian Installer,
+ you will need to specify that <prgn>dpkg-shlibdeps</prgn>
+ should use the dependency line of type <tt>udeb</tt> by
+ adding the <tt>-tudeb</tt> option<footnote>
<prgn>dh_shlibdeps</prgn> from the <tt>debhelper</tt> suite
will automatically add this option if it knows it is
processing a udeb.
for 64 bit binaries is removed.
</p>
</item>
+ <item>
+ <p>
+ The requirement for object files, internal binaries, and
+ libraries, including <file>libc.so.*</file>, to be located
+ directly under <file>/lib{,32}</file> and
+ <file>/usr/lib{,32}</file> is amended, permitting files
+ to instead be installed to
+ <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
+ 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>.
+ <footnote>
+ This is necessary in order to reserve the directories for
+ use in cross-installation of library packages from other
+ architectures, as part of the planned deployment of
+ <tt>multiarch</tt>.
+ </footnote>
+ </p>
+ <p>
+ Applications may also use a single subdirectory under
+ <file>/usr/lib/<var>triplet</var></file>.
+ </p>
+ <p>
+ The execution time linker/loader, ld*, must still be made
+ available in the existing location under /lib or /lib64
+ since this is part of the ELF ABI for the architecture.
+ </p>
+ </item>
<item>
<p>
The requirement that
symlinked there, is relaxed to a recommendation.
</p>
</item>
+ <item>
+ <p>
+ The following directories in the root filesystem are
+ additionally allowed: <file>/sys</file> and
+ <file>/selinux</file>. <footnote>These directories
+ are used as mount points to mount virtual filesystems
+ to get access to kernel information.</footnote>
+ </p>
+ </item>
</enumlist>
</p>
</p>
<p>
- Note, that this applies only to directories <em>below</em>
- <file>/usr/local</file>, not <em>in</em> <file>/usr/local</file>.
- Packages must not create sub-directories in the directory
- <file>/usr/local</file> itself, except those listed in FHS,
- section 4.5. However, you may create directories below
- them as you wish. You must not remove any of the
- directories listed in 4.5, even if you created them.
+ Note that this applies only to
+ directories <em>below</em> <file>/usr/local</file>,
+ not <em>in</em> <file>/usr/local</file>. Packages must
+ not create sub-directories in the
+ directory <file>/usr/local</file> itself, except those
+ listed in FHS, section 4.5. However, you may create
+ directories below them as you wish. You must not remove
+ any of the directories listed in 4.5, even if you created
+ them.
</p>
<p>
<sect1>
<heading>The system-wide mail directory</heading>
<p>
- The system-wide mail directory is <file>/var/mail</file>. This
- directory is part of the base system and should not owned
- by any particular mail agents. The use of the old
+ The system-wide mail directory
+ is <file>/var/mail</file>. This directory is part of the
+ base system and should not be owned by any particular mail
+ agents. The use of the old
location <file>/var/spool/mail</file> is deprecated, even
though the spool may still be physically located there.
</p>
</p>
</item>
- <tag>1000-29999:</tag>
+ <tag>1000-59999:</tag>
<item>
<p>
Dynamically allocated user accounts. By default
</p>
</item>
- <tag>30000-59999:</tag>
- <item>
- <p>Reserved.</p>
- </item>
-
<tag>60000-64999:</tag>
<item>
<p>
</p>
</sect1>
- <sect1>
+ <sect1 id="writing-init">
<heading>Writing the scripts</heading>
<p>
option.
</p>
+ <p>
+ Be careful of using <tt>set -e</tt> in <file>init.d</file>
+ scripts. Writing correct <file>init.d</file> scripts requires
+ accepting various error exit statuses when daemons are already
+ running or already stopped without aborting
+ the <file>init.d</file> script, and common <file>init.d</file>
+ function libraries are not safe to call with <tt>set -e</tt>
+ in effect<footnote>
+ <tt>/lib/lsb/init-functions</tt>, which assists in writing
+ LSB-compliant init scripts, may fail if <tt>set -e</tt> is
+ in effect and echoing status messages to the console fails,
+ for example.
+ </footnote>. For <tt>init.d</tt> scripts, it's often easier
+ to not use <tt>set -e</tt> and instead check the result of
+ each command separately.
+ </p>
+
<p>
If a service reloads its configuration automatically (as
in the case of <prgn>cron</prgn>, for example), the
</p>
<p>
- Note that the same symbol (<tt>"</tt>) is used for the left
- and right quotation marks. A grave accent (<tt>`</tt>) is
- not a quote character; neither is an apostrophe
- (<tt>'</tt>).
+ Note that the same symbol (<tt>"</tt>) <!-- " --> is used
+ for the left and right quotation marks. A grave accent
+ (<tt>`</tt>) is not a quote character; neither is an
+ apostrophe (<tt>'</tt>).
</p>
</item>
<prgn>anacron</prgn>. Thus, you should only use this
directory for jobs which may be skipped if the system is not
running.)</p>
+ <p>
+ Unlike <file>crontab</file> files described in the IEEE Std
+ 1003.1-2008 (POSIX.1) available from
+ <url id="http://www.opengroup.org/onlinepubs/9699919799/"
+ name="The Open Group">, the files in
+ <file>/etc/cron.d</file> and the file
+ <file>/etc/crontab</file> have seven fields; namely:
+ <enumlist>
+ <item>Minute [0,59]</item>
+ <item>Hour [0,23]</item>
+ <item>Day of the month [1,31]</item>
+ <item>Month of the year [1,12]</item>
+ <item>Day of the week ([0,6] with 0=Sunday)</item>
+ <item>Username</item>
+ <item>Command to be run</item>
+ </enumlist>
+ Ranges of numbers are allowed. Ranges are two numbers
+ separated with a hyphen. The specified range is inclusive.
+ Lists are allowed. A list is a set of numbers (or ranges)
+ separated by commas. Step values can be used in conjunction
+ with ranges.
+ </p>
<p>
- The scripts or crontab entries in these directories should
+ The scripts or <tt>crontab</tt> entries in these directories should
check if all necessary programs are installed before they
try to execute them. Otherwise, problems will arise when a
package was removed but not purged since configuration files
- are kept on the system in this situation.</p>
+ are kept on the system in this situation.
+ </p>
+
+ <p>
+ Any <tt>cron</tt> daemon must provide
+ <file>/usr/bin/crontab</file> and support normal
+ <tt>crontab</tt> entries as specified in POSIX. The daemon
+ must also support names for days and months, ranges, and
+ step values. It has to support <file>/etc/crontab</file>,
+ and correctly execute the scripts in
+ <file>/etc/cron.d</file>. The daemon must also correctly
+ execute scripts in
+ <file>/etc/cron.{hourly,daily,weekly,monthly}</file>.
+ </p>
</sect>
<sect id="menus">
language currently used to implement it.
</p>
<p>
- Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>)
- should almost certainly start with <tt>set -e</tt> so that
- errors are detected. Every script should use
- <tt>set -e</tt> or check the exit status of <em>every</em>
- command.
+ Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>) other than
+ <file>init.d</file> scripts should almost certainly start
+ with <tt>set -e</tt> so that errors are detected.
+ <file>init.d</file> scripts are something of a special case, due
+ to how frequently they need to call commands that are allowed to
+ fail, and it may instead be easier to check the exit status of
+ commands directly. See <ref id="writing-init"> for more
+ information about writing <file>init.d</file> scripts.
+ </p>
+ <p>
+ Every script should use <tt>set -e</tt> or check the exit status
+ of <em>every</em> command.
</p>
-
<p>
Scripts may assume that <file>/bin/sh</file> implements the
SUSv3 Shell Command Language<footnote>
<heading>Device files</heading>
<p>
- Packages must not include device files in the package file
- tree.
+ Packages must not include device files or named pipes in the
+ package file tree.
</p>
<p>
<file>/dev/cu*</file> devices should be changed to use
<file>/dev/ttyS*</file>.
</p>
+
+ <p>
+ Named pipes needed by the package must be created in
+ the <prgn>postinst</prgn> script<footnote>
+ It's better to use <prgn>mkfifo</prgn> rather
+ than <prgn>mknod</prgn> to create named pipes so that
+ automated checks for packages incorrectly creating device
+ files with <prgn>mknod</prgn> won't have false positives.
+ </footnote> and removed in
+ the <prgn>prerm</prgn> or <prgn>postrm</prgn> script as
+ appropriate.
+ </p>
</sect>
<sect id="config-files">
security policy by changing the permissions on a binary:
they can do this by using <prgn>dpkg-statoverride</prgn>, as
described below.<footnote>
- Ordinary files installed by <prgn>dpkg</prgn> (as
- opposed to <tt>conffile</tt>s and other similar objects)
- normally have their permissions reset to the distributed
- permissions when the package is reinstalled. However,
- the use of <prgn>dpkg-statoverride</prgn> overrides this
- default behavior. If you use this method, you should
- remember to describe <prgn>dpkg-statoverride</prgn> in
- the package documentation; being a relatively new
- addition to Debian, it is probably not yet well-known.
+ Ordinary files installed by <prgn>dpkg</prgn> (as
+ opposed to <tt>conffile</tt>s and other similar objects)
+ normally have their permissions reset to the distributed
+ permissions when the package is reinstalled. However,
+ the use of <prgn>dpkg-statoverride</prgn> overrides this
+ default behavior.
</footnote>
Another method you should consider is to create a group for
people allowed to use the program(s) and make any setuid
fi
done
</example>
- The corresponding <tt>dpkg-statoverride --remove</tt>
- calls can then be made unconditionally when the package is
- purged.
+ The corresponding code to remove the override when the package
+ is purged would be:
+ <example>
+for i in /usr/bin/foo /usr/sbin/bar
+do
+ if dpkg-statoverride --list $i >/dev/null 2>&1
+ then
+ dpkg-statoverride --remove $i
+ fi
+done
+ </example>
</p>
</sect1>
</sect>
<p>
If a program needs to specify an <em>architecture specification
- string</em> in some place, it should select one of the
- strings provided by <tt>dpkg-architecture -L</tt>. The
- strings are in the format
- <tt><var>os</var>-<var>arch</var></tt>, though the OS part
- is sometimes elided, as when the OS is Linux.<footnote>
- <p>Currently, the strings are:
- i386 ia64 alpha amd64 armeb arm hppa m32r m68k mips
- mipsel powerpc ppc64 s390 s390x sh3 sh3eb sh4 sh4eb
- sparc darwin-i386 darwin-ia64 darwin-alpha darwin-amd64
- darwin-armeb darwin-arm darwin-hppa darwin-m32r
- darwin-m68k darwin-mips darwin-mipsel darwin-powerpc
- darwin-ppc64 darwin-s390 darwin-s390x darwin-sh3
- darwin-sh3eb darwin-sh4 darwin-sh4eb darwin-sparc
- freebsd-i386 freebsd-ia64 freebsd-alpha freebsd-amd64
- freebsd-armeb freebsd-arm freebsd-hppa freebsd-m32r
- freebsd-m68k freebsd-mips freebsd-mipsel freebsd-powerpc
- freebsd-ppc64 freebsd-s390 freebsd-s390x freebsd-sh3
- freebsd-sh3eb freebsd-sh4 freebsd-sh4eb freebsd-sparc
- kfreebsd-i386 kfreebsd-ia64 kfreebsd-alpha
- kfreebsd-amd64 kfreebsd-armeb kfreebsd-arm kfreebsd-hppa
- kfreebsd-m32r kfreebsd-m68k kfreebsd-mips
- kfreebsd-mipsel kfreebsd-powerpc kfreebsd-ppc64
- kfreebsd-s390 kfreebsd-s390x kfreebsd-sh3 kfreebsd-sh3eb
- kfreebsd-sh4 kfreebsd-sh4eb kfreebsd-sparc knetbsd-i386
- knetbsd-ia64 knetbsd-alpha knetbsd-amd64 knetbsd-armeb
- knetbsd-arm knetbsd-hppa knetbsd-m32r knetbsd-m68k
- knetbsd-mips knetbsd-mipsel knetbsd-powerpc
- knetbsd-ppc64 knetbsd-s390 knetbsd-s390x knetbsd-sh3
- knetbsd-sh3eb knetbsd-sh4 knetbsd-sh4eb knetbsd-sparc
- netbsd-i386 netbsd-ia64 netbsd-alpha netbsd-amd64
- netbsd-armeb netbsd-arm netbsd-hppa netbsd-m32r
- netbsd-m68k netbsd-mips netbsd-mipsel netbsd-powerpc
- netbsd-ppc64 netbsd-s390 netbsd-s390x netbsd-sh3
- netbsd-sh3eb netbsd-sh4 netbsd-sh4eb netbsd-sparc
- openbsd-i386 openbsd-ia64 openbsd-alpha openbsd-amd64
- openbsd-armeb openbsd-arm openbsd-hppa openbsd-m32r
- openbsd-m68k openbsd-mips openbsd-mipsel openbsd-powerpc
- openbsd-ppc64 openbsd-s390 openbsd-s390x openbsd-sh3
- openbsd-sh3eb openbsd-sh4 openbsd-sh4eb openbsd-sparc
- hurd-i386 hurd-ia64 hurd-alpha hurd-amd64 hurd-armeb
- hurd-arm hurd-hppa hurd-m32r hurd-m68k hurd-mips
- hurd-mipsel hurd-powerpc hurd-ppc64 hurd-s390 hurd-s390x
- hurd-sh3 hurd-sh3eb hurd-sh4 hurd-sh4eb hurd-sparc
- </p>
- </footnote>
+ string</em> in some place, it should select one of the strings
+ provided by <tt>dpkg-architecture -L</tt>. The strings are in
+ the format <tt><var>os</var>-<var>arch</var></tt>, though the OS
+ part is sometimes elided, as when the OS is Linux.
</p>
<p>
<tt><var>arch</var>-unknown-linux</tt>, since the
<tt>unknown</tt> does not look very good.
</p>
+
+ <sect1 id="arch-wildcard-spec">
+ <heading>Architecture wildcards</heading>
+
+ <p>
+ A package may specify an architecture wildcard. Architecture
+ wildcards are in the format <tt>any</tt> (which matches every
+ architecture), <tt><var>os</var></tt>-any, or
+ any-<tt><var>cpu</var></tt>. <footnote>
+ Internally, the package system normalizes the GNU triplets
+ and the Debian arches into Debian arch triplets (which are
+ kind of inverted GNU triplets), with the first component of
+ the triplet representing the libc and ABI in use, and then
+ does matching against those triplets. However, such
+ triplets are an internal implementation detail that should
+ not be used by packages directly. The libc and ABI portion
+ is handled internally by the package system based on
+ the <var>os</var> and <var>cpu</var>.
+ </footnote>
+ </p>
+ </sect1>
</sect>
<sect>
use <file>/usr/bin/sensible-editor</file> and
<file>/usr/bin/sensible-pager</file> as the editor or pager
program respectively. These are two scripts provided in the
- Debian base system that check the EDITOR and PAGER variables
- and launch the appropriate program, and fall back to
- <file>/usr/bin/editor</file> and <file>/usr/bin/pager</file> if the
- variable is not set.
+ <package>sensible-utils</package> package that check the EDITOR
+ and PAGER variables and launch the appropriate program, and fall
+ back to <file>/usr/bin/editor</file>
+ and <file>/usr/bin/pager</file> if the variable is not set.
</p>
<p>
</p>
</sect1>
- <sect1>
+ <sect1 id="appdefaults">
<heading>Application defaults files</heading>
<p>
<p>
Customization of programs' X resources may also be
supported with the provision of a file with the same name
- as that of the package placed in the
- <file>/etc/X11/Xresources/</file> directory, which must
- registered as a <tt>conffile</tt> or handled as a
+ as that of the package placed in
+ the <file>/etc/X11/Xresources/</file> directory, which
+ must be registered as a <tt>conffile</tt> or handled as a
configuration file.<footnote>
Note that this mechanism is not the same as using
app-defaults; app-defaults are tied to the client
<heading>Installation directory issues</heading>
<p>
- Packages using the X Window System should not be
- configured to install files under the
- <file>/usr/X11R6/</file> directory. The
- <file>/usr/X11R6/</file> directory hierarchy should be
+ Historically, packages using the X Window System used a
+ separate set of installation directories from other packages.
+ This practice has been discontinued and packages using the X
+ Window System should now generally be installed in the same
+ directories as any other package. Specifically, packages must
+ not install files under the <file>/usr/X11R6/</file> directory
+ and the <file>/usr/X11R6/</file> directory hierarchy should be
regarded as obsolete.
</p>
<p>
- Programs that use GNU <prgn>autoconf</prgn> and
- <prgn>automake</prgn> are usually easily configured at
- compile time to use <file>/usr/</file> instead of
- <file>/usr/X11R6/</file>, and this should be done whenever
- possible. Configuration files for window managers and
- display managers should be placed in a subdirectory of
- <file>/etc/X11/</file> corresponding to the package name due
- to these programs' tight integration with the mechanisms
- of the X Window System. Application-level programs should
- use the <file>/etc/</file> directory unless otherwise mandated
- by policy.
+ Include files previously installed under
+ <file>/usr/X11R6/include/X11/</file> should be installed into
+ <file>/usr/include/X11/</file>. For files previously
+ installed into subdirectories of
+ <file>/usr/X11R6/lib/X11/</file>, package maintainers should
+ determine if subdirectories of <file>/usr/lib/</file> and
+ <file>/usr/share/</file> can be used. If not, a subdirectory
+ of <file>/usr/lib/X11/</file> should be used.
</p>
<p>
- The installation of files into subdirectories
- of <file>/usr/X11R6/include/X11/</file> and
- <file>/usr/X11R6/lib/X11/</file> is now prohibited;
- package maintainers should determine if subdirectories of
- <file>/usr/lib/</file> and <file>/usr/share/</file> can be used
- instead.
- </p>
-
- <p>
- Packages should install any relevant files into the
- directories <file>/usr/include/X11/</file> and
- <file>/usr/lib/X11/</file>, but if they do so, they must
- pre-depend on <tt>x11-common (>=
- 1:7.0.0)</tt><footnote>
- <p>
- These libraries used to be all symbolic
- links. However, with <tt>X11R7</tt>,
- <tt>/usr/include/X11</tt> and <tt>/usr/lib/X11</tt>
- are now real directories, and packages
- <strong>should</strong> ship their files here instead
- of in <tt>/usr/X11R6/{include,lib}/X11</tt>.
- <tt>x11-common (>= 1:7.0.0) </tt> is the package
- responsible for converting these symlinks into
- directories.
- </p>
- </footnote>
+ Configuration files for window, display, or session managers
+ or other applications that are tightly integrated with the X
+ Window System may be placed in a subdirectory
+ of <file>/etc/X11/</file> corresponding to the package name.
+ Other X Window System applications should use
+ the <file>/etc/</file> directory unless otherwise mandated by
+ policy (such as for <ref id="appdefaults">).
</p>
</sect1>
</p>
<p>
- Due to limitations in current implementations, all characters
- in the manual page source should be representable in the usual
- legacy encoding for that language, even if the file is
- actually encoded in UTF-8. Safe alternative ways to write many
- characters outside that range may be found in
- <manref name="groff_char" section="7">.
+ If a localized version of a manual page is provided, it should
+ either be up-to-date or it should be obvious to the reader that
+ it is outdated and the original manual page should be used
+ instead. This can be done either by a note at the beginning of
+ the manual page or by showing the missing or changed portions in
+ the original language instead of the target language.
</p>
</sect>
</p>
<p>
- Your package should call <prgn>install-info</prgn> to update
- the Info <file>dir</file> file in its <prgn>postinst</prgn>
- script when called with a <tt>configure</tt> argument, for
- example:
- <example compact="compact">
-install-info --quiet --section Development Development \
- /usr/share/info/foobar.info
- </example></p>
-
- <p>
- It is a good idea to specify a section for the location of
- your program; this is done with the <tt>--section</tt>
- switch. To determine which section to use, you should look
- at <file>/usr/share/info/dir</file> on your system and choose the most
- relevant (or create a new section if none of the current
- sections are relevant). Note that the <tt>--section</tt>
- flag takes two arguments; the first is a regular expression
- to match (case-insensitively) against an existing section,
- the second is used when creating a new one.</p>
-
- <p>
- You should remove the entries in the <prgn>prerm</prgn>
- script when called with a <tt>remove</tt> argument:
- <example compact="compact">
-install-info --quiet --remove /usr/share/info/foobar.info
- </example></p>
-
- <p>
- If <prgn>install-info</prgn> cannot find a description entry
- in the Info file you must supply one. See <manref
- name="install-info" section="8"> for details.</p>
+ The <prgn>install-info</prgn> program maintains a directory of
+ installed info documents in <file>/usr/share/info/dir</file> for
+ the use of info readers.<footnote>
+ It was previously necessary for packages installing info
+ documents to run <prgn>install-info</prgn> from maintainer
+ scripts. This is no longer necessary. The installation
+ system now uses dpkg triggers.
+ </footnote>
+ This file must not be included in packages. Packages containing
+ info documents should depend on <tt>dpkg (>= 1.15.4) |
+ install-info</tt> to ensure that the directory file is properly
+ rebuilt during partial upgrades from Debian 5.0 (lenny) and
+ earlier.
+ </p>
+
+ <p>
+ Info documents should contain section and directory entry
+ information in the document for the use
+ of <prgn>install-info</prgn>. The section should be specified
+ via a line starting with <tt>INFO-DIR-SECTION</tt> followed by a
+ space and the section of this info page. The directory entry or
+ entries should be included between
+ a <tt>START-INFO-DIR-ENTRY</tt> line and
+ an <tt>END-INFO-DIR-ENTRY</tt> line. For example:
+ <example>
+INFO-DIR-SECTION Individual utilities
+START-INFO-DIR-ENTRY
+* example: (example). An example info directory entry.
+END-INFO-DIR-ENTRY
+ </example>
+ To determine which section to use, you should look
+ at <file>/usr/share/info/dir</file> on your system and choose
+ the most relevant (or create a new section if none of the
+ current sections are relevant).<footnote>
+ Normally, info documents are generated from Texinfo source.
+ To include this information in the generated info document, if
+ it is absent, add commands like:
+ <example>
+@dircategory Individual utilities
+@direntry
+* example: (example). An example info directory entry.
+@end direntry
+ </example>
+ to the Texinfo source of the document and ensure that the info
+ documents are rebuilt from source during the package build.
+ </footnote>
+ </p>
</sect>
<sect>
<p>
Please note that this does not override the section on
changelog files below, so the file
- <file>/usr/share/<var>package</var>/changelog.Debian.gz</file>
+ <file>/usr/share/doc/<var>package</var>/changelog.Debian.gz</file>
must refer to the changelog for the current version of
<var>package</var> in question. In practice, this means
that the sources of the target and the destination of the
<p>
Every package must be accompanied by a verbatim copy of its
- copyright and distribution license in the file
+ copyright information and distribution license in the file
<file>/usr/share/doc/<var>package</var>/copyright</file>. This
file must neither be compressed nor be a symbolic link.
</p>
</p>
<p>
- The maintainer scripts are guaranteed to run with a
- controlling terminal and can interact with the user.
- See <ref id="controllingterminal">.
+ The maintainer scripts are not guaranteed to run with a
+ controlling terminal and may not be able to interact with
+ the user. See <ref id="controllingterminal">.
</p>
</item>
</p>
</sect1>
-
- <sect1 id="pkg-dpkgchangelog">
- <heading><file>debian/changelog</file></heading>
-
- <p>
- See <ref id="dpkgchangelog">.
- </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><qref id="f-Source"><tt>Source</tt></qref></item>
- <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
- <item><qref id="f-Distribution"><tt>Distribution</tt></qref> (mandatory)</item>
- <item><qref id="f-Urgency"><tt>Urgency</tt></qref> (mandatory)</item>
- <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
- <item><qref id="f-Date"><tt>Date</tt></qref></item>
- <item><qref id="f-Changes"><tt>Changes</tt></qref> (mandatory)</item>
- </list>
- </p>
-
- <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="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 synthesize
- 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>
-
<sect1 id="pkg-srcsubstvars">
<heading><file>debian/substvars</file> and variable substitutions</heading>