chiark / gitweb /
Re-applied comments from SGML source to the DocBook files.
[developers-reference.git] / best-pkging-practices.dbk
1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3     "">
4 <chapter id="best-pkging-practices">
5 <title>Best Packaging Practices</title>
6 <para>
7 Debian's quality is largely due to the <ulink
8 url="">Debian Policy</ulink>, which
9 defines explicit baseline requirements which all Debian packages must fulfill.
10 Yet there is also a shared history of experience which goes beyond the Debian
11 Policy, an accumulation of years of experience in packaging.  Many very
12 talented people have created great tools, tools which help you, the Debian
13 maintainer, create and maintain excellent packages.
14 </para>
15 <para>
16 This chapter provides some best practices for Debian developers.  All
17 recommendations are merely that, and are not requirements or policy.  These are
18 just some subjective hints, advice and pointers collected from Debian
19 developers.  Feel free to pick and choose whatever works best for you.
20 </para>
21 <section id="bpp-debian-rules">
22 <title>Best practices for <filename>debian/rules</filename></title>
23 <para>
24 The following recommendations apply to the <filename>debian/rules</filename>
25 file.  Since <filename>debian/rules</filename> controls the build process and
26 selects the files which go into the package (directly or indirectly), it's
27 usually the file maintainers spend the most time on.
28 </para>
29 <section id="helper-scripts">
30 <title>Helper scripts</title>
31 <para>
32 The rationale for using helper scripts in <filename>debian/rules</filename> is
33 that they let maintainers use and share common logic among many packages.  Take
34 for instance the question of installing menu entries: you need to put the file
35 into <filename>/usr/lib/menu</filename> (or <filename>/usr/lib/menu</filename>
36 for executable binary menufiles, if this is needed), and add commands to the
37 maintainer scripts to register and unregister the menu entries.  Since this is
38 a very common thing for packages to do, why should each maintainer rewrite all
39 this on their own, sometimes with bugs?  Also, supposing the menu directory
40 changed, every package would have to be changed.
41 </para>
42 <para>
43 Helper scripts take care of these issues.  Assuming you comply with the
44 conventions expected by the helper script, the helper takes care of all the
45 details.  Changes in policy can be made in the helper script; then packages
46 just need to be rebuilt with the new version of the helper and no other
47 changes.
48 </para>
49 <para>
50 <xref linkend="tools"/> contains a couple of different helpers.  The most
51 common and best (in our opinion) helper system is <systemitem
52 role="package">debhelper</systemitem>.  Previous helper systems, such as
53 <systemitem role="package">debmake</systemitem>, were monolithic: you couldn't
54 pick and choose which part of the helper you found useful, but had to use the
55 helper to do everything.  <systemitem role="package">debhelper</systemitem>,
56 however, is a number of separate little <command>dh_*</command> programs.  For
57 instance, <command>dh_installman</command> installs and compresses man pages,
58 <command>dh_installmenu</command> installs menu files, and so on.  Thus, it
59 offers enough flexibility to be able to use the little helper scripts, where
60 useful, in conjunction with hand-crafted commands in
61 <filename>debian/rules</filename>.
62 </para>
63 <para>
64 You can get started with <systemitem role="package">debhelper</systemitem> by
65 reading <citerefentry> <refentrytitle>debhelper</refentrytitle>
66 <manvolnum>1</manvolnum> </citerefentry>, and looking at the examples that come
67 with the package.  <command>dh_make</command>, from the <systemitem
68 role="package">dh-make</systemitem> package (see <xref linkend="dh-make"/> ),
69 can be used to convert a vanilla source package to a <systemitem
70 role="package">debhelper</systemitem>ized package.  This shortcut, though,
71 should not convince you that you do not need to bother understanding the
72 individual <command>dh_*</command> helpers.  If you are going to use a helper,
73 you do need to take the time to learn to use that helper, to learn its
74 expectations and behavior.
75 </para>
76 <para>
77 Some people feel that vanilla <filename>debian/rules</filename> files are
78 better, since you don't have to learn the intricacies of any helper system.
79 This decision is completely up to you.  Use what works for you.  Many examples
80 of vanilla <filename>debian/rules</filename> files are available at <ulink
81 url=""></ulink>.
82 </para>
83 </section>
85 <section id="multiple-patches">
86 <title>Separating your patches into multiple files</title>
87 <para>
88 Big, complex packages may have many bugs that you need to deal with.  If you
89 correct a number of bugs directly in the source, and you're not careful, it can
90 get hard to differentiate the various patches that you applied.  It can get
91 quite messy when you have to update the package to a new upstream version which
92 integrates some of the fixes (but not all).  You can't take the total set of
93 diffs (e.g., from <filename>.diff.gz</filename>) and work out which patch sets
94 to back out as a unit as bugs are fixed upstream.
95 </para>
96 <para>
97 Unfortunately, the packaging system as such currently doesn't provide for
98 separating the patches into several files.  Nevertheless, there are ways to
99 separate patches: the patch files are shipped within the Debian patch file
100 (<filename>.diff.gz</filename>), usually within the
101 <filename>debian/</filename> directory.  The only difference is that they
102 aren't applied immediately by dpkg-source, but by the <literal>build</literal>
103 rule of <filename>debian/rules</filename>.  Conversely, they are reverted in
104 the <literal>clean</literal> rule.
105 </para>
106 <para>
107 <command>dbs</command> is one of the more popular approaches to this.  It does
108 all of the above, and provides a facility for creating new and updating old
109 patches.  See the package <systemitem role="package">dbs</systemitem> for more
110 information and <systemitem role="package">hello-dbs</systemitem> for an
111 example.
112 </para>
113 <para>
114 <command>dpatch</command> also provides these facilities, but it's intended to
115 be even easier to use.  See the package <systemitem
116 role="package">dpatch</systemitem> for documentation and examples (in
117 <filename>/usr/share/doc/dpatch</filename>).
118 </para>
119 </section>
121 <section id="multiple-binary">
122 <title>Multiple binary packages</title>
123 <para>
124 A single source package will often build several binary packages, either to
125 provide several flavors of the same software (e.g., the <systemitem
126 role="package">vim</systemitem> source package) or to make several small
127 packages instead of a big one (e.g., so the user can install only the subset
128 needed, and thus save some disk space).
129 </para>
130 <para>
131 The second case can be easily managed in <filename>debian/rules</filename>.
132 You just need to move the appropriate files from the build directory into the
133 package's temporary trees.  You can do this using <command>install</command> or
134 <command>dh_install</command> from <systemitem
135 role="package">debhelper</systemitem>.  Be sure to check the different
136 permutations of the various packages, ensuring that you have the inter-package
137 dependencies set right in <filename>debian/control</filename>.
138 </para>
139 <para>
140 The first case is a bit more difficult since it involves multiple recompiles of
141 the same software but with different configuration options.  The <systemitem
142 role="package">vim</systemitem> source package is an example of how to manage
143 this using an hand-crafted <filename>debian/rules</filename> file.
144 </para>
145 <!-- FIXME: Find a good debhelper example with multiple configure/make
146      cycles -->
147 </section>
149 </section>
151 <section id="bpp-debian-control">
152 <title>Best practices for <filename>debian/control</filename></title>
153 <para>
154 The following practices are relevant to the <filename>debian/control</filename>
155 file.  They supplement the <ulink
156 url="">Policy
157 on package descriptions</ulink>.
158 </para>
159 <para>
160 The description of the package, as defined by the corresponding field in the
161 <filename>control</filename> file, contains both the package synopsis and the
162 long description for the package.  <xref linkend="bpp-desc-basics"/> describes
163 common guidelines for both parts of the package description.  Following that,
164 <xref linkend="bpp-pkg-synopsis"/> provides guidelines specific to the
165 synopsis, and <xref linkend="bpp-pkg-desc"/> contains guidelines specific to
166 the description.
167 </para>
168 <section id="bpp-desc-basics">
169 <title>General guidelines for package descriptions</title>
170 <para>
171 The package description should be written for the average likely user, the
172 average person who will use and benefit from the package.  For instance,
173 development packages are for developers, and can be technical in their
174 language.  More general-purpose applications, such as editors, should be
175 written for a less technical user.
176 </para>
177 <para>
178 Our review of package descriptions lead us to conclude that most package
179 descriptions are technical, that is, are not written to make sense for
180 non-technical users.  Unless your package really is only for technical users,
181 this is a problem.
182 </para>
183 <para>
184 How do you write for non-technical users?  Avoid jargon.  Avoid referring to
185 other applications or frameworks that the user might not be familiar with —
186 GNOME or KDE is fine, since users are probably familiar with these terms, but
187 GTK+ is probably not.  Try not to assume any knowledge at all.  If you must use
188 technical terms, introduce them.
189 </para>
190 <para>
191 Be objective.  Package descriptions are not the place for advocating your
192 package, no matter how much you love it.  Remember that the reader may not care
193 about the same things you care about.
194 </para>
195 <para>
196 References to the names of any other software packages, protocol names,
197 standards, or specifications should use their canonical forms, if one exists.
198 For example, use X Window System, X11, or X; not X Windows, X-Windows, or X
199 Window.  Use GTK+, not GTK or gtk.  Use GNOME, not Gnome.  Use PostScript, not
200 Postscript or postscript.
201 </para>
202 <para>
203 If you are having problems writing your description, you may wish to send it
204 along to <email></email> and request
205 feedback.
206 </para>
207 </section>
209 <section id="bpp-pkg-synopsis">
210 <title>The package synopsis, or short description</title>
211 <para>
212 The synopsis line (the short description) should be concise.  It must not
213 repeat the package's name (this is policy).
214 </para>
215 <para>
216 It's a good idea to think of the synopsis as an appositive clause, not a full
217 sentence.  An appositive clause is defined in WordNet as a grammatical relation
218 between a word and a noun phrase that follows, e.g., Rudolph the red-nosed
219 reindeer.  The appositive clause here is red-nosed reindeer.  Since the
220 synopsis is a clause, rather than a full sentence, we recommend that it neither
221 start with a capital nor end with a full stop (period).  It should also not
222 begin with an article, either definite (the) or indefinite (a or an).
223 </para>
224 <para>
225 It might help to imagine that the synopsis is combined with the package name in
226 the following way:
227 </para>
228 <screen>
229 <replaceable>package-name</replaceable> is a <replaceable>synopsis</replaceable>.
230 </screen>
231 <para>
232 Alternatively, it might make sense to think of it as
233 </para>
234 <screen>
235 <replaceable>package-name</replaceable> is <replaceable>synopsis</replaceable>.
236 </screen>
237 <para>
238 or, if the package name itself is a plural (such as developers-tools)
239 </para>
240 <screen>
241 <replaceable>package-name</replaceable> are <replaceable>synopsis</replaceable>.
242 </screen>
243 <para>
244 This way of forming a sentence from the package name and synopsis should be
245 considered as a heuristic and not a strict rule.  There are some cases where it
246 doesn't make sense to try to form a sentence.
247 </para>
248 </section>
250 <section id="bpp-pkg-desc">
251 <title>The long description</title>
252 <para>
253 The long description is the primary information available to the user about a
254 package before they install it.  It should provide all the information needed
255 to let the user decide whether to install the package.  Assume that the user
256 has already read the package synopsis.
257 </para>
258 <para>
259 The long description should consist of full and complete sentences.
260 </para>
261 <para>
262 The first paragraph of the long description should answer the following
263 questions: what does the package do?  what task does it help the user
264 accomplish?  It is important to describe this in a non-technical way, unless of
265 course the audience for the package is necessarily technical.
266 </para>
267 <para>
268 The following paragraphs should answer the following questions: Why do I as a
269 user need this package?  What other features does the package have?  What
270 outstanding features and deficiencies are there compared to other packages
271 (e.g., if you need X, use Y instead)?  Is this package related to other
272 packages in some way that is not handled by the package manager (e.g., this is
273 the client for the foo server)?
274 </para>
275 <para>
276 Be careful to avoid spelling and grammar mistakes.  Ensure that you spell-check
277 it.  Both <command>ispell</command> and <command>aspell</command> have special
278 modes for checking <filename>debian/control</filename> files:
279 </para>
280 <screen>
281  -d american -g debian/control
282 </screen>
283 <screen>
284  -d en -D -c debian/control
285 </screen>
286 <para>
287 Users usually expect these questions to be answered in the package description:
288 </para>
289 <itemizedlist>
290 <listitem>
291 <para>
292 What does the package do?  If it is an add-on to another package, then the
293 short description of the package we are an add-on to should be put in here.
294 </para>
295 </listitem>
296 <listitem>
297 <para>
298 Why should I want this package?  This is related to the above, but not the same
299 (this is a mail user agent; this is cool, fast, interfaces with PGP and LDAP
300 and IMAP, has features X, Y, and Z).
301 </para>
302 </listitem>
303 <listitem>
304 <para>
305 If this package should not be installed directly, but is pulled in by another
306 package, this should be mentioned.
307 </para>
308 </listitem>
309 <listitem>
310 <para>
311 If the package is experimental, or there are other reasons it should not be
312 used, if there are other packages that should be used instead, it should be
313 here as well.
314 </para>
315 </listitem>
316 <listitem>
317 <para>
318 How is this package different from the competition?  Is it a better
319 implementation?  more features?  different features?  Why should I choose this
320 package.
321 </para>
322 </listitem>
323 <!-- FIXME: what's this?
324 (the second questions is about the class of packages, and
325 this about this particular package, if you have information related to both).
326 -->
327 </itemizedlist>
328 </section>
330 <section id="bpp-upstream-info">
331 <title>Upstream home page</title>
332 <para>
333 We recommend that you add the URL for the package's home page to the package
334 description in <filename>debian/control</filename>.  This information should be
335 added at the end of description, using the following format:
336 </para>
337 <screen>
338  .
339   Homepage:
340 </screen>
341 <para>
342 Note the spaces prepending the line, which serves to break the lines correctly.
343 To see an example of how this displays, see <ulink
344 url=""></ulink>.
345 </para>
346 <para>
347 If there is no home page for the software, this should naturally be left out.
348 </para>
349 <para>
350 Note that we expect this field will eventually be replaced by a proper
351 <filename>debian/control</filename> field understood by <command>dpkg</command>
352 and <literal></literal>.  If you don't want to bother
353 migrating the home page from the description to this field, you should probably
354 wait until that is available.  Please make sure that this line matches the
355 regular expression <literal>/^ Homepage: [^ ]*$/</literal>, as this allows
356 <filename></filename> to parse it correctly.
357 </para>
358 </section>
360 <section id="bpp-vcs">
361 <title>Version Control System location</title>
362 <para>
363 There are additional fields for the location of the Version Control System in
364 <filename>debian/control</filename>.
365 </para>
366 <section id="s6.2.5.1">
367 <title>XS-Vcs-Browser</title>
368 <para>
369 Value of this field should be a <literal>http://</literal> URL pointing to a
370 web-browsable copy of the Version Control System repository used to maintain
371 the given package, if available.
372 </para>
373 <para>
374 The information is meant to be useful for the final user, willing to browse the
375 latest work done on the package (e.g.  when looking for the patch fixing a bug
376 tagged as <literal>pending</literal> in the bug tracking system).
377 </para>
378 </section>
380 <section id="s6.2.5.2">
381 <title>XS-Vcs-*</title>
382 <para>
383 Value of this field should be a string identifying unequivocally the location
384 of the Version Control System repository used to maintain the given package, if
385 available.  <literal>*</literal> identify the Version Control System; currently
386 the following systems are supported by the package tracking system:
387 <literal>arch</literal>, <literal>bzr</literal> (Bazaar),
388 <literal>cvs</literal>, <literal>darcs</literal>, <literal>git</literal>,
389 <literal>hg</literal> (Mercurial), <literal>mtn</literal> (Monotone),
390 <literal>svn</literal> (Subversion).  It is allowed to specify different VCS
391 fields for the same package: they will all be shown in the PTS web interface.
392 </para>
393 <para>
394 The information is meant to be useful for a user knowledgeable in the given
395 Version Control System and willing to build the current version of a package
396 from the VCS sources.  Other uses of this information might include automatic
397 building of the latest VCS version of the given package.  To this end the
398 location pointed to by the field should better be version agnostic and point to
399 the main branch (for VCSs supporting such a concept).  Also, the location
400 pointed to should be accessible to the final user; fulfilling this requirement
401 might imply pointing to an anonymous access of the repository instead of
402 pointing to an SSH-accessible version of the same.
403 </para>
404 <para>
405 In the following example, an instance of the field for a Subversion repository
406 of the <systemitem role="package">vim</systemitem> package is shown.  Note how
407 the URL is in the <literal>svn://</literal> scheme (instead of
408 <literal>svn+ssh://</literal>) and how it points to the
409 <filename>trunk/</filename> branch.  The use of the
410 <literal>XS-Vcs-Browser</literal> field described above is also shown.
411 </para>
412 <screen>
413   Source: vim
414   Section: editors
415   Priority: optional
416   &lt;snip&gt;
417   XS-Vcs-Svn: svn://
418   XS-Vcs-Browser:
419 </screen>
420 </section>
422 </section>
424 </section>
426 <section id="bpp-debian-changelog">
427 <title>Best practices for <filename>debian/changelog</filename></title>
428 <para>
429 The following practices supplement the <ulink
430 url="">Policy
431 on changelog files</ulink>.
432 </para>
433 <section id="bpp-changelog-do">
434 <title>Writing useful changelog entries</title>
435 <para>
436 The changelog entry for a package revision documents changes in that revision,
437 and only them.  Concentrate on describing significant and user-visible changes
438 that were made since the last version.
439 </para>
440 <para>
441 Focus on <emphasis>what</emphasis> was changed — who, how and when are
442 usually less important.  Having said that, remember to politely attribute
443 people who have provided notable help in making the package (e.g., those who
444 have sent in patches).
445 </para>
446 <para>
447 There's no need to elaborate the trivial and obvious changes.  You can also
448 aggregate several changes in one entry.  On the other hand, don't be overly
449 terse if you have undertaken a major change.  Be especially clear if there are
450 changes that affect the behaviour of the program.  For further explanations,
451 use the <filename>README.Debian</filename> file.
452 </para>
453 <para>
454 Use common English so that the majority of readers can comprehend it.  Avoid
455 abbreviations, tech-speak and jargon when explaining changes that close bugs,
456 especially for bugs filed by users that did not strike you as particularly
457 technically savvy.  Be polite, don't swear.
458 </para>
459 <para>
460 It is sometimes desirable to prefix changelog entries with the names of the
461 files that were changed.  However, there's no need to explicitly list each and
462 every last one of the changed files, especially if the change was small or
463 repetitive.  You may use wildcards.
464 </para>
465 <para>
466 When referring to bugs, don't assume anything.  Say what the problem was, how
467 it was fixed, and append the closes: #nnnnn string.  See <xref
468 linkend="upload-bugfix"/> for more information.
469 </para>
470 </section>
472 <section id="bpp-changelog-misconceptions">
473 <title>Common misconceptions about changelog entries</title>
474 <para>
475 The changelog entries should <emphasis role="strong">not</emphasis> document
476 generic packaging issues (Hey, if you're looking for foo.conf, it's in
477 /etc/blah/.), since administrators and users are supposed to be at least
478 remotely acquainted with how such things are generally arranged on Debian
479 systems.  Do, however, mention if you change the location of a configuration
480 file.
481 </para>
482 <para>
483 The only bugs closed with a changelog entry should be those that are actually
484 fixed in the same package revision.  Closing unrelated bugs in the changelog is
485 bad practice.  See <xref linkend="upload-bugfix"/> .
486 </para>
487 <para>
488 The changelog entries should <emphasis role="strong">not</emphasis> be used for
489 random discussion with bug reporters (I don't see segfaults when starting foo
490 with option bar; send in more info), general statements on life, the universe
491 and everything (sorry this upload took me so long, but I caught the flu), or
492 pleas for help (the bug list on this package is huge, please lend me a hand).
493 Such things usually won't be noticed by their target audience, but may annoy
494 people who wish to read information about actual changes in the package.  See
495 <xref linkend="bug-answering"/> for more information on how to use the bug
496 tracking system.
497 </para>
498 <para>
499 It is an old tradition to acknowledge bugs fixed in non-maintainer uploads in
500 the first changelog entry of the proper maintainer upload.  As we have version
501 tracking now, it is enough to keep the NMUed changelog entries and just mention
502 this fact in your own changelog entry.
503 </para>
504 </section>
506 <section id="bpp-changelog-errors">
507 <title>Common errors in changelog entries</title>
508 <para>
509 The following examples demonstrate some common errors or examples of bad style
510 in changelog entries.
511 </para>
512 <screen>
513   * Fixed all outstanding bugs.
514 </screen>
515 <para>
516 This doesn't tell readers anything too useful, obviously.
517 </para>
518 <screen>
519   * Applied patch from Jane Random.
520 </screen>
521 <para>
522 What was the patch about?
523 </para>
524 <screen>
525   * Late night install target overhaul.
526 </screen>
527 <para>
528 Overhaul which accomplished what?  Is the mention of late night supposed to
529 remind us that we shouldn't trust that code?
530 </para>
531 <screen>
532   * Fix vsync FU w/ ancient CRTs.
533 </screen>
534 <para>
535 Too many acronyms, and it's not overly clear what the, uh, fsckup (oops, a
536 curse word!) was actually about, or how it was fixed.
537 </para>
538 <screen>
539   * This is not a bug, closes: #nnnnnn.
540 </screen>
541 <para>
542 First of all, there's absolutely no need to upload the package to convey this
543 information; instead, use the bug tracking system.  Secondly, there's no
544 explanation as to why the report is not a bug.
545 </para>
546 <screen>
547   * Has been fixed for ages, but I forgot to close; closes: #54321.
548 </screen>
549 <para>
550 If for some reason you didn't mention the bug number in a previous changelog
551 entry, there's no problem, just close the bug normally in the BTS.  There's no
552 need to touch the changelog file, presuming the description of the fix is
553 already in (this applies to the fixes by the upstream authors/maintainers as
554 well, you don't have to track bugs that they fixed ages ago in your changelog).
555 </para>
556 <screen>
557   * Closes: #12345, #12346, #15432
558 </screen>
559 <para>
560 Where's the description?  If you can't think of a descriptive message, start by
561 inserting the title of each different bug.
562 </para>
563 </section>
565 <section id="bpp-news-debian">
566 <title>Supplementing changelogs with NEWS.Debian files</title>
567 <para>
568 Important news about changes in a package can also be put in NEWS.Debian files.
569 The news will be displayed by tools like apt-listchanges, before all the rest
570 of the changelogs.  This is the preferred means to let the user know about
571 significant changes in a package.  It is better than using debconf notes since
572 it is less annoying and the user can go back and refer to the NEWS.Debian file
573 after the install.  And it's better than listing major changes in
574 README.Debian, since the user can easily miss such notes.
575 </para>
576 <para>
577 The file format is the same as a debian changelog file, but leave off the
578 asterisks and describe each news item with a full paragraph when necessary
579 rather than the more concise summaries that would go in a changelog.  It's a
580 good idea to run your file through dpkg-parsechangelog to check its formatting
581 as it will not be automatically checked during build as the changelog is.  Here
582 is an example of a real NEWS.Debian file:
583 </para>
584 <screen>
585  (3.0pl1-74) unstable; urgency=low
587     The checksecurity script is no longer included with the cron package:
588     it now has its own package, checksecurity. If you liked the
589     functionality provided with that script, please install the new
590     package.
592  -- Steve Greenland &lt;;  Sat,  6 Sep 2003 17:15:03 -0500
593 </screen>
594 <para>
595 The NEWS.Debian file is installed as
596 /usr/share/doc/&lt;package&gt;/NEWS.Debian.gz.  It is compressed, and always
597 has that name even in Debian native packages.  If you use debhelper,
598 dh_installchangelogs will install debian/NEWS files for you.
599 </para>
600 <para>
601 Unlike changelog files, you need not update NEWS.Debian files with every
602 release.  Only update them if you have something particularly newsworthy that
603 user should know about.  If you have no news at all, there's no need to ship a
604 NEWS.Debian file in your package.  No news is good news!
605 </para>
606 </section>
608 </section>
610 <!--
611 <section id="pkg-mgmt-cvs">
612 <title>Managing a package with CVS</title>
613 <para>
614 FIXME: presentation of cvs-buildpackage, updating sources
615 via CVS (debian/rules refresh).
616 <ulink url="">""</ulink>
617 </para>
618 </section>
619 -->
621 <section id="bpp-debian-maint-scripts">
622 <title>Best practices for maintainer scripts</title>
623 <para>
624 Maintainer scripts include the files <filename>debian/postinst</filename>,
625 <filename>debian/preinst</filename>, <filename>debian/prerm</filename> and
626 <filename>debian/postrm</filename>.  These scripts take care of any package
627 installation or deinstallation setup which isn't handled merely by the creation
628 or removal of files and directories.  The following instructions supplement the
629 <ulink url="">Debian Policy</ulink>.
630 </para>
631 <para>
632 Maintainer scripts must be idempotent.  That means that you need to make sure
633 nothing bad will happen if the script is called twice where it would usually be
634 called once.
635 </para>
636 <para>
637 Standard input and output may be redirected (e.g.  into pipes) for logging
638 purposes, so don't rely on them being a tty.
639 </para>
640 <para>
641 All prompting or interactive configuration should be kept to a minimum.  When
642 it is necessary, you should use the <systemitem
643 role="package">debconf</systemitem> package for the interface.  Remember that
644 prompting in any case can only be in the <literal>configure</literal> stage of
645 the <filename>postinst</filename> script.
646 </para>
647 <para>
648 Keep the maintainer scripts as simple as possible.  We suggest you use pure
649 POSIX shell scripts.  Remember, if you do need any bash features, the
650 maintainer script must have a bash shebang line.  POSIX shell or Bash are
651 preferred to Perl, since they enable <systemitem
652 role="package">debhelper</systemitem> to easily add bits to the scripts.
653 </para>
654 <para>
655 If you change your maintainer scripts, be sure to test package removal, double
656 installation, and purging.  Be sure that a purged package is completely gone,
657 that is, it must remove any files created, directly or indirectly, in any
658 maintainer script.
659 </para>
660 <para>
661 If you need to check for the existence of a command, you should use something
662 like
663 </para>
664 <screen>
665  [ -x /usr/sbin/install-docs ]; then ...
666 </screen>
667 <para>
668 If you don't wish to hard-code the path of a command in your maintainer script,
669 the following POSIX-compliant shell function may help:
670 </para>
671 <screen>
672 () {
673     OLDIFS=$IFS
674     IFS=:
675     for p in $PATH; do
676         if [ -x $p/$* ]; then
677             IFS=$OLDIFS
678             return 0
679         fi
680     done
681     IFS=$OLDIFS
682     return 1
683 }
684 </screen>
685 <para>
686 You can use this function to search <literal>$PATH</literal> for a command
687 name, passed as an argument.  It returns true (zero) if the command was found,
688 and false if not.  This is really the most portable way, since <literal>command
689 -v</literal>, <command>type</command>, and <command>which</command> are not
690 POSIX.
691 </para>
692 <para>
693 While <command>which</command> is an acceptable alternative, since it is from
694 the required <systemitem role="package">debianutils</systemitem> package, it's
695 not on the root partition.  That is, it's in <filename>/usr/bin</filename>
696 rather than <filename>/bin</filename>, so one can't use it in scripts which are
697 run before the <filename>/usr</filename> partition is mounted.  Most scripts
698 won't have this problem, though.
699 </para>
700 </section>
702 <section id="bpp-config-mgmt">
703 <title>Configuration management with <systemitem role="package">debconf</systemitem></title>
704 <para>
705 <systemitem role="package">Debconf</systemitem> is a configuration management
706 system which can be used by all the various packaging scripts
707 (<filename>postinst</filename> mainly) to request feedback from the user
708 concerning how to configure the package.  Direct user interactions must now be
709 avoided in favor of <systemitem role="package">debconf</systemitem>
710 interaction.  This will enable non-interactive installations in the future.
711 </para>
712 <para>
713 Debconf is a great tool but it is often poorly used.  Many common mistakes are
714 listed in the <citerefentry> <refentrytitle>debconf-devel</refentrytitle>
715 <manvolnum>7</manvolnum> </citerefentry> man page.  It is something that you
716 must read if you decide to use debconf.  Also, we document some best practices
717 here.
718 </para>
719 <para>
720 These guidelines include some writing style and typography recommendations,
721 general considerations about debconf usage as well as more specific
722 recommendations for some parts of the distribution (the installation system for
723 instance).
724 </para>
725 <section id="s6.5.1">
726 <title>Do not abuse debconf</title>
727 <para>
728 Since debconf appeared in Debian, it has been widely abused and several
729 criticisms received by the Debian distribution come from debconf abuse with the
730 need of answering a wide bunch of questions before getting any little thing
731 installed.
732 </para>
733 <para>
734 Keep usage notes to what they belong: the NEWS.Debian, or README.Debian file.
735 Only use notes for important notes which may directly affect the package
736 usability.  Remember that notes will always block the install until confirmed
737 or bother the user by email.
738 </para>
739 <para>
740 Carefully choose the questions priorities in maintainer scripts.  See
741 <citerefentry> <refentrytitle>debconf-devel</refentrytitle>
742 <manvolnum>7</manvolnum> </citerefentry> for details about priorities.  Most
743 questions should use medium and low priorities.
744 </para>
745 </section>
747 <section id="s6.5.2">
748 <title>General recommendations for authors and translators</title>
749 <section id="s6.5.2.1">
750 <title>Write correct English</title>
751 <para>
752 Most Debian package maintainers are not native English speakers.  So, writing
753 properly phrased templates may not be easy for them.
754 </para>
755 <para>
756 Please use (and abuse) <email></email>
757 mailing list.  Have your templates proofread.
758 </para>
759 <para>
760 Badly written templates give a poor image of your package, of your work...or
761 even of Debian itself.
762 </para>
763 <para>
764 Avoid technical jargon as much as possible.  If some terms sound common to you,
765 they may be impossible to understand for others.  If you cannot avoid them, try
766 to explain them (use the extended description).  When doing so, try to balance
767 between verbosity and simplicity.
768 </para>
769 </section>
771 <section id="s6.5.2.2">
772 <title>Be kind to translators</title>
773 <para>
774 Debconf templates may be translated.  Debconf, along with its sister package
775 <command>po-debconf</command> offers a simple framework for getting templates
776 translated by translation teams or even individuals.
777 </para>
778 <para>
779 Please use gettext-based templates.  Install <systemitem
780 role="package">po-debconf</systemitem> on your development system and read its
781 documentation (man po-debconf is a good start).
782 </para>
783 <para>
784 Avoid changing templates too often.  Changing templates text induces more work
785 to translators which will get their translation fuzzied.  If you plan changes
786 to your original templates, please contact translators.  Most active
787 translators are very responsive and getting their work included along with your
788 modified templates will save you additional uploads.  If you use gettext-based
789 templates, the translator's name and e-mail addresses are mentioned in the po
790 files headers.
791 </para>
792 <para>
793 The use of the <command>podebconf-report-po</command> from the po-debconf
794 package is highly recommended to warn translators which have incomplete
795 translations and request them for updates.
796 </para>
797 <para>
798 If in doubt, you may also contact the translation team for a given language
799 (, or the
800 <email></email> mailing list.
801 </para>
802 <para>
803 Calls for translations posted to <email></email>
804 with the <filename>debian/po/templates.pot</filename> file attached or
805 referenced in a URL are encouraged.  Be sure to mentions in these calls for new
806 translations which languages you have existing translations for, in order to
807 avoid duplicate work.
808 </para>
809 </section>
811 <section id="s6.5.2.3">
812 <title>Unfuzzy complete translations when correcting typos and spelling</title>
813 <para>
814 When the text of a debconf template is corrected and you are <emphasis
815 role="strong">sure</emphasis> that the change does <emphasis
816 role="strong">not</emphasis> affect translations, please be kind to translators
817 and unfuzzy their translations.
818 </para>
819 <para>
820 If you don't do so, the whole template will not be translated as long as a
821 translator will send you an update.
822 </para>
823 <para>
824 To <emphasis role="strong">unfuzzy</emphasis> translations, you can proceed the
825 following way:
826 </para>
827 <orderedlist numeration="arabic">
828 <listitem>
829 <para>
830 Put all incomplete PO files out of the way.  You can check the completeness by
831 using (needs the <systemitem role="package">gettext</systemitem> package
832 installed):
833 </para>
834 <screen>
835  i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null
836 --statistics $i; done
837 </screen>
838 </listitem>
839 <listitem>
840 <para>
841 move all files which report either fuzzy strings to a temporary place.  Files
842 which report no fuzzy strings (only translated and untranslated) will be kept
843 in place.
844 </para>
845 </listitem>
846 <listitem>
847 <para>
848 now <emphasis role="strong">and now only</emphasis>, modify the template for
849 the typos and check again that translation are not impacted (typos, spelling
850 errors, sometimes typographical corrections are usually OK)
851 </para>
852 </listitem>
853 <listitem>
854 <para>
855 run <command>debconf-updatepo</command>.  This will fuzzy all strings you
856 modified in translations.  You can see this by running the above again
857 </para>
858 </listitem>
859 <listitem>
860 <para>
861 use the following command:
862 </para>
863 <screen>
864  i in debian/po/*po; do msgattrib --output-file=$i --clear-fuzzy $i; done
865 </screen>
866 </listitem>
867 <listitem>
868 <para>
869 move back to debian/po the files which showed fuzzy strings in the first step
870 </para>
871 </listitem>
872 <listitem>
873 <para>
874 run <command>debconf-updatepo</command> again
875 </para>
876 </listitem>
877 </orderedlist>
878 </section>
880 <section id="s6.5.2.4">
881 <title>Do not make assumptions about interfaces</title>
882 <para>
883 Templates text should not make reference to widgets belonging to some debconf
884 interfaces.  Sentences like If you answer Yes...  have no meaning for users of
885 graphical interfaces which use checkboxes for boolean questions.
886 </para>
887 <para>
888 String templates should also avoid mentioning the default values in their
889 description.  First, because this is redundant with the values seen by the
890 users.  Also, because these default values may be different from the maintainer
891 choices (for instance, when the debconf database was preseeded).
892 </para>
893 <para>
894 More generally speaking, try to avoid referring to user actions.  Just give
895 facts.
896 </para>
897 </section>
899 <section id="s6.5.2.5">
900 <title>Do not use first person</title>
901 <para>
902 You should avoid the use of first person (I will do this...  or We
903 recommend...).  The computer is not a person and the Debconf templates do not
904 speak for the Debian developers.  You should use neutral construction.  Those
905 of you who already wrote scientific publications, just write your templates
906 like you would write a scientific paper.  However, try using action voice if
907 still possible, like Enable this if ...  instead of This can be enabled if ....
908 </para>
909 </section>
911 <section id="s6.5.2.6">
912 <title>Be gender neutral</title>
913 <para>
914 The world is made of men and women.  Please use gender-neutral constructions in
915 your writing.
916 </para>
917 </section>
919 </section>
921 <section id="s6.5.3">
922 <title>Templates fields definition</title>
923 <para>
924 This part gives some information which is mostly taken from the <citerefentry>
925 <refentrytitle>debconf-devel</refentrytitle> <manvolnum>7</manvolnum>
926 </citerefentry> manual page.
927 </para>
928 <section id="s6.5.3.1">
929 <title>Type</title>
930 <section id="s6.">
931 <title>string:</title>
932 <para>
933 Results in a free-form input field that the user can type any string into.
934 </para>
935 </section>
937 <section id="s6.">
938 <title>password:</title>
939 <para>
940 Prompts the user for a password.  Use this with caution; be aware that the
941 password the user enters will be written to debconf's database.  You should
942 probably clean that value out of the database as soon as is possible.
943 </para>
944 </section>
946 <section id="s6.">
947 <title>boolean:</title>
948 <para>
949 A true/false choice.  Remember: true/false, <emphasis role="strong">not
950 yes/no</emphasis>...
951 </para>
952 </section>
954 <section id="s6.">
955 <title>select:</title>
956 <para>
957 A choice between one of a number of values.  The choices must be specified in a
958 field named 'Choices'.  Separate the possible values with commas and spaces,
959 like this: Choices: yes, no, maybe
960 </para>
961 </section>
963 <section id="s6.">
964 <title>multiselect:</title>
965 <para>
966 Like the select data type, except the user can choose any number of items from
967 the choices list (or chose none of them).
968 </para>
969 </section>
971 <section id="s6.">
972 <title>note:</title>
973 <para>
974 Rather than being a question per se, this datatype indicates a note that can be
975 displayed to the user.  It should be used only for important notes that the
976 user really should see, since debconf will go to great pains to make sure the
977 user sees it; halting the install for them to press a key, and even mailing the
978 note to them in some cases.
979 </para>
980 </section>
982 <section id="s6.">
983 <title>text:</title>
984 <para>
985 This type is now considered obsolete: don't use it.
986 </para>
987 </section>
989 <section id="s6.">
990 <title>error:</title>
991 <para>
992 This type is designed to handle error messages.  It is mostly similar to the
993 note type.  Frontends may present it differently (for instance, the dialog
994 frontend of cdebconf draws a red screen instead of the usual blue one).
995 </para>
996 <para>
997 It is recommended to use this type for any message that needs user attention
998 for a correction of any kind.
999 </para>
1000 </section>
1002 </section>
1004 <section id="s6.5.3.2">
1005 <title>Description: short and extended description</title>
1006 <para>
1007 Template descriptions have two parts: short and extended.  The short
1008 description is in the Description: line of the template.
1009 </para>
1010 <para>
1011 The short description should be kept short (50 characters or so) so that it may
1012 be accomodated by most debconf interfaces.  Keeping it short also helps
1013 translators, as usually translations tend to end up being longer than the
1014 original.
1015 </para>
1016 <para>
1017 The short description should be able to stand on its own.  Some interfaces do
1018 not show the long description by default, or only if the user explicitely asks
1019 for it or even do not show it at all.  Avoid things like What do you want to
1020 do?
1021 </para>
1022 <para>
1023 The short description does not necessarily have to be a full sentence.  This is
1024 part of the keep it short and efficient recommendation.
1025 </para>
1026 <para>
1027 The extended description should not repeat the short description word for word.
1028 If you can't think up a long description, then first, think some more.  Post to
1029 debian-devel.  Ask for help.  Take a writing class!  That extended description
1030 is important.  If after all that you still can't come up with anything, leave
1031 it blank.
1032 </para>
1033 <para>
1034 The extended description should use complete sentences.  Paragraphs should be
1035 kept short for improved readability.  Do not mix two ideas in the same
1036 paragraph but rather use another paragraph.
1037 </para>
1038 <para>
1039 Don't be too verbose.  User tend to ignore too long screens.  20 lines are by
1040 experience a border you shouldn't cross, because that means that in the
1041 classical dialog interface, people will need to scroll, and lot of people just
1042 don't do that.
1043 </para>
1044 <para>
1045 The extended description should <emphasis role="strong">never</emphasis>
1046 include a question.
1047 </para>
1048 <para>
1049 For specific rules depending on templates type (string, boolean, etc.), please
1050 read below.
1051 </para>
1052 </section>
1054 <section id="s6.5.3.3">
1055 <title>Choices</title>
1056 <para>
1057 This field should be used for Select and Multiselect types.  It contains the
1058 possible choices which will be presented to users.  These choices should be
1059 separated by commas.
1060 </para>
1061 </section>
1063 <section id="s6.5.3.4">
1064 <title>Default</title>
1065 <para>
1066 This field is optional.  It contains the default answer for string, select and
1067 multiselect templates.  For multiselect templates, it may contain a
1068 comma-separated list of choices.
1069 </para>
1070 </section>
1072 </section>
1074 <section id="s6.5.4">
1075 <title>Templates fields specific style guide</title>
1076 <section id="s6.5.4.1">
1077 <title>Type field</title>
1078 <para>
1079 No specific indication except: use the appropriate type by referring to the
1080 previous section.
1081 </para>
1082 </section>
1084 <section id="s6.5.4.2">
1085 <title>Description field</title>
1086 <para>
1087 Below are specific instructions for properly writing the Description (short and
1088 extended) depending on the template type.
1089 </para>
1090 <section id="s6.">
1091 <title>String/password templates</title>
1092 <itemizedlist>
1093 <listitem>
1094 <para>
1095 The short description is a prompt and <emphasis role="strong">not</emphasis> a
1096 title.  Avoid question style prompts (IP Address?) in favour of opened prompts
1097 (IP address:).  The use of colons is recommended.
1098 </para>
1099 </listitem>
1100 <listitem>
1101 <para>
1102 The extended description is a complement to the short description.  In the
1103 extended part, explain what is being asked, rather than ask the same question
1104 again using longer words.  Use complete sentences.  Terse writing style is
1105 strongly discouraged.
1106 </para>
1107 </listitem>
1108 </itemizedlist>
1109 </section>
1111 <section id="s6.">
1112 <title>Boolean templates</title>
1113 <itemizedlist>
1114 <listitem>
1115 <para>
1116 The short description should be phrased in the form of a question which should
1117 be kept short and should generally end with a question mark.  Terse writing
1118 style is permitted and even encouraged if the question is rather long (remember
1119 that translations are often longer than original versions)
1120 </para>
1121 </listitem>
1122 <listitem>
1123 <para>
1124 Again, please avoid referring to specific interface widgets.  A common mistake
1125 for such templates is if you answer Yes-type constructions.
1126 </para>
1127 </listitem>
1128 </itemizedlist>
1129 </section>
1131 <section id="s6.">
1132 <title>Select/Multiselect</title>
1133 <itemizedlist>
1134 <listitem>
1135 <para>
1136 The short description is a prompt and <emphasis role="strong">not</emphasis> a
1137 title.  Do <emphasis role="strong">not</emphasis> use useless Please choose...
1138 constructions.  Users are clever enough to figure out they have to choose
1139 something...:)
1140 </para>
1141 </listitem>
1142 <listitem>
1143 <para>
1144 The extended description will complete the short description.  It may refer to
1145 the available choices.  It may also mention that the user may choose more than
1146 one of the available choices, if the template is a multiselect one (although
1147 the interface often makes this clear).
1148 </para>
1149 </listitem>
1150 </itemizedlist>
1151 </section>
1153 <section id="s6.">
1154 <title>Notes</title>
1155 <itemizedlist>
1156 <listitem>
1157 <para>
1158 The short description should be considered to be a *title*.
1159 </para>
1160 </listitem>
1161 <listitem>
1162 <para>
1163 The extended description is what will be displayed as a more detailed
1164 explanation of the note.  Phrases, no terse writing style.
1165 </para>
1166 </listitem>
1167 <listitem>
1168 <para>
1169 <emphasis role="strong">Do not abuse debconf.</emphasis> Notes are the most
1170 common way to abuse debconf.  As written in debconf-devel manual page: it's
1171 best to use them only for warning about very serious problems.  The NEWS.Debian
1172 or README.Debian files are the appropriate location for a lot of notes.  If, by
1173 reading this, you consider converting your Note type templates to entries in
1174 NEWS/Debian or README.Debian, plus consider keeping existing translations for
1175 the future.
1176 </para>
1177 </listitem>
1178 </itemizedlist>
1179 </section>
1181 </section>
1183 <section id="s6.5.4.3">
1184 <title>Choices field</title>
1185 <para>
1186 If the Choices are likely to change often, please consider using the __Choices
1187 trick.  This will split each individual choice into a single string, which will
1188 considerably help translators for doing their work.
1189 </para>
1190 </section>
1192 <section id="s6.5.4.4">
1193 <title>Default field</title>
1194 <para>
1195 If the default value, for a select template, is likely to vary depending on the
1196 user language (for instance, if the choice is a language choice), please use
1197 the _DefaultChoice trick.
1198 </para>
1199 <para>
1200 This special field allow translators to put the most appropriate choice
1201 according to their own language.  It will become the default choice when their
1202 language is used while your own mentioned Default Choice will be used chan
1203 using English.
1204 </para>
1205 <para>
1206 Example, taken from the geneweb package templates:
1207 </para>
1208 <screen>
1209 : geneweb/lang
1210 Type: select
1211 __Choices: Afrikaans (af), Bulgarian (bg), Catalan (ca), Chinese (zh), Czech (cs), Danish (da), Dutch (nl), English (en), Esperanto (eo), Estonian (et), Finnish (fi), French (fr), German (de), Hebrew (he), Icelandic (is), Italian (it), Latvian (lv), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv)
1212 # This is the default choice. Translators may put their own language here
1213 # instead of the default.
1214 # WARNING : you MUST use the ENGLISH FORM of your language
1215 # For instance, the french translator will need to put French (fr) here.
1216 _DefaultChoice: English (en)[ translators, please see comment in PO files]
1217 _Description: Geneweb default language:
1218 </screen>
1219 <para>
1220 Note the use of brackets which allow internal comments in debconf fields.  Also
1221 note the use of comments which will show up in files the translators will work
1222 with.
1223 </para>
1224 <para>
1225 The comments are needed as the DefaultChoice trick is a bit confusing: the
1226 translators may put their own choice
1227 </para>
1228 </section>
1230 <section id="s6.5.4.5">
1231 <title>Default field</title>
1232 <para>
1233 Do NOT use empty default field.  If you don't want to use default values, do
1234 not use Default at all.
1235 </para>
1236 <para>
1237 If you use po-debconf (and you <emphasis role="strong">should</emphasis>, see
1238 2.2), consider making this field translatable, if you think it may be
1239 translated.
1240 </para>
1241 <para>
1242 If the default value may vary depending on language/country (for instance the
1243 default value for a language choice), consider using the special _DefaultChoice
1244 type documented in <citerefentry> <refentrytitle>po-debconf</refentrytitle>
1245 <manvolnum>7</manvolnum> </citerefentry>).
1246 </para>
1247 </section>
1249 </section>
1251 </section>
1253 <section id="bpp-i18n">
1254 <title>Internationalization</title>
1255 <section id="bpp-i18n-debconf">
1256 <title>Handling debconf translations</title>
1257 <para>
1258 Like porters, translators have a difficult task.  They work on many packages
1259 and must collaborate with many different maintainers.  Moreover, most of the
1260 time, they are not native English speakers, so you may need to be particularly
1261 patient with them.
1262 </para>
1263 <para>
1264 The goal of <systemitem role="package">debconf</systemitem> was to make
1265 packages configuration easier for maintainers and for users.  Originally,
1266 translation of debconf templates was handled with
1267 <command>debconf-mergetemplate</command>.  However, that technique is now
1268 deprecated; the best way to accomplish <systemitem
1269 role="package">debconf</systemitem> internationalization is by using the
1270 <systemitem role="package">po-debconf</systemitem> package.  This method is
1271 easier both for maintainer and translators; transition scripts are provided.
1272 </para>
1273 <para>
1274 Using <systemitem role="package">po-debconf</systemitem>, the translation is
1275 stored in <filename>po</filename> files (drawing from
1276 <command>gettext</command> translation techniques).  Special template files
1277 contain the original messages and mark which fields are translatable.  When you
1278 change the value of a translatable field, by calling
1279 <command>debconf-updatepo</command>, the translation is marked as needing
1280 attention from the translators.  Then, at build time, the
1281 <command>dh_installdebconf</command> program takes care of all the needed magic
1282 to add the template along with the up-to-date translations into the binary
1283 packages.  Refer to the <citerefentry>
1284 <refentrytitle>po-debconf</refentrytitle> <manvolnum>7</manvolnum>
1285 </citerefentry> manual page for details.
1286 </para>
1287 </section>
1289 <section id="bpp-i18n-docs">
1290 <title>Internationalized documentation</title>
1291 <para>
1292 Internationalizing documentation is crucial for users, but a lot of labor.
1293 There's no way to eliminate all that work, but you can make things easier for
1294 translators.
1295 </para>
1296 <para>
1297 If you maintain documentation of any size, its easier for translators if they
1298 have access to a source control system.  That lets translators see the
1299 differences between two versions of the documentation, so, for instance, they
1300 can see what needs to be retranslated.  It is recommended that the translated
1301 documentation maintain a note about what source control revision the
1302 translation is based on.  An interesting system is provided by <ulink
1303 url="\|[amp
1304 ]\|content-type=text/vnd.viewcvs-markup">doc-check</ulink> in the <systemitem
1305 role="package">boot-floppies</systemitem> package, which shows an overview of
1306 the translation status for any given language, using structured comments for
1307 the current revision of the file to be translated and, for a translated file,
1308 the revision of the original file the translation is based on.  You might wish
1309 to adapt and provide that in your CVS area.
1310 </para>
1311 <para>
1312 If you maintain XML or SGML documentation, we suggest that you isolate any
1313 language-independent information and define those as entities in a separate
1314 file which is included by all the different translations.  This makes it much
1315 easier, for instance, to keep URLs up to date across multiple files.
1316 </para>
1317 </section>
1319 </section>
1321 <section id="bpp-common-situations">
1322 <title>Common packaging situations</title>
1323 <!--
1324 <section id="bpp-kernel">
1325 <title>Kernel modules/patches</title>
1326 <para>
1327 FIXME: Heavy use of kernel-package. provide files in
1328 /etc/modutils/ for module configuration.
1329 </para>
1330 </section>
1331 -->
1332 <section id="bpp-autotools">
1333 <title>Packages using <command>autoconf</command>/<command>automake</command></title>
1334 <para>
1335 Keeping <command>autoconf</command>'s <filename>config.sub</filename> and
1336 <filename>config.guess</filename> files up to date is critical for porters,
1337 especially on more volatile architectures.  Some very good packaging practices
1338 for any package using <command>autoconf</command> and/or
1339 <command>automake</command> have been synthesized in
1340 <filename>/usr/share/doc/autotools-dev/README.Debian.gz</filename> from the
1341 <systemitem role="package">autotools-dev</systemitem> package.  You're strongly
1342 encouraged to read this file and to follow the given recommendations.
1343 </para>
1344 </section>
1346 <section id="bpp-libraries">
1347 <title>Libraries</title>
1348 <para>
1349 Libraries are always difficult to package for various reasons.  The policy
1350 imposes many constraints to ease their maintenance and to make sure upgrades
1351 are as simple as possible when a new upstream version comes out.  Breakage in a
1352 library can result in dozens of dependent packages breaking.
1353 </para>
1354 <para>
1355 Good practices for library packaging have been grouped in <ulink
1356 url="">the library
1357 packaging guide</ulink>.
1358 </para>
1359 </section>
1361 <section id="bpp-docs">
1362 <title>Documentation</title>
1363 <para>
1364 Be sure to follow the <ulink
1365 url="">Policy on
1366 documentation</ulink>.
1367 </para>
1368 <para>
1369 If your package contains documentation built from XML or SGML, we recommend you
1370 not ship the XML or SGML source in the binary package(s).  If users want the
1371 source of the documentation, they should retrieve the source package.
1372 </para>
1373 <para>
1374 Policy specifies that documentation should be shipped in HTML format.  We also
1375 recommend shipping documentation in PDF and plain text format if convenient and
1376 if output of reasonable quality is possible.  However, it is generally not
1377 appropriate to ship plain text versions of documentation whose source format is
1378 HTML.
1379 </para>
1380 <para>
1381 Major shipped manuals should register themselves with <systemitem
1382 role="package">doc-base</systemitem> on installation.  See the <systemitem
1383 role="package">doc-base</systemitem> package documentation for more
1384 information.
1385 </para>
1386 </section>
1388 <section id="bpp-other">
1389 <title>Specific types of packages</title>
1390 <para>
1391 Several specific types of packages have special sub-policies and corresponding
1392 packaging rules and practices:
1393 </para>
1394 <itemizedlist>
1395 <listitem>
1396 <para>
1397 Perl related packages have a <ulink
1398 url="">Perl
1399 policy</ulink>, some examples of packages following that policy are <systemitem
1400 role="package">libdbd-pg-perl</systemitem> (binary perl module) or <systemitem
1401 role="package">libmldbm-perl</systemitem> (arch independent perl module).
1402 </para>
1403 </listitem>
1404 <listitem>
1405 <para>
1406 Python related packages have their python policy; see
1407 <filename>/usr/share/doc/python/python-policy.txt.gz</filename> in the
1408 <systemitem role="package">python</systemitem> package.
1409 </para>
1410 </listitem>
1411 <listitem>
1412 <para>
1413 Emacs related packages have the <ulink
1414 url="">emacs
1415 policy</ulink>.
1416 </para>
1417 </listitem>
1418 <listitem>
1419 <para>
1420 Java related packages have their <ulink
1421 url="">java
1422 policy</ulink>.
1423 </para>
1424 </listitem>
1425 <listitem>
1426 <para>
1427 Ocaml related packages have their own policy, found in
1428 <filename>/usr/share/doc/ocaml/ocaml_packaging_policy.gz</filename> from the
1429 <systemitem role="package">ocaml</systemitem> package.  A good example is the
1430 <systemitem role="package">camlzip</systemitem> source package.
1431 </para>
1432 </listitem>
1433 <listitem>
1434 <para>
1435 Packages providing XML or SGML DTDs should conform to the recommendations found
1436 in the <systemitem role="package">sgml-base-doc</systemitem> package.
1437 </para>
1438 </listitem>
1439 <listitem>
1440 <para>
1441 Lisp packages should register themselves with <systemitem
1442 role="package">common-lisp-controller</systemitem>, about which see
1443 <filename>/usr/share/doc/common-lisp-controller/README.packaging</filename>.
1444 </para>
1445 </listitem>
1446 <!-- TODO: mozilla extension policy, once that becomes available -->
1447 </itemizedlist>
1448 </section>
1450 <!--
1451 <section id="custom-config-files">
1452 <title>Custom configuration files</title>
1453 <para>
1454 FIXME: speak of "ucf", explain solution with a template,
1455 explain conf.d directories
1456 </para>
1457 </section>
1458 <section id="config-with-db">
1459 <title>Use of an external database</title>
1460 <para>
1461 FIXME: The software may require a database that you need to setup.
1462 But the database may be local or distant. Thus you can't depend
1463 on a database server but just on the corresponding library.
1465 sympa may be an example package
1466 </para>
1467 </section>
1468 -->
1470 <section id="bpp-archindepdata">
1471 <title>Architecture-independent data</title>
1472 <para>
1473 It is not uncommon to have a large amount of architecture-independent data
1474 packaged with a program.  For example, audio files, a collection of icons,
1475 wallpaper patterns, or other graphic files.  If the size of this data is
1476 negligible compared to the size of the rest of the package, it's probably best
1477 to keep it all in a single package.
1478 </para>
1479 <para>
1480 However, if the size of the data is considerable, consider splitting it out
1481 into a separate, architecture-independent package (_all.deb).  By doing this,
1482 you avoid needless duplication of the same data into eleven or more .debs, one
1483 per each architecture.  While this adds some extra overhead into the
1484 <filename>Packages</filename> files, it saves a lot of disk space on Debian
1485 mirrors.  Separating out architecture-independent data also reduces processing
1486 time of <command>lintian</command> or <command>linda</command> (see <xref
1487 linkend="tools-lint"/> ) when run over the entire Debian archive.
1488 </para>
1489 </section>
1491 <section id="bpp-locale">
1492 <title>Needing a certain locale during build</title>
1493 <para>
1494 If you need a certain locale during build, you can create a temporary file via
1495 this trick:
1496 </para>
1497 <para>
1498 If you set LOCPATH to the equivalent of /usr/lib/locale, and LC_ALL to the name
1499 of the locale you generate, you should get what you want without being root.
1500 Something like this:
1501 </para>
1502 <screen>
1503 =debian/tmpdir/usr/lib/locale
1507 mkdir -p $LOCALE_PATH
1510 # Using the locale
1512 </screen>
1513 </section>
1515 <section id="bpp-transition">
1516 <title>Make transition packages deborphan compliant</title>
1517 <para>
1518 Deborphan is a program for helping users to detect which packages can safely be
1519 removed from the system, i.e.  the ones that have no packages depending on
1520 them.  The default operation is to search only within the libs and oldlibs
1521 sections, to hunt down unused libraries.  But when passed the right argument,
1522 it tries to catch other useless packages.
1523 </para>
1524 <para>
1525 For example, with --guess-dummy, deborphan tries to search all transitional
1526 packages which were needed for upgrade but which can now safely be removed.
1527 For that, it looks for the string dummy or transitional in their short
1528 description.
1529 </para>
1530 <para>
1531 So, when you are creating such a package, please make sure to add this text to
1532 your short description.  If you are looking for examples, just run:
1533 </para>
1534 <screen>
1535 -cache search .|grep dummy
1536 </screen>
1537 <para>
1538 or
1539 </para>
1540 <screen>
1541 -cache search .|grep transitional
1542 </screen>
1543 <para>
1544 .
1545 </para>
1546 </section>
1548 <section id="bpp-origtargz">
1549 <title>Best practices for <filename>orig.tar.gz</filename> files</title>
1550 <para>
1551 There are two kinds of original source tarballs: Pristine source and repackaged
1552 upstream source.
1553 </para>
1554 <section id="pristinesource">
1555 <title>Pristine source</title>
1556 <para>
1557 The defining characteristic of a pristine source tarball is that the
1558 .orig.tar.gz file is byte-for-byte identical to a tarball officially
1559 distributed by the upstream author.  <footnote><para> We cannot prevent
1560 upstream authors from changing the tarball they distribute without also
1561 incrementing the version number, so there can be no guarantee that a pristine
1562 tarball is identical to what upstream <emphasis>currently</emphasis>
1563 distributing at any point in time.  All that can be expected is that it is
1564 identical to something that upstream once <emphasis>did</emphasis> distribute.
1565 If a difference arises later (say, if upstream notices that he wasn't using
1566 maximal comression in his original distribution and then
1567 re-<literal>gzip</literal>s it), that's just too bad.  Since there is no good
1568 way to upload a new .orig.tar.gz for the same version, there is not even any
1569 point in treating this situation as a bug.  </para> </footnote> This makes it
1570 possible to use checksums to easily verify that all changes between Debian's
1571 version and upstream's are contained in the Debian diff.  Also, if the original
1572 source is huge, upstream authors and others who already have the upstream
1573 tarball can save download time if they want to inspect your packaging in
1574 detail.
1575 </para>
1576 <para>
1577 There is no universally accepted guidelines that upstream authors follow
1578 regarding to the directory structure inside their tarball, but
1579 <command>dpkg-source</command> is nevertheless able to deal with most upstream
1580 tarballs as pristine source.  Its strategy is equivalent to the following:
1581 </para>
1582 <orderedlist numeration="arabic">
1583 <listitem>
1584 <para>
1585 It unpacks the tarball in an empty temporary directory by doing
1586 </para>
1587 <screen>
1588  path/to/&lt;packagename&gt;_&lt;upstream-version&gt;.orig.tar.gz | tar xf -
1589 </screen>
1590 </listitem>
1591 <listitem>
1592 <para>
1593 If, after this, the temporary directory contains nothing but one directory and
1594 no other files, <command>dpkg-source</command> renames that directory to
1595 <literal>&lt;packagename&gt;-&lt;upstream-version&gt;(.orig)</literal>.  The
1596 name of the top-level directory in the tarball does not matter, and is
1597 forgotten.
1598 </para>
1599 </listitem>
1600 <listitem>
1601 <para>
1602 Otherwise, the upstream tarball must have been packaged without a common
1603 top-level directory (shame on the upstream author!).  In this case,
1604 <command>dpkg-source</command> renames the temporary directory
1605 <emphasis>itself</emphasis> to
1606 <literal>&lt;packagename&gt;-&lt;upstream-version&gt;(.orig)</literal>.
1607 </para>
1608 </listitem>
1609 </orderedlist>
1610 </section>
1612 <section id="repackagedorigtargz">
1613 <title>Repackaged upstream source</title>
1614 <para>
1615 You <emphasis role="strong">should</emphasis> upload packages with a pristine
1616 source tarball if possible, but there are various reasons why it might not be
1617 possible.  This is the case if upstream does not distribute the source as
1618 gzipped tar at all, or if upstream's tarball contains non-DFSG-free material
1619 that you must remove before uploading.
1620 </para>
1621 <para>
1622 In these cases the developer must construct a suitable .orig.tar.gz file
1623 himself.  We refer to such a tarball as a repackaged upstream source.  Note
1624 that a repackaged upstream source is different from a Debian-native package.  A
1625 repackaged source still comes with Debian-specific changes in a separate
1626 <literal>.diff.gz</literal> and still has a version number composed of
1627 <literal>&lt;upstream-version&gt;</literal> and
1628 <literal>&lt;debian-revision&gt;</literal>.
1629 </para>
1630 <para>
1631 There may be cases where it is desirable to repackage the source even though
1632 upstream distributes a <literal>.tar.gz</literal> that could in principle be
1633 used in its pristine form.  The most obvious is if
1634 <emphasis>significant</emphasis> space savings can be achieved by recompressing
1635 the tar archive or by removing genuinely useless cruft from the upstream
1636 archive.  Use your own discretion here, but be prepared to defend your decision
1637 if you repackage source that could have been pristine.
1638 </para>
1639 <para>
1640 A repackaged .orig.tar.gz
1641 </para>
1642 <orderedlist numeration="arabic">
1643 <listitem>
1644 <para>
1645 <emphasis role="strong">must</emphasis> contain detailed information how the
1646 repackaged source was obtained, and how this can be reproduced in the
1647 <filename>debian/copyright</filename>.  It is also a good idea to provide a
1648 <literal>get-orig-source</literal> target in your
1649 <filename>debian/rules</filename> file that repeats the process, as described
1650 in the Policy Manual, <ulink
1651 url="">Main
1652 building script: debian/rules</ulink>.
1653 </para>
1654 </listitem>
1655 <listitem>
1656 <para>
1657 <emphasis role="strong">should not</emphasis> contain any file that does not
1658 come from the upstream author(s), or whose contents has been changed by you.
1659 <footnote><para> As a special exception, if the omission of non-free files
1660 would lead to the source failing to build without assistance from the Debian
1661 diff, it might be appropriate to instead edit the files, omitting only the
1662 non-free parts of them, and/or explain the situation in a README.Debian-source
1663 <!-- or similarly named -->
1664 file in the root of the source tree.  But in that case please also urge the
1665 upstream author to make the non-free components easier seperable from the rest
1666 of the source.  </para> </footnote>
1667 </para>
1668 </listitem>
1669 <listitem>
1670 <para>
1671 <emphasis role="strong">should</emphasis>, except where impossible for legal
1672 reasons, preserve the entire building and portablility infrastructure provided
1673 by the upstream author.  For example, it is not a sufficient reason for
1674 omitting a file that it is used only when building on MS-DOS.  Similarly, a
1675 Makefile provided by upstream should not be omitted even if the first thing
1676 your <filename>debian/rules</filename> does is to overwrite it by running a
1677 configure script.
1678 </para>
1679 <para>
1680 (<emphasis>Rationale:</emphasis> It is common for Debian users who need to
1681 build software for non-Debian platforms to fetch the source from a Debian
1682 mirror rather than trying to locate a canonical upstream distribution point).
1683 </para>
1684 </listitem>
1685 <listitem>
1686 <para>
1687 <emphasis role="strong">should</emphasis> use
1688 <literal>&lt;packagename&gt;-&lt;upstream-version&gt;.orig</literal> as the
1689 name of the top-level directory in its tarball.  This makes it possible to
1690 distinguish pristine tarballs from repackaged ones.
1691 </para>
1692 </listitem>
1693 <listitem>
1694 <para>
1695 <emphasis role="strong">should</emphasis> be gzipped with maximal compression.
1696 </para>
1697 </listitem>
1698 </orderedlist>
1699 <para>
1700 The canonical way to meet the latter two points is to let <literal>dpkg-source
1701 -b</literal> construct the repackaged tarball from an unpacked directory.
1702 </para>
1703 </section>
1705 <section id="changed-binfiles">
1706 <title>Changing binary files in <literal>diff.gz</literal></title>
1707 <para>
1708 Sometimes it is necessary to change binary files contained in the original
1709 tarball, or to add binary files that are not in it.  If this is done by simply
1710 copying the files into the debianized source tree,
1711 <command>dpkg-source</command> will not be able to handle this.  On the other
1712 hand, according to the guidelines given above, you cannot include such a
1713 changed binary file in a repackaged <filename>orig.tar.gz</filename>.  Instead,
1714 include the file in the <filename>debian</filename> directory in
1715 <command>uuencode</command>d (or similar) form <footnote><para> The file should
1716 have a name that makes it clear which binary file it encodes.  Usually, some
1717 postfix indicating the encoding should be appended to the original filename.
1718 Note that you don't need to depend on <systemitem
1719 role="package">sharutils</systemitem> to get the <command>uudecode</command>
1720 program if you use <command>perl</command>'s <literal>pack</literal> function.
1721 The code could look like </para> <screen> -file: perl -ne 'print(pack u, $$_);'
1722 $(file) &gt; $(file).uuencoded uudecode-file: perl -ne 'print(unpack u, $$_);'
1723 $(file).uuencoded &gt; $(file) </screen> </footnote>.  The file would then be
1724 decoded and copied to its place during the build process.  Thus the change will
1725 be visible quite easy.
1726 </para>
1727 <para>
1728 Some packages use <command>dbs</command> to manage patches to their upstream
1729 source, and always create a new <literal>orig.tar.gz</literal> file that
1730 contains the real <literal>orig.tar.gz</literal> in its toplevel directory.
1731 This is questionable with respect to the preference for pristine source.  On
1732 the other hand, it is easy to modify or add binary files in this case: Just put
1733 them into the newly created <literal>orig.tar.gz</literal> file, besides the
1734 real one, and copy them to the right place during the build process.
1735 </para>
1736 </section>
1738 </section>
1740 <section id="bpp-dbg">
1741 <title>Best practices for debug packages</title>
1742 <para>
1743 A debug package is a package with a name ending in -dbg, that contains
1744 additional information that gdb can use.  Since Debian binaries are stripped by
1745 default, debugging information, including function names and line numbers, is
1746 otherwise not available when running gdb on Debian binaries.  Debug packages
1747 allow users who need this additional debugging information to install it,
1748 without bloating a regular system with the information.
1749 </para>
1750 <para>
1751 It is up to a package's maintainer whether to create a debug package or not.
1752 Maintainers are encouraged to create debug packages for library packages, since
1753 this can aid in debugging many programs linked to a library.  In general, debug
1754 packages do not need to be added for all programs; doing so would bloat the
1755 archive.  But if a maintainer finds that users often need a debugging version
1756 of a program, it can be worthwhile to make a debug package for it.  Programs
1757 that are core infrastructure, such as apache and the X server are also good
1758 candidates for debug packages.
1759 </para>
1760 <para>
1761 Some debug packages may contain an entire special debugging build of a library
1762 or other binary, but most of them can save space and build time by instead
1763 containing separated debugging symbols that gdb can find and load on the fly
1764 when debugging a program or library.  The convention in Debian is to keep these
1765 symbols in <filename>/usr/lib/debug/path</filename>, where
1766 <emphasis>path</emphasis> is the path to the executable or library.  For
1767 example, debugging symbols for <filename>/usr/bin/foo</filename> go in
1768 <filename>/usr/lib/debug/usr/bin/foo</filename>, and debugging symbols for
1769 <filename>/usr/lib/</filename> go in
1770 <filename>/usr/lib/debug/usr/lib/</filename>.
1771 </para>
1772 <para>
1773 The debugging symbols can be extracted from an object file using objcopy
1774 --only-keep-debug.  Then the object file can be stripped, and objcopy
1775 --add-gnu-debuglink used to specify the path to the debugging symbol file.
1776 <citerefentry> <refentrytitle>objcopy</refentrytitle> <manvolnum>1</manvolnum>
1777 </citerefentry> explains in detail how this works.
1778 </para>
1779 <para>
1780 The dh_strip command in debhelper supports creating debug packages, and can
1781 take care of using objcopy to separate out the debugging symbols for you.  If
1782 your package uses debhelper, all you need to do is call dh_strip
1783 --dbg-package=libfoo-dbg, and add an entry to debian/control for the debug
1784 package.
1785 </para>
1786 <para>
1787 Note that the Debian package should depend on the package that it provides
1788 debugging symbols for, and this dependency should be versioned.  For example:
1789 </para>
1790 <screen>
1791 : libfoo-dbg (= ${binary:Version})
1792 </screen>
1793 </section>
1795 </section>
1797 </chapter>