]> git.donarmstrong.com Git - debian/debian-policy.git/blob - policy.sgml
Merge branch 'master' into bug504880-rra
[debian/debian-policy.git] / policy.sgml
1 <!doctype debiandoc system [
2 <!-- include version information so we don't have to hard code it
3      within the document -->
4 <!entity % versiondata SYSTEM "version.ent"> %versiondata;
5 ]>
6 <debiandoc>
7
8   <book>
9     <titlepag>
10       <title>Debian Policy Manual</title>
11       <author><qref id="authors">The Debian Policy Mailing List</qref></author>
12       <version>version &version;, &date;</version>
13
14       <abstract>
15         This manual describes the policy requirements for the Debian
16         GNU/Linux distribution.  This includes the structure and
17         contents of the Debian archive and several design issues of
18         the operating system, as well as technical requirements that
19         each package must satisfy to be included in the distribution.
20       </abstract>
21
22       <copyright>
23         <copyrightsummary>
24           Copyright &copy; 1996,1997,1998 Ian Jackson
25           and Christian Schwarz.
26         </copyrightsummary>
27         <p>
28           These are the copyright dates of the original Policy manual.
29           Since then, this manual has been updated by many others.  No
30           comprehensive collection of copyright notices for subsequent
31           work exists.
32         </p>
33
34         <p>
35           This manual is free software; you may redistribute it and/or
36           modify it under the terms of the GNU General Public License
37           as published by the Free Software Foundation; either version
38           2, or (at your option) any later version.
39         </p>
40
41         <p>
42           This is distributed in the hope that it will be useful, but
43           <em>without any warranty</em>; without even the implied
44           warranty of merchantability or fitness for a particular
45           purpose.  See the GNU General Public License for more
46           details.
47         </p>
48
49         <p>
50           A copy of the GNU General Public License is available as
51           <file>/usr/share/common-licenses/GPL</file> in the Debian GNU/Linux
52           distribution or on the World Wide Web at
53           <url id="http://www.gnu.org/copyleft/gpl.html"
54                name="the GNU General Public Licence">. You can also
55           obtain it by writing to the Free Software Foundation, Inc.,
56           51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
57         </p>
58       </copyright>
59     </titlepag>
60
61     <toc detail="sect1">
62
63     <chapt id="scope">
64       <heading>About this manual</heading>
65       <sect>
66         <heading>Scope</heading>
67         <p>
68           This manual describes the policy requirements for the Debian
69           GNU/Linux distribution. This includes the structure and
70           contents of the Debian archive and several design issues of the
71           operating system, as well as technical requirements that
72           each package must satisfy to be included in the
73           distribution.
74         </p>
75
76         <p>
77           This manual also describes Debian policy as it relates to
78           creating Debian packages. It is not a tutorial on how to build
79           packages, nor is it exhaustive where it comes to describing
80           the behavior of the packaging system. Instead, this manual
81           attempts to define the interface to the package management
82           system that the developers have to be conversant with.<footnote>
83               Informally, the criteria used for inclusion is that the
84               material meet one of the following requirements:
85               <taglist compact="compact">
86                 <tag>Standard interfaces</tag>
87                 <item>
88                     The material presented represents an interface to
89                     the packaging system that is mandated for use, and
90                     is used by, a significant number of packages, and
91                     therefore should not be changed without peer
92                     review. Package maintainers can then rely on this
93                     interfaces not changing, and the package
94                     management software authors need to ensure
95                     compatibility with these interface
96                     definitions. (Control file and changelog file
97                     formats are examples.)
98                 </item>
99                 <tag>Chosen Convention</tag>
100                 <item>
101                     If there are a number of technically viable choices
102                     that can be made, but one needs to select one of
103                     these options for inter-operability. The version
104                     number format is one example.
105                 </item>
106               </taglist>
107               Please note that these are not mutually exclusive;
108               selected conventions often become parts of standard
109               interfaces.
110           </footnote>
111         </p>
112
113         <p>
114           The footnotes present in this manual are
115           merely informative, and are not part of Debian policy itself.
116         </p>
117
118         <p>
119           The appendices to this manual are not necessarily normative,
120           either. Please see <ref id="pkg-scope"> for more information.
121         </p>
122
123         <p>
124           In the normative part of this manual,
125           the words <em>must</em>, <em>should</em> and
126           <em>may</em>, and the adjectives <em>required</em>,
127           <em>recommended</em> and <em>optional</em>, are used to
128           distinguish the significance of the various guidelines in
129           this policy document. Packages that do not conform to the
130           guidelines denoted by <em>must</em> (or <em>required</em>)
131           will generally not be considered acceptable for the Debian
132           distribution. Non-conformance with guidelines denoted by
133           <em>should</em> (or <em>recommended</em>) will generally be
134           considered a bug, but will not necessarily render a package
135           unsuitable for distribution. Guidelines denoted by
136           <em>may</em> (or <em>optional</em>) are truly optional and
137           adherence is left to the maintainer's discretion.
138         </p>
139
140         <p>
141           These classifications are roughly equivalent to the bug
142           severities <em>serious</em> (for <em>must</em> or
143           <em>required</em> directive violations), <em>minor</em>,
144           <em>normal</em> or <em>important</em>
145           (for <em>should</em> or <em>recommended</em> directive
146           violations) and <em>wishlist</em> (for <em>optional</em>
147           items).
148           <footnote>
149                 Compare RFC 2119.  Note, however, that these words are
150                 used in a different way in this document.
151           </footnote>
152         </p>
153
154         <p>
155           Much of the information presented in this manual will be
156           useful even when building a package which is to be
157           distributed in some other way or is intended for local use
158           only.
159         </p>
160       </sect>
161
162       <sect>
163         <heading>New versions of this document</heading>
164
165         <p>
166           This manual is distributed via the Debian package
167           <package><url name="debian-policy"
168               id="http://packages.debian.org/debian-policy"></package> 
169           (<httpsite>packages.debian.org</httpsite> 
170           <httppath>/debian-policy</httppath>).
171         </p>
172
173         <p>
174           The current version of this document is also available from
175           the Debian web mirrors at
176           <tt><url name="/doc/debian-policy/"
177                 id="http://www.debian.org/doc/debian-policy/"></tt>.
178           (
179           <httpsite>www.debian.org</httpsite>
180           <httppath>/doc/debian-policy/</httppath>)
181           Also available from the same directory are several other
182           formats: <file>policy.html.tar.gz</file>
183           (<httppath>/doc/debian-policy/policy.html.tar.gz</httppath>),
184           <file>policy.pdf.gz</file> 
185           (<httppath>/doc/debian-policy/policy.pdf.gz</httppath>)
186           and <file>policy.ps.gz</file>
187           (<httppath>/doc/debian-policy/policy.ps.gz</httppath>).
188         </p>
189
190         <p>
191           The <package>debian-policy</package> package also includes the file
192           <file>upgrading-checklist.txt.gz</file> which indicates policy
193           changes between versions of this document.
194         </p>
195       </sect>
196
197       <sect id="authors">
198         <heading>Authors and Maintainers</heading>
199
200         <p>
201           Originally called "Debian GNU/Linux Policy Manual", this
202           manual was initially written in 1996 by Ian Jackson.
203           It was revised on November 27th, 1996 by David A. Morris.
204           Christian Schwarz added new sections on March 15th, 1997,
205           and reworked/restructured it in April-July 1997.
206           Christoph Lameter contributed the "Web Standard".
207           Julian Gilbey largely restructured it in 2001.
208         </p>
209
210         <p>
211           Since September 1998, the responsibility for the contents of
212           this document lies on the <url name="debian-policy mailing list"
213           id="mailto:debian-policy@lists.debian.org">. Proposals
214           are discussed there and inserted into policy after a certain
215           consensus is established.
216           <!-- insert shameless policy-process plug here eventually -->
217           The actual editing is done by a group of maintainers that have
218           no editorial powers. These are the current maintainers:
219
220           <enumlist>
221             <item>Julian Gilbey</item>
222             <item>Branden Robinson</item>
223             <item>Josip Rodin</item>
224             <item>Manoj Srivastava</item>
225           </enumlist>
226         </p>
227
228         <p>
229           While the authors of this document have tried hard to avoid
230           typos and other errors, these do still occur. If you discover
231           an error in this manual or if you want to give any
232           comments, suggestions, or criticisms please send an email to
233           the Debian Policy List,
234           <email>debian-policy@lists.debian.org</email>, or submit a
235           bug report against the <tt>debian-policy</tt> package.
236         </p>
237
238         <p>
239           Please do not try to reach the individual authors or maintainers
240           of the Policy Manual regarding changes to the Policy.
241         </p>
242       </sect>
243
244       <sect id="related">
245         <heading>Related documents</heading>
246
247         <p>
248           There are several other documents other than this Policy Manual
249           that are necessary to fully understand some Debian policies and
250           procedures.
251         </p>
252
253         <p>
254           The external "sub-policy" documents are referred to in:
255           <list compact="compact">
256             <item><ref id="fhs"></item>
257             <item><ref id="virtual_pkg"></item>
258             <item><ref id="menus"></item>
259             <item><ref id="mime"></item>
260             <item><ref id="perl"></item>
261             <item><ref id="maintscriptprompt"></item>
262             <item><ref id="emacs"></item>
263           </list>
264         </p>
265
266         <p>
267           In addition to those, which carry the weight of policy, there
268           is the Debian Developer's Reference. This document describes
269           procedures and resources for Debian developers, but it is
270           <em>not</em> normative; rather, it includes things that don't
271           belong in the Policy, such as best practices for developers.
272         </p>
273
274         <p>
275           The Developer's Reference is available in the
276           <package>developers-reference</package> package.
277           It's also available from the Debian web mirrors at
278           <tt><url name="/doc/developers-reference/"
279                 id="http://www.debian.org/doc/developers-reference/"></tt>.
280         </p>
281       </sect>
282
283       <sect id="definitions">
284         <heading>Definitions</heading>
285
286         <p>
287           The following terms are used in this Policy Manual:
288           <taglist>
289             <tag>ASCII</tag>
290             <item>
291               The character encoding specified by ANSI X3.4-1986 and its
292               predecessor standards, referred to in MIME as US-ASCII, and
293               corresponding to an encoding in eight bits per character of
294               the first 128 <url id="http://www.unicode.org/"
295               name="Unicode"> characters, with the eighth bit always zero.
296             </item>
297             <tag>UTF-8</tag>
298             <item>
299               The transformation format (sometimes called encoding) of
300               <url id="http://www.unicode.org/" name="Unicode"> defined by
301               <url id="http://www.rfc-editor.org/rfc/rfc3629.txt"
302               name="RFC 3629">.  UTF-8 has the useful property of having
303               ASCII as a subset, so any text encoded in ASCII is trivially
304               also valid UTF-8.
305             </item>
306           </taglist>
307         </p>
308       </sect>
309     </chapt>
310
311
312     <chapt id="archive">
313       <heading>The Debian Archive</heading>
314
315       <p>
316         The Debian GNU/Linux system is maintained and distributed as a
317         collection of <em>packages</em>. Since there are so many of
318         them (currently well over 15000), they are split into
319         <em>sections</em> and given <em>priorities</em> to simplify
320         the handling of them.
321       </p>
322
323       <p>
324         The effort of the Debian project is to build a free operating
325         system, but not every package we want to make accessible is
326         <em>free</em> in our sense (see the Debian Free Software
327         Guidelines, below), or may be imported/exported without
328         restrictions. Thus, the archive is split into areas<footnote>
329           The Debian archive software uses the term "component" internally
330           and in the Release file format to refer to the division of an
331           archive.  The Debian Social Contract simply refers to "areas."
332           This document uses terminology similar to the Social Contract.
333         </footnote> based on their licenses and other restrictions.
334       </p>
335
336       <p>
337         The aims of this are:
338
339         <list compact="compact">
340           <item>to allow us to make as much software available as we can</item>
341           <item>to allow us to encourage everyone to write free software,
342                 and</item>
343           <item>to allow us to make it easy for people to produce
344                 CD-ROMs of our system without violating any licenses,
345                 import/export restrictions, or any other laws.</item>
346         </list>
347       </p>
348
349       <p>
350         The <em>main</em> archive area forms the <em>Debian GNU/Linux
351         distribution</em>.
352       </p>
353
354       <p>
355         Packages in the other archive areas (<tt>contrib</tt>,
356         <tt>non-free</tt>) are not considered to be part of the Debian
357         distribution, although we support their use and provide
358         infrastructure for them (such as our bug-tracking system and
359         mailing lists). This Debian Policy Manual applies to these
360         packages as well.
361       </p>
362
363       <sect id="dfsg">
364         <heading>The Debian Free Software Guidelines</heading>
365         <p>
366           The Debian Free Software Guidelines (DFSG) form our
367           definition of "free software".  These are:
368             <taglist>
369               <tag>Free Redistribution
370               </tag>
371               <item>
372                   The license of a Debian component may not restrict any
373                   party from selling or giving away the software as a
374                   component of an aggregate software distribution
375                   containing programs from several different
376                   sources. The license may not require a royalty or
377                   other fee for such sale.
378               </item>
379               <tag>Source Code
380               </tag>
381               <item>
382                   The program must include source code, and must allow
383                   distribution in source code as well as compiled form.
384               </item>
385               <tag>Derived Works
386               </tag>
387               <item>
388                   The license must allow modifications and derived
389                   works, and must allow them to be distributed under the
390                   same terms as the license of the original software.
391               </item>
392               <tag>Integrity of The Author's Source Code
393               </tag>
394               <item>
395                   The license may restrict source-code from being
396                   distributed in modified form <em>only</em> if the
397                   license allows the distribution of "patch files"
398                   with the source code for the purpose of modifying the
399                   program at build time. The license must explicitly
400                   permit distribution of software built from modified
401                   source code. The license may require derived works to
402                   carry a different name or version number from the
403                   original software.  (This is a compromise. The Debian
404                   Project encourages all authors to not restrict any
405                   files, source or binary, from being modified.)
406               </item>
407               <tag>No Discrimination Against Persons or Groups
408               </tag>
409               <item>
410                   The license must not discriminate against any person
411                   or group of persons.
412               </item>
413               <tag>No Discrimination Against Fields of Endeavor
414               </tag>
415               <item>
416                   The license must not restrict anyone from making use
417                   of the program in a specific field of endeavor. For
418                   example, it may not restrict the program from being
419                   used in a business, or from being used for genetic
420                   research.
421               </item>
422               <tag>Distribution of License
423               </tag>
424               <item>
425                   The rights attached to the program must apply to all
426                   to whom the program is redistributed without the need
427                   for execution of an additional license by those
428                   parties.
429               </item>
430               <tag>License Must Not Be Specific to Debian
431               </tag>
432               <item>
433                   The rights attached to the program must not depend on
434                   the program's being part of a Debian system. If the
435                   program is extracted from Debian and used or
436                   distributed without Debian but otherwise within the
437                   terms of the program's license, all parties to whom
438                   the program is redistributed must have the same
439                   rights as those that are granted in conjunction with
440                   the Debian system.
441               </item>
442               <tag>License Must Not Contaminate Other Software
443               </tag>
444               <item>
445                   The license must not place restrictions on other
446                   software that is distributed along with the licensed
447                   software. For example, the license must not insist
448                   that all other programs distributed on the same medium
449                   must be free software.
450               </item>
451               <tag>Example Licenses
452               </tag>
453               <item>
454                   The "GPL," "BSD," and "Artistic" licenses are examples of
455                   licenses that we consider <em>free</em>.
456               </item>
457             </taglist>
458         </p>
459       </sect>
460
461       <sect id="sections">
462         <heading>Archive areas</heading>
463
464         <sect1 id="main">
465           <heading>The main archive area</heading>
466
467           <p>
468             Every package in <em>main</em> must comply with the DFSG
469             (Debian Free Software Guidelines).
470           </p>
471
472           <p>
473             In addition, the packages in <em>main</em>
474             <list compact="compact">
475               <item>
476                   must not require a package outside of <em>main</em>
477                   for compilation or execution (thus, the package must
478                   not declare a "Depends", "Recommends", or
479                   "Build-Depends" relationship on a non-<em>main</em>
480                   package),
481               </item>
482               <item>
483                   must not be so buggy that we refuse to support them,
484                   and
485               </item>
486               <item>
487                   must meet all policy requirements presented in this
488                   manual.
489               </item>
490             </list>
491           </p>
492
493         </sect1>
494
495         <sect1 id="contrib">
496           <heading>The contrib archive area</heading>
497
498           <p>
499             Every package in <em>contrib</em> must comply with the DFSG.
500           </p>
501
502           <p>
503             In addition, the packages in <em>contrib</em>
504             <list compact="compact">
505               <item>
506                   must not be so buggy that we refuse to support them,
507                   and
508               </item>
509               <item>
510                   must meet all policy requirements presented in this
511                   manual.
512               </item>
513             </list>
514           </p>
515
516
517           <p>
518             Examples of packages which would be included in
519             <em>contrib</em> are:
520             <list compact="compact">
521               <item>
522                   free packages which require <em>contrib</em>,
523                   <em>non-free</em> packages or packages which are not
524                   in our archive at all for compilation or execution,
525                   and
526               </item>
527               <item>
528                   wrapper packages or other sorts of free accessories for
529                   non-free programs.
530               </item>
531             </list>
532           </p>
533         </sect1>
534
535         <sect1 id="non-free">
536           <heading>The non-free archive area</heading>
537
538           <p>
539             Packages must be placed in <em>non-free</em> if they are
540             not compliant with the DFSG or are encumbered by patents
541             or other legal issues that make their distribution
542             problematic.
543           </p>
544
545           <p>
546             In addition, the packages in <em>non-free</em>
547             <list compact="compact">
548               <item>
549                   must not be so buggy that we refuse to support them,
550                   and
551               </item>
552               <item>
553                   must meet all policy requirements presented in this
554                   manual that it is possible for them to meet.
555                   <footnote>
556                       It is possible that there are policy
557                       requirements which the package is unable to
558                       meet, for example, if the source is
559                       unavailable.  These situations will need to be
560                       handled on a case-by-case basis.
561                   </footnote>
562               </item>
563             </list>
564           </p>
565         </sect1>
566
567       </sect>
568
569       <sect id="pkgcopyright">
570         <heading>Copyright considerations</heading>
571
572         <p>
573           Every package must be accompanied by a verbatim copy of
574           its copyright and distribution license in the file
575           <file>/usr/share/doc/<var>package</var>/copyright</file>
576           (see <ref id="copyrightfile"> for further details).
577         </p>
578
579         <p>
580           We reserve the right to restrict files from being included
581           anywhere in our archives if
582           <list compact="compact">
583             <item>
584                   their use or distribution would break a law,
585             </item>
586             <item>
587                   there is an ethical conflict in their distribution or
588                   use,
589             </item>
590             <item>
591                   we would have to sign a license for them, or
592             </item>
593             <item>
594                   their distribution would conflict with other project
595                   policies.
596             </item>
597           </list>
598         </p>
599
600         <p>
601           Programs whose authors encourage the user to make
602           donations are fine for the main distribution, provided
603           that the authors do not claim that not donating is
604           immoral, unethical, illegal or something similar; in such
605           a case they must go in <em>non-free</em>.
606         </p>
607
608         <p>
609           Packages whose copyright permission notices (or patent
610           problems) do not even allow redistribution of binaries
611           only, and where no special permission has been obtained,
612           must not be placed on the Debian FTP site and its mirrors
613           at all.
614         </p>
615
616         <p>
617           Note that under international copyright law (this applies
618           in the United States, too), <em>no</em> distribution or
619           modification of a work is allowed without an explicit
620           notice saying so.  Therefore a program without a copyright
621           notice <em>is</em> copyrighted and you may not do anything
622           to it without risking being sued! Likewise if a program
623           has a copyright notice but no statement saying what is
624           permitted then nothing is permitted.
625         </p>
626
627         <p>
628           Many authors are unaware of the problems that restrictive
629           copyrights (or lack of copyright notices) can cause for
630           the users of their supposedly-free software.  It is often
631           worthwhile contacting such authors diplomatically to ask
632           them to modify their license terms. However, this can be a
633           politically difficult thing to do and you should ask for
634           advice on the <tt>debian-legal</tt> mailing list first, as
635           explained below.
636         </p>
637
638         <p>
639           When in doubt about a copyright, send mail to
640           <email>debian-legal@lists.debian.org</email>.  Be prepared
641           to provide us with the copyright statement.  Software
642           covered by the GPL, public domain software and BSD-like
643           copyrights are safe; be wary of the phrases "commercial
644           use prohibited" and "distribution restricted".
645         </p>
646       </sect>
647
648       <sect id="subsections">
649         <heading>Sections</heading>
650
651         <p>
652           The packages in the archive areas <em>main</em>,
653           <em>contrib</em> and <em>non-free</em> are grouped further into
654           <em>sections</em> to simplify handling.
655         </p>
656
657         <p>
658           The archive area and section for each package should be
659           specified in the package's <tt>Section</tt> control record (see
660           <ref id="f-Section">).  However, the maintainer of the Debian
661           archive may override this selection to ensure the consistency of
662           the Debian distribution.  The <tt>Section</tt> field should be
663           of the form:
664           <list compact="compact">
665             <item>
666                   <em>section</em> if the package is in the
667                   <em>main</em> archive area,
668             </item>
669             <item>
670                   <em>area/section</em> if the package is in
671                   the <em>contrib</em> or <em>non-free</em>
672                   archive areas.
673             </item>
674           </list>
675         </p>
676
677         <p>
678           The Debian archive maintainers provide the authoritative
679           list of sections.  At present, they are:
680           <em>admin</em>, <em>cli-mono</em>, <em>comm</em>, <em>database</em>,
681           <em>devel</em>, <em>debug</em>, <em>doc</em>, <em>editors</em>,
682           <em>electronics</em>, <em>embedded</em>, <em>fonts</em>,
683           <em>games</em>, <em>gnome</em>, <em>graphics</em>, <em>gnu-r</em>,
684           <em>gnustep</em>, <em>hamradio</em>, <em>haskell</em>,
685           <em>httpd</em>, <em>interpreters</em>, <em>java</em>, <em>kde</em>,
686           <em>kernel</em>, <em>libs</em>, <em>libdevel</em>, <em>lisp</em>,
687           <em>localization</em>, <em>mail</em>, <em>math</em>, <em>misc</em>,
688           <em>net</em>, <em>news</em>, <em>ocaml</em>, <em>oldlibs</em>,
689           <em>otherosfs</em>, <em>perl</em>, <em>php</em>, <em>python</em>,
690           <em>ruby</em>, <em>science</em>, <em>shells</em>, <em>sound</em>,
691           <em>tex</em>, <em>text</em>, <em>utils</em>, <em>vcs</em>,
692           <em>video</em>, <em>web</em>, <em>x11</em>, <em>xfce</em>,
693           <em>zope</em>.
694         </p>
695       </sect>
696
697       <sect id="priorities">
698         <heading>Priorities</heading>
699
700         <p>
701           Each package should have a <em>priority</em> value, which is
702           included in the package's <em>control record</em>
703           (see <ref id="f-Priority">).
704           This information is used by the Debian package management tools to
705           separate high-priority packages from less-important packages.
706         </p>
707
708         <p>
709           The following <em>priority levels</em> are recognized by the
710           Debian package management tools.
711           <taglist>
712             <tag><tt>required</tt></tag>
713             <item>
714                 Packages which are necessary for the proper
715                 functioning of the system (usually, this means that
716                 dpkg functionality depends on these packages).
717                 Removing a <tt>required</tt> package may cause your
718                 system to become totally broken and you may not even
719                 be able to use <prgn>dpkg</prgn> to put things back,
720                 so only do so if you know what you are doing.  Systems
721                 with only the <tt>required</tt> packages are probably
722                 unusable, but they do have enough functionality to
723                 allow the sysadmin to boot and install more software.
724             </item>
725             <tag><tt>important</tt></tag>
726             <item>
727                 Important programs, including those which one would
728                 expect to find on any Unix-like system.  If the
729                 expectation is that an experienced Unix person who
730                 found it missing would say "What on earth is going on,
731                 where is <prgn>foo</prgn>?", it must be an
732                 <tt>important</tt> package.<footnote>
733                     This is an important criterion because we are
734                     trying to produce, amongst other things, a free
735                     Unix.
736                 </footnote>
737                 Other packages without which the system will not run
738                 well or be usable must also have priority
739                 <tt>important</tt>.  This does
740                 <em>not</em> include Emacs, the X Window System, TeX
741                 or any other large applications.  The
742                 <tt>important</tt> packages are just a bare minimum of
743                 commonly-expected and necessary tools.
744             </item>
745             <tag><tt>standard</tt></tag>
746             <item>
747                 These packages provide a reasonably small but not too
748                 limited character-mode system.  This is what will be
749                 installed by default if the user doesn't select anything
750                 else.  It doesn't include many large applications.
751             </item>
752             <tag><tt>optional</tt></tag>
753             <item>
754                 (In a sense everything that isn't required is
755                 optional, but that's not what is meant here.) This is
756                 all the software that you might reasonably want to
757                 install if you didn't know what it was and don't have
758                 specialized requirements. This is a much larger system
759                 and includes the X Window System, a full TeX
760                 distribution, and many applications. Note that
761                 optional packages should not conflict with each other.
762             </item>
763             <tag><tt>extra</tt></tag>
764             <item>
765                 This contains all packages that conflict with others
766                 with required, important, standard or optional
767                 priorities, or are only likely to be useful if you
768                 already know what they are or have specialized
769                 requirements (such as packages containing only detached
770                 debugging symbols).
771             </item>
772           </taglist>
773         </p>
774
775         <p>
776           Packages must not depend on packages with lower priority
777           values (excluding build-time dependencies).  In order to
778           ensure this, the priorities of one or more packages may need
779           to be adjusted.
780         </p>
781       </sect>
782
783     </chapt>
784
785
786     <chapt id="binary">
787       <heading>Binary packages</heading>
788
789       <p>
790         The Debian GNU/Linux distribution is based on the Debian
791         package management system, called <prgn>dpkg</prgn>. Thus,
792         all packages in the Debian distribution must be provided
793         in the <tt>.deb</tt> file format.
794       </p>
795
796       <sect>
797         <heading>The package name</heading>
798
799         <p>
800           Every package must have a name that's unique within the Debian
801           archive.
802         </p>
803
804         <p>
805           The package name is included in the control field
806           <tt>Package</tt>, the format of which is described
807           in <ref id="f-Package">.
808           The package name is also included as a part of the file name
809           of the <tt>.deb</tt> file.
810         </p>
811       </sect>
812
813       <sect id="versions">
814         <heading>The version of a package</heading>
815
816         <p>
817           Every package has a version number recorded in its
818           <tt>Version</tt> control file field, described in
819           <ref id="f-Version">.
820         </p>
821
822         <p>
823           The package management system imposes an ordering on version
824           numbers, so that it can tell whether packages are being up- or
825           downgraded and so that package system front end applications
826           can tell whether a package it finds available is newer than
827           the one installed on the system.  The version number format
828           has the most significant parts (as far as comparison is
829           concerned) at the beginning.
830         </p>
831
832         <p>
833           If an upstream package has problematic version numbers they
834           should be converted to a sane form for use in the
835           <tt>Version</tt> field.
836         </p>
837
838         <sect1>
839           <heading>Version numbers based on dates</heading>
840
841           <p>
842             In general, Debian packages should use the same version
843             numbers as the upstream sources.
844           </p>
845
846           <p>
847             However, in some cases where the upstream version number is
848             based on a date (e.g., a development "snapshot" release) the
849             package management system cannot handle these version
850             numbers without epochs. For example, dpkg will consider
851             "96May01" to be greater than "96Dec24".
852           </p>
853
854           <p>
855             To prevent having to use epochs for every new upstream
856             version, the date based portion of the version number
857             should be changed to the following format in such cases:
858             "19960501", "19961224". It is up to the maintainer whether
859             they want to bother the upstream maintainer to change
860             the version numbers upstream, too.
861           </p>
862
863           <p>
864             Note that other version formats based on dates which are
865             parsed correctly by the package management system should
866             <em>not</em> be changed.
867           </p>
868
869           <p>
870             Native Debian packages (i.e., packages which have been
871             written especially for Debian) whose version numbers include
872             dates should always use the "YYYYMMDD" format.
873           </p>
874         </sect1>
875
876       </sect>
877
878       <sect>
879         <heading>The maintainer of a package</heading>
880
881         <p>
882           Every package must have a Debian maintainer (the
883           maintainer may be one person or a group of people
884           reachable from a common email address, such as a mailing
885           list).  The maintainer is responsible for ensuring that
886           the package is placed in the appropriate distributions.
887         </p>
888
889         <p>
890           The maintainer must be specified in the
891           <tt>Maintainer</tt> control field with their correct name
892           and a working email address.  If one person maintains
893           several packages, they should try to avoid having
894           different forms of their name and email address in
895           the <tt>Maintainer</tt> fields of those packages.
896         </p>
897
898         <p>
899           The format of the <tt>Maintainer</tt> control field is
900           described in <ref id="f-Maintainer">.
901         </p>
902
903         <p>
904           If the maintainer of a package quits from the Debian
905           project, "Debian QA Group"
906           <email>packages@qa.debian.org</email> takes over the
907           maintainer-ship of the package until someone else
908           volunteers for that task. These packages are called
909           <em>orphaned packages</em>.<footnote>
910                 The detailed procedure for doing this gracefully can
911                 be found in the Debian Developer's Reference,
912                 see <ref id="related">.
913           </footnote>
914         </p>
915       </sect>
916
917       <sect id="descriptions">
918         <heading>The description of a package</heading>
919
920         <p>
921           Every Debian package must have an extended description
922           stored in the appropriate field of the control record.
923           The technical information about the format of the
924           <tt>Description</tt> field is in <ref id="f-Description">.
925         </p>
926
927         <p>
928           The description should describe the package (the program) to a
929           user (system administrator) who has never met it before so that
930           they have enough information to decide whether they want to
931           install it. This description should not just be copied verbatim
932           from the program's documentation.
933         </p>
934
935         <p>
936           Put important information first, both in the synopsis and
937           extended description.  Sometimes only the first part of the
938           synopsis or of the description will be displayed.  You can
939           assume that there will usually be a way to see the whole
940           extended description.
941         </p>
942
943         <p>
944           The description should also give information about the
945           significant dependencies and conflicts between this package
946           and others, so that the user knows why these dependencies and
947           conflicts have been declared.
948         </p>
949
950         <p>
951           Instructions for configuring or using the package should
952           not be included (that is what installation scripts,
953           manual pages, info files, etc., are for).  Copyright
954           statements and other administrivia should not be included
955           either (that is what the copyright file is for).
956         </p>
957
958         <sect1 id="synopsis"><heading>The single line synopsis</heading>
959
960           <p>
961             The single line synopsis should be kept brief - certainly
962             under 80 characters.
963           </p>
964
965           <p>
966             Do not include the package name in the synopsis line.  The
967             display software knows how to display this already, and you
968             do not need to state it.  Remember that in many situations
969             the user may only see the synopsis line - make it as
970             informative as you can.
971           </p>
972
973         </sect1>
974
975         <sect1 id="extendeddesc"><heading>The extended description</heading>
976
977           <p>
978             Do not try to continue the single line synopsis into the
979             extended description.  This will not work correctly when
980             the full description is displayed, and makes no sense
981             where only the summary (the single line synopsis) is
982             available.
983           </p>
984
985           <p>
986             The extended description should describe what the package
987             does and how it relates to the rest of the system (in terms
988             of, for example, which subsystem it is which part of).
989           </p>
990
991           <p>
992             The description field needs to make sense to anyone, even
993             people who have no idea about any of the things the
994             package deals with.<footnote>
995                 The blurb that comes with a program in its
996                 announcements and/or <prgn>README</prgn> files is
997                 rarely suitable for use in a description.  It is
998                 usually aimed at people who are already in the
999                 community where the package is used.
1000             </footnote>
1001           </p>
1002
1003         </sect1>
1004
1005       </sect>
1006
1007       <sect>
1008         <heading>Dependencies</heading>
1009
1010         <p>
1011           Every package must specify the dependency information
1012           about other packages that are required for the first to
1013           work correctly.
1014         </p>
1015
1016         <p>
1017           For example, a dependency entry must be provided for any
1018           shared libraries required by a dynamically-linked executable
1019           binary in a package.
1020         </p>
1021
1022         <p>
1023           Packages are not required to declare any dependencies they
1024           have on other packages which are marked <tt>Essential</tt>
1025           (see below), and should not do so unless they depend on a
1026           particular version of that package.<footnote>
1027             <p>
1028               Essential is needed in part to avoid unresolvable dependency
1029               loops on upgrade.  If packages add unnecessary dependencies
1030               on packages in this set, the chances that there
1031               <strong>will</strong> be an unresolvable dependency loop
1032               caused by forcing these Essential packages to be configured
1033               first before they need to be is greatly increased.  It also
1034               increases the chances that frontends will be unable to
1035               <strong>calculate</strong> an upgrade path, even if one
1036               exists.
1037             </p>
1038             <p>
1039               Also, functionality is rarely ever removed from the
1040               Essential set, but <em>packages</em> have been removed from
1041               the Essential set when the functionality moved to a
1042               different package. So depending on these packages <em>just
1043               in case</em> they stop being essential does way more harm
1044               than good.
1045             </p>
1046           </footnote>
1047         </p>
1048
1049         <p>
1050           Sometimes, a package requires another package to be unpacked
1051           <em>and</em> configured before it can be unpacked. In this
1052           case, you must specify a <tt>Pre-Depends</tt> entry for
1053           the package.
1054         </p>
1055
1056         <p>
1057           You should not specify a <tt>Pre-Depends</tt> entry for a
1058           package before this has been discussed on the
1059           <tt>debian-devel</tt> mailing list and a consensus about
1060           doing that has been reached.
1061         </p>
1062
1063         <p>
1064           The format of the package interrelationship control fields is
1065           described in <ref id="relationships">.
1066         </p>
1067       </sect>
1068
1069       <sect id="virtual_pkg">
1070         <heading>Virtual packages</heading>
1071
1072         <p>
1073           Sometimes, there are several packages which offer
1074           more-or-less the same functionality. In this case, it's
1075           useful to define a <em>virtual package</em> whose name
1076           describes that common functionality.  (The virtual
1077           packages only exist logically, not physically; that's why
1078           they are called <em>virtual</em>.) The packages with this
1079           particular function will then <em>provide</em> the virtual
1080           package. Thus, any other package requiring that function
1081           can simply depend on the virtual package without having to
1082           specify all possible packages individually.
1083         </p>
1084
1085         <p>
1086           All packages should use virtual package names where
1087           appropriate, and arrange to create new ones if necessary.
1088           They should not use virtual package names (except privately,
1089           amongst a cooperating group of packages) unless they have
1090           been agreed upon and appear in the list of virtual package
1091           names. (See also <ref id="virtual">)
1092         </p>
1093
1094         <p>
1095           The latest version of the authoritative list of virtual
1096           package names can be found in the <tt>debian-policy</tt> package.
1097           It is also available from the Debian web mirrors at
1098           <tt><url name="/doc/packaging-manuals/virtual-package-names-list.txt"
1099                 id="http://www.debian.org/doc/packaging-manuals/virtual-package-names-list.txt"></tt>.
1100         </p>
1101
1102         <p>
1103           The procedure for updating the list is described in the preface
1104           to the list.
1105         </p>
1106
1107       </sect>
1108
1109       <sect>
1110         <heading>Base system</heading>
1111
1112         <p>
1113           The <tt>base system</tt> is a minimum subset of the Debian
1114           GNU/Linux system that is installed before everything else
1115           on a new system. Only very few packages are allowed to form
1116           part of the base system, in order to keep the required disk
1117           usage very small.
1118         </p>
1119
1120         <p>
1121           The base system consists of all those packages with priority
1122           <tt>required</tt> or <tt>important</tt>. Many of them will
1123           be tagged <tt>essential</tt> (see below).
1124         </p>
1125       </sect>
1126
1127       <sect>
1128         <heading>Essential packages</heading>
1129
1130         <p>
1131           Essential is defined as the minimal set of functionality that
1132           must be available and usable on the system at all times, even
1133           when packages are in an unconfigured (but unpacked) state.
1134           Packages are tagged <tt>essential</tt> for a system using the
1135           <tt>Essential</tt> control file field.  The format of the
1136           <tt>Essential</tt> control field is described in <ref
1137           id="f-Essential">.
1138         </p>
1139
1140         <p>
1141           Since these packages cannot be easily removed (one has to
1142           specify an extra <em>force option</em> to
1143           <prgn>dpkg</prgn> to do so), this flag must not be used
1144           unless absolutely necessary.  A shared library package
1145           must not be tagged <tt>essential</tt>; dependencies will
1146           prevent its premature removal, and we need to be able to
1147           remove it when it has been superseded.
1148         </p>
1149
1150         <p>
1151           Since dpkg will not prevent upgrading of other packages
1152           while an <tt>essential</tt> package is in an unconfigured
1153             state, all <tt>essential</tt> packages must supply all of
1154             their core functionality even when unconfigured. If the
1155             package cannot satisfy this requirement it must not be
1156             tagged as essential, and any packages depending on this
1157             package must instead have explicit dependency fields as
1158             appropriate.
1159         </p>
1160
1161         <p>
1162           Maintainers should take great care in adding any programs,
1163           interfaces, or functionality to <tt>essential</tt> packages.
1164           Packages may assume that functionality provided by
1165           <tt>essential</tt> packages is always available without
1166           declaring explicit dependencies, which means that removing
1167           functionality from the Essential set is very difficult and is
1168           almost never done.  Any capability added to an
1169           <tt>essential</tt> package therefore creates an obligation to
1170           support that capability as part of the Essential set in
1171           perpetuity.
1172         </p>
1173
1174         <p>
1175           You must not tag any packages <tt>essential</tt> before
1176           this has been discussed on the <tt>debian-devel</tt>
1177           mailing list and a consensus about doing that has been
1178           reached.
1179         </p>
1180       </sect>
1181
1182       <sect id="maintscripts">
1183         <heading>Maintainer Scripts</heading>
1184
1185         <p>
1186           The package installation scripts should avoid producing
1187           output which is unnecessary for the user to see and
1188           should rely on <prgn>dpkg</prgn> to stave off boredom on
1189           the part of a user installing many packages.  This means,
1190           amongst other things, using the <tt>--quiet</tt> option on
1191           <prgn>install-info</prgn>.
1192         </p>
1193
1194         <p>
1195           Errors which occur during the execution of an installation
1196           script must be checked and the installation must not
1197           continue after an error.
1198         </p>
1199
1200         <p>
1201           Note that in general <ref id="scripts"> applies to package
1202           maintainer scripts, too.
1203         </p>
1204
1205         <p>
1206           You should not use <prgn>dpkg-divert</prgn> on a file
1207           belonging to another package without consulting the
1208           maintainer of that package first.
1209         </p>
1210
1211         <p>
1212           All packages which supply an instance of a common command
1213           name (or, in general, filename) should generally use
1214           <prgn>update-alternatives</prgn>, so that they may be
1215           installed together.  If <prgn>update-alternatives</prgn>
1216           is not used, then each package must use
1217           <tt>Conflicts</tt> to ensure that other packages are
1218           de-installed.  (In this case, it may be appropriate to
1219           specify a conflict against earlier versions of something
1220           that previously did not use
1221           <prgn>update-alternatives</prgn>; this is an exception to
1222           the usual rule that versioned conflicts should be
1223           avoided.)
1224         </p>
1225
1226         <sect1 id="maintscriptprompt">
1227           <heading>Prompting in maintainer scripts</heading>
1228           <p>
1229             Package maintainer scripts may prompt the user if
1230             necessary. Prompting must be done by communicating
1231             through a program, such as <prgn>debconf</prgn>, which
1232             conforms to the Debian Configuration Management
1233             Specification, version 2 or higher.
1234           </p>
1235
1236           <p>
1237             Packages which are essential, or which are dependencies of
1238             essential packages, may fall back on another prompting method
1239             if no such interface is available when they are executed.
1240           </p>
1241
1242           <p>
1243             The Debian Configuration Management Specification is included
1244             in the <file>debconf_specification</file> files in the
1245             <package>debian-policy</package> package.
1246             It is also available from the Debian web mirrors at
1247             <tt><url name="/doc/packaging-manuals/debconf_specification.html"
1248                 id="http://www.debian.org/doc/packaging-manuals/debconf_specification.html"></tt>.
1249           </p>
1250
1251           <p>
1252             Packages which use the Debian Configuration Management
1253             Specification may contain an additional
1254             <prgn>config</prgn> script and a <tt>templates</tt>
1255             file in their control archive<footnote>
1256                 The control.tar.gz inside the .deb.
1257                 See <manref name="deb" section="5">.
1258             </footnote>.
1259             The <prgn>config</prgn> script might be run before the
1260             <prgn>preinst</prgn> script, and before the package is unpacked
1261             or any of its dependencies or pre-dependencies are satisfied.
1262             Therefore it must work using only the tools present in
1263             <em>essential</em> packages.<footnote>
1264                   <package>Debconf</package> or another tool that
1265                   implements the Debian Configuration Management
1266                   Specification will also be installed, and any
1267                   versioned dependencies on it will be satisfied
1268                   before preconfiguration begins.
1269             </footnote>
1270           </p>
1271
1272           <p>
1273             Packages which use the Debian Configuration Management
1274             Specification must allow for translation of their user-visible
1275             messages by using a gettext-based system such as the one
1276             provided by the <package>po-debconf</package> package.
1277           </p>
1278
1279           <p>
1280             Packages should try to minimize the amount of prompting
1281             they need to do, and they should ensure that the user
1282             will only ever be asked each question once.  This means
1283             that packages should try to use appropriate shared
1284             configuration files (such as <file>/etc/papersize</file> and
1285             <file>/etc/news/server</file>), and shared
1286             <package>debconf</package> variables rather than each
1287             prompting for their own list of required pieces of
1288             information.
1289           </p>
1290
1291           <p>
1292             It also means that an upgrade should not ask the same
1293             questions again, unless the user has used
1294             <tt>dpkg --purge</tt> to remove the package's configuration.
1295             The answers to configuration questions should be stored in an
1296             appropriate place in <file>/etc</file> so that the user can
1297             modify them, and how this has been done should be
1298             documented.
1299           </p>
1300
1301           <p>
1302             If a package has a vitally important piece of
1303             information to pass to the user (such as "don't run me
1304             as I am, you must edit the following configuration files
1305             first or you risk your system emitting badly-formatted
1306             messages"), it should display this in the
1307             <prgn>config</prgn> or <prgn>postinst</prgn> script and
1308             prompt the user to hit return to acknowledge the
1309             message.  Copyright messages do not count as vitally
1310             important (they belong in
1311             <file>/usr/share/doc/<var>package</var>/copyright</file>);
1312             neither do instructions on how to use a program (these
1313             should be in on-line documentation, where all the users
1314             can see them).
1315           </p>
1316
1317           <p>
1318             Any necessary prompting should almost always be confined
1319             to the <prgn>config</prgn> or <prgn>postinst</prgn>
1320             script. If it is done in the <prgn>postinst</prgn>, it
1321             should be protected with a conditional so that
1322             unnecessary prompting doesn't happen if a package's
1323             installation fails and the <prgn>postinst</prgn> is
1324             called with <tt>abort-upgrade</tt>,
1325             <tt>abort-remove</tt> or <tt>abort-deconfigure</tt>.
1326           </p>
1327         </sect1>
1328
1329       </sect>
1330
1331     </chapt>
1332
1333
1334     <chapt id="source">
1335       <heading>Source packages</heading>
1336
1337       <sect id="standardsversion">
1338         <heading>Standards conformance</heading>
1339
1340         <p>
1341           Source packages should specify the most recent version number
1342           of this policy document with which your package complied
1343           when it was last updated.
1344         </p>
1345
1346         <p>
1347           This information may be used to file bug reports
1348           automatically if your package becomes too much out of date.
1349         </p>
1350
1351         <p>
1352           The version is specified in the <tt>Standards-Version</tt>
1353           control field.
1354           The format of the <tt>Standards-Version</tt> field is
1355           described in <ref id="f-Standards-Version">.
1356         </p>
1357
1358         <p>
1359           You should regularly, and especially if your package has
1360           become out of date, check for the newest Policy Manual
1361           available and update your package, if necessary. When your
1362           package complies with the new standards you should update the
1363           <tt>Standards-Version</tt> source package field and
1364           release it.<footnote>
1365                 See the file <file>upgrading-checklist</file> for
1366                 information about policy which has changed between
1367                 different versions of this document.
1368           </footnote>
1369         </p>
1370
1371       </sect>
1372
1373       <sect id="pkg-relations">
1374         <heading>Package relationships</heading>
1375
1376         <p>
1377           Source packages should specify which binary packages they
1378           require to be installed or not to be installed in order to
1379           build correctly.  For example, if building a package
1380           requires a certain compiler, then the compiler should be
1381           specified as a build-time dependency.
1382         </p>
1383
1384         <p>
1385           It is not necessary to explicitly specify build-time
1386           relationships on a minimal set of packages that are always
1387           needed to compile, link and put in a Debian package a
1388           standard "Hello World!" program written in C or C++.  The
1389           required packages are called <em>build-essential</em>, and
1390           an informational list can be found in
1391           <file>/usr/share/doc/build-essential/list</file> (which is
1392           contained in the <tt>build-essential</tt>
1393           package).<footnote>
1394             Rationale:
1395                 <list compact="compact">
1396                   <item>
1397                       This allows maintaining the list separately
1398                       from the policy documents (the list does not
1399                       need the kind of control that the policy
1400                       documents do).
1401                   </item>
1402                   <item>
1403                       Having a separate package allows one to install
1404                       the build-essential packages on a machine, as
1405                       well as allowing other packages such as tasks to
1406                       require installation of the build-essential
1407                       packages using the depends relation.
1408                   </item>
1409                   <item>
1410                       The separate package allows bug reports against
1411                       the list to be categorized separately from
1412                       the policy management process in the BTS.
1413                   </item>
1414                 </list>
1415           </footnote>
1416         </p>
1417
1418         <p>
1419           When specifying the set of build-time dependencies, one
1420           should list only those packages explicitly required by the
1421           build.  It is not necessary to list packages which are
1422           required merely because some other package in the list of
1423           build-time dependencies depends on them.<footnote>
1424                 The reason for this is that dependencies change, and
1425                 you should list all those packages, and <em>only</em>
1426                 those packages that <em>you</em> need directly.  What
1427                 others need is their business.  For example, if you
1428                 only link against <file>libimlib</file>, you will need to
1429                 build-depend on <package>libimlib2-dev</package> but
1430                 not against any <tt>libjpeg*</tt> packages, even
1431                 though <tt>libimlib2-dev</tt> currently depends on
1432                 them: installation of <package>libimlib2-dev</package>
1433                 will automatically ensure that all of its run-time
1434                 dependencies are satisfied.
1435           </footnote>
1436         </p>
1437
1438         <p>
1439           If build-time dependencies are specified, it must be
1440           possible to build the package and produce working binaries
1441           on a system with only essential and build-essential
1442           packages installed and also those required to satisfy the
1443           build-time relationships (including any implied
1444           relationships).  In particular, this means that version
1445           clauses should be used rigorously in build-time
1446           relationships so that one cannot produce bad or
1447           inconsistently configured packages when the relationships
1448           are properly satisfied.
1449         </p>
1450
1451         <p>
1452           <ref id="relationships"> explains the technical details.
1453         </p>
1454       </sect>
1455
1456       <sect>
1457         <heading>Changes to the upstream sources</heading>
1458
1459         <p>
1460           If changes to the source code are made that are not
1461           specific to the needs of the Debian system, they should be
1462           sent to the upstream authors in whatever form they prefer
1463           so as to be included in the upstream version of the
1464           package.
1465         </p>
1466
1467         <p>
1468           If you need to configure the package differently for
1469           Debian or for Linux, and the upstream source doesn't
1470           provide a way to do so, you should add such configuration
1471           facilities (for example, a new <prgn>autoconf</prgn> test
1472           or <tt>#define</tt>) and send the patch to the upstream
1473           authors, with the default set to the way they originally
1474           had it.  You can then easily override the default in your
1475           <file>debian/rules</file> or wherever is appropriate.
1476         </p>
1477
1478         <p>
1479           You should make sure that the <prgn>configure</prgn> utility
1480           detects the correct architecture specification string
1481           (refer to <ref id="arch-spec"> for details).
1482         </p>
1483
1484         <p>
1485           If you need to edit a <prgn>Makefile</prgn> where GNU-style
1486           <prgn>configure</prgn> scripts are used, you should edit the
1487           <file>.in</file> files rather than editing the
1488           <prgn>Makefile</prgn> directly.  This allows the user to
1489           reconfigure the package if necessary.  You should
1490           <em>not</em> configure the package and edit the generated
1491           <prgn>Makefile</prgn>!  This makes it impossible for someone
1492           else to later reconfigure the package without losing the
1493           changes you made.
1494         </p>
1495
1496       </sect>
1497
1498       <sect id="dpkgchangelog">
1499         <heading>Debian changelog: <file>debian/changelog</file></heading>
1500
1501         <p>
1502           Changes in the Debian version of the package should be
1503           briefly explained in the Debian changelog file
1504           <file>debian/changelog</file>.<footnote>
1505             <p>
1506               Mistakes in changelogs are usually best rectified by
1507               making a new changelog entry rather than "rewriting
1508               history" by editing old changelog entries.
1509             </p>
1510           </footnote>
1511           This includes modifications
1512           made in the Debian package compared to the upstream one
1513           as well as other changes and updates to the package.
1514           <footnote>
1515               Although there is nothing stopping an author who is also
1516               the Debian maintainer from using this changelog for all
1517               their changes, it will have to be renamed if the Debian
1518               and upstream maintainers become different people. In such
1519               a case, however, it might be better to maintain the package
1520               as a non-native package.
1521           </footnote>
1522         </p>
1523
1524         <p>
1525           The format of the <file>debian/changelog</file> allows the
1526           package building tools to discover which version of the package
1527           is being built and find out other release-specific information.
1528         </p>
1529
1530         <p>
1531           That format is a series of entries like this:
1532
1533 <example compact="compact">
1534 <var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
1535             <var>
1536               [optional blank line(s), stripped]
1537             </var>
1538   * <var>change details</var>
1539     <var>more change details</var>
1540             <var>
1541               [blank line(s), included in output of dpkg-parsechangelog]
1542             </var>
1543   * <var>even more change details</var>
1544             <var>
1545               [optional blank line(s), stripped]
1546             </var>
1547  -- <var>maintainer name</var> &lt;<var>email address</var>&gt;<var>[two spaces]</var>  <var>date</var>
1548 </example>
1549         </p>
1550
1551         <p>
1552           <var>package</var> and <var>version</var> are the source
1553           package name and version number.
1554         </p>
1555
1556         <p>
1557           <var>distribution(s)</var> lists the distributions where
1558           this version should be installed when it is uploaded - it
1559           is copied to the <tt>Distribution</tt> field in the
1560           <file>.changes</file> file.  See <ref id="f-Distribution">.
1561         </p>
1562
1563         <p>
1564           <var>urgency</var> is the value for the <tt>Urgency</tt>
1565           field in the <file>.changes</file> file for the upload
1566           (see <ref id="f-Urgency">). It is not possible to specify
1567           an urgency containing commas; commas are used to separate
1568           <tt><var>keyword</var>=<var>value</var></tt> settings in the
1569           <prgn>dpkg</prgn> changelog format (though there is
1570           currently only one useful <var>keyword</var>,
1571           <tt>urgency</tt>).
1572         </p>
1573
1574         <p>
1575           The change details may in fact be any series of lines
1576           starting with at least two spaces, but conventionally each
1577           change starts with an asterisk and a separating space and
1578           continuation lines are indented so as to bring them in
1579           line with the start of the text above.  Blank lines may be
1580           used here to separate groups of changes, if desired.
1581         </p>
1582
1583         <p>
1584           If this upload resolves bugs recorded in the Bug Tracking
1585           System (BTS), they may be automatically closed on the
1586           inclusion of this package into the Debian archive by
1587           including the string: <tt>closes: Bug#<var>nnnnn</var></tt>
1588           in the change details.<footnote>
1589               To be precise, the string should match the following
1590               Perl regular expression:
1591               <example>
1592 /closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i
1593               </example>
1594               Then all of the bug numbers listed will be closed by the
1595               archive maintenance script (<prgn>katie</prgn>) using the
1596               <var>version</var> of the changelog entry.
1597           </footnote>
1598           This information is conveyed via the <tt>Closes</tt> field
1599           in the <tt>.changes</tt> file (see <ref id="f-Closes">).
1600         </p>
1601
1602         <p>
1603           The maintainer name and email address used in the changelog
1604           should be the details of the person uploading <em>this</em>
1605           version.  They are <em>not</em> necessarily those of the
1606           usual package maintainer.  The information here will be
1607           copied to the <tt>Changed-By</tt> field in the
1608           <tt>.changes</tt> file (see <ref id="f-Changed-By">),
1609           and then later used to send an acknowledgement when the
1610           upload has been installed.
1611         </p>
1612
1613         <p>
1614           The <var>date</var> must be in RFC822 format<footnote>
1615               This is generated by <tt>date -R</tt>.
1616           </footnote>; it must include the time zone specified
1617           numerically, with the time zone name or abbreviation
1618           optionally present as a comment in parentheses.
1619         </p>
1620
1621         <p>
1622           The first "title" line with the package name must start
1623           at the left hand margin.  The "trailer" line with the
1624           maintainer and date details must be preceded by exactly
1625           one space.  The maintainer details and the date must be
1626           separated by exactly two spaces.
1627         </p>
1628
1629         <p>
1630           The entire changelog must be encoded in UTF-8.
1631         </p>
1632
1633         <p>
1634           For more information on placement of the changelog files
1635           within binary packages, please see <ref id="changelogs">.
1636         </p>
1637       </sect>
1638
1639       <sect id="dpkgcopyright">
1640         <heading>Copyright: <file>debian/copyright</file></heading>
1641         <p>
1642           Every package must be accompanied by a verbatim copy of
1643           its copyright and distribution license in the file
1644           <file>/usr/share/doc/<var>package</var>/copyright</file>
1645           (see <ref id="copyrightfile"> for further details). Also see
1646           <ref id="pkgcopyright"> for further considerations relayed
1647           to copyrights for packages.
1648         </p>
1649       </sect>
1650       <sect>
1651         <heading>Error trapping in makefiles</heading>
1652
1653         <p>
1654           When <prgn>make</prgn> invokes a command in a makefile
1655           (including your package's upstream makefiles and
1656           <file>debian/rules</file>), it does so using <prgn>sh</prgn>.  This
1657           means that <prgn>sh</prgn>'s usual bad error handling
1658           properties apply: if you include a miniature script as one
1659           of the commands in your makefile you'll find that if you
1660           don't do anything about it then errors are not detected
1661           and <prgn>make</prgn> will blithely continue after
1662           problems.
1663         </p>
1664
1665         <p>
1666           Every time you put more than one shell command (this
1667           includes using a loop) in a makefile command you
1668           must make sure that errors are trapped.  For
1669           simple compound commands, such as changing directory and
1670           then running a program, using <tt>&amp;&amp;</tt> rather
1671           than semicolon as a command separator is sufficient.  For
1672           more complex commands including most loops and
1673           conditionals you should include a separate <tt>set -e</tt>
1674           command at the start of every makefile command that's
1675           actually one of these miniature shell scripts.
1676         </p>
1677       </sect>
1678
1679       <sect id="timestamps">
1680         <heading>Time Stamps</heading>
1681         <p>
1682           Maintainers should preserve the modification times of the
1683           upstream source files in a package, as far as is reasonably
1684           possible.<footnote>
1685               The rationale is that there is some information conveyed
1686               by knowing the age of the file, for example, you could
1687               recognize that some documentation is very old by looking
1688               at the modification time, so it would be nice if the
1689               modification time of the upstream source would be
1690               preserved.
1691           </footnote>
1692         </p>
1693       </sect>
1694
1695       <sect id="restrictions">
1696         <heading>Restrictions on objects in source packages</heading>
1697
1698         <p>
1699           The source package may not contain any hard links<footnote>
1700             <p>
1701               This is not currently detected when building source
1702               packages, but only when extracting
1703               them.
1704             </p>
1705             <p>
1706               Hard links may be permitted at some point in the
1707               future, but would require a fair amount of
1708               work.
1709             </p>
1710           </footnote>, device special files, sockets or setuid or
1711           setgid files.<footnote>
1712               Setgid directories are allowed.
1713           </footnote>
1714         </p>
1715       </sect>
1716
1717       <sect id="debianrules">
1718         <heading>Main building script: <file>debian/rules</file></heading>
1719
1720         <p>
1721           This file must be an executable makefile, and contains the
1722           package-specific recipes for compiling the package and
1723           building binary package(s) from the source.
1724         </p>
1725
1726         <p>
1727           It must start with the line <tt>#!/usr/bin/make -f</tt>,
1728           so that it can be invoked by saying its name rather than
1729           invoking <prgn>make</prgn> explicitly.
1730         </p>
1731
1732         <p>
1733           Since an interactive <file>debian/rules</file> script makes it
1734           impossible to auto-compile that package and also makes it
1735           hard for other people to reproduce the same binary
1736           package, all <em>required targets</em> MUST be
1737           non-interactive. At a minimum, required targets are the
1738           ones called by <prgn>dpkg-buildpackage</prgn>, namely,
1739           <em>clean</em>, <em>binary</em>, <em>binary-arch</em>,
1740           <em>binary-indep</em>, and <em>build</em>. It also follows
1741           that any target that these targets depend on must also be
1742           non-interactive.
1743         </p>
1744
1745         <p>
1746           The targets are as follows (required unless stated otherwise):
1747           <taglist>
1748             <tag><tt>build</tt></tag>
1749             <item>
1750               <p>
1751                 The <tt>build</tt> target should perform all the
1752                 configuration and compilation of the package.
1753                 If a package has an interactive pre-build
1754                 configuration routine, the Debianized source package
1755                 must either be built after this has taken place (so
1756                 that the binary package can be built without rerunning
1757                 the configuration) or the configuration routine
1758                 modified to become non-interactive.  (The latter is
1759                 preferable if there are architecture-specific features
1760                 detected by the configuration routine.)
1761               </p>
1762
1763               <p>
1764                 For some packages, notably ones where the same
1765                 source tree is compiled in different ways to produce
1766                 two binary packages, the <tt>build</tt> target
1767                 does not make much sense.  For these packages it is
1768                 good enough to provide two (or more) targets
1769                 (<tt>build-a</tt> and <tt>build-b</tt> or whatever)
1770                 for each of the ways of building the package, and a
1771                 <tt>build</tt> target that does nothing.  The
1772                 <tt>binary</tt> target will have to build the
1773                 package in each of the possible ways and make the
1774                 binary package out of each.
1775               </p>
1776
1777               <p>
1778                 The <tt>build</tt> target must not do anything
1779                 that might require root privilege.
1780               </p>
1781
1782               <p>
1783                 The <tt>build</tt> target may need to run the
1784                 <tt>clean</tt> target first - see below.
1785               </p>
1786
1787               <p>
1788                 When a package has a configuration and build routine
1789                 which takes a long time, or when the makefiles are
1790                 poorly designed, or when <tt>build</tt> needs to
1791                 run <tt>clean</tt> first, it is a good idea to
1792                 <tt>touch build</tt> when the build process is
1793                 complete.  This will ensure that if <tt>debian/rules
1794                 build</tt> is run again it will not rebuild the whole
1795                 program.<footnote>
1796                     Another common way to do this is for <tt>build</tt>
1797                     to depend on <prgn>build-stamp</prgn> and to do
1798                     nothing else, and for the <prgn>build-stamp</prgn>
1799                     target to do the building and to <tt>touch
1800                     build-stamp</tt> on completion.  This is
1801                     especially useful if the build routine creates a
1802                     file or directory called <tt>build</tt>; in such a
1803                     case, <tt>build</tt> will need to be listed as
1804                     a phony target (i.e., as a dependency of the
1805                     <tt>.PHONY</tt> target).  See the documentation of
1806                     <prgn>make</prgn> for more information on phony
1807                     targets.
1808                 </footnote>
1809               </p>
1810             </item>
1811
1812             <tag><tt>build-arch</tt> (optional),
1813                  <tt>build-indep</tt> (optional)
1814             </tag>
1815             <item>
1816               <p>
1817                 A package may also provide both of the targets
1818                 <tt>build-arch</tt> and <tt>build-indep</tt>.
1819                 The <tt>build-arch</tt> target, if provided, should
1820                 perform all the configuration and compilation required
1821                 for producing all architecture-dependant binary packages
1822                 (those packages for which the body of the
1823                 <tt>Architecture</tt> field in <tt>debian/control</tt>
1824                 is not <tt>all</tt>).
1825                 Similarly, the <tt>build-indep</tt> target, if
1826                 provided, should perform all the configuration and
1827                 compilation required for producing all
1828                 architecture-independent binary packages
1829                 (those packages for which the body of the
1830                 <tt>Architecture</tt> field in <tt>debian/control</tt>
1831                 is <tt>all</tt>).
1832                 The <tt>build</tt> target should depend on those of the
1833                 targets <tt>build-arch</tt> and <tt>build-indep</tt> that
1834                 are provided in the rules file.
1835               </p>
1836
1837               <p>
1838                 If one or both of the targets <tt>build-arch</tt> and
1839                 <tt>build-indep</tt> are not provided, then invoking
1840                 <file>debian/rules</file> with one of the not-provided
1841                 targets as arguments should produce a exit status code
1842                 of 2.  Usually this is provided automatically by make
1843                 if the target is missing.
1844               </p>
1845
1846               <p>
1847                 The <tt>build-arch</tt> and <tt>build-indep</tt> targets
1848                 must not do anything that might require root privilege.
1849               </p>
1850             </item>
1851
1852             <tag><tt>binary</tt>, <tt>binary-arch</tt>,
1853               <tt>binary-indep</tt>
1854             </tag>
1855             <item>
1856               <p>
1857                 The <tt>binary</tt> target must be all that is
1858                 necessary for the user to build the binary package(s)
1859                 produced from this source package.  It is
1860                 split into two parts: <prgn>binary-arch</prgn> builds
1861                 the binary packages which are specific to a particular
1862                 architecture, and <tt>binary-indep</tt> builds
1863                 those which are not.
1864               </p>
1865               <p>
1866                 <tt>binary</tt> may be (and commonly is) a target with
1867                 no commands which simply depends on
1868                 <tt>binary-arch</tt> and <tt>binary-indep</tt>.
1869               </p>
1870               <p>
1871                 Both <tt>binary-*</tt> targets should depend on the
1872                 <tt>build</tt> target, or on the appropriate
1873                 <tt>build-arch</tt> or <tt>build-indep</tt> target, if
1874                 provided, so that the package is built if it has not
1875                 been already.  It should then create the relevant
1876                 binary package(s), using <prgn>dpkg-gencontrol</prgn> to
1877                 make their control files and <prgn>dpkg-deb</prgn> to
1878                 build them and place them in the parent of the top
1879                 level directory.
1880               </p>
1881
1882               <p>
1883                 Both the <tt>binary-arch</tt> and
1884                 <tt>binary-indep</tt> targets <em>must</em> exist.
1885                 If one of them has nothing to do (which will always be
1886                 the case if the source generates only a single binary
1887                 package, whether architecture-dependent or not), it
1888                 must still exist and must always succeed.
1889               </p>
1890
1891               <p>
1892                 The <tt>binary</tt> targets must be invoked as
1893                 root.<footnote>
1894                     The <prgn>fakeroot</prgn> package often allows one
1895                     to build a package correctly even without being
1896                     root.
1897                 </footnote>
1898               </p>
1899             </item>
1900
1901             <tag><tt>clean</tt></tag>
1902             <item>
1903               <p>
1904                 This must undo any effects that the <tt>build</tt>
1905                 and <tt>binary</tt> targets may have had, except
1906                 that it should leave alone any output files created in
1907                 the parent directory by a run of a <tt>binary</tt>
1908                 target.
1909               </p>
1910
1911               <p>
1912                 If a <tt>build</tt> file is touched at the end of
1913                 the <tt>build</tt> target, as suggested above, it
1914                 should be removed as the first action that
1915                 <tt>clean</tt> performs, so that running
1916                 <tt>build</tt> again after an interrupted
1917                 <tt>clean</tt> doesn't think that everything is
1918                 already done.
1919               </p>
1920
1921               <p>
1922                 The <tt>clean</tt> target may need to be
1923                 invoked as root if <tt>binary</tt> has been
1924                 invoked since the last <tt>clean</tt>, or if
1925                 <tt>build</tt> has been invoked as root (since
1926                 <tt>build</tt> may create directories, for
1927                 example).
1928               </p>
1929             </item>
1930
1931             <tag><tt>get-orig-source</tt> (optional)</tag>
1932             <item>
1933               <p>
1934                 This target fetches the most recent version of the
1935                 original source package from a canonical archive site
1936                 (via FTP or WWW, for example), does any necessary
1937                 rearrangement to turn it into the original source
1938                 tar file format described below, and leaves it in the
1939                 current directory.
1940               </p>
1941
1942               <p>
1943                 This target may be invoked in any directory, and
1944                 should take care to clean up any temporary files it
1945                 may have left.
1946               </p>
1947
1948               <p>
1949                 This target is optional, but providing it if
1950                 possible is a good idea.
1951               </p>
1952             </item>
1953
1954             <tag><tt>patch</tt> (optional)</tag>
1955             <item>
1956               <p>
1957                 This target performs whatever additional actions are
1958                 required to make the source ready for editing (unpacking
1959                 additional upstream archives, applying patches, etc.).
1960                 It is recommended to be implemented for any package where
1961                 <tt>dpkg-source -x</tt> does not result in source ready
1962                 for additional modification.  See
1963                 <ref id="readmesource">.
1964               </p>
1965             </item>
1966           </taglist>
1967
1968         <p>
1969           The <tt>build</tt>, <tt>binary</tt> and
1970           <tt>clean</tt> targets must be invoked with the current
1971           directory being the package's top-level directory.
1972         </p>
1973
1974
1975         <p>
1976           Additional targets may exist in <file>debian/rules</file>,
1977           either as published or undocumented interfaces or for the
1978           package's internal use.
1979         </p>
1980
1981         <p>
1982           The architectures we build on and build for are determined
1983           by <prgn>make</prgn> variables using the utility
1984           <qref id="pkg-dpkg-architecture"><prgn>dpkg-architecture</prgn></qref>.
1985           You can determine the
1986           Debian architecture and the GNU style architecture
1987           specification string for the build machine (the machine type
1988           we are building on) as well as for the host machine (the
1989           machine type we are building for).  Here is a list of
1990           supported <prgn>make</prgn> variables:
1991           <list compact="compact">
1992             <item>
1993                 <tt>DEB_*_ARCH</tt> (the Debian architecture)
1994             </item>
1995             <item>
1996                 <tt>DEB_*_ARCH_CPU</tt> (the Debian CPU name)
1997             </item>
1998             <item>
1999                 <tt>DEB_*_ARCH_OS</tt> (the Debian System name)
2000             </item>
2001             <item>
2002                 <tt>DEB_*_GNU_TYPE</tt> (the GNU style architecture
2003                 specification string)
2004             </item>
2005             <item>
2006                 <tt>DEB_*_GNU_CPU</tt> (the CPU part of
2007                 <tt>DEB_*_GNU_TYPE</tt>)
2008             </item>
2009             <item>
2010                 <tt>DEB_*_GNU_SYSTEM</tt> (the System part of
2011                 <tt>DEB_*_GNU_TYPE</tt>)
2012           </list>
2013           where <tt>*</tt> is either <tt>BUILD</tt> for specification of
2014           the build machine or <tt>HOST</tt> for specification of the
2015           host machine.
2016         </p>
2017
2018         <p>
2019           Backward compatibility can be provided in the rules file
2020           by setting the needed variables to suitable default
2021           values; please refer to the documentation of
2022           <prgn>dpkg-architecture</prgn> for details.
2023         </p>
2024
2025         <p>
2026           It is important to understand that the <tt>DEB_*_ARCH</tt>
2027           string only determines which Debian architecture we are
2028           building on or for. It should not be used to get the CPU
2029           or system information; the <tt>DEB_*_ARCH_CPU</tt> and
2030           <tt>DEB_*_ARCH_OS</tt> variables should be used for that.
2031           GNU style variables should generally only be used with upstream
2032           build systems.
2033         </p>
2034
2035         <sect1 id="debianrules-options">
2036           <heading><file>debian/rules</file> and
2037             <tt>DEB_BUILD_OPTIONS</tt></heading>
2038
2039           <p>
2040             Supporting the standardized environment variable
2041             <tt>DEB_BUILD_OPTIONS</tt> is recommended.  This variable can
2042             contain several flags to change how a package is compiled and
2043             built.  Each flag must be in the form <var>flag</var> or
2044             <var>flag</var>=<var>options</var>.  If multiple flags are
2045             given, they must be separated by whitespace.<footnote>
2046               Some packages support any delimiter, but whitespace is the
2047               easiest to parse inside a makefile and avoids ambiguity with
2048               flag values that contain commas.
2049             </footnote>
2050             <var>flag</var> must start with a lowercase letter
2051             (<tt>a-z</tt>) and consist only of lowercase letters,
2052             numbers (<tt>0-9</tt>), and the characters
2053             <tt>-</tt> and <tt>_</tt> (hyphen and underscore).
2054             <var>options</var> must not contain whitespace.  The same
2055             tag should not be given multiple times with conflicting
2056             values.  Package maintainers may assume that
2057             <tt>DEB_BUILD_OPTIONS</tt> will not contain conflicting tags.
2058           </p>
2059
2060           <p>
2061             The meaning of the following tags has been standardized:
2062             <taglist>
2063               <tag>nocheck</tag>
2064               <item>
2065                   This tag says to not run any build-time test suite
2066                   provided by the package.
2067               </item>
2068               <tag>noopt</tag>
2069               <item>
2070                   The presence of this tag means that the package should
2071                   be compiled with a minimum of optimization.  For C
2072                   programs, it is best to add <tt>-O0</tt> to
2073                   <tt>CFLAGS</tt> (although this is usually the default).
2074                   Some programs might fail to build or run at this level
2075                   of optimization; it may be necessary to use
2076                   <tt>-O1</tt>, for example.
2077               </item>
2078               <tag>nostrip</tag>
2079               <item>
2080                   This tag means that the debugging symbols should not be
2081                   stripped from the binary during installation, so that
2082                   debugging information may be included in the package.
2083               </item>
2084               <tag>parallel=n</tag>
2085               <item>
2086                   This tag means that the package should be built using up
2087                   to <tt>n</tt> parallel processes if the package build
2088                   system supports this.<footnote>
2089                       Packages built with <tt>make</tt> can often implement
2090                       this by passing the <tt>-j</tt><var>n</var> option to
2091                       <tt>make</tt>.
2092                   </footnote>
2093                   If the package build system does not support parallel
2094                   builds, this string must be ignored.  If the package
2095                   build system only supports a lower level of concurrency
2096                   than <var>n</var>, the package should be built using as
2097                   many parallel processes as the package build system
2098                   supports.  It is up to the package maintainer to decide
2099                   whether the package build times are long enough and the
2100                   package build system is robust enough to make supporting
2101                   parallel builds worthwhile.
2102                </item>
2103             </taglist>
2104           </p>
2105
2106           <p>
2107             Unknown flags must be ignored by <file>debian/rules</file>.
2108           </p>
2109
2110           <p>
2111             The following makefile snippet is an example of how one may
2112             implement the build options; you will probably have to
2113             massage this example in order to make it work for your
2114             package.
2115             <example compact="compact">
2116 CFLAGS = -Wall -g
2117 INSTALL = install
2118 INSTALL_FILE    = $(INSTALL) -p    -o root -g root  -m  644
2119 INSTALL_PROGRAM = $(INSTALL) -p    -o root -g root  -m  755
2120 INSTALL_SCRIPT  = $(INSTALL) -p    -o root -g root  -m  755
2121 INSTALL_DIR     = $(INSTALL) -p -d -o root -g root  -m  755
2122
2123 ifneq (,$(filter noopt,$(DEB_BUILD_OPTIONS)))
2124     CFLAGS += -O0
2125 else
2126     CFLAGS += -O2
2127 endif
2128 ifeq (,$(filter nostrip,$(DEB_BUILD_OPTIONS)))
2129     INSTALL_PROGRAM += -s
2130 endif
2131 ifneq (,$(filter parallel=%,$(DEB_BUILD_OPTIONS)))
2132     NUMJOBS = $(patsubst parallel=%,%,$(filter parallel=%,$(DEB_BUILD_OPTIONS)))
2133     MAKEFLAGS += -j$(NUMJOBS)
2134 endif
2135
2136 build:
2137         # ...
2138 ifeq (,$(filter nocheck,$(DEB_BUILD_OPTIONS)))
2139         # Code to run the package test suite.
2140 endif
2141             </example>
2142           </p>
2143         </sect1>
2144       </sect>
2145
2146 <!-- FIXME: section pkg-srcsubstvars is the same as substvars -->
2147       <sect id="substvars">
2148         <heading>Variable substitutions: <file>debian/substvars</file></heading>
2149
2150         <p>
2151           When <prgn>dpkg-gencontrol</prgn>,
2152           <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
2153           generate control files they perform variable substitutions
2154           on their output just before writing it.  Variable
2155           substitutions have the form <tt>${<var>variable</var>}</tt>.
2156           The optional file <file>debian/substvars</file> contains
2157           variable substitutions to be used; variables can also be set
2158           directly from <file>debian/rules</file> using the <tt>-V</tt>
2159           option to the source packaging commands, and certain
2160           predefined variables are also available.
2161         </p>
2162
2163         <p>
2164           The <file>debian/substvars</file> file is usually generated and
2165           modified dynamically by <file>debian/rules</file> targets, in
2166           which case it must be removed by the <tt>clean</tt> target.
2167         </p>
2168
2169         <p>
2170           See <manref name="deb-substvars" section="5"> for full
2171           details about source variable substitutions, including the
2172           format of <file>debian/substvars</file>.</p>
2173       </sect>
2174
2175       <sect id="debianwatch">
2176         <heading>Optional upstream source location: <file>debian/watch</file></heading>
2177
2178         <p>
2179           This is an optional, recommended control file for the
2180           <tt>uscan</tt> utility which defines how to automatically
2181           scan ftp or http sites for newly available updates of the
2182           package. This is used by <url id="
2183           http://dehs.alioth.debian.org/"> and other Debian QA tools
2184           to help with quality control and maintenance of the
2185           distribution as a whole.
2186         </p>
2187
2188       </sect>
2189
2190       <sect id="debianfiles">
2191         <heading>Generated files list: <file>debian/files</file></heading>
2192
2193         <p>
2194           This file is not a permanent part of the source tree; it
2195           is used while building packages to record which files are
2196           being generated.  <prgn>dpkg-genchanges</prgn> uses it
2197           when it generates a <file>.changes</file> file.
2198         </p>
2199
2200         <p>
2201           It should not exist in a shipped source package, and so it
2202           (and any backup files or temporary files such as
2203           <file>files.new</file><footnote>
2204               <file>files.new</file> is used as a temporary file by
2205               <prgn>dpkg-gencontrol</prgn> and
2206               <prgn>dpkg-distaddfile</prgn> - they write a new
2207               version of <tt>files</tt> here before renaming it,
2208               to avoid leaving a corrupted copy if an error
2209               occurs.
2210           </footnote>) should be removed by the
2211           <tt>clean</tt> target.  It may also be wise to
2212           ensure a fresh start by emptying or removing it at the
2213           start of the <tt>binary</tt> target.
2214         </p>
2215
2216         <p>
2217           When <prgn>dpkg-gencontrol</prgn> is run for a binary
2218           package, it adds an entry to <file>debian/files</file> for the
2219           <file>.deb</file> file that will be created when <tt>dpkg-deb
2220           --build</tt> is run for that binary package.  So for most
2221           packages all that needs to be done with this file is to
2222           delete it in the <tt>clean</tt> target.
2223         </p>
2224
2225         <p>
2226           If a package upload includes files besides the source
2227           package and any binary packages whose control files were
2228           made with <prgn>dpkg-gencontrol</prgn> then they should be
2229           placed in the parent of the package's top-level directory
2230           and <prgn>dpkg-distaddfile</prgn> should be called to add
2231           the file to the list in <file>debian/files</file>.</p>
2232       </sect>
2233
2234       <sect id="embeddedfiles">
2235         <heading>Convenience copies of code</heading>
2236
2237         <p>
2238           Some software packages include in their distribution convenience
2239           copies of code from other software packages, generally so that
2240           users compiling from source don't have to download multiple
2241           packages.  Debian packages should not make use of these
2242           convenience copies unless the included package is explicitly
2243           intended to be used in this way.<footnote>
2244             For example, parts of the GNU build system work like this.
2245           </footnote>
2246           If the included code is already in the Debian archive in the
2247           form of a library, the Debian packaging should ensure that
2248           binary packages reference the libraries already in Debian and
2249           the convenience copy is not used.  If the included code is not
2250           already in Debian, it should be packaged separately as a
2251           prerequisite if possible.
2252           <footnote>
2253             Having multiple copies of the same code in Debian is
2254             inefficient, often creates either static linking or shared
2255             library conflicts, and, most importantly, increases the
2256             difficulty of handling security vulnerabilities in the
2257             duplicated code.
2258           </footnote>
2259         </p>
2260       </sect>
2261
2262       <sect id="readmesource">
2263         <heading>Source package handling:
2264           <file>debian/README.source</file></heading>
2265
2266         <p>
2267           If running <prgn>dpkg-source -x</prgn> on a source package
2268           doesn't produce the source of the package, ready for editing,
2269           and allow one to make changes and run
2270           <prgn>dpkg-buildpackage</prgn> to produce a modified package
2271           without taking any additional steps, creating a
2272           <file>debian/README.source</file> documentation file is
2273           recommended.  This file should explain how to do all of the
2274           following:
2275             <enumlist>
2276               <item>Generate the fully patched source, in a form ready for
2277               editing, that would be built to create Debian
2278               packages.  Doing this with a <tt>patch</tt> target in
2279               <file>debian/rules</file> is recommended; see
2280               <ref id="debianrules">.</item>
2281               <item>Modify the source and save those modifications so that
2282               they will be applied when building the package.</item>
2283               <item>Remove source modifications that are currently being
2284               applied when building the package.</item>
2285               <item>Optionally, document what steps are necessary to
2286               upgrade the Debian source package to a new upstream version,
2287               if applicable.</item>
2288             </enumlist>
2289           This explanation should include specific commands and mention
2290           any additional required Debian packages.  It should not assume
2291           familiarity with any specific Debian packaging system or patch
2292           management tools.
2293         </p>
2294
2295         <p>
2296           This explanation may refer to a documentation file installed by
2297           one of the package's build dependencies provided that the
2298           referenced documentation clearly explains these tasks and is not
2299           a general reference manual.
2300         </p>
2301
2302         <p>
2303           <file>debian/README.source</file> may also include any other
2304           information that would be helpful to someone modifying the
2305           source package.  Even if the package doesn't fit the above
2306           description, maintainers are encouraged to document in a
2307           <file>debian/README.source</file> file any source package with a
2308           particularly complex or unintuitive source layout or build
2309           system (for example, a package that builds the same source
2310           multiple times to generate different binary packages).
2311         </p>
2312       </sect>
2313     </chapt>
2314
2315
2316     <chapt id="controlfields">
2317       <heading>Control files and their fields</heading>
2318
2319       <p>
2320         The package management system manipulates data represented in
2321         a common format, known as <em>control data</em>, stored in
2322         <em>control files</em>.
2323         Control files are used for source packages, binary packages and
2324         the <file>.changes</file> files which control the installation
2325         of uploaded files<footnote>
2326             <prgn>dpkg</prgn>'s internal databases are in a similar
2327             format.
2328         </footnote>.
2329       </p>
2330
2331       <sect id="controlsyntax">
2332         <heading>Syntax of control files</heading>
2333
2334         <p>
2335           A control file consists of one or more paragraphs of
2336           fields<footnote>
2337                 The paragraphs are also sometimes referred to as stanzas.
2338           </footnote>.
2339           The paragraphs are separated by blank lines.  Some control
2340           files allow only one paragraph; others allow several, in
2341           which case each paragraph usually refers to a different
2342           package.  (For example, in source packages, the first
2343           paragraph refers to the source package, and later paragraphs
2344           refer to binary packages generated from the source.)
2345         </p>
2346
2347         <p>
2348           Each paragraph consists of a series of data fields; each
2349           field consists of the field name, followed by a colon and
2350           then the data/value associated with that field.  It ends at
2351           the end of the (logical) line.  Horizontal whitespace
2352           (spaces and tabs) may occur immediately before or after the
2353           value and is ignored there; it is conventional to put a
2354           single space after the colon.  For example, a field might
2355           be:
2356           <example compact="compact">
2357 Package: libc6
2358           </example>
2359           the field name is <tt>Package</tt> and the field value
2360           <tt>libc6</tt>.
2361         </p>
2362
2363         <p>
2364           Many fields' values may span several lines; in this case
2365           each continuation line must start with a space or a tab.
2366           Any trailing spaces or tabs at the end of individual
2367           lines of a field value are ignored. 
2368         </p>
2369
2370         <p>
2371           In fields where it is specified that lines may not wrap,
2372           only a single line of data is allowed and whitespace is not
2373           significant in a field body. Whitespace must not appear
2374           inside names (of packages, architectures, files or anything
2375           else) or version numbers, or between the characters of
2376           multi-character version relationships.
2377         </p>
2378
2379         <p>
2380           Field names are not case-sensitive, but it is usual to
2381           capitalize the field names using mixed case as shown below.
2382           Field values are case-sensitive unless the description of the
2383           field says otherwise.
2384         </p>
2385
2386         <p>
2387           Blank lines, or lines consisting only of spaces and tabs,
2388           are not allowed within field values or between fields - that
2389           would mean a new paragraph.
2390         </p>
2391
2392         <p>
2393           All control files must be encoded in UTF-8.
2394         </p>
2395       </sect>
2396
2397       <sect id="sourcecontrolfiles">
2398         <heading>Source package control files -- <file>debian/control</file></heading>
2399
2400         <p>
2401           The <file>debian/control</file> file contains the most vital
2402           (and version-independent) information about the source package
2403           and about the binary packages it creates.
2404         </p>
2405
2406         <p>
2407           The first paragraph of the control file contains information about
2408           the source package in general. The subsequent sets each describe a
2409           binary package that the source tree builds.
2410         </p>
2411
2412         <p>
2413           The fields in the general paragraph (the first one, for the source
2414           package) are:
2415
2416           <list compact="compact">
2417             <item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
2418             <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
2419             <item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
2420             <item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
2421             <item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
2422             <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
2423             <item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
2424             <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
2425           </list>
2426         </p>
2427
2428         <p>
2429           The fields in the binary package paragraphs are:
2430
2431           <list compact="compact">
2432             <item><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</item>
2433             <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (mandatory)</item>
2434             <item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
2435             <item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
2436             <item><qref id="f-Essential"><tt>Essential</tt></qref></item>
2437             <item><qref id="binarydeps"><tt>Depends</tt> et al</qref></item>
2438             <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
2439             <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
2440           </list>
2441         </p>
2442
2443         <p>
2444           The syntax and semantics of the fields are described below.
2445         </p>
2446
2447 <!-- stuff -->
2448
2449         <p>
2450           These fields are used by <prgn>dpkg-gencontrol</prgn> to
2451           generate control files for binary packages (see below), by
2452           <prgn>dpkg-genchanges</prgn> to generate the
2453           <tt>.changes</tt> file to accompany the upload, and by
2454           <prgn>dpkg-source</prgn> when it creates the
2455           <file>.dsc</file> source control file as part of a source
2456           archive. Many fields are permitted to span multiple lines in
2457           <file>debian/control</file> but not in any other control
2458           file. These tools are responsible for removing the line
2459           breaks from such fields when using fields from
2460           <file>debian/control</file> to generate other control files.
2461         </p>
2462
2463         <p>
2464           The fields here may contain variable references - their
2465           values will be substituted by <prgn>dpkg-gencontrol</prgn>,
2466           <prgn>dpkg-genchanges</prgn> or <prgn>dpkg-source</prgn>
2467           when they generate output control files.
2468           See <ref id="substvars"> for details.
2469         </p>
2470
2471         <p>
2472           In addition to the control file syntax described <qref
2473           id="controlsyntax">above</qref>, this file may also contain
2474           comment lines starting with <tt>#</tt> without any preceding
2475           whitespace.  All such lines are ignored, even in the middle of
2476           continuation lines for a multiline field, and do not end a
2477           multiline field.
2478         </p>
2479
2480       </sect>
2481
2482       <sect id="binarycontrolfiles">
2483         <heading>Binary package control files -- <file>DEBIAN/control</file></heading>
2484
2485         <p>
2486           The <file>DEBIAN/control</file> file contains the most vital
2487           (and version-dependent) information about a binary package.
2488         </p>
2489
2490         <p>
2491           The fields in this file are:
2492
2493           <list compact="compact">
2494             <item><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</item>
2495             <item><qref id="f-Source"><tt>Source</tt></qref></item>
2496             <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
2497             <item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
2498             <item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
2499             <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (mandatory)</item>
2500             <item><qref id="f-Essential"><tt>Essential</tt></qref></item>
2501             <item><qref id="binarydeps"><tt>Depends</tt> et al</qref></item>
2502             <item><qref id="f-Installed-Size"><tt>Installed-Size</tt></qref></item>
2503             <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
2504             <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
2505             <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
2506           </list>
2507         </p>
2508       </sect>
2509
2510       <sect id="debiansourcecontrolfiles">
2511         <heading>Debian source control files -- <tt>.dsc</tt></heading>
2512
2513         <p>
2514           This file contains a series of fields, identified and
2515           separated just like the fields in the control file of
2516           a binary package.  The fields are listed below; their
2517           syntax is described above, in <ref id="pkg-controlfields">.
2518
2519         <list compact="compact">
2520           <item><qref id="f-Format"><tt>Format</tt></qref> (mandatory)</item>
2521           <item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
2522           <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
2523           <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
2524           <item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
2525           <item><qref id="f-Binary"><tt>Binary</tt></qref></item>
2526           <item><qref id="f-Architecture"><tt>Architecture</tt></qref></item>
2527           <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
2528           <item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
2529           <item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
2530           <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
2531         </list>
2532         </p>
2533
2534         <p>
2535           The source package control file is generated by
2536           <prgn>dpkg-source</prgn> when it builds the source
2537           archive, from other files in the source package,
2538           described above.  When unpacking, it is checked against
2539           the files and directories in the other parts of the
2540           source package.
2541         </p>
2542
2543       </sect>
2544
2545       <sect id="debianchangesfiles">
2546         <heading>Debian changes files -- <file>.changes</file></heading>
2547
2548         <p>
2549           The .changes files are used by the Debian archive maintenance
2550           software to process updates to packages. They contain one
2551           paragraph which contains information from the
2552           <tt>debian/control</tt> file and other data about the
2553           source package gathered via <tt>debian/changelog</tt>
2554           and <tt>debian/rules</tt>.
2555         </p>
2556
2557         <p>
2558           The fields in this file are:
2559
2560           <list compact="compact">
2561             <item><qref id="f-Format"><tt>Format</tt></qref> (mandatory)</item>
2562             <item><qref id="f-Date"><tt>Date</tt></qref> (mandatory)</item>
2563             <item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
2564             <item><qref id="f-Binary"><tt>Binary</tt></qref> (mandatory)</item>
2565             <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (mandatory)</item>
2566             <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
2567             <item><qref id="f-Distribution"><tt>Distribution</tt></qref> (mandatory)</item>
2568             <item><qref id="f-Urgency"><tt>Urgency</tt></qref> (recommended)</item>
2569             <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
2570             <item><qref id="f-Changed-By"><tt>Changed-By</tt></qref></item>
2571             <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
2572             <item><qref id="f-Closes"><tt>Closes</tt></qref></item>
2573             <item><qref id="f-Changes"><tt>Changes</tt></qref> (mandatory)</item>
2574             <item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
2575           </list>
2576         </p>
2577       </sect>
2578
2579       <sect id="controlfieldslist">
2580         <heading>List of fields</heading>
2581
2582         <sect1 id="f-Source">
2583           <heading><tt>Source</tt></heading>
2584
2585           <p>
2586             This field identifies the source package name.
2587           </p>
2588
2589           <p>
2590             In <file>debian/control</file> or a <file>.dsc</file> file,
2591             this field must contain only the name of the source package.
2592           </p>
2593
2594           <p>
2595             In a binary package control file or a <file>.changes</file>
2596             file, the source package name may be followed by a version
2597             number in parentheses<footnote>
2598                 It is customary to leave a space after the package name
2599                 if a version number is specified.
2600             </footnote>.
2601             This version number may be omitted (and is, by
2602             <prgn>dpkg-gencontrol</prgn>) if it has the same value as
2603             the <tt>Version</tt> field of the binary package in
2604             question.  The field itself may be omitted from a binary
2605             package control file when the source package has the same
2606             name and version as the binary package.
2607           </p>
2608
2609           <p>
2610             Package names (both source and binary,
2611             see <ref id="f-Package">) must consist only of lower case
2612             letters (<tt>a-z</tt>), digits (<tt>0-9</tt>), plus
2613             (<tt>+</tt>) and minus (<tt>-</tt>) signs, and periods
2614             (<tt>.</tt>).  They must be at least two characters long and
2615             must start with an alphanumeric character.
2616           </p>
2617         </sect1>
2618
2619         <sect1 id="f-Maintainer">
2620           <heading><tt>Maintainer</tt></heading>
2621
2622           <p>
2623             The package maintainer's name and email address.  The name
2624             should come first, then the email address inside angle
2625             brackets <tt>&lt;&gt</tt> (in RFC822 format).
2626           </p>
2627
2628           <p>
2629             If the maintainer's name contains a full stop then the
2630             whole field will not work directly as an email address due
2631             to a misfeature in the syntax specified in RFC822; a
2632             program using this field as an address must check for this
2633             and correct the problem if necessary (for example by
2634             putting the name in round brackets and moving it to the
2635             end, and bringing the email address forward).
2636           </p>
2637         </sect1>
2638
2639         <sect1 id="f-Uploaders">
2640           <heading><tt>Uploaders</tt></heading>
2641
2642           <p>
2643             List of the names and email addresses of co-maintainers of
2644             the package, if any. If the package has other maintainers
2645             beside the one named in the 
2646             <qref id="f-Maintainer">Maintainer field</qref>, their
2647             names and email addresses should be listed here. The
2648             format is the same as that of the Maintainer tag, and
2649             multiple entries should be comma separated. Currently,
2650             this field is restricted to a single line of data.  This
2651             is an optional field.
2652           </p>
2653           <p>
2654             Any parser that interprets the Uploaders field in
2655             <file>debian/control</file> must permit it to span multiple
2656             lines.  Line breaks in an Uploaders field that spans multiple
2657             lines are not significant and the semantics of the field are
2658             the same as if the line breaks had not been present.
2659           </p>
2660         </sect1>
2661
2662         <sect1 id="f-Changed-By">
2663           <heading><tt>Changed-By</tt></heading>
2664
2665           <p>
2666             The name and email address of the person who changed the
2667             said package. Usually the name of the maintainer.
2668             All the rules for the Maintainer field apply here, too.
2669           </p>
2670         </sect1>
2671
2672         <sect1 id="f-Section">
2673           <heading><tt>Section</tt></heading>
2674
2675           <p>
2676             This field specifies an application area into which the package
2677             has been classified. See <ref id="subsections">.
2678           </p>
2679
2680           <p>
2681             When it appears in the <file>debian/control</file> file,
2682             it gives the value for the subfield of the same name in
2683             the <tt>Files</tt> field of the <file>.changes</file> file.
2684             It also gives the default for the same field in the binary
2685             packages.
2686           </p>
2687         </sect1>
2688
2689         <sect1 id="f-Priority">
2690           <heading><tt>Priority</tt></heading>
2691
2692           <p>
2693             This field represents how important that it is that the user
2694             have the package installed. See <ref id="priorities">.
2695           </p>
2696
2697           <p>
2698             When it appears in the <file>debian/control</file> file,
2699             it gives the value for the subfield of the same name in
2700             the <tt>Files</tt> field of the <file>.changes</file> file.
2701             It also gives the default for the same field in the binary
2702             packages.
2703           </p>
2704         </sect1>
2705
2706         <sect1 id="f-Package">
2707           <heading><tt>Package</tt></heading>
2708
2709           <p>
2710             The name of the binary package.
2711           </p>
2712
2713           <p>
2714             Binary package names must follow the same syntax and
2715             restrictions as source package names.  See <ref id="f-Source">
2716             for the details.
2717           </p>
2718         </sect1>
2719
2720         <sect1 id="f-Architecture">
2721           <heading><tt>Architecture</tt></heading>
2722
2723           <p>
2724             Depending on context and the control file used, the
2725             <tt>Architecture</tt> field can include the following sets of
2726             values:
2727             <list>
2728                 <item>A unique single word identifying a Debian machine
2729                       architecture as described in <ref id="arch-spec">.
2730                 <item><tt>all</tt>, which indicates an
2731                       architecture-independent package.
2732                 <item><tt>any</tt>, which indicates a package available
2733                       for building on any architecture.
2734                 <item><tt>source</tt>, which indicates a source package.
2735             </list>
2736           </p>
2737
2738           <p>
2739             In the main <file>debian/control</file> file in the source
2740             package, this field may contain the special value
2741             <tt>any</tt>, the special value <tt>all</tt>, or a list of
2742             architectures separated by spaces.  If <tt>any</tt> or
2743             <tt>all</tt> appear, they must be the entire contents of the
2744             field.  Most packages will use either <tt>any</tt> or
2745             <tt>all</tt>.  Specifying a specific list of architectures is
2746             for the minority of cases where a program is not portable or
2747             is not useful on some architectures, and where possible the
2748             program should be made portable instead.
2749           </p>
2750
2751           <p>
2752             In the source package control file <file>.dsc</file>, this
2753             field may contain either the special value <tt>any</tt> or a
2754             list of architectures separated by spaces. If a list is given,
2755             it may include (or consist solely of) the special value
2756             <tt>all</tt>.  In other words, in <file>.dsc</file> files
2757             unlike the <file>debian/control</file>, <tt>all</tt> may occur
2758             in combination with specific architectures.  The
2759             <tt>Architecture</tt> field in the source package control file
2760             <file>.dsc</file> is generally constructed from the
2761             <tt>Architecture</tt> fields in the
2762             <file>debian/control</file> in the source package.
2763           </p>
2764
2765           <p>
2766             Specifying <tt>any</tt> indicates that the source package
2767             isn't dependent on any particular architecture and should
2768             compile fine on any one. The produced binary package(s)
2769             will either be specific to whatever the current build
2770             architecture is or will be architecture-independent.
2771           </p>
2772
2773           <p>
2774             Specifying only <tt>all</tt> indicates that the source package
2775             will only build architecture-independent packages.  If this is
2776             the case, <tt>all</tt> must be used rather than <tt>any</tt>;
2777             <tt>any</tt> implies that the source package will build at
2778             least one architecture-dependent package.
2779           </p>
2780
2781           <p>
2782             Specifying a list of architectures indicates that the source
2783             will build an architecture-dependent package, and will only
2784             work correctly on the listed architectures.  If the source
2785             package also builds at least one architecture-independent
2786             package, <tt>all</tt> will also be included in the list.
2787           </p>
2788
2789           <p>
2790             In a <file>.changes</file> file, the <tt>Architecture</tt>
2791             field lists the architecture(s) of the package(s)
2792             currently being uploaded.  This will be a list; if the
2793             source for the package is also being uploaded, the special
2794             entry <tt>source</tt> is also present.  <tt>all</tt> will be
2795             present if any architecture-independent packages are being
2796             uploaded.  <tt>any</tt> may never occur in the
2797             <tt>Architecture</tt> field in the <file>.changes</file>
2798             file.
2799           </p>
2800
2801           <p>
2802             See <ref id="debianrules"> for information how to get the
2803             architecture for the build process.
2804           </p>
2805         </sect1>
2806
2807         <sect1 id="f-Essential">
2808           <heading><tt>Essential</tt></heading>
2809
2810           <p>
2811             This is a boolean field which may occur only in the
2812             control file of a binary package or in a per-package fields
2813             paragraph of a main source control data file.
2814           </p>
2815
2816           <p>
2817             If set to <tt>yes</tt> then the package management system
2818             will refuse to remove the package (upgrading and replacing
2819             it is still possible). The other possible value is <tt>no</tt>,
2820             which is the same as not having the field at all.
2821           </p>
2822         </sect1>
2823
2824         <sect1>
2825           <heading>Package interrelationship fields:
2826             <tt>Depends</tt>, <tt>Pre-Depends</tt>,
2827             <tt>Recommends</tt>, <tt>Suggests</tt>,
2828             <tt>Breaks</tt>, <tt>Conflicts</tt>,
2829             <tt>Provides</tt>, <tt>Replaces</tt>, <tt>Enhances</tt>
2830           </heading>
2831
2832           <p>
2833             These fields describe the package's relationships with
2834             other packages.  Their syntax and semantics are described
2835             in <ref id="relationships">.</p>
2836         </sect1>
2837
2838         <sect1 id="f-Standards-Version">
2839           <heading><tt>Standards-Version</tt></heading>
2840
2841           <p>
2842             The most recent version of the standards (the policy
2843             manual and associated texts) with which the package
2844             complies.
2845           </p>
2846
2847           <p>
2848             The version number has four components: major and minor
2849             version number and major and minor patch level.  When the
2850             standards change in a way that requires every package to
2851             change the major number will be changed.  Significant
2852             changes that will require work in many packages will be
2853             signaled by a change to the minor number.  The major patch
2854             level will be changed for any change to the meaning of the
2855             standards, however small; the minor patch level will be
2856             changed when only cosmetic, typographical or other edits
2857             are made which neither change the meaning of the document
2858             nor affect the contents of packages.
2859           </p>
2860
2861           <p>
2862             Thus only the first three components of the policy version
2863             are significant in the <em>Standards-Version</em> control
2864             field, and so either these three components or the all
2865             four components may be specified.<footnote>
2866                 In the past, people specified the full version number
2867                 in the Standards-Version field, for example "2.3.0.0".
2868                 Since minor patch-level changes don't introduce new
2869                 policy, it was thought it would be better to relax
2870                 policy and only require the first 3 components to be
2871                 specified, in this example "2.3.0".  All four
2872                 components may still be used if someone wishes to do so.
2873             </footnote>
2874           </p>
2875
2876         </sect1>
2877
2878         <sect1 id="f-Version">
2879           <heading><tt>Version</tt></heading>
2880
2881           <p>
2882             The version number of a package. The format is:
2883             [<var>epoch</var><tt>:</tt>]<var>upstream_version</var>[<tt>-</tt><var>debian_revision</var>]
2884           </p>
2885
2886           <p>
2887             The three components here are:
2888             <taglist>
2889               <tag><var>epoch</var></tag>
2890               <item>
2891                 <p>
2892                   This is a single (generally small) unsigned integer.  It
2893                   may be omitted, in which case zero is assumed.  If it is
2894                   omitted then the <var>upstream_version</var> may not
2895                   contain any colons.
2896                 </p>
2897
2898                 <p>
2899                   It is provided to allow mistakes in the version numbers
2900                   of older versions of a package, and also a package's
2901                   previous version numbering schemes, to be left behind.
2902                 </p>
2903               </item>
2904
2905               <tag><var>upstream_version</var></tag>
2906               <item>
2907                 <p>
2908                   This is the main part of the version number.  It is
2909                   usually the version number of the original ("upstream")
2910                   package from which the <file>.deb</file> file has been made,
2911                   if this is applicable.  Usually this will be in the same
2912                   format as that specified by the upstream author(s);
2913                   however, it may need to be reformatted to fit into the
2914                   package management system's format and comparison
2915                   scheme.
2916                 </p>
2917
2918                 <p>
2919                   The comparison behavior of the package management system
2920                   with respect to the <var>upstream_version</var> is
2921                   described below.  The <var>upstream_version</var>
2922                   portion of the version number is mandatory.
2923                 </p>
2924
2925                 <p>
2926                   The <var>upstream_version</var> may contain only
2927                   alphanumerics<footnote>
2928                         Alphanumerics are <tt>A-Za-z0-9</tt> only.
2929                   </footnote>
2930                   and the characters <tt>.</tt> <tt>+</tt> <tt>-</tt>
2931                   <tt>:</tt> <tt>~</tt> (full stop, plus, hyphen, colon,
2932                   tilde) and should start with a digit.  If there is no
2933                   <var>debian_revision</var> then hyphens are not allowed;
2934                   if there is no <var>epoch</var> then colons are not
2935                   allowed.
2936                 </p>
2937               </item>
2938
2939               <tag><var>debian_revision</var></tag>
2940               <item>
2941                 <p>
2942                   This part of the version number specifies the version of
2943                   the Debian package based on the upstream version.  It
2944                   may contain only alphanumerics and the characters
2945                   <tt>+</tt> <tt>.</tt> <tt>~</tt> (plus, full stop,
2946                   tilde) and is compared in the same way as the
2947                   <var>upstream_version</var> is.
2948                 </p>
2949
2950                 <p>
2951                   It is optional; if it isn't present then the
2952                   <var>upstream_version</var> may not contain a hyphen.
2953                   This format represents the case where a piece of
2954                   software was written specifically to be turned into a
2955                   Debian package, and so there is only one "debianisation"
2956                   of it and therefore no revision indication is required.
2957                 </p>
2958
2959                 <p>
2960                   It is conventional to restart the
2961                   <var>debian_revision</var> at <tt>1</tt> each time the
2962                   <var>upstream_version</var> is increased.
2963                 </p>
2964
2965                 <p>
2966                   The package management system will break the version
2967                   number apart at the last hyphen in the string (if there
2968                   is one) to determine the <var>upstream_version</var> and
2969                   <var>debian_revision</var>.  The absence of a
2970                   <var>debian_revision</var> is equivalent to a
2971                   <var>debian_revision</var> of <tt>0</tt>.
2972                 </p>
2973               </item>
2974             </taglist>
2975           </p>
2976
2977           <p>
2978             When comparing two version numbers, first the <var>epoch</var>
2979             of each are compared, then the <var>upstream_version</var> if
2980             <var>epoch</var> is equal, and then <var>debian_revision</var>
2981             if <var>upstream_version</var> is also equal.
2982             <var>epoch</var> is compared numerically.  The
2983             <var>upstream_version</var> and <var>debian_revision</var>
2984             parts are compared by the package management system using the
2985             following algorithm:
2986           </p>
2987
2988           <p>
2989             The strings are compared from left to right.
2990           </p>
2991
2992           <p>
2993             First the initial part of each string consisting entirely of
2994             non-digit characters is determined.  These two parts (one of
2995             which may be empty) are compared lexically.  If a difference
2996             is found it is returned.  The lexical comparison is a
2997             comparison of ASCII values modified so that all the letters
2998             sort earlier than all the non-letters and so that a tilde
2999             sorts before anything, even the end of a part.  For example,
3000             the following parts are in sorted order from earliest to
3001             latest: <tt>~~</tt>, <tt>~~a</tt>, <tt>~</tt>, the empty part,
3002             <tt>a</tt>.<footnote>
3003               One common use of <tt>~</tt> is for upstream pre-releases.
3004               For example, <tt>1.0~beta1~svn1245</tt> sorts earlier than
3005               <tt>1.0~beta1</tt>, which sorts earlier than <tt>1.0</tt>.
3006             </footnote>
3007           </p>
3008
3009           <p>
3010             Then the initial part of the remainder of each string which
3011             consists entirely of digit characters is determined.  The
3012             numerical values of these two parts are compared, and any
3013             difference found is returned as the result of the comparison.
3014             For these purposes an empty string (which can only occur at
3015             the end of one or both version strings being compared) counts
3016             as zero.
3017           </p>
3018
3019           <p>
3020             These two steps (comparing and removing initial non-digit
3021             strings and initial digit strings) are repeated until a
3022             difference is found or both strings are exhausted.
3023           </p>
3024
3025           <p>
3026             Note that the purpose of epochs is to allow us to leave behind
3027             mistakes in version numbering, and to cope with situations
3028             where the version numbering scheme changes.  It is
3029             <em>not</em> intended to cope with version numbers containing
3030             strings of letters which the package management system cannot
3031             interpret (such as <tt>ALPHA</tt> or <tt>pre-</tt>), or with
3032             silly orderings (the author of this manual has heard of a
3033             package whose versions went <tt>1.1</tt>, <tt>1.2</tt>,
3034             <tt>1.3</tt>, <tt>1</tt>, <tt>2.1</tt>, <tt>2.2</tt>,
3035             <tt>2</tt> and so forth).
3036           </p>
3037         </sect1>
3038
3039         <sect1 id="f-Description">
3040           <heading><tt>Description</tt></heading>
3041
3042           <p>
3043             In a source or binary control file, the <tt>Description</tt>
3044             field contains a description of the binary package, consisting
3045             of two parts, the synopsis or the short description, and the
3046             long description. The field's format is as follows:
3047           </p>
3048
3049           <p>
3050 <example>
3051         Description: &lt;single line synopsis&gt;
3052          &lt;extended description over several lines&gt;
3053 </example>
3054           </p>
3055
3056           <p>
3057             The lines in the extended description can have these formats:
3058           </p>
3059
3060           <p><list>
3061
3062             <item>
3063               Those starting with a single space are part of a paragraph.
3064               Successive lines of this form will be word-wrapped when
3065               displayed. The leading space will usually be stripped off.
3066             </item>
3067
3068             <item>
3069               Those starting with two or more spaces. These will be
3070               displayed verbatim. If the display cannot be panned
3071               horizontally, the displaying program will line wrap them "hard"
3072               (i.e., without taking account of word breaks). If it can they
3073               will be allowed to trail off to the right. None, one or two
3074               initial spaces may be deleted, but the number of spaces
3075               deleted from each line will be the same (so that you can have
3076               indenting work correctly, for example).
3077             </item>
3078
3079             <item>
3080               Those containing a single space followed by a single full stop
3081               character. These are rendered as blank lines. This is the
3082               <em>only</em> way to get a blank line<footnote>
3083                 Completely empty lines will not be rendered as blank lines.
3084                 Instead, they will cause the parser to think you're starting
3085                 a whole new record in the control file, and will therefore
3086                 likely abort with an error.
3087               </footnote>.
3088             </item>
3089
3090             <item>
3091               Those containing a space, a full stop and some more characters.
3092               These are for future expansion. Do not use them.
3093             </item>
3094
3095           </list></p>
3096
3097           <p>
3098             Do not use tab characters.  Their effect is not predictable.
3099           </p>
3100
3101           <p>
3102             See <ref id="descriptions"> for further information on this.
3103           </p>
3104
3105           <p>
3106             In a <file>.changes</file> file, the <tt>Description</tt>
3107             field contains a summary of the descriptions for the packages
3108             being uploaded.  For this case, the first line of the field
3109             value (the part on the same line as <tt>Description:</tt>) is
3110             always empty.  The content of the field is expressed as
3111             continuation lines, one line per package.  Each line is
3112             indented by one space and contains the name of a binary
3113             package, a space, a hyphen (<tt>-</tt>), a space, and the
3114             short description line from that package.
3115           </p>
3116         </sect1>
3117
3118         <sect1 id="f-Distribution">
3119           <heading><tt>Distribution</tt></heading>
3120
3121           <p>
3122             In a <file>.changes</file> file or parsed changelog output
3123             this contains the (space-separated) name(s) of the
3124             distribution(s) where this version of the package should
3125             be installed.  Valid distributions are determined by the
3126             archive maintainers.<footnote>
3127               Example distribution names in the Debian archive used in
3128               <file>.changes</file> files are:
3129                 <taglist compact="compact">
3130                   <tag><em>unstable</em></tag>
3131                   <item>
3132                     This distribution value refers to the
3133                     <em>developmental</em> part of the Debian distribution
3134                     tree.  Most new packages, new upstream versions of
3135                     packages and bug fixes go into the <em>unstable</em>
3136                     directory tree.
3137                   </item>
3138
3139                   <tag><em>experimental</em></tag>
3140                   <item>
3141                     The packages with this distribution value are deemed
3142                     by their maintainers to be high risk.  Oftentimes they
3143                     represent early beta or developmental packages from
3144                     various sources that the maintainers want people to
3145                     try, but are not ready to be a part of the other parts
3146                     of the Debian distribution tree.
3147                   </item>
3148                 </taglist>
3149
3150                 <p>
3151                   Others are used for updating stable releases or for
3152                   security uploads.  More information is available in the
3153                   Debian Developer's Reference, section "The Debian
3154                   archive".
3155                 </p>
3156             </footnote>
3157             The Debian archive software only supports listing a single
3158             distribution.  Migration of packages to other distributions is
3159             handled outside of the upload process.
3160           </p>
3161         </sect1>
3162
3163         <sect1 id="f-Date">
3164           <heading><tt>Date</tt></heading>
3165
3166           <p>
3167             This field includes the date the package was built or last edited.
3168           </p>
3169
3170           <p>
3171             The value of this field is usually extracted from the
3172             <file>debian/changelog</file> file - see
3173             <ref id="dpkgchangelog">).
3174           </p>
3175         </sect1>
3176
3177         <sect1 id="f-Format">
3178           <heading><tt>Format</tt></heading>
3179
3180           <p>
3181             This field specifies a format revision for the file.
3182             The most current format described in the Policy Manual
3183             is version <strong>1.5</strong>.  The syntax of the
3184             format value is the same as that of a package version
3185             number except that no epoch or Debian revision is allowed
3186             - see <ref id="f-Version">.
3187           </p>
3188         </sect1>
3189
3190         <sect1 id="f-Urgency">
3191           <heading><tt>Urgency</tt></heading>
3192
3193           <p>
3194             This is a description of how important it is to upgrade to
3195             this version from previous ones.  It consists of a single
3196             keyword taking one of the values <tt>low</tt>,
3197             <tt>medium</tt>, <tt>high</tt>, <tt>emergency</tt>, or
3198             <tt>critical</tt><footnote>
3199               Other urgency values are supported with configuration
3200               changes in the archive software but are not used in Debian.
3201               The urgency affects how quickly a package will be considered
3202               for inclusion into the <tt>testing</tt> distribution and
3203               gives an indication of the importance of any fixes included
3204               in the upload.  <tt>Emergency</tt> and <tt>critical</tt> are
3205               treated as synonymous.
3206             </footnote> (not case-sensitive) followed by an optional
3207             commentary (separated by a space) which is usually in
3208             parentheses.  For example:
3209
3210             <example>
3211   Urgency: low (HIGH for users of diversions)
3212             </example>
3213
3214           </p>
3215
3216           <p>
3217             The value of this field is usually extracted from the
3218             <file>debian/changelog</file> file - see
3219             <ref id="dpkgchangelog">.
3220           </p>
3221         </sect1>
3222
3223         <sect1 id="f-Changes">
3224           <heading><tt>Changes</tt></heading>
3225
3226           <p>
3227             This field contains the human-readable changes data, describing
3228             the differences between the last version and the current one.
3229           </p>
3230
3231           <p>
3232             The first line of the field value (the part on the same line
3233             as <tt>Changes:</tt>) is always empty.  The content of the
3234             field is expressed as continuation lines, with each line
3235             indented by at least one space.  Blank lines must be
3236             represented by a line consisting only of a space and a full
3237             stop (<tt>.</tt>).
3238           </p>
3239
3240           <p>
3241             The value of this field is usually extracted from the
3242             <file>debian/changelog</file> file - see
3243             <ref id="dpkgchangelog">).
3244           </p>
3245
3246           <p>
3247             Each version's change information should be preceded by a
3248             "title" line giving at least the version, distribution(s)
3249             and urgency, in a human-readable way.
3250           </p>
3251
3252           <p>
3253             If data from several versions is being returned the entry
3254             for the most recent version should be returned first, and
3255             entries should be separated by the representation of a
3256             blank line (the "title" line may also be followed by the
3257             representation of blank line).
3258           </p>
3259         </sect1>
3260
3261         <sect1 id="f-Binary">
3262           <heading><tt>Binary</tt></heading>
3263
3264           <p>
3265             This field is a list of binary packages.  Its syntax and
3266             meaning varies depending on the control file in which it
3267             appears.
3268           </p>
3269
3270           <p>
3271             When it appears in the <file>.dsc</file> file, it lists binary
3272             packages which a source package can produce, separated by
3273             commas<footnote>
3274                 A space after each comma is conventional.
3275             </footnote>.  It may span multiple lines.  The source package
3276             does not necessarily produce all of these binary packages for
3277             every architecture.  The source control file doesn't contain
3278             details of which architectures are appropriate for which of
3279             the binary packages.
3280           </p>
3281
3282           <p>
3283             When it appears in a <file>.changes</file> file, it lists the
3284             names of the binary packages being uploaded, separated by
3285             whitespace (not commas).  It may span multiple lines.
3286           </p>
3287         </sect1>
3288
3289         <sect1 id="f-Installed-Size">
3290           <heading><tt>Installed-Size</tt></heading>
3291
3292           <p>
3293             This field appears in the control files of binary packages,
3294             and in the <file>Packages</file> files.  It gives an estimate
3295             of the total amount of disk space required to install the
3296             named package.  Actual installed size may vary based on block
3297             size, file system properties, or actions taken by package
3298             maintainer scripts.
3299           </p>
3300
3301           <p>
3302             The disk space is given as the integer value of the estimated
3303             installed size in bytes, divided by 1024 and rounded up.
3304           </p>
3305         </sect1>
3306
3307         <sect1 id="f-Files">
3308           <heading><tt>Files</tt></heading>
3309
3310           <p>
3311             This field contains a list of files with information about
3312             each one.  The exact information and syntax varies with
3313             the context.
3314           </p>
3315
3316           <p>
3317             In all cases, Files is a multiline field.  The first line of
3318             the field value (the part on the same line as <tt>Files:</tt>)
3319             is always empty.  The content of the field is expressed as
3320             continuation lines, one line per file.  Each line must be
3321             indented by one space and contain a number of sub-fields,
3322             separated by spaces, as described below.
3323           </p>
3324
3325           <p>
3326             In the <file>.dsc</file> file, each line contains the MD5
3327             checksum, size and filename of the tar file and (if
3328             applicable) diff file which make up the remainder of the
3329             source package<footnote>
3330               That is, the parts which are not the <tt>.dsc</tt>.
3331             </footnote>.  For example:
3332             <example>
3333 Files:
3334  c6f698f19f2a2aa07dbb9bbda90a2754 571925 example_1.2.orig.tar.gz
3335  938512f08422f3509ff36f125f5873ba 6220 example_1.2-1.diff.gz
3336             </example>
3337             The exact forms of the filenames are described
3338             in <ref id="pkg-sourcearchives">.
3339           </p>
3340
3341           <p>
3342             In the <file>.changes</file> file this contains one line per
3343             file being uploaded.  Each line contains the MD5 checksum,
3344             size, section and priority and the filename.  For example:
3345             <example>
3346 Files:
3347  4c31ab7bfc40d3cf49d7811987390357 1428 text extra example_1.2-1.dsc
3348  c6f698f19f2a2aa07dbb9bbda90a2754 571925 text extra example_1.2.orig.tar.gz
3349  938512f08422f3509ff36f125f5873ba 6220 text extra example_1.2-1.diff.gz
3350  7c98fe853b3bbb47a00e5cd129b6cb56 703542 text extra example_1.2-1_i386.deb
3351             </example>
3352             The <qref id="f-Section">section</qref>
3353             and <qref id="f-Priority">priority</qref> are the values of
3354             the corresponding fields in the main source control file.  If
3355             no section or priority is specified then <tt>-</tt> should be
3356             used, though section and priority values must be specified for
3357             new packages to be installed properly.
3358           </p>
3359
3360           <p>
3361             The special value <tt>byhand</tt> for the section in a
3362             <tt>.changes</tt> file indicates that the file in question
3363             is not an ordinary package file and must by installed by
3364             hand by the distribution maintainers.  If the section is
3365             <tt>byhand</tt> the priority should be <tt>-</tt>.
3366           </p>
3367
3368           <p>
3369             If a new Debian revision of a package is being shipped and
3370             no new original source archive is being distributed the
3371             <tt>.dsc</tt> must still contain the <tt>Files</tt> field
3372             entry for the original source archive
3373             <file><var>package</var>-<var>upstream-version</var>.orig.tar.gz</file>,
3374             but the <file>.changes</file> file should leave it out.  In
3375             this case the original source archive on the distribution
3376             site must match exactly, byte-for-byte, the original
3377             source archive which was used to generate the
3378             <file>.dsc</file> file and diff which are being uploaded.</p>
3379         </sect1>
3380
3381         <sect1 id="f-Closes">
3382           <heading><tt>Closes</tt></heading>
3383
3384           <p>
3385             A space-separated list of bug report numbers that the upload
3386             governed by the .changes file closes.
3387           </p>
3388         </sect1>
3389
3390         <sect1 id="f-Homepage">
3391           <heading><tt>Homepage</tt></heading>
3392
3393           <p>
3394             The URL of the web site for this package, preferably (when
3395             applicable) the site from which the original source can be
3396             obtained and any additional upstream documentation or
3397             information may be found.  The content of this field is a
3398             simple URL without any surrounding characters such as
3399             <tt>&lt;&gt;</tt>.
3400           </p>
3401         </sect1>
3402
3403       </sect>
3404
3405       <sect>
3406         <heading>User-defined fields</heading>
3407
3408         <p>
3409           Additional user-defined fields may be added to the
3410           source package control file.  Such fields will be
3411           ignored, and not copied to (for example) binary or
3412           source package control files or upload control files.
3413         </p>
3414
3415         <p>
3416           If you wish to add additional unsupported fields to
3417           these output files you should use the mechanism
3418           described here.
3419         </p>
3420
3421         <p>
3422           Fields in the main source control information file with
3423           names starting <tt>X</tt>, followed by one or more of
3424           the letters <tt>BCS</tt> and a hyphen <tt>-</tt>, will
3425           be copied to the output files.  Only the part of the
3426           field name after the hyphen will be used in the output
3427           file.  Where the letter <tt>B</tt> is used the field
3428           will appear in binary package control files, where the
3429           letter <tt>S</tt> is used in source package control
3430           files and where <tt>C</tt> is used in upload control
3431           (<tt>.changes</tt>) files.
3432         </p>
3433
3434         <p>
3435           For example, if the main source information control file
3436           contains the field
3437           <example>
3438   XBS-Comment: I stand between the candle and the star.
3439           </example>
3440           then the binary and source package control files will contain the
3441           field
3442           <example>
3443   Comment: I stand between the candle and the star.
3444           </example>
3445         </p>
3446
3447       </sect>
3448
3449     </chapt>
3450
3451
3452     <chapt id="maintainerscripts">
3453       <heading>Package maintainer scripts and installation procedure</heading>
3454
3455       <sect>
3456         <heading>Introduction to package maintainer scripts</heading>
3457
3458         <p>
3459           It is possible to supply scripts as part of a package which
3460           the package management system will run for you when your
3461           package is installed, upgraded or removed.
3462         </p>
3463
3464         <p>
3465           These scripts are the files <prgn>preinst</prgn>,
3466           <prgn>postinst</prgn>, <prgn>prerm</prgn> and
3467           <prgn>postrm</prgn> in the control area of the package.
3468           They must be proper executable files; if they are scripts
3469           (which is recommended), they must start with the usual
3470           <tt>#!</tt> convention.  They should be readable and
3471           executable by anyone, and must not be world-writable.
3472         </p>
3473
3474         <p>
3475           The package management system looks at the exit status from
3476           these scripts.  It is important that they exit with a
3477           non-zero status if there is an error, so that the package
3478           management system can stop its processing.  For shell
3479           scripts this means that you <em>almost always</em> need to
3480           use <tt>set -e</tt> (this is usually true when writing shell
3481           scripts, in fact).  It is also important, of course, that
3482           they exit with a zero status if everything went well.
3483         </p>
3484
3485         <p>
3486           Additionally, packages interacting with users using
3487           <tt>debconf</tt> in the <prgn>postinst</prgn> script should
3488           install a <prgn>config</prgn> script  in the control area,
3489           see <ref id="maintscriptprompt"> for details.
3490         </p>
3491
3492         <p>
3493           When a package is upgraded a combination of the scripts from
3494           the old and new packages is called during the upgrade
3495           procedure.  If your scripts are going to be at all
3496           complicated you need to be aware of this, and may need to
3497           check the arguments to your scripts.
3498         </p>
3499
3500         <p>
3501           Broadly speaking the <prgn>preinst</prgn> is called before
3502           (a particular version of) a package is unpacked, and the
3503           <prgn>postinst</prgn> afterwards; the <prgn>prerm</prgn>
3504           before (a version of) a package is removed and the
3505           <prgn>postrm</prgn> afterwards.
3506         </p>
3507
3508         <p>
3509           Programs called from maintainer scripts should not normally
3510           have a path prepended to them. Before installation is
3511           started, the package management system checks to see if the
3512           programs <prgn>ldconfig</prgn>,
3513           <prgn>start-stop-daemon</prgn>, <prgn>install-info</prgn>,
3514           and <prgn>update-rc.d</prgn> can be found via the
3515           <tt>PATH</tt> environment variable. Those programs, and any
3516           other program that one would expect to be in the
3517           <tt>PATH</tt>, should thus be invoked without an absolute
3518           pathname. Maintainer scripts should also not reset the
3519           <tt>PATH</tt>, though they might choose to modify it by
3520           prepending or appending package-specific directories. These
3521           considerations really apply to all shell scripts.</p>
3522       </sect>
3523
3524       <sect id="idempotency">
3525         <heading>Maintainer scripts idempotency</heading>
3526
3527         <p>
3528           It is necessary for the error recovery procedures that the
3529           scripts be idempotent.  This means that if it is run
3530           successfully, and then it is called again, it doesn't bomb
3531           out or cause any harm, but just ensures that everything is
3532           the way it ought to be.  If the first call failed, or
3533           aborted half way through for some reason, the second call
3534           should merely do the things that were left undone the first
3535           time, if any, and exit with a success status if everything
3536           is OK.<footnote>
3537               This is so that if an error occurs, the user interrupts
3538               <prgn>dpkg</prgn> or some other unforeseen circumstance
3539               happens you don't leave the user with a badly-broken
3540               package when <prgn>dpkg</prgn> attempts to repeat the
3541               action.
3542           </footnote>
3543         </p>
3544       </sect>
3545
3546       <sect id="controllingterminal">
3547         <heading>Controlling terminal for maintainer scripts</heading>
3548
3549         <p>
3550           The maintainer scripts are guaranteed to run with a
3551           controlling terminal and can interact with the user.
3552           Because these scripts may be executed with standard output
3553           redirected into a pipe for logging purposes, Perl scripts
3554           should set unbuffered output by setting <tt>$|=1</tt> so
3555           that the output is printed immediately rather than being
3556           buffered.
3557         </p>
3558       </sect>
3559       <sect id="exitstatus">
3560         <heading>Exit status</heading>
3561
3562         <p>
3563           Each script must return a zero exit status for
3564           success, or a nonzero one for failure, since the package
3565           management system looks for the exit status of these scripts
3566           and determines what action to take next based on that datum.
3567         </p>
3568       </sect>
3569
3570       <sect id="mscriptsinstact"><heading>Summary of ways maintainer
3571           scripts are called
3572         </heading>
3573
3574         <p>
3575           <list compact="compact">
3576             <item>
3577               <var>new-preinst</var> <tt>install</tt>
3578             </item>
3579             <item>
3580               <var>new-preinst</var> <tt>install</tt> <var>old-version</var>
3581             </item>
3582             <item>
3583                 <var>new-preinst</var> <tt>upgrade</tt> <var>old-version</var>
3584             </item>
3585             <item>
3586                 <var>old-preinst</var> <tt>abort-upgrade</tt>
3587                 <var>new-version</var>
3588             </item>
3589           </list>
3590
3591         <p>
3592           <list compact="compact">
3593             <item>
3594                 <var>postinst</var> <tt>configure</tt>
3595                 <var>most-recently-configured-version</var>
3596             </item>
3597             <item>
3598                 <var>old-postinst</var> <tt>abort-upgrade</tt>
3599                 <var>new-version</var>
3600             </item>
3601             <item>
3602                 <var>conflictor's-postinst</var> <tt>abort-remove</tt>
3603                 <tt>in-favour</tt> <var>package</var>
3604                 <var>new-version</var>
3605             </item>
3606             <item>
3607                 <var>postinst</var> <tt>abort-remove</tt>
3608             </item>
3609             <item>
3610                 <var>deconfigured's-postinst</var>
3611                 <tt>abort-deconfigure</tt> <tt>in-favour</tt>
3612                 <var>failed-install-package</var> <var>version</var>
3613                 [<tt>removing</tt> <var>conflicting-package</var>
3614                 <var>version</var>]
3615             </item>
3616           </list>
3617
3618         <p>
3619           <list compact="compact">
3620             <item>
3621                 <var>prerm</var> <tt>remove</tt>
3622             </item>
3623             <item>
3624                 <var>old-prerm</var> <tt>upgrade</tt>
3625                 <var>new-version</var>
3626             </item>
3627             <item>
3628                 <var>new-prerm</var> <tt>failed-upgrade</tt>
3629                 <var>old-version</var>
3630             </item>
3631             <item>
3632                 <var>conflictor's-prerm</var> <tt>remove</tt>
3633                 <tt>in-favour</tt> <var>package</var>
3634                 <var>new-version</var>
3635             </item>
3636             <item>
3637                 <var>deconfigured's-prerm</var> <tt>deconfigure</tt>
3638                 <tt>in-favour</tt> <var>package-being-installed</var>
3639                 <var>version</var> [<tt>removing</tt>
3640                 <var>conflicting-package</var>
3641                 <var>version</var>]
3642             </item>
3643           </list>
3644
3645         <p>
3646           <list compact="compact">
3647             <item>
3648                 <var>postrm</var> <tt>remove</tt>
3649             </item>
3650             <item>
3651                 <var>postrm</var> <tt>purge</tt>
3652             </item>
3653             <item>
3654                 <var>old-postrm</var> <tt>upgrade</tt>
3655                 <var>new-version</var>
3656             </item>
3657             <item>
3658                 <var>new-postrm</var> <tt>failed-upgrade</tt>
3659                 <var>old-version</var>
3660             </item>
3661             <item>
3662                 <var>new-postrm</var> <tt>abort-install</tt>
3663             </item>
3664             <item>
3665                 <var>new-postrm</var> <tt>abort-install</tt>
3666                 <var>old-version</var>
3667             </item>
3668             <item>
3669                 <var>new-postrm</var> <tt>abort-upgrade</tt>
3670                 <var>old-version</var>
3671             </item>
3672             <item>
3673                 <var>disappearer's-postrm</var> <tt>disappear</tt>
3674                 <var>overwriter</var>
3675                 <var>overwriter-version</var>
3676             </item>
3677           </list>
3678         </p>
3679
3680
3681       <sect id="unpackphase">
3682         <heading>Details of unpack phase of installation or upgrade</heading>
3683
3684         <p>
3685           The procedure on installation/upgrade/overwrite/disappear
3686           (i.e., when running <tt>dpkg --unpack</tt>, or the unpack
3687           stage of <tt>dpkg --install</tt>) is as follows.  In each
3688           case, if a major error occurs (unless listed below) the
3689           actions are, in general, run backwards - this means that the
3690           maintainer scripts are run with different arguments in
3691           reverse order.  These are the "error unwind" calls listed
3692           below.
3693
3694           <enumlist>
3695             <item>
3696                 <enumlist>
3697                   <item>
3698                       If a version of the package is already installed, call
3699                       <example compact="compact">
3700 <var>old-prerm</var> upgrade <var>new-version</var>
3701                       </example>
3702                   </item>
3703                   <item>
3704                       If the script runs but exits with a non-zero
3705                       exit status, <prgn>dpkg</prgn> will attempt:
3706                       <example compact="compact">
3707 <var>new-prerm</var> failed-upgrade <var>old-version</var>
3708                       </example>
3709                       If this works, the upgrade continues. If this
3710                       does not work, the error unwind:
3711                       <example compact="compact">
3712 <var>old-postinst</var> abort-upgrade <var>new-version</var>
3713                       </example>
3714                       If this works, then the old-version is
3715                       "Installed", if not, the old version is in a
3716                       "Failed-Config" state.
3717                   </item>
3718                 </enumlist>
3719             </item>
3720
3721             <item>
3722                 If a "conflicting" package is being removed at the same time,
3723                 or if any package will be broken (due to <tt>Breaks</tt>):
3724                 <enumlist>
3725                   <item>
3726                       If <tt>--auto-deconfigure</tt> is
3727                       specified, call, for each package to be deconfigured
3728                       due to <tt>Breaks</tt>:
3729                       <example compact="compact">
3730 <var>deconfigured's-prerm</var> deconfigure \
3731   in-favour <var>package-being-installed</var> <var>version</var>
3732                       </example>
3733                       Error unwind:
3734                       <example compact="compact">
3735 <var>deconfigured's-postinst</var> abort-deconfigure \
3736   in-favour <var>package-being-installed-but-failed</var> <var>version</var>
3737                       </example>
3738                       The deconfigured packages are marked as
3739                       requiring configuration, so that if
3740                       <tt>--install</tt> is used they will be
3741                       configured again if possible.
3742                   </item>
3743                   <item>
3744                       If any packages depended on a conflicting
3745                       package being removed and <tt>--auto-deconfigure</tt> is
3746                       specified, call, for each such package:
3747                       <example compact="compact">
3748 <var>deconfigured's-prerm</var> deconfigure \
3749   in-favour <var>package-being-installed</var> <var>version</var> \
3750     removing <var>conflicting-package</var> <var>version</var>
3751                       </example>
3752                       Error unwind:
3753                       <example compact="compact">
3754 <var>deconfigured's-postinst</var> abort-deconfigure \
3755   in-favour <var>package-being-installed-but-failed</var> <var>version</var> \
3756     removing <var>conflicting-package</var> <var>version</var>
3757                       </example>
3758                       The deconfigured packages are marked as
3759                       requiring configuration, so that if
3760                       <tt>--install</tt> is used they will be
3761                       configured again if possible.
3762                   </item>
3763                   <item>
3764                       To prepare for removal of each conflicting package, call:
3765                       <example compact="compact">
3766 <var>conflictor's-prerm</var> remove \
3767   in-favour <var>package</var> <var>new-version</var>
3768                       </example>
3769                       Error unwind:
3770                       <example compact="compact">
3771 <var>conflictor's-postinst</var> abort-remove \
3772   in-favour <var>package</var> <var>new-version</var>
3773                       </example>
3774                   </item>
3775                 </enumlist>
3776             </item>
3777
3778             <item>
3779                 <enumlist>
3780                   <item>
3781                       If the package is being upgraded, call:
3782                       <example compact="compact">
3783 <var>new-preinst</var> upgrade <var>old-version</var>
3784                       </example>
3785                       If this fails, we call:
3786                       <example>
3787 <var>new-postrm</var> abort-upgrade <var>old-version</var>
3788                       </example>
3789                       <enumlist>
3790                         <item>
3791                           <p>
3792                             If that works, then
3793                             <example>
3794 <var>old-postinst</var> abort-upgrade <var>new-version</var>
3795                             </example>
3796                             is called. If this works, then the old version
3797                             is in an "Installed" state, or else it is left
3798                             in an "Unpacked" state.
3799                           </p>
3800                         </item>
3801                         <item>
3802                           <p>
3803                             If it fails, then the old version is left
3804                             in an "Half-Installed" state.
3805                           </p>
3806                         </item>
3807                       </enumlist>
3808                       
3809                   </item>
3810                   <item>
3811                       Otherwise, if the package had some configuration
3812                       files from a previous version installed (i.e., it
3813                       is in the "configuration files only" state):
3814                       <example compact="compact">
3815 <var>new-preinst</var> install <var>old-version</var>
3816                       </example>
3817                       Error unwind:
3818                       <example>
3819 <var>new-postrm</var> abort-install <var>old-version</var>
3820                       </example>
3821                       If this fails, the package is left in a
3822                       "Half-Installed" state, which requires a
3823                       reinstall. If it works, the packages is left in
3824                       a "Config Files" state.
3825                   </item>
3826                   <item>
3827                       Otherwise (i.e., the package was completely purged):
3828                       <example compact="compact">
3829 <var>new-preinst</var> install
3830                       </example>
3831                       Error unwind:
3832                       <example compact="compact">
3833 <var>new-postrm</var> abort-install
3834                       </example>
3835                       If the error-unwind fails, the package is in a
3836                       "Half Installed" phase, and requires a
3837                       reinstall. If the error unwind works, the
3838                       package is in a not installed state.
3839                   </item>
3840                 </enumlist>
3841             </item>
3842
3843             <item>
3844               <p>
3845                 The new package's files are unpacked, overwriting any
3846                 that may be on the system already, for example any
3847                 from the old version of the same package or from
3848                 another package.  Backups of the old files are kept
3849                 temporarily, and if anything goes wrong the package
3850                 management system will attempt to put them back as
3851                 part of the error unwind.
3852               </p>
3853
3854               <p>
3855                 It is an error for a package to contain files which
3856                 are on the system in another package, unless
3857                 <tt>Replaces</tt> is used (see <ref id="replaces">).
3858                 <!--
3859                 The following paragraph is not currently the case:
3860                 Currently the <tt>- - force-overwrite</tt> flag is
3861                 enabled, downgrading it to a warning, but this may not
3862                 always be the case.
3863                 -->
3864               </p>
3865
3866               <p>
3867                 It is a more serious error for a package to contain a
3868                 plain file or other kind of non-directory where another
3869                 package has a directory (again, unless
3870                 <tt>Replaces</tt> is used).  This error can be
3871                 overridden if desired using
3872                 <tt>--force-overwrite-dir</tt>, but this is not
3873                 advisable.
3874               </p>
3875
3876               <p>
3877                 Packages which overwrite each other's files produce
3878                 behavior which, though deterministic, is hard for the
3879                 system administrator to understand.  It can easily
3880                 lead to "missing" programs if, for example, a package
3881                 is unpacked which overwrites a file from another
3882                 package, and is then removed again.<footnote>
3883                     Part of the problem is due to what is arguably a
3884                     bug in <prgn>dpkg</prgn>.
3885                 </footnote>
3886               </p>
3887
3888               <p>
3889                 A directory will never be replaced by a symbolic link
3890                 to a directory or vice versa; instead, the existing
3891                 state (symlink or not) will be left alone and
3892                 <prgn>dpkg</prgn> will follow the symlink if there is
3893                 one.
3894               </p>
3895             </item>
3896
3897             <item>
3898               <p>
3899                 <enumlist>
3900                   <item>
3901                       If the package is being upgraded, call
3902                       <example compact="compact">
3903 <var>old-postrm</var> upgrade <var>new-version</var>
3904                       </example>
3905                   </item>
3906                   <item>
3907                       If this fails, <prgn>dpkg</prgn> will attempt:
3908                       <example compact="compact">
3909 <var>new-postrm</var> failed-upgrade <var>old-version</var>
3910                       </example>
3911                       If this works, installation continues. If not, 
3912                       Error unwind:
3913                       <example compact="compact">
3914 <var>old-preinst</var> abort-upgrade <var>new-version</var>
3915                       </example>
3916                       If this fails, the old version is left in an
3917                       "Half Installed" state. If it works, dpkg now
3918                       calls:
3919                       <example compact="compact">
3920 <var>new-postrm</var> abort-upgrade <var>old-version</var>
3921                       </example>
3922                       If this fails, the old version is left in an
3923                       "Half Installed" state. If it works, dpkg now
3924                       calls:
3925                       <example compact="compact">
3926 <var>old-postinst</var> abort-upgrade <var>new-version</var>
3927                       </example>
3928                       If this fails, the old version is in an
3929                       "Unpacked" state.
3930                   </item>
3931                 </enumlist>
3932               </p>
3933
3934               <p>
3935                 This is the point of no return - if
3936                 <prgn>dpkg</prgn> gets this far, it won't back off
3937                 past this point if an error occurs.  This will
3938                 leave the package in a fairly bad state, which
3939                 will require a successful re-installation to clear
3940                 up, but it's when <prgn>dpkg</prgn> starts doing
3941                 things that are irreversible.
3942               </p>
3943             </item>
3944
3945             <item>
3946                 Any files which were in the old version of the package
3947                 but not in the new are removed.
3948             </item>
3949
3950             <item>
3951                 The new file list replaces the old.
3952             </item>
3953
3954             <item>
3955                 The new maintainer scripts replace the old.
3956             </item>
3957
3958             <item>
3959                 Any packages all of whose files have been overwritten
3960                 during the installation, and which aren't required for
3961                 dependencies, are considered to have been removed.
3962                 For each such package
3963                 <enumlist>
3964                   <item>
3965                       <prgn>dpkg</prgn> calls:
3966                       <example compact="compact">
3967 <var>disappearer's-postrm</var> disappear \
3968   <var>overwriter</var> <var>overwriter-version</var>
3969                       </example>
3970                   </item>
3971                   <item>
3972                       The package's maintainer scripts are removed.
3973                   </item>
3974                   <item>
3975                       It is noted in the status database as being in a
3976                       sane state, namely not installed (any conffiles
3977                       it may have are ignored, rather than being
3978                       removed by <prgn>dpkg</prgn>).  Note that
3979                       disappearing packages do not have their prerm
3980                       called, because <prgn>dpkg</prgn> doesn't know
3981                       in advance that the package is going to
3982                       vanish.
3983                   </item>
3984                 </enumlist>
3985             </item>
3986
3987             <item>
3988                 Any files in the package we're unpacking that are also
3989                 listed in the file lists of other packages are removed
3990                 from those lists.  (This will lobotomize the file list
3991                 of the "conflicting" package if there is one.)
3992             </item>
3993
3994             <item>
3995                 The backup files made during installation, above, are
3996                 deleted.
3997             </item>
3998
3999             <item>
4000               <p>
4001                 The new package's status is now sane, and recorded as
4002                 "unpacked".
4003               </p>
4004
4005               <p>
4006                 Here is another point of no return - if the
4007                 conflicting package's removal fails we do not unwind
4008                 the rest of the installation; the conflicting package
4009                 is left in a half-removed limbo.
4010               </p>
4011             </item>
4012
4013             <item>
4014                 If there was a conflicting package we go and do the
4015                 removal actions (described below), starting with the
4016                 removal of the conflicting package's files (any that
4017                 are also in the package being unpacked have already
4018                 been removed from the conflicting package's file list,
4019                 and so do not get removed now).
4020             </item>
4021           </enumlist>
4022         </p>
4023       </sect>
4024
4025       <sect id="configdetails"><heading>Details of configuration</heading>
4026
4027         <p>
4028           When we configure a package (this happens with <tt>dpkg
4029             --install</tt> and <tt>dpkg --configure</tt>), we first
4030           update any <tt>conffile</tt>s and then call:
4031           <example compact="compact">
4032 <var>postinst</var> configure <var>most-recently-configured-version</var>
4033           </example>
4034         </p>
4035
4036         <p>
4037           No attempt is made to unwind after errors during
4038           configuration. If the configuration fails, the package is in
4039           a "Failed Config" state, and an error message is generated.
4040         </p>
4041
4042         <p>
4043           If there is no most recently configured version
4044           <prgn>dpkg</prgn> will pass a null argument.
4045           <footnote>
4046             <p>
4047               Historical note: Truly ancient (pre-1997) versions of
4048               <prgn>dpkg</prgn> passed <tt>&lt;unknown&gt;</tt>
4049               (including the angle brackets) in this case.  Even older
4050               ones did not pass a second argument at all, under any
4051               circumstance.  Note that upgrades using such an old dpkg
4052               version are unlikely to work for other reasons, even if
4053               this old argument behavior is handled by your postinst script.
4054             </p>
4055           </footnote>     
4056         </p>
4057       </sect>
4058
4059       <sect id="removedetails"><heading>Details of removal and/or
4060       configuration purging</heading>
4061
4062         <p>
4063           <enumlist>
4064             <item>
4065               <p>
4066                 <example compact="compact">
4067 <var>prerm</var> remove
4068                 </example>
4069               </p>
4070               <p>
4071                 If prerm fails during replacement due to conflict
4072                 <example>
4073 <var>conflictor's-postinst</var> abort-remove \
4074   in-favour <var>package</var> <var>new-version</var>
4075                 </example>
4076                 Or else we call:
4077                 <example>
4078 <var>postinst</var> abort-remove
4079                 </example>
4080               </p>
4081               <p>
4082                 If this fails, the package is in a "Failed-Config"
4083                 state, or else it remains "Installed".
4084               </p>
4085             </item>
4086             <item>
4087                 The package's files are removed (except <tt>conffile</tt>s).
4088             </item>
4089             <item>
4090                 <example compact="compact">
4091 <var>postrm</var> remove
4092                 </example>
4093
4094               <p>
4095                 If it fails, there's no error unwind, and the package is in
4096                 an "Half-Installed" state.
4097               </p>
4098             </item>
4099             <item>
4100               <p>
4101                 All the maintainer scripts except the <prgn>postrm</prgn>
4102                 are removed.
4103               </p>
4104
4105               <p>
4106                 If we aren't purging the package we stop here.  Note
4107                 that packages which have no <prgn>postrm</prgn> and no
4108                 <tt>conffile</tt>s are automatically purged when
4109                 removed, as there is no difference except for the
4110                 <prgn>dpkg</prgn> status.
4111               </p>
4112             </item>
4113             <item>
4114                 The <tt>conffile</tt>s and any backup files
4115                 (<tt>~</tt>-files, <tt>#*#</tt> files,
4116                 <tt>%</tt>-files, <tt>.dpkg-{old,new,tmp}</tt>, etc.)
4117                 are removed.
4118             </item>
4119             <item>
4120               <p>
4121                 <example compact="compact">
4122 <var>postrm</var> purge
4123                 </example>
4124               </p>
4125               <p>
4126                 If this fails, the package remains in a "Config-Files"
4127                 state.
4128               </p>
4129             </item>
4130             <item>
4131                 The package's file list is removed.
4132             </item>
4133           </enumlist>
4134
4135         </p>
4136       </sect>
4137     </chapt>
4138
4139
4140     <chapt id="relationships">
4141       <heading>Declaring relationships between packages</heading>
4142
4143       <sect id="depsyntax">
4144         <heading>Syntax of relationship fields</heading>
4145
4146         <p>
4147           These fields all have a uniform syntax.  They are a list of
4148           package names separated by commas.
4149         </p>
4150
4151         <p>
4152           In the <tt>Depends</tt>, <tt>Recommends</tt>,
4153           <tt>Suggests</tt>, <tt>Pre-Depends</tt>,
4154           <tt>Build-Depends</tt> and <tt>Build-Depends-Indep</tt>
4155           control file fields of the package, which declare
4156           dependencies on other packages, the package names listed may
4157           also include lists of alternative package names, separated
4158           by vertical bar (pipe) symbols <tt>|</tt>.  In such a case,
4159           if any one of the alternative packages is installed, that
4160           part of the dependency is considered to be satisfied.
4161         </p>
4162
4163         <p>
4164           All of the fields except for <tt>Provides</tt> may restrict
4165           their applicability to particular versions of each named
4166           package.  This is done in parentheses after each individual
4167           package name; the parentheses should contain a relation from
4168           the list below followed by a version number, in the format
4169           described in <ref id="f-Version">.
4170         </p>
4171
4172         <p>
4173           The relations allowed are <tt>&lt;&lt;</tt>, <tt>&lt;=</tt>,
4174           <tt>=</tt>, <tt>&gt;=</tt> and <tt>&gt;&gt;</tt> for
4175           strictly earlier, earlier or equal, exactly equal, later or
4176           equal and strictly later, respectively.  The deprecated
4177           forms <tt>&lt;</tt> and <tt>&gt;</tt> were used to mean
4178           earlier/later or equal, rather than strictly earlier/later,
4179           so they should not appear in new packages (though
4180           <prgn>dpkg</prgn> still supports them).
4181         </p>
4182
4183         <p>
4184           Whitespace may appear at any point in the version
4185           specification subject to the rules in <ref
4186           id="controlsyntax">, and must appear where it's necessary to
4187           disambiguate; it is not otherwise significant.  All of the
4188           relationship fields may span multiple lines.  For
4189           consistency and in case of future changes to
4190           <prgn>dpkg</prgn> it is recommended that a single space be
4191           used after a version relationship and before a version
4192           number; it is also conventional to put a single space after
4193           each comma, on either side of each vertical bar, and before
4194           each open parenthesis.  When wrapping a relationship field, it
4195           is conventional to do so after a comma and before the space
4196           following that comma.
4197         </p>
4198
4199         <p>
4200           For example, a list of dependencies might appear as:
4201           <example compact="compact">
4202 Package: mutt
4203 Version: 1.3.17-1
4204 Depends: libc6 (>= 2.2.1), exim | mail-transport-agent
4205           </example>
4206         </p>
4207
4208         <p>
4209           All fields that specify build-time relationships
4210           (<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
4211           <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>)
4212           may be restricted to a certain set of architectures.  This
4213           is indicated in brackets after each individual package name and
4214           the optional version specification.  The brackets enclose a
4215           list of Debian architecture names separated by whitespace.
4216           Exclamation marks may be prepended to each of the names.
4217           (It is not permitted for some names to be prepended with
4218           exclamation marks while others aren't.) If the current Debian
4219           host architecture is not in this list and there are no
4220           exclamation marks in the list, or it is in the list with a
4221           prepended exclamation mark, the package name and the
4222           associated version specification are ignored completely for
4223           the purposes of defining the relationships.
4224         </p>
4225
4226         <p>
4227           For example:
4228           <example compact="compact">
4229 Source: glibc
4230 Build-Depends-Indep: texinfo
4231 Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
4232   hurd-dev [hurd-i386], gnumach-dev [hurd-i386]
4233           </example>
4234           requires <tt>kernel-headers-2.2.10</tt> on all architectures
4235           other than hurd-i386 and requires <tt>hurd-dev</tt> and
4236           <tt>gnumach-dev</tt> only on hurd-i386.
4237         </p>
4238
4239         <p>
4240           If the architecture-restricted dependency is part of a set of
4241           alternatives using <tt>|</tt>, that alternative is ignored
4242           completely on architectures that do not match the restriction.
4243           For example:
4244           <example compact="compact">
4245 Build-Depends: foo [!i386] | bar [!amd64]
4246           </example>
4247           is equivalent to <tt>bar</tt> on the i386 architecture, to
4248           <tt>foo</tt> on the amd64 architecture, and to <tt>foo |
4249           bar</tt> on all other architectures.
4250         </p>
4251
4252         <p>
4253           Note that the binary package relationship fields such as
4254           <tt>Depends</tt> appear in one of the binary package
4255           sections of the control file, whereas the build-time
4256           relationships such as <tt>Build-Depends</tt> appear in the
4257           source package section of the control file (which is the
4258           first section).
4259         </p>
4260       </sect>
4261
4262       <sect id="binarydeps">
4263         <heading>Binary Dependencies - <tt>Depends</tt>,
4264           <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
4265           <tt>Pre-Depends</tt>
4266         </heading>
4267
4268         <p>
4269           Packages can declare in their control file that they have
4270           certain relationships to other packages - for example, that
4271           they may not be installed at the same time as certain other
4272           packages, and/or that they depend on the presence of others.
4273         </p>
4274
4275         <p>
4276           This is done using the <tt>Depends</tt>, <tt>Pre-Depends</tt>,
4277           <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
4278           <tt>Breaks</tt> and <tt>Conflicts</tt> control file fields.
4279           <tt>Breaks</tt> is described in <ref id="breaks">, and
4280           <tt>Conflicts</tt> is described in <ref id="conflicts">.  The
4281           rest are described below.
4282         </p>
4283
4284         <p>
4285           These seven fields are used to declare a dependency
4286           relationship by one package on another.  Except for
4287           <tt>Enhances</tt> and <tt>Breaks</tt>, they appear in the
4288           depending (binary) package's control file.
4289           (<tt>Enhances</tt> appears in the recommending package's
4290           control file, and <tt>Breaks</tt> appears in the version of
4291           depended-on package which causes the named package to
4292           break).
4293         </p>
4294
4295         <p>
4296           A <tt>Depends</tt> field takes effect <em>only</em> when a
4297           package is to be configured.  It does not prevent a package
4298           being on the system in an unconfigured state while its
4299           dependencies are unsatisfied, and it is possible to replace
4300           a package whose dependencies are satisfied and which is
4301           properly installed with a different version whose
4302           dependencies are not and cannot be satisfied; when this is
4303           done the depending package will be left unconfigured (since
4304           attempts to configure it will give errors) and will not
4305           function properly.  If it is necessary, a
4306           <tt>Pre-Depends</tt> field can be used, which has a partial
4307           effect even when a package is being unpacked, as explained
4308           in detail below.  (The other three dependency fields,
4309           <tt>Recommends</tt>, <tt>Suggests</tt> and
4310           <tt>Enhances</tt>, are only used by the various front-ends
4311           to <prgn>dpkg</prgn> such as <prgn>apt-get</prgn>,
4312           <prgn>aptitude</prgn>, and <prgn>dselect</prgn>.)
4313         </p>
4314
4315         <p>
4316           Since <tt>Depends</tt> only places requirements on the
4317           configuration step, packages in an installation run are usually
4318           all unpacked first and all configured later.  This makes it
4319           easier to satisfy all dependencies when multiple packages are
4320           being upgraded.
4321         </p>
4322
4323         <p>
4324           If there is a circular dependency among packages being installed
4325           or removed, installation or removal order honoring the
4326           dependency order is impossible, requiring the dependency loop be
4327           broken at some point and the dependency requirements violated
4328           for at least one package.  Packages involved in circular
4329           dependencies may not be able to rely on their dependencies being
4330           configured when being configured or removed depending on which
4331           side of the break of the circular dependency loop they happen to
4332           be on.  If one of the packages in the loop has no
4333           <prgn>postinst</prgn> script, then the cycle will be broken at
4334           that package; this ensures that all <prgn>postinst</prgn>
4335           scripts are run with their dependencies properly configured if
4336           this is possible.  Otherwise the breaking point is arbitrary.
4337           Packages should therefore avoid circular dependencies where
4338           possible, particularly if they have <prgn>postinst</prgn>
4339           scripts.
4340         </p>
4341
4342         <p>
4343           The meaning of the five dependency fields is as follows:
4344           <taglist>
4345             <tag><tt>Depends</tt></tag>
4346             <item>
4347               <p>
4348                 This declares an absolute dependency.  A package will
4349                 not be configured unless all of the packages listed in
4350                 its <tt>Depends</tt> field have been correctly
4351                 configured (unless there is a circular dependency as
4352                 described above).
4353               </p>
4354
4355               <p>
4356                 The <tt>Depends</tt> field should be used if the
4357                 depended-on package is required for the depending
4358                 package to provide a significant amount of
4359                 functionality.
4360               </p>
4361
4362               <p>
4363                 The <tt>Depends</tt> field should also be used if the
4364                 <prgn>postinst</prgn>, <prgn>prerm</prgn> or
4365                 <prgn>postrm</prgn> scripts require the package to be
4366                 present in order to run.  (If both packages are involved
4367                 in a dependency loop, this might not work as expected; see
4368                 the explanation a few paragraphs back.)  In the case of
4369                 <prgn>postinst</prgn> and <prgn>postrm</prgn>, the
4370                 depended-on packages will be unpacked and configured
4371                 first.  (Note, however, that the <prgn>postrm</prgn>
4372                 cannot rely on any non-essential packages to be present
4373                 during the <tt>purge</tt> phase.)  In the case of
4374                 <prgn>prerm</prgn>, the depended-on package will at least
4375                 be unpacked (it might be configured too, but you can't
4376                 rely on this unless you use <tt>Pre-Depends</tt>).
4377             </item>
4378
4379             <tag><tt>Recommends</tt></tag>
4380             <item>
4381               <p>
4382                 This declares a strong, but not absolute, dependency.
4383               </p>
4384
4385               <p>
4386                 The <tt>Recommends</tt> field should list packages
4387                 that would be found together with this one in all but
4388                 unusual installations.
4389               </p>
4390             </item>
4391
4392             <tag><tt>Suggests</tt></tag>
4393             <item>
4394                 This is used to declare that one package may be more
4395                 useful with one or more others.  Using this field
4396                 tells the packaging system and the user that the
4397                 listed packages are related to this one and can
4398                 perhaps enhance its usefulness, but that installing
4399                 this one without them is perfectly reasonable.
4400             </item>
4401
4402             <tag><tt>Enhances</tt></tag>
4403             <item>
4404                 This field is similar to Suggests but works in the
4405                 opposite direction. It is used to declare that a
4406                 package can enhance the functionality of another
4407                 package.
4408             </item>
4409
4410             <tag><tt>Pre-Depends</tt></tag>
4411             <item>
4412               <p>
4413                 This field is like <tt>Depends</tt>, except that it
4414                 also forces <prgn>dpkg</prgn> to complete installation
4415                 of the packages named before even starting the
4416                 installation of the package which declares the
4417                 pre-dependency, as follows:
4418               </p>
4419
4420               <p>
4421                 When a package declaring a pre-dependency is about to
4422                 be <em>unpacked</em> the pre-dependency can be
4423                 satisfied if the depended-on package is either fully
4424                 configured, <em>or even if</em> the depended-on
4425                 package(s) are only unpacked or half-configured,
4426                 provided that they have been configured correctly at
4427                 some point in the past (and not removed or partially
4428                 removed since).  In this case, both the
4429                 previously-configured and currently unpacked or
4430                 half-configured versions must satisfy any version
4431                 clause in the <tt>Pre-Depends</tt> field.
4432               </p>
4433
4434               <p>
4435                 When the package declaring a pre-dependency is about
4436                 to be <em>configured</em>, the pre-dependency will be
4437                 treated as a normal <tt>Depends</tt>, that is, it will
4438                 be considered satisfied only if the depended-on
4439                 package has been correctly configured.  However, unlike
4440                 with <tt>Depends</tt>, <tt>Pre-Depends</tt> does not
4441                 permit circular dependencies to be broken.  If a circular
4442                 dependency is encountered while attempting to honor
4443                 <tt>Pre-Depends</tt>, the installation will be aborted.
4444               </p>
4445
4446               <p>
4447                 <tt>Pre-Depends</tt> are also required if the
4448                 <prgn>preinst</prgn> script depends on the named package.
4449                 It is best to avoid this situation if possible.
4450               </p>
4451
4452               <p>
4453                 <tt>Pre-Depends</tt> should be used sparingly,
4454                 preferably only by packages whose premature upgrade or
4455                 installation would hamper the ability of the system to
4456                 continue with any upgrade that might be in progress.
4457               </p>
4458             </item>
4459           </taglist>
4460         </p>
4461
4462         <p>
4463           When selecting which level of dependency to use you should
4464           consider how important the depended-on package is to the
4465           functionality of the one declaring the dependency.  Some
4466           packages are composed of components of varying degrees of
4467           importance.  Such a package should list using
4468           <tt>Depends</tt> the package(s) which are required by the
4469           more important components.  The other components'
4470           requirements may be mentioned as Suggestions or
4471           Recommendations, as appropriate to the components' relative
4472           importance.
4473         </p>
4474       </sect>
4475
4476       <sect id="breaks">
4477         <heading>Packages which break other packages - <tt>Breaks</tt></heading>
4478
4479         <p>
4480           When one binary package declares that it breaks another,
4481           <prgn>dpkg</prgn> will refuse to allow the package which
4482           declares <tt>Breaks</tt> be unpacked unless the broken
4483           package is deconfigured first, and it will refuse to
4484           allow the broken package to be reconfigured.
4485         </p>
4486
4487         <p>
4488           A package will not be regarded as causing breakage merely
4489           because its configuration files are still installed; it must
4490           be at least half-installed.
4491         </p>
4492
4493         <p>
4494           A special exception is made for packages which declare that
4495           they break their own package name or a virtual package which
4496           they provide (see below): this does not count as a real
4497           breakage.
4498         </p>
4499
4500         <p>
4501           Normally a <tt>Breaks</tt> entry will have an "earlier than"
4502           version clause; such a <tt>Breaks</tt> is introduced in the
4503           version of an (implicit or explicit) dependency which
4504           violates an assumption or reveals a bug in earlier versions
4505           of the broken package.  This use of <tt>Breaks</tt> will
4506           inform higher-level package management tools that broken
4507           package must be upgraded before the new one.
4508         </p>
4509
4510         <p>
4511           If the breaking package also overwrites some files from the
4512           older package, it should use <tt>Replaces</tt> (not
4513           <tt>Conflicts</tt>) to ensure this goes smoothly.
4514         </p>
4515       </sect>
4516
4517       <sect id="conflicts">
4518         <heading>Conflicting binary packages - <tt>Conflicts</tt></heading>
4519
4520         <p>
4521           When one binary package declares a conflict with another
4522           using a <tt>Conflicts</tt> field, <prgn>dpkg</prgn> will
4523           refuse to allow them to be unpacked on the system at the
4524           same time.
4525         </p>
4526
4527         <p>
4528           If one package is to be unpacked, the other must be removed
4529           first - if the package being unpacked is marked as
4530           replacing (see <ref id="replaces">) the one on the system,
4531           or the one on the system is marked as deselected, or both
4532           packages are marked <tt>Essential</tt>, then
4533           <prgn>dpkg</prgn> will automatically remove the package
4534           which is causing the conflict, otherwise it will halt the
4535           installation of the new package with an error.  This
4536           mechanism is specifically designed to produce an error when
4537           the installed package is <tt>Essential</tt>, but the new
4538           package is not.
4539         </p>
4540
4541         <p>
4542           A package will not cause a conflict merely because its
4543           configuration files are still installed; it must be at least
4544           half-installed.
4545         </p>
4546
4547         <p>
4548           A special exception is made for packages which declare a
4549           conflict with their own package name, or with a virtual
4550           package which they provide (see below): this does not
4551           prevent their installation, and allows a package to conflict
4552           with others providing a replacement for it.  You use this
4553           feature when you want the package in question to be the only
4554           package providing some feature.
4555         </p>
4556
4557         <p>
4558           A <tt>Conflicts</tt> entry should almost never have an
4559           "earlier than" version clause.  This would prevent
4560           <prgn>dpkg</prgn> from upgrading or installing the package
4561           which declared such a conflict until the upgrade or removal
4562           of the conflicted-with package had been completed.  Instead,
4563           <tt>Breaks</tt> may be used.
4564         </p>
4565       </sect>
4566
4567       <sect id="virtual"><heading>Virtual packages - <tt>Provides</tt>
4568         </heading>
4569
4570         <p>
4571           As well as the names of actual ("concrete") packages, the
4572           package relationship fields <tt>Depends</tt>,
4573           <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
4574           <tt>Pre-Depends</tt>, <tt>Breaks</tt>, <tt>Conflicts</tt>,
4575           <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
4576           <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>
4577           may mention "virtual packages".
4578         </p>
4579
4580         <p>
4581           A <em>virtual package</em> is one which appears in the
4582           <tt>Provides</tt> control file field of another package.
4583           The effect is as if the package(s) which provide a
4584           particular virtual package name had been listed by name
4585           everywhere the virtual package name appears. (See also <ref
4586             id="virtual_pkg">)
4587         </p>
4588
4589         <p>
4590           If there are both concrete and virtual packages of the same
4591           name, then the dependency may be satisfied (or the conflict
4592           caused) by either the concrete package with the name in
4593           question or any other concrete package which provides the
4594           virtual package with the name in question.  This is so that,
4595           for example, supposing we have
4596           <example compact="compact">
4597 Package: foo
4598 Depends: bar
4599           </example> and someone else releases an enhanced version of
4600           the <tt>bar</tt> package they can say:
4601           <example compact="compact">
4602 Package: bar-plus
4603 Provides: bar
4604           </example>
4605           and the <tt>bar-plus</tt> package will now also satisfy the
4606           dependency for the <tt>foo</tt> package.
4607         </p>
4608
4609         <p>
4610           If a relationship field has a version number attached
4611           then only real packages will be considered to see whether
4612           the relationship is satisfied (or the prohibition violated,
4613           for a conflict or breakage) - it is assumed that a real
4614           package which provides the virtual package is not of the
4615           "right" version.  So, a <tt>Provides</tt> field may not
4616           contain version numbers, and the version number of the
4617           concrete package which provides a particular virtual package
4618           will not be looked at when considering a dependency on or
4619           conflict with the virtual package name.
4620         </p>
4621
4622         <p>
4623           It is likely that the ability will be added in a future
4624           release of <prgn>dpkg</prgn> to specify a version number for
4625           each virtual package it provides.  This feature is not yet
4626           present, however, and is expected to be used only
4627           infrequently.
4628         </p>
4629
4630         <p>
4631           If you want to specify which of a set of real packages
4632           should be the default to satisfy a particular dependency on
4633           a virtual package, you should list the real package as an
4634           alternative before the virtual one.
4635         </p>
4636       </sect>
4637
4638
4639       <sect id="replaces"><heading>Overwriting files and replacing
4640           packages - <tt>Replaces</tt></heading>
4641
4642         <p>
4643           Packages can declare in their control file that they should
4644           overwrite files in certain other packages, or completely
4645           replace other packages. The <tt>Replaces</tt> control file
4646           field has these two distinct purposes.
4647         </p>
4648
4649         <sect1><heading>Overwriting files in other packages</heading>
4650
4651           <p>
4652             Firstly, as mentioned before, it is usually an error for a
4653             package to contain files which are on the system in
4654             another package.
4655           </p>
4656
4657           <p>
4658             However, if the overwriting package declares that it
4659             <tt>Replaces</tt> the one containing the file being
4660             overwritten, then <prgn>dpkg</prgn> will replace the file
4661             from the old package with that from the new.  The file
4662             will no longer be listed as "owned" by the old package.
4663           </p>
4664
4665           <p>
4666             If a package is completely replaced in this way, so that
4667             <prgn>dpkg</prgn> does not know of any files it still
4668             contains, it is considered to have "disappeared".  It will
4669             be marked as not wanted on the system (selected for
4670             removal) and not installed.  Any <tt>conffile</tt>s
4671             details noted for the package will be ignored, as they
4672             will have been taken over by the overwriting package.  The
4673             package's <prgn>postrm</prgn> script will be run with a
4674             special argument to allow the package to do any final
4675             cleanup required.  See <ref id="mscriptsinstact">.
4676             <footnote>
4677               <p>
4678                 Replaces is a one way relationship -- you have to              
4679                 install the replacing package after the replaced
4680                 package.
4681               </p>
4682             </footnote>
4683           </p>
4684
4685           <p>
4686             For this usage of <tt>Replaces</tt>, virtual packages (see
4687             <ref id="virtual">) are not considered when looking at a
4688             <tt>Replaces</tt> field - the packages declared as being
4689             replaced must be mentioned by their real names.
4690           </p>
4691
4692           <p>
4693             Furthermore, this usage of <tt>Replaces</tt> only takes
4694             effect when both packages are at least partially on the
4695             system at once, so that it can only happen if they do not
4696             conflict or if the conflict has been overridden.
4697           </p>
4698
4699         </sect1>
4700
4701         <sect1><heading>Replacing whole packages, forcing their
4702             removal</heading>
4703
4704           <p>
4705             Secondly, <tt>Replaces</tt> allows the packaging system to
4706             resolve which package should be removed when there is a
4707             conflict - see <ref id="conflicts">.  This usage only
4708             takes effect when the two packages <em>do</em> conflict,
4709             so that the two usages of this field do not interfere with
4710             each other.
4711           </p>
4712
4713           <p>
4714             In this situation, the package declared as being replaced
4715             can be a virtual package, so for example, all mail
4716             transport agents (MTAs) would have the following fields in
4717             their control files:
4718             <example compact="compact">
4719 Provides: mail-transport-agent
4720 Conflicts: mail-transport-agent
4721 Replaces: mail-transport-agent
4722             </example>
4723             ensuring that only one MTA can be unpacked at any one
4724             time.
4725         </sect1>
4726       </sect>
4727
4728       <sect id="sourcebinarydeps">
4729         <heading>Relationships between source and binary packages -
4730           <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
4731           <tt>Build-Conflicts</tt>, <tt>Build-Conflicts-Indep</tt>
4732         </heading>
4733
4734         <p>
4735           Source packages that require certain binary packages to be
4736           installed or absent at the time of building the package
4737           can declare relationships to those binary packages.
4738         </p>
4739
4740         <p>
4741           This is done using the <tt>Build-Depends</tt>,
4742           <tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt> and
4743           <tt>Build-Conflicts-Indep</tt> control file fields.
4744         </p>
4745
4746         <p>
4747           Build-dependencies on "build-essential" binary packages can be
4748           omitted. Please see <ref id="pkg-relations"> for more information.
4749         </p>
4750
4751         <p>
4752           The dependencies and conflicts they define must be satisfied
4753           (as defined earlier for binary packages) in order to invoke
4754           the targets in <tt>debian/rules</tt>, as follows:<footnote>
4755             <p>
4756               If you make "build-arch" or "binary-arch", you need
4757               Build-Depends.  If you make "build-indep" or
4758               "binary-indep", you need Build-Depends and
4759               Build-Depends-Indep.  If you make "build" or "binary",
4760               you need both.
4761             </p>
4762             <p>
4763               There is no Build-Depends-Arch; this role is essentially
4764               met with Build-Depends.  Anyone building the
4765               <tt>build-indep</tt> and binary-indep<tt></tt> targets
4766               is basically assumed to be building the whole package
4767               anyway and so installs all build dependencies.  The
4768               autobuilders use <tt>dpkg-buildpackage -B</tt>, which
4769               calls <tt>build</tt> (not <tt>build-arch</tt>, since it
4770               does not yet know how to check for its existence) and
4771               <tt>binary-arch</tt>.
4772             </p>
4773             <p>
4774               The purpose of the original split, I recall, was so that
4775               the autobuilders wouldn't need to install extra packages
4776               needed only for the binary-indep targets.  But without a
4777               build-arch/build-indep split, this didn't work, since
4778               most of the work is done in the build target, not in the
4779               binary target.
4780             </p>
4781           </footnote>
4782
4783           <taglist>
4784             <tag><tt>Build-Depends</tt>, <tt>Build-Conflicts</tt></tag>
4785             <item>
4786                 The <tt>Build-Depends</tt> and
4787                 <tt>Build-Conflicts</tt> fields must be satisfied when
4788                 any of the following targets is invoked:
4789                 <tt>build</tt>, <tt>clean</tt>, <tt>binary</tt>,
4790                 <tt>binary-arch</tt>, <tt>build-arch</tt>,
4791                 <tt>build-indep</tt> and <tt>binary-indep</tt>.
4792             </item>
4793             <tag><tt>Build-Depends-Indep</tt>,
4794               <tt>Build-Conflicts-Indep</tt></tag>
4795             <item>
4796                 The <tt>Build-Depends-Indep</tt> and
4797                 <tt>Build-Conflicts-Indep</tt> fields must be
4798                 satisfied when any of the following targets is
4799                 invoked: <tt>build</tt>, <tt>build-indep</tt>,
4800                 <tt>binary</tt> and <tt>binary-indep</tt>.
4801             </item>
4802           </taglist>
4803         </p>
4804
4805       </sect>
4806
4807     </chapt>
4808
4809
4810     <chapt id="sharedlibs"><heading>Shared libraries</heading>
4811
4812       <p>
4813         Packages containing shared libraries must be constructed with
4814         a little care to make sure that the shared library is always
4815         available.  This is especially important for packages whose
4816         shared libraries are vitally important, such as the C library
4817         (currently <tt>libc6</tt>).
4818       </p>
4819
4820       <p>
4821         Packages involving shared libraries should be split up into
4822         several binary packages. This section mostly deals with how
4823         this separation is to be accomplished; rules for files within
4824         the shared library packages are in <ref id="libraries"> instead.
4825       </p>
4826
4827       <sect id="sharedlibs-runtime">
4828         <heading>Run-time shared libraries</heading>
4829
4830       <p>
4831         The run-time shared library needs to be placed in a package
4832         whose name changes whenever the shared object version
4833         changes.<footnote>
4834             <p>
4835               Since it is common place to install several versions of a
4836               package that just provides shared libraries, it is a
4837               good idea that the library package should not
4838               contain any extraneous non-versioned files, unless they
4839               happen to be in versioned directories.</p>
4840           </footnote>
4841           The most common mechanism is to place it in a package
4842         called
4843         <package><var>libraryname</var><var>soversion</var></package>,
4844         where <file><var>soversion</var></file> is the version number
4845         in the soname of the shared library<footnote>
4846               The soname is the shared object name: it's the thing
4847               that has to match exactly between building an executable
4848               and running it for the dynamic linker to be able run the
4849               program.  For example, if the soname of the library is
4850               <file>libfoo.so.6</file>, the library package would be
4851               called <file>libfoo6</file>.
4852           </footnote>.
4853         Alternatively, if it would be confusing to directly append
4854         <var>soversion</var> to <var>libraryname</var> (e.g. because
4855         <var>libraryname</var> itself ends in a number), you may use
4856         <package><var>libraryname</var>-<var>soversion</var></package> and
4857         <package><var>libraryname</var>-<var>soversion</var>-dev</package>
4858         instead.
4859       </p>
4860
4861       <p>
4862         If you have several shared libraries built from the same
4863         source tree you may lump them all together into a single
4864         shared library package, provided that you change all of
4865         their sonames at once (so that you don't get filename
4866         clashes if you try to install different versions of the
4867         combined shared libraries package).
4868       </p>
4869
4870       <p>
4871         The package should install the shared libraries under
4872         their normal names.  For example, the <package>libgdbm3</package>
4873         package should install <file>libgdbm.so.3.0.0</file> as
4874         <file>/usr/lib/libgdbm.so.3.0.0</file>.  The files should not be
4875         renamed or re-linked by any <prgn>prerm</prgn> or
4876         <prgn>postrm</prgn> scripts; <prgn>dpkg</prgn> will take care
4877         of renaming things safely without affecting running programs,
4878         and attempts to interfere with this are likely to lead to
4879         problems.
4880       </p>
4881
4882       <p>
4883         Shared libraries should not be installed executable, since
4884         the dynamic linker does not require this and trying to
4885         execute a shared library usually results in a core dump.
4886       </p>
4887
4888       <p>
4889         The run-time library package should include the symbolic link that
4890         <prgn>ldconfig</prgn> would create for the shared libraries.
4891         For example, the <package>libgdbm3</package> package should include
4892         a symbolic link from <file>/usr/lib/libgdbm.so.3</file> to
4893         <file>libgdbm.so.3.0.0</file>.  This is needed so that the dynamic
4894         linker (for example <prgn>ld.so</prgn> or
4895         <prgn>ld-linux.so.*</prgn>) can find the library between the
4896         time that <prgn>dpkg</prgn> installs it and the time that
4897         <prgn>ldconfig</prgn> is run in the <prgn>postinst</prgn>
4898         script.<footnote>
4899             The package management system requires the library to be
4900             placed before the symbolic link pointing to it in the
4901             <file>.deb</file> file.  This is so that when
4902             <prgn>dpkg</prgn> comes to install the symlink
4903             (overwriting the previous symlink pointing at an older
4904             version of the library), the new shared library is already
4905             in place.  In the past, this was achieved by creating the
4906             library in the temporary packaging directory before
4907             creating the symlink.  Unfortunately, this was not always
4908             effective, since the building of the tar file in the
4909             <file>.deb</file> depended on the behavior of the underlying
4910             file system.  Some file systems (such as reiserfs) reorder
4911             the files so that the order of creation is forgotten.
4912             Since version 1.7.0, <prgn>dpkg</prgn>
4913             reorders the files itself as necessary when building a
4914             package.  Thus it is no longer important to concern
4915             oneself with the order of file creation.
4916         </footnote>
4917       </p>
4918
4919         <sect1 id="ldconfig">
4920           <heading><tt>ldconfig</tt></heading>
4921
4922         <p>
4923           Any package installing shared libraries in one of the default
4924           library directories of the dynamic linker (which are currently
4925           <file>/usr/lib</file> and <file>/lib</file>) or a directory that is
4926           listed in <file>/etc/ld.so.conf</file><footnote>
4927             These are currently
4928             <list compact="compact">
4929               <item>/usr/local/lib</item>
4930               <item>/usr/lib/libc5-compat</item>
4931               <item>/lib/libc5-compat</item>
4932             </list>
4933           </footnote>
4934           must use <prgn>ldconfig</prgn> to update the shared library
4935           system.
4936         </p>
4937
4938         <p>
4939             The package maintainer scripts must only call
4940             <prgn>ldconfig</prgn> under these circumstances:
4941             <list compact="compact">
4942               <item>When the <prgn>postinst</prgn> script is run with a
4943                   first argument of <tt>configure</tt>, the script must call
4944                   <prgn>ldconfig</prgn>, and may optionally invoke
4945                   <prgn>ldconfig</prgn> at other times.
4946               </item>
4947               <item>When the <prgn>postrm</prgn> script is run with a
4948                   first argument of <tt>remove</tt>, the script should call
4949                   <prgn>ldconfig</prgn>.
4950               </item>
4951             </list>
4952          <footnote>
4953             <p>
4954               During install or upgrade, the preinst is called before
4955               the new files are unpacked, so calling "ldconfig" is
4956               pointless.  The preinst of an existing package can also be
4957               called if an upgrade fails.  However, this happens during
4958               the critical time when a shared libs may exist on-disk
4959               under a temporary name.  Thus, it is dangerous and
4960               forbidden by current policy to call "ldconfig" at this
4961               time.
4962             </p>
4963
4964             <p>
4965               When a package is installed or upgraded, "postinst
4966               configure" runs after the new files are safely on-disk.
4967               Since it is perfectly safe to invoke ldconfig
4968               unconditionally in a postinst, it is OK for a package to
4969               simply put ldconfig in its postinst without checking the
4970               argument.  The postinst can also be called to recover from
4971               a failed upgrade.  This happens before any new files are
4972               unpacked, so there is no reason to call "ldconfig" at this
4973               point.
4974             </p>
4975
4976             <p>
4977               For a package that is being removed, prerm is
4978               called with all the files intact, so calling ldconfig is
4979               useless.  The other calls to "prerm" happen in the case of
4980               upgrade at a time when all the files of the old package
4981               are on-disk, so again calling "ldconfig" is pointless.
4982             </p>
4983
4984             <p>
4985               postrm, on the other hand, is called with the "remove"
4986               argument just after the files are removed, so this is
4987               the proper time to call "ldconfig" to notify the system
4988               of the fact that the shared libraries from the package
4989               are removed.  The postrm can be called at several other
4990               times.  At the time of "postrm purge", "postrm
4991               abort-install", or "postrm abort-upgrade", calling
4992               "ldconfig" is useless because the shared lib files are
4993               not on-disk.  However, when "postrm" is invoked with
4994               arguments "upgrade", "failed-upgrade", or "disappear", a
4995               shared lib may exist on-disk under a temporary filename.
4996             </p>
4997           </footnote>
4998         </p>
4999         </sect1>
5000
5001       </sect>
5002
5003       <sect id="sharedlibs-support-files">
5004         <heading>Shared library support files</heading>
5005
5006         <p>
5007           If your package contains files whose names do not change with
5008           each change in the library shared object version, you must not
5009           put them in the shared library package.  Otherwise, several
5010           versions of the shared library cannot be installed at the same
5011           time without filename clashes, making upgrades and transitions
5012           unnecessarily difficult.
5013         </p>
5014
5015         <p>
5016           It is recommended that supporting files and run-time support
5017           programs that do not need to be invoked manually by users, but
5018           are nevertheless required for the package to function, be placed
5019           (if they are binary) in a subdirectory of <file>/usr/lib</file>,
5020           preferably under <file>/usr/lib/</file><var>package-name</var>.
5021           If the program or file is architecture independent, the
5022           recommendation is for it to be placed in a subdirectory of
5023           <file>/usr/share</file> instead, preferably under
5024           <file>/usr/share/</file><var>package-name</var>.  Following the
5025           <var>package-name</var> naming convention ensures that the file
5026           names change when the shared object version changes.
5027         </p>
5028
5029         <p>
5030           Run-time support programs that use the shared library but are
5031           not required for the library to function or files used by the
5032           shared library that can be used by any version of the shared
5033           library package should instead be put in a separate package.
5034           This package might typically be named
5035           <package><var>libraryname</var>-tools</package>; note the
5036           absence of the <var>soversion</var> in the package name.
5037         </p>
5038
5039         <p>
5040           Files and support programs only useful when compiling software
5041           against the library should be included in the development
5042           package for the library.<footnote>
5043             For example, a <file><var>package-name</var>-config</file>
5044             script or <package>pkg-config</package> configuration files.
5045           </footnote>
5046         </p>
5047       </sect>
5048
5049       <sect id="sharedlibs-static">
5050         <heading>Static libraries</heading>
5051
5052       <p>
5053         The static library (<file><var>libraryname.a</var></file>)
5054         is usually provided in addition to the shared version.
5055         It is placed into the development package (see below).
5056       </p>
5057
5058       <p>
5059         In some cases, it is acceptable for a library to be
5060         available in static form only; these cases include:
5061         <list>
5062           <item>libraries for languages whose shared library support
5063                 is immature or unstable</item>
5064           <item>libraries whose interfaces are in flux or under
5065                 development (commonly the case when the library's
5066                 major version number is zero, or where the ABI breaks
5067                 across patchlevels)</item>
5068           <item>libraries which are explicitly intended to be
5069                 available only in static form by their upstream
5070                 author(s)</item>
5071         </list>
5072       </p>
5073
5074       <sect id="sharedlibs-dev">
5075         <heading>Development files</heading>
5076
5077       <p>
5078         The development files associated to a shared library need to be
5079         placed in a package called
5080         <package><var>libraryname</var><var>soversion</var>-dev</package>,
5081         or if you prefer only to support one development version at a
5082         time, <package><var>libraryname</var>-dev</package>.
5083       </p>
5084
5085       <p>
5086         In case several development versions of a library exist, you may
5087         need to use <prgn>dpkg</prgn>'s Conflicts mechanism (see
5088         <ref id="conflicts">) to ensure that the user only installs one
5089         development version at a time (as different development versions are
5090         likely to have the same header files in them, which would cause a
5091         filename clash if both were unpacked).
5092       </p>
5093
5094       <p>
5095         The development package should contain a symlink for the associated
5096         shared library without a version number. For example, the
5097         <package>libgdbm-dev</package> package should include a symlink
5098         from <file>/usr/lib/libgdbm.so</file> to
5099         <file>libgdbm.so.3.0.0</file>.  This symlink is needed by the linker
5100         (<prgn>ld</prgn>) when compiling packages, as it will only look for
5101         <file>libgdbm.so</file> when compiling dynamically.
5102       </p>
5103       </sect>
5104
5105       <sect id="sharedlibs-intradeps">
5106         <heading>Dependencies between the packages of the same library</heading>
5107
5108         <p>
5109           Typically the development version should have an exact
5110           version dependency on the runtime library, to make sure that
5111           compilation and linking happens correctly.  The
5112           <tt>${binary:Version}</tt> substitution variable can be
5113           useful for this purpose.
5114           <footnote>
5115             Previously, <tt>${Source-Version}</tt> was used, but its name
5116             was confusing and it has been deprecated since dpkg 1.13.19.
5117           </footnote>
5118         </p>
5119       </sect>
5120
5121       <sect id="sharedlibs-shlibdeps">
5122         <heading>Dependencies between the library and other packages -
5123         the <tt>shlibs</tt> system</heading>
5124
5125         <p>
5126           If a package contains a binary or library which links to a
5127           shared library, we must ensure that when the package is
5128           installed on the system, all of the libraries needed are
5129           also installed.  This requirement led to the creation of the
5130           <tt>shlibs</tt> system, which is very simple in its design:
5131           any package which <em>provides</em> a shared library also
5132           provides information on the package dependencies required to
5133           ensure the presence of this library, and any package which
5134           <em>uses</em> a shared library uses this information to
5135           determine the dependencies it requires.  The files which
5136           contain the mapping from shared libraries to the necessary
5137           dependency information are called <file>shlibs</file> files.
5138         </p>
5139
5140         <p>
5141           Thus, when a package is built which contains any shared
5142           libraries, it must provide a <file>shlibs</file> file for other
5143           packages to use, and when a package is built which contains
5144           any shared libraries or compiled binaries, it must run
5145           <qref id="pkg-dpkg-shlibdeps"><prgn>dpkg-shlibdeps</prgn></qref>
5146           on these to determine the libraries used and hence the
5147           dependencies needed by this package.<footnote>
5148             <p>
5149               In the past, the shared libraries linked to were
5150               determined by calling <prgn>ldd</prgn>, but now
5151               <prgn>objdump</prgn> is used to do this.  The only
5152               change this makes to package building is that
5153               <prgn>dpkg-shlibdeps</prgn> must also be run on shared
5154               libraries, whereas in the past this was unnecessary.
5155               The rest of this footnote explains the advantage that
5156               this method gives.
5157             </p>
5158
5159             <p>
5160               We say that a binary <tt>foo</tt> <em>directly</em> uses
5161               a library <tt>libbar</tt> if it is explicitly linked
5162               with that library (that is, it uses the flag
5163               <tt>-lbar</tt> during the linking stage).  Other
5164               libraries that are needed by <tt>libbar</tt> are linked
5165               <em>indirectly</em> to <tt>foo</tt>, and the dynamic
5166               linker will load them automatically when it loads
5167               <tt>libbar</tt>.  A package should depend on
5168               the libraries it directly uses, and the dependencies for
5169               those libraries should automatically pull in the other
5170               libraries.
5171             </p>
5172
5173             <p>
5174               Unfortunately, the <prgn>ldd</prgn> program shows both
5175               the directly and indirectly used libraries, meaning that
5176               the dependencies determined included both direct and
5177               indirect dependencies.  The use of <prgn>objdump</prgn>
5178               avoids this problem by determining only the directly
5179               used libraries.
5180             </p>
5181
5182             <p>
5183               A good example of where this helps is the following.  We
5184               could update <tt>libimlib</tt> with a new version that
5185               supports a new graphics format called dgf (but retaining
5186               the same major version number).  If we used the old
5187               <prgn>ldd</prgn> method, every package that uses
5188               <tt>libimlib</tt> would need to be recompiled so it
5189               would also depend on <tt>libdgf</tt> or it wouldn't run
5190               due to missing symbols.  However with the new system,
5191               packages using <tt>libimlib</tt> can rely on
5192               <tt>libimlib</tt> itself having the dependency on
5193               <tt>libdgf</tt> and so they would not need rebuilding.
5194             </p>
5195           </footnote>
5196         </p>
5197
5198         <p>
5199           In the following sections, we will first describe where the
5200           various <tt>shlibs</tt> files are to be found, then how to
5201           use <prgn>dpkg-shlibdeps</prgn>, and finally the <tt>shlibs</tt>
5202           file format and how to create them if your package contains a
5203           shared library.
5204         </p>
5205
5206       <sect1>
5207         <heading>The <tt>shlibs</tt> files present on the system</heading>
5208
5209         <p>
5210           There are several places where <tt>shlibs</tt> files are
5211           found.  The following list gives them in the order in which
5212           they are read by
5213           <qref id="pkg-dpkg-shlibdeps"><prgn>dpkg-shlibdeps</prgn></qref>.
5214           (The first one which gives the required information is used.)
5215         </p>
5216
5217         <p>
5218           <list>
5219             <item>
5220               <p><file>debian/shlibs.local</file></p>
5221
5222               <p>
5223                 This lists overrides for this package.  Its use is
5224                 described below (see <ref id="shlibslocal">).
5225               </p>
5226             </item>
5227
5228             <item>
5229               <p><file>/etc/dpkg/shlibs.override</file></p>
5230
5231               <p>
5232                 This lists global overrides.  This list is normally
5233                 empty.  It is maintained by the local system
5234                 administrator.
5235               </p>
5236             </item>
5237
5238             <item>
5239               <p><file>DEBIAN/shlibs</file> files in the "build directory"</p>
5240
5241               <p>
5242                 When packages are being built, any
5243                 <file>debian/shlibs</file> files are copied into the
5244                 control file area of the temporary build directory and
5245                 given the name <file>shlibs</file>.  These files give
5246                 details of any shared libraries included in the
5247                 package.<footnote>
5248                     An example may help here.  Let us say that the
5249                     source package <tt>foo</tt> generates two binary
5250                     packages, <tt>libfoo2</tt> and
5251                     <tt>foo-runtime</tt>.  When building the binary
5252                     packages, the two packages are created in the
5253                     directories <file>debian/libfoo2</file> and
5254                     <file>debian/foo-runtime</file> respectively.
5255                     (<file>debian/tmp</file> could be used instead of one
5256                     of these.)  Since <tt>libfoo2</tt> provides the
5257                     <tt>libfoo</tt> shared library, it will require a
5258                     <tt>shlibs</tt> file, which will be installed in
5259                     <file>debian/libfoo2/DEBIAN/shlibs</file>, eventually
5260                     to become
5261                     <file>/var/lib/dpkg/info/libfoo2.shlibs</file>.  Then
5262                     when <prgn>dpkg-shlibdeps</prgn> is run on the
5263                     executable
5264                     <file>debian/foo-runtime/usr/bin/foo-prog</file>, it
5265                     will examine the
5266                     <file>debian/libfoo2/DEBIAN/shlibs</file> file to
5267                     determine whether <tt>foo-prog</tt>'s library
5268                     dependencies are satisfied by any of the libraries
5269                     provided by <tt>libfoo2</tt>.  For this reason,
5270                     <prgn>dpkg-shlibdeps</prgn> must only be run once
5271                     all of the individual binary packages'
5272                     <tt>shlibs</tt> files have been installed into the
5273                     build directory.
5274                 </footnote>
5275               </p>
5276             </item>
5277
5278             <item>
5279               <p><file>/var/lib/dpkg/info/*.shlibs</file></p>
5280
5281               <p>
5282                 These are the <file>shlibs</file> files corresponding to
5283                 all of the packages installed on the system, and are
5284                 maintained by the relevant package maintainers.
5285               </p>
5286             </item>
5287
5288             <item>
5289               <p><file>/etc/dpkg/shlibs.default</file></p>
5290
5291               <p>
5292                 This file lists any shared libraries whose packages
5293                 have failed to provide correct <file>shlibs</file> files.
5294                 It was used when the <file>shlibs</file> setup was first
5295                 introduced, but it is now normally empty.  It is
5296                 maintained by the <tt>dpkg</tt> maintainer.
5297               </p>
5298             </item>
5299           </list>
5300         </p>
5301       </sect1>
5302
5303       <sect1>
5304         <heading>How to use <prgn>dpkg-shlibdeps</prgn> and the
5305             <file>shlibs</file> files</heading>
5306
5307         <p>
5308           Put a call to
5309           <qref id="pkg-dpkg-shlibdeps"><prgn>dpkg-shlibdeps</prgn></qref>
5310           into your <file>debian/rules</file> file.  If your package
5311           contains only compiled binaries and libraries (but no scripts),
5312           you can use a command such as:
5313           <example compact="compact">
5314 dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \
5315   debian/tmp/usr/lib/*
5316           </example>
5317           Otherwise, you will need to explicitly list the compiled
5318           binaries and libraries.<footnote>
5319               If you are using <tt>debhelper</tt>, the
5320               <prgn>dh_shlibdeps</prgn> program will do this work for
5321               you.  It will also correctly handle multi-binary
5322               packages.
5323           </footnote>
5324         </p>
5325
5326         <p>
5327           This command puts the dependency information into the
5328           <file>debian/substvars</file> file, which is then used by
5329           <prgn>dpkg-gencontrol</prgn>.  You will need to place a
5330           <tt>${shlibs:Depends}</tt> variable in the <tt>Depends</tt>
5331           field in the control file for this to work.
5332         </p>
5333
5334         <p>
5335           If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
5336           done.  If it does complain you might need to create your own
5337           <file>debian/shlibs.local</file> file, as explained below (see
5338           <ref id="shlibslocal">).
5339         </p>
5340
5341         <p>
5342           If you have multiple binary packages, you will need to call
5343           <prgn>dpkg-shlibdeps</prgn> on each one which contains
5344           compiled libraries or binaries.  In such a case, you will
5345           need to use the <tt>-T</tt> option to the <tt>dpkg</tt>
5346           utilities to specify a different <file>substvars</file> file.
5347         </p>
5348
5349         <p>
5350           If you are creating a udeb for use in the Debian Installer, you
5351           will need to specify that <prgn>dpkg-shlibdeps</prgn> should use
5352           the dependency line of type <tt>udeb</tt> by adding
5353           <tt>-tudeb</tt> as option<footnote>
5354               <prgn>dh_shlibdeps</prgn> from the <tt>debhelper</tt> suite
5355               will automatically add this option if it knows it is
5356               processing a udeb.
5357           </footnote>. If there is no dependency line of type <tt>udeb</tt>
5358           in the <file>shlibs</file> file, <prgn>dpkg-shlibdeps</prgn> will
5359           fall back to the regular dependency line.
5360         </p>
5361
5362         <p>
5363           For more details on dpkg-shlibdeps, please see
5364           <ref id="pkg-dpkg-shlibdeps"> and
5365           <manref name="dpkg-shlibdeps" section="1">.
5366         </p>
5367       </sect1>
5368
5369       <sect1 id="shlibs">
5370         <heading>The <file>shlibs</file> File Format</heading>
5371
5372         <p>
5373           Each <file>shlibs</file> file has the same format.  Lines
5374           beginning with <tt>#</tt> are considered to be comments and
5375           are ignored.  Each line is of the form:
5376           <example compact="compact">
5377 [<var>type</var>: ]<var>library-name</var> <var>soname-version</var> <var>dependencies ...</var>
5378           </example>
5379         </p>
5380
5381         <p>
5382           We will explain this by reference to the example of the
5383           <tt>zlib1g</tt> package, which (at the time of writing)
5384           installs the shared library <file>/usr/lib/libz.so.1.1.3</file>.
5385         </p>
5386
5387         <p>
5388           <var>type</var> is an optional element that indicates the type
5389           of package for which the line is valid. The only type currently
5390           in use is <tt>udeb</tt>. The colon and space after the type are
5391           required.
5392         </p>
5393
5394         <p>
5395           <var>library-name</var> is the name of the shared library,
5396           in this case <tt>libz</tt>.  (This must match the name part
5397           of the soname, see below.)
5398         </p>
5399
5400         <p>
5401           <var>soname-version</var> is the version part of the soname of
5402           the library.  The soname is the thing that must exactly match
5403           for the library to be recognized by the dynamic linker, and is
5404           usually of the form
5405           <tt><var>name</var>.so.<var>major-version</var></tt>, in our
5406           example, <tt>libz.so.1</tt>.<footnote>
5407               This can be determined using the command
5408               <example compact="compact">
5409 objdump -p /usr/lib/libz.so.1.1.3 | grep SONAME
5410               </example>
5411           </footnote>
5412           The version part is the part which comes after
5413           <tt>.so.</tt>, so in our case, it is <tt>1</tt>.
5414         </p>
5415
5416         <p>
5417           <var>dependencies</var> has the same syntax as a dependency
5418           field in a binary package control file.  It should give
5419           details of which packages are required to satisfy a binary
5420           built against the version of the library contained in the
5421           package.  See <ref id="depsyntax"> for details.
5422         </p>
5423
5424         <p>
5425           In our example, if the first version of the <tt>zlib1g</tt>
5426           package which contained a minor number of at least
5427           <tt>1.3</tt> was <var>1:1.1.3-1</var>, then the
5428           <tt>shlibs</tt> entry for this library could say:
5429           <example compact="compact">
5430 libz 1 zlib1g (>= 1:1.1.3)
5431           </example>
5432           The version-specific dependency is to avoid warnings from
5433           the dynamic linker about using older shared libraries with
5434           newer binaries.
5435         </p>
5436
5437         <p>
5438           As zlib1g also provides a udeb containing the shared library,
5439           there would also be a second line:
5440           <example compact="compact">
5441 udeb: libz 1 zlib1g-udeb (>= 1:1.1.3)
5442           </example>
5443         </p>
5444       </sect1>
5445
5446       <sect1>
5447         <heading>Providing a <file>shlibs</file> file</heading>
5448
5449         <p>
5450           If your package provides a shared library, you need to create
5451           a <file>shlibs</file> file following the format described above.
5452           It is usual to call this file <file>debian/shlibs</file> (but if
5453           you have multiple binary packages, you might want to call it
5454           <file>debian/shlibs.<var>package</var></file> instead).  Then
5455           let <file>debian/rules</file> install it in the control area:
5456           <example compact="compact">
5457 install -m644 debian/shlibs debian/tmp/DEBIAN
5458           </example>
5459           or, in the case of a multi-binary package:
5460           <example compact="compact">
5461 install -m644 debian/shlibs.<var>package</var> debian/<var>package</var>/DEBIAN/shlibs
5462           </example>
5463           An alternative way of doing this is to create the
5464           <file>shlibs</file> file in the control area directly from
5465           <file>debian/rules</file> without using a <file>debian/shlibs</file>
5466           file at all,<footnote>
5467               This is what <prgn>dh_makeshlibs</prgn> in the
5468               <tt>debhelper</tt> suite does. If your package also has a udeb
5469               that provides a shared library, <prgn>dh_makeshlibs</prgn> can
5470               automatically generate the <tt>udeb:</tt> lines if you specify
5471               the name of the udeb with the <tt>--add-udeb</tt> option.
5472           </footnote>
5473           since the <file>debian/shlibs</file> file itself is ignored by
5474           <prgn>dpkg-shlibdeps</prgn>.
5475         </p>
5476
5477         <p>
5478           As <prgn>dpkg-shlibdeps</prgn> reads the
5479           <file>DEBIAN/shlibs</file> files in all of the binary packages
5480           being built from this source package, all of the
5481           <file>DEBIAN/shlibs</file> files should be installed before
5482           <prgn>dpkg-shlibdeps</prgn> is called on any of the binary
5483           packages.
5484         </p>
5485       </sect1>
5486
5487       <sect1 id="shlibslocal">
5488         <heading>Writing the <file>debian/shlibs.local</file> file</heading>
5489
5490         <p>
5491           This file is intended only as a <em>temporary</em> fix if
5492           your binaries or libraries depend on a library whose package
5493           does not yet provide a correct <file>shlibs</file> file.
5494         </p>
5495
5496         <p>
5497           We will assume that you are trying to package a binary
5498           <tt>foo</tt>.  When you try running
5499           <prgn>dpkg-shlibdeps</prgn> you get the following error
5500           message (<tt>-O</tt> displays the dependency information on
5501           <tt>stdout</tt> instead of writing it to
5502           <tt>debian/substvars</tt>, and the lines have been wrapped
5503           for ease of reading):
5504           <example compact="compact">
5505 $ dpkg-shlibdeps -O debian/tmp/usr/bin/foo
5506 dpkg-shlibdeps: warning: unable to find dependency
5507   information for shared library libbar (soname 1,
5508   path /usr/lib/libbar.so.1, dependency field Depends)
5509 shlibs:Depends=libc6 (>= 2.2.2-2)
5510           </example>
5511           You can then run <prgn>ldd</prgn> on the binary to find the
5512           full location of the library concerned:
5513           <example compact="compact">
5514 $ ldd foo
5515 libbar.so.1 => /usr/lib/libbar.so.1 (0x4001e000)
5516 libc.so.6 => /lib/libc.so.6 (0x40032000)
5517 /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
5518           </example>
5519           So the <prgn>foo</prgn> binary depends on the
5520           <prgn>libbar</prgn> shared library, but no package seems to
5521           provide a <file>*.shlibs</file> file handling
5522           <file>libbar.so.1</file> in <file>/var/lib/dpkg/info/</file>.  Let's
5523           determine the package responsible:
5524           <example compact="compact">
5525 $ dpkg -S /usr/lib/libbar.so.1
5526 bar1: /usr/lib/libbar.so.1
5527 $ dpkg -s bar1 | grep Version
5528 Version: 1.0-1
5529           </example>
5530           This tells us that the <tt>bar1</tt> package, version 1.0-1,
5531           is the one we are using.  Now we can file a bug against the
5532           <tt>bar1</tt> package and create our own
5533           <file>debian/shlibs.local</file> to locally fix the problem.
5534           Including the following line into your
5535           <file>debian/shlibs.local</file> file:
5536           <example compact="compact">
5537 libbar 1 bar1 (>= 1.0-1)
5538           </example>
5539           should allow the package build to work.
5540         </p>
5541
5542         <p>
5543           As soon as the maintainer of <tt>bar1</tt> provides a
5544           correct <file>shlibs</file> file, you should remove this line
5545           from your <file>debian/shlibs.local</file> file.  (You should
5546           probably also then have a versioned <tt>Build-Depends</tt>
5547           on <tt>bar1</tt> to help ensure that others do not have the
5548           same problem building your package.)
5549         </p>
5550       </sect1>
5551
5552       </sect>
5553
5554     </chapt>
5555
5556
5557     <chapt id="opersys"><heading>The Operating System</heading>
5558
5559       <sect>
5560         <heading>File system hierarchy</heading>
5561
5562
5563         <sect1 id="fhs">
5564           <heading>File System Structure</heading>
5565
5566           <p>
5567             The location of all installed files and directories must
5568             comply with the Filesystem Hierarchy Standard (FHS),
5569             version 2.3, with the exceptions noted below, and except
5570             where doing so would violate other terms of Debian
5571             Policy.  The following exceptions to the FHS apply:
5572
5573             <enumlist>
5574               <item>
5575                 <p>
5576                   The optional rules related to user specific
5577                   configuration files for applications are stored in
5578                   the user's home directory are relaxed.  It is
5579                   recommended that such files start with the
5580                   '<tt>.</tt>' character (a "dot file"), and if an
5581                   application needs to create more than one dot file
5582                   then the preferred placement is in a subdirectory
5583                   with a name starting with a '.' character, (a "dot
5584                   directory"). In this case it is recommended the
5585                   configuration files not start with the '.'
5586                   character.
5587                 </p>
5588               </item>
5589               <item>
5590                 <p>
5591                   The requirement for amd64 to use <file>/lib64</file>
5592                   for 64 bit binaries is removed.
5593                 </p>
5594               </item>
5595               <item>
5596                 <p>
5597                   The requirement that
5598                   <file>/usr/local/share/man</file> be "synonymous"
5599                   with <file>/usr/local/man</file> is relaxed to a
5600                   recommendation</p>
5601               </item>
5602               <item>
5603                 <p>
5604                   The requirement that windowmanagers with a single
5605                   configuration file call it <file>system.*wmrc</file>
5606                   is removed, as is the restriction that the window
5607                   manager subdirectory be named identically to the
5608                   window manager name itself.
5609                 </p>
5610               </item>
5611               <item>
5612                 <p>
5613                   The requirement that boot manager configuration
5614                   files live in <file>/etc</file>, or at least are
5615                   symlinked there, is relaxed to a recommendation.
5616                 </p>
5617               </item>
5618             </enumlist>
5619
5620           </p>
5621           <p>
5622             The version of this document referred here can be
5623             found in the <tt>debian-policy</tt> package or on <url
5624             id="http://www.debian.org/doc/packaging-manuals/fhs/"
5625               name="FHS (Debian copy)"> alongside this manual (or, if
5626             you have the <package>debian-policy</package> installed,
5627             you can try <url
5628               id="file:///usr/share/doc/debian-policy/fhs/" name="FHS
5629               (local copy)">). The
5630             latest version, which may be a more recent version, may
5631             be found on
5632             <url id="http://www.pathname.com/fhs/" name="FHS (upstream)">.
5633             Specific questions about following the standard may be
5634             asked on the <tt>debian-devel</tt> mailing list, or
5635             referred to the FHS mailing list (see the
5636             <url id="http://www.pathname.com/fhs/" name="FHS web site"> for
5637             more information).
5638           </p>
5639         </sect1>
5640
5641         <sect1>
5642           <heading>Site-specific programs</heading>
5643
5644           <p>
5645             As mandated by the FHS, packages must not place any
5646             files in <file>/usr/local</file>, either by putting them in
5647             the file system archive to be unpacked by <prgn>dpkg</prgn>
5648             or by manipulating them in their maintainer scripts.
5649           </p>
5650
5651           <p>
5652             However, the package may create empty directories below
5653             <file>/usr/local</file> so that the system administrator knows
5654             where to place site-specific files.  These are not
5655             directories <em>in</em> <file>/usr/local</file>, but are
5656             children of directories in <file>/usr/local</file>.  These
5657             directories (<file>/usr/local/*/dir/</file>)
5658             should be removed on package removal if they are
5659             empty.
5660           </p>
5661
5662           <p>
5663             Note, that this applies only to directories <em>below</em>
5664             <file>/usr/local</file>, not <em>in</em> <file>/usr/local</file>.
5665             Packages must not create sub-directories in the directory
5666             <file>/usr/local</file> itself, except those listed in FHS,
5667             section 4.5.  However, you may create directories below
5668             them as you wish. You must not remove any of the
5669             directories listed in 4.5, even if you created them.
5670           </p>
5671
5672           <p>
5673             Since <file>/usr/local</file> can be mounted read-only from a
5674             remote server, these directories must be created and
5675             removed by the <prgn>postinst</prgn> and <prgn>prerm</prgn>
5676             maintainer scripts and not be included in the
5677             <file>.deb</file> archive.  These scripts must not fail if
5678             either of these operations fail.
5679           </p>
5680
5681           <p>
5682             For example, the <tt>emacsen-common</tt> package could
5683             contain something like
5684             <example compact="compact">
5685 if [ ! -e /usr/local/share/emacs ]
5686 then
5687   if mkdir /usr/local/share/emacs 2>/dev/null
5688   then
5689     chown root:staff /usr/local/share/emacs
5690     chmod 2775 /usr/local/share/emacs
5691   fi
5692 fi
5693             </example>
5694             in its <prgn>postinst</prgn> script, and
5695             <example compact="compact">
5696 rmdir /usr/local/share/emacs/site-lisp 2>/dev/null || true
5697 rmdir /usr/local/share/emacs 2>/dev/null || true
5698             </example>
5699             in the <prgn>prerm</prgn> script.  (Note that this form is
5700             used to ensure that if the script is interrupted, the
5701             directory <file>/usr/local/share/emacs</file> will still be
5702             removed.)
5703           </p>
5704
5705           <p>
5706             If you do create a directory in <file>/usr/local</file> for
5707             local additions to a package, you should ensure that
5708             settings in <file>/usr/local</file> take precedence over the
5709             equivalents in <file>/usr</file>.
5710           </p>
5711
5712           <p>
5713             However, because <file>/usr/local</file> and its contents are
5714             for exclusive use of the local administrator, a package
5715             must not rely on the presence or absence of files or
5716             directories in <file>/usr/local</file> for normal operation.
5717           </p>
5718
5719           <p>
5720             The <file>/usr/local</file> directory itself and all the
5721             subdirectories created by the package should (by default) have
5722             permissions 2775 (group-writable and set-group-id) and be
5723             owned by <tt>root:staff</tt>.
5724           </p>
5725         </sect1>
5726
5727         <sect1>
5728           <heading>The system-wide mail directory</heading>
5729           <p>
5730             The system-wide mail directory is <file>/var/mail</file>. This
5731             directory is part of the base system and should not owned
5732             by any particular mail agents.  The use of the old
5733             location <file>/var/spool/mail</file> is deprecated, even
5734             though the spool may still be physically located there.
5735           </p>
5736         </sect1>
5737       </sect>
5738
5739       <sect>
5740         <heading>Users and groups</heading>
5741
5742         <sect1>
5743           <heading>Introduction</heading>
5744           <p>
5745             The Debian system can be configured to use either plain or
5746             shadow passwords.
5747           </p>
5748
5749           <p>
5750             Some user ids (UIDs) and group ids (GIDs) are reserved
5751             globally for use by certain packages.  Because some
5752             packages need to include files which are owned by these
5753             users or groups, or need the ids compiled into binaries,
5754             these ids must be used on any Debian system only for the
5755             purpose for which they are allocated. This is a serious
5756             restriction, and we should avoid getting in the way of
5757             local administration policies. In particular, many sites
5758             allocate users and/or local system groups starting at 100.
5759           </p>
5760
5761           <p>
5762             Apart from this we should have dynamically allocated ids,
5763             which should by default be arranged in some sensible
5764             order, but the behavior should be configurable.
5765           </p>
5766
5767           <p>
5768             Packages other than <tt>base-passwd</tt> must not modify
5769             <file>/etc/passwd</file>, <file>/etc/shadow</file>,
5770             <file>/etc/group</file> or <file>/etc/gshadow</file>.
5771           </p>
5772         </sect1>
5773
5774         <sect1>
5775           <heading>UID and GID classes</heading>
5776           <p>
5777             The UID and GID numbers are divided into classes as
5778             follows:
5779             <taglist>
5780               <tag>0-99:</tag>
5781               <item>
5782                 <p>
5783                   Globally allocated by the Debian project, the same
5784                   on every Debian system.  These ids will appear in
5785                   the <file>passwd</file> and <file>group</file> files of all
5786                   Debian systems, new ids in this range being added
5787                   automatically as the <tt>base-passwd</tt> package is
5788                   updated.
5789                 </p>
5790
5791                 <p>
5792                   Packages which need a single statically allocated
5793                   uid or gid should use one of these; their
5794                   maintainers should ask the <tt>base-passwd</tt>
5795                   maintainer for ids.
5796                 </p>
5797               </item>
5798
5799               <tag>100-999:</tag>
5800               <item>
5801                 <p>
5802                   Dynamically allocated system users and groups.
5803                   Packages which need a user or group, but can have
5804                   this user or group allocated dynamically and
5805                   differently on each system, should use <tt>adduser
5806                   --system</tt> to create the group and/or user.
5807                   <prgn>adduser</prgn> will check for the existence of
5808                   the user or group, and if necessary choose an unused
5809                   id based on the ranges specified in
5810                   <file>adduser.conf</file>.
5811                 </p>
5812               </item>
5813
5814               <tag>1000-29999:</tag>
5815               <item>
5816                 <p>
5817                   Dynamically allocated user accounts.  By default
5818                   <prgn>adduser</prgn> will choose UIDs and GIDs for
5819                   user accounts in this range, though
5820                   <file>adduser.conf</file> may be used to modify this
5821                   behavior.
5822                 </p>
5823               </item>
5824
5825               <tag>30000-59999:</tag>
5826               <item>
5827                 <p>Reserved.</p>
5828               </item>
5829
5830               <tag>60000-64999:</tag>
5831               <item>
5832                 <p>
5833                   Globally allocated by the Debian project, but only
5834                   created on demand. The ids are allocated centrally
5835                   and statically, but the actual accounts are only
5836                   created on users' systems on demand.
5837                 </p>
5838
5839                 <p>
5840                   These ids are for packages which are obscure or
5841                   which require many statically-allocated ids.  These
5842                   packages should check for and create the accounts in
5843                   <file>/etc/passwd</file> or <file>/etc/group</file> (using
5844                   <prgn>adduser</prgn> if it has this facility) if
5845                   necessary.  Packages which are likely to require
5846                   further allocations should have a "hole" left after
5847                   them in the allocation, to give them room to
5848                   grow.
5849                 </p>
5850               </item>
5851
5852               <tag>65000-65533:</tag>
5853               <item>
5854                 <p>Reserved.</p>
5855               </item>
5856
5857               <tag>65534:</tag>
5858               <item>
5859                 <p>
5860                   User <tt>nobody</tt>. The corresponding gid refers
5861                   to the group <tt>nogroup</tt>.
5862                 </p>
5863               </item>
5864
5865               <tag>65535:</tag>
5866               <item>
5867                 <p>
5868                   <tt>(uid_t)(-1) == (gid_t)(-1)</tt> <em>must
5869                   not</em> be used, because it is the error return
5870                   sentinel value.
5871                 </p>
5872               </item>
5873             </taglist>
5874           </p>
5875         </sect1>
5876       </sect>
5877
5878       <sect id="sysvinit">
5879         <heading>System run levels and <file>init.d</file> scripts</heading>
5880
5881         <sect1 id="/etc/init.d">
5882           <heading>Introduction</heading>
5883
5884           <p>
5885             The <file>/etc/init.d</file> directory contains the scripts
5886             executed by <prgn>init</prgn> at boot time and when the
5887             init state (or "runlevel") is changed (see <manref
5888             name="init" section="8">).
5889           </p>
5890
5891           <p>
5892             There are at least two different, yet functionally
5893             equivalent, ways of handling these scripts.  For the sake
5894             of simplicity, this document describes only the symbolic
5895             link method. However, it must not be assumed by maintainer
5896             scripts that this method is being used, and any automated
5897             manipulation of the various runlevel behaviors by
5898             maintainer scripts must be performed using
5899             <prgn>update-rc.d</prgn> as described below and not by
5900             manually installing or removing symlinks.  For information
5901             on the implementation details of the other method,
5902             implemented in the <tt>file-rc</tt> package, please refer
5903             to the documentation of that package.
5904           </p>
5905
5906           <p>
5907             These scripts are referenced by symbolic links in the
5908             <file>/etc/rc<var>n</var>.d</file> directories.  When changing
5909             runlevels, <prgn>init</prgn> looks in the directory
5910             <file>/etc/rc<var>n</var>.d</file> for the scripts it should
5911             execute, where <tt><var>n</var></tt> is the runlevel that
5912             is being changed to, or <tt>S</tt> for the boot-up
5913             scripts.
5914           </p>
5915
5916           <p>
5917             The names of the links all have the form
5918             <file>S<var>mm</var><var>script</var></file> or
5919             <file>K<var>mm</var><var>script</var></file> where
5920             <var>mm</var> is a two-digit number and <var>script</var>
5921             is the name of the script (this should be the same as the
5922             name of the actual script in <file>/etc/init.d</file>).
5923           </p>
5924
5925           <p>
5926             When <prgn>init</prgn> changes runlevel first the targets
5927             of the links whose names start with a <tt>K</tt> are
5928             executed, each with the single argument <tt>stop</tt>,
5929             followed by the scripts prefixed with an <tt>S</tt>, each
5930             with the single argument <tt>start</tt>.  (The links are
5931             those in the <file>/etc/rc<var>n</var>.d</file> directory
5932             corresponding to the new runlevel.)  The <tt>K</tt> links
5933             are responsible for killing services and the <tt>S</tt>
5934             link for starting services upon entering the runlevel.
5935           </p>
5936
5937           <p>
5938             For example, if we are changing from runlevel 2 to
5939             runlevel 3, init will first execute all of the <tt>K</tt>
5940             prefixed scripts it finds in <file>/etc/rc3.d</file>, and then
5941             all of the <tt>S</tt> prefixed scripts in that directory.
5942             The links starting with <tt>K</tt> will cause the
5943             referred-to file to be executed with an argument of
5944             <tt>stop</tt>, and the <tt>S</tt> links with an argument
5945             of <tt>start</tt>.
5946           </p>
5947
5948           <p>
5949             The two-digit number <var>mm</var> is used to determine
5950             the order in which to run the scripts: low-numbered links
5951             have their scripts run first.  For example, the
5952             <tt>K20</tt> scripts will be executed before the
5953             <tt>K30</tt> scripts.  This is used when a certain service
5954             must be started before another.  For example, the name
5955             server <prgn>bind</prgn> might need to be started before
5956             the news server <prgn>inn</prgn> so that <prgn>inn</prgn>
5957             can set up its access lists.  In this case, the script
5958             that starts <prgn>bind</prgn> would have a lower number
5959             than the script that starts <prgn>inn</prgn> so that it
5960             runs first:
5961             <example compact="compact">
5962 /etc/rc2.d/S17bind
5963 /etc/rc2.d/S70inn
5964             </example>
5965           </p>
5966
5967           <p>
5968             The two runlevels 0 (halt) and 6 (reboot) are slightly
5969             different.  In these runlevels, the links with an
5970             <tt>S</tt> prefix are still called after those with a
5971             <tt>K</tt> prefix, but they too are called with the single
5972             argument <tt>stop</tt>.
5973           </p>
5974         </sect1>
5975
5976         <sect1>
5977           <heading>Writing the scripts</heading>
5978
5979           <p>
5980             Packages that include daemons for system services should
5981             place scripts in <file>/etc/init.d</file> to start or stop
5982             services at boot time or during a change of runlevel.
5983             These scripts should be named
5984             <file>/etc/init.d/<var>package</var></file>, and they should
5985             accept one argument, saying what to do:
5986
5987             <taglist>
5988               <tag><tt>start</tt></tag>
5989               <item>start the service,</item>
5990
5991               <tag><tt>stop</tt></tag>
5992               <item>stop the service,</item>
5993
5994               <tag><tt>restart</tt></tag>
5995               <item>stop and restart the service if it's already running,
5996                   otherwise start the service</item>
5997
5998               <tag><tt>reload</tt></tag>
5999               <item><p>cause the configuration of the service to be
6000                   reloaded without actually stopping and restarting
6001                   the service,</item>
6002
6003               <tag><tt>force-reload</tt></tag>
6004               <item>cause the configuration to be reloaded if the
6005                   service supports this, otherwise restart the
6006                   service.</item>
6007             </taglist>
6008
6009             The <tt>start</tt>, <tt>stop</tt>, <tt>restart</tt>, and
6010             <tt>force-reload</tt> options should be supported by all
6011             scripts in <file>/etc/init.d</file>, the <tt>reload</tt>
6012             option is optional.
6013           </p>
6014
6015           <p>
6016             The <file>init.d</file> scripts must ensure that they will
6017             behave sensibly (i.e., returning success and not starting
6018             multiple copies of a service) if invoked with <tt>start</tt>
6019             when the service is already running, or with <tt>stop</tt>
6020             when it isn't, and that they don't kill unfortunately-named
6021             user processes.  The best way to achieve this is usually to
6022             use <prgn>start-stop-daemon</prgn> with the <tt>--oknodo</tt>
6023             option.
6024           </p>
6025
6026           <p>
6027             If a service reloads its configuration automatically (as
6028             in the case of <prgn>cron</prgn>, for example), the
6029             <tt>reload</tt> option of the <file>init.d</file> script
6030             should behave as if the configuration has been reloaded
6031             successfully.
6032           </p>
6033
6034           <p>
6035             The <file>/etc/init.d</file> scripts must be treated as
6036             configuration files, either (if they are present in the
6037             package, that is, in the .deb file) by marking them as
6038             <tt>conffile</tt>s, or, (if they do not exist in the .deb)
6039             by managing them correctly in the maintainer scripts (see
6040             <ref id="config-files">).  This is important since we want
6041             to give the local system administrator the chance to adapt
6042             the scripts to the local system, e.g., to disable a
6043             service without de-installing the package, or to specify
6044             some special command line options when starting a service,
6045             while making sure their changes aren't lost during the next
6046             package upgrade.
6047           </p>
6048
6049           <p>
6050             These scripts should not fail obscurely when the
6051             configuration files remain but the package has been
6052             removed, as configuration files remain on the system after
6053             the package has been removed.  Only when <prgn>dpkg</prgn>
6054             is executed with the <tt>--purge</tt> option will
6055             configuration files be removed.  In particular, as the
6056             <file>/etc/init.d/<var>package</var></file> script itself is
6057             usually a <tt>conffile</tt>, it will remain on the system
6058             if the package is removed but not purged.  Therefore, you
6059             should include a <tt>test</tt> statement at the top of the
6060             script, like this:
6061             <example compact="compact">
6062 test -f <var>program-executed-later-in-script</var> || exit 0
6063             </example>
6064           </p>
6065
6066           <p>
6067             Often there are some variables in the <file>init.d</file>
6068             scripts whose values control the behavior of the scripts,
6069             and which a system administrator is likely to want to
6070             change.  As the scripts themselves are frequently
6071             <tt>conffile</tt>s, modifying them requires that the
6072             administrator merge in their changes each time the package
6073             is upgraded and the <tt>conffile</tt> changes.  To ease
6074             the burden on the system administrator, such configurable
6075             values should not be placed directly in the script.
6076             Instead, they should be placed in a file in
6077             <file>/etc/default</file>, which typically will have the same
6078             base name as the <file>init.d</file> script.  This extra file
6079             should be sourced by the script when the script runs.  It
6080             must contain only variable settings and comments in SUSv3
6081             <prgn>sh</prgn> format.  It may either be a
6082             <tt>conffile</tt> or a configuration file maintained by
6083             the package maintainer scripts.  See <ref id="config-files">
6084             for more details.
6085           </p>
6086
6087           <p>
6088             To ensure that vital configurable values are always
6089             available, the <file>init.d</file> script should set default
6090             values for each of the shell variables it uses, either
6091             before sourcing the <file>/etc/default/</file> file or
6092             afterwards using something like the <tt>:
6093             ${VAR:=default}</tt> syntax.  Also, the <file>init.d</file>
6094             script must behave sensibly and not fail if the
6095             <file>/etc/default</file> file is deleted.
6096           </p>
6097
6098           <p>
6099             <file>/var/run</file> and <file>/var/lock</file> may be mounted
6100             as temporary filesystems<footnote>
6101                 For example, using the <tt>RAMRUN</tt> and <tt>RAMLOCK</tt>
6102                 options in <file>/etc/default/rcS</file>.
6103             </footnote>, so the <file>init.d</file> scripts must handle this
6104             correctly. This will typically amount to creating any required
6105             subdirectories dynamically when the <file>init.d</file> script
6106             is run, rather than including them in the package and relying on
6107             <prgn>dpkg</prgn> to create them.
6108           </p>
6109         </sect1>
6110
6111         <sect1>
6112           <heading>Interfacing with the initscript system</heading>
6113
6114           <p>
6115             Maintainers should use the abstraction layer provided by
6116             the <prgn>update-rc.d</prgn> and <prgn>invoke-rc.d</prgn>
6117             programs to deal with initscripts in their packages'
6118             scripts such as <prgn>postinst</prgn>, <prgn>prerm</prgn>
6119             and <prgn>postrm</prgn>.
6120           </p>
6121
6122           <p>
6123             Directly managing the /etc/rc?.d links and directly
6124             invoking the <file>/etc/init.d/</file> initscripts should
6125             be done only by packages providing the initscript
6126             subsystem (such as <prgn>sysv-rc</prgn> and
6127             <prgn>file-rc</prgn>).
6128           </p>
6129
6130           <sect2>
6131             <heading>Managing the links</heading>
6132
6133             <p>
6134               The program <prgn>update-rc.d</prgn> is provided for
6135               package maintainers to arrange for the proper creation and
6136               removal of <file>/etc/rc<var>n</var>.d</file> symbolic links,
6137               or their functional equivalent if another method is being
6138               used.  This may be used by maintainers in their packages'
6139               <prgn>postinst</prgn> and <prgn>postrm</prgn> scripts.
6140             </p>
6141
6142             <p>
6143               You must not include any <file>/etc/rc<var>n</var>.d</file>
6144               symbolic links in the actual archive or manually create or
6145               remove the symbolic links in maintainer scripts; you must
6146               use the <prgn>update-rc.d</prgn> program instead.  (The
6147               former will fail if an alternative method of maintaining
6148               runlevel information is being used.)  You must not include
6149               the <file>/etc/rc<var>n</var>.d</file> directories themselves
6150               in the archive either.  (Only the <tt>sysvinit</tt>
6151               package may do so.)
6152             </p>
6153
6154             <p>
6155               By default <prgn>update-rc.d</prgn> will start services in
6156               each of the multi-user state runlevels (2, 3, 4, and 5)
6157               and stop them in the halt runlevel (0), the single-user
6158               runlevel (1) and the reboot runlevel (6).  The system
6159               administrator will have the opportunity to customize
6160               runlevels by simply adding, moving, or removing the
6161               symbolic links in <file>/etc/rc<var>n</var>.d</file> if
6162               symbolic links are being used, or by modifying
6163               <file>/etc/runlevel.conf</file> if the <tt>file-rc</tt> method
6164               is being used.
6165             </p>
6166
6167             <p>
6168               To get the default behavior for your package, put in your
6169               <prgn>postinst</prgn> script
6170               <example compact="compact">
6171                 update-rc.d <var>package</var> defaults
6172               </example>
6173               and in your <prgn>postrm</prgn>
6174               <example compact="compact">
6175                 if [ "$1" = purge ]; then
6176                 update-rc.d <var>package</var> remove
6177                 fi
6178               </example>. Note that if your package changes runlevels
6179               or priority, you may have to remove and recreate the links,
6180               since otherwise the old links may persist. Refer to the
6181               documentation of <prgn>update-rc.d</prgn>.
6182             </p>
6183
6184             <p>
6185               This will use a default sequence number of 20.  If it does
6186               not matter when or in which order the <file>init.d</file>
6187               script is run, use this default.  If it does, then you
6188               should talk to the maintainer of the <prgn>sysvinit</prgn>
6189               package or post to <tt>debian-devel</tt>, and they will
6190               help you choose a number.
6191             </p>
6192
6193             <p>
6194               For more information about using <tt>update-rc.d</tt>,
6195               please consult its man page <manref name="update-rc.d"
6196                 section="8">.
6197             </p>
6198           </sect2>
6199
6200           <sect2>
6201             <heading>Running initscripts</heading>
6202             <p>
6203               The program <prgn>invoke-rc.d</prgn> is provided to make
6204               it easier for package maintainers to properly invoke an
6205               initscript, obeying runlevel and other locally-defined
6206               constraints that might limit a package's right to start,
6207               stop and otherwise manage services. This program may be
6208               used by maintainers in their packages' scripts.
6209             </p>
6210
6211             <p>
6212               The package maintainer scripts must use
6213               <prgn>invoke-rc.d</prgn> to invoke the
6214               <file>/etc/init.d/*</file> initscripts, instead of
6215               calling them directly.
6216             </p>
6217
6218             <p>
6219               By default, <prgn>invoke-rc.d</prgn> will pass any
6220               action requests (start, stop, reload, restart...) to the
6221               <file>/etc/init.d</file> script, filtering out requests
6222               to start or restart a service out of its intended
6223               runlevels.
6224             </p>
6225
6226             <p>
6227               Most packages will simply need to change:
6228               <example compact="compact">/etc/init.d/&lt;package&gt;
6229               &lt;action&gt;</example> in their <prgn>postinst</prgn>
6230               and <prgn>prerm</prgn> scripts to:
6231               <example compact="compact">
6232         if which invoke-rc.d >/dev/null 2>&1; then
6233                 invoke-rc.d <var>package</var> &lt;action&gt;
6234         else
6235                 /etc/init.d/<var>package</var> &lt;action&gt;
6236         fi
6237               </example>
6238             </p>
6239
6240             <p>
6241               A package should register its initscript services using
6242               <prgn>update-rc.d</prgn> before it tries to invoke them
6243               using <prgn>invoke-rc.d</prgn>. Invocation of
6244               unregistered services may fail.
6245             </p>
6246
6247             <p>
6248               For more information about using
6249               <prgn>invoke-rc.d</prgn>, please consult its man page
6250               <manref name="invoke-rc.d" section="8">.
6251             </p>
6252           </sect2>
6253         </sect1>
6254
6255         <sect1>
6256           <heading>Boot-time initialization</heading>
6257
6258           <p>
6259             There used to be another directory, <file>/etc/rc.boot</file>,
6260             which contained scripts which were run once per machine
6261             boot. This has been deprecated in favour of links from
6262             <file>/etc/rcS.d</file> to files in <file>/etc/init.d</file> as
6263             described in <ref id="/etc/init.d">.  Packages must not
6264             place files in <file>/etc/rc.boot</file>.
6265           </p>
6266         </sect1>
6267
6268         <sect1>
6269           <heading>Example</heading>
6270
6271           <p>
6272             An example on which you can base your
6273             <file>/etc/init.d</file> scripts is found in
6274             <file>/etc/init.d/skeleton</file>.
6275           </p>
6276
6277         </sect1>
6278       </sect>
6279
6280       <sect>
6281         <heading>Console messages from <file>init.d</file> scripts</heading>
6282
6283         <p>
6284           This section describes the formats to be used for messages
6285           written to standard output by the <file>/etc/init.d</file>
6286           scripts.  The intent is to improve the consistency of
6287           Debian's startup and shutdown look and feel.  For this
6288           reason, please look very carefully at the details.  We want
6289           the messages to have the same format in terms of wording,
6290           spaces, punctuation and case of letters.
6291         </p>
6292
6293         <p>
6294           Here is a list of overall rules that should be used for
6295           messages generated by <file>/etc/init.d</file> scripts.  
6296         </p>
6297
6298         <p>
6299           <list>
6300             <item>
6301                 The message should fit in one line (fewer than 80
6302                 characters), start with a capital letter and end with
6303                 a period (<tt>.</tt>) and line feed (<tt>"\n"</tt>).
6304             </item>
6305
6306             <item>
6307               If the script is performing some time consuming task in
6308               the background (not merely starting or stopping a
6309               program, for instance), an ellipsis (three dots:
6310               <tt>...</tt>) should be output to the screen, with no
6311               leading or tailing whitespace or line feeds.
6312             </item>
6313
6314             <item>
6315               The messages should appear as if the computer is telling
6316               the user what it is doing (politely :-), but should not
6317                 mention "it" directly.  For example, instead of:
6318                 <example compact="compact">
6319 I'm starting network daemons: nfsd mountd.
6320                 </example>
6321                 the message should say
6322                 <example compact="compact">
6323 Starting network daemons: nfsd mountd.
6324                 </example>
6325             </item>
6326           </list>
6327         </p>
6328
6329         <p>
6330           <tt>init.d</tt> script should use the following  standard
6331           message formats for the situations enumerated below.
6332         </p>
6333
6334         <p>
6335           <list>
6336             <item>
6337               <p>When daemons are started</p>
6338
6339               <p>
6340                 If the script starts one or more daemons, the output
6341                 should look like this (a single line, no leading
6342                 spaces):
6343                 <example compact="compact">
6344 Starting <var>description</var>: <var>daemon-1</var> ... <var>daemon-n</var>.
6345                 </example>
6346                 The <var>description</var> should describe the
6347                 subsystem the daemon or set of daemons are part of,
6348                 while <var>daemon-1</var> up to <var>daemon-n</var>
6349                 denote each daemon's name (typically the file name of
6350                 the program).
6351               </p>
6352
6353               <p>
6354                 For example, the output of <file>/etc/init.d/lpd</file>
6355                 would look like:
6356                 <example compact="compact">
6357 Starting printer spooler: lpd.
6358                 </example>
6359               </p>
6360
6361               <p>
6362                 This can be achieved by saying
6363                 <example compact="compact">
6364 echo -n "Starting printer spooler: lpd"
6365 start-stop-daemon --start --quiet --exec /usr/sbin/lpd
6366 echo "."
6367                 </example>
6368                 in the script. If there are more than one daemon to
6369                 start, the output should look like this:
6370                 <example compact="compact">
6371 echo -n "Starting remote file system services:"
6372 echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
6373 echo -n " mountd"; start-stop-daemon --start --quiet mountd
6374 echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
6375 echo "."
6376                 </example>
6377                 This makes it possible for the user to see what is
6378                 happening and when the final daemon has been started.
6379                 Care should be taken in the placement of white spaces:
6380                 in the example above the system administrators can
6381                 easily comment out a line if they don't want to start
6382                 a specific daemon, while the displayed message still
6383                 looks good.
6384               </p>
6385             </item>
6386
6387             <item>
6388               <p>When a system parameter is being set</p>
6389
6390               <p>
6391                 If you have to set up different system parameters
6392                 during the system boot, you should use this format:
6393                 <example compact="compact">
6394 Setting <var>parameter</var> to "<var>value</var>".
6395                 </example>
6396               </p>
6397
6398               <p>
6399                 You can use a statement such as the following to get
6400                 the quotes right:
6401                 <example compact="compact">
6402 echo "Setting DNS domainname to \"$domainname\"."
6403                 </example>
6404               </p>
6405
6406               <p>
6407                 Note that the same symbol (<tt>"</tt>) <!-- " --> is used
6408                 for the left and right quotation marks.  A grave accent
6409                 (<tt>`</tt>) is not a quote character; neither is an
6410                 apostrophe (<tt>'</tt>).
6411               </p>
6412             </item>
6413
6414             <item>
6415               <p>When a daemon is stopped or restarted</p>
6416
6417               <p>
6418                 When you stop or restart a daemon, you should issue a
6419                 message identical to the startup message, except that
6420                 <tt>Starting</tt> is replaced with <tt>Stopping</tt>
6421                 or <tt>Restarting</tt> respectively.
6422               </p>
6423
6424               <p>
6425                 For example, stopping the printer daemon will look like
6426                 this:
6427                 <example compact="compact">
6428 Stopping printer spooler: lpd.
6429                 </example>
6430               </p>
6431             </item>
6432
6433             <item>
6434               <p>When something is executed</p>
6435
6436               <p>
6437                 There are several examples where you have to run a
6438                 program at system startup or shutdown to perform a
6439                 specific task, for example, setting the system's clock
6440                 using <prgn>netdate</prgn> or killing all processes
6441                 when the system shuts down.  Your message should look
6442                 like this:
6443                 <example compact="compact">
6444 Doing something very useful...done.
6445                 </example>
6446                 You should print the <tt>done.</tt> immediately after
6447                 the job has been completed, so that the user is
6448                 informed why they have to wait.  You can get this
6449                 behavior by saying
6450                 <example compact="compact">
6451 echo -n "Doing something very useful..."
6452 do_something
6453 echo "done."
6454                 </example>
6455                 in your script.
6456               </p>
6457             </item>
6458
6459             <item>
6460               <p>When the configuration is reloaded</p>
6461
6462               <p>
6463                 When a daemon is forced to reload its configuration
6464                 files you should use the following format:
6465                 <example compact="compact">
6466 Reloading <var>description</var> configuration...done.
6467                 </example>
6468                 where <var>description</var> is the same as in the
6469                 daemon starting message.
6470               </p>
6471             </item>
6472           </list>
6473         </p>
6474       </sect>
6475
6476       <sect>
6477         <heading>Cron jobs</heading>
6478
6479         <p>
6480           Packages must not modify the configuration file
6481           <file>/etc/crontab</file>, and they must not modify the files in
6482           <file>/var/spool/cron/crontabs</file>.</p>
6483
6484         <p>
6485           If a package wants to install a job that has to be executed
6486           via cron, it should place a file with the name of the
6487           package in one or more of the following directories:
6488           <example compact="compact">
6489 /etc/cron.hourly
6490 /etc/cron.daily
6491 /etc/cron.weekly
6492 /etc/cron.monthly
6493           </example>
6494           As these directory names imply, the files within them are
6495           executed on an hourly, daily, weekly, or monthly basis,
6496           respectively. The exact times are listed in
6497           <file>/etc/crontab</file>.</p>
6498
6499         <p>
6500           All files installed in any of these directories must be
6501           scripts (e.g., shell scripts or Perl scripts) so that they
6502           can easily be modified by the local system administrator.
6503           In addition, they must be treated as configuration files.
6504         </p>
6505
6506         <p>
6507           If a certain job has to be executed at some other frequency or
6508           at a specific time, the package should install a file
6509           <file>/etc/cron.d/<var>package</var></file>. This file uses the
6510           same syntax as <file>/etc/crontab</file> and is processed by
6511           <prgn>cron</prgn> automatically. The file must also be
6512           treated as a configuration file. (Note that entries in the
6513           <file>/etc/cron.d</file> directory are not handled by
6514           <prgn>anacron</prgn>. Thus, you should only use this
6515           directory for jobs which may be skipped if the system is not
6516           running.)</p>
6517
6518         <p>
6519           The scripts or crontab entries in these directories should
6520           check if all necessary programs are installed before they
6521           try to execute them. Otherwise, problems will arise when a
6522           package was removed but not purged since configuration files
6523           are kept on the system in this situation.</p>
6524       </sect>
6525
6526       <sect id="menus">
6527         <heading>Menus</heading>
6528
6529         <p>
6530           The Debian <tt>menu</tt> package provides a standard
6531           interface between packages providing applications and
6532           <em>menu programs</em> (either X window managers or
6533           text-based menu programs such as <prgn>pdmenu</prgn>).
6534         </p>
6535
6536         <p>
6537           All packages that provide applications that need not be
6538           passed any special command line arguments for normal
6539           operation should register a menu entry for those
6540           applications, so that users of the <tt>menu</tt> package
6541           will automatically get menu entries in their window
6542           managers, as well in shells like <tt>pdmenu</tt>.
6543         </p>
6544
6545         <p>
6546           Menu entries should follow the current menu policy.
6547         </p>
6548
6549         <p>
6550           The menu policy can be found in the <tt>menu-policy</tt>
6551           files in the <tt>debian-policy</tt> package.
6552           It is also available from the Debian web mirrors at
6553           <tt><url name="/doc/packaging-manuals/menu-policy/"
6554                 id="http://www.debian.org/doc/packaging-manuals/menu-policy/"></tt>.
6555         </p>
6556
6557         <p>
6558           Please also refer to the <em>Debian Menu System</em>
6559           documentation that comes with the <package>menu</package>
6560           package for information about how to register your
6561           applications.
6562         </p>
6563       </sect>
6564
6565       <sect id="mime">
6566         <heading>Multimedia handlers</heading>
6567
6568         <p>
6569           MIME (Multipurpose Internet Mail Extensions, RFCs 2045-2049)
6570           is a mechanism for encoding files and data streams and
6571           providing meta-information about them, in particular their
6572           type (e.g.  audio or video) and format (e.g. PNG, HTML,
6573           MP3).
6574         </p>
6575
6576         <p>
6577           Registration of MIME type handlers allows programs like mail
6578           user agents and web browsers to invoke these handlers to
6579           view, edit or display MIME types they don't support directly.
6580         </p>
6581
6582         <p>
6583           Packages which provide the ability to view/show/play,
6584           compose, edit or print MIME types should register themselves
6585           as such following the current MIME support policy.
6586         </p>
6587
6588         <p>
6589           The MIME support policy can be found in the <tt>mime-policy</tt>
6590           files in the <tt>debian-policy</tt> package.
6591           It is also available from the Debian web mirrors at
6592           <tt><url name="/doc/packaging-manuals/mime-policy/"
6593                 id="http://www.debian.org/doc/packaging-manuals/mime-policy/"></tt>.
6594         </p>
6595
6596       </sect>
6597
6598       <sect>
6599         <heading>Keyboard configuration</heading>
6600
6601         <p>
6602           To achieve a consistent keyboard configuration so that all
6603           applications interpret a keyboard event the same way, all
6604           programs in the Debian distribution must be configured to
6605           comply with the following guidelines.
6606         </p>
6607
6608         <p>
6609           The following keys must have the specified interpretations:
6610
6611           <taglist>
6612             <tag><tt>&lt;--</tt></tag>
6613             <item>delete the character to the left of the cursor</item>
6614
6615             <tag><tt>Delete</tt></tag>
6616             <item>delete the character to the right of the cursor</item>
6617
6618             <tag><tt>Control+H</tt></tag>
6619             <item>emacs: the help prefix</item>
6620           </taglist>
6621
6622           The interpretation of any keyboard events should be
6623           independent of the terminal that is used, be it a virtual
6624           console, an X terminal emulator, an rlogin/telnet session,
6625           etc.
6626         </p>
6627
6628         <p>
6629           The following list explains how the different programs
6630           should be set up to achieve this:
6631         </p>
6632
6633         <p>
6634           <list>
6635             <item>
6636                 <tt>&lt;--</tt> generates <tt>KB_BackSpace</tt> in X.
6637             </item>
6638
6639             <item>
6640                 <tt>Delete</tt> generates <tt>KB_Delete</tt> in X.
6641             </item>
6642
6643             <item>
6644                 X translations are set up to make
6645                 <tt>KB_Backspace</tt> generate ASCII DEL, and to make
6646                 <tt>KB_Delete</tt> generate <tt>ESC [ 3 ~</tt> (this
6647                 is the vt220 escape code for the "delete character"
6648                 key).  This must be done by loading the X resources
6649                 using <prgn>xrdb</prgn> on all local X displays, not
6650                 using the application defaults, so that the
6651                 translation resources used correspond to the
6652                 <prgn>xmodmap</prgn> settings.
6653             </item>
6654
6655             <item>
6656                 The Linux console is configured to make
6657                 <tt>&lt;--</tt> generate DEL, and <tt>Delete</tt>
6658                 generate <tt>ESC [ 3 ~</tt>.
6659             </item>
6660
6661             <item>
6662                 X applications are configured so that <tt>&lt;</tt>
6663                 deletes left, and <tt>Delete</tt> deletes right.  Motif
6664                 applications already work like this.
6665             </item>
6666
6667             <item>
6668                 Terminals should have <tt>stty erase ^?</tt> .
6669             </item>
6670
6671             <item>
6672                 The <tt>xterm</tt> terminfo entry should have <tt>ESC
6673                 [ 3 ~</tt> for <tt>kdch1</tt>, just as for
6674                 <tt>TERM=linux</tt> and <tt>TERM=vt220</tt>.
6675             </item>
6676
6677             <item>
6678                 Emacs is programmed to map <tt>KB_Backspace</tt> or
6679                 the <tt>stty erase</tt> character to
6680                 <tt>delete-backward-char</tt>, and <tt>KB_Delete</tt>
6681                 or <tt>kdch1</tt> to <tt>delete-forward-char</tt>, and
6682                 <tt>^H</tt> to <tt>help</tt> as always.
6683             </item>
6684
6685             <item>
6686                 Other applications use the <tt>stty erase</tt>
6687                 character and <tt>kdch1</tt> for the two delete keys,
6688                 with ASCII DEL being "delete previous character" and
6689                 <tt>kdch1</tt> being "delete character under
6690                 cursor".
6691             </item>
6692
6693           </list>
6694         </p>
6695
6696         <p>
6697           This will solve the problem except for the following
6698           cases:
6699         </p>
6700
6701         <p>
6702           <list>
6703             <item>
6704                 Some terminals have a <tt>&lt;--</tt> key that cannot
6705                 be made to produce anything except <tt>^H</tt>.  On
6706                 these terminals Emacs help will be unavailable on
6707                 <tt>^H</tt> (assuming that the <tt>stty erase</tt>
6708                 character takes precedence in Emacs, and has been set
6709                 correctly).  <tt>M-x help</tt> or <tt>F1</tt> (if
6710                 available) can be used instead.
6711             </item>
6712
6713             <item>
6714                 Some operating systems use <tt>^H</tt> for <tt>stty
6715                 erase</tt>.  However, modern telnet versions and all
6716                 rlogin versions propagate <tt>stty</tt> settings, and
6717                 almost all UNIX versions honour <tt>stty erase</tt>.
6718                 Where the <tt>stty</tt> settings are not propagated
6719                 correctly, things can be made to work by using
6720                 <tt>stty</tt> manually.
6721             </item>
6722
6723             <item>
6724                 Some systems (including previous Debian versions) use
6725                 <prgn>xmodmap</prgn> to arrange for both
6726                 <tt>&lt;--</tt> and <tt>Delete</tt> to generate
6727                 <tt>KB_Delete</tt>.  We can change the behavior of
6728                 their X clients using the same X resources that we use
6729                 to do it for our own clients, or configure our clients
6730                 using their resources when things are the other way
6731                 around.  On displays configured like this
6732                 <tt>Delete</tt> will not work, but <tt>&lt;--</tt>
6733                 will.
6734             </item>
6735
6736             <item>
6737                 Some operating systems have different <tt>kdch1</tt>
6738                 settings in their <tt>terminfo</tt> database for
6739                 <tt>xterm</tt> and others.  On these systems the
6740                 <tt>Delete</tt> key will not work correctly when you
6741                 log in from a system conforming to our policy, but
6742                 <tt>&lt;--</tt> will.
6743             </item>
6744           </list>
6745         </p>
6746       </sect>
6747
6748       <sect>
6749         <heading>Environment variables</heading>
6750
6751         <p>
6752           A program must not depend on environment variables to get
6753           reasonable defaults.  (That's because these environment
6754           variables would have to be set in a system-wide
6755           configuration file like <file>/etc/profile</file>, which is not
6756           supported by all shells.)
6757         </p>
6758
6759         <p>
6760           If a program usually depends on environment variables for its
6761           configuration, the program should be changed to fall back to
6762           a reasonable default configuration if these environment
6763           variables are not present. If this cannot be done easily
6764           (e.g., if the source code of a non-free program is not
6765           available), the program must be replaced by a small
6766           "wrapper" shell script which sets the environment variables
6767           if they are not already defined, and calls the original program.
6768         </p>
6769
6770         <p>
6771           Here is an example of a wrapper script for this purpose:
6772
6773           <example compact="compact">
6774 #!/bin/sh
6775 BAR=${BAR:-/var/lib/fubar}
6776 export BAR
6777 exec /usr/lib/foo/foo "$@"
6778           </example>
6779         </p>
6780
6781         <p>
6782           Furthermore, as <file>/etc/profile</file> is a configuration
6783           file of the <prgn>base-files</prgn> package, other packages must
6784           not put any environment variables or other commands into that
6785           file.
6786         </p>
6787       </sect>
6788
6789       <sect id="doc-base">
6790         <heading>Registering Documents using doc-base</heading>
6791
6792         <p>
6793           The <package>doc-base</package> package implements a
6794           flexible mechanism for handling and presenting
6795           documentation. The recommended practice is for every Debian
6796           package that provides online documentation (other than just
6797           manual pages) to register these documents with
6798           <package>doc-base</package> by installing a
6799           <package>doc-base</package> control file via the
6800           <prgn/install-docs/ script at installation time and
6801           de-register the manuals again when the package is removed.
6802         </p> 
6803         <p>
6804           Please refer to the documentation that comes with the
6805           <package>doc-base</package>  package for information and
6806           details. 
6807         </p>
6808       </sect>
6809
6810     </chapt>
6811
6812
6813     <chapt id="files">
6814       <heading>Files</heading>
6815
6816       <sect>
6817         <heading>Binaries</heading>
6818
6819         <p>
6820           Two different packages must not install programs with
6821           different functionality but with the same filenames.  (The
6822           case of two programs having the same functionality but
6823           different implementations is handled via "alternatives" or
6824           the "Conflicts" mechanism.  See <ref id="maintscripts"> and
6825           <ref id="conflicts"> respectively.)  If this case happens,
6826           one of the programs must be renamed.  The maintainers should
6827           report this to the <tt>debian-devel</tt> mailing list and
6828           try to find a consensus about which program will have to be
6829           renamed.  If a consensus cannot be reached, <em>both</em>
6830           programs must be renamed.
6831         </p>
6832
6833         <p>
6834          By default, when a package is being built, any binaries
6835          created should include debugging information, as well as
6836          being compiled with optimization.  You should also turn on
6837          as many reasonable compilation warnings as possible; this
6838          makes life easier for porters, who can then look at build
6839          logs for possible problems.  For the C programming language,
6840          this means the following compilation parameters should be
6841          used:
6842           <example compact="compact">
6843 CC = gcc
6844 CFLAGS = -O2 -g -Wall # sane warning options vary between programs
6845 LDFLAGS = # none
6846 INSTALL = install -s # (or use strip on the files in debian/tmp)
6847           </example>
6848         </p>
6849
6850         <p>
6851           Note that by default all installed binaries should be stripped,
6852           either by using the <tt>-s</tt> flag to
6853           <prgn>install</prgn>, or by calling <prgn>strip</prgn> on
6854           the binaries after they have been copied into
6855           <file>debian/tmp</file> but before the tree is made into a
6856           package.
6857         </p>
6858
6859         <p>
6860           Although binaries in the build tree should be compiled with
6861           debugging information by default, it can often be difficult to
6862           debug programs if they are also subjected to compiler
6863           optimization.  For this reason, it is recommended to support the
6864           standardized environment variable <tt>DEB_BUILD_OPTIONS</tt>
6865           (see <ref id="debianrules-options">).  This variable can contain
6866           several flags to change how a package is compiled and built.
6867         </p>
6868
6869         <p>
6870           It is up to the package maintainer to decide what
6871           compilation options are best for the package.  Certain
6872           binaries (such as computationally-intensive programs) will
6873           function better with certain flags (<tt>-O3</tt>, for
6874           example); feel free to use them.  Please use good judgment
6875           here.  Don't use flags for the sake of it; only use them
6876           if there is good reason to do so.  Feel free to override
6877           the upstream author's ideas about which compilation
6878           options are best: they are often inappropriate for our
6879           environment.
6880         </p>
6881       </sect>
6882
6883
6884       <sect id="libraries">
6885         <heading>Libraries</heading>
6886
6887         <p>
6888           If the package is <strong>architecture: any</strong>, then
6889           the shared library compilation and linking flags must have
6890           <tt>-fPIC</tt>, or the package shall not build on some of
6891           the supported architectures<footnote>
6892             <p>
6893               If you are using GCC, <tt>-fPIC</tt> produces code with
6894               relocatable position independent code, which is required for
6895               most architectures to create a shared library, with i386 and
6896               perhaps some others where non position independent code is
6897               permitted in a shared library.
6898             </p>
6899             <p>
6900               Position independent code may have a performance penalty,
6901               especially on <tt>i386</tt>. However, in most cases the
6902               speed penalty must be measured against the memory wasted on
6903               the few architectures where non position independent code is
6904               even possible.
6905             </p>
6906           </footnote>. Any exception to this rule must be discussed on
6907           the mailing list <em>debian-devel@lists.debian.org</em>, and
6908           a rough consensus obtained.  The reasons for not compiling
6909           with <tt>-fPIC</tt> flag must be recorded in the file
6910           <tt>README.Debian</tt>, and care must be taken to either
6911           restrict the architecture or arrange for <tt>-fPIC</tt> to
6912           be used on architectures where it is required.<footnote>
6913             <p>
6914               Some of the reasons why this might be required is if the
6915               library contains hand crafted assembly code that is not
6916               relocatable, the speed penalty is excessive for compute
6917               intensive libs, and similar reasons.
6918             </p>
6919           </footnote>
6920         </p>
6921         <p>
6922           As to the static libraries, the common case is not to have
6923           relocatable code, since there is no benefit, unless in specific
6924           cases; therefore the static version must not be compiled
6925           with the <tt>-fPIC</tt> flag. Any exception to this rule
6926           should be discussed on the mailing list
6927           <em>debian-devel@lists.debian.org</em>,  and the reasons for
6928           compiling with the <tt>-fPIC</tt> flag must be recorded in
6929           the file <tt>README.Debian</tt>. <footnote>
6930             <p>
6931               Some of the reasons for linking static libraries with
6932               the <tt>-fPIC</tt> flag are if, for example, one needs a
6933               Perl API for a library that is under rapid development,
6934               and has an unstable API, so shared libraries are
6935               pointless at this phase of the library's development. In
6936               that case, since Perl needs a library with relocatable
6937               code, it may make sense to create a static library with
6938               relocatable code. Another reason cited is if you are
6939               distilling various libraries into a common shared
6940               library, like <tt>mklibs</tt> does in the Debian
6941               installer project.
6942             </p>
6943           </footnote>
6944         </p>
6945         <p>
6946           In other words, if both a shared and a static library is
6947           being built, each source unit (<tt>*.c</tt>, for example,
6948           for C files) will need to be compiled twice, for the normal
6949           case. 
6950         </p>
6951         <p>
6952           You must specify the gcc option <tt>-D_REENTRANT</tt>
6953           when building a library (either static or shared) to make
6954           the library compatible with LinuxThreads.
6955         </p>
6956
6957         <p>
6958           Although not enforced by the build tools, shared libraries
6959           must be linked against all libraries that they use symbols from
6960           in the same way that binaries are.  This ensures the correct
6961           functioning of the <qref id="sharedlibs-shlibdeps">shlibs</qref>
6962           system and guarantees that all libraries can be safely opened
6963           with <tt>dlopen()</tt>.  Packagers may wish to use the gcc
6964           option <tt>-Wl,-z,defs</tt> when building a shared library.
6965           Since this option enforces symbol resolution at build time,
6966           a missing library reference will be caught early as a fatal
6967           build error.
6968         </p>
6969
6970         <p>
6971           All installed shared libraries should be stripped with
6972           <example compact="compact">
6973 strip --strip-unneeded <var>your-lib</var>
6974           </example>
6975           (The option <tt>--strip-unneeded</tt> makes
6976           <prgn>strip</prgn> remove only the symbols which aren't
6977           needed for relocation processing.)  Shared libraries can
6978           function perfectly well when stripped, since the symbols for
6979           dynamic linking are in a separate part of the ELF object
6980           file.<footnote>
6981               You might also want to use the options
6982               <tt>--remove-section=.comment</tt> and
6983               <tt>--remove-section=.note</tt> on both shared libraries
6984               and executables, and <tt>--strip-debug</tt> on static
6985               libraries.
6986           </footnote>
6987         </p>
6988
6989         <p>
6990           Note that under some circumstances it may be useful to
6991           install a shared library unstripped, for example when
6992           building a separate package to support debugging.
6993         </p>
6994
6995         <p>
6996           Shared object files (often <file>.so</file> files) that are not
6997           public libraries, that is, they are not meant to be linked
6998           to by third party executables (binaries of other packages),
6999           should be installed in subdirectories of the
7000           <file>/usr/lib</file> directory.  Such files are exempt from the
7001           rules that govern ordinary shared libraries, except that
7002           they must not be installed executable and should be
7003           stripped.<footnote>
7004               A common example are the so-called "plug-ins",
7005               internal shared objects that are dynamically loaded by
7006               programs using <manref name="dlopen" section="3">.
7007           </footnote>
7008         </p>
7009
7010         <p>
7011           An ever increasing number of packages are using
7012           <prgn>libtool</prgn> to do their linking.  The latest GNU
7013           libtools (>= 1.3a) can take advantage of the metadata in the
7014           installed <prgn>libtool</prgn> archive files (<file>*.la</file>
7015           files).  The main advantage of <prgn>libtool</prgn>'s
7016           <file>.la</file> files is that it allows <prgn>libtool</prgn> to
7017           store and subsequently access metadata with respect to the
7018           libraries it builds.  <prgn>libtool</prgn> will search for
7019           those files, which contain a lot of useful information about
7020           a library (such as library dependency information for static
7021           linking).  Also, they're <em>essential</em> for programs
7022           using <tt>libltdl</tt>.<footnote>
7023               Although <prgn>libtool</prgn> is fully capable of
7024               linking against shared libraries which don't have
7025               <tt>.la</tt> files, as it is a mere shell script it can
7026               add considerably to the build time of a
7027               <prgn>libtool</prgn>-using package if that shell script
7028               has to derive all this information from first principles
7029               for each library every time it is linked.  With the
7030               advent of <prgn>libtool</prgn> version 1.4 (and to a
7031               lesser extent <prgn>libtool</prgn> version 1.3), the
7032               <file>.la</file> files also store information about
7033               inter-library dependencies which cannot necessarily be
7034               derived after the <file>.la</file> file is deleted.
7035           </footnote>
7036         </p>
7037
7038         <p>
7039           Packages that use <prgn>libtool</prgn> to create shared
7040           libraries should include the <file>.la</file> files in the
7041           <tt>-dev</tt> package, unless the package relies on
7042           <tt>libtool</tt>'s <tt>libltdl</tt> library, in which case
7043           the <tt>.la</tt> files must go in the run-time library
7044           package.
7045         </p>
7046
7047         <p>
7048           You must make sure that you use only released versions of
7049           shared libraries to build your packages; otherwise other
7050           users will not be able to run your binaries
7051           properly. Producing source packages that depend on
7052           unreleased compilers is also usually a bad
7053           idea.
7054         </p>
7055       </sect>
7056
7057
7058       <sect>
7059         <heading>Shared libraries</heading>
7060         <p>
7061           This section has moved to <ref id="sharedlibs">.
7062         </p>
7063       </sect>
7064
7065
7066       <sect id="scripts">
7067         <heading>Scripts</heading>
7068
7069         <p>
7070           All command scripts, including the package maintainer
7071           scripts inside the package and used by <prgn>dpkg</prgn>,
7072           should have a <tt>#!</tt> line naming the shell to be used
7073           to interpret them.
7074         </p>
7075
7076         <p>
7077           In the case of Perl scripts this should be
7078           <tt>#!/usr/bin/perl</tt>.
7079         </p>
7080
7081         <p>
7082           When scripts are installed into a directory in the system
7083           PATH, the script name should not include an extension such
7084           as <tt>.sh</tt> or <tt>.pl</tt> that denotes the scripting
7085           language currently used to implement it.
7086         </p>
7087         <p>
7088           Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>)
7089           should almost certainly start with <tt>set -e</tt> so that
7090           errors are detected.  Every script should use
7091           <tt>set -e</tt> or check the exit status of <em>every</em>
7092           command.
7093         </p>
7094
7095         <p>
7096           Scripts may assume that <file>/bin/sh</file> implements the
7097           SUSv3 Shell Command Language<footnote>
7098             Single UNIX Specification, version 3, which is also IEEE
7099             1003.1-2004 (POSIX), and is available on the World Wide Web
7100             from <url id="http://www.unix.org/version3/online.html"
7101                       name="The Open Group"> after free
7102             registration.</footnote>
7103           plus the following additional features not mandated by
7104           SUSv3:<footnote>
7105             These features are in widespread use in the Linux community
7106             and are implemented in all of bash, dash, and ksh, the most
7107             common shells users may wish to use as <file>/bin/sh</file>.
7108           </footnote>
7109           <list>
7110             <item><tt>echo -n</tt>, if implemented as a shell built-in,
7111               must not generate a newline.</item>
7112             <item><tt>test</tt>, if implemented as a shell built-in, must
7113               support <tt>-a</tt> and <tt>-o</tt> as binary logical
7114               operators.</item>
7115             <item><tt>local</tt> to create a scoped variable must be
7116               supported, including listing multiple variables in a single
7117               local command and assigning a value to a variable at the
7118               same time as localizing it.  <tt>local</tt> may or
7119               may not preserve the variable value from an outer scope if
7120               no assignment is present.  Uses such as:
7121 <example compact>
7122 fname () {
7123     local a b c=delta d
7124     # ... use a, b, c, d ...
7125 }
7126 </example>
7127               must be supported and must set the value of <tt>c</tt> to
7128               <tt>delta</tt>.
7129             </item>
7130           </list>
7131           If a shell script requires non-SUSv3 features from the shell
7132           interpreter other than those listed above, the appropriate shell
7133           must be specified in the first line of the script (e.g.,
7134           <tt>#!/bin/bash</tt>) and the package must depend on the package
7135           providing the shell (unless the shell package is marked
7136           "Essential", as in the case of <prgn>bash</prgn>).
7137         </p>
7138
7139         <p>
7140           You may wish to restrict your script to SUSv3 features plus the
7141           above set when possible so that it may use <file>/bin/sh</file>
7142           as its interpreter. If your script works with <prgn>dash</prgn>
7143           (originally called <prgn>ash</prgn>), it probably complies with
7144           the above requirements, but if you are in doubt, use
7145           <file>/bin/bash</file>.
7146         </p>
7147
7148         <p>
7149           Perl scripts should check for errors when making any
7150           system calls, including <tt>open</tt>, <tt>print</tt>,
7151           <tt>close</tt>, <tt>rename</tt> and <tt>system</tt>.
7152         </p>
7153
7154         <p>
7155           <prgn>csh</prgn> and <prgn>tcsh</prgn> should be avoided as
7156           scripting languages.  See <em>Csh Programming Considered
7157           Harmful</em>, one of the <tt>comp.unix.*</tt> FAQs, which
7158           can be found at <url id="http://www.faqs.org/faqs/unix-faq/shell/csh-whynot/">.
7159           If an upstream package comes with <prgn>csh</prgn> scripts
7160           then you must make sure that they start with
7161           <tt>#!/bin/csh</tt> and make your package depend on the
7162           <prgn>c-shell</prgn> virtual package.
7163         </p>
7164
7165         <p>
7166           Any scripts which create files in world-writeable
7167           directories (e.g., in <file>/tmp</file>) must use a
7168           mechanism which will fail atomically if a file with the same
7169           name already exists.
7170         </p>
7171
7172         <p>
7173           The Debian base system provides the <prgn>tempfile</prgn>
7174           and <prgn>mktemp</prgn> utilities for use by scripts for
7175           this purpose.
7176         </p>
7177       </sect>
7178
7179
7180       <sect>
7181         <heading>Symbolic links</heading>
7182
7183         <p>
7184           In general, symbolic links within a top-level directory
7185           should be relative, and symbolic links pointing from one
7186           top-level directory into another should be absolute. (A
7187           top-level directory is a sub-directory of the root
7188           directory <file>/</file>.)
7189         </p>
7190
7191         <p>
7192           In addition, symbolic links should be specified as short as
7193           possible, i.e., link targets like <file>foo/../bar</file> are
7194           deprecated.
7195         </p>
7196
7197         <p>
7198           Note that when creating a relative link using
7199           <prgn>ln</prgn> it is not necessary for the target of the
7200           link to exist relative to the working directory you're
7201           running <prgn>ln</prgn> from, nor is it necessary to change
7202           directory to the directory where the link is to be made.
7203           Simply include the string that should appear as the target
7204           of the link (this will be a pathname relative to the
7205           directory in which the link resides) as the first argument
7206           to <prgn>ln</prgn>.
7207         </p>
7208
7209         <p>
7210           For example, in your <prgn>Makefile</prgn> or
7211           <file>debian/rules</file>, you can do things like:
7212           <example compact="compact">
7213 ln -fs gcc $(prefix)/bin/cc
7214 ln -fs gcc debian/tmp/usr/bin/cc
7215 ln -fs ../sbin/sendmail $(prefix)/bin/runq
7216 ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
7217           </example>
7218         </p>
7219
7220         <p>
7221           A symbolic link pointing to a compressed file should always
7222           have the same file extension as the referenced file. (For
7223           example, if a file <file>foo.gz</file> is referenced by a
7224           symbolic link, the filename of the link has to end with
7225           "<file>.gz</file>" too, as in <file>bar.gz</file>.)
7226         </p>
7227       </sect>
7228
7229       <sect>
7230         <heading>Device files</heading>
7231
7232         <p>
7233           Packages must not include device files in the package file
7234           tree.
7235         </p>
7236
7237         <p>
7238           If a package needs any special device files that are not
7239           included in the base system, it must call
7240           <prgn>MAKEDEV</prgn> in the <prgn>postinst</prgn> script,
7241           after notifying the user<footnote>
7242               This notification could be done via a (low-priority)
7243               debconf message, or an echo (printf) statement.
7244           </footnote>.
7245         </p>
7246
7247         <p>
7248           Packages must not remove any device files in the
7249           <prgn>postrm</prgn> or any other script. This is left to the
7250           system administrator.
7251         </p>
7252
7253         <p>
7254           Debian uses the serial devices
7255           <file>/dev/ttyS*</file>. Programs using the old
7256           <file>/dev/cu*</file> devices should be changed to use
7257           <file>/dev/ttyS*</file>.
7258         </p>
7259       </sect>
7260
7261       <sect id="config-files">
7262         <heading>Configuration files</heading>
7263
7264         <sect1>
7265           <heading>Definitions</heading>
7266
7267           <p>
7268             <taglist>
7269               <tag>configuration file</tag>
7270               <item>
7271                   A file that affects the operation of a program, or
7272                   provides site- or host-specific information, or
7273                   otherwise customizes the behavior of a program.
7274                   Typically, configuration files are intended to be
7275                   modified by the system administrator (if needed or
7276                   desired) to conform to local policy or to provide
7277                   more useful site-specific behavior.
7278               </item>
7279
7280               <tag><tt>conffile</tt></tag>
7281               <item>
7282                   A file listed in a package's <tt>conffiles</tt>
7283                   file, and is treated specially by <prgn>dpkg</prgn>
7284                   (see <ref id="configdetails">).
7285               </item>
7286             </taglist>
7287           </p>
7288
7289           <p>
7290             The distinction between these two is important; they are
7291             not interchangeable concepts. Almost all
7292             <tt>conffile</tt>s are configuration files, but many
7293             configuration files are not <tt>conffiles</tt>.
7294           </p>
7295
7296           <p>
7297             As noted elsewhere, <file>/etc/init.d</file> scripts,
7298             <file>/etc/default</file> files, scripts installed in
7299             <file>/etc/cron.{hourly,daily,weekly,monthly}</file>, and cron
7300             configuration installed in <file>/etc/cron.d</file> must be
7301             treated as configuration files.  In general, any script that
7302             embeds configuration information is de-facto a configuration
7303             file and should be treated as such.
7304           </p>
7305         </sect1>
7306
7307         <sect1>
7308           <heading>Location</heading>
7309
7310           <p>
7311             Any configuration files created or used by your package
7312             must reside in <file>/etc</file>. If there are several,
7313             consider creating a subdirectory of <file>/etc</file>
7314             named after your package.
7315           </p>
7316
7317           <p>
7318             If your package creates or uses configuration files
7319             outside of <file>/etc</file>, and it is not feasible to modify
7320             the package to use <file>/etc</file> directly, put the files
7321             in <file>/etc</file> and create symbolic links to those files
7322             from the location that the package requires.
7323           </p>
7324         </sect1>
7325
7326         <sect1>
7327           <heading>Behavior</heading>
7328
7329           <p>
7330             Configuration file handling must conform to the following
7331             behavior:
7332             <list compact="compact">
7333               <item>
7334                   local changes must be preserved during a package
7335                   upgrade, and
7336               </item>
7337               <item>
7338                   configuration files must be preserved when the
7339                   package is removed, and only deleted when the
7340                   package is purged.
7341               </item>
7342             </list>
7343           </p>
7344
7345           <p>
7346             The easy way to achieve this behavior is to make the
7347             configuration file a <tt>conffile</tt>. This is
7348             appropriate only if it is possible to distribute a default
7349             version that will work for most installations, although
7350             some system administrators may choose to modify it. This
7351             implies that the default version will be part of the
7352             package distribution, and must not be modified by the
7353             maintainer scripts during installation (or at any other
7354             time).
7355           </p>
7356
7357           <p>
7358             In order to ensure that local changes are preserved
7359             correctly, no package may contain or make hard links to
7360             conffiles.<footnote>
7361                 Rationale: There are two problems with hard links.
7362                 The first is that some editors break the link while
7363                 editing one of the files, so that the two files may
7364                 unwittingly become unlinked and different.  The second
7365                 is that <prgn>dpkg</prgn> might break the hard link
7366                 while upgrading <tt>conffile</tt>s.
7367             </footnote>
7368           </p>
7369
7370           <p>
7371             The other way to do it is via the maintainer scripts.  In
7372             this case, the configuration file must not be listed as a
7373             <tt>conffile</tt> and must not be part of the package
7374             distribution. If the existence of a file is required for
7375             the package to be sensibly configured it is the
7376             responsibility of the package maintainer to provide
7377             maintainer scripts which correctly create, update and
7378             maintain the file and remove it on purge.  (See <ref
7379             id="maintainerscripts"> for more information.)  These
7380             scripts must be idempotent (i.e., must work correctly if
7381             <prgn>dpkg</prgn> needs to re-run them due to errors
7382             during installation or removal), must cope with all the
7383             variety of ways <prgn>dpkg</prgn> can call maintainer
7384             scripts, must not overwrite or otherwise mangle the user's
7385             configuration without asking, must not ask unnecessary
7386             questions (particularly during upgrades), and must
7387             otherwise be good citizens.
7388           </p>
7389
7390           <p>
7391             The scripts are not required to configure every possible
7392             option for the package, but only those necessary to get
7393             the package running on a given system. Ideally the
7394             sysadmin should not have to do any configuration other
7395             than that done (semi-)automatically by the
7396             <prgn>postinst</prgn> script.
7397           </p>
7398
7399           <p>
7400             A common practice is to create a script called
7401             <file><var>package</var>-configure</file> and have the
7402             package's <prgn>postinst</prgn> call it if and only if the
7403             configuration file does not already exist.  In certain
7404             cases it is useful for there to be an example or template
7405             file which the maintainer scripts use.  Such files should
7406             be in <file>/usr/share/<var>package</var></file> or
7407             <file>/usr/lib/<var>package</var></file> (depending on whether
7408             they are architecture-independent or not).  There should
7409             be symbolic links to them from
7410             <file>/usr/share/doc/<var>package</var>/examples</file> if
7411             they are examples, and should be perfectly ordinary
7412             <prgn>dpkg</prgn>-handled files (<em>not</em>
7413             configuration files).
7414           </p>
7415
7416           <p>
7417             These two styles of configuration file handling must
7418             not be mixed, for that way lies madness:
7419             <prgn>dpkg</prgn> will ask about overwriting the file
7420             every time the package is upgraded.
7421           </p>
7422         </sect1>
7423
7424         <sect1>
7425           <heading>Sharing configuration files</heading>
7426
7427           <p>
7428             Packages which specify the same file as a
7429             <tt>conffile</tt> must be tagged as <em>conflicting</em>
7430             with each other.  (This is an instance of the general rule
7431             about not sharing files.  Note that neither alternatives
7432             nor diversions are likely to be appropriate in this case;
7433             in particular, <prgn>dpkg</prgn> does not handle diverted
7434             <tt>conffile</tt>s well.)
7435           </p>
7436
7437           <p>
7438             The maintainer scripts must not alter a <tt>conffile</tt>
7439             of <em>any</em> package, including the one the scripts
7440             belong to.
7441           </p>
7442
7443           <p>
7444             If two or more packages use the same configuration file
7445             and it is reasonable for both to be installed at the same
7446             time, one of these packages must be defined as
7447             <em>owner</em> of the configuration file, i.e., it will be
7448             the package which handles that file as a configuration
7449             file.  Other packages that use the configuration file must
7450             depend on the owning package if they require the
7451             configuration file to operate. If the other package will
7452             use the configuration file if present, but is capable of
7453             operating without it, no dependency need be declared.
7454           </p>
7455
7456           <p>
7457             If it is desirable for two or more related packages to
7458             share a configuration file <em>and</em> for all of the
7459             related packages to be able to modify that configuration
7460             file, then the following should be done:
7461             <enumlist compact="compact">
7462               <item>
7463                   One of the related packages (the "owning" package)
7464                   will manage the configuration file with maintainer
7465                   scripts as described in the previous section.
7466               </item>
7467               <item>
7468                   The owning package should also provide a program
7469                   that the other packages may use to modify the
7470                   configuration file.
7471               </item>
7472               <item>
7473                   The related packages must use the provided program
7474                   to make any desired modifications to the
7475                   configuration file.  They should either depend on
7476                   the core package to guarantee that the configuration
7477                   modifier program is available or accept gracefully
7478                   that they cannot modify the configuration file if it
7479                   is not.  (This is in addition to the fact that the
7480                   configuration file may not even be present in the
7481                   latter scenario.)
7482               </item>
7483             </enumlist>
7484           </p>
7485
7486           <p>
7487             Sometimes it's appropriate to create a new package which
7488             provides the basic infrastructure for the other packages
7489             and which manages the shared configuration files.  (The
7490             <tt>sgml-base</tt> package is a good example.)
7491           </p>
7492         </sect1>
7493
7494         <sect1>
7495           <heading>User configuration files ("dotfiles")</heading>
7496
7497           <p>
7498             The files in <file>/etc/skel</file> will automatically be
7499             copied into new user accounts by <prgn>adduser</prgn>.
7500             No other program should reference the files in
7501             <file>/etc/skel</file>.
7502           </p>
7503
7504           <p>
7505             Therefore, if a program needs a dotfile to exist in
7506             advance in <file>$HOME</file> to work sensibly, that dotfile
7507             should be installed in <file>/etc/skel</file> and treated as a
7508             configuration file.
7509           </p>
7510
7511           <p>
7512             However, programs that require dotfiles in order to
7513             operate sensibly are a bad thing, unless they do create
7514             the dotfiles themselves automatically.
7515           </p>
7516
7517           <p>
7518             Furthermore, programs should be configured by the Debian
7519             default installation to behave as closely to the upstream
7520             default behavior as possible.
7521           </p>
7522
7523           <p>
7524             Therefore, if a program in a Debian package needs to be
7525             configured in some way in order to operate sensibly, that
7526             should be done using a site-wide configuration file placed
7527             in <file>/etc</file>.  Only if the program doesn't support a
7528             site-wide default configuration and the package maintainer
7529             doesn't have time to add it may a default per-user file be
7530             placed in <file>/etc/skel</file>.
7531           </p>
7532
7533           <p>
7534             <file>/etc/skel</file> should be as empty as we can make it.
7535             This is particularly true because there is no easy (or
7536             necessarily desirable) mechanism for ensuring that the
7537             appropriate dotfiles are copied into the accounts of
7538             existing users when a package is installed.
7539           </p>
7540         </sect1>
7541       </sect>
7542
7543       <sect>
7544         <heading>Log files</heading>
7545         <p>
7546           Log files should usually be named
7547           <file>/var/log/<var>package</var>.log</file>.  If you have many
7548           log files, or need a separate directory for permission
7549           reasons (<file>/var/log</file> is writable only by
7550           <file>root</file>), you should usually create a directory named
7551           <file>/var/log/<var>package</var></file> and place your log
7552           files there.
7553         </p>
7554
7555         <p>
7556           Log files must be rotated occasionally so that they don't
7557           grow indefinitely; the best way to do this is to drop a log
7558           rotation configuration file into the directory
7559           <file>/etc/logrotate.d</file> and use the facilities provided by
7560           logrotate.<footnote>
7561             <p>
7562               The traditional approach to log files has been to set up
7563               <em>ad hoc</em> log rotation schemes using simple shell
7564               scripts and cron.  While this approach is highly
7565               customizable, it requires quite a lot of sysadmin work.
7566               Even though the original Debian system helped a little
7567               by automatically installing a system which can be used
7568               as a template, this was deemed not enough.
7569             </p>
7570
7571             <p>
7572               The use of <prgn>logrotate</prgn>, a program developed
7573               by Red Hat, is better, as it centralizes log management.
7574               It has both a configuration file
7575               (<file>/etc/logrotate.conf</file>) and a directory where
7576               packages can drop their individual log rotation
7577               configurations (<file>/etc/logrotate.d</file>).
7578             </p>
7579           </footnote>
7580           Here is a good example for a logrotate config
7581           file (for more information see <manref name="logrotate"
7582             section="8">):
7583           <example compact="compact">
7584 /var/log/foo/*.log {
7585 rotate 12
7586 weekly
7587 compress
7588 postrotate
7589 /etc/init.d/foo force-reload
7590 endscript
7591 }
7592           </example>
7593           This rotates all files under <file>/var/log/foo</file>, saves 12
7594           compressed generations, and forces the daemon to reload its
7595           configuration information after the log rotation.
7596         </p>
7597
7598         <p>
7599           Log files should be removed when the package is
7600           purged (but not when it is only removed).  This should be
7601           done by the <prgn>postrm</prgn> script when it is called
7602           with the argument <tt>purge</tt> (see <ref
7603           id="removedetails">).
7604         </p>
7605       </sect>
7606
7607       <sect>
7608         <heading>Permissions and owners</heading>
7609
7610         <p>
7611           The rules in this section are guidelines for general use.
7612           If necessary you may deviate from the details below.
7613           However, if you do so you must make sure that what is done
7614           is secure and you should try to be as consistent as possible
7615           with the rest of the system.  You should probably also
7616           discuss it on <prgn>debian-devel</prgn> first.
7617         </p>
7618
7619         <p>
7620           Files should be owned by <tt>root:root</tt>, and made
7621           writable only by the owner and universally readable (and
7622           executable, if appropriate), that is mode 644 or 755.
7623         </p>
7624
7625         <p>
7626           Directories should be mode 755 or (for group-writability)
7627           mode 2775.  The ownership of the directory should be
7628           consistent with its mode: if a directory is mode 2775, it
7629           should be owned by the group that needs write access to
7630           it.<footnote>
7631             <p>
7632               When a package is upgraded, and the owner or permissions
7633               of a file included in the package has changed, dpkg
7634               arranges for the ownership and permissions to be
7635               correctly set upon installation. However, this does not
7636               extend to directories; the permissions and ownership of
7637               directories already on the system does not change on
7638               install or upgrade of packages.  This makes sense, since
7639               otherwise common directories like <tt>/usr</tt> would
7640               always be in flux.  To correctly change permissions of a
7641               directory the package owns, explicit action is required,
7642               usually in the <tt>postinst</tt> script. Care must be
7643               taken to handle downgrades as well, in that case.
7644             </p>
7645           </footnote>
7646         </p>
7647
7648
7649         <p>
7650           Setuid and setgid executables should be mode 4755 or 2755
7651           respectively, and owned by the appropriate user or group.
7652           They should not be made unreadable (modes like 4711 or
7653           2711 or even 4111); doing so achieves no extra security,
7654           because anyone can find the binary in the freely available
7655           Debian package; it is merely inconvenient.  For the same
7656           reason you should not restrict read or execute permissions
7657           on non-set-id executables.
7658         </p>
7659
7660         <p>
7661           Some setuid programs need to be restricted to particular
7662           sets of users, using file permissions.  In this case they
7663           should be owned by the uid to which they are set-id, and by
7664           the group which should be allowed to execute them.  They
7665           should have mode 4754; again there is no point in making
7666           them unreadable to those users who must not be allowed to
7667           execute them.
7668         </p>
7669
7670         <p>
7671           It is possible to arrange that the system administrator can
7672           reconfigure the package to correspond to their local
7673           security policy by changing the permissions on a binary:
7674           they can do this by using <prgn>dpkg-statoverride</prgn>, as
7675           described below.<footnote>
7676               Ordinary files installed by <prgn>dpkg</prgn> (as
7677               opposed to <tt>conffile</tt>s and other similar objects)
7678               normally have their permissions reset to the distributed
7679               permissions when the package is reinstalled.  However,
7680               the use of <prgn>dpkg-statoverride</prgn> overrides this
7681               default behavior.  If you use this method, you should
7682               remember to describe <prgn>dpkg-statoverride</prgn> in
7683               the package documentation; being a relatively new
7684               addition to Debian, it is probably not yet well-known.
7685           </footnote>
7686           Another method you should consider is to create a group for
7687           people allowed to use the program(s) and make any setuid
7688           executables executable only by that group.
7689         </p>
7690
7691         <p>
7692           If you need to create a new user or group for your package
7693           there are two possibilities.  Firstly, you may need to
7694           make some files in the binary package be owned by this
7695           user or group, or you may need to compile the user or
7696           group id (rather than just the name) into the binary
7697           (though this latter should be avoided if possible, as in
7698           this case you need a statically allocated id).</p>
7699
7700         <p>
7701           If you need a statically allocated id, you must ask for a
7702           user or group id from the <tt>base-passwd</tt> maintainer,
7703           and must not release the package until you have been
7704           allocated one.  Once you have been allocated one you must
7705           either make the package depend on a version of the
7706           <tt>base-passwd</tt> package with the id present in
7707           <file>/etc/passwd</file> or <file>/etc/group</file>, or arrange for
7708           your package to create the user or group itself with the
7709           correct id (using <tt>adduser</tt>) in its
7710           <prgn>preinst</prgn> or <prgn>postinst</prgn>.  (Doing it in
7711           the <prgn>postinst</prgn> is to be preferred if it is
7712           possible, otherwise a pre-dependency will be needed on the
7713           <tt>adduser</tt> package.)
7714         </p>
7715
7716         <p>
7717           On the other hand, the program might be able to determine
7718           the uid or gid from the user or group name at runtime, so
7719           that a dynamically allocated id can be used.  In this case
7720           you should choose an appropriate user or group name,
7721           discussing this on <prgn>debian-devel</prgn> and checking
7722           with the <package/base-passwd/ maintainer that it is unique and that
7723           they do not wish you to use a statically allocated id
7724           instead.  When this has been checked you must arrange for
7725           your package to create the user or group if necessary using
7726           <prgn>adduser</prgn> in the <prgn>preinst</prgn> or
7727           <prgn>postinst</prgn> script (again, the latter is to be
7728           preferred if it is possible).
7729         </p>
7730
7731         <p>
7732           Note that changing the numeric value of an id associated
7733           with a name is very difficult, and involves searching the
7734           file system for all appropriate files.  You need to think
7735           carefully whether a static or dynamic id is required, since
7736           changing your mind later will cause problems.
7737         </p>
7738
7739         <sect1><heading>The use of <prgn>dpkg-statoverride</prgn></heading>
7740           <p>
7741             This section is not intended as policy, but as a
7742             description of the use of <prgn>dpkg-statoverride</prgn>.
7743           </p>
7744
7745           <p>
7746             If a system administrator wishes to have a file (or
7747             directory or other such thing) installed with owner and
7748             permissions different from those in the distributed Debian
7749             package, they can use the <prgn>dpkg-statoverride</prgn>
7750             program to instruct <prgn>dpkg</prgn> to use the different
7751             settings every time the file is installed.  Thus the
7752             package maintainer should distribute the files with their
7753             normal permissions, and leave it for the system
7754             administrator to make any desired changes.  For example, a
7755             daemon which is normally required to be setuid root, but
7756             in certain situations could be used without being setuid,
7757             should be installed setuid in the <tt>.deb</tt>.  Then the
7758             local system administrator can change this if they wish.
7759             If there are two standard ways of doing it, the package
7760             maintainer can use <tt>debconf</tt> to find out the
7761             preference, and call <prgn>dpkg-statoverride</prgn> in the
7762             maintainer script if necessary to accommodate the system
7763             administrator's choice. Care must be taken during
7764             upgrades to not override an existing setting.
7765           </p>
7766
7767           <p>
7768             Given the above, <prgn>dpkg-statoverride</prgn> is
7769             essentially a tool for system administrators and would not
7770             normally be needed in the maintainer scripts.  There is
7771             one type of situation, though, where calls to
7772             <prgn>dpkg-statoverride</prgn> would be needed in the
7773             maintainer scripts, and that involves packages which use
7774             dynamically allocated user or group ids.  In such a
7775             situation, something like the following idiom can be very
7776             helpful in the package's <prgn>postinst</prgn>, where
7777             <tt>sysuser</tt> is a dynamically allocated id:
7778             <example>
7779 for i in /usr/bin/foo /usr/sbin/bar
7780 do
7781   # only do something when no setting exists
7782   if ! dpkg-statoverride --list $i >/dev/null 2>&1
7783   then
7784     #include: debconf processing, question about foo and bar
7785     if [ "$RET" = "true" ] ; then
7786       dpkg-statoverride --update --add sysuser root 4755 $i
7787     fi
7788   fi
7789 done
7790             </example>
7791             The corresponding code to remove the override when the package
7792             is purged would be:
7793             <example>
7794 for i in /usr/bin/foo /usr/sbin/bar
7795 do
7796   if dpkg-statoverride --list $i >/dev/null 2>&1
7797   then
7798     dpkg-statoverride --remove $i
7799   fi
7800 done
7801             </example>
7802           </p>
7803         </sect1>
7804       </sect>
7805     </chapt>
7806
7807
7808     <chapt id="customized-programs">
7809       <heading>Customized programs</heading>
7810
7811       <sect id="arch-spec">
7812         <heading>Architecture specification strings</heading>
7813
7814         <p>
7815           If a program needs to specify an <em>architecture specification
7816             string</em> in some place, it should select one of the
7817           strings provided by <tt>dpkg-architecture -L</tt>. The
7818           strings are in the format
7819           <tt><var>os</var>-<var>arch</var></tt>, though the OS part
7820           is sometimes elided, as when the OS is Linux.<footnote>
7821             <p>Currently, the strings are:
7822               i386 ia64 alpha amd64 armeb arm hppa m32r m68k mips
7823               mipsel powerpc ppc64 s390 s390x sh3 sh3eb sh4 sh4eb
7824               sparc darwin-i386 darwin-ia64 darwin-alpha darwin-amd64
7825               darwin-armeb darwin-arm darwin-hppa darwin-m32r
7826               darwin-m68k darwin-mips darwin-mipsel darwin-powerpc
7827               darwin-ppc64 darwin-s390 darwin-s390x darwin-sh3
7828               darwin-sh3eb darwin-sh4 darwin-sh4eb darwin-sparc
7829               freebsd-i386 freebsd-ia64 freebsd-alpha freebsd-amd64
7830               freebsd-armeb freebsd-arm freebsd-hppa freebsd-m32r
7831               freebsd-m68k freebsd-mips freebsd-mipsel freebsd-powerpc
7832               freebsd-ppc64 freebsd-s390 freebsd-s390x freebsd-sh3
7833               freebsd-sh3eb freebsd-sh4 freebsd-sh4eb freebsd-sparc
7834               kfreebsd-i386 kfreebsd-ia64 kfreebsd-alpha
7835               kfreebsd-amd64 kfreebsd-armeb kfreebsd-arm kfreebsd-hppa
7836               kfreebsd-m32r kfreebsd-m68k kfreebsd-mips
7837               kfreebsd-mipsel kfreebsd-powerpc kfreebsd-ppc64
7838               kfreebsd-s390 kfreebsd-s390x kfreebsd-sh3 kfreebsd-sh3eb
7839               kfreebsd-sh4 kfreebsd-sh4eb kfreebsd-sparc knetbsd-i386
7840               knetbsd-ia64 knetbsd-alpha knetbsd-amd64 knetbsd-armeb
7841               knetbsd-arm knetbsd-hppa knetbsd-m32r knetbsd-m68k
7842               knetbsd-mips knetbsd-mipsel knetbsd-powerpc
7843               knetbsd-ppc64 knetbsd-s390 knetbsd-s390x knetbsd-sh3
7844               knetbsd-sh3eb knetbsd-sh4 knetbsd-sh4eb knetbsd-sparc
7845               netbsd-i386 netbsd-ia64 netbsd-alpha netbsd-amd64
7846               netbsd-armeb netbsd-arm netbsd-hppa netbsd-m32r
7847               netbsd-m68k netbsd-mips netbsd-mipsel netbsd-powerpc
7848               netbsd-ppc64 netbsd-s390 netbsd-s390x netbsd-sh3
7849               netbsd-sh3eb netbsd-sh4 netbsd-sh4eb netbsd-sparc
7850               openbsd-i386 openbsd-ia64 openbsd-alpha openbsd-amd64
7851               openbsd-armeb openbsd-arm openbsd-hppa openbsd-m32r
7852               openbsd-m68k openbsd-mips openbsd-mipsel openbsd-powerpc
7853               openbsd-ppc64 openbsd-s390 openbsd-s390x openbsd-sh3
7854               openbsd-sh3eb openbsd-sh4 openbsd-sh4eb openbsd-sparc
7855               hurd-i386 hurd-ia64 hurd-alpha hurd-amd64 hurd-armeb
7856               hurd-arm hurd-hppa hurd-m32r hurd-m68k hurd-mips
7857               hurd-mipsel hurd-powerpc hurd-ppc64 hurd-s390 hurd-s390x
7858               hurd-sh3 hurd-sh3eb hurd-sh4 hurd-sh4eb hurd-sparc
7859             </p>
7860           </footnote>
7861         </p>
7862
7863         <p>
7864           Note that we don't want to use
7865           <tt><var>arch</var>-debian-linux</tt> to apply to the rule
7866           <tt><var>architecture</var>-<var>vendor</var>-<var>os</var></tt>
7867           since this would make our programs incompatible with other
7868           Linux distributions.  We also don't use something like
7869           <tt><var>arch</var>-unknown-linux</tt>, since the
7870           <tt>unknown</tt> does not look very good.
7871         </p>
7872       </sect>
7873
7874       <sect>
7875         <heading>Daemons</heading>
7876
7877         <p>
7878           The configuration files <file>/etc/services</file>,
7879           <file>/etc/protocols</file>, and <file>/etc/rpc</file> are managed
7880           by the <prgn>netbase</prgn> package and must not be modified
7881           by other packages.
7882         </p>
7883
7884         <p>
7885           If a package requires a new entry in one of these files, the
7886           maintainer should get in contact with the
7887           <prgn>netbase</prgn> maintainer, who will add the entries
7888           and release a new version of the <prgn>netbase</prgn>
7889           package.
7890         </p>
7891
7892         <p>
7893           The configuration file <file>/etc/inetd.conf</file> must not be
7894           modified by the package's scripts except via the
7895           <prgn>update-inetd</prgn> script or the
7896           <file>DebianNet.pm</file> Perl module.  See their documentation
7897           for details on how to add entries.
7898         </p>
7899
7900         <p>
7901           If a package wants to install an example entry into
7902           <file>/etc/inetd.conf</file>, the entry must be preceded with
7903           exactly one hash character (<tt>#</tt>). Such lines are
7904           treated as "commented out by user" by the
7905           <prgn>update-inetd</prgn> script and are not changed or
7906           activated during package updates.
7907         </p>
7908       </sect>
7909
7910       <sect>
7911         <heading>Using pseudo-ttys and modifying wtmp, utmp and
7912         lastlog</heading>
7913
7914         <p>
7915           Some programs need to create pseudo-ttys. This should be done
7916           using Unix98 ptys if the C library supports it. The resulting
7917           program must not be installed setuid root, unless that
7918           is required for other functionality.
7919         </p>
7920
7921         <p>
7922           The files <file>/var/run/utmp</file>, <file>/var/log/wtmp</file> and
7923           <file>/var/log/lastlog</file> must be installed writable by
7924           group <tt>utmp</tt>.  Programs which need to modify those
7925           files must be installed setgid <tt>utmp</tt>.
7926         </p>
7927       </sect>
7928
7929       <sect>
7930         <heading>Editors and pagers</heading>
7931
7932         <p>
7933           Some programs have the ability to launch an editor or pager
7934           program to edit or display a text document.  Since there are
7935           lots of different editors and pagers available in the Debian
7936           distribution, the system administrator and each user should
7937           have the possibility to choose their preferred editor and
7938           pager.
7939         </p>
7940
7941         <p>
7942           In addition, every program should choose a good default
7943           editor/pager if none is selected by the user or system
7944           administrator.
7945         </p>
7946
7947         <p>
7948           Thus, every program that launches an editor or pager must
7949           use the EDITOR or PAGER environment variable to determine
7950           the editor or pager the user wishes to use.  If these
7951           variables are not set, the programs <file>/usr/bin/editor</file>
7952           and <file>/usr/bin/pager</file> should be used, respectively.
7953         </p>
7954
7955         <p>
7956           These two files are managed through the <prgn>dpkg</prgn>
7957           "alternatives" mechanism.  Thus every package providing an
7958           editor or pager must call the
7959           <prgn>update-alternatives</prgn> script to register these
7960           programs.
7961         </p>
7962
7963         <p>
7964           If it is very hard to adapt a program to make use of the
7965           EDITOR or PAGER variables, that program may be configured to
7966           use <file>/usr/bin/sensible-editor</file> and
7967           <file>/usr/bin/sensible-pager</file> as the editor or pager
7968           program respectively.  These are two scripts provided in the
7969           <package>sensible-utils</package> package that check the EDITOR
7970           and PAGER variables and launch the appropriate program, and fall
7971           back to <file>/usr/bin/editor</file>
7972           and <file>/usr/bin/pager</file> if the variable is not set.
7973         </p>
7974
7975         <p>
7976           A program may also use the VISUAL environment variable to
7977           determine the user's choice of editor.  If it exists, it
7978           should take precedence over EDITOR.  This is in fact what
7979           <file>/usr/bin/sensible-editor</file> does.
7980         </p>
7981
7982         <p>
7983           It is not required for a package to depend on
7984           <tt>editor</tt> and <tt>pager</tt>, nor is it required for a
7985           package to provide such virtual packages.<footnote>
7986               The Debian base system already provides an editor and a
7987               pager program.
7988           </footnote>
7989         </p>
7990       </sect>
7991
7992       <sect id="web-appl">
7993         <heading>Web servers and applications</heading>
7994
7995         <p>
7996           This section describes the locations and URLs that should
7997           be used by all web servers and web applications in the
7998           Debian system.
7999         </p>
8000
8001         <p>
8002           <enumlist>
8003             <item>
8004                 Cgi-bin executable files are installed in the
8005                 directory
8006                 <example compact="compact">
8007 /usr/lib/cgi-bin/<var>cgi-bin-name</var>
8008                 </example>
8009                 and should be referred to as
8010                 <example compact="compact">
8011 http://localhost/cgi-bin/<var>cgi-bin-name</var>
8012                 </example>
8013
8014             </item>
8015
8016             <item>
8017               <p>Access to HTML documents</p>
8018
8019               <p>
8020                 HTML documents for a package are stored in
8021                 <file>/usr/share/doc/<var>package</var></file>
8022                 and can be referred to as
8023                 <example compact="compact">
8024 http://localhost/doc/<var>package</var>/<var>filename</var>
8025                 </example>
8026               </p>
8027
8028               <p>
8029                 The web server should restrict access to the document
8030                 tree so that only clients on the same host can read
8031                 the documents. If the web server does not support such
8032                 access controls, then it should not provide access at
8033                 all, or ask about providing access during installation.
8034               </p>
8035             </item>
8036
8037             <item>
8038               <p>Access to images</p>
8039               <p>
8040                 It is recommended that images for a package be stored
8041                 in <tt>/usr/share/images/<var>package</var></tt> and
8042                 may be referred to through an alias <tt>/images/</tt>
8043                 as
8044                 <example>
8045                   http://localhost/images/&lt;package&gt;/&lt;filename&gt;     
8046                 </example>
8047                 
8048               </p>
8049             </item>
8050
8051             <item>
8052               <p>Web Document Root</p>
8053
8054               <p>
8055                 Web Applications should try to avoid storing files in
8056                 the Web Document Root.  Instead they should use the
8057                 /usr/share/doc/<var>package</var> directory for
8058                 documents and register the Web Application via the
8059                 <package>doc-base</package> package.  If access to the
8060                 web document root is unavoidable then use
8061                 <example compact="compact">
8062 /var/www
8063                 </example>
8064                 as the Document Root.  This might be just a symbolic
8065                 link to the location where the system administrator
8066                 has put the real document root.
8067               </p>
8068             </item>
8069             <item><p>Providing httpd and/or httpd-cgi</p>
8070               <p>
8071                 All web servers should provide the virtual package
8072                 <tt>httpd</tt>. If a web server has CGI support it should
8073                 provide <tt>httpd-cgi</tt> additionally.
8074               </p>
8075               <p>
8076                 All web applications which do not contain CGI scripts should
8077                 depend on <tt>httpd</tt>, all those web applications which
8078                 <tt>do</tt> contain CGI scripts, should depend on
8079                 <tt>httpd-cgi</tt>.
8080               </p>
8081             </item>
8082           </enumlist>
8083         </p>
8084       </sect>
8085
8086       <sect id="mail-transport-agents">
8087         <heading>Mail transport, delivery and user agents</heading>
8088
8089         <p>
8090           Debian packages which process electronic mail, whether mail
8091           user agents (MUAs) or mail transport agents (MTAs), must
8092           ensure that they are compatible with the configuration
8093           decisions below.  Failure to do this may result in lost
8094           mail, broken <tt>From:</tt> lines, and other serious brain
8095           damage!
8096         </p>
8097
8098         <p>
8099           The mail spool is <file>/var/mail</file> and the interface to
8100           send a mail message is <file>/usr/sbin/sendmail</file> (as per
8101           the FHS).  On older systems, the mail spool may be
8102           physically located in <file>/var/spool/mail</file>, but all
8103           access to the mail spool should be via the
8104           <file>/var/mail</file> symlink.  The mail spool is part of the
8105           base system and not part of the MTA package.
8106         </p>
8107
8108         <p>
8109           All Debian MUAs, MTAs, MDAs and other mailbox accessing
8110           programs (such as IMAP daemons) must lock the mailbox in an
8111           NFS-safe way. This means that <tt>fcntl()</tt> locking must
8112           be combined with dot locking.  To avoid deadlocks, a program
8113           should use <tt>fcntl()</tt> first and dot locking after
8114           this, or alternatively implement the two locking methods in
8115           a non blocking way<footnote>
8116               If it is not possible to establish both locks, the
8117               system shouldn't wait for the second lock to be
8118               established, but remove the first lock, wait a (random)
8119               time, and start over locking again.
8120           </footnote>. Using the functions <tt>maillock</tt> and
8121           <tt>mailunlock</tt> provided by the
8122           <tt>liblockfile*</tt><footnote>
8123               You will need to depend on <tt>liblockfile1 (&gt;&gt;1.01)</tt>
8124               to use these functions.
8125           </footnote> packages is the recommended way to realize this.
8126         </p>
8127
8128         <p>
8129           Mailboxes are generally either mode 600 and owned by
8130           <var>user</var> or mode 660 and owned by
8131           <tt><var>user</var>:mail</tt><footnote>
8132             There are two traditional permission schemes for mail spools:
8133             mode 600 with all mail delivery done by processes running as
8134             the destination user, or mode 660 and owned by group mail with
8135             mail delivery done by a process running as a system user in
8136             group mail.  Historically, Debian required mode 660 mail
8137             spools to enable the latter model, but that model has become
8138             increasingly uncommon and the principle of least privilege
8139             indicates that mail systems that use the first model should
8140             use permissions of 600.  If delivery to programs is permitted,
8141             it's easier to keep the mail system secure if the delivery
8142             agent runs as the destination user.  Debian Policy therefore
8143             permits either scheme.
8144           </footnote>. The local system administrator may choose a
8145           different permission scheme; packages should not make
8146           assumptions about the permission and ownership of mailboxes
8147           unless required (such as when creating a new mailbox).  A MUA
8148           may remove a mailbox (unless it has nonstandard permissions) in
8149           which case the MTA or another MUA must recreate it if needed.
8150         </p>
8151
8152         <p>
8153           The mail spool is 2775 <tt>root:mail</tt>, and MUAs should
8154           be setgid mail to do the locking mentioned above (and
8155           must obviously avoid accessing other users' mailboxes
8156           using this privilege).</p>
8157
8158         <p>
8159           <file>/etc/aliases</file> is the source file for the system mail
8160           aliases (e.g., postmaster, usenet, etc.), it is the one
8161           which the sysadmin and <prgn>postinst</prgn> scripts may
8162           edit.  After <file>/etc/aliases</file> is edited the program or
8163           human editing it must call <prgn>newaliases</prgn>.  All MTA
8164           packages must come with a <prgn>newaliases</prgn> program,
8165           even if it does nothing, but older MTA packages did not do
8166           this so programs should not fail if <prgn>newaliases</prgn>
8167           cannot be found.  Note that because of this, all MTA
8168           packages must have <tt>Provides</tt>, <tt>Conflicts</tt> and
8169           <tt>Replaces: mail-transport-agent</tt> control file
8170           fields.
8171         </p>
8172
8173         <p>
8174           The convention of writing <tt>forward to
8175             <var>address</var></tt> in the mailbox itself is not
8176           supported.  Use a <tt>.forward</tt> file instead.</p>
8177
8178         <p>
8179           The <prgn>rmail</prgn> program used by UUCP
8180           for incoming mail should be  <file>/usr/sbin/rmail</file>.
8181           Likewise, <prgn>rsmtp</prgn>, for receiving
8182           batch-SMTP-over-UUCP, should be <file>/usr/sbin/rsmtp</file> if it
8183           is supported.</p>
8184
8185         <p>
8186           If your package needs to know what hostname to use on (for
8187           example) outgoing news and mail messages which are generated
8188           locally, you should use the file <file>/etc/mailname</file>.  It
8189           will contain the portion after the username and <tt>@</tt>
8190           (at) sign for email addresses of users on the machine
8191           (followed by a newline).
8192         </p>
8193
8194         <p>
8195           Such a package should check for the existence of this file
8196           when it is being configured.  If it exists, it should be
8197           used without comment, although an MTA's configuration script
8198           may wish to prompt the user even if it finds that this file
8199           exists.  If the file does not exist, the package should
8200           prompt the user for the value (preferably using
8201           <prgn>debconf</prgn>) and store it in <file>/etc/mailname</file>
8202           as well as using it in the package's configuration.  The
8203           prompt should make it clear that the name will not just be
8204           used by that package.  For example, in this situation the
8205           <tt>inn</tt> package could say something like:
8206           <example compact="compact">
8207 Please enter the "mail name" of your system.  This is the
8208 hostname portion of the address to be shown on outgoing
8209 news and mail messages.  The default is
8210 <var>syshostname</var>, your system's host name.  Mail
8211 name ["<var>syshostname</var>"]:
8212           </example>
8213           where <var>syshostname</var> is the output of <tt>hostname
8214             --fqdn</tt>.
8215         </p>
8216       </sect>
8217
8218       <sect>
8219         <heading>News system configuration</heading>
8220
8221         <p>
8222           All the configuration files related to the NNTP (news)
8223           servers and clients should be located under
8224           <file>/etc/news</file>.</p>
8225
8226         <p>
8227           There are some configuration issues that apply to a number
8228           of news clients and server packages on the machine. These
8229           are:
8230
8231           <taglist>
8232             <tag><file>/etc/news/organization</file></tag>
8233             <item>
8234                 A string which should appear as the
8235                 organization header for all messages posted
8236                 by NNTP clients on the machine
8237             </item>
8238
8239             <tag><file>/etc/news/server</file></tag>
8240             <item>
8241                 Contains the FQDN of the upstream NNTP
8242                 server, or localhost if the local machine is
8243                 an NNTP server.
8244             </item>
8245           </taglist>
8246
8247           Other global files may be added as required for cross-package news
8248           configuration.
8249         </p>
8250       </sect>
8251
8252
8253       <sect>
8254         <heading>Programs for the X Window System</heading>
8255
8256         <sect1>
8257           <heading>Providing X support and package priorities</heading>
8258
8259           <p>
8260             Programs that can be configured with support for the X
8261             Window System must be configured to do so and must declare
8262             any package dependencies necessary to satisfy their
8263             runtime requirements when using the X Window System.  If
8264             such a package is of higher priority than the X packages
8265             on which it depends, it is required that either the
8266             X-specific components be split into a separate package, or
8267             that an alternative version of the package, which includes
8268             X support, be provided, or that the package's priority be
8269             lowered.
8270           </p>
8271         </sect1>
8272
8273         <sect1>
8274           <heading>Packages providing an X server</heading>
8275
8276           <p>
8277             Packages that provide an X server that, directly or
8278             indirectly, communicates with real input and display
8279             hardware should declare in their control data that they
8280             provide the virtual package <tt>xserver</tt>.<footnote>
8281                 This implements current practice, and provides an
8282                 actual policy for usage of the <tt>xserver</tt>
8283                 virtual package which appears in the virtual packages
8284                 list.  In a nutshell, X servers that interface
8285                 directly with the display and input hardware or via
8286                 another subsystem (e.g., GGI) should provide
8287                 <tt>xserver</tt>.  Things like <tt>Xvfb</tt>,
8288                 <tt>Xnest</tt>, and <tt>Xprt</tt> should not.
8289             </footnote>
8290           </p>
8291         </sect1>
8292
8293         <sect1>
8294           <heading>Packages providing a terminal emulator</heading>
8295
8296           <p>
8297             Packages that provide a terminal emulator for the X Window
8298             System which meet the criteria listed below should declare
8299             in their control data that they provide the virtual
8300             package <tt>x-terminal-emulator</tt>.  They should also
8301             register themselves as an alternative for
8302             <file>/usr/bin/x-terminal-emulator</file>, with a priority of
8303             20.
8304           </p>
8305
8306           <p>
8307             To be an <tt>x-terminal-emulator</tt>, a program must:
8308             <list compact="compact">
8309               <item>
8310                   Be able to emulate a DEC VT100 terminal, or a
8311                   compatible terminal.
8312               </item>
8313
8314               <item>
8315                   Support the command-line option <tt>-e
8316                     <var>command</var></tt>, which creates a new
8317                   terminal window<footnote>
8318                       "New terminal window" does not necessarily mean
8319                       a new top-level X window directly parented by
8320                       the window manager; it could, if the terminal
8321                       emulator application were so coded, be a new
8322                       "view" in a multiple-document interface (MDI).
8323                   </footnote>
8324                   and runs the specified <var>command</var>,
8325                   interpreting the entirety of the rest of the command
8326                   line as a command to pass straight to exec, in the
8327                   manner that <tt>xterm</tt> does.
8328               </item>
8329
8330               <item>
8331                   Support the command-line option <tt>-T
8332                     <var>title</var></tt>, which creates a new terminal
8333                   window with the window title <var>title</var>.
8334               </item>
8335             </list>
8336           </p>
8337         </sect1>
8338
8339         <sect1>
8340           <heading>Packages providing a window manager</heading>
8341
8342           <p>
8343             Packages that provide a window manager should declare in
8344             their control data that they provide the virtual package
8345             <tt>x-window-manager</tt>.  They should also register
8346             themselves as an alternative for
8347             <file>/usr/bin/x-window-manager</file>, with a priority
8348             calculated as follows:
8349             <list compact="compact">
8350               <item>
8351                   Start with a priority of 20.
8352               </item>
8353
8354               <item>
8355                   If the window manager supports the Debian menu
8356                   system, add 20 points if this support is available
8357                   in the package's default configuration (i.e., no
8358                   configuration files belonging to the system or user
8359                   have to be edited to activate the feature); if
8360                   configuration files must be modified, add only 10
8361                   points.
8362                 </p>
8363               </item>
8364
8365               <item>
8366                   If the window manager complies with <url
8367                     id="http://www.freedesktop.org/Standards/wm-spec"
8368                     name="The Window Manager Specification Project">,
8369                   written by the <url id="http://www.freedesktop.org/"
8370                     name="Free Desktop Group">, add 40 points.
8371               </item>
8372
8373               <item>
8374                   If the window manager permits the X session to be
8375                   restarted using a <em>different</em> window manager
8376                   (without killing the X server) in its default
8377                   configuration, add 10 points; otherwise add none.
8378               </item>
8379             </list>
8380           </p>
8381         </sect1>
8382
8383         <sect1>
8384           <heading>Packages providing fonts</heading>
8385
8386           <p>
8387             Packages that provide fonts for the X Window
8388             System<footnote>
8389                 For the purposes of Debian Policy, a "font for the X
8390                 Window System" is one which is accessed via X protocol
8391                 requests.  Fonts for the Linux console, for PostScript
8392                 renderer, or any other purpose, do not fit this
8393                 definition.  Any tool which makes such fonts available
8394                 to the X Window System, however, must abide by this
8395                 font policy.
8396             </footnote>
8397             must do a number of things to ensure that they are both
8398             available without modification of the X or font server
8399             configuration, and that they do not corrupt files used by
8400             other font packages to register information about
8401             themselves.
8402             <enumlist>
8403               <item>
8404                   Fonts of any type supported by the X Window System
8405                   must be in a separate binary package from any
8406                   executables, libraries, or documentation (except
8407                   that specific to the fonts shipped, such as their
8408                   license information).  If one or more of the fonts
8409                   so packaged are necessary for proper operation of
8410                   the package with which they are associated the font
8411                   package may be Recommended; if the fonts merely
8412                   provide an enhancement, a Suggests relationship may
8413                   be used.  Packages must not Depend on font
8414                   packages.<footnote>
8415                       This is because the X server may retrieve fonts
8416                       from the local file system or over the network
8417                       from an X font server; the Debian package system
8418                       is empowered to deal only with the local
8419                       file system.
8420                   </footnote>
8421               </item>
8422
8423               <item>
8424                   BDF fonts must be converted to PCF fonts with the
8425                   <prgn>bdftopcf</prgn> utility (available in the
8426                   <tt>xfonts-utils</tt> package, <prgn>gzip</prgn>ped, and
8427                   placed in a directory that corresponds to their
8428                   resolution:
8429                   <list compact="compact">
8430                     <item>
8431                         100 dpi fonts must be placed in
8432                         <file>/usr/share/fonts/X11/100dpi/</file>.
8433                     </item>
8434
8435                     <item>
8436                         75 dpi fonts must be placed in
8437                         <file>/usr/share/fonts/X11/75dpi/</file>.
8438                     </item>
8439
8440                     <item>
8441                         Character-cell fonts, cursor fonts, and other
8442                         low-resolution fonts must be placed in
8443                         <file>/usr/share/fonts/X11/misc/</file>.
8444                     </item>
8445                   </list>
8446               </item>
8447
8448               <item>
8449                   Type 1 fonts must be placed in
8450                   <file>/usr/share/fonts/X11/Type1/</file>.  If font
8451                   metric files are available, they must be placed here
8452                   as well.
8453               </item>
8454
8455               <item>
8456                   Subdirectories of <file>/usr/share/fonts/X11/</file>
8457                   other than those listed above must be neither
8458                   created nor used.  (The <file>PEX</file>, <file>CID</file>,
8459                   <file>Speedo</file>, and <file>cyrillic</file> directories
8460                   are excepted for historical reasons, but installation of
8461                   files into these directories remains discouraged.)
8462               </item>
8463
8464               <item>
8465                   Font packages may, instead of placing files directly
8466                   in the X font directories listed above, provide
8467                   symbolic links in that font directory pointing to
8468                   the files' actual location in the filesystem.  Such
8469                   a location must comply with the FHS.
8470               </item>
8471
8472               <item>
8473                   Font packages should not contain both 75dpi and
8474                   100dpi versions of a font.  If both are available,
8475                   they should be provided in separate binary packages
8476                   with <tt>-75dpi</tt> or <tt>-100dpi</tt> appended to
8477                   the names of the packages containing the
8478                   corresponding fonts.
8479               </item>
8480
8481               <item>
8482                   Fonts destined for the <file>misc</file> subdirectory
8483                   should not be included in the same package as 75dpi
8484                   or 100dpi fonts; instead, they should be provided in
8485                   a separate package with <tt>-misc</tt> appended to
8486                   its name.
8487               </item>
8488
8489               <item>
8490                   Font packages must not provide the files
8491                   <file>fonts.dir</file>, <file>fonts.alias</file>, or
8492                   <file>fonts.scale</file> in a font directory:
8493                   <list>
8494                     <item>
8495                         <file>fonts.dir</file> files must not be provided at all.
8496                     </item>
8497
8498                     <item>
8499                         <file>fonts.alias</file> and <file>fonts.scale</file>
8500                         files, if needed, should be provided in the
8501                         directory
8502                         <file>/etc/X11/fonts/<var>fontdir</var>/<var>package</var>.<var>extension</var></file>,
8503                         where <var>fontdir</var> is the name of the
8504                         subdirectory of
8505                         <file>/usr/share/fonts/X11/</file> where the
8506                         package's corresponding fonts are stored
8507                         (e.g., <tt>75dpi</tt> or <tt>misc</tt>),
8508                         <var>package</var> is the name of the package
8509                         that provides these fonts, and
8510                         <var>extension</var> is either <tt>scale</tt>
8511                         or <tt>alias</tt>, whichever corresponds to
8512                         the file contents.
8513                     </item>
8514                   </list>
8515               </item>
8516
8517               <item>
8518                   Font packages must declare a dependency on
8519                   <tt>xfonts-utils</tt> in their control
8520                   data.
8521               </item>
8522
8523               <item>
8524                   Font packages that provide one or more
8525                   <file>fonts.scale</file> files as described above must
8526                   invoke <prgn>update-fonts-scale</prgn> on each
8527                   directory into which they installed fonts
8528                   <em>before</em> invoking
8529                   <prgn>update-fonts-dir</prgn> on that directory.
8530                   This invocation must occur in both the
8531                   <prgn>postinst</prgn> (for all arguments) and
8532                   <prgn>postrm</prgn> (for all arguments except
8533                   <tt>upgrade</tt>) scripts.
8534               </item>
8535
8536               <item>
8537                   Font packages that provide one or more
8538                   <file>fonts.alias</file> files as described above must
8539                   invoke <prgn>update-fonts-alias</prgn> on each
8540                   directory into which they installed fonts.  This
8541                   invocation must occur in both the
8542                   <prgn>postinst</prgn> (for all arguments) and
8543                   <prgn>postrm</prgn> (for all arguments except
8544                   <tt>upgrade</tt>) scripts.
8545               </item>
8546
8547               <item>
8548                   Font packages must invoke
8549                   <prgn>update-fonts-dir</prgn> on each directory into
8550                   which they installed fonts.  This invocation must
8551                   occur in both the <prgn>postinst</prgn> (for all
8552                   arguments) and <prgn>postrm</prgn> (for all
8553                   arguments except <tt>upgrade</tt>) scripts.
8554               </item>
8555
8556               <item>
8557                   Font packages must not provide alias names for the
8558                   fonts they include which collide with alias names
8559                   already in use by fonts already packaged.
8560               </item>
8561
8562               <item>
8563                   Font packages must not provide fonts with the same
8564                   XLFD registry name as another font already packaged.
8565               </item>
8566             </enumlist>
8567           </p>
8568         </sect1>
8569
8570         <sect1 id="appdefaults">
8571           <heading>Application defaults files</heading>
8572
8573           <p>
8574             Application defaults files must be installed in the
8575             directory <file>/etc/X11/app-defaults/</file> (use of a
8576             localized subdirectory of <file>/etc/X11/</file> as described
8577             in the <em>X Toolkit Intrinsics - C Language
8578             Interface</em> manual is also permitted).  They must be
8579             registered as <tt>conffile</tt>s or handled as
8580             configuration files.
8581           </p>
8582
8583           <p>
8584             Customization of programs' X resources may also be
8585             supported with the provision of a file with the same name
8586             as that of the package placed in the
8587             <file>/etc/X11/Xresources/</file> directory, which must
8588             registered as a <tt>conffile</tt> or handled as a
8589             configuration file.<footnote>
8590                 Note that this mechanism is not the same as using
8591                 app-defaults; app-defaults are tied to the client
8592                 binary on the local file system, whereas X resources
8593                 are stored in the X server and affect all connecting
8594                 clients.
8595             </footnote>
8596           </p>
8597         </sect1>
8598
8599         <sect1>
8600           <heading>Installation directory issues</heading>
8601
8602           <p>
8603             Historically, packages using the X Window System used a
8604             separate set of installation directories from other packages.
8605             This practice has been discontinued and packages using the X
8606             Window System should now generally be installed in the same
8607             directories as any other package.  Specifically, packages must
8608             not install files under the <file>/usr/X11R6/</file> directory
8609             and the <file>/usr/X11R6/</file> directory hierarchy should be
8610             regarded as obsolete.
8611           </p>
8612
8613           <p>
8614             Include files previously installed under
8615             <file>/usr/X11R6/include/X11/</file> should be installed into
8616             <file>/usr/include/X11/</file>.  For files previously
8617             installed into subdirectories of
8618             <file>/usr/X11R6/lib/X11/</file>, package maintainers should
8619             determine if subdirectories of <file>/usr/lib/</file> and
8620             <file>/usr/share/</file> can be used.  If not, a subdirectory
8621             of <file>/usr/lib/X11/</file> should be used.
8622           </p>
8623
8624           <p>
8625             Configuration files for window, display, or session managers
8626             or other applications that are tightly integrated with the X
8627             Window System may be placed in a subdirectory
8628             of <file>/etc/X11/</file> corresponding to the package name.
8629             Other X Window System applications should use
8630             the <file>/etc/</file> directory unless otherwise mandated by
8631             policy (such as for <ref id="appdefaults">).
8632           </p>
8633         </sect1>
8634
8635         <sect1>
8636           <heading>The OSF/Motif and OpenMotif libraries</heading>
8637
8638           <p>
8639             <em>Programs that require the non-DFSG-compliant OSF/Motif or
8640               OpenMotif libraries</em><footnote>
8641                 OSF/Motif and OpenMotif are collectively referred to as
8642                 "Motif" in this policy document.
8643             </footnote>
8644             should be compiled against and tested with LessTif (a free
8645             re-implementation of Motif) instead.  If the maintainer
8646             judges that the program or programs do not work
8647             sufficiently well with LessTif to be distributed and
8648             supported, but do so when compiled against Motif, then two
8649             versions of the package should be created; one linked
8650             statically against Motif and with <tt>-smotif</tt>
8651             appended to the package name, and one linked dynamically
8652             against Motif and with <tt>-dmotif</tt> appended to the
8653             package name.
8654           </p>
8655
8656           <p>
8657             Both Motif-linked versions are dependent
8658             upon non-DFSG-compliant software and thus cannot be
8659             uploaded to the <em>main</em> distribution; if the
8660             software is itself DFSG-compliant it may be uploaded to
8661             the <em>contrib</em> distribution.  While known existing
8662             versions of Motif permit unlimited redistribution of
8663             binaries linked against the library (whether statically or
8664             dynamically), it is the package maintainer's
8665             responsibility to determine whether this is permitted by
8666             the license of the copy of Motif in their possession.
8667           </p>
8668         </sect1>
8669       </sect>
8670
8671       <sect id="perl">
8672         <heading>Perl programs and modules</heading>
8673
8674         <p>
8675           Perl programs and modules should follow the current Perl policy.
8676         </p>
8677
8678         <p>
8679           The Perl policy can be found in the <tt>perl-policy</tt>
8680           files in the <tt>debian-policy</tt> package.
8681           It is also available from the Debian web mirrors at
8682           <tt><url name="/doc/packaging-manuals/perl-policy/"
8683                 id="http://www.debian.org/doc/packaging-manuals/perl-policy/"></tt>.
8684         </p>
8685       </sect>
8686
8687       <sect id="emacs">
8688         <heading>Emacs lisp programs</heading>
8689
8690         <p>
8691           Please refer to the "Debian Emacs Policy" for details of how to
8692           package emacs lisp programs.
8693         </p>
8694
8695         <p>
8696           The Emacs policy is available in
8697           <file>debian-emacs-policy.gz</file> of the
8698           <package>emacsen-common</package> package.
8699           It is also available from the Debian web mirrors at
8700           <tt><url name="/doc/packaging-manuals/debian-emacs-policy"
8701                 id="http://www.debian.org/doc/packaging-manuals/debian-emacs-policy"></tt>.
8702         </p>
8703       </sect>
8704
8705       <sect>
8706         <heading>Games</heading>
8707
8708         <p>
8709           The permissions on <file>/var/games</file> are mode 755, owner
8710           <tt>root</tt> and group <tt>root</tt>.
8711         </p>
8712
8713         <p>
8714           Each game decides on its own security policy.</p>
8715
8716         <p>
8717           Games which require protected, privileged access to
8718           high-score files, saved games, etc., may be made
8719           set-<em>group</em>-id (mode 2755) and owned by
8720           <tt>root:games</tt>, and use files and directories with
8721           appropriate permissions (770 <tt>root:games</tt>, for
8722           example).  They must not be made
8723           set-<em>user</em>-id, as this causes security problems. (If
8724           an attacker can subvert any set-user-id game they can
8725           overwrite the executable of any other, causing other players
8726           of these games to run a Trojan horse program.  With a
8727           set-group-id game the attacker only gets access to less
8728           important game data, and if they can get at the other
8729           players' accounts at all it will take considerably more
8730           effort.)</p>
8731
8732         <p>
8733           Some packages, for example some fortune cookie programs, are
8734           configured by the upstream authors to install with their
8735           data files or other static information made unreadable so
8736           that they can only be accessed through set-id programs
8737           provided.  You should not do this in a Debian package: anyone can
8738           download the <file>.deb</file> file and read the data from it,
8739           so there is no point making the files unreadable.  Not
8740           making the files unreadable also means that you don't have
8741           to make so many programs set-id, which reduces the risk of a
8742           security hole.</p>
8743
8744         <p>
8745           As described in the FHS, binaries of games should be
8746           installed in the directory <file>/usr/games</file>. This also
8747           applies to games that use the X Window System. Manual pages
8748           for games (X and non-X games) should be installed in
8749           <file>/usr/share/man/man6</file>.</p>
8750       </sect>
8751     </chapt>
8752
8753
8754     <chapt id="docs">
8755       <heading>Documentation</heading>
8756
8757       <sect>
8758         <heading>Manual pages</heading>
8759
8760         <p>
8761           You should install manual pages in <prgn>nroff</prgn> source
8762           form, in appropriate places under <file>/usr/share/man</file>.
8763           You should only use sections 1 to 9 (see the FHS for more
8764           details).  You must not install a pre-formatted "cat page".
8765         </p>
8766
8767         <p>
8768           Each program, utility, and function should have an
8769           associated manual page included in the same package. It is
8770           suggested that all configuration files also have a manual
8771           page included as well. Manual pages for protocols and other
8772           auxiliary things are optional.
8773         </p>
8774
8775         <p>
8776           If no manual page is available, this is considered as a bug
8777           and should be reported to the Debian Bug Tracking System (the
8778           maintainer of the package is allowed to write this bug report
8779           themselves, if they so desire).  Do not close the bug report
8780           until a proper man page is available.<footnote>
8781               It is not very hard to write a man page. See the
8782               <url id="http://www.schweikhardt.net/man_page_howto.html"
8783                 name="Man-Page-HOWTO">,
8784               <manref name="man" section="7">, the examples
8785               created by <prgn>debmake</prgn> or <prgn>dh_make</prgn>,
8786               the helper programs <prgn>help2man</prgn>, or the
8787               directory <file>/usr/share/doc/man-db/examples</file>.
8788           </footnote>
8789         </p>
8790
8791         <p>
8792           You may forward a complaint about a missing man page to the
8793           upstream authors, and mark the bug as forwarded in the
8794           Debian bug tracking system.  Even though the GNU Project do
8795           not in general consider the lack of a man page to be a bug,
8796           we do; if they tell you that they don't consider it a bug
8797           you should leave the bug in our bug tracking system open
8798           anyway.
8799         </p>
8800
8801         <p>
8802           Manual pages should be installed compressed using <tt>gzip -9</tt>.
8803         </p>
8804
8805         <p>
8806           If one man page needs to be accessible via several names it
8807           is better to use a symbolic link than the <file>.so</file>
8808           feature, but there is no need to fiddle with the relevant
8809           parts of the upstream source to change from <file>.so</file> to
8810           symlinks: don't do it unless it's easy.  You should not
8811           create hard links in the manual page directories, nor put
8812           absolute filenames in <file>.so</file> directives.  The filename
8813           in a <file>.so</file> in a man page should be relative to the
8814           base of the man page tree (usually
8815           <file>/usr/share/man</file>). If you do not create any links
8816           (whether symlinks, hard links, or <tt>.so</tt> directives)
8817           in the file system to the alternate names of the man page,
8818           then you should not rely on <prgn>man</prgn> finding your
8819           man page under those names based solely on the information in
8820           the man page's header.<footnote>
8821               Supporting this in <prgn>man</prgn> often requires
8822               unreasonable processing time to find a manual page or to
8823               report that none exists, and moves knowledge into man's
8824               database that would be better left in the file system.
8825               This support is therefore deprecated and will cease to
8826               be present in the future.
8827           </footnote>
8828         </p>
8829
8830         <p>
8831           Manual pages in locale-specific subdirectories of
8832           <file>/usr/share/man</file> should use either UTF-8 or the usual
8833           legacy encoding for that language (normally the one corresponding
8834           to the shortest relevant locale name in
8835           <file>/usr/share/i18n/SUPPORTED</file>). For example, pages under
8836           <file>/usr/share/man/fr</file> should use either UTF-8 or
8837           ISO-8859-1.<footnote>
8838             <prgn>man</prgn> will automatically detect whether UTF-8 is in
8839             use. In future, all manual pages will be required to use
8840             UTF-8.
8841           </footnote>
8842         </p>
8843
8844         <p>
8845           A country name (the <tt>DE</tt> in <tt>de_DE</tt>) should not be
8846           included in the subdirectory name unless it indicates a
8847           significant difference in the language, as this excludes
8848           speakers of the language in other countries.<footnote>
8849             At the time of writing, Chinese and Portuguese are the main
8850             languages with such differences, so <file>pt_BR</file>,
8851             <file>zh_CN</file>, and <file>zh_TW</file> are all allowed.
8852           </footnote>
8853         </p>
8854
8855         <p>
8856           If a localized version of a manual page is provided, it should
8857           either be up-to-date or it should be obvious to the reader that
8858           it is outdated and the original manual page should be used
8859           instead.  This can be done either by a note at the beginning of
8860           the manual page or by showing the missing or changed portions in
8861           the original language instead of the target language.
8862         </p>
8863       </sect>
8864
8865       <sect>
8866         <heading>Info documents</heading>
8867
8868         <p>
8869           Info documents should be installed in <file>/usr/share/info</file>.
8870           They should be compressed with <tt>gzip -9</tt>.
8871         </p>
8872
8873         <p>
8874           The <prgn>install-info</prgn> program maintains a directory of
8875           installed info documents in <file>/usr/share/info/dir</file> for
8876           the use of info readers.<footnote>
8877             It was previously necessary for packages installing info
8878             documents to run <prgn>install-info</prgn> from maintainer
8879             scripts.  This is no longer necessary.  The installation
8880             system now uses dpkg triggers.
8881           </footnote>
8882           This file must not be included in packages.  Packages containing
8883           info documents should depend on <tt>dpkg (>= 1.15.4) |
8884           install-info</tt> to ensure that the directory file is properly
8885           rebuilt during partial upgrades from Debian 5.0 (lenny) and
8886           earlier.
8887         </p>
8888
8889         <p>
8890           Info documents should contain section and directory entry
8891           information in the document for the use
8892           of <prgn>install-info</prgn>.  The section should be specified
8893           via a line starting with <tt>INFO-DIR-SECTION</tt> followed by a
8894           space and the section of this info page.  The directory entry or
8895           entries should be included between
8896           a <tt>START-INFO-DIR-ENTRY</tt> line and
8897           an <tt>END-INFO-DIR-ENTRY</tt> line.  For example:
8898           <example>
8899 INFO-DIR-SECTION Individual utilities
8900 START-INFO-DIR-ENTRY
8901 * example: (example).               An example info directory entry.
8902 END-INFO-DIR-ENTRY
8903           </example>
8904           To determine which section to use, you should look
8905           at <file>/usr/share/info/dir</file> on your system and choose
8906           the most relevant (or create a new section if none of the
8907           current sections are relevant).<footnote>
8908             Normally, info documents are generated from Texinfo source.
8909             To include this information in the generated info document, if
8910             it is absent, add commands like:
8911             <example>
8912 @dircategory Individual utilities
8913 @direntry
8914 * example: (example).               An example info directory entry.
8915 @end direntry
8916             </example>
8917             to the Texinfo source of the document and ensure that the info
8918             documents are rebuilt from source during the package build.
8919           </footnote>
8920         </p>
8921       </sect>
8922
8923       <sect>
8924         <heading>Additional documentation</heading>
8925
8926         <p>
8927           Any additional documentation that comes with the package may
8928           be installed at the discretion of the package maintainer.
8929           Plain text documentation should be installed in the directory
8930           <file>/usr/share/doc/<var>package</var></file>, where
8931           <var>package</var> is the name of the package, and
8932           compressed with <tt>gzip -9</tt> unless it is small.
8933         </p>
8934
8935         <p>
8936           If a package comes with large amounts of documentation which
8937           many users of the package will not require you should create
8938           a separate binary package to contain it, so that it does not
8939           take up disk space on the machines of users who do not need
8940           or want it installed.</p>
8941
8942         <p>
8943           It is often a good idea to put text information files
8944           (<file>README</file>s, changelogs, and so forth) that come with
8945           the source package in <file>/usr/share/doc/<var>package</var></file>
8946           in the binary package.  However, you don't need to install
8947           the instructions for building and installing the package, of
8948           course!</p>
8949
8950         <p>
8951           Packages must not require the existence of any files in
8952           <file>/usr/share/doc/</file> in order to function
8953           <footnote>
8954               The system administrator should be able to
8955               delete files in <file>/usr/share/doc/</file> without causing
8956               any programs to break.
8957           </footnote>.
8958           Any files that are referenced by programs but are also
8959           useful as stand alone documentation should be installed under
8960           <file>/usr/share/<var>package</var>/</file> with symbolic links from
8961           <file>/usr/share/doc/<var>package</var></file>.
8962         </p>
8963
8964         <p>
8965           <file>/usr/share/doc/<var>package</var></file> may be a symbolic
8966           link to another directory in <file>/usr/share/doc</file> only if
8967           the two packages both come from the same source and the
8968           first package Depends on the second.<footnote>
8969             <p>
8970               Please note that this does not override the section on
8971               changelog files below, so the file 
8972               <file>/usr/share/<var>package</var>/changelog.Debian.gz</file>
8973               must refer to the changelog for the current version of
8974               <var>package</var> in question. In practice, this means
8975               that the sources of the target and the destination of the
8976               symlink must be the same (same source package and
8977               version). 
8978             </p>
8979           </footnote>
8980         </p>
8981
8982         <p>
8983           Former Debian releases placed all additional documentation
8984           in <file>/usr/doc/<var>package</var></file>.  This has been
8985           changed to <file>/usr/share/doc/<var>package</var></file>,
8986           and packages must not put documentation in the directory
8987           <file>/usr/doc/<var>package</var></file>. <footnote>
8988             At this phase of the transition, we no longer require a
8989             symbolic link in <file>/usr/doc/</file>. At a later point,
8990             policy shall change to make the symbolic links a bug.
8991           </footnote>
8992         </p>
8993       </sect>
8994
8995       <sect>
8996         <heading>Preferred documentation formats</heading>
8997
8998         <p>
8999           The unification of Debian documentation is being carried out
9000           via HTML.</p>
9001
9002         <p>
9003           If your package comes with extensive documentation in a
9004           markup format that can be converted to various other formats
9005           you should if possible ship HTML versions in a binary
9006           package, in the directory
9007           <file>/usr/share/doc/<var>appropriate-package</var></file> or
9008           its subdirectories.<footnote>
9009               The rationale: The important thing here is that HTML
9010               docs should be available in <em>some</em> package, not
9011               necessarily in the main binary package.
9012           </footnote>
9013         </p>
9014
9015         <p>
9016           Other formats such as PostScript may be provided at the
9017           package maintainer's discretion.
9018         </p>
9019       </sect>
9020
9021       <sect id="copyrightfile">
9022         <heading>Copyright information</heading>
9023
9024         <p>
9025           Every package must be accompanied by a verbatim copy of its
9026           copyright and distribution license in the file
9027           <file>/usr/share/doc/<var>package</var>/copyright</file>. This
9028           file must neither be compressed nor be a symbolic link.
9029         </p>
9030
9031         <p>
9032           In addition, the copyright file must say where the upstream
9033           sources (if any) were obtained.  It should name the original
9034           authors of the package and the Debian maintainer(s) who were
9035           involved with its creation.
9036         </p>
9037
9038         <p>
9039           Packages in the <em>contrib</em> or <em>non-free</em> archive
9040           areas should state in the copyright file that the package is not
9041           part of the Debian GNU/Linux distribution and briefly explain
9042           why.
9043         </p>
9044
9045         <p>
9046           A copy of the file which will be installed in
9047           <file>/usr/share/doc/<var>package</var>/copyright</file> should
9048           be in <file>debian/copyright</file> in the source package.
9049         </p>
9050
9051         <p>
9052           <file>/usr/share/doc/<var>package</var></file> may be a symbolic
9053           link to another directory in <file>/usr/share/doc</file> only if
9054           the two packages both come from the same source and the
9055           first package Depends on the second.  These rules are
9056           important because copyrights must be extractable by
9057           mechanical means.
9058         </p>
9059
9060         <p>
9061           Packages distributed under the UCB BSD license, the Apache
9062           license (version 2.0), the Artistic license, the GNU GPL
9063           (version 2 or 3), the GNU LGPL (versions 2, 2.1, or 3), and the
9064           GNU FDL (versions 1.2 or 1.3) should refer to the corresponding
9065           files under <file>/usr/share/common-licenses</file>,<footnote>
9066             <p>
9067               In particular,
9068               <file>/usr/share/common-licenses/BSD</file>,
9069               <file>/usr/share/common-licenses/Apache-2.0</file>,
9070               <file>/usr/share/common-licenses/Artistic</file>,
9071               <file>/usr/share/common-licenses/GPL-2</file>,
9072               <file>/usr/share/common-licenses/GPL-3</file>,
9073               <file>/usr/share/common-licenses/LGPL-2</file>,
9074               <file>/usr/share/common-licenses/LGPL-2.1</file>,
9075               <file>/usr/share/common-licenses/LGPL-3</file>,
9076               <file>/usr/share/common-licenses/GFDL-1.2</file>, and
9077               <file>/usr/share/common-licenses/GFDL-1.3</file>
9078               respectively.
9079             </p>
9080           </footnote> rather than quoting them in the copyright
9081           file. 
9082         </p>
9083
9084         <p>
9085           You should not use the copyright file as a general <file>README</file>
9086           file.  If your package has such a file it should be
9087           installed in <file>/usr/share/doc/<var>package</var>/README</file> or
9088           <file>README.Debian</file> or some other appropriate place.</p>
9089       </sect>
9090
9091       <sect>
9092         <heading>Examples</heading>
9093
9094         <p>
9095           Any examples (configurations, source files, whatever),
9096           should be installed in a directory
9097           <file>/usr/share/doc/<var>package</var>/examples</file>.  These
9098           files should not be referenced by any program: they're there
9099           for the benefit of the system administrator and users as
9100           documentation only.  Architecture-specific example files
9101           should be installed in a directory
9102           <file>/usr/lib/<var>package</var>/examples</file> with symbolic
9103           links to them from
9104           <file>/usr/share/doc/<var>package</var>/examples</file>, or the
9105           latter directory itself may be a symbolic link to the
9106           former.
9107         </p>
9108
9109         <p>
9110           If the purpose of a package is to provide examples, then the
9111           example files may be installed into
9112           <file>/usr/share/doc/<var>package</var></file>.
9113         </p>
9114       </sect>
9115
9116       <sect id="changelogs">
9117         <heading>Changelog files</heading>
9118
9119         <p>
9120           Packages that are not Debian-native must contain a
9121           compressed copy of the <file>debian/changelog</file> file from
9122           the Debian source tree in
9123           <file>/usr/share/doc/<var>package</var></file> with the name
9124           <file>changelog.Debian.gz</file>.
9125         </p>
9126
9127         <p>
9128           If an upstream changelog is available, it should be accessible as
9129           <file>/usr/share/doc/<var>package</var>/changelog.gz</file> in
9130           plain text.  If the upstream changelog is distributed in
9131           HTML, it should be made available in that form as
9132           <file>/usr/share/doc/<var>package</var>/changelog.html.gz</file>
9133           and a plain text <file>changelog.gz</file> should be generated
9134           from it using, for example, <tt>lynx -dump -nolist</tt>.  If
9135           the upstream changelog files do not already conform to this
9136           naming convention, then this may be achieved either by
9137           renaming the files, or by adding a symbolic link, at the
9138           maintainer's discretion.<footnote>
9139               Rationale: People should not have to look in places for
9140               upstream changelogs merely because they are given
9141               different names or are distributed in HTML format.
9142           </footnote>
9143         </p>
9144
9145         <p>
9146           All of these files should be installed compressed using
9147           <tt>gzip -9</tt>, as they will become large with time even
9148           if they start out small.
9149         </p>
9150
9151         <p>
9152           If the package has only one changelog which is used both as
9153           the Debian changelog and the upstream one because there is
9154           no separate upstream maintainer then that changelog should
9155           usually be installed as
9156           <file>/usr/share/doc/<var>package</var>/changelog.gz</file>; if
9157           there is a separate upstream maintainer, but no upstream
9158           changelog, then the Debian changelog should still be called
9159           <file>changelog.Debian.gz</file>.
9160         </p>
9161
9162         <p>
9163           For details about the format and contents of the Debian
9164           changelog file, please see <ref id="dpkgchangelog">.
9165         </p>
9166       </sect>
9167     </chapt>
9168
9169     <appendix id="pkg-scope">
9170       <heading>Introduction and scope of these appendices</heading>
9171
9172       <p>
9173         These appendices are taken essentially verbatim from the
9174         now-deprecated Packaging Manual, version 3.2.1.0.  They are
9175         the chapters which are likely to be of use to package
9176         maintainers and which have not already been included in the
9177         policy document itself. Most of these sections are very likely
9178         not relevant to policy; they should be treated as
9179         documentation for the packaging system. Please note that these
9180         appendices are included for convenience, and for historical
9181         reasons: they used to be part of policy package, and they have
9182         not yet been incorporated into dpkg documentation. However,
9183         they still have value, and hence they are presented here.
9184       </p>
9185
9186       <p>
9187         They have not yet been checked to ensure that they are
9188         compatible with the contents of policy, and if there are any
9189         contradictions, the version in the main policy document takes
9190         precedence.  The remaining chapters of the old Packaging
9191         Manual have also not been read in detail to ensure that there
9192         are not parts which have been left out.  Both of these will be
9193         done in due course.
9194       </p>
9195
9196       <p>
9197         Certain parts of the Packaging manual were integrated into the
9198         Policy Manual proper, and removed from the appendices. Links
9199         have been placed from the old locations to the new ones.
9200       </p>
9201
9202       <p>
9203         <prgn>dpkg</prgn> is a suite of programs for creating binary
9204         package files and installing and removing them on Unix
9205         systems.<footnote>
9206             <prgn>dpkg</prgn> is targeted primarily at Debian
9207             GNU/Linux, but may work on or be ported to other
9208             systems.
9209         </footnote>
9210       </p>
9211
9212       <p>
9213         The binary packages are designed for the management of
9214         installed executable programs (usually compiled binaries) and
9215         their associated data, though source code examples and
9216         documentation are provided as part of some packages.</p>
9217
9218       <p>
9219         This manual describes the technical aspects of creating Debian
9220         binary packages (<file>.deb</file> files).  It documents the
9221         behavior of the package management programs
9222         <prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and the way
9223         they interact with packages.</p>
9224
9225       <p>
9226         It also documents the interaction between
9227         <prgn>dselect</prgn>'s core and the access method scripts it
9228         uses to actually install the selected packages, and describes
9229         how to create a new access method.</p>
9230
9231       <p>
9232         This manual does not go into detail about the options and
9233         usage of the package building and installation tools.  It
9234         should therefore be read in conjunction with those programs'
9235         man pages.
9236       </p>
9237
9238       <p>
9239         The utility programs which are provided with <prgn>dpkg</prgn>
9240         for managing various system configuration and similar issues,
9241         such as <prgn>update-rc.d</prgn> and
9242         <prgn>install-info</prgn>, are not described in detail here -
9243         please see their man pages.
9244       </p>
9245
9246       <p>
9247         It is assumed that the reader is reasonably familiar with the
9248         <prgn>dpkg</prgn> System Administrators' manual.
9249         Unfortunately this manual does not yet exist.
9250       </p>
9251
9252       <p>
9253         The Debian version of the FSF's GNU hello program is provided
9254         as an example for people wishing to create Debian
9255         packages. The Debian <prgn>debmake</prgn> package is
9256         recommended as a very helpful tool in creating and maintaining
9257         Debian packages. However, while the tools and examples are
9258         helpful, they do not replace the need to read and follow the
9259         Policy and Programmer's Manual.</p>
9260     </appendix>
9261
9262     <appendix id="pkg-binarypkg">
9263       <heading>Binary packages (from old Packaging Manual)</heading>
9264
9265       <p>
9266         The binary package has two main sections.  The first part
9267         consists of various control information files and scripts used
9268         by <prgn>dpkg</prgn> when installing and removing.  See <ref
9269         id="pkg-controlarea">.
9270       </p>
9271
9272       <p>
9273         The second part is an archive containing the files and
9274         directories to be installed.
9275       </p>
9276
9277       <p>
9278         In the future binary packages may also contain other
9279         components, such as checksums and digital signatures. The
9280         format for the archive is described in full in the
9281         <file>deb(5)</file> man page.
9282       </p>
9283
9284
9285       <sect id="pkg-bincreating"><heading>Creating package files -
9286       <prgn>dpkg-deb</prgn>
9287         </heading>
9288
9289         <p>
9290           All manipulation of binary package files is done by
9291           <prgn>dpkg-deb</prgn>; it's the only program that has
9292           knowledge of the format.  (<prgn>dpkg-deb</prgn> may be
9293           invoked by calling <prgn>dpkg</prgn>, as <prgn>dpkg</prgn>
9294           will spot that the options requested are appropriate to
9295           <prgn>dpkg-deb</prgn> and invoke that instead with the same
9296           arguments.)
9297         </p>
9298
9299         <p>
9300           In order to create a binary package you must make a
9301           directory tree which contains all the files and directories
9302           you want to have in the file system data part of the package.
9303           In Debian-format source packages this directory is usually
9304           <file>debian/tmp</file>, relative to the top of the package's
9305           source tree.
9306         </p>
9307
9308         <p>
9309           They should have the locations (relative to the root of the
9310           directory tree you're constructing) ownerships and
9311           permissions which you want them to have on the system when
9312           they are installed.
9313         </p>
9314
9315         <p>
9316           With current versions of <prgn>dpkg</prgn> the uid/username
9317           and gid/groupname mappings for the users and groups being
9318           used should be the same on the system where the package is
9319           built and the one where it is installed.
9320         </p>
9321
9322         <p>
9323           You need to add one special directory to the root of the
9324           miniature file system tree you're creating:
9325           <prgn>DEBIAN</prgn>.  It should contain the control
9326           information files, notably the binary package control file
9327           (see <ref id="pkg-controlfile">).
9328         </p>
9329
9330         <p>
9331           The <prgn>DEBIAN</prgn> directory will not appear in the
9332           file system archive of the package, and so won't be installed
9333           by <prgn>dpkg</prgn> when the package is unpacked.
9334         </p>
9335
9336         <p>
9337           When you've prepared the package, you should invoke:
9338           <example>
9339   dpkg --build <var>directory</var>
9340           </example>
9341         </p>
9342
9343         <p>
9344           This will build the package in
9345           <file><var>directory</var>.deb</file>.  (<prgn>dpkg</prgn> knows
9346           that <tt>--build</tt> is a <prgn>dpkg-deb</prgn> option, so
9347           it invokes <prgn>dpkg-deb</prgn> with the same arguments to
9348           build the package.)
9349         </p>
9350
9351         <p>
9352           See the man page <manref name="dpkg-deb" section="8"> for details of how
9353           to examine the contents of this newly-created file.  You may find the
9354           output of following commands enlightening:
9355           <example>
9356   dpkg-deb --info <var>filename</var>.deb
9357   dpkg-deb --contents <var>filename</var>.deb
9358   dpkg --contents <var>filename</var>.deb
9359           </example>
9360           To view the copyright file for a package you could use this command:
9361           <example>
9362   dpkg --fsys-tarfile <var>filename</var>.deb | tar xOf - --wildcards \*/copyright | pager
9363           </example>
9364         </p>
9365       </sect>
9366
9367       <sect id="pkg-controlarea">
9368         <heading>Package control information files</heading>
9369
9370         <p>
9371           The control information portion of a binary package is a
9372           collection of files with names known to <prgn>dpkg</prgn>.
9373           It will treat the contents of these files specially - some
9374           of them contain information used by <prgn>dpkg</prgn> when
9375           installing or removing the package; others are scripts which
9376           the package maintainer wants <prgn>dpkg</prgn> to run.
9377         </p>
9378
9379         <p>
9380           It is possible to put other files in the package control
9381           area, but this is not generally a good idea (though they
9382           will largely be ignored).
9383         </p>
9384
9385         <p>
9386           Here is a brief list of the control info files supported by
9387           <prgn>dpkg</prgn> and a summary of what they're used for.
9388         </p>
9389
9390         <p>
9391           <taglist>
9392             <tag><tt>control</tt>
9393             <item>
9394               <p>
9395                 This is the key description file used by
9396                 <prgn>dpkg</prgn>.  It specifies the package's name
9397                 and version, gives its description for the user,
9398                 states its relationships with other packages, and so
9399                 forth.  See <ref id="sourcecontrolfiles"> and
9400                 <ref id="binarycontrolfiles">.
9401               </p>
9402
9403               <p>
9404                 It is usually generated automatically from information
9405                 in the source package by the
9406                 <prgn>dpkg-gencontrol</prgn> program, and with
9407                 assistance from <prgn>dpkg-shlibdeps</prgn>.
9408                 See <ref id="pkg-sourcetools">.
9409               </p>
9410             </item>
9411
9412             <tag><tt>postinst</tt>, <tt>preinst</tt>, <tt>postrm</tt>,
9413                  <tt>prerm</tt>
9414             </tag>
9415             <item>
9416               <p>
9417                 These are executable files (usually scripts) which
9418                 <prgn>dpkg</prgn> runs during installation, upgrade
9419                 and removal of packages.  They allow the package to
9420                 deal with matters which are particular to that package
9421                 or require more complicated processing than that
9422                 provided by <prgn>dpkg</prgn>.  Details of when and
9423                 how they are called are in <ref id="maintainerscripts">.
9424               </p>
9425
9426               <p>
9427                 It is very important to make these scripts idempotent.
9428                 See <ref id="idempotency">.
9429               </p>
9430
9431               <p>
9432                 The maintainer scripts are guaranteed to run with a
9433                 controlling terminal and can interact with the user.
9434                 See <ref id="controllingterminal">.
9435               </p>
9436             </item>
9437
9438             <tag><tt>conffiles</tt>
9439             </tag>
9440             <item>
9441                 This file contains a list of configuration files which
9442                 are to be handled automatically by <prgn>dpkg</prgn>
9443                 (see <ref id="pkg-conffiles">).  Note that not necessarily
9444                 every configuration file should be listed here.
9445             </item>
9446
9447             <tag><tt>shlibs</tt>
9448             </tag>
9449             <item>
9450                 This file contains a list of the shared libraries
9451                 supplied by the package, with dependency details for
9452                 each.  This is used by <prgn>dpkg-shlibdeps</prgn>
9453                 when it determines what dependencies are required in a
9454                 package control file. The <tt>shlibs</tt> file format
9455                 is described on <ref id="shlibs">.
9456             </item>
9457           </taglist>
9458         </p>
9459
9460       <sect id="pkg-controlfile">
9461         <heading>The main control information file: <tt>control</tt></heading>
9462
9463         <p>
9464           The most important control information file used by
9465           <prgn>dpkg</prgn> when it installs a package is
9466           <tt>control</tt>.  It contains all the package's "vital
9467           statistics".
9468         </p>
9469
9470         <p>
9471           The binary package control files of packages built from
9472           Debian sources are made by a special tool,
9473           <prgn>dpkg-gencontrol</prgn>, which reads
9474           <file>debian/control</file> and <file>debian/changelog</file> to
9475           find the information it needs.  See <ref id="pkg-sourcepkg"> for
9476           more details.
9477         </p>
9478
9479         <p>
9480           The fields in binary package control files are listed in
9481           <ref id="binarycontrolfiles">.
9482         </p>
9483
9484         <p>
9485           A description of the syntax of control files and the purpose
9486           of the fields is available in <ref id="controlfields">.
9487         </p>
9488       </sect>
9489
9490       <sect>
9491         <heading>Time Stamps</heading>
9492
9493         <p>
9494           See <ref id="timestamps">.
9495         </p>
9496       </sect>
9497     </appendix>
9498
9499     <appendix id="pkg-sourcepkg">
9500       <heading>Source packages (from old Packaging Manual) </heading>
9501
9502       <p>
9503         The Debian binary packages in the distribution are generated
9504         from Debian sources, which are in a special format to assist
9505         the easy and automatic building of binaries.
9506       </p>
9507
9508       <sect id="pkg-sourcetools">
9509         <heading>Tools for processing source packages</heading>
9510
9511         <p>
9512           Various tools are provided for manipulating source packages;
9513           they pack and unpack sources and help build of binary
9514           packages and help manage the distribution of new versions.
9515         </p>
9516
9517         <p>
9518           They are introduced and typical uses described here; see
9519           <manref name="dpkg-source" section="1"> for full
9520           documentation about their arguments and operation.
9521         </p>
9522
9523         <p>
9524           For examples of how to construct a Debian source package,
9525           and how to use those utilities that are used by Debian
9526           source packages, please see the <prgn>hello</prgn> example
9527           package.
9528         </p>
9529
9530         <sect1 id="pkg-dpkg-source">
9531           <heading>
9532             <prgn>dpkg-source</prgn> - packs and unpacks Debian source
9533             packages
9534           </heading>
9535
9536           <p>
9537             This program is frequently used by hand, and is also
9538             called from package-independent automated building scripts
9539             such as <prgn>dpkg-buildpackage</prgn>.
9540           </p>
9541
9542           <p>
9543             To unpack a package it is typically invoked with
9544             <example>
9545   dpkg-source -x <var>.../path/to/filename</var>.dsc
9546             </example>
9547           </p>
9548
9549            <p>
9550             with the <file><var>filename</var>.tar.gz</file> and
9551             <file><var>filename</var>.diff.gz</file> (if applicable) in
9552             the same directory.  It unpacks into
9553             <file><var>package</var>-<var>version</var></file>, and if
9554             applicable
9555             <file><var>package</var>-<var>version</var>.orig</file>, in
9556             the current directory.
9557           </p>
9558
9559           <p>
9560             To create a packed source archive it is typically invoked:
9561             <example>
9562   dpkg-source -b <var>package</var>-<var>version</var>
9563           </example>
9564           </p>
9565
9566           <p>
9567             This will create the <file>.dsc</file>, <file>.tar.gz</file> and
9568             <file>.diff.gz</file> (if appropriate) in the current
9569             directory.  <prgn>dpkg-source</prgn> does not clean the
9570             source tree first - this must be done separately if it is
9571             required.
9572           </p>
9573
9574           <p>
9575             See also <ref id="pkg-sourcearchives">.</p>
9576         </sect1>
9577
9578
9579         <sect1 id="pkg-dpkg-buildpackage">
9580           <heading>
9581             <prgn>dpkg-buildpackage</prgn> - overall package-building
9582             control script
9583           </heading>
9584
9585           <p>
9586             <prgn>dpkg-buildpackage</prgn> is a script which invokes
9587             <prgn>dpkg-source</prgn>, the <file>debian/rules</file>
9588             targets <tt>clean</tt>, <tt>build</tt> and
9589             <tt>binary</tt>, <prgn>dpkg-genchanges</prgn> and
9590             <prgn>gpg</prgn> (or <prgn>pgp</prgn>) to build a signed
9591             source and binary package upload.
9592           </p>
9593
9594           <p>
9595             It is usually invoked by hand from the top level of the
9596             built or unbuilt source directory.  It may be invoked with
9597             no arguments; useful arguments include:
9598             <taglist compact="compact">
9599               <tag><tt>-uc</tt>, <tt>-us</tt></tag>
9600               <item>
9601                 <p>
9602                   Do not sign the <tt>.changes</tt> file or the
9603                   source package <tt>.dsc</tt> file, respectively.</p>
9604               </item>
9605               <tag><tt>-p<var>sign-command</var></tt></tag>
9606               <item>
9607                 <p>
9608                   Invoke <var>sign-command</var> instead of finding
9609                   <tt>gpg</tt> or <tt>pgp</tt> on the <prgn>PATH</prgn>.
9610                   <var>sign-command</var> must behave just like
9611                   <prgn>gpg</prgn> or <tt>pgp</tt>.</p>
9612               </item>
9613               <tag><tt>-r<var>root-command</var></tt></tag>
9614               <item>
9615                 <p>
9616                   When root privilege is required, invoke the command
9617                   <var>root-command</var>.  <var>root-command</var>
9618                   should invoke its first argument as a command, from
9619                   the <prgn>PATH</prgn> if necessary, and pass its
9620                   second and subsequent arguments to the command it
9621                   calls.  If no <var>root-command</var> is supplied
9622                   then <var>dpkg-buildpackage</var> will take no
9623                   special action to gain root privilege, so that for
9624                   most packages it will have to be invoked as root to
9625                   start with.</p>
9626               </item>
9627               <tag><tt>-b</tt>, <tt>-B</tt></tag>
9628               <item>
9629                 <p>
9630                   Two types of binary-only build and upload - see
9631                   <manref name="dpkg-source" section="1">.
9632                 </p>
9633               </item>
9634             </taglist>
9635           </p>
9636         </sect1>
9637
9638         <sect1 id="pkg-dpkg-gencontrol">
9639           <heading>
9640             <prgn>dpkg-gencontrol</prgn> - generates binary package
9641             control files
9642           </heading>
9643
9644           <p>
9645             This program is usually called from <file>debian/rules</file>
9646             (see <ref id="pkg-sourcetree">) in the top level of the source
9647             tree.
9648           </p>
9649
9650           <p>
9651             This is usually done just before the files and directories in the
9652             temporary directory tree where the package is being built have their
9653             permissions and ownerships set and the package is constructed using
9654             <prgn>dpkg-deb/</prgn>
9655               <footnote>
9656                 This is so that the control file which is produced has
9657                 the right permissions
9658             </footnote>.
9659           </p>
9660
9661           <p>
9662             <prgn>dpkg-gencontrol</prgn> must be called after all the
9663             files which are to go into the package have been placed in
9664             the temporary build directory, so that its calculation of
9665             the installed size of a package is correct.
9666           </p>
9667
9668           <p>
9669             It is also necessary for <prgn>dpkg-gencontrol</prgn> to
9670             be run after <prgn>dpkg-shlibdeps</prgn> so that the
9671             variable substitutions created by
9672             <prgn>dpkg-shlibdeps</prgn> in <file>debian/substvars</file>
9673             are available.
9674           </p>
9675
9676           <p>
9677             For a package which generates only one binary package, and
9678             which builds it in <file>debian/tmp</file> relative to the top
9679             of the source package, it is usually sufficient to call
9680             <prgn>dpkg-gencontrol</prgn>.
9681           </p>
9682
9683           <p>
9684             Sources which build several binaries will typically need
9685             something like:
9686             <example>
9687   dpkg-gencontrol -Pdebian/tmp-<var>pkg</var> -p<var>package</var>
9688             </example> The <tt>-P</tt> tells
9689             <prgn>dpkg-gencontrol</prgn> that the package is being
9690             built in a non-default directory, and the <tt>-p</tt>
9691             tells it which package's control file should be generated.
9692           </p>
9693
9694           <p>
9695             <prgn>dpkg-gencontrol</prgn> also adds information to the
9696             list of files in <file>debian/files</file>, for the benefit of
9697             (for example) a future invocation of
9698             <prgn>dpkg-genchanges</prgn>.</p>
9699         </sect1>
9700
9701         <sect1 id="pkg-dpkg-shlibdeps">
9702           <heading>
9703             <prgn>dpkg-shlibdeps</prgn> - calculates shared library
9704             dependencies
9705           </heading>
9706
9707           <p>
9708             This program is usually called from <file>debian/rules</file>
9709             just before <prgn>dpkg-gencontrol</prgn> (see <ref
9710             id="pkg-sourcetree">), in the top level of the source tree.
9711           </p>
9712
9713           <p>
9714             Its arguments are executables and shared libraries
9715             <footnote>
9716               <p>
9717                 They may be specified either in the locations in the
9718                 source tree where they are created or in the locations
9719                 in the temporary build tree where they are installed
9720                 prior to binary package creation.
9721               </p>
9722             </footnote> for which shared library dependencies should
9723             be included in the binary package's control file.
9724           </p>
9725
9726           <p>
9727             If some of the found shared libraries should only
9728             warrant a <tt>Recommends</tt> or <tt>Suggests</tt>, or if
9729             some warrant a <tt>Pre-Depends</tt>, this can be achieved
9730             by using the <tt>-d<var>dependency-field</var></tt> option
9731             before those executable(s).  (Each <tt>-d</tt> option
9732             takes effect until the next <tt>-d</tt>.)
9733           </p>
9734
9735           <p>
9736             <prgn>dpkg-shlibdeps</prgn> does not directly cause the
9737             output control file to be modified.  Instead by default it
9738             adds to the <file>debian/substvars</file> file variable
9739             settings like <tt>shlibs:Depends</tt>.  These variable
9740             settings must be referenced in dependency fields in the
9741             appropriate per-binary-package sections of the source
9742             control file.
9743           </p>
9744
9745           <p>
9746             For example, a package that generates an essential part
9747             which requires dependencies, and optional parts that 
9748             which only require a recommendation, would separate those
9749             two sets of dependencies into two different fields.<footnote>
9750                 At the time of writing, an example for this was the
9751                 <package/xmms/ package, with Depends used for the xmms
9752                 executable, Recommends for the plug-ins and Suggests for
9753                 even more optional features provided by unzip.
9754             </footnote>
9755             It can say in its <file>debian/rules</file>:
9756             <example>
9757   dpkg-shlibdeps -dDepends <var>program anotherprogram ...</var> \
9758                  -dRecommends <var>optionalpart anotheroptionalpart</var>
9759             </example>
9760             and then in its main control file <file>debian/control</file>:
9761             <example>
9762   <var>...</var>
9763   Depends: ${shlibs:Depends}
9764   Recommends: ${shlibs:Recommends}
9765   <var>...</var>
9766             </example>
9767           </p>
9768
9769           <p>
9770             Sources which produce several binary packages with
9771             different shared library dependency requirements can use
9772             the <tt>-p<var>varnameprefix</var></tt> option to override
9773             the default <tt>shlibs:</tt> prefix (one invocation of
9774             <prgn>dpkg-shlibdeps</prgn> per setting of this option).
9775             They can thus produce several sets of dependency
9776             variables, each of the form
9777             <tt><var>varnameprefix</var>:<var>dependencyfield</var></tt>,
9778             which can be referred to in the appropriate parts of the
9779             binary package control files.
9780           </p>
9781         </sect1>
9782
9783
9784         <sect1 id="pkg-dpkg-distaddfile">
9785           <heading>
9786             <prgn>dpkg-distaddfile</prgn> - adds a file to
9787             <file>debian/files</file>
9788           </heading>
9789
9790           <p>
9791             Some packages' uploads need to include files other than
9792             the source and binary package files.
9793           </p>
9794
9795           <p>
9796             <prgn>dpkg-distaddfile</prgn> adds a file to the
9797             <file>debian/files</file> file so that it will be included in
9798             the <file>.changes</file> file when
9799             <prgn>dpkg-genchanges</prgn> is run.
9800           </p>
9801
9802           <p>
9803             It is usually invoked from the <tt>binary</tt> target of
9804             <file>debian/rules</file>:
9805             <example>
9806   dpkg-distaddfile <var>filename</var> <var>section</var> <var>priority</var>
9807             </example>
9808             The <var>filename</var> is relative to the directory where
9809             <prgn>dpkg-genchanges</prgn> will expect to find it - this
9810             is usually the directory above the top level of the source
9811             tree.  The <file>debian/rules</file> target should put the
9812             file there just before or just after calling
9813             <prgn>dpkg-distaddfile</prgn>.
9814           </p>
9815
9816           <p>
9817             The <var>section</var> and <var>priority</var> are passed
9818             unchanged into the resulting <file>.changes</file> file.
9819           </p>
9820         </sect1>
9821
9822
9823         <sect1 id="pkg-dpkg-genchanges">
9824           <heading>
9825             <prgn>dpkg-genchanges</prgn> - generates a <file>.changes</file>
9826             upload control file
9827           </heading>
9828
9829           <p>
9830             This program is usually called by package-independent
9831             automatic building scripts such as
9832             <prgn>dpkg-buildpackage</prgn>, but it may also be called
9833             by hand.
9834           </p>
9835
9836           <p>
9837             It is usually called in the top level of a built source
9838             tree, and when invoked with no arguments will print out a
9839             straightforward <file>.changes</file> file based on the
9840             information in the source package's changelog and control
9841             file and the binary and source packages which should have
9842             been built.
9843           </p>
9844         </sect1>
9845
9846
9847         <sect1 id="pkg-dpkg-parsechangelog">
9848           <heading>
9849             <prgn>dpkg-parsechangelog</prgn> - produces parsed
9850             representation of a changelog
9851           </heading>
9852
9853           <p>
9854             This program is used internally by
9855             <prgn>dpkg-source</prgn> et al.  It may also occasionally
9856             be useful in <file>debian/rules</file> and elsewhere.  It
9857             parses a changelog, <file>debian/changelog</file> by default,
9858             and prints a control-file format representation of the
9859             information in it to standard output.
9860           </p>
9861         </sect1>
9862
9863         <sect1 id="pkg-dpkg-architecture">
9864           <heading>
9865             <prgn>dpkg-architecture</prgn> - information about the build and
9866             host system
9867           </heading>
9868
9869           <p>
9870             This program can be used manually, but is also invoked by
9871             <tt>dpkg-buildpackage</tt> or <file>debian/rules</file> to set
9872             environment or make variables which specify the build and host
9873             architecture for the package building process.
9874           </p>
9875         </sect1>
9876       </sect>
9877
9878       <sect id="pkg-sourcetree">
9879         <heading>The Debianised source tree</heading>
9880
9881         <p>
9882           The source archive scheme described later is intended to
9883           allow a Debianised source tree with some associated control
9884           information to be reproduced and transported easily.  The
9885           Debianised source tree is a version of the original program
9886           with certain files added for the benefit of the
9887           Debianisation process, and with any other changes required
9888           made to the rest of the source code and installation
9889           scripts.
9890         </p>
9891
9892         <p>
9893           The extra files created for Debian are in the subdirectory
9894           <file>debian</file> of the top level of the Debianised source
9895           tree.  They are described below.
9896         </p>
9897
9898         <sect1 id="pkg-debianrules">
9899           <heading><file>debian/rules</file> - the main building script</heading>
9900
9901           <p>
9902             See <ref id="debianrules">.
9903           </p>
9904         </sect1>
9905
9906
9907         <sect1 id="pkg-dpkgchangelog">
9908           <heading><file>debian/changelog</file></heading>
9909
9910           <p>
9911             See <ref id="dpkgchangelog">.
9912           </p>
9913
9914           <sect2><heading>Defining alternative changelog formats
9915             </heading>
9916
9917             <p>
9918               It is possible to use a different format to the standard
9919               one, by providing a parser for the format you wish to
9920               use.
9921             </p>
9922
9923             <p>
9924               In order to have <tt>dpkg-parsechangelog</tt> run your
9925               parser, you must include a line within the last 40 lines
9926               of your file matching the Perl regular expression:
9927               <tt>\schangelog-format:\s+([0-9a-z]+)\W</tt> The part in
9928               parentheses should be the name of the format.  For
9929               example, you might say:
9930               <example>
9931   @@@ changelog-format: joebloggs @@@
9932               </example>
9933               Changelog format names are non-empty strings of alphanumerics.
9934             </p>
9935
9936             <p>
9937               If such a line exists then <tt>dpkg-parsechangelog</tt>
9938               will look for the parser as
9939               <file>/usr/lib/dpkg/parsechangelog/<var>format-name</var></file>
9940               or
9941               <file>/usr/local/lib/dpkg/parsechangelog/<var>format-name</var></file>;
9942               it is an error for it not to find it, or for it not to
9943               be an executable program.  The default changelog format
9944               is <tt>dpkg</tt>, and a parser for it is provided with
9945               the <tt>dpkg</tt> package.
9946             </p>
9947
9948             <p>
9949               The parser will be invoked with the changelog open on
9950               standard input at the start of the file.  It should read
9951               the file (it may seek if it wishes) to determine the
9952               information required and return the parsed information
9953               to standard output in the form of a series of control
9954               fields in the standard format.  By default it should
9955               return information about only the most recent version in
9956               the changelog; it should accept a
9957               <tt>-v<var>version</var></tt> option to return changes
9958               information from all versions present <em>strictly
9959               after</em> <var>version</var>, and it should then be an
9960               error for <var>version</var> not to be present in the
9961               changelog.
9962             </p>
9963
9964             <p>
9965               The fields are:
9966               <list compact="compact">
9967                 <item><qref id="f-Source"><tt>Source</tt></qref></item>
9968                 <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
9969                 <item><qref id="f-Distribution"><tt>Distribution</tt></qref> (mandatory)</item>
9970                 <item><qref id="f-Urgency"><tt>Urgency</tt></qref> (mandatory)</item>
9971                 <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
9972                 <item><qref id="f-Date"><tt>Date</tt></qref></item>
9973                 <item><qref id="f-Changes"><tt>Changes</tt></qref> (mandatory)</item>
9974               </list>
9975             </p>
9976
9977             <p>
9978               If several versions are being returned (due to the use
9979               of <tt>-v</tt>), the urgency value should be of the
9980               highest urgency code listed at the start of any of the
9981               versions requested followed by the concatenated
9982               (space-separated) comments from all the versions
9983               requested; the maintainer, version, distribution and
9984               date should always be from the most recent version.
9985             </p>
9986
9987             <p>
9988               For the format of the <tt>Changes</tt> field see
9989               <ref id="f-Changes">.
9990             </p>
9991
9992             <p>
9993               If the changelog format which is being parsed always or
9994               almost always leaves a blank line between individual
9995               change notes these blank lines should be stripped out,
9996               so as to make the resulting output compact.
9997             </p>
9998
9999             <p>
10000               If the changelog format does not contain date or package
10001               name information this information should be omitted from
10002               the output.  The parser should not attempt to synthesize
10003               it or find it from other sources.
10004             </p>
10005
10006             <p>
10007               If the changelog does not have the expected format the
10008               parser should exit with a nonzero exit status, rather
10009               than trying to muddle through and possibly generating
10010               incorrect output.
10011             </p>
10012
10013             <p>
10014               A changelog parser may not interact with the user at
10015               all.
10016             </p>
10017           </sect2>
10018         </sect1>
10019
10020         <sect1 id="pkg-srcsubstvars">
10021           <heading><file>debian/substvars</file> and variable substitutions</heading>
10022
10023           <p>
10024             See <ref id="substvars">.
10025           </p>
10026
10027         </sect1>
10028
10029         <sect1>
10030           <heading><file>debian/files</file></heading>
10031
10032           <p>
10033             See <ref id="debianfiles">.
10034           </p>
10035         </sect1>
10036
10037         <sect1><heading><file>debian/tmp</file>
10038           </heading>
10039
10040           <p>
10041             This is the canonical temporary location for the
10042             construction of binary packages by the <tt>binary</tt>
10043             target.  The directory <file>tmp</file> serves as the root of
10044             the file system tree as it is being constructed (for
10045             example, by using the package's upstream makefiles install
10046             targets and redirecting the output there), and it also
10047             contains the <tt>DEBIAN</tt> subdirectory.  See <ref
10048             id="pkg-bincreating">.
10049           </p>
10050
10051           <p>
10052             If several binary packages are generated from the same
10053             source tree it is usual to use several
10054             <file>debian/tmp<var>something</var></file> directories, for
10055             example <file>tmp-a</file> or <file>tmp-doc</file>.
10056           </p>
10057
10058           <p>
10059             Whatever <file>tmp</file> directories are created and used by
10060             <tt>binary</tt> must of course be removed by the
10061             <tt>clean</tt> target.</p></sect1>
10062       </sect>
10063
10064
10065       <sect id="pkg-sourcearchives"><heading>Source packages as archives
10066         </heading>
10067
10068         <p>
10069           As it exists on the FTP site, a Debian source package
10070           consists of three related files.  You must have the right
10071           versions of all three to be able to use them.
10072         </p>
10073
10074         <p>
10075           <taglist>
10076             <tag>Debian source control file - <tt>.dsc</tt></tag>
10077             <item>
10078                 This file is a control file used by <prgn>dpkg-source</prgn>
10079                 to extract a source package.
10080                 See <ref id="debiansourcecontrolfiles">.
10081             </item>
10082
10083             <tag>
10084               Original source archive -
10085               <file>
10086                 <var>package</var>_<var>upstream-version</var>.orig.tar.gz
10087               </file>
10088             </tag>
10089
10090             <item>
10091               <p>
10092                 This is a compressed (with <tt>gzip -9</tt>)
10093                 <prgn>tar</prgn> file containing the source code from
10094                 the upstream authors of the program.
10095               </p>
10096             </item>
10097
10098             <tag>
10099               Debianisation diff -
10100               <file>
10101                 <var>package</var>_<var>upstream_version-revision</var>.diff.gz
10102               </file>
10103             </tag>
10104             <item>
10105
10106               <p>
10107                 This is a unified context diff (<tt>diff -u</tt>)
10108                 giving the changes which are required to turn the
10109                 original source into the Debian source.  These changes
10110                 may only include editing and creating plain files.
10111                 The permissions of files, the targets of symbolic
10112                 links and the characteristics of special files or
10113                 pipes may not be changed and no files may be removed
10114                 or renamed.
10115               </p>
10116
10117               <p>
10118                 All the directories in the diff must exist, except the
10119                 <file>debian</file> subdirectory of the top of the source
10120                 tree, which will be created by
10121                 <prgn>dpkg-source</prgn> if necessary when unpacking.
10122               </p>
10123
10124               <p>
10125                 The <prgn>dpkg-source</prgn> program will
10126                 automatically make the <file>debian/rules</file> file
10127                 executable (see below).</p></item>
10128           </taglist>
10129         </p>
10130
10131         <p>
10132           If there is no original source code - for example, if the
10133           package is specially prepared for Debian or the Debian
10134           maintainer is the same as the upstream maintainer - the
10135           format is slightly different: then there is no diff, and the
10136           tarfile is named
10137           <file><var>package</var>_<var>version</var>.tar.gz</file>,
10138           and preferably contains a directory named
10139           <file><var>package</var>-<var>version</var></file>.
10140         </p>
10141       </sect>
10142
10143       <sect>
10144         <heading>Unpacking a Debian source package without <prgn>dpkg-source</prgn></heading>
10145
10146         <p>
10147           <tt>dpkg-source -x</tt> is the recommended way to unpack a
10148           Debian source package.  However, if it is not available it
10149           is possible to unpack a Debian source archive as follows:
10150         <enumlist compact="compact">
10151           <item>
10152             <p>
10153               Untar the tarfile, which will create a <file>.orig</file>
10154               directory.</p>
10155           </item>
10156           <item>
10157             <p>Rename the <file>.orig</file> directory to
10158               <file><var>package</var>-<var>version</var></file>.</p>
10159           </item>
10160             <item>
10161             <p>
10162               Create the subdirectory <file>debian</file> at the top of
10163               the source tree.</p>
10164           </item>
10165           <item><p>Apply the diff using <tt>patch -p0</tt>.</p>
10166           </item>
10167           <item><p>Untar the tarfile again if you want a copy of the original
10168               source code alongside the Debianised version.</p>
10169           </item>
10170         </enumlist>
10171
10172         <p>
10173           It is not possible to generate a valid Debian source archive
10174           without using <prgn>dpkg-source</prgn>.  In particular,
10175           attempting to use <prgn>diff</prgn> directly to generate the
10176           <file>.diff.gz</file> file will not work.
10177         </p>
10178
10179         <sect1>
10180           <heading>Restrictions on objects in source packages</heading>
10181
10182           <p>
10183             The source package may not contain any hard links
10184             <footnote>
10185                 This is not currently detected when building source
10186                 packages, but only when extracting
10187                 them.
10188             </footnote>
10189             <footnote>
10190                 Hard links may be permitted at some point in the
10191                 future, but would require a fair amount of
10192                 work.
10193             </footnote>, device special files, sockets or setuid or
10194             setgid files.
10195             <footnote>
10196                 Setgid directories are allowed.
10197             </footnote>
10198           </p>
10199
10200           <p>
10201             The source packaging tools manage the changes between the
10202             original and Debianised source using <prgn>diff</prgn> and
10203             <prgn>patch</prgn>.  Turning the original source tree as
10204             included in the <file>.orig.tar.gz</file> into the debianised
10205             source must not involve any changes which cannot be
10206             handled by these tools.  Problematic changes which cause
10207             <prgn>dpkg-source</prgn> to halt with an error when
10208             building the source package are:
10209             <list compact="compact">
10210               <item><p>Adding or removing symbolic links, sockets or pipes.</p>
10211               </item>
10212               <item><p>Changing the targets of symbolic links.</p>
10213               </item>
10214               <item><p>Creating directories, other than <file>debian</file>.</p>
10215               </item>
10216               <item><p>Changes to the contents of binary files.</p></item>
10217             </list> Changes which cause <prgn>dpkg-source</prgn> to
10218             print a warning but continue anyway are:
10219             <list compact="compact">
10220               <item>
10221                 <p>
10222                   Removing files, directories or symlinks.
10223                   <footnote>
10224                       Renaming a file is not treated specially - it is
10225                       seen as the removal of the old file (which
10226                       generates a warning, but is otherwise ignored),
10227                       and the creation of the new one.
10228                   </footnote>
10229                 </p>
10230               </item>
10231               <item>
10232                 <p>
10233                   Changed text files which are missing the usual final
10234                   newline (either in the original or the modified
10235                   source tree).
10236                 </p>
10237               </item>
10238             </list>
10239             Changes which are not represented, but which are not detected by
10240             <prgn>dpkg-source</prgn>, are:
10241             <list compact="compact">
10242               <item><p>Changing the permissions of files (other than
10243                   <file>debian/rules</file>) and directories.</p></item>
10244             </list>
10245           </p>
10246
10247           <p>
10248             The <file>debian</file> directory and <file>debian/rules</file>
10249             are handled specially by <prgn>dpkg-source</prgn> - before
10250             applying the changes it will create the <file>debian</file>
10251             directory, and afterwards it will make
10252             <file>debian/rules</file> world-executable.
10253           </p>
10254         </sect1>
10255       </sect>
10256     </appendix>
10257
10258     <appendix id="pkg-controlfields">
10259       <heading>Control files and their fields (from old Packaging Manual)</heading>
10260
10261       <p>
10262         Many of the tools in the <prgn>dpkg</prgn> suite manipulate
10263         data in a common format, known as control files.  Binary and
10264         source packages have control data as do the <file>.changes</file>
10265         files which control the installation of uploaded files, and
10266         <prgn>dpkg</prgn>'s internal databases are in a similar
10267         format.
10268       </p>
10269
10270       <sect>
10271         <heading>Syntax of control files</heading>
10272
10273         <p>
10274           See <ref id="controlsyntax">.
10275         </p>
10276
10277         <p>
10278           It is important to note that there are several fields which
10279           are optional as far as <prgn>dpkg</prgn> and the related
10280           tools are concerned, but which must appear in every Debian
10281           package, or whose omission may cause problems.
10282         </p>
10283       </sect>
10284
10285       <sect>
10286         <heading>List of fields</heading>
10287
10288         <p>
10289           See <ref id="controlfieldslist">.
10290         </p>
10291
10292         <p>
10293           This section now contains only the fields that didn't belong
10294           to the Policy manual.
10295         </p>
10296
10297         <sect1 id="pkg-f-Filename">
10298           <heading><tt>Filename</tt> and <tt>MSDOS-Filename</tt></heading>
10299
10300           <p>
10301             These fields in <tt>Packages</tt> files give the
10302             filename(s) of (the parts of) a package in the
10303             distribution directories, relative to the root of the
10304             Debian hierarchy.  If the package has been split into
10305             several parts the parts are all listed in order, separated
10306             by spaces.
10307           </p>
10308         </sect1>
10309
10310         <sect1 id="pkg-f-Size">
10311           <heading><tt>Size</tt> and <tt>MD5sum</tt></heading>
10312
10313           <p>
10314             These fields in <file>Packages</file> files give the size (in
10315             bytes, expressed in decimal) and MD5 checksum of the
10316             file(s) which make(s) up a binary package in the
10317             distribution.  If the package is split into several parts
10318             the values for the parts are listed in order, separated by
10319             spaces.
10320           </p>
10321         </sect1>
10322
10323         <sect1 id="pkg-f-Status">
10324           <heading><tt>Status</tt></heading>
10325
10326           <p>
10327             This field in <prgn>dpkg</prgn>'s status file records
10328             whether the user wants a package installed, removed or
10329             left alone, whether it is broken (requiring
10330             re-installation) or not and what its current state on the
10331             system is.  Each of these pieces of information is a
10332             single word.
10333           </p>
10334         </sect1>
10335
10336         <sect1 id="pkg-f-Config-Version">
10337           <heading><tt>Config-Version</tt></heading>
10338
10339           <p>
10340             If a package is not installed or not configured, this
10341             field in <prgn>dpkg</prgn>'s status file records the last
10342             version of the package which was successfully
10343             configured.
10344           </p>
10345         </sect1>
10346
10347         <sect1 id="pkg-f-Conffiles">
10348           <heading><tt>Conffiles</tt></heading>
10349
10350           <p>
10351             This field in <prgn>dpkg</prgn>'s status file contains
10352             information about the automatically-managed configuration
10353             files held by a package.  This field should <em>not</em>
10354             appear anywhere in a package!
10355           </p>
10356         </sect1>
10357
10358         <sect1>
10359           <heading>Obsolete fields</heading>
10360
10361           <p>
10362             These are still recognized by <prgn>dpkg</prgn> but should
10363             not appear anywhere any more.
10364
10365             <taglist compact="compact">
10366
10367               <tag><tt>Revision</tt></tag>
10368               <tag><tt>Package-Revision</tt></tag>
10369               <tag><tt>Package_Revision</tt></tag>
10370               <item>
10371                   The Debian revision part of the package version was
10372                   at one point in a separate control file field.  This
10373                   field went through several names.
10374               </item>
10375
10376               <tag><tt>Recommended</tt></tag>
10377               <item>Old name for <tt>Recommends</tt>.</item>
10378
10379               <tag><tt>Optional</tt></tag>
10380               <item>Old name for <tt>Suggests</tt>.</item>
10381
10382               <tag><tt>Class</tt></tag>
10383               <item>Old name for <tt>Priority</tt>.</item>
10384
10385             </taglist>
10386           </p>
10387         </sect1>
10388       </sect>
10389
10390     </appendix>
10391
10392     <appendix id="pkg-conffiles">
10393       <heading>Configuration file handling (from old Packaging Manual)</heading>
10394
10395       <p>
10396         <prgn>dpkg</prgn> can do a certain amount of automatic
10397         handling of package configuration files.
10398       </p>
10399
10400       <p>
10401         Whether this mechanism is appropriate depends on a number of
10402         factors, but basically there are two approaches to any
10403         particular configuration file.
10404       </p>
10405
10406       <p>
10407         The easy method is to ship a best-effort configuration in the
10408         package, and use <prgn>dpkg</prgn>'s conffile mechanism to
10409         handle updates.  If the user is unlikely to want to edit the
10410         file, but you need them to be able to without losing their
10411         changes, and a new package with a changed version of the file
10412         is only released infrequently, this is a good approach.
10413       </p>
10414
10415       <p>
10416         The hard method is to build the configuration file from
10417         scratch in the <prgn>postinst</prgn> script, and to take the
10418         responsibility for fixing any mistakes made in earlier
10419         versions of the package automatically.  This will be
10420         appropriate if the file is likely to need to be different on
10421         each system.
10422       </p>
10423
10424       <sect><heading>Automatic handling of configuration files by
10425       <prgn>dpkg</prgn>
10426         </heading>
10427
10428         <p>
10429           A package may contain a control area file called
10430           <tt>conffiles</tt>.  This file should be a list of filenames
10431           of configuration files needing automatic handling, separated
10432           by newlines.  The filenames should be absolute pathnames,
10433           and the files referred to should actually exist in the
10434           package.
10435         </p>
10436
10437         <p>
10438           When a package is upgraded <prgn>dpkg</prgn> will process
10439           the configuration files during the configuration stage,
10440           shortly before it runs the package's <prgn>postinst</prgn>
10441           script,
10442         </p>
10443
10444         <p>
10445           For each file it checks to see whether the version of the
10446           file included in the package is the same as the one that was
10447           included in the last version of the package (the one that is
10448           being upgraded from); it also compares the version currently
10449           installed on the system with the one shipped with the last
10450           version.
10451         </p>
10452
10453         <p>
10454           If neither the user nor the package maintainer has changed
10455           the file, it is left alone.  If one or the other has changed
10456           their version, then the changed version is preferred - i.e.,
10457           if the user edits their file, but the package maintainer
10458           doesn't ship a different version, the user's changes will
10459           stay, silently, but if the maintainer ships a new version
10460           and the user hasn't edited it the new version will be
10461           installed (with an informative message).  If both have
10462           changed their version the user is prompted about the problem
10463           and must resolve the differences themselves.
10464         </p>
10465
10466         <p>
10467           The comparisons are done by calculating the MD5 message
10468           digests of the files, and storing the MD5 of the file as it
10469           was included in the most recent version of the package.
10470         </p>
10471
10472         <p>
10473           When a package is installed for the first time
10474           <prgn>dpkg</prgn> will install the file that comes with it,
10475           unless that would mean overwriting a file already on the
10476           file system.
10477         </p>
10478
10479         <p>
10480           However, note that <prgn>dpkg</prgn> will <em>not</em>
10481           replace a conffile that was removed by the user (or by a
10482           script).  This is necessary because with some programs a
10483           missing file produces an effect hard or impossible to
10484           achieve in another way, so that a missing file needs to be
10485           kept that way if the user did it.
10486         </p>
10487
10488         <p>
10489           Note that a package should <em>not</em> modify a
10490           <prgn>dpkg</prgn>-handled conffile in its maintainer
10491           scripts.  Doing this will lead to <prgn>dpkg</prgn> giving
10492           the user confusing and possibly dangerous options for
10493           conffile update when the package is upgraded.</p>
10494       </sect>
10495
10496       <sect><heading>Fully-featured maintainer script configuration
10497       handling
10498         </heading>
10499
10500         <p>
10501           For files which contain site-specific information such as
10502           the hostname and networking details and so forth, it is
10503           better to create the file in the package's
10504           <prgn>postinst</prgn> script.
10505         </p>
10506
10507         <p>
10508           This will typically involve examining the state of the rest
10509           of the system to determine values and other information, and
10510           may involve prompting the user for some information which
10511           can't be obtained some other way.
10512         </p>
10513
10514         <p>
10515           When using this method there are a couple of important
10516           issues which should be considered:
10517         </p>
10518
10519         <p>
10520           If you discover a bug in the program which generates the
10521           configuration file, or if the format of the file changes
10522           from one version to the next, you will have to arrange for
10523           the postinst script to do something sensible - usually this
10524           will mean editing the installed configuration file to remove
10525           the problem or change the syntax.  You will have to do this
10526           very carefully, since the user may have changed the file,
10527           perhaps to fix the very problem that your script is trying
10528           to deal with - you will have to detect these situations and
10529           deal with them correctly.
10530         </p>
10531
10532         <p>
10533           If you do go down this route it's probably a good idea to
10534           make the program that generates the configuration file(s) a
10535           separate program in <file>/usr/sbin</file>, by convention called
10536           <file><var>package</var>config</file> and then run that if
10537           appropriate from the post-installation script.  The
10538           <tt><var>package</var>config</tt> program should not
10539           unquestioningly overwrite an existing configuration - if its
10540           mode of operation is geared towards setting up a package for
10541           the first time (rather than any arbitrary reconfiguration
10542           later) you should have it check whether the configuration
10543           already exists, and require a <tt>--force</tt> flag to
10544           overwrite it.</p></sect>
10545     </appendix>
10546
10547     <appendix id="pkg-alternatives"><heading>Alternative versions of
10548         an interface - <prgn>update-alternatives</prgn> (from old
10549     Packaging Manual)
10550       </heading>
10551
10552       <p>
10553         When several packages all provide different versions of the
10554         same program or file it is useful to have the system select a
10555         default, but to allow the system administrator to change it
10556         and have their decisions respected.
10557       </p>
10558
10559       <p>
10560         For example, there are several versions of the <prgn>vi</prgn>
10561         editor, and there is no reason to prevent all of them from
10562         being installed at once, each under their own name
10563         (<prgn>nvi</prgn>, <prgn>vim</prgn> or whatever).
10564         Nevertheless it is desirable to have the name <tt>vi</tt>
10565         refer to something, at least by default.
10566       </p>
10567
10568       <p>
10569         If all the packages involved cooperate, this can be done with
10570         <prgn>update-alternatives</prgn>.
10571       </p>
10572
10573       <p>
10574         Each package provides its own version under its own name, and
10575         calls <prgn>update-alternatives</prgn> in its postinst to
10576         register its version (and again in its prerm to deregister
10577         it).
10578       </p>
10579
10580       <p>
10581         See the man page <manref name="update-alternatives"
10582         section="8"> for details.
10583       </p>
10584
10585       <p>
10586         If <prgn>update-alternatives</prgn> does not seem appropriate
10587         you may wish to consider using diversions instead.</p>
10588     </appendix>
10589
10590     <appendix id="pkg-diversions"><heading>Diversions - overriding a
10591     package's version of a file (from old Packaging Manual)
10592       </heading>
10593
10594       <p>
10595         It is possible to have <prgn>dpkg</prgn> not overwrite a file
10596         when it reinstalls the package it belongs to, and to have it
10597         put the file from the package somewhere else instead.
10598       </p>
10599
10600       <p>
10601         This can be used locally to override a package's version of a
10602         file, or by one package to override another's version (or
10603         provide a wrapper for it).
10604       </p>
10605
10606       <p>
10607         Before deciding to use a diversion, read <ref
10608         id="pkg-alternatives"> to see if you really want a diversion
10609         rather than several alternative versions of a program.
10610       </p>
10611
10612       <p>
10613         There is a diversion list, which is read by <prgn>dpkg</prgn>,
10614         and updated by a special program <prgn>dpkg-divert</prgn>.
10615         Please see <manref name="dpkg-divert" section="8"> for full
10616         details of its operation.
10617       </p>
10618
10619       <p>
10620         When a package wishes to divert a file from another, it should
10621         call <prgn>dpkg-divert</prgn> in its preinst to add the
10622         diversion and rename the existing file.  For example,
10623         supposing that a <prgn>smailwrapper</prgn> package wishes to
10624         install a wrapper around <file>/usr/sbin/smail</file>:
10625         <example>
10626    dpkg-divert --package smailwrapper --add --rename \
10627       --divert /usr/sbin/smail.real /usr/sbin/smail
10628         </example> The <tt>--package smailwrapper</tt> ensures that
10629         <prgn>smailwrapper</prgn>'s copy of <file>/usr/sbin/smail</file>
10630         can bypass the diversion and get installed as the true version.
10631         It's safe to add the diversion unconditionally on upgrades since
10632         it will be left unchanged if it already exists, but
10633         <prgn>dpkg-divert</prgn> will display a message.  To suppress that
10634         message, make the command conditional on the version from which
10635         the package is being upgraded:
10636         <example>
10637    if [ upgrade != "$1" ] || dpkg --compare-versions "$2" lt 1.0-2; then
10638       dpkg-divert --package smailwrapper --add --rename \
10639          --divert /usr/sbin/smail.real /usr/sbin/smail
10640    fi
10641         </example> where <tt>1.0-2</tt> is the version at which the
10642         diversion was first added to the package.  Running the command
10643         during abort-upgrade is pointless but harmless.
10644       </p>
10645
10646       <p>
10647         The postrm has to do the reverse:
10648         <example>
10649   if [ remove = "$1" -o abort-install = "$1" -o disappear = "$1" ]; then
10650      dpkg-divert --package smailwrapper --remove --rename \
10651         --divert /usr/sbin/smail.real /usr/sbin/smail
10652   fi
10653         </example> If the diversion was added at a particular version, the
10654         postrm should also handle the failure case of upgrading from an
10655         older version (unless the older version is so old that direct
10656         upgrades are no longer supported):
10657         <example>
10658   if [ abort-upgrade = "$1" ] && dpkg --compare-versions "$2" lt 1.0-2; then
10659      dpkg-divert --package smailwrapper --remove --rename \
10660         --divert /usr/sbin/smail.real /usr/sbin/smail
10661   fi
10662         </example> where <tt>1.02-2</tt> is the version at which the
10663         diversion was first added to the package.  The postrm should not
10664         remove the diversion on upgrades both because there's no reason to
10665         remove the diversion only to immediately re-add it and since the
10666         postrm of the old package is run after unpacking so the removal of
10667         the diversion will fail.
10668       </p>
10669
10670       <p>
10671         Do not attempt to divert a file which is vitally important for
10672         the system's operation - when using <prgn>dpkg-divert</prgn>
10673         there is a time, after it has been diverted but before
10674         <prgn>dpkg</prgn> has installed the new version, when the file
10675         does not exist.</p>
10676     </appendix>
10677
10678   </book>
10679 </debiandoc>
10680 <!-- Local variables: -->
10681 <!-- indent-tabs-mode: t -->
10682 <!-- End: -->
10683 <!-- vim:set ai et sts=2 sw=2 tw=76: -->