<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>.
<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>
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>
package's <prgn>postrm</prgn> script will be run with a
special argument to allow the package to do any final
cleanup required. See <ref id="mscriptsinstact">.
- </p>
-
- <p>
- If an installed package, <tt>foo</tt> say, declares that
- it replaces another, <tt>bar</tt>, and an attempt is made
- to install <tt>bar</tt>, <prgn>dpkg</prgn> will discard
- files in the <tt>bar</tt> package which would overwrite
- those already present in <tt>foo</tt>. This is so that
- you can install an older version of a package without
- problems.
+ <footnote>
+ <p>
+ Replaces is a one way relationship -- you have to
+ install the replacing package after the replaced
+ package.
+ </p>
+ </footnote>
</p>
<p>
The <tt>Build-Depends-Indep</tt> and
<tt>Build-Conflicts-Indep</tt> fields must be
satisfied when any of the following targets is
- invoked: <tt>build</tt>, <tt>clean</tt>,
- <tt>build-indep</tt>, <tt>binary</tt> and
- <tt>binary-indep</tt>.
+ invoked: <tt>build</tt>, <tt>build-indep</tt>,
+ <tt>binary</tt> and <tt>binary-indep</tt>.
</item>
</taglist>
</p>
<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>
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-rct</prgn> and
<prgn>file-rc</prgn>).
</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
the library compatible with LinuxThreads.
</p>
+ <p>
+ Although not enforced by the build tools, shared libraries
+ must be linked against all libraries that they use symbols from
+ in the same way that binaries are. This ensures the correct
+ functioning of the <qref id="sharedlibs-shlibdeps">shlibs</qref>
+ system and guarantees that all libraries can be safely opened
+ with <tt>dlopen()</tt>. Packagers may wish to use the gcc
+ option <tt>-Wl,-z,defs</tt> when building a shared library.
+ Since this option enforces symbol resolution at build time,
+ a missing library reference will be caught early as a fatal
+ build error.
+ </p>
+
<p>
All installed shared libraries should be stripped with
<example compact="compact">
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>,