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