<!entity % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!entity cvs-rev "$Revision: 1.147 $">
+ <!entity cvs-rev "$Revision: 1.150 $">
<!-- if you are translating this document, please notate the CVS
revision of the developers reference here -->
<!--
(see <ref id="collaborative-maint">).
- <sect id="porting">Porting and Being Ported
+ <sect id="porting">Porting and being ported
<p>
Debian supports an ever-increasing number of architectures. Even if
you are not a porter, and you don't use any architecture but one, it
blessing or status, so buyer, beware.
- <sect1>Tools for porters
- <p>
-There are several tools available for the porting effort. This section
-contains a brief introduction to these tools; see the package
-documentation or references for full information.
-
-
- <sect2 id="quinn-diff">
- <heading><package>quinn-diff</package>
- <p>
-<package>quinn-diff</package> is used to locate the differences from
-one architecture to another. For instance, it could tell you which
-packages need to be ported for architecture <var>Y</var>, based on
-architecture <var>X</var>.
-
-
- <sect2 id="buildd">
- <heading><package>buildd</package>
- <p>
+ <sect1 id="porter-automation">
+ <heading>Porting infrastructure and automation</heading>
+ <p>
+There is infrastructure and several tools to help automate the package
+porting. This section contains a brief overview of this automation and
+portingto these tools; see the package documentation or references for
+full information.</p>
+
+ <sect2>
+ <heading>Mailing lists and web pages</heading>
+ <p>
+Web pages containing the status of each port can be found at <url
+id="&url-debian-ports;">.
+ <p>
+Each port of Debian has a mailing list. The list of porting mailing
+lists can be found at <url id="&url-debian-port-lists;">. These lists
+are used to coordinate porters, and to connect the users of a given
+port with the porters.</p>
+ </sect2>
+
+ <sect2>
+ <heading>Porter tools</heading>
+ <p>
+Descriptions of several porting tools can be found in <ref
+id="tools-porting">.</p>
+ </sect2>
+
+ <sect2 id="buildd">
+ <heading><package>buildd</package></heading>
+ <p>
The <package>buildd</package> system is used as a distributed,
client-server build distribution system. It is usually used in
conjunction with <em>auto-builders</em>, which are ``slave'' hosts
<p>
<package>buildd</package> is not yet available as a package; however,
most porting efforts are either using it currently or planning to use
-it in the near future. It collects a number of as yet unpackaged
+it in the near future. The actual automated builder is packaged as
+<package>sbuild</package>, see its description in <ref id="sbuild">.
+The complete <package>buildd</package> system also collects a number of as yet unpackaged
components which are currently very useful and in use continually,
-such as <prgn>andrea</prgn>, <prgn>sbuild</prgn> and
+such as <prgn>andrea</prgn> and
<prgn>wanna-build</prgn>.
<p>
Some of the data produced by <package>buildd</package> which is
from <prgn>andrea</prgn> (source dependencies) and
<package>quinn-diff</package> (packages needing recompilation).
<p>
-We are very excited about this system, since it potentially has so
-many uses. Independent development groups can use the system for
+We are quite proud of this system, since it has so
+many possible uses. Independent development groups can use the system for
different sub-flavors of Debian, which may or may not really be of
-general interest (for instance, a flavor of Debian built with gcc
+general interest (for instance, a flavor of Debian built with <prgn>gcc</prgn>
bounds checking). It will also enable Debian to recompile entire
distributions quickly.
+ </sect2>
- <sect2 id="dpkg-cross">
- <heading><package>dpkg-cross</package>
- <p>
-<package>dpkg-cross</package> is a tool for installing libraries and
-headers for cross-compiling in a way similar to
-<package>dpkg</package>. Furthermore, the functionality of
-<prgn>dpkg-buildpackage</prgn> and <prgn>dpkg-shlibdeps</prgn> is
-enhanced to support cross-compiling.
-
<sect id="collaborative-maint">
<heading>Collaborative maintenance</heading>
</sect>
<sect id="archive-manip">
- <heading>Moving, Removing, Renaming, Adopting, and Orphaning
- Packages</heading>
+ <heading>Moving, removing, renaming, adopting, and orphaning
+ packages</heading>
<p>
Some archive manipulation operations are not automated in the Debian
upload process. These procedures should be manually followed by
best for you.
<sect id="bpp-debian-rules">
- <heading>Best Practices for <file>debian/rules</file></heading>
+ <heading>Best practices for <file>debian/rules</file></heading>
<p>
The following recommendations apply to the <file>debian/rules</file>
file. Since <file>debian/rules</file> controls the build process and
</sect1>
</sect>
+ <sect id="bpp-debian-maint-scripts">
+ <heading>Best practices for maintainer scripts</heading>
+ <p>
+Maintainer scripts include the files <file>debian/postinst</file>,
+<file>debian/preinst</file>, <file>debian/prerm</file> and
+<file>debian/postrm</file>. These scripts take care of any package
+installation or deinstallation setup which isn't handled merely by the
+creation or removal of files and directories. The following
+instructions supplement the <url id="&url-debian-policy;" name="Debian
+Policy">.
+ <p>
+Maintainer scripts must be idempotent. That means that you need to
+make sure nothing bad will happen if the script is called twice where
+it would usually be called once.
+ <p>
+Standard input and output may be redirected (e.g. into pipes) for
+logging purposes, so don't rely on them being a tty.
+ <p>
+All prompting or interactive configuration should be kept to a
+minimum. When it is necessary, you should use the
+<package>debconf</package> package for the interface. Remember that
+prompting in any case can only be in the <tt>configure</tt> stage of
+the <file>postinst</file> script.
+ <p>
+Keep the maintainer scripts as simple as possible. We suggest you use
+pure POSIX shell scripts. Remember, if you do need any bash features,
+the maintainer script must have a bash shbang line. Posix shell or
+Bash are preferred to Perl, since they enable
+<package>debhelper</package> to easily add bits to the scripts.
+ <p>
+If you change your maintainer scripts, be sure to test package
+removal, double installation, and purging. Be sure that a purged
+package is completely gone, that is, it must remove any files created,
+directly or indirectly, in any maintainer script.
+ <p>
+If you need to check for the existance of a command, you should use
+something like
+<example>if [ -x /usr/sbin/install-docs ]; then ...</example>
+
+If you don't wish to hardcode the path of the command in your
+maintainer script, the following POSIX-compliant shell function may
+help:
+
+&example-pathfind;
+
+You can use this function to search <tt>$PATH</tt> for a command name,
+passed as an argument. It returns true (zero) if the command was
+found, and false if not. This is really the most portable way, since
+<tt>command -v</tt>, <prgn>type</prgn>, and <prgn>which</prgn> are not
+POSIX. While <prgn>which</prgn> is an acceptable alternative, since
+it is from the required <package>debianutils</package> package, it's
+not on the root partition, although that is probably not something
+that will cause a problem.
+
+
+ <sect id="bpp-debian-control">
+ <heading>Best practices for <file>debian/control</file></heading>
+ <p>
+The following practices supplement the <url
+ id="&url-debian-policy;ch-miscellaneous.html#s-descriptions"
+ name="Policy on package descriptions">.</p>
+
+ <sect1 id="bpp-pkg-desc">
+ <heading>Writing useful descriptions</heading>
+ <p>
+The description of the package (as defined by the corresponding field
+in the <file>control</file> file) is the primary information available
+to the user about a package before they install it. It should provide
+all the required information to let the user decide whether to install
+the package.
+ <p>
+For consistency and aesthetics, you should capitalize the first letter
+of the Synopsis. Don't put a full stop (period) at the end. The
+description itself should consist of full sentences.
+ <p>
+Since the first user impression is based on the description, be
+careful to avoid spelling and grammar mistakes. Ensure that you
+spell-check it. <prgn>ispell</prgn> has a special <tt>-g</tt> option
+for <file>debian/control</file> files:
+
+<example>ispell -d american -g debian/control</example>
+
+If you want someone to proofread the description that you
+intend to use you may ask on &email-debian-l10n-english;.
+ </sect1>
+
+ <sect1 id="bpp-upstream-info">
+ <heading>Upstream home page</heading>
+ <p>
+We recommend that you add the URL for the package's homepage to the
+package description in <file>debian/control</file>, and a link to a
+screenshot, if one is handy. This information should be added at the
+end of description, using the following format:
+
+<example> .
+ Homepage: http://some-project.some-place.org/
+ Screenshot: http://some-project.some-place.org/</example>
+
+Note the spaces prepending the line, which serves to break the lines
+correctly. To see an example of how this displays, see <url
+id="&url-eg-desc-upstream-info;">.
+ <p>
+If there is no home page for the software, this should naturally be
+left empty.
+ </sect1>
+ </sect>
+
<!--
<sect1 id="pkg-mgmt-cvs">Managing a package with CVS
<p>
via CVS (debian/rules refresh).
-->
+
<sect id="bpp-config-mgmt">
<heading>Configuration management with <package>debconf</package></heading>
</sect1>
<sect1 id="bpp-i18n-docs">
- <heading>Internationalized Documentation</heading>
+ <heading>Internationalized documentation</heading>
<p>
Internationalizing documentation is crucial for users, but a lot of
labor. There's no way to eliminate all that work, but you can make things
sympa may be an example package
-->
- <sect id="misc-advice">
- <heading>Miscellaneous advice</heading>
-
- <sect1 id="writing-desc">
- <heading>Writing useful descriptions</heading>
- <p>
-The description of the package (as defined by the corresponding field
-in the <file>control</file> file) is the primary information available
-to the user about a package before they install it. It should provide
-all the required information to let the user decide whether to install
-the package.
- <p>
-For example, apart from the usual description that you might adapt
-from the upstream <file>README</file>, you should include the URL of
-the web site if there's any. If the package is not yet considered
-stable by the author, you may also want to warn the user that the
-package is not ready for production use.
- <p>
-For consistency and aesthetics, you should capitalize the first letter
-of the description. Don't put a full stop (period) at the end.
- <p>
-Since the first user impression is based on the description, be
-careful to avoid spelling and grammar mistakes. Ensure that you
-spell-check it. <prgn>ispell</prgn> has a special <tt>-g</tt> option
-for <file>debian/control</file> files:
-
-<example>ispell -d american -g debian/control</example>
-
-If you want someone to proofread the description that you
-intend to use you may ask on &email-debian-l10n-english;.
the most critical thing to spend their time on.
<sect id="submit-bug">
- <heading>Bug Reporting</heading>
+ <heading>Bug reporting</heading>
<p>
We encourage you to file bugs as you find them in Debian packages. In
fact, Debian developers are often the first line testers. Finding and
for help on &email-debian-qa; or &email-debian-devel;). At the same
time, you can look for co-maintainers (see <ref id="collaborative-maint">).
- <sect1 id="qa-bsp">Bug Squashing Parties
+ <sect1 id="qa-bsp">Bug squashing parties
<p>
From time to time the QA group organizes bug squashing parties to get rid of
as many problems as possible. They are announced on &email-debian-devel-announce;
Most of the descriptions of these packages come from the actual
package descriptions themselves. Further information can be found in
the package documentation itself. You can also see more info with the
-command <tt>apt-cache show <package-name></tt>.
+command <tt>apt-cache show <package-name></tt>.</p>
+ <sect id="tools-core">
+ <heading>Core tools</heading>
+ <p>
+The following tools are pretty much required for any maintainer.</p>
- <sect id="dpkg-dev">
+ <sect1 id="dpkg-dev">
<heading><package>dpkg-dev</package>
<p>
<package>dpkg-dev</package> contains the tools (including
functionality required to create and manipulated packages; as such,
they are required for any Debian maintainer.
+ <sect1 id="debconf">
+ <heading><package>debconf</package></heading>
+ <p>
+<package>debconf</package> provides a consistent interface to
+configuring packages interactively. It is user interface
+independent, allowing end-users to configure packages with a
+text-only interface, an HTML interface, or a dialog interface. New
+interfaces can be added modularly.
+ <p>
+You can find documentation for this package in the
+<package>debconf-doc</package> package.
+ <p>
+Many feel that this system should be used for all packages requiring
+interactive configuration; see <ref id="bpp-config-mgmt">.
+<package>debconf</package> is not currently required by Debian Policy,
+but that may change in the future.
+ </sect1>
- <sect id="lintian">
- <heading><package>lintian</package>
+ <sect1 id="fakeroot">
+ <heading><package>fakeroot</package>
<p>
-<package>Lintian</package> dissects Debian packages and reports bugs
+<package>fakeroot</package> simulates root privileges. This enables
+you to build packages without being root (packages usually want to
+install files with root ownership). If you have
+<package>fakeroot</package> installed, you can build packages as a
+user: <tt>dpkg-buildpackage -rfakeroot</tt>.
+ </sect1>
+ </sect>
+
+ <sect id="tools-lint">
+ <heading>Package lint tools</heading>
+ <p>
+According to the Free On-line Dictionary of Computing (FOLDOC), `lint'
+is "a Unix C language processor which carries out more thorough checks
+on the code than is usual with C compilers." Package lint tools help
+package maintainers by automatically finding common problems and
+policy violations with their packages.</p>
+
+ <sect1 id="lintian">
+ <heading><package>lintian</package></heading>
+ <p>
+<package>lintian</package> dissects Debian packages and emits
+information on bugs
and policy violations. It contains automated checks for many aspects
of Debian policy as well as some checks for common errors.
<p>
packages at <url id="&url-lintian;">. Those reports contain the latest
<prgn>lintian</prgn> output on the whole development distribution
("unstable").
+ </sect1>
+ <sect1 id="linda">
+ <heading><package>linda</package></heading>
+ <p>
+<package>linda</package> is another package linter. It is similar to
+<package>lintian</package> but has a different set of checks. Its
+written in Python rather than Perl.</p>
+ </sect1>
+ </sect>
- <sect id="debconf">
- <heading><package>debconf</package></heading>
- <p>
-<package>debconf</package> provides a consistent interface to
-configuring packages interactively. It is user interface
-independent, allowing end-users to configure packages with a
-text-only interface, an HTML interface, or a dialog interface. New
-interfaces can be added modularly.
- <p>
-You can find documentation for this package in the
-<package>debconf-doc</package> package.
- <p>
-Many feel that this system should be used for all packages requiring
-interactive configuration. <package>debconf</package> is not
-currently required by Debian Policy, however, that may change in the
-future.
- <p>
-
+ <sect id="tools-helpers">
+ <heading>Helpers for <file>debian/rules</file></heading>
+ <p>
+Package building tools make the process of writing
+<file>debian/rules</file> files easier. See <ref id="helper-scripts">
+for more information on why these might or might not be desired.
- <sect id="debhelper">
- <heading><package>debhelper</package>
+ <sect1 id="debhelper">
+ <heading><package>debhelper</package></heading>
<p>
<package>debhelper</package> is a collection of programs that can be
used in <file>debian/rules</file> to automate common tasks related to
There are a number of little <package>debhelper</package> add-on
packages, too transient to document. You can see the list of most of
them by doing <tt>apt-cache search ^dh-</tt>.
+ </sect1>
-
- <sect id="debmake">
- <heading><package>debmake</package>
+ <sect1 id="debmake">
+ <heading><package>debmake</package>
<p>
<package>debmake</package>, a pre-cursor to
<package>debhelper</package>, is a less granular
The consensus is that <package>debmake</package> is now deprecated in
favor of <package>debhelper</package>. However, it's not a bug to use
<package>debmake</package>.
+ </sect1>
-
- <sect id="dh-make">
- <heading><package>dh-make</package>
+ <sect1 id="dh-make">
+ <heading><package>dh-make</package>
<p>
The <package/dh-make/ package contains <prgn/dh_make/, a program that
creates a skeleton of files necessary to build a Debian package out of
sufficient basis for a working package, they are still just the groundwork:
the burden still lies on the maintainer to finely tune the generated files
and make the package entirely functional and Policy-compliant.
+ </sect1>
-
- <sect id="yada">
- <heading><package>yada</package>
+ <sect1 id="yada">
+ <heading><package>yada</package>
<p>
<package>yada</package> is another packaging helper tool. It uses a
<file>debian/packages</file> file to auto-generate
Note that <package>yada</package> is called "essentially unmaintained"
by it's own maintainer, Charles Briscoe-Smith. As such, it can be
considered deprecated.
+ </sect1>
-
- <sect id="equivs">
- <heading><package>equivs</package>
+ <sect1 id="equivs">
+ <heading><package>equivs</package>
<p>
<package>equivs</package> is another package for making packages. It
is often suggested for local use if you need to make a package simply
to fulfill dependencies. It is also sometimes used when making
``meta-packages'', which are packages whose only purpose is to depend
-on other packages.
+on other packages.</p>
+ </sect1>
+ </sect>
- <sect id="cvs-buildpackage">
- <heading><package>cvs-buildpackage</package>
+
+ <sect id="tools-builders">
+ <heading>Package builders</heading>
+ <p>
+The following packages help with the package building process, general
+driving <prgn>dpkg-buildpackage</prgn> as well as handling supporting
+tasks.</p>
+
+ <sect1 id="cvs-buildpackage">
+ <heading><package>cvs-buildpackage</package>
<p>
<package>cvs-buildpackage</package> provides the capability to inject
or import Debian source packages into a CVS repository, build a Debian
of a package for <em>stable</em>, <em>unstable</em> and possibly
<em>experimental</em> distributions, along with the other benefits of
a version control system.
+ </sect1>
-
- <sect id="dupload">
- <heading><package>dupload</package>
+ <sect1 id="debootstrap">
+ <heading><package>debootstrap</package></heading>
+ <p>
+The <package>debootstrap</package> package and script allows you to
+"bootstrap" a Debian base system into any part of your file-system.
+By "base system", we mean the bare minimum of packages required to
+operate and install the rest of the system.
<p>
+Having a system like this can be useful in many ways. For instance,
+you can <prgn>chroot</prgn> into it if you want to test your build
+depends. Or, you can test how your package behaves when installed
+into a bare base system. Chroot builders use this package, see below.
+ </sect1>
+
+ <sect1 id="pbuilder">
+ <heading><package>pbuilder</package></heading>
+ <p>
+<package>pbuilder</package> constructs a chrooted system, and builds a
+package inside the chroot. It is very useful to check that a package's
+build-dependencies are correct, and to be sure that unnecessary and
+wrong build dependencies will not exist in the resulting package.</p>
+ <p>
+A related package is <package>pbuilder-uml</package>, which goes even
+further build doing the build within User-mode-linux.</p>
+ </sect1>
+
+ <sect1 id="sbuild">
+ <heading><package>sbuild</package></heading>
+ <p>
+<package>sbuild</package> is another automated builder. It can use
+chrooted environments as well. It can be used stand-alone, or as part
+of a networked, distributed build environment. As the latter, it is
+part of the system used by porters to build binary packages for all
+the available architectures. See <ref id="buildd"> for more
+information, and <url id="&url-buildd;"> to see the system in
+action.</p>
+ </sect1>
+ </sect>
+
+ <sect id="uploaders">
+ <heading>Package uploaders</heading>
+ <p>
+The following packages help automate or simplify the process of
+uploading packages into the official archive.</p>
+
+ <sect1 id="dupload">
+ <heading><package>dupload</package></heading>
+ <p>
<package>dupload</package> is a package and a script to automatically
upload Debian packages to the Debian archive, to log the upload, and
to send mail about the upload of a package. You can configure it for
new upload locations or methods.
+ </sect1>
-
- <sect id="dput">
- <heading><package>dput</package>
- <p>
+ <sect1 id="dput">
+ <heading><package>dput</package></heading>
+ <p>
The <package>dput</package> package and script does much the same
thing as <package>dupload</package>, but in a different way. It has
some features over <package>dupload</package>, such as the ability to
check the GnuPG signature and checksums before uploading, and the
possibility of running <prgn>dinstall</prgn> in dry-run mode after the
upload.
+ </sect1>
+ </sect>
-
- <sect id="fakeroot">
- <heading><package>fakeroot</package>
- <p>
-<package>fakeroot</package> simulates root privileges. This enables
-you to build packages without being root (packages usually want to
-install files with root ownership). If you have
-<package>fakeroot</package> installed, you can build packages as a
-user: <tt>dpkg-buildpackage -rfakeroot</tt>.
-
-
- <sect id="debootstrap">
- <heading><package>debootstrap</package>
- <p>
-The <package>debootstrap</package> package and script allows you to
-"bootstrap" a Debian base system into any part of your file-system.
-By "base system", we mean the bare minimum of packages required to
-operate and install the rest of the system.
- <p>
-Having a system like this can be useful in many ways. For instance,
-you can <prgn>chroot</prgn> into it if you want to test your build
-depends. Or, you can test how your package behaves when installed
-into a bare base system.
-
-
- <sect id="pbuilder">
- <heading><package>pbuilder</package>
+ <sect id="tools-maint-automate">
+ <heading>Maintenance automation</heading>
<p>
-<package>pbuilder</package> constructs a chrooted system, and builds
-a package inside the chroot. It is very useful to check that
-a package's build-dependencies are correct, and to be sure that
-unnecessary and wrong build dependencies will not exist in the
-resulting package.
-
+The following tools help automate different maintenance tasks, from
+adding changelog entries or signature lines, looking up bugs in Emacs,
+to making use of the newest and official use of
+<file>config.sub</file>.</p>
- <sect id="devscripts">
- <heading><package>devscripts</package>
- <p>
-<package>devscripts</package> is a package containing a few wrappers
+ <sect1 id="devscripts">
+ <heading><package>devscripts</package></heading>
+<package>devscripts</package> is a package containing wrappers
and tools which are very helpful for maintaining your Debian
packages. Example scripts include <prgn>debchange</prgn> and
<prgn>dch</prgn>, which manipulate your <file>debian/changelog</file>
file from the command-line, and <prgn>debuild</prgn>, which is a
wrapper around <prgn>dpkg-buildpackage</prgn>. The <prgn>bts</prgn>
utility is also very helpful to update the state of bug reports on the
-command line, as is <prgn>uscan</prgn> to watch for new upstream
-versions of your packages. Check the <tt>devscripts(1)</tt> manual
-page for a complete list of available scripts.
-
+command line. <prgn>uscan</prgn> can be used to watch for new upstream
+versions of your packages. The <prgn>debrsign</prgn> can be used to
+remotely sign a package prior to upload, which is nice when the
+machine you build the package on is different from where your GPG keys
+are.</p>
+ <p>
+See the <manref name="devscripts" section="1"> manual page for a
+complete list of available scripts.</p>
+ </sect1>
- <sect id="dpkg-dev-el">
- <heading><package>dpkg-dev-el</package>
- <p>
+ <sect1 id="dpkg-dev-el">
+ <heading><package>dpkg-dev-el</package></heading>
<package>dpkg-dev-el</package> is an Emacs lisp package which provides
assistance when editing some of the files in the <file>debian</file>
directory of your package. For instance, when editing
<file>debian/changelog</file>, there are handy functions for
-finalizing a version and listing the package's current bugs.
+finalizing a version and listing the package's current bugs.</p>
+ </sect1>
+ </sect>
+ <sect id="tools-porting">
+ <heading>Porting tools</heading>
+ <p>
+The following tools are helpful for porters and for
+cross-compilation.</p>
+
+ <sect1 id="quinn-diff">
+ <heading><package>quinn-diff</package>
+ <p>
+<package>quinn-diff</package> is used to locate the differences from
+one architecture to another. For instance, it could tell you which
+packages need to be ported for architecture <var>Y</var>, based on
+architecture <var>X</var>.
+
+ <sect1 id="dpkg-cross">
+ <heading><package>dpkg-cross</package>
+ <p>
+<package>dpkg-cross</package> is a tool for installing libraries and
+headers for cross-compiling in a way similar to
+<package>dpkg</package>. Furthermore, the functionality of
+<prgn>dpkg-buildpackage</prgn> and <prgn>dpkg-shlibdeps</prgn> is
+enhanced to support cross-compiling.
+ </sect1>
+ </sect>
<!-- FIXME: add the following
alien
dpkg-awk
grep-dctrl
debview
+ d-shlibs
+ wajig
+ magpie
+ apt-dpkg-ref
+ apt-show-source
+ apt-show-versions
+ pdbv
+ epm
+
+rejected:
+ debaux: too new, unmaintained?
+ dh-make-perl: too new, unmaintained?
-->
-
+ </appendix>
</book>
</debiandoc>
~ianmdlvl / developers-reference.git / blobdiff