1 # SOME DESCRIPTIVE TITLE
2 # Copyright (C) YEAR Free Software Foundation, Inc.
3 # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
8 "Project-Id-Version: PACKAGE VERSION\n"
9 "POT-Creation-Date: 2007-07-01 21:18+0000\n"
10 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
11 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
12 "Language-Team: LANGUAGE <LL@li.org>\n"
14 "Content-Type: text/plain; charset=UTF-8\n"
15 "Content-Transfer-Encoding: ENCODING\n"
17 # type: Content of: <appendix><title>
19 msgid "Overview of Debian Maintainer Tools"
22 # type: Content of: <appendix><para>
25 "This section contains a rough overview of the tools available to "
26 "maintainers. The following is by no means complete or definitive, but just "
27 "a guide to some of the more popular tools."
30 # type: Content of: <appendix><para>
33 "Debian maintainer tools are meant to aid developers and free their time for "
34 "critical tasks. As Larry Wall says, there's more than one way to do it."
37 # type: Content of: <appendix><para>
40 "Some people prefer to use high-level package maintenance tools and some do "
41 "not. Debian is officially agnostic on this issue; any tool which gets the "
42 "job done is fine. Therefore, this section is not meant to stipulate to "
43 "anyone which tools they should use or how they should go about their duties "
44 "of maintainership. Nor is it meant to endorse any particular tool to the "
45 "exclusion of a competing tool."
48 # type: Content of: <appendix><para>
51 "Most of the descriptions of these packages come from the actual package "
52 "descriptions themselves. Further information can be found in the package "
53 "documentation itself. You can also see more info with the command "
54 "<command>apt-cache show <package-name></command>."
57 # type: Content of: <appendix><section><title>
62 # type: Content of: <appendix><section><para>
64 msgid "The following tools are pretty much required for any maintainer."
67 # type: Content of: <appendix><section><section><para>
70 "<systemitem role=\"package\">dpkg-dev</systemitem> contains the tools "
71 "(including <command>dpkg-source</command>) required to unpack, build, and "
72 "upload Debian source packages. These utilities contain the fundamental, low-"
73 "level functionality required to create and manipulate packages; as such, "
74 "they are essential for any Debian maintainer."
77 # type: Content of: <appendix><section><section><para>
80 "<systemitem role=\"package\">debconf</systemitem> provides a consistent "
81 "interface to configuring packages interactively. It is user interface "
82 "independent, allowing end-users to configure packages with a text-only "
83 "interface, an HTML interface, or a dialog interface. New interfaces can be "
87 # type: Content of: <appendix><section><section><para>
90 "You can find documentation for this package in the <systemitem role=\"package"
91 "\">debconf-doc</systemitem> package."
94 # type: Content of: <appendix><section><section><para>
97 "Many feel that this system should be used for all packages which require "
98 "interactive configuration; see <xref linkend=\"bpp-config-mgmt\"/> . "
99 "<systemitem role=\"package\">debconf</systemitem> is not currently required "
100 "by Debian Policy, but that may change in the future."
103 # type: Content of: <appendix><section><section><para>
106 "<systemitem role=\"package\">fakeroot</systemitem> simulates root "
107 "privileges. This enables you to build packages without being root (packages "
108 "usually want to install files with root ownership). If you have <systemitem "
109 "role=\"package\">fakeroot</systemitem> installed, you can build packages as "
110 "a regular user: <literal>dpkg-buildpackage -rfakeroot</literal>."
113 # type: Content of: <appendix><section><title>
115 msgid "Package lint tools"
118 # type: Content of: <appendix><section><para>
121 "According to the Free On-line Dictionary of Computing (FOLDOC), `lint' is a "
122 "Unix C language processor which carries out more thorough checks on the code "
123 "than is usual with C compilers. Package lint tools help package maintainers "
124 "by automatically finding common problems and policy violations in their "
128 # type: Content of: <appendix><section><section><para>
131 "<systemitem role=\"package\">lintian</systemitem> dissects Debian packages "
132 "and emits information about bugs and policy violations. It contains "
133 "automated checks for many aspects of Debian policy as well as some checks "
137 # type: Content of: <appendix><section><section><para>
140 "You should periodically get the newest <systemitem role=\"package\">lintian</"
141 "systemitem> from `unstable' and check over all your packages. Notice that "
142 "the <literal>-i</literal> option provides detailed explanations of what each "
143 "error or warning means, what its basis in Policy is, and commonly how you "
144 "can fix the problem."
147 # type: Content of: <appendix><section><section><para>
150 "Refer to <xref linkend=\"sanitycheck\"/> for more information on how and "
151 "when to use Lintian."
154 # type: Content of: <appendix><section><section><para>
157 "You can also see a summary of all problems reported by Lintian on your "
158 "packages at <ulink url=\"&url-lintian;\"></ulink>. These reports contain "
159 "the latest <command>lintian</command> output for the whole development "
160 "distribution (unstable)."
163 # type: Content of: <appendix><section><section><para>
166 "<systemitem role=\"package\">linda</systemitem> is another package linter. "
167 "It is similar to <systemitem role=\"package\">lintian</systemitem> but has a "
168 "different set of checks. Its written in Python rather than Perl."
171 # type: Content of: <appendix><section><section><para>
174 "<command>debdiff</command> (from the <systemitem role=\"package"
175 "\">devscripts</systemitem> package, <xref linkend=\"devscripts\"/> ) "
176 "compares file lists and control files of two packages. It is a simple "
177 "regression test, as it will help you notice if the number of binary packages "
178 "has changed since the last upload, or if something has changed in the "
179 "control file. Of course, some of the changes it reports will be all right, "
180 "but it can help you prevent various accidents."
183 # type: Content of: <appendix><section><section><para>
185 msgid "You can run it over a pair of binary packages:"
188 # type: Content of: <appendix><section><section><screen>
191 msgid "debdiff package_1-1_arch.deb package_2-1_arch.deb"
194 # type: Content of: <appendix><section><section><para>
196 msgid "Or even a pair of changes files:"
199 # type: Content of: <appendix><section><section><screen>
202 msgid "debdiff package_1-1_arch.changes package_2-1_arch.changes"
205 # type: Content of: <appendix><section><section><para>
208 "For more information please see <citerefentry> <refentrytitle>debdiff</"
209 "refentrytitle> <manvolnum>1</manvolnum> </citerefentry>."
212 # type: Content of: <appendix><section><title>
214 msgid "Helpers for <filename>debian/rules</filename>"
217 # type: Content of: <appendix><section><para>
220 "Package building tools make the process of writing <filename>debian/rules</"
221 "filename> files easier. See <xref linkend=\"helper-scripts\"/> for more "
222 "information about why these might or might not be desired."
225 # type: Content of: <appendix><section><section><para>
228 "<systemitem role=\"package\">debhelper</systemitem> is a collection of "
229 "programs which can be used in <filename>debian/rules</filename> to automate "
230 "common tasks related to building binary Debian packages. <systemitem role="
231 "\"package\">debhelper</systemitem> includes programs to install various "
232 "files into your package, compress files, fix file permissions, and integrate "
233 "your package with the Debian menu system."
236 # type: Content of: <appendix><section><section><para>
239 "Unlike some approaches, <systemitem role=\"package\">debhelper</systemitem> "
240 "is broken into several small, simple commands which act in a consistent "
241 "manner. As such, it allows more fine-grained control than some of the other "
242 "debian/rules tools."
245 # type: Content of: <appendix><section><section><para>
248 "There are a number of little <systemitem role=\"package\">debhelper</"
249 "systemitem> add-on packages, too transient to document. You can see the "
250 "list of most of them by doing <literal>apt-cache search ^dh-</literal>."
253 # type: Content of: <appendix><section><section><para>
256 "<systemitem role=\"package\">debmake</systemitem>, a precursor to "
257 "<systemitem role=\"package\">debhelper</systemitem>, is a more coarse-"
258 "grained <filename>debian/rules</filename> assistant. It includes two main "
259 "programs: <command>deb-make</command>, which can be used to help a "
260 "maintainer convert a regular (non-Debian) source archive into a Debian "
261 "source package; and <command>debstd</command>, which incorporates in one big "
262 "shot the same sort of automated functions that one finds in <systemitem role="
263 "\"package\">debhelper</systemitem>."
266 # type: Content of: <appendix><section><section><para>
269 "The consensus is that <systemitem role=\"package\">debmake</systemitem> is "
270 "now deprecated in favor of <systemitem role=\"package\">debhelper</"
271 "systemitem>. It is a bug to use <systemitem role=\"package\">debmake</"
272 "systemitem> in new packages. New packages using <systemitem role=\"package"
273 "\">debmake</systemitem> will be rejected from the archive."
276 # type: Content of: <appendix><section><section><para>
279 "The <systemitem role=\"package\">dh-make</systemitem> package contains "
280 "<command>dh_make</command>, a program that creates a skeleton of files "
281 "necessary to build a Debian package out of a source tree. As the name "
282 "suggests, <command>dh_make</command> is a rewrite of <systemitem role="
283 "\"package\">debmake</systemitem> and its template files use dh_* programs "
284 "from <systemitem role=\"package\">debhelper</systemitem>."
287 # type: Content of: <appendix><section><section><para>
290 "While the rules files generated by <command>dh_make</command> are in general "
291 "a sufficient basis for a working package, they are still just the "
292 "groundwork: the burden still lies on the maintainer to finely tune the "
293 "generated files and make the package entirely functional and Policy-"
297 # type: Content of: <appendix><section><section><para>
300 "<systemitem role=\"package\">yada</systemitem> is another packaging helper "
301 "tool. It uses a <filename>debian/packages</filename> file to auto-generate "
302 "<filename>debian/rules</filename> and other necessary files in the "
303 "<filename>debian/</filename> subdirectory. The <filename>debian/packages</"
304 "filename> file contains instruction to build packages and there is no need "
305 "to create any <filename>Makefile</filename> files. There is possibility to "
306 "use macro engine similar to the one used in SPECS files from RPM source "
310 # type: Content of: <appendix><section><section><para>
313 "For more informations see <literal><ulink url=\"http://yada.alioth.debian."
314 "org/\">YADA site</ulink></literal>."
317 # type: Content of: <appendix><section><section><para>
320 "<systemitem role=\"package\">equivs</systemitem> is another package for "
321 "making packages. It is often suggested for local use if you need to make a "
322 "package simply to fulfill dependencies. It is also sometimes used when "
323 "making ``meta-packages'', which are packages whose only purpose is to depend "
327 # type: Content of: <appendix><section><title>
329 msgid "Package builders"
332 # type: Content of: <appendix><section><para>
335 "The following packages help with the package building process, general "
336 "driving <command>dpkg-buildpackage</command> as well as handling supporting "
340 # type: Content of: <appendix><section><section><para>
343 "<systemitem role=\"package\">cvs-buildpackage</systemitem> provides the "
344 "capability to inject or import Debian source packages into a CVS repository, "
345 "build a Debian package from the CVS repository, and helps in integrating "
346 "upstream changes into the repository."
349 # type: Content of: <appendix><section><section><para>
352 "These utilities provide an infrastructure to facilitate the use of CVS by "
353 "Debian maintainers. This allows one to keep separate CVS branches of a "
354 "package for <emphasis>stable</emphasis>, <emphasis>unstable</emphasis> and "
355 "possibly <emphasis>experimental</emphasis> distributions, along with the "
356 "other benefits of a version control system."
359 # type: Content of: <appendix><section><section><para>
362 "The <systemitem role=\"package\">debootstrap</systemitem> package and script "
363 "allows you to bootstrap a Debian base system into any part of your "
364 "filesystem. By base system, we mean the bare minimum of packages required "
365 "to operate and install the rest of the system."
368 # type: Content of: <appendix><section><section><para>
371 "Having a system like this can be useful in many ways. For instance, you can "
372 "<command>chroot</command> into it if you want to test your build "
373 "dependencies. Or you can test how your package behaves when installed into "
374 "a bare base system. Chroot builders use this package; see below."
377 # type: Content of: <appendix><section><section><para>
380 "<systemitem role=\"package\">pbuilder</systemitem> constructs a chrooted "
381 "system, and builds a package inside the chroot. It is very useful to check "
382 "that a package's build-dependencies are correct, and to be sure that "
383 "unnecessary and wrong build dependencies will not exist in the resulting "
387 # type: Content of: <appendix><section><section><para>
390 "A related package is <systemitem role=\"package\">pbuilder-uml</systemitem>, "
391 "which goes even further by doing the build within a User Mode Linux "
395 # type: Content of: <appendix><section><section><para>
398 "<systemitem role=\"package\">sbuild</systemitem> is another automated "
399 "builder. It can use chrooted environments as well. It can be used stand-"
400 "alone, or as part of a networked, distributed build environment. As the "
401 "latter, it is part of the system used by porters to build binary packages "
402 "for all the available architectures. See <xref linkend=\"buildd\"/> for "
403 "more information, and <ulink url=\"&url-buildd;\"></ulink> to see the system "
407 # type: Content of: <appendix><section><title>
409 msgid "Package uploaders"
412 # type: Content of: <appendix><section><para>
415 "The following packages help automate or simplify the process of uploading "
416 "packages into the official archive."
419 # type: Content of: <appendix><section><section><para>
422 "<systemitem role=\"package\">dupload</systemitem> is a package and a script "
423 "to automatically upload Debian packages to the Debian archive, to log the "
424 "upload, and to send mail about the upload of a package. You can configure "
425 "it for new upload locations or methods."
428 # type: Content of: <appendix><section><section><para>
431 "The <systemitem role=\"package\">dput</systemitem> package and script does "
432 "much the same thing as <systemitem role=\"package\">dupload</systemitem>, "
433 "but in a different way. It has some features over <systemitem role=\"package"
434 "\">dupload</systemitem>, such as the ability to check the GnuPG signature "
435 "and checksums before uploading, and the possibility of running "
436 "<command>dinstall</command> in dry-run mode after the upload."
439 # type: Content of: <appendix><section><section><para>
442 "The <systemitem role=\"package\">dcut</systemitem> script (part of the "
443 "package <xref linkend=\"dput\"/> ) helps in removing files from the ftp "
447 # type: Content of: <appendix><section><title>
449 msgid "Maintenance automation"
452 # type: Content of: <appendix><section><para>
455 "The following tools help automate different maintenance tasks, from adding "
456 "changelog entries or signature lines and looking up bugs in Emacs to making "
457 "use of the newest and official <filename>config.sub</filename>."
460 # type: Content of: <appendix><section><section><para>
463 "<systemitem role=\"package\">devscripts</systemitem> is a package containing "
464 "wrappers and tools which are very helpful for maintaining your Debian "
465 "packages. Example scripts include <command>debchange</command> and "
466 "<command>dch</command>, which manipulate your <filename>debian/changelog</"
467 "filename> file from the command-line, and <command>debuild</command>, which "
468 "is a wrapper around <command>dpkg-buildpackage</command>. The <command>bts</"
469 "command> utility is also very helpful to update the state of bug reports on "
470 "the command line. <command>uscan</command> can be used to watch for new "
471 "upstream versions of your packages. <command>debrsign</command> can be used "
472 "to remotely sign a package prior to upload, which is nice when the machine "
473 "you build the package on is different from where your GPG keys are."
476 # type: Content of: <appendix><section><section><para>
479 "See the <citerefentry> <refentrytitle>devscripts</refentrytitle> "
480 "<manvolnum>1</manvolnum> </citerefentry> manual page for a complete list of "
484 # type: Content of: <appendix><section><section><para>
487 "<systemitem role=\"package\">autotools-dev</systemitem> contains best "
488 "practices for people who maintain packages which use <command>autoconf</"
489 "command> and/or <command>automake</command>. Also contains canonical "
490 "<filename>config.sub</filename> and <filename>config.guess</filename> files "
491 "which are known to work on all Debian ports."
494 # type: Content of: <appendix><section><section><para>
497 "<command>dpkg-repack</command> creates Debian package file out of a package "
498 "that has already been installed. If any changes have been made to the "
499 "package while it was unpacked (e.g., files in <filename>/etc</filename> were "
500 "modified), the new package will inherit the changes."
503 # type: Content of: <appendix><section><section><para>
506 "This utility can make it easy to copy packages from one computer to another, "
507 "or to recreate packages which are installed on your system but no longer "
508 "available elsewhere, or to save the current state of a package before you "
512 # type: Content of: <appendix><section><section><para>
515 "<command>alien</command> converts binary packages between various packaging "
516 "formats, including Debian, RPM (RedHat), LSB (Linux Standard Base), Solaris, "
517 "and Slackware packages."
520 # type: Content of: <appendix><section><section><para>
523 "<command>debsums</command> checks installed packages against their MD5 "
524 "sums. Note that not all packages have MD5 sums, since they aren't required "
528 # type: Content of: <appendix><section><section><para>
531 "<systemitem role=\"package\">dpkg-dev-el</systemitem> is an Emacs lisp "
532 "package which provides assistance when editing some of the files in the "
533 "<filename>debian</filename> directory of your package. For instance, there "
534 "are handy functions for listing a package's current bugs, and for finalizing "
535 "the latest entry in a <filename>debian/changelog</filename> file."
538 # type: Content of: <appendix><section><section><para>
541 "<command>dpkg-depcheck</command> (from the <systemitem role=\"package"
542 "\">devscripts</systemitem> package, <xref linkend=\"devscripts\"/> ) runs a "
543 "command under <command>strace</command> to determine all the packages that "
544 "were used by the said command."
547 # type: Content of: <appendix><section><section><para>
550 "For Debian packages, this is useful when you have to compose a "
551 "<literal>Build-Depends</literal> line for your new package: running the "
552 "build process through <command>dpkg-depcheck</command> will provide you with "
553 "a good first approximation of the build-dependencies. For example:"
556 # type: Content of: <appendix><section><section><screen>
559 msgid "dpkg-depcheck -b debian/rules build"
562 # type: Content of: <appendix><section><section><para>
565 "<command>dpkg-depcheck</command> can also be used to check for run-time "
566 "dependencies, especially if your package uses exec(2) to run other programs."
569 # type: Content of: <appendix><section><section><para>
572 "For more information please see <citerefentry> <refentrytitle>dpkg-depcheck</"
573 "refentrytitle> <manvolnum>1</manvolnum> </citerefentry>."
576 # type: Content of: <appendix><section><title>
578 msgid "Porting tools"
581 # type: Content of: <appendix><section><para>
583 msgid "The following tools are helpful for porters and for cross-compilation."
586 # type: Content of: <appendix><section><section><para>
589 "<systemitem role=\"package\">quinn-diff</systemitem> is used to locate the "
590 "differences from one architecture to another. For instance, it could tell "
591 "you which packages need to be ported for architecture <replaceable>Y</"
592 "replaceable>, based on architecture <replaceable>X</replaceable>."
595 # type: Content of: <appendix><section><section><para>
598 "<systemitem role=\"package\">dpkg-cross</systemitem> is a tool for "
599 "installing libraries and headers for cross-compiling in a way similar to "
600 "<systemitem role=\"package\">dpkg</systemitem>. Furthermore, the "
601 "functionality of <command>dpkg-buildpackage</command> and <command>dpkg-"
602 "shlibdeps</command> is enhanced to support cross-compiling."
605 # type: Content of: <appendix><section><title>
607 msgid "Documentation and information"
610 # type: Content of: <appendix><section><para>
613 "The following packages provide information for maintainers or help with "
614 "building documentation."
617 # type: Content of: <appendix><section><section><para>
620 "<systemitem role=\"package\">debiandoc-sgml</systemitem> provides the "
621 "DebianDoc SGML DTD, which is commonly used for Debian documentation. This "
622 "manual, for instance, is written in DebianDoc. It also provides scripts for "
623 "building and styling the source to various output formats."
626 # type: Content of: <appendix><section><section><para>
629 "Documentation for the DTD can be found in the <systemitem role=\"package"
630 "\">debiandoc-sgml-doc</systemitem> package."
633 # type: Content of: <appendix><section><section><para>
636 "Contains the public GPG and PGP keys of Debian developers. See <xref "
637 "linkend=\"key-maint\"/> and the package documentation for more information."
640 # type: Content of: <appendix><section><section><para>
643 "<systemitem role=\"package\">debview</systemitem> provides an Emacs mode for "
644 "viewing Debian binary packages. This lets you examine a package without "