<!entity % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!entity cvs-rev "$Revision: 1.149 $">
+ <!entity cvs-rev "$Revision: 1.156 $">
<!-- if you are translating this document, please notate the CVS
revision of the developers reference here -->
<!--
or like *.debian.net DNS entry. Those features are documented
at <url id="&url-debian-db-mail-gw;">.
- <sect id="servers-mirrors">Mirrors of Debian servers
- <p>
-The web and FTP servers have several mirrors available. Please do not
-put heavy load on the canonical FTP or web servers. Ideally, the
-canonical servers only mirror out to a first tier of mirrors, and all
-user access is to the mirrors. This allows Debian to better spread
-its bandwidth requirements over several servers and networks. Note
-that newer push mirroring techniques ensure that mirrors are as
-up-to-date as they can be.
- <p>
-The main web page listing the available public FTP/HTTP
-servers can be found at <url id="&url-debian-mirrors;">. More
-information concerning Debian mirrors can be found at <url
-id="&url-debian-mirroring;">. This useful page includes information
-and tools which can be helpful if you are interested in setting up
-your own mirror, either for internal or public access.
- <p>
-Note that mirrors are generally run by third-parties who are
-interested in helping Debian. As such, developers generally do not
-have accounts on these machines.
-
<sect id="archive">The Debian archive
<p>
symbolic links for <em>stable</em>, <em>testing</em>, and
<em>unstable</em> point to the appropriate release directories.
+
+ <sect id="mirrors">Debian mirrors
+ <p>
+The various download archives and the web site have several mirrors
+available in order to relieve our canonical servers from heavy load.
+In fact, some of the canonical servers aren't public, and instead a
+first tier of mirrors balances the load. That way, users always access
+the mirrors and get used to using them, which allows Debian to better
+spread its bandwidth requirements over several servers and networks,
+and basically makes users avoid hammering on one primary location.
+Note that the first tier of mirrors is as up-to-date as it can be since
+they update when triggered from the internal sites (we call this
+"push mirroring").
+ <p>
+All the information on Debian mirrors, including a list of the available
+public FTP/HTTP servers, can be found at <url id="&url-debian-mirrors;">.
+This useful page also includes information and tools which can be helpful if
+you are interested in setting up your own mirror, either for internal or
+public access.
+ <p>
+Note that mirrors are generally run by third-parties who are
+interested in helping Debian. As such, developers generally do not
+have accounts on these machines.
+
+
<sect id="incoming-system">
<heading>The Incoming system
<p>
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
+porting to 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>
It is not OK to simply take over a package that you feel is neglected
— that would be package hijacking. You can, of course, contact the
current maintainer and ask them if you may take over the package.
-However, without their assent, you may not take over the package.
-Even if they ignore you, that is still not grounds to take over a
-package. If you really feel that a maintainer has gone AWOL (absent
-without leave), post a query to &email-debian-private;. You may also
-inform the QA group (cf. <ref id="mia-qa">).
+If you have reason to believe a maintainer has gone AWOL
+(absent without leave), see <ref id="mia-qa">.
+ <p>
+Generally, you may not take over the package without the assent of the
+current maintainer. Even if they ignore you, that is still not grounds to
+take over a package. Complaints about maintainers should be brought up on
+the developers' mailing list. If the discussion doesn't end with a positive
+conclusion, and the issue is of a technical nature, consider bringing it to
+the attention of the technical committee (see the <url name="technical
+committee web page" id="&url-tech-ctte;"> for more information).
<p>
If you take over an old package, you probably want to be listed as the
package's official maintainer in the bug system. This will happen
name="Debian Policy">, which defines explicit baseline requirements
which all Debian packages must fulfill. Yet there is also a shared
history of experience which goes beyond the Debian Policy, an
-accumulatation of years of experience in packaging. Many very
+accumulation of years of experience in packaging. Many very
talented people have created great tools, tools which help you, the
Debian maintainer, create and maintain excellent packages.
<p>
<package>debmake</package>, were "monolithic": you couldn't pick and
choose which part of the helper you found useful, but had to use the
helper to do everything. <package>debhelper</package>, however, is a
-number of sep
erate little <prgn>dh_*</prgn> programs. For instance,
-<prgn>dh_installman</prgn> installs and compresses manpages,
+number of sep
arate little <prgn>dh_*</prgn> programs. For instance,
+<prgn>dh_installman</prgn> installs and compresses man pages,
<prgn>dh_installmenu</prgn> installs menu files, and so on. Thus, it
offers enough flexibility to be able to use the little helper scripts,
where useful, in conjunction with hand-crafted commands in
learn its expectations and behavior.
<p>
Some people feel that vanilla <file>debian/rules</file> files are
-better, since you don't have to learn the intricies of any helper
+better, since you don't have to learn the intricacies of any helper
system. This decision is completely up to you. Use what works for
you. Many examples of vanilla <file>debian/rules</file> files are
available at <url id="&url-rules-files;">.
<prgn>install</prgn> (vanilla approach) or <prgn>dh_install</prgn>
(from <package>debhelper</package>). Be sure to check the different
permutations of the various packages, ensuring that you have the
-inter-package dependancies set right in <file>debian/control</file>.
+inter-package dependencies set right in <file>debian/control</file>.
<p>
The first case is a bit more difficult since it involves multiple
recompiles of the same software but with different configure
<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
+the maintainer script must have a bash sh-bang line. POSIX shell or
Bash are preferred to Perl, since they enable
<package>debhelper</package> to easily add bits to the scripts.
<p>
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
+If you need to check for the existence 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
+If you don't wish to hard-code the path of the command in your
maintainer script, the following POSIX-compliant shell function may
help:
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 home page to the
+package description in <file>debian/control</file>. This information
+should be added at the
+end of description, using the following format:
+
+<example> .
+ Homepage: 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.
+ <p>
+Note that we expect this field will eventually be replaced by a proper
+<file>debian/control</file> field understood by <prgn>dpkg</prgn> and
+<tt>&packages-host;</tt>. If you don't want to bother migrating the
+home page from the description to this field, you should probably wait
+until that is available.</p>
+ </sect1>
+ </sect>
<!--
<sect1 id="pkg-mgmt-cvs">Managing a package with CVS
via CVS (debian/rules refresh).
-->
+
<sect id="bpp-config-mgmt">
<heading>Configuration management with <package>debconf</package></heading>
and provide that in your CVS area.
<p>
If you maintain XML or SGML documentation, we suggest that you isolate
-any language-independant information and define those as entities in a
+any language-independent information and define those as entities in a
separate file which is included by all the different
translations. This makes it much easier, for instance, to keep URLs
up-to-date across multiple files.
especially on more volatile architectures. Some very good packaging
practices for any package using <prgn>autoconf</prgn> and/or
<prgn>automake</prgn> have been synthesized in
-&file-bpp-autotools;. You're strongly encouraged to read this file and
+&file-bpp-autotools; from the <package>autotools-dev</package>
+package. You're strongly encouraged to read this file and
to follow the given recommendations.
Good practices for library packaging have been grouped in
<url id="&url-libpkg-guide;" name="the library packaging guide">.
+
+ <sect1 id="bpp-docs">Documentation
+ <p>
+Be sure to follow the <url id="&url-debian-policy;ch-docs.html"
+ name="Policy on documentation">.</p>
+ <p>
+If your package contains documentation built from XML or SGML, we
+recommend you not ship the XML or SGML source in the binary
+package(s). If users want the source of the documentation, they
+should retrieve the source package.</p>
+ <p>
+Policy specifies that documentation should be shipped in HTML format.
+We also recommend shipping documentation in PDF and plain text format if
+convenient and quality output is possible. However, it is generally
+not appropriate to ship plain text versions of documentation whose source
+format is HTML.</p>
+ <p>
+Major shipped manuals should register themselves with
+<package>doc-base</package> on installation. See the
+<package>doc-base</package> package documentation for more
+information.</p>
+
+
<sect1 id="bpp-other">Specific types of packages
<p>
Several specific types of packages have special sub-policies and
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;.
If someone doesn't feel confident with an NMU, he should just send a patch
to the BTS. It's far better than a broken NMU.
- <sect id="mia-qa">Dealing with unreachable maintainers
- <p>
-If you notice that a package is lacking maintenance, you should
-make sure the maintainer is active and will continue to work on
-his packages. Try contacting him yourself.
- <p>
-If you do not get a reply after a few weeks you should collect all
-useful information about this maintainer. Start by logging into
-the <url id="&url-debian-db;" name="Debian Developer's Database">
-and doing a full search to check whether the maintainer is on vacation
-and when they were last seen. Collect any important package names
-they maintain and any Release Critical bugs filed against them.
- <p>
-Send all this information to &email-debian-qa;, in order to let the
-QA people do whatever is needed.
<sect id="contacting-maintainers">Contacting other maintainers
<p>
email address.
+ <sect id="mia-qa">Dealing with inactive and/or unreachable maintainers
+ <p>
+If you notice that a package is lacking maintenance, you should
+make sure that the maintainer is active and will continue to work on
+their packages. It is possible that they are not active any more, but
+haven't registered out of the system, so to speak. On the other hand,
+it is also possible that they just need a reminder.
+ <p>
+The first step is to politely contact the maintainer, and wait for a
+response, for a reasonable time. It is quite hard to define "reasonable
+time", but it is important to take into account that real life is sometimes
+very hectic. One way to handle this would be send a reminder after two
+weeks.
+ <p>
+If the maintainer doesn't reply within four weeks (a month), one can
+assume that a response will probably not happen. If that happens, you
+should investigate further, and try to gather as much useful information
+about the maintainer in question as possible. This includes:
+ <p>
+ <list>
+ <item>The "echelon" information available through the
+ <url id="&url-debian-db;" name="developers' LDAP database">,
+ which indicates when's the last time a developer has posted to
+ a Debian mailing list. (This includes uploads via
+ debian-*-changes lists.) Also, remember to check whether the
+ maintainer is marked as "on vacation" in the database.
+
+ <item>The number of packages this maintainer is responsible for,
+ and the condition of those packages. In particular, are there
+ any RC bugs that have been open for ages? Furthermore, how
+ many bugs are there in general? Another important piece of
+ information is whether the packages have been NMUed, and if
+ so, by whom?
+
+ <item>Is there any activity of the maintainer outside of Debian?
+ For example, they might have posted something recently to
+ non-Debian mailing lists or news groups.
+ </list>
+ <p>
+One big problem are packages which were sponsored -- the maintainer is not
+an official Debian developer. The echelon information is not available for
+sponsored people, for example, so you need to find and contact the Debian
+developer who has actually uploaded the package. Given that they signed the
+package, they're responsible for the upload anyhow, and should know what
+happened to the person they sponsored.
+ <p>
+It is also allowed to post a query to &email-debian-devel;, asking if anyone
+is aware of the whereabouts of the missing maintainer.
+ <p>
+Once you have gathered all of this, you can contact &email-debian-qa;.
+People on this alias will use the information you provided in order to
+decide how to proceed. For example, they might orphan one or all of the
+packages of the maintainer. If a packages has been NMUed, they might prefer
+to contact the NMUer before orphaning the package -- perhaps the person who
+has done the NMU is interested in the package.
+ <p>
+One last word: please remember to be polite. We are all volunteers and
+cannot dedicate all of our time to Debian. Also, you are not aware of the
+circumstances of the person who is involved. Perhaps they might be
+seriously ill or might even had died -- you do not know who may be on the
+receiving side -- imagine how a relative will feel if they read the e-mail
+of the deceased and find a very impolite, angry and accusing message!)
+ <p>
+On the other hand, although we are volunteers, we do have a responsibility.
+So you can stress the importance of the greater good -- if a maintainer does
+not have the time or interest anymore, they should "let go" and give the
+package to someone with more time.
+
+
<sect id="newmaint">
<heading>Interacting with prospective Debian developers</heading>
<p>
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>
+ <p>
+<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>
+ <sect1 id="autotools-dev">
+ <heading><package>autotools-dev</package></heading>
+ <p>
+Contains best practices for people maintaining packages that use
+<prgn>autoconf</prgn> and/or <prgn>automake</prgn>. Also contains
+canonical <file>config.sub</file> and <file>config.guess</file> files
+which are known to work on all Debian ports.</p>
+ </sect1>
- <sect id="dpkg-dev-el">
- <heading><package>dpkg-dev-el</package>
- <p>
+ <sect1 id="dpkg-repack">
+ <heading><package>dpkg-repack</package></heading>
+ <p>
+<prgn>dpkg-repack</prgn> creates Debian package file out of a package
+that has already been installed. If any changes have been made to the
+package while it was unpacked (e.g., files in <file>/etc</file> were
+modified), the new package will inherit the changes.</p>
+ <p>
+This utility can make it easy to copy packages from one computer to
+another, or to recreate packages that are installed on your system
+but no longer available elsewhere, or to store the current state of a
+package before you upgrade it.</p>
+ </sect1>
+
+ <sect1 id="alien">
+ <heading><package>alien</package></heading>
+ <p>
+<prgn>alien</prgn> converts binary packages between various packaging
+formats, including Debian, RPM (RedHat), LSB (Linux Standard Base),
+Solaris and Slackware packages.</p>
+ </sect1>
+
+ <sect1 id="debsums">
+ <heading><package>debsums</package></heading>
+ <p>
+<prgn>debsums</prgn> checks installed packages against their MD5 sums.
+Note that not all packages have MD5 sums, since they aren't required
+by Policy.</p>
+ </sect1>
+
+ <sect1 id="dpkg-dev-el">
+ <heading><package>dpkg-dev-el</package></heading>
+ <p>
<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 id="tools-doc">
+ <heading>Documentation and information</heading>
+ <p>
+The following packages provide information for maintainers or help
+with building documentation.
+
+ <sect1 id="debiandoc-sgml">
+ <heading><package>debiandoc-sgml</package></heading>
+ <p>
+<package>debiandoc-sgml</package> provides the DebianDoc SGML DTD,
+which is commonly used for Debian documentation. This manual, for
+instance, is written in DebianDoc. It also provides scripts for
+building and styling the source to various output formats.</p>
+ <p>
+Documentation for the DTD can be found in the
+<package>debiandoc-sgml-doc</package> package.</p>
+ </sect1>
+
+ <sect1 id="debian-keyring">
+ <heading><package>debian-keyring</package></heading>
+ <p>
+Contains the public GPG and PGP keys of Debian developers. See <ref
+id="key-maint"> and the package documentation for more
+information.</p>
+ </sect1>
+
+ <sect1 id="debview">
+ <heading><package>debview</package></heading>
+ <p>
+<package>debview</package> provides an Emacs mode for viewing Debian
+binary packages. This lets you examine a package without unpacking
+it.</p>
+ </sect1>
+ </sect>
<!-- FIXME: add the following
- alien
- dpkg-repack
- debsums
- debiandoc-sgml, debiandoc-sgml-doc
- debian-keyring
questionable:
ucf
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