</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-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-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>
</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>
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>
projects / debian / debian-policy.git / blobdiff