chiark / gitweb /
Use dblatex instead of fop, as long fop is in contrib.
[developers-reference.git] / tools.dbk
1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3     "" [
4   <!ENTITY % commondata SYSTEM "common.ent" > %commondata;
5 ]>
6 <appendix id="tools">
7 <title>Overview of Debian Maintainer Tools</title>
8 <para>
9 This section contains a rough overview of the tools available to maintainers.
10 The following is by no means complete or definitive, but just a guide to some
11 of the more popular tools.
12 </para>
13 <para>
14 Debian maintainer tools are meant to aid developers and free their time for
15 critical tasks.  As Larry Wall says, there's more than one way to do it.
16 </para>
17 <para>
18 Some people prefer to use high-level package maintenance tools and some do not.
19 Debian is officially agnostic on this issue; any tool which gets the job done
20 is fine.  Therefore, this section is not meant to stipulate to anyone which
21 tools they should use or how they should go about their duties of
22 maintainership.  Nor is it meant to endorse any particular tool to the
23 exclusion of a competing tool.
24 </para>
25 <para>
26 Most of the descriptions of these packages come from the actual package
27 descriptions themselves.  Further information can be found in the package
28 documentation itself.  You can also see more info with the command
29 <command>apt-cache show &lt;package-name&gt;</command>.
30 </para>
31 <section id="tools-core">
32 <title>Core tools</title>
33 <para>
34 The following tools are pretty much required for any maintainer.
35 </para>
36 <section id="dpkg-dev">
37 <title><systemitem role="package">dpkg-dev</systemitem></title>
38 <para>
39 <systemitem role="package">dpkg-dev</systemitem> contains the tools (including
40 <command>dpkg-source</command>) required to unpack, build, and upload Debian
41 source packages.  These utilities contain the fundamental, low-level
42 functionality required to create and manipulate packages; as such, they are
43 essential for any Debian maintainer.
44 </para>
45 </section>
47 <section id="debconf">
48 <title><systemitem role="package">debconf</systemitem></title>
49 <para>
50 <systemitem role="package">debconf</systemitem> provides a consistent interface
51 to configuring packages interactively.  It is user interface independent,
52 allowing end-users to configure packages with a text-only interface, an HTML
53 interface, or a dialog interface.  New interfaces can be added as modules.
54 </para>
55 <para>
56 You can find documentation for this package in the <systemitem
57 role="package">debconf-doc</systemitem> package.
58 </para>
59 <para>
60 Many feel that this system should be used for all packages which require
61 interactive configuration; see <xref linkend="bpp-config-mgmt"/> .  <systemitem
62 role="package">debconf</systemitem> is not currently required by Debian Policy,
63 but that may change in the future.
64 </para>
65 </section>
67 <section id="fakeroot">
68 <title><systemitem role="package">fakeroot</systemitem></title>
69 <para>
70 <systemitem role="package">fakeroot</systemitem> simulates root privileges.
71 This enables you to build packages without being root (packages usually want to
72 install files with root ownership).  If you have <systemitem
73 role="package">fakeroot</systemitem> installed, you can build packages as a
74 regular user: <literal>dpkg-buildpackage -rfakeroot</literal>.
75 </para>
76 </section>
78 </section>
80 <section id="tools-lint">
81 <title>Package lint tools</title>
82 <para>
83 According to the Free On-line Dictionary of Computing (FOLDOC), `lint' is a
84 Unix C language processor which carries out more thorough checks on the code
85 than is usual with C compilers.  Package lint tools help package maintainers by
86 automatically finding common problems and policy violations in their packages.
87 </para>
88 <section id="lintian">
89 <title><systemitem role="package">lintian</systemitem></title>
90 <para>
91 <systemitem role="package">lintian</systemitem> dissects Debian packages and
92 emits information about bugs and policy violations.  It contains automated
93 checks for many aspects of Debian policy as well as some checks for common
94 errors.
95 </para>
96 <para>
97 You should periodically get the newest <systemitem
98 role="package">lintian</systemitem> from `unstable' and check over all your
99 packages.  Notice that the <literal>-i</literal> option provides detailed
100 explanations of what each error or warning means, what its basis in Policy is,
101 and commonly how you can fix the problem.
102 </para>
103 <para>
104 Refer to <xref linkend="sanitycheck"/> for more information on how and when to
105 use Lintian.
106 </para>
107 <para>
108 You can also see a summary of all problems reported by Lintian on your packages
109 at <ulink url="&url-lintian;"></ulink>.  These reports contain the
110 latest <command>lintian</command> output for the whole development distribution
111 (unstable).
112 </para>
113 </section>
115 <section id="linda">
116 <title><systemitem role="package">linda</systemitem></title>
117 <para>
118 <systemitem role="package">linda</systemitem> is another package linter.  It is
119 similar to <systemitem role="package">lintian</systemitem> but has a different
120 set of checks.  Its written in Python rather than Perl.
121 </para>
122 </section>
124 <section id="debdiff">
125 <title><systemitem role="package">debdiff</systemitem></title>
126 <para>
127 <command>debdiff</command> (from the <systemitem
128 role="package">devscripts</systemitem> package, <xref linkend="devscripts"/> )
129 compares file lists and control files of two packages.  It is a simple
130 regression test, as it will help you notice if the number of binary packages
131 has changed since the last upload, or if something has changed in the control
132 file.  Of course, some of the changes it reports will be all right, but it can
133 help you prevent various accidents.
134 </para>
135 <para>
136 You can run it over a pair of binary packages:
137 </para>
138 <screen>
139 debdiff package_1-1_arch.deb package_2-1_arch.deb
140 </screen>
141 <para>
142 Or even a pair of changes files:
143 </para>
144 <screen>
145 debdiff package_1-1_arch.changes package_2-1_arch.changes
146 </screen>
147 <para>
148 For more information please see <citerefentry>
149 <refentrytitle>debdiff</refentrytitle> <manvolnum>1</manvolnum>
150 </citerefentry>.
151 </para>
152 </section>
154 </section>
156 <section id="tools-helpers">
157 <title>Helpers for <filename>debian/rules</filename></title>
158 <para>
159 Package building tools make the process of writing
160 <filename>debian/rules</filename> files easier.  See <xref
161 linkend="helper-scripts"/> for more information about why these might or might
162 not be desired.
163 </para>
164 <section id="debhelper">
165 <title><systemitem role="package">debhelper</systemitem></title>
166 <para>
167 <systemitem role="package">debhelper</systemitem> is a collection of programs
168 which can be used in <filename>debian/rules</filename> to automate common tasks
169 related to building binary Debian packages.  <systemitem
170 role="package">debhelper</systemitem> includes programs to install various
171 files into your package, compress files, fix file permissions, and integrate
172 your package with the Debian menu system.
173 </para>
174 <para>
175 Unlike some approaches, <systemitem role="package">debhelper</systemitem> is
176 broken into several small, simple commands which act in a consistent manner.
177 As such, it allows more fine-grained control than some of the other
178 debian/rules tools.
179 </para>
180 <para>
181 There are a number of little <systemitem role="package">debhelper</systemitem>
182 add-on packages, too transient to document.  You can see the list of most of
183 them by doing <literal>apt-cache search ^dh-</literal>.
184 </para>
185 </section>
187 <section id="debmake">
188 <title><systemitem role="package">debmake</systemitem></title>
189 <para>
190 <systemitem role="package">debmake</systemitem>, a precursor to <systemitem
191 role="package">debhelper</systemitem>, is a more coarse-grained
192 <filename>debian/rules</filename> assistant.  It includes two main programs:
193 <command>deb-make</command>, which can be used to help a maintainer convert a
194 regular (non-Debian) source archive into a Debian source package; and
195 <command>debstd</command>, which incorporates in one big shot the same sort of
196 automated functions that one finds in <systemitem
197 role="package">debhelper</systemitem>.
198 </para>
199 <para>
200 The consensus is that <systemitem role="package">debmake</systemitem> is now
201 deprecated in favor of <systemitem role="package">debhelper</systemitem>.  It
202 is a bug to use <systemitem role="package">debmake</systemitem> in new
203 packages.  New packages using <systemitem role="package">debmake</systemitem>
204 will be rejected from the archive.
205 </para>
206 </section>
208 <section id="dh-make">
209 <title><systemitem role="package">dh-make</systemitem></title>
210 <para>
211 The <systemitem role="package">dh-make</systemitem> package contains
212 <command>dh_make</command>, a program that creates a skeleton of files
213 necessary to build a Debian package out of a source tree.  As the name
214 suggests, <command>dh_make</command> is a rewrite of <systemitem
215 role="package">debmake</systemitem> and its template files use dh_* programs
216 from <systemitem role="package">debhelper</systemitem>.
217 </para>
218 <para>
219 While the rules files generated by <command>dh_make</command> are in general a
220 sufficient basis for a working package, they are still just the groundwork: the
221 burden still lies on the maintainer to finely tune the generated files and make
222 the package entirely functional and Policy-compliant.
223 </para>
224 </section>
226 <section id="yada">
227 <title><systemitem role="package">yada</systemitem></title>
228 <para>
229 <systemitem role="package">yada</systemitem> is another packaging helper tool.
230 It uses a <filename>debian/packages</filename> file to auto-generate
231 <filename>debian/rules</filename> and other necessary files in the
232 <filename>debian/</filename> subdirectory.  The
233 <filename>debian/packages</filename> file contains instruction to build
234 packages and there is no need to create any <filename>Makefile</filename>
235 files.  There is possibility to use macro engine similar to the one used in
236 SPECS files from RPM source packages.
237 </para>
238 <para>
239 For more informations see <literal><ulink
240 url="">YADA site</ulink></literal>.
241 </para>
242 </section>
244 <section id="equivs">
245 <title><systemitem role="package">equivs</systemitem></title>
246 <para>
247 <systemitem role="package">equivs</systemitem> is another package for making
248 packages.  It is often suggested for local use if you need to make a package
249 simply to fulfill dependencies.  It is also sometimes used when making
250 ``meta-packages'', which are packages whose only purpose is to depend on other
251 packages.
252 </para>
253 </section>
255 </section>
257 <section id="tools-builders">
258 <title>Package builders</title>
259 <para>
260 The following packages help with the package building process, general driving
261 <command>dpkg-buildpackage</command> as well as handling supporting tasks.
262 </para>
263 <section id="cvs-buildpackage">
264 <title><systemitem role="package">cvs-buildpackage</systemitem></title>
265 <para>
266 <systemitem role="package">cvs-buildpackage</systemitem> provides the
267 capability to inject or import Debian source packages into a CVS repository,
268 build a Debian package from the CVS repository, and helps in integrating
269 upstream changes into the repository.
270 </para>
271 <para>
272 These utilities provide an infrastructure to facilitate the use of CVS by
273 Debian maintainers.  This allows one to keep separate CVS branches of a package
274 for <emphasis>stable</emphasis>, <emphasis>unstable</emphasis> and possibly
275 <emphasis>experimental</emphasis> distributions, along with the other benefits
276 of a version control system.
277 </para>
278 </section>
280 <section id="debootstrap">
281 <title><systemitem role="package">debootstrap</systemitem></title>
282 <para>
283 The <systemitem role="package">debootstrap</systemitem> package and script
284 allows you to bootstrap a Debian base system into any part of your filesystem.
285 By base system, we mean the bare minimum of packages required to operate and
286 install the rest of the system.
287 </para>
288 <para>
289 Having a system like this can be useful in many ways.  For instance, you can
290 <command>chroot</command> into it if you want to test your build dependencies.
291 Or you can test how your package behaves when installed into a bare base
292 system.  Chroot builders use this package; see below.
293 </para>
294 </section>
296 <section id="pbuilder">
297 <title><systemitem role="package">pbuilder</systemitem></title>
298 <para>
299 <systemitem role="package">pbuilder</systemitem> constructs a chrooted system,
300 and builds a package inside the chroot.  It is very useful to check that a
301 package's build-dependencies are correct, and to be sure that unnecessary and
302 wrong build dependencies will not exist in the resulting package.
303 </para>
304 <para>
305 A related package is <systemitem role="package">pbuilder-uml</systemitem>,
306 which goes even further by doing the build within a User Mode Linux
307 environment.
308 </para>
309 </section>
311 <section id="sbuild">
312 <title><systemitem role="package">sbuild</systemitem></title>
313 <para>
314 <systemitem role="package">sbuild</systemitem> is another automated builder.
315 It can use chrooted environments as well.  It can be used stand-alone, or as
316 part of a networked, distributed build environment.  As the latter, it is part
317 of the system used by porters to build binary packages for all the available
318 architectures.  See <xref linkend="buildd"/> for more information, and <ulink
319 url="&url-buildd;"></ulink> to see the system in action.
320 </para>
321 </section>
323 </section>
325 <section id="uploaders">
326 <title>Package uploaders</title>
327 <para>
328 The following packages help automate or simplify the process of uploading
329 packages into the official archive.
330 </para>
331 <section id="dupload">
332 <title><systemitem role="package">dupload</systemitem></title>
333 <para>
334 <systemitem role="package">dupload</systemitem> is a package and a script to
335 automatically upload Debian packages to the Debian archive, to log the upload,
336 and to send mail about the upload of a package.  You can configure it for new
337 upload locations or methods.
338 </para>
339 </section>
341 <section id="dput">
342 <title><systemitem role="package">dput</systemitem></title>
343 <para>
344 The <systemitem role="package">dput</systemitem> package and script does much
345 the same thing as <systemitem role="package">dupload</systemitem>, but in a
346 different way.  It has some features over <systemitem
347 role="package">dupload</systemitem>, such as the ability to check the GnuPG
348 signature and checksums before uploading, and the possibility of running
349 <command>dinstall</command> in dry-run mode after the upload.
350 </para>
351 </section>
353 <section id="dcut">
354 <title><systemitem role="package">dcut</systemitem></title>
355 <para>
356 The <systemitem role="package">dcut</systemitem> script (part of the package
357 <xref linkend="dput"/> ) helps in removing files from the ftp upload directory.
358 </para>
359 </section>
361 </section>
363 <section id="tools-maint-automate">
364 <title>Maintenance automation</title>
365 <para>
366 The following tools help automate different maintenance tasks, from adding
367 changelog entries or signature lines and looking up bugs in Emacs to making use
368 of the newest and official <filename>config.sub</filename>.
369 </para>
370 <section id="devscripts">
371 <title><systemitem role="package">devscripts</systemitem></title>
372 <para>
373 <systemitem role="package">devscripts</systemitem> is a package containing
374 wrappers and tools which are very helpful for maintaining your Debian packages.
375 Example scripts include <command>debchange</command> and
376 <command>dch</command>, which manipulate your
377 <filename>debian/changelog</filename> file from the command-line, and
378 <command>debuild</command>, which is a wrapper around
379 <command>dpkg-buildpackage</command>.  The <command>bts</command> utility is
380 also very helpful to update the state of bug reports on the command line.
381 <command>uscan</command> can be used to watch for new upstream versions of your
382 packages.  <command>debrsign</command> can be used to remotely sign a package
383 prior to upload, which is nice when the machine you build the package on is
384 different from where your GPG keys are.
385 </para>
386 <para>
387 See the <citerefentry> <refentrytitle>devscripts</refentrytitle>
388 <manvolnum>1</manvolnum> </citerefentry> manual page for a complete list of
389 available scripts.
390 </para>
391 </section>
393 <section id="autotools-dev">
394 <title><systemitem role="package">autotools-dev</systemitem></title>
395 <para>
396 <systemitem role="package">autotools-dev</systemitem> contains best practices
397 for people who maintain packages which use <command>autoconf</command> and/or
398 <command>automake</command>.  Also contains canonical
399 <filename>config.sub</filename> and <filename>config.guess</filename> files
400 which are known to work on all Debian ports.
401 </para>
402 </section>
404 <section id="dpkg-repack">
405 <title><systemitem role="package">dpkg-repack</systemitem></title>
406 <para>
407 <command>dpkg-repack</command> creates Debian package file out of a package
408 that has already been installed.  If any changes have been made to the package
409 while it was unpacked (e.g., files in <filename>/etc</filename> were modified),
410 the new package will inherit the changes.
411 </para>
412 <para>
413 This utility can make it easy to copy packages from one computer to another, or
414 to recreate packages which are installed on your system but no longer available
415 elsewhere, or to save the current state of a package before you upgrade it.
416 </para>
417 </section>
419 <section id="alien">
420 <title><systemitem role="package">alien</systemitem></title>
421 <para>
422 <command>alien</command> converts binary packages between various packaging
423 formats, including Debian, RPM (RedHat), LSB (Linux Standard Base), Solaris,
424 and Slackware packages.
425 </para>
426 </section>
428 <section id="debsums">
429 <title><systemitem role="package">debsums</systemitem></title>
430 <para>
431 <command>debsums</command> checks installed packages against their MD5 sums.
432 Note that not all packages have MD5 sums, since they aren't required by Policy.
433 </para>
434 </section>
436 <section id="dpkg-dev-el">
437 <title><systemitem role="package">dpkg-dev-el</systemitem></title>
438 <para>
439 <systemitem role="package">dpkg-dev-el</systemitem> is an Emacs lisp package
440 which provides assistance when editing some of the files in the
441 <filename>debian</filename> directory of your package.  For instance, there are
442 handy functions for listing a package's current bugs, and for finalizing the
443 latest entry in a <filename>debian/changelog</filename> file.
444 </para>
445 </section>
447 <section id="dpkg-depcheck">
448 <title><systemitem role="package">dpkg-depcheck</systemitem></title>
449 <para>
450 <command>dpkg-depcheck</command> (from the <systemitem
451 role="package">devscripts</systemitem> package, <xref linkend="devscripts"/> )
452 runs a command under <command>strace</command> to determine all the packages
453 that were used by the said command.
454 </para>
455 <para>
456 For Debian packages, this is useful when you have to compose a
457 <literal>Build-Depends</literal> line for your new package: running the build
458 process through <command>dpkg-depcheck</command> will provide you with a good
459 first approximation of the build-dependencies.  For example:
460 </para>
461 <screen>
462 dpkg-depcheck -b debian/rules build
463 </screen>
464 <para>
465 <command>dpkg-depcheck</command> can also be used to check for run-time
466 dependencies, especially if your package uses exec(2) to run other programs.
467 </para>
468 <para>
469 For more information please see <citerefentry>
470 <refentrytitle>dpkg-depcheck</refentrytitle> <manvolnum>1</manvolnum>
471 </citerefentry>.
472 </para>
473 </section>
475 </section>
477 <section id="tools-porting">
478 <title>Porting tools</title>
479 <para>
480 The following tools are helpful for porters and for cross-compilation.
481 </para>
482 <section id="quinn-diff">
483 <title><systemitem role="package">quinn-diff</systemitem></title>
484 <para>
485 <systemitem role="package">quinn-diff</systemitem> is used to locate the
486 differences from one architecture to another.  For instance, it could tell you
487 which packages need to be ported for architecture <replaceable>Y</replaceable>,
488 based on architecture <replaceable>X</replaceable>.
489 </para>
490 </section>
492 <section id="dpkg-cross">
493 <title><systemitem role="package">dpkg-cross</systemitem></title>
494 <para>
495 <systemitem role="package">dpkg-cross</systemitem> is a tool for installing
496 libraries and headers for cross-compiling in a way similar to <systemitem
497 role="package">dpkg</systemitem>.  Furthermore, the functionality of
498 <command>dpkg-buildpackage</command> and <command>dpkg-shlibdeps</command> is
499 enhanced to support cross-compiling.
500 </para>
501 </section>
503 </section>
505 <section id="tools-doc">
506 <title>Documentation and information</title>
507 <para>
508 The following packages provide information for maintainers or help with
509 building documentation.
510 </para>
511 <section id="debiandoc-sgml">
512 <title><systemitem role="package">debiandoc-sgml</systemitem></title>
513 <para>
514 <systemitem role="package">debiandoc-sgml</systemitem> provides the DebianDoc
515 SGML DTD, which is commonly used for Debian documentation.  This manual, for
516 instance, is written in DebianDoc.  It also provides scripts for building and
517 styling the source to various output formats.
518 </para>
519 <para>
520 Documentation for the DTD can be found in the <systemitem
521 role="package">debiandoc-sgml-doc</systemitem> package.
522 </para>
523 </section>
524 <!-- TODO: Maybe better:
525 <section id="docbook-xml">
526 <title><systemitem role="package">docbook-xml</systemitem></title>
527 <para>
528 <systemitem role="package">docbook-xml</systemitem> provides the
529 DocBook XML DTDs, which are commonly used for Debian documentation (as
530 is the older debiandoc SGML DTD). This manual, for instance, is written
531 in DocBook XML. The <systemitem
532 role="package">docbook-xsl</systemitem> package provides the XSL files
533 for building and styling the source to various output formats. You
534 will need an XSLT processor, such as <systemitem
535 role="package">xsltproc</systemitem>, and an FO processor, such as
536 <systemitem role="package">fop</systemitem>, to generate documentation.
537 </para>
538 </section>
539 -->
541 <section id="debian-keyring">
542 <title><systemitem role="package">debian-keyring</systemitem></title>
543 <para>
544 Contains the public GPG and PGP keys of Debian developers.  See <xref
545 linkend="key-maint"/> and the package documentation for more information.
546 </para>
547 </section>
549 <section id="debview">
550 <title><systemitem role="package">debview</systemitem></title>
551 <para>
552 <systemitem role="package">debview</systemitem> provides an Emacs mode for
553 viewing Debian binary packages.  This lets you examine a package without
554 unpacking it.
555 </para>
556 </section>
558 </section>
559 <!-- FIXME: add the following
561 questionable:
562   dbs (referred to above)
563   dpatch (referred to above)
564   debarchiver
565   ucf
566   dpkg-awk
567   grep-dctrl
568   d-shlibs
569   wajig
570   magpie
571   apt-dpkg-ref
572   apt-show-source
573   apt-show-versions
574   pdbv
575   epm
576   apt-src
577   apt-build
579 rejected:
580   debaux: too new, unmaintained?
581   dh-make-perl: too new, unmaintained?
582 -->
583 </appendix>