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