]> git.donarmstrong.com Git - debian/debian-policy.git/blob - policy.sgml
Add changelog for the removal of GNU/Linux
[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 <!-- current Debian changes file format -->
6 <!entity changesversion "1.8">
7 ]>
8 <debiandoc>
9
10   <book>
11     <titlepag>
12       <title>Debian Policy Manual</title>
13       <author><qref id="authors">The Debian Policy Mailing List</qref></author>
14       <version>version &version;, &date;</version>
15
16       <abstract>
17         This manual describes the policy requirements for the Debian
18         distribution.  This includes the structure and
19         contents of the Debian archive and several design issues of
20         the operating system, as well as technical requirements that
21         each package must satisfy to be included in the distribution.
22       </abstract>
23
24       <copyright>
25         <copyrightsummary>
26           Copyright &copy; 1996,1997,1998 Ian Jackson
27           and Christian Schwarz.
28         </copyrightsummary>
29         <p>
30           These are the copyright dates of the original Policy manual.
31           Since then, this manual has been updated by many others.  No
32           comprehensive collection of copyright notices for subsequent
33           work exists.
34         </p>
35
36         <p>
37           This manual is free software; you may redistribute it and/or
38           modify it under the terms of the GNU General Public License
39           as published by the Free Software Foundation; either version
40           2, or (at your option) any later version.
41         </p>
42
43         <p>
44           This is distributed in the hope that it will be useful, but
45           <em>without any warranty</em>; without even the implied
46           warranty of merchantability or fitness for a particular
47           purpose.  See the GNU General Public License for more
48           details.
49         </p>
50
51         <p>
52           A copy of the GNU General Public License is available as
53           <file>/usr/share/common-licenses/GPL</file> in the Debian
54           distribution or on the World Wide Web at
55           <url id="http://www.gnu.org/copyleft/gpl.html"
56                name="the GNU General Public Licence">. You can also
57           obtain it by writing to the Free Software Foundation, Inc.,
58           51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
59         </p>
60       </copyright>
61     </titlepag>
62
63     <toc detail="sect1">
64
65     <chapt id="scope">
66       <heading>About this manual</heading>
67       <sect>
68         <heading>Scope</heading>
69         <p>
70           This manual describes the policy requirements for the Debian
71           distribution. This includes the structure and
72           contents of the Debian archive and several design issues of the
73           operating system, as well as technical requirements that
74           each package must satisfy to be included in the
75           distribution.
76         </p>
77
78         <p>
79           This manual also describes Debian policy as it relates to
80           creating Debian packages. It is not a tutorial on how to build
81           packages, nor is it exhaustive where it comes to describing
82           the behavior of the packaging system. Instead, this manual
83           attempts to define the interface to the package management
84           system that the developers have to be conversant with.<footnote>
85               Informally, the criteria used for inclusion is that the
86               material meet one of the following requirements:
87               <taglist compact="compact">
88                 <tag>Standard interfaces</tag>
89                 <item>
90                     The material presented represents an interface to
91                     the packaging system that is mandated for use, and
92                     is used by, a significant number of packages, and
93                     therefore should not be changed without peer
94                     review. Package maintainers can then rely on this
95                     interface not changing, and the package management
96                     software authors need to ensure compatibility with
97                     this interface definition. (Control file and
98                     changelog file formats are examples.)
99                 </item>
100                 <tag>Chosen Convention</tag>
101                 <item>
102                     If there are a number of technically viable choices
103                     that can be made, but one needs to select one of
104                     these options for inter-operability. The version
105                     number format is one example.
106                 </item>
107               </taglist>
108               Please note that these are not mutually exclusive;
109               selected conventions often become parts of standard
110               interfaces.
111           </footnote>
112         </p>
113
114         <p>
115           The footnotes present in this manual are
116           merely informative, and are not part of Debian policy itself.
117         </p>
118
119         <p>
120           The appendices to this manual are not necessarily normative,
121           either. Please see <ref id="pkg-scope"> for more information.
122         </p>
123
124         <p>
125           In the normative part of this manual,
126           the words <em>must</em>, <em>should</em> and
127           <em>may</em>, and the adjectives <em>required</em>,
128           <em>recommended</em> and <em>optional</em>, are used to
129           distinguish the significance of the various guidelines in
130           this policy document. Packages that do not conform to the
131           guidelines denoted by <em>must</em> (or <em>required</em>)
132           will generally not be considered acceptable for the Debian
133           distribution. Non-conformance with guidelines denoted by
134           <em>should</em> (or <em>recommended</em>) will generally be
135           considered a bug, but will not necessarily render a package
136           unsuitable for distribution. Guidelines denoted by
137           <em>may</em> (or <em>optional</em>) are truly optional and
138           adherence is left to the maintainer's discretion.
139         </p>
140
141         <p>
142           These classifications are roughly equivalent to the bug
143           severities <em>serious</em> (for <em>must</em> or
144           <em>required</em> directive violations), <em>minor</em>,
145           <em>normal</em> or <em>important</em>
146           (for <em>should</em> or <em>recommended</em> directive
147           violations) and <em>wishlist</em> (for <em>optional</em>
148           items).
149           <footnote>
150                 Compare RFC 2119.  Note, however, that these words are
151                 used in a different way in this document.
152           </footnote>
153         </p>
154
155         <p>
156           Much of the information presented in this manual will be
157           useful even when building a package which is to be
158           distributed in some other way or is intended for local use
159           only.
160         </p>
161       </sect>
162
163       <sect>
164         <heading>New versions of this document</heading>
165
166         <p>
167           This manual is distributed via the Debian package
168           <package><url name="debian-policy"
169               id="http://packages.debian.org/debian-policy"></package> 
170           (<httpsite>packages.debian.org</httpsite> 
171           <httppath>/debian-policy</httppath>).
172         </p>
173
174         <p>
175           The current version of this document is also available from
176           the Debian web mirrors at
177           <tt><url name="/doc/debian-policy/"
178                 id="http://www.debian.org/doc/debian-policy/"></tt>.
179           (
180           <httpsite>www.debian.org</httpsite>
181           <httppath>/doc/debian-policy/</httppath>)
182           Also available from the same directory are several other
183           formats: <file>policy.html.tar.gz</file>
184           (<httppath>/doc/debian-policy/policy.html.tar.gz</httppath>),
185           <file>policy.pdf.gz</file> 
186           (<httppath>/doc/debian-policy/policy.pdf.gz</httppath>)
187           and <file>policy.ps.gz</file>
188           (<httppath>/doc/debian-policy/policy.ps.gz</httppath>).
189         </p>
190
191         <p>
192           The <package>debian-policy</package> package also includes the file
193           <file>upgrading-checklist.txt.gz</file> which indicates policy
194           changes between versions of this document.
195         </p>
196       </sect>
197
198       <sect id="authors">
199         <heading>Authors and Maintainers</heading>
200
201         <p>
202           Originally called "Debian GNU/Linux Policy Manual", this
203           manual was initially written in 1996 by Ian Jackson.
204           It was revised on November 27th, 1996 by David A. Morris.
205           Christian Schwarz added new sections on March 15th, 1997,
206           and reworked/restructured it in April-July 1997.
207           Christoph Lameter contributed the "Web Standard".
208           Julian Gilbey largely restructured it in 2001.
209         </p>
210
211         <p>
212           Since September 1998, the responsibility for the contents of
213           this document lies on the <url name="debian-policy mailing list"
214           id="mailto:debian-policy@lists.debian.org">. Proposals
215           are discussed there and inserted into policy after a certain
216           consensus is established.
217           <!-- insert shameless policy-process plug here eventually -->
218           The actual editing is done by a group of maintainers that have
219           no editorial powers. These are the current maintainers:
220
221           <enumlist>
222             <item>Julian Gilbey</item>
223             <item>Branden Robinson</item>
224             <item>Josip Rodin</item>
225             <item>Manoj Srivastava</item>
226           </enumlist>
227         </p>
228
229         <p>
230           While the authors of this document have tried hard to avoid
231           typos and other errors, these do still occur. If you discover
232           an error in this manual or if you want to give any
233           comments, suggestions, or criticisms please send an email to
234           the Debian Policy List,
235           <email>debian-policy@lists.debian.org</email>, or submit a
236           bug report against the <tt>debian-policy</tt> package.
237         </p>
238
239         <p>
240           Please do not try to reach the individual authors or maintainers
241           of the Policy Manual regarding changes to the Policy.
242         </p>
243       </sect>
244
245       <sect id="related">
246         <heading>Related documents</heading>
247
248         <p>
249           There are several other documents other than this Policy Manual
250           that are necessary to fully understand some Debian policies and
251           procedures.
252         </p>
253
254         <p>
255           The external "sub-policy" documents are referred to in:
256           <list compact="compact">
257             <item><ref id="fhs"></item>
258             <item><ref id="virtual_pkg"></item>
259             <item><ref id="menus"></item>
260             <item><ref id="mime"></item>
261             <item><ref id="perl"></item>
262             <item><ref id="maintscriptprompt"></item>
263             <item><ref id="emacs"></item>
264           </list>
265         </p>
266
267         <p>
268           In addition to those, which carry the weight of policy, there
269           is the Debian Developer's Reference. This document describes
270           procedures and resources for Debian developers, but it is
271           <em>not</em> normative; rather, it includes things that don't
272           belong in the Policy, such as best practices for developers.
273         </p>
274
275         <p>
276           The Developer's Reference is available in the
277           <package>developers-reference</package> package.
278           It's also available from the Debian web mirrors at
279           <tt><url name="/doc/developers-reference/"
280                 id="http://www.debian.org/doc/developers-reference/"></tt>.
281         </p>
282       </sect>
283
284       <sect id="definitions">
285         <heading>Definitions</heading>
286
287         <p>
288           The following terms are used in this Policy Manual:
289           <taglist>
290             <tag>ASCII</tag>
291             <item>
292               The character encoding specified by ANSI X3.4-1986 and its
293               predecessor standards, referred to in MIME as US-ASCII, and
294               corresponding to an encoding in eight bits per character of
295               the first 128 <url id="http://www.unicode.org/"
296               name="Unicode"> characters, with the eighth bit always zero.
297             </item>
298             <tag>UTF-8</tag>
299             <item>
300               The transformation format (sometimes called encoding) of
301               <url id="http://www.unicode.org/" name="Unicode"> defined by
302               <url id="http://www.rfc-editor.org/rfc/rfc3629.txt"
303               name="RFC 3629">.  UTF-8 has the useful property of having
304               ASCII as a subset, so any text encoded in ASCII is trivially
305               also valid UTF-8.
306             </item>
307           </taglist>
308         </p>
309       </sect>
310     </chapt>
311
312
313     <chapt id="archive">
314       <heading>The Debian Archive</heading>
315
316       <p>
317         The Debian system is maintained and distributed as a
318         collection of <em>packages</em>. Since there are so many of
319         them (currently well over 15000), they are split into
320         <em>sections</em> and given <em>priorities</em> to simplify
321         the handling of them.
322       </p>
323
324       <p>
325         The effort of the Debian project is to build a free operating
326         system, but not every package we want to make accessible is
327         <em>free</em> in our sense (see the Debian Free Software
328         Guidelines, below), or may be imported/exported without
329         restrictions. Thus, the archive is split into areas<footnote>
330           The Debian archive software uses the term "component" internally
331           and in the Release file format to refer to the division of an
332           archive.  The Debian Social Contract simply refers to "areas."
333           This document uses terminology similar to the Social Contract.
334         </footnote> based on their licenses and other restrictions.
335       </p>
336
337       <p>
338         The aims of this are:
339
340         <list compact="compact">
341           <item>to allow us to make as much software available as we can</item>
342           <item>to allow us to encourage everyone to write free software,
343                 and</item>
344           <item>to allow us to make it easy for people to produce
345                 CD-ROMs of our system without violating any licenses,
346                 import/export restrictions, or any other laws.</item>
347         </list>
348       </p>
349
350       <p>
351         The <em>main</em> archive area forms the <em>Debian 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>1. 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>2. 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>3. 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>4. 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>5. 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>6. 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>7. 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>8. 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>9. 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>10. 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 its
574           copyright information 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>.  The additional section <em>debian-installer</em>
694           contains special packages used by the installer and is not used
695           for normal Debian packages.
696         </p>
697
698         <p>
699           For more information about the sections and their definitions,
700           see the <url id="http://packages.debian.org/unstable/"
701                        name="list of sections in unstable">.
702         </p>
703       </sect>
704
705       <sect id="priorities">
706         <heading>Priorities</heading>
707
708         <p>
709           Each package should have a <em>priority</em> value, which is
710           included in the package's <em>control record</em>
711           (see <ref id="f-Priority">).
712           This information is used by the Debian package management tools to
713           separate high-priority packages from less-important packages.
714         </p>
715
716         <p>
717           The following <em>priority levels</em> are recognized by the
718           Debian package management tools.
719           <taglist>
720             <tag><tt>required</tt></tag>
721             <item>
722                 Packages which are necessary for the proper
723                 functioning of the system (usually, this means that
724                 dpkg functionality depends on these packages).
725                 Removing a <tt>required</tt> package may cause your
726                 system to become totally broken and you may not even
727                 be able to use <prgn>dpkg</prgn> to put things back,
728                 so only do so if you know what you are doing.  Systems
729                 with only the <tt>required</tt> packages are probably
730                 unusable, but they do have enough functionality to
731                 allow the sysadmin to boot and install more software.
732             </item>
733             <tag><tt>important</tt></tag>
734             <item>
735                 Important programs, including those which one would
736                 expect to find on any Unix-like system.  If the
737                 expectation is that an experienced Unix person who
738                 found it missing would say "What on earth is going on,
739                 where is <prgn>foo</prgn>?", it must be an
740                 <tt>important</tt> package.<footnote>
741                     This is an important criterion because we are
742                     trying to produce, amongst other things, a free
743                     Unix.
744                 </footnote>
745                 Other packages without which the system will not run
746                 well or be usable must also have priority
747                 <tt>important</tt>.  This does
748                 <em>not</em> include Emacs, the X Window System, TeX
749                 or any other large applications.  The
750                 <tt>important</tt> packages are just a bare minimum of
751                 commonly-expected and necessary tools.
752             </item>
753             <tag><tt>standard</tt></tag>
754             <item>
755                 These packages provide a reasonably small but not too
756                 limited character-mode system.  This is what will be
757                 installed by default if the user doesn't select anything
758                 else.  It doesn't include many large applications.
759             </item>
760             <tag><tt>optional</tt></tag>
761             <item>
762                 (In a sense everything that isn't required is
763                 optional, but that's not what is meant here.) This is
764                 all the software that you might reasonably want to
765                 install if you didn't know what it was and don't have
766                 specialized requirements. This is a much larger system
767                 and includes the X Window System, a full TeX
768                 distribution, and many applications. Note that
769                 optional packages should not conflict with each other.
770             </item>
771             <tag><tt>extra</tt></tag>
772             <item>
773                 This contains all packages that conflict with others
774                 with required, important, standard or optional
775                 priorities, or are only likely to be useful if you
776                 already know what they are or have specialized
777                 requirements (such as packages containing only detached
778                 debugging symbols).
779             </item>
780           </taglist>
781         </p>
782
783         <p>
784           Packages must not depend on packages with lower priority
785           values (excluding build-time dependencies).  In order to
786           ensure this, the priorities of one or more packages may need
787           to be adjusted.
788         </p>
789       </sect>
790
791     </chapt>
792
793
794     <chapt id="binary">
795       <heading>Binary packages</heading>
796
797       <p>
798         The Debian distribution is based on the Debian
799         package management system, called <prgn>dpkg</prgn>. Thus,
800         all packages in the Debian distribution must be provided
801         in the <tt>.deb</tt> file format.
802       </p>
803
804       <p>
805         A <tt>.deb</tt> package contains two sets of files: a set of files
806         to install on the system when the package is installed, and a set
807         of files that provide additional metadata about the package or
808         which are executed when the package is installed or removed.  This
809         second set of files is called <em>control information files</em>.
810         Among those files are the package maintainer scripts
811         and <file>control</file>, the <qref id="binarycontrolfiles">binary
812         package control file</qref> that contains the control fields for
813         the package.  Other control information files
814         include <qref id="sharedlibs-shlibdeps">the <file>shlibs</file>
815         file</qref> used to store shared library dependency information
816         and the <file>conffiles</file> file that lists the package's
817         configuration files (described in <ref id="config-files">).
818       </p>
819
820       <p>
821         There is unfortunately a collision of terminology here between
822         control information files and files in the Debian control file
823         format.  Throughout this document, a <em>control file</em> refers
824         to a file in the Debian control file format.  These files are
825         documented in <ref id="controlfields">.  Only files referred to
826         specifically as <em>control information files</em> are the files
827         included in the control information file member of
828         the <file>.deb</file> file format used by binary packages.  Most
829         control information files are not in the Debian control file
830         format.
831       </p>
832
833       <sect>
834         <heading>The package name</heading>
835
836         <p>
837           Every package must have a name that's unique within the Debian
838           archive.
839         </p>
840
841         <p>
842           The package name is included in the control field
843           <tt>Package</tt>, the format of which is described
844           in <ref id="f-Package">.
845           The package name is also included as a part of the file name
846           of the <tt>.deb</tt> file.
847         </p>
848       </sect>
849
850       <sect id="versions">
851         <heading>The version of a package</heading>
852
853         <p>
854           Every package has a version number recorded in its
855           <tt>Version</tt> control file field, described in
856           <ref id="f-Version">.
857         </p>
858
859         <p>
860           The package management system imposes an ordering on version
861           numbers, so that it can tell whether packages are being up- or
862           downgraded and so that package system front end applications
863           can tell whether a package it finds available is newer than
864           the one installed on the system.  The version number format
865           has the most significant parts (as far as comparison is
866           concerned) at the beginning.
867         </p>
868
869         <p>
870           If an upstream package has problematic version numbers they
871           should be converted to a sane form for use in the
872           <tt>Version</tt> field.
873         </p>
874
875         <sect1>
876           <heading>Version numbers based on dates</heading>
877
878           <p>
879             In general, Debian packages should use the same version
880             numbers as the upstream sources.  However, upstream version
881             numbers based on some date formats (sometimes used for
882             development or "snapshot" releases) will not be ordered
883             correctly by the package management software.  For
884             example, <prgn>dpkg</prgn> will consider "96May01" to be
885             greater than "96Dec24".
886           </p>
887
888           <p>
889             To prevent having to use epochs for every new upstream
890             version, the date-based portion of any upstream version number
891             should be given in a way that sorts correctly: four-digit year
892             first, followed by a two-digit numeric month, followed by a
893             two-digit numeric date, possibly with punctuation between the
894             components.
895           </p>
896
897           <p>
898             Native Debian packages (i.e., packages which have been written
899             especially for Debian) whose version numbers include dates
900             should also follow these rules.  If punctuation is desired
901             between the date components, remember that hyphen (<tt>-</tt>)
902             cannot be used in native package versions.  Period
903             (<tt>.</tt>) is normally a good choice.
904           </p>
905         </sect1>
906
907       </sect>
908
909       <sect id="maintainer">
910         <heading>The maintainer of a package</heading>
911
912         <p>
913           Every package must have a maintainer, except for orphaned
914           packages as described below.  The maintainer may be one person
915           or a group of people reachable from a common email address, such
916           as a mailing list.  The maintainer is responsible for
917           maintaining the Debian packaging files, evaluating and
918           responding appropriately to reported bugs, uploading new
919           versions of the package (either directly or through a sponsor),
920           ensuring that the package is placed in the appropriate archive
921           area and included in Debian releases as appropriate for the
922           stability and utility of the package, and requesting removal of
923           the package from the Debian distribution if it is no longer
924           useful or maintainable.
925         </p>
926
927         <p>
928           The maintainer must be specified in the <tt>Maintainer</tt>
929           control field with their correct name and a working email
930           address.  The email address given in the <tt>Maintainer</tt>
931           control field must accept mail from those role accounts in
932           Debian used to send automated mails regarding the package.  This
933           includes non-spam mail from the bug-tracking system, all mail
934           from the Debian archive maintenance software, and other role
935           accounts or automated processes that are commonly agreed on by
936           the project.<footnote>
937             A sample implementation of such a whitelist written for the
938             Mailman mailing list management software is used for mailing
939             lists hosted by alioth.debian.org.
940           </footnote>
941           If one person or team maintains several packages, they should
942           use the same form of their name and email address in
943           the <tt>Maintainer</tt> fields of those packages.
944         </p>
945
946         <p>
947           The format of the <tt>Maintainer</tt> control field is
948           described in <ref id="f-Maintainer">.
949         </p>
950
951         <p>
952           If the maintainer of the package is a team of people with a
953           shared email address, the <tt>Uploaders</tt> control field must
954           be present and must contain at least one human with their
955           personal email address.  See <ref id="f-Uploaders"> for the
956           syntax of that field.
957         </p>
958
959         <p>
960           An orphaned package is one with no current maintainer.  Orphaned
961           packages should have their <tt>Maintainer</tt> control field set
962           to <tt>Debian QA Group &lt;packages@qa.debian.org&gt;</tt>.
963           These packages are considered maintained by the Debian project
964           as a whole until someone else volunteers to take over
965           maintenance.<footnote>
966             The detailed procedure for gracefully orphaning a package can
967             be found in the Debian Developer's Reference
968             (see <ref id="related">).
969           </footnote>
970         </p>
971       </sect>
972
973       <sect id="descriptions">
974         <heading>The description of a package</heading>
975
976         <p>
977           Every Debian package must have a <tt>Description</tt> control
978           field which contains a synopsis and extended description of the
979           package.  Technical information about the format of the
980           <tt>Description</tt> field is in <ref id="f-Description">.
981         </p>
982
983         <p>
984           The description should describe the package (the program) to a
985           user (system administrator) who has never met it before so that
986           they have enough information to decide whether they want to
987           install it. This description should not just be copied verbatim
988           from the program's documentation.
989         </p>
990
991         <p>
992           Put important information first, both in the synopsis and
993           extended description.  Sometimes only the first part of the
994           synopsis or of the description will be displayed.  You can
995           assume that there will usually be a way to see the whole
996           extended description.
997         </p>
998
999         <p>
1000           The description should also give information about the
1001           significant dependencies and conflicts between this package
1002           and others, so that the user knows why these dependencies and
1003           conflicts have been declared.
1004         </p>
1005
1006         <p>
1007           Instructions for configuring or using the package should
1008           not be included (that is what installation scripts,
1009           manual pages, info files, etc., are for).  Copyright
1010           statements and other administrivia should not be included
1011           either (that is what the copyright file is for).
1012         </p>
1013
1014         <sect1 id="synopsis"><heading>The single line synopsis</heading>
1015
1016           <p>
1017             The single line synopsis should be kept brief - certainly
1018             under 80 characters.
1019           </p>
1020
1021           <p>
1022             Do not include the package name in the synopsis line.  The
1023             display software knows how to display this already, and you
1024             do not need to state it.  Remember that in many situations
1025             the user may only see the synopsis line - make it as
1026             informative as you can.
1027           </p>
1028
1029         </sect1>
1030
1031         <sect1 id="extendeddesc"><heading>The extended description</heading>
1032
1033           <p>
1034             Do not try to continue the single line synopsis into the
1035             extended description.  This will not work correctly when
1036             the full description is displayed, and makes no sense
1037             where only the summary (the single line synopsis) is
1038             available.
1039           </p>
1040
1041           <p>
1042             The extended description should describe what the package
1043             does and how it relates to the rest of the system (in terms
1044             of, for example, which subsystem it is which part of).
1045           </p>
1046
1047           <p>
1048             The description field needs to make sense to anyone, even
1049             people who have no idea about any of the things the
1050             package deals with.<footnote>
1051                 The blurb that comes with a program in its
1052                 announcements and/or <prgn>README</prgn> files is
1053                 rarely suitable for use in a description.  It is
1054                 usually aimed at people who are already in the
1055                 community where the package is used.
1056             </footnote>
1057           </p>
1058
1059         </sect1>
1060
1061       </sect>
1062
1063       <sect>
1064         <heading>Dependencies</heading>
1065
1066         <p>
1067           Every package must specify the dependency information
1068           about other packages that are required for the first to
1069           work correctly.
1070         </p>
1071
1072         <p>
1073           For example, a dependency entry must be provided for any
1074           shared libraries required by a dynamically-linked executable
1075           binary in a package.
1076         </p>
1077
1078         <p>
1079           Packages are not required to declare any dependencies they
1080           have on other packages which are marked <tt>Essential</tt>
1081           (see below), and should not do so unless they depend on a
1082           particular version of that package.<footnote>
1083             <p>
1084               Essential is needed in part to avoid unresolvable dependency
1085               loops on upgrade.  If packages add unnecessary dependencies
1086               on packages in this set, the chances that there
1087               <strong>will</strong> be an unresolvable dependency loop
1088               caused by forcing these Essential packages to be configured
1089               first before they need to be is greatly increased.  It also
1090               increases the chances that frontends will be unable to
1091               <strong>calculate</strong> an upgrade path, even if one
1092               exists.
1093             </p>
1094             <p>
1095               Also, functionality is rarely ever removed from the
1096               Essential set, but <em>packages</em> have been removed from
1097               the Essential set when the functionality moved to a
1098               different package. So depending on these packages <em>just
1099               in case</em> they stop being essential does way more harm
1100               than good.
1101             </p>
1102           </footnote>
1103         </p>
1104
1105         <p>
1106           Sometimes, a package requires another package to be installed
1107           <em>and</em> configured before it can be installed. In this
1108           case, you must specify a <tt>Pre-Depends</tt> entry for
1109           the package.
1110         </p>
1111
1112         <p>
1113           You should not specify a <tt>Pre-Depends</tt> entry for a
1114           package before this has been discussed on the
1115           <tt>debian-devel</tt> mailing list and a consensus about
1116           doing that has been reached.
1117         </p>
1118
1119         <p>
1120           The format of the package interrelationship control fields is
1121           described in <ref id="relationships">.
1122         </p>
1123       </sect>
1124
1125       <sect id="virtual_pkg">
1126         <heading>Virtual packages</heading>
1127
1128         <p>
1129           Sometimes, there are several packages which offer
1130           more-or-less the same functionality. In this case, it's
1131           useful to define a <em>virtual package</em> whose name
1132           describes that common functionality.  (The virtual
1133           packages only exist logically, not physically; that's why
1134           they are called <em>virtual</em>.) The packages with this
1135           particular function will then <em>provide</em> the virtual
1136           package. Thus, any other package requiring that function
1137           can simply depend on the virtual package without having to
1138           specify all possible packages individually.
1139         </p>
1140
1141         <p>
1142           All packages should use virtual package names where
1143           appropriate, and arrange to create new ones if necessary.
1144           They should not use virtual package names (except privately,
1145           amongst a cooperating group of packages) unless they have
1146           been agreed upon and appear in the list of virtual package
1147           names. (See also <ref id="virtual">)
1148         </p>
1149
1150         <p>
1151           The latest version of the authoritative list of virtual
1152           package names can be found in the <tt>debian-policy</tt> package.
1153           It is also available from the Debian web mirrors at
1154           <tt><url name="/doc/packaging-manuals/virtual-package-names-list.txt"
1155                 id="http://www.debian.org/doc/packaging-manuals/virtual-package-names-list.txt"></tt>.
1156         </p>
1157
1158         <p>
1159           The procedure for updating the list is described in the preface
1160           to the list.
1161         </p>
1162
1163       </sect>
1164
1165       <sect>
1166         <heading>Base system</heading>
1167
1168         <p>
1169           The <tt>base system</tt> is a minimum subset of the Debian
1170           system that is installed before everything else
1171           on a new system. Only very few packages are allowed to form
1172           part of the base system, in order to keep the required disk
1173           usage very small.
1174         </p>
1175
1176         <p>
1177           The base system consists of all those packages with priority
1178           <tt>required</tt> or <tt>important</tt>. Many of them will
1179           be tagged <tt>essential</tt> (see below).
1180         </p>
1181       </sect>
1182
1183       <sect>
1184         <heading>Essential packages</heading>
1185
1186         <p>
1187           Essential is defined as the minimal set of functionality that
1188           must be available and usable on the system at all times, even
1189           when packages are in an unconfigured (but unpacked) state.
1190           Packages are tagged <tt>essential</tt> for a system using the
1191           <tt>Essential</tt> control field.  The format of the
1192           <tt>Essential</tt> control field is described in <ref
1193           id="f-Essential">.
1194         </p>
1195
1196         <p>
1197           Since these packages cannot be easily removed (one has to
1198           specify an extra <em>force option</em> to
1199           <prgn>dpkg</prgn> to do so), this flag must not be used
1200           unless absolutely necessary.  A shared library package
1201           must not be tagged <tt>essential</tt>; dependencies will
1202           prevent its premature removal, and we need to be able to
1203           remove it when it has been superseded.
1204         </p>
1205
1206         <p>
1207           Since dpkg will not prevent upgrading of other packages
1208           while an <tt>essential</tt> package is in an unconfigured
1209             state, all <tt>essential</tt> packages must supply all of
1210             their core functionality even when unconfigured. If the
1211             package cannot satisfy this requirement it must not be
1212             tagged as essential, and any packages depending on this
1213             package must instead have explicit dependency fields as
1214             appropriate.
1215         </p>
1216
1217         <p>
1218           Maintainers should take great care in adding any programs,
1219           interfaces, or functionality to <tt>essential</tt> packages.
1220           Packages may assume that functionality provided by
1221           <tt>essential</tt> packages is always available without
1222           declaring explicit dependencies, which means that removing
1223           functionality from the Essential set is very difficult and is
1224           almost never done.  Any capability added to an
1225           <tt>essential</tt> package therefore creates an obligation to
1226           support that capability as part of the Essential set in
1227           perpetuity.
1228         </p>
1229
1230         <p>
1231           You must not tag any packages <tt>essential</tt> before
1232           this has been discussed on the <tt>debian-devel</tt>
1233           mailing list and a consensus about doing that has been
1234           reached.
1235         </p>
1236       </sect>
1237
1238       <sect id="maintscripts">
1239         <heading>Maintainer Scripts</heading>
1240
1241         <p>
1242           The package installation scripts should avoid producing
1243           output which is unnecessary for the user to see and
1244           should rely on <prgn>dpkg</prgn> to stave off boredom on
1245           the part of a user installing many packages.  This means,
1246           amongst other things, using the <tt>--quiet</tt> option on
1247           <prgn>install-info</prgn>.
1248         </p>
1249
1250         <p>
1251           Errors which occur during the execution of an installation
1252           script must be checked and the installation must not
1253           continue after an error.
1254         </p>
1255
1256         <p>
1257           Note that in general <ref id="scripts"> applies to package
1258           maintainer scripts, too.
1259         </p>
1260
1261         <p>
1262           You should not use <prgn>dpkg-divert</prgn> on a file belonging
1263           to another package without consulting the maintainer of that
1264           package first.  When adding or removing diversions, package
1265           maintainer scripts must provide the <tt>--package</tt> flag
1266           to <prgn>dpkg-divert</prgn> and must not use <tt>--local</tt>.
1267         </p>
1268
1269         <p>
1270           All packages which supply an instance of a common command
1271           name (or, in general, filename) should generally use
1272           <prgn>update-alternatives</prgn>, so that they may be
1273           installed together.  If <prgn>update-alternatives</prgn>
1274           is not used, then each package must use
1275           <tt>Conflicts</tt> to ensure that other packages are
1276           de-installed.  (In this case, it may be appropriate to
1277           specify a conflict against earlier versions of something
1278           that previously did not use
1279           <prgn>update-alternatives</prgn>; this is an exception to
1280           the usual rule that versioned conflicts should be
1281           avoided.)
1282         </p>
1283
1284         <sect1 id="maintscriptprompt">
1285           <heading>Prompting in maintainer scripts</heading>
1286           <p>
1287             Package maintainer scripts may prompt the user if
1288             necessary. Prompting must be done by communicating
1289             through a program, such as <prgn>debconf</prgn>, which
1290             conforms to the Debian Configuration Management
1291             Specification, version 2 or higher.
1292           </p>
1293
1294           <p>
1295             Packages which are essential, or which are dependencies of
1296             essential packages, may fall back on another prompting method
1297             if no such interface is available when they are executed.
1298           </p>
1299
1300           <p>
1301             The Debian Configuration Management Specification is included
1302             in the <file>debconf_specification</file> files in the
1303             <package>debian-policy</package> package.
1304             It is also available from the Debian web mirrors at
1305             <tt><url name="/doc/packaging-manuals/debconf_specification.html"
1306                 id="http://www.debian.org/doc/packaging-manuals/debconf_specification.html"></tt>.
1307           </p>
1308
1309           <p>
1310             Packages which use the Debian Configuration Management
1311             Specification may contain the additional control information
1312             files <file>config</file>
1313             and <file>templates</file>.  <file>config</file> is an
1314             additional maintainer script used for package configuration,
1315             and <file>templates</file> contains templates used for user
1316             prompting.  The <prgn>config</prgn> script might be run before
1317             the <prgn>preinst</prgn> script and before the package is
1318             unpacked or any of its dependencies or pre-dependencies are
1319             satisfied.  Therefore it must work using only the tools
1320             present in <em>essential</em> packages.<footnote>
1321                   <package>Debconf</package> or another tool that
1322                   implements the Debian Configuration Management
1323                   Specification will also be installed, and any
1324                   versioned dependencies on it will be satisfied
1325                   before preconfiguration begins.
1326             </footnote>
1327           </p>
1328
1329           <p>
1330             Packages which use the Debian Configuration Management
1331             Specification must allow for translation of their user-visible
1332             messages by using a gettext-based system such as the one
1333             provided by the <package>po-debconf</package> package.
1334           </p>
1335
1336           <p>
1337             Packages should try to minimize the amount of prompting
1338             they need to do, and they should ensure that the user
1339             will only ever be asked each question once.  This means
1340             that packages should try to use appropriate shared
1341             configuration files (such as <file>/etc/papersize</file> and
1342             <file>/etc/news/server</file>), and shared
1343             <package>debconf</package> variables rather than each
1344             prompting for their own list of required pieces of
1345             information.
1346           </p>
1347
1348           <p>
1349             It also means that an upgrade should not ask the same
1350             questions again, unless the user has used
1351             <tt>dpkg --purge</tt> to remove the package's configuration.
1352             The answers to configuration questions should be stored in an
1353             appropriate place in <file>/etc</file> so that the user can
1354             modify them, and how this has been done should be
1355             documented.
1356           </p>
1357
1358           <p>
1359             If a package has a vitally important piece of
1360             information to pass to the user (such as "don't run me
1361             as I am, you must edit the following configuration files
1362             first or you risk your system emitting badly-formatted
1363             messages"), it should display this in the
1364             <prgn>config</prgn> or <prgn>postinst</prgn> script and
1365             prompt the user to hit return to acknowledge the
1366             message.  Copyright messages do not count as vitally
1367             important (they belong in
1368             <file>/usr/share/doc/<var>package</var>/copyright</file>);
1369             neither do instructions on how to use a program (these
1370             should be in on-line documentation, where all the users
1371             can see them).
1372           </p>
1373
1374           <p>
1375             Any necessary prompting should almost always be confined
1376             to the <prgn>config</prgn> or <prgn>postinst</prgn>
1377             script. If it is done in the <prgn>postinst</prgn>, it
1378             should be protected with a conditional so that
1379             unnecessary prompting doesn't happen if a package's
1380             installation fails and the <prgn>postinst</prgn> is
1381             called with <tt>abort-upgrade</tt>,
1382             <tt>abort-remove</tt> or <tt>abort-deconfigure</tt>.
1383           </p>
1384         </sect1>
1385
1386       </sect>
1387
1388     </chapt>
1389
1390
1391     <chapt id="source">
1392       <heading>Source packages</heading>
1393
1394       <sect id="standardsversion">
1395         <heading>Standards conformance</heading>
1396
1397         <p>
1398           Source packages should specify the most recent version number
1399           of this policy document with which your package complied
1400           when it was last updated.
1401         </p>
1402
1403         <p>
1404           This information may be used to file bug reports
1405           automatically if your package becomes too much out of date.
1406         </p>
1407
1408         <p>
1409           The version is specified in the <tt>Standards-Version</tt>
1410           control field.
1411           The format of the <tt>Standards-Version</tt> field is
1412           described in <ref id="f-Standards-Version">.
1413         </p>
1414
1415         <p>
1416           You should regularly, and especially if your package has
1417           become out of date, check for the newest Policy Manual
1418           available and update your package, if necessary. When your
1419           package complies with the new standards you should update the
1420           <tt>Standards-Version</tt> source package field and
1421           release it.<footnote>
1422                 See the file <file>upgrading-checklist</file> for
1423                 information about policy which has changed between
1424                 different versions of this document.
1425           </footnote>
1426         </p>
1427
1428       </sect>
1429
1430       <sect id="pkg-relations">
1431         <heading>Package relationships</heading>
1432
1433         <p>
1434           Source packages should specify which binary packages they
1435           require to be installed or not to be installed in order to
1436           build correctly.  For example, if building a package
1437           requires a certain compiler, then the compiler should be
1438           specified as a build-time dependency.
1439         </p>
1440
1441         <p>
1442           It is not necessary to explicitly specify build-time
1443           relationships on a minimal set of packages that are always
1444           needed to compile, link and put in a Debian package a
1445           standard "Hello World!" program written in C or C++.  The
1446           required packages are called <em>build-essential</em>, and
1447           an informational list can be found in
1448           <file>/usr/share/doc/build-essential/list</file> (which is
1449           contained in the <tt>build-essential</tt>
1450           package).<footnote>
1451             Rationale:
1452                 <list compact="compact">
1453                   <item>
1454                       This allows maintaining the list separately
1455                       from the policy documents (the list does not
1456                       need the kind of control that the policy
1457                       documents do).
1458                   </item>
1459                   <item>
1460                       Having a separate package allows one to install
1461                       the build-essential packages on a machine, as
1462                       well as allowing other packages such as tasks to
1463                       require installation of the build-essential
1464                       packages using the depends relation.
1465                   </item>
1466                   <item>
1467                       The separate package allows bug reports against
1468                       the list to be categorized separately from
1469                       the policy management process in the BTS.
1470                   </item>
1471                 </list>
1472           </footnote>
1473         </p>
1474
1475         <p>
1476           When specifying the set of build-time dependencies, one
1477           should list only those packages explicitly required by the
1478           build.  It is not necessary to list packages which are
1479           required merely because some other package in the list of
1480           build-time dependencies depends on them.<footnote>
1481                 The reason for this is that dependencies change, and
1482                 you should list all those packages, and <em>only</em>
1483                 those packages that <em>you</em> need directly.  What
1484                 others need is their business.  For example, if you
1485                 only link against <file>libimlib</file>, you will need to
1486                 build-depend on <package>libimlib2-dev</package> but
1487                 not against any <tt>libjpeg*</tt> packages, even
1488                 though <tt>libimlib2-dev</tt> currently depends on
1489                 them: installation of <package>libimlib2-dev</package>
1490                 will automatically ensure that all of its run-time
1491                 dependencies are satisfied.
1492           </footnote>
1493         </p>
1494
1495         <p>
1496           If build-time dependencies are specified, it must be
1497           possible to build the package and produce working binaries
1498           on a system with only essential and build-essential
1499           packages installed and also those required to satisfy the
1500           build-time relationships (including any implied
1501           relationships).  In particular, this means that version
1502           clauses should be used rigorously in build-time
1503           relationships so that one cannot produce bad or
1504           inconsistently configured packages when the relationships
1505           are properly satisfied.
1506         </p>
1507
1508         <p>
1509           <ref id="relationships"> explains the technical details.
1510         </p>
1511       </sect>
1512
1513       <sect>
1514         <heading>Changes to the upstream sources</heading>
1515
1516         <p>
1517           If changes to the source code are made that are not
1518           specific to the needs of the Debian system, they should be
1519           sent to the upstream authors in whatever form they prefer
1520           so as to be included in the upstream version of the
1521           package.
1522         </p>
1523
1524         <p>
1525           If you need to configure the package differently for
1526           Debian or for Linux, and the upstream source doesn't
1527           provide a way to do so, you should add such configuration
1528           facilities (for example, a new <prgn>autoconf</prgn> test
1529           or <tt>#define</tt>) and send the patch to the upstream
1530           authors, with the default set to the way they originally
1531           had it.  You can then easily override the default in your
1532           <file>debian/rules</file> or wherever is appropriate.
1533         </p>
1534
1535         <p>
1536           You should make sure that the <prgn>configure</prgn> utility
1537           detects the correct architecture specification string
1538           (refer to <ref id="arch-spec"> for details).
1539         </p>
1540
1541         <p>
1542           If you need to edit a <prgn>Makefile</prgn> where GNU-style
1543           <prgn>configure</prgn> scripts are used, you should edit the
1544           <file>.in</file> files rather than editing the
1545           <prgn>Makefile</prgn> directly.  This allows the user to
1546           reconfigure the package if necessary.  You should
1547           <em>not</em> configure the package and edit the generated
1548           <prgn>Makefile</prgn>!  This makes it impossible for someone
1549           else to later reconfigure the package without losing the
1550           changes you made.
1551         </p>
1552
1553       </sect>
1554
1555       <sect id="dpkgchangelog">
1556         <heading>Debian changelog: <file>debian/changelog</file></heading>
1557
1558         <p>
1559           Changes in the Debian version of the package should be
1560           briefly explained in the Debian changelog file
1561           <file>debian/changelog</file>.<footnote>
1562             <p>
1563               Mistakes in changelogs are usually best rectified by
1564               making a new changelog entry rather than "rewriting
1565               history" by editing old changelog entries.
1566             </p>
1567           </footnote>
1568           This includes modifications
1569           made in the Debian package compared to the upstream one
1570           as well as other changes and updates to the package.
1571           <footnote>
1572               Although there is nothing stopping an author who is also
1573               the Debian maintainer from using this changelog for all
1574               their changes, it will have to be renamed if the Debian
1575               and upstream maintainers become different people. In such
1576               a case, however, it might be better to maintain the package
1577               as a non-native package.
1578           </footnote>
1579         </p>
1580
1581         <p>
1582           The format of the <file>debian/changelog</file> allows the
1583           package building tools to discover which version of the package
1584           is being built and find out other release-specific information.
1585         </p>
1586
1587         <p>
1588           That format is a series of entries like this:
1589
1590 <example compact="compact">
1591 <var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
1592             <var>
1593               [optional blank line(s), stripped]
1594             </var>
1595   * <var>change details</var>
1596     <var>more change details</var>
1597             <var>
1598               [blank line(s), included in output of dpkg-parsechangelog]
1599             </var>
1600   * <var>even more change details</var>
1601             <var>
1602               [optional blank line(s), stripped]
1603             </var>
1604  -- <var>maintainer name</var> &lt;<var>email address</var>&gt;<var>[two spaces]</var>  <var>date</var>
1605 </example>
1606         </p>
1607
1608         <p>
1609           <var>package</var> and <var>version</var> are the source
1610           package name and version number.
1611         </p>
1612
1613         <p>
1614           <var>distribution(s)</var> lists the distributions where
1615           this version should be installed when it is uploaded - it
1616           is copied to the <tt>Distribution</tt> field in the
1617           <file>.changes</file> file.  See <ref id="f-Distribution">.
1618         </p>
1619
1620         <p>
1621           <var>urgency</var> is the value for the <tt>Urgency</tt>
1622           field in the <file>.changes</file> file for the upload
1623           (see <ref id="f-Urgency">). It is not possible to specify
1624           an urgency containing commas; commas are used to separate
1625           <tt><var>keyword</var>=<var>value</var></tt> settings in the
1626           <prgn>dpkg</prgn> changelog format (though there is
1627           currently only one useful <var>keyword</var>,
1628           <tt>urgency</tt>).
1629         </p>
1630
1631         <p>
1632           The change details may in fact be any series of lines
1633           starting with at least two spaces, but conventionally each
1634           change starts with an asterisk and a separating space and
1635           continuation lines are indented so as to bring them in
1636           line with the start of the text above.  Blank lines may be
1637           used here to separate groups of changes, if desired.
1638         </p>
1639
1640         <p>
1641           If this upload resolves bugs recorded in the Bug Tracking
1642           System (BTS), they may be automatically closed on the
1643           inclusion of this package into the Debian archive by
1644           including the string: <tt>closes: Bug#<var>nnnnn</var></tt>
1645           in the change details.<footnote>
1646               To be precise, the string should match the following
1647               Perl regular expression:
1648               <example>
1649 /closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i
1650               </example>
1651               Then all of the bug numbers listed will be closed by the
1652               archive maintenance script (<prgn>katie</prgn>) using the
1653               <var>version</var> of the changelog entry.
1654           </footnote>
1655           This information is conveyed via the <tt>Closes</tt> field
1656           in the <tt>.changes</tt> file (see <ref id="f-Closes">).
1657         </p>
1658
1659         <p>
1660           The maintainer name and email address used in the changelog
1661           should be the details of the person uploading <em>this</em>
1662           version.  They are <em>not</em> necessarily those of the
1663           usual package maintainer.<footnote>
1664             If the developer uploading the package is not one of the usual
1665             maintainers of the package (as listed in
1666             the <qref id="f-Maintainer"><tt>Maintainer</tt></qref>
1667             or <qref id="f-Uploaders"><tt>Uploaders</tt></qref> control
1668             fields of the package), the first line of the changelog is
1669             conventionally used to explain why a non-maintainer is
1670             uploading the package.  The Debian Developer's Reference
1671             (see <ref id="related">) documents the conventions
1672             used.</footnote>
1673           The information here will be copied to the <tt>Changed-By</tt>
1674           field in the <tt>.changes</tt> file
1675           (see <ref id="f-Changed-By">), and then later used to send an
1676           acknowledgement when the upload has been installed.
1677         </p>
1678
1679         <p>
1680           The <var>date</var> has the following format<footnote>
1681               This is the same as the format generated by <tt>date
1682               -R</tt>.
1683           </footnote> (compatible and with the same semantics of
1684           RFC 2822 and RFC 5322):
1685           <example>day-of-week, dd month yyyy hh:mm:ss +zzzz</example>
1686           where:
1687           <list compact="compact">
1688             <item>
1689               day-of week is one of: Mon, Tue, Wed, Thu, Fri, Sat, Sun
1690             </item>
1691             <item>
1692               dd is a one- or two-digit day of the month (01-31)
1693             </item>
1694             <item>
1695               month is one of: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug,
1696               Sep, Oct, Nov, Dec
1697             </item>
1698             <item>yyyy is the four-digit year (e.g. 2010)</item>
1699             <item>hh is the two-digit hour (00-23)</item>
1700             <item>mm is the two-digit minutes (00-59)</item>
1701             <item>ss is the two-digit seconds (00-60)</item>
1702             <item>
1703               +zzzz or -zzzz is the the time zone offset from Coordinated
1704               Universal Time (UTC).  "+" indicates that the time is ahead
1705               of (i.e., east of) UTC and "-" indicates that the time is
1706               behind (i.e., west of) UTC.  The first two digits indicate
1707               the hour difference from UTC and the last two digits
1708               indicate the number of additional minutes difference from
1709               UTC.  The last two digits must be in the range 00-59.
1710             </item>
1711           </list>
1712         </p>
1713
1714         <p>
1715           The first "title" line with the package name must start
1716           at the left hand margin.  The "trailer" line with the
1717           maintainer and date details must be preceded by exactly
1718           one space.  The maintainer details and the date must be
1719           separated by exactly two spaces.
1720         </p>
1721
1722         <p>
1723           The entire changelog must be encoded in UTF-8.
1724         </p>
1725
1726         <p>
1727           For more information on placement of the changelog files
1728           within binary packages, please see <ref id="changelogs">.
1729         </p>
1730       </sect>
1731
1732       <sect id="dpkgcopyright">
1733         <heading>Copyright: <file>debian/copyright</file></heading>
1734         <p>
1735           Every package must be accompanied by a verbatim copy of its
1736           copyright information and distribution license in the file
1737           <file>/usr/share/doc/<var>package</var>/copyright</file>
1738           (see <ref id="copyrightfile"> for further details). Also see
1739           <ref id="pkgcopyright"> for further considerations related
1740           to copyrights for packages.
1741         </p>
1742       </sect>
1743       <sect>
1744         <heading>Error trapping in makefiles</heading>
1745
1746         <p>
1747           When <prgn>make</prgn> invokes a command in a makefile
1748           (including your package's upstream makefiles and
1749           <file>debian/rules</file>), it does so using <prgn>sh</prgn>.  This
1750           means that <prgn>sh</prgn>'s usual bad error handling
1751           properties apply: if you include a miniature script as one
1752           of the commands in your makefile you'll find that if you
1753           don't do anything about it then errors are not detected
1754           and <prgn>make</prgn> will blithely continue after
1755           problems.
1756         </p>
1757
1758         <p>
1759           Every time you put more than one shell command (this
1760           includes using a loop) in a makefile command you
1761           must make sure that errors are trapped.  For
1762           simple compound commands, such as changing directory and
1763           then running a program, using <tt>&amp;&amp;</tt> rather
1764           than semicolon as a command separator is sufficient.  For
1765           more complex commands including most loops and
1766           conditionals you should include a separate <tt>set -e</tt>
1767           command at the start of every makefile command that's
1768           actually one of these miniature shell scripts.
1769         </p>
1770       </sect>
1771
1772       <sect id="timestamps">
1773         <heading>Time Stamps</heading>
1774         <p>
1775           Maintainers should preserve the modification times of the
1776           upstream source files in a package, as far as is reasonably
1777           possible.<footnote>
1778               The rationale is that there is some information conveyed
1779               by knowing the age of the file, for example, you could
1780               recognize that some documentation is very old by looking
1781               at the modification time, so it would be nice if the
1782               modification time of the upstream source would be
1783               preserved.
1784           </footnote>
1785         </p>
1786       </sect>
1787
1788       <sect id="restrictions">
1789         <heading>Restrictions on objects in source packages</heading>
1790
1791         <p>
1792           The source package may not contain any hard links<footnote>
1793             <p>
1794               This is not currently detected when building source
1795               packages, but only when extracting
1796               them.
1797             </p>
1798             <p>
1799               Hard links may be permitted at some point in the
1800               future, but would require a fair amount of
1801               work.
1802             </p>
1803           </footnote>, device special files, sockets or setuid or
1804           setgid files.<footnote>
1805               Setgid directories are allowed.
1806           </footnote>
1807         </p>
1808       </sect>
1809
1810       <sect id="debianrules">
1811         <heading>Main building script: <file>debian/rules</file></heading>
1812
1813         <p>
1814           This file must be an executable makefile, and contains the
1815           package-specific recipes for compiling the package and
1816           building binary package(s) from the source.
1817         </p>
1818
1819         <p>
1820           It must start with the line <tt>#!/usr/bin/make -f</tt>,
1821           so that it can be invoked by saying its name rather than
1822           invoking <prgn>make</prgn> explicitly. That is, invoking
1823           either of <tt>make -f debian/rules <em>args...</em></tt>
1824           or <tt>./debian/rules <em>args...</em></tt> must result in
1825           identical behavior.
1826         </p>
1827
1828         <p>
1829           The following targets are required and must be implemented
1830           by <file>debian/rules</file>: <tt>clean</tt>, <tt>binary</tt>,
1831           <tt>binary-arch</tt>, <tt>binary-indep</tt>, and <tt>build</tt>.
1832           These are the targets called by <prgn>dpkg-buildpackage</prgn>.
1833         </p>
1834
1835         <p>
1836           Since an interactive <file>debian/rules</file> script makes it
1837           impossible to auto-compile that package and also makes it hard
1838           for other people to reproduce the same binary package, all
1839           required targets must be non-interactive.  It also follows that
1840           any target that these targets depend on must also be
1841           non-interactive.
1842         </p>
1843
1844         <p>
1845           The targets are as follows:
1846           <taglist>
1847             <tag><tt>build</tt> (required)</tag>
1848             <item>
1849               <p>
1850                 The <tt>build</tt> target should perform all the
1851                 configuration and compilation of the package.
1852                 If a package has an interactive pre-build
1853                 configuration routine, the Debian source package
1854                 must either be built after this has taken place (so
1855                 that the binary package can be built without rerunning
1856                 the configuration) or the configuration routine
1857                 modified to become non-interactive.  (The latter is
1858                 preferable if there are architecture-specific features
1859                 detected by the configuration routine.)
1860               </p>
1861
1862               <p>
1863                 For some packages, notably ones where the same
1864                 source tree is compiled in different ways to produce
1865                 two binary packages, the <tt>build</tt> target
1866                 does not make much sense.  For these packages it is
1867                 good enough to provide two (or more) targets
1868                 (<tt>build-a</tt> and <tt>build-b</tt> or whatever)
1869                 for each of the ways of building the package, and a
1870                 <tt>build</tt> target that does nothing.  The
1871                 <tt>binary</tt> target will have to build the
1872                 package in each of the possible ways and make the
1873                 binary package out of each.
1874               </p>
1875
1876               <p>
1877                 The <tt>build</tt> target must not do anything
1878                 that might require root privilege.
1879               </p>
1880
1881               <p>
1882                 The <tt>build</tt> target may need to run the
1883                 <tt>clean</tt> target first - see below.
1884               </p>
1885
1886               <p>
1887                 When a package has a configuration and build routine
1888                 which takes a long time, or when the makefiles are
1889                 poorly designed, or when <tt>build</tt> needs to
1890                 run <tt>clean</tt> first, it is a good idea to
1891                 <tt>touch build</tt> when the build process is
1892                 complete.  This will ensure that if <tt>debian/rules
1893                 build</tt> is run again it will not rebuild the whole
1894                 program.<footnote>
1895                     Another common way to do this is for <tt>build</tt>
1896                     to depend on <prgn>build-stamp</prgn> and to do
1897                     nothing else, and for the <prgn>build-stamp</prgn>
1898                     target to do the building and to <tt>touch
1899                     build-stamp</tt> on completion.  This is
1900                     especially useful if the build routine creates a
1901                     file or directory called <tt>build</tt>; in such a
1902                     case, <tt>build</tt> will need to be listed as
1903                     a phony target (i.e., as a dependency of the
1904                     <tt>.PHONY</tt> target).  See the documentation of
1905                     <prgn>make</prgn> for more information on phony
1906                     targets.
1907                 </footnote>
1908               </p>
1909             </item>
1910
1911             <tag><tt>build-arch</tt> (optional),
1912                  <tt>build-indep</tt> (optional)
1913             </tag>
1914             <item>
1915               <p>
1916                 A package may also provide both of the targets
1917                 <tt>build-arch</tt> and <tt>build-indep</tt>.
1918                 The <tt>build-arch</tt> target, if provided, should
1919                 perform all the configuration and compilation required for
1920                 producing all architecture-dependant binary packages
1921                 (those packages for which the body of the
1922                 <tt>Architecture</tt> field in <tt>debian/control</tt> is
1923                 not <tt>all</tt>).  Similarly, the <tt>build-indep</tt>
1924                 target, if provided, should perform all the configuration
1925                 and compilation required for producing all
1926                 architecture-independent binary packages (those packages
1927                 for which the body of the <tt>Architecture</tt> field
1928                 in <tt>debian/control</tt> is <tt>all</tt>).
1929                 The <tt>build</tt> target should depend on those of the
1930                 targets <tt>build-arch</tt> and <tt>build-indep</tt> that
1931                 are provided in the rules file.<footnote>
1932                   The intent of this split is so that binary-only builds
1933                   need not install the dependencies required for
1934                   the <tt>build-indep</tt> target.  However, this is not
1935                   yet used in practice since <tt>dpkg-buildpackage
1936                   -B</tt>, and therefore the autobuilders,
1937                   invoke <tt>build</tt> rather than <tt>build-arch</tt>
1938                   due to the difficulties in determining whether the
1939                   optional <tt>build-arch</tt> target exists.
1940                 </footnote>
1941               </p>
1942
1943               <p>
1944                 If one or both of the targets <tt>build-arch</tt> and
1945                 <tt>build-indep</tt> are not provided, then invoking
1946                 <file>debian/rules</file> with one of the not-provided
1947                 targets as arguments should produce a exit status code
1948                 of 2.  Usually this is provided automatically by make
1949                 if the target is missing.
1950               </p>
1951
1952               <p>
1953                 The <tt>build-arch</tt> and <tt>build-indep</tt> targets
1954                 must not do anything that might require root privilege.
1955               </p>
1956             </item>
1957
1958             <tag><tt>binary</tt> (required), <tt>binary-arch</tt>
1959               (required), <tt>binary-indep</tt> (required)
1960             </tag>
1961             <item>
1962               <p>
1963                 The <tt>binary</tt> target must be all that is
1964                 necessary for the user to build the binary package(s)
1965                 produced from this source package.  It is
1966                 split into two parts: <prgn>binary-arch</prgn> builds
1967                 the binary packages which are specific to a particular
1968                 architecture, and <tt>binary-indep</tt> builds
1969                 those which are not.
1970               </p>
1971               <p>
1972                 <tt>binary</tt> may be (and commonly is) a target with
1973                 no commands which simply depends on
1974                 <tt>binary-arch</tt> and <tt>binary-indep</tt>.
1975               </p>
1976               <p>
1977                 Both <tt>binary-*</tt> targets should depend on the
1978                 <tt>build</tt> target, or on the appropriate
1979                 <tt>build-arch</tt> or <tt>build-indep</tt> target, if
1980                 provided, so that the package is built if it has not
1981                 been already.  It should then create the relevant
1982                 binary package(s), using <prgn>dpkg-gencontrol</prgn> to
1983                 make their control files and <prgn>dpkg-deb</prgn> to
1984                 build them and place them in the parent of the top
1985                 level directory.
1986               </p>
1987
1988               <p>
1989                 Both the <tt>binary-arch</tt> and
1990                 <tt>binary-indep</tt> targets <em>must</em> exist.
1991                 If one of them has nothing to do (which will always be
1992                 the case if the source generates only a single binary
1993                 package, whether architecture-dependent or not), it
1994                 must still exist and must always succeed.
1995               </p>
1996
1997               <p>
1998                 The <tt>binary</tt> targets must be invoked as
1999                 root.<footnote>
2000                     The <prgn>fakeroot</prgn> package often allows one
2001                     to build a package correctly even without being
2002                     root.
2003                 </footnote>
2004               </p>
2005             </item>
2006
2007             <tag><tt>clean</tt> (required)</tag>
2008             <item>
2009               <p>
2010                 This must undo any effects that the <tt>build</tt>
2011                 and <tt>binary</tt> targets may have had, except
2012                 that it should leave alone any output files created in
2013                 the parent directory by a run of a <tt>binary</tt>
2014                 target.
2015               </p>
2016
2017               <p>
2018                 If a <tt>build</tt> file is touched at the end of
2019                 the <tt>build</tt> target, as suggested above, it
2020                 should be removed as the first action that
2021                 <tt>clean</tt> performs, so that running
2022                 <tt>build</tt> again after an interrupted
2023                 <tt>clean</tt> doesn't think that everything is
2024                 already done.
2025               </p>
2026
2027               <p>
2028                 The <tt>clean</tt> target may need to be
2029                 invoked as root if <tt>binary</tt> has been
2030                 invoked since the last <tt>clean</tt>, or if
2031                 <tt>build</tt> has been invoked as root (since
2032                 <tt>build</tt> may create directories, for
2033                 example).
2034               </p>
2035             </item>
2036
2037             <tag><tt>get-orig-source</tt> (optional)</tag>
2038             <item>
2039               <p>
2040                 This target fetches the most recent version of the
2041                 original source package from a canonical archive site
2042                 (via FTP or WWW, for example), does any necessary
2043                 rearrangement to turn it into the original source
2044                 tar file format described below, and leaves it in the
2045                 current directory.
2046               </p>
2047
2048               <p>
2049                 This target may be invoked in any directory, and
2050                 should take care to clean up any temporary files it
2051                 may have left.
2052               </p>
2053
2054               <p>
2055                 This target is optional, but providing it if
2056                 possible is a good idea.
2057               </p>
2058             </item>
2059
2060             <tag><tt>patch</tt> (optional)</tag>
2061             <item>
2062               <p>
2063                 This target performs whatever additional actions are
2064                 required to make the source ready for editing (unpacking
2065                 additional upstream archives, applying patches, etc.).
2066                 It is recommended to be implemented for any package where
2067                 <tt>dpkg-source -x</tt> does not result in source ready
2068                 for additional modification.  See
2069                 <ref id="readmesource">.
2070               </p>
2071             </item>
2072           </taglist>
2073
2074         <p>
2075           The <tt>build</tt>, <tt>binary</tt> and
2076           <tt>clean</tt> targets must be invoked with the current
2077           directory being the package's top-level directory.
2078         </p>
2079
2080
2081         <p>
2082           Additional targets may exist in <file>debian/rules</file>,
2083           either as published or undocumented interfaces or for the
2084           package's internal use.
2085         </p>
2086
2087         <p>
2088           The architectures we build on and build for are determined
2089           by <prgn>make</prgn> variables using the
2090           utility <qref id="pkg-dpkg-architecture"><prgn>dpkg-architecture</prgn></qref>.
2091           You can determine the Debian architecture and the GNU style
2092           architecture specification string for the build architecture as
2093           well as for the host architecture.  The build architecture is
2094           the architecture on which <file>debian/rules</file> is run and
2095           the package build is performed.  The host architecture is the
2096           architecture on which the resulting package will be installed
2097           and run.  These are normally the same, but may be different in
2098           the case of cross-compilation (building packages for one
2099           architecture on machines of a different architecture).
2100         </p>
2101
2102         <p>
2103           Here is a list of supported <prgn>make</prgn> variables:
2104           <list compact="compact">
2105             <item>
2106                 <tt>DEB_*_ARCH</tt> (the Debian architecture)
2107             </item>
2108             <item>
2109                 <tt>DEB_*_ARCH_CPU</tt> (the Debian CPU name)
2110             </item>
2111             <item>
2112                 <tt>DEB_*_ARCH_OS</tt> (the Debian System name)
2113             </item>
2114             <item>
2115                 <tt>DEB_*_GNU_TYPE</tt> (the GNU style architecture
2116                 specification string)
2117             </item>
2118             <item>
2119                 <tt>DEB_*_GNU_CPU</tt> (the CPU part of
2120                 <tt>DEB_*_GNU_TYPE</tt>)
2121             </item>
2122             <item>
2123                 <tt>DEB_*_GNU_SYSTEM</tt> (the System part of
2124                 <tt>DEB_*_GNU_TYPE</tt>)
2125           </list>
2126           where <tt>*</tt> is either <tt>BUILD</tt> for specification of
2127           the build architecture or <tt>HOST</tt> for specification of the
2128           host architecture.
2129         </p>
2130
2131         <p>
2132           Backward compatibility can be provided in the rules file
2133           by setting the needed variables to suitable default
2134           values; please refer to the documentation of
2135           <prgn>dpkg-architecture</prgn> for details.
2136         </p>
2137
2138         <p>
2139           It is important to understand that the <tt>DEB_*_ARCH</tt>
2140           string only determines which Debian architecture we are
2141           building on or for. It should not be used to get the CPU
2142           or system information; the <tt>DEB_*_ARCH_CPU</tt> and
2143           <tt>DEB_*_ARCH_OS</tt> variables should be used for that.
2144           GNU style variables should generally only be used with upstream
2145           build systems.
2146         </p>
2147
2148         <sect1 id="debianrules-options">
2149           <heading><file>debian/rules</file> and
2150             <tt>DEB_BUILD_OPTIONS</tt></heading>
2151
2152           <p>
2153             Supporting the standardized environment variable
2154             <tt>DEB_BUILD_OPTIONS</tt> is recommended.  This variable can
2155             contain several flags to change how a package is compiled and
2156             built.  Each flag must be in the form <var>flag</var> or
2157             <var>flag</var>=<var>options</var>.  If multiple flags are
2158             given, they must be separated by whitespace.<footnote>
2159               Some packages support any delimiter, but whitespace is the
2160               easiest to parse inside a makefile and avoids ambiguity with
2161               flag values that contain commas.
2162             </footnote>
2163             <var>flag</var> must start with a lowercase letter
2164             (<tt>a-z</tt>) and consist only of lowercase letters,
2165             numbers (<tt>0-9</tt>), and the characters
2166             <tt>-</tt> and <tt>_</tt> (hyphen and underscore).
2167             <var>options</var> must not contain whitespace.  The same
2168             tag should not be given multiple times with conflicting
2169             values.  Package maintainers may assume that
2170             <tt>DEB_BUILD_OPTIONS</tt> will not contain conflicting tags.
2171           </p>
2172
2173           <p>
2174             The meaning of the following tags has been standardized:
2175             <taglist>
2176               <tag>nocheck</tag>
2177               <item>
2178                   This tag says to not run any build-time test suite
2179                   provided by the package.
2180               </item>
2181               <tag>noopt</tag>
2182               <item>
2183                   The presence of this tag means that the package should
2184                   be compiled with a minimum of optimization.  For C
2185                   programs, it is best to add <tt>-O0</tt> to
2186                   <tt>CFLAGS</tt> (although this is usually the default).
2187                   Some programs might fail to build or run at this level
2188                   of optimization; it may be necessary to use
2189                   <tt>-O1</tt>, for example.
2190               </item>
2191               <tag>nostrip</tag>
2192               <item>
2193                   This tag means that the debugging symbols should not be
2194                   stripped from the binary during installation, so that
2195                   debugging information may be included in the package.
2196               </item>
2197               <tag>parallel=n</tag>
2198               <item>
2199                   This tag means that the package should be built using up
2200                   to <tt>n</tt> parallel processes if the package build
2201                   system supports this.<footnote>
2202                       Packages built with <tt>make</tt> can often implement
2203                       this by passing the <tt>-j</tt><var>n</var> option to
2204                       <tt>make</tt>.
2205                   </footnote>
2206                   If the package build system does not support parallel
2207                   builds, this string must be ignored.  If the package
2208                   build system only supports a lower level of concurrency
2209                   than <var>n</var>, the package should be built using as
2210                   many parallel processes as the package build system
2211                   supports.  It is up to the package maintainer to decide
2212                   whether the package build times are long enough and the
2213                   package build system is robust enough to make supporting
2214                   parallel builds worthwhile.
2215                </item>
2216             </taglist>
2217           </p>
2218
2219           <p>
2220             Unknown flags must be ignored by <file>debian/rules</file>.
2221           </p>
2222
2223           <p>
2224             The following makefile snippet is an example of how one may
2225             implement the build options; you will probably have to
2226             massage this example in order to make it work for your
2227             package.
2228             <example compact="compact">
2229 CFLAGS = -Wall -g
2230 INSTALL = install
2231 INSTALL_FILE    = $(INSTALL) -p    -o root -g root  -m  644
2232 INSTALL_PROGRAM = $(INSTALL) -p    -o root -g root  -m  755
2233 INSTALL_SCRIPT  = $(INSTALL) -p    -o root -g root  -m  755
2234 INSTALL_DIR     = $(INSTALL) -p -d -o root -g root  -m  755
2235
2236 ifneq (,$(filter noopt,$(DEB_BUILD_OPTIONS)))
2237     CFLAGS += -O0
2238 else
2239     CFLAGS += -O2
2240 endif
2241 ifeq (,$(filter nostrip,$(DEB_BUILD_OPTIONS)))
2242     INSTALL_PROGRAM += -s
2243 endif
2244 ifneq (,$(filter parallel=%,$(DEB_BUILD_OPTIONS)))
2245     NUMJOBS = $(patsubst parallel=%,%,$(filter parallel=%,$(DEB_BUILD_OPTIONS)))
2246     MAKEFLAGS += -j$(NUMJOBS)
2247 endif
2248
2249 build:
2250         # ...
2251 ifeq (,$(filter nocheck,$(DEB_BUILD_OPTIONS)))
2252         # Code to run the package test suite.
2253 endif
2254             </example>
2255           </p>
2256         </sect1>
2257       </sect>
2258
2259 <!-- FIXME: section pkg-srcsubstvars is the same as substvars -->
2260       <sect id="substvars">
2261         <heading>Variable substitutions: <file>debian/substvars</file></heading>
2262
2263         <p>
2264           When <prgn>dpkg-gencontrol</prgn>
2265           generates <qref id="binarycontrolfiles">binary package control
2266           files</qref> (<file>DEBIAN/control</file>), it performs variable
2267           substitutions on its output just before writing it.  Variable
2268           substitutions have the form <tt>${<var>variable</var>}</tt>.
2269           The optional file <file>debian/substvars</file> contains
2270           variable substitutions to be used; variables can also be set
2271           directly from <file>debian/rules</file> using the <tt>-V</tt>
2272           option to the source packaging commands, and certain predefined
2273           variables are also available.
2274         </p>
2275
2276         <p>
2277           The <file>debian/substvars</file> file is usually generated and
2278           modified dynamically by <file>debian/rules</file> targets, in
2279           which case it must be removed by the <tt>clean</tt> target.
2280         </p>
2281
2282         <p>
2283           See <manref name="deb-substvars" section="5"> for full
2284           details about source variable substitutions, including the
2285           format of <file>debian/substvars</file>.</p>
2286       </sect>
2287
2288       <sect id="debianwatch">
2289         <heading>Optional upstream source location: <file>debian/watch</file></heading>
2290
2291         <p>
2292           This is an optional, recommended configuration file for the
2293           <tt>uscan</tt> utility which defines how to automatically scan
2294           ftp or http sites for newly available updates of the
2295           package. This is used
2296           by <url id="http://dehs.alioth.debian.org/"> and other Debian QA
2297           tools to help with quality control and maintenance of the
2298           distribution as a whole.
2299         </p>
2300
2301       </sect>
2302
2303       <sect id="debianfiles">
2304         <heading>Generated files list: <file>debian/files</file></heading>
2305
2306         <p>
2307           This file is not a permanent part of the source tree; it
2308           is used while building packages to record which files are
2309           being generated.  <prgn>dpkg-genchanges</prgn> uses it
2310           when it generates a <file>.changes</file> file.
2311         </p>
2312
2313         <p>
2314           It should not exist in a shipped source package, and so it
2315           (and any backup files or temporary files such as
2316           <file>files.new</file><footnote>
2317               <file>files.new</file> is used as a temporary file by
2318               <prgn>dpkg-gencontrol</prgn> and
2319               <prgn>dpkg-distaddfile</prgn> - they write a new
2320               version of <tt>files</tt> here before renaming it,
2321               to avoid leaving a corrupted copy if an error
2322               occurs.
2323           </footnote>) should be removed by the
2324           <tt>clean</tt> target.  It may also be wise to
2325           ensure a fresh start by emptying or removing it at the
2326           start of the <tt>binary</tt> target.
2327         </p>
2328
2329         <p>
2330           When <prgn>dpkg-gencontrol</prgn> is run for a binary
2331           package, it adds an entry to <file>debian/files</file> for the
2332           <file>.deb</file> file that will be created when <tt>dpkg-deb
2333           --build</tt> is run for that binary package.  So for most
2334           packages all that needs to be done with this file is to
2335           delete it in the <tt>clean</tt> target.
2336         </p>
2337
2338         <p>
2339           If a package upload includes files besides the source
2340           package and any binary packages whose control files were
2341           made with <prgn>dpkg-gencontrol</prgn> then they should be
2342           placed in the parent of the package's top-level directory
2343           and <prgn>dpkg-distaddfile</prgn> should be called to add
2344           the file to the list in <file>debian/files</file>.</p>
2345       </sect>
2346
2347       <sect id="embeddedfiles">
2348         <heading>Convenience copies of code</heading>
2349
2350         <p>
2351           Some software packages include in their distribution convenience
2352           copies of code from other software packages, generally so that
2353           users compiling from source don't have to download multiple
2354           packages.  Debian packages should not make use of these
2355           convenience copies unless the included package is explicitly
2356           intended to be used in this way.<footnote>
2357             For example, parts of the GNU build system work like this.
2358           </footnote>
2359           If the included code is already in the Debian archive in the
2360           form of a library, the Debian packaging should ensure that
2361           binary packages reference the libraries already in Debian and
2362           the convenience copy is not used.  If the included code is not
2363           already in Debian, it should be packaged separately as a
2364           prerequisite if possible.
2365           <footnote>
2366             Having multiple copies of the same code in Debian is
2367             inefficient, often creates either static linking or shared
2368             library conflicts, and, most importantly, increases the
2369             difficulty of handling security vulnerabilities in the
2370             duplicated code.
2371           </footnote>
2372         </p>
2373       </sect>
2374
2375       <sect id="readmesource">
2376         <heading>Source package handling:
2377           <file>debian/README.source</file></heading>
2378
2379         <p>
2380           If running <prgn>dpkg-source -x</prgn> on a source package
2381           doesn't produce the source of the package, ready for editing,
2382           and allow one to make changes and run
2383           <prgn>dpkg-buildpackage</prgn> to produce a modified package
2384           without taking any additional steps, creating a
2385           <file>debian/README.source</file> documentation file is
2386           recommended.  This file should explain how to do all of the
2387           following:
2388             <enumlist>
2389               <item>Generate the fully patched source, in a form ready for
2390               editing, that would be built to create Debian
2391               packages.  Doing this with a <tt>patch</tt> target in
2392               <file>debian/rules</file> is recommended; see
2393               <ref id="debianrules">.</item>
2394               <item>Modify the source and save those modifications so that
2395               they will be applied when building the package.</item>
2396               <item>Remove source modifications that are currently being
2397               applied when building the package.</item>
2398               <item>Optionally, document what steps are necessary to
2399               upgrade the Debian source package to a new upstream version,
2400               if applicable.</item>
2401             </enumlist>
2402           This explanation should include specific commands and mention
2403           any additional required Debian packages.  It should not assume
2404           familiarity with any specific Debian packaging system or patch
2405           management tools.
2406         </p>
2407
2408         <p>
2409           This explanation may refer to a documentation file installed by
2410           one of the package's build dependencies provided that the
2411           referenced documentation clearly explains these tasks and is not
2412           a general reference manual.
2413         </p>
2414
2415         <p>
2416           <file>debian/README.source</file> may also include any other
2417           information that would be helpful to someone modifying the
2418           source package.  Even if the package doesn't fit the above
2419           description, maintainers are encouraged to document in a
2420           <file>debian/README.source</file> file any source package with a
2421           particularly complex or unintuitive source layout or build
2422           system (for example, a package that builds the same source
2423           multiple times to generate different binary packages).
2424         </p>
2425       </sect>
2426     </chapt>
2427
2428
2429     <chapt id="controlfields">
2430       <heading>Control files and their fields</heading>
2431
2432       <p>
2433         The package management system manipulates data represented in
2434         a common format, known as <em>control data</em>, stored in
2435         <em>control files</em>.
2436         Control files are used for source packages, binary packages and
2437         the <file>.changes</file> files which control the installation
2438         of uploaded files<footnote>
2439             <prgn>dpkg</prgn>'s internal databases are in a similar
2440             format.
2441         </footnote>.
2442       </p>
2443
2444       <sect id="controlsyntax">
2445         <heading>Syntax of control files</heading>
2446
2447         <p>
2448           A control file consists of one or more paragraphs of
2449           fields<footnote>
2450                 The paragraphs are also sometimes referred to as stanzas.
2451           </footnote>.
2452           The paragraphs are separated by blank lines.  Some control
2453           files allow only one paragraph; others allow several, in
2454           which case each paragraph usually refers to a different
2455           package.  (For example, in source packages, the first
2456           paragraph refers to the source package, and later paragraphs
2457           refer to binary packages generated from the source.)
2458         </p>
2459
2460         <p>
2461           Each paragraph consists of a series of data fields; each
2462           field consists of the field name, followed by a colon and
2463           then the data/value associated with that field.  It ends at
2464           the end of the (logical) line.  Horizontal whitespace
2465           (spaces and tabs) may occur immediately before or after the
2466           value and is ignored there; it is conventional to put a
2467           single space after the colon.  For example, a field might
2468           be:
2469           <example compact="compact">
2470 Package: libc6
2471           </example>
2472           the field name is <tt>Package</tt> and the field value
2473           <tt>libc6</tt>.
2474         </p>
2475
2476         <p>
2477           A paragraph must not contain more than one instance of a
2478           particular field name.
2479         </p>
2480
2481         <p>
2482           Many fields' values may span several lines; in this case
2483           each continuation line must start with a space or a tab.
2484           Any trailing spaces or tabs at the end of individual
2485           lines of a field value are ignored. 
2486         </p>
2487
2488         <p>
2489           In fields where it is specified that lines may not wrap,
2490           only a single line of data is allowed and whitespace is not
2491           significant in a field body. Whitespace must not appear
2492           inside names (of packages, architectures, files or anything
2493           else) or version numbers, or between the characters of
2494           multi-character version relationships.
2495         </p>
2496
2497         <p>
2498           Field names are not case-sensitive, but it is usual to
2499           capitalize the field names using mixed case as shown below.
2500           Field values are case-sensitive unless the description of the
2501           field says otherwise.
2502         </p>
2503
2504         <p>
2505           Blank lines, or lines consisting only of spaces and tabs,
2506           are not allowed within field values or between fields - that
2507           would mean a new paragraph.
2508         </p>
2509
2510         <p>
2511           All control files must be encoded in UTF-8.
2512         </p>
2513       </sect>
2514
2515       <sect id="sourcecontrolfiles">
2516         <heading>Source package control files -- <file>debian/control</file></heading>
2517
2518         <p>
2519           The <file>debian/control</file> file contains the most vital
2520           (and version-independent) information about the source package
2521           and about the binary packages it creates.
2522         </p>
2523
2524         <p>
2525           The first paragraph of the control file contains information about
2526           the source package in general. The subsequent sets each describe a
2527           binary package that the source tree builds.
2528         </p>
2529
2530         <p>
2531           The fields in the general paragraph (the first one, for the source
2532           package) are:
2533
2534           <list compact="compact">
2535             <item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
2536             <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
2537             <item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
2538             <item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
2539             <item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
2540             <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
2541             <item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
2542             <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
2543           </list>
2544         </p>
2545
2546         <p>
2547           The fields in the binary package paragraphs are:
2548
2549           <list compact="compact">
2550             <item><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</item>
2551             <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (mandatory)</item>
2552             <item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
2553             <item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
2554             <item><qref id="f-Essential"><tt>Essential</tt></qref></item>
2555             <item><qref id="binarydeps"><tt>Depends</tt> et al</qref></item>
2556             <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
2557             <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
2558           </list>
2559         </p>
2560
2561         <p>
2562           The syntax and semantics of the fields are described below.
2563         </p>
2564
2565         <p>
2566           These fields are used by <prgn>dpkg-gencontrol</prgn> to
2567           generate control files for binary packages (see below), by
2568           <prgn>dpkg-genchanges</prgn> to generate the
2569           <file>.changes</file> file to accompany the upload, and by
2570           <prgn>dpkg-source</prgn> when it creates the
2571           <file>.dsc</file> source control file as part of a source
2572           archive. Many fields are permitted to span multiple lines in
2573           <file>debian/control</file> but not in any other control
2574           file. These tools are responsible for removing the line
2575           breaks from such fields when using fields from
2576           <file>debian/control</file> to generate other control files.
2577         </p>
2578
2579         <p>
2580           The fields here may contain variable references - their
2581           values will be substituted by <prgn>dpkg-gencontrol</prgn>,
2582           <prgn>dpkg-genchanges</prgn> or <prgn>dpkg-source</prgn>
2583           when they generate output control files.
2584           See <ref id="substvars"> for details.
2585         </p>
2586
2587         <p>
2588           In addition to the control file syntax described <qref
2589           id="controlsyntax">above</qref>, this file may also contain
2590           comment lines starting with <tt>#</tt> without any preceding
2591           whitespace.  All such lines are ignored, even in the middle of
2592           continuation lines for a multiline field, and do not end a
2593           multiline field.
2594         </p>
2595
2596       </sect>
2597
2598       <sect id="binarycontrolfiles">
2599         <heading>Binary package control files -- <file>DEBIAN/control</file></heading>
2600
2601         <p>
2602           The <file>DEBIAN/control</file> file contains the most vital
2603           (and version-dependent) information about a binary package.  It
2604           consists of a single paragraph.
2605         </p>
2606
2607         <p>
2608           The fields in this file are:
2609
2610           <list compact="compact">
2611             <item><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</item>
2612             <item><qref id="f-Source"><tt>Source</tt></qref></item>
2613             <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
2614             <item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
2615             <item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
2616             <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (mandatory)</item>
2617             <item><qref id="f-Essential"><tt>Essential</tt></qref></item>
2618             <item><qref id="binarydeps"><tt>Depends</tt> et al</qref></item>
2619             <item><qref id="f-Installed-Size"><tt>Installed-Size</tt></qref></item>
2620             <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
2621             <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
2622             <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
2623           </list>
2624         </p>
2625       </sect>
2626
2627       <sect id="debiansourcecontrolfiles">
2628         <heading>Debian source control files -- <tt>.dsc</tt></heading>
2629
2630         <p>
2631           This file consists of a single paragraph, possibly surrounded by
2632           a PGP signature. The fields of that paragraph are listed below.
2633           Their syntax is described above, in <ref id="pkg-controlfields">.
2634
2635         <list compact="compact">
2636           <item><qref id="f-Format"><tt>Format</tt></qref> (mandatory)</item>
2637           <item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
2638           <item><qref id="f-Binary"><tt>Binary</tt></qref></item>
2639           <item><qref id="f-Architecture"><tt>Architecture</tt></qref></item>
2640           <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
2641           <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
2642           <item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
2643           <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
2644           <item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
2645           <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
2646           <item><qref id="f-Checksums"><tt>Checksums-Sha1</tt>
2647               and <tt>Checksums-Sha256</tt></qref> (recommended)</item>
2648           <item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
2649         </list>
2650         </p>
2651
2652         <p>
2653           The source package control file is generated by
2654           <prgn>dpkg-source</prgn> when it builds the source
2655           archive, from other files in the source package,
2656           described above.  When unpacking, it is checked against
2657           the files and directories in the other parts of the
2658           source package.
2659         </p>
2660
2661       </sect>
2662
2663       <sect id="debianchangesfiles">
2664         <heading>Debian changes files -- <file>.changes</file></heading>
2665
2666         <p>
2667           The <file>.changes</file> files are used by the Debian archive
2668           maintenance software to process updates to packages. They
2669           consist of a single paragraph, possibly surrounded by a PGP
2670           signature. That paragraph contains information from the
2671           <file>debian/control</file> file and other data about the
2672           source package gathered via <file>debian/changelog</file>
2673           and <file>debian/rules</file>.
2674         </p>
2675
2676         <p>
2677           <file>.changes</file> files have a format version that is
2678           incremented whenever the documented fields or their meaning
2679           change.  This document describes format &changesversion;.
2680         </p>
2681
2682         <p>
2683           The fields in this file are:
2684
2685           <list compact="compact">
2686             <item><qref id="f-Format"><tt>Format</tt></qref> (mandatory)</item>
2687             <item><qref id="f-Date"><tt>Date</tt></qref> (mandatory)</item>
2688             <item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
2689             <item><qref id="f-Binary"><tt>Binary</tt></qref> (mandatory)</item>
2690             <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (mandatory)</item>
2691             <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
2692             <item><qref id="f-Distribution"><tt>Distribution</tt></qref> (mandatory)</item>
2693             <item><qref id="f-Urgency"><tt>Urgency</tt></qref> (recommended)</item>
2694             <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
2695             <item><qref id="f-Changed-By"><tt>Changed-By</tt></qref></item>
2696             <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
2697             <item><qref id="f-Closes"><tt>Closes</tt></qref></item>
2698             <item><qref id="f-Changes"><tt>Changes</tt></qref> (mandatory)</item>
2699             <item><qref id="f-Checksums"><tt>Checksums-Sha1</tt>
2700                 and <tt>Checksums-Sha256</tt></qref> (recommended)</item>
2701             <item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
2702           </list>
2703         </p>
2704       </sect>
2705
2706       <sect id="controlfieldslist">
2707         <heading>List of fields</heading>
2708
2709         <sect1 id="f-Source">
2710           <heading><tt>Source</tt></heading>
2711
2712           <p>
2713             This field identifies the source package name.
2714           </p>
2715
2716           <p>
2717             In <file>debian/control</file> or a <file>.dsc</file> file,
2718             this field must contain only the name of the source package.
2719           </p>
2720
2721           <p>
2722             In a binary package control file or a <file>.changes</file>
2723             file, the source package name may be followed by a version
2724             number in parentheses<footnote>
2725                 It is customary to leave a space after the package name
2726                 if a version number is specified.
2727             </footnote>.
2728             This version number may be omitted (and is, by
2729             <prgn>dpkg-gencontrol</prgn>) if it has the same value as
2730             the <tt>Version</tt> field of the binary package in
2731             question.  The field itself may be omitted from a binary
2732             package control file when the source package has the same
2733             name and version as the binary package.
2734           </p>
2735
2736           <p>
2737             Package names (both source and binary,
2738             see <ref id="f-Package">) must consist only of lower case
2739             letters (<tt>a-z</tt>), digits (<tt>0-9</tt>), plus
2740             (<tt>+</tt>) and minus (<tt>-</tt>) signs, and periods
2741             (<tt>.</tt>).  They must be at least two characters long and
2742             must start with an alphanumeric character.
2743           </p>
2744         </sect1>
2745
2746         <sect1 id="f-Maintainer">
2747           <heading><tt>Maintainer</tt></heading>
2748
2749           <p>
2750             The package maintainer's name and email address.  The name
2751             must come first, then the email address inside angle
2752             brackets <tt>&lt;&gt;</tt> (in RFC822 format).
2753           </p>
2754
2755           <p>
2756             If the maintainer's name contains a full stop then the
2757             whole field will not work directly as an email address due
2758             to a misfeature in the syntax specified in RFC822; a
2759             program using this field as an address must check for this
2760             and correct the problem if necessary (for example by
2761             putting the name in round brackets and moving it to the
2762             end, and bringing the email address forward).
2763           </p>
2764
2765           <p>
2766             See <ref id="maintainer"> for additional requirements and
2767             information about package maintainers.
2768           </p>
2769         </sect1>
2770
2771         <sect1 id="f-Uploaders">
2772           <heading><tt>Uploaders</tt></heading>
2773
2774           <p>
2775             List of the names and email addresses of co-maintainers of the
2776             package, if any. If the package has other maintainers besides
2777             the one named in the <qref id="f-Maintainer">Maintainer
2778             field</qref>, their names and email addresses should be listed
2779             here. The format of each entry is the same as that of the
2780             Maintainer field, and multiple entries must be comma
2781             separated.
2782           </p>
2783
2784           <p>
2785             This is normally an optional field, but if
2786             the <tt>Maintainer</tt> control field names a group of people
2787             and a shared email address, the <tt>Uploaders</tt> field must
2788             be present and must contain at least one human with their
2789             personal email address.
2790           </p>
2791
2792           <p>
2793             Any parser that interprets the Uploaders field in
2794             <file>debian/control</file> must permit it to span multiple
2795             lines.  Line breaks in an Uploaders field that spans multiple
2796             lines are not significant and the semantics of the field are
2797             the same as if the line breaks had not been present.
2798           </p>
2799         </sect1>
2800
2801         <sect1 id="f-Changed-By">
2802           <heading><tt>Changed-By</tt></heading>
2803
2804           <p>
2805             The name and email address of the person who prepared this
2806             version of the package, usually a maintainer.  The syntax is
2807             the same as for the <qref id="f-Maintainer">Maintainer
2808             field</qref>.
2809           </p>
2810         </sect1>
2811
2812         <sect1 id="f-Section">
2813           <heading><tt>Section</tt></heading>
2814
2815           <p>
2816             This field specifies an application area into which the package
2817             has been classified. See <ref id="subsections">.
2818           </p>
2819
2820           <p>
2821             When it appears in the <file>debian/control</file> file,
2822             it gives the value for the subfield of the same name in
2823             the <tt>Files</tt> field of the <file>.changes</file> file.
2824             It also gives the default for the same field in the binary
2825             packages.
2826           </p>
2827         </sect1>
2828
2829         <sect1 id="f-Priority">
2830           <heading><tt>Priority</tt></heading>
2831
2832           <p>
2833             This field represents how important it is that the user
2834             have the package installed. See <ref id="priorities">.
2835           </p>
2836
2837           <p>
2838             When it appears in the <file>debian/control</file> file,
2839             it gives the value for the subfield of the same name in
2840             the <tt>Files</tt> field of the <file>.changes</file> file.
2841             It also gives the default for the same field in the binary
2842             packages.
2843           </p>
2844         </sect1>
2845
2846         <sect1 id="f-Package">
2847           <heading><tt>Package</tt></heading>
2848
2849           <p>
2850             The name of the binary package.
2851           </p>
2852
2853           <p>
2854             Binary package names must follow the same syntax and
2855             restrictions as source package names.  See <ref id="f-Source">
2856             for the details.
2857           </p>
2858         </sect1>
2859
2860         <sect1 id="f-Architecture">
2861           <heading><tt>Architecture</tt></heading>
2862
2863           <p>
2864             Depending on context and the control file used, the
2865             <tt>Architecture</tt> field can include the following sets of
2866             values:
2867             <list>
2868                 <item>
2869                   A unique single word identifying a Debian machine
2870                   architecture as described in <ref id="arch-spec">.
2871                 </item>
2872                 <item>
2873                   An architecture wildcard identifying a set of Debian
2874                   machine architectures, see <ref id="arch-wildcard-spec">.
2875                   <tt>any</tt> matches all Debian machine architectures
2876                   and is the most frequently used.
2877                 </item>
2878                 <item>
2879                   <tt>all</tt>, which indicates an
2880                   architecture-independent package.
2881                 </item>
2882                 <item>
2883                   <tt>source</tt>, which indicates a source package.
2884                 </item>
2885             </list>
2886           </p>
2887
2888           <p>
2889             In the main <file>debian/control</file> file in the source
2890             package, this field may contain the special
2891             value <tt>all</tt>, the special architecture
2892             wildcard <tt>any</tt>, or a list of specific and wildcard
2893             architectures separated by spaces.  If <tt>all</tt>
2894             or <tt>any</tt> appears, that value must be the entire
2895             contents of the field.  Most packages will use
2896             either <tt>all</tt> or <tt>any</tt>.
2897           </p>
2898
2899           <p>
2900             Specifying a specific list of architectures indicates that the
2901             source will build an architecture-dependent package only on
2902             architectures included in the list.  Specifying a list of
2903             architecture wildcards indicates that the source will build an
2904             architecture-dependent package on only those architectures
2905             that match any of the specified architecture wildcards.
2906             Specifying a list of architectures or architecture wildcards
2907             other than <tt>any</tt> is for the minority of cases where a
2908             program is not portable or is not useful on some
2909             architectures.  Where possible, the program should be made
2910             portable instead.
2911           </p>
2912
2913           <p>
2914             In the source package control file <file>.dsc</file>, this
2915             field may contain either the architecture
2916             wildcard <tt>any</tt> or a list of architectures and
2917             architecture wildcards separated by spaces. If a list is
2918             given, it may include (or consist solely of) the special
2919             value <tt>all</tt>.  In other words, in <file>.dsc</file>
2920             files unlike the <file>debian/control</file>, <tt>all</tt> may
2921             occur in combination with specific architectures.
2922             The <tt>Architecture</tt> field in the source package control
2923             file <file>.dsc</file> is generally constructed from
2924             the <tt>Architecture</tt> fields in
2925             the <file>debian/control</file> in the source package.
2926           </p>
2927
2928           <p>
2929             Specifying <tt>any</tt> indicates that the source package
2930             isn't dependent on any particular architecture and should
2931             compile fine on any one. The produced binary package(s)
2932             will either be specific to whatever the current build
2933             architecture is or will be architecture-independent.
2934           </p>
2935
2936           <p>
2937             Specifying only <tt>all</tt> indicates that the source package
2938             will only build architecture-independent packages.  If this is
2939             the case, <tt>all</tt> must be used rather than <tt>any</tt>;
2940             <tt>any</tt> implies that the source package will build at
2941             least one architecture-dependent package.
2942           </p>
2943
2944           <p>
2945             Specifying a list of architectures or architecture wildcards
2946             indicates that the source will build an architecture-dependent
2947             package, and will only work correctly on the listed or
2948             matching architectures.  If the source package also builds at
2949             least one architecture-independent package, <tt>all</tt> will
2950             also be included in the list.
2951           </p>
2952
2953           <p>
2954             In a <file>.changes</file> file, the <tt>Architecture</tt>
2955             field lists the architecture(s) of the package(s) currently
2956             being uploaded.  This will be a list; if the source for the
2957             package is also being uploaded, the special
2958             entry <tt>source</tt> is also present.  <tt>all</tt> will be
2959             present if any architecture-independent packages are being
2960             uploaded.  Architecture wildcards such as <tt>any</tt> must
2961             never occur in the <tt>Architecture</tt> field in
2962             the <file>.changes</file> file.
2963           </p>
2964
2965           <p>
2966             See <ref id="debianrules"> for information on how to get
2967             the architecture for the build process.
2968           </p>
2969         </sect1>
2970
2971         <sect1 id="f-Essential">
2972           <heading><tt>Essential</tt></heading>
2973
2974           <p>
2975             This is a boolean field which may occur only in the
2976             control file of a binary package or in a per-package fields
2977             paragraph of a main source control data file.
2978           </p>
2979
2980           <p>
2981             If set to <tt>yes</tt> then the package management system
2982             will refuse to remove the package (upgrading and replacing
2983             it is still possible). The other possible value is <tt>no</tt>,
2984             which is the same as not having the field at all.
2985           </p>
2986         </sect1>
2987
2988         <sect1>
2989           <heading>Package interrelationship fields:
2990             <tt>Depends</tt>, <tt>Pre-Depends</tt>,
2991             <tt>Recommends</tt>, <tt>Suggests</tt>,
2992             <tt>Breaks</tt>, <tt>Conflicts</tt>,
2993             <tt>Provides</tt>, <tt>Replaces</tt>, <tt>Enhances</tt>
2994           </heading>
2995
2996           <p>
2997             These fields describe the package's relationships with
2998             other packages.  Their syntax and semantics are described
2999             in <ref id="relationships">.</p>
3000         </sect1>
3001
3002         <sect1 id="f-Standards-Version">
3003           <heading><tt>Standards-Version</tt></heading>
3004
3005           <p>
3006             The most recent version of the standards (the policy
3007             manual and associated texts) with which the package
3008             complies.
3009           </p>
3010
3011           <p>
3012             The version number has four components: major and minor
3013             version number and major and minor patch level.  When the
3014             standards change in a way that requires every package to
3015             change the major number will be changed.  Significant
3016             changes that will require work in many packages will be
3017             signaled by a change to the minor number.  The major patch
3018             level will be changed for any change to the meaning of the
3019             standards, however small; the minor patch level will be
3020             changed when only cosmetic, typographical or other edits
3021             are made which neither change the meaning of the document
3022             nor affect the contents of packages.
3023           </p>
3024
3025           <p>
3026             Thus only the first three components of the policy version
3027             are significant in the <em>Standards-Version</em> control
3028             field, and so either these three components or all four
3029             components may be specified.<footnote>
3030                 In the past, people specified the full version number
3031                 in the Standards-Version field, for example "2.3.0.0".
3032                 Since minor patch-level changes don't introduce new
3033                 policy, it was thought it would be better to relax
3034                 policy and only require the first 3 components to be
3035                 specified, in this example "2.3.0".  All four
3036                 components may still be used if someone wishes to do so.
3037             </footnote>
3038           </p>
3039
3040         </sect1>
3041
3042         <sect1 id="f-Version">
3043           <heading><tt>Version</tt></heading>
3044
3045           <p>
3046             The version number of a package. The format is:
3047             [<var>epoch</var><tt>:</tt>]<var>upstream_version</var>[<tt>-</tt><var>debian_revision</var>]
3048           </p>
3049
3050           <p>
3051             The three components here are:
3052             <taglist>
3053               <tag><var>epoch</var></tag>
3054               <item>
3055                 <p>
3056                   This is a single (generally small) unsigned integer.  It
3057                   may be omitted, in which case zero is assumed.  If it is
3058                   omitted then the <var>upstream_version</var> may not
3059                   contain any colons.
3060                 </p>
3061
3062                 <p>
3063                   It is provided to allow mistakes in the version numbers
3064                   of older versions of a package, and also a package's
3065                   previous version numbering schemes, to be left behind.
3066                 </p>
3067               </item>
3068
3069               <tag><var>upstream_version</var></tag>
3070               <item>
3071                 <p>
3072                   This is the main part of the version number.  It is
3073                   usually the version number of the original ("upstream")
3074                   package from which the <file>.deb</file> file has been made,
3075                   if this is applicable.  Usually this will be in the same
3076                   format as that specified by the upstream author(s);
3077                   however, it may need to be reformatted to fit into the
3078                   package management system's format and comparison
3079                   scheme.
3080                 </p>
3081
3082                 <p>
3083                   The comparison behavior of the package management system
3084                   with respect to the <var>upstream_version</var> is
3085                   described below.  The <var>upstream_version</var>
3086                   portion of the version number is mandatory.
3087                 </p>
3088
3089                 <p>
3090                   The <var>upstream_version</var> may contain only
3091                   alphanumerics<footnote>
3092                         Alphanumerics are <tt>A-Za-z0-9</tt> only.
3093                   </footnote>
3094                   and the characters <tt>.</tt> <tt>+</tt> <tt>-</tt>
3095                   <tt>:</tt> <tt>~</tt> (full stop, plus, hyphen, colon,
3096                   tilde) and should start with a digit.  If there is no
3097                   <var>debian_revision</var> then hyphens are not allowed;
3098                   if there is no <var>epoch</var> then colons are not
3099                   allowed.
3100                 </p>
3101               </item>
3102
3103               <tag><var>debian_revision</var></tag>
3104               <item>
3105                 <p>
3106                   This part of the version number specifies the version of
3107                   the Debian package based on the upstream version.  It
3108                   may contain only alphanumerics and the characters
3109                   <tt>+</tt> <tt>.</tt> <tt>~</tt> (plus, full stop,
3110                   tilde) and is compared in the same way as the
3111                   <var>upstream_version</var> is.
3112                 </p>
3113
3114                 <p>
3115                   It is optional; if it isn't present then the
3116                   <var>upstream_version</var> may not contain a hyphen.
3117                   This format represents the case where a piece of
3118                   software was written specifically to be a Debian
3119                   package, where the Debian package source must always
3120                   be identical to the pristine source and therefore no
3121                   revision indication is required.
3122                 </p>
3123
3124                 <p>
3125                   It is conventional to restart the
3126                   <var>debian_revision</var> at <tt>1</tt> each time the
3127                   <var>upstream_version</var> is increased.
3128                 </p>
3129
3130                 <p>
3131                   The package management system will break the version
3132                   number apart at the last hyphen in the string (if there
3133                   is one) to determine the <var>upstream_version</var> and
3134                   <var>debian_revision</var>.  The absence of a
3135                   <var>debian_revision</var> is equivalent to a
3136                   <var>debian_revision</var> of <tt>0</tt>.
3137                 </p>
3138               </item>
3139             </taglist>
3140           </p>
3141
3142           <p>
3143             When comparing two version numbers, first the <var>epoch</var>
3144             of each are compared, then the <var>upstream_version</var> if
3145             <var>epoch</var> is equal, and then <var>debian_revision</var>
3146             if <var>upstream_version</var> is also equal.
3147             <var>epoch</var> is compared numerically.  The
3148             <var>upstream_version</var> and <var>debian_revision</var>
3149             parts are compared by the package management system using the
3150             following algorithm:
3151           </p>
3152
3153           <p>
3154             The strings are compared from left to right.
3155           </p>
3156
3157           <p>
3158             First the initial part of each string consisting entirely of
3159             non-digit characters is determined.  These two parts (one of
3160             which may be empty) are compared lexically.  If a difference
3161             is found it is returned.  The lexical comparison is a
3162             comparison of ASCII values modified so that all the letters
3163             sort earlier than all the non-letters and so that a tilde
3164             sorts before anything, even the end of a part.  For example,
3165             the following parts are in sorted order from earliest to
3166             latest: <tt>~~</tt>, <tt>~~a</tt>, <tt>~</tt>, the empty part,
3167             <tt>a</tt>.<footnote>
3168               One common use of <tt>~</tt> is for upstream pre-releases.
3169               For example, <tt>1.0~beta1~svn1245</tt> sorts earlier than
3170               <tt>1.0~beta1</tt>, which sorts earlier than <tt>1.0</tt>.
3171             </footnote>
3172           </p>
3173
3174           <p>
3175             Then the initial part of the remainder of each string which
3176             consists entirely of digit characters is determined.  The
3177             numerical values of these two parts are compared, and any
3178             difference found is returned as the result of the comparison.
3179             For these purposes an empty string (which can only occur at
3180             the end of one or both version strings being compared) counts
3181             as zero.
3182           </p>
3183
3184           <p>
3185             These two steps (comparing and removing initial non-digit
3186             strings and initial digit strings) are repeated until a
3187             difference is found or both strings are exhausted.
3188           </p>
3189
3190           <p>
3191             Note that the purpose of epochs is to allow us to leave behind
3192             mistakes in version numbering, and to cope with situations
3193             where the version numbering scheme changes.  It is
3194             <em>not</em> intended to cope with version numbers containing
3195             strings of letters which the package management system cannot
3196             interpret (such as <tt>ALPHA</tt> or <tt>pre-</tt>), or with
3197             silly orderings.<footnote>
3198               The author of this manual has heard of a package whose
3199               versions went <tt>1.1</tt>, <tt>1.2</tt>, <tt>1.3</tt>,
3200               <tt>1</tt>, <tt>2.1</tt>, <tt>2.2</tt>, <tt>2</tt> and so
3201               forth.
3202             </footnote>
3203           </p>
3204         </sect1>
3205
3206         <sect1 id="f-Description">
3207           <heading><tt>Description</tt></heading>
3208
3209           <p>
3210             In a source or binary control file, the <tt>Description</tt>
3211             field contains a description of the binary package, consisting
3212             of two parts, the synopsis or the short description, and the
3213             long description. The field's format is as follows:
3214           </p>
3215
3216           <p>
3217 <example>
3218         Description: &lt;single line synopsis&gt;
3219          &lt;extended description over several lines&gt;
3220 </example>
3221           </p>
3222
3223           <p>
3224             The lines in the extended description can have these formats:
3225           </p>
3226
3227           <p><list>
3228
3229             <item>
3230               Those starting with a single space are part of a paragraph.
3231               Successive lines of this form will be word-wrapped when
3232               displayed. The leading space will usually be stripped off.
3233             </item>
3234
3235             <item>
3236               Those starting with two or more spaces. These will be
3237               displayed verbatim. If the display cannot be panned
3238               horizontally, the displaying program will line wrap them "hard"
3239               (i.e., without taking account of word breaks). If it can they
3240               will be allowed to trail off to the right. None, one or two
3241               initial spaces may be deleted, but the number of spaces
3242               deleted from each line will be the same (so that you can have
3243               indenting work correctly, for example).
3244             </item>
3245
3246             <item>
3247               Those containing a single space followed by a single full stop
3248               character. These are rendered as blank lines. This is the
3249               <em>only</em> way to get a blank line<footnote>
3250                 Completely empty lines will not be rendered as blank lines.
3251                 Instead, they will cause the parser to think you're starting
3252                 a whole new record in the control file, and will therefore
3253                 likely abort with an error.
3254               </footnote>.
3255             </item>
3256
3257             <item>
3258               Those containing a space, a full stop and some more characters.
3259               These are for future expansion. Do not use them.
3260             </item>
3261
3262           </list></p>
3263
3264           <p>
3265             Do not use tab characters.  Their effect is not predictable.
3266           </p>
3267
3268           <p>
3269             See <ref id="descriptions"> for further information on this.
3270           </p>
3271
3272           <p>
3273             In a <file>.changes</file> file, the <tt>Description</tt>
3274             field contains a summary of the descriptions for the packages
3275             being uploaded.  For this case, the first line of the field
3276             value (the part on the same line as <tt>Description:</tt>) is
3277             always empty.  The content of the field is expressed as
3278             continuation lines, one line per package.  Each line is
3279             indented by one space and contains the name of a binary
3280             package, a space, a hyphen (<tt>-</tt>), a space, and the
3281             short description line from that package.
3282           </p>
3283         </sect1>
3284
3285         <sect1 id="f-Distribution">
3286           <heading><tt>Distribution</tt></heading>
3287
3288           <p>
3289             In a <file>.changes</file> file or parsed changelog output
3290             this contains the (space-separated) name(s) of the
3291             distribution(s) where this version of the package should
3292             be installed.  Valid distributions are determined by the
3293             archive maintainers.<footnote>
3294               Example distribution names in the Debian archive used in
3295               <file>.changes</file> files are:
3296                 <taglist compact="compact">
3297                   <tag><em>unstable</em></tag>
3298                   <item>
3299                     This distribution value refers to the
3300                     <em>developmental</em> part of the Debian distribution
3301                     tree.  Most new packages, new upstream versions of
3302                     packages and bug fixes go into the <em>unstable</em>
3303                     directory tree.
3304                   </item>
3305
3306                   <tag><em>experimental</em></tag>
3307                   <item>
3308                     The packages with this distribution value are deemed
3309                     by their maintainers to be high risk.  Oftentimes they
3310                     represent early beta or developmental packages from
3311                     various sources that the maintainers want people to
3312                     try, but are not ready to be a part of the other parts
3313                     of the Debian distribution tree.
3314                   </item>
3315                 </taglist>
3316
3317                 <p>
3318                   Others are used for updating stable releases or for
3319                   security uploads.  More information is available in the
3320                   Debian Developer's Reference, section "The Debian
3321                   archive".
3322                 </p>
3323             </footnote>
3324             The Debian archive software only supports listing a single
3325             distribution.  Migration of packages to other distributions is
3326             handled outside of the upload process.
3327           </p>
3328         </sect1>
3329
3330         <sect1 id="f-Date">
3331           <heading><tt>Date</tt></heading>
3332
3333           <p>
3334             This field includes the date the package was built or last
3335             edited.  It must be in the same format as the <var>date</var>
3336             in a <file>debian/changelog</file> entry.
3337           </p>
3338
3339           <p>
3340             The value of this field is usually extracted from the
3341             <file>debian/changelog</file> file - see
3342             <ref id="dpkgchangelog">).
3343           </p>
3344         </sect1>
3345
3346         <sect1 id="f-Format">
3347           <heading><tt>Format</tt></heading>
3348
3349           <p>
3350             In <qref id="debianchangesfiles"><file>.changes</file></qref>
3351             files, this field declares the format version of that file.
3352             The syntax of the field value is the same as that of
3353             a <qref id="f-Version">package version number</qref> except
3354             that no epoch or Debian revision is allowed.  The format
3355             described in this document is <tt>&changesversion;</tt>.
3356           </p>
3357
3358           <p>
3359             In <qref id="debiansourcecontrolfiles"><file>.dsc</file>
3360             Debian source control</qref> files, this field declares the
3361             format of the source package.  The field value is used by
3362             programs acting on a source package to interpret the list of
3363             files in the source package and determine how to unpack it.
3364             The syntax of the field value is a numeric major revision, a
3365             period, a numeric minor revision, and then an optional subtype
3366             after whitespace, which if specified is an alphanumeric word
3367             in parentheses.  The subtype is optional in the syntax but may
3368             be mandatory for particular source format revisions.
3369             <footnote>
3370               The source formats currently supported by the Debian archive
3371               software are <tt>1.0</tt>, <tt>3.0 (native)</tt>,
3372               and <tt>3.0 (quilt)</tt>.
3373             </footnote>
3374           </p>
3375         </sect1>
3376
3377         <sect1 id="f-Urgency">
3378           <heading><tt>Urgency</tt></heading>
3379
3380           <p>
3381             This is a description of how important it is to upgrade to
3382             this version from previous ones.  It consists of a single
3383             keyword taking one of the values <tt>low</tt>,
3384             <tt>medium</tt>, <tt>high</tt>, <tt>emergency</tt>, or
3385             <tt>critical</tt><footnote>
3386               Other urgency values are supported with configuration
3387               changes in the archive software but are not used in Debian.
3388               The urgency affects how quickly a package will be considered
3389               for inclusion into the <tt>testing</tt> distribution and
3390               gives an indication of the importance of any fixes included
3391               in the upload.  <tt>Emergency</tt> and <tt>critical</tt> are
3392               treated as synonymous.
3393             </footnote> (not case-sensitive) followed by an optional
3394             commentary (separated by a space) which is usually in
3395             parentheses.  For example:
3396
3397             <example>
3398   Urgency: low (HIGH for users of diversions)
3399             </example>
3400
3401           </p>
3402
3403           <p>
3404             The value of this field is usually extracted from the
3405             <file>debian/changelog</file> file - see
3406             <ref id="dpkgchangelog">.
3407           </p>
3408         </sect1>
3409
3410         <sect1 id="f-Changes">
3411           <heading><tt>Changes</tt></heading>
3412
3413           <p>
3414             This field contains the human-readable changes data, describing
3415             the differences between the last version and the current one.
3416           </p>
3417
3418           <p>
3419             The first line of the field value (the part on the same line
3420             as <tt>Changes:</tt>) is always empty.  The content of the
3421             field is expressed as continuation lines, with each line
3422             indented by at least one space.  Blank lines must be
3423             represented by a line consisting only of a space and a full
3424             stop (<tt>.</tt>).
3425           </p>
3426
3427           <p>
3428             The value of this field is usually extracted from the
3429             <file>debian/changelog</file> file - see
3430             <ref id="dpkgchangelog">).
3431           </p>
3432
3433           <p>
3434             Each version's change information should be preceded by a
3435             "title" line giving at least the version, distribution(s)
3436             and urgency, in a human-readable way.
3437           </p>
3438
3439           <p>
3440             If data from several versions is being returned the entry
3441             for the most recent version should be returned first, and
3442             entries should be separated by the representation of a
3443             blank line (the "title" line may also be followed by the
3444             representation of a blank line).
3445           </p>
3446         </sect1>
3447
3448         <sect1 id="f-Binary">
3449           <heading><tt>Binary</tt></heading>
3450
3451           <p>
3452             This field is a list of binary packages.  Its syntax and
3453             meaning varies depending on the control file in which it
3454             appears.
3455           </p>
3456
3457           <p>
3458             When it appears in the <file>.dsc</file> file, it lists binary
3459             packages which a source package can produce, separated by
3460             commas<footnote>
3461                 A space after each comma is conventional.
3462             </footnote>.  It may span multiple lines.  The source package
3463             does not necessarily produce all of these binary packages for
3464             every architecture.  The source control file doesn't contain
3465             details of which architectures are appropriate for which of
3466             the binary packages.
3467           </p>
3468
3469           <p>
3470             When it appears in a <file>.changes</file> file, it lists the
3471             names of the binary packages being uploaded, separated by
3472             whitespace (not commas).  It may span multiple lines.
3473           </p>
3474         </sect1>
3475
3476         <sect1 id="f-Installed-Size">
3477           <heading><tt>Installed-Size</tt></heading>
3478
3479           <p>
3480             This field appears in the control files of binary packages,
3481             and in the <file>Packages</file> files.  It gives an estimate
3482             of the total amount of disk space required to install the
3483             named package.  Actual installed size may vary based on block
3484             size, file system properties, or actions taken by package
3485             maintainer scripts.
3486           </p>
3487
3488           <p>
3489             The disk space is given as the integer value of the estimated
3490             installed size in bytes, divided by 1024 and rounded up.
3491           </p>
3492         </sect1>
3493
3494         <sect1 id="f-Files">
3495           <heading><tt>Files</tt></heading>
3496
3497           <p>
3498             This field contains a list of files with information about
3499             each one.  The exact information and syntax varies with
3500             the context.
3501           </p>
3502
3503           <p>
3504             In all cases, Files is a multiline field.  The first line of
3505             the field value (the part on the same line as <tt>Files:</tt>)
3506             is always empty.  The content of the field is expressed as
3507             continuation lines, one line per file.  Each line must be
3508             indented by one space and contain a number of sub-fields,
3509             separated by spaces, as described below.
3510           </p>
3511
3512           <p>
3513             In the <file>.dsc</file> file, each line contains the MD5
3514             checksum, size and filename of the tar file and (if
3515             applicable) diff file which make up the remainder of the
3516             source package<footnote>
3517               That is, the parts which are not the <tt>.dsc</tt>.
3518             </footnote>.  For example:
3519             <example>
3520 Files:
3521  c6f698f19f2a2aa07dbb9bbda90a2754 571925 example_1.2.orig.tar.gz
3522  938512f08422f3509ff36f125f5873ba 6220 example_1.2-1.diff.gz
3523             </example>
3524             The exact forms of the filenames are described
3525             in <ref id="pkg-sourcearchives">.
3526           </p>
3527
3528           <p>
3529             In the <file>.changes</file> file this contains one line per
3530             file being uploaded.  Each line contains the MD5 checksum,
3531             size, section and priority and the filename.  For example:
3532             <example>
3533 Files:
3534  4c31ab7bfc40d3cf49d7811987390357 1428 text extra example_1.2-1.dsc
3535  c6f698f19f2a2aa07dbb9bbda90a2754 571925 text extra example_1.2.orig.tar.gz
3536  938512f08422f3509ff36f125f5873ba 6220 text extra example_1.2-1.diff.gz
3537  7c98fe853b3bbb47a00e5cd129b6cb56 703542 text extra example_1.2-1_i386.deb
3538             </example>
3539             The <qref id="f-Section">section</qref>
3540             and <qref id="f-Priority">priority</qref> are the values of
3541             the corresponding fields in the main source control file.  If
3542             no section or priority is specified then <tt>-</tt> should be
3543             used, though section and priority values must be specified for
3544             new packages to be installed properly.
3545           </p>
3546
3547           <p>
3548             The special value <tt>byhand</tt> for the section in a
3549             <tt>.changes</tt> file indicates that the file in question
3550             is not an ordinary package file and must by installed by
3551             hand by the distribution maintainers.  If the section is
3552             <tt>byhand</tt> the priority should be <tt>-</tt>.
3553           </p>
3554
3555           <p>
3556             If a new Debian revision of a package is being shipped and
3557             no new original source archive is being distributed the
3558             <tt>.dsc</tt> must still contain the <tt>Files</tt> field
3559             entry for the original source archive
3560             <file><var>package</var>_<var>upstream-version</var>.orig.tar.gz</file>,
3561             but the <file>.changes</file> file should leave it out.  In
3562             this case the original source archive on the distribution
3563             site must match exactly, byte-for-byte, the original
3564             source archive which was used to generate the
3565             <file>.dsc</file> file and diff which are being uploaded.</p>
3566         </sect1>
3567
3568         <sect1 id="f-Closes">
3569           <heading><tt>Closes</tt></heading>
3570
3571           <p>
3572             A space-separated list of bug report numbers that the upload
3573             governed by the .changes file closes.
3574           </p>
3575         </sect1>
3576
3577         <sect1 id="f-Homepage">
3578           <heading><tt>Homepage</tt></heading>
3579
3580           <p>
3581             The URL of the web site for this package, preferably (when
3582             applicable) the site from which the original source can be
3583             obtained and any additional upstream documentation or
3584             information may be found.  The content of this field is a
3585             simple URL without any surrounding characters such as
3586             <tt>&lt;&gt;</tt>.
3587           </p>
3588         </sect1>
3589
3590         <sect1 id="f-Checksums">
3591           <heading><tt>Checksums-Sha1</tt>
3592             and <tt>Checksums-Sha256</tt></heading>
3593
3594           <p>
3595             These fields contain a list of files with a checksum and size
3596             for each one.  Both <tt>Checksums-Sha1</tt>
3597             and <tt>Checksums-Sha256</tt> have the same syntax and differ
3598             only in the checksum algorithm used: SHA-1
3599             for <tt>Checksums-Sha1</tt> and SHA-256
3600             for <tt>Checksums-Sha256</tt>.
3601           </p>
3602
3603           <p>
3604             <tt>Checksums-Sha1</tt> and <tt>Checksums-Sha256</tt> are
3605             multiline fields.  The first line of the field value (the part
3606             on the same line as <tt>Checksums-Sha1:</tt>
3607             or <tt>Checksums-Sha256:</tt>) is always empty.  The content
3608             of the field is expressed as continuation lines, one line per
3609             file.  Each line consists of the checksum, a space, the file
3610             size, a space, and the file name.  For example (from
3611             a <file>.changes</file> file):
3612             <example>
3613 Checksums-Sha1:
3614  1f418afaa01464e63cc1ee8a66a05f0848bd155c 1276 example_1.0-1.dsc
3615  a0ed1456fad61116f868b1855530dbe948e20f06 171602 example_1.0.orig.tar.gz
3616  5e86ecf0671e113b63388dac81dd8d00e00ef298 6137 example_1.0-1.debian.tar.gz
3617  71a0ff7da0faaf608481195f9cf30974b142c183 548402 example_1.0-1_i386.deb
3618 Checksums-Sha256:
3619  ac9d57254f7e835bed299926fd51bf6f534597cc3fcc52db01c4bffedae81272 1276 example_1.0-1.dsc
3620  0d123be7f51e61c4bf15e5c492b484054be7e90f3081608a5517007bfb1fd128 171602 example_1.0.orig.tar.gz
3621  f54ae966a5f580571ae7d9ef5e1df0bd42d63e27cb505b27957351a495bc6288 6137 example_1.0-1.debian.tar.gz
3622  3bec05c03974fdecd11d020fc2e8250de8404867a8a2ce865160c250eb723664 548402 example_1.0-1_i386.deb
3623             </example>
3624           </p>
3625
3626           <p>
3627             In the <file>.dsc</file> file, these fields should list all
3628             files that make up the source package.  In
3629             the <file>.changes</file> file, these fields should list all
3630             files being uploaded.  The list of files in these fields
3631             must match the list of files in the <tt>Files</tt> field.
3632           </p>
3633         </sect1>
3634       </sect>
3635
3636       <sect>
3637         <heading>User-defined fields</heading>
3638
3639         <p>
3640           Additional user-defined fields may be added to the
3641           source package control file.  Such fields will be
3642           ignored, and not copied to (for example) binary or
3643           source package control files or upload control files.
3644         </p>
3645
3646         <p>
3647           If you wish to add additional unsupported fields to
3648           these output files you should use the mechanism
3649           described here.
3650         </p>
3651
3652         <p>
3653           Fields in the main source control information file with
3654           names starting <tt>X</tt>, followed by one or more of
3655           the letters <tt>BCS</tt> and a hyphen <tt>-</tt>, will
3656           be copied to the output files.  Only the part of the
3657           field name after the hyphen will be used in the output
3658           file.  Where the letter <tt>B</tt> is used the field
3659           will appear in binary package control files, where the
3660           letter <tt>S</tt> is used in source package control
3661           files and where <tt>C</tt> is used in upload control
3662           (<tt>.changes</tt>) files.
3663         </p>
3664
3665         <p>
3666           For example, if the main source information control file
3667           contains the field
3668           <example>
3669   XBS-Comment: I stand between the candle and the star.
3670           </example>
3671           then the binary and source package control files will contain the
3672           field
3673           <example>
3674   Comment: I stand between the candle and the star.
3675           </example>
3676         </p>
3677
3678       </sect>
3679
3680     </chapt>
3681
3682
3683     <chapt id="maintainerscripts">
3684       <heading>Package maintainer scripts and installation procedure</heading>
3685
3686       <sect>
3687         <heading>Introduction to package maintainer scripts</heading>
3688
3689         <p>
3690           It is possible to supply scripts as part of a package which
3691           the package management system will run for you when your
3692           package is installed, upgraded or removed.
3693         </p>
3694
3695         <p>
3696           These scripts are the control information
3697           files <prgn>preinst</prgn>, <prgn>postinst</prgn>, <prgn>prerm</prgn>
3698           and <prgn>postrm</prgn>.  They must be proper executable files;
3699           if they are scripts (which is recommended), they must start with
3700           the usual <tt>#!</tt> convention.  They should be readable and
3701           executable by anyone, and must not be world-writable.
3702         </p>
3703
3704         <p>
3705           The package management system looks at the exit status from
3706           these scripts.  It is important that they exit with a
3707           non-zero status if there is an error, so that the package
3708           management system can stop its processing.  For shell
3709           scripts this means that you <em>almost always</em> need to
3710           use <tt>set -e</tt> (this is usually true when writing shell
3711           scripts, in fact).  It is also important, of course, that
3712           they exit with a zero status if everything went well.
3713         </p>
3714
3715         <p>
3716           Additionally, packages interacting with users
3717           using <prgn>debconf</prgn> in the <prgn>postinst</prgn> script
3718           should install a <prgn>config</prgn> script as a control
3719           information file.  See <ref id="maintscriptprompt"> for details.
3720         </p>
3721
3722         <p>
3723           When a package is upgraded a combination of the scripts from
3724           the old and new packages is called during the upgrade
3725           procedure.  If your scripts are going to be at all
3726           complicated you need to be aware of this, and may need to
3727           check the arguments to your scripts.
3728         </p>
3729
3730         <p>
3731           Broadly speaking the <prgn>preinst</prgn> is called before
3732           (a particular version of) a package is installed, and the
3733           <prgn>postinst</prgn> afterwards; the <prgn>prerm</prgn>
3734           before (a version of) a package is removed and the
3735           <prgn>postrm</prgn> afterwards.
3736         </p>
3737
3738         <p>
3739           Programs called from maintainer scripts should not normally
3740           have a path prepended to them. Before installation is
3741           started, the package management system checks to see if the
3742           programs <prgn>ldconfig</prgn>,
3743           <prgn>start-stop-daemon</prgn>, <prgn>install-info</prgn>,
3744           and <prgn>update-rc.d</prgn> can be found via the
3745           <tt>PATH</tt> environment variable. Those programs, and any
3746           other program that one would expect to be in the
3747           <tt>PATH</tt>, should thus be invoked without an absolute
3748           pathname. Maintainer scripts should also not reset the
3749           <tt>PATH</tt>, though they might choose to modify it by
3750           prepending or appending package-specific directories. These
3751           considerations really apply to all shell scripts.</p>
3752       </sect>
3753
3754       <sect id="idempotency">
3755         <heading>Maintainer scripts idempotency</heading>
3756
3757         <p>
3758           It is necessary for the error recovery procedures that the
3759           scripts be idempotent.  This means that if it is run
3760           successfully, and then it is called again, it doesn't bomb
3761           out or cause any harm, but just ensures that everything is
3762           the way it ought to be.  If the first call failed, or
3763           aborted half way through for some reason, the second call
3764           should merely do the things that were left undone the first
3765           time, if any, and exit with a success status if everything
3766           is OK.<footnote>
3767               This is so that if an error occurs, the user interrupts
3768               <prgn>dpkg</prgn> or some other unforeseen circumstance
3769               happens you don't leave the user with a badly-broken
3770               package when <prgn>dpkg</prgn> attempts to repeat the
3771               action.
3772           </footnote>
3773         </p>
3774       </sect>
3775
3776       <sect id="controllingterminal">
3777         <heading>Controlling terminal for maintainer scripts</heading>
3778
3779         <p>
3780           Maintainer scripts are not guaranteed to run with a controlling
3781           terminal and may not be able to interact with the user.  They
3782           must be able to fall back to noninteractive behavior if no
3783           controlling terminal is available.  Maintainer scripts that
3784           prompt via a program conforming to the Debian Configuration
3785           Management Specification (see <ref id="maintscriptprompt">) may
3786           assume that program will handle falling back to noninteractive
3787           behavior.
3788         </p>
3789
3790         <p>
3791           For high-priority prompts without a reasonable default answer,
3792           maintainer scripts may abort if there is no controlling
3793           terminal.  However, this situation should be avoided if at all
3794           possible, since it prevents automated or unattended installs.
3795           In most cases, users will consider this to be a bug in the
3796           package.
3797         </p>
3798       </sect>
3799
3800       <sect id="exitstatus">
3801         <heading>Exit status</heading>
3802
3803         <p>
3804           Each script must return a zero exit status for
3805           success, or a nonzero one for failure, since the package
3806           management system looks for the exit status of these scripts
3807           and determines what action to take next based on that datum.
3808         </p>
3809       </sect>
3810
3811       <sect id="mscriptsinstact"><heading>Summary of ways maintainer
3812           scripts are called
3813         </heading>
3814
3815         <p>
3816           <list compact="compact">
3817             <item>
3818               <var>new-preinst</var> <tt>install</tt>
3819             </item>
3820             <item>
3821               <var>new-preinst</var> <tt>install</tt> <var>old-version</var>
3822             </item>
3823             <item>
3824                 <var>new-preinst</var> <tt>upgrade</tt> <var>old-version</var>
3825             </item>
3826             <item>
3827                 <var>old-preinst</var> <tt>abort-upgrade</tt>
3828                 <var>new-version</var>
3829             </item>
3830           </list>
3831
3832         <p>
3833           <list compact="compact">
3834             <item>
3835                 <var>postinst</var> <tt>configure</tt>
3836                 <var>most-recently-configured-version</var>
3837             </item>
3838             <item>
3839                 <var>old-postinst</var> <tt>abort-upgrade</tt>
3840                 <var>new-version</var>
3841             </item>
3842             <item>
3843                 <var>conflictor's-postinst</var> <tt>abort-remove</tt>
3844                 <tt>in-favour</tt> <var>package</var>
3845                 <var>new-version</var>
3846             </item>
3847             <item>
3848                 <var>postinst</var> <tt>abort-remove</tt>
3849             </item>
3850             <item>
3851                 <var>deconfigured's-postinst</var>
3852                 <tt>abort-deconfigure</tt> <tt>in-favour</tt>
3853                 <var>failed-install-package</var> <var>version</var>
3854                 [<tt>removing</tt> <var>conflicting-package</var>
3855                 <var>version</var>]
3856             </item>
3857           </list>
3858
3859         <p>
3860           <list compact="compact">
3861             <item>
3862                 <var>prerm</var> <tt>remove</tt>
3863             </item>
3864             <item>
3865                 <var>old-prerm</var> <tt>upgrade</tt>
3866                 <var>new-version</var>
3867             </item>
3868             <item>
3869                 <var>new-prerm</var> <tt>failed-upgrade</tt>
3870                 <var>old-version</var>
3871             </item>
3872             <item>
3873                 <var>conflictor's-prerm</var> <tt>remove</tt>
3874                 <tt>in-favour</tt> <var>package</var>
3875                 <var>new-version</var>
3876             </item>
3877             <item>
3878                 <var>deconfigured's-prerm</var> <tt>deconfigure</tt>
3879                 <tt>in-favour</tt> <var>package-being-installed</var>
3880                 <var>version</var> [<tt>removing</tt>
3881                 <var>conflicting-package</var>
3882                 <var>version</var>]
3883             </item>
3884           </list>
3885
3886         <p>
3887           <list compact="compact">
3888             <item>
3889                 <var>postrm</var> <tt>remove</tt>
3890             </item>
3891             <item>
3892                 <var>postrm</var> <tt>purge</tt>
3893             </item>
3894             <item>
3895                 <var>old-postrm</var> <tt>upgrade</tt>
3896                 <var>new-version</var>
3897             </item>
3898             <item>
3899                 <var>new-postrm</var> <tt>failed-upgrade</tt>
3900                 <var>old-version</var>
3901             </item>
3902             <item>
3903                 <var>new-postrm</var> <tt>abort-install</tt>
3904             </item>
3905             <item>
3906                 <var>new-postrm</var> <tt>abort-install</tt>
3907                 <var>old-version</var>
3908             </item>
3909             <item>
3910                 <var>new-postrm</var> <tt>abort-upgrade</tt>
3911                 <var>old-version</var>
3912             </item>
3913             <item>
3914                 <var>disappearer's-postrm</var> <tt>disappear</tt>
3915                 <var>overwriter</var>
3916                 <var>overwriter-version</var>
3917             </item>
3918           </list>
3919         </p>
3920
3921
3922       <sect id="unpackphase">
3923         <heading>Details of unpack phase of installation or upgrade</heading>
3924
3925         <p>
3926           The procedure on installation/upgrade/overwrite/disappear
3927           (i.e., when running <tt>dpkg --unpack</tt>, or the unpack
3928           stage of <tt>dpkg --install</tt>) is as follows.  In each
3929           case, if a major error occurs (unless listed below) the
3930           actions are, in general, run backwards - this means that the
3931           maintainer scripts are run with different arguments in
3932           reverse order.  These are the "error unwind" calls listed
3933           below.
3934
3935           <enumlist>
3936             <item>
3937                 <enumlist>
3938                   <item>
3939                       If a version of the package is already installed, call
3940                       <example compact="compact">
3941 <var>old-prerm</var> upgrade <var>new-version</var>
3942                       </example>
3943                   </item>
3944                   <item>
3945                       If the script runs but exits with a non-zero
3946                       exit status, <prgn>dpkg</prgn> will attempt:
3947                       <example compact="compact">
3948 <var>new-prerm</var> failed-upgrade <var>old-version</var>
3949                       </example>
3950                       If this works, the upgrade continues. If this
3951                       does not work, the error unwind:
3952                       <example compact="compact">
3953 <var>old-postinst</var> abort-upgrade <var>new-version</var>
3954                       </example>
3955                       If this works, then the old-version is
3956                       "Installed", if not, the old version is in a
3957                       "Half-Configured" state.
3958                   </item>
3959                 </enumlist>
3960             </item>
3961
3962             <item>
3963                 If a "conflicting" package is being removed at the same time,
3964                 or if any package will be broken (due to <tt>Breaks</tt>):
3965                 <enumlist>
3966                   <item>
3967                       If <tt>--auto-deconfigure</tt> is
3968                       specified, call, for each package to be deconfigured
3969                       due to <tt>Breaks</tt>:
3970                       <example compact="compact">
3971 <var>deconfigured's-prerm</var> deconfigure \
3972   in-favour <var>package-being-installed</var> <var>version</var>
3973                       </example>
3974                       Error unwind:
3975                       <example compact="compact">
3976 <var>deconfigured's-postinst</var> abort-deconfigure \
3977   in-favour <var>package-being-installed-but-failed</var> <var>version</var>
3978                       </example>
3979                       The deconfigured packages are marked as
3980                       requiring configuration, so that if
3981                       <tt>--install</tt> is used they will be
3982                       configured again if possible.
3983                   </item>
3984                   <item>
3985                       If any packages depended on a conflicting
3986                       package being removed and <tt>--auto-deconfigure</tt> is
3987                       specified, call, for each such package:
3988                       <example compact="compact">
3989 <var>deconfigured's-prerm</var> deconfigure \
3990   in-favour <var>package-being-installed</var> <var>version</var> \
3991     removing <var>conflicting-package</var> <var>version</var>
3992                       </example>
3993                       Error unwind:
3994                       <example compact="compact">
3995 <var>deconfigured's-postinst</var> abort-deconfigure \
3996   in-favour <var>package-being-installed-but-failed</var> <var>version</var> \
3997     removing <var>conflicting-package</var> <var>version</var>
3998                       </example>
3999                       The deconfigured packages are marked as
4000                       requiring configuration, so that if
4001                       <tt>--install</tt> is used they will be
4002                       configured again if possible.
4003                   </item>
4004                   <item>
4005                       To prepare for removal of each conflicting package, call:
4006                       <example compact="compact">
4007 <var>conflictor's-prerm</var> remove \
4008   in-favour <var>package</var> <var>new-version</var>
4009                       </example>
4010                       Error unwind:
4011                       <example compact="compact">
4012 <var>conflictor's-postinst</var> abort-remove \
4013   in-favour <var>package</var> <var>new-version</var>
4014                       </example>
4015                   </item>
4016                 </enumlist>
4017             </item>
4018
4019             <item>
4020                 <enumlist>
4021                   <item>
4022                       If the package is being upgraded, call:
4023                       <example compact="compact">
4024 <var>new-preinst</var> upgrade <var>old-version</var>
4025                       </example>
4026                       If this fails, we call:
4027                       <example>
4028 <var>new-postrm</var> abort-upgrade <var>old-version</var>
4029                       </example>
4030                       <enumlist>
4031                         <item>
4032                           <p>
4033                             If that works, then
4034                             <example>
4035 <var>old-postinst</var> abort-upgrade <var>new-version</var>
4036                             </example>
4037                             is called. If this works, then the old version
4038                             is in an "Installed" state, or else it is left
4039                             in an "Unpacked" state.
4040                           </p>
4041                         </item>
4042                         <item>
4043                           <p>
4044                             If it fails, then the old version is left
4045                             in an "Half-Installed" state.
4046                           </p>
4047                         </item>
4048                       </enumlist>
4049                       
4050                   </item>
4051                   <item>
4052                       Otherwise, if the package had some configuration
4053                       files from a previous version installed (i.e., it
4054                       is in the "configuration files only" state):
4055                       <example compact="compact">
4056 <var>new-preinst</var> install <var>old-version</var>
4057                       </example>
4058                       Error unwind:
4059                       <example>
4060 <var>new-postrm</var> abort-install <var>old-version</var>
4061                       </example>
4062                       If this fails, the package is left in a
4063                       "Half-Installed" state, which requires a
4064                       reinstall. If it works, the packages is left in
4065                       a "Config-Files" state.
4066                   </item>
4067                   <item>
4068                       Otherwise (i.e., the package was completely purged):
4069                       <example compact="compact">
4070 <var>new-preinst</var> install
4071                       </example>
4072                       Error unwind:
4073                       <example compact="compact">
4074 <var>new-postrm</var> abort-install
4075                       </example>
4076                       If the error-unwind fails, the package is in a
4077                       "Half-Installed" phase, and requires a
4078                       reinstall. If the error unwind works, the
4079                       package is in a not installed state.
4080                   </item>
4081                 </enumlist>
4082             </item>
4083
4084             <item>
4085               <p>
4086                 The new package's files are unpacked, overwriting any
4087                 that may be on the system already, for example any
4088                 from the old version of the same package or from
4089                 another package.  Backups of the old files are kept
4090                 temporarily, and if anything goes wrong the package
4091                 management system will attempt to put them back as
4092                 part of the error unwind.
4093               </p>
4094
4095               <p>
4096                 It is an error for a package to contain files which
4097                 are on the system in another package, unless
4098                 <tt>Replaces</tt> is used (see <ref id="replaces">).
4099                 <!--
4100                 The following paragraph is not currently the case:
4101                 Currently the <tt>- - force-overwrite</tt> flag is
4102                 enabled, downgrading it to a warning, but this may not
4103                 always be the case.
4104                 -->
4105               </p>
4106
4107               <p>
4108                 It is a more serious error for a package to contain a
4109                 plain file or other kind of non-directory where another
4110                 package has a directory (again, unless
4111                 <tt>Replaces</tt> is used).  This error can be
4112                 overridden if desired using
4113                 <tt>--force-overwrite-dir</tt>, but this is not
4114                 advisable.
4115               </p>
4116
4117               <p>
4118                 Packages which overwrite each other's files produce
4119                 behavior which, though deterministic, is hard for the
4120                 system administrator to understand.  It can easily
4121                 lead to "missing" programs if, for example, a package
4122                 is installed which overwrites a file from another
4123                 package, and is then removed again.<footnote>
4124                     Part of the problem is due to what is arguably a
4125                     bug in <prgn>dpkg</prgn>.
4126                 </footnote>
4127               </p>
4128
4129               <p>
4130                 A directory will never be replaced by a symbolic link
4131                 to a directory or vice versa; instead, the existing
4132                 state (symlink or not) will be left alone and
4133                 <prgn>dpkg</prgn> will follow the symlink if there is
4134                 one.
4135               </p>
4136             </item>
4137
4138             <item>
4139               <p>
4140                 <enumlist>
4141                   <item>
4142                       If the package is being upgraded, call
4143                       <example compact="compact">
4144 <var>old-postrm</var> upgrade <var>new-version</var>
4145                       </example>
4146                   </item>
4147                   <item>
4148                       If this fails, <prgn>dpkg</prgn> will attempt:
4149                       <example compact="compact">
4150 <var>new-postrm</var> failed-upgrade <var>old-version</var>
4151                       </example>
4152                       If this works, installation continues. If not, 
4153                       Error unwind:
4154                       <example compact="compact">
4155 <var>old-preinst</var> abort-upgrade <var>new-version</var>
4156                       </example>
4157                       If this fails, the old version is left in a
4158                       "Half-Installed" state. If it works, dpkg now
4159                       calls:
4160                       <example compact="compact">
4161 <var>new-postrm</var> abort-upgrade <var>old-version</var>
4162                       </example>
4163                       If this fails, the old version is left in a
4164                       "Half-Installed" state. If it works, dpkg now
4165                       calls:
4166                       <example compact="compact">
4167 <var>old-postinst</var> abort-upgrade <var>new-version</var>
4168                       </example>
4169                       If this fails, the old version is in an
4170                       "Unpacked" state.
4171                   </item>
4172                 </enumlist>
4173               </p>
4174
4175               <p>
4176                 This is the point of no return - if
4177                 <prgn>dpkg</prgn> gets this far, it won't back off
4178                 past this point if an error occurs.  This will
4179                 leave the package in a fairly bad state, which
4180                 will require a successful re-installation to clear
4181                 up, but it's when <prgn>dpkg</prgn> starts doing
4182                 things that are irreversible.
4183               </p>
4184             </item>
4185
4186             <item>
4187                 Any files which were in the old version of the package
4188                 but not in the new are removed.
4189             </item>
4190
4191             <item>
4192                 The new file list replaces the old.
4193             </item>
4194
4195             <item>
4196                 The new maintainer scripts replace the old.
4197             </item>
4198
4199             <item>
4200                 Any packages all of whose files have been overwritten
4201                 during the installation, and which aren't required for
4202                 dependencies, are considered to have been removed.
4203                 For each such package
4204                 <enumlist>
4205                   <item>
4206                       <prgn>dpkg</prgn> calls:
4207                       <example compact="compact">
4208 <var>disappearer's-postrm</var> disappear \
4209   <var>overwriter</var> <var>overwriter-version</var>
4210                       </example>
4211                   </item>
4212                   <item>
4213                       The package's maintainer scripts are removed.
4214                   </item>
4215                   <item>
4216                       It is noted in the status database as being in a
4217                       sane state, namely not installed (any conffiles
4218                       it may have are ignored, rather than being
4219                       removed by <prgn>dpkg</prgn>).  Note that
4220                       disappearing packages do not have their prerm
4221                       called, because <prgn>dpkg</prgn> doesn't know
4222                       in advance that the package is going to
4223                       vanish.
4224                   </item>
4225                 </enumlist>
4226             </item>
4227
4228             <item>
4229                 Any files in the package we're unpacking that are also
4230                 listed in the file lists of other packages are removed
4231                 from those lists.  (This will lobotomize the file list
4232                 of the "conflicting" package if there is one.)
4233             </item>
4234
4235             <item>
4236                 The backup files made during installation, above, are
4237                 deleted.
4238             </item>
4239
4240             <item>
4241               <p>
4242                 The new package's status is now sane, and recorded as
4243                 "unpacked".
4244               </p>
4245
4246               <p>
4247                 Here is another point of no return - if the
4248                 conflicting package's removal fails we do not unwind
4249                 the rest of the installation; the conflicting package
4250                 is left in a half-removed limbo.
4251               </p>
4252             </item>
4253
4254             <item>
4255                 If there was a conflicting package we go and do the
4256                 removal actions (described below), starting with the
4257                 removal of the conflicting package's files (any that
4258                 are also in the package being installed have already
4259                 been removed from the conflicting package's file list,
4260                 and so do not get removed now).
4261             </item>
4262           </enumlist>
4263         </p>
4264       </sect>
4265
4266       <sect id="configdetails"><heading>Details of configuration</heading>
4267
4268         <p>
4269           When we configure a package (this happens with <tt>dpkg
4270             --install</tt> and <tt>dpkg --configure</tt>), we first
4271           update any <tt>conffile</tt>s and then call:
4272           <example compact="compact">
4273 <var>postinst</var> configure <var>most-recently-configured-version</var>
4274           </example>
4275         </p>
4276
4277         <p>
4278           No attempt is made to unwind after errors during
4279           configuration. If the configuration fails, the package is in
4280           a "Failed Config" state, and an error message is generated.
4281         </p>
4282
4283         <p>
4284           If there is no most recently configured version
4285           <prgn>dpkg</prgn> will pass a null argument.
4286           <footnote>
4287             <p>
4288               Historical note: Truly ancient (pre-1997) versions of
4289               <prgn>dpkg</prgn> passed <tt>&lt;unknown&gt;</tt>
4290               (including the angle brackets) in this case.  Even older
4291               ones did not pass a second argument at all, under any
4292               circumstance.  Note that upgrades using such an old dpkg
4293               version are unlikely to work for other reasons, even if
4294               this old argument behavior is handled by your postinst script.
4295             </p>
4296           </footnote>     
4297         </p>
4298       </sect>
4299
4300       <sect id="removedetails"><heading>Details of removal and/or
4301       configuration purging</heading>
4302
4303         <p>
4304           <enumlist>
4305             <item>
4306               <p>
4307                 <example compact="compact">
4308 <var>prerm</var> remove
4309                 </example>
4310               </p>
4311               <p>
4312                 If prerm fails during replacement due to conflict
4313                 <example>
4314 <var>conflictor's-postinst</var> abort-remove \
4315   in-favour <var>package</var> <var>new-version</var>
4316                 </example>
4317                 Or else we call:
4318                 <example>
4319 <var>postinst</var> abort-remove
4320                 </example>
4321               </p>
4322               <p>
4323                 If this fails, the package is in a "Half-Configured"
4324                 state, or else it remains "Installed".
4325               </p>
4326             </item>
4327             <item>
4328                 The package's files are removed (except <tt>conffile</tt>s).
4329             </item>
4330             <item>
4331                 <example compact="compact">
4332 <var>postrm</var> remove
4333                 </example>
4334
4335               <p>
4336                 If it fails, there's no error unwind, and the package is in
4337                 an "Half-Installed" state.
4338               </p>
4339             </item>
4340             <item>
4341               <p>
4342                 All the maintainer scripts except the <prgn>postrm</prgn>
4343                 are removed.
4344               </p>
4345
4346               <p>
4347                 If we aren't purging the package we stop here.  Note
4348                 that packages which have no <prgn>postrm</prgn> and no
4349                 <tt>conffile</tt>s are automatically purged when
4350                 removed, as there is no difference except for the
4351                 <prgn>dpkg</prgn> status.
4352               </p>
4353             </item>
4354             <item>
4355                 The <tt>conffile</tt>s and any backup files
4356                 (<tt>~</tt>-files, <tt>#*#</tt> files,
4357                 <tt>%</tt>-files, <tt>.dpkg-{old,new,tmp}</tt>, etc.)
4358                 are removed.
4359             </item>
4360             <item>
4361               <p>
4362                 <example compact="compact">
4363 <var>postrm</var> purge
4364                 </example>
4365               </p>
4366               <p>
4367                 If this fails, the package remains in a "Config-Files"
4368                 state.
4369               </p>
4370             </item>
4371             <item>
4372                 The package's file list is removed.
4373             </item>
4374           </enumlist>
4375
4376         </p>
4377       </sect>
4378     </chapt>
4379
4380
4381     <chapt id="relationships">
4382       <heading>Declaring relationships between packages</heading>
4383
4384       <sect id="depsyntax">
4385         <heading>Syntax of relationship fields</heading>
4386
4387         <p>
4388           These fields all have a uniform syntax.  They are a list of
4389           package names separated by commas.
4390         </p>
4391
4392         <p>
4393           In the <tt>Depends</tt>, <tt>Recommends</tt>,
4394           <tt>Suggests</tt>, <tt>Pre-Depends</tt>,
4395           <tt>Build-Depends</tt> and <tt>Build-Depends-Indep</tt>
4396           control fields of the package, which declare
4397           dependencies on other packages, the package names listed may
4398           also include lists of alternative package names, separated
4399           by vertical bar (pipe) symbols <tt>|</tt>.  In such a case,
4400           if any one of the alternative packages is installed, that
4401           part of the dependency is considered to be satisfied.
4402         </p>
4403
4404         <p>
4405           All of the fields except for <tt>Provides</tt> may restrict
4406           their applicability to particular versions of each named
4407           package.  This is done in parentheses after each individual
4408           package name; the parentheses should contain a relation from
4409           the list below followed by a version number, in the format
4410           described in <ref id="f-Version">.
4411         </p>
4412
4413         <p>
4414           The relations allowed are <tt>&lt;&lt;</tt>, <tt>&lt;=</tt>,
4415           <tt>=</tt>, <tt>&gt;=</tt> and <tt>&gt;&gt;</tt> for
4416           strictly earlier, earlier or equal, exactly equal, later or
4417           equal and strictly later, respectively.  The deprecated
4418           forms <tt>&lt;</tt> and <tt>&gt;</tt> were used to mean
4419           earlier/later or equal, rather than strictly earlier/later,
4420           so they should not appear in new packages (though
4421           <prgn>dpkg</prgn> still supports them).
4422         </p>
4423
4424         <p>
4425           Whitespace may appear at any point in the version
4426           specification subject to the rules in <ref
4427           id="controlsyntax">, and must appear where it's necessary to
4428           disambiguate; it is not otherwise significant.  All of the
4429           relationship fields may span multiple lines.  For
4430           consistency and in case of future changes to
4431           <prgn>dpkg</prgn> it is recommended that a single space be
4432           used after a version relationship and before a version
4433           number; it is also conventional to put a single space after
4434           each comma, on either side of each vertical bar, and before
4435           each open parenthesis.  When wrapping a relationship field, it
4436           is conventional to do so after a comma and before the space
4437           following that comma.
4438         </p>
4439
4440         <p>
4441           For example, a list of dependencies might appear as:
4442           <example compact="compact">
4443 Package: mutt
4444 Version: 1.3.17-1
4445 Depends: libc6 (>= 2.2.1), exim | mail-transport-agent
4446           </example>
4447         </p>
4448
4449         <p>
4450           Relationships may be restricted to a certain set of
4451           architectures.  This is indicated in brackets after each
4452           individual package name and the optional version specification.
4453           The brackets enclose a list of Debian architecture names
4454           separated by whitespace.  Exclamation marks may be prepended to
4455           each of the names.  (It is not permitted for some names to be
4456           prepended with exclamation marks while others aren't.)
4457         </p>
4458
4459         <p>
4460           For build relationship fields
4461           (<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
4462           <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>), if
4463           the current Debian host architecture is not in this list and
4464           there are no exclamation marks in the list, or it is in the list
4465           with a prepended exclamation mark, the package name and the
4466           associated version specification are ignored completely for the
4467           purposes of defining the relationships.
4468         </p>
4469
4470         <p>
4471           For example:
4472           <example compact="compact">
4473 Source: glibc
4474 Build-Depends-Indep: texinfo
4475 Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
4476   hurd-dev [hurd-i386], gnumach-dev [hurd-i386]
4477           </example>
4478           requires <tt>kernel-headers-2.2.10</tt> on all architectures
4479           other than hurd-i386 and requires <tt>hurd-dev</tt> and
4480           <tt>gnumach-dev</tt> only on hurd-i386.
4481         </p>
4482
4483         <p>
4484           For binary relationship fields, the architecture restriction
4485           syntax is only supported in the source package control
4486           file <file>debian/control</file>.  When the corresponding binary
4487           package control file is generated, the relationship will either
4488           be omitted or included without the architecture restriction
4489           based on the architecture of the binary package.  This means
4490           that architecture restrictions must not be used in binary
4491           relationship fields for architecture-independent packages
4492           (<tt>Architecture: all</tt>).
4493         </p>
4494
4495         <p>
4496           For example:
4497           <example compact="compact">
4498 Depends: foo [i386], bar [amd64]
4499           </example>
4500           becomes <tt>Depends: foo</tt> when the package is built on
4501           the <tt>i386</tt> architecture, <tt>Depends: bar</tt> when the
4502           package is built on the <tt>amd64</tt> architecture, and omitted
4503           entirely in binary packages built on all other architectures.
4504         </p>
4505
4506         <p>
4507           If the architecture-restricted dependency is part of a set of
4508           alternatives using <tt>|</tt>, that alternative is ignored
4509           completely on architectures that do not match the restriction.
4510           For example:
4511           <example compact="compact">
4512 Build-Depends: foo [!i386] | bar [!amd64]
4513           </example>
4514           is equivalent to <tt>bar</tt> on the i386 architecture, to
4515           <tt>foo</tt> on the amd64 architecture, and to <tt>foo |
4516           bar</tt> on all other architectures.
4517         </p>
4518
4519         <p>
4520           Relationships may also be restricted to a certain set of
4521           architectures using architecture wildcards.  The syntax for
4522           declaring such restrictions is the same as declaring
4523           restrictions using a certain set of architectures without
4524           architecture wildcards.  For example:
4525           <example compact="compact">
4526 Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
4527           </example>
4528           is equivalent to <tt>foo</tt> on architectures using the Linux
4529           kernel and any cpu, <tt>bar</tt> on architectures using any
4530           kernel and an i386 cpu, and <tt>baz</tt> on any architecture
4531           using a kernel other than Linux.
4532         </p>
4533
4534         <p>
4535           Note that the binary package relationship fields such as
4536           <tt>Depends</tt> appear in one of the binary package
4537           sections of the control file, whereas the build-time
4538           relationships such as <tt>Build-Depends</tt> appear in the
4539           source package section of the control file (which is the
4540           first section).
4541         </p>
4542       </sect>
4543
4544       <sect id="binarydeps">
4545         <heading>Binary Dependencies - <tt>Depends</tt>,
4546           <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
4547           <tt>Pre-Depends</tt>
4548         </heading>
4549
4550         <p>
4551           Packages can declare in their control file that they have
4552           certain relationships to other packages - for example, that
4553           they may not be installed at the same time as certain other
4554           packages, and/or that they depend on the presence of others.
4555         </p>
4556
4557         <p>
4558           This is done using the <tt>Depends</tt>, <tt>Pre-Depends</tt>,
4559           <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
4560           <tt>Breaks</tt> and <tt>Conflicts</tt> control fields.
4561           <tt>Breaks</tt> is described in <ref id="breaks">, and
4562           <tt>Conflicts</tt> is described in <ref id="conflicts">.  The
4563           rest are described below.
4564         </p>
4565
4566         <p>
4567           These seven fields are used to declare a dependency
4568           relationship by one package on another.  Except for
4569           <tt>Enhances</tt> and <tt>Breaks</tt>, they appear in the
4570           depending (binary) package's control file.
4571           (<tt>Enhances</tt> appears in the recommending package's
4572           control file, and <tt>Breaks</tt> appears in the version of
4573           depended-on package which causes the named package to
4574           break).
4575         </p>
4576
4577         <p>
4578           A <tt>Depends</tt> field takes effect <em>only</em> when a
4579           package is to be configured.  It does not prevent a package
4580           being on the system in an unconfigured state while its
4581           dependencies are unsatisfied, and it is possible to replace
4582           a package whose dependencies are satisfied and which is
4583           properly installed with a different version whose
4584           dependencies are not and cannot be satisfied; when this is
4585           done the depending package will be left unconfigured (since
4586           attempts to configure it will give errors) and will not
4587           function properly.  If it is necessary, a
4588           <tt>Pre-Depends</tt> field can be used, which has a partial
4589           effect even when a package is being unpacked, as explained
4590           in detail below.  (The other three dependency fields,
4591           <tt>Recommends</tt>, <tt>Suggests</tt> and
4592           <tt>Enhances</tt>, are only used by the various front-ends
4593           to <prgn>dpkg</prgn> such as <prgn>apt-get</prgn>,
4594           <prgn>aptitude</prgn>, and <prgn>dselect</prgn>.)
4595         </p>
4596
4597         <p>
4598           For this reason packages in an installation run are usually
4599           all unpacked first and all configured later; this gives
4600           later versions of packages with dependencies on later
4601           versions of other packages the opportunity to have their
4602           dependencies satisfied.
4603         </p>
4604
4605         <p>
4606           In case of circular dependencies, since installation or
4607           removal order honoring the dependency order can't be
4608           established, dependency loops are broken at some point
4609           (based on rules below), and some packages may not be able to
4610           rely on their dependencies being present when being
4611           installed or removed, depending on which side of the break
4612           of the circular dependency loop they happen to be on.  If one
4613           of the packages in the loop has no postinst script, then the
4614           cycle will be broken at that package, so as to ensure that
4615           all postinst scripts run with the dependencies properly
4616           configured if this is possible. Otherwise the breaking point
4617           is arbitrary.
4618         </p>
4619
4620         <p>
4621           The <tt>Depends</tt> field thus allows package maintainers
4622           to impose an order in which packages should be configured.
4623         </p>
4624
4625         <p>
4626           The meaning of the five dependency fields is as follows:
4627           <taglist>
4628             <tag><tt>Depends</tt></tag>
4629             <item>
4630               <p>
4631                 This declares an absolute dependency.  A package will
4632                 not be configured unless all of the packages listed in
4633                 its <tt>Depends</tt> field have been correctly
4634                 configured.
4635               </p>
4636
4637               <p>
4638                 The <tt>Depends</tt> field should be used if the
4639                 depended-on package is required for the depending
4640                 package to provide a significant amount of
4641                 functionality.
4642               </p>
4643
4644               <p>
4645                 The <tt>Depends</tt> field should also be used if the
4646                 <prgn>postinst</prgn>, <prgn>prerm</prgn> or
4647                 <prgn>postrm</prgn> scripts require the package to be
4648                 present in order to run.  Note, however, that the
4649                 <prgn>postrm</prgn> cannot rely on any non-essential
4650                 packages to be present during the <tt>purge</tt>
4651                 phase.
4652             </item>
4653
4654             <tag><tt>Recommends</tt></tag>
4655             <item>
4656               <p>
4657                 This declares a strong, but not absolute, dependency.
4658               </p>
4659
4660               <p>
4661                 The <tt>Recommends</tt> field should list packages
4662                 that would be found together with this one in all but
4663                 unusual installations.
4664               </p>
4665             </item>
4666
4667             <tag><tt>Suggests</tt></tag>
4668             <item>
4669                 This is used to declare that one package may be more
4670                 useful with one or more others.  Using this field
4671                 tells the packaging system and the user that the
4672                 listed packages are related to this one and can
4673                 perhaps enhance its usefulness, but that installing
4674                 this one without them is perfectly reasonable.
4675             </item>
4676
4677             <tag><tt>Enhances</tt></tag>
4678             <item>
4679                 This field is similar to Suggests but works in the
4680                 opposite direction. It is used to declare that a
4681                 package can enhance the functionality of another
4682                 package.
4683             </item>
4684
4685             <tag><tt>Pre-Depends</tt></tag>
4686             <item>
4687               <p>
4688                 This field is like <tt>Depends</tt>, except that it
4689                 also forces <prgn>dpkg</prgn> to complete installation
4690                 of the packages named before even starting the
4691                 installation of the package which declares the
4692                 pre-dependency, as follows:
4693               </p>
4694
4695               <p>
4696                 When a package declaring a pre-dependency is about to
4697                 be <em>unpacked</em> the pre-dependency can be
4698                 satisfied if the depended-on package is either fully
4699                 configured, <em>or even if</em> the depended-on
4700                 package(s) are only unpacked or in the "Half-Configured"
4701                 state, provided that they have been configured
4702                 correctly at some point in the past (and not removed
4703                 or partially removed since).  In this case, both the
4704                 previously-configured and currently unpacked or
4705                 "Half-Configured" versions must satisfy any version
4706                 clause in the <tt>Pre-Depends</tt> field.
4707               </p>
4708
4709               <p>
4710                 When the package declaring a pre-dependency is about
4711                 to be <em>configured</em>, the pre-dependency will be
4712                 treated as a normal <tt>Depends</tt>, that is, it will
4713                 be considered satisfied only if the depended-on
4714                 package has been correctly configured.
4715               </p>
4716
4717               <p>
4718                 <tt>Pre-Depends</tt> should be used sparingly,
4719                 preferably only by packages whose premature upgrade or
4720                 installation would hamper the ability of the system to
4721                 continue with any upgrade that might be in progress.
4722               </p>
4723
4724               <p>
4725                 <tt>Pre-Depends</tt> are also required if the
4726                 <prgn>preinst</prgn> script depends on the named
4727                 package.  It is best to avoid this situation if
4728                 possible.
4729               </p>
4730             </item>
4731           </taglist>
4732         </p>
4733
4734         <p>
4735           When selecting which level of dependency to use you should
4736           consider how important the depended-on package is to the
4737           functionality of the one declaring the dependency.  Some
4738           packages are composed of components of varying degrees of
4739           importance.  Such a package should list using
4740           <tt>Depends</tt> the package(s) which are required by the
4741           more important components.  The other components'
4742           requirements may be mentioned as Suggestions or
4743           Recommendations, as appropriate to the components' relative
4744           importance.
4745         </p>
4746       </sect>
4747
4748       <sect id="breaks">
4749         <heading>Packages which break other packages - <tt>Breaks</tt></heading>
4750
4751         <p>
4752           When one binary package declares that it breaks another,
4753           <prgn>dpkg</prgn> will refuse to allow the package which
4754           declares <tt>Breaks</tt> be installed unless the broken
4755           package is deconfigured first, and it will refuse to
4756           allow the broken package to be reconfigured.
4757         </p>
4758
4759         <p>
4760           A package will not be regarded as causing breakage merely
4761           because its configuration files are still installed; it must
4762           be at least "Half-Installed".
4763         </p>
4764
4765         <p>
4766           A special exception is made for packages which declare that
4767           they break their own package name or a virtual package which
4768           they provide (see below): this does not count as a real
4769           breakage.
4770         </p>
4771
4772         <p>
4773           Normally a <tt>Breaks</tt> entry will have an "earlier than"
4774           version clause; such a <tt>Breaks</tt> is introduced in the
4775           version of an (implicit or explicit) dependency which violates
4776           an assumption or reveals a bug in earlier versions of the broken
4777           package, or which takes over a file from earlier versions of the
4778           package named in <tt>Breaks</tt>.  This use of <tt>Breaks</tt>
4779           will inform higher-level package management tools that the
4780           broken package must be upgraded before the new one.
4781         </p>
4782
4783         <p>
4784           If the breaking package also overwrites some files from the
4785           older package, it should use <tt>Replaces</tt> to ensure this
4786           goes smoothly.  See <ref id="replaces"> for a full discussion
4787           of taking over files from other packages, including how to
4788           use <tt>Breaks</tt> in those cases.
4789         </p>
4790
4791         <p>
4792           Many of the cases where <tt>Breaks</tt> should be used were
4793           previously handled with <tt>Conflicts</tt>
4794           because <tt>Breaks</tt> did not yet exist.
4795           Many <tt>Conflicts</tt> fields should now be <tt>Breaks</tt>.
4796           See <ref id="conflicts"> for more information about the
4797           differences.
4798         </p>
4799       </sect>
4800
4801       <sect id="conflicts">
4802         <heading>Conflicting binary packages - <tt>Conflicts</tt></heading>
4803
4804         <p>
4805           When one binary package declares a conflict with another
4806           using a <tt>Conflicts</tt> field, <prgn>dpkg</prgn> will
4807           refuse to allow them to be installed on the system at the
4808           same time.  This is a stronger restriction than <tt>Breaks</tt>,
4809           which just prevents both packages from being configured at the
4810           same time.  Conflicting packages cannot be unpacked on the
4811           system at the same time.
4812         </p>
4813
4814         <p>
4815           If one package is to be installed, the other must be removed
4816           first.  If the package being installed is marked as replacing
4817           (see <ref id="replaces">, but note that <tt>Breaks</tt> should
4818           normally be used in this case) the one on the system, or the one
4819           on the system is marked as deselected, or both packages are
4820           marked <tt>Essential</tt>, then <prgn>dpkg</prgn> will
4821           automatically remove the package which is causing the conflict.
4822           Otherwise, it will halt the installation of the new package with
4823           an error.  This mechanism is specifically designed to produce an
4824           error when the installed package is <tt>Essential</tt>, but the
4825           new package is not.
4826         </p>
4827
4828         <p>
4829           A package will not cause a conflict merely because its
4830           configuration files are still installed; it must be at least
4831           "Half-Installed".
4832         </p>
4833
4834         <p>
4835           A special exception is made for packages which declare a
4836           conflict with their own package name, or with a virtual
4837           package which they provide (see below): this does not
4838           prevent their installation, and allows a package to conflict
4839           with others providing a replacement for it.  You use this
4840           feature when you want the package in question to be the only
4841           package providing some feature.
4842         </p>
4843
4844         <p>
4845           Normally, <tt>Breaks</tt> should be used instead
4846           of <tt>Conflicts</tt> since <tt>Conflicts</tt> imposes a
4847           stronger restriction on the ordering of package installation or
4848           upgrade and can make it more difficult for the package manager
4849           to find a correct solution to an upgrade or installation
4850           problem.  <tt>Breaks</tt> should be used
4851           <list>
4852             <item>when moving a file from one package to another (see
4853               <ref id="replaces">),</item>
4854             <item>when splitting a package (a special case of the previous
4855               one), or</item>
4856             <item>when the breaking package exposes a bug in or interacts
4857               badly with particular versions of the broken
4858               package.</item>
4859           </list>
4860           <tt>Conflicts</tt> should be used
4861           <list>
4862             <item>when two packages provide the same file and will
4863               continue to do so,</item>
4864             <item>in conjunction with <tt>Provides</tt> when only one
4865               package providing a given virtual facility may be installed
4866               at a time (see <ref id="virtual">),</item>
4867             <item>in other cases where one must prevent simultaneous
4868               installation of two packages for reasons that are ongoing
4869               (not fixed in a later version of one of the packages) or
4870               that must prevent both packages from being unpacked at the
4871               same time, not just configured.</item>
4872           </list>
4873           Be aware that adding <tt>Conflicts</tt> is normally not the best
4874           solution when two packages provide the same files.  Depending on
4875           the reason for that conflict, using alternatives or renaming the
4876           files is often a better approach.  See, for
4877           example, <ref id="binaries">.
4878         </p>
4879
4880         <p>
4881           Neither <tt>Breaks</tt> nor <tt>Conflicts</tt> should be used
4882           unless two packages cannot be installed at the same time or
4883           installing them both causes one of them to be broken or
4884           unusable.  Having similar functionality or performing the same
4885           tasks as another package is not sufficient reason to
4886           declare <tt>Breaks</tt> or <tt>Conflicts</tt> with that package.
4887         </p>
4888
4889         <p>
4890           A <tt>Conflicts</tt> entry may have an "earlier than" version
4891           clause if the reason for the conflict is corrected in a later
4892           version of one of the packages.  However, normally the presence
4893           of an "earlier than" version clause is a sign
4894           that <tt>Breaks</tt> should have been used instead.  An "earlier
4895           than" version clause in <tt>Conflicts</tt>
4896           prevents <prgn>dpkg</prgn> from upgrading or installing the
4897           package which declares such a conflict until the upgrade or
4898           removal of the conflicted-with package has been completed, which
4899           is a strong restriction.
4900         </p>
4901       </sect>
4902
4903       <sect id="virtual"><heading>Virtual packages - <tt>Provides</tt>
4904         </heading>
4905
4906         <p>
4907           As well as the names of actual ("concrete") packages, the
4908           package relationship fields <tt>Depends</tt>,
4909           <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
4910           <tt>Pre-Depends</tt>, <tt>Breaks</tt>, <tt>Conflicts</tt>,
4911           <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
4912           <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>
4913           may mention "virtual packages".
4914         </p>
4915
4916         <p>
4917           A <em>virtual package</em> is one which appears in the
4918           <tt>Provides</tt> control field of another package.  The effect
4919           is as if the package(s) which provide a particular virtual
4920           package name had been listed by name everywhere the virtual
4921           package name appears. (See also <ref id="virtual_pkg">)
4922         </p>
4923
4924         <p>
4925           If there are both concrete and virtual packages of the same
4926           name, then the dependency may be satisfied (or the conflict
4927           caused) by either the concrete package with the name in
4928           question or any other concrete package which provides the
4929           virtual package with the name in question.  This is so that,
4930           for example, supposing we have
4931           <example compact="compact">
4932 Package: foo
4933 Depends: bar
4934           </example> and someone else releases an enhanced version of
4935           the <tt>bar</tt> package they can say:
4936           <example compact="compact">
4937 Package: bar-plus
4938 Provides: bar
4939           </example>
4940           and the <tt>bar-plus</tt> package will now also satisfy the
4941           dependency for the <tt>foo</tt> package.
4942         </p>
4943
4944         <p>
4945           If a relationship field has a version number attached, only real
4946           packages will be considered to see whether the relationship is
4947           satisfied (or the prohibition violated, for a conflict or
4948           breakage).  In other words, if a version number is specified,
4949           this is a request to ignore all <tt>Provides</tt> for that
4950           package name and consider only real packages.  The package
4951           manager will assume that a package providing that virtual
4952           package is not of the "right" version.  A <tt>Provides</tt>
4953           field may not contain version numbers, and the version number of
4954           the concrete package which provides a particular virtual package
4955           will not be considered when considering a dependency on or
4956           conflict with the virtual package name.<footnote>
4957             It is possible that a future release of <prgn>dpkg</prgn> may
4958             add the ability to specify a version number for each virtual
4959             package it provides.  This feature is not yet present,
4960             however, and is expected to be used only infrequently.
4961           </footnote>
4962         </p>
4963
4964         <p>
4965           To specify which of a set of real packages should be the default
4966           to satisfy a particular dependency on a virtual package, list
4967           the real package as an alternative before the virtual one.
4968         </p>
4969
4970         <p>
4971           If the virtual package represents a facility that can only be
4972           provided by one real package at a time, such as
4973           the <package>mail-transport-agent</package> virtual package that
4974           requires installation of a binary that would conflict with all
4975           other providers of that virtual package (see
4976           <ref id="mail-transport-agents">), all packages providing that
4977           virtual package should also declare a conflict with it
4978           using <tt>Conflicts</tt>.  This will ensure that at most one
4979           provider of that virtual package is unpacked or installed at a
4980           time.
4981         </p>
4982       </sect>
4983
4984       <sect id="replaces"><heading>Overwriting files and replacing
4985           packages - <tt>Replaces</tt></heading>
4986
4987         <p>
4988           Packages can declare in their control file that they should
4989           overwrite files in certain other packages, or completely replace
4990           other packages. The <tt>Replaces</tt> control field has these
4991           two distinct purposes.
4992         </p>
4993
4994         <sect1><heading>Overwriting files in other packages</heading>
4995
4996           <p>
4997             It is usually an error for a package to contain files which
4998             are on the system in another package.  However, if the
4999             overwriting package declares that it <tt>Replaces</tt> the one
5000             containing the file being overwritten, then <prgn>dpkg</prgn>
5001             will replace the file from the old package with that from the
5002             new.  The file will no longer be listed as "owned" by the old
5003             package and will be taken over by the new package.
5004             Normally, <tt>Breaks</tt> should be used in conjunction
5005             with <tt>Replaces</tt>.<footnote>
5006               To see why <tt>Breaks</tt> is normally needed in addition
5007               to <tt>Replaces</tt>, consider the case of a file in the
5008               package <package>foo</package> being taken over by the
5009               package <package>foo-data</package>.
5010               <tt>Replaces</tt> will allow <package>foo-data</package> to
5011               be installed and take over that file.  However,
5012               without <tt>Breaks</tt>, nothing
5013               requires <package>foo</package> to be upgraded to a newer
5014               version that knows it does not include that file and instead
5015               depends on <package>foo-data</package>.  Nothing would
5016               prevent the new <package>foo-data</package> package from
5017               being installed and then removed, removing the file that it
5018               took over from <package>foo</package>.  After that
5019               operation, the package manager would think the system was in
5020               a consistent state, but the <package>foo</package> package
5021               would be missing one of its files.
5022             </footnote>
5023           </p>
5024
5025           <p>
5026             For example, if a package <package>foo</package> is split
5027             into <package>foo</package> and <package>foo-data</package>
5028             starting at version 1.2-3, <package>foo-data</package> would
5029             have the fields
5030             <example compact="compact">
5031 Replaces: foo (&lt;&lt; 1.2-3)
5032 Breaks: foo (&lt;&lt; 1.2-3)
5033             </example>
5034             in its control file.  The new version of the
5035             package <package>foo</package> would normally have the field
5036             <example compact="compact">
5037 Depends: foo-data (&gt;= 1.2-3)
5038             </example>
5039             (or possibly <tt>Recommends</tt> or even <tt>Suggests</tt> if
5040             the files moved into <package>foo-data</package> are not
5041             required for normal operation).
5042           </p>
5043
5044           <p>
5045             If a package is completely replaced in this way, so that
5046             <prgn>dpkg</prgn> does not know of any files it still
5047             contains, it is considered to have "disappeared".  It will
5048             be marked as not wanted on the system (selected for
5049             removal) and not installed.  Any <tt>conffile</tt>s
5050             details noted for the package will be ignored, as they
5051             will have been taken over by the overwriting package.  The
5052             package's <prgn>postrm</prgn> script will be run with a
5053             special argument to allow the package to do any final
5054             cleanup required.  See <ref id="mscriptsinstact">.
5055             <footnote>
5056               Replaces is a one way relationship.  You have to install
5057               the replacing package after the replaced package.
5058             </footnote>
5059           </p>
5060
5061           <p>
5062             For this usage of <tt>Replaces</tt>, virtual packages (see
5063             <ref id="virtual">) are not considered when looking at a
5064             <tt>Replaces</tt> field.  The packages declared as being
5065             replaced must be mentioned by their real names.
5066           </p>
5067
5068           <p>
5069             This usage of <tt>Replaces</tt> only takes effect when both
5070             packages are at least partially on the system at once.  It is
5071             not relevant if the packages conflict unless the conflict has
5072             been overridden.
5073           </p>
5074         </sect1>
5075
5076         <sect1><heading>Replacing whole packages, forcing their
5077             removal</heading>
5078
5079           <p>
5080             Second, <tt>Replaces</tt> allows the packaging system to
5081             resolve which package should be removed when there is a
5082             conflict (see <ref id="conflicts">).  This usage only takes
5083             effect when the two packages <em>do</em> conflict, so that the
5084             two usages of this field do not interfere with each other.
5085           </p>
5086
5087           <p>
5088             In this situation, the package declared as being replaced
5089             can be a virtual package, so for example, all mail
5090             transport agents (MTAs) would have the following fields in
5091             their control files:
5092             <example compact="compact">
5093 Provides: mail-transport-agent
5094 Conflicts: mail-transport-agent
5095 Replaces: mail-transport-agent
5096             </example>
5097             ensuring that only one MTA can be installed at any one
5098             time.  See <ref id="virtual"> for more information about this
5099             example.
5100         </sect1>
5101       </sect>
5102
5103       <sect id="sourcebinarydeps">
5104         <heading>Relationships between source and binary packages -
5105           <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
5106           <tt>Build-Conflicts</tt>, <tt>Build-Conflicts-Indep</tt>
5107         </heading>
5108
5109         <p>
5110           Source packages that require certain binary packages to be
5111           installed or absent at the time of building the package
5112           can declare relationships to those binary packages.
5113         </p>
5114
5115         <p>
5116           This is done using the <tt>Build-Depends</tt>,
5117           <tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt> and
5118           <tt>Build-Conflicts-Indep</tt> control fields.
5119         </p>
5120
5121         <p>
5122           Build-dependencies on "build-essential" binary packages can be
5123           omitted. Please see <ref id="pkg-relations"> for more information.
5124         </p>
5125
5126         <p>
5127           The dependencies and conflicts they define must be satisfied
5128           (as defined earlier for binary packages) in order to invoke
5129           the targets in <tt>debian/rules</tt>, as follows:<footnote>
5130             <p>
5131               There is no Build-Depends-Arch; this role is essentially
5132               met with Build-Depends.  Anyone building the
5133               <tt>build-indep</tt> and <tt>binary-indep</tt> targets is
5134               assumed to be building the whole package, and therefore
5135               installation of all build dependencies is required.
5136             </p>
5137             <p>
5138               The autobuilders use <tt>dpkg-buildpackage -B</tt>, which
5139               calls <tt>build</tt>, not <tt>build-arch</tt> since it does
5140               not yet know how to check for its existence, and
5141               <tt>binary-arch</tt>.  The purpose of the original split
5142               between <tt>Build-Depends</tt> and
5143               <tt>Build-Depends-Indep</tt> was so that the autobuilders
5144               wouldn't need to install extra packages needed only for the
5145               binary-indep targets.  But without a build-arch/build-indep
5146               split, this didn't work, since most of the work is done in
5147               the build target, not in the binary target.
5148             </p>
5149           </footnote>
5150           <taglist>
5151             <tag><tt>clean</tt>, <tt>build-arch</tt>, and
5152               <tt>binary-arch</tt></tag>
5153             <item>
5154               Only the <tt>Build-Depends</tt> and <tt>Build-Conflicts</tt>
5155               fields must be satisfied when these targets are invoked.
5156             </item>
5157             <tag><tt>build</tt>, <tt>build-indep</tt>, <tt>binary</tt>,
5158               and <tt>binary-indep</tt></tag>
5159             <item>
5160               The <tt>Build-Depends</tt>, <tt>Build-Conflicts</tt>,
5161               <tt>Build-Depends-Indep</tt>, and
5162               <tt>Build-Conflicts-Indep</tt> fields must be satisfied when
5163               these targets are invoked.
5164             </item>
5165           </taglist>
5166         </p>
5167       </sect>
5168     </chapt>
5169
5170
5171     <chapt id="sharedlibs"><heading>Shared libraries</heading>
5172
5173       <p>
5174         Packages containing shared libraries must be constructed with
5175         a little care to make sure that the shared library is always
5176         available.  This is especially important for packages whose
5177         shared libraries are vitally important, such as the C library
5178         (currently <tt>libc6</tt>).
5179       </p>
5180
5181       <p>
5182         This section deals only with public shared libraries: shared
5183         libraries that are placed in directories searched by the dynamic
5184         linker by default or which are intended to be linked against
5185         normally and possibly used by other, independent packages.  Shared
5186         libraries that are internal to a particular package or that are
5187         only loaded as dynamic modules are not covered by this section and
5188         are not subject to its requirements.
5189       </p>
5190
5191       <p>
5192         A shared library is identified by the <tt>SONAME</tt> attribute
5193         stored in its dynamic section.  When a binary is linked against a
5194         shared library, the <tt>SONAME</tt> of the shared library is
5195         recorded in the binary's <tt>NEEDED</tt> section so that the
5196         dynamic linker knows that library must be loaded at runtime.  The
5197         shared library file's full name (which usually contains additional
5198         version information not needed in the <tt>SONAME</tt>) is
5199         therefore normally not referenced directly.  Instead, the shared
5200         library is loaded by its <tt>SONAME</tt>, which exists on the file
5201         system as a symlink pointing to the full name of the shared
5202         library.  This symlink must be provided by the
5203         package.  <ref id="sharedlibs-runtime"> describes how to do this.
5204         <footnote>
5205           This is a convention of shared library versioning, but not a
5206           requirement.  Some libraries use the <tt>SONAME</tt> as the full
5207           library file name instead and therefore do not need a symlink.
5208           Most, however, encode additional information about
5209           backwards-compatible revisions as a minor version number in the
5210           file name.  The <tt>SONAME</tt> itself only changes when
5211           binaries linked with the earlier version of the shared library
5212           may no longer work, but the filename may change with each
5213           release of the library.  See <ref id="sharedlibs-runtime"> for
5214           more information.
5215         </footnote>
5216       </p>
5217
5218       <p>
5219         When linking a binary or another shared library against a shared
5220         library, the <tt>SONAME</tt> for that shared library is not yet
5221         known.  Instead, the shared library is found by looking for a file
5222         matching the library name with <tt>.so</tt> appended.  This file
5223         exists on the file system as a symlink pointing to the shared
5224         library.
5225       </p>
5226
5227       <p>
5228         Shared libraries are normally split into several binary packages.
5229         The <tt>SONAME</tt> symlink is installed by the runtime shared
5230         library package, and the bare <tt>.so</tt> symlink is installed in
5231         the development package since it's only used when linking binaries
5232         or shared libraries.  However, there are some exceptions for
5233         unusual shared libraries or for shared libraries that are also
5234         loaded as dynamic modules by other programs.
5235       </p>
5236
5237       <p>
5238         This section is primarily concerned with how the separation of
5239         shared libraries into multiple packages should be done and how
5240         dependencies on and between shared library binary packages are
5241         managed in Debian.  <ref id="libraries"> should be read in
5242         conjunction with this section and contains additional rules for
5243         the files contained in the shared library packages.
5244       </p>
5245
5246       <sect id="sharedlibs-runtime">
5247         <heading>Run-time shared libraries</heading>
5248
5249         <p>
5250           The run-time shared library must be placed in a package
5251           whose name changes whenever the <tt>SONAME</tt> of the shared
5252           library changes.  This allows several versions of the shared
5253           library to be installed at the same time, allowing installation
5254           of the new version of the shared library without immediately
5255           breaking binaries that depend on the old version.  Normally, the
5256           run-time shared library and its <tt>SONAME</tt> symlink should
5257           be placed in a package named
5258           <package><var>libraryname</var><var>soversion</var></package>,
5259           where <var>soversion</var> is the version number in
5260           the <tt>SONAME</tt> of the shared library.
5261           See <ref id="shlibs"> for detailed information on how to
5262           determine this version.  Alternatively, if it would be confusing
5263           to directly append <var>soversion</var>
5264           to <var>libraryname</var> (if, for example, <var>libraryname</var>
5265           itself ends in a number), you should use
5266           <package><var>libraryname</var>-<var>soversion</var></package>
5267           instead.
5268         </p>
5269
5270         <p>
5271           If you have several shared libraries built from the same source
5272           tree, you may lump them all together into a single shared
5273           library package provided that all of their <tt>SONAME</tt>s will
5274           always change together.  Be aware that this is not normally the
5275           case, and if the <tt>SONAME</tt>s do not change together,
5276           upgrading such a merged shared library package will be
5277           unnecessarily difficult because of file conflicts with the old
5278           version of the package.  When in doubt, always split shared
5279           library packages so that each binary package installs a single
5280           shared library.
5281         </p>
5282
5283         <p>
5284           Every time the shared library ABI changes in a way that may
5285           break binaries linked against older versions of the shared
5286           library, the <tt>SONAME</tt> of the library and the
5287           corresponding name for the binary package containing the runtime
5288           shared library should change.  Normally, this means
5289           the <tt>SONAME</tt> should change any time an interface is
5290           removed from the shared library or the signature of an interface
5291           (the number of parameters or the types of parameters that it
5292           takes, for example) is changed.  This practice is vital to
5293           allowing clean upgrades from older versions of the package and
5294           clean transitions between the old ABI and new ABI without having
5295           to upgrade every affected package simultaneously.
5296         </p>
5297
5298         <p>
5299           The <tt>SONAME</tt> and binary package name need not, and indeed
5300           normally should not, change if new interfaces are added but none
5301           are removed or changed, since this will not break binaries
5302           linked against the old shared library.  Correct versioning of
5303           dependencies on the newer shared library by binaries that use
5304           the new interfaces is handled via
5305           the <qref id="sharedlibs-shlibdeps"><tt>shlibs</tt>
5306           system</qref> or via symbols files (see
5307           <manref name="deb-symbols" section="5">).
5308         </p>
5309
5310       <p>
5311         The package should install the shared libraries under
5312         their normal names.  For example, the <package>libgdbm3</package>
5313         package should install <file>libgdbm.so.3.0.0</file> as
5314         <file>/usr/lib/libgdbm.so.3.0.0</file>.  The files should not be
5315         renamed or re-linked by any <prgn>prerm</prgn> or
5316         <prgn>postrm</prgn> scripts; <prgn>dpkg</prgn> will take care
5317         of renaming things safely without affecting running programs,
5318         and attempts to interfere with this are likely to lead to
5319         problems.
5320       </p>
5321
5322       <p>
5323         Shared libraries should not be installed executable, since
5324         the dynamic linker does not require this and trying to
5325         execute a shared library usually results in a core dump.
5326       </p>
5327
5328       <p>
5329         The run-time library package should include the symbolic link for
5330         the <tt>SONAME</tt> that <prgn>ldconfig</prgn> would create for
5331         the shared libraries.  For example,
5332         the <package>libgdbm3</package> package should include a symbolic
5333         link from <file>/usr/lib/libgdbm.so.3</file> to
5334         <file>libgdbm.so.3.0.0</file>.  This is needed so that the dynamic
5335         linker (for example <prgn>ld.so</prgn> or
5336         <prgn>ld-linux.so.*</prgn>) can find the library between the
5337         time that <prgn>dpkg</prgn> installs it and the time that
5338         <prgn>ldconfig</prgn> is run in the <prgn>postinst</prgn>
5339         script.<footnote>
5340             The package management system requires the library to be
5341             placed before the symbolic link pointing to it in the
5342             <file>.deb</file> file.  This is so that when
5343             <prgn>dpkg</prgn> comes to install the symlink
5344             (overwriting the previous symlink pointing at an older
5345             version of the library), the new shared library is already
5346             in place.  In the past, this was achieved by creating the
5347             library in the temporary packaging directory before
5348             creating the symlink.  Unfortunately, this was not always
5349             effective, since the building of the tar file in the
5350             <file>.deb</file> depended on the behavior of the underlying
5351             file system.  Some file systems (such as reiserfs) reorder
5352             the files so that the order of creation is forgotten.
5353             Since version 1.7.0, <prgn>dpkg</prgn>
5354             reorders the files itself as necessary when building a
5355             package.  Thus it is no longer important to concern
5356             oneself with the order of file creation.
5357         </footnote>
5358       </p>
5359
5360         <sect1 id="ldconfig">
5361           <heading><tt>ldconfig</tt></heading>
5362
5363         <p>
5364           Any package installing shared libraries in one of the default
5365           library directories of the dynamic linker (which are currently
5366           <file>/usr/lib</file> and <file>/lib</file>) or a directory that is
5367           listed in <file>/etc/ld.so.conf</file><footnote>
5368             These are currently
5369             <list compact="compact">
5370               <item>/usr/local/lib</item>
5371               <item>/usr/lib/libc5-compat</item>
5372               <item>/lib/libc5-compat</item>
5373             </list>
5374           </footnote>
5375           must use <prgn>ldconfig</prgn> to update the shared library
5376           system.
5377         </p>
5378
5379         <p>
5380             The package maintainer scripts must only call
5381             <prgn>ldconfig</prgn> under these circumstances:
5382             <list compact="compact">
5383               <item>When the <prgn>postinst</prgn> script is run with a
5384                   first argument of <tt>configure</tt>, the script must call
5385                   <prgn>ldconfig</prgn>, and may optionally invoke
5386                   <prgn>ldconfig</prgn> at other times.
5387               </item>
5388               <item>When the <prgn>postrm</prgn> script is run with a
5389                   first argument of <tt>remove</tt>, the script should call
5390                   <prgn>ldconfig</prgn>.
5391               </item>
5392             </list>
5393          <footnote>
5394             <p>
5395               During install or upgrade, the preinst is called before
5396               the new files are installed, so calling "ldconfig" is
5397               pointless.  The preinst of an existing package can also be
5398               called if an upgrade fails.  However, this happens during
5399               the critical time when a shared libs may exist on-disk
5400               under a temporary name.  Thus, it is dangerous and
5401               forbidden by current policy to call "ldconfig" at this
5402               time.
5403             </p>
5404
5405             <p>
5406               When a package is installed or upgraded, "postinst
5407               configure" runs after the new files are safely on-disk.
5408               Since it is perfectly safe to invoke ldconfig
5409               unconditionally in a postinst, it is OK for a package to
5410               simply put ldconfig in its postinst without checking the
5411               argument.  The postinst can also be called to recover from
5412               a failed upgrade.  This happens before any new files are
5413               unpacked, so there is no reason to call "ldconfig" at this
5414               point.
5415             </p>
5416
5417             <p>
5418               For a package that is being removed, prerm is
5419               called with all the files intact, so calling ldconfig is
5420               useless.  The other calls to "prerm" happen in the case of
5421               upgrade at a time when all the files of the old package
5422               are on-disk, so again calling "ldconfig" is pointless.
5423             </p>
5424
5425             <p>
5426               postrm, on the other hand, is called with the "remove"
5427               argument just after the files are removed, so this is
5428               the proper time to call "ldconfig" to notify the system
5429               of the fact that the shared libraries from the package
5430               are removed.  The postrm can be called at several other
5431               times.  At the time of "postrm purge", "postrm
5432               abort-install", or "postrm abort-upgrade", calling
5433               "ldconfig" is useless because the shared lib files are
5434               not on-disk.  However, when "postrm" is invoked with
5435               arguments "upgrade", "failed-upgrade", or "disappear", a
5436               shared lib may exist on-disk under a temporary filename.
5437             </p>
5438           </footnote>
5439         </p>
5440         </sect1>
5441
5442       </sect>
5443
5444       <sect id="sharedlibs-support-files">
5445         <heading>Shared library support files</heading>
5446
5447         <p>
5448           If your package contains files whose names do not change with
5449           each change in the library shared object version, you must not
5450           put them in the shared library package.  Otherwise, several
5451           versions of the shared library cannot be installed at the same
5452           time without filename clashes, making upgrades and transitions
5453           unnecessarily difficult.
5454         </p>
5455
5456         <p>
5457           It is recommended that supporting files and run-time support
5458           programs that do not need to be invoked manually by users, but
5459           are nevertheless required for the package to function, be placed
5460           (if they are binary) in a subdirectory of <file>/usr/lib</file>,
5461           preferably under <file>/usr/lib/</file><var>package-name</var>.
5462           If the program or file is architecture independent, the
5463           recommendation is for it to be placed in a subdirectory of
5464           <file>/usr/share</file> instead, preferably under
5465           <file>/usr/share/</file><var>package-name</var>.  Following the
5466           <var>package-name</var> naming convention ensures that the file
5467           names change when the shared object version changes.
5468         </p>
5469
5470         <p>
5471           Run-time support programs that use the shared library but are
5472           not required for the library to function or files used by the
5473           shared library that can be used by any version of the shared
5474           library package should instead be put in a separate package.
5475           This package might typically be named
5476           <package><var>libraryname</var>-tools</package>; note the
5477           absence of the <var>soversion</var> in the package name.
5478         </p>
5479
5480         <p>
5481           Files and support programs only useful when compiling software
5482           against the library should be included in the development
5483           package for the library.<footnote>
5484             For example, a <file><var>package-name</var>-config</file>
5485             script or <package>pkg-config</package> configuration files.
5486           </footnote>
5487         </p>
5488       </sect>
5489
5490       <sect id="sharedlibs-static">
5491         <heading>Static libraries</heading>
5492
5493       <p>
5494         The static library (<file><var>libraryname.a</var></file>)
5495         is usually provided in addition to the shared version.
5496         It is placed into the development package (see below).
5497       </p>
5498
5499       <p>
5500         In some cases, it is acceptable for a library to be
5501         available in static form only; these cases include:
5502         <list>
5503           <item>libraries for languages whose shared library support
5504                 is immature or unstable</item>
5505           <item>libraries whose interfaces are in flux or under
5506                 development (commonly the case when the library's
5507                 major version number is zero, or where the ABI breaks
5508                 across patchlevels)</item>
5509           <item>libraries which are explicitly intended to be
5510                 available only in static form by their upstream
5511                 author(s)</item>
5512         </list>
5513       </p>
5514
5515       <sect id="sharedlibs-dev">
5516         <heading>Development files</heading>
5517
5518       <p>
5519         If there are development files associated with a shared library,
5520         the source package needs to generate a binary development package
5521         named <package><var>libraryname</var><var>soversion</var>-dev</package>,
5522         or if you prefer only to support one development version at a
5523         time, <package><var>libraryname</var>-dev</package>.  Installing
5524         the development package must result in installation of all the
5525         development files necessary for compiling programs against that
5526         shared library.<footnote>
5527           This wording allows the development files to be split into
5528           several packages, such as a separate architecture-independent
5529           <package><var>libraryname</var>-headers</package>, provided that
5530           the development package depends on all the required additional
5531           packages.
5532         </footnote>
5533       </p>
5534
5535       <p>
5536         In case several development versions of a library exist, you may
5537         need to use <prgn>dpkg</prgn>'s Conflicts mechanism (see
5538         <ref id="conflicts">) to ensure that the user only installs one
5539         development version at a time (as different development versions are
5540         likely to have the same header files in them, which would cause a
5541         filename clash if both were installed).
5542       </p>
5543
5544       <p>
5545         The development package should contain a symlink for the associated
5546         shared library without a version number. For example, the
5547         <package>libgdbm-dev</package> package should include a symlink
5548         from <file>/usr/lib/libgdbm.so</file> to
5549         <file>libgdbm.so.3.0.0</file>.  This symlink is needed by the linker
5550         (<prgn>ld</prgn>) when compiling packages, as it will only look for
5551         <file>libgdbm.so</file> when compiling dynamically.
5552       </p>
5553
5554       <p>
5555         If the package provides Ada Library Information
5556         (<file>*.ali</file>) files for use with GNAT, these files must be
5557         installed read-only (mode 0444) so that GNAT will not attempt to
5558         recompile them.  This overrides the normal file mode requirements
5559         given in <ref id="permissions-owners">.
5560       </p>
5561       </sect>
5562
5563       <sect id="sharedlibs-intradeps">
5564         <heading>Dependencies between the packages of the same library</heading>
5565
5566         <p>
5567           Typically the development version should have an exact
5568           version dependency on the runtime library, to make sure that
5569           compilation and linking happens correctly.  The
5570           <tt>${binary:Version}</tt> substitution variable can be
5571           useful for this purpose.
5572           <footnote>
5573             Previously, <tt>${Source-Version}</tt> was used, but its name
5574             was confusing and it has been deprecated since dpkg 1.13.19.
5575           </footnote>
5576         </p>
5577       </sect>
5578
5579       <sect id="sharedlibs-shlibdeps">
5580         <heading>Dependencies between the library and other packages -
5581         the <tt>shlibs</tt> system</heading>
5582
5583         <p>
5584           If a package contains a binary or library which links to a
5585           shared library, we must ensure that when the package is
5586           installed on the system, all of the libraries needed are
5587           also installed.  This requirement led to the creation of the
5588           <tt>shlibs</tt> system, which is very simple in its design:
5589           any package which <em>provides</em> a shared library also
5590           provides information on the package dependencies required to
5591           ensure the presence of this library, and any package which
5592           <em>uses</em> a shared library uses this information to
5593           determine the dependencies it requires.  The files which
5594           contain the mapping from shared libraries to the necessary
5595           dependency information are called <file>shlibs</file> files.
5596         </p>
5597
5598         <p>
5599           When a package is built which contains any shared libraries, it
5600           must provide a <file>shlibs</file> file for other packages to
5601           use.  When a package is built which contains any shared
5602           libraries or compiled binaries, it must run
5603           <qref id="pkg-dpkg-shlibdeps"><prgn>dpkg-shlibdeps</prgn></qref>
5604           on these to determine the libraries used and hence the
5605           dependencies needed by this package.<footnote>
5606             <p>
5607               <prgn>dpkg-shlibdeps</prgn> will use a program
5608               like <prgn>objdump</prgn> or <prgn>readelf</prgn> to find
5609               the libraries directly needed by the binaries or shared
5610               libraries in the package.
5611             </p>
5612
5613             <p>
5614               We say that a binary <tt>foo</tt> <em>directly</em> uses
5615               a library <tt>libbar</tt> if it is explicitly linked
5616               with that library (that is, the library is listed in the ELF
5617               <tt>NEEDED</tt> attribute, caused by adding <tt>-lbar</tt>
5618               to the link line when the binary is created).  Other
5619               libraries that are needed by <tt>libbar</tt> are linked
5620               <em>indirectly</em> to <tt>foo</tt>, and the dynamic
5621               linker will load them automatically when it loads
5622               <tt>libbar</tt>.  A package should depend on the libraries
5623               it directly uses, but not the libraries it indirectly uses.
5624               The dependencies for those libraries will automatically pull
5625               in the other libraries.
5626             </p>
5627
5628             <p>
5629               A good example of where this helps is the following.  We
5630               could update <tt>libimlib</tt> with a new version that
5631               supports a new graphics format called dgf (but retaining the
5632               same major version number) and depends on <tt>libdgf</tt>.
5633               If we used <prgn>ldd</prgn> to add dependencies for every
5634               library directly or indirectly linked with a binary, every
5635               package that uses <tt>libimlib</tt> would need to be
5636               recompiled so it would also depend on <tt>libdgf</tt> or it
5637               wouldn't run due to missing symbols.  Since dependencies are
5638               only added based on ELF <tt>NEEDED</tt> attribute, packages
5639               using <tt>libimlib</tt> can rely on <tt>libimlib</tt> itself
5640               having the dependency on <tt>libdgf</tt> and so they would
5641               not need rebuilding.
5642             </p>
5643           </footnote>
5644         </p>
5645
5646         <p>
5647           In the following sections, we will first describe where the
5648           various <tt>shlibs</tt> files are to be found, then how to
5649           use <prgn>dpkg-shlibdeps</prgn>, and finally the <tt>shlibs</tt>
5650           file format and how to create them if your package contains a
5651           shared library.
5652         </p>
5653
5654       <sect1>
5655         <heading>The <tt>shlibs</tt> files present on the system</heading>
5656
5657         <p>
5658           There are several places where <tt>shlibs</tt> files are
5659           found.  The following list gives them in the order in which
5660           they are read by
5661           <qref id="pkg-dpkg-shlibdeps"><prgn>dpkg-shlibdeps</prgn></qref>.
5662           (The first one which gives the required information is used.)
5663         </p>
5664
5665         <p>
5666           <list>
5667             <item>
5668               <p><file>debian/shlibs.local</file></p>
5669
5670               <p>
5671                 This lists overrides for this package.  This file should
5672                 normally not be used, but may be needed temporarily in
5673                 unusual situations to work around bugs in other packages,
5674                 or in unusual cases where the normally declared dependency
5675                 information in the installed <file>shlibs</file> file for
5676                 a library cannot be used.  This file overrides information
5677                 obtained from any other source.
5678               </p>
5679             </item>
5680
5681             <item>
5682               <p><file>/etc/dpkg/shlibs.override</file></p>
5683
5684               <p>
5685                 This lists global overrides.  This list is normally
5686                 empty.  It is maintained by the local system
5687                 administrator.
5688               </p>
5689             </item>
5690
5691             <item>
5692               <p><file>DEBIAN/shlibs</file> files in the "build directory"</p>
5693
5694               <p>
5695                 When packages are being built,
5696                 any <file>debian/shlibs</file> files are copied into the
5697                 control information file area of the temporary build
5698                 directory and given the name <file>shlibs</file>.  These
5699                 files give details of any shared libraries included in the
5700                 same package.<footnote>
5701                   An example may help here.  Let us say that the source
5702                   package <tt>foo</tt> generates two binary
5703                   packages, <tt>libfoo2</tt> and <tt>foo-runtime</tt>.
5704                   When building the binary packages, the two packages are
5705                   created in the directories <file>debian/libfoo2</file>
5706                   and <file>debian/foo-runtime</file> respectively.
5707                   (<file>debian/tmp</file> could be used instead of one of
5708                   these.)  Since <tt>libfoo2</tt> provides the
5709                   <tt>libfoo</tt> shared library, it will require a
5710                   <tt>shlibs</tt> file, which will be installed in
5711                   <file>debian/libfoo2/DEBIAN/shlibs</file>, eventually to
5712                   become <file>/var/lib/dpkg/info/libfoo2.shlibs</file>.
5713                   When <prgn>dpkg-shlibdeps</prgn> is run on the
5714                   executable <file>debian/foo-runtime/usr/bin/foo-prog</file>,
5715                   it will examine
5716                   the <file>debian/libfoo2/DEBIAN/shlibs</file> file to
5717                   determine whether <tt>foo-prog</tt>'s library
5718                   dependencies are satisfied by any of the libraries
5719                   provided by <tt>libfoo2</tt>.  For this reason,
5720                   <prgn>dpkg-shlibdeps</prgn> must only be run once all of
5721                   the individual binary packages' <tt>shlibs</tt> files
5722                   have been installed into the build directory.
5723                 </footnote>
5724               </p>
5725             </item>
5726
5727             <item>
5728               <p><file>/var/lib/dpkg/info/*.shlibs</file></p>
5729
5730               <p>
5731                 These are the <file>shlibs</file> files corresponding to
5732                 all of the packages installed on the system, and are
5733                 maintained by the relevant package maintainers.
5734               </p>
5735             </item>
5736
5737             <item>
5738               <p><file>/etc/dpkg/shlibs.default</file></p>
5739
5740               <p>
5741                 This file lists any shared libraries whose packages
5742                 have failed to provide correct <file>shlibs</file> files.
5743                 It was used when the <file>shlibs</file> setup was first
5744                 introduced, but it is now normally empty.  It is
5745                 maintained by the <tt>dpkg</tt> maintainer.
5746               </p>
5747             </item>
5748           </list>
5749         </p>
5750       </sect1>
5751
5752       <sect1>
5753         <heading>How to use <prgn>dpkg-shlibdeps</prgn> and the
5754             <file>shlibs</file> files</heading>
5755
5756         <p>
5757           Put a call to
5758           <qref id="pkg-dpkg-shlibdeps"><prgn>dpkg-shlibdeps</prgn></qref>
5759           into your <file>debian/rules</file> file.  If your package
5760           contains only compiled binaries and libraries (but no scripts),
5761           you can use a command such as:
5762           <example compact="compact">
5763 dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \
5764   debian/tmp/usr/lib/*
5765           </example>
5766           Otherwise, you will need to explicitly list the compiled
5767           binaries and libraries.<footnote>
5768             If you are using <tt>debhelper</tt>, the
5769             <prgn>dh_shlibdeps</prgn> program will do this work for you.
5770             It will also correctly handle multi-binary packages.
5771           </footnote>
5772         </p>
5773
5774         <p>
5775           This command puts the dependency information into the
5776           <file>debian/substvars</file> file, which is then used by
5777           <prgn>dpkg-gencontrol</prgn>.  You will need to place a
5778           <tt>${shlibs:Depends}</tt> variable in the <tt>Depends</tt>
5779           field in the control file for this to work.
5780         </p>
5781
5782         <p>
5783           If you have multiple binary packages, you will need to call
5784           <prgn>dpkg-shlibdeps</prgn> on each one which contains
5785           compiled libraries or binaries.  In such a case, you will
5786           need to use the <tt>-T</tt> option to the <tt>dpkg</tt>
5787           utilities to specify a different <file>substvars</file> file.
5788         </p>
5789
5790         <p>
5791           If you are creating a udeb for use in the Debian Installer,
5792           you will need to specify that <prgn>dpkg-shlibdeps</prgn>
5793           should use the dependency line of type <tt>udeb</tt> by
5794           adding the <tt>-tudeb</tt> option<footnote>
5795             <prgn>dh_shlibdeps</prgn> from the <tt>debhelper</tt> suite
5796             will automatically add this option if it knows it is
5797             processing a udeb.
5798           </footnote>. If there is no dependency line of
5799           type <tt>udeb</tt> in the <file>shlibs</file>
5800           file, <prgn>dpkg-shlibdeps</prgn> will fall back to the regular
5801           dependency line.
5802         </p>
5803
5804         <p>
5805           For more details on <prgn>dpkg-shlibdeps</prgn>, please see
5806           <ref id="pkg-dpkg-shlibdeps"> and
5807           <manref name="dpkg-shlibdeps" section="1">.
5808         </p>
5809       </sect1>
5810
5811       <sect1 id="shlibs">
5812         <heading>The <file>shlibs</file> File Format</heading>
5813
5814         <p>
5815           Each <file>shlibs</file> file has the same format.  Lines
5816           beginning with <tt>#</tt> are considered to be comments and
5817           are ignored.  Each line is of the form:
5818           <example compact="compact">
5819 [<var>type</var>: ]<var>library-name</var> <var>soname-version</var> <var>dependencies ...</var>
5820           </example>
5821         </p>
5822
5823         <p>
5824           We will explain this by reference to the example of the
5825           <tt>zlib1g</tt> package, which (at the time of writing)
5826           installs the shared library <file>/usr/lib/libz.so.1.1.3</file>.
5827         </p>
5828
5829         <p>
5830           <var>type</var> is an optional element that indicates the type
5831           of package for which the line is valid. The only type currently
5832           in use is <tt>udeb</tt>. The colon and space after the type are
5833           required.
5834         </p>
5835
5836         <p>
5837           <var>library-name</var> is the name of the shared library,
5838           in this case <tt>libz</tt>.  (This must match the name part
5839           of the soname, see below.)
5840         </p>
5841
5842         <p>
5843           <var>soname-version</var> is the version part of the soname of
5844           the library.  The soname is the thing that must exactly match
5845           for the library to be recognized by the dynamic linker, and is
5846           usually of the form
5847           <tt><var>name</var>.so.<var>major-version</var></tt>, in our
5848           example, <tt>libz.so.1</tt>.<footnote>
5849             This can be determined using the command
5850             <example compact="compact">
5851 objdump -p /usr/lib/libz.so.1.1.3 | grep SONAME
5852             </example>
5853           </footnote>
5854           The version part is the part which comes after
5855           <tt>.so.</tt>, so in our case, it is <tt>1</tt>.  The soname may
5856           instead be of the form
5857           <tt><var>name</var>-<var>major-version</var>.so</tt>, such
5858           as <tt>libdb-4.8.so</tt>, in which case the name would
5859           be <tt>libdb</tt> and the version would be <tt>4.8</tt>.
5860         </p>
5861
5862         <p>
5863           <var>dependencies</var> has the same syntax as a dependency
5864           field in a binary package control file.  It should give
5865           details of which packages are required to satisfy a binary
5866           built against the version of the library contained in the
5867           package.  See <ref id="depsyntax"> for details.
5868         </p>
5869
5870         <p>
5871           In our example, if the first version of the <tt>zlib1g</tt>
5872           package which contained a minor number of at least
5873           <tt>1.3</tt> was <var>1:1.1.3-1</var>, then the
5874           <tt>shlibs</tt> entry for this library could say:
5875           <example compact="compact">
5876 libz 1 zlib1g (>= 1:1.1.3)
5877           </example>
5878           The version-specific dependency is to avoid warnings from
5879           the dynamic linker about using older shared libraries with
5880           newer binaries.
5881         </p>
5882
5883         <p>
5884           As zlib1g also provides a udeb containing the shared library,
5885           there would also be a second line:
5886           <example compact="compact">
5887 udeb: libz 1 zlib1g-udeb (>= 1:1.1.3)
5888           </example>
5889         </p>
5890       </sect1>
5891
5892       <sect1>
5893         <heading>Providing a <file>shlibs</file> file</heading>
5894
5895         <p>
5896           If your package provides a shared library, you need to create
5897           a <file>shlibs</file> file following the format described above.
5898           It is usual to call this file <file>debian/shlibs</file> (but if
5899           you have multiple binary packages, you might want to call it
5900           <file>debian/shlibs.<var>package</var></file> instead).  Then
5901           let <file>debian/rules</file> install it in the control
5902           information file area:
5903           <example compact="compact">
5904 install -m644 debian/shlibs debian/tmp/DEBIAN
5905           </example>
5906           or, in the case of a multi-binary package:
5907           <example compact="compact">
5908 install -m644 debian/shlibs.<var>package</var> debian/<var>package</var>/DEBIAN/shlibs
5909           </example>
5910           An alternative way of doing this is to create the
5911           <file>shlibs</file> file in the control information file area
5912           directly from <file>debian/rules</file> without using
5913           a <file>debian/shlibs</file> file at all,<footnote>
5914             This is what <prgn>dh_makeshlibs</prgn> in
5915             the <package>debhelper</package> suite does. If your package
5916             also has a udeb that provides a shared
5917             library, <prgn>dh_makeshlibs</prgn> can automatically generate
5918             the <tt>udeb:</tt> lines if you specify the name of the udeb
5919             with the <tt>--add-udeb</tt> option.
5920           </footnote>
5921           since the <file>debian/shlibs</file> file itself is ignored by
5922           <prgn>dpkg-shlibdeps</prgn>.
5923         </p>
5924
5925         <p>
5926           As <prgn>dpkg-shlibdeps</prgn> reads the
5927           <file>DEBIAN/shlibs</file> files in all of the binary packages
5928           being built from this source package, all of the
5929           <file>DEBIAN/shlibs</file> files should be installed before
5930           <prgn>dpkg-shlibdeps</prgn> is called on any of the binary
5931           packages.
5932         </p>
5933       </sect1>
5934       </sect>
5935     </chapt>
5936
5937
5938     <chapt id="opersys"><heading>The Operating System</heading>
5939
5940       <sect>
5941         <heading>File system hierarchy</heading>
5942
5943
5944         <sect1 id="fhs">
5945           <heading>File System Structure</heading>
5946
5947           <p>
5948             The location of all installed files and directories must
5949             comply with the Filesystem Hierarchy Standard (FHS),
5950             version 2.3, with the exceptions noted below, and except
5951             where doing so would violate other terms of Debian
5952             Policy.  The following exceptions to the FHS apply:
5953
5954             <enumlist>
5955               <item>
5956                 <p>
5957                   The optional rules related to user specific
5958                   configuration files for applications are stored in
5959                   the user's home directory are relaxed.  It is
5960                   recommended that such files start with the
5961                   '<tt>.</tt>' character (a "dot file"), and if an
5962                   application needs to create more than one dot file
5963                   then the preferred placement is in a subdirectory
5964                   with a name starting with a '.' character, (a "dot
5965                   directory"). In this case it is recommended the
5966                   configuration files not start with the '.'
5967                   character.
5968                 </p>
5969               </item>
5970               <item>
5971                 <p>
5972                   The requirement for amd64 to use <file>/lib64</file>
5973                   for 64 bit binaries is removed.
5974                 </p>
5975               </item>
5976               <item>
5977                 <p>
5978                   The requirement for object files, internal binaries, and
5979                   libraries, including <file>libc.so.*</file>, to be located
5980                   directly under <file>/lib{,32}</file> and
5981                   <file>/usr/lib{,32}</file> is amended, permitting files
5982                   to instead be installed to
5983                   <file>/lib/<var>triplet</var></file> and
5984                   <file>/usr/lib/<var>triplet</var></file>, where
5985                   <tt><var>triplet</var></tt> is the value returned by
5986                   <tt>dpkg-architecture -qDEB_HOST_GNU_TYPE</tt> for the
5987                   architecture of the package.  Packages may <em>not</em>
5988                   install files to any <var>triplet</var> path other
5989                   than the one matching the architecture of that package;
5990                   for instance, an <tt>Architecture: amd64</tt> package
5991                   containing 32-bit x86 libraries may not install these
5992                   libraries to <file>/usr/lib/i486-linux-gnu</file>.
5993                   <footnote>
5994                     This is necessary in order to reserve the directories for
5995                     use in cross-installation of library packages from other
5996                     architectures, as part of the planned deployment of
5997                     <tt>multiarch</tt>.
5998                   </footnote>
5999                 </p>
6000                 <p>
6001                   Applications may also use a single subdirectory under
6002                   <file>/usr/lib/<var>triplet</var></file>.
6003                 </p>
6004                 <p>
6005                   The execution time linker/loader, ld*, must still be made
6006                   available in the existing location under /lib or /lib64
6007                   since this is part of the ELF ABI for the architecture.
6008                 </p>
6009               </item>
6010               <item>
6011                 <p>
6012                   The requirement that
6013                   <file>/usr/local/share/man</file> be "synonymous"
6014                   with <file>/usr/local/man</file> is relaxed to a
6015                   recommendation</p>
6016               </item>
6017               <item>
6018                 <p>
6019                   The requirement that windowmanagers with a single
6020                   configuration file call it <file>system.*wmrc</file>
6021                   is removed, as is the restriction that the window
6022                   manager subdirectory be named identically to the
6023                   window manager name itself.
6024                 </p>
6025               </item>
6026               <item>
6027                 <p>
6028                   The requirement that boot manager configuration
6029                   files live in <file>/etc</file>, or at least are
6030                   symlinked there, is relaxed to a recommendation.
6031                 </p>
6032               </item>
6033               <item>
6034                 <p>
6035                   The following directories in the root filesystem are
6036                   additionally allowed: <file>/sys</file> and
6037                   <file>/selinux</file>. <footnote>These directories
6038                   are used as mount points to mount virtual filesystems
6039                   to get access to kernel information.</footnote>
6040                 </p>
6041               </item>
6042             </enumlist>
6043
6044           </p>
6045           <p>
6046             The version of this document referred here can be
6047             found in the <tt>debian-policy</tt> package or on <url
6048             id="http://www.debian.org/doc/packaging-manuals/fhs/"
6049               name="FHS (Debian copy)"> alongside this manual (or, if
6050             you have the <package>debian-policy</package> installed,
6051             you can try <url
6052               id="file:///usr/share/doc/debian-policy/fhs/" name="FHS
6053               (local copy)">). The
6054             latest version, which may be a more recent version, may
6055             be found on
6056             <url id="http://www.pathname.com/fhs/" name="FHS (upstream)">.
6057             Specific questions about following the standard may be
6058             asked on the <tt>debian-devel</tt> mailing list, or
6059             referred to the FHS mailing list (see the
6060             <url id="http://www.pathname.com/fhs/" name="FHS web site"> for
6061             more information).
6062           </p>
6063         </sect1>
6064
6065         <sect1>
6066           <heading>Site-specific programs</heading>
6067
6068           <p>
6069             As mandated by the FHS, packages must not place any
6070             files in <file>/usr/local</file>, either by putting them in
6071             the file system archive to be unpacked by <prgn>dpkg</prgn>
6072             or by manipulating them in their maintainer scripts.
6073           </p>
6074
6075           <p>
6076             However, the package may create empty directories below
6077             <file>/usr/local</file> so that the system administrator knows
6078             where to place site-specific files.  These are not
6079             directories <em>in</em> <file>/usr/local</file>, but are
6080             children of directories in <file>/usr/local</file>.  These
6081             directories (<file>/usr/local/*/dir/</file>)
6082             should be removed on package removal if they are
6083             empty.
6084           </p>
6085
6086           <p>
6087             Note that this applies only to
6088             directories <em>below</em> <file>/usr/local</file>,
6089             not <em>in</em> <file>/usr/local</file>.  Packages must
6090             not create sub-directories in the
6091             directory <file>/usr/local</file> itself, except those
6092             listed in FHS, section 4.5.  However, you may create
6093             directories below them as you wish. You must not remove
6094             any of the directories listed in 4.5, even if you created
6095             them.
6096           </p>
6097
6098           <p>
6099             Since <file>/usr/local</file> can be mounted read-only from a
6100             remote server, these directories must be created and
6101             removed by the <prgn>postinst</prgn> and <prgn>prerm</prgn>
6102             maintainer scripts and not be included in the
6103             <file>.deb</file> archive.  These scripts must not fail if
6104             either of these operations fail.
6105           </p>
6106
6107           <p>
6108             For example, the <tt>emacsen-common</tt> package could
6109             contain something like
6110             <example compact="compact">
6111 if [ ! -e /usr/local/share/emacs ]
6112 then
6113   if mkdir /usr/local/share/emacs 2>/dev/null
6114   then
6115     chown root:staff /usr/local/share/emacs
6116     chmod 2775 /usr/local/share/emacs
6117   fi
6118 fi
6119             </example>
6120             in its <prgn>postinst</prgn> script, and
6121             <example compact="compact">
6122 rmdir /usr/local/share/emacs/site-lisp 2>/dev/null || true
6123 rmdir /usr/local/share/emacs 2>/dev/null || true
6124             </example>
6125             in the <prgn>prerm</prgn> script.  (Note that this form is
6126             used to ensure that if the script is interrupted, the
6127             directory <file>/usr/local/share/emacs</file> will still be
6128             removed.)
6129           </p>
6130
6131           <p>
6132             If you do create a directory in <file>/usr/local</file> for
6133             local additions to a package, you should ensure that
6134             settings in <file>/usr/local</file> take precedence over the
6135             equivalents in <file>/usr</file>.
6136           </p>
6137
6138           <p>
6139             However, because <file>/usr/local</file> and its contents are
6140             for exclusive use of the local administrator, a package
6141             must not rely on the presence or absence of files or
6142             directories in <file>/usr/local</file> for normal operation.
6143           </p>
6144
6145           <p>
6146             The <file>/usr/local</file> directory itself and all the
6147             subdirectories created by the package should (by default) have
6148             permissions 2775 (group-writable and set-group-id) and be
6149             owned by <tt>root:staff</tt>.
6150           </p>
6151         </sect1>
6152
6153         <sect1>
6154           <heading>The system-wide mail directory</heading>
6155           <p>
6156             The system-wide mail directory
6157             is <file>/var/mail</file>. This directory is part of the
6158             base system and should not be owned by any particular mail
6159             agents.  The use of the old
6160             location <file>/var/spool/mail</file> is deprecated, even
6161             though the spool may still be physically located there.
6162           </p>
6163         </sect1>
6164       </sect>
6165
6166       <sect>
6167         <heading>Users and groups</heading>
6168
6169         <sect1>
6170           <heading>Introduction</heading>
6171           <p>
6172             The Debian system can be configured to use either plain or
6173             shadow passwords.
6174           </p>
6175
6176           <p>
6177             Some user ids (UIDs) and group ids (GIDs) are reserved
6178             globally for use by certain packages.  Because some
6179             packages need to include files which are owned by these
6180             users or groups, or need the ids compiled into binaries,
6181             these ids must be used on any Debian system only for the
6182             purpose for which they are allocated. This is a serious
6183             restriction, and we should avoid getting in the way of
6184             local administration policies. In particular, many sites
6185             allocate users and/or local system groups starting at 100.
6186           </p>
6187
6188           <p>
6189             Apart from this we should have dynamically allocated ids,
6190             which should by default be arranged in some sensible
6191             order, but the behavior should be configurable.
6192           </p>
6193
6194           <p>
6195             Packages other than <tt>base-passwd</tt> must not modify
6196             <file>/etc/passwd</file>, <file>/etc/shadow</file>,
6197             <file>/etc/group</file> or <file>/etc/gshadow</file>.
6198           </p>
6199         </sect1>
6200
6201         <sect1>
6202           <heading>UID and GID classes</heading>
6203           <p>
6204             The UID and GID numbers are divided into classes as
6205             follows:
6206             <taglist>
6207               <tag>0-99:</tag>
6208               <item>
6209                 <p>
6210                   Globally allocated by the Debian project, the same
6211                   on every Debian system.  These ids will appear in
6212                   the <file>passwd</file> and <file>group</file> files of all
6213                   Debian systems, new ids in this range being added
6214                   automatically as the <tt>base-passwd</tt> package is
6215                   updated.
6216                 </p>
6217
6218                 <p>
6219                   Packages which need a single statically allocated
6220                   uid or gid should use one of these; their
6221                   maintainers should ask the <tt>base-passwd</tt>
6222                   maintainer for ids.
6223                 </p>
6224               </item>
6225
6226               <tag>100-999:</tag>
6227               <item>
6228                 <p>
6229                   Dynamically allocated system users and groups.
6230                   Packages which need a user or group, but can have
6231                   this user or group allocated dynamically and
6232                   differently on each system, should use <tt>adduser
6233                   --system</tt> to create the group and/or user.
6234                   <prgn>adduser</prgn> will check for the existence of
6235                   the user or group, and if necessary choose an unused
6236                   id based on the ranges specified in
6237                   <file>adduser.conf</file>.
6238                 </p>
6239               </item>
6240
6241               <tag>1000-59999:</tag>
6242               <item>
6243                 <p>
6244                   Dynamically allocated user accounts.  By default
6245                   <prgn>adduser</prgn> will choose UIDs and GIDs for
6246                   user accounts in this range, though
6247                   <file>adduser.conf</file> may be used to modify this
6248                   behavior.
6249                 </p>
6250               </item>
6251
6252               <tag>60000-64999:</tag>
6253               <item>
6254                 <p>
6255                   Globally allocated by the Debian project, but only
6256                   created on demand. The ids are allocated centrally
6257                   and statically, but the actual accounts are only
6258                   created on users' systems on demand.
6259                 </p>
6260
6261                 <p>
6262                   These ids are for packages which are obscure or
6263                   which require many statically-allocated ids.  These
6264                   packages should check for and create the accounts in
6265                   <file>/etc/passwd</file> or <file>/etc/group</file> (using
6266                   <prgn>adduser</prgn> if it has this facility) if
6267                   necessary.  Packages which are likely to require
6268                   further allocations should have a "hole" left after
6269                   them in the allocation, to give them room to
6270                   grow.
6271                 </p>
6272               </item>
6273
6274               <tag>65000-65533:</tag>
6275               <item>
6276                 <p>Reserved.</p>
6277               </item>
6278
6279               <tag>65534:</tag>
6280               <item>
6281                 <p>
6282                   User <tt>nobody</tt>. The corresponding gid refers
6283                   to the group <tt>nogroup</tt>.
6284                 </p>
6285               </item>
6286
6287               <tag>65535:</tag>
6288               <item>
6289                 <p>
6290                   <tt>(uid_t)(-1) == (gid_t)(-1)</tt> <em>must
6291                   not</em> be used, because it is the error return
6292                   sentinel value.
6293                 </p>
6294               </item>
6295             </taglist>
6296           </p>
6297         </sect1>
6298       </sect>
6299
6300       <sect id="sysvinit">
6301         <heading>System run levels and <file>init.d</file> scripts</heading>
6302
6303         <sect1 id="/etc/init.d">
6304           <heading>Introduction</heading>
6305
6306           <p>
6307             The <file>/etc/init.d</file> directory contains the scripts
6308             executed by <prgn>init</prgn> at boot time and when the
6309             init state (or "runlevel") is changed (see <manref
6310             name="init" section="8">).
6311           </p>
6312
6313           <p>
6314             There are at least two different, yet functionally
6315             equivalent, ways of handling these scripts.  For the sake
6316             of simplicity, this document describes only the symbolic
6317             link method. However, it must not be assumed by maintainer
6318             scripts that this method is being used, and any automated
6319             manipulation of the various runlevel behaviors by
6320             maintainer scripts must be performed using
6321             <prgn>update-rc.d</prgn> as described below and not by
6322             manually installing or removing symlinks.  For information
6323             on the implementation details of the other method,
6324             implemented in the <tt>file-rc</tt> package, please refer
6325             to the documentation of that package.
6326           </p>
6327
6328           <p>
6329             These scripts are referenced by symbolic links in the
6330             <file>/etc/rc<var>n</var>.d</file> directories.  When changing
6331             runlevels, <prgn>init</prgn> looks in the directory
6332             <file>/etc/rc<var>n</var>.d</file> for the scripts it should
6333             execute, where <tt><var>n</var></tt> is the runlevel that
6334             is being changed to, or <tt>S</tt> for the boot-up
6335             scripts.
6336           </p>
6337
6338           <p>
6339             The names of the links all have the form
6340             <file>S<var>mm</var><var>script</var></file> or
6341             <file>K<var>mm</var><var>script</var></file> where
6342             <var>mm</var> is a two-digit number and <var>script</var>
6343             is the name of the script (this should be the same as the
6344             name of the actual script in <file>/etc/init.d</file>).
6345           </p>
6346
6347           <p>
6348             When <prgn>init</prgn> changes runlevel first the targets
6349             of the links whose names start with a <tt>K</tt> are
6350             executed, each with the single argument <tt>stop</tt>,
6351             followed by the scripts prefixed with an <tt>S</tt>, each
6352             with the single argument <tt>start</tt>.  (The links are
6353             those in the <file>/etc/rc<var>n</var>.d</file> directory
6354             corresponding to the new runlevel.)  The <tt>K</tt> links
6355             are responsible for killing services and the <tt>S</tt>
6356             link for starting services upon entering the runlevel.
6357           </p>
6358
6359           <p>
6360             For example, if we are changing from runlevel 2 to
6361             runlevel 3, init will first execute all of the <tt>K</tt>
6362             prefixed scripts it finds in <file>/etc/rc3.d</file>, and then
6363             all of the <tt>S</tt> prefixed scripts in that directory.
6364             The links starting with <tt>K</tt> will cause the
6365             referred-to file to be executed with an argument of
6366             <tt>stop</tt>, and the <tt>S</tt> links with an argument
6367             of <tt>start</tt>.
6368           </p>
6369
6370           <p>
6371             The two-digit number <var>mm</var> is used to determine
6372             the order in which to run the scripts: low-numbered links
6373             have their scripts run first.  For example, the
6374             <tt>K20</tt> scripts will be executed before the
6375             <tt>K30</tt> scripts.  This is used when a certain service
6376             must be started before another.  For example, the name
6377             server <prgn>bind</prgn> might need to be started before
6378             the news server <prgn>inn</prgn> so that <prgn>inn</prgn>
6379             can set up its access lists.  In this case, the script
6380             that starts <prgn>bind</prgn> would have a lower number
6381             than the script that starts <prgn>inn</prgn> so that it
6382             runs first:
6383             <example compact="compact">
6384 /etc/rc2.d/S17bind
6385 /etc/rc2.d/S70inn
6386             </example>
6387           </p>
6388
6389           <p>
6390             The two runlevels 0 (halt) and 6 (reboot) are slightly
6391             different.  In these runlevels, the links with an
6392             <tt>S</tt> prefix are still called after those with a
6393             <tt>K</tt> prefix, but they too are called with the single
6394             argument <tt>stop</tt>.
6395           </p>
6396         </sect1>
6397
6398         <sect1 id="writing-init">
6399           <heading>Writing the scripts</heading>
6400
6401           <p>
6402             Packages that include daemons for system services should
6403             place scripts in <file>/etc/init.d</file> to start or stop
6404             services at boot time or during a change of runlevel.
6405             These scripts should be named
6406             <file>/etc/init.d/<var>package</var></file>, and they should
6407             accept one argument, saying what to do:
6408
6409             <taglist>
6410               <tag><tt>start</tt></tag>
6411               <item>start the service,</item>
6412
6413               <tag><tt>stop</tt></tag>
6414               <item>stop the service,</item>
6415
6416               <tag><tt>restart</tt></tag>
6417               <item>stop and restart the service if it's already running,
6418                   otherwise start the service</item>
6419
6420               <tag><tt>reload</tt></tag>
6421               <item><p>cause the configuration of the service to be
6422                   reloaded without actually stopping and restarting
6423                   the service,</item>
6424
6425               <tag><tt>force-reload</tt></tag>
6426               <item>cause the configuration to be reloaded if the
6427                   service supports this, otherwise restart the
6428                   service.</item>
6429             </taglist>
6430
6431             The <tt>start</tt>, <tt>stop</tt>, <tt>restart</tt>, and
6432             <tt>force-reload</tt> options should be supported by all
6433             scripts in <file>/etc/init.d</file>, the <tt>reload</tt>
6434             option is optional.
6435           </p>
6436
6437           <p>
6438             The <file>init.d</file> scripts must ensure that they will
6439             behave sensibly (i.e., returning success and not starting
6440             multiple copies of a service) if invoked with <tt>start</tt>
6441             when the service is already running, or with <tt>stop</tt>
6442             when it isn't, and that they don't kill unfortunately-named
6443             user processes.  The best way to achieve this is usually to
6444             use <prgn>start-stop-daemon</prgn> with the <tt>--oknodo</tt>
6445             option.
6446           </p>
6447
6448           <p>
6449             Be careful of using <tt>set -e</tt> in <file>init.d</file>
6450             scripts.  Writing correct <file>init.d</file> scripts requires
6451             accepting various error exit statuses when daemons are already
6452             running or already stopped without aborting
6453             the <file>init.d</file> script, and common <file>init.d</file>
6454             function libraries are not safe to call with <tt>set -e</tt>
6455             in effect<footnote>
6456               <tt>/lib/lsb/init-functions</tt>, which assists in writing
6457               LSB-compliant init scripts, may fail if <tt>set -e</tt> is
6458               in effect and echoing status messages to the console fails,
6459               for example.
6460             </footnote>.  For <tt>init.d</tt> scripts, it's often easier
6461             to not use <tt>set -e</tt> and instead check the result of
6462             each command separately.
6463           </p>
6464
6465           <p>
6466             If a service reloads its configuration automatically (as
6467             in the case of <prgn>cron</prgn>, for example), the
6468             <tt>reload</tt> option of the <file>init.d</file> script
6469             should behave as if the configuration has been reloaded
6470             successfully.
6471           </p>
6472
6473           <p>
6474             The <file>/etc/init.d</file> scripts must be treated as
6475             configuration files, either (if they are present in the
6476             package, that is, in the .deb file) by marking them as
6477             <tt>conffile</tt>s, or, (if they do not exist in the .deb)
6478             by managing them correctly in the maintainer scripts (see
6479             <ref id="config-files">).  This is important since we want
6480             to give the local system administrator the chance to adapt
6481             the scripts to the local system, e.g., to disable a
6482             service without de-installing the package, or to specify
6483             some special command line options when starting a service,
6484             while making sure their changes aren't lost during the next
6485             package upgrade.
6486           </p>
6487
6488           <p>
6489             These scripts should not fail obscurely when the
6490             configuration files remain but the package has been
6491             removed, as configuration files remain on the system after
6492             the package has been removed.  Only when <prgn>dpkg</prgn>
6493             is executed with the <tt>--purge</tt> option will
6494             configuration files be removed.  In particular, as the
6495             <file>/etc/init.d/<var>package</var></file> script itself is
6496             usually a <tt>conffile</tt>, it will remain on the system
6497             if the package is removed but not purged.  Therefore, you
6498             should include a <tt>test</tt> statement at the top of the
6499             script, like this:
6500             <example compact="compact">
6501 test -f <var>program-executed-later-in-script</var> || exit 0
6502             </example>
6503           </p>
6504
6505           <p>
6506             Often there are some variables in the <file>init.d</file>
6507             scripts whose values control the behavior of the scripts,
6508             and which a system administrator is likely to want to
6509             change.  As the scripts themselves are frequently
6510             <tt>conffile</tt>s, modifying them requires that the
6511             administrator merge in their changes each time the package
6512             is upgraded and the <tt>conffile</tt> changes.  To ease
6513             the burden on the system administrator, such configurable
6514             values should not be placed directly in the script.
6515             Instead, they should be placed in a file in
6516             <file>/etc/default</file>, which typically will have the same
6517             base name as the <file>init.d</file> script.  This extra file
6518             should be sourced by the script when the script runs.  It
6519             must contain only variable settings and comments in SUSv3
6520             <prgn>sh</prgn> format.  It may either be a
6521             <tt>conffile</tt> or a configuration file maintained by
6522             the package maintainer scripts.  See <ref id="config-files">
6523             for more details.
6524           </p>
6525
6526           <p>
6527             To ensure that vital configurable values are always
6528             available, the <file>init.d</file> script should set default
6529             values for each of the shell variables it uses, either
6530             before sourcing the <file>/etc/default/</file> file or
6531             afterwards using something like the <tt>:
6532             ${VAR:=default}</tt> syntax.  Also, the <file>init.d</file>
6533             script must behave sensibly and not fail if the
6534             <file>/etc/default</file> file is deleted.
6535           </p>
6536
6537           <p>
6538             <file>/var/run</file> and <file>/var/lock</file> may be mounted
6539             as temporary filesystems<footnote>
6540                 For example, using the <tt>RAMRUN</tt> and <tt>RAMLOCK</tt>
6541                 options in <file>/etc/default/rcS</file>.
6542             </footnote>, so the <file>init.d</file> scripts must handle this
6543             correctly. This will typically amount to creating any required
6544             subdirectories dynamically when the <file>init.d</file> script
6545             is run, rather than including them in the package and relying on
6546             <prgn>dpkg</prgn> to create them.
6547           </p>
6548         </sect1>
6549
6550         <sect1>
6551           <heading>Interfacing with the initscript system</heading>
6552
6553           <p>
6554             Maintainers should use the abstraction layer provided by
6555             the <prgn>update-rc.d</prgn> and <prgn>invoke-rc.d</prgn>
6556             programs to deal with initscripts in their packages'
6557             scripts such as <prgn>postinst</prgn>, <prgn>prerm</prgn>
6558             and <prgn>postrm</prgn>.
6559           </p>
6560
6561           <p>
6562             Directly managing the /etc/rc?.d links and directly
6563             invoking the <file>/etc/init.d/</file> initscripts should
6564             be done only by packages providing the initscript
6565             subsystem (such as <prgn>sysv-rc</prgn> and
6566             <prgn>file-rc</prgn>).
6567           </p>
6568
6569           <sect2>
6570             <heading>Managing the links</heading>
6571
6572             <p>
6573               The program <prgn>update-rc.d</prgn> is provided for
6574               package maintainers to arrange for the proper creation and
6575               removal of <file>/etc/rc<var>n</var>.d</file> symbolic links,
6576               or their functional equivalent if another method is being
6577               used.  This may be used by maintainers in their packages'
6578               <prgn>postinst</prgn> and <prgn>postrm</prgn> scripts.
6579             </p>
6580
6581             <p>
6582               You must not include any <file>/etc/rc<var>n</var>.d</file>
6583               symbolic links in the actual archive or manually create or
6584               remove the symbolic links in maintainer scripts; you must
6585               use the <prgn>update-rc.d</prgn> program instead.  (The
6586               former will fail if an alternative method of maintaining
6587               runlevel information is being used.)  You must not include
6588               the <file>/etc/rc<var>n</var>.d</file> directories themselves
6589               in the archive either.  (Only the <tt>sysvinit</tt>
6590               package may do so.)
6591             </p>
6592
6593             <p>
6594               By default <prgn>update-rc.d</prgn> will start services in
6595               each of the multi-user state runlevels (2, 3, 4, and 5)
6596               and stop them in the halt runlevel (0), the single-user
6597               runlevel (1) and the reboot runlevel (6).  The system
6598               administrator will have the opportunity to customize
6599               runlevels by simply adding, moving, or removing the
6600               symbolic links in <file>/etc/rc<var>n</var>.d</file> if
6601               symbolic links are being used, or by modifying
6602               <file>/etc/runlevel.conf</file> if the <tt>file-rc</tt> method
6603               is being used.
6604             </p>
6605
6606             <p>
6607               To get the default behavior for your package, put in your
6608               <prgn>postinst</prgn> script
6609               <example compact="compact">
6610                 update-rc.d <var>package</var> defaults
6611               </example>
6612               and in your <prgn>postrm</prgn>
6613               <example compact="compact">
6614                 if [ "$1" = purge ]; then
6615                 update-rc.d <var>package</var> remove
6616                 fi
6617               </example>. Note that if your package changes runlevels
6618               or priority, you may have to remove and recreate the links,
6619               since otherwise the old links may persist. Refer to the
6620               documentation of <prgn>update-rc.d</prgn>.
6621             </p>
6622
6623             <p>
6624               This will use a default sequence number of 20.  If it does
6625               not matter when or in which order the <file>init.d</file>
6626               script is run, use this default.  If it does, then you
6627               should talk to the maintainer of the <prgn>sysvinit</prgn>
6628               package or post to <tt>debian-devel</tt>, and they will
6629               help you choose a number.
6630             </p>
6631
6632             <p>
6633               For more information about using <tt>update-rc.d</tt>,
6634               please consult its man page <manref name="update-rc.d"
6635                 section="8">.
6636             </p>
6637           </sect2>
6638
6639           <sect2>
6640             <heading>Running initscripts</heading>
6641             <p>
6642               The program <prgn>invoke-rc.d</prgn> is provided to make
6643               it easier for package maintainers to properly invoke an
6644               initscript, obeying runlevel and other locally-defined
6645               constraints that might limit a package's right to start,
6646               stop and otherwise manage services. This program may be
6647               used by maintainers in their packages' scripts.
6648             </p>
6649
6650             <p>
6651               The package maintainer scripts must use
6652               <prgn>invoke-rc.d</prgn> to invoke the
6653               <file>/etc/init.d/*</file> initscripts, instead of
6654               calling them directly.
6655             </p>
6656
6657             <p>
6658               By default, <prgn>invoke-rc.d</prgn> will pass any
6659               action requests (start, stop, reload, restart...) to the
6660               <file>/etc/init.d</file> script, filtering out requests
6661               to start or restart a service out of its intended
6662               runlevels.
6663             </p>
6664
6665             <p>
6666               Most packages will simply need to change:
6667               <example compact="compact">/etc/init.d/&lt;package&gt;
6668               &lt;action&gt;</example> in their <prgn>postinst</prgn>
6669               and <prgn>prerm</prgn> scripts to:
6670               <example compact="compact">
6671         if which invoke-rc.d >/dev/null 2>&1; then
6672                 invoke-rc.d <var>package</var> &lt;action&gt;
6673         else
6674                 /etc/init.d/<var>package</var> &lt;action&gt;
6675         fi
6676               </example>
6677             </p>
6678
6679             <p>
6680               A package should register its initscript services using
6681               <prgn>update-rc.d</prgn> before it tries to invoke them
6682               using <prgn>invoke-rc.d</prgn>. Invocation of
6683               unregistered services may fail.
6684             </p>
6685
6686             <p>
6687               For more information about using
6688               <prgn>invoke-rc.d</prgn>, please consult its man page
6689               <manref name="invoke-rc.d" section="8">.
6690             </p>
6691           </sect2>
6692         </sect1>
6693
6694         <sect1>
6695           <heading>Boot-time initialization</heading>
6696
6697           <p>
6698             There used to be another directory, <file>/etc/rc.boot</file>,
6699             which contained scripts which were run once per machine
6700             boot. This has been deprecated in favour of links from
6701             <file>/etc/rcS.d</file> to files in <file>/etc/init.d</file> as
6702             described in <ref id="/etc/init.d">.  Packages must not
6703             place files in <file>/etc/rc.boot</file>.
6704           </p>
6705         </sect1>
6706
6707         <sect1>
6708           <heading>Example</heading>
6709
6710           <p>
6711             An example on which you can base your
6712             <file>/etc/init.d</file> scripts is found in
6713             <file>/etc/init.d/skeleton</file>.
6714           </p>
6715
6716         </sect1>
6717       </sect>
6718
6719       <sect>
6720         <heading>Console messages from <file>init.d</file> scripts</heading>
6721
6722         <p>
6723           This section describes the formats to be used for messages
6724           written to standard output by the <file>/etc/init.d</file>
6725           scripts.  The intent is to improve the consistency of
6726           Debian's startup and shutdown look and feel.  For this
6727           reason, please look very carefully at the details.  We want
6728           the messages to have the same format in terms of wording,
6729           spaces, punctuation and case of letters.
6730         </p>
6731
6732         <p>
6733           Here is a list of overall rules that should be used for
6734           messages generated by <file>/etc/init.d</file> scripts.  
6735         </p>
6736
6737         <p>
6738           <list>
6739             <item>
6740                 The message should fit in one line (fewer than 80
6741                 characters), start with a capital letter and end with
6742                 a period (<tt>.</tt>) and line feed (<tt>"\n"</tt>).
6743             </item>
6744
6745             <item>
6746               If the script is performing some time consuming task in
6747               the background (not merely starting or stopping a
6748               program, for instance), an ellipsis (three dots:
6749               <tt>...</tt>) should be output to the screen, with no
6750               leading or tailing whitespace or line feeds.
6751             </item>
6752
6753             <item>
6754               The messages should appear as if the computer is telling
6755               the user what it is doing (politely :-), but should not
6756                 mention "it" directly.  For example, instead of:
6757                 <example compact="compact">
6758 I'm starting network daemons: nfsd mountd.
6759                 </example>
6760                 the message should say
6761                 <example compact="compact">
6762 Starting network daemons: nfsd mountd.
6763                 </example>
6764             </item>
6765           </list>
6766         </p>
6767
6768         <p>
6769           <tt>init.d</tt> script should use the following  standard
6770           message formats for the situations enumerated below.
6771         </p>
6772
6773         <p>
6774           <list>
6775             <item>
6776               <p>When daemons are started</p>
6777
6778               <p>
6779                 If the script starts one or more daemons, the output
6780                 should look like this (a single line, no leading
6781                 spaces):
6782                 <example compact="compact">
6783 Starting <var>description</var>: <var>daemon-1</var> ... <var>daemon-n</var>.
6784                 </example>
6785                 The <var>description</var> should describe the
6786                 subsystem the daemon or set of daemons are part of,
6787                 while <var>daemon-1</var> up to <var>daemon-n</var>
6788                 denote each daemon's name (typically the file name of
6789                 the program).
6790               </p>
6791
6792               <p>
6793                 For example, the output of <file>/etc/init.d/lpd</file>
6794                 would look like:
6795                 <example compact="compact">
6796 Starting printer spooler: lpd.
6797                 </example>
6798               </p>
6799
6800               <p>
6801                 This can be achieved by saying
6802                 <example compact="compact">
6803 echo -n "Starting printer spooler: lpd"
6804 start-stop-daemon --start --quiet --exec /usr/sbin/lpd
6805 echo "."
6806                 </example>
6807                 in the script. If there are more than one daemon to
6808                 start, the output should look like this:
6809                 <example compact="compact">
6810 echo -n "Starting remote file system services:"
6811 echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
6812 echo -n " mountd"; start-stop-daemon --start --quiet mountd
6813 echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
6814 echo "."
6815                 </example>
6816                 This makes it possible for the user to see what is
6817                 happening and when the final daemon has been started.
6818                 Care should be taken in the placement of white spaces:
6819                 in the example above the system administrators can
6820                 easily comment out a line if they don't want to start
6821                 a specific daemon, while the displayed message still
6822                 looks good.
6823               </p>
6824             </item>
6825
6826             <item>
6827               <p>When a system parameter is being set</p>
6828
6829               <p>
6830                 If you have to set up different system parameters
6831                 during the system boot, you should use this format:
6832                 <example compact="compact">
6833 Setting <var>parameter</var> to "<var>value</var>".
6834                 </example>
6835               </p>
6836
6837               <p>
6838                 You can use a statement such as the following to get
6839                 the quotes right:
6840                 <example compact="compact">
6841 echo "Setting DNS domainname to \"$domainname\"."
6842                 </example>
6843               </p>
6844
6845               <p>
6846                 Note that the same symbol (<tt>"</tt>) <!-- " --> is used
6847                 for the left and right quotation marks.  A grave accent
6848                 (<tt>`</tt>) is not a quote character; neither is an
6849                 apostrophe (<tt>'</tt>).
6850               </p>
6851             </item>
6852
6853             <item>
6854               <p>When a daemon is stopped or restarted</p>
6855
6856               <p>
6857                 When you stop or restart a daemon, you should issue a
6858                 message identical to the startup message, except that
6859                 <tt>Starting</tt> is replaced with <tt>Stopping</tt>
6860                 or <tt>Restarting</tt> respectively.
6861               </p>
6862
6863               <p>
6864                 For example, stopping the printer daemon will look like
6865                 this:
6866                 <example compact="compact">
6867 Stopping printer spooler: lpd.
6868                 </example>
6869               </p>
6870             </item>
6871
6872             <item>
6873               <p>When something is executed</p>
6874
6875               <p>
6876                 There are several examples where you have to run a
6877                 program at system startup or shutdown to perform a
6878                 specific task, for example, setting the system's clock
6879                 using <prgn>netdate</prgn> or killing all processes
6880                 when the system shuts down.  Your message should look
6881                 like this:
6882                 <example compact="compact">
6883 Doing something very useful...done.
6884                 </example>
6885                 You should print the <tt>done.</tt> immediately after
6886                 the job has been completed, so that the user is
6887                 informed why they have to wait.  You can get this
6888                 behavior by saying
6889                 <example compact="compact">
6890 echo -n "Doing something very useful..."
6891 do_something
6892 echo "done."
6893                 </example>
6894                 in your script.
6895               </p>
6896             </item>
6897
6898             <item>
6899               <p>When the configuration is reloaded</p>
6900
6901               <p>
6902                 When a daemon is forced to reload its configuration
6903                 files you should use the following format:
6904                 <example compact="compact">
6905 Reloading <var>description</var> configuration...done.
6906                 </example>
6907                 where <var>description</var> is the same as in the
6908                 daemon starting message.
6909               </p>
6910             </item>
6911           </list>
6912         </p>
6913       </sect>
6914
6915       <sect>
6916         <heading>Cron jobs</heading>
6917
6918         <p>
6919           Packages must not modify the configuration file
6920           <file>/etc/crontab</file>, and they must not modify the files in
6921           <file>/var/spool/cron/crontabs</file>.</p>
6922
6923         <p>
6924           If a package wants to install a job that has to be executed
6925           via cron, it should place a file with the name of the
6926           package in one or more of the following directories:
6927           <example compact="compact">
6928 /etc/cron.hourly
6929 /etc/cron.daily
6930 /etc/cron.weekly
6931 /etc/cron.monthly
6932           </example>
6933           As these directory names imply, the files within them are
6934           executed on an hourly, daily, weekly, or monthly basis,
6935           respectively. The exact times are listed in
6936           <file>/etc/crontab</file>.</p>
6937
6938         <p>
6939           All files installed in any of these directories must be
6940           scripts (e.g., shell scripts or Perl scripts) so that they
6941           can easily be modified by the local system administrator.
6942           In addition, they must be treated as configuration files.
6943         </p>
6944
6945         <p>
6946           If a certain job has to be executed at some other frequency or
6947           at a specific time, the package should install a file
6948           <file>/etc/cron.d/<var>package</var></file>. This file uses the
6949           same syntax as <file>/etc/crontab</file> and is processed by
6950           <prgn>cron</prgn> automatically. The file must also be
6951           treated as a configuration file. (Note that entries in the
6952           <file>/etc/cron.d</file> directory are not handled by
6953           <prgn>anacron</prgn>. Thus, you should only use this
6954           directory for jobs which may be skipped if the system is not
6955           running.)</p>
6956         <p>
6957           Unlike <file>crontab</file> files described in the IEEE Std
6958           1003.1-2008 (POSIX.1) available from
6959           <url id="http://www.opengroup.org/onlinepubs/9699919799/"
6960                name="The Open Group">, the files in
6961           <file>/etc/cron.d</file> and the file
6962           <file>/etc/crontab</file> have seven fields; namely:
6963           <enumlist>
6964             <item>Minute [0,59]</item>
6965             <item>Hour [0,23]</item>
6966             <item>Day of the month [1,31]</item>
6967             <item>Month of the year [1,12]</item>
6968             <item>Day of the week ([0,6] with 0=Sunday)</item>
6969             <item>Username</item>
6970             <item>Command to be run</item>
6971           </enumlist>
6972           Ranges of numbers are allowed.  Ranges are two numbers
6973           separated with a hyphen.  The specified range is inclusive.
6974           Lists are allowed.  A list is a set of numbers (or ranges)
6975           separated by commas. Step values can be used in conjunction
6976           with ranges.
6977         </p>
6978
6979         <p>
6980           The scripts or <tt>crontab</tt> entries in these directories should
6981           check if all necessary programs are installed before they
6982           try to execute them. Otherwise, problems will arise when a
6983           package was removed but not purged since configuration files
6984           are kept on the system in this situation.
6985         </p>
6986
6987         <p>
6988           Any <tt>cron</tt> daemon must provide
6989           <file>/usr/bin/crontab</file> and support normal
6990           <tt>crontab</tt> entries as specified in POSIX. The daemon
6991           must also support names for days and months, ranges, and
6992           step values. It has to support <file>/etc/crontab</file>,
6993           and correctly execute the scripts in
6994           <file>/etc/cron.d</file>. The daemon must also correctly
6995           execute scripts in
6996           <file>/etc/cron.{hourly,daily,weekly,monthly}</file>.
6997         </p>
6998       </sect>
6999
7000       <sect id="menus">
7001         <heading>Menus</heading>
7002
7003         <p>
7004           The Debian <tt>menu</tt> package provides a standard
7005           interface between packages providing applications and
7006           <em>menu programs</em> (either X window managers or
7007           text-based menu programs such as <prgn>pdmenu</prgn>).
7008         </p>
7009
7010         <p>
7011           All packages that provide applications that need not be
7012           passed any special command line arguments for normal
7013           operation should register a menu entry for those
7014           applications, so that users of the <tt>menu</tt> package
7015           will automatically get menu entries in their window
7016           managers, as well in shells like <tt>pdmenu</tt>.
7017         </p>
7018
7019         <p>
7020           Menu entries should follow the current menu policy.
7021         </p>
7022
7023         <p>
7024           The menu policy can be found in the <tt>menu-policy</tt>
7025           files in the <tt>debian-policy</tt> package.
7026           It is also available from the Debian web mirrors at
7027           <tt><url name="/doc/packaging-manuals/menu-policy/"
7028                 id="http://www.debian.org/doc/packaging-manuals/menu-policy/"></tt>.
7029         </p>
7030
7031         <p>
7032           Please also refer to the <em>Debian Menu System</em>
7033           documentation that comes with the <package>menu</package>
7034           package for information about how to register your
7035           applications.
7036         </p>
7037       </sect>
7038
7039       <sect id="mime">
7040         <heading>Multimedia handlers</heading>
7041
7042         <p>
7043           MIME (Multipurpose Internet Mail Extensions, RFCs 2045-2049)
7044           is a mechanism for encoding files and data streams and
7045           providing meta-information about them, in particular their
7046           type (e.g.  audio or video) and format (e.g. PNG, HTML,
7047           MP3).
7048         </p>
7049
7050         <p>
7051           Registration of MIME type handlers allows programs like mail
7052           user agents and web browsers to invoke these handlers to
7053           view, edit or display MIME types they don't support directly.
7054         </p>
7055
7056         <p>
7057           Packages which provide the ability to view/show/play,
7058           compose, edit or print MIME types should register themselves
7059           as such following the current MIME support policy.
7060         </p>
7061
7062         <p>
7063           The MIME support policy can be found in the <tt>mime-policy</tt>
7064           files in the <tt>debian-policy</tt> package.
7065           It is also available from the Debian web mirrors at
7066           <tt><url name="/doc/packaging-manuals/mime-policy/"
7067                 id="http://www.debian.org/doc/packaging-manuals/mime-policy/"></tt>.
7068         </p>
7069
7070       </sect>
7071
7072       <sect>
7073         <heading>Keyboard configuration</heading>
7074
7075         <p>
7076           To achieve a consistent keyboard configuration so that all
7077           applications interpret a keyboard event the same way, all
7078           programs in the Debian distribution must be configured to
7079           comply with the following guidelines.
7080         </p>
7081
7082         <p>
7083           The following keys must have the specified interpretations:
7084
7085           <taglist>
7086             <tag><tt>&lt;--</tt></tag>
7087             <item>delete the character to the left of the cursor</item>
7088
7089             <tag><tt>Delete</tt></tag>
7090             <item>delete the character to the right of the cursor</item>
7091
7092             <tag><tt>Control+H</tt></tag>
7093             <item>emacs: the help prefix</item>
7094           </taglist>
7095
7096           The interpretation of any keyboard events should be
7097           independent of the terminal that is used, be it a virtual
7098           console, an X terminal emulator, an rlogin/telnet session,
7099           etc.
7100         </p>
7101
7102         <p>
7103           The following list explains how the different programs
7104           should be set up to achieve this:
7105         </p>
7106
7107         <p>
7108           <list>
7109             <item>
7110                 <tt>&lt;--</tt> generates <tt>KB_BackSpace</tt> in X.
7111             </item>
7112
7113             <item>
7114                 <tt>Delete</tt> generates <tt>KB_Delete</tt> in X.
7115             </item>
7116
7117             <item>
7118                 X translations are set up to make
7119                 <tt>KB_Backspace</tt> generate ASCII DEL, and to make
7120                 <tt>KB_Delete</tt> generate <tt>ESC [ 3 ~</tt> (this
7121                 is the vt220 escape code for the "delete character"
7122                 key).  This must be done by loading the X resources
7123                 using <prgn>xrdb</prgn> on all local X displays, not
7124                 using the application defaults, so that the
7125                 translation resources used correspond to the
7126                 <prgn>xmodmap</prgn> settings.
7127             </item>
7128
7129             <item>
7130                 The Linux console is configured to make
7131                 <tt>&lt;--</tt> generate DEL, and <tt>Delete</tt>
7132                 generate <tt>ESC [ 3 ~</tt>.
7133             </item>
7134
7135             <item>
7136                 X applications are configured so that <tt>&lt;</tt>
7137                 deletes left, and <tt>Delete</tt> deletes right.  Motif
7138                 applications already work like this.
7139             </item>
7140
7141             <item>
7142                 Terminals should have <tt>stty erase ^?</tt> .
7143             </item>
7144
7145             <item>
7146                 The <tt>xterm</tt> terminfo entry should have <tt>ESC
7147                 [ 3 ~</tt> for <tt>kdch1</tt>, just as for
7148                 <tt>TERM=linux</tt> and <tt>TERM=vt220</tt>.
7149             </item>
7150
7151             <item>
7152                 Emacs is programmed to map <tt>KB_Backspace</tt> or
7153                 the <tt>stty erase</tt> character to
7154                 <tt>delete-backward-char</tt>, and <tt>KB_Delete</tt>
7155                 or <tt>kdch1</tt> to <tt>delete-forward-char</tt>, and
7156                 <tt>^H</tt> to <tt>help</tt> as always.
7157             </item>
7158
7159             <item>
7160                 Other applications use the <tt>stty erase</tt>
7161                 character and <tt>kdch1</tt> for the two delete keys,
7162                 with ASCII DEL being "delete previous character" and
7163                 <tt>kdch1</tt> being "delete character under
7164                 cursor".
7165             </item>
7166
7167           </list>
7168         </p>
7169
7170         <p>
7171           This will solve the problem except for the following
7172           cases:
7173         </p>
7174
7175         <p>
7176           <list>
7177             <item>
7178                 Some terminals have a <tt>&lt;--</tt> key that cannot
7179                 be made to produce anything except <tt>^H</tt>.  On
7180                 these terminals Emacs help will be unavailable on
7181                 <tt>^H</tt> (assuming that the <tt>stty erase</tt>
7182                 character takes precedence in Emacs, and has been set
7183                 correctly).  <tt>M-x help</tt> or <tt>F1</tt> (if
7184                 available) can be used instead.
7185             </item>
7186
7187             <item>
7188                 Some operating systems use <tt>^H</tt> for <tt>stty
7189                 erase</tt>.  However, modern telnet versions and all
7190                 rlogin versions propagate <tt>stty</tt> settings, and
7191                 almost all UNIX versions honour <tt>stty erase</tt>.
7192                 Where the <tt>stty</tt> settings are not propagated
7193                 correctly, things can be made to work by using
7194                 <tt>stty</tt> manually.
7195             </item>
7196
7197             <item>
7198                 Some systems (including previous Debian versions) use
7199                 <prgn>xmodmap</prgn> to arrange for both
7200                 <tt>&lt;--</tt> and <tt>Delete</tt> to generate
7201                 <tt>KB_Delete</tt>.  We can change the behavior of
7202                 their X clients using the same X resources that we use
7203                 to do it for our own clients, or configure our clients
7204                 using their resources when things are the other way
7205                 around.  On displays configured like this
7206                 <tt>Delete</tt> will not work, but <tt>&lt;--</tt>
7207                 will.
7208             </item>
7209
7210             <item>
7211                 Some operating systems have different <tt>kdch1</tt>
7212                 settings in their <tt>terminfo</tt> database for
7213                 <tt>xterm</tt> and others.  On these systems the
7214                 <tt>Delete</tt> key will not work correctly when you
7215                 log in from a system conforming to our policy, but
7216                 <tt>&lt;--</tt> will.
7217             </item>
7218           </list>
7219         </p>
7220       </sect>
7221
7222       <sect>
7223         <heading>Environment variables</heading>
7224
7225         <p>
7226           A program must not depend on environment variables to get
7227           reasonable defaults.  (That's because these environment
7228           variables would have to be set in a system-wide
7229           configuration file like <file>/etc/profile</file>, which is not
7230           supported by all shells.)
7231         </p>
7232
7233         <p>
7234           If a program usually depends on environment variables for its
7235           configuration, the program should be changed to fall back to
7236           a reasonable default configuration if these environment
7237           variables are not present. If this cannot be done easily
7238           (e.g., if the source code of a non-free program is not
7239           available), the program must be replaced by a small
7240           "wrapper" shell script which sets the environment variables
7241           if they are not already defined, and calls the original program.
7242         </p>
7243
7244         <p>
7245           Here is an example of a wrapper script for this purpose:
7246
7247           <example compact="compact">
7248 #!/bin/sh
7249 BAR=${BAR:-/var/lib/fubar}
7250 export BAR
7251 exec /usr/lib/foo/foo "$@"
7252           </example>
7253         </p>
7254
7255         <p>
7256           Furthermore, as <file>/etc/profile</file> is a configuration
7257           file of the <prgn>base-files</prgn> package, other packages must
7258           not put any environment variables or other commands into that
7259           file.
7260         </p>
7261       </sect>
7262
7263       <sect id="doc-base">
7264         <heading>Registering Documents using doc-base</heading>
7265
7266         <p>
7267           The <package>doc-base</package> package implements a
7268           flexible mechanism for handling and presenting
7269           documentation. The recommended practice is for every Debian
7270           package that provides online documentation (other than just
7271           manual pages) to register these documents with
7272           <package>doc-base</package> by installing a
7273           <package>doc-base</package> control file via the
7274           <prgn/install-docs/ script at installation time and
7275           de-register the manuals again when the package is removed.
7276         </p> 
7277         <p>
7278           Please refer to the documentation that comes with the
7279           <package>doc-base</package>  package for information and
7280           details. 
7281         </p>
7282       </sect>
7283
7284     </chapt>
7285
7286
7287     <chapt id="files">
7288       <heading>Files</heading>
7289
7290       <sect id="binaries">
7291         <heading>Binaries</heading>
7292
7293         <p>
7294           Two different packages must not install programs with
7295           different functionality but with the same filenames.  (The
7296           case of two programs having the same functionality but
7297           different implementations is handled via "alternatives" or
7298           the "Conflicts" mechanism.  See <ref id="maintscripts"> and
7299           <ref id="conflicts"> respectively.)  If this case happens,
7300           one of the programs must be renamed.  The maintainers should
7301           report this to the <tt>debian-devel</tt> mailing list and
7302           try to find a consensus about which program will have to be
7303           renamed.  If a consensus cannot be reached, <em>both</em>
7304           programs must be renamed.
7305         </p>
7306
7307         <p>
7308          By default, when a package is being built, any binaries
7309          created should include debugging information, as well as
7310          being compiled with optimization.  You should also turn on
7311          as many reasonable compilation warnings as possible; this
7312          makes life easier for porters, who can then look at build
7313          logs for possible problems.  For the C programming language,
7314          this means the following compilation parameters should be
7315          used:
7316           <example compact="compact">
7317 CC = gcc
7318 CFLAGS = -O2 -g -Wall # sane warning options vary between programs
7319 LDFLAGS = # none
7320 INSTALL = install -s # (or use strip on the files in debian/tmp)
7321           </example>
7322         </p>
7323
7324         <p>
7325           Note that by default all installed binaries should be stripped,
7326           either by using the <tt>-s</tt> flag to
7327           <prgn>install</prgn>, or by calling <prgn>strip</prgn> on
7328           the binaries after they have been copied into
7329           <file>debian/tmp</file> but before the tree is made into a
7330           package.
7331         </p>
7332
7333         <p>
7334           Although binaries in the build tree should be compiled with
7335           debugging information by default, it can often be difficult to
7336           debug programs if they are also subjected to compiler
7337           optimization.  For this reason, it is recommended to support the
7338           standardized environment variable <tt>DEB_BUILD_OPTIONS</tt>
7339           (see <ref id="debianrules-options">).  This variable can contain
7340           several flags to change how a package is compiled and built.
7341         </p>
7342
7343         <p>
7344           It is up to the package maintainer to decide what
7345           compilation options are best for the package.  Certain
7346           binaries (such as computationally-intensive programs) will
7347           function better with certain flags (<tt>-O3</tt>, for
7348           example); feel free to use them.  Please use good judgment
7349           here.  Don't use flags for the sake of it; only use them
7350           if there is good reason to do so.  Feel free to override
7351           the upstream author's ideas about which compilation
7352           options are best: they are often inappropriate for our
7353           environment.
7354         </p>
7355       </sect>
7356
7357
7358       <sect id="libraries">
7359         <heading>Libraries</heading>
7360
7361         <p>
7362           If the package is <strong>architecture: any</strong>, then
7363           the shared library compilation and linking flags must have
7364           <tt>-fPIC</tt>, or the package shall not build on some of
7365           the supported architectures<footnote>
7366             <p>
7367               If you are using GCC, <tt>-fPIC</tt> produces code with
7368               relocatable position independent code, which is required for
7369               most architectures to create a shared library, with i386 and
7370               perhaps some others where non position independent code is
7371               permitted in a shared library.
7372             </p>
7373             <p>
7374               Position independent code may have a performance penalty,
7375               especially on <tt>i386</tt>. However, in most cases the
7376               speed penalty must be measured against the memory wasted on
7377               the few architectures where non position independent code is
7378               even possible.
7379             </p>
7380           </footnote>. Any exception to this rule must be discussed on
7381           the mailing list <em>debian-devel@lists.debian.org</em>, and
7382           a rough consensus obtained.  The reasons for not compiling
7383           with <tt>-fPIC</tt> flag must be recorded in the file
7384           <tt>README.Debian</tt>, and care must be taken to either
7385           restrict the architecture or arrange for <tt>-fPIC</tt> to
7386           be used on architectures where it is required.<footnote>
7387             <p>
7388               Some of the reasons why this might be required is if the
7389               library contains hand crafted assembly code that is not
7390               relocatable, the speed penalty is excessive for compute
7391               intensive libs, and similar reasons.
7392             </p>
7393           </footnote>
7394         </p>
7395         <p>
7396           As to the static libraries, the common case is not to have
7397           relocatable code, since there is no benefit, unless in specific
7398           cases; therefore the static version must not be compiled
7399           with the <tt>-fPIC</tt> flag. Any exception to this rule
7400           should be discussed on the mailing list
7401           <em>debian-devel@lists.debian.org</em>,  and the reasons for
7402           compiling with the <tt>-fPIC</tt> flag must be recorded in
7403           the file <tt>README.Debian</tt>. <footnote>
7404             <p>
7405               Some of the reasons for linking static libraries with
7406               the <tt>-fPIC</tt> flag are if, for example, one needs a
7407               Perl API for a library that is under rapid development,
7408               and has an unstable API, so shared libraries are
7409               pointless at this phase of the library's development. In
7410               that case, since Perl needs a library with relocatable
7411               code, it may make sense to create a static library with
7412               relocatable code. Another reason cited is if you are
7413               distilling various libraries into a common shared
7414               library, like <tt>mklibs</tt> does in the Debian
7415               installer project.
7416             </p>
7417           </footnote>
7418         </p>
7419         <p>
7420           In other words, if both a shared and a static library is
7421           being built, each source unit (<tt>*.c</tt>, for example,
7422           for C files) will need to be compiled twice, for the normal
7423           case. 
7424         </p>
7425
7426         <p>
7427           Libraries should be built with threading support and to be
7428           thread-safe if the library supports this.
7429         </p>
7430
7431         <p>
7432           Although not enforced by the build tools, shared libraries
7433           must be linked against all libraries that they use symbols from
7434           in the same way that binaries are.  This ensures the correct
7435           functioning of the <qref id="sharedlibs-shlibdeps">shlibs</qref>
7436           system and guarantees that all libraries can be safely opened
7437           with <tt>dlopen()</tt>.  Packagers may wish to use the gcc
7438           option <tt>-Wl,-z,defs</tt> when building a shared library.
7439           Since this option enforces symbol resolution at build time,
7440           a missing library reference will be caught early as a fatal
7441           build error.
7442         </p>
7443
7444         <p>
7445           All installed shared libraries should be stripped with
7446           <example compact="compact">
7447 strip --strip-unneeded <var>your-lib</var>
7448           </example>
7449           (The option <tt>--strip-unneeded</tt> makes
7450           <prgn>strip</prgn> remove only the symbols which aren't
7451           needed for relocation processing.)  Shared libraries can
7452           function perfectly well when stripped, since the symbols for
7453           dynamic linking are in a separate part of the ELF object
7454           file.<footnote>
7455               You might also want to use the options
7456               <tt>--remove-section=.comment</tt> and
7457               <tt>--remove-section=.note</tt> on both shared libraries
7458               and executables, and <tt>--strip-debug</tt> on static
7459               libraries.
7460           </footnote>
7461         </p>
7462
7463         <p>
7464           Note that under some circumstances it may be useful to
7465           install a shared library unstripped, for example when
7466           building a separate package to support debugging.
7467         </p>
7468
7469         <p>
7470           Shared object files (often <file>.so</file> files) that are not
7471           public libraries, that is, they are not meant to be linked
7472           to by third party executables (binaries of other packages),
7473           should be installed in subdirectories of the
7474           <file>/usr/lib</file> directory.  Such files are exempt from the
7475           rules that govern ordinary shared libraries, except that
7476           they must not be installed executable and should be
7477           stripped.<footnote>
7478               A common example are the so-called "plug-ins",
7479               internal shared objects that are dynamically loaded by
7480               programs using <manref name="dlopen" section="3">.
7481           </footnote>
7482         </p>
7483
7484         <p>
7485           Packages that use <prgn>libtool</prgn> to create and install
7486           their shared libraries install a file containing additional
7487           metadata (ending in <file>.la</file>) alongside the library.
7488           For public libraries intended for use by other packages, these
7489           files normally should not be included in the Debian package,
7490           since the information they include is not necessary to link with
7491           the shared library on Debian and can add unnecessary additional
7492           dependencies to other programs or libraries.<footnote>
7493             These files store, among other things, all libraries on which
7494             that shared library depends.  Unfortunately, if
7495             the <file>.la</file> file is present and contains that
7496             dependency information, using <prgn>libtool</prgn> when
7497             linking against that library will cause the resulting program
7498             or library to be linked against those dependencies as well,
7499             even if this is unnecessary.  This can create unneeded
7500             dependencies on shared library packages that would otherwise
7501             be hidden behind the library ABI, and can make library
7502             transitions to new SONAMEs unnecessarily complicated and
7503             difficult to manage.
7504           </footnote>
7505           If the <file>.la</file> file is required for that library (if,
7506           for instance, it's loaded via <tt>libltdl</tt> in a way that
7507           requires that meta-information), the <tt>dependency_libs</tt>
7508           setting in the <file>.la</file> file should normally be set to
7509           the empty string.  If the shared library development package has
7510           historically included the <file>.la</file>, it must be retained
7511           in the development package (with <tt>dependency_libs</tt>
7512           emptied) until all libraries that depend on it have removed or
7513           emptied <tt>dependency_libs</tt> in their <file>.la</file>
7514           files to prevent linking with those other libraries
7515           using <prgn>libtool</prgn> from failing.
7516         </p>
7517
7518         <p>
7519           If the <file>.la</file> must be included, it should be included
7520           in the development (<tt>-dev</tt>) package, unless the library
7521           will be loaded by <prgn>libtool</prgn>'s <tt>libltdl</tt>
7522           library.  If it is intended for use with <tt>libltdl</tt>,
7523           the <file>.la</file> files must go in the run-time library
7524           package.
7525         </p>
7526
7527         <p>
7528           These requirements for handling of <file>.la</file> files do not
7529           apply to loadable modules or libraries not installed in
7530           directories searched by default by the dynamic linker.  Packages
7531           installing loadable modules will frequently need to install
7532           the <file>.la</file> files alongside the modules so that they
7533           can be loaded by <tt>libltdl</tt>.  <tt>dependency_libs</tt>
7534           does not need to be modified for libraries or modules that are
7535           not installed in directories searched by the dynamic linker by
7536           default and not intended for use by other packages.
7537         </p>
7538
7539         <p>
7540           You must make sure that you use only released versions of
7541           shared libraries to build your packages; otherwise other
7542           users will not be able to run your binaries
7543           properly. Producing source packages that depend on
7544           unreleased compilers is also usually a bad
7545           idea.
7546         </p>
7547       </sect>
7548
7549
7550       <sect>
7551         <heading>Shared libraries</heading>
7552         <p>
7553           This section has moved to <ref id="sharedlibs">.
7554         </p>
7555       </sect>
7556
7557
7558       <sect id="scripts">
7559         <heading>Scripts</heading>
7560
7561         <p>
7562           All command scripts, including the package maintainer
7563           scripts inside the package and used by <prgn>dpkg</prgn>,
7564           should have a <tt>#!</tt> line naming the shell to be used
7565           to interpret them.
7566         </p>
7567
7568         <p>
7569           In the case of Perl scripts this should be
7570           <tt>#!/usr/bin/perl</tt>.
7571         </p>
7572
7573         <p>
7574           When scripts are installed into a directory in the system
7575           PATH, the script name should not include an extension such
7576           as <tt>.sh</tt> or <tt>.pl</tt> that denotes the scripting
7577           language currently used to implement it.
7578         </p>
7579         <p>
7580           Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>) other than
7581           <file>init.d</file> scripts should almost certainly start
7582           with <tt>set -e</tt> so that errors are detected.
7583           <file>init.d</file> scripts are something of a special case, due
7584           to how frequently they need to call commands that are allowed to
7585           fail, and it may instead be easier to check the exit status of
7586           commands directly.  See <ref id="writing-init"> for more
7587           information about writing <file>init.d</file> scripts.
7588         </p>
7589         <p>
7590           Every script should use <tt>set -e</tt> or check the exit status
7591           of <em>every</em> command.
7592         </p>
7593         <p>
7594           Scripts may assume that <file>/bin/sh</file> implements the
7595           SUSv3 Shell Command Language<footnote>
7596             Single UNIX Specification, version 3, which is also IEEE
7597             1003.1-2004 (POSIX), and is available on the World Wide Web
7598             from <url id="http://www.unix.org/version3/online.html"
7599                       name="The Open Group"> after free
7600             registration.</footnote>
7601           plus the following additional features not mandated by
7602           SUSv3:<footnote>
7603             These features are in widespread use in the Linux community
7604             and are implemented in all of bash, dash, and ksh, the most
7605             common shells users may wish to use as <file>/bin/sh</file>.
7606           </footnote>
7607           <list>
7608             <item><tt>echo -n</tt>, if implemented as a shell built-in,
7609               must not generate a newline.</item>
7610             <item><tt>test</tt>, if implemented as a shell built-in, must
7611               support <tt>-a</tt> and <tt>-o</tt> as binary logical
7612               operators.</item>
7613             <item><tt>local</tt> to create a scoped variable must be
7614               supported, including listing multiple variables in a single
7615               local command and assigning a value to a variable at the
7616               same time as localizing it.  <tt>local</tt> may or
7617               may not preserve the variable value from an outer scope if
7618               no assignment is present.  Uses such as:
7619 <example compact>
7620 fname () {
7621     local a b c=delta d
7622     # ... use a, b, c, d ...
7623 }
7624 </example>
7625               must be supported and must set the value of <tt>c</tt> to
7626               <tt>delta</tt>.
7627             </item>
7628             <item>The XSI extension to <prgn>kill</prgn> allowing <tt>kill
7629               -<var>signal</var></tt>, where <var>signal</var> is either
7630               the name of a signal or one of the numeric signals listed in
7631               the XSI extension (0, 1, 2, 3, 6, 9, 14, and 15), must be
7632               supported if <prgn>kill</prgn> is implemented as a shell
7633               built-in.
7634             </item>
7635             <item>The XSI extension to <prgn>trap</prgn> allowing numeric
7636               signals must be supported.  In addition to the signal
7637               numbers listed in the extension, which are the same as for
7638               <prgn>kill</prgn> above, 13 (SIGPIPE) must be allowed.
7639             </item>
7640           </list>
7641           If a shell script requires non-SUSv3 features from the shell
7642           interpreter other than those listed above, the appropriate shell
7643           must be specified in the first line of the script (e.g.,
7644           <tt>#!/bin/bash</tt>) and the package must depend on the package
7645           providing the shell (unless the shell package is marked
7646           "Essential", as in the case of <prgn>bash</prgn>).
7647         </p>
7648
7649         <p>
7650           You may wish to restrict your script to SUSv3 features plus the
7651           above set when possible so that it may use <file>/bin/sh</file>
7652           as its interpreter. If your script works with <prgn>dash</prgn>
7653           (originally called <prgn>ash</prgn>), it probably complies with
7654           the above requirements, but if you are in doubt, use
7655           <file>/bin/bash</file>.
7656         </p>
7657
7658         <p>
7659           Perl scripts should check for errors when making any
7660           system calls, including <tt>open</tt>, <tt>print</tt>,
7661           <tt>close</tt>, <tt>rename</tt> and <tt>system</tt>.
7662         </p>
7663
7664         <p>
7665           <prgn>csh</prgn> and <prgn>tcsh</prgn> should be avoided as
7666           scripting languages.  See <em>Csh Programming Considered
7667           Harmful</em>, one of the <tt>comp.unix.*</tt> FAQs, which
7668           can be found at <url id="http://www.faqs.org/faqs/unix-faq/shell/csh-whynot/">.
7669           If an upstream package comes with <prgn>csh</prgn> scripts
7670           then you must make sure that they start with
7671           <tt>#!/bin/csh</tt> and make your package depend on the
7672           <prgn>c-shell</prgn> virtual package.
7673         </p>
7674
7675         <p>
7676           Any scripts which create files in world-writeable
7677           directories (e.g., in <file>/tmp</file>) must use a
7678           mechanism which will fail atomically if a file with the same
7679           name already exists.
7680         </p>
7681
7682         <p>
7683           The Debian base system provides the <prgn>tempfile</prgn>
7684           and <prgn>mktemp</prgn> utilities for use by scripts for
7685           this purpose.
7686         </p>
7687       </sect>
7688
7689
7690       <sect>
7691         <heading>Symbolic links</heading>
7692
7693         <p>
7694           In general, symbolic links within a top-level directory
7695           should be relative, and symbolic links pointing from one
7696           top-level directory into another should be absolute. (A
7697           top-level directory is a sub-directory of the root
7698           directory <file>/</file>.)
7699         </p>
7700
7701         <p>
7702           In addition, symbolic links should be specified as short as
7703           possible, i.e., link targets like <file>foo/../bar</file> are
7704           deprecated.
7705         </p>
7706
7707         <p>
7708           Note that when creating a relative link using
7709           <prgn>ln</prgn> it is not necessary for the target of the
7710           link to exist relative to the working directory you're
7711           running <prgn>ln</prgn> from, nor is it necessary to change
7712           directory to the directory where the link is to be made.
7713           Simply include the string that should appear as the target
7714           of the link (this will be a pathname relative to the
7715           directory in which the link resides) as the first argument
7716           to <prgn>ln</prgn>.
7717         </p>
7718
7719         <p>
7720           For example, in your <prgn>Makefile</prgn> or
7721           <file>debian/rules</file>, you can do things like:
7722           <example compact="compact">
7723 ln -fs gcc $(prefix)/bin/cc
7724 ln -fs gcc debian/tmp/usr/bin/cc
7725 ln -fs ../sbin/sendmail $(prefix)/bin/runq
7726 ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
7727           </example>
7728         </p>
7729
7730         <p>
7731           A symbolic link pointing to a compressed file should always
7732           have the same file extension as the referenced file. (For
7733           example, if a file <file>foo.gz</file> is referenced by a
7734           symbolic link, the filename of the link has to end with
7735           "<file>.gz</file>" too, as in <file>bar.gz</file>.)
7736         </p>
7737       </sect>
7738
7739       <sect>
7740         <heading>Device files</heading>
7741
7742         <p>
7743           Packages must not include device files or named pipes in the
7744           package file tree.
7745         </p>
7746
7747         <p>
7748           If a package needs any special device files that are not
7749           included in the base system, it must call
7750           <prgn>MAKEDEV</prgn> in the <prgn>postinst</prgn> script,
7751           after notifying the user<footnote>
7752               This notification could be done via a (low-priority)
7753               debconf message, or an echo (printf) statement.
7754           </footnote>.
7755         </p>
7756
7757         <p>
7758           Packages must not remove any device files in the
7759           <prgn>postrm</prgn> or any other script. This is left to the
7760           system administrator.
7761         </p>
7762
7763         <p>
7764           Debian uses the serial devices
7765           <file>/dev/ttyS*</file>. Programs using the old
7766           <file>/dev/cu*</file> devices should be changed to use
7767           <file>/dev/ttyS*</file>.
7768         </p>
7769
7770         <p>
7771           Named pipes needed by the package must be created in
7772           the <prgn>postinst</prgn> script<footnote>
7773             It's better to use <prgn>mkfifo</prgn> rather
7774             than <prgn>mknod</prgn> to create named pipes so that
7775             automated checks for packages incorrectly creating device
7776             files with <prgn>mknod</prgn> won't have false positives.
7777           </footnote> and removed in
7778           the <prgn>prerm</prgn> or <prgn>postrm</prgn> script as
7779           appropriate.
7780         </p>
7781       </sect>
7782
7783       <sect id="config-files">
7784         <heading>Configuration files</heading>
7785
7786         <sect1>
7787           <heading>Definitions</heading>
7788
7789           <p>
7790             <taglist>
7791               <tag>configuration file</tag>
7792               <item>
7793                   A file that affects the operation of a program, or
7794                   provides site- or host-specific information, or
7795                   otherwise customizes the behavior of a program.
7796                   Typically, configuration files are intended to be
7797                   modified by the system administrator (if needed or
7798                   desired) to conform to local policy or to provide
7799                   more useful site-specific behavior.
7800               </item>
7801
7802               <tag><tt>conffile</tt></tag>
7803               <item>
7804                   A file listed in a package's <tt>conffiles</tt>
7805                   file, and is treated specially by <prgn>dpkg</prgn>
7806                   (see <ref id="configdetails">).
7807               </item>
7808             </taglist>
7809           </p>
7810
7811           <p>
7812             The distinction between these two is important; they are
7813             not interchangeable concepts. Almost all
7814             <tt>conffile</tt>s are configuration files, but many
7815             configuration files are not <tt>conffiles</tt>.
7816           </p>
7817
7818           <p>
7819             As noted elsewhere, <file>/etc/init.d</file> scripts,
7820             <file>/etc/default</file> files, scripts installed in
7821             <file>/etc/cron.{hourly,daily,weekly,monthly}</file>, and cron
7822             configuration installed in <file>/etc/cron.d</file> must be
7823             treated as configuration files.  In general, any script that
7824             embeds configuration information is de-facto a configuration
7825             file and should be treated as such.
7826           </p>
7827         </sect1>
7828
7829         <sect1>
7830           <heading>Location</heading>
7831
7832           <p>
7833             Any configuration files created or used by your package
7834             must reside in <file>/etc</file>. If there are several,
7835             consider creating a subdirectory of <file>/etc</file>
7836             named after your package.
7837           </p>
7838
7839           <p>
7840             If your package creates or uses configuration files
7841             outside of <file>/etc</file>, and it is not feasible to modify
7842             the package to use <file>/etc</file> directly, put the files
7843             in <file>/etc</file> and create symbolic links to those files
7844             from the location that the package requires.
7845           </p>
7846         </sect1>
7847
7848         <sect1>
7849           <heading>Behavior</heading>
7850
7851           <p>
7852             Configuration file handling must conform to the following
7853             behavior:
7854             <list compact="compact">
7855               <item>
7856                   local changes must be preserved during a package
7857                   upgrade, and
7858               </item>
7859               <item>
7860                   configuration files must be preserved when the
7861                   package is removed, and only deleted when the
7862                   package is purged.
7863               </item>
7864             </list>
7865             Obsolete configuration files without local changes may be
7866             removed by the package during upgrade.
7867           </p>
7868
7869           <p>
7870             The easy way to achieve this behavior is to make the
7871             configuration file a <tt>conffile</tt>. This is
7872             appropriate only if it is possible to distribute a default
7873             version that will work for most installations, although
7874             some system administrators may choose to modify it. This
7875             implies that the default version will be part of the
7876             package distribution, and must not be modified by the
7877             maintainer scripts during installation (or at any other
7878             time).
7879           </p>
7880
7881           <p>
7882             In order to ensure that local changes are preserved
7883             correctly, no package may contain or make hard links to
7884             conffiles.<footnote>
7885                 Rationale: There are two problems with hard links.
7886                 The first is that some editors break the link while
7887                 editing one of the files, so that the two files may
7888                 unwittingly become unlinked and different.  The second
7889                 is that <prgn>dpkg</prgn> might break the hard link
7890                 while upgrading <tt>conffile</tt>s.
7891             </footnote>
7892           </p>
7893
7894           <p>
7895             The other way to do it is via the maintainer scripts.  In
7896             this case, the configuration file must not be listed as a
7897             <tt>conffile</tt> and must not be part of the package
7898             distribution. If the existence of a file is required for
7899             the package to be sensibly configured it is the
7900             responsibility of the package maintainer to provide
7901             maintainer scripts which correctly create, update and
7902             maintain the file and remove it on purge.  (See <ref
7903             id="maintainerscripts"> for more information.)  These
7904             scripts must be idempotent (i.e., must work correctly if
7905             <prgn>dpkg</prgn> needs to re-run them due to errors
7906             during installation or removal), must cope with all the
7907             variety of ways <prgn>dpkg</prgn> can call maintainer
7908             scripts, must not overwrite or otherwise mangle the user's
7909             configuration without asking, must not ask unnecessary
7910             questions (particularly during upgrades), and must
7911             otherwise be good citizens.
7912           </p>
7913
7914           <p>
7915             The scripts are not required to configure every possible
7916             option for the package, but only those necessary to get
7917             the package running on a given system. Ideally the
7918             sysadmin should not have to do any configuration other
7919             than that done (semi-)automatically by the
7920             <prgn>postinst</prgn> script.
7921           </p>
7922
7923           <p>
7924             A common practice is to create a script called
7925             <file><var>package</var>-configure</file> and have the
7926             package's <prgn>postinst</prgn> call it if and only if the
7927             configuration file does not already exist.  In certain
7928             cases it is useful for there to be an example or template
7929             file which the maintainer scripts use.  Such files should
7930             be in <file>/usr/share/<var>package</var></file> or
7931             <file>/usr/lib/<var>package</var></file> (depending on whether
7932             they are architecture-independent or not).  There should
7933             be symbolic links to them from
7934             <file>/usr/share/doc/<var>package</var>/examples</file> if
7935             they are examples, and should be perfectly ordinary
7936             <prgn>dpkg</prgn>-handled files (<em>not</em>
7937             configuration files).
7938           </p>
7939
7940           <p>
7941             These two styles of configuration file handling must
7942             not be mixed, for that way lies madness:
7943             <prgn>dpkg</prgn> will ask about overwriting the file
7944             every time the package is upgraded.
7945           </p>
7946         </sect1>
7947
7948         <sect1>
7949           <heading>Sharing configuration files</heading>
7950
7951           <p>
7952             Packages which specify the same file as a
7953             <tt>conffile</tt> must be tagged as <em>conflicting</em>
7954             with each other.  (This is an instance of the general rule
7955             about not sharing files.  Note that neither alternatives
7956             nor diversions are likely to be appropriate in this case;
7957             in particular, <prgn>dpkg</prgn> does not handle diverted
7958             <tt>conffile</tt>s well.)
7959           </p>
7960
7961           <p>
7962             The maintainer scripts must not alter a <tt>conffile</tt>
7963             of <em>any</em> package, including the one the scripts
7964             belong to.
7965           </p>
7966
7967           <p>
7968             If two or more packages use the same configuration file
7969             and it is reasonable for both to be installed at the same
7970             time, one of these packages must be defined as
7971             <em>owner</em> of the configuration file, i.e., it will be
7972             the package which handles that file as a configuration
7973             file.  Other packages that use the configuration file must
7974             depend on the owning package if they require the
7975             configuration file to operate. If the other package will
7976             use the configuration file if present, but is capable of
7977             operating without it, no dependency need be declared.
7978           </p>
7979
7980           <p>
7981             If it is desirable for two or more related packages to
7982             share a configuration file <em>and</em> for all of the
7983             related packages to be able to modify that configuration
7984             file, then the following should be done:
7985             <enumlist compact="compact">
7986               <item>
7987                   One of the related packages (the "owning" package)
7988                   will manage the configuration file with maintainer
7989                   scripts as described in the previous section.
7990               </item>
7991               <item>
7992                   The owning package should also provide a program
7993                   that the other packages may use to modify the
7994                   configuration file.
7995               </item>
7996               <item>
7997                   The related packages must use the provided program
7998                   to make any desired modifications to the
7999                   configuration file.  They should either depend on
8000                   the core package to guarantee that the configuration
8001                   modifier program is available or accept gracefully
8002                   that they cannot modify the configuration file if it
8003                   is not.  (This is in addition to the fact that the
8004                   configuration file may not even be present in the
8005                   latter scenario.)
8006               </item>
8007             </enumlist>
8008           </p>
8009
8010           <p>
8011             Sometimes it's appropriate to create a new package which
8012             provides the basic infrastructure for the other packages
8013             and which manages the shared configuration files.  (The
8014             <tt>sgml-base</tt> package is a good example.)
8015           </p>
8016         </sect1>
8017
8018         <sect1>
8019           <heading>User configuration files ("dotfiles")</heading>
8020
8021           <p>
8022             The files in <file>/etc/skel</file> will automatically be
8023             copied into new user accounts by <prgn>adduser</prgn>.
8024             No other program should reference the files in
8025             <file>/etc/skel</file>.
8026           </p>
8027
8028           <p>
8029             Therefore, if a program needs a dotfile to exist in
8030             advance in <file>$HOME</file> to work sensibly, that dotfile
8031             should be installed in <file>/etc/skel</file> and treated as a
8032             configuration file.
8033           </p>
8034
8035           <p>
8036             However, programs that require dotfiles in order to
8037             operate sensibly are a bad thing, unless they do create
8038             the dotfiles themselves automatically.
8039           </p>
8040
8041           <p>
8042             Furthermore, programs should be configured by the Debian
8043             default installation to behave as closely to the upstream
8044             default behavior as possible.
8045           </p>
8046
8047           <p>
8048             Therefore, if a program in a Debian package needs to be
8049             configured in some way in order to operate sensibly, that
8050             should be done using a site-wide configuration file placed
8051             in <file>/etc</file>.  Only if the program doesn't support a
8052             site-wide default configuration and the package maintainer
8053             doesn't have time to add it may a default per-user file be
8054             placed in <file>/etc/skel</file>.
8055           </p>
8056
8057           <p>
8058             <file>/etc/skel</file> should be as empty as we can make it.
8059             This is particularly true because there is no easy (or
8060             necessarily desirable) mechanism for ensuring that the
8061             appropriate dotfiles are copied into the accounts of
8062             existing users when a package is installed.
8063           </p>
8064         </sect1>
8065       </sect>
8066
8067       <sect>
8068         <heading>Log files</heading>
8069         <p>
8070           Log files should usually be named
8071           <file>/var/log/<var>package</var>.log</file>.  If you have many
8072           log files, or need a separate directory for permission
8073           reasons (<file>/var/log</file> is writable only by
8074           <file>root</file>), you should usually create a directory named
8075           <file>/var/log/<var>package</var></file> and place your log
8076           files there.
8077         </p>
8078
8079         <p>
8080           Log files must be rotated occasionally so that they don't grow
8081           indefinitely.  The best way to do this is to install a log
8082           rotation configuration file in the
8083           directory <file>/etc/logrotate.d</file>, normally
8084           named <file>/etc/logrotate.d/<var>package</var></file>, and use
8085           the facilities provided by <prgn>logrotate</prgn>.
8086           <footnote>
8087             <p>
8088               The traditional approach to log files has been to set up
8089               <em>ad hoc</em> log rotation schemes using simple shell
8090               scripts and cron.  While this approach is highly
8091               customizable, it requires quite a lot of sysadmin work.
8092               Even though the original Debian system helped a little
8093               by automatically installing a system which can be used
8094               as a template, this was deemed not enough.
8095             </p>
8096
8097             <p>
8098               The use of <prgn>logrotate</prgn>, a program developed
8099               by Red Hat, is better, as it centralizes log management.
8100               It has both a configuration file
8101               (<file>/etc/logrotate.conf</file>) and a directory where
8102               packages can drop their individual log rotation
8103               configurations (<file>/etc/logrotate.d</file>).
8104             </p>
8105           </footnote>
8106           Here is a good example for a logrotate config
8107           file (for more information see <manref name="logrotate"
8108             section="8">):
8109           <example compact="compact">
8110 /var/log/foo/*.log {
8111     rotate 12
8112     weekly
8113     compress
8114     missingok
8115     postrotate
8116         start-stop-daemon -K -p /var/run/foo.pid -s HUP -x /usr/sbin/foo -q
8117     endscript
8118 }
8119           </example>
8120           This rotates all files under <file>/var/log/foo</file>, saves 12
8121           compressed generations, and tells the daemon to reopen its log
8122           files after the log rotation.  It skips this log rotation
8123           (via <tt>missingok</tt>) if no such log file is present, which
8124           avoids errors if the package is removed but not purged.
8125         </p>
8126
8127         <p>
8128           Log files should be removed when the package is
8129           purged (but not when it is only removed).  This should be
8130           done by the <prgn>postrm</prgn> script when it is called
8131           with the argument <tt>purge</tt> (see <ref
8132           id="removedetails">).
8133         </p>
8134       </sect>
8135
8136       <sect id="permissions-owners">
8137         <heading>Permissions and owners</heading>
8138
8139         <p>
8140           The rules in this section are guidelines for general use.
8141           If necessary you may deviate from the details below.
8142           However, if you do so you must make sure that what is done
8143           is secure and you should try to be as consistent as possible
8144           with the rest of the system.  You should probably also
8145           discuss it on <prgn>debian-devel</prgn> first.
8146         </p>
8147
8148         <p>
8149           Files should be owned by <tt>root:root</tt>, and made
8150           writable only by the owner and universally readable (and
8151           executable, if appropriate), that is mode 644 or 755.
8152         </p>
8153
8154         <p>
8155           Directories should be mode 755 or (for group-writability)
8156           mode 2775.  The ownership of the directory should be
8157           consistent with its mode: if a directory is mode 2775, it
8158           should be owned by the group that needs write access to
8159           it.<footnote>
8160             <p>
8161               When a package is upgraded, and the owner or permissions
8162               of a file included in the package has changed, dpkg
8163               arranges for the ownership and permissions to be
8164               correctly set upon installation. However, this does not
8165               extend to directories; the permissions and ownership of
8166               directories already on the system does not change on
8167               install or upgrade of packages.  This makes sense, since
8168               otherwise common directories like <tt>/usr</tt> would
8169               always be in flux.  To correctly change permissions of a
8170               directory the package owns, explicit action is required,
8171               usually in the <tt>postinst</tt> script. Care must be
8172               taken to handle downgrades as well, in that case.
8173             </p>
8174           </footnote>
8175         </p>
8176
8177         <p>
8178           Control information files should be owned by <tt>root:root</tt>
8179           and either mode 644 (for most files) or mode 755 (for
8180           executables such as <qref id="maintscripts">maintainer
8181           scripts</qref>).
8182         </p>
8183
8184         <p>
8185           Setuid and setgid executables should be mode 4755 or 2755
8186           respectively, and owned by the appropriate user or group.
8187           They should not be made unreadable (modes like 4711 or
8188           2711 or even 4111); doing so achieves no extra security,
8189           because anyone can find the binary in the freely available
8190           Debian package; it is merely inconvenient.  For the same
8191           reason you should not restrict read or execute permissions
8192           on non-set-id executables.
8193         </p>
8194
8195         <p>
8196           Some setuid programs need to be restricted to particular
8197           sets of users, using file permissions.  In this case they
8198           should be owned by the uid to which they are set-id, and by
8199           the group which should be allowed to execute them.  They
8200           should have mode 4754; again there is no point in making
8201           them unreadable to those users who must not be allowed to
8202           execute them.
8203         </p>
8204
8205         <p>
8206           It is possible to arrange that the system administrator can
8207           reconfigure the package to correspond to their local
8208           security policy by changing the permissions on a binary:
8209           they can do this by using <prgn>dpkg-statoverride</prgn>, as
8210           described below.<footnote>
8211             Ordinary files installed by <prgn>dpkg</prgn> (as
8212             opposed to <tt>conffile</tt>s and other similar objects)
8213             normally have their permissions reset to the distributed
8214             permissions when the package is reinstalled.  However,
8215             the use of <prgn>dpkg-statoverride</prgn> overrides this
8216             default behavior.
8217           </footnote>
8218           Another method you should consider is to create a group for
8219           people allowed to use the program(s) and make any setuid
8220           executables executable only by that group.
8221         </p>
8222
8223         <p>
8224           If you need to create a new user or group for your package
8225           there are two possibilities.  Firstly, you may need to
8226           make some files in the binary package be owned by this
8227           user or group, or you may need to compile the user or
8228           group id (rather than just the name) into the binary
8229           (though this latter should be avoided if possible, as in
8230           this case you need a statically allocated id).</p>
8231
8232         <p>
8233           If you need a statically allocated id, you must ask for a
8234           user or group id from the <tt>base-passwd</tt> maintainer,
8235           and must not release the package until you have been
8236           allocated one.  Once you have been allocated one you must
8237           either make the package depend on a version of the
8238           <tt>base-passwd</tt> package with the id present in
8239           <file>/etc/passwd</file> or <file>/etc/group</file>, or arrange for
8240           your package to create the user or group itself with the
8241           correct id (using <tt>adduser</tt>) in its
8242           <prgn>preinst</prgn> or <prgn>postinst</prgn>.  (Doing it in
8243           the <prgn>postinst</prgn> is to be preferred if it is
8244           possible, otherwise a pre-dependency will be needed on the
8245           <tt>adduser</tt> package.)
8246         </p>
8247
8248         <p>
8249           On the other hand, the program might be able to determine
8250           the uid or gid from the user or group name at runtime, so
8251           that a dynamically allocated id can be used.  In this case
8252           you should choose an appropriate user or group name,
8253           discussing this on <prgn>debian-devel</prgn> and checking
8254           with the <package/base-passwd/ maintainer that it is unique and that
8255           they do not wish you to use a statically allocated id
8256           instead.  When this has been checked you must arrange for
8257           your package to create the user or group if necessary using
8258           <prgn>adduser</prgn> in the <prgn>preinst</prgn> or
8259           <prgn>postinst</prgn> script (again, the latter is to be
8260           preferred if it is possible).
8261         </p>
8262
8263         <p>
8264           Note that changing the numeric value of an id associated
8265           with a name is very difficult, and involves searching the
8266           file system for all appropriate files.  You need to think
8267           carefully whether a static or dynamic id is required, since
8268           changing your mind later will cause problems.
8269         </p>
8270
8271         <sect1><heading>The use of <prgn>dpkg-statoverride</prgn></heading>
8272           <p>
8273             This section is not intended as policy, but as a
8274             description of the use of <prgn>dpkg-statoverride</prgn>.
8275           </p>
8276
8277           <p>
8278             If a system administrator wishes to have a file (or
8279             directory or other such thing) installed with owner and
8280             permissions different from those in the distributed Debian
8281             package, they can use the <prgn>dpkg-statoverride</prgn>
8282             program to instruct <prgn>dpkg</prgn> to use the different
8283             settings every time the file is installed.  Thus the
8284             package maintainer should distribute the files with their
8285             normal permissions, and leave it for the system
8286             administrator to make any desired changes.  For example, a
8287             daemon which is normally required to be setuid root, but
8288             in certain situations could be used without being setuid,
8289             should be installed setuid in the <tt>.deb</tt>.  Then the
8290             local system administrator can change this if they wish.
8291             If there are two standard ways of doing it, the package
8292             maintainer can use <tt>debconf</tt> to find out the
8293             preference, and call <prgn>dpkg-statoverride</prgn> in the
8294             maintainer script if necessary to accommodate the system
8295             administrator's choice. Care must be taken during
8296             upgrades to not override an existing setting.
8297           </p>
8298
8299           <p>
8300             Given the above, <prgn>dpkg-statoverride</prgn> is
8301             essentially a tool for system administrators and would not
8302             normally be needed in the maintainer scripts.  There is
8303             one type of situation, though, where calls to
8304             <prgn>dpkg-statoverride</prgn> would be needed in the
8305             maintainer scripts, and that involves packages which use
8306             dynamically allocated user or group ids.  In such a
8307             situation, something like the following idiom can be very
8308             helpful in the package's <prgn>postinst</prgn>, where
8309             <tt>sysuser</tt> is a dynamically allocated id:
8310             <example>
8311 for i in /usr/bin/foo /usr/sbin/bar
8312 do
8313   # only do something when no setting exists
8314   if ! dpkg-statoverride --list $i >/dev/null 2>&1
8315   then
8316     #include: debconf processing, question about foo and bar
8317     if [ "$RET" = "true" ] ; then
8318       dpkg-statoverride --update --add sysuser root 4755 $i
8319     fi
8320   fi
8321 done
8322             </example>
8323             The corresponding code to remove the override when the package
8324             is purged would be:
8325             <example>
8326 for i in /usr/bin/foo /usr/sbin/bar
8327 do
8328   if dpkg-statoverride --list $i >/dev/null 2>&1
8329   then
8330     dpkg-statoverride --remove $i
8331   fi
8332 done
8333             </example>
8334           </p>
8335         </sect1>
8336       </sect>
8337     </chapt>
8338
8339
8340     <chapt id="customized-programs">
8341       <heading>Customized programs</heading>
8342
8343       <sect id="arch-spec">
8344         <heading>Architecture specification strings</heading>
8345
8346         <p>
8347           If a program needs to specify an <em>architecture specification
8348           string</em> in some place, it should select one of the strings
8349           provided by <tt>dpkg-architecture -L</tt>. The strings are in
8350           the format <tt><var>os</var>-<var>arch</var></tt>, though the OS
8351           part is sometimes elided, as when the OS is Linux.
8352         </p>
8353
8354         <p>
8355           Note that we don't want to use
8356           <tt><var>arch</var>-debian-linux</tt> to apply to the rule
8357           <tt><var>architecture</var>-<var>vendor</var>-<var>os</var></tt>
8358           since this would make our programs incompatible with other
8359           Linux distributions.  We also don't use something like
8360           <tt><var>arch</var>-unknown-linux</tt>, since the
8361           <tt>unknown</tt> does not look very good.
8362         </p>
8363
8364         <sect1 id="arch-wildcard-spec">
8365           <heading>Architecture wildcards</heading>
8366
8367           <p>
8368             A package may specify an architecture wildcard. Architecture
8369             wildcards are in the format <tt>any</tt> (which matches every
8370             architecture), <tt><var>os</var></tt>-any, or
8371             any-<tt><var>cpu</var></tt>. <footnote>
8372               Internally, the package system normalizes the GNU triplets
8373               and the Debian arches into Debian arch triplets (which are
8374               kind of inverted GNU triplets), with the first component of
8375               the triplet representing the libc and ABI in use, and then
8376               does matching against those triplets.  However, such
8377               triplets are an internal implementation detail that should
8378               not be used by packages directly.  The libc and ABI portion
8379               is handled internally by the package system based on
8380               the <var>os</var> and <var>cpu</var>.
8381             </footnote>
8382           </p>
8383         </sect1>
8384       </sect>
8385
8386       <sect>
8387         <heading>Daemons</heading>
8388
8389         <p>
8390           The configuration files <file>/etc/services</file>,
8391           <file>/etc/protocols</file>, and <file>/etc/rpc</file> are managed
8392           by the <prgn>netbase</prgn> package and must not be modified
8393           by other packages.
8394         </p>
8395
8396         <p>
8397           If a package requires a new entry in one of these files, the
8398           maintainer should get in contact with the
8399           <prgn>netbase</prgn> maintainer, who will add the entries
8400           and release a new version of the <prgn>netbase</prgn>
8401           package.
8402         </p>
8403
8404         <p>
8405           The configuration file <file>/etc/inetd.conf</file> must not be
8406           modified by the package's scripts except via the
8407           <prgn>update-inetd</prgn> script or the
8408           <file>DebianNet.pm</file> Perl module.  See their documentation
8409           for details on how to add entries.
8410         </p>
8411
8412         <p>
8413           If a package wants to install an example entry into
8414           <file>/etc/inetd.conf</file>, the entry must be preceded with
8415           exactly one hash character (<tt>#</tt>). Such lines are
8416           treated as "commented out by user" by the
8417           <prgn>update-inetd</prgn> script and are not changed or
8418           activated during package updates.
8419         </p>
8420       </sect>
8421
8422       <sect>
8423         <heading>Using pseudo-ttys and modifying wtmp, utmp and
8424         lastlog</heading>
8425
8426         <p>
8427           Some programs need to create pseudo-ttys. This should be done
8428           using Unix98 ptys if the C library supports it. The resulting
8429           program must not be installed setuid root, unless that
8430           is required for other functionality.
8431         </p>
8432
8433         <p>
8434           The files <file>/var/run/utmp</file>, <file>/var/log/wtmp</file> and
8435           <file>/var/log/lastlog</file> must be installed writable by
8436           group <tt>utmp</tt>.  Programs which need to modify those
8437           files must be installed setgid <tt>utmp</tt>.
8438         </p>
8439       </sect>
8440
8441       <sect>
8442         <heading>Editors and pagers</heading>
8443
8444         <p>
8445           Some programs have the ability to launch an editor or pager
8446           program to edit or display a text document.  Since there are
8447           lots of different editors and pagers available in the Debian
8448           distribution, the system administrator and each user should
8449           have the possibility to choose their preferred editor and
8450           pager.
8451         </p>
8452
8453         <p>
8454           In addition, every program should choose a good default
8455           editor/pager if none is selected by the user or system
8456           administrator.
8457         </p>
8458
8459         <p>
8460           Thus, every program that launches an editor or pager must
8461           use the EDITOR or PAGER environment variable to determine
8462           the editor or pager the user wishes to use.  If these
8463           variables are not set, the programs <file>/usr/bin/editor</file>
8464           and <file>/usr/bin/pager</file> should be used, respectively.
8465         </p>
8466
8467         <p>
8468           These two files are managed through the <prgn>dpkg</prgn>
8469           "alternatives" mechanism.  Every package providing an editor or
8470           pager must call the <prgn>update-alternatives</prgn> script to
8471           register as an alternative for <file>/usr/bin/editor</file>
8472           or <file>/usr/bin/pager</file> as appropriate.  The alternative
8473           should have a slave alternative
8474           for <file>/usr/share/man/man1/editor.1.gz</file>
8475           or <file>/usr/share/man/man1/pager.1.gz</file> pointing to the
8476           corresponding manual page.
8477         </p>
8478
8479         <p>
8480           If it is very hard to adapt a program to make use of the
8481           EDITOR or PAGER variables, that program may be configured to
8482           use <file>/usr/bin/sensible-editor</file> and
8483           <file>/usr/bin/sensible-pager</file> as the editor or pager
8484           program respectively.  These are two scripts provided in the
8485           <package>sensible-utils</package> package that check the EDITOR
8486           and PAGER variables and launch the appropriate program, and fall
8487           back to <file>/usr/bin/editor</file>
8488           and <file>/usr/bin/pager</file> if the variable is not set.
8489         </p>
8490
8491         <p>
8492           A program may also use the VISUAL environment variable to
8493           determine the user's choice of editor.  If it exists, it
8494           should take precedence over EDITOR.  This is in fact what
8495           <file>/usr/bin/sensible-editor</file> does.
8496         </p>
8497
8498         <p>
8499           It is not required for a package to depend on
8500           <tt>editor</tt> and <tt>pager</tt>, nor is it required for a
8501           package to provide such virtual packages.<footnote>
8502               The Debian base system already provides an editor and a
8503               pager program.
8504           </footnote>
8505         </p>
8506       </sect>
8507
8508       <sect id="web-appl">
8509         <heading>Web servers and applications</heading>
8510
8511         <p>
8512           This section describes the locations and URLs that should
8513           be used by all web servers and web applications in the
8514           Debian system.
8515         </p>
8516
8517         <p>
8518           <enumlist>
8519             <item>
8520                 Cgi-bin executable files are installed in the
8521                 directory
8522                 <example compact="compact">
8523 /usr/lib/cgi-bin/<var>cgi-bin-name</var>
8524                 </example>
8525                 or a subdirectory of that directory, and should be
8526                 referred to as
8527                 <example compact="compact">
8528 http://localhost/cgi-bin/<var>cgi-bin-name</var>
8529                 </example>
8530                 (possibly with a subdirectory name
8531                 before <var>cgi-bin-name</var>).
8532             </item>
8533
8534             <item>
8535               <p>Access to HTML documents</p>
8536
8537               <p>
8538                 HTML documents for a package are stored in
8539                 <file>/usr/share/doc/<var>package</var></file>
8540                 and can be referred to as
8541                 <example compact="compact">
8542 http://localhost/doc/<var>package</var>/<var>filename</var>
8543                 </example>
8544               </p>
8545
8546               <p>
8547                 The web server should restrict access to the document
8548                 tree so that only clients on the same host can read
8549                 the documents. If the web server does not support such
8550                 access controls, then it should not provide access at
8551                 all, or ask about providing access during installation.
8552               </p>
8553             </item>
8554
8555             <item>
8556               <p>Access to images</p>
8557               <p>
8558                 It is recommended that images for a package be stored
8559                 in <tt>/usr/share/images/<var>package</var></tt> and
8560                 may be referred to through an alias <tt>/images/</tt>
8561                 as
8562                 <example>
8563                   http://localhost/images/&lt;package&gt;/&lt;filename&gt;     
8564                 </example>
8565                 
8566               </p>
8567             </item>
8568
8569             <item>
8570               <p>Web Document Root</p>
8571
8572               <p>
8573                 Web Applications should try to avoid storing files in
8574                 the Web Document Root.  Instead they should use the
8575                 /usr/share/doc/<var>package</var> directory for
8576                 documents and register the Web Application via the
8577                 <package>doc-base</package> package.  If access to the
8578                 web document root is unavoidable then use
8579                 <example compact="compact">
8580 /var/www
8581                 </example>
8582                 as the Document Root.  This might be just a symbolic
8583                 link to the location where the system administrator
8584                 has put the real document root.
8585               </p>
8586             </item>
8587             <item><p>Providing httpd and/or httpd-cgi</p>
8588               <p>
8589                 All web servers should provide the virtual package
8590                 <tt>httpd</tt>. If a web server has CGI support it should
8591                 provide <tt>httpd-cgi</tt> additionally.
8592               </p>
8593               <p>
8594                 All web applications which do not contain CGI scripts should
8595                 depend on <tt>httpd</tt>, all those web applications which
8596                 <tt>do</tt> contain CGI scripts, should depend on
8597                 <tt>httpd-cgi</tt>.
8598               </p>
8599             </item>
8600           </enumlist>
8601         </p>
8602       </sect>
8603
8604       <sect id="mail-transport-agents">
8605         <heading>Mail transport, delivery and user agents</heading>
8606
8607         <p>
8608           Debian packages which process electronic mail, whether mail
8609           user agents (MUAs) or mail transport agents (MTAs), must
8610           ensure that they are compatible with the configuration
8611           decisions below.  Failure to do this may result in lost
8612           mail, broken <tt>From:</tt> lines, and other serious brain
8613           damage!
8614         </p>
8615
8616         <p>
8617           The mail spool is <file>/var/mail</file> and the interface to
8618           send a mail message is <file>/usr/sbin/sendmail</file> (as per
8619           the FHS).  On older systems, the mail spool may be
8620           physically located in <file>/var/spool/mail</file>, but all
8621           access to the mail spool should be via the
8622           <file>/var/mail</file> symlink.  The mail spool is part of the
8623           base system and not part of the MTA package.
8624         </p>
8625
8626         <p>
8627           All Debian MUAs, MTAs, MDAs and other mailbox accessing
8628           programs (such as IMAP daemons) must lock the mailbox in an
8629           NFS-safe way. This means that <tt>fcntl()</tt> locking must
8630           be combined with dot locking.  To avoid deadlocks, a program
8631           should use <tt>fcntl()</tt> first and dot locking after
8632           this, or alternatively implement the two locking methods in
8633           a non blocking way<footnote>
8634               If it is not possible to establish both locks, the
8635               system shouldn't wait for the second lock to be
8636               established, but remove the first lock, wait a (random)
8637               time, and start over locking again.
8638           </footnote>. Using the functions <tt>maillock</tt> and
8639           <tt>mailunlock</tt> provided by the
8640           <tt>liblockfile*</tt><footnote>
8641               You will need to depend on <tt>liblockfile1 (&gt;&gt;1.01)</tt>
8642               to use these functions.
8643           </footnote> packages is the recommended way to realize this.
8644         </p>
8645
8646         <p>
8647           Mailboxes are generally either mode 600 and owned by
8648           <var>user</var> or mode 660 and owned by
8649           <tt><var>user</var>:mail</tt><footnote>
8650             There are two traditional permission schemes for mail spools:
8651             mode 600 with all mail delivery done by processes running as
8652             the destination user, or mode 660 and owned by group mail with
8653             mail delivery done by a process running as a system user in
8654             group mail.  Historically, Debian required mode 660 mail
8655             spools to enable the latter model, but that model has become
8656             increasingly uncommon and the principle of least privilege
8657             indicates that mail systems that use the first model should
8658             use permissions of 600.  If delivery to programs is permitted,
8659             it's easier to keep the mail system secure if the delivery
8660             agent runs as the destination user.  Debian Policy therefore
8661             permits either scheme.
8662           </footnote>. The local system administrator may choose a
8663           different permission scheme; packages should not make
8664           assumptions about the permission and ownership of mailboxes
8665           unless required (such as when creating a new mailbox).  A MUA
8666           may remove a mailbox (unless it has nonstandard permissions) in
8667           which case the MTA or another MUA must recreate it if needed.
8668         </p>
8669
8670         <p>
8671           The mail spool is 2775 <tt>root:mail</tt>, and MUAs should
8672           be setgid mail to do the locking mentioned above (and
8673           must obviously avoid accessing other users' mailboxes
8674           using this privilege).</p>
8675
8676         <p>
8677           <file>/etc/aliases</file> is the source file for the system mail
8678           aliases (e.g., postmaster, usenet, etc.), it is the one
8679           which the sysadmin and <prgn>postinst</prgn> scripts may
8680           edit.  After <file>/etc/aliases</file> is edited the program or
8681           human editing it must call <prgn>newaliases</prgn>.  All MTA
8682           packages must come with a <prgn>newaliases</prgn> program,
8683           even if it does nothing, but older MTA packages did not do
8684           this so programs should not fail if <prgn>newaliases</prgn>
8685           cannot be found.  Note that because of this, all MTA
8686           packages must have <tt>Provides</tt>, <tt>Conflicts</tt> and
8687           <tt>Replaces: mail-transport-agent</tt> control fields.
8688         </p>
8689
8690         <p>
8691           The convention of writing <tt>forward to
8692             <var>address</var></tt> in the mailbox itself is not
8693           supported.  Use a <tt>.forward</tt> file instead.</p>
8694
8695         <p>
8696           The <prgn>rmail</prgn> program used by UUCP
8697           for incoming mail should be  <file>/usr/sbin/rmail</file>.
8698           Likewise, <prgn>rsmtp</prgn>, for receiving
8699           batch-SMTP-over-UUCP, should be <file>/usr/sbin/rsmtp</file> if it
8700           is supported.</p>
8701
8702         <p>
8703           If your package needs to know what hostname to use on (for
8704           example) outgoing news and mail messages which are generated
8705           locally, you should use the file <file>/etc/mailname</file>.  It
8706           will contain the portion after the username and <tt>@</tt>
8707           (at) sign for email addresses of users on the machine
8708           (followed by a newline).
8709         </p>
8710
8711         <p>
8712           Such a package should check for the existence of this file
8713           when it is being configured.  If it exists, it should be
8714           used without comment, although an MTA's configuration script
8715           may wish to prompt the user even if it finds that this file
8716           exists.  If the file does not exist, the package should
8717           prompt the user for the value (preferably using
8718           <prgn>debconf</prgn>) and store it in <file>/etc/mailname</file>
8719           as well as using it in the package's configuration.  The
8720           prompt should make it clear that the name will not just be
8721           used by that package.  For example, in this situation the
8722           <tt>inn</tt> package could say something like:
8723           <example compact="compact">
8724 Please enter the "mail name" of your system.  This is the
8725 hostname portion of the address to be shown on outgoing
8726 news and mail messages.  The default is
8727 <var>syshostname</var>, your system's host name.  Mail
8728 name ["<var>syshostname</var>"]:
8729           </example>
8730           where <var>syshostname</var> is the output of <tt>hostname
8731             --fqdn</tt>.
8732         </p>
8733       </sect>
8734
8735       <sect>
8736         <heading>News system configuration</heading>
8737
8738         <p>
8739           All the configuration files related to the NNTP (news)
8740           servers and clients should be located under
8741           <file>/etc/news</file>.</p>
8742
8743         <p>
8744           There are some configuration issues that apply to a number
8745           of news clients and server packages on the machine. These
8746           are:
8747
8748           <taglist>
8749             <tag><file>/etc/news/organization</file></tag>
8750             <item>
8751                 A string which should appear as the
8752                 organization header for all messages posted
8753                 by NNTP clients on the machine
8754             </item>
8755
8756             <tag><file>/etc/news/server</file></tag>
8757             <item>
8758                 Contains the FQDN of the upstream NNTP
8759                 server, or localhost if the local machine is
8760                 an NNTP server.
8761             </item>
8762           </taglist>
8763
8764           Other global files may be added as required for cross-package news
8765           configuration.
8766         </p>
8767       </sect>
8768
8769
8770       <sect>
8771         <heading>Programs for the X Window System</heading>
8772
8773         <sect1>
8774           <heading>Providing X support and package priorities</heading>
8775
8776           <p>
8777             Programs that can be configured with support for the X
8778             Window System must be configured to do so and must declare
8779             any package dependencies necessary to satisfy their
8780             runtime requirements when using the X Window System.  If
8781             such a package is of higher priority than the X packages
8782             on which it depends, it is required that either the
8783             X-specific components be split into a separate package, or
8784             that an alternative version of the package, which includes
8785             X support, be provided, or that the package's priority be
8786             lowered.
8787           </p>
8788         </sect1>
8789
8790         <sect1>
8791           <heading>Packages providing an X server</heading>
8792
8793           <p>
8794             Packages that provide an X server that, directly or
8795             indirectly, communicates with real input and display
8796             hardware should declare in their <tt>Provides</tt> control
8797             field that they provide the virtual
8798             package <tt>xserver</tt>.<footnote>
8799                 This implements current practice, and provides an
8800                 actual policy for usage of the <tt>xserver</tt>
8801                 virtual package which appears in the virtual packages
8802                 list.  In a nutshell, X servers that interface
8803                 directly with the display and input hardware or via
8804                 another subsystem (e.g., GGI) should provide
8805                 <tt>xserver</tt>.  Things like <tt>Xvfb</tt>,
8806                 <tt>Xnest</tt>, and <tt>Xprt</tt> should not.
8807             </footnote>
8808           </p>
8809         </sect1>
8810
8811         <sect1>
8812           <heading>Packages providing a terminal emulator</heading>
8813
8814           <p>
8815             Packages that provide a terminal emulator for the X Window
8816             System which meet the criteria listed below should declare in
8817             their <tt>Provides</tt> control field that they provide the
8818             virtual package <tt>x-terminal-emulator</tt>.  They should
8819             also register themselves as an alternative for
8820             <file>/usr/bin/x-terminal-emulator</file>, with a priority of
8821             20.  That alternative should have a slave alternative
8822             for <file>/usr/share/man/man1/x-terminal-emulator.1.gz</file>
8823             pointing to the corresponding manual page.
8824           </p>
8825
8826           <p>
8827             To be an <tt>x-terminal-emulator</tt>, a program must:
8828             <list compact="compact">
8829               <item>
8830                   Be able to emulate a DEC VT100 terminal, or a
8831                   compatible terminal.
8832               </item>
8833
8834               <item>
8835                   Support the command-line option <tt>-e
8836                     <var>command</var></tt>, which creates a new
8837                   terminal window<footnote>
8838                       "New terminal window" does not necessarily mean
8839                       a new top-level X window directly parented by
8840                       the window manager; it could, if the terminal
8841                       emulator application were so coded, be a new
8842                       "view" in a multiple-document interface (MDI).
8843                   </footnote>
8844                   and runs the specified <var>command</var>,
8845                   interpreting the entirety of the rest of the command
8846                   line as a command to pass straight to exec, in the
8847                   manner that <tt>xterm</tt> does.
8848               </item>
8849
8850               <item>
8851                   Support the command-line option <tt>-T
8852                     <var>title</var></tt>, which creates a new terminal
8853                   window with the window title <var>title</var>.
8854               </item>
8855             </list>
8856           </p>
8857         </sect1>
8858
8859         <sect1>
8860           <heading>Packages providing a window manager</heading>
8861
8862           <p>
8863             Packages that provide a window manager should declare in
8864             their <tt>Provides</tt> control field that they provide the
8865             virtual package <tt>x-window-manager</tt>.  They should also
8866             register themselves as an alternative for
8867             <file>/usr/bin/x-window-manager</file>, with a priority
8868             calculated as follows:
8869             <list compact="compact">
8870               <item>
8871                   Start with a priority of 20.
8872               </item>
8873
8874               <item>
8875                   If the window manager supports the Debian menu
8876                   system, add 20 points if this support is available
8877                   in the package's default configuration (i.e., no
8878                   configuration files belonging to the system or user
8879                   have to be edited to activate the feature); if
8880                   configuration files must be modified, add only 10
8881                   points.
8882                 </p>
8883               </item>
8884
8885               <item>
8886                   If the window manager complies with <url
8887                     id="http://www.freedesktop.org/Standards/wm-spec"
8888                     name="The Window Manager Specification Project">,
8889                   written by the <url id="http://www.freedesktop.org/"
8890                     name="Free Desktop Group">, add 40 points.
8891               </item>
8892
8893               <item>
8894                   If the window manager permits the X session to be
8895                   restarted using a <em>different</em> window manager
8896                   (without killing the X server) in its default
8897                   configuration, add 10 points; otherwise add none.
8898               </item>
8899             </list>
8900             That alternative should have a slave alternative
8901             for <file>/usr/share/man/man1/x-window-manager.1.gz</file>
8902             pointing to the corresponding manual page.
8903           </p>
8904         </sect1>
8905
8906         <sect1>
8907           <heading>Packages providing fonts</heading>
8908
8909           <p>
8910             Packages that provide fonts for the X Window
8911             System<footnote>
8912                 For the purposes of Debian Policy, a "font for the X
8913                 Window System" is one which is accessed via X protocol
8914                 requests.  Fonts for the Linux console, for PostScript
8915                 renderer, or any other purpose, do not fit this
8916                 definition.  Any tool which makes such fonts available
8917                 to the X Window System, however, must abide by this
8918                 font policy.
8919             </footnote>
8920             must do a number of things to ensure that they are both
8921             available without modification of the X or font server
8922             configuration, and that they do not corrupt files used by
8923             other font packages to register information about
8924             themselves.
8925             <enumlist>
8926               <item>
8927                   Fonts of any type supported by the X Window System
8928                   must be in a separate binary package from any
8929                   executables, libraries, or documentation (except
8930                   that specific to the fonts shipped, such as their
8931                   license information).  If one or more of the fonts
8932                   so packaged are necessary for proper operation of
8933                   the package with which they are associated the font
8934                   package may be Recommended; if the fonts merely
8935                   provide an enhancement, a Suggests relationship may
8936                   be used.  Packages must not Depend on font
8937                   packages.<footnote>
8938                       This is because the X server may retrieve fonts
8939                       from the local file system or over the network
8940                       from an X font server; the Debian package system
8941                       is empowered to deal only with the local
8942                       file system.
8943                   </footnote>
8944               </item>
8945
8946               <item>
8947                   BDF fonts must be converted to PCF fonts with the
8948                   <prgn>bdftopcf</prgn> utility (available in the
8949                   <tt>xfonts-utils</tt> package, <prgn>gzip</prgn>ped, and
8950                   placed in a directory that corresponds to their
8951                   resolution:
8952                   <list compact="compact">
8953                     <item>
8954                         100 dpi fonts must be placed in
8955                         <file>/usr/share/fonts/X11/100dpi/</file>.
8956                     </item>
8957
8958                     <item>
8959                         75 dpi fonts must be placed in
8960                         <file>/usr/share/fonts/X11/75dpi/</file>.
8961                     </item>
8962
8963                     <item>
8964                         Character-cell fonts, cursor fonts, and other
8965                         low-resolution fonts must be placed in
8966                         <file>/usr/share/fonts/X11/misc/</file>.
8967                     </item>
8968                   </list>
8969               </item>
8970
8971               <item>
8972                   Type 1 fonts must be placed in
8973                   <file>/usr/share/fonts/X11/Type1/</file>.  If font
8974                   metric files are available, they must be placed here
8975                   as well.
8976               </item>
8977
8978               <item>
8979                   Subdirectories of <file>/usr/share/fonts/X11/</file>
8980                   other than those listed above must be neither
8981                   created nor used.  (The <file>PEX</file>, <file>CID</file>,
8982                   <file>Speedo</file>, and <file>cyrillic</file> directories
8983                   are excepted for historical reasons, but installation of
8984                   files into these directories remains discouraged.)
8985               </item>
8986
8987               <item>
8988                   Font packages may, instead of placing files directly
8989                   in the X font directories listed above, provide
8990                   symbolic links in that font directory pointing to
8991                   the files' actual location in the filesystem.  Such
8992                   a location must comply with the FHS.
8993               </item>
8994
8995               <item>
8996                   Font packages should not contain both 75dpi and
8997                   100dpi versions of a font.  If both are available,
8998                   they should be provided in separate binary packages
8999                   with <tt>-75dpi</tt> or <tt>-100dpi</tt> appended to
9000                   the names of the packages containing the
9001                   corresponding fonts.
9002               </item>
9003
9004               <item>
9005                   Fonts destined for the <file>misc</file> subdirectory
9006                   should not be included in the same package as 75dpi
9007                   or 100dpi fonts; instead, they should be provided in
9008                   a separate package with <tt>-misc</tt> appended to
9009                   its name.
9010               </item>
9011
9012               <item>
9013                   Font packages must not provide the files
9014                   <file>fonts.dir</file>, <file>fonts.alias</file>, or
9015                   <file>fonts.scale</file> in a font directory:
9016                   <list>
9017                     <item>
9018                         <file>fonts.dir</file> files must not be provided at all.
9019                     </item>
9020
9021                     <item>
9022                         <file>fonts.alias</file> and <file>fonts.scale</file>
9023                         files, if needed, should be provided in the
9024                         directory
9025                         <file>/etc/X11/fonts/<var>fontdir</var>/<var>package</var>.<var>extension</var></file>,
9026                         where <var>fontdir</var> is the name of the
9027                         subdirectory of
9028                         <file>/usr/share/fonts/X11/</file> where the
9029                         package's corresponding fonts are stored
9030                         (e.g., <tt>75dpi</tt> or <tt>misc</tt>),
9031                         <var>package</var> is the name of the package
9032                         that provides these fonts, and
9033                         <var>extension</var> is either <tt>scale</tt>
9034                         or <tt>alias</tt>, whichever corresponds to
9035                         the file contents.
9036                     </item>
9037                   </list>
9038               </item>
9039
9040               <item>
9041                   Font packages must declare a dependency on
9042                   <tt>xfonts-utils</tt> in their <tt>Depends</tt>
9043                   or <tt>Pre-Depends</tt> control field.
9044               </item>
9045
9046               <item>
9047                   Font packages that provide one or more
9048                   <file>fonts.scale</file> files as described above must
9049                   invoke <prgn>update-fonts-scale</prgn> on each
9050                   directory into which they installed fonts
9051                   <em>before</em> invoking
9052                   <prgn>update-fonts-dir</prgn> on that directory.
9053                   This invocation must occur in both the
9054                   <prgn>postinst</prgn> (for all arguments) and
9055                   <prgn>postrm</prgn> (for all arguments except
9056                   <tt>upgrade</tt>) scripts.
9057               </item>
9058
9059               <item>
9060                   Font packages that provide one or more
9061                   <file>fonts.alias</file> files as described above must
9062                   invoke <prgn>update-fonts-alias</prgn> on each
9063                   directory into which they installed fonts.  This
9064                   invocation must occur in both the
9065                   <prgn>postinst</prgn> (for all arguments) and
9066                   <prgn>postrm</prgn> (for all arguments except
9067                   <tt>upgrade</tt>) scripts.
9068               </item>
9069
9070               <item>
9071                   Font packages must invoke
9072                   <prgn>update-fonts-dir</prgn> on each directory into
9073                   which they installed fonts.  This invocation must
9074                   occur in both the <prgn>postinst</prgn> (for all
9075                   arguments) and <prgn>postrm</prgn> (for all
9076                   arguments except <tt>upgrade</tt>) scripts.
9077               </item>
9078
9079               <item>
9080                   Font packages must not provide alias names for the
9081                   fonts they include which collide with alias names
9082                   already in use by fonts already packaged.
9083               </item>
9084
9085               <item>
9086                   Font packages must not provide fonts with the same
9087                   XLFD registry name as another font already packaged.
9088               </item>
9089             </enumlist>
9090           </p>
9091         </sect1>
9092
9093         <sect1 id="appdefaults">
9094           <heading>Application defaults files</heading>
9095
9096           <p>
9097             Application defaults files must be installed in the
9098             directory <file>/etc/X11/app-defaults/</file> (use of a
9099             localized subdirectory of <file>/etc/X11/</file> as described
9100             in the <em>X Toolkit Intrinsics - C Language
9101             Interface</em> manual is also permitted).  They must be
9102             registered as <tt>conffile</tt>s or handled as
9103             configuration files.
9104           </p>
9105
9106           <p>
9107             Customization of programs' X resources may also be
9108             supported with the provision of a file with the same name
9109             as that of the package placed in
9110             the <file>/etc/X11/Xresources/</file> directory, which
9111             must be registered as a <tt>conffile</tt> or handled as a
9112             configuration file.<footnote>
9113                 Note that this mechanism is not the same as using
9114                 app-defaults; app-defaults are tied to the client
9115                 binary on the local file system, whereas X resources
9116                 are stored in the X server and affect all connecting
9117                 clients.
9118             </footnote>
9119           </p>
9120         </sect1>
9121
9122         <sect1>
9123           <heading>Installation directory issues</heading>
9124
9125           <p>
9126             Historically, packages using the X Window System used a
9127             separate set of installation directories from other packages.
9128             This practice has been discontinued and packages using the X
9129             Window System should now generally be installed in the same
9130             directories as any other package.  Specifically, packages must
9131             not install files under the <file>/usr/X11R6/</file> directory
9132             and the <file>/usr/X11R6/</file> directory hierarchy should be
9133             regarded as obsolete.
9134           </p>
9135
9136           <p>
9137             Include files previously installed under
9138             <file>/usr/X11R6/include/X11/</file> should be installed into
9139             <file>/usr/include/X11/</file>.  For files previously
9140             installed into subdirectories of
9141             <file>/usr/X11R6/lib/X11/</file>, package maintainers should
9142             determine if subdirectories of <file>/usr/lib/</file> and
9143             <file>/usr/share/</file> can be used.  If not, a subdirectory
9144             of <file>/usr/lib/X11/</file> should be used.
9145           </p>
9146
9147           <p>
9148             Configuration files for window, display, or session managers
9149             or other applications that are tightly integrated with the X
9150             Window System may be placed in a subdirectory
9151             of <file>/etc/X11/</file> corresponding to the package name.
9152             Other X Window System applications should use
9153             the <file>/etc/</file> directory unless otherwise mandated by
9154             policy (such as for <ref id="appdefaults">).
9155           </p>
9156         </sect1>
9157
9158         <sect1>
9159           <heading>The OSF/Motif and OpenMotif libraries</heading>
9160
9161           <p>
9162             <em>Programs that require the non-DFSG-compliant OSF/Motif or
9163               OpenMotif libraries</em><footnote>
9164                 OSF/Motif and OpenMotif are collectively referred to as
9165                 "Motif" in this policy document.
9166             </footnote>
9167             should be compiled against and tested with LessTif (a free
9168             re-implementation of Motif) instead.  If the maintainer
9169             judges that the program or programs do not work
9170             sufficiently well with LessTif to be distributed and
9171             supported, but do so when compiled against Motif, then two
9172             versions of the package should be created; one linked
9173             statically against Motif and with <tt>-smotif</tt>
9174             appended to the package name, and one linked dynamically
9175             against Motif and with <tt>-dmotif</tt> appended to the
9176             package name.
9177           </p>
9178
9179           <p>
9180             Both Motif-linked versions are dependent
9181             upon non-DFSG-compliant software and thus cannot be
9182             uploaded to the <em>main</em> distribution; if the
9183             software is itself DFSG-compliant it may be uploaded to
9184             the <em>contrib</em> distribution.  While known existing
9185             versions of Motif permit unlimited redistribution of
9186             binaries linked against the library (whether statically or
9187             dynamically), it is the package maintainer's
9188             responsibility to determine whether this is permitted by
9189             the license of the copy of Motif in their possession.
9190           </p>
9191         </sect1>
9192       </sect>
9193
9194       <sect id="perl">
9195         <heading>Perl programs and modules</heading>
9196
9197         <p>
9198           Perl programs and modules should follow the current Perl policy.
9199         </p>
9200
9201         <p>
9202           The Perl policy can be found in the <tt>perl-policy</tt>
9203           files in the <tt>debian-policy</tt> package.
9204           It is also available from the Debian web mirrors at
9205           <tt><url name="/doc/packaging-manuals/perl-policy/"
9206                 id="http://www.debian.org/doc/packaging-manuals/perl-policy/"></tt>.
9207         </p>
9208       </sect>
9209
9210       <sect id="emacs">
9211         <heading>Emacs lisp programs</heading>
9212
9213         <p>
9214           Please refer to the "Debian Emacs Policy" for details of how to
9215           package emacs lisp programs.
9216         </p>
9217
9218         <p>
9219           The Emacs policy is available in
9220           <file>debian-emacs-policy.gz</file> of the
9221           <package>emacsen-common</package> package.
9222           It is also available from the Debian web mirrors at
9223           <tt><url name="/doc/packaging-manuals/debian-emacs-policy"
9224                 id="http://www.debian.org/doc/packaging-manuals/debian-emacs-policy"></tt>.
9225         </p>
9226       </sect>
9227
9228       <sect>
9229         <heading>Games</heading>
9230
9231         <p>
9232           The permissions on <file>/var/games</file> are mode 755, owner
9233           <tt>root</tt> and group <tt>root</tt>.
9234         </p>
9235
9236         <p>
9237           Each game decides on its own security policy.</p>
9238
9239         <p>
9240           Games which require protected, privileged access to
9241           high-score files, saved games, etc., may be made
9242           set-<em>group</em>-id (mode 2755) and owned by
9243           <tt>root:games</tt>, and use files and directories with
9244           appropriate permissions (770 <tt>root:games</tt>, for
9245           example).  They must not be made
9246           set-<em>user</em>-id, as this causes security problems. (If
9247           an attacker can subvert any set-user-id game they can
9248           overwrite the executable of any other, causing other players
9249           of these games to run a Trojan horse program.  With a
9250           set-group-id game the attacker only gets access to less
9251           important game data, and if they can get at the other
9252           players' accounts at all it will take considerably more
9253           effort.)</p>
9254
9255         <p>
9256           Some packages, for example some fortune cookie programs, are
9257           configured by the upstream authors to install with their
9258           data files or other static information made unreadable so
9259           that they can only be accessed through set-id programs
9260           provided.  You should not do this in a Debian package: anyone can
9261           download the <file>.deb</file> file and read the data from it,
9262           so there is no point making the files unreadable.  Not
9263           making the files unreadable also means that you don't have
9264           to make so many programs set-id, which reduces the risk of a
9265           security hole.</p>
9266
9267         <p>
9268           As described in the FHS, binaries of games should be
9269           installed in the directory <file>/usr/games</file>. This also
9270           applies to games that use the X Window System. Manual pages
9271           for games (X and non-X games) should be installed in
9272           <file>/usr/share/man/man6</file>.</p>
9273       </sect>
9274     </chapt>
9275
9276
9277     <chapt id="docs">
9278       <heading>Documentation</heading>
9279
9280       <sect>
9281         <heading>Manual pages</heading>
9282
9283         <p>
9284           You should install manual pages in <prgn>nroff</prgn> source
9285           form, in appropriate places under <file>/usr/share/man</file>.
9286           You should only use sections 1 to 9 (see the FHS for more
9287           details).  You must not install a pre-formatted "cat page".
9288         </p>
9289
9290         <p>
9291           Each program, utility, and function should have an
9292           associated manual page included in the same package. It is
9293           suggested that all configuration files also have a manual
9294           page included as well. Manual pages for protocols and other
9295           auxiliary things are optional.
9296         </p>
9297
9298         <p>
9299           If no manual page is available, this is considered as a bug
9300           and should be reported to the Debian Bug Tracking System (the
9301           maintainer of the package is allowed to write this bug report
9302           themselves, if they so desire).  Do not close the bug report
9303           until a proper man page is available.<footnote>
9304               It is not very hard to write a man page. See the
9305               <url id="http://www.schweikhardt.net/man_page_howto.html"
9306                 name="Man-Page-HOWTO">,
9307               <manref name="man" section="7">, the examples
9308               created by <prgn>debmake</prgn> or <prgn>dh_make</prgn>,
9309               the helper program <prgn>help2man</prgn>, or the
9310               directory <file>/usr/share/doc/man-db/examples</file>.
9311           </footnote>
9312         </p>
9313
9314         <p>
9315           You may forward a complaint about a missing man page to the
9316           upstream authors, and mark the bug as forwarded in the
9317           Debian bug tracking system.  Even though the GNU Project do
9318           not in general consider the lack of a man page to be a bug,
9319           we do; if they tell you that they don't consider it a bug
9320           you should leave the bug in our bug tracking system open
9321           anyway.
9322         </p>
9323
9324         <p>
9325           Manual pages should be installed compressed using <tt>gzip -9</tt>.
9326         </p>
9327
9328         <p>
9329           If one man page needs to be accessible via several names it
9330           is better to use a symbolic link than the <file>.so</file>
9331           feature, but there is no need to fiddle with the relevant
9332           parts of the upstream source to change from <file>.so</file> to
9333           symlinks: don't do it unless it's easy.  You should not
9334           create hard links in the manual page directories, nor put
9335           absolute filenames in <file>.so</file> directives.  The filename
9336           in a <file>.so</file> in a man page should be relative to the
9337           base of the man page tree (usually
9338           <file>/usr/share/man</file>). If you do not create any links
9339           (whether symlinks, hard links, or <tt>.so</tt> directives)
9340           in the file system to the alternate names of the man page,
9341           then you should not rely on <prgn>man</prgn> finding your
9342           man page under those names based solely on the information in
9343           the man page's header.<footnote>
9344               Supporting this in <prgn>man</prgn> often requires
9345               unreasonable processing time to find a manual page or to
9346               report that none exists, and moves knowledge into man's
9347               database that would be better left in the file system.
9348               This support is therefore deprecated and will cease to
9349               be present in the future.
9350           </footnote>
9351         </p>
9352
9353         <p>
9354           Manual pages in locale-specific subdirectories of
9355           <file>/usr/share/man</file> should use either UTF-8 or the usual
9356           legacy encoding for that language (normally the one corresponding
9357           to the shortest relevant locale name in
9358           <file>/usr/share/i18n/SUPPORTED</file>). For example, pages under
9359           <file>/usr/share/man/fr</file> should use either UTF-8 or
9360           ISO-8859-1.<footnote>
9361             <prgn>man</prgn> will automatically detect whether UTF-8 is in
9362             use. In future, all manual pages will be required to use
9363             UTF-8.
9364           </footnote>
9365         </p>
9366
9367         <p>
9368           A country name (the <tt>DE</tt> in <tt>de_DE</tt>) should not be
9369           included in the subdirectory name unless it indicates a
9370           significant difference in the language, as this excludes
9371           speakers of the language in other countries.<footnote>
9372             At the time of writing, Chinese and Portuguese are the main
9373             languages with such differences, so <file>pt_BR</file>,
9374             <file>zh_CN</file>, and <file>zh_TW</file> are all allowed.
9375           </footnote>
9376         </p>
9377
9378         <p>
9379           If a localized version of a manual page is provided, it should
9380           either be up-to-date or it should be obvious to the reader that
9381           it is outdated and the original manual page should be used
9382           instead.  This can be done either by a note at the beginning of
9383           the manual page or by showing the missing or changed portions in
9384           the original language instead of the target language.
9385         </p>
9386       </sect>
9387
9388       <sect>
9389         <heading>Info documents</heading>
9390
9391         <p>
9392           Info documents should be installed in <file>/usr/share/info</file>.
9393           They should be compressed with <tt>gzip -9</tt>.
9394         </p>
9395
9396         <p>
9397           The <prgn>install-info</prgn> program maintains a directory of
9398           installed info documents in <file>/usr/share/info/dir</file> for
9399           the use of info readers.<footnote>
9400             It was previously necessary for packages installing info
9401             documents to run <prgn>install-info</prgn> from maintainer
9402             scripts.  This is no longer necessary.  The installation
9403             system now uses dpkg triggers.
9404           </footnote>
9405           This file must not be included in packages.  Packages containing
9406           info documents should depend on <tt>dpkg (>= 1.15.4) |
9407           install-info</tt> to ensure that the directory file is properly
9408           rebuilt during partial upgrades from Debian 5.0 (lenny) and
9409           earlier.
9410         </p>
9411
9412         <p>
9413           Info documents should contain section and directory entry
9414           information in the document for the use
9415           of <prgn>install-info</prgn>.  The section should be specified
9416           via a line starting with <tt>INFO-DIR-SECTION</tt> followed by a
9417           space and the section of this info page.  The directory entry or
9418           entries should be included between
9419           a <tt>START-INFO-DIR-ENTRY</tt> line and
9420           an <tt>END-INFO-DIR-ENTRY</tt> line.  For example:
9421           <example>
9422 INFO-DIR-SECTION Individual utilities
9423 START-INFO-DIR-ENTRY
9424 * example: (example).               An example info directory entry.
9425 END-INFO-DIR-ENTRY
9426           </example>
9427           To determine which section to use, you should look
9428           at <file>/usr/share/info/dir</file> on your system and choose
9429           the most relevant (or create a new section if none of the
9430           current sections are relevant).<footnote>
9431             Normally, info documents are generated from Texinfo source.
9432             To include this information in the generated info document, if
9433             it is absent, add commands like:
9434             <example>
9435 @dircategory Individual utilities
9436 @direntry
9437 * example: (example).               An example info directory entry.
9438 @end direntry
9439             </example>
9440             to the Texinfo source of the document and ensure that the info
9441             documents are rebuilt from source during the package build.
9442           </footnote>
9443         </p>
9444       </sect>
9445
9446       <sect>
9447         <heading>Additional documentation</heading>
9448
9449         <p>
9450           Any additional documentation that comes with the package may
9451           be installed at the discretion of the package maintainer.
9452           Plain text documentation should be installed in the directory
9453           <file>/usr/share/doc/<var>package</var></file>, where
9454           <var>package</var> is the name of the package, and
9455           compressed with <tt>gzip -9</tt> unless it is small.
9456         </p>
9457
9458         <p>
9459           If a package comes with large amounts of documentation which
9460           many users of the package will not require you should create
9461           a separate binary package to contain it, so that it does not
9462           take up disk space on the machines of users who do not need
9463           or want it installed.</p>
9464
9465         <p>
9466           It is often a good idea to put text information files
9467           (<file>README</file>s, changelogs, and so forth) that come with
9468           the source package in <file>/usr/share/doc/<var>package</var></file>
9469           in the binary package.  However, you don't need to install
9470           the instructions for building and installing the package, of
9471           course!</p>
9472
9473         <p>
9474           Packages must not require the existence of any files in
9475           <file>/usr/share/doc/</file> in order to function
9476           <footnote>
9477               The system administrator should be able to
9478               delete files in <file>/usr/share/doc/</file> without causing
9479               any programs to break.
9480           </footnote>.
9481           Any files that are referenced by programs but are also
9482           useful as stand alone documentation should be installed under
9483           <file>/usr/share/<var>package</var>/</file> with symbolic links from
9484           <file>/usr/share/doc/<var>package</var></file>.
9485         </p>
9486
9487         <p>
9488           <file>/usr/share/doc/<var>package</var></file> may be a symbolic
9489           link to another directory in <file>/usr/share/doc</file> only if
9490           the two packages both come from the same source and the
9491           first package Depends on the second.<footnote>
9492             <p>
9493               Please note that this does not override the section on
9494               changelog files below, so the file 
9495               <file>/usr/share/doc/<var>package</var>/changelog.Debian.gz</file>
9496               must refer to the changelog for the current version of
9497               <var>package</var> in question. In practice, this means
9498               that the sources of the target and the destination of the
9499               symlink must be the same (same source package and
9500               version). 
9501             </p>
9502           </footnote>
9503         </p>
9504
9505         <p>
9506           Former Debian releases placed all additional documentation
9507           in <file>/usr/doc/<var>package</var></file>.  This has been
9508           changed to <file>/usr/share/doc/<var>package</var></file>,
9509           and packages must not put documentation in the directory
9510           <file>/usr/doc/<var>package</var></file>. <footnote>
9511             At this phase of the transition, we no longer require a
9512             symbolic link in <file>/usr/doc/</file>. At a later point,
9513             policy shall change to make the symbolic links a bug.
9514           </footnote>
9515         </p>
9516       </sect>
9517
9518       <sect>
9519         <heading>Preferred documentation formats</heading>
9520
9521         <p>
9522           The unification of Debian documentation is being carried out
9523           via HTML.</p>
9524
9525         <p>
9526           If your package comes with extensive documentation in a
9527           markup format that can be converted to various other formats
9528           you should if possible ship HTML versions in a binary
9529           package, in the directory
9530           <file>/usr/share/doc/<var>appropriate-package</var></file> or
9531           its subdirectories.<footnote>
9532               The rationale: The important thing here is that HTML
9533               docs should be available in <em>some</em> package, not
9534               necessarily in the main binary package.
9535           </footnote>
9536         </p>
9537
9538         <p>
9539           Other formats such as PostScript may be provided at the
9540           package maintainer's discretion.
9541         </p>
9542       </sect>
9543
9544       <sect id="copyrightfile">
9545         <heading>Copyright information</heading>
9546
9547         <p>
9548           Every package must be accompanied by a verbatim copy of its
9549           copyright information and distribution license in the file
9550           <file>/usr/share/doc/<var>package</var>/copyright</file>. This
9551           file must neither be compressed nor be a symbolic link.
9552         </p>
9553
9554         <p>
9555           In addition, the copyright file must say where the upstream
9556           sources (if any) were obtained.  It should name the original
9557           authors of the package and the Debian maintainer(s) who were
9558           involved with its creation.
9559         </p>
9560
9561         <p>
9562           Packages in the <em>contrib</em> or <em>non-free</em> archive
9563           areas should state in the copyright file that the package is not
9564           part of the Debian distribution and briefly explain why.
9565         </p>
9566
9567         <p>
9568           A copy of the file which will be installed in
9569           <file>/usr/share/doc/<var>package</var>/copyright</file> should
9570           be in <file>debian/copyright</file> in the source package.
9571         </p>
9572
9573         <p>
9574           <file>/usr/share/doc/<var>package</var></file> may be a symbolic
9575           link to another directory in <file>/usr/share/doc</file> only if
9576           the two packages both come from the same source and the
9577           first package Depends on the second.  These rules are
9578           important because copyrights must be extractable by
9579           mechanical means.
9580         </p>
9581
9582         <p>
9583           Packages distributed under the Apache license (version 2.0), the
9584           Artistic license, the GNU GPL (versions 1, 2, or 3), the GNU
9585           LGPL (versions 2, 2.1, or 3), and the GNU FDL (versions 1.2 or
9586           1.3) should refer to the corresponding files
9587           under <file>/usr/share/common-licenses</file>,<footnote>
9588             <p>
9589               In particular,
9590               <file>/usr/share/common-licenses/Apache-2.0</file>,
9591               <file>/usr/share/common-licenses/Artistic</file>,
9592               <file>/usr/share/common-licenses/GPL-1</file>,
9593               <file>/usr/share/common-licenses/GPL-2</file>,
9594               <file>/usr/share/common-licenses/GPL-3</file>,
9595               <file>/usr/share/common-licenses/LGPL-2</file>,
9596               <file>/usr/share/common-licenses/LGPL-2.1</file>,
9597               <file>/usr/share/common-licenses/LGPL-3</file>,
9598               <file>/usr/share/common-licenses/GFDL-1.2</file>, and
9599               <file>/usr/share/common-licenses/GFDL-1.3</file>
9600               respectively.  The University of California BSD license is
9601               also included in <package>base-files</package> as
9602               <file>/usr/share/common-licenses/BSD</file>, but given the
9603               brevity of this license, its specificity to code whose
9604               copyright is held by the Regents of the University of
9605               California, and the frequency of minor wording changes, its
9606               text should be included in the copyright file rather than
9607               referencing this file.
9608             </p>
9609           </footnote> rather than quoting them in the copyright
9610           file. 
9611         </p>
9612
9613         <p>
9614           You should not use the copyright file as a general <file>README</file>
9615           file.  If your package has such a file it should be
9616           installed in <file>/usr/share/doc/<var>package</var>/README</file> or
9617           <file>README.Debian</file> or some other appropriate place.</p>
9618       </sect>
9619
9620       <sect>
9621         <heading>Examples</heading>
9622
9623         <p>
9624           Any examples (configurations, source files, whatever),
9625           should be installed in a directory
9626           <file>/usr/share/doc/<var>package</var>/examples</file>.  These
9627           files should not be referenced by any program: they're there
9628           for the benefit of the system administrator and users as
9629           documentation only.  Architecture-specific example files
9630           should be installed in a directory
9631           <file>/usr/lib/<var>package</var>/examples</file> with symbolic
9632           links to them from
9633           <file>/usr/share/doc/<var>package</var>/examples</file>, or the
9634           latter directory itself may be a symbolic link to the
9635           former.
9636         </p>
9637
9638         <p>
9639           If the purpose of a package is to provide examples, then the
9640           example files may be installed into
9641           <file>/usr/share/doc/<var>package</var></file>.
9642         </p>
9643       </sect>
9644
9645       <sect id="changelogs">
9646         <heading>Changelog files</heading>
9647
9648         <p>
9649           Packages that are not Debian-native must contain a
9650           compressed copy of the <file>debian/changelog</file> file from
9651           the Debian source tree in
9652           <file>/usr/share/doc/<var>package</var></file> with the name
9653           <file>changelog.Debian.gz</file>.
9654         </p>
9655
9656         <p>
9657           If an upstream changelog is available, it should be accessible as
9658           <file>/usr/share/doc/<var>package</var>/changelog.gz</file> in
9659           plain text.  If the upstream changelog is distributed in
9660           HTML, it should be made available in that form as
9661           <file>/usr/share/doc/<var>package</var>/changelog.html.gz</file>
9662           and a plain text <file>changelog.gz</file> should be generated
9663           from it using, for example, <tt>lynx -dump -nolist</tt>.  If
9664           the upstream changelog files do not already conform to this
9665           naming convention, then this may be achieved either by
9666           renaming the files, or by adding a symbolic link, at the
9667           maintainer's discretion.<footnote>
9668               Rationale: People should not have to look in places for
9669               upstream changelogs merely because they are given
9670               different names or are distributed in HTML format.
9671           </footnote>
9672         </p>
9673
9674         <p>
9675           All of these files should be installed compressed using
9676           <tt>gzip -9</tt>, as they will become large with time even
9677           if they start out small.
9678         </p>
9679
9680         <p>
9681           If the package has only one changelog which is used both as
9682           the Debian changelog and the upstream one because there is
9683           no separate upstream maintainer then that changelog should
9684           usually be installed as
9685           <file>/usr/share/doc/<var>package</var>/changelog.gz</file>; if
9686           there is a separate upstream maintainer, but no upstream
9687           changelog, then the Debian changelog should still be called
9688           <file>changelog.Debian.gz</file>.
9689         </p>
9690
9691         <p>
9692           For details about the format and contents of the Debian
9693           changelog file, please see <ref id="dpkgchangelog">.
9694         </p>
9695       </sect>
9696     </chapt>
9697
9698     <appendix id="pkg-scope">
9699       <heading>Introduction and scope of these appendices</heading>
9700
9701       <p>
9702         These appendices are taken essentially verbatim from the
9703         now-deprecated Packaging Manual, version 3.2.1.0.  They are
9704         the chapters which are likely to be of use to package
9705         maintainers and which have not already been included in the
9706         policy document itself. Most of these sections are very likely
9707         not relevant to policy; they should be treated as
9708         documentation for the packaging system. Please note that these
9709         appendices are included for convenience, and for historical
9710         reasons: they used to be part of policy package, and they have
9711         not yet been incorporated into dpkg documentation. However,
9712         they still have value, and hence they are presented here.
9713       </p>
9714
9715       <p>
9716         They have not yet been checked to ensure that they are
9717         compatible with the contents of policy, and if there are any
9718         contradictions, the version in the main policy document takes
9719         precedence.  The remaining chapters of the old Packaging
9720         Manual have also not been read in detail to ensure that there
9721         are not parts which have been left out.  Both of these will be
9722         done in due course.
9723       </p>
9724
9725       <p>
9726         Certain parts of the Packaging manual were integrated into the
9727         Policy Manual proper, and removed from the appendices. Links
9728         have been placed from the old locations to the new ones.
9729       </p>
9730
9731       <p>
9732         <prgn>dpkg</prgn> is a suite of programs for creating binary
9733         package files and installing and removing them on Unix
9734         systems.<footnote>
9735             <prgn>dpkg</prgn> is targeted primarily at Debian, but may
9736             work on or be ported to other systems.
9737         </footnote>
9738       </p>
9739
9740       <p>
9741         The binary packages are designed for the management of
9742         installed executable programs (usually compiled binaries) and
9743         their associated data, though source code examples and
9744         documentation are provided as part of some packages.</p>
9745
9746       <p>
9747         This manual describes the technical aspects of creating Debian
9748         binary packages (<file>.deb</file> files).  It documents the
9749         behavior of the package management programs
9750         <prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and the way
9751         they interact with packages.</p>
9752
9753       <p>
9754         It also documents the interaction between
9755         <prgn>dselect</prgn>'s core and the access method scripts it
9756         uses to actually install the selected packages, and describes
9757         how to create a new access method.</p>
9758
9759       <p>
9760         This manual does not go into detail about the options and
9761         usage of the package building and installation tools.  It
9762         should therefore be read in conjunction with those programs'
9763         man pages.
9764       </p>
9765
9766       <p>
9767         The utility programs which are provided with <prgn>dpkg</prgn>
9768         for managing various system configuration and similar issues,
9769         such as <prgn>update-rc.d</prgn> and
9770         <prgn>install-info</prgn>, are not described in detail here -
9771         please see their man pages.
9772       </p>
9773
9774       <p>
9775         It is assumed that the reader is reasonably familiar with the
9776         <prgn>dpkg</prgn> System Administrators' manual.
9777         Unfortunately this manual does not yet exist.
9778       </p>
9779
9780       <p>
9781         The Debian version of the FSF's GNU hello program is provided
9782         as an example for people wishing to create Debian
9783         packages. The Debian <prgn>debmake</prgn> package is
9784         recommended as a very helpful tool in creating and maintaining
9785         Debian packages. However, while the tools and examples are
9786         helpful, they do not replace the need to read and follow the
9787         Policy and Programmer's Manual.</p>
9788     </appendix>
9789
9790     <appendix id="pkg-binarypkg">
9791       <heading>Binary packages (from old Packaging Manual)</heading>
9792
9793       <p>
9794         The binary package has two main sections.  The first part
9795         consists of various control information files and scripts used
9796         by <prgn>dpkg</prgn> when installing and removing.  See <ref
9797         id="pkg-controlarea">.
9798       </p>
9799
9800       <p>
9801         The second part is an archive containing the files and
9802         directories to be installed.
9803       </p>
9804
9805       <p>
9806         In the future binary packages may also contain other
9807         components, such as checksums and digital signatures. The
9808         format for the archive is described in full in the
9809         <file>deb(5)</file> man page.
9810       </p>
9811
9812
9813       <sect id="pkg-bincreating"><heading>Creating package files -
9814       <prgn>dpkg-deb</prgn>
9815         </heading>
9816
9817         <p>
9818           All manipulation of binary package files is done by
9819           <prgn>dpkg-deb</prgn>; it's the only program that has
9820           knowledge of the format.  (<prgn>dpkg-deb</prgn> may be
9821           invoked by calling <prgn>dpkg</prgn>, as <prgn>dpkg</prgn>
9822           will spot that the options requested are appropriate to
9823           <prgn>dpkg-deb</prgn> and invoke that instead with the same
9824           arguments.)
9825         </p>
9826
9827         <p>
9828           In order to create a binary package you must make a
9829           directory tree which contains all the files and directories
9830           you want to have in the file system data part of the package.
9831           In Debian-format source packages this directory is usually
9832           <file>debian/tmp</file>, relative to the top of the package's
9833           source tree.
9834         </p>
9835
9836         <p>
9837           They should have the locations (relative to the root of the
9838           directory tree you're constructing) ownerships and
9839           permissions which you want them to have on the system when
9840           they are installed.
9841         </p>
9842
9843         <p>
9844           With current versions of <prgn>dpkg</prgn> the uid/username
9845           and gid/groupname mappings for the users and groups being
9846           used should be the same on the system where the package is
9847           built and the one where it is installed.
9848         </p>
9849
9850         <p>
9851           You need to add one special directory to the root of the
9852           miniature file system tree you're creating:
9853           <prgn>DEBIAN</prgn>.  It should contain the control
9854           information files, notably the binary package control file
9855           (see <ref id="pkg-controlfile">).
9856         </p>
9857
9858         <p>
9859           The <prgn>DEBIAN</prgn> directory will not appear in the
9860           file system archive of the package, and so won't be installed
9861           by <prgn>dpkg</prgn> when the package is installed.
9862         </p>
9863
9864         <p>
9865           When you've prepared the package, you should invoke:
9866           <example>
9867   dpkg --build <var>directory</var>
9868           </example>
9869         </p>
9870
9871         <p>
9872           This will build the package in
9873           <file><var>directory</var>.deb</file>.  (<prgn>dpkg</prgn> knows
9874           that <tt>--build</tt> is a <prgn>dpkg-deb</prgn> option, so
9875           it invokes <prgn>dpkg-deb</prgn> with the same arguments to
9876           build the package.)
9877         </p>
9878
9879         <p>
9880           See the man page <manref name="dpkg-deb" section="8"> for details of how
9881           to examine the contents of this newly-created file.  You may find the
9882           output of following commands enlightening:
9883           <example>
9884   dpkg-deb --info <var>filename</var>.deb
9885   dpkg-deb --contents <var>filename</var>.deb
9886   dpkg --contents <var>filename</var>.deb
9887           </example>
9888           To view the copyright file for a package you could use this command:
9889           <example>
9890   dpkg --fsys-tarfile <var>filename</var>.deb | tar xOf - --wildcards \*/copyright | pager
9891           </example>
9892         </p>
9893       </sect>
9894
9895       <sect id="pkg-controlarea">
9896         <heading>Package control information files</heading>
9897
9898         <p>
9899           The control information portion of a binary package is a
9900           collection of files with names known to <prgn>dpkg</prgn>.
9901           It will treat the contents of these files specially - some
9902           of them contain information used by <prgn>dpkg</prgn> when
9903           installing or removing the package; others are scripts which
9904           the package maintainer wants <prgn>dpkg</prgn> to run.
9905         </p>
9906
9907         <p>
9908           It is possible to put other files in the package control
9909           information file area, but this is not generally a good idea
9910           (though they will largely be ignored).
9911         </p>
9912
9913         <p>
9914           Here is a brief list of the control information files supported
9915           by <prgn>dpkg</prgn> and a summary of what they're used for.
9916         </p>
9917
9918         <p>
9919           <taglist>
9920             <tag><tt>control</tt>
9921             <item>
9922               <p>
9923                 This is the key description file used by
9924                 <prgn>dpkg</prgn>.  It specifies the package's name
9925                 and version, gives its description for the user,
9926                 states its relationships with other packages, and so
9927                 forth.  See <ref id="sourcecontrolfiles"> and
9928                 <ref id="binarycontrolfiles">.
9929               </p>
9930
9931               <p>
9932                 It is usually generated automatically from information
9933                 in the source package by the
9934                 <prgn>dpkg-gencontrol</prgn> program, and with
9935                 assistance from <prgn>dpkg-shlibdeps</prgn>.
9936                 See <ref id="pkg-sourcetools">.
9937               </p>
9938             </item>
9939
9940             <tag><tt>postinst</tt>, <tt>preinst</tt>, <tt>postrm</tt>,
9941                  <tt>prerm</tt>
9942             </tag>
9943             <item>
9944               <p>
9945                 These are executable files (usually scripts) which
9946                 <prgn>dpkg</prgn> runs during installation, upgrade
9947                 and removal of packages.  They allow the package to
9948                 deal with matters which are particular to that package
9949                 or require more complicated processing than that
9950                 provided by <prgn>dpkg</prgn>.  Details of when and
9951                 how they are called are in <ref id="maintainerscripts">.
9952               </p>
9953
9954               <p>
9955                 It is very important to make these scripts idempotent.
9956                 See <ref id="idempotency">.
9957               </p>
9958
9959               <p>
9960                 The maintainer scripts are not guaranteed to run with a
9961                 controlling terminal and may not be able to interact with
9962                 the user.  See <ref id="controllingterminal">.
9963               </p>
9964             </item>
9965
9966             <tag><tt>conffiles</tt>
9967             </tag>
9968             <item>
9969                 This file contains a list of configuration files which
9970                 are to be handled automatically by <prgn>dpkg</prgn>
9971                 (see <ref id="pkg-conffiles">).  Note that not necessarily
9972                 every configuration file should be listed here.
9973             </item>
9974
9975             <tag><tt>shlibs</tt>
9976             </tag>
9977             <item>
9978                 This file contains a list of the shared libraries
9979                 supplied by the package, with dependency details for
9980                 each.  This is used by <prgn>dpkg-shlibdeps</prgn>
9981                 when it determines what dependencies are required in a
9982                 package control file. The <tt>shlibs</tt> file format
9983                 is described on <ref id="shlibs">.
9984             </item>
9985           </taglist>
9986         </p>
9987
9988       <sect id="pkg-controlfile">
9989         <heading>The main control information file: <tt>control</tt></heading>
9990
9991         <p>
9992           The most important control information file used by
9993           <prgn>dpkg</prgn> when it installs a package is
9994           <tt>control</tt>.  It contains all the package's "vital
9995           statistics".
9996         </p>
9997
9998         <p>
9999           The binary package control files of packages built from
10000           Debian sources are made by a special tool,
10001           <prgn>dpkg-gencontrol</prgn>, which reads
10002           <file>debian/control</file> and <file>debian/changelog</file> to
10003           find the information it needs.  See <ref id="pkg-sourcepkg"> for
10004           more details.
10005         </p>
10006
10007         <p>
10008           The fields in binary package control files are listed in
10009           <ref id="binarycontrolfiles">.
10010         </p>
10011
10012         <p>
10013           A description of the syntax of control files and the purpose
10014           of the fields is available in <ref id="controlfields">.
10015         </p>
10016       </sect>
10017
10018       <sect>
10019         <heading>Time Stamps</heading>
10020
10021         <p>
10022           See <ref id="timestamps">.
10023         </p>
10024       </sect>
10025     </appendix>
10026
10027     <appendix id="pkg-sourcepkg">
10028       <heading>Source packages (from old Packaging Manual) </heading>
10029
10030       <p>
10031         The Debian binary packages in the distribution are generated
10032         from Debian sources, which are in a special format to assist
10033         the easy and automatic building of binaries.
10034       </p>
10035
10036       <sect id="pkg-sourcetools">
10037         <heading>Tools for processing source packages</heading>
10038
10039         <p>
10040           Various tools are provided for manipulating source packages;
10041           they pack and unpack sources and help build of binary
10042           packages and help manage the distribution of new versions.
10043         </p>
10044
10045         <p>
10046           They are introduced and typical uses described here; see
10047           <manref name="dpkg-source" section="1"> for full
10048           documentation about their arguments and operation.
10049         </p>
10050
10051         <p>
10052           For examples of how to construct a Debian source package,
10053           and how to use those utilities that are used by Debian
10054           source packages, please see the <prgn>hello</prgn> example
10055           package.
10056         </p>
10057
10058         <sect1 id="pkg-dpkg-source">
10059           <heading>
10060             <prgn>dpkg-source</prgn> - packs and unpacks Debian source
10061             packages
10062           </heading>
10063
10064           <p>
10065             This program is frequently used by hand, and is also
10066             called from package-independent automated building scripts
10067             such as <prgn>dpkg-buildpackage</prgn>.
10068           </p>
10069
10070           <p>
10071             To unpack a package it is typically invoked with
10072             <example>
10073   dpkg-source -x <var>.../path/to/filename</var>.dsc
10074             </example>
10075           </p>
10076
10077            <p>
10078             with the <file><var>filename</var>.tar.gz</file> and
10079             <file><var>filename</var>.diff.gz</file> (if applicable) in
10080             the same directory.  It unpacks into
10081             <file><var>package</var>-<var>version</var></file>, and if
10082             applicable
10083             <file><var>package</var>-<var>version</var>.orig</file>, in
10084             the current directory.
10085           </p>
10086
10087           <p>
10088             To create a packed source archive it is typically invoked:
10089             <example>
10090   dpkg-source -b <var>package</var>-<var>version</var>
10091           </example>
10092           </p>
10093
10094           <p>
10095             This will create the <file>.dsc</file>, <file>.tar.gz</file> and
10096             <file>.diff.gz</file> (if appropriate) in the current
10097             directory.  <prgn>dpkg-source</prgn> does not clean the
10098             source tree first - this must be done separately if it is
10099             required.
10100           </p>
10101
10102           <p>
10103             See also <ref id="pkg-sourcearchives">.</p>
10104         </sect1>
10105
10106
10107         <sect1 id="pkg-dpkg-buildpackage">
10108           <heading>
10109             <prgn>dpkg-buildpackage</prgn> - overall package-building
10110             control script
10111           </heading>
10112
10113           <p>
10114             <prgn>dpkg-buildpackage</prgn> is a script which invokes
10115             <prgn>dpkg-source</prgn>, the <file>debian/rules</file>
10116             targets <tt>clean</tt>, <tt>build</tt> and
10117             <tt>binary</tt>, <prgn>dpkg-genchanges</prgn> and
10118             <prgn>gpg</prgn> (or <prgn>pgp</prgn>) to build a signed
10119             source and binary package upload.
10120           </p>
10121
10122           <p>
10123             It is usually invoked by hand from the top level of the
10124             built or unbuilt source directory.  It may be invoked with
10125             no arguments; useful arguments include:
10126             <taglist compact="compact">
10127               <tag><tt>-uc</tt>, <tt>-us</tt></tag>
10128               <item>
10129                 <p>
10130                   Do not sign the <tt>.changes</tt> file or the
10131                   source package <tt>.dsc</tt> file, respectively.</p>
10132               </item>
10133               <tag><tt>-p<var>sign-command</var></tt></tag>
10134               <item>
10135                 <p>
10136                   Invoke <var>sign-command</var> instead of finding
10137                   <tt>gpg</tt> or <tt>pgp</tt> on the <prgn>PATH</prgn>.
10138                   <var>sign-command</var> must behave just like
10139                   <prgn>gpg</prgn> or <tt>pgp</tt>.</p>
10140               </item>
10141               <tag><tt>-r<var>root-command</var></tt></tag>
10142               <item>
10143                 <p>
10144                   When root privilege is required, invoke the command
10145                   <var>root-command</var>.  <var>root-command</var>
10146                   should invoke its first argument as a command, from
10147                   the <prgn>PATH</prgn> if necessary, and pass its
10148                   second and subsequent arguments to the command it
10149                   calls.  If no <var>root-command</var> is supplied
10150                   then <var>dpkg-buildpackage</var> will take no
10151                   special action to gain root privilege, so that for
10152                   most packages it will have to be invoked as root to
10153                   start with.</p>
10154               </item>
10155               <tag><tt>-b</tt>, <tt>-B</tt></tag>
10156               <item>
10157                 <p>
10158                   Two types of binary-only build and upload - see
10159                   <manref name="dpkg-source" section="1">.
10160                 </p>
10161               </item>
10162             </taglist>
10163           </p>
10164         </sect1>
10165
10166         <sect1 id="pkg-dpkg-gencontrol">
10167           <heading>
10168             <prgn>dpkg-gencontrol</prgn> - generates binary package
10169             control files
10170           </heading>
10171
10172           <p>
10173             This program is usually called from <file>debian/rules</file>
10174             (see <ref id="pkg-sourcetree">) in the top level of the source
10175             tree.
10176           </p>
10177
10178           <p>
10179             This is usually done just before the files and directories in the
10180             temporary directory tree where the package is being built have their
10181             permissions and ownerships set and the package is constructed using
10182             <prgn>dpkg-deb/</prgn>
10183               <footnote>
10184                 This is so that the control file which is produced has
10185                 the right permissions
10186             </footnote>.
10187           </p>
10188
10189           <p>
10190             <prgn>dpkg-gencontrol</prgn> must be called after all the
10191             files which are to go into the package have been placed in
10192             the temporary build directory, so that its calculation of
10193             the installed size of a package is correct.
10194           </p>
10195
10196           <p>
10197             It is also necessary for <prgn>dpkg-gencontrol</prgn> to
10198             be run after <prgn>dpkg-shlibdeps</prgn> so that the
10199             variable substitutions created by
10200             <prgn>dpkg-shlibdeps</prgn> in <file>debian/substvars</file>
10201             are available.
10202           </p>
10203
10204           <p>
10205             For a package which generates only one binary package, and
10206             which builds it in <file>debian/tmp</file> relative to the top
10207             of the source package, it is usually sufficient to call
10208             <prgn>dpkg-gencontrol</prgn>.
10209           </p>
10210
10211           <p>
10212             Sources which build several binaries will typically need
10213             something like:
10214             <example>
10215   dpkg-gencontrol -Pdebian/tmp-<var>pkg</var> -p<var>package</var>
10216             </example> The <tt>-P</tt> tells
10217             <prgn>dpkg-gencontrol</prgn> that the package is being
10218             built in a non-default directory, and the <tt>-p</tt>
10219             tells it which package's control file should be generated.
10220           </p>
10221
10222           <p>
10223             <prgn>dpkg-gencontrol</prgn> also adds information to the
10224             list of files in <file>debian/files</file>, for the benefit of
10225             (for example) a future invocation of
10226             <prgn>dpkg-genchanges</prgn>.</p>
10227         </sect1>
10228
10229         <sect1 id="pkg-dpkg-shlibdeps">
10230           <heading>
10231             <prgn>dpkg-shlibdeps</prgn> - calculates shared library
10232             dependencies
10233           </heading>
10234
10235           <p>
10236             This program is usually called from <file>debian/rules</file>
10237             just before <prgn>dpkg-gencontrol</prgn> (see <ref
10238             id="pkg-sourcetree">), in the top level of the source tree.
10239           </p>
10240
10241           <p>
10242             Its arguments are executables and shared libraries
10243             <footnote>
10244               <p>
10245                 They may be specified either in the locations in the
10246                 source tree where they are created or in the locations
10247                 in the temporary build tree where they are installed
10248                 prior to binary package creation.
10249               </p>
10250             </footnote> for which shared library dependencies should
10251             be included in the binary package's control file.
10252           </p>
10253
10254           <p>
10255             If some of the found shared libraries should only
10256             warrant a <tt>Recommends</tt> or <tt>Suggests</tt>, or if
10257             some warrant a <tt>Pre-Depends</tt>, this can be achieved
10258             by using the <tt>-d<var>dependency-field</var></tt> option
10259             before those executable(s).  (Each <tt>-d</tt> option
10260             takes effect until the next <tt>-d</tt>.)
10261           </p>
10262
10263           <p>
10264             <prgn>dpkg-shlibdeps</prgn> does not directly cause the
10265             output control file to be modified.  Instead by default it
10266             adds to the <file>debian/substvars</file> file variable
10267             settings like <tt>shlibs:Depends</tt>.  These variable
10268             settings must be referenced in dependency fields in the
10269             appropriate per-binary-package sections of the source
10270             control file.
10271           </p>
10272
10273           <p>
10274             For example, a package that generates an essential part
10275             which requires dependencies, and optional parts that 
10276             which only require a recommendation, would separate those
10277             two sets of dependencies into two different fields.<footnote>
10278                 At the time of writing, an example for this was the
10279                 <package/xmms/ package, with Depends used for the xmms
10280                 executable, Recommends for the plug-ins and Suggests for
10281                 even more optional features provided by unzip.
10282             </footnote>
10283             It can say in its <file>debian/rules</file>:
10284             <example>
10285   dpkg-shlibdeps -dDepends <var>program anotherprogram ...</var> \
10286                  -dRecommends <var>optionalpart anotheroptionalpart</var>
10287             </example>
10288             and then in its main control file <file>debian/control</file>:
10289             <example>
10290   <var>...</var>
10291   Depends: ${shlibs:Depends}
10292   Recommends: ${shlibs:Recommends}
10293   <var>...</var>
10294             </example>
10295           </p>
10296
10297           <p>
10298             Sources which produce several binary packages with
10299             different shared library dependency requirements can use
10300             the <tt>-p<var>varnameprefix</var></tt> option to override
10301             the default <tt>shlibs:</tt> prefix (one invocation of
10302             <prgn>dpkg-shlibdeps</prgn> per setting of this option).
10303             They can thus produce several sets of dependency
10304             variables, each of the form
10305             <tt><var>varnameprefix</var>:<var>dependencyfield</var></tt>,
10306             which can be referred to in the appropriate parts of the
10307             binary package control files.
10308           </p>
10309         </sect1>
10310
10311
10312         <sect1 id="pkg-dpkg-distaddfile">
10313           <heading>
10314             <prgn>dpkg-distaddfile</prgn> - adds a file to
10315             <file>debian/files</file>
10316           </heading>
10317
10318           <p>
10319             Some packages' uploads need to include files other than
10320             the source and binary package files.
10321           </p>
10322
10323           <p>
10324             <prgn>dpkg-distaddfile</prgn> adds a file to the
10325             <file>debian/files</file> file so that it will be included in
10326             the <file>.changes</file> file when
10327             <prgn>dpkg-genchanges</prgn> is run.
10328           </p>
10329
10330           <p>
10331             It is usually invoked from the <tt>binary</tt> target of
10332             <file>debian/rules</file>:
10333             <example>
10334   dpkg-distaddfile <var>filename</var> <var>section</var> <var>priority</var>
10335             </example>
10336             The <var>filename</var> is relative to the directory where
10337             <prgn>dpkg-genchanges</prgn> will expect to find it - this
10338             is usually the directory above the top level of the source
10339             tree.  The <file>debian/rules</file> target should put the
10340             file there just before or just after calling
10341             <prgn>dpkg-distaddfile</prgn>.
10342           </p>
10343
10344           <p>
10345             The <var>section</var> and <var>priority</var> are passed
10346             unchanged into the resulting <file>.changes</file> file.
10347           </p>
10348         </sect1>
10349
10350
10351         <sect1 id="pkg-dpkg-genchanges">
10352           <heading>
10353             <prgn>dpkg-genchanges</prgn> - generates a <file>.changes</file>
10354             upload control file
10355           </heading>
10356
10357           <p>
10358             This program is usually called by package-independent
10359             automatic building scripts such as
10360             <prgn>dpkg-buildpackage</prgn>, but it may also be called
10361             by hand.
10362           </p>
10363
10364           <p>
10365             It is usually called in the top level of a built source
10366             tree, and when invoked with no arguments will print out a
10367             straightforward <file>.changes</file> file based on the
10368             information in the source package's changelog and control
10369             file and the binary and source packages which should have
10370             been built.
10371           </p>
10372         </sect1>
10373
10374
10375         <sect1 id="pkg-dpkg-parsechangelog">
10376           <heading>
10377             <prgn>dpkg-parsechangelog</prgn> - produces parsed
10378             representation of a changelog
10379           </heading>
10380
10381           <p>
10382             This program is used internally by
10383             <prgn>dpkg-source</prgn> et al.  It may also occasionally
10384             be useful in <file>debian/rules</file> and elsewhere.  It
10385             parses a changelog, <file>debian/changelog</file> by default,
10386             and prints a control-file format representation of the
10387             information in it to standard output.
10388           </p>
10389         </sect1>
10390
10391         <sect1 id="pkg-dpkg-architecture">
10392           <heading>
10393             <prgn>dpkg-architecture</prgn> - information about the build and
10394             host system
10395           </heading>
10396
10397           <p>
10398             This program can be used manually, but is also invoked by
10399             <tt>dpkg-buildpackage</tt> or <file>debian/rules</file> to set
10400             environment or make variables which specify the build and host
10401             architecture for the package building process.
10402           </p>
10403         </sect1>
10404       </sect>
10405
10406       <sect id="pkg-sourcetree">
10407         <heading>The Debian package source tree</heading>
10408
10409         <p>
10410           The source archive scheme described later is intended to
10411           allow a Debian package source tree with some associated
10412           control information to be reproduced and transported easily.
10413           The Debian package source tree is a version of the original
10414           program with certain files added for the benefit of the
10415           packaging process, and with any other changes required
10416           made to the rest of the source code and installation
10417           scripts.
10418         </p>
10419
10420         <p>
10421           The extra files created for Debian are in the subdirectory
10422           <file>debian</file> of the top level of the Debian package
10423           source tree. They are described below.
10424         </p>
10425
10426         <sect1 id="pkg-debianrules">
10427           <heading><file>debian/rules</file> - the main building script</heading>
10428
10429           <p>
10430             See <ref id="debianrules">.
10431           </p>
10432         </sect1>
10433
10434         <sect1 id="pkg-srcsubstvars">
10435           <heading><file>debian/substvars</file> and variable substitutions</heading>
10436
10437           <p>
10438             See <ref id="substvars">.
10439           </p>
10440
10441         </sect1>
10442
10443         <sect1>
10444           <heading><file>debian/files</file></heading>
10445
10446           <p>
10447             See <ref id="debianfiles">.
10448           </p>
10449         </sect1>
10450
10451         <sect1><heading><file>debian/tmp</file>
10452           </heading>
10453
10454           <p>
10455             This is the canonical temporary location for the
10456             construction of binary packages by the <tt>binary</tt>
10457             target.  The directory <file>tmp</file> serves as the root of
10458             the file system tree as it is being constructed (for
10459             example, by using the package's upstream makefiles install
10460             targets and redirecting the output there), and it also
10461             contains the <tt>DEBIAN</tt> subdirectory.  See <ref
10462             id="pkg-bincreating">.
10463           </p>
10464
10465           <p>
10466             If several binary packages are generated from the same
10467             source tree it is usual to use several
10468             <file>debian/tmp<var>something</var></file> directories, for
10469             example <file>tmp-a</file> or <file>tmp-doc</file>.
10470           </p>
10471
10472           <p>
10473             Whatever <file>tmp</file> directories are created and used by
10474             <tt>binary</tt> must of course be removed by the
10475             <tt>clean</tt> target.</p></sect1>
10476       </sect>
10477
10478
10479       <sect id="pkg-sourcearchives"><heading>Source packages as archives
10480         </heading>
10481
10482         <p>
10483           As it exists on the FTP site, a Debian source package
10484           consists of three related files.  You must have the right
10485           versions of all three to be able to use them.
10486         </p>
10487
10488         <p>
10489           <taglist>
10490             <tag>Debian source control file - <tt>.dsc</tt></tag>
10491             <item>
10492                 This file is a control file used by <prgn>dpkg-source</prgn>
10493                 to extract a source package.
10494                 See <ref id="debiansourcecontrolfiles">.
10495             </item>
10496
10497             <tag>
10498               Original source archive -
10499               <file>
10500                 <var>package</var>_<var>upstream-version</var>.orig.tar.gz
10501               </file>
10502             </tag>
10503
10504             <item>
10505               <p>
10506                 This is a compressed (with <tt>gzip -9</tt>)
10507                 <prgn>tar</prgn> file containing the source code from
10508                 the upstream authors of the program.
10509               </p>
10510             </item>
10511
10512             <tag>
10513               Debian package diff -
10514               <file>
10515                 <var>package</var>_<var>upstream_version-revision</var>.diff.gz
10516               </file>
10517             </tag>
10518             <item>
10519
10520               <p>
10521                 This is a unified context diff (<tt>diff -u</tt>)
10522                 giving the changes which are required to turn the
10523                 original source into the Debian source.  These changes
10524                 may only include editing and creating plain files.
10525                 The permissions of files, the targets of symbolic
10526                 links and the characteristics of special files or
10527                 pipes may not be changed and no files may be removed
10528                 or renamed.
10529               </p>
10530
10531               <p>
10532                 All the directories in the diff must exist, except the
10533                 <file>debian</file> subdirectory of the top of the source
10534                 tree, which will be created by
10535                 <prgn>dpkg-source</prgn> if necessary when unpacking.
10536               </p>
10537
10538               <p>
10539                 The <prgn>dpkg-source</prgn> program will
10540                 automatically make the <file>debian/rules</file> file
10541                 executable (see below).</p></item>
10542           </taglist>
10543         </p>
10544
10545         <p>
10546           If there is no original source code - for example, if the
10547           package is specially prepared for Debian or the Debian
10548           maintainer is the same as the upstream maintainer - the
10549           format is slightly different: then there is no diff, and the
10550           tarfile is named
10551           <file><var>package</var>_<var>version</var>.tar.gz</file>,
10552           and preferably contains a directory named
10553           <file><var>package</var>-<var>version</var></file>.
10554         </p>
10555       </sect>
10556
10557       <sect>
10558         <heading>Unpacking a Debian source package without <prgn>dpkg-source</prgn></heading>
10559
10560         <p>
10561           <tt>dpkg-source -x</tt> is the recommended way to unpack a
10562           Debian source package.  However, if it is not available it
10563           is possible to unpack a Debian source archive as follows:
10564         <enumlist compact="compact">
10565           <item>
10566             <p>
10567               Untar the tarfile, which will create a <file>.orig</file>
10568               directory.</p>
10569           </item>
10570           <item>
10571             <p>Rename the <file>.orig</file> directory to
10572               <file><var>package</var>-<var>version</var></file>.</p>
10573           </item>
10574             <item>
10575             <p>
10576               Create the subdirectory <file>debian</file> at the top of
10577               the source tree.</p>
10578           </item>
10579           <item><p>Apply the diff using <tt>patch -p0</tt>.</p>
10580           </item>
10581           <item><p>Untar the tarfile again if you want a copy of the original
10582               source code alongside the Debian version.</p>
10583           </item>
10584         </enumlist>
10585
10586         <p>
10587           It is not possible to generate a valid Debian source archive
10588           without using <prgn>dpkg-source</prgn>.  In particular,
10589           attempting to use <prgn>diff</prgn> directly to generate the
10590           <file>.diff.gz</file> file will not work.
10591         </p>
10592
10593         <sect1>
10594           <heading>Restrictions on objects in source packages</heading>
10595
10596           <p>
10597             The source package may not contain any hard links
10598             <footnote>
10599                 This is not currently detected when building source
10600                 packages, but only when extracting
10601                 them.
10602             </footnote>
10603             <footnote>
10604                 Hard links may be permitted at some point in the
10605                 future, but would require a fair amount of
10606                 work.
10607             </footnote>, device special files, sockets or setuid or
10608             setgid files.
10609             <footnote>
10610                 Setgid directories are allowed.
10611             </footnote>
10612           </p>
10613
10614           <p>
10615             The source packaging tools manage the changes between the
10616             original and Debian source using <prgn>diff</prgn> and
10617             <prgn>patch</prgn>.  Turning the original source tree as
10618             included in the <file>.orig.tar.gz</file> into the Debian
10619             package source must not involve any changes which cannot be
10620             handled by these tools.  Problematic changes which cause
10621             <prgn>dpkg-source</prgn> to halt with an error when
10622             building the source package are:
10623             <list compact="compact">
10624               <item><p>Adding or removing symbolic links, sockets or pipes.</p>
10625               </item>
10626               <item><p>Changing the targets of symbolic links.</p>
10627               </item>
10628               <item><p>Creating directories, other than <file>debian</file>.</p>
10629               </item>
10630               <item><p>Changes to the contents of binary files.</p></item>
10631             </list> Changes which cause <prgn>dpkg-source</prgn> to
10632             print a warning but continue anyway are:
10633             <list compact="compact">
10634               <item>
10635                 <p>
10636                   Removing files, directories or symlinks.
10637                   <footnote>
10638                       Renaming a file is not treated specially - it is
10639                       seen as the removal of the old file (which
10640                       generates a warning, but is otherwise ignored),
10641                       and the creation of the new one.
10642                   </footnote>
10643                 </p>
10644               </item>
10645               <item>
10646                 <p>
10647                   Changed text files which are missing the usual final
10648                   newline (either in the original or the modified
10649                   source tree).
10650                 </p>
10651               </item>
10652             </list>
10653             Changes which are not represented, but which are not detected by
10654             <prgn>dpkg-source</prgn>, are:
10655             <list compact="compact">
10656               <item><p>Changing the permissions of files (other than
10657                   <file>debian/rules</file>) and directories.</p></item>
10658             </list>
10659           </p>
10660
10661           <p>
10662             The <file>debian</file> directory and <file>debian/rules</file>
10663             are handled specially by <prgn>dpkg-source</prgn> - before
10664             applying the changes it will create the <file>debian</file>
10665             directory, and afterwards it will make
10666             <file>debian/rules</file> world-executable.
10667           </p>
10668         </sect1>
10669       </sect>
10670     </appendix>
10671
10672     <appendix id="pkg-controlfields">
10673       <heading>Control files and their fields (from old Packaging Manual)</heading>
10674
10675       <p>
10676         Many of the tools in the <prgn>dpkg</prgn> suite manipulate
10677         data in a common format, known as control files.  Binary and
10678         source packages have control data as do the <file>.changes</file>
10679         files which control the installation of uploaded files, and
10680         <prgn>dpkg</prgn>'s internal databases are in a similar
10681         format.
10682       </p>
10683
10684       <sect>
10685         <heading>Syntax of control files</heading>
10686
10687         <p>
10688           See <ref id="controlsyntax">.
10689         </p>
10690
10691         <p>
10692           It is important to note that there are several fields which
10693           are optional as far as <prgn>dpkg</prgn> and the related
10694           tools are concerned, but which must appear in every Debian
10695           package, or whose omission may cause problems.
10696         </p>
10697       </sect>
10698
10699       <sect>
10700         <heading>List of fields</heading>
10701
10702         <p>
10703           See <ref id="controlfieldslist">.
10704         </p>
10705
10706         <p>
10707           This section now contains only the fields that didn't belong
10708           to the Policy manual.
10709         </p>
10710
10711         <sect1 id="pkg-f-Filename">
10712           <heading><tt>Filename</tt> and <tt>MSDOS-Filename</tt></heading>
10713
10714           <p>
10715             These fields in <tt>Packages</tt> files give the
10716             filename(s) of (the parts of) a package in the
10717             distribution directories, relative to the root of the
10718             Debian hierarchy.  If the package has been split into
10719             several parts the parts are all listed in order, separated
10720             by spaces.
10721           </p>
10722         </sect1>
10723
10724         <sect1 id="pkg-f-Size">
10725           <heading><tt>Size</tt> and <tt>MD5sum</tt></heading>
10726
10727           <p>
10728             These fields in <file>Packages</file> files give the size (in
10729             bytes, expressed in decimal) and MD5 checksum of the
10730             file(s) which make(s) up a binary package in the
10731             distribution.  If the package is split into several parts
10732             the values for the parts are listed in order, separated by
10733             spaces.
10734           </p>
10735         </sect1>
10736
10737         <sect1 id="pkg-f-Status">
10738           <heading><tt>Status</tt></heading>
10739
10740           <p>
10741             This field in <prgn>dpkg</prgn>'s status file records
10742             whether the user wants a package installed, removed or
10743             left alone, whether it is broken (requiring
10744             re-installation) or not and what its current state on the
10745             system is.  Each of these pieces of information is a
10746             single word.
10747           </p>
10748         </sect1>
10749
10750         <sect1 id="pkg-f-Config-Version">
10751           <heading><tt>Config-Version</tt></heading>
10752
10753           <p>
10754             If a package is not installed or not configured, this
10755             field in <prgn>dpkg</prgn>'s status file records the last
10756             version of the package which was successfully
10757             configured.
10758           </p>
10759         </sect1>
10760
10761         <sect1 id="pkg-f-Conffiles">
10762           <heading><tt>Conffiles</tt></heading>
10763
10764           <p>
10765             This field in <prgn>dpkg</prgn>'s status file contains
10766             information about the automatically-managed configuration
10767             files held by a package.  This field should <em>not</em>
10768             appear anywhere in a package!
10769           </p>
10770         </sect1>
10771
10772         <sect1>
10773           <heading>Obsolete fields</heading>
10774
10775           <p>
10776             These are still recognized by <prgn>dpkg</prgn> but should
10777             not appear anywhere any more.
10778
10779             <taglist compact="compact">
10780
10781               <tag><tt>Revision</tt></tag>
10782               <tag><tt>Package-Revision</tt></tag>
10783               <tag><tt>Package_Revision</tt></tag>
10784               <item>
10785                   The Debian revision part of the package version was
10786                   at one point in a separate control field.  This
10787                   field went through several names.
10788               </item>
10789
10790               <tag><tt>Recommended</tt></tag>
10791               <item>Old name for <tt>Recommends</tt>.</item>
10792
10793               <tag><tt>Optional</tt></tag>
10794               <item>Old name for <tt>Suggests</tt>.</item>
10795
10796               <tag><tt>Class</tt></tag>
10797               <item>Old name for <tt>Priority</tt>.</item>
10798
10799             </taglist>
10800           </p>
10801         </sect1>
10802       </sect>
10803
10804     </appendix>
10805
10806     <appendix id="pkg-conffiles">
10807       <heading>Configuration file handling (from old Packaging Manual)</heading>
10808
10809       <p>
10810         <prgn>dpkg</prgn> can do a certain amount of automatic
10811         handling of package configuration files.
10812       </p>
10813
10814       <p>
10815         Whether this mechanism is appropriate depends on a number of
10816         factors, but basically there are two approaches to any
10817         particular configuration file.
10818       </p>
10819
10820       <p>
10821         The easy method is to ship a best-effort configuration in the
10822         package, and use <prgn>dpkg</prgn>'s conffile mechanism to
10823         handle updates.  If the user is unlikely to want to edit the
10824         file, but you need them to be able to without losing their
10825         changes, and a new package with a changed version of the file
10826         is only released infrequently, this is a good approach.
10827       </p>
10828
10829       <p>
10830         The hard method is to build the configuration file from
10831         scratch in the <prgn>postinst</prgn> script, and to take the
10832         responsibility for fixing any mistakes made in earlier
10833         versions of the package automatically.  This will be
10834         appropriate if the file is likely to need to be different on
10835         each system.
10836       </p>
10837
10838       <sect><heading>Automatic handling of configuration files by
10839       <prgn>dpkg</prgn>
10840         </heading>
10841
10842         <p>
10843           A package may contain a control information file called
10844           <tt>conffiles</tt>.  This file should be a list of filenames
10845           of configuration files needing automatic handling, separated
10846           by newlines.  The filenames should be absolute pathnames,
10847           and the files referred to should actually exist in the
10848           package.
10849         </p>
10850
10851         <p>
10852           When a package is upgraded <prgn>dpkg</prgn> will process
10853           the configuration files during the configuration stage,
10854           shortly before it runs the package's <prgn>postinst</prgn>
10855           script,
10856         </p>
10857
10858         <p>
10859           For each file it checks to see whether the version of the
10860           file included in the package is the same as the one that was
10861           included in the last version of the package (the one that is
10862           being upgraded from); it also compares the version currently
10863           installed on the system with the one shipped with the last
10864           version.
10865         </p>
10866
10867         <p>
10868           If neither the user nor the package maintainer has changed
10869           the file, it is left alone.  If one or the other has changed
10870           their version, then the changed version is preferred - i.e.,
10871           if the user edits their file, but the package maintainer
10872           doesn't ship a different version, the user's changes will
10873           stay, silently, but if the maintainer ships a new version
10874           and the user hasn't edited it the new version will be
10875           installed (with an informative message).  If both have
10876           changed their version the user is prompted about the problem
10877           and must resolve the differences themselves.
10878         </p>
10879
10880         <p>
10881           The comparisons are done by calculating the MD5 message
10882           digests of the files, and storing the MD5 of the file as it
10883           was included in the most recent version of the package.
10884         </p>
10885
10886         <p>
10887           When a package is installed for the first time
10888           <prgn>dpkg</prgn> will install the file that comes with it,
10889           unless that would mean overwriting a file already on the
10890           file system.
10891         </p>
10892
10893         <p>
10894           However, note that <prgn>dpkg</prgn> will <em>not</em>
10895           replace a conffile that was removed by the user (or by a
10896           script).  This is necessary because with some programs a
10897           missing file produces an effect hard or impossible to
10898           achieve in another way, so that a missing file needs to be
10899           kept that way if the user did it.
10900         </p>
10901
10902         <p>
10903           Note that a package should <em>not</em> modify a
10904           <prgn>dpkg</prgn>-handled conffile in its maintainer
10905           scripts.  Doing this will lead to <prgn>dpkg</prgn> giving
10906           the user confusing and possibly dangerous options for
10907           conffile update when the package is upgraded.</p>
10908       </sect>
10909
10910       <sect><heading>Fully-featured maintainer script configuration
10911       handling
10912         </heading>
10913
10914         <p>
10915           For files which contain site-specific information such as
10916           the hostname and networking details and so forth, it is
10917           better to create the file in the package's
10918           <prgn>postinst</prgn> script.
10919         </p>
10920
10921         <p>
10922           This will typically involve examining the state of the rest
10923           of the system to determine values and other information, and
10924           may involve prompting the user for some information which
10925           can't be obtained some other way.
10926         </p>
10927
10928         <p>
10929           When using this method there are a couple of important
10930           issues which should be considered:
10931         </p>
10932
10933         <p>
10934           If you discover a bug in the program which generates the
10935           configuration file, or if the format of the file changes
10936           from one version to the next, you will have to arrange for
10937           the postinst script to do something sensible - usually this
10938           will mean editing the installed configuration file to remove
10939           the problem or change the syntax.  You will have to do this
10940           very carefully, since the user may have changed the file,
10941           perhaps to fix the very problem that your script is trying
10942           to deal with - you will have to detect these situations and
10943           deal with them correctly.
10944         </p>
10945
10946         <p>
10947           If you do go down this route it's probably a good idea to
10948           make the program that generates the configuration file(s) a
10949           separate program in <file>/usr/sbin</file>, by convention called
10950           <file><var>package</var>config</file> and then run that if
10951           appropriate from the post-installation script.  The
10952           <tt><var>package</var>config</tt> program should not
10953           unquestioningly overwrite an existing configuration - if its
10954           mode of operation is geared towards setting up a package for
10955           the first time (rather than any arbitrary reconfiguration
10956           later) you should have it check whether the configuration
10957           already exists, and require a <tt>--force</tt> flag to
10958           overwrite it.</p></sect>
10959     </appendix>
10960
10961     <appendix id="pkg-alternatives"><heading>Alternative versions of
10962         an interface - <prgn>update-alternatives</prgn> (from old
10963     Packaging Manual)
10964       </heading>
10965
10966       <p>
10967         When several packages all provide different versions of the
10968         same program or file it is useful to have the system select a
10969         default, but to allow the system administrator to change it
10970         and have their decisions respected.
10971       </p>
10972
10973       <p>
10974         For example, there are several versions of the <prgn>vi</prgn>
10975         editor, and there is no reason to prevent all of them from
10976         being installed at once, each under their own name
10977         (<prgn>nvi</prgn>, <prgn>vim</prgn> or whatever).
10978         Nevertheless it is desirable to have the name <tt>vi</tt>
10979         refer to something, at least by default.
10980       </p>
10981
10982       <p>
10983         If all the packages involved cooperate, this can be done with
10984         <prgn>update-alternatives</prgn>.
10985       </p>
10986
10987       <p>
10988         Each package provides its own version under its own name, and
10989         calls <prgn>update-alternatives</prgn> in its postinst to
10990         register its version (and again in its prerm to deregister
10991         it).
10992       </p>
10993
10994       <p>
10995         See the man page <manref name="update-alternatives"
10996         section="8"> for details.
10997       </p>
10998
10999       <p>
11000         If <prgn>update-alternatives</prgn> does not seem appropriate
11001         you may wish to consider using diversions instead.</p>
11002     </appendix>
11003
11004     <appendix id="pkg-diversions"><heading>Diversions - overriding a
11005     package's version of a file (from old Packaging Manual)
11006       </heading>
11007
11008       <p>
11009         It is possible to have <prgn>dpkg</prgn> not overwrite a file
11010         when it reinstalls the package it belongs to, and to have it
11011         put the file from the package somewhere else instead.
11012       </p>
11013
11014       <p>
11015         This can be used locally to override a package's version of a
11016         file, or by one package to override another's version (or
11017         provide a wrapper for it).
11018       </p>
11019
11020       <p>
11021         Before deciding to use a diversion, read <ref
11022         id="pkg-alternatives"> to see if you really want a diversion
11023         rather than several alternative versions of a program.
11024       </p>
11025
11026       <p>
11027         There is a diversion list, which is read by <prgn>dpkg</prgn>,
11028         and updated by a special program <prgn>dpkg-divert</prgn>.
11029         Please see <manref name="dpkg-divert" section="8"> for full
11030         details of its operation.
11031       </p>
11032
11033       <p>
11034         When a package wishes to divert a file from another, it should
11035         call <prgn>dpkg-divert</prgn> in its preinst to add the
11036         diversion and rename the existing file.  For example,
11037         supposing that a <prgn>smailwrapper</prgn> package wishes to
11038         install a wrapper around <file>/usr/sbin/smail</file>:
11039         <example>
11040    dpkg-divert --package smailwrapper --add --rename \
11041       --divert /usr/sbin/smail.real /usr/sbin/smail
11042         </example> The <tt>--package smailwrapper</tt> ensures that
11043         <prgn>smailwrapper</prgn>'s copy of <file>/usr/sbin/smail</file>
11044         can bypass the diversion and get installed as the true version.
11045         It's safe to add the diversion unconditionally on upgrades since
11046         it will be left unchanged if it already exists, but
11047         <prgn>dpkg-divert</prgn> will display a message.  To suppress that
11048         message, make the command conditional on the version from which
11049         the package is being upgraded:
11050         <example>
11051    if [ upgrade != "$1" ] || dpkg --compare-versions "$2" lt 1.0-2; then
11052       dpkg-divert --package smailwrapper --add --rename \
11053          --divert /usr/sbin/smail.real /usr/sbin/smail
11054    fi
11055         </example> where <tt>1.0-2</tt> is the version at which the
11056         diversion was first added to the package.  Running the command
11057         during abort-upgrade is pointless but harmless.
11058       </p>
11059
11060       <p>
11061         The postrm has to do the reverse:
11062         <example>
11063   if [ remove = "$1" -o abort-install = "$1" -o disappear = "$1" ]; then
11064      dpkg-divert --package smailwrapper --remove --rename \
11065         --divert /usr/sbin/smail.real /usr/sbin/smail
11066   fi
11067         </example> If the diversion was added at a particular version, the
11068         postrm should also handle the failure case of upgrading from an
11069         older version (unless the older version is so old that direct
11070         upgrades are no longer supported):
11071         <example>
11072   if [ abort-upgrade = "$1" ] && dpkg --compare-versions "$2" lt 1.0-2; then
11073      dpkg-divert --package smailwrapper --remove --rename \
11074         --divert /usr/sbin/smail.real /usr/sbin/smail
11075   fi
11076         </example> where <tt>1.02-2</tt> is the version at which the
11077         diversion was first added to the package.  The postrm should not
11078         remove the diversion on upgrades both because there's no reason to
11079         remove the diversion only to immediately re-add it and since the
11080         postrm of the old package is run after unpacking so the removal of
11081         the diversion will fail.
11082       </p>
11083
11084       <p>
11085         Do not attempt to divert a file which is vitally important for
11086         the system's operation - when using <prgn>dpkg-divert</prgn>
11087         there is a time, after it has been diverted but before
11088         <prgn>dpkg</prgn> has installed the new version, when the file
11089         does not exist.</p>
11090     </appendix>
11091
11092   </book>
11093 </debiandoc>
11094 <!-- Local variables: -->
11095 <!-- indent-tabs-mode: t -->
11096 <!-- End: -->
11097 <!-- vim:set ai et sts=2 sw=2 tw=76: -->