]> git.donarmstrong.com Git - debian/debian-policy.git/blob - policy.sgml
Merge branch 'master' into bug504880-rra
[debian/debian-policy.git] / policy.sgml
1 <!doctype debiandoc system [
2 <!-- include version information so we don't have to hard code it
3      within the document -->
4 <!entity % versiondata SYSTEM "version.ent"> %versiondata;
5 ]>
6 <debiandoc>
7
8   <book>
9     <titlepag>
10       <title>Debian Policy Manual</title>
11       <author><qref id="authors">The Debian Policy Mailing List</qref></author>
12       <version>version &version;, &date;</version>
13
14       <abstract>
15         This manual describes the policy requirements for the Debian
16         GNU/Linux distribution.  This includes the structure and
17         contents of the Debian archive and several design issues of
18         the operating system, as well as technical requirements that
19         each package must satisfy to be included in the distribution.
20       </abstract>
21
22       <copyright>
23         <copyrightsummary>
24           Copyright &copy; 1996,1997,1998 Ian Jackson
25           and Christian Schwarz.
26         </copyrightsummary>
27         <p>
28           These are the copyright dates of the original Policy manual.
29           Since then, this manual has been updated by many others.  No
30           comprehensive collection of copyright notices for subsequent
31           work exists.
32         </p>
33
34         <p>
35           This manual is free software; you may redistribute it and/or
36           modify it under the terms of the GNU General Public License
37           as published by the Free Software Foundation; either version
38           2, or (at your option) any later version.
39         </p>
40
41         <p>
42           This is distributed in the hope that it will be useful, but
43           <em>without any warranty</em>; without even the implied
44           warranty of merchantability or fitness for a particular
45           purpose.  See the GNU General Public License for more
46           details.
47         </p>
48
49         <p>
50           A copy of the GNU General Public License is available as
51           <file>/usr/share/common-licenses/GPL</file> in the Debian GNU/Linux
52           distribution or on the World Wide Web at
53           <url id="http://www.gnu.org/copyleft/gpl.html"
54                name="the GNU General Public Licence">. You can also
55           obtain it by writing to the Free Software Foundation, Inc.,
56           51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
57         </p>
58       </copyright>
59     </titlepag>
60
61     <toc detail="sect1">
62
63     <chapt id="scope">
64       <heading>About this manual</heading>
65       <sect>
66         <heading>Scope</heading>
67         <p>
68           This manual describes the policy requirements for the Debian
69           GNU/Linux distribution. This includes the structure and
70           contents of the Debian archive and several design issues of the
71           operating system, as well as technical requirements that
72           each package must satisfy to be included in the
73           distribution.
74         </p>
75
76         <p>
77           This manual also describes Debian policy as it relates to
78           creating Debian packages. It is not a tutorial on how to build
79           packages, nor is it exhaustive where it comes to describing
80           the behavior of the packaging system. Instead, this manual
81           attempts to define the interface to the package management
82           system that the developers have to be conversant with.<footnote>
83               Informally, the criteria used for inclusion is that the
84               material meet one of the following requirements:
85               <taglist compact="compact">
86                 <tag>Standard interfaces</tag>
87                 <item>
88                     The material presented represents an interface to
89                     the packaging system that is mandated for use, and
90                     is used by, a significant number of packages, and
91                     therefore should not be changed without peer
92                     review. Package maintainers can then rely on this
93                     interface not changing, and the package management
94                     software authors need to ensure compatibility with
95                     this interface definition. (Control file and
96                     changelog file formats are examples.)
97                 </item>
98                 <tag>Chosen Convention</tag>
99                 <item>
100                     If there are a number of technically viable choices
101                     that can be made, but one needs to select one of
102                     these options for inter-operability. The version
103                     number format is one example.
104                 </item>
105               </taglist>
106               Please note that these are not mutually exclusive;
107               selected conventions often become parts of standard
108               interfaces.
109           </footnote>
110         </p>
111
112         <p>
113           The footnotes present in this manual are
114           merely informative, and are not part of Debian policy itself.
115         </p>
116
117         <p>
118           The appendices to this manual are not necessarily normative,
119           either. Please see <ref id="pkg-scope"> for more information.
120         </p>
121
122         <p>
123           In the normative part of this manual,
124           the words <em>must</em>, <em>should</em> and
125           <em>may</em>, and the adjectives <em>required</em>,
126           <em>recommended</em> and <em>optional</em>, are used to
127           distinguish the significance of the various guidelines in
128           this policy document. Packages that do not conform to the
129           guidelines denoted by <em>must</em> (or <em>required</em>)
130           will generally not be considered acceptable for the Debian
131           distribution. Non-conformance with guidelines denoted by
132           <em>should</em> (or <em>recommended</em>) will generally be
133           considered a bug, but will not necessarily render a package
134           unsuitable for distribution. Guidelines denoted by
135           <em>may</em> (or <em>optional</em>) are truly optional and
136           adherence is left to the maintainer's discretion.
137         </p>
138
139         <p>
140           These classifications are roughly equivalent to the bug
141           severities <em>serious</em> (for <em>must</em> or
142           <em>required</em> directive violations), <em>minor</em>,
143           <em>normal</em> or <em>important</em>
144           (for <em>should</em> or <em>recommended</em> directive
145           violations) and <em>wishlist</em> (for <em>optional</em>
146           items).
147           <footnote>
148                 Compare RFC 2119.  Note, however, that these words are
149                 used in a different way in this document.
150           </footnote>
151         </p>
152
153         <p>
154           Much of the information presented in this manual will be
155           useful even when building a package which is to be
156           distributed in some other way or is intended for local use
157           only.
158         </p>
159       </sect>
160
161       <sect>
162         <heading>New versions of this document</heading>
163
164         <p>
165           This manual is distributed via the Debian package
166           <package><url name="debian-policy"
167               id="http://packages.debian.org/debian-policy"></package> 
168           (<httpsite>packages.debian.org</httpsite> 
169           <httppath>/debian-policy</httppath>).
170         </p>
171
172         <p>
173           The current version of this document is also available from
174           the Debian web mirrors at
175           <tt><url name="/doc/debian-policy/"
176                 id="http://www.debian.org/doc/debian-policy/"></tt>.
177           (
178           <httpsite>www.debian.org</httpsite>
179           <httppath>/doc/debian-policy/</httppath>)
180           Also available from the same directory are several other
181           formats: <file>policy.html.tar.gz</file>
182           (<httppath>/doc/debian-policy/policy.html.tar.gz</httppath>),
183           <file>policy.pdf.gz</file> 
184           (<httppath>/doc/debian-policy/policy.pdf.gz</httppath>)
185           and <file>policy.ps.gz</file>
186           (<httppath>/doc/debian-policy/policy.ps.gz</httppath>).
187         </p>
188
189         <p>
190           The <package>debian-policy</package> package also includes the file
191           <file>upgrading-checklist.txt.gz</file> which indicates policy
192           changes between versions of this document.
193         </p>
194       </sect>
195
196       <sect id="authors">
197         <heading>Authors and Maintainers</heading>
198
199         <p>
200           Originally called "Debian GNU/Linux Policy Manual", this
201           manual was initially written in 1996 by Ian Jackson.
202           It was revised on November 27th, 1996 by David A. Morris.
203           Christian Schwarz added new sections on March 15th, 1997,
204           and reworked/restructured it in April-July 1997.
205           Christoph Lameter contributed the "Web Standard".
206           Julian Gilbey largely restructured it in 2001.
207         </p>
208
209         <p>
210           Since September 1998, the responsibility for the contents of
211           this document lies on the <url name="debian-policy mailing list"
212           id="mailto:debian-policy@lists.debian.org">. Proposals
213           are discussed there and inserted into policy after a certain
214           consensus is established.
215           <!-- insert shameless policy-process plug here eventually -->
216           The actual editing is done by a group of maintainers that have
217           no editorial powers. These are the current maintainers:
218
219           <enumlist>
220             <item>Julian Gilbey</item>
221             <item>Branden Robinson</item>
222             <item>Josip Rodin</item>
223             <item>Manoj Srivastava</item>
224           </enumlist>
225         </p>
226
227         <p>
228           While the authors of this document have tried hard to avoid
229           typos and other errors, these do still occur. If you discover
230           an error in this manual or if you want to give any
231           comments, suggestions, or criticisms please send an email to
232           the Debian Policy List,
233           <email>debian-policy@lists.debian.org</email>, or submit a
234           bug report against the <tt>debian-policy</tt> package.
235         </p>
236
237         <p>
238           Please do not try to reach the individual authors or maintainers
239           of the Policy Manual regarding changes to the Policy.
240         </p>
241       </sect>
242
243       <sect id="related">
244         <heading>Related documents</heading>
245
246         <p>
247           There are several other documents other than this Policy Manual
248           that are necessary to fully understand some Debian policies and
249           procedures.
250         </p>
251
252         <p>
253           The external "sub-policy" documents are referred to in:
254           <list compact="compact">
255             <item><ref id="fhs"></item>
256             <item><ref id="virtual_pkg"></item>
257             <item><ref id="menus"></item>
258             <item><ref id="mime"></item>
259             <item><ref id="perl"></item>
260             <item><ref id="maintscriptprompt"></item>
261             <item><ref id="emacs"></item>
262           </list>
263         </p>
264
265         <p>
266           In addition to those, which carry the weight of policy, there
267           is the Debian Developer's Reference. This document describes
268           procedures and resources for Debian developers, but it is
269           <em>not</em> normative; rather, it includes things that don't
270           belong in the Policy, such as best practices for developers.
271         </p>
272
273         <p>
274           The Developer's Reference is available in the
275           <package>developers-reference</package> package.
276           It's also available from the Debian web mirrors at
277           <tt><url name="/doc/developers-reference/"
278                 id="http://www.debian.org/doc/developers-reference/"></tt>.
279         </p>
280       </sect>
281
282       <sect id="definitions">
283         <heading>Definitions</heading>
284
285         <p>
286           The following terms are used in this Policy Manual:
287           <taglist>
288             <tag>ASCII</tag>
289             <item>
290               The character encoding specified by ANSI X3.4-1986 and its
291               predecessor standards, referred to in MIME as US-ASCII, and
292               corresponding to an encoding in eight bits per character of
293               the first 128 <url id="http://www.unicode.org/"
294               name="Unicode"> characters, with the eighth bit always zero.
295             </item>
296             <tag>UTF-8</tag>
297             <item>
298               The transformation format (sometimes called encoding) of
299               <url id="http://www.unicode.org/" name="Unicode"> defined by
300               <url id="http://www.rfc-editor.org/rfc/rfc3629.txt"
301               name="RFC 3629">.  UTF-8 has the useful property of having
302               ASCII as a subset, so any text encoded in ASCII is trivially
303               also valid UTF-8.
304             </item>
305           </taglist>
306         </p>
307       </sect>
308     </chapt>
309
310
311     <chapt id="archive">
312       <heading>The Debian Archive</heading>
313
314       <p>
315         The Debian GNU/Linux system is maintained and distributed as a
316         collection of <em>packages</em>. Since there are so many of
317         them (currently well over 15000), they are split into
318         <em>sections</em> and given <em>priorities</em> to simplify
319         the handling of them.
320       </p>
321
322       <p>
323         The effort of the Debian project is to build a free operating
324         system, but not every package we want to make accessible is
325         <em>free</em> in our sense (see the Debian Free Software
326         Guidelines, below), or may be imported/exported without
327         restrictions. Thus, the archive is split into areas<footnote>
328           The Debian archive software uses the term "component" internally
329           and in the Release file format to refer to the division of an
330           archive.  The Debian Social Contract simply refers to "areas."
331           This document uses terminology similar to the Social Contract.
332         </footnote> based on their licenses and other restrictions.
333       </p>
334
335       <p>
336         The aims of this are:
337
338         <list compact="compact">
339           <item>to allow us to make as much software available as we can</item>
340           <item>to allow us to encourage everyone to write free software,
341                 and</item>
342           <item>to allow us to make it easy for people to produce
343                 CD-ROMs of our system without violating any licenses,
344                 import/export restrictions, or any other laws.</item>
345         </list>
346       </p>
347
348       <p>
349         The <em>main</em> archive area forms the <em>Debian GNU/Linux
350         distribution</em>.
351       </p>
352
353       <p>
354         Packages in the other archive areas (<tt>contrib</tt>,
355         <tt>non-free</tt>) are not considered to be part of the Debian
356         distribution, although we support their use and provide
357         infrastructure for them (such as our bug-tracking system and
358         mailing lists). This Debian Policy Manual applies to these
359         packages as well.
360       </p>
361
362       <sect id="dfsg">
363         <heading>The Debian Free Software Guidelines</heading>
364         <p>
365           The Debian Free Software Guidelines (DFSG) form our
366           definition of "free software".  These are:
367             <taglist>
368               <tag>1. Free Redistribution
369               </tag>
370               <item>
371                   The license of a Debian component may not restrict any
372                   party from selling or giving away the software as a
373                   component of an aggregate software distribution
374                   containing programs from several different
375                   sources. The license may not require a royalty or
376                   other fee for such sale.
377               </item>
378               <tag>2. Source Code
379               </tag>
380               <item>
381                   The program must include source code, and must allow
382                   distribution in source code as well as compiled form.
383               </item>
384               <tag>3. Derived Works
385               </tag>
386               <item>
387                   The license must allow modifications and derived
388                   works, and must allow them to be distributed under the
389                   same terms as the license of the original software.
390               </item>
391               <tag>4. Integrity of The Author's Source Code
392               </tag>
393               <item>
394                   The license may restrict source-code from being
395                   distributed in modified form <em>only</em> if the
396                   license allows the distribution of "patch files"
397                   with the source code for the purpose of modifying the
398                   program at build time. The license must explicitly
399                   permit distribution of software built from modified
400                   source code. The license may require derived works to
401                   carry a different name or version number from the
402                   original software.  (This is a compromise. The Debian
403                   Project encourages all authors to not restrict any
404                   files, source or binary, from being modified.)
405               </item>
406               <tag>5. No Discrimination Against Persons or Groups
407               </tag>
408               <item>
409                   The license must not discriminate against any person
410                   or group of persons.
411               </item>
412               <tag>6. No Discrimination Against Fields of Endeavor
413               </tag>
414               <item>
415                   The license must not restrict anyone from making use
416                   of the program in a specific field of endeavor. For
417                   example, it may not restrict the program from being
418                   used in a business, or from being used for genetic
419                   research.
420               </item>
421               <tag>7. Distribution of License
422               </tag>
423               <item>
424                   The rights attached to the program must apply to all
425                   to whom the program is redistributed without the need
426                   for execution of an additional license by those
427                   parties.
428               </item>
429               <tag>8. License Must Not Be Specific to Debian
430               </tag>
431               <item>
432                   The rights attached to the program must not depend on
433                   the program's being part of a Debian system. If the
434                   program is extracted from Debian and used or
435                   distributed without Debian but otherwise within the
436                   terms of the program's license, all parties to whom
437                   the program is redistributed must have the same
438                   rights as those that are granted in conjunction with
439                   the Debian system.
440               </item>
441               <tag>9. License Must Not Contaminate Other Software
442               </tag>
443               <item>
444                   The license must not place restrictions on other
445                   software that is distributed along with the licensed
446                   software. For example, the license must not insist
447                   that all other programs distributed on the same medium
448                   must be free software.
449               </item>
450               <tag>10. Example Licenses
451               </tag>
452               <item>
453                   The "GPL," "BSD," and "Artistic" licenses are examples of
454                   licenses that we consider <em>free</em>.
455               </item>
456             </taglist>
457         </p>
458       </sect>
459
460       <sect id="sections">
461         <heading>Archive areas</heading>
462
463         <sect1 id="main">
464           <heading>The main archive area</heading>
465
466           <p>
467             Every package in <em>main</em> must comply with the DFSG
468             (Debian Free Software Guidelines).
469           </p>
470
471           <p>
472             In addition, the packages in <em>main</em>
473             <list compact="compact">
474               <item>
475                   must not require a package outside of <em>main</em>
476                   for compilation or execution (thus, the package must
477                   not declare a "Depends", "Recommends", or
478                   "Build-Depends" relationship on a non-<em>main</em>
479                   package),
480               </item>
481               <item>
482                   must not be so buggy that we refuse to support them,
483                   and
484               </item>
485               <item>
486                   must meet all policy requirements presented in this
487                   manual.
488               </item>
489             </list>
490           </p>
491
492         </sect1>
493
494         <sect1 id="contrib">
495           <heading>The contrib archive area</heading>
496
497           <p>
498             Every package in <em>contrib</em> must comply with the DFSG.
499           </p>
500
501           <p>
502             In addition, the packages in <em>contrib</em>
503             <list compact="compact">
504               <item>
505                   must not be so buggy that we refuse to support them,
506                   and
507               </item>
508               <item>
509                   must meet all policy requirements presented in this
510                   manual.
511               </item>
512             </list>
513           </p>
514
515
516           <p>
517             Examples of packages which would be included in
518             <em>contrib</em> are:
519             <list compact="compact">
520               <item>
521                   free packages which require <em>contrib</em>,
522                   <em>non-free</em> packages or packages which are not
523                   in our archive at all for compilation or execution,
524                   and
525               </item>
526               <item>
527                   wrapper packages or other sorts of free accessories for
528                   non-free programs.
529               </item>
530             </list>
531           </p>
532         </sect1>
533
534         <sect1 id="non-free">
535           <heading>The non-free archive area</heading>
536
537           <p>
538             Packages must be placed in <em>non-free</em> if they are
539             not compliant with the DFSG or are encumbered by patents
540             or other legal issues that make their distribution
541             problematic.
542           </p>
543
544           <p>
545             In addition, the packages in <em>non-free</em>
546             <list compact="compact">
547               <item>
548                   must not be so buggy that we refuse to support them,
549                   and
550               </item>
551               <item>
552                   must meet all policy requirements presented in this
553                   manual that it is possible for them to meet.
554                   <footnote>
555                       It is possible that there are policy
556                       requirements which the package is unable to
557                       meet, for example, if the source is
558                       unavailable.  These situations will need to be
559                       handled on a case-by-case basis.
560                   </footnote>
561               </item>
562             </list>
563           </p>
564         </sect1>
565
566       </sect>
567
568       <sect id="pkgcopyright">
569         <heading>Copyright considerations</heading>
570
571         <p>
572           Every package must be accompanied by a verbatim copy of its
573           copyright information and distribution license in the file
574           <file>/usr/share/doc/<var>package</var>/copyright</file>
575           (see <ref id="copyrightfile"> for further details).
576         </p>
577
578         <p>
579           We reserve the right to restrict files from being included
580           anywhere in our archives if
581           <list compact="compact">
582             <item>
583                   their use or distribution would break a law,
584             </item>
585             <item>
586                   there is an ethical conflict in their distribution or
587                   use,
588             </item>
589             <item>
590                   we would have to sign a license for them, or
591             </item>
592             <item>
593                   their distribution would conflict with other project
594                   policies.
595             </item>
596           </list>
597         </p>
598
599         <p>
600           Programs whose authors encourage the user to make
601           donations are fine for the main distribution, provided
602           that the authors do not claim that not donating is
603           immoral, unethical, illegal or something similar; in such
604           a case they must go in <em>non-free</em>.
605         </p>
606
607         <p>
608           Packages whose copyright permission notices (or patent
609           problems) do not even allow redistribution of binaries
610           only, and where no special permission has been obtained,
611           must not be placed on the Debian FTP site and its mirrors
612           at all.
613         </p>
614
615         <p>
616           Note that under international copyright law (this applies
617           in the United States, too), <em>no</em> distribution or
618           modification of a work is allowed without an explicit
619           notice saying so.  Therefore a program without a copyright
620           notice <em>is</em> copyrighted and you may not do anything
621           to it without risking being sued! Likewise if a program
622           has a copyright notice but no statement saying what is
623           permitted then nothing is permitted.
624         </p>
625
626         <p>
627           Many authors are unaware of the problems that restrictive
628           copyrights (or lack of copyright notices) can cause for
629           the users of their supposedly-free software.  It is often
630           worthwhile contacting such authors diplomatically to ask
631           them to modify their license terms. However, this can be a
632           politically difficult thing to do and you should ask for
633           advice on the <tt>debian-legal</tt> mailing list first, as
634           explained below.
635         </p>
636
637         <p>
638           When in doubt about a copyright, send mail to
639           <email>debian-legal@lists.debian.org</email>.  Be prepared
640           to provide us with the copyright statement.  Software
641           covered by the GPL, public domain software and BSD-like
642           copyrights are safe; be wary of the phrases "commercial
643           use prohibited" and "distribution restricted".
644         </p>
645       </sect>
646
647       <sect id="subsections">
648         <heading>Sections</heading>
649
650         <p>
651           The packages in the archive areas <em>main</em>,
652           <em>contrib</em> and <em>non-free</em> are grouped further into
653           <em>sections</em> to simplify handling.
654         </p>
655
656         <p>
657           The archive area and section for each package should be
658           specified in the package's <tt>Section</tt> control record (see
659           <ref id="f-Section">).  However, the maintainer of the Debian
660           archive may override this selection to ensure the consistency of
661           the Debian distribution.  The <tt>Section</tt> field should be
662           of the form:
663           <list compact="compact">
664             <item>
665                   <em>section</em> if the package is in the
666                   <em>main</em> archive area,
667             </item>
668             <item>
669                   <em>area/section</em> if the package is in
670                   the <em>contrib</em> or <em>non-free</em>
671                   archive areas.
672             </item>
673           </list>
674         </p>
675
676         <p>
677           The Debian archive maintainers provide the authoritative
678           list of sections.  At present, they are:
679           <em>admin</em>, <em>cli-mono</em>, <em>comm</em>, <em>database</em>,
680           <em>devel</em>, <em>debug</em>, <em>doc</em>, <em>editors</em>,
681           <em>electronics</em>, <em>embedded</em>, <em>fonts</em>,
682           <em>games</em>, <em>gnome</em>, <em>graphics</em>, <em>gnu-r</em>,
683           <em>gnustep</em>, <em>hamradio</em>, <em>haskell</em>,
684           <em>httpd</em>, <em>interpreters</em>, <em>java</em>, <em>kde</em>,
685           <em>kernel</em>, <em>libs</em>, <em>libdevel</em>, <em>lisp</em>,
686           <em>localization</em>, <em>mail</em>, <em>math</em>, <em>misc</em>,
687           <em>net</em>, <em>news</em>, <em>ocaml</em>, <em>oldlibs</em>,
688           <em>otherosfs</em>, <em>perl</em>, <em>php</em>, <em>python</em>,
689           <em>ruby</em>, <em>science</em>, <em>shells</em>, <em>sound</em>,
690           <em>tex</em>, <em>text</em>, <em>utils</em>, <em>vcs</em>,
691           <em>video</em>, <em>web</em>, <em>x11</em>, <em>xfce</em>,
692           <em>zope</em>.
693         </p>
694       </sect>
695
696       <sect id="priorities">
697         <heading>Priorities</heading>
698
699         <p>
700           Each package should have a <em>priority</em> value, which is
701           included in the package's <em>control record</em>
702           (see <ref id="f-Priority">).
703           This information is used by the Debian package management tools to
704           separate high-priority packages from less-important packages.
705         </p>
706
707         <p>
708           The following <em>priority levels</em> are recognized by the
709           Debian package management tools.
710           <taglist>
711             <tag><tt>required</tt></tag>
712             <item>
713                 Packages which are necessary for the proper
714                 functioning of the system (usually, this means that
715                 dpkg functionality depends on these packages).
716                 Removing a <tt>required</tt> package may cause your
717                 system to become totally broken and you may not even
718                 be able to use <prgn>dpkg</prgn> to put things back,
719                 so only do so if you know what you are doing.  Systems
720                 with only the <tt>required</tt> packages are probably
721                 unusable, but they do have enough functionality to
722                 allow the sysadmin to boot and install more software.
723             </item>
724             <tag><tt>important</tt></tag>
725             <item>
726                 Important programs, including those which one would
727                 expect to find on any Unix-like system.  If the
728                 expectation is that an experienced Unix person who
729                 found it missing would say "What on earth is going on,
730                 where is <prgn>foo</prgn>?", it must be an
731                 <tt>important</tt> package.<footnote>
732                     This is an important criterion because we are
733                     trying to produce, amongst other things, a free
734                     Unix.
735                 </footnote>
736                 Other packages without which the system will not run
737                 well or be usable must also have priority
738                 <tt>important</tt>.  This does
739                 <em>not</em> include Emacs, the X Window System, TeX
740                 or any other large applications.  The
741                 <tt>important</tt> packages are just a bare minimum of
742                 commonly-expected and necessary tools.
743             </item>
744             <tag><tt>standard</tt></tag>
745             <item>
746                 These packages provide a reasonably small but not too
747                 limited character-mode system.  This is what will be
748                 installed by default if the user doesn't select anything
749                 else.  It doesn't include many large applications.
750             </item>
751             <tag><tt>optional</tt></tag>
752             <item>
753                 (In a sense everything that isn't required is
754                 optional, but that's not what is meant here.) This is
755                 all the software that you might reasonably want to
756                 install if you didn't know what it was and don't have
757                 specialized requirements. This is a much larger system
758                 and includes the X Window System, a full TeX
759                 distribution, and many applications. Note that
760                 optional packages should not conflict with each other.
761             </item>
762             <tag><tt>extra</tt></tag>
763             <item>
764                 This contains all packages that conflict with others
765                 with required, important, standard or optional
766                 priorities, or are only likely to be useful if you
767                 already know what they are or have specialized
768                 requirements (such as packages containing only detached
769                 debugging symbols).
770             </item>
771           </taglist>
772         </p>
773
774         <p>
775           Packages must not depend on packages with lower priority
776           values (excluding build-time dependencies).  In order to
777           ensure this, the priorities of one or more packages may need
778           to be adjusted.
779         </p>
780       </sect>
781
782     </chapt>
783
784
785     <chapt id="binary">
786       <heading>Binary packages</heading>
787
788       <p>
789         The Debian GNU/Linux distribution is based on the Debian
790         package management system, called <prgn>dpkg</prgn>. Thus,
791         all packages in the Debian distribution must be provided
792         in the <tt>.deb</tt> file format.
793       </p>
794
795       <sect>
796         <heading>The package name</heading>
797
798         <p>
799           Every package must have a name that's unique within the Debian
800           archive.
801         </p>
802
803         <p>
804           The package name is included in the control field
805           <tt>Package</tt>, the format of which is described
806           in <ref id="f-Package">.
807           The package name is also included as a part of the file name
808           of the <tt>.deb</tt> file.
809         </p>
810       </sect>
811
812       <sect id="versions">
813         <heading>The version of a package</heading>
814
815         <p>
816           Every package has a version number recorded in its
817           <tt>Version</tt> control file field, described in
818           <ref id="f-Version">.
819         </p>
820
821         <p>
822           The package management system imposes an ordering on version
823           numbers, so that it can tell whether packages are being up- or
824           downgraded and so that package system front end applications
825           can tell whether a package it finds available is newer than
826           the one installed on the system.  The version number format
827           has the most significant parts (as far as comparison is
828           concerned) at the beginning.
829         </p>
830
831         <p>
832           If an upstream package has problematic version numbers they
833           should be converted to a sane form for use in the
834           <tt>Version</tt> field.
835         </p>
836
837         <sect1>
838           <heading>Version numbers based on dates</heading>
839
840           <p>
841             In general, Debian packages should use the same version
842             numbers as the upstream sources.
843           </p>
844
845           <p>
846             However, in some cases where the upstream version number is
847             based on a date (e.g., a development "snapshot" release) the
848             package management system cannot handle these version
849             numbers without epochs. For example, dpkg will consider
850             "96May01" to be greater than "96Dec24".
851           </p>
852
853           <p>
854             To prevent having to use epochs for every new upstream
855             version, the date based portion of the version number
856             should be changed to the following format in such cases:
857             "19960501", "19961224". It is up to the maintainer whether
858             they want to bother the upstream maintainer to change
859             the version numbers upstream, too.
860           </p>
861
862           <p>
863             Note that other version formats based on dates which are
864             parsed correctly by the package management system should
865             <em>not</em> be changed.
866           </p>
867
868           <p>
869             Native Debian packages (i.e., packages which have been
870             written especially for Debian) whose version numbers include
871             dates should always use the "YYYYMMDD" format.
872           </p>
873         </sect1>
874
875       </sect>
876
877       <sect>
878         <heading>The maintainer of a package</heading>
879
880         <p>
881           Every package must have a Debian maintainer (the
882           maintainer may be one person or a group of people
883           reachable from a common email address, such as a mailing
884           list).  The maintainer is responsible for ensuring that
885           the package is placed in the appropriate distributions.
886         </p>
887
888         <p>
889           The maintainer must be specified in the
890           <tt>Maintainer</tt> control field with their correct name
891           and a working email address.  If one person maintains
892           several packages, they should try to avoid having
893           different forms of their name and email address in
894           the <tt>Maintainer</tt> fields of those packages.
895         </p>
896
897         <p>
898           The format of the <tt>Maintainer</tt> control field is
899           described in <ref id="f-Maintainer">.
900         </p>
901
902         <p>
903           If the maintainer of a package quits from the Debian
904           project, "Debian QA Group"
905           <email>packages@qa.debian.org</email> takes over the
906           maintainer-ship of the package until someone else
907           volunteers for that task. These packages are called
908           <em>orphaned packages</em>.<footnote>
909                 The detailed procedure for doing this gracefully can
910                 be found in the Debian Developer's Reference,
911                 see <ref id="related">.
912           </footnote>
913         </p>
914       </sect>
915
916       <sect id="descriptions">
917         <heading>The description of a package</heading>
918
919         <p>
920           Every Debian package must have an extended description
921           stored in the appropriate field of the control record.
922           The technical information about the format of the
923           <tt>Description</tt> field is in <ref id="f-Description">.
924         </p>
925
926         <p>
927           The description should describe the package (the program) to a
928           user (system administrator) who has never met it before so that
929           they have enough information to decide whether they want to
930           install it. This description should not just be copied verbatim
931           from the program's documentation.
932         </p>
933
934         <p>
935           Put important information first, both in the synopsis and
936           extended description.  Sometimes only the first part of the
937           synopsis or of the description will be displayed.  You can
938           assume that there will usually be a way to see the whole
939           extended description.
940         </p>
941
942         <p>
943           The description should also give information about the
944           significant dependencies and conflicts between this package
945           and others, so that the user knows why these dependencies and
946           conflicts have been declared.
947         </p>
948
949         <p>
950           Instructions for configuring or using the package should
951           not be included (that is what installation scripts,
952           manual pages, info files, etc., are for).  Copyright
953           statements and other administrivia should not be included
954           either (that is what the copyright file is for).
955         </p>
956
957         <sect1 id="synopsis"><heading>The single line synopsis</heading>
958
959           <p>
960             The single line synopsis should be kept brief - certainly
961             under 80 characters.
962           </p>
963
964           <p>
965             Do not include the package name in the synopsis line.  The
966             display software knows how to display this already, and you
967             do not need to state it.  Remember that in many situations
968             the user may only see the synopsis line - make it as
969             informative as you can.
970           </p>
971
972         </sect1>
973
974         <sect1 id="extendeddesc"><heading>The extended description</heading>
975
976           <p>
977             Do not try to continue the single line synopsis into the
978             extended description.  This will not work correctly when
979             the full description is displayed, and makes no sense
980             where only the summary (the single line synopsis) is
981             available.
982           </p>
983
984           <p>
985             The extended description should describe what the package
986             does and how it relates to the rest of the system (in terms
987             of, for example, which subsystem it is which part of).
988           </p>
989
990           <p>
991             The description field needs to make sense to anyone, even
992             people who have no idea about any of the things the
993             package deals with.<footnote>
994                 The blurb that comes with a program in its
995                 announcements and/or <prgn>README</prgn> files is
996                 rarely suitable for use in a description.  It is
997                 usually aimed at people who are already in the
998                 community where the package is used.
999             </footnote>
1000           </p>
1001
1002         </sect1>
1003
1004       </sect>
1005
1006       <sect>
1007         <heading>Dependencies</heading>
1008
1009         <p>
1010           Every package must specify the dependency information
1011           about other packages that are required for the first to
1012           work correctly.
1013         </p>
1014
1015         <p>
1016           For example, a dependency entry must be provided for any
1017           shared libraries required by a dynamically-linked executable
1018           binary in a package.
1019         </p>
1020
1021         <p>
1022           Packages are not required to declare any dependencies they
1023           have on other packages which are marked <tt>Essential</tt>
1024           (see below), and should not do so unless they depend on a
1025           particular version of that package.<footnote>
1026             <p>
1027               Essential is needed in part to avoid unresolvable dependency
1028               loops on upgrade.  If packages add unnecessary dependencies
1029               on packages in this set, the chances that there
1030               <strong>will</strong> be an unresolvable dependency loop
1031               caused by forcing these Essential packages to be configured
1032               first before they need to be is greatly increased.  It also
1033               increases the chances that frontends will be unable to
1034               <strong>calculate</strong> an upgrade path, even if one
1035               exists.
1036             </p>
1037             <p>
1038               Also, functionality is rarely ever removed from the
1039               Essential set, but <em>packages</em> have been removed from
1040               the Essential set when the functionality moved to a
1041               different package. So depending on these packages <em>just
1042               in case</em> they stop being essential does way more harm
1043               than good.
1044             </p>
1045           </footnote>
1046         </p>
1047
1048         <p>
1049           Sometimes, a package requires another package to be unpacked
1050           <em>and</em> configured before it can be unpacked. In this
1051           case, you must specify a <tt>Pre-Depends</tt> entry for
1052           the package.
1053         </p>
1054
1055         <p>
1056           You should not specify a <tt>Pre-Depends</tt> entry for a
1057           package before this has been discussed on the
1058           <tt>debian-devel</tt> mailing list and a consensus about
1059           doing that has been reached.
1060         </p>
1061
1062         <p>
1063           The format of the package interrelationship control fields is
1064           described in <ref id="relationships">.
1065         </p>
1066       </sect>
1067
1068       <sect id="virtual_pkg">
1069         <heading>Virtual packages</heading>
1070
1071         <p>
1072           Sometimes, there are several packages which offer
1073           more-or-less the same functionality. In this case, it's
1074           useful to define a <em>virtual package</em> whose name
1075           describes that common functionality.  (The virtual
1076           packages only exist logically, not physically; that's why
1077           they are called <em>virtual</em>.) The packages with this
1078           particular function will then <em>provide</em> the virtual
1079           package. Thus, any other package requiring that function
1080           can simply depend on the virtual package without having to
1081           specify all possible packages individually.
1082         </p>
1083
1084         <p>
1085           All packages should use virtual package names where
1086           appropriate, and arrange to create new ones if necessary.
1087           They should not use virtual package names (except privately,
1088           amongst a cooperating group of packages) unless they have
1089           been agreed upon and appear in the list of virtual package
1090           names. (See also <ref id="virtual">)
1091         </p>
1092
1093         <p>
1094           The latest version of the authoritative list of virtual
1095           package names can be found in the <tt>debian-policy</tt> package.
1096           It is also available from the Debian web mirrors at
1097           <tt><url name="/doc/packaging-manuals/virtual-package-names-list.txt"
1098                 id="http://www.debian.org/doc/packaging-manuals/virtual-package-names-list.txt"></tt>.
1099         </p>
1100
1101         <p>
1102           The procedure for updating the list is described in the preface
1103           to the list.
1104         </p>
1105
1106       </sect>
1107
1108       <sect>
1109         <heading>Base system</heading>
1110
1111         <p>
1112           The <tt>base system</tt> is a minimum subset of the Debian
1113           GNU/Linux system that is installed before everything else
1114           on a new system. Only very few packages are allowed to form
1115           part of the base system, in order to keep the required disk
1116           usage very small.
1117         </p>
1118
1119         <p>
1120           The base system consists of all those packages with priority
1121           <tt>required</tt> or <tt>important</tt>. Many of them will
1122           be tagged <tt>essential</tt> (see below).
1123         </p>
1124       </sect>
1125
1126       <sect>
1127         <heading>Essential packages</heading>
1128
1129         <p>
1130           Essential is defined as the minimal set of functionality that
1131           must be available and usable on the system at all times, even
1132           when packages are in an unconfigured (but unpacked) state.
1133           Packages are tagged <tt>essential</tt> for a system using the
1134           <tt>Essential</tt> control file field.  The format of the
1135           <tt>Essential</tt> control field is described in <ref
1136           id="f-Essential">.
1137         </p>
1138
1139         <p>
1140           Since these packages cannot be easily removed (one has to
1141           specify an extra <em>force option</em> to
1142           <prgn>dpkg</prgn> to do so), this flag must not be used
1143           unless absolutely necessary.  A shared library package
1144           must not be tagged <tt>essential</tt>; dependencies will
1145           prevent its premature removal, and we need to be able to
1146           remove it when it has been superseded.
1147         </p>
1148
1149         <p>
1150           Since dpkg will not prevent upgrading of other packages
1151           while an <tt>essential</tt> package is in an unconfigured
1152             state, all <tt>essential</tt> packages must supply all of
1153             their core functionality even when unconfigured. If the
1154             package cannot satisfy this requirement it must not be
1155             tagged as essential, and any packages depending on this
1156             package must instead have explicit dependency fields as
1157             appropriate.
1158         </p>
1159
1160         <p>
1161           Maintainers should take great care in adding any programs,
1162           interfaces, or functionality to <tt>essential</tt> packages.
1163           Packages may assume that functionality provided by
1164           <tt>essential</tt> packages is always available without
1165           declaring explicit dependencies, which means that removing
1166           functionality from the Essential set is very difficult and is
1167           almost never done.  Any capability added to an
1168           <tt>essential</tt> package therefore creates an obligation to
1169           support that capability as part of the Essential set in
1170           perpetuity.
1171         </p>
1172
1173         <p>
1174           You must not tag any packages <tt>essential</tt> before
1175           this has been discussed on the <tt>debian-devel</tt>
1176           mailing list and a consensus about doing that has been
1177           reached.
1178         </p>
1179       </sect>
1180
1181       <sect id="maintscripts">
1182         <heading>Maintainer Scripts</heading>
1183
1184         <p>
1185           The package installation scripts should avoid producing
1186           output which is unnecessary for the user to see and
1187           should rely on <prgn>dpkg</prgn> to stave off boredom on
1188           the part of a user installing many packages.  This means,
1189           amongst other things, using the <tt>--quiet</tt> option on
1190           <prgn>install-info</prgn>.
1191         </p>
1192
1193         <p>
1194           Errors which occur during the execution of an installation
1195           script must be checked and the installation must not
1196           continue after an error.
1197         </p>
1198
1199         <p>
1200           Note that in general <ref id="scripts"> applies to package
1201           maintainer scripts, too.
1202         </p>
1203
1204         <p>
1205           You should not use <prgn>dpkg-divert</prgn> on a file
1206           belonging to another package without consulting the
1207           maintainer of that package first.
1208         </p>
1209
1210         <p>
1211           All packages which supply an instance of a common command
1212           name (or, in general, filename) should generally use
1213           <prgn>update-alternatives</prgn>, so that they may be
1214           installed together.  If <prgn>update-alternatives</prgn>
1215           is not used, then each package must use
1216           <tt>Conflicts</tt> to ensure that other packages are
1217           de-installed.  (In this case, it may be appropriate to
1218           specify a conflict against earlier versions of something
1219           that previously did not use
1220           <prgn>update-alternatives</prgn>; this is an exception to
1221           the usual rule that versioned conflicts should be
1222           avoided.)
1223         </p>
1224
1225         <sect1 id="maintscriptprompt">
1226           <heading>Prompting in maintainer scripts</heading>
1227           <p>
1228             Package maintainer scripts may prompt the user if
1229             necessary. Prompting must be done by communicating
1230             through a program, such as <prgn>debconf</prgn>, which
1231             conforms to the Debian Configuration Management
1232             Specification, version 2 or higher.
1233           </p>
1234
1235           <p>
1236             Packages which are essential, or which are dependencies of
1237             essential packages, may fall back on another prompting method
1238             if no such interface is available when they are executed.
1239           </p>
1240
1241           <p>
1242             The Debian Configuration Management Specification is included
1243             in the <file>debconf_specification</file> files in the
1244             <package>debian-policy</package> package.
1245             It is also available from the Debian web mirrors at
1246             <tt><url name="/doc/packaging-manuals/debconf_specification.html"
1247                 id="http://www.debian.org/doc/packaging-manuals/debconf_specification.html"></tt>.
1248           </p>
1249
1250           <p>
1251             Packages which use the Debian Configuration Management
1252             Specification may contain an additional
1253             <prgn>config</prgn> script and a <tt>templates</tt>
1254             file in their control archive<footnote>
1255                 The control.tar.gz inside the .deb.
1256                 See <manref name="deb" section="5">.
1257             </footnote>.
1258             The <prgn>config</prgn> script might be run before the
1259             <prgn>preinst</prgn> script, and before the package is unpacked
1260             or any of its dependencies or pre-dependencies are satisfied.
1261             Therefore it must work using only the tools present in
1262             <em>essential</em> packages.<footnote>
1263                   <package>Debconf</package> or another tool that
1264                   implements the Debian Configuration Management
1265                   Specification will also be installed, and any
1266                   versioned dependencies on it will be satisfied
1267                   before preconfiguration begins.
1268             </footnote>
1269           </p>
1270
1271           <p>
1272             Packages which use the Debian Configuration Management
1273             Specification must allow for translation of their user-visible
1274             messages by using a gettext-based system such as the one
1275             provided by the <package>po-debconf</package> package.
1276           </p>
1277
1278           <p>
1279             Packages should try to minimize the amount of prompting
1280             they need to do, and they should ensure that the user
1281             will only ever be asked each question once.  This means
1282             that packages should try to use appropriate shared
1283             configuration files (such as <file>/etc/papersize</file> and
1284             <file>/etc/news/server</file>), and shared
1285             <package>debconf</package> variables rather than each
1286             prompting for their own list of required pieces of
1287             information.
1288           </p>
1289
1290           <p>
1291             It also means that an upgrade should not ask the same
1292             questions again, unless the user has used
1293             <tt>dpkg --purge</tt> to remove the package's configuration.
1294             The answers to configuration questions should be stored in an
1295             appropriate place in <file>/etc</file> so that the user can
1296             modify them, and how this has been done should be
1297             documented.
1298           </p>
1299
1300           <p>
1301             If a package has a vitally important piece of
1302             information to pass to the user (such as "don't run me
1303             as I am, you must edit the following configuration files
1304             first or you risk your system emitting badly-formatted
1305             messages"), it should display this in the
1306             <prgn>config</prgn> or <prgn>postinst</prgn> script and
1307             prompt the user to hit return to acknowledge the
1308             message.  Copyright messages do not count as vitally
1309             important (they belong in
1310             <file>/usr/share/doc/<var>package</var>/copyright</file>);
1311             neither do instructions on how to use a program (these
1312             should be in on-line documentation, where all the users
1313             can see them).
1314           </p>
1315
1316           <p>
1317             Any necessary prompting should almost always be confined
1318             to the <prgn>config</prgn> or <prgn>postinst</prgn>
1319             script. If it is done in the <prgn>postinst</prgn>, it
1320             should be protected with a conditional so that
1321             unnecessary prompting doesn't happen if a package's
1322             installation fails and the <prgn>postinst</prgn> is
1323             called with <tt>abort-upgrade</tt>,
1324             <tt>abort-remove</tt> or <tt>abort-deconfigure</tt>.
1325           </p>
1326         </sect1>
1327
1328       </sect>
1329
1330     </chapt>
1331
1332
1333     <chapt id="source">
1334       <heading>Source packages</heading>
1335
1336       <sect id="standardsversion">
1337         <heading>Standards conformance</heading>
1338
1339         <p>
1340           Source packages should specify the most recent version number
1341           of this policy document with which your package complied
1342           when it was last updated.
1343         </p>
1344
1345         <p>
1346           This information may be used to file bug reports
1347           automatically if your package becomes too much out of date.
1348         </p>
1349
1350         <p>
1351           The version is specified in the <tt>Standards-Version</tt>
1352           control field.
1353           The format of the <tt>Standards-Version</tt> field is
1354           described in <ref id="f-Standards-Version">.
1355         </p>
1356
1357         <p>
1358           You should regularly, and especially if your package has
1359           become out of date, check for the newest Policy Manual
1360           available and update your package, if necessary. When your
1361           package complies with the new standards you should update the
1362           <tt>Standards-Version</tt> source package field and
1363           release it.<footnote>
1364                 See the file <file>upgrading-checklist</file> for
1365                 information about policy which has changed between
1366                 different versions of this document.
1367           </footnote>
1368         </p>
1369
1370       </sect>
1371
1372       <sect id="pkg-relations">
1373         <heading>Package relationships</heading>
1374
1375         <p>
1376           Source packages should specify which binary packages they
1377           require to be installed or not to be installed in order to
1378           build correctly.  For example, if building a package
1379           requires a certain compiler, then the compiler should be
1380           specified as a build-time dependency.
1381         </p>
1382
1383         <p>
1384           It is not necessary to explicitly specify build-time
1385           relationships on a minimal set of packages that are always
1386           needed to compile, link and put in a Debian package a
1387           standard "Hello World!" program written in C or C++.  The
1388           required packages are called <em>build-essential</em>, and
1389           an informational list can be found in
1390           <file>/usr/share/doc/build-essential/list</file> (which is
1391           contained in the <tt>build-essential</tt>
1392           package).<footnote>
1393             Rationale:
1394                 <list compact="compact">
1395                   <item>
1396                       This allows maintaining the list separately
1397                       from the policy documents (the list does not
1398                       need the kind of control that the policy
1399                       documents do).
1400                   </item>
1401                   <item>
1402                       Having a separate package allows one to install
1403                       the build-essential packages on a machine, as
1404                       well as allowing other packages such as tasks to
1405                       require installation of the build-essential
1406                       packages using the depends relation.
1407                   </item>
1408                   <item>
1409                       The separate package allows bug reports against
1410                       the list to be categorized separately from
1411                       the policy management process in the BTS.
1412                   </item>
1413                 </list>
1414           </footnote>
1415         </p>
1416
1417         <p>
1418           When specifying the set of build-time dependencies, one
1419           should list only those packages explicitly required by the
1420           build.  It is not necessary to list packages which are
1421           required merely because some other package in the list of
1422           build-time dependencies depends on them.<footnote>
1423                 The reason for this is that dependencies change, and
1424                 you should list all those packages, and <em>only</em>
1425                 those packages that <em>you</em> need directly.  What
1426                 others need is their business.  For example, if you
1427                 only link against <file>libimlib</file>, you will need to
1428                 build-depend on <package>libimlib2-dev</package> but
1429                 not against any <tt>libjpeg*</tt> packages, even
1430                 though <tt>libimlib2-dev</tt> currently depends on
1431                 them: installation of <package>libimlib2-dev</package>
1432                 will automatically ensure that all of its run-time
1433                 dependencies are satisfied.
1434           </footnote>
1435         </p>
1436
1437         <p>
1438           If build-time dependencies are specified, it must be
1439           possible to build the package and produce working binaries
1440           on a system with only essential and build-essential
1441           packages installed and also those required to satisfy the
1442           build-time relationships (including any implied
1443           relationships).  In particular, this means that version
1444           clauses should be used rigorously in build-time
1445           relationships so that one cannot produce bad or
1446           inconsistently configured packages when the relationships
1447           are properly satisfied.
1448         </p>
1449
1450         <p>
1451           <ref id="relationships"> explains the technical details.
1452         </p>
1453       </sect>
1454
1455       <sect>
1456         <heading>Changes to the upstream sources</heading>
1457
1458         <p>
1459           If changes to the source code are made that are not
1460           specific to the needs of the Debian system, they should be
1461           sent to the upstream authors in whatever form they prefer
1462           so as to be included in the upstream version of the
1463           package.
1464         </p>
1465
1466         <p>
1467           If you need to configure the package differently for
1468           Debian or for Linux, and the upstream source doesn't
1469           provide a way to do so, you should add such configuration
1470           facilities (for example, a new <prgn>autoconf</prgn> test
1471           or <tt>#define</tt>) and send the patch to the upstream
1472           authors, with the default set to the way they originally
1473           had it.  You can then easily override the default in your
1474           <file>debian/rules</file> or wherever is appropriate.
1475         </p>
1476
1477         <p>
1478           You should make sure that the <prgn>configure</prgn> utility
1479           detects the correct architecture specification string
1480           (refer to <ref id="arch-spec"> for details).
1481         </p>
1482
1483         <p>
1484           If you need to edit a <prgn>Makefile</prgn> where GNU-style
1485           <prgn>configure</prgn> scripts are used, you should edit the
1486           <file>.in</file> files rather than editing the
1487           <prgn>Makefile</prgn> directly.  This allows the user to
1488           reconfigure the package if necessary.  You should
1489           <em>not</em> configure the package and edit the generated
1490           <prgn>Makefile</prgn>!  This makes it impossible for someone
1491           else to later reconfigure the package without losing the
1492           changes you made.
1493         </p>
1494
1495       </sect>
1496
1497       <sect id="dpkgchangelog">
1498         <heading>Debian changelog: <file>debian/changelog</file></heading>
1499
1500         <p>
1501           Changes in the Debian version of the package should be
1502           briefly explained in the Debian changelog file
1503           <file>debian/changelog</file>.<footnote>
1504             <p>
1505               Mistakes in changelogs are usually best rectified by
1506               making a new changelog entry rather than "rewriting
1507               history" by editing old changelog entries.
1508             </p>
1509           </footnote>
1510           This includes modifications
1511           made in the Debian package compared to the upstream one
1512           as well as other changes and updates to the package.
1513           <footnote>
1514               Although there is nothing stopping an author who is also
1515               the Debian maintainer from using this changelog for all
1516               their changes, it will have to be renamed if the Debian
1517               and upstream maintainers become different people. In such
1518               a case, however, it might be better to maintain the package
1519               as a non-native package.
1520           </footnote>
1521         </p>
1522
1523         <p>
1524           The format of the <file>debian/changelog</file> allows the
1525           package building tools to discover which version of the package
1526           is being built and find out other release-specific information.
1527         </p>
1528
1529         <p>
1530           That format is a series of entries like this:
1531
1532 <example compact="compact">
1533 <var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
1534             <var>
1535               [optional blank line(s), stripped]
1536             </var>
1537   * <var>change details</var>
1538     <var>more change details</var>
1539             <var>
1540               [blank line(s), included in output of dpkg-parsechangelog]
1541             </var>
1542   * <var>even more change details</var>
1543             <var>
1544               [optional blank line(s), stripped]
1545             </var>
1546  -- <var>maintainer name</var> &lt;<var>email address</var>&gt;<var>[two spaces]</var>  <var>date</var>
1547 </example>
1548         </p>
1549
1550         <p>
1551           <var>package</var> and <var>version</var> are the source
1552           package name and version number.
1553         </p>
1554
1555         <p>
1556           <var>distribution(s)</var> lists the distributions where
1557           this version should be installed when it is uploaded - it
1558           is copied to the <tt>Distribution</tt> field in the
1559           <file>.changes</file> file.  See <ref id="f-Distribution">.
1560         </p>
1561
1562         <p>
1563           <var>urgency</var> is the value for the <tt>Urgency</tt>
1564           field in the <file>.changes</file> file for the upload
1565           (see <ref id="f-Urgency">). It is not possible to specify
1566           an urgency containing commas; commas are used to separate
1567           <tt><var>keyword</var>=<var>value</var></tt> settings in the
1568           <prgn>dpkg</prgn> changelog format (though there is
1569           currently only one useful <var>keyword</var>,
1570           <tt>urgency</tt>).
1571         </p>
1572
1573         <p>
1574           The change details may in fact be any series of lines
1575           starting with at least two spaces, but conventionally each
1576           change starts with an asterisk and a separating space and
1577           continuation lines are indented so as to bring them in
1578           line with the start of the text above.  Blank lines may be
1579           used here to separate groups of changes, if desired.
1580         </p>
1581
1582         <p>
1583           If this upload resolves bugs recorded in the Bug Tracking
1584           System (BTS), they may be automatically closed on the
1585           inclusion of this package into the Debian archive by
1586           including the string: <tt>closes: Bug#<var>nnnnn</var></tt>
1587           in the change details.<footnote>
1588               To be precise, the string should match the following
1589               Perl regular expression:
1590               <example>
1591 /closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i
1592               </example>
1593               Then all of the bug numbers listed will be closed by the
1594               archive maintenance script (<prgn>katie</prgn>) using the
1595               <var>version</var> of the changelog entry.
1596           </footnote>
1597           This information is conveyed via the <tt>Closes</tt> field
1598           in the <tt>.changes</tt> file (see <ref id="f-Closes">).
1599         </p>
1600
1601         <p>
1602           The maintainer name and email address used in the changelog
1603           should be the details of the person uploading <em>this</em>
1604           version.  They are <em>not</em> necessarily those of the
1605           usual package maintainer.  The information here will be
1606           copied to the <tt>Changed-By</tt> field in the
1607           <tt>.changes</tt> file (see <ref id="f-Changed-By">),
1608           and then later used to send an acknowledgement when the
1609           upload has been installed.
1610         </p>
1611
1612         <p>
1613           The <var>date</var> must be in RFC822 format<footnote>
1614               This is generated by <tt>date -R</tt>.
1615           </footnote>; it must include the time zone specified
1616           numerically, with the time zone name or abbreviation
1617           optionally present as a comment in parentheses.
1618         </p>
1619
1620         <p>
1621           The first "title" line with the package name must start
1622           at the left hand margin.  The "trailer" line with the
1623           maintainer and date details must be preceded by exactly
1624           one space.  The maintainer details and the date must be
1625           separated by exactly two spaces.
1626         </p>
1627
1628         <p>
1629           The entire changelog must be encoded in UTF-8.
1630         </p>
1631
1632         <p>
1633           For more information on placement of the changelog files
1634           within binary packages, please see <ref id="changelogs">.
1635         </p>
1636       </sect>
1637
1638       <sect id="dpkgcopyright">
1639         <heading>Copyright: <file>debian/copyright</file></heading>
1640         <p>
1641           Every package must be accompanied by a verbatim copy of its
1642           copyright information and distribution license in the file
1643           <file>/usr/share/doc/<var>package</var>/copyright</file>
1644           (see <ref id="copyrightfile"> for further details). Also see
1645           <ref id="pkgcopyright"> for further considerations related
1646           to copyrights for packages.
1647         </p>
1648       </sect>
1649       <sect>
1650         <heading>Error trapping in makefiles</heading>
1651
1652         <p>
1653           When <prgn>make</prgn> invokes a command in a makefile
1654           (including your package's upstream makefiles and
1655           <file>debian/rules</file>), it does so using <prgn>sh</prgn>.  This
1656           means that <prgn>sh</prgn>'s usual bad error handling
1657           properties apply: if you include a miniature script as one
1658           of the commands in your makefile you'll find that if you
1659           don't do anything about it then errors are not detected
1660           and <prgn>make</prgn> will blithely continue after
1661           problems.
1662         </p>
1663
1664         <p>
1665           Every time you put more than one shell command (this
1666           includes using a loop) in a makefile command you
1667           must make sure that errors are trapped.  For
1668           simple compound commands, such as changing directory and
1669           then running a program, using <tt>&amp;&amp;</tt> rather
1670           than semicolon as a command separator is sufficient.  For
1671           more complex commands including most loops and
1672           conditionals you should include a separate <tt>set -e</tt>
1673           command at the start of every makefile command that's
1674           actually one of these miniature shell scripts.
1675         </p>
1676       </sect>
1677
1678       <sect id="timestamps">
1679         <heading>Time Stamps</heading>
1680         <p>
1681           Maintainers should preserve the modification times of the
1682           upstream source files in a package, as far as is reasonably
1683           possible.<footnote>
1684               The rationale is that there is some information conveyed
1685               by knowing the age of the file, for example, you could
1686               recognize that some documentation is very old by looking
1687               at the modification time, so it would be nice if the
1688               modification time of the upstream source would be
1689               preserved.
1690           </footnote>
1691         </p>
1692       </sect>
1693
1694       <sect id="restrictions">
1695         <heading>Restrictions on objects in source packages</heading>
1696
1697         <p>
1698           The source package may not contain any hard links<footnote>
1699             <p>
1700               This is not currently detected when building source
1701               packages, but only when extracting
1702               them.
1703             </p>
1704             <p>
1705               Hard links may be permitted at some point in the
1706               future, but would require a fair amount of
1707               work.
1708             </p>
1709           </footnote>, device special files, sockets or setuid or
1710           setgid files.<footnote>
1711               Setgid directories are allowed.
1712           </footnote>
1713         </p>
1714       </sect>
1715
1716       <sect id="debianrules">
1717         <heading>Main building script: <file>debian/rules</file></heading>
1718
1719         <p>
1720           This file must be an executable makefile, and contains the
1721           package-specific recipes for compiling the package and
1722           building binary package(s) from the source.
1723         </p>
1724
1725         <p>
1726           It must start with the line <tt>#!/usr/bin/make -f</tt>,
1727           so that it can be invoked by saying its name rather than
1728           invoking <prgn>make</prgn> explicitly. That is, invoking
1729           either of <tt>make -f debian/rules <em>args...</em></tt>
1730           or <tt>./debian/rules <em>args...</em></tt> must result in
1731           identical behavior.
1732         </p>
1733
1734         <p>
1735           Since an interactive <file>debian/rules</file> script makes it
1736           impossible to auto-compile that package and also makes it
1737           hard for other people to reproduce the same binary
1738           package, all <em>required targets</em> must be
1739           non-interactive. At a minimum, required targets are the
1740           ones called by <prgn>dpkg-buildpackage</prgn>, namely,
1741           <em>clean</em>, <em>binary</em>, <em>binary-arch</em>,
1742           <em>binary-indep</em>, and <em>build</em>. It also follows
1743           that any target that these targets depend on must also be
1744           non-interactive.
1745         </p>
1746
1747         <p>
1748           The targets are as follows (required unless stated otherwise):
1749           <taglist>
1750             <tag><tt>build</tt></tag>
1751             <item>
1752               <p>
1753                 The <tt>build</tt> target should perform all the
1754                 configuration and compilation of the package.
1755                 If a package has an interactive pre-build
1756                 configuration routine, the Debianized source package
1757                 must either be built after this has taken place (so
1758                 that the binary package can be built without rerunning
1759                 the configuration) or the configuration routine
1760                 modified to become non-interactive.  (The latter is
1761                 preferable if there are architecture-specific features
1762                 detected by the configuration routine.)
1763               </p>
1764
1765               <p>
1766                 For some packages, notably ones where the same
1767                 source tree is compiled in different ways to produce
1768                 two binary packages, the <tt>build</tt> target
1769                 does not make much sense.  For these packages it is
1770                 good enough to provide two (or more) targets
1771                 (<tt>build-a</tt> and <tt>build-b</tt> or whatever)
1772                 for each of the ways of building the package, and a
1773                 <tt>build</tt> target that does nothing.  The
1774                 <tt>binary</tt> target will have to build the
1775                 package in each of the possible ways and make the
1776                 binary package out of each.
1777               </p>
1778
1779               <p>
1780                 The <tt>build</tt> target must not do anything
1781                 that might require root privilege.
1782               </p>
1783
1784               <p>
1785                 The <tt>build</tt> target may need to run the
1786                 <tt>clean</tt> target first - see below.
1787               </p>
1788
1789               <p>
1790                 When a package has a configuration and build routine
1791                 which takes a long time, or when the makefiles are
1792                 poorly designed, or when <tt>build</tt> needs to
1793                 run <tt>clean</tt> first, it is a good idea to
1794                 <tt>touch build</tt> when the build process is
1795                 complete.  This will ensure that if <tt>debian/rules
1796                 build</tt> is run again it will not rebuild the whole
1797                 program.<footnote>
1798                     Another common way to do this is for <tt>build</tt>
1799                     to depend on <prgn>build-stamp</prgn> and to do
1800                     nothing else, and for the <prgn>build-stamp</prgn>
1801                     target to do the building and to <tt>touch
1802                     build-stamp</tt> on completion.  This is
1803                     especially useful if the build routine creates a
1804                     file or directory called <tt>build</tt>; in such a
1805                     case, <tt>build</tt> will need to be listed as
1806                     a phony target (i.e., as a dependency of the
1807                     <tt>.PHONY</tt> target).  See the documentation of
1808                     <prgn>make</prgn> for more information on phony
1809                     targets.
1810                 </footnote>
1811               </p>
1812             </item>
1813
1814             <tag><tt>build-arch</tt> (optional),
1815                  <tt>build-indep</tt> (optional)
1816             </tag>
1817             <item>
1818               <p>
1819                 A package may also provide both of the targets
1820                 <tt>build-arch</tt> and <tt>build-indep</tt>.
1821                 The <tt>build-arch</tt> target, if provided, should
1822                 perform all the configuration and compilation required
1823                 for producing all architecture-dependant binary packages
1824                 (those packages for which the body of the
1825                 <tt>Architecture</tt> field in <tt>debian/control</tt>
1826                 is not <tt>all</tt>).
1827                 Similarly, the <tt>build-indep</tt> target, if
1828                 provided, should perform all the configuration and
1829                 compilation required for producing all
1830                 architecture-independent binary packages
1831                 (those packages for which the body of the
1832                 <tt>Architecture</tt> field in <tt>debian/control</tt>
1833                 is <tt>all</tt>).
1834                 The <tt>build</tt> target should depend on those of the
1835                 targets <tt>build-arch</tt> and <tt>build-indep</tt> that
1836                 are provided in the rules file.
1837               </p>
1838
1839               <p>
1840                 If one or both of the targets <tt>build-arch</tt> and
1841                 <tt>build-indep</tt> are not provided, then invoking
1842                 <file>debian/rules</file> with one of the not-provided
1843                 targets as arguments should produce a exit status code
1844                 of 2.  Usually this is provided automatically by make
1845                 if the target is missing.
1846               </p>
1847
1848               <p>
1849                 The <tt>build-arch</tt> and <tt>build-indep</tt> targets
1850                 must not do anything that might require root privilege.
1851               </p>
1852             </item>
1853
1854             <tag><tt>binary</tt>, <tt>binary-arch</tt>,
1855               <tt>binary-indep</tt>
1856             </tag>
1857             <item>
1858               <p>
1859                 The <tt>binary</tt> target must be all that is
1860                 necessary for the user to build the binary package(s)
1861                 produced from this source package.  It is
1862                 split into two parts: <prgn>binary-arch</prgn> builds
1863                 the binary packages which are specific to a particular
1864                 architecture, and <tt>binary-indep</tt> builds
1865                 those which are not.
1866               </p>
1867               <p>
1868                 <tt>binary</tt> may be (and commonly is) a target with
1869                 no commands which simply depends on
1870                 <tt>binary-arch</tt> and <tt>binary-indep</tt>.
1871               </p>
1872               <p>
1873                 Both <tt>binary-*</tt> targets should depend on the
1874                 <tt>build</tt> target, or on the appropriate
1875                 <tt>build-arch</tt> or <tt>build-indep</tt> target, if
1876                 provided, so that the package is built if it has not
1877                 been already.  It should then create the relevant
1878                 binary package(s), using <prgn>dpkg-gencontrol</prgn> to
1879                 make their control files and <prgn>dpkg-deb</prgn> to
1880                 build them and place them in the parent of the top
1881                 level directory.
1882               </p>
1883
1884               <p>
1885                 Both the <tt>binary-arch</tt> and
1886                 <tt>binary-indep</tt> targets <em>must</em> exist.
1887                 If one of them has nothing to do (which will always be
1888                 the case if the source generates only a single binary
1889                 package, whether architecture-dependent or not), it
1890                 must still exist and must always succeed.
1891               </p>
1892
1893               <p>
1894                 The <tt>binary</tt> targets must be invoked as
1895                 root.<footnote>
1896                     The <prgn>fakeroot</prgn> package often allows one
1897                     to build a package correctly even without being
1898                     root.
1899                 </footnote>
1900               </p>
1901             </item>
1902
1903             <tag><tt>clean</tt></tag>
1904             <item>
1905               <p>
1906                 This must undo any effects that the <tt>build</tt>
1907                 and <tt>binary</tt> targets may have had, except
1908                 that it should leave alone any output files created in
1909                 the parent directory by a run of a <tt>binary</tt>
1910                 target.
1911               </p>
1912
1913               <p>
1914                 If a <tt>build</tt> file is touched at the end of
1915                 the <tt>build</tt> target, as suggested above, it
1916                 should be removed as the first action that
1917                 <tt>clean</tt> performs, so that running
1918                 <tt>build</tt> again after an interrupted
1919                 <tt>clean</tt> doesn't think that everything is
1920                 already done.
1921               </p>
1922
1923               <p>
1924                 The <tt>clean</tt> target may need to be
1925                 invoked as root if <tt>binary</tt> has been
1926                 invoked since the last <tt>clean</tt>, or if
1927                 <tt>build</tt> has been invoked as root (since
1928                 <tt>build</tt> may create directories, for
1929                 example).
1930               </p>
1931             </item>
1932
1933             <tag><tt>get-orig-source</tt> (optional)</tag>
1934             <item>
1935               <p>
1936                 This target fetches the most recent version of the
1937                 original source package from a canonical archive site
1938                 (via FTP or WWW, for example), does any necessary
1939                 rearrangement to turn it into the original source
1940                 tar file format described below, and leaves it in the
1941                 current directory.
1942               </p>
1943
1944               <p>
1945                 This target may be invoked in any directory, and
1946                 should take care to clean up any temporary files it
1947                 may have left.
1948               </p>
1949
1950               <p>
1951                 This target is optional, but providing it if
1952                 possible is a good idea.
1953               </p>
1954             </item>
1955
1956             <tag><tt>patch</tt> (optional)</tag>
1957             <item>
1958               <p>
1959                 This target performs whatever additional actions are
1960                 required to make the source ready for editing (unpacking
1961                 additional upstream archives, applying patches, etc.).
1962                 It is recommended to be implemented for any package where
1963                 <tt>dpkg-source -x</tt> does not result in source ready
1964                 for additional modification.  See
1965                 <ref id="readmesource">.
1966               </p>
1967             </item>
1968           </taglist>
1969
1970         <p>
1971           The <tt>build</tt>, <tt>binary</tt> and
1972           <tt>clean</tt> targets must be invoked with the current
1973           directory being the package's top-level directory.
1974         </p>
1975
1976
1977         <p>
1978           Additional targets may exist in <file>debian/rules</file>,
1979           either as published or undocumented interfaces or for the
1980           package's internal use.
1981         </p>
1982
1983         <p>
1984           The architectures we build on and build for are determined
1985           by <prgn>make</prgn> variables using the utility
1986           <qref id="pkg-dpkg-architecture"><prgn>dpkg-architecture</prgn></qref>.
1987           You can determine the
1988           Debian architecture and the GNU style architecture
1989           specification string for the build machine (the machine type
1990           we are building on) as well as for the host machine (the
1991           machine type we are building for).  Here is a list of
1992           supported <prgn>make</prgn> variables:
1993           <list compact="compact">
1994             <item>
1995                 <tt>DEB_*_ARCH</tt> (the Debian architecture)
1996             </item>
1997             <item>
1998                 <tt>DEB_*_ARCH_CPU</tt> (the Debian CPU name)
1999             </item>
2000             <item>
2001                 <tt>DEB_*_ARCH_OS</tt> (the Debian System name)
2002             </item>
2003             <item>
2004                 <tt>DEB_*_GNU_TYPE</tt> (the GNU style architecture
2005                 specification string)
2006             </item>
2007             <item>
2008                 <tt>DEB_*_GNU_CPU</tt> (the CPU part of
2009                 <tt>DEB_*_GNU_TYPE</tt>)
2010             </item>
2011             <item>
2012                 <tt>DEB_*_GNU_SYSTEM</tt> (the System part of
2013                 <tt>DEB_*_GNU_TYPE</tt>)
2014           </list>
2015           where <tt>*</tt> is either <tt>BUILD</tt> for specification of
2016           the build machine or <tt>HOST</tt> for specification of the
2017           host machine.
2018         </p>
2019
2020         <p>
2021           Backward compatibility can be provided in the rules file
2022           by setting the needed variables to suitable default
2023           values; please refer to the documentation of
2024           <prgn>dpkg-architecture</prgn> for details.
2025         </p>
2026
2027         <p>
2028           It is important to understand that the <tt>DEB_*_ARCH</tt>
2029           string only determines which Debian architecture we are
2030           building on or for. It should not be used to get the CPU
2031           or system information; the <tt>DEB_*_ARCH_CPU</tt> and
2032           <tt>DEB_*_ARCH_OS</tt> variables should be used for that.
2033           GNU style variables should generally only be used with upstream
2034           build systems.
2035         </p>
2036
2037         <sect1 id="debianrules-options">
2038           <heading><file>debian/rules</file> and
2039             <tt>DEB_BUILD_OPTIONS</tt></heading>
2040
2041           <p>
2042             Supporting the standardized environment variable
2043             <tt>DEB_BUILD_OPTIONS</tt> is recommended.  This variable can
2044             contain several flags to change how a package is compiled and
2045             built.  Each flag must be in the form <var>flag</var> or
2046             <var>flag</var>=<var>options</var>.  If multiple flags are
2047             given, they must be separated by whitespace.<footnote>
2048               Some packages support any delimiter, but whitespace is the
2049               easiest to parse inside a makefile and avoids ambiguity with
2050               flag values that contain commas.
2051             </footnote>
2052             <var>flag</var> must start with a lowercase letter
2053             (<tt>a-z</tt>) and consist only of lowercase letters,
2054             numbers (<tt>0-9</tt>), and the characters
2055             <tt>-</tt> and <tt>_</tt> (hyphen and underscore).
2056             <var>options</var> must not contain whitespace.  The same
2057             tag should not be given multiple times with conflicting
2058             values.  Package maintainers may assume that
2059             <tt>DEB_BUILD_OPTIONS</tt> will not contain conflicting tags.
2060           </p>
2061
2062           <p>
2063             The meaning of the following tags has been standardized:
2064             <taglist>
2065               <tag>nocheck</tag>
2066               <item>
2067                   This tag says to not run any build-time test suite
2068                   provided by the package.
2069               </item>
2070               <tag>noopt</tag>
2071               <item>
2072                   The presence of this tag means that the package should
2073                   be compiled with a minimum of optimization.  For C
2074                   programs, it is best to add <tt>-O0</tt> to
2075                   <tt>CFLAGS</tt> (although this is usually the default).
2076                   Some programs might fail to build or run at this level
2077                   of optimization; it may be necessary to use
2078                   <tt>-O1</tt>, for example.
2079               </item>
2080               <tag>nostrip</tag>
2081               <item>
2082                   This tag means that the debugging symbols should not be
2083                   stripped from the binary during installation, so that
2084                   debugging information may be included in the package.
2085               </item>
2086               <tag>parallel=n</tag>
2087               <item>
2088                   This tag means that the package should be built using up
2089                   to <tt>n</tt> parallel processes if the package build
2090                   system supports this.<footnote>
2091                       Packages built with <tt>make</tt> can often implement
2092                       this by passing the <tt>-j</tt><var>n</var> option to
2093                       <tt>make</tt>.
2094                   </footnote>
2095                   If the package build system does not support parallel
2096                   builds, this string must be ignored.  If the package
2097                   build system only supports a lower level of concurrency
2098                   than <var>n</var>, the package should be built using as
2099                   many parallel processes as the package build system
2100                   supports.  It is up to the package maintainer to decide
2101                   whether the package build times are long enough and the
2102                   package build system is robust enough to make supporting
2103                   parallel builds worthwhile.
2104                </item>
2105             </taglist>
2106           </p>
2107
2108           <p>
2109             Unknown flags must be ignored by <file>debian/rules</file>.
2110           </p>
2111
2112           <p>
2113             The following makefile snippet is an example of how one may
2114             implement the build options; you will probably have to
2115             massage this example in order to make it work for your
2116             package.
2117             <example compact="compact">
2118 CFLAGS = -Wall -g
2119 INSTALL = install
2120 INSTALL_FILE    = $(INSTALL) -p    -o root -g root  -m  644
2121 INSTALL_PROGRAM = $(INSTALL) -p    -o root -g root  -m  755
2122 INSTALL_SCRIPT  = $(INSTALL) -p    -o root -g root  -m  755
2123 INSTALL_DIR     = $(INSTALL) -p -d -o root -g root  -m  755
2124
2125 ifneq (,$(filter noopt,$(DEB_BUILD_OPTIONS)))
2126     CFLAGS += -O0
2127 else
2128     CFLAGS += -O2
2129 endif
2130 ifeq (,$(filter nostrip,$(DEB_BUILD_OPTIONS)))
2131     INSTALL_PROGRAM += -s
2132 endif
2133 ifneq (,$(filter parallel=%,$(DEB_BUILD_OPTIONS)))
2134     NUMJOBS = $(patsubst parallel=%,%,$(filter parallel=%,$(DEB_BUILD_OPTIONS)))
2135     MAKEFLAGS += -j$(NUMJOBS)
2136 endif
2137
2138 build:
2139         # ...
2140 ifeq (,$(filter nocheck,$(DEB_BUILD_OPTIONS)))
2141         # Code to run the package test suite.
2142 endif
2143             </example>
2144           </p>
2145         </sect1>
2146       </sect>
2147
2148 <!-- FIXME: section pkg-srcsubstvars is the same as substvars -->
2149       <sect id="substvars">
2150         <heading>Variable substitutions: <file>debian/substvars</file></heading>
2151
2152         <p>
2153           When <prgn>dpkg-gencontrol</prgn>,
2154           <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
2155           generate control files they perform variable substitutions
2156           on their output just before writing it.  Variable
2157           substitutions have the form <tt>${<var>variable</var>}</tt>.
2158           The optional file <file>debian/substvars</file> contains
2159           variable substitutions to be used; variables can also be set
2160           directly from <file>debian/rules</file> using the <tt>-V</tt>
2161           option to the source packaging commands, and certain
2162           predefined variables are also available.
2163         </p>
2164
2165         <p>
2166           The <file>debian/substvars</file> file is usually generated and
2167           modified dynamically by <file>debian/rules</file> targets, in
2168           which case it must be removed by the <tt>clean</tt> target.
2169         </p>
2170
2171         <p>
2172           See <manref name="deb-substvars" section="5"> for full
2173           details about source variable substitutions, including the
2174           format of <file>debian/substvars</file>.</p>
2175       </sect>
2176
2177       <sect id="debianwatch">
2178         <heading>Optional upstream source location: <file>debian/watch</file></heading>
2179
2180         <p>
2181           This is an optional, recommended control file for the
2182           <tt>uscan</tt> utility which defines how to automatically
2183           scan ftp or http sites for newly available updates of the
2184           package. This is used by <url id="
2185           http://dehs.alioth.debian.org/"> and other Debian QA tools
2186           to help with quality control and maintenance of the
2187           distribution as a whole.
2188         </p>
2189
2190       </sect>
2191
2192       <sect id="debianfiles">
2193         <heading>Generated files list: <file>debian/files</file></heading>
2194
2195         <p>
2196           This file is not a permanent part of the source tree; it
2197           is used while building packages to record which files are
2198           being generated.  <prgn>dpkg-genchanges</prgn> uses it
2199           when it generates a <file>.changes</file> file.
2200         </p>
2201
2202         <p>
2203           It should not exist in a shipped source package, and so it
2204           (and any backup files or temporary files such as
2205           <file>files.new</file><footnote>
2206               <file>files.new</file> is used as a temporary file by
2207               <prgn>dpkg-gencontrol</prgn> and
2208               <prgn>dpkg-distaddfile</prgn> - they write a new
2209               version of <tt>files</tt> here before renaming it,
2210               to avoid leaving a corrupted copy if an error
2211               occurs.
2212           </footnote>) should be removed by the
2213           <tt>clean</tt> target.  It may also be wise to
2214           ensure a fresh start by emptying or removing it at the
2215           start of the <tt>binary</tt> target.
2216         </p>
2217
2218         <p>
2219           When <prgn>dpkg-gencontrol</prgn> is run for a binary
2220           package, it adds an entry to <file>debian/files</file> for the
2221           <file>.deb</file> file that will be created when <tt>dpkg-deb
2222           --build</tt> is run for that binary package.  So for most
2223           packages all that needs to be done with this file is to
2224           delete it in the <tt>clean</tt> target.
2225         </p>
2226
2227         <p>
2228           If a package upload includes files besides the source
2229           package and any binary packages whose control files were
2230           made with <prgn>dpkg-gencontrol</prgn> then they should be
2231           placed in the parent of the package's top-level directory
2232           and <prgn>dpkg-distaddfile</prgn> should be called to add
2233           the file to the list in <file>debian/files</file>.</p>
2234       </sect>
2235
2236       <sect id="embeddedfiles">
2237         <heading>Convenience copies of code</heading>
2238
2239         <p>
2240           Some software packages include in their distribution convenience
2241           copies of code from other software packages, generally so that
2242           users compiling from source don't have to download multiple
2243           packages.  Debian packages should not make use of these
2244           convenience copies unless the included package is explicitly
2245           intended to be used in this way.<footnote>
2246             For example, parts of the GNU build system work like this.
2247           </footnote>
2248           If the included code is already in the Debian archive in the
2249           form of a library, the Debian packaging should ensure that
2250           binary packages reference the libraries already in Debian and
2251           the convenience copy is not used.  If the included code is not
2252           already in Debian, it should be packaged separately as a
2253           prerequisite if possible.
2254           <footnote>
2255             Having multiple copies of the same code in Debian is
2256             inefficient, often creates either static linking or shared
2257             library conflicts, and, most importantly, increases the
2258             difficulty of handling security vulnerabilities in the
2259             duplicated code.
2260           </footnote>
2261         </p>
2262       </sect>
2263
2264       <sect id="readmesource">
2265         <heading>Source package handling:
2266           <file>debian/README.source</file></heading>
2267
2268         <p>
2269           If running <prgn>dpkg-source -x</prgn> on a source package
2270           doesn't produce the source of the package, ready for editing,
2271           and allow one to make changes and run
2272           <prgn>dpkg-buildpackage</prgn> to produce a modified package
2273           without taking any additional steps, creating a
2274           <file>debian/README.source</file> documentation file is
2275           recommended.  This file should explain how to do all of the
2276           following:
2277             <enumlist>
2278               <item>Generate the fully patched source, in a form ready for
2279               editing, that would be built to create Debian
2280               packages.  Doing this with a <tt>patch</tt> target in
2281               <file>debian/rules</file> is recommended; see
2282               <ref id="debianrules">.</item>
2283               <item>Modify the source and save those modifications so that
2284               they will be applied when building the package.</item>
2285               <item>Remove source modifications that are currently being
2286               applied when building the package.</item>
2287               <item>Optionally, document what steps are necessary to
2288               upgrade the Debian source package to a new upstream version,
2289               if applicable.</item>
2290             </enumlist>
2291           This explanation should include specific commands and mention
2292           any additional required Debian packages.  It should not assume
2293           familiarity with any specific Debian packaging system or patch
2294           management tools.
2295         </p>
2296
2297         <p>
2298           This explanation may refer to a documentation file installed by
2299           one of the package's build dependencies provided that the
2300           referenced documentation clearly explains these tasks and is not
2301           a general reference manual.
2302         </p>
2303
2304         <p>
2305           <file>debian/README.source</file> may also include any other
2306           information that would be helpful to someone modifying the
2307           source package.  Even if the package doesn't fit the above
2308           description, maintainers are encouraged to document in a
2309           <file>debian/README.source</file> file any source package with a
2310           particularly complex or unintuitive source layout or build
2311           system (for example, a package that builds the same source
2312           multiple times to generate different binary packages).
2313         </p>
2314       </sect>
2315     </chapt>
2316
2317
2318     <chapt id="controlfields">
2319       <heading>Control files and their fields</heading>
2320
2321       <p>
2322         The package management system manipulates data represented in
2323         a common format, known as <em>control data</em>, stored in
2324         <em>control files</em>.
2325         Control files are used for source packages, binary packages and
2326         the <file>.changes</file> files which control the installation
2327         of uploaded files<footnote>
2328             <prgn>dpkg</prgn>'s internal databases are in a similar
2329             format.
2330         </footnote>.
2331       </p>
2332
2333       <sect id="controlsyntax">
2334         <heading>Syntax of control files</heading>
2335
2336         <p>
2337           A control file consists of one or more paragraphs of
2338           fields<footnote>
2339                 The paragraphs are also sometimes referred to as stanzas.
2340           </footnote>.
2341           The paragraphs are separated by blank lines.  Some control
2342           files allow only one paragraph; others allow several, in
2343           which case each paragraph usually refers to a different
2344           package.  (For example, in source packages, the first
2345           paragraph refers to the source package, and later paragraphs
2346           refer to binary packages generated from the source.)
2347         </p>
2348
2349         <p>
2350           Each paragraph consists of a series of data fields; each
2351           field consists of the field name, followed by a colon and
2352           then the data/value associated with that field.  It ends at
2353           the end of the (logical) line.  Horizontal whitespace
2354           (spaces and tabs) may occur immediately before or after the
2355           value and is ignored there; it is conventional to put a
2356           single space after the colon.  For example, a field might
2357           be:
2358           <example compact="compact">
2359 Package: libc6
2360           </example>
2361           the field name is <tt>Package</tt> and the field value
2362           <tt>libc6</tt>.
2363         </p>
2364
2365         <p>
2366           Many fields' values may span several lines; in this case
2367           each continuation line must start with a space or a tab.
2368           Any trailing spaces or tabs at the end of individual
2369           lines of a field value are ignored. 
2370         </p>
2371
2372         <p>
2373           In fields where it is specified that lines may not wrap,
2374           only a single line of data is allowed and whitespace is not
2375           significant in a field body. Whitespace must not appear
2376           inside names (of packages, architectures, files or anything
2377           else) or version numbers, or between the characters of
2378           multi-character version relationships.
2379         </p>
2380
2381         <p>
2382           Field names are not case-sensitive, but it is usual to
2383           capitalize the field names using mixed case as shown below.
2384           Field values are case-sensitive unless the description of the
2385           field says otherwise.
2386         </p>
2387
2388         <p>
2389           Blank lines, or lines consisting only of spaces and tabs,
2390           are not allowed within field values or between fields - that
2391           would mean a new paragraph.
2392         </p>
2393
2394         <p>
2395           All control files must be encoded in UTF-8.
2396         </p>
2397       </sect>
2398
2399       <sect id="sourcecontrolfiles">
2400         <heading>Source package control files -- <file>debian/control</file></heading>
2401
2402         <p>
2403           The <file>debian/control</file> file contains the most vital
2404           (and version-independent) information about the source package
2405           and about the binary packages it creates.
2406         </p>
2407
2408         <p>
2409           The first paragraph of the control file contains information about
2410           the source package in general. The subsequent sets each describe a
2411           binary package that the source tree builds.
2412         </p>
2413
2414         <p>
2415           The fields in the general paragraph (the first one, for the source
2416           package) are:
2417
2418           <list compact="compact">
2419             <item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
2420             <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
2421             <item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
2422             <item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
2423             <item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
2424             <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
2425             <item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
2426             <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
2427           </list>
2428         </p>
2429
2430         <p>
2431           The fields in the binary package paragraphs are:
2432
2433           <list compact="compact">
2434             <item><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</item>
2435             <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (mandatory)</item>
2436             <item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
2437             <item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
2438             <item><qref id="f-Essential"><tt>Essential</tt></qref></item>
2439             <item><qref id="binarydeps"><tt>Depends</tt> et al</qref></item>
2440             <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
2441             <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
2442           </list>
2443         </p>
2444
2445         <p>
2446           The syntax and semantics of the fields are described below.
2447         </p>
2448
2449 <!-- stuff -->
2450
2451         <p>
2452           These fields are used by <prgn>dpkg-gencontrol</prgn> to
2453           generate control files for binary packages (see below), by
2454           <prgn>dpkg-genchanges</prgn> to generate the
2455           <tt>.changes</tt> file to accompany the upload, and by
2456           <prgn>dpkg-source</prgn> when it creates the
2457           <file>.dsc</file> source control file as part of a source
2458           archive. Many fields are permitted to span multiple lines in
2459           <file>debian/control</file> but not in any other control
2460           file. These tools are responsible for removing the line
2461           breaks from such fields when using fields from
2462           <file>debian/control</file> to generate other control files.
2463         </p>
2464
2465         <p>
2466           The fields here may contain variable references - their
2467           values will be substituted by <prgn>dpkg-gencontrol</prgn>,
2468           <prgn>dpkg-genchanges</prgn> or <prgn>dpkg-source</prgn>
2469           when they generate output control files.
2470           See <ref id="substvars"> for details.
2471         </p>
2472
2473         <p>
2474           In addition to the control file syntax described <qref
2475           id="controlsyntax">above</qref>, this file may also contain
2476           comment lines starting with <tt>#</tt> without any preceding
2477           whitespace.  All such lines are ignored, even in the middle of
2478           continuation lines for a multiline field, and do not end a
2479           multiline field.
2480         </p>
2481
2482       </sect>
2483
2484       <sect id="binarycontrolfiles">
2485         <heading>Binary package control files -- <file>DEBIAN/control</file></heading>
2486
2487         <p>
2488           The <file>DEBIAN/control</file> file contains the most vital
2489           (and version-dependent) information about a binary package.
2490         </p>
2491
2492         <p>
2493           The fields in this file are:
2494
2495           <list compact="compact">
2496             <item><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</item>
2497             <item><qref id="f-Source"><tt>Source</tt></qref></item>
2498             <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
2499             <item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
2500             <item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
2501             <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (mandatory)</item>
2502             <item><qref id="f-Essential"><tt>Essential</tt></qref></item>
2503             <item><qref id="binarydeps"><tt>Depends</tt> et al</qref></item>
2504             <item><qref id="f-Installed-Size"><tt>Installed-Size</tt></qref></item>
2505             <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
2506             <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
2507             <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
2508           </list>
2509         </p>
2510       </sect>
2511
2512       <sect id="debiansourcecontrolfiles">
2513         <heading>Debian source control files -- <tt>.dsc</tt></heading>
2514
2515         <p>
2516           This file contains a series of fields, identified and
2517           separated just like the fields in the control file of
2518           a binary package.  The fields are listed below; their
2519           syntax is described above, in <ref id="pkg-controlfields">.
2520
2521         <list compact="compact">
2522           <item><qref id="f-Format"><tt>Format</tt></qref> (mandatory)</item>
2523           <item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
2524           <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
2525           <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
2526           <item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
2527           <item><qref id="f-Binary"><tt>Binary</tt></qref></item>
2528           <item><qref id="f-Architecture"><tt>Architecture</tt></qref></item>
2529           <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
2530           <item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
2531           <item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
2532           <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
2533         </list>
2534         </p>
2535
2536         <p>
2537           The source package control file is generated by
2538           <prgn>dpkg-source</prgn> when it builds the source
2539           archive, from other files in the source package,
2540           described above.  When unpacking, it is checked against
2541           the files and directories in the other parts of the
2542           source package.
2543         </p>
2544
2545       </sect>
2546
2547       <sect id="debianchangesfiles">
2548         <heading>Debian changes files -- <file>.changes</file></heading>
2549
2550         <p>
2551           The .changes files are used by the Debian archive maintenance
2552           software to process updates to packages. They contain one
2553           paragraph which contains information from the
2554           <tt>debian/control</tt> file and other data about the
2555           source package gathered via <tt>debian/changelog</tt>
2556           and <tt>debian/rules</tt>.
2557         </p>
2558
2559         <p>
2560           The fields in this file are:
2561
2562           <list compact="compact">
2563             <item><qref id="f-Format"><tt>Format</tt></qref> (mandatory)</item>
2564             <item><qref id="f-Date"><tt>Date</tt></qref> (mandatory)</item>
2565             <item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
2566             <item><qref id="f-Binary"><tt>Binary</tt></qref> (mandatory)</item>
2567             <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (mandatory)</item>
2568             <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
2569             <item><qref id="f-Distribution"><tt>Distribution</tt></qref> (mandatory)</item>
2570             <item><qref id="f-Urgency"><tt>Urgency</tt></qref> (recommended)</item>
2571             <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
2572             <item><qref id="f-Changed-By"><tt>Changed-By</tt></qref></item>
2573             <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
2574             <item><qref id="f-Closes"><tt>Closes</tt></qref></item>
2575             <item><qref id="f-Changes"><tt>Changes</tt></qref> (mandatory)</item>
2576             <item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
2577           </list>
2578         </p>
2579       </sect>
2580
2581       <sect id="controlfieldslist">
2582         <heading>List of fields</heading>
2583
2584         <sect1 id="f-Source">
2585           <heading><tt>Source</tt></heading>
2586
2587           <p>
2588             This field identifies the source package name.
2589           </p>
2590
2591           <p>
2592             In <file>debian/control</file> or a <file>.dsc</file> file,
2593             this field must contain only the name of the source package.
2594           </p>
2595
2596           <p>
2597             In a binary package control file or a <file>.changes</file>
2598             file, the source package name may be followed by a version
2599             number in parentheses<footnote>
2600                 It is customary to leave a space after the package name
2601                 if a version number is specified.
2602             </footnote>.
2603             This version number may be omitted (and is, by
2604             <prgn>dpkg-gencontrol</prgn>) if it has the same value as
2605             the <tt>Version</tt> field of the binary package in
2606             question.  The field itself may be omitted from a binary
2607             package control file when the source package has the same
2608             name and version as the binary package.
2609           </p>
2610
2611           <p>
2612             Package names (both source and binary,
2613             see <ref id="f-Package">) must consist only of lower case
2614             letters (<tt>a-z</tt>), digits (<tt>0-9</tt>), plus
2615             (<tt>+</tt>) and minus (<tt>-</tt>) signs, and periods
2616             (<tt>.</tt>).  They must be at least two characters long and
2617             must start with an alphanumeric character.
2618           </p>
2619         </sect1>
2620
2621         <sect1 id="f-Maintainer">
2622           <heading><tt>Maintainer</tt></heading>
2623
2624           <p>
2625             The package maintainer's name and email address.  The name
2626             should come first, then the email address inside angle
2627             brackets <tt>&lt;&gt</tt> (in RFC822 format).
2628           </p>
2629
2630           <p>
2631             If the maintainer's name contains a full stop then the
2632             whole field will not work directly as an email address due
2633             to a misfeature in the syntax specified in RFC822; a
2634             program using this field as an address must check for this
2635             and correct the problem if necessary (for example by
2636             putting the name in round brackets and moving it to the
2637             end, and bringing the email address forward).
2638           </p>
2639         </sect1>
2640
2641         <sect1 id="f-Uploaders">
2642           <heading><tt>Uploaders</tt></heading>
2643
2644           <p>
2645             List of the names and email addresses of co-maintainers of
2646             the package, if any. If the package has other maintainers
2647             beside the one named in the 
2648             <qref id="f-Maintainer">Maintainer field</qref>, their
2649             names and email addresses should be listed here. The
2650             format is the same as that of the Maintainer tag, and
2651             multiple entries should be comma separated. Currently,
2652             this field is restricted to a single line of data.  This
2653             is an optional field.
2654           </p>
2655           <p>
2656             Any parser that interprets the Uploaders field in
2657             <file>debian/control</file> must permit it to span multiple
2658             lines.  Line breaks in an Uploaders field that spans multiple
2659             lines are not significant and the semantics of the field are
2660             the same as if the line breaks had not been present.
2661           </p>
2662         </sect1>
2663
2664         <sect1 id="f-Changed-By">
2665           <heading><tt>Changed-By</tt></heading>
2666
2667           <p>
2668             The name and email address of the person who changed the
2669             said package. Usually the name of the maintainer.
2670             All the rules for the Maintainer field apply here, too.
2671           </p>
2672         </sect1>
2673
2674         <sect1 id="f-Section">
2675           <heading><tt>Section</tt></heading>
2676
2677           <p>
2678             This field specifies an application area into which the package
2679             has been classified. See <ref id="subsections">.
2680           </p>
2681
2682           <p>
2683             When it appears in the <file>debian/control</file> file,
2684             it gives the value for the subfield of the same name in
2685             the <tt>Files</tt> field of the <file>.changes</file> file.
2686             It also gives the default for the same field in the binary
2687             packages.
2688           </p>
2689         </sect1>
2690
2691         <sect1 id="f-Priority">
2692           <heading><tt>Priority</tt></heading>
2693
2694           <p>
2695             This field represents how important it is that the user
2696             have the package installed. See <ref id="priorities">.
2697           </p>
2698
2699           <p>
2700             When it appears in the <file>debian/control</file> file,
2701             it gives the value for the subfield of the same name in
2702             the <tt>Files</tt> field of the <file>.changes</file> file.
2703             It also gives the default for the same field in the binary
2704             packages.
2705           </p>
2706         </sect1>
2707
2708         <sect1 id="f-Package">
2709           <heading><tt>Package</tt></heading>
2710
2711           <p>
2712             The name of the binary package.
2713           </p>
2714
2715           <p>
2716             Binary package names must follow the same syntax and
2717             restrictions as source package names.  See <ref id="f-Source">
2718             for the details.
2719           </p>
2720         </sect1>
2721
2722         <sect1 id="f-Architecture">
2723           <heading><tt>Architecture</tt></heading>
2724
2725           <p>
2726             Depending on context and the control file used, the
2727             <tt>Architecture</tt> field can include the following sets of
2728             values:
2729             <list>
2730                 <item>A unique single word identifying a Debian machine
2731                       architecture as described in <ref id="arch-spec">.
2732                 <item><tt>all</tt>, which indicates an
2733                       architecture-independent package.
2734                 <item><tt>any</tt>, which indicates a package available
2735                       for building on any architecture.
2736                 <item><tt>source</tt>, which indicates a source package.
2737             </list>
2738           </p>
2739
2740           <p>
2741             In the main <file>debian/control</file> file in the source
2742             package, this field may contain the special value
2743             <tt>any</tt>, the special value <tt>all</tt>, or a list of
2744             architectures separated by spaces.  If <tt>any</tt> or
2745             <tt>all</tt> appear, they must be the entire contents of the
2746             field.  Most packages will use either <tt>any</tt> or
2747             <tt>all</tt>.  Specifying a specific list of architectures is
2748             for the minority of cases where a program is not portable or
2749             is not useful on some architectures, and where possible the
2750             program should be made portable instead.
2751           </p>
2752
2753           <p>
2754             In the source package control file <file>.dsc</file>, this
2755             field may contain either the special value <tt>any</tt> or a
2756             list of architectures separated by spaces. If a list is given,
2757             it may include (or consist solely of) the special value
2758             <tt>all</tt>.  In other words, in <file>.dsc</file> files
2759             unlike the <file>debian/control</file>, <tt>all</tt> may occur
2760             in combination with specific architectures.  The
2761             <tt>Architecture</tt> field in the source package control file
2762             <file>.dsc</file> is generally constructed from the
2763             <tt>Architecture</tt> fields in the
2764             <file>debian/control</file> in the source package.
2765           </p>
2766
2767           <p>
2768             Specifying <tt>any</tt> indicates that the source package
2769             isn't dependent on any particular architecture and should
2770             compile fine on any one. The produced binary package(s)
2771             will either be specific to whatever the current build
2772             architecture is or will be architecture-independent.
2773           </p>
2774
2775           <p>
2776             Specifying only <tt>all</tt> indicates that the source package
2777             will only build architecture-independent packages.  If this is
2778             the case, <tt>all</tt> must be used rather than <tt>any</tt>;
2779             <tt>any</tt> implies that the source package will build at
2780             least one architecture-dependent package.
2781           </p>
2782
2783           <p>
2784             Specifying a list of architectures indicates that the source
2785             will build an architecture-dependent package, and will only
2786             work correctly on the listed architectures.  If the source
2787             package also builds at least one architecture-independent
2788             package, <tt>all</tt> will also be included in the list.
2789           </p>
2790
2791           <p>
2792             In a <file>.changes</file> file, the <tt>Architecture</tt>
2793             field lists the architecture(s) of the package(s)
2794             currently being uploaded.  This will be a list; if the
2795             source for the package is also being uploaded, the special
2796             entry <tt>source</tt> is also present.  <tt>all</tt> will be
2797             present if any architecture-independent packages are being
2798             uploaded.  <tt>any</tt> may never occur in the
2799             <tt>Architecture</tt> field in the <file>.changes</file>
2800             file.
2801           </p>
2802
2803           <p>
2804             See <ref id="debianrules"> for information on how to get
2805             the architecture for the build process.
2806           </p>
2807         </sect1>
2808
2809         <sect1 id="f-Essential">
2810           <heading><tt>Essential</tt></heading>
2811
2812           <p>
2813             This is a boolean field which may occur only in the
2814             control file of a binary package or in a per-package fields
2815             paragraph of a main source control data file.
2816           </p>
2817
2818           <p>
2819             If set to <tt>yes</tt> then the package management system
2820             will refuse to remove the package (upgrading and replacing
2821             it is still possible). The other possible value is <tt>no</tt>,
2822             which is the same as not having the field at all.
2823           </p>
2824         </sect1>
2825
2826         <sect1>
2827           <heading>Package interrelationship fields:
2828             <tt>Depends</tt>, <tt>Pre-Depends</tt>,
2829             <tt>Recommends</tt>, <tt>Suggests</tt>,
2830             <tt>Breaks</tt>, <tt>Conflicts</tt>,
2831             <tt>Provides</tt>, <tt>Replaces</tt>, <tt>Enhances</tt>
2832           </heading>
2833
2834           <p>
2835             These fields describe the package's relationships with
2836             other packages.  Their syntax and semantics are described
2837             in <ref id="relationships">.</p>
2838         </sect1>
2839
2840         <sect1 id="f-Standards-Version">
2841           <heading><tt>Standards-Version</tt></heading>
2842
2843           <p>
2844             The most recent version of the standards (the policy
2845             manual and associated texts) with which the package
2846             complies.
2847           </p>
2848
2849           <p>
2850             The version number has four components: major and minor
2851             version number and major and minor patch level.  When the
2852             standards change in a way that requires every package to
2853             change the major number will be changed.  Significant
2854             changes that will require work in many packages will be
2855             signaled by a change to the minor number.  The major patch
2856             level will be changed for any change to the meaning of the
2857             standards, however small; the minor patch level will be
2858             changed when only cosmetic, typographical or other edits
2859             are made which neither change the meaning of the document
2860             nor affect the contents of packages.
2861           </p>
2862
2863           <p>
2864             Thus only the first three components of the policy version
2865             are significant in the <em>Standards-Version</em> control
2866             field, and so either these three components or all four
2867             components may be specified.<footnote>
2868                 In the past, people specified the full version number
2869                 in the Standards-Version field, for example "2.3.0.0".
2870                 Since minor patch-level changes don't introduce new
2871                 policy, it was thought it would be better to relax
2872                 policy and only require the first 3 components to be
2873                 specified, in this example "2.3.0".  All four
2874                 components may still be used if someone wishes to do so.
2875             </footnote>
2876           </p>
2877
2878         </sect1>
2879
2880         <sect1 id="f-Version">
2881           <heading><tt>Version</tt></heading>
2882
2883           <p>
2884             The version number of a package. The format is:
2885             [<var>epoch</var><tt>:</tt>]<var>upstream_version</var>[<tt>-</tt><var>debian_revision</var>]
2886           </p>
2887
2888           <p>
2889             The three components here are:
2890             <taglist>
2891               <tag><var>epoch</var></tag>
2892               <item>
2893                 <p>
2894                   This is a single (generally small) unsigned integer.  It
2895                   may be omitted, in which case zero is assumed.  If it is
2896                   omitted then the <var>upstream_version</var> may not
2897                   contain any colons.
2898                 </p>
2899
2900                 <p>
2901                   It is provided to allow mistakes in the version numbers
2902                   of older versions of a package, and also a package's
2903                   previous version numbering schemes, to be left behind.
2904                 </p>
2905               </item>
2906
2907               <tag><var>upstream_version</var></tag>
2908               <item>
2909                 <p>
2910                   This is the main part of the version number.  It is
2911                   usually the version number of the original ("upstream")
2912                   package from which the <file>.deb</file> file has been made,
2913                   if this is applicable.  Usually this will be in the same
2914                   format as that specified by the upstream author(s);
2915                   however, it may need to be reformatted to fit into the
2916                   package management system's format and comparison
2917                   scheme.
2918                 </p>
2919
2920                 <p>
2921                   The comparison behavior of the package management system
2922                   with respect to the <var>upstream_version</var> is
2923                   described below.  The <var>upstream_version</var>
2924                   portion of the version number is mandatory.
2925                 </p>
2926
2927                 <p>
2928                   The <var>upstream_version</var> may contain only
2929                   alphanumerics<footnote>
2930                         Alphanumerics are <tt>A-Za-z0-9</tt> only.
2931                   </footnote>
2932                   and the characters <tt>.</tt> <tt>+</tt> <tt>-</tt>
2933                   <tt>:</tt> <tt>~</tt> (full stop, plus, hyphen, colon,
2934                   tilde) and should start with a digit.  If there is no
2935                   <var>debian_revision</var> then hyphens are not allowed;
2936                   if there is no <var>epoch</var> then colons are not
2937                   allowed.
2938                 </p>
2939               </item>
2940
2941               <tag><var>debian_revision</var></tag>
2942               <item>
2943                 <p>
2944                   This part of the version number specifies the version of
2945                   the Debian package based on the upstream version.  It
2946                   may contain only alphanumerics and the characters
2947                   <tt>+</tt> <tt>.</tt> <tt>~</tt> (plus, full stop,
2948                   tilde) and is compared in the same way as the
2949                   <var>upstream_version</var> is.
2950                 </p>
2951
2952                 <p>
2953                   It is optional; if it isn't present then the
2954                   <var>upstream_version</var> may not contain a hyphen.
2955                   This format represents the case where a piece of
2956                   software was written specifically to be turned into a
2957                   Debian package, and so there is only one "debianisation"
2958                   of it and therefore no revision indication is required.
2959                 </p>
2960
2961                 <p>
2962                   It is conventional to restart the
2963                   <var>debian_revision</var> at <tt>1</tt> each time the
2964                   <var>upstream_version</var> is increased.
2965                 </p>
2966
2967                 <p>
2968                   The package management system will break the version
2969                   number apart at the last hyphen in the string (if there
2970                   is one) to determine the <var>upstream_version</var> and
2971                   <var>debian_revision</var>.  The absence of a
2972                   <var>debian_revision</var> is equivalent to a
2973                   <var>debian_revision</var> of <tt>0</tt>.
2974                 </p>
2975               </item>
2976             </taglist>
2977           </p>
2978
2979           <p>
2980             When comparing two version numbers, first the <var>epoch</var>
2981             of each are compared, then the <var>upstream_version</var> if
2982             <var>epoch</var> is equal, and then <var>debian_revision</var>
2983             if <var>upstream_version</var> is also equal.
2984             <var>epoch</var> is compared numerically.  The
2985             <var>upstream_version</var> and <var>debian_revision</var>
2986             parts are compared by the package management system using the
2987             following algorithm:
2988           </p>
2989
2990           <p>
2991             The strings are compared from left to right.
2992           </p>
2993
2994           <p>
2995             First the initial part of each string consisting entirely of
2996             non-digit characters is determined.  These two parts (one of
2997             which may be empty) are compared lexically.  If a difference
2998             is found it is returned.  The lexical comparison is a
2999             comparison of ASCII values modified so that all the letters
3000             sort earlier than all the non-letters and so that a tilde
3001             sorts before anything, even the end of a part.  For example,
3002             the following parts are in sorted order from earliest to
3003             latest: <tt>~~</tt>, <tt>~~a</tt>, <tt>~</tt>, the empty part,
3004             <tt>a</tt>.<footnote>
3005               One common use of <tt>~</tt> is for upstream pre-releases.
3006               For example, <tt>1.0~beta1~svn1245</tt> sorts earlier than
3007               <tt>1.0~beta1</tt>, which sorts earlier than <tt>1.0</tt>.
3008             </footnote>
3009           </p>
3010
3011           <p>
3012             Then the initial part of the remainder of each string which
3013             consists entirely of digit characters is determined.  The
3014             numerical values of these two parts are compared, and any
3015             difference found is returned as the result of the comparison.
3016             For these purposes an empty string (which can only occur at
3017             the end of one or both version strings being compared) counts
3018             as zero.
3019           </p>
3020
3021           <p>
3022             These two steps (comparing and removing initial non-digit
3023             strings and initial digit strings) are repeated until a
3024             difference is found or both strings are exhausted.
3025           </p>
3026
3027           <p>
3028             Note that the purpose of epochs is to allow us to leave behind
3029             mistakes in version numbering, and to cope with situations
3030             where the version numbering scheme changes.  It is
3031             <em>not</em> intended to cope with version numbers containing
3032             strings of letters which the package management system cannot
3033             interpret (such as <tt>ALPHA</tt> or <tt>pre-</tt>), or with
3034             silly orderings (the author of this manual has heard of a
3035             package whose versions went <tt>1.1</tt>, <tt>1.2</tt>,
3036             <tt>1.3</tt>, <tt>1</tt>, <tt>2.1</tt>, <tt>2.2</tt>,
3037             <tt>2</tt> and so forth).
3038           </p>
3039         </sect1>
3040
3041         <sect1 id="f-Description">
3042           <heading><tt>Description</tt></heading>
3043
3044           <p>
3045             In a source or binary control file, the <tt>Description</tt>
3046             field contains a description of the binary package, consisting
3047             of two parts, the synopsis or the short description, and the
3048             long description. The field's format is as follows:
3049           </p>
3050
3051           <p>
3052 <example>
3053         Description: &lt;single line synopsis&gt;
3054          &lt;extended description over several lines&gt;
3055 </example>
3056           </p>
3057
3058           <p>
3059             The lines in the extended description can have these formats:
3060           </p>
3061
3062           <p><list>
3063
3064             <item>
3065               Those starting with a single space are part of a paragraph.
3066               Successive lines of this form will be word-wrapped when
3067               displayed. The leading space will usually be stripped off.
3068             </item>
3069
3070             <item>
3071               Those starting with two or more spaces. These will be
3072               displayed verbatim. If the display cannot be panned
3073               horizontally, the displaying program will line wrap them "hard"
3074               (i.e., without taking account of word breaks). If it can they
3075               will be allowed to trail off to the right. None, one or two
3076               initial spaces may be deleted, but the number of spaces
3077               deleted from each line will be the same (so that you can have
3078               indenting work correctly, for example).
3079             </item>
3080
3081             <item>
3082               Those containing a single space followed by a single full stop
3083               character. These are rendered as blank lines. This is the
3084               <em>only</em> way to get a blank line<footnote>
3085                 Completely empty lines will not be rendered as blank lines.
3086                 Instead, they will cause the parser to think you're starting
3087                 a whole new record in the control file, and will therefore
3088                 likely abort with an error.
3089               </footnote>.
3090             </item>
3091
3092             <item>
3093               Those containing a space, a full stop and some more characters.
3094               These are for future expansion. Do not use them.
3095             </item>
3096
3097           </list></p>
3098
3099           <p>
3100             Do not use tab characters.  Their effect is not predictable.
3101           </p>
3102
3103           <p>
3104             See <ref id="descriptions"> for further information on this.
3105           </p>
3106
3107           <p>
3108             In a <file>.changes</file> file, the <tt>Description</tt>
3109             field contains a summary of the descriptions for the packages
3110             being uploaded.  For this case, the first line of the field
3111             value (the part on the same line as <tt>Description:</tt>) is
3112             always empty.  The content of the field is expressed as
3113             continuation lines, one line per package.  Each line is
3114             indented by one space and contains the name of a binary
3115             package, a space, a hyphen (<tt>-</tt>), a space, and the
3116             short description line from that package.
3117           </p>
3118         </sect1>
3119
3120         <sect1 id="f-Distribution">
3121           <heading><tt>Distribution</tt></heading>
3122
3123           <p>
3124             In a <file>.changes</file> file or parsed changelog output
3125             this contains the (space-separated) name(s) of the
3126             distribution(s) where this version of the package should
3127             be installed.  Valid distributions are determined by the
3128             archive maintainers.<footnote>
3129               Example distribution names in the Debian archive used in
3130               <file>.changes</file> files are:
3131                 <taglist compact="compact">
3132                   <tag><em>unstable</em></tag>
3133                   <item>
3134                     This distribution value refers to the
3135                     <em>developmental</em> part of the Debian distribution
3136                     tree.  Most new packages, new upstream versions of
3137                     packages and bug fixes go into the <em>unstable</em>
3138                     directory tree.
3139                   </item>
3140
3141                   <tag><em>experimental</em></tag>
3142                   <item>
3143                     The packages with this distribution value are deemed
3144                     by their maintainers to be high risk.  Oftentimes they
3145                     represent early beta or developmental packages from
3146                     various sources that the maintainers want people to
3147                     try, but are not ready to be a part of the other parts
3148                     of the Debian distribution tree.
3149                   </item>
3150                 </taglist>
3151
3152                 <p>
3153                   Others are used for updating stable releases or for
3154                   security uploads.  More information is available in the
3155                   Debian Developer's Reference, section "The Debian
3156                   archive".
3157                 </p>
3158             </footnote>
3159             The Debian archive software only supports listing a single
3160             distribution.  Migration of packages to other distributions is
3161             handled outside of the upload process.
3162           </p>
3163         </sect1>
3164
3165         <sect1 id="f-Date">
3166           <heading><tt>Date</tt></heading>
3167
3168           <p>
3169             This field includes the date the package was built or last edited.
3170           </p>
3171
3172           <p>
3173             The value of this field is usually extracted from the
3174             <file>debian/changelog</file> file - see
3175             <ref id="dpkgchangelog">).
3176           </p>
3177         </sect1>
3178
3179         <sect1 id="f-Format">
3180           <heading><tt>Format</tt></heading>
3181
3182           <p>
3183             This field specifies a format revision for the file.
3184             The most current format described in the Policy Manual
3185             is version <strong>1.5</strong>.  The syntax of the
3186             format value is the same as that of a package version
3187             number except that no epoch or Debian revision is allowed
3188             - see <ref id="f-Version">.
3189           </p>
3190         </sect1>
3191
3192         <sect1 id="f-Urgency">
3193           <heading><tt>Urgency</tt></heading>
3194
3195           <p>
3196             This is a description of how important it is to upgrade to
3197             this version from previous ones.  It consists of a single
3198             keyword taking one of the values <tt>low</tt>,
3199             <tt>medium</tt>, <tt>high</tt>, <tt>emergency</tt>, or
3200             <tt>critical</tt><footnote>
3201               Other urgency values are supported with configuration
3202               changes in the archive software but are not used in Debian.
3203               The urgency affects how quickly a package will be considered
3204               for inclusion into the <tt>testing</tt> distribution and
3205               gives an indication of the importance of any fixes included
3206               in the upload.  <tt>Emergency</tt> and <tt>critical</tt> are
3207               treated as synonymous.
3208             </footnote> (not case-sensitive) followed by an optional
3209             commentary (separated by a space) which is usually in
3210             parentheses.  For example:
3211
3212             <example>
3213   Urgency: low (HIGH for users of diversions)
3214             </example>
3215
3216           </p>
3217
3218           <p>
3219             The value of this field is usually extracted from the
3220             <file>debian/changelog</file> file - see
3221             <ref id="dpkgchangelog">.
3222           </p>
3223         </sect1>
3224
3225         <sect1 id="f-Changes">
3226           <heading><tt>Changes</tt></heading>
3227
3228           <p>
3229             This field contains the human-readable changes data, describing
3230             the differences between the last version and the current one.
3231           </p>
3232
3233           <p>
3234             The first line of the field value (the part on the same line
3235             as <tt>Changes:</tt>) is always empty.  The content of the
3236             field is expressed as continuation lines, with each line
3237             indented by at least one space.  Blank lines must be
3238             represented by a line consisting only of a space and a full
3239             stop (<tt>.</tt>).
3240           </p>
3241
3242           <p>
3243             The value of this field is usually extracted from the
3244             <file>debian/changelog</file> file - see
3245             <ref id="dpkgchangelog">).
3246           </p>
3247
3248           <p>
3249             Each version's change information should be preceded by a
3250             "title" line giving at least the version, distribution(s)
3251             and urgency, in a human-readable way.
3252           </p>
3253
3254           <p>
3255             If data from several versions is being returned the entry
3256             for the most recent version should be returned first, and
3257             entries should be separated by the representation of a
3258             blank line (the "title" line may also be followed by the
3259             representation of a blank line).
3260           </p>
3261         </sect1>
3262
3263         <sect1 id="f-Binary">
3264           <heading><tt>Binary</tt></heading>
3265
3266           <p>
3267             This field is a list of binary packages.  Its syntax and
3268             meaning varies depending on the control file in which it
3269             appears.
3270           </p>
3271
3272           <p>
3273             When it appears in the <file>.dsc</file> file, it lists binary
3274             packages which a source package can produce, separated by
3275             commas<footnote>
3276                 A space after each comma is conventional.
3277             </footnote>.  It may span multiple lines.  The source package
3278             does not necessarily produce all of these binary packages for
3279             every architecture.  The source control file doesn't contain
3280             details of which architectures are appropriate for which of
3281             the binary packages.
3282           </p>
3283
3284           <p>
3285             When it appears in a <file>.changes</file> file, it lists the
3286             names of the binary packages being uploaded, separated by
3287             whitespace (not commas).  It may span multiple lines.
3288           </p>
3289         </sect1>
3290
3291         <sect1 id="f-Installed-Size">
3292           <heading><tt>Installed-Size</tt></heading>
3293
3294           <p>
3295             This field appears in the control files of binary packages,
3296             and in the <file>Packages</file> files.  It gives an estimate
3297             of the total amount of disk space required to install the
3298             named package.  Actual installed size may vary based on block
3299             size, file system properties, or actions taken by package
3300             maintainer scripts.
3301           </p>
3302
3303           <p>
3304             The disk space is given as the integer value of the estimated
3305             installed size in bytes, divided by 1024 and rounded up.
3306           </p>
3307         </sect1>
3308
3309         <sect1 id="f-Files">
3310           <heading><tt>Files</tt></heading>
3311
3312           <p>
3313             This field contains a list of files with information about
3314             each one.  The exact information and syntax varies with
3315             the context.
3316           </p>
3317
3318           <p>
3319             In all cases, Files is a multiline field.  The first line of
3320             the field value (the part on the same line as <tt>Files:</tt>)
3321             is always empty.  The content of the field is expressed as
3322             continuation lines, one line per file.  Each line must be
3323             indented by one space and contain a number of sub-fields,
3324             separated by spaces, as described below.
3325           </p>
3326
3327           <p>
3328             In the <file>.dsc</file> file, each line contains the MD5
3329             checksum, size and filename of the tar file and (if
3330             applicable) diff file which make up the remainder of the
3331             source package<footnote>
3332               That is, the parts which are not the <tt>.dsc</tt>.
3333             </footnote>.  For example:
3334             <example>
3335 Files:
3336  c6f698f19f2a2aa07dbb9bbda90a2754 571925 example_1.2.orig.tar.gz
3337  938512f08422f3509ff36f125f5873ba 6220 example_1.2-1.diff.gz
3338             </example>
3339             The exact forms of the filenames are described
3340             in <ref id="pkg-sourcearchives">.
3341           </p>
3342
3343           <p>
3344             In the <file>.changes</file> file this contains one line per
3345             file being uploaded.  Each line contains the MD5 checksum,
3346             size, section and priority and the filename.  For example:
3347             <example>
3348 Files:
3349  4c31ab7bfc40d3cf49d7811987390357 1428 text extra example_1.2-1.dsc
3350  c6f698f19f2a2aa07dbb9bbda90a2754 571925 text extra example_1.2.orig.tar.gz
3351  938512f08422f3509ff36f125f5873ba 6220 text extra example_1.2-1.diff.gz
3352  7c98fe853b3bbb47a00e5cd129b6cb56 703542 text extra example_1.2-1_i386.deb
3353             </example>
3354             The <qref id="f-Section">section</qref>
3355             and <qref id="f-Priority">priority</qref> are the values of
3356             the corresponding fields in the main source control file.  If
3357             no section or priority is specified then <tt>-</tt> should be
3358             used, though section and priority values must be specified for
3359             new packages to be installed properly.
3360           </p>
3361
3362           <p>
3363             The special value <tt>byhand</tt> for the section in a
3364             <tt>.changes</tt> file indicates that the file in question
3365             is not an ordinary package file and must by installed by
3366             hand by the distribution maintainers.  If the section is
3367             <tt>byhand</tt> the priority should be <tt>-</tt>.
3368           </p>
3369
3370           <p>
3371             If a new Debian revision of a package is being shipped and
3372             no new original source archive is being distributed the
3373             <tt>.dsc</tt> must still contain the <tt>Files</tt> field
3374             entry for the original source archive
3375             <file><var>package</var>_<var>upstream-version</var>.orig.tar.gz</file>,
3376             but the <file>.changes</file> file should leave it out.  In
3377             this case the original source archive on the distribution
3378             site must match exactly, byte-for-byte, the original
3379             source archive which was used to generate the
3380             <file>.dsc</file> file and diff which are being uploaded.</p>
3381         </sect1>
3382
3383         <sect1 id="f-Closes">
3384           <heading><tt>Closes</tt></heading>
3385
3386           <p>
3387             A space-separated list of bug report numbers that the upload
3388             governed by the .changes file closes.
3389           </p>
3390         </sect1>
3391
3392         <sect1 id="f-Homepage">
3393           <heading><tt>Homepage</tt></heading>
3394
3395           <p>
3396             The URL of the web site for this package, preferably (when
3397             applicable) the site from which the original source can be
3398             obtained and any additional upstream documentation or
3399             information may be found.  The content of this field is a
3400             simple URL without any surrounding characters such as
3401             <tt>&lt;&gt;</tt>.
3402           </p>
3403         </sect1>
3404
3405       </sect>
3406
3407       <sect>
3408         <heading>User-defined fields</heading>
3409
3410         <p>
3411           Additional user-defined fields may be added to the
3412           source package control file.  Such fields will be
3413           ignored, and not copied to (for example) binary or
3414           source package control files or upload control files.
3415         </p>
3416
3417         <p>
3418           If you wish to add additional unsupported fields to
3419           these output files you should use the mechanism
3420           described here.
3421         </p>
3422
3423         <p>
3424           Fields in the main source control information file with
3425           names starting <tt>X</tt>, followed by one or more of
3426           the letters <tt>BCS</tt> and a hyphen <tt>-</tt>, will
3427           be copied to the output files.  Only the part of the
3428           field name after the hyphen will be used in the output
3429           file.  Where the letter <tt>B</tt> is used the field
3430           will appear in binary package control files, where the
3431           letter <tt>S</tt> is used in source package control
3432           files and where <tt>C</tt> is used in upload control
3433           (<tt>.changes</tt>) files.
3434         </p>
3435
3436         <p>
3437           For example, if the main source information control file
3438           contains the field
3439           <example>
3440   XBS-Comment: I stand between the candle and the star.
3441           </example>
3442           then the binary and source package control files will contain the
3443           field
3444           <example>
3445   Comment: I stand between the candle and the star.
3446           </example>
3447         </p>
3448
3449       </sect>
3450
3451     </chapt>
3452
3453
3454     <chapt id="maintainerscripts">
3455       <heading>Package maintainer scripts and installation procedure</heading>
3456
3457       <sect>
3458         <heading>Introduction to package maintainer scripts</heading>
3459
3460         <p>
3461           It is possible to supply scripts as part of a package which
3462           the package management system will run for you when your
3463           package is installed, upgraded or removed.
3464         </p>
3465
3466         <p>
3467           These scripts are the files <prgn>preinst</prgn>,
3468           <prgn>postinst</prgn>, <prgn>prerm</prgn> and
3469           <prgn>postrm</prgn> in the control area of the package.
3470           They must be proper executable files; if they are scripts
3471           (which is recommended), they must start with the usual
3472           <tt>#!</tt> convention.  They should be readable and
3473           executable by anyone, and must not be world-writable.
3474         </p>
3475
3476         <p>
3477           The package management system looks at the exit status from
3478           these scripts.  It is important that they exit with a
3479           non-zero status if there is an error, so that the package
3480           management system can stop its processing.  For shell
3481           scripts this means that you <em>almost always</em> need to
3482           use <tt>set -e</tt> (this is usually true when writing shell
3483           scripts, in fact).  It is also important, of course, that
3484           they exit with a zero status if everything went well.
3485         </p>
3486
3487         <p>
3488           Additionally, packages interacting with users using
3489           <tt>debconf</tt> in the <prgn>postinst</prgn> script should
3490           install a <prgn>config</prgn> script  in the control area,
3491           see <ref id="maintscriptprompt"> for details.
3492         </p>
3493
3494         <p>
3495           When a package is upgraded a combination of the scripts from
3496           the old and new packages is called during the upgrade
3497           procedure.  If your scripts are going to be at all
3498           complicated you need to be aware of this, and may need to
3499           check the arguments to your scripts.
3500         </p>
3501
3502         <p>
3503           Broadly speaking the <prgn>preinst</prgn> is called before
3504           (a particular version of) a package is unpacked, and the
3505           <prgn>postinst</prgn> afterwards; the <prgn>prerm</prgn>
3506           before (a version of) a package is removed and the
3507           <prgn>postrm</prgn> afterwards.
3508         </p>
3509
3510         <p>
3511           Programs called from maintainer scripts should not normally
3512           have a path prepended to them. Before installation is
3513           started, the package management system checks to see if the
3514           programs <prgn>ldconfig</prgn>,
3515           <prgn>start-stop-daemon</prgn>, <prgn>install-info</prgn>,
3516           and <prgn>update-rc.d</prgn> can be found via the
3517           <tt>PATH</tt> environment variable. Those programs, and any
3518           other program that one would expect to be in the
3519           <tt>PATH</tt>, should thus be invoked without an absolute
3520           pathname. Maintainer scripts should also not reset the
3521           <tt>PATH</tt>, though they might choose to modify it by
3522           prepending or appending package-specific directories. These
3523           considerations really apply to all shell scripts.</p>
3524       </sect>
3525
3526       <sect id="idempotency">
3527         <heading>Maintainer scripts idempotency</heading>
3528
3529         <p>
3530           It is necessary for the error recovery procedures that the
3531           scripts be idempotent.  This means that if it is run
3532           successfully, and then it is called again, it doesn't bomb
3533           out or cause any harm, but just ensures that everything is
3534           the way it ought to be.  If the first call failed, or
3535           aborted half way through for some reason, the second call
3536           should merely do the things that were left undone the first
3537           time, if any, and exit with a success status if everything
3538           is OK.<footnote>
3539               This is so that if an error occurs, the user interrupts
3540               <prgn>dpkg</prgn> or some other unforeseen circumstance
3541               happens you don't leave the user with a badly-broken
3542               package when <prgn>dpkg</prgn> attempts to repeat the
3543               action.
3544           </footnote>
3545         </p>
3546       </sect>
3547
3548       <sect id="controllingterminal">
3549         <heading>Controlling terminal for maintainer scripts</heading>
3550
3551         <p>
3552           The maintainer scripts are guaranteed to run with a
3553           controlling terminal and can interact with the user.
3554           Because these scripts may be executed with standard output
3555           redirected into a pipe for logging purposes, Perl scripts
3556           should set unbuffered output by setting <tt>$|=1</tt> so
3557           that the output is printed immediately rather than being
3558           buffered.
3559         </p>
3560       </sect>
3561       <sect id="exitstatus">
3562         <heading>Exit status</heading>
3563
3564         <p>
3565           Each script must return a zero exit status for
3566           success, or a nonzero one for failure, since the package
3567           management system looks for the exit status of these scripts
3568           and determines what action to take next based on that datum.
3569         </p>
3570       </sect>
3571
3572       <sect id="mscriptsinstact"><heading>Summary of ways maintainer
3573           scripts are called
3574         </heading>
3575
3576         <p>
3577           <list compact="compact">
3578             <item>
3579               <var>new-preinst</var> <tt>install</tt>
3580             </item>
3581             <item>
3582               <var>new-preinst</var> <tt>install</tt> <var>old-version</var>
3583             </item>
3584             <item>
3585                 <var>new-preinst</var> <tt>upgrade</tt> <var>old-version</var>
3586             </item>
3587             <item>
3588                 <var>old-preinst</var> <tt>abort-upgrade</tt>
3589                 <var>new-version</var>
3590             </item>
3591           </list>
3592
3593         <p>
3594           <list compact="compact">
3595             <item>
3596                 <var>postinst</var> <tt>configure</tt>
3597                 <var>most-recently-configured-version</var>
3598             </item>
3599             <item>
3600                 <var>old-postinst</var> <tt>abort-upgrade</tt>
3601                 <var>new-version</var>
3602             </item>
3603             <item>
3604                 <var>conflictor's-postinst</var> <tt>abort-remove</tt>
3605                 <tt>in-favour</tt> <var>package</var>
3606                 <var>new-version</var>
3607             </item>
3608             <item>
3609                 <var>postinst</var> <tt>abort-remove</tt>
3610             </item>
3611             <item>
3612                 <var>deconfigured's-postinst</var>
3613                 <tt>abort-deconfigure</tt> <tt>in-favour</tt>
3614                 <var>failed-install-package</var> <var>version</var>
3615                 [<tt>removing</tt> <var>conflicting-package</var>
3616                 <var>version</var>]
3617             </item>
3618           </list>
3619
3620         <p>
3621           <list compact="compact">
3622             <item>
3623                 <var>prerm</var> <tt>remove</tt>
3624             </item>
3625             <item>
3626                 <var>old-prerm</var> <tt>upgrade</tt>
3627                 <var>new-version</var>
3628             </item>
3629             <item>
3630                 <var>new-prerm</var> <tt>failed-upgrade</tt>
3631                 <var>old-version</var>
3632             </item>
3633             <item>
3634                 <var>conflictor's-prerm</var> <tt>remove</tt>
3635                 <tt>in-favour</tt> <var>package</var>
3636                 <var>new-version</var>
3637             </item>
3638             <item>
3639                 <var>deconfigured's-prerm</var> <tt>deconfigure</tt>
3640                 <tt>in-favour</tt> <var>package-being-installed</var>
3641                 <var>version</var> [<tt>removing</tt>
3642                 <var>conflicting-package</var>
3643                 <var>version</var>]
3644             </item>
3645           </list>
3646
3647         <p>
3648           <list compact="compact">
3649             <item>
3650                 <var>postrm</var> <tt>remove</tt>
3651             </item>
3652             <item>
3653                 <var>postrm</var> <tt>purge</tt>
3654             </item>
3655             <item>
3656                 <var>old-postrm</var> <tt>upgrade</tt>
3657                 <var>new-version</var>
3658             </item>
3659             <item>
3660                 <var>new-postrm</var> <tt>failed-upgrade</tt>
3661                 <var>old-version</var>
3662             </item>
3663             <item>
3664                 <var>new-postrm</var> <tt>abort-install</tt>
3665             </item>
3666             <item>
3667                 <var>new-postrm</var> <tt>abort-install</tt>
3668                 <var>old-version</var>
3669             </item>
3670             <item>
3671                 <var>new-postrm</var> <tt>abort-upgrade</tt>
3672                 <var>old-version</var>
3673             </item>
3674             <item>
3675                 <var>disappearer's-postrm</var> <tt>disappear</tt>
3676                 <var>overwriter</var>
3677                 <var>overwriter-version</var>
3678             </item>
3679           </list>
3680         </p>
3681
3682
3683       <sect id="unpackphase">
3684         <heading>Details of unpack phase of installation or upgrade</heading>
3685
3686         <p>
3687           The procedure on installation/upgrade/overwrite/disappear
3688           (i.e., when running <tt>dpkg --unpack</tt>, or the unpack
3689           stage of <tt>dpkg --install</tt>) is as follows.  In each
3690           case, if a major error occurs (unless listed below) the
3691           actions are, in general, run backwards - this means that the
3692           maintainer scripts are run with different arguments in
3693           reverse order.  These are the "error unwind" calls listed
3694           below.
3695
3696           <enumlist>
3697             <item>
3698                 <enumlist>
3699                   <item>
3700                       If a version of the package is already installed, call
3701                       <example compact="compact">
3702 <var>old-prerm</var> upgrade <var>new-version</var>
3703                       </example>
3704                   </item>
3705                   <item>
3706                       If the script runs but exits with a non-zero
3707                       exit status, <prgn>dpkg</prgn> will attempt:
3708                       <example compact="compact">
3709 <var>new-prerm</var> failed-upgrade <var>old-version</var>
3710                       </example>
3711                       If this works, the upgrade continues. If this
3712                       does not work, the error unwind:
3713                       <example compact="compact">
3714 <var>old-postinst</var> abort-upgrade <var>new-version</var>
3715                       </example>
3716                       If this works, then the old-version is
3717                       "Installed", if not, the old version is in a
3718                       "Half-Configured" state.
3719                   </item>
3720                 </enumlist>
3721             </item>
3722
3723             <item>
3724                 If a "conflicting" package is being removed at the same time,
3725                 or if any package will be broken (due to <tt>Breaks</tt>):
3726                 <enumlist>
3727                   <item>
3728                       If <tt>--auto-deconfigure</tt> is
3729                       specified, call, for each package to be deconfigured
3730                       due to <tt>Breaks</tt>:
3731                       <example compact="compact">
3732 <var>deconfigured's-prerm</var> deconfigure \
3733   in-favour <var>package-being-installed</var> <var>version</var>
3734                       </example>
3735                       Error unwind:
3736                       <example compact="compact">
3737 <var>deconfigured's-postinst</var> abort-deconfigure \
3738   in-favour <var>package-being-installed-but-failed</var> <var>version</var>
3739                       </example>
3740                       The deconfigured packages are marked as
3741                       requiring configuration, so that if
3742                       <tt>--install</tt> is used they will be
3743                       configured again if possible.
3744                   </item>
3745                   <item>
3746                       If any packages depended on a conflicting
3747                       package being removed and <tt>--auto-deconfigure</tt> is
3748                       specified, call, for each such package:
3749                       <example compact="compact">
3750 <var>deconfigured's-prerm</var> deconfigure \
3751   in-favour <var>package-being-installed</var> <var>version</var> \
3752     removing <var>conflicting-package</var> <var>version</var>
3753                       </example>
3754                       Error unwind:
3755                       <example compact="compact">
3756 <var>deconfigured's-postinst</var> abort-deconfigure \
3757   in-favour <var>package-being-installed-but-failed</var> <var>version</var> \
3758     removing <var>conflicting-package</var> <var>version</var>
3759                       </example>
3760                       The deconfigured packages are marked as
3761                       requiring configuration, so that if
3762                       <tt>--install</tt> is used they will be
3763                       configured again if possible.
3764                   </item>
3765                   <item>
3766                       To prepare for removal of each conflicting package, call:
3767                       <example compact="compact">
3768 <var>conflictor's-prerm</var> remove \
3769   in-favour <var>package</var> <var>new-version</var>
3770                       </example>
3771                       Error unwind:
3772                       <example compact="compact">
3773 <var>conflictor's-postinst</var> abort-remove \
3774   in-favour <var>package</var> <var>new-version</var>
3775                       </example>
3776                   </item>
3777                 </enumlist>
3778             </item>
3779
3780             <item>
3781                 <enumlist>
3782                   <item>
3783                       If the package is being upgraded, call:
3784                       <example compact="compact">
3785 <var>new-preinst</var> upgrade <var>old-version</var>
3786                       </example>
3787                       If this fails, we call:
3788                       <example>
3789 <var>new-postrm</var> abort-upgrade <var>old-version</var>
3790                       </example>
3791                       <enumlist>
3792                         <item>
3793                           <p>
3794                             If that works, then
3795                             <example>
3796 <var>old-postinst</var> abort-upgrade <var>new-version</var>
3797                             </example>
3798                             is called. If this works, then the old version
3799                             is in an "Installed" state, or else it is left
3800                             in an "Unpacked" state.
3801                           </p>
3802                         </item>
3803                         <item>
3804                           <p>
3805                             If it fails, then the old version is left
3806                             in an "Half-Installed" state.
3807                           </p>
3808                         </item>
3809                       </enumlist>
3810                       
3811                   </item>
3812                   <item>
3813                       Otherwise, if the package had some configuration
3814                       files from a previous version installed (i.e., it
3815                       is in the "configuration files only" state):
3816                       <example compact="compact">
3817 <var>new-preinst</var> install <var>old-version</var>
3818                       </example>
3819                       Error unwind:
3820                       <example>
3821 <var>new-postrm</var> abort-install <var>old-version</var>
3822                       </example>
3823                       If this fails, the package is left in a
3824                       "Half-Installed" state, which requires a
3825                       reinstall. If it works, the packages is left in
3826                       a "Config-Files" state.
3827                   </item>
3828                   <item>
3829                       Otherwise (i.e., the package was completely purged):
3830                       <example compact="compact">
3831 <var>new-preinst</var> install
3832                       </example>
3833                       Error unwind:
3834                       <example compact="compact">
3835 <var>new-postrm</var> abort-install
3836                       </example>
3837                       If the error-unwind fails, the package is in a
3838                       "Half-Installed" phase, and requires a
3839                       reinstall. If the error unwind works, the
3840                       package is in a not installed state.
3841                   </item>
3842                 </enumlist>
3843             </item>
3844
3845             <item>
3846               <p>
3847                 The new package's files are unpacked, overwriting any
3848                 that may be on the system already, for example any
3849                 from the old version of the same package or from
3850                 another package.  Backups of the old files are kept
3851                 temporarily, and if anything goes wrong the package
3852                 management system will attempt to put them back as
3853                 part of the error unwind.
3854               </p>
3855
3856               <p>
3857                 It is an error for a package to contain files which
3858                 are on the system in another package, unless
3859                 <tt>Replaces</tt> is used (see <ref id="replaces">).
3860                 <!--
3861                 The following paragraph is not currently the case:
3862                 Currently the <tt>- - force-overwrite</tt> flag is
3863                 enabled, downgrading it to a warning, but this may not
3864                 always be the case.
3865                 -->
3866               </p>
3867
3868               <p>
3869                 It is a more serious error for a package to contain a
3870                 plain file or other kind of non-directory where another
3871                 package has a directory (again, unless
3872                 <tt>Replaces</tt> is used).  This error can be
3873                 overridden if desired using
3874                 <tt>--force-overwrite-dir</tt>, but this is not
3875                 advisable.
3876               </p>
3877
3878               <p>
3879                 Packages which overwrite each other's files produce
3880                 behavior which, though deterministic, is hard for the
3881                 system administrator to understand.  It can easily
3882                 lead to "missing" programs if, for example, a package
3883                 is unpacked which overwrites a file from another
3884                 package, and is then removed again.<footnote>
3885                     Part of the problem is due to what is arguably a
3886                     bug in <prgn>dpkg</prgn>.
3887                 </footnote>
3888               </p>
3889
3890               <p>
3891                 A directory will never be replaced by a symbolic link
3892                 to a directory or vice versa; instead, the existing
3893                 state (symlink or not) will be left alone and
3894                 <prgn>dpkg</prgn> will follow the symlink if there is
3895                 one.
3896               </p>
3897             </item>
3898
3899             <item>
3900               <p>
3901                 <enumlist>
3902                   <item>
3903                       If the package is being upgraded, call
3904                       <example compact="compact">
3905 <var>old-postrm</var> upgrade <var>new-version</var>
3906                       </example>
3907                   </item>
3908                   <item>
3909                       If this fails, <prgn>dpkg</prgn> will attempt:
3910                       <example compact="compact">
3911 <var>new-postrm</var> failed-upgrade <var>old-version</var>
3912                       </example>
3913                       If this works, installation continues. If not, 
3914                       Error unwind:
3915                       <example compact="compact">
3916 <var>old-preinst</var> abort-upgrade <var>new-version</var>
3917                       </example>
3918                       If this fails, the old version is left in a
3919                       "Half-Installed" state. If it works, dpkg now
3920                       calls:
3921                       <example compact="compact">
3922 <var>new-postrm</var> abort-upgrade <var>old-version</var>
3923                       </example>
3924                       If this fails, the old version is left in a
3925                       "Half-Installed" state. If it works, dpkg now
3926                       calls:
3927                       <example compact="compact">
3928 <var>old-postinst</var> abort-upgrade <var>new-version</var>
3929                       </example>
3930                       If this fails, the old version is in an
3931                       "Unpacked" state.
3932                   </item>
3933                 </enumlist>
3934               </p>
3935
3936               <p>
3937                 This is the point of no return - if
3938                 <prgn>dpkg</prgn> gets this far, it won't back off
3939                 past this point if an error occurs.  This will
3940                 leave the package in a fairly bad state, which
3941                 will require a successful re-installation to clear
3942                 up, but it's when <prgn>dpkg</prgn> starts doing
3943                 things that are irreversible.
3944               </p>
3945             </item>
3946
3947             <item>
3948                 Any files which were in the old version of the package
3949                 but not in the new are removed.
3950             </item>
3951
3952             <item>
3953                 The new file list replaces the old.
3954             </item>
3955
3956             <item>
3957                 The new maintainer scripts replace the old.
3958             </item>
3959
3960             <item>
3961                 Any packages all of whose files have been overwritten
3962                 during the installation, and which aren't required for
3963                 dependencies, are considered to have been removed.
3964                 For each such package
3965                 <enumlist>
3966                   <item>
3967                       <prgn>dpkg</prgn> calls:
3968                       <example compact="compact">
3969 <var>disappearer's-postrm</var> disappear \
3970   <var>overwriter</var> <var>overwriter-version</var>
3971                       </example>
3972                   </item>
3973                   <item>
3974                       The package's maintainer scripts are removed.
3975                   </item>
3976                   <item>
3977                       It is noted in the status database as being in a
3978                       sane state, namely not installed (any conffiles
3979                       it may have are ignored, rather than being
3980                       removed by <prgn>dpkg</prgn>).  Note that
3981                       disappearing packages do not have their prerm
3982                       called, because <prgn>dpkg</prgn> doesn't know
3983                       in advance that the package is going to
3984                       vanish.
3985                   </item>
3986                 </enumlist>
3987             </item>
3988
3989             <item>
3990                 Any files in the package we're unpacking that are also
3991                 listed in the file lists of other packages are removed
3992                 from those lists.  (This will lobotomize the file list
3993                 of the "conflicting" package if there is one.)
3994             </item>
3995
3996             <item>
3997                 The backup files made during installation, above, are
3998                 deleted.
3999             </item>
4000
4001             <item>
4002               <p>
4003                 The new package's status is now sane, and recorded as
4004                 "unpacked".
4005               </p>
4006
4007               <p>
4008                 Here is another point of no return - if the
4009                 conflicting package's removal fails we do not unwind
4010                 the rest of the installation; the conflicting package
4011                 is left in a half-removed limbo.
4012               </p>
4013             </item>
4014
4015             <item>
4016                 If there was a conflicting package we go and do the
4017                 removal actions (described below), starting with the
4018                 removal of the conflicting package's files (any that
4019                 are also in the package being unpacked have already
4020                 been removed from the conflicting package's file list,
4021                 and so do not get removed now).
4022             </item>
4023           </enumlist>
4024         </p>
4025       </sect>
4026
4027       <sect id="configdetails"><heading>Details of configuration</heading>
4028
4029         <p>
4030           When we configure a package (this happens with <tt>dpkg
4031             --install</tt> and <tt>dpkg --configure</tt>), we first
4032           update any <tt>conffile</tt>s and then call:
4033           <example compact="compact">
4034 <var>postinst</var> configure <var>most-recently-configured-version</var>
4035           </example>
4036         </p>
4037
4038         <p>
4039           No attempt is made to unwind after errors during
4040           configuration. If the configuration fails, the package is in
4041           a "Failed Config" state, and an error message is generated.
4042         </p>
4043
4044         <p>
4045           If there is no most recently configured version
4046           <prgn>dpkg</prgn> will pass a null argument.
4047           <footnote>
4048             <p>
4049               Historical note: Truly ancient (pre-1997) versions of
4050               <prgn>dpkg</prgn> passed <tt>&lt;unknown&gt;</tt>
4051               (including the angle brackets) in this case.  Even older
4052               ones did not pass a second argument at all, under any
4053               circumstance.  Note that upgrades using such an old dpkg
4054               version are unlikely to work for other reasons, even if
4055               this old argument behavior is handled by your postinst script.
4056             </p>
4057           </footnote>     
4058         </p>
4059       </sect>
4060
4061       <sect id="removedetails"><heading>Details of removal and/or
4062       configuration purging</heading>
4063
4064         <p>
4065           <enumlist>
4066             <item>
4067               <p>
4068                 <example compact="compact">
4069 <var>prerm</var> remove
4070                 </example>
4071               </p>
4072               <p>
4073                 If prerm fails during replacement due to conflict
4074                 <example>
4075 <var>conflictor's-postinst</var> abort-remove \
4076   in-favour <var>package</var> <var>new-version</var>
4077                 </example>
4078                 Or else we call:
4079                 <example>
4080 <var>postinst</var> abort-remove
4081                 </example>
4082               </p>
4083               <p>
4084                 If this fails, the package is in a "Half-Configured"
4085                 state, or else it remains "Installed".
4086               </p>
4087             </item>
4088             <item>
4089                 The package's files are removed (except <tt>conffile</tt>s).
4090             </item>
4091             <item>
4092                 <example compact="compact">
4093 <var>postrm</var> remove
4094                 </example>
4095
4096               <p>
4097                 If it fails, there's no error unwind, and the package is in
4098                 an "Half-Installed" state.
4099               </p>
4100             </item>
4101             <item>
4102               <p>
4103                 All the maintainer scripts except the <prgn>postrm</prgn>
4104                 are removed.
4105               </p>
4106
4107               <p>
4108                 If we aren't purging the package we stop here.  Note
4109                 that packages which have no <prgn>postrm</prgn> and no
4110                 <tt>conffile</tt>s are automatically purged when
4111                 removed, as there is no difference except for the
4112                 <prgn>dpkg</prgn> status.
4113               </p>
4114             </item>
4115             <item>
4116                 The <tt>conffile</tt>s and any backup files
4117                 (<tt>~</tt>-files, <tt>#*#</tt> files,
4118                 <tt>%</tt>-files, <tt>.dpkg-{old,new,tmp}</tt>, etc.)
4119                 are removed.
4120             </item>
4121             <item>
4122               <p>
4123                 <example compact="compact">
4124 <var>postrm</var> purge
4125                 </example>
4126               </p>
4127               <p>
4128                 If this fails, the package remains in a "Config-Files"
4129                 state.
4130               </p>
4131             </item>
4132             <item>
4133                 The package's file list is removed.
4134             </item>
4135           </enumlist>
4136
4137         </p>
4138       </sect>
4139     </chapt>
4140
4141
4142     <chapt id="relationships">
4143       <heading>Declaring relationships between packages</heading>
4144
4145       <sect id="depsyntax">
4146         <heading>Syntax of relationship fields</heading>
4147
4148         <p>
4149           These fields all have a uniform syntax.  They are a list of
4150           package names separated by commas.
4151         </p>
4152
4153         <p>
4154           In the <tt>Depends</tt>, <tt>Recommends</tt>,
4155           <tt>Suggests</tt>, <tt>Pre-Depends</tt>,
4156           <tt>Build-Depends</tt> and <tt>Build-Depends-Indep</tt>
4157           control file fields of the package, which declare
4158           dependencies on other packages, the package names listed may
4159           also include lists of alternative package names, separated
4160           by vertical bar (pipe) symbols <tt>|</tt>.  In such a case,
4161           if any one of the alternative packages is installed, that
4162           part of the dependency is considered to be satisfied.
4163         </p>
4164
4165         <p>
4166           All of the fields except for <tt>Provides</tt> may restrict
4167           their applicability to particular versions of each named
4168           package.  This is done in parentheses after each individual
4169           package name; the parentheses should contain a relation from
4170           the list below followed by a version number, in the format
4171           described in <ref id="f-Version">.
4172         </p>
4173
4174         <p>
4175           The relations allowed are <tt>&lt;&lt;</tt>, <tt>&lt;=</tt>,
4176           <tt>=</tt>, <tt>&gt;=</tt> and <tt>&gt;&gt;</tt> for
4177           strictly earlier, earlier or equal, exactly equal, later or
4178           equal and strictly later, respectively.  The deprecated
4179           forms <tt>&lt;</tt> and <tt>&gt;</tt> were used to mean
4180           earlier/later or equal, rather than strictly earlier/later,
4181           so they should not appear in new packages (though
4182           <prgn>dpkg</prgn> still supports them).
4183         </p>
4184
4185         <p>
4186           Whitespace may appear at any point in the version
4187           specification subject to the rules in <ref
4188           id="controlsyntax">, and must appear where it's necessary to
4189           disambiguate; it is not otherwise significant.  All of the
4190           relationship fields may span multiple lines.  For
4191           consistency and in case of future changes to
4192           <prgn>dpkg</prgn> it is recommended that a single space be
4193           used after a version relationship and before a version
4194           number; it is also conventional to put a single space after
4195           each comma, on either side of each vertical bar, and before
4196           each open parenthesis.  When wrapping a relationship field, it
4197           is conventional to do so after a comma and before the space
4198           following that comma.
4199         </p>
4200
4201         <p>
4202           For example, a list of dependencies might appear as:
4203           <example compact="compact">
4204 Package: mutt
4205 Version: 1.3.17-1
4206 Depends: libc6 (>= 2.2.1), exim | mail-transport-agent
4207           </example>
4208         </p>
4209
4210         <p>
4211           All fields that specify build-time relationships
4212           (<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
4213           <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>)
4214           may be restricted to a certain set of architectures.  This
4215           is indicated in brackets after each individual package name and
4216           the optional version specification.  The brackets enclose a
4217           list of Debian architecture names separated by whitespace.
4218           Exclamation marks may be prepended to each of the names.
4219           (It is not permitted for some names to be prepended with
4220           exclamation marks while others aren't.) If the current Debian
4221           host architecture is not in this list and there are no
4222           exclamation marks in the list, or it is in the list with a
4223           prepended exclamation mark, the package name and the
4224           associated version specification are ignored completely for
4225           the purposes of defining the relationships.
4226         </p>
4227
4228         <p>
4229           For example:
4230           <example compact="compact">
4231 Source: glibc
4232 Build-Depends-Indep: texinfo
4233 Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
4234   hurd-dev [hurd-i386], gnumach-dev [hurd-i386]
4235           </example>
4236           requires <tt>kernel-headers-2.2.10</tt> on all architectures
4237           other than hurd-i386 and requires <tt>hurd-dev</tt> and
4238           <tt>gnumach-dev</tt> only on hurd-i386.
4239         </p>
4240
4241         <p>
4242           If the architecture-restricted dependency is part of a set of
4243           alternatives using <tt>|</tt>, that alternative is ignored
4244           completely on architectures that do not match the restriction.
4245           For example:
4246           <example compact="compact">
4247 Build-Depends: foo [!i386] | bar [!amd64]
4248           </example>
4249           is equivalent to <tt>bar</tt> on the i386 architecture, to
4250           <tt>foo</tt> on the amd64 architecture, and to <tt>foo |
4251           bar</tt> on all other architectures.
4252         </p>
4253
4254         <p>
4255           Note that the binary package relationship fields such as
4256           <tt>Depends</tt> appear in one of the binary package
4257           sections of the control file, whereas the build-time
4258           relationships such as <tt>Build-Depends</tt> appear in the
4259           source package section of the control file (which is the
4260           first section).
4261         </p>
4262       </sect>
4263
4264       <sect id="binarydeps">
4265         <heading>Binary Dependencies - <tt>Depends</tt>,
4266           <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
4267           <tt>Pre-Depends</tt>
4268         </heading>
4269
4270         <p>
4271           Packages can declare in their control file that they have
4272           certain relationships to other packages - for example, that
4273           they may not be installed at the same time as certain other
4274           packages, and/or that they depend on the presence of others.
4275         </p>
4276
4277         <p>
4278           This is done using the <tt>Depends</tt>, <tt>Pre-Depends</tt>,
4279           <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
4280           <tt>Breaks</tt> and <tt>Conflicts</tt> control file fields.
4281           <tt>Breaks</tt> is described in <ref id="breaks">, and
4282           <tt>Conflicts</tt> is described in <ref id="conflicts">.  The
4283           rest are described below.
4284         </p>
4285
4286         <p>
4287           These seven fields are used to declare a dependency
4288           relationship by one package on another.  Except for
4289           <tt>Enhances</tt> and <tt>Breaks</tt>, they appear in the
4290           depending (binary) package's control file.
4291           (<tt>Enhances</tt> appears in the recommending package's
4292           control file, and <tt>Breaks</tt> appears in the version of
4293           depended-on package which causes the named package to
4294           break).
4295         </p>
4296
4297         <p>
4298           A <tt>Depends</tt> field takes effect <em>only</em> when a
4299           package is to be configured.  It does not prevent a package
4300           being on the system in an unconfigured state while its
4301           dependencies are unsatisfied, and it is possible to replace
4302           a package whose dependencies are satisfied and which is
4303           properly installed with a different version whose
4304           dependencies are not and cannot be satisfied; when this is
4305           done the depending package will be left unconfigured (since
4306           attempts to configure it will give errors) and will not
4307           function properly.  If it is necessary, a
4308           <tt>Pre-Depends</tt> field can be used, which has a partial
4309           effect even when a package is being unpacked, as explained
4310           in detail below.  (The other three dependency fields,
4311           <tt>Recommends</tt>, <tt>Suggests</tt> and
4312           <tt>Enhances</tt>, are only used by the various front-ends
4313           to <prgn>dpkg</prgn> such as <prgn>apt-get</prgn>,
4314           <prgn>aptitude</prgn>, and <prgn>dselect</prgn>.)
4315         </p>
4316
4317         <p>
4318           Since <tt>Depends</tt> only places requirements on the
4319           configuration step, packages in an installation run are usually
4320           all unpacked first and all configured later.  This makes it
4321           easier to satisfy all dependencies when multiple packages are
4322           being upgraded.
4323         </p>
4324
4325         <p>
4326           If there is a circular dependency among packages being installed
4327           or removed, installation or removal order honoring the
4328           dependency order is impossible, requiring the dependency loop be
4329           broken at some point and the dependency requirements violated
4330           for at least one package.  Packages involved in circular
4331           dependencies may not be able to rely on their dependencies being
4332           configured when being configured or removed depending on which
4333           side of the break of the circular dependency loop they happen to
4334           be on.  If one of the packages in the loop has no
4335           <prgn>postinst</prgn> script, then the cycle will be broken at
4336           that package; this ensures that all <prgn>postinst</prgn>
4337           scripts are run with their dependencies properly configured if
4338           this is possible.  Otherwise the breaking point is arbitrary.
4339           Packages should therefore avoid circular dependencies where
4340           possible, particularly if they have <prgn>postinst</prgn>
4341           scripts.
4342         </p>
4343
4344         <p>
4345           The meaning of the five dependency fields is as follows:
4346           <taglist>
4347             <tag><tt>Depends</tt></tag>
4348             <item>
4349               <p>
4350                 This declares an absolute dependency.  A package will
4351                 not be configured unless all of the packages listed in
4352                 its <tt>Depends</tt> field have been correctly
4353                 configured (unless there is a circular dependency as
4354                 described above).
4355               </p>
4356
4357               <p>
4358                 The <tt>Depends</tt> field should be used if the
4359                 depended-on package is required for the depending
4360                 package to provide a significant amount of
4361                 functionality.
4362               </p>
4363
4364               <p>
4365                 The <tt>Depends</tt> field should also be used if the
4366                 <prgn>postinst</prgn>, <prgn>prerm</prgn> or
4367                 <prgn>postrm</prgn> scripts require the package to be
4368                 present in order to run.  (If both packages are involved
4369                 in a dependency loop, this might not work as expected; see
4370                 the explanation a few paragraphs back.)  In the case of
4371                 <prgn>postinst</prgn> and <prgn>postrm</prgn>, the
4372                 depended-on packages will be unpacked and configured
4373                 first.  (Note, however, that the <prgn>postrm</prgn>
4374                 cannot rely on any non-essential packages to be present
4375                 during the <tt>purge</tt> phase.)  In the case of
4376                 <prgn>prerm</prgn>, the depended-on package will at least
4377                 be unpacked (it might be configured too, but you can't
4378                 rely on this unless you use <tt>Pre-Depends</tt>).
4379             </item>
4380
4381             <tag><tt>Recommends</tt></tag>
4382             <item>
4383               <p>
4384                 This declares a strong, but not absolute, dependency.
4385               </p>
4386
4387               <p>
4388                 The <tt>Recommends</tt> field should list packages
4389                 that would be found together with this one in all but
4390                 unusual installations.
4391               </p>
4392             </item>
4393
4394             <tag><tt>Suggests</tt></tag>
4395             <item>
4396                 This is used to declare that one package may be more
4397                 useful with one or more others.  Using this field
4398                 tells the packaging system and the user that the
4399                 listed packages are related to this one and can
4400                 perhaps enhance its usefulness, but that installing
4401                 this one without them is perfectly reasonable.
4402             </item>
4403
4404             <tag><tt>Enhances</tt></tag>
4405             <item>
4406                 This field is similar to Suggests but works in the
4407                 opposite direction. It is used to declare that a
4408                 package can enhance the functionality of another
4409                 package.
4410             </item>
4411
4412             <tag><tt>Pre-Depends</tt></tag>
4413             <item>
4414               <p>
4415                 This field is like <tt>Depends</tt>, except that it
4416                 also forces <prgn>dpkg</prgn> to complete installation
4417                 of the packages named before even starting the
4418                 installation of the package which declares the
4419                 pre-dependency, as follows:
4420               </p>
4421
4422               <p>
4423                 When a package declaring a pre-dependency is about to
4424                 be <em>unpacked</em> the pre-dependency can be
4425                 satisfied if the depended-on package is either fully
4426                 configured, <em>or even if</em> the depended-on
4427                 package(s) are only unpacked or in the "Half-Configured"
4428                 state, provided that they have been configured
4429                 correctly at some point in the past (and not removed
4430                 or partially removed since).  In this case, both the
4431                 previously-configured and currently unpacked or
4432                 "Half-Configured" versions must satisfy any version
4433                 clause in the <tt>Pre-Depends</tt> field.
4434               </p>
4435
4436               <p>
4437                 When the package declaring a pre-dependency is about
4438                 to be <em>configured</em>, the pre-dependency will be
4439                 treated as a normal <tt>Depends</tt>, that is, it will
4440                 be considered satisfied only if the depended-on
4441                 package has been correctly configured.  However, unlike
4442                 with <tt>Depends</tt>, <tt>Pre-Depends</tt> does not
4443                 permit circular dependencies to be broken.  If a circular
4444                 dependency is encountered while attempting to honor
4445                 <tt>Pre-Depends</tt>, the installation will be aborted.
4446               </p>
4447
4448               <p>
4449                 <tt>Pre-Depends</tt> are also required if the
4450                 <prgn>preinst</prgn> script depends on the named package.
4451                 It is best to avoid this situation if possible.
4452               </p>
4453
4454               <p>
4455                 <tt>Pre-Depends</tt> should be used sparingly,
4456                 preferably only by packages whose premature upgrade or
4457                 installation would hamper the ability of the system to
4458                 continue with any upgrade that might be in progress.
4459               </p>
4460             </item>
4461           </taglist>
4462         </p>
4463
4464         <p>
4465           When selecting which level of dependency to use you should
4466           consider how important the depended-on package is to the
4467           functionality of the one declaring the dependency.  Some
4468           packages are composed of components of varying degrees of
4469           importance.  Such a package should list using
4470           <tt>Depends</tt> the package(s) which are required by the
4471           more important components.  The other components'
4472           requirements may be mentioned as Suggestions or
4473           Recommendations, as appropriate to the components' relative
4474           importance.
4475         </p>
4476       </sect>
4477
4478       <sect id="breaks">
4479         <heading>Packages which break other packages - <tt>Breaks</tt></heading>
4480
4481         <p>
4482           When one binary package declares that it breaks another,
4483           <prgn>dpkg</prgn> will refuse to allow the package which
4484           declares <tt>Breaks</tt> be unpacked unless the broken
4485           package is deconfigured first, and it will refuse to
4486           allow the broken package to be reconfigured.
4487         </p>
4488
4489         <p>
4490           A package will not be regarded as causing breakage merely
4491           because its configuration files are still installed; it must
4492           be at least "Half-Installed".
4493         </p>
4494
4495         <p>
4496           A special exception is made for packages which declare that
4497           they break their own package name or a virtual package which
4498           they provide (see below): this does not count as a real
4499           breakage.
4500         </p>
4501
4502         <p>
4503           Normally a <tt>Breaks</tt> entry will have an "earlier than"
4504           version clause; such a <tt>Breaks</tt> is introduced in the
4505           version of an (implicit or explicit) dependency which
4506           violates an assumption or reveals a bug in earlier versions
4507           of the broken package.  This use of <tt>Breaks</tt> will
4508           inform higher-level package management tools that broken
4509           package must be upgraded before the new one.
4510         </p>
4511
4512         <p>
4513           If the breaking package also overwrites some files from the
4514           older package, it should use <tt>Replaces</tt> (not
4515           <tt>Conflicts</tt>) to ensure this goes smoothly.
4516         </p>
4517       </sect>
4518
4519       <sect id="conflicts">
4520         <heading>Conflicting binary packages - <tt>Conflicts</tt></heading>
4521
4522         <p>
4523           When one binary package declares a conflict with another
4524           using a <tt>Conflicts</tt> field, <prgn>dpkg</prgn> will
4525           refuse to allow them to be unpacked on the system at the
4526           same time.
4527         </p>
4528
4529         <p>
4530           If one package is to be unpacked, the other must be removed
4531           first - if the package being unpacked is marked as
4532           replacing (see <ref id="replaces">) the one on the system,
4533           or the one on the system is marked as deselected, or both
4534           packages are marked <tt>Essential</tt>, then
4535           <prgn>dpkg</prgn> will automatically remove the package
4536           which is causing the conflict, otherwise it will halt the
4537           installation of the new package with an error.  This
4538           mechanism is specifically designed to produce an error when
4539           the installed package is <tt>Essential</tt>, but the new
4540           package is not.
4541         </p>
4542
4543         <p>
4544           A package will not cause a conflict merely because its
4545           configuration files are still installed; it must be at least
4546           "Half-Installed".
4547         </p>
4548
4549         <p>
4550           A special exception is made for packages which declare a
4551           conflict with their own package name, or with a virtual
4552           package which they provide (see below): this does not
4553           prevent their installation, and allows a package to conflict
4554           with others providing a replacement for it.  You use this
4555           feature when you want the package in question to be the only
4556           package providing some feature.
4557         </p>
4558
4559         <p>
4560           A <tt>Conflicts</tt> entry should almost never have an
4561           "earlier than" version clause.  This would prevent
4562           <prgn>dpkg</prgn> from upgrading or installing the package
4563           which declared such a conflict until the upgrade or removal
4564           of the conflicted-with package had been completed.  Instead,
4565           <tt>Breaks</tt> may be used.
4566         </p>
4567       </sect>
4568
4569       <sect id="virtual"><heading>Virtual packages - <tt>Provides</tt>
4570         </heading>
4571
4572         <p>
4573           As well as the names of actual ("concrete") packages, the
4574           package relationship fields <tt>Depends</tt>,
4575           <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
4576           <tt>Pre-Depends</tt>, <tt>Breaks</tt>, <tt>Conflicts</tt>,
4577           <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
4578           <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>
4579           may mention "virtual packages".
4580         </p>
4581
4582         <p>
4583           A <em>virtual package</em> is one which appears in the
4584           <tt>Provides</tt> control file field of another package.
4585           The effect is as if the package(s) which provide a
4586           particular virtual package name had been listed by name
4587           everywhere the virtual package name appears. (See also <ref
4588             id="virtual_pkg">)
4589         </p>
4590
4591         <p>
4592           If there are both concrete and virtual packages of the same
4593           name, then the dependency may be satisfied (or the conflict
4594           caused) by either the concrete package with the name in
4595           question or any other concrete package which provides the
4596           virtual package with the name in question.  This is so that,
4597           for example, supposing we have
4598           <example compact="compact">
4599 Package: foo
4600 Depends: bar
4601           </example> and someone else releases an enhanced version of
4602           the <tt>bar</tt> package they can say:
4603           <example compact="compact">
4604 Package: bar-plus
4605 Provides: bar
4606           </example>
4607           and the <tt>bar-plus</tt> package will now also satisfy the
4608           dependency for the <tt>foo</tt> package.
4609         </p>
4610
4611         <p>
4612           If a relationship field has a version number attached
4613           then only real packages will be considered to see whether
4614           the relationship is satisfied (or the prohibition violated,
4615           for a conflict or breakage) - it is assumed that a real
4616           package which provides the virtual package is not of the
4617           "right" version.  So, a <tt>Provides</tt> field may not
4618           contain version numbers, and the version number of the
4619           concrete package which provides a particular virtual package
4620           will not be looked at when considering a dependency on or
4621           conflict with the virtual package name.
4622         </p>
4623
4624         <p>
4625           It is likely that the ability will be added in a future
4626           release of <prgn>dpkg</prgn> to specify a version number for
4627           each virtual package it provides.  This feature is not yet
4628           present, however, and is expected to be used only
4629           infrequently.
4630         </p>
4631
4632         <p>
4633           If you want to specify which of a set of real packages
4634           should be the default to satisfy a particular dependency on
4635           a virtual package, you should list the real package as an
4636           alternative before the virtual one.
4637         </p>
4638       </sect>
4639
4640
4641       <sect id="replaces"><heading>Overwriting files and replacing
4642           packages - <tt>Replaces</tt></heading>
4643
4644         <p>
4645           Packages can declare in their control file that they should
4646           overwrite files in certain other packages, or completely
4647           replace other packages. The <tt>Replaces</tt> control file
4648           field has these two distinct purposes.
4649         </p>
4650
4651         <sect1><heading>Overwriting files in other packages</heading>
4652
4653           <p>
4654             Firstly, as mentioned before, it is usually an error for a
4655             package to contain files which are on the system in
4656             another package.
4657           </p>
4658
4659           <p>
4660             However, if the overwriting package declares that it
4661             <tt>Replaces</tt> the one containing the file being
4662             overwritten, then <prgn>dpkg</prgn> will replace the file
4663             from the old package with that from the new.  The file
4664             will no longer be listed as "owned" by the old package.
4665           </p>
4666
4667           <p>
4668             If a package is completely replaced in this way, so that
4669             <prgn>dpkg</prgn> does not know of any files it still
4670             contains, it is considered to have "disappeared".  It will
4671             be marked as not wanted on the system (selected for
4672             removal) and not installed.  Any <tt>conffile</tt>s
4673             details noted for the package will be ignored, as they
4674             will have been taken over by the overwriting package.  The
4675             package's <prgn>postrm</prgn> script will be run with a
4676             special argument to allow the package to do any final
4677             cleanup required.  See <ref id="mscriptsinstact">.
4678             <footnote>
4679               <p>
4680                 Replaces is a one way relationship -- you have to              
4681                 install the replacing package after the replaced
4682                 package.
4683               </p>
4684             </footnote>
4685           </p>
4686
4687           <p>
4688             For this usage of <tt>Replaces</tt>, virtual packages (see
4689             <ref id="virtual">) are not considered when looking at a
4690             <tt>Replaces</tt> field - the packages declared as being
4691             replaced must be mentioned by their real names.
4692           </p>
4693
4694           <p>
4695             Furthermore, this usage of <tt>Replaces</tt> only takes
4696             effect when both packages are at least partially on the
4697             system at once, so that it can only happen if they do not
4698             conflict or if the conflict has been overridden.
4699           </p>
4700
4701         </sect1>
4702
4703         <sect1><heading>Replacing whole packages, forcing their
4704             removal</heading>
4705
4706           <p>
4707             Secondly, <tt>Replaces</tt> allows the packaging system to
4708             resolve which package should be removed when there is a
4709             conflict - see <ref id="conflicts">.  This usage only
4710             takes effect when the two packages <em>do</em> conflict,
4711             so that the two usages of this field do not interfere with
4712             each other.
4713           </p>
4714
4715           <p>
4716             In this situation, the package declared as being replaced
4717             can be a virtual package, so for example, all mail
4718             transport agents (MTAs) would have the following fields in
4719             their control files:
4720             <example compact="compact">
4721 Provides: mail-transport-agent
4722 Conflicts: mail-transport-agent
4723 Replaces: mail-transport-agent
4724             </example>
4725             ensuring that only one MTA can be unpacked at any one
4726             time.
4727         </sect1>
4728       </sect>
4729
4730       <sect id="sourcebinarydeps">
4731         <heading>Relationships between source and binary packages -
4732           <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
4733           <tt>Build-Conflicts</tt>, <tt>Build-Conflicts-Indep</tt>
4734         </heading>
4735
4736         <p>
4737           Source packages that require certain binary packages to be
4738           installed or absent at the time of building the package
4739           can declare relationships to those binary packages.
4740         </p>
4741
4742         <p>
4743           This is done using the <tt>Build-Depends</tt>,
4744           <tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt> and
4745           <tt>Build-Conflicts-Indep</tt> control file fields.
4746         </p>
4747
4748         <p>
4749           Build-dependencies on "build-essential" binary packages can be
4750           omitted. Please see <ref id="pkg-relations"> for more information.
4751         </p>
4752
4753         <p>
4754           The dependencies and conflicts they define must be satisfied
4755           (as defined earlier for binary packages) in order to invoke
4756           the targets in <tt>debian/rules</tt>, as follows:<footnote>
4757             <p>
4758               If you make "build-arch" or "binary-arch", you need
4759               Build-Depends.  If you make "build-indep" or
4760               "binary-indep", you need Build-Depends and
4761               Build-Depends-Indep.  If you make "build" or "binary",
4762               you need both.
4763             </p>
4764             <p>
4765               There is no Build-Depends-Arch; this role is essentially
4766               met with Build-Depends.  Anyone building the
4767               <tt>build-indep</tt> and binary-indep<tt></tt> targets
4768               is basically assumed to be building the whole package
4769               anyway and so installs all build dependencies.  The
4770               autobuilders use <tt>dpkg-buildpackage -B</tt>, which
4771               calls <tt>build</tt> (not <tt>build-arch</tt>, since it
4772               does not yet know how to check for its existence) and
4773               <tt>binary-arch</tt>.
4774             </p>
4775             <p>
4776               The purpose of the original split, I recall, was so that
4777               the autobuilders wouldn't need to install extra packages
4778               needed only for the binary-indep targets.  But without a
4779               build-arch/build-indep split, this didn't work, since
4780               most of the work is done in the build target, not in the
4781               binary target.
4782             </p>
4783           </footnote>
4784
4785           <taglist>
4786             <tag><tt>Build-Depends</tt>, <tt>Build-Conflicts</tt></tag>
4787             <item>
4788                 The <tt>Build-Depends</tt> and
4789                 <tt>Build-Conflicts</tt> fields must be satisfied when
4790                 any of the following targets is invoked:
4791                 <tt>build</tt>, <tt>clean</tt>, <tt>binary</tt>,
4792                 <tt>binary-arch</tt>, <tt>build-arch</tt>,
4793                 <tt>build-indep</tt> and <tt>binary-indep</tt>.
4794             </item>
4795             <tag><tt>Build-Depends-Indep</tt>,
4796               <tt>Build-Conflicts-Indep</tt></tag>
4797             <item>
4798                 The <tt>Build-Depends-Indep</tt> and
4799                 <tt>Build-Conflicts-Indep</tt> fields must be
4800                 satisfied when any of the following targets is
4801                 invoked: <tt>build</tt>, <tt>build-indep</tt>,
4802                 <tt>binary</tt> and <tt>binary-indep</tt>.
4803             </item>
4804           </taglist>
4805         </p>
4806
4807       </sect>
4808
4809     </chapt>
4810
4811
4812     <chapt id="sharedlibs"><heading>Shared libraries</heading>
4813
4814       <p>
4815         Packages containing shared libraries must be constructed with
4816         a little care to make sure that the shared library is always
4817         available.  This is especially important for packages whose
4818         shared libraries are vitally important, such as the C library
4819         (currently <tt>libc6</tt>).
4820       </p>
4821
4822       <p>
4823         Packages involving shared libraries should be split up into
4824         several binary packages. This section mostly deals with how
4825         this separation is to be accomplished; rules for files within
4826         the shared library packages are in <ref id="libraries"> instead.
4827       </p>
4828
4829       <sect id="sharedlibs-runtime">
4830         <heading>Run-time shared libraries</heading>
4831
4832       <p>
4833         The run-time shared library needs to be placed in a package
4834         whose name changes whenever the shared object version
4835         changes.<footnote>
4836             <p>
4837               Since it is common place to install several versions of a
4838               package that just provides shared libraries, it is a
4839               good idea that the library package should not
4840               contain any extraneous non-versioned files, unless they
4841               happen to be in versioned directories.</p>
4842           </footnote>
4843           The most common mechanism is to place it in a package
4844         called
4845         <package><var>libraryname</var><var>soversion</var></package>,
4846         where <file><var>soversion</var></file> is the version number
4847         in the soname of the shared library<footnote>
4848               The soname is the shared object name: it's the thing
4849               that has to match exactly between building an executable
4850               and running it for the dynamic linker to be able run the
4851               program.  For example, if the soname of the library is
4852               <file>libfoo.so.6</file>, the library package would be
4853               called <file>libfoo6</file>.
4854           </footnote>.
4855         Alternatively, if it would be confusing to directly append
4856         <var>soversion</var> to <var>libraryname</var> (e.g. because
4857         <var>libraryname</var> itself ends in a number), you may use
4858         <package><var>libraryname</var>-<var>soversion</var></package> and
4859         <package><var>libraryname</var>-<var>soversion</var>-dev</package>
4860         instead.
4861       </p>
4862
4863       <p>
4864         If you have several shared libraries built from the same
4865         source tree you may lump them all together into a single
4866         shared library package, provided that you change all of
4867         their sonames at once (so that you don't get filename
4868         clashes if you try to install different versions of the
4869         combined shared libraries package).
4870       </p>
4871
4872       <p>
4873         The package should install the shared libraries under
4874         their normal names.  For example, the <package>libgdbm3</package>
4875         package should install <file>libgdbm.so.3.0.0</file> as
4876         <file>/usr/lib/libgdbm.so.3.0.0</file>.  The files should not be
4877         renamed or re-linked by any <prgn>prerm</prgn> or
4878         <prgn>postrm</prgn> scripts; <prgn>dpkg</prgn> will take care
4879         of renaming things safely without affecting running programs,
4880         and attempts to interfere with this are likely to lead to
4881         problems.
4882       </p>
4883
4884       <p>
4885         Shared libraries should not be installed executable, since
4886         the dynamic linker does not require this and trying to
4887         execute a shared library usually results in a core dump.
4888       </p>
4889
4890       <p>
4891         The run-time library package should include the symbolic link that
4892         <prgn>ldconfig</prgn> would create for the shared libraries.
4893         For example, the <package>libgdbm3</package> package should include
4894         a symbolic link from <file>/usr/lib/libgdbm.so.3</file> to
4895         <file>libgdbm.so.3.0.0</file>.  This is needed so that the dynamic
4896         linker (for example <prgn>ld.so</prgn> or
4897         <prgn>ld-linux.so.*</prgn>) can find the library between the
4898         time that <prgn>dpkg</prgn> installs it and the time that
4899         <prgn>ldconfig</prgn> is run in the <prgn>postinst</prgn>
4900         script.<footnote>
4901             The package management system requires the library to be
4902             placed before the symbolic link pointing to it in the
4903             <file>.deb</file> file.  This is so that when
4904             <prgn>dpkg</prgn> comes to install the symlink
4905             (overwriting the previous symlink pointing at an older
4906             version of the library), the new shared library is already
4907             in place.  In the past, this was achieved by creating the
4908             library in the temporary packaging directory before
4909             creating the symlink.  Unfortunately, this was not always
4910             effective, since the building of the tar file in the
4911             <file>.deb</file> depended on the behavior of the underlying
4912             file system.  Some file systems (such as reiserfs) reorder
4913             the files so that the order of creation is forgotten.
4914             Since version 1.7.0, <prgn>dpkg</prgn>
4915             reorders the files itself as necessary when building a
4916             package.  Thus it is no longer important to concern
4917             oneself with the order of file creation.
4918         </footnote>
4919       </p>
4920
4921         <sect1 id="ldconfig">
4922           <heading><tt>ldconfig</tt></heading>
4923
4924         <p>
4925           Any package installing shared libraries in one of the default
4926           library directories of the dynamic linker (which are currently
4927           <file>/usr/lib</file> and <file>/lib</file>) or a directory that is
4928           listed in <file>/etc/ld.so.conf</file><footnote>
4929             These are currently
4930             <list compact="compact">
4931               <item>/usr/local/lib</item>
4932               <item>/usr/lib/libc5-compat</item>
4933               <item>/lib/libc5-compat</item>
4934             </list>
4935           </footnote>
4936           must use <prgn>ldconfig</prgn> to update the shared library
4937           system.
4938         </p>
4939
4940         <p>
4941             The package maintainer scripts must only call
4942             <prgn>ldconfig</prgn> under these circumstances:
4943             <list compact="compact">
4944               <item>When the <prgn>postinst</prgn> script is run with a
4945                   first argument of <tt>configure</tt>, the script must call
4946                   <prgn>ldconfig</prgn>, and may optionally invoke
4947                   <prgn>ldconfig</prgn> at other times.
4948               </item>
4949               <item>When the <prgn>postrm</prgn> script is run with a
4950                   first argument of <tt>remove</tt>, the script should call
4951                   <prgn>ldconfig</prgn>.
4952               </item>
4953             </list>
4954          <footnote>
4955             <p>
4956               During install or upgrade, the preinst is called before
4957               the new files are unpacked, so calling "ldconfig" is
4958               pointless.  The preinst of an existing package can also be
4959               called if an upgrade fails.  However, this happens during
4960               the critical time when a shared libs may exist on-disk
4961               under a temporary name.  Thus, it is dangerous and
4962               forbidden by current policy to call "ldconfig" at this
4963               time.
4964             </p>
4965
4966             <p>
4967               When a package is installed or upgraded, "postinst
4968               configure" runs after the new files are safely on-disk.
4969               Since it is perfectly safe to invoke ldconfig
4970               unconditionally in a postinst, it is OK for a package to
4971               simply put ldconfig in its postinst without checking the
4972               argument.  The postinst can also be called to recover from
4973               a failed upgrade.  This happens before any new files are
4974               unpacked, so there is no reason to call "ldconfig" at this
4975               point.
4976             </p>
4977
4978             <p>
4979               For a package that is being removed, prerm is
4980               called with all the files intact, so calling ldconfig is
4981               useless.  The other calls to "prerm" happen in the case of
4982               upgrade at a time when all the files of the old package
4983               are on-disk, so again calling "ldconfig" is pointless.
4984             </p>
4985
4986             <p>
4987               postrm, on the other hand, is called with the "remove"
4988               argument just after the files are removed, so this is
4989               the proper time to call "ldconfig" to notify the system
4990               of the fact that the shared libraries from the package
4991               are removed.  The postrm can be called at several other
4992               times.  At the time of "postrm purge", "postrm
4993               abort-install", or "postrm abort-upgrade", calling
4994               "ldconfig" is useless because the shared lib files are
4995               not on-disk.  However, when "postrm" is invoked with
4996               arguments "upgrade", "failed-upgrade", or "disappear", a
4997               shared lib may exist on-disk under a temporary filename.
4998             </p>
4999           </footnote>
5000         </p>
5001         </sect1>
5002
5003       </sect>
5004
5005       <sect id="sharedlibs-support-files">
5006         <heading>Shared library support files</heading>
5007
5008         <p>
5009           If your package contains files whose names do not change with
5010           each change in the library shared object version, you must not
5011           put them in the shared library package.  Otherwise, several
5012           versions of the shared library cannot be installed at the same
5013           time without filename clashes, making upgrades and transitions
5014           unnecessarily difficult.
5015         </p>
5016
5017         <p>
5018           It is recommended that supporting files and run-time support
5019           programs that do not need to be invoked manually by users, but
5020           are nevertheless required for the package to function, be placed
5021           (if they are binary) in a subdirectory of <file>/usr/lib</file>,
5022           preferably under <file>/usr/lib/</file><var>package-name</var>.
5023           If the program or file is architecture independent, the
5024           recommendation is for it to be placed in a subdirectory of
5025           <file>/usr/share</file> instead, preferably under
5026           <file>/usr/share/</file><var>package-name</var>.  Following the
5027           <var>package-name</var> naming convention ensures that the file
5028           names change when the shared object version changes.
5029         </p>
5030
5031         <p>
5032           Run-time support programs that use the shared library but are
5033           not required for the library to function or files used by the
5034           shared library that can be used by any version of the shared
5035           library package should instead be put in a separate package.
5036           This package might typically be named
5037           <package><var>libraryname</var>-tools</package>; note the
5038           absence of the <var>soversion</var> in the package name.
5039         </p>
5040
5041         <p>
5042           Files and support programs only useful when compiling software
5043           against the library should be included in the development
5044           package for the library.<footnote>
5045             For example, a <file><var>package-name</var>-config</file>
5046             script or <package>pkg-config</package> configuration files.
5047           </footnote>
5048         </p>
5049       </sect>
5050
5051       <sect id="sharedlibs-static">
5052         <heading>Static libraries</heading>
5053
5054       <p>
5055         The static library (<file><var>libraryname.a</var></file>)
5056         is usually provided in addition to the shared version.
5057         It is placed into the development package (see below).
5058       </p>
5059
5060       <p>
5061         In some cases, it is acceptable for a library to be
5062         available in static form only; these cases include:
5063         <list>
5064           <item>libraries for languages whose shared library support
5065                 is immature or unstable</item>
5066           <item>libraries whose interfaces are in flux or under
5067                 development (commonly the case when the library's
5068                 major version number is zero, or where the ABI breaks
5069                 across patchlevels)</item>
5070           <item>libraries which are explicitly intended to be
5071                 available only in static form by their upstream
5072                 author(s)</item>
5073         </list>
5074       </p>
5075
5076       <sect id="sharedlibs-dev">
5077         <heading>Development files</heading>
5078
5079       <p>
5080         The development files associated to a shared library need to be
5081         placed in a package called
5082         <package><var>libraryname</var><var>soversion</var>-dev</package>,
5083         or if you prefer only to support one development version at a
5084         time, <package><var>libraryname</var>-dev</package>.
5085       </p>
5086
5087       <p>
5088         In case several development versions of a library exist, you may
5089         need to use <prgn>dpkg</prgn>'s Conflicts mechanism (see
5090         <ref id="conflicts">) to ensure that the user only installs one
5091         development version at a time (as different development versions are
5092         likely to have the same header files in them, which would cause a
5093         filename clash if both were unpacked).
5094       </p>
5095
5096       <p>
5097         The development package should contain a symlink for the associated
5098         shared library without a version number. For example, the
5099         <package>libgdbm-dev</package> package should include a symlink
5100         from <file>/usr/lib/libgdbm.so</file> to
5101         <file>libgdbm.so.3.0.0</file>.  This symlink is needed by the linker
5102         (<prgn>ld</prgn>) when compiling packages, as it will only look for
5103         <file>libgdbm.so</file> when compiling dynamically.
5104       </p>
5105       </sect>
5106
5107       <sect id="sharedlibs-intradeps">
5108         <heading>Dependencies between the packages of the same library</heading>
5109
5110         <p>
5111           Typically the development version should have an exact
5112           version dependency on the runtime library, to make sure that
5113           compilation and linking happens correctly.  The
5114           <tt>${binary:Version}</tt> substitution variable can be
5115           useful for this purpose.
5116           <footnote>
5117             Previously, <tt>${Source-Version}</tt> was used, but its name
5118             was confusing and it has been deprecated since dpkg 1.13.19.
5119           </footnote>
5120         </p>
5121       </sect>
5122
5123       <sect id="sharedlibs-shlibdeps">
5124         <heading>Dependencies between the library and other packages -
5125         the <tt>shlibs</tt> system</heading>
5126
5127         <p>
5128           If a package contains a binary or library which links to a
5129           shared library, we must ensure that when the package is
5130           installed on the system, all of the libraries needed are
5131           also installed.  This requirement led to the creation of the
5132           <tt>shlibs</tt> system, which is very simple in its design:
5133           any package which <em>provides</em> a shared library also
5134           provides information on the package dependencies required to
5135           ensure the presence of this library, and any package which
5136           <em>uses</em> a shared library uses this information to
5137           determine the dependencies it requires.  The files which
5138           contain the mapping from shared libraries to the necessary
5139           dependency information are called <file>shlibs</file> files.
5140         </p>
5141
5142         <p>
5143           Thus, when a package is built which contains any shared
5144           libraries, it must provide a <file>shlibs</file> file for other
5145           packages to use, and when a package is built which contains
5146           any shared libraries or compiled binaries, it must run
5147           <qref id="pkg-dpkg-shlibdeps"><prgn>dpkg-shlibdeps</prgn></qref>
5148           on these to determine the libraries used and hence the
5149           dependencies needed by this package.<footnote>
5150             <p>
5151               In the past, the shared libraries linked to were
5152               determined by calling <prgn>ldd</prgn>, but now
5153               <prgn>objdump</prgn> is used to do this.  The only
5154               change this makes to package building is that
5155               <prgn>dpkg-shlibdeps</prgn> must also be run on shared
5156               libraries, whereas in the past this was unnecessary.
5157               The rest of this footnote explains the advantage that
5158               this method gives.
5159             </p>
5160
5161             <p>
5162               We say that a binary <tt>foo</tt> <em>directly</em> uses
5163               a library <tt>libbar</tt> if it is explicitly linked
5164               with that library (that is, it uses the flag
5165               <tt>-lbar</tt> during the linking stage).  Other
5166               libraries that are needed by <tt>libbar</tt> are linked
5167               <em>indirectly</em> to <tt>foo</tt>, and the dynamic
5168               linker will load them automatically when it loads
5169               <tt>libbar</tt>.  A package should depend on
5170               the libraries it directly uses, and the dependencies for
5171               those libraries should automatically pull in the other
5172               libraries.
5173             </p>
5174
5175             <p>
5176               Unfortunately, the <prgn>ldd</prgn> program shows both
5177               the directly and indirectly used libraries, meaning that
5178               the dependencies determined included both direct and
5179               indirect dependencies.  The use of <prgn>objdump</prgn>
5180               avoids this problem by determining only the directly
5181               used libraries.
5182             </p>
5183
5184             <p>
5185               A good example of where this helps is the following.  We
5186               could update <tt>libimlib</tt> with a new version that
5187               supports a new graphics format called dgf (but retaining
5188               the same major version number).  If we used the old
5189               <prgn>ldd</prgn> method, every package that uses
5190               <tt>libimlib</tt> would need to be recompiled so it
5191               would also depend on <tt>libdgf</tt> or it wouldn't run
5192               due to missing symbols.  However with the new system,
5193               packages using <tt>libimlib</tt> can rely on
5194               <tt>libimlib</tt> itself having the dependency on
5195               <tt>libdgf</tt> and so they would not need rebuilding.
5196             </p>
5197           </footnote>
5198         </p>
5199
5200         <p>
5201           In the following sections, we will first describe where the
5202           various <tt>shlibs</tt> files are to be found, then how to
5203           use <prgn>dpkg-shlibdeps</prgn>, and finally the <tt>shlibs</tt>
5204           file format and how to create them if your package contains a
5205           shared library.
5206         </p>
5207
5208       <sect1>
5209         <heading>The <tt>shlibs</tt> files present on the system</heading>
5210
5211         <p>
5212           There are several places where <tt>shlibs</tt> files are
5213           found.  The following list gives them in the order in which
5214           they are read by
5215           <qref id="pkg-dpkg-shlibdeps"><prgn>dpkg-shlibdeps</prgn></qref>.
5216           (The first one which gives the required information is used.)
5217         </p>
5218
5219         <p>
5220           <list>
5221             <item>
5222               <p><file>debian/shlibs.local</file></p>
5223
5224               <p>
5225                 This lists overrides for this package.  Its use is
5226                 described below (see <ref id="shlibslocal">).
5227               </p>
5228             </item>
5229
5230             <item>
5231               <p><file>/etc/dpkg/shlibs.override</file></p>
5232
5233               <p>
5234                 This lists global overrides.  This list is normally
5235                 empty.  It is maintained by the local system
5236                 administrator.
5237               </p>
5238             </item>
5239
5240             <item>
5241               <p><file>DEBIAN/shlibs</file> files in the "build directory"</p>
5242
5243               <p>
5244                 When packages are being built, any
5245                 <file>debian/shlibs</file> files are copied into the
5246                 control file area of the temporary build directory and
5247                 given the name <file>shlibs</file>.  These files give
5248                 details of any shared libraries included in the
5249                 package.<footnote>
5250                     An example may help here.  Let us say that the
5251                     source package <tt>foo</tt> generates two binary
5252                     packages, <tt>libfoo2</tt> and
5253                     <tt>foo-runtime</tt>.  When building the binary
5254                     packages, the two packages are created in the
5255                     directories <file>debian/libfoo2</file> and
5256                     <file>debian/foo-runtime</file> respectively.
5257                     (<file>debian/tmp</file> could be used instead of one
5258                     of these.)  Since <tt>libfoo2</tt> provides the
5259                     <tt>libfoo</tt> shared library, it will require a
5260                     <tt>shlibs</tt> file, which will be installed in
5261                     <file>debian/libfoo2/DEBIAN/shlibs</file>, eventually
5262                     to become
5263                     <file>/var/lib/dpkg/info/libfoo2.shlibs</file>.  Then
5264                     when <prgn>dpkg-shlibdeps</prgn> is run on the
5265                     executable
5266                     <file>debian/foo-runtime/usr/bin/foo-prog</file>, it
5267                     will examine the
5268                     <file>debian/libfoo2/DEBIAN/shlibs</file> file to
5269                     determine whether <tt>foo-prog</tt>'s library
5270                     dependencies are satisfied by any of the libraries
5271                     provided by <tt>libfoo2</tt>.  For this reason,
5272                     <prgn>dpkg-shlibdeps</prgn> must only be run once
5273                     all of the individual binary packages'
5274                     <tt>shlibs</tt> files have been installed into the
5275                     build directory.
5276                 </footnote>
5277               </p>
5278             </item>
5279
5280             <item>
5281               <p><file>/var/lib/dpkg/info/*.shlibs</file></p>
5282
5283               <p>
5284                 These are the <file>shlibs</file> files corresponding to
5285                 all of the packages installed on the system, and are
5286                 maintained by the relevant package maintainers.
5287               </p>
5288             </item>
5289
5290             <item>
5291               <p><file>/etc/dpkg/shlibs.default</file></p>
5292
5293               <p>
5294                 This file lists any shared libraries whose packages
5295                 have failed to provide correct <file>shlibs</file> files.
5296                 It was used when the <file>shlibs</file> setup was first
5297                 introduced, but it is now normally empty.  It is
5298                 maintained by the <tt>dpkg</tt> maintainer.
5299               </p>
5300             </item>
5301           </list>
5302         </p>
5303       </sect1>
5304
5305       <sect1>
5306         <heading>How to use <prgn>dpkg-shlibdeps</prgn> and the
5307             <file>shlibs</file> files</heading>
5308
5309         <p>
5310           Put a call to
5311           <qref id="pkg-dpkg-shlibdeps"><prgn>dpkg-shlibdeps</prgn></qref>
5312           into your <file>debian/rules</file> file.  If your package
5313           contains only compiled binaries and libraries (but no scripts),
5314           you can use a command such as:
5315           <example compact="compact">
5316 dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \
5317   debian/tmp/usr/lib/*
5318           </example>
5319           Otherwise, you will need to explicitly list the compiled
5320           binaries and libraries.<footnote>
5321               If you are using <tt>debhelper</tt>, the
5322               <prgn>dh_shlibdeps</prgn> program will do this work for
5323               you.  It will also correctly handle multi-binary
5324               packages.
5325           </footnote>
5326         </p>
5327
5328         <p>
5329           This command puts the dependency information into the
5330           <file>debian/substvars</file> file, which is then used by
5331           <prgn>dpkg-gencontrol</prgn>.  You will need to place a
5332           <tt>${shlibs:Depends}</tt> variable in the <tt>Depends</tt>
5333           field in the control file for this to work.
5334         </p>
5335
5336         <p>
5337           If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
5338           done.  If it does complain you might need to create your own
5339           <file>debian/shlibs.local</file> file, as explained below (see
5340           <ref id="shlibslocal">).
5341         </p>
5342
5343         <p>
5344           If you have multiple binary packages, you will need to call
5345           <prgn>dpkg-shlibdeps</prgn> on each one which contains
5346           compiled libraries or binaries.  In such a case, you will
5347           need to use the <tt>-T</tt> option to the <tt>dpkg</tt>
5348           utilities to specify a different <file>substvars</file> file.
5349         </p>
5350
5351         <p>
5352           If you are creating a udeb for use in the Debian Installer,
5353           you will need to specify that <prgn>dpkg-shlibdeps</prgn>
5354           should use the dependency line of type <tt>udeb</tt> by
5355           adding the <tt>-tudeb</tt> option<footnote>
5356               <prgn>dh_shlibdeps</prgn> from the <tt>debhelper</tt> suite
5357               will automatically add this option if it knows it is
5358               processing a udeb.
5359           </footnote>. If there is no dependency line of type <tt>udeb</tt>
5360           in the <file>shlibs</file> file, <prgn>dpkg-shlibdeps</prgn> will
5361           fall back to the regular dependency line.
5362         </p>
5363
5364         <p>
5365           For more details on dpkg-shlibdeps, please see
5366           <ref id="pkg-dpkg-shlibdeps"> and
5367           <manref name="dpkg-shlibdeps" section="1">.
5368         </p>
5369       </sect1>
5370
5371       <sect1 id="shlibs">
5372         <heading>The <file>shlibs</file> File Format</heading>
5373
5374         <p>
5375           Each <file>shlibs</file> file has the same format.  Lines
5376           beginning with <tt>#</tt> are considered to be comments and
5377           are ignored.  Each line is of the form:
5378           <example compact="compact">
5379 [<var>type</var>: ]<var>library-name</var> <var>soname-version</var> <var>dependencies ...</var>
5380           </example>
5381         </p>
5382
5383         <p>
5384           We will explain this by reference to the example of the
5385           <tt>zlib1g</tt> package, which (at the time of writing)
5386           installs the shared library <file>/usr/lib/libz.so.1.1.3</file>.
5387         </p>
5388
5389         <p>
5390           <var>type</var> is an optional element that indicates the type
5391           of package for which the line is valid. The only type currently
5392           in use is <tt>udeb</tt>. The colon and space after the type are
5393           required.
5394         </p>
5395
5396         <p>
5397           <var>library-name</var> is the name of the shared library,
5398           in this case <tt>libz</tt>.  (This must match the name part
5399           of the soname, see below.)
5400         </p>
5401
5402         <p>
5403           <var>soname-version</var> is the version part of the soname of
5404           the library.  The soname is the thing that must exactly match
5405           for the library to be recognized by the dynamic linker, and is
5406           usually of the form
5407           <tt><var>name</var>.so.<var>major-version</var></tt>, in our
5408           example, <tt>libz.so.1</tt>.<footnote>
5409               This can be determined using the command
5410               <example compact="compact">
5411 objdump -p /usr/lib/libz.so.1.1.3 | grep SONAME
5412               </example>
5413           </footnote>
5414           The version part is the part which comes after
5415           <tt>.so.</tt>, so in our case, it is <tt>1</tt>.
5416         </p>
5417
5418         <p>
5419           <var>dependencies</var> has the same syntax as a dependency
5420           field in a binary package control file.  It should give
5421           details of which packages are required to satisfy a binary
5422           built against the version of the library contained in the
5423           package.  See <ref id="depsyntax"> for details.
5424         </p>
5425
5426         <p>
5427           In our example, if the first version of the <tt>zlib1g</tt>
5428           package which contained a minor number of at least
5429           <tt>1.3</tt> was <var>1:1.1.3-1</var>, then the
5430           <tt>shlibs</tt> entry for this library could say:
5431           <example compact="compact">
5432 libz 1 zlib1g (>= 1:1.1.3)
5433           </example>
5434           The version-specific dependency is to avoid warnings from
5435           the dynamic linker about using older shared libraries with
5436           newer binaries.
5437         </p>
5438
5439         <p>
5440           As zlib1g also provides a udeb containing the shared library,
5441           there would also be a second line:
5442           <example compact="compact">
5443 udeb: libz 1 zlib1g-udeb (>= 1:1.1.3)
5444           </example>
5445         </p>
5446       </sect1>
5447
5448       <sect1>
5449         <heading>Providing a <file>shlibs</file> file</heading>
5450
5451         <p>
5452           If your package provides a shared library, you need to create
5453           a <file>shlibs</file> file following the format described above.
5454           It is usual to call this file <file>debian/shlibs</file> (but if
5455           you have multiple binary packages, you might want to call it
5456           <file>debian/shlibs.<var>package</var></file> instead).  Then
5457           let <file>debian/rules</file> install it in the control area:
5458           <example compact="compact">
5459 install -m644 debian/shlibs debian/tmp/DEBIAN
5460           </example>
5461           or, in the case of a multi-binary package:
5462           <example compact="compact">
5463 install -m644 debian/shlibs.<var>package</var> debian/<var>package</var>/DEBIAN/shlibs
5464           </example>
5465           An alternative way of doing this is to create the
5466           <file>shlibs</file> file in the control area directly from
5467           <file>debian/rules</file> without using a <file>debian/shlibs</file>
5468           file at all,<footnote>
5469               This is what <prgn>dh_makeshlibs</prgn> in the
5470               <tt>debhelper</tt> suite does. If your package also has a udeb
5471               that provides a shared library, <prgn>dh_makeshlibs</prgn> can
5472               automatically generate the <tt>udeb:</tt> lines if you specify
5473               the name of the udeb with the <tt>--add-udeb</tt> option.
5474           </footnote>
5475           since the <file>debian/shlibs</file> file itself is ignored by
5476           <prgn>dpkg-shlibdeps</prgn>.
5477         </p>
5478
5479         <p>
5480           As <prgn>dpkg-shlibdeps</prgn> reads the
5481           <file>DEBIAN/shlibs</file> files in all of the binary packages
5482           being built from this source package, all of the
5483           <file>DEBIAN/shlibs</file> files should be installed before
5484           <prgn>dpkg-shlibdeps</prgn> is called on any of the binary
5485           packages.
5486         </p>
5487       </sect1>
5488
5489       <sect1 id="shlibslocal">
5490         <heading>Writing the <file>debian/shlibs.local</file> file</heading>
5491
5492         <p>
5493           This file is intended only as a <em>temporary</em> fix if
5494           your binaries or libraries depend on a library whose package
5495           does not yet provide a correct <file>shlibs</file> file.
5496         </p>
5497
5498         <p>
5499           We will assume that you are trying to package a binary
5500           <tt>foo</tt>.  When you try running
5501           <prgn>dpkg-shlibdeps</prgn> you get the following error
5502           message (<tt>-O</tt> displays the dependency information on
5503           <tt>stdout</tt> instead of writing it to
5504           <tt>debian/substvars</tt>, and the lines have been wrapped
5505           for ease of reading):
5506           <example compact="compact">
5507 $ dpkg-shlibdeps -O debian/tmp/usr/bin/foo
5508 dpkg-shlibdeps: warning: unable to find dependency
5509   information for shared library libbar (soname 1,
5510   path /usr/lib/libbar.so.1, dependency field Depends)
5511 shlibs:Depends=libc6 (>= 2.2.2-2)
5512           </example>
5513           You can then run <prgn>ldd</prgn> on the binary to find the
5514           full location of the library concerned:
5515           <example compact="compact">
5516 $ ldd foo
5517 libbar.so.1 => /usr/lib/libbar.so.1 (0x4001e000)
5518 libc.so.6 => /lib/libc.so.6 (0x40032000)
5519 /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
5520           </example>
5521           So the <prgn>foo</prgn> binary depends on the
5522           <prgn>libbar</prgn> shared library, but no package seems to
5523           provide a <file>*.shlibs</file> file handling
5524           <file>libbar.so.1</file> in <file>/var/lib/dpkg/info/</file>.  Let's
5525           determine the package responsible:
5526           <example compact="compact">
5527 $ dpkg -S /usr/lib/libbar.so.1
5528 bar1: /usr/lib/libbar.so.1
5529 $ dpkg -s bar1 | grep Version
5530 Version: 1.0-1
5531           </example>
5532           This tells us that the <tt>bar1</tt> package, version 1.0-1,
5533           is the one we are using.  Now we can file a bug against the
5534           <tt>bar1</tt> package and create our own
5535           <file>debian/shlibs.local</file> to locally fix the problem.
5536           Including the following line into your
5537           <file>debian/shlibs.local</file> file:
5538           <example compact="compact">
5539 libbar 1 bar1 (>= 1.0-1)
5540           </example>
5541           should allow the package build to work.
5542         </p>
5543
5544         <p>
5545           As soon as the maintainer of <tt>bar1</tt> provides a
5546           correct <file>shlibs</file> file, you should remove this line
5547           from your <file>debian/shlibs.local</file> file.  (You should
5548           probably also then have a versioned <tt>Build-Depends</tt>
5549           on <tt>bar1</tt> to help ensure that others do not have the
5550           same problem building your package.)
5551         </p>
5552       </sect1>
5553
5554       </sect>
5555
5556     </chapt>
5557
5558
5559     <chapt id="opersys"><heading>The Operating System</heading>
5560
5561       <sect>
5562         <heading>File system hierarchy</heading>
5563
5564
5565         <sect1 id="fhs">
5566           <heading>File System Structure</heading>
5567
5568           <p>
5569             The location of all installed files and directories must
5570             comply with the Filesystem Hierarchy Standard (FHS),
5571             version 2.3, with the exceptions noted below, and except
5572             where doing so would violate other terms of Debian
5573             Policy.  The following exceptions to the FHS apply:
5574
5575             <enumlist>
5576               <item>
5577                 <p>
5578                   The optional rules related to user specific
5579                   configuration files for applications are stored in
5580                   the user's home directory are relaxed.  It is
5581                   recommended that such files start with the
5582                   '<tt>.</tt>' character (a "dot file"), and if an
5583                   application needs to create more than one dot file
5584                   then the preferred placement is in a subdirectory
5585                   with a name starting with a '.' character, (a "dot
5586                   directory"). In this case it is recommended the
5587                   configuration files not start with the '.'
5588                   character.
5589                 </p>
5590               </item>
5591               <item>
5592                 <p>
5593                   The requirement for amd64 to use <file>/lib64</file>
5594                   for 64 bit binaries is removed.
5595                 </p>
5596               </item>
5597               <item>
5598                 <p>
5599                   The requirement for object files, internal binaries, and
5600                   libraries, including <file>libc.so.*</file>, to be located
5601                   directly under <file>/lib{,32}</file> and
5602                   <file>/usr/lib{,32}</file> is amended, permitting files
5603                   to instead be installed to
5604                   <file>/lib/<var>triplet</var></file> and
5605                   <file>/usr/lib/<var>triplet</var></file>, where
5606                   <tt><var>triplet</var></tt> is the value returned by
5607                   <tt>dpkg-architecture -qDEB_HOST_GNU_TYPE</tt> for the
5608                   architecture of the package.  Packages may <em>not</em>
5609                   install files to any <var>triplet</var> path other
5610                   than the one matching the architecture of that package;
5611                   for instance, an <tt>Architecture: amd64</tt> package
5612                   containing 32-bit x86 libraries may not install these
5613                   libraries to <file>/usr/lib/i486-linux-gnu</file>.
5614                   <footnote>
5615                     This is necessary in order to reserve the directories for
5616                     use in cross-installation of library packages from other
5617                     architectures, as part of the planned deployment of
5618                     <tt>multiarch</tt>.
5619                   </footnote>
5620                 </p>
5621                 <p>
5622                   Applications may also use a single subdirectory under
5623                   <file>/usr/lib/<var>triplet</var></file>.
5624                 </p>
5625                 <p>
5626                   The execution time linker/loader, ld*, must still be made
5627                   available in the existing location under /lib or /lib64
5628                   since this is part of the ELF ABI for the architecture.
5629                 </p>
5630               </item>
5631               <item>
5632                 <p>
5633                   The requirement that
5634                   <file>/usr/local/share/man</file> be "synonymous"
5635                   with <file>/usr/local/man</file> is relaxed to a
5636                   recommendation</p>
5637               </item>
5638               <item>
5639                 <p>
5640                   The requirement that windowmanagers with a single
5641                   configuration file call it <file>system.*wmrc</file>
5642                   is removed, as is the restriction that the window
5643                   manager subdirectory be named identically to the
5644                   window manager name itself.
5645                 </p>
5646               </item>
5647               <item>
5648                 <p>
5649                   The requirement that boot manager configuration
5650                   files live in <file>/etc</file>, or at least are
5651                   symlinked there, is relaxed to a recommendation.
5652                 </p>
5653               </item>
5654               <item>
5655                 <p>
5656                   The following directories in the root filesystem are
5657                   additionally allowed: <file>/sys</file> and
5658                   <file>/selinux</file>. <footnote>These directories
5659                   are used as mount points to mount virtual filesystems
5660                   to get access to kernel information.</footnote>
5661                 </p>
5662               </item>
5663             </enumlist>
5664
5665           </p>
5666           <p>
5667             The version of this document referred here can be
5668             found in the <tt>debian-policy</tt> package or on <url
5669             id="http://www.debian.org/doc/packaging-manuals/fhs/"
5670               name="FHS (Debian copy)"> alongside this manual (or, if
5671             you have the <package>debian-policy</package> installed,
5672             you can try <url
5673               id="file:///usr/share/doc/debian-policy/fhs/" name="FHS
5674               (local copy)">). The
5675             latest version, which may be a more recent version, may
5676             be found on
5677             <url id="http://www.pathname.com/fhs/" name="FHS (upstream)">.
5678             Specific questions about following the standard may be
5679             asked on the <tt>debian-devel</tt> mailing list, or
5680             referred to the FHS mailing list (see the
5681             <url id="http://www.pathname.com/fhs/" name="FHS web site"> for
5682             more information).
5683           </p>
5684         </sect1>
5685
5686         <sect1>
5687           <heading>Site-specific programs</heading>
5688
5689           <p>
5690             As mandated by the FHS, packages must not place any
5691             files in <file>/usr/local</file>, either by putting them in
5692             the file system archive to be unpacked by <prgn>dpkg</prgn>
5693             or by manipulating them in their maintainer scripts.
5694           </p>
5695
5696           <p>
5697             However, the package may create empty directories below
5698             <file>/usr/local</file> so that the system administrator knows
5699             where to place site-specific files.  These are not
5700             directories <em>in</em> <file>/usr/local</file>, but are
5701             children of directories in <file>/usr/local</file>.  These
5702             directories (<file>/usr/local/*/dir/</file>)
5703             should be removed on package removal if they are
5704             empty.
5705           </p>
5706
5707           <p>
5708             Note that this applies only to
5709             directories <em>below</em> <file>/usr/local</file>,
5710             not <em>in</em> <file>/usr/local</file>.  Packages must
5711             not create sub-directories in the
5712             directory <file>/usr/local</file> itself, except those
5713             listed in FHS, section 4.5.  However, you may create
5714             directories below them as you wish. You must not remove
5715             any of the directories listed in 4.5, even if you created
5716             them.
5717           </p>
5718
5719           <p>
5720             Since <file>/usr/local</file> can be mounted read-only from a
5721             remote server, these directories must be created and
5722             removed by the <prgn>postinst</prgn> and <prgn>prerm</prgn>
5723             maintainer scripts and not be included in the
5724             <file>.deb</file> archive.  These scripts must not fail if
5725             either of these operations fail.
5726           </p>
5727
5728           <p>
5729             For example, the <tt>emacsen-common</tt> package could
5730             contain something like
5731             <example compact="compact">
5732 if [ ! -e /usr/local/share/emacs ]
5733 then
5734   if mkdir /usr/local/share/emacs 2>/dev/null
5735   then
5736     chown root:staff /usr/local/share/emacs
5737     chmod 2775 /usr/local/share/emacs
5738   fi
5739 fi
5740             </example>
5741             in its <prgn>postinst</prgn> script, and
5742             <example compact="compact">
5743 rmdir /usr/local/share/emacs/site-lisp 2>/dev/null || true
5744 rmdir /usr/local/share/emacs 2>/dev/null || true
5745             </example>
5746             in the <prgn>prerm</prgn> script.  (Note that this form is
5747             used to ensure that if the script is interrupted, the
5748             directory <file>/usr/local/share/emacs</file> will still be
5749             removed.)
5750           </p>
5751
5752           <p>
5753             If you do create a directory in <file>/usr/local</file> for
5754             local additions to a package, you should ensure that
5755             settings in <file>/usr/local</file> take precedence over the
5756             equivalents in <file>/usr</file>.
5757           </p>
5758
5759           <p>
5760             However, because <file>/usr/local</file> and its contents are
5761             for exclusive use of the local administrator, a package
5762             must not rely on the presence or absence of files or
5763             directories in <file>/usr/local</file> for normal operation.
5764           </p>
5765
5766           <p>
5767             The <file>/usr/local</file> directory itself and all the
5768             subdirectories created by the package should (by default) have
5769             permissions 2775 (group-writable and set-group-id) and be
5770             owned by <tt>root:staff</tt>.
5771           </p>
5772         </sect1>
5773
5774         <sect1>
5775           <heading>The system-wide mail directory</heading>
5776           <p>
5777             The system-wide mail directory
5778             is <file>/var/mail</file>. This directory is part of the
5779             base system and should not be owned by any particular mail
5780             agents.  The use of the old
5781             location <file>/var/spool/mail</file> is deprecated, even
5782             though the spool may still be physically located there.
5783           </p>
5784         </sect1>
5785       </sect>
5786
5787       <sect>
5788         <heading>Users and groups</heading>
5789
5790         <sect1>
5791           <heading>Introduction</heading>
5792           <p>
5793             The Debian system can be configured to use either plain or
5794             shadow passwords.
5795           </p>
5796
5797           <p>
5798             Some user ids (UIDs) and group ids (GIDs) are reserved
5799             globally for use by certain packages.  Because some
5800             packages need to include files which are owned by these
5801             users or groups, or need the ids compiled into binaries,
5802             these ids must be used on any Debian system only for the
5803             purpose for which they are allocated. This is a serious
5804             restriction, and we should avoid getting in the way of
5805             local administration policies. In particular, many sites
5806             allocate users and/or local system groups starting at 100.
5807           </p>
5808
5809           <p>
5810             Apart from this we should have dynamically allocated ids,
5811             which should by default be arranged in some sensible
5812             order, but the behavior should be configurable.
5813           </p>
5814
5815           <p>
5816             Packages other than <tt>base-passwd</tt> must not modify
5817             <file>/etc/passwd</file>, <file>/etc/shadow</file>,
5818             <file>/etc/group</file> or <file>/etc/gshadow</file>.
5819           </p>
5820         </sect1>
5821
5822         <sect1>
5823           <heading>UID and GID classes</heading>
5824           <p>
5825             The UID and GID numbers are divided into classes as
5826             follows:
5827             <taglist>
5828               <tag>0-99:</tag>
5829               <item>
5830                 <p>
5831                   Globally allocated by the Debian project, the same
5832                   on every Debian system.  These ids will appear in
5833                   the <file>passwd</file> and <file>group</file> files of all
5834                   Debian systems, new ids in this range being added
5835                   automatically as the <tt>base-passwd</tt> package is
5836                   updated.
5837                 </p>
5838
5839                 <p>
5840                   Packages which need a single statically allocated
5841                   uid or gid should use one of these; their
5842                   maintainers should ask the <tt>base-passwd</tt>
5843                   maintainer for ids.
5844                 </p>
5845               </item>
5846
5847               <tag>100-999:</tag>
5848               <item>
5849                 <p>
5850                   Dynamically allocated system users and groups.
5851                   Packages which need a user or group, but can have
5852                   this user or group allocated dynamically and
5853                   differently on each system, should use <tt>adduser
5854                   --system</tt> to create the group and/or user.
5855                   <prgn>adduser</prgn> will check for the existence of
5856                   the user or group, and if necessary choose an unused
5857                   id based on the ranges specified in
5858                   <file>adduser.conf</file>.
5859                 </p>
5860               </item>
5861
5862               <tag>1000-59999:</tag>
5863               <item>
5864                 <p>
5865                   Dynamically allocated user accounts.  By default
5866                   <prgn>adduser</prgn> will choose UIDs and GIDs for
5867                   user accounts in this range, though
5868                   <file>adduser.conf</file> may be used to modify this
5869                   behavior.
5870                 </p>
5871               </item>
5872
5873               <tag>60000-64999:</tag>
5874               <item>
5875                 <p>
5876                   Globally allocated by the Debian project, but only
5877                   created on demand. The ids are allocated centrally
5878                   and statically, but the actual accounts are only
5879                   created on users' systems on demand.
5880                 </p>
5881
5882                 <p>
5883                   These ids are for packages which are obscure or
5884                   which require many statically-allocated ids.  These
5885                   packages should check for and create the accounts in
5886                   <file>/etc/passwd</file> or <file>/etc/group</file> (using
5887                   <prgn>adduser</prgn> if it has this facility) if
5888                   necessary.  Packages which are likely to require
5889                   further allocations should have a "hole" left after
5890                   them in the allocation, to give them room to
5891                   grow.
5892                 </p>
5893               </item>
5894
5895               <tag>65000-65533:</tag>
5896               <item>
5897                 <p>Reserved.</p>
5898               </item>
5899
5900               <tag>65534:</tag>
5901               <item>
5902                 <p>
5903                   User <tt>nobody</tt>. The corresponding gid refers
5904                   to the group <tt>nogroup</tt>.
5905                 </p>
5906               </item>
5907
5908               <tag>65535:</tag>
5909               <item>
5910                 <p>
5911                   <tt>(uid_t)(-1) == (gid_t)(-1)</tt> <em>must
5912                   not</em> be used, because it is the error return
5913                   sentinel value.
5914                 </p>
5915               </item>
5916             </taglist>
5917           </p>
5918         </sect1>
5919       </sect>
5920
5921       <sect id="sysvinit">
5922         <heading>System run levels and <file>init.d</file> scripts</heading>
5923
5924         <sect1 id="/etc/init.d">
5925           <heading>Introduction</heading>
5926
5927           <p>
5928             The <file>/etc/init.d</file> directory contains the scripts
5929             executed by <prgn>init</prgn> at boot time and when the
5930             init state (or "runlevel") is changed (see <manref
5931             name="init" section="8">).
5932           </p>
5933
5934           <p>
5935             There are at least two different, yet functionally
5936             equivalent, ways of handling these scripts.  For the sake
5937             of simplicity, this document describes only the symbolic
5938             link method. However, it must not be assumed by maintainer
5939             scripts that this method is being used, and any automated
5940             manipulation of the various runlevel behaviors by
5941             maintainer scripts must be performed using
5942             <prgn>update-rc.d</prgn> as described below and not by
5943             manually installing or removing symlinks.  For information
5944             on the implementation details of the other method,
5945             implemented in the <tt>file-rc</tt> package, please refer
5946             to the documentation of that package.
5947           </p>
5948
5949           <p>
5950             These scripts are referenced by symbolic links in the
5951             <file>/etc/rc<var>n</var>.d</file> directories.  When changing
5952             runlevels, <prgn>init</prgn> looks in the directory
5953             <file>/etc/rc<var>n</var>.d</file> for the scripts it should
5954             execute, where <tt><var>n</var></tt> is the runlevel that
5955             is being changed to, or <tt>S</tt> for the boot-up
5956             scripts.
5957           </p>
5958
5959           <p>
5960             The names of the links all have the form
5961             <file>S<var>mm</var><var>script</var></file> or
5962             <file>K<var>mm</var><var>script</var></file> where
5963             <var>mm</var> is a two-digit number and <var>script</var>
5964             is the name of the script (this should be the same as the
5965             name of the actual script in <file>/etc/init.d</file>).
5966           </p>
5967
5968           <p>
5969             When <prgn>init</prgn> changes runlevel first the targets
5970             of the links whose names start with a <tt>K</tt> are
5971             executed, each with the single argument <tt>stop</tt>,
5972             followed by the scripts prefixed with an <tt>S</tt>, each
5973             with the single argument <tt>start</tt>.  (The links are
5974             those in the <file>/etc/rc<var>n</var>.d</file> directory
5975             corresponding to the new runlevel.)  The <tt>K</tt> links
5976             are responsible for killing services and the <tt>S</tt>
5977             link for starting services upon entering the runlevel.
5978           </p>
5979
5980           <p>
5981             For example, if we are changing from runlevel 2 to
5982             runlevel 3, init will first execute all of the <tt>K</tt>
5983             prefixed scripts it finds in <file>/etc/rc3.d</file>, and then
5984             all of the <tt>S</tt> prefixed scripts in that directory.
5985             The links starting with <tt>K</tt> will cause the
5986             referred-to file to be executed with an argument of
5987             <tt>stop</tt>, and the <tt>S</tt> links with an argument
5988             of <tt>start</tt>.
5989           </p>
5990
5991           <p>
5992             The two-digit number <var>mm</var> is used to determine
5993             the order in which to run the scripts: low-numbered links
5994             have their scripts run first.  For example, the
5995             <tt>K20</tt> scripts will be executed before the
5996             <tt>K30</tt> scripts.  This is used when a certain service
5997             must be started before another.  For example, the name
5998             server <prgn>bind</prgn> might need to be started before
5999             the news server <prgn>inn</prgn> so that <prgn>inn</prgn>
6000             can set up its access lists.  In this case, the script
6001             that starts <prgn>bind</prgn> would have a lower number
6002             than the script that starts <prgn>inn</prgn> so that it
6003             runs first:
6004             <example compact="compact">
6005 /etc/rc2.d/S17bind
6006 /etc/rc2.d/S70inn
6007             </example>
6008           </p>
6009
6010           <p>
6011             The two runlevels 0 (halt) and 6 (reboot) are slightly
6012             different.  In these runlevels, the links with an
6013             <tt>S</tt> prefix are still called after those with a
6014             <tt>K</tt> prefix, but they too are called with the single
6015             argument <tt>stop</tt>.
6016           </p>
6017         </sect1>
6018
6019         <sect1>
6020           <heading>Writing the scripts</heading>
6021
6022           <p>
6023             Packages that include daemons for system services should
6024             place scripts in <file>/etc/init.d</file> to start or stop
6025             services at boot time or during a change of runlevel.
6026             These scripts should be named
6027             <file>/etc/init.d/<var>package</var></file>, and they should
6028             accept one argument, saying what to do:
6029
6030             <taglist>
6031               <tag><tt>start</tt></tag>
6032               <item>start the service,</item>
6033
6034               <tag><tt>stop</tt></tag>
6035               <item>stop the service,</item>
6036
6037               <tag><tt>restart</tt></tag>
6038               <item>stop and restart the service if it's already running,
6039                   otherwise start the service</item>
6040
6041               <tag><tt>reload</tt></tag>
6042               <item><p>cause the configuration of the service to be
6043                   reloaded without actually stopping and restarting
6044                   the service,</item>
6045
6046               <tag><tt>force-reload</tt></tag>
6047               <item>cause the configuration to be reloaded if the
6048                   service supports this, otherwise restart the
6049                   service.</item>
6050             </taglist>
6051
6052             The <tt>start</tt>, <tt>stop</tt>, <tt>restart</tt>, and
6053             <tt>force-reload</tt> options should be supported by all
6054             scripts in <file>/etc/init.d</file>, the <tt>reload</tt>
6055             option is optional.
6056           </p>
6057
6058           <p>
6059             The <file>init.d</file> scripts must ensure that they will
6060             behave sensibly (i.e., returning success and not starting
6061             multiple copies of a service) if invoked with <tt>start</tt>
6062             when the service is already running, or with <tt>stop</tt>
6063             when it isn't, and that they don't kill unfortunately-named
6064             user processes.  The best way to achieve this is usually to
6065             use <prgn>start-stop-daemon</prgn> with the <tt>--oknodo</tt>
6066             option.
6067           </p>
6068
6069           <p>
6070             If a service reloads its configuration automatically (as
6071             in the case of <prgn>cron</prgn>, for example), the
6072             <tt>reload</tt> option of the <file>init.d</file> script
6073             should behave as if the configuration has been reloaded
6074             successfully.
6075           </p>
6076
6077           <p>
6078             The <file>/etc/init.d</file> scripts must be treated as
6079             configuration files, either (if they are present in the
6080             package, that is, in the .deb file) by marking them as
6081             <tt>conffile</tt>s, or, (if they do not exist in the .deb)
6082             by managing them correctly in the maintainer scripts (see
6083             <ref id="config-files">).  This is important since we want
6084             to give the local system administrator the chance to adapt
6085             the scripts to the local system, e.g., to disable a
6086             service without de-installing the package, or to specify
6087             some special command line options when starting a service,
6088             while making sure their changes aren't lost during the next
6089             package upgrade.
6090           </p>
6091
6092           <p>
6093             These scripts should not fail obscurely when the
6094             configuration files remain but the package has been
6095             removed, as configuration files remain on the system after
6096             the package has been removed.  Only when <prgn>dpkg</prgn>
6097             is executed with the <tt>--purge</tt> option will
6098             configuration files be removed.  In particular, as the
6099             <file>/etc/init.d/<var>package</var></file> script itself is
6100             usually a <tt>conffile</tt>, it will remain on the system
6101             if the package is removed but not purged.  Therefore, you
6102             should include a <tt>test</tt> statement at the top of the
6103             script, like this:
6104             <example compact="compact">
6105 test -f <var>program-executed-later-in-script</var> || exit 0
6106             </example>
6107           </p>
6108
6109           <p>
6110             Often there are some variables in the <file>init.d</file>
6111             scripts whose values control the behavior of the scripts,
6112             and which a system administrator is likely to want to
6113             change.  As the scripts themselves are frequently
6114             <tt>conffile</tt>s, modifying them requires that the
6115             administrator merge in their changes each time the package
6116             is upgraded and the <tt>conffile</tt> changes.  To ease
6117             the burden on the system administrator, such configurable
6118             values should not be placed directly in the script.
6119             Instead, they should be placed in a file in
6120             <file>/etc/default</file>, which typically will have the same
6121             base name as the <file>init.d</file> script.  This extra file
6122             should be sourced by the script when the script runs.  It
6123             must contain only variable settings and comments in SUSv3
6124             <prgn>sh</prgn> format.  It may either be a
6125             <tt>conffile</tt> or a configuration file maintained by
6126             the package maintainer scripts.  See <ref id="config-files">
6127             for more details.
6128           </p>
6129
6130           <p>
6131             To ensure that vital configurable values are always
6132             available, the <file>init.d</file> script should set default
6133             values for each of the shell variables it uses, either
6134             before sourcing the <file>/etc/default/</file> file or
6135             afterwards using something like the <tt>:
6136             ${VAR:=default}</tt> syntax.  Also, the <file>init.d</file>
6137             script must behave sensibly and not fail if the
6138             <file>/etc/default</file> file is deleted.
6139           </p>
6140
6141           <p>
6142             <file>/var/run</file> and <file>/var/lock</file> may be mounted
6143             as temporary filesystems<footnote>
6144                 For example, using the <tt>RAMRUN</tt> and <tt>RAMLOCK</tt>
6145                 options in <file>/etc/default/rcS</file>.
6146             </footnote>, so the <file>init.d</file> scripts must handle this
6147             correctly. This will typically amount to creating any required
6148             subdirectories dynamically when the <file>init.d</file> script
6149             is run, rather than including them in the package and relying on
6150             <prgn>dpkg</prgn> to create them.
6151           </p>
6152         </sect1>
6153
6154         <sect1>
6155           <heading>Interfacing with the initscript system</heading>
6156
6157           <p>
6158             Maintainers should use the abstraction layer provided by
6159             the <prgn>update-rc.d</prgn> and <prgn>invoke-rc.d</prgn>
6160             programs to deal with initscripts in their packages'
6161             scripts such as <prgn>postinst</prgn>, <prgn>prerm</prgn>
6162             and <prgn>postrm</prgn>.
6163           </p>
6164
6165           <p>
6166             Directly managing the /etc/rc?.d links and directly
6167             invoking the <file>/etc/init.d/</file> initscripts should
6168             be done only by packages providing the initscript
6169             subsystem (such as <prgn>sysv-rc</prgn> and
6170             <prgn>file-rc</prgn>).
6171           </p>
6172
6173           <sect2>
6174             <heading>Managing the links</heading>
6175
6176             <p>
6177               The program <prgn>update-rc.d</prgn> is provided for
6178               package maintainers to arrange for the proper creation and
6179               removal of <file>/etc/rc<var>n</var>.d</file> symbolic links,
6180               or their functional equivalent if another method is being
6181               used.  This may be used by maintainers in their packages'
6182               <prgn>postinst</prgn> and <prgn>postrm</prgn> scripts.
6183             </p>
6184
6185             <p>
6186               You must not include any <file>/etc/rc<var>n</var>.d</file>
6187               symbolic links in the actual archive or manually create or
6188               remove the symbolic links in maintainer scripts; you must
6189               use the <prgn>update-rc.d</prgn> program instead.  (The
6190               former will fail if an alternative method of maintaining
6191               runlevel information is being used.)  You must not include
6192               the <file>/etc/rc<var>n</var>.d</file> directories themselves
6193               in the archive either.  (Only the <tt>sysvinit</tt>
6194               package may do so.)
6195             </p>
6196
6197             <p>
6198               By default <prgn>update-rc.d</prgn> will start services in
6199               each of the multi-user state runlevels (2, 3, 4, and 5)
6200               and stop them in the halt runlevel (0), the single-user
6201               runlevel (1) and the reboot runlevel (6).  The system
6202               administrator will have the opportunity to customize
6203               runlevels by simply adding, moving, or removing the
6204               symbolic links in <file>/etc/rc<var>n</var>.d</file> if
6205               symbolic links are being used, or by modifying
6206               <file>/etc/runlevel.conf</file> if the <tt>file-rc</tt> method
6207               is being used.
6208             </p>
6209
6210             <p>
6211               To get the default behavior for your package, put in your
6212               <prgn>postinst</prgn> script
6213               <example compact="compact">
6214                 update-rc.d <var>package</var> defaults
6215               </example>
6216               and in your <prgn>postrm</prgn>
6217               <example compact="compact">
6218                 if [ "$1" = purge ]; then
6219                 update-rc.d <var>package</var> remove
6220                 fi
6221               </example>. Note that if your package changes runlevels
6222               or priority, you may have to remove and recreate the links,
6223               since otherwise the old links may persist. Refer to the
6224               documentation of <prgn>update-rc.d</prgn>.
6225             </p>
6226
6227             <p>
6228               This will use a default sequence number of 20.  If it does
6229               not matter when or in which order the <file>init.d</file>
6230               script is run, use this default.  If it does, then you
6231               should talk to the maintainer of the <prgn>sysvinit</prgn>
6232               package or post to <tt>debian-devel</tt>, and they will
6233               help you choose a number.
6234             </p>
6235
6236             <p>
6237               For more information about using <tt>update-rc.d</tt>,
6238               please consult its man page <manref name="update-rc.d"
6239                 section="8">.
6240             </p>
6241           </sect2>
6242
6243           <sect2>
6244             <heading>Running initscripts</heading>
6245             <p>
6246               The program <prgn>invoke-rc.d</prgn> is provided to make
6247               it easier for package maintainers to properly invoke an
6248               initscript, obeying runlevel and other locally-defined
6249               constraints that might limit a package's right to start,
6250               stop and otherwise manage services. This program may be
6251               used by maintainers in their packages' scripts.
6252             </p>
6253
6254             <p>
6255               The package maintainer scripts must use
6256               <prgn>invoke-rc.d</prgn> to invoke the
6257               <file>/etc/init.d/*</file> initscripts, instead of
6258               calling them directly.
6259             </p>
6260
6261             <p>
6262               By default, <prgn>invoke-rc.d</prgn> will pass any
6263               action requests (start, stop, reload, restart...) to the
6264               <file>/etc/init.d</file> script, filtering out requests
6265               to start or restart a service out of its intended
6266               runlevels.
6267             </p>
6268
6269             <p>
6270               Most packages will simply need to change:
6271               <example compact="compact">/etc/init.d/&lt;package&gt;
6272               &lt;action&gt;</example> in their <prgn>postinst</prgn>
6273               and <prgn>prerm</prgn> scripts to:
6274               <example compact="compact">
6275         if which invoke-rc.d >/dev/null 2>&1; then
6276                 invoke-rc.d <var>package</var> &lt;action&gt;
6277         else
6278                 /etc/init.d/<var>package</var> &lt;action&gt;
6279         fi
6280               </example>
6281             </p>
6282
6283             <p>
6284               A package should register its initscript services using
6285               <prgn>update-rc.d</prgn> before it tries to invoke them
6286               using <prgn>invoke-rc.d</prgn>. Invocation of
6287               unregistered services may fail.
6288             </p>
6289
6290             <p>
6291               For more information about using
6292               <prgn>invoke-rc.d</prgn>, please consult its man page
6293               <manref name="invoke-rc.d" section="8">.
6294             </p>
6295           </sect2>
6296         </sect1>
6297
6298         <sect1>
6299           <heading>Boot-time initialization</heading>
6300
6301           <p>
6302             There used to be another directory, <file>/etc/rc.boot</file>,
6303             which contained scripts which were run once per machine
6304             boot. This has been deprecated in favour of links from
6305             <file>/etc/rcS.d</file> to files in <file>/etc/init.d</file> as
6306             described in <ref id="/etc/init.d">.  Packages must not
6307             place files in <file>/etc/rc.boot</file>.
6308           </p>
6309         </sect1>
6310
6311         <sect1>
6312           <heading>Example</heading>
6313
6314           <p>
6315             An example on which you can base your
6316             <file>/etc/init.d</file> scripts is found in
6317             <file>/etc/init.d/skeleton</file>.
6318           </p>
6319
6320         </sect1>
6321       </sect>
6322
6323       <sect>
6324         <heading>Console messages from <file>init.d</file> scripts</heading>
6325
6326         <p>
6327           This section describes the formats to be used for messages
6328           written to standard output by the <file>/etc/init.d</file>
6329           scripts.  The intent is to improve the consistency of
6330           Debian's startup and shutdown look and feel.  For this
6331           reason, please look very carefully at the details.  We want
6332           the messages to have the same format in terms of wording,
6333           spaces, punctuation and case of letters.
6334         </p>
6335
6336         <p>
6337           Here is a list of overall rules that should be used for
6338           messages generated by <file>/etc/init.d</file> scripts.  
6339         </p>
6340
6341         <p>
6342           <list>
6343             <item>
6344                 The message should fit in one line (fewer than 80
6345                 characters), start with a capital letter and end with
6346                 a period (<tt>.</tt>) and line feed (<tt>"\n"</tt>).
6347             </item>
6348
6349             <item>
6350               If the script is performing some time consuming task in
6351               the background (not merely starting or stopping a
6352               program, for instance), an ellipsis (three dots:
6353               <tt>...</tt>) should be output to the screen, with no
6354               leading or tailing whitespace or line feeds.
6355             </item>
6356
6357             <item>
6358               The messages should appear as if the computer is telling
6359               the user what it is doing (politely :-), but should not
6360                 mention "it" directly.  For example, instead of:
6361                 <example compact="compact">
6362 I'm starting network daemons: nfsd mountd.
6363                 </example>
6364                 the message should say
6365                 <example compact="compact">
6366 Starting network daemons: nfsd mountd.
6367                 </example>
6368             </item>
6369           </list>
6370         </p>
6371
6372         <p>
6373           <tt>init.d</tt> script should use the following  standard
6374           message formats for the situations enumerated below.
6375         </p>
6376
6377         <p>
6378           <list>
6379             <item>
6380               <p>When daemons are started</p>
6381
6382               <p>
6383                 If the script starts one or more daemons, the output
6384                 should look like this (a single line, no leading
6385                 spaces):
6386                 <example compact="compact">
6387 Starting <var>description</var>: <var>daemon-1</var> ... <var>daemon-n</var>.
6388                 </example>
6389                 The <var>description</var> should describe the
6390                 subsystem the daemon or set of daemons are part of,
6391                 while <var>daemon-1</var> up to <var>daemon-n</var>
6392                 denote each daemon's name (typically the file name of
6393                 the program).
6394               </p>
6395
6396               <p>
6397                 For example, the output of <file>/etc/init.d/lpd</file>
6398                 would look like:
6399                 <example compact="compact">
6400 Starting printer spooler: lpd.
6401                 </example>
6402               </p>
6403
6404               <p>
6405                 This can be achieved by saying
6406                 <example compact="compact">
6407 echo -n "Starting printer spooler: lpd"
6408 start-stop-daemon --start --quiet --exec /usr/sbin/lpd
6409 echo "."
6410                 </example>
6411                 in the script. If there are more than one daemon to
6412                 start, the output should look like this:
6413                 <example compact="compact">
6414 echo -n "Starting remote file system services:"
6415 echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
6416 echo -n " mountd"; start-stop-daemon --start --quiet mountd
6417 echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
6418 echo "."
6419                 </example>
6420                 This makes it possible for the user to see what is
6421                 happening and when the final daemon has been started.
6422                 Care should be taken in the placement of white spaces:
6423                 in the example above the system administrators can
6424                 easily comment out a line if they don't want to start
6425                 a specific daemon, while the displayed message still
6426                 looks good.
6427               </p>
6428             </item>
6429
6430             <item>
6431               <p>When a system parameter is being set</p>
6432
6433               <p>
6434                 If you have to set up different system parameters
6435                 during the system boot, you should use this format:
6436                 <example compact="compact">
6437 Setting <var>parameter</var> to "<var>value</var>".
6438                 </example>
6439               </p>
6440
6441               <p>
6442                 You can use a statement such as the following to get
6443                 the quotes right:
6444                 <example compact="compact">
6445 echo "Setting DNS domainname to \"$domainname\"."
6446                 </example>
6447               </p>
6448
6449               <p>
6450                 Note that the same symbol (<tt>"</tt>) <!-- " --> is used
6451                 for the left and right quotation marks.  A grave accent
6452                 (<tt>`</tt>) is not a quote character; neither is an
6453                 apostrophe (<tt>'</tt>).
6454               </p>
6455             </item>
6456
6457             <item>
6458               <p>When a daemon is stopped or restarted</p>
6459
6460               <p>
6461                 When you stop or restart a daemon, you should issue a
6462                 message identical to the startup message, except that
6463                 <tt>Starting</tt> is replaced with <tt>Stopping</tt>
6464                 or <tt>Restarting</tt> respectively.
6465               </p>
6466
6467               <p>
6468                 For example, stopping the printer daemon will look like
6469                 this:
6470                 <example compact="compact">
6471 Stopping printer spooler: lpd.
6472                 </example>
6473               </p>
6474             </item>
6475
6476             <item>
6477               <p>When something is executed</p>
6478
6479               <p>
6480                 There are several examples where you have to run a
6481                 program at system startup or shutdown to perform a
6482                 specific task, for example, setting the system's clock
6483                 using <prgn>netdate</prgn> or killing all processes
6484                 when the system shuts down.  Your message should look
6485                 like this:
6486                 <example compact="compact">
6487 Doing something very useful...done.
6488                 </example>
6489                 You should print the <tt>done.</tt> immediately after
6490                 the job has been completed, so that the user is
6491                 informed why they have to wait.  You can get this
6492                 behavior by saying
6493                 <example compact="compact">
6494 echo -n "Doing something very useful..."
6495 do_something
6496 echo "done."
6497                 </example>
6498                 in your script.
6499               </p>
6500             </item>
6501
6502             <item>
6503               <p>When the configuration is reloaded</p>
6504
6505               <p>
6506                 When a daemon is forced to reload its configuration
6507                 files you should use the following format:
6508                 <example compact="compact">
6509 Reloading <var>description</var> configuration...done.
6510                 </example>
6511                 where <var>description</var> is the same as in the
6512                 daemon starting message.
6513               </p>
6514             </item>
6515           </list>
6516         </p>
6517       </sect>
6518
6519       <sect>
6520         <heading>Cron jobs</heading>
6521
6522         <p>
6523           Packages must not modify the configuration file
6524           <file>/etc/crontab</file>, and they must not modify the files in
6525           <file>/var/spool/cron/crontabs</file>.</p>
6526
6527         <p>
6528           If a package wants to install a job that has to be executed
6529           via cron, it should place a file with the name of the
6530           package in one or more of the following directories:
6531           <example compact="compact">
6532 /etc/cron.hourly
6533 /etc/cron.daily
6534 /etc/cron.weekly
6535 /etc/cron.monthly
6536           </example>
6537           As these directory names imply, the files within them are
6538           executed on an hourly, daily, weekly, or monthly basis,
6539           respectively. The exact times are listed in
6540           <file>/etc/crontab</file>.</p>
6541
6542         <p>
6543           All files installed in any of these directories must be
6544           scripts (e.g., shell scripts or Perl scripts) so that they
6545           can easily be modified by the local system administrator.
6546           In addition, they must be treated as configuration files.
6547         </p>
6548
6549         <p>
6550           If a certain job has to be executed at some other frequency or
6551           at a specific time, the package should install a file
6552           <file>/etc/cron.d/<var>package</var></file>. This file uses the
6553           same syntax as <file>/etc/crontab</file> and is processed by
6554           <prgn>cron</prgn> automatically. The file must also be
6555           treated as a configuration file. (Note that entries in the
6556           <file>/etc/cron.d</file> directory are not handled by
6557           <prgn>anacron</prgn>. Thus, you should only use this
6558           directory for jobs which may be skipped if the system is not
6559           running.)</p>
6560         <p>
6561           Unlike <file>crontab</file> files described in the IEEE Std
6562           1003.1-2008 (POSIX.1) available from
6563           <url id="http://www.opengroup.org/onlinepubs/9699919799/"
6564                name="The Open Group">, the files in
6565           <file>/etc/cron.d</file> and the file
6566           <file>/etc/crontab</file> have seven fields; namely:
6567           <enumlist>
6568             <item>Minute [0,59]</item>
6569             <item>Hour [0,23]</item>
6570             <item>Day of the month [1,31]</item>
6571             <item>Month of the year [1,12]</item>
6572             <item>Day of the week ([0,6] with 0=Sunday)</item>
6573             <item>Username</item>
6574             <item>Command to be run</item>
6575           </enumlist>
6576           Ranges of numbers are allowed.  Ranges are two numbers
6577           separated with a hyphen.  The specified range is inclusive.
6578           Lists are allowed.  A list is a set of numbers (or ranges)
6579           separated by commas. Step values can be used in conjunction
6580           with ranges.
6581         </p>
6582
6583         <p>
6584           The scripts or <tt>crontab</tt> entries in these directories should
6585           check if all necessary programs are installed before they
6586           try to execute them. Otherwise, problems will arise when a
6587           package was removed but not purged since configuration files
6588           are kept on the system in this situation.
6589         </p>
6590
6591         <p>
6592           Any <tt>cron</tt> daemon must provide
6593           <file>/usr/bin/crontab</file> and support normal
6594           <tt>crontab</tt> entries as specified in POSIX. The daemon
6595           must also support names for days and months, ranges, and
6596           step values. It has to support <file>/etc/crontab</file>,
6597           and correctly execute the scripts in
6598           <file>/etc/cron.d</file>. The daemon must also correctly
6599           execute scripts in
6600           <file>/etc/cron.{hourly,daily,weekly,monthly}</file>.
6601         </p>
6602       </sect>
6603
6604       <sect id="menus">
6605         <heading>Menus</heading>
6606
6607         <p>
6608           The Debian <tt>menu</tt> package provides a standard
6609           interface between packages providing applications and
6610           <em>menu programs</em> (either X window managers or
6611           text-based menu programs such as <prgn>pdmenu</prgn>).
6612         </p>
6613
6614         <p>
6615           All packages that provide applications that need not be
6616           passed any special command line arguments for normal
6617           operation should register a menu entry for those
6618           applications, so that users of the <tt>menu</tt> package
6619           will automatically get menu entries in their window
6620           managers, as well in shells like <tt>pdmenu</tt>.
6621         </p>
6622
6623         <p>
6624           Menu entries should follow the current menu policy.
6625         </p>
6626
6627         <p>
6628           The menu policy can be found in the <tt>menu-policy</tt>
6629           files in the <tt>debian-policy</tt> package.
6630           It is also available from the Debian web mirrors at
6631           <tt><url name="/doc/packaging-manuals/menu-policy/"
6632                 id="http://www.debian.org/doc/packaging-manuals/menu-policy/"></tt>.
6633         </p>
6634
6635         <p>
6636           Please also refer to the <em>Debian Menu System</em>
6637           documentation that comes with the <package>menu</package>
6638           package for information about how to register your
6639           applications.
6640         </p>
6641       </sect>
6642
6643       <sect id="mime">
6644         <heading>Multimedia handlers</heading>
6645
6646         <p>
6647           MIME (Multipurpose Internet Mail Extensions, RFCs 2045-2049)
6648           is a mechanism for encoding files and data streams and
6649           providing meta-information about them, in particular their
6650           type (e.g.  audio or video) and format (e.g. PNG, HTML,
6651           MP3).
6652         </p>
6653
6654         <p>
6655           Registration of MIME type handlers allows programs like mail
6656           user agents and web browsers to invoke these handlers to
6657           view, edit or display MIME types they don't support directly.
6658         </p>
6659
6660         <p>
6661           Packages which provide the ability to view/show/play,
6662           compose, edit or print MIME types should register themselves
6663           as such following the current MIME support policy.
6664         </p>
6665
6666         <p>
6667           The MIME support policy can be found in the <tt>mime-policy</tt>
6668           files in the <tt>debian-policy</tt> package.
6669           It is also available from the Debian web mirrors at
6670           <tt><url name="/doc/packaging-manuals/mime-policy/"
6671                 id="http://www.debian.org/doc/packaging-manuals/mime-policy/"></tt>.
6672         </p>
6673
6674       </sect>
6675
6676       <sect>
6677         <heading>Keyboard configuration</heading>
6678
6679         <p>
6680           To achieve a consistent keyboard configuration so that all
6681           applications interpret a keyboard event the same way, all
6682           programs in the Debian distribution must be configured to
6683           comply with the following guidelines.
6684         </p>
6685
6686         <p>
6687           The following keys must have the specified interpretations:
6688
6689           <taglist>
6690             <tag><tt>&lt;--</tt></tag>
6691             <item>delete the character to the left of the cursor</item>
6692
6693             <tag><tt>Delete</tt></tag>
6694             <item>delete the character to the right of the cursor</item>
6695
6696             <tag><tt>Control+H</tt></tag>
6697             <item>emacs: the help prefix</item>
6698           </taglist>
6699
6700           The interpretation of any keyboard events should be
6701           independent of the terminal that is used, be it a virtual
6702           console, an X terminal emulator, an rlogin/telnet session,
6703           etc.
6704         </p>
6705
6706         <p>
6707           The following list explains how the different programs
6708           should be set up to achieve this:
6709         </p>
6710
6711         <p>
6712           <list>
6713             <item>
6714                 <tt>&lt;--</tt> generates <tt>KB_BackSpace</tt> in X.
6715             </item>
6716
6717             <item>
6718                 <tt>Delete</tt> generates <tt>KB_Delete</tt> in X.
6719             </item>
6720
6721             <item>
6722                 X translations are set up to make
6723                 <tt>KB_Backspace</tt> generate ASCII DEL, and to make
6724                 <tt>KB_Delete</tt> generate <tt>ESC [ 3 ~</tt> (this
6725                 is the vt220 escape code for the "delete character"
6726                 key).  This must be done by loading the X resources
6727                 using <prgn>xrdb</prgn> on all local X displays, not
6728                 using the application defaults, so that the
6729                 translation resources used correspond to the
6730                 <prgn>xmodmap</prgn> settings.
6731             </item>
6732
6733             <item>
6734                 The Linux console is configured to make
6735                 <tt>&lt;--</tt> generate DEL, and <tt>Delete</tt>
6736                 generate <tt>ESC [ 3 ~</tt>.
6737             </item>
6738
6739             <item>
6740                 X applications are configured so that <tt>&lt;</tt>
6741                 deletes left, and <tt>Delete</tt> deletes right.  Motif
6742                 applications already work like this.
6743             </item>
6744
6745             <item>
6746                 Terminals should have <tt>stty erase ^?</tt> .
6747             </item>
6748
6749             <item>
6750                 The <tt>xterm</tt> terminfo entry should have <tt>ESC
6751                 [ 3 ~</tt> for <tt>kdch1</tt>, just as for
6752                 <tt>TERM=linux</tt> and <tt>TERM=vt220</tt>.
6753             </item>
6754
6755             <item>
6756                 Emacs is programmed to map <tt>KB_Backspace</tt> or
6757                 the <tt>stty erase</tt> character to
6758                 <tt>delete-backward-char</tt>, and <tt>KB_Delete</tt>
6759                 or <tt>kdch1</tt> to <tt>delete-forward-char</tt>, and
6760                 <tt>^H</tt> to <tt>help</tt> as always.
6761             </item>
6762
6763             <item>
6764                 Other applications use the <tt>stty erase</tt>
6765                 character and <tt>kdch1</tt> for the two delete keys,
6766                 with ASCII DEL being "delete previous character" and
6767                 <tt>kdch1</tt> being "delete character under
6768                 cursor".
6769             </item>
6770
6771           </list>
6772         </p>
6773
6774         <p>
6775           This will solve the problem except for the following
6776           cases:
6777         </p>
6778
6779         <p>
6780           <list>
6781             <item>
6782                 Some terminals have a <tt>&lt;--</tt> key that cannot
6783                 be made to produce anything except <tt>^H</tt>.  On
6784                 these terminals Emacs help will be unavailable on
6785                 <tt>^H</tt> (assuming that the <tt>stty erase</tt>
6786                 character takes precedence in Emacs, and has been set
6787                 correctly).  <tt>M-x help</tt> or <tt>F1</tt> (if
6788                 available) can be used instead.
6789             </item>
6790
6791             <item>
6792                 Some operating systems use <tt>^H</tt> for <tt>stty
6793                 erase</tt>.  However, modern telnet versions and all
6794                 rlogin versions propagate <tt>stty</tt> settings, and
6795                 almost all UNIX versions honour <tt>stty erase</tt>.
6796                 Where the <tt>stty</tt> settings are not propagated
6797                 correctly, things can be made to work by using
6798                 <tt>stty</tt> manually.
6799             </item>
6800
6801             <item>
6802                 Some systems (including previous Debian versions) use
6803                 <prgn>xmodmap</prgn> to arrange for both
6804                 <tt>&lt;--</tt> and <tt>Delete</tt> to generate
6805                 <tt>KB_Delete</tt>.  We can change the behavior of
6806                 their X clients using the same X resources that we use
6807                 to do it for our own clients, or configure our clients
6808                 using their resources when things are the other way
6809                 around.  On displays configured like this
6810                 <tt>Delete</tt> will not work, but <tt>&lt;--</tt>
6811                 will.
6812             </item>
6813
6814             <item>
6815                 Some operating systems have different <tt>kdch1</tt>
6816                 settings in their <tt>terminfo</tt> database for
6817                 <tt>xterm</tt> and others.  On these systems the
6818                 <tt>Delete</tt> key will not work correctly when you
6819                 log in from a system conforming to our policy, but
6820                 <tt>&lt;--</tt> will.
6821             </item>
6822           </list>
6823         </p>
6824       </sect>
6825
6826       <sect>
6827         <heading>Environment variables</heading>
6828
6829         <p>
6830           A program must not depend on environment variables to get
6831           reasonable defaults.  (That's because these environment
6832           variables would have to be set in a system-wide
6833           configuration file like <file>/etc/profile</file>, which is not
6834           supported by all shells.)
6835         </p>
6836
6837         <p>
6838           If a program usually depends on environment variables for its
6839           configuration, the program should be changed to fall back to
6840           a reasonable default configuration if these environment
6841           variables are not present. If this cannot be done easily
6842           (e.g., if the source code of a non-free program is not
6843           available), the program must be replaced by a small
6844           "wrapper" shell script which sets the environment variables
6845           if they are not already defined, and calls the original program.
6846         </p>
6847
6848         <p>
6849           Here is an example of a wrapper script for this purpose:
6850
6851           <example compact="compact">
6852 #!/bin/sh
6853 BAR=${BAR:-/var/lib/fubar}
6854 export BAR
6855 exec /usr/lib/foo/foo "$@"
6856           </example>
6857         </p>
6858
6859         <p>
6860           Furthermore, as <file>/etc/profile</file> is a configuration
6861           file of the <prgn>base-files</prgn> package, other packages must
6862           not put any environment variables or other commands into that
6863           file.
6864         </p>
6865       </sect>
6866
6867       <sect id="doc-base">
6868         <heading>Registering Documents using doc-base</heading>
6869
6870         <p>
6871           The <package>doc-base</package> package implements a
6872           flexible mechanism for handling and presenting
6873           documentation. The recommended practice is for every Debian
6874           package that provides online documentation (other than just
6875           manual pages) to register these documents with
6876           <package>doc-base</package> by installing a
6877           <package>doc-base</package> control file via the
6878           <prgn/install-docs/ script at installation time and
6879           de-register the manuals again when the package is removed.
6880         </p> 
6881         <p>
6882           Please refer to the documentation that comes with the
6883           <package>doc-base</package>  package for information and
6884           details. 
6885         </p>
6886       </sect>
6887
6888     </chapt>
6889
6890
6891     <chapt id="files">
6892       <heading>Files</heading>
6893
6894       <sect>
6895         <heading>Binaries</heading>
6896
6897         <p>
6898           Two different packages must not install programs with
6899           different functionality but with the same filenames.  (The
6900           case of two programs having the same functionality but
6901           different implementations is handled via "alternatives" or
6902           the "Conflicts" mechanism.  See <ref id="maintscripts"> and
6903           <ref id="conflicts"> respectively.)  If this case happens,
6904           one of the programs must be renamed.  The maintainers should
6905           report this to the <tt>debian-devel</tt> mailing list and
6906           try to find a consensus about which program will have to be
6907           renamed.  If a consensus cannot be reached, <em>both</em>
6908           programs must be renamed.
6909         </p>
6910
6911         <p>
6912          By default, when a package is being built, any binaries
6913          created should include debugging information, as well as
6914          being compiled with optimization.  You should also turn on
6915          as many reasonable compilation warnings as possible; this
6916          makes life easier for porters, who can then look at build
6917          logs for possible problems.  For the C programming language,
6918          this means the following compilation parameters should be
6919          used:
6920           <example compact="compact">
6921 CC = gcc
6922 CFLAGS = -O2 -g -Wall # sane warning options vary between programs
6923 LDFLAGS = # none
6924 INSTALL = install -s # (or use strip on the files in debian/tmp)
6925           </example>
6926         </p>
6927
6928         <p>
6929           Note that by default all installed binaries should be stripped,
6930           either by using the <tt>-s</tt> flag to
6931           <prgn>install</prgn>, or by calling <prgn>strip</prgn> on
6932           the binaries after they have been copied into
6933           <file>debian/tmp</file> but before the tree is made into a
6934           package.
6935         </p>
6936
6937         <p>
6938           Although binaries in the build tree should be compiled with
6939           debugging information by default, it can often be difficult to
6940           debug programs if they are also subjected to compiler
6941           optimization.  For this reason, it is recommended to support the
6942           standardized environment variable <tt>DEB_BUILD_OPTIONS</tt>
6943           (see <ref id="debianrules-options">).  This variable can contain
6944           several flags to change how a package is compiled and built.
6945         </p>
6946
6947         <p>
6948           It is up to the package maintainer to decide what
6949           compilation options are best for the package.  Certain
6950           binaries (such as computationally-intensive programs) will
6951           function better with certain flags (<tt>-O3</tt>, for
6952           example); feel free to use them.  Please use good judgment
6953           here.  Don't use flags for the sake of it; only use them
6954           if there is good reason to do so.  Feel free to override
6955           the upstream author's ideas about which compilation
6956           options are best: they are often inappropriate for our
6957           environment.
6958         </p>
6959       </sect>
6960
6961
6962       <sect id="libraries">
6963         <heading>Libraries</heading>
6964
6965         <p>
6966           If the package is <strong>architecture: any</strong>, then
6967           the shared library compilation and linking flags must have
6968           <tt>-fPIC</tt>, or the package shall not build on some of
6969           the supported architectures<footnote>
6970             <p>
6971               If you are using GCC, <tt>-fPIC</tt> produces code with
6972               relocatable position independent code, which is required for
6973               most architectures to create a shared library, with i386 and
6974               perhaps some others where non position independent code is
6975               permitted in a shared library.
6976             </p>
6977             <p>
6978               Position independent code may have a performance penalty,
6979               especially on <tt>i386</tt>. However, in most cases the
6980               speed penalty must be measured against the memory wasted on
6981               the few architectures where non position independent code is
6982               even possible.
6983             </p>
6984           </footnote>. Any exception to this rule must be discussed on
6985           the mailing list <em>debian-devel@lists.debian.org</em>, and
6986           a rough consensus obtained.  The reasons for not compiling
6987           with <tt>-fPIC</tt> flag must be recorded in the file
6988           <tt>README.Debian</tt>, and care must be taken to either
6989           restrict the architecture or arrange for <tt>-fPIC</tt> to
6990           be used on architectures where it is required.<footnote>
6991             <p>
6992               Some of the reasons why this might be required is if the
6993               library contains hand crafted assembly code that is not
6994               relocatable, the speed penalty is excessive for compute
6995               intensive libs, and similar reasons.
6996             </p>
6997           </footnote>
6998         </p>
6999         <p>
7000           As to the static libraries, the common case is not to have
7001           relocatable code, since there is no benefit, unless in specific
7002           cases; therefore the static version must not be compiled
7003           with the <tt>-fPIC</tt> flag. Any exception to this rule
7004           should be discussed on the mailing list
7005           <em>debian-devel@lists.debian.org</em>,  and the reasons for
7006           compiling with the <tt>-fPIC</tt> flag must be recorded in
7007           the file <tt>README.Debian</tt>. <footnote>
7008             <p>
7009               Some of the reasons for linking static libraries with
7010               the <tt>-fPIC</tt> flag are if, for example, one needs a
7011               Perl API for a library that is under rapid development,
7012               and has an unstable API, so shared libraries are
7013               pointless at this phase of the library's development. In
7014               that case, since Perl needs a library with relocatable
7015               code, it may make sense to create a static library with
7016               relocatable code. Another reason cited is if you are
7017               distilling various libraries into a common shared
7018               library, like <tt>mklibs</tt> does in the Debian
7019               installer project.
7020             </p>
7021           </footnote>
7022         </p>
7023         <p>
7024           In other words, if both a shared and a static library is
7025           being built, each source unit (<tt>*.c</tt>, for example,
7026           for C files) will need to be compiled twice, for the normal
7027           case. 
7028         </p>
7029         <p>
7030           You must specify the gcc option <tt>-D_REENTRANT</tt>
7031           when building a library (either static or shared) to make
7032           the library compatible with LinuxThreads.
7033         </p>
7034
7035         <p>
7036           Although not enforced by the build tools, shared libraries
7037           must be linked against all libraries that they use symbols from
7038           in the same way that binaries are.  This ensures the correct
7039           functioning of the <qref id="sharedlibs-shlibdeps">shlibs</qref>
7040           system and guarantees that all libraries can be safely opened
7041           with <tt>dlopen()</tt>.  Packagers may wish to use the gcc
7042           option <tt>-Wl,-z,defs</tt> when building a shared library.
7043           Since this option enforces symbol resolution at build time,
7044           a missing library reference will be caught early as a fatal
7045           build error.
7046         </p>
7047
7048         <p>
7049           All installed shared libraries should be stripped with
7050           <example compact="compact">
7051 strip --strip-unneeded <var>your-lib</var>
7052           </example>
7053           (The option <tt>--strip-unneeded</tt> makes
7054           <prgn>strip</prgn> remove only the symbols which aren't
7055           needed for relocation processing.)  Shared libraries can
7056           function perfectly well when stripped, since the symbols for
7057           dynamic linking are in a separate part of the ELF object
7058           file.<footnote>
7059               You might also want to use the options
7060               <tt>--remove-section=.comment</tt> and
7061               <tt>--remove-section=.note</tt> on both shared libraries
7062               and executables, and <tt>--strip-debug</tt> on static
7063               libraries.
7064           </footnote>
7065         </p>
7066
7067         <p>
7068           Note that under some circumstances it may be useful to
7069           install a shared library unstripped, for example when
7070           building a separate package to support debugging.
7071         </p>
7072
7073         <p>
7074           Shared object files (often <file>.so</file> files) that are not
7075           public libraries, that is, they are not meant to be linked
7076           to by third party executables (binaries of other packages),
7077           should be installed in subdirectories of the
7078           <file>/usr/lib</file> directory.  Such files are exempt from the
7079           rules that govern ordinary shared libraries, except that
7080           they must not be installed executable and should be
7081           stripped.<footnote>
7082               A common example are the so-called "plug-ins",
7083               internal shared objects that are dynamically loaded by
7084               programs using <manref name="dlopen" section="3">.
7085           </footnote>
7086         </p>
7087
7088         <p>
7089           An ever increasing number of packages are using
7090           <prgn>libtool</prgn> to do their linking.  The latest GNU
7091           libtools (>= 1.3a) can take advantage of the metadata in the
7092           installed <prgn>libtool</prgn> archive files (<file>*.la</file>
7093           files).  The main advantage of <prgn>libtool</prgn>'s
7094           <file>.la</file> files is that it allows <prgn>libtool</prgn> to
7095           store and subsequently access metadata with respect to the
7096           libraries it builds.  <prgn>libtool</prgn> will search for
7097           those files, which contain a lot of useful information about
7098           a library (such as library dependency information for static
7099           linking).  Also, they're <em>essential</em> for programs
7100           using <tt>libltdl</tt>.<footnote>
7101               Although <prgn>libtool</prgn> is fully capable of
7102               linking against shared libraries which don't have
7103               <tt>.la</tt> files, as it is a mere shell script it can
7104               add considerably to the build time of a
7105               <prgn>libtool</prgn>-using package if that shell script
7106               has to derive all this information from first principles
7107               for each library every time it is linked.  With the
7108               advent of <prgn>libtool</prgn> version 1.4 (and to a
7109               lesser extent <prgn>libtool</prgn> version 1.3), the
7110               <file>.la</file> files also store information about
7111               inter-library dependencies which cannot necessarily be
7112               derived after the <file>.la</file> file is deleted.
7113           </footnote>
7114         </p>
7115
7116         <p>
7117           Packages that use <prgn>libtool</prgn> to create shared
7118           libraries should include the <file>.la</file> files in the
7119           <tt>-dev</tt> package, unless the package relies on
7120           <tt>libtool</tt>'s <tt>libltdl</tt> library, in which case
7121           the <tt>.la</tt> files must go in the run-time library
7122           package.
7123         </p>
7124
7125         <p>
7126           You must make sure that you use only released versions of
7127           shared libraries to build your packages; otherwise other
7128           users will not be able to run your binaries
7129           properly. Producing source packages that depend on
7130           unreleased compilers is also usually a bad
7131           idea.
7132         </p>
7133       </sect>
7134
7135
7136       <sect>
7137         <heading>Shared libraries</heading>
7138         <p>
7139           This section has moved to <ref id="sharedlibs">.
7140         </p>
7141       </sect>
7142
7143
7144       <sect id="scripts">
7145         <heading>Scripts</heading>
7146
7147         <p>
7148           All command scripts, including the package maintainer
7149           scripts inside the package and used by <prgn>dpkg</prgn>,
7150           should have a <tt>#!</tt> line naming the shell to be used
7151           to interpret them.
7152         </p>
7153
7154         <p>
7155           In the case of Perl scripts this should be
7156           <tt>#!/usr/bin/perl</tt>.
7157         </p>
7158
7159         <p>
7160           When scripts are installed into a directory in the system
7161           PATH, the script name should not include an extension such
7162           as <tt>.sh</tt> or <tt>.pl</tt> that denotes the scripting
7163           language currently used to implement it.
7164         </p>
7165         <p>
7166           Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>)
7167           should almost certainly start with <tt>set -e</tt> so that
7168           errors are detected.  Every script should use
7169           <tt>set -e</tt> or check the exit status of <em>every</em>
7170           command.
7171         </p>
7172
7173         <p>
7174           Scripts may assume that <file>/bin/sh</file> implements the
7175           SUSv3 Shell Command Language<footnote>
7176             Single UNIX Specification, version 3, which is also IEEE
7177             1003.1-2004 (POSIX), and is available on the World Wide Web
7178             from <url id="http://www.unix.org/version3/online.html"
7179                       name="The Open Group"> after free
7180             registration.</footnote>
7181           plus the following additional features not mandated by
7182           SUSv3:<footnote>
7183             These features are in widespread use in the Linux community
7184             and are implemented in all of bash, dash, and ksh, the most
7185             common shells users may wish to use as <file>/bin/sh</file>.
7186           </footnote>
7187           <list>
7188             <item><tt>echo -n</tt>, if implemented as a shell built-in,
7189               must not generate a newline.</item>
7190             <item><tt>test</tt>, if implemented as a shell built-in, must
7191               support <tt>-a</tt> and <tt>-o</tt> as binary logical
7192               operators.</item>
7193             <item><tt>local</tt> to create a scoped variable must be
7194               supported, including listing multiple variables in a single
7195               local command and assigning a value to a variable at the
7196               same time as localizing it.  <tt>local</tt> may or
7197               may not preserve the variable value from an outer scope if
7198               no assignment is present.  Uses such as:
7199 <example compact>
7200 fname () {
7201     local a b c=delta d
7202     # ... use a, b, c, d ...
7203 }
7204 </example>
7205               must be supported and must set the value of <tt>c</tt> to
7206               <tt>delta</tt>.
7207             </item>
7208           </list>
7209           If a shell script requires non-SUSv3 features from the shell
7210           interpreter other than those listed above, the appropriate shell
7211           must be specified in the first line of the script (e.g.,
7212           <tt>#!/bin/bash</tt>) and the package must depend on the package
7213           providing the shell (unless the shell package is marked
7214           "Essential", as in the case of <prgn>bash</prgn>).
7215         </p>
7216
7217         <p>
7218           You may wish to restrict your script to SUSv3 features plus the
7219           above set when possible so that it may use <file>/bin/sh</file>
7220           as its interpreter. If your script works with <prgn>dash</prgn>
7221           (originally called <prgn>ash</prgn>), it probably complies with
7222           the above requirements, but if you are in doubt, use
7223           <file>/bin/bash</file>.
7224         </p>
7225
7226         <p>
7227           Perl scripts should check for errors when making any
7228           system calls, including <tt>open</tt>, <tt>print</tt>,
7229           <tt>close</tt>, <tt>rename</tt> and <tt>system</tt>.
7230         </p>
7231
7232         <p>
7233           <prgn>csh</prgn> and <prgn>tcsh</prgn> should be avoided as
7234           scripting languages.  See <em>Csh Programming Considered
7235           Harmful</em>, one of the <tt>comp.unix.*</tt> FAQs, which
7236           can be found at <url id="http://www.faqs.org/faqs/unix-faq/shell/csh-whynot/">.
7237           If an upstream package comes with <prgn>csh</prgn> scripts
7238           then you must make sure that they start with
7239           <tt>#!/bin/csh</tt> and make your package depend on the
7240           <prgn>c-shell</prgn> virtual package.
7241         </p>
7242
7243         <p>
7244           Any scripts which create files in world-writeable
7245           directories (e.g., in <file>/tmp</file>) must use a
7246           mechanism which will fail atomically if a file with the same
7247           name already exists.
7248         </p>
7249
7250         <p>
7251           The Debian base system provides the <prgn>tempfile</prgn>
7252           and <prgn>mktemp</prgn> utilities for use by scripts for
7253           this purpose.
7254         </p>
7255       </sect>
7256
7257
7258       <sect>
7259         <heading>Symbolic links</heading>
7260
7261         <p>
7262           In general, symbolic links within a top-level directory
7263           should be relative, and symbolic links pointing from one
7264           top-level directory into another should be absolute. (A
7265           top-level directory is a sub-directory of the root
7266           directory <file>/</file>.)
7267         </p>
7268
7269         <p>
7270           In addition, symbolic links should be specified as short as
7271           possible, i.e., link targets like <file>foo/../bar</file> are
7272           deprecated.
7273         </p>
7274
7275         <p>
7276           Note that when creating a relative link using
7277           <prgn>ln</prgn> it is not necessary for the target of the
7278           link to exist relative to the working directory you're
7279           running <prgn>ln</prgn> from, nor is it necessary to change
7280           directory to the directory where the link is to be made.
7281           Simply include the string that should appear as the target
7282           of the link (this will be a pathname relative to the
7283           directory in which the link resides) as the first argument
7284           to <prgn>ln</prgn>.
7285         </p>
7286
7287         <p>
7288           For example, in your <prgn>Makefile</prgn> or
7289           <file>debian/rules</file>, you can do things like:
7290           <example compact="compact">
7291 ln -fs gcc $(prefix)/bin/cc
7292 ln -fs gcc debian/tmp/usr/bin/cc
7293 ln -fs ../sbin/sendmail $(prefix)/bin/runq
7294 ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
7295           </example>
7296         </p>
7297
7298         <p>
7299           A symbolic link pointing to a compressed file should always
7300           have the same file extension as the referenced file. (For
7301           example, if a file <file>foo.gz</file> is referenced by a
7302           symbolic link, the filename of the link has to end with
7303           "<file>.gz</file>" too, as in <file>bar.gz</file>.)
7304         </p>
7305       </sect>
7306
7307       <sect>
7308         <heading>Device files</heading>
7309
7310         <p>
7311           Packages must not include device files or named pipes in the
7312           package file tree.
7313         </p>
7314
7315         <p>
7316           If a package needs any special device files that are not
7317           included in the base system, it must call
7318           <prgn>MAKEDEV</prgn> in the <prgn>postinst</prgn> script,
7319           after notifying the user<footnote>
7320               This notification could be done via a (low-priority)
7321               debconf message, or an echo (printf) statement.
7322           </footnote>.
7323         </p>
7324
7325         <p>
7326           Packages must not remove any device files in the
7327           <prgn>postrm</prgn> or any other script. This is left to the
7328           system administrator.
7329         </p>
7330
7331         <p>
7332           Debian uses the serial devices
7333           <file>/dev/ttyS*</file>. Programs using the old
7334           <file>/dev/cu*</file> devices should be changed to use
7335           <file>/dev/ttyS*</file>.
7336         </p>
7337
7338         <p>
7339           Named pipes needed by the package must be created in
7340           the <prgn>postinst</prgn> script<footnote>
7341             It's better to use <prgn>mkfifo</prgn> rather
7342             than <prgn>mknod</prgn> to create named pipes so that
7343             automated checks for packages incorrectly creating device
7344             files with <prgn>mknod</prgn> won't have false positives.
7345           </footnote> and removed in
7346           the <prgn>prerm</prgn> or <prgn>postrm</prgn> script as
7347           appropriate.
7348         </p>
7349       </sect>
7350
7351       <sect id="config-files">
7352         <heading>Configuration files</heading>
7353
7354         <sect1>
7355           <heading>Definitions</heading>
7356
7357           <p>
7358             <taglist>
7359               <tag>configuration file</tag>
7360               <item>
7361                   A file that affects the operation of a program, or
7362                   provides site- or host-specific information, or
7363                   otherwise customizes the behavior of a program.
7364                   Typically, configuration files are intended to be
7365                   modified by the system administrator (if needed or
7366                   desired) to conform to local policy or to provide
7367                   more useful site-specific behavior.
7368               </item>
7369
7370               <tag><tt>conffile</tt></tag>
7371               <item>
7372                   A file listed in a package's <tt>conffiles</tt>
7373                   file, and is treated specially by <prgn>dpkg</prgn>
7374                   (see <ref id="configdetails">).
7375               </item>
7376             </taglist>
7377           </p>
7378
7379           <p>
7380             The distinction between these two is important; they are
7381             not interchangeable concepts. Almost all
7382             <tt>conffile</tt>s are configuration files, but many
7383             configuration files are not <tt>conffiles</tt>.
7384           </p>
7385
7386           <p>
7387             As noted elsewhere, <file>/etc/init.d</file> scripts,
7388             <file>/etc/default</file> files, scripts installed in
7389             <file>/etc/cron.{hourly,daily,weekly,monthly}</file>, and cron
7390             configuration installed in <file>/etc/cron.d</file> must be
7391             treated as configuration files.  In general, any script that
7392             embeds configuration information is de-facto a configuration
7393             file and should be treated as such.
7394           </p>
7395         </sect1>
7396
7397         <sect1>
7398           <heading>Location</heading>
7399
7400           <p>
7401             Any configuration files created or used by your package
7402             must reside in <file>/etc</file>. If there are several,
7403             consider creating a subdirectory of <file>/etc</file>
7404             named after your package.
7405           </p>
7406
7407           <p>
7408             If your package creates or uses configuration files
7409             outside of <file>/etc</file>, and it is not feasible to modify
7410             the package to use <file>/etc</file> directly, put the files
7411             in <file>/etc</file> and create symbolic links to those files
7412             from the location that the package requires.
7413           </p>
7414         </sect1>
7415
7416         <sect1>
7417           <heading>Behavior</heading>
7418
7419           <p>
7420             Configuration file handling must conform to the following
7421             behavior:
7422             <list compact="compact">
7423               <item>
7424                   local changes must be preserved during a package
7425                   upgrade, and
7426               </item>
7427               <item>
7428                   configuration files must be preserved when the
7429                   package is removed, and only deleted when the
7430                   package is purged.
7431               </item>
7432             </list>
7433           </p>
7434
7435           <p>
7436             The easy way to achieve this behavior is to make the
7437             configuration file a <tt>conffile</tt>. This is
7438             appropriate only if it is possible to distribute a default
7439             version that will work for most installations, although
7440             some system administrators may choose to modify it. This
7441             implies that the default version will be part of the
7442             package distribution, and must not be modified by the
7443             maintainer scripts during installation (or at any other
7444             time).
7445           </p>
7446
7447           <p>
7448             In order to ensure that local changes are preserved
7449             correctly, no package may contain or make hard links to
7450             conffiles.<footnote>
7451                 Rationale: There are two problems with hard links.
7452                 The first is that some editors break the link while
7453                 editing one of the files, so that the two files may
7454                 unwittingly become unlinked and different.  The second
7455                 is that <prgn>dpkg</prgn> might break the hard link
7456                 while upgrading <tt>conffile</tt>s.
7457             </footnote>
7458           </p>
7459
7460           <p>
7461             The other way to do it is via the maintainer scripts.  In
7462             this case, the configuration file must not be listed as a
7463             <tt>conffile</tt> and must not be part of the package
7464             distribution. If the existence of a file is required for
7465             the package to be sensibly configured it is the
7466             responsibility of the package maintainer to provide
7467             maintainer scripts which correctly create, update and
7468             maintain the file and remove it on purge.  (See <ref
7469             id="maintainerscripts"> for more information.)  These
7470             scripts must be idempotent (i.e., must work correctly if
7471             <prgn>dpkg</prgn> needs to re-run them due to errors
7472             during installation or removal), must cope with all the
7473             variety of ways <prgn>dpkg</prgn> can call maintainer
7474             scripts, must not overwrite or otherwise mangle the user's
7475             configuration without asking, must not ask unnecessary
7476             questions (particularly during upgrades), and must
7477             otherwise be good citizens.
7478           </p>
7479
7480           <p>
7481             The scripts are not required to configure every possible
7482             option for the package, but only those necessary to get
7483             the package running on a given system. Ideally the
7484             sysadmin should not have to do any configuration other
7485             than that done (semi-)automatically by the
7486             <prgn>postinst</prgn> script.
7487           </p>
7488
7489           <p>
7490             A common practice is to create a script called
7491             <file><var>package</var>-configure</file> and have the
7492             package's <prgn>postinst</prgn> call it if and only if the
7493             configuration file does not already exist.  In certain
7494             cases it is useful for there to be an example or template
7495             file which the maintainer scripts use.  Such files should
7496             be in <file>/usr/share/<var>package</var></file> or
7497             <file>/usr/lib/<var>package</var></file> (depending on whether
7498             they are architecture-independent or not).  There should
7499             be symbolic links to them from
7500             <file>/usr/share/doc/<var>package</var>/examples</file> if
7501             they are examples, and should be perfectly ordinary
7502             <prgn>dpkg</prgn>-handled files (<em>not</em>
7503             configuration files).
7504           </p>
7505
7506           <p>
7507             These two styles of configuration file handling must
7508             not be mixed, for that way lies madness:
7509             <prgn>dpkg</prgn> will ask about overwriting the file
7510             every time the package is upgraded.
7511           </p>
7512         </sect1>
7513
7514         <sect1>
7515           <heading>Sharing configuration files</heading>
7516
7517           <p>
7518             Packages which specify the same file as a
7519             <tt>conffile</tt> must be tagged as <em>conflicting</em>
7520             with each other.  (This is an instance of the general rule
7521             about not sharing files.  Note that neither alternatives
7522             nor diversions are likely to be appropriate in this case;
7523             in particular, <prgn>dpkg</prgn> does not handle diverted
7524             <tt>conffile</tt>s well.)
7525           </p>
7526
7527           <p>
7528             The maintainer scripts must not alter a <tt>conffile</tt>
7529             of <em>any</em> package, including the one the scripts
7530             belong to.
7531           </p>
7532
7533           <p>
7534             If two or more packages use the same configuration file
7535             and it is reasonable for both to be installed at the same
7536             time, one of these packages must be defined as
7537             <em>owner</em> of the configuration file, i.e., it will be
7538             the package which handles that file as a configuration
7539             file.  Other packages that use the configuration file must
7540             depend on the owning package if they require the
7541             configuration file to operate. If the other package will
7542             use the configuration file if present, but is capable of
7543             operating without it, no dependency need be declared.
7544           </p>
7545
7546           <p>
7547             If it is desirable for two or more related packages to
7548             share a configuration file <em>and</em> for all of the
7549             related packages to be able to modify that configuration
7550             file, then the following should be done:
7551             <enumlist compact="compact">
7552               <item>
7553                   One of the related packages (the "owning" package)
7554                   will manage the configuration file with maintainer
7555                   scripts as described in the previous section.
7556               </item>
7557               <item>
7558                   The owning package should also provide a program
7559                   that the other packages may use to modify the
7560                   configuration file.
7561               </item>
7562               <item>
7563                   The related packages must use the provided program
7564                   to make any desired modifications to the
7565                   configuration file.  They should either depend on
7566                   the core package to guarantee that the configuration
7567                   modifier program is available or accept gracefully
7568                   that they cannot modify the configuration file if it
7569                   is not.  (This is in addition to the fact that the
7570                   configuration file may not even be present in the
7571                   latter scenario.)
7572               </item>
7573             </enumlist>
7574           </p>
7575
7576           <p>
7577             Sometimes it's appropriate to create a new package which
7578             provides the basic infrastructure for the other packages
7579             and which manages the shared configuration files.  (The
7580             <tt>sgml-base</tt> package is a good example.)
7581           </p>
7582         </sect1>
7583
7584         <sect1>
7585           <heading>User configuration files ("dotfiles")</heading>
7586
7587           <p>
7588             The files in <file>/etc/skel</file> will automatically be
7589             copied into new user accounts by <prgn>adduser</prgn>.
7590             No other program should reference the files in
7591             <file>/etc/skel</file>.
7592           </p>
7593
7594           <p>
7595             Therefore, if a program needs a dotfile to exist in
7596             advance in <file>$HOME</file> to work sensibly, that dotfile
7597             should be installed in <file>/etc/skel</file> and treated as a
7598             configuration file.
7599           </p>
7600
7601           <p>
7602             However, programs that require dotfiles in order to
7603             operate sensibly are a bad thing, unless they do create
7604             the dotfiles themselves automatically.
7605           </p>
7606
7607           <p>
7608             Furthermore, programs should be configured by the Debian
7609             default installation to behave as closely to the upstream
7610             default behavior as possible.
7611           </p>
7612
7613           <p>
7614             Therefore, if a program in a Debian package needs to be
7615             configured in some way in order to operate sensibly, that
7616             should be done using a site-wide configuration file placed
7617             in <file>/etc</file>.  Only if the program doesn't support a
7618             site-wide default configuration and the package maintainer
7619             doesn't have time to add it may a default per-user file be
7620             placed in <file>/etc/skel</file>.
7621           </p>
7622
7623           <p>
7624             <file>/etc/skel</file> should be as empty as we can make it.
7625             This is particularly true because there is no easy (or
7626             necessarily desirable) mechanism for ensuring that the
7627             appropriate dotfiles are copied into the accounts of
7628             existing users when a package is installed.
7629           </p>
7630         </sect1>
7631       </sect>
7632
7633       <sect>
7634         <heading>Log files</heading>
7635         <p>
7636           Log files should usually be named
7637           <file>/var/log/<var>package</var>.log</file>.  If you have many
7638           log files, or need a separate directory for permission
7639           reasons (<file>/var/log</file> is writable only by
7640           <file>root</file>), you should usually create a directory named
7641           <file>/var/log/<var>package</var></file> and place your log
7642           files there.
7643         </p>
7644
7645         <p>
7646           Log files must be rotated occasionally so that they don't
7647           grow indefinitely; the best way to do this is to drop a log
7648           rotation configuration file into the directory
7649           <file>/etc/logrotate.d</file> and use the facilities provided by
7650           logrotate.<footnote>
7651             <p>
7652               The traditional approach to log files has been to set up
7653               <em>ad hoc</em> log rotation schemes using simple shell
7654               scripts and cron.  While this approach is highly
7655               customizable, it requires quite a lot of sysadmin work.
7656               Even though the original Debian system helped a little
7657               by automatically installing a system which can be used
7658               as a template, this was deemed not enough.
7659             </p>
7660
7661             <p>
7662               The use of <prgn>logrotate</prgn>, a program developed
7663               by Red Hat, is better, as it centralizes log management.
7664               It has both a configuration file
7665               (<file>/etc/logrotate.conf</file>) and a directory where
7666               packages can drop their individual log rotation
7667               configurations (<file>/etc/logrotate.d</file>).
7668             </p>
7669           </footnote>
7670           Here is a good example for a logrotate config
7671           file (for more information see <manref name="logrotate"
7672             section="8">):
7673           <example compact="compact">
7674 /var/log/foo/*.log {
7675 rotate 12
7676 weekly
7677 compress
7678 postrotate
7679 /etc/init.d/foo force-reload
7680 endscript
7681 }
7682           </example>
7683           This rotates all files under <file>/var/log/foo</file>, saves 12
7684           compressed generations, and forces the daemon to reload its
7685           configuration information after the log rotation.
7686         </p>
7687
7688         <p>
7689           Log files should be removed when the package is
7690           purged (but not when it is only removed).  This should be
7691           done by the <prgn>postrm</prgn> script when it is called
7692           with the argument <tt>purge</tt> (see <ref
7693           id="removedetails">).
7694         </p>
7695       </sect>
7696
7697       <sect>
7698         <heading>Permissions and owners</heading>
7699
7700         <p>
7701           The rules in this section are guidelines for general use.
7702           If necessary you may deviate from the details below.
7703           However, if you do so you must make sure that what is done
7704           is secure and you should try to be as consistent as possible
7705           with the rest of the system.  You should probably also
7706           discuss it on <prgn>debian-devel</prgn> first.
7707         </p>
7708
7709         <p>
7710           Files should be owned by <tt>root:root</tt>, and made
7711           writable only by the owner and universally readable (and
7712           executable, if appropriate), that is mode 644 or 755.
7713         </p>
7714
7715         <p>
7716           Directories should be mode 755 or (for group-writability)
7717           mode 2775.  The ownership of the directory should be
7718           consistent with its mode: if a directory is mode 2775, it
7719           should be owned by the group that needs write access to
7720           it.<footnote>
7721             <p>
7722               When a package is upgraded, and the owner or permissions
7723               of a file included in the package has changed, dpkg
7724               arranges for the ownership and permissions to be
7725               correctly set upon installation. However, this does not
7726               extend to directories; the permissions and ownership of
7727               directories already on the system does not change on
7728               install or upgrade of packages.  This makes sense, since
7729               otherwise common directories like <tt>/usr</tt> would
7730               always be in flux.  To correctly change permissions of a
7731               directory the package owns, explicit action is required,
7732               usually in the <tt>postinst</tt> script. Care must be
7733               taken to handle downgrades as well, in that case.
7734             </p>
7735           </footnote>
7736         </p>
7737
7738
7739         <p>
7740           Setuid and setgid executables should be mode 4755 or 2755
7741           respectively, and owned by the appropriate user or group.
7742           They should not be made unreadable (modes like 4711 or
7743           2711 or even 4111); doing so achieves no extra security,
7744           because anyone can find the binary in the freely available
7745           Debian package; it is merely inconvenient.  For the same
7746           reason you should not restrict read or execute permissions
7747           on non-set-id executables.
7748         </p>
7749
7750         <p>
7751           Some setuid programs need to be restricted to particular
7752           sets of users, using file permissions.  In this case they
7753           should be owned by the uid to which they are set-id, and by
7754           the group which should be allowed to execute them.  They
7755           should have mode 4754; again there is no point in making
7756           them unreadable to those users who must not be allowed to
7757           execute them.
7758         </p>
7759
7760         <p>
7761           It is possible to arrange that the system administrator can
7762           reconfigure the package to correspond to their local
7763           security policy by changing the permissions on a binary:
7764           they can do this by using <prgn>dpkg-statoverride</prgn>, as
7765           described below.<footnote>
7766               Ordinary files installed by <prgn>dpkg</prgn> (as
7767               opposed to <tt>conffile</tt>s and other similar objects)
7768               normally have their permissions reset to the distributed
7769               permissions when the package is reinstalled.  However,
7770               the use of <prgn>dpkg-statoverride</prgn> overrides this
7771               default behavior.  If you use this method, you should
7772               remember to describe <prgn>dpkg-statoverride</prgn> in
7773               the package documentation; being a relatively new
7774               addition to Debian, it is probably not yet well-known.
7775           </footnote>
7776           Another method you should consider is to create a group for
7777           people allowed to use the program(s) and make any setuid
7778           executables executable only by that group.
7779         </p>
7780
7781         <p>
7782           If you need to create a new user or group for your package
7783           there are two possibilities.  Firstly, you may need to
7784           make some files in the binary package be owned by this
7785           user or group, or you may need to compile the user or
7786           group id (rather than just the name) into the binary
7787           (though this latter should be avoided if possible, as in
7788           this case you need a statically allocated id).</p>
7789
7790         <p>
7791           If you need a statically allocated id, you must ask for a
7792           user or group id from the <tt>base-passwd</tt> maintainer,
7793           and must not release the package until you have been
7794           allocated one.  Once you have been allocated one you must
7795           either make the package depend on a version of the
7796           <tt>base-passwd</tt> package with the id present in
7797           <file>/etc/passwd</file> or <file>/etc/group</file>, or arrange for
7798           your package to create the user or group itself with the
7799           correct id (using <tt>adduser</tt>) in its
7800           <prgn>preinst</prgn> or <prgn>postinst</prgn>.  (Doing it in
7801           the <prgn>postinst</prgn> is to be preferred if it is
7802           possible, otherwise a pre-dependency will be needed on the
7803           <tt>adduser</tt> package.)
7804         </p>
7805
7806         <p>
7807           On the other hand, the program might be able to determine
7808           the uid or gid from the user or group name at runtime, so
7809           that a dynamically allocated id can be used.  In this case
7810           you should choose an appropriate user or group name,
7811           discussing this on <prgn>debian-devel</prgn> and checking
7812           with the <package/base-passwd/ maintainer that it is unique and that
7813           they do not wish you to use a statically allocated id
7814           instead.  When this has been checked you must arrange for
7815           your package to create the user or group if necessary using
7816           <prgn>adduser</prgn> in the <prgn>preinst</prgn> or
7817           <prgn>postinst</prgn> script (again, the latter is to be
7818           preferred if it is possible).
7819         </p>
7820
7821         <p>
7822           Note that changing the numeric value of an id associated
7823           with a name is very difficult, and involves searching the
7824           file system for all appropriate files.  You need to think
7825           carefully whether a static or dynamic id is required, since
7826           changing your mind later will cause problems.
7827         </p>
7828
7829         <sect1><heading>The use of <prgn>dpkg-statoverride</prgn></heading>
7830           <p>
7831             This section is not intended as policy, but as a
7832             description of the use of <prgn>dpkg-statoverride</prgn>.
7833           </p>
7834
7835           <p>
7836             If a system administrator wishes to have a file (or
7837             directory or other such thing) installed with owner and
7838             permissions different from those in the distributed Debian
7839             package, they can use the <prgn>dpkg-statoverride</prgn>
7840             program to instruct <prgn>dpkg</prgn> to use the different
7841             settings every time the file is installed.  Thus the
7842             package maintainer should distribute the files with their
7843             normal permissions, and leave it for the system
7844             administrator to make any desired changes.  For example, a
7845             daemon which is normally required to be setuid root, but
7846             in certain situations could be used without being setuid,
7847             should be installed setuid in the <tt>.deb</tt>.  Then the
7848             local system administrator can change this if they wish.
7849             If there are two standard ways of doing it, the package
7850             maintainer can use <tt>debconf</tt> to find out the
7851             preference, and call <prgn>dpkg-statoverride</prgn> in the
7852             maintainer script if necessary to accommodate the system
7853             administrator's choice. Care must be taken during
7854             upgrades to not override an existing setting.
7855           </p>
7856
7857           <p>
7858             Given the above, <prgn>dpkg-statoverride</prgn> is
7859             essentially a tool for system administrators and would not
7860             normally be needed in the maintainer scripts.  There is
7861             one type of situation, though, where calls to
7862             <prgn>dpkg-statoverride</prgn> would be needed in the
7863             maintainer scripts, and that involves packages which use
7864             dynamically allocated user or group ids.  In such a
7865             situation, something like the following idiom can be very
7866             helpful in the package's <prgn>postinst</prgn>, where
7867             <tt>sysuser</tt> is a dynamically allocated id:
7868             <example>
7869 for i in /usr/bin/foo /usr/sbin/bar
7870 do
7871   # only do something when no setting exists
7872   if ! dpkg-statoverride --list $i >/dev/null 2>&1
7873   then
7874     #include: debconf processing, question about foo and bar
7875     if [ "$RET" = "true" ] ; then
7876       dpkg-statoverride --update --add sysuser root 4755 $i
7877     fi
7878   fi
7879 done
7880             </example>
7881             The corresponding code to remove the override when the package
7882             is purged would be:
7883             <example>
7884 for i in /usr/bin/foo /usr/sbin/bar
7885 do
7886   if dpkg-statoverride --list $i >/dev/null 2>&1
7887   then
7888     dpkg-statoverride --remove $i
7889   fi
7890 done
7891             </example>
7892           </p>
7893         </sect1>
7894       </sect>
7895     </chapt>
7896
7897
7898     <chapt id="customized-programs">
7899       <heading>Customized programs</heading>
7900
7901       <sect id="arch-spec">
7902         <heading>Architecture specification strings</heading>
7903
7904         <p>
7905           If a program needs to specify an <em>architecture specification
7906             string</em> in some place, it should select one of the
7907           strings provided by <tt>dpkg-architecture -L</tt>. The
7908           strings are in the format
7909           <tt><var>os</var>-<var>arch</var></tt>, though the OS part
7910           is sometimes elided, as when the OS is Linux.<footnote>
7911             <p>Currently, the strings are:
7912               i386 ia64 alpha amd64 armeb arm hppa m32r m68k mips
7913               mipsel powerpc ppc64 s390 s390x sh3 sh3eb sh4 sh4eb
7914               sparc darwin-i386 darwin-ia64 darwin-alpha darwin-amd64
7915               darwin-armeb darwin-arm darwin-hppa darwin-m32r
7916               darwin-m68k darwin-mips darwin-mipsel darwin-powerpc
7917               darwin-ppc64 darwin-s390 darwin-s390x darwin-sh3
7918               darwin-sh3eb darwin-sh4 darwin-sh4eb darwin-sparc
7919               freebsd-i386 freebsd-ia64 freebsd-alpha freebsd-amd64
7920               freebsd-armeb freebsd-arm freebsd-hppa freebsd-m32r
7921               freebsd-m68k freebsd-mips freebsd-mipsel freebsd-powerpc
7922               freebsd-ppc64 freebsd-s390 freebsd-s390x freebsd-sh3
7923               freebsd-sh3eb freebsd-sh4 freebsd-sh4eb freebsd-sparc
7924               kfreebsd-i386 kfreebsd-ia64 kfreebsd-alpha
7925               kfreebsd-amd64 kfreebsd-armeb kfreebsd-arm kfreebsd-hppa
7926               kfreebsd-m32r kfreebsd-m68k kfreebsd-mips
7927               kfreebsd-mipsel kfreebsd-powerpc kfreebsd-ppc64
7928               kfreebsd-s390 kfreebsd-s390x kfreebsd-sh3 kfreebsd-sh3eb
7929               kfreebsd-sh4 kfreebsd-sh4eb kfreebsd-sparc knetbsd-i386
7930               knetbsd-ia64 knetbsd-alpha knetbsd-amd64 knetbsd-armeb
7931               knetbsd-arm knetbsd-hppa knetbsd-m32r knetbsd-m68k
7932               knetbsd-mips knetbsd-mipsel knetbsd-powerpc
7933               knetbsd-ppc64 knetbsd-s390 knetbsd-s390x knetbsd-sh3
7934               knetbsd-sh3eb knetbsd-sh4 knetbsd-sh4eb knetbsd-sparc
7935               netbsd-i386 netbsd-ia64 netbsd-alpha netbsd-amd64
7936               netbsd-armeb netbsd-arm netbsd-hppa netbsd-m32r
7937               netbsd-m68k netbsd-mips netbsd-mipsel netbsd-powerpc
7938               netbsd-ppc64 netbsd-s390 netbsd-s390x netbsd-sh3
7939               netbsd-sh3eb netbsd-sh4 netbsd-sh4eb netbsd-sparc
7940               openbsd-i386 openbsd-ia64 openbsd-alpha openbsd-amd64
7941               openbsd-armeb openbsd-arm openbsd-hppa openbsd-m32r
7942               openbsd-m68k openbsd-mips openbsd-mipsel openbsd-powerpc
7943               openbsd-ppc64 openbsd-s390 openbsd-s390x openbsd-sh3
7944               openbsd-sh3eb openbsd-sh4 openbsd-sh4eb openbsd-sparc
7945               hurd-i386 hurd-ia64 hurd-alpha hurd-amd64 hurd-armeb
7946               hurd-arm hurd-hppa hurd-m32r hurd-m68k hurd-mips
7947               hurd-mipsel hurd-powerpc hurd-ppc64 hurd-s390 hurd-s390x
7948               hurd-sh3 hurd-sh3eb hurd-sh4 hurd-sh4eb hurd-sparc
7949             </p>
7950           </footnote>
7951         </p>
7952
7953         <p>
7954           Note that we don't want to use
7955           <tt><var>arch</var>-debian-linux</tt> to apply to the rule
7956           <tt><var>architecture</var>-<var>vendor</var>-<var>os</var></tt>
7957           since this would make our programs incompatible with other
7958           Linux distributions.  We also don't use something like
7959           <tt><var>arch</var>-unknown-linux</tt>, since the
7960           <tt>unknown</tt> does not look very good.
7961         </p>
7962       </sect>
7963
7964       <sect>
7965         <heading>Daemons</heading>
7966
7967         <p>
7968           The configuration files <file>/etc/services</file>,
7969           <file>/etc/protocols</file>, and <file>/etc/rpc</file> are managed
7970           by the <prgn>netbase</prgn> package and must not be modified
7971           by other packages.
7972         </p>
7973
7974         <p>
7975           If a package requires a new entry in one of these files, the
7976           maintainer should get in contact with the
7977           <prgn>netbase</prgn> maintainer, who will add the entries
7978           and release a new version of the <prgn>netbase</prgn>
7979           package.
7980         </p>
7981
7982         <p>
7983           The configuration file <file>/etc/inetd.conf</file> must not be
7984           modified by the package's scripts except via the
7985           <prgn>update-inetd</prgn> script or the
7986           <file>DebianNet.pm</file> Perl module.  See their documentation
7987           for details on how to add entries.
7988         </p>
7989
7990         <p>
7991           If a package wants to install an example entry into
7992           <file>/etc/inetd.conf</file>, the entry must be preceded with
7993           exactly one hash character (<tt>#</tt>). Such lines are
7994           treated as "commented out by user" by the
7995           <prgn>update-inetd</prgn> script and are not changed or
7996           activated during package updates.
7997         </p>
7998       </sect>
7999
8000       <sect>
8001         <heading>Using pseudo-ttys and modifying wtmp, utmp and
8002         lastlog</heading>
8003
8004         <p>
8005           Some programs need to create pseudo-ttys. This should be done
8006           using Unix98 ptys if the C library supports it. The resulting
8007           program must not be installed setuid root, unless that
8008           is required for other functionality.
8009         </p>
8010
8011         <p>
8012           The files <file>/var/run/utmp</file>, <file>/var/log/wtmp</file> and
8013           <file>/var/log/lastlog</file> must be installed writable by
8014           group <tt>utmp</tt>.  Programs which need to modify those
8015           files must be installed setgid <tt>utmp</tt>.
8016         </p>
8017       </sect>
8018
8019       <sect>
8020         <heading>Editors and pagers</heading>
8021
8022         <p>
8023           Some programs have the ability to launch an editor or pager
8024           program to edit or display a text document.  Since there are
8025           lots of different editors and pagers available in the Debian
8026           distribution, the system administrator and each user should
8027           have the possibility to choose their preferred editor and
8028           pager.
8029         </p>
8030
8031         <p>
8032           In addition, every program should choose a good default
8033           editor/pager if none is selected by the user or system
8034           administrator.
8035         </p>
8036
8037         <p>
8038           Thus, every program that launches an editor or pager must
8039           use the EDITOR or PAGER environment variable to determine
8040           the editor or pager the user wishes to use.  If these
8041           variables are not set, the programs <file>/usr/bin/editor</file>
8042           and <file>/usr/bin/pager</file> should be used, respectively.
8043         </p>
8044
8045         <p>
8046           These two files are managed through the <prgn>dpkg</prgn>
8047           "alternatives" mechanism.  Thus every package providing an
8048           editor or pager must call the
8049           <prgn>update-alternatives</prgn> script to register these
8050           programs.
8051         </p>
8052
8053         <p>
8054           If it is very hard to adapt a program to make use of the
8055           EDITOR or PAGER variables, that program may be configured to
8056           use <file>/usr/bin/sensible-editor</file> and
8057           <file>/usr/bin/sensible-pager</file> as the editor or pager
8058           program respectively.  These are two scripts provided in the
8059           <package>sensible-utils</package> package that check the EDITOR
8060           and PAGER variables and launch the appropriate program, and fall
8061           back to <file>/usr/bin/editor</file>
8062           and <file>/usr/bin/pager</file> if the variable is not set.
8063         </p>
8064
8065         <p>
8066           A program may also use the VISUAL environment variable to
8067           determine the user's choice of editor.  If it exists, it
8068           should take precedence over EDITOR.  This is in fact what
8069           <file>/usr/bin/sensible-editor</file> does.
8070         </p>
8071
8072         <p>
8073           It is not required for a package to depend on
8074           <tt>editor</tt> and <tt>pager</tt>, nor is it required for a
8075           package to provide such virtual packages.<footnote>
8076               The Debian base system already provides an editor and a
8077               pager program.
8078           </footnote>
8079         </p>
8080       </sect>
8081
8082       <sect id="web-appl">
8083         <heading>Web servers and applications</heading>
8084
8085         <p>
8086           This section describes the locations and URLs that should
8087           be used by all web servers and web applications in the
8088           Debian system.
8089         </p>
8090
8091         <p>
8092           <enumlist>
8093             <item>
8094                 Cgi-bin executable files are installed in the
8095                 directory
8096                 <example compact="compact">
8097 /usr/lib/cgi-bin/<var>cgi-bin-name</var>
8098                 </example>
8099                 and should be referred to as
8100                 <example compact="compact">
8101 http://localhost/cgi-bin/<var>cgi-bin-name</var>
8102                 </example>
8103
8104             </item>
8105
8106             <item>
8107               <p>Access to HTML documents</p>
8108
8109               <p>
8110                 HTML documents for a package are stored in
8111                 <file>/usr/share/doc/<var>package</var></file>
8112                 and can be referred to as
8113                 <example compact="compact">
8114 http://localhost/doc/<var>package</var>/<var>filename</var>
8115                 </example>
8116               </p>
8117
8118               <p>
8119                 The web server should restrict access to the document
8120                 tree so that only clients on the same host can read
8121                 the documents. If the web server does not support such
8122                 access controls, then it should not provide access at
8123                 all, or ask about providing access during installation.
8124               </p>
8125             </item>
8126
8127             <item>
8128               <p>Access to images</p>
8129               <p>
8130                 It is recommended that images for a package be stored
8131                 in <tt>/usr/share/images/<var>package</var></tt> and
8132                 may be referred to through an alias <tt>/images/</tt>
8133                 as
8134                 <example>
8135                   http://localhost/images/&lt;package&gt;/&lt;filename&gt;     
8136                 </example>
8137                 
8138               </p>
8139             </item>
8140
8141             <item>
8142               <p>Web Document Root</p>
8143
8144               <p>
8145                 Web Applications should try to avoid storing files in
8146                 the Web Document Root.  Instead they should use the
8147                 /usr/share/doc/<var>package</var> directory for
8148                 documents and register the Web Application via the
8149                 <package>doc-base</package> package.  If access to the
8150                 web document root is unavoidable then use
8151                 <example compact="compact">
8152 /var/www
8153                 </example>
8154                 as the Document Root.  This might be just a symbolic
8155                 link to the location where the system administrator
8156                 has put the real document root.
8157               </p>
8158             </item>
8159             <item><p>Providing httpd and/or httpd-cgi</p>
8160               <p>
8161                 All web servers should provide the virtual package
8162                 <tt>httpd</tt>. If a web server has CGI support it should
8163                 provide <tt>httpd-cgi</tt> additionally.
8164               </p>
8165               <p>
8166                 All web applications which do not contain CGI scripts should
8167                 depend on <tt>httpd</tt>, all those web applications which
8168                 <tt>do</tt> contain CGI scripts, should depend on
8169                 <tt>httpd-cgi</tt>.
8170               </p>
8171             </item>
8172           </enumlist>
8173         </p>
8174       </sect>
8175
8176       <sect id="mail-transport-agents">
8177         <heading>Mail transport, delivery and user agents</heading>
8178
8179         <p>
8180           Debian packages which process electronic mail, whether mail
8181           user agents (MUAs) or mail transport agents (MTAs), must
8182           ensure that they are compatible with the configuration
8183           decisions below.  Failure to do this may result in lost
8184           mail, broken <tt>From:</tt> lines, and other serious brain
8185           damage!
8186         </p>
8187
8188         <p>
8189           The mail spool is <file>/var/mail</file> and the interface to
8190           send a mail message is <file>/usr/sbin/sendmail</file> (as per
8191           the FHS).  On older systems, the mail spool may be
8192           physically located in <file>/var/spool/mail</file>, but all
8193           access to the mail spool should be via the
8194           <file>/var/mail</file> symlink.  The mail spool is part of the
8195           base system and not part of the MTA package.
8196         </p>
8197
8198         <p>
8199           All Debian MUAs, MTAs, MDAs and other mailbox accessing
8200           programs (such as IMAP daemons) must lock the mailbox in an
8201           NFS-safe way. This means that <tt>fcntl()</tt> locking must
8202           be combined with dot locking.  To avoid deadlocks, a program
8203           should use <tt>fcntl()</tt> first and dot locking after
8204           this, or alternatively implement the two locking methods in
8205           a non blocking way<footnote>
8206               If it is not possible to establish both locks, the
8207               system shouldn't wait for the second lock to be
8208               established, but remove the first lock, wait a (random)
8209               time, and start over locking again.
8210           </footnote>. Using the functions <tt>maillock</tt> and
8211           <tt>mailunlock</tt> provided by the
8212           <tt>liblockfile*</tt><footnote>
8213               You will need to depend on <tt>liblockfile1 (&gt;&gt;1.01)</tt>
8214               to use these functions.
8215           </footnote> packages is the recommended way to realize this.
8216         </p>
8217
8218         <p>
8219           Mailboxes are generally either mode 600 and owned by
8220           <var>user</var> or mode 660 and owned by
8221           <tt><var>user</var>:mail</tt><footnote>
8222             There are two traditional permission schemes for mail spools:
8223             mode 600 with all mail delivery done by processes running as
8224             the destination user, or mode 660 and owned by group mail with
8225             mail delivery done by a process running as a system user in
8226             group mail.  Historically, Debian required mode 660 mail
8227             spools to enable the latter model, but that model has become
8228             increasingly uncommon and the principle of least privilege
8229             indicates that mail systems that use the first model should
8230             use permissions of 600.  If delivery to programs is permitted,
8231             it's easier to keep the mail system secure if the delivery
8232             agent runs as the destination user.  Debian Policy therefore
8233             permits either scheme.
8234           </footnote>. The local system administrator may choose a
8235           different permission scheme; packages should not make
8236           assumptions about the permission and ownership of mailboxes
8237           unless required (such as when creating a new mailbox).  A MUA
8238           may remove a mailbox (unless it has nonstandard permissions) in
8239           which case the MTA or another MUA must recreate it if needed.
8240         </p>
8241
8242         <p>
8243           The mail spool is 2775 <tt>root:mail</tt>, and MUAs should
8244           be setgid mail to do the locking mentioned above (and
8245           must obviously avoid accessing other users' mailboxes
8246           using this privilege).</p>
8247
8248         <p>
8249           <file>/etc/aliases</file> is the source file for the system mail
8250           aliases (e.g., postmaster, usenet, etc.), it is the one
8251           which the sysadmin and <prgn>postinst</prgn> scripts may
8252           edit.  After <file>/etc/aliases</file> is edited the program or
8253           human editing it must call <prgn>newaliases</prgn>.  All MTA
8254           packages must come with a <prgn>newaliases</prgn> program,
8255           even if it does nothing, but older MTA packages did not do
8256           this so programs should not fail if <prgn>newaliases</prgn>
8257           cannot be found.  Note that because of this, all MTA
8258           packages must have <tt>Provides</tt>, <tt>Conflicts</tt> and
8259           <tt>Replaces: mail-transport-agent</tt> control file
8260           fields.
8261         </p>
8262
8263         <p>
8264           The convention of writing <tt>forward to
8265             <var>address</var></tt> in the mailbox itself is not
8266           supported.  Use a <tt>.forward</tt> file instead.</p>
8267
8268         <p>
8269           The <prgn>rmail</prgn> program used by UUCP
8270           for incoming mail should be  <file>/usr/sbin/rmail</file>.
8271           Likewise, <prgn>rsmtp</prgn>, for receiving
8272           batch-SMTP-over-UUCP, should be <file>/usr/sbin/rsmtp</file> if it
8273           is supported.</p>
8274
8275         <p>
8276           If your package needs to know what hostname to use on (for
8277           example) outgoing news and mail messages which are generated
8278           locally, you should use the file <file>/etc/mailname</file>.  It
8279           will contain the portion after the username and <tt>@</tt>
8280           (at) sign for email addresses of users on the machine
8281           (followed by a newline).
8282         </p>
8283
8284         <p>
8285           Such a package should check for the existence of this file
8286           when it is being configured.  If it exists, it should be
8287           used without comment, although an MTA's configuration script
8288           may wish to prompt the user even if it finds that this file
8289           exists.  If the file does not exist, the package should
8290           prompt the user for the value (preferably using
8291           <prgn>debconf</prgn>) and store it in <file>/etc/mailname</file>
8292           as well as using it in the package's configuration.  The
8293           prompt should make it clear that the name will not just be
8294           used by that package.  For example, in this situation the
8295           <tt>inn</tt> package could say something like:
8296           <example compact="compact">
8297 Please enter the "mail name" of your system.  This is the
8298 hostname portion of the address to be shown on outgoing
8299 news and mail messages.  The default is
8300 <var>syshostname</var>, your system's host name.  Mail
8301 name ["<var>syshostname</var>"]:
8302           </example>
8303           where <var>syshostname</var> is the output of <tt>hostname
8304             --fqdn</tt>.
8305         </p>
8306       </sect>
8307
8308       <sect>
8309         <heading>News system configuration</heading>
8310
8311         <p>
8312           All the configuration files related to the NNTP (news)
8313           servers and clients should be located under
8314           <file>/etc/news</file>.</p>
8315
8316         <p>
8317           There are some configuration issues that apply to a number
8318           of news clients and server packages on the machine. These
8319           are:
8320
8321           <taglist>
8322             <tag><file>/etc/news/organization</file></tag>
8323             <item>
8324                 A string which should appear as the
8325                 organization header for all messages posted
8326                 by NNTP clients on the machine
8327             </item>
8328
8329             <tag><file>/etc/news/server</file></tag>
8330             <item>
8331                 Contains the FQDN of the upstream NNTP
8332                 server, or localhost if the local machine is
8333                 an NNTP server.
8334             </item>
8335           </taglist>
8336
8337           Other global files may be added as required for cross-package news
8338           configuration.
8339         </p>
8340       </sect>
8341
8342
8343       <sect>
8344         <heading>Programs for the X Window System</heading>
8345
8346         <sect1>
8347           <heading>Providing X support and package priorities</heading>
8348
8349           <p>
8350             Programs that can be configured with support for the X
8351             Window System must be configured to do so and must declare
8352             any package dependencies necessary to satisfy their
8353             runtime requirements when using the X Window System.  If
8354             such a package is of higher priority than the X packages
8355             on which it depends, it is required that either the
8356             X-specific components be split into a separate package, or
8357             that an alternative version of the package, which includes
8358             X support, be provided, or that the package's priority be
8359             lowered.
8360           </p>
8361         </sect1>
8362
8363         <sect1>
8364           <heading>Packages providing an X server</heading>
8365
8366           <p>
8367             Packages that provide an X server that, directly or
8368             indirectly, communicates with real input and display
8369             hardware should declare in their control data that they
8370             provide the virtual package <tt>xserver</tt>.<footnote>
8371                 This implements current practice, and provides an
8372                 actual policy for usage of the <tt>xserver</tt>
8373                 virtual package which appears in the virtual packages
8374                 list.  In a nutshell, X servers that interface
8375                 directly with the display and input hardware or via
8376                 another subsystem (e.g., GGI) should provide
8377                 <tt>xserver</tt>.  Things like <tt>Xvfb</tt>,
8378                 <tt>Xnest</tt>, and <tt>Xprt</tt> should not.
8379             </footnote>
8380           </p>
8381         </sect1>
8382
8383         <sect1>
8384           <heading>Packages providing a terminal emulator</heading>
8385
8386           <p>
8387             Packages that provide a terminal emulator for the X Window
8388             System which meet the criteria listed below should declare
8389             in their control data that they provide the virtual
8390             package <tt>x-terminal-emulator</tt>.  They should also
8391             register themselves as an alternative for
8392             <file>/usr/bin/x-terminal-emulator</file>, with a priority of
8393             20.
8394           </p>
8395
8396           <p>
8397             To be an <tt>x-terminal-emulator</tt>, a program must:
8398             <list compact="compact">
8399               <item>
8400                   Be able to emulate a DEC VT100 terminal, or a
8401                   compatible terminal.
8402               </item>
8403
8404               <item>
8405                   Support the command-line option <tt>-e
8406                     <var>command</var></tt>, which creates a new
8407                   terminal window<footnote>
8408                       "New terminal window" does not necessarily mean
8409                       a new top-level X window directly parented by
8410                       the window manager; it could, if the terminal
8411                       emulator application were so coded, be a new
8412                       "view" in a multiple-document interface (MDI).
8413                   </footnote>
8414                   and runs the specified <var>command</var>,
8415                   interpreting the entirety of the rest of the command
8416                   line as a command to pass straight to exec, in the
8417                   manner that <tt>xterm</tt> does.
8418               </item>
8419
8420               <item>
8421                   Support the command-line option <tt>-T
8422                     <var>title</var></tt>, which creates a new terminal
8423                   window with the window title <var>title</var>.
8424               </item>
8425             </list>
8426           </p>
8427         </sect1>
8428
8429         <sect1>
8430           <heading>Packages providing a window manager</heading>
8431
8432           <p>
8433             Packages that provide a window manager should declare in
8434             their control data that they provide the virtual package
8435             <tt>x-window-manager</tt>.  They should also register
8436             themselves as an alternative for
8437             <file>/usr/bin/x-window-manager</file>, with a priority
8438             calculated as follows:
8439             <list compact="compact">
8440               <item>
8441                   Start with a priority of 20.
8442               </item>
8443
8444               <item>
8445                   If the window manager supports the Debian menu
8446                   system, add 20 points if this support is available
8447                   in the package's default configuration (i.e., no
8448                   configuration files belonging to the system or user
8449                   have to be edited to activate the feature); if
8450                   configuration files must be modified, add only 10
8451                   points.
8452                 </p>
8453               </item>
8454
8455               <item>
8456                   If the window manager complies with <url
8457                     id="http://www.freedesktop.org/Standards/wm-spec"
8458                     name="The Window Manager Specification Project">,
8459                   written by the <url id="http://www.freedesktop.org/"
8460                     name="Free Desktop Group">, add 40 points.
8461               </item>
8462
8463               <item>
8464                   If the window manager permits the X session to be
8465                   restarted using a <em>different</em> window manager
8466                   (without killing the X server) in its default
8467                   configuration, add 10 points; otherwise add none.
8468               </item>
8469             </list>
8470           </p>
8471         </sect1>
8472
8473         <sect1>
8474           <heading>Packages providing fonts</heading>
8475
8476           <p>
8477             Packages that provide fonts for the X Window
8478             System<footnote>
8479                 For the purposes of Debian Policy, a "font for the X
8480                 Window System" is one which is accessed via X protocol
8481                 requests.  Fonts for the Linux console, for PostScript
8482                 renderer, or any other purpose, do not fit this
8483                 definition.  Any tool which makes such fonts available
8484                 to the X Window System, however, must abide by this
8485                 font policy.
8486             </footnote>
8487             must do a number of things to ensure that they are both
8488             available without modification of the X or font server
8489             configuration, and that they do not corrupt files used by
8490             other font packages to register information about
8491             themselves.
8492             <enumlist>
8493               <item>
8494                   Fonts of any type supported by the X Window System
8495                   must be in a separate binary package from any
8496                   executables, libraries, or documentation (except
8497                   that specific to the fonts shipped, such as their
8498                   license information).  If one or more of the fonts
8499                   so packaged are necessary for proper operation of
8500                   the package with which they are associated the font
8501                   package may be Recommended; if the fonts merely
8502                   provide an enhancement, a Suggests relationship may
8503                   be used.  Packages must not Depend on font
8504                   packages.<footnote>
8505                       This is because the X server may retrieve fonts
8506                       from the local file system or over the network
8507                       from an X font server; the Debian package system
8508                       is empowered to deal only with the local
8509                       file system.
8510                   </footnote>
8511               </item>
8512
8513               <item>
8514                   BDF fonts must be converted to PCF fonts with the
8515                   <prgn>bdftopcf</prgn> utility (available in the
8516                   <tt>xfonts-utils</tt> package, <prgn>gzip</prgn>ped, and
8517                   placed in a directory that corresponds to their
8518                   resolution:
8519                   <list compact="compact">
8520                     <item>
8521                         100 dpi fonts must be placed in
8522                         <file>/usr/share/fonts/X11/100dpi/</file>.
8523                     </item>
8524
8525                     <item>
8526                         75 dpi fonts must be placed in
8527                         <file>/usr/share/fonts/X11/75dpi/</file>.
8528                     </item>
8529
8530                     <item>
8531                         Character-cell fonts, cursor fonts, and other
8532                         low-resolution fonts must be placed in
8533                         <file>/usr/share/fonts/X11/misc/</file>.
8534                     </item>
8535                   </list>
8536               </item>
8537
8538               <item>
8539                   Type 1 fonts must be placed in
8540                   <file>/usr/share/fonts/X11/Type1/</file>.  If font
8541                   metric files are available, they must be placed here
8542                   as well.
8543               </item>
8544
8545               <item>
8546                   Subdirectories of <file>/usr/share/fonts/X11/</file>
8547                   other than those listed above must be neither
8548                   created nor used.  (The <file>PEX</file>, <file>CID</file>,
8549                   <file>Speedo</file>, and <file>cyrillic</file> directories
8550                   are excepted for historical reasons, but installation of
8551                   files into these directories remains discouraged.)
8552               </item>
8553
8554               <item>
8555                   Font packages may, instead of placing files directly
8556                   in the X font directories listed above, provide
8557                   symbolic links in that font directory pointing to
8558                   the files' actual location in the filesystem.  Such
8559                   a location must comply with the FHS.
8560               </item>
8561
8562               <item>
8563                   Font packages should not contain both 75dpi and
8564                   100dpi versions of a font.  If both are available,
8565                   they should be provided in separate binary packages
8566                   with <tt>-75dpi</tt> or <tt>-100dpi</tt> appended to
8567                   the names of the packages containing the
8568                   corresponding fonts.
8569               </item>
8570
8571               <item>
8572                   Fonts destined for the <file>misc</file> subdirectory
8573                   should not be included in the same package as 75dpi
8574                   or 100dpi fonts; instead, they should be provided in
8575                   a separate package with <tt>-misc</tt> appended to
8576                   its name.
8577               </item>
8578
8579               <item>
8580                   Font packages must not provide the files
8581                   <file>fonts.dir</file>, <file>fonts.alias</file>, or
8582                   <file>fonts.scale</file> in a font directory:
8583                   <list>
8584                     <item>
8585                         <file>fonts.dir</file> files must not be provided at all.
8586                     </item>
8587
8588                     <item>
8589                         <file>fonts.alias</file> and <file>fonts.scale</file>
8590                         files, if needed, should be provided in the
8591                         directory
8592                         <file>/etc/X11/fonts/<var>fontdir</var>/<var>package</var>.<var>extension</var></file>,
8593                         where <var>fontdir</var> is the name of the
8594                         subdirectory of
8595                         <file>/usr/share/fonts/X11/</file> where the
8596                         package's corresponding fonts are stored
8597                         (e.g., <tt>75dpi</tt> or <tt>misc</tt>),
8598                         <var>package</var> is the name of the package
8599                         that provides these fonts, and
8600                         <var>extension</var> is either <tt>scale</tt>
8601                         or <tt>alias</tt>, whichever corresponds to
8602                         the file contents.
8603                     </item>
8604                   </list>
8605               </item>
8606
8607               <item>
8608                   Font packages must declare a dependency on
8609                   <tt>xfonts-utils</tt> in their control
8610                   data.
8611               </item>
8612
8613               <item>
8614                   Font packages that provide one or more
8615                   <file>fonts.scale</file> files as described above must
8616                   invoke <prgn>update-fonts-scale</prgn> on each
8617                   directory into which they installed fonts
8618                   <em>before</em> invoking
8619                   <prgn>update-fonts-dir</prgn> on that directory.
8620                   This invocation must occur in both the
8621                   <prgn>postinst</prgn> (for all arguments) and
8622                   <prgn>postrm</prgn> (for all arguments except
8623                   <tt>upgrade</tt>) scripts.
8624               </item>
8625
8626               <item>
8627                   Font packages that provide one or more
8628                   <file>fonts.alias</file> files as described above must
8629                   invoke <prgn>update-fonts-alias</prgn> on each
8630                   directory into which they installed fonts.  This
8631                   invocation must occur in both the
8632                   <prgn>postinst</prgn> (for all arguments) and
8633                   <prgn>postrm</prgn> (for all arguments except
8634                   <tt>upgrade</tt>) scripts.
8635               </item>
8636
8637               <item>
8638                   Font packages must invoke
8639                   <prgn>update-fonts-dir</prgn> on each directory into
8640                   which they installed fonts.  This invocation must
8641                   occur in both the <prgn>postinst</prgn> (for all
8642                   arguments) and <prgn>postrm</prgn> (for all
8643                   arguments except <tt>upgrade</tt>) scripts.
8644               </item>
8645
8646               <item>
8647                   Font packages must not provide alias names for the
8648                   fonts they include which collide with alias names
8649                   already in use by fonts already packaged.
8650               </item>
8651
8652               <item>
8653                   Font packages must not provide fonts with the same
8654                   XLFD registry name as another font already packaged.
8655               </item>
8656             </enumlist>
8657           </p>
8658         </sect1>
8659
8660         <sect1 id="appdefaults">
8661           <heading>Application defaults files</heading>
8662
8663           <p>
8664             Application defaults files must be installed in the
8665             directory <file>/etc/X11/app-defaults/</file> (use of a
8666             localized subdirectory of <file>/etc/X11/</file> as described
8667             in the <em>X Toolkit Intrinsics - C Language
8668             Interface</em> manual is also permitted).  They must be
8669             registered as <tt>conffile</tt>s or handled as
8670             configuration files.
8671           </p>
8672
8673           <p>
8674             Customization of programs' X resources may also be
8675             supported with the provision of a file with the same name
8676             as that of the package placed in
8677             the <file>/etc/X11/Xresources/</file> directory, which
8678             must be registered as a <tt>conffile</tt> or handled as a
8679             configuration file.<footnote>
8680                 Note that this mechanism is not the same as using
8681                 app-defaults; app-defaults are tied to the client
8682                 binary on the local file system, whereas X resources
8683                 are stored in the X server and affect all connecting
8684                 clients.
8685             </footnote>
8686           </p>
8687         </sect1>
8688
8689         <sect1>
8690           <heading>Installation directory issues</heading>
8691
8692           <p>
8693             Historically, packages using the X Window System used a
8694             separate set of installation directories from other packages.
8695             This practice has been discontinued and packages using the X
8696             Window System should now generally be installed in the same
8697             directories as any other package.  Specifically, packages must
8698             not install files under the <file>/usr/X11R6/</file> directory
8699             and the <file>/usr/X11R6/</file> directory hierarchy should be
8700             regarded as obsolete.
8701           </p>
8702
8703           <p>
8704             Include files previously installed under
8705             <file>/usr/X11R6/include/X11/</file> should be installed into
8706             <file>/usr/include/X11/</file>.  For files previously
8707             installed into subdirectories of
8708             <file>/usr/X11R6/lib/X11/</file>, package maintainers should
8709             determine if subdirectories of <file>/usr/lib/</file> and
8710             <file>/usr/share/</file> can be used.  If not, a subdirectory
8711             of <file>/usr/lib/X11/</file> should be used.
8712           </p>
8713
8714           <p>
8715             Configuration files for window, display, or session managers
8716             or other applications that are tightly integrated with the X
8717             Window System may be placed in a subdirectory
8718             of <file>/etc/X11/</file> corresponding to the package name.
8719             Other X Window System applications should use
8720             the <file>/etc/</file> directory unless otherwise mandated by
8721             policy (such as for <ref id="appdefaults">).
8722           </p>
8723         </sect1>
8724
8725         <sect1>
8726           <heading>The OSF/Motif and OpenMotif libraries</heading>
8727
8728           <p>
8729             <em>Programs that require the non-DFSG-compliant OSF/Motif or
8730               OpenMotif libraries</em><footnote>
8731                 OSF/Motif and OpenMotif are collectively referred to as
8732                 "Motif" in this policy document.
8733             </footnote>
8734             should be compiled against and tested with LessTif (a free
8735             re-implementation of Motif) instead.  If the maintainer
8736             judges that the program or programs do not work
8737             sufficiently well with LessTif to be distributed and
8738             supported, but do so when compiled against Motif, then two
8739             versions of the package should be created; one linked
8740             statically against Motif and with <tt>-smotif</tt>
8741             appended to the package name, and one linked dynamically
8742             against Motif and with <tt>-dmotif</tt> appended to the
8743             package name.
8744           </p>
8745
8746           <p>
8747             Both Motif-linked versions are dependent
8748             upon non-DFSG-compliant software and thus cannot be
8749             uploaded to the <em>main</em> distribution; if the
8750             software is itself DFSG-compliant it may be uploaded to
8751             the <em>contrib</em> distribution.  While known existing
8752             versions of Motif permit unlimited redistribution of
8753             binaries linked against the library (whether statically or
8754             dynamically), it is the package maintainer's
8755             responsibility to determine whether this is permitted by
8756             the license of the copy of Motif in their possession.
8757           </p>
8758         </sect1>
8759       </sect>
8760
8761       <sect id="perl">
8762         <heading>Perl programs and modules</heading>
8763
8764         <p>
8765           Perl programs and modules should follow the current Perl policy.
8766         </p>
8767
8768         <p>
8769           The Perl policy can be found in the <tt>perl-policy</tt>
8770           files in the <tt>debian-policy</tt> package.
8771           It is also available from the Debian web mirrors at
8772           <tt><url name="/doc/packaging-manuals/perl-policy/"
8773                 id="http://www.debian.org/doc/packaging-manuals/perl-policy/"></tt>.
8774         </p>
8775       </sect>
8776
8777       <sect id="emacs">
8778         <heading>Emacs lisp programs</heading>
8779
8780         <p>
8781           Please refer to the "Debian Emacs Policy" for details of how to
8782           package emacs lisp programs.
8783         </p>
8784
8785         <p>
8786           The Emacs policy is available in
8787           <file>debian-emacs-policy.gz</file> of the
8788           <package>emacsen-common</package> package.
8789           It is also available from the Debian web mirrors at
8790           <tt><url name="/doc/packaging-manuals/debian-emacs-policy"
8791                 id="http://www.debian.org/doc/packaging-manuals/debian-emacs-policy"></tt>.
8792         </p>
8793       </sect>
8794
8795       <sect>
8796         <heading>Games</heading>
8797
8798         <p>
8799           The permissions on <file>/var/games</file> are mode 755, owner
8800           <tt>root</tt> and group <tt>root</tt>.
8801         </p>
8802
8803         <p>
8804           Each game decides on its own security policy.</p>
8805
8806         <p>
8807           Games which require protected, privileged access to
8808           high-score files, saved games, etc., may be made
8809           set-<em>group</em>-id (mode 2755) and owned by
8810           <tt>root:games</tt>, and use files and directories with
8811           appropriate permissions (770 <tt>root:games</tt>, for
8812           example).  They must not be made
8813           set-<em>user</em>-id, as this causes security problems. (If
8814           an attacker can subvert any set-user-id game they can
8815           overwrite the executable of any other, causing other players
8816           of these games to run a Trojan horse program.  With a
8817           set-group-id game the attacker only gets access to less
8818           important game data, and if they can get at the other
8819           players' accounts at all it will take considerably more
8820           effort.)</p>
8821
8822         <p>
8823           Some packages, for example some fortune cookie programs, are
8824           configured by the upstream authors to install with their
8825           data files or other static information made unreadable so
8826           that they can only be accessed through set-id programs
8827           provided.  You should not do this in a Debian package: anyone can
8828           download the <file>.deb</file> file and read the data from it,
8829           so there is no point making the files unreadable.  Not
8830           making the files unreadable also means that you don't have
8831           to make so many programs set-id, which reduces the risk of a
8832           security hole.</p>
8833
8834         <p>
8835           As described in the FHS, binaries of games should be
8836           installed in the directory <file>/usr/games</file>. This also
8837           applies to games that use the X Window System. Manual pages
8838           for games (X and non-X games) should be installed in
8839           <file>/usr/share/man/man6</file>.</p>
8840       </sect>
8841     </chapt>
8842
8843
8844     <chapt id="docs">
8845       <heading>Documentation</heading>
8846
8847       <sect>
8848         <heading>Manual pages</heading>
8849
8850         <p>
8851           You should install manual pages in <prgn>nroff</prgn> source
8852           form, in appropriate places under <file>/usr/share/man</file>.
8853           You should only use sections 1 to 9 (see the FHS for more
8854           details).  You must not install a pre-formatted "cat page".
8855         </p>
8856
8857         <p>
8858           Each program, utility, and function should have an
8859           associated manual page included in the same package. It is
8860           suggested that all configuration files also have a manual
8861           page included as well. Manual pages for protocols and other
8862           auxiliary things are optional.
8863         </p>
8864
8865         <p>
8866           If no manual page is available, this is considered as a bug
8867           and should be reported to the Debian Bug Tracking System (the
8868           maintainer of the package is allowed to write this bug report
8869           themselves, if they so desire).  Do not close the bug report
8870           until a proper man page is available.<footnote>
8871               It is not very hard to write a man page. See the
8872               <url id="http://www.schweikhardt.net/man_page_howto.html"
8873                 name="Man-Page-HOWTO">,
8874               <manref name="man" section="7">, the examples
8875               created by <prgn>debmake</prgn> or <prgn>dh_make</prgn>,
8876               the helper programs <prgn>help2man</prgn>, or the
8877               directory <file>/usr/share/doc/man-db/examples</file>.
8878           </footnote>
8879         </p>
8880
8881         <p>
8882           You may forward a complaint about a missing man page to the
8883           upstream authors, and mark the bug as forwarded in the
8884           Debian bug tracking system.  Even though the GNU Project do
8885           not in general consider the lack of a man page to be a bug,
8886           we do; if they tell you that they don't consider it a bug
8887           you should leave the bug in our bug tracking system open
8888           anyway.
8889         </p>
8890
8891         <p>
8892           Manual pages should be installed compressed using <tt>gzip -9</tt>.
8893         </p>
8894
8895         <p>
8896           If one man page needs to be accessible via several names it
8897           is better to use a symbolic link than the <file>.so</file>
8898           feature, but there is no need to fiddle with the relevant
8899           parts of the upstream source to change from <file>.so</file> to
8900           symlinks: don't do it unless it's easy.  You should not
8901           create hard links in the manual page directories, nor put
8902           absolute filenames in <file>.so</file> directives.  The filename
8903           in a <file>.so</file> in a man page should be relative to the
8904           base of the man page tree (usually
8905           <file>/usr/share/man</file>). If you do not create any links
8906           (whether symlinks, hard links, or <tt>.so</tt> directives)
8907           in the file system to the alternate names of the man page,
8908           then you should not rely on <prgn>man</prgn> finding your
8909           man page under those names based solely on the information in
8910           the man page's header.<footnote>
8911               Supporting this in <prgn>man</prgn> often requires
8912               unreasonable processing time to find a manual page or to
8913               report that none exists, and moves knowledge into man's
8914               database that would be better left in the file system.
8915               This support is therefore deprecated and will cease to
8916               be present in the future.
8917           </footnote>
8918         </p>
8919
8920         <p>
8921           Manual pages in locale-specific subdirectories of
8922           <file>/usr/share/man</file> should use either UTF-8 or the usual
8923           legacy encoding for that language (normally the one corresponding
8924           to the shortest relevant locale name in
8925           <file>/usr/share/i18n/SUPPORTED</file>). For example, pages under
8926           <file>/usr/share/man/fr</file> should use either UTF-8 or
8927           ISO-8859-1.<footnote>
8928             <prgn>man</prgn> will automatically detect whether UTF-8 is in
8929             use. In future, all manual pages will be required to use
8930             UTF-8.
8931           </footnote>
8932         </p>
8933
8934         <p>
8935           A country name (the <tt>DE</tt> in <tt>de_DE</tt>) should not be
8936           included in the subdirectory name unless it indicates a
8937           significant difference in the language, as this excludes
8938           speakers of the language in other countries.<footnote>
8939             At the time of writing, Chinese and Portuguese are the main
8940             languages with such differences, so <file>pt_BR</file>,
8941             <file>zh_CN</file>, and <file>zh_TW</file> are all allowed.
8942           </footnote>
8943         </p>
8944
8945         <p>
8946           If a localized version of a manual page is provided, it should
8947           either be up-to-date or it should be obvious to the reader that
8948           it is outdated and the original manual page should be used
8949           instead.  This can be done either by a note at the beginning of
8950           the manual page or by showing the missing or changed portions in
8951           the original language instead of the target language.
8952         </p>
8953       </sect>
8954
8955       <sect>
8956         <heading>Info documents</heading>
8957
8958         <p>
8959           Info documents should be installed in <file>/usr/share/info</file>.
8960           They should be compressed with <tt>gzip -9</tt>.
8961         </p>
8962
8963         <p>
8964           The <prgn>install-info</prgn> program maintains a directory of
8965           installed info documents in <file>/usr/share/info/dir</file> for
8966           the use of info readers.<footnote>
8967             It was previously necessary for packages installing info
8968             documents to run <prgn>install-info</prgn> from maintainer
8969             scripts.  This is no longer necessary.  The installation
8970             system now uses dpkg triggers.
8971           </footnote>
8972           This file must not be included in packages.  Packages containing
8973           info documents should depend on <tt>dpkg (>= 1.15.4) |
8974           install-info</tt> to ensure that the directory file is properly
8975           rebuilt during partial upgrades from Debian 5.0 (lenny) and
8976           earlier.
8977         </p>
8978
8979         <p>
8980           Info documents should contain section and directory entry
8981           information in the document for the use
8982           of <prgn>install-info</prgn>.  The section should be specified
8983           via a line starting with <tt>INFO-DIR-SECTION</tt> followed by a
8984           space and the section of this info page.  The directory entry or
8985           entries should be included between
8986           a <tt>START-INFO-DIR-ENTRY</tt> line and
8987           an <tt>END-INFO-DIR-ENTRY</tt> line.  For example:
8988           <example>
8989 INFO-DIR-SECTION Individual utilities
8990 START-INFO-DIR-ENTRY
8991 * example: (example).               An example info directory entry.
8992 END-INFO-DIR-ENTRY
8993           </example>
8994           To determine which section to use, you should look
8995           at <file>/usr/share/info/dir</file> on your system and choose
8996           the most relevant (or create a new section if none of the
8997           current sections are relevant).<footnote>
8998             Normally, info documents are generated from Texinfo source.
8999             To include this information in the generated info document, if
9000             it is absent, add commands like:
9001             <example>
9002 @dircategory Individual utilities
9003 @direntry
9004 * example: (example).               An example info directory entry.
9005 @end direntry
9006             </example>
9007             to the Texinfo source of the document and ensure that the info
9008             documents are rebuilt from source during the package build.
9009           </footnote>
9010         </p>
9011       </sect>
9012
9013       <sect>
9014         <heading>Additional documentation</heading>
9015
9016         <p>
9017           Any additional documentation that comes with the package may
9018           be installed at the discretion of the package maintainer.
9019           Plain text documentation should be installed in the directory
9020           <file>/usr/share/doc/<var>package</var></file>, where
9021           <var>package</var> is the name of the package, and
9022           compressed with <tt>gzip -9</tt> unless it is small.
9023         </p>
9024
9025         <p>
9026           If a package comes with large amounts of documentation which
9027           many users of the package will not require you should create
9028           a separate binary package to contain it, so that it does not
9029           take up disk space on the machines of users who do not need
9030           or want it installed.</p>
9031
9032         <p>
9033           It is often a good idea to put text information files
9034           (<file>README</file>s, changelogs, and so forth) that come with
9035           the source package in <file>/usr/share/doc/<var>package</var></file>
9036           in the binary package.  However, you don't need to install
9037           the instructions for building and installing the package, of
9038           course!</p>
9039
9040         <p>
9041           Packages must not require the existence of any files in
9042           <file>/usr/share/doc/</file> in order to function
9043           <footnote>
9044               The system administrator should be able to
9045               delete files in <file>/usr/share/doc/</file> without causing
9046               any programs to break.
9047           </footnote>.
9048           Any files that are referenced by programs but are also
9049           useful as stand alone documentation should be installed under
9050           <file>/usr/share/<var>package</var>/</file> with symbolic links from
9051           <file>/usr/share/doc/<var>package</var></file>.
9052         </p>
9053
9054         <p>
9055           <file>/usr/share/doc/<var>package</var></file> may be a symbolic
9056           link to another directory in <file>/usr/share/doc</file> only if
9057           the two packages both come from the same source and the
9058           first package Depends on the second.<footnote>
9059             <p>
9060               Please note that this does not override the section on
9061               changelog files below, so the file 
9062               <file>/usr/share/doc/<var>package</var>/changelog.Debian.gz</file>
9063               must refer to the changelog for the current version of
9064               <var>package</var> in question. In practice, this means
9065               that the sources of the target and the destination of the
9066               symlink must be the same (same source package and
9067               version). 
9068             </p>
9069           </footnote>
9070         </p>
9071
9072         <p>
9073           Former Debian releases placed all additional documentation
9074           in <file>/usr/doc/<var>package</var></file>.  This has been
9075           changed to <file>/usr/share/doc/<var>package</var></file>,
9076           and packages must not put documentation in the directory
9077           <file>/usr/doc/<var>package</var></file>. <footnote>
9078             At this phase of the transition, we no longer require a
9079             symbolic link in <file>/usr/doc/</file>. At a later point,
9080             policy shall change to make the symbolic links a bug.
9081           </footnote>
9082         </p>
9083       </sect>
9084
9085       <sect>
9086         <heading>Preferred documentation formats</heading>
9087
9088         <p>
9089           The unification of Debian documentation is being carried out
9090           via HTML.</p>
9091
9092         <p>
9093           If your package comes with extensive documentation in a
9094           markup format that can be converted to various other formats
9095           you should if possible ship HTML versions in a binary
9096           package, in the directory
9097           <file>/usr/share/doc/<var>appropriate-package</var></file> or
9098           its subdirectories.<footnote>
9099               The rationale: The important thing here is that HTML
9100               docs should be available in <em>some</em> package, not
9101               necessarily in the main binary package.
9102           </footnote>
9103         </p>
9104
9105         <p>
9106           Other formats such as PostScript may be provided at the
9107           package maintainer's discretion.
9108         </p>
9109       </sect>
9110
9111       <sect id="copyrightfile">
9112         <heading>Copyright information</heading>
9113
9114         <p>
9115           Every package must be accompanied by a verbatim copy of its
9116           copyright information and distribution license in the file
9117           <file>/usr/share/doc/<var>package</var>/copyright</file>. This
9118           file must neither be compressed nor be a symbolic link.
9119         </p>
9120
9121         <p>
9122           In addition, the copyright file must say where the upstream
9123           sources (if any) were obtained.  It should name the original
9124           authors of the package and the Debian maintainer(s) who were
9125           involved with its creation.
9126         </p>
9127
9128         <p>
9129           Packages in the <em>contrib</em> or <em>non-free</em> archive
9130           areas should state in the copyright file that the package is not
9131           part of the Debian GNU/Linux distribution and briefly explain
9132           why.
9133         </p>
9134
9135         <p>
9136           A copy of the file which will be installed in
9137           <file>/usr/share/doc/<var>package</var>/copyright</file> should
9138           be in <file>debian/copyright</file> in the source package.
9139         </p>
9140
9141         <p>
9142           <file>/usr/share/doc/<var>package</var></file> may be a symbolic
9143           link to another directory in <file>/usr/share/doc</file> only if
9144           the two packages both come from the same source and the
9145           first package Depends on the second.  These rules are
9146           important because copyrights must be extractable by
9147           mechanical means.
9148         </p>
9149
9150         <p>
9151           Packages distributed under the UCB BSD license, the Apache
9152           license (version 2.0), the Artistic license, the GNU GPL
9153           (version 2 or 3), the GNU LGPL (versions 2, 2.1, or 3), and the
9154           GNU FDL (versions 1.2 or 1.3) should refer to the corresponding
9155           files under <file>/usr/share/common-licenses</file>,<footnote>
9156             <p>
9157               In particular,
9158               <file>/usr/share/common-licenses/BSD</file>,
9159               <file>/usr/share/common-licenses/Apache-2.0</file>,
9160               <file>/usr/share/common-licenses/Artistic</file>,
9161               <file>/usr/share/common-licenses/GPL-2</file>,
9162               <file>/usr/share/common-licenses/GPL-3</file>,
9163               <file>/usr/share/common-licenses/LGPL-2</file>,
9164               <file>/usr/share/common-licenses/LGPL-2.1</file>,
9165               <file>/usr/share/common-licenses/LGPL-3</file>,
9166               <file>/usr/share/common-licenses/GFDL-1.2</file>, and
9167               <file>/usr/share/common-licenses/GFDL-1.3</file>
9168               respectively.
9169             </p>
9170           </footnote> rather than quoting them in the copyright
9171           file. 
9172         </p>
9173
9174         <p>
9175           You should not use the copyright file as a general <file>README</file>
9176           file.  If your package has such a file it should be
9177           installed in <file>/usr/share/doc/<var>package</var>/README</file> or
9178           <file>README.Debian</file> or some other appropriate place.</p>
9179       </sect>
9180
9181       <sect>
9182         <heading>Examples</heading>
9183
9184         <p>
9185           Any examples (configurations, source files, whatever),
9186           should be installed in a directory
9187           <file>/usr/share/doc/<var>package</var>/examples</file>.  These
9188           files should not be referenced by any program: they're there
9189           for the benefit of the system administrator and users as
9190           documentation only.  Architecture-specific example files
9191           should be installed in a directory
9192           <file>/usr/lib/<var>package</var>/examples</file> with symbolic
9193           links to them from
9194           <file>/usr/share/doc/<var>package</var>/examples</file>, or the
9195           latter directory itself may be a symbolic link to the
9196           former.
9197         </p>
9198
9199         <p>
9200           If the purpose of a package is to provide examples, then the
9201           example files may be installed into
9202           <file>/usr/share/doc/<var>package</var></file>.
9203         </p>
9204       </sect>
9205
9206       <sect id="changelogs">
9207         <heading>Changelog files</heading>
9208
9209         <p>
9210           Packages that are not Debian-native must contain a
9211           compressed copy of the <file>debian/changelog</file> file from
9212           the Debian source tree in
9213           <file>/usr/share/doc/<var>package</var></file> with the name
9214           <file>changelog.Debian.gz</file>.
9215         </p>
9216
9217         <p>
9218           If an upstream changelog is available, it should be accessible as
9219           <file>/usr/share/doc/<var>package</var>/changelog.gz</file> in
9220           plain text.  If the upstream changelog is distributed in
9221           HTML, it should be made available in that form as
9222           <file>/usr/share/doc/<var>package</var>/changelog.html.gz</file>
9223           and a plain text <file>changelog.gz</file> should be generated
9224           from it using, for example, <tt>lynx -dump -nolist</tt>.  If
9225           the upstream changelog files do not already conform to this
9226           naming convention, then this may be achieved either by
9227           renaming the files, or by adding a symbolic link, at the
9228           maintainer's discretion.<footnote>
9229               Rationale: People should not have to look in places for
9230               upstream changelogs merely because they are given
9231               different names or are distributed in HTML format.
9232           </footnote>
9233         </p>
9234
9235         <p>
9236           All of these files should be installed compressed using
9237           <tt>gzip -9</tt>, as they will become large with time even
9238           if they start out small.
9239         </p>
9240
9241         <p>
9242           If the package has only one changelog which is used both as
9243           the Debian changelog and the upstream one because there is
9244           no separate upstream maintainer then that changelog should
9245           usually be installed as
9246           <file>/usr/share/doc/<var>package</var>/changelog.gz</file>; if
9247           there is a separate upstream maintainer, but no upstream
9248           changelog, then the Debian changelog should still be called
9249           <file>changelog.Debian.gz</file>.
9250         </p>
9251
9252         <p>
9253           For details about the format and contents of the Debian
9254           changelog file, please see <ref id="dpkgchangelog">.
9255         </p>
9256       </sect>
9257     </chapt>
9258
9259     <appendix id="pkg-scope">
9260       <heading>Introduction and scope of these appendices</heading>
9261
9262       <p>
9263         These appendices are taken essentially verbatim from the
9264         now-deprecated Packaging Manual, version 3.2.1.0.  They are
9265         the chapters which are likely to be of use to package
9266         maintainers and which have not already been included in the
9267         policy document itself. Most of these sections are very likely
9268         not relevant to policy; they should be treated as
9269         documentation for the packaging system. Please note that these
9270         appendices are included for convenience, and for historical
9271         reasons: they used to be part of policy package, and they have
9272         not yet been incorporated into dpkg documentation. However,
9273         they still have value, and hence they are presented here.
9274       </p>
9275
9276       <p>
9277         They have not yet been checked to ensure that they are
9278         compatible with the contents of policy, and if there are any
9279         contradictions, the version in the main policy document takes
9280         precedence.  The remaining chapters of the old Packaging
9281         Manual have also not been read in detail to ensure that there
9282         are not parts which have been left out.  Both of these will be
9283         done in due course.
9284       </p>
9285
9286       <p>
9287         Certain parts of the Packaging manual were integrated into the
9288         Policy Manual proper, and removed from the appendices. Links
9289         have been placed from the old locations to the new ones.
9290       </p>
9291
9292       <p>
9293         <prgn>dpkg</prgn> is a suite of programs for creating binary
9294         package files and installing and removing them on Unix
9295         systems.<footnote>
9296             <prgn>dpkg</prgn> is targeted primarily at Debian
9297             GNU/Linux, but may work on or be ported to other
9298             systems.
9299         </footnote>
9300       </p>
9301
9302       <p>
9303         The binary packages are designed for the management of
9304         installed executable programs (usually compiled binaries) and
9305         their associated data, though source code examples and
9306         documentation are provided as part of some packages.</p>
9307
9308       <p>
9309         This manual describes the technical aspects of creating Debian
9310         binary packages (<file>.deb</file> files).  It documents the
9311         behavior of the package management programs
9312         <prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and the way
9313         they interact with packages.</p>
9314
9315       <p>
9316         It also documents the interaction between
9317         <prgn>dselect</prgn>'s core and the access method scripts it
9318         uses to actually install the selected packages, and describes
9319         how to create a new access method.</p>
9320
9321       <p>
9322         This manual does not go into detail about the options and
9323         usage of the package building and installation tools.  It
9324         should therefore be read in conjunction with those programs'
9325         man pages.
9326       </p>
9327
9328       <p>
9329         The utility programs which are provided with <prgn>dpkg</prgn>
9330         for managing various system configuration and similar issues,
9331         such as <prgn>update-rc.d</prgn> and
9332         <prgn>install-info</prgn>, are not described in detail here -
9333         please see their man pages.
9334       </p>
9335
9336       <p>
9337         It is assumed that the reader is reasonably familiar with the
9338         <prgn>dpkg</prgn> System Administrators' manual.
9339         Unfortunately this manual does not yet exist.
9340       </p>
9341
9342       <p>
9343         The Debian version of the FSF's GNU hello program is provided
9344         as an example for people wishing to create Debian
9345         packages. The Debian <prgn>debmake</prgn> package is
9346         recommended as a very helpful tool in creating and maintaining
9347         Debian packages. However, while the tools and examples are
9348         helpful, they do not replace the need to read and follow the
9349         Policy and Programmer's Manual.</p>
9350     </appendix>
9351
9352     <appendix id="pkg-binarypkg">
9353       <heading>Binary packages (from old Packaging Manual)</heading>
9354
9355       <p>
9356         The binary package has two main sections.  The first part
9357         consists of various control information files and scripts used
9358         by <prgn>dpkg</prgn> when installing and removing.  See <ref
9359         id="pkg-controlarea">.
9360       </p>
9361
9362       <p>
9363         The second part is an archive containing the files and
9364         directories to be installed.
9365       </p>
9366
9367       <p>
9368         In the future binary packages may also contain other
9369         components, such as checksums and digital signatures. The
9370         format for the archive is described in full in the
9371         <file>deb(5)</file> man page.
9372       </p>
9373
9374
9375       <sect id="pkg-bincreating"><heading>Creating package files -
9376       <prgn>dpkg-deb</prgn>
9377         </heading>
9378
9379         <p>
9380           All manipulation of binary package files is done by
9381           <prgn>dpkg-deb</prgn>; it's the only program that has
9382           knowledge of the format.  (<prgn>dpkg-deb</prgn> may be
9383           invoked by calling <prgn>dpkg</prgn>, as <prgn>dpkg</prgn>
9384           will spot that the options requested are appropriate to
9385           <prgn>dpkg-deb</prgn> and invoke that instead with the same
9386           arguments.)
9387         </p>
9388
9389         <p>
9390           In order to create a binary package you must make a
9391           directory tree which contains all the files and directories
9392           you want to have in the file system data part of the package.
9393           In Debian-format source packages this directory is usually
9394           <file>debian/tmp</file>, relative to the top of the package's
9395           source tree.
9396         </p>
9397
9398         <p>
9399           They should have the locations (relative to the root of the
9400           directory tree you're constructing) ownerships and
9401           permissions which you want them to have on the system when
9402           they are installed.
9403         </p>
9404
9405         <p>
9406           With current versions of <prgn>dpkg</prgn> the uid/username
9407           and gid/groupname mappings for the users and groups being
9408           used should be the same on the system where the package is
9409           built and the one where it is installed.
9410         </p>
9411
9412         <p>
9413           You need to add one special directory to the root of the
9414           miniature file system tree you're creating:
9415           <prgn>DEBIAN</prgn>.  It should contain the control
9416           information files, notably the binary package control file
9417           (see <ref id="pkg-controlfile">).
9418         </p>
9419
9420         <p>
9421           The <prgn>DEBIAN</prgn> directory will not appear in the
9422           file system archive of the package, and so won't be installed
9423           by <prgn>dpkg</prgn> when the package is unpacked.
9424         </p>
9425
9426         <p>
9427           When you've prepared the package, you should invoke:
9428           <example>
9429   dpkg --build <var>directory</var>
9430           </example>
9431         </p>
9432
9433         <p>
9434           This will build the package in
9435           <file><var>directory</var>.deb</file>.  (<prgn>dpkg</prgn> knows
9436           that <tt>--build</tt> is a <prgn>dpkg-deb</prgn> option, so
9437           it invokes <prgn>dpkg-deb</prgn> with the same arguments to
9438           build the package.)
9439         </p>
9440
9441         <p>
9442           See the man page <manref name="dpkg-deb" section="8"> for details of how
9443           to examine the contents of this newly-created file.  You may find the
9444           output of following commands enlightening:
9445           <example>
9446   dpkg-deb --info <var>filename</var>.deb
9447   dpkg-deb --contents <var>filename</var>.deb
9448   dpkg --contents <var>filename</var>.deb
9449           </example>
9450           To view the copyright file for a package you could use this command:
9451           <example>
9452   dpkg --fsys-tarfile <var>filename</var>.deb | tar xOf - --wildcards \*/copyright | pager
9453           </example>
9454         </p>
9455       </sect>
9456
9457       <sect id="pkg-controlarea">
9458         <heading>Package control information files</heading>
9459
9460         <p>
9461           The control information portion of a binary package is a
9462           collection of files with names known to <prgn>dpkg</prgn>.
9463           It will treat the contents of these files specially - some
9464           of them contain information used by <prgn>dpkg</prgn> when
9465           installing or removing the package; others are scripts which
9466           the package maintainer wants <prgn>dpkg</prgn> to run.
9467         </p>
9468
9469         <p>
9470           It is possible to put other files in the package control
9471           area, but this is not generally a good idea (though they
9472           will largely be ignored).
9473         </p>
9474
9475         <p>
9476           Here is a brief list of the control info files supported by
9477           <prgn>dpkg</prgn> and a summary of what they're used for.
9478         </p>
9479
9480         <p>
9481           <taglist>
9482             <tag><tt>control</tt>
9483             <item>
9484               <p>
9485                 This is the key description file used by
9486                 <prgn>dpkg</prgn>.  It specifies the package's name
9487                 and version, gives its description for the user,
9488                 states its relationships with other packages, and so
9489                 forth.  See <ref id="sourcecontrolfiles"> and
9490                 <ref id="binarycontrolfiles">.
9491               </p>
9492
9493               <p>
9494                 It is usually generated automatically from information
9495                 in the source package by the
9496                 <prgn>dpkg-gencontrol</prgn> program, and with
9497                 assistance from <prgn>dpkg-shlibdeps</prgn>.
9498                 See <ref id="pkg-sourcetools">.
9499               </p>
9500             </item>
9501
9502             <tag><tt>postinst</tt>, <tt>preinst</tt>, <tt>postrm</tt>,
9503                  <tt>prerm</tt>
9504             </tag>
9505             <item>
9506               <p>
9507                 These are executable files (usually scripts) which
9508                 <prgn>dpkg</prgn> runs during installation, upgrade
9509                 and removal of packages.  They allow the package to
9510                 deal with matters which are particular to that package
9511                 or require more complicated processing than that
9512                 provided by <prgn>dpkg</prgn>.  Details of when and
9513                 how they are called are in <ref id="maintainerscripts">.
9514               </p>
9515
9516               <p>
9517                 It is very important to make these scripts idempotent.
9518                 See <ref id="idempotency">.
9519               </p>
9520
9521               <p>
9522                 The maintainer scripts are guaranteed to run with a
9523                 controlling terminal and can interact with the user.
9524                 See <ref id="controllingterminal">.
9525               </p>
9526             </item>
9527
9528             <tag><tt>conffiles</tt>
9529             </tag>
9530             <item>
9531                 This file contains a list of configuration files which
9532                 are to be handled automatically by <prgn>dpkg</prgn>
9533                 (see <ref id="pkg-conffiles">).  Note that not necessarily
9534                 every configuration file should be listed here.
9535             </item>
9536
9537             <tag><tt>shlibs</tt>
9538             </tag>
9539             <item>
9540                 This file contains a list of the shared libraries
9541                 supplied by the package, with dependency details for
9542                 each.  This is used by <prgn>dpkg-shlibdeps</prgn>
9543                 when it determines what dependencies are required in a
9544                 package control file. The <tt>shlibs</tt> file format
9545                 is described on <ref id="shlibs">.
9546             </item>
9547           </taglist>
9548         </p>
9549
9550       <sect id="pkg-controlfile">
9551         <heading>The main control information file: <tt>control</tt></heading>
9552
9553         <p>
9554           The most important control information file used by
9555           <prgn>dpkg</prgn> when it installs a package is
9556           <tt>control</tt>.  It contains all the package's "vital
9557           statistics".
9558         </p>
9559
9560         <p>
9561           The binary package control files of packages built from
9562           Debian sources are made by a special tool,
9563           <prgn>dpkg-gencontrol</prgn>, which reads
9564           <file>debian/control</file> and <file>debian/changelog</file> to
9565           find the information it needs.  See <ref id="pkg-sourcepkg"> for
9566           more details.
9567         </p>
9568
9569         <p>
9570           The fields in binary package control files are listed in
9571           <ref id="binarycontrolfiles">.
9572         </p>
9573
9574         <p>
9575           A description of the syntax of control files and the purpose
9576           of the fields is available in <ref id="controlfields">.
9577         </p>
9578       </sect>
9579
9580       <sect>
9581         <heading>Time Stamps</heading>
9582
9583         <p>
9584           See <ref id="timestamps">.
9585         </p>
9586       </sect>
9587     </appendix>
9588
9589     <appendix id="pkg-sourcepkg">
9590       <heading>Source packages (from old Packaging Manual) </heading>
9591
9592       <p>
9593         The Debian binary packages in the distribution are generated
9594         from Debian sources, which are in a special format to assist
9595         the easy and automatic building of binaries.
9596       </p>
9597
9598       <sect id="pkg-sourcetools">
9599         <heading>Tools for processing source packages</heading>
9600
9601         <p>
9602           Various tools are provided for manipulating source packages;
9603           they pack and unpack sources and help build of binary
9604           packages and help manage the distribution of new versions.
9605         </p>
9606
9607         <p>
9608           They are introduced and typical uses described here; see
9609           <manref name="dpkg-source" section="1"> for full
9610           documentation about their arguments and operation.
9611         </p>
9612
9613         <p>
9614           For examples of how to construct a Debian source package,
9615           and how to use those utilities that are used by Debian
9616           source packages, please see the <prgn>hello</prgn> example
9617           package.
9618         </p>
9619
9620         <sect1 id="pkg-dpkg-source">
9621           <heading>
9622             <prgn>dpkg-source</prgn> - packs and unpacks Debian source
9623             packages
9624           </heading>
9625
9626           <p>
9627             This program is frequently used by hand, and is also
9628             called from package-independent automated building scripts
9629             such as <prgn>dpkg-buildpackage</prgn>.
9630           </p>
9631
9632           <p>
9633             To unpack a package it is typically invoked with
9634             <example>
9635   dpkg-source -x <var>.../path/to/filename</var>.dsc
9636             </example>
9637           </p>
9638
9639            <p>
9640             with the <file><var>filename</var>.tar.gz</file> and
9641             <file><var>filename</var>.diff.gz</file> (if applicable) in
9642             the same directory.  It unpacks into
9643             <file><var>package</var>-<var>version</var></file>, and if
9644             applicable
9645             <file><var>package</var>-<var>version</var>.orig</file>, in
9646             the current directory.
9647           </p>
9648
9649           <p>
9650             To create a packed source archive it is typically invoked:
9651             <example>
9652   dpkg-source -b <var>package</var>-<var>version</var>
9653           </example>
9654           </p>
9655
9656           <p>
9657             This will create the <file>.dsc</file>, <file>.tar.gz</file> and
9658             <file>.diff.gz</file> (if appropriate) in the current
9659             directory.  <prgn>dpkg-source</prgn> does not clean the
9660             source tree first - this must be done separately if it is
9661             required.
9662           </p>
9663
9664           <p>
9665             See also <ref id="pkg-sourcearchives">.</p>
9666         </sect1>
9667
9668
9669         <sect1 id="pkg-dpkg-buildpackage">
9670           <heading>
9671             <prgn>dpkg-buildpackage</prgn> - overall package-building
9672             control script
9673           </heading>
9674
9675           <p>
9676             <prgn>dpkg-buildpackage</prgn> is a script which invokes
9677             <prgn>dpkg-source</prgn>, the <file>debian/rules</file>
9678             targets <tt>clean</tt>, <tt>build</tt> and
9679             <tt>binary</tt>, <prgn>dpkg-genchanges</prgn> and
9680             <prgn>gpg</prgn> (or <prgn>pgp</prgn>) to build a signed
9681             source and binary package upload.
9682           </p>
9683
9684           <p>
9685             It is usually invoked by hand from the top level of the
9686             built or unbuilt source directory.  It may be invoked with
9687             no arguments; useful arguments include:
9688             <taglist compact="compact">
9689               <tag><tt>-uc</tt>, <tt>-us</tt></tag>
9690               <item>
9691                 <p>
9692                   Do not sign the <tt>.changes</tt> file or the
9693                   source package <tt>.dsc</tt> file, respectively.</p>
9694               </item>
9695               <tag><tt>-p<var>sign-command</var></tt></tag>
9696               <item>
9697                 <p>
9698                   Invoke <var>sign-command</var> instead of finding
9699                   <tt>gpg</tt> or <tt>pgp</tt> on the <prgn>PATH</prgn>.
9700                   <var>sign-command</var> must behave just like
9701                   <prgn>gpg</prgn> or <tt>pgp</tt>.</p>
9702               </item>
9703               <tag><tt>-r<var>root-command</var></tt></tag>
9704               <item>
9705                 <p>
9706                   When root privilege is required, invoke the command
9707                   <var>root-command</var>.  <var>root-command</var>
9708                   should invoke its first argument as a command, from
9709                   the <prgn>PATH</prgn> if necessary, and pass its
9710                   second and subsequent arguments to the command it
9711                   calls.  If no <var>root-command</var> is supplied
9712                   then <var>dpkg-buildpackage</var> will take no
9713                   special action to gain root privilege, so that for
9714                   most packages it will have to be invoked as root to
9715                   start with.</p>
9716               </item>
9717               <tag><tt>-b</tt>, <tt>-B</tt></tag>
9718               <item>
9719                 <p>
9720                   Two types of binary-only build and upload - see
9721                   <manref name="dpkg-source" section="1">.
9722                 </p>
9723               </item>
9724             </taglist>
9725           </p>
9726         </sect1>
9727
9728         <sect1 id="pkg-dpkg-gencontrol">
9729           <heading>
9730             <prgn>dpkg-gencontrol</prgn> - generates binary package
9731             control files
9732           </heading>
9733
9734           <p>
9735             This program is usually called from <file>debian/rules</file>
9736             (see <ref id="pkg-sourcetree">) in the top level of the source
9737             tree.
9738           </p>
9739
9740           <p>
9741             This is usually done just before the files and directories in the
9742             temporary directory tree where the package is being built have their
9743             permissions and ownerships set and the package is constructed using
9744             <prgn>dpkg-deb/</prgn>
9745               <footnote>
9746                 This is so that the control file which is produced has
9747                 the right permissions
9748             </footnote>.
9749           </p>
9750
9751           <p>
9752             <prgn>dpkg-gencontrol</prgn> must be called after all the
9753             files which are to go into the package have been placed in
9754             the temporary build directory, so that its calculation of
9755             the installed size of a package is correct.
9756           </p>
9757
9758           <p>
9759             It is also necessary for <prgn>dpkg-gencontrol</prgn> to
9760             be run after <prgn>dpkg-shlibdeps</prgn> so that the
9761             variable substitutions created by
9762             <prgn>dpkg-shlibdeps</prgn> in <file>debian/substvars</file>
9763             are available.
9764           </p>
9765
9766           <p>
9767             For a package which generates only one binary package, and
9768             which builds it in <file>debian/tmp</file> relative to the top
9769             of the source package, it is usually sufficient to call
9770             <prgn>dpkg-gencontrol</prgn>.
9771           </p>
9772
9773           <p>
9774             Sources which build several binaries will typically need
9775             something like:
9776             <example>
9777   dpkg-gencontrol -Pdebian/tmp-<var>pkg</var> -p<var>package</var>
9778             </example> The <tt>-P</tt> tells
9779             <prgn>dpkg-gencontrol</prgn> that the package is being
9780             built in a non-default directory, and the <tt>-p</tt>
9781             tells it which package's control file should be generated.
9782           </p>
9783
9784           <p>
9785             <prgn>dpkg-gencontrol</prgn> also adds information to the
9786             list of files in <file>debian/files</file>, for the benefit of
9787             (for example) a future invocation of
9788             <prgn>dpkg-genchanges</prgn>.</p>
9789         </sect1>
9790
9791         <sect1 id="pkg-dpkg-shlibdeps">
9792           <heading>
9793             <prgn>dpkg-shlibdeps</prgn> - calculates shared library
9794             dependencies
9795           </heading>
9796
9797           <p>
9798             This program is usually called from <file>debian/rules</file>
9799             just before <prgn>dpkg-gencontrol</prgn> (see <ref
9800             id="pkg-sourcetree">), in the top level of the source tree.
9801           </p>
9802
9803           <p>
9804             Its arguments are executables and shared libraries
9805             <footnote>
9806               <p>
9807                 They may be specified either in the locations in the
9808                 source tree where they are created or in the locations
9809                 in the temporary build tree where they are installed
9810                 prior to binary package creation.
9811               </p>
9812             </footnote> for which shared library dependencies should
9813             be included in the binary package's control file.
9814           </p>
9815
9816           <p>
9817             If some of the found shared libraries should only
9818             warrant a <tt>Recommends</tt> or <tt>Suggests</tt>, or if
9819             some warrant a <tt>Pre-Depends</tt>, this can be achieved
9820             by using the <tt>-d<var>dependency-field</var></tt> option
9821             before those executable(s).  (Each <tt>-d</tt> option
9822             takes effect until the next <tt>-d</tt>.)
9823           </p>
9824
9825           <p>
9826             <prgn>dpkg-shlibdeps</prgn> does not directly cause the
9827             output control file to be modified.  Instead by default it
9828             adds to the <file>debian/substvars</file> file variable
9829             settings like <tt>shlibs:Depends</tt>.  These variable
9830             settings must be referenced in dependency fields in the
9831             appropriate per-binary-package sections of the source
9832             control file.
9833           </p>
9834
9835           <p>
9836             For example, a package that generates an essential part
9837             which requires dependencies, and optional parts that 
9838             which only require a recommendation, would separate those
9839             two sets of dependencies into two different fields.<footnote>
9840                 At the time of writing, an example for this was the
9841                 <package/xmms/ package, with Depends used for the xmms
9842                 executable, Recommends for the plug-ins and Suggests for
9843                 even more optional features provided by unzip.
9844             </footnote>
9845             It can say in its <file>debian/rules</file>:
9846             <example>
9847   dpkg-shlibdeps -dDepends <var>program anotherprogram ...</var> \
9848                  -dRecommends <var>optionalpart anotheroptionalpart</var>
9849             </example>
9850             and then in its main control file <file>debian/control</file>:
9851             <example>
9852   <var>...</var>
9853   Depends: ${shlibs:Depends}
9854   Recommends: ${shlibs:Recommends}
9855   <var>...</var>
9856             </example>
9857           </p>
9858
9859           <p>
9860             Sources which produce several binary packages with
9861             different shared library dependency requirements can use
9862             the <tt>-p<var>varnameprefix</var></tt> option to override
9863             the default <tt>shlibs:</tt> prefix (one invocation of
9864             <prgn>dpkg-shlibdeps</prgn> per setting of this option).
9865             They can thus produce several sets of dependency
9866             variables, each of the form
9867             <tt><var>varnameprefix</var>:<var>dependencyfield</var></tt>,
9868             which can be referred to in the appropriate parts of the
9869             binary package control files.
9870           </p>
9871         </sect1>
9872
9873
9874         <sect1 id="pkg-dpkg-distaddfile">
9875           <heading>
9876             <prgn>dpkg-distaddfile</prgn> - adds a file to
9877             <file>debian/files</file>
9878           </heading>
9879
9880           <p>
9881             Some packages' uploads need to include files other than
9882             the source and binary package files.
9883           </p>
9884
9885           <p>
9886             <prgn>dpkg-distaddfile</prgn> adds a file to the
9887             <file>debian/files</file> file so that it will be included in
9888             the <file>.changes</file> file when
9889             <prgn>dpkg-genchanges</prgn> is run.
9890           </p>
9891
9892           <p>
9893             It is usually invoked from the <tt>binary</tt> target of
9894             <file>debian/rules</file>:
9895             <example>
9896   dpkg-distaddfile <var>filename</var> <var>section</var> <var>priority</var>
9897             </example>
9898             The <var>filename</var> is relative to the directory where
9899             <prgn>dpkg-genchanges</prgn> will expect to find it - this
9900             is usually the directory above the top level of the source
9901             tree.  The <file>debian/rules</file> target should put the
9902             file there just before or just after calling
9903             <prgn>dpkg-distaddfile</prgn>.
9904           </p>
9905
9906           <p>
9907             The <var>section</var> and <var>priority</var> are passed
9908             unchanged into the resulting <file>.changes</file> file.
9909           </p>
9910         </sect1>
9911
9912
9913         <sect1 id="pkg-dpkg-genchanges">
9914           <heading>
9915             <prgn>dpkg-genchanges</prgn> - generates a <file>.changes</file>
9916             upload control file
9917           </heading>
9918
9919           <p>
9920             This program is usually called by package-independent
9921             automatic building scripts such as
9922             <prgn>dpkg-buildpackage</prgn>, but it may also be called
9923             by hand.
9924           </p>
9925
9926           <p>
9927             It is usually called in the top level of a built source
9928             tree, and when invoked with no arguments will print out a
9929             straightforward <file>.changes</file> file based on the
9930             information in the source package's changelog and control
9931             file and the binary and source packages which should have
9932             been built.
9933           </p>
9934         </sect1>
9935
9936
9937         <sect1 id="pkg-dpkg-parsechangelog">
9938           <heading>
9939             <prgn>dpkg-parsechangelog</prgn> - produces parsed
9940             representation of a changelog
9941           </heading>
9942
9943           <p>
9944             This program is used internally by
9945             <prgn>dpkg-source</prgn> et al.  It may also occasionally
9946             be useful in <file>debian/rules</file> and elsewhere.  It
9947             parses a changelog, <file>debian/changelog</file> by default,
9948             and prints a control-file format representation of the
9949             information in it to standard output.
9950           </p>
9951         </sect1>
9952
9953         <sect1 id="pkg-dpkg-architecture">
9954           <heading>
9955             <prgn>dpkg-architecture</prgn> - information about the build and
9956             host system
9957           </heading>
9958
9959           <p>
9960             This program can be used manually, but is also invoked by
9961             <tt>dpkg-buildpackage</tt> or <file>debian/rules</file> to set
9962             environment or make variables which specify the build and host
9963             architecture for the package building process.
9964           </p>
9965         </sect1>
9966       </sect>
9967
9968       <sect id="pkg-sourcetree">
9969         <heading>The Debianised source tree</heading>
9970
9971         <p>
9972           The source archive scheme described later is intended to
9973           allow a Debianised source tree with some associated control
9974           information to be reproduced and transported easily.  The
9975           Debianised source tree is a version of the original program
9976           with certain files added for the benefit of the
9977           Debianisation process, and with any other changes required
9978           made to the rest of the source code and installation
9979           scripts.
9980         </p>
9981
9982         <p>
9983           The extra files created for Debian are in the subdirectory
9984           <file>debian</file> of the top level of the Debianised source
9985           tree.  They are described below.
9986         </p>
9987
9988         <sect1 id="pkg-debianrules">
9989           <heading><file>debian/rules</file> - the main building script</heading>
9990
9991           <p>
9992             See <ref id="debianrules">.
9993           </p>
9994         </sect1>
9995
9996
9997         <sect1 id="pkg-dpkgchangelog">
9998           <heading><file>debian/changelog</file></heading>
9999
10000           <p>
10001             See <ref id="dpkgchangelog">.
10002           </p>
10003
10004           <sect2><heading>Defining alternative changelog formats
10005             </heading>
10006
10007             <p>
10008               It is possible to use a different format to the standard
10009               one, by providing a parser for the format you wish to
10010               use.
10011             </p>
10012
10013             <p>
10014               In order to have <tt>dpkg-parsechangelog</tt> run your
10015               parser, you must include a line within the last 40 lines
10016               of your file matching the Perl regular expression:
10017               <tt>\schangelog-format:\s+([0-9a-z]+)\W</tt> The part in
10018               parentheses should be the name of the format.  For
10019               example, you might say:
10020               <example>
10021   @@@ changelog-format: joebloggs @@@
10022               </example>
10023               Changelog format names are non-empty strings of alphanumerics.
10024             </p>
10025
10026             <p>
10027               If such a line exists then <tt>dpkg-parsechangelog</tt>
10028               will look for the parser as
10029               <file>/usr/lib/dpkg/parsechangelog/<var>format-name</var></file>
10030               or
10031               <file>/usr/local/lib/dpkg/parsechangelog/<var>format-name</var></file>;
10032               it is an error for it not to find it, or for it not to
10033               be an executable program.  The default changelog format
10034               is <tt>dpkg</tt>, and a parser for it is provided with
10035               the <tt>dpkg</tt> package.
10036             </p>
10037
10038             <p>
10039               The parser will be invoked with the changelog open on
10040               standard input at the start of the file.  It should read
10041               the file (it may seek if it wishes) to determine the
10042               information required and return the parsed information
10043               to standard output in the form of a series of control
10044               fields in the standard format.  By default it should
10045               return information about only the most recent version in
10046               the changelog; it should accept a
10047               <tt>-v<var>version</var></tt> option to return changes
10048               information from all versions present <em>strictly
10049               after</em> <var>version</var>, and it should then be an
10050               error for <var>version</var> not to be present in the
10051               changelog.
10052             </p>
10053
10054             <p>
10055               The fields are:
10056               <list compact="compact">
10057                 <item><qref id="f-Source"><tt>Source</tt></qref></item>
10058                 <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
10059                 <item><qref id="f-Distribution"><tt>Distribution</tt></qref> (mandatory)</item>
10060                 <item><qref id="f-Urgency"><tt>Urgency</tt></qref> (mandatory)</item>
10061                 <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
10062                 <item><qref id="f-Date"><tt>Date</tt></qref></item>
10063                 <item><qref id="f-Changes"><tt>Changes</tt></qref> (mandatory)</item>
10064               </list>
10065             </p>
10066
10067             <p>
10068               If several versions are being returned (due to the use
10069               of <tt>-v</tt>), the urgency value should be of the
10070               highest urgency code listed at the start of any of the
10071               versions requested followed by the concatenated
10072               (space-separated) comments from all the versions
10073               requested; the maintainer, version, distribution and
10074               date should always be from the most recent version.
10075             </p>
10076
10077             <p>
10078               For the format of the <tt>Changes</tt> field see
10079               <ref id="f-Changes">.
10080             </p>
10081
10082             <p>
10083               If the changelog format which is being parsed always or
10084               almost always leaves a blank line between individual
10085               change notes these blank lines should be stripped out,
10086               so as to make the resulting output compact.
10087             </p>
10088
10089             <p>
10090               If the changelog format does not contain date or package
10091               name information this information should be omitted from
10092               the output.  The parser should not attempt to synthesize
10093               it or find it from other sources.
10094             </p>
10095
10096             <p>
10097               If the changelog does not have the expected format the
10098               parser should exit with a nonzero exit status, rather
10099               than trying to muddle through and possibly generating
10100               incorrect output.
10101             </p>
10102
10103             <p>
10104               A changelog parser may not interact with the user at
10105               all.
10106             </p>
10107           </sect2>
10108         </sect1>
10109
10110         <sect1 id="pkg-srcsubstvars">
10111           <heading><file>debian/substvars</file> and variable substitutions</heading>
10112
10113           <p>
10114             See <ref id="substvars">.
10115           </p>
10116
10117         </sect1>
10118
10119         <sect1>
10120           <heading><file>debian/files</file></heading>
10121
10122           <p>
10123             See <ref id="debianfiles">.
10124           </p>
10125         </sect1>
10126
10127         <sect1><heading><file>debian/tmp</file>
10128           </heading>
10129
10130           <p>
10131             This is the canonical temporary location for the
10132             construction of binary packages by the <tt>binary</tt>
10133             target.  The directory <file>tmp</file> serves as the root of
10134             the file system tree as it is being constructed (for
10135             example, by using the package's upstream makefiles install
10136             targets and redirecting the output there), and it also
10137             contains the <tt>DEBIAN</tt> subdirectory.  See <ref
10138             id="pkg-bincreating">.
10139           </p>
10140
10141           <p>
10142             If several binary packages are generated from the same
10143             source tree it is usual to use several
10144             <file>debian/tmp<var>something</var></file> directories, for
10145             example <file>tmp-a</file> or <file>tmp-doc</file>.
10146           </p>
10147
10148           <p>
10149             Whatever <file>tmp</file> directories are created and used by
10150             <tt>binary</tt> must of course be removed by the
10151             <tt>clean</tt> target.</p></sect1>
10152       </sect>
10153
10154
10155       <sect id="pkg-sourcearchives"><heading>Source packages as archives
10156         </heading>
10157
10158         <p>
10159           As it exists on the FTP site, a Debian source package
10160           consists of three related files.  You must have the right
10161           versions of all three to be able to use them.
10162         </p>
10163
10164         <p>
10165           <taglist>
10166             <tag>Debian source control file - <tt>.dsc</tt></tag>
10167             <item>
10168                 This file is a control file used by <prgn>dpkg-source</prgn>
10169                 to extract a source package.
10170                 See <ref id="debiansourcecontrolfiles">.
10171             </item>
10172
10173             <tag>
10174               Original source archive -
10175               <file>
10176                 <var>package</var>_<var>upstream-version</var>.orig.tar.gz
10177               </file>
10178             </tag>
10179
10180             <item>
10181               <p>
10182                 This is a compressed (with <tt>gzip -9</tt>)
10183                 <prgn>tar</prgn> file containing the source code from
10184                 the upstream authors of the program.
10185               </p>
10186             </item>
10187
10188             <tag>
10189               Debianisation diff -
10190               <file>
10191                 <var>package</var>_<var>upstream_version-revision</var>.diff.gz
10192               </file>
10193             </tag>
10194             <item>
10195
10196               <p>
10197                 This is a unified context diff (<tt>diff -u</tt>)
10198                 giving the changes which are required to turn the
10199                 original source into the Debian source.  These changes
10200                 may only include editing and creating plain files.
10201                 The permissions of files, the targets of symbolic
10202                 links and the characteristics of special files or
10203                 pipes may not be changed and no files may be removed
10204                 or renamed.
10205               </p>
10206
10207               <p>
10208                 All the directories in the diff must exist, except the
10209                 <file>debian</file> subdirectory of the top of the source
10210                 tree, which will be created by
10211                 <prgn>dpkg-source</prgn> if necessary when unpacking.
10212               </p>
10213
10214               <p>
10215                 The <prgn>dpkg-source</prgn> program will
10216                 automatically make the <file>debian/rules</file> file
10217                 executable (see below).</p></item>
10218           </taglist>
10219         </p>
10220
10221         <p>
10222           If there is no original source code - for example, if the
10223           package is specially prepared for Debian or the Debian
10224           maintainer is the same as the upstream maintainer - the
10225           format is slightly different: then there is no diff, and the
10226           tarfile is named
10227           <file><var>package</var>_<var>version</var>.tar.gz</file>,
10228           and preferably contains a directory named
10229           <file><var>package</var>-<var>version</var></file>.
10230         </p>
10231       </sect>
10232
10233       <sect>
10234         <heading>Unpacking a Debian source package without <prgn>dpkg-source</prgn></heading>
10235
10236         <p>
10237           <tt>dpkg-source -x</tt> is the recommended way to unpack a
10238           Debian source package.  However, if it is not available it
10239           is possible to unpack a Debian source archive as follows:
10240         <enumlist compact="compact">
10241           <item>
10242             <p>
10243               Untar the tarfile, which will create a <file>.orig</file>
10244               directory.</p>
10245           </item>
10246           <item>
10247             <p>Rename the <file>.orig</file> directory to
10248               <file><var>package</var>-<var>version</var></file>.</p>
10249           </item>
10250             <item>
10251             <p>
10252               Create the subdirectory <file>debian</file> at the top of
10253               the source tree.</p>
10254           </item>
10255           <item><p>Apply the diff using <tt>patch -p0</tt>.</p>
10256           </item>
10257           <item><p>Untar the tarfile again if you want a copy of the original
10258               source code alongside the Debianised version.</p>
10259           </item>
10260         </enumlist>
10261
10262         <p>
10263           It is not possible to generate a valid Debian source archive
10264           without using <prgn>dpkg-source</prgn>.  In particular,
10265           attempting to use <prgn>diff</prgn> directly to generate the
10266           <file>.diff.gz</file> file will not work.
10267         </p>
10268
10269         <sect1>
10270           <heading>Restrictions on objects in source packages</heading>
10271
10272           <p>
10273             The source package may not contain any hard links
10274             <footnote>
10275                 This is not currently detected when building source
10276                 packages, but only when extracting
10277                 them.
10278             </footnote>
10279             <footnote>
10280                 Hard links may be permitted at some point in the
10281                 future, but would require a fair amount of
10282                 work.
10283             </footnote>, device special files, sockets or setuid or
10284             setgid files.
10285             <footnote>
10286                 Setgid directories are allowed.
10287             </footnote>
10288           </p>
10289
10290           <p>
10291             The source packaging tools manage the changes between the
10292             original and Debianised source using <prgn>diff</prgn> and
10293             <prgn>patch</prgn>.  Turning the original source tree as
10294             included in the <file>.orig.tar.gz</file> into the debianised
10295             source must not involve any changes which cannot be
10296             handled by these tools.  Problematic changes which cause
10297             <prgn>dpkg-source</prgn> to halt with an error when
10298             building the source package are:
10299             <list compact="compact">
10300               <item><p>Adding or removing symbolic links, sockets or pipes.</p>
10301               </item>
10302               <item><p>Changing the targets of symbolic links.</p>
10303               </item>
10304               <item><p>Creating directories, other than <file>debian</file>.</p>
10305               </item>
10306               <item><p>Changes to the contents of binary files.</p></item>
10307             </list> Changes which cause <prgn>dpkg-source</prgn> to
10308             print a warning but continue anyway are:
10309             <list compact="compact">
10310               <item>
10311                 <p>
10312                   Removing files, directories or symlinks.
10313                   <footnote>
10314                       Renaming a file is not treated specially - it is
10315                       seen as the removal of the old file (which
10316                       generates a warning, but is otherwise ignored),
10317                       and the creation of the new one.
10318                   </footnote>
10319                 </p>
10320               </item>
10321               <item>
10322                 <p>
10323                   Changed text files which are missing the usual final
10324                   newline (either in the original or the modified
10325                   source tree).
10326                 </p>
10327               </item>
10328             </list>
10329             Changes which are not represented, but which are not detected by
10330             <prgn>dpkg-source</prgn>, are:
10331             <list compact="compact">
10332               <item><p>Changing the permissions of files (other than
10333                   <file>debian/rules</file>) and directories.</p></item>
10334             </list>
10335           </p>
10336
10337           <p>
10338             The <file>debian</file> directory and <file>debian/rules</file>
10339             are handled specially by <prgn>dpkg-source</prgn> - before
10340             applying the changes it will create the <file>debian</file>
10341             directory, and afterwards it will make
10342             <file>debian/rules</file> world-executable.
10343           </p>
10344         </sect1>
10345       </sect>
10346     </appendix>
10347
10348     <appendix id="pkg-controlfields">
10349       <heading>Control files and their fields (from old Packaging Manual)</heading>
10350
10351       <p>
10352         Many of the tools in the <prgn>dpkg</prgn> suite manipulate
10353         data in a common format, known as control files.  Binary and
10354         source packages have control data as do the <file>.changes</file>
10355         files which control the installation of uploaded files, and
10356         <prgn>dpkg</prgn>'s internal databases are in a similar
10357         format.
10358       </p>
10359
10360       <sect>
10361         <heading>Syntax of control files</heading>
10362
10363         <p>
10364           See <ref id="controlsyntax">.
10365         </p>
10366
10367         <p>
10368           It is important to note that there are several fields which
10369           are optional as far as <prgn>dpkg</prgn> and the related
10370           tools are concerned, but which must appear in every Debian
10371           package, or whose omission may cause problems.
10372         </p>
10373       </sect>
10374
10375       <sect>
10376         <heading>List of fields</heading>
10377
10378         <p>
10379           See <ref id="controlfieldslist">.
10380         </p>
10381
10382         <p>
10383           This section now contains only the fields that didn't belong
10384           to the Policy manual.
10385         </p>
10386
10387         <sect1 id="pkg-f-Filename">
10388           <heading><tt>Filename</tt> and <tt>MSDOS-Filename</tt></heading>
10389
10390           <p>
10391             These fields in <tt>Packages</tt> files give the
10392             filename(s) of (the parts of) a package in the
10393             distribution directories, relative to the root of the
10394             Debian hierarchy.  If the package has been split into
10395             several parts the parts are all listed in order, separated
10396             by spaces.
10397           </p>
10398         </sect1>
10399
10400         <sect1 id="pkg-f-Size">
10401           <heading><tt>Size</tt> and <tt>MD5sum</tt></heading>
10402
10403           <p>
10404             These fields in <file>Packages</file> files give the size (in
10405             bytes, expressed in decimal) and MD5 checksum of the
10406             file(s) which make(s) up a binary package in the
10407             distribution.  If the package is split into several parts
10408             the values for the parts are listed in order, separated by
10409             spaces.
10410           </p>
10411         </sect1>
10412
10413         <sect1 id="pkg-f-Status">
10414           <heading><tt>Status</tt></heading>
10415
10416           <p>
10417             This field in <prgn>dpkg</prgn>'s status file records
10418             whether the user wants a package installed, removed or
10419             left alone, whether it is broken (requiring
10420             re-installation) or not and what its current state on the
10421             system is.  Each of these pieces of information is a
10422             single word.
10423           </p>
10424         </sect1>
10425
10426         <sect1 id="pkg-f-Config-Version">
10427           <heading><tt>Config-Version</tt></heading>
10428
10429           <p>
10430             If a package is not installed or not configured, this
10431             field in <prgn>dpkg</prgn>'s status file records the last
10432             version of the package which was successfully
10433             configured.
10434           </p>
10435         </sect1>
10436
10437         <sect1 id="pkg-f-Conffiles">
10438           <heading><tt>Conffiles</tt></heading>
10439
10440           <p>
10441             This field in <prgn>dpkg</prgn>'s status file contains
10442             information about the automatically-managed configuration
10443             files held by a package.  This field should <em>not</em>
10444             appear anywhere in a package!
10445           </p>
10446         </sect1>
10447
10448         <sect1>
10449           <heading>Obsolete fields</heading>
10450
10451           <p>
10452             These are still recognized by <prgn>dpkg</prgn> but should
10453             not appear anywhere any more.
10454
10455             <taglist compact="compact">
10456
10457               <tag><tt>Revision</tt></tag>
10458               <tag><tt>Package-Revision</tt></tag>
10459               <tag><tt>Package_Revision</tt></tag>
10460               <item>
10461                   The Debian revision part of the package version was
10462                   at one point in a separate control file field.  This
10463                   field went through several names.
10464               </item>
10465
10466               <tag><tt>Recommended</tt></tag>
10467               <item>Old name for <tt>Recommends</tt>.</item>
10468
10469               <tag><tt>Optional</tt></tag>
10470               <item>Old name for <tt>Suggests</tt>.</item>
10471
10472               <tag><tt>Class</tt></tag>
10473               <item>Old name for <tt>Priority</tt>.</item>
10474
10475             </taglist>
10476           </p>
10477         </sect1>
10478       </sect>
10479
10480     </appendix>
10481
10482     <appendix id="pkg-conffiles">
10483       <heading>Configuration file handling (from old Packaging Manual)</heading>
10484
10485       <p>
10486         <prgn>dpkg</prgn> can do a certain amount of automatic
10487         handling of package configuration files.
10488       </p>
10489
10490       <p>
10491         Whether this mechanism is appropriate depends on a number of
10492         factors, but basically there are two approaches to any
10493         particular configuration file.
10494       </p>
10495
10496       <p>
10497         The easy method is to ship a best-effort configuration in the
10498         package, and use <prgn>dpkg</prgn>'s conffile mechanism to
10499         handle updates.  If the user is unlikely to want to edit the
10500         file, but you need them to be able to without losing their
10501         changes, and a new package with a changed version of the file
10502         is only released infrequently, this is a good approach.
10503       </p>
10504
10505       <p>
10506         The hard method is to build the configuration file from
10507         scratch in the <prgn>postinst</prgn> script, and to take the
10508         responsibility for fixing any mistakes made in earlier
10509         versions of the package automatically.  This will be
10510         appropriate if the file is likely to need to be different on
10511         each system.
10512       </p>
10513
10514       <sect><heading>Automatic handling of configuration files by
10515       <prgn>dpkg</prgn>
10516         </heading>
10517
10518         <p>
10519           A package may contain a control area file called
10520           <tt>conffiles</tt>.  This file should be a list of filenames
10521           of configuration files needing automatic handling, separated
10522           by newlines.  The filenames should be absolute pathnames,
10523           and the files referred to should actually exist in the
10524           package.
10525         </p>
10526
10527         <p>
10528           When a package is upgraded <prgn>dpkg</prgn> will process
10529           the configuration files during the configuration stage,
10530           shortly before it runs the package's <prgn>postinst</prgn>
10531           script,
10532         </p>
10533
10534         <p>
10535           For each file it checks to see whether the version of the
10536           file included in the package is the same as the one that was
10537           included in the last version of the package (the one that is
10538           being upgraded from); it also compares the version currently
10539           installed on the system with the one shipped with the last
10540           version.
10541         </p>
10542
10543         <p>
10544           If neither the user nor the package maintainer has changed
10545           the file, it is left alone.  If one or the other has changed
10546           their version, then the changed version is preferred - i.e.,
10547           if the user edits their file, but the package maintainer
10548           doesn't ship a different version, the user's changes will
10549           stay, silently, but if the maintainer ships a new version
10550           and the user hasn't edited it the new version will be
10551           installed (with an informative message).  If both have
10552           changed their version the user is prompted about the problem
10553           and must resolve the differences themselves.
10554         </p>
10555
10556         <p>
10557           The comparisons are done by calculating the MD5 message
10558           digests of the files, and storing the MD5 of the file as it
10559           was included in the most recent version of the package.
10560         </p>
10561
10562         <p>
10563           When a package is installed for the first time
10564           <prgn>dpkg</prgn> will install the file that comes with it,
10565           unless that would mean overwriting a file already on the
10566           file system.
10567         </p>
10568
10569         <p>
10570           However, note that <prgn>dpkg</prgn> will <em>not</em>
10571           replace a conffile that was removed by the user (or by a
10572           script).  This is necessary because with some programs a
10573           missing file produces an effect hard or impossible to
10574           achieve in another way, so that a missing file needs to be
10575           kept that way if the user did it.
10576         </p>
10577
10578         <p>
10579           Note that a package should <em>not</em> modify a
10580           <prgn>dpkg</prgn>-handled conffile in its maintainer
10581           scripts.  Doing this will lead to <prgn>dpkg</prgn> giving
10582           the user confusing and possibly dangerous options for
10583           conffile update when the package is upgraded.</p>
10584       </sect>
10585
10586       <sect><heading>Fully-featured maintainer script configuration
10587       handling
10588         </heading>
10589
10590         <p>
10591           For files which contain site-specific information such as
10592           the hostname and networking details and so forth, it is
10593           better to create the file in the package's
10594           <prgn>postinst</prgn> script.
10595         </p>
10596
10597         <p>
10598           This will typically involve examining the state of the rest
10599           of the system to determine values and other information, and
10600           may involve prompting the user for some information which
10601           can't be obtained some other way.
10602         </p>
10603
10604         <p>
10605           When using this method there are a couple of important
10606           issues which should be considered:
10607         </p>
10608
10609         <p>
10610           If you discover a bug in the program which generates the
10611           configuration file, or if the format of the file changes
10612           from one version to the next, you will have to arrange for
10613           the postinst script to do something sensible - usually this
10614           will mean editing the installed configuration file to remove
10615           the problem or change the syntax.  You will have to do this
10616           very carefully, since the user may have changed the file,
10617           perhaps to fix the very problem that your script is trying
10618           to deal with - you will have to detect these situations and
10619           deal with them correctly.
10620         </p>
10621
10622         <p>
10623           If you do go down this route it's probably a good idea to
10624           make the program that generates the configuration file(s) a
10625           separate program in <file>/usr/sbin</file>, by convention called
10626           <file><var>package</var>config</file> and then run that if
10627           appropriate from the post-installation script.  The
10628           <tt><var>package</var>config</tt> program should not
10629           unquestioningly overwrite an existing configuration - if its
10630           mode of operation is geared towards setting up a package for
10631           the first time (rather than any arbitrary reconfiguration
10632           later) you should have it check whether the configuration
10633           already exists, and require a <tt>--force</tt> flag to
10634           overwrite it.</p></sect>
10635     </appendix>
10636
10637     <appendix id="pkg-alternatives"><heading>Alternative versions of
10638         an interface - <prgn>update-alternatives</prgn> (from old
10639     Packaging Manual)
10640       </heading>
10641
10642       <p>
10643         When several packages all provide different versions of the
10644         same program or file it is useful to have the system select a
10645         default, but to allow the system administrator to change it
10646         and have their decisions respected.
10647       </p>
10648
10649       <p>
10650         For example, there are several versions of the <prgn>vi</prgn>
10651         editor, and there is no reason to prevent all of them from
10652         being installed at once, each under their own name
10653         (<prgn>nvi</prgn>, <prgn>vim</prgn> or whatever).
10654         Nevertheless it is desirable to have the name <tt>vi</tt>
10655         refer to something, at least by default.
10656       </p>
10657
10658       <p>
10659         If all the packages involved cooperate, this can be done with
10660         <prgn>update-alternatives</prgn>.
10661       </p>
10662
10663       <p>
10664         Each package provides its own version under its own name, and
10665         calls <prgn>update-alternatives</prgn> in its postinst to
10666         register its version (and again in its prerm to deregister
10667         it).
10668       </p>
10669
10670       <p>
10671         See the man page <manref name="update-alternatives"
10672         section="8"> for details.
10673       </p>
10674
10675       <p>
10676         If <prgn>update-alternatives</prgn> does not seem appropriate
10677         you may wish to consider using diversions instead.</p>
10678     </appendix>
10679
10680     <appendix id="pkg-diversions"><heading>Diversions - overriding a
10681     package's version of a file (from old Packaging Manual)
10682       </heading>
10683
10684       <p>
10685         It is possible to have <prgn>dpkg</prgn> not overwrite a file
10686         when it reinstalls the package it belongs to, and to have it
10687         put the file from the package somewhere else instead.
10688       </p>
10689
10690       <p>
10691         This can be used locally to override a package's version of a
10692         file, or by one package to override another's version (or
10693         provide a wrapper for it).
10694       </p>
10695
10696       <p>
10697         Before deciding to use a diversion, read <ref
10698         id="pkg-alternatives"> to see if you really want a diversion
10699         rather than several alternative versions of a program.
10700       </p>
10701
10702       <p>
10703         There is a diversion list, which is read by <prgn>dpkg</prgn>,
10704         and updated by a special program <prgn>dpkg-divert</prgn>.
10705         Please see <manref name="dpkg-divert" section="8"> for full
10706         details of its operation.
10707       </p>
10708
10709       <p>
10710         When a package wishes to divert a file from another, it should
10711         call <prgn>dpkg-divert</prgn> in its preinst to add the
10712         diversion and rename the existing file.  For example,
10713         supposing that a <prgn>smailwrapper</prgn> package wishes to
10714         install a wrapper around <file>/usr/sbin/smail</file>:
10715         <example>
10716    dpkg-divert --package smailwrapper --add --rename \
10717       --divert /usr/sbin/smail.real /usr/sbin/smail
10718         </example> The <tt>--package smailwrapper</tt> ensures that
10719         <prgn>smailwrapper</prgn>'s copy of <file>/usr/sbin/smail</file>
10720         can bypass the diversion and get installed as the true version.
10721         It's safe to add the diversion unconditionally on upgrades since
10722         it will be left unchanged if it already exists, but
10723         <prgn>dpkg-divert</prgn> will display a message.  To suppress that
10724         message, make the command conditional on the version from which
10725         the package is being upgraded:
10726         <example>
10727    if [ upgrade != "$1" ] || dpkg --compare-versions "$2" lt 1.0-2; then
10728       dpkg-divert --package smailwrapper --add --rename \
10729          --divert /usr/sbin/smail.real /usr/sbin/smail
10730    fi
10731         </example> where <tt>1.0-2</tt> is the version at which the
10732         diversion was first added to the package.  Running the command
10733         during abort-upgrade is pointless but harmless.
10734       </p>
10735
10736       <p>
10737         The postrm has to do the reverse:
10738         <example>
10739   if [ remove = "$1" -o abort-install = "$1" -o disappear = "$1" ]; then
10740      dpkg-divert --package smailwrapper --remove --rename \
10741         --divert /usr/sbin/smail.real /usr/sbin/smail
10742   fi
10743         </example> If the diversion was added at a particular version, the
10744         postrm should also handle the failure case of upgrading from an
10745         older version (unless the older version is so old that direct
10746         upgrades are no longer supported):
10747         <example>
10748   if [ abort-upgrade = "$1" ] && dpkg --compare-versions "$2" lt 1.0-2; then
10749      dpkg-divert --package smailwrapper --remove --rename \
10750         --divert /usr/sbin/smail.real /usr/sbin/smail
10751   fi
10752         </example> where <tt>1.02-2</tt> is the version at which the
10753         diversion was first added to the package.  The postrm should not
10754         remove the diversion on upgrades both because there's no reason to
10755         remove the diversion only to immediately re-add it and since the
10756         postrm of the old package is run after unpacking so the removal of
10757         the diversion will fail.
10758       </p>
10759
10760       <p>
10761         Do not attempt to divert a file which is vitally important for
10762         the system's operation - when using <prgn>dpkg-divert</prgn>
10763         there is a time, after it has been diverted but before
10764         <prgn>dpkg</prgn> has installed the new version, when the file
10765         does not exist.</p>
10766     </appendix>
10767
10768   </book>
10769 </debiandoc>
10770 <!-- Local variables: -->
10771 <!-- indent-tabs-mode: t -->
10772 <!-- End: -->
10773 <!-- vim:set ai et sts=2 sw=2 tw=76: -->