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
its copyright 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>
<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>
values:
<list>
<item>A unique single word identifying a Debian machine
- architecture as described in <ref id="arch-spec">.
+ 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">.
+ </item>
<item><tt>all</tt>, which indicates an
architecture-independent package.
<item><tt>any</tt>, which indicates a package available
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.
+ specific and wildcard architectures separated by
+ spaces. If the special value <tt>any</tt> appears, it 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.
</p>
<p>
package, <tt>all</tt> will also be included in the list.
</p>
+ <p>
+ Specifying a list of architecture wildcards indicates that
+ the source will build an architecture-dependent package on
+ the union of the lists of architectures from the expansion
+ of each specified architecture wildcard, and will only
+ work correctly on the architectures in the union of the
+ lists.<footnote> As mentioned in the footnote for
+ specifying a list of architectures, this is for a minority
+ of cases where the program is not portable. Generally, it
+ should not be used for new packages. Wildcards are not
+ expanded into a list of known architectures before
+ comparing to the build architecutre. Instead, the build
+ architecture is matched against wildcards and this package
+ is built if the wildcard matches.</footnote> 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)
</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
<p>
In a <file>.changes</file> file, the <tt>Description</tt>
field contains a summary of the descriptions for the packages
- being uploaded. For this caes, the first line of the field
+ 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
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>
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
</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>
source package section of the control file (which is the
first section).
</p>
+ <p>
+ All fields that specify build-time relationships
+ (<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
+ <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>) 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
+ on any architecture using a kernel other than Linux.
+ </p>
</sect>
<sect id="binarydeps">
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>
<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">
<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">
</p>
</sect>
+ <sect id="arch-wildcard-spec">
+ <heading>Architecture Wildcards</heading>
+
+ <p>
+ A package may specify an architecture wildcard. Architecture
+ wildcards are in the format <tt><var>os</var></tt>-any and
+ 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). So when matching two Debian arch triplets, whenever an
+ <var>any</var> is found it matches with anything on the other side,
+ like in:
+ <example>
+ gnu-linux-i386 is matched by gnu-linux-any
+ gnu-kfreebsd-amd64 is matched by any-any-amd64
+ </example>
+ And for example <var>any</var> is normalized to <var>any-any-any</var>.
+ </footnote>
+ </p>
+ </sect>
+
<sect>
<heading>Daemons</heading>
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>
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
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 hooks.
+ system now uses dpkg triggers.
</footnote>
- This file must not be included in packages.
+ 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>
* 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>
- to the Texinfo source of the document and ensure that the info
- documents are rebuilt from source during the package build.
</p>
</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