chiark / gitweb /
Removed mention of Gandi's discontinued discount.
[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     "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
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 <replaceable>package-name</replaceable></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>
46
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>
66
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>
77
78 </section>
79
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 <literal>unstable</literal> and check
99 over all your packages.  Notice that the <literal>-i</literal> option provides
100 detailed explanations of what each error or warning means, what its basis in
101 Policy is, 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 (<literal>unstable</literal>).
112 </para>
113 </section>
114
115 <section id="debdiff">
116 <title><command>debdiff</command></title>
117 <para>
118 <command>debdiff</command> (from the <systemitem
119 role="package">devscripts</systemitem> package, <xref linkend="devscripts"/>)
120 compares file lists and control files of two packages.  It is a simple
121 regression test, as it will help you notice if the number of binary packages
122 has changed since the last upload, or if something has changed in the control
123 file.  Of course, some of the changes it reports will be all right, but it can
124 help you prevent various accidents.
125 </para>
126 <para>
127 You can run it over a pair of binary packages:
128 </para>
129 <screen>
130 debdiff package_1-1_arch.deb package_2-1_arch.deb
131 </screen>
132 <para>
133 Or even a pair of changes files:
134 </para>
135 <screen>
136 debdiff package_1-1_arch.changes package_2-1_arch.changes
137 </screen>
138 <para>
139 For more information please see <citerefentry>
140 <refentrytitle>debdiff</refentrytitle> <manvolnum>1</manvolnum>
141 </citerefentry>.
142 </para>
143 </section>
144
145 </section>
146
147 <section id="tools-helpers">
148 <title>Helpers for <filename>debian/rules</filename></title>
149 <para>
150 Package building tools make the process of writing
151 <filename>debian/rules</filename> files easier.  See <xref
152 linkend="helper-scripts"/> for more information about why these might or might
153 not be desired.
154 </para>
155 <section id="debhelper">
156 <title><systemitem role="package">debhelper</systemitem></title>
157 <para>
158 <systemitem role="package">debhelper</systemitem> is a collection of programs
159 which can be used in <filename>debian/rules</filename> to automate common tasks
160 related to building binary Debian packages.  <systemitem
161 role="package">debhelper</systemitem> includes programs to install various
162 files into your package, compress files, fix file permissions, and integrate
163 your package with the Debian menu system.
164 </para>
165 <para>
166 Unlike some approaches, <systemitem role="package">debhelper</systemitem> is
167 broken into several small, simple commands which act in a consistent manner.
168 As such, it allows more fine-grained control than some of the other
169 debian/rules tools.
170 </para>
171 <para>
172 There are a number of little <systemitem role="package">debhelper</systemitem>
173 add-on packages, too transient to document.  You can see the list of most of
174 them by doing <literal>apt-cache search ^dh-</literal>.
175 </para>
176 </section>
177
178 <section id="dh-make">
179 <title><systemitem role="package">dh-make</systemitem></title>
180 <para>
181 The <systemitem role="package">dh-make</systemitem> package contains
182 <command>dh_make</command>, a program that creates a skeleton of files
183 necessary to build a Debian package out of a source tree.  As the name
184 suggests, <command>dh_make</command> is a rewrite of <systemitem
185 role="package">debmake</systemitem> and its template files use <command>dh_*</command> programs
186 from <systemitem role="package">debhelper</systemitem>.
187 </para>
188 <para>
189 While the rules files generated by <command>dh_make</command> are in general a
190 sufficient basis for a working package, they are still just the groundwork: the
191 burden still lies on the maintainer to finely tune the generated files and make
192 the package entirely functional and Policy-compliant.
193 </para>
194 </section>
195
196 <section id="equivs">
197 <title><systemitem role="package">equivs</systemitem></title>
198 <para>
199 <systemitem role="package">equivs</systemitem> is another package for making
200 packages.  It is often suggested for local use if you need to make a package
201 simply to fulfill dependencies.  It is also sometimes used when making
202 ``meta-packages'', which are packages whose only purpose is to depend on other
203 packages.
204 </para>
205 </section>
206
207 </section>
208
209 <section id="tools-builders">
210 <title>Package builders</title>
211 <para>
212 The following packages help with the package building process, general driving
213 <command>dpkg-buildpackage</command> as well as handling supporting tasks.
214 </para>
215 <section id="cvs-buildpackage">
216 <title><systemitem role="package">cvs-buildpackage</systemitem></title>
217 <para>
218 <systemitem role="package">cvs-buildpackage</systemitem> provides the
219 capability to inject or import Debian source packages into a CVS repository,
220 build a Debian package from the CVS repository, and helps in integrating
221 upstream changes into the repository.
222 </para>
223 <para>
224 These utilities provide an infrastructure to facilitate the use of CVS by
225 Debian maintainers.  This allows one to keep separate CVS branches of a package
226 for <literal>stable</literal>, <literal>unstable</literal> and possibly
227 <literal>experimental</literal> distributions, along with the other benefits
228 of a version control system.
229 </para>
230 </section>
231
232 <section id="debootstrap">
233 <title><systemitem role="package">debootstrap</systemitem></title>
234 <para>
235 The <systemitem role="package">debootstrap</systemitem> package and script
236 allows you to bootstrap a Debian base system into any part of your filesystem.
237 By base system, we mean the bare minimum of packages required to operate and
238 install the rest of the system.
239 </para>
240 <para>
241 Having a system like this can be useful in many ways.  For instance, you can
242 <command>chroot</command> into it if you want to test your build dependencies.
243 Or you can test how your package behaves when installed into a bare base
244 system.  Chroot builders use this package; see below.
245 </para>
246 </section>
247
248 <section id="pbuilder">
249 <title><systemitem role="package">pbuilder</systemitem></title>
250 <para>
251 <systemitem role="package">pbuilder</systemitem> constructs a chrooted system,
252 and builds a package inside the chroot.  It is very useful to check that a
253 package's build-dependencies are correct, and to be sure that unnecessary and
254 wrong build dependencies will not exist in the resulting package.
255 </para>
256 <para>
257 A related package is <systemitem role="package">pbuilder-uml</systemitem>,
258 which goes even further by doing the build within a User Mode Linux
259 environment.
260 </para>
261 </section>
262
263 <section id="sbuild">
264 <title><systemitem role="package">sbuild</systemitem></title>
265 <para>
266 <systemitem role="package">sbuild</systemitem> is another automated builder.
267 It can use chrooted environments as well.  It can be used stand-alone, or as
268 part of a networked, distributed build environment.  As the latter, it is part
269 of the system used by porters to build binary packages for all the available
270 architectures.  See <xref linkend="wanna-build"/> for more information, and 
271 <ulink url="&url-buildd;"></ulink> to see the system in action.
272 </para>
273 </section>
274
275 </section>
276
277 <section id="uploaders">
278 <title>Package uploaders</title>
279 <para>
280 The following packages help automate or simplify the process of uploading
281 packages into the official archive.
282 </para>
283 <section id="dupload">
284 <title><systemitem role="package">dupload</systemitem></title>
285 <para>
286 <systemitem role="package">dupload</systemitem> is a package and a script to
287 automatically upload Debian packages to the Debian archive, to log the upload,
288 and to send mail about the upload of a package.  You can configure it for new
289 upload locations or methods.
290 </para>
291 </section>
292
293 <section id="dput">
294 <title><systemitem role="package">dput</systemitem></title>
295 <para>
296 The <systemitem role="package">dput</systemitem> package and script does much
297 the same thing as <systemitem role="package">dupload</systemitem>, but in a
298 different way.  It has some features over <systemitem
299 role="package">dupload</systemitem>, such as the ability to check the GnuPG
300 signature and checksums before uploading, and the possibility of running
301 <command>dinstall</command> in dry-run mode after the upload.
302 </para>
303 </section>
304
305 <section id="dcut">
306 <title><command>dcut</command></title>
307 <para>
308 The <command>dcut</command> script (part of the package <systemitem role="package">dput</systemitem>,
309 <xref linkend="dput"/>) helps in removing files from the ftp upload directory.
310 </para>
311 </section>
312
313 </section>
314
315 <section id="tools-maint-automate">
316 <title>Maintenance automation</title>
317 <para>
318 The following tools help automate different maintenance tasks, from adding
319 changelog entries or signature lines and looking up bugs in Emacs to making use
320 of the newest and official <filename>config.sub</filename>.
321 </para>
322 <section id="devscripts">
323 <title><systemitem role="package">devscripts</systemitem></title>
324 <para>
325 <systemitem role="package">devscripts</systemitem> is a package containing
326 wrappers and tools which are very helpful for maintaining your Debian packages.
327 Example scripts include <command>debchange</command> and
328 <command>dch</command>, which manipulate your
329 <filename>debian/changelog</filename> file from the command-line, and
330 <command>debuild</command>, which is a wrapper around
331 <command>dpkg-buildpackage</command>.  The <command>bts</command> utility is
332 also very helpful to update the state of bug reports on the command line.
333 <command>uscan</command> can be used to watch for new upstream versions of your
334 packages.  <command>debrsign</command> can be used to remotely sign a package
335 prior to upload, which is nice when the machine you build the package on is
336 different from where your GPG keys are.
337 </para>
338 <para>
339 See the <citerefentry> <refentrytitle>devscripts</refentrytitle>
340 <manvolnum>1</manvolnum> </citerefentry> manual page for a complete list of
341 available scripts.
342 </para>
343 </section>
344
345 <section id="autotools-dev">
346 <title><systemitem role="package">autotools-dev</systemitem></title>
347 <para>
348 <systemitem role="package">autotools-dev</systemitem> contains best practices
349 for people who maintain packages which use <command>autoconf</command> and/or
350 <command>automake</command>.  Also contains canonical
351 <filename>config.sub</filename> and <filename>config.guess</filename> files
352 which are known to work on all Debian ports.
353 </para>
354 </section>
355
356 <section id="dpkg-repack">
357 <title><systemitem role="package">dpkg-repack</systemitem></title>
358 <para>
359 <command>dpkg-repack</command> creates Debian package file out of a package
360 that has already been installed.  If any changes have been made to the package
361 while it was unpacked (e.g., files in <filename>/etc</filename> were modified),
362 the new package will inherit the changes.
363 </para>
364 <para>
365 This utility can make it easy to copy packages from one computer to another, or
366 to recreate packages which are installed on your system but no longer available
367 elsewhere, or to save the current state of a package before you upgrade it.
368 </para>
369 </section>
370
371 <section id="alien">
372 <title><systemitem role="package">alien</systemitem></title>
373 <para>
374 <command>alien</command> converts binary packages between various packaging
375 formats, including Debian, RPM (RedHat), LSB (Linux Standard Base), Solaris,
376 and Slackware packages.
377 </para>
378 </section>
379
380 <section id="debsums">
381 <title><systemitem role="package">debsums</systemitem></title>
382 <para>
383 <command>debsums</command> checks installed packages against their MD5 sums.
384 Note that not all packages have MD5 sums, since they aren't required by Policy.
385 </para>
386 </section>
387
388 <section id="dpkg-dev-el">
389 <title><systemitem role="package">dpkg-dev-el</systemitem></title>
390 <para>
391 <systemitem role="package">dpkg-dev-el</systemitem> is an Emacs lisp package
392 which provides assistance when editing some of the files in the
393 <filename>debian</filename> directory of your package.  For instance, there are
394 handy functions for listing a package's current bugs, and for finalizing the
395 latest entry in a <filename>debian/changelog</filename> file.
396 </para>
397 </section>
398
399 <section id="dpkg-depcheck">
400 <title><command>dpkg-depcheck</command></title>
401 <para>
402 <command>dpkg-depcheck</command> (from the <systemitem
403 role="package">devscripts</systemitem> package, <xref linkend="devscripts"/>)
404 runs a command under <command>strace</command> to determine all the packages
405 that were used by the said command.
406 </para>
407 <para>
408 For Debian packages, this is useful when you have to compose a
409 <literal>Build-Depends</literal> line for your new package: running the build
410 process through <command>dpkg-depcheck</command> will provide you with a good
411 first approximation of the build-dependencies.  For example:
412 </para>
413 <screen>
414 dpkg-depcheck -b debian/rules build
415 </screen>
416 <para>
417 <command>dpkg-depcheck</command> can also be used to check for run-time
418 dependencies, especially if your package uses <citerefentry>
419 <refentrytitle>exec</refentrytitle> <manvolnum>2</manvolnum> </citerefentry>
420 to run other programs.
421 </para>
422 <para>
423 For more information please see <citerefentry>
424 <refentrytitle>dpkg-depcheck</refentrytitle> <manvolnum>1</manvolnum>
425 </citerefentry>.
426 </para>
427 </section>
428
429 </section>
430
431 <section id="tools-porting">
432 <title>Porting tools</title>
433 <para>
434 The following tools are helpful for porters and for cross-compilation.
435 </para>
436 <section id="quinn-diff">
437 <title><systemitem role="package">quinn-diff</systemitem></title>
438 <para>
439 <systemitem role="package">quinn-diff</systemitem> is used to locate the
440 differences from one architecture to another.  For instance, it could tell you
441 which packages need to be ported for architecture <replaceable>Y</replaceable>,
442 based on architecture <replaceable>X</replaceable>.
443 </para>
444 </section>
445
446 <section id="dpkg-cross">
447 <title><systemitem role="package">dpkg-cross</systemitem></title>
448 <para>
449 <systemitem role="package">dpkg-cross</systemitem> is a tool for installing
450 libraries and headers for cross-compiling in a way similar to <systemitem
451 role="package">dpkg</systemitem>.  Furthermore, the functionality of
452 <command>dpkg-buildpackage</command> and <command>dpkg-shlibdeps</command> is
453 enhanced to support cross-compiling.
454 </para>
455 </section>
456
457 </section>
458
459 <section id="tools-doc">
460 <title>Documentation and information</title>
461 <para>
462 The following packages provide information for maintainers or help with
463 building documentation.
464 </para>
465
466 <section id="docbook-xml">
467 <title><systemitem role="package">docbook-xml</systemitem></title>
468 <para>
469 <systemitem role="package">docbook-xml</systemitem> provides the
470 DocBook XML DTDs, which are commonly used for Debian documentation (as
471 is the older debiandoc SGML DTD). This manual, for instance, is
472 written in DocBook XML.
473 </para>
474 <para>
475 The <systemitem role="package">docbook-xsl</systemitem> package
476 provides the XSL files for building and styling the source to various
477 output formats. You will need an XSLT processor, such as <systemitem
478 role="package">xsltproc</systemitem>, to use the XSL stylesheets.
479 Documentation for the stylesheets can be found in the various
480 <systemitem role="package">docbook-xsl-doc-*</systemitem> packages.
481 </para>
482 <para>
483 To produce PDF from FO, you need an FO processor, such as <systemitem
484 role="package">xmlroff</systemitem> or <systemitem
485 role="package">fop</systemitem>. Another tool to generate PDF from
486 DocBook XML is <systemitem role="package">dblatex</systemitem>.
487 </para>
488 </section>
489
490 <section id="debiandoc-sgml">
491 <title><systemitem role="package">debiandoc-sgml</systemitem></title>
492 <para>
493 <systemitem role="package">debiandoc-sgml</systemitem> provides the DebianDoc
494 SGML DTD, which is commonly used for Debian documentation,
495 but is now deprecated
496 (<systemitem role="package">docbook-xml</systemitem>
497 should be used instead).
498 It also provides scripts for building and
499 styling the source to various output formats.
500 </para>
501 <para>
502 Documentation for the DTD can be found in the <systemitem
503 role="package">debiandoc-sgml-doc</systemitem> package.
504 </para>
505 </section>
506
507 <section id="debian-keyring">
508 <title><systemitem role="package">debian-keyring</systemitem></title>
509 <para>
510 Contains the public GPG and PGP keys of Debian developers.  See <xref
511 linkend="key-maint"/> and the package documentation for more information.
512 </para>
513 </section>
514
515 <section id="debian-maintainers">
516 <title><systemitem role="package">debian-maintainers</systemitem></title>
517 <para>
518 Contains the public GPG keys of Debian Maintainers.
519 See <ulink url="&url-wiki-dm;"></ulink> for more information.
520 </para>
521 </section>
522
523 <section id="debview">
524 <title><systemitem role="package">debview</systemitem></title>
525 <para>
526 <systemitem role="package">debview</systemitem> provides an Emacs mode for
527 viewing Debian binary packages.  This lets you examine a package without
528 unpacking it.
529 </para>
530 </section>
531
532 </section>
533 <!-- FIXME: add the following
534
535 questionable:
536   dbs (referred to above)
537   dpatch (referred to above)
538   debarchiver
539   ucf
540   dpkg-awk
541   grep-dctrl
542   d-shlibs
543   wajig
544   magpie
545   apt-dpkg-ref
546   apt-show-source
547   apt-show-versions
548   pdbv
549   epm
550   apt-src
551   apt-build
552
553 rejected:
554   debaux: too new, unmaintained?
555   dh-make-perl: too new, unmaintained?
556 -->
557 </appendix>