<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>
Those containing a single space followed by a single full stop
character. These are rendered as blank lines. This is the
<em>only</em> way to get a blank line<footnote>
- Completely empty lines will not be rendered as blank lines.
+ Completely empty lines will not be rendered as blank lines.
Instead, they will cause the parser to think you're starting
a whole new record in the control file, and will therefore
likely abort with an error.
<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>
they may not be installed at the same time as certain other
packages, and/or that they depend on the presence of others.
</p>
-
+
<p>
This is done using the <tt>Depends</tt>, <tt>Pre-Depends</tt>,
<tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt> and
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>
installed or absent at the time of building the package
can declare relationships to those binary packages.
</p>
-
+
<p>
This is done using the <tt>Build-Depends</tt>,
<tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt> and
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>,
maintainer of the package is allowed to write this bug report
themselves, if they so desire). Do not close the bug report
until a proper manpage is available.<footnote>
- It is not very hard to write a man page. See the
+ It is not very hard to write a man page. See the
<url id="http://www.schweikhardt.net/man_page_howto.html"
- name="Man-Page-HOWTO">,
+ name="Man-Page-HOWTO">,
<manref name="man" section="7">, the examples
created by <prgn>debmake</prgn> or <prgn>dh_make</prgn>,
the helper programs <prgn>help2man</prgn>, or the
See <ref id="dpkgchangelog">.
</p>
- <sect2><heading>Defining alternative changelog formats
+ <p>
+ It is recommended that the entire changelog be encoded in the
+ <url id="http://www.cis.ohio-state.edu/cgi-bin/rfc/rfc2279.html" name="UTF-8">
+ encoding of
+ <url id="http://www.unicode.org/"
+ name="Unicode">.<footnote>
+ <p>
+ Support for Unicode, and specifically UTF-8, is
+ steadily increasing among popular applications in
+ Debian. For example, in unstable, GNOME 2 has
+ excellent support (almost level 2) in almost all its
+ applications; the big remaining one is gnome-terminal,
+ of which one requires development versions in order to
+ support UTF-8 (available in Debian experimental now if
+ you want to play). I think that by the time sarge is
+ released, UTF-8 support will start to hit critical
+ mass. </p>
+ <p>
+ I think it is fairly obvious that we need to
+ eventually transition to UTF-8 for our package
+ infrastructure; it is really the only sane charset in
+ an international environment. Now, we can't switch to
+ using UTF-8 for package control fields and the like
+ until dpkg has better support, but one thing we can
+ start doing today is requesting that Debian changelogs
+ are UTF-8 encoded. At some point in time, we can start
+ requiring them to do so.
+ </p>
+ <p>
+ Checking for non-UTF8 characters in a changelog is
+ trivial. Dump the file through
+ <example>iconv -f utf-8 -t ucs-4</example>
+ discard the output, and check the return
+ value. If there are any characters in the stream
+ which are invalid UTF-8 sequences, iconv will exit
+ with an error code; and this will be the case for the
+ vast majority of other character sets.
+ </p>
+ </footnote>
+ </p>
+
+ <sect2><heading>Defining alternative changelog formats
</heading>
<p>
projects / debian / debian-policy.git / blobdiff