is the Debian Developer's Reference. This document describes
procedures and resources for Debian developers, but it is
<em>not</em> normative; rather, it includes things that don't
- belong into the Policy, such as best practices for developers.
+ belong in the Policy, such as best practices for developers.
</p>
<p>
<p>
Programs which use patented algorithms that have a
restricted license also need to be stored on "non-us",
- since that is located in a country where it is not allowed
- to patent algorithms.
+ since the non-us archive is located in a country where
+ patenting algorithms is not allowed.
</p>
<p>
<em>libs</em>, <em>libdevel</em>, <em>mail</em>,
<em>math</em>, <em>misc</em>, <em>net</em>, <em>news</em>,
<em>non-US</em>, <em>non-free</em>, <em>oldlibs</em>,
- <em>otherosfs</em>, <em>perl</em>, <em>python</em>
+ <em>otherosfs</em>, <em>perl</em>, <em>python</em>,
<em>science</em>, <em>shells</em>,
<em>sound</em>, <em>tex</em>, <em>text</em>,
<em>utils</em>, <em>web</em>, <em>x11</em>.
<p>
To prevent having to use epochs for every new upstream
- version, the version number should be changed to the
- following format in such cases: "19960501", "19961224". It
- is up to the maintainer whether he/she wants to bother the
- upstream maintainer to change the version numbers upstream,
- too.
+ version, the date based portion of the version number
+ should be changed to the following format in such cases:
+ "19960501", "19961224". It is up to the maintainer whether
+ they want to bother the upstream maintainer to change
+ the version numbers upstream, too.
</p>
<p>
The maintainer must be specified in the
<tt>Maintainer</tt> control field with their correct name
and a working email address. If one person maintains
- several packages, he/she should try to avoid having
+ several packages, they should try to avoid having
different forms of their name and email address in
the <tt>Maintainer</tt> fields of those packages.
</p>
package names can be found in the <tt>debian-policy</tt> package.
It is also available from the Debian web mirrors at
<tt><url name="/doc/packaging-manuals/virtual-package-names-list.txt"
- id="http://www.debian.org/doc/packaging-manuals/virtual-package-names-list.txt"></tt>
- and from the Debian archive mirrors at
- <tt><url name="/doc/package-developer/virtual-package-names-list.txt"
- id="http://ftp.debian.org/debian/doc/package-developer/virtual-package-names-list.txt"></tt>.
+ id="http://www.debian.org/doc/packaging-manuals/virtual-package-names-list.txt"></tt>.
</p>
<p>
<p>
The package installation scripts should avoid producing
- output which it is unnecessary for the user to see and
+ output which is unnecessary for the user to see and
should rely on <prgn>dpkg</prgn> to stave off boredom on
the part of a user installing many packages. This means,
amongst other things, using the <tt>--quiet</tt> option on
<package>debian-policy</package> package.
It is also available from the Debian web mirrors at
<tt><url name="/doc/packaging-manuals/debconf_specification.html"
- id="http://www.debian.org/doc/packaging-manuals/debconf_specification.html"></tt>
- and from the Debian archive mirrors at
- <tt><url name="/doc/package-developer/debconf_specification.txt.gz"
- id="http://ftp.debian.org/debian/doc/package-developer/debconf_specification.txt.gz"></tt>.
+ id="http://www.debian.org/doc/packaging-manuals/debconf_specification.html"></tt>.
</p>
<p>
</p>
<p>
- If you need to edit a <prgn>Makefile</prgn> where
- GNU-style <prgn>configure</prgn> scripts are used, you
- should edit the <file>.in</file> files rather than editing the
+ If you need to edit a <prgn>Makefile</prgn> where GNU-style
+ <prgn>configure</prgn> scripts are used, you should edit the
+ <file>.in</file> files rather than editing the
<prgn>Makefile</prgn> directly. This allows the user to
reconfigure the package if necessary. You should
<em>not</em> configure the package and edit the generated
- <prgn>Makefile</prgn>! This makes it impossible for
- someone else to later reconfigure the package.
+ <prgn>Makefile</prgn>! This makes it impossible for someone
+ else to later reconfigure the package without losing the
+ changes you made.
</p>
</sect>
<p>
Changes in the Debian version of the package should be
briefly explained in the Debian changelog file
- <file>debian/changelog</file>. This includes modifications
+ <file>debian/changelog</file>.<footnote>
+ <p>
+ Mistakes in changelogs are usually best rectified by
+ making a new changelog entry rather than "rewriting
+ history" by editing old changelog entries.
+ </p>
+ </footnote>
+ This includes modifications
made in the Debian package compared to the upstream one
as well as other changes and updates to the package.
<footnote>
</p>
<p>
- Mistakes in changelogs are usually best rectified by making
- a new changelog entry rather than "rewriting history" by
- editing old changelog entries.
+
</p>
<p>
contact the <package>dpkg</package> maintainer to have the
parser script for it included in the <prgn>dpkg</prgn>
package. (You will need to agree that the parser and its
- manpage may be distributed under the GNU GPL, just as the rest
+ man page may be distributed under the GNU GPL, just as the rest
of <prgn>dpkg</prgn> is.)
</footnote>
</p>
<list compact="compact">
<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-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-Source"><tt>Source</tt></qref> (mandatory)</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-Binary"><tt>Binary</tt></qref></item>
<item><qref id="f-Architecture"><tt>Architecture</tt></qref></item>
<item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
</p>
</sect1>
+ <sect1 id="f-Uploaders">
+ <heading><tt>Uploaders</tt></heading>
+
+ <p>
+ List of the names and email addresses of
+ co-maintaintainers of the package, if any. If the package
+ has other maintainers beside the one named in the <qref
+ id="f-Maintainer">Maintainer field</qref>, they their
+ names and email addresses should be listed here. The
+ format is the same as that of the Maintainer tag, and
+ multiple entries should be comma separated. This is an
+ optional field.
+ </p>
+ </sect1>
+
<sect1 id="f-Changed-By">
<heading><tt>Changed-By</tt></heading>
<heading>Package interrelationship fields:
<tt>Depends</tt>, <tt>Pre-Depends</tt>,
<tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Conflicts</tt>,
- <tt>Provides</tt>, <tt>Replaces</tt>
+ <tt>Provides</tt>, <tt>Replaces</tt>, <tt>Enhances</tt>
</heading>
<p>
<example compact="compact">
<var>new-preinst</var> upgrade <var>old-version</var>
</example>
+
+ <example>
+<var>new-postrm</var> abort-upgrade <var>old-version</var>
+ </example>
+ If that too fails, then
+ <example>
+<var>old-postinst</var> abort-upgrade <var>old-version</var>
+ </example>
+ is called.
</item>
<item>
Otherwise, if the package had some configuration
<example compact="compact">
<var>new-preinst</var> install <var>old-version</var>
</example>
+ Error unwind:
+ <example>
+<var>new-postrm</var> abort-install <var>old-version</var>
+ </example>
</item>
<item>
Otherwise (i.e., the package was completely purged):
<example compact="compact">
<var>new-preinst</var> install
- </example>
- Error unwind actions, respectively:
- <example compact="compact">
-<var>new-postrm</var> abort-upgrade <var>old-version</var>
-<var>new-postrm</var> abort-install <var>old-version</var>
+ </example>
+ Error unwind:
+ <example compact="compact">
<var>new-postrm</var> abort-install
- </example>
+ </example>
</item>
- </enumlist>
+ </enumlist>
</item>
<item>
<heading>Run-time shared libraries</heading>
<p>
- The run-time shared library needs to be placed in a package called
- <package><var>libraryname</var><var>soversion</var></package>, where
- <file><var>soversion</var></file> is the version number in the
- soname of the shared library<footnote>
+ The run-time shared library needs to be placed in a package
+ whose name changes whenever the shared object version
+ changes.<footnote>
+ <p>
+ Since it is common place to install several versions of a
+ package that just provides shared libraries, it is a
+ good idea that that the library package should not
+ contain any extraneous non-versioned files, unless they
+ happen to be in versioned directories.</p>
+ </footnote>
+ The most common mechanism is to place it in a package
+ called
+ <package><var>libraryname</var><var>soversion</var></package>,
+ where <file><var>soversion</var></file> is the version number
+ in the soname of the shared library<footnote>
The soname is the shared object name: it's the thing
that has to match exactly between building an executable
and running it for the dynamic linker to be able run the
<package><var>libraryname</var>-<var>soversion</var>-dev</package>
instead.
</p>
-
<p>
If you have several shared libraries built from the same
source tree you may lump them all together into a single
the scripts to the local system, e.g., to disable a
service without de-installing the package, or to specify
some special command line options when starting a service,
- while making sure her changes aren't lost during the next
+ while making sure their changes aren't lost during the next
package upgrade.
</p>
<p>
For more information about using <tt>update-rc.d</tt>,
- please consult its manpage <manref name="update-rc.d"
+ please consult its man page <manref name="update-rc.d"
section="8">.
</p>
</sect2>
<action></example> in their <prgn>postinst</prgn>
and <prgn>prerm</prgn> scripts to:
<example compact="compact">
- if command -v invoke-rc.d >/dev/null 2>&1; then
+ if which invoke-rc.d >/dev/null 2>&1; then
invoke-rc.d <var>package</var> <action>
else
/etc/init.d/<var>package</var> <action>
<p>
For more information about using
- <prgn>invoke-rc.d</prgn>, please consult its manpage
+ <prgn>invoke-rc.d</prgn>, please consult its man page
<manref name="invoke-rc.d" section="8">.
</p>
</sect2>
</p>
<p>
- Here is a list of overall rules that you should use when you
- create output messages. They can be useful if you have a
- non-standard message that is not covered specifically in the
- sections below.
+ Here is a list of overall rules that should be used for
+ messages generated by <file>/etc/init.d</file> scripts.
</p>
<p>
<list>
<item>
- Every message should fit in one line (fewer than 80
+ The message should fit in one line (fewer than 80
characters), start with a capital letter and end with
a period (<tt>.</tt>) and line feed (<tt>"\n"</tt>).
</item>
<item>
- If you want to express that the computer is working on
- something (that is, performing a specific task, not
- starting or stopping a program), we use an "ellipsis"
- (three dots: <tt>...</tt>). Note that we don't insert
- spaces before or after the dots. If the task has been
- completed we write <tt>done.</tt> and a line feed.
+ If the script is performing some time consuming task in
+ the background (not merely starting or stopping a
+ program, for instance), an ellipsis (three dots:
+ <tt>...</tt>) should be output to the screen, with no
+ leading or tailing whitespace or line feeds.
</item>
<item>
- Design your messages as if the computer is telling you
- what he is doing (let him be polite :-), but don't
- mention "him" directly. For example, if you think of
- saying
+ The messages should appear as if the computer is telling
+ the user what it is doing (politely :-), but should not
+ mention "it" directly. For example, instead of:
<example compact="compact">
I'm starting network daemons: nfsd mountd.
</example>
- just say
+ the message should say
<example compact="compact">
Starting network daemons: nfsd mountd.
</example>
</p>
<p>
- There are standard message formats for the following
- situations. They should be used by the <tt>init.d</tt>
- scripts.
+ <tt>init.d</tt> script should use the following standard
+ message formats for the situations enumerated below.
</p>
<p>
<p>When daemons are started</p>
<p>
- If your script starts one or more daemons, the output
+ If the script starts one or more daemons, the output
should look like this (a single line, no leading
spaces):
<example compact="compact">
start-stop-daemon --start --quiet --exec /usr/sbin/lpd
echo "."
</example>
- in the script. If you have more than one daemon to
- start, you should do the following:
+ in the script. If there are more than one daemon to
+ start, the output should look like this:
<example compact="compact">
echo -n "Starting remote file system services:"
echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
echo "."
</example>
- This makes it possible for the user to see what takes
- so long and when the final daemon has been started.
- You should be careful where to put spaces: in the
- example above the system administrator can easily
- comment out a line if he don't wants to start a
- specific daemon, while the displayed message still
+ This makes it possible for the user to see what is
+ happening and when the final daemon has been started.
+ Care should be taken in the placement of white spaces:
+ in the example above the system administrators can
+ easily comment out a line if they don't want to start
+ a specific daemon, while the displayed message still
looks good.
</p>
</item>
</example>
You should print the <tt>done.</tt> immediately after
the job has been completed, so that the user is
- informed why she has to wait. You can get this
+ informed why they have to wait. You can get this
behavior by saying
<example compact="compact">
echo -n "Doing something very useful..."
<p>
The Debian <tt>menu</tt> package provides a standard
interface between packages providing applications and
- documents, and <em>menu programs</em> (either X window
- managers or text-based menu programs such as
- <prgn>pdmenu</prgn>).
+ <em>menu programs</em> (either X window managers or
+ text-based menu programs such as <prgn>pdmenu</prgn>).
</p>
<p>
files in the <tt>debian-policy</tt> package.
It is also available from the Debian web mirrors at
<tt><url name="/doc/packaging-manuals/menu-policy/"
- id="http://www.debian.org/doc/packaging-manuals/menu-policy/"></tt>
- and from the Debian archive mirrors at
- <tt><url name="/doc/package-developer/menu-policy.txt.gz"
- id="http://ftp.debian.org/debian/doc/package-developer/menu-policy.txt.gz"></tt>.
+ id="http://www.debian.org/doc/packaging-manuals/menu-policy/"></tt>.
</p>
<p>
Please also refer to the <em>Debian Menu System</em>
- documentation that comes with the <tt>menu</tt> package for
- information about how to register your applications and web
- documents.
+ documentation that comes with the <package>menu</package>
+ package for information about how to register your
+ applications.
</p>
</sect>
files in the <tt>debian-policy</tt> package.
It is also available from the Debian web mirrors at
<tt><url name="/doc/packaging-manuals/mime-policy/"
- id="http://www.debian.org/doc/packaging-manuals/mime-policy/"></tt>
- and from the Debian archive mirrors at
- <tt><url name="/doc/package-developer/mime-policy.txt.gz"
- id="http://ftp.debian.org/debian/doc/package-developer/mime-policy.txt.gz"></tt>.
+ id="http://www.debian.org/doc/packaging-manuals/mime-policy/"></tt>.
</p>
</sect>
</p>
</sect>
+ <sect id="doc-base">
+ <heading>Registering Documents using doc-base</heading>
+
+ <p>
+ The <package>doc-base</package> package implements a
+ flexible mechanism for handling and presenting
+ documentation. The recommended practice is for every Debian
+ package that provides online documentation (other than just
+ manual pages) to register these documents with
+ <package>doc-base</package> by installing a
+ <package>doc-base</package> control file via the
+ <prgn/install-docs/ script at installation time and
+ de-register the manuals again when the package is removed.
+ </p>
+ <p>
+ Please refer to the documentation that comes with the
+ <package>doc-base</package> package for information and
+ details.
+ </p>
+ </sect>
+
</chapt>
<prgn>csh</prgn> and <prgn>tcsh</prgn> should be avoided as
scripting languages. See <em>Csh Programming Considered
Harmful</em>, one of the <tt>comp.unix.*</tt> FAQs, which
- can be found at <url id="http://language.perl.com/versus/csh.whynot">.
+ can be found at <url id="http://www.faqs.org/faqs/unix-faq/shell/csh-whynot/">.
If an upstream package comes with <prgn>csh</prgn> scripts
then you must make sure that they start with
<tt>#!/bin/csh</tt> and make your package depend on the
If a system administrator wishes to have a file (or
directory or other such thing) installed with owner and
permissions different from those in the distributed Debian
- package,
he can use the <prgn>dpkg-statoverride</prgn>
+ package,
they can use the <prgn>dpkg-statoverride</prgn>
program to instruct <prgn>dpkg</prgn> to use the different
settings every time the file is installed. Thus the
package maintainer should distribute the files with their
program to edit or display a text document. Since there are
lots of different editors and pagers available in the Debian
distribution, the system administrator and each user should
- have the possibility to choose his/her preferred editor and
+ have the possibility to choose their preferred editor and
pager.
</p>
the Web Document Root. Instead they should use the
/usr/share/doc/<var>package</var> directory for
documents and register the Web Application via the
- menu package. If access to the web document root is
- unavoidable then use
+ <package>doc-base</package> package. If access to the
+ web document root is unavoidable then use
<example compact="compact">
/var/www
</example>
<item>
If the window manager complies with <url
- id="http://www.freedesktop.org/standards/wm-spec.html"
+ id="http://www.freedesktop.org/Standards/wm-spec"
name="The Window Manager Specification Project">,
written by the <url id="http://www.freedesktop.org/"
name="Free Desktop Group">, add 40 points.
binaries linked against the library (whether statically or
dynamically), it is the package maintainer's
responsibility to determine whether this is permitted by
- the license of the copy of Motif in his or her possession.
+ the license of the copy of Motif in their possession.
</p>
</sect1>
</sect>
files in the <tt>debian-policy</tt> package.
It is also available from the Debian web mirrors at
<tt><url name="/doc/packaging-manuals/perl-policy/"
- id="http://www.debian.org/doc/packaging-manuals/perl-policy/"></tt>
- and from the Debian archive mirrors at
- <tt><url name="/doc/package-developer/perl-policy.txt.gz"
- id="http://ftp.debian.org/debian/doc/package-developer/perl-policy.txt.gz"></tt>.
+ id="http://www.debian.org/doc/packaging-manuals/perl-policy/"></tt>.
</p>
</sect>
and should be reported to the Debian Bug Tracking System (the
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>
+ until a proper man page is available.<footnote>
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">,
</p>
<p>
- You may forward a complaint about a missing manpage to the
+ You may forward a complaint about a missing man page to the
upstream authors, and mark the bug as forwarded in the
Debian bug tracking system. Even though the GNU Project do
- not in general consider the lack of a manpage to be a bug,
+ not in general consider the lack of a man page to be a bug,
we do; if they tell you that they don't consider it a bug
you should leave the bug in our bug tracking system open
anyway.
</p>
<p>
- If one manpage needs to be accessible via several names it
+ If one man page needs to be accessible via several names it
is better to use a symbolic link than the <file>.so</file>
feature, but there is no need to fiddle with the relevant
parts of the upstream source to change from <file>.so</file> to
symlinks: don't do it unless it's easy. You should not
create hard links in the manual page directories, nor put
absolute filenames in <file>.so</file> directives. The filename
- in a <file>.so</file> in a manpage should be relative to the
- base of the manpage tree (usually
+ in a <file>.so</file> in a man page should be relative to the
+ base of the man page tree (usually
<file>/usr/share/man</file>). If you do not create any links
(whether symlinks, hard links, or <tt>.so</tt> directives)
- in the filesystem to the alternate names of the manpage,
+ in the filesystem to the alternate names of the man page,
then you should not rely on <prgn>man</prgn> finding your
- manpage under those names based solely on the information in
- the manpage's header.<footnote>
+ man page under those names based solely on the information in
+ the man page's header.<footnote>
Supporting this in <prgn>man</prgn> often requires
unreasonable processing time to find a manual page or to
report that none exists, and moves knowledge into man's
<file>/usr/share/doc/<var>package</var></file> may be a symbolic
link to another directory in <file>/usr/share/doc</file> only if
the two packages both come from the same source and the
- first package Depends on the second.
+ first package Depends on the second.<footnote>
+ <p>
+ Please note that this does not override the section on
+ changelog files below, so the file
+ <file>/usr/share/<var>package</var>/changelog.Debian.gz</file>
+ must refer to the changelog for the current version of
+ <var>package</var> in question. In practice, this means
+ that the sources of the target and the destnation of the
+ symlink must be the same (same source package and
+ version).
+ </p>
+ </footnote>
</p>
<p>
This manual does not go into detail about the options and
usage of the package building and installation tools. It
should therefore be read in conjuction with those programs'
- manpages.
+ man pages.
</p>
<p>
for managing various system configuration and similar issues,
such as <prgn>update-rc.d</prgn> and
<prgn>install-info</prgn>, are not described in detail here -
- please see their manpages.
+ please see their man pages.
</p>
<p>
In the future binary packages may also contain other
components, such as checksums and digital signatures. The
format for the archive is described in full in the
- <file>deb(5)</file> manpage.
+ <file>deb(5)</file> man page.
</p>
</p>
<p>
- See the manpage <manref name="dpkg-deb" section="8"> for details of how
+ See the man page <manref name="dpkg-deb" section="8"> for details of how
to examine the contents of this newly-created file. You may find the
output of following commands enlightening:
<example>
</p>
<p>
- See the manpage <manref name="update-alternatives"
+ See the man page <manref name="update-alternatives"
section="8"> for details.
</p>
projects / debian / debian-policy.git / blobdiff