]> git.donarmstrong.com Git - debian/debian-policy.git/blob - policy.sgml
Except init.d scripts from the normal set -e requirement
[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 installed
1050           <em>and</em> configured before it can be installed. 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 installed, 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 installed 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 installed 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           For this reason packages in an installation run are usually
4319           all unpacked first and all configured later; this gives
4320           later versions of packages with dependencies on later
4321           versions of other packages the opportunity to have their
4322           dependencies satisfied.
4323         </p>
4324
4325         <p>
4326           In case of circular dependencies, since installation or
4327           removal order honoring the dependency order can't be
4328           established, dependency loops are broken at some point
4329           (based on rules below), and some packages may not be able to
4330           rely on their dependencies being present when being
4331           installed or removed, depending on which side of the break
4332           of the circular dependency loop they happen to be on.  If one
4333           of the packages in the loop has no postinst script, then the
4334           cycle will be broken at that package, so as to ensure that
4335           all postinst scripts run with the dependencies properly
4336           configured if this is possible. Otherwise the breaking point
4337           is arbitrary.
4338         </p>
4339
4340         <p>
4341           The <tt>Depends</tt> field thus allows package maintainers
4342           to impose an order in which packages should be configured.
4343         </p>
4344
4345         <p>
4346           The meaning of the five dependency fields is as follows:
4347           <taglist>
4348             <tag><tt>Depends</tt></tag>
4349             <item>
4350               <p>
4351                 This declares an absolute dependency.  A package will
4352                 not be configured unless all of the packages listed in
4353                 its <tt>Depends</tt> field have been correctly
4354                 configured.
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.  Note, however, that the
4369                 <prgn>postrm</prgn> cannot rely on any non-essential
4370                 packages to be present during the <tt>purge</tt>
4371                 phase.
4372             </item>
4373
4374             <tag><tt>Recommends</tt></tag>
4375             <item>
4376               <p>
4377                 This declares a strong, but not absolute, dependency.
4378               </p>
4379
4380               <p>
4381                 The <tt>Recommends</tt> field should list packages
4382                 that would be found together with this one in all but
4383                 unusual installations.
4384               </p>
4385             </item>
4386
4387             <tag><tt>Suggests</tt></tag>
4388             <item>
4389                 This is used to declare that one package may be more
4390                 useful with one or more others.  Using this field
4391                 tells the packaging system and the user that the
4392                 listed packages are related to this one and can
4393                 perhaps enhance its usefulness, but that installing
4394                 this one without them is perfectly reasonable.
4395             </item>
4396
4397             <tag><tt>Enhances</tt></tag>
4398             <item>
4399                 This field is similar to Suggests but works in the
4400                 opposite direction. It is used to declare that a
4401                 package can enhance the functionality of another
4402                 package.
4403             </item>
4404
4405             <tag><tt>Pre-Depends</tt></tag>
4406             <item>
4407               <p>
4408                 This field is like <tt>Depends</tt>, except that it
4409                 also forces <prgn>dpkg</prgn> to complete installation
4410                 of the packages named before even starting the
4411                 installation of the package which declares the
4412                 pre-dependency, as follows:
4413               </p>
4414
4415               <p>
4416                 When a package declaring a pre-dependency is about to
4417                 be <em>unpacked</em> the pre-dependency can be
4418                 satisfied if the depended-on package is either fully
4419                 configured, <em>or even if</em> the depended-on
4420                 package(s) are only unpacked or in the "Half-Configured"
4421                 state, provided that they have been configured
4422                 correctly at some point in the past (and not removed
4423                 or partially removed since).  In this case, both the
4424                 previously-configured and currently unpacked or
4425                 "Half-Configured" versions must satisfy any version
4426                 clause in the <tt>Pre-Depends</tt> field.
4427               </p>
4428
4429               <p>
4430                 When the package declaring a pre-dependency is about
4431                 to be <em>configured</em>, the pre-dependency will be
4432                 treated as a normal <tt>Depends</tt>, that is, it will
4433                 be considered satisfied only if the depended-on
4434                 package has been correctly configured.
4435               </p>
4436
4437               <p>
4438                 <tt>Pre-Depends</tt> should be used sparingly,
4439                 preferably only by packages whose premature upgrade or
4440                 installation would hamper the ability of the system to
4441                 continue with any upgrade that might be in progress.
4442               </p>
4443
4444               <p>
4445                 <tt>Pre-Depends</tt> are also required if the
4446                 <prgn>preinst</prgn> script depends on the named
4447                 package.  It is best to avoid this situation if
4448                 possible.
4449               </p>
4450             </item>
4451           </taglist>
4452         </p>
4453
4454         <p>
4455           When selecting which level of dependency to use you should
4456           consider how important the depended-on package is to the
4457           functionality of the one declaring the dependency.  Some
4458           packages are composed of components of varying degrees of
4459           importance.  Such a package should list using
4460           <tt>Depends</tt> the package(s) which are required by the
4461           more important components.  The other components'
4462           requirements may be mentioned as Suggestions or
4463           Recommendations, as appropriate to the components' relative
4464           importance.
4465         </p>
4466       </sect>
4467
4468       <sect id="breaks">
4469         <heading>Packages which break other packages - <tt>Breaks</tt></heading>
4470
4471         <p>
4472           When one binary package declares that it breaks another,
4473           <prgn>dpkg</prgn> will refuse to allow the package which
4474           declares <tt>Breaks</tt> be installed unless the broken
4475           package is deconfigured first, and it will refuse to
4476           allow the broken package to be reconfigured.
4477         </p>
4478
4479         <p>
4480           A package will not be regarded as causing breakage merely
4481           because its configuration files are still installed; it must
4482           be at least "Half-Installed".
4483         </p>
4484
4485         <p>
4486           A special exception is made for packages which declare that
4487           they break their own package name or a virtual package which
4488           they provide (see below): this does not count as a real
4489           breakage.
4490         </p>
4491
4492         <p>
4493           Normally a <tt>Breaks</tt> entry will have an "earlier than"
4494           version clause; such a <tt>Breaks</tt> is introduced in the
4495           version of an (implicit or explicit) dependency which
4496           violates an assumption or reveals a bug in earlier versions
4497           of the broken package.  This use of <tt>Breaks</tt> will
4498           inform higher-level package management tools that broken
4499           package must be upgraded before the new one.
4500         </p>
4501
4502         <p>
4503           If the breaking package also overwrites some files from the
4504           older package, it should use <tt>Replaces</tt> (not
4505           <tt>Conflicts</tt>) to ensure this goes smoothly.
4506         </p>
4507       </sect>
4508
4509       <sect id="conflicts">
4510         <heading>Conflicting binary packages - <tt>Conflicts</tt></heading>
4511
4512         <p>
4513           When one binary package declares a conflict with another
4514           using a <tt>Conflicts</tt> field, <prgn>dpkg</prgn> will
4515           refuse to allow them to be installed on the system at the
4516           same time.
4517         </p>
4518
4519         <p>
4520           If one package is to be installed, the other must be removed
4521           first - if the package being installed is marked as
4522           replacing (see <ref id="replaces">) the one on the system,
4523           or the one on the system is marked as deselected, or both
4524           packages are marked <tt>Essential</tt>, then
4525           <prgn>dpkg</prgn> will automatically remove the package
4526           which is causing the conflict, otherwise it will halt the
4527           installation of the new package with an error.  This
4528           mechanism is specifically designed to produce an error when
4529           the installed package is <tt>Essential</tt>, but the new
4530           package is not.
4531         </p>
4532
4533         <p>
4534           A package will not cause a conflict merely because its
4535           configuration files are still installed; it must be at least
4536           "Half-Installed".
4537         </p>
4538
4539         <p>
4540           A special exception is made for packages which declare a
4541           conflict with their own package name, or with a virtual
4542           package which they provide (see below): this does not
4543           prevent their installation, and allows a package to conflict
4544           with others providing a replacement for it.  You use this
4545           feature when you want the package in question to be the only
4546           package providing some feature.
4547         </p>
4548
4549         <p>
4550           A <tt>Conflicts</tt> entry should almost never have an
4551           "earlier than" version clause.  This would prevent
4552           <prgn>dpkg</prgn> from upgrading or installing the package
4553           which declared such a conflict until the upgrade or removal
4554           of the conflicted-with package had been completed.  Instead,
4555           <tt>Breaks</tt> may be used.
4556         </p>
4557       </sect>
4558
4559       <sect id="virtual"><heading>Virtual packages - <tt>Provides</tt>
4560         </heading>
4561
4562         <p>
4563           As well as the names of actual ("concrete") packages, the
4564           package relationship fields <tt>Depends</tt>,
4565           <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
4566           <tt>Pre-Depends</tt>, <tt>Breaks</tt>, <tt>Conflicts</tt>,
4567           <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
4568           <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>
4569           may mention "virtual packages".
4570         </p>
4571
4572         <p>
4573           A <em>virtual package</em> is one which appears in the
4574           <tt>Provides</tt> control file field of another package.
4575           The effect is as if the package(s) which provide a
4576           particular virtual package name had been listed by name
4577           everywhere the virtual package name appears. (See also <ref
4578             id="virtual_pkg">)
4579         </p>
4580
4581         <p>
4582           If there are both concrete and virtual packages of the same
4583           name, then the dependency may be satisfied (or the conflict
4584           caused) by either the concrete package with the name in
4585           question or any other concrete package which provides the
4586           virtual package with the name in question.  This is so that,
4587           for example, supposing we have
4588           <example compact="compact">
4589 Package: foo
4590 Depends: bar
4591           </example> and someone else releases an enhanced version of
4592           the <tt>bar</tt> package they can say:
4593           <example compact="compact">
4594 Package: bar-plus
4595 Provides: bar
4596           </example>
4597           and the <tt>bar-plus</tt> package will now also satisfy the
4598           dependency for the <tt>foo</tt> package.
4599         </p>
4600
4601         <p>
4602           If a relationship field has a version number attached
4603           then only real packages will be considered to see whether
4604           the relationship is satisfied (or the prohibition violated,
4605           for a conflict or breakage) - it is assumed that a real
4606           package which provides the virtual package is not of the
4607           "right" version.  So, a <tt>Provides</tt> field may not
4608           contain version numbers, and the version number of the
4609           concrete package which provides a particular virtual package
4610           will not be looked at when considering a dependency on or
4611           conflict with the virtual package name.
4612         </p>
4613
4614         <p>
4615           It is likely that the ability will be added in a future
4616           release of <prgn>dpkg</prgn> to specify a version number for
4617           each virtual package it provides.  This feature is not yet
4618           present, however, and is expected to be used only
4619           infrequently.
4620         </p>
4621
4622         <p>
4623           If you want to specify which of a set of real packages
4624           should be the default to satisfy a particular dependency on
4625           a virtual package, you should list the real package as an
4626           alternative before the virtual one.
4627         </p>
4628       </sect>
4629
4630
4631       <sect id="replaces"><heading>Overwriting files and replacing
4632           packages - <tt>Replaces</tt></heading>
4633
4634         <p>
4635           Packages can declare in their control file that they should
4636           overwrite files in certain other packages, or completely
4637           replace other packages. The <tt>Replaces</tt> control file
4638           field has these two distinct purposes.
4639         </p>
4640
4641         <sect1><heading>Overwriting files in other packages</heading>
4642
4643           <p>
4644             Firstly, as mentioned before, it is usually an error for a
4645             package to contain files which are on the system in
4646             another package.
4647           </p>
4648
4649           <p>
4650             However, if the overwriting package declares that it
4651             <tt>Replaces</tt> the one containing the file being
4652             overwritten, then <prgn>dpkg</prgn> will replace the file
4653             from the old package with that from the new.  The file
4654             will no longer be listed as "owned" by the old package.
4655           </p>
4656
4657           <p>
4658             If a package is completely replaced in this way, so that
4659             <prgn>dpkg</prgn> does not know of any files it still
4660             contains, it is considered to have "disappeared".  It will
4661             be marked as not wanted on the system (selected for
4662             removal) and not installed.  Any <tt>conffile</tt>s
4663             details noted for the package will be ignored, as they
4664             will have been taken over by the overwriting package.  The
4665             package's <prgn>postrm</prgn> script will be run with a
4666             special argument to allow the package to do any final
4667             cleanup required.  See <ref id="mscriptsinstact">.
4668             <footnote>
4669               <p>
4670                 Replaces is a one way relationship -- you have to              
4671                 install the replacing package after the replaced
4672                 package.
4673               </p>
4674             </footnote>
4675           </p>
4676
4677           <p>
4678             For this usage of <tt>Replaces</tt>, virtual packages (see
4679             <ref id="virtual">) are not considered when looking at a
4680             <tt>Replaces</tt> field - the packages declared as being
4681             replaced must be mentioned by their real names.
4682           </p>
4683
4684           <p>
4685             Furthermore, this usage of <tt>Replaces</tt> only takes
4686             effect when both packages are at least partially on the
4687             system at once, so that it can only happen if they do not
4688             conflict or if the conflict has been overridden.
4689           </p>
4690
4691         </sect1>
4692
4693         <sect1><heading>Replacing whole packages, forcing their
4694             removal</heading>
4695
4696           <p>
4697             Secondly, <tt>Replaces</tt> allows the packaging system to
4698             resolve which package should be removed when there is a
4699             conflict - see <ref id="conflicts">.  This usage only
4700             takes effect when the two packages <em>do</em> conflict,
4701             so that the two usages of this field do not interfere with
4702             each other.
4703           </p>
4704
4705           <p>
4706             In this situation, the package declared as being replaced
4707             can be a virtual package, so for example, all mail
4708             transport agents (MTAs) would have the following fields in
4709             their control files:
4710             <example compact="compact">
4711 Provides: mail-transport-agent
4712 Conflicts: mail-transport-agent
4713 Replaces: mail-transport-agent
4714             </example>
4715             ensuring that only one MTA can be installed at any one
4716             time.
4717         </sect1>
4718       </sect>
4719
4720       <sect id="sourcebinarydeps">
4721         <heading>Relationships between source and binary packages -
4722           <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
4723           <tt>Build-Conflicts</tt>, <tt>Build-Conflicts-Indep</tt>
4724         </heading>
4725
4726         <p>
4727           Source packages that require certain binary packages to be
4728           installed or absent at the time of building the package
4729           can declare relationships to those binary packages.
4730         </p>
4731
4732         <p>
4733           This is done using the <tt>Build-Depends</tt>,
4734           <tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt> and
4735           <tt>Build-Conflicts-Indep</tt> control file fields.
4736         </p>
4737
4738         <p>
4739           Build-dependencies on "build-essential" binary packages can be
4740           omitted. Please see <ref id="pkg-relations"> for more information.
4741         </p>
4742
4743         <p>
4744           The dependencies and conflicts they define must be satisfied
4745           (as defined earlier for binary packages) in order to invoke
4746           the targets in <tt>debian/rules</tt>, as follows:<footnote>
4747             <p>
4748               If you make "build-arch" or "binary-arch", you need
4749               Build-Depends.  If you make "build-indep" or
4750               "binary-indep", you need Build-Depends and
4751               Build-Depends-Indep.  If you make "build" or "binary",
4752               you need both.
4753             </p>
4754             <p>
4755               There is no Build-Depends-Arch; this role is essentially
4756               met with Build-Depends.  Anyone building the
4757               <tt>build-indep</tt> and binary-indep<tt></tt> targets
4758               is basically assumed to be building the whole package
4759               anyway and so installs all build dependencies.  The
4760               autobuilders use <tt>dpkg-buildpackage -B</tt>, which
4761               calls <tt>build</tt> (not <tt>build-arch</tt>, since it
4762               does not yet know how to check for its existence) and
4763               <tt>binary-arch</tt>.
4764             </p>
4765             <p>
4766               The purpose of the original split, I recall, was so that
4767               the autobuilders wouldn't need to install extra packages
4768               needed only for the binary-indep targets.  But without a
4769               build-arch/build-indep split, this didn't work, since
4770               most of the work is done in the build target, not in the
4771               binary target.
4772             </p>
4773           </footnote>
4774
4775           <taglist>
4776             <tag><tt>Build-Depends</tt>, <tt>Build-Conflicts</tt></tag>
4777             <item>
4778                 The <tt>Build-Depends</tt> and
4779                 <tt>Build-Conflicts</tt> fields must be satisfied when
4780                 any of the following targets is invoked:
4781                 <tt>build</tt>, <tt>clean</tt>, <tt>binary</tt>,
4782                 <tt>binary-arch</tt>, <tt>build-arch</tt>,
4783                 <tt>build-indep</tt> and <tt>binary-indep</tt>.
4784             </item>
4785             <tag><tt>Build-Depends-Indep</tt>,
4786               <tt>Build-Conflicts-Indep</tt></tag>
4787             <item>
4788                 The <tt>Build-Depends-Indep</tt> and
4789                 <tt>Build-Conflicts-Indep</tt> fields must be
4790                 satisfied when any of the following targets is
4791                 invoked: <tt>build</tt>, <tt>build-indep</tt>,
4792                 <tt>binary</tt> and <tt>binary-indep</tt>.
4793             </item>
4794           </taglist>
4795         </p>
4796
4797       </sect>
4798
4799     </chapt>
4800
4801
4802     <chapt id="sharedlibs"><heading>Shared libraries</heading>
4803
4804       <p>
4805         Packages containing shared libraries must be constructed with
4806         a little care to make sure that the shared library is always
4807         available.  This is especially important for packages whose
4808         shared libraries are vitally important, such as the C library
4809         (currently <tt>libc6</tt>).
4810       </p>
4811
4812       <p>
4813         Packages involving shared libraries should be split up into
4814         several binary packages. This section mostly deals with how
4815         this separation is to be accomplished; rules for files within
4816         the shared library packages are in <ref id="libraries"> instead.
4817       </p>
4818
4819       <sect id="sharedlibs-runtime">
4820         <heading>Run-time shared libraries</heading>
4821
4822       <p>
4823         The run-time shared library needs to be placed in a package
4824         whose name changes whenever the shared object version
4825         changes.<footnote>
4826             <p>
4827               Since it is common place to install several versions of a
4828               package that just provides shared libraries, it is a
4829               good idea that the library package should not
4830               contain any extraneous non-versioned files, unless they
4831               happen to be in versioned directories.</p>
4832           </footnote>
4833           The most common mechanism is to place it in a package
4834         called
4835         <package><var>libraryname</var><var>soversion</var></package>,
4836         where <file><var>soversion</var></file> is the version number
4837         in the soname of the shared library<footnote>
4838               The soname is the shared object name: it's the thing
4839               that has to match exactly between building an executable
4840               and running it for the dynamic linker to be able run the
4841               program.  For example, if the soname of the library is
4842               <file>libfoo.so.6</file>, the library package would be
4843               called <file>libfoo6</file>.
4844           </footnote>.
4845         Alternatively, if it would be confusing to directly append
4846         <var>soversion</var> to <var>libraryname</var> (e.g. because
4847         <var>libraryname</var> itself ends in a number), you may use
4848         <package><var>libraryname</var>-<var>soversion</var></package> and
4849         <package><var>libraryname</var>-<var>soversion</var>-dev</package>
4850         instead.
4851       </p>
4852
4853       <p>
4854         If you have several shared libraries built from the same
4855         source tree you may lump them all together into a single
4856         shared library package, provided that you change all of
4857         their sonames at once (so that you don't get filename
4858         clashes if you try to install different versions of the
4859         combined shared libraries package).
4860       </p>
4861
4862       <p>
4863         The package should install the shared libraries under
4864         their normal names.  For example, the <package>libgdbm3</package>
4865         package should install <file>libgdbm.so.3.0.0</file> as
4866         <file>/usr/lib/libgdbm.so.3.0.0</file>.  The files should not be
4867         renamed or re-linked by any <prgn>prerm</prgn> or
4868         <prgn>postrm</prgn> scripts; <prgn>dpkg</prgn> will take care
4869         of renaming things safely without affecting running programs,
4870         and attempts to interfere with this are likely to lead to
4871         problems.
4872       </p>
4873
4874       <p>
4875         Shared libraries should not be installed executable, since
4876         the dynamic linker does not require this and trying to
4877         execute a shared library usually results in a core dump.
4878       </p>
4879
4880       <p>
4881         The run-time library package should include the symbolic link that
4882         <prgn>ldconfig</prgn> would create for the shared libraries.
4883         For example, the <package>libgdbm3</package> package should include
4884         a symbolic link from <file>/usr/lib/libgdbm.so.3</file> to
4885         <file>libgdbm.so.3.0.0</file>.  This is needed so that the dynamic
4886         linker (for example <prgn>ld.so</prgn> or
4887         <prgn>ld-linux.so.*</prgn>) can find the library between the
4888         time that <prgn>dpkg</prgn> installs it and the time that
4889         <prgn>ldconfig</prgn> is run in the <prgn>postinst</prgn>
4890         script.<footnote>
4891             The package management system requires the library to be
4892             placed before the symbolic link pointing to it in the
4893             <file>.deb</file> file.  This is so that when
4894             <prgn>dpkg</prgn> comes to install the symlink
4895             (overwriting the previous symlink pointing at an older
4896             version of the library), the new shared library is already
4897             in place.  In the past, this was achieved by creating the
4898             library in the temporary packaging directory before
4899             creating the symlink.  Unfortunately, this was not always
4900             effective, since the building of the tar file in the
4901             <file>.deb</file> depended on the behavior of the underlying
4902             file system.  Some file systems (such as reiserfs) reorder
4903             the files so that the order of creation is forgotten.
4904             Since version 1.7.0, <prgn>dpkg</prgn>
4905             reorders the files itself as necessary when building a
4906             package.  Thus it is no longer important to concern
4907             oneself with the order of file creation.
4908         </footnote>
4909       </p>
4910
4911         <sect1 id="ldconfig">
4912           <heading><tt>ldconfig</tt></heading>
4913
4914         <p>
4915           Any package installing shared libraries in one of the default
4916           library directories of the dynamic linker (which are currently
4917           <file>/usr/lib</file> and <file>/lib</file>) or a directory that is
4918           listed in <file>/etc/ld.so.conf</file><footnote>
4919             These are currently
4920             <list compact="compact">
4921               <item>/usr/local/lib</item>
4922               <item>/usr/lib/libc5-compat</item>
4923               <item>/lib/libc5-compat</item>
4924             </list>
4925           </footnote>
4926           must use <prgn>ldconfig</prgn> to update the shared library
4927           system.
4928         </p>
4929
4930         <p>
4931             The package maintainer scripts must only call
4932             <prgn>ldconfig</prgn> under these circumstances:
4933             <list compact="compact">
4934               <item>When the <prgn>postinst</prgn> script is run with a
4935                   first argument of <tt>configure</tt>, the script must call
4936                   <prgn>ldconfig</prgn>, and may optionally invoke
4937                   <prgn>ldconfig</prgn> at other times.
4938               </item>
4939               <item>When the <prgn>postrm</prgn> script is run with a
4940                   first argument of <tt>remove</tt>, the script should call
4941                   <prgn>ldconfig</prgn>.
4942               </item>
4943             </list>
4944          <footnote>
4945             <p>
4946               During install or upgrade, the preinst is called before
4947               the new files are installed, so calling "ldconfig" is
4948               pointless.  The preinst of an existing package can also be
4949               called if an upgrade fails.  However, this happens during
4950               the critical time when a shared libs may exist on-disk
4951               under a temporary name.  Thus, it is dangerous and
4952               forbidden by current policy to call "ldconfig" at this
4953               time.
4954             </p>
4955
4956             <p>
4957               When a package is installed or upgraded, "postinst
4958               configure" runs after the new files are safely on-disk.
4959               Since it is perfectly safe to invoke ldconfig
4960               unconditionally in a postinst, it is OK for a package to
4961               simply put ldconfig in its postinst without checking the
4962               argument.  The postinst can also be called to recover from
4963               a failed upgrade.  This happens before any new files are
4964               unpacked, so there is no reason to call "ldconfig" at this
4965               point.
4966             </p>
4967
4968             <p>
4969               For a package that is being removed, prerm is
4970               called with all the files intact, so calling ldconfig is
4971               useless.  The other calls to "prerm" happen in the case of
4972               upgrade at a time when all the files of the old package
4973               are on-disk, so again calling "ldconfig" is pointless.
4974             </p>
4975
4976             <p>
4977               postrm, on the other hand, is called with the "remove"
4978               argument just after the files are removed, so this is
4979               the proper time to call "ldconfig" to notify the system
4980               of the fact that the shared libraries from the package
4981               are removed.  The postrm can be called at several other
4982               times.  At the time of "postrm purge", "postrm
4983               abort-install", or "postrm abort-upgrade", calling
4984               "ldconfig" is useless because the shared lib files are
4985               not on-disk.  However, when "postrm" is invoked with
4986               arguments "upgrade", "failed-upgrade", or "disappear", a
4987               shared lib may exist on-disk under a temporary filename.
4988             </p>
4989           </footnote>
4990         </p>
4991         </sect1>
4992
4993       </sect>
4994
4995       <sect id="sharedlibs-support-files">
4996         <heading>Shared library support files</heading>
4997
4998         <p>
4999           If your package contains files whose names do not change with
5000           each change in the library shared object version, you must not
5001           put them in the shared library package.  Otherwise, several
5002           versions of the shared library cannot be installed at the same
5003           time without filename clashes, making upgrades and transitions
5004           unnecessarily difficult.
5005         </p>
5006
5007         <p>
5008           It is recommended that supporting files and run-time support
5009           programs that do not need to be invoked manually by users, but
5010           are nevertheless required for the package to function, be placed
5011           (if they are binary) in a subdirectory of <file>/usr/lib</file>,
5012           preferably under <file>/usr/lib/</file><var>package-name</var>.
5013           If the program or file is architecture independent, the
5014           recommendation is for it to be placed in a subdirectory of
5015           <file>/usr/share</file> instead, preferably under
5016           <file>/usr/share/</file><var>package-name</var>.  Following the
5017           <var>package-name</var> naming convention ensures that the file
5018           names change when the shared object version changes.
5019         </p>
5020
5021         <p>
5022           Run-time support programs that use the shared library but are
5023           not required for the library to function or files used by the
5024           shared library that can be used by any version of the shared
5025           library package should instead be put in a separate package.
5026           This package might typically be named
5027           <package><var>libraryname</var>-tools</package>; note the
5028           absence of the <var>soversion</var> in the package name.
5029         </p>
5030
5031         <p>
5032           Files and support programs only useful when compiling software
5033           against the library should be included in the development
5034           package for the library.<footnote>
5035             For example, a <file><var>package-name</var>-config</file>
5036             script or <package>pkg-config</package> configuration files.
5037           </footnote>
5038         </p>
5039       </sect>
5040
5041       <sect id="sharedlibs-static">
5042         <heading>Static libraries</heading>
5043
5044       <p>
5045         The static library (<file><var>libraryname.a</var></file>)
5046         is usually provided in addition to the shared version.
5047         It is placed into the development package (see below).
5048       </p>
5049
5050       <p>
5051         In some cases, it is acceptable for a library to be
5052         available in static form only; these cases include:
5053         <list>
5054           <item>libraries for languages whose shared library support
5055                 is immature or unstable</item>
5056           <item>libraries whose interfaces are in flux or under
5057                 development (commonly the case when the library's
5058                 major version number is zero, or where the ABI breaks
5059                 across patchlevels)</item>
5060           <item>libraries which are explicitly intended to be
5061                 available only in static form by their upstream
5062                 author(s)</item>
5063         </list>
5064       </p>
5065
5066       <sect id="sharedlibs-dev">
5067         <heading>Development files</heading>
5068
5069       <p>
5070         The development files associated to a shared library need to be
5071         placed in a package called
5072         <package><var>libraryname</var><var>soversion</var>-dev</package>,
5073         or if you prefer only to support one development version at a
5074         time, <package><var>libraryname</var>-dev</package>.
5075       </p>
5076
5077       <p>
5078         In case several development versions of a library exist, you may
5079         need to use <prgn>dpkg</prgn>'s Conflicts mechanism (see
5080         <ref id="conflicts">) to ensure that the user only installs one
5081         development version at a time (as different development versions are
5082         likely to have the same header files in them, which would cause a
5083         filename clash if both were installed).
5084       </p>
5085
5086       <p>
5087         The development package should contain a symlink for the associated
5088         shared library without a version number. For example, the
5089         <package>libgdbm-dev</package> package should include a symlink
5090         from <file>/usr/lib/libgdbm.so</file> to
5091         <file>libgdbm.so.3.0.0</file>.  This symlink is needed by the linker
5092         (<prgn>ld</prgn>) when compiling packages, as it will only look for
5093         <file>libgdbm.so</file> when compiling dynamically.
5094       </p>
5095       </sect>
5096
5097       <sect id="sharedlibs-intradeps">
5098         <heading>Dependencies between the packages of the same library</heading>
5099
5100         <p>
5101           Typically the development version should have an exact
5102           version dependency on the runtime library, to make sure that
5103           compilation and linking happens correctly.  The
5104           <tt>${binary:Version}</tt> substitution variable can be
5105           useful for this purpose.
5106           <footnote>
5107             Previously, <tt>${Source-Version}</tt> was used, but its name
5108             was confusing and it has been deprecated since dpkg 1.13.19.
5109           </footnote>
5110         </p>
5111       </sect>
5112
5113       <sect id="sharedlibs-shlibdeps">
5114         <heading>Dependencies between the library and other packages -
5115         the <tt>shlibs</tt> system</heading>
5116
5117         <p>
5118           If a package contains a binary or library which links to a
5119           shared library, we must ensure that when the package is
5120           installed on the system, all of the libraries needed are
5121           also installed.  This requirement led to the creation of the
5122           <tt>shlibs</tt> system, which is very simple in its design:
5123           any package which <em>provides</em> a shared library also
5124           provides information on the package dependencies required to
5125           ensure the presence of this library, and any package which
5126           <em>uses</em> a shared library uses this information to
5127           determine the dependencies it requires.  The files which
5128           contain the mapping from shared libraries to the necessary
5129           dependency information are called <file>shlibs</file> files.
5130         </p>
5131
5132         <p>
5133           Thus, when a package is built which contains any shared
5134           libraries, it must provide a <file>shlibs</file> file for other
5135           packages to use, and when a package is built which contains
5136           any shared libraries or compiled binaries, it must run
5137           <qref id="pkg-dpkg-shlibdeps"><prgn>dpkg-shlibdeps</prgn></qref>
5138           on these to determine the libraries used and hence the
5139           dependencies needed by this package.<footnote>
5140             <p>
5141               In the past, the shared libraries linked to were
5142               determined by calling <prgn>ldd</prgn>, but now
5143               <prgn>objdump</prgn> is used to do this.  The only
5144               change this makes to package building is that
5145               <prgn>dpkg-shlibdeps</prgn> must also be run on shared
5146               libraries, whereas in the past this was unnecessary.
5147               The rest of this footnote explains the advantage that
5148               this method gives.
5149             </p>
5150
5151             <p>
5152               We say that a binary <tt>foo</tt> <em>directly</em> uses
5153               a library <tt>libbar</tt> if it is explicitly linked
5154               with that library (that is, it uses the flag
5155               <tt>-lbar</tt> during the linking stage).  Other
5156               libraries that are needed by <tt>libbar</tt> are linked
5157               <em>indirectly</em> to <tt>foo</tt>, and the dynamic
5158               linker will load them automatically when it loads
5159               <tt>libbar</tt>.  A package should depend on
5160               the libraries it directly uses, and the dependencies for
5161               those libraries should automatically pull in the other
5162               libraries.
5163             </p>
5164
5165             <p>
5166               Unfortunately, the <prgn>ldd</prgn> program shows both
5167               the directly and indirectly used libraries, meaning that
5168               the dependencies determined included both direct and
5169               indirect dependencies.  The use of <prgn>objdump</prgn>
5170               avoids this problem by determining only the directly
5171               used libraries.
5172             </p>
5173
5174             <p>
5175               A good example of where this helps is the following.  We
5176               could update <tt>libimlib</tt> with a new version that
5177               supports a new graphics format called dgf (but retaining
5178               the same major version number).  If we used the old
5179               <prgn>ldd</prgn> method, every package that uses
5180               <tt>libimlib</tt> would need to be recompiled so it
5181               would also depend on <tt>libdgf</tt> or it wouldn't run
5182               due to missing symbols.  However with the new system,
5183               packages using <tt>libimlib</tt> can rely on
5184               <tt>libimlib</tt> itself having the dependency on
5185               <tt>libdgf</tt> and so they would not need rebuilding.
5186             </p>
5187           </footnote>
5188         </p>
5189
5190         <p>
5191           In the following sections, we will first describe where the
5192           various <tt>shlibs</tt> files are to be found, then how to
5193           use <prgn>dpkg-shlibdeps</prgn>, and finally the <tt>shlibs</tt>
5194           file format and how to create them if your package contains a
5195           shared library.
5196         </p>
5197
5198       <sect1>
5199         <heading>The <tt>shlibs</tt> files present on the system</heading>
5200
5201         <p>
5202           There are several places where <tt>shlibs</tt> files are
5203           found.  The following list gives them in the order in which
5204           they are read by
5205           <qref id="pkg-dpkg-shlibdeps"><prgn>dpkg-shlibdeps</prgn></qref>.
5206           (The first one which gives the required information is used.)
5207         </p>
5208
5209         <p>
5210           <list>
5211             <item>
5212               <p><file>debian/shlibs.local</file></p>
5213
5214               <p>
5215                 This lists overrides for this package.  Its use is
5216                 described below (see <ref id="shlibslocal">).
5217               </p>
5218             </item>
5219
5220             <item>
5221               <p><file>/etc/dpkg/shlibs.override</file></p>
5222
5223               <p>
5224                 This lists global overrides.  This list is normally
5225                 empty.  It is maintained by the local system
5226                 administrator.
5227               </p>
5228             </item>
5229
5230             <item>
5231               <p><file>DEBIAN/shlibs</file> files in the "build directory"</p>
5232
5233               <p>
5234                 When packages are being built, any
5235                 <file>debian/shlibs</file> files are copied into the
5236                 control file area of the temporary build directory and
5237                 given the name <file>shlibs</file>.  These files give
5238                 details of any shared libraries included in the
5239                 package.<footnote>
5240                     An example may help here.  Let us say that the
5241                     source package <tt>foo</tt> generates two binary
5242                     packages, <tt>libfoo2</tt> and
5243                     <tt>foo-runtime</tt>.  When building the binary
5244                     packages, the two packages are created in the
5245                     directories <file>debian/libfoo2</file> and
5246                     <file>debian/foo-runtime</file> respectively.
5247                     (<file>debian/tmp</file> could be used instead of one
5248                     of these.)  Since <tt>libfoo2</tt> provides the
5249                     <tt>libfoo</tt> shared library, it will require a
5250                     <tt>shlibs</tt> file, which will be installed in
5251                     <file>debian/libfoo2/DEBIAN/shlibs</file>, eventually
5252                     to become
5253                     <file>/var/lib/dpkg/info/libfoo2.shlibs</file>.  Then
5254                     when <prgn>dpkg-shlibdeps</prgn> is run on the
5255                     executable
5256                     <file>debian/foo-runtime/usr/bin/foo-prog</file>, it
5257                     will examine the
5258                     <file>debian/libfoo2/DEBIAN/shlibs</file> file to
5259                     determine whether <tt>foo-prog</tt>'s library
5260                     dependencies are satisfied by any of the libraries
5261                     provided by <tt>libfoo2</tt>.  For this reason,
5262                     <prgn>dpkg-shlibdeps</prgn> must only be run once
5263                     all of the individual binary packages'
5264                     <tt>shlibs</tt> files have been installed into the
5265                     build directory.
5266                 </footnote>
5267               </p>
5268             </item>
5269
5270             <item>
5271               <p><file>/var/lib/dpkg/info/*.shlibs</file></p>
5272
5273               <p>
5274                 These are the <file>shlibs</file> files corresponding to
5275                 all of the packages installed on the system, and are
5276                 maintained by the relevant package maintainers.
5277               </p>
5278             </item>
5279
5280             <item>
5281               <p><file>/etc/dpkg/shlibs.default</file></p>
5282
5283               <p>
5284                 This file lists any shared libraries whose packages
5285                 have failed to provide correct <file>shlibs</file> files.
5286                 It was used when the <file>shlibs</file> setup was first
5287                 introduced, but it is now normally empty.  It is
5288                 maintained by the <tt>dpkg</tt> maintainer.
5289               </p>
5290             </item>
5291           </list>
5292         </p>
5293       </sect1>
5294
5295       <sect1>
5296         <heading>How to use <prgn>dpkg-shlibdeps</prgn> and the
5297             <file>shlibs</file> files</heading>
5298
5299         <p>
5300           Put a call to
5301           <qref id="pkg-dpkg-shlibdeps"><prgn>dpkg-shlibdeps</prgn></qref>
5302           into your <file>debian/rules</file> file.  If your package
5303           contains only compiled binaries and libraries (but no scripts),
5304           you can use a command such as:
5305           <example compact="compact">
5306 dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \
5307   debian/tmp/usr/lib/*
5308           </example>
5309           Otherwise, you will need to explicitly list the compiled
5310           binaries and libraries.<footnote>
5311               If you are using <tt>debhelper</tt>, the
5312               <prgn>dh_shlibdeps</prgn> program will do this work for
5313               you.  It will also correctly handle multi-binary
5314               packages.
5315           </footnote>
5316         </p>
5317
5318         <p>
5319           This command puts the dependency information into the
5320           <file>debian/substvars</file> file, which is then used by
5321           <prgn>dpkg-gencontrol</prgn>.  You will need to place a
5322           <tt>${shlibs:Depends}</tt> variable in the <tt>Depends</tt>
5323           field in the control file for this to work.
5324         </p>
5325
5326         <p>
5327           If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
5328           done.  If it does complain you might need to create your own
5329           <file>debian/shlibs.local</file> file, as explained below (see
5330           <ref id="shlibslocal">).
5331         </p>
5332
5333         <p>
5334           If you have multiple binary packages, you will need to call
5335           <prgn>dpkg-shlibdeps</prgn> on each one which contains
5336           compiled libraries or binaries.  In such a case, you will
5337           need to use the <tt>-T</tt> option to the <tt>dpkg</tt>
5338           utilities to specify a different <file>substvars</file> file.
5339         </p>
5340
5341         <p>
5342           If you are creating a udeb for use in the Debian Installer,
5343           you will need to specify that <prgn>dpkg-shlibdeps</prgn>
5344           should use the dependency line of type <tt>udeb</tt> by
5345           adding the <tt>-tudeb</tt> option<footnote>
5346               <prgn>dh_shlibdeps</prgn> from the <tt>debhelper</tt> suite
5347               will automatically add this option if it knows it is
5348               processing a udeb.
5349           </footnote>. If there is no dependency line of type <tt>udeb</tt>
5350           in the <file>shlibs</file> file, <prgn>dpkg-shlibdeps</prgn> will
5351           fall back to the regular dependency line.
5352         </p>
5353
5354         <p>
5355           For more details on dpkg-shlibdeps, please see
5356           <ref id="pkg-dpkg-shlibdeps"> and
5357           <manref name="dpkg-shlibdeps" section="1">.
5358         </p>
5359       </sect1>
5360
5361       <sect1 id="shlibs">
5362         <heading>The <file>shlibs</file> File Format</heading>
5363
5364         <p>
5365           Each <file>shlibs</file> file has the same format.  Lines
5366           beginning with <tt>#</tt> are considered to be comments and
5367           are ignored.  Each line is of the form:
5368           <example compact="compact">
5369 [<var>type</var>: ]<var>library-name</var> <var>soname-version</var> <var>dependencies ...</var>
5370           </example>
5371         </p>
5372
5373         <p>
5374           We will explain this by reference to the example of the
5375           <tt>zlib1g</tt> package, which (at the time of writing)
5376           installs the shared library <file>/usr/lib/libz.so.1.1.3</file>.
5377         </p>
5378
5379         <p>
5380           <var>type</var> is an optional element that indicates the type
5381           of package for which the line is valid. The only type currently
5382           in use is <tt>udeb</tt>. The colon and space after the type are
5383           required.
5384         </p>
5385
5386         <p>
5387           <var>library-name</var> is the name of the shared library,
5388           in this case <tt>libz</tt>.  (This must match the name part
5389           of the soname, see below.)
5390         </p>
5391
5392         <p>
5393           <var>soname-version</var> is the version part of the soname of
5394           the library.  The soname is the thing that must exactly match
5395           for the library to be recognized by the dynamic linker, and is
5396           usually of the form
5397           <tt><var>name</var>.so.<var>major-version</var></tt>, in our
5398           example, <tt>libz.so.1</tt>.<footnote>
5399               This can be determined using the command
5400               <example compact="compact">
5401 objdump -p /usr/lib/libz.so.1.1.3 | grep SONAME
5402               </example>
5403           </footnote>
5404           The version part is the part which comes after
5405           <tt>.so.</tt>, so in our case, it is <tt>1</tt>.
5406         </p>
5407
5408         <p>
5409           <var>dependencies</var> has the same syntax as a dependency
5410           field in a binary package control file.  It should give
5411           details of which packages are required to satisfy a binary
5412           built against the version of the library contained in the
5413           package.  See <ref id="depsyntax"> for details.
5414         </p>
5415
5416         <p>
5417           In our example, if the first version of the <tt>zlib1g</tt>
5418           package which contained a minor number of at least
5419           <tt>1.3</tt> was <var>1:1.1.3-1</var>, then the
5420           <tt>shlibs</tt> entry for this library could say:
5421           <example compact="compact">
5422 libz 1 zlib1g (>= 1:1.1.3)
5423           </example>
5424           The version-specific dependency is to avoid warnings from
5425           the dynamic linker about using older shared libraries with
5426           newer binaries.
5427         </p>
5428
5429         <p>
5430           As zlib1g also provides a udeb containing the shared library,
5431           there would also be a second line:
5432           <example compact="compact">
5433 udeb: libz 1 zlib1g-udeb (>= 1:1.1.3)
5434           </example>
5435         </p>
5436       </sect1>
5437
5438       <sect1>
5439         <heading>Providing a <file>shlibs</file> file</heading>
5440
5441         <p>
5442           If your package provides a shared library, you need to create
5443           a <file>shlibs</file> file following the format described above.
5444           It is usual to call this file <file>debian/shlibs</file> (but if
5445           you have multiple binary packages, you might want to call it
5446           <file>debian/shlibs.<var>package</var></file> instead).  Then
5447           let <file>debian/rules</file> install it in the control area:
5448           <example compact="compact">
5449 install -m644 debian/shlibs debian/tmp/DEBIAN
5450           </example>
5451           or, in the case of a multi-binary package:
5452           <example compact="compact">
5453 install -m644 debian/shlibs.<var>package</var> debian/<var>package</var>/DEBIAN/shlibs
5454           </example>
5455           An alternative way of doing this is to create the
5456           <file>shlibs</file> file in the control area directly from
5457           <file>debian/rules</file> without using a <file>debian/shlibs</file>
5458           file at all,<footnote>
5459               This is what <prgn>dh_makeshlibs</prgn> in the
5460               <tt>debhelper</tt> suite does. If your package also has a udeb
5461               that provides a shared library, <prgn>dh_makeshlibs</prgn> can
5462               automatically generate the <tt>udeb:</tt> lines if you specify
5463               the name of the udeb with the <tt>--add-udeb</tt> option.
5464           </footnote>
5465           since the <file>debian/shlibs</file> file itself is ignored by
5466           <prgn>dpkg-shlibdeps</prgn>.
5467         </p>
5468
5469         <p>
5470           As <prgn>dpkg-shlibdeps</prgn> reads the
5471           <file>DEBIAN/shlibs</file> files in all of the binary packages
5472           being built from this source package, all of the
5473           <file>DEBIAN/shlibs</file> files should be installed before
5474           <prgn>dpkg-shlibdeps</prgn> is called on any of the binary
5475           packages.
5476         </p>
5477       </sect1>
5478
5479       <sect1 id="shlibslocal">
5480         <heading>Writing the <file>debian/shlibs.local</file> file</heading>
5481
5482         <p>
5483           This file is intended only as a <em>temporary</em> fix if
5484           your binaries or libraries depend on a library whose package
5485           does not yet provide a correct <file>shlibs</file> file.
5486         </p>
5487
5488         <p>
5489           We will assume that you are trying to package a binary
5490           <tt>foo</tt>.  When you try running
5491           <prgn>dpkg-shlibdeps</prgn> you get the following error
5492           message (<tt>-O</tt> displays the dependency information on
5493           <tt>stdout</tt> instead of writing it to
5494           <tt>debian/substvars</tt>, and the lines have been wrapped
5495           for ease of reading):
5496           <example compact="compact">
5497 $ dpkg-shlibdeps -O debian/tmp/usr/bin/foo
5498 dpkg-shlibdeps: warning: unable to find dependency
5499   information for shared library libbar (soname 1,
5500   path /usr/lib/libbar.so.1, dependency field Depends)
5501 shlibs:Depends=libc6 (>= 2.2.2-2)
5502           </example>
5503           You can then run <prgn>ldd</prgn> on the binary to find the
5504           full location of the library concerned:
5505           <example compact="compact">
5506 $ ldd foo
5507 libbar.so.1 => /usr/lib/libbar.so.1 (0x4001e000)
5508 libc.so.6 => /lib/libc.so.6 (0x40032000)
5509 /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
5510           </example>
5511           So the <prgn>foo</prgn> binary depends on the
5512           <prgn>libbar</prgn> shared library, but no package seems to
5513           provide a <file>*.shlibs</file> file handling
5514           <file>libbar.so.1</file> in <file>/var/lib/dpkg/info/</file>.  Let's
5515           determine the package responsible:
5516           <example compact="compact">
5517 $ dpkg -S /usr/lib/libbar.so.1
5518 bar1: /usr/lib/libbar.so.1
5519 $ dpkg -s bar1 | grep Version
5520 Version: 1.0-1
5521           </example>
5522           This tells us that the <tt>bar1</tt> package, version 1.0-1,
5523           is the one we are using.  Now we can file a bug against the
5524           <tt>bar1</tt> package and create our own
5525           <file>debian/shlibs.local</file> to locally fix the problem.
5526           Including the following line into your
5527           <file>debian/shlibs.local</file> file:
5528           <example compact="compact">
5529 libbar 1 bar1 (>= 1.0-1)
5530           </example>
5531           should allow the package build to work.
5532         </p>
5533
5534         <p>
5535           As soon as the maintainer of <tt>bar1</tt> provides a
5536           correct <file>shlibs</file> file, you should remove this line
5537           from your <file>debian/shlibs.local</file> file.  (You should
5538           probably also then have a versioned <tt>Build-Depends</tt>
5539           on <tt>bar1</tt> to help ensure that others do not have the
5540           same problem building your package.)
5541         </p>
5542       </sect1>
5543
5544       </sect>
5545
5546     </chapt>
5547
5548
5549     <chapt id="opersys"><heading>The Operating System</heading>
5550
5551       <sect>
5552         <heading>File system hierarchy</heading>
5553
5554
5555         <sect1 id="fhs">
5556           <heading>File System Structure</heading>
5557
5558           <p>
5559             The location of all installed files and directories must
5560             comply with the Filesystem Hierarchy Standard (FHS),
5561             version 2.3, with the exceptions noted below, and except
5562             where doing so would violate other terms of Debian
5563             Policy.  The following exceptions to the FHS apply:
5564
5565             <enumlist>
5566               <item>
5567                 <p>
5568                   The optional rules related to user specific
5569                   configuration files for applications are stored in
5570                   the user's home directory are relaxed.  It is
5571                   recommended that such files start with the
5572                   '<tt>.</tt>' character (a "dot file"), and if an
5573                   application needs to create more than one dot file
5574                   then the preferred placement is in a subdirectory
5575                   with a name starting with a '.' character, (a "dot
5576                   directory"). In this case it is recommended the
5577                   configuration files not start with the '.'
5578                   character.
5579                 </p>
5580               </item>
5581               <item>
5582                 <p>
5583                   The requirement for amd64 to use <file>/lib64</file>
5584                   for 64 bit binaries is removed.
5585                 </p>
5586               </item>
5587               <item>
5588                 <p>
5589                   The requirement for object files, internal binaries, and
5590                   libraries, including <file>libc.so.*</file>, to be located
5591                   directly under <file>/lib{,32}</file> and
5592                   <file>/usr/lib{,32}</file> is amended, permitting files
5593                   to instead be installed to
5594                   <file>/lib/<var>triplet</var></file> and
5595                   <file>/usr/lib/<var>triplet</var></file>, where
5596                   <tt><var>triplet</var></tt> is the value returned by
5597                   <tt>dpkg-architecture -qDEB_HOST_GNU_TYPE</tt> for the
5598                   architecture of the package.  Packages may <em>not</em>
5599                   install files to any <var>triplet</var> path other
5600                   than the one matching the architecture of that package;
5601                   for instance, an <tt>Architecture: amd64</tt> package
5602                   containing 32-bit x86 libraries may not install these
5603                   libraries to <file>/usr/lib/i486-linux-gnu</file>.
5604                   <footnote>
5605                     This is necessary in order to reserve the directories for
5606                     use in cross-installation of library packages from other
5607                     architectures, as part of the planned deployment of
5608                     <tt>multiarch</tt>.
5609                   </footnote>
5610                 </p>
5611                 <p>
5612                   Applications may also use a single subdirectory under
5613                   <file>/usr/lib/<var>triplet</var></file>.
5614                 </p>
5615                 <p>
5616                   The execution time linker/loader, ld*, must still be made
5617                   available in the existing location under /lib or /lib64
5618                   since this is part of the ELF ABI for the architecture.
5619                 </p>
5620               </item>
5621               <item>
5622                 <p>
5623                   The requirement that
5624                   <file>/usr/local/share/man</file> be "synonymous"
5625                   with <file>/usr/local/man</file> is relaxed to a
5626                   recommendation</p>
5627               </item>
5628               <item>
5629                 <p>
5630                   The requirement that windowmanagers with a single
5631                   configuration file call it <file>system.*wmrc</file>
5632                   is removed, as is the restriction that the window
5633                   manager subdirectory be named identically to the
5634                   window manager name itself.
5635                 </p>
5636               </item>
5637               <item>
5638                 <p>
5639                   The requirement that boot manager configuration
5640                   files live in <file>/etc</file>, or at least are
5641                   symlinked there, is relaxed to a recommendation.
5642                 </p>
5643               </item>
5644               <item>
5645                 <p>
5646                   The following directories in the root filesystem are
5647                   additionally allowed: <file>/sys</file> and
5648                   <file>/selinux</file>. <footnote>These directories
5649                   are used as mount points to mount virtual filesystems
5650                   to get access to kernel information.</footnote>
5651                 </p>
5652               </item>
5653             </enumlist>
5654
5655           </p>
5656           <p>
5657             The version of this document referred here can be
5658             found in the <tt>debian-policy</tt> package or on <url
5659             id="http://www.debian.org/doc/packaging-manuals/fhs/"
5660               name="FHS (Debian copy)"> alongside this manual (or, if
5661             you have the <package>debian-policy</package> installed,
5662             you can try <url
5663               id="file:///usr/share/doc/debian-policy/fhs/" name="FHS
5664               (local copy)">). The
5665             latest version, which may be a more recent version, may
5666             be found on
5667             <url id="http://www.pathname.com/fhs/" name="FHS (upstream)">.
5668             Specific questions about following the standard may be
5669             asked on the <tt>debian-devel</tt> mailing list, or
5670             referred to the FHS mailing list (see the
5671             <url id="http://www.pathname.com/fhs/" name="FHS web site"> for
5672             more information).
5673           </p>
5674         </sect1>
5675
5676         <sect1>
5677           <heading>Site-specific programs</heading>
5678
5679           <p>
5680             As mandated by the FHS, packages must not place any
5681             files in <file>/usr/local</file>, either by putting them in
5682             the file system archive to be unpacked by <prgn>dpkg</prgn>
5683             or by manipulating them in their maintainer scripts.
5684           </p>
5685
5686           <p>
5687             However, the package may create empty directories below
5688             <file>/usr/local</file> so that the system administrator knows
5689             where to place site-specific files.  These are not
5690             directories <em>in</em> <file>/usr/local</file>, but are
5691             children of directories in <file>/usr/local</file>.  These
5692             directories (<file>/usr/local/*/dir/</file>)
5693             should be removed on package removal if they are
5694             empty.
5695           </p>
5696
5697           <p>
5698             Note that this applies only to
5699             directories <em>below</em> <file>/usr/local</file>,
5700             not <em>in</em> <file>/usr/local</file>.  Packages must
5701             not create sub-directories in the
5702             directory <file>/usr/local</file> itself, except those
5703             listed in FHS, section 4.5.  However, you may create
5704             directories below them as you wish. You must not remove
5705             any of the directories listed in 4.5, even if you created
5706             them.
5707           </p>
5708
5709           <p>
5710             Since <file>/usr/local</file> can be mounted read-only from a
5711             remote server, these directories must be created and
5712             removed by the <prgn>postinst</prgn> and <prgn>prerm</prgn>
5713             maintainer scripts and not be included in the
5714             <file>.deb</file> archive.  These scripts must not fail if
5715             either of these operations fail.
5716           </p>
5717
5718           <p>
5719             For example, the <tt>emacsen-common</tt> package could
5720             contain something like
5721             <example compact="compact">
5722 if [ ! -e /usr/local/share/emacs ]
5723 then
5724   if mkdir /usr/local/share/emacs 2>/dev/null
5725   then
5726     chown root:staff /usr/local/share/emacs
5727     chmod 2775 /usr/local/share/emacs
5728   fi
5729 fi
5730             </example>
5731             in its <prgn>postinst</prgn> script, and
5732             <example compact="compact">
5733 rmdir /usr/local/share/emacs/site-lisp 2>/dev/null || true
5734 rmdir /usr/local/share/emacs 2>/dev/null || true
5735             </example>
5736             in the <prgn>prerm</prgn> script.  (Note that this form is
5737             used to ensure that if the script is interrupted, the
5738             directory <file>/usr/local/share/emacs</file> will still be
5739             removed.)
5740           </p>
5741
5742           <p>
5743             If you do create a directory in <file>/usr/local</file> for
5744             local additions to a package, you should ensure that
5745             settings in <file>/usr/local</file> take precedence over the
5746             equivalents in <file>/usr</file>.
5747           </p>
5748
5749           <p>
5750             However, because <file>/usr/local</file> and its contents are
5751             for exclusive use of the local administrator, a package
5752             must not rely on the presence or absence of files or
5753             directories in <file>/usr/local</file> for normal operation.
5754           </p>
5755
5756           <p>
5757             The <file>/usr/local</file> directory itself and all the
5758             subdirectories created by the package should (by default) have
5759             permissions 2775 (group-writable and set-group-id) and be
5760             owned by <tt>root:staff</tt>.
5761           </p>
5762         </sect1>
5763
5764         <sect1>
5765           <heading>The system-wide mail directory</heading>
5766           <p>
5767             The system-wide mail directory
5768             is <file>/var/mail</file>. This directory is part of the
5769             base system and should not be owned by any particular mail
5770             agents.  The use of the old
5771             location <file>/var/spool/mail</file> is deprecated, even
5772             though the spool may still be physically located there.
5773           </p>
5774         </sect1>
5775       </sect>
5776
5777       <sect>
5778         <heading>Users and groups</heading>
5779
5780         <sect1>
5781           <heading>Introduction</heading>
5782           <p>
5783             The Debian system can be configured to use either plain or
5784             shadow passwords.
5785           </p>
5786
5787           <p>
5788             Some user ids (UIDs) and group ids (GIDs) are reserved
5789             globally for use by certain packages.  Because some
5790             packages need to include files which are owned by these
5791             users or groups, or need the ids compiled into binaries,
5792             these ids must be used on any Debian system only for the
5793             purpose for which they are allocated. This is a serious
5794             restriction, and we should avoid getting in the way of
5795             local administration policies. In particular, many sites
5796             allocate users and/or local system groups starting at 100.
5797           </p>
5798
5799           <p>
5800             Apart from this we should have dynamically allocated ids,
5801             which should by default be arranged in some sensible
5802             order, but the behavior should be configurable.
5803           </p>
5804
5805           <p>
5806             Packages other than <tt>base-passwd</tt> must not modify
5807             <file>/etc/passwd</file>, <file>/etc/shadow</file>,
5808             <file>/etc/group</file> or <file>/etc/gshadow</file>.
5809           </p>
5810         </sect1>
5811
5812         <sect1>
5813           <heading>UID and GID classes</heading>
5814           <p>
5815             The UID and GID numbers are divided into classes as
5816             follows:
5817             <taglist>
5818               <tag>0-99:</tag>
5819               <item>
5820                 <p>
5821                   Globally allocated by the Debian project, the same
5822                   on every Debian system.  These ids will appear in
5823                   the <file>passwd</file> and <file>group</file> files of all
5824                   Debian systems, new ids in this range being added
5825                   automatically as the <tt>base-passwd</tt> package is
5826                   updated.
5827                 </p>
5828
5829                 <p>
5830                   Packages which need a single statically allocated
5831                   uid or gid should use one of these; their
5832                   maintainers should ask the <tt>base-passwd</tt>
5833                   maintainer for ids.
5834                 </p>
5835               </item>
5836
5837               <tag>100-999:</tag>
5838               <item>
5839                 <p>
5840                   Dynamically allocated system users and groups.
5841                   Packages which need a user or group, but can have
5842                   this user or group allocated dynamically and
5843                   differently on each system, should use <tt>adduser
5844                   --system</tt> to create the group and/or user.
5845                   <prgn>adduser</prgn> will check for the existence of
5846                   the user or group, and if necessary choose an unused
5847                   id based on the ranges specified in
5848                   <file>adduser.conf</file>.
5849                 </p>
5850               </item>
5851
5852               <tag>1000-29999:</tag>
5853               <item>
5854                 <p>
5855                   Dynamically allocated user accounts.  By default
5856                   <prgn>adduser</prgn> will choose UIDs and GIDs for
5857                   user accounts in this range, though
5858                   <file>adduser.conf</file> may be used to modify this
5859                   behavior.
5860                 </p>
5861               </item>
5862
5863               <tag>30000-59999:</tag>
5864               <item>
5865                 <p>Reserved.</p>
5866               </item>
5867
5868               <tag>60000-64999:</tag>
5869               <item>
5870                 <p>
5871                   Globally allocated by the Debian project, but only
5872                   created on demand. The ids are allocated centrally
5873                   and statically, but the actual accounts are only
5874                   created on users' systems on demand.
5875                 </p>
5876
5877                 <p>
5878                   These ids are for packages which are obscure or
5879                   which require many statically-allocated ids.  These
5880                   packages should check for and create the accounts in
5881                   <file>/etc/passwd</file> or <file>/etc/group</file> (using
5882                   <prgn>adduser</prgn> if it has this facility) if
5883                   necessary.  Packages which are likely to require
5884                   further allocations should have a "hole" left after
5885                   them in the allocation, to give them room to
5886                   grow.
5887                 </p>
5888               </item>
5889
5890               <tag>65000-65533:</tag>
5891               <item>
5892                 <p>Reserved.</p>
5893               </item>
5894
5895               <tag>65534:</tag>
5896               <item>
5897                 <p>
5898                   User <tt>nobody</tt>. The corresponding gid refers
5899                   to the group <tt>nogroup</tt>.
5900                 </p>
5901               </item>
5902
5903               <tag>65535:</tag>
5904               <item>
5905                 <p>
5906                   <tt>(uid_t)(-1) == (gid_t)(-1)</tt> <em>must
5907                   not</em> be used, because it is the error return
5908                   sentinel value.
5909                 </p>
5910               </item>
5911             </taglist>
5912           </p>
5913         </sect1>
5914       </sect>
5915
5916       <sect id="sysvinit">
5917         <heading>System run levels and <file>init.d</file> scripts</heading>
5918
5919         <sect1 id="/etc/init.d">
5920           <heading>Introduction</heading>
5921
5922           <p>
5923             The <file>/etc/init.d</file> directory contains the scripts
5924             executed by <prgn>init</prgn> at boot time and when the
5925             init state (or "runlevel") is changed (see <manref
5926             name="init" section="8">).
5927           </p>
5928
5929           <p>
5930             There are at least two different, yet functionally
5931             equivalent, ways of handling these scripts.  For the sake
5932             of simplicity, this document describes only the symbolic
5933             link method. However, it must not be assumed by maintainer
5934             scripts that this method is being used, and any automated
5935             manipulation of the various runlevel behaviors by
5936             maintainer scripts must be performed using
5937             <prgn>update-rc.d</prgn> as described below and not by
5938             manually installing or removing symlinks.  For information
5939             on the implementation details of the other method,
5940             implemented in the <tt>file-rc</tt> package, please refer
5941             to the documentation of that package.
5942           </p>
5943
5944           <p>
5945             These scripts are referenced by symbolic links in the
5946             <file>/etc/rc<var>n</var>.d</file> directories.  When changing
5947             runlevels, <prgn>init</prgn> looks in the directory
5948             <file>/etc/rc<var>n</var>.d</file> for the scripts it should
5949             execute, where <tt><var>n</var></tt> is the runlevel that
5950             is being changed to, or <tt>S</tt> for the boot-up
5951             scripts.
5952           </p>
5953
5954           <p>
5955             The names of the links all have the form
5956             <file>S<var>mm</var><var>script</var></file> or
5957             <file>K<var>mm</var><var>script</var></file> where
5958             <var>mm</var> is a two-digit number and <var>script</var>
5959             is the name of the script (this should be the same as the
5960             name of the actual script in <file>/etc/init.d</file>).
5961           </p>
5962
5963           <p>
5964             When <prgn>init</prgn> changes runlevel first the targets
5965             of the links whose names start with a <tt>K</tt> are
5966             executed, each with the single argument <tt>stop</tt>,
5967             followed by the scripts prefixed with an <tt>S</tt>, each
5968             with the single argument <tt>start</tt>.  (The links are
5969             those in the <file>/etc/rc<var>n</var>.d</file> directory
5970             corresponding to the new runlevel.)  The <tt>K</tt> links
5971             are responsible for killing services and the <tt>S</tt>
5972             link for starting services upon entering the runlevel.
5973           </p>
5974
5975           <p>
5976             For example, if we are changing from runlevel 2 to
5977             runlevel 3, init will first execute all of the <tt>K</tt>
5978             prefixed scripts it finds in <file>/etc/rc3.d</file>, and then
5979             all of the <tt>S</tt> prefixed scripts in that directory.
5980             The links starting with <tt>K</tt> will cause the
5981             referred-to file to be executed with an argument of
5982             <tt>stop</tt>, and the <tt>S</tt> links with an argument
5983             of <tt>start</tt>.
5984           </p>
5985
5986           <p>
5987             The two-digit number <var>mm</var> is used to determine
5988             the order in which to run the scripts: low-numbered links
5989             have their scripts run first.  For example, the
5990             <tt>K20</tt> scripts will be executed before the
5991             <tt>K30</tt> scripts.  This is used when a certain service
5992             must be started before another.  For example, the name
5993             server <prgn>bind</prgn> might need to be started before
5994             the news server <prgn>inn</prgn> so that <prgn>inn</prgn>
5995             can set up its access lists.  In this case, the script
5996             that starts <prgn>bind</prgn> would have a lower number
5997             than the script that starts <prgn>inn</prgn> so that it
5998             runs first:
5999             <example compact="compact">
6000 /etc/rc2.d/S17bind
6001 /etc/rc2.d/S70inn
6002             </example>
6003           </p>
6004
6005           <p>
6006             The two runlevels 0 (halt) and 6 (reboot) are slightly
6007             different.  In these runlevels, the links with an
6008             <tt>S</tt> prefix are still called after those with a
6009             <tt>K</tt> prefix, but they too are called with the single
6010             argument <tt>stop</tt>.
6011           </p>
6012         </sect1>
6013
6014         <sect1 id="writing-init">
6015           <heading>Writing the scripts</heading>
6016
6017           <p>
6018             Packages that include daemons for system services should
6019             place scripts in <file>/etc/init.d</file> to start or stop
6020             services at boot time or during a change of runlevel.
6021             These scripts should be named
6022             <file>/etc/init.d/<var>package</var></file>, and they should
6023             accept one argument, saying what to do:
6024
6025             <taglist>
6026               <tag><tt>start</tt></tag>
6027               <item>start the service,</item>
6028
6029               <tag><tt>stop</tt></tag>
6030               <item>stop the service,</item>
6031
6032               <tag><tt>restart</tt></tag>
6033               <item>stop and restart the service if it's already running,
6034                   otherwise start the service</item>
6035
6036               <tag><tt>reload</tt></tag>
6037               <item><p>cause the configuration of the service to be
6038                   reloaded without actually stopping and restarting
6039                   the service,</item>
6040
6041               <tag><tt>force-reload</tt></tag>
6042               <item>cause the configuration to be reloaded if the
6043                   service supports this, otherwise restart the
6044                   service.</item>
6045             </taglist>
6046
6047             The <tt>start</tt>, <tt>stop</tt>, <tt>restart</tt>, and
6048             <tt>force-reload</tt> options should be supported by all
6049             scripts in <file>/etc/init.d</file>, the <tt>reload</tt>
6050             option is optional.
6051           </p>
6052
6053           <p>
6054             The <file>init.d</file> scripts must ensure that they will
6055             behave sensibly (i.e., returning success and not starting
6056             multiple copies of a service) if invoked with <tt>start</tt>
6057             when the service is already running, or with <tt>stop</tt>
6058             when it isn't, and that they don't kill unfortunately-named
6059             user processes.  The best way to achieve this is usually to
6060             use <prgn>start-stop-daemon</prgn> with the <tt>--oknodo</tt>
6061             option.
6062           </p>
6063
6064           <p>
6065             Be careful of using <tt>set -e</tt> in <file>init.d</file>
6066             scripts.  Writing correct <file>init.d</file> scripts requires
6067             accepting various error exit statuses when daemons are already
6068             running or already stopped without aborting
6069             the <file>init.d</file> script, and common <file>init.d</file>
6070             function libraries are not safe to call with <tt>set -e</tt>
6071             in effect<footnote>
6072               <tt>/lib/lsb/init-functions</tt>, which assists in writing
6073               LSB-compliant init scripts, may fail if <tt>set -e</tt> is
6074               in effect and echoing status messages to the console fails,
6075               for example.
6076             </footnote>.  For <tt>init.d</tt> scripts, it's often easier
6077             to not use <tt>set -e</tt> and instead check the result of
6078             each command separately.
6079           </p>
6080
6081           <p>
6082             If a service reloads its configuration automatically (as
6083             in the case of <prgn>cron</prgn>, for example), the
6084             <tt>reload</tt> option of the <file>init.d</file> script
6085             should behave as if the configuration has been reloaded
6086             successfully.
6087           </p>
6088
6089           <p>
6090             The <file>/etc/init.d</file> scripts must be treated as
6091             configuration files, either (if they are present in the
6092             package, that is, in the .deb file) by marking them as
6093             <tt>conffile</tt>s, or, (if they do not exist in the .deb)
6094             by managing them correctly in the maintainer scripts (see
6095             <ref id="config-files">).  This is important since we want
6096             to give the local system administrator the chance to adapt
6097             the scripts to the local system, e.g., to disable a
6098             service without de-installing the package, or to specify
6099             some special command line options when starting a service,
6100             while making sure their changes aren't lost during the next
6101             package upgrade.
6102           </p>
6103
6104           <p>
6105             These scripts should not fail obscurely when the
6106             configuration files remain but the package has been
6107             removed, as configuration files remain on the system after
6108             the package has been removed.  Only when <prgn>dpkg</prgn>
6109             is executed with the <tt>--purge</tt> option will
6110             configuration files be removed.  In particular, as the
6111             <file>/etc/init.d/<var>package</var></file> script itself is
6112             usually a <tt>conffile</tt>, it will remain on the system
6113             if the package is removed but not purged.  Therefore, you
6114             should include a <tt>test</tt> statement at the top of the
6115             script, like this:
6116             <example compact="compact">
6117 test -f <var>program-executed-later-in-script</var> || exit 0
6118             </example>
6119           </p>
6120
6121           <p>
6122             Often there are some variables in the <file>init.d</file>
6123             scripts whose values control the behavior of the scripts,
6124             and which a system administrator is likely to want to
6125             change.  As the scripts themselves are frequently
6126             <tt>conffile</tt>s, modifying them requires that the
6127             administrator merge in their changes each time the package
6128             is upgraded and the <tt>conffile</tt> changes.  To ease
6129             the burden on the system administrator, such configurable
6130             values should not be placed directly in the script.
6131             Instead, they should be placed in a file in
6132             <file>/etc/default</file>, which typically will have the same
6133             base name as the <file>init.d</file> script.  This extra file
6134             should be sourced by the script when the script runs.  It
6135             must contain only variable settings and comments in SUSv3
6136             <prgn>sh</prgn> format.  It may either be a
6137             <tt>conffile</tt> or a configuration file maintained by
6138             the package maintainer scripts.  See <ref id="config-files">
6139             for more details.
6140           </p>
6141
6142           <p>
6143             To ensure that vital configurable values are always
6144             available, the <file>init.d</file> script should set default
6145             values for each of the shell variables it uses, either
6146             before sourcing the <file>/etc/default/</file> file or
6147             afterwards using something like the <tt>:
6148             ${VAR:=default}</tt> syntax.  Also, the <file>init.d</file>
6149             script must behave sensibly and not fail if the
6150             <file>/etc/default</file> file is deleted.
6151           </p>
6152
6153           <p>
6154             <file>/var/run</file> and <file>/var/lock</file> may be mounted
6155             as temporary filesystems<footnote>
6156                 For example, using the <tt>RAMRUN</tt> and <tt>RAMLOCK</tt>
6157                 options in <file>/etc/default/rcS</file>.
6158             </footnote>, so the <file>init.d</file> scripts must handle this
6159             correctly. This will typically amount to creating any required
6160             subdirectories dynamically when the <file>init.d</file> script
6161             is run, rather than including them in the package and relying on
6162             <prgn>dpkg</prgn> to create them.
6163           </p>
6164         </sect1>
6165
6166         <sect1>
6167           <heading>Interfacing with the initscript system</heading>
6168
6169           <p>
6170             Maintainers should use the abstraction layer provided by
6171             the <prgn>update-rc.d</prgn> and <prgn>invoke-rc.d</prgn>
6172             programs to deal with initscripts in their packages'
6173             scripts such as <prgn>postinst</prgn>, <prgn>prerm</prgn>
6174             and <prgn>postrm</prgn>.
6175           </p>
6176
6177           <p>
6178             Directly managing the /etc/rc?.d links and directly
6179             invoking the <file>/etc/init.d/</file> initscripts should
6180             be done only by packages providing the initscript
6181             subsystem (such as <prgn>sysv-rc</prgn> and
6182             <prgn>file-rc</prgn>).
6183           </p>
6184
6185           <sect2>
6186             <heading>Managing the links</heading>
6187
6188             <p>
6189               The program <prgn>update-rc.d</prgn> is provided for
6190               package maintainers to arrange for the proper creation and
6191               removal of <file>/etc/rc<var>n</var>.d</file> symbolic links,
6192               or their functional equivalent if another method is being
6193               used.  This may be used by maintainers in their packages'
6194               <prgn>postinst</prgn> and <prgn>postrm</prgn> scripts.
6195             </p>
6196
6197             <p>
6198               You must not include any <file>/etc/rc<var>n</var>.d</file>
6199               symbolic links in the actual archive or manually create or
6200               remove the symbolic links in maintainer scripts; you must
6201               use the <prgn>update-rc.d</prgn> program instead.  (The
6202               former will fail if an alternative method of maintaining
6203               runlevel information is being used.)  You must not include
6204               the <file>/etc/rc<var>n</var>.d</file> directories themselves
6205               in the archive either.  (Only the <tt>sysvinit</tt>
6206               package may do so.)
6207             </p>
6208
6209             <p>
6210               By default <prgn>update-rc.d</prgn> will start services in
6211               each of the multi-user state runlevels (2, 3, 4, and 5)
6212               and stop them in the halt runlevel (0), the single-user
6213               runlevel (1) and the reboot runlevel (6).  The system
6214               administrator will have the opportunity to customize
6215               runlevels by simply adding, moving, or removing the
6216               symbolic links in <file>/etc/rc<var>n</var>.d</file> if
6217               symbolic links are being used, or by modifying
6218               <file>/etc/runlevel.conf</file> if the <tt>file-rc</tt> method
6219               is being used.
6220             </p>
6221
6222             <p>
6223               To get the default behavior for your package, put in your
6224               <prgn>postinst</prgn> script
6225               <example compact="compact">
6226                 update-rc.d <var>package</var> defaults
6227               </example>
6228               and in your <prgn>postrm</prgn>
6229               <example compact="compact">
6230                 if [ "$1" = purge ]; then
6231                 update-rc.d <var>package</var> remove
6232                 fi
6233               </example>. Note that if your package changes runlevels
6234               or priority, you may have to remove and recreate the links,
6235               since otherwise the old links may persist. Refer to the
6236               documentation of <prgn>update-rc.d</prgn>.
6237             </p>
6238
6239             <p>
6240               This will use a default sequence number of 20.  If it does
6241               not matter when or in which order the <file>init.d</file>
6242               script is run, use this default.  If it does, then you
6243               should talk to the maintainer of the <prgn>sysvinit</prgn>
6244               package or post to <tt>debian-devel</tt>, and they will
6245               help you choose a number.
6246             </p>
6247
6248             <p>
6249               For more information about using <tt>update-rc.d</tt>,
6250               please consult its man page <manref name="update-rc.d"
6251                 section="8">.
6252             </p>
6253           </sect2>
6254
6255           <sect2>
6256             <heading>Running initscripts</heading>
6257             <p>
6258               The program <prgn>invoke-rc.d</prgn> is provided to make
6259               it easier for package maintainers to properly invoke an
6260               initscript, obeying runlevel and other locally-defined
6261               constraints that might limit a package's right to start,
6262               stop and otherwise manage services. This program may be
6263               used by maintainers in their packages' scripts.
6264             </p>
6265
6266             <p>
6267               The package maintainer scripts must use
6268               <prgn>invoke-rc.d</prgn> to invoke the
6269               <file>/etc/init.d/*</file> initscripts, instead of
6270               calling them directly.
6271             </p>
6272
6273             <p>
6274               By default, <prgn>invoke-rc.d</prgn> will pass any
6275               action requests (start, stop, reload, restart...) to the
6276               <file>/etc/init.d</file> script, filtering out requests
6277               to start or restart a service out of its intended
6278               runlevels.
6279             </p>
6280
6281             <p>
6282               Most packages will simply need to change:
6283               <example compact="compact">/etc/init.d/&lt;package&gt;
6284               &lt;action&gt;</example> in their <prgn>postinst</prgn>
6285               and <prgn>prerm</prgn> scripts to:
6286               <example compact="compact">
6287         if which invoke-rc.d >/dev/null 2>&1; then
6288                 invoke-rc.d <var>package</var> &lt;action&gt;
6289         else
6290                 /etc/init.d/<var>package</var> &lt;action&gt;
6291         fi
6292               </example>
6293             </p>
6294
6295             <p>
6296               A package should register its initscript services using
6297               <prgn>update-rc.d</prgn> before it tries to invoke them
6298               using <prgn>invoke-rc.d</prgn>. Invocation of
6299               unregistered services may fail.
6300             </p>
6301
6302             <p>
6303               For more information about using
6304               <prgn>invoke-rc.d</prgn>, please consult its man page
6305               <manref name="invoke-rc.d" section="8">.
6306             </p>
6307           </sect2>
6308         </sect1>
6309
6310         <sect1>
6311           <heading>Boot-time initialization</heading>
6312
6313           <p>
6314             There used to be another directory, <file>/etc/rc.boot</file>,
6315             which contained scripts which were run once per machine
6316             boot. This has been deprecated in favour of links from
6317             <file>/etc/rcS.d</file> to files in <file>/etc/init.d</file> as
6318             described in <ref id="/etc/init.d">.  Packages must not
6319             place files in <file>/etc/rc.boot</file>.
6320           </p>
6321         </sect1>
6322
6323         <sect1>
6324           <heading>Example</heading>
6325
6326           <p>
6327             An example on which you can base your
6328             <file>/etc/init.d</file> scripts is found in
6329             <file>/etc/init.d/skeleton</file>.
6330           </p>
6331
6332         </sect1>
6333       </sect>
6334
6335       <sect>
6336         <heading>Console messages from <file>init.d</file> scripts</heading>
6337
6338         <p>
6339           This section describes the formats to be used for messages
6340           written to standard output by the <file>/etc/init.d</file>
6341           scripts.  The intent is to improve the consistency of
6342           Debian's startup and shutdown look and feel.  For this
6343           reason, please look very carefully at the details.  We want
6344           the messages to have the same format in terms of wording,
6345           spaces, punctuation and case of letters.
6346         </p>
6347
6348         <p>
6349           Here is a list of overall rules that should be used for
6350           messages generated by <file>/etc/init.d</file> scripts.  
6351         </p>
6352
6353         <p>
6354           <list>
6355             <item>
6356                 The message should fit in one line (fewer than 80
6357                 characters), start with a capital letter and end with
6358                 a period (<tt>.</tt>) and line feed (<tt>"\n"</tt>).
6359             </item>
6360
6361             <item>
6362               If the script is performing some time consuming task in
6363               the background (not merely starting or stopping a
6364               program, for instance), an ellipsis (three dots:
6365               <tt>...</tt>) should be output to the screen, with no
6366               leading or tailing whitespace or line feeds.
6367             </item>
6368
6369             <item>
6370               The messages should appear as if the computer is telling
6371               the user what it is doing (politely :-), but should not
6372                 mention "it" directly.  For example, instead of:
6373                 <example compact="compact">
6374 I'm starting network daemons: nfsd mountd.
6375                 </example>
6376                 the message should say
6377                 <example compact="compact">
6378 Starting network daemons: nfsd mountd.
6379                 </example>
6380             </item>
6381           </list>
6382         </p>
6383
6384         <p>
6385           <tt>init.d</tt> script should use the following  standard
6386           message formats for the situations enumerated below.
6387         </p>
6388
6389         <p>
6390           <list>
6391             <item>
6392               <p>When daemons are started</p>
6393
6394               <p>
6395                 If the script starts one or more daemons, the output
6396                 should look like this (a single line, no leading
6397                 spaces):
6398                 <example compact="compact">
6399 Starting <var>description</var>: <var>daemon-1</var> ... <var>daemon-n</var>.
6400                 </example>
6401                 The <var>description</var> should describe the
6402                 subsystem the daemon or set of daemons are part of,
6403                 while <var>daemon-1</var> up to <var>daemon-n</var>
6404                 denote each daemon's name (typically the file name of
6405                 the program).
6406               </p>
6407
6408               <p>
6409                 For example, the output of <file>/etc/init.d/lpd</file>
6410                 would look like:
6411                 <example compact="compact">
6412 Starting printer spooler: lpd.
6413                 </example>
6414               </p>
6415
6416               <p>
6417                 This can be achieved by saying
6418                 <example compact="compact">
6419 echo -n "Starting printer spooler: lpd"
6420 start-stop-daemon --start --quiet --exec /usr/sbin/lpd
6421 echo "."
6422                 </example>
6423                 in the script. If there are more than one daemon to
6424                 start, the output should look like this:
6425                 <example compact="compact">
6426 echo -n "Starting remote file system services:"
6427 echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
6428 echo -n " mountd"; start-stop-daemon --start --quiet mountd
6429 echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
6430 echo "."
6431                 </example>
6432                 This makes it possible for the user to see what is
6433                 happening and when the final daemon has been started.
6434                 Care should be taken in the placement of white spaces:
6435                 in the example above the system administrators can
6436                 easily comment out a line if they don't want to start
6437                 a specific daemon, while the displayed message still
6438                 looks good.
6439               </p>
6440             </item>
6441
6442             <item>
6443               <p>When a system parameter is being set</p>
6444
6445               <p>
6446                 If you have to set up different system parameters
6447                 during the system boot, you should use this format:
6448                 <example compact="compact">
6449 Setting <var>parameter</var> to "<var>value</var>".
6450                 </example>
6451               </p>
6452
6453               <p>
6454                 You can use a statement such as the following to get
6455                 the quotes right:
6456                 <example compact="compact">
6457 echo "Setting DNS domainname to \"$domainname\"."
6458                 </example>
6459               </p>
6460
6461               <p>
6462                 Note that the same symbol (<tt>"</tt>) <!-- " --> is used
6463                 for the left and right quotation marks.  A grave accent
6464                 (<tt>`</tt>) is not a quote character; neither is an
6465                 apostrophe (<tt>'</tt>).
6466               </p>
6467             </item>
6468
6469             <item>
6470               <p>When a daemon is stopped or restarted</p>
6471
6472               <p>
6473                 When you stop or restart a daemon, you should issue a
6474                 message identical to the startup message, except that
6475                 <tt>Starting</tt> is replaced with <tt>Stopping</tt>
6476                 or <tt>Restarting</tt> respectively.
6477               </p>
6478
6479               <p>
6480                 For example, stopping the printer daemon will look like
6481                 this:
6482                 <example compact="compact">
6483 Stopping printer spooler: lpd.
6484                 </example>
6485               </p>
6486             </item>
6487
6488             <item>
6489               <p>When something is executed</p>
6490
6491               <p>
6492                 There are several examples where you have to run a
6493                 program at system startup or shutdown to perform a
6494                 specific task, for example, setting the system's clock
6495                 using <prgn>netdate</prgn> or killing all processes
6496                 when the system shuts down.  Your message should look
6497                 like this:
6498                 <example compact="compact">
6499 Doing something very useful...done.
6500                 </example>
6501                 You should print the <tt>done.</tt> immediately after
6502                 the job has been completed, so that the user is
6503                 informed why they have to wait.  You can get this
6504                 behavior by saying
6505                 <example compact="compact">
6506 echo -n "Doing something very useful..."
6507 do_something
6508 echo "done."
6509                 </example>
6510                 in your script.
6511               </p>
6512             </item>
6513
6514             <item>
6515               <p>When the configuration is reloaded</p>
6516
6517               <p>
6518                 When a daemon is forced to reload its configuration
6519                 files you should use the following format:
6520                 <example compact="compact">
6521 Reloading <var>description</var> configuration...done.
6522                 </example>
6523                 where <var>description</var> is the same as in the
6524                 daemon starting message.
6525               </p>
6526             </item>
6527           </list>
6528         </p>
6529       </sect>
6530
6531       <sect>
6532         <heading>Cron jobs</heading>
6533
6534         <p>
6535           Packages must not modify the configuration file
6536           <file>/etc/crontab</file>, and they must not modify the files in
6537           <file>/var/spool/cron/crontabs</file>.</p>
6538
6539         <p>
6540           If a package wants to install a job that has to be executed
6541           via cron, it should place a file with the name of the
6542           package in one or more of the following directories:
6543           <example compact="compact">
6544 /etc/cron.hourly
6545 /etc/cron.daily
6546 /etc/cron.weekly
6547 /etc/cron.monthly
6548           </example>
6549           As these directory names imply, the files within them are
6550           executed on an hourly, daily, weekly, or monthly basis,
6551           respectively. The exact times are listed in
6552           <file>/etc/crontab</file>.</p>
6553
6554         <p>
6555           All files installed in any of these directories must be
6556           scripts (e.g., shell scripts or Perl scripts) so that they
6557           can easily be modified by the local system administrator.
6558           In addition, they must be treated as configuration files.
6559         </p>
6560
6561         <p>
6562           If a certain job has to be executed at some other frequency or
6563           at a specific time, the package should install a file
6564           <file>/etc/cron.d/<var>package</var></file>. This file uses the
6565           same syntax as <file>/etc/crontab</file> and is processed by
6566           <prgn>cron</prgn> automatically. The file must also be
6567           treated as a configuration file. (Note that entries in the
6568           <file>/etc/cron.d</file> directory are not handled by
6569           <prgn>anacron</prgn>. Thus, you should only use this
6570           directory for jobs which may be skipped if the system is not
6571           running.)</p>
6572         <p>
6573           Unlike <file>crontab</file> files described in the IEEE Std
6574           1003.1-2008 (POSIX.1) available from
6575           <url id="http://www.opengroup.org/onlinepubs/9699919799/"
6576                name="The Open Group">, the files in
6577           <file>/etc/cron.d</file> and the file
6578           <file>/etc/crontab</file> have seven fields; namely:
6579           <enumlist>
6580             <item>Minute [0,59]</item>
6581             <item>Hour [0,23]</item>
6582             <item>Day of the month [1,31]</item>
6583             <item>Month of the year [1,12]</item>
6584             <item>Day of the week ([0,6] with 0=Sunday)</item>
6585             <item>Username</item>
6586             <item>Command to be run</item>
6587           </enumlist>
6588           Ranges of numbers are allowed.  Ranges are two numbers
6589           separated with a hyphen.  The specified range is inclusive.
6590           Lists are allowed.  A list is a set of numbers (or ranges)
6591           separated by commas. Step values can be used in conjunction
6592           with ranges.
6593         </p>
6594
6595         <p>
6596           The scripts or <tt>crontab</tt> entries in these directories should
6597           check if all necessary programs are installed before they
6598           try to execute them. Otherwise, problems will arise when a
6599           package was removed but not purged since configuration files
6600           are kept on the system in this situation.
6601         </p>
6602
6603         <p>
6604           Any <tt>cron</tt> daemon must provide
6605           <file>/usr/bin/crontab</file> and support normal
6606           <tt>crontab</tt> entries as specified in POSIX. The daemon
6607           must also support names for days and months, ranges, and
6608           step values. It has to support <file>/etc/crontab</file>,
6609           and correctly execute the scripts in
6610           <file>/etc/cron.d</file>. The daemon must also correctly
6611           execute scripts in
6612           <file>/etc/cron.{hourly,daily,weekly,monthly}</file>.
6613         </p>
6614       </sect>
6615
6616       <sect id="menus">
6617         <heading>Menus</heading>
6618
6619         <p>
6620           The Debian <tt>menu</tt> package provides a standard
6621           interface between packages providing applications and
6622           <em>menu programs</em> (either X window managers or
6623           text-based menu programs such as <prgn>pdmenu</prgn>).
6624         </p>
6625
6626         <p>
6627           All packages that provide applications that need not be
6628           passed any special command line arguments for normal
6629           operation should register a menu entry for those
6630           applications, so that users of the <tt>menu</tt> package
6631           will automatically get menu entries in their window
6632           managers, as well in shells like <tt>pdmenu</tt>.
6633         </p>
6634
6635         <p>
6636           Menu entries should follow the current menu policy.
6637         </p>
6638
6639         <p>
6640           The menu policy can be found in the <tt>menu-policy</tt>
6641           files in the <tt>debian-policy</tt> package.
6642           It is also available from the Debian web mirrors at
6643           <tt><url name="/doc/packaging-manuals/menu-policy/"
6644                 id="http://www.debian.org/doc/packaging-manuals/menu-policy/"></tt>.
6645         </p>
6646
6647         <p>
6648           Please also refer to the <em>Debian Menu System</em>
6649           documentation that comes with the <package>menu</package>
6650           package for information about how to register your
6651           applications.
6652         </p>
6653       </sect>
6654
6655       <sect id="mime">
6656         <heading>Multimedia handlers</heading>
6657
6658         <p>
6659           MIME (Multipurpose Internet Mail Extensions, RFCs 2045-2049)
6660           is a mechanism for encoding files and data streams and
6661           providing meta-information about them, in particular their
6662           type (e.g.  audio or video) and format (e.g. PNG, HTML,
6663           MP3).
6664         </p>
6665
6666         <p>
6667           Registration of MIME type handlers allows programs like mail
6668           user agents and web browsers to invoke these handlers to
6669           view, edit or display MIME types they don't support directly.
6670         </p>
6671
6672         <p>
6673           Packages which provide the ability to view/show/play,
6674           compose, edit or print MIME types should register themselves
6675           as such following the current MIME support policy.
6676         </p>
6677
6678         <p>
6679           The MIME support policy can be found in the <tt>mime-policy</tt>
6680           files in the <tt>debian-policy</tt> package.
6681           It is also available from the Debian web mirrors at
6682           <tt><url name="/doc/packaging-manuals/mime-policy/"
6683                 id="http://www.debian.org/doc/packaging-manuals/mime-policy/"></tt>.
6684         </p>
6685
6686       </sect>
6687
6688       <sect>
6689         <heading>Keyboard configuration</heading>
6690
6691         <p>
6692           To achieve a consistent keyboard configuration so that all
6693           applications interpret a keyboard event the same way, all
6694           programs in the Debian distribution must be configured to
6695           comply with the following guidelines.
6696         </p>
6697
6698         <p>
6699           The following keys must have the specified interpretations:
6700
6701           <taglist>
6702             <tag><tt>&lt;--</tt></tag>
6703             <item>delete the character to the left of the cursor</item>
6704
6705             <tag><tt>Delete</tt></tag>
6706             <item>delete the character to the right of the cursor</item>
6707
6708             <tag><tt>Control+H</tt></tag>
6709             <item>emacs: the help prefix</item>
6710           </taglist>
6711
6712           The interpretation of any keyboard events should be
6713           independent of the terminal that is used, be it a virtual
6714           console, an X terminal emulator, an rlogin/telnet session,
6715           etc.
6716         </p>
6717
6718         <p>
6719           The following list explains how the different programs
6720           should be set up to achieve this:
6721         </p>
6722
6723         <p>
6724           <list>
6725             <item>
6726                 <tt>&lt;--</tt> generates <tt>KB_BackSpace</tt> in X.
6727             </item>
6728
6729             <item>
6730                 <tt>Delete</tt> generates <tt>KB_Delete</tt> in X.
6731             </item>
6732
6733             <item>
6734                 X translations are set up to make
6735                 <tt>KB_Backspace</tt> generate ASCII DEL, and to make
6736                 <tt>KB_Delete</tt> generate <tt>ESC [ 3 ~</tt> (this
6737                 is the vt220 escape code for the "delete character"
6738                 key).  This must be done by loading the X resources
6739                 using <prgn>xrdb</prgn> on all local X displays, not
6740                 using the application defaults, so that the
6741                 translation resources used correspond to the
6742                 <prgn>xmodmap</prgn> settings.
6743             </item>
6744
6745             <item>
6746                 The Linux console is configured to make
6747                 <tt>&lt;--</tt> generate DEL, and <tt>Delete</tt>
6748                 generate <tt>ESC [ 3 ~</tt>.
6749             </item>
6750
6751             <item>
6752                 X applications are configured so that <tt>&lt;</tt>
6753                 deletes left, and <tt>Delete</tt> deletes right.  Motif
6754                 applications already work like this.
6755             </item>
6756
6757             <item>
6758                 Terminals should have <tt>stty erase ^?</tt> .
6759             </item>
6760
6761             <item>
6762                 The <tt>xterm</tt> terminfo entry should have <tt>ESC
6763                 [ 3 ~</tt> for <tt>kdch1</tt>, just as for
6764                 <tt>TERM=linux</tt> and <tt>TERM=vt220</tt>.
6765             </item>
6766
6767             <item>
6768                 Emacs is programmed to map <tt>KB_Backspace</tt> or
6769                 the <tt>stty erase</tt> character to
6770                 <tt>delete-backward-char</tt>, and <tt>KB_Delete</tt>
6771                 or <tt>kdch1</tt> to <tt>delete-forward-char</tt>, and
6772                 <tt>^H</tt> to <tt>help</tt> as always.
6773             </item>
6774
6775             <item>
6776                 Other applications use the <tt>stty erase</tt>
6777                 character and <tt>kdch1</tt> for the two delete keys,
6778                 with ASCII DEL being "delete previous character" and
6779                 <tt>kdch1</tt> being "delete character under
6780                 cursor".
6781             </item>
6782
6783           </list>
6784         </p>
6785
6786         <p>
6787           This will solve the problem except for the following
6788           cases:
6789         </p>
6790
6791         <p>
6792           <list>
6793             <item>
6794                 Some terminals have a <tt>&lt;--</tt> key that cannot
6795                 be made to produce anything except <tt>^H</tt>.  On
6796                 these terminals Emacs help will be unavailable on
6797                 <tt>^H</tt> (assuming that the <tt>stty erase</tt>
6798                 character takes precedence in Emacs, and has been set
6799                 correctly).  <tt>M-x help</tt> or <tt>F1</tt> (if
6800                 available) can be used instead.
6801             </item>
6802
6803             <item>
6804                 Some operating systems use <tt>^H</tt> for <tt>stty
6805                 erase</tt>.  However, modern telnet versions and all
6806                 rlogin versions propagate <tt>stty</tt> settings, and
6807                 almost all UNIX versions honour <tt>stty erase</tt>.
6808                 Where the <tt>stty</tt> settings are not propagated
6809                 correctly, things can be made to work by using
6810                 <tt>stty</tt> manually.
6811             </item>
6812
6813             <item>
6814                 Some systems (including previous Debian versions) use
6815                 <prgn>xmodmap</prgn> to arrange for both
6816                 <tt>&lt;--</tt> and <tt>Delete</tt> to generate
6817                 <tt>KB_Delete</tt>.  We can change the behavior of
6818                 their X clients using the same X resources that we use
6819                 to do it for our own clients, or configure our clients
6820                 using their resources when things are the other way
6821                 around.  On displays configured like this
6822                 <tt>Delete</tt> will not work, but <tt>&lt;--</tt>
6823                 will.
6824             </item>
6825
6826             <item>
6827                 Some operating systems have different <tt>kdch1</tt>
6828                 settings in their <tt>terminfo</tt> database for
6829                 <tt>xterm</tt> and others.  On these systems the
6830                 <tt>Delete</tt> key will not work correctly when you
6831                 log in from a system conforming to our policy, but
6832                 <tt>&lt;--</tt> will.
6833             </item>
6834           </list>
6835         </p>
6836       </sect>
6837
6838       <sect>
6839         <heading>Environment variables</heading>
6840
6841         <p>
6842           A program must not depend on environment variables to get
6843           reasonable defaults.  (That's because these environment
6844           variables would have to be set in a system-wide
6845           configuration file like <file>/etc/profile</file>, which is not
6846           supported by all shells.)
6847         </p>
6848
6849         <p>
6850           If a program usually depends on environment variables for its
6851           configuration, the program should be changed to fall back to
6852           a reasonable default configuration if these environment
6853           variables are not present. If this cannot be done easily
6854           (e.g., if the source code of a non-free program is not
6855           available), the program must be replaced by a small
6856           "wrapper" shell script which sets the environment variables
6857           if they are not already defined, and calls the original program.
6858         </p>
6859
6860         <p>
6861           Here is an example of a wrapper script for this purpose:
6862
6863           <example compact="compact">
6864 #!/bin/sh
6865 BAR=${BAR:-/var/lib/fubar}
6866 export BAR
6867 exec /usr/lib/foo/foo "$@"
6868           </example>
6869         </p>
6870
6871         <p>
6872           Furthermore, as <file>/etc/profile</file> is a configuration
6873           file of the <prgn>base-files</prgn> package, other packages must
6874           not put any environment variables or other commands into that
6875           file.
6876         </p>
6877       </sect>
6878
6879       <sect id="doc-base">
6880         <heading>Registering Documents using doc-base</heading>
6881
6882         <p>
6883           The <package>doc-base</package> package implements a
6884           flexible mechanism for handling and presenting
6885           documentation. The recommended practice is for every Debian
6886           package that provides online documentation (other than just
6887           manual pages) to register these documents with
6888           <package>doc-base</package> by installing a
6889           <package>doc-base</package> control file via the
6890           <prgn/install-docs/ script at installation time and
6891           de-register the manuals again when the package is removed.
6892         </p> 
6893         <p>
6894           Please refer to the documentation that comes with the
6895           <package>doc-base</package>  package for information and
6896           details. 
6897         </p>
6898       </sect>
6899
6900     </chapt>
6901
6902
6903     <chapt id="files">
6904       <heading>Files</heading>
6905
6906       <sect>
6907         <heading>Binaries</heading>
6908
6909         <p>
6910           Two different packages must not install programs with
6911           different functionality but with the same filenames.  (The
6912           case of two programs having the same functionality but
6913           different implementations is handled via "alternatives" or
6914           the "Conflicts" mechanism.  See <ref id="maintscripts"> and
6915           <ref id="conflicts"> respectively.)  If this case happens,
6916           one of the programs must be renamed.  The maintainers should
6917           report this to the <tt>debian-devel</tt> mailing list and
6918           try to find a consensus about which program will have to be
6919           renamed.  If a consensus cannot be reached, <em>both</em>
6920           programs must be renamed.
6921         </p>
6922
6923         <p>
6924          By default, when a package is being built, any binaries
6925          created should include debugging information, as well as
6926          being compiled with optimization.  You should also turn on
6927          as many reasonable compilation warnings as possible; this
6928          makes life easier for porters, who can then look at build
6929          logs for possible problems.  For the C programming language,
6930          this means the following compilation parameters should be
6931          used:
6932           <example compact="compact">
6933 CC = gcc
6934 CFLAGS = -O2 -g -Wall # sane warning options vary between programs
6935 LDFLAGS = # none
6936 INSTALL = install -s # (or use strip on the files in debian/tmp)
6937           </example>
6938         </p>
6939
6940         <p>
6941           Note that by default all installed binaries should be stripped,
6942           either by using the <tt>-s</tt> flag to
6943           <prgn>install</prgn>, or by calling <prgn>strip</prgn> on
6944           the binaries after they have been copied into
6945           <file>debian/tmp</file> but before the tree is made into a
6946           package.
6947         </p>
6948
6949         <p>
6950           Although binaries in the build tree should be compiled with
6951           debugging information by default, it can often be difficult to
6952           debug programs if they are also subjected to compiler
6953           optimization.  For this reason, it is recommended to support the
6954           standardized environment variable <tt>DEB_BUILD_OPTIONS</tt>
6955           (see <ref id="debianrules-options">).  This variable can contain
6956           several flags to change how a package is compiled and built.
6957         </p>
6958
6959         <p>
6960           It is up to the package maintainer to decide what
6961           compilation options are best for the package.  Certain
6962           binaries (such as computationally-intensive programs) will
6963           function better with certain flags (<tt>-O3</tt>, for
6964           example); feel free to use them.  Please use good judgment
6965           here.  Don't use flags for the sake of it; only use them
6966           if there is good reason to do so.  Feel free to override
6967           the upstream author's ideas about which compilation
6968           options are best: they are often inappropriate for our
6969           environment.
6970         </p>
6971       </sect>
6972
6973
6974       <sect id="libraries">
6975         <heading>Libraries</heading>
6976
6977         <p>
6978           If the package is <strong>architecture: any</strong>, then
6979           the shared library compilation and linking flags must have
6980           <tt>-fPIC</tt>, or the package shall not build on some of
6981           the supported architectures<footnote>
6982             <p>
6983               If you are using GCC, <tt>-fPIC</tt> produces code with
6984               relocatable position independent code, which is required for
6985               most architectures to create a shared library, with i386 and
6986               perhaps some others where non position independent code is
6987               permitted in a shared library.
6988             </p>
6989             <p>
6990               Position independent code may have a performance penalty,
6991               especially on <tt>i386</tt>. However, in most cases the
6992               speed penalty must be measured against the memory wasted on
6993               the few architectures where non position independent code is
6994               even possible.
6995             </p>
6996           </footnote>. Any exception to this rule must be discussed on
6997           the mailing list <em>debian-devel@lists.debian.org</em>, and
6998           a rough consensus obtained.  The reasons for not compiling
6999           with <tt>-fPIC</tt> flag must be recorded in the file
7000           <tt>README.Debian</tt>, and care must be taken to either
7001           restrict the architecture or arrange for <tt>-fPIC</tt> to
7002           be used on architectures where it is required.<footnote>
7003             <p>
7004               Some of the reasons why this might be required is if the
7005               library contains hand crafted assembly code that is not
7006               relocatable, the speed penalty is excessive for compute
7007               intensive libs, and similar reasons.
7008             </p>
7009           </footnote>
7010         </p>
7011         <p>
7012           As to the static libraries, the common case is not to have
7013           relocatable code, since there is no benefit, unless in specific
7014           cases; therefore the static version must not be compiled
7015           with the <tt>-fPIC</tt> flag. Any exception to this rule
7016           should be discussed on the mailing list
7017           <em>debian-devel@lists.debian.org</em>,  and the reasons for
7018           compiling with the <tt>-fPIC</tt> flag must be recorded in
7019           the file <tt>README.Debian</tt>. <footnote>
7020             <p>
7021               Some of the reasons for linking static libraries with
7022               the <tt>-fPIC</tt> flag are if, for example, one needs a
7023               Perl API for a library that is under rapid development,
7024               and has an unstable API, so shared libraries are
7025               pointless at this phase of the library's development. In
7026               that case, since Perl needs a library with relocatable
7027               code, it may make sense to create a static library with
7028               relocatable code. Another reason cited is if you are
7029               distilling various libraries into a common shared
7030               library, like <tt>mklibs</tt> does in the Debian
7031               installer project.
7032             </p>
7033           </footnote>
7034         </p>
7035         <p>
7036           In other words, if both a shared and a static library is
7037           being built, each source unit (<tt>*.c</tt>, for example,
7038           for C files) will need to be compiled twice, for the normal
7039           case. 
7040         </p>
7041         <p>
7042           You must specify the gcc option <tt>-D_REENTRANT</tt>
7043           when building a library (either static or shared) to make
7044           the library compatible with LinuxThreads.
7045         </p>
7046
7047         <p>
7048           Although not enforced by the build tools, shared libraries
7049           must be linked against all libraries that they use symbols from
7050           in the same way that binaries are.  This ensures the correct
7051           functioning of the <qref id="sharedlibs-shlibdeps">shlibs</qref>
7052           system and guarantees that all libraries can be safely opened
7053           with <tt>dlopen()</tt>.  Packagers may wish to use the gcc
7054           option <tt>-Wl,-z,defs</tt> when building a shared library.
7055           Since this option enforces symbol resolution at build time,
7056           a missing library reference will be caught early as a fatal
7057           build error.
7058         </p>
7059
7060         <p>
7061           All installed shared libraries should be stripped with
7062           <example compact="compact">
7063 strip --strip-unneeded <var>your-lib</var>
7064           </example>
7065           (The option <tt>--strip-unneeded</tt> makes
7066           <prgn>strip</prgn> remove only the symbols which aren't
7067           needed for relocation processing.)  Shared libraries can
7068           function perfectly well when stripped, since the symbols for
7069           dynamic linking are in a separate part of the ELF object
7070           file.<footnote>
7071               You might also want to use the options
7072               <tt>--remove-section=.comment</tt> and
7073               <tt>--remove-section=.note</tt> on both shared libraries
7074               and executables, and <tt>--strip-debug</tt> on static
7075               libraries.
7076           </footnote>
7077         </p>
7078
7079         <p>
7080           Note that under some circumstances it may be useful to
7081           install a shared library unstripped, for example when
7082           building a separate package to support debugging.
7083         </p>
7084
7085         <p>
7086           Shared object files (often <file>.so</file> files) that are not
7087           public libraries, that is, they are not meant to be linked
7088           to by third party executables (binaries of other packages),
7089           should be installed in subdirectories of the
7090           <file>/usr/lib</file> directory.  Such files are exempt from the
7091           rules that govern ordinary shared libraries, except that
7092           they must not be installed executable and should be
7093           stripped.<footnote>
7094               A common example are the so-called "plug-ins",
7095               internal shared objects that are dynamically loaded by
7096               programs using <manref name="dlopen" section="3">.
7097           </footnote>
7098         </p>
7099
7100         <p>
7101           An ever increasing number of packages are using
7102           <prgn>libtool</prgn> to do their linking.  The latest GNU
7103           libtools (>= 1.3a) can take advantage of the metadata in the
7104           installed <prgn>libtool</prgn> archive files (<file>*.la</file>
7105           files).  The main advantage of <prgn>libtool</prgn>'s
7106           <file>.la</file> files is that it allows <prgn>libtool</prgn> to
7107           store and subsequently access metadata with respect to the
7108           libraries it builds.  <prgn>libtool</prgn> will search for
7109           those files, which contain a lot of useful information about
7110           a library (such as library dependency information for static
7111           linking).  Also, they're <em>essential</em> for programs
7112           using <tt>libltdl</tt>.<footnote>
7113               Although <prgn>libtool</prgn> is fully capable of
7114               linking against shared libraries which don't have
7115               <tt>.la</tt> files, as it is a mere shell script it can
7116               add considerably to the build time of a
7117               <prgn>libtool</prgn>-using package if that shell script
7118               has to derive all this information from first principles
7119               for each library every time it is linked.  With the
7120               advent of <prgn>libtool</prgn> version 1.4 (and to a
7121               lesser extent <prgn>libtool</prgn> version 1.3), the
7122               <file>.la</file> files also store information about
7123               inter-library dependencies which cannot necessarily be
7124               derived after the <file>.la</file> file is deleted.
7125           </footnote>
7126         </p>
7127
7128         <p>
7129           Packages that use <prgn>libtool</prgn> to create shared
7130           libraries should include the <file>.la</file> files in the
7131           <tt>-dev</tt> package, unless the package relies on
7132           <tt>libtool</tt>'s <tt>libltdl</tt> library, in which case
7133           the <tt>.la</tt> files must go in the run-time library
7134           package.
7135         </p>
7136
7137         <p>
7138           You must make sure that you use only released versions of
7139           shared libraries to build your packages; otherwise other
7140           users will not be able to run your binaries
7141           properly. Producing source packages that depend on
7142           unreleased compilers is also usually a bad
7143           idea.
7144         </p>
7145       </sect>
7146
7147
7148       <sect>
7149         <heading>Shared libraries</heading>
7150         <p>
7151           This section has moved to <ref id="sharedlibs">.
7152         </p>
7153       </sect>
7154
7155
7156       <sect id="scripts">
7157         <heading>Scripts</heading>
7158
7159         <p>
7160           All command scripts, including the package maintainer
7161           scripts inside the package and used by <prgn>dpkg</prgn>,
7162           should have a <tt>#!</tt> line naming the shell to be used
7163           to interpret them.
7164         </p>
7165
7166         <p>
7167           In the case of Perl scripts this should be
7168           <tt>#!/usr/bin/perl</tt>.
7169         </p>
7170
7171         <p>
7172           When scripts are installed into a directory in the system
7173           PATH, the script name should not include an extension such
7174           as <tt>.sh</tt> or <tt>.pl</tt> that denotes the scripting
7175           language currently used to implement it.
7176         </p>
7177         <p>
7178           Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>) other than
7179           <file>init.d</file> scripts should almost certainly start
7180           with <tt>set -e</tt> so that errors are detected.
7181           <file>init.d</file> scripts are something of a special case, due
7182           to how frequently they need to call commands that are allowed to
7183           fail, and it may instead be easier to check the exit status of
7184           commands directly.  See <ref id="writing-init"> for more
7185           information about writing <file>init.d</file> scripts.
7186         </p>
7187         <p>
7188           Every script should use <tt>set -e</tt> or check the exit status
7189           of <em>every</em> command.
7190         </p>
7191         <p>
7192           Scripts may assume that <file>/bin/sh</file> implements the
7193           SUSv3 Shell Command Language<footnote>
7194             Single UNIX Specification, version 3, which is also IEEE
7195             1003.1-2004 (POSIX), and is available on the World Wide Web
7196             from <url id="http://www.unix.org/version3/online.html"
7197                       name="The Open Group"> after free
7198             registration.</footnote>
7199           plus the following additional features not mandated by
7200           SUSv3:<footnote>
7201             These features are in widespread use in the Linux community
7202             and are implemented in all of bash, dash, and ksh, the most
7203             common shells users may wish to use as <file>/bin/sh</file>.
7204           </footnote>
7205           <list>
7206             <item><tt>echo -n</tt>, if implemented as a shell built-in,
7207               must not generate a newline.</item>
7208             <item><tt>test</tt>, if implemented as a shell built-in, must
7209               support <tt>-a</tt> and <tt>-o</tt> as binary logical
7210               operators.</item>
7211             <item><tt>local</tt> to create a scoped variable must be
7212               supported, including listing multiple variables in a single
7213               local command and assigning a value to a variable at the
7214               same time as localizing it.  <tt>local</tt> may or
7215               may not preserve the variable value from an outer scope if
7216               no assignment is present.  Uses such as:
7217 <example compact>
7218 fname () {
7219     local a b c=delta d
7220     # ... use a, b, c, d ...
7221 }
7222 </example>
7223               must be supported and must set the value of <tt>c</tt> to
7224               <tt>delta</tt>.
7225             </item>
7226           </list>
7227           If a shell script requires non-SUSv3 features from the shell
7228           interpreter other than those listed above, the appropriate shell
7229           must be specified in the first line of the script (e.g.,
7230           <tt>#!/bin/bash</tt>) and the package must depend on the package
7231           providing the shell (unless the shell package is marked
7232           "Essential", as in the case of <prgn>bash</prgn>).
7233         </p>
7234
7235         <p>
7236           You may wish to restrict your script to SUSv3 features plus the
7237           above set when possible so that it may use <file>/bin/sh</file>
7238           as its interpreter. If your script works with <prgn>dash</prgn>
7239           (originally called <prgn>ash</prgn>), it probably complies with
7240           the above requirements, but if you are in doubt, use
7241           <file>/bin/bash</file>.
7242         </p>
7243
7244         <p>
7245           Perl scripts should check for errors when making any
7246           system calls, including <tt>open</tt>, <tt>print</tt>,
7247           <tt>close</tt>, <tt>rename</tt> and <tt>system</tt>.
7248         </p>
7249
7250         <p>
7251           <prgn>csh</prgn> and <prgn>tcsh</prgn> should be avoided as
7252           scripting languages.  See <em>Csh Programming Considered
7253           Harmful</em>, one of the <tt>comp.unix.*</tt> FAQs, which
7254           can be found at <url id="http://www.faqs.org/faqs/unix-faq/shell/csh-whynot/">.
7255           If an upstream package comes with <prgn>csh</prgn> scripts
7256           then you must make sure that they start with
7257           <tt>#!/bin/csh</tt> and make your package depend on the
7258           <prgn>c-shell</prgn> virtual package.
7259         </p>
7260
7261         <p>
7262           Any scripts which create files in world-writeable
7263           directories (e.g., in <file>/tmp</file>) must use a
7264           mechanism which will fail atomically if a file with the same
7265           name already exists.
7266         </p>
7267
7268         <p>
7269           The Debian base system provides the <prgn>tempfile</prgn>
7270           and <prgn>mktemp</prgn> utilities for use by scripts for
7271           this purpose.
7272         </p>
7273       </sect>
7274
7275
7276       <sect>
7277         <heading>Symbolic links</heading>
7278
7279         <p>
7280           In general, symbolic links within a top-level directory
7281           should be relative, and symbolic links pointing from one
7282           top-level directory into another should be absolute. (A
7283           top-level directory is a sub-directory of the root
7284           directory <file>/</file>.)
7285         </p>
7286
7287         <p>
7288           In addition, symbolic links should be specified as short as
7289           possible, i.e., link targets like <file>foo/../bar</file> are
7290           deprecated.
7291         </p>
7292
7293         <p>
7294           Note that when creating a relative link using
7295           <prgn>ln</prgn> it is not necessary for the target of the
7296           link to exist relative to the working directory you're
7297           running <prgn>ln</prgn> from, nor is it necessary to change
7298           directory to the directory where the link is to be made.
7299           Simply include the string that should appear as the target
7300           of the link (this will be a pathname relative to the
7301           directory in which the link resides) as the first argument
7302           to <prgn>ln</prgn>.
7303         </p>
7304
7305         <p>
7306           For example, in your <prgn>Makefile</prgn> or
7307           <file>debian/rules</file>, you can do things like:
7308           <example compact="compact">
7309 ln -fs gcc $(prefix)/bin/cc
7310 ln -fs gcc debian/tmp/usr/bin/cc
7311 ln -fs ../sbin/sendmail $(prefix)/bin/runq
7312 ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
7313           </example>
7314         </p>
7315
7316         <p>
7317           A symbolic link pointing to a compressed file should always
7318           have the same file extension as the referenced file. (For
7319           example, if a file <file>foo.gz</file> is referenced by a
7320           symbolic link, the filename of the link has to end with
7321           "<file>.gz</file>" too, as in <file>bar.gz</file>.)
7322         </p>
7323       </sect>
7324
7325       <sect>
7326         <heading>Device files</heading>
7327
7328         <p>
7329           Packages must not include device files or named pipes in the
7330           package file tree.
7331         </p>
7332
7333         <p>
7334           If a package needs any special device files that are not
7335           included in the base system, it must call
7336           <prgn>MAKEDEV</prgn> in the <prgn>postinst</prgn> script,
7337           after notifying the user<footnote>
7338               This notification could be done via a (low-priority)
7339               debconf message, or an echo (printf) statement.
7340           </footnote>.
7341         </p>
7342
7343         <p>
7344           Packages must not remove any device files in the
7345           <prgn>postrm</prgn> or any other script. This is left to the
7346           system administrator.
7347         </p>
7348
7349         <p>
7350           Debian uses the serial devices
7351           <file>/dev/ttyS*</file>. Programs using the old
7352           <file>/dev/cu*</file> devices should be changed to use
7353           <file>/dev/ttyS*</file>.
7354         </p>
7355
7356         <p>
7357           Named pipes needed by the package must be created in
7358           the <prgn>postinst</prgn> script<footnote>
7359             It's better to use <prgn>mkfifo</prgn> rather
7360             than <prgn>mknod</prgn> to create named pipes so that
7361             automated checks for packages incorrectly creating device
7362             files with <prgn>mknod</prgn> won't have false positives.
7363           </footnote> and removed in
7364           the <prgn>prerm</prgn> or <prgn>postrm</prgn> script as
7365           appropriate.
7366         </p>
7367       </sect>
7368
7369       <sect id="config-files">
7370         <heading>Configuration files</heading>
7371
7372         <sect1>
7373           <heading>Definitions</heading>
7374
7375           <p>
7376             <taglist>
7377               <tag>configuration file</tag>
7378               <item>
7379                   A file that affects the operation of a program, or
7380                   provides site- or host-specific information, or
7381                   otherwise customizes the behavior of a program.
7382                   Typically, configuration files are intended to be
7383                   modified by the system administrator (if needed or
7384                   desired) to conform to local policy or to provide
7385                   more useful site-specific behavior.
7386               </item>
7387
7388               <tag><tt>conffile</tt></tag>
7389               <item>
7390                   A file listed in a package's <tt>conffiles</tt>
7391                   file, and is treated specially by <prgn>dpkg</prgn>
7392                   (see <ref id="configdetails">).
7393               </item>
7394             </taglist>
7395           </p>
7396
7397           <p>
7398             The distinction between these two is important; they are
7399             not interchangeable concepts. Almost all
7400             <tt>conffile</tt>s are configuration files, but many
7401             configuration files are not <tt>conffiles</tt>.
7402           </p>
7403
7404           <p>
7405             As noted elsewhere, <file>/etc/init.d</file> scripts,
7406             <file>/etc/default</file> files, scripts installed in
7407             <file>/etc/cron.{hourly,daily,weekly,monthly}</file>, and cron
7408             configuration installed in <file>/etc/cron.d</file> must be
7409             treated as configuration files.  In general, any script that
7410             embeds configuration information is de-facto a configuration
7411             file and should be treated as such.
7412           </p>
7413         </sect1>
7414
7415         <sect1>
7416           <heading>Location</heading>
7417
7418           <p>
7419             Any configuration files created or used by your package
7420             must reside in <file>/etc</file>. If there are several,
7421             consider creating a subdirectory of <file>/etc</file>
7422             named after your package.
7423           </p>
7424
7425           <p>
7426             If your package creates or uses configuration files
7427             outside of <file>/etc</file>, and it is not feasible to modify
7428             the package to use <file>/etc</file> directly, put the files
7429             in <file>/etc</file> and create symbolic links to those files
7430             from the location that the package requires.
7431           </p>
7432         </sect1>
7433
7434         <sect1>
7435           <heading>Behavior</heading>
7436
7437           <p>
7438             Configuration file handling must conform to the following
7439             behavior:
7440             <list compact="compact">
7441               <item>
7442                   local changes must be preserved during a package
7443                   upgrade, and
7444               </item>
7445               <item>
7446                   configuration files must be preserved when the
7447                   package is removed, and only deleted when the
7448                   package is purged.
7449               </item>
7450             </list>
7451           </p>
7452
7453           <p>
7454             The easy way to achieve this behavior is to make the
7455             configuration file a <tt>conffile</tt>. This is
7456             appropriate only if it is possible to distribute a default
7457             version that will work for most installations, although
7458             some system administrators may choose to modify it. This
7459             implies that the default version will be part of the
7460             package distribution, and must not be modified by the
7461             maintainer scripts during installation (or at any other
7462             time).
7463           </p>
7464
7465           <p>
7466             In order to ensure that local changes are preserved
7467             correctly, no package may contain or make hard links to
7468             conffiles.<footnote>
7469                 Rationale: There are two problems with hard links.
7470                 The first is that some editors break the link while
7471                 editing one of the files, so that the two files may
7472                 unwittingly become unlinked and different.  The second
7473                 is that <prgn>dpkg</prgn> might break the hard link
7474                 while upgrading <tt>conffile</tt>s.
7475             </footnote>
7476           </p>
7477
7478           <p>
7479             The other way to do it is via the maintainer scripts.  In
7480             this case, the configuration file must not be listed as a
7481             <tt>conffile</tt> and must not be part of the package
7482             distribution. If the existence of a file is required for
7483             the package to be sensibly configured it is the
7484             responsibility of the package maintainer to provide
7485             maintainer scripts which correctly create, update and
7486             maintain the file and remove it on purge.  (See <ref
7487             id="maintainerscripts"> for more information.)  These
7488             scripts must be idempotent (i.e., must work correctly if
7489             <prgn>dpkg</prgn> needs to re-run them due to errors
7490             during installation or removal), must cope with all the
7491             variety of ways <prgn>dpkg</prgn> can call maintainer
7492             scripts, must not overwrite or otherwise mangle the user's
7493             configuration without asking, must not ask unnecessary
7494             questions (particularly during upgrades), and must
7495             otherwise be good citizens.
7496           </p>
7497
7498           <p>
7499             The scripts are not required to configure every possible
7500             option for the package, but only those necessary to get
7501             the package running on a given system. Ideally the
7502             sysadmin should not have to do any configuration other
7503             than that done (semi-)automatically by the
7504             <prgn>postinst</prgn> script.
7505           </p>
7506
7507           <p>
7508             A common practice is to create a script called
7509             <file><var>package</var>-configure</file> and have the
7510             package's <prgn>postinst</prgn> call it if and only if the
7511             configuration file does not already exist.  In certain
7512             cases it is useful for there to be an example or template
7513             file which the maintainer scripts use.  Such files should
7514             be in <file>/usr/share/<var>package</var></file> or
7515             <file>/usr/lib/<var>package</var></file> (depending on whether
7516             they are architecture-independent or not).  There should
7517             be symbolic links to them from
7518             <file>/usr/share/doc/<var>package</var>/examples</file> if
7519             they are examples, and should be perfectly ordinary
7520             <prgn>dpkg</prgn>-handled files (<em>not</em>
7521             configuration files).
7522           </p>
7523
7524           <p>
7525             These two styles of configuration file handling must
7526             not be mixed, for that way lies madness:
7527             <prgn>dpkg</prgn> will ask about overwriting the file
7528             every time the package is upgraded.
7529           </p>
7530         </sect1>
7531
7532         <sect1>
7533           <heading>Sharing configuration files</heading>
7534
7535           <p>
7536             Packages which specify the same file as a
7537             <tt>conffile</tt> must be tagged as <em>conflicting</em>
7538             with each other.  (This is an instance of the general rule
7539             about not sharing files.  Note that neither alternatives
7540             nor diversions are likely to be appropriate in this case;
7541             in particular, <prgn>dpkg</prgn> does not handle diverted
7542             <tt>conffile</tt>s well.)
7543           </p>
7544
7545           <p>
7546             The maintainer scripts must not alter a <tt>conffile</tt>
7547             of <em>any</em> package, including the one the scripts
7548             belong to.
7549           </p>
7550
7551           <p>
7552             If two or more packages use the same configuration file
7553             and it is reasonable for both to be installed at the same
7554             time, one of these packages must be defined as
7555             <em>owner</em> of the configuration file, i.e., it will be
7556             the package which handles that file as a configuration
7557             file.  Other packages that use the configuration file must
7558             depend on the owning package if they require the
7559             configuration file to operate. If the other package will
7560             use the configuration file if present, but is capable of
7561             operating without it, no dependency need be declared.
7562           </p>
7563
7564           <p>
7565             If it is desirable for two or more related packages to
7566             share a configuration file <em>and</em> for all of the
7567             related packages to be able to modify that configuration
7568             file, then the following should be done:
7569             <enumlist compact="compact">
7570               <item>
7571                   One of the related packages (the "owning" package)
7572                   will manage the configuration file with maintainer
7573                   scripts as described in the previous section.
7574               </item>
7575               <item>
7576                   The owning package should also provide a program
7577                   that the other packages may use to modify the
7578                   configuration file.
7579               </item>
7580               <item>
7581                   The related packages must use the provided program
7582                   to make any desired modifications to the
7583                   configuration file.  They should either depend on
7584                   the core package to guarantee that the configuration
7585                   modifier program is available or accept gracefully
7586                   that they cannot modify the configuration file if it
7587                   is not.  (This is in addition to the fact that the
7588                   configuration file may not even be present in the
7589                   latter scenario.)
7590               </item>
7591             </enumlist>
7592           </p>
7593
7594           <p>
7595             Sometimes it's appropriate to create a new package which
7596             provides the basic infrastructure for the other packages
7597             and which manages the shared configuration files.  (The
7598             <tt>sgml-base</tt> package is a good example.)
7599           </p>
7600         </sect1>
7601
7602         <sect1>
7603           <heading>User configuration files ("dotfiles")</heading>
7604
7605           <p>
7606             The files in <file>/etc/skel</file> will automatically be
7607             copied into new user accounts by <prgn>adduser</prgn>.
7608             No other program should reference the files in
7609             <file>/etc/skel</file>.
7610           </p>
7611
7612           <p>
7613             Therefore, if a program needs a dotfile to exist in
7614             advance in <file>$HOME</file> to work sensibly, that dotfile
7615             should be installed in <file>/etc/skel</file> and treated as a
7616             configuration file.
7617           </p>
7618
7619           <p>
7620             However, programs that require dotfiles in order to
7621             operate sensibly are a bad thing, unless they do create
7622             the dotfiles themselves automatically.
7623           </p>
7624
7625           <p>
7626             Furthermore, programs should be configured by the Debian
7627             default installation to behave as closely to the upstream
7628             default behavior as possible.
7629           </p>
7630
7631           <p>
7632             Therefore, if a program in a Debian package needs to be
7633             configured in some way in order to operate sensibly, that
7634             should be done using a site-wide configuration file placed
7635             in <file>/etc</file>.  Only if the program doesn't support a
7636             site-wide default configuration and the package maintainer
7637             doesn't have time to add it may a default per-user file be
7638             placed in <file>/etc/skel</file>.
7639           </p>
7640
7641           <p>
7642             <file>/etc/skel</file> should be as empty as we can make it.
7643             This is particularly true because there is no easy (or
7644             necessarily desirable) mechanism for ensuring that the
7645             appropriate dotfiles are copied into the accounts of
7646             existing users when a package is installed.
7647           </p>
7648         </sect1>
7649       </sect>
7650
7651       <sect>
7652         <heading>Log files</heading>
7653         <p>
7654           Log files should usually be named
7655           <file>/var/log/<var>package</var>.log</file>.  If you have many
7656           log files, or need a separate directory for permission
7657           reasons (<file>/var/log</file> is writable only by
7658           <file>root</file>), you should usually create a directory named
7659           <file>/var/log/<var>package</var></file> and place your log
7660           files there.
7661         </p>
7662
7663         <p>
7664           Log files must be rotated occasionally so that they don't
7665           grow indefinitely; the best way to do this is to drop a log
7666           rotation configuration file into the directory
7667           <file>/etc/logrotate.d</file> and use the facilities provided by
7668           logrotate.<footnote>
7669             <p>
7670               The traditional approach to log files has been to set up
7671               <em>ad hoc</em> log rotation schemes using simple shell
7672               scripts and cron.  While this approach is highly
7673               customizable, it requires quite a lot of sysadmin work.
7674               Even though the original Debian system helped a little
7675               by automatically installing a system which can be used
7676               as a template, this was deemed not enough.
7677             </p>
7678
7679             <p>
7680               The use of <prgn>logrotate</prgn>, a program developed
7681               by Red Hat, is better, as it centralizes log management.
7682               It has both a configuration file
7683               (<file>/etc/logrotate.conf</file>) and a directory where
7684               packages can drop their individual log rotation
7685               configurations (<file>/etc/logrotate.d</file>).
7686             </p>
7687           </footnote>
7688           Here is a good example for a logrotate config
7689           file (for more information see <manref name="logrotate"
7690             section="8">):
7691           <example compact="compact">
7692 /var/log/foo/*.log {
7693 rotate 12
7694 weekly
7695 compress
7696 postrotate
7697 /etc/init.d/foo force-reload
7698 endscript
7699 }
7700           </example>
7701           This rotates all files under <file>/var/log/foo</file>, saves 12
7702           compressed generations, and forces the daemon to reload its
7703           configuration information after the log rotation.
7704         </p>
7705
7706         <p>
7707           Log files should be removed when the package is
7708           purged (but not when it is only removed).  This should be
7709           done by the <prgn>postrm</prgn> script when it is called
7710           with the argument <tt>purge</tt> (see <ref
7711           id="removedetails">).
7712         </p>
7713       </sect>
7714
7715       <sect>
7716         <heading>Permissions and owners</heading>
7717
7718         <p>
7719           The rules in this section are guidelines for general use.
7720           If necessary you may deviate from the details below.
7721           However, if you do so you must make sure that what is done
7722           is secure and you should try to be as consistent as possible
7723           with the rest of the system.  You should probably also
7724           discuss it on <prgn>debian-devel</prgn> first.
7725         </p>
7726
7727         <p>
7728           Files should be owned by <tt>root:root</tt>, and made
7729           writable only by the owner and universally readable (and
7730           executable, if appropriate), that is mode 644 or 755.
7731         </p>
7732
7733         <p>
7734           Directories should be mode 755 or (for group-writability)
7735           mode 2775.  The ownership of the directory should be
7736           consistent with its mode: if a directory is mode 2775, it
7737           should be owned by the group that needs write access to
7738           it.<footnote>
7739             <p>
7740               When a package is upgraded, and the owner or permissions
7741               of a file included in the package has changed, dpkg
7742               arranges for the ownership and permissions to be
7743               correctly set upon installation. However, this does not
7744               extend to directories; the permissions and ownership of
7745               directories already on the system does not change on
7746               install or upgrade of packages.  This makes sense, since
7747               otherwise common directories like <tt>/usr</tt> would
7748               always be in flux.  To correctly change permissions of a
7749               directory the package owns, explicit action is required,
7750               usually in the <tt>postinst</tt> script. Care must be
7751               taken to handle downgrades as well, in that case.
7752             </p>
7753           </footnote>
7754         </p>
7755
7756
7757         <p>
7758           Setuid and setgid executables should be mode 4755 or 2755
7759           respectively, and owned by the appropriate user or group.
7760           They should not be made unreadable (modes like 4711 or
7761           2711 or even 4111); doing so achieves no extra security,
7762           because anyone can find the binary in the freely available
7763           Debian package; it is merely inconvenient.  For the same
7764           reason you should not restrict read or execute permissions
7765           on non-set-id executables.
7766         </p>
7767
7768         <p>
7769           Some setuid programs need to be restricted to particular
7770           sets of users, using file permissions.  In this case they
7771           should be owned by the uid to which they are set-id, and by
7772           the group which should be allowed to execute them.  They
7773           should have mode 4754; again there is no point in making
7774           them unreadable to those users who must not be allowed to
7775           execute them.
7776         </p>
7777
7778         <p>
7779           It is possible to arrange that the system administrator can
7780           reconfigure the package to correspond to their local
7781           security policy by changing the permissions on a binary:
7782           they can do this by using <prgn>dpkg-statoverride</prgn>, as
7783           described below.<footnote>
7784               Ordinary files installed by <prgn>dpkg</prgn> (as
7785               opposed to <tt>conffile</tt>s and other similar objects)
7786               normally have their permissions reset to the distributed
7787               permissions when the package is reinstalled.  However,
7788               the use of <prgn>dpkg-statoverride</prgn> overrides this
7789               default behavior.  If you use this method, you should
7790               remember to describe <prgn>dpkg-statoverride</prgn> in
7791               the package documentation; being a relatively new
7792               addition to Debian, it is probably not yet well-known.
7793           </footnote>
7794           Another method you should consider is to create a group for
7795           people allowed to use the program(s) and make any setuid
7796           executables executable only by that group.
7797         </p>
7798
7799         <p>
7800           If you need to create a new user or group for your package
7801           there are two possibilities.  Firstly, you may need to
7802           make some files in the binary package be owned by this
7803           user or group, or you may need to compile the user or
7804           group id (rather than just the name) into the binary
7805           (though this latter should be avoided if possible, as in
7806           this case you need a statically allocated id).</p>
7807
7808         <p>
7809           If you need a statically allocated id, you must ask for a
7810           user or group id from the <tt>base-passwd</tt> maintainer,
7811           and must not release the package until you have been
7812           allocated one.  Once you have been allocated one you must
7813           either make the package depend on a version of the
7814           <tt>base-passwd</tt> package with the id present in
7815           <file>/etc/passwd</file> or <file>/etc/group</file>, or arrange for
7816           your package to create the user or group itself with the
7817           correct id (using <tt>adduser</tt>) in its
7818           <prgn>preinst</prgn> or <prgn>postinst</prgn>.  (Doing it in
7819           the <prgn>postinst</prgn> is to be preferred if it is
7820           possible, otherwise a pre-dependency will be needed on the
7821           <tt>adduser</tt> package.)
7822         </p>
7823
7824         <p>
7825           On the other hand, the program might be able to determine
7826           the uid or gid from the user or group name at runtime, so
7827           that a dynamically allocated id can be used.  In this case
7828           you should choose an appropriate user or group name,
7829           discussing this on <prgn>debian-devel</prgn> and checking
7830           with the <package/base-passwd/ maintainer that it is unique and that
7831           they do not wish you to use a statically allocated id
7832           instead.  When this has been checked you must arrange for
7833           your package to create the user or group if necessary using
7834           <prgn>adduser</prgn> in the <prgn>preinst</prgn> or
7835           <prgn>postinst</prgn> script (again, the latter is to be
7836           preferred if it is possible).
7837         </p>
7838
7839         <p>
7840           Note that changing the numeric value of an id associated
7841           with a name is very difficult, and involves searching the
7842           file system for all appropriate files.  You need to think
7843           carefully whether a static or dynamic id is required, since
7844           changing your mind later will cause problems.
7845         </p>
7846
7847         <sect1><heading>The use of <prgn>dpkg-statoverride</prgn></heading>
7848           <p>
7849             This section is not intended as policy, but as a
7850             description of the use of <prgn>dpkg-statoverride</prgn>.
7851           </p>
7852
7853           <p>
7854             If a system administrator wishes to have a file (or
7855             directory or other such thing) installed with owner and
7856             permissions different from those in the distributed Debian
7857             package, they can use the <prgn>dpkg-statoverride</prgn>
7858             program to instruct <prgn>dpkg</prgn> to use the different
7859             settings every time the file is installed.  Thus the
7860             package maintainer should distribute the files with their
7861             normal permissions, and leave it for the system
7862             administrator to make any desired changes.  For example, a
7863             daemon which is normally required to be setuid root, but
7864             in certain situations could be used without being setuid,
7865             should be installed setuid in the <tt>.deb</tt>.  Then the
7866             local system administrator can change this if they wish.
7867             If there are two standard ways of doing it, the package
7868             maintainer can use <tt>debconf</tt> to find out the
7869             preference, and call <prgn>dpkg-statoverride</prgn> in the
7870             maintainer script if necessary to accommodate the system
7871             administrator's choice. Care must be taken during
7872             upgrades to not override an existing setting.
7873           </p>
7874
7875           <p>
7876             Given the above, <prgn>dpkg-statoverride</prgn> is
7877             essentially a tool for system administrators and would not
7878             normally be needed in the maintainer scripts.  There is
7879             one type of situation, though, where calls to
7880             <prgn>dpkg-statoverride</prgn> would be needed in the
7881             maintainer scripts, and that involves packages which use
7882             dynamically allocated user or group ids.  In such a
7883             situation, something like the following idiom can be very
7884             helpful in the package's <prgn>postinst</prgn>, where
7885             <tt>sysuser</tt> is a dynamically allocated id:
7886             <example>
7887 for i in /usr/bin/foo /usr/sbin/bar
7888 do
7889   # only do something when no setting exists
7890   if ! dpkg-statoverride --list $i >/dev/null 2>&1
7891   then
7892     #include: debconf processing, question about foo and bar
7893     if [ "$RET" = "true" ] ; then
7894       dpkg-statoverride --update --add sysuser root 4755 $i
7895     fi
7896   fi
7897 done
7898             </example>
7899             The corresponding code to remove the override when the package
7900             is purged would be:
7901             <example>
7902 for i in /usr/bin/foo /usr/sbin/bar
7903 do
7904   if dpkg-statoverride --list $i >/dev/null 2>&1
7905   then
7906     dpkg-statoverride --remove $i
7907   fi
7908 done
7909             </example>
7910           </p>
7911         </sect1>
7912       </sect>
7913     </chapt>
7914
7915
7916     <chapt id="customized-programs">
7917       <heading>Customized programs</heading>
7918
7919       <sect id="arch-spec">
7920         <heading>Architecture specification strings</heading>
7921
7922         <p>
7923           If a program needs to specify an <em>architecture specification
7924             string</em> in some place, it should select one of the
7925           strings provided by <tt>dpkg-architecture -L</tt>. The
7926           strings are in the format
7927           <tt><var>os</var>-<var>arch</var></tt>, though the OS part
7928           is sometimes elided, as when the OS is Linux.<footnote>
7929             <p>Currently, the strings are:
7930               i386 ia64 alpha amd64 armeb arm hppa m32r m68k mips
7931               mipsel powerpc ppc64 s390 s390x sh3 sh3eb sh4 sh4eb
7932               sparc darwin-i386 darwin-ia64 darwin-alpha darwin-amd64
7933               darwin-armeb darwin-arm darwin-hppa darwin-m32r
7934               darwin-m68k darwin-mips darwin-mipsel darwin-powerpc
7935               darwin-ppc64 darwin-s390 darwin-s390x darwin-sh3
7936               darwin-sh3eb darwin-sh4 darwin-sh4eb darwin-sparc
7937               freebsd-i386 freebsd-ia64 freebsd-alpha freebsd-amd64
7938               freebsd-armeb freebsd-arm freebsd-hppa freebsd-m32r
7939               freebsd-m68k freebsd-mips freebsd-mipsel freebsd-powerpc
7940               freebsd-ppc64 freebsd-s390 freebsd-s390x freebsd-sh3
7941               freebsd-sh3eb freebsd-sh4 freebsd-sh4eb freebsd-sparc
7942               kfreebsd-i386 kfreebsd-ia64 kfreebsd-alpha
7943               kfreebsd-amd64 kfreebsd-armeb kfreebsd-arm kfreebsd-hppa
7944               kfreebsd-m32r kfreebsd-m68k kfreebsd-mips
7945               kfreebsd-mipsel kfreebsd-powerpc kfreebsd-ppc64
7946               kfreebsd-s390 kfreebsd-s390x kfreebsd-sh3 kfreebsd-sh3eb
7947               kfreebsd-sh4 kfreebsd-sh4eb kfreebsd-sparc knetbsd-i386
7948               knetbsd-ia64 knetbsd-alpha knetbsd-amd64 knetbsd-armeb
7949               knetbsd-arm knetbsd-hppa knetbsd-m32r knetbsd-m68k
7950               knetbsd-mips knetbsd-mipsel knetbsd-powerpc
7951               knetbsd-ppc64 knetbsd-s390 knetbsd-s390x knetbsd-sh3
7952               knetbsd-sh3eb knetbsd-sh4 knetbsd-sh4eb knetbsd-sparc
7953               netbsd-i386 netbsd-ia64 netbsd-alpha netbsd-amd64
7954               netbsd-armeb netbsd-arm netbsd-hppa netbsd-m32r
7955               netbsd-m68k netbsd-mips netbsd-mipsel netbsd-powerpc
7956               netbsd-ppc64 netbsd-s390 netbsd-s390x netbsd-sh3
7957               netbsd-sh3eb netbsd-sh4 netbsd-sh4eb netbsd-sparc
7958               openbsd-i386 openbsd-ia64 openbsd-alpha openbsd-amd64
7959               openbsd-armeb openbsd-arm openbsd-hppa openbsd-m32r
7960               openbsd-m68k openbsd-mips openbsd-mipsel openbsd-powerpc
7961               openbsd-ppc64 openbsd-s390 openbsd-s390x openbsd-sh3
7962               openbsd-sh3eb openbsd-sh4 openbsd-sh4eb openbsd-sparc
7963               hurd-i386 hurd-ia64 hurd-alpha hurd-amd64 hurd-armeb
7964               hurd-arm hurd-hppa hurd-m32r hurd-m68k hurd-mips
7965               hurd-mipsel hurd-powerpc hurd-ppc64 hurd-s390 hurd-s390x
7966               hurd-sh3 hurd-sh3eb hurd-sh4 hurd-sh4eb hurd-sparc
7967             </p>
7968           </footnote>
7969         </p>
7970
7971         <p>
7972           Note that we don't want to use
7973           <tt><var>arch</var>-debian-linux</tt> to apply to the rule
7974           <tt><var>architecture</var>-<var>vendor</var>-<var>os</var></tt>
7975           since this would make our programs incompatible with other
7976           Linux distributions.  We also don't use something like
7977           <tt><var>arch</var>-unknown-linux</tt>, since the
7978           <tt>unknown</tt> does not look very good.
7979         </p>
7980       </sect>
7981
7982       <sect>
7983         <heading>Daemons</heading>
7984
7985         <p>
7986           The configuration files <file>/etc/services</file>,
7987           <file>/etc/protocols</file>, and <file>/etc/rpc</file> are managed
7988           by the <prgn>netbase</prgn> package and must not be modified
7989           by other packages.
7990         </p>
7991
7992         <p>
7993           If a package requires a new entry in one of these files, the
7994           maintainer should get in contact with the
7995           <prgn>netbase</prgn> maintainer, who will add the entries
7996           and release a new version of the <prgn>netbase</prgn>
7997           package.
7998         </p>
7999
8000         <p>
8001           The configuration file <file>/etc/inetd.conf</file> must not be
8002           modified by the package's scripts except via the
8003           <prgn>update-inetd</prgn> script or the
8004           <file>DebianNet.pm</file> Perl module.  See their documentation
8005           for details on how to add entries.
8006         </p>
8007
8008         <p>
8009           If a package wants to install an example entry into
8010           <file>/etc/inetd.conf</file>, the entry must be preceded with
8011           exactly one hash character (<tt>#</tt>). Such lines are
8012           treated as "commented out by user" by the
8013           <prgn>update-inetd</prgn> script and are not changed or
8014           activated during package updates.
8015         </p>
8016       </sect>
8017
8018       <sect>
8019         <heading>Using pseudo-ttys and modifying wtmp, utmp and
8020         lastlog</heading>
8021
8022         <p>
8023           Some programs need to create pseudo-ttys. This should be done
8024           using Unix98 ptys if the C library supports it. The resulting
8025           program must not be installed setuid root, unless that
8026           is required for other functionality.
8027         </p>
8028
8029         <p>
8030           The files <file>/var/run/utmp</file>, <file>/var/log/wtmp</file> and
8031           <file>/var/log/lastlog</file> must be installed writable by
8032           group <tt>utmp</tt>.  Programs which need to modify those
8033           files must be installed setgid <tt>utmp</tt>.
8034         </p>
8035       </sect>
8036
8037       <sect>
8038         <heading>Editors and pagers</heading>
8039
8040         <p>
8041           Some programs have the ability to launch an editor or pager
8042           program to edit or display a text document.  Since there are
8043           lots of different editors and pagers available in the Debian
8044           distribution, the system administrator and each user should
8045           have the possibility to choose their preferred editor and
8046           pager.
8047         </p>
8048
8049         <p>
8050           In addition, every program should choose a good default
8051           editor/pager if none is selected by the user or system
8052           administrator.
8053         </p>
8054
8055         <p>
8056           Thus, every program that launches an editor or pager must
8057           use the EDITOR or PAGER environment variable to determine
8058           the editor or pager the user wishes to use.  If these
8059           variables are not set, the programs <file>/usr/bin/editor</file>
8060           and <file>/usr/bin/pager</file> should be used, respectively.
8061         </p>
8062
8063         <p>
8064           These two files are managed through the <prgn>dpkg</prgn>
8065           "alternatives" mechanism.  Thus every package providing an
8066           editor or pager must call the
8067           <prgn>update-alternatives</prgn> script to register these
8068           programs.
8069         </p>
8070
8071         <p>
8072           If it is very hard to adapt a program to make use of the
8073           EDITOR or PAGER variables, that program may be configured to
8074           use <file>/usr/bin/sensible-editor</file> and
8075           <file>/usr/bin/sensible-pager</file> as the editor or pager
8076           program respectively.  These are two scripts provided in the
8077           <package>sensible-utils</package> package that check the EDITOR
8078           and PAGER variables and launch the appropriate program, and fall
8079           back to <file>/usr/bin/editor</file>
8080           and <file>/usr/bin/pager</file> if the variable is not set.
8081         </p>
8082
8083         <p>
8084           A program may also use the VISUAL environment variable to
8085           determine the user's choice of editor.  If it exists, it
8086           should take precedence over EDITOR.  This is in fact what
8087           <file>/usr/bin/sensible-editor</file> does.
8088         </p>
8089
8090         <p>
8091           It is not required for a package to depend on
8092           <tt>editor</tt> and <tt>pager</tt>, nor is it required for a
8093           package to provide such virtual packages.<footnote>
8094               The Debian base system already provides an editor and a
8095               pager program.
8096           </footnote>
8097         </p>
8098       </sect>
8099
8100       <sect id="web-appl">
8101         <heading>Web servers and applications</heading>
8102
8103         <p>
8104           This section describes the locations and URLs that should
8105           be used by all web servers and web applications in the
8106           Debian system.
8107         </p>
8108
8109         <p>
8110           <enumlist>
8111             <item>
8112                 Cgi-bin executable files are installed in the
8113                 directory
8114                 <example compact="compact">
8115 /usr/lib/cgi-bin/<var>cgi-bin-name</var>
8116                 </example>
8117                 and should be referred to as
8118                 <example compact="compact">
8119 http://localhost/cgi-bin/<var>cgi-bin-name</var>
8120                 </example>
8121
8122             </item>
8123
8124             <item>
8125               <p>Access to HTML documents</p>
8126
8127               <p>
8128                 HTML documents for a package are stored in
8129                 <file>/usr/share/doc/<var>package</var></file>
8130                 and can be referred to as
8131                 <example compact="compact">
8132 http://localhost/doc/<var>package</var>/<var>filename</var>
8133                 </example>
8134               </p>
8135
8136               <p>
8137                 The web server should restrict access to the document
8138                 tree so that only clients on the same host can read
8139                 the documents. If the web server does not support such
8140                 access controls, then it should not provide access at
8141                 all, or ask about providing access during installation.
8142               </p>
8143             </item>
8144
8145             <item>
8146               <p>Access to images</p>
8147               <p>
8148                 It is recommended that images for a package be stored
8149                 in <tt>/usr/share/images/<var>package</var></tt> and
8150                 may be referred to through an alias <tt>/images/</tt>
8151                 as
8152                 <example>
8153                   http://localhost/images/&lt;package&gt;/&lt;filename&gt;     
8154                 </example>
8155                 
8156               </p>
8157             </item>
8158
8159             <item>
8160               <p>Web Document Root</p>
8161
8162               <p>
8163                 Web Applications should try to avoid storing files in
8164                 the Web Document Root.  Instead they should use the
8165                 /usr/share/doc/<var>package</var> directory for
8166                 documents and register the Web Application via the
8167                 <package>doc-base</package> package.  If access to the
8168                 web document root is unavoidable then use
8169                 <example compact="compact">
8170 /var/www
8171                 </example>
8172                 as the Document Root.  This might be just a symbolic
8173                 link to the location where the system administrator
8174                 has put the real document root.
8175               </p>
8176             </item>
8177             <item><p>Providing httpd and/or httpd-cgi</p>
8178               <p>
8179                 All web servers should provide the virtual package
8180                 <tt>httpd</tt>. If a web server has CGI support it should
8181                 provide <tt>httpd-cgi</tt> additionally.
8182               </p>
8183               <p>
8184                 All web applications which do not contain CGI scripts should
8185                 depend on <tt>httpd</tt>, all those web applications which
8186                 <tt>do</tt> contain CGI scripts, should depend on
8187                 <tt>httpd-cgi</tt>.
8188               </p>
8189             </item>
8190           </enumlist>
8191         </p>
8192       </sect>
8193
8194       <sect id="mail-transport-agents">
8195         <heading>Mail transport, delivery and user agents</heading>
8196
8197         <p>
8198           Debian packages which process electronic mail, whether mail
8199           user agents (MUAs) or mail transport agents (MTAs), must
8200           ensure that they are compatible with the configuration
8201           decisions below.  Failure to do this may result in lost
8202           mail, broken <tt>From:</tt> lines, and other serious brain
8203           damage!
8204         </p>
8205
8206         <p>
8207           The mail spool is <file>/var/mail</file> and the interface to
8208           send a mail message is <file>/usr/sbin/sendmail</file> (as per
8209           the FHS).  On older systems, the mail spool may be
8210           physically located in <file>/var/spool/mail</file>, but all
8211           access to the mail spool should be via the
8212           <file>/var/mail</file> symlink.  The mail spool is part of the
8213           base system and not part of the MTA package.
8214         </p>
8215
8216         <p>
8217           All Debian MUAs, MTAs, MDAs and other mailbox accessing
8218           programs (such as IMAP daemons) must lock the mailbox in an
8219           NFS-safe way. This means that <tt>fcntl()</tt> locking must
8220           be combined with dot locking.  To avoid deadlocks, a program
8221           should use <tt>fcntl()</tt> first and dot locking after
8222           this, or alternatively implement the two locking methods in
8223           a non blocking way<footnote>
8224               If it is not possible to establish both locks, the
8225               system shouldn't wait for the second lock to be
8226               established, but remove the first lock, wait a (random)
8227               time, and start over locking again.
8228           </footnote>. Using the functions <tt>maillock</tt> and
8229           <tt>mailunlock</tt> provided by the
8230           <tt>liblockfile*</tt><footnote>
8231               You will need to depend on <tt>liblockfile1 (&gt;&gt;1.01)</tt>
8232               to use these functions.
8233           </footnote> packages is the recommended way to realize this.
8234         </p>
8235
8236         <p>
8237           Mailboxes are generally either mode 600 and owned by
8238           <var>user</var> or mode 660 and owned by
8239           <tt><var>user</var>:mail</tt><footnote>
8240             There are two traditional permission schemes for mail spools:
8241             mode 600 with all mail delivery done by processes running as
8242             the destination user, or mode 660 and owned by group mail with
8243             mail delivery done by a process running as a system user in
8244             group mail.  Historically, Debian required mode 660 mail
8245             spools to enable the latter model, but that model has become
8246             increasingly uncommon and the principle of least privilege
8247             indicates that mail systems that use the first model should
8248             use permissions of 600.  If delivery to programs is permitted,
8249             it's easier to keep the mail system secure if the delivery
8250             agent runs as the destination user.  Debian Policy therefore
8251             permits either scheme.
8252           </footnote>. The local system administrator may choose a
8253           different permission scheme; packages should not make
8254           assumptions about the permission and ownership of mailboxes
8255           unless required (such as when creating a new mailbox).  A MUA
8256           may remove a mailbox (unless it has nonstandard permissions) in
8257           which case the MTA or another MUA must recreate it if needed.
8258         </p>
8259
8260         <p>
8261           The mail spool is 2775 <tt>root:mail</tt>, and MUAs should
8262           be setgid mail to do the locking mentioned above (and
8263           must obviously avoid accessing other users' mailboxes
8264           using this privilege).</p>
8265
8266         <p>
8267           <file>/etc/aliases</file> is the source file for the system mail
8268           aliases (e.g., postmaster, usenet, etc.), it is the one
8269           which the sysadmin and <prgn>postinst</prgn> scripts may
8270           edit.  After <file>/etc/aliases</file> is edited the program or
8271           human editing it must call <prgn>newaliases</prgn>.  All MTA
8272           packages must come with a <prgn>newaliases</prgn> program,
8273           even if it does nothing, but older MTA packages did not do
8274           this so programs should not fail if <prgn>newaliases</prgn>
8275           cannot be found.  Note that because of this, all MTA
8276           packages must have <tt>Provides</tt>, <tt>Conflicts</tt> and
8277           <tt>Replaces: mail-transport-agent</tt> control file
8278           fields.
8279         </p>
8280
8281         <p>
8282           The convention of writing <tt>forward to
8283             <var>address</var></tt> in the mailbox itself is not
8284           supported.  Use a <tt>.forward</tt> file instead.</p>
8285
8286         <p>
8287           The <prgn>rmail</prgn> program used by UUCP
8288           for incoming mail should be  <file>/usr/sbin/rmail</file>.
8289           Likewise, <prgn>rsmtp</prgn>, for receiving
8290           batch-SMTP-over-UUCP, should be <file>/usr/sbin/rsmtp</file> if it
8291           is supported.</p>
8292
8293         <p>
8294           If your package needs to know what hostname to use on (for
8295           example) outgoing news and mail messages which are generated
8296           locally, you should use the file <file>/etc/mailname</file>.  It
8297           will contain the portion after the username and <tt>@</tt>
8298           (at) sign for email addresses of users on the machine
8299           (followed by a newline).
8300         </p>
8301
8302         <p>
8303           Such a package should check for the existence of this file
8304           when it is being configured.  If it exists, it should be
8305           used without comment, although an MTA's configuration script
8306           may wish to prompt the user even if it finds that this file
8307           exists.  If the file does not exist, the package should
8308           prompt the user for the value (preferably using
8309           <prgn>debconf</prgn>) and store it in <file>/etc/mailname</file>
8310           as well as using it in the package's configuration.  The
8311           prompt should make it clear that the name will not just be
8312           used by that package.  For example, in this situation the
8313           <tt>inn</tt> package could say something like:
8314           <example compact="compact">
8315 Please enter the "mail name" of your system.  This is the
8316 hostname portion of the address to be shown on outgoing
8317 news and mail messages.  The default is
8318 <var>syshostname</var>, your system's host name.  Mail
8319 name ["<var>syshostname</var>"]:
8320           </example>
8321           where <var>syshostname</var> is the output of <tt>hostname
8322             --fqdn</tt>.
8323         </p>
8324       </sect>
8325
8326       <sect>
8327         <heading>News system configuration</heading>
8328
8329         <p>
8330           All the configuration files related to the NNTP (news)
8331           servers and clients should be located under
8332           <file>/etc/news</file>.</p>
8333
8334         <p>
8335           There are some configuration issues that apply to a number
8336           of news clients and server packages on the machine. These
8337           are:
8338
8339           <taglist>
8340             <tag><file>/etc/news/organization</file></tag>
8341             <item>
8342                 A string which should appear as the
8343                 organization header for all messages posted
8344                 by NNTP clients on the machine
8345             </item>
8346
8347             <tag><file>/etc/news/server</file></tag>
8348             <item>
8349                 Contains the FQDN of the upstream NNTP
8350                 server, or localhost if the local machine is
8351                 an NNTP server.
8352             </item>
8353           </taglist>
8354
8355           Other global files may be added as required for cross-package news
8356           configuration.
8357         </p>
8358       </sect>
8359
8360
8361       <sect>
8362         <heading>Programs for the X Window System</heading>
8363
8364         <sect1>
8365           <heading>Providing X support and package priorities</heading>
8366
8367           <p>
8368             Programs that can be configured with support for the X
8369             Window System must be configured to do so and must declare
8370             any package dependencies necessary to satisfy their
8371             runtime requirements when using the X Window System.  If
8372             such a package is of higher priority than the X packages
8373             on which it depends, it is required that either the
8374             X-specific components be split into a separate package, or
8375             that an alternative version of the package, which includes
8376             X support, be provided, or that the package's priority be
8377             lowered.
8378           </p>
8379         </sect1>
8380
8381         <sect1>
8382           <heading>Packages providing an X server</heading>
8383
8384           <p>
8385             Packages that provide an X server that, directly or
8386             indirectly, communicates with real input and display
8387             hardware should declare in their control data that they
8388             provide the virtual package <tt>xserver</tt>.<footnote>
8389                 This implements current practice, and provides an
8390                 actual policy for usage of the <tt>xserver</tt>
8391                 virtual package which appears in the virtual packages
8392                 list.  In a nutshell, X servers that interface
8393                 directly with the display and input hardware or via
8394                 another subsystem (e.g., GGI) should provide
8395                 <tt>xserver</tt>.  Things like <tt>Xvfb</tt>,
8396                 <tt>Xnest</tt>, and <tt>Xprt</tt> should not.
8397             </footnote>
8398           </p>
8399         </sect1>
8400
8401         <sect1>
8402           <heading>Packages providing a terminal emulator</heading>
8403
8404           <p>
8405             Packages that provide a terminal emulator for the X Window
8406             System which meet the criteria listed below should declare
8407             in their control data that they provide the virtual
8408             package <tt>x-terminal-emulator</tt>.  They should also
8409             register themselves as an alternative for
8410             <file>/usr/bin/x-terminal-emulator</file>, with a priority of
8411             20.
8412           </p>
8413
8414           <p>
8415             To be an <tt>x-terminal-emulator</tt>, a program must:
8416             <list compact="compact">
8417               <item>
8418                   Be able to emulate a DEC VT100 terminal, or a
8419                   compatible terminal.
8420               </item>
8421
8422               <item>
8423                   Support the command-line option <tt>-e
8424                     <var>command</var></tt>, which creates a new
8425                   terminal window<footnote>
8426                       "New terminal window" does not necessarily mean
8427                       a new top-level X window directly parented by
8428                       the window manager; it could, if the terminal
8429                       emulator application were so coded, be a new
8430                       "view" in a multiple-document interface (MDI).
8431                   </footnote>
8432                   and runs the specified <var>command</var>,
8433                   interpreting the entirety of the rest of the command
8434                   line as a command to pass straight to exec, in the
8435                   manner that <tt>xterm</tt> does.
8436               </item>
8437
8438               <item>
8439                   Support the command-line option <tt>-T
8440                     <var>title</var></tt>, which creates a new terminal
8441                   window with the window title <var>title</var>.
8442               </item>
8443             </list>
8444           </p>
8445         </sect1>
8446
8447         <sect1>
8448           <heading>Packages providing a window manager</heading>
8449
8450           <p>
8451             Packages that provide a window manager should declare in
8452             their control data that they provide the virtual package
8453             <tt>x-window-manager</tt>.  They should also register
8454             themselves as an alternative for
8455             <file>/usr/bin/x-window-manager</file>, with a priority
8456             calculated as follows:
8457             <list compact="compact">
8458               <item>
8459                   Start with a priority of 20.
8460               </item>
8461
8462               <item>
8463                   If the window manager supports the Debian menu
8464                   system, add 20 points if this support is available
8465                   in the package's default configuration (i.e., no
8466                   configuration files belonging to the system or user
8467                   have to be edited to activate the feature); if
8468                   configuration files must be modified, add only 10
8469                   points.
8470                 </p>
8471               </item>
8472
8473               <item>
8474                   If the window manager complies with <url
8475                     id="http://www.freedesktop.org/Standards/wm-spec"
8476                     name="The Window Manager Specification Project">,
8477                   written by the <url id="http://www.freedesktop.org/"
8478                     name="Free Desktop Group">, add 40 points.
8479               </item>
8480
8481               <item>
8482                   If the window manager permits the X session to be
8483                   restarted using a <em>different</em> window manager
8484                   (without killing the X server) in its default
8485                   configuration, add 10 points; otherwise add none.
8486               </item>
8487             </list>
8488           </p>
8489         </sect1>
8490
8491         <sect1>
8492           <heading>Packages providing fonts</heading>
8493
8494           <p>
8495             Packages that provide fonts for the X Window
8496             System<footnote>
8497                 For the purposes of Debian Policy, a "font for the X
8498                 Window System" is one which is accessed via X protocol
8499                 requests.  Fonts for the Linux console, for PostScript
8500                 renderer, or any other purpose, do not fit this
8501                 definition.  Any tool which makes such fonts available
8502                 to the X Window System, however, must abide by this
8503                 font policy.
8504             </footnote>
8505             must do a number of things to ensure that they are both
8506             available without modification of the X or font server
8507             configuration, and that they do not corrupt files used by
8508             other font packages to register information about
8509             themselves.
8510             <enumlist>
8511               <item>
8512                   Fonts of any type supported by the X Window System
8513                   must be in a separate binary package from any
8514                   executables, libraries, or documentation (except
8515                   that specific to the fonts shipped, such as their
8516                   license information).  If one or more of the fonts
8517                   so packaged are necessary for proper operation of
8518                   the package with which they are associated the font
8519                   package may be Recommended; if the fonts merely
8520                   provide an enhancement, a Suggests relationship may
8521                   be used.  Packages must not Depend on font
8522                   packages.<footnote>
8523                       This is because the X server may retrieve fonts
8524                       from the local file system or over the network
8525                       from an X font server; the Debian package system
8526                       is empowered to deal only with the local
8527                       file system.
8528                   </footnote>
8529               </item>
8530
8531               <item>
8532                   BDF fonts must be converted to PCF fonts with the
8533                   <prgn>bdftopcf</prgn> utility (available in the
8534                   <tt>xfonts-utils</tt> package, <prgn>gzip</prgn>ped, and
8535                   placed in a directory that corresponds to their
8536                   resolution:
8537                   <list compact="compact">
8538                     <item>
8539                         100 dpi fonts must be placed in
8540                         <file>/usr/share/fonts/X11/100dpi/</file>.
8541                     </item>
8542
8543                     <item>
8544                         75 dpi fonts must be placed in
8545                         <file>/usr/share/fonts/X11/75dpi/</file>.
8546                     </item>
8547
8548                     <item>
8549                         Character-cell fonts, cursor fonts, and other
8550                         low-resolution fonts must be placed in
8551                         <file>/usr/share/fonts/X11/misc/</file>.
8552                     </item>
8553                   </list>
8554               </item>
8555
8556               <item>
8557                   Type 1 fonts must be placed in
8558                   <file>/usr/share/fonts/X11/Type1/</file>.  If font
8559                   metric files are available, they must be placed here
8560                   as well.
8561               </item>
8562
8563               <item>
8564                   Subdirectories of <file>/usr/share/fonts/X11/</file>
8565                   other than those listed above must be neither
8566                   created nor used.  (The <file>PEX</file>, <file>CID</file>,
8567                   <file>Speedo</file>, and <file>cyrillic</file> directories
8568                   are excepted for historical reasons, but installation of
8569                   files into these directories remains discouraged.)
8570               </item>
8571
8572               <item>
8573                   Font packages may, instead of placing files directly
8574                   in the X font directories listed above, provide
8575                   symbolic links in that font directory pointing to
8576                   the files' actual location in the filesystem.  Such
8577                   a location must comply with the FHS.
8578               </item>
8579
8580               <item>
8581                   Font packages should not contain both 75dpi and
8582                   100dpi versions of a font.  If both are available,
8583                   they should be provided in separate binary packages
8584                   with <tt>-75dpi</tt> or <tt>-100dpi</tt> appended to
8585                   the names of the packages containing the
8586                   corresponding fonts.
8587               </item>
8588
8589               <item>
8590                   Fonts destined for the <file>misc</file> subdirectory
8591                   should not be included in the same package as 75dpi
8592                   or 100dpi fonts; instead, they should be provided in
8593                   a separate package with <tt>-misc</tt> appended to
8594                   its name.
8595               </item>
8596
8597               <item>
8598                   Font packages must not provide the files
8599                   <file>fonts.dir</file>, <file>fonts.alias</file>, or
8600                   <file>fonts.scale</file> in a font directory:
8601                   <list>
8602                     <item>
8603                         <file>fonts.dir</file> files must not be provided at all.
8604                     </item>
8605
8606                     <item>
8607                         <file>fonts.alias</file> and <file>fonts.scale</file>
8608                         files, if needed, should be provided in the
8609                         directory
8610                         <file>/etc/X11/fonts/<var>fontdir</var>/<var>package</var>.<var>extension</var></file>,
8611                         where <var>fontdir</var> is the name of the
8612                         subdirectory of
8613                         <file>/usr/share/fonts/X11/</file> where the
8614                         package's corresponding fonts are stored
8615                         (e.g., <tt>75dpi</tt> or <tt>misc</tt>),
8616                         <var>package</var> is the name of the package
8617                         that provides these fonts, and
8618                         <var>extension</var> is either <tt>scale</tt>
8619                         or <tt>alias</tt>, whichever corresponds to
8620                         the file contents.
8621                     </item>
8622                   </list>
8623               </item>
8624
8625               <item>
8626                   Font packages must declare a dependency on
8627                   <tt>xfonts-utils</tt> in their control
8628                   data.
8629               </item>
8630
8631               <item>
8632                   Font packages that provide one or more
8633                   <file>fonts.scale</file> files as described above must
8634                   invoke <prgn>update-fonts-scale</prgn> on each
8635                   directory into which they installed fonts
8636                   <em>before</em> invoking
8637                   <prgn>update-fonts-dir</prgn> on that directory.
8638                   This invocation must occur in both the
8639                   <prgn>postinst</prgn> (for all arguments) and
8640                   <prgn>postrm</prgn> (for all arguments except
8641                   <tt>upgrade</tt>) scripts.
8642               </item>
8643
8644               <item>
8645                   Font packages that provide one or more
8646                   <file>fonts.alias</file> files as described above must
8647                   invoke <prgn>update-fonts-alias</prgn> on each
8648                   directory into which they installed fonts.  This
8649                   invocation must occur in both the
8650                   <prgn>postinst</prgn> (for all arguments) and
8651                   <prgn>postrm</prgn> (for all arguments except
8652                   <tt>upgrade</tt>) scripts.
8653               </item>
8654
8655               <item>
8656                   Font packages must invoke
8657                   <prgn>update-fonts-dir</prgn> on each directory into
8658                   which they installed fonts.  This invocation must
8659                   occur in both the <prgn>postinst</prgn> (for all
8660                   arguments) and <prgn>postrm</prgn> (for all
8661                   arguments except <tt>upgrade</tt>) scripts.
8662               </item>
8663
8664               <item>
8665                   Font packages must not provide alias names for the
8666                   fonts they include which collide with alias names
8667                   already in use by fonts already packaged.
8668               </item>
8669
8670               <item>
8671                   Font packages must not provide fonts with the same
8672                   XLFD registry name as another font already packaged.
8673               </item>
8674             </enumlist>
8675           </p>
8676         </sect1>
8677
8678         <sect1 id="appdefaults">
8679           <heading>Application defaults files</heading>
8680
8681           <p>
8682             Application defaults files must be installed in the
8683             directory <file>/etc/X11/app-defaults/</file> (use of a
8684             localized subdirectory of <file>/etc/X11/</file> as described
8685             in the <em>X Toolkit Intrinsics - C Language
8686             Interface</em> manual is also permitted).  They must be
8687             registered as <tt>conffile</tt>s or handled as
8688             configuration files.
8689           </p>
8690
8691           <p>
8692             Customization of programs' X resources may also be
8693             supported with the provision of a file with the same name
8694             as that of the package placed in
8695             the <file>/etc/X11/Xresources/</file> directory, which
8696             must be registered as a <tt>conffile</tt> or handled as a
8697             configuration file.<footnote>
8698                 Note that this mechanism is not the same as using
8699                 app-defaults; app-defaults are tied to the client
8700                 binary on the local file system, whereas X resources
8701                 are stored in the X server and affect all connecting
8702                 clients.
8703             </footnote>
8704           </p>
8705         </sect1>
8706
8707         <sect1>
8708           <heading>Installation directory issues</heading>
8709
8710           <p>
8711             Historically, packages using the X Window System used a
8712             separate set of installation directories from other packages.
8713             This practice has been discontinued and packages using the X
8714             Window System should now generally be installed in the same
8715             directories as any other package.  Specifically, packages must
8716             not install files under the <file>/usr/X11R6/</file> directory
8717             and the <file>/usr/X11R6/</file> directory hierarchy should be
8718             regarded as obsolete.
8719           </p>
8720
8721           <p>
8722             Include files previously installed under
8723             <file>/usr/X11R6/include/X11/</file> should be installed into
8724             <file>/usr/include/X11/</file>.  For files previously
8725             installed into subdirectories of
8726             <file>/usr/X11R6/lib/X11/</file>, package maintainers should
8727             determine if subdirectories of <file>/usr/lib/</file> and
8728             <file>/usr/share/</file> can be used.  If not, a subdirectory
8729             of <file>/usr/lib/X11/</file> should be used.
8730           </p>
8731
8732           <p>
8733             Configuration files for window, display, or session managers
8734             or other applications that are tightly integrated with the X
8735             Window System may be placed in a subdirectory
8736             of <file>/etc/X11/</file> corresponding to the package name.
8737             Other X Window System applications should use
8738             the <file>/etc/</file> directory unless otherwise mandated by
8739             policy (such as for <ref id="appdefaults">).
8740           </p>
8741         </sect1>
8742
8743         <sect1>
8744           <heading>The OSF/Motif and OpenMotif libraries</heading>
8745
8746           <p>
8747             <em>Programs that require the non-DFSG-compliant OSF/Motif or
8748               OpenMotif libraries</em><footnote>
8749                 OSF/Motif and OpenMotif are collectively referred to as
8750                 "Motif" in this policy document.
8751             </footnote>
8752             should be compiled against and tested with LessTif (a free
8753             re-implementation of Motif) instead.  If the maintainer
8754             judges that the program or programs do not work
8755             sufficiently well with LessTif to be distributed and
8756             supported, but do so when compiled against Motif, then two
8757             versions of the package should be created; one linked
8758             statically against Motif and with <tt>-smotif</tt>
8759             appended to the package name, and one linked dynamically
8760             against Motif and with <tt>-dmotif</tt> appended to the
8761             package name.
8762           </p>
8763
8764           <p>
8765             Both Motif-linked versions are dependent
8766             upon non-DFSG-compliant software and thus cannot be
8767             uploaded to the <em>main</em> distribution; if the
8768             software is itself DFSG-compliant it may be uploaded to
8769             the <em>contrib</em> distribution.  While known existing
8770             versions of Motif permit unlimited redistribution of
8771             binaries linked against the library (whether statically or
8772             dynamically), it is the package maintainer's
8773             responsibility to determine whether this is permitted by
8774             the license of the copy of Motif in their possession.
8775           </p>
8776         </sect1>
8777       </sect>
8778
8779       <sect id="perl">
8780         <heading>Perl programs and modules</heading>
8781
8782         <p>
8783           Perl programs and modules should follow the current Perl policy.
8784         </p>
8785
8786         <p>
8787           The Perl policy can be found in the <tt>perl-policy</tt>
8788           files in the <tt>debian-policy</tt> package.
8789           It is also available from the Debian web mirrors at
8790           <tt><url name="/doc/packaging-manuals/perl-policy/"
8791                 id="http://www.debian.org/doc/packaging-manuals/perl-policy/"></tt>.
8792         </p>
8793       </sect>
8794
8795       <sect id="emacs">
8796         <heading>Emacs lisp programs</heading>
8797
8798         <p>
8799           Please refer to the "Debian Emacs Policy" for details of how to
8800           package emacs lisp programs.
8801         </p>
8802
8803         <p>
8804           The Emacs policy is available in
8805           <file>debian-emacs-policy.gz</file> of the
8806           <package>emacsen-common</package> package.
8807           It is also available from the Debian web mirrors at
8808           <tt><url name="/doc/packaging-manuals/debian-emacs-policy"
8809                 id="http://www.debian.org/doc/packaging-manuals/debian-emacs-policy"></tt>.
8810         </p>
8811       </sect>
8812
8813       <sect>
8814         <heading>Games</heading>
8815
8816         <p>
8817           The permissions on <file>/var/games</file> are mode 755, owner
8818           <tt>root</tt> and group <tt>root</tt>.
8819         </p>
8820
8821         <p>
8822           Each game decides on its own security policy.</p>
8823
8824         <p>
8825           Games which require protected, privileged access to
8826           high-score files, saved games, etc., may be made
8827           set-<em>group</em>-id (mode 2755) and owned by
8828           <tt>root:games</tt>, and use files and directories with
8829           appropriate permissions (770 <tt>root:games</tt>, for
8830           example).  They must not be made
8831           set-<em>user</em>-id, as this causes security problems. (If
8832           an attacker can subvert any set-user-id game they can
8833           overwrite the executable of any other, causing other players
8834           of these games to run a Trojan horse program.  With a
8835           set-group-id game the attacker only gets access to less
8836           important game data, and if they can get at the other
8837           players' accounts at all it will take considerably more
8838           effort.)</p>
8839
8840         <p>
8841           Some packages, for example some fortune cookie programs, are
8842           configured by the upstream authors to install with their
8843           data files or other static information made unreadable so
8844           that they can only be accessed through set-id programs
8845           provided.  You should not do this in a Debian package: anyone can
8846           download the <file>.deb</file> file and read the data from it,
8847           so there is no point making the files unreadable.  Not
8848           making the files unreadable also means that you don't have
8849           to make so many programs set-id, which reduces the risk of a
8850           security hole.</p>
8851
8852         <p>
8853           As described in the FHS, binaries of games should be
8854           installed in the directory <file>/usr/games</file>. This also
8855           applies to games that use the X Window System. Manual pages
8856           for games (X and non-X games) should be installed in
8857           <file>/usr/share/man/man6</file>.</p>
8858       </sect>
8859     </chapt>
8860
8861
8862     <chapt id="docs">
8863       <heading>Documentation</heading>
8864
8865       <sect>
8866         <heading>Manual pages</heading>
8867
8868         <p>
8869           You should install manual pages in <prgn>nroff</prgn> source
8870           form, in appropriate places under <file>/usr/share/man</file>.
8871           You should only use sections 1 to 9 (see the FHS for more
8872           details).  You must not install a pre-formatted "cat page".
8873         </p>
8874
8875         <p>
8876           Each program, utility, and function should have an
8877           associated manual page included in the same package. It is
8878           suggested that all configuration files also have a manual
8879           page included as well. Manual pages for protocols and other
8880           auxiliary things are optional.
8881         </p>
8882
8883         <p>
8884           If no manual page is available, this is considered as a bug
8885           and should be reported to the Debian Bug Tracking System (the
8886           maintainer of the package is allowed to write this bug report
8887           themselves, if they so desire).  Do not close the bug report
8888           until a proper man page is available.<footnote>
8889               It is not very hard to write a man page. See the
8890               <url id="http://www.schweikhardt.net/man_page_howto.html"
8891                 name="Man-Page-HOWTO">,
8892               <manref name="man" section="7">, the examples
8893               created by <prgn>debmake</prgn> or <prgn>dh_make</prgn>,
8894               the helper programs <prgn>help2man</prgn>, or the
8895               directory <file>/usr/share/doc/man-db/examples</file>.
8896           </footnote>
8897         </p>
8898
8899         <p>
8900           You may forward a complaint about a missing man page to the
8901           upstream authors, and mark the bug as forwarded in the
8902           Debian bug tracking system.  Even though the GNU Project do
8903           not in general consider the lack of a man page to be a bug,
8904           we do; if they tell you that they don't consider it a bug
8905           you should leave the bug in our bug tracking system open
8906           anyway.
8907         </p>
8908
8909         <p>
8910           Manual pages should be installed compressed using <tt>gzip -9</tt>.
8911         </p>
8912
8913         <p>
8914           If one man page needs to be accessible via several names it
8915           is better to use a symbolic link than the <file>.so</file>
8916           feature, but there is no need to fiddle with the relevant
8917           parts of the upstream source to change from <file>.so</file> to
8918           symlinks: don't do it unless it's easy.  You should not
8919           create hard links in the manual page directories, nor put
8920           absolute filenames in <file>.so</file> directives.  The filename
8921           in a <file>.so</file> in a man page should be relative to the
8922           base of the man page tree (usually
8923           <file>/usr/share/man</file>). If you do not create any links
8924           (whether symlinks, hard links, or <tt>.so</tt> directives)
8925           in the file system to the alternate names of the man page,
8926           then you should not rely on <prgn>man</prgn> finding your
8927           man page under those names based solely on the information in
8928           the man page's header.<footnote>
8929               Supporting this in <prgn>man</prgn> often requires
8930               unreasonable processing time to find a manual page or to
8931               report that none exists, and moves knowledge into man's
8932               database that would be better left in the file system.
8933               This support is therefore deprecated and will cease to
8934               be present in the future.
8935           </footnote>
8936         </p>
8937
8938         <p>
8939           Manual pages in locale-specific subdirectories of
8940           <file>/usr/share/man</file> should use either UTF-8 or the usual
8941           legacy encoding for that language (normally the one corresponding
8942           to the shortest relevant locale name in
8943           <file>/usr/share/i18n/SUPPORTED</file>). For example, pages under
8944           <file>/usr/share/man/fr</file> should use either UTF-8 or
8945           ISO-8859-1.<footnote>
8946             <prgn>man</prgn> will automatically detect whether UTF-8 is in
8947             use. In future, all manual pages will be required to use
8948             UTF-8.
8949           </footnote>
8950         </p>
8951
8952         <p>
8953           A country name (the <tt>DE</tt> in <tt>de_DE</tt>) should not be
8954           included in the subdirectory name unless it indicates a
8955           significant difference in the language, as this excludes
8956           speakers of the language in other countries.<footnote>
8957             At the time of writing, Chinese and Portuguese are the main
8958             languages with such differences, so <file>pt_BR</file>,
8959             <file>zh_CN</file>, and <file>zh_TW</file> are all allowed.
8960           </footnote>
8961         </p>
8962
8963         <p>
8964           If a localized version of a manual page is provided, it should
8965           either be up-to-date or it should be obvious to the reader that
8966           it is outdated and the original manual page should be used
8967           instead.  This can be done either by a note at the beginning of
8968           the manual page or by showing the missing or changed portions in
8969           the original language instead of the target language.
8970         </p>
8971       </sect>
8972
8973       <sect>
8974         <heading>Info documents</heading>
8975
8976         <p>
8977           Info documents should be installed in <file>/usr/share/info</file>.
8978           They should be compressed with <tt>gzip -9</tt>.
8979         </p>
8980
8981         <p>
8982           The <prgn>install-info</prgn> program maintains a directory of
8983           installed info documents in <file>/usr/share/info/dir</file> for
8984           the use of info readers.<footnote>
8985             It was previously necessary for packages installing info
8986             documents to run <prgn>install-info</prgn> from maintainer
8987             scripts.  This is no longer necessary.  The installation
8988             system now uses dpkg triggers.
8989           </footnote>
8990           This file must not be included in packages.  Packages containing
8991           info documents should depend on <tt>dpkg (>= 1.15.4) |
8992           install-info</tt> to ensure that the directory file is properly
8993           rebuilt during partial upgrades from Debian 5.0 (lenny) and
8994           earlier.
8995         </p>
8996
8997         <p>
8998           Info documents should contain section and directory entry
8999           information in the document for the use
9000           of <prgn>install-info</prgn>.  The section should be specified
9001           via a line starting with <tt>INFO-DIR-SECTION</tt> followed by a
9002           space and the section of this info page.  The directory entry or
9003           entries should be included between
9004           a <tt>START-INFO-DIR-ENTRY</tt> line and
9005           an <tt>END-INFO-DIR-ENTRY</tt> line.  For example:
9006           <example>
9007 INFO-DIR-SECTION Individual utilities
9008 START-INFO-DIR-ENTRY
9009 * example: (example).               An example info directory entry.
9010 END-INFO-DIR-ENTRY
9011           </example>
9012           To determine which section to use, you should look
9013           at <file>/usr/share/info/dir</file> on your system and choose
9014           the most relevant (or create a new section if none of the
9015           current sections are relevant).<footnote>
9016             Normally, info documents are generated from Texinfo source.
9017             To include this information in the generated info document, if
9018             it is absent, add commands like:
9019             <example>
9020 @dircategory Individual utilities
9021 @direntry
9022 * example: (example).               An example info directory entry.
9023 @end direntry
9024             </example>
9025             to the Texinfo source of the document and ensure that the info
9026             documents are rebuilt from source during the package build.
9027           </footnote>
9028         </p>
9029       </sect>
9030
9031       <sect>
9032         <heading>Additional documentation</heading>
9033
9034         <p>
9035           Any additional documentation that comes with the package may
9036           be installed at the discretion of the package maintainer.
9037           Plain text documentation should be installed in the directory
9038           <file>/usr/share/doc/<var>package</var></file>, where
9039           <var>package</var> is the name of the package, and
9040           compressed with <tt>gzip -9</tt> unless it is small.
9041         </p>
9042
9043         <p>
9044           If a package comes with large amounts of documentation which
9045           many users of the package will not require you should create
9046           a separate binary package to contain it, so that it does not
9047           take up disk space on the machines of users who do not need
9048           or want it installed.</p>
9049
9050         <p>
9051           It is often a good idea to put text information files
9052           (<file>README</file>s, changelogs, and so forth) that come with
9053           the source package in <file>/usr/share/doc/<var>package</var></file>
9054           in the binary package.  However, you don't need to install
9055           the instructions for building and installing the package, of
9056           course!</p>
9057
9058         <p>
9059           Packages must not require the existence of any files in
9060           <file>/usr/share/doc/</file> in order to function
9061           <footnote>
9062               The system administrator should be able to
9063               delete files in <file>/usr/share/doc/</file> without causing
9064               any programs to break.
9065           </footnote>.
9066           Any files that are referenced by programs but are also
9067           useful as stand alone documentation should be installed under
9068           <file>/usr/share/<var>package</var>/</file> with symbolic links from
9069           <file>/usr/share/doc/<var>package</var></file>.
9070         </p>
9071
9072         <p>
9073           <file>/usr/share/doc/<var>package</var></file> may be a symbolic
9074           link to another directory in <file>/usr/share/doc</file> only if
9075           the two packages both come from the same source and the
9076           first package Depends on the second.<footnote>
9077             <p>
9078               Please note that this does not override the section on
9079               changelog files below, so the file 
9080               <file>/usr/share/doc/<var>package</var>/changelog.Debian.gz</file>
9081               must refer to the changelog for the current version of
9082               <var>package</var> in question. In practice, this means
9083               that the sources of the target and the destination of the
9084               symlink must be the same (same source package and
9085               version). 
9086             </p>
9087           </footnote>
9088         </p>
9089
9090         <p>
9091           Former Debian releases placed all additional documentation
9092           in <file>/usr/doc/<var>package</var></file>.  This has been
9093           changed to <file>/usr/share/doc/<var>package</var></file>,
9094           and packages must not put documentation in the directory
9095           <file>/usr/doc/<var>package</var></file>. <footnote>
9096             At this phase of the transition, we no longer require a
9097             symbolic link in <file>/usr/doc/</file>. At a later point,
9098             policy shall change to make the symbolic links a bug.
9099           </footnote>
9100         </p>
9101       </sect>
9102
9103       <sect>
9104         <heading>Preferred documentation formats</heading>
9105
9106         <p>
9107           The unification of Debian documentation is being carried out
9108           via HTML.</p>
9109
9110         <p>
9111           If your package comes with extensive documentation in a
9112           markup format that can be converted to various other formats
9113           you should if possible ship HTML versions in a binary
9114           package, in the directory
9115           <file>/usr/share/doc/<var>appropriate-package</var></file> or
9116           its subdirectories.<footnote>
9117               The rationale: The important thing here is that HTML
9118               docs should be available in <em>some</em> package, not
9119               necessarily in the main binary package.
9120           </footnote>
9121         </p>
9122
9123         <p>
9124           Other formats such as PostScript may be provided at the
9125           package maintainer's discretion.
9126         </p>
9127       </sect>
9128
9129       <sect id="copyrightfile">
9130         <heading>Copyright information</heading>
9131
9132         <p>
9133           Every package must be accompanied by a verbatim copy of its
9134           copyright information and distribution license in the file
9135           <file>/usr/share/doc/<var>package</var>/copyright</file>. This
9136           file must neither be compressed nor be a symbolic link.
9137         </p>
9138
9139         <p>
9140           In addition, the copyright file must say where the upstream
9141           sources (if any) were obtained.  It should name the original
9142           authors of the package and the Debian maintainer(s) who were
9143           involved with its creation.
9144         </p>
9145
9146         <p>
9147           Packages in the <em>contrib</em> or <em>non-free</em> archive
9148           areas should state in the copyright file that the package is not
9149           part of the Debian GNU/Linux distribution and briefly explain
9150           why.
9151         </p>
9152
9153         <p>
9154           A copy of the file which will be installed in
9155           <file>/usr/share/doc/<var>package</var>/copyright</file> should
9156           be in <file>debian/copyright</file> in the source package.
9157         </p>
9158
9159         <p>
9160           <file>/usr/share/doc/<var>package</var></file> may be a symbolic
9161           link to another directory in <file>/usr/share/doc</file> only if
9162           the two packages both come from the same source and the
9163           first package Depends on the second.  These rules are
9164           important because copyrights must be extractable by
9165           mechanical means.
9166         </p>
9167
9168         <p>
9169           Packages distributed under the UCB BSD license, the Apache
9170           license (version 2.0), the Artistic license, the GNU GPL
9171           (version 2 or 3), the GNU LGPL (versions 2, 2.1, or 3), and the
9172           GNU FDL (versions 1.2 or 1.3) should refer to the corresponding
9173           files under <file>/usr/share/common-licenses</file>,<footnote>
9174             <p>
9175               In particular,
9176               <file>/usr/share/common-licenses/BSD</file>,
9177               <file>/usr/share/common-licenses/Apache-2.0</file>,
9178               <file>/usr/share/common-licenses/Artistic</file>,
9179               <file>/usr/share/common-licenses/GPL-2</file>,
9180               <file>/usr/share/common-licenses/GPL-3</file>,
9181               <file>/usr/share/common-licenses/LGPL-2</file>,
9182               <file>/usr/share/common-licenses/LGPL-2.1</file>,
9183               <file>/usr/share/common-licenses/LGPL-3</file>,
9184               <file>/usr/share/common-licenses/GFDL-1.2</file>, and
9185               <file>/usr/share/common-licenses/GFDL-1.3</file>
9186               respectively.
9187             </p>
9188           </footnote> rather than quoting them in the copyright
9189           file. 
9190         </p>
9191
9192         <p>
9193           You should not use the copyright file as a general <file>README</file>
9194           file.  If your package has such a file it should be
9195           installed in <file>/usr/share/doc/<var>package</var>/README</file> or
9196           <file>README.Debian</file> or some other appropriate place.</p>
9197       </sect>
9198
9199       <sect>
9200         <heading>Examples</heading>
9201
9202         <p>
9203           Any examples (configurations, source files, whatever),
9204           should be installed in a directory
9205           <file>/usr/share/doc/<var>package</var>/examples</file>.  These
9206           files should not be referenced by any program: they're there
9207           for the benefit of the system administrator and users as
9208           documentation only.  Architecture-specific example files
9209           should be installed in a directory
9210           <file>/usr/lib/<var>package</var>/examples</file> with symbolic
9211           links to them from
9212           <file>/usr/share/doc/<var>package</var>/examples</file>, or the
9213           latter directory itself may be a symbolic link to the
9214           former.
9215         </p>
9216
9217         <p>
9218           If the purpose of a package is to provide examples, then the
9219           example files may be installed into
9220           <file>/usr/share/doc/<var>package</var></file>.
9221         </p>
9222       </sect>
9223
9224       <sect id="changelogs">
9225         <heading>Changelog files</heading>
9226
9227         <p>
9228           Packages that are not Debian-native must contain a
9229           compressed copy of the <file>debian/changelog</file> file from
9230           the Debian source tree in
9231           <file>/usr/share/doc/<var>package</var></file> with the name
9232           <file>changelog.Debian.gz</file>.
9233         </p>
9234
9235         <p>
9236           If an upstream changelog is available, it should be accessible as
9237           <file>/usr/share/doc/<var>package</var>/changelog.gz</file> in
9238           plain text.  If the upstream changelog is distributed in
9239           HTML, it should be made available in that form as
9240           <file>/usr/share/doc/<var>package</var>/changelog.html.gz</file>
9241           and a plain text <file>changelog.gz</file> should be generated
9242           from it using, for example, <tt>lynx -dump -nolist</tt>.  If
9243           the upstream changelog files do not already conform to this
9244           naming convention, then this may be achieved either by
9245           renaming the files, or by adding a symbolic link, at the
9246           maintainer's discretion.<footnote>
9247               Rationale: People should not have to look in places for
9248               upstream changelogs merely because they are given
9249               different names or are distributed in HTML format.
9250           </footnote>
9251         </p>
9252
9253         <p>
9254           All of these files should be installed compressed using
9255           <tt>gzip -9</tt>, as they will become large with time even
9256           if they start out small.
9257         </p>
9258
9259         <p>
9260           If the package has only one changelog which is used both as
9261           the Debian changelog and the upstream one because there is
9262           no separate upstream maintainer then that changelog should
9263           usually be installed as
9264           <file>/usr/share/doc/<var>package</var>/changelog.gz</file>; if
9265           there is a separate upstream maintainer, but no upstream
9266           changelog, then the Debian changelog should still be called
9267           <file>changelog.Debian.gz</file>.
9268         </p>
9269
9270         <p>
9271           For details about the format and contents of the Debian
9272           changelog file, please see <ref id="dpkgchangelog">.
9273         </p>
9274       </sect>
9275     </chapt>
9276
9277     <appendix id="pkg-scope">
9278       <heading>Introduction and scope of these appendices</heading>
9279
9280       <p>
9281         These appendices are taken essentially verbatim from the
9282         now-deprecated Packaging Manual, version 3.2.1.0.  They are
9283         the chapters which are likely to be of use to package
9284         maintainers and which have not already been included in the
9285         policy document itself. Most of these sections are very likely
9286         not relevant to policy; they should be treated as
9287         documentation for the packaging system. Please note that these
9288         appendices are included for convenience, and for historical
9289         reasons: they used to be part of policy package, and they have
9290         not yet been incorporated into dpkg documentation. However,
9291         they still have value, and hence they are presented here.
9292       </p>
9293
9294       <p>
9295         They have not yet been checked to ensure that they are
9296         compatible with the contents of policy, and if there are any
9297         contradictions, the version in the main policy document takes
9298         precedence.  The remaining chapters of the old Packaging
9299         Manual have also not been read in detail to ensure that there
9300         are not parts which have been left out.  Both of these will be
9301         done in due course.
9302       </p>
9303
9304       <p>
9305         Certain parts of the Packaging manual were integrated into the
9306         Policy Manual proper, and removed from the appendices. Links
9307         have been placed from the old locations to the new ones.
9308       </p>
9309
9310       <p>
9311         <prgn>dpkg</prgn> is a suite of programs for creating binary
9312         package files and installing and removing them on Unix
9313         systems.<footnote>
9314             <prgn>dpkg</prgn> is targeted primarily at Debian
9315             GNU/Linux, but may work on or be ported to other
9316             systems.
9317         </footnote>
9318       </p>
9319
9320       <p>
9321         The binary packages are designed for the management of
9322         installed executable programs (usually compiled binaries) and
9323         their associated data, though source code examples and
9324         documentation are provided as part of some packages.</p>
9325
9326       <p>
9327         This manual describes the technical aspects of creating Debian
9328         binary packages (<file>.deb</file> files).  It documents the
9329         behavior of the package management programs
9330         <prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and the way
9331         they interact with packages.</p>
9332
9333       <p>
9334         It also documents the interaction between
9335         <prgn>dselect</prgn>'s core and the access method scripts it
9336         uses to actually install the selected packages, and describes
9337         how to create a new access method.</p>
9338
9339       <p>
9340         This manual does not go into detail about the options and
9341         usage of the package building and installation tools.  It
9342         should therefore be read in conjunction with those programs'
9343         man pages.
9344       </p>
9345
9346       <p>
9347         The utility programs which are provided with <prgn>dpkg</prgn>
9348         for managing various system configuration and similar issues,
9349         such as <prgn>update-rc.d</prgn> and
9350         <prgn>install-info</prgn>, are not described in detail here -
9351         please see their man pages.
9352       </p>
9353
9354       <p>
9355         It is assumed that the reader is reasonably familiar with the
9356         <prgn>dpkg</prgn> System Administrators' manual.
9357         Unfortunately this manual does not yet exist.
9358       </p>
9359
9360       <p>
9361         The Debian version of the FSF's GNU hello program is provided
9362         as an example for people wishing to create Debian
9363         packages. The Debian <prgn>debmake</prgn> package is
9364         recommended as a very helpful tool in creating and maintaining
9365         Debian packages. However, while the tools and examples are
9366         helpful, they do not replace the need to read and follow the
9367         Policy and Programmer's Manual.</p>
9368     </appendix>
9369
9370     <appendix id="pkg-binarypkg">
9371       <heading>Binary packages (from old Packaging Manual)</heading>
9372
9373       <p>
9374         The binary package has two main sections.  The first part
9375         consists of various control information files and scripts used
9376         by <prgn>dpkg</prgn> when installing and removing.  See <ref
9377         id="pkg-controlarea">.
9378       </p>
9379
9380       <p>
9381         The second part is an archive containing the files and
9382         directories to be installed.
9383       </p>
9384
9385       <p>
9386         In the future binary packages may also contain other
9387         components, such as checksums and digital signatures. The
9388         format for the archive is described in full in the
9389         <file>deb(5)</file> man page.
9390       </p>
9391
9392
9393       <sect id="pkg-bincreating"><heading>Creating package files -
9394       <prgn>dpkg-deb</prgn>
9395         </heading>
9396
9397         <p>
9398           All manipulation of binary package files is done by
9399           <prgn>dpkg-deb</prgn>; it's the only program that has
9400           knowledge of the format.  (<prgn>dpkg-deb</prgn> may be
9401           invoked by calling <prgn>dpkg</prgn>, as <prgn>dpkg</prgn>
9402           will spot that the options requested are appropriate to
9403           <prgn>dpkg-deb</prgn> and invoke that instead with the same
9404           arguments.)
9405         </p>
9406
9407         <p>
9408           In order to create a binary package you must make a
9409           directory tree which contains all the files and directories
9410           you want to have in the file system data part of the package.
9411           In Debian-format source packages this directory is usually
9412           <file>debian/tmp</file>, relative to the top of the package's
9413           source tree.
9414         </p>
9415
9416         <p>
9417           They should have the locations (relative to the root of the
9418           directory tree you're constructing) ownerships and
9419           permissions which you want them to have on the system when
9420           they are installed.
9421         </p>
9422
9423         <p>
9424           With current versions of <prgn>dpkg</prgn> the uid/username
9425           and gid/groupname mappings for the users and groups being
9426           used should be the same on the system where the package is
9427           built and the one where it is installed.
9428         </p>
9429
9430         <p>
9431           You need to add one special directory to the root of the
9432           miniature file system tree you're creating:
9433           <prgn>DEBIAN</prgn>.  It should contain the control
9434           information files, notably the binary package control file
9435           (see <ref id="pkg-controlfile">).
9436         </p>
9437
9438         <p>
9439           The <prgn>DEBIAN</prgn> directory will not appear in the
9440           file system archive of the package, and so won't be installed
9441           by <prgn>dpkg</prgn> when the package is installed.
9442         </p>
9443
9444         <p>
9445           When you've prepared the package, you should invoke:
9446           <example>
9447   dpkg --build <var>directory</var>
9448           </example>
9449         </p>
9450
9451         <p>
9452           This will build the package in
9453           <file><var>directory</var>.deb</file>.  (<prgn>dpkg</prgn> knows
9454           that <tt>--build</tt> is a <prgn>dpkg-deb</prgn> option, so
9455           it invokes <prgn>dpkg-deb</prgn> with the same arguments to
9456           build the package.)
9457         </p>
9458
9459         <p>
9460           See the man page <manref name="dpkg-deb" section="8"> for details of how
9461           to examine the contents of this newly-created file.  You may find the
9462           output of following commands enlightening:
9463           <example>
9464   dpkg-deb --info <var>filename</var>.deb
9465   dpkg-deb --contents <var>filename</var>.deb
9466   dpkg --contents <var>filename</var>.deb
9467           </example>
9468           To view the copyright file for a package you could use this command:
9469           <example>
9470   dpkg --fsys-tarfile <var>filename</var>.deb | tar xOf - --wildcards \*/copyright | pager
9471           </example>
9472         </p>
9473       </sect>
9474
9475       <sect id="pkg-controlarea">
9476         <heading>Package control information files</heading>
9477
9478         <p>
9479           The control information portion of a binary package is a
9480           collection of files with names known to <prgn>dpkg</prgn>.
9481           It will treat the contents of these files specially - some
9482           of them contain information used by <prgn>dpkg</prgn> when
9483           installing or removing the package; others are scripts which
9484           the package maintainer wants <prgn>dpkg</prgn> to run.
9485         </p>
9486
9487         <p>
9488           It is possible to put other files in the package control
9489           area, but this is not generally a good idea (though they
9490           will largely be ignored).
9491         </p>
9492
9493         <p>
9494           Here is a brief list of the control info files supported by
9495           <prgn>dpkg</prgn> and a summary of what they're used for.
9496         </p>
9497
9498         <p>
9499           <taglist>
9500             <tag><tt>control</tt>
9501             <item>
9502               <p>
9503                 This is the key description file used by
9504                 <prgn>dpkg</prgn>.  It specifies the package's name
9505                 and version, gives its description for the user,
9506                 states its relationships with other packages, and so
9507                 forth.  See <ref id="sourcecontrolfiles"> and
9508                 <ref id="binarycontrolfiles">.
9509               </p>
9510
9511               <p>
9512                 It is usually generated automatically from information
9513                 in the source package by the
9514                 <prgn>dpkg-gencontrol</prgn> program, and with
9515                 assistance from <prgn>dpkg-shlibdeps</prgn>.
9516                 See <ref id="pkg-sourcetools">.
9517               </p>
9518             </item>
9519
9520             <tag><tt>postinst</tt>, <tt>preinst</tt>, <tt>postrm</tt>,
9521                  <tt>prerm</tt>
9522             </tag>
9523             <item>
9524               <p>
9525                 These are executable files (usually scripts) which
9526                 <prgn>dpkg</prgn> runs during installation, upgrade
9527                 and removal of packages.  They allow the package to
9528                 deal with matters which are particular to that package
9529                 or require more complicated processing than that
9530                 provided by <prgn>dpkg</prgn>.  Details of when and
9531                 how they are called are in <ref id="maintainerscripts">.
9532               </p>
9533
9534               <p>
9535                 It is very important to make these scripts idempotent.
9536                 See <ref id="idempotency">.
9537               </p>
9538
9539               <p>
9540                 The maintainer scripts are guaranteed to run with a
9541                 controlling terminal and can interact with the user.
9542                 See <ref id="controllingterminal">.
9543               </p>
9544             </item>
9545
9546             <tag><tt>conffiles</tt>
9547             </tag>
9548             <item>
9549                 This file contains a list of configuration files which
9550                 are to be handled automatically by <prgn>dpkg</prgn>
9551                 (see <ref id="pkg-conffiles">).  Note that not necessarily
9552                 every configuration file should be listed here.
9553             </item>
9554
9555             <tag><tt>shlibs</tt>
9556             </tag>
9557             <item>
9558                 This file contains a list of the shared libraries
9559                 supplied by the package, with dependency details for
9560                 each.  This is used by <prgn>dpkg-shlibdeps</prgn>
9561                 when it determines what dependencies are required in a
9562                 package control file. The <tt>shlibs</tt> file format
9563                 is described on <ref id="shlibs">.
9564             </item>
9565           </taglist>
9566         </p>
9567
9568       <sect id="pkg-controlfile">
9569         <heading>The main control information file: <tt>control</tt></heading>
9570
9571         <p>
9572           The most important control information file used by
9573           <prgn>dpkg</prgn> when it installs a package is
9574           <tt>control</tt>.  It contains all the package's "vital
9575           statistics".
9576         </p>
9577
9578         <p>
9579           The binary package control files of packages built from
9580           Debian sources are made by a special tool,
9581           <prgn>dpkg-gencontrol</prgn>, which reads
9582           <file>debian/control</file> and <file>debian/changelog</file> to
9583           find the information it needs.  See <ref id="pkg-sourcepkg"> for
9584           more details.
9585         </p>
9586
9587         <p>
9588           The fields in binary package control files are listed in
9589           <ref id="binarycontrolfiles">.
9590         </p>
9591
9592         <p>
9593           A description of the syntax of control files and the purpose
9594           of the fields is available in <ref id="controlfields">.
9595         </p>
9596       </sect>
9597
9598       <sect>
9599         <heading>Time Stamps</heading>
9600
9601         <p>
9602           See <ref id="timestamps">.
9603         </p>
9604       </sect>
9605     </appendix>
9606
9607     <appendix id="pkg-sourcepkg">
9608       <heading>Source packages (from old Packaging Manual) </heading>
9609
9610       <p>
9611         The Debian binary packages in the distribution are generated
9612         from Debian sources, which are in a special format to assist
9613         the easy and automatic building of binaries.
9614       </p>
9615
9616       <sect id="pkg-sourcetools">
9617         <heading>Tools for processing source packages</heading>
9618
9619         <p>
9620           Various tools are provided for manipulating source packages;
9621           they pack and unpack sources and help build of binary
9622           packages and help manage the distribution of new versions.
9623         </p>
9624
9625         <p>
9626           They are introduced and typical uses described here; see
9627           <manref name="dpkg-source" section="1"> for full
9628           documentation about their arguments and operation.
9629         </p>
9630
9631         <p>
9632           For examples of how to construct a Debian source package,
9633           and how to use those utilities that are used by Debian
9634           source packages, please see the <prgn>hello</prgn> example
9635           package.
9636         </p>
9637
9638         <sect1 id="pkg-dpkg-source">
9639           <heading>
9640             <prgn>dpkg-source</prgn> - packs and unpacks Debian source
9641             packages
9642           </heading>
9643
9644           <p>
9645             This program is frequently used by hand, and is also
9646             called from package-independent automated building scripts
9647             such as <prgn>dpkg-buildpackage</prgn>.
9648           </p>
9649
9650           <p>
9651             To unpack a package it is typically invoked with
9652             <example>
9653   dpkg-source -x <var>.../path/to/filename</var>.dsc
9654             </example>
9655           </p>
9656
9657            <p>
9658             with the <file><var>filename</var>.tar.gz</file> and
9659             <file><var>filename</var>.diff.gz</file> (if applicable) in
9660             the same directory.  It unpacks into
9661             <file><var>package</var>-<var>version</var></file>, and if
9662             applicable
9663             <file><var>package</var>-<var>version</var>.orig</file>, in
9664             the current directory.
9665           </p>
9666
9667           <p>
9668             To create a packed source archive it is typically invoked:
9669             <example>
9670   dpkg-source -b <var>package</var>-<var>version</var>
9671           </example>
9672           </p>
9673
9674           <p>
9675             This will create the <file>.dsc</file>, <file>.tar.gz</file> and
9676             <file>.diff.gz</file> (if appropriate) in the current
9677             directory.  <prgn>dpkg-source</prgn> does not clean the
9678             source tree first - this must be done separately if it is
9679             required.
9680           </p>
9681
9682           <p>
9683             See also <ref id="pkg-sourcearchives">.</p>
9684         </sect1>
9685
9686
9687         <sect1 id="pkg-dpkg-buildpackage">
9688           <heading>
9689             <prgn>dpkg-buildpackage</prgn> - overall package-building
9690             control script
9691           </heading>
9692
9693           <p>
9694             <prgn>dpkg-buildpackage</prgn> is a script which invokes
9695             <prgn>dpkg-source</prgn>, the <file>debian/rules</file>
9696             targets <tt>clean</tt>, <tt>build</tt> and
9697             <tt>binary</tt>, <prgn>dpkg-genchanges</prgn> and
9698             <prgn>gpg</prgn> (or <prgn>pgp</prgn>) to build a signed
9699             source and binary package upload.
9700           </p>
9701
9702           <p>
9703             It is usually invoked by hand from the top level of the
9704             built or unbuilt source directory.  It may be invoked with
9705             no arguments; useful arguments include:
9706             <taglist compact="compact">
9707               <tag><tt>-uc</tt>, <tt>-us</tt></tag>
9708               <item>
9709                 <p>
9710                   Do not sign the <tt>.changes</tt> file or the
9711                   source package <tt>.dsc</tt> file, respectively.</p>
9712               </item>
9713               <tag><tt>-p<var>sign-command</var></tt></tag>
9714               <item>
9715                 <p>
9716                   Invoke <var>sign-command</var> instead of finding
9717                   <tt>gpg</tt> or <tt>pgp</tt> on the <prgn>PATH</prgn>.
9718                   <var>sign-command</var> must behave just like
9719                   <prgn>gpg</prgn> or <tt>pgp</tt>.</p>
9720               </item>
9721               <tag><tt>-r<var>root-command</var></tt></tag>
9722               <item>
9723                 <p>
9724                   When root privilege is required, invoke the command
9725                   <var>root-command</var>.  <var>root-command</var>
9726                   should invoke its first argument as a command, from
9727                   the <prgn>PATH</prgn> if necessary, and pass its
9728                   second and subsequent arguments to the command it
9729                   calls.  If no <var>root-command</var> is supplied
9730                   then <var>dpkg-buildpackage</var> will take no
9731                   special action to gain root privilege, so that for
9732                   most packages it will have to be invoked as root to
9733                   start with.</p>
9734               </item>
9735               <tag><tt>-b</tt>, <tt>-B</tt></tag>
9736               <item>
9737                 <p>
9738                   Two types of binary-only build and upload - see
9739                   <manref name="dpkg-source" section="1">.
9740                 </p>
9741               </item>
9742             </taglist>
9743           </p>
9744         </sect1>
9745
9746         <sect1 id="pkg-dpkg-gencontrol">
9747           <heading>
9748             <prgn>dpkg-gencontrol</prgn> - generates binary package
9749             control files
9750           </heading>
9751
9752           <p>
9753             This program is usually called from <file>debian/rules</file>
9754             (see <ref id="pkg-sourcetree">) in the top level of the source
9755             tree.
9756           </p>
9757
9758           <p>
9759             This is usually done just before the files and directories in the
9760             temporary directory tree where the package is being built have their
9761             permissions and ownerships set and the package is constructed using
9762             <prgn>dpkg-deb/</prgn>
9763               <footnote>
9764                 This is so that the control file which is produced has
9765                 the right permissions
9766             </footnote>.
9767           </p>
9768
9769           <p>
9770             <prgn>dpkg-gencontrol</prgn> must be called after all the
9771             files which are to go into the package have been placed in
9772             the temporary build directory, so that its calculation of
9773             the installed size of a package is correct.
9774           </p>
9775
9776           <p>
9777             It is also necessary for <prgn>dpkg-gencontrol</prgn> to
9778             be run after <prgn>dpkg-shlibdeps</prgn> so that the
9779             variable substitutions created by
9780             <prgn>dpkg-shlibdeps</prgn> in <file>debian/substvars</file>
9781             are available.
9782           </p>
9783
9784           <p>
9785             For a package which generates only one binary package, and
9786             which builds it in <file>debian/tmp</file> relative to the top
9787             of the source package, it is usually sufficient to call
9788             <prgn>dpkg-gencontrol</prgn>.
9789           </p>
9790
9791           <p>
9792             Sources which build several binaries will typically need
9793             something like:
9794             <example>
9795   dpkg-gencontrol -Pdebian/tmp-<var>pkg</var> -p<var>package</var>
9796             </example> The <tt>-P</tt> tells
9797             <prgn>dpkg-gencontrol</prgn> that the package is being
9798             built in a non-default directory, and the <tt>-p</tt>
9799             tells it which package's control file should be generated.
9800           </p>
9801
9802           <p>
9803             <prgn>dpkg-gencontrol</prgn> also adds information to the
9804             list of files in <file>debian/files</file>, for the benefit of
9805             (for example) a future invocation of
9806             <prgn>dpkg-genchanges</prgn>.</p>
9807         </sect1>
9808
9809         <sect1 id="pkg-dpkg-shlibdeps">
9810           <heading>
9811             <prgn>dpkg-shlibdeps</prgn> - calculates shared library
9812             dependencies
9813           </heading>
9814
9815           <p>
9816             This program is usually called from <file>debian/rules</file>
9817             just before <prgn>dpkg-gencontrol</prgn> (see <ref
9818             id="pkg-sourcetree">), in the top level of the source tree.
9819           </p>
9820
9821           <p>
9822             Its arguments are executables and shared libraries
9823             <footnote>
9824               <p>
9825                 They may be specified either in the locations in the
9826                 source tree where they are created or in the locations
9827                 in the temporary build tree where they are installed
9828                 prior to binary package creation.
9829               </p>
9830             </footnote> for which shared library dependencies should
9831             be included in the binary package's control file.
9832           </p>
9833
9834           <p>
9835             If some of the found shared libraries should only
9836             warrant a <tt>Recommends</tt> or <tt>Suggests</tt>, or if
9837             some warrant a <tt>Pre-Depends</tt>, this can be achieved
9838             by using the <tt>-d<var>dependency-field</var></tt> option
9839             before those executable(s).  (Each <tt>-d</tt> option
9840             takes effect until the next <tt>-d</tt>.)
9841           </p>
9842
9843           <p>
9844             <prgn>dpkg-shlibdeps</prgn> does not directly cause the
9845             output control file to be modified.  Instead by default it
9846             adds to the <file>debian/substvars</file> file variable
9847             settings like <tt>shlibs:Depends</tt>.  These variable
9848             settings must be referenced in dependency fields in the
9849             appropriate per-binary-package sections of the source
9850             control file.
9851           </p>
9852
9853           <p>
9854             For example, a package that generates an essential part
9855             which requires dependencies, and optional parts that 
9856             which only require a recommendation, would separate those
9857             two sets of dependencies into two different fields.<footnote>
9858                 At the time of writing, an example for this was the
9859                 <package/xmms/ package, with Depends used for the xmms
9860                 executable, Recommends for the plug-ins and Suggests for
9861                 even more optional features provided by unzip.
9862             </footnote>
9863             It can say in its <file>debian/rules</file>:
9864             <example>
9865   dpkg-shlibdeps -dDepends <var>program anotherprogram ...</var> \
9866                  -dRecommends <var>optionalpart anotheroptionalpart</var>
9867             </example>
9868             and then in its main control file <file>debian/control</file>:
9869             <example>
9870   <var>...</var>
9871   Depends: ${shlibs:Depends}
9872   Recommends: ${shlibs:Recommends}
9873   <var>...</var>
9874             </example>
9875           </p>
9876
9877           <p>
9878             Sources which produce several binary packages with
9879             different shared library dependency requirements can use
9880             the <tt>-p<var>varnameprefix</var></tt> option to override
9881             the default <tt>shlibs:</tt> prefix (one invocation of
9882             <prgn>dpkg-shlibdeps</prgn> per setting of this option).
9883             They can thus produce several sets of dependency
9884             variables, each of the form
9885             <tt><var>varnameprefix</var>:<var>dependencyfield</var></tt>,
9886             which can be referred to in the appropriate parts of the
9887             binary package control files.
9888           </p>
9889         </sect1>
9890
9891
9892         <sect1 id="pkg-dpkg-distaddfile">
9893           <heading>
9894             <prgn>dpkg-distaddfile</prgn> - adds a file to
9895             <file>debian/files</file>
9896           </heading>
9897
9898           <p>
9899             Some packages' uploads need to include files other than
9900             the source and binary package files.
9901           </p>
9902
9903           <p>
9904             <prgn>dpkg-distaddfile</prgn> adds a file to the
9905             <file>debian/files</file> file so that it will be included in
9906             the <file>.changes</file> file when
9907             <prgn>dpkg-genchanges</prgn> is run.
9908           </p>
9909
9910           <p>
9911             It is usually invoked from the <tt>binary</tt> target of
9912             <file>debian/rules</file>:
9913             <example>
9914   dpkg-distaddfile <var>filename</var> <var>section</var> <var>priority</var>
9915             </example>
9916             The <var>filename</var> is relative to the directory where
9917             <prgn>dpkg-genchanges</prgn> will expect to find it - this
9918             is usually the directory above the top level of the source
9919             tree.  The <file>debian/rules</file> target should put the
9920             file there just before or just after calling
9921             <prgn>dpkg-distaddfile</prgn>.
9922           </p>
9923
9924           <p>
9925             The <var>section</var> and <var>priority</var> are passed
9926             unchanged into the resulting <file>.changes</file> file.
9927           </p>
9928         </sect1>
9929
9930
9931         <sect1 id="pkg-dpkg-genchanges">
9932           <heading>
9933             <prgn>dpkg-genchanges</prgn> - generates a <file>.changes</file>
9934             upload control file
9935           </heading>
9936
9937           <p>
9938             This program is usually called by package-independent
9939             automatic building scripts such as
9940             <prgn>dpkg-buildpackage</prgn>, but it may also be called
9941             by hand.
9942           </p>
9943
9944           <p>
9945             It is usually called in the top level of a built source
9946             tree, and when invoked with no arguments will print out a
9947             straightforward <file>.changes</file> file based on the
9948             information in the source package's changelog and control
9949             file and the binary and source packages which should have
9950             been built.
9951           </p>
9952         </sect1>
9953
9954
9955         <sect1 id="pkg-dpkg-parsechangelog">
9956           <heading>
9957             <prgn>dpkg-parsechangelog</prgn> - produces parsed
9958             representation of a changelog
9959           </heading>
9960
9961           <p>
9962             This program is used internally by
9963             <prgn>dpkg-source</prgn> et al.  It may also occasionally
9964             be useful in <file>debian/rules</file> and elsewhere.  It
9965             parses a changelog, <file>debian/changelog</file> by default,
9966             and prints a control-file format representation of the
9967             information in it to standard output.
9968           </p>
9969         </sect1>
9970
9971         <sect1 id="pkg-dpkg-architecture">
9972           <heading>
9973             <prgn>dpkg-architecture</prgn> - information about the build and
9974             host system
9975           </heading>
9976
9977           <p>
9978             This program can be used manually, but is also invoked by
9979             <tt>dpkg-buildpackage</tt> or <file>debian/rules</file> to set
9980             environment or make variables which specify the build and host
9981             architecture for the package building process.
9982           </p>
9983         </sect1>
9984       </sect>
9985
9986       <sect id="pkg-sourcetree">
9987         <heading>The Debianised source tree</heading>
9988
9989         <p>
9990           The source archive scheme described later is intended to
9991           allow a Debianised source tree with some associated control
9992           information to be reproduced and transported easily.  The
9993           Debianised source tree is a version of the original program
9994           with certain files added for the benefit of the
9995           Debianisation process, and with any other changes required
9996           made to the rest of the source code and installation
9997           scripts.
9998         </p>
9999
10000         <p>
10001           The extra files created for Debian are in the subdirectory
10002           <file>debian</file> of the top level of the Debianised source
10003           tree.  They are described below.
10004         </p>
10005
10006         <sect1 id="pkg-debianrules">
10007           <heading><file>debian/rules</file> - the main building script</heading>
10008
10009           <p>
10010             See <ref id="debianrules">.
10011           </p>
10012         </sect1>
10013
10014
10015         <sect1 id="pkg-dpkgchangelog">
10016           <heading><file>debian/changelog</file></heading>
10017
10018           <p>
10019             See <ref id="dpkgchangelog">.
10020           </p>
10021
10022           <sect2><heading>Defining alternative changelog formats
10023             </heading>
10024
10025             <p>
10026               It is possible to use a different format to the standard
10027               one, by providing a parser for the format you wish to
10028               use.
10029             </p>
10030
10031             <p>
10032               In order to have <tt>dpkg-parsechangelog</tt> run your
10033               parser, you must include a line within the last 40 lines
10034               of your file matching the Perl regular expression:
10035               <tt>\schangelog-format:\s+([0-9a-z]+)\W</tt> The part in
10036               parentheses should be the name of the format.  For
10037               example, you might say:
10038               <example>
10039   @@@ changelog-format: joebloggs @@@
10040               </example>
10041               Changelog format names are non-empty strings of alphanumerics.
10042             </p>
10043
10044             <p>
10045               If such a line exists then <tt>dpkg-parsechangelog</tt>
10046               will look for the parser as
10047               <file>/usr/lib/dpkg/parsechangelog/<var>format-name</var></file>
10048               or
10049               <file>/usr/local/lib/dpkg/parsechangelog/<var>format-name</var></file>;
10050               it is an error for it not to find it, or for it not to
10051               be an executable program.  The default changelog format
10052               is <tt>dpkg</tt>, and a parser for it is provided with
10053               the <tt>dpkg</tt> package.
10054             </p>
10055
10056             <p>
10057               The parser will be invoked with the changelog open on
10058               standard input at the start of the file.  It should read
10059               the file (it may seek if it wishes) to determine the
10060               information required and return the parsed information
10061               to standard output in the form of a series of control
10062               fields in the standard format.  By default it should
10063               return information about only the most recent version in
10064               the changelog; it should accept a
10065               <tt>-v<var>version</var></tt> option to return changes
10066               information from all versions present <em>strictly
10067               after</em> <var>version</var>, and it should then be an
10068               error for <var>version</var> not to be present in the
10069               changelog.
10070             </p>
10071
10072             <p>
10073               The fields are:
10074               <list compact="compact">
10075                 <item><qref id="f-Source"><tt>Source</tt></qref></item>
10076                 <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
10077                 <item><qref id="f-Distribution"><tt>Distribution</tt></qref> (mandatory)</item>
10078                 <item><qref id="f-Urgency"><tt>Urgency</tt></qref> (mandatory)</item>
10079                 <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
10080                 <item><qref id="f-Date"><tt>Date</tt></qref></item>
10081                 <item><qref id="f-Changes"><tt>Changes</tt></qref> (mandatory)</item>
10082               </list>
10083             </p>
10084
10085             <p>
10086               If several versions are being returned (due to the use
10087               of <tt>-v</tt>), the urgency value should be of the
10088               highest urgency code listed at the start of any of the
10089               versions requested followed by the concatenated
10090               (space-separated) comments from all the versions
10091               requested; the maintainer, version, distribution and
10092               date should always be from the most recent version.
10093             </p>
10094
10095             <p>
10096               For the format of the <tt>Changes</tt> field see
10097               <ref id="f-Changes">.
10098             </p>
10099
10100             <p>
10101               If the changelog format which is being parsed always or
10102               almost always leaves a blank line between individual
10103               change notes these blank lines should be stripped out,
10104               so as to make the resulting output compact.
10105             </p>
10106
10107             <p>
10108               If the changelog format does not contain date or package
10109               name information this information should be omitted from
10110               the output.  The parser should not attempt to synthesize
10111               it or find it from other sources.
10112             </p>
10113
10114             <p>
10115               If the changelog does not have the expected format the
10116               parser should exit with a nonzero exit status, rather
10117               than trying to muddle through and possibly generating
10118               incorrect output.
10119             </p>
10120
10121             <p>
10122               A changelog parser may not interact with the user at
10123               all.
10124             </p>
10125           </sect2>
10126         </sect1>
10127
10128         <sect1 id="pkg-srcsubstvars">
10129           <heading><file>debian/substvars</file> and variable substitutions</heading>
10130
10131           <p>
10132             See <ref id="substvars">.
10133           </p>
10134
10135         </sect1>
10136
10137         <sect1>
10138           <heading><file>debian/files</file></heading>
10139
10140           <p>
10141             See <ref id="debianfiles">.
10142           </p>
10143         </sect1>
10144
10145         <sect1><heading><file>debian/tmp</file>
10146           </heading>
10147
10148           <p>
10149             This is the canonical temporary location for the
10150             construction of binary packages by the <tt>binary</tt>
10151             target.  The directory <file>tmp</file> serves as the root of
10152             the file system tree as it is being constructed (for
10153             example, by using the package's upstream makefiles install
10154             targets and redirecting the output there), and it also
10155             contains the <tt>DEBIAN</tt> subdirectory.  See <ref
10156             id="pkg-bincreating">.
10157           </p>
10158
10159           <p>
10160             If several binary packages are generated from the same
10161             source tree it is usual to use several
10162             <file>debian/tmp<var>something</var></file> directories, for
10163             example <file>tmp-a</file> or <file>tmp-doc</file>.
10164           </p>
10165
10166           <p>
10167             Whatever <file>tmp</file> directories are created and used by
10168             <tt>binary</tt> must of course be removed by the
10169             <tt>clean</tt> target.</p></sect1>
10170       </sect>
10171
10172
10173       <sect id="pkg-sourcearchives"><heading>Source packages as archives
10174         </heading>
10175
10176         <p>
10177           As it exists on the FTP site, a Debian source package
10178           consists of three related files.  You must have the right
10179           versions of all three to be able to use them.
10180         </p>
10181
10182         <p>
10183           <taglist>
10184             <tag>Debian source control file - <tt>.dsc</tt></tag>
10185             <item>
10186                 This file is a control file used by <prgn>dpkg-source</prgn>
10187                 to extract a source package.
10188                 See <ref id="debiansourcecontrolfiles">.
10189             </item>
10190
10191             <tag>
10192               Original source archive -
10193               <file>
10194                 <var>package</var>_<var>upstream-version</var>.orig.tar.gz
10195               </file>
10196             </tag>
10197
10198             <item>
10199               <p>
10200                 This is a compressed (with <tt>gzip -9</tt>)
10201                 <prgn>tar</prgn> file containing the source code from
10202                 the upstream authors of the program.
10203               </p>
10204             </item>
10205
10206             <tag>
10207               Debianisation diff -
10208               <file>
10209                 <var>package</var>_<var>upstream_version-revision</var>.diff.gz
10210               </file>
10211             </tag>
10212             <item>
10213
10214               <p>
10215                 This is a unified context diff (<tt>diff -u</tt>)
10216                 giving the changes which are required to turn the
10217                 original source into the Debian source.  These changes
10218                 may only include editing and creating plain files.
10219                 The permissions of files, the targets of symbolic
10220                 links and the characteristics of special files or
10221                 pipes may not be changed and no files may be removed
10222                 or renamed.
10223               </p>
10224
10225               <p>
10226                 All the directories in the diff must exist, except the
10227                 <file>debian</file> subdirectory of the top of the source
10228                 tree, which will be created by
10229                 <prgn>dpkg-source</prgn> if necessary when unpacking.
10230               </p>
10231
10232               <p>
10233                 The <prgn>dpkg-source</prgn> program will
10234                 automatically make the <file>debian/rules</file> file
10235                 executable (see below).</p></item>
10236           </taglist>
10237         </p>
10238
10239         <p>
10240           If there is no original source code - for example, if the
10241           package is specially prepared for Debian or the Debian
10242           maintainer is the same as the upstream maintainer - the
10243           format is slightly different: then there is no diff, and the
10244           tarfile is named
10245           <file><var>package</var>_<var>version</var>.tar.gz</file>,
10246           and preferably contains a directory named
10247           <file><var>package</var>-<var>version</var></file>.
10248         </p>
10249       </sect>
10250
10251       <sect>
10252         <heading>Unpacking a Debian source package without <prgn>dpkg-source</prgn></heading>
10253
10254         <p>
10255           <tt>dpkg-source -x</tt> is the recommended way to unpack a
10256           Debian source package.  However, if it is not available it
10257           is possible to unpack a Debian source archive as follows:
10258         <enumlist compact="compact">
10259           <item>
10260             <p>
10261               Untar the tarfile, which will create a <file>.orig</file>
10262               directory.</p>
10263           </item>
10264           <item>
10265             <p>Rename the <file>.orig</file> directory to
10266               <file><var>package</var>-<var>version</var></file>.</p>
10267           </item>
10268             <item>
10269             <p>
10270               Create the subdirectory <file>debian</file> at the top of
10271               the source tree.</p>
10272           </item>
10273           <item><p>Apply the diff using <tt>patch -p0</tt>.</p>
10274           </item>
10275           <item><p>Untar the tarfile again if you want a copy of the original
10276               source code alongside the Debianised version.</p>
10277           </item>
10278         </enumlist>
10279
10280         <p>
10281           It is not possible to generate a valid Debian source archive
10282           without using <prgn>dpkg-source</prgn>.  In particular,
10283           attempting to use <prgn>diff</prgn> directly to generate the
10284           <file>.diff.gz</file> file will not work.
10285         </p>
10286
10287         <sect1>
10288           <heading>Restrictions on objects in source packages</heading>
10289
10290           <p>
10291             The source package may not contain any hard links
10292             <footnote>
10293                 This is not currently detected when building source
10294                 packages, but only when extracting
10295                 them.
10296             </footnote>
10297             <footnote>
10298                 Hard links may be permitted at some point in the
10299                 future, but would require a fair amount of
10300                 work.
10301             </footnote>, device special files, sockets or setuid or
10302             setgid files.
10303             <footnote>
10304                 Setgid directories are allowed.
10305             </footnote>
10306           </p>
10307
10308           <p>
10309             The source packaging tools manage the changes between the
10310             original and Debianised source using <prgn>diff</prgn> and
10311             <prgn>patch</prgn>.  Turning the original source tree as
10312             included in the <file>.orig.tar.gz</file> into the debianised
10313             source must not involve any changes which cannot be
10314             handled by these tools.  Problematic changes which cause
10315             <prgn>dpkg-source</prgn> to halt with an error when
10316             building the source package are:
10317             <list compact="compact">
10318               <item><p>Adding or removing symbolic links, sockets or pipes.</p>
10319               </item>
10320               <item><p>Changing the targets of symbolic links.</p>
10321               </item>
10322               <item><p>Creating directories, other than <file>debian</file>.</p>
10323               </item>
10324               <item><p>Changes to the contents of binary files.</p></item>
10325             </list> Changes which cause <prgn>dpkg-source</prgn> to
10326             print a warning but continue anyway are:
10327             <list compact="compact">
10328               <item>
10329                 <p>
10330                   Removing files, directories or symlinks.
10331                   <footnote>
10332                       Renaming a file is not treated specially - it is
10333                       seen as the removal of the old file (which
10334                       generates a warning, but is otherwise ignored),
10335                       and the creation of the new one.
10336                   </footnote>
10337                 </p>
10338               </item>
10339               <item>
10340                 <p>
10341                   Changed text files which are missing the usual final
10342                   newline (either in the original or the modified
10343                   source tree).
10344                 </p>
10345               </item>
10346             </list>
10347             Changes which are not represented, but which are not detected by
10348             <prgn>dpkg-source</prgn>, are:
10349             <list compact="compact">
10350               <item><p>Changing the permissions of files (other than
10351                   <file>debian/rules</file>) and directories.</p></item>
10352             </list>
10353           </p>
10354
10355           <p>
10356             The <file>debian</file> directory and <file>debian/rules</file>
10357             are handled specially by <prgn>dpkg-source</prgn> - before
10358             applying the changes it will create the <file>debian</file>
10359             directory, and afterwards it will make
10360             <file>debian/rules</file> world-executable.
10361           </p>
10362         </sect1>
10363       </sect>
10364     </appendix>
10365
10366     <appendix id="pkg-controlfields">
10367       <heading>Control files and their fields (from old Packaging Manual)</heading>
10368
10369       <p>
10370         Many of the tools in the <prgn>dpkg</prgn> suite manipulate
10371         data in a common format, known as control files.  Binary and
10372         source packages have control data as do the <file>.changes</file>
10373         files which control the installation of uploaded files, and
10374         <prgn>dpkg</prgn>'s internal databases are in a similar
10375         format.
10376       </p>
10377
10378       <sect>
10379         <heading>Syntax of control files</heading>
10380
10381         <p>
10382           See <ref id="controlsyntax">.
10383         </p>
10384
10385         <p>
10386           It is important to note that there are several fields which
10387           are optional as far as <prgn>dpkg</prgn> and the related
10388           tools are concerned, but which must appear in every Debian
10389           package, or whose omission may cause problems.
10390         </p>
10391       </sect>
10392
10393       <sect>
10394         <heading>List of fields</heading>
10395
10396         <p>
10397           See <ref id="controlfieldslist">.
10398         </p>
10399
10400         <p>
10401           This section now contains only the fields that didn't belong
10402           to the Policy manual.
10403         </p>
10404
10405         <sect1 id="pkg-f-Filename">
10406           <heading><tt>Filename</tt> and <tt>MSDOS-Filename</tt></heading>
10407
10408           <p>
10409             These fields in <tt>Packages</tt> files give the
10410             filename(s) of (the parts of) a package in the
10411             distribution directories, relative to the root of the
10412             Debian hierarchy.  If the package has been split into
10413             several parts the parts are all listed in order, separated
10414             by spaces.
10415           </p>
10416         </sect1>
10417
10418         <sect1 id="pkg-f-Size">
10419           <heading><tt>Size</tt> and <tt>MD5sum</tt></heading>
10420
10421           <p>
10422             These fields in <file>Packages</file> files give the size (in
10423             bytes, expressed in decimal) and MD5 checksum of the
10424             file(s) which make(s) up a binary package in the
10425             distribution.  If the package is split into several parts
10426             the values for the parts are listed in order, separated by
10427             spaces.
10428           </p>
10429         </sect1>
10430
10431         <sect1 id="pkg-f-Status">
10432           <heading><tt>Status</tt></heading>
10433
10434           <p>
10435             This field in <prgn>dpkg</prgn>'s status file records
10436             whether the user wants a package installed, removed or
10437             left alone, whether it is broken (requiring
10438             re-installation) or not and what its current state on the
10439             system is.  Each of these pieces of information is a
10440             single word.
10441           </p>
10442         </sect1>
10443
10444         <sect1 id="pkg-f-Config-Version">
10445           <heading><tt>Config-Version</tt></heading>
10446
10447           <p>
10448             If a package is not installed or not configured, this
10449             field in <prgn>dpkg</prgn>'s status file records the last
10450             version of the package which was successfully
10451             configured.
10452           </p>
10453         </sect1>
10454
10455         <sect1 id="pkg-f-Conffiles">
10456           <heading><tt>Conffiles</tt></heading>
10457
10458           <p>
10459             This field in <prgn>dpkg</prgn>'s status file contains
10460             information about the automatically-managed configuration
10461             files held by a package.  This field should <em>not</em>
10462             appear anywhere in a package!
10463           </p>
10464         </sect1>
10465
10466         <sect1>
10467           <heading>Obsolete fields</heading>
10468
10469           <p>
10470             These are still recognized by <prgn>dpkg</prgn> but should
10471             not appear anywhere any more.
10472
10473             <taglist compact="compact">
10474
10475               <tag><tt>Revision</tt></tag>
10476               <tag><tt>Package-Revision</tt></tag>
10477               <tag><tt>Package_Revision</tt></tag>
10478               <item>
10479                   The Debian revision part of the package version was
10480                   at one point in a separate control file field.  This
10481                   field went through several names.
10482               </item>
10483
10484               <tag><tt>Recommended</tt></tag>
10485               <item>Old name for <tt>Recommends</tt>.</item>
10486
10487               <tag><tt>Optional</tt></tag>
10488               <item>Old name for <tt>Suggests</tt>.</item>
10489
10490               <tag><tt>Class</tt></tag>
10491               <item>Old name for <tt>Priority</tt>.</item>
10492
10493             </taglist>
10494           </p>
10495         </sect1>
10496       </sect>
10497
10498     </appendix>
10499
10500     <appendix id="pkg-conffiles">
10501       <heading>Configuration file handling (from old Packaging Manual)</heading>
10502
10503       <p>
10504         <prgn>dpkg</prgn> can do a certain amount of automatic
10505         handling of package configuration files.
10506       </p>
10507
10508       <p>
10509         Whether this mechanism is appropriate depends on a number of
10510         factors, but basically there are two approaches to any
10511         particular configuration file.
10512       </p>
10513
10514       <p>
10515         The easy method is to ship a best-effort configuration in the
10516         package, and use <prgn>dpkg</prgn>'s conffile mechanism to
10517         handle updates.  If the user is unlikely to want to edit the
10518         file, but you need them to be able to without losing their
10519         changes, and a new package with a changed version of the file
10520         is only released infrequently, this is a good approach.
10521       </p>
10522
10523       <p>
10524         The hard method is to build the configuration file from
10525         scratch in the <prgn>postinst</prgn> script, and to take the
10526         responsibility for fixing any mistakes made in earlier
10527         versions of the package automatically.  This will be
10528         appropriate if the file is likely to need to be different on
10529         each system.
10530       </p>
10531
10532       <sect><heading>Automatic handling of configuration files by
10533       <prgn>dpkg</prgn>
10534         </heading>
10535
10536         <p>
10537           A package may contain a control area file called
10538           <tt>conffiles</tt>.  This file should be a list of filenames
10539           of configuration files needing automatic handling, separated
10540           by newlines.  The filenames should be absolute pathnames,
10541           and the files referred to should actually exist in the
10542           package.
10543         </p>
10544
10545         <p>
10546           When a package is upgraded <prgn>dpkg</prgn> will process
10547           the configuration files during the configuration stage,
10548           shortly before it runs the package's <prgn>postinst</prgn>
10549           script,
10550         </p>
10551
10552         <p>
10553           For each file it checks to see whether the version of the
10554           file included in the package is the same as the one that was
10555           included in the last version of the package (the one that is
10556           being upgraded from); it also compares the version currently
10557           installed on the system with the one shipped with the last
10558           version.
10559         </p>
10560
10561         <p>
10562           If neither the user nor the package maintainer has changed
10563           the file, it is left alone.  If one or the other has changed
10564           their version, then the changed version is preferred - i.e.,
10565           if the user edits their file, but the package maintainer
10566           doesn't ship a different version, the user's changes will
10567           stay, silently, but if the maintainer ships a new version
10568           and the user hasn't edited it the new version will be
10569           installed (with an informative message).  If both have
10570           changed their version the user is prompted about the problem
10571           and must resolve the differences themselves.
10572         </p>
10573
10574         <p>
10575           The comparisons are done by calculating the MD5 message
10576           digests of the files, and storing the MD5 of the file as it
10577           was included in the most recent version of the package.
10578         </p>
10579
10580         <p>
10581           When a package is installed for the first time
10582           <prgn>dpkg</prgn> will install the file that comes with it,
10583           unless that would mean overwriting a file already on the
10584           file system.
10585         </p>
10586
10587         <p>
10588           However, note that <prgn>dpkg</prgn> will <em>not</em>
10589           replace a conffile that was removed by the user (or by a
10590           script).  This is necessary because with some programs a
10591           missing file produces an effect hard or impossible to
10592           achieve in another way, so that a missing file needs to be
10593           kept that way if the user did it.
10594         </p>
10595
10596         <p>
10597           Note that a package should <em>not</em> modify a
10598           <prgn>dpkg</prgn>-handled conffile in its maintainer
10599           scripts.  Doing this will lead to <prgn>dpkg</prgn> giving
10600           the user confusing and possibly dangerous options for
10601           conffile update when the package is upgraded.</p>
10602       </sect>
10603
10604       <sect><heading>Fully-featured maintainer script configuration
10605       handling
10606         </heading>
10607
10608         <p>
10609           For files which contain site-specific information such as
10610           the hostname and networking details and so forth, it is
10611           better to create the file in the package's
10612           <prgn>postinst</prgn> script.
10613         </p>
10614
10615         <p>
10616           This will typically involve examining the state of the rest
10617           of the system to determine values and other information, and
10618           may involve prompting the user for some information which
10619           can't be obtained some other way.
10620         </p>
10621
10622         <p>
10623           When using this method there are a couple of important
10624           issues which should be considered:
10625         </p>
10626
10627         <p>
10628           If you discover a bug in the program which generates the
10629           configuration file, or if the format of the file changes
10630           from one version to the next, you will have to arrange for
10631           the postinst script to do something sensible - usually this
10632           will mean editing the installed configuration file to remove
10633           the problem or change the syntax.  You will have to do this
10634           very carefully, since the user may have changed the file,
10635           perhaps to fix the very problem that your script is trying
10636           to deal with - you will have to detect these situations and
10637           deal with them correctly.
10638         </p>
10639
10640         <p>
10641           If you do go down this route it's probably a good idea to
10642           make the program that generates the configuration file(s) a
10643           separate program in <file>/usr/sbin</file>, by convention called
10644           <file><var>package</var>config</file> and then run that if
10645           appropriate from the post-installation script.  The
10646           <tt><var>package</var>config</tt> program should not
10647           unquestioningly overwrite an existing configuration - if its
10648           mode of operation is geared towards setting up a package for
10649           the first time (rather than any arbitrary reconfiguration
10650           later) you should have it check whether the configuration
10651           already exists, and require a <tt>--force</tt> flag to
10652           overwrite it.</p></sect>
10653     </appendix>
10654
10655     <appendix id="pkg-alternatives"><heading>Alternative versions of
10656         an interface - <prgn>update-alternatives</prgn> (from old
10657     Packaging Manual)
10658       </heading>
10659
10660       <p>
10661         When several packages all provide different versions of the
10662         same program or file it is useful to have the system select a
10663         default, but to allow the system administrator to change it
10664         and have their decisions respected.
10665       </p>
10666
10667       <p>
10668         For example, there are several versions of the <prgn>vi</prgn>
10669         editor, and there is no reason to prevent all of them from
10670         being installed at once, each under their own name
10671         (<prgn>nvi</prgn>, <prgn>vim</prgn> or whatever).
10672         Nevertheless it is desirable to have the name <tt>vi</tt>
10673         refer to something, at least by default.
10674       </p>
10675
10676       <p>
10677         If all the packages involved cooperate, this can be done with
10678         <prgn>update-alternatives</prgn>.
10679       </p>
10680
10681       <p>
10682         Each package provides its own version under its own name, and
10683         calls <prgn>update-alternatives</prgn> in its postinst to
10684         register its version (and again in its prerm to deregister
10685         it).
10686       </p>
10687
10688       <p>
10689         See the man page <manref name="update-alternatives"
10690         section="8"> for details.
10691       </p>
10692
10693       <p>
10694         If <prgn>update-alternatives</prgn> does not seem appropriate
10695         you may wish to consider using diversions instead.</p>
10696     </appendix>
10697
10698     <appendix id="pkg-diversions"><heading>Diversions - overriding a
10699     package's version of a file (from old Packaging Manual)
10700       </heading>
10701
10702       <p>
10703         It is possible to have <prgn>dpkg</prgn> not overwrite a file
10704         when it reinstalls the package it belongs to, and to have it
10705         put the file from the package somewhere else instead.
10706       </p>
10707
10708       <p>
10709         This can be used locally to override a package's version of a
10710         file, or by one package to override another's version (or
10711         provide a wrapper for it).
10712       </p>
10713
10714       <p>
10715         Before deciding to use a diversion, read <ref
10716         id="pkg-alternatives"> to see if you really want a diversion
10717         rather than several alternative versions of a program.
10718       </p>
10719
10720       <p>
10721         There is a diversion list, which is read by <prgn>dpkg</prgn>,
10722         and updated by a special program <prgn>dpkg-divert</prgn>.
10723         Please see <manref name="dpkg-divert" section="8"> for full
10724         details of its operation.
10725       </p>
10726
10727       <p>
10728         When a package wishes to divert a file from another, it should
10729         call <prgn>dpkg-divert</prgn> in its preinst to add the
10730         diversion and rename the existing file.  For example,
10731         supposing that a <prgn>smailwrapper</prgn> package wishes to
10732         install a wrapper around <file>/usr/sbin/smail</file>:
10733         <example>
10734    dpkg-divert --package smailwrapper --add --rename \
10735       --divert /usr/sbin/smail.real /usr/sbin/smail
10736         </example> The <tt>--package smailwrapper</tt> ensures that
10737         <prgn>smailwrapper</prgn>'s copy of <file>/usr/sbin/smail</file>
10738         can bypass the diversion and get installed as the true version.
10739         It's safe to add the diversion unconditionally on upgrades since
10740         it will be left unchanged if it already exists, but
10741         <prgn>dpkg-divert</prgn> will display a message.  To suppress that
10742         message, make the command conditional on the version from which
10743         the package is being upgraded:
10744         <example>
10745    if [ upgrade != "$1" ] || dpkg --compare-versions "$2" lt 1.0-2; then
10746       dpkg-divert --package smailwrapper --add --rename \
10747          --divert /usr/sbin/smail.real /usr/sbin/smail
10748    fi
10749         </example> where <tt>1.0-2</tt> is the version at which the
10750         diversion was first added to the package.  Running the command
10751         during abort-upgrade is pointless but harmless.
10752       </p>
10753
10754       <p>
10755         The postrm has to do the reverse:
10756         <example>
10757   if [ remove = "$1" -o abort-install = "$1" -o disappear = "$1" ]; then
10758      dpkg-divert --package smailwrapper --remove --rename \
10759         --divert /usr/sbin/smail.real /usr/sbin/smail
10760   fi
10761         </example> If the diversion was added at a particular version, the
10762         postrm should also handle the failure case of upgrading from an
10763         older version (unless the older version is so old that direct
10764         upgrades are no longer supported):
10765         <example>
10766   if [ abort-upgrade = "$1" ] && dpkg --compare-versions "$2" lt 1.0-2; then
10767      dpkg-divert --package smailwrapper --remove --rename \
10768         --divert /usr/sbin/smail.real /usr/sbin/smail
10769   fi
10770         </example> where <tt>1.02-2</tt> is the version at which the
10771         diversion was first added to the package.  The postrm should not
10772         remove the diversion on upgrades both because there's no reason to
10773         remove the diversion only to immediately re-add it and since the
10774         postrm of the old package is run after unpacking so the removal of
10775         the diversion will fail.
10776       </p>
10777
10778       <p>
10779         Do not attempt to divert a file which is vitally important for
10780         the system's operation - when using <prgn>dpkg-divert</prgn>
10781         there is a time, after it has been diverted but before
10782         <prgn>dpkg</prgn> has installed the new version, when the file
10783         does not exist.</p>
10784     </appendix>
10785
10786   </book>
10787 </debiandoc>
10788 <!-- Local variables: -->
10789 <!-- indent-tabs-mode: t -->
10790 <!-- End: -->
10791 <!-- vim:set ai et sts=2 sw=2 tw=76: -->