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;
8 Debian GNU/Linux Policy Manual.
9 Copyright (C)1996,1997,1998 Ian Jackson and Christian Schwarz;
10 released under the terms of the GNU
11 General Public License, version 2 or (at your option) any later.
12 Initial version 1996, Ian Jackson, ijackson@gnu.ai.mit.edu
13 Revised November 27, 1996, David A. Morris, bweaver@debian.org
14 New sections March 15, 1997, Christian Schwarz, schwarz@debian.org
15 Reworked/Restructured April-July 1997, Christian Schwarz, schwarz@debian.org
16 Maintainer since 1997, Christian Schwarz, schwarz@debian.org
17 Christoph Lameter contributed the "Web Standard"
18 The debian-policy mailing list has taken responsibility for the
19 contents of this document since September 1998, with the package
20 maintainers responsible for packaging administrivia only.
25 <title>Debian Policy Manual</title>
27 <name>Ian Jackson </name>
28 <email>ijackson@gnu.ai.mit.edu</email>
31 <name>Christian Schwarz</name>
32 <email>schwarz@debian.org</email>
35 <name>revised: David A. Morris</name>
36 <email>bweaver@debian.org</email>
39 <name>The Debian Policy mailing List</name>
40 <email>debian-policy@lists.debian.org</email>
42 <version>version &version;, &date;</version>
45 This manual describes the policy requirements for the Debian
46 GNU/Linux distribution. This includes the structure and
47 contents of the Debian archive and several design issues of
48 the operating system, as well as technical requirements that
49 each package must satisfy to be included in the distribution.
50 The policy package itself is maintained by a group of
51 maintainers that have no editorial powers. The current list
55 <p>Julian Gilbey <email>jdg@debian.org</email></p>
58 <p>Manoj Srivastava <email>srivasta@debian.org</email></p>
66 Copyright ©1996,1997,1998 Ian Jackson
67 and Christian Schwarz.
70 This manual is free software; you may redistribute it and/or
71 modify it under the terms of the GNU General Public License
72 as published by the Free Software Foundation; either version
73 2, or (at your option) any later version.
77 This is distributed in the hope that it will be useful, but
78 <em>without any warranty</em>; without even the implied
79 warranty of merchantability or fitness for a particular
80 purpose. See the GNU General Public License for more
85 A copy of the GNU General Public License is available as
86 <file>/usr/share/common-licenses/GPL</file> in the Debian GNU/Linux
87 distribution or on the World Wide Web at
88 <url id="http://www.gnu.org/copyleft/gpl.html"
89 name="The GNU General Public Licence">. You can also
90 obtain it by writing to the Free Software Foundation, Inc.,
91 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
99 <heading>About this manual</heading>
101 <heading>Scope</heading>
103 This manual describes the policy requirements for the Debian
104 GNU/Linux distribution. This includes the structure and
105 contents of the Debian archive and several design issues of the
106 operating system, as well as technical requirements that
107 each package must satisfy to be included in the
113 This manual also describes Debian policy as it relates to
114 creating Debian packages. It is not a tutorial on how to build
115 packages, nor is it exhaustive where it comes to describing
116 the behavior of the packaging system. Instead, this manual
117 attempts to define the interface to the package management
118 system that the developers have to be conversant with.<footnote>
120 Informally, the criteria used for inclusion is that the
121 material meet one of the following requirements:
122 <taglist compact="compact">
123 <tag>Standard interfaces</tag>
126 The material presented represents an interface to
127 the packaging system that is mandated for use, and
128 is used by, a significant number of packages, and
129 therefore should not be changed without peer
130 review. Package maintainers can then rely on this
131 interfaces not changing, and the package
132 management software authors need to ensure
133 compatibility with these interface
134 definitions. (Control file and changelog file
135 formats are examples.)
138 <tag>Chosen Convention</tag>
141 If there are a number of technically viable choices
142 that can be made, but one needs to select one of
143 these options for inter-operability. The version
144 number format is one example.
148 Please note that these are not mutually exclusive;
149 selected conventions often become parts of standard
156 The footnotes present in this manual are
157 merely informative, and are not part of Debian policy itself.
162 In this manual, the words <em>must</em>, <em>should</em> and
163 <em>may</em>, and the adjectives <em>required</em>,
164 <em>recommended</em> and <em>optional</em>, are used to
165 distinguish the significance of the various guidelines in
166 this policy document. Packages that do not conform to the
167 guidelines denoted by <em>must</em> (or <em>required</em>)
168 will generally not be considered acceptable for the Debian
169 distribution. Non-conformance with guidelines denoted by
170 <em>should</em> (or <em>recommended</em>) will generally be
171 considered a bug, but will not necessarily render a package
172 unsuitable for distribution. Guidelines denoted by
173 <em>may</em> (or <em>optional</em>) are truly optional and
174 adherence is left to the maintainer's discretion.
177 These classifications are roughly equivalent to the bug
178 severities <em>serious</em> (for <em>must</em> or
179 <em>required</em> directive violations), <em>minor</em>,
180 <em>normal</em> or <em>important</em>
181 (for <em>should</em> or <em>recommended</em> directive
182 violations) and <em>wishlist</em> (for <em>optional</em>
184 <p>Compare RFC 2119. Note, however, that these words are
185 used in a different way in this document.</p>
189 Much of the information presented in this manual will be
190 useful even when building a package which is to be
191 distributed in some other way or is intended for local use
196 <heading>New versions of this document</heading>
198 The current version of this document is always accessible
199 from the Debian FTP server <ftpsite>ftp.debian.org</ftpsite>
201 <ftppath>/debian/doc/package-developer/policy.txt.gz</ftppath>
202 (also available from the same directory are several other
203 formats: <file>policy.html.tar.gz</file>, <file>policy.pdf.gz</file>
204 and <file>policy.ps.gz</file>) or from the <url
205 id="http://www.debian.org/doc/debian-policy/" name="Debian
206 Policy Manual"> webpage.</p>
209 In addition, this manual is distributed via the Debian package
210 <file>debian-policy</file>.
214 The <tt>debian-policy</tt> package also includes the file
215 <file>upgrading-checklist.txt</file> which indicates policy
216 changes between versions of this document.
220 <heading>Feedback</heading>
223 As the Debian GNU/Linux system is continuously evolving this
227 While the authors of this document have tried hard to avoid
228 typos and other errors, these do still occur. If you discover
229 an error in this manual or if you want to give any
230 comments, suggestions, or criticisms please send an email to
231 the Debian Policy List,
232 <email>debian-policy@lists.debian.org</email>, or submit a
233 bug report against the <tt>debian-policy</tt> package.
239 <heading>The Debian Archive</heading>
241 The Debian GNU/Linux system is maintained and distributed as a
242 collection of <em>packages</em>. Since there are so many of
243 them (currently well over 6000), they are split into
244 <em>sections</em> and given <em>priorities</em> to simplify
245 the handling of them.
248 The effort of the Debian project is to build a free operating
249 system, but not every package we want to make accessible is
250 <em>free</em> in our sense (see the Debian Free Software
251 Guidelines, below), or may be imported/exported without
252 restrictions. Thus, the archive is split into the sections
253 <em>main</em>, <em>non-free</em>, <em>contrib</em>,
254 <em>non-US/main</em>, <em>non-US/non-free</em>, and
255 <em>non-US/contrib</em>. The sections are explained in detail
260 The <em>main</em> and the <em>non-US/main</em> sections
261 together form the <em>Debian GNU/Linux distribution</em>.
265 Packages in the other sections are not considered to be part
266 of the Debian distribution, although we support their use and
267 provide infrastructure for them (such as our bug-tracking
268 system and mailing lists). This Debian Policy Manual applies
269 to these packages as well.</p>
271 <sect id="pkgcopyright">
272 <heading>Package copyright and sections</heading>
274 The aims of this section are:
276 <list compact="compact">
278 <p>to allow us to make as much software available as we
282 <p>to allow us to encourage everyone to write free
286 <p>to allow us to make it easy for people to produce
287 CD-ROMs of our system without violating any licenses,
288 import/export restrictions, or any other laws.</p>
293 <heading>The Debian Free Software Guidelines</heading>
295 The Debian Free Software Guidelines (DFSG) form our
296 definition of `free software'. These are:
298 <tag>Free Redistribution
302 The license of a Debian component may not restrict any
303 party from selling or giving away the software as a
304 component of an aggregate software distribution
305 containing programs from several different
306 sources. The license may not require a royalty or
307 other fee for such sale.
314 The program must include source code, and must allow
315 distribution in source code as well as compiled form.
322 The license must allow modifications and derived
323 works, and must allow them to be distributed under the
324 same terms as the license of the original software.
327 <tag>Integrity of The Author's Source Code
331 The license may restrict source-code from being
332 distributed in modified form <em>only</em> if the
333 license allows the distribution of ``patch files''
334 with the source code for the purpose of modifying the
335 program at build time. The license must explicitly
336 permit distribution of software built from modified
337 source code. The license may require derived works to
338 carry a different name or version number from the
339 original software. (This is a compromise. The Debian
340 Project encourages all authors to not restrict any
341 files, source or binary, from being modified.)
344 <tag>No Discrimination Against Persons or Groups
348 The license must not discriminate against any person
352 <tag>No Discrimination Against Fields of Endeavor
356 The license must not restrict anyone from making use
357 of the program in a specific field of endeavor. For
358 example, it may not restrict the program from being
359 used in a business, or from being used for genetic
363 <tag>Distribution of License
367 The rights attached to the program must apply to all
368 to whom the program is redistributed without the need
369 for execution of an additional license by those
373 <tag>License Must Not Be Specific to Debian
377 The rights attached to the program must not depend on
378 the program's being part of a Debian system. If the
379 program is extracted from Debian and used or
380 distributed without Debian but otherwise within the
381 terms of the program's license, all parties to whom
382 the program is redistributed must have the same
383 rights as those that are granted in conjunction with
387 <tag>License Must Not Contaminate Other Software
391 The license must not place restrictions on other
392 software that is distributed along with the licensed
393 software. For example, the license must not insist
394 that all other programs distributed on the same medium
395 must be free software.
398 <tag>Example Licenses
402 The ``GPL,'' ``BSD,'' and ``Artistic'' licenses are
403 examples of licenses that we consider <em>free</em>.
410 <heading>The main section</heading>
412 Every package in <em>main</em> and <em>non-US/main</em>
413 must comply with the DFSG (Debian Free Software
417 In addition, the packages in <em>main</em>
418 <list compact="compact">
421 must not require a package outside of <em>main</em>
422 for compilation or execution (thus, the package must
423 not declare a "Depends", "Recommends", or
424 "Build-Depends" relationship on a non-<em>main</em>
430 must not be so buggy that we refuse to support them,
436 must meet all policy requirements presented in this
443 Similarly, the packages in <em>non-US/main</em>
444 <list compact="compact">
447 must not require a package outside of <em>main</em>
448 or <em>non-US/main</em> for compilation or
454 must not be so buggy that we refuse to support them,
459 must meet all policy requirements presented in this
467 <heading>The contrib section</heading>
469 Every package in <em>contrib</em> and
470 <em>non-US/contrib</em> must comply with the DFSG.
474 In addition, the packages in <em>contrib</em> and
475 <em>non-US/contrib</em>
476 <list compact="compact">
479 must not be so buggy that we refuse to support them,
485 must meet all policy requirements presented in this
493 Furthermore, packages in <em>contrib</em> must not require
494 a package in a <em>non-US</em> section for compilation or
499 Examples of packages which would be included in
500 <em>contrib</em> or <em>non-US/contrib</em> are:
501 <list compact="compact">
504 free packages which require <em>contrib</em>,
505 <em>non-free</em> packages or packages which are not
506 in our archive at all for compilation or execution,
512 wrapper packages or other sorts of free accessories for
520 <heading>The non-free section</heading>
522 Packages must be placed in <em>non-free</em> or
523 <em>non-US/non-free</em> if they are not compliant with
524 the DFSG or are encumbered by patents or other legal
525 issues that make their distribution problematic.
528 In addition, the packages in <em>non-free</em> and
529 <em>non-US/non-free</em>
530 <list compact="compact">
533 must not be so buggy that we refuse to support them,
539 must meet all policy requirements presented in this
540 manual that it is possible for them to meet.<footnote>
542 It is possible that there are policy
543 requirements which the package is unable to
544 meet, for example, if the source is
545 unavailable. These situations will need to be
546 handled on a case-by-case basis.
556 <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.
563 Programs which use patented algorithms that have a
564 restrictied license also need to be stored on "non-us",
565 since that is located in a country where it is not allowed
566 to patent algorithms.
569 A package depends on another package which is distributed
570 via the non-us server has to be stored on the non-us
575 <heading>Further copyright considerations</heading>
577 Every package must be accompanied by a verbatim copy of
578 its copyright and distribution license in the file
579 <file>/usr/share/doc/<var>package</var>/copyright</file>
580 (see <ref id="copyrightfile"> for further details).
583 We reserve the right to restrict files from being included
584 anywhere in our archives if
585 <list compact="compact">
588 their use or distribution would break a law,
593 there is an ethical conflict in their distribution or
599 we would have to sign a license for them, or
604 their distribution would conflict with other project
612 Programs whose authors encourage the user to make
613 donations are fine for the main distribution, provided
614 that the authors do not claim that not donating is
615 immoral, unethical, illegal or something similar; in such
616 a case they must go in <em>non-free</em>.</p>
619 Packages whose copyright permission notices (or patent
620 problems) do not even allow redistribution of binaries
621 only, and where no special permission has been obtained,
622 must not be placed on the Debian FTP site and its mirrors
626 Note that under international copyright law (this applies
627 in the United States, too), <em>no</em> distribution or
628 modification of a work is allowed without an explicit
629 notice saying so. Therefore a program without a copyright
630 notice <em>is</em> copyrighted and you may not do anything
631 to it without risking being sued! Likewise if a program
632 has a copyright notice but no statement saying what is
633 permitted then nothing is permitted.</p>
636 Many authors are unaware of the problems that restrictive
637 copyrights (or lack of copyright notices) can cause for
638 the users of their supposedly-free software. It is often
639 worthwhile contacting such authors diplomatically to ask
640 them to modify their license terms. However, this can be a
641 politically difficult thing to do and you should ask for
642 advice on the <tt>debian-legal</tt> mailing list first, as
647 When in doubt about a copyright, send mail to
648 <email>debian-legal@lists.debian.org</email>. Be prepared
649 to provide us with the copyright statement. Software
650 covered by the GPL, public domain software and BSD-like
651 copyrights are safe; be wary of the phrases `commercial
652 use prohibited' and `distribution restricted'.
656 <heading>Subsections</heading>
659 The packages in the sections <em>main</em>,
660 <em>contrib</em> and <em>non-free</em> are grouped further
661 into <em>subsections</em> to simplify handling.
665 The section and subsection for each package should be
666 specified in the package's <tt>Section</tt> control
667 record. However, the maintainer of the Debian archive
668 may override this selection to ensure the consistency of
669 the Debian distribution. The <tt>Section</tt> field
670 should be of the form:
671 <list compact="compact">
674 <em>subsection</em> if the package is in the
675 <em>main</em> section,
680 <em>section/subsection</em> if the package is in
681 the <em>contrib</em> or <em>non-free</em> section,
687 <tt>non-US</tt>, <tt>non-US/contrib</tt> or
688 <tt>non-US/non-free</tt> if the package is in
689 <em>non-US/main</em>, <em>non-US/contrib</em> or
690 <em>non-US/non-free</em> respectively.
697 The Debian archive maintainers provide the authoritative
698 list of subsections. At present, they are:
699 <em>admin</em>, <em>base</em>, <em>comm</em>,
700 <em>contrib</em>, <em>devel</em>, <em>doc</em>,
701 <em>editors</em>, <em>electronics</em>, <em>games</em>,
702 <em>graphics</em>, <em>hamradio</em>,
703 <em>interpreters</em>, <em>libs</em>, <em>mail</em>,
704 <em>math</em>, <em>misc</em>, <em>net</em>, <em>news</em>,
705 <em>non-US</em>, <em>non-free</em>, <em>oldlibs</em>,
706 <em>otherosfs</em>, <em>science</em>, <em>shells</em>,
707 <em>sound</em>, <em>tex</em>, <em>text</em>,
708 <em>utils</em>, <em>web</em>, <em>x11</em>.
712 <heading>Priorities</heading>
715 Each package should have a <em>priority</em> value, which is
716 included in the package's <em>control record</em>. This
717 information is used by the Debian package management tools
718 to separate high-priority packages from less-important
722 The following <em>priority levels</em> are recognised by the
723 Debian package management tools.
725 <tag><tt>required</tt></tag>
728 Packages which are necessary for the proper
729 functioning of the system. You must not remove these
730 packages or your system may become totally broken and
731 you may not even be able to use <prgn>dpkg</prgn> to
732 put things back. Systems with only the
733 <tt>required</tt> packages are probably unusable, but
734 they do have enough functionality to allow the
735 sysadmin to boot and install more software.</p>
737 <tag><tt>important</tt></tag>
740 Important programs, including those which one would
741 expect to find on any Unix-like system. If the
742 expectation is that an experienced Unix person who
743 found it missing would say `What on earth is going on,
744 where is <prgn>foo</prgn>?', it must be an
745 <tt>important</tt> package.<footnote>
747 This is an important criterion because we are
748 trying to produce, amongst other things, a free
752 Other packages without which the system will not run
753 well or be usable must also have priority
754 <tt>important</tt>. This does
755 <em>not</em> include Emacs, the X Window System, TeX
756 or any other large applications. The
757 <tt>important</tt> packages are just a bare minimum of
758 commonly-expected and necessary tools.</p>
760 <tag><tt>standard</tt></tag>
763 These packages provide a reasonably small but not too
764 limited character-mode system. This is what will be
765 installed by default if the user doesn't select anything
766 else. It doesn't include many large applications.</p>
768 <tag><tt>optional</tt></tag>
771 (In a sense everything that isn't required is
772 optional, but that's not what is meant here.) This is
773 all the software that you might reasonably want to
774 install if you didn't know what it was and don't have
775 specialized requirements. This is a much larger system
776 and includes the X Window System, a full TeX
777 distribution, and many applications. Note that
778 optional packages should not conflict with each other.
781 <tag><tt>extra</tt></tag>
784 This contains all packages that conflict with others
785 with required, important, standard or optional
786 priorities, or are only likely to be useful if you
787 already know what they are or have specialised
794 Packages must not depend on packages with lower priority
795 values (excluding build-time dependencies). In order to
796 ensure this, the priorities of one or more packages may need
802 <heading>Binary packages</heading>
805 The Debian GNU/Linux distribution is based on the Debian
806 package management system, called <prgn>dpkg</prgn>. Thus,
807 all packages in the Debian distribution must be provided
808 in the <tt>.deb</tt> file format.</p>
812 <heading>The package name</heading>
815 Every package must have a name that's unique within the Debian
819 Package names must consist of lower case letters
820 (<tt>a-z</tt>), digits (<tt>0-9</tt>), plus (<tt>+</tt>)
821 and minus (<tt>-</tt>) signs, and periods (<tt>.</tt>).
822 They must be at least two characters long and must start
823 with an alphanumeric character.
827 The package name is part of the file name of the
828 <tt>.deb</tt> file and is included in the control field
834 <heading>The maintainer of a package</heading>
836 Every package must have a Debian maintainer (the
837 maintainer may be one person or a group of people
838 reachable from a common email address, such as a mailing
839 list). The maintainer is responsible for ensuring that
840 the package is placed in the appropriate distributions.
844 The maintainer must be specified in the
845 <tt>Maintainer</tt> control field with their correct name
846 and a working email address. If one person maintains
847 several packages, he/she should try to avoid having
848 different forms of their name and email address in
849 the <tt>Maintainer</tt> fields of those packages.
853 If the maintainer of a package quits from the Debian
854 project, "Debian QA Group"
855 <email>packages@qa.debian.org</email> takes over the
856 maintainership of the package until someone else
857 volunteers for that task. These packages are called
858 <em>orphaned packages</em>.<footnote>
860 The detailed procedure for doing this gracefully can
861 be found in the Debian Developer's Reference, either
862 in the <tt>developers-reference</tt> package, or on
863 the Debian FTP server
864 <ftpsite>ftp.debian.org</ftpsite> as
865 <ftppath>/debian/doc/package-developer/developers-reference.txt.gz</ftppath>
867 id="http://www.debian.org/doc/packaging-manuals/developers-reference/"
868 name="Debian Developer's Reference"> webpage.
876 <heading>The description of a package</heading>
879 Every Debian package must have an extended description
880 stored in the appropriate field of the control record.</p>
883 The description should be written so that it gives the
884 system administrator enough information to decide whether
885 to install the package. This description should not just
886 be copied verbatim from the program's documentation.
887 Instructions for configuring or using the package should
888 not be included (that is what installation scripts,
889 manual pages, info files, etc., are for). Copyright
890 statements and other administrivia should not be included
891 either (that is what the copyright file is for).
897 <heading>Dependencies</heading>
900 Every package must specify the dependency information
901 about other packages that are required for the first to
905 For example, a dependency entry must be provided for any
906 shared libraries required by a dynamically-linked executable
907 binary in a package.</p>
910 Packages are not required to declare any dependencies they
911 have on other packages which are marked <tt>Essential</tt>
912 (see below), and should not do so unless they depend on a
913 particular version of that package.</p>
916 Sometimes, a package requires another package to be installed
917 <em>and</em> configured before it can be installed. In this
918 case, you must specify a <tt>Pre-Depends</tt> entry for
922 You should not specify a <tt>Pre-Depends</tt> entry for a
923 package before this has been discussed on the
924 <tt>debian-devel</tt> mailing list and a consensus about
925 doing that has been reached.</p></sect1>
928 <sect1 id="virtual_pkg_sect">
929 <heading>Virtual packages</heading>
932 Sometimes, there are several packages which offer
933 more-or-less the same functionality. In this case, it's
934 useful to define a <em>virtual package</em> whose name
935 describes that common functionality. (The virtual
936 packages only exist logically, not physically; that's why
937 they are called <em>virtual</em>.) The packages with this
938 particular function will then <em>provide</em> the virtual
939 package. Thus, any other package requiring that function
940 can simply depend on the virtual package without having to
941 specify all possible packages individually.</p>
944 All packages should use virtual package names where
945 appropriate, and arrange to create new ones if necessary.
946 They should not use virtual package names (except privately,
947 amongst a cooperating group of packages) unless they have
948 been agreed upon and appear in the list of virtual package
949 names. (See also <ref id="virtual">)</p>
952 The latest version of the authoritative list of virtual
953 package names can be found on
954 <ftpsite>ftp.debian.org</ftpsite> in
955 <ftppath>/debian/doc/package-developer/virtual-package-names-list.txt</ftppath>
956 or your local mirror. In addition, it is included in the
957 <tt>debian-policy</tt> package. The procedure for updating
958 the list is described at the top of the file.</p></sect1>
962 <heading>Base system</heading>
965 The <tt>base system</tt> is a minimum subset of the Debian
966 GNU/Linux system that is installed before everything else
967 on a new system. Thus, only very few packages are allowed
968 to go into the <tt>base</tt> section to keep the required
969 disk usage very small.</p>
972 Most of these packages will have the priority value
973 <tt>required</tt> or at least <tt>important</tt>, and many
974 of them will be tagged <tt>essential</tt> (see below).</p>
981 <heading>Essential packages</heading>
984 Some packages are tagged <tt>essential</tt>. (They have
985 <tt>Essential: yes</tt> in their package control record.)
986 This flag is used for packages that are <em>essential</em>
990 Since these packages cannot be easily removed (one has to
991 specify an extra <em>force option</em> to
992 <prgn>dpkg</prgn> to do so), this flag must not be used
993 unless absolutely necessary. A shared library package
994 must not be tagged <tt>essential</tt>; dependencies will
995 prevent its premature removal, and we need to be able to
996 remove it when it has been superseded.
1000 Since dpkg will not prevent upgrading of other packages
1001 while an <tt>essential</tt> package is in an unconfigured
1002 state, all <tt>essential</tt> packages must supply all of
1003 their core functionality even when unconfigured. If the
1004 package cannot satisfy this requirement it must not be
1005 tagged as essential, and any packages depending on this
1006 package must instead have explicit dependency fields as
1011 You must not tag any packages <tt>essential</tt> before
1012 this has been discussed on the <tt>debian-devel</tt>
1013 mailing list and a consensus about doing that has been
1018 <heading>Tasks</heading>
1021 The Debian install process allows the user to choose from
1022 a number of common tasks which a Debian system can be used to
1023 perform. Selecting a task with <prgn>tasksel</prgn> causes
1024 a set of packages that are useful in performing that task to be
1029 This set of packages is all available packages which have the
1030 name of the selected task in the <tt>Task</tt> field of their
1031 control file. The format of this field is a list of tasks,
1032 separated by commas.
1036 You should not tag any packages as belonging to a task
1037 before this has been discussed on the
1038 <em>debian-devel</em> mailing list and a consensus about
1039 doing that has been reached.
1043 For third parties (and historical reasons), tasksel also
1044 supports constructing tasks based on <em>task
1045 packages</em>. These are packages whose names begin with
1046 <em>task-</em>. Task packages should not be included in the
1051 <sect1 id="maintscripts">
1052 <heading>Maintainer Scripts</heading>
1055 The package installation scripts should avoid producing
1056 output which it is unnecessary for the user to see and
1057 should rely on <prgn>dpkg</prgn> to stave off boredom on
1058 the part of a user installing many packages. This means,
1059 amongst other things, using the <tt>--quiet</tt> option on
1060 <prgn>install-info</prgn>.</p>
1063 Errors which occur during the execution of an installation
1064 script must be checked and the installation must not
1065 continue after an error.
1069 Note that in general <ref id="scripts"> applies to package
1070 maintainer scripts, too.
1074 You should not use <prgn>dpkg-divert</prgn> on a file
1075 belonging to another package without consulting the
1076 maintainer of that package first.
1080 All packages which supply an instance of a common command
1081 name (or, in general, filename) should generally use
1082 <prgn>update-alternatives</prgn>, so that they may be
1083 installed together. If <prgn>update-alternatives</prgn>
1084 is not used, then each package must use
1085 <tt>Conflicts</tt> to ensure that other packages are
1086 de-installed. (In this case, it may be appropriate to
1087 specify a conflict against earlier versions of something
1088 that previously did not use
1089 <prgn>update-alternatives</prgn>; this is an exception to
1090 the usual rule that versioned conflicts should be
1096 <heading>Prompting in maintainer scripts</heading>
1098 Package maintainer scripts may prompt the user if
1099 necessary. Prompting may be accomplished by hand, or by
1100 communicating with a program, such as
1101 <prgn>debconf</prgn>, which conforms to the Debian
1102 Configuration management specification, version 2 or
1103 higher. These are included in the
1104 <file>debconf_specification</file> files in the
1105 <package>debian-policy</package> package.
1106 You may also find this file on the FTP site
1107 <ftpsite>ftp.debian.org</ftpsite> in
1108 <ftppath>/debian/doc/package-developer/debconf_specification.txt.gz</ftppath>
1109 or on your local mirror.<footnote>
1111 4% of Debian packages [see <url
1112 id="http://kitenet.net/programs/debconf/stats/"
1113 name="Debconf stats">] currently use
1114 <package>debconf</package> to prompt the user at
1115 install time, and this number is growing daily. The
1116 benefits of using debconf are briefly explained at
1118 id="http://kitenet.net/doc/debconf-doc/introduction.html"
1119 name="Debconf introduction">; they include
1120 preconfiguration, (mostly) noninteractive
1121 installation, elimination of redundant prompting,
1122 consistency of user interface, etc.
1125 With this increasing number of packages using
1126 <package>debconf</package>, plus the existance of a
1127 nascent second implementation of the Debian
1128 configuration management system
1129 (<package>cdebconf</package>), and the stabilization
1130 of the protocol these things use, the time has
1131 finally come to reflect the use of these things in
1138 Packages which use the Debian Configuration management
1139 specification may contain an additional
1140 <prgn>config</prgn> script and a <tt>templates</tt>
1141 file in their control archive. The <prgn>config</prgn>
1142 script might be run before the <prgn>preinst</prgn>
1143 script, and before the package is unpacked or any of its
1144 dependencies or pre-dependancies are satisfied.
1145 Therefore it must work using only the tools present in
1146 <em>essential</em> packages.<footnote>
1148 <package>Debconf</package> or another tool that
1149 implements the Debian Configuration management
1150 specification will also be installed, and any
1151 versioned dependencies on it will be satisfied
1152 before preconfiguration begins.
1158 Packages should try to minimize the amount of prompting
1159 they need to do, and they should ensure that the user
1160 will only ever be asked each question once. This means
1161 that packages should try to use appropriate shared
1162 configuration files (such as <file>/etc/papersize</file> and
1163 <file>/etc/news/server</file>), and shared
1164 <package>debconf</package> variables rather than each
1165 prompting for their own list of required pieces of
1170 It also means that an upgrade should not ask the same
1171 questions again, unless the user has used <tt>dpkg
1172 --purge</tt> to remove the package's configuration. The
1173 answers to configuration questions should be stored in an
1174 appropriate place in <file>/etc</file> so that the user can
1175 modify them, and how this has been done should be
1179 If a package has a vitally important piece of
1180 information to pass to the user (such as "don't run me
1181 as I am, you must edit the following configuration files
1182 first or you risk your system emitting badly-formatted
1183 messages"), it should display this in the
1184 <prgn>config</prgn> or <prgn>postinst</prgn> script and
1185 prompt the user to hit return to acknowledge the
1186 message. Copyright messages do not count as vitally
1187 important (they belong in
1188 <file>/usr/share/doc/<var>package</var>/copyright</file>);
1189 neither do instructions on how to use a program (these
1190 should be in on-line documentation, where all the users
1194 Any necessary prompting should almost always be confined
1195 to the <prgn>config</prgn> or <prgn>postinst</prgn>
1196 script. If it is done in the <prgn>postinst</prgn>, it
1197 should be protected with a conditional so that
1198 unnecessary prompting doesn't happen if a package's
1199 installation fails and the <prgn>postinst</prgn> is
1200 called with <tt>abort-upgrade</tt>,
1201 <tt>abort-remove</tt> or <tt>abort-deconfigure</tt>.</p>
1206 <heading>Source packages</heading>
1208 <sect1 id="standardsversion">
1209 <heading>Standards conformance</heading>
1212 In the source package's <tt>Standards-Version</tt> control
1213 field, you should specify the most recent version number
1214 of this policy document with which your package complied
1215 when it was last updated. The current version number is
1220 This information may be used to file bug reports
1221 automatically if your package becomes too much out of
1226 The version number has four components: major and minor
1227 version number and major and minor patch level. When the
1228 standards change in a way that requires every package to
1229 change the major number will be changed. Significant
1230 changes that will require work in many packages will be
1231 signaled by a change to the minor number. The major patch
1232 level will be changed for any change to the meaning of the
1233 standards, however small; the minor patch level will be
1234 changed when only cosmetic, typographical or other edits
1235 are made which neither change the meaning of the document
1236 nor affect the contents of packages.</p>
1239 Thus only the first three components of the policy version
1240 are significant in the <em>Standards-Version</em> control
1241 field, and so either these three components or the all
1242 four components may be specified.<footnote>
1244 In the past, people specified the full version number
1245 in the Standards-Version field, for example `2.3.0.0'.
1246 Since minor patch-level changes don't introduce new
1247 policy, it was thought it would be better to relax
1248 policy and only require the first 3 components to be
1249 specified, in this example `2.3.0'. All four
1250 components may still be used if someone wishes to do
1257 You should regularly, and especially if your package has
1258 become out of date, check for the newest Policy Manual
1259 available and update your package, if necessary. When your
1260 package complies with the new standards you should update the
1261 <tt>Standards-Version</tt> source package field and
1262 release it.<footnote>
1264 See the file <file>upgrading-checklist</file> for
1265 information about policy which has changed between
1266 different versions of this document.
1274 <heading>Package relationships</heading>
1277 Source packages should specify which binary packages they
1278 require to be installed or not to be installed in order to
1279 build correctly. For example, if building a package
1280 requires a certain compiler, then the compiler should be
1281 specified as a build-time dependency.
1285 It is not necessary to explicitly specify build-time
1286 relationships on a minimal set of packages that are always
1287 needed to compile, link and put in a Debian package a
1288 standard "Hello World!" program written in C or C++. The
1289 required packages are called <em>build-essential</em>, and
1290 an informational list can be found in
1291 <file>/usr/share/doc/build-essential/list</file> (which is
1292 contained in the <tt>build-essential</tt>
1295 <list compact="compact">
1297 <p>This allows maintaining the list separately
1298 from the policy documents (the list does not
1299 need the kind of control that the policy
1305 Having a separate package allows one to install
1306 the build-essential packages on a machine, as
1307 well as allowing other packages such as tasks to
1308 require installation of the build-essential
1309 packages using the depends relation.
1314 The separate package allows bug reports against
1315 the list to be categorized separately from
1316 the policy management process in the BTS.
1326 When specifying the set of build-time dependencies, one
1327 should list only those packages explicitly required by the
1328 build. It is not necessary to list packages which are
1329 required merely because some other package in the list of
1330 build-time dependencies depends on them.<footnote>
1332 The reason for this is that dependencies change, and
1333 you should list all those packages, and <em>only</em>
1334 those packages that <em>you</em> need directly. What
1335 others need is their business. For example, if you
1336 only link against <file>libimlib</file>, you will need to
1337 build-depend on <package>libimlib2-dev</package> but
1338 not against any <tt>libjpeg*</tt> packages, even
1339 though <tt>libimlib2-dev</tt> currently depends on
1340 them: installation of <package>libimlib2-dev</package>
1341 will automatically ensure that all of its run-time
1342 dependencies are satisfied.
1348 If build-time dependencies are specified, it must be
1349 possible to build the package and produce working binaries
1350 on a system with only essential and build-essential
1351 packages installed and also those required to satisfy the
1352 build-time relationships (including any implied
1353 relationships). In particular, this means that version
1354 clauses should be used rigorously in build-time
1355 relationships so that one cannot produce bad or
1356 inconsistently configured packages when the relationships
1357 are properly satisfied.
1361 <heading>Changes to the upstream sources</heading>
1364 If changes to the source code are made that are not
1365 specific to the needs of the Debian system, they should be
1366 sent to the upstream authors in whatever form they prefer
1367 so as to be included in the upstream version of the
1371 If you need to configure the package differently for
1372 Debian or for Linux, and the upstream source doesn't
1373 provide a way to do so, you should add such configuration
1374 facilities (for example, a new <prgn>autoconf</prgn> test
1375 or <tt>#define</tt>) and send the patch to the upstream
1376 authors, with the default set to the way they originally
1377 had it. You can then easily override the default in your
1378 <file>debian/rules</file> or wherever is appropriate.</p>
1381 You should make sure that the <prgn>configure</prgn> utility
1382 detects the correct architecture specification string
1383 (refer to <ref id="arch-spec"> for details).</p>
1386 If you need to edit a <prgn>Makefile</prgn> where
1387 GNU-style <prgn>configure</prgn> scripts are used, you
1388 should edit the <file>.in</file> files rather than editing the
1389 <prgn>Makefile</prgn> directly. This allows the user to
1390 reconfigure the package if necessary. You should
1391 <em>not</em> configure the package and edit the generated
1392 <prgn>Makefile</prgn>! This makes it impossible for
1393 someone else to later reconfigure the package.</p>
1396 You should document your changes and updates to the source
1397 package properly in the <file>debian/changelog</file> file.
1398 For more information, please see <ref id="changelogs">.
1404 <heading>Error trapping in makefiles</heading>
1407 When <prgn>make</prgn> invokes a command in a makefile
1408 (including your package's upstream makefiles and
1409 <file>debian/rules</file>), it does so using <prgn>sh</prgn>. This
1410 means that <prgn>sh</prgn>'s usual bad error handling
1411 properties apply: if you include a miniature script as one
1412 of the commands in your makefile you'll find that if you
1413 don't do anything about it then errors are not detected
1414 and <prgn>make</prgn> will blithely continue after
1418 Every time you put more than one shell command (this
1419 includes using a loop) in a makefile command you
1420 must make sure that errors are trapped. For
1421 simple compound commands, such as changing directory and
1422 then running a program, using <tt>&&</tt> rather
1423 than semicolon as a command separator is sufficient. For
1424 more complex commands including most loops and
1425 conditionals you should include a separate <tt>set -e</tt>
1426 command at the start of every makefile command that's
1427 actually one of these miniature shell scripts.</p></sect1>
1431 <heading>Obsolete constructs and libraries</heading>
1434 The include file <tt><varargs.h></tt> is
1435 provided to support end-users compiling very old software;
1436 the library <tt>libtermcap</tt> is provided to support the
1437 execution of software which has been linked against it
1438 (either old programs or those such as Netscape which are
1439 only available in binary form).</p>
1442 Debian packages should be patched to use
1443 <tt><stdarg.h></tt> and <tt>ncurses</tt>
1450 <chapt id="controlfields"><heading>Control files and their fields</heading>
1453 Many of the tools in the package management suite manipulate
1454 data represented in a common format, known as <em>control
1455 data</em>. The data is often stored in <em>control
1456 files</em>. Binary and source packages have control files,
1457 and the <file>.changes</file> files which control the installation
1458 of uploaded files are also in control file format.
1459 <prgn>Dpkg</prgn>'s internal databases are in a similar
1463 <sect id="controlsyntax"><heading>Syntax of control files</heading>
1466 A control file consists of one or more paragraphs of fields.
1467 The paragraphs are separated by blank lines. Some control
1468 files allow only one paragraph; others allow several, in
1469 which case each paragraph usually refers to a different
1470 package. (For example, in source packages, the first
1471 paragraph refers to the source package, and later paragraphs
1472 refer to binary packages generated from the source.)
1476 Each paragraph consists of a series of data fields; each
1477 field consists of the field name, followed by a colon and
1478 then the data/value associated with that field. It ends at
1479 the end of the line. Horizontal whitespace (spaces and
1480 tabs) may occur immediately before or after the value and is
1481 ignored there; it is conventional to put a single space
1482 after the colon. For example, a field might be:
1483 <example compact="compact">
1486 the field name is <tt>Package</tt> and the field value
1491 Some fields' values may span several lines; in this case
1492 each continuation line <em>must</em> start with a space or
1493 tab. Any trailing spaces or tabs at the end of individual
1494 lines of a field value are ignored.
1498 Except where otherwise stated only a single line of data is
1499 allowed and whitespace is not significant in a field body.
1500 Whitespace must not appear inside names (of packages,
1501 architectures, files or anything else) or version numbers,
1502 or between the characters of multi-character version
1507 Field names are not case-sensitive, but it is usual to
1508 capitalize the field names using mixed case as shown below.
1512 Blank lines, or lines consisting only of spaces and tabs,
1513 are not allowed within field values or between fields - that
1514 would mean a new paragraph.
1519 <sect><heading>List of fields</heading>
1521 This list here is not supposed to be exhaustive. Most fields
1522 are dealt with elsewhere in this document.
1524 <sect1 id="f-Package"><heading><tt>Package</tt>
1528 The name of the binary package. Package names consist of
1529 lower case letters (<tt>a-z</tt>), digits (<tt>0-9</tt>),
1530 plus (<tt>+</tt>) and minus (<tt>-</tt>) signs, and
1531 periods (<tt>.</tt>).
1535 They must be at least two characters long and must start
1536 with an alphanumeric character. The use of lowercase
1537 package names is required unless the package you're
1538 building (or referring to, in other fields) is already
1539 using uppercase characters.</p>
1542 <sect1 id="f-Version"><heading><tt>Version</tt>
1546 This lists the source or binary package's version number -
1547 see <ref id="versions">.
1553 id="f-Standards-Version"><heading><tt>Standards-Version</tt>
1557 The most recent version of the standards (the policy
1558 manual and associated texts) with which the package
1559 complies. This is updated manually when editing the
1560 source package to conform to newer standards; it can
1561 sometimes be used to tell when a package needs attention.
1562 Its format is described above; see
1563 <ref id="standardsversion">.
1568 <sect1 id="f-Distribution"><heading><tt>Distribution</tt>
1572 In a <file>.changes</file> file or parsed changelog output
1573 this contains the (space-separated) name(s) of the
1574 distribution(s) where this version of the package should
1575 be installed. Valid distributions are determined by the
1576 archive maintainers.<footnote>
1577 Current distribution names are:
1578 <taglist compact="compact">
1579 <tag><em>stable</em></tag>
1582 This is the current `released' version of Debian
1583 GNU/Linux. Once the distribution is
1584 <em>stable</em> only security fixes and other
1585 major bug fixes are allowed. When changes are
1586 made to this distribution, the release number is
1587 increased (for example: 2.2r1 becomes 2.2r2 then
1592 <tag><em>unstable</em></tag>
1595 This distribution value refers to the
1596 <em>developmental</em> part of the Debian
1597 distribution tree. New packages, new upstream
1598 versions of packages and bug fixes go into the
1599 <em>unstable</em> directory tree. Download from
1600 this distribution at your own risk.
1604 <tag><em>testing</em></tag>
1607 This distribution value refers to the
1608 <em>testing</em> part of the Debian distribution
1609 tree. It receives its packages from the
1610 unstable distribution after a short time lag to
1611 ensure that there are no major issues with the
1612 unstable packages. It is less prone to breakage
1613 than unstable, but still risky. It is not
1614 possible to upload packages directly to
1619 <tag><em>frozen</em></tag>
1622 From time to time, the <em>testing</em>
1623 distribution enters a state of `code-freeze' in
1624 anticipation of release as a <em>stable</em>
1625 version. During this period of testing only
1626 fixes for existing or newly-discovered bugs will
1627 be allowed. The exact details of this stage are
1628 determined by the Release Manager.
1632 <tag><em>experimental</em></tag>
1635 The packages with this distribution value are
1636 deemed by their maintainers to be high
1637 risk. Oftentimes they represent early beta or
1638 developmental packages from various sources that
1639 the maintainers want people to try, but are not
1640 ready to be a part of the other parts of the
1641 Debian distribution tree. Download at your own
1647 You should list <em>all</em> distributions that the
1648 package should be installed into.
1657 <chapt id="versions"><heading>Version numbering</heading>
1660 Every package has a version number recorded in its
1661 <tt>Version</tt> control file field.
1665 The package management system imposes an ordering on version
1666 numbers, so that it can tell whether packages are being up- or
1667 downgraded and so that package system front end applications
1668 can tell whether a package it finds available is newer than
1669 the one installed on the system. The version number format
1670 has the most significant parts (as far as comparison is
1671 concerned) at the beginning.
1675 The version number format is:
1676 [<var>epoch</var><tt>:</tt>]<var>upstream_version</var>[<tt>-</tt><var>debian_revision</var>]
1680 The three components here are:
1682 <tag><var>epoch</var></tag>
1685 This is a single (generally small) unsigned integer. It
1686 may be omitted, in which case zero is assumed. If it is
1687 omitted then the <var>upstream_version</var> may not
1692 It is provided to allow mistakes in the version numbers
1693 of older versions of a package, and also a package's
1694 previous version numbering schemes, to be left behind.
1698 <tag><var>upstream_version</var></tag>
1701 This is the main part of the version number. It is
1702 usually the version number of the original (`upstream')
1703 package from which the <file>.deb</file> file has been made,
1704 if this is applicable. Usually this will be in the same
1705 format as that specified by the upstream author(s);
1706 however, it may need to be reformatted to fit into the
1707 package management system's format and comparison
1712 The comparison behavior of the package management system
1713 with respect to the <var>upstream_version</var> is
1714 described below. The <var>upstream_version</var>
1715 portion of the version number is mandatory.
1719 The <var>upstream_version</var> may contain only
1720 alphanumerics<footnote>
1721 <p>Alphanumerics are <tt>A-Za-z0-9</tt> only.</p>
1723 and the characters <tt>.</tt> <tt>+</tt> <tt>-</tt>
1724 <tt>:</tt> (full stop, plus, hyphen, colon) and should
1725 start with a digit. If there is no
1726 <var>debian_revision</var> then hyphens are not allowed;
1727 if there is no <var>epoch</var> then colons are not
1731 <tag><var>debian_revision</var></tag>
1734 This part of the version number specifies the version of
1735 the Debian package based on the upstream version. It
1736 may contain only alphanumerics and the characters
1737 <tt>+</tt> and <tt>.</tt> (plus and full stop) and is
1738 compared in the same way as the
1739 <var>upstream_version</var> is.
1743 It is optional; if it isn't present then the
1744 <var>upstream_version</var> may not contain a hyphen.
1745 This format represents the case where a piece of
1746 software was written specifically to be turned into a
1747 Debian package, and so there is only one `debianization'
1748 of it and therefore no revision indication is required.
1752 It is conventional to restart the
1753 <var>debian_revision</var> at <tt>1</tt> each time the
1754 <var>upstream_version</var> is increased.
1758 The package management system will break the version
1759 number apart at the last hyphen in the string (if there
1760 is one) to determine the <var>upstream_version</var> and
1761 <var>debian_revision</var>. The absence of a
1762 <var>debian_revision</var> compares earlier than the
1763 presence of one (but note that the
1764 <var>debian_revision</var> is the least significant part
1765 of the version number).
1772 The <var>upstream_version</var> and <var>debian_revision</var>
1773 parts are compared by the package management system using the
1778 The strings are compared from left to right.
1782 First the initial part of each string consisting entirely of
1783 non-digit characters is determined. These two parts (one of
1784 which may be empty) are compared lexically. If a difference
1785 is found it is returned. The lexical comparison is a
1786 comparison of ASCII values modified so that all the letters
1787 sort earlier than all the non-letters.
1791 Then the initial part of the remainder of each string which
1792 consists entirely of digit characters is determined. The
1793 numerical values of these two parts are compared, and any
1794 difference found is returned as the result of the comparison.
1795 For these purposes an empty string (which can only occur at
1796 the end of one or both version strings being compared) counts
1801 These two steps (comparing and removing initial non-digit
1802 strings and initial digit strings) are repeated until a
1803 difference is found or both strings are exhausted.
1807 Note that the purpose of epochs is to allow us to leave behind
1808 mistakes in version numbering, and to cope with situations
1809 where the version numbering scheme changes. It is
1810 <em>not</em> intended to cope with version numbers containing
1811 strings of letters which the package management system cannot
1812 interpret (such as <tt>ALPHA</tt> or <tt>pre-</tt>), or with
1813 silly orderings (the author of this manual has heard of a
1814 package whose versions went <tt>1.1</tt>, <tt>1.2</tt>,
1815 <tt>1.3</tt>, <tt>1</tt>, <tt>2.1</tt>, <tt>2.2</tt>,
1816 <tt>2</tt> and so forth).
1820 If an upstream package has problematic version numbers they
1821 should be converted to a sane form for use in the
1822 <tt>Version</tt> field.
1826 <heading>Version numbers based on dates</heading>
1828 In general, Debian packages should use the same version
1829 numbers as the upstream sources.</p>
1832 However, in some cases where the upstream version number is
1833 based on a date (e.g., a development `snapshot' release) the
1834 package management system cannot handle these version
1835 numbers without epochs. For example, dpkg will consider
1836 `96May01' to be greater than `96Dec24'.</p>
1839 To prevent having to use epochs for every new upstream
1840 version, the version number should be changed to the
1841 following format in such cases: `19960501', `19961224'. It
1842 is up to the maintainer whether he/she wants to bother the
1843 upstream maintainer to change the version numbers upstream,
1847 Note that other version formats based on dates which are
1848 parsed correctly by the package management system should
1849 <em>not</em> be changed.</p>
1852 Native Debian packages (i.e., packages which have been
1853 written especially for Debian) whose version numbers include
1854 dates should always use the `YYYYMMDD' format.</p>
1858 <chapt id="miscellaneous"><heading>Packaging Considerations</heading>
1860 <sect id="timestamps"><heading>Time Stamps</heading>
1862 Maintainers should preserve the modification times of the
1863 upstream source files in a package, as far as is reasonably
1866 The rationale is that there is some information conveyed
1867 by knowing the age of the file, for example, you could
1868 recognize that some documentation is very old by looking
1869 at the modification time, so it would be nice if the
1870 modification time of the upstream source would be
1877 <sect id="debianrules"><heading><file>debian/rules</file> - the
1878 main building script</heading>
1881 This file must be an executable makefile, and contains the
1882 package-specific recipes for compiling the package and
1883 building binary package(s) from the source.
1887 It must start with the line <tt>#!/usr/bin/make -f</tt>,
1888 so that it can be invoked by saying its name rather than
1889 invoking <prgn>make</prgn> explicitly.
1893 Since an interactive <file>debian/rules</file> script makes it
1894 impossible to auto-compile that package and also makes it
1895 hard for other people to reproduce the same binary
1896 package, all <em>required targets</em> MUST be
1897 non-interactive. At a minimum, required targets are the
1898 ones called by <prgn>dpkg-buildpackage</prgn>, namely,
1899 <em>clean</em>, <em>binary</em>, <em>binary-arch</em>,
1900 <em>binary-indep</em>, and <em>build</em>. It also follows
1901 that any target that these targets depend on must also be
1906 The required and optional targets are as follows:
1908 <tag><tt>build</tt>, <tt>build-arch</tt> (optional),
1909 <tt>build-indep</tt> (optional)</tag>
1912 The <tt>build</tt> target should perform all
1913 non-interactive configuration and compilation of the
1914 package. If a package has an interactive pre-build
1915 configuration routine, the Debianized source package
1916 must either be built after this has taken place (so
1917 that the binary package can be built without rerunning
1918 the configuration) or the configuration routine
1919 modified to become non-interactive. (The latter is
1920 preferable if there are architecture-specific features
1921 detected by the configuration routine.)
1925 For some packages, notably ones where the same
1926 source tree is compiled in different ways to produce
1927 two binary packages, the <tt>build</tt> target
1928 does not make much sense. For these packages it is
1929 good enough to provide two (or more) targets
1930 (<tt>build-a</tt> and <tt>build-b</tt> or whatever)
1931 for each of the ways of building the package, and a
1932 <tt>build</tt> target that does nothing. The
1933 <tt>binary</tt> target will have to build the
1934 package in each of the possible ways and make the
1935 binary package out of each.
1939 The <tt>build</tt> target must not do anything
1940 that might require root privilege.
1944 The <tt>build</tt> target may need to run the
1945 <tt>clean</tt> target first - see below.
1949 When a package has a configuration and build routine
1950 which takes a long time, or when the makefiles are
1951 poorly designed, or when <tt>build</tt> needs to
1952 run <tt>clean</tt> first, it is a good idea to
1953 <tt>touch build</tt> when the build process is
1954 complete. This will ensure that if <tt>debian/rules
1955 build</tt> is run again it will not rebuild the whole
1958 Another common way to do this is for <tt>build</tt>
1959 to depend on <prgn>build-stamp</prgn> and to do
1960 nothing else, and for the <prgn>build-stamp</prgn>
1961 target to do the building and to <tt>touch
1962 build-stamp</tt> on completion. This is
1963 especially useful if the build routine creates a
1964 file or directory called <tt>build</tt>; in such a
1965 case, <tt>build</tt> will need to be listed as
1966 a phony target (i.e., as a dependency of the
1967 <tt>.PHONY</tt> target). See the documentation of
1968 <prgn>make</prgn> for more information on phony
1975 <tag><tt>binary</tt>, <tt>binary-arch</tt>,
1976 <tt>binary-indep</tt>
1980 The <tt>binary</tt> target must be all that is
1981 necessary for the user to build the binary package(s)
1982 produced from this source package. All of these
1983 targets are required to be non-interactive. It is
1984 split into two parts: <prgn>binary-arch</prgn> builds
1985 the binary packages which are specific to a particular
1986 architecture, and <tt>binary-indep</tt> builds
1987 those which are not.
1990 <tt>binary</tt> may be (and commonly is) a target with
1991 no commands which simply depends on
1992 <tt>binary-arch</tt> and <tt>binary-indep</tt>.
1995 Both <tt>binary-*</tt> targets should depend on the
1996 <tt>build</tt> target, or on the appropriate
1997 <tt>build-arch</tt> or <tt>build-indep</tt> target, if
1998 provided, so that the package is built if it has not
1999 been already. It should then create the relevant
2000 binary package(s), using <prgn>dpkg-gencontrol</prgn> to
2001 make their control files and <prgn>dpkg-deb</prgn> to
2002 build them and place them in the parent of the top
2007 Both the <tt>binary-arch</tt> and
2008 <tt>binary-indep</tt> targets <em>must</em> exist.
2009 If one of them has nothing to do (which will always be
2010 the case if the source generates only a single binary
2011 package, whether architecture-dependent or not), it
2012 must still exist and must always succeed.
2016 The <tt>binary</tt> targets must be invoked as
2019 The <prgn>fakeroot</prgn> package often allows one
2020 to build a package correctly even without being
2027 <tag><tt>clean</tt></tag>
2030 This must undo any effects that the <tt>build</tt>
2031 and <tt>binary</tt> targets may have had, except
2032 that it should leave alone any output files created in
2033 the parent directory by a run of a <tt>binary</tt>
2034 target. This target must be non-interactive.
2038 If a <tt>build</tt> file is touched at the end of
2039 the <tt>build</tt> target, as suggested above, it
2040 should be removed as the first action that
2041 <tt>clean</tt> performs, so that running
2042 <tt>build</tt> again after an interrupted
2043 <tt>clean</tt> doesn't think that everything is
2048 The <tt>clean</tt> target may need to be
2049 invoked as root if <tt>binary</tt> has been
2050 invoked since the last <tt>clean</tt>, or if
2051 <tt>build</tt> has been invoked as root (since
2052 <tt>build</tt> may create directories, for
2057 <tag><tt>get-orig-source</tt> (optional)</tag>
2060 This target fetches the most recent version of the
2061 original source package from a canonical archive site
2062 (via FTP or WWW, for example), does any necessary
2063 rearrangement to turn it into the original source
2064 tar file format described below, and leaves it in the
2069 This target may be invoked in any directory, and
2070 should take care to clean up any temporary files it
2075 This target is optional, but providing it if
2076 possible is a good idea.
2082 The <tt>build</tt>, <tt>binary</tt> and
2083 <tt>clean</tt> targets must be invoked with the current
2084 directory being the package's top-level directory.
2089 Additional targets may exist in <file>debian/rules</file>,
2090 either as published or undocumented interfaces or for the
2091 package's internal use.
2095 The architectures we build on and build for are determined
2096 by <prgn>make</prgn> variables using the utility
2097 <prgn>dpkg-architecture</prgn>. You can determine the
2098 Debian architecture and the GNU style architecture
2099 specification string for the build machine (the machine type
2100 we are building on) as well as for the host machine (the
2101 machine type we are building for). Here is a list of
2102 supported <prgn>make</prgn> variables:
2103 <list compact="compact">
2105 <p><tt>DEB_*_ARCH</tt> (the Debian architecture)</p>
2108 <p><tt>DEB_*_GNU_TYPE</tt> (the GNU style architecture
2109 specification string)</p>
2112 <p><tt>DEB_*_GNU_CPU</tt> (the CPU part of
2113 <tt>DEB_*_GNU_TYPE</tt>)</p>
2116 <p><tt>DEB_*_GNU_SYSTEM</tt> (the System part of
2117 <tt>DEB_*_GNU_TYPE</tt>)</p>
2119 where <tt>*</tt> is either <tt>BUILD</tt> for specification of
2120 the build machine or <tt>HOST</tt> for specification of the
2125 Backward compatibility can be provided in the rules file
2126 by setting the needed variables to suitable default
2127 values; please refer to the documentation of
2128 <prgn>dpkg-architecture</prgn> for details.
2132 It is important to understand that the <tt>DEB_*_ARCH</tt>
2133 string only determines which Debian architecture we are
2134 building on or for. It should not be used to get the CPU
2135 or system information; the GNU style variables should be
2140 <sect id="dpkgchangelog"><heading><file>debian/changelog</file>
2144 This file records the changes to the Debian-specific parts of the
2147 Though there is nothing stopping an author who is also
2148 the Debian maintainer from using it for all their
2149 changes, it will have to be renamed if the Debian and
2150 upstream maintainers become different people. In such a
2151 case, however, it might be better to maintain the
2152 package as a non-native package.
2158 It has a special format which allows the package building
2159 tools to discover which version of the package is being
2160 built and find out other release-specific information.
2164 That format is a series of entries like this:
2165 <example compact="compact">
2166 <var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
2168 <p>[optional blank line(s), stripped]</p>
2170 * <var>change details</var>
2171 <var>more change details</var>
2173 <p>[blank line(s), included in output of dpkg-parsechangelog]</p>
2175 * <var>even more change details</var>
2177 <p>[optional blank line(s), stripped]</p>
2179 -- <var>maintainer name</var> <<var>email
2180 address</var>><var>[two spaces]</var> <var>date</var>
2185 <var>package</var> and <var>version</var> are the source
2186 package name and version number.
2190 <var>distribution(s)</var> lists the distributions where
2191 this version should be installed when it is uploaded - it
2192 is copied to the <tt>Distribution</tt> field in the
2193 <file>.changes</file> file. See <ref id="f-Distribution">.
2197 <var>urgency</var> is the value for the <tt>Urgency</tt>
2198 field in the <file>.changes</file> file for the upload. It is
2199 not possible to specify an urgency containing commas; commas
2200 are used to separate
2201 <tt><var>keyword</var>=<var>value</var></tt> settings in the
2202 <prgn>dpkg</prgn> changelog format (though there is
2203 currently only one useful <var>keyword</var>,
2204 <tt>urgency</tt>).<footnote>
2206 Recognised urgency values are <tt>low</tt>,
2207 <tt>medium</tt>, <tt>high</tt> and <tt>emergency</tt>.
2208 They have an effect on how quickly a package will be
2209 considered for inclusion into the <tt>testing</tt>
2210 distribution, and give an indication of the importance
2211 of any fixes included in this upload.
2217 The change details may in fact be any series of lines
2218 starting with at least two spaces, but conventionally each
2219 change starts with an asterisk and a separating space and
2220 continuation lines are indented so as to bring them in
2221 line with the start of the text above. Blank lines may be
2222 used here to separate groups of changes, if desired.
2226 If this upload resolves bugs recorded in the Bug Tracking
2227 System (BTS), they may be automatically closed on the
2228 inclusion of this package into the Debian archive by
2229 including the string: <tt>closes: Bug#<var>nnnnn</var></tt>
2230 in the change details.<footnote>
2232 To be precise, the string should match the following
2233 Perl regular expression:
2235 /closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i
2237 Then all of the bug numbers listed will be closed by the
2238 archive maintenance script (<prgn>katie</prgn>), or in
2239 the case of an NMU, marked as fixed.
2245 The maintainer name and email address used in the changelog
2246 should be the details of the person uploading <em>this</em>
2247 version. They are <em>not</em> necessarily those of the
2248 usual package maintainer. The information here will be
2249 copied to the <tt>Changed-By</tt> field in the
2250 <tt>.changes</tt> file, and then later used to send an
2251 acknowledgement when the upload has been installed.
2255 The <var>date</var> should be in RFC822 format<footnote>
2257 This is generated by the <prgn>822-date</prgn>
2260 </footnote>; it should include the time zone specified
2261 numerically, with the time zone name or abbreviation
2262 optionally present as a comment in parentheses.
2266 The first `title' line with the package name should start
2267 at the left hand margin; the `trailer' line with the
2268 maintainer and date details should be preceded by exactly
2269 one space. The maintainer details and the date must be
2270 separated by exactly two spaces.
2273 <sect1><heading>Defining alternative changelog formats</heading>
2276 It is possible to use a different format to the standard
2277 one, by providing a parser for the format you wish to
2281 A changelog parser must not interact with the user at
2287 <sect id="srcsubstvars"><heading><file>debian/substvars</file>
2288 and variable substitutions </heading>
2291 When <prgn>dpkg-gencontrol</prgn>,
2292 <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
2293 generate control files they perform variable substitutions
2294 on their output just before writing it. Variable
2295 substitutions have the form <tt>${<var>variable</var>}</tt>.
2296 The optional file <file>debian/substvars</file> contains
2297 variable substitutions to be used; variables can also be set
2298 directly from <file>debian/rules</file> using the <tt>-V</tt>
2299 option to the source packaging commands, and certain
2300 predefined variables are also available.
2304 The <file>debian/substvars</file> file is usually generated and
2305 modified dynamically by <file>debian/rules</file> targets; in
2306 this case it must be removed by the <tt>clean</tt>
2311 See <manref name="dpkg-source" section="1"> for full
2312 details about source variable substitutions, including the
2313 format of <file>debian/substvars</file>.</p>
2316 <sect id="debianfiles"><heading><file>debian/files</file>
2320 This file is not a permanent part of the source tree; it
2321 is used while building packages to record which files are
2322 being generated. <prgn>dpkg-genchanges</prgn> uses it
2323 when it generates a <file>.changes</file> file.
2327 It should not exist in a shipped source package, and so it
2328 (and any backup files or temporary files such as
2329 <file>files.new</file><footnote>
2331 <file>files.new</file> is used as a temporary file by
2332 <prgn>dpkg-gencontrol</prgn> and
2333 <prgn>dpkg-distaddfile</prgn> - they write a new
2334 version of <tt>files</tt> here before renaming it,
2335 to avoid leaving a corrupted copy if an error
2338 </footnote>) should be removed by the
2339 <tt>clean</tt> target. It may also be wise to
2340 ensure a fresh start by emptying or removing it at the
2341 start of the <tt>binary</tt> target.
2345 When <prgn>dpkg-gencontrol</prgn> is run for a binary
2346 package, it adds an entry to <file>debian/files</file> for the
2347 <file>.deb</file> file that will be created when <tt>dpkg-deb
2348 --build</tt> is run for that binary package. So for most
2349 packages all that needs to be done with this file is to
2350 delete it in the <tt>clean</tt> target.
2354 If a package upload includes files besides the source
2355 package and any binary packages whose control files were
2356 made with <prgn>dpkg-gencontrol</prgn> then they should be
2357 placed in the parent of the package's top-level directory
2358 and <prgn>dpkg-distaddfile</prgn> should be called to add
2359 the file to the list in <file>debian/files</file>.</p>
2362 <sect id="restrictions"><heading>Restrictions on objects in source packages
2366 The source package may not contain any hard links<footnote>
2368 This is not currently detected when building source
2369 packages, but only when extracting
2373 Hard links may be permitted at some point in the
2374 future, but would require a fair amount of
2377 </footnote>, device special files, sockets or setuid or
2378 setgid files.<footnote>
2380 Setgid directories are allowed.
2385 <sect id="descriptions"><heading>Descriptions of packages - the
2386 <tt>Description</tt> field </heading>
2389 The description is intended to describe the program to a user
2390 who has never met it before so that they know whether they
2391 want to install it. It should also give information about the
2392 significant dependencies and conflicts between this package
2393 and others, so that the user knows why these dependencies and
2394 conflicts have been declared.
2397 <sect1><heading>Notes about writing descriptions
2401 The single line synopsis should be kept brief - certainly
2402 under 80 characters.
2406 Do not include the package name in the synopsis line. The
2407 display software knows how to display this already, and you
2408 do not need to state it. Remember that in many situations
2409 the user may only see the synopsis line - make it as
2410 informative as you can.
2414 Do not try to continue the single line synopsis into the
2415 extended description. This will not work correctly when
2416 the full description is displayed, and makes no sense
2417 where only the summary (the single line synopsis) is
2422 The extended description should describe what the package
2423 does and how it relates to the rest of the system (in terms
2424 of, for example, which subsystem it is which part of).
2428 The description field needs to make sense to anyone, even
2429 people who have no idea about any of the things the
2430 package deals with.<footnote>
2432 The blurb that comes with a program in its
2433 announcements and/or <prgn>README</prgn> files is
2434 rarely suitable for use in a description. It is
2435 usually aimed at people who are already in the
2436 community where the package is used.
2442 Put important information first, both in the synopsis and
2443 extended description. Sometimes only the first part of the
2444 synopsis or of the description will be displayed. You can
2445 assume that there will usually be a way to see the whole
2446 extended description.
2450 You may include information about dependencies and so forth
2451 in the extended description, if you wish.
2455 Do not use tab characters. Their effect is not predictable.
2463 <chapt id="maintainerscripts"><heading>Package maintainer scripts
2464 and installation procedure
2467 <sect><heading>Introduction to package maintainer scripts
2471 It is possible to supply scripts as part of a package which
2472 the package management system will run for you when your
2473 package is installed, upgraded or removed.
2477 These scripts are the files <prgn>preinst</prgn>,
2478 <prgn>postinst</prgn>, <prgn>prerm</prgn> and <prgn>postrm</prgn> in the
2479 control area of the package. They must be proper executable
2480 files; if they are scripts (which is recommended), they must
2481 start with the usual <tt>#!</tt> convention. They should be
2482 readable and executable by anyone, and not world-writable.
2486 The package management system looks at the exit status from
2487 these scripts. It is important that they exit with a
2488 non-zero status if there is an error, so that the package
2489 management system can stop its processing. For shell
2490 scripts this means that you <em>almost always</em> need to
2491 use <tt>set -e</tt> (this is usually true when writing shell
2492 scripts, in fact). It is also important, of course, that
2493 they don't exit with a non-zero status if everything went
2498 When a package is upgraded a combination of the scripts from
2499 the old and new packages is called during the upgrade
2500 procedure. If your scripts are going to be at all
2501 complicated you need to be aware of this, and may need to
2502 check the arguments to your scripts.
2506 Broadly speaking the <prgn>preinst</prgn> is called before
2507 (a particular version of) a package is installed, and the
2508 <prgn>postinst</prgn> afterwards; the <prgn>prerm</prgn>
2509 before (a version of) a package is removed and the
2510 <prgn>postrm</prgn> afterwards.
2514 Programs called from maintainer scripts should not normally
2515 have a path prepended to them. Before installation is
2516 started, the package management system checks to see if the
2517 programs <prgn>ldconfig</prgn>,
2518 <prgn>start-stop-daemon</prgn>, <prgn>install-info</prgn>,
2519 and <prgn>update-rc.d</prgn> can be found via the
2520 <tt>PATH</tt> environment variable. Those programs, and any
2521 other program that one would expect to be on the
2522 <tt>PATH</tt>, should thus be invoked without an absolute
2523 pathname. Maintainer scripts should also not reset the
2524 <tt>PATH</tt>, though they might choose to modify it by
2525 prepending or appending package-specific directories. These
2526 considerations really apply to all shell scripts.</p>
2530 <heading>Maintainer scripts Idempotency</heading>
2533 It is necessary for the error recovery procedures that the
2534 scripts be idempotent. This means that if it is run
2535 successfully, and then it is called again, it doesn't bomb
2536 out or cause any harm, but just ensures that everything is
2537 the way it ought to be. If the first call failed, or
2538 aborted half way through for some reason, the second call
2539 should merely do the things that were left undone the first
2540 time, if any, and exit with a success status if everything
2543 This is so that if an error occurs, the user interrupts
2544 <prgn>dpkg</prgn> or some other unforeseen circumstance
2545 happens you don't leave the user with a badly-broken
2546 package when <prgn>dpkg</prgn> attempts to repeat the
2554 <heading>Controlling terminal for maintainer scripts</heading>
2557 The maintainer scripts are guaranteed to run with a
2558 controlling terminal and can interact with the user.
2559 If they need to prompt for passwords, do full-screen
2560 interaction or something similar you should do these
2561 things to and from <file>/dev/tty</file>, since
2562 <prgn>dpkg</prgn> will at some point redirect scripts'
2563 standard input and output so that it can log the
2564 installation process. Likewise, because these scripts
2565 may be executed with standard output redirected into a
2566 pipe for logging purposes, Perl scripts should set
2567 unbuffered output by setting <tt>$|=1</tt> so that the
2568 output is printed immediately rather than being
2573 Each script should return a zero exit status for
2574 success, or a nonzero one for failure.
2578 <sect id="mscriptsinstact"><heading>Summary of ways maintainer
2583 <list compact="compact">
2585 <p><var>new-preinst</var> <tt>install</tt></p>
2588 <p><var>new-preinst</var> <tt>install</tt>
2589 <var>old-version</var></p>
2592 <p><var>new-preinst</var> <tt>upgrade</tt>
2593 <var>old-version</var></p>
2596 <p><var>old-preinst</var> <tt>abort-upgrade</tt>
2597 <var>new-version</var>
2603 <list compact="compact">
2605 <p><var>postinst</var> <tt>configure</tt>
2606 <var>most-recently-configured-version</var></p>
2609 <p><var>old-postinst</var> <tt>abort-upgrade</tt>
2610 <var>new-version</var></p>
2613 <p><var>conflictor's-postinst</var> <tt>abort-remove</tt>
2614 <tt>in-favour</tt> <var>package</var>
2615 <var>new-version</var></p>
2619 <var>deconfigured's-postinst</var>
2620 <tt>abort-deconfigure</tt> <tt>in-favour</tt>
2621 <var>failed-install-package</var> <var>version</var>
2622 <tt>removing</tt> <var>conflicting-package</var>
2629 <list compact="compact">
2631 <p><var>prerm</var> <tt>remove</tt></p>
2634 <p><var>old-prerm</var> <tt>upgrade</tt>
2635 <var>new-version</var></p>
2638 <p><var>new-prerm</var> <tt>failed-upgrade</tt>
2639 <var>old-version</var></p>
2642 <p><var>conflictor's-prerm</var> <tt>remove</tt>
2643 <tt>in-favour</tt> <var>package</var>
2644 <var>new-version</var></p>
2648 <var>deconfigured's-prerm</var> <tt>deconfigure</tt>
2649 <tt>in-favour</tt> <var>package-being-installed</var>
2650 <var>version</var> <tt>removing</tt>
2651 <var>conflicting-package</var>
2658 <list compact="compact">
2660 <p><var>postrm</var> <tt>remove</tt></p>
2663 <p><var>postrm</var> <tt>purge</tt></p>
2667 <var>old-postrm</var> <tt>upgrade</tt>
2668 <var>new-version</var></p>
2671 <p><var>new-postrm</var> <tt>failed-upgrade</tt>
2672 <var>old-version</var></p>
2675 <p><var>new-postrm</var> <tt>abort-install</tt></p>
2678 <p><var>new-postrm</var> <tt>abort-install</tt>
2679 <var>old-version</var></p>
2682 <p><var>new-postrm</var> <tt>abort-upgrade</tt>
2683 <var>old-version</var></p>
2687 <var>disappearer's-postrm</var> <tt>disappear</tt>
2688 <var>overwriter</var>
2689 <var>overwriter-version</var></p></item>
2694 <sect id="unpackphase"><heading>Details of unpack phase of
2695 installation or upgrade
2699 The procedure on installation/upgrade/overwrite/disappear
2700 (i.e., when running <tt>dpkg --unpack</tt>, or the unpack
2701 stage of <tt>dpkg --install</tt>) is as follows. In each
2702 case, if a major error occurs (unless listed below) the
2703 actions are, in general, run backwards - this means that the
2704 maintainer scripts are run with different arguments in
2705 reverse order. These are the `error unwind' calls listed
2713 <p>If a version of the package is already
2715 <example compact="compact">
2716 <var>old-prerm</var> upgrade <var>new-version</var>
2721 If the script runs but exits with a non-zero
2722 exit status, <prgn>dpkg</prgn> will attempt:
2723 <example compact="compact">
2724 <var>new-prerm</var> failed-upgrade <var>old-version</var>
2726 Error unwind, for both the above cases:
2727 <example compact="compact">
2728 <var>old-postinst</var> abort-upgrade <var>new-version</var>
2736 <p>If a `conflicting' package is being removed at the same time:
2740 If any packages depended on that conflicting
2741 package and <tt>--auto-deconfigure</tt> is
2742 specified, call, for each such package:
2743 <example compact="compact">
2744 <var>deconfigured's-prerm</var> deconfigure \
2745 in-favour <var>package-being-installed</var> <var>version</var> \
2746 removing <var>conflicting-package</var> <var>version</var>
2749 <example compact="compact">
2750 <var>deconfigured's-postinst</var> abort-deconfigure \
2751 in-favour <var>package-being-installed-but-failed</var> <var>version</var> \
2752 removing <var>conflicting-package</var> <var>version</var>
2754 The deconfigured packages are marked as
2755 requiring configuration, so that if
2756 <tt>--install</tt> is used they will be
2757 configured again if possible.</p>
2760 <p>To prepare for removal of the conflicting package, call:
2761 <example compact="compact">
2762 <var>conflictor's-prerm</var> remove \
2763 in-favour <var>package</var> <var>new-version</var>
2766 <example compact="compact">
2767 <var>conflictor's-postinst</var> abort-remove \
2768 in-favour <var>package</var> <var>new-version</var>
2779 <p>If the package is being upgraded, call:
2780 <example compact="compact">
2781 <var>new-preinst</var> upgrade <var>old-version</var>
2786 Otherwise, if the package had some configuration
2787 files from a previous version installed (i.e., it
2788 is in the `configuration files only' state):
2789 <example compact="compact">
2790 <var>new-preinst</var> install <var>old-version</var>
2794 <p>Otherwise (i.e., the package was completely purged):
2795 <example compact="compact">
2796 <var>new-preinst</var> install
2798 Error unwind actions, respectively:
2799 <example compact="compact">
2800 <var>new-postrm</var> abort-upgrade <var>old-version</var>
2801 <var>new-postrm</var> abort-install <var>old-version</var>
2802 <var>new-postrm</var> abort-install
2811 The new package's files are unpacked, overwriting any
2812 that may be on the system already, for example any
2813 from the old version of the same package or from
2814 another package. Backups of the old files are kept
2815 temporarily, and if anything goes wrong the package
2816 management system will attempt to put them back as
2817 part of the error unwind.
2821 It is an error for a package to contains files which
2822 are on the system in another package, unless
2823 <tt>Replaces</tt> is used (see <ref id="replaces">).
2825 The following paragraph is not currently the case:
2826 Currently the <tt>- - force-overwrite</tt> flag is
2827 enabled, downgrading it to a warning, but this may not
2833 It is a more serious error for a package to contain a
2834 plain file or other kind of non-directory where another
2835 package has a directory (again, unless
2836 <tt>Replaces</tt> is used). This error can be
2837 overridden if desired using
2838 <tt>--force-overwrite-dir</tt>, but this is not
2843 Packages which overwrite each other's files produce
2844 behavior which, though deterministic, is hard for the
2845 system administrator to understand. It can easily
2846 lead to `missing' programs if, for example, a package
2847 is installed which overwrites a file from another
2848 package, and is then removed again.<footnote>
2850 Part of the problem is due to what is arguably a
2851 bug in <prgn>dpkg</prgn>.
2857 A directory will never be replaced by a symbolic link
2858 to a directory or vice versa; instead, the existing
2859 state (symlink or not) will be left alone and
2860 <prgn>dpkg</prgn> will follow the symlink if there is
2868 <p>If the package is being upgraded, call
2869 <example compact="compact">
2870 <var>old-postrm</var> upgrade <var>new-version</var>
2875 <p>If this fails, <prgn>dpkg</prgn> will attempt:
2876 <example compact="compact">
2877 <var>new-postrm</var> failed-upgrade <var>old-version</var>
2879 Error unwind, for both cases:
2880 <example compact="compact">
2881 <var>old-preinst</var> abort-upgrade <var>new-version</var>
2888 This is the point of no return - if
2889 <prgn>dpkg</prgn> gets this far, it won't back off
2890 past this point if an error occurs. This will
2891 leave the package in a fairly bad state, which
2892 will require a successful re-installation to clear
2893 up, but it's when <prgn>dpkg</prgn> starts doing
2894 things that are irreversible.
2899 Any files which were in the old version of the package
2900 but not in the new are removed.</p>
2903 <p>The new file list replaces the old.</p>
2906 <p>The new maintainer scripts replace the old.</p>
2910 <p>Any packages all of whose files have been overwritten during the
2911 installation, and which aren't required for
2912 dependencies, are considered to have been removed.
2913 For each such package
2916 <p><prgn>dpkg</prgn> calls:
2917 <example compact="compact">
2918 <var>disappearer's-postrm</var> disappear \
2919 <var>overwriter</var> <var>overwriter-version</var>
2924 <p>The package's maintainer scripts are removed.
2929 It is noted in the status database as being in a
2930 sane state, namely not installed (any conffiles
2931 it may have are ignored, rather than being
2932 removed by <prgn>dpkg</prgn>). Note that
2933 disappearing packages do not have their prerm
2934 called, because <prgn>dpkg</prgn> doesn't know
2935 in advance that the package is going to
2944 Any files in the package we're unpacking that are also
2945 listed in the file lists of other packages are removed
2946 from those lists. (This will lobotomize the file list
2947 of the `conflicting' package if there is one.)
2952 The backup files made during installation, above, are
2959 The new package's status is now sane, and recorded as
2964 Here is another point of no return - if the
2965 conflicting package's removal fails we do not unwind
2966 the rest of the installation; the conflicting package
2967 is left in a half-removed limbo.
2973 If there was a conflicting package we go and do the
2974 removal actions (described below), starting with the
2975 removal of the conflicting package's files (any that
2976 are also in the package being installed have already
2977 been removed from the conflicting package's file list,
2978 and so do not get removed now).
2985 <sect id="configdetails"><heading>Details of configuration</heading>
2988 When we configure a package (this happens with <tt>dpkg
2989 --install</tt> and <tt>dpkg --configure</tt>), we first
2990 update any <tt>conffile</tt>s and then call:
2991 <example compact="compact">
2992 <var>postinst</var> configure <var>most-recently-configured-version</var>
2997 No attempt is made to unwind after errors during
3002 If there is no most recently configured version
3003 <prgn>dpkg</prgn> will pass a null argument; older versions
3004 of dpkg may pass <tt><unknown></tt> (including the
3005 angle brackets) in this case. Even older ones do not pass a
3006 second argument at all, under any circumstances.
3010 <sect id="removedetails"><heading>Details of removal and/or
3011 configuration purging</heading>
3017 <example compact="compact">
3018 <var>prerm</var> remove
3024 The package's files are removed (except <tt>conffile</tt>s).
3029 <example compact="compact">
3030 <var>postrm</var> remove
3036 All the maintainer scripts except the <prgn>postrm</prgn>
3041 If we aren't purging the package we stop here. Note
3042 that packages which have no <prgn>postrm</prgn> and no
3043 <tt>conffile</tt>s are automatically purged when
3044 removed, as there is no difference except for the
3045 <prgn>dpkg</prgn> status.</p>
3049 The <tt>conffile</tt>s and any backup files
3050 (<tt>~</tt>-files, <tt>#*#</tt> files,
3051 <tt>%</tt>-files, <tt>.dpkg-{old,new,tmp}</tt>, etc.)
3056 <example compact="compact">
3057 <var>postrm</var> purge
3062 <p>The package's file list is removed.</p>
3065 No attempt is made to unwind after errors during
3072 <chapt id="relationships"><heading>Declaring relationships between
3076 Packages can declare in their control file that they have
3077 certain relationships to other packages - for example, that
3078 they may not be installed at the same time as certain other
3079 packages, and/or that they depend on the presence of others,
3080 or that they should overwrite files in certain other packages
3085 This is done using the <tt>Depends</tt>, <tt>Pre-Depends</tt>,
3086 <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
3087 <tt>Conflicts</tt>, <tt>Provides</tt> and <tt>Replaces</tt>
3088 control file fields.
3092 Source packages may declare relationships to binary packages,
3093 saying that they require certain binary packages to be
3094 installed or absent at the time of building the package.
3098 This is done using the <tt>Build-Depends</tt>,
3099 <tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt> and
3100 <tt>Build-Conflicts-Indep</tt> control file fields.
3103 <sect id="depsyntax"><heading>Syntax of relationship fields
3107 These fields all have a uniform syntax. They are a list of
3108 package names separated by commas.
3112 In the <tt>Depends</tt>, <tt>Recommends</tt>,
3113 <tt>Suggests</tt>, <tt>Pre-Depends</tt>,
3114 <tt>Build-Depends</tt> and <tt>Build-Depends-Indep</tt>
3115 control file fields of the package, which declare
3116 dependencies on other packages, the package names listed may
3117 also include lists of alternative package names, separated
3118 by vertical bar (pipe) symbols <tt>|</tt>. In such a case,
3119 if any one of the alternative packages is installed, that
3120 part of the dependency is considered to be satisfied.
3124 All of the fields except for <tt>Provides</tt> may restrict
3125 their applicability to particular versions of each named
3126 package. This is done in parentheses after each individual
3127 package name; the parentheses should contain a relation from
3128 the list below followed by a version number, in the format
3129 described in <ref id="versions">.
3133 The relations allowed are <tt><<</tt>, <tt><=</tt>,
3134 <tt>=</tt>, <tt>>=</tt> and <tt>>></tt> for
3135 strictly earlier, earlier or equal, exactly equal, later or
3136 equal and strictly later, respectively. The deprecated
3137 forms <tt><</tt> and <tt>></tt> were used to mean
3138 earlier/later or equal, rather than strictly earlier/later,
3139 so they should not appear in new packages (though
3140 <prgn>dpkg</prgn> still supports them).
3144 Whitespace may appear at any point in the version
3145 specification subject to the rules in <ref
3146 id="controlsyntax">, and must appear where it's necessary to
3147 disambiguate; it is not otherwise significant. For
3148 consistency and in case of future changes to
3149 <prgn>dpkg</prgn> it is recommended that a single space be
3150 used after a version relationship and before a version
3151 number; it is also conventional to put a single space after
3152 each comma, on either side of each vertical bar, and before
3153 each open parenthesis.
3157 For example, a list of dependencies might appear as:
3158 <example compact="compact">
3161 Depends: libc6 (>= 2.2.1), exim | mail-transport-agent
3166 All fields that specify build-time relationships
3167 (<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
3168 <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>)
3169 may be restricted to a certain set of architectures. This
3170 is indicated in brackets after each individual package name and
3171 the optional version specification. The brackets enclose a
3172 list of Debian architecture names separated by whitespace.
3173 Exclamation marks may be prepended to each of the names.
3174 (It is not permitted for some names to be prepended with
3175 exclamation marks and others not.) If the current Debian
3176 host architecture is not in this list and there are no
3177 exclamation marks in the list, or it is in the list with a
3178 prepended exclamation mark, the package name and the
3179 associated version specification are ignored completely for
3180 the purposes of defining the relationships.
3185 <example compact="compact">
3187 Build-Depends-Indep: texinfo
3188 Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
3189 hurd-dev [hurd-i386], gnumach-dev [hurd-i386]
3194 Note that the binary package relationship fields such as
3195 <tt>Depends</tt> appear in one of the binary package
3196 sections of the control file, whereas the build-time
3197 relationships such as <tt>Build-Depends</tt> appear in the
3198 source package section of the control file (which is the
3204 <heading>Binary Dependencies - <tt>Depends</tt>,
3205 <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
3206 <tt>Pre-Depends</tt>
3210 These five fields are used to declare a dependency
3211 relationship by one package on another. Except for
3212 <tt>Enhances</tt>, they appear in the depending (binary)
3213 package's control file. (<tt>Enhances</tt> appears in the
3214 recommending package's control file.)
3218 A <tt>Depends</tt> field takes effect <em>only</em> when a
3219 package is to be configured. It does not prevent a package
3220 being on the system in an unconfigured state while its
3221 dependencies are unsatisfied, and it is possible to replace
3222 a package whose dependencies are satisfied and which is
3223 properly installed with a different version whose
3224 dependencies are not and cannot be satisfied; when this is
3225 done the depending package will be left unconfigured (since
3226 attempts to configure it will give errors) and will not
3227 function properly. If it is necessary, a
3228 <tt>Pre-Depends</tt> field can be used, which has a partial
3229 effect even when a package is being unpacked, as explained
3230 in detail below. (The other three dependency fields,
3231 <tt>Recommends</tt>, <tt>Suggests</tt> and
3232 <tt>Enhances</tt>, are only used by the various front-ends
3233 to <prgn>dpkg</prgn> such as <prgn>dselect</prgn>.)
3237 For this reason packages in an installation run are usually
3238 all unpacked first and all configured later; this gives
3239 later versions of packages with dependencies on later
3240 versions of other packages the opportunity to have their
3241 dependencies satisfied.
3245 The <tt>Depends</tt> field thus allows package maintainers
3246 to impose an order in which packages should be configured.
3250 The meaning of the five dependency fields is as follows:
3252 <tag><tt>Depends</tt></tag>
3255 This declares an absolute dependency. A package will
3256 not be configured unless all of the packages listed in
3257 its <tt>Depends</tt> field have been correctly
3262 The <tt>Depends</tt> field should be used if the
3263 depended-on package is required for the depending
3264 package to provide a significant amount of
3268 The <tt>Depends</tt> field should also be used if the
3269 <prgn>postinst</prgn>, <prgn>prerm</prgn> or
3270 <prgn>postrm</prgn> scripts require the package to be
3271 present in order to run. Note, however, that the
3272 <prgn>postrm</prgn> cannot rely on any non-essential
3273 packages to be present during the <tt>purge</tt>
3277 <tag><tt>Recommends</tt></tag>
3279 <p>This declares a strong, but not absolute, dependency.
3283 The <tt>Recommends</tt> field should list packages
3284 that would be found together with this one in all but
3285 unusual installations.</p>
3288 <tag><tt>Suggests</tt></tag>
3291 This is used to declare that one package may be more
3292 useful with one or more others. Using this field
3293 tells the packaging system and the user that the
3294 listed packages are related to this one and can
3295 perhaps enhance its usefulness, but that installing
3296 this one without them is perfectly reasonable.
3300 <tag><tt>Enhances</tt></tag>
3303 This field is similar to Suggests but works in the
3304 opposite direction. It is used to declare that a
3305 package can enhance the functionality of another
3310 <tag><tt>Pre-Depends</tt></tag>
3313 This field is like <tt>Depends</tt>, except that it
3314 also forces <prgn>dpkg</prgn> to complete installation
3315 of the packages named before even starting the
3316 installation of the package which declares the
3317 pre-dependency, as follows:
3321 When a package declaring a pre-dependency is about to
3322 be <em>unpacked</em> the pre-dependency can be
3323 satisfied if the depended-on package is either fully
3324 configured, <em>or even if</em> the depended-on
3325 package(s) are only unpacked or half-configured,
3326 provided that they have been configured correctly at
3327 some point in the past (and not removed or partially
3328 removed since). In this case, both the
3329 previously-configured and currently unpacked or
3330 half-configured versions must satisfy any version
3331 clause in the <tt>Pre-Depends</tt> field.
3335 When the package declaring a pre-dependency is about
3336 to be <em>configured</em>, the pre-dependency will be
3337 treated as a normal <tt>Depends</tt>, that is, it will
3338 be considered satisfied only if the depended-on
3339 package has been correctly configured.
3343 <tt>Pre-Depends</tt> should be used sparingly,
3344 preferably only by packages whose premature upgrade or
3345 installation would hamper the ability of the system to
3346 continue with any upgrade that might be in progress.
3350 <tt>Pre-Depends</tt> are also required if the
3351 <prgn>preinst</prgn> script depends on the named
3352 package. It is best to avoid this situation if
3358 When selecting which level of dependency to use you should
3359 consider how important the depended-on package is to the
3360 functionality of the one declaring the dependency. Some
3361 packages are composed of components of varying degrees of
3362 importance. Such a package should list using
3363 <tt>Depends</tt> the package(s) which are required by the
3364 more important components. The other components'
3365 requirements may be mentioned as Suggestions or
3366 Recommendations, as appropriate to the components' relative
3371 <sect id="conflicts"><heading>Conflicting binary packages -
3372 <tt>Conflicts</tt></heading>
3375 When one binary package declares a conflict with another
3376 using a <tt>Conflicts</tt> field, <prgn>dpkg</prgn> will
3377 refuse to allow them to be installed on the system at the
3382 If one package is to be installed, the other must be removed
3383 first - if the package being installed is marked as
3384 replacing (see <ref id="replaces">) the one on the system,
3385 or the one on the system is marked as deselected, or both
3386 packages are marked <tt>Essential</tt>, then
3387 <prgn>dpkg</prgn> will automatically remove the package
3388 which is causing the conflict, otherwise it will halt the
3389 installation of the new package with an error. This
3390 mechanism is specifically designed to produce an error when
3391 the installed package is <tt>Essential</tt>, but the new
3396 A package will not cause a conflict merely because its
3397 configuration files are still installed; it must be at least
3402 A special exception is made for packages which declare a
3403 conflict with their own package name, or with a virtual
3404 package which they provide (see below): this does not
3405 prevent their installation, and allows a package to conflict
3406 with others providing a replacement for it. You use this
3407 feature when you want the package in question to be the only
3408 package providing some feature.
3412 A <tt>Conflicts</tt> entry should almost never have an
3413 `earlier than' version clause. This would prevent
3414 <prgn>dpkg</prgn> from upgrading or installing the package
3415 which declared such a conflict until the upgrade or removal
3416 of the conflicted-with package had been completed.
3420 <sect id="virtual"><heading>Virtual packages - <tt>Provides</tt>
3424 As well as the names of actual (`concrete') packages, the
3425 package relationship fields <tt>Depends</tt>,
3426 <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
3427 <tt>Pre-Depends</tt>, <tt>Conflicts</tt>,
3428 <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
3429 <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>
3430 may mention `virtual packages'.
3434 A <em>virtual package</em> is one which appears in the
3435 <tt>Provides</tt> control file field of another package.
3436 The effect is as if the package(s) which provide a
3437 particular virtual package name had been listed by name
3438 everywhere the virtual package name appears. (See also <ref
3439 id="virtual_pkg_sect">)
3443 If there are both concrete and virtual packages of the same
3444 name, then the dependency may be satisfied (or the conflict
3445 caused) by either the concrete package with the name in
3446 question or any other concrete package which provides the
3447 virtual package with the name in question. This is so that,
3448 for example, supposing we have
3449 <example compact="compact">
3453 and someone else releases an enhanced version of the
3454 <tt>bar</tt> package (for example, a non-US variant), they
3456 <example compact="compact">
3460 and the <tt>bar-plus</tt> package will now also satisfy the
3461 dependency for the <tt>foo</tt> package.
3465 If a dependency or a conflict has a version number attached
3466 then only real packages will be considered to see whether
3467 the relationship is satisfied (or the prohibition violated,
3468 for a conflict) - it is assumed that a real package which
3469 provides the virtual package is not of the `right' version.
3470 So, a <tt>Provides</tt> field may not contain version
3471 numbers, and the version number of the concrete package
3472 which provides a particular virtual package will not be
3473 looked at when considering a dependency on or conflict with
3474 the virtual package name.
3478 It is likely that the ability will be added in a future
3479 release of <prgn>dpkg</prgn> to specify a version number for
3480 each virtual package it provides. This feature is not yet
3481 present, however, and is expected to be used only
3486 If you want to specify which of a set of real packages
3487 should be the default to satisfy a particular dependency on
3488 a virtual package, you should list the real package as an
3489 alternative before the virtual one.
3494 <sect id="replaces"><heading>Overwriting files and replacing
3495 packages - <tt>Replaces</tt></heading>
3498 The <tt>Replaces</tt> control file field has two distinct
3499 purposes, which come into play in different situations.
3502 <sect1><heading>Overwriting files in other packages</heading>
3505 Firstly, as mentioned before, it is usually an error for a
3506 package to contain files which are on the system in
3511 However, if the overwriting package declares that it
3512 <tt>Replaces</tt> the one containing the file being
3513 overwritten, then <prgn>dpkg</prgn> will replace the file
3514 from the old package with that from the new. The file
3515 will no longer be listed as `owned' by the old package.
3519 If a package is completely replaced in this way, so that
3520 <prgn>dpkg</prgn> does not know of any files it still
3521 contains, it is considered to have `disappeared'. It will
3522 be marked as not wanted on the system (selected for
3523 removal) and not installed. Any <tt>conffile</tt>s
3524 details noted for the package will be ignored, as they
3525 will have been taken over by the overwriting package. The
3526 package's <prgn>postrm</prgn> script will be run with a
3527 special argument to allow the package to do any final
3528 cleanup required. See <ref id="mscriptsinstact">.
3532 If an installed package, <tt>foo</tt> say, declares that
3533 it replaces another, <tt>bar</tt>, and an attempt is made
3534 to install <tt>bar</tt>, <prgn>dpkg</prgn> will discard
3535 files in the <tt>bar</tt> package which would overwrite
3536 those already present in <tt>foo</tt>. This is so that
3537 you can install an older version of a package without
3542 For this usage of <tt>Replaces</tt>, virtual packages (see
3543 <ref id="virtual">) are not considered when looking at a
3544 <tt>Replaces</tt> field - the packages declared as being
3545 replaced must be mentioned by their real names.
3549 Furthermore, this usage of <tt>Replaces</tt> only takes
3550 effect when both packages are at least partially on the
3551 system at once, so that it can only happen if they do not
3552 conflict or if the conflict has been overridden.
3557 <sect1><heading>Replacing whole packages, forcing their
3561 Secondly, <tt>Replaces</tt> allows the packaging system to
3562 resolve which package should be removed when there is a
3563 conflict - see <ref id="conflicts">. This usage only
3564 takes effect when the two packages <em>do</em> conflict,
3565 so that the two usages of this field do not interfere with
3570 In this situation, the package declared as being replaced
3571 can be a virtual package, so for example, all mail
3572 transport agents (MTAs) would have the following fields in
3573 their control files:
3574 <example compact="compact">
3575 Provides: mail-transport-agent
3576 Conflicts: mail-transport-agent
3577 Replaces: mail-transport-agent
3579 ensuring that only one MTA can be installed at any one
3584 <sect><heading>Relationships between source and binary packages -
3585 <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
3586 <tt>Build-Conflicts</tt>, <tt>Build-Conflicts-Indep</tt>
3590 A source package may declare a dependency or a conflict on a
3591 binary package, indicating which packages are required to be
3592 present on the system in order to build the binary packages
3593 from the source package. This is done with the control file
3594 fields <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
3595 <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>.
3596 The dependencies and conflicts they define must be satisfied
3597 (as defined earlier for binary packages) in order to invoke
3598 the targets in <tt>debian/rules</tt>, as follows:<footnote>
3600 If you make "build-arch" or "binary-arch", you need
3601 Build-Depends. If you make "build-indep" or
3602 "binary-indep", you need Build-Depends and
3603 Build-Depends-Indep. If you make "build" or "binary",
3607 There is no Build-Depends-Arch; the autobuilders will
3608 only need the Build-Depends if they know how to build
3609 only build-arch and binary-arch. Anyone building the
3610 build-indep/binary-indep targets is basically assumed to
3611 be building the whole package and so installs all build
3615 The purpose of the original split, I recall, was so that
3616 the autobuilders wouldn't need to install extra packages
3617 needed only for the binary-indep targets. But without a
3618 build-arch/build-indep split, this didn't work, since
3619 most of the work is done in the build target, not in the
3625 <tag><tt>Build-Depends</tt>, <tt>Build-Conflicts</tt></tag>
3628 The <tt>Build-Depends</tt> and
3629 <tt>Build-Conflicts</tt> fields must be satisfied when
3630 any of the following targets is invoked:
3631 <tt>build</tt>, <tt>binary</tt>, <tt>binary-arch</tt>,
3632 <tt>build-arch</tt>, <tt>build-indep</tt>
3633 and <tt>binary-indep</tt>.
3636 <tag><tt>Build-Depends-Indep</tt>,
3637 <tt>Build-Conflicts-Indep</tt></tag>
3640 The <tt>Build-Depends-Indep</tt> and
3641 <tt>Build-Conflicts-Indep</tt> fields must be
3642 satisfied when any of the following targets is
3643 invoked: <tt>build</tt>, <tt>build-indep</tt>,
3644 <tt>binary</tt> and <tt>binary-indep</tt>.
3655 <chapt id="conffiles"><heading>Configuration file handling
3659 This chapter has been superseded by <ref id="config-files">.
3663 <chapt id="sharedlibs"><heading>Shared libraries</heading>
3666 Packages containing shared libraries must be constructed with
3667 a little care to make sure that the shared library is always
3668 available. This is especially important for packages whose
3669 shared libraries are vitally important, such as the C library
3670 (currently <tt>libc6</tt>).
3674 Firstly, the package should install the shared libraries under
3675 their normal names. For example, the <tt>libgdbmg1</tt>
3676 package should install <tt>libgdbm.so.1.7.3</tt> as
3677 <file>/usr/lib/libgdbm.so.1.7.3</file>. The files should not be
3678 renamed or re-linked by any <prgn>prerm</prgn> or
3679 <prgn>postrm</prgn> scripts; <prgn>dpkg</prgn> will take care
3680 of renaming things safely without affecting running programs,
3681 and attempts to interfere with this are likely to lead to
3686 Secondly, the package should include the symbolic link that
3687 <prgn>ldconfig</prgn> would create for the shared libraries.
3688 For example, the <prgn>libgdbmg1</prgn> package should include
3689 a symbolic link from <file>/usr/lib/libgdbm.so.1</file> to
3690 <file>libgdbm.so.1.7.3</file>. This is needed so that the dynamic
3691 linker (for example <prgn>ld.so</prgn> or
3692 <prgn>ld-linux.so.*</prgn>) can find the library between the
3693 time that <prgn>dpkg</prgn> installs it and the time that
3694 <prgn>ldconfig</prgn> is run in the <prgn>postinst</prgn>
3697 The package management system requires the library to be
3698 placed before the symbolic link pointing to it in the
3699 <file>.deb</file> file. This is so that when
3700 <prgn>dpkg</prgn> comes to install the symlink
3701 (overwriting the previous symlink pointing at an older
3702 version of the library), the new shared library is already
3703 in place. In the past, this was achieved by creating the
3704 library in the temporary packaging directory before
3705 creating the symlink. Unfortunately, this was not always
3706 effective, since the building of the tar file in the
3707 <file>.deb</file> depended on the behavior of the underlying
3708 file system. Some file systems (such as reiserfs) reorder
3709 the files so that the order of creation is forgotten.
3710 Starting with release <tt>1.7.0</tt>, <prgn>dpkg</prgn>
3711 will reorder the files itself as necessary when building a
3712 package. Thus it is no longer important to concern
3713 oneself with the order of file creation.
3719 Thirdly, the associated development package should contain a
3720 symlink for the shared library without a version number. For
3721 example, the <tt>libgdbmg1-dev</tt> package should include a
3722 symlink from <tt>/usr/lib/libgdbm.so</tt> to
3723 <file>libgdbm.so.1.7.3</file>. This symlink is needed by the
3724 linker (<prgn>ld</prgn>) when compiling packages, as it will
3725 only look for <file>libgdbm.so</file> when compiling dynamically.
3729 Any package installing shared libraries in one of the default
3730 library directories of the dynamic linker (which are currently
3731 <file>/usr/lib</file> and <file>/lib</file>) or a directory that is
3732 listed in <file>/etc/ld.so.conf</file><footnote>
3735 <list compact="compact">
3736 <item><p>/usr/X11R6/lib/Xaw3d</p></item>
3737 <item><p>/usr/local/lib</p></item>
3738 <item><p>/usr/lib/libc5-compat</p></item>
3739 <item><p>/lib/libc5-compat</p></item>
3740 <item><p>/usr/X11R6/lib</p></item>
3744 must use <prgn>ldconfig</prgn> to update the shared library
3745 system. The package must call <prgn>ldconfig</prgn> in the
3746 <prgn>postinst</prgn> script if the first argument is
3747 <tt>configure</tt>; the <prgn>postinst</prgn> script may
3748 optionally invoke <prgn>ldconfig</prgn> at other times. The
3749 package should call <prgn>ldconfig</prgn> in the
3750 <prgn>postrm</prgn> script if the first argument is
3751 <tt>remove</tt>. The maintainer scripts must not invoke
3752 <prgn>ldconfig</prgn> under any circumstances other than those
3753 described in this paragraph.<footnote>
3754 <p>During install or upgrade, the preinst is called before
3755 the new files are installed, so calling "ldconfig" is
3756 pointless. The preinst of an existing package can also be
3757 called if an upgrade fails. However, this happens during
3758 the critical time when a shared libs may exist on-disk
3759 under a temporary name. Thus, it is dangerous and
3760 forbidden by current policy to call "ldconfig" at this
3763 <p>When a package is installed or upgraded, "postinst
3764 configure" runs after the new files are safely on-disk.
3765 Since it is perfectly safe to invoke ldconfig
3766 unconditionally in a postinst, it is OK for a package to
3767 simply put ldconfig in its postinst without checking the
3768 argument. The postinst can also be called to recover from
3769 a failed upgrade. This happens before any new files are
3770 unpacked, so there is no reason to call "ldconfig" at this
3773 <p>For a package that is being removed, prerm is
3774 called with all the files intact, so calling ldconfig is
3775 useless. The other calls to "prerm" happen in the case of
3776 upgrade at a time when all the files of the old package
3777 are on-disk, so again calling "ldconfig" is pointless.
3779 <p>postrm, on the other hand, is called with the "remove"
3780 argument just after the files are removed, so this is the
3781 proper time to call "ldconfig" to notify the system of the
3782 fact shared libraries from the package are removed.
3783 The postrm can be called at several other times. At the
3784 time of "postrm purge", "postrm abort-install", or "postrm
3785 abort-upgrade", calling "ldconfig" is useless because the
3786 shared lib files are not on-disk. However, when "postrm"
3787 is invoked with arguments "upgrade", "failed-upgrade", or
3788 "disappear", a shared lib may exist on-disk under a
3795 <heading>Handling shared library dependencies - the
3796 <tt>shlibs</tt> system</heading>
3799 If a package contains a binary or library which links to a
3800 shared library, we must ensure that when the package is
3801 installed on the system, all of the libraries needed are
3802 also installed. This requirement led to the creation of the
3803 <tt>shlibs</tt> system, which is very simple in its design:
3804 any package which <em>provides</em> a shared library also
3805 provides information on the package dependencies required to
3806 ensure the presence of this library, and any package which
3807 <em>uses</em> a shared library uses this information to
3808 determine the dependencies it requires. The files which
3809 contain the mapping from shared libraries to the necessary
3810 dependency information are called <file>shlibs</file> files.
3814 Thus, when a package is built which contains any shared
3815 libraries, it must provide a <file>shlibs</file> file for other
3816 packages to use, and when a package is built which contains
3817 any shared libraries or compiled binaries, it must run
3818 <prgn>dpkg-shlibdeps</prgn> on these to determine the
3819 libraries used and hence the dependencies needed by this
3822 In the past, the shared libraries linked to were
3823 determined by calling <prgn>ldd</prgn>, but now
3824 <prgn>objdump</prgn> is used to do this. The only
3825 change this makes to package building is that
3826 <prgn>dpkg-shlibdeps</prgn> must also be run on shared
3827 libraries, whereas in the past this was unnecessary.
3828 The rest of this footnote explains the advantage that
3833 We say that a binary <tt>foo</tt> <em>directly</em> uses
3834 a library <tt>libbar</tt> if it is explicitly linked
3835 with that library (that is, it uses the flag
3836 <tt>-lbar</tt> during the linking stage). Other
3837 libraries that are needed by <tt>libbar</tt> are linked
3838 <em>indirectly</em> to <tt>foo</tt>, and the dynamic
3839 linker will load them automatically when it loads
3840 <tt>libbar</tt>. A package should depend on
3841 the libraries it directly uses, and the dependencies for
3842 those libraries should automatically pull in the other
3847 Unfortunately, the <prgn>ldd</prgn> program shows both
3848 the directly and indirectly used libraries, meaning that
3849 the dependencies determined included both direct and
3850 indirect dependencies. The use of <prgn>objdump</prgn>
3851 avoids this problem by determining only the directly
3856 A good example of where this helps is the following. We
3857 could update <tt>libimlib</tt> with a new version that
3858 supports a new graphics format called dgf (but retaining
3859 the same major version number). If we used the old
3860 <prgn>ldd</prgn> method, every package that uses
3861 <tt>libimlib</tt> would need to be recompiled so it
3862 would also depend on <tt>libdgf</tt> or it wouldn't run
3863 due to missing symbols. However with the new system,
3864 packages using <tt>libimlib</tt> can rely on
3865 <tt>libimlib</tt> itself having the dependency on
3866 <tt>libdgf</tt> and so they would not need rebuilding.
3872 In the following sections, we will first describe where the
3873 various <tt>shlibs</tt> files are to be found, then how to
3874 use <prgn>dpkg-shlibdeps</prgn>, and finally the
3875 <tt>shlibs</tt> file format and how to create them if your
3876 package contains a shared library.
3880 <sect><heading>The <tt>shlibs</tt> files present on the system
3884 There are several places where <tt>shlibs</tt> files are
3885 found. The following list gives them in the order in which
3886 they are read by <prgn>dpkg-shlibdeps</prgn>. (The first
3887 one which gives the required information is used.)
3893 <p><file>debian/shlibs.local</file></p>
3895 This lists overrides for this package. Its use is
3896 described below (see <ref id="shlibslocal">).
3901 <p><file>/etc/dpkg/shlibs.override</file></p>
3903 This lists global overrides. This list is normally
3904 empty. It is maintained by the local system
3910 <p><file>DEBIAN/shlibs</file> files in the `build directory'</p>
3912 When packages are being built, any
3913 <file>debian/shlibs</file> files are copied into the
3914 control file area of the temporary build directory and
3915 given the name <file>shlibs</file>. These files give
3916 details of any shared libraries included in the
3919 An example may help here. Let us say that the
3920 source package <tt>foo</tt> generates two binary
3921 packages, <tt>libfoo2</tt> and
3922 <tt>foo-runtime</tt>. When building the binary
3923 packages, the two packages are created in the
3924 directories <file>debian/libfoo2</file> and
3925 <file>debian/foo-runtime</file> respectively.
3926 (<file>debian/tmp</file> could be used instead of one
3927 of these.) Since <tt>libfoo2</tt> provides the
3928 <tt>libfoo</tt> shared library, it will require a
3929 <tt>shlibs</tt> file, which will be installed in
3930 <file>debian/libfoo2/DEBIAN/shlibs</file>, eventually
3932 <file>/var/lib/dpkg/info/libfoo2.shlibs</file>. Then
3933 when <prgn>dpkg-shlibdeps</prgn> is run on the
3935 <file>debian/foo-runtime/usr/bin/foo-prog</file>, it
3937 <file>debian/libfoo2/DEBIAN/shlibs</file> file to
3938 determine whether <tt>foo-prog</tt>'s library
3939 dependencies are satisfied by any of the libraries
3940 provided by <tt>libfoo2</tt>. For this reason,
3941 <prgn>dpkg-shlibdeps</prgn> must only be run once
3942 all of the individual binary packages'
3943 <tt>shlibs</tt> files have been installed into the
3951 <p><file>/var/lib/dpkg/info/*.shlibs</file></p>
3953 These are the <file>shlibs</file> files corresponding to
3954 all of the packages installed on the system, and are
3955 maintained by the relevant package maintainers.
3960 <p><file>/etc/dpkg/shlibs.default</file></p>
3962 This file lists any shared libraries whose packages
3963 have failed to provide correct <file>shlibs</file> files.
3964 It was used when the <file>shlibs</file> setup was first
3965 introduced, but it is now normally empty. It is
3966 maintained by the <tt>dpkg</tt> maintainer.
3974 <heading>How to use <prgn>dpkg-shlibdeps</prgn> and the
3975 <file>shlibs</file> files</heading>
3978 Put a call to <prgn>dpkg-shlibdeps</prgn> into your
3979 <file>debian/rules</file> file. If your package contains only
3980 compiled binaries and libraries (but no scripts), you can
3981 use a command such as:
3982 <example compact="compact">
3983 dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \
3984 debian/tmp/usr/lib/*
3986 Otherwise, you will need to explicitly list the compiled
3987 binaries and libraries.<footnote>
3989 If you are using <tt>debhelper</tt>, the
3990 <prgn>dh_shlibdeps</prgn> program will do this work for
3991 you. It will also correctly handle multi-binary
3998 This command puts the dependency information into the
3999 <file>debian/substvars</file> file, which is then used by
4000 <prgn>dpkg-gencontrol</prgn>. You will need to place a
4001 <tt>${shlib:Depends}</tt> variable in the <tt>Depends</tt>
4002 field in the control file for this to work.
4006 If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
4007 done. If it does complain you might need to create your own
4008 <file>debian/shlibs.local</file> file, as explained below (see
4009 <ref id="shlibslocal">).
4013 If you have multiple binary packages, you will need to call
4014 <prgn>dpkg-shlibdeps</prgn> on each one which contains
4015 compiled libraries or binaries. In such a case, you will
4016 need to use the <tt>-T</tt> option to the <tt>dpkg</tt>
4017 utilities to specify a different <file>substvars</file> file.
4018 For more details on this and other options, see <manref
4019 name="dpkg-shlibdeps" section="1">.
4023 <sect id="shlibs"><heading>The <file>shlibs</file> File Format
4027 Each <file>shlibs</file> file has the same format. Lines
4028 beginning with <tt>#</tt> are considered to be comments and
4029 are ignored. Each line is of the form:
4030 <example compact="compact">
4031 <var>library-name</var> <var>soname-version-number</var> <var>dependencies ...</var>
4036 We will explain this by reference to the example of the
4037 <tt>zlib1g</tt> package, which (at the time of writing)
4038 installs the shared library <file>/usr/lib/libz.so.1.1.3</file>.
4042 <var>library-name</var> is the name of the shared library,
4043 in this case <tt>libz</tt>. (This must match the name part
4044 of the soname, see below.)
4048 <var>soname-version-number</var> is the version part of the
4049 soname of the library. The soname is the thing that must
4050 exactly match for the library to be recognized by the
4051 dynamic linker, and is usually of the form
4052 <tt><var>name</var>.so.<var>major-version</var></tt>, in our
4053 example, <tt>libz.so.1</tt>.<footnote>
4055 This can be determined using the command
4056 <example compact="compact">
4057 objdump -p /usr/lib/libz.so.1.1.3 | grep SONAME
4061 The version part is the part which comes after
4062 <tt>.so.</tt>, so in our case, it is <tt>1</tt>.
4066 <var>dependencies</var> has the same syntax as a dependency
4067 field in a binary package control file. It should give
4068 details of which packages are required to satisfy a binary
4069 built against the version of the library contained in the
4070 package. See <ref id="depsyntax"> for details.
4074 In our example, if the first version of the <tt>zlib1g</tt>
4075 package which contained a minor number of at least
4076 <tt>1.3</tt> was <var>1:1.1.3-1</var>, then the
4077 <tt>shlibs</tt> entry for this library could say:
4078 <example compact="compact">
4079 libz 1 zlib1g (>= 1:1.1.3)
4081 The version-specific dependency is to avoid warnings from
4082 the dynamic linker about using older shared libraries with
4088 <heading>Providing a <file>shlibs</file> file</heading>
4091 If your package provides a shared library, you should create
4092 a <file>shlibs</file> file following the format described above.
4093 It is usual to call this file <file>debian/shlibs</file> (but if
4094 you have multiple binary packages, you might want to call it
4095 <file>debian/shlibs.<var>package</var></file> instead). Then
4096 let <file>debian/rules</file> install it in the control area:
4097 <example compact="compact">
4098 install -m644 debian/shlibs debian/tmp/DEBIAN
4100 or, in the case of a multi-binary package:
4101 <example compact="compact">
4102 install -m644 debian/shlibs.<var>package</var> debian/<var>package</var>/DEBIAN/shlibs
4104 An alternative way of doing this is to create the
4105 <file>shlibs</file> file in the control area directly from
4106 <file>debian/rules</file> without using a <file>debian/shlibs</file>
4107 file at all,<footnote>
4109 This is what <prgn>dh_makeshlibs</prgn> in the
4110 <tt>debhelper</tt> suite does.
4113 since the <file>debian/shlibs</file> file itself is ignored by
4114 <prgn>dpkg-shlibdeps</prgn>.
4118 As <prgn>dpkg-shlibdeps</prgn> reads the
4119 <file>DEBIAN/shlibs</file> files in all of the binary packages
4120 being built from this source package, all of the
4121 <file>DEBIAN/shlibs</file> files should be installed before
4122 <prgn>dpkg-shlibdeps</prgn> is called on any of the binary
4127 <sect id="shlibslocal">
4128 <heading>Writing the <file>debian/shlibs.local</file> file</heading>
4131 This file is intended only as a <em>temporary</em> fix if
4132 your binaries or libraries depend on a library whose package
4133 does not yet provide a correct <file>shlibs</file> file.
4137 We will assume that you are trying to package a binary
4138 <tt>foo</tt>. When you try running
4139 <prgn>dpkg-shlibdeps</prgn> you get the following error
4140 message (<tt>-O</tt> displays the dependency information on
4141 <tt>stdout</tt> instead of writing it to
4142 <tt>debian/substvars</tt>, and the lines have been wrapped
4143 for ease of reading):
4144 <example compact="compact">
4145 $ dpkg-shlibdeps -O debian/tmp/usr/bin/foo
4146 dpkg-shlibdeps: warning: unable to find dependency
4147 information for shared library libbar (soname 1,
4148 path /usr/lib/libbar.so.1, dependency field Depends)
4149 shlibs:Depends=libc6 (>= 2.2.2-2)
4151 You can then run <prgn>ldd</prgn> on the binary to find the
4152 full location of the library concerned:
4153 <example compact="compact">
4155 libbar.so.1 => /usr/lib/libbar.so.1 (0x4001e000)
4156 libc.so.6 => /lib/libc.so.6 (0x40032000)
4157 /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
4159 So the <prgn>foo</prgn> binary depends on the
4160 <prgn>libbar</prgn> shared library, but no package seems to
4161 provide a <file>*.shlibs</file> file handling
4162 <file>libbar.so.1</file> in <file>/var/lib/dpkg/info/</file>. Let's
4163 determine the package responsible:
4164 <example compact="compact">
4165 $ dpkg -S /usr/lib/libbar.so.1
4166 bar1: /usr/lib/libbar.so.1
4167 $ dpkg -s bar1 | grep Version
4170 This tells us that the <tt>bar1</tt> package, version 1.0-1,
4171 is the one we are using. Now we can file a bug against the
4172 <tt>bar1</tt> package and create our own
4173 <file>debian/shlibs.local</file> to locally fix the problem.
4174 Including the following line into your
4175 <file>debian/shlibs.local</file> file:
4176 <example compact="compact">
4177 libbar 1 bar1 (>= 1.0-1)
4179 should allow the package build to work.
4183 As soon as the maintainer of <tt>bar1</tt> provides a
4184 correct <file>shlibs</file> file, you should remove this line
4185 from your <file>debian/shlibs.local</file> file. (You should
4186 probably also then have a versioned <tt>Build-Depends</tt>
4187 on <tt>bar1</tt> to help ensure that others do not have the
4188 same problem building your package.)
4193 <chapt id="opersys"><heading>The Operating System</heading>
4196 <heading>Filesystem hierarchy</heading>
4200 <heading>Filesystem Structure</heading>
4203 The location of all installed files and directories must
4204 comply with the Filesystem Hierarchy Standard (FHS),
4205 version 2.1, except where doing so would violate other
4206 terms of Debian Policy. The version of this document
4207 referred here can be found in the <tt>debian-policy</tt>
4209 <url id="http://www.debian.org/doc/packaging-manuals/fhs/"
4210 name="FHS (Debian copy)"> alongside this manual (or, if
4211 you have the <package>debian-policy</package> installed,
4213 id="file:///usr/share/doc/debian-policy/fhs/" name="FHS
4214 (local copy)">). The
4215 latest version, which may be a more recent version, may
4217 <url id="http://www.pathname.com/fhs/" name="FHS (upstream)">.
4218 Specific questions about following the standard may be
4219 asked on the <tt>debian-devel</tt> mailing list, or
4220 referred to the FHS mailing list (see the
4221 <url id="http://www.pathname.com/fhs/" name="FHS web site"> for
4227 <heading>Site-specific programs</heading>
4230 As mandated by the FHS, packages must not place any
4231 files in <file>/usr/local</file>, either by putting them in
4232 the file system archive to be unpacked by <prgn>dpkg</prgn>
4233 or by manipulating them in their maintainer scripts.
4237 However, the package may create empty directories below
4238 <file>/usr/local</file> so that the system administrator knows
4239 where to place site-specific files. These directories
4240 should be removed on package removal if they are
4245 Note, that this applies only to directories <em>below</em>
4246 <file>/usr/local</file>, not <em>in</em> <file>/usr/local</file>.
4247 Packages must not create sub-directories in the directory
4248 <file>/usr/local</file> itself, except those listed in FHS,
4249 section 4.5. However, you may create directories below
4250 them as you wish. You must not remove any of the
4251 directories listed in 4.5, even if you created them.
4255 Since <file>/usr/local</file> can be mounted read-only from a
4256 remote server, these directories must be created and
4257 removed by the <prgn>postinst</prgn> and <prgn>prerm</prgn>
4258 maintainer scripts and not be included in the
4259 <file>.deb</file> archive. These scripts must not fail if
4260 either of these operations fail.
4264 For example, the <tt>emacsen-common</tt> package could
4265 contain something like
4266 <example compact="compact">
4267 if [ ! -e /usr/local/share/emacs ]
4269 if mkdir /usr/local/share/emacs 2>/dev/null
4271 chown root:staff /usr/local/share/emacs
4272 chmod 2775 /usr/local/share/emacs
4276 in its <prgn>postinst</prgn> script, and
4277 <example compact="compact">
4278 rmdir /usr/local/share/emacs/site-lisp 2>/dev/null || true
4279 rmdir /usr/local/share/emacs 2>/dev/null || true
4281 in the <prgn>prerm</prgn> script. (Note that this form is
4282 used to ensure that if the script is interrupted, the
4283 directory <file>/usr/local/share/emacs</file> will still be
4288 If you do create a directory in <file>/usr/local</file> for
4289 local additions to a package, you should ensure that
4290 settings in <file>/usr/local</file> take precedence over the
4291 equivalents in <file>/usr</file>.
4295 However, because <file>/usr/local</file> and its contents are
4296 for exclusive use of the local administrator, a package
4297 must not rely on the presence or absence of files or
4298 directories in <file>/usr/local</file> for normal operation.
4302 The <file>/usr/local</file> directory itself and all the
4303 subdirectories created by the package should (by default) have
4304 permissions 2775 (group-writable and set-group-id) and be
4305 owned by <tt>root.staff</tt>.
4310 <heading>The system-wide mail directory</heading>
4312 The system-wide mail directory is <file>/var/mail</file>. This
4313 directory is part of the base system and should not owned
4314 by any particular mail agents. The use of the old
4315 location <file>/var/spool/mail</file> is deprecated, even
4316 though the spool may still be physically located there.
4317 To maintain partial upgrade compatibility for systems
4318 which have <file>/var/spool/mail</file> as their physical mail
4319 spool, packages using <file>/var/mail</file> must depend on
4320 either <package>libc6</package> (>= 2.1.3-13), or on
4321 <package>base-files</package> (>= 2.2.0), or on later
4322 versions of either one of these packages.
4328 <heading>Users and groups</heading>
4331 <heading>Introduction</heading>
4333 The Debian system can be configured to use either plain or
4338 Some user ids (UIDs) and group ids (GIDs) are reserved
4339 globally for use by certain packages. Because some
4340 packages need to include files which are owned by these
4341 users or groups, or need the ids compiled into binaries,
4342 these ids must be used on any Debian system only for the
4343 purpose for which they are allocated. This is a serious
4344 restriction, and we should avoid getting in the way of
4345 local administration policies. In particular, many sites
4346 allocate users and/or local system groups starting at 100.
4350 Apart from this we should have dynamically allocated ids,
4351 which should by default be arranged in some sensible
4352 order, but the behavior should be configurable.
4356 Packages other than <tt>base-passwd</tt> must not modify
4357 <file>/etc/passwd</file>, <file>/etc/shadow</file>,
4358 <file>/etc/group</file> or <file>/etc/gshadow</file>.
4363 <heading>UID and GID classes</heading>
4365 The UID and GID numbers are divided into classes as
4371 Globally allocated by the Debian project, the same
4372 on every Debian system. These ids will appear in
4373 the <file>passwd</file> and <file>group</file> files of all
4374 Debian systems, new ids in this range being added
4375 automatically as the <tt>base-passwd</tt> package is
4380 Packages which need a single statically allocated
4381 uid or gid should use one of these; their
4382 maintainers should ask the <tt>base-passwd</tt>
4390 Dynamically allocated system users and groups.
4391 Packages which need a user or group, but can have
4392 this user or group allocated dynamically and
4393 differently on each system, should use <tt>adduser
4394 --system</tt> to create the group and/or user.
4395 <prgn>adduser</prgn> will check for the existence of
4396 the user or group, and if necessary choose an unused
4397 id based on the ranges specified in
4398 <file>adduser.conf</file>.
4402 <tag>1000-29999:</tag>
4405 Dynamically allocated user accounts. By default
4406 <prgn>adduser</prgn> will choose UIDs and GIDs for
4407 user accounts in this range, though
4408 <file>adduser.conf</file> may be used to modify this
4413 <tag>30000-59999:</tag>
4418 <tag>60000-64999:</tag>
4421 Globally allocated by the Debian project, but only
4422 created on demand. The ids are allocated centrally
4423 and statically, but the actual accounts are only
4424 created on users' systems on demand.
4428 These ids are for packages which are obscure or
4429 which require many statically-allocated ids. These
4430 packages should check for and create the accounts in
4431 <file>/etc/passwd</file> or <file>/etc/group</file> (using
4432 <prgn>adduser</prgn> if it has this facility) if
4433 necessary. Packages which are likely to require
4434 further allocations should have a `hole' left after
4435 them in the allocation, to give them room to
4440 <tag>65000-65533:</tag>
4448 User <tt>nobody</tt>. The corresponding gid refers
4449 to the group <tt>nogroup</tt>.
4456 <tt>(uid_t)(-1) == (gid_t)(-1)</tt> <em>must
4457 not</em> be used, because it is the error return
4466 <sect id="sysvinit">
4467 <heading>System run levels and <file>init.d</file> scripts</heading>
4469 <sect1 id="/etc/init.d">
4470 <heading>Introduction</heading>
4473 The <file>/etc/init.d</file> directory contains the scripts
4474 executed by <prgn>init</prgn> at boot time and when the
4475 init state (or `runlevel') is changed (see <manref
4476 name="init" section="8">).
4480 There are at least two different, yet functionally
4481 equivalent, ways of handling these scripts. For the sake
4482 of simplicity, this document describes only the symbolic
4483 link method. However, it must not be assumed by maintainer
4484 scripts that this method is being used, and any automated
4485 manipulation of the various runlevel behaviours by
4486 maintainer scripts must be performed using
4487 <prgn>update-rc.d</prgn> as described below and not by
4488 manually installing or removing symlinks. For information
4489 on the implementation details of the other method,
4490 implemented in the <tt>file-rc</tt> package, please refer
4491 to the documentation of that package.
4495 These scripts are referenced by symbolic links in the
4496 <file>/etc/rc<var>n</var>.d</file> directories. When changing
4497 runlevels, <prgn>init</prgn> looks in the directory
4498 <file>/etc/rc<var>n</var>.d</file> for the scripts it should
4499 execute, where <tt><var>n</var></tt> is the runlevel that
4500 is being changed to, or <tt>S</tt> for the boot-up
4505 The names of the links all have the form
4506 <file>S<var>mm</var><var>script</var></file> or
4507 <file>K<var>mm</var><var>script</var></file> where
4508 <var>mm</var> is a two-digit number and <var>script</var>
4509 is the name of the script (this should be the same as the
4510 name of the actual script in <file>/etc/init.d</file>).
4514 When <prgn>init</prgn> changes runlevel first the targets
4515 of the links whose names start with a <tt>K</tt> are
4516 executed, each with the single argument <tt>stop</tt>,
4517 followed by the scripts prefixed with an <tt>S</tt>, each
4518 with the single argument <tt>start</tt>. (The links are
4519 those in the <file>/etc/rc<var>n</var>.d</file> directory
4520 corresponding to the new runlevel.) The <tt>K</tt> links
4521 are responsible for killing services and the <tt>S</tt>
4522 link for starting services upon entering the runlevel.
4526 For example, if we are changing from runlevel 2 to
4527 runlevel 3, init will first execute all of the <tt>K</tt>
4528 prefixed scripts it finds in <file>/etc/rc3.d</file>, and then
4529 all of the <tt>S</tt> prefixed scripts in that directory.
4530 The links starting with <tt>K</tt> will cause the
4531 referred-to file to be executed with an argument of
4532 <tt>stop</tt>, and the <tt>S</tt> links with an argument
4537 The two-digit number <var>mm</var> is used to determine
4538 the order in which to run the scripts: low-numbered links
4539 have their scripts run first. For example, the
4540 <tt>K20</tt> scripts will be executed before the
4541 <tt>K30</tt> scripts. This is used when a certain service
4542 must be started before another. For example, the name
4543 server <prgn>bind</prgn> might need to be started before
4544 the news server <prgn>inn</prgn> so that <prgn>inn</prgn>
4545 can set up its access lists. In this case, the script
4546 that starts <prgn>bind</prgn> would have a lower number
4547 than the script that starts <prgn>inn</prgn> so that it
4549 <example compact="compact">
4556 The two runlevels 0 (halt) and 6 (reboot) are slightly
4557 different. In these runlevels, the links with an
4558 <tt>S</tt> prefix are still called after those with a
4559 <tt>K</tt> prefix, but they too are called with the single
4560 argument <tt>stop</tt>.
4564 Also, if the script name ends <tt>.sh</tt>, the script
4565 will be sourced in runlevel <tt>S</tt> rather that being
4566 run in a forked subprocess, but will be explicitly run by
4567 <prgn>sh</prgn> in all other runlevels.
4572 <heading>Writing the scripts</heading>
4575 Packages that include daemons for system services should
4576 place scripts in <file>/etc/init.d</file> to start or stop
4577 services at boot time or during a change of runlevel.
4578 These scripts should be named
4579 <file>/etc/init.d/<var>package</var></file>, and they should
4580 accept one argument, saying what to do:
4583 <tag><tt>start</tt></tag>
4584 <item><p>start the service,</p></item>
4586 <tag><tt>stop</tt></tag>
4587 <item><p>stop the service,</p></item>
4589 <tag><tt>restart</tt></tag>
4590 <item><p>stop and restart the service,</p></item>
4592 <tag><tt>reload</tt></tag>
4593 <item><p>cause the configuration of the service to be
4594 reloaded without actually stopping and restarting
4595 the service,</p></item>
4597 <tag><tt>force-reload</tt></tag>
4598 <item><p>cause the configuration to be reloaded if the
4599 service supports this, otherwise restart the
4603 The <tt>start</tt>, <tt>stop</tt>, <tt>restart</tt>, and
4604 <tt>force-reload</tt> options should be supported by all
4605 scripts in <file>/etc/init.d</file>, the <tt>reload</tt>
4606 option is optional.</p>
4609 The <file>init.d</file> scripts should ensure that they will
4610 behave sensibly if invoked with <tt>start</tt> when the
4611 service is already running, or with <tt>stop</tt> when it
4612 isn't, and that they don't kill unfortunately-named user
4613 processes. The best way to achieve this is usually to use
4614 <prgn>start-stop-daemon</prgn>.</p>
4617 If a service reloads its configuration automatically (as
4618 in the case of <prgn>cron</prgn>, for example), the
4619 <tt>reload</tt> option of the <file>init.d</file> script
4620 should behave as if the configuration has been reloaded
4624 The <file>/etc/init.d</file> scripts must be treated as
4625 configuration files, either (if they are present in the
4626 package, that is, in the .deb file) by marking them as
4627 <tt>conffile</tt>s, or, (if they do not exist in the .deb)
4628 by managing them correctly in the maintainer scripts (see
4629 <ref id="config-files">). This is important since we want
4630 to give the local system administrator the chance to adapt
4631 the scripts to the local system, e.g., to disable a
4632 service without de-installing the package, or to specify
4633 some special command line options when starting a service,
4634 while making sure her changes aren't lost during the next
4639 These scripts should not fail obscurely when the
4640 configuration files remain but the package has been
4641 removed, as configuration files remain on the system after
4642 the package has been removed. Only when <prgn>dpkg</prgn>
4643 is executed with the <tt>--purge</tt> option will
4644 configuration files be removed. In particular, as the
4645 <file>/etc/init.d/<var>package</var></file> script itself is
4646 usually a <tt>conffile</tt>, it will remain on the system
4647 if the package is removed but not purged. Therefore, you
4648 should include a <tt>test</tt> statement at the top of the
4650 <example compact="compact">
4651 test -f <var>program-executed-later-in-script</var> || exit 0
4656 Often there are some variables in the <file>init.d</file>
4657 scripts whose values control the behaviour of the scripts,
4658 and which a system administrator is likely to want to
4659 change. As the scripts themselves are frequently
4660 <tt>conffile</tt>s, modifying them requires that the
4661 administrator merge in their changes each time the package
4662 is upgraded and the <tt>conffile</tt> changes. To ease
4663 the burden on the system administrator, such configurable
4664 values should not be placed directly in the script.
4665 Instead, they should be placed in a file in
4666 <file>/etc/default</file>, which typically will have the same
4667 base name as the <file>init.d</file> script. This extra file
4668 should be sourced by the script when the script runs. It
4669 must contain only variable settings and comments in POSIX
4670 <prgn>sh</prgn> format. It may either be a
4671 <tt>conffile</tt> or a configuration file maintained by
4672 the package maintainer scripts. See <ref id="config-files">
4677 To ensure that vital configurable values are always
4678 available, the <file>init.d</file> script should set default
4679 values for each of the shell variables it uses, either
4680 before sourcing the <file>/etc/default/</file> file or
4681 afterwards using something like the <tt>:
4682 ${VAR:=default}</tt> syntax. Also, the <file>init.d</file>
4683 script must behave sensibly and not fail if the
4684 <file>/etc/default</file> file is deleted.
4689 <heading>Interfacing with the initscript system</heading>
4692 Maintainers should use the abstraction layer provided by
4693 the <prgn>update-rc.d</prgn> and <prgn>invoke-rc.d</prgn>
4694 programs to deal with initscripts in their packages'
4695 scripts such as <prgn>postinst</prgn>, <prgn>prerm</prgn>
4696 and <prgn>postrm</prgn>.
4699 Directly managing the /etc/rc?.d links and directly
4700 invoking the <file>/etc/init.d/</file> initscripts should
4701 be done only by packages providing the initscript
4702 subsystem (such as <prgn>sysvinit</prgn> and
4703 <prgn>file-rc</prgn>).
4708 <heading>Managing the links</heading>
4711 The program <prgn>update-rc.d</prgn> is provided for
4712 package maintainers to arrange for the proper creation and
4713 removal of <file>/etc/rc<var>n</var>.d</file> symbolic links,
4714 or their functional equivalent if another method is being
4715 used. This may be used by maintainers in their packages'
4716 <prgn>postinst</prgn> and <prgn>postrm</prgn> scripts.</p>
4719 You must not include any <file>/etc/rc<var>n</var>.d</file>
4720 symbolic links in the actual archive or manually create or
4721 remove the symbolic links in maintainer scripts; you must
4722 use the <prgn>update-rc.d</prgn> program instead. (The
4723 former will fail if an alternative method of maintaining
4724 runlevel information is being used.) You must not include
4725 the <file>/etc/rc<var>n</var>.d</file> directories themselves
4726 in the archive either. (Only the <tt>sysvinit</tt>
4731 By default <prgn>update-rc.d</prgn> will start services in
4732 each of the multi-user state runlevels (2, 3, 4, and 5)
4733 and stop them in the halt runlevel (0), the single-user
4734 runlevel (1) and the reboot runlevel (6). The system
4735 administrator will have the opportunity to customize
4736 runlevels by simply adding, moving, or removing the
4737 symbolic links in <file>/etc/rc<var>n</var>.d</file> if
4738 symbolic links are being used, or by modifying
4739 <file>/etc/runlevel.conf</file> if the <tt>file-rc</tt> method
4744 To get the default behavior for your package, put in your
4745 <prgn>postinst</prgn> script
4746 <example compact="compact">
4747 update-rc.d <var>package</var> defaults
4749 and in your <prgn>postrm</prgn>
4750 <example compact="compact">
4751 if [ "$1" = purge ]; then
4752 update-rc.d <var>package</var> remove
4754 </example>. Note that is your package changes runlevels
4755 or priority, you may have to remove and recreate the
4756 links, since otherwise the old links may
4757 persist. Refer to the documentation of
4758 <prgn>update-rc.d</prgn></p>
4761 This will use a default sequence number of 20. If it does
4762 not matter when or in which order the <file>init.d</file>
4763 script is run, use this default. If it does, then you
4764 should talk to the maintainer of the <prgn>sysvinit</prgn>
4765 package or post to <tt>debian-devel</tt>, and they will
4766 help you choose a number.
4770 For more information about using <tt>update-rc.d</tt>,
4771 please consult its manpage <manref name="update-rc.d"
4777 <heading>Running initscripts</heading>
4779 The program <prgn>invoke-rc.d</prgn> is provided to make
4780 it easier for package maintainers to properly invoke an
4781 initscript, obeying runlevel and other locally-defined
4782 constraints that might limit a package's right to start,
4783 stop and otherwise manage services. This program may be
4784 used by maintainers in their packages' scripts.
4787 The use of <prgn>invoke-rc.d</prgn> to invoke the
4788 <file>/etc/init.d/*</file> initscripts is strongly
4789 recommended<footnote>
4791 In the future, the use of invoke-rc.d to invoke
4792 initscripts shall be made mandatory. Maintainers are
4793 advised to switch to invoke-rc.d as soon as
4795 </footnote>, instead of calling them directly.
4799 By default, <prgn>invoke-rc.d</prgn> will pass any
4800 action requests (start, stop, reload, restart...) to the
4801 <file>/etc/init.d</file> script, filtering out requests
4802 to start or restart a service out of its intended
4806 Most packages will simply need to change:
4807 <example compact="compact">/etc/init.d/<package>
4808 <action></example> in their <prgn>postinst</prgn>
4809 and <prgn>prerm</prgn> scripts to:
4810 <example compact="compact">
4811 if [ -x /usr/sbin/invoke-rc.d ] ; then
4812 invoke-rc.d <var>package</var> <action>
4814 /etc/init.d/<var>package</var> <action>
4818 A package should register its initscript services using
4819 <prgn>update-rc.d</prgn> before it tries to invoke them
4820 using <prgn>invoke-rc.d</prgn>. Invocation of
4821 unregistered services may fail.
4824 For more information about using
4825 <prgn>invoke-rc.d</prgn>, please consult its manpage
4826 <manref name="invoke-rc.d" section="8">.
4833 <heading>Boot-time initialization</heading>
4836 There used to be another directory, <file>/etc/rc.boot</file>,
4837 which contained scripts which were run once per machine
4838 boot. This has been deprecated in favour of links from
4839 <file>/etc/rcS.d</file> to files in <file>/etc/init.d</file> as
4840 described in <ref id="/etc/init.d">. Packages must not
4841 place files in <file>/etc/rc.boot</file>.</p>
4844 <heading>Example</heading>
4847 The <prgn>bind</prgn> DNS (nameserver) package wants to
4848 make sure that the nameserver is running in multiuser
4849 runlevels, and is properly shut down with the system. It
4850 puts a script in <file>/etc/init.d</file>, naming the script
4851 appropriately <tt>bind</tt>. As you can see, the script
4852 interprets the argument <tt>reload</tt> to send the
4853 nameserver a <tt>HUP</tt> signal (causing it to reload its
4854 configuration); this way the system administrator can say
4855 <file>/etc/init.d/bind reload</file> to reload the name
4856 server. The script has one configurable value, which can
4857 be used to pass parameters to the named program at
4858 startup; this value is read from
4859 <file>/etc/default/bind</file> (see below).
4863 <example compact="compact">
4866 # Original version by Robert Leslie
4867 # <rob@mars.org>, edited by iwj and cs
4869 test -x /usr/sbin/named || exit 0
4871 # Source defaults file.
4873 if [ -f /etc/default/bind ]; then
4880 echo -n "Starting domain name service: named"
4881 start-stop-daemon --start --quiet --exec /usr/sbin/named \
4886 echo -n "Stopping domain name service: named"
4887 start-stop-daemon --stop --quiet \
4888 --pidfile /var/run/named.pid --exec /usr/sbin/named
4892 echo -n "Restarting domain name service: named"
4893 start-stop-daemon --stop --quiet \
4894 --pidfile /var/run/named.pid --exec /usr/sbin/named
4895 start-stop-daemon --start --verbose --exec /usr/sbin/named \
4899 force-reload|reload)
4900 echo -n "Reloading configuration of domain name service: named"
4901 start-stop-daemon --stop --signal 1 --quiet \
4902 --pidfile /var/run/named.pid --exec /usr/sbin/named
4906 echo "Usage: /etc/init.d/bind " \
4907 " {start|stop|restart|reload|force-reload}" >&2
4917 Complementing the above init script is a configuration
4918 file <file>/etc/default/bind</file>, which contains
4919 configurable parameters used by the script. This would be
4920 created by the <prgn>postinst</prgn> script if it was not
4921 already present, and removed on purge by the
4922 <prgn>postrm</prgn> script.
4923 <example compact="compact">
4924 # Specified parameters to pass to named. See named(8).
4925 # You may uncomment the following line, and edit to taste.
4931 Another example on which you can base your
4932 <file>/etc/init.d</file> scripts is found in
4933 <file>/etc/init.d/skeleton</file>.
4937 If this package is happy with the default setup from
4938 <prgn>update-rc.d</prgn>, namely an ordering number of 20
4939 and having named running in all runlevels, it can say in
4940 its <prgn>postinst</prgn>:
4941 <example compact="compact">
4942 update-rc.d bind defaults >/dev/null
4944 And in its <prgn>postrm</prgn>, to remove the links when the
4946 <example compact="compact">
4947 if [ "$1" = purge ]; then
4948 update-rc.d bind remove >/dev/null
4956 <heading>Console messages from <file>init.d</file> scripts</heading>
4959 This section describes the formats to be used for messages
4960 written to standard output by the <file>/etc/init.d</file>
4961 scripts. The intent is to improve the consistency of
4962 Debian's startup and shutdown look and feel. For this
4963 reason, please look very carefully at the details. We want
4964 the messages to have the same format in terms of wording,
4965 spaces, punctuation and case of letters.
4969 Here is a list of overall rules that you should use when you
4970 create output messages. They can be useful if you have a
4971 non-standard message that is not covered specifically in the
4979 Every message should fit in one line (fewer than 80
4980 characters), start with a capital letter and end with
4981 a period (<tt>.</tt>) and line feed (<tt>"\n"</tt>).
4987 If you want to express that the computer is working on
4988 something (that is, performing a specific task, not
4989 starting or stopping a program), we use an "ellipsis"
4990 (three dots: <tt>...</tt>). Note that we don't insert
4991 spaces before or after the dots. If the task has been
4992 completed we write <tt>done.</tt> and a line feed.
4998 Design your messages as if the computer is telling you
4999 what he is doing (let him be polite :-), but don't
5000 mention "him" directly. For example, if you think of
5002 <example compact="compact">
5003 I'm starting network daemons: nfsd mountd.
5006 <example compact="compact">
5007 Starting network daemons: nfsd mountd.
5015 There are standard message formats for the following
5016 situations. They should be used by the <tt>init.d</tt>
5023 <p>When daemons are started</p>
5026 If your script starts one or more daemons, the output
5027 should look like this (a single line, no leading
5029 <example compact="compact">
5030 Starting <var>description</var>: <var>daemon-1</var> ... <var>daemon-n</var>.
5032 The <var>description</var> should describe the
5033 subsystem the daemon or set of daemons are part of,
5034 while <var>daemon-1</var> up to <var>daemon-n</var>
5035 denote each daemon's name (typically the file name of
5040 For example, the output of <file>/etc/init.d/lpd</file>
5042 <example compact="compact">
5043 Starting printer spooler: lpd.
5048 This can be achieved by saying
5049 <example compact="compact">
5050 echo -n "Starting printer spooler: lpd"
5051 start-stop-daemon --start --quiet --exec /usr/sbin/lpd
5054 in the script. If you have more than one daemon to
5055 start, you should do the following:
5056 <example compact="compact">
5057 echo -n "Starting remote file system services:"
5058 echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
5059 echo -n " mountd"; start-stop-daemon --start --quiet mountd
5060 echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
5063 This makes it possible for the user to see what takes
5064 so long and when the final daemon has been started.
5065 You should be careful where to put spaces: in the
5066 example above the system administrator can easily
5067 comment out a line if he don't wants to start a
5068 specific daemon, while the displayed message still
5074 <p>When a system parameter is being set</p>
5077 If you have to set up different system parameters
5078 during the system boot, you should use this format:
5079 <example compact="compact">
5080 Setting <var>parameter</var> to `<var>value</var>'.
5085 You can use a statement such as the following to get
5087 <example compact="compact">
5088 echo "Setting DNS domainname to \`$domainname'."
5093 Note that the left quotation mark (<tt>`</tt>) is
5094 different from the right one (<tt>'</tt>).
5099 <p>When a daemon is stopped or restarted</p>
5102 When you stop or restart a daemon, you should issue a
5103 message identical to the startup message, except that
5104 <tt>Starting</tt> is replaced with <tt>Stopping</tt>
5105 or <tt>Restarting</tt> respectively.
5109 For example, stopping the printer daemon will like
5111 <example compact="compact">
5112 Stopping printer spooler: lpd.
5118 <p>When something is executed</p>
5121 There are several examples where you have to run a
5122 program at system startup or shutdown to perform a
5123 specific task, for example, setting the system's clock
5124 using <prgn>netdate</prgn> or killing all processes
5125 when the system shuts down. Your message should look
5127 <example compact="compact">
5128 Doing something very useful...done.
5130 You should print the <tt>done.</tt> immediately after
5131 the job has been completed, so that the user is
5132 informed why she has to wait. You can get this
5134 <example compact="compact">
5135 echo -n "Doing something very useful..."
5144 <p>When the configuration is reloaded</p>
5147 When a daemon is forced to reload its configuration
5148 files you should use the following format:
5149 <example compact="compact">
5150 Reloading <var>description</var> configuration...done.
5152 where <var>description</var> is the same as in the
5153 daemon starting message.
5161 <heading>Cron jobs</heading>
5164 Packages must not modify the configuration file
5165 <file>/etc/crontab</file>, and they must not modify the files in
5166 <file>/var/spool/cron/crontabs</file>.</p>
5169 If a package wants to install a job that has to be executed
5170 via cron, it should place a file with the name of the
5171 package in one or more of the following directories:
5172 <example compact="compact">
5177 As these directory names imply, the files within them are
5178 executed on a daily, weekly, or monthly basis,
5179 respectively. The exact times are listed in
5180 <file>/etc/crontab</file>.</p>
5183 All files installed in any of these directories must be
5184 scripts (e.g., shell scripts or Perl scripts) so that they
5185 can easily be modified by the local system administrator.
5186 In addition, they should be treated as configuration
5191 If a certain job has to be executed more frequently than
5192 daily, the package should install a file
5193 <file>/etc/cron.d/<var>package</var></file>. This file uses the
5194 same syntax as <file>/etc/crontab</file> and is processed by
5195 <prgn>cron</prgn> automatically. The file must also be
5196 treated as a configuration file. (Note that entries in the
5197 <file>/etc/cron.d</file> directory are not handled by
5198 <prgn>anacron</prgn>. Thus, you should only use this
5199 directory for jobs which may be skipped if the system is not
5203 The scripts or crontab entries in these directories should
5204 check if all necessary programs are installed before they
5205 try to execute them. Otherwise, problems will arise when a
5206 package was removed but not purged since configuration files
5207 are kept on the system in this situation.</p>
5211 <heading>Menus</heading>
5214 Menu entries should follow the current menu policy found in
5215 the <tt>menu-policy</tt> files in the <tt>debian-policy</tt>
5216 package. It may also be found on the Debian FTP site
5217 <ftpsite>ftp.debian.org</ftpsite> as the file
5218 <ftppath>/debian/doc/package-developer/menu-policy.txt.gz</ftppath>,
5219 or in the equivalent location on your local mirror.
5223 The Debian <tt>menu</tt> package provides a standard
5224 interface between packages providing applications and
5225 documents, and <em>menu programs</em> (either X window
5226 managers or text-based menu programs such as
5227 <prgn>pdmenu</prgn>).
5231 All packages that provide applications that need not be
5232 passed any special command line arguments for normal
5233 operation should register a menu entry for those
5234 applications, so that users of the <tt>menu</tt> package
5235 will automatically get menu entries in their window
5236 managers, as well in shells like <tt>pdmenu</tt>.</p>
5239 Please also refer to the <em>Debian Menu System</em>
5240 documentation that comes with the <tt>menu</tt> package for
5241 information about how to register your applications and web
5247 <heading>Multimedia handlers</heading>
5250 Packages which provide the ability to view/show/play,
5251 compose, edit or print MIME types should register themselves
5252 as such following the current MIME support policy found in
5253 the <tt>mime-policy</tt> files in the <tt>debian-policy</tt>
5254 package. It may also be found on the Debian FTP site
5255 <ftpsite>ftp.debian.org</ftpsite> as the file
5256 <ftppath>/debian/doc/package-developer/mime-policy.txt.gz</ftppath>,
5257 or in the equivalent location on your local mirror.
5261 MIME (Multipurpose Internet Mail Extensions, RFCs 2045-2049)
5262 is a mechanism for encoding files and data streams and
5263 providing meta-information about them, in particular their
5264 type (e.g. audio or video) and format (e.g. PNG, HTML,
5269 Registration of MIME type handlers allows programs like mail
5270 user agents and web browsers to to invoke these handlers to
5271 view, edit or display MIME types they don't support
5277 <heading>Keyboard configuration</heading>
5280 To achieve a consistent keyboard configuration so that all
5281 applications interpret a keyboard event the same way, all
5282 programs in the Debian distribution must be configured to
5283 comply with the following guidelines.
5287 The following keys must have the specified interpretations:
5290 <tag><tt><--</tt></tag>
5291 <item><p>delete the character to the left of the cursor</p></item>
5293 <tag><tt>Delete</tt></tag>
5294 <item><p>delete the character to the right of the cursor</p></item>
5296 <tag><tt>Control+H</tt></tag>
5297 <item><p>emacs: the help prefix</p></item>
5300 The interpretation of any keyboard events should be
5301 independent of the terminal that is used, be it a virtual
5302 console, an X terminal emulator, an rlogin/telnet session,
5307 The following list explains how the different programs
5308 should be set up to achieve this:
5313 <item><p><tt><--</tt> generates <tt>KB_BackSpace</tt>
5316 <item><p><tt>Delete</tt> generates <tt>KB_Delete</tt> in
5321 X translations are set up to make
5322 <tt>KB_Backspace</tt> generate ASCII DEL, and to make
5323 <tt>KB_Delete</tt> generate <tt>ESC [ 3 ~</tt> (this
5324 is the vt220 escape code for the `delete character'
5325 key). This must be done by loading the X resources
5326 using <prgn>xrdb</prgn> on all local X displays, not
5327 using the application defaults, so that the
5328 translation resources used correspond to the
5329 <prgn>xmodmap</prgn> settings.</p></item>
5333 The Linux console is configured to make
5334 <tt><--</tt> generate DEL, and <tt>Delete</tt>
5335 generate <tt>ESC [ 3 ~</tt>.</p></item>
5339 X applications are configured so that <tt><</tt>
5340 deletes left, and <tt>Delete</tt> deletes right. Motif
5341 applications already work like this.</p></item>
5343 <item><p>Terminals should have <tt>stty erase ^?</tt> .</p></item>
5347 The <tt>xterm</tt> terminfo entry should have <tt>ESC
5348 [ 3 ~</tt> for <tt>kdch1</tt>, just as for
5349 <tt>TERM=linux</tt> and <tt>TERM=vt220</tt>.</p></item>
5353 Emacs is programmed to map <tt>KB_Backspace</tt> or
5354 the <tt>stty erase</tt> character to
5355 <tt>delete-backward-char</tt>, and <tt>KB_Delete</tt>
5356 or <tt>kdch1</tt> to <tt>delete-forward-char</tt>, and
5357 <tt>^H</tt> to <tt>help</tt> as always.</p></item>
5361 Other applications use the <tt>stty erase</tt>
5362 character and <tt>kdch1</tt> for the two delete keys,
5363 with ASCII DEL being `delete previous character' and
5364 <tt>kdch1</tt> being `delete character under
5371 This will solve the problem except for the following
5379 Some terminals have a <tt><--</tt> key that cannot
5380 be made to produce anything except <tt>^H</tt>. On
5381 these terminals Emacs help will be unavailable on
5382 <tt>^H</tt> (assuming that the <tt>stty erase</tt>
5383 character takes precedence in Emacs, and has been set
5384 correctly). <tt>M-x help</tt> or <tt>F1</tt> (if
5385 available) can be used instead.</p></item>
5389 Some operating systems use <tt>^H</tt> for <tt>stty
5390 erase</tt>. However, modern telnet versions and all
5391 rlogin versions propagate <tt>stty</tt> settings, and
5392 almost all UNIX versions honour <tt>stty erase</tt>.
5393 Where the <tt>stty</tt> settings are not propagated
5394 correctly, things can be made to work by using
5395 <tt>stty</tt> manually.</p></item>
5399 Some systems (including previous Debian versions) use
5400 <prgn>xmodmap</prgn> to arrange for both
5401 <tt><--</tt> and <tt>Delete</tt> to generate
5402 <tt>KB_Delete</tt>. We can change the behavior of
5403 their X clients using the same X resources that we use
5404 to do it for our own clients, or configure our clients
5405 using their resources when things are the other way
5406 around. On displays configured like this
5407 <tt>Delete</tt> will not work, but <tt><--</tt>
5412 Some operating systems have different <tt>kdch1</tt>
5413 settings in their <tt>terminfo</tt> database for
5414 <tt>xterm</tt> and others. On these systems the
5415 <tt>Delete</tt> key will not work correctly when you
5416 log in from a system conforming to our policy, but
5417 <tt><--</tt> will.</p></item>
5423 <heading>Environment variables</heading>
5426 A program must not depend on environment variables to get
5427 reasonable defaults. (That's because these environment
5428 variables would have to be set in a system-wide
5429 configuration file like <file>/etc/profile</file>, which is not
5430 supported by all shells.)</p>
5433 If a program usually depends on environment variables for its
5434 configuration, the program should be changed to fall back to
5435 a reasonable default configuration if these environment
5436 variables are not present. If this cannot be done easily
5437 (e.g., if the source code of a non-free program is not
5438 available), the program must be replaced by a small
5439 `wrapper' shell script which sets the environment variables
5440 if they are not already defined, and calls the original program.</p>
5443 Here is an example of a wrapper script for this purpose:
5445 <example compact="compact">
5447 BAR=${BAR:-/var/lib/fubar}
5449 exec /usr/lib/foo/foo "$@"
5454 Furthermore, as <file>/etc/profile</file> is a configuration
5455 file of the <prgn>base-files</prgn> package, other packages must not
5456 put any environment variables or other commands into that
5462 <heading>Files</heading>
5465 <heading>Binaries</heading>
5468 Two different packages must not install programs with
5469 different functionality but with the same filenames. (The
5470 case of two programs having the same functionality but
5471 different implementations is handled via `alternatives' or
5472 the `Conflicts' mechanism. See <ref id="maintscripts"> and
5473 <ref id="conflicts"> respectively.) If this case happens,
5474 one of the programs must be renamed. The maintainers should
5475 report this to the <tt>debian-devel</tt> mailing list and
5476 try to find a consensus about which program will have to be
5477 renamed. If a consensus cannot be reached, <em>both</em>
5478 programs must be renamed.
5482 By default, when a package is being built, any binaries
5483 created should include debugging information, as well as
5484 being compiled with optimization. You should also turn on
5485 as many reasonable compilation warnings as possible; this
5486 makes life easier for porters, who can then look at build
5487 logs for possible problems. For the C programming language,
5488 this means the following compilation parameters should be
5490 <example compact="compact">
5492 CFLAGS = -O2 -g -Wall # sane warning options vary between programs
5494 install -s # (or use strip on the files in debian/tmp)
5499 Note that by default all installed binaries should be stripped,
5500 either by using the <tt>-s</tt> flag to
5501 <prgn>install</prgn>, or by calling <prgn>strip</prgn> on
5502 the binaries after they have been copied into
5503 <file>debian/tmp</file> but before the tree is made into a
5507 Although binaries in the build tree should be compiled with
5508 debugging information by default, it can often be difficult
5509 to debug programs if they are also subjected to compiler
5510 optimization. For this reason, it is recommended to support
5511 the standardized environment
5512 variable <tt>DEB_BUILD_OPTIONS</tt>. This variable can
5513 contain several flags to change how a package is compiled
5521 The presence of this string means that the package
5522 should be complied with a minimum of optimization.
5523 For C programs, it is best to add <tt>-O0</tt>
5524 to <tt>CFLAGS</tt> (although this is usually the
5525 default). Some programs might fail to build or run at
5526 this level of optimization; it may be necessary to
5527 use <tt>-O1</tt>, for example.
5533 This string means that the debugging symbols should
5534 not be stripped from the binary during installation,
5535 so that debugging information may be included in the package.
5541 The following makefile snippet is an example of how one may
5542 implement the build options; you will probably have to
5543 massage this example in order to make it work for your
5545 <example compact="compact">
5548 INSTALL_FILE = $(INSTALL) -p -o root -g root -m 644
5549 INSTALL_PROGRAM = $(INSTALL) -p -o root -g root -m 755
5550 INSTALL_SCRIPT = $(INSTALL) -p -o root -g root -m 755
5551 INSTALL_DIR = $(INSTALL) -p -d -o root -g root -m 755
5553 ifneq (,$(findstring noopt,$(DEB_BUILD_OPTIONS)))
5558 ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS)))
5559 INSTALL_PROGRAM += -s
5565 It is up to the package maintainer to decide what
5566 compilation options are best for the package. Certain
5567 binaries (such as computationally-intensive programs) will
5568 function better with certain flags (<tt>-O3</tt>, for
5569 example); feel free to use them. Please use good judgment
5570 here. Don't use flags for the sake of it; only use them
5571 if there is good reason to do so. Feel free to override
5572 the upstream author's ideas about which compilation
5573 options are best: they are often inappropriate for our
5580 <heading>Libraries</heading>
5582 In general, libraries must have a shared version in the
5583 library package and a static version in the development
5584 package. The shared version must be compiled with
5585 <tt>-fPIC</tt>, and the static version must not be. In
5586 other words, each source unit ( <tt>*.c</tt>, for example,
5587 for C files) will need to be compiled twice.
5590 In some cases, it is acceptable for a library to be
5591 available in static form only; these cases include:
5594 <p>libraries for languages whose shared library support
5595 is immature or unstable</p>
5599 libraries whose interfaces are in flux or under
5600 development (commonly the case when the library's
5601 major version number is zero, or where the ABI breaks
5607 libraries which are explicitly intended to be
5608 available only in static form by their upstream
5612 If a library is available only in static form, then it must follow
5613 the conventions for a development package.
5616 All libraries must have a shared version in the
5617 <tt>lib*</tt> package and a static version in the
5618 <tt>lib*-dev</tt> package. The shared version must be
5619 compiled with <tt>-fPIC</tt>, and the static version must
5620 not be. In other words, each <tt>*.c</tt> file will need to
5621 be compiled twice.</p>
5624 You must specify the gcc option <tt>-D_REENTRANT</tt>
5625 when building a library (either static or shared) to make
5626 the library compatible with LinuxThreads.</p>
5629 Note that all installed shared libraries should be
5631 <example compact="compact">
5632 strip --strip-unneeded <var>your-lib</var>
5634 (The option <tt>--strip-unneeded</tt> makes
5635 <prgn>strip</prgn> remove only the symbols which aren't
5636 needed for relocation processing.) Shared libraries can
5637 function perfectly well when stripped, since the symbols for
5638 dynamic linking are in a separate part of the ELF object
5641 You might also want to use the options
5642 <tt>--remove-section=.comment</tt> and
5643 <tt>--remove-section=.note</tt> on both shared libraries
5644 and executables, and <tt>--strip-debug</tt> on static
5651 Note that under some circumstances it may be useful to
5652 install a shared library unstripped, for example when
5653 building a separate package to support debugging.
5657 Shared object files (often <file>.so</file> files) that are not
5658 public libraries, that is, they are not meant to be linked
5659 to by third party executables (binaries of other packages),
5660 should be installed in subdirectories of the
5661 <file>/usr/lib</file> directory. Such files are exempt from the
5662 rules that govern ordinary shared libraries, except that
5663 they must not be installed executable and should be
5666 A common example are the so-called ``plug-ins'',
5667 internal shared objects that are dynamically loaded by
5668 programs using <manref name="dlopen" section="3">.
5674 Packages containing shared libraries that may be linked to
5675 by other packages' binaries, but which for some
5676 <em>compelling</em> reason can not be installed in
5677 <file>/usr/lib</file> directory, may install the shared library
5678 files in subdirectories of the <file>/usr/lib</file> directory,
5679 in which case they should arrange to add that directory in
5680 <file>/etc/ld.so.conf</file> in the package's post-installation
5681 script, and remove it in the package's post-removal script.
5685 An ever increasing number of packages are using
5686 <prgn>libtool</prgn> to do their linking. The latest GNU
5687 libtools (>= 1.3a) can take advantage of the metadata in the
5688 installed <prgn>libtool</prgn> archive files (<file>*.la</file>
5689 files). The main advantage of <prgn>libtool</prgn>'s
5690 <file>.la</file> files is that it allows <prgn>libtool</prgn> to
5691 store and subsequently access metadata with respect to the
5692 libraries it builds. <prgn>libtool</prgn> will search for
5693 those files, which contain a lot of useful information about
5694 a library (such as library dependency information for static
5695 linking). Also, they're <em>essential</em> for programs
5696 using <tt>libltdl</tt>.<footnote>
5698 Although <prgn>libtool</prgn> is fully capable of
5699 linking against shared libraries which don't have
5700 <tt>.la</tt> files, as it is a mere shell script it can
5701 add considerably to the build time of a
5702 <prgn>libtool</prgn>-using package if that shell script
5703 has to derive all this information from first principles
5704 for each library every time it is linked. With the
5705 advent of <prgn>libtool</prgn> version 1.4 (and to a
5706 lesser extent <prgn>libtool</prgn> version 1.3), the
5707 <file>.la</file> files also store information about
5708 inter-library dependencies which cannot necessarily be
5709 derived after the <file>.la</file> file is deleted.
5715 Packages that use <prgn>libtool</prgn> to create shared
5716 libraries should include the <file>.la</file> files in the
5717 <tt>-dev</tt> package, unless the package relies on
5718 <tt>libtool</tt>'s <tt>libltdl</tt> library, in which case
5719 the <tt>.la</tt> files must go in the run-time library
5724 You must make sure that you use only released versions of
5725 shared libraries to build your packages; otherwise other
5726 users will not be able to run your binaries
5727 properly. Producing source packages that depend on
5728 unreleased compilers is also usually a bad
5734 <heading>Shared libraries</heading>
5737 Packages involving shared libraries should be split up
5738 into several binary packages.</p>
5741 For a straightforward library which has a development
5742 environment and a runtime kit including just shared
5743 libraries you need to create two packages:
5744 <file><var>libraryname</var><var>soversion</var></file>, where
5745 <file><var>soversion</var></file> is the version number in the
5746 soname of the shared library<footnote>
5748 The soname is the shared object name: it's the thing
5749 that has to match exactly between building an executable
5750 and running it for the dynamic linker to be able run the
5751 program. For example, if the soname of the library is
5752 <file>libfoo.so.6</file>, the library package would be
5753 called <file>libfoo6</file>.
5756 and <tt><var>libraryname</var><var>soversion</var>-dev</tt>.
5757 Alternatively, if it would be confusing to directly append
5758 <var>soversion</var> to <var>libraryname</var> (e.g. because
5759 <var>libraryname</var> itself ends in a number), you may use
5760 <tt><var>libraryname</var>-<var>soversion</var></tt> and
5761 <tt><var>libraryname</var>-<var>soversion</var>-dev</tt>
5766 If you prefer only to support one development version at a
5767 time you may name the development package
5768 <file><var>libraryname</var>-dev</file>; otherwise you may need
5769 to use <prgn>dpkg</prgn>'s Conflicts mechanism (see <ref
5770 id="conflicts">) to ensure that the user only installs one
5771 development version at a time (as different development
5772 versions are likely to have the same header files in them,
5773 which would cause a filename clash if both were installed).
5774 Typically the development version should also have an exact
5775 version dependency on the runtime library, to make sure that
5776 compilation and linking happens correctly. The
5777 <tt>${Source-Version}</tt> substitution variable can be
5778 useful for this purpose.
5782 Packages which use the shared library should have a
5783 dependency on the name of the shared library package,
5784 <file><var>libraryname</var><var>soversion</var></file>. When
5785 the soname changes you can have both versions of the library
5786 installed while migrating from the old library to the new.
5790 If your package has some run-time support programs which use
5791 the shared library you must not put them in the shared
5792 library package. If you do that then you won't be able to
5793 install several versions of the shared library without
5794 getting filename clashes. Instead, either create a third
5795 package for the runtime binaries (this package might
5796 typically be named <tt><var>libraryname</var>-runtime</tt>;
5797 note the absence of the <var>soversion</var> in the package
5798 name), or if the development package is small you may
5799 include them in there.
5803 If you have several shared libraries built from the same
5804 source tree you may lump them all together into a single
5805 shared library package, provided that you change all of
5806 their sonames at once (so that you don't get filename
5807 clashes if you try to install different versions of the
5808 combined shared libraries package).
5812 Shared libraries should not be installed executable, since
5813 the dynamic linker does not require this and trying to
5814 execute a shared library usually results in a core dump.
5819 <heading>Scripts</heading>
5822 All command scripts, including the package maintainer
5823 scripts inside the package and used by <prgn>dpkg</prgn>,
5824 should have a <tt>#!</tt> line naming the shell to be used
5825 to interpret them.</p>
5828 In the case of Perl scripts this should be
5829 <tt>#!/usr/bin/perl</tt>.</p>
5832 Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>)
5833 should almost certainly start with <tt>set -e</tt> so that
5834 errors are detected. Every script should use
5835 <tt>set -e</tt> or check the exit status of <em>every</em>
5839 The standard shell interpreter <file>/bin/sh</file> can be a
5840 symbolic link to any POSIX compatible shell, if <tt>echo
5841 -n</tt> does not generate a newline.<footnote>
5843 Debian policy specifies POSIX behavior for
5844 <file>/bin/sh</file>, but <tt>echo -n</tt> has widespread
5845 use in the Linux community (in particular including this
5846 policy, the Linux kernel source, many Debian scripts,
5847 etc.). This <tt>echo -n</tt> mechanism is valid but not
5848 required under POSIX, hence this explicit addition.
5849 Also, rumour has it that this shall be mandated under
5853 Thus, shell scripts specifying <file>/bin/sh</file> as
5854 interpreter should only use POSIX features. If a script
5855 requires non-POSIX features from the shell interpreter, the
5856 appropriate shell must be specified in the first line of the
5857 script (e.g., <tt>#!/bin/bash</tt>) and the package must
5858 depend on the package providing the shell (unless the shell
5859 package is marked `Essential', as in the case of
5864 You may wish to restrict your script to POSIX features when
5865 possible so that it may use <file>/bin/sh</file> as its
5866 interpreter. If your script works with <prgn>dash</prgn>
5867 (originally called <prgn>ash</prgn>), it's probably POSIX
5868 compliant, but if you are in doubt, use
5869 <file>/bin/bash</file>.
5873 Perl scripts should check for errors when making any
5874 system calls, including <tt>open</tt>, <tt>print</tt>,
5875 <tt>close</tt>, <tt>rename</tt> and <tt>system</tt>.
5879 <prgn>csh</prgn> and <prgn>tcsh</prgn> should be avoided as
5880 scripting languages. See <em>Csh Programming Considered
5881 Harmful</em>, one of the <tt>comp.unix.*</tt> FAQs, which
5882 can be found at <url
5883 id="http://language.perl.com/versus/csh.whynot">.<footnote>
5885 It can also be found on
5886 <url id="http://www.cpan.org/doc/FMTEYEWTK/versus/csh.whynot">
5887 or on the ftp site <ftpsite>ftp.cpan.org</ftpsite> as
5888 <ftppath>/pub/perl/CPAN/doc/FMTEYEWTK/versus/csh.whynot</ftppath>.
5891 If an upstream package comes with <prgn>csh</prgn> scripts
5892 then you must make sure that they start with
5893 <tt>#!/bin/csh</tt> and make your package depend on the
5894 <prgn>c-shell</prgn> virtual package.
5898 Any scripts which create files in world-writeable
5899 directories (e.g., in <file>/tmp</file>) must use a
5900 mechanism which will fail if a file with the same name
5904 The Debian base system provides the <prgn>tempfile</prgn>
5905 and <prgn>mktemp</prgn> utilities for use by scripts for
5906 this purpose.</p></sect>
5910 <heading>Symbolic links</heading>
5913 In general, symbolic links within a top-level directory
5914 should be relative, and symbolic links pointing from one
5915 top-level directory into another should be absolute. (A
5916 top-level directory is a sub-directory of the root
5917 directory <file>/</file>.)</p>
5920 In addition, symbolic links should be specified as short as
5921 possible, i.e., link targets like <file>foo/../bar</file> are
5925 Note that when creating a relative link using
5926 <prgn>ln</prgn> it is not necessary for the target of the
5927 link to exist relative to the working directory you're
5928 running <prgn>ln</prgn> from, nor is it necessary to change
5929 directory to the directory where the link is to be made.
5930 Simply include the string that should appear as the target
5931 of the link (this will be a pathname relative to the
5932 directory in which the link resides) as the first argument
5933 to <prgn>ln</prgn>.</p>
5936 For example, in your <prgn>Makefile</prgn> or
5937 <file>debian/rules</file>, you can do things like:
5938 <example compact="compact">
5939 ln -fs gcc $(prefix)/bin/cc
5940 ln -fs gcc debian/tmp/usr/bin/cc
5941 ln -fs ../sbin/sendmail $(prefix)/bin/runq
5942 ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
5946 A symbolic link pointing to a compressed file should always
5947 have the same file extension as the referenced file. (For
5948 example, if a file <file>foo.gz</file> is referenced by a
5949 symbolic link, the filename of the link has to end with
5950 `<file>.gz</file>' too, as in <file>bar.gz</file>.)
5955 <heading>Device files</heading>
5958 Packages must not include device files in the package file
5962 If a package needs any special device files that are not
5963 included in the base system, it must call
5964 <prgn>MAKEDEV</prgn> in the <prgn>postinst</prgn> script,
5965 after notifying the user<footnote>
5967 This notification could be done via a (low-priority)
5968 debconf message, or an echo (printf) statement.
5974 Packages must not remove any device files in the
5975 <prgn>postrm</prgn> or any other script. This is left to the
5976 system administrator.</p>
5979 Debian uses the serial devices
5980 <file>/dev/ttyS*</file>. Programs using the old
5981 <file>/dev/cu*</file> devices should be changed to use
5982 <file>/dev/ttyS*</file>.</p>
5985 <sect id="config-files">
5986 <heading>Configuration files</heading>
5988 <heading>Definitions</heading>
5991 <tag>configuration file</tag>
5994 A file that affects the operation of a program, or
5995 provides site- or host-specific information, or
5996 otherwise customizes the behavior of a program.
5997 Typically, configuration files are intended to be
5998 modified by the system administrator (if needed or
5999 desired) to conform to local policy or to provide
6000 more useful site-specific behavior.
6004 <tag><tt>conffile</tt></tag>
6007 A file listed in a package's <tt>conffiles</tt>
6008 file, and is treated specially by <prgn>dpkg</prgn>
6009 (see <ref id="configdetails">).
6016 The distinction between these two is important; they are
6017 not interchangeable concepts. Almost all
6018 <tt>conffile</tt>s are configuration files, but many
6019 configuration files are not <tt>conffiles</tt>.
6023 Note that a script that embeds configuration information
6024 (such as most of the files in <file>/etc/default</file> and
6025 <file>/etc/cron.{daily,weekly,monthly}</file>) is de-facto a
6026 configuration file and should be treated as such.
6031 <heading>Location</heading>
6033 Any configuration files created or used by your package
6034 must reside in <file>/etc</file>. If there are several you
6035 should consider creating a subdirectory of <file>/etc</file>
6036 named after your package.</p>
6039 If your package creates or uses configuration files
6040 outside of <file>/etc</file>, and it is not feasible to modify
6041 the package to use the <file>/etc</file>, you should still put
6042 the files in <file>/etc</file> and create symbolic links to
6043 those files from the location that the package
6048 <heading>Behavior</heading>
6050 Configuration file handling must conform to the following
6052 <list compact="compact">
6055 local changes must be preserved during a package
6061 configuration files must be preserved when the
6062 package is removed, and only deleted when the
6070 The easy way to achieve this behavior is to make the
6071 configuration file a <tt>conffile</tt>. This is
6072 appropriate only if it is possible to distribute a default
6073 version that will work for most installations, although
6074 some system administrators may choose to modify it. This
6075 implies that the default version will be part of the
6076 package distribution, and must not be modified by the
6077 maintainer scripts during installation (or at any other
6082 In order to ensure that local changes are preserved
6083 correctly, no package may contain or make hard links to
6084 conffiles.<footnote>
6086 Rationale: There are two problems with hard links.
6087 The first is that some editors break the link while
6088 editing one of the files, so that the two files may
6089 unwittingly become unlinked and different. The second
6090 is that <prgn>dpkg</prgn> might break the hard link
6091 while upgrading <tt>conffile</tt>s.
6097 The other way to do it is via the maintainer scripts. In
6098 this case, the configuration file must not be listed as a
6099 <tt>conffile</tt> and must not be part of the package
6100 distribution. If the existence of a file is required for
6101 the package to be sensibly configured it is the
6102 responsibility of the package maintainer to provide
6103 maintainer scripts which correctly create, update and
6104 maintain the file and remove it on purge. (See <ref
6105 id="maintainerscripts"> for more information.) These
6106 scripts must be idempotent (i.e., must work correctly if
6107 <prgn>dpkg</prgn> needs to re-run them due to errors
6108 during installation or removal), must cope with all the
6109 variety of ways <prgn>dpkg</prgn> can call maintainer
6110 scripts, must not overwrite or otherwise mangle the user's
6111 configuration without asking, must not ask unnecessary
6112 questions (particularly during upgrades), and otherwise be
6117 The scripts are not required to configure every possible
6118 option for the package, but only those necessary to get
6119 the package running on a given system. Ideally the
6120 sysadmin should not have to do any configuration other
6121 than that done (semi-)automatically by the
6122 <prgn>postinst</prgn> script.
6126 A common practice is to create a script called
6127 <file><var>package</var>-configure</file> and have the
6128 package's <prgn>postinst</prgn> call it if and only if the
6129 configuration file does not already exist. In certain
6130 cases it is useful for there to be an example or template
6131 file which the maintainer scripts use. Such files should
6132 be in <file>/usr/share/<var>package</var></file> or
6133 <file>/usr/lib/<var>package</var></file> (depending on whether
6134 they are architecture-independent or not). There should
6135 be symbolic links to them from
6136 <file>/usr/share/doc/<var>package</var>/examples</file> if
6137 they are examples, and should be perfectly ordinary
6138 <prgn>dpkg</prgn>-handled files (<em>not</em>
6139 configuration files).
6143 These two styles of configuration file handling must
6144 not be mixed, for that way lies madness:
6145 <prgn>dpkg</prgn> will ask about overwriting the file
6146 every time the package is upgraded.
6151 <heading>Sharing configuration files</heading>
6153 Packages which specify the same file as a
6154 <tt>conffile</tt> must be tagged as <em>conflicting</em>
6155 with each other. (This is an instance of the general rule
6156 about not sharing files. Note that neither alternatives
6157 nor diversions are likely to be appropriate in this case;
6158 in particular, <prgn>dpkg</prgn> does not handle diverted
6159 <tt>conffile</tt>s well.)
6163 The maintainer scripts must not alter a <tt>conffile</tt>
6164 of <em>any</em> package, including the one the scripts
6169 If two or more packages use the same configuration file
6170 and it is reasonable for both to be installed at the same
6171 time, one of these packages must be defined as
6172 <em>owner</em> of the configuration file, i.e., it will be
6173 the package which handles that file as a configuration
6174 file. Other packages that use the configuration file must
6175 depend on the owning package if they require the
6176 configuration file to operate. If the other package will
6177 use the configuration file if present, but is capable of
6178 operating without it, no dependency need be declared.</p>
6181 If it is desirable for two or more related packages to
6182 share a configuration file <em>and</em> for all of the
6183 related packages to be able to modify that configuration
6184 file, then the following should be done:
6185 <enumlist compact="compact">
6188 One of the related packages (the "owning" package)
6189 will manage the configuration file with maintainer
6190 scripts as described in the previous section.
6195 The owning package should also provide a program
6196 that the other packages may use to modify the
6202 The related packages must use the provided program
6203 to make any desired modifications to the
6204 configuration file. They should either depend on
6205 the core package to guarantee that the configuration
6206 modifier program is available or accept gracefully
6207 that they cannot modify the configuration file if it
6208 is not. (This is in addition to the fact that the
6209 configuration file may not even be present in the
6217 Sometimes it's appropriate to create a new package which
6218 provides the basic infrastructure for the other packages
6219 and which manages the shared configuration files. (The
6220 <tt>sgml-base</tt> package is a good example.)
6225 <heading>User configuration files ("dotfiles")</heading>
6228 The files in <file>/etc/skel</file> will automatically be
6229 copied into new user accounts by <prgn>adduser</prgn>.
6230 No other program should reference the files in
6231 <file>/etc/skel</file>.
6235 Therefore, if a program needs a dotfile to exist in
6236 advance in <file>$HOME</file> to work sensibly, that dotfile
6237 should be installed in <file>/etc/skel</file> and treated as a
6242 However, programs that require dotfiles in order to
6243 operate sensibly (dotfiles that they do not create
6244 themselves automatically, that is) are a bad thing.
6245 Furthermore, programs should be configured by the Debian
6246 default installation to behave as closely to the upstream
6247 default behaviour as possible.
6251 Therefore, if a program in a Debian package needs to be
6252 configured in some way in order to operate sensibly, that
6253 should be done using a site-wide configuration file placed
6254 in <file>/etc</file>. Only if the program doesn't support a
6255 site-wide default configuration and the package maintainer
6256 doesn't have time to add it may a default per-user file be
6257 placed in <file>/etc/skel</file>.
6261 <file>/etc/skel</file> should be as empty as we can make it.
6262 This is particularly true because there is no easy (or
6263 necessarily desirable) mechanism for ensuring that the
6264 appropriate dotfiles are copied into the accounts of
6265 existing users when a package is installed.
6271 <heading>Log files</heading>
6273 Log files should usually be named
6274 <file>/var/log/<var>package</var>.log</file>. If you have many
6275 log files, or need a separate directory for permission
6276 reasons (<file>/var/log</file> is writable only by
6277 <file>root</file>), you should usually create a directory named
6278 <file>/var/log/<var>package</var></file> and place your log
6283 Log files must be rotated occasionally so that they don't
6284 grow indefinitely; the best way to do this is to drop a log
6285 rotation configuration file into the directory
6286 <file>/etc/logrotate.d</file> and use the facilities provided by
6287 logrotate.<footnote>
6289 The traditional approach to log files has been to set up
6290 <em>ad hoc</em> log rotation schemes using simple shell
6291 scripts and cron. While this approach is highly
6292 customizable, it requires quite a lot of sysadmin work.
6293 Even though the original Debian system helped a little
6294 by automatically installing a system which can be used
6295 as a template, this was deemed not enough.
6299 The use of <prgn>logrotate</prgn>, a program developed
6300 by Red Hat, is better, as it centralizes log management.
6301 It has both a configuration file
6302 (<file>/etc/logrotate.conf</file>) and a directory where
6303 packages can drop their individual log rotation
6304 configurations (<file>/etc/logrotate.d</file>).
6307 Here is a good example for a logrotate config
6308 file (for more information see <manref name="logrotate"
6310 <example compact="compact">
6316 /etc/init.d/foo force-reload
6320 This rotates all files under <file>/var/log/foo</file>, saves 12
6321 compressed generations, and forces the daemon to reload its
6322 configuration information after the log rotation.
6326 Log files should be removed when the package is
6327 purged (but not when it is only removed). This should be
6328 done by the <prgn>postrm</prgn> script when it is called
6329 with the argument <tt>purge</tt> (see <ref
6330 id="removedetails">).
6335 <heading>Permissions and owners</heading>
6338 The rules in this section are guidelines for general use.
6339 If necessary you may deviate from the details below.
6340 However, if you do so you must make sure that what is done
6341 is secure and you should try to be as consistent as possible
6342 with the rest of the system. You should probably also
6343 discuss it on <prgn>debian-devel</prgn> first.
6347 Files should be owned by <tt>root.root</tt>, and made
6348 writable only by the owner and universally readable (and
6349 executable, if appropriate), that is mode 644 or 755.
6353 Directories should be mode 755 or (for group-writability)
6354 mode 2775. The ownership of the directory should be
6355 consistent with its mode: if a directory is mode 2775, it
6356 should be owned by the group that needs write access to
6361 Setuid and setgid executables should be mode 4755 or 2755
6362 respectively, and owned by the appropriate user or group.
6363 They should not be made unreadable (modes like 4711 or
6364 2711 or even 4111); doing so achieves no extra security,
6365 because anyone can find the binary in the freely available
6366 Debian package; it is merely inconvenient. For the same
6367 reason you should not restrict read or execute permissions
6368 on non-set-id executables.
6372 Some setuid programs need to be restricted to particular
6373 sets of users, using file permissions. In this case they
6374 should be owned by the uid to which they are set-id, and by
6375 the group which should be allowed to execute them. They
6376 should have mode 4754; again there is no point in making
6377 them unreadable to those users who must not be allowed to
6382 It is possible to arrange that the system administrator can
6383 reconfigure the package to correspond to their local
6384 security policy by changing the permissions on a binary:
6385 they can do this by using <prgn>dpkg-statoverride</prgn>, as
6386 described below.<footnote>
6388 Ordinary files installed by <prgn>dpkg</prgn> (as
6389 opposed to <tt>conffile</tt>s and other similar objects)
6390 normally have their permissions reset to the distributed
6391 permissions when the package is reinstalled. However,
6392 the use of <prgn>dpkg-statoverride</prgn> overrides this
6393 default behaviour. If you use this method, you should
6394 remember to describe <prgn>dpkg-statoverride</prgn> in
6395 the package documentation; being a relatively new
6396 addition to Debian, it is probably not yet well-known.
6399 Another method you should consider is to create a group for
6400 people allowed to use the program(s) and make any setuid
6401 executables executable only by that group.
6405 If you need to create a new user or group for your package
6406 there are two possibilities. Firstly, you may need to
6407 make some files in the binary package be owned by this
6408 user or group, or you may need to compile the user or
6409 group id (rather than just the name) into the binary
6410 (though this latter should be avoided if possible, as in
6411 this case you need a statically allocated id).</p>
6414 If you need a statically allocated id, you must ask for a
6415 user or group id from the <tt>base-passwd</tt> maintainer,
6416 and must not release the package until you have been
6417 allocated one. Once you have been allocated one you must
6418 either make the package depend on a version of the
6419 <tt>base-passwd</tt> package with the id present in
6420 <file>/etc/passwd</file> or <file>/etc/group</file>, or arrange for
6421 your package to create the user or group itself with the
6422 correct id (using <tt>adduser</tt>) in its
6423 <prgn>preinst</prgn> or <prgn>postinst</prgn>. (Doing it in
6424 the <prgn>postinst</prgn> is to be preferred if it is
6425 possible, otherwise a pre-dependency will be needed on the
6426 <tt>adduser</tt> package.)
6430 On the other hand, the program might be able to determine
6431 the uid or gid from the user or group name at runtime, so
6432 that a dynamically allocated id can be used. In this case
6433 you should choose an appropriate user or group name,
6434 discussing this on <prgn>debian-devel</prgn> and checking
6435 with the base system maintainer that it is unique and that
6436 they do not wish you to use a statically allocated id
6437 instead. When this has been checked you must arrange for
6438 your package to create the user or group if necessary using
6439 <prgn>adduser</prgn> in the <prgn>preinst</prgn> or
6440 <prgn>postinst</prgn> script (again, the latter is to be
6441 preferred if it is possible).
6445 Note that changing the numeric value of an id associated
6446 with a name is very difficult, and involves searching the
6447 file system for all appropriate files. You need to think
6448 carefully whether a static or dynamic id is required, since
6449 changing your mind later will cause problems.
6452 <sect1><heading>The use of <prgn>dpkg-statoverride</prgn></heading>
6454 This section is not intended as policy, but as a
6455 description of the use of <prgn>dpkg-statoverride</prgn>.
6459 <prgn>dpkg-statoverride</prgn> is a replacement for the
6460 deprecated <tt>suidmanager</tt> package. Packages which
6461 previously used <tt>suidmanager</tt> should have a
6462 <tt>Conflicts: suidmanager (<< 0.50)</tt> entry (or even
6463 <tt>(<< 0.52)</tt>), and calls to <tt>suidregister</tt>
6464 and <tt>suidunregister</tt> should now be simply removed
6465 from the maintainer scripts.
6469 If a system administrator wishes to have a file (or
6470 directory or other such thing) installed with owner and
6471 permissions different from those in the distributed Debian
6472 package, he can use the <prgn>dpkg-statoverride</prgn>
6473 program to instruct <prgn>dpkg</prgn> to use the different
6474 settings every time the file is installed. Thus the
6475 package maintainer should distribute the files with their
6476 normal permissions, and leave it for the system
6477 administrator to make any desired changes. For example, a
6478 daemon which is normally required to be setuid root, but
6479 in certain situations could be used without being setuid,
6480 should be installed setuid in the <tt>.deb</tt>. Then the
6481 local system administrator can change this if they wish.
6482 If there are two standard ways of doing it, the package
6483 maintainer can use <tt>debconf</tt> to find out the
6484 preference, and call <prgn>dpkg-statoverride</prgn> in the
6485 maintainer script if necessary to accommodate the system
6486 administrator's choice.
6490 Given the above, <prgn>dpkg-statoverride</prgn> is
6491 essentially a tool for system administrators and would not
6492 normally be needed in the maintainer scripts. There is
6493 one type of situation, though, where calls to
6494 <prgn>dpkg-statoverride</prgn> would be needed in the
6495 maintainer scripts, and that involves packages which use
6496 dynamically allocated user or group ids. In such a
6497 situation, something like the following idiom can be very
6498 helpful in the package's <prgn>postinst</prgn>, where
6499 <tt>sysuser</tt> is a dynamically allocated id:
6501 for i in /usr/bin/foo /usr/sbin/bar
6503 if ! dpkg-statoverride --list $i >/dev/null
6505 dpkg-statoverride --update --add sysuser root 4755 $i
6509 The corresponding <tt>dpkg-statoverride --remove</tt>
6510 calls can then be made unconditionally when the package is
6517 <chapt id="customized-programs">
6518 <heading>Customized programs</heading>
6520 <sect id="arch-spec">
6521 <heading>Architecture specification strings</heading>
6524 If a program needs to specify an <em>architecture specification
6525 string</em> in some place, the following format should be
6526 used: <var>arch</var>-<var>os</var><footnote>
6528 The following architectures and operating systems are
6529 currently recognised by <prgn>dpkg-archictecture</prgn>.
6530 The architecture, <tt><var>arch</var></tt>, is one of
6531 the following: <tt>alpha</tt>, <tt>arm</tt>,
6532 <tt>hppa</tt>, <tt>i386</tt>, <tt>ia64</tt>,
6533 <tt>m68k</tt>, <tt>mips</tt>, <tt>mipsel</tt>,
6534 <tt>powerpc</tt>, <tt>s390</tt>, <tt>sh</tt>,
6535 <tt>sheb</tt>, <tt>sparc</tt> and <tt>sparc64</tt>. The
6536 operating system, <tt><var>os</var></tt>, is one of:
6537 <tt>linux</tt>, <tt>gnu</tt>, <tt>freebsd</tt> and
6538 <tt>openbsd</tt>. Use of <tt>gnu</tt> in this string is
6539 reserved for the GNU/Hurd operating system.
6545 Note that we don't want to use
6546 <tt><var>arch</var>-debian-linux</tt> to apply to the rule
6547 <tt><var>architecture</var>-<var>vendor</var>-<var>os</var></tt>
6548 since this would make our programs incompatible with other
6549 Linux distributions. We also don't use something like
6550 <tt><var>arch</var>-unknown-linux</tt>, since the
6551 <tt>unknown</tt> does not look very good.
6556 <heading>Daemons</heading>
6559 The configuration files <file>/etc/services</file>,
6560 <file>/etc/protocols</file>, and <file>/etc/rpc</file> are managed
6561 by the <prgn>netbase</prgn> package and must not be modified
6566 If a package requires a new entry in one of these files, the
6567 maintainer should get in contact with the
6568 <prgn>netbase</prgn> maintainer, who will add the entries
6569 and release a new version of the <prgn>netbase</prgn>
6574 The configuration file <file>/etc/inetd.conf</file> must not be
6575 modified by the package's scripts except via the
6576 <prgn>update-inetd</prgn> script or the
6577 <file>DebianNet.pm</file> Perl module. See their documentation
6578 for details on how to add entries.
6582 If a package wants to install an example entry into
6583 <file>/etc/inetd.conf</file>, the entry must be preceded with
6584 exactly one hash character (<tt>#</tt>). Such lines are
6585 treated as `commented out by user' by the
6586 <prgn>update-inetd</prgn> script and are not changed or
6587 activated during package updates.
6592 <heading>Using pseudo-ttys and modifying wtmp, utmp and
6596 Some programs need to create pseudo-ttys. This should be done
6597 using Unix98 ptys if the C library supports it. The resulting
6598 program must not be installed setuid root, unless that
6599 is required for other functionality.
6603 The files <file>/var/run/utmp</file>, <file>/var/log/wtmp</file> and
6604 <file>/var/log/lastlog</file> must be installed writeable by
6605 group <tt>utmp</tt>. Programs which need to modify those
6606 files must be installed setgid <tt>utmp</tt>.
6611 <heading>Editors and pagers</heading>
6614 Some programs have the ability to launch an editor or pager
6615 program to edit or display a text document. Since there are
6616 lots of different editors and pagers available in the Debian
6617 distribution, the system administrator and each user should
6618 have the possibility to choose his/her preferred editor and
6623 In addition, every program should choose a good default
6624 editor/pager if none is selected by the user or system
6629 Thus, every program that launches an editor or pager must
6630 use the EDITOR or PAGER environment variable to determine
6631 the editor or pager the user wishes to use. If these
6632 variables are not set, the programs <file>/usr/bin/editor</file>
6633 and <file>/usr/bin/pager</file> should be used, respectively.
6637 These two files are managed through the <prgn>dpkg</prgn>
6638 `alternatives' mechanism. Thus every package providing an
6639 editor or pager must call the
6640 <prgn>update-alternatives</prgn> script to register these
6645 If it is very hard to adapt a program to make use of the
6646 EDITOR or PAGER variables, that program may be configured to
6647 use <file>/usr/bin/sensible-editor</file> and
6648 <file>/usr/bin/sensible-pager</file> as the editor or pager
6649 program respectively. These are two scripts provided in the
6650 Debian base system that check the EDITOR and PAGER variables
6651 and launch the appropriate program, and fall back to
6652 <file>/usr/bin/editor</file> and <file>/usr/bin/pager</file> if the
6653 variable is not set.
6657 A program may also use the VISUAL environment variable to
6658 determine the user's choice of editor. If it exists, it
6659 should take precedence over EDITOR. This is in fact what
6660 <file>/usr/bin/sensible-editor</file> does.
6664 It is not required for a package to depend on
6665 <tt>editor</tt> and <tt>pager</tt>, nor is it required for a
6666 package to provide such virtual packages.<footnote>
6668 The Debian base system already provides an editor and a
6675 <sect id="web-appl">
6676 <heading>Web servers and applications</heading>
6679 This section describes the locations and URLs that should
6680 be used by all web servers and web applications in the
6688 Cgi-bin executable files are installed in the
6690 <example compact="compact">
6691 /usr/lib/cgi-bin/<var>cgi-bin-name</var>
6693 and should be referred to as
6694 <example compact="compact">
6695 http://localhost/cgi-bin/<var>cgi-bin-name</var>
6700 <item><p>Access to HTML documents</p>
6703 HTML documents for a package are stored in
6704 <file>/usr/share/doc/<var>package</var></file>
6705 and can be referred to as
6706 <example compact="compact">
6707 http://localhost/doc/<var>package</var>/<var>filename</var>
6711 The web server should restrict access to the document
6712 tree so that only clients on the same host can read
6713 the documents. If the web server does not support such
6714 access controls, then it should not provide access at
6715 all, or ask about providing access during installation.
6719 <item><p>Web Document Root</p>
6722 Web Applications should try to avoid storing files in
6723 the Web Document Root. Instead they should use the
6724 /usr/share/doc/<var>package</var> directory for
6725 documents and register the Web Application via the
6726 menu package. If access to the web document root is
6727 unavoidable then use
6728 <example compact="compact">
6731 as the Document Root. This might be just a symbolic
6732 link to the location where the system administrator
6733 has put the real document root.
6737 </enumlist></p></sect>
6740 <sect id="mail-transport-agents">
6741 <heading>Mail transport, delivery and user agents</heading>
6744 Debian packages which process electronic mail, whether mail
6745 user agents (MUAs) or mail transport agents (MTAs), must
6746 ensure that they are compatible with the configuration
6747 decisions below. Failure to do this may result in lost
6748 mail, broken <tt>From:</tt> lines, and other serious brain
6753 The mail spool is <file>/var/mail</file> and the interface to
6754 send a mail message is <file>/usr/sbin/sendmail</file> (as per
6755 the FHS). On older systems, the mail spool may be
6756 physically located in <file>/var/spool/mail</file>, but all
6757 access to the mail spool should be via the
6758 <file>/var/mail</file> symlink. The mail spool is part of the
6759 base system and not part of the MTA package.
6763 All Debian MUAs, MTAs, MDAs and other mailbox accessing
6764 programs (such as IMAP daemons) must lock the mailbox in an
6765 NFS-safe way. This means that <tt>fcntl()</tt> locking must
6766 be combined with dot locking. To avoid deadlocks, a program
6767 should use <tt>fcntl()</tt> first and dot locking after
6768 this, or alternatively implement the two locking methods in
6769 a non blocking way<footnote>
6771 If it is not possible to establish both locks, the
6772 system shouldn't wait for the second lock to be
6773 established, but remove the first lock, wait a (random)
6774 time, and start over locking again.
6776 </footnote>. Using the functions <tt>maillock</tt> and
6777 <tt>mailunlock</tt> provided by the
6778 <tt>liblockfile*</tt><footnote>
6780 You will need to depend on <tt>liblockfile1
6781 (>>1.01)</tt> to use these functions.
6783 </footnote> packages is the recommended way to realize this.
6787 Mailboxes are generally mode 660
6788 <tt><var>user</var>.mail</tt> unless the system
6789 administrator has chosen otherwise. A MUA may remove a
6790 mailbox (unless it has nonstandard permissions) in which
6791 case the MTA or another MUA must recreate it if needed.
6792 Mailboxes must be writable by group mail.
6796 The mail spool is 2775 <tt>root.mail</tt>, and MUAs should
6797 be setgid mail to do the locking mentioned above (and
6798 must obviously avoid accessing other users' mailboxes
6799 using this privilege).</p>
6802 <file>/etc/aliases</file> is the source file for the system mail
6803 aliases (e.g., postmaster, usenet, etc.), it is the one
6804 which the sysadmin and <prgn>postinst</prgn> scripts may
6805 edit. After <file>/etc/aliases</file> is edited the program or
6806 human editing it must call <prgn>newaliases</prgn>. All MTA
6807 packages must come with a <prgn>newaliases</prgn> program,
6808 even if it does nothing, but older MTA packages did not do
6809 this so programs should not fail if <prgn>newaliases</prgn>
6810 cannot be found. Note that because of this, all MTA
6811 packages must have <tt>Provides</tt>, <tt>Conflicts</tt> and
6812 <tt>Replaces: mail-transport-agent</tt> control file
6817 The convention of writing <tt>forward to
6818 <var>address</var></tt> in the mailbox itself is not
6819 supported. Use a <tt>.forward</tt> file instead.</p>
6822 The <prgn>rmail</prgn> program used by UUCP
6823 for incoming mail should be <file>/usr/sbin/rmail</file>.
6824 Likewise, <prgn>rsmtp</prgn>, for receiving
6825 batch-SMTP-over-UUCP, should be <file>/usr/sbin/rsmtp</file> if it
6829 If your package needs to know what hostname to use on (for
6830 example) outgoing news and mail messages which are generated
6831 locally, you should use the file <file>/etc/mailname</file>. It
6832 will contain the portion after the username and <tt>@</tt>
6833 (at) sign for email addresses of users on the machine
6834 (followed by a newline).
6838 Such package should check for the existence of this file
6839 when it is being configured. If it exists, it should be
6840 used without comment, although an MTA's configuration script
6841 may wish to prompt the user even if it finds that this file
6842 exists. If the file does not exist, the package should
6843 prompt the user for the value (preferably using
6844 <prgn>debconf</prgn>) and store it in <file>/etc/mailname</file>
6845 as well as using it in the package's configuration. The
6846 prompt should make it clear that the name will not just be
6847 used by that package. For example, in this situation the
6848 <tt>inn</tt> package could say something like:
6849 <example compact="compact">
6850 Please enter the `mail name' of your system. This is the
6851 hostname portion of the address to be shown on outgoing
6852 news and mail messages. The default is
6853 <var>syshostname</var>, your system's host name. Mail
6854 name [`<var>syshostname</var>']:
6856 where <var>syshostname</var> is the output of <tt>hostname
6862 <heading>News system configuration</heading>
6865 All the configuration files related to the NNTP (news)
6866 servers and clients should be located under
6867 <file>/etc/news</file>.</p>
6870 There are some configuration issues that apply to a number
6871 of news clients and server packages on the machine. These
6875 <tag><file>/etc/news/organization</file></tag>
6876 <item><p>A string which should appear as the
6877 organization header for all messages posted
6878 by NNTP clients on the machine</p></item>
6880 <tag><file>/etc/news/server</file></tag>
6881 <item><p>Contains the FQDN of the upstream NNTP
6882 server, or localhost if the local machine is
6883 an NNTP server.</p></item>
6886 Other global files may be added as required for cross-package news
6887 configuration.</p></sect>
6891 <heading>Programs for the X Window System</heading>
6894 <heading>Providing X support and package priorities</heading>
6897 Programs that can be configured with support for the X
6898 Window System must be configured to do so and must declare
6899 any package dependencies necessary to satisfy their
6900 runtime requirements when using the X Window System. If
6901 such a package is of higher priority than the X packages
6902 on which it depends, it is required that either the
6903 X-specific components be split into a separate package, or
6904 that an alternative version of the package, which includes
6905 X support, be provided, or that the package's priority be
6911 <heading>Packages providing an X server</heading>
6914 Packages that provide an X server that, directly or
6915 indirectly, communicates with real input and display
6916 hardware should declare in their control data that they
6917 provide the virtual package <tt>xserver</tt>.<footnote>
6919 This implements current practice, and provides an
6920 actual policy for usage of the <tt>xserver</tt>
6921 virtual package which appears in the virtual packages
6922 list. In a nutshell, X servers that interface
6923 directly with the display and input hardware or via
6924 another subsystem (e.g., GGI) should provide
6925 <tt>xserver</tt>. Things like <tt>Xvfb</tt>,
6926 <tt>Xnest</tt>, and <tt>Xprt</tt> should not.
6933 <heading>Packages providing a terminal emulator</heading>
6936 Packages that provide a terminal emulator for the X Window
6937 System which meet the criteria listed below should declare
6938 in their control data that they provide the virtual
6939 package <tt>x-terminal-emulator</tt>. They should also
6940 register themselves as an alternative for
6941 <file>/usr/bin/x-terminal-emulator</file>, with a priority of
6946 To be an <tt>x-terminal-emulator</tt>, a program must:
6947 <list compact="compact">
6949 Be able to emulate a DEC VT100 terminal, or a
6950 compatible terminal.
6954 Support the command-line option <tt>-e
6955 <var>command</var></tt>, which creates a new
6956 terminal window<footnote>
6958 "New terminal window" does not necessarily mean
6959 a new top-level X window directly parented by
6960 the window manager; it could, if the terminal
6961 emulator application were so coded, be a new
6962 "view" in a multiple-document interface (MDI).
6965 and runs the specified <var>command</var>.
6969 Support the command-line option <tt>-T
6970 <var>title</var></tt>, which creates a new terminal
6971 window with the window title <var>title</var>.
6978 <heading>Packages providing a window manager</heading>
6981 Packages that provide a window manager should declare in
6982 their control data that they provide the virtual package
6983 <tt>x-window-manager</tt>. They should also register
6984 themselves as an alternative for
6985 <file>/usr/bin/x-window-manager</file>, with a priority
6986 calculated as follows:
6987 <list compact="compact">
6988 <item><p>Start with a priority of 20.</p></item>
6992 If the window manager supports the Debian menu
6993 system, add 20 points if this support is available
6994 in the package's default configuration (i.e., no
6995 configuration files belonging to the system or user
6996 have to be edited to activate the feature); if
6997 configuration files must be modified, add only 10
7003 If the window manager complies with <url
7004 id="http://www.freedesktop.org/standards/wm-spec.html"
7005 name="The Window Manager Specification Project">,
7006 written by the <url id="http://www.freedesktop.org"
7007 name="Free Desktop Group">, add 20 points.
7013 If the window manager permits the X session to be
7014 restarted using a <em>different</em> window manager
7015 (without killing the X server) in its default
7016 configuration, add 10 points; otherwise add none.
7024 <heading>Packages providing fonts</heading>
7027 Packages that provide fonts for the X Window
7030 For the purposes of Debian Policy, a "font for the X
7031 Window System" is one which is accessed via X protocol
7032 requests. Fonts for the Linux console, for PostScript
7033 renderers, or any other purpose, do not fit this
7034 definition. Any tool which makes such fonts available
7035 to the X Window System, however, must abide by this
7039 must do a number of things to ensure that they are both
7040 available without modification of the X or font server
7041 configuration, and that they do not corrupt files used by
7042 other font packages to register information about
7047 Fonts of any type supported by the X Window System
7048 must be in a separate binary package from any
7049 executables, libraries, or documentation (except
7050 that specific to the fonts shipped, such as their
7051 license information). If one or more of the fonts
7052 so packaged are necessary for proper operation of
7053 the package with which they are associated the font
7054 package may be Recommended; if the fonts merely
7055 provide an enhancement, a Suggests relationship may
7056 be used. Packages must not Depend on font
7059 This is because the X server may retrieve fonts
7060 from the local filesystem or over the network
7061 from an X font server; the Debian package system
7062 is empowered to deal only with the local
7071 BDF fonts must be converted to PCF fonts with the
7072 <prgn>bdftopcf</prgn> utility (available in the
7073 <tt>xutils</tt> package, <tt>gzip</tt>ped, and
7074 placed in a directory that corresponds to their
7076 <list compact="compact">
7078 100 dpi fonts must be placed in
7079 <file>/usr/X11R6/lib/X11/fonts/100dpi/</file>.
7083 75 dpi fonts must be placed in
7084 <file>/usr/X11R6/lib/X11/fonts/75dpi/</file>.
7088 Character-cell fonts, cursor fonts, and other
7089 low-resolution fonts must be placed in
7090 <file>/usr/X11R6/lib/X11/fonts/misc/</file>.
7097 Speedo fonts must be placed in
7098 <file>/usr/X11R6/lib/X11/fonts/Speedo/</file>.
7102 Type 1 fonts must be placed in
7103 <file>/usr/X11R6/lib/X11/fonts/Type1/</file>. If font
7104 metric files are available, they must be placed here
7110 Subdirectories of <file>/usr/X11R6/lib/X11/fonts/</file>
7111 other than those listed above must be neither
7112 created nor used. (The <file>PEX</file>, <file>CID</file>,
7113 and <file>cyrillic</file> directories are excepted for
7114 historical reasons, but installation of files into
7115 these directories remains discouraged.)
7121 Font packages may, instead of placing files directly
7122 in the X font directories listed above, provide
7123 symbolic links in that font directory pointing to
7124 the files' actual location in the filesystem. Such
7125 a location must comply with the FHS.
7131 Font packages should not contain both 75dpi and
7132 100dpi versions of a font. If both are available,
7133 they should be provided in separate binary packages
7134 with <tt>-75dpi</tt> or <tt>-100dpi</tt> appended to
7135 the names of the packages containing the
7136 corresponding fonts.
7142 Fonts destined for the <file>misc</file> subdirectory
7143 should not be included in the same package as 75dpi
7144 or 100dpi fonts; instead, they should be provided in
7145 a separate package with <tt>-misc</tt> appended to
7152 Font packages must not provide the files
7153 <file>fonts.dir</file>, <file>fonts.alias</file>, or
7154 <file>fonts.scale</file> in a font directory:
7157 <file>fonts.dir</file> files must not be provided at all.
7162 <file>fonts.alias</file> and <file>fonts.scale</file>
7163 files, if needed, should be provided in the
7165 <file>/etc/X11/fonts/<var>fontdir</var>/<var>package</var>.<var>extension</var></file>,
7166 where <var>fontdir</var> is the name of the
7168 <file>/usr/X11R6/lib/X11/fonts/</file> where the
7169 package's corresponding fonts are stored
7170 (e.g., <tt>75dpi</tt> or <tt>misc</tt>),
7171 <var>package</var> is the name of the package
7172 that provides these fonts, and
7173 <var>extension</var> is either <tt>scale</tt>
7174 or <tt>alias</tt>, whichever corresponds to
7184 Font packages must declare a dependency on
7185 <tt>xutils (>> 4.0.3)</tt> in their control
7192 Font packages that provide one or more
7193 <file>fonts.scale</file> files as described above must
7194 invoke <prgn>update-fonts-scale</prgn> on each
7195 directory into which they installed fonts
7196 <em>before</em> invoking
7197 <prgn>update-fonts-dir</prgn> on that directory.
7198 This invocation must occur in both the
7199 <prgn>postinst</prgn> (for all arguments) and
7200 <prgn>postrm</prgn> (for all arguments except
7201 <tt>upgrade</tt>) scripts.
7207 Font packages that provide one or more
7208 <file>fonts.alias</file> files as described above must
7209 invoke <prgn>update-fonts-alias</prgn> on each
7210 directory into which they installed fonts. This
7211 invocation must occur in both the
7212 <prgn>postinst</prgn> (for all arguments) and
7213 <prgn>postrm</prgn> (for all arguments except
7214 <tt>upgrade</tt>) scripts.
7220 Font packages must invoke
7221 <prgn>update-fonts-dir</prgn> on each directory into
7222 which they installed fonts. This invocation must
7223 occur in both the <prgn>postinst</prgn> (for all
7224 arguments) and <prgn>postrm</prgn> (for all
7225 arguments except <tt>upgrade</tt>) scripts.
7231 Font packages must not provide alias names for the
7232 fonts they include which collide with alias names
7233 already in use by fonts already packaged.
7239 Font packages must not provide fonts with the same
7240 XLFD registry name as another font already packaged.
7248 <heading>Application defaults files</heading>
7251 Application defaults files must be installed in the
7252 directory <file>/etc/X11/app-defaults/</file> (use of a
7253 localized subdirectory of <file>/etc/X11/</file> as described
7254 in the <em>X Toolkit Intrinsics - C Language
7255 Interface</em> manual is also permitted). They must be
7256 registered as <tt>conffile</tt>s or handled as
7257 configuration files. Packages must not provide the
7258 directory <file>/usr/X11R6/lib/X11/app-defaults/</file>.
7262 Customization of programs' X resources may also be
7263 supported with the provision of a file with the same name
7264 as that of the package placed in the
7265 <file>/etc/X11/Xresources/</file> directory, which must
7266 registered as a <tt>conffile</tt> or handled as a
7267 configuration file.<footnote>
7269 Note that this mechanism is not the same as using
7270 app-defaults; app-defaults are tied to the client
7271 binary on the local filesystem, whereas X resources
7272 are stored in the X server and affect all connecting
7276 <em>Important:</em> packages that install files into the
7277 <file>/etc/X11/Xresources/</file> directory must conflict with
7278 <tt>xbase (<< 3.3.2.3a-2)</tt>; if this is not done
7279 it is possible for the installing package to destroy a
7280 previously-existing <file>/etc/X11/Xresources</file> file
7281 which had been customized by the system administrator.
7286 <heading>Installation directory issues</heading>
7289 Packages using the X Window System should not be
7290 configured to install files under the <file>/usr/X11R6/</file>
7291 directory unless they use <prgn>imake</prgn>. The
7292 <file>/usr/X11R6/</file> directory hierarchy should be
7293 regarded as deprecated for all packages except the X
7294 Window System itself, and those which use the
7295 <prgn>imake</prgn> program it provides, in which case the
7296 packages may transition out of the <file>/usr/X11R6/</file>
7297 directory at the maintainer's discretion.<footnote>
7299 <prgn>Imake</prgn>-using programs are exempt because,
7300 as long as they are written correctly, the pathnames
7301 they use to locate resources and install themselves
7302 are derived wholly from the X Window System
7303 configuration. Thus, in the event that the X Window
7304 System moves to <file>/usr/X11R7/</file>,
7305 <file>/usr/X12/</file>, or just plain <file>/usr/</file>, all
7306 that is required for these programs is a recompile
7307 against the corresponding X Window System library
7308 development packages.
7311 Programs that use GNU <prgn>autoconf</prgn> and
7312 <prgn>automake</prgn> are usually easily configured at
7313 compile time to use <file>/usr/</file> instead of
7314 <file>/usr/X11R6/</file>, and this should be done whenever
7315 possible. Configuration files for window managers and
7316 display managers should be placed in a subdirectory of
7317 <file>/etc/X11/</file> corresponding to the package name due
7318 to these programs' tight integration with the mechanisms
7319 of the X Window System. Application-level programs should
7320 use the <file>/etc/</file> directory unless otherwise mandated
7321 by policy. The installation of files into subdirectories
7322 of <file>/usr/X11R6/include/X11/</file> and
7323 <file>/usr/X11R6/lib/X11/</file> is permitted but discouraged;
7324 package maintainers should determine if subdirectories of
7325 <file>/usr/lib/</file> and <file>/usr/share/</file> can be used
7326 instead. (The use of symbolic links from the
7327 <file>X11R6</file> directories to other FHS-compliant
7328 locations is encouraged if the program is not easily
7329 configured to look elsewhere for its files.) Packages
7330 must not provide or install files into the directories
7331 <file>/usr/bin/X11/</file>, <file>/usr/include/X11/</file> or
7332 <file>/usr/lib/X11/</file>. Files within a package should,
7333 however, make reference to these directories, rather than
7334 their <tt>X11R6</tt>-named counterparts
7335 <file>/usr/X11R6/bin/</file>, <file>/usr/X11R6/include/X11/</file>
7336 and <file>/usr/X11R6/lib/X11/</file>, if the resources being
7337 referred to have not been moved to other FHS-compliant
7343 <heading>The OSF/Motif and OpenMotif libraries</heading>
7346 <em>Programs that require the non-DFSG-compliant OSF/Motif or
7347 OpenMotif libraries</em><footnote>
7349 OSF/Motif and OpenMotif are collectively referred to as
7350 "Motif" in this policy document.
7353 should be compiled against and tested with LessTif (a free
7354 re-implementation of Motif) instead. If the maintainer
7355 judges that the program or programs do not work
7356 sufficiently well with LessTif to be distributed and
7357 supported, but do so when compiled against Motif, then two
7358 versions of the package should be created; one linked
7359 statically against Motif and with <tt>-smotif</tt>
7360 appended to the package name, and one linked dynamically
7361 against Motif and with <tt>-dmotif</tt> appended to the
7362 package name. Both Motif-linked versions are dependent
7363 upon non-DFSG-compliant software and thus cannot be
7364 uploaded to the <em>main</em> distribution; if the
7365 software is itself DFSG-compliant it may be uploaded to
7366 the <em>contrib</em> distribution. While known existing
7367 versions of Motif permit unlimited redistribution of
7368 binaries linked against the library (whether statically or
7369 dynamically), it is the package maintainer's
7370 responsibility to determine whether this is permitted by
7371 the license of the copy of Motif in his or her possession.
7377 <heading>Perl programs and modules</heading>
7379 Perl programs and modules should follow the current Perl
7380 policy as defined in the file found on
7381 <ftpsite>ftp.debian.org</ftpsite> in
7382 <ftppath>/debian/doc/package-developer/perl-policy.txt.gz</ftppath>
7383 or your local mirror. In addition, it is included in the
7384 <tt>debian-policy</tt> package.
7389 <heading>Emacs lisp programs</heading>
7392 Please refer to the `Debian Emacs Policy' (documented in
7393 <file>debian-emacs-policy.gz</file> of the
7394 <prgn>emacsen-common</prgn> package) for details of how to
7395 package emacs lisp programs.
7400 <heading>Games</heading>
7403 The permissions on <file>/var/games</file> are mode 755, owner
7404 <tt>root</tt> and group <tt>root</tt>.
7408 Each game decides on its own security policy.</p>
7411 Games which require protected, privileged access to
7412 high-score files, savegames, etc., may be made
7413 set-<em>group</em>-id (mode 2755) and owned by
7414 <tt>root.games</tt>, and use files and directories with
7415 appropriate permissions (770 <tt>root.games</tt>, for
7416 example). They must not be made
7417 set-<em>user</em>-id, as this causes security problems. (If
7418 an attacker can subvert any set-user-id game they can
7419 overwrite the executable of any other, causing other players
7420 of these games to run a Trojan horse program. With a
7421 set-group-id game the attacker only gets access to less
7422 important game data, and if they can get at the other
7423 players' accounts at all it will take considerably more
7427 Some packages, for example some fortune cookie programs, are
7428 configured by the upstream authors to install with their
7429 data files or other static information made unreadable so
7430 that they can only be accessed through set-id programs
7431 provided. You should not do this in a Debian package: anyone can
7432 download the <file>.deb</file> file and read the data from it,
7433 so there is no point making the files unreadable. Not
7434 making the files unreadable also means that you don't have
7435 to make so many programs set-id, which reduces the risk of a
7439 As described in the FHS, binaries of games should be
7440 installed in the directory <file>/usr/games</file>. This also
7441 applies to games that use the X Window System. Manual pages
7442 for games (X and non-X games) should be installed in
7443 <file>/usr/share/man/man6</file>.</p>
7447 <chapt id="docs"><heading>Documentation</heading>
7451 <heading>Manual pages</heading>
7454 You should install manual pages in <prgn>nroff</prgn> source
7455 form, in appropriate places under <file>/usr/share/man</file>. You
7456 should only use sections 1 to 9 (see the FHS for more
7457 details). You must not install a preformatted `cat
7461 Each program, utility, and function should have an
7462 associated manpage included in the same package. It is
7463 suggested that all configuration files also have a manual
7464 page included as well.
7468 If no manual page is available for a particular program,
7469 utility, function or configuration file and this is reported
7470 as a bug to the Debian Bug Tracking System, a symbolic link
7471 from the requested manual page to the <manref
7472 name="undocumented" section="7"> manual page may be
7473 provided. This symbolic link can be created from
7474 <file>debian/rules</file> like this:
7475 <example compact="compact">
7476 ln -s ../man7/undocumented.7.gz \
7477 debian/tmp/usr/share/man/man[1-9]/<var>requested_manpage</var>.[1-9].gz
7479 This manpage claims that the lack of a manpage has been
7480 reported as a bug, so you may only do this if it really has
7481 (you can report it yourself, if you like). Do not close the
7482 bug report until a proper manpage is available.</p>
7485 You may forward a complaint about a missing manpage to the
7486 upstream authors, and mark the bug as forwarded in the
7487 Debian bug tracking system. Even though the GNU Project do
7488 not in general consider the lack of a manpage to be a bug,
7489 we do; if they tell you that they don't consider it a bug
7490 you should leave the bug in our bug tracking system open
7494 Manual pages should be installed compressed using <tt>gzip
7498 If one manpage needs to be accessible via several names it
7499 is better to use a symbolic link than the <file>.so</file>
7500 feature, but there is no need to fiddle with the relevant
7501 parts of the upstream source to change from <file>.so</file> to
7502 symlinks: don't do it unless it's easy. You should not
7503 create hard links in the manual page directories, nor put
7504 absolute filenames in <file>.so</file> directives. The filename
7505 in a <file>.so</file> in a manpage should be relative to the
7506 base of the manpage tree (usually
7507 <file>/usr/share/man</file>). If you do not create any links
7508 (whether symlinks, hard links, or <tt>.so</tt> directives)
7509 in the filesystem to the alternate names of the manpage,
7510 then you should not rely on <prgn>man</prgn> finding your
7511 manpage under those names based solely on the information in
7512 the manpage's header.<footnote>
7514 Supporting this in <prgn>man</prgn> often requires
7515 unreasonable processing time to find a manual page or to
7516 report that none exists, and moves knowledge into man's
7517 database that would be better left in the filesystem.
7518 This support is therefore deprecated and will cease to
7519 be present in the future.
7526 <heading>Info documents</heading>
7529 Info documents should be installed in <file>/usr/share/info</file>.
7530 They should be compressed with <tt>gzip -9</tt>.</p>
7533 Your package should call <prgn>install-info</prgn> to update
7534 the Info <file>dir</file> file in its <prgn>postinst</prgn>
7535 script when called with a <tt>configure</tt> argument, for
7537 <example compact="compact">
7538 install-info --quiet --section Development Development \
7539 /usr/share/info/foobar.info
7543 It is a good idea to specify a section for the location of
7544 your program; this is done with the <tt>--section</tt>
7545 switch. To determine which section to use, you should look
7546 at <file>/usr/share/info/dir</file> on your system and choose the most
7547 relevant (or create a new section if none of the current
7548 sections are relevant). Note that the <tt>--section</tt>
7549 flag takes two arguments; the first is a regular expression
7550 to match (case-insensitively) against an existing section,
7551 the second is used when creating a new one.</p>
7554 You should remove the entries in the <prgn>prerm</prgn>
7555 script when called with a <tt>remove</tt> argument:
7556 <example compact="compact">
7557 install-info --quiet --remove /usr/share/info/foobar.info
7561 If <prgn>install-info</prgn> cannot find a description entry
7562 in the Info file you must supply one. See <manref
7563 name="install-info" section="8"> for details.</p>
7567 <heading>Additional documentation</heading>
7570 Any additional documentation that comes with the package may
7571 be installed at the discretion of the package maintainer.
7572 Text documentation should be installed in the directory
7573 <file>/usr/share/doc/<var>package</var></file>, where
7574 <var>package</var> is the name of the package, and
7575 compressed with <tt>gzip -9</tt> unless it is small.</p>
7578 If a package comes with large amounts of documentation which
7579 many users of the package will not require you should create
7580 a separate binary package to contain it, so that it does not
7581 take up disk space on the machines of users who do not need
7582 or want it installed.</p>
7585 It is often a good idea to put text information files
7586 (<file>README</file>s, changelogs, and so forth) that come with
7587 the source package in <file>/usr/share/doc/<var>package</var></file>
7588 in the binary package. However, you don't need to install
7589 the instructions for building and installing the package, of
7593 Files in <file>/usr/share/doc</file> should not be referenced by
7594 any program, and the system administrator should be able to
7595 delete them without causing any programs to break. Any files
7596 that are referenced by programs but are also useful as
7597 standalone documentation should be installed under
7598 <file>/usr/share/<var>package</var>/</file> with symbolic links
7599 from <file>/usr/share/doc/<var>package</var>/</file>.
7603 <file>/usr/share/doc/<var>package</var></file> may be a symbolic
7604 link to another directory in <file>/usr/share/doc</file> only if
7605 the two packages both come from the same source and the
7606 first package Depends on the second.
7610 Former Debian releases placed all additional documentation
7611 in <file>/usr/doc/<var>package</var></file>. This has been
7612 changed to <file>/usr/share/doc/<var>package</var></file>,
7613 and packages must not put documentation in the directory
7614 <file>/usr/doc/<var>package</var></file>. <footnote>
7615 <p>At this phase of the transition, we no longer require a
7616 symbolic link in <file>/usr/doc/</file>. At a later point,
7617 policy shall change to make the symbolic links a bug.</p>
7623 <heading>Preferred documentation formats</heading>
7626 The unification of Debian documentation is being carried out
7630 If your package comes with extensive documentation in a
7631 markup format that can be converted to various other formats
7632 you should if possible ship HTML versions in a binary
7633 package, in the directory
7634 <file>/usr/share/doc/<var>appropriate-package</var></file> or
7635 its subdirectories.<footnote>
7637 The rationale: The important thing here is that HTML
7638 docs should be available in <em>some</em> package, not
7639 necessarily in the main binary package.
7645 Other formats such as PostScript may be provided at the
7646 package maintainer's discretion.
7650 <sect id="copyrightfile">
7651 <heading>Copyright information</heading>
7654 Every package must be accompanied by a verbatim copy of its
7655 copyright and distribution license in the file
7656 <file>/usr/share/doc/<var>package</var>/copyright</file>. This
7657 file must neither be compressed nor be a symbolic link.
7661 In addition, the copyright file must say where the upstream
7662 sources (if any) were obtained. It should name the original
7663 authors of the package and the Debian maintainer(s) who were
7664 involved with its creation.</p>
7667 A copy of the file which will be installed in
7668 <file>/usr/share/doc/<var>package</var>/copyright</file> should
7669 be in <file>debian/copyright</file> in the source package.
7673 <file>/usr/share/doc/<var>package</var></file> may be a symbolic
7674 link to another directory in <file>/usr/share/doc</file> only if
7675 the two packages both come from the same source and the
7676 first package Depends on the second. These rules are
7677 important because copyrights must be extractable by
7682 Packages distributed under the UCB BSD license, the Artistic
7683 license, the GNU GPL, and the GNU LGPL should refer to the
7684 files <file>/usr/share/common-licenses/BSD</file>,
7685 <file>/usr/share/common-licenses/Artistic</file>,
7686 <file>/usr/share/common-licenses/GPL</file>, and
7687 <file>/usr/share/common-licenses/LGPL</file> respectively,
7688 rather than quoting them in the copyright file.
7692 You should not use the copyright file as a general <file>README</file>
7693 file. If your package has such a file it should be
7694 installed in <file>/usr/share/doc/<var>package</var>/README</file> or
7695 <file>README.Debian</file> or some other appropriate place.</p>
7699 <heading>Examples</heading>
7702 Any examples (configurations, source files, whatever),
7703 should be installed in a directory
7704 <file>/usr/share/doc/<var>package</var>/examples</file>. These
7705 files should not be referenced by any program: they're there
7706 for the benefit of the system administrator and users as
7707 documentation only. Architecture-specific example files
7708 should be installed in a directory
7709 <file>/usr/lib/<var>package</var>/examples</file> with symbolic
7711 <file>/usr/share/doc/<var>package</var>/examples</file>, or the
7712 latter directory itself may be a symbolic link to the
7717 <sect id="changelogs">
7718 <heading>Changelog files</heading>
7721 The Debian changelog file (<file>debian/changelog</file>) should
7722 explain briefly what modifications were made in the Debian version
7723 of the package compared to the upstream one. Other changes and
7724 updates to the package should also be documented in this file.
7728 Mistakes in changelogs are usually best rectified by
7729 making a new changelog entry rather than "rewriting history"
7730 by editing old changelog entries.
7734 The format of the <file>debian/changelog</file> file is described
7735 in <ref id="dpkgchangelog">. In non-experimental packages you must
7736 use a format for <file>debian/changelog</file> which is supported
7737 by the most recent released version of <prgn>dpkg</prgn>.<footnote>
7739 If you wish to use an alternative format, you may do so as long
7740 as you include a parser for it in your source package. The
7741 parser must have an API compatible with that expected by
7742 <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-gencontrol</prgn>.
7743 If there is general interest in the new format, you should
7744 contact the <package>dpkg</package> maintainer to have the
7745 parser script for it included in the <prgn>dpkg</prgn> package.
7746 (You will need to agree that the parser and its manpage may be
7747 distributed under the GNU GPL, just as the rest of `dpkg' is.)
7753 Packages that are not Debian-native must contain a
7754 compressed copy of the <file>debian/changelog</file> file from
7755 the Debian source tree in
7756 <file>/usr/share/doc/<var>package</var></file> with the name
7757 <file>changelog.Debian.gz</file>.
7761 If an upstream changelog is available, it should be accessible as
7762 <file>/usr/share/doc/<var>package</var>/changelog.gz</file> in
7763 plain text. If the upstream changelog is distributed in
7764 HTML, it should be made available in that form as
7765 <file>/usr/share/doc/<var>package</var>/changelog.html.gz</file>
7766 and a plain text <file>changelog.gz</file> should be generated
7767 from it using, for example, <tt>lynx -dump -nolist</tt>. If
7768 the upstream changelog files do not already conform to this
7769 naming convention, then this may be achieved either by
7770 renaming the files, or by adding a symbolic link, at the
7771 maintainer's discretion.<footnote>
7773 Rationale: People should not have to look in places for
7774 upstream changelogs merely because they are given
7775 different names or are distributed in HTML format.
7781 All of these files should be installed compressed using
7782 <tt>gzip -9</tt>, as they will become large with time even
7783 if they start out small.
7787 If the package has only one changelog which is used both as
7788 the Debian changelog and the upstream one because there is
7789 no separate upstream maintainer then that changelog should
7790 usually be installed as
7791 <file>/usr/share/doc/<var>package</var>/changelog.gz</file>; if
7792 there is a separate upstream maintainer, but no upstream
7793 changelog, then the Debian changelog should still be called
7794 <file>changelog.Debian.gz</file>.</p>
7799 <appendix id="pkg-scope">
7800 <heading>Introduction and scope of these appendices</heading>
7803 These appendices are taken essentially verbatim from the
7804 now-deprecated Packaging Manual, version 3.2.1.0. They are
7805 the chapters which are likely to be of use to package
7806 maintainers and which have not already been included in the
7807 policy document itself. Most of these sections are very likely
7808 not relevant to policy; they should be treated as
7809 documentation for the packaging system. Please note that these
7810 appendices are included for convenience, and for historical
7811 reasons: they used to be part of policy package, and they have
7812 not yet been incorporated into dpkg documentation. However,
7813 they still have value, and hence they are presented here.
7816 They have not yet been checked to ensure that they are
7817 compatible with the contents of policy, and if there are any
7818 contradictions, the version in the main policy document takes
7819 precedence. The remaining chapters of the old Packaging
7820 Manual have also not been read in detail to ensure that there
7821 are not parts which have been left out. Both of these will be
7826 <prgn>dpkg</prgn> is a suite of programs for creating binary
7827 package files and installing and removing them on Unix
7830 <prgn>dpkg</prgn> is targetted primarily at Debian
7831 GNU/Linux, but may work on or be ported to other
7838 The binary packages are designed for the management of
7839 installed executable programs (usually compiled binaries) and
7840 their associated data, though source code examples and
7841 documentation are provided as part of some packages.</p>
7844 This manual describes the technical aspects of creating Debian
7845 binary packages (<file>.deb</file> files). It documents the
7846 behaviour of the package management programs
7847 <prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and the way
7848 they interact with packages.</p>
7851 It also documents the interaction between
7852 <prgn>dselect</prgn>'s core and the access method scripts it
7853 uses to actually install the selected packages, and describes
7854 how to create a new access method.</p>
7857 This manual does not go into detail about the options and
7858 usage of the package building and installation tools. It
7859 should therefore be read in conjuction with those programs'
7864 The utility programs which are provided with <prgn>dpkg</prgn>
7865 for managing various system configuration and similar issues,
7866 such as <prgn>update-rc.d</prgn> and
7867 <prgn>install-info</prgn>, are not described in detail here -
7868 please see their manpages.
7872 It does <em>not</em> describe the policy requirements imposed
7873 on Debian packages, such as the permissions on files and
7874 directories, documentation requirements, upload procedure, and
7875 so on. You should see the Debian packaging policy manual for
7876 these details. (Many of them will probably turn out to be
7877 helpful even if you don't plan to upload your package and make
7878 it available as part of the distribution.)
7882 It is assumed that the reader is reasonably familiar with the
7883 <prgn>dpkg</prgn> System Administrators' manual.
7884 Unfortunately this manual does not yet exist.
7888 The Debian version of the FSF's GNU hello program is provided
7889 as an example for people wishing to create Debian
7890 packages. The Debian <prgn>debmake</prgn> package is
7891 recommended as a very helpful tool in creating and maintaining
7892 Debian packages. However, while the tools and examples are
7893 helpful, they do not replace the need to read and follow the
7894 Policy and Programmer's Manual.</p>
7897 <appendix id="pkg-binarypkg"><heading>Binary packages (from old
7902 The binary package has two main sections. The first part
7903 consists of various control information files and scripts used
7904 by <prgn>dpkg</prgn> when installing and removing. See <ref
7905 id="pkg-controlarea">.
7909 The second part is an archive containing the files and
7910 directories to be installed.
7914 In the future binary packages may also contain other
7915 components, such as checksums and digital signatures. The
7916 format for the archive is described in full in the
7917 <file>deb(5)</file> manpage.
7921 <sect id="pkg-bincreating"><heading>Creating package files -
7922 <prgn>dpkg-deb</prgn>
7926 All manipulation of binary package files is done by
7927 <prgn>dpkg-deb</prgn>; it's the only program that has
7928 knowledge of the format. (<prgn>dpkg-deb</prgn> may be
7929 invoked by calling <prgn>dpkg</prgn>, as <prgn>dpkg</prgn>
7930 will spot that the options requested are appropriate to
7931 <prgn>dpkg-deb</prgn> and invoke that instead with the same
7936 In order to create a binary package you must make a
7937 directory tree which contains all the files and directories
7938 you want to have in the filesystem data part of the package.
7939 In Debian-format source packages this directory is usually
7940 <file>debian/tmp</file>, relative to the top of the package's
7945 They should have the locations (relative to the root of the
7946 directory tree you're constructing) ownerships and
7947 permissions which you want them to have on the system when
7952 With current versions of <prgn>dpkg</prgn> the uid/username
7953 and gid/groupname mappings for the users and groups being
7954 used should be the same on the system where the package is
7955 built and the one where it is installed.
7959 You need to add one special directory to the root of the
7960 miniature filesystem tree you're creating:
7961 <prgn>DEBIAN</prgn>. It should contain the control
7962 information files, notably the binary package control file
7963 (see <ref id="pkg-controlfile">).
7967 The <prgn>DEBIAN</prgn> directory will not appear in the
7968 filesystem archive of the package, and so won't be installed
7969 by <prgn>dpkg</prgn> when the package is installed.
7973 When you've prepared the package, you should invoke:
7975 dpkg --build <var>directory</var>
7980 This will build the package in
7981 <file><var>directory</var>.deb</file>. (<prgn>dpkg</prgn> knows
7982 that <tt>--build</tt> is a <prgn>dpkg-deb</prgn> option, so
7983 it invokes <prgn>dpkg-deb</prgn> with the same arguments to
7988 See the manpage <manref name="dpkg-deb" section="8"> for details of how
7989 to examine the contents of this newly-created file. You may find the
7990 output of following commands enlightening:
7992 dpkg-deb --info <var>filename</var>.deb
7993 dpkg-deb --contents <var>filename</var>.deb
7994 dpkg --contents <var>filename</var>.deb
7996 To view the copyright file for a package you could use this command:
7998 dpkg --fsys-tarfile <var>filename</var>.deb | tar xof usr/share/doc/<var>\*</var>copyright | less
8003 <sect id="pkg-controlarea">
8005 Package control information files
8009 The control information portion of a binary package is a
8010 collection of files with names known to <prgn>dpkg</prgn>.
8011 It will treat the contents of these files specially - some
8012 of them contain information used by <prgn>dpkg</prgn> when
8013 installing or removing the package; others are scripts which
8014 the package maintainer wants <prgn>dpkg</prgn> to run.
8018 It is possible to put other files in the package control
8019 area, but this is not generally a good idea (though they
8020 will largely be ignored).
8024 Here is a brief list of the control info files supported by
8025 <prgn>dpkg</prgn> and a summary of what they're used for.
8030 <tag><tt>control</tt>
8034 This is the key description file used by
8035 <prgn>dpkg</prgn>. It specifies the package's name
8036 and version, gives its description for the user,
8037 states its relationships with other packages, and so
8038 forth. See <ref id="pkg-controlfile">.
8042 It is usually generated automatically from information
8043 in the source package by the
8044 <prgn>dpkg-gencontrol</prgn> program, and with
8045 assistance from <prgn>dpkg-shlibdeps</prgn>. See <ref
8046 id="pkg-sourcetools">.</p>
8049 <tag><tt>postinst</tt>, <tt>preinst</tt>, <tt>postrm</tt>,
8055 These are exectuable files (usually scripts) which
8056 <prgn>dpkg</prgn> runs during installation, upgrade
8057 and removal of packages. They allow the package to
8058 deal with matters which are particular to that package
8059 or require more complicated processing than that
8060 provided by <prgn>dpkg</prgn>. Details of when and
8061 how they are called are in <ref
8062 id="maintainerscripts">.
8066 It is very important to make these scripts
8070 That means that if it runs successfully or fails
8071 and then you call it again it doesn't bomb out,
8072 but just ensures that everything is the way it
8075 </footnote> This is so that if an error occurs, the
8076 user interrupts <prgn>dpkg</prgn> or some other
8077 unforeseen circumstance happens you don't leave the
8078 user with a badly-broken package.
8082 The maintainer scripts are guaranteed to run with a
8083 controlling terminal and can interact with the user.
8084 If they need to prompt for passwords, do full-screen
8085 interaction or something similar you should do these
8086 things to and from <file>/dev/tty</file>, since
8087 <prgn>dpkg</prgn> will at some point redirect scripts'
8088 standard input and output so that it can log the
8089 installation process. Likewise, because these scripts
8090 may be executed with standard output redirected into a
8091 pipe for logging purposes, Perl scripts should set
8092 unbuffered output by setting <tt>$|=1</tt> so that the
8093 output is printed immediately rather than being
8098 Each script should return a zero exit status for
8099 success, or a nonzero one for failure.</p>
8102 <tag><tt>conffiles</tt>
8107 This file contains a list of configuration files which
8108 are to be handled automatically by <prgn>dpkg</prgn>
8109 (see <ref id="pkg-conffiles">). Note that not necessarily
8110 every configuration file should be listed here.</p>
8113 <tag><tt>shlibs</tt>
8118 This file contains a list of the shared libraries
8119 supplied by the package, with dependency details for
8120 each. This is used by <prgn>dpkg-shlibdeps</prgn>
8121 when it determines what dependencies are required in a
8122 package control file. The <tt>shlibs</tt> file format
8123 is described on <ref id="shlibs">.
8129 <sect id="pkg-controlfile">
8131 The main control information file: <tt>control</tt>
8134 The most important control information file used by
8135 <prgn>dpkg</prgn> when it installs a package is
8136 <tt>control</tt>. It contains all the package's `vital
8141 The binary package control files of packages built from
8142 Debian sources are made by a special tool,
8143 <prgn>dpkg-gencontrol</prgn>, which reads
8144 <file>debian/control</file> and <file>debian/changelog</file> to
8145 find the information it needs. See <ref id="pkg-sourcepkg"> for
8150 The fields in binary package control files are:
8151 <list compact="compact">
8153 <p><qref id="pkg-f-Package"><tt>Package</tt></qref> (mandatory)</p>
8156 <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
8158 <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.
8170 <p><qref id="relationships"><tt>Depends</tt>,
8171 <tt>Provides</tt> et al.</qref></p>
8174 <p><qref id="pkg-f-Essential"><tt>Essential</tt></qref></p>
8177 <p><qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref></p>
8180 <p><qref id="pkg-f-classification"><tt>Section</tt>,
8181 <tt>Priority</tt></qref></p>
8184 <p><qref id="pkg-f-Source"><tt>Source</tt></qref></p>
8187 <p><qref id="descriptions"><tt>Description</tt></qref></p>
8191 <qref id="pkg-f-Installed-Size"><tt>Installed-Size</tt></qref>
8197 A description of the syntax of control files and the purpose
8198 of these fields is available in <ref id="pkg-controlfields">.
8203 <heading>Time Stamps</heading>
8205 Maintainers are encouraged to preserve the modification
8206 times of the upstream source files in a package, as far as
8207 is reasonably possible.
8210 The rationale is that there is some information conveyed
8211 by knowing the age of the file, for example, you could
8212 recognize that some documentation is very old by looking
8213 at the modification time, so it would be nice if the
8214 modification time of the upstream source would be
8222 <appendix id="pkg-sourcepkg">
8223 <heading>Source packages (from old Packaging Manual) </heading>
8226 The Debian binary packages in the distribution are generated
8227 from Debian sources, which are in a special format to assist
8228 the easy and automatic building of binaries.
8232 There was a previous version of the Debian source format,
8233 which is now being phased out. Instructions for converting an
8234 old-style package are given in the Debian policy manual.
8237 <sect id="pkg-sourcetools">
8238 <heading>Tools for processing source packages</heading>
8241 Various tools are provided for manipulating source packages;
8242 they pack and unpack sources and help build of binary
8243 packages and help manage the distribution of new versions.
8247 They are introduced and typical uses described here; see
8248 <manref name="dpkg-source" section="1"> for full
8249 documentation about their arguments and operation.
8253 For examples of how to construct a Debian source package,
8254 and how to use those utilities that are used by Debian
8255 source packages, please see the <prgn>hello</prgn> example
8261 <prgn>dpkg-source</prgn> - packs and unpacks Debian source
8266 This program is frequently used by hand, and is also
8267 called from package-independent automated building scripts
8268 such as <prgn>dpkg-buildpackage</prgn>.
8272 To unpack a package it is typically invoked with
8274 dpkg-source -x <var>.../path/to/filename</var>.dsc
8279 with the <file><var>filename</var>.tar.gz</file> and
8280 <file><var>filename</var>.diff.gz</file> (if applicable) in
8281 the same directory. It unpacks into
8282 <file><var>package</var>-<var>version</var></file>, and if
8284 <file><var>package</var>-<var>version</var>.orig</file>, in
8285 the current directory.
8289 To create a packed source archive it is typically invoked:
8291 dpkg-source -b <var>package</var>-<var>version</var>
8296 This will create the <file>.dsc</file>, <file>.tar.gz</file> and
8297 <file>.diff.gz</file> (if appropriate) in the current
8298 directory. <prgn>dpkg-source</prgn> does not clean the
8299 source tree first - this must be done separately if it is
8304 See also <ref id="pkg-sourcearchives">.</p>
8310 <prgn>dpkg-buildpackage</prgn> - overall package-building
8315 <prgn>dpkg-buildpackage</prgn> is a script which invokes
8316 <prgn>dpkg-source</prgn>, the <file>debian/rules</file>
8317 targets <tt>clean</tt>, <tt>build</tt> and
8318 <tt>binary</tt>, <prgn>dpkg-genchanges</prgn> and
8319 <prgn>pgp</prgn> to build a signed source and binary
8324 It is usually invoked by hand from the top level of the
8325 built or unbuilt source directory. It may be invoked with
8326 no arguments; useful arguments include:
8327 <taglist compact="compact">
8328 <tag><tt>-uc</tt>, <tt>-us</tt></tag>
8331 Do not PGP-sign the <tt>.changes</tt> file or the
8332 source package <tt>.dsc</tt> file, respectively.</p>
8334 <tag><tt>-p<var>pgp-command</var></tt></tag>
8337 Invoke <var>pgp-command</var> instead of finding
8338 <tt>pgp</tt> on the <prgn>PATH</prgn>.
8339 <var>pgp-command</var> must behave just like
8340 <prgn>pgp</prgn>.</p>
8342 <tag><tt>-r<var>root-command</var></tt></tag>
8345 When root privilege is required, invoke the command
8346 <var>root-command</var>. <var>root-command</var>
8347 should invoke its first argument as a command, from
8348 the <prgn>PATH</prgn> if necessary, and pass its
8349 second and subsequent arguments to the command it
8350 calls. If no <var>root-command</var> is supplied
8351 then <var>dpkg-buildpackage</var> will take no
8352 special action to gain root privilege, so that for
8353 most packages it will have to be invoked as root to
8356 <tag><tt>-b</tt>, <tt>-B</tt></tag>
8359 Two types of binary-only build and upload - see
8360 <manref name="dpkg-source" section="1">.
8369 <prgn>dpkg-gencontrol</prgn> - generates binary package
8374 This program is usually called from <file>debian/rules</file>
8375 (see <ref id="pkg-sourcetree">) in the top level of the source
8380 This is usually done just before the files and directories in the
8381 temporary directory tree where the package is being built have their
8382 permissions and ownerships set and the package is constructed using
8383 <prgn>dpkg-deb/</prgn>
8386 This is so that the control file which is produced has
8387 the right permissions
8393 <prgn>dpkg-gencontrol</prgn> must be called after all the
8394 files which are to go into the package have been placed in
8395 the temporary build directory, so that its calculation of
8396 the installed size of a package is correct.
8400 It is also necessary for <prgn>dpkg-gencontrol</prgn> to
8401 be run after <prgn>dpkg-shlibdeps</prgn> so that the
8402 variable substitutions created by
8403 <prgn>dpkg-shlibdeps</prgn> in <file>debian/substvars</file>
8408 For a package which generates only one binary package, and
8409 which builds it in <file>debian/tmp</file> relative to the top
8410 of the source package, it is usually sufficient to call
8411 <prgn>dpkg-gencontrol</prgn>.
8415 Sources which build several binaries will typically need
8418 dpkg-gencontrol -Pdebian/tmp-<var>pkg</var> -p<var>package</var>
8419 </example> The <tt>-P</tt> tells
8420 <prgn>dpkg-gencontrol</prgn> that the package is being
8421 built in a non-default directory, and the <tt>-p</tt>
8422 tells it which package's control file should be generated.
8426 <prgn>dpkg-gencontrol</prgn> also adds information to the
8427 list of files in <file>debian/files</file>, for the benefit of
8428 (for example) a future invocation of
8429 <prgn>dpkg-genchanges</prgn>.</p>
8434 <prgn>dpkg-shlibdeps</prgn> - calculates shared library
8439 This program is usually called from <file>debian/rules</file>
8440 just before <prgn>dpkg-gencontrol</prgn> (see <ref
8441 id="pkg-sourcetree">), in the top level of the source tree.
8445 Its arguments are executables.
8448 In a forthcoming dpkg version,
8449 <prgn>dpkg-shlibdeps</prgn> would be required to be
8450 called on shared libraries as well.
8453 They may be specified either in the locations in the
8454 source tree where they are created or in the locations
8455 in the temporary build tree where they are installed
8456 prior to binary package creation.
8458 </footnote> for which shared library dependencies should
8459 be included in the binary package's control file.
8463 If some of the found shared libraries should only
8464 warrant a <tt>Recommends</tt> or <tt>Suggests</tt>, or if
8465 some warrant a <tt>Pre-Depends</tt>, this can be achieved
8466 by using the <tt>-d<var>dependency-field</var></tt> option
8467 before those executable(s). (Each <tt>-d</tt> option
8468 takes effect until the next <tt>-d</tt>.)
8472 <prgn>dpkg-shlibdeps</prgn> does not directly cause the
8473 output control file to be modified. Instead by default it
8474 adds to the <file>debian/substvars</file> file variable
8475 settings like <tt>shlibs:Depends</tt>. These variable
8476 settings must be referenced in dependency fields in the
8477 appropriate per-binary-package sections of the source
8482 For example, the <prgn>procps</prgn> package generates two
8483 kinds of binaries, simple C binaries like <prgn>ps</prgn>
8484 which require a predependency and full-screen ncurses
8485 binaries like <prgn>top</prgn> which require only a
8486 recommendation. It can say in its <file>debian/rules</file>:
8488 dpkg-shlibdeps -dPre-Depends ps -dRecommends top
8490 and then in its main control file <file>debian/control</file>:
8494 Pre-Depends: ${shlibs:Pre-Depends}
8495 Recommends: ${shlibs:Recommends}
8501 Sources which produce several binary packages with
8502 different shared library dependency requirements can use
8503 the <tt>-p<var>varnameprefix</var></tt> option to override
8504 the default <tt>shlibs:</tt> prefix (one invocation of
8505 <prgn>dpkg-shlibdeps</prgn> per setting of this option).
8506 They can thus produce several sets of dependency
8507 variables, each of the form
8508 <tt><var>varnameprefix</var>:<var>dependencyfield</var></tt>,
8509 which can be referred to in the appropriate parts of the
8510 binary package control files.
8517 <prgn>dpkg-distaddfile</prgn> - adds a file to
8518 <file>debian/files</file>
8522 Some packages' uploads need to include files other than
8523 the source and binary package files.
8527 <prgn>dpkg-distaddfile</prgn> adds a file to the
8528 <file>debian/files</file> file so that it will be included in
8529 the <file>.changes</file> file when
8530 <prgn>dpkg-genchanges</prgn> is run.
8534 It is usually invoked from the <tt>binary</tt> target of
8535 <file>debian/rules</file>:
8537 dpkg-distaddfile <var>filename</var> <var>section</var> <var>priority</var>
8539 The <var>filename</var> is relative to the directory where
8540 <prgn>dpkg-genchanges</prgn> will expect to find it - this
8541 is usually the directory above the top level of the source
8542 tree. The <file>debian/rules</file> target should put the
8543 file there just before or just after calling
8544 <prgn>dpkg-distaddfile</prgn>.
8548 The <var>section</var> and <var>priority</var> are passed
8549 unchanged into the resulting <file>.changes</file> file. See
8550 <ref id="pkg-f-classification">.
8555 <sect1><heading><prgn>dpkg-genchanges</prgn> - generates a <file>.changes</file> upload
8560 This program is usually called by package-independent
8561 automatic building scripts such as
8562 <prgn>dpkg-buildpackage</prgn>, but it may also be called
8567 It is usually called in the top level of a built source
8568 tree, and when invoked with no arguments will print out a
8569 straightforward <file>.changes</file> file based on the
8570 information in the source package's changelog and control
8571 file and the binary and source packages which should have
8577 <sect1><heading><prgn>dpkg-parsechangelog</prgn> - produces parsed representation of
8582 This program is used internally by
8583 <prgn>dpkg-source</prgn> et al. It may also occasionally
8584 be useful in <file>debian/rules</file> and elsewhere. It
8585 parses a changelog, <file>debian/changelog</file> by default,
8586 and prints a control-file format representation of the
8587 information in it to standard output.
8591 <sect1 id="pkg-dpkgarch"><heading><prgn>dpkg-architecture</prgn> -
8592 information about the build and host system
8596 This program can be used manually, but is also invoked by
8597 <tt>dpkg-buildpackage</tt> or <file>debian/rules</file> to set
8598 to set environment or make variables which specify the build and
8599 host architecture for the package building process.
8604 <sect id="pkg-sourcetree"><heading>The Debianised source tree
8608 The source archive scheme described later is intended to
8609 allow a Debianised source tree with some associated control
8610 information to be reproduced and transported easily. The
8611 Debianised source tree is a version of the original program
8612 with certain files added for the benefit of the
8613 Debianisation process, and with any other changes required
8614 made to the rest of the source code and installation
8619 The extra files created for Debian are in the subdirectory
8620 <file>debian</file> of the top level of the Debianised source
8621 tree. They are described below.
8624 <sect1 id="pkg-debianrules"><heading><file>debian/rules</file> - the main building
8629 This file is an executable makefile, and contains the
8630 package-specific recipies for compiling the package and
8631 building binary package(s) out of the source.
8635 It must start with the line <tt>#!/usr/bin/make -f</tt>,
8636 so that it can be invoked by saying its name rather than
8637 invoking <prgn>make</prgn> explicitly.
8641 Since an interactive <file>debian/rules</file> script makes it
8642 impossible to autocompile that package and also makes it
8643 hard for other people to reproduce the same binary
8644 package, all <strong>required targets</strong> have to be
8645 non-interactive. At a minimul, required targets are the
8646 ones called by <prgn>dpkg-buildpackage</prgn>, namely,
8647 <em>clean</em>, <em>binary</em>, <em>binary-arch</em>, and
8648 <em>build</em>. It also follows that any target that these
8649 targets depend on must also be non-interactive.
8653 The targets which are required to be present are:
8655 <tag><tt>build</tt></tag>
8658 This should perform all non-interactive
8659 configuration and compilation of the package. If a
8660 package has an interactive pre-build configuration
8661 routine, the Debianised source package should be
8662 built after this has taken place, so that it can be
8663 built without rerunning the configuration.
8667 A package may also provide both of the targets
8668 <tt>build-arch</tt> and <tt>build-indep</tt>. The
8669 <tt>build-arch</tt> target, if provided, should
8670 perform all non-interactive configuration and
8671 compilation required for producing all
8672 architecture-dependant binary packages (those packages
8673 for which the body of the <tt>Architecture</tt> field
8674 in <tt>debian/control</tt> is not <tt>all</tt>).
8675 Similarly, the <tt>build-indep</tt> target, if
8676 provided, should perform all non-interactive
8677 configuration and compilation required for producing
8678 all architecture-independent binary packages (those
8679 packages for which the body of the
8680 <tt>Architecture</tt> field in <tt>debian/control</tt>
8681 is <tt>all</tt>). The <tt>build</tt> target should
8682 depend on those of the targets <tt>build-arch</tt> and
8683 <tt>build-indep</tt> that are provided in the rules
8688 If one or both of the targets <tt>build-arch</tt> and
8689 <tt>build-indep</tt> are not provided, then invoking
8690 <file>debian/rules</file> with one of the not-provided
8691 targets as arguments should produce a exit status code
8692 of 2. Usually this is provided automatically by make
8693 if the target is missing.
8697 For some packages, notably ones where the same
8698 source tree is compiled in different ways to produce
8699 two binary packages, the <tt>build</tt> target does
8700 not make much sense. For these packages it is good
8701 enough to provide two (or more) targets
8702 (<tt>build-a</tt> and <tt>build-b</tt> or whatever)
8703 for each of the ways of building the package, and a
8704 <tt>build</tt> target that does nothing. The
8705 <tt>binary</tt> target will have to build the
8706 package in each of the possible ways and make the
8707 binary package out of each.
8711 The targets <tt>build</tt>, <tt>build-arch</tt>
8712 and <tt>build-indep</tt> target must not do
8713 anything that might require root privilege.
8717 The <tt>build</tt> target may need to run
8718 <tt>clean</tt> first - see below.
8722 When a package has a configuration routine that takes
8723 a long time, or when the makefiles are poorly
8724 designed, or when <tt>build</tt> needs to run
8725 <tt>clean</tt> first, it is a good idea to <tt>touch
8726 build</tt> when the build process is complete. This
8727 will ensure that if <tt>debian/rules build</tt> is run
8728 again it will not rebuild the whole program.
8732 <tag><tt>binary</tt>, <tt>binary-arch</tt>,
8733 <tt>binary-indep</tt>
8737 The <tt>binary</tt> target should be all that is
8738 necessary for the user to build the binary
8739 package. All these targets are required to be
8740 non-interactive. It is split into two parts:
8741 <tt>binary-arch</tt> builds the packages' output
8742 files which are specific to a particular
8743 architecture, and <tt>binary-indep</tt> builds
8744 those which are not.
8748 <tt>binary</tt> should usually be a target with
8749 no commands which simply depends on
8750 <prgn>binary-arch</prgn> and
8751 <prgn>binary-indep</prgn>.
8755 Both <prgn>binary-*</prgn> targets should depend on
8756 the <tt>build</tt> target, above, so that the
8757 package is built if it has not been already. It
8758 should then create the relevant binary package(s),
8759 using <prgn>dpkg-gencontrol</prgn> to make their
8760 control files and <prgn>dpkg-deb</prgn> to build
8761 them and place them in the parent of the top level
8766 If one of the <prgn>binary-*</prgn> targets has
8767 nothing to do (this will be always be the case if
8768 the source generates only a single binary package,
8769 whether architecture-dependent or not) it
8770 <em>must</em> still exist, but should always
8775 <ref id="pkg-binarypkg"> describes how to construct
8780 The <tt>binary</tt> targets must be invoked as
8785 <tag><tt>clean</tt></tag>
8789 This should undo any effects that the
8790 <tt>build</tt> and <tt>binary</tt> targets
8791 may have had, except that it should leave alone any
8792 output files created in the parent directory by a
8793 run of <tt>binary</tt>. This target is required
8794 to be non-interactive.
8798 If a <tt>build</tt> file is touched at the end
8799 of the <tt>build</tt> target, as suggested
8800 above, it must be removed as the first thing that
8801 <tt>clean</tt> does, so that running
8802 <tt>build</tt> again after an interrupted
8803 <tt>clean</tt> doesn't think that everything is
8808 The <tt>clean</tt> target must be invoked as
8809 root if <tt>binary</tt> has been invoked since
8810 the last <tt>clean</tt>, or if
8811 <tt>build</tt> has been invoked as root (since
8812 <tt>build</tt> may create directories, for
8817 <tag><tt>get-orig-source</tt> (optional)</tag>
8821 This target fetches the most recent version of the
8822 original source package from a canonical archive
8823 site (via FTP or WWW, for example), does any
8824 necessary rearrangement to turn it into the original
8825 source tarfile format described below, and leaves it
8826 in the current directory.
8830 This target may be invoked in any directory, and
8831 should take care to clean up any temporary files it
8836 This target is optional, but providing it if
8837 possible is a good idea.
8843 The <tt>build</tt>, <tt>binary</tt> and
8844 <tt>clean</tt> targets must be invoked with a current
8845 directory of the package's top-level directory.
8850 Additional targets may exist in <file>debian/rules</file>,
8851 either as published or undocumented interfaces or for the
8852 package's internal use.
8856 The architecture we build on and build for is determined by make
8857 variables via dpkg-architecture (see <ref id="pkg-dpkgarch">). You can
8858 get the Debian architecture and the GNU style architecture
8859 specification string for the build machine as well as the host
8860 machine. Here is a list of supported make variables:
8861 <list compact="compact">
8863 <p><tt>DEB_*_ARCH</tt> (the Debian architecture)</p>
8866 <p><tt>DEB_*_GNU_TYPE</tt> (the GNU style architecture
8867 specification string)</p>
8870 <p><tt>DEB_*_GNU_CPU</tt> (the CPU part of DEB_*_GNU_TYPE)</p>
8873 <p><tt>DEB_*_GNU_SYSTEM</tt> (the System part of
8879 where <tt>*</tt> is either <tt>BUILD</tt> for specification of
8880 the build machine or <tt>HOST</tt> for specification of the machine
8885 Backward compatibility can be provided in the rules file
8886 by setting the needed variables to suitable default
8887 values, please refer to the documentation of
8888 dpkg-architecture for details.
8892 It is important to understand that the <tt>DEB_*_ARCH</tt>
8893 string does only determine which Debian architecture we
8894 build on resp. for. It should not be used to get the CPU
8895 or System information, the GNU style variables should be
8901 <sect1><heading><file>debian/control</file>
8905 This file contains version-independent details about the
8906 source package and about the binary packages it creates.
8910 It is a series of sets of control fields, each
8911 syntactically similar to a binary package control file.
8912 The sets are separated by one or more blank lines. The
8913 first set is information about the source package in
8914 general; each subsequent set describes one binary package
8915 that the source tree builds.
8919 The syntax and semantics of the fields are described below
8920 in <ref id="pkg-controlfields">.
8924 The general (binary-package-independent) fields are:
8925 <list compact="compact">
8927 <p><qref id="pkg-f-Source"><tt>Source</tt></qref> (mandatory)</p>
8930 <p><qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref></p>
8934 <qref id="pkg-f-classification"><tt>Section</tt> and
8935 <tt>Priority</tt></qref>
8936 (classification, mandatory)
8941 <qref id="relationships"><tt>Build-Depends</tt> et
8942 al.</qref> (source package interrelationships)
8947 <qref id="pkg-f-Standards-Version"><tt>Standards-Version</tt></qref>
8953 The per-binary-package fields are:
8954 <list compact="compact">
8956 <p><qref id="pkg-f-Package"><tt>Package</tt></qref> (mandatory)</p>
8960 <qref id="pkg-f-Architecture"><tt>Architecture</tt></qref>
8964 <p><qref id="descriptions"><tt>Description</tt></qref></p>
8968 <qref id="pkg-f-classification"><tt>Section</tt> and
8969 <tt>Priority</tt></qref> (classification)</p>
8972 <p><qref id="pkg-f-Essential"><tt>Essential</tt></qref></p>
8976 <qref id="relationships"><tt>Depends</tt> et
8977 al.</qref> (binary package interrelationships)
8983 These fields are used by <prgn>dpkg-gencontrol</prgn> to
8984 generate control files for binary packages (see below), by
8985 <prgn>dpkg-genchanges</prgn> to generate the
8986 <tt>.changes</tt> file to accompany the upload, and by
8987 <prgn>dpkg-source</prgn> when it creates the <file>.dsc</file>
8988 source control file as part of a source archive.
8992 The fields here may contain variable references - their
8993 values will be substituted by
8994 <prgn>dpkg-gencontrol</prgn>, <prgn>dpkg-genchanges</prgn>
8995 or <prgn>dpkg-source</prgn> when they generate output
8996 control files. See <ref id="pkg-srcsubstvars"> for details.
8999 <p> <sect2><heading>User-defined fields
9003 Additional user-defined fields may be added to the
9004 source package control file. Such fields will be
9005 ignored, and not copied to (for example) binary or
9006 source package control files or upload control files.
9010 If you wish to add additional unsupported fields to
9011 these output files you should use the mechanism
9016 Fields in the main source control information file with
9017 names starting <tt>X</tt>, followed by one or more of
9018 the letters <tt>BCS</tt> and a hyphen <tt>-</tt>, will
9019 be copied to the output files. Only the part of the
9020 field name after the hyphen will be used in the output
9021 file. Where the letter <tt>B</tt> is used the field
9022 will appear in binary package control files, where the
9023 letter <tt>S</tt> is used in source package control
9024 files and where <tt>C</tt> is used in upload control
9025 (<tt>.changes</tt>) files.
9029 For example, if the main source information control file
9032 XBS-Comment: I stand between the candle and the star.
9034 then the binary and source package control files will contain the
9037 Comment: I stand between the candle and the star.
9044 <sect1 id="pkg-dpkgchangelog"><heading><file>debian/changelog</file>
9048 This file records the changes to the Debian-specific parts of the
9052 Though there is nothing stopping an author who is also
9053 the Debian maintainer from using it for all their
9054 changes, it will have to be renamed if the Debian and
9055 upstream maintainers become different
9062 It has a special format which allows the package building
9063 tools to discover which version of the package is being
9064 built and find out other release-specific information.
9068 That format is a series of entries like this:
9070 <var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
9072 * <var>change details</var>
9073 <var>more change details</var>
9074 * <var>even more change details</var>
9076 -- <var>maintainer name and email address</var> <var>date</var>
9081 <var>package</var> and <var>version</var> are the source
9082 package name and version number.
9086 <var>distribution(s)</var> lists the distributions where
9087 this version should be installed when it is uploaded - it
9088 is copied to the <tt>Distribution</tt> field in the
9089 <tt>.changes</tt> file. See <ref id="pkg-f-Distribution">.
9093 <var>urgency</var> is the value for the <tt>Urgency</tt>
9094 field in the <file>.changes</file> file for the upload. See
9095 <ref id="pkg-f-Urgency">. It is not possible to specify an
9096 urgency containing commas; commas are used to separate
9097 <tt><var>keyword</var>=<var>value</var></tt> settings in
9098 the <prgn>dpkg</prgn> changelog format (though there is
9099 currently only one useful <var>keyword</var>,
9104 The change details may in fact be any series of lines
9105 starting with at least two spaces, but conventionally each
9106 change starts with an asterisk and a separating space and
9107 continuation lines are indented so as to bring them in
9108 line with the start of the text above. Blank lines may be
9109 used here to separate groups of changes, if desired.
9113 The maintainer name and email address should <em>not</em>
9114 necessarily be those of the usual package maintainer.
9115 They should be the details of the person doing
9116 <em>this</em> version. The information here will be
9117 copied to the <file>.changes</file> file, and then later used
9118 to send an acknowledgement when the upload has been
9123 The <var>date</var> should be in RFC822 format
9126 This is generated by the <prgn>822-date</prgn>
9129 </footnote>; it should include the timezone specified
9130 numerically, with the timezone name or abbreviation
9131 optionally present as a comment.
9135 The first `title' line with the package name should start
9136 at the left hand margin; the `trailer' line with the
9137 maintainer and date details should be preceded by exactly
9138 one space. The maintainer details and the date must be
9139 separated by exactly two spaces.
9143 An Emacs mode for editing this format is available: it is
9144 called <tt>debian-changelog-mode</tt>. You can have this
9145 mode selected automatically when you edit a Debian
9146 changelog by adding a local variables clause to the end of
9150 <sect2><heading>Defining alternative changelog formats
9154 It is possible to use a different format to the standard
9155 one, by providing a parser for the format you wish to
9160 In order to have <tt>dpkg-parsechangelog</tt> run your
9161 parser, you must include a line within the last 40 lines
9162 of your file matching the Perl regular expression:
9163 <tt>\schangelog-format:\s+([0-9a-z]+)\W</tt> The part in
9164 parentheses should be the name of the format. For
9165 example, you might say:
9167 @@@ changelog-format: joebloggs @@@
9169 Changelog format names are non-empty strings of alphanumerics.
9173 If such a line exists then <tt>dpkg-parsechangelog</tt>
9174 will look for the parser as
9175 <file>/usr/lib/dpkg/parsechangelog/<var>format-name</var></file>
9177 <file>/usr/local/lib/dpkg/parsechangelog/<var>format-name</var></file>;
9178 it is an error for it not to find it, or for it not to
9179 be an executable program. The default changelog format
9180 is <tt>dpkg</tt>, and a parser for it is provided with
9181 the <tt>dpkg</tt> package.
9185 The parser will be invoked with the changelog open on
9186 standard input at the start of the file. It should read
9187 the file (it may seek if it wishes) to determine the
9188 information required and return the parsed information
9189 to standard output in the form of a series of control
9190 fields in the standard format. By default it should
9191 return information about only the most recent version in
9192 the changelog; it should accept a
9193 <tt>-v<var>version</var></tt> option to return changes
9194 information from all versions present <em>strictly
9195 after</em> <var>version</var>, and it should then be an
9196 error for <var>version</var> not to be present in the
9202 <list compact="compact">
9204 <p><qref id="pkg-f-Source"><tt>Source</tt></qref></p>
9207 <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
9211 <qref id="pkg-f-Distribution"><tt>Distribution</tt></qref>
9216 <p><qref id="pkg-f-Urgency"><tt>Urgency</tt></qref> (mandatory)</p>
9220 <qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref>
9225 <p><qref id="pkg-f-Date"><tt>Date</tt></qref></p>
9229 <qref id="pkg-f-Changes"><tt>Changes</tt></qref>
9236 If several versions are being returned (due to the use
9237 of <tt>-v</tt>), the urgency value should be of the
9238 highest urgency code listed at the start of any of the
9239 versions requested followed by the concatenated
9240 (space-separated) comments from all the versions
9241 requested; the maintainer, version, distribution and
9242 date should always be from the most recent version.
9246 For the format of the <tt>Changes</tt> field see <ref
9247 id="pkg-f-Changes">.
9251 If the changelog format which is being parsed always or
9252 almost always leaves a blank line between individual
9253 change notes these blank lines should be stripped out,
9254 so as to make the resulting output compact.
9258 If the changelog format does not contain date or package
9259 name information this information should be omitted from
9260 the output. The parser should not attempt to synthesise
9261 it or find it from other sources.
9265 If the changelog does not have the expected format the
9266 parser should exit with a nonzero exit status, rather
9267 than trying to muddle through and possibly generating
9272 A changelog parser may not interact with the user at
9276 <sect1 id="pkg-srcsubstvars"><heading><file>debian/substvars</file>
9277 and variable substitutions
9281 When <prgn>dpkg-gencontrol</prgn>,
9282 <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
9283 generate control files they do variable substitutions on
9284 their output just before writing it. Variable
9285 substitutions have the form
9286 <tt>${<var>variable-name</var>}</tt>. The optional file
9287 <file>debian/substvars</file> contains variable substitutions
9288 to be used; variables can also be set directly from
9289 <file>debian/rules</file> using the <tt>-V</tt> option to the
9290 source packaging commands, and certain predefined
9291 variables are available.
9295 The is usually generated and modified dynamically by
9296 <file>debian/rules</file> targets; in this case it must be
9297 removed by the <tt>clean</tt> target.
9301 See <manref name="dpkg-source" section="1"> for full
9302 details about source variable substitutions, including the
9303 format of <file>debian/substvars</file>.</p>
9306 <sect1><heading><file>debian/files</file>
9310 This file is not a permanent part of the source tree; it
9311 is used while building packages to record which files are
9312 being generated. <prgn>dpkg-genchanges</prgn> uses it
9313 when it generates a <file>.changes</file> file.
9317 It should not exist in a shipped source package, and so it
9318 (and any backup files or temporary files such as
9319 <file>files.new</file>
9322 <file>files.new</file> is used as a temporary file by
9323 <prgn>dpkg-gencontrol</prgn> and
9324 <prgn>dpkg-distaddfile</prgn> - they write a new
9325 version of <file>files</file> here before renaming it,
9326 to avoid leaving a corrupted copy if an error
9329 </footnote>) should be removed by the
9330 <tt>clean</tt> target. It may also be wise to
9331 ensure a fresh start by emptying or removing it at the
9332 start of the <tt>binary</tt> target.
9336 <prgn>dpkg-gencontrol</prgn> adds an entry to this file
9337 for the <file>.deb</file> file that will be created by
9338 <prgn>dpkg-deb</prgn> from the control file that it
9339 generates, so for most packages all that needs to be done
9340 with this file is to delete it in <tt>clean</tt>.
9344 If a package upload includes files besides the source
9345 package and any binary packages whose control files were
9346 made with <prgn>dpkg-gencontrol</prgn> then they should be
9347 placed in the parent of the package's top-level directory
9348 and <prgn>dpkg-distaddfile</prgn> should be called to add
9349 the file to the list in <file>debian/files</file>.</p>
9352 <sect1><heading><file>debian/tmp</file>
9356 This is the canonical temporary location for the
9357 construction of binary packages by the <tt>binary</tt>
9358 target. The directory <file>tmp</file> serves as the root of
9359 the filesystem tree as it is being constructed (for
9360 example, by using the package's upstream makefiles install
9361 targets and redirecting the output there), and it also
9362 contains the <tt>DEBIAN</tt> subdirectory. See <ref
9363 id="pkg-bincreating">.
9367 If several binary packages are generated from the same
9368 source tree it is usual to use several
9369 <file>debian/tmp<var>something</var></file> directories, for
9370 example <file>tmp-a</file> or <file>tmp-doc</file>.
9374 Whatever <file>tmp</file> directories are created and used by
9375 <tt>binary</tt> must of course be removed by the
9376 <tt>clean</tt> target.</p></sect1>
9380 <sect id="pkg-sourcearchives"><heading>Source packages as archives
9384 As it exists on the FTP site, a Debian source package
9385 consists of three related files. You must have the right
9386 versions of all three to be able to use them.
9391 <tag>Debian source control file - <tt>.dsc</tt></tag>
9395 This file contains a series of fields, identified and
9396 separated just like the fields in the control file of
9397 a binary package. The fields are listed below; their
9398 syntax is described above, in <ref id="pkg-controlfields">.
9399 <list compact="compact">
9401 <p><qref id="pkg-f-Source"><tt>Source</tt></qref></p>
9404 <p><qref id="versions"><tt>Version</tt></qref></p>
9407 <p><qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref></p>
9410 <p><qref id="pkg-f-Binary"><tt>Binary</tt></qref></p>
9413 <p><qref id="pkg-f-Architecture"><tt>Architecture</tt></qref></p>
9417 <qref id="relationships"><tt>Build-Depends</tt> et
9418 al.</qref> (source package interrelationships)
9423 <qref id="pkg-f-Standards-Version"><tt>Standards-Version</tt></qref></p>
9426 <p><qref id="pkg-f-Files"><tt>Files</tt></qref></p>
9431 The source package control file is generated by
9432 <prgn>dpkg-source</prgn> when it builds the source
9433 archive, from other files in the source package,
9434 described above. When unpacking it is checked against
9435 the files and directories in the other parts of the
9436 source package, as described below.</p>
9440 Original source archive -
9442 <var>package</var>_<var>upstream-version</var>.orig.tar.gz
9449 This is a compressed (with <tt>gzip -9</tt>)
9450 <prgn>tar</prgn> file containing the source code from
9451 the upstream authors of the program. The tarfile
9452 unpacks into a directory
9453 <file><var>package</var>-<var>upstream-version</var>.orig</file>,
9454 and does not contain files anywhere other than in
9455 there or in its subdirectories.</p>
9459 Debianisation diff -
9461 <var>package</var>_<var>upstream_version-revision</var>.diff.gz
9467 This is a unified context diff (<tt>diff -u</tt>)
9468 giving the changes which are required to turn the
9469 original source into the Debian source. These changes
9470 may only include editing and creating plain files.
9471 The permissions of files, the targets of symbolic
9472 links and the characteristics of special files or
9473 pipes may not be changed and no files may be removed
9478 All the directories in the diff must exist, except the
9479 <file>debian</file> subdirectory of the top of the source
9480 tree, which will be created by
9481 <prgn>dpkg-source</prgn> if necessary when unpacking.
9485 The <prgn>dpkg-source</prgn> program will
9486 automatically make the <file>debian/rules</file> file
9487 executable (see below).</p></item>
9492 If there is no original source code - for example, if the
9493 package is specially prepared for Debian or the Debian
9494 maintainer is the same as the upstream maintainer - the
9495 format is slightly different: then there is no diff, and the
9497 <file><var>package</var>_<var>version</var>.tar.gz</file> and
9498 contains a directory
9499 <file><var>package</var>-<var>version</var></file>.
9503 <sect><heading>Unpacking a Debian source package without
9504 <prgn>dpkg-source</prgn>
9508 <tt>dpkg-source -x</tt> is the recommended way to unpack a
9509 Debian source package. However, if it is not available it
9510 is possible to unpack a Debian source archive as follows:
9511 <enumlist compact="compact">
9514 Untar the tarfile, which will create a <file>.orig</file>
9518 <p>Rename the <file>.orig</file> directory to
9519 <file><var>package</var>-<var>version</var></file>.</p>
9523 Create the subdirectory <file>debian</file> at the top of
9524 the source tree.</p>
9526 <item><p>Apply the diff using <tt>patch -p0</tt>.</p>
9528 <item><p>Untar the tarfile again if you want a copy of the original
9529 source code alongside the Debianised version.</p>
9534 It is not possible to generate a valid Debian source archive
9535 without using <prgn>dpkg-source</prgn>. In particular,
9536 attempting to use <prgn>diff</prgn> directly to generate the
9537 <file>.diff.gz</file> file will not work.
9540 <sect1><heading>Restrictions on objects in source packages
9544 The source package may not contain any hard links
9547 This is not currently detected when building source
9548 packages, but only when extracting
9554 Hard links may be permitted at some point in the
9555 future, but would require a fair amount of
9558 </footnote>, device special files, sockets or setuid or
9562 Setgid directories are allowed.
9568 The source packaging tools manage the changes between the
9569 original and Debianised source using <prgn>diff</prgn> and
9570 <prgn>patch</prgn>. Turning the original source tree as
9571 included in the <file>.orig.tar.gz</file> into the debianised
9572 source must not involve any changes which cannot be
9573 handled by these tools. Problematic changes which cause
9574 <prgn>dpkg-source</prgn> to halt with an error when
9575 building the source package are:
9576 <list compact="compact">
9577 <item><p>Adding or removing symbolic links, sockets or pipes.</p>
9579 <item><p>Changing the targets of symbolic links.</p>
9581 <item><p>Creating directories, other than <file>debian</file>.</p>
9583 <item><p>Changes to the contents of binary files.</p></item>
9584 </list> Changes which cause <prgn>dpkg-source</prgn> to
9585 print a warning but continue anyway are:
9586 <list compact="compact">
9589 Removing files, directories or symlinks.
9592 Renaming a file is not treated specially - it is
9593 seen as the removal of the old file (which
9594 generates a warning, but is otherwise ignored),
9595 and the creation of the new
9602 Changed text files which are missing the usual final
9603 newline (either in the original or the modified
9608 Changes which are not represented, but which are not detected by
9609 <prgn>dpkg-source</prgn>, are:
9610 <list compact="compact">
9611 <item><p>Changing the permissions of files (other than
9612 <file>debian/rules</file>) and directories.</p></item>
9617 The <file>debian</file> directory and <file>debian/rules</file>
9618 are handled specially by <prgn>dpkg-source</prgn> - before
9619 applying the changes it will create the <file>debian</file>
9620 directory, and afterwards it will make
9621 <file>debian/rules</file> world-exectuable.
9627 <appendix id="pkg-controlfields"><heading>Control files and their
9628 fields (from old Packaging Manual)
9632 Many of the tools in the <prgn>dpkg</prgn> suite manipulate
9633 data in a common format, known as control files. Binary and
9634 source packages have control data as do the <file>.changes</file>
9635 files which control the installation of uploaded files, and
9636 <prgn>dpkg</prgn>'s internal databases are in a similar
9640 <sect><heading>Syntax of control files
9644 A file consists of one or more paragraphs of fields. The
9645 paragraphs are separated by blank lines. Some control files
9646 only allow one paragraph; others allow several, in which
9647 case each paragraph often refers to a different package.
9651 Each paragraph is a series of fields and values; each field
9652 consists of a name, followed by a colon and the value. It
9653 ends at the end of the line. Horizontal whitespace (spaces
9654 and tabs) may occur before or after the value and is ignored
9655 there; it is conventional to put a single space after the
9660 Some fields' values may span several lines; in this case
9661 each continuation line <em>must</em> start with a space or
9662 tab. Any trailing spaces or tabs at the end of individual
9663 lines of a field value are ignored.
9667 Except where otherwise stated only a single line of data is
9668 allowed and whitespace is not significant in a field body.
9669 Whitespace may never appear inside names (of packages,
9670 architectures, files or anything else), version numbers or
9671 in between the characters of multi-character version
9676 Field names are not case-sensitive, but it is usual to
9677 capitalise the field names using mixed case as shown below.
9681 Blank lines, or lines consisting only of spaces and tabs,
9682 are not allowed within field values or between fields - that
9683 would mean a new paragraph.
9687 It is important to note that there are several fields which
9688 are optional as far as <prgn>dpkg</prgn> and the related
9689 tools are concerned, but which must appear in every Debian
9690 package, or whose omission may cause problems. When writing
9691 the control files for Debian packages you <em>must</em> read
9692 the Debian policy manual in conjuction with the details
9693 below and the list of fields for the particular file.</p>
9696 <sect><heading>List of fields
9699 <sect1 id="pkg-f-Package"><heading><tt>Package</tt>
9703 The name of the binary package. Package names consist of
9704 the alphanumerics and <tt>+</tt> <tt>-</tt> <tt>.</tt>
9705 (plus, minus and full stop).
9708 The characters <tt>@</tt> <tt>:</tt> <tt>=</tt>
9709 <tt>%</tt> <tt>_</tt> (at, colon, equals, percent
9710 and underscore) used to be legal and are still
9711 accepted when found in a package file, but may not be
9712 used in new packages
9718 They must be at least two characters and must start with
9719 an alphanumeric. In current versions of dpkg they are
9720 sort of case-sensitive<footnote><p>This is a
9721 bug.</p></footnote>; use lowercase package names unless
9722 the package you're building (or referring to, in other
9723 fields) is already using uppercase.</p>
9726 <sect1 id="pkg-f-Version"><heading><tt>Version</tt>
9730 This lists the source or binary package's version number -
9731 see <ref id="versions">.
9736 <sect1 id="pkg-f-Architecture"><heading><tt>Architecture</tt>
9740 This is the architecture string; it is a single word for
9741 the Debian architecture.
9745 <prgn>dpkg</prgn> will check the declared architecture of
9746 a binary package against its own compiled-in value before
9751 The special value <tt>all</tt> indicates that the package
9752 is architecture-independent.
9756 In the main <file>debian/control</file> file in the source
9757 package, or in the source package control file
9758 <file>.dsc</file>, a list of architectures (separated by
9759 spaces) is also allowed, as is the special value
9760 <tt>any</tt>. A list indicates that the source will build
9761 an architecture-dependent package, and will only work
9762 correctly on the listed architectures. <tt>any</tt>
9763 indicates that though the source package isn't dependent
9764 on any particular architecture and should compile fine on
9765 any one, the binary package(s) produced are not
9766 architecture-independent but will instead be specific to
9767 whatever the current build architecture is.
9771 In a <file>.changes</file> file the <tt>Architecture</tt>
9772 field lists the architecture(s) of the package(s)
9773 currently being uploaded. This will be a list; if the
9774 source for the package is being uploaded too the special
9775 entry <tt>source</tt> is also present.
9779 See <ref id="pkg-debianrules"> for information how to get the
9780 architecture for the build process.
9784 <sect1 id="pkg-f-Maintainer"><heading><tt>Maintainer</tt>
9788 The package maintainer's name and email address. The name
9789 should come first, then the email address inside angle
9790 brackets <tt><></tt> (in RFC822 format).
9794 If the maintainer's name contains a full stop then the
9795 whole field will not work directly as an email address due
9796 to a misfeature in the syntax specified in RFC822; a
9797 program using this field as an address must check for this
9798 and correct the problem if necessary (for example by
9799 putting the name in round brackets and moving it to the
9800 end, and bringing the email address forward).
9804 In a <file>.changes</file> file or parsed changelog data this
9805 contains the name and email address of the person
9806 responsible for the particular version in question - this
9807 may not be the package's usual maintainer.
9811 This field is usually optional in as far as the
9812 <prgn>dpkg</prgn> are concerned, but its absence when
9813 building packages usually generates a warning.</p>
9816 <sect1 id="pkg-f-Source"><heading><tt>Source</tt>
9820 This field identifies the source package name.
9824 In a main source control information or a
9825 <file>.changes</file> or <file>.dsc</file> file or parsed
9826 changelog data this may contain only the name of the
9831 In the control file of a binary package (or in a
9832 <file>Packages</file> file) it may be followed by a version
9833 number in parentheses.
9836 It is usual to leave a space after the package name if
9837 a version number is specified.
9839 </footnote> This version number may be omitted (and is, by
9840 <prgn>dpkg-gencontrol</prgn>) if it has the same value as
9841 the <tt>Version</tt> field of the binary package in
9842 question. The field itself may be omitted from a binary
9843 package control file when the source package has the same
9844 name and version as the binary package.
9848 <sect1><heading>Package interrelationship fields:
9849 <tt>Depends</tt>, <tt>Pre-Depends</tt>,
9850 <tt>Recommends</tt> <tt>Suggests</tt>, <tt>Conflicts</tt>,
9851 <tt>Provides</tt>, <tt>Replaces</tt>
9855 These fields describe the package's relationships with
9856 other packages. Their syntax and semantics are described
9857 in <ref id="relationships">.</p>
9860 <sect1 id="pkg-f-Description"><heading><tt>Description</tt>
9864 In a binary package <tt>Packages</tt> file or main source
9865 control file this field contains a description of the
9866 binary package, in a special format. See <ref
9867 id="descriptions"> for details.
9871 In a <file>.changes</file> file it contains a summary of the
9872 descriptions for the packages being uploaded. The part of
9873 the field before the first newline is empty; thereafter
9874 each line has the name of a binary package and the summary
9875 description line from that binary package. Each line is
9876 indented by one space.</p>
9879 <sect1 id="pkg-f-Essential"><heading><tt>Essential</tt>
9883 This is a boolean field which may occur only in the
9884 control file of a binary package (or in the
9885 <file>Packages</file> file) or in a per-package fields
9886 paragraph of a main source control data file.
9890 If set to <tt>yes</tt> then <prgn>dpkg</prgn> and
9891 <prgn>dselect</prgn> will refuse to remove the package
9892 (though it can be upgraded and/or replaced). The other
9893 possible value is <tt>no</tt>, which is the same as not
9894 having the field at all.</p>
9897 <sect1 id="pkg-f-classification"><heading><tt>Section</tt> and
9902 These two fields classify the package. The
9903 <tt>Priority</tt> represents how important that it is that
9904 the user have it installed; the <tt>Section</tt>
9905 represents an application area into which the package has
9910 When they appear in the <file>debian/control</file> file these
9911 fields give values for the section and priority subfields
9912 of the <tt>Files</tt> field of the <file>.changes</file> file,
9913 and give defaults for the section and priority of the
9918 The section and priority are represented, though not as
9919 separate fields, in the information for each file in the
9920 <qref id="pkg-f-Files"><tt>-File</tt></qref>field of a
9921 <file>.changes</file> file. The section value in a
9922 <file>.changes</file> file is used to decide where to install
9923 a package in the FTP archive.
9927 These fields are not used by by <prgn>dpkg</prgn> proper,
9928 but by <prgn>dselect</prgn> when it sorts packages and
9929 selects defaults. See the Debian policy manual for the
9930 priorities in use and the criteria for selecting the
9931 priority for a Debian package, and look at the Debian FTP
9932 archive for a list of currently in-use priorities.
9936 These fields may appear in binary package control files,
9937 in which case they provide a default value in case the
9938 <file>Packages</file> files are missing the information.
9939 <prgn>dpkg</prgn> and <prgn>dselect</prgn> will only use
9940 the value from a <file>.deb</file> file if they have no other
9941 information; a value listed in a <file>Packages</file> file
9942 will always take precedence. By default
9943 <prgn>dpkg-gencontrol</prgn> does not include the section
9944 and priority in the control file of a binary package - use
9945 the <tt>-isp</tt>, <tt>-is</tt> or <tt>-ip</tt> options to
9946 achieve this effect.</p>
9949 <sect1 id="pkg-f-Binary"><heading><tt>Binary</tt>
9953 This field is a list of binary packages.
9957 When it appears in the <file>.dsc</file> file it is the list
9958 of binary packages which a source package can produce. It
9959 does not necessarily produce all of these binary packages
9960 for every architecture. The source control file doesn't
9961 contain details of which architectures are appropriate for
9962 which of the binary packages.
9966 When it appears in a <file>.changes</file> file it lists the
9967 names of the binary packages actually being uploaded.
9971 The syntax is a list of binary packages separated by
9975 A space after each comma is conventional.
9977 </footnote> Currently the packages must be separated using
9978 only spaces in the <file>.changes</file> file.</p>
9981 <sect1 id="pkg-f-Installed-Size"><heading><tt>Installed-Size</tt>
9985 This field appears in the control files of binary
9986 packages, and in the <file>Packages</file> files. It gives
9987 the total amount of disk space required to install the
9992 The disk space is represented in kilobytes as a simple
9996 <sect1 id="pkg-f-Files"><heading><tt>Files</tt>
10000 This field contains a list of files with information about
10001 each one. The exact information and syntax varies with
10002 the context. In all cases the the part of the field
10003 contents on the same line as the field name is empty. The
10004 remainder of the field is one line per file, each line
10005 being indented by one space and containing a number of
10006 sub-fields separated by spaces.
10010 In the <file>.dsc</file> (Debian source control) file each
10011 line contains the MD5 checksum, size and filename of the
10012 tarfile and (if applicable) diff file which make up the
10013 remainder of the source package.
10016 That is, the parts which are not the
10019 </footnote> The exact forms of the filenames are described
10020 in <ref id="pkg-sourcearchives">.
10024 In the <file>.changes</file> file this contains one line per
10025 file being uploaded. Each line contains the MD5 checksum,
10026 size, section and priority and the filename. The section
10027 and priority are the values of the corresponding fields in
10028 the main source control file - see <ref
10029 id="pkg-f-classification">. If no section or priority is
10030 specified then <tt>-</tt> should be used, though section
10031 and priority values must be specified for new packages to
10032 be installed properly.
10036 The special value <tt>byhand</tt> for the section in a
10037 <tt>.changes</tt> file indicates that the file in question
10038 is not an ordinary package file and must by installed by
10039 hand by the distribution maintainers. If the section is
10040 <tt>byhand</tt> the priority should be <tt>-</tt>.
10044 If a new Debian revision of a package is being shipped and
10045 no new original source archive is being distributed the
10046 <tt>.dsc</tt> must still contain the <tt>Files</tt> field
10047 entry for the original source archive
10048 <file><var>package</var>-<var>upstream-version</var>.orig.tar.gz</file>,
10049 but the <file>.changes</file> file should leave it out. In
10050 this case the original source archive on the distribution
10051 site must match exactly, byte-for-byte, the original
10052 source archive which was used to generate the
10053 <file>.dsc</file> file and diff which are being uploaded.</p>
10058 id="pkg-f-Standards-Version"><heading><tt>Standards-Version</tt>
10062 The most recent version of the standards (the
10063 <prgn>dpkg</prgn> programmers' and policy manuals and
10064 associated texts) with which the package complies. This
10065 is updated manually when editing the source package to
10066 conform to newer standards; it can sometimes be used to
10067 tell when a package needs attention.
10071 Its format is the same as that of a version number except
10072 that no epoch or Debian revision is allowed - see <ref
10073 id="versions">.</p>
10077 <sect1 id="pkg-f-Distribution"><heading><tt>Distribution</tt>
10081 In a <file>.changes</file> file or parsed changelog output
10082 this contains the (space-separated) name(s) of the
10083 distribution(s) where this version of the package should
10084 be or was installed. Distribution names follow the rules
10085 for package names. (See <ref id="pkg-f-Package">).
10089 Current distribution values are:
10091 <tag><em>stable</em></tag>
10094 This is the current `released' version of Debian
10095 GNU/Linux. A new version is released approximately
10096 every 3 months after the <em>development</em> code has
10097 been <em>frozen</em> for a month of testing. Once the
10098 distribution is <em>stable</em> only major bug fixes
10099 are allowed. When changes are made to this
10100 distribution, the release number is increased
10101 (for example: 1.2r1 becomes 1.2r2 then 1.2r3, etc).
10105 <tag><em>unstable</em></tag>
10108 This distribution value refers to the
10109 <em>developmental</em> part of the Debian distribution
10110 tree. New packages, new upstream versions of packages
10111 and bug fixes go into the <em>unstable</em> directory
10112 tree. Download from this distribution at your own
10116 <tag><em>contrib</em></tag>
10119 The packages with this distribution value do not meet
10120 the criteria for inclusion in the main Debian
10121 distribution as defined by the Policy Manual, but meet
10122 the criteria for the <em>contrib</em>
10123 Distribution. There is currently no distinction
10124 between stable and unstable packages in the
10125 <em>contrib</em> or <em>non-free</em>
10126 distributions. Use your best judgement in downloading
10127 from this Distribution.</p>
10130 <tag><em>non-free</em></tag>
10133 Like the packages in the <em>contrib</em> seciton,
10134 the packages in <em>non-free</em> do not meet the
10135 criteria for inclusion in the main Debian distribution
10136 as defined by the Policy Manual. Again, use your best
10137 judgement in downloading from this Distribution.</p>
10139 <tag><em>experimental</em></tag>
10142 The packages with this distribution value are deemed
10143 by their maintainers to be high risk. Oftentimes they
10144 represent early beta or developmental packages from
10145 various sources that the maintainers want people to
10146 try, but are not ready to be a part of the other parts
10147 of the Debian distribution tree. Download at your own
10151 <tag><em>frozen</em></tag>
10154 From time to time, (currently, every 3 months) the
10155 <em>unstable</em> distribution enters a state of
10156 `code-freeze' in anticipation of release as a
10157 <em>stable</em> version. During this period of testing
10158 (usually 4 weeks) only fixes for existing or
10159 newly-discovered bugs will be allowed.
10162 </taglist> You should list <em>all</em> distributions that
10163 the package should be installed into. Except in unusual
10164 circumstances, installations to <em>stable</em> should also
10165 go into <em>frozen</em> (if it exists) and
10166 <em>unstable</em>. Likewise, installations into
10167 <em>frozen</em> should also go into <em>unstable</em>.</p>
10170 <sect1 id="pkg-f-Urgency"><heading><tt>Urgency</tt>
10174 This is a description of how important it is to upgrade to
10175 this version from previous ones. It consists of a single
10176 keyword usually taking one of the values <tt>LOW</tt>,
10177 <tt>MEDIUM</tt> or <tt>HIGH</tt>) followed by an optional
10178 commentary (separated by a space) which is usually in
10179 parentheses. For example:
10181 Urgency: LOW (HIGH for diversions users)
10186 This field appears in the <file>.changes</file> file and in
10187 parsed changelogs; its value appears as the value of the
10188 <tt>urgency</tt> attribute in a <prgn>dpkg</prgn>-style
10189 changelog (see <ref id="pkg-dpkgchangelog">).
10193 Urgency keywords are not case-sensitive.</p>
10196 <sect1 id="pkg-f-Date"><heading><tt>Date</tt>
10200 In <tt>.changes</tt> files and parsed changelogs, this
10201 gives the date the package was built or last edited.</p>
10204 <sect1 id="pkg-f-Format"><heading><tt>Format</tt>
10208 This field occurs in <file>.changes</file> files, and
10209 specifies a format revision for the file. The format
10210 described here is version <tt>1.5</tt>. The syntax of the
10211 format value is the same as that of a package version
10212 number except that no epoch or Debian revision is allowed
10213 - see <ref id="versions">.</p>
10216 <sect1 id="pkg-f-Changes"><heading><tt>Changes</tt>
10220 In a <file>.changes</file> file or parsed changelog this field
10221 contains the human-readable changes data, describing the
10222 differences between the last version and the current one.
10226 There should be nothing in this field before the first
10227 newline; all the subsequent lines must be indented by at
10228 least one space; blank lines must be represented by a line
10229 consiting only of a space and a full stop.
10233 Each version's change information should be preceded by a
10234 `title' line giving at least the version, distribution(s)
10235 and urgency, in a human-readable way.
10239 If data from several versions is being returned the entry
10240 for the most recent version should be returned first, and
10241 entries should be separated by the representation of a
10242 blank line (the `title' line may also be followed by the
10243 representation of blank line).</p>
10246 <sect1 id="pkg-f-Filename"><heading><tt>Filename</tt> and
10247 <tt>MSDOS-Filename</tt>
10251 These fields in <tt>Packages</tt> files give the
10252 filename(s) of (the parts of) a package in the
10253 distribution directories, relative to the root of the
10254 Debian hierarchy. If the package has been split into
10255 several parts the parts are all listed in order, separated
10259 <sect1 id="pkg-f-Size"><heading><tt>Size</tt> and <tt>MD5sum</tt>
10263 These fields in <file>Packages</file> files give the size (in
10264 bytes, expressed in decimal) and MD5 checksum of the
10265 file(s) which make(s) up a binary package in the
10266 distribution. If the package is split into several parts
10267 the values for the parts are listed in order, separated by
10271 <sect1 id="pkg-f-Status"><heading><tt>Status</tt>
10275 This field in <prgn>dpkg</prgn>'s status file records
10276 whether the user wants a package installed, removed or
10277 left alone, whether it is broken (requiring
10278 reinstallation) or not and what its current state on the
10279 system is. Each of these pieces of information is a
10283 <sect1 id="pkg-f-Config-Version"><heading><tt>Config-Version</tt>
10287 If a package is not installed or not configured, this
10288 field in <prgn>dpkg</prgn>'s status file records the last
10289 version of the package which was successfully
10293 <sect1 id="pkg-f-Conffiles"><heading><tt>Conffiles</tt>
10297 This field in <prgn>dpkg</prgn>'s status file contains
10298 information about the automatically-managed configuration
10299 files held by a package. This field should <em>not</em>
10300 appear anywhere in a package!</p>
10303 <sect1><heading>Obsolete fields
10307 These are still recognised by <prgn>dpkg</prgn> but should
10308 not appear anywhere any more.
10309 <taglist compact="compact">
10311 <tag><tt>Revision</tt></tag>
10312 <tag><tt>Package-Revision</tt></tag>
10313 <tag><tt>Package_Revision</tt></tag>
10316 The Debian revision part of the package version was
10317 at one point in a separate control file field. This
10318 field went through several names.</p>
10321 <tag><tt>Recommended</tt></tag>
10322 <item><p>Old name for <tt>Recommends</tt></p>
10325 <tag><tt>Optional</tt></tag>
10326 <item><p>Old name for <tt>Suggests</tt>.</p>
10328 <tag><tt>Class</tt></tag>
10329 <item><p>Old name for <tt>Priority</tt>.</p>
10337 <appendix id="pkg-conffiles"><heading>Configuration file handling
10338 (from old Packaging Manual)
10342 <prgn>dpkg</prgn> can do a certain amount of automatic
10343 handling of package configuration files.
10347 Whether this mechanism is appropriate depends on a number of
10348 factors, but basically there are two approaches to any
10349 particular configuration file.
10353 The easy method is to ship a best-effort configuration in the
10354 package, and use <prgn>dpkg</prgn>'s conffile mechanism to
10355 handle updates. If the user is unlikely to want to edit the
10356 file, but you need them to be able to without losing their
10357 changes, and a new package with a changed version of the file
10358 is only released infrequently, this is a good approach.
10362 The hard method is to build the configuration file from
10363 scratch in the <prgn>postinst</prgn> script, and to take the
10364 responsibility for fixing any mistakes made in earlier
10365 versions of the package automatically. This will be
10366 appropriate if the file is likely to need to be different on
10370 <sect><heading>Automatic handling of configuration files by
10375 A package may contain a control area file called
10376 <tt>conffiles</tt>. This file should be a list of filenames
10377 of configuration files needing automatic handling, separated
10378 by newlines. The filenames should be absolute pathnames,
10379 and the files referred to should actually exist in the
10384 When a package is upgraded <prgn>dpkg</prgn> will process
10385 the configuration files during the configuration stage,
10386 shortly before it runs the package's <prgn>postinst</prgn>
10391 For each file it checks to see whether the version of the
10392 file included in the package is the same as the one that was
10393 included in the last version of the package (the one that is
10394 being upgraded from); it also compares the version currently
10395 installed on the system with the one shipped with the last
10400 If neither the user nor the package maintainer has changed
10401 the file, it is left alone. If one or the other has changed
10402 their version, then the changed version is preferred - i.e.,
10403 if the user edits their file, but the package maintainer
10404 doesn't ship a different version, the user's changes will
10405 stay, silently, but if the maintainer ships a new version
10406 and the user hasn't edited it the new version will be
10407 installed (with an informative message). If both have
10408 changed their version the user is prompted about the problem
10409 and must resolve the differences themselves.
10413 The comparisons are done by calculating the MD5 message
10414 digests of the files, and storing the MD5 of the file as it
10415 was included in the most recent version of the package.
10419 When a package is installed for the first time
10420 <prgn>dpkg</prgn> will install the file that comes with it,
10421 unless that would mean overwriting a file already on the
10426 However, note that <prgn>dpkg</prgn> will <em>not</em>
10427 replace a conffile that was removed by the user (or by a
10428 script). This is necessary because with some programs a
10429 missing file produces an effect hard or impossible to
10430 achieve in another way, so that a missing file needs to be
10431 kept that way if the user did it.
10435 Note that a package should <em>not</em> modify a
10436 <prgn>dpkg</prgn>-handled conffile in its maintainer
10437 scripts. Doing this will lead to <prgn>dpkg</prgn> giving
10438 the user confusing and possibly dangerous options for
10439 conffile update when the package is upgraded.</p>
10442 <sect><heading>Fully-featured maintainer script configuration
10447 For files which contain site-specific information such as
10448 the hostname and networking details and so forth, it is
10449 better to create the file in the package's
10450 <prgn>postinst</prgn> script.
10454 This will typically involve examining the state of the rest
10455 of the system to determine values and other information, and
10456 may involve prompting the user for some information which
10457 can't be obtained some other way.
10461 When using this method there are a couple of important
10462 issues which should be considered:
10466 If you discover a bug in the program which generates the
10467 configuration file, or if the format of the file changes
10468 from one version to the next, you will have to arrange for
10469 the postinst script to do something sensible - usually this
10470 will mean editing the installed configuration file to remove
10471 the problem or change the syntax. You will have to do this
10472 very carefully, since the user may have changed the file,
10473 perhaps to fix the very problem that your script is trying
10474 to deal with - you will have to detect these situations and
10475 deal with them correctly.
10479 If you do go down this route it's probably a good idea to
10480 make the program that generates the configuration file(s) a
10481 separate program in <file>/usr/sbin</file>, by convention called
10482 <file><var>package</var>config</file> and then run that if
10483 appropriate from the post-installation script. The
10484 <tt><var>package</var>config</tt> program should not
10485 unquestioningly overwrite an existing configuration - if its
10486 mode of operation is geared towards setting up a package for
10487 the first time (rather than any arbitrary reconfiguration
10488 later) you should have it check whether the configuration
10489 already exists, and require a <tt>--force</tt> flag to
10490 overwrite it.</p></sect>
10493 <appendix id="pkg-alternatives"><heading>Alternative versions of
10494 an interface - <prgn>update-alternatives</prgn> (from old
10499 When several packages all provide different versions of the
10500 same program or file it is useful to have the system select a
10501 default, but to allow the system administrator to change it
10502 and have their decisions respected.
10506 For example, there are several versions of the <prgn>vi</prgn>
10507 editor, and there is no reason to prevent all of them from
10508 being installed at once, each under their own name
10509 (<prgn>nvi</prgn>, <prgn>vim</prgn> or whatever).
10510 Nevertheless it is desirable to have the name <tt>vi</tt>
10511 refer to something, at least by default.
10515 If all the packages involved cooperate, this can be done with
10516 <prgn>update-alternatives</prgn>.
10520 Each package provides its own version under its own name, and
10521 calls <prgn>update-alternatives</prgn> in its postinst to
10522 register its version (and again in its prerm to deregister
10527 See the manpage <manref name="update-alternatives"
10528 section="8"> for details.
10532 If <prgn>update-alternatives</prgn> does not seem appropriate
10533 you may wish to consider using diversions instead.</p>
10536 <appendix id="pkg-diversions"><heading>Diversions - overriding a
10537 package's version of a file (from old Packaging Manual)
10541 It is possible to have <prgn>dpkg</prgn> not overwrite a file
10542 when it reinstalls the package it belongs to, and to have it
10543 put the file from the package somewhere else instead.
10547 This can be used locally to override a package's version of a
10548 file, or by one package to override another's version (or
10549 provide a wrapper for it).
10553 Before deciding to use a diversion, read <ref
10554 id="pkg-alternatives"> to see if you really want a diversion
10555 rather than several alternative versions of a program.
10559 There is a diversion list, which is read by <prgn>dpkg</prgn>,
10560 and updated by a special program <prgn>dpkg-divert</prgn>.
10561 Please see <manref name="dpkg-divert" section="8"> for full
10562 details of its operation.
10566 When a package wishes to divert a file from another, it should
10567 call <prgn>dpkg-divert</prgn> in its preinst to add the
10568 diversion and rename the existing file. For example,
10569 supposing that a <prgn>smailwrapper</prgn> package wishes to
10570 install a wrapper around <file>/usr/sbin/smail</file>:
10572 if [ install = "$1" ]; then
10573 dpkg-divert --package smailwrapper --add --rename \
10574 --divert /usr/sbin/smail.real /usr/sbin/smail
10576 </example> Testing <tt>$1</tt> is necessary so that the script
10577 doesn't try to add the diversion again when
10578 <prgn>smailwrapper</prgn> is upgraded. The <tt>--package
10579 smailwrapper</tt> ensures that <prgn>smailwrapper</prgn>'s
10580 copy of <file>/usr/sbin/smail</file> can bypass the diversion and
10581 get installed as the true version.
10585 The postrm has to do the reverse:
10587 if [ remove = "$1" ]; then
10588 dpkg-divert --package smailwrapper --remove --rename \
10589 --divert /usr/sbin/smail.real /usr/sbin/smail
10595 Do not attempt to divert a file which is vitally important for
10596 the system's operation - when using <prgn>dpkg-divert</prgn>
10597 there is a time, after it has been diverted but before
10598 <prgn>dpkg</prgn> has installed the new version, when the file
10599 does not exist.</p>