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;
10 <title>Debian Policy Manual</title>
11 <author><qref id="authors">The Debian Policy Mailing List</qref></author>
12 <version>version &version;, &date;</version>
15 This manual describes the policy requirements for the Debian
16 GNU/Linux distribution. This includes the structure and
17 contents of the Debian archive and several design issues of
18 the operating system, as well as technical requirements that
19 each package must satisfy to be included in the distribution.
24 Copyright © 1996,1997,1998 Ian Jackson
25 and Christian Schwarz.
28 This manual is free software; you may redistribute it and/or
29 modify it under the terms of the GNU General Public License
30 as published by the Free Software Foundation; either version
31 2, or (at your option) any later version.
35 This is distributed in the hope that it will be useful, but
36 <em>without any warranty</em>; without even the implied
37 warranty of merchantability or fitness for a particular
38 purpose. See the GNU General Public License for more
43 A copy of the GNU General Public License is available as
44 <file>/usr/share/common-licenses/GPL</file> in the Debian GNU/Linux
45 distribution or on the World Wide Web at
46 <url id="http://www.gnu.org/copyleft/gpl.html"
47 name="the GNU General Public Licence">. You can also
48 obtain it by writing to the Free Software Foundation, Inc.,
49 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
57 <heading>About this manual</heading>
59 <heading>Scope</heading>
61 This manual describes the policy requirements for the Debian
62 GNU/Linux distribution. This includes the structure and
63 contents of the Debian archive and several design issues of the
64 operating system, as well as technical requirements that
65 each package must satisfy to be included in the
70 This manual also describes Debian policy as it relates to
71 creating Debian packages. It is not a tutorial on how to build
72 packages, nor is it exhaustive where it comes to describing
73 the behavior of the packaging system. Instead, this manual
74 attempts to define the interface to the package management
75 system that the developers have to be conversant with.<footnote>
77 Informally, the criteria used for inclusion is that the
78 material meet one of the following requirements:
79 <taglist compact="compact">
80 <tag>Standard interfaces</tag>
82 The material presented represents an interface to
83 the packaging system that is mandated for use, and
84 is used by, a significant number of packages, and
85 therefore should not be changed without peer
86 review. Package maintainers can then rely on this
87 interfaces not changing, and the package
88 management software authors need to ensure
89 compatibility with these interface
90 definitions. (Control file and changelog file
91 formats are examples.)
93 <tag>Chosen Convention</tag>
95 If there are a number of technically viable choices
96 that can be made, but one needs to select one of
97 these options for inter-operability. The version
98 number format is one example.
101 Please note that these are not mutually exclusive;
102 selected conventions often become parts of standard
109 The footnotes present in this manual are
110 merely informative, and are not part of Debian policy itself.
114 The appendices to this manual are not necessarily normative,
115 either. Please see <ref id="pkg-scope"> for more information.
119 In the normative part of this manual,
120 the words <em>must</em>, <em>should</em> and
121 <em>may</em>, and the adjectives <em>required</em>,
122 <em>recommended</em> and <em>optional</em>, are used to
123 distinguish the significance of the various guidelines in
124 this policy document. Packages that do not conform to the
125 guidelines denoted by <em>must</em> (or <em>required</em>)
126 will generally not be considered acceptable for the Debian
127 distribution. Non-conformance with guidelines denoted by
128 <em>should</em> (or <em>recommended</em>) will generally be
129 considered a bug, but will not necessarily render a package
130 unsuitable for distribution. Guidelines denoted by
131 <em>may</em> (or <em>optional</em>) are truly optional and
132 adherence is left to the maintainer's discretion.
136 These classifications are roughly equivalent to the bug
137 severities <em>serious</em> (for <em>must</em> or
138 <em>required</em> directive violations), <em>minor</em>,
139 <em>normal</em> or <em>important</em>
140 (for <em>should</em> or <em>recommended</em> directive
141 violations) and <em>wishlist</em> (for <em>optional</em>
144 Compare RFC 2119. Note, however, that these words are
145 used in a different way in this document.
150 Much of the information presented in this manual will be
151 useful even when building a package which is to be
152 distributed in some other way or is intended for local use
158 <heading>New versions of this document</heading>
161 This manual is distributed via the Debian package
162 <package>debian-policy</package>.
166 The current version of this document is also available from
167 the Debian web mirrors at
168 <tt><url name="/doc/debian-policy/"
169 id="http://www.debian.org/doc/debian-policy/"></tt>
170 and from the Debian archive mirrors at
171 <tt><url name="/doc/package-developer/policy.txt.gz"
172 id="http://ftp.debian.org/debian/doc/package-developer/policy.txt.gz"></tt>.
173 Also available from the same directory are several other
174 formats: <file>policy.html.tar.gz</file>, <file>policy.pdf.gz</file>
175 and <file>policy.ps.gz</file>.
179 The <package>debian-policy</package> package also includes the file
180 <file>upgrading-checklist.txt</file> which indicates policy
181 changes between versions of this document.
186 <heading>Authors and Maintainers</heading>
189 Originally called "Debian GNU/Linux Policy Manual", this
190 manual was initially written in 1996 by Ian Jackson.
191 It was revised on November 27th, 1996 by David A. Morris.
192 Christian Schwarz added new sections on March 15th, 1997,
193 and reworked/restructured it in April-July 1997.
194 Christoph Lameter contributed the "Web Standard".
195 Julian Gilbey largely restructured it in 2001.
199 Since September 1998, the responsibility for the contents of
200 this document lies on the <url name="debian-policy mailing list"
201 id="mailto:debian-policy@lists.debian.org">. Proposals
202 are discussed there and inserted into policy after a certain
203 consensus is established.
204 <!-- insert shameless policy-process plug here eventually -->
205 The actual editing is done by a group of maintainers that have
206 no editorial powers. These are the current maintainers:
209 <item>Julian Gilbey</item>
210 <item>Branden Robinson</item>
211 <item>Josip Rodin</item>
212 <item>Manoj Srivastava</item>
217 While the authors of this document have tried hard to avoid
218 typos and other errors, these do still occur. If you discover
219 an error in this manual or if you want to give any
220 comments, suggestions, or criticisms please send an email to
221 the Debian Policy List,
222 <email>debian-policy@lists.debian.org</email>, or submit a
223 bug report against the <tt>debian-policy</tt> package.
227 Please do not try to reach the individual authors or maintainers
228 of the Policy Manual regarding changes to the Policy.
233 <heading>Related documents</heading>
236 There are several other documents other than this Policy Manual
237 that are necessary to fully understand some Debian policies and
242 The external "sub-policy" documents are referred to in:
243 <list compact="compact">
244 <item><ref id="fhs"></item>
245 <item><ref id="virtual_pkg"></item>
246 <item><ref id="menus"></item>
247 <item><ref id="mime"></item>
248 <item><ref id="perl"></item>
249 <item><ref id="maintscriptprompt"></item>
250 <item><ref id="emacs"></item>
255 In addition to those, which carry the weight of policy, there
256 is the Debian Developer's Reference. This document describes
257 procedures and resources for Debian developers, but it is
258 <em>not</em> normative; rather, it includes things that don't
259 belong into the Policy, such as best practices for developers.
263 The Developer's Reference is available in the
264 <package>developers-reference</package> package.
265 It's also available from the Debian web mirrors at
266 <tt><url name="/doc/developers-reference/"
267 id="http://www.debian.org/doc/developers-reference/"></tt>.
275 <heading>The Debian Archive</heading>
278 The Debian GNU/Linux system is maintained and distributed as a
279 collection of <em>packages</em>. Since there are so many of
280 them (currently well over 6000), they are split into
281 <em>sections</em> and given <em>priorities</em> to simplify
282 the handling of them.
286 The effort of the Debian project is to build a free operating
287 system, but not every package we want to make accessible is
288 <em>free</em> in our sense (see the Debian Free Software
289 Guidelines, below), or may be imported/exported without
290 restrictions. Thus, the archive is split into the sections
291 <em>main</em>, <em>non-free</em>, <em>contrib</em>,
292 <em>non-US/main</em>, <em>non-US/non-free</em>, and
293 <em>non-US/contrib</em>. The sections are explained in detail
298 The <em>main</em> and the <em>non-US/main</em> sections
299 together form the <em>Debian GNU/Linux distribution</em>.
303 Packages in the other sections are not considered to be part
304 of the Debian distribution, although we support their use and
305 provide infrastructure for them (such as our bug-tracking
306 system and mailing lists). This Debian Policy Manual applies
307 to these packages as well.</p>
309 <sect id="pkgcopyright">
310 <heading>Package copyright and sections</heading>
312 The aims of this section are:
314 <list compact="compact">
316 to allow us to make as much software available as we can,
319 to allow us to encourage everyone to write free software, and
322 to allow us to make it easy for people to produce
323 CD-ROMs of our system without violating any licenses,
324 import/export restrictions, or any other laws.
329 <heading>The Debian Free Software Guidelines</heading>
331 The Debian Free Software Guidelines (DFSG) form our
332 definition of "free software". These are:
334 <tag>Free Redistribution
337 The license of a Debian component may not restrict any
338 party from selling or giving away the software as a
339 component of an aggregate software distribution
340 containing programs from several different
341 sources. The license may not require a royalty or
342 other fee for such sale.
347 The program must include source code, and must allow
348 distribution in source code as well as compiled form.
353 The license must allow modifications and derived
354 works, and must allow them to be distributed under the
355 same terms as the license of the original software.
357 <tag>Integrity of The Author's Source Code
360 The license may restrict source-code from being
361 distributed in modified form <em>only</em> if the
362 license allows the distribution of "patch files"
363 with the source code for the purpose of modifying the
364 program at build time. The license must explicitly
365 permit distribution of software built from modified
366 source code. The license may require derived works to
367 carry a different name or version number from the
368 original software. (This is a compromise. The Debian
369 Project encourages all authors to not restrict any
370 files, source or binary, from being modified.)
372 <tag>No Discrimination Against Persons or Groups
375 The license must not discriminate against any person
378 <tag>No Discrimination Against Fields of Endeavor
381 The license must not restrict anyone from making use
382 of the program in a specific field of endeavor. For
383 example, it may not restrict the program from being
384 used in a business, or from being used for genetic
387 <tag>Distribution of License
390 The rights attached to the program must apply to all
391 to whom the program is redistributed without the need
392 for execution of an additional license by those
395 <tag>License Must Not Be Specific to Debian
398 The rights attached to the program must not depend on
399 the program's being part of a Debian system. If the
400 program is extracted from Debian and used or
401 distributed without Debian but otherwise within the
402 terms of the program's license, all parties to whom
403 the program is redistributed must have the same
404 rights as those that are granted in conjunction with
407 <tag>License Must Not Contaminate Other Software
410 The license must not place restrictions on other
411 software that is distributed along with the licensed
412 software. For example, the license must not insist
413 that all other programs distributed on the same medium
414 must be free software.
416 <tag>Example Licenses
419 The "GPL," "BSD," and "Artistic" licenses are examples of
420 licenses that we consider <em>free</em>.
426 <heading>The main section</heading>
428 Every package in <em>main</em> and <em>non-US/main</em>
429 must comply with the DFSG (Debian Free Software
434 In addition, the packages in <em>main</em>
435 <list compact="compact">
437 must not require a package outside of <em>main</em>
438 for compilation or execution (thus, the package must
439 not declare a "Depends", "Recommends", or
440 "Build-Depends" relationship on a non-<em>main</em>
444 must not be so buggy that we refuse to support them,
448 must meet all policy requirements presented in this
455 Similarly, the packages in <em>non-US/main</em>
456 <list compact="compact">
458 must not require a package outside of <em>main</em>
459 or <em>non-US/main</em> for compilation or
463 must not be so buggy that we refuse to support them,
466 must meet all policy requirements presented in this
475 <heading>The contrib section</heading>
478 Every package in <em>contrib</em> and
479 <em>non-US/contrib</em> must comply with the DFSG.
483 In addition, the packages in <em>contrib</em> and
484 <em>non-US/contrib</em>
485 <list compact="compact">
487 must not be so buggy that we refuse to support them,
491 must meet all policy requirements presented in this
498 Furthermore, packages in <em>contrib</em> must not require
499 a package in a <em>non-US</em> section for compilation or
504 Examples of packages which would be included in
505 <em>contrib</em> or <em>non-US/contrib</em> are:
506 <list compact="compact">
508 free packages which require <em>contrib</em>,
509 <em>non-free</em> packages or packages which are not
510 in our archive at all for compilation or execution,
514 wrapper packages or other sorts of free accessories for
521 <sect1 id="non-free">
522 <heading>The non-free section</heading>
525 Packages must be placed in <em>non-free</em> or
526 <em>non-US/non-free</em> if they are not compliant with
527 the DFSG or are encumbered by patents or other legal
528 issues that make their distribution problematic.
532 In addition, the packages in <em>non-free</em> and
533 <em>non-US/non-free</em>
534 <list compact="compact">
536 must not be so buggy that we refuse to support them,
540 must meet all policy requirements presented in this
541 manual that it is possible for them to meet.
543 It is possible that there are policy
544 requirements which the package is unable to
545 meet, for example, if the source is
546 unavailable. These situations will need to be
547 handled on a case-by-case basis.
555 <heading>The non-US sections</heading>
558 Non-free programs with cryptographic program code need to
559 be stored on the <em>non-us</em> server because of export
560 restrictions of the U.S.
564 Programs which use patented algorithms that have a
565 restrictied license also need to be stored on "non-us",
566 since that is located in a country where it is not allowed
567 to patent algorithms.
571 A package depends on another package which is distributed
572 via the non-us server has to be stored on the non-us
577 <heading>Further copyright considerations</heading>
579 Every package must be accompanied by a verbatim copy of
580 its copyright and distribution license in the file
581 <file>/usr/share/doc/<var>package</var>/copyright</file>
582 (see <ref id="copyrightfile"> for further details).
585 We reserve the right to restrict files from being included
586 anywhere in our archives if
587 <list compact="compact">
589 their use or distribution would break a law,
592 there is an ethical conflict in their distribution or
596 we would have to sign a license for them, or
599 their distribution would conflict with other project
606 Programs whose authors encourage the user to make
607 donations are fine for the main distribution, provided
608 that the authors do not claim that not donating is
609 immoral, unethical, illegal or something similar; in such
610 a case they must go in <em>non-free</em>.</p>
613 Packages whose copyright permission notices (or patent
614 problems) do not even allow redistribution of binaries
615 only, and where no special permission has been obtained,
616 must not be placed on the Debian FTP site and its mirrors
620 Note that under international copyright law (this applies
621 in the United States, too), <em>no</em> distribution or
622 modification of a work is allowed without an explicit
623 notice saying so. Therefore a program without a copyright
624 notice <em>is</em> copyrighted and you may not do anything
625 to it without risking being sued! Likewise if a program
626 has a copyright notice but no statement saying what is
627 permitted then nothing is permitted.</p>
630 Many authors are unaware of the problems that restrictive
631 copyrights (or lack of copyright notices) can cause for
632 the users of their supposedly-free software. It is often
633 worthwhile contacting such authors diplomatically to ask
634 them to modify their license terms. However, this can be a
635 politically difficult thing to do and you should ask for
636 advice on the <tt>debian-legal</tt> mailing list first, as
641 When in doubt about a copyright, send mail to
642 <email>debian-legal@lists.debian.org</email>. Be prepared
643 to provide us with the copyright statement. Software
644 covered by the GPL, public domain software and BSD-like
645 copyrights are safe; be wary of the phrases "commercial
646 use prohibited" and "distribution restricted".
650 <heading>Subsections</heading>
653 The packages in the sections <em>main</em>,
654 <em>contrib</em> and <em>non-free</em> are grouped further
655 into <em>subsections</em> to simplify handling.
659 The section and subsection for each package should be
660 specified in the package's <tt>Section</tt> control
661 record. However, the maintainer of the Debian archive
662 may override this selection to ensure the consistency of
663 the Debian distribution. The <tt>Section</tt> field
664 should be of the form:
665 <list compact="compact">
667 <em>subsection</em> if the package is in the
668 <em>main</em> section,
671 <em>section/subsection</em> if the package is in
672 the <em>contrib</em> or <em>non-free</em> section,
676 <tt>non-US</tt>, <tt>non-US/contrib</tt> or
677 <tt>non-US/non-free</tt> if the package is in
678 <em>non-US/main</em>, <em>non-US/contrib</em> or
679 <em>non-US/non-free</em> respectively.
685 The Debian archive maintainers provide the authoritative
686 list of subsections. At present, they are:
687 <em>admin</em>, <em>base</em>, <em>comm</em>,
688 <em>contrib</em>, <em>devel</em>, <em>doc</em>,
689 <em>editors</em>, <em>electronics</em>, <em>games</em>,
690 <em>graphics</em>, <em>hamradio</em>,
691 <em>interpreters</em>, <em>libs</em>, <em>mail</em>,
692 <em>math</em>, <em>misc</em>, <em>net</em>, <em>news</em>,
693 <em>non-US</em>, <em>non-free</em>, <em>oldlibs</em>,
694 <em>otherosfs</em>, <em>science</em>, <em>shells</em>,
695 <em>sound</em>, <em>tex</em>, <em>text</em>,
696 <em>utils</em>, <em>web</em>, <em>x11</em>.
700 <heading>Priorities</heading>
703 Each package should have a <em>priority</em> value, which is
704 included in the package's <em>control record</em>. This
705 information is used by the Debian package management tools
706 to separate high-priority packages from less-important
710 The following <em>priority levels</em> are recognised by the
711 Debian package management tools.
713 <tag><tt>required</tt></tag>
715 Packages which are necessary for the proper
716 functioning of the system. You must not remove these
717 packages or your system may become totally broken and
718 you may not even be able to use <prgn>dpkg</prgn> to
719 put things back. Systems with only the
720 <tt>required</tt> packages are probably unusable, but
721 they do have enough functionality to allow the
722 sysadmin to boot and install more software.
724 <tag><tt>important</tt></tag>
726 Important programs, including those which one would
727 expect to find on any Unix-like system. If the
728 expectation is that an experienced Unix person who
729 found it missing would say "What on earth is going on,
730 where is <prgn>foo</prgn>?", it must be an
731 <tt>important</tt> package.<footnote>
732 This is an important criterion because we are
733 trying to produce, amongst other things, a free
736 Other packages without which the system will not run
737 well or be usable must also have priority
738 <tt>important</tt>. This does
739 <em>not</em> include Emacs, the X Window System, TeX
740 or any other large applications. The
741 <tt>important</tt> packages are just a bare minimum of
742 commonly-expected and necessary tools.
744 <tag><tt>standard</tt></tag>
746 These packages provide a reasonably small but not too
747 limited character-mode system. This is what will be
748 installed by default if the user doesn't select anything
749 else. It doesn't include many large applications.
751 <tag><tt>optional</tt></tag>
753 (In a sense everything that isn't required is
754 optional, but that's not what is meant here.) This is
755 all the software that you might reasonably want to
756 install if you didn't know what it was and don't have
757 specialized requirements. This is a much larger system
758 and includes the X Window System, a full TeX
759 distribution, and many applications. Note that
760 optional packages should not conflict with each other.
762 <tag><tt>extra</tt></tag>
764 This contains all packages that conflict with others
765 with required, important, standard or optional
766 priorities, or are only likely to be useful if you
767 already know what they are or have specialised
774 Packages must not depend on packages with lower priority
775 values (excluding build-time dependencies). In order to
776 ensure this, the priorities of one or more packages may need
782 <heading>Binary packages</heading>
785 The Debian GNU/Linux distribution is based on the Debian
786 package management system, called <prgn>dpkg</prgn>. Thus,
787 all packages in the Debian distribution must be provided
788 in the <tt>.deb</tt> file format.</p>
792 <heading>The package name</heading>
795 Every package must have a name that's unique within the Debian
799 Package names must consist only of lower case letters
800 (<tt>a-z</tt>), digits (<tt>0-9</tt>), plus (<tt>+</tt>)
801 and minus (<tt>-</tt>) signs, and periods (<tt>.</tt>).
802 They must be at least two characters long and must start
803 with an alphanumeric character.
807 The package name is part of the file name of the
808 <tt>.deb</tt> file and is included in the control field
814 <heading>The maintainer of a package</heading>
816 Every package must have a Debian maintainer (the
817 maintainer may be one person or a group of people
818 reachable from a common email address, such as a mailing
819 list). The maintainer is responsible for ensuring that
820 the package is placed in the appropriate distributions.
824 The maintainer must be specified in the
825 <tt>Maintainer</tt> control field with their correct name
826 and a working email address. If one person maintains
827 several packages, he/she should try to avoid having
828 different forms of their name and email address in
829 the <tt>Maintainer</tt> fields of those packages.
833 If the maintainer of a package quits from the Debian
834 project, "Debian QA Group"
835 <email>packages@qa.debian.org</email> takes over the
836 maintainership of the package until someone else
837 volunteers for that task. These packages are called
838 <em>orphaned packages</em>.<footnote>
839 The detailed procedure for doing this gracefully can
840 be found in the Debian Developer's Reference,
841 see <ref id="related">.
848 <heading>The description of a package</heading>
851 Every Debian package must have an extended description
852 stored in the appropriate field of the control record.</p>
855 The description should be written so that it gives the
856 system administrator enough information to decide whether
857 to install the package. This description should not just
858 be copied verbatim from the program's documentation.
859 Instructions for configuring or using the package should
860 not be included (that is what installation scripts,
861 manual pages, info files, etc., are for). Copyright
862 statements and other administrivia should not be included
863 either (that is what the copyright file is for).
867 Please refer to <ref id="descriptions"> for more information.
874 <heading>Dependencies</heading>
877 Every package must specify the dependency information
878 about other packages that are required for the first to
882 For example, a dependency entry must be provided for any
883 shared libraries required by a dynamically-linked executable
884 binary in a package.</p>
887 Packages are not required to declare any dependencies they
888 have on other packages which are marked <tt>Essential</tt>
889 (see below), and should not do so unless they depend on a
890 particular version of that package.</p>
893 Sometimes, a package requires another package to be installed
894 <em>and</em> configured before it can be installed. In this
895 case, you must specify a <tt>Pre-Depends</tt> entry for
899 You should not specify a <tt>Pre-Depends</tt> entry for a
900 package before this has been discussed on the
901 <tt>debian-devel</tt> mailing list and a consensus about
902 doing that has been reached.</p></sect1>
905 <sect1 id="virtual_pkg">
906 <heading>Virtual packages</heading>
909 Sometimes, there are several packages which offer
910 more-or-less the same functionality. In this case, it's
911 useful to define a <em>virtual package</em> whose name
912 describes that common functionality. (The virtual
913 packages only exist logically, not physically; that's why
914 they are called <em>virtual</em>.) The packages with this
915 particular function will then <em>provide</em> the virtual
916 package. Thus, any other package requiring that function
917 can simply depend on the virtual package without having to
918 specify all possible packages individually.</p>
921 All packages should use virtual package names where
922 appropriate, and arrange to create new ones if necessary.
923 They should not use virtual package names (except privately,
924 amongst a cooperating group of packages) unless they have
925 been agreed upon and appear in the list of virtual package
926 names. (See also <ref id="virtual">)</p>
929 The latest version of the authoritative list of virtual
930 package names can be found in the <tt>debian-policy</tt> package.
931 It's also available from the Debian web mirrors at
932 <tt><url name="/doc/packaging-manuals/virtual-package-names-list.txt"
933 id="http://www.debian.org/doc/packaging-manuals/virtual-package-names-list.txt"></tt>
934 and from the Debian archive mirrors at
935 <tt><url name="/doc/package-developer/virtual-package-names-list.txt"
936 id="http://ftp.debian.org/debian/doc/package-developer/virtual-package-names-list.txt"></tt>.
940 The procedure for updating the list is described in the preface
947 <heading>Base system</heading>
950 The <tt>base system</tt> is a minimum subset of the Debian
951 GNU/Linux system that is installed before everything else
952 on a new system. Thus, only very few packages are allowed
953 to go into the <tt>base</tt> section to keep the required
954 disk usage very small.</p>
957 Most of these packages will have the priority value
958 <tt>required</tt> or at least <tt>important</tt>, and many
959 of them will be tagged <tt>essential</tt> (see below).</p>
966 <heading>Essential packages</heading>
969 Some packages are tagged <tt>essential</tt>. (They have
970 <tt>Essential: yes</tt> in their package control record.)
971 This flag is used for packages that are <em>essential</em>
975 Since these packages cannot be easily removed (one has to
976 specify an extra <em>force option</em> to
977 <prgn>dpkg</prgn> to do so), this flag must not be used
978 unless absolutely necessary. A shared library package
979 must not be tagged <tt>essential</tt>; dependencies will
980 prevent its premature removal, and we need to be able to
981 remove it when it has been superseded.
985 Since dpkg will not prevent upgrading of other packages
986 while an <tt>essential</tt> package is in an unconfigured
987 state, all <tt>essential</tt> packages must supply all of
988 their core functionality even when unconfigured. If the
989 package cannot satisfy this requirement it must not be
990 tagged as essential, and any packages depending on this
991 package must instead have explicit dependency fields as
996 You must not tag any packages <tt>essential</tt> before
997 this has been discussed on the <tt>debian-devel</tt>
998 mailing list and a consensus about doing that has been
1003 <heading>Tasks</heading>
1006 The Debian install process allows the user to choose from
1007 a number of common tasks which a Debian system can be used to
1008 perform. Selecting a task with <prgn>tasksel</prgn> causes
1009 a set of packages that are useful in performing that task to be
1014 This set of packages is all available packages which have the
1015 name of the selected task in the <tt>Task</tt> field of their
1016 control file. The format of this field is a list of tasks,
1017 separated by commas.
1021 You should not tag any packages as belonging to a task
1022 before this has been discussed on the
1023 <em>debian-devel</em> mailing list and a consensus about
1024 doing that has been reached.
1028 For third parties (and historical reasons), tasksel also
1029 supports constructing tasks based on <em>task
1030 packages</em>. These are packages whose names begin with
1031 <em>task-</em>. Task packages should not be included in the
1036 <sect1 id="maintscripts">
1037 <heading>Maintainer Scripts</heading>
1040 The package installation scripts should avoid producing
1041 output which it is unnecessary for the user to see and
1042 should rely on <prgn>dpkg</prgn> to stave off boredom on
1043 the part of a user installing many packages. This means,
1044 amongst other things, using the <tt>--quiet</tt> option on
1045 <prgn>install-info</prgn>.</p>
1048 Errors which occur during the execution of an installation
1049 script must be checked and the installation must not
1050 continue after an error.
1054 Note that in general <ref id="scripts"> applies to package
1055 maintainer scripts, too.
1059 You should not use <prgn>dpkg-divert</prgn> on a file
1060 belonging to another package without consulting the
1061 maintainer of that package first.
1065 All packages which supply an instance of a common command
1066 name (or, in general, filename) should generally use
1067 <prgn>update-alternatives</prgn>, so that they may be
1068 installed together. If <prgn>update-alternatives</prgn>
1069 is not used, then each package must use
1070 <tt>Conflicts</tt> to ensure that other packages are
1071 de-installed. (In this case, it may be appropriate to
1072 specify a conflict against earlier versions of something
1073 that previously did not use
1074 <prgn>update-alternatives</prgn>; this is an exception to
1075 the usual rule that versioned conflicts should be
1080 <sect2 id="maintscriptprompt">
1081 <heading>Prompting in maintainer scripts</heading>
1083 Package maintainer scripts may prompt the user if
1084 necessary. Prompting may be accomplished by
1086 From the Jargon file: by hand 2. By extension,
1087 writing code which does something in an explicit or
1088 low-level way for which a presupplied library
1089 (<em>debconf, in this instance</em>) routine ought
1090 to have been available.
1091 </footnote> (but this is deprecated), or by communicating
1092 through a program which conforms to the Debian Configuration
1093 management specification, version 2 or higher, such as
1094 <prgn>debconf</prgn><footnote>
1096 6% of Debian packages [see <url
1097 id="http://auric.debian.org/%7Ejoeyh/debconf-stats/data/"
1098 name="Debconf stats">] currently use
1099 <package>debconf</package> to prompt the user at
1100 install time, and this number is growing daily. The
1101 benefits of using debconf are briefly explained at
1103 id="http://kitenet.net/doc/debconf-doc/introduction.html"
1104 name="Debconf introduction">; they include
1105 preconfiguration, (mostly) noninteractive
1106 installation, elimination of redundant prompting,
1107 consistency of user interface, etc.
1111 With this increasing number of packages using
1112 <package>debconf</package>, plus the existance of a
1113 nascent second implementation of the Debian
1114 configuration management system
1115 (<package>cdebconf</package>), and the stabilization
1116 of the protocol these things use, the time has
1117 finally come to reflect the use of these things in
1124 The Debian Configuration management specification is included
1125 in the <file>debconf_specification</file> files in the
1126 <package>debian-policy</package> package.
1127 It is also available from the Debian web mirrors at
1128 <tt><url name="/doc/packaging-manuals/debconf_specification.html"
1129 id="http://www.debian.org/doc/packaging-manuals/debconf_specification.html"></tt>
1130 and from the Debian archive mirrors at
1131 <tt><url name="/doc/package-developer/debconf_specification.txt.gz"
1132 id="http://ftp.debian.org/debian/doc/package-developer/debconf_specification.txt.gz"></tt>.
1136 Packages which use the Debian Configuration management
1137 specification may contain an additional
1138 <prgn>config</prgn> script and a <tt>templates</tt>
1139 file in their control archive. The <prgn>config</prgn>
1140 script might be run before the <prgn>preinst</prgn>
1141 script, and before the package is unpacked or any of its
1142 dependencies or pre-dependancies are satisfied.
1143 Therefore it must work using only the tools present in
1144 <em>essential</em> packages.<footnote>
1145 <package>Debconf</package> or another tool that
1146 implements the Debian Configuration management
1147 specification will also be installed, and any
1148 versioned dependencies on it will be satisfied
1149 before preconfiguration begins.
1154 Packages should try to minimize the amount of prompting
1155 they need to do, and they should ensure that the user
1156 will only ever be asked each question once. This means
1157 that packages should try to use appropriate shared
1158 configuration files (such as <file>/etc/papersize</file> and
1159 <file>/etc/news/server</file>), and shared
1160 <package>debconf</package> variables rather than each
1161 prompting for their own list of required pieces of
1166 It also means that an upgrade should not ask the same
1167 questions again, unless the user has used <tt>dpkg
1168 --purge</tt> to remove the package's configuration. The
1169 answers to configuration questions should be stored in an
1170 appropriate place in <file>/etc</file> so that the user can
1171 modify them, and how this has been done should be
1175 If a package has a vitally important piece of
1176 information to pass to the user (such as "don't run me
1177 as I am, you must edit the following configuration files
1178 first or you risk your system emitting badly-formatted
1179 messages"), it should display this in the
1180 <prgn>config</prgn> or <prgn>postinst</prgn> script and
1181 prompt the user to hit return to acknowledge the
1182 message. Copyright messages do not count as vitally
1183 important (they belong in
1184 <file>/usr/share/doc/<var>package</var>/copyright</file>);
1185 neither do instructions on how to use a program (these
1186 should be in on-line documentation, where all the users
1190 Any necessary prompting should almost always be confined
1191 to the <prgn>config</prgn> or <prgn>postinst</prgn>
1192 script. If it is done in the <prgn>postinst</prgn>, it
1193 should be protected with a conditional so that
1194 unnecessary prompting doesn't happen if a package's
1195 installation fails and the <prgn>postinst</prgn> is
1196 called with <tt>abort-upgrade</tt>,
1197 <tt>abort-remove</tt> or <tt>abort-deconfigure</tt>.</p>
1202 <heading>Source packages</heading>
1204 <sect1 id="standardsversion">
1205 <heading>Standards conformance</heading>
1208 In the source package's <tt>Standards-Version</tt> control
1209 field, you should specify the most recent version number
1210 of this policy document with which your package complied
1211 when it was last updated. The current version number is
1216 This information may be used to file bug reports
1217 automatically if your package becomes too much out of
1222 The version number has four components: major and minor
1223 version number and major and minor patch level. When the
1224 standards change in a way that requires every package to
1225 change the major number will be changed. Significant
1226 changes that will require work in many packages will be
1227 signaled by a change to the minor number. The major patch
1228 level will be changed for any change to the meaning of the
1229 standards, however small; the minor patch level will be
1230 changed when only cosmetic, typographical or other edits
1231 are made which neither change the meaning of the document
1232 nor affect the contents of packages.</p>
1235 Thus only the first three components of the policy version
1236 are significant in the <em>Standards-Version</em> control
1237 field, and so either these three components or the all
1238 four components may be specified.<footnote>
1239 In the past, people specified the full version number
1240 in the Standards-Version field, for example "2.3.0.0".
1241 Since minor patch-level changes don't introduce new
1242 policy, it was thought it would be better to relax
1243 policy and only require the first 3 components to be
1244 specified, in this example "2.3.0". All four
1245 components may still be used if someone wishes to do
1251 You should regularly, and especially if your package has
1252 become out of date, check for the newest Policy Manual
1253 available and update your package, if necessary. When your
1254 package complies with the new standards you should update the
1255 <tt>Standards-Version</tt> source package field and
1256 release it.<footnote>
1257 See the file <file>upgrading-checklist</file> for
1258 information about policy which has changed between
1259 different versions of this document.
1265 <sect1 id="pkg-relations">
1266 <heading>Package relationships</heading>
1269 Source packages should specify which binary packages they
1270 require to be installed or not to be installed in order to
1271 build correctly. For example, if building a package
1272 requires a certain compiler, then the compiler should be
1273 specified as a build-time dependency.
1277 It is not necessary to explicitly specify build-time
1278 relationships on a minimal set of packages that are always
1279 needed to compile, link and put in a Debian package a
1280 standard "Hello World!" program written in C or C++. The
1281 required packages are called <em>build-essential</em>, and
1282 an informational list can be found in
1283 <file>/usr/share/doc/build-essential/list</file> (which is
1284 contained in the <tt>build-essential</tt>
1287 <list compact="compact">
1289 This allows maintaining the list separately
1290 from the policy documents (the list does not
1291 need the kind of control that the policy
1295 Having a separate package allows one to install
1296 the build-essential packages on a machine, as
1297 well as allowing other packages such as tasks to
1298 require installation of the build-essential
1299 packages using the depends relation.
1302 The separate package allows bug reports against
1303 the list to be categorized separately from
1304 the policy management process in the BTS.
1311 When specifying the set of build-time dependencies, one
1312 should list only those packages explicitly required by the
1313 build. It is not necessary to list packages which are
1314 required merely because some other package in the list of
1315 build-time dependencies depends on them.<footnote>
1316 The reason for this is that dependencies change, and
1317 you should list all those packages, and <em>only</em>
1318 those packages that <em>you</em> need directly. What
1319 others need is their business. For example, if you
1320 only link against <file>libimlib</file>, you will need to
1321 build-depend on <package>libimlib2-dev</package> but
1322 not against any <tt>libjpeg*</tt> packages, even
1323 though <tt>libimlib2-dev</tt> currently depends on
1324 them: installation of <package>libimlib2-dev</package>
1325 will automatically ensure that all of its run-time
1326 dependencies are satisfied.
1331 If build-time dependencies are specified, it must be
1332 possible to build the package and produce working binaries
1333 on a system with only essential and build-essential
1334 packages installed and also those required to satisfy the
1335 build-time relationships (including any implied
1336 relationships). In particular, this means that version
1337 clauses should be used rigorously in build-time
1338 relationships so that one cannot produce bad or
1339 inconsistently configured packages when the relationships
1340 are properly satisfied.
1344 <ref id="relationships"> explains the technical details.
1348 <heading>Changes to the upstream sources</heading>
1351 If changes to the source code are made that are not
1352 specific to the needs of the Debian system, they should be
1353 sent to the upstream authors in whatever form they prefer
1354 so as to be included in the upstream version of the
1358 If you need to configure the package differently for
1359 Debian or for Linux, and the upstream source doesn't
1360 provide a way to do so, you should add such configuration
1361 facilities (for example, a new <prgn>autoconf</prgn> test
1362 or <tt>#define</tt>) and send the patch to the upstream
1363 authors, with the default set to the way they originally
1364 had it. You can then easily override the default in your
1365 <file>debian/rules</file> or wherever is appropriate.</p>
1368 You should make sure that the <prgn>configure</prgn> utility
1369 detects the correct architecture specification string
1370 (refer to <ref id="arch-spec"> for details).</p>
1373 If you need to edit a <prgn>Makefile</prgn> where
1374 GNU-style <prgn>configure</prgn> scripts are used, you
1375 should edit the <file>.in</file> files rather than editing the
1376 <prgn>Makefile</prgn> directly. This allows the user to
1377 reconfigure the package if necessary. You should
1378 <em>not</em> configure the package and edit the generated
1379 <prgn>Makefile</prgn>! This makes it impossible for
1380 someone else to later reconfigure the package.</p>
1383 You should document your changes and updates to the source
1384 package properly in the <file>debian/changelog</file> file.
1385 For more information, please see <ref id="changelogs">.
1391 <heading>Error trapping in makefiles</heading>
1394 When <prgn>make</prgn> invokes a command in a makefile
1395 (including your package's upstream makefiles and
1396 <file>debian/rules</file>), it does so using <prgn>sh</prgn>. This
1397 means that <prgn>sh</prgn>'s usual bad error handling
1398 properties apply: if you include a miniature script as one
1399 of the commands in your makefile you'll find that if you
1400 don't do anything about it then errors are not detected
1401 and <prgn>make</prgn> will blithely continue after
1405 Every time you put more than one shell command (this
1406 includes using a loop) in a makefile command you
1407 must make sure that errors are trapped. For
1408 simple compound commands, such as changing directory and
1409 then running a program, using <tt>&&</tt> rather
1410 than semicolon as a command separator is sufficient. For
1411 more complex commands including most loops and
1412 conditionals you should include a separate <tt>set -e</tt>
1413 command at the start of every makefile command that's
1414 actually one of these miniature shell scripts.</p></sect1>
1418 <heading>Obsolete constructs and libraries</heading>
1421 The include file <tt><varargs.h></tt> is
1422 provided to support end-users compiling very old software;
1423 the library <tt>libtermcap</tt> is provided to support the
1424 execution of software which has been linked against it
1425 (either old programs or those such as Netscape which are
1426 only available in binary form).</p>
1429 Debian packages should be patched to use
1430 <tt><stdarg.h></tt> and <tt>ncurses</tt>
1437 <chapt id="controlfields"><heading>Control files and their fields</heading>
1440 Many of the tools in the package management suite manipulate
1441 data represented in a common format, known as <em>control
1442 data</em>. The data is often stored in <em>control
1443 files</em>. Binary and source packages have control files,
1444 and the <file>.changes</file> files which control the installation
1445 of uploaded files are also in control file format.
1446 <prgn>dpkg</prgn>'s internal databases are in a similar
1450 <sect id="controlsyntax"><heading>Syntax of control files</heading>
1453 A control file consists of one or more paragraphs of fields.
1454 The paragraphs are separated by blank lines. Some control
1455 files allow only one paragraph; others allow several, in
1456 which case each paragraph usually refers to a different
1457 package. (For example, in source packages, the first
1458 paragraph refers to the source package, and later paragraphs
1459 refer to binary packages generated from the source.)
1463 Each paragraph consists of a series of data fields; each
1464 field consists of the field name, followed by a colon and
1465 then the data/value associated with that field. It ends at
1466 the end of the line. Horizontal whitespace (spaces and
1467 tabs) may occur immediately before or after the value and is
1468 ignored there; it is conventional to put a single space
1469 after the colon. For example, a field might be:
1470 <example compact="compact">
1473 the field name is <tt>Package</tt> and the field value
1478 Some fields' values may span several lines; in this case
1479 each continuation line <em>must</em> start with a space or
1480 tab. Any trailing spaces or tabs at the end of individual
1481 lines of a field value are ignored.
1485 Except where otherwise stated only a single line of data is
1486 allowed and whitespace is not significant in a field body.
1487 Whitespace must not appear inside names (of packages,
1488 architectures, files or anything else) or version numbers,
1489 or between the characters of multi-character version
1494 Field names are not case-sensitive, but it is usual to
1495 capitalize the field names using mixed case as shown below.
1499 Blank lines, or lines consisting only of spaces and tabs,
1500 are not allowed within field values or between fields - that
1501 would mean a new paragraph.
1506 <sect><heading>List of fields</heading>
1508 This list here is not supposed to be exhaustive. Most fields
1509 are dealt with elsewhere in this document.
1511 <sect1 id="f-Package"><heading><tt>Package</tt>
1515 The name of the binary package. Package names consist of
1516 lower case letters (<tt>a-z</tt>), digits (<tt>0-9</tt>),
1517 plus (<tt>+</tt>) and minus (<tt>-</tt>) signs, and
1518 periods (<tt>.</tt>).
1522 They must be at least two characters long and must start
1523 with an alphanumeric character. The use of lowercase
1524 package names is required unless the package you're
1525 building (or referring to, in other fields) is already
1526 using uppercase characters.</p>
1529 <sect1 id="f-Version"><heading><tt>Version</tt>
1533 This lists the source or binary package's version number -
1534 see <ref id="versions">.
1540 id="f-Standards-Version"><heading><tt>Standards-Version</tt>
1544 The most recent version of the standards (the policy
1545 manual and associated texts) with which the package
1546 complies. This is updated manually when editing the
1547 source package to conform to newer standards; it can
1548 sometimes be used to tell when a package needs attention.
1549 Its format is described above; see
1550 <ref id="standardsversion">.
1555 <sect1 id="f-Distribution"><heading><tt>Distribution</tt>
1559 In a <file>.changes</file> file or parsed changelog output
1560 this contains the (space-separated) name(s) of the
1561 distribution(s) where this version of the package should
1562 be installed. Valid distributions are determined by the
1563 archive maintainers.<footnote>
1564 Current distribution names are:
1565 <taglist compact="compact">
1566 <tag><em>stable</em></tag>
1568 This is the current "released" version of Debian
1569 GNU/Linux. Once the distribution is
1570 <em>stable</em> only security fixes and other
1571 major bug fixes are allowed. When changes are
1572 made to this distribution, the release number is
1573 increased (for example: 2.2r1 becomes 2.2r2 then
1577 <tag><em>unstable</em></tag>
1579 This distribution value refers to the
1580 <em>developmental</em> part of the Debian
1581 distribution tree. New packages, new upstream
1582 versions of packages and bug fixes go into the
1583 <em>unstable</em> directory tree. Download from
1584 this distribution at your own risk.
1587 <tag><em>testing</em></tag>
1589 This distribution value refers to the
1590 <em>testing</em> part of the Debian distribution
1591 tree. It receives its packages from the
1592 unstable distribution after a short time lag to
1593 ensure that there are no major issues with the
1594 unstable packages. It is less prone to breakage
1595 than unstable, but still risky. It is not
1596 possible to upload packages directly to
1600 <tag><em>frozen</em></tag>
1602 From time to time, the <em>testing</em>
1603 distribution enters a state of "code-freeze" in
1604 anticipation of release as a <em>stable</em>
1605 version. During this period of testing only
1606 fixes for existing or newly-discovered bugs will
1607 be allowed. The exact details of this stage are
1608 determined by the Release Manager.
1611 <tag><em>experimental</em></tag>
1613 The packages with this distribution value are
1614 deemed by their maintainers to be high
1615 risk. Oftentimes they represent early beta or
1616 developmental packages from various sources that
1617 the maintainers want people to try, but are not
1618 ready to be a part of the other parts of the
1619 Debian distribution tree. Download at your own
1624 You should list <em>all</em> distributions that the
1625 package should be installed into.
1635 <chapt id="versions"><heading>Version numbering</heading>
1638 Every package has a version number recorded in its
1639 <tt>Version</tt> control file field.
1643 The package management system imposes an ordering on version
1644 numbers, so that it can tell whether packages are being up- or
1645 downgraded and so that package system front end applications
1646 can tell whether a package it finds available is newer than
1647 the one installed on the system. The version number format
1648 has the most significant parts (as far as comparison is
1649 concerned) at the beginning.
1653 The version number format is:
1654 [<var>epoch</var><tt>:</tt>]<var>upstream_version</var>[<tt>-</tt><var>debian_revision</var>]
1658 The three components here are:
1660 <tag><var>epoch</var></tag>
1663 This is a single (generally small) unsigned integer. It
1664 may be omitted, in which case zero is assumed. If it is
1665 omitted then the <var>upstream_version</var> may not
1670 It is provided to allow mistakes in the version numbers
1671 of older versions of a package, and also a package's
1672 previous version numbering schemes, to be left behind.
1676 <tag><var>upstream_version</var></tag>
1679 This is the main part of the version number. It is
1680 usually the version number of the original ("upstream")
1681 package from which the <file>.deb</file> file has been made,
1682 if this is applicable. Usually this will be in the same
1683 format as that specified by the upstream author(s);
1684 however, it may need to be reformatted to fit into the
1685 package management system's format and comparison
1690 The comparison behavior of the package management system
1691 with respect to the <var>upstream_version</var> is
1692 described below. The <var>upstream_version</var>
1693 portion of the version number is mandatory.
1697 The <var>upstream_version</var> may contain only
1698 alphanumerics<footnote>
1699 Alphanumerics are <tt>A-Za-z0-9</tt> only.
1701 and the characters <tt>.</tt> <tt>+</tt> <tt>-</tt>
1702 <tt>:</tt> (full stop, plus, hyphen, colon) and should
1703 start with a digit. If there is no
1704 <var>debian_revision</var> then hyphens are not allowed;
1705 if there is no <var>epoch</var> then colons are not
1709 <tag><var>debian_revision</var></tag>
1712 This part of the version number specifies the version of
1713 the Debian package based on the upstream version. It
1714 may contain only alphanumerics and the characters
1715 <tt>+</tt> and <tt>.</tt> (plus and full stop) and is
1716 compared in the same way as the
1717 <var>upstream_version</var> is.
1721 It is optional; if it isn't present then the
1722 <var>upstream_version</var> may not contain a hyphen.
1723 This format represents the case where a piece of
1724 software was written specifically to be turned into a
1725 Debian package, and so there is only one "debianization"
1726 of it and therefore no revision indication is required.
1730 It is conventional to restart the
1731 <var>debian_revision</var> at <tt>1</tt> each time the
1732 <var>upstream_version</var> is increased.
1736 The package management system will break the version
1737 number apart at the last hyphen in the string (if there
1738 is one) to determine the <var>upstream_version</var> and
1739 <var>debian_revision</var>. The absence of a
1740 <var>debian_revision</var> compares earlier than the
1741 presence of one (but note that the
1742 <var>debian_revision</var> is the least significant part
1743 of the version number).
1750 The <var>upstream_version</var> and <var>debian_revision</var>
1751 parts are compared by the package management system using the
1756 The strings are compared from left to right.
1760 First the initial part of each string consisting entirely of
1761 non-digit characters is determined. These two parts (one of
1762 which may be empty) are compared lexically. If a difference
1763 is found it is returned. The lexical comparison is a
1764 comparison of ASCII values modified so that all the letters
1765 sort earlier than all the non-letters.
1769 Then the initial part of the remainder of each string which
1770 consists entirely of digit characters is determined. The
1771 numerical values of these two parts are compared, and any
1772 difference found is returned as the result of the comparison.
1773 For these purposes an empty string (which can only occur at
1774 the end of one or both version strings being compared) counts
1779 These two steps (comparing and removing initial non-digit
1780 strings and initial digit strings) are repeated until a
1781 difference is found or both strings are exhausted.
1785 Note that the purpose of epochs is to allow us to leave behind
1786 mistakes in version numbering, and to cope with situations
1787 where the version numbering scheme changes. It is
1788 <em>not</em> intended to cope with version numbers containing
1789 strings of letters which the package management system cannot
1790 interpret (such as <tt>ALPHA</tt> or <tt>pre-</tt>), or with
1791 silly orderings (the author of this manual has heard of a
1792 package whose versions went <tt>1.1</tt>, <tt>1.2</tt>,
1793 <tt>1.3</tt>, <tt>1</tt>, <tt>2.1</tt>, <tt>2.2</tt>,
1794 <tt>2</tt> and so forth).
1798 If an upstream package has problematic version numbers they
1799 should be converted to a sane form for use in the
1800 <tt>Version</tt> field.
1804 <heading>Version numbers based on dates</heading>
1806 In general, Debian packages should use the same version
1807 numbers as the upstream sources.</p>
1810 However, in some cases where the upstream version number is
1811 based on a date (e.g., a development "snapshot" release) the
1812 package management system cannot handle these version
1813 numbers without epochs. For example, dpkg will consider
1814 "96May01" to be greater than "96Dec24".</p>
1817 To prevent having to use epochs for every new upstream
1818 version, the version number should be changed to the
1819 following format in such cases: "19960501", "19961224". It
1820 is up to the maintainer whether he/she wants to bother the
1821 upstream maintainer to change the version numbers upstream,
1825 Note that other version formats based on dates which are
1826 parsed correctly by the package management system should
1827 <em>not</em> be changed.</p>
1830 Native Debian packages (i.e., packages which have been
1831 written especially for Debian) whose version numbers include
1832 dates should always use the "YYYYMMDD" format.</p>
1836 <chapt id="miscellaneous"><heading>Packaging Considerations</heading>
1838 <sect id="timestamps"><heading>Time Stamps</heading>
1840 Maintainers should preserve the modification times of the
1841 upstream source files in a package, as far as is reasonably
1843 The rationale is that there is some information conveyed
1844 by knowing the age of the file, for example, you could
1845 recognize that some documentation is very old by looking
1846 at the modification time, so it would be nice if the
1847 modification time of the upstream source would be
1853 <sect id="debianrules"><heading><file>debian/rules</file> - the
1854 main building script</heading>
1857 This file must be an executable makefile, and contains the
1858 package-specific recipes for compiling the package and
1859 building binary package(s) from the source.
1863 It must start with the line <tt>#!/usr/bin/make -f</tt>,
1864 so that it can be invoked by saying its name rather than
1865 invoking <prgn>make</prgn> explicitly.
1869 Since an interactive <file>debian/rules</file> script makes it
1870 impossible to auto-compile that package and also makes it
1871 hard for other people to reproduce the same binary
1872 package, all <em>required targets</em> MUST be
1873 non-interactive. At a minimum, required targets are the
1874 ones called by <prgn>dpkg-buildpackage</prgn>, namely,
1875 <em>clean</em>, <em>binary</em>, <em>binary-arch</em>,
1876 <em>binary-indep</em>, and <em>build</em>. It also follows
1877 that any target that these targets depend on must also be
1882 The required and optional targets are as follows:
1884 <tag><tt>build</tt>, <tt>build-arch</tt> (optional),
1885 <tt>build-indep</tt> (optional)</tag>
1888 The <tt>build</tt> target should perform all
1889 non-interactive configuration and compilation of the
1890 package. If a package has an interactive pre-build
1891 configuration routine, the Debianized source package
1892 must either be built after this has taken place (so
1893 that the binary package can be built without rerunning
1894 the configuration) or the configuration routine
1895 modified to become non-interactive. (The latter is
1896 preferable if there are architecture-specific features
1897 detected by the configuration routine.)
1901 For some packages, notably ones where the same
1902 source tree is compiled in different ways to produce
1903 two binary packages, the <tt>build</tt> target
1904 does not make much sense. For these packages it is
1905 good enough to provide two (or more) targets
1906 (<tt>build-a</tt> and <tt>build-b</tt> or whatever)
1907 for each of the ways of building the package, and a
1908 <tt>build</tt> target that does nothing. The
1909 <tt>binary</tt> target will have to build the
1910 package in each of the possible ways and make the
1911 binary package out of each.
1915 The <tt>build</tt> target must not do anything
1916 that might require root privilege.
1920 The <tt>build</tt> target may need to run the
1921 <tt>clean</tt> target first - see below.
1925 When a package has a configuration and build routine
1926 which takes a long time, or when the makefiles are
1927 poorly designed, or when <tt>build</tt> needs to
1928 run <tt>clean</tt> first, it is a good idea to
1929 <tt>touch build</tt> when the build process is
1930 complete. This will ensure that if <tt>debian/rules
1931 build</tt> is run again it will not rebuild the whole
1933 Another common way to do this is for <tt>build</tt>
1934 to depend on <prgn>build-stamp</prgn> and to do
1935 nothing else, and for the <prgn>build-stamp</prgn>
1936 target to do the building and to <tt>touch
1937 build-stamp</tt> on completion. This is
1938 especially useful if the build routine creates a
1939 file or directory called <tt>build</tt>; in such a
1940 case, <tt>build</tt> will need to be listed as
1941 a phony target (i.e., as a dependency of the
1942 <tt>.PHONY</tt> target). See the documentation of
1943 <prgn>make</prgn> for more information on phony
1949 <tag><tt>binary</tt>, <tt>binary-arch</tt>,
1950 <tt>binary-indep</tt>
1954 The <tt>binary</tt> target must be all that is
1955 necessary for the user to build the binary package(s)
1956 produced from this source package. All of these
1957 targets are required to be non-interactive. It is
1958 split into two parts: <prgn>binary-arch</prgn> builds
1959 the binary packages which are specific to a particular
1960 architecture, and <tt>binary-indep</tt> builds
1961 those which are not.
1964 <tt>binary</tt> may be (and commonly is) a target with
1965 no commands which simply depends on
1966 <tt>binary-arch</tt> and <tt>binary-indep</tt>.
1969 Both <tt>binary-*</tt> targets should depend on the
1970 <tt>build</tt> target, or on the appropriate
1971 <tt>build-arch</tt> or <tt>build-indep</tt> target, if
1972 provided, so that the package is built if it has not
1973 been already. It should then create the relevant
1974 binary package(s), using <prgn>dpkg-gencontrol</prgn> to
1975 make their control files and <prgn>dpkg-deb</prgn> to
1976 build them and place them in the parent of the top
1981 Both the <tt>binary-arch</tt> and
1982 <tt>binary-indep</tt> targets <em>must</em> exist.
1983 If one of them has nothing to do (which will always be
1984 the case if the source generates only a single binary
1985 package, whether architecture-dependent or not), it
1986 must still exist and must always succeed.
1990 The <tt>binary</tt> targets must be invoked as
1992 The <prgn>fakeroot</prgn> package often allows one
1993 to build a package correctly even without being
1999 <tag><tt>clean</tt></tag>
2002 This must undo any effects that the <tt>build</tt>
2003 and <tt>binary</tt> targets may have had, except
2004 that it should leave alone any output files created in
2005 the parent directory by a run of a <tt>binary</tt>
2006 target. This target must be non-interactive.
2010 If a <tt>build</tt> file is touched at the end of
2011 the <tt>build</tt> target, as suggested above, it
2012 should be removed as the first action that
2013 <tt>clean</tt> performs, so that running
2014 <tt>build</tt> again after an interrupted
2015 <tt>clean</tt> doesn't think that everything is
2020 The <tt>clean</tt> target may need to be
2021 invoked as root if <tt>binary</tt> has been
2022 invoked since the last <tt>clean</tt>, or if
2023 <tt>build</tt> has been invoked as root (since
2024 <tt>build</tt> may create directories, for
2029 <tag><tt>get-orig-source</tt> (optional)</tag>
2032 This target fetches the most recent version of the
2033 original source package from a canonical archive site
2034 (via FTP or WWW, for example), does any necessary
2035 rearrangement to turn it into the original source
2036 tar file format described below, and leaves it in the
2041 This target may be invoked in any directory, and
2042 should take care to clean up any temporary files it
2047 This target is optional, but providing it if
2048 possible is a good idea.
2054 The <tt>build</tt>, <tt>binary</tt> and
2055 <tt>clean</tt> targets must be invoked with the current
2056 directory being the package's top-level directory.
2061 Additional targets may exist in <file>debian/rules</file>,
2062 either as published or undocumented interfaces or for the
2063 package's internal use.
2067 The architectures we build on and build for are determined
2068 by <prgn>make</prgn> variables using the utility
2069 <qref id="pkg-dpkgarch"><prgn>dpkg-architecture</prgn></qref>.
2070 You can determine the
2071 Debian architecture and the GNU style architecture
2072 specification string for the build machine (the machine type
2073 we are building on) as well as for the host machine (the
2074 machine type we are building for). Here is a list of
2075 supported <prgn>make</prgn> variables:
2076 <list compact="compact">
2078 <tt>DEB_*_ARCH</tt> (the Debian architecture)
2081 <tt>DEB_*_GNU_TYPE</tt> (the GNU style architecture
2082 specification string)
2085 <tt>DEB_*_GNU_CPU</tt> (the CPU part of
2086 <tt>DEB_*_GNU_TYPE</tt>)
2089 <tt>DEB_*_GNU_SYSTEM</tt> (the System part of
2090 <tt>DEB_*_GNU_TYPE</tt>)
2092 where <tt>*</tt> is either <tt>BUILD</tt> for specification of
2093 the build machine or <tt>HOST</tt> for specification of the
2098 Backward compatibility can be provided in the rules file
2099 by setting the needed variables to suitable default
2100 values; please refer to the documentation of
2101 <prgn>dpkg-architecture</prgn> for details.
2105 It is important to understand that the <tt>DEB_*_ARCH</tt>
2106 string only determines which Debian architecture we are
2107 building on or for. It should not be used to get the CPU
2108 or system information; the GNU style variables should be
2113 <sect id="dpkgchangelog"><heading><file>debian/changelog</file>
2117 This file records the changes to the Debian-specific parts of the
2119 Though there is nothing stopping an author who is also
2120 the Debian maintainer from using it for all their
2121 changes, it will have to be renamed if the Debian and
2122 upstream maintainers become different people. In such a
2123 case, however, it might be better to maintain the
2124 package as a non-native package.
2129 It has a special format which allows the package building
2130 tools to discover which version of the package is being
2131 built and find out other release-specific information.
2135 That format is a series of entries like this:
2136 <example compact="compact">
2137 <var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
2139 <p>[optional blank line(s), stripped]</p>
2141 * <var>change details</var>
2142 <var>more change details</var>
2144 <p>[blank line(s), included in output of dpkg-parsechangelog]</p>
2146 * <var>even more change details</var>
2148 <p>[optional blank line(s), stripped]</p>
2150 -- <var>maintainer name</var> <<var>email
2151 address</var>><var>[two spaces]</var> <var>date</var>
2156 <var>package</var> and <var>version</var> are the source
2157 package name and version number.
2161 <var>distribution(s)</var> lists the distributions where
2162 this version should be installed when it is uploaded - it
2163 is copied to the <tt>Distribution</tt> field in the
2164 <file>.changes</file> file. See <ref id="f-Distribution">.
2168 <var>urgency</var> is the value for the <tt>Urgency</tt>
2169 field in the <file>.changes</file> file for the upload. It is
2170 not possible to specify an urgency containing commas; commas
2171 are used to separate
2172 <tt><var>keyword</var>=<var>value</var></tt> settings in the
2173 <prgn>dpkg</prgn> changelog format (though there is
2174 currently only one useful <var>keyword</var>,
2175 <tt>urgency</tt>).<footnote>
2176 Recognised urgency values are <tt>low</tt>,
2177 <tt>medium</tt>, <tt>high</tt> and <tt>emergency</tt>.
2178 They have an effect on how quickly a package will be
2179 considered for inclusion into the <tt>testing</tt>
2180 distribution, and give an indication of the importance
2181 of any fixes included in this upload.
2186 The change details may in fact be any series of lines
2187 starting with at least two spaces, but conventionally each
2188 change starts with an asterisk and a separating space and
2189 continuation lines are indented so as to bring them in
2190 line with the start of the text above. Blank lines may be
2191 used here to separate groups of changes, if desired.
2195 If this upload resolves bugs recorded in the Bug Tracking
2196 System (BTS), they may be automatically closed on the
2197 inclusion of this package into the Debian archive by
2198 including the string: <tt>closes: Bug#<var>nnnnn</var></tt>
2199 in the change details.<footnote>
2200 To be precise, the string should match the following
2201 Perl regular expression:
2203 /closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i
2205 Then all of the bug numbers listed will be closed by the
2206 archive maintenance script (<prgn>katie</prgn>), or in
2207 the case of an NMU, marked as fixed.
2212 The maintainer name and email address used in the changelog
2213 should be the details of the person uploading <em>this</em>
2214 version. They are <em>not</em> necessarily those of the
2215 usual package maintainer. The information here will be
2216 copied to the <tt>Changed-By</tt> field in the
2217 <tt>.changes</tt> file, and then later used to send an
2218 acknowledgement when the upload has been installed.
2222 The <var>date</var> should be in RFC822 format<footnote>
2223 This is generated by the <prgn>822-date</prgn>
2225 </footnote>; it should include the time zone specified
2226 numerically, with the time zone name or abbreviation
2227 optionally present as a comment in parentheses.
2231 The first "title" line with the package name should start
2232 at the left hand margin; the "trailer" line with the
2233 maintainer and date details should be preceded by exactly
2234 one space. The maintainer details and the date must be
2235 separated by exactly two spaces.
2238 <sect1><heading>Defining alternative changelog formats</heading>
2241 It is possible to use a different format to the standard
2242 one, by providing a parser for the format you wish to
2246 A changelog parser must not interact with the user at
2252 <!-- FIXME: section pkg-srcsubstvars is the same as srcsubstvars -->
2254 <sect id="srcsubstvars"><heading><file>debian/substvars</file>
2255 and variable substitutions </heading>
2258 When <prgn>dpkg-gencontrol</prgn>,
2259 <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
2260 generate control files they perform variable substitutions
2261 on their output just before writing it. Variable
2262 substitutions have the form <tt>${<var>variable</var>}</tt>.
2263 The optional file <file>debian/substvars</file> contains
2264 variable substitutions to be used; variables can also be set
2265 directly from <file>debian/rules</file> using the <tt>-V</tt>
2266 option to the source packaging commands, and certain
2267 predefined variables are also available.
2271 The <file>debian/substvars</file> file is usually generated and
2272 modified dynamically by <file>debian/rules</file> targets, in
2273 which case it must be removed by the <tt>clean</tt> target.
2277 See <manref name="dpkg-source" section="1"> for full
2278 details about source variable substitutions, including the
2279 format of <file>debian/substvars</file>.</p>
2282 <sect id="debianfiles"><heading><file>debian/files</file>
2286 This file is not a permanent part of the source tree; it
2287 is used while building packages to record which files are
2288 being generated. <prgn>dpkg-genchanges</prgn> uses it
2289 when it generates a <file>.changes</file> file.
2293 It should not exist in a shipped source package, and so it
2294 (and any backup files or temporary files such as
2295 <file>files.new</file><footnote>
2296 <file>files.new</file> is used as a temporary file by
2297 <prgn>dpkg-gencontrol</prgn> and
2298 <prgn>dpkg-distaddfile</prgn> - they write a new
2299 version of <tt>files</tt> here before renaming it,
2300 to avoid leaving a corrupted copy if an error
2302 </footnote>) should be removed by the
2303 <tt>clean</tt> target. It may also be wise to
2304 ensure a fresh start by emptying or removing it at the
2305 start of the <tt>binary</tt> target.
2309 When <prgn>dpkg-gencontrol</prgn> is run for a binary
2310 package, it adds an entry to <file>debian/files</file> for the
2311 <file>.deb</file> file that will be created when <tt>dpkg-deb
2312 --build</tt> is run for that binary package. So for most
2313 packages all that needs to be done with this file is to
2314 delete it in the <tt>clean</tt> target.
2318 If a package upload includes files besides the source
2319 package and any binary packages whose control files were
2320 made with <prgn>dpkg-gencontrol</prgn> then they should be
2321 placed in the parent of the package's top-level directory
2322 and <prgn>dpkg-distaddfile</prgn> should be called to add
2323 the file to the list in <file>debian/files</file>.</p>
2326 <sect id="restrictions"><heading>Restrictions on objects in source packages
2330 The source package may not contain any hard links<footnote>
2332 This is not currently detected when building source
2333 packages, but only when extracting
2337 Hard links may be permitted at some point in the
2338 future, but would require a fair amount of
2341 </footnote>, device special files, sockets or setuid or
2342 setgid files.<footnote>
2343 Setgid directories are allowed.
2348 <sect id="descriptions"><heading>Descriptions of packages - the
2349 <tt>Description</tt> field</heading>
2352 The "Description" control file field consists of two parts,
2353 the synopsis or the short description, and the long description.
2354 The field's format is as follows:
2358 Description: <single line synopsis>
2359 <extended description over several lines>
2363 The description is intended to describe the program to a user
2364 who has never met it before so that they know whether they
2365 want to install it. It should also give information about the
2366 significant dependencies and conflicts between this package
2367 and others, so that the user knows why these dependencies and
2368 conflicts have been declared.
2372 Put important information first, both in the synopsis and
2373 extended description. Sometimes only the first part of the
2374 synopsis or of the description will be displayed. You can
2375 assume that there will usually be a way to see the whole
2376 extended description.
2379 <sect1 id="synopsis"><heading>The single line synopsis</heading>
2382 The single line synopsis should be kept brief - certainly
2383 under 80 characters.
2387 Do not include the package name in the synopsis line. The
2388 display software knows how to display this already, and you
2389 do not need to state it. Remember that in many situations
2390 the user may only see the synopsis line - make it as
2391 informative as you can.
2396 <sect1 id="extendeddesc"><heading>The extended description</heading>
2399 Do not try to continue the single line synopsis into the
2400 extended description. This will not work correctly when
2401 the full description is displayed, and makes no sense
2402 where only the summary (the single line synopsis) is
2407 The extended description should describe what the package
2408 does and how it relates to the rest of the system (in terms
2409 of, for example, which subsystem it is which part of).
2413 The description field needs to make sense to anyone, even
2414 people who have no idea about any of the things the
2415 package deals with.<footnote>
2416 The blurb that comes with a program in its
2417 announcements and/or <prgn>README</prgn> files is
2418 rarely suitable for use in a description. It is
2419 usually aimed at people who are already in the
2420 community where the package is used.
2425 The lines in the extended description can have these formats:
2431 Those starting with a single space are part of a paragraph.
2432 Successive lines of this form will be word-wrapped when
2433 displayed. The leading space will usually be stripped off.
2437 Those starting with two or more spaces. These will be
2438 displayed verbatim. If the display cannot be panned
2439 horizontally, the displaying program will linewrap them "hard"
2440 (i.e., without taking account of word breaks). If it can they
2441 will be allowed to trail off to the right. None, one or two
2442 initial spaces may be deleted, but the number of spaces
2443 deleted from each line will be the same (so that you can have
2444 indenting work correctly, for example).
2448 Those containing a single space followed by a single full stop
2449 character. These are rendered as blank lines. This is the
2450 <em>only</em> way to get a blank line<footnote>
2451 Completely empty lines will not be rendered as blank lines.
2452 Instead, they will cause the parser to think you're starting
2453 a whole new record in the control file, and will therefore
2454 likely abort with an error.
2459 Those containing a space, a full stop and some more characters.
2460 These are for future expansion. Do not use them.
2466 Do not use tab characters. Their effect is not predictable.
2476 <chapt id="maintainerscripts"><heading>Package maintainer scripts
2477 and installation procedure
2480 <sect><heading>Introduction to package maintainer scripts
2484 It is possible to supply scripts as part of a package which
2485 the package management system will run for you when your
2486 package is installed, upgraded or removed.
2490 These scripts are the files <prgn>preinst</prgn>,
2491 <prgn>postinst</prgn>, <prgn>prerm</prgn> and <prgn>postrm</prgn> in the
2492 control area of the package. They must be proper executable
2493 files; if they are scripts (which is recommended), they must
2494 start with the usual <tt>#!</tt> convention. They should be
2495 readable and executable by anyone, and not world-writable.
2499 The package management system looks at the exit status from
2500 these scripts. It is important that they exit with a
2501 non-zero status if there is an error, so that the package
2502 management system can stop its processing. For shell
2503 scripts this means that you <em>almost always</em> need to
2504 use <tt>set -e</tt> (this is usually true when writing shell
2505 scripts, in fact). It is also important, of course, that
2506 they don't exit with a non-zero status if everything went
2511 When a package is upgraded a combination of the scripts from
2512 the old and new packages is called during the upgrade
2513 procedure. If your scripts are going to be at all
2514 complicated you need to be aware of this, and may need to
2515 check the arguments to your scripts.
2519 Broadly speaking the <prgn>preinst</prgn> is called before
2520 (a particular version of) a package is installed, and the
2521 <prgn>postinst</prgn> afterwards; the <prgn>prerm</prgn>
2522 before (a version of) a package is removed and the
2523 <prgn>postrm</prgn> afterwards.
2527 Programs called from maintainer scripts should not normally
2528 have a path prepended to them. Before installation is
2529 started, the package management system checks to see if the
2530 programs <prgn>ldconfig</prgn>,
2531 <prgn>start-stop-daemon</prgn>, <prgn>install-info</prgn>,
2532 and <prgn>update-rc.d</prgn> can be found via the
2533 <tt>PATH</tt> environment variable. Those programs, and any
2534 other program that one would expect to be on the
2535 <tt>PATH</tt>, should thus be invoked without an absolute
2536 pathname. Maintainer scripts should also not reset the
2537 <tt>PATH</tt>, though they might choose to modify it by
2538 prepending or appending package-specific directories. These
2539 considerations really apply to all shell scripts.</p>
2543 <heading>Maintainer scripts Idempotency</heading>
2546 It is necessary for the error recovery procedures that the
2547 scripts be idempotent. This means that if it is run
2548 successfully, and then it is called again, it doesn't bomb
2549 out or cause any harm, but just ensures that everything is
2550 the way it ought to be. If the first call failed, or
2551 aborted half way through for some reason, the second call
2552 should merely do the things that were left undone the first
2553 time, if any, and exit with a success status if everything
2555 This is so that if an error occurs, the user interrupts
2556 <prgn>dpkg</prgn> or some other unforeseen circumstance
2557 happens you don't leave the user with a badly-broken
2558 package when <prgn>dpkg</prgn> attempts to repeat the
2565 <heading>Controlling terminal for maintainer scripts</heading>
2568 The maintainer scripts are guaranteed to run with a
2569 controlling terminal and can interact with the user.
2570 If they need to prompt for passwords, do full-screen
2571 interaction or something similar you should do these
2572 things to and from <file>/dev/tty</file>, since
2573 <prgn>dpkg</prgn> will at some point redirect scripts'
2574 standard input and output so that it can log the
2575 installation process. Likewise, because these scripts
2576 may be executed with standard output redirected into a
2577 pipe for logging purposes, Perl scripts should set
2578 unbuffered output by setting <tt>$|=1</tt> so that the
2579 output is printed immediately rather than being
2584 Each script should return a zero exit status for
2585 success, or a nonzero one for failure.
2589 <sect id="mscriptsinstact"><heading>Summary of ways maintainer
2594 <list compact="compact">
2596 <var>new-preinst</var> <tt>install</tt>
2599 <var>new-preinst</var> <tt>install</tt> <var>old-version</var>
2602 <var>new-preinst</var> <tt>upgrade</tt> <var>old-version</var>
2605 <var>old-preinst</var> <tt>abort-upgrade</tt>
2606 <var>new-version</var>
2611 <list compact="compact">
2613 <var>postinst</var> <tt>configure</tt>
2614 <var>most-recently-configured-version</var>
2617 <var>old-postinst</var> <tt>abort-upgrade</tt>
2618 <var>new-version</var>
2621 <var>conflictor's-postinst</var> <tt>abort-remove</tt>
2622 <tt>in-favour</tt> <var>package</var>
2623 <var>new-version</var>
2626 <var>deconfigured's-postinst</var>
2627 <tt>abort-deconfigure</tt> <tt>in-favour</tt>
2628 <var>failed-install-package</var> <var>version</var>
2629 <tt>removing</tt> <var>conflicting-package</var>
2635 <list compact="compact">
2637 <var>prerm</var> <tt>remove</tt>
2640 <var>old-prerm</var> <tt>upgrade</tt>
2641 <var>new-version</var>
2644 <var>new-prerm</var> <tt>failed-upgrade</tt>
2645 <var>old-version</var>
2648 <var>conflictor's-prerm</var> <tt>remove</tt>
2649 <tt>in-favour</tt> <var>package</var>
2650 <var>new-version</var>
2653 <var>deconfigured's-prerm</var> <tt>deconfigure</tt>
2654 <tt>in-favour</tt> <var>package-being-installed</var>
2655 <var>version</var> <tt>removing</tt>
2656 <var>conflicting-package</var>
2662 <list compact="compact">
2664 <var>postrm</var> <tt>remove</tt>
2667 <var>postrm</var> <tt>purge</tt>
2670 <var>old-postrm</var> <tt>upgrade</tt>
2671 <var>new-version</var>
2674 <var>new-postrm</var> <tt>failed-upgrade</tt>
2675 <var>old-version</var>
2678 <var>new-postrm</var> <tt>abort-install</tt>
2681 <var>new-postrm</var> <tt>abort-install</tt>
2682 <var>old-version</var>
2685 <var>new-postrm</var> <tt>abort-upgrade</tt>
2686 <var>old-version</var>
2689 <var>disappearer's-postrm</var> <tt>disappear</tt>
2690 <var>overwriter</var>
2691 <var>overwriter-version</var>
2697 <sect id="unpackphase">
2698 <heading>Details of unpack phase of installation or upgrade</heading>
2701 The procedure on installation/upgrade/overwrite/disappear
2702 (i.e., when running <tt>dpkg --unpack</tt>, or the unpack
2703 stage of <tt>dpkg --install</tt>) is as follows. In each
2704 case, if a major error occurs (unless listed below) the
2705 actions are, in general, run backwards - this means that the
2706 maintainer scripts are run with different arguments in
2707 reverse order. These are the "error unwind" calls listed
2714 If a version of the package is already installed, call
2715 <example compact="compact">
2716 <var>old-prerm</var> upgrade <var>new-version</var>
2720 If the script runs but exits with a non-zero
2721 exit status, <prgn>dpkg</prgn> will attempt:
2722 <example compact="compact">
2723 <var>new-prerm</var> failed-upgrade <var>old-version</var>
2725 Error unwind, for both the above cases:
2726 <example compact="compact">
2727 <var>old-postinst</var> abort-upgrade <var>new-version</var>
2734 If a "conflicting" package is being removed at the same time:
2737 If any packages depended on that conflicting
2738 package and <tt>--auto-deconfigure</tt> is
2739 specified, call, for each such package:
2740 <example compact="compact">
2741 <var>deconfigured's-prerm</var> deconfigure \
2742 in-favour <var>package-being-installed</var> <var>version</var> \
2743 removing <var>conflicting-package</var> <var>version</var>
2746 <example compact="compact">
2747 <var>deconfigured's-postinst</var> abort-deconfigure \
2748 in-favour <var>package-being-installed-but-failed</var> <var>version</var> \
2749 removing <var>conflicting-package</var> <var>version</var>
2751 The deconfigured packages are marked as
2752 requiring configuration, so that if
2753 <tt>--install</tt> is used they will be
2754 configured again if possible.
2757 To prepare for removal of the conflicting package, call:
2758 <example compact="compact">
2759 <var>conflictor's-prerm</var> remove \
2760 in-favour <var>package</var> <var>new-version</var>
2763 <example compact="compact">
2764 <var>conflictor's-postinst</var> abort-remove \
2765 in-favour <var>package</var> <var>new-version</var>
2774 If the package is being upgraded, call:
2775 <example compact="compact">
2776 <var>new-preinst</var> upgrade <var>old-version</var>
2780 Otherwise, if the package had some configuration
2781 files from a previous version installed (i.e., it
2782 is in the "configuration files only" state):
2783 <example compact="compact">
2784 <var>new-preinst</var> install <var>old-version</var>
2788 Otherwise (i.e., the package was completely purged):
2789 <example compact="compact">
2790 <var>new-preinst</var> install
2792 Error unwind actions, respectively:
2793 <example compact="compact">
2794 <var>new-postrm</var> abort-upgrade <var>old-version</var>
2795 <var>new-postrm</var> abort-install <var>old-version</var>
2796 <var>new-postrm</var> abort-install
2804 The new package's files are unpacked, overwriting any
2805 that may be on the system already, for example any
2806 from the old version of the same package or from
2807 another package. Backups of the old files are kept
2808 temporarily, and if anything goes wrong the package
2809 management system will attempt to put them back as
2810 part of the error unwind.
2814 It is an error for a package to contains files which
2815 are on the system in another package, unless
2816 <tt>Replaces</tt> is used (see <ref id="replaces">).
2818 The following paragraph is not currently the case:
2819 Currently the <tt>- - force-overwrite</tt> flag is
2820 enabled, downgrading it to a warning, but this may not
2826 It is a more serious error for a package to contain a
2827 plain file or other kind of non-directory where another
2828 package has a directory (again, unless
2829 <tt>Replaces</tt> is used). This error can be
2830 overridden if desired using
2831 <tt>--force-overwrite-dir</tt>, but this is not
2836 Packages which overwrite each other's files produce
2837 behavior which, though deterministic, is hard for the
2838 system administrator to understand. It can easily
2839 lead to "missing" programs if, for example, a package
2840 is installed which overwrites a file from another
2841 package, and is then removed again.<footnote>
2842 Part of the problem is due to what is arguably a
2843 bug in <prgn>dpkg</prgn>.
2848 A directory will never be replaced by a symbolic link
2849 to a directory or vice versa; instead, the existing
2850 state (symlink or not) will be left alone and
2851 <prgn>dpkg</prgn> will follow the symlink if there is
2860 If the package is being upgraded, call
2861 <example compact="compact">
2862 <var>old-postrm</var> upgrade <var>new-version</var>
2866 If this fails, <prgn>dpkg</prgn> will attempt:
2867 <example compact="compact">
2868 <var>new-postrm</var> failed-upgrade <var>old-version</var>
2870 Error unwind, for both cases:
2871 <example compact="compact">
2872 <var>old-preinst</var> abort-upgrade <var>new-version</var>
2879 This is the point of no return - if
2880 <prgn>dpkg</prgn> gets this far, it won't back off
2881 past this point if an error occurs. This will
2882 leave the package in a fairly bad state, which
2883 will require a successful re-installation to clear
2884 up, but it's when <prgn>dpkg</prgn> starts doing
2885 things that are irreversible.
2890 Any files which were in the old version of the package
2891 but not in the new are removed.
2895 The new file list replaces the old.
2899 The new maintainer scripts replace the old.
2903 Any packages all of whose files have been overwritten
2904 during the installation, and which aren't required for
2905 dependencies, are considered to have been removed.
2906 For each such package
2909 <prgn>dpkg</prgn> calls:
2910 <example compact="compact">
2911 <var>disappearer's-postrm</var> disappear \
2912 <var>overwriter</var> <var>overwriter-version</var>
2916 The package's maintainer scripts are removed.
2919 It is noted in the status database as being in a
2920 sane state, namely not installed (any conffiles
2921 it may have are ignored, rather than being
2922 removed by <prgn>dpkg</prgn>). Note that
2923 disappearing packages do not have their prerm
2924 called, because <prgn>dpkg</prgn> doesn't know
2925 in advance that the package is going to
2932 Any files in the package we're unpacking that are also
2933 listed in the file lists of other packages are removed
2934 from those lists. (This will lobotomize the file list
2935 of the "conflicting" package if there is one.)
2939 The backup files made during installation, above, are
2945 The new package's status is now sane, and recorded as
2950 Here is another point of no return - if the
2951 conflicting package's removal fails we do not unwind
2952 the rest of the installation; the conflicting package
2953 is left in a half-removed limbo.
2958 If there was a conflicting package we go and do the
2959 removal actions (described below), starting with the
2960 removal of the conflicting package's files (any that
2961 are also in the package being installed have already
2962 been removed from the conflicting package's file list,
2963 and so do not get removed now).
2969 <sect id="configdetails"><heading>Details of configuration</heading>
2972 When we configure a package (this happens with <tt>dpkg
2973 --install</tt> and <tt>dpkg --configure</tt>), we first
2974 update any <tt>conffile</tt>s and then call:
2975 <example compact="compact">
2976 <var>postinst</var> configure <var>most-recently-configured-version</var>
2981 No attempt is made to unwind after errors during
2986 If there is no most recently configured version
2987 <prgn>dpkg</prgn> will pass a null argument; older versions
2988 of dpkg may pass <tt><unknown></tt> (including the
2989 angle brackets) in this case. Even older ones do not pass a
2990 second argument at all, under any circumstances.
2994 <sect id="removedetails"><heading>Details of removal and/or
2995 configuration purging</heading>
3000 <example compact="compact">
3001 <var>prerm</var> remove
3005 The package's files are removed (except <tt>conffile</tt>s).
3008 <example compact="compact">
3009 <var>postrm</var> remove
3014 All the maintainer scripts except the <prgn>postrm</prgn>
3019 If we aren't purging the package we stop here. Note
3020 that packages which have no <prgn>postrm</prgn> and no
3021 <tt>conffile</tt>s are automatically purged when
3022 removed, as there is no difference except for the
3023 <prgn>dpkg</prgn> status.
3027 The <tt>conffile</tt>s and any backup files
3028 (<tt>~</tt>-files, <tt>#*#</tt> files,
3029 <tt>%</tt>-files, <tt>.dpkg-{old,new,tmp}</tt>, etc.)
3033 <example compact="compact">
3034 <var>postrm</var> purge
3038 The package's file list is removed.
3042 No attempt is made to unwind after errors during
3049 <chapt id="relationships">
3050 <heading>Declaring relationships between packages</heading>
3052 <sect id="depsyntax">
3053 <heading>Syntax of relationship fields</heading>
3056 These fields all have a uniform syntax. They are a list of
3057 package names separated by commas.
3061 In the <tt>Depends</tt>, <tt>Recommends</tt>,
3062 <tt>Suggests</tt>, <tt>Pre-Depends</tt>,
3063 <tt>Build-Depends</tt> and <tt>Build-Depends-Indep</tt>
3064 control file fields of the package, which declare
3065 dependencies on other packages, the package names listed may
3066 also include lists of alternative package names, separated
3067 by vertical bar (pipe) symbols <tt>|</tt>. In such a case,
3068 if any one of the alternative packages is installed, that
3069 part of the dependency is considered to be satisfied.
3073 All of the fields except for <tt>Provides</tt> may restrict
3074 their applicability to particular versions of each named
3075 package. This is done in parentheses after each individual
3076 package name; the parentheses should contain a relation from
3077 the list below followed by a version number, in the format
3078 described in <ref id="versions">.
3082 The relations allowed are <tt><<</tt>, <tt><=</tt>,
3083 <tt>=</tt>, <tt>>=</tt> and <tt>>></tt> for
3084 strictly earlier, earlier or equal, exactly equal, later or
3085 equal and strictly later, respectively. The deprecated
3086 forms <tt><</tt> and <tt>></tt> were used to mean
3087 earlier/later or equal, rather than strictly earlier/later,
3088 so they should not appear in new packages (though
3089 <prgn>dpkg</prgn> still supports them).
3093 Whitespace may appear at any point in the version
3094 specification subject to the rules in <ref
3095 id="controlsyntax">, and must appear where it's necessary to
3096 disambiguate; it is not otherwise significant. For
3097 consistency and in case of future changes to
3098 <prgn>dpkg</prgn> it is recommended that a single space be
3099 used after a version relationship and before a version
3100 number; it is also conventional to put a single space after
3101 each comma, on either side of each vertical bar, and before
3102 each open parenthesis.
3106 For example, a list of dependencies might appear as:
3107 <example compact="compact">
3110 Depends: libc6 (>= 2.2.1), exim | mail-transport-agent
3115 All fields that specify build-time relationships
3116 (<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
3117 <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>)
3118 may be restricted to a certain set of architectures. This
3119 is indicated in brackets after each individual package name and
3120 the optional version specification. The brackets enclose a
3121 list of Debian architecture names separated by whitespace.
3122 Exclamation marks may be prepended to each of the names.
3123 (It is not permitted for some names to be prepended with
3124 exclamation marks and others not.) If the current Debian
3125 host architecture is not in this list and there are no
3126 exclamation marks in the list, or it is in the list with a
3127 prepended exclamation mark, the package name and the
3128 associated version specification are ignored completely for
3129 the purposes of defining the relationships.
3134 <example compact="compact">
3136 Build-Depends-Indep: texinfo
3137 Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
3138 hurd-dev [hurd-i386], gnumach-dev [hurd-i386]
3143 Note that the binary package relationship fields such as
3144 <tt>Depends</tt> appear in one of the binary package
3145 sections of the control file, whereas the build-time
3146 relationships such as <tt>Build-Depends</tt> appear in the
3147 source package section of the control file (which is the
3153 <heading>Binary Dependencies - <tt>Depends</tt>,
3154 <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
3155 <tt>Pre-Depends</tt>
3159 Packages can declare in their control file that they have
3160 certain relationships to other packages - for example, that
3161 they may not be installed at the same time as certain other
3162 packages, and/or that they depend on the presence of others.
3166 This is done using the <tt>Depends</tt>, <tt>Pre-Depends</tt>,
3167 <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt> and
3168 <tt>Conflicts</tt> control file fields.
3172 These six fields are used to declare a dependency
3173 relationship by one package on another. Except for
3174 <tt>Enhances</tt>, they appear in the depending (binary)
3175 package's control file. (<tt>Enhances</tt> appears in the
3176 recommending package's control file.)
3180 A <tt>Depends</tt> field takes effect <em>only</em> when a
3181 package is to be configured. It does not prevent a package
3182 being on the system in an unconfigured state while its
3183 dependencies are unsatisfied, and it is possible to replace
3184 a package whose dependencies are satisfied and which is
3185 properly installed with a different version whose
3186 dependencies are not and cannot be satisfied; when this is
3187 done the depending package will be left unconfigured (since
3188 attempts to configure it will give errors) and will not
3189 function properly. If it is necessary, a
3190 <tt>Pre-Depends</tt> field can be used, which has a partial
3191 effect even when a package is being unpacked, as explained
3192 in detail below. (The other three dependency fields,
3193 <tt>Recommends</tt>, <tt>Suggests</tt> and
3194 <tt>Enhances</tt>, are only used by the various front-ends
3195 to <prgn>dpkg</prgn> such as <prgn>dselect</prgn>.)
3199 For this reason packages in an installation run are usually
3200 all unpacked first and all configured later; this gives
3201 later versions of packages with dependencies on later
3202 versions of other packages the opportunity to have their
3203 dependencies satisfied.
3207 The <tt>Depends</tt> field thus allows package maintainers
3208 to impose an order in which packages should be configured.
3212 The meaning of the five dependency fields is as follows:
3214 <tag><tt>Depends</tt></tag>
3217 This declares an absolute dependency. A package will
3218 not be configured unless all of the packages listed in
3219 its <tt>Depends</tt> field have been correctly
3224 The <tt>Depends</tt> field should be used if the
3225 depended-on package is required for the depending
3226 package to provide a significant amount of
3231 The <tt>Depends</tt> field should also be used if the
3232 <prgn>postinst</prgn>, <prgn>prerm</prgn> or
3233 <prgn>postrm</prgn> scripts require the package to be
3234 present in order to run. Note, however, that the
3235 <prgn>postrm</prgn> cannot rely on any non-essential
3236 packages to be present during the <tt>purge</tt>
3240 <tag><tt>Recommends</tt></tag>
3243 This declares a strong, but not absolute, dependency.
3247 The <tt>Recommends</tt> field should list packages
3248 that would be found together with this one in all but
3249 unusual installations.
3253 <tag><tt>Suggests</tt></tag>
3255 This is used to declare that one package may be more
3256 useful with one or more others. Using this field
3257 tells the packaging system and the user that the
3258 listed packages are related to this one and can
3259 perhaps enhance its usefulness, but that installing
3260 this one without them is perfectly reasonable.
3263 <tag><tt>Enhances</tt></tag>
3265 This field is similar to Suggests but works in the
3266 opposite direction. It is used to declare that a
3267 package can enhance the functionality of another
3271 <tag><tt>Pre-Depends</tt></tag>
3274 This field is like <tt>Depends</tt>, except that it
3275 also forces <prgn>dpkg</prgn> to complete installation
3276 of the packages named before even starting the
3277 installation of the package which declares the
3278 pre-dependency, as follows:
3282 When a package declaring a pre-dependency is about to
3283 be <em>unpacked</em> the pre-dependency can be
3284 satisfied if the depended-on package is either fully
3285 configured, <em>or even if</em> the depended-on
3286 package(s) are only unpacked or half-configured,
3287 provided that they have been configured correctly at
3288 some point in the past (and not removed or partially
3289 removed since). In this case, both the
3290 previously-configured and currently unpacked or
3291 half-configured versions must satisfy any version
3292 clause in the <tt>Pre-Depends</tt> field.
3296 When the package declaring a pre-dependency is about
3297 to be <em>configured</em>, the pre-dependency will be
3298 treated as a normal <tt>Depends</tt>, that is, it will
3299 be considered satisfied only if the depended-on
3300 package has been correctly configured.
3304 <tt>Pre-Depends</tt> should be used sparingly,
3305 preferably only by packages whose premature upgrade or
3306 installation would hamper the ability of the system to
3307 continue with any upgrade that might be in progress.
3311 <tt>Pre-Depends</tt> are also required if the
3312 <prgn>preinst</prgn> script depends on the named
3313 package. It is best to avoid this situation if
3321 When selecting which level of dependency to use you should
3322 consider how important the depended-on package is to the
3323 functionality of the one declaring the dependency. Some
3324 packages are composed of components of varying degrees of
3325 importance. Such a package should list using
3326 <tt>Depends</tt> the package(s) which are required by the
3327 more important components. The other components'
3328 requirements may be mentioned as Suggestions or
3329 Recommendations, as appropriate to the components' relative
3334 <sect id="conflicts">
3335 <heading>Conflicting binary packages - <tt>Conflicts</tt></heading>
3338 When one binary package declares a conflict with another
3339 using a <tt>Conflicts</tt> field, <prgn>dpkg</prgn> will
3340 refuse to allow them to be installed on the system at the
3345 If one package is to be installed, the other must be removed
3346 first - if the package being installed is marked as
3347 replacing (see <ref id="replaces">) the one on the system,
3348 or the one on the system is marked as deselected, or both
3349 packages are marked <tt>Essential</tt>, then
3350 <prgn>dpkg</prgn> will automatically remove the package
3351 which is causing the conflict, otherwise it will halt the
3352 installation of the new package with an error. This
3353 mechanism is specifically designed to produce an error when
3354 the installed package is <tt>Essential</tt>, but the new
3359 A package will not cause a conflict merely because its
3360 configuration files are still installed; it must be at least
3365 A special exception is made for packages which declare a
3366 conflict with their own package name, or with a virtual
3367 package which they provide (see below): this does not
3368 prevent their installation, and allows a package to conflict
3369 with others providing a replacement for it. You use this
3370 feature when you want the package in question to be the only
3371 package providing some feature.
3375 A <tt>Conflicts</tt> entry should almost never have an
3376 "earlier than" version clause. This would prevent
3377 <prgn>dpkg</prgn> from upgrading or installing the package
3378 which declared such a conflict until the upgrade or removal
3379 of the conflicted-with package had been completed.
3383 <sect id="virtual"><heading>Virtual packages - <tt>Provides</tt>
3387 As well as the names of actual ("concrete") packages, the
3388 package relationship fields <tt>Depends</tt>,
3389 <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
3390 <tt>Pre-Depends</tt>, <tt>Conflicts</tt>,
3391 <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
3392 <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>
3393 may mention "virtual packages".
3397 A <em>virtual package</em> is one which appears in the
3398 <tt>Provides</tt> control file field of another package.
3399 The effect is as if the package(s) which provide a
3400 particular virtual package name had been listed by name
3401 everywhere the virtual package name appears. (See also <ref
3406 If there are both concrete and virtual packages of the same
3407 name, then the dependency may be satisfied (or the conflict
3408 caused) by either the concrete package with the name in
3409 question or any other concrete package which provides the
3410 virtual package with the name in question. This is so that,
3411 for example, supposing we have
3412 <example compact="compact">
3416 and someone else releases an enhanced version of the
3417 <tt>bar</tt> package (for example, a non-US variant), they
3419 <example compact="compact">
3423 and the <tt>bar-plus</tt> package will now also satisfy the
3424 dependency for the <tt>foo</tt> package.
3428 If a dependency or a conflict has a version number attached
3429 then only real packages will be considered to see whether
3430 the relationship is satisfied (or the prohibition violated,
3431 for a conflict) - it is assumed that a real package which
3432 provides the virtual package is not of the "right" version.
3433 So, a <tt>Provides</tt> field may not contain version
3434 numbers, and the version number of the concrete package
3435 which provides a particular virtual package will not be
3436 looked at when considering a dependency on or conflict with
3437 the virtual package name.
3441 It is likely that the ability will be added in a future
3442 release of <prgn>dpkg</prgn> to specify a version number for
3443 each virtual package it provides. This feature is not yet
3444 present, however, and is expected to be used only
3449 If you want to specify which of a set of real packages
3450 should be the default to satisfy a particular dependency on
3451 a virtual package, you should list the real package as an
3452 alternative before the virtual one.
3457 <sect id="replaces"><heading>Overwriting files and replacing
3458 packages - <tt>Replaces</tt></heading>
3461 Packages can declare in their control file that they should
3462 overwrite files in certain other packages, or completely
3463 replace other packages. The <tt>Replaces</tt> control file
3464 field has these two distinct purposes.
3467 <sect1><heading>Overwriting files in other packages</heading>
3470 Firstly, as mentioned before, it is usually an error for a
3471 package to contain files which are on the system in
3476 However, if the overwriting package declares that it
3477 <tt>Replaces</tt> the one containing the file being
3478 overwritten, then <prgn>dpkg</prgn> will replace the file
3479 from the old package with that from the new. The file
3480 will no longer be listed as "owned" by the old package.
3484 If a package is completely replaced in this way, so that
3485 <prgn>dpkg</prgn> does not know of any files it still
3486 contains, it is considered to have "disappeared". It will
3487 be marked as not wanted on the system (selected for
3488 removal) and not installed. Any <tt>conffile</tt>s
3489 details noted for the package will be ignored, as they
3490 will have been taken over by the overwriting package. The
3491 package's <prgn>postrm</prgn> script will be run with a
3492 special argument to allow the package to do any final
3493 cleanup required. See <ref id="mscriptsinstact">.
3497 If an installed package, <tt>foo</tt> say, declares that
3498 it replaces another, <tt>bar</tt>, and an attempt is made
3499 to install <tt>bar</tt>, <prgn>dpkg</prgn> will discard
3500 files in the <tt>bar</tt> package which would overwrite
3501 those already present in <tt>foo</tt>. This is so that
3502 you can install an older version of a package without
3507 For this usage of <tt>Replaces</tt>, virtual packages (see
3508 <ref id="virtual">) are not considered when looking at a
3509 <tt>Replaces</tt> field - the packages declared as being
3510 replaced must be mentioned by their real names.
3514 Furthermore, this usage of <tt>Replaces</tt> only takes
3515 effect when both packages are at least partially on the
3516 system at once, so that it can only happen if they do not
3517 conflict or if the conflict has been overridden.
3522 <sect1><heading>Replacing whole packages, forcing their
3526 Secondly, <tt>Replaces</tt> allows the packaging system to
3527 resolve which package should be removed when there is a
3528 conflict - see <ref id="conflicts">. This usage only
3529 takes effect when the two packages <em>do</em> conflict,
3530 so that the two usages of this field do not interfere with
3535 In this situation, the package declared as being replaced
3536 can be a virtual package, so for example, all mail
3537 transport agents (MTAs) would have the following fields in
3538 their control files:
3539 <example compact="compact">
3540 Provides: mail-transport-agent
3541 Conflicts: mail-transport-agent
3542 Replaces: mail-transport-agent
3544 ensuring that only one MTA can be installed at any one
3549 <sect><heading>Relationships between source and binary packages -
3550 <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
3551 <tt>Build-Conflicts</tt>, <tt>Build-Conflicts-Indep</tt>
3555 Source packages that require certain binary packages to be
3556 installed or absent at the time of building the package
3557 can declare relationships to those binary packages.
3561 This is done using the <tt>Build-Depends</tt>,
3562 <tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt> and
3563 <tt>Build-Conflicts-Indep</tt> control file fields.
3567 Build-dependencies on "build-essential" binary packages can be
3568 omitted. Please see <ref id="pkg-relations"> for more information.
3572 The dependencies and conflicts they define must be satisfied
3573 (as defined earlier for binary packages) in order to invoke
3574 the targets in <tt>debian/rules</tt>, as follows:<footnote>
3576 If you make "build-arch" or "binary-arch", you need
3577 Build-Depends. If you make "build-indep" or
3578 "binary-indep", you need Build-Depends and
3579 Build-Depends-Indep. If you make "build" or "binary",
3583 There is no Build-Depends-Arch; the autobuilders will
3584 only need the Build-Depends if they know how to build
3585 only build-arch and binary-arch. Anyone building the
3586 build-indep/binary-indep targets is basically assumed to
3587 be building the whole package and so installs all build
3591 The purpose of the original split, I recall, was so that
3592 the autobuilders wouldn't need to install extra packages
3593 needed only for the binary-indep targets. But without a
3594 build-arch/build-indep split, this didn't work, since
3595 most of the work is done in the build target, not in the
3601 <tag><tt>Build-Depends</tt>, <tt>Build-Conflicts</tt></tag>
3603 The <tt>Build-Depends</tt> and
3604 <tt>Build-Conflicts</tt> fields must be satisfied when
3605 any of the following targets is invoked:
3606 <tt>build</tt>, <tt>clean</tt>, <tt>binary</tt>,
3607 <tt>binary-arch</tt>, <tt>build-arch</tt>,
3608 <tt>build-indep</tt> and <tt>binary-indep</tt>.
3610 <tag><tt>Build-Depends-Indep</tt>,
3611 <tt>Build-Conflicts-Indep</tt></tag>
3613 The <tt>Build-Depends-Indep</tt> and
3614 <tt>Build-Conflicts-Indep</tt> fields must be
3615 satisfied when any of the following targets is
3616 invoked: <tt>build</tt>, <tt>clean</tt>,
3617 <tt>build-indep</tt>, <tt>binary</tt> and
3618 <tt>binary-indep</tt>.
3629 <chapt id="conffiles">
3630 <heading>Configuration file handling</heading>
3633 This chapter has been superseded by <ref id="config-files">.
3638 <chapt id="sharedlibs"><heading>Shared libraries</heading>
3641 Packages containing shared libraries must be constructed with
3642 a little care to make sure that the shared library is always
3643 available. This is especially important for packages whose
3644 shared libraries are vitally important, such as the C library
3645 (currently <tt>libc6</tt>).
3649 Packages involving shared libraries should be split up into
3650 several binary packages. This section mostly deals with how
3651 this separation is to be accomplished; rules for files within
3652 the shared library packages are in <ref id="libraries"> instead.
3655 <sect id="sharedlibs-runtime">
3656 <heading>Run-time shared libraries</heading>
3659 The run-time shared library needs to be placed in a package called
3660 <package><var>libraryname</var><var>soversion</var></package>, where
3661 <file><var>soversion</var></file> is the version number in the
3662 soname of the shared library<footnote>
3663 The soname is the shared object name: it's the thing
3664 that has to match exactly between building an executable
3665 and running it for the dynamic linker to be able run the
3666 program. For example, if the soname of the library is
3667 <file>libfoo.so.6</file>, the library package would be
3668 called <file>libfoo6</file>.
3670 Alternatively, if it would be confusing to directly append
3671 <var>soversion</var> to <var>libraryname</var> (e.g. because
3672 <var>libraryname</var> itself ends in a number), you may use
3673 <package><var>libraryname</var>-<var>soversion</var></package> and
3674 <package><var>libraryname</var>-<var>soversion</var>-dev</package>
3679 If you have several shared libraries built from the same
3680 source tree you may lump them all together into a single
3681 shared library package, provided that you change all of
3682 their sonames at once (so that you don't get filename
3683 clashes if you try to install different versions of the
3684 combined shared libraries package).
3688 The package should install the shared libraries under
3689 their normal names. For example, the <package>libgdbmg1</package>
3690 package should install <file>libgdbm.so.1.7.3</file> as
3691 <file>/usr/lib/libgdbm.so.1.7.3</file>. The files should not be
3692 renamed or re-linked by any <prgn>prerm</prgn> or
3693 <prgn>postrm</prgn> scripts; <prgn>dpkg</prgn> will take care
3694 of renaming things safely without affecting running programs,
3695 and attempts to interfere with this are likely to lead to
3700 Shared libraries should not be installed executable, since
3701 the dynamic linker does not require this and trying to
3702 execute a shared library usually results in a core dump.
3706 The run-time library package should include the symbolic link that
3707 <prgn>ldconfig</prgn> would create for the shared libraries.
3708 For example, the <package>libgdbmg1</package> package should include
3709 a symbolic link from <file>/usr/lib/libgdbm.so.1</file> to
3710 <file>libgdbm.so.1.7.3</file>. This is needed so that the dynamic
3711 linker (for example <prgn>ld.so</prgn> or
3712 <prgn>ld-linux.so.*</prgn>) can find the library between the
3713 time that <prgn>dpkg</prgn> installs it and the time that
3714 <prgn>ldconfig</prgn> is run in the <prgn>postinst</prgn>
3716 The package management system requires the library to be
3717 placed before the symbolic link pointing to it in the
3718 <file>.deb</file> file. This is so that when
3719 <prgn>dpkg</prgn> comes to install the symlink
3720 (overwriting the previous symlink pointing at an older
3721 version of the library), the new shared library is already
3722 in place. In the past, this was achieved by creating the
3723 library in the temporary packaging directory before
3724 creating the symlink. Unfortunately, this was not always
3725 effective, since the building of the tar file in the
3726 <file>.deb</file> depended on the behavior of the underlying
3727 file system. Some file systems (such as reiserfs) reorder
3728 the files so that the order of creation is forgotten.
3729 Since version 1.7.0, <prgn>dpkg</prgn>
3730 reorders the files itself as necessary when building a
3731 package. Thus it is no longer important to concern
3732 oneself with the order of file creation.
3736 <sect1 id="ldconfig">
3737 <heading><tt>ldconfig</tt></heading>
3740 Any package installing shared libraries in one of the default
3741 library directories of the dynamic linker (which are currently
3742 <file>/usr/lib</file> and <file>/lib</file>) or a directory that is
3743 listed in <file>/etc/ld.so.conf</file><footnote>
3745 <list compact="compact">
3746 <item>/usr/X11R6/lib/Xaw3d</item>
3747 <item>/usr/local/lib</item>
3748 <item>/usr/lib/libc5-compat</item>
3749 <item>/lib/libc5-compat</item>
3750 <item>/usr/X11R6/lib</item>
3753 must use <prgn>ldconfig</prgn> to update the shared library
3758 The package must call <prgn>ldconfig</prgn> in the
3759 <prgn>postinst</prgn> script if the first argument is
3760 <tt>configure</tt>; the <prgn>postinst</prgn> script may
3761 optionally invoke <prgn>ldconfig</prgn> at other times. The
3762 package should call <prgn>ldconfig</prgn> in the
3763 <prgn>postrm</prgn> script if the first argument is
3764 <tt>remove</tt>. The maintainer scripts must not invoke
3765 <prgn>ldconfig</prgn> under any circumstances other than those
3766 described in this paragraph.<footnote>
3768 During install or upgrade, the preinst is called before
3769 the new files are installed, so calling "ldconfig" is
3770 pointless. The preinst of an existing package can also be
3771 called if an upgrade fails. However, this happens during
3772 the critical time when a shared libs may exist on-disk
3773 under a temporary name. Thus, it is dangerous and
3774 forbidden by current policy to call "ldconfig" at this
3779 When a package is installed or upgraded, "postinst
3780 configure" runs after the new files are safely on-disk.
3781 Since it is perfectly safe to invoke ldconfig
3782 unconditionally in a postinst, it is OK for a package to
3783 simply put ldconfig in its postinst without checking the
3784 argument. The postinst can also be called to recover from
3785 a failed upgrade. This happens before any new files are
3786 unpacked, so there is no reason to call "ldconfig" at this
3791 For a package that is being removed, prerm is
3792 called with all the files intact, so calling ldconfig is
3793 useless. The other calls to "prerm" happen in the case of
3794 upgrade at a time when all the files of the old package
3795 are on-disk, so again calling "ldconfig" is pointless.
3799 postrm, on the other hand, is called with the "remove"
3800 argument just after the files are removed, so this is the
3801 proper time to call "ldconfig" to notify the system of the
3802 fact shared libraries from the package are removed.
3803 The postrm can be called at several other times. At the
3804 time of "postrm purge", "postrm abort-install", or "postrm
3805 abort-upgrade", calling "ldconfig" is useless because the
3806 shared lib files are not on-disk. However, when "postrm"
3807 is invoked with arguments "upgrade", "failed-upgrade", or
3808 "disappear", a shared lib may exist on-disk under a
3817 <sect id="sharedlibs-runtime-progs">
3818 <heading>Run-time support programs</heading>
3821 If your package has some run-time support programs which use
3822 the shared library you must not put them in the shared
3823 library package. If you do that then you won't be able to
3824 install several versions of the shared library without
3825 getting filename clashes.
3829 Instead, either create another package for the runtime binaries
3830 (this package might typically be named
3831 <package><var>libraryname</var>-runtime</package>; note the absence
3832 of the <var>soversion</var> in the package name), or if the
3833 development package is small, include them in there.
3837 <sect id="sharedlibs-static">
3838 <heading>Static libraries</heading>
3841 The static library (<file><var>libraryname.a</var></file>)
3842 is usually provided in addition to the shared version.
3843 It is placed into the development package (see below).
3847 In some cases, it is acceptable for a library to be
3848 available in static form only; these cases include:
3850 <item>libraries for languages whose shared library support
3851 is immature or unstable</item>
3852 <item>libraries whose interfaces are in flux or under
3853 development (commonly the case when the library's
3854 major version number is zero, or where the ABI breaks
3855 across patchlevels)</item>
3856 <item>libraries which are explicitly intended to be
3857 available only in static form by their upstream
3862 <sect id="sharedlibs-dev">
3863 <heading>Development files</heading>
3866 The development files associated to a shared library need to be
3867 placed in a package called
3868 <package><var>libraryname</var><var>soversion</var>-dev</package>,
3869 or if you prefer only to support one development version at a
3870 time, <package><var>libraryname</var>-dev</package>.
3874 In case several development versions of a library exist, you may
3875 need to use <prgn>dpkg</prgn>'s Conflicts mechanism (see
3876 <ref id="conflicts">) to ensure that the user only installs one
3877 development version at a time (as different development versions are
3878 likely to have the same header files in them, which would cause a
3879 filename clash if both were installed).
3883 The development package should contain a symlink for the associated
3884 shared library without a version number. For example, the
3885 <package>libgdbmg1-dev</package> package should include a symlink
3886 from <file>/usr/lib/libgdbm.so</file> to
3887 <file>libgdbm.so.1.7.3</file>. This symlink is needed by the linker
3888 (<prgn>ld</prgn>) when compiling packages, as it will only look for
3889 <file>libgdbm.so</file> when compiling dynamically.
3893 <sect id="sharedlibs-intradeps">
3894 <heading>Dependencies between the packages of the same library</heading>
3897 Typically the development version should have an exact
3898 version dependency on the runtime library, to make sure that
3899 compilation and linking happens correctly. The
3900 <tt>${Source-Version}</tt> substitution variable can be
3901 useful for this purpose.
3905 <sect id="sharedlibs-shlibdeps">
3906 <heading>Dependencies between the library and other packages -
3907 the <tt>shlibs</tt> system</heading>
3910 If a package contains a binary or library which links to a
3911 shared library, we must ensure that when the package is
3912 installed on the system, all of the libraries needed are
3913 also installed. This requirement led to the creation of the
3914 <tt>shlibs</tt> system, which is very simple in its design:
3915 any package which <em>provides</em> a shared library also
3916 provides information on the package dependencies required to
3917 ensure the presence of this library, and any package which
3918 <em>uses</em> a shared library uses this information to
3919 determine the dependencies it requires. The files which
3920 contain the mapping from shared libraries to the necessary
3921 dependency information are called <file>shlibs</file> files.
3925 Thus, when a package is built which contains any shared
3926 libraries, it must provide a <file>shlibs</file> file for other
3927 packages to use, and when a package is built which contains
3928 any shared libraries or compiled binaries, it must run
3929 <prgn>dpkg-shlibdeps</prgn> on these to determine the
3930 libraries used and hence the dependencies needed by this
3933 In the past, the shared libraries linked to were
3934 determined by calling <prgn>ldd</prgn>, but now
3935 <prgn>objdump</prgn> is used to do this. The only
3936 change this makes to package building is that
3937 <prgn>dpkg-shlibdeps</prgn> must also be run on shared
3938 libraries, whereas in the past this was unnecessary.
3939 The rest of this footnote explains the advantage that
3944 We say that a binary <tt>foo</tt> <em>directly</em> uses
3945 a library <tt>libbar</tt> if it is explicitly linked
3946 with that library (that is, it uses the flag
3947 <tt>-lbar</tt> during the linking stage). Other
3948 libraries that are needed by <tt>libbar</tt> are linked
3949 <em>indirectly</em> to <tt>foo</tt>, and the dynamic
3950 linker will load them automatically when it loads
3951 <tt>libbar</tt>. A package should depend on
3952 the libraries it directly uses, and the dependencies for
3953 those libraries should automatically pull in the other
3958 Unfortunately, the <prgn>ldd</prgn> program shows both
3959 the directly and indirectly used libraries, meaning that
3960 the dependencies determined included both direct and
3961 indirect dependencies. The use of <prgn>objdump</prgn>
3962 avoids this problem by determining only the directly
3967 A good example of where this helps is the following. We
3968 could update <tt>libimlib</tt> with a new version that
3969 supports a new graphics format called dgf (but retaining
3970 the same major version number). If we used the old
3971 <prgn>ldd</prgn> method, every package that uses
3972 <tt>libimlib</tt> would need to be recompiled so it
3973 would also depend on <tt>libdgf</tt> or it wouldn't run
3974 due to missing symbols. However with the new system,
3975 packages using <tt>libimlib</tt> can rely on
3976 <tt>libimlib</tt> itself having the dependency on
3977 <tt>libdgf</tt> and so they would not need rebuilding.
3983 In the following sections, we will first describe where the
3984 various <tt>shlibs</tt> files are to be found, then how to
3985 use <prgn>dpkg-shlibdeps</prgn>, and finally the
3986 <tt>shlibs</tt> file format and how to create them if your
3987 package contains a shared library.
3991 <heading>The <tt>shlibs</tt> files present on the system</heading>
3994 There are several places where <tt>shlibs</tt> files are
3995 found. The following list gives them in the order in which
3996 they are read by <prgn>dpkg-shlibdeps</prgn>. (The first
3997 one which gives the required information is used.)
4003 <p><file>debian/shlibs.local</file></p>
4006 This lists overrides for this package. Its use is
4007 described below (see <ref id="shlibslocal">).
4012 <p><file>/etc/dpkg/shlibs.override</file></p>
4015 This lists global overrides. This list is normally
4016 empty. It is maintained by the local system
4022 <p><file>DEBIAN/shlibs</file> files in the "build directory"</p>
4025 When packages are being built, any
4026 <file>debian/shlibs</file> files are copied into the
4027 control file area of the temporary build directory and
4028 given the name <file>shlibs</file>. These files give
4029 details of any shared libraries included in the
4031 An example may help here. Let us say that the
4032 source package <tt>foo</tt> generates two binary
4033 packages, <tt>libfoo2</tt> and
4034 <tt>foo-runtime</tt>. When building the binary
4035 packages, the two packages are created in the
4036 directories <file>debian/libfoo2</file> and
4037 <file>debian/foo-runtime</file> respectively.
4038 (<file>debian/tmp</file> could be used instead of one
4039 of these.) Since <tt>libfoo2</tt> provides the
4040 <tt>libfoo</tt> shared library, it will require a
4041 <tt>shlibs</tt> file, which will be installed in
4042 <file>debian/libfoo2/DEBIAN/shlibs</file>, eventually
4044 <file>/var/lib/dpkg/info/libfoo2.shlibs</file>. Then
4045 when <prgn>dpkg-shlibdeps</prgn> is run on the
4047 <file>debian/foo-runtime/usr/bin/foo-prog</file>, it
4049 <file>debian/libfoo2/DEBIAN/shlibs</file> file to
4050 determine whether <tt>foo-prog</tt>'s library
4051 dependencies are satisfied by any of the libraries
4052 provided by <tt>libfoo2</tt>. For this reason,
4053 <prgn>dpkg-shlibdeps</prgn> must only be run once
4054 all of the individual binary packages'
4055 <tt>shlibs</tt> files have been installed into the
4062 <p><file>/var/lib/dpkg/info/*.shlibs</file></p>
4065 These are the <file>shlibs</file> files corresponding to
4066 all of the packages installed on the system, and are
4067 maintained by the relevant package maintainers.
4072 <p><file>/etc/dpkg/shlibs.default</file></p>
4075 This file lists any shared libraries whose packages
4076 have failed to provide correct <file>shlibs</file> files.
4077 It was used when the <file>shlibs</file> setup was first
4078 introduced, but it is now normally empty. It is
4079 maintained by the <tt>dpkg</tt> maintainer.
4087 <heading>How to use <prgn>dpkg-shlibdeps</prgn> and the
4088 <file>shlibs</file> files</heading>
4091 Put a call to <prgn>dpkg-shlibdeps</prgn> into your
4092 <file>debian/rules</file> file. If your package contains only
4093 compiled binaries and libraries (but no scripts), you can
4094 use a command such as:
4095 <example compact="compact">
4096 dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \
4097 debian/tmp/usr/lib/*
4099 Otherwise, you will need to explicitly list the compiled
4100 binaries and libraries.<footnote>
4101 If you are using <tt>debhelper</tt>, the
4102 <prgn>dh_shlibdeps</prgn> program will do this work for
4103 you. It will also correctly handle multi-binary
4109 This command puts the dependency information into the
4110 <file>debian/substvars</file> file, which is then used by
4111 <prgn>dpkg-gencontrol</prgn>. You will need to place a
4112 <tt>${shlib:Depends}</tt> variable in the <tt>Depends</tt>
4113 field in the control file for this to work.
4117 If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
4118 done. If it does complain you might need to create your own
4119 <file>debian/shlibs.local</file> file, as explained below (see
4120 <ref id="shlibslocal">).
4124 If you have multiple binary packages, you will need to call
4125 <prgn>dpkg-shlibdeps</prgn> on each one which contains
4126 compiled libraries or binaries. In such a case, you will
4127 need to use the <tt>-T</tt> option to the <tt>dpkg</tt>
4128 utilities to specify a different <file>substvars</file> file.
4129 For more details on this and other options, see <manref
4130 name="dpkg-shlibdeps" section="1">.
4135 <heading>The <file>shlibs</file> File Format</heading>
4138 Each <file>shlibs</file> file has the same format. Lines
4139 beginning with <tt>#</tt> are considered to be comments and
4140 are ignored. Each line is of the form:
4141 <example compact="compact">
4142 <var>library-name</var> <var>soname-version-number</var> <var>dependencies ...</var>
4147 We will explain this by reference to the example of the
4148 <tt>zlib1g</tt> package, which (at the time of writing)
4149 installs the shared library <file>/usr/lib/libz.so.1.1.3</file>.
4153 <var>library-name</var> is the name of the shared library,
4154 in this case <tt>libz</tt>. (This must match the name part
4155 of the soname, see below.)
4159 <var>soname-version-number</var> is the version part of the
4160 soname of the library. The soname is the thing that must
4161 exactly match for the library to be recognized by the
4162 dynamic linker, and is usually of the form
4163 <tt><var>name</var>.so.<var>major-version</var></tt>, in our
4164 example, <tt>libz.so.1</tt>.<footnote>
4165 This can be determined using the command
4166 <example compact="compact">
4167 objdump -p /usr/lib/libz.so.1.1.3 | grep SONAME
4170 The version part is the part which comes after
4171 <tt>.so.</tt>, so in our case, it is <tt>1</tt>.
4175 <var>dependencies</var> has the same syntax as a dependency
4176 field in a binary package control file. It should give
4177 details of which packages are required to satisfy a binary
4178 built against the version of the library contained in the
4179 package. See <ref id="depsyntax"> for details.
4183 In our example, if the first version of the <tt>zlib1g</tt>
4184 package which contained a minor number of at least
4185 <tt>1.3</tt> was <var>1:1.1.3-1</var>, then the
4186 <tt>shlibs</tt> entry for this library could say:
4187 <example compact="compact">
4188 libz 1 zlib1g (>= 1:1.1.3)
4190 The version-specific dependency is to avoid warnings from
4191 the dynamic linker about using older shared libraries with
4197 <heading>Providing a <file>shlibs</file> file</heading>
4200 If your package provides a shared library, you should create
4201 a <file>shlibs</file> file following the format described above.
4202 It is usual to call this file <file>debian/shlibs</file> (but if
4203 you have multiple binary packages, you might want to call it
4204 <file>debian/shlibs.<var>package</var></file> instead). Then
4205 let <file>debian/rules</file> install it in the control area:
4206 <example compact="compact">
4207 install -m644 debian/shlibs debian/tmp/DEBIAN
4209 or, in the case of a multi-binary package:
4210 <example compact="compact">
4211 install -m644 debian/shlibs.<var>package</var> debian/<var>package</var>/DEBIAN/shlibs
4213 An alternative way of doing this is to create the
4214 <file>shlibs</file> file in the control area directly from
4215 <file>debian/rules</file> without using a <file>debian/shlibs</file>
4216 file at all,<footnote>
4217 This is what <prgn>dh_makeshlibs</prgn> in the
4218 <tt>debhelper</tt> suite does.
4220 since the <file>debian/shlibs</file> file itself is ignored by
4221 <prgn>dpkg-shlibdeps</prgn>.
4225 As <prgn>dpkg-shlibdeps</prgn> reads the
4226 <file>DEBIAN/shlibs</file> files in all of the binary packages
4227 being built from this source package, all of the
4228 <file>DEBIAN/shlibs</file> files should be installed before
4229 <prgn>dpkg-shlibdeps</prgn> is called on any of the binary
4234 <sect1 id="shlibslocal">
4235 <heading>Writing the <file>debian/shlibs.local</file> file</heading>
4238 This file is intended only as a <em>temporary</em> fix if
4239 your binaries or libraries depend on a library whose package
4240 does not yet provide a correct <file>shlibs</file> file.
4244 We will assume that you are trying to package a binary
4245 <tt>foo</tt>. When you try running
4246 <prgn>dpkg-shlibdeps</prgn> you get the following error
4247 message (<tt>-O</tt> displays the dependency information on
4248 <tt>stdout</tt> instead of writing it to
4249 <tt>debian/substvars</tt>, and the lines have been wrapped
4250 for ease of reading):
4251 <example compact="compact">
4252 $ dpkg-shlibdeps -O debian/tmp/usr/bin/foo
4253 dpkg-shlibdeps: warning: unable to find dependency
4254 information for shared library libbar (soname 1,
4255 path /usr/lib/libbar.so.1, dependency field Depends)
4256 shlibs:Depends=libc6 (>= 2.2.2-2)
4258 You can then run <prgn>ldd</prgn> on the binary to find the
4259 full location of the library concerned:
4260 <example compact="compact">
4262 libbar.so.1 => /usr/lib/libbar.so.1 (0x4001e000)
4263 libc.so.6 => /lib/libc.so.6 (0x40032000)
4264 /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
4266 So the <prgn>foo</prgn> binary depends on the
4267 <prgn>libbar</prgn> shared library, but no package seems to
4268 provide a <file>*.shlibs</file> file handling
4269 <file>libbar.so.1</file> in <file>/var/lib/dpkg/info/</file>. Let's
4270 determine the package responsible:
4271 <example compact="compact">
4272 $ dpkg -S /usr/lib/libbar.so.1
4273 bar1: /usr/lib/libbar.so.1
4274 $ dpkg -s bar1 | grep Version
4277 This tells us that the <tt>bar1</tt> package, version 1.0-1,
4278 is the one we are using. Now we can file a bug against the
4279 <tt>bar1</tt> package and create our own
4280 <file>debian/shlibs.local</file> to locally fix the problem.
4281 Including the following line into your
4282 <file>debian/shlibs.local</file> file:
4283 <example compact="compact">
4284 libbar 1 bar1 (>= 1.0-1)
4286 should allow the package build to work.
4290 As soon as the maintainer of <tt>bar1</tt> provides a
4291 correct <file>shlibs</file> file, you should remove this line
4292 from your <file>debian/shlibs.local</file> file. (You should
4293 probably also then have a versioned <tt>Build-Depends</tt>
4294 on <tt>bar1</tt> to help ensure that others do not have the
4295 same problem building your package.)
4303 <chapt id="opersys"><heading>The Operating System</heading>
4306 <heading>Filesystem hierarchy</heading>
4310 <heading>Filesystem Structure</heading>
4313 The location of all installed files and directories must
4314 comply with the Filesystem Hierarchy Standard (FHS),
4315 version 2.1, except where doing so would violate other
4316 terms of Debian Policy. The version of this document
4317 referred here can be found in the <tt>debian-policy</tt>
4319 <url id="http://www.debian.org/doc/packaging-manuals/fhs/"
4320 name="FHS (Debian copy)"> alongside this manual (or, if
4321 you have the <package>debian-policy</package> installed,
4323 id="file:///usr/share/doc/debian-policy/fhs/" name="FHS
4324 (local copy)">). The
4325 latest version, which may be a more recent version, may
4327 <url id="http://www.pathname.com/fhs/" name="FHS (upstream)">.
4328 Specific questions about following the standard may be
4329 asked on the <tt>debian-devel</tt> mailing list, or
4330 referred to the FHS mailing list (see the
4331 <url id="http://www.pathname.com/fhs/" name="FHS web site"> for
4337 <heading>Site-specific programs</heading>
4340 As mandated by the FHS, packages must not place any
4341 files in <file>/usr/local</file>, either by putting them in
4342 the file system archive to be unpacked by <prgn>dpkg</prgn>
4343 or by manipulating them in their maintainer scripts.
4347 However, the package may create empty directories below
4348 <file>/usr/local</file> so that the system administrator knows
4349 where to place site-specific files. These directories
4350 should be removed on package removal if they are
4355 Note, that this applies only to directories <em>below</em>
4356 <file>/usr/local</file>, not <em>in</em> <file>/usr/local</file>.
4357 Packages must not create sub-directories in the directory
4358 <file>/usr/local</file> itself, except those listed in FHS,
4359 section 4.5. However, you may create directories below
4360 them as you wish. You must not remove any of the
4361 directories listed in 4.5, even if you created them.
4365 Since <file>/usr/local</file> can be mounted read-only from a
4366 remote server, these directories must be created and
4367 removed by the <prgn>postinst</prgn> and <prgn>prerm</prgn>
4368 maintainer scripts and not be included in the
4369 <file>.deb</file> archive. These scripts must not fail if
4370 either of these operations fail.
4374 For example, the <tt>emacsen-common</tt> package could
4375 contain something like
4376 <example compact="compact">
4377 if [ ! -e /usr/local/share/emacs ]
4379 if mkdir /usr/local/share/emacs 2>/dev/null
4381 chown root:staff /usr/local/share/emacs
4382 chmod 2775 /usr/local/share/emacs
4386 in its <prgn>postinst</prgn> script, and
4387 <example compact="compact">
4388 rmdir /usr/local/share/emacs/site-lisp 2>/dev/null || true
4389 rmdir /usr/local/share/emacs 2>/dev/null || true
4391 in the <prgn>prerm</prgn> script. (Note that this form is
4392 used to ensure that if the script is interrupted, the
4393 directory <file>/usr/local/share/emacs</file> will still be
4398 If you do create a directory in <file>/usr/local</file> for
4399 local additions to a package, you should ensure that
4400 settings in <file>/usr/local</file> take precedence over the
4401 equivalents in <file>/usr</file>.
4405 However, because <file>/usr/local</file> and its contents are
4406 for exclusive use of the local administrator, a package
4407 must not rely on the presence or absence of files or
4408 directories in <file>/usr/local</file> for normal operation.
4412 The <file>/usr/local</file> directory itself and all the
4413 subdirectories created by the package should (by default) have
4414 permissions 2775 (group-writable and set-group-id) and be
4415 owned by <tt>root.staff</tt>.
4420 <heading>The system-wide mail directory</heading>
4422 The system-wide mail directory is <file>/var/mail</file>. This
4423 directory is part of the base system and should not owned
4424 by any particular mail agents. The use of the old
4425 location <file>/var/spool/mail</file> is deprecated, even
4426 though the spool may still be physically located there.
4427 To maintain partial upgrade compatibility for systems
4428 which have <file>/var/spool/mail</file> as their physical mail
4429 spool, packages using <file>/var/mail</file> must depend on
4430 either <package>libc6</package> (>= 2.1.3-13), or on
4431 <package>base-files</package> (>= 2.2.0), or on later
4432 versions of either one of these packages.
4438 <heading>Users and groups</heading>
4441 <heading>Introduction</heading>
4443 The Debian system can be configured to use either plain or
4448 Some user ids (UIDs) and group ids (GIDs) are reserved
4449 globally for use by certain packages. Because some
4450 packages need to include files which are owned by these
4451 users or groups, or need the ids compiled into binaries,
4452 these ids must be used on any Debian system only for the
4453 purpose for which they are allocated. This is a serious
4454 restriction, and we should avoid getting in the way of
4455 local administration policies. In particular, many sites
4456 allocate users and/or local system groups starting at 100.
4460 Apart from this we should have dynamically allocated ids,
4461 which should by default be arranged in some sensible
4462 order, but the behavior should be configurable.
4466 Packages other than <tt>base-passwd</tt> must not modify
4467 <file>/etc/passwd</file>, <file>/etc/shadow</file>,
4468 <file>/etc/group</file> or <file>/etc/gshadow</file>.
4473 <heading>UID and GID classes</heading>
4475 The UID and GID numbers are divided into classes as
4481 Globally allocated by the Debian project, the same
4482 on every Debian system. These ids will appear in
4483 the <file>passwd</file> and <file>group</file> files of all
4484 Debian systems, new ids in this range being added
4485 automatically as the <tt>base-passwd</tt> package is
4490 Packages which need a single statically allocated
4491 uid or gid should use one of these; their
4492 maintainers should ask the <tt>base-passwd</tt>
4500 Dynamically allocated system users and groups.
4501 Packages which need a user or group, but can have
4502 this user or group allocated dynamically and
4503 differently on each system, should use <tt>adduser
4504 --system</tt> to create the group and/or user.
4505 <prgn>adduser</prgn> will check for the existence of
4506 the user or group, and if necessary choose an unused
4507 id based on the ranges specified in
4508 <file>adduser.conf</file>.
4512 <tag>1000-29999:</tag>
4515 Dynamically allocated user accounts. By default
4516 <prgn>adduser</prgn> will choose UIDs and GIDs for
4517 user accounts in this range, though
4518 <file>adduser.conf</file> may be used to modify this
4523 <tag>30000-59999:</tag>
4528 <tag>60000-64999:</tag>
4531 Globally allocated by the Debian project, but only
4532 created on demand. The ids are allocated centrally
4533 and statically, but the actual accounts are only
4534 created on users' systems on demand.
4538 These ids are for packages which are obscure or
4539 which require many statically-allocated ids. These
4540 packages should check for and create the accounts in
4541 <file>/etc/passwd</file> or <file>/etc/group</file> (using
4542 <prgn>adduser</prgn> if it has this facility) if
4543 necessary. Packages which are likely to require
4544 further allocations should have a "hole" left after
4545 them in the allocation, to give them room to
4550 <tag>65000-65533:</tag>
4558 User <tt>nobody</tt>. The corresponding gid refers
4559 to the group <tt>nogroup</tt>.
4566 <tt>(uid_t)(-1) == (gid_t)(-1)</tt> <em>must
4567 not</em> be used, because it is the error return
4576 <sect id="sysvinit">
4577 <heading>System run levels and <file>init.d</file> scripts</heading>
4579 <sect1 id="/etc/init.d">
4580 <heading>Introduction</heading>
4583 The <file>/etc/init.d</file> directory contains the scripts
4584 executed by <prgn>init</prgn> at boot time and when the
4585 init state (or "runlevel") is changed (see <manref
4586 name="init" section="8">).
4590 There are at least two different, yet functionally
4591 equivalent, ways of handling these scripts. For the sake
4592 of simplicity, this document describes only the symbolic
4593 link method. However, it must not be assumed by maintainer
4594 scripts that this method is being used, and any automated
4595 manipulation of the various runlevel behaviours by
4596 maintainer scripts must be performed using
4597 <prgn>update-rc.d</prgn> as described below and not by
4598 manually installing or removing symlinks. For information
4599 on the implementation details of the other method,
4600 implemented in the <tt>file-rc</tt> package, please refer
4601 to the documentation of that package.
4605 These scripts are referenced by symbolic links in the
4606 <file>/etc/rc<var>n</var>.d</file> directories. When changing
4607 runlevels, <prgn>init</prgn> looks in the directory
4608 <file>/etc/rc<var>n</var>.d</file> for the scripts it should
4609 execute, where <tt><var>n</var></tt> is the runlevel that
4610 is being changed to, or <tt>S</tt> for the boot-up
4615 The names of the links all have the form
4616 <file>S<var>mm</var><var>script</var></file> or
4617 <file>K<var>mm</var><var>script</var></file> where
4618 <var>mm</var> is a two-digit number and <var>script</var>
4619 is the name of the script (this should be the same as the
4620 name of the actual script in <file>/etc/init.d</file>).
4624 When <prgn>init</prgn> changes runlevel first the targets
4625 of the links whose names start with a <tt>K</tt> are
4626 executed, each with the single argument <tt>stop</tt>,
4627 followed by the scripts prefixed with an <tt>S</tt>, each
4628 with the single argument <tt>start</tt>. (The links are
4629 those in the <file>/etc/rc<var>n</var>.d</file> directory
4630 corresponding to the new runlevel.) The <tt>K</tt> links
4631 are responsible for killing services and the <tt>S</tt>
4632 link for starting services upon entering the runlevel.
4636 For example, if we are changing from runlevel 2 to
4637 runlevel 3, init will first execute all of the <tt>K</tt>
4638 prefixed scripts it finds in <file>/etc/rc3.d</file>, and then
4639 all of the <tt>S</tt> prefixed scripts in that directory.
4640 The links starting with <tt>K</tt> will cause the
4641 referred-to file to be executed with an argument of
4642 <tt>stop</tt>, and the <tt>S</tt> links with an argument
4647 The two-digit number <var>mm</var> is used to determine
4648 the order in which to run the scripts: low-numbered links
4649 have their scripts run first. For example, the
4650 <tt>K20</tt> scripts will be executed before the
4651 <tt>K30</tt> scripts. This is used when a certain service
4652 must be started before another. For example, the name
4653 server <prgn>bind</prgn> might need to be started before
4654 the news server <prgn>inn</prgn> so that <prgn>inn</prgn>
4655 can set up its access lists. In this case, the script
4656 that starts <prgn>bind</prgn> would have a lower number
4657 than the script that starts <prgn>inn</prgn> so that it
4659 <example compact="compact">
4666 The two runlevels 0 (halt) and 6 (reboot) are slightly
4667 different. In these runlevels, the links with an
4668 <tt>S</tt> prefix are still called after those with a
4669 <tt>K</tt> prefix, but they too are called with the single
4670 argument <tt>stop</tt>.
4674 Also, if the script name ends <tt>.sh</tt>, the script
4675 will be sourced in runlevel <tt>S</tt> rather that being
4676 run in a forked subprocess, but will be explicitly run by
4677 <prgn>sh</prgn> in all other runlevels.
4682 <heading>Writing the scripts</heading>
4685 Packages that include daemons for system services should
4686 place scripts in <file>/etc/init.d</file> to start or stop
4687 services at boot time or during a change of runlevel.
4688 These scripts should be named
4689 <file>/etc/init.d/<var>package</var></file>, and they should
4690 accept one argument, saying what to do:
4693 <tag><tt>start</tt></tag>
4694 <item>start the service,</item>
4696 <tag><tt>stop</tt></tag>
4697 <item>stop the service,</item>
4699 <tag><tt>restart</tt></tag>
4700 <item>stop and restart the service if it's already running,
4701 otherwise start the service</item>
4703 <tag><tt>reload</tt></tag>
4704 <item><p>cause the configuration of the service to be
4705 reloaded without actually stopping and restarting
4708 <tag><tt>force-reload</tt></tag>
4709 <item>cause the configuration to be reloaded if the
4710 service supports this, otherwise restart the
4714 The <tt>start</tt>, <tt>stop</tt>, <tt>restart</tt>, and
4715 <tt>force-reload</tt> options should be supported by all
4716 scripts in <file>/etc/init.d</file>, the <tt>reload</tt>
4721 The <file>init.d</file> scripts should ensure that they will
4722 behave sensibly if invoked with <tt>start</tt> when the
4723 service is already running, or with <tt>stop</tt> when it
4724 isn't, and that they don't kill unfortunately-named user
4725 processes. The best way to achieve this is usually to use
4726 <prgn>start-stop-daemon</prgn>.
4730 If a service reloads its configuration automatically (as
4731 in the case of <prgn>cron</prgn>, for example), the
4732 <tt>reload</tt> option of the <file>init.d</file> script
4733 should behave as if the configuration has been reloaded
4738 The <file>/etc/init.d</file> scripts must be treated as
4739 configuration files, either (if they are present in the
4740 package, that is, in the .deb file) by marking them as
4741 <tt>conffile</tt>s, or, (if they do not exist in the .deb)
4742 by managing them correctly in the maintainer scripts (see
4743 <ref id="config-files">). This is important since we want
4744 to give the local system administrator the chance to adapt
4745 the scripts to the local system, e.g., to disable a
4746 service without de-installing the package, or to specify
4747 some special command line options when starting a service,
4748 while making sure her changes aren't lost during the next
4753 These scripts should not fail obscurely when the
4754 configuration files remain but the package has been
4755 removed, as configuration files remain on the system after
4756 the package has been removed. Only when <prgn>dpkg</prgn>
4757 is executed with the <tt>--purge</tt> option will
4758 configuration files be removed. In particular, as the
4759 <file>/etc/init.d/<var>package</var></file> script itself is
4760 usually a <tt>conffile</tt>, it will remain on the system
4761 if the package is removed but not purged. Therefore, you
4762 should include a <tt>test</tt> statement at the top of the
4764 <example compact="compact">
4765 test -f <var>program-executed-later-in-script</var> || exit 0
4770 Often there are some variables in the <file>init.d</file>
4771 scripts whose values control the behaviour of the scripts,
4772 and which a system administrator is likely to want to
4773 change. As the scripts themselves are frequently
4774 <tt>conffile</tt>s, modifying them requires that the
4775 administrator merge in their changes each time the package
4776 is upgraded and the <tt>conffile</tt> changes. To ease
4777 the burden on the system administrator, such configurable
4778 values should not be placed directly in the script.
4779 Instead, they should be placed in a file in
4780 <file>/etc/default</file>, which typically will have the same
4781 base name as the <file>init.d</file> script. This extra file
4782 should be sourced by the script when the script runs. It
4783 must contain only variable settings and comments in POSIX
4784 <prgn>sh</prgn> format. It may either be a
4785 <tt>conffile</tt> or a configuration file maintained by
4786 the package maintainer scripts. See <ref id="config-files">
4791 To ensure that vital configurable values are always
4792 available, the <file>init.d</file> script should set default
4793 values for each of the shell variables it uses, either
4794 before sourcing the <file>/etc/default/</file> file or
4795 afterwards using something like the <tt>:
4796 ${VAR:=default}</tt> syntax. Also, the <file>init.d</file>
4797 script must behave sensibly and not fail if the
4798 <file>/etc/default</file> file is deleted.
4803 <heading>Interfacing with the initscript system</heading>
4806 Maintainers should use the abstraction layer provided by
4807 the <prgn>update-rc.d</prgn> and <prgn>invoke-rc.d</prgn>
4808 programs to deal with initscripts in their packages'
4809 scripts such as <prgn>postinst</prgn>, <prgn>prerm</prgn>
4810 and <prgn>postrm</prgn>.
4814 Directly managing the /etc/rc?.d links and directly
4815 invoking the <file>/etc/init.d/</file> initscripts should
4816 be done only by packages providing the initscript
4817 subsystem (such as <prgn>sysvinit</prgn> and
4818 <prgn>file-rc</prgn>).
4822 <heading>Managing the links</heading>
4825 The program <prgn>update-rc.d</prgn> is provided for
4826 package maintainers to arrange for the proper creation and
4827 removal of <file>/etc/rc<var>n</var>.d</file> symbolic links,
4828 or their functional equivalent if another method is being
4829 used. This may be used by maintainers in their packages'
4830 <prgn>postinst</prgn> and <prgn>postrm</prgn> scripts.
4834 You must not include any <file>/etc/rc<var>n</var>.d</file>
4835 symbolic links in the actual archive or manually create or
4836 remove the symbolic links in maintainer scripts; you must
4837 use the <prgn>update-rc.d</prgn> program instead. (The
4838 former will fail if an alternative method of maintaining
4839 runlevel information is being used.) You must not include
4840 the <file>/etc/rc<var>n</var>.d</file> directories themselves
4841 in the archive either. (Only the <tt>sysvinit</tt>
4846 By default <prgn>update-rc.d</prgn> will start services in
4847 each of the multi-user state runlevels (2, 3, 4, and 5)
4848 and stop them in the halt runlevel (0), the single-user
4849 runlevel (1) and the reboot runlevel (6). The system
4850 administrator will have the opportunity to customize
4851 runlevels by simply adding, moving, or removing the
4852 symbolic links in <file>/etc/rc<var>n</var>.d</file> if
4853 symbolic links are being used, or by modifying
4854 <file>/etc/runlevel.conf</file> if the <tt>file-rc</tt> method
4859 To get the default behavior for your package, put in your
4860 <prgn>postinst</prgn> script
4861 <example compact="compact">
4862 update-rc.d <var>package</var> defaults
4864 and in your <prgn>postrm</prgn>
4865 <example compact="compact">
4866 if [ "$1" = purge ]; then
4867 update-rc.d <var>package</var> remove
4869 </example>. Note that if your package changes runlevels
4870 or priority, you may have to remove and recreate the links,
4871 since otherwise the old links may persist. Refer to the
4872 documentation of <prgn>update-rc.d</prgn>.
4876 This will use a default sequence number of 20. If it does
4877 not matter when or in which order the <file>init.d</file>
4878 script is run, use this default. If it does, then you
4879 should talk to the maintainer of the <prgn>sysvinit</prgn>
4880 package or post to <tt>debian-devel</tt>, and they will
4881 help you choose a number.
4885 For more information about using <tt>update-rc.d</tt>,
4886 please consult its manpage <manref name="update-rc.d"
4892 <heading>Running initscripts</heading>
4894 The program <prgn>invoke-rc.d</prgn> is provided to make
4895 it easier for package maintainers to properly invoke an
4896 initscript, obeying runlevel and other locally-defined
4897 constraints that might limit a package's right to start,
4898 stop and otherwise manage services. This program may be
4899 used by maintainers in their packages' scripts.
4903 The use of <prgn>invoke-rc.d</prgn> to invoke the
4904 <file>/etc/init.d/*</file> initscripts is strongly
4905 recommended<footnote>
4906 In the future, the use of invoke-rc.d to invoke
4907 initscripts shall be made mandatory. Maintainers are
4908 advised to switch to invoke-rc.d as soon as
4910 </footnote>, instead of calling them directly.
4914 By default, <prgn>invoke-rc.d</prgn> will pass any
4915 action requests (start, stop, reload, restart...) to the
4916 <file>/etc/init.d</file> script, filtering out requests
4917 to start or restart a service out of its intended
4922 Most packages will simply need to change:
4923 <example compact="compact">/etc/init.d/<package>
4924 <action></example> in their <prgn>postinst</prgn>
4925 and <prgn>prerm</prgn> scripts to:
4926 <example compact="compact">
4927 if [ -x /usr/sbin/invoke-rc.d ] ; then
4928 invoke-rc.d <var>package</var> <action>
4930 /etc/init.d/<var>package</var> <action>
4936 A package should register its initscript services using
4937 <prgn>update-rc.d</prgn> before it tries to invoke them
4938 using <prgn>invoke-rc.d</prgn>. Invocation of
4939 unregistered services may fail.
4943 For more information about using
4944 <prgn>invoke-rc.d</prgn>, please consult its manpage
4945 <manref name="invoke-rc.d" section="8">.
4951 <heading>Boot-time initialization</heading>
4954 There used to be another directory, <file>/etc/rc.boot</file>,
4955 which contained scripts which were run once per machine
4956 boot. This has been deprecated in favour of links from
4957 <file>/etc/rcS.d</file> to files in <file>/etc/init.d</file> as
4958 described in <ref id="/etc/init.d">. Packages must not
4959 place files in <file>/etc/rc.boot</file>.
4964 <heading>Example</heading>
4967 The <prgn>bind</prgn> DNS (nameserver) package wants to
4968 make sure that the nameserver is running in multiuser
4969 runlevels, and is properly shut down with the system. It
4970 puts a script in <file>/etc/init.d</file>, naming the script
4971 appropriately <tt>bind</tt>. As you can see, the script
4972 interprets the argument <tt>reload</tt> to send the
4973 nameserver a <tt>HUP</tt> signal (causing it to reload its
4974 configuration); this way the system administrator can say
4975 <tt>/etc/init.d/bind reload</tt> to reload the name
4976 server. The script has one configurable value, which can
4977 be used to pass parameters to the named program at
4978 startup; this value is read from
4979 <file>/etc/default/bind</file> (see below).
4983 <example compact="compact">
4986 # Original version by Robert Leslie
4987 # <rob@mars.org>, edited by iwj and cs
4989 test -x /usr/sbin/named || exit 0
4991 # Source defaults file.
4993 if [ -f /etc/default/bind ]; then
5000 echo -n "Starting domain name service: named"
5001 start-stop-daemon --start --quiet --exec /usr/sbin/named \
5006 echo -n "Stopping domain name service: named"
5007 start-stop-daemon --stop --quiet \
5008 --pidfile /var/run/named.pid --exec /usr/sbin/named
5012 echo -n "Restarting domain name service: named"
5013 start-stop-daemon --stop --quiet \
5014 --pidfile /var/run/named.pid --exec /usr/sbin/named
5015 start-stop-daemon --start --verbose --exec /usr/sbin/named \
5019 force-reload|reload)
5020 echo -n "Reloading configuration of domain name service: named"
5021 start-stop-daemon --stop --signal 1 --quiet \
5022 --pidfile /var/run/named.pid --exec /usr/sbin/named
5026 echo "Usage: /etc/init.d/bind " \
5027 " {start|stop|restart|reload|force-reload}" >&2
5037 Complementing the above init script is a configuration
5038 file <file>/etc/default/bind</file>, which contains
5039 configurable parameters used by the script. This would be
5040 created by the <prgn>postinst</prgn> script if it was not
5041 already present, and removed on purge by the
5042 <prgn>postrm</prgn> script.
5043 <example compact="compact">
5044 # Specified parameters to pass to named. See named(8).
5045 # You may uncomment the following line, and edit to taste.
5051 Another example on which you can base your
5052 <file>/etc/init.d</file> scripts is found in
5053 <file>/etc/init.d/skeleton</file>.
5057 If this package is happy with the default setup from
5058 <prgn>update-rc.d</prgn>, namely an ordering number of 20
5059 and having named running in all runlevels, it can say in
5060 its <prgn>postinst</prgn>:
5061 <example compact="compact">
5062 update-rc.d bind defaults >/dev/null
5064 And in its <prgn>postrm</prgn>, to remove the links when the
5066 <example compact="compact">
5067 if [ "$1" = purge ]; then
5068 update-rc.d bind remove >/dev/null
5076 <heading>Console messages from <file>init.d</file> scripts</heading>
5079 This section describes the formats to be used for messages
5080 written to standard output by the <file>/etc/init.d</file>
5081 scripts. The intent is to improve the consistency of
5082 Debian's startup and shutdown look and feel. For this
5083 reason, please look very carefully at the details. We want
5084 the messages to have the same format in terms of wording,
5085 spaces, punctuation and case of letters.
5089 Here is a list of overall rules that you should use when you
5090 create output messages. They can be useful if you have a
5091 non-standard message that is not covered specifically in the
5098 Every message should fit in one line (fewer than 80
5099 characters), start with a capital letter and end with
5100 a period (<tt>.</tt>) and line feed (<tt>"\n"</tt>).
5104 If you want to express that the computer is working on
5105 something (that is, performing a specific task, not
5106 starting or stopping a program), we use an "ellipsis"
5107 (three dots: <tt>...</tt>). Note that we don't insert
5108 spaces before or after the dots. If the task has been
5109 completed we write <tt>done.</tt> and a line feed.
5113 Design your messages as if the computer is telling you
5114 what he is doing (let him be polite :-), but don't
5115 mention "him" directly. For example, if you think of
5117 <example compact="compact">
5118 I'm starting network daemons: nfsd mountd.
5121 <example compact="compact">
5122 Starting network daemons: nfsd mountd.
5129 There are standard message formats for the following
5130 situations. They should be used by the <tt>init.d</tt>
5137 <p>When daemons are started</p>
5140 If your script starts one or more daemons, the output
5141 should look like this (a single line, no leading
5143 <example compact="compact">
5144 Starting <var>description</var>: <var>daemon-1</var> ... <var>daemon-n</var>.
5146 The <var>description</var> should describe the
5147 subsystem the daemon or set of daemons are part of,
5148 while <var>daemon-1</var> up to <var>daemon-n</var>
5149 denote each daemon's name (typically the file name of
5154 For example, the output of <file>/etc/init.d/lpd</file>
5156 <example compact="compact">
5157 Starting printer spooler: lpd.
5162 This can be achieved by saying
5163 <example compact="compact">
5164 echo -n "Starting printer spooler: lpd"
5165 start-stop-daemon --start --quiet --exec /usr/sbin/lpd
5168 in the script. If you have more than one daemon to
5169 start, you should do the following:
5170 <example compact="compact">
5171 echo -n "Starting remote file system services:"
5172 echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
5173 echo -n " mountd"; start-stop-daemon --start --quiet mountd
5174 echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
5177 This makes it possible for the user to see what takes
5178 so long and when the final daemon has been started.
5179 You should be careful where to put spaces: in the
5180 example above the system administrator can easily
5181 comment out a line if he don't wants to start a
5182 specific daemon, while the displayed message still
5188 <p>When a system parameter is being set</p>
5191 If you have to set up different system parameters
5192 during the system boot, you should use this format:
5193 <example compact="compact">
5194 Setting <var>parameter</var> to "<var>value</var>".
5199 You can use a statement such as the following to get
5201 <example compact="compact">
5202 echo "Setting DNS domainname to \"$domainname\"."
5207 Note that the same symbol (<tt>"</tt>) is used for the left
5208 and right quotation marks. A grave accent (<tt>`</tt>) is
5209 not a quote character; neither is an apostrophe
5215 <p>When a daemon is stopped or restarted</p>
5218 When you stop or restart a daemon, you should issue a
5219 message identical to the startup message, except that
5220 <tt>Starting</tt> is replaced with <tt>Stopping</tt>
5221 or <tt>Restarting</tt> respectively.
5225 For example, stopping the printer daemon will like
5227 <example compact="compact">
5228 Stopping printer spooler: lpd.
5234 <p>When something is executed</p>
5237 There are several examples where you have to run a
5238 program at system startup or shutdown to perform a
5239 specific task, for example, setting the system's clock
5240 using <prgn>netdate</prgn> or killing all processes
5241 when the system shuts down. Your message should look
5243 <example compact="compact">
5244 Doing something very useful...done.
5246 You should print the <tt>done.</tt> immediately after
5247 the job has been completed, so that the user is
5248 informed why she has to wait. You can get this
5250 <example compact="compact">
5251 echo -n "Doing something very useful..."
5260 <p>When the configuration is reloaded</p>
5263 When a daemon is forced to reload its configuration
5264 files you should use the following format:
5265 <example compact="compact">
5266 Reloading <var>description</var> configuration...done.
5268 where <var>description</var> is the same as in the
5269 daemon starting message.
5277 <heading>Cron jobs</heading>
5280 Packages must not modify the configuration file
5281 <file>/etc/crontab</file>, and they must not modify the files in
5282 <file>/var/spool/cron/crontabs</file>.</p>
5285 If a package wants to install a job that has to be executed
5286 via cron, it should place a file with the name of the
5287 package in one or more of the following directories:
5288 <example compact="compact">
5293 As these directory names imply, the files within them are
5294 executed on a daily, weekly, or monthly basis,
5295 respectively. The exact times are listed in
5296 <file>/etc/crontab</file>.</p>
5299 All files installed in any of these directories must be
5300 scripts (e.g., shell scripts or Perl scripts) so that they
5301 can easily be modified by the local system administrator.
5302 In addition, they should be treated as configuration
5307 If a certain job has to be executed more frequently than
5308 daily, the package should install a file
5309 <file>/etc/cron.d/<var>package</var></file>. This file uses the
5310 same syntax as <file>/etc/crontab</file> and is processed by
5311 <prgn>cron</prgn> automatically. The file must also be
5312 treated as a configuration file. (Note that entries in the
5313 <file>/etc/cron.d</file> directory are not handled by
5314 <prgn>anacron</prgn>. Thus, you should only use this
5315 directory for jobs which may be skipped if the system is not
5319 The scripts or crontab entries in these directories should
5320 check if all necessary programs are installed before they
5321 try to execute them. Otherwise, problems will arise when a
5322 package was removed but not purged since configuration files
5323 are kept on the system in this situation.</p>
5327 <heading>Menus</heading>
5330 The Debian <tt>menu</tt> package provides a standard
5331 interface between packages providing applications and
5332 documents, and <em>menu programs</em> (either X window
5333 managers or text-based menu programs such as
5334 <prgn>pdmenu</prgn>).
5338 All packages that provide applications that need not be
5339 passed any special command line arguments for normal
5340 operation should register a menu entry for those
5341 applications, so that users of the <tt>menu</tt> package
5342 will automatically get menu entries in their window
5343 managers, as well in shells like <tt>pdmenu</tt>.
5347 Menu entries should follow the current menu policy.
5351 The menu policy can be found in the <tt>menu-policy</tt>
5352 files in the <tt>debian-policy</tt> package.
5353 They are also available from the Debian web mirrors at
5354 <tt><url name="/doc/packaging-manuals/menu-policy/"
5355 id="http://www.debian.org/doc/packaging-manuals/menu-policy/"></tt>
5356 and from the Debian archive mirrors at
5357 <tt><url name="/doc/package-developer/menu-policy.txt.gz"
5358 id="http://ftp.debian.org/debian/doc/package-developer/menu-policy.txt.gz"></tt>.
5362 Please also refer to the <em>Debian Menu System</em>
5363 documentation that comes with the <tt>menu</tt> package for
5364 information about how to register your applications and web
5370 <heading>Multimedia handlers</heading>
5373 MIME (Multipurpose Internet Mail Extensions, RFCs 2045-2049)
5374 is a mechanism for encoding files and data streams and
5375 providing meta-information about them, in particular their
5376 type (e.g. audio or video) and format (e.g. PNG, HTML,
5381 Registration of MIME type handlers allows programs like mail
5382 user agents and web browsers to to invoke these handlers to
5383 view, edit or display MIME types they don't support
5388 Packages which provide the ability to view/show/play,
5389 compose, edit or print MIME types should register themselves
5390 as such following the current MIME support policy.
5394 The MIME support policy can be found in the <tt>mime-policy</tt>
5395 files in the <tt>debian-policy</tt> package.
5396 They are also available from the Debian web mirrors at
5397 <tt><url name="/doc/packaging-manuals/mime-policy/"
5398 id="http://www.debian.org/doc/packaging-manuals/mime-policy/"></tt>
5399 and from the Debian archive mirrors at
5400 <tt><url name="/doc/package-developer/mime-policy.txt.gz"
5401 id="http://ftp.debian.org/debian/doc/package-developer/mime-policy.txt.gz"></tt>.
5407 <heading>Keyboard configuration</heading>
5410 To achieve a consistent keyboard configuration so that all
5411 applications interpret a keyboard event the same way, all
5412 programs in the Debian distribution must be configured to
5413 comply with the following guidelines.
5417 The following keys must have the specified interpretations:
5420 <tag><tt><--</tt></tag>
5421 <item>delete the character to the left of the cursor</item>
5423 <tag><tt>Delete</tt></tag>
5424 <item>delete the character to the right of the cursor</item>
5426 <tag><tt>Control+H</tt></tag>
5427 <item>emacs: the help prefix</item>
5430 The interpretation of any keyboard events should be
5431 independent of the terminal that is used, be it a virtual
5432 console, an X terminal emulator, an rlogin/telnet session,
5437 The following list explains how the different programs
5438 should be set up to achieve this:
5444 <tt><--</tt> generates <tt>KB_BackSpace</tt> in X.
5448 <tt>Delete</tt> generates <tt>KB_Delete</tt> in X.
5452 X translations are set up to make
5453 <tt>KB_Backspace</tt> generate ASCII DEL, and to make
5454 <tt>KB_Delete</tt> generate <tt>ESC [ 3 ~</tt> (this
5455 is the vt220 escape code for the "delete character"
5456 key). This must be done by loading the X resources
5457 using <prgn>xrdb</prgn> on all local X displays, not
5458 using the application defaults, so that the
5459 translation resources used correspond to the
5460 <prgn>xmodmap</prgn> settings.
5464 The Linux console is configured to make
5465 <tt><--</tt> generate DEL, and <tt>Delete</tt>
5466 generate <tt>ESC [ 3 ~</tt>.
5470 X applications are configured so that <tt><</tt>
5471 deletes left, and <tt>Delete</tt> deletes right. Motif
5472 applications already work like this.
5476 Terminals should have <tt>stty erase ^?</tt> .
5480 The <tt>xterm</tt> terminfo entry should have <tt>ESC
5481 [ 3 ~</tt> for <tt>kdch1</tt>, just as for
5482 <tt>TERM=linux</tt> and <tt>TERM=vt220</tt>.
5486 Emacs is programmed to map <tt>KB_Backspace</tt> or
5487 the <tt>stty erase</tt> character to
5488 <tt>delete-backward-char</tt>, and <tt>KB_Delete</tt>
5489 or <tt>kdch1</tt> to <tt>delete-forward-char</tt>, and
5490 <tt>^H</tt> to <tt>help</tt> as always.
5494 Other applications use the <tt>stty erase</tt>
5495 character and <tt>kdch1</tt> for the two delete keys,
5496 with ASCII DEL being "delete previous character" and
5497 <tt>kdch1</tt> being "delete character under
5505 This will solve the problem except for the following
5512 Some terminals have a <tt><--</tt> key that cannot
5513 be made to produce anything except <tt>^H</tt>. On
5514 these terminals Emacs help will be unavailable on
5515 <tt>^H</tt> (assuming that the <tt>stty erase</tt>
5516 character takes precedence in Emacs, and has been set
5517 correctly). <tt>M-x help</tt> or <tt>F1</tt> (if
5518 available) can be used instead.
5522 Some operating systems use <tt>^H</tt> for <tt>stty
5523 erase</tt>. However, modern telnet versions and all
5524 rlogin versions propagate <tt>stty</tt> settings, and
5525 almost all UNIX versions honour <tt>stty erase</tt>.
5526 Where the <tt>stty</tt> settings are not propagated
5527 correctly, things can be made to work by using
5528 <tt>stty</tt> manually.
5532 Some systems (including previous Debian versions) use
5533 <prgn>xmodmap</prgn> to arrange for both
5534 <tt><--</tt> and <tt>Delete</tt> to generate
5535 <tt>KB_Delete</tt>. We can change the behavior of
5536 their X clients using the same X resources that we use
5537 to do it for our own clients, or configure our clients
5538 using their resources when things are the other way
5539 around. On displays configured like this
5540 <tt>Delete</tt> will not work, but <tt><--</tt>
5545 Some operating systems have different <tt>kdch1</tt>
5546 settings in their <tt>terminfo</tt> database for
5547 <tt>xterm</tt> and others. On these systems the
5548 <tt>Delete</tt> key will not work correctly when you
5549 log in from a system conforming to our policy, but
5550 <tt><--</tt> will.
5557 <heading>Environment variables</heading>
5560 A program must not depend on environment variables to get
5561 reasonable defaults. (That's because these environment
5562 variables would have to be set in a system-wide
5563 configuration file like <file>/etc/profile</file>, which is not
5564 supported by all shells.)
5568 If a program usually depends on environment variables for its
5569 configuration, the program should be changed to fall back to
5570 a reasonable default configuration if these environment
5571 variables are not present. If this cannot be done easily
5572 (e.g., if the source code of a non-free program is not
5573 available), the program must be replaced by a small
5574 "wrapper" shell script which sets the environment variables
5575 if they are not already defined, and calls the original program.
5579 Here is an example of a wrapper script for this purpose:
5581 <example compact="compact">
5583 BAR=${BAR:-/var/lib/fubar}
5585 exec /usr/lib/foo/foo "$@"
5590 Furthermore, as <file>/etc/profile</file> is a configuration
5591 file of the <prgn>base-files</prgn> package, other packages must not
5592 put any environment variables or other commands into that
5601 <heading>Files</heading>
5604 <heading>Binaries</heading>
5607 Two different packages must not install programs with
5608 different functionality but with the same filenames. (The
5609 case of two programs having the same functionality but
5610 different implementations is handled via "alternatives" or
5611 the "Conflicts" mechanism. See <ref id="maintscripts"> and
5612 <ref id="conflicts"> respectively.) If this case happens,
5613 one of the programs must be renamed. The maintainers should
5614 report this to the <tt>debian-devel</tt> mailing list and
5615 try to find a consensus about which program will have to be
5616 renamed. If a consensus cannot be reached, <em>both</em>
5617 programs must be renamed.
5621 By default, when a package is being built, any binaries
5622 created should include debugging information, as well as
5623 being compiled with optimization. You should also turn on
5624 as many reasonable compilation warnings as possible; this
5625 makes life easier for porters, who can then look at build
5626 logs for possible problems. For the C programming language,
5627 this means the following compilation parameters should be
5629 <example compact="compact">
5631 CFLAGS = -O2 -g -Wall # sane warning options vary between programs
5633 install -s # (or use strip on the files in debian/tmp)
5638 Note that by default all installed binaries should be stripped,
5639 either by using the <tt>-s</tt> flag to
5640 <prgn>install</prgn>, or by calling <prgn>strip</prgn> on
5641 the binaries after they have been copied into
5642 <file>debian/tmp</file> but before the tree is made into a
5647 Although binaries in the build tree should be compiled with
5648 debugging information by default, it can often be difficult
5649 to debug programs if they are also subjected to compiler
5650 optimization. For this reason, it is recommended to support
5651 the standardized environment
5652 variable <tt>DEB_BUILD_OPTIONS</tt>. This variable can
5653 contain several flags to change how a package is compiled
5661 The presence of this string means that the package
5662 should be complied with a minimum of optimization.
5663 For C programs, it is best to add <tt>-O0</tt>
5664 to <tt>CFLAGS</tt> (although this is usually the
5665 default). Some programs might fail to build or run at
5666 this level of optimization; it may be necessary to
5667 use <tt>-O1</tt>, for example.
5671 This string means that the debugging symbols should
5672 not be stripped from the binary during installation,
5673 so that debugging information may be included in the package.
5679 The following makefile snippet is an example of how one may
5680 implement the build options; you will probably have to
5681 massage this example in order to make it work for your
5683 <example compact="compact">
5686 INSTALL_FILE = $(INSTALL) -p -o root -g root -m 644
5687 INSTALL_PROGRAM = $(INSTALL) -p -o root -g root -m 755
5688 INSTALL_SCRIPT = $(INSTALL) -p -o root -g root -m 755
5689 INSTALL_DIR = $(INSTALL) -p -d -o root -g root -m 755
5691 ifneq (,$(findstring noopt,$(DEB_BUILD_OPTIONS)))
5696 ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS)))
5697 INSTALL_PROGRAM += -s
5703 It is up to the package maintainer to decide what
5704 compilation options are best for the package. Certain
5705 binaries (such as computationally-intensive programs) will
5706 function better with certain flags (<tt>-O3</tt>, for
5707 example); feel free to use them. Please use good judgment
5708 here. Don't use flags for the sake of it; only use them
5709 if there is good reason to do so. Feel free to override
5710 the upstream author's ideas about which compilation
5711 options are best: they are often inappropriate for our
5717 <sect id="libraries">
5718 <heading>Libraries</heading>
5721 The shared version of a library must be compiled with
5722 <tt>-fPIC</tt>, and the static version must not be. In other
5723 words, each source unit (<tt>*.c</tt>, for example, for C files)
5724 will need to be compiled twice.
5728 You must specify the gcc option <tt>-D_REENTRANT</tt>
5729 when building a library (either static or shared) to make
5730 the library compatible with LinuxThreads.
5734 All installed shared libraries should be stripped with
5735 <example compact="compact">
5736 strip --strip-unneeded <var>your-lib</var>
5738 (The option <tt>--strip-unneeded</tt> makes
5739 <prgn>strip</prgn> remove only the symbols which aren't
5740 needed for relocation processing.) Shared libraries can
5741 function perfectly well when stripped, since the symbols for
5742 dynamic linking are in a separate part of the ELF object
5744 You might also want to use the options
5745 <tt>--remove-section=.comment</tt> and
5746 <tt>--remove-section=.note</tt> on both shared libraries
5747 and executables, and <tt>--strip-debug</tt> on static
5753 Note that under some circumstances it may be useful to
5754 install a shared library unstripped, for example when
5755 building a separate package to support debugging.
5759 Shared object files (often <file>.so</file> files) that are not
5760 public libraries, that is, they are not meant to be linked
5761 to by third party executables (binaries of other packages),
5762 should be installed in subdirectories of the
5763 <file>/usr/lib</file> directory. Such files are exempt from the
5764 rules that govern ordinary shared libraries, except that
5765 they must not be installed executable and should be
5767 A common example are the so-called "plug-ins",
5768 internal shared objects that are dynamically loaded by
5769 programs using <manref name="dlopen" section="3">.
5774 Packages containing shared libraries that may be linked to
5775 by other packages' binaries, but which for some
5776 <em>compelling</em> reason can not be installed in
5777 <file>/usr/lib</file> directory, may install the shared library
5778 files in subdirectories of the <file>/usr/lib</file> directory,
5779 in which case they should arrange to add that directory in
5780 <file>/etc/ld.so.conf</file> in the package's post-installation
5781 script, and remove it in the package's post-removal script.
5785 An ever increasing number of packages are using
5786 <prgn>libtool</prgn> to do their linking. The latest GNU
5787 libtools (>= 1.3a) can take advantage of the metadata in the
5788 installed <prgn>libtool</prgn> archive files (<file>*.la</file>
5789 files). The main advantage of <prgn>libtool</prgn>'s
5790 <file>.la</file> files is that it allows <prgn>libtool</prgn> to
5791 store and subsequently access metadata with respect to the
5792 libraries it builds. <prgn>libtool</prgn> will search for
5793 those files, which contain a lot of useful information about
5794 a library (such as library dependency information for static
5795 linking). Also, they're <em>essential</em> for programs
5796 using <tt>libltdl</tt>.<footnote>
5797 Although <prgn>libtool</prgn> is fully capable of
5798 linking against shared libraries which don't have
5799 <tt>.la</tt> files, as it is a mere shell script it can
5800 add considerably to the build time of a
5801 <prgn>libtool</prgn>-using package if that shell script
5802 has to derive all this information from first principles
5803 for each library every time it is linked. With the
5804 advent of <prgn>libtool</prgn> version 1.4 (and to a
5805 lesser extent <prgn>libtool</prgn> version 1.3), the
5806 <file>.la</file> files also store information about
5807 inter-library dependencies which cannot necessarily be
5808 derived after the <file>.la</file> file is deleted.
5813 Packages that use <prgn>libtool</prgn> to create shared
5814 libraries should include the <file>.la</file> files in the
5815 <tt>-dev</tt> package, unless the package relies on
5816 <tt>libtool</tt>'s <tt>libltdl</tt> library, in which case
5817 the <tt>.la</tt> files must go in the run-time library
5822 You must make sure that you use only released versions of
5823 shared libraries to build your packages; otherwise other
5824 users will not be able to run your binaries
5825 properly. Producing source packages that depend on
5826 unreleased compilers is also usually a bad
5833 <heading>Shared libraries</heading>
5835 This section has moved to <ref id="sharedlibs">.
5841 <heading>Scripts</heading>
5844 All command scripts, including the package maintainer
5845 scripts inside the package and used by <prgn>dpkg</prgn>,
5846 should have a <tt>#!</tt> line naming the shell to be used
5851 In the case of Perl scripts this should be
5852 <tt>#!/usr/bin/perl</tt>.
5856 Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>)
5857 should almost certainly start with <tt>set -e</tt> so that
5858 errors are detected. Every script should use
5859 <tt>set -e</tt> or check the exit status of <em>every</em>
5864 The standard shell interpreter <file>/bin/sh</file> can be a
5865 symbolic link to any POSIX compatible shell, if <tt>echo
5866 -n</tt> does not generate a newline.<footnote>
5867 Debian policy specifies POSIX behavior for
5868 <file>/bin/sh</file>, but <tt>echo -n</tt> has widespread
5869 use in the Linux community (in particular including this
5870 policy, the Linux kernel source, many Debian scripts,
5871 etc.). This <tt>echo -n</tt> mechanism is valid but not
5872 required under POSIX, hence this explicit addition.
5873 Also, rumour has it that this shall be mandated under
5876 Thus, shell scripts specifying <file>/bin/sh</file> as
5877 interpreter should only use POSIX features. If a script
5878 requires non-POSIX features from the shell interpreter, the
5879 appropriate shell must be specified in the first line of the
5880 script (e.g., <tt>#!/bin/bash</tt>) and the package must
5881 depend on the package providing the shell (unless the shell
5882 package is marked "Essential", as in the case of
5887 You may wish to restrict your script to POSIX features when
5888 possible so that it may use <file>/bin/sh</file> as its
5889 interpreter. If your script works with <prgn>dash</prgn>
5890 (originally called <prgn>ash</prgn>), it's probably POSIX
5891 compliant, but if you are in doubt, use
5892 <file>/bin/bash</file>.
5896 Perl scripts should check for errors when making any
5897 system calls, including <tt>open</tt>, <tt>print</tt>,
5898 <tt>close</tt>, <tt>rename</tt> and <tt>system</tt>.
5902 <prgn>csh</prgn> and <prgn>tcsh</prgn> should be avoided as
5903 scripting languages. See <em>Csh Programming Considered
5904 Harmful</em>, one of the <tt>comp.unix.*</tt> FAQs, which
5905 can be found at <url
5906 id="http://language.perl.com/versus/csh.whynot">.<footnote>
5907 It can also be found on
5908 <url id="http://www.cpan.org/doc/FMTEYEWTK/versus/csh.whynot">
5909 or on the ftp site <ftpsite>ftp.cpan.org</ftpsite> as
5910 <ftppath>/pub/perl/CPAN/doc/FMTEYEWTK/versus/csh.whynot</ftppath>.
5912 If an upstream package comes with <prgn>csh</prgn> scripts
5913 then you must make sure that they start with
5914 <tt>#!/bin/csh</tt> and make your package depend on the
5915 <prgn>c-shell</prgn> virtual package.
5919 Any scripts which create files in world-writeable
5920 directories (e.g., in <file>/tmp</file>) must use a
5921 mechanism which will fail if a file with the same name
5926 The Debian base system provides the <prgn>tempfile</prgn>
5927 and <prgn>mktemp</prgn> utilities for use by scripts for
5934 <heading>Symbolic links</heading>
5937 In general, symbolic links within a top-level directory
5938 should be relative, and symbolic links pointing from one
5939 top-level directory into another should be absolute. (A
5940 top-level directory is a sub-directory of the root
5941 directory <file>/</file>.)
5945 In addition, symbolic links should be specified as short as
5946 possible, i.e., link targets like <file>foo/../bar</file> are
5951 Note that when creating a relative link using
5952 <prgn>ln</prgn> it is not necessary for the target of the
5953 link to exist relative to the working directory you're
5954 running <prgn>ln</prgn> from, nor is it necessary to change
5955 directory to the directory where the link is to be made.
5956 Simply include the string that should appear as the target
5957 of the link (this will be a pathname relative to the
5958 directory in which the link resides) as the first argument
5963 For example, in your <prgn>Makefile</prgn> or
5964 <file>debian/rules</file>, you can do things like:
5965 <example compact="compact">
5966 ln -fs gcc $(prefix)/bin/cc
5967 ln -fs gcc debian/tmp/usr/bin/cc
5968 ln -fs ../sbin/sendmail $(prefix)/bin/runq
5969 ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
5974 A symbolic link pointing to a compressed file should always
5975 have the same file extension as the referenced file. (For
5976 example, if a file <file>foo.gz</file> is referenced by a
5977 symbolic link, the filename of the link has to end with
5978 "<file>.gz</file>" too, as in <file>bar.gz</file>.)
5983 <heading>Device files</heading>
5986 Packages must not include device files in the package file
5991 If a package needs any special device files that are not
5992 included in the base system, it must call
5993 <prgn>MAKEDEV</prgn> in the <prgn>postinst</prgn> script,
5994 after notifying the user<footnote>
5995 This notification could be done via a (low-priority)
5996 debconf message, or an echo (printf) statement.
6001 Packages must not remove any device files in the
6002 <prgn>postrm</prgn> or any other script. This is left to the
6003 system administrator.
6007 Debian uses the serial devices
6008 <file>/dev/ttyS*</file>. Programs using the old
6009 <file>/dev/cu*</file> devices should be changed to use
6010 <file>/dev/ttyS*</file>.
6014 <sect id="config-files">
6015 <heading>Configuration files</heading>
6018 <heading>Definitions</heading>
6022 <tag>configuration file</tag>
6024 A file that affects the operation of a program, or
6025 provides site- or host-specific information, or
6026 otherwise customizes the behavior of a program.
6027 Typically, configuration files are intended to be
6028 modified by the system administrator (if needed or
6029 desired) to conform to local policy or to provide
6030 more useful site-specific behavior.
6033 <tag><tt>conffile</tt></tag>
6035 A file listed in a package's <tt>conffiles</tt>
6036 file, and is treated specially by <prgn>dpkg</prgn>
6037 (see <ref id="configdetails">).
6043 The distinction between these two is important; they are
6044 not interchangeable concepts. Almost all
6045 <tt>conffile</tt>s are configuration files, but many
6046 configuration files are not <tt>conffiles</tt>.
6050 Note that a script that embeds configuration information
6051 (such as most of the files in <file>/etc/default</file> and
6052 <file>/etc/cron.{daily,weekly,monthly}</file>) is de-facto a
6053 configuration file and should be treated as such.
6058 <heading>Location</heading>
6061 Any configuration files created or used by your package
6062 must reside in <file>/etc</file>. If there are several,
6063 consider creating a subdirectory of <file>/etc</file>
6064 named after your package.
6068 If your package creates or uses configuration files
6069 outside of <file>/etc</file>, and it is not feasible to modify
6070 the package to use <file>/etc</file> directly, put the files
6071 in <file>/etc</file> and create symbolic links to those files
6072 from the location that the package requires.
6077 <heading>Behavior</heading>
6080 Configuration file handling must conform to the following
6082 <list compact="compact">
6084 local changes must be preserved during a package
6088 configuration files must be preserved when the
6089 package is removed, and only deleted when the
6096 The easy way to achieve this behavior is to make the
6097 configuration file a <tt>conffile</tt>. This is
6098 appropriate only if it is possible to distribute a default
6099 version that will work for most installations, although
6100 some system administrators may choose to modify it. This
6101 implies that the default version will be part of the
6102 package distribution, and must not be modified by the
6103 maintainer scripts during installation (or at any other
6108 In order to ensure that local changes are preserved
6109 correctly, no package may contain or make hard links to
6110 conffiles.<footnote>
6111 Rationale: There are two problems with hard links.
6112 The first is that some editors break the link while
6113 editing one of the files, so that the two files may
6114 unwittingly become unlinked and different. The second
6115 is that <prgn>dpkg</prgn> might break the hard link
6116 while upgrading <tt>conffile</tt>s.
6121 The other way to do it is via the maintainer scripts. In
6122 this case, the configuration file must not be listed as a
6123 <tt>conffile</tt> and must not be part of the package
6124 distribution. If the existence of a file is required for
6125 the package to be sensibly configured it is the
6126 responsibility of the package maintainer to provide
6127 maintainer scripts which correctly create, update and
6128 maintain the file and remove it on purge. (See <ref
6129 id="maintainerscripts"> for more information.) These
6130 scripts must be idempotent (i.e., must work correctly if
6131 <prgn>dpkg</prgn> needs to re-run them due to errors
6132 during installation or removal), must cope with all the
6133 variety of ways <prgn>dpkg</prgn> can call maintainer
6134 scripts, must not overwrite or otherwise mangle the user's
6135 configuration without asking, must not ask unnecessary
6136 questions (particularly during upgrades), and otherwise be
6141 The scripts are not required to configure every possible
6142 option for the package, but only those necessary to get
6143 the package running on a given system. Ideally the
6144 sysadmin should not have to do any configuration other
6145 than that done (semi-)automatically by the
6146 <prgn>postinst</prgn> script.
6150 A common practice is to create a script called
6151 <file><var>package</var>-configure</file> and have the
6152 package's <prgn>postinst</prgn> call it if and only if the
6153 configuration file does not already exist. In certain
6154 cases it is useful for there to be an example or template
6155 file which the maintainer scripts use. Such files should
6156 be in <file>/usr/share/<var>package</var></file> or
6157 <file>/usr/lib/<var>package</var></file> (depending on whether
6158 they are architecture-independent or not). There should
6159 be symbolic links to them from
6160 <file>/usr/share/doc/<var>package</var>/examples</file> if
6161 they are examples, and should be perfectly ordinary
6162 <prgn>dpkg</prgn>-handled files (<em>not</em>
6163 configuration files).
6167 These two styles of configuration file handling must
6168 not be mixed, for that way lies madness:
6169 <prgn>dpkg</prgn> will ask about overwriting the file
6170 every time the package is upgraded.
6175 <heading>Sharing configuration files</heading>
6178 Packages which specify the same file as a
6179 <tt>conffile</tt> must be tagged as <em>conflicting</em>
6180 with each other. (This is an instance of the general rule
6181 about not sharing files. Note that neither alternatives
6182 nor diversions are likely to be appropriate in this case;
6183 in particular, <prgn>dpkg</prgn> does not handle diverted
6184 <tt>conffile</tt>s well.)
6188 The maintainer scripts must not alter a <tt>conffile</tt>
6189 of <em>any</em> package, including the one the scripts
6194 If two or more packages use the same configuration file
6195 and it is reasonable for both to be installed at the same
6196 time, one of these packages must be defined as
6197 <em>owner</em> of the configuration file, i.e., it will be
6198 the package which handles that file as a configuration
6199 file. Other packages that use the configuration file must
6200 depend on the owning package if they require the
6201 configuration file to operate. If the other package will
6202 use the configuration file if present, but is capable of
6203 operating without it, no dependency need be declared.
6207 If it is desirable for two or more related packages to
6208 share a configuration file <em>and</em> for all of the
6209 related packages to be able to modify that configuration
6210 file, then the following should be done:
6211 <enumlist compact="compact">
6213 One of the related packages (the "owning" package)
6214 will manage the configuration file with maintainer
6215 scripts as described in the previous section.
6218 The owning package should also provide a program
6219 that the other packages may use to modify the
6223 The related packages must use the provided program
6224 to make any desired modifications to the
6225 configuration file. They should either depend on
6226 the core package to guarantee that the configuration
6227 modifier program is available or accept gracefully
6228 that they cannot modify the configuration file if it
6229 is not. (This is in addition to the fact that the
6230 configuration file may not even be present in the
6237 Sometimes it's appropriate to create a new package which
6238 provides the basic infrastructure for the other packages
6239 and which manages the shared configuration files. (The
6240 <tt>sgml-base</tt> package is a good example.)
6245 <heading>User configuration files ("dotfiles")</heading>
6248 The files in <file>/etc/skel</file> will automatically be
6249 copied into new user accounts by <prgn>adduser</prgn>.
6250 No other program should reference the files in
6251 <file>/etc/skel</file>.
6255 Therefore, if a program needs a dotfile to exist in
6256 advance in <file>$HOME</file> to work sensibly, that dotfile
6257 should be installed in <file>/etc/skel</file> and treated as a
6262 However, programs that require dotfiles in order to
6263 operate sensibly are a bad thing, unless they do create
6264 the dotfiles themselves automatically.
6268 Furthermore, programs should be configured by the Debian
6269 default installation to behave as closely to the upstream
6270 default behaviour as possible.
6274 Therefore, if a program in a Debian package needs to be
6275 configured in some way in order to operate sensibly, that
6276 should be done using a site-wide configuration file placed
6277 in <file>/etc</file>. Only if the program doesn't support a
6278 site-wide default configuration and the package maintainer
6279 doesn't have time to add it may a default per-user file be
6280 placed in <file>/etc/skel</file>.
6284 <file>/etc/skel</file> should be as empty as we can make it.
6285 This is particularly true because there is no easy (or
6286 necessarily desirable) mechanism for ensuring that the
6287 appropriate dotfiles are copied into the accounts of
6288 existing users when a package is installed.
6294 <heading>Log files</heading>
6296 Log files should usually be named
6297 <file>/var/log/<var>package</var>.log</file>. If you have many
6298 log files, or need a separate directory for permission
6299 reasons (<file>/var/log</file> is writable only by
6300 <file>root</file>), you should usually create a directory named
6301 <file>/var/log/<var>package</var></file> and place your log
6306 Log files must be rotated occasionally so that they don't
6307 grow indefinitely; the best way to do this is to drop a log
6308 rotation configuration file into the directory
6309 <file>/etc/logrotate.d</file> and use the facilities provided by
6310 logrotate.<footnote>
6312 The traditional approach to log files has been to set up
6313 <em>ad hoc</em> log rotation schemes using simple shell
6314 scripts and cron. While this approach is highly
6315 customizable, it requires quite a lot of sysadmin work.
6316 Even though the original Debian system helped a little
6317 by automatically installing a system which can be used
6318 as a template, this was deemed not enough.
6322 The use of <prgn>logrotate</prgn>, a program developed
6323 by Red Hat, is better, as it centralizes log management.
6324 It has both a configuration file
6325 (<file>/etc/logrotate.conf</file>) and a directory where
6326 packages can drop their individual log rotation
6327 configurations (<file>/etc/logrotate.d</file>).
6330 Here is a good example for a logrotate config
6331 file (for more information see <manref name="logrotate"
6333 <example compact="compact">
6334 /var/log/foo/*.log {
6339 /etc/init.d/foo force-reload
6343 This rotates all files under <file>/var/log/foo</file>, saves 12
6344 compressed generations, and forces the daemon to reload its
6345 configuration information after the log rotation.
6349 Log files should be removed when the package is
6350 purged (but not when it is only removed). This should be
6351 done by the <prgn>postrm</prgn> script when it is called
6352 with the argument <tt>purge</tt> (see <ref
6353 id="removedetails">).
6358 <heading>Permissions and owners</heading>
6361 The rules in this section are guidelines for general use.
6362 If necessary you may deviate from the details below.
6363 However, if you do so you must make sure that what is done
6364 is secure and you should try to be as consistent as possible
6365 with the rest of the system. You should probably also
6366 discuss it on <prgn>debian-devel</prgn> first.
6370 Files should be owned by <tt>root.root</tt>, and made
6371 writable only by the owner and universally readable (and
6372 executable, if appropriate), that is mode 644 or 755.
6376 Directories should be mode 755 or (for group-writability)
6377 mode 2775. The ownership of the directory should be
6378 consistent with its mode: if a directory is mode 2775, it
6379 should be owned by the group that needs write access to
6384 Setuid and setgid executables should be mode 4755 or 2755
6385 respectively, and owned by the appropriate user or group.
6386 They should not be made unreadable (modes like 4711 or
6387 2711 or even 4111); doing so achieves no extra security,
6388 because anyone can find the binary in the freely available
6389 Debian package; it is merely inconvenient. For the same
6390 reason you should not restrict read or execute permissions
6391 on non-set-id executables.
6395 Some setuid programs need to be restricted to particular
6396 sets of users, using file permissions. In this case they
6397 should be owned by the uid to which they are set-id, and by
6398 the group which should be allowed to execute them. They
6399 should have mode 4754; again there is no point in making
6400 them unreadable to those users who must not be allowed to
6405 It is possible to arrange that the system administrator can
6406 reconfigure the package to correspond to their local
6407 security policy by changing the permissions on a binary:
6408 they can do this by using <prgn>dpkg-statoverride</prgn>, as
6409 described below.<footnote>
6410 Ordinary files installed by <prgn>dpkg</prgn> (as
6411 opposed to <tt>conffile</tt>s and other similar objects)
6412 normally have their permissions reset to the distributed
6413 permissions when the package is reinstalled. However,
6414 the use of <prgn>dpkg-statoverride</prgn> overrides this
6415 default behaviour. If you use this method, you should
6416 remember to describe <prgn>dpkg-statoverride</prgn> in
6417 the package documentation; being a relatively new
6418 addition to Debian, it is probably not yet well-known.
6420 Another method you should consider is to create a group for
6421 people allowed to use the program(s) and make any setuid
6422 executables executable only by that group.
6426 If you need to create a new user or group for your package
6427 there are two possibilities. Firstly, you may need to
6428 make some files in the binary package be owned by this
6429 user or group, or you may need to compile the user or
6430 group id (rather than just the name) into the binary
6431 (though this latter should be avoided if possible, as in
6432 this case you need a statically allocated id).</p>
6435 If you need a statically allocated id, you must ask for a
6436 user or group id from the <tt>base-passwd</tt> maintainer,
6437 and must not release the package until you have been
6438 allocated one. Once you have been allocated one you must
6439 either make the package depend on a version of the
6440 <tt>base-passwd</tt> package with the id present in
6441 <file>/etc/passwd</file> or <file>/etc/group</file>, or arrange for
6442 your package to create the user or group itself with the
6443 correct id (using <tt>adduser</tt>) in its
6444 <prgn>preinst</prgn> or <prgn>postinst</prgn>. (Doing it in
6445 the <prgn>postinst</prgn> is to be preferred if it is
6446 possible, otherwise a pre-dependency will be needed on the
6447 <tt>adduser</tt> package.)
6451 On the other hand, the program might be able to determine
6452 the uid or gid from the user or group name at runtime, so
6453 that a dynamically allocated id can be used. In this case
6454 you should choose an appropriate user or group name,
6455 discussing this on <prgn>debian-devel</prgn> and checking
6456 with the <package/base-passwd/ maintainer that it is unique and that
6457 they do not wish you to use a statically allocated id
6458 instead. When this has been checked you must arrange for
6459 your package to create the user or group if necessary using
6460 <prgn>adduser</prgn> in the <prgn>preinst</prgn> or
6461 <prgn>postinst</prgn> script (again, the latter is to be
6462 preferred if it is possible).
6466 Note that changing the numeric value of an id associated
6467 with a name is very difficult, and involves searching the
6468 file system for all appropriate files. You need to think
6469 carefully whether a static or dynamic id is required, since
6470 changing your mind later will cause problems.
6473 <sect1><heading>The use of <prgn>dpkg-statoverride</prgn></heading>
6475 This section is not intended as policy, but as a
6476 description of the use of <prgn>dpkg-statoverride</prgn>.
6480 <prgn>dpkg-statoverride</prgn> is a replacement for the
6481 deprecated <tt>suidmanager</tt> package. Packages which
6482 previously used <tt>suidmanager</tt> should have a
6483 <tt>Conflicts: suidmanager (<< 0.50)</tt> entry (or even
6484 <tt>(<< 0.52)</tt>), and calls to <tt>suidregister</tt>
6485 and <tt>suidunregister</tt> should now be simply removed
6486 from the maintainer scripts.
6490 If a system administrator wishes to have a file (or
6491 directory or other such thing) installed with owner and
6492 permissions different from those in the distributed Debian
6493 package, he can use the <prgn>dpkg-statoverride</prgn>
6494 program to instruct <prgn>dpkg</prgn> to use the different
6495 settings every time the file is installed. Thus the
6496 package maintainer should distribute the files with their
6497 normal permissions, and leave it for the system
6498 administrator to make any desired changes. For example, a
6499 daemon which is normally required to be setuid root, but
6500 in certain situations could be used without being setuid,
6501 should be installed setuid in the <tt>.deb</tt>. Then the
6502 local system administrator can change this if they wish.
6503 If there are two standard ways of doing it, the package
6504 maintainer can use <tt>debconf</tt> to find out the
6505 preference, and call <prgn>dpkg-statoverride</prgn> in the
6506 maintainer script if necessary to accommodate the system
6507 administrator's choice.
6511 Given the above, <prgn>dpkg-statoverride</prgn> is
6512 essentially a tool for system administrators and would not
6513 normally be needed in the maintainer scripts. There is
6514 one type of situation, though, where calls to
6515 <prgn>dpkg-statoverride</prgn> would be needed in the
6516 maintainer scripts, and that involves packages which use
6517 dynamically allocated user or group ids. In such a
6518 situation, something like the following idiom can be very
6519 helpful in the package's <prgn>postinst</prgn>, where
6520 <tt>sysuser</tt> is a dynamically allocated id:
6522 for i in /usr/bin/foo /usr/sbin/bar
6524 if ! dpkg-statoverride --list $i >/dev/null
6526 dpkg-statoverride --update --add sysuser root 4755 $i
6530 The corresponding <tt>dpkg-statoverride --remove</tt>
6531 calls can then be made unconditionally when the package is
6538 <chapt id="customized-programs">
6539 <heading>Customized programs</heading>
6541 <sect id="arch-spec">
6542 <heading>Architecture specification strings</heading>
6545 If a program needs to specify an <em>architecture specification
6546 string</em> in some place, the following format should be
6547 used: <var>arch</var>-<var>os</var><footnote>
6548 The following architectures and operating systems are
6549 currently recognised by <prgn>dpkg-archictecture</prgn>.
6550 The architecture, <tt><var>arch</var></tt>, is one of
6551 the following: <tt>alpha</tt>, <tt>arm</tt>,
6552 <tt>hppa</tt>, <tt>i386</tt>, <tt>ia64</tt>,
6553 <tt>m68k</tt>, <tt>mips</tt>, <tt>mipsel</tt>,
6554 <tt>powerpc</tt>, <tt>s390</tt>, <tt>sh</tt>,
6555 <tt>sheb</tt>, <tt>sparc</tt> and <tt>sparc64</tt>. The
6556 operating system, <tt><var>os</var></tt>, is one of:
6557 <tt>linux</tt>, <tt>gnu</tt>, <tt>freebsd</tt> and
6558 <tt>openbsd</tt>. Use of <tt>gnu</tt> in this string is
6559 reserved for the GNU/Hurd operating system.
6564 Note that we don't want to use
6565 <tt><var>arch</var>-debian-linux</tt> to apply to the rule
6566 <tt><var>architecture</var>-<var>vendor</var>-<var>os</var></tt>
6567 since this would make our programs incompatible with other
6568 Linux distributions. We also don't use something like
6569 <tt><var>arch</var>-unknown-linux</tt>, since the
6570 <tt>unknown</tt> does not look very good.
6575 <heading>Daemons</heading>
6578 The configuration files <file>/etc/services</file>,
6579 <file>/etc/protocols</file>, and <file>/etc/rpc</file> are managed
6580 by the <prgn>netbase</prgn> package and must not be modified
6585 If a package requires a new entry in one of these files, the
6586 maintainer should get in contact with the
6587 <prgn>netbase</prgn> maintainer, who will add the entries
6588 and release a new version of the <prgn>netbase</prgn>
6593 The configuration file <file>/etc/inetd.conf</file> must not be
6594 modified by the package's scripts except via the
6595 <prgn>update-inetd</prgn> script or the
6596 <file>DebianNet.pm</file> Perl module. See their documentation
6597 for details on how to add entries.
6601 If a package wants to install an example entry into
6602 <file>/etc/inetd.conf</file>, the entry must be preceded with
6603 exactly one hash character (<tt>#</tt>). Such lines are
6604 treated as "commented out by user" by the
6605 <prgn>update-inetd</prgn> script and are not changed or
6606 activated during package updates.
6611 <heading>Using pseudo-ttys and modifying wtmp, utmp and
6615 Some programs need to create pseudo-ttys. This should be done
6616 using Unix98 ptys if the C library supports it. The resulting
6617 program must not be installed setuid root, unless that
6618 is required for other functionality.
6622 The files <file>/var/run/utmp</file>, <file>/var/log/wtmp</file> and
6623 <file>/var/log/lastlog</file> must be installed writeable by
6624 group <tt>utmp</tt>. Programs which need to modify those
6625 files must be installed setgid <tt>utmp</tt>.
6630 <heading>Editors and pagers</heading>
6633 Some programs have the ability to launch an editor or pager
6634 program to edit or display a text document. Since there are
6635 lots of different editors and pagers available in the Debian
6636 distribution, the system administrator and each user should
6637 have the possibility to choose his/her preferred editor and
6642 In addition, every program should choose a good default
6643 editor/pager if none is selected by the user or system
6648 Thus, every program that launches an editor or pager must
6649 use the EDITOR or PAGER environment variable to determine
6650 the editor or pager the user wishes to use. If these
6651 variables are not set, the programs <file>/usr/bin/editor</file>
6652 and <file>/usr/bin/pager</file> should be used, respectively.
6656 These two files are managed through the <prgn>dpkg</prgn>
6657 "alternatives" mechanism. Thus every package providing an
6658 editor or pager must call the
6659 <prgn>update-alternatives</prgn> script to register these
6664 If it is very hard to adapt a program to make use of the
6665 EDITOR or PAGER variables, that program may be configured to
6666 use <file>/usr/bin/sensible-editor</file> and
6667 <file>/usr/bin/sensible-pager</file> as the editor or pager
6668 program respectively. These are two scripts provided in the
6669 Debian base system that check the EDITOR and PAGER variables
6670 and launch the appropriate program, and fall back to
6671 <file>/usr/bin/editor</file> and <file>/usr/bin/pager</file> if the
6672 variable is not set.
6676 A program may also use the VISUAL environment variable to
6677 determine the user's choice of editor. If it exists, it
6678 should take precedence over EDITOR. This is in fact what
6679 <file>/usr/bin/sensible-editor</file> does.
6683 It is not required for a package to depend on
6684 <tt>editor</tt> and <tt>pager</tt>, nor is it required for a
6685 package to provide such virtual packages.<footnote>
6686 The Debian base system already provides an editor and a
6692 <sect id="web-appl">
6693 <heading>Web servers and applications</heading>
6696 This section describes the locations and URLs that should
6697 be used by all web servers and web applications in the
6704 Cgi-bin executable files are installed in the
6706 <example compact="compact">
6707 /usr/lib/cgi-bin/<var>cgi-bin-name</var>
6709 and should be referred to as
6710 <example compact="compact">
6711 http://localhost/cgi-bin/<var>cgi-bin-name</var>
6716 <p>Access to HTML documents</p>
6719 HTML documents for a package are stored in
6720 <file>/usr/share/doc/<var>package</var></file>
6721 and can be referred to as
6722 <example compact="compact">
6723 http://localhost/doc/<var>package</var>/<var>filename</var>
6728 The web server should restrict access to the document
6729 tree so that only clients on the same host can read
6730 the documents. If the web server does not support such
6731 access controls, then it should not provide access at
6732 all, or ask about providing access during installation.
6737 <p>Web Document Root</p>
6740 Web Applications should try to avoid storing files in
6741 the Web Document Root. Instead they should use the
6742 /usr/share/doc/<var>package</var> directory for
6743 documents and register the Web Application via the
6744 menu package. If access to the web document root is
6745 unavoidable then use
6746 <example compact="compact">
6749 as the Document Root. This might be just a symbolic
6750 link to the location where the system administrator
6751 has put the real document root.
6759 <sect id="mail-transport-agents">
6760 <heading>Mail transport, delivery and user agents</heading>
6763 Debian packages which process electronic mail, whether mail
6764 user agents (MUAs) or mail transport agents (MTAs), must
6765 ensure that they are compatible with the configuration
6766 decisions below. Failure to do this may result in lost
6767 mail, broken <tt>From:</tt> lines, and other serious brain
6772 The mail spool is <file>/var/mail</file> and the interface to
6773 send a mail message is <file>/usr/sbin/sendmail</file> (as per
6774 the FHS). On older systems, the mail spool may be
6775 physically located in <file>/var/spool/mail</file>, but all
6776 access to the mail spool should be via the
6777 <file>/var/mail</file> symlink. The mail spool is part of the
6778 base system and not part of the MTA package.
6782 All Debian MUAs, MTAs, MDAs and other mailbox accessing
6783 programs (such as IMAP daemons) must lock the mailbox in an
6784 NFS-safe way. This means that <tt>fcntl()</tt> locking must
6785 be combined with dot locking. To avoid deadlocks, a program
6786 should use <tt>fcntl()</tt> first and dot locking after
6787 this, or alternatively implement the two locking methods in
6788 a non blocking way<footnote>
6789 If it is not possible to establish both locks, the
6790 system shouldn't wait for the second lock to be
6791 established, but remove the first lock, wait a (random)
6792 time, and start over locking again.
6793 </footnote>. Using the functions <tt>maillock</tt> and
6794 <tt>mailunlock</tt> provided by the
6795 <tt>liblockfile*</tt><footnote>
6797 You will need to depend on <tt>liblockfile1
6798 (>>1.01)</tt> to use these functions.
6800 </footnote> packages is the recommended way to realize this.
6804 Mailboxes are generally mode 660
6805 <tt><var>user</var>.mail</tt> unless the system
6806 administrator has chosen otherwise. A MUA may remove a
6807 mailbox (unless it has nonstandard permissions) in which
6808 case the MTA or another MUA must recreate it if needed.
6809 Mailboxes must be writable by group mail.
6813 The mail spool is 2775 <tt>root.mail</tt>, and MUAs should
6814 be setgid mail to do the locking mentioned above (and
6815 must obviously avoid accessing other users' mailboxes
6816 using this privilege).</p>
6819 <file>/etc/aliases</file> is the source file for the system mail
6820 aliases (e.g., postmaster, usenet, etc.), it is the one
6821 which the sysadmin and <prgn>postinst</prgn> scripts may
6822 edit. After <file>/etc/aliases</file> is edited the program or
6823 human editing it must call <prgn>newaliases</prgn>. All MTA
6824 packages must come with a <prgn>newaliases</prgn> program,
6825 even if it does nothing, but older MTA packages did not do
6826 this so programs should not fail if <prgn>newaliases</prgn>
6827 cannot be found. Note that because of this, all MTA
6828 packages must have <tt>Provides</tt>, <tt>Conflicts</tt> and
6829 <tt>Replaces: mail-transport-agent</tt> control file
6834 The convention of writing <tt>forward to
6835 <var>address</var></tt> in the mailbox itself is not
6836 supported. Use a <tt>.forward</tt> file instead.</p>
6839 The <prgn>rmail</prgn> program used by UUCP
6840 for incoming mail should be <file>/usr/sbin/rmail</file>.
6841 Likewise, <prgn>rsmtp</prgn>, for receiving
6842 batch-SMTP-over-UUCP, should be <file>/usr/sbin/rsmtp</file> if it
6846 If your package needs to know what hostname to use on (for
6847 example) outgoing news and mail messages which are generated
6848 locally, you should use the file <file>/etc/mailname</file>. It
6849 will contain the portion after the username and <tt>@</tt>
6850 (at) sign for email addresses of users on the machine
6851 (followed by a newline).
6855 Such package should check for the existence of this file
6856 when it is being configured. If it exists, it should be
6857 used without comment, although an MTA's configuration script
6858 may wish to prompt the user even if it finds that this file
6859 exists. If the file does not exist, the package should
6860 prompt the user for the value (preferably using
6861 <prgn>debconf</prgn>) and store it in <file>/etc/mailname</file>
6862 as well as using it in the package's configuration. The
6863 prompt should make it clear that the name will not just be
6864 used by that package. For example, in this situation the
6865 <tt>inn</tt> package could say something like:
6866 <example compact="compact">
6867 Please enter the "mail name" of your system. This is the
6868 hostname portion of the address to be shown on outgoing
6869 news and mail messages. The default is
6870 <var>syshostname</var>, your system's host name. Mail
6871 name ["<var>syshostname</var>"]:
6873 where <var>syshostname</var> is the output of <tt>hostname
6879 <heading>News system configuration</heading>
6882 All the configuration files related to the NNTP (news)
6883 servers and clients should be located under
6884 <file>/etc/news</file>.</p>
6887 There are some configuration issues that apply to a number
6888 of news clients and server packages on the machine. These
6892 <tag><file>/etc/news/organization</file></tag>
6894 A string which should appear as the
6895 organization header for all messages posted
6896 by NNTP clients on the machine
6899 <tag><file>/etc/news/server</file></tag>
6901 Contains the FQDN of the upstream NNTP
6902 server, or localhost if the local machine is
6907 Other global files may be added as required for cross-package news
6914 <heading>Programs for the X Window System</heading>
6917 <heading>Providing X support and package priorities</heading>
6920 Programs that can be configured with support for the X
6921 Window System must be configured to do so and must declare
6922 any package dependencies necessary to satisfy their
6923 runtime requirements when using the X Window System. If
6924 such a package is of higher priority than the X packages
6925 on which it depends, it is required that either the
6926 X-specific components be split into a separate package, or
6927 that an alternative version of the package, which includes
6928 X support, be provided, or that the package's priority be
6934 <heading>Packages providing an X server</heading>
6937 Packages that provide an X server that, directly or
6938 indirectly, communicates with real input and display
6939 hardware should declare in their control data that they
6940 provide the virtual package <tt>xserver</tt>.<footnote>
6941 This implements current practice, and provides an
6942 actual policy for usage of the <tt>xserver</tt>
6943 virtual package which appears in the virtual packages
6944 list. In a nutshell, X servers that interface
6945 directly with the display and input hardware or via
6946 another subsystem (e.g., GGI) should provide
6947 <tt>xserver</tt>. Things like <tt>Xvfb</tt>,
6948 <tt>Xnest</tt>, and <tt>Xprt</tt> should not.
6954 <heading>Packages providing a terminal emulator</heading>
6957 Packages that provide a terminal emulator for the X Window
6958 System which meet the criteria listed below should declare
6959 in their control data that they provide the virtual
6960 package <tt>x-terminal-emulator</tt>. They should also
6961 register themselves as an alternative for
6962 <file>/usr/bin/x-terminal-emulator</file>, with a priority of
6967 To be an <tt>x-terminal-emulator</tt>, a program must:
6968 <list compact="compact">
6970 Be able to emulate a DEC VT100 terminal, or a
6971 compatible terminal.
6975 Support the command-line option <tt>-e
6976 <var>command</var></tt>, which creates a new
6977 terminal window<footnote>
6978 "New terminal window" does not necessarily mean
6979 a new top-level X window directly parented by
6980 the window manager; it could, if the terminal
6981 emulator application were so coded, be a new
6982 "view" in a multiple-document interface (MDI).
6984 and runs the specified <var>command</var>,
6985 interpreting the entirity of the rest of the command
6986 line as a command to pass straight to exec, in the
6987 manner that <tt>xterm</tt> does.
6991 Support the command-line option <tt>-T
6992 <var>title</var></tt>, which creates a new terminal
6993 window with the window title <var>title</var>.
7000 <heading>Packages providing a window manager</heading>
7003 Packages that provide a window manager should declare in
7004 their control data that they provide the virtual package
7005 <tt>x-window-manager</tt>. They should also register
7006 themselves as an alternative for
7007 <file>/usr/bin/x-window-manager</file>, with a priority
7008 calculated as follows:
7009 <list compact="compact">
7011 Start with a priority of 20.
7015 If the window manager supports the Debian menu
7016 system, add 20 points if this support is available
7017 in the package's default configuration (i.e., no
7018 configuration files belonging to the system or user
7019 have to be edited to activate the feature); if
7020 configuration files must be modified, add only 10
7025 If the window manager complies with <url
7026 id="http://www.freedesktop.org/standards/wm-spec.html"
7027 name="The Window Manager Specification Project">,
7028 written by the <url id="http://www.freedesktop.org"
7029 name="Free Desktop Group">, add 40 points.
7033 If the window manager permits the X session to be
7034 restarted using a <em>different</em> window manager
7035 (without killing the X server) in its default
7036 configuration, add 10 points; otherwise add none.
7043 <heading>Packages providing fonts</heading>
7046 Packages that provide fonts for the X Window
7048 For the purposes of Debian Policy, a "font for the X
7049 Window System" is one which is accessed via X protocol
7050 requests. Fonts for the Linux console, for PostScript
7051 renderers, or any other purpose, do not fit this
7052 definition. Any tool which makes such fonts available
7053 to the X Window System, however, must abide by this
7056 must do a number of things to ensure that they are both
7057 available without modification of the X or font server
7058 configuration, and that they do not corrupt files used by
7059 other font packages to register information about
7063 Fonts of any type supported by the X Window System
7064 must be in a separate binary package from any
7065 executables, libraries, or documentation (except
7066 that specific to the fonts shipped, such as their
7067 license information). If one or more of the fonts
7068 so packaged are necessary for proper operation of
7069 the package with which they are associated the font
7070 package may be Recommended; if the fonts merely
7071 provide an enhancement, a Suggests relationship may
7072 be used. Packages must not Depend on font
7074 This is because the X server may retrieve fonts
7075 from the local filesystem or over the network
7076 from an X font server; the Debian package system
7077 is empowered to deal only with the local
7083 BDF fonts must be converted to PCF fonts with the
7084 <prgn>bdftopcf</prgn> utility (available in the
7085 <tt>xutils</tt> package, <prgn>gzip</prgn>ped, and
7086 placed in a directory that corresponds to their
7088 <list compact="compact">
7090 100 dpi fonts must be placed in
7091 <file>/usr/X11R6/lib/X11/fonts/100dpi/</file>.
7095 75 dpi fonts must be placed in
7096 <file>/usr/X11R6/lib/X11/fonts/75dpi/</file>.
7100 Character-cell fonts, cursor fonts, and other
7101 low-resolution fonts must be placed in
7102 <file>/usr/X11R6/lib/X11/fonts/misc/</file>.
7108 Speedo fonts must be placed in
7109 <file>/usr/X11R6/lib/X11/fonts/Speedo/</file>.
7113 Type 1 fonts must be placed in
7114 <file>/usr/X11R6/lib/X11/fonts/Type1/</file>. If font
7115 metric files are available, they must be placed here
7120 Subdirectories of <file>/usr/X11R6/lib/X11/fonts/</file>
7121 other than those listed above must be neither
7122 created nor used. (The <file>PEX</file>, <file>CID</file>,
7123 and <file>cyrillic</file> directories are excepted for
7124 historical reasons, but installation of files into
7125 these directories remains discouraged.)
7129 Font packages may, instead of placing files directly
7130 in the X font directories listed above, provide
7131 symbolic links in that font directory pointing to
7132 the files' actual location in the filesystem. Such
7133 a location must comply with the FHS.
7137 Font packages should not contain both 75dpi and
7138 100dpi versions of a font. If both are available,
7139 they should be provided in separate binary packages
7140 with <tt>-75dpi</tt> or <tt>-100dpi</tt> appended to
7141 the names of the packages containing the
7142 corresponding fonts.
7146 Fonts destined for the <file>misc</file> subdirectory
7147 should not be included in the same package as 75dpi
7148 or 100dpi fonts; instead, they should be provided in
7149 a separate package with <tt>-misc</tt> appended to
7154 Font packages must not provide the files
7155 <file>fonts.dir</file>, <file>fonts.alias</file>, or
7156 <file>fonts.scale</file> in a font directory:
7159 <file>fonts.dir</file> files must not be provided at all.
7163 <file>fonts.alias</file> and <file>fonts.scale</file>
7164 files, if needed, should be provided in the
7166 <file>/etc/X11/fonts/<var>fontdir</var>/<var>package</var>.<var>extension</var></file>,
7167 where <var>fontdir</var> is the name of the
7169 <file>/usr/X11R6/lib/X11/fonts/</file> where the
7170 package's corresponding fonts are stored
7171 (e.g., <tt>75dpi</tt> or <tt>misc</tt>),
7172 <var>package</var> is the name of the package
7173 that provides these fonts, and
7174 <var>extension</var> is either <tt>scale</tt>
7175 or <tt>alias</tt>, whichever corresponds to
7182 Font packages must declare a dependency on
7183 <tt>xutils (>> 4.0.3)</tt> in their control
7188 Font packages that provide one or more
7189 <file>fonts.scale</file> files as described above must
7190 invoke <prgn>update-fonts-scale</prgn> on each
7191 directory into which they installed fonts
7192 <em>before</em> invoking
7193 <prgn>update-fonts-dir</prgn> on that directory.
7194 This invocation must occur in both the
7195 <prgn>postinst</prgn> (for all arguments) and
7196 <prgn>postrm</prgn> (for all arguments except
7197 <tt>upgrade</tt>) scripts.
7201 Font packages that provide one or more
7202 <file>fonts.alias</file> files as described above must
7203 invoke <prgn>update-fonts-alias</prgn> on each
7204 directory into which they installed fonts. This
7205 invocation must occur in both the
7206 <prgn>postinst</prgn> (for all arguments) and
7207 <prgn>postrm</prgn> (for all arguments except
7208 <tt>upgrade</tt>) scripts.
7212 Font packages must invoke
7213 <prgn>update-fonts-dir</prgn> on each directory into
7214 which they installed fonts. This invocation must
7215 occur in both the <prgn>postinst</prgn> (for all
7216 arguments) and <prgn>postrm</prgn> (for all
7217 arguments except <tt>upgrade</tt>) scripts.
7221 Font packages must not provide alias names for the
7222 fonts they include which collide with alias names
7223 already in use by fonts already packaged.
7227 Font packages must not provide fonts with the same
7228 XLFD registry name as another font already packaged.
7235 <heading>Application defaults files</heading>
7238 Application defaults files must be installed in the
7239 directory <file>/etc/X11/app-defaults/</file> (use of a
7240 localized subdirectory of <file>/etc/X11/</file> as described
7241 in the <em>X Toolkit Intrinsics - C Language
7242 Interface</em> manual is also permitted). They must be
7243 registered as <tt>conffile</tt>s or handled as
7244 configuration files. Packages must not provide the
7245 directory <file>/usr/X11R6/lib/X11/app-defaults/</file>.
7249 Customization of programs' X resources may also be
7250 supported with the provision of a file with the same name
7251 as that of the package placed in the
7252 <file>/etc/X11/Xresources/</file> directory, which must
7253 registered as a <tt>conffile</tt> or handled as a
7254 configuration file.<footnote>
7255 Note that this mechanism is not the same as using
7256 app-defaults; app-defaults are tied to the client
7257 binary on the local filesystem, whereas X resources
7258 are stored in the X server and affect all connecting
7261 <em>Important:</em> packages that install files into the
7262 <file>/etc/X11/Xresources/</file> directory must conflict with
7263 <tt>xbase (<< 3.3.2.3a-2)</tt>; if this is not done
7264 it is possible for the installing package to destroy a
7265 previously-existing <file>/etc/X11/Xresources</file> file
7266 which had been customized by the system administrator.
7271 <heading>Installation directory issues</heading>
7274 Packages using the X Window System should not be
7275 configured to install files under the <file>/usr/X11R6/</file>
7276 directory unless they use <prgn>imake</prgn>. The
7277 <file>/usr/X11R6/</file> directory hierarchy should be
7278 regarded as deprecated for all packages except the X
7279 Window System itself, and those which use the
7280 <prgn>imake</prgn> program it provides, in which case the
7281 packages may transition out of the <file>/usr/X11R6/</file>
7282 directory at the maintainer's discretion.<footnote>
7283 <prgn>Imake</prgn>-using programs are exempt because,
7284 as long as they are written correctly, the pathnames
7285 they use to locate resources and install themselves
7286 are derived wholly from the X Window System
7287 configuration. Thus, in the event that the X Window
7288 System moves to <file>/usr/X11R7/</file>,
7289 <file>/usr/X12/</file>, or just plain <file>/usr/</file>, all
7290 that is required for these programs is a recompile
7291 against the corresponding X Window System library
7292 development packages.
7297 Programs that use GNU <prgn>autoconf</prgn> and
7298 <prgn>automake</prgn> are usually easily configured at
7299 compile time to use <file>/usr/</file> instead of
7300 <file>/usr/X11R6/</file>, and this should be done whenever
7301 possible. Configuration files for window managers and
7302 display managers should be placed in a subdirectory of
7303 <file>/etc/X11/</file> corresponding to the package name due
7304 to these programs' tight integration with the mechanisms
7305 of the X Window System. Application-level programs should
7306 use the <file>/etc/</file> directory unless otherwise mandated
7311 The installation of files into subdirectories
7312 of <file>/usr/X11R6/include/X11/</file> and
7313 <file>/usr/X11R6/lib/X11/</file> is permitted but discouraged;
7314 package maintainers should determine if subdirectories of
7315 <file>/usr/lib/</file> and <file>/usr/share/</file> can be used
7316 instead. (The use of symbolic links from the
7317 <file>X11R6</file> directories to other FHS-compliant
7318 locations is encouraged if the program is not easily
7319 configured to look elsewhere for its files.)
7323 Packages must not provide or install files into the directories
7324 <file>/usr/bin/X11/</file>, <file>/usr/include/X11/</file> or
7325 <file>/usr/lib/X11/</file>. Files within a package should,
7326 however, make reference to these directories, rather than
7327 their <tt>X11R6</tt>-named counterparts
7328 <file>/usr/X11R6/bin/</file>, <file>/usr/X11R6/include/X11/</file>
7329 and <file>/usr/X11R6/lib/X11/</file>, if the resources being
7330 referred to have not been moved to other FHS-compliant
7336 <heading>The OSF/Motif and OpenMotif libraries</heading>
7339 <em>Programs that require the non-DFSG-compliant OSF/Motif or
7340 OpenMotif libraries</em><footnote>
7341 OSF/Motif and OpenMotif are collectively referred to as
7342 "Motif" in this policy document.
7344 should be compiled against and tested with LessTif (a free
7345 re-implementation of Motif) instead. If the maintainer
7346 judges that the program or programs do not work
7347 sufficiently well with LessTif to be distributed and
7348 supported, but do so when compiled against Motif, then two
7349 versions of the package should be created; one linked
7350 statically against Motif and with <tt>-smotif</tt>
7351 appended to the package name, and one linked dynamically
7352 against Motif and with <tt>-dmotif</tt> appended to the
7357 Both Motif-linked versions are dependent
7358 upon non-DFSG-compliant software and thus cannot be
7359 uploaded to the <em>main</em> distribution; if the
7360 software is itself DFSG-compliant it may be uploaded to
7361 the <em>contrib</em> distribution. While known existing
7362 versions of Motif permit unlimited redistribution of
7363 binaries linked against the library (whether statically or
7364 dynamically), it is the package maintainer's
7365 responsibility to determine whether this is permitted by
7366 the license of the copy of Motif in his or her possession.
7372 <heading>Perl programs and modules</heading>
7375 Perl programs and modules should follow the current Perl policy.
7379 The Perl policy can be found in the <tt>perl-policy</tt>
7380 files in the <tt>debian-policy</tt> package.
7381 They are also available from the Debian web mirrors at
7382 <tt><url name="/doc/packaging-manuals/perl-policy/"
7383 id="http://www.debian.org/doc/packaging-manuals/perl-policy/"></tt>
7384 and from the Debian archive mirrors at
7385 <tt><url name="/doc/package-developer/perl-policy.txt.gz"
7386 id="http://ftp.debian.org/debian/doc/package-developer/perl-policy.txt.gz"></tt>.
7391 <heading>Emacs lisp programs</heading>
7394 Please refer to the "Debian Emacs Policy" for details of how to
7395 package emacs lisp programs.
7399 The Emacs policy is available in
7400 <file>debian-emacs-policy.gz</file> of the
7401 <package>emacsen-common</package> package.
7402 It is also available from the Debian web mirrors at
7403 <tt><url name="/doc/packaging-manuals/debian-emacs-policy"
7404 id="http://www.debian.org/doc/packaging-manuals/debian-emacs-policy"></tt>.
7409 <heading>Games</heading>
7412 The permissions on <file>/var/games</file> are mode 755, owner
7413 <tt>root</tt> and group <tt>root</tt>.
7417 Each game decides on its own security policy.</p>
7420 Games which require protected, privileged access to
7421 high-score files, savegames, etc., may be made
7422 set-<em>group</em>-id (mode 2755) and owned by
7423 <tt>root.games</tt>, and use files and directories with
7424 appropriate permissions (770 <tt>root.games</tt>, for
7425 example). They must not be made
7426 set-<em>user</em>-id, as this causes security problems. (If
7427 an attacker can subvert any set-user-id game they can
7428 overwrite the executable of any other, causing other players
7429 of these games to run a Trojan horse program. With a
7430 set-group-id game the attacker only gets access to less
7431 important game data, and if they can get at the other
7432 players' accounts at all it will take considerably more
7436 Some packages, for example some fortune cookie programs, are
7437 configured by the upstream authors to install with their
7438 data files or other static information made unreadable so
7439 that they can only be accessed through set-id programs
7440 provided. You should not do this in a Debian package: anyone can
7441 download the <file>.deb</file> file and read the data from it,
7442 so there is no point making the files unreadable. Not
7443 making the files unreadable also means that you don't have
7444 to make so many programs set-id, which reduces the risk of a
7448 As described in the FHS, binaries of games should be
7449 installed in the directory <file>/usr/games</file>. This also
7450 applies to games that use the X Window System. Manual pages
7451 for games (X and non-X games) should be installed in
7452 <file>/usr/share/man/man6</file>.</p>
7456 <chapt id="docs"><heading>Documentation</heading>
7460 <heading>Manual pages</heading>
7463 You should install manual pages in <prgn>nroff</prgn> source
7464 form, in appropriate places under <file>/usr/share/man</file>.
7465 You should only use sections 1 to 9 (see the FHS for more
7466 details). You must not install a preformatted "cat page".
7470 Each program, utility, and function should have an
7471 associated manual page included in the same package. It is
7472 suggested that all configuration files also have a manual
7473 page included as well. Manual pages for protocols and other
7474 auxiliary things are optional.
7478 If no manual page is available, this is considered as a bug
7479 and should be reported to the Debian Bug Tracking System (the
7480 maintainer of the package is allowed to write this bug report
7481 themselves, if they so desire). Do not close the bug report
7482 until a proper manpage is available.<footnote>
7483 It is not very hard to write a man page. See the
7484 <url id="http://www.schweikhardt.net/man_page_howto.html"
7485 name="Man-Page-HOWTO">,
7486 <manref name="man" section="7">, the examples
7487 created by <prgn>debmake</prgn> or <prgn>dh_make</prgn>,
7488 the helper programs <prgn>help2man</prgn>, or the
7489 directory <file>/usr/share/doc/man-db/examples</file>.
7494 You may forward a complaint about a missing manpage to the
7495 upstream authors, and mark the bug as forwarded in the
7496 Debian bug tracking system. Even though the GNU Project do
7497 not in general consider the lack of a manpage to be a bug,
7498 we do; if they tell you that they don't consider it a bug
7499 you should leave the bug in our bug tracking system open
7504 Manual pages should be installed compressed using <tt>gzip -9</tt>.
7508 If one manpage needs to be accessible via several names it
7509 is better to use a symbolic link than the <file>.so</file>
7510 feature, but there is no need to fiddle with the relevant
7511 parts of the upstream source to change from <file>.so</file> to
7512 symlinks: don't do it unless it's easy. You should not
7513 create hard links in the manual page directories, nor put
7514 absolute filenames in <file>.so</file> directives. The filename
7515 in a <file>.so</file> in a manpage should be relative to the
7516 base of the manpage tree (usually
7517 <file>/usr/share/man</file>). If you do not create any links
7518 (whether symlinks, hard links, or <tt>.so</tt> directives)
7519 in the filesystem to the alternate names of the manpage,
7520 then you should not rely on <prgn>man</prgn> finding your
7521 manpage under those names based solely on the information in
7522 the manpage's header.<footnote>
7523 Supporting this in <prgn>man</prgn> often requires
7524 unreasonable processing time to find a manual page or to
7525 report that none exists, and moves knowledge into man's
7526 database that would be better left in the filesystem.
7527 This support is therefore deprecated and will cease to
7528 be present in the future.
7534 <heading>Info documents</heading>
7537 Info documents should be installed in <file>/usr/share/info</file>.
7538 They should be compressed with <tt>gzip -9</tt>.
7542 Your package should call <prgn>install-info</prgn> to update
7543 the Info <file>dir</file> file in its <prgn>postinst</prgn>
7544 script when called with a <tt>configure</tt> argument, for
7546 <example compact="compact">
7547 install-info --quiet --section Development Development \
7548 /usr/share/info/foobar.info
7552 It is a good idea to specify a section for the location of
7553 your program; this is done with the <tt>--section</tt>
7554 switch. To determine which section to use, you should look
7555 at <file>/usr/share/info/dir</file> on your system and choose the most
7556 relevant (or create a new section if none of the current
7557 sections are relevant). Note that the <tt>--section</tt>
7558 flag takes two arguments; the first is a regular expression
7559 to match (case-insensitively) against an existing section,
7560 the second is used when creating a new one.</p>
7563 You should remove the entries in the <prgn>prerm</prgn>
7564 script when called with a <tt>remove</tt> argument:
7565 <example compact="compact">
7566 install-info --quiet --remove /usr/share/info/foobar.info
7570 If <prgn>install-info</prgn> cannot find a description entry
7571 in the Info file you must supply one. See <manref
7572 name="install-info" section="8"> for details.</p>
7576 <heading>Additional documentation</heading>
7579 Any additional documentation that comes with the package may
7580 be installed at the discretion of the package maintainer.
7581 Text documentation should be installed in the directory
7582 <file>/usr/share/doc/<var>package</var></file>, where
7583 <var>package</var> is the name of the package, and
7584 compressed with <tt>gzip -9</tt> unless it is small.
7588 If a package comes with large amounts of documentation which
7589 many users of the package will not require you should create
7590 a separate binary package to contain it, so that it does not
7591 take up disk space on the machines of users who do not need
7592 or want it installed.</p>
7595 It is often a good idea to put text information files
7596 (<file>README</file>s, changelogs, and so forth) that come with
7597 the source package in <file>/usr/share/doc/<var>package</var></file>
7598 in the binary package. However, you don't need to install
7599 the instructions for building and installing the package, of
7603 Packages must not require the existance of any files in
7604 <file>/usr/share/doc/</file> in order to function
7606 The system administrator should be able to
7607 delete files in <file>/usr/share/doc/</file> without causing
7608 any programs to break.
7610 Any files that are referenced by programs but are also
7611 useful as standalone documentation should be installed under
7612 <file>/usr/share/<var>package</var>/</file> with symbolic links from
7613 <file>/usr/share/doc/<var>package</var></file>.
7617 <file>/usr/share/doc/<var>package</var></file> may be a symbolic
7618 link to another directory in <file>/usr/share/doc</file> only if
7619 the two packages both come from the same source and the
7620 first package Depends on the second.
7624 Former Debian releases placed all additional documentation
7625 in <file>/usr/doc/<var>package</var></file>. This has been
7626 changed to <file>/usr/share/doc/<var>package</var></file>,
7627 and packages must not put documentation in the directory
7628 <file>/usr/doc/<var>package</var></file>. <footnote>
7629 At this phase of the transition, we no longer require a
7630 symbolic link in <file>/usr/doc/</file>. At a later point,
7631 policy shall change to make the symbolic links a bug.
7637 <heading>Preferred documentation formats</heading>
7640 The unification of Debian documentation is being carried out
7644 If your package comes with extensive documentation in a
7645 markup format that can be converted to various other formats
7646 you should if possible ship HTML versions in a binary
7647 package, in the directory
7648 <file>/usr/share/doc/<var>appropriate-package</var></file> or
7649 its subdirectories.<footnote>
7650 The rationale: The important thing here is that HTML
7651 docs should be available in <em>some</em> package, not
7652 necessarily in the main binary package.
7657 Other formats such as PostScript may be provided at the
7658 package maintainer's discretion.
7662 <sect id="copyrightfile">
7663 <heading>Copyright information</heading>
7666 Every package must be accompanied by a verbatim copy of its
7667 copyright and distribution license in the file
7668 <file>/usr/share/doc/<var>package</var>/copyright</file>. This
7669 file must neither be compressed nor be a symbolic link.
7673 In addition, the copyright file must say where the upstream
7674 sources (if any) were obtained. It should name the original
7675 authors of the package and the Debian maintainer(s) who were
7676 involved with its creation.</p>
7679 A copy of the file which will be installed in
7680 <file>/usr/share/doc/<var>package</var>/copyright</file> should
7681 be in <file>debian/copyright</file> in the source package.
7685 <file>/usr/share/doc/<var>package</var></file> may be a symbolic
7686 link to another directory in <file>/usr/share/doc</file> only if
7687 the two packages both come from the same source and the
7688 first package Depends on the second. These rules are
7689 important because copyrights must be extractable by
7694 Packages distributed under the UCB BSD license, the Artistic
7695 license, the GNU GPL, and the GNU LGPL should refer to the
7696 files <file>/usr/share/common-licenses/BSD</file>,
7697 <file>/usr/share/common-licenses/Artistic</file>,
7698 <file>/usr/share/common-licenses/GPL</file>, and
7699 <file>/usr/share/common-licenses/LGPL</file> respectively,
7700 rather than quoting them in the copyright file.
7704 You should not use the copyright file as a general <file>README</file>
7705 file. If your package has such a file it should be
7706 installed in <file>/usr/share/doc/<var>package</var>/README</file> or
7707 <file>README.Debian</file> or some other appropriate place.</p>
7711 <heading>Examples</heading>
7714 Any examples (configurations, source files, whatever),
7715 should be installed in a directory
7716 <file>/usr/share/doc/<var>package</var>/examples</file>. These
7717 files should not be referenced by any program: they're there
7718 for the benefit of the system administrator and users as
7719 documentation only. Architecture-specific example files
7720 should be installed in a directory
7721 <file>/usr/lib/<var>package</var>/examples</file> with symbolic
7723 <file>/usr/share/doc/<var>package</var>/examples</file>, or the
7724 latter directory itself may be a symbolic link to the
7729 If the purpose of a package is to provide examples, then the
7730 example files may be installed into
7731 <file>/usr/share/doc/<var>package</var></file>.
7735 <sect id="changelogs">
7736 <heading>Changelog files</heading>
7739 The Debian changelog file (<file>debian/changelog</file>) should
7740 explain briefly what modifications were made in the Debian version
7741 of the package compared to the upstream one. Other changes and
7742 updates to the package should also be documented in this file.
7746 Mistakes in changelogs are usually best rectified by
7747 making a new changelog entry rather than "rewriting history"
7748 by editing old changelog entries.
7752 The format of the <file>debian/changelog</file> file is described
7753 in <ref id="dpkgchangelog">. In non-experimental packages you must
7754 use a format for <file>debian/changelog</file> which is supported
7755 by the most recent released version of <prgn>dpkg</prgn>.<footnote>
7756 If you wish to use an alternative format, you may do so as
7757 long as you include a parser for it in your source package.
7758 The parser must have an API compatible with that expected by
7759 <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-gencontrol</prgn>.
7760 If there is general interest in the new format, you should
7761 contact the <package>dpkg</package> maintainer to have the
7762 parser script for it included in the <prgn>dpkg</prgn>
7763 package. (You will need to agree that the parser and its
7764 manpage may be distributed under the GNU GPL, just as the rest
7765 of <prgn>dpkg</prgn> is.)
7770 Packages that are not Debian-native must contain a
7771 compressed copy of the <file>debian/changelog</file> file from
7772 the Debian source tree in
7773 <file>/usr/share/doc/<var>package</var></file> with the name
7774 <file>changelog.Debian.gz</file>.
7778 If an upstream changelog is available, it should be accessible as
7779 <file>/usr/share/doc/<var>package</var>/changelog.gz</file> in
7780 plain text. If the upstream changelog is distributed in
7781 HTML, it should be made available in that form as
7782 <file>/usr/share/doc/<var>package</var>/changelog.html.gz</file>
7783 and a plain text <file>changelog.gz</file> should be generated
7784 from it using, for example, <tt>lynx -dump -nolist</tt>. If
7785 the upstream changelog files do not already conform to this
7786 naming convention, then this may be achieved either by
7787 renaming the files, or by adding a symbolic link, at the
7788 maintainer's discretion.<footnote>
7789 Rationale: People should not have to look in places for
7790 upstream changelogs merely because they are given
7791 different names or are distributed in HTML format.
7796 All of these files should be installed compressed using
7797 <tt>gzip -9</tt>, as they will become large with time even
7798 if they start out small.
7802 If the package has only one changelog which is used both as
7803 the Debian changelog and the upstream one because there is
7804 no separate upstream maintainer then that changelog should
7805 usually be installed as
7806 <file>/usr/share/doc/<var>package</var>/changelog.gz</file>; if
7807 there is a separate upstream maintainer, but no upstream
7808 changelog, then the Debian changelog should still be called
7809 <file>changelog.Debian.gz</file>.</p>
7814 <appendix id="pkg-scope">
7815 <heading>Introduction and scope of these appendices</heading>
7818 These appendices are taken essentially verbatim from the
7819 now-deprecated Packaging Manual, version 3.2.1.0. They are
7820 the chapters which are likely to be of use to package
7821 maintainers and which have not already been included in the
7822 policy document itself. Most of these sections are very likely
7823 not relevant to policy; they should be treated as
7824 documentation for the packaging system. Please note that these
7825 appendices are included for convenience, and for historical
7826 reasons: they used to be part of policy package, and they have
7827 not yet been incorporated into dpkg documentation. However,
7828 they still have value, and hence they are presented here.
7831 They have not yet been checked to ensure that they are
7832 compatible with the contents of policy, and if there are any
7833 contradictions, the version in the main policy document takes
7834 precedence. The remaining chapters of the old Packaging
7835 Manual have also not been read in detail to ensure that there
7836 are not parts which have been left out. Both of these will be
7841 <prgn>dpkg</prgn> is a suite of programs for creating binary
7842 package files and installing and removing them on Unix
7844 <prgn>dpkg</prgn> is targetted primarily at Debian
7845 GNU/Linux, but may work on or be ported to other
7851 The binary packages are designed for the management of
7852 installed executable programs (usually compiled binaries) and
7853 their associated data, though source code examples and
7854 documentation are provided as part of some packages.</p>
7857 This manual describes the technical aspects of creating Debian
7858 binary packages (<file>.deb</file> files). It documents the
7859 behaviour of the package management programs
7860 <prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and the way
7861 they interact with packages.</p>
7864 It also documents the interaction between
7865 <prgn>dselect</prgn>'s core and the access method scripts it
7866 uses to actually install the selected packages, and describes
7867 how to create a new access method.</p>
7870 This manual does not go into detail about the options and
7871 usage of the package building and installation tools. It
7872 should therefore be read in conjuction with those programs'
7877 The utility programs which are provided with <prgn>dpkg</prgn>
7878 for managing various system configuration and similar issues,
7879 such as <prgn>update-rc.d</prgn> and
7880 <prgn>install-info</prgn>, are not described in detail here -
7881 please see their manpages.
7885 It is assumed that the reader is reasonably familiar with the
7886 <prgn>dpkg</prgn> System Administrators' manual.
7887 Unfortunately this manual does not yet exist.
7891 The Debian version of the FSF's GNU hello program is provided
7892 as an example for people wishing to create Debian
7893 packages. The Debian <prgn>debmake</prgn> package is
7894 recommended as a very helpful tool in creating and maintaining
7895 Debian packages. However, while the tools and examples are
7896 helpful, they do not replace the need to read and follow the
7897 Policy and Programmer's Manual.</p>
7900 <appendix id="pkg-binarypkg"><heading>Binary packages (from old
7905 The binary package has two main sections. The first part
7906 consists of various control information files and scripts used
7907 by <prgn>dpkg</prgn> when installing and removing. See <ref
7908 id="pkg-controlarea">.
7912 The second part is an archive containing the files and
7913 directories to be installed.
7917 In the future binary packages may also contain other
7918 components, such as checksums and digital signatures. The
7919 format for the archive is described in full in the
7920 <file>deb(5)</file> manpage.
7924 <sect id="pkg-bincreating"><heading>Creating package files -
7925 <prgn>dpkg-deb</prgn>
7929 All manipulation of binary package files is done by
7930 <prgn>dpkg-deb</prgn>; it's the only program that has
7931 knowledge of the format. (<prgn>dpkg-deb</prgn> may be
7932 invoked by calling <prgn>dpkg</prgn>, as <prgn>dpkg</prgn>
7933 will spot that the options requested are appropriate to
7934 <prgn>dpkg-deb</prgn> and invoke that instead with the same
7939 In order to create a binary package you must make a
7940 directory tree which contains all the files and directories
7941 you want to have in the filesystem data part of the package.
7942 In Debian-format source packages this directory is usually
7943 <file>debian/tmp</file>, relative to the top of the package's
7948 They should have the locations (relative to the root of the
7949 directory tree you're constructing) ownerships and
7950 permissions which you want them to have on the system when
7955 With current versions of <prgn>dpkg</prgn> the uid/username
7956 and gid/groupname mappings for the users and groups being
7957 used should be the same on the system where the package is
7958 built and the one where it is installed.
7962 You need to add one special directory to the root of the
7963 miniature filesystem tree you're creating:
7964 <prgn>DEBIAN</prgn>. It should contain the control
7965 information files, notably the binary package control file
7966 (see <ref id="pkg-controlfile">).
7970 The <prgn>DEBIAN</prgn> directory will not appear in the
7971 filesystem archive of the package, and so won't be installed
7972 by <prgn>dpkg</prgn> when the package is installed.
7976 When you've prepared the package, you should invoke:
7978 dpkg --build <var>directory</var>
7983 This will build the package in
7984 <file><var>directory</var>.deb</file>. (<prgn>dpkg</prgn> knows
7985 that <tt>--build</tt> is a <prgn>dpkg-deb</prgn> option, so
7986 it invokes <prgn>dpkg-deb</prgn> with the same arguments to
7991 See the manpage <manref name="dpkg-deb" section="8"> for details of how
7992 to examine the contents of this newly-created file. You may find the
7993 output of following commands enlightening:
7995 dpkg-deb --info <var>filename</var>.deb
7996 dpkg-deb --contents <var>filename</var>.deb
7997 dpkg --contents <var>filename</var>.deb
7999 To view the copyright file for a package you could use this command:
8001 dpkg --fsys-tarfile <var>filename</var>.deb | tar xof usr/share/doc/<var>\*</var>copyright | less
8006 <sect id="pkg-controlarea">
8008 Package control information files
8012 The control information portion of a binary package is a
8013 collection of files with names known to <prgn>dpkg</prgn>.
8014 It will treat the contents of these files specially - some
8015 of them contain information used by <prgn>dpkg</prgn> when
8016 installing or removing the package; others are scripts which
8017 the package maintainer wants <prgn>dpkg</prgn> to run.
8021 It is possible to put other files in the package control
8022 area, but this is not generally a good idea (though they
8023 will largely be ignored).
8027 Here is a brief list of the control info files supported by
8028 <prgn>dpkg</prgn> and a summary of what they're used for.
8033 <tag><tt>control</tt>
8037 This is the key description file used by
8038 <prgn>dpkg</prgn>. It specifies the package's name
8039 and version, gives its description for the user,
8040 states its relationships with other packages, and so
8041 forth. See <ref id="pkg-controlfile">.
8045 It is usually generated automatically from information
8046 in the source package by the
8047 <prgn>dpkg-gencontrol</prgn> program, and with
8048 assistance from <prgn>dpkg-shlibdeps</prgn>. See <ref
8049 id="pkg-sourcetools">.</p>
8052 <tag><tt>postinst</tt>, <tt>preinst</tt>, <tt>postrm</tt>,
8058 These are exectuable files (usually scripts) which
8059 <prgn>dpkg</prgn> runs during installation, upgrade
8060 and removal of packages. They allow the package to
8061 deal with matters which are particular to that package
8062 or require more complicated processing than that
8063 provided by <prgn>dpkg</prgn>. Details of when and
8064 how they are called are in <ref
8065 id="maintainerscripts">.
8069 It is very important to make these scripts
8072 That means that if it runs successfully or fails
8073 and then you call it again it doesn't bomb out,
8074 but just ensures that everything is the way it
8076 </footnote> This is so that if an error occurs, the
8077 user interrupts <prgn>dpkg</prgn> or some other
8078 unforeseen circumstance happens you don't leave the
8079 user with a badly-broken package.
8083 The maintainer scripts are guaranteed to run with a
8084 controlling terminal and can interact with the user.
8085 If they need to prompt for passwords, do full-screen
8086 interaction or something similar you should do these
8087 things to and from <file>/dev/tty</file>, since
8088 <prgn>dpkg</prgn> will at some point redirect scripts'
8089 standard input and output so that it can log the
8090 installation process. Likewise, because these scripts
8091 may be executed with standard output redirected into a
8092 pipe for logging purposes, Perl scripts should set
8093 unbuffered output by setting <tt>$|=1</tt> so that the
8094 output is printed immediately rather than being
8099 Each script should return a zero exit status for
8100 success, or a nonzero one for failure.</p>
8103 <tag><tt>conffiles</tt>
8108 This file contains a list of configuration files which
8109 are to be handled automatically by <prgn>dpkg</prgn>
8110 (see <ref id="pkg-conffiles">). Note that not necessarily
8111 every configuration file should be listed here.</p>
8114 <tag><tt>shlibs</tt>
8119 This file contains a list of the shared libraries
8120 supplied by the package, with dependency details for
8121 each. This is used by <prgn>dpkg-shlibdeps</prgn>
8122 when it determines what dependencies are required in a
8123 package control file. The <tt>shlibs</tt> file format
8124 is described on <ref id="shlibs">.
8130 <sect id="pkg-controlfile">
8132 The main control information file: <tt>control</tt>
8135 The most important control information file used by
8136 <prgn>dpkg</prgn> when it installs a package is
8137 <tt>control</tt>. It contains all the package"s "vital
8142 The binary package control files of packages built from
8143 Debian sources are made by a special tool,
8144 <prgn>dpkg-gencontrol</prgn>, which reads
8145 <file>debian/control</file> and <file>debian/changelog</file> to
8146 find the information it needs. See <ref id="pkg-sourcepkg"> for
8151 The fields in binary package control files are:
8152 <list compact="compact">
8154 <p><qref id="pkg-f-Package"><tt>Package</tt></qref> (mandatory)</p>
8157 <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
8159 <item><p><qref id="pkg-f-Architecture"><tt>Architecture</tt></qref>
8162 This field should appear in all packages, though
8163 <prgn>dpkg</prgn> doesn't require it yet so that
8164 old packages can still be installed.
8169 <p><qref id="relationships"><tt>Depends</tt>,
8170 <tt>Provides</tt> et al.</qref></p>
8173 <p><qref id="pkg-f-Essential"><tt>Essential</tt></qref></p>
8176 <p><qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref></p>
8179 <p><qref id="pkg-f-classification"><tt>Section</tt>,
8180 <tt>Priority</tt></qref></p>
8183 <p><qref id="pkg-f-Source"><tt>Source</tt></qref></p>
8186 <p><qref id="descriptions"><tt>Description</tt></qref></p>
8190 <qref id="pkg-f-Installed-Size"><tt>Installed-Size</tt></qref>
8196 A description of the syntax of control files and the purpose
8197 of these fields is available in <ref id="pkg-controlfields">.
8202 <heading>Time Stamps</heading>
8204 Maintainers are encouraged to preserve the modification
8205 times of the upstream source files in a package, as far as
8206 is reasonably possible.
8208 The rationale is that there is some information conveyed
8209 by knowing the age of the file, for example, you could
8210 recognize that some documentation is very old by looking
8211 at the modification time, so it would be nice if the
8212 modification time of the upstream source would be
8219 <appendix id="pkg-sourcepkg">
8220 <heading>Source packages (from old Packaging Manual) </heading>
8223 The Debian binary packages in the distribution are generated
8224 from Debian sources, which are in a special format to assist
8225 the easy and automatic building of binaries.
8228 <sect id="pkg-sourcetools">
8229 <heading>Tools for processing source packages</heading>
8232 Various tools are provided for manipulating source packages;
8233 they pack and unpack sources and help build of binary
8234 packages and help manage the distribution of new versions.
8238 They are introduced and typical uses described here; see
8239 <manref name="dpkg-source" section="1"> for full
8240 documentation about their arguments and operation.
8244 For examples of how to construct a Debian source package,
8245 and how to use those utilities that are used by Debian
8246 source packages, please see the <prgn>hello</prgn> example
8252 <prgn>dpkg-source</prgn> - packs and unpacks Debian source
8257 This program is frequently used by hand, and is also
8258 called from package-independent automated building scripts
8259 such as <prgn>dpkg-buildpackage</prgn>.
8263 To unpack a package it is typically invoked with
8265 dpkg-source -x <var>.../path/to/filename</var>.dsc
8270 with the <file><var>filename</var>.tar.gz</file> and
8271 <file><var>filename</var>.diff.gz</file> (if applicable) in
8272 the same directory. It unpacks into
8273 <file><var>package</var>-<var>version</var></file>, and if
8275 <file><var>package</var>-<var>version</var>.orig</file>, in
8276 the current directory.
8280 To create a packed source archive it is typically invoked:
8282 dpkg-source -b <var>package</var>-<var>version</var>
8287 This will create the <file>.dsc</file>, <file>.tar.gz</file> and
8288 <file>.diff.gz</file> (if appropriate) in the current
8289 directory. <prgn>dpkg-source</prgn> does not clean the
8290 source tree first - this must be done separately if it is
8295 See also <ref id="pkg-sourcearchives">.</p>
8301 <prgn>dpkg-buildpackage</prgn> - overall package-building
8306 <prgn>dpkg-buildpackage</prgn> is a script which invokes
8307 <prgn>dpkg-source</prgn>, the <file>debian/rules</file>
8308 targets <tt>clean</tt>, <tt>build</tt> and
8309 <tt>binary</tt>, <prgn>dpkg-genchanges</prgn> and
8310 <prgn>pgp</prgn> to build a signed source and binary
8315 It is usually invoked by hand from the top level of the
8316 built or unbuilt source directory. It may be invoked with
8317 no arguments; useful arguments include:
8318 <taglist compact="compact">
8319 <tag><tt>-uc</tt>, <tt>-us</tt></tag>
8322 Do not PGP-sign the <tt>.changes</tt> file or the
8323 source package <tt>.dsc</tt> file, respectively.</p>
8325 <tag><tt>-p<var>pgp-command</var></tt></tag>
8328 Invoke <var>pgp-command</var> instead of finding
8329 <tt>pgp</tt> on the <prgn>PATH</prgn>.
8330 <var>pgp-command</var> must behave just like
8331 <prgn>pgp</prgn>.</p>
8333 <tag><tt>-r<var>root-command</var></tt></tag>
8336 When root privilege is required, invoke the command
8337 <var>root-command</var>. <var>root-command</var>
8338 should invoke its first argument as a command, from
8339 the <prgn>PATH</prgn> if necessary, and pass its
8340 second and subsequent arguments to the command it
8341 calls. If no <var>root-command</var> is supplied
8342 then <var>dpkg-buildpackage</var> will take no
8343 special action to gain root privilege, so that for
8344 most packages it will have to be invoked as root to
8347 <tag><tt>-b</tt>, <tt>-B</tt></tag>
8350 Two types of binary-only build and upload - see
8351 <manref name="dpkg-source" section="1">.
8360 <prgn>dpkg-gencontrol</prgn> - generates binary package
8365 This program is usually called from <file>debian/rules</file>
8366 (see <ref id="pkg-sourcetree">) in the top level of the source
8371 This is usually done just before the files and directories in the
8372 temporary directory tree where the package is being built have their
8373 permissions and ownerships set and the package is constructed using
8374 <prgn>dpkg-deb/</prgn>
8376 This is so that the control file which is produced has
8377 the right permissions
8382 <prgn>dpkg-gencontrol</prgn> must be called after all the
8383 files which are to go into the package have been placed in
8384 the temporary build directory, so that its calculation of
8385 the installed size of a package is correct.
8389 It is also necessary for <prgn>dpkg-gencontrol</prgn> to
8390 be run after <prgn>dpkg-shlibdeps</prgn> so that the
8391 variable substitutions created by
8392 <prgn>dpkg-shlibdeps</prgn> in <file>debian/substvars</file>
8397 For a package which generates only one binary package, and
8398 which builds it in <file>debian/tmp</file> relative to the top
8399 of the source package, it is usually sufficient to call
8400 <prgn>dpkg-gencontrol</prgn>.
8404 Sources which build several binaries will typically need
8407 dpkg-gencontrol -Pdebian/tmp-<var>pkg</var> -p<var>package</var>
8408 </example> The <tt>-P</tt> tells
8409 <prgn>dpkg-gencontrol</prgn> that the package is being
8410 built in a non-default directory, and the <tt>-p</tt>
8411 tells it which package's control file should be generated.
8415 <prgn>dpkg-gencontrol</prgn> also adds information to the
8416 list of files in <file>debian/files</file>, for the benefit of
8417 (for example) a future invocation of
8418 <prgn>dpkg-genchanges</prgn>.</p>
8423 <prgn>dpkg-shlibdeps</prgn> - calculates shared library
8428 This program is usually called from <file>debian/rules</file>
8429 just before <prgn>dpkg-gencontrol</prgn> (see <ref
8430 id="pkg-sourcetree">), in the top level of the source tree.
8434 Its arguments are executables.
8437 In a forthcoming dpkg version,
8438 <prgn>dpkg-shlibdeps</prgn> would be required to be
8439 called on shared libraries as well.
8442 They may be specified either in the locations in the
8443 source tree where they are created or in the locations
8444 in the temporary build tree where they are installed
8445 prior to binary package creation.
8447 </footnote> for which shared library dependencies should
8448 be included in the binary package's control file.
8452 If some of the found shared libraries should only
8453 warrant a <tt>Recommends</tt> or <tt>Suggests</tt>, or if
8454 some warrant a <tt>Pre-Depends</tt>, this can be achieved
8455 by using the <tt>-d<var>dependency-field</var></tt> option
8456 before those executable(s). (Each <tt>-d</tt> option
8457 takes effect until the next <tt>-d</tt>.)
8461 <prgn>dpkg-shlibdeps</prgn> does not directly cause the
8462 output control file to be modified. Instead by default it
8463 adds to the <file>debian/substvars</file> file variable
8464 settings like <tt>shlibs:Depends</tt>. These variable
8465 settings must be referenced in dependency fields in the
8466 appropriate per-binary-package sections of the source
8471 For example, the <prgn>procps</prgn> package generates two
8472 kinds of binaries, simple C binaries like <prgn>ps</prgn>
8473 which require a predependency and full-screen ncurses
8474 binaries like <prgn>top</prgn> which require only a
8475 recommendation. It can say in its <file>debian/rules</file>:
8477 dpkg-shlibdeps -dPre-Depends ps -dRecommends top
8479 and then in its main control file <file>debian/control</file>:
8483 Pre-Depends: ${shlibs:Pre-Depends}
8484 Recommends: ${shlibs:Recommends}
8490 Sources which produce several binary packages with
8491 different shared library dependency requirements can use
8492 the <tt>-p<var>varnameprefix</var></tt> option to override
8493 the default <tt>shlibs:</tt> prefix (one invocation of
8494 <prgn>dpkg-shlibdeps</prgn> per setting of this option).
8495 They can thus produce several sets of dependency
8496 variables, each of the form
8497 <tt><var>varnameprefix</var>:<var>dependencyfield</var></tt>,
8498 which can be referred to in the appropriate parts of the
8499 binary package control files.
8506 <prgn>dpkg-distaddfile</prgn> - adds a file to
8507 <file>debian/files</file>
8511 Some packages' uploads need to include files other than
8512 the source and binary package files.
8516 <prgn>dpkg-distaddfile</prgn> adds a file to the
8517 <file>debian/files</file> file so that it will be included in
8518 the <file>.changes</file> file when
8519 <prgn>dpkg-genchanges</prgn> is run.
8523 It is usually invoked from the <tt>binary</tt> target of
8524 <file>debian/rules</file>:
8526 dpkg-distaddfile <var>filename</var> <var>section</var> <var>priority</var>
8528 The <var>filename</var> is relative to the directory where
8529 <prgn>dpkg-genchanges</prgn> will expect to find it - this
8530 is usually the directory above the top level of the source
8531 tree. The <file>debian/rules</file> target should put the
8532 file there just before or just after calling
8533 <prgn>dpkg-distaddfile</prgn>.
8537 The <var>section</var> and <var>priority</var> are passed
8538 unchanged into the resulting <file>.changes</file> file. See
8539 <ref id="pkg-f-classification">.
8544 <sect1><heading><prgn>dpkg-genchanges</prgn> - generates a <file>.changes</file> upload
8549 This program is usually called by package-independent
8550 automatic building scripts such as
8551 <prgn>dpkg-buildpackage</prgn>, but it may also be called
8556 It is usually called in the top level of a built source
8557 tree, and when invoked with no arguments will print out a
8558 straightforward <file>.changes</file> file based on the
8559 information in the source package's changelog and control
8560 file and the binary and source packages which should have
8566 <sect1><heading><prgn>dpkg-parsechangelog</prgn> - produces parsed representation of
8571 This program is used internally by
8572 <prgn>dpkg-source</prgn> et al. It may also occasionally
8573 be useful in <file>debian/rules</file> and elsewhere. It
8574 parses a changelog, <file>debian/changelog</file> by default,
8575 and prints a control-file format representation of the
8576 information in it to standard output.
8580 <sect1 id="pkg-dpkgarch"><heading><prgn>dpkg-architecture</prgn> -
8581 information about the build and host system
8585 This program can be used manually, but is also invoked by
8586 <tt>dpkg-buildpackage</tt> or <file>debian/rules</file> to set
8587 to set environment or make variables which specify the build and
8588 host architecture for the package building process.
8593 <sect id="pkg-sourcetree"><heading>The Debianised source tree
8597 The source archive scheme described later is intended to
8598 allow a Debianised source tree with some associated control
8599 information to be reproduced and transported easily. The
8600 Debianised source tree is a version of the original program
8601 with certain files added for the benefit of the
8602 Debianisation process, and with any other changes required
8603 made to the rest of the source code and installation
8608 The extra files created for Debian are in the subdirectory
8609 <file>debian</file> of the top level of the Debianised source
8610 tree. They are described below.
8613 <sect1 id="pkg-debianrules"><heading><file>debian/rules</file> - the main building
8618 This file is an executable makefile, and contains the
8619 package-specific recipies for compiling the package and
8620 building binary package(s) out of the source.
8624 It must start with the line <tt>#!/usr/bin/make -f</tt>,
8625 so that it can be invoked by saying its name rather than
8626 invoking <prgn>make</prgn> explicitly.
8630 Since an interactive <file>debian/rules</file> script makes it
8631 impossible to autocompile that package and also makes it
8632 hard for other people to reproduce the same binary
8633 package, all <strong>required targets</strong> have to be
8634 non-interactive. At a minimul, required targets are the
8635 ones called by <prgn>dpkg-buildpackage</prgn>, namely,
8636 <em>clean</em>, <em>binary</em>, <em>binary-arch</em>, and
8637 <em>build</em>. It also follows that any target that these
8638 targets depend on must also be non-interactive.
8642 The targets which are required to be present are:
8644 <tag><tt>build</tt></tag>
8647 This should perform all non-interactive
8648 configuration and compilation of the package. If a
8649 package has an interactive pre-build configuration
8650 routine, the Debianised source package should be
8651 built after this has taken place, so that it can be
8652 built without rerunning the configuration.
8656 A package may also provide both of the targets
8657 <tt>build-arch</tt> and <tt>build-indep</tt>. The
8658 <tt>build-arch</tt> target, if provided, should
8659 perform all non-interactive configuration and
8660 compilation required for producing all
8661 architecture-dependant binary packages (those packages
8662 for which the body of the <tt>Architecture</tt> field
8663 in <tt>debian/control</tt> is not <tt>all</tt>).
8664 Similarly, the <tt>build-indep</tt> target, if
8665 provided, should perform all non-interactive
8666 configuration and compilation required for producing
8667 all architecture-independent binary packages (those
8668 packages for which the body of the
8669 <tt>Architecture</tt> field in <tt>debian/control</tt>
8670 is <tt>all</tt>). The <tt>build</tt> target should
8671 depend on those of the targets <tt>build-arch</tt> and
8672 <tt>build-indep</tt> that are provided in the rules
8677 If one or both of the targets <tt>build-arch</tt> and
8678 <tt>build-indep</tt> are not provided, then invoking
8679 <file>debian/rules</file> with one of the not-provided
8680 targets as arguments should produce a exit status code
8681 of 2. Usually this is provided automatically by make
8682 if the target is missing.
8686 For some packages, notably ones where the same
8687 source tree is compiled in different ways to produce
8688 two binary packages, the <tt>build</tt> target does
8689 not make much sense. For these packages it is good
8690 enough to provide two (or more) targets
8691 (<tt>build-a</tt> and <tt>build-b</tt> or whatever)
8692 for each of the ways of building the package, and a
8693 <tt>build</tt> target that does nothing. The
8694 <tt>binary</tt> target will have to build the
8695 package in each of the possible ways and make the
8696 binary package out of each.
8700 The targets <tt>build</tt>, <tt>build-arch</tt>
8701 and <tt>build-indep</tt> target must not do
8702 anything that might require root privilege.
8706 The <tt>build</tt> target may need to run
8707 <tt>clean</tt> first - see below.
8711 When a package has a configuration routine that takes
8712 a long time, or when the makefiles are poorly
8713 designed, or when <tt>build</tt> needs to run
8714 <tt>clean</tt> first, it is a good idea to <tt>touch
8715 build</tt> when the build process is complete. This
8716 will ensure that if <tt>debian/rules build</tt> is run
8717 again it will not rebuild the whole program.
8721 <tag><tt>binary</tt>, <tt>binary-arch</tt>,
8722 <tt>binary-indep</tt>
8726 The <tt>binary</tt> target should be all that is
8727 necessary for the user to build the binary
8728 package. All these targets are required to be
8729 non-interactive. It is split into two parts:
8730 <tt>binary-arch</tt> builds the packages' output
8731 files which are specific to a particular
8732 architecture, and <tt>binary-indep</tt> builds
8733 those which are not.
8737 <tt>binary</tt> should usually be a target with
8738 no commands which simply depends on
8739 <prgn>binary-arch</prgn> and
8740 <prgn>binary-indep</prgn>.
8744 Both <prgn>binary-*</prgn> targets should depend on
8745 the <tt>build</tt> target, above, so that the
8746 package is built if it has not been already. It
8747 should then create the relevant binary package(s),
8748 using <prgn>dpkg-gencontrol</prgn> to make their
8749 control files and <prgn>dpkg-deb</prgn> to build
8750 them and place them in the parent of the top level
8755 If one of the <prgn>binary-*</prgn> targets has
8756 nothing to do (this will be always be the case if
8757 the source generates only a single binary package,
8758 whether architecture-dependent or not) it
8759 <em>must</em> still exist, but should always
8764 <ref id="pkg-binarypkg"> describes how to construct
8769 The <tt>binary</tt> targets must be invoked as
8774 <tag><tt>clean</tt></tag>
8778 This should undo any effects that the
8779 <tt>build</tt> and <tt>binary</tt> targets
8780 may have had, except that it should leave alone any
8781 output files created in the parent directory by a
8782 run of <tt>binary</tt>. This target is required
8783 to be non-interactive.
8787 If a <tt>build</tt> file is touched at the end
8788 of the <tt>build</tt> target, as suggested
8789 above, it must be removed as the first thing that
8790 <tt>clean</tt> does, so that running
8791 <tt>build</tt> again after an interrupted
8792 <tt>clean</tt> doesn't think that everything is
8797 The <tt>clean</tt> target must be invoked as
8798 root if <tt>binary</tt> has been invoked since
8799 the last <tt>clean</tt>, or if
8800 <tt>build</tt> has been invoked as root (since
8801 <tt>build</tt> may create directories, for
8806 <tag><tt>get-orig-source</tt> (optional)</tag>
8810 This target fetches the most recent version of the
8811 original source package from a canonical archive
8812 site (via FTP or WWW, for example), does any
8813 necessary rearrangement to turn it into the original
8814 source tarfile format described below, and leaves it
8815 in the current directory.
8819 This target may be invoked in any directory, and
8820 should take care to clean up any temporary files it
8825 This target is optional, but providing it if
8826 possible is a good idea.
8832 The <tt>build</tt>, <tt>binary</tt> and
8833 <tt>clean</tt> targets must be invoked with a current
8834 directory of the package's top-level directory.
8839 Additional targets may exist in <file>debian/rules</file>,
8840 either as published or undocumented interfaces or for the
8841 package's internal use.
8845 The architecture we build on and build for is determined by make
8846 variables via dpkg-architecture (see <ref id="pkg-dpkgarch">). You can
8847 get the Debian architecture and the GNU style architecture
8848 specification string for the build machine as well as the host
8849 machine. Here is a list of supported make variables:
8850 <list compact="compact">
8852 <p><tt>DEB_*_ARCH</tt> (the Debian architecture)</p>
8855 <p><tt>DEB_*_GNU_TYPE</tt> (the GNU style architecture
8856 specification string)</p>
8859 <p><tt>DEB_*_GNU_CPU</tt> (the CPU part of DEB_*_GNU_TYPE)</p>
8862 <p><tt>DEB_*_GNU_SYSTEM</tt> (the System part of
8868 where <tt>*</tt> is either <tt>BUILD</tt> for specification of
8869 the build machine or <tt>HOST</tt> for specification of the machine
8874 Backward compatibility can be provided in the rules file
8875 by setting the needed variables to suitable default
8876 values, please refer to the documentation of
8877 dpkg-architecture for details.
8881 It is important to understand that the <tt>DEB_*_ARCH</tt>
8882 string does only determine which Debian architecture we
8883 build on resp. for. It should not be used to get the CPU
8884 or System information, the GNU style variables should be
8890 <sect1><heading><file>debian/control</file>
8894 This file contains version-independent details about the
8895 source package and about the binary packages it creates.
8899 It is a series of sets of control fields, each
8900 syntactically similar to a binary package control file.
8901 The sets are separated by one or more blank lines. The
8902 first set is information about the source package in
8903 general; each subsequent set describes one binary package
8904 that the source tree builds.
8908 The syntax and semantics of the fields are described below
8909 in <ref id="pkg-controlfields">.
8913 The general (binary-package-independent) fields are:
8914 <list compact="compact">
8916 <p><qref id="pkg-f-Source"><tt>Source</tt></qref> (mandatory)</p>
8919 <p><qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref></p>
8923 <qref id="pkg-f-classification"><tt>Section</tt> and
8924 <tt>Priority</tt></qref>
8925 (classification, mandatory)
8930 <qref id="relationships"><tt>Build-Depends</tt> et
8931 al.</qref> (source package interrelationships)
8936 <qref id="pkg-f-Standards-Version"><tt>Standards-Version</tt></qref>
8942 The per-binary-package fields are:
8943 <list compact="compact">
8945 <p><qref id="pkg-f-Package"><tt>Package</tt></qref> (mandatory)</p>
8949 <qref id="pkg-f-Architecture"><tt>Architecture</tt></qref>
8953 <p><qref id="descriptions"><tt>Description</tt></qref></p>
8957 <qref id="pkg-f-classification"><tt>Section</tt> and
8958 <tt>Priority</tt></qref> (classification)</p>
8961 <p><qref id="pkg-f-Essential"><tt>Essential</tt></qref></p>
8965 <qref id="relationships"><tt>Depends</tt> et
8966 al.</qref> (binary package interrelationships)
8972 These fields are used by <prgn>dpkg-gencontrol</prgn> to
8973 generate control files for binary packages (see below), by
8974 <prgn>dpkg-genchanges</prgn> to generate the
8975 <tt>.changes</tt> file to accompany the upload, and by
8976 <prgn>dpkg-source</prgn> when it creates the <file>.dsc</file>
8977 source control file as part of a source archive.
8981 The fields here may contain variable references - their
8982 values will be substituted by
8983 <prgn>dpkg-gencontrol</prgn>, <prgn>dpkg-genchanges</prgn>
8984 or <prgn>dpkg-source</prgn> when they generate output
8985 control files. See <ref id="pkg-srcsubstvars"> for details.
8988 <p> <sect2><heading>User-defined fields
8992 Additional user-defined fields may be added to the
8993 source package control file. Such fields will be
8994 ignored, and not copied to (for example) binary or
8995 source package control files or upload control files.
8999 If you wish to add additional unsupported fields to
9000 these output files you should use the mechanism
9005 Fields in the main source control information file with
9006 names starting <tt>X</tt>, followed by one or more of
9007 the letters <tt>BCS</tt> and a hyphen <tt>-</tt>, will
9008 be copied to the output files. Only the part of the
9009 field name after the hyphen will be used in the output
9010 file. Where the letter <tt>B</tt> is used the field
9011 will appear in binary package control files, where the
9012 letter <tt>S</tt> is used in source package control
9013 files and where <tt>C</tt> is used in upload control
9014 (<tt>.changes</tt>) files.
9018 For example, if the main source information control file
9021 XBS-Comment: I stand between the candle and the star.
9023 then the binary and source package control files will contain the
9026 Comment: I stand between the candle and the star.
9033 <sect1 id="pkg-dpkgchangelog"><heading><file>debian/changelog</file>
9037 This file records the changes to the Debian-specific parts of the
9040 Though there is nothing stopping an author who is also
9041 the Debian maintainer from using it for all their
9042 changes, it will have to be renamed if the Debian and
9043 upstream maintainers become different
9049 It has a special format which allows the package building
9050 tools to discover which version of the package is being
9051 built and find out other release-specific information.
9055 That format is a series of entries like this:
9057 <var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
9059 * <var>change details</var>
9060 <var>more change details</var>
9061 * <var>even more change details</var>
9063 -- <var>maintainer name and email address</var> <var>date</var>
9068 <var>package</var> and <var>version</var> are the source
9069 package name and version number.
9073 <var>distribution(s)</var> lists the distributions where
9074 this version should be installed when it is uploaded - it
9075 is copied to the <tt>Distribution</tt> field in the
9076 <tt>.changes</tt> file. See <ref id="pkg-f-Distribution">.
9080 <var>urgency</var> is the value for the <tt>Urgency</tt>
9081 field in the <file>.changes</file> file for the upload. See
9082 <ref id="pkg-f-Urgency">. It is not possible to specify an
9083 urgency containing commas; commas are used to separate
9084 <tt><var>keyword</var>=<var>value</var></tt> settings in
9085 the <prgn>dpkg</prgn> changelog format (though there is
9086 currently only one useful <var>keyword</var>,
9091 The change details may in fact be any series of lines
9092 starting with at least two spaces, but conventionally each
9093 change starts with an asterisk and a separating space and
9094 continuation lines are indented so as to bring them in
9095 line with the start of the text above. Blank lines may be
9096 used here to separate groups of changes, if desired.
9100 The maintainer name and email address should <em>not</em>
9101 necessarily be those of the usual package maintainer.
9102 They should be the details of the person doing
9103 <em>this</em> version. The information here will be
9104 copied to the <file>.changes</file> file, and then later used
9105 to send an acknowledgement when the upload has been
9110 The <var>date</var> should be in RFC822 format
9112 This is generated by the <prgn>822-date</prgn>
9114 </footnote>; it should include the timezone specified
9115 numerically, with the timezone name or abbreviation
9116 optionally present as a comment.
9120 The first "title" line with the package name should start
9121 at the left hand margin; the "trailer" line with the
9122 maintainer and date details should be preceded by exactly
9123 one space. The maintainer details and the date must be
9124 separated by exactly two spaces.
9128 An Emacs mode for editing this format is available: it is
9129 called <tt>debian-changelog-mode</tt>. You can have this
9130 mode selected automatically when you edit a Debian
9131 changelog by adding a local variables clause to the end of
9135 <sect2><heading>Defining alternative changelog formats
9139 It is possible to use a different format to the standard
9140 one, by providing a parser for the format you wish to
9145 In order to have <tt>dpkg-parsechangelog</tt> run your
9146 parser, you must include a line within the last 40 lines
9147 of your file matching the Perl regular expression:
9148 <tt>\schangelog-format:\s+([0-9a-z]+)\W</tt> The part in
9149 parentheses should be the name of the format. For
9150 example, you might say:
9152 @@@ changelog-format: joebloggs @@@
9154 Changelog format names are non-empty strings of alphanumerics.
9158 If such a line exists then <tt>dpkg-parsechangelog</tt>
9159 will look for the parser as
9160 <file>/usr/lib/dpkg/parsechangelog/<var>format-name</var></file>
9162 <file>/usr/local/lib/dpkg/parsechangelog/<var>format-name</var></file>;
9163 it is an error for it not to find it, or for it not to
9164 be an executable program. The default changelog format
9165 is <tt>dpkg</tt>, and a parser for it is provided with
9166 the <tt>dpkg</tt> package.
9170 The parser will be invoked with the changelog open on
9171 standard input at the start of the file. It should read
9172 the file (it may seek if it wishes) to determine the
9173 information required and return the parsed information
9174 to standard output in the form of a series of control
9175 fields in the standard format. By default it should
9176 return information about only the most recent version in
9177 the changelog; it should accept a
9178 <tt>-v<var>version</var></tt> option to return changes
9179 information from all versions present <em>strictly
9180 after</em> <var>version</var>, and it should then be an
9181 error for <var>version</var> not to be present in the
9187 <list compact="compact">
9189 <p><qref id="pkg-f-Source"><tt>Source</tt></qref></p>
9192 <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
9196 <qref id="pkg-f-Distribution"><tt>Distribution</tt></qref>
9201 <p><qref id="pkg-f-Urgency"><tt>Urgency</tt></qref> (mandatory)</p>
9205 <qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref>
9210 <p><qref id="pkg-f-Date"><tt>Date</tt></qref></p>
9214 <qref id="pkg-f-Changes"><tt>Changes</tt></qref>
9221 If several versions are being returned (due to the use
9222 of <tt>-v</tt>), the urgency value should be of the
9223 highest urgency code listed at the start of any of the
9224 versions requested followed by the concatenated
9225 (space-separated) comments from all the versions
9226 requested; the maintainer, version, distribution and
9227 date should always be from the most recent version.
9231 For the format of the <tt>Changes</tt> field see <ref
9232 id="pkg-f-Changes">.
9236 If the changelog format which is being parsed always or
9237 almost always leaves a blank line between individual
9238 change notes these blank lines should be stripped out,
9239 so as to make the resulting output compact.
9243 If the changelog format does not contain date or package
9244 name information this information should be omitted from
9245 the output. The parser should not attempt to synthesise
9246 it or find it from other sources.
9250 If the changelog does not have the expected format the
9251 parser should exit with a nonzero exit status, rather
9252 than trying to muddle through and possibly generating
9257 A changelog parser may not interact with the user at
9261 <!-- FIXME: section pkg-srcsubstvars is the same as srcsubstvars -->
9263 <sect1 id="pkg-srcsubstvars"><heading><file>debian/substvars</file>
9264 and variable substitutions
9268 When <prgn>dpkg-gencontrol</prgn>,
9269 <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
9270 generate control files they do variable substitutions on
9271 their output just before writing it. Variable
9272 substitutions have the form
9273 <tt>${<var>variable-name</var>}</tt>. The optional file
9274 <file>debian/substvars</file> contains variable substitutions
9275 to be used; variables can also be set directly from
9276 <file>debian/rules</file> using the <tt>-V</tt> option to the
9277 source packaging commands, and certain predefined
9278 variables are available.
9282 This file is usually generated and modified dynamically by
9283 <file>debian/rules</file> targets, in which case it must be
9284 removed by the <tt>clean</tt> target.
9288 See <manref name="dpkg-source" section="1"> for full
9289 details about source variable substitutions, including the
9290 format of <file>debian/substvars</file>.</p>
9293 <sect1><heading><file>debian/files</file>
9297 This file is not a permanent part of the source tree; it
9298 is used while building packages to record which files are
9299 being generated. <prgn>dpkg-genchanges</prgn> uses it
9300 when it generates a <file>.changes</file> file.
9304 It should not exist in a shipped source package, and so it
9305 (and any backup files or temporary files such as
9306 <file>files.new</file>
9308 <file>files.new</file> is used as a temporary file by
9309 <prgn>dpkg-gencontrol</prgn> and
9310 <prgn>dpkg-distaddfile</prgn> - they write a new
9311 version of <file>files</file> here before renaming it,
9312 to avoid leaving a corrupted copy if an error
9314 </footnote>) should be removed by the
9315 <tt>clean</tt> target. It may also be wise to
9316 ensure a fresh start by emptying or removing it at the
9317 start of the <tt>binary</tt> target.
9321 <prgn>dpkg-gencontrol</prgn> adds an entry to this file
9322 for the <file>.deb</file> file that will be created by
9323 <prgn>dpkg-deb</prgn> from the control file that it
9324 generates, so for most packages all that needs to be done
9325 with this file is to delete it in <tt>clean</tt>.
9329 If a package upload includes files besides the source
9330 package and any binary packages whose control files were
9331 made with <prgn>dpkg-gencontrol</prgn> then they should be
9332 placed in the parent of the package's top-level directory
9333 and <prgn>dpkg-distaddfile</prgn> should be called to add
9334 the file to the list in <file>debian/files</file>.</p>
9337 <sect1><heading><file>debian/tmp</file>
9341 This is the canonical temporary location for the
9342 construction of binary packages by the <tt>binary</tt>
9343 target. The directory <file>tmp</file> serves as the root of
9344 the filesystem tree as it is being constructed (for
9345 example, by using the package's upstream makefiles install
9346 targets and redirecting the output there), and it also
9347 contains the <tt>DEBIAN</tt> subdirectory. See <ref
9348 id="pkg-bincreating">.
9352 If several binary packages are generated from the same
9353 source tree it is usual to use several
9354 <file>debian/tmp<var>something</var></file> directories, for
9355 example <file>tmp-a</file> or <file>tmp-doc</file>.
9359 Whatever <file>tmp</file> directories are created and used by
9360 <tt>binary</tt> must of course be removed by the
9361 <tt>clean</tt> target.</p></sect1>
9365 <sect id="pkg-sourcearchives"><heading>Source packages as archives
9369 As it exists on the FTP site, a Debian source package
9370 consists of three related files. You must have the right
9371 versions of all three to be able to use them.
9376 <tag>Debian source control file - <tt>.dsc</tt></tag>
9380 This file contains a series of fields, identified and
9381 separated just like the fields in the control file of
9382 a binary package. The fields are listed below; their
9383 syntax is described above, in <ref id="pkg-controlfields">.
9384 <list compact="compact">
9386 <p><qref id="pkg-f-Source"><tt>Source</tt></qref></p>
9389 <p><qref id="versions"><tt>Version</tt></qref></p>
9392 <p><qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref></p>
9395 <p><qref id="pkg-f-Binary"><tt>Binary</tt></qref></p>
9398 <p><qref id="pkg-f-Architecture"><tt>Architecture</tt></qref></p>
9402 <qref id="relationships"><tt>Build-Depends</tt> et
9403 al.</qref> (source package interrelationships)
9408 <qref id="pkg-f-Standards-Version"><tt>Standards-Version</tt></qref></p>
9411 <p><qref id="pkg-f-Files"><tt>Files</tt></qref></p>
9416 The source package control file is generated by
9417 <prgn>dpkg-source</prgn> when it builds the source
9418 archive, from other files in the source package,
9419 described above. When unpacking it is checked against
9420 the files and directories in the other parts of the
9421 source package, as described below.</p>
9425 Original source archive -
9427 <var>package</var>_<var>upstream-version</var>.orig.tar.gz
9434 This is a compressed (with <tt>gzip -9</tt>)
9435 <prgn>tar</prgn> file containing the source code from
9436 the upstream authors of the program. The tarfile
9437 unpacks into a directory
9438 <file><var>package</var>-<var>upstream-version</var>.orig</file>,
9439 and does not contain files anywhere other than in
9440 there or in its subdirectories.</p>
9444 Debianisation diff -
9446 <var>package</var>_<var>upstream_version-revision</var>.diff.gz
9452 This is a unified context diff (<tt>diff -u</tt>)
9453 giving the changes which are required to turn the
9454 original source into the Debian source. These changes
9455 may only include editing and creating plain files.
9456 The permissions of files, the targets of symbolic
9457 links and the characteristics of special files or
9458 pipes may not be changed and no files may be removed
9463 All the directories in the diff must exist, except the
9464 <file>debian</file> subdirectory of the top of the source
9465 tree, which will be created by
9466 <prgn>dpkg-source</prgn> if necessary when unpacking.
9470 The <prgn>dpkg-source</prgn> program will
9471 automatically make the <file>debian/rules</file> file
9472 executable (see below).</p></item>
9477 If there is no original source code - for example, if the
9478 package is specially prepared for Debian or the Debian
9479 maintainer is the same as the upstream maintainer - the
9480 format is slightly different: then there is no diff, and the
9482 <file><var>package</var>_<var>version</var>.tar.gz</file> and
9483 contains a directory
9484 <file><var>package</var>-<var>version</var></file>.
9488 <sect><heading>Unpacking a Debian source package without
9489 <prgn>dpkg-source</prgn>
9493 <tt>dpkg-source -x</tt> is the recommended way to unpack a
9494 Debian source package. However, if it is not available it
9495 is possible to unpack a Debian source archive as follows:
9496 <enumlist compact="compact">
9499 Untar the tarfile, which will create a <file>.orig</file>
9503 <p>Rename the <file>.orig</file> directory to
9504 <file><var>package</var>-<var>version</var></file>.</p>
9508 Create the subdirectory <file>debian</file> at the top of
9509 the source tree.</p>
9511 <item><p>Apply the diff using <tt>patch -p0</tt>.</p>
9513 <item><p>Untar the tarfile again if you want a copy of the original
9514 source code alongside the Debianised version.</p>
9519 It is not possible to generate a valid Debian source archive
9520 without using <prgn>dpkg-source</prgn>. In particular,
9521 attempting to use <prgn>diff</prgn> directly to generate the
9522 <file>.diff.gz</file> file will not work.
9525 <sect1><heading>Restrictions on objects in source packages
9529 The source package may not contain any hard links
9531 This is not currently detected when building source
9532 packages, but only when extracting
9536 Hard links may be permitted at some point in the
9537 future, but would require a fair amount of
9539 </footnote>, device special files, sockets or setuid or
9542 Setgid directories are allowed.
9547 The source packaging tools manage the changes between the
9548 original and Debianised source using <prgn>diff</prgn> and
9549 <prgn>patch</prgn>. Turning the original source tree as
9550 included in the <file>.orig.tar.gz</file> into the debianised
9551 source must not involve any changes which cannot be
9552 handled by these tools. Problematic changes which cause
9553 <prgn>dpkg-source</prgn> to halt with an error when
9554 building the source package are:
9555 <list compact="compact">
9556 <item><p>Adding or removing symbolic links, sockets or pipes.</p>
9558 <item><p>Changing the targets of symbolic links.</p>
9560 <item><p>Creating directories, other than <file>debian</file>.</p>
9562 <item><p>Changes to the contents of binary files.</p></item>
9563 </list> Changes which cause <prgn>dpkg-source</prgn> to
9564 print a warning but continue anyway are:
9565 <list compact="compact">
9568 Removing files, directories or symlinks.
9570 Renaming a file is not treated specially - it is
9571 seen as the removal of the old file (which
9572 generates a warning, but is otherwise ignored),
9573 and the creation of the new one.
9579 Changed text files which are missing the usual final
9580 newline (either in the original or the modified
9585 Changes which are not represented, but which are not detected by
9586 <prgn>dpkg-source</prgn>, are:
9587 <list compact="compact">
9588 <item><p>Changing the permissions of files (other than
9589 <file>debian/rules</file>) and directories.</p></item>
9594 The <file>debian</file> directory and <file>debian/rules</file>
9595 are handled specially by <prgn>dpkg-source</prgn> - before
9596 applying the changes it will create the <file>debian</file>
9597 directory, and afterwards it will make
9598 <file>debian/rules</file> world-exectuable.
9604 <appendix id="pkg-controlfields"><heading>Control files and their
9605 fields (from old Packaging Manual)
9609 Many of the tools in the <prgn>dpkg</prgn> suite manipulate
9610 data in a common format, known as control files. Binary and
9611 source packages have control data as do the <file>.changes</file>
9612 files which control the installation of uploaded files, and
9613 <prgn>dpkg</prgn>'s internal databases are in a similar
9617 <sect><heading>Syntax of control files
9621 A file consists of one or more paragraphs of fields. The
9622 paragraphs are separated by blank lines. Some control files
9623 only allow one paragraph; others allow several, in which
9624 case each paragraph often refers to a different package.
9628 Each paragraph is a series of fields and values; each field
9629 consists of a name, followed by a colon and the value. It
9630 ends at the end of the line. Horizontal whitespace (spaces
9631 and tabs) may occur before or after the value and is ignored
9632 there; it is conventional to put a single space after the
9637 Some fields' values may span several lines; in this case
9638 each continuation line <em>must</em> start with a space or
9639 tab. Any trailing spaces or tabs at the end of individual
9640 lines of a field value are ignored.
9644 Except where otherwise stated only a single line of data is
9645 allowed and whitespace is not significant in a field body.
9646 Whitespace may never appear inside names (of packages,
9647 architectures, files or anything else), version numbers or
9648 in between the characters of multi-character version
9653 Field names are not case-sensitive, but it is usual to
9654 capitalise the field names using mixed case as shown below.
9658 Blank lines, or lines consisting only of spaces and tabs,
9659 are not allowed within field values or between fields - that
9660 would mean a new paragraph.
9664 It is important to note that there are several fields which
9665 are optional as far as <prgn>dpkg</prgn> and the related
9666 tools are concerned, but which must appear in every Debian
9667 package, or whose omission may cause problems.
9671 <sect><heading>List of fields
9674 <sect1 id="pkg-f-Package"><heading><tt>Package</tt>
9678 The name of the binary package. Package names consist of
9679 the alphanumerics and <tt>+</tt> <tt>-</tt> <tt>.</tt>
9680 (plus, minus and full stop).
9682 The characters <tt>@</tt> <tt>:</tt> <tt>=</tt>
9683 <tt>%</tt> <tt>_</tt> (at, colon, equals, percent
9684 and underscore) used to be legal and are still
9685 accepted when found in a package file, but may not be
9686 used in new packages.
9691 They must be at least two characters and must start with
9692 an alphanumeric. In current versions of dpkg they are
9693 sort of case-sensitive<footnote>
9695 </footnote>; use lowercase package names unless
9696 the package you're building (or referring to, in other
9697 fields) is already using uppercase.
9701 <sect1 id="pkg-f-Version"><heading><tt>Version</tt>
9705 This lists the source or binary package's version number -
9706 see <ref id="versions">.
9711 <sect1 id="pkg-f-Architecture"><heading><tt>Architecture</tt>
9715 This is the architecture string; it is a single word for
9716 the Debian architecture.
9720 <prgn>dpkg</prgn> will check the declared architecture of
9721 a binary package against its own compiled-in value before
9726 The special value <tt>all</tt> indicates that the package
9727 is architecture-independent.
9731 In the main <file>debian/control</file> file in the source
9732 package, or in the source package control file
9733 <file>.dsc</file>, a list of architectures (separated by
9734 spaces) is also allowed, as is the special value
9735 <tt>any</tt>. A list indicates that the source will build
9736 an architecture-dependent package, and will only work
9737 correctly on the listed architectures. <tt>any</tt>
9738 indicates that though the source package isn't dependent
9739 on any particular architecture and should compile fine on
9740 any one, the binary package(s) produced are not
9741 architecture-independent but will instead be specific to
9742 whatever the current build architecture is.
9746 In a <file>.changes</file> file the <tt>Architecture</tt>
9747 field lists the architecture(s) of the package(s)
9748 currently being uploaded. This will be a list; if the
9749 source for the package is being uploaded too the special
9750 entry <tt>source</tt> is also present.
9754 See <ref id="pkg-debianrules"> for information how to get the
9755 architecture for the build process.
9759 <sect1 id="pkg-f-Maintainer"><heading><tt>Maintainer</tt>
9763 The package maintainer's name and email address. The name
9764 should come first, then the email address inside angle
9765 brackets <tt><></tt> (in RFC822 format).
9769 If the maintainer's name contains a full stop then the
9770 whole field will not work directly as an email address due
9771 to a misfeature in the syntax specified in RFC822; a
9772 program using this field as an address must check for this
9773 and correct the problem if necessary (for example by
9774 putting the name in round brackets and moving it to the
9775 end, and bringing the email address forward).
9779 In a <file>.changes</file> file or parsed changelog data this
9780 contains the name and email address of the person
9781 responsible for the particular version in question - this
9782 may not be the package's usual maintainer.
9786 This field is usually optional in as far as the
9787 <prgn>dpkg</prgn> are concerned, but its absence when
9788 building packages usually generates a warning.</p>
9791 <sect1 id="pkg-f-Source"><heading><tt>Source</tt>
9795 This field identifies the source package name.
9799 In a main source control information or a
9800 <file>.changes</file> or <file>.dsc</file> file or parsed
9801 changelog data this may contain only the name of the
9806 In the control file of a binary package (or in a
9807 <file>Packages</file> file) it may be followed by a version
9808 number in parentheses.
9810 It is usual to leave a space after the package name if
9811 a version number is specified.
9812 </footnote> This version number may be omitted (and is, by
9813 <prgn>dpkg-gencontrol</prgn>) if it has the same value as
9814 the <tt>Version</tt> field of the binary package in
9815 question. The field itself may be omitted from a binary
9816 package control file when the source package has the same
9817 name and version as the binary package.
9821 <sect1><heading>Package interrelationship fields:
9822 <tt>Depends</tt>, <tt>Pre-Depends</tt>,
9823 <tt>Recommends</tt> <tt>Suggests</tt>, <tt>Conflicts</tt>,
9824 <tt>Provides</tt>, <tt>Replaces</tt>
9828 These fields describe the package's relationships with
9829 other packages. Their syntax and semantics are described
9830 in <ref id="relationships">.</p>
9833 <sect1 id="pkg-f-Description"><heading><tt>Description</tt>
9837 In a binary package <tt>Packages</tt> file or main source
9838 control file this field contains a description of the
9839 binary package, in a special format. See <ref
9840 id="descriptions"> for details.
9844 In a <file>.changes</file> file it contains a summary of the
9845 descriptions for the packages being uploaded. The part of
9846 the field before the first newline is empty; thereafter
9847 each line has the name of a binary package and the summary
9848 description line from that binary package. Each line is
9849 indented by one space.</p>
9852 <sect1 id="pkg-f-Essential"><heading><tt>Essential</tt>
9856 This is a boolean field which may occur only in the
9857 control file of a binary package (or in the
9858 <file>Packages</file> file) or in a per-package fields
9859 paragraph of a main source control data file.
9863 If set to <tt>yes</tt> then <prgn>dpkg</prgn> and
9864 <prgn>dselect</prgn> will refuse to remove the package
9865 (though it can be upgraded and/or replaced). The other
9866 possible value is <tt>no</tt>, which is the same as not
9867 having the field at all.</p>
9870 <sect1 id="pkg-f-classification"><heading><tt>Section</tt> and
9875 These two fields classify the package. The
9876 <tt>Priority</tt> represents how important that it is that
9877 the user have it installed; the <tt>Section</tt>
9878 represents an application area into which the package has
9883 When they appear in the <file>debian/control</file> file these
9884 fields give values for the section and priority subfields
9885 of the <tt>Files</tt> field of the <file>.changes</file> file,
9886 and give defaults for the section and priority of the
9891 The section and priority are represented, though not as
9892 separate fields, in the information for each file in the
9893 <qref id="pkg-f-Files"><tt>-File</tt></qref>field of a
9894 <file>.changes</file> file. The section value in a
9895 <file>.changes</file> file is used to decide where to install
9896 a package in the FTP archive.
9900 These fields are not used by by <prgn>dpkg</prgn> proper,
9901 but by <prgn>dselect</prgn> when it sorts packages and
9906 These fields can appear in binary package control files,
9907 in which case they provide a default value in case the
9908 <file>Packages</file> files are missing the information.
9909 <prgn>dpkg</prgn> and <prgn>dselect</prgn> will only use
9910 the value from a <file>.deb</file> file if they have no other
9911 information; a value listed in a <file>Packages</file> file
9912 will always take precedence. By default
9913 <prgn>dpkg-gencontrol</prgn> does not include the section
9914 and priority in the control file of a binary package - use
9915 the <tt>-isp</tt>, <tt>-is</tt> or <tt>-ip</tt> options to
9916 achieve this effect.</p>
9919 <sect1 id="pkg-f-Binary"><heading><tt>Binary</tt>
9923 This field is a list of binary packages.
9927 When it appears in the <file>.dsc</file> file it is the list
9928 of binary packages which a source package can produce. It
9929 does not necessarily produce all of these binary packages
9930 for every architecture. The source control file doesn't
9931 contain details of which architectures are appropriate for
9932 which of the binary packages.
9936 When it appears in a <file>.changes</file> file it lists the
9937 names of the binary packages actually being uploaded.
9941 The syntax is a list of binary packages separated by
9944 A space after each comma is conventional.
9945 </footnote> Currently the packages must be separated using
9946 only spaces in the <file>.changes</file> file.</p>
9949 <sect1 id="pkg-f-Installed-Size"><heading><tt>Installed-Size</tt>
9953 This field appears in the control files of binary
9954 packages, and in the <file>Packages</file> files. It gives
9955 the total amount of disk space required to install the
9960 The disk space is represented in kilobytes as a simple
9964 <sect1 id="pkg-f-Files"><heading><tt>Files</tt>
9968 This field contains a list of files with information about
9969 each one. The exact information and syntax varies with
9970 the context. In all cases the part of the field
9971 contents on the same line as the field name is empty. The
9972 remainder of the field is one line per file, each line
9973 being indented by one space and containing a number of
9974 sub-fields separated by spaces.
9978 In the <file>.dsc</file> (Debian source control) file each
9979 line contains the MD5 checksum, size and filename of the
9980 tarfile and (if applicable) diff file which make up the
9981 remainder of the source package.
9983 That is, the parts which are not the <tt>.dsc</tt>.
9984 </footnote> The exact forms of the filenames are described
9985 in <ref id="pkg-sourcearchives">.
9989 In the <file>.changes</file> file this contains one line per
9990 file being uploaded. Each line contains the MD5 checksum,
9991 size, section and priority and the filename. The section
9992 and priority are the values of the corresponding fields in
9993 the main source control file - see <ref
9994 id="pkg-f-classification">. If no section or priority is
9995 specified then <tt>-</tt> should be used, though section
9996 and priority values must be specified for new packages to
9997 be installed properly.
10001 The special value <tt>byhand</tt> for the section in a
10002 <tt>.changes</tt> file indicates that the file in question
10003 is not an ordinary package file and must by installed by
10004 hand by the distribution maintainers. If the section is
10005 <tt>byhand</tt> the priority should be <tt>-</tt>.
10009 If a new Debian revision of a package is being shipped and
10010 no new original source archive is being distributed the
10011 <tt>.dsc</tt> must still contain the <tt>Files</tt> field
10012 entry for the original source archive
10013 <file><var>package</var>-<var>upstream-version</var>.orig.tar.gz</file>,
10014 but the <file>.changes</file> file should leave it out. In
10015 this case the original source archive on the distribution
10016 site must match exactly, byte-for-byte, the original
10017 source archive which was used to generate the
10018 <file>.dsc</file> file and diff which are being uploaded.</p>
10023 id="pkg-f-Standards-Version"><heading><tt>Standards-Version</tt>
10027 The most recent version of the standards (the Debian Policy
10028 and associated texts) with which the package complies. This
10029 is updated manually when editing the source package to
10030 conform to newer standards; it can sometimes be used to
10031 tell when a package needs attention.
10035 Its format is the same as that of a version number except
10036 that no epoch or Debian revision is allowed - see <ref
10037 id="versions">.</p>
10041 <sect1 id="pkg-f-Distribution"><heading><tt>Distribution</tt>
10045 In a <file>.changes</file> file or parsed changelog output
10046 this contains the (space-separated) name(s) of the
10047 distribution(s) where this version of the package should
10048 be or was installed. Distribution names follow the rules
10049 for package names. (See <ref id="pkg-f-Package">).
10053 Current distribution values are:
10055 <tag><em>stable</em></tag>
10058 This is the current "released" version of Debian
10059 GNU/Linux. A new version is released approximately
10060 every 3 months after the <em>development</em> code has
10061 been <em>frozen</em> for a month of testing. Once the
10062 distribution is <em>stable</em> only major bug fixes
10063 are allowed. When changes are made to this
10064 distribution, the release number is increased
10065 (for example: 1.2r1 becomes 1.2r2 then 1.2r3, etc).
10069 <tag><em>unstable</em></tag>
10072 This distribution value refers to the
10073 <em>developmental</em> part of the Debian distribution
10074 tree. New packages, new upstream versions of packages
10075 and bug fixes go into the <em>unstable</em> directory
10076 tree. Download from this distribution at your own
10080 <tag><em>contrib</em></tag>
10083 The packages with this distribution value do not meet
10084 the criteria for inclusion in the main Debian
10085 distribution as defined by the Policy Manual, but meet
10086 the criteria for the <em>contrib</em>
10087 Distribution. There is currently no distinction
10088 between stable and unstable packages in the
10089 <em>contrib</em> or <em>non-free</em>
10090 distributions. Use your best judgement in downloading
10091 from this Distribution.</p>
10094 <tag><em>non-free</em></tag>
10097 Like the packages in the <em>contrib</em> seciton,
10098 the packages in <em>non-free</em> do not meet the
10099 criteria for inclusion in the main Debian distribution
10100 as defined by the Policy Manual. Again, use your best
10101 judgement in downloading from this Distribution.</p>
10103 <tag><em>experimental</em></tag>
10106 The packages with this distribution value are deemed
10107 by their maintainers to be high risk. Oftentimes they
10108 represent early beta or developmental packages from
10109 various sources that the maintainers want people to
10110 try, but are not ready to be a part of the other parts
10111 of the Debian distribution tree. Download at your own
10115 <tag><em>frozen</em></tag>
10118 From time to time, (currently, every 3 months) the
10119 <em>unstable</em> distribution enters a state of
10120 "code-freeze" in anticipation of release as a
10121 <em>stable</em> version. During this period of testing
10122 (usually 4 weeks) only fixes for existing or
10123 newly-discovered bugs will be allowed.
10126 </taglist> You should list <em>all</em> distributions that
10127 the package should be installed into. Except in unusual
10128 circumstances, installations to <em>stable</em> should also
10129 go into <em>frozen</em> (if it exists) and
10130 <em>unstable</em>. Likewise, installations into
10131 <em>frozen</em> should also go into <em>unstable</em>.</p>
10134 <sect1 id="pkg-f-Urgency"><heading><tt>Urgency</tt>
10138 This is a description of how important it is to upgrade to
10139 this version from previous ones. It consists of a single
10140 keyword usually taking one of the values <tt>LOW</tt>,
10141 <tt>MEDIUM</tt> or <tt>HIGH</tt>) followed by an optional
10142 commentary (separated by a space) which is usually in
10143 parentheses. For example:
10145 Urgency: LOW (HIGH for diversions users)
10150 This field appears in the <file>.changes</file> file and in
10151 parsed changelogs; its value appears as the value of the
10152 <tt>urgency</tt> attribute in a <prgn>dpkg</prgn>-style
10153 changelog (see <ref id="pkg-dpkgchangelog">).
10157 Urgency keywords are not case-sensitive.</p>
10160 <sect1 id="pkg-f-Date"><heading><tt>Date</tt>
10164 In <tt>.changes</tt> files and parsed changelogs, this
10165 gives the date the package was built or last edited.</p>
10168 <sect1 id="pkg-f-Format"><heading><tt>Format</tt>
10172 This field occurs in <file>.changes</file> files, and
10173 specifies a format revision for the file. The format
10174 described here is version <tt>1.5</tt>. The syntax of the
10175 format value is the same as that of a package version
10176 number except that no epoch or Debian revision is allowed
10177 - see <ref id="versions">.</p>
10180 <sect1 id="pkg-f-Changes"><heading><tt>Changes</tt>
10184 In a <file>.changes</file> file or parsed changelog this field
10185 contains the human-readable changes data, describing the
10186 differences between the last version and the current one.
10190 There should be nothing in this field before the first
10191 newline; all the subsequent lines must be indented by at
10192 least one space; blank lines must be represented by a line
10193 consiting only of a space and a full stop.
10197 Each version's change information should be preceded by a
10198 "title" line giving at least the version, distribution(s)
10199 and urgency, in a human-readable way.
10203 If data from several versions is being returned the entry
10204 for the most recent version should be returned first, and
10205 entries should be separated by the representation of a
10206 blank line (the "title" line may also be followed by the
10207 representation of blank line).</p>
10210 <sect1 id="pkg-f-Filename"><heading><tt>Filename</tt> and
10211 <tt>MSDOS-Filename</tt>
10215 These fields in <tt>Packages</tt> files give the
10216 filename(s) of (the parts of) a package in the
10217 distribution directories, relative to the root of the
10218 Debian hierarchy. If the package has been split into
10219 several parts the parts are all listed in order, separated
10224 <sect1 id="pkg-f-Size">
10225 <heading><tt>Size</tt> and <tt>MD5sum</tt></heading>
10228 These fields in <file>Packages</file> files give the size (in
10229 bytes, expressed in decimal) and MD5 checksum of the
10230 file(s) which make(s) up a binary package in the
10231 distribution. If the package is split into several parts
10232 the values for the parts are listed in order, separated by
10237 <sect1 id="pkg-f-Status">
10238 <heading><tt>Status</tt></heading>
10241 This field in <prgn>dpkg</prgn>'s status file records
10242 whether the user wants a package installed, removed or
10243 left alone, whether it is broken (requiring
10244 reinstallation) or not and what its current state on the
10245 system is. Each of these pieces of information is a
10250 <sect1 id="pkg-f-Config-Version">
10251 <heading><tt>Config-Version</tt></heading>
10254 If a package is not installed or not configured, this
10255 field in <prgn>dpkg</prgn>'s status file records the last
10256 version of the package which was successfully
10261 <sect1 id="pkg-f-Conffiles">
10262 <heading><tt>Conffiles</tt></heading>
10265 This field in <prgn>dpkg</prgn>'s status file contains
10266 information about the automatically-managed configuration
10267 files held by a package. This field should <em>not</em>
10268 appear anywhere in a package!
10273 <heading>Obsolete fields</heading>
10276 These are still recognised by <prgn>dpkg</prgn> but should
10277 not appear anywhere any more.
10279 <taglist compact="compact">
10281 <tag><tt>Revision</tt></tag>
10282 <tag><tt>Package-Revision</tt></tag>
10283 <tag><tt>Package_Revision</tt></tag>
10285 The Debian revision part of the package version was
10286 at one point in a separate control file field. This
10287 field went through several names.
10290 <tag><tt>Recommended</tt></tag>
10291 <item>Old name for <tt>Recommends</tt>.</item>
10293 <tag><tt>Optional</tt></tag>
10294 <item>Old name for <tt>Suggests</tt>.</item>
10296 <tag><tt>Class</tt></tag>
10297 <item>Old name for <tt>Priority</tt>.</item>
10306 <appendix id="pkg-conffiles">
10307 <heading>Configuration file handling (from old Packaging Manual)</heading>
10310 <prgn>dpkg</prgn> can do a certain amount of automatic
10311 handling of package configuration files.
10315 Whether this mechanism is appropriate depends on a number of
10316 factors, but basically there are two approaches to any
10317 particular configuration file.
10321 The easy method is to ship a best-effort configuration in the
10322 package, and use <prgn>dpkg</prgn>'s conffile mechanism to
10323 handle updates. If the user is unlikely to want to edit the
10324 file, but you need them to be able to without losing their
10325 changes, and a new package with a changed version of the file
10326 is only released infrequently, this is a good approach.
10330 The hard method is to build the configuration file from
10331 scratch in the <prgn>postinst</prgn> script, and to take the
10332 responsibility for fixing any mistakes made in earlier
10333 versions of the package automatically. This will be
10334 appropriate if the file is likely to need to be different on
10338 <sect><heading>Automatic handling of configuration files by
10343 A package may contain a control area file called
10344 <tt>conffiles</tt>. This file should be a list of filenames
10345 of configuration files needing automatic handling, separated
10346 by newlines. The filenames should be absolute pathnames,
10347 and the files referred to should actually exist in the
10352 When a package is upgraded <prgn>dpkg</prgn> will process
10353 the configuration files during the configuration stage,
10354 shortly before it runs the package's <prgn>postinst</prgn>
10359 For each file it checks to see whether the version of the
10360 file included in the package is the same as the one that was
10361 included in the last version of the package (the one that is
10362 being upgraded from); it also compares the version currently
10363 installed on the system with the one shipped with the last
10368 If neither the user nor the package maintainer has changed
10369 the file, it is left alone. If one or the other has changed
10370 their version, then the changed version is preferred - i.e.,
10371 if the user edits their file, but the package maintainer
10372 doesn't ship a different version, the user's changes will
10373 stay, silently, but if the maintainer ships a new version
10374 and the user hasn't edited it the new version will be
10375 installed (with an informative message). If both have
10376 changed their version the user is prompted about the problem
10377 and must resolve the differences themselves.
10381 The comparisons are done by calculating the MD5 message
10382 digests of the files, and storing the MD5 of the file as it
10383 was included in the most recent version of the package.
10387 When a package is installed for the first time
10388 <prgn>dpkg</prgn> will install the file that comes with it,
10389 unless that would mean overwriting a file already on the
10394 However, note that <prgn>dpkg</prgn> will <em>not</em>
10395 replace a conffile that was removed by the user (or by a
10396 script). This is necessary because with some programs a
10397 missing file produces an effect hard or impossible to
10398 achieve in another way, so that a missing file needs to be
10399 kept that way if the user did it.
10403 Note that a package should <em>not</em> modify a
10404 <prgn>dpkg</prgn>-handled conffile in its maintainer
10405 scripts. Doing this will lead to <prgn>dpkg</prgn> giving
10406 the user confusing and possibly dangerous options for
10407 conffile update when the package is upgraded.</p>
10410 <sect><heading>Fully-featured maintainer script configuration
10415 For files which contain site-specific information such as
10416 the hostname and networking details and so forth, it is
10417 better to create the file in the package's
10418 <prgn>postinst</prgn> script.
10422 This will typically involve examining the state of the rest
10423 of the system to determine values and other information, and
10424 may involve prompting the user for some information which
10425 can't be obtained some other way.
10429 When using this method there are a couple of important
10430 issues which should be considered:
10434 If you discover a bug in the program which generates the
10435 configuration file, or if the format of the file changes
10436 from one version to the next, you will have to arrange for
10437 the postinst script to do something sensible - usually this
10438 will mean editing the installed configuration file to remove
10439 the problem or change the syntax. You will have to do this
10440 very carefully, since the user may have changed the file,
10441 perhaps to fix the very problem that your script is trying
10442 to deal with - you will have to detect these situations and
10443 deal with them correctly.
10447 If you do go down this route it's probably a good idea to
10448 make the program that generates the configuration file(s) a
10449 separate program in <file>/usr/sbin</file>, by convention called
10450 <file><var>package</var>config</file> and then run that if
10451 appropriate from the post-installation script. The
10452 <tt><var>package</var>config</tt> program should not
10453 unquestioningly overwrite an existing configuration - if its
10454 mode of operation is geared towards setting up a package for
10455 the first time (rather than any arbitrary reconfiguration
10456 later) you should have it check whether the configuration
10457 already exists, and require a <tt>--force</tt> flag to
10458 overwrite it.</p></sect>
10461 <appendix id="pkg-alternatives"><heading>Alternative versions of
10462 an interface - <prgn>update-alternatives</prgn> (from old
10467 When several packages all provide different versions of the
10468 same program or file it is useful to have the system select a
10469 default, but to allow the system administrator to change it
10470 and have their decisions respected.
10474 For example, there are several versions of the <prgn>vi</prgn>
10475 editor, and there is no reason to prevent all of them from
10476 being installed at once, each under their own name
10477 (<prgn>nvi</prgn>, <prgn>vim</prgn> or whatever).
10478 Nevertheless it is desirable to have the name <tt>vi</tt>
10479 refer to something, at least by default.
10483 If all the packages involved cooperate, this can be done with
10484 <prgn>update-alternatives</prgn>.
10488 Each package provides its own version under its own name, and
10489 calls <prgn>update-alternatives</prgn> in its postinst to
10490 register its version (and again in its prerm to deregister
10495 See the manpage <manref name="update-alternatives"
10496 section="8"> for details.
10500 If <prgn>update-alternatives</prgn> does not seem appropriate
10501 you may wish to consider using diversions instead.</p>
10504 <appendix id="pkg-diversions"><heading>Diversions - overriding a
10505 package's version of a file (from old Packaging Manual)
10509 It is possible to have <prgn>dpkg</prgn> not overwrite a file
10510 when it reinstalls the package it belongs to, and to have it
10511 put the file from the package somewhere else instead.
10515 This can be used locally to override a package's version of a
10516 file, or by one package to override another's version (or
10517 provide a wrapper for it).
10521 Before deciding to use a diversion, read <ref
10522 id="pkg-alternatives"> to see if you really want a diversion
10523 rather than several alternative versions of a program.
10527 There is a diversion list, which is read by <prgn>dpkg</prgn>,
10528 and updated by a special program <prgn>dpkg-divert</prgn>.
10529 Please see <manref name="dpkg-divert" section="8"> for full
10530 details of its operation.
10534 When a package wishes to divert a file from another, it should
10535 call <prgn>dpkg-divert</prgn> in its preinst to add the
10536 diversion and rename the existing file. For example,
10537 supposing that a <prgn>smailwrapper</prgn> package wishes to
10538 install a wrapper around <file>/usr/sbin/smail</file>:
10540 if [ install = "$1" ]; then
10541 dpkg-divert --package smailwrapper --add --rename \
10542 --divert /usr/sbin/smail.real /usr/sbin/smail
10544 </example> Testing <tt>$1</tt> is necessary so that the script
10545 doesn't try to add the diversion again when
10546 <prgn>smailwrapper</prgn> is upgraded. The <tt>--package
10547 smailwrapper</tt> ensures that <prgn>smailwrapper</prgn>'s
10548 copy of <file>/usr/sbin/smail</file> can bypass the diversion and
10549 get installed as the true version.
10553 The postrm has to do the reverse:
10555 if [ remove = "$1" ]; then
10556 dpkg-divert --package smailwrapper --remove --rename \
10557 --divert /usr/sbin/smail.real /usr/sbin/smail
10563 Do not attempt to divert a file which is vitally important for
10564 the system's operation - when using <prgn>dpkg-divert</prgn>
10565 there is a time, after it has been diverted but before
10566 <prgn>dpkg</prgn> has installed the new version, when the file
10567 does not exist.</p>
10572 <!-- vim:set ai et sts=2 sw=2 tw=76: -->