<p>
The Debian archive maintainers provide the authoritative
list of sections. At present, they are:
- <em>admin</em>, <em>cli-mono</em>, <em>comm</em>, <em>database</em>,
- <em>devel</em>, <em>debug</em>, <em>doc</em>, <em>editors</em>,
- <em>education</em>, <em>electronics</em>, <em>embedded</em>,
- <em>fonts</em>, <em>games</em>, <em>gnome</em>, <em>graphics</em>,
- <em>gnu-r</em>, <em>gnustep</em>, <em>hamradio</em>, <em>haskell</em>,
- <em>httpd</em>, <em>interpreters</em>, <em>introspection</em>,
- <em>java</em>, <em>kde</em>, <em>kernel</em>, <em>libs</em>,
- <em>libdevel</em>, <em>lisp</em>, <em>localization</em>,
- <em>mail</em>, <em>math</em>, <em>metapackages</em>, <em>misc</em>,
- <em>net</em>, <em>news</em>, <em>ocaml</em>, <em>oldlibs</em>,
- <em>otherosfs</em>, <em>perl</em>, <em>php</em>, <em>python</em>,
- <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>. The additional section <em>debian-installer</em>
+admin,
+cli-mono,
+comm,
+database,
+debug,
+devel,
+doc,
+editors,
+education,
+electronics,
+embedded,
+fonts,
+games,
+gnome,
+gnu-r,
+gnustep,
+graphics,
+hamradio,
+haskell,
+httpd,
+interpreters,
+introspection,
+java,
+kde,
+kernel,
+libdevel,
+libs,
+lisp,
+localization,
+mail,
+math,
+metapackages,
+misc,
+net,
+news,
+ocaml,
+oldlibs,
+otherosfs,
+perl,
+php,
+python,
+ruby,
+science,
+shells,
+sound,
+tasks,
+tex,
+text,
+utils,
+vcs,
+video,
+web,
+x11,
+xfce,
+zope.
+ The additional section <em>debian-installer</em>
contains special packages used by the installer and is not used
for normal Debian packages.
</p>
/closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i
</example>
Then all of the bug numbers listed will be closed by the
- archive maintenance script (<prgn>katie</prgn>) using the
+ archive maintenance software (<prgn>dak</prgn>) using the
<var>version</var> of the changelog entry.
</footnote>
This information is conveyed via the <tt>Closes</tt> field
</p>
</item>
- <tag><tt>build-arch</tt> (optional),
- <tt>build-indep</tt> (optional)
+ <tag><tt>build-arch</tt> (required),
+ <tt>build-indep</tt> (required)
</tag>
<item>
<p>
- A package may also provide one or both of the targets
- <tt>build-arch</tt> and <tt>build-indep</tt>.
- The <tt>build-arch</tt> target, if provided, should
+ The <tt>build-arch</tt> target must
perform all the configuration and compilation required for
producing all architecture-dependant binary packages
(those packages for which the body of the
<tt>Architecture</tt> field in <tt>debian/control</tt> is
not <tt>all</tt>). Similarly, the <tt>build-indep</tt>
- target, if provided, should perform all the configuration
+ target must perform all the configuration
and compilation required for producing all
architecture-independent binary packages (those packages
for which the body of the <tt>Architecture</tt> field
in <tt>debian/control</tt> is <tt>all</tt>).
- </p>
-
- <p>
- If <tt>build-arch</tt> or <tt>build-indep</tt> targets are
- provided in the rules file, the <tt>build</tt> target
+ The <tt>build</tt> target
should either depend on those targets or take the same
actions as invoking those targets would perform.<footnote>
- The intent of this split is so that binary-only builds
- need not install the dependencies required for
- the <tt>build-indep</tt> target. However, this is not
- yet used in practice since <tt>dpkg-buildpackage
- -B</tt>, and therefore the autobuilders,
- invoke <tt>build</tt> rather than <tt>build-arch</tt>
- due to the difficulties in determining whether the
- optional <tt>build-arch</tt> target exists.
+ This split allows binary-only builds to not install the
+ dependencies required for the <tt>build-indep</tt>
+ target and skip any resource-intensive build tasks that
+ are only required when building architecture-independent
+ binary packages.
</footnote>
</p>
- <p>
- If one or both of the targets <tt>build-arch</tt> and
- <tt>build-indep</tt> are not provided, then invoking
- <file>debian/rules</file> with one of the not-provided
- targets as arguments should produce a exit status code
- of 2. Usually this is provided automatically by make
- if the target is missing.
- </p>
-
<p>
The <tt>build-arch</tt> and <tt>build-indep</tt> targets
must not do anything that might require root privilege.
<item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
<item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
<item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
- <item><qref id="f-DM-Upload-Allowed"><tt>DM-Upload-Allowed</tt></qref></item>
<item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
<item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
<item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
<item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
<item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
+ <item><qref id="f-VCS-fields"><tt>Vcs-Browser</tt>, <tt>Vcs-Git</tt>, et al.</qref></item>
</list>
</p>
<item><qref id="binarydeps"><tt>Depends</tt> et al</qref></item>
<item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
<item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
+ <item><qref id="built-using"><tt>Built-Using</tt></qref></item>
+ <item><qref id="f-Package-Type"><tt>Package-Type</tt></qref></item>
</list>
</p>
<item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
<item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
<item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
+ <item><qref id="built-using"><tt>Built-Using</tt></qref></item>
</list>
</p>
</sect>
<item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
<item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
<item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
- <item><qref id="f-DM-Upload-Allowed"><tt>DM-Upload-Allowed</tt></qref></item>
<item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
+ <item><qref id="f-VCS-fields"><tt>Vcs-Browser</tt>, <tt>Vcs-Git</tt>, et al.</qref></item>
<item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
<item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
+ <item><qref id="f-Package-List"><tt>Package-List</tt></qref> (recommended)</item>
<item><qref id="f-Checksums"><tt>Checksums-Sha1</tt>
- and <tt>Checksums-Sha256</tt></qref> (recommended)</item>
+ and <tt>Checksums-Sha256</tt></qref> (mandatory)</item>
<item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
</list>
</p>
<item><qref id="f-Closes"><tt>Closes</tt></qref></item>
<item><qref id="f-Changes"><tt>Changes</tt></qref> (mandatory)</item>
<item><qref id="f-Checksums"><tt>Checksums-Sha1</tt>
- and <tt>Checksums-Sha256</tt></qref> (recommended)</item>
+ and <tt>Checksums-Sha256</tt></qref> (mandatory)</item>
<item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
</list>
</p>
</p>
<p>
- In the <file>.dsc</file> file, these fields should list all
+ In the <file>.dsc</file> file, these fields list all
files that make up the source package. In
- the <file>.changes</file> file, these fields should list all
+ the <file>.changes</file> file, these fields list all
files being uploaded. The list of files in these fields
must match the list of files in the <tt>Files</tt> field.
</p>
</sect1>
- <sect1 id="f-DM-Upload-Allowed">
+ <sect1>
<heading><tt>DM-Upload-Allowed</tt></heading>
<p>
- Indicates that Debian Maintainers may upload this package to
- the Debian archive. The only valid value is <tt>yes</tt>. If
- the field <tt>DM-Upload-Allowed: yes</tt> is present in the
- source section of the source control file of the most recent
- version of a package in unstable or experimental, the Debian
- archive will accept uploads of this package signed with a key
- in the Debian Maintainer keyring. See the General
- Resolution <url id="http://www.debian.org/vote/2007/vote_003"
- name="Endorse the concept of Debian Maintainers"> for more
- details.
+ Obsolete, see <qref id="f-DM-Upload-Allowed">below</qref>.
+ </p>
+ </sect1>
+
+ <sect1 id="f-VCS-fields">
+ <heading>Version Control System (VCS) fields</heading>
+
+ <p>
+ Debian source packages are increasingly developed using VCSs. The
+ purpose of the following fields is to indicate a publicly accessible
+ repository where the Debian source package is developed.
+
+ <taglist>
+ <tag><tt>Vcs-Browser</tt></tag>
+ <item>
+ <p>
+ URL of a web interface for browsing the repository.
+ </p>
+ </item>
+
+ <tag>
+ <tt>Vcs-Arch</tt>, <tt>Vcs-Bzr</tt> (Bazaar), <tt>Vcs-Cvs</tt>,
+ <tt>Vcs-Darcs</tt>, <tt>Vcs-Git</tt>, <tt>Vcs-Hg</tt>
+ (Mercurial), <tt>Vcs-Mtn</tt> (Monotone), <tt>Vcs-Svn</tt>
+ (Subversion)
+ </tag>
+ <item>
+ <p>
+ The field name identifies the VCS. The field's value uses the
+ version control system's conventional syntax for describing
+ repository locations and should be sufficient to locate the
+ repository used for packaging. Ideally, it also locates the
+ branch used for development of new versions of the Debian
+ package.
+ </p>
+ <p>
+ In the case of Git, the value consists of a URL, optionally
+ followed by the word <tt>-b</tt> and the name of a branch in
+ the indicated repository, following the syntax of the
+ <tt>git clone</tt> command. If no branch is specified, the
+ packaging should be on the default branch.
+ </p>
+ <p>
+ More than one different VCS may be specified for the same
+ package.
+ </p>
+ </item>
+ </taglist>
+ </p>
+ </sect1>
+
+ <sect1 id="f-Package-List">
+ <heading><tt>Package-List</tt></heading>
+
+ <p>
+ Multiline field listing all the packages that can be built from
+ the source package, considering every architecture. The first line
+ of the field value is empty. Each one of the next lines describes
+ one binary package, by listing its name, type, section and priority
+ separated by spaces. Fifth and subsequent space-separated items
+ may be present and parsers must allow them. See the
+ <qref id="f-Package-Type">Package-Type</qref> field for a list of
+ package types.
+ </p>
+ </sect1>
+
+ <sect1 id="f-Package-Type">
+ <heading><tt>Package-Type</tt></heading>
+
+ <p>
+ Simple field containing a word indicating the type of package:
+ <tt>deb</tt> for binary packages and <tt>udeb</tt> for micro binary
+ packages. Other types not defined here may be indicated. In
+ source package control files, the <tt>Package-Type</tt> field
+ should be omitted instead of giving it a value of <tt>deb</tt>, as
+ this value is assumed for paragraphs lacking this field.
</p>
</sect1>
</sect>
</sect>
+ <sect id="obsolete-control-data-fields">
+ <heading>Obsolete fields</heading>
+
+ <p>
+ The following fields have been obsoleted and may be found in packages
+ conforming with previous versions of the Policy.
+ </p>
+
+ <sect1 id="f-DM-Upload-Allowed">
+ <heading><tt>DM-Upload-Allowed</tt></heading>
+
+ <p>
+ Indicates that Debian Maintainers may upload this package to
+ the Debian archive. The only valid value is <tt>yes</tt>. This
+ field was used to regulate uploads by Debian Maintainers, See the
+ General Resolution <url id="http://www.debian.org/vote/2007/vote_003"
+ name="Endorse the concept of Debian Maintainers"> for more details.
+ </p>
+ </sect1>
+
+ </sect>
+
</chapt>
<p>
The relations allowed are <tt><<</tt>, <tt><=</tt>,
- <tt>=</tt>, <tt>>=</tt> and <tt>>></tt> for
- strictly earlier, earlier or equal, exactly equal, later or
- equal and strictly later, respectively. The deprecated
- forms <tt><</tt> and <tt>></tt> were used to mean
- earlier/later or equal, rather than strictly earlier/later,
- so they should not appear in new packages (though
- <prgn>dpkg</prgn> still supports them).
+ <tt>=</tt>, <tt>>=</tt> and <tt>>></tt> for strictly
+ earlier, earlier or equal, exactly equal, later or equal and
+ strictly later, respectively. The deprecated
+ forms <tt><</tt> and <tt>></tt> were confusingly used to
+ mean earlier/later or equal, rather than strictly earlier/later,
+ and must not appear in new packages (though <prgn>dpkg</prgn>
+ still supports them with a warning).
</p>
<p>
</p>
<p>
- For binary relationship fields, the architecture restriction
+ For binary relationship fields and the <tt>Built-Using</tt>
+ field, the architecture restriction
syntax is only supported in the source package control
file <file>debian/control</file>. When the corresponding binary
package control file is generated, the relationship will either
</taglist>
</p>
</sect>
+
+ <sect id="built-using">
+ <heading>Additional source packages used to build the binary
+ - <tt>Built-Using</tt>
+ </heading>
+
+ <p>
+ Some binary packages incorporate parts of other packages when built
+ but do not have to depend on those packages. Examples include
+ linking with static libraries or incorporating source code from
+ another package during the build. In this case, the source packages
+ of those other packages are a required part of the complete source
+ (the binary package is not reproducible without them).
+ </p>
+
+ <p>
+ A <tt>Built-Using</tt> field must list the corresponding source
+ package for any such binary package incorporated during the build
+ <footnote>
+ <tt>Build-Depends</tt> in the source package is not adequate since
+ it (rightfully) does not document the exact version used in the
+ build.
+ </footnote>,
+ including an "exactly equal" ("=") version relation on the version
+ that was used to build that binary package<footnote>
+ The archive software might reject packages that refer to
+ non-existent sources.
+ </footnote>.
+ </p>
+
+ <p>
+ A package using the source code from the gcc-4.6-source
+ binary package built from the gcc-4.6 source package would
+ have this field in its control file:
+ <example compact="compact">
+Built-Using: gcc-4.6 (= 4.6.0-11)
+ </example>
+ </p>
+
+ <p>
+ A package including binaries from grub2 and loadlin would
+ have this field in its control file:
+ <example compact="compact">
+Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
+ </example>
+ </p>
+ </sect>
</chapt>
<p>
To determine the <var>soversion</var>, look at
the <tt>SONAME</tt> of the library, stored in the
- ELF <tt>SONAME</tt> attribute. it is usually of the
+ ELF <tt>SONAME</tt> attribute. It is usually of the
form <tt><var>name</var>.so.<var>major-version</var></tt> (for
example, <tt>libz.so.1</tt>). The version part is the part
which comes after <tt>.so.</tt>, so in that example it
whether new library interfaces are available and can be called).
To allow these dependencies to be constructed, shared libraries
must provide either a <file>symbols</file> file or
- a <file>shlibs</file> file, which provide information on the
- package dependencies required to ensure the presence of this
- library. Any package which uses a shared library must use these
- files to determine the required dependencies when it is built.
- </p>
-
- <p>
- These two mechanisms differ in the degree of detail that they
- provide. A <file>symbols</file> file documents every symbol
- that is part of the library ABI and, for each, the version of
- the package in which it was introduced. This permits detailed
- analysis of the symbols used by a particular package and
- construction of an accurate dependency, but it requires the
- package maintainer to track more information about the shared
- library. A <file>shlibs</file> file, in contrast, only
- documents the last time the library ABI changed in any way. It
- only provides information about the library as a whole, not
- individual symbols. When a package is built using a shared
- library with only a <file>shlibs</file> file, the generated
- dependency will require a version of the shared library equal to
- or newer than the version of the last ABI change. This
- generates unnecessarily restrictive dependencies compared
+ a <file>shlibs</file> file. These provide information on the
+ package dependencies required to ensure the presence of
+ interfaces provided by this library. Any package with binaries
+ or libraries linking to a shared library must use these files to
+ determine the required dependencies when it is built. Other
+ packages which use a shared library (for example using
+ <tt>dlopen()</tt>) should compute appropriate dependencies
+ using these files at build time as well.
+ </p>
+
+ <p>
+ The two mechanisms differ in the degree of detail that they
+ provide. A <file>symbols</file> file documents, for each symbol
+ exported by a library, the minimal version of the package any
+ binary using this symbol will need. This is typically the
+ version of the package in which the symbol was introduced. This
+ information permits detailed analysis of the symbols used by a
+ particular package and construction of an accurate dependency,
+ but it requires the package maintainer to track more information
+ about the shared library.
+ </p>
+
+ <p>
+ A <file>shlibs</file> file, in contrast, only documents the last
+ time the library ABI changed in any way. It only provides
+ information about the library as a whole, not individual
+ symbols. When a package is built using a shared library with
+ only a <file>shlibs</file> file, the generated dependency will
+ require a version of the shared library equal to or newer than
+ the version of the last ABI change. This generates
+ unnecessarily restrictive dependencies compared
to <file>symbols</file> files if none of the symbols used by the
package have changed. This, in turn, may make upgrades
needlessly complex and unnecessarily restrict use of the package
</p>
<p>
- <file>shlibs<file> files also have a flawed representation of
+ <file>shlibs</file> files also only support a limited range of
library SONAMEs, making it difficult to use <file>shlibs</file>
- files in some unusual corner cases.
+ files in some unusual corner cases.<footnote>
+ A <file>shlibs</file> file represents an SONAME as a library
+ name and version number, such as <tt>libfoo VERSION</tt>,
+ instead of recording the actual SONAME. If the SONAME doesn't
+ match one of the two expected formats
+ (<tt>libfoo-VERSION.so</tt> or <tt>libfoo.so.VERSION</tt>), it
+ cannot be represented.
+ </footnote>
</p>
<p>
required by <file>symbols</file> files is not too difficult to
maintain. However, maintaining exhaustive symbols information
for a C++ library can be quite onerous, so <file>shlibs</file>
- files may be more appropriate for most C++ libraries. udebs
- must also use <file>shlibs</file>, since the udeb infrastructure
- does not use <file>symbols</file>.
+ files may be more appropriate for most C++ libraries. Libraries
+ with a corresponding udeb must also provide
+ a <file>shlibs</file> file, since the udeb infrastructure does
+ not use <file>symbols</file> files.
</p>
<sect1 id="dpkg-shlibdeps">
binaries, libraries, or loadable modules. If you have
multiple binary packages, you will need to
call <prgn>dpkg-shlibdeps</prgn> on each one which contains
- compiled libraries or binaries, using the <tt>-T</tt> option
- to the <tt>dpkg</tt> utilities to specify a
- different <file>substvars</file> file for each binary
- package.<footnote>
+ compiled libraries or binaries. For example, you could use
+ the <tt>-T</tt> option to the <tt>dpkg</tt> utilities to
+ specify a different <file>substvars</file> file for each
+ binary package.<footnote>
Again, <prgn>dh_shlibdeps</prgn>
and <prgn>dh_gencontrol</prgn> will handle everything except
the addition of the variable to the control file for you if
linked <em>indirectly</em> to <tt>foo</tt>, and the dynamic
linker will load them automatically when it
loads <tt>libbar</tt>. A package should depend on the
- libraries it directly uses, but not the libraries it
- indirectly uses. The dependencies for the libraries used
+ libraries it directly uses, but not the libraries it only uses
+ indirectly. The dependencies for the libraries used
directly will automatically pull in the indirectly-used
libraries. <prgn>dpkg-shlibdeps</prgn> will handle this logic
automatically, but package maintainers need to be aware of
<p>
There are two types of ABI changes: ones that are
backward-compatible and ones that are not. An ABI change is
- backward-compatible if any binary was linked with the previous
- version of the shared library will still work correctly with
- the new version of the shared library. Adding new symbols to
- the shared library is a backward-compatible change. Removing
- symbols from the shared library is not. Changing the behavior
- of a symbol may or may not be backward-compatible depending on
- the change; for example, changing a function to accept a new
- enum constant not previously used by the library is generally
+ backward-compatible if any reasonable program or library that
+ was linked with the previous version of the shared library
+ will still work correctly with the new version of the shared
+ library.<footnote>
+ An example of an "unreasonable" program is one that uses
+ library interfaces that are documented as internal and
+ unsupported. If the only programs or libraries affected by
+ a change are "unreasonable" ones, other techniques, such as
+ declaring <tt>Breaks</tt> relationships with affected
+ packages or treating their usage of the library as bugs in
+ those packages, may be appropriate instead of changing the
+ SONAME. However, the default approach is to change the
+ SONAME for any change to the ABI that could break a program.
+ </footnote>
+ Adding new symbols to the shared library is a
+ backward-compatible change. Removing symbols from the shared
+ library is not. Changing the behavior of a symbol may or may
+ not be backward-compatible depending on the change; for
+ example, changing a function to accept a new enum constant not
+ previously used by the library is generally
backward-compatible, but changing the members of a struct that
is passed into library functions is generally not unless the
library takes special precautions to accept old versions of
</p>
<p>
- A common example of when a change to the is required is a
- function that takes an enum or struct argument that controls
- what the function does. For example:
+ A common example of when a change to the dependency version
+ is required is a function that takes an enum or struct
+ argument that controls what the function does. For example:
<example>
enum library_op { OP_FOO, OP_BAR };
int library_do_operation(enum library_op);
<p>
<file>symbols</file> files for a shared library are normally
- provided by the shared library package, but there are
- several override paths that are checked first in case that
- information is wrong or missing. The following list gives
- them in the order in which they are read
+ provided by the shared library package as a control file,
+ but there are several override paths that are checked first
+ in case that information is wrong or missing. The following
+ list gives them in the order in which they are read
by <prgn>dpkg-shlibdeps</prgn> The first one that contains
the required information is used.
<list>
recent version of the shared library that changed the
behavior of that symbol, whether by adding it, changing its
function signature (the parameters, their types, or the
- return type), or its behavior in a way that is visible to a
- caller. <var>id-of-dependency-template</var> is an optional
+ return type), or changing its behavior in a way that is
+ visible to a caller.
+ <var>id-of-dependency-template</var> is an optional
field that references
an <var>alternative-dependency-template</var>; see below for
a full description.
compressBound@ZLIB_1.2.0 1:1.2.0
</example>
Packages using only <tt>compress</tt> would then get a
- dependency of <tt>zlib1g (>= 1:1.1.4)</tt>, but packages
+ dependency on <tt>zlib1g (>= 1:1.1.4)</tt>, but packages
using <tt>compressBound</tt> would get a dependency
- of <tt>zlib1g (>= 1:1.2.0)</tt>.
+ on <tt>zlib1g (>= 1:1.2.0)</tt>.
</p>
<p>
<heading>The <tt>shlibs</tt> system</heading>
<p>
- The <tt>shlibs</tt> system is an simpler alternative to
+ The <tt>shlibs</tt> system is a simpler alternative to
the <tt>symbols</tt> system for declaring dependencies for
shared libraries. It may be more appropriate for C++
libraries and other cases where tracking individual symbols is
library was in version <tt>1:1.2.3.3.dfsg-1</tt>, then
the <tt>shlibs</tt> entry for this library could say:
<example compact="compact">
- libz 1 zlib1g (>= 1:1.2.3.3.dfsg-1)
+ libz 1 zlib1g (>= 1:1.2.3.3.dfsg)
</example>
This version restriction must be new enough that any binary
built against the current version of the library will work
As zlib1g also provides a udeb containing the shared
library, there would also be a second line:
<example compact="compact">
- udeb: libz 1 zlib1g-udeb (>= 1:1.2.3.3.dfsg-1)
+ udeb: libz 1 zlib1g-udeb (>= 1:1.2.3.3.dfsg)
</example>
</p>
</sect2>
in <file>/run</file> should be stored on a temporary
file system.
</p>
+ <p>
+ Packages must not assume the <file>/run</file>
+ directory exists or is usable without a dependency
+ on <tt>initscripts (>= 2.88dsf-13.3)</tt> until the
+ stable release of Debian supports <file>/run</file>.
+ </p>
</item>
<item>
<p>
</p>
<p>
- Packages which provide the ability to view/show/play,
- compose, edit or print MIME types should register themselves
- as such following the current MIME support policy.
+ Packages which provide programs to view/show/play, compose, edit or
+ print MIME types should register them as such by placing a file in
+ <manref name="mailcap" section="5"> format (RFC 1524) in the directory
+ <file>/usr/lib/mime/packages/</file>. The file name should be the
+ binary package's name.
</p>
<p>
The <package>mime-support</package> package provides the
- <prgn>update-mime</prgn> program which allows packages to
- register programs that can show, compose, edit or print
- MIME types.
- </p>
-
- <p>
- Packages containing such programs must register them
- with <prgn>update-mime</prgn> as documented in <manref
- name="update-mime" section="8">. They should <em>not</em> depend
- on, recommend, or suggest <prgn>mime-support</prgn>. Instead,
- they should just put something like the following in the
- <tt>postinst</tt> and <tt>postrm</tt> scripts:
-
- <example>
- if [ -x /usr/sbin/update-mime ]; then
- update-mime
- fi
- </example>
+ <prgn>update-mime</prgn> program, which integrates these
+ registrations in the <file>/etc/mailcap</file> file, using dpkg
+ triggers<footnote>
+ Creating, modifying or removing a file in
+ <file>/usr/lib/mime/packages/</file> using maintainer scripts will
+ not activate the trigger. In that case, it can be done by calling
+ <tt>dpkg-trigger --no-await /usr/lib/mime/packages</tt> from
+ the maintainer script after creating, modifying, or removing
+ the file.
+ </footnote>.
+ Packages using this facility <em>should not</em> depend on,
+ recommend, or suggest <prgn>mime-support</prgn>.
</p>
-
</sect>
<sect>
</p>
</sect>
+ <sect id="alternateinit">
+ <heading>Alternate init systems</heading>
+ <p>
+ A number of other init systems are available now in Debian that
+ can be used in place of <package>sysvinit</package>. Alternative
+ init implementations must support running SysV init scripts as
+ described at <ref id="sysvinit"> for compatibility.
+ </p>
+ <p>
+ Packages may integrate with these replacement init systems by
+ providing implementation-specific configuration information about
+ how and when to start a service or in what order to run certain
+ tasks at boot time. However, any package integrating with other
+ init systems must also be backwards-compatible with
+ <package>sysvinit</package> by providing a SysV-style init script
+ with the same name as and equivalent functionality to any
+ init-specific job, as this is the only start-up configuration
+ method guaranteed to be supported by all init implementations. An
+ exception to this rule is scripts or jobs provided by the init
+ implementation itself; such jobs may be required for an
+ implementation-specific equivalent of the <file>/etc/rcS.d/</file>
+ scripts and may not have a one-to-one correspondence with the init
+ scripts.
+ </p>
+ <sect1 id="upstart">
+ <heading>Event-based boot with upstart</heading>
+
+ <p>
+ Packages may integrate with the <prgn>upstart</prgn> event-based
+ boot system by installing job files in the
+ <file>/etc/init</file> directory. SysV init scripts for which
+ an equivalent upstart job is available must query the output of
+ the command <prgn>initctl version</prgn> for the string
+ <tt>upstart</tt> and avoid running in favor of the native
+ upstart job, using a test such as this:
+ <example compact="compact">
+if [ "$1" = start ] && which initctl >/dev/null && initctl version | grep -q upstart
+then
+ exit 1
+fi
+ </example>
+ </p>
+ <p>
+ Because packages shipping upstart jobs may be installed on
+ systems that are not using upstart, maintainer scripts must
+ still use the common <prgn>update-rc.d</prgn> and
+ <prgn>invoke-rc.d</prgn> interfaces for configuring runlevels
+ and for starting and stopping services. These maintainer
+ scripts must not call the upstart <prgn>start</prgn>,
+ <prgn>restart</prgn>, <prgn>reload</prgn>, or <prgn>stop</prgn>
+ interfaces directly. Instead, implementations of
+ <prgn>invoke-rc.d</prgn> must detect when upstart is running and
+ when an upstart job with the same name as an init script is
+ present, and perform the requested action using the upstart job
+ instead of the init script.
+ </p>
+ <p>
+ Dependency-based boot managers for SysV init scripts, such as
+ <prgn>startpar</prgn>, may avoid running a given init script
+ entirely when an equivalent upstart job is present, to avoid
+ unnecessary forking of no-op init scripts. In this case, the
+ boot manager should integrate with upstart to detect when the
+ upstart job in question is started or stopped to know when the
+ dependency has been satisfied.
+ </p>
+ </sect1>
+ </sect>
+
</chapt>
<file>README.Debian</file> or some other appropriate place.
</p>
+ <p>
+ All copyright files must be encoded in UTF-8.
+ </p>
+
<sect1 id="copyrightformat">
<heading>Machine-readable copyright information</heading>
<prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and the way
they interact with packages.</p>
- <p>
- It also documents the interaction between
- <prgn>dselect</prgn>'s core and the access method scripts it
- uses to actually install the selected packages, and describes
- how to create a new access method.</p>
-
<p>
This manual does not go into detail about the options and
usage of the package building and installation tools. It