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