<p>
This manual is distributed via the Debian package
- <package>debian-policy</package>.
+ <package><url name="debian-policy" id="http://packages.debian.org/debian-policy"></package>.
</p>
<p>
The current version of this document is also available from
the Debian web mirrors at
<tt><url name="/doc/debian-policy/"
- id="http://www.debian.org/doc/debian-policy/"></tt>
- and from the Debian archive mirrors at
- <tt><url name="/doc/package-developer/policy.txt.gz"
- id="http://ftp.debian.org/debian/doc/package-developer/policy.txt.gz"></tt>.
+ id="http://www.debian.org/doc/debian-policy/"></tt>.
Also available from the same directory are several other
formats: <file>policy.html.tar.gz</file>, <file>policy.pdf.gz</file>
and <file>policy.ps.gz</file>.
<em>admin</em>, <em>base</em>, <em>comm</em>,
<em>contrib</em>, <em>devel</em>, <em>doc</em>,
<em>editors</em>, <em>electronics</em>, <em>embedded</em>,
- <em>games</em>, <em>gnome</em> <em>graphics</em>,
+ <em>games</em>, <em>gnome</em>, <em>graphics</em>,
<em>hamradio</em>, <em>interpreters</em>, <em>kde</em>,
<em>libs</em>, <em>libdevel</em>, <em>mail</em>,
<em>math</em>, <em>misc</em>, <em>net</em>, <em>news</em>,
<heading>Prompting in maintainer scripts</heading>
<p>
Package maintainer scripts may prompt the user if
- necessary. Prompting may be accomplished by hand<footnote>
- From the Jargon file: by hand 2. By extension,
- writing code which does something in an explicit or
- low-level way for which a presupplied library
- (<em>debconf, in this instance</em>) routine ought
- to have been available.
- </footnote>
- (but this is deprecated), or by communicating through a program
- which conforms to the Debian Configuration management
- specification, version 2 or higher, such as
- <prgn>debconf</prgn><footnote>
- <p>
- 6% of Debian packages [see <url
- id="http://ftp-master.debian.org/~joeyh/debconf-stats/"
- name="Debconf stats">] currently use
- <package>debconf</package> to prompt the user at
- install time, and this number is growing daily. The
- benefits of using debconf are briefly explained at
- <url
- id="http://kitenet.net/doc/debconf-doc/introduction.html"
- name="Debconf introduction">; they include
- preconfiguration, (mostly) noninteractive
- installation, elimination of redundant prompting,
- consistency of user interface, etc.
- </p>
-
- <p>
- With this increasing number of packages using
- <package>debconf</package>, plus the existence of a
- nascent second implementation of the Debian
- configuration management system
- (<package>cdebconf</package>), and the stabilization
- of the protocol these things use, the time has
- finally come to reflect the use of these things in
- policy.
- </p>
- </footnote>.
+ necessary. Prompting should be done by communicating
+ through a program, such as <prgn>debconf</prgn>, which
+ conforms to the Debian Configuration management
+ specification, version 2 or higher. Prompting the user by
+ other means, such as by hand<footnote>
+ From the Jargon file: by hand 2. By extension,
+ writing code which does something in an explicit or
+ low-level way for which a presupplied library
+ (<em>debconf, in this instance</em>) routine ought
+ to have been available.
+ </footnote>, is now deprecated.
</p>
<p>
</p>
</sect>
- <sect>
- <heading>Obsolete constructs and libraries</heading>
-
- <p>
- The include file <tt><varargs.h></tt> is
- provided to support end-users compiling very old software;
- the library <tt>libtermcap</tt> is provided to support the
- execution of software which has been linked against it
- (either old programs or those such as Netscape which are
- only available in binary form).
- </p>
-
- <p>
- Debian packages should be patched to use
- <tt><stdarg.h></tt> and <tt>ncurses</tt>
- instead.
- </p>
- </sect>
-
<sect id="debianrules">
<heading>Main building script: <file>debian/rules</file></heading>
<p>
The architectures we build on and build for are determined
by <prgn>make</prgn> variables using the utility
- <qref id="pkg-dpkg
arch"><prgn>dpkg-architecture</prgn></qref>.
+ <qref id="pkg-dpkg
-architecture"><prgn>dpkg-architecture</prgn></qref>.
You can determine the
Debian architecture and the GNU style architecture
specification string for the build machine (the machine type
<heading><tt>Architecture</tt></heading>
<p>
- This is the architecture string; it is a single word for
- the Debian architecture. The special value <tt>all</tt>
- indicates that the package is architecture-independent.
+ Depending on context and the control file used, the
+ <tt>Architecture</tt> field can include the following sets of
+ values:
+ <list>
+ <item>A unique single word identifying a Debian machine
+ architecture, see <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.
+ </list>
</p>
<p>
In the main <file>debian/control</file> file in the source
package, or in the source package control file
- <file>.dsc</file>, a list of architectures (separated by
- spaces) is also allowed, as is the special value
- <tt>any</tt>. A list indicates that the source will build
- an architecture-dependent package, and will only work
- correctly on the listed architectures. <tt>any</tt>
- indicates that though the source package isn't dependent
- on any particular architecture and should compile fine on
- any one, the binary package(s) produced are not
- architecture-independent but will instead be specific to
- whatever the current build architecture is.
+ <file>.dsc</file>, one may specify a list of architectures
+ separated by spaces, or the special values <tt>any</tt> or
+ <tt>all</tt>.
+ </p>
+
+ <p>
+ Specifying <tt>any</tt> indicates that the source package
+ isn't dependent on any particular architecture and should
+ compile fine on any one. The produced binary package(s)
+ will be specific to whatever the current build architecture
+ is.<footnote>
+ This is the most often used setting, and is recommended
+ for new packages that aren't <tt>Architecture: all</tt>.
+ </footnote>
+ </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.<footnote>
+ This is a setting used for a minority of cases where the
+ program is not portable. Generally, it should not be used
+ for new packages.
+ </footnote>
</p>
<p>
- In a <file>.changes</file> file the <tt>Architecture</tt>
+ 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 being uploaded too the special
+ source for the package is also being uploaded, the special
entry <tt>source</tt> is also present.
</p>
<p>
If there is no most recently configured version
- <prgn>dpkg</prgn> will pass a null argument; older versions
- of dpkg may pass <tt><unknown></tt> (including the
- angle brackets) in this case. Even older ones do not pass a
- second argument at all, under any circumstances.
+ <prgn>dpkg</prgn> will pass a null argument.
+ <footnote>
+ <p>
+ Historical note: Truly ancient (pre-1997) versions of
+ <prgn>dpkg</prgn> passed <tt><unknown></tt>
+ (including the angle brackets) in this case. Even older
+ ones did not pass a second argument at all, under any
+ circumstance. Note that upgrades using such an old dpkg
+ version are unlikely to work for other reasons, even if
+ this old argument behavior is handled by your postinst script.
+ </p>
+ </footnote>
</p>
</sect>
</item>
</enumlist>
- No attempt is made to unwind after errors during
- removal.
+ If there are problems during this process, we call
+ <example compact="compact">postinst
+ abort-remove</example>. No other attempt is made to unwind
+ after errors during removal.
</p>
</sect>
</chapt>
<p>
The package should install the shared libraries under
- their normal names. For example, the <package>libgdbmg1</package>
- package should install <file>libgdbm.so.1.7.3</file> as
- <file>/usr/lib/libgdbm.so.1.7.3</file>. The files should not be
+ their normal names. For example, the <package>libgdbm3</package>
+ package should install <file>libgdbm.so.3.0.0</file> as
+ <file>/usr/lib/libgdbm.so.3.0.0</file>. The files should not be
renamed or re-linked by any <prgn>prerm</prgn> or
<prgn>postrm</prgn> scripts; <prgn>dpkg</prgn> will take care
of renaming things safely without affecting running programs,
<p>
The run-time library package should include the symbolic link that
<prgn>ldconfig</prgn> would create for the shared libraries.
- For example, the <package>libgdbmg1</package> package should include
- a symbolic link from <file>/usr/lib/libgdbm.so.1</file> to
- <file>libgdbm.so.1.7.3</file>. This is needed so that the dynamic
+ For example, the <package>libgdbm3</package> package should include
+ a symbolic link from <file>/usr/lib/libgdbm.so.3</file> to
+ <file>libgdbm.so.3.0.0</file>. This is needed so that the dynamic
linker (for example <prgn>ld.so</prgn> or
<prgn>ld-linux.so.*</prgn>) can find the library between the
time that <prgn>dpkg</prgn> installs it and the time that
<p>
The development package should contain a symlink for the associated
shared library without a version number. For example, the
- <package>libgdbmg1-dev</package> package should include a symlink
+ <package>libgdbm-dev</package> package should include a symlink
from <file>/usr/lib/libgdbm.so</file> to
- <file>libgdbm.so.1.7.3</file>. This symlink is needed by the linker
+ <file>libgdbm.so.3.0.0</file>. This symlink is needed by the linker
(<prgn>ld</prgn>) when compiling packages, as it will only look for
<file>libgdbm.so</file> when compiling dynamically.
</p>
libraries, it must provide a <file>shlibs</file> file for other
packages to use, and when a package is built which contains
any shared libraries or compiled binaries, it must run
- <prgn>dpkg-shlibdeps</prgn> on these to determine the
- libraries used and hence the dependencies needed by this
- package.<footnote>
+ <qref id="pkg-dpkg-shlibdeps"><prgn>dpkg-shlibdeps</prgn></qref>
+ on these to determine the libraries used and hence the
+ dependencies needed by this package.<footnote>
<p>
In the past, the shared libraries linked to were
determined by calling <prgn>ldd</prgn>, but now
<p>
In the following sections, we will first describe where the
various <tt>shlibs</tt> files are to be found, then how to
- use <prgn>dpkg-shlibdeps</prgn>, and finally the
- <tt>shlibs</tt> file format and how to create them if your
- package contains a shared library.
+ use <prgn>dpkg-shlibdeps</prgn>, and finally the <tt>shlibs</tt>
+ file format and how to create them if your package contains a
+ shared library.
</p>
<sect1>
<p>
There are several places where <tt>shlibs</tt> files are
found. The following list gives them in the order in which
- they are read by <prgn>dpkg-shlibdeps</prgn>. (The first
- one which gives the required information is used.)
+ they are read by
+ <qref id="pkg-dpkg-shlibdeps"><prgn>dpkg-shlibdeps</prgn></qref>.
+ (The first one which gives the required information is used.)
</p>
<p>
<file>shlibs</file> files</heading>
<p>
- Put a call to <prgn>dpkg-shlibdeps</prgn> into your
- <file>debian/rules</file> file. If your package contains only
- compiled binaries and libraries (but no scripts), you can
- use a command such as:
+ Put a call to
+ <qref id="pkg-dpkg-shlibdeps"><prgn>dpkg-shlibdeps</prgn></qref>
+ into your <file>debian/rules</file> file. If your package
+ contains only compiled binaries and libraries (but no scripts),
+ you can use a command such as:
<example compact="compact">
dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \
debian/tmp/usr/lib/*
compiled libraries or binaries. In such a case, you will
need to use the <tt>-T</tt> option to the <tt>dpkg</tt>
utilities to specify a different <file>substvars</file> file.
- For more details on this and other options, see <manref
- name="dpkg-shlibdeps" section="1">.
+ </p>
+
+ <p>
+ For more details on dpkg-shlibdeps, please see
+ <ref id="pkg-dpkg-shlibdeps"> and
+ <manref name="dpkg-shlibdeps" section="1">.
</p>
</sect1>
Directly managing the /etc/rc?.d links and directly
invoking the <file>/etc/init.d/</file> initscripts should
be done only by packages providing the initscript
- subsystem (such as <prgn>sysvinit</prgn> and
+ subsystem (such as <prgn>sysv-rc</prgn> and
<prgn>file-rc</prgn>).
</p>
<action></example> in their <prgn>postinst</prgn>
and <prgn>prerm</prgn> scripts to:
<example compact="compact">
- if [ -x /usr/sbin/invoke-rc.d ] ; then
+ if command -v invoke-rc.d >/dev/null 2>&1; then
invoke-rc.d <var>package</var> <action>
- else
- /etc/init.d/<var>package</var> <action>
- fi
+ else
+ /etc/init.d/<var>package</var> <action>
+ fi
</example>
</p>
;;
restart)
echo -n "Restarting domain name service: named"
- start-stop-daemon --stop --quiet \
+ start-stop-daemon --stop --quiet --oknodo \
--pidfile /var/run/named.pid --exec /usr/sbin/named
start-stop-daemon --start --verbose --exec /usr/sbin/named \
-- $PARAMS
string</em> in some place, the following format should be
used: <var>arch</var>-<var>os</var><footnote>
The following architectures and operating systems are
- currently recognised by <prgn>dpkg-archictecture</prgn>.
+ currently recognised by <prgn>dpkg-architecture</prgn>.
The architecture, <tt><var>arch</var></tt>, is one of
the following: <tt>alpha</tt>, <tt>arm</tt>,
<tt>hppa</tt>, <tt>i386</tt>, <tt>ia64</tt>,
package.
</p>
- <sect1>
+ <sect1 id="pkg-dpkg-source">
<heading>
<prgn>dpkg-source</prgn> - packs and unpacks Debian source
packages
</sect1>
- <sect1>
+ <sect1 id="pkg-dpkg-buildpackage">
<heading>
<prgn>dpkg-buildpackage</prgn> - overall package-building
control script
</p>
</sect1>
- <sect1>
+ <sect1 id="pkg-dpkg-gencontrol">
<heading>
<prgn>dpkg-gencontrol</prgn> - generates binary package
control files
<prgn>dpkg-genchanges</prgn>.</p>
</sect1>
- <sect1>
+ <sect1 id="pkg-dpkg-shlibdeps">
<heading>
<prgn>dpkg-shlibdeps</prgn> - calculates shared library
dependencies
</p>
<p>
- For example, the <prgn>procps</prgn> package generates two
- kinds of binaries, simple C binaries like <prgn>ps</prgn>
- which require a predependency and full-screen ncurses
- binaries like <prgn>top</prgn> which require only a
- recommendation. It can say in its <file>debian/rules</file>:
+ For example, a package that generates an essential part
+ which requires dependencies, and optional parts that
+ which only require a recommendation, would separate those
+ two sets of dependencies into two different fields.<footnote>
+ At the time of writing, an example for this was the
+ <package/xmms/ package, with Depends used for the xmms
+ executable, Recommends for the plug-ins and Suggests for
+ even more optional features provided by unzip.
+ </footnote>
+ It can say in its <file>debian/rules</file>:
<example>
- dpkg-shlibdeps -dPre-Depends ps -dRecommends top
+ dpkg-shlibdeps -dDepends <var>program anotherprogram ...</var> \
+ -dRecommends <var>optionalpart anotheroptionalpart</var>
</example>
and then in its main control file <file>debian/control</file>:
<example>
<var>...</var>
- Package: procps
- Pre-Depends: ${shlibs:Pre-Depends}
+ Depends: ${shlibs:Pre-Depends}
Recommends: ${shlibs:Recommends}
<var>...</var>
</example>
</sect1>
- <sect1>
+ <sect1 id="pkg-dpkg-distaddfile">
<heading>
<prgn>dpkg-distaddfile</prgn> - adds a file to
<file>debian/files</file>
</sect1>
- <sect1><heading><prgn>dpkg-genchanges</prgn> - generates a <file>.changes</file> upload
- control file
+ <sect1 id="pkg-dpkg-genchanges">
+ <heading>
+ <prgn>dpkg-genchanges</prgn> - generates a <file>.changes</file>
+ upload control file
</heading>
<p>
</sect1>
- <sect1><heading><prgn>dpkg-parsechangelog</prgn> - produces parsed representation of
- a changelog
+ <sect1 id="pkg-dpkg-parsechangelog">
+ <heading>
+ <prgn>dpkg-parsechangelog</prgn> - produces parsed
+ representation of a changelog
</heading>
<p>
</p>
</sect1>
- <sect1 id="pkg-dpkgarch"><heading><prgn>dpkg-architecture</prgn> -
- information about the build and host system
+ <sect1 id="pkg-dpkg-architecture">
+ <heading>
+ <prgn>dpkg-architecture</prgn> - information about the build and
+ host system
</heading>
<p>
projects / debian / debian-policy.git / blobdiff