</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
</p>
<p>
- <file>shlibs<file> files also only support a limited range 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.<footnote>
A <file>shlibs</file> file represents an SONAME as a library
</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);
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.
<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