<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>.
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>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>,
<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>.
<tag><tt>required</tt></tag>
<item>
Packages which are necessary for the proper
- functioning of the system. You must not remove these
- packages or your system may become totally broken and
- you may not even be able to use <prgn>dpkg</prgn> to
- put things back. Systems with only the
- <tt>required</tt> packages are probably unusable, but
- they do have enough functionality to allow the
- sysadmin to boot and install more software.
+ functioning of the system (usually, this means that
+ dpkg functionality depends on these packages).
+ Removing an <tt>required</tt> package may cause your
+ system to become totally broken and you may not even
+ be able to use <prgn>dpkg</prgn> to put things back,
+ so only do so if you know what you are doing. Systems
+ with only the <tt>required</tt> packages are probably
+ unusable, but they do have enough functionality to
+ allow the sysadmin to boot and install more software.
</item>
<tag><tt>important</tt></tag>
<item>
<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>
<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
<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>
syntax is described above, in <ref id="pkg-controlfields">.
<list compact="compact">
+ <item><qref id="f-Format"><tt>Format</tt></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><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>
- In a <file>.changes</file> file the <tt>Architecture</tt>
+ 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>
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>
<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>
<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>
<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
instead.
</p>
+ <p>
+ If your package includes run-time support programs that
+ do not need to be invoked manually by users, but are
+ nevertheless required for the package to function, then it
+ is recommended that these programs are placed
+ (if they are binary) in a subdirectory of
+ <file>/usr/lib</file>, preferably under
+ <file>/usr/lib/</file><var>package-name</var>.
+ If the program is architecture independent, the
+ recommendation is for it to be placed in a subdirectory of
+ <file>/usr/share</file> instead, preferably under
+ <file>/usr/share/</file><var>package-name</var>.
+ </p>
+
+
<p>
If you have several shared libraries built from the same
source tree you may lump them all together into a single
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>
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>
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>sysv-rct</prgn> and
+ subsystem (such as <prgn>sysv-rc</prgn> and
<prgn>file-rc</prgn>).
</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 [ -x /usr/sbin/invoke-rc.d ] ; 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>
- fi
+ else
+ /etc/init.d/<var>package</var> <action>
+ fi
</example>
</p>
<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
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>,
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>
</example>
To view the copyright file for a package you could use this command:
<example>
- dpkg --fsys-tarfile <var>filename</var>.deb | tar xof usr/share/doc/<var>\*</var>copyright | less
+ dpkg --fsys-tarfile <var>filename</var>.deb | tar xO ./usr/share/doc/\*/copyright | pager
</example>
</p>
</sect>
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
<prgn>dpkg-source</prgn>, the <file>debian/rules</file>
targets <tt>clean</tt>, <tt>build</tt> and
<tt>binary</tt>, <prgn>dpkg-genchanges</prgn> and
- <prgn>pgp</prgn> to build a signed source and binary
- package upload.
+ <prgn>gpg</prgn> (or <prgn>pgp</prgn>) to build a signed
+ source and binary package upload.
</p>
<p>
<tag><tt>-uc</tt>, <tt>-us</tt></tag>
<item>
<p>
- Do not PGP-sign the <tt>.changes</tt> file or the
+ Do not sign the <tt>.changes</tt> file or the
source package <tt>.dsc</tt> file, respectively.</p>
</item>
- <tag><tt>-p<var>pgp-command</var></tt></tag>
+ <tag><tt>-p<var>sign-command</var></tt></tag>
<item>
<p>
- Invoke <var>pgp-command</var> instead of finding
- <tt>pgp</tt> on the <prgn>PATH</prgn>.
- <var>pgp-command</var> must behave just like
- <prgn>pgp</prgn>.</p>
+ Invoke <var>sign-command</var> instead of finding
+ <tt>
gpg</tt> or <tt>pgp</tt> on the <prgn>PATH</prgn>.
+ <var>sign-command</var> must behave just like
+ <prgn>gpg</prgn> or <tt>pgp</tt>.</p>
</item>
<tag><tt>-r<var>root-command</var></tt></tag>
<item>
</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>
</tag>
<item>
-
<p>
This is a compressed (with <tt>gzip -9</tt>)
<prgn>tar</prgn> file containing the source code from
- the upstream authors of the program. The tarfile
- unpacks into a directory
- <file><var>package</var>-<var>upstream-version</var>.orig</file>,
- and does not contain files anywhere other than in
- there or in its subdirectories.</p>
+ the upstream authors of the program.
+ </p>
</item>
<tag>
automatically make the <file>debian/rules</file> file
executable (see below).</p></item>
</taglist>
-
+ </p>
<p>
If there is no original source code - for example, if the
maintainer is the same as the upstream maintainer - the
format is slightly different: then there is no diff, and the
tarfile is named
- <file><var>package</var>_<var>version</var>.tar.gz</file> and
- contains a directory
+ <file><var>package</var>_<var>version</var>.tar.gz</file>,
+ and preferably contains a directory named
<file><var>package</var>-<var>version</var></file>.
</p>
</sect>
</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