1 <!doctype debiandoc system [
2 <!-- include version information so we don't have to hard code it
3 within the document -->
4 <!entity % versiondata SYSTEM "version.ent"> %versiondata;
10 <title>Debian Policy Manual</title>
11 <author><qref id="authors">The Debian Policy Mailing List</qref></author>
12 <version>version &version;, &date;</version>
15 This manual describes the policy requirements for the Debian
16 GNU/Linux distribution. This includes the structure and
17 contents of the Debian archive and several design issues of
18 the operating system, as well as technical requirements that
19 each package must satisfy to be included in the distribution.
24 Copyright © 1996,1997,1998 Ian Jackson
25 and Christian Schwarz.
28 This manual is free software; you may redistribute it and/or
29 modify it under the terms of the GNU General Public License
30 as published by the Free Software Foundation; either version
31 2, or (at your option) any later version.
35 This is distributed in the hope that it will be useful, but
36 <em>without any warranty</em>; without even the implied
37 warranty of merchantability or fitness for a particular
38 purpose. See the GNU General Public License for more
43 A copy of the GNU General Public License is available as
44 <file>/usr/share/common-licenses/GPL</file> in the Debian GNU/Linux
45 distribution or on the World Wide Web at
46 <url id="http://www.gnu.org/copyleft/gpl.html"
47 name="the GNU General Public Licence">. You can also
48 obtain it by writing to the Free Software Foundation, Inc.,
49 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
57 <heading>About this manual</heading>
59 <heading>Scope</heading>
61 This manual describes the policy requirements for the Debian
62 GNU/Linux distribution. This includes the structure and
63 contents of the Debian archive and several design issues of the
64 operating system, as well as technical requirements that
65 each package must satisfy to be included in the
70 This manual also describes Debian policy as it relates to
71 creating Debian packages. It is not a tutorial on how to build
72 packages, nor is it exhaustive where it comes to describing
73 the behavior of the packaging system. Instead, this manual
74 attempts to define the interface to the package management
75 system that the developers have to be conversant with.<footnote>
76 Informally, the criteria used for inclusion is that the
77 material meet one of the following requirements:
78 <taglist compact="compact">
79 <tag>Standard interfaces</tag>
81 The material presented represents an interface to
82 the packaging system that is mandated for use, and
83 is used by, a significant number of packages, and
84 therefore should not be changed without peer
85 review. Package maintainers can then rely on this
86 interfaces not changing, and the package
87 management software authors need to ensure
88 compatibility with these interface
89 definitions. (Control file and changelog file
90 formats are examples.)
92 <tag>Chosen Convention</tag>
94 If there are a number of technically viable choices
95 that can be made, but one needs to select one of
96 these options for inter-operability. The version
97 number format is one example.
100 Please note that these are not mutually exclusive;
101 selected conventions often become parts of standard
107 The footnotes present in this manual are
108 merely informative, and are not part of Debian policy itself.
112 The appendices to this manual are not necessarily normative,
113 either. Please see <ref id="pkg-scope"> for more information.
117 In the normative part of this manual,
118 the words <em>must</em>, <em>should</em> and
119 <em>may</em>, and the adjectives <em>required</em>,
120 <em>recommended</em> and <em>optional</em>, are used to
121 distinguish the significance of the various guidelines in
122 this policy document. Packages that do not conform to the
123 guidelines denoted by <em>must</em> (or <em>required</em>)
124 will generally not be considered acceptable for the Debian
125 distribution. Non-conformance with guidelines denoted by
126 <em>should</em> (or <em>recommended</em>) will generally be
127 considered a bug, but will not necessarily render a package
128 unsuitable for distribution. Guidelines denoted by
129 <em>may</em> (or <em>optional</em>) are truly optional and
130 adherence is left to the maintainer's discretion.
134 These classifications are roughly equivalent to the bug
135 severities <em>serious</em> (for <em>must</em> or
136 <em>required</em> directive violations), <em>minor</em>,
137 <em>normal</em> or <em>important</em>
138 (for <em>should</em> or <em>recommended</em> directive
139 violations) and <em>wishlist</em> (for <em>optional</em>
142 Compare RFC 2119. Note, however, that these words are
143 used in a different way in this document.
148 Much of the information presented in this manual will be
149 useful even when building a package which is to be
150 distributed in some other way or is intended for local use
156 <heading>New versions of this document</heading>
159 This manual is distributed via the Debian package
160 <package><url name="debian-policy" id="http://packages.debian.org/debian-policy"></package>.
164 The current version of this document is also available from
165 the Debian web mirrors at
166 <tt><url name="/doc/debian-policy/"
167 id="http://www.debian.org/doc/debian-policy/"></tt>.
168 Also available from the same directory are several other
169 formats: <file>policy.html.tar.gz</file>, <file>policy.pdf.gz</file>
170 and <file>policy.ps.gz</file>.
174 The <package>debian-policy</package> package also includes the file
175 <file>upgrading-checklist.txt</file> which indicates policy
176 changes between versions of this document.
181 <heading>Authors and Maintainers</heading>
184 Originally called "Debian GNU/Linux Policy Manual", this
185 manual was initially written in 1996 by Ian Jackson.
186 It was revised on November 27th, 1996 by David A. Morris.
187 Christian Schwarz added new sections on March 15th, 1997,
188 and reworked/restructured it in April-July 1997.
189 Christoph Lameter contributed the "Web Standard".
190 Julian Gilbey largely restructured it in 2001.
194 Since September 1998, the responsibility for the contents of
195 this document lies on the <url name="debian-policy mailing list"
196 id="mailto:debian-policy@lists.debian.org">. Proposals
197 are discussed there and inserted into policy after a certain
198 consensus is established.
199 <!-- insert shameless policy-process plug here eventually -->
200 The actual editing is done by a group of maintainers that have
201 no editorial powers. These are the current maintainers:
204 <item>Julian Gilbey</item>
205 <item>Branden Robinson</item>
206 <item>Josip Rodin</item>
207 <item>Manoj Srivastava</item>
212 While the authors of this document have tried hard to avoid
213 typos and other errors, these do still occur. If you discover
214 an error in this manual or if you want to give any
215 comments, suggestions, or criticisms please send an email to
216 the Debian Policy List,
217 <email>debian-policy@lists.debian.org</email>, or submit a
218 bug report against the <tt>debian-policy</tt> package.
222 Please do not try to reach the individual authors or maintainers
223 of the Policy Manual regarding changes to the Policy.
228 <heading>Related documents</heading>
231 There are several other documents other than this Policy Manual
232 that are necessary to fully understand some Debian policies and
237 The external "sub-policy" documents are referred to in:
238 <list compact="compact">
239 <item><ref id="fhs"></item>
240 <item><ref id="virtual_pkg"></item>
241 <item><ref id="menus"></item>
242 <item><ref id="mime"></item>
243 <item><ref id="perl"></item>
244 <item><ref id="maintscriptprompt"></item>
245 <item><ref id="emacs"></item>
250 In addition to those, which carry the weight of policy, there
251 is the Debian Developer's Reference. This document describes
252 procedures and resources for Debian developers, but it is
253 <em>not</em> normative; rather, it includes things that don't
254 belong into the Policy, such as best practices for developers.
258 The Developer's Reference is available in the
259 <package>developers-reference</package> package.
260 It's also available from the Debian web mirrors at
261 <tt><url name="/doc/developers-reference/"
262 id="http://www.debian.org/doc/developers-reference/"></tt>.
270 <heading>The Debian Archive</heading>
273 The Debian GNU/Linux system is maintained and distributed as a
274 collection of <em>packages</em>. Since there are so many of
275 them (currently well over 6000), they are split into
276 <em>sections</em> and given <em>priorities</em> to simplify
277 the handling of them.
281 The effort of the Debian project is to build a free operating
282 system, but not every package we want to make accessible is
283 <em>free</em> in our sense (see the Debian Free Software
284 Guidelines, below), or may be imported/exported without
285 restrictions. Thus, the archive is split into the sections
286 based on their licenses and other restrictions.
290 The aims of this are:
292 <list compact="compact">
293 <item>to allow us to make as much software available as we can</item>
294 <item>to allow us to encourage everyone to write free software,
296 <item>to allow us to make it easy for people to produce
297 CD-ROMs of our system without violating any licenses,
298 import/export restrictions, or any other laws.</item>
303 The <em>main</em> and the <em>non-US/main</em> sections
304 together form the <em>Debian GNU/Linux distribution</em>.
308 Packages in the other sections are not considered to be part
309 of the Debian distribution, although we support their use and
310 provide infrastructure for them (such as our bug-tracking
311 system and mailing lists). This Debian Policy Manual applies
312 to these packages as well.
316 <heading>The Debian Free Software Guidelines</heading>
318 The Debian Free Software Guidelines (DFSG) form our
319 definition of "free software". These are:
321 <tag>Free Redistribution
324 The license of a Debian component may not restrict any
325 party from selling or giving away the software as a
326 component of an aggregate software distribution
327 containing programs from several different
328 sources. The license may not require a royalty or
329 other fee for such sale.
334 The program must include source code, and must allow
335 distribution in source code as well as compiled form.
340 The license must allow modifications and derived
341 works, and must allow them to be distributed under the
342 same terms as the license of the original software.
344 <tag>Integrity of The Author's Source Code
347 The license may restrict source-code from being
348 distributed in modified form <em>only</em> if the
349 license allows the distribution of "patch files"
350 with the source code for the purpose of modifying the
351 program at build time. The license must explicitly
352 permit distribution of software built from modified
353 source code. The license may require derived works to
354 carry a different name or version number from the
355 original software. (This is a compromise. The Debian
356 Project encourages all authors to not restrict any
357 files, source or binary, from being modified.)
359 <tag>No Discrimination Against Persons or Groups
362 The license must not discriminate against any person
365 <tag>No Discrimination Against Fields of Endeavor
368 The license must not restrict anyone from making use
369 of the program in a specific field of endeavor. For
370 example, it may not restrict the program from being
371 used in a business, or from being used for genetic
374 <tag>Distribution of License
377 The rights attached to the program must apply to all
378 to whom the program is redistributed without the need
379 for execution of an additional license by those
382 <tag>License Must Not Be Specific to Debian
385 The rights attached to the program must not depend on
386 the program's being part of a Debian system. If the
387 program is extracted from Debian and used or
388 distributed without Debian but otherwise within the
389 terms of the program's license, all parties to whom
390 the program is redistributed must have the same
391 rights as those that are granted in conjunction with
394 <tag>License Must Not Contaminate Other Software
397 The license must not place restrictions on other
398 software that is distributed along with the licensed
399 software. For example, the license must not insist
400 that all other programs distributed on the same medium
401 must be free software.
403 <tag>Example Licenses
406 The "GPL," "BSD," and "Artistic" licenses are examples of
407 licenses that we consider <em>free</em>.
414 <heading>Sections</heading>
417 <heading>The main section</heading>
420 Every package in <em>main</em> and <em>non-US/main</em>
421 must comply with the DFSG (Debian Free Software
426 In addition, the packages in <em>main</em>
427 <list compact="compact">
429 must not require a package outside of <em>main</em>
430 for compilation or execution (thus, the package must
431 not declare a "Depends", "Recommends", or
432 "Build-Depends" relationship on a non-<em>main</em>
436 must not be so buggy that we refuse to support them,
440 must meet all policy requirements presented in this
447 Similarly, the packages in <em>non-US/main</em>
448 <list compact="compact">
450 must not require a package outside of <em>main</em>
451 or <em>non-US/main</em> for compilation or
455 must not be so buggy that we refuse to support them,
458 must meet all policy requirements presented in this
467 <heading>The contrib section</heading>
470 Every package in <em>contrib</em> and
471 <em>non-US/contrib</em> must comply with the DFSG.
475 In addition, the packages in <em>contrib</em> and
476 <em>non-US/contrib</em>
477 <list compact="compact">
479 must not be so buggy that we refuse to support them,
483 must meet all policy requirements presented in this
490 Furthermore, packages in <em>contrib</em> must not require
491 a package in a <em>non-US</em> section for compilation or
496 Examples of packages which would be included in
497 <em>contrib</em> or <em>non-US/contrib</em> are:
498 <list compact="compact">
500 free packages which require <em>contrib</em>,
501 <em>non-free</em> packages or packages which are not
502 in our archive at all for compilation or execution,
506 wrapper packages or other sorts of free accessories for
513 <sect1 id="non-free">
514 <heading>The non-free section</heading>
517 Packages must be placed in <em>non-free</em> or
518 <em>non-US/non-free</em> if they are not compliant with
519 the DFSG or are encumbered by patents or other legal
520 issues that make their distribution problematic.
524 In addition, the packages in <em>non-free</em> and
525 <em>non-US/non-free</em>
526 <list compact="compact">
528 must not be so buggy that we refuse to support them,
532 must meet all policy requirements presented in this
533 manual that it is possible for them to meet.
535 It is possible that there are policy
536 requirements which the package is unable to
537 meet, for example, if the source is
538 unavailable. These situations will need to be
539 handled on a case-by-case basis.
547 <heading>The non-US sections</heading>
550 Non-free programs with cryptographic program code need to
551 be stored on the <em>non-us</em> server because of export
552 restrictions of the U.S.
556 Programs which use patented algorithms that have a
557 restricted license also need to be stored on "non-us",
558 since that is located in a country where it is not allowed
559 to patent algorithms.
563 A package depends on another package which is distributed
564 via the non-us server has to be stored on the non-us
570 <sect id="pkgcopyright">
571 <heading>Copyright considerations</heading>
574 Every package must be accompanied by a verbatim copy of
575 its copyright and distribution license in the file
576 <file>/usr/share/doc/<var>package</var>/copyright</file>
577 (see <ref id="copyrightfile"> for further details).
581 We reserve the right to restrict files from being included
582 anywhere in our archives if
583 <list compact="compact">
585 their use or distribution would break a law,
588 there is an ethical conflict in their distribution or
592 we would have to sign a license for them, or
595 their distribution would conflict with other project
602 Programs whose authors encourage the user to make
603 donations are fine for the main distribution, provided
604 that the authors do not claim that not donating is
605 immoral, unethical, illegal or something similar; in such
606 a case they must go in <em>non-free</em>.
610 Packages whose copyright permission notices (or patent
611 problems) do not even allow redistribution of binaries
612 only, and where no special permission has been obtained,
613 must not be placed on the Debian FTP site and its mirrors
618 Note that under international copyright law (this applies
619 in the United States, too), <em>no</em> distribution or
620 modification of a work is allowed without an explicit
621 notice saying so. Therefore a program without a copyright
622 notice <em>is</em> copyrighted and you may not do anything
623 to it without risking being sued! Likewise if a program
624 has a copyright notice but no statement saying what is
625 permitted then nothing is permitted.
629 Many authors are unaware of the problems that restrictive
630 copyrights (or lack of copyright notices) can cause for
631 the users of their supposedly-free software. It is often
632 worthwhile contacting such authors diplomatically to ask
633 them to modify their license terms. However, this can be a
634 politically difficult thing to do and you should ask for
635 advice on the <tt>debian-legal</tt> mailing list first, as
640 When in doubt about a copyright, send mail to
641 <email>debian-legal@lists.debian.org</email>. Be prepared
642 to provide us with the copyright statement. Software
643 covered by the GPL, public domain software and BSD-like
644 copyrights are safe; be wary of the phrases "commercial
645 use prohibited" and "distribution restricted".
649 <sect id="subsections">
650 <heading>Subsections</heading>
653 The packages in the sections <em>main</em>,
654 <em>contrib</em> and <em>non-free</em> are grouped further
655 into <em>subsections</em> to simplify handling.
659 The section and subsection for each package should be
660 specified in the package's <tt>Section</tt> control
661 record (see <ref id="f-Section">).
662 However, the maintainer of the Debian archive
663 may override this selection to ensure the consistency of
664 the Debian distribution. The <tt>Section</tt> field
665 should be of the form:
666 <list compact="compact">
668 <em>subsection</em> if the package is in the
669 <em>main</em> section,
672 <em>section/subsection</em> if the package is in
673 the <em>contrib</em> or <em>non-free</em> section,
677 <tt>non-US</tt>, <tt>non-US/contrib</tt> or
678 <tt>non-US/non-free</tt> if the package is in
679 <em>non-US/main</em>, <em>non-US/contrib</em> or
680 <em>non-US/non-free</em> respectively.
686 The Debian archive maintainers provide the authoritative
687 list of subsections. At present, they are:
688 <em>admin</em>, <em>base</em>, <em>comm</em>,
689 <em>contrib</em>, <em>devel</em>, <em>doc</em>,
690 <em>editors</em>, <em>electronics</em>, <em>embedded</em>,
691 <em>games</em>, <em>gnome</em>, <em>graphics</em>,
692 <em>hamradio</em>, <em>interpreters</em>, <em>kde</em>,
693 <em>libs</em>, <em>libdevel</em>, <em>mail</em>,
694 <em>math</em>, <em>misc</em>, <em>net</em>, <em>news</em>,
695 <em>non-US</em>, <em>non-free</em>, <em>oldlibs</em>,
696 <em>otherosfs</em>, <em>perl</em>, <em>python</em>
697 <em>science</em>, <em>shells</em>,
698 <em>sound</em>, <em>tex</em>, <em>text</em>,
699 <em>utils</em>, <em>web</em>, <em>x11</em>.
703 <sect id="priorities">
704 <heading>Priorities</heading>
707 Each package should have a <em>priority</em> value, which is
708 included in the package's <em>control record</em>
709 (see <ref id="f-Priority">).
710 This information is used by the Debian package management tools to
711 separate high-priority packages from less-important packages.
715 The following <em>priority levels</em> are recognised by the
716 Debian package management tools.
718 <tag><tt>required</tt></tag>
720 Packages which are necessary for the proper
721 functioning of the system. You must not remove these
722 packages or your system may become totally broken and
723 you may not even be able to use <prgn>dpkg</prgn> to
724 put things back. Systems with only the
725 <tt>required</tt> packages are probably unusable, but
726 they do have enough functionality to allow the
727 sysadmin to boot and install more software.
729 <tag><tt>important</tt></tag>
731 Important programs, including those which one would
732 expect to find on any Unix-like system. If the
733 expectation is that an experienced Unix person who
734 found it missing would say "What on earth is going on,
735 where is <prgn>foo</prgn>?", it must be an
736 <tt>important</tt> package.<footnote>
737 This is an important criterion because we are
738 trying to produce, amongst other things, a free
741 Other packages without which the system will not run
742 well or be usable must also have priority
743 <tt>important</tt>. This does
744 <em>not</em> include Emacs, the X Window System, TeX
745 or any other large applications. The
746 <tt>important</tt> packages are just a bare minimum of
747 commonly-expected and necessary tools.
749 <tag><tt>standard</tt></tag>
751 These packages provide a reasonably small but not too
752 limited character-mode system. This is what will be
753 installed by default if the user doesn't select anything
754 else. It doesn't include many large applications.
756 <tag><tt>optional</tt></tag>
758 (In a sense everything that isn't required is
759 optional, but that's not what is meant here.) This is
760 all the software that you might reasonably want to
761 install if you didn't know what it was and don't have
762 specialized requirements. This is a much larger system
763 and includes the X Window System, a full TeX
764 distribution, and many applications. Note that
765 optional packages should not conflict with each other.
767 <tag><tt>extra</tt></tag>
769 This contains all packages that conflict with others
770 with required, important, standard or optional
771 priorities, or are only likely to be useful if you
772 already know what they are or have specialised
779 Packages must not depend on packages with lower priority
780 values (excluding build-time dependencies). In order to
781 ensure this, the priorities of one or more packages may need
790 <heading>Binary packages</heading>
793 The Debian GNU/Linux distribution is based on the Debian
794 package management system, called <prgn>dpkg</prgn>. Thus,
795 all packages in the Debian distribution must be provided
796 in the <tt>.deb</tt> file format.
800 <heading>The package name</heading>
803 Every package must have a name that's unique within the Debian
808 The package name is included in the control field
809 <tt>Package</tt>, the format of which is described
810 in <ref id="f-Package">.
811 The package name is also included as a part of the file name
812 of the <tt>.deb</tt> file.
817 <heading>The version of a package</heading>
820 Every package has a version number recorded in its
821 <tt>Version</tt> control file field, described in
822 <ref id="f-Version">.
826 The package management system imposes an ordering on version
827 numbers, so that it can tell whether packages are being up- or
828 downgraded and so that package system front end applications
829 can tell whether a package it finds available is newer than
830 the one installed on the system. The version number format
831 has the most significant parts (as far as comparison is
832 concerned) at the beginning.
836 If an upstream package has problematic version numbers they
837 should be converted to a sane form for use in the
838 <tt>Version</tt> field.
842 <heading>Version numbers based on dates</heading>
845 In general, Debian packages should use the same version
846 numbers as the upstream sources.
850 However, in some cases where the upstream version number is
851 based on a date (e.g., a development "snapshot" release) the
852 package management system cannot handle these version
853 numbers without epochs. For example, dpkg will consider
854 "96May01" to be greater than "96Dec24".
858 To prevent having to use epochs for every new upstream
859 version, the version number should be changed to the
860 following format in such cases: "19960501", "19961224". It
861 is up to the maintainer whether he/she wants to bother the
862 upstream maintainer to change the version numbers upstream,
867 Note that other version formats based on dates which are
868 parsed correctly by the package management system should
869 <em>not</em> be changed.
873 Native Debian packages (i.e., packages which have been
874 written especially for Debian) whose version numbers include
875 dates should always use the "YYYYMMDD" format.
882 <heading>The maintainer of a package</heading>
885 Every package must have a Debian maintainer (the
886 maintainer may be one person or a group of people
887 reachable from a common email address, such as a mailing
888 list). The maintainer is responsible for ensuring that
889 the package is placed in the appropriate distributions.
893 The maintainer must be specified in the
894 <tt>Maintainer</tt> control field with their correct name
895 and a working email address. If one person maintains
896 several packages, he/she should try to avoid having
897 different forms of their name and email address in
898 the <tt>Maintainer</tt> fields of those packages.
902 The format of the <tt>Maintainer</tt> control field is
903 described in <ref id="f-Maintainer">.
907 If the maintainer of a package quits from the Debian
908 project, "Debian QA Group"
909 <email>packages@qa.debian.org</email> takes over the
910 maintainership of the package until someone else
911 volunteers for that task. These packages are called
912 <em>orphaned packages</em>.<footnote>
913 The detailed procedure for doing this gracefully can
914 be found in the Debian Developer's Reference,
915 see <ref id="related">.
920 <sect id="descriptions">
921 <heading>The description of a package</heading>
924 Every Debian package must have an extended description
925 stored in the appropriate field of the control record.
926 The technical information about the format of the
927 <tt>Description</tt> field is in <ref id="f-Description">.
931 The description should describe the package (the program) to a
932 user (system administrator) who has never met it before so that
933 they have enough information to decide whether they want to
934 install it. This description should not just be copied verbatim
935 from the program's documentation.
939 Put important information first, both in the synopsis and
940 extended description. Sometimes only the first part of the
941 synopsis or of the description will be displayed. You can
942 assume that there will usually be a way to see the whole
943 extended description.
947 The description should also give information about the
948 significant dependencies and conflicts between this package
949 and others, so that the user knows why these dependencies and
950 conflicts have been declared.
954 Instructions for configuring or using the package should
955 not be included (that is what installation scripts,
956 manual pages, info files, etc., are for). Copyright
957 statements and other administrivia should not be included
958 either (that is what the copyright file is for).
961 <sect1 id="synopsis"><heading>The single line synopsis</heading>
964 The single line synopsis should be kept brief - certainly
969 Do not include the package name in the synopsis line. The
970 display software knows how to display this already, and you
971 do not need to state it. Remember that in many situations
972 the user may only see the synopsis line - make it as
973 informative as you can.
978 <sect1 id="extendeddesc"><heading>The extended description</heading>
981 Do not try to continue the single line synopsis into the
982 extended description. This will not work correctly when
983 the full description is displayed, and makes no sense
984 where only the summary (the single line synopsis) is
989 The extended description should describe what the package
990 does and how it relates to the rest of the system (in terms
991 of, for example, which subsystem it is which part of).
995 The description field needs to make sense to anyone, even
996 people who have no idea about any of the things the
997 package deals with.<footnote>
998 The blurb that comes with a program in its
999 announcements and/or <prgn>README</prgn> files is
1000 rarely suitable for use in a description. It is
1001 usually aimed at people who are already in the
1002 community where the package is used.
1011 <heading>Dependencies</heading>
1014 Every package must specify the dependency information
1015 about other packages that are required for the first to
1020 For example, a dependency entry must be provided for any
1021 shared libraries required by a dynamically-linked executable
1022 binary in a package.
1026 Packages are not required to declare any dependencies they
1027 have on other packages which are marked <tt>Essential</tt>
1028 (see below), and should not do so unless they depend on a
1029 particular version of that package.
1033 Sometimes, a package requires another package to be installed
1034 <em>and</em> configured before it can be installed. In this
1035 case, you must specify a <tt>Pre-Depends</tt> entry for
1040 You should not specify a <tt>Pre-Depends</tt> entry for a
1041 package before this has been discussed on the
1042 <tt>debian-devel</tt> mailing list and a consensus about
1043 doing that has been reached.
1047 The format of the package interrelationship control fields is
1048 described in <ref id="relationships">.
1052 <sect id="virtual_pkg">
1053 <heading>Virtual packages</heading>
1056 Sometimes, there are several packages which offer
1057 more-or-less the same functionality. In this case, it's
1058 useful to define a <em>virtual package</em> whose name
1059 describes that common functionality. (The virtual
1060 packages only exist logically, not physically; that's why
1061 they are called <em>virtual</em>.) The packages with this
1062 particular function will then <em>provide</em> the virtual
1063 package. Thus, any other package requiring that function
1064 can simply depend on the virtual package without having to
1065 specify all possible packages individually.
1069 All packages should use virtual package names where
1070 appropriate, and arrange to create new ones if necessary.
1071 They should not use virtual package names (except privately,
1072 amongst a cooperating group of packages) unless they have
1073 been agreed upon and appear in the list of virtual package
1074 names. (See also <ref id="virtual">)
1078 The latest version of the authoritative list of virtual
1079 package names can be found in the <tt>debian-policy</tt> package.
1080 It is also available from the Debian web mirrors at
1081 <tt><url name="/doc/packaging-manuals/virtual-package-names-list.txt"
1082 id="http://www.debian.org/doc/packaging-manuals/virtual-package-names-list.txt"></tt>
1083 and from the Debian archive mirrors at
1084 <tt><url name="/doc/package-developer/virtual-package-names-list.txt"
1085 id="http://ftp.debian.org/debian/doc/package-developer/virtual-package-names-list.txt"></tt>.
1089 The procedure for updating the list is described in the preface
1096 <heading>Base system</heading>
1099 The <tt>base system</tt> is a minimum subset of the Debian
1100 GNU/Linux system that is installed before everything else
1101 on a new system. Thus, only very few packages are allowed
1102 to go into the <tt>base</tt> section to keep the required
1103 disk usage very small.
1107 Most of these packages will have the priority value
1108 <tt>required</tt> or at least <tt>important</tt>, and many
1109 of them will be tagged <tt>essential</tt> (see below).
1114 <heading>Essential packages</heading>
1117 Some packages are tagged <tt>essential</tt> for a system
1118 using the <tt>Essential</tt> control file field.
1119 The format of the <tt>Essential</tt> control field is
1120 described in <ref id="f-Essential">.
1124 Since these packages cannot be easily removed (one has to
1125 specify an extra <em>force option</em> to
1126 <prgn>dpkg</prgn> to do so), this flag must not be used
1127 unless absolutely necessary. A shared library package
1128 must not be tagged <tt>essential</tt>; dependencies will
1129 prevent its premature removal, and we need to be able to
1130 remove it when it has been superseded.
1134 Since dpkg will not prevent upgrading of other packages
1135 while an <tt>essential</tt> package is in an unconfigured
1136 state, all <tt>essential</tt> packages must supply all of
1137 their core functionality even when unconfigured. If the
1138 package cannot satisfy this requirement it must not be
1139 tagged as essential, and any packages depending on this
1140 package must instead have explicit dependency fields as
1145 You must not tag any packages <tt>essential</tt> before
1146 this has been discussed on the <tt>debian-devel</tt>
1147 mailing list and a consensus about doing that has been
1153 <heading>Tasks</heading>
1156 The Debian install process allows the user to choose from
1157 a number of common tasks which a Debian system can be used to
1158 perform. Selecting a task with <prgn>tasksel</prgn> causes
1159 a set of packages that are useful in performing that task to be
1164 This set of packages is all available packages which have the
1165 name of the selected task in the <tt>Task</tt> field of their
1166 control file. The format of this field is a list of tasks,
1167 separated by commas.
1171 You should not tag any packages as belonging to a task
1172 before this has been discussed on the
1173 <em>debian-devel</em> mailing list and a consensus about
1174 doing that has been reached.
1178 For third parties (and historical reasons), tasksel also
1179 supports constructing tasks based on <em>task
1180 packages</em>. These are packages whose names begin with
1181 <em>task-</em>. Task packages should not be included in the
1186 <sect id="maintscripts">
1187 <heading>Maintainer Scripts</heading>
1190 The package installation scripts should avoid producing
1191 output which it is unnecessary for the user to see and
1192 should rely on <prgn>dpkg</prgn> to stave off boredom on
1193 the part of a user installing many packages. This means,
1194 amongst other things, using the <tt>--quiet</tt> option on
1195 <prgn>install-info</prgn>.
1199 Errors which occur during the execution of an installation
1200 script must be checked and the installation must not
1201 continue after an error.
1205 Note that in general <ref id="scripts"> applies to package
1206 maintainer scripts, too.
1210 You should not use <prgn>dpkg-divert</prgn> on a file
1211 belonging to another package without consulting the
1212 maintainer of that package first.
1216 All packages which supply an instance of a common command
1217 name (or, in general, filename) should generally use
1218 <prgn>update-alternatives</prgn>, so that they may be
1219 installed together. If <prgn>update-alternatives</prgn>
1220 is not used, then each package must use
1221 <tt>Conflicts</tt> to ensure that other packages are
1222 de-installed. (In this case, it may be appropriate to
1223 specify a conflict against earlier versions of something
1224 that previously did not use
1225 <prgn>update-alternatives</prgn>; this is an exception to
1226 the usual rule that versioned conflicts should be
1230 <sect1 id="maintscriptprompt">
1231 <heading>Prompting in maintainer scripts</heading>
1233 Package maintainer scripts may prompt the user if
1234 necessary. Prompting should be done by communicating
1235 through a program, such as <prgn>debconf</prgn>, which
1236 conforms to the Debian Configuration management
1237 specification, version 2 or higher. Prompting the user by
1238 other means, such as by hand<footnote>
1239 From the Jargon file: by hand 2. By extension,
1240 writing code which does something in an explicit or
1241 low-level way for which a presupplied library
1242 (<em>debconf, in this instance</em>) routine ought
1243 to have been available.
1244 </footnote>, is now deprecated.
1248 The Debian Configuration management specification is included
1249 in the <file>debconf_specification</file> files in the
1250 <package>debian-policy</package> package.
1251 It is also available from the Debian web mirrors at
1252 <tt><url name="/doc/packaging-manuals/debconf_specification.html"
1253 id="http://www.debian.org/doc/packaging-manuals/debconf_specification.html"></tt>
1254 and from the Debian archive mirrors at
1255 <tt><url name="/doc/package-developer/debconf_specification.txt.gz"
1256 id="http://ftp.debian.org/debian/doc/package-developer/debconf_specification.txt.gz"></tt>.
1260 Packages which use the Debian Configuration management
1261 specification may contain an additional
1262 <prgn>config</prgn> script and a <tt>templates</tt>
1263 file in their control archive<footnote>
1264 The control.tar.gz inside the .deb.
1265 See <manref name="deb" section="5">.
1267 The <prgn>config</prgn> script might be run before the
1268 <prgn>preinst</prgn> script, and before the package is unpacked
1269 or any of its dependencies or pre-dependancies are satisfied.
1270 Therefore it must work using only the tools present in
1271 <em>essential</em> packages.<footnote>
1272 <package>Debconf</package> or another tool that
1273 implements the Debian Configuration management
1274 specification will also be installed, and any
1275 versioned dependencies on it will be satisfied
1276 before preconfiguration begins.
1281 Packages should try to minimize the amount of prompting
1282 they need to do, and they should ensure that the user
1283 will only ever be asked each question once. This means
1284 that packages should try to use appropriate shared
1285 configuration files (such as <file>/etc/papersize</file> and
1286 <file>/etc/news/server</file>), and shared
1287 <package>debconf</package> variables rather than each
1288 prompting for their own list of required pieces of
1293 It also means that an upgrade should not ask the same
1294 questions again, unless the user has used
1295 <tt>dpkg --purge</tt> to remove the package's configuration.
1296 The answers to configuration questions should be stored in an
1297 appropriate place in <file>/etc</file> so that the user can
1298 modify them, and how this has been done should be
1303 If a package has a vitally important piece of
1304 information to pass to the user (such as "don't run me
1305 as I am, you must edit the following configuration files
1306 first or you risk your system emitting badly-formatted
1307 messages"), it should display this in the
1308 <prgn>config</prgn> or <prgn>postinst</prgn> script and
1309 prompt the user to hit return to acknowledge the
1310 message. Copyright messages do not count as vitally
1311 important (they belong in
1312 <file>/usr/share/doc/<var>package</var>/copyright</file>);
1313 neither do instructions on how to use a program (these
1314 should be in on-line documentation, where all the users
1319 Any necessary prompting should almost always be confined
1320 to the <prgn>config</prgn> or <prgn>postinst</prgn>
1321 script. If it is done in the <prgn>postinst</prgn>, it
1322 should be protected with a conditional so that
1323 unnecessary prompting doesn't happen if a package's
1324 installation fails and the <prgn>postinst</prgn> is
1325 called with <tt>abort-upgrade</tt>,
1326 <tt>abort-remove</tt> or <tt>abort-deconfigure</tt>.
1336 <heading>Source packages</heading>
1338 <sect id="standardsversion">
1339 <heading>Standards conformance</heading>
1342 Source packages should specify the most recent version number
1343 of this policy document with which your package complied
1344 when it was last updated.
1348 This information may be used to file bug reports
1349 automatically if your package becomes too much out of date.
1353 The version is specified in the <tt>Standards-Version</tt>
1355 The format of the <tt>Standards-Version</tt> field is
1356 described in <ref id="f-Standards-Version">.
1360 You should regularly, and especially if your package has
1361 become out of date, check for the newest Policy Manual
1362 available and update your package, if necessary. When your
1363 package complies with the new standards you should update the
1364 <tt>Standards-Version</tt> source package field and
1365 release it.<footnote>
1366 See the file <file>upgrading-checklist</file> for
1367 information about policy which has changed between
1368 different versions of this document.
1374 <sect id="pkg-relations">
1375 <heading>Package relationships</heading>
1378 Source packages should specify which binary packages they
1379 require to be installed or not to be installed in order to
1380 build correctly. For example, if building a package
1381 requires a certain compiler, then the compiler should be
1382 specified as a build-time dependency.
1386 It is not necessary to explicitly specify build-time
1387 relationships on a minimal set of packages that are always
1388 needed to compile, link and put in a Debian package a
1389 standard "Hello World!" program written in C or C++. The
1390 required packages are called <em>build-essential</em>, and
1391 an informational list can be found in
1392 <file>/usr/share/doc/build-essential/list</file> (which is
1393 contained in the <tt>build-essential</tt>
1396 <list compact="compact">
1398 This allows maintaining the list separately
1399 from the policy documents (the list does not
1400 need the kind of control that the policy
1404 Having a separate package allows one to install
1405 the build-essential packages on a machine, as
1406 well as allowing other packages such as tasks to
1407 require installation of the build-essential
1408 packages using the depends relation.
1411 The separate package allows bug reports against
1412 the list to be categorized separately from
1413 the policy management process in the BTS.
1420 When specifying the set of build-time dependencies, one
1421 should list only those packages explicitly required by the
1422 build. It is not necessary to list packages which are
1423 required merely because some other package in the list of
1424 build-time dependencies depends on them.<footnote>
1425 The reason for this is that dependencies change, and
1426 you should list all those packages, and <em>only</em>
1427 those packages that <em>you</em> need directly. What
1428 others need is their business. For example, if you
1429 only link against <file>libimlib</file>, you will need to
1430 build-depend on <package>libimlib2-dev</package> but
1431 not against any <tt>libjpeg*</tt> packages, even
1432 though <tt>libimlib2-dev</tt> currently depends on
1433 them: installation of <package>libimlib2-dev</package>
1434 will automatically ensure that all of its run-time
1435 dependencies are satisfied.
1440 If build-time dependencies are specified, it must be
1441 possible to build the package and produce working binaries
1442 on a system with only essential and build-essential
1443 packages installed and also those required to satisfy the
1444 build-time relationships (including any implied
1445 relationships). In particular, this means that version
1446 clauses should be used rigorously in build-time
1447 relationships so that one cannot produce bad or
1448 inconsistently configured packages when the relationships
1449 are properly satisfied.
1453 <ref id="relationships"> explains the technical details.
1458 <heading>Changes to the upstream sources</heading>
1461 If changes to the source code are made that are not
1462 specific to the needs of the Debian system, they should be
1463 sent to the upstream authors in whatever form they prefer
1464 so as to be included in the upstream version of the
1469 If you need to configure the package differently for
1470 Debian or for Linux, and the upstream source doesn't
1471 provide a way to do so, you should add such configuration
1472 facilities (for example, a new <prgn>autoconf</prgn> test
1473 or <tt>#define</tt>) and send the patch to the upstream
1474 authors, with the default set to the way they originally
1475 had it. You can then easily override the default in your
1476 <file>debian/rules</file> or wherever is appropriate.
1480 You should make sure that the <prgn>configure</prgn> utility
1481 detects the correct architecture specification string
1482 (refer to <ref id="arch-spec"> for details).
1486 If you need to edit a <prgn>Makefile</prgn> where
1487 GNU-style <prgn>configure</prgn> scripts are used, you
1488 should edit the <file>.in</file> files rather than editing the
1489 <prgn>Makefile</prgn> directly. This allows the user to
1490 reconfigure the package if necessary. You should
1491 <em>not</em> configure the package and edit the generated
1492 <prgn>Makefile</prgn>! This makes it impossible for
1493 someone else to later reconfigure the package.
1498 <sect id="dpkgchangelog">
1499 <heading>Debian changelog: <file>debian/changelog</file></heading>
1502 Changes in the Debian version of the package should be
1503 briefly explained in the Debian changelog file
1504 <file>debian/changelog</file>. This includes modifications
1505 made in the Debian package compared to the upstream one
1506 as well as other changes and updates to the package.
1508 Although there is nothing stopping an author who is also
1509 the Debian maintainer from using this changelog for all
1510 their changes, it will have to be renamed if the Debian
1511 and upstream maintainers become different people. In such
1512 a case, however, it might be better to maintain the package
1513 as a non-native package.
1518 Mistakes in changelogs are usually best rectified by making
1519 a new changelog entry rather than "rewriting history" by
1520 editing old changelog entries.
1524 The format of the <file>debian/changelog</file> allows the
1525 package building tools to discover which version of the package
1526 is being built and find out other release-specific information.
1530 That format is a series of entries like this:
1532 <example compact="compact">
1533 <var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
1535 [optional blank line(s), stripped]
1537 * <var>change details</var>
1538 <var>more change details</var>
1540 [blank line(s), included in output of dpkg-parsechangelog]
1542 * <var>even more change details</var>
1544 [optional blank line(s), stripped]
1546 -- <var>maintainer name</var> <<var>email address</var>><var>[two spaces]</var> <var>date</var>
1551 <var>package</var> and <var>version</var> are the source
1552 package name and version number.
1556 <var>distribution(s)</var> lists the distributions where
1557 this version should be installed when it is uploaded - it
1558 is copied to the <tt>Distribution</tt> field in the
1559 <file>.changes</file> file. See <ref id="f-Distribution">.
1563 <var>urgency</var> is the value for the <tt>Urgency</tt>
1564 field in the <file>.changes</file> file for the upload
1565 (see <ref id="f-Urgency">). It is not possible to specify
1566 an urgency containing commas; commas are used to separate
1567 <tt><var>keyword</var>=<var>value</var></tt> settings in the
1568 <prgn>dpkg</prgn> changelog format (though there is
1569 currently only one useful <var>keyword</var>,
1570 <tt>urgency</tt>).<footnote>
1571 Recognised urgency values are <tt>low</tt>,
1572 <tt>medium</tt>, <tt>high</tt> and <tt>emergency</tt>.
1573 They have an effect on how quickly a package will be
1574 considered for inclusion into the <tt>testing</tt>
1575 distribution, and give an indication of the importance
1576 of any fixes included in this upload.
1581 The change details may in fact be any series of lines
1582 starting with at least two spaces, but conventionally each
1583 change starts with an asterisk and a separating space and
1584 continuation lines are indented so as to bring them in
1585 line with the start of the text above. Blank lines may be
1586 used here to separate groups of changes, if desired.
1590 If this upload resolves bugs recorded in the Bug Tracking
1591 System (BTS), they may be automatically closed on the
1592 inclusion of this package into the Debian archive by
1593 including the string: <tt>closes: Bug#<var>nnnnn</var></tt>
1594 in the change details.<footnote>
1595 To be precise, the string should match the following
1596 Perl regular expression:
1598 /closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i
1600 Then all of the bug numbers listed will be closed by the
1601 archive maintenance script (<prgn>katie</prgn>), or in
1602 the case of an NMU, marked as fixed.
1604 This information is conveyed via the <tt>Closes</tt> field
1605 in the <tt>.changes</tt> file (see <ref id="f-Closes">).
1609 The maintainer name and email address used in the changelog
1610 should be the details of the person uploading <em>this</em>
1611 version. They are <em>not</em> necessarily those of the
1612 usual package maintainer. The information here will be
1613 copied to the <tt>Changed-By</tt> field in the
1614 <tt>.changes</tt> file (see <ref id="f-Changed-By">),
1615 and then later used to send an acknowledgement when the
1616 upload has been installed.
1620 The <var>date</var> should be in RFC822 format<footnote>
1621 This is generated by the <prgn>822-date</prgn>
1623 </footnote>; it should include the time zone specified
1624 numerically, with the time zone name or abbreviation
1625 optionally present as a comment in parentheses.
1629 The first "title" line with the package name should start
1630 at the left hand margin; the "trailer" line with the
1631 maintainer and date details should be preceded by exactly
1632 one space. The maintainer details and the date must be
1633 separated by exactly two spaces.
1637 For more information on placement of the changelog files
1638 within binary packages, please see <ref id="changelogs">.
1641 <sect1><heading>Alternative changelog formats</heading>
1644 In non-experimental packages you must use a format for
1645 <file>debian/changelog</file> which is supported by the most
1646 recent released version of <prgn>dpkg</prgn>.
1650 It is possible to use a format different from the standard
1651 one by providing a changelog parser for the format you wish
1652 to use. The parser must have an API compatible with that
1653 expected by <prgn>dpkg-genchanges</prgn> and
1654 <prgn>dpkg-gencontrol</prgn>, and it must not interact with
1657 If there is general interest in the new format, you should
1658 contact the <package>dpkg</package> maintainer to have the
1659 parser script for it included in the <prgn>dpkg</prgn>
1660 package. (You will need to agree that the parser and its
1661 manpage may be distributed under the GNU GPL, just as the rest
1662 of <prgn>dpkg</prgn> is.)
1669 <heading>Error trapping in makefiles</heading>
1672 When <prgn>make</prgn> invokes a command in a makefile
1673 (including your package's upstream makefiles and
1674 <file>debian/rules</file>), it does so using <prgn>sh</prgn>. This
1675 means that <prgn>sh</prgn>'s usual bad error handling
1676 properties apply: if you include a miniature script as one
1677 of the commands in your makefile you'll find that if you
1678 don't do anything about it then errors are not detected
1679 and <prgn>make</prgn> will blithely continue after
1684 Every time you put more than one shell command (this
1685 includes using a loop) in a makefile command you
1686 must make sure that errors are trapped. For
1687 simple compound commands, such as changing directory and
1688 then running a program, using <tt>&&</tt> rather
1689 than semicolon as a command separator is sufficient. For
1690 more complex commands including most loops and
1691 conditionals you should include a separate <tt>set -e</tt>
1692 command at the start of every makefile command that's
1693 actually one of these miniature shell scripts.
1697 <sect id="timestamps">
1698 <heading>Time Stamps</heading>
1700 Maintainers should preserve the modification times of the
1701 upstream source files in a package, as far as is reasonably
1703 The rationale is that there is some information conveyed
1704 by knowing the age of the file, for example, you could
1705 recognize that some documentation is very old by looking
1706 at the modification time, so it would be nice if the
1707 modification time of the upstream source would be
1713 <sect id="restrictions">
1714 <heading>Restrictions on objects in source packages</heading>
1717 The source package may not contain any hard links<footnote>
1719 This is not currently detected when building source
1720 packages, but only when extracting
1724 Hard links may be permitted at some point in the
1725 future, but would require a fair amount of
1728 </footnote>, device special files, sockets or setuid or
1729 setgid files.<footnote>
1730 Setgid directories are allowed.
1735 <sect id="debianrules">
1736 <heading>Main building script: <file>debian/rules</file></heading>
1739 This file must be an executable makefile, and contains the
1740 package-specific recipes for compiling the package and
1741 building binary package(s) from the source.
1745 It must start with the line <tt>#!/usr/bin/make -f</tt>,
1746 so that it can be invoked by saying its name rather than
1747 invoking <prgn>make</prgn> explicitly.
1751 Since an interactive <file>debian/rules</file> script makes it
1752 impossible to auto-compile that package and also makes it
1753 hard for other people to reproduce the same binary
1754 package, all <em>required targets</em> MUST be
1755 non-interactive. At a minimum, required targets are the
1756 ones called by <prgn>dpkg-buildpackage</prgn>, namely,
1757 <em>clean</em>, <em>binary</em>, <em>binary-arch</em>,
1758 <em>binary-indep</em>, and <em>build</em>. It also follows
1759 that any target that these targets depend on must also be
1764 The targets are as follows (required unless stated otherwise):
1766 <tag><tt>build</tt></tag>
1769 The <tt>build</tt> target should perform all the
1770 configuration and compilation of the package.
1771 If a package has an interactive pre-build
1772 configuration routine, the Debianized source package
1773 must either be built after this has taken place (so
1774 that the binary package can be built without rerunning
1775 the configuration) or the configuration routine
1776 modified to become non-interactive. (The latter is
1777 preferable if there are architecture-specific features
1778 detected by the configuration routine.)
1782 For some packages, notably ones where the same
1783 source tree is compiled in different ways to produce
1784 two binary packages, the <tt>build</tt> target
1785 does not make much sense. For these packages it is
1786 good enough to provide two (or more) targets
1787 (<tt>build-a</tt> and <tt>build-b</tt> or whatever)
1788 for each of the ways of building the package, and a
1789 <tt>build</tt> target that does nothing. The
1790 <tt>binary</tt> target will have to build the
1791 package in each of the possible ways and make the
1792 binary package out of each.
1796 The <tt>build</tt> target must not do anything
1797 that might require root privilege.
1801 The <tt>build</tt> target may need to run the
1802 <tt>clean</tt> target first - see below.
1806 When a package has a configuration and build routine
1807 which takes a long time, or when the makefiles are
1808 poorly designed, or when <tt>build</tt> needs to
1809 run <tt>clean</tt> first, it is a good idea to
1810 <tt>touch build</tt> when the build process is
1811 complete. This will ensure that if <tt>debian/rules
1812 build</tt> is run again it will not rebuild the whole
1814 Another common way to do this is for <tt>build</tt>
1815 to depend on <prgn>build-stamp</prgn> and to do
1816 nothing else, and for the <prgn>build-stamp</prgn>
1817 target to do the building and to <tt>touch
1818 build-stamp</tt> on completion. This is
1819 especially useful if the build routine creates a
1820 file or directory called <tt>build</tt>; in such a
1821 case, <tt>build</tt> will need to be listed as
1822 a phony target (i.e., as a dependency of the
1823 <tt>.PHONY</tt> target). See the documentation of
1824 <prgn>make</prgn> for more information on phony
1830 <tag><tt>build-arch</tt> (optional),
1831 <tt>build-indep</tt> (optional)
1835 A package may also provide both of the targets
1836 <tt>build-arch</tt> and <tt>build-indep</tt>.
1837 The <tt>build-arch</tt> target, if provided, should
1838 perform all the configuration and compilation required
1839 for producing all architecture-dependant binary packages
1840 (those packages for which the body of the
1841 <tt>Architecture</tt> field in <tt>debian/control</tt>
1842 is not <tt>all</tt>).
1843 Similarly, the <tt>build-indep</tt> target, if
1844 provided, should perform all the configuration and
1845 compilation required for producing all
1846 architecture-independent binary packages
1847 (those packages for which the body of the
1848 <tt>Architecture</tt> field in <tt>debian/control</tt>
1850 The <tt>build</tt> target should depend on those of the
1851 targets <tt>build-arch</tt> and <tt>build-indep</tt> that
1852 are provided in the rules file.
1856 If one or both of the targets <tt>build-arch</tt> and
1857 <tt>build-indep</tt> are not provided, then invoking
1858 <file>debian/rules</file> with one of the not-provided
1859 targets as arguments should produce a exit status code
1860 of 2. Usually this is provided automatically by make
1861 if the target is missing.
1865 The <tt>build-arch</tt> and <tt>build-indep</tt> targets
1866 must not do anything that might require root privilege.
1870 <tag><tt>binary</tt>, <tt>binary-arch</tt>,
1871 <tt>binary-indep</tt>
1875 The <tt>binary</tt> target must be all that is
1876 necessary for the user to build the binary package(s)
1877 produced from this source package. It is
1878 split into two parts: <prgn>binary-arch</prgn> builds
1879 the binary packages which are specific to a particular
1880 architecture, and <tt>binary-indep</tt> builds
1881 those which are not.
1884 <tt>binary</tt> may be (and commonly is) a target with
1885 no commands which simply depends on
1886 <tt>binary-arch</tt> and <tt>binary-indep</tt>.
1889 Both <tt>binary-*</tt> targets should depend on the
1890 <tt>build</tt> target, or on the appropriate
1891 <tt>build-arch</tt> or <tt>build-indep</tt> target, if
1892 provided, so that the package is built if it has not
1893 been already. It should then create the relevant
1894 binary package(s), using <prgn>dpkg-gencontrol</prgn> to
1895 make their control files and <prgn>dpkg-deb</prgn> to
1896 build them and place them in the parent of the top
1901 Both the <tt>binary-arch</tt> and
1902 <tt>binary-indep</tt> targets <em>must</em> exist.
1903 If one of them has nothing to do (which will always be
1904 the case if the source generates only a single binary
1905 package, whether architecture-dependent or not), it
1906 must still exist and must always succeed.
1910 The <tt>binary</tt> targets must be invoked as
1912 The <prgn>fakeroot</prgn> package often allows one
1913 to build a package correctly even without being
1919 <tag><tt>clean</tt></tag>
1922 This must undo any effects that the <tt>build</tt>
1923 and <tt>binary</tt> targets may have had, except
1924 that it should leave alone any output files created in
1925 the parent directory by a run of a <tt>binary</tt>
1930 If a <tt>build</tt> file is touched at the end of
1931 the <tt>build</tt> target, as suggested above, it
1932 should be removed as the first action that
1933 <tt>clean</tt> performs, so that running
1934 <tt>build</tt> again after an interrupted
1935 <tt>clean</tt> doesn't think that everything is
1940 The <tt>clean</tt> target may need to be
1941 invoked as root if <tt>binary</tt> has been
1942 invoked since the last <tt>clean</tt>, or if
1943 <tt>build</tt> has been invoked as root (since
1944 <tt>build</tt> may create directories, for
1949 <tag><tt>get-orig-source</tt> (optional)</tag>
1952 This target fetches the most recent version of the
1953 original source package from a canonical archive site
1954 (via FTP or WWW, for example), does any necessary
1955 rearrangement to turn it into the original source
1956 tar file format described below, and leaves it in the
1961 This target may be invoked in any directory, and
1962 should take care to clean up any temporary files it
1967 This target is optional, but providing it if
1968 possible is a good idea.
1974 The <tt>build</tt>, <tt>binary</tt> and
1975 <tt>clean</tt> targets must be invoked with the current
1976 directory being the package's top-level directory.
1981 Additional targets may exist in <file>debian/rules</file>,
1982 either as published or undocumented interfaces or for the
1983 package's internal use.
1987 The architectures we build on and build for are determined
1988 by <prgn>make</prgn> variables using the utility
1989 <qref id="pkg-dpkg-architecture"><prgn>dpkg-architecture</prgn></qref>.
1990 You can determine the
1991 Debian architecture and the GNU style architecture
1992 specification string for the build machine (the machine type
1993 we are building on) as well as for the host machine (the
1994 machine type we are building for). Here is a list of
1995 supported <prgn>make</prgn> variables:
1996 <list compact="compact">
1998 <tt>DEB_*_ARCH</tt> (the Debian architecture)
2001 <tt>DEB_*_GNU_TYPE</tt> (the GNU style architecture
2002 specification string)
2005 <tt>DEB_*_GNU_CPU</tt> (the CPU part of
2006 <tt>DEB_*_GNU_TYPE</tt>)
2009 <tt>DEB_*_GNU_SYSTEM</tt> (the System part of
2010 <tt>DEB_*_GNU_TYPE</tt>)
2012 where <tt>*</tt> is either <tt>BUILD</tt> for specification of
2013 the build machine or <tt>HOST</tt> for specification of the
2018 Backward compatibility can be provided in the rules file
2019 by setting the needed variables to suitable default
2020 values; please refer to the documentation of
2021 <prgn>dpkg-architecture</prgn> for details.
2025 It is important to understand that the <tt>DEB_*_ARCH</tt>
2026 string only determines which Debian architecture we are
2027 building on or for. It should not be used to get the CPU
2028 or system information; the GNU style variables should be
2033 <!-- FIXME: section pkg-srcsubstvars is the same as substvars -->
2034 <sect id="substvars">
2035 <heading>Variable substitutions: <file>debian/substvars</file></heading>
2038 When <prgn>dpkg-gencontrol</prgn>,
2039 <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
2040 generate control files they perform variable substitutions
2041 on their output just before writing it. Variable
2042 substitutions have the form <tt>${<var>variable</var>}</tt>.
2043 The optional file <file>debian/substvars</file> contains
2044 variable substitutions to be used; variables can also be set
2045 directly from <file>debian/rules</file> using the <tt>-V</tt>
2046 option to the source packaging commands, and certain
2047 predefined variables are also available.
2051 The <file>debian/substvars</file> file is usually generated and
2052 modified dynamically by <file>debian/rules</file> targets, in
2053 which case it must be removed by the <tt>clean</tt> target.
2057 See <manref name="dpkg-source" section="1"> for full
2058 details about source variable substitutions, including the
2059 format of <file>debian/substvars</file>.</p>
2062 <sect id="debianfiles">
2063 <heading>Generated files list: <file>debian/files</file></heading>
2066 This file is not a permanent part of the source tree; it
2067 is used while building packages to record which files are
2068 being generated. <prgn>dpkg-genchanges</prgn> uses it
2069 when it generates a <file>.changes</file> file.
2073 It should not exist in a shipped source package, and so it
2074 (and any backup files or temporary files such as
2075 <file>files.new</file><footnote>
2076 <file>files.new</file> is used as a temporary file by
2077 <prgn>dpkg-gencontrol</prgn> and
2078 <prgn>dpkg-distaddfile</prgn> - they write a new
2079 version of <tt>files</tt> here before renaming it,
2080 to avoid leaving a corrupted copy if an error
2082 </footnote>) should be removed by the
2083 <tt>clean</tt> target. It may also be wise to
2084 ensure a fresh start by emptying or removing it at the
2085 start of the <tt>binary</tt> target.
2089 When <prgn>dpkg-gencontrol</prgn> is run for a binary
2090 package, it adds an entry to <file>debian/files</file> for the
2091 <file>.deb</file> file that will be created when <tt>dpkg-deb
2092 --build</tt> is run for that binary package. So for most
2093 packages all that needs to be done with this file is to
2094 delete it in the <tt>clean</tt> target.
2098 If a package upload includes files besides the source
2099 package and any binary packages whose control files were
2100 made with <prgn>dpkg-gencontrol</prgn> then they should be
2101 placed in the parent of the package's top-level directory
2102 and <prgn>dpkg-distaddfile</prgn> should be called to add
2103 the file to the list in <file>debian/files</file>.</p>
2109 <chapt id="controlfields">
2110 <heading>Control files and their fields</heading>
2113 The package management system manipulates data represented in
2114 a common format, known as <em>control data</em>, stored in
2115 <em>control files</em>.
2116 Control files are used for source packages, binary packages and
2117 the <file>.changes</file> files which control the installation
2118 of uploaded files<footnote>
2119 <prgn>dpkg</prgn>'s internal databases are in a similar
2124 <sect id="controlsyntax">
2125 <heading>Syntax of control files</heading>
2128 A control file consists of one or more paragraphs of
2130 The paragraphs are also sometimes referred to as stanzas.
2132 The paragraphs are separated by blank lines. Some control
2133 files allow only one paragraph; others allow several, in
2134 which case each paragraph usually refers to a different
2135 package. (For example, in source packages, the first
2136 paragraph refers to the source package, and later paragraphs
2137 refer to binary packages generated from the source.)
2141 Each paragraph consists of a series of data fields; each
2142 field consists of the field name, followed by a colon and
2143 then the data/value associated with that field. It ends at
2144 the end of the line. Horizontal whitespace (spaces and
2145 tabs) may occur immediately before or after the value and is
2146 ignored there; it is conventional to put a single space
2147 after the colon. For example, a field might be:
2148 <example compact="compact">
2151 the field name is <tt>Package</tt> and the field value
2156 Some fields' values may span several lines; in this case
2157 each continuation line must start with a space or a tab.
2158 Any trailing spaces or tabs at the end of individual
2159 lines of a field value are ignored.
2163 Except where otherwise stated, only a single line of data is
2164 allowed and whitespace is not significant in a field body.
2165 Whitespace must not appear inside names (of packages,
2166 architectures, files or anything else) or version numbers,
2167 or between the characters of multi-character version
2172 Field names are not case-sensitive, but it is usual to
2173 capitalize the field names using mixed case as shown below.
2177 Blank lines, or lines consisting only of spaces and tabs,
2178 are not allowed within field values or between fields - that
2179 would mean a new paragraph.
2184 <sect id="sourcecontrolfiles">
2185 <heading>Source package control files -- <file>debian/control</file></heading>
2188 The <file>debian/control</file> file contains the most vital
2189 (and version-independent) information about the source package
2190 and about the binary packages it creates.
2194 The first paragraph of the control file contains information about
2195 the source package in general. The subsequent sets each describe a
2196 binary package that the source tree builds.
2200 The fields in the general paragraph (the first one, for the source
2203 <list compact="compact">
2204 <item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
2205 <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
2206 <item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
2207 <item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
2208 <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
2209 <item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
2214 The fields in the binary package paragraphs are:
2216 <list compact="compact">
2217 <item><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</item>
2218 <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (mandatory)</item>
2219 <item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
2220 <item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
2221 <item><qref id="f-Essential"><tt>Essential</tt></qref></item>
2222 <item><qref id="binarydeps"><tt>Depends</tt> et al</qref></item>
2223 <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
2228 The syntax and semantics of the fields are described below.
2234 These fields are used by <prgn>dpkg-gencontrol</prgn> to
2235 generate control files for binary packages (see below), by
2236 <prgn>dpkg-genchanges</prgn> to generate the
2237 <tt>.changes</tt> file to accompany the upload, and by
2238 <prgn>dpkg-source</prgn> when it creates the <file>.dsc</file>
2239 source control file as part of a source archive.
2243 The fields here may contain variable references - their
2244 values will be substituted by <prgn>dpkg-gencontrol</prgn>,
2245 <prgn>dpkg-genchanges</prgn> or <prgn>dpkg-source</prgn>
2246 when they generate output control files.
2247 See <ref id="substvars"> for details.
2252 <sect id="binarycontrolfiles">
2253 <heading>Binary package control files -- <file>DEBIAN/control</file></heading>
2256 The <file>DEBIAN/control</file> file contains the most vital
2257 (and version-dependent) information about a binary package.
2261 The fields in this file are:
2263 <list compact="compact">
2264 <item><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</item>
2265 <item><qref id="f-Source"><tt>Source</tt></qref></item>
2266 <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
2267 <item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
2268 <item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
2269 <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (mandatory)</item>
2270 <item><qref id="f-Essential"><tt>Essential</tt></qref></item>
2271 <item><qref id="binarydeps"><tt>Depends</tt> et al</qref></item>
2272 <item><qref id="f-Installed-Size"><tt>Installed-Size</tt></qref></item>
2273 <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
2274 <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
2279 <sect id="debiansourcecontrolfiles">
2280 <heading>Debian source control files -- <tt>.dsc</tt></heading>
2283 This file contains a series of fields, identified and
2284 separated just like the fields in the control file of
2285 a binary package. The fields are listed below; their
2286 syntax is described above, in <ref id="pkg-controlfields">.
2288 <list compact="compact">
2289 <item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
2290 <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
2291 <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
2292 <item><qref id="f-Binary"><tt>Binary</tt></qref></item>
2293 <item><qref id="f-Architecture"><tt>Architecture</tt></qref></item>
2294 <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
2295 <item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
2296 <item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
2301 The source package control file is generated by
2302 <prgn>dpkg-source</prgn> when it builds the source
2303 archive, from other files in the source package,
2304 described above. When unpacking, it is checked against
2305 the files and directories in the other parts of the
2311 <sect id="debianchangesfiles">
2312 <heading>Debian changes files -- <file>.changes</file></heading>
2315 The .changes files are used by the Debian archive maintenance
2316 software to process updates to packages. They contain one
2317 paragraph which contains information from the
2318 <tt>debian/control</tt> file and other data about the
2319 source package gathered via <tt>debian/changelog</tt>
2320 and <tt>debian/rules</tt>.
2324 The fields in this file are:
2326 <list compact="compact">
2327 <item><qref id="f-Format"><tt>Format</tt></qref> (mandatory)</item>
2328 <item><qref id="f-Date"><tt>Date</tt></qref> (mandatory)</item>
2329 <item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
2330 <item><qref id="f-Binary"><tt>Binary</tt></qref> (mandatory)</item>
2331 <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (mandatory)</item>
2332 <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
2333 <item><qref id="f-Distribution"><tt>Distribution</tt></qref> (mandatory)</item>
2334 <item><qref id="f-Urgency"><tt>Urgency</tt></qref> (recommended)</item>
2335 <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
2336 <item><qref id="f-Changed-By"><tt>Changed-By</tt></qref></item>
2337 <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
2338 <item><qref id="f-Closes"><tt>Closes</tt></qref></item>
2339 <item><qref id="f-Changes"><tt>Changes</tt></qref> (mandatory)</item>
2340 <item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
2345 <sect id="controlfieldslist">
2346 <heading>List of fields</heading>
2348 <sect1 id="f-Source">
2349 <heading><tt>Source</tt></heading>
2352 This field identifies the source package name.
2356 In a main source control information, a <file>.changes</file>
2357 or a <file>.dsc</file> file this may contain only the name
2358 of the source package.
2362 In the control file of a binary package it may be followed
2363 by a version number in parentheses<footnote>
2364 It is customary to leave a space after the package name
2365 if a version number is specified.
2367 This version number may be omitted (and is, by
2368 <prgn>dpkg-gencontrol</prgn>) if it has the same value as
2369 the <tt>Version</tt> field of the binary package in
2370 question. The field itself may be omitted from a binary
2371 package control file when the source package has the same
2372 name and version as the binary package.
2376 <sect1 id="f-Maintainer">
2377 <heading><tt>Maintainer</tt></heading>
2380 The package maintainer's name and email address. The name
2381 should come first, then the email address inside angle
2382 brackets <tt><></tt> (in RFC822 format).
2386 If the maintainer's name contains a full stop then the
2387 whole field will not work directly as an email address due
2388 to a misfeature in the syntax specified in RFC822; a
2389 program using this field as an address must check for this
2390 and correct the problem if necessary (for example by
2391 putting the name in round brackets and moving it to the
2392 end, and bringing the email address forward).
2396 <sect1 id="f-Changed-By">
2397 <heading><tt>Changed-By</tt></heading>
2400 The name and email address of the person who changed the
2401 said package. Usually the name of the maintainer.
2402 All the rules for the Maintainer field apply here, too.
2406 <sect1 id="f-Section">
2407 <heading><tt>Section</tt></heading>
2410 This field specifies an application area into which the package
2411 has been classified. See <ref id="subsections">.
2415 When it appears in the <file>debian/control</file> file,
2416 it gives the value for the subfield of the same name in
2417 the <tt>Files</tt> field of the <file>.changes</file> file.
2418 It also gives the default for the same field in the binary
2423 By default, <prgn>dpkg-gencontrol</prgn> does not include this
2424 field in the control file of a binary package - use the
2425 <tt>-is</tt> (or <tt>-isp</tt>) options to achieve this effect.
2429 <sect1 id="f-Priority">
2430 <heading><tt>Priority</tt></heading>
2433 This field represents how important that it is that the user
2434 have the package installed. See <ref id="priorities">.
2438 When it appears in the <file>debian/control</file> file,
2439 it gives the value for the subfield of the same name in
2440 the <tt>Files</tt> field of the <file>.changes</file> file.
2441 It also gives the default for the same field in the binary
2446 By default, <prgn>dpkg-gencontrol</prgn> does not include this
2447 field in the control file of a binary package - use the
2448 <tt>-ip</tt> (or <tt>-isp</tt>) options to achieve this effect.
2452 <sect1 id="f-Package">
2453 <heading><tt>Package</tt></heading>
2456 The name of the binary package.
2460 Package names must consist only of lower case letters
2461 (<tt>a-z</tt>), digits (<tt>0-9</tt>), plus (<tt>+</tt>)
2462 and minus (<tt>-</tt>) signs, and periods (<tt>.</tt>).
2463 They must be at least two characters long and must start
2464 with an alphanumeric character.
2468 <sect1 id="f-Architecture">
2469 <heading><tt>Architecture</tt></heading>
2472 Depending on context and the control file used, the
2473 <tt>Architecture</tt> field can include the following sets of
2476 <item>A unique single word identifying a Debian machine
2477 architecture, see <ref id="arch-spec">.
2478 <item><tt>all</tt>, which indicates an
2479 architecture-independent package.
2480 <item><tt>any</tt>, which indicates a package available
2481 for building on any architecture.
2482 <item><tt>source</tt>, which indicates a source package.
2487 In the main <file>debian/control</file> file in the source
2488 package, or in the source package control file
2489 <file>.dsc</file>, one may specify a list of architectures
2490 separated by spaces, or the special values <tt>any</tt> or
2495 Specifying <tt>any</tt> indicates that the source package
2496 isn't dependent on any particular architecture and should
2497 compile fine on any one. The produced binary package(s)
2498 will be specific to whatever the current build architecture
2500 This is the most often used setting, and is recommended
2501 for new packages that aren't <tt>Architecture: all</tt>.
2506 Specifying a list of architectures indicates that the source
2507 will build an architecture-dependent package, and will only
2508 work correctly on the listed architectures.<footnote>
2509 This is a setting used for a minority of cases where the
2510 program is not portable. Generally, it should not be used
2516 In a <file>.changes</file> file, the <tt>Architecture</tt>
2517 field lists the architecture(s) of the package(s)
2518 currently being uploaded. This will be a list; if the
2519 source for the package is also being uploaded, the special
2520 entry <tt>source</tt> is also present.
2524 See <ref id="debianrules"> for information how to get the
2525 architecture for the build process.
2529 <sect1 id="f-Essential">
2530 <heading><tt>Essential</tt></heading>
2533 This is a boolean field which may occur only in the
2534 control file of a binary package or in a per-package fields
2535 paragraph of a main source control data file.
2539 If set to <tt>yes</tt> then the package management system
2540 will refuse to remove the package (upgrading and replacing
2541 it is still possible). The other possible value is <tt>no</tt>,
2542 which is the same as not having the field at all.
2547 <heading>Package interrelationship fields:
2548 <tt>Depends</tt>, <tt>Pre-Depends</tt>,
2549 <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Conflicts</tt>,
2550 <tt>Provides</tt>, <tt>Replaces</tt>
2554 These fields describe the package's relationships with
2555 other packages. Their syntax and semantics are described
2556 in <ref id="relationships">.</p>
2559 <sect1 id="f-Standards-Version">
2560 <heading><tt>Standards-Version</tt></heading>
2563 The most recent version of the standards (the policy
2564 manual and associated texts) with which the package
2569 The version number has four components: major and minor
2570 version number and major and minor patch level. When the
2571 standards change in a way that requires every package to
2572 change the major number will be changed. Significant
2573 changes that will require work in many packages will be
2574 signaled by a change to the minor number. The major patch
2575 level will be changed for any change to the meaning of the
2576 standards, however small; the minor patch level will be
2577 changed when only cosmetic, typographical or other edits
2578 are made which neither change the meaning of the document
2579 nor affect the contents of packages.
2583 Thus only the first three components of the policy version
2584 are significant in the <em>Standards-Version</em> control
2585 field, and so either these three components or the all
2586 four components may be specified.<footnote>
2587 In the past, people specified the full version number
2588 in the Standards-Version field, for example "2.3.0.0".
2589 Since minor patch-level changes don't introduce new
2590 policy, it was thought it would be better to relax
2591 policy and only require the first 3 components to be
2592 specified, in this example "2.3.0". All four
2593 components may still be used if someone wishes to do so.
2599 <sect1 id="f-Version">
2600 <heading><tt>Version</tt></heading>
2603 The version number of a package. The format is:
2604 [<var>epoch</var><tt>:</tt>]<var>upstream_version</var>[<tt>-</tt><var>debian_revision</var>]
2608 The three components here are:
2610 <tag><var>epoch</var></tag>
2613 This is a single (generally small) unsigned integer. It
2614 may be omitted, in which case zero is assumed. If it is
2615 omitted then the <var>upstream_version</var> may not
2620 It is provided to allow mistakes in the version numbers
2621 of older versions of a package, and also a package's
2622 previous version numbering schemes, to be left behind.
2626 <tag><var>upstream_version</var></tag>
2629 This is the main part of the version number. It is
2630 usually the version number of the original ("upstream")
2631 package from which the <file>.deb</file> file has been made,
2632 if this is applicable. Usually this will be in the same
2633 format as that specified by the upstream author(s);
2634 however, it may need to be reformatted to fit into the
2635 package management system's format and comparison
2640 The comparison behavior of the package management system
2641 with respect to the <var>upstream_version</var> is
2642 described below. The <var>upstream_version</var>
2643 portion of the version number is mandatory.
2647 The <var>upstream_version</var> may contain only
2648 alphanumerics<footnote>
2649 Alphanumerics are <tt>A-Za-z0-9</tt> only.
2651 and the characters <tt>.</tt> <tt>+</tt> <tt>-</tt>
2652 <tt>:</tt> (full stop, plus, hyphen, colon) and should
2653 start with a digit. If there is no
2654 <var>debian_revision</var> then hyphens are not allowed;
2655 if there is no <var>epoch</var> then colons are not
2660 <tag><var>debian_revision</var></tag>
2663 This part of the version number specifies the version of
2664 the Debian package based on the upstream version. It
2665 may contain only alphanumerics and the characters
2666 <tt>+</tt> and <tt>.</tt> (plus and full stop) and is
2667 compared in the same way as the
2668 <var>upstream_version</var> is.
2672 It is optional; if it isn't present then the
2673 <var>upstream_version</var> may not contain a hyphen.
2674 This format represents the case where a piece of
2675 software was written specifically to be turned into a
2676 Debian package, and so there is only one "debianization"
2677 of it and therefore no revision indication is required.
2681 It is conventional to restart the
2682 <var>debian_revision</var> at <tt>1</tt> each time the
2683 <var>upstream_version</var> is increased.
2687 The package management system will break the version
2688 number apart at the last hyphen in the string (if there
2689 is one) to determine the <var>upstream_version</var> and
2690 <var>debian_revision</var>. The absence of a
2691 <var>debian_revision</var> compares earlier than the
2692 presence of one (but note that the
2693 <var>debian_revision</var> is the least significant part
2694 of the version number).
2701 The <var>upstream_version</var> and <var>debian_revision</var>
2702 parts are compared by the package management system using the
2707 The strings are compared from left to right.
2711 First the initial part of each string consisting entirely of
2712 non-digit characters is determined. These two parts (one of
2713 which may be empty) are compared lexically. If a difference
2714 is found it is returned. The lexical comparison is a
2715 comparison of ASCII values modified so that all the letters
2716 sort earlier than all the non-letters.
2720 Then the initial part of the remainder of each string which
2721 consists entirely of digit characters is determined. The
2722 numerical values of these two parts are compared, and any
2723 difference found is returned as the result of the comparison.
2724 For these purposes an empty string (which can only occur at
2725 the end of one or both version strings being compared) counts
2730 These two steps (comparing and removing initial non-digit
2731 strings and initial digit strings) are repeated until a
2732 difference is found or both strings are exhausted.
2736 Note that the purpose of epochs is to allow us to leave behind
2737 mistakes in version numbering, and to cope with situations
2738 where the version numbering scheme changes. It is
2739 <em>not</em> intended to cope with version numbers containing
2740 strings of letters which the package management system cannot
2741 interpret (such as <tt>ALPHA</tt> or <tt>pre-</tt>), or with
2742 silly orderings (the author of this manual has heard of a
2743 package whose versions went <tt>1.1</tt>, <tt>1.2</tt>,
2744 <tt>1.3</tt>, <tt>1</tt>, <tt>2.1</tt>, <tt>2.2</tt>,
2745 <tt>2</tt> and so forth).
2749 <sect1 id="f-Description">
2750 <heading><tt>Description</tt></heading>
2753 In a source or binary control file, the <tt>Description</tt>
2754 field contains a description of the binary package, consisting
2755 of two parts, the synopsis or the short description, and the
2756 long description. The field's format is as follows:
2761 Description: <single line synopsis>
2762 <extended description over several lines>
2767 The lines in the extended description can have these formats:
2773 Those starting with a single space are part of a paragraph.
2774 Successive lines of this form will be word-wrapped when
2775 displayed. The leading space will usually be stripped off.
2779 Those starting with two or more spaces. These will be
2780 displayed verbatim. If the display cannot be panned
2781 horizontally, the displaying program will linewrap them "hard"
2782 (i.e., without taking account of word breaks). If it can they
2783 will be allowed to trail off to the right. None, one or two
2784 initial spaces may be deleted, but the number of spaces
2785 deleted from each line will be the same (so that you can have
2786 indenting work correctly, for example).
2790 Those containing a single space followed by a single full stop
2791 character. These are rendered as blank lines. This is the
2792 <em>only</em> way to get a blank line<footnote>
2793 Completely empty lines will not be rendered as blank lines.
2794 Instead, they will cause the parser to think you're starting
2795 a whole new record in the control file, and will therefore
2796 likely abort with an error.
2801 Those containing a space, a full stop and some more characters.
2802 These are for future expansion. Do not use them.
2808 Do not use tab characters. Their effect is not predictable.
2812 See <ref id="descriptions"> for further information on this.
2816 In a <file>.changes</file> file, the <tt>Description</tt> field
2817 contains a summary of the descriptions for the packages being
2822 The part of the field before the first newline is empty;
2823 thereafter each line has the name of a binary package and
2824 the summary description line from that binary package.
2825 Each line is indented by one space.
2830 <sect1 id="f-Distribution">
2831 <heading><tt>Distribution</tt></heading>
2834 In a <file>.changes</file> file or parsed changelog output
2835 this contains the (space-separated) name(s) of the
2836 distribution(s) where this version of the package should
2837 be installed. Valid distributions are determined by the
2838 archive maintainers.<footnote>
2839 Current distribution names are:
2840 <taglist compact="compact">
2841 <tag><em>stable</em></tag>
2843 This is the current "released" version of Debian
2844 GNU/Linux. Once the distribution is
2845 <em>stable</em> only security fixes and other
2846 major bug fixes are allowed. When changes are
2847 made to this distribution, the release number is
2848 increased (for example: 2.2r1 becomes 2.2r2 then
2852 <tag><em>unstable</em></tag>
2854 This distribution value refers to the
2855 <em>developmental</em> part of the Debian
2856 distribution tree. New packages, new upstream
2857 versions of packages and bug fixes go into the
2858 <em>unstable</em> directory tree. Download from
2859 this distribution at your own risk.
2862 <tag><em>testing</em></tag>
2864 This distribution value refers to the
2865 <em>testing</em> part of the Debian distribution
2866 tree. It receives its packages from the
2867 unstable distribution after a short time lag to
2868 ensure that there are no major issues with the
2869 unstable packages. It is less prone to breakage
2870 than unstable, but still risky. It is not
2871 possible to upload packages directly to
2875 <tag><em>frozen</em></tag>
2877 From time to time, the <em>testing</em>
2878 distribution enters a state of "code-freeze" in
2879 anticipation of release as a <em>stable</em>
2880 version. During this period of testing only
2881 fixes for existing or newly-discovered bugs will
2882 be allowed. The exact details of this stage are
2883 determined by the Release Manager.
2886 <tag><em>experimental</em></tag>
2888 The packages with this distribution value are
2889 deemed by their maintainers to be high
2890 risk. Oftentimes they represent early beta or
2891 developmental packages from various sources that
2892 the maintainers want people to try, but are not
2893 ready to be a part of the other parts of the
2894 Debian distribution tree. Download at your own
2900 You should list <em>all</em> distributions that the
2901 package should be installed into.
2905 More information is available in the Debian Developer's
2906 Reference, section "The Debian archive".
2913 <heading><tt>Date</tt></heading>
2916 This field includes the date the package was built or last edited.
2920 The value of this field is usually extracted from the
2921 <file>debian/changelog</file> file - see
2922 <ref id="dpkgchangelog">).
2926 <sect1 id="f-Format">
2927 <heading><tt>Format</tt></heading>
2930 This field specifies a format revision for the file.
2931 The most current format described in the Policy Manual
2932 is version <strong>1.5</strong>. The syntax of the
2933 format value is the same as that of a package version
2934 number except that no epoch or Debian revision is allowed
2935 - see <ref id="f-Version">.
2939 <sect1 id="f-Urgency">
2940 <heading><tt>Urgency</tt></heading>
2943 This is a description of how important it is to upgrade to
2944 this version from previous ones. It consists of a single
2945 keyword usually taking one of the values <tt>low</tt>,
2946 <tt>medium</tt> or <tt>high</tt> (not case-sensitive)
2947 followed by an optional commentary (separated by a space)
2948 which is usually in parentheses. For example:
2951 Urgency: low (HIGH for users of diversions)
2957 The value of this field is usually extracted from the
2958 <file>debian/changelog</file> file - see
2959 <ref id="dpkgchangelog">.
2963 <sect1 id="f-Changes">
2964 <heading><tt>Changes</tt></heading>
2967 This field contains the human-readable changes data, describing
2968 the differences between the last version and the current one.
2972 There should be nothing in this field before the first
2973 newline; all the subsequent lines must be indented by at
2974 least one space; blank lines must be represented by a line
2975 consiting only of a space and a full stop.
2979 The value of this field is usually extracted from the
2980 <file>debian/changelog</file> file - see
2981 <ref id="dpkgchangelog">).
2985 Each version's change information should be preceded by a
2986 "title" line giving at least the version, distribution(s)
2987 and urgency, in a human-readable way.
2991 If data from several versions is being returned the entry
2992 for the most recent version should be returned first, and
2993 entries should be separated by the representation of a
2994 blank line (the "title" line may also be followed by the
2995 representation of blank line).
2999 <sect1 id="f-Binary">
3000 <heading><tt>Binary</tt></heading>
3003 This field is a list of binary packages.
3007 When it appears in the <file>.dsc</file> file it is the list
3008 of binary packages which a source package can produce. It
3009 does not necessarily produce all of these binary packages
3010 for every architecture. The source control file doesn't
3011 contain details of which architectures are appropriate for
3012 which of the binary packages.
3016 When it appears in a <file>.changes</file> file it lists the
3017 names of the binary packages actually being uploaded.
3021 The syntax is a list of binary packages separated by
3023 A space after each comma is conventional.
3024 </footnote>. Currently the packages must be separated using
3025 only spaces in the <file>.changes</file> file.
3029 <sect1 id="f-Installed-Size">
3030 <heading><tt>Installed-Size</tt></heading>
3033 This field appears in the control files of binary
3034 packages, and in the <file>Packages</file> files. It gives
3035 the total amount of disk space required to install the
3040 The disk space is represented in kilobytes as a simple
3045 <sect1 id="f-Files">
3046 <heading><tt>Files</tt></heading>
3049 This field contains a list of files with information about
3050 each one. The exact information and syntax varies with
3051 the context. In all cases the part of the field
3052 contents on the same line as the field name is empty. The
3053 remainder of the field is one line per file, each line
3054 being indented by one space and containing a number of
3055 sub-fields separated by spaces.
3059 In the <file>.dsc</file> file, each line contains the MD5
3060 checksum, size and filename of the tar file and (if applicable)
3061 diff file which make up the remainder of the source
3063 That is, the parts which are not the <tt>.dsc</tt>.
3065 The exact forms of the filenames are described
3066 in <ref id="pkg-sourcearchives">.
3070 In the <file>.changes</file> file this contains one line per
3071 file being uploaded. Each line contains the MD5 checksum,
3072 size, section and priority and the filename.
3073 The <qref id="f-Section">section</qref>
3074 and <qref id="f-Priority">priority</qref>
3075 are the values of the corresponding fields in
3076 the main source control file. If no section or priority is
3077 specified then <tt>-</tt> should be used, though section
3078 and priority values must be specified for new packages to
3079 be installed properly.
3083 The special value <tt>byhand</tt> for the section in a
3084 <tt>.changes</tt> file indicates that the file in question
3085 is not an ordinary package file and must by installed by
3086 hand by the distribution maintainers. If the section is
3087 <tt>byhand</tt> the priority should be <tt>-</tt>.
3091 If a new Debian revision of a package is being shipped and
3092 no new original source archive is being distributed the
3093 <tt>.dsc</tt> must still contain the <tt>Files</tt> field
3094 entry for the original source archive
3095 <file><var>package</var>-<var>upstream-version</var>.orig.tar.gz</file>,
3096 but the <file>.changes</file> file should leave it out. In
3097 this case the original source archive on the distribution
3098 site must match exactly, byte-for-byte, the original
3099 source archive which was used to generate the
3100 <file>.dsc</file> file and diff which are being uploaded.</p>
3103 <sect1 id="f-Closes">
3104 <heading><tt>Closes</tt></heading>
3107 A space-separated list of bug report numbers that the upload
3108 governed by the .changes file closes.
3115 <heading>User-defined fields</heading>
3118 Additional user-defined fields may be added to the
3119 source package control file. Such fields will be
3120 ignored, and not copied to (for example) binary or
3121 source package control files or upload control files.
3125 If you wish to add additional unsupported fields to
3126 these output files you should use the mechanism
3131 Fields in the main source control information file with
3132 names starting <tt>X</tt>, followed by one or more of
3133 the letters <tt>BCS</tt> and a hyphen <tt>-</tt>, will
3134 be copied to the output files. Only the part of the
3135 field name after the hyphen will be used in the output
3136 file. Where the letter <tt>B</tt> is used the field
3137 will appear in binary package control files, where the
3138 letter <tt>S</tt> is used in source package control
3139 files and where <tt>C</tt> is used in upload control
3140 (<tt>.changes</tt>) files.
3144 For example, if the main source information control file
3147 XBS-Comment: I stand between the candle and the star.
3149 then the binary and source package control files will contain the
3152 Comment: I stand between the candle and the star.
3161 <chapt id="maintainerscripts">
3162 <heading>Package maintainer scripts and installation procedure</heading>
3165 <heading>Introduction to package maintainer scripts</heading>
3168 It is possible to supply scripts as part of a package which
3169 the package management system will run for you when your
3170 package is installed, upgraded or removed.
3174 These scripts are the files <prgn>preinst</prgn>,
3175 <prgn>postinst</prgn>, <prgn>prerm</prgn> and <prgn>postrm</prgn> in the
3176 control area of the package. They must be proper executable
3177 files; if they are scripts (which is recommended), they must
3178 start with the usual <tt>#!</tt> convention. They should be
3179 readable and executable by anyone, and not world-writable.
3183 The package management system looks at the exit status from
3184 these scripts. It is important that they exit with a
3185 non-zero status if there is an error, so that the package
3186 management system can stop its processing. For shell
3187 scripts this means that you <em>almost always</em> need to
3188 use <tt>set -e</tt> (this is usually true when writing shell
3189 scripts, in fact). It is also important, of course, that
3190 they don't exit with a non-zero status if everything went
3195 When a package is upgraded a combination of the scripts from
3196 the old and new packages is called during the upgrade
3197 procedure. If your scripts are going to be at all
3198 complicated you need to be aware of this, and may need to
3199 check the arguments to your scripts.
3203 Broadly speaking the <prgn>preinst</prgn> is called before
3204 (a particular version of) a package is installed, and the
3205 <prgn>postinst</prgn> afterwards; the <prgn>prerm</prgn>
3206 before (a version of) a package is removed and the
3207 <prgn>postrm</prgn> afterwards.
3211 Programs called from maintainer scripts should not normally
3212 have a path prepended to them. Before installation is
3213 started, the package management system checks to see if the
3214 programs <prgn>ldconfig</prgn>,
3215 <prgn>start-stop-daemon</prgn>, <prgn>install-info</prgn>,
3216 and <prgn>update-rc.d</prgn> can be found via the
3217 <tt>PATH</tt> environment variable. Those programs, and any
3218 other program that one would expect to be on the
3219 <tt>PATH</tt>, should thus be invoked without an absolute
3220 pathname. Maintainer scripts should also not reset the
3221 <tt>PATH</tt>, though they might choose to modify it by
3222 prepending or appending package-specific directories. These
3223 considerations really apply to all shell scripts.</p>
3226 <sect id="idempotency">
3227 <heading>Maintainer scripts Idempotency</heading>
3230 It is necessary for the error recovery procedures that the
3231 scripts be idempotent. This means that if it is run
3232 successfully, and then it is called again, it doesn't bomb
3233 out or cause any harm, but just ensures that everything is
3234 the way it ought to be. If the first call failed, or
3235 aborted half way through for some reason, the second call
3236 should merely do the things that were left undone the first
3237 time, if any, and exit with a success status if everything
3239 This is so that if an error occurs, the user interrupts
3240 <prgn>dpkg</prgn> or some other unforeseen circumstance
3241 happens you don't leave the user with a badly-broken
3242 package when <prgn>dpkg</prgn> attempts to repeat the
3248 <sect id="controllingterminal">
3249 <heading>Controlling terminal for maintainer scripts</heading>
3252 The maintainer scripts are guaranteed to run with a
3253 controlling terminal and can interact with the user.
3254 If they need to prompt for passwords, do full-screen
3255 interaction or something similar you should do these
3256 things to and from <file>/dev/tty</file>, since
3257 <prgn>dpkg</prgn> will at some point redirect scripts'
3258 standard input and output so that it can log the
3259 installation process. Likewise, because these scripts
3260 may be executed with standard output redirected into a
3261 pipe for logging purposes, Perl scripts should set
3262 unbuffered output by setting <tt>$|=1</tt> so that the
3263 output is printed immediately rather than being
3268 Each script should return a zero exit status for
3269 success, or a nonzero one for failure.
3273 <sect id="mscriptsinstact"><heading>Summary of ways maintainer
3278 <list compact="compact">
3280 <var>new-preinst</var> <tt>install</tt>
3283 <var>new-preinst</var> <tt>install</tt> <var>old-version</var>
3286 <var>new-preinst</var> <tt>upgrade</tt> <var>old-version</var>
3289 <var>old-preinst</var> <tt>abort-upgrade</tt>
3290 <var>new-version</var>
3295 <list compact="compact">
3297 <var>postinst</var> <tt>configure</tt>
3298 <var>most-recently-configured-version</var>
3301 <var>old-postinst</var> <tt>abort-upgrade</tt>
3302 <var>new-version</var>
3305 <var>conflictor's-postinst</var> <tt>abort-remove</tt>
3306 <tt>in-favour</tt> <var>package</var>
3307 <var>new-version</var>
3310 <var>deconfigured's-postinst</var>
3311 <tt>abort-deconfigure</tt> <tt>in-favour</tt>
3312 <var>failed-install-package</var> <var>version</var>
3313 <tt>removing</tt> <var>conflicting-package</var>
3319 <list compact="compact">
3321 <var>prerm</var> <tt>remove</tt>
3324 <var>old-prerm</var> <tt>upgrade</tt>
3325 <var>new-version</var>
3328 <var>new-prerm</var> <tt>failed-upgrade</tt>
3329 <var>old-version</var>
3332 <var>conflictor's-prerm</var> <tt>remove</tt>
3333 <tt>in-favour</tt> <var>package</var>
3334 <var>new-version</var>
3337 <var>deconfigured's-prerm</var> <tt>deconfigure</tt>
3338 <tt>in-favour</tt> <var>package-being-installed</var>
3339 <var>version</var> <tt>removing</tt>
3340 <var>conflicting-package</var>
3346 <list compact="compact">
3348 <var>postrm</var> <tt>remove</tt>
3351 <var>postrm</var> <tt>purge</tt>
3354 <var>old-postrm</var> <tt>upgrade</tt>
3355 <var>new-version</var>
3358 <var>new-postrm</var> <tt>failed-upgrade</tt>
3359 <var>old-version</var>
3362 <var>new-postrm</var> <tt>abort-install</tt>
3365 <var>new-postrm</var> <tt>abort-install</tt>
3366 <var>old-version</var>
3369 <var>new-postrm</var> <tt>abort-upgrade</tt>
3370 <var>old-version</var>
3373 <var>disappearer's-postrm</var> <tt>disappear</tt>
3374 <var>overwriter</var>
3375 <var>overwriter-version</var>
3381 <sect id="unpackphase">
3382 <heading>Details of unpack phase of installation or upgrade</heading>
3385 The procedure on installation/upgrade/overwrite/disappear
3386 (i.e., when running <tt>dpkg --unpack</tt>, or the unpack
3387 stage of <tt>dpkg --install</tt>) is as follows. In each
3388 case, if a major error occurs (unless listed below) the
3389 actions are, in general, run backwards - this means that the
3390 maintainer scripts are run with different arguments in
3391 reverse order. These are the "error unwind" calls listed
3398 If a version of the package is already installed, call
3399 <example compact="compact">
3400 <var>old-prerm</var> upgrade <var>new-version</var>
3404 If the script runs but exits with a non-zero
3405 exit status, <prgn>dpkg</prgn> will attempt:
3406 <example compact="compact">
3407 <var>new-prerm</var> failed-upgrade <var>old-version</var>
3409 Error unwind, for both the above cases:
3410 <example compact="compact">
3411 <var>old-postinst</var> abort-upgrade <var>new-version</var>
3418 If a "conflicting" package is being removed at the same time:
3421 If any packages depended on that conflicting
3422 package and <tt>--auto-deconfigure</tt> is
3423 specified, call, for each such package:
3424 <example compact="compact">
3425 <var>deconfigured's-prerm</var> deconfigure \
3426 in-favour <var>package-being-installed</var> <var>version</var> \
3427 removing <var>conflicting-package</var> <var>version</var>
3430 <example compact="compact">
3431 <var>deconfigured's-postinst</var> abort-deconfigure \
3432 in-favour <var>package-being-installed-but-failed</var> <var>version</var> \
3433 removing <var>conflicting-package</var> <var>version</var>
3435 The deconfigured packages are marked as
3436 requiring configuration, so that if
3437 <tt>--install</tt> is used they will be
3438 configured again if possible.
3441 To prepare for removal of the conflicting package, call:
3442 <example compact="compact">
3443 <var>conflictor's-prerm</var> remove \
3444 in-favour <var>package</var> <var>new-version</var>
3447 <example compact="compact">
3448 <var>conflictor's-postinst</var> abort-remove \
3449 in-favour <var>package</var> <var>new-version</var>
3458 If the package is being upgraded, call:
3459 <example compact="compact">
3460 <var>new-preinst</var> upgrade <var>old-version</var>
3464 Otherwise, if the package had some configuration
3465 files from a previous version installed (i.e., it
3466 is in the "configuration files only" state):
3467 <example compact="compact">
3468 <var>new-preinst</var> install <var>old-version</var>
3472 Otherwise (i.e., the package was completely purged):
3473 <example compact="compact">
3474 <var>new-preinst</var> install
3476 Error unwind actions, respectively:
3477 <example compact="compact">
3478 <var>new-postrm</var> abort-upgrade <var>old-version</var>
3479 <var>new-postrm</var> abort-install <var>old-version</var>
3480 <var>new-postrm</var> abort-install
3488 The new package's files are unpacked, overwriting any
3489 that may be on the system already, for example any
3490 from the old version of the same package or from
3491 another package. Backups of the old files are kept
3492 temporarily, and if anything goes wrong the package
3493 management system will attempt to put them back as
3494 part of the error unwind.
3498 It is an error for a package to contain files which
3499 are on the system in another package, unless
3500 <tt>Replaces</tt> is used (see <ref id="replaces">).
3502 The following paragraph is not currently the case:
3503 Currently the <tt>- - force-overwrite</tt> flag is
3504 enabled, downgrading it to a warning, but this may not
3510 It is a more serious error for a package to contain a
3511 plain file or other kind of non-directory where another
3512 package has a directory (again, unless
3513 <tt>Replaces</tt> is used). This error can be
3514 overridden if desired using
3515 <tt>--force-overwrite-dir</tt>, but this is not
3520 Packages which overwrite each other's files produce
3521 behavior which, though deterministic, is hard for the
3522 system administrator to understand. It can easily
3523 lead to "missing" programs if, for example, a package
3524 is installed which overwrites a file from another
3525 package, and is then removed again.<footnote>
3526 Part of the problem is due to what is arguably a
3527 bug in <prgn>dpkg</prgn>.
3532 A directory will never be replaced by a symbolic link
3533 to a directory or vice versa; instead, the existing
3534 state (symlink or not) will be left alone and
3535 <prgn>dpkg</prgn> will follow the symlink if there is
3544 If the package is being upgraded, call
3545 <example compact="compact">
3546 <var>old-postrm</var> upgrade <var>new-version</var>
3550 If this fails, <prgn>dpkg</prgn> will attempt:
3551 <example compact="compact">
3552 <var>new-postrm</var> failed-upgrade <var>old-version</var>
3554 Error unwind, for both cases:
3555 <example compact="compact">
3556 <var>old-preinst</var> abort-upgrade <var>new-version</var>
3563 This is the point of no return - if
3564 <prgn>dpkg</prgn> gets this far, it won't back off
3565 past this point if an error occurs. This will
3566 leave the package in a fairly bad state, which
3567 will require a successful re-installation to clear
3568 up, but it's when <prgn>dpkg</prgn> starts doing
3569 things that are irreversible.
3574 Any files which were in the old version of the package
3575 but not in the new are removed.
3579 The new file list replaces the old.
3583 The new maintainer scripts replace the old.
3587 Any packages all of whose files have been overwritten
3588 during the installation, and which aren't required for
3589 dependencies, are considered to have been removed.
3590 For each such package
3593 <prgn>dpkg</prgn> calls:
3594 <example compact="compact">
3595 <var>disappearer's-postrm</var> disappear \
3596 <var>overwriter</var> <var>overwriter-version</var>
3600 The package's maintainer scripts are removed.
3603 It is noted in the status database as being in a
3604 sane state, namely not installed (any conffiles
3605 it may have are ignored, rather than being
3606 removed by <prgn>dpkg</prgn>). Note that
3607 disappearing packages do not have their prerm
3608 called, because <prgn>dpkg</prgn> doesn't know
3609 in advance that the package is going to
3616 Any files in the package we're unpacking that are also
3617 listed in the file lists of other packages are removed
3618 from those lists. (This will lobotomize the file list
3619 of the "conflicting" package if there is one.)
3623 The backup files made during installation, above, are
3629 The new package's status is now sane, and recorded as
3634 Here is another point of no return - if the
3635 conflicting package's removal fails we do not unwind
3636 the rest of the installation; the conflicting package
3637 is left in a half-removed limbo.
3642 If there was a conflicting package we go and do the
3643 removal actions (described below), starting with the
3644 removal of the conflicting package's files (any that
3645 are also in the package being installed have already
3646 been removed from the conflicting package's file list,
3647 and so do not get removed now).
3653 <sect id="configdetails"><heading>Details of configuration</heading>
3656 When we configure a package (this happens with <tt>dpkg
3657 --install</tt> and <tt>dpkg --configure</tt>), we first
3658 update any <tt>conffile</tt>s and then call:
3659 <example compact="compact">
3660 <var>postinst</var> configure <var>most-recently-configured-version</var>
3665 No attempt is made to unwind after errors during
3670 If there is no most recently configured version
3671 <prgn>dpkg</prgn> will pass a null argument.
3674 Historical note: Truly ancient (pre-1997) versions of
3675 <prgn>dpkg</prgn> passed <tt><unknown></tt>
3676 (including the angle brackets) in this case. Even older
3677 ones did not pass a second argument at all, under any
3678 circumstance. Note that upgrades using such an old dpkg
3679 version are unlikely to work for other reasons, even if
3680 this old argument behavior is handled by your postinst script.
3686 <sect id="removedetails"><heading>Details of removal and/or
3687 configuration purging</heading>
3692 <example compact="compact">
3693 <var>prerm</var> remove
3697 The package's files are removed (except <tt>conffile</tt>s).
3700 <example compact="compact">
3701 <var>postrm</var> remove
3706 All the maintainer scripts except the <prgn>postrm</prgn>
3711 If we aren't purging the package we stop here. Note
3712 that packages which have no <prgn>postrm</prgn> and no
3713 <tt>conffile</tt>s are automatically purged when
3714 removed, as there is no difference except for the
3715 <prgn>dpkg</prgn> status.
3719 The <tt>conffile</tt>s and any backup files
3720 (<tt>~</tt>-files, <tt>#*#</tt> files,
3721 <tt>%</tt>-files, <tt>.dpkg-{old,new,tmp}</tt>, etc.)
3725 <example compact="compact">
3726 <var>postrm</var> purge
3730 The package's file list is removed.
3734 If there are problems during this process, we call
3735 <example compact="compact">postinst
3736 abort-remove</example>. No other attempt is made to unwind
3737 after errors during removal.
3743 <chapt id="relationships">
3744 <heading>Declaring relationships between packages</heading>
3746 <sect id="depsyntax">
3747 <heading>Syntax of relationship fields</heading>
3750 These fields all have a uniform syntax. They are a list of
3751 package names separated by commas.
3755 In the <tt>Depends</tt>, <tt>Recommends</tt>,
3756 <tt>Suggests</tt>, <tt>Pre-Depends</tt>,
3757 <tt>Build-Depends</tt> and <tt>Build-Depends-Indep</tt>
3758 control file fields of the package, which declare
3759 dependencies on other packages, the package names listed may
3760 also include lists of alternative package names, separated
3761 by vertical bar (pipe) symbols <tt>|</tt>. In such a case,
3762 if any one of the alternative packages is installed, that
3763 part of the dependency is considered to be satisfied.
3767 All of the fields except for <tt>Provides</tt> may restrict
3768 their applicability to particular versions of each named
3769 package. This is done in parentheses after each individual
3770 package name; the parentheses should contain a relation from
3771 the list below followed by a version number, in the format
3772 described in <ref id="f-Version">.
3776 The relations allowed are <tt><<</tt>, <tt><=</tt>,
3777 <tt>=</tt>, <tt>>=</tt> and <tt>>></tt> for
3778 strictly earlier, earlier or equal, exactly equal, later or
3779 equal and strictly later, respectively. The deprecated
3780 forms <tt><</tt> and <tt>></tt> were used to mean
3781 earlier/later or equal, rather than strictly earlier/later,
3782 so they should not appear in new packages (though
3783 <prgn>dpkg</prgn> still supports them).
3787 Whitespace may appear at any point in the version
3788 specification subject to the rules in <ref
3789 id="controlsyntax">, and must appear where it's necessary to
3790 disambiguate; it is not otherwise significant. For
3791 consistency and in case of future changes to
3792 <prgn>dpkg</prgn> it is recommended that a single space be
3793 used after a version relationship and before a version
3794 number; it is also conventional to put a single space after
3795 each comma, on either side of each vertical bar, and before
3796 each open parenthesis.
3800 For example, a list of dependencies might appear as:
3801 <example compact="compact">
3804 Depends: libc6 (>= 2.2.1), exim | mail-transport-agent
3809 All fields that specify build-time relationships
3810 (<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
3811 <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>)
3812 may be restricted to a certain set of architectures. This
3813 is indicated in brackets after each individual package name and
3814 the optional version specification. The brackets enclose a
3815 list of Debian architecture names separated by whitespace.
3816 Exclamation marks may be prepended to each of the names.
3817 (It is not permitted for some names to be prepended with
3818 exclamation marks and others not.) If the current Debian
3819 host architecture is not in this list and there are no
3820 exclamation marks in the list, or it is in the list with a
3821 prepended exclamation mark, the package name and the
3822 associated version specification are ignored completely for
3823 the purposes of defining the relationships.
3828 <example compact="compact">
3830 Build-Depends-Indep: texinfo
3831 Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
3832 hurd-dev [hurd-i386], gnumach-dev [hurd-i386]
3837 Note that the binary package relationship fields such as
3838 <tt>Depends</tt> appear in one of the binary package
3839 sections of the control file, whereas the build-time
3840 relationships such as <tt>Build-Depends</tt> appear in the
3841 source package section of the control file (which is the
3846 <sect id="binarydeps">
3847 <heading>Binary Dependencies - <tt>Depends</tt>,
3848 <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
3849 <tt>Pre-Depends</tt>
3853 Packages can declare in their control file that they have
3854 certain relationships to other packages - for example, that
3855 they may not be installed at the same time as certain other
3856 packages, and/or that they depend on the presence of others.
3860 This is done using the <tt>Depends</tt>, <tt>Pre-Depends</tt>,
3861 <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt> and
3862 <tt>Conflicts</tt> control file fields.
3866 These six fields are used to declare a dependency
3867 relationship by one package on another. Except for
3868 <tt>Enhances</tt>, they appear in the depending (binary)
3869 package's control file. (<tt>Enhances</tt> appears in the
3870 recommending package's control file.)
3874 A <tt>Depends</tt> field takes effect <em>only</em> when a
3875 package is to be configured. It does not prevent a package
3876 being on the system in an unconfigured state while its
3877 dependencies are unsatisfied, and it is possible to replace
3878 a package whose dependencies are satisfied and which is
3879 properly installed with a different version whose
3880 dependencies are not and cannot be satisfied; when this is
3881 done the depending package will be left unconfigured (since
3882 attempts to configure it will give errors) and will not
3883 function properly. If it is necessary, a
3884 <tt>Pre-Depends</tt> field can be used, which has a partial
3885 effect even when a package is being unpacked, as explained
3886 in detail below. (The other three dependency fields,
3887 <tt>Recommends</tt>, <tt>Suggests</tt> and
3888 <tt>Enhances</tt>, are only used by the various front-ends
3889 to <prgn>dpkg</prgn> such as <prgn>dselect</prgn>.)
3893 For this reason packages in an installation run are usually
3894 all unpacked first and all configured later; this gives
3895 later versions of packages with dependencies on later
3896 versions of other packages the opportunity to have their
3897 dependencies satisfied.
3901 The <tt>Depends</tt> field thus allows package maintainers
3902 to impose an order in which packages should be configured.
3906 The meaning of the five dependency fields is as follows:
3908 <tag><tt>Depends</tt></tag>
3911 This declares an absolute dependency. A package will
3912 not be configured unless all of the packages listed in
3913 its <tt>Depends</tt> field have been correctly
3918 The <tt>Depends</tt> field should be used if the
3919 depended-on package is required for the depending
3920 package to provide a significant amount of
3925 The <tt>Depends</tt> field should also be used if the
3926 <prgn>postinst</prgn>, <prgn>prerm</prgn> or
3927 <prgn>postrm</prgn> scripts require the package to be
3928 present in order to run. Note, however, that the
3929 <prgn>postrm</prgn> cannot rely on any non-essential
3930 packages to be present during the <tt>purge</tt>
3934 <tag><tt>Recommends</tt></tag>
3937 This declares a strong, but not absolute, dependency.
3941 The <tt>Recommends</tt> field should list packages
3942 that would be found together with this one in all but
3943 unusual installations.
3947 <tag><tt>Suggests</tt></tag>
3949 This is used to declare that one package may be more
3950 useful with one or more others. Using this field
3951 tells the packaging system and the user that the
3952 listed packages are related to this one and can
3953 perhaps enhance its usefulness, but that installing
3954 this one without them is perfectly reasonable.
3957 <tag><tt>Enhances</tt></tag>
3959 This field is similar to Suggests but works in the
3960 opposite direction. It is used to declare that a
3961 package can enhance the functionality of another
3965 <tag><tt>Pre-Depends</tt></tag>
3968 This field is like <tt>Depends</tt>, except that it
3969 also forces <prgn>dpkg</prgn> to complete installation
3970 of the packages named before even starting the
3971 installation of the package which declares the
3972 pre-dependency, as follows:
3976 When a package declaring a pre-dependency is about to
3977 be <em>unpacked</em> the pre-dependency can be
3978 satisfied if the depended-on package is either fully
3979 configured, <em>or even if</em> the depended-on
3980 package(s) are only unpacked or half-configured,
3981 provided that they have been configured correctly at
3982 some point in the past (and not removed or partially
3983 removed since). In this case, both the
3984 previously-configured and currently unpacked or
3985 half-configured versions must satisfy any version
3986 clause in the <tt>Pre-Depends</tt> field.
3990 When the package declaring a pre-dependency is about
3991 to be <em>configured</em>, the pre-dependency will be
3992 treated as a normal <tt>Depends</tt>, that is, it will
3993 be considered satisfied only if the depended-on
3994 package has been correctly configured.
3998 <tt>Pre-Depends</tt> should be used sparingly,
3999 preferably only by packages whose premature upgrade or
4000 installation would hamper the ability of the system to
4001 continue with any upgrade that might be in progress.
4005 <tt>Pre-Depends</tt> are also required if the
4006 <prgn>preinst</prgn> script depends on the named
4007 package. It is best to avoid this situation if
4015 When selecting which level of dependency to use you should
4016 consider how important the depended-on package is to the
4017 functionality of the one declaring the dependency. Some
4018 packages are composed of components of varying degrees of
4019 importance. Such a package should list using
4020 <tt>Depends</tt> the package(s) which are required by the
4021 more important components. The other components'
4022 requirements may be mentioned as Suggestions or
4023 Recommendations, as appropriate to the components' relative
4028 <sect id="conflicts">
4029 <heading>Conflicting binary packages - <tt>Conflicts</tt></heading>
4032 When one binary package declares a conflict with another
4033 using a <tt>Conflicts</tt> field, <prgn>dpkg</prgn> will
4034 refuse to allow them to be installed on the system at the
4039 If one package is to be installed, the other must be removed
4040 first - if the package being installed is marked as
4041 replacing (see <ref id="replaces">) the one on the system,
4042 or the one on the system is marked as deselected, or both
4043 packages are marked <tt>Essential</tt>, then
4044 <prgn>dpkg</prgn> will automatically remove the package
4045 which is causing the conflict, otherwise it will halt the
4046 installation of the new package with an error. This
4047 mechanism is specifically designed to produce an error when
4048 the installed package is <tt>Essential</tt>, but the new
4053 A package will not cause a conflict merely because its
4054 configuration files are still installed; it must be at least
4059 A special exception is made for packages which declare a
4060 conflict with their own package name, or with a virtual
4061 package which they provide (see below): this does not
4062 prevent their installation, and allows a package to conflict
4063 with others providing a replacement for it. You use this
4064 feature when you want the package in question to be the only
4065 package providing some feature.
4069 A <tt>Conflicts</tt> entry should almost never have an
4070 "earlier than" version clause. This would prevent
4071 <prgn>dpkg</prgn> from upgrading or installing the package
4072 which declared such a conflict until the upgrade or removal
4073 of the conflicted-with package had been completed.
4077 <sect id="virtual"><heading>Virtual packages - <tt>Provides</tt>
4081 As well as the names of actual ("concrete") packages, the
4082 package relationship fields <tt>Depends</tt>,
4083 <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
4084 <tt>Pre-Depends</tt>, <tt>Conflicts</tt>,
4085 <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
4086 <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>
4087 may mention "virtual packages".
4091 A <em>virtual package</em> is one which appears in the
4092 <tt>Provides</tt> control file field of another package.
4093 The effect is as if the package(s) which provide a
4094 particular virtual package name had been listed by name
4095 everywhere the virtual package name appears. (See also <ref
4100 If there are both concrete and virtual packages of the same
4101 name, then the dependency may be satisfied (or the conflict
4102 caused) by either the concrete package with the name in
4103 question or any other concrete package which provides the
4104 virtual package with the name in question. This is so that,
4105 for example, supposing we have
4106 <example compact="compact">
4110 and someone else releases an enhanced version of the
4111 <tt>bar</tt> package (for example, a non-US variant), they
4113 <example compact="compact">
4117 and the <tt>bar-plus</tt> package will now also satisfy the
4118 dependency for the <tt>foo</tt> package.
4122 If a dependency or a conflict has a version number attached
4123 then only real packages will be considered to see whether
4124 the relationship is satisfied (or the prohibition violated,
4125 for a conflict) - it is assumed that a real package which
4126 provides the virtual package is not of the "right" version.
4127 So, a <tt>Provides</tt> field may not contain version
4128 numbers, and the version number of the concrete package
4129 which provides a particular virtual package will not be
4130 looked at when considering a dependency on or conflict with
4131 the virtual package name.
4135 It is likely that the ability will be added in a future
4136 release of <prgn>dpkg</prgn> to specify a version number for
4137 each virtual package it provides. This feature is not yet
4138 present, however, and is expected to be used only
4143 If you want to specify which of a set of real packages
4144 should be the default to satisfy a particular dependency on
4145 a virtual package, you should list the real package as an
4146 alternative before the virtual one.
4151 <sect id="replaces"><heading>Overwriting files and replacing
4152 packages - <tt>Replaces</tt></heading>
4155 Packages can declare in their control file that they should
4156 overwrite files in certain other packages, or completely
4157 replace other packages. The <tt>Replaces</tt> control file
4158 field has these two distinct purposes.
4161 <sect1><heading>Overwriting files in other packages</heading>
4164 Firstly, as mentioned before, it is usually an error for a
4165 package to contain files which are on the system in
4170 However, if the overwriting package declares that it
4171 <tt>Replaces</tt> the one containing the file being
4172 overwritten, then <prgn>dpkg</prgn> will replace the file
4173 from the old package with that from the new. The file
4174 will no longer be listed as "owned" by the old package.
4178 If a package is completely replaced in this way, so that
4179 <prgn>dpkg</prgn> does not know of any files it still
4180 contains, it is considered to have "disappeared". It will
4181 be marked as not wanted on the system (selected for
4182 removal) and not installed. Any <tt>conffile</tt>s
4183 details noted for the package will be ignored, as they
4184 will have been taken over by the overwriting package. The
4185 package's <prgn>postrm</prgn> script will be run with a
4186 special argument to allow the package to do any final
4187 cleanup required. See <ref id="mscriptsinstact">.
4190 Replaces is a one way relationship -- you have to
4191 install the replacing package after the replaced
4198 For this usage of <tt>Replaces</tt>, virtual packages (see
4199 <ref id="virtual">) are not considered when looking at a
4200 <tt>Replaces</tt> field - the packages declared as being
4201 replaced must be mentioned by their real names.
4205 Furthermore, this usage of <tt>Replaces</tt> only takes
4206 effect when both packages are at least partially on the
4207 system at once, so that it can only happen if they do not
4208 conflict or if the conflict has been overridden.
4213 <sect1><heading>Replacing whole packages, forcing their
4217 Secondly, <tt>Replaces</tt> allows the packaging system to
4218 resolve which package should be removed when there is a
4219 conflict - see <ref id="conflicts">. This usage only
4220 takes effect when the two packages <em>do</em> conflict,
4221 so that the two usages of this field do not interfere with
4226 In this situation, the package declared as being replaced
4227 can be a virtual package, so for example, all mail
4228 transport agents (MTAs) would have the following fields in
4229 their control files:
4230 <example compact="compact">
4231 Provides: mail-transport-agent
4232 Conflicts: mail-transport-agent
4233 Replaces: mail-transport-agent
4235 ensuring that only one MTA can be installed at any one
4240 <sect id="sourcebinarydeps">
4241 <heading>Relationships between source and binary packages -
4242 <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
4243 <tt>Build-Conflicts</tt>, <tt>Build-Conflicts-Indep</tt>
4247 Source packages that require certain binary packages to be
4248 installed or absent at the time of building the package
4249 can declare relationships to those binary packages.
4253 This is done using the <tt>Build-Depends</tt>,
4254 <tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt> and
4255 <tt>Build-Conflicts-Indep</tt> control file fields.
4259 Build-dependencies on "build-essential" binary packages can be
4260 omitted. Please see <ref id="pkg-relations"> for more information.
4264 The dependencies and conflicts they define must be satisfied
4265 (as defined earlier for binary packages) in order to invoke
4266 the targets in <tt>debian/rules</tt>, as follows:<footnote>
4268 If you make "build-arch" or "binary-arch", you need
4269 Build-Depends. If you make "build-indep" or
4270 "binary-indep", you need Build-Depends and
4271 Build-Depends-Indep. If you make "build" or "binary",
4275 There is no Build-Depends-Arch; the autobuilders will
4276 only need the Build-Depends if they know how to build
4277 only build-arch and binary-arch. Anyone building the
4278 build-indep/binary-indep targets is basically assumed to
4279 be building the whole package and so installs all build
4283 The purpose of the original split, I recall, was so that
4284 the autobuilders wouldn't need to install extra packages
4285 needed only for the binary-indep targets. But without a
4286 build-arch/build-indep split, this didn't work, since
4287 most of the work is done in the build target, not in the
4293 <tag><tt>Build-Depends</tt>, <tt>Build-Conflicts</tt></tag>
4295 The <tt>Build-Depends</tt> and
4296 <tt>Build-Conflicts</tt> fields must be satisfied when
4297 any of the following targets is invoked:
4298 <tt>build</tt>, <tt>clean</tt>, <tt>binary</tt>,
4299 <tt>binary-arch</tt>, <tt>build-arch</tt>,
4300 <tt>build-indep</tt> and <tt>binary-indep</tt>.
4302 <tag><tt>Build-Depends-Indep</tt>,
4303 <tt>Build-Conflicts-Indep</tt></tag>
4305 The <tt>Build-Depends-Indep</tt> and
4306 <tt>Build-Conflicts-Indep</tt> fields must be
4307 satisfied when any of the following targets is
4308 invoked: <tt>build</tt>, <tt>build-indep</tt>,
4309 <tt>binary</tt> and <tt>binary-indep</tt>.
4319 <chapt id="sharedlibs"><heading>Shared libraries</heading>
4322 Packages containing shared libraries must be constructed with
4323 a little care to make sure that the shared library is always
4324 available. This is especially important for packages whose
4325 shared libraries are vitally important, such as the C library
4326 (currently <tt>libc6</tt>).
4330 Packages involving shared libraries should be split up into
4331 several binary packages. This section mostly deals with how
4332 this separation is to be accomplished; rules for files within
4333 the shared library packages are in <ref id="libraries"> instead.
4336 <sect id="sharedlibs-runtime">
4337 <heading>Run-time shared libraries</heading>
4340 The run-time shared library needs to be placed in a package called
4341 <package><var>libraryname</var><var>soversion</var></package>, where
4342 <file><var>soversion</var></file> is the version number in the
4343 soname of the shared library<footnote>
4344 The soname is the shared object name: it's the thing
4345 that has to match exactly between building an executable
4346 and running it for the dynamic linker to be able run the
4347 program. For example, if the soname of the library is
4348 <file>libfoo.so.6</file>, the library package would be
4349 called <file>libfoo6</file>.
4351 Alternatively, if it would be confusing to directly append
4352 <var>soversion</var> to <var>libraryname</var> (e.g. because
4353 <var>libraryname</var> itself ends in a number), you may use
4354 <package><var>libraryname</var>-<var>soversion</var></package> and
4355 <package><var>libraryname</var>-<var>soversion</var>-dev</package>
4360 If you have several shared libraries built from the same
4361 source tree you may lump them all together into a single
4362 shared library package, provided that you change all of
4363 their sonames at once (so that you don't get filename
4364 clashes if you try to install different versions of the
4365 combined shared libraries package).
4369 The package should install the shared libraries under
4370 their normal names. For example, the <package>libgdbm3</package>
4371 package should install <file>libgdbm.so.3.0.0</file> as
4372 <file>/usr/lib/libgdbm.so.3.0.0</file>. The files should not be
4373 renamed or re-linked by any <prgn>prerm</prgn> or
4374 <prgn>postrm</prgn> scripts; <prgn>dpkg</prgn> will take care
4375 of renaming things safely without affecting running programs,
4376 and attempts to interfere with this are likely to lead to
4381 Shared libraries should not be installed executable, since
4382 the dynamic linker does not require this and trying to
4383 execute a shared library usually results in a core dump.
4387 The run-time library package should include the symbolic link that
4388 <prgn>ldconfig</prgn> would create for the shared libraries.
4389 For example, the <package>libgdbm3</package> package should include
4390 a symbolic link from <file>/usr/lib/libgdbm.so.3</file> to
4391 <file>libgdbm.so.3.0.0</file>. This is needed so that the dynamic
4392 linker (for example <prgn>ld.so</prgn> or
4393 <prgn>ld-linux.so.*</prgn>) can find the library between the
4394 time that <prgn>dpkg</prgn> installs it and the time that
4395 <prgn>ldconfig</prgn> is run in the <prgn>postinst</prgn>
4397 The package management system requires the library to be
4398 placed before the symbolic link pointing to it in the
4399 <file>.deb</file> file. This is so that when
4400 <prgn>dpkg</prgn> comes to install the symlink
4401 (overwriting the previous symlink pointing at an older
4402 version of the library), the new shared library is already
4403 in place. In the past, this was achieved by creating the
4404 library in the temporary packaging directory before
4405 creating the symlink. Unfortunately, this was not always
4406 effective, since the building of the tar file in the
4407 <file>.deb</file> depended on the behavior of the underlying
4408 file system. Some file systems (such as reiserfs) reorder
4409 the files so that the order of creation is forgotten.
4410 Since version 1.7.0, <prgn>dpkg</prgn>
4411 reorders the files itself as necessary when building a
4412 package. Thus it is no longer important to concern
4413 oneself with the order of file creation.
4417 <sect1 id="ldconfig">
4418 <heading><tt>ldconfig</tt></heading>
4421 Any package installing shared libraries in one of the default
4422 library directories of the dynamic linker (which are currently
4423 <file>/usr/lib</file> and <file>/lib</file>) or a directory that is
4424 listed in <file>/etc/ld.so.conf</file><footnote>
4426 <list compact="compact">
4427 <item>/usr/X11R6/lib/Xaw3d</item>
4428 <item>/usr/local/lib</item>
4429 <item>/usr/lib/libc5-compat</item>
4430 <item>/lib/libc5-compat</item>
4431 <item>/usr/X11R6/lib</item>
4434 must use <prgn>ldconfig</prgn> to update the shared library
4439 The package must call <prgn>ldconfig</prgn> in the
4440 <prgn>postinst</prgn> script if the first argument is
4441 <tt>configure</tt>; the <prgn>postinst</prgn> script may
4442 optionally invoke <prgn>ldconfig</prgn> at other times. The
4443 package should call <prgn>ldconfig</prgn> in the
4444 <prgn>postrm</prgn> script if the first argument is
4445 <tt>remove</tt>. The maintainer scripts must not invoke
4446 <prgn>ldconfig</prgn> under any circumstances other than those
4447 described in this paragraph.<footnote>
4449 During install or upgrade, the preinst is called before
4450 the new files are installed, so calling "ldconfig" is
4451 pointless. The preinst of an existing package can also be
4452 called if an upgrade fails. However, this happens during
4453 the critical time when a shared libs may exist on-disk
4454 under a temporary name. Thus, it is dangerous and
4455 forbidden by current policy to call "ldconfig" at this
4460 When a package is installed or upgraded, "postinst
4461 configure" runs after the new files are safely on-disk.
4462 Since it is perfectly safe to invoke ldconfig
4463 unconditionally in a postinst, it is OK for a package to
4464 simply put ldconfig in its postinst without checking the
4465 argument. The postinst can also be called to recover from
4466 a failed upgrade. This happens before any new files are
4467 unpacked, so there is no reason to call "ldconfig" at this
4472 For a package that is being removed, prerm is
4473 called with all the files intact, so calling ldconfig is
4474 useless. The other calls to "prerm" happen in the case of
4475 upgrade at a time when all the files of the old package
4476 are on-disk, so again calling "ldconfig" is pointless.
4480 postrm, on the other hand, is called with the "remove"
4481 argument just after the files are removed, so this is the
4482 proper time to call "ldconfig" to notify the system of the
4483 fact shared libraries from the package are removed.
4484 The postrm can be called at several other times. At the
4485 time of "postrm purge", "postrm abort-install", or "postrm
4486 abort-upgrade", calling "ldconfig" is useless because the
4487 shared lib files are not on-disk. However, when "postrm"
4488 is invoked with arguments "upgrade", "failed-upgrade", or
4489 "disappear", a shared lib may exist on-disk under a
4498 <sect id="sharedlibs-runtime-progs">
4499 <heading>Run-time support programs</heading>
4502 If your package has some run-time support programs which use
4503 the shared library you must not put them in the shared
4504 library package. If you do that then you won't be able to
4505 install several versions of the shared library without
4506 getting filename clashes.
4510 Instead, either create another package for the runtime binaries
4511 (this package might typically be named
4512 <package><var>libraryname</var>-runtime</package>; note the absence
4513 of the <var>soversion</var> in the package name), or if the
4514 development package is small, include them in there.
4518 <sect id="sharedlibs-static">
4519 <heading>Static libraries</heading>
4522 The static library (<file><var>libraryname.a</var></file>)
4523 is usually provided in addition to the shared version.
4524 It is placed into the development package (see below).
4528 In some cases, it is acceptable for a library to be
4529 available in static form only; these cases include:
4531 <item>libraries for languages whose shared library support
4532 is immature or unstable</item>
4533 <item>libraries whose interfaces are in flux or under
4534 development (commonly the case when the library's
4535 major version number is zero, or where the ABI breaks
4536 across patchlevels)</item>
4537 <item>libraries which are explicitly intended to be
4538 available only in static form by their upstream
4543 <sect id="sharedlibs-dev">
4544 <heading>Development files</heading>
4547 The development files associated to a shared library need to be
4548 placed in a package called
4549 <package><var>libraryname</var><var>soversion</var>-dev</package>,
4550 or if you prefer only to support one development version at a
4551 time, <package><var>libraryname</var>-dev</package>.
4555 In case several development versions of a library exist, you may
4556 need to use <prgn>dpkg</prgn>'s Conflicts mechanism (see
4557 <ref id="conflicts">) to ensure that the user only installs one
4558 development version at a time (as different development versions are
4559 likely to have the same header files in them, which would cause a
4560 filename clash if both were installed).
4564 The development package should contain a symlink for the associated
4565 shared library without a version number. For example, the
4566 <package>libgdbm-dev</package> package should include a symlink
4567 from <file>/usr/lib/libgdbm.so</file> to
4568 <file>libgdbm.so.3.0.0</file>. This symlink is needed by the linker
4569 (<prgn>ld</prgn>) when compiling packages, as it will only look for
4570 <file>libgdbm.so</file> when compiling dynamically.
4574 <sect id="sharedlibs-intradeps">
4575 <heading>Dependencies between the packages of the same library</heading>
4578 Typically the development version should have an exact
4579 version dependency on the runtime library, to make sure that
4580 compilation and linking happens correctly. The
4581 <tt>${Source-Version}</tt> substitution variable can be
4582 useful for this purpose.
4586 <sect id="sharedlibs-shlibdeps">
4587 <heading>Dependencies between the library and other packages -
4588 the <tt>shlibs</tt> system</heading>
4591 If a package contains a binary or library which links to a
4592 shared library, we must ensure that when the package is
4593 installed on the system, all of the libraries needed are
4594 also installed. This requirement led to the creation of the
4595 <tt>shlibs</tt> system, which is very simple in its design:
4596 any package which <em>provides</em> a shared library also
4597 provides information on the package dependencies required to
4598 ensure the presence of this library, and any package which
4599 <em>uses</em> a shared library uses this information to
4600 determine the dependencies it requires. The files which
4601 contain the mapping from shared libraries to the necessary
4602 dependency information are called <file>shlibs</file> files.
4606 Thus, when a package is built which contains any shared
4607 libraries, it must provide a <file>shlibs</file> file for other
4608 packages to use, and when a package is built which contains
4609 any shared libraries or compiled binaries, it must run
4610 <qref id="pkg-dpkg-shlibdeps"><prgn>dpkg-shlibdeps</prgn></qref>
4611 on these to determine the libraries used and hence the
4612 dependencies needed by this package.<footnote>
4614 In the past, the shared libraries linked to were
4615 determined by calling <prgn>ldd</prgn>, but now
4616 <prgn>objdump</prgn> is used to do this. The only
4617 change this makes to package building is that
4618 <prgn>dpkg-shlibdeps</prgn> must also be run on shared
4619 libraries, whereas in the past this was unnecessary.
4620 The rest of this footnote explains the advantage that
4625 We say that a binary <tt>foo</tt> <em>directly</em> uses
4626 a library <tt>libbar</tt> if it is explicitly linked
4627 with that library (that is, it uses the flag
4628 <tt>-lbar</tt> during the linking stage). Other
4629 libraries that are needed by <tt>libbar</tt> are linked
4630 <em>indirectly</em> to <tt>foo</tt>, and the dynamic
4631 linker will load them automatically when it loads
4632 <tt>libbar</tt>. A package should depend on
4633 the libraries it directly uses, and the dependencies for
4634 those libraries should automatically pull in the other
4639 Unfortunately, the <prgn>ldd</prgn> program shows both
4640 the directly and indirectly used libraries, meaning that
4641 the dependencies determined included both direct and
4642 indirect dependencies. The use of <prgn>objdump</prgn>
4643 avoids this problem by determining only the directly
4648 A good example of where this helps is the following. We
4649 could update <tt>libimlib</tt> with a new version that
4650 supports a new graphics format called dgf (but retaining
4651 the same major version number). If we used the old
4652 <prgn>ldd</prgn> method, every package that uses
4653 <tt>libimlib</tt> would need to be recompiled so it
4654 would also depend on <tt>libdgf</tt> or it wouldn't run
4655 due to missing symbols. However with the new system,
4656 packages using <tt>libimlib</tt> can rely on
4657 <tt>libimlib</tt> itself having the dependency on
4658 <tt>libdgf</tt> and so they would not need rebuilding.
4664 In the following sections, we will first describe where the
4665 various <tt>shlibs</tt> files are to be found, then how to
4666 use <prgn>dpkg-shlibdeps</prgn>, and finally the <tt>shlibs</tt>
4667 file format and how to create them if your package contains a
4672 <heading>The <tt>shlibs</tt> files present on the system</heading>
4675 There are several places where <tt>shlibs</tt> files are
4676 found. The following list gives them in the order in which
4678 <qref id="pkg-dpkg-shlibdeps"><prgn>dpkg-shlibdeps</prgn></qref>.
4679 (The first one which gives the required information is used.)
4685 <p><file>debian/shlibs.local</file></p>
4688 This lists overrides for this package. Its use is
4689 described below (see <ref id="shlibslocal">).
4694 <p><file>/etc/dpkg/shlibs.override</file></p>
4697 This lists global overrides. This list is normally
4698 empty. It is maintained by the local system
4704 <p><file>DEBIAN/shlibs</file> files in the "build directory"</p>
4707 When packages are being built, any
4708 <file>debian/shlibs</file> files are copied into the
4709 control file area of the temporary build directory and
4710 given the name <file>shlibs</file>. These files give
4711 details of any shared libraries included in the
4713 An example may help here. Let us say that the
4714 source package <tt>foo</tt> generates two binary
4715 packages, <tt>libfoo2</tt> and
4716 <tt>foo-runtime</tt>. When building the binary
4717 packages, the two packages are created in the
4718 directories <file>debian/libfoo2</file> and
4719 <file>debian/foo-runtime</file> respectively.
4720 (<file>debian/tmp</file> could be used instead of one
4721 of these.) Since <tt>libfoo2</tt> provides the
4722 <tt>libfoo</tt> shared library, it will require a
4723 <tt>shlibs</tt> file, which will be installed in
4724 <file>debian/libfoo2/DEBIAN/shlibs</file>, eventually
4726 <file>/var/lib/dpkg/info/libfoo2.shlibs</file>. Then
4727 when <prgn>dpkg-shlibdeps</prgn> is run on the
4729 <file>debian/foo-runtime/usr/bin/foo-prog</file>, it
4731 <file>debian/libfoo2/DEBIAN/shlibs</file> file to
4732 determine whether <tt>foo-prog</tt>'s library
4733 dependencies are satisfied by any of the libraries
4734 provided by <tt>libfoo2</tt>. For this reason,
4735 <prgn>dpkg-shlibdeps</prgn> must only be run once
4736 all of the individual binary packages'
4737 <tt>shlibs</tt> files have been installed into the
4744 <p><file>/var/lib/dpkg/info/*.shlibs</file></p>
4747 These are the <file>shlibs</file> files corresponding to
4748 all of the packages installed on the system, and are
4749 maintained by the relevant package maintainers.
4754 <p><file>/etc/dpkg/shlibs.default</file></p>
4757 This file lists any shared libraries whose packages
4758 have failed to provide correct <file>shlibs</file> files.
4759 It was used when the <file>shlibs</file> setup was first
4760 introduced, but it is now normally empty. It is
4761 maintained by the <tt>dpkg</tt> maintainer.
4769 <heading>How to use <prgn>dpkg-shlibdeps</prgn> and the
4770 <file>shlibs</file> files</heading>
4774 <qref id="pkg-dpkg-shlibdeps"><prgn>dpkg-shlibdeps</prgn></qref>
4775 into your <file>debian/rules</file> file. If your package
4776 contains only compiled binaries and libraries (but no scripts),
4777 you can use a command such as:
4778 <example compact="compact">
4779 dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \
4780 debian/tmp/usr/lib/*
4782 Otherwise, you will need to explicitly list the compiled
4783 binaries and libraries.<footnote>
4784 If you are using <tt>debhelper</tt>, the
4785 <prgn>dh_shlibdeps</prgn> program will do this work for
4786 you. It will also correctly handle multi-binary
4792 This command puts the dependency information into the
4793 <file>debian/substvars</file> file, which is then used by
4794 <prgn>dpkg-gencontrol</prgn>. You will need to place a
4795 <tt>${shlib:Depends}</tt> variable in the <tt>Depends</tt>
4796 field in the control file for this to work.
4800 If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
4801 done. If it does complain you might need to create your own
4802 <file>debian/shlibs.local</file> file, as explained below (see
4803 <ref id="shlibslocal">).
4807 If you have multiple binary packages, you will need to call
4808 <prgn>dpkg-shlibdeps</prgn> on each one which contains
4809 compiled libraries or binaries. In such a case, you will
4810 need to use the <tt>-T</tt> option to the <tt>dpkg</tt>
4811 utilities to specify a different <file>substvars</file> file.
4815 For more details on dpkg-shlibdeps, please see
4816 <ref id="pkg-dpkg-shlibdeps"> and
4817 <manref name="dpkg-shlibdeps" section="1">.
4822 <heading>The <file>shlibs</file> File Format</heading>
4825 Each <file>shlibs</file> file has the same format. Lines
4826 beginning with <tt>#</tt> are considered to be comments and
4827 are ignored. Each line is of the form:
4828 <example compact="compact">
4829 <var>library-name</var> <var>soname-version-number</var> <var>dependencies ...</var>
4834 We will explain this by reference to the example of the
4835 <tt>zlib1g</tt> package, which (at the time of writing)
4836 installs the shared library <file>/usr/lib/libz.so.1.1.3</file>.
4840 <var>library-name</var> is the name of the shared library,
4841 in this case <tt>libz</tt>. (This must match the name part
4842 of the soname, see below.)
4846 <var>soname-version-number</var> is the version part of the
4847 soname of the library. The soname is the thing that must
4848 exactly match for the library to be recognized by the
4849 dynamic linker, and is usually of the form
4850 <tt><var>name</var>.so.<var>major-version</var></tt>, in our
4851 example, <tt>libz.so.1</tt>.<footnote>
4852 This can be determined using the command
4853 <example compact="compact">
4854 objdump -p /usr/lib/libz.so.1.1.3 | grep SONAME
4857 The version part is the part which comes after
4858 <tt>.so.</tt>, so in our case, it is <tt>1</tt>.
4862 <var>dependencies</var> has the same syntax as a dependency
4863 field in a binary package control file. It should give
4864 details of which packages are required to satisfy a binary
4865 built against the version of the library contained in the
4866 package. See <ref id="depsyntax"> for details.
4870 In our example, if the first version of the <tt>zlib1g</tt>
4871 package which contained a minor number of at least
4872 <tt>1.3</tt> was <var>1:1.1.3-1</var>, then the
4873 <tt>shlibs</tt> entry for this library could say:
4874 <example compact="compact">
4875 libz 1 zlib1g (>= 1:1.1.3)
4877 The version-specific dependency is to avoid warnings from
4878 the dynamic linker about using older shared libraries with
4884 <heading>Providing a <file>shlibs</file> file</heading>
4887 If your package provides a shared library, you should create
4888 a <file>shlibs</file> file following the format described above.
4889 It is usual to call this file <file>debian/shlibs</file> (but if
4890 you have multiple binary packages, you might want to call it
4891 <file>debian/shlibs.<var>package</var></file> instead). Then
4892 let <file>debian/rules</file> install it in the control area:
4893 <example compact="compact">
4894 install -m644 debian/shlibs debian/tmp/DEBIAN
4896 or, in the case of a multi-binary package:
4897 <example compact="compact">
4898 install -m644 debian/shlibs.<var>package</var> debian/<var>package</var>/DEBIAN/shlibs
4900 An alternative way of doing this is to create the
4901 <file>shlibs</file> file in the control area directly from
4902 <file>debian/rules</file> without using a <file>debian/shlibs</file>
4903 file at all,<footnote>
4904 This is what <prgn>dh_makeshlibs</prgn> in the
4905 <tt>debhelper</tt> suite does.
4907 since the <file>debian/shlibs</file> file itself is ignored by
4908 <prgn>dpkg-shlibdeps</prgn>.
4912 As <prgn>dpkg-shlibdeps</prgn> reads the
4913 <file>DEBIAN/shlibs</file> files in all of the binary packages
4914 being built from this source package, all of the
4915 <file>DEBIAN/shlibs</file> files should be installed before
4916 <prgn>dpkg-shlibdeps</prgn> is called on any of the binary
4921 <sect1 id="shlibslocal">
4922 <heading>Writing the <file>debian/shlibs.local</file> file</heading>
4925 This file is intended only as a <em>temporary</em> fix if
4926 your binaries or libraries depend on a library whose package
4927 does not yet provide a correct <file>shlibs</file> file.
4931 We will assume that you are trying to package a binary
4932 <tt>foo</tt>. When you try running
4933 <prgn>dpkg-shlibdeps</prgn> you get the following error
4934 message (<tt>-O</tt> displays the dependency information on
4935 <tt>stdout</tt> instead of writing it to
4936 <tt>debian/substvars</tt>, and the lines have been wrapped
4937 for ease of reading):
4938 <example compact="compact">
4939 $ dpkg-shlibdeps -O debian/tmp/usr/bin/foo
4940 dpkg-shlibdeps: warning: unable to find dependency
4941 information for shared library libbar (soname 1,
4942 path /usr/lib/libbar.so.1, dependency field Depends)
4943 shlibs:Depends=libc6 (>= 2.2.2-2)
4945 You can then run <prgn>ldd</prgn> on the binary to find the
4946 full location of the library concerned:
4947 <example compact="compact">
4949 libbar.so.1 => /usr/lib/libbar.so.1 (0x4001e000)
4950 libc.so.6 => /lib/libc.so.6 (0x40032000)
4951 /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
4953 So the <prgn>foo</prgn> binary depends on the
4954 <prgn>libbar</prgn> shared library, but no package seems to
4955 provide a <file>*.shlibs</file> file handling
4956 <file>libbar.so.1</file> in <file>/var/lib/dpkg/info/</file>. Let's
4957 determine the package responsible:
4958 <example compact="compact">
4959 $ dpkg -S /usr/lib/libbar.so.1
4960 bar1: /usr/lib/libbar.so.1
4961 $ dpkg -s bar1 | grep Version
4964 This tells us that the <tt>bar1</tt> package, version 1.0-1,
4965 is the one we are using. Now we can file a bug against the
4966 <tt>bar1</tt> package and create our own
4967 <file>debian/shlibs.local</file> to locally fix the problem.
4968 Including the following line into your
4969 <file>debian/shlibs.local</file> file:
4970 <example compact="compact">
4971 libbar 1 bar1 (>= 1.0-1)
4973 should allow the package build to work.
4977 As soon as the maintainer of <tt>bar1</tt> provides a
4978 correct <file>shlibs</file> file, you should remove this line
4979 from your <file>debian/shlibs.local</file> file. (You should
4980 probably also then have a versioned <tt>Build-Depends</tt>
4981 on <tt>bar1</tt> to help ensure that others do not have the
4982 same problem building your package.)
4991 <chapt id="opersys"><heading>The Operating System</heading>
4994 <heading>Filesystem hierarchy</heading>
4998 <heading>Filesystem Structure</heading>
5001 The location of all installed files and directories must
5002 comply with the Filesystem Hierarchy Standard (FHS),
5003 version 2.1, except where doing so would violate other
5004 terms of Debian Policy. The version of this document
5005 referred here can be found in the <tt>debian-policy</tt>
5007 <url id="http://www.debian.org/doc/packaging-manuals/fhs/"
5008 name="FHS (Debian copy)"> alongside this manual (or, if
5009 you have the <package>debian-policy</package> installed,
5011 id="file:///usr/share/doc/debian-policy/fhs/" name="FHS
5012 (local copy)">). The
5013 latest version, which may be a more recent version, may
5015 <url id="http://www.pathname.com/fhs/" name="FHS (upstream)">.
5016 Specific questions about following the standard may be
5017 asked on the <tt>debian-devel</tt> mailing list, or
5018 referred to the FHS mailing list (see the
5019 <url id="http://www.pathname.com/fhs/" name="FHS web site"> for
5025 <heading>Site-specific programs</heading>
5028 As mandated by the FHS, packages must not place any
5029 files in <file>/usr/local</file>, either by putting them in
5030 the file system archive to be unpacked by <prgn>dpkg</prgn>
5031 or by manipulating them in their maintainer scripts.
5035 However, the package may create empty directories below
5036 <file>/usr/local</file> so that the system administrator knows
5037 where to place site-specific files. These directories
5038 should be removed on package removal if they are
5043 Note, that this applies only to directories <em>below</em>
5044 <file>/usr/local</file>, not <em>in</em> <file>/usr/local</file>.
5045 Packages must not create sub-directories in the directory
5046 <file>/usr/local</file> itself, except those listed in FHS,
5047 section 4.5. However, you may create directories below
5048 them as you wish. You must not remove any of the
5049 directories listed in 4.5, even if you created them.
5053 Since <file>/usr/local</file> can be mounted read-only from a
5054 remote server, these directories must be created and
5055 removed by the <prgn>postinst</prgn> and <prgn>prerm</prgn>
5056 maintainer scripts and not be included in the
5057 <file>.deb</file> archive. These scripts must not fail if
5058 either of these operations fail.
5062 For example, the <tt>emacsen-common</tt> package could
5063 contain something like
5064 <example compact="compact">
5065 if [ ! -e /usr/local/share/emacs ]
5067 if mkdir /usr/local/share/emacs 2>/dev/null
5069 chown root:staff /usr/local/share/emacs
5070 chmod 2775 /usr/local/share/emacs
5074 in its <prgn>postinst</prgn> script, and
5075 <example compact="compact">
5076 rmdir /usr/local/share/emacs/site-lisp 2>/dev/null || true
5077 rmdir /usr/local/share/emacs 2>/dev/null || true
5079 in the <prgn>prerm</prgn> script. (Note that this form is
5080 used to ensure that if the script is interrupted, the
5081 directory <file>/usr/local/share/emacs</file> will still be
5086 If you do create a directory in <file>/usr/local</file> for
5087 local additions to a package, you should ensure that
5088 settings in <file>/usr/local</file> take precedence over the
5089 equivalents in <file>/usr</file>.
5093 However, because <file>/usr/local</file> and its contents are
5094 for exclusive use of the local administrator, a package
5095 must not rely on the presence or absence of files or
5096 directories in <file>/usr/local</file> for normal operation.
5100 The <file>/usr/local</file> directory itself and all the
5101 subdirectories created by the package should (by default) have
5102 permissions 2775 (group-writable and set-group-id) and be
5103 owned by <tt>root.staff</tt>.
5108 <heading>The system-wide mail directory</heading>
5110 The system-wide mail directory is <file>/var/mail</file>. This
5111 directory is part of the base system and should not owned
5112 by any particular mail agents. The use of the old
5113 location <file>/var/spool/mail</file> is deprecated, even
5114 though the spool may still be physically located there.
5115 To maintain partial upgrade compatibility for systems
5116 which have <file>/var/spool/mail</file> as their physical mail
5117 spool, packages using <file>/var/mail</file> must depend on
5118 either <package>libc6</package> (>= 2.1.3-13), or on
5119 <package>base-files</package> (>= 2.2.0), or on later
5120 versions of either one of these packages.
5126 <heading>Users and groups</heading>
5129 <heading>Introduction</heading>
5131 The Debian system can be configured to use either plain or
5136 Some user ids (UIDs) and group ids (GIDs) are reserved
5137 globally for use by certain packages. Because some
5138 packages need to include files which are owned by these
5139 users or groups, or need the ids compiled into binaries,
5140 these ids must be used on any Debian system only for the
5141 purpose for which they are allocated. This is a serious
5142 restriction, and we should avoid getting in the way of
5143 local administration policies. In particular, many sites
5144 allocate users and/or local system groups starting at 100.
5148 Apart from this we should have dynamically allocated ids,
5149 which should by default be arranged in some sensible
5150 order, but the behavior should be configurable.
5154 Packages other than <tt>base-passwd</tt> must not modify
5155 <file>/etc/passwd</file>, <file>/etc/shadow</file>,
5156 <file>/etc/group</file> or <file>/etc/gshadow</file>.
5161 <heading>UID and GID classes</heading>
5163 The UID and GID numbers are divided into classes as
5169 Globally allocated by the Debian project, the same
5170 on every Debian system. These ids will appear in
5171 the <file>passwd</file> and <file>group</file> files of all
5172 Debian systems, new ids in this range being added
5173 automatically as the <tt>base-passwd</tt> package is
5178 Packages which need a single statically allocated
5179 uid or gid should use one of these; their
5180 maintainers should ask the <tt>base-passwd</tt>
5188 Dynamically allocated system users and groups.
5189 Packages which need a user or group, but can have
5190 this user or group allocated dynamically and
5191 differently on each system, should use <tt>adduser
5192 --system</tt> to create the group and/or user.
5193 <prgn>adduser</prgn> will check for the existence of
5194 the user or group, and if necessary choose an unused
5195 id based on the ranges specified in
5196 <file>adduser.conf</file>.
5200 <tag>1000-29999:</tag>
5203 Dynamically allocated user accounts. By default
5204 <prgn>adduser</prgn> will choose UIDs and GIDs for
5205 user accounts in this range, though
5206 <file>adduser.conf</file> may be used to modify this
5211 <tag>30000-59999:</tag>
5216 <tag>60000-64999:</tag>
5219 Globally allocated by the Debian project, but only
5220 created on demand. The ids are allocated centrally
5221 and statically, but the actual accounts are only
5222 created on users' systems on demand.
5226 These ids are for packages which are obscure or
5227 which require many statically-allocated ids. These
5228 packages should check for and create the accounts in
5229 <file>/etc/passwd</file> or <file>/etc/group</file> (using
5230 <prgn>adduser</prgn> if it has this facility) if
5231 necessary. Packages which are likely to require
5232 further allocations should have a "hole" left after
5233 them in the allocation, to give them room to
5238 <tag>65000-65533:</tag>
5246 User <tt>nobody</tt>. The corresponding gid refers
5247 to the group <tt>nogroup</tt>.
5254 <tt>(uid_t)(-1) == (gid_t)(-1)</tt> <em>must
5255 not</em> be used, because it is the error return
5264 <sect id="sysvinit">
5265 <heading>System run levels and <file>init.d</file> scripts</heading>
5267 <sect1 id="/etc/init.d">
5268 <heading>Introduction</heading>
5271 The <file>/etc/init.d</file> directory contains the scripts
5272 executed by <prgn>init</prgn> at boot time and when the
5273 init state (or "runlevel") is changed (see <manref
5274 name="init" section="8">).
5278 There are at least two different, yet functionally
5279 equivalent, ways of handling these scripts. For the sake
5280 of simplicity, this document describes only the symbolic
5281 link method. However, it must not be assumed by maintainer
5282 scripts that this method is being used, and any automated
5283 manipulation of the various runlevel behaviours by
5284 maintainer scripts must be performed using
5285 <prgn>update-rc.d</prgn> as described below and not by
5286 manually installing or removing symlinks. For information
5287 on the implementation details of the other method,
5288 implemented in the <tt>file-rc</tt> package, please refer
5289 to the documentation of that package.
5293 These scripts are referenced by symbolic links in the
5294 <file>/etc/rc<var>n</var>.d</file> directories. When changing
5295 runlevels, <prgn>init</prgn> looks in the directory
5296 <file>/etc/rc<var>n</var>.d</file> for the scripts it should
5297 execute, where <tt><var>n</var></tt> is the runlevel that
5298 is being changed to, or <tt>S</tt> for the boot-up
5303 The names of the links all have the form
5304 <file>S<var>mm</var><var>script</var></file> or
5305 <file>K<var>mm</var><var>script</var></file> where
5306 <var>mm</var> is a two-digit number and <var>script</var>
5307 is the name of the script (this should be the same as the
5308 name of the actual script in <file>/etc/init.d</file>).
5312 When <prgn>init</prgn> changes runlevel first the targets
5313 of the links whose names start with a <tt>K</tt> are
5314 executed, each with the single argument <tt>stop</tt>,
5315 followed by the scripts prefixed with an <tt>S</tt>, each
5316 with the single argument <tt>start</tt>. (The links are
5317 those in the <file>/etc/rc<var>n</var>.d</file> directory
5318 corresponding to the new runlevel.) The <tt>K</tt> links
5319 are responsible for killing services and the <tt>S</tt>
5320 link for starting services upon entering the runlevel.
5324 For example, if we are changing from runlevel 2 to
5325 runlevel 3, init will first execute all of the <tt>K</tt>
5326 prefixed scripts it finds in <file>/etc/rc3.d</file>, and then
5327 all of the <tt>S</tt> prefixed scripts in that directory.
5328 The links starting with <tt>K</tt> will cause the
5329 referred-to file to be executed with an argument of
5330 <tt>stop</tt>, and the <tt>S</tt> links with an argument
5335 The two-digit number <var>mm</var> is used to determine
5336 the order in which to run the scripts: low-numbered links
5337 have their scripts run first. For example, the
5338 <tt>K20</tt> scripts will be executed before the
5339 <tt>K30</tt> scripts. This is used when a certain service
5340 must be started before another. For example, the name
5341 server <prgn>bind</prgn> might need to be started before
5342 the news server <prgn>inn</prgn> so that <prgn>inn</prgn>
5343 can set up its access lists. In this case, the script
5344 that starts <prgn>bind</prgn> would have a lower number
5345 than the script that starts <prgn>inn</prgn> so that it
5347 <example compact="compact">
5354 The two runlevels 0 (halt) and 6 (reboot) are slightly
5355 different. In these runlevels, the links with an
5356 <tt>S</tt> prefix are still called after those with a
5357 <tt>K</tt> prefix, but they too are called with the single
5358 argument <tt>stop</tt>.
5362 Also, if the script name ends <tt>.sh</tt>, the script
5363 will be sourced in runlevel <tt>S</tt> rather that being
5364 run in a forked subprocess, but will be explicitly run by
5365 <prgn>sh</prgn> in all other runlevels.
5370 <heading>Writing the scripts</heading>
5373 Packages that include daemons for system services should
5374 place scripts in <file>/etc/init.d</file> to start or stop
5375 services at boot time or during a change of runlevel.
5376 These scripts should be named
5377 <file>/etc/init.d/<var>package</var></file>, and they should
5378 accept one argument, saying what to do:
5381 <tag><tt>start</tt></tag>
5382 <item>start the service,</item>
5384 <tag><tt>stop</tt></tag>
5385 <item>stop the service,</item>
5387 <tag><tt>restart</tt></tag>
5388 <item>stop and restart the service if it's already running,
5389 otherwise start the service</item>
5391 <tag><tt>reload</tt></tag>
5392 <item><p>cause the configuration of the service to be
5393 reloaded without actually stopping and restarting
5396 <tag><tt>force-reload</tt></tag>
5397 <item>cause the configuration to be reloaded if the
5398 service supports this, otherwise restart the
5402 The <tt>start</tt>, <tt>stop</tt>, <tt>restart</tt>, and
5403 <tt>force-reload</tt> options should be supported by all
5404 scripts in <file>/etc/init.d</file>, the <tt>reload</tt>
5409 The <file>init.d</file> scripts should ensure that they will
5410 behave sensibly if invoked with <tt>start</tt> when the
5411 service is already running, or with <tt>stop</tt> when it
5412 isn't, and that they don't kill unfortunately-named user
5413 processes. The best way to achieve this is usually to use
5414 <prgn>start-stop-daemon</prgn>.
5418 If a service reloads its configuration automatically (as
5419 in the case of <prgn>cron</prgn>, for example), the
5420 <tt>reload</tt> option of the <file>init.d</file> script
5421 should behave as if the configuration has been reloaded
5426 The <file>/etc/init.d</file> scripts must be treated as
5427 configuration files, either (if they are present in the
5428 package, that is, in the .deb file) by marking them as
5429 <tt>conffile</tt>s, or, (if they do not exist in the .deb)
5430 by managing them correctly in the maintainer scripts (see
5431 <ref id="config-files">). This is important since we want
5432 to give the local system administrator the chance to adapt
5433 the scripts to the local system, e.g., to disable a
5434 service without de-installing the package, or to specify
5435 some special command line options when starting a service,
5436 while making sure her changes aren't lost during the next
5441 These scripts should not fail obscurely when the
5442 configuration files remain but the package has been
5443 removed, as configuration files remain on the system after
5444 the package has been removed. Only when <prgn>dpkg</prgn>
5445 is executed with the <tt>--purge</tt> option will
5446 configuration files be removed. In particular, as the
5447 <file>/etc/init.d/<var>package</var></file> script itself is
5448 usually a <tt>conffile</tt>, it will remain on the system
5449 if the package is removed but not purged. Therefore, you
5450 should include a <tt>test</tt> statement at the top of the
5452 <example compact="compact">
5453 test -f <var>program-executed-later-in-script</var> || exit 0
5458 Often there are some variables in the <file>init.d</file>
5459 scripts whose values control the behaviour of the scripts,
5460 and which a system administrator is likely to want to
5461 change. As the scripts themselves are frequently
5462 <tt>conffile</tt>s, modifying them requires that the
5463 administrator merge in their changes each time the package
5464 is upgraded and the <tt>conffile</tt> changes. To ease
5465 the burden on the system administrator, such configurable
5466 values should not be placed directly in the script.
5467 Instead, they should be placed in a file in
5468 <file>/etc/default</file>, which typically will have the same
5469 base name as the <file>init.d</file> script. This extra file
5470 should be sourced by the script when the script runs. It
5471 must contain only variable settings and comments in POSIX
5472 <prgn>sh</prgn> format. It may either be a
5473 <tt>conffile</tt> or a configuration file maintained by
5474 the package maintainer scripts. See <ref id="config-files">
5479 To ensure that vital configurable values are always
5480 available, the <file>init.d</file> script should set default
5481 values for each of the shell variables it uses, either
5482 before sourcing the <file>/etc/default/</file> file or
5483 afterwards using something like the <tt>:
5484 ${VAR:=default}</tt> syntax. Also, the <file>init.d</file>
5485 script must behave sensibly and not fail if the
5486 <file>/etc/default</file> file is deleted.
5491 <heading>Interfacing with the initscript system</heading>
5494 Maintainers should use the abstraction layer provided by
5495 the <prgn>update-rc.d</prgn> and <prgn>invoke-rc.d</prgn>
5496 programs to deal with initscripts in their packages'
5497 scripts such as <prgn>postinst</prgn>, <prgn>prerm</prgn>
5498 and <prgn>postrm</prgn>.
5502 Directly managing the /etc/rc?.d links and directly
5503 invoking the <file>/etc/init.d/</file> initscripts should
5504 be done only by packages providing the initscript
5505 subsystem (such as <prgn>sysv-rc</prgn> and
5506 <prgn>file-rc</prgn>).
5510 <heading>Managing the links</heading>
5513 The program <prgn>update-rc.d</prgn> is provided for
5514 package maintainers to arrange for the proper creation and
5515 removal of <file>/etc/rc<var>n</var>.d</file> symbolic links,
5516 or their functional equivalent if another method is being
5517 used. This may be used by maintainers in their packages'
5518 <prgn>postinst</prgn> and <prgn>postrm</prgn> scripts.
5522 You must not include any <file>/etc/rc<var>n</var>.d</file>
5523 symbolic links in the actual archive or manually create or
5524 remove the symbolic links in maintainer scripts; you must
5525 use the <prgn>update-rc.d</prgn> program instead. (The
5526 former will fail if an alternative method of maintaining
5527 runlevel information is being used.) You must not include
5528 the <file>/etc/rc<var>n</var>.d</file> directories themselves
5529 in the archive either. (Only the <tt>sysvinit</tt>
5534 By default <prgn>update-rc.d</prgn> will start services in
5535 each of the multi-user state runlevels (2, 3, 4, and 5)
5536 and stop them in the halt runlevel (0), the single-user
5537 runlevel (1) and the reboot runlevel (6). The system
5538 administrator will have the opportunity to customize
5539 runlevels by simply adding, moving, or removing the
5540 symbolic links in <file>/etc/rc<var>n</var>.d</file> if
5541 symbolic links are being used, or by modifying
5542 <file>/etc/runlevel.conf</file> if the <tt>file-rc</tt> method
5547 To get the default behavior for your package, put in your
5548 <prgn>postinst</prgn> script
5549 <example compact="compact">
5550 update-rc.d <var>package</var> defaults
5552 and in your <prgn>postrm</prgn>
5553 <example compact="compact">
5554 if [ "$1" = purge ]; then
5555 update-rc.d <var>package</var> remove
5557 </example>. Note that if your package changes runlevels
5558 or priority, you may have to remove and recreate the links,
5559 since otherwise the old links may persist. Refer to the
5560 documentation of <prgn>update-rc.d</prgn>.
5564 This will use a default sequence number of 20. If it does
5565 not matter when or in which order the <file>init.d</file>
5566 script is run, use this default. If it does, then you
5567 should talk to the maintainer of the <prgn>sysvinit</prgn>
5568 package or post to <tt>debian-devel</tt>, and they will
5569 help you choose a number.
5573 For more information about using <tt>update-rc.d</tt>,
5574 please consult its manpage <manref name="update-rc.d"
5580 <heading>Running initscripts</heading>
5582 The program <prgn>invoke-rc.d</prgn> is provided to make
5583 it easier for package maintainers to properly invoke an
5584 initscript, obeying runlevel and other locally-defined
5585 constraints that might limit a package's right to start,
5586 stop and otherwise manage services. This program may be
5587 used by maintainers in their packages' scripts.
5591 The use of <prgn>invoke-rc.d</prgn> to invoke the
5592 <file>/etc/init.d/*</file> initscripts is strongly
5593 recommended<footnote>
5594 In the future, the use of invoke-rc.d to invoke
5595 initscripts shall be made mandatory. Maintainers are
5596 advised to switch to invoke-rc.d as soon as
5598 </footnote>, instead of calling them directly.
5602 By default, <prgn>invoke-rc.d</prgn> will pass any
5603 action requests (start, stop, reload, restart...) to the
5604 <file>/etc/init.d</file> script, filtering out requests
5605 to start or restart a service out of its intended
5610 Most packages will simply need to change:
5611 <example compact="compact">/etc/init.d/<package>
5612 <action></example> in their <prgn>postinst</prgn>
5613 and <prgn>prerm</prgn> scripts to:
5614 <example compact="compact">
5615 if command -v invoke-rc.d >/dev/null 2>&1; then
5616 invoke-rc.d <var>package</var> <action>
5618 /etc/init.d/<var>package</var> <action>
5624 A package should register its initscript services using
5625 <prgn>update-rc.d</prgn> before it tries to invoke them
5626 using <prgn>invoke-rc.d</prgn>. Invocation of
5627 unregistered services may fail.
5631 For more information about using
5632 <prgn>invoke-rc.d</prgn>, please consult its manpage
5633 <manref name="invoke-rc.d" section="8">.
5639 <heading>Boot-time initialization</heading>
5642 There used to be another directory, <file>/etc/rc.boot</file>,
5643 which contained scripts which were run once per machine
5644 boot. This has been deprecated in favour of links from
5645 <file>/etc/rcS.d</file> to files in <file>/etc/init.d</file> as
5646 described in <ref id="/etc/init.d">. Packages must not
5647 place files in <file>/etc/rc.boot</file>.
5652 <heading>Example</heading>
5655 The <prgn>bind</prgn> DNS (nameserver) package wants to
5656 make sure that the nameserver is running in multiuser
5657 runlevels, and is properly shut down with the system. It
5658 puts a script in <file>/etc/init.d</file>, naming the script
5659 appropriately <tt>bind</tt>. As you can see, the script
5660 interprets the argument <tt>reload</tt> to send the
5661 nameserver a <tt>HUP</tt> signal (causing it to reload its
5662 configuration); this way the system administrator can say
5663 <tt>/etc/init.d/bind reload</tt> to reload the name
5664 server. The script has one configurable value, which can
5665 be used to pass parameters to the named program at
5666 startup; this value is read from
5667 <file>/etc/default/bind</file> (see below).
5671 <example compact="compact">
5674 # Original version by Robert Leslie
5675 # <rob@mars.org>, edited by iwj and cs
5677 test -x /usr/sbin/named || exit 0
5679 # Source defaults file.
5681 if [ -f /etc/default/bind ]; then
5688 echo -n "Starting domain name service: named"
5689 start-stop-daemon --start --quiet --exec /usr/sbin/named \
5694 echo -n "Stopping domain name service: named"
5695 start-stop-daemon --stop --quiet \
5696 --pidfile /var/run/named.pid --exec /usr/sbin/named
5700 echo -n "Restarting domain name service: named"
5701 start-stop-daemon --stop --quiet --oknodo \
5702 --pidfile /var/run/named.pid --exec /usr/sbin/named
5703 start-stop-daemon --start --verbose --exec /usr/sbin/named \
5707 force-reload|reload)
5708 echo -n "Reloading configuration of domain name service: named"
5709 start-stop-daemon --stop --signal 1 --quiet \
5710 --pidfile /var/run/named.pid --exec /usr/sbin/named
5714 echo "Usage: /etc/init.d/bind " \
5715 " {start|stop|restart|reload|force-reload}" >&2
5725 Complementing the above init script is a configuration
5726 file <file>/etc/default/bind</file>, which contains
5727 configurable parameters used by the script. This would be
5728 created by the <prgn>postinst</prgn> script if it was not
5729 already present, and removed on purge by the
5730 <prgn>postrm</prgn> script.
5731 <example compact="compact">
5732 # Specified parameters to pass to named. See named(8).
5733 # You may uncomment the following line, and edit to taste.
5739 Another example on which you can base your
5740 <file>/etc/init.d</file> scripts is found in
5741 <file>/etc/init.d/skeleton</file>.
5745 If this package is happy with the default setup from
5746 <prgn>update-rc.d</prgn>, namely an ordering number of 20
5747 and having named running in all runlevels, it can say in
5748 its <prgn>postinst</prgn>:
5749 <example compact="compact">
5750 update-rc.d bind defaults >/dev/null
5752 And in its <prgn>postrm</prgn>, to remove the links when the
5754 <example compact="compact">
5755 if [ "$1" = purge ]; then
5756 update-rc.d bind remove >/dev/null
5764 <heading>Console messages from <file>init.d</file> scripts</heading>
5767 This section describes the formats to be used for messages
5768 written to standard output by the <file>/etc/init.d</file>
5769 scripts. The intent is to improve the consistency of
5770 Debian's startup and shutdown look and feel. For this
5771 reason, please look very carefully at the details. We want
5772 the messages to have the same format in terms of wording,
5773 spaces, punctuation and case of letters.
5777 Here is a list of overall rules that you should use when you
5778 create output messages. They can be useful if you have a
5779 non-standard message that is not covered specifically in the
5786 Every message should fit in one line (fewer than 80
5787 characters), start with a capital letter and end with
5788 a period (<tt>.</tt>) and line feed (<tt>"\n"</tt>).
5792 If you want to express that the computer is working on
5793 something (that is, performing a specific task, not
5794 starting or stopping a program), we use an "ellipsis"
5795 (three dots: <tt>...</tt>). Note that we don't insert
5796 spaces before or after the dots. If the task has been
5797 completed we write <tt>done.</tt> and a line feed.
5801 Design your messages as if the computer is telling you
5802 what he is doing (let him be polite :-), but don't
5803 mention "him" directly. For example, if you think of
5805 <example compact="compact">
5806 I'm starting network daemons: nfsd mountd.
5809 <example compact="compact">
5810 Starting network daemons: nfsd mountd.
5817 There are standard message formats for the following
5818 situations. They should be used by the <tt>init.d</tt>
5825 <p>When daemons are started</p>
5828 If your script starts one or more daemons, the output
5829 should look like this (a single line, no leading
5831 <example compact="compact">
5832 Starting <var>description</var>: <var>daemon-1</var> ... <var>daemon-n</var>.
5834 The <var>description</var> should describe the
5835 subsystem the daemon or set of daemons are part of,
5836 while <var>daemon-1</var> up to <var>daemon-n</var>
5837 denote each daemon's name (typically the file name of
5842 For example, the output of <file>/etc/init.d/lpd</file>
5844 <example compact="compact">
5845 Starting printer spooler: lpd.
5850 This can be achieved by saying
5851 <example compact="compact">
5852 echo -n "Starting printer spooler: lpd"
5853 start-stop-daemon --start --quiet --exec /usr/sbin/lpd
5856 in the script. If you have more than one daemon to
5857 start, you should do the following:
5858 <example compact="compact">
5859 echo -n "Starting remote file system services:"
5860 echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
5861 echo -n " mountd"; start-stop-daemon --start --quiet mountd
5862 echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
5865 This makes it possible for the user to see what takes
5866 so long and when the final daemon has been started.
5867 You should be careful where to put spaces: in the
5868 example above the system administrator can easily
5869 comment out a line if he don't wants to start a
5870 specific daemon, while the displayed message still
5876 <p>When a system parameter is being set</p>
5879 If you have to set up different system parameters
5880 during the system boot, you should use this format:
5881 <example compact="compact">
5882 Setting <var>parameter</var> to "<var>value</var>".
5887 You can use a statement such as the following to get
5889 <example compact="compact">
5890 echo "Setting DNS domainname to \"$domainname\"."
5895 Note that the same symbol (<tt>"</tt>) is used for the left
5896 and right quotation marks. A grave accent (<tt>`</tt>) is
5897 not a quote character; neither is an apostrophe
5903 <p>When a daemon is stopped or restarted</p>
5906 When you stop or restart a daemon, you should issue a
5907 message identical to the startup message, except that
5908 <tt>Starting</tt> is replaced with <tt>Stopping</tt>
5909 or <tt>Restarting</tt> respectively.
5913 For example, stopping the printer daemon will like
5915 <example compact="compact">
5916 Stopping printer spooler: lpd.
5922 <p>When something is executed</p>
5925 There are several examples where you have to run a
5926 program at system startup or shutdown to perform a
5927 specific task, for example, setting the system's clock
5928 using <prgn>netdate</prgn> or killing all processes
5929 when the system shuts down. Your message should look
5931 <example compact="compact">
5932 Doing something very useful...done.
5934 You should print the <tt>done.</tt> immediately after
5935 the job has been completed, so that the user is
5936 informed why she has to wait. You can get this
5938 <example compact="compact">
5939 echo -n "Doing something very useful..."
5948 <p>When the configuration is reloaded</p>
5951 When a daemon is forced to reload its configuration
5952 files you should use the following format:
5953 <example compact="compact">
5954 Reloading <var>description</var> configuration...done.
5956 where <var>description</var> is the same as in the
5957 daemon starting message.
5965 <heading>Cron jobs</heading>
5968 Packages must not modify the configuration file
5969 <file>/etc/crontab</file>, and they must not modify the files in
5970 <file>/var/spool/cron/crontabs</file>.</p>
5973 If a package wants to install a job that has to be executed
5974 via cron, it should place a file with the name of the
5975 package in one or more of the following directories:
5976 <example compact="compact">
5981 As these directory names imply, the files within them are
5982 executed on a daily, weekly, or monthly basis,
5983 respectively. The exact times are listed in
5984 <file>/etc/crontab</file>.</p>
5987 All files installed in any of these directories must be
5988 scripts (e.g., shell scripts or Perl scripts) so that they
5989 can easily be modified by the local system administrator.
5990 In addition, they should be treated as configuration
5995 If a certain job has to be executed more frequently than
5996 daily, the package should install a file
5997 <file>/etc/cron.d/<var>package</var></file>. This file uses the
5998 same syntax as <file>/etc/crontab</file> and is processed by
5999 <prgn>cron</prgn> automatically. The file must also be
6000 treated as a configuration file. (Note that entries in the
6001 <file>/etc/cron.d</file> directory are not handled by
6002 <prgn>anacron</prgn>. Thus, you should only use this
6003 directory for jobs which may be skipped if the system is not
6007 The scripts or crontab entries in these directories should
6008 check if all necessary programs are installed before they
6009 try to execute them. Otherwise, problems will arise when a
6010 package was removed but not purged since configuration files
6011 are kept on the system in this situation.</p>
6015 <heading>Menus</heading>
6018 The Debian <tt>menu</tt> package provides a standard
6019 interface between packages providing applications and
6020 documents, and <em>menu programs</em> (either X window
6021 managers or text-based menu programs such as
6022 <prgn>pdmenu</prgn>).
6026 All packages that provide applications that need not be
6027 passed any special command line arguments for normal
6028 operation should register a menu entry for those
6029 applications, so that users of the <tt>menu</tt> package
6030 will automatically get menu entries in their window
6031 managers, as well in shells like <tt>pdmenu</tt>.
6035 Menu entries should follow the current menu policy.
6039 The menu policy can be found in the <tt>menu-policy</tt>
6040 files in the <tt>debian-policy</tt> package.
6041 It is also available from the Debian web mirrors at
6042 <tt><url name="/doc/packaging-manuals/menu-policy/"
6043 id="http://www.debian.org/doc/packaging-manuals/menu-policy/"></tt>
6044 and from the Debian archive mirrors at
6045 <tt><url name="/doc/package-developer/menu-policy.txt.gz"
6046 id="http://ftp.debian.org/debian/doc/package-developer/menu-policy.txt.gz"></tt>.
6050 Please also refer to the <em>Debian Menu System</em>
6051 documentation that comes with the <tt>menu</tt> package for
6052 information about how to register your applications and web
6058 <heading>Multimedia handlers</heading>
6061 MIME (Multipurpose Internet Mail Extensions, RFCs 2045-2049)
6062 is a mechanism for encoding files and data streams and
6063 providing meta-information about them, in particular their
6064 type (e.g. audio or video) and format (e.g. PNG, HTML,
6069 Registration of MIME type handlers allows programs like mail
6070 user agents and web browsers to invoke these handlers to
6071 view, edit or display MIME types they don't support directly.
6075 Packages which provide the ability to view/show/play,
6076 compose, edit or print MIME types should register themselves
6077 as such following the current MIME support policy.
6081 The MIME support policy can be found in the <tt>mime-policy</tt>
6082 files in the <tt>debian-policy</tt> package.
6083 It is also available from the Debian web mirrors at
6084 <tt><url name="/doc/packaging-manuals/mime-policy/"
6085 id="http://www.debian.org/doc/packaging-manuals/mime-policy/"></tt>
6086 and from the Debian archive mirrors at
6087 <tt><url name="/doc/package-developer/mime-policy.txt.gz"
6088 id="http://ftp.debian.org/debian/doc/package-developer/mime-policy.txt.gz"></tt>.
6094 <heading>Keyboard configuration</heading>
6097 To achieve a consistent keyboard configuration so that all
6098 applications interpret a keyboard event the same way, all
6099 programs in the Debian distribution must be configured to
6100 comply with the following guidelines.
6104 The following keys must have the specified interpretations:
6107 <tag><tt><--</tt></tag>
6108 <item>delete the character to the left of the cursor</item>
6110 <tag><tt>Delete</tt></tag>
6111 <item>delete the character to the right of the cursor</item>
6113 <tag><tt>Control+H</tt></tag>
6114 <item>emacs: the help prefix</item>
6117 The interpretation of any keyboard events should be
6118 independent of the terminal that is used, be it a virtual
6119 console, an X terminal emulator, an rlogin/telnet session,
6124 The following list explains how the different programs
6125 should be set up to achieve this:
6131 <tt><--</tt> generates <tt>KB_BackSpace</tt> in X.
6135 <tt>Delete</tt> generates <tt>KB_Delete</tt> in X.
6139 X translations are set up to make
6140 <tt>KB_Backspace</tt> generate ASCII DEL, and to make
6141 <tt>KB_Delete</tt> generate <tt>ESC [ 3 ~</tt> (this
6142 is the vt220 escape code for the "delete character"
6143 key). This must be done by loading the X resources
6144 using <prgn>xrdb</prgn> on all local X displays, not
6145 using the application defaults, so that the
6146 translation resources used correspond to the
6147 <prgn>xmodmap</prgn> settings.
6151 The Linux console is configured to make
6152 <tt><--</tt> generate DEL, and <tt>Delete</tt>
6153 generate <tt>ESC [ 3 ~</tt>.
6157 X applications are configured so that <tt><</tt>
6158 deletes left, and <tt>Delete</tt> deletes right. Motif
6159 applications already work like this.
6163 Terminals should have <tt>stty erase ^?</tt> .
6167 The <tt>xterm</tt> terminfo entry should have <tt>ESC
6168 [ 3 ~</tt> for <tt>kdch1</tt>, just as for
6169 <tt>TERM=linux</tt> and <tt>TERM=vt220</tt>.
6173 Emacs is programmed to map <tt>KB_Backspace</tt> or
6174 the <tt>stty erase</tt> character to
6175 <tt>delete-backward-char</tt>, and <tt>KB_Delete</tt>
6176 or <tt>kdch1</tt> to <tt>delete-forward-char</tt>, and
6177 <tt>^H</tt> to <tt>help</tt> as always.
6181 Other applications use the <tt>stty erase</tt>
6182 character and <tt>kdch1</tt> for the two delete keys,
6183 with ASCII DEL being "delete previous character" and
6184 <tt>kdch1</tt> being "delete character under
6192 This will solve the problem except for the following
6199 Some terminals have a <tt><--</tt> key that cannot
6200 be made to produce anything except <tt>^H</tt>. On
6201 these terminals Emacs help will be unavailable on
6202 <tt>^H</tt> (assuming that the <tt>stty erase</tt>
6203 character takes precedence in Emacs, and has been set
6204 correctly). <tt>M-x help</tt> or <tt>F1</tt> (if
6205 available) can be used instead.
6209 Some operating systems use <tt>^H</tt> for <tt>stty
6210 erase</tt>. However, modern telnet versions and all
6211 rlogin versions propagate <tt>stty</tt> settings, and
6212 almost all UNIX versions honour <tt>stty erase</tt>.
6213 Where the <tt>stty</tt> settings are not propagated
6214 correctly, things can be made to work by using
6215 <tt>stty</tt> manually.
6219 Some systems (including previous Debian versions) use
6220 <prgn>xmodmap</prgn> to arrange for both
6221 <tt><--</tt> and <tt>Delete</tt> to generate
6222 <tt>KB_Delete</tt>. We can change the behavior of
6223 their X clients using the same X resources that we use
6224 to do it for our own clients, or configure our clients
6225 using their resources when things are the other way
6226 around. On displays configured like this
6227 <tt>Delete</tt> will not work, but <tt><--</tt>
6232 Some operating systems have different <tt>kdch1</tt>
6233 settings in their <tt>terminfo</tt> database for
6234 <tt>xterm</tt> and others. On these systems the
6235 <tt>Delete</tt> key will not work correctly when you
6236 log in from a system conforming to our policy, but
6237 <tt><--</tt> will.
6244 <heading>Environment variables</heading>
6247 A program must not depend on environment variables to get
6248 reasonable defaults. (That's because these environment
6249 variables would have to be set in a system-wide
6250 configuration file like <file>/etc/profile</file>, which is not
6251 supported by all shells.)
6255 If a program usually depends on environment variables for its
6256 configuration, the program should be changed to fall back to
6257 a reasonable default configuration if these environment
6258 variables are not present. If this cannot be done easily
6259 (e.g., if the source code of a non-free program is not
6260 available), the program must be replaced by a small
6261 "wrapper" shell script which sets the environment variables
6262 if they are not already defined, and calls the original program.
6266 Here is an example of a wrapper script for this purpose:
6268 <example compact="compact">
6270 BAR=${BAR:-/var/lib/fubar}
6272 exec /usr/lib/foo/foo "$@"
6277 Furthermore, as <file>/etc/profile</file> is a configuration
6278 file of the <prgn>base-files</prgn> package, other packages must
6279 not put any environment variables or other commands into that
6288 <heading>Files</heading>
6291 <heading>Binaries</heading>
6294 Two different packages must not install programs with
6295 different functionality but with the same filenames. (The
6296 case of two programs having the same functionality but
6297 different implementations is handled via "alternatives" or
6298 the "Conflicts" mechanism. See <ref id="maintscripts"> and
6299 <ref id="conflicts"> respectively.) If this case happens,
6300 one of the programs must be renamed. The maintainers should
6301 report this to the <tt>debian-devel</tt> mailing list and
6302 try to find a consensus about which program will have to be
6303 renamed. If a consensus cannot be reached, <em>both</em>
6304 programs must be renamed.
6308 By default, when a package is being built, any binaries
6309 created should include debugging information, as well as
6310 being compiled with optimization. You should also turn on
6311 as many reasonable compilation warnings as possible; this
6312 makes life easier for porters, who can then look at build
6313 logs for possible problems. For the C programming language,
6314 this means the following compilation parameters should be
6316 <example compact="compact">
6318 CFLAGS = -O2 -g -Wall # sane warning options vary between programs
6320 install -s # (or use strip on the files in debian/tmp)
6325 Note that by default all installed binaries should be stripped,
6326 either by using the <tt>-s</tt> flag to
6327 <prgn>install</prgn>, or by calling <prgn>strip</prgn> on
6328 the binaries after they have been copied into
6329 <file>debian/tmp</file> but before the tree is made into a
6334 Although binaries in the build tree should be compiled with
6335 debugging information by default, it can often be difficult
6336 to debug programs if they are also subjected to compiler
6337 optimization. For this reason, it is recommended to support
6338 the standardized environment
6339 variable <tt>DEB_BUILD_OPTIONS</tt>. This variable can
6340 contain several flags to change how a package is compiled
6348 The presence of this string means that the package
6349 should be compiled with a minimum of optimization.
6350 For C programs, it is best to add <tt>-O0</tt>
6351 to <tt>CFLAGS</tt> (although this is usually the
6352 default). Some programs might fail to build or run at
6353 this level of optimization; it may be necessary to
6354 use <tt>-O1</tt>, for example.
6358 This string means that the debugging symbols should
6359 not be stripped from the binary during installation,
6360 so that debugging information may be included in the package.
6366 The following makefile snippet is an example of how one may
6367 implement the build options; you will probably have to
6368 massage this example in order to make it work for your
6370 <example compact="compact">
6373 INSTALL_FILE = $(INSTALL) -p -o root -g root -m 644
6374 INSTALL_PROGRAM = $(INSTALL) -p -o root -g root -m 755
6375 INSTALL_SCRIPT = $(INSTALL) -p -o root -g root -m 755
6376 INSTALL_DIR = $(INSTALL) -p -d -o root -g root -m 755
6378 ifneq (,$(findstring noopt,$(DEB_BUILD_OPTIONS)))
6383 ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS)))
6384 INSTALL_PROGRAM += -s
6390 It is up to the package maintainer to decide what
6391 compilation options are best for the package. Certain
6392 binaries (such as computationally-intensive programs) will
6393 function better with certain flags (<tt>-O3</tt>, for
6394 example); feel free to use them. Please use good judgment
6395 here. Don't use flags for the sake of it; only use them
6396 if there is good reason to do so. Feel free to override
6397 the upstream author's ideas about which compilation
6398 options are best: they are often inappropriate for our
6404 <sect id="libraries">
6405 <heading>Libraries</heading>
6408 The shared version of a library must be compiled with
6409 <tt>-fPIC</tt>, and the static version must not be. In other
6410 words, each source unit (<tt>*.c</tt>, for example, for C files)
6411 will need to be compiled twice.
6415 You must specify the gcc option <tt>-D_REENTRANT</tt>
6416 when building a library (either static or shared) to make
6417 the library compatible with LinuxThreads.
6421 Although not enforced by the build tools, shared libraries
6422 must be linked against all libraries that they use symbols from
6423 in the same way that binaries are. This ensures the correct
6424 functioning of the <qref id="sharedlibs-shlibdeps">shlibs</qref>
6425 system and guarantees that all libraries can be safely opened
6426 with <tt>dlopen()</tt>. Packagers may wish to use the gcc
6427 option <tt>-Wl,-z,defs</tt> when building a shared library.
6428 Since this option enforces symbol resolution at build time,
6429 a missing library reference will be caught early as a fatal
6434 All installed shared libraries should be stripped with
6435 <example compact="compact">
6436 strip --strip-unneeded <var>your-lib</var>
6438 (The option <tt>--strip-unneeded</tt> makes
6439 <prgn>strip</prgn> remove only the symbols which aren't
6440 needed for relocation processing.) Shared libraries can
6441 function perfectly well when stripped, since the symbols for
6442 dynamic linking are in a separate part of the ELF object
6444 You might also want to use the options
6445 <tt>--remove-section=.comment</tt> and
6446 <tt>--remove-section=.note</tt> on both shared libraries
6447 and executables, and <tt>--strip-debug</tt> on static
6453 Note that under some circumstances it may be useful to
6454 install a shared library unstripped, for example when
6455 building a separate package to support debugging.
6459 Shared object files (often <file>.so</file> files) that are not
6460 public libraries, that is, they are not meant to be linked
6461 to by third party executables (binaries of other packages),
6462 should be installed in subdirectories of the
6463 <file>/usr/lib</file> directory. Such files are exempt from the
6464 rules that govern ordinary shared libraries, except that
6465 they must not be installed executable and should be
6467 A common example are the so-called "plug-ins",
6468 internal shared objects that are dynamically loaded by
6469 programs using <manref name="dlopen" section="3">.
6474 Packages containing shared libraries that may be linked to
6475 by other packages' binaries, but which for some
6476 <em>compelling</em> reason can not be installed in
6477 <file>/usr/lib</file> directory, may install the shared library
6478 files in subdirectories of the <file>/usr/lib</file> directory,
6479 in which case they should arrange to add that directory in
6480 <file>/etc/ld.so.conf</file> in the package's post-installation
6481 script, and remove it in the package's post-removal script.
6485 An ever increasing number of packages are using
6486 <prgn>libtool</prgn> to do their linking. The latest GNU
6487 libtools (>= 1.3a) can take advantage of the metadata in the
6488 installed <prgn>libtool</prgn> archive files (<file>*.la</file>
6489 files). The main advantage of <prgn>libtool</prgn>'s
6490 <file>.la</file> files is that it allows <prgn>libtool</prgn> to
6491 store and subsequently access metadata with respect to the
6492 libraries it builds. <prgn>libtool</prgn> will search for
6493 those files, which contain a lot of useful information about
6494 a library (such as library dependency information for static
6495 linking). Also, they're <em>essential</em> for programs
6496 using <tt>libltdl</tt>.<footnote>
6497 Although <prgn>libtool</prgn> is fully capable of
6498 linking against shared libraries which don't have
6499 <tt>.la</tt> files, as it is a mere shell script it can
6500 add considerably to the build time of a
6501 <prgn>libtool</prgn>-using package if that shell script
6502 has to derive all this information from first principles
6503 for each library every time it is linked. With the
6504 advent of <prgn>libtool</prgn> version 1.4 (and to a
6505 lesser extent <prgn>libtool</prgn> version 1.3), the
6506 <file>.la</file> files also store information about
6507 inter-library dependencies which cannot necessarily be
6508 derived after the <file>.la</file> file is deleted.
6513 Packages that use <prgn>libtool</prgn> to create shared
6514 libraries should include the <file>.la</file> files in the
6515 <tt>-dev</tt> package, unless the package relies on
6516 <tt>libtool</tt>'s <tt>libltdl</tt> library, in which case
6517 the <tt>.la</tt> files must go in the run-time library
6522 You must make sure that you use only released versions of
6523 shared libraries to build your packages; otherwise other
6524 users will not be able to run your binaries
6525 properly. Producing source packages that depend on
6526 unreleased compilers is also usually a bad
6533 <heading>Shared libraries</heading>
6535 This section has moved to <ref id="sharedlibs">.
6541 <heading>Scripts</heading>
6544 All command scripts, including the package maintainer
6545 scripts inside the package and used by <prgn>dpkg</prgn>,
6546 should have a <tt>#!</tt> line naming the shell to be used
6551 In the case of Perl scripts this should be
6552 <tt>#!/usr/bin/perl</tt>.
6556 Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>)
6557 should almost certainly start with <tt>set -e</tt> so that
6558 errors are detected. Every script should use
6559 <tt>set -e</tt> or check the exit status of <em>every</em>
6564 The standard shell interpreter <file>/bin/sh</file> can be a
6565 symbolic link to any POSIX compatible shell, if <tt>echo
6566 -n</tt> does not generate a newline.<footnote>
6567 Debian policy specifies POSIX behavior for
6568 <file>/bin/sh</file>, but <tt>echo -n</tt> has widespread
6569 use in the Linux community (in particular including this
6570 policy, the Linux kernel source, many Debian scripts,
6571 etc.). This <tt>echo -n</tt> mechanism is valid but not
6572 required under POSIX, hence this explicit addition.
6573 Also, rumour has it that this shall be mandated under
6576 Thus, shell scripts specifying <file>/bin/sh</file> as
6577 interpreter should only use POSIX features. If a script
6578 requires non-POSIX features from the shell interpreter, the
6579 appropriate shell must be specified in the first line of the
6580 script (e.g., <tt>#!/bin/bash</tt>) and the package must
6581 depend on the package providing the shell (unless the shell
6582 package is marked "Essential", as in the case of
6587 You may wish to restrict your script to POSIX features when
6588 possible so that it may use <file>/bin/sh</file> as its
6589 interpreter. If your script works with <prgn>dash</prgn>
6590 (originally called <prgn>ash</prgn>), it's probably POSIX
6591 compliant, but if you are in doubt, use
6592 <file>/bin/bash</file>.
6596 Perl scripts should check for errors when making any
6597 system calls, including <tt>open</tt>, <tt>print</tt>,
6598 <tt>close</tt>, <tt>rename</tt> and <tt>system</tt>.
6602 <prgn>csh</prgn> and <prgn>tcsh</prgn> should be avoided as
6603 scripting languages. See <em>Csh Programming Considered
6604 Harmful</em>, one of the <tt>comp.unix.*</tt> FAQs, which
6605 can be found at <url id="http://language.perl.com/versus/csh.whynot">.
6606 If an upstream package comes with <prgn>csh</prgn> scripts
6607 then you must make sure that they start with
6608 <tt>#!/bin/csh</tt> and make your package depend on the
6609 <prgn>c-shell</prgn> virtual package.
6613 Any scripts which create files in world-writeable
6614 directories (e.g., in <file>/tmp</file>) must use a
6615 mechanism which will fail if a file with the same name
6620 The Debian base system provides the <prgn>tempfile</prgn>
6621 and <prgn>mktemp</prgn> utilities for use by scripts for
6628 <heading>Symbolic links</heading>
6631 In general, symbolic links within a top-level directory
6632 should be relative, and symbolic links pointing from one
6633 top-level directory into another should be absolute. (A
6634 top-level directory is a sub-directory of the root
6635 directory <file>/</file>.)
6639 In addition, symbolic links should be specified as short as
6640 possible, i.e., link targets like <file>foo/../bar</file> are
6645 Note that when creating a relative link using
6646 <prgn>ln</prgn> it is not necessary for the target of the
6647 link to exist relative to the working directory you're
6648 running <prgn>ln</prgn> from, nor is it necessary to change
6649 directory to the directory where the link is to be made.
6650 Simply include the string that should appear as the target
6651 of the link (this will be a pathname relative to the
6652 directory in which the link resides) as the first argument
6657 For example, in your <prgn>Makefile</prgn> or
6658 <file>debian/rules</file>, you can do things like:
6659 <example compact="compact">
6660 ln -fs gcc $(prefix)/bin/cc
6661 ln -fs gcc debian/tmp/usr/bin/cc
6662 ln -fs ../sbin/sendmail $(prefix)/bin/runq
6663 ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
6668 A symbolic link pointing to a compressed file should always
6669 have the same file extension as the referenced file. (For
6670 example, if a file <file>foo.gz</file> is referenced by a
6671 symbolic link, the filename of the link has to end with
6672 "<file>.gz</file>" too, as in <file>bar.gz</file>.)
6677 <heading>Device files</heading>
6680 Packages must not include device files in the package file
6685 If a package needs any special device files that are not
6686 included in the base system, it must call
6687 <prgn>MAKEDEV</prgn> in the <prgn>postinst</prgn> script,
6688 after notifying the user<footnote>
6689 This notification could be done via a (low-priority)
6690 debconf message, or an echo (printf) statement.
6695 Packages must not remove any device files in the
6696 <prgn>postrm</prgn> or any other script. This is left to the
6697 system administrator.
6701 Debian uses the serial devices
6702 <file>/dev/ttyS*</file>. Programs using the old
6703 <file>/dev/cu*</file> devices should be changed to use
6704 <file>/dev/ttyS*</file>.
6708 <sect id="config-files">
6709 <heading>Configuration files</heading>
6712 <heading>Definitions</heading>
6716 <tag>configuration file</tag>
6718 A file that affects the operation of a program, or
6719 provides site- or host-specific information, or
6720 otherwise customizes the behavior of a program.
6721 Typically, configuration files are intended to be
6722 modified by the system administrator (if needed or
6723 desired) to conform to local policy or to provide
6724 more useful site-specific behavior.
6727 <tag><tt>conffile</tt></tag>
6729 A file listed in a package's <tt>conffiles</tt>
6730 file, and is treated specially by <prgn>dpkg</prgn>
6731 (see <ref id="configdetails">).
6737 The distinction between these two is important; they are
6738 not interchangeable concepts. Almost all
6739 <tt>conffile</tt>s are configuration files, but many
6740 configuration files are not <tt>conffiles</tt>.
6744 Note that a script that embeds configuration information
6745 (such as most of the files in <file>/etc/default</file> and
6746 <file>/etc/cron.{daily,weekly,monthly}</file>) is de-facto a
6747 configuration file and should be treated as such.
6752 <heading>Location</heading>
6755 Any configuration files created or used by your package
6756 must reside in <file>/etc</file>. If there are several,
6757 consider creating a subdirectory of <file>/etc</file>
6758 named after your package.
6762 If your package creates or uses configuration files
6763 outside of <file>/etc</file>, and it is not feasible to modify
6764 the package to use <file>/etc</file> directly, put the files
6765 in <file>/etc</file> and create symbolic links to those files
6766 from the location that the package requires.
6771 <heading>Behavior</heading>
6774 Configuration file handling must conform to the following
6776 <list compact="compact">
6778 local changes must be preserved during a package
6782 configuration files must be preserved when the
6783 package is removed, and only deleted when the
6790 The easy way to achieve this behavior is to make the
6791 configuration file a <tt>conffile</tt>. This is
6792 appropriate only if it is possible to distribute a default
6793 version that will work for most installations, although
6794 some system administrators may choose to modify it. This
6795 implies that the default version will be part of the
6796 package distribution, and must not be modified by the
6797 maintainer scripts during installation (or at any other
6802 In order to ensure that local changes are preserved
6803 correctly, no package may contain or make hard links to
6804 conffiles.<footnote>
6805 Rationale: There are two problems with hard links.
6806 The first is that some editors break the link while
6807 editing one of the files, so that the two files may
6808 unwittingly become unlinked and different. The second
6809 is that <prgn>dpkg</prgn> might break the hard link
6810 while upgrading <tt>conffile</tt>s.
6815 The other way to do it is via the maintainer scripts. In
6816 this case, the configuration file must not be listed as a
6817 <tt>conffile</tt> and must not be part of the package
6818 distribution. If the existence of a file is required for
6819 the package to be sensibly configured it is the
6820 responsibility of the package maintainer to provide
6821 maintainer scripts which correctly create, update and
6822 maintain the file and remove it on purge. (See <ref
6823 id="maintainerscripts"> for more information.) These
6824 scripts must be idempotent (i.e., must work correctly if
6825 <prgn>dpkg</prgn> needs to re-run them due to errors
6826 during installation or removal), must cope with all the
6827 variety of ways <prgn>dpkg</prgn> can call maintainer
6828 scripts, must not overwrite or otherwise mangle the user's
6829 configuration without asking, must not ask unnecessary
6830 questions (particularly during upgrades), and otherwise be
6835 The scripts are not required to configure every possible
6836 option for the package, but only those necessary to get
6837 the package running on a given system. Ideally the
6838 sysadmin should not have to do any configuration other
6839 than that done (semi-)automatically by the
6840 <prgn>postinst</prgn> script.
6844 A common practice is to create a script called
6845 <file><var>package</var>-configure</file> and have the
6846 package's <prgn>postinst</prgn> call it if and only if the
6847 configuration file does not already exist. In certain
6848 cases it is useful for there to be an example or template
6849 file which the maintainer scripts use. Such files should
6850 be in <file>/usr/share/<var>package</var></file> or
6851 <file>/usr/lib/<var>package</var></file> (depending on whether
6852 they are architecture-independent or not). There should
6853 be symbolic links to them from
6854 <file>/usr/share/doc/<var>package</var>/examples</file> if
6855 they are examples, and should be perfectly ordinary
6856 <prgn>dpkg</prgn>-handled files (<em>not</em>
6857 configuration files).
6861 These two styles of configuration file handling must
6862 not be mixed, for that way lies madness:
6863 <prgn>dpkg</prgn> will ask about overwriting the file
6864 every time the package is upgraded.
6869 <heading>Sharing configuration files</heading>
6872 Packages which specify the same file as a
6873 <tt>conffile</tt> must be tagged as <em>conflicting</em>
6874 with each other. (This is an instance of the general rule
6875 about not sharing files. Note that neither alternatives
6876 nor diversions are likely to be appropriate in this case;
6877 in particular, <prgn>dpkg</prgn> does not handle diverted
6878 <tt>conffile</tt>s well.)
6882 The maintainer scripts must not alter a <tt>conffile</tt>
6883 of <em>any</em> package, including the one the scripts
6888 If two or more packages use the same configuration file
6889 and it is reasonable for both to be installed at the same
6890 time, one of these packages must be defined as
6891 <em>owner</em> of the configuration file, i.e., it will be
6892 the package which handles that file as a configuration
6893 file. Other packages that use the configuration file must
6894 depend on the owning package if they require the
6895 configuration file to operate. If the other package will
6896 use the configuration file if present, but is capable of
6897 operating without it, no dependency need be declared.
6901 If it is desirable for two or more related packages to
6902 share a configuration file <em>and</em> for all of the
6903 related packages to be able to modify that configuration
6904 file, then the following should be done:
6905 <enumlist compact="compact">
6907 One of the related packages (the "owning" package)
6908 will manage the configuration file with maintainer
6909 scripts as described in the previous section.
6912 The owning package should also provide a program
6913 that the other packages may use to modify the
6917 The related packages must use the provided program
6918 to make any desired modifications to the
6919 configuration file. They should either depend on
6920 the core package to guarantee that the configuration
6921 modifier program is available or accept gracefully
6922 that they cannot modify the configuration file if it
6923 is not. (This is in addition to the fact that the
6924 configuration file may not even be present in the
6931 Sometimes it's appropriate to create a new package which
6932 provides the basic infrastructure for the other packages
6933 and which manages the shared configuration files. (The
6934 <tt>sgml-base</tt> package is a good example.)
6939 <heading>User configuration files ("dotfiles")</heading>
6942 The files in <file>/etc/skel</file> will automatically be
6943 copied into new user accounts by <prgn>adduser</prgn>.
6944 No other program should reference the files in
6945 <file>/etc/skel</file>.
6949 Therefore, if a program needs a dotfile to exist in
6950 advance in <file>$HOME</file> to work sensibly, that dotfile
6951 should be installed in <file>/etc/skel</file> and treated as a
6956 However, programs that require dotfiles in order to
6957 operate sensibly are a bad thing, unless they do create
6958 the dotfiles themselves automatically.
6962 Furthermore, programs should be configured by the Debian
6963 default installation to behave as closely to the upstream
6964 default behaviour as possible.
6968 Therefore, if a program in a Debian package needs to be
6969 configured in some way in order to operate sensibly, that
6970 should be done using a site-wide configuration file placed
6971 in <file>/etc</file>. Only if the program doesn't support a
6972 site-wide default configuration and the package maintainer
6973 doesn't have time to add it may a default per-user file be
6974 placed in <file>/etc/skel</file>.
6978 <file>/etc/skel</file> should be as empty as we can make it.
6979 This is particularly true because there is no easy (or
6980 necessarily desirable) mechanism for ensuring that the
6981 appropriate dotfiles are copied into the accounts of
6982 existing users when a package is installed.
6988 <heading>Log files</heading>
6990 Log files should usually be named
6991 <file>/var/log/<var>package</var>.log</file>. If you have many
6992 log files, or need a separate directory for permission
6993 reasons (<file>/var/log</file> is writable only by
6994 <file>root</file>), you should usually create a directory named
6995 <file>/var/log/<var>package</var></file> and place your log
7000 Log files must be rotated occasionally so that they don't
7001 grow indefinitely; the best way to do this is to drop a log
7002 rotation configuration file into the directory
7003 <file>/etc/logrotate.d</file> and use the facilities provided by
7004 logrotate.<footnote>
7006 The traditional approach to log files has been to set up
7007 <em>ad hoc</em> log rotation schemes using simple shell
7008 scripts and cron. While this approach is highly
7009 customizable, it requires quite a lot of sysadmin work.
7010 Even though the original Debian system helped a little
7011 by automatically installing a system which can be used
7012 as a template, this was deemed not enough.
7016 The use of <prgn>logrotate</prgn>, a program developed
7017 by Red Hat, is better, as it centralizes log management.
7018 It has both a configuration file
7019 (<file>/etc/logrotate.conf</file>) and a directory where
7020 packages can drop their individual log rotation
7021 configurations (<file>/etc/logrotate.d</file>).
7024 Here is a good example for a logrotate config
7025 file (for more information see <manref name="logrotate"
7027 <example compact="compact">
7028 /var/log/foo/*.log {
7033 /etc/init.d/foo force-reload
7037 This rotates all files under <file>/var/log/foo</file>, saves 12
7038 compressed generations, and forces the daemon to reload its
7039 configuration information after the log rotation.
7043 Log files should be removed when the package is
7044 purged (but not when it is only removed). This should be
7045 done by the <prgn>postrm</prgn> script when it is called
7046 with the argument <tt>purge</tt> (see <ref
7047 id="removedetails">).
7052 <heading>Permissions and owners</heading>
7055 The rules in this section are guidelines for general use.
7056 If necessary you may deviate from the details below.
7057 However, if you do so you must make sure that what is done
7058 is secure and you should try to be as consistent as possible
7059 with the rest of the system. You should probably also
7060 discuss it on <prgn>debian-devel</prgn> first.
7064 Files should be owned by <tt>root.root</tt>, and made
7065 writable only by the owner and universally readable (and
7066 executable, if appropriate), that is mode 644 or 755.
7070 Directories should be mode 755 or (for group-writability)
7071 mode 2775. The ownership of the directory should be
7072 consistent with its mode: if a directory is mode 2775, it
7073 should be owned by the group that needs write access to
7078 Setuid and setgid executables should be mode 4755 or 2755
7079 respectively, and owned by the appropriate user or group.
7080 They should not be made unreadable (modes like 4711 or
7081 2711 or even 4111); doing so achieves no extra security,
7082 because anyone can find the binary in the freely available
7083 Debian package; it is merely inconvenient. For the same
7084 reason you should not restrict read or execute permissions
7085 on non-set-id executables.
7089 Some setuid programs need to be restricted to particular
7090 sets of users, using file permissions. In this case they
7091 should be owned by the uid to which they are set-id, and by
7092 the group which should be allowed to execute them. They
7093 should have mode 4754; again there is no point in making
7094 them unreadable to those users who must not be allowed to
7099 It is possible to arrange that the system administrator can
7100 reconfigure the package to correspond to their local
7101 security policy by changing the permissions on a binary:
7102 they can do this by using <prgn>dpkg-statoverride</prgn>, as
7103 described below.<footnote>
7104 Ordinary files installed by <prgn>dpkg</prgn> (as
7105 opposed to <tt>conffile</tt>s and other similar objects)
7106 normally have their permissions reset to the distributed
7107 permissions when the package is reinstalled. However,
7108 the use of <prgn>dpkg-statoverride</prgn> overrides this
7109 default behaviour. If you use this method, you should
7110 remember to describe <prgn>dpkg-statoverride</prgn> in
7111 the package documentation; being a relatively new
7112 addition to Debian, it is probably not yet well-known.
7114 Another method you should consider is to create a group for
7115 people allowed to use the program(s) and make any setuid
7116 executables executable only by that group.
7120 If you need to create a new user or group for your package
7121 there are two possibilities. Firstly, you may need to
7122 make some files in the binary package be owned by this
7123 user or group, or you may need to compile the user or
7124 group id (rather than just the name) into the binary
7125 (though this latter should be avoided if possible, as in
7126 this case you need a statically allocated id).</p>
7129 If you need a statically allocated id, you must ask for a
7130 user or group id from the <tt>base-passwd</tt> maintainer,
7131 and must not release the package until you have been
7132 allocated one. Once you have been allocated one you must
7133 either make the package depend on a version of the
7134 <tt>base-passwd</tt> package with the id present in
7135 <file>/etc/passwd</file> or <file>/etc/group</file>, or arrange for
7136 your package to create the user or group itself with the
7137 correct id (using <tt>adduser</tt>) in its
7138 <prgn>preinst</prgn> or <prgn>postinst</prgn>. (Doing it in
7139 the <prgn>postinst</prgn> is to be preferred if it is
7140 possible, otherwise a pre-dependency will be needed on the
7141 <tt>adduser</tt> package.)
7145 On the other hand, the program might be able to determine
7146 the uid or gid from the user or group name at runtime, so
7147 that a dynamically allocated id can be used. In this case
7148 you should choose an appropriate user or group name,
7149 discussing this on <prgn>debian-devel</prgn> and checking
7150 with the <package/base-passwd/ maintainer that it is unique and that
7151 they do not wish you to use a statically allocated id
7152 instead. When this has been checked you must arrange for
7153 your package to create the user or group if necessary using
7154 <prgn>adduser</prgn> in the <prgn>preinst</prgn> or
7155 <prgn>postinst</prgn> script (again, the latter is to be
7156 preferred if it is possible).
7160 Note that changing the numeric value of an id associated
7161 with a name is very difficult, and involves searching the
7162 file system for all appropriate files. You need to think
7163 carefully whether a static or dynamic id is required, since
7164 changing your mind later will cause problems.
7167 <sect1><heading>The use of <prgn>dpkg-statoverride</prgn></heading>
7169 This section is not intended as policy, but as a
7170 description of the use of <prgn>dpkg-statoverride</prgn>.
7174 <prgn>dpkg-statoverride</prgn> is a replacement for the
7175 deprecated <tt>suidmanager</tt> package. Packages which
7176 previously used <tt>suidmanager</tt> should have a
7177 <tt>Conflicts: suidmanager (<< 0.50)</tt> entry (or even
7178 <tt>(<< 0.52)</tt>), and calls to <tt>suidregister</tt>
7179 and <tt>suidunregister</tt> should now be simply removed
7180 from the maintainer scripts.
7184 If a system administrator wishes to have a file (or
7185 directory or other such thing) installed with owner and
7186 permissions different from those in the distributed Debian
7187 package, he can use the <prgn>dpkg-statoverride</prgn>
7188 program to instruct <prgn>dpkg</prgn> to use the different
7189 settings every time the file is installed. Thus the
7190 package maintainer should distribute the files with their
7191 normal permissions, and leave it for the system
7192 administrator to make any desired changes. For example, a
7193 daemon which is normally required to be setuid root, but
7194 in certain situations could be used without being setuid,
7195 should be installed setuid in the <tt>.deb</tt>. Then the
7196 local system administrator can change this if they wish.
7197 If there are two standard ways of doing it, the package
7198 maintainer can use <tt>debconf</tt> to find out the
7199 preference, and call <prgn>dpkg-statoverride</prgn> in the
7200 maintainer script if necessary to accommodate the system
7201 administrator's choice.
7205 Given the above, <prgn>dpkg-statoverride</prgn> is
7206 essentially a tool for system administrators and would not
7207 normally be needed in the maintainer scripts. There is
7208 one type of situation, though, where calls to
7209 <prgn>dpkg-statoverride</prgn> would be needed in the
7210 maintainer scripts, and that involves packages which use
7211 dynamically allocated user or group ids. In such a
7212 situation, something like the following idiom can be very
7213 helpful in the package's <prgn>postinst</prgn>, where
7214 <tt>sysuser</tt> is a dynamically allocated id:
7216 for i in /usr/bin/foo /usr/sbin/bar
7218 if ! dpkg-statoverride --list $i >/dev/null
7220 dpkg-statoverride --update --add sysuser root 4755 $i
7224 The corresponding <tt>dpkg-statoverride --remove</tt>
7225 calls can then be made unconditionally when the package is
7233 <chapt id="customized-programs">
7234 <heading>Customized programs</heading>
7236 <sect id="arch-spec">
7237 <heading>Architecture specification strings</heading>
7240 If a program needs to specify an <em>architecture specification
7241 string</em> in some place, the following format should be
7242 used: <var>arch</var>-<var>os</var><footnote>
7243 The following architectures and operating systems are
7244 currently recognised by <prgn>dpkg-architecture</prgn>.
7245 The architecture, <tt><var>arch</var></tt>, is one of
7246 the following: <tt>alpha</tt>, <tt>arm</tt>,
7247 <tt>hppa</tt>, <tt>i386</tt>, <tt>ia64</tt>,
7248 <tt>m68k</tt>, <tt>mips</tt>, <tt>mipsel</tt>,
7249 <tt>powerpc</tt>, <tt>s390</tt>, <tt>sh</tt>,
7250 <tt>sheb</tt>, <tt>sparc</tt> and <tt>sparc64</tt>. The
7251 operating system, <tt><var>os</var></tt>, is one of:
7252 <tt>linux</tt>, <tt>gnu</tt>, <tt>freebsd</tt> and
7253 <tt>openbsd</tt>. Use of <tt>gnu</tt> in this string is
7254 reserved for the GNU/Hurd operating system.
7259 Note that we don't want to use
7260 <tt><var>arch</var>-debian-linux</tt> to apply to the rule
7261 <tt><var>architecture</var>-<var>vendor</var>-<var>os</var></tt>
7262 since this would make our programs incompatible with other
7263 Linux distributions. We also don't use something like
7264 <tt><var>arch</var>-unknown-linux</tt>, since the
7265 <tt>unknown</tt> does not look very good.
7270 <heading>Daemons</heading>
7273 The configuration files <file>/etc/services</file>,
7274 <file>/etc/protocols</file>, and <file>/etc/rpc</file> are managed
7275 by the <prgn>netbase</prgn> package and must not be modified
7280 If a package requires a new entry in one of these files, the
7281 maintainer should get in contact with the
7282 <prgn>netbase</prgn> maintainer, who will add the entries
7283 and release a new version of the <prgn>netbase</prgn>
7288 The configuration file <file>/etc/inetd.conf</file> must not be
7289 modified by the package's scripts except via the
7290 <prgn>update-inetd</prgn> script or the
7291 <file>DebianNet.pm</file> Perl module. See their documentation
7292 for details on how to add entries.
7296 If a package wants to install an example entry into
7297 <file>/etc/inetd.conf</file>, the entry must be preceded with
7298 exactly one hash character (<tt>#</tt>). Such lines are
7299 treated as "commented out by user" by the
7300 <prgn>update-inetd</prgn> script and are not changed or
7301 activated during package updates.
7306 <heading>Using pseudo-ttys and modifying wtmp, utmp and
7310 Some programs need to create pseudo-ttys. This should be done
7311 using Unix98 ptys if the C library supports it. The resulting
7312 program must not be installed setuid root, unless that
7313 is required for other functionality.
7317 The files <file>/var/run/utmp</file>, <file>/var/log/wtmp</file> and
7318 <file>/var/log/lastlog</file> must be installed writeable by
7319 group <tt>utmp</tt>. Programs which need to modify those
7320 files must be installed setgid <tt>utmp</tt>.
7325 <heading>Editors and pagers</heading>
7328 Some programs have the ability to launch an editor or pager
7329 program to edit or display a text document. Since there are
7330 lots of different editors and pagers available in the Debian
7331 distribution, the system administrator and each user should
7332 have the possibility to choose his/her preferred editor and
7337 In addition, every program should choose a good default
7338 editor/pager if none is selected by the user or system
7343 Thus, every program that launches an editor or pager must
7344 use the EDITOR or PAGER environment variable to determine
7345 the editor or pager the user wishes to use. If these
7346 variables are not set, the programs <file>/usr/bin/editor</file>
7347 and <file>/usr/bin/pager</file> should be used, respectively.
7351 These two files are managed through the <prgn>dpkg</prgn>
7352 "alternatives" mechanism. Thus every package providing an
7353 editor or pager must call the
7354 <prgn>update-alternatives</prgn> script to register these
7359 If it is very hard to adapt a program to make use of the
7360 EDITOR or PAGER variables, that program may be configured to
7361 use <file>/usr/bin/sensible-editor</file> and
7362 <file>/usr/bin/sensible-pager</file> as the editor or pager
7363 program respectively. These are two scripts provided in the
7364 Debian base system that check the EDITOR and PAGER variables
7365 and launch the appropriate program, and fall back to
7366 <file>/usr/bin/editor</file> and <file>/usr/bin/pager</file> if the
7367 variable is not set.
7371 A program may also use the VISUAL environment variable to
7372 determine the user's choice of editor. If it exists, it
7373 should take precedence over EDITOR. This is in fact what
7374 <file>/usr/bin/sensible-editor</file> does.
7378 It is not required for a package to depend on
7379 <tt>editor</tt> and <tt>pager</tt>, nor is it required for a
7380 package to provide such virtual packages.<footnote>
7381 The Debian base system already provides an editor and a
7387 <sect id="web-appl">
7388 <heading>Web servers and applications</heading>
7391 This section describes the locations and URLs that should
7392 be used by all web servers and web applications in the
7399 Cgi-bin executable files are installed in the
7401 <example compact="compact">
7402 /usr/lib/cgi-bin/<var>cgi-bin-name</var>
7404 and should be referred to as
7405 <example compact="compact">
7406 http://localhost/cgi-bin/<var>cgi-bin-name</var>
7411 <p>Access to HTML documents</p>
7414 HTML documents for a package are stored in
7415 <file>/usr/share/doc/<var>package</var></file>
7416 and can be referred to as
7417 <example compact="compact">
7418 http://localhost/doc/<var>package</var>/<var>filename</var>
7423 The web server should restrict access to the document
7424 tree so that only clients on the same host can read
7425 the documents. If the web server does not support such
7426 access controls, then it should not provide access at
7427 all, or ask about providing access during installation.
7432 <p>Web Document Root</p>
7435 Web Applications should try to avoid storing files in
7436 the Web Document Root. Instead they should use the
7437 /usr/share/doc/<var>package</var> directory for
7438 documents and register the Web Application via the
7439 menu package. If access to the web document root is
7440 unavoidable then use
7441 <example compact="compact">
7444 as the Document Root. This might be just a symbolic
7445 link to the location where the system administrator
7446 has put the real document root.
7454 <sect id="mail-transport-agents">
7455 <heading>Mail transport, delivery and user agents</heading>
7458 Debian packages which process electronic mail, whether mail
7459 user agents (MUAs) or mail transport agents (MTAs), must
7460 ensure that they are compatible with the configuration
7461 decisions below. Failure to do this may result in lost
7462 mail, broken <tt>From:</tt> lines, and other serious brain
7467 The mail spool is <file>/var/mail</file> and the interface to
7468 send a mail message is <file>/usr/sbin/sendmail</file> (as per
7469 the FHS). On older systems, the mail spool may be
7470 physically located in <file>/var/spool/mail</file>, but all
7471 access to the mail spool should be via the
7472 <file>/var/mail</file> symlink. The mail spool is part of the
7473 base system and not part of the MTA package.
7477 All Debian MUAs, MTAs, MDAs and other mailbox accessing
7478 programs (such as IMAP daemons) must lock the mailbox in an
7479 NFS-safe way. This means that <tt>fcntl()</tt> locking must
7480 be combined with dot locking. To avoid deadlocks, a program
7481 should use <tt>fcntl()</tt> first and dot locking after
7482 this, or alternatively implement the two locking methods in
7483 a non blocking way<footnote>
7484 If it is not possible to establish both locks, the
7485 system shouldn't wait for the second lock to be
7486 established, but remove the first lock, wait a (random)
7487 time, and start over locking again.
7488 </footnote>. Using the functions <tt>maillock</tt> and
7489 <tt>mailunlock</tt> provided by the
7490 <tt>liblockfile*</tt><footnote>
7491 You will need to depend on <tt>liblockfile1 (>>1.01)</tt>
7492 to use these functions.
7493 </footnote> packages is the recommended way to realize this.
7497 Mailboxes are generally mode 660
7498 <tt><var>user</var>.mail</tt> unless the system
7499 administrator has chosen otherwise. A MUA may remove a
7500 mailbox (unless it has nonstandard permissions) in which
7501 case the MTA or another MUA must recreate it if needed.
7502 Mailboxes must be writable by group mail.
7506 The mail spool is 2775 <tt>root.mail</tt>, and MUAs should
7507 be setgid mail to do the locking mentioned above (and
7508 must obviously avoid accessing other users' mailboxes
7509 using this privilege).</p>
7512 <file>/etc/aliases</file> is the source file for the system mail
7513 aliases (e.g., postmaster, usenet, etc.), it is the one
7514 which the sysadmin and <prgn>postinst</prgn> scripts may
7515 edit. After <file>/etc/aliases</file> is edited the program or
7516 human editing it must call <prgn>newaliases</prgn>. All MTA
7517 packages must come with a <prgn>newaliases</prgn> program,
7518 even if it does nothing, but older MTA packages did not do
7519 this so programs should not fail if <prgn>newaliases</prgn>
7520 cannot be found. Note that because of this, all MTA
7521 packages must have <tt>Provides</tt>, <tt>Conflicts</tt> and
7522 <tt>Replaces: mail-transport-agent</tt> control file
7527 The convention of writing <tt>forward to
7528 <var>address</var></tt> in the mailbox itself is not
7529 supported. Use a <tt>.forward</tt> file instead.</p>
7532 The <prgn>rmail</prgn> program used by UUCP
7533 for incoming mail should be <file>/usr/sbin/rmail</file>.
7534 Likewise, <prgn>rsmtp</prgn>, for receiving
7535 batch-SMTP-over-UUCP, should be <file>/usr/sbin/rsmtp</file> if it
7539 If your package needs to know what hostname to use on (for
7540 example) outgoing news and mail messages which are generated
7541 locally, you should use the file <file>/etc/mailname</file>. It
7542 will contain the portion after the username and <tt>@</tt>
7543 (at) sign for email addresses of users on the machine
7544 (followed by a newline).
7548 Such package should check for the existence of this file
7549 when it is being configured. If it exists, it should be
7550 used without comment, although an MTA's configuration script
7551 may wish to prompt the user even if it finds that this file
7552 exists. If the file does not exist, the package should
7553 prompt the user for the value (preferably using
7554 <prgn>debconf</prgn>) and store it in <file>/etc/mailname</file>
7555 as well as using it in the package's configuration. The
7556 prompt should make it clear that the name will not just be
7557 used by that package. For example, in this situation the
7558 <tt>inn</tt> package could say something like:
7559 <example compact="compact">
7560 Please enter the "mail name" of your system. This is the
7561 hostname portion of the address to be shown on outgoing
7562 news and mail messages. The default is
7563 <var>syshostname</var>, your system's host name. Mail
7564 name ["<var>syshostname</var>"]:
7566 where <var>syshostname</var> is the output of <tt>hostname
7572 <heading>News system configuration</heading>
7575 All the configuration files related to the NNTP (news)
7576 servers and clients should be located under
7577 <file>/etc/news</file>.</p>
7580 There are some configuration issues that apply to a number
7581 of news clients and server packages on the machine. These
7585 <tag><file>/etc/news/organization</file></tag>
7587 A string which should appear as the
7588 organization header for all messages posted
7589 by NNTP clients on the machine
7592 <tag><file>/etc/news/server</file></tag>
7594 Contains the FQDN of the upstream NNTP
7595 server, or localhost if the local machine is
7600 Other global files may be added as required for cross-package news
7607 <heading>Programs for the X Window System</heading>
7610 <heading>Providing X support and package priorities</heading>
7613 Programs that can be configured with support for the X
7614 Window System must be configured to do so and must declare
7615 any package dependencies necessary to satisfy their
7616 runtime requirements when using the X Window System. If
7617 such a package is of higher priority than the X packages
7618 on which it depends, it is required that either the
7619 X-specific components be split into a separate package, or
7620 that an alternative version of the package, which includes
7621 X support, be provided, or that the package's priority be
7627 <heading>Packages providing an X server</heading>
7630 Packages that provide an X server that, directly or
7631 indirectly, communicates with real input and display
7632 hardware should declare in their control data that they
7633 provide the virtual package <tt>xserver</tt>.<footnote>
7634 This implements current practice, and provides an
7635 actual policy for usage of the <tt>xserver</tt>
7636 virtual package which appears in the virtual packages
7637 list. In a nutshell, X servers that interface
7638 directly with the display and input hardware or via
7639 another subsystem (e.g., GGI) should provide
7640 <tt>xserver</tt>. Things like <tt>Xvfb</tt>,
7641 <tt>Xnest</tt>, and <tt>Xprt</tt> should not.
7647 <heading>Packages providing a terminal emulator</heading>
7650 Packages that provide a terminal emulator for the X Window
7651 System which meet the criteria listed below should declare
7652 in their control data that they provide the virtual
7653 package <tt>x-terminal-emulator</tt>. They should also
7654 register themselves as an alternative for
7655 <file>/usr/bin/x-terminal-emulator</file>, with a priority of
7660 To be an <tt>x-terminal-emulator</tt>, a program must:
7661 <list compact="compact">
7663 Be able to emulate a DEC VT100 terminal, or a
7664 compatible terminal.
7668 Support the command-line option <tt>-e
7669 <var>command</var></tt>, which creates a new
7670 terminal window<footnote>
7671 "New terminal window" does not necessarily mean
7672 a new top-level X window directly parented by
7673 the window manager; it could, if the terminal
7674 emulator application were so coded, be a new
7675 "view" in a multiple-document interface (MDI).
7677 and runs the specified <var>command</var>,
7678 interpreting the entirity of the rest of the command
7679 line as a command to pass straight to exec, in the
7680 manner that <tt>xterm</tt> does.
7684 Support the command-line option <tt>-T
7685 <var>title</var></tt>, which creates a new terminal
7686 window with the window title <var>title</var>.
7693 <heading>Packages providing a window manager</heading>
7696 Packages that provide a window manager should declare in
7697 their control data that they provide the virtual package
7698 <tt>x-window-manager</tt>. They should also register
7699 themselves as an alternative for
7700 <file>/usr/bin/x-window-manager</file>, with a priority
7701 calculated as follows:
7702 <list compact="compact">
7704 Start with a priority of 20.
7708 If the window manager supports the Debian menu
7709 system, add 20 points if this support is available
7710 in the package's default configuration (i.e., no
7711 configuration files belonging to the system or user
7712 have to be edited to activate the feature); if
7713 configuration files must be modified, add only 10
7719 If the window manager complies with <url
7720 id="http://www.freedesktop.org/standards/wm-spec.html"
7721 name="The Window Manager Specification Project">,
7722 written by the <url id="http://www.freedesktop.org/"
7723 name="Free Desktop Group">, add 40 points.
7727 If the window manager permits the X session to be
7728 restarted using a <em>different</em> window manager
7729 (without killing the X server) in its default
7730 configuration, add 10 points; otherwise add none.
7737 <heading>Packages providing fonts</heading>
7740 Packages that provide fonts for the X Window
7742 For the purposes of Debian Policy, a "font for the X
7743 Window System" is one which is accessed via X protocol
7744 requests. Fonts for the Linux console, for PostScript
7745 renderers, or any other purpose, do not fit this
7746 definition. Any tool which makes such fonts available
7747 to the X Window System, however, must abide by this
7750 must do a number of things to ensure that they are both
7751 available without modification of the X or font server
7752 configuration, and that they do not corrupt files used by
7753 other font packages to register information about
7757 Fonts of any type supported by the X Window System
7758 must be in a separate binary package from any
7759 executables, libraries, or documentation (except
7760 that specific to the fonts shipped, such as their
7761 license information). If one or more of the fonts
7762 so packaged are necessary for proper operation of
7763 the package with which they are associated the font
7764 package may be Recommended; if the fonts merely
7765 provide an enhancement, a Suggests relationship may
7766 be used. Packages must not Depend on font
7768 This is because the X server may retrieve fonts
7769 from the local filesystem or over the network
7770 from an X font server; the Debian package system
7771 is empowered to deal only with the local
7777 BDF fonts must be converted to PCF fonts with the
7778 <prgn>bdftopcf</prgn> utility (available in the
7779 <tt>xutils</tt> package, <prgn>gzip</prgn>ped, and
7780 placed in a directory that corresponds to their
7782 <list compact="compact">
7784 100 dpi fonts must be placed in
7785 <file>/usr/X11R6/lib/X11/fonts/100dpi/</file>.
7789 75 dpi fonts must be placed in
7790 <file>/usr/X11R6/lib/X11/fonts/75dpi/</file>.
7794 Character-cell fonts, cursor fonts, and other
7795 low-resolution fonts must be placed in
7796 <file>/usr/X11R6/lib/X11/fonts/misc/</file>.
7802 Speedo fonts must be placed in
7803 <file>/usr/X11R6/lib/X11/fonts/Speedo/</file>.
7807 Type 1 fonts must be placed in
7808 <file>/usr/X11R6/lib/X11/fonts/Type1/</file>. If font
7809 metric files are available, they must be placed here
7814 Subdirectories of <file>/usr/X11R6/lib/X11/fonts/</file>
7815 other than those listed above must be neither
7816 created nor used. (The <file>PEX</file>, <file>CID</file>,
7817 and <file>cyrillic</file> directories are excepted for
7818 historical reasons, but installation of files into
7819 these directories remains discouraged.)
7823 Font packages may, instead of placing files directly
7824 in the X font directories listed above, provide
7825 symbolic links in that font directory pointing to
7826 the files' actual location in the filesystem. Such
7827 a location must comply with the FHS.
7831 Font packages should not contain both 75dpi and
7832 100dpi versions of a font. If both are available,
7833 they should be provided in separate binary packages
7834 with <tt>-75dpi</tt> or <tt>-100dpi</tt> appended to
7835 the names of the packages containing the
7836 corresponding fonts.
7840 Fonts destined for the <file>misc</file> subdirectory
7841 should not be included in the same package as 75dpi
7842 or 100dpi fonts; instead, they should be provided in
7843 a separate package with <tt>-misc</tt> appended to
7848 Font packages must not provide the files
7849 <file>fonts.dir</file>, <file>fonts.alias</file>, or
7850 <file>fonts.scale</file> in a font directory:
7853 <file>fonts.dir</file> files must not be provided at all.
7857 <file>fonts.alias</file> and <file>fonts.scale</file>
7858 files, if needed, should be provided in the
7860 <file>/etc/X11/fonts/<var>fontdir</var>/<var>package</var>.<var>extension</var></file>,
7861 where <var>fontdir</var> is the name of the
7863 <file>/usr/X11R6/lib/X11/fonts/</file> where the
7864 package's corresponding fonts are stored
7865 (e.g., <tt>75dpi</tt> or <tt>misc</tt>),
7866 <var>package</var> is the name of the package
7867 that provides these fonts, and
7868 <var>extension</var> is either <tt>scale</tt>
7869 or <tt>alias</tt>, whichever corresponds to
7876 Font packages must declare a dependency on
7877 <tt>xutils (>> 4.0.3)</tt> in their control
7882 Font packages that provide one or more
7883 <file>fonts.scale</file> files as described above must
7884 invoke <prgn>update-fonts-scale</prgn> on each
7885 directory into which they installed fonts
7886 <em>before</em> invoking
7887 <prgn>update-fonts-dir</prgn> on that directory.
7888 This invocation must occur in both the
7889 <prgn>postinst</prgn> (for all arguments) and
7890 <prgn>postrm</prgn> (for all arguments except
7891 <tt>upgrade</tt>) scripts.
7895 Font packages that provide one or more
7896 <file>fonts.alias</file> files as described above must
7897 invoke <prgn>update-fonts-alias</prgn> on each
7898 directory into which they installed fonts. This
7899 invocation must occur in both the
7900 <prgn>postinst</prgn> (for all arguments) and
7901 <prgn>postrm</prgn> (for all arguments except
7902 <tt>upgrade</tt>) scripts.
7906 Font packages must invoke
7907 <prgn>update-fonts-dir</prgn> on each directory into
7908 which they installed fonts. This invocation must
7909 occur in both the <prgn>postinst</prgn> (for all
7910 arguments) and <prgn>postrm</prgn> (for all
7911 arguments except <tt>upgrade</tt>) scripts.
7915 Font packages must not provide alias names for the
7916 fonts they include which collide with alias names
7917 already in use by fonts already packaged.
7921 Font packages must not provide fonts with the same
7922 XLFD registry name as another font already packaged.
7929 <heading>Application defaults files</heading>
7932 Application defaults files must be installed in the
7933 directory <file>/etc/X11/app-defaults/</file> (use of a
7934 localized subdirectory of <file>/etc/X11/</file> as described
7935 in the <em>X Toolkit Intrinsics - C Language
7936 Interface</em> manual is also permitted). They must be
7937 registered as <tt>conffile</tt>s or handled as
7938 configuration files. Packages must not provide the
7939 directory <file>/usr/X11R6/lib/X11/app-defaults/</file>.
7943 Customization of programs' X resources may also be
7944 supported with the provision of a file with the same name
7945 as that of the package placed in the
7946 <file>/etc/X11/Xresources/</file> directory, which must
7947 registered as a <tt>conffile</tt> or handled as a
7948 configuration file.<footnote>
7949 Note that this mechanism is not the same as using
7950 app-defaults; app-defaults are tied to the client
7951 binary on the local filesystem, whereas X resources
7952 are stored in the X server and affect all connecting
7955 <em>Important:</em> packages that install files into the
7956 <file>/etc/X11/Xresources/</file> directory must conflict with
7957 <tt>xbase (<< 3.3.2.3a-2)</tt>; if this is not done
7958 it is possible for the installing package to destroy a
7959 previously-existing <file>/etc/X11/Xresources</file> file
7960 which had been customized by the system administrator.
7965 <heading>Installation directory issues</heading>
7968 Packages using the X Window System should not be
7969 configured to install files under the <file>/usr/X11R6/</file>
7970 directory unless they use <prgn>imake</prgn>. The
7971 <file>/usr/X11R6/</file> directory hierarchy should be
7972 regarded as deprecated for all packages except the X
7973 Window System itself, and those which use the
7974 <prgn>imake</prgn> program it provides, in which case the
7975 packages may transition out of the <file>/usr/X11R6/</file>
7976 directory at the maintainer's discretion.<footnote>
7977 <prgn>Imake</prgn>-using programs are exempt because,
7978 as long as they are written correctly, the pathnames
7979 they use to locate resources and install themselves
7980 are derived wholly from the X Window System
7981 configuration. Thus, in the event that the X Window
7982 System moves to <file>/usr/X11R7/</file>,
7983 <file>/usr/X12/</file>, or just plain <file>/usr/</file>, all
7984 that is required for these programs is a recompile
7985 against the corresponding X Window System library
7986 development packages.
7991 Programs that use GNU <prgn>autoconf</prgn> and
7992 <prgn>automake</prgn> are usually easily configured at
7993 compile time to use <file>/usr/</file> instead of
7994 <file>/usr/X11R6/</file>, and this should be done whenever
7995 possible. Configuration files for window managers and
7996 display managers should be placed in a subdirectory of
7997 <file>/etc/X11/</file> corresponding to the package name due
7998 to these programs' tight integration with the mechanisms
7999 of the X Window System. Application-level programs should
8000 use the <file>/etc/</file> directory unless otherwise mandated
8005 The installation of files into subdirectories
8006 of <file>/usr/X11R6/include/X11/</file> and
8007 <file>/usr/X11R6/lib/X11/</file> is permitted but discouraged;
8008 package maintainers should determine if subdirectories of
8009 <file>/usr/lib/</file> and <file>/usr/share/</file> can be used
8010 instead. (The use of symbolic links from the
8011 <file>X11R6</file> directories to other FHS-compliant
8012 locations is encouraged if the program is not easily
8013 configured to look elsewhere for its files.)
8017 Packages must not provide or install files into the directories
8018 <file>/usr/bin/X11/</file>, <file>/usr/include/X11/</file> or
8019 <file>/usr/lib/X11/</file>. Files within a package should,
8020 however, make reference to these directories, rather than
8021 their <tt>X11R6</tt>-named counterparts
8022 <file>/usr/X11R6/bin/</file>, <file>/usr/X11R6/include/X11/</file>
8023 and <file>/usr/X11R6/lib/X11/</file>, if the resources being
8024 referred to have not been moved to other FHS-compliant
8030 <heading>The OSF/Motif and OpenMotif libraries</heading>
8033 <em>Programs that require the non-DFSG-compliant OSF/Motif or
8034 OpenMotif libraries</em><footnote>
8035 OSF/Motif and OpenMotif are collectively referred to as
8036 "Motif" in this policy document.
8038 should be compiled against and tested with LessTif (a free
8039 re-implementation of Motif) instead. If the maintainer
8040 judges that the program or programs do not work
8041 sufficiently well with LessTif to be distributed and
8042 supported, but do so when compiled against Motif, then two
8043 versions of the package should be created; one linked
8044 statically against Motif and with <tt>-smotif</tt>
8045 appended to the package name, and one linked dynamically
8046 against Motif and with <tt>-dmotif</tt> appended to the
8051 Both Motif-linked versions are dependent
8052 upon non-DFSG-compliant software and thus cannot be
8053 uploaded to the <em>main</em> distribution; if the
8054 software is itself DFSG-compliant it may be uploaded to
8055 the <em>contrib</em> distribution. While known existing
8056 versions of Motif permit unlimited redistribution of
8057 binaries linked against the library (whether statically or
8058 dynamically), it is the package maintainer's
8059 responsibility to determine whether this is permitted by
8060 the license of the copy of Motif in his or her possession.
8066 <heading>Perl programs and modules</heading>
8069 Perl programs and modules should follow the current Perl policy.
8073 The Perl policy can be found in the <tt>perl-policy</tt>
8074 files in the <tt>debian-policy</tt> package.
8075 It is also available from the Debian web mirrors at
8076 <tt><url name="/doc/packaging-manuals/perl-policy/"
8077 id="http://www.debian.org/doc/packaging-manuals/perl-policy/"></tt>
8078 and from the Debian archive mirrors at
8079 <tt><url name="/doc/package-developer/perl-policy.txt.gz"
8080 id="http://ftp.debian.org/debian/doc/package-developer/perl-policy.txt.gz"></tt>.
8085 <heading>Emacs lisp programs</heading>
8088 Please refer to the "Debian Emacs Policy" for details of how to
8089 package emacs lisp programs.
8093 The Emacs policy is available in
8094 <file>debian-emacs-policy.gz</file> of the
8095 <package>emacsen-common</package> package.
8096 It is also available from the Debian web mirrors at
8097 <tt><url name="/doc/packaging-manuals/debian-emacs-policy"
8098 id="http://www.debian.org/doc/packaging-manuals/debian-emacs-policy"></tt>.
8103 <heading>Games</heading>
8106 The permissions on <file>/var/games</file> are mode 755, owner
8107 <tt>root</tt> and group <tt>root</tt>.
8111 Each game decides on its own security policy.</p>
8114 Games which require protected, privileged access to
8115 high-score files, savegames, etc., may be made
8116 set-<em>group</em>-id (mode 2755) and owned by
8117 <tt>root.games</tt>, and use files and directories with
8118 appropriate permissions (770 <tt>root.games</tt>, for
8119 example). They must not be made
8120 set-<em>user</em>-id, as this causes security problems. (If
8121 an attacker can subvert any set-user-id game they can
8122 overwrite the executable of any other, causing other players
8123 of these games to run a Trojan horse program. With a
8124 set-group-id game the attacker only gets access to less
8125 important game data, and if they can get at the other
8126 players' accounts at all it will take considerably more
8130 Some packages, for example some fortune cookie programs, are
8131 configured by the upstream authors to install with their
8132 data files or other static information made unreadable so
8133 that they can only be accessed through set-id programs
8134 provided. You should not do this in a Debian package: anyone can
8135 download the <file>.deb</file> file and read the data from it,
8136 so there is no point making the files unreadable. Not
8137 making the files unreadable also means that you don't have
8138 to make so many programs set-id, which reduces the risk of a
8142 As described in the FHS, binaries of games should be
8143 installed in the directory <file>/usr/games</file>. This also
8144 applies to games that use the X Window System. Manual pages
8145 for games (X and non-X games) should be installed in
8146 <file>/usr/share/man/man6</file>.</p>
8152 <heading>Documentation</heading>
8155 <heading>Manual pages</heading>
8158 You should install manual pages in <prgn>nroff</prgn> source
8159 form, in appropriate places under <file>/usr/share/man</file>.
8160 You should only use sections 1 to 9 (see the FHS for more
8161 details). You must not install a preformatted "cat page".
8165 Each program, utility, and function should have an
8166 associated manual page included in the same package. It is
8167 suggested that all configuration files also have a manual
8168 page included as well. Manual pages for protocols and other
8169 auxiliary things are optional.
8173 If no manual page is available, this is considered as a bug
8174 and should be reported to the Debian Bug Tracking System (the
8175 maintainer of the package is allowed to write this bug report
8176 themselves, if they so desire). Do not close the bug report
8177 until a proper manpage is available.<footnote>
8178 It is not very hard to write a man page. See the
8179 <url id="http://www.schweikhardt.net/man_page_howto.html"
8180 name="Man-Page-HOWTO">,
8181 <manref name="man" section="7">, the examples
8182 created by <prgn>debmake</prgn> or <prgn>dh_make</prgn>,
8183 the helper programs <prgn>help2man</prgn>, or the
8184 directory <file>/usr/share/doc/man-db/examples</file>.
8189 You may forward a complaint about a missing manpage to the
8190 upstream authors, and mark the bug as forwarded in the
8191 Debian bug tracking system. Even though the GNU Project do
8192 not in general consider the lack of a manpage to be a bug,
8193 we do; if they tell you that they don't consider it a bug
8194 you should leave the bug in our bug tracking system open
8199 Manual pages should be installed compressed using <tt>gzip -9</tt>.
8203 If one manpage needs to be accessible via several names it
8204 is better to use a symbolic link than the <file>.so</file>
8205 feature, but there is no need to fiddle with the relevant
8206 parts of the upstream source to change from <file>.so</file> to
8207 symlinks: don't do it unless it's easy. You should not
8208 create hard links in the manual page directories, nor put
8209 absolute filenames in <file>.so</file> directives. The filename
8210 in a <file>.so</file> in a manpage should be relative to the
8211 base of the manpage tree (usually
8212 <file>/usr/share/man</file>). If you do not create any links
8213 (whether symlinks, hard links, or <tt>.so</tt> directives)
8214 in the filesystem to the alternate names of the manpage,
8215 then you should not rely on <prgn>man</prgn> finding your
8216 manpage under those names based solely on the information in
8217 the manpage's header.<footnote>
8218 Supporting this in <prgn>man</prgn> often requires
8219 unreasonable processing time to find a manual page or to
8220 report that none exists, and moves knowledge into man's
8221 database that would be better left in the filesystem.
8222 This support is therefore deprecated and will cease to
8223 be present in the future.
8229 <heading>Info documents</heading>
8232 Info documents should be installed in <file>/usr/share/info</file>.
8233 They should be compressed with <tt>gzip -9</tt>.
8237 Your package should call <prgn>install-info</prgn> to update
8238 the Info <file>dir</file> file in its <prgn>postinst</prgn>
8239 script when called with a <tt>configure</tt> argument, for
8241 <example compact="compact">
8242 install-info --quiet --section Development Development \
8243 /usr/share/info/foobar.info
8247 It is a good idea to specify a section for the location of
8248 your program; this is done with the <tt>--section</tt>
8249 switch. To determine which section to use, you should look
8250 at <file>/usr/share/info/dir</file> on your system and choose the most
8251 relevant (or create a new section if none of the current
8252 sections are relevant). Note that the <tt>--section</tt>
8253 flag takes two arguments; the first is a regular expression
8254 to match (case-insensitively) against an existing section,
8255 the second is used when creating a new one.</p>
8258 You should remove the entries in the <prgn>prerm</prgn>
8259 script when called with a <tt>remove</tt> argument:
8260 <example compact="compact">
8261 install-info --quiet --remove /usr/share/info/foobar.info
8265 If <prgn>install-info</prgn> cannot find a description entry
8266 in the Info file you must supply one. See <manref
8267 name="install-info" section="8"> for details.</p>
8271 <heading>Additional documentation</heading>
8274 Any additional documentation that comes with the package may
8275 be installed at the discretion of the package maintainer.
8276 Text documentation should be installed in the directory
8277 <file>/usr/share/doc/<var>package</var></file>, where
8278 <var>package</var> is the name of the package, and
8279 compressed with <tt>gzip -9</tt> unless it is small.
8283 If a package comes with large amounts of documentation which
8284 many users of the package will not require you should create
8285 a separate binary package to contain it, so that it does not
8286 take up disk space on the machines of users who do not need
8287 or want it installed.</p>
8290 It is often a good idea to put text information files
8291 (<file>README</file>s, changelogs, and so forth) that come with
8292 the source package in <file>/usr/share/doc/<var>package</var></file>
8293 in the binary package. However, you don't need to install
8294 the instructions for building and installing the package, of
8298 Packages must not require the existence of any files in
8299 <file>/usr/share/doc/</file> in order to function
8301 The system administrator should be able to
8302 delete files in <file>/usr/share/doc/</file> without causing
8303 any programs to break.
8305 Any files that are referenced by programs but are also
8306 useful as standalone documentation should be installed under
8307 <file>/usr/share/<var>package</var>/</file> with symbolic links from
8308 <file>/usr/share/doc/<var>package</var></file>.
8312 <file>/usr/share/doc/<var>package</var></file> may be a symbolic
8313 link to another directory in <file>/usr/share/doc</file> only if
8314 the two packages both come from the same source and the
8315 first package Depends on the second.
8319 Former Debian releases placed all additional documentation
8320 in <file>/usr/doc/<var>package</var></file>. This has been
8321 changed to <file>/usr/share/doc/<var>package</var></file>,
8322 and packages must not put documentation in the directory
8323 <file>/usr/doc/<var>package</var></file>. <footnote>
8324 At this phase of the transition, we no longer require a
8325 symbolic link in <file>/usr/doc/</file>. At a later point,
8326 policy shall change to make the symbolic links a bug.
8332 <heading>Preferred documentation formats</heading>
8335 The unification of Debian documentation is being carried out
8339 If your package comes with extensive documentation in a
8340 markup format that can be converted to various other formats
8341 you should if possible ship HTML versions in a binary
8342 package, in the directory
8343 <file>/usr/share/doc/<var>appropriate-package</var></file> or
8344 its subdirectories.<footnote>
8345 The rationale: The important thing here is that HTML
8346 docs should be available in <em>some</em> package, not
8347 necessarily in the main binary package.
8352 Other formats such as PostScript may be provided at the
8353 package maintainer's discretion.
8357 <sect id="copyrightfile">
8358 <heading>Copyright information</heading>
8361 Every package must be accompanied by a verbatim copy of its
8362 copyright and distribution license in the file
8363 <file>/usr/share/doc/<var>package</var>/copyright</file>. This
8364 file must neither be compressed nor be a symbolic link.
8368 In addition, the copyright file must say where the upstream
8369 sources (if any) were obtained. It should name the original
8370 authors of the package and the Debian maintainer(s) who were
8371 involved with its creation.</p>
8374 A copy of the file which will be installed in
8375 <file>/usr/share/doc/<var>package</var>/copyright</file> should
8376 be in <file>debian/copyright</file> in the source package.
8380 <file>/usr/share/doc/<var>package</var></file> may be a symbolic
8381 link to another directory in <file>/usr/share/doc</file> only if
8382 the two packages both come from the same source and the
8383 first package Depends on the second. These rules are
8384 important because copyrights must be extractable by
8389 Packages distributed under the UCB BSD license, the Artistic
8390 license, the GNU GPL, and the GNU LGPL should refer to the
8391 files <file>/usr/share/common-licenses/BSD</file>,
8392 <file>/usr/share/common-licenses/Artistic</file>,
8393 <file>/usr/share/common-licenses/GPL</file>, and
8394 <file>/usr/share/common-licenses/LGPL</file> respectively,
8395 rather than quoting them in the copyright file.
8399 You should not use the copyright file as a general <file>README</file>
8400 file. If your package has such a file it should be
8401 installed in <file>/usr/share/doc/<var>package</var>/README</file> or
8402 <file>README.Debian</file> or some other appropriate place.</p>
8406 <heading>Examples</heading>
8409 Any examples (configurations, source files, whatever),
8410 should be installed in a directory
8411 <file>/usr/share/doc/<var>package</var>/examples</file>. These
8412 files should not be referenced by any program: they're there
8413 for the benefit of the system administrator and users as
8414 documentation only. Architecture-specific example files
8415 should be installed in a directory
8416 <file>/usr/lib/<var>package</var>/examples</file> with symbolic
8418 <file>/usr/share/doc/<var>package</var>/examples</file>, or the
8419 latter directory itself may be a symbolic link to the
8424 If the purpose of a package is to provide examples, then the
8425 example files may be installed into
8426 <file>/usr/share/doc/<var>package</var></file>.
8430 <sect id="changelogs">
8431 <heading>Changelog files</heading>
8434 Packages that are not Debian-native must contain a
8435 compressed copy of the <file>debian/changelog</file> file from
8436 the Debian source tree in
8437 <file>/usr/share/doc/<var>package</var></file> with the name
8438 <file>changelog.Debian.gz</file>.
8442 If an upstream changelog is available, it should be accessible as
8443 <file>/usr/share/doc/<var>package</var>/changelog.gz</file> in
8444 plain text. If the upstream changelog is distributed in
8445 HTML, it should be made available in that form as
8446 <file>/usr/share/doc/<var>package</var>/changelog.html.gz</file>
8447 and a plain text <file>changelog.gz</file> should be generated
8448 from it using, for example, <tt>lynx -dump -nolist</tt>. If
8449 the upstream changelog files do not already conform to this
8450 naming convention, then this may be achieved either by
8451 renaming the files, or by adding a symbolic link, at the
8452 maintainer's discretion.<footnote>
8453 Rationale: People should not have to look in places for
8454 upstream changelogs merely because they are given
8455 different names or are distributed in HTML format.
8460 All of these files should be installed compressed using
8461 <tt>gzip -9</tt>, as they will become large with time even
8462 if they start out small.
8466 If the package has only one changelog which is used both as
8467 the Debian changelog and the upstream one because there is
8468 no separate upstream maintainer then that changelog should
8469 usually be installed as
8470 <file>/usr/share/doc/<var>package</var>/changelog.gz</file>; if
8471 there is a separate upstream maintainer, but no upstream
8472 changelog, then the Debian changelog should still be called
8473 <file>changelog.Debian.gz</file>.
8477 For details about the format and contents of the Debian
8478 changelog file, please see <ref id="dpkgchangelog">.
8483 <appendix id="pkg-scope">
8484 <heading>Introduction and scope of these appendices</heading>
8487 These appendices are taken essentially verbatim from the
8488 now-deprecated Packaging Manual, version 3.2.1.0. They are
8489 the chapters which are likely to be of use to package
8490 maintainers and which have not already been included in the
8491 policy document itself. Most of these sections are very likely
8492 not relevant to policy; they should be treated as
8493 documentation for the packaging system. Please note that these
8494 appendices are included for convenience, and for historical
8495 reasons: they used to be part of policy package, and they have
8496 not yet been incorporated into dpkg documentation. However,
8497 they still have value, and hence they are presented here.
8501 They have not yet been checked to ensure that they are
8502 compatible with the contents of policy, and if there are any
8503 contradictions, the version in the main policy document takes
8504 precedence. The remaining chapters of the old Packaging
8505 Manual have also not been read in detail to ensure that there
8506 are not parts which have been left out. Both of these will be
8511 Certain parts of the Packaging manual were integrated into the
8512 Policy Manual proper, and removed from the appendices. Links
8513 have been placed from the old locations to the new ones.
8517 <prgn>dpkg</prgn> is a suite of programs for creating binary
8518 package files and installing and removing them on Unix
8520 <prgn>dpkg</prgn> is targetted primarily at Debian
8521 GNU/Linux, but may work on or be ported to other
8527 The binary packages are designed for the management of
8528 installed executable programs (usually compiled binaries) and
8529 their associated data, though source code examples and
8530 documentation are provided as part of some packages.</p>
8533 This manual describes the technical aspects of creating Debian
8534 binary packages (<file>.deb</file> files). It documents the
8535 behaviour of the package management programs
8536 <prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and the way
8537 they interact with packages.</p>
8540 It also documents the interaction between
8541 <prgn>dselect</prgn>'s core and the access method scripts it
8542 uses to actually install the selected packages, and describes
8543 how to create a new access method.</p>
8546 This manual does not go into detail about the options and
8547 usage of the package building and installation tools. It
8548 should therefore be read in conjuction with those programs'
8553 The utility programs which are provided with <prgn>dpkg</prgn>
8554 for managing various system configuration and similar issues,
8555 such as <prgn>update-rc.d</prgn> and
8556 <prgn>install-info</prgn>, are not described in detail here -
8557 please see their manpages.
8561 It is assumed that the reader is reasonably familiar with the
8562 <prgn>dpkg</prgn> System Administrators' manual.
8563 Unfortunately this manual does not yet exist.
8567 The Debian version of the FSF's GNU hello program is provided
8568 as an example for people wishing to create Debian
8569 packages. The Debian <prgn>debmake</prgn> package is
8570 recommended as a very helpful tool in creating and maintaining
8571 Debian packages. However, while the tools and examples are
8572 helpful, they do not replace the need to read and follow the
8573 Policy and Programmer's Manual.</p>
8576 <appendix id="pkg-binarypkg">
8577 <heading>Binary packages (from old Packaging Manual)</heading>
8580 The binary package has two main sections. The first part
8581 consists of various control information files and scripts used
8582 by <prgn>dpkg</prgn> when installing and removing. See <ref
8583 id="pkg-controlarea">.
8587 The second part is an archive containing the files and
8588 directories to be installed.
8592 In the future binary packages may also contain other
8593 components, such as checksums and digital signatures. The
8594 format for the archive is described in full in the
8595 <file>deb(5)</file> manpage.
8599 <sect id="pkg-bincreating"><heading>Creating package files -
8600 <prgn>dpkg-deb</prgn>
8604 All manipulation of binary package files is done by
8605 <prgn>dpkg-deb</prgn>; it's the only program that has
8606 knowledge of the format. (<prgn>dpkg-deb</prgn> may be
8607 invoked by calling <prgn>dpkg</prgn>, as <prgn>dpkg</prgn>
8608 will spot that the options requested are appropriate to
8609 <prgn>dpkg-deb</prgn> and invoke that instead with the same
8614 In order to create a binary package you must make a
8615 directory tree which contains all the files and directories
8616 you want to have in the filesystem data part of the package.
8617 In Debian-format source packages this directory is usually
8618 <file>debian/tmp</file>, relative to the top of the package's
8623 They should have the locations (relative to the root of the
8624 directory tree you're constructing) ownerships and
8625 permissions which you want them to have on the system when
8630 With current versions of <prgn>dpkg</prgn> the uid/username
8631 and gid/groupname mappings for the users and groups being
8632 used should be the same on the system where the package is
8633 built and the one where it is installed.
8637 You need to add one special directory to the root of the
8638 miniature filesystem tree you're creating:
8639 <prgn>DEBIAN</prgn>. It should contain the control
8640 information files, notably the binary package control file
8641 (see <ref id="pkg-controlfile">).
8645 The <prgn>DEBIAN</prgn> directory will not appear in the
8646 filesystem archive of the package, and so won't be installed
8647 by <prgn>dpkg</prgn> when the package is installed.
8651 When you've prepared the package, you should invoke:
8653 dpkg --build <var>directory</var>
8658 This will build the package in
8659 <file><var>directory</var>.deb</file>. (<prgn>dpkg</prgn> knows
8660 that <tt>--build</tt> is a <prgn>dpkg-deb</prgn> option, so
8661 it invokes <prgn>dpkg-deb</prgn> with the same arguments to
8666 See the manpage <manref name="dpkg-deb" section="8"> for details of how
8667 to examine the contents of this newly-created file. You may find the
8668 output of following commands enlightening:
8670 dpkg-deb --info <var>filename</var>.deb
8671 dpkg-deb --contents <var>filename</var>.deb
8672 dpkg --contents <var>filename</var>.deb
8674 To view the copyright file for a package you could use this command:
8676 dpkg --fsys-tarfile <var>filename</var>.deb | tar xof usr/share/doc/<var>\*</var>copyright | less
8681 <sect id="pkg-controlarea">
8682 <heading>Package control information files</heading>
8685 The control information portion of a binary package is a
8686 collection of files with names known to <prgn>dpkg</prgn>.
8687 It will treat the contents of these files specially - some
8688 of them contain information used by <prgn>dpkg</prgn> when
8689 installing or removing the package; others are scripts which
8690 the package maintainer wants <prgn>dpkg</prgn> to run.
8694 It is possible to put other files in the package control
8695 area, but this is not generally a good idea (though they
8696 will largely be ignored).
8700 Here is a brief list of the control info files supported by
8701 <prgn>dpkg</prgn> and a summary of what they're used for.
8706 <tag><tt>control</tt>
8709 This is the key description file used by
8710 <prgn>dpkg</prgn>. It specifies the package's name
8711 and version, gives its description for the user,
8712 states its relationships with other packages, and so
8713 forth. See <ref id="sourcecontrolfiles"> and
8714 <ref id="binarycontrolfiles">.
8718 It is usually generated automatically from information
8719 in the source package by the
8720 <prgn>dpkg-gencontrol</prgn> program, and with
8721 assistance from <prgn>dpkg-shlibdeps</prgn>.
8722 See <ref id="pkg-sourcetools">.
8726 <tag><tt>postinst</tt>, <tt>preinst</tt>, <tt>postrm</tt>,
8731 These are exectuable files (usually scripts) which
8732 <prgn>dpkg</prgn> runs during installation, upgrade
8733 and removal of packages. They allow the package to
8734 deal with matters which are particular to that package
8735 or require more complicated processing than that
8736 provided by <prgn>dpkg</prgn>. Details of when and
8737 how they are called are in <ref id="maintainerscripts">.
8741 It is very important to make these scripts idempotent.
8742 See <ref id="idempotency">.
8746 The maintainer scripts are guaranteed to run with a
8747 controlling terminal and can interact with the user.
8748 See <ref id="controllingterminal">.
8752 <tag><tt>conffiles</tt>
8755 This file contains a list of configuration files which
8756 are to be handled automatically by <prgn>dpkg</prgn>
8757 (see <ref id="pkg-conffiles">). Note that not necessarily
8758 every configuration file should be listed here.
8761 <tag><tt>shlibs</tt>
8764 This file contains a list of the shared libraries
8765 supplied by the package, with dependency details for
8766 each. This is used by <prgn>dpkg-shlibdeps</prgn>
8767 when it determines what dependencies are required in a
8768 package control file. The <tt>shlibs</tt> file format
8769 is described on <ref id="shlibs">.
8774 <sect id="pkg-controlfile">
8775 <heading>The main control information file: <tt>control</tt></heading>
8778 The most important control information file used by
8779 <prgn>dpkg</prgn> when it installs a package is
8780 <tt>control</tt>. It contains all the package's "vital
8785 The binary package control files of packages built from
8786 Debian sources are made by a special tool,
8787 <prgn>dpkg-gencontrol</prgn>, which reads
8788 <file>debian/control</file> and <file>debian/changelog</file> to
8789 find the information it needs. See <ref id="pkg-sourcepkg"> for
8794 The fields in binary package control files are listed in
8795 <ref id="binarycontrolfiles">.
8799 A description of the syntax of control files and the purpose
8800 of the fields is available in <ref id="controlfields">.
8805 <heading>Time Stamps</heading>
8808 See <ref id="timestamps">.
8813 <appendix id="pkg-sourcepkg">
8814 <heading>Source packages (from old Packaging Manual) </heading>
8817 The Debian binary packages in the distribution are generated
8818 from Debian sources, which are in a special format to assist
8819 the easy and automatic building of binaries.
8822 <sect id="pkg-sourcetools">
8823 <heading>Tools for processing source packages</heading>
8826 Various tools are provided for manipulating source packages;
8827 they pack and unpack sources and help build of binary
8828 packages and help manage the distribution of new versions.
8832 They are introduced and typical uses described here; see
8833 <manref name="dpkg-source" section="1"> for full
8834 documentation about their arguments and operation.
8838 For examples of how to construct a Debian source package,
8839 and how to use those utilities that are used by Debian
8840 source packages, please see the <prgn>hello</prgn> example
8844 <sect1 id="pkg-dpkg-source">
8846 <prgn>dpkg-source</prgn> - packs and unpacks Debian source
8851 This program is frequently used by hand, and is also
8852 called from package-independent automated building scripts
8853 such as <prgn>dpkg-buildpackage</prgn>.
8857 To unpack a package it is typically invoked with
8859 dpkg-source -x <var>.../path/to/filename</var>.dsc
8864 with the <file><var>filename</var>.tar.gz</file> and
8865 <file><var>filename</var>.diff.gz</file> (if applicable) in
8866 the same directory. It unpacks into
8867 <file><var>package</var>-<var>version</var></file>, and if
8869 <file><var>package</var>-<var>version</var>.orig</file>, in
8870 the current directory.
8874 To create a packed source archive it is typically invoked:
8876 dpkg-source -b <var>package</var>-<var>version</var>
8881 This will create the <file>.dsc</file>, <file>.tar.gz</file> and
8882 <file>.diff.gz</file> (if appropriate) in the current
8883 directory. <prgn>dpkg-source</prgn> does not clean the
8884 source tree first - this must be done separately if it is
8889 See also <ref id="pkg-sourcearchives">.</p>
8893 <sect1 id="pkg-dpkg-buildpackage">
8895 <prgn>dpkg-buildpackage</prgn> - overall package-building
8900 <prgn>dpkg-buildpackage</prgn> is a script which invokes
8901 <prgn>dpkg-source</prgn>, the <file>debian/rules</file>
8902 targets <tt>clean</tt>, <tt>build</tt> and
8903 <tt>binary</tt>, <prgn>dpkg-genchanges</prgn> and
8904 <prgn>pgp</prgn> to build a signed source and binary
8909 It is usually invoked by hand from the top level of the
8910 built or unbuilt source directory. It may be invoked with
8911 no arguments; useful arguments include:
8912 <taglist compact="compact">
8913 <tag><tt>-uc</tt>, <tt>-us</tt></tag>
8916 Do not PGP-sign the <tt>.changes</tt> file or the
8917 source package <tt>.dsc</tt> file, respectively.</p>
8919 <tag><tt>-p<var>pgp-command</var></tt></tag>
8922 Invoke <var>pgp-command</var> instead of finding
8923 <tt>pgp</tt> on the <prgn>PATH</prgn>.
8924 <var>pgp-command</var> must behave just like
8925 <prgn>pgp</prgn>.</p>
8927 <tag><tt>-r<var>root-command</var></tt></tag>
8930 When root privilege is required, invoke the command
8931 <var>root-command</var>. <var>root-command</var>
8932 should invoke its first argument as a command, from
8933 the <prgn>PATH</prgn> if necessary, and pass its
8934 second and subsequent arguments to the command it
8935 calls. If no <var>root-command</var> is supplied
8936 then <var>dpkg-buildpackage</var> will take no
8937 special action to gain root privilege, so that for
8938 most packages it will have to be invoked as root to
8941 <tag><tt>-b</tt>, <tt>-B</tt></tag>
8944 Two types of binary-only build and upload - see
8945 <manref name="dpkg-source" section="1">.
8952 <sect1 id="pkg-dpkg-gencontrol">
8954 <prgn>dpkg-gencontrol</prgn> - generates binary package
8959 This program is usually called from <file>debian/rules</file>
8960 (see <ref id="pkg-sourcetree">) in the top level of the source
8965 This is usually done just before the files and directories in the
8966 temporary directory tree where the package is being built have their
8967 permissions and ownerships set and the package is constructed using
8968 <prgn>dpkg-deb/</prgn>
8970 This is so that the control file which is produced has
8971 the right permissions
8976 <prgn>dpkg-gencontrol</prgn> must be called after all the
8977 files which are to go into the package have been placed in
8978 the temporary build directory, so that its calculation of
8979 the installed size of a package is correct.
8983 It is also necessary for <prgn>dpkg-gencontrol</prgn> to
8984 be run after <prgn>dpkg-shlibdeps</prgn> so that the
8985 variable substitutions created by
8986 <prgn>dpkg-shlibdeps</prgn> in <file>debian/substvars</file>
8991 For a package which generates only one binary package, and
8992 which builds it in <file>debian/tmp</file> relative to the top
8993 of the source package, it is usually sufficient to call
8994 <prgn>dpkg-gencontrol</prgn>.
8998 Sources which build several binaries will typically need
9001 dpkg-gencontrol -Pdebian/tmp-<var>pkg</var> -p<var>package</var>
9002 </example> The <tt>-P</tt> tells
9003 <prgn>dpkg-gencontrol</prgn> that the package is being
9004 built in a non-default directory, and the <tt>-p</tt>
9005 tells it which package's control file should be generated.
9009 <prgn>dpkg-gencontrol</prgn> also adds information to the
9010 list of files in <file>debian/files</file>, for the benefit of
9011 (for example) a future invocation of
9012 <prgn>dpkg-genchanges</prgn>.</p>
9015 <sect1 id="pkg-dpkg-shlibdeps">
9017 <prgn>dpkg-shlibdeps</prgn> - calculates shared library
9022 This program is usually called from <file>debian/rules</file>
9023 just before <prgn>dpkg-gencontrol</prgn> (see <ref
9024 id="pkg-sourcetree">), in the top level of the source tree.
9028 Its arguments are executables.
9031 In a forthcoming dpkg version,
9032 <prgn>dpkg-shlibdeps</prgn> would be required to be
9033 called on shared libraries as well.
9036 They may be specified either in the locations in the
9037 source tree where they are created or in the locations
9038 in the temporary build tree where they are installed
9039 prior to binary package creation.
9041 </footnote> for which shared library dependencies should
9042 be included in the binary package's control file.
9046 If some of the found shared libraries should only
9047 warrant a <tt>Recommends</tt> or <tt>Suggests</tt>, or if
9048 some warrant a <tt>Pre-Depends</tt>, this can be achieved
9049 by using the <tt>-d<var>dependency-field</var></tt> option
9050 before those executable(s). (Each <tt>-d</tt> option
9051 takes effect until the next <tt>-d</tt>.)
9055 <prgn>dpkg-shlibdeps</prgn> does not directly cause the
9056 output control file to be modified. Instead by default it
9057 adds to the <file>debian/substvars</file> file variable
9058 settings like <tt>shlibs:Depends</tt>. These variable
9059 settings must be referenced in dependency fields in the
9060 appropriate per-binary-package sections of the source
9065 For example, a package that generates an essential part
9066 which requires dependencies, and optional parts that
9067 which only require a recommendation, would separate those
9068 two sets of dependencies into two different fields.<footnote>
9069 At the time of writing, an example for this was the
9070 <package/xmms/ package, with Depends used for the xmms
9071 executable, Recommends for the plug-ins and Suggests for
9072 even more optional features provided by unzip.
9074 It can say in its <file>debian/rules</file>:
9076 dpkg-shlibdeps -dDepends <var>program anotherprogram ...</var> \
9077 -dRecommends <var>optionalpart anotheroptionalpart</var>
9079 and then in its main control file <file>debian/control</file>:
9082 Depends: ${shlibs:Pre-Depends}
9083 Recommends: ${shlibs:Recommends}
9089 Sources which produce several binary packages with
9090 different shared library dependency requirements can use
9091 the <tt>-p<var>varnameprefix</var></tt> option to override
9092 the default <tt>shlibs:</tt> prefix (one invocation of
9093 <prgn>dpkg-shlibdeps</prgn> per setting of this option).
9094 They can thus produce several sets of dependency
9095 variables, each of the form
9096 <tt><var>varnameprefix</var>:<var>dependencyfield</var></tt>,
9097 which can be referred to in the appropriate parts of the
9098 binary package control files.
9103 <sect1 id="pkg-dpkg-distaddfile">
9105 <prgn>dpkg-distaddfile</prgn> - adds a file to
9106 <file>debian/files</file>
9110 Some packages' uploads need to include files other than
9111 the source and binary package files.
9115 <prgn>dpkg-distaddfile</prgn> adds a file to the
9116 <file>debian/files</file> file so that it will be included in
9117 the <file>.changes</file> file when
9118 <prgn>dpkg-genchanges</prgn> is run.
9122 It is usually invoked from the <tt>binary</tt> target of
9123 <file>debian/rules</file>:
9125 dpkg-distaddfile <var>filename</var> <var>section</var> <var>priority</var>
9127 The <var>filename</var> is relative to the directory where
9128 <prgn>dpkg-genchanges</prgn> will expect to find it - this
9129 is usually the directory above the top level of the source
9130 tree. The <file>debian/rules</file> target should put the
9131 file there just before or just after calling
9132 <prgn>dpkg-distaddfile</prgn>.
9136 The <var>section</var> and <var>priority</var> are passed
9137 unchanged into the resulting <file>.changes</file> file.
9142 <sect1 id="pkg-dpkg-genchanges">
9144 <prgn>dpkg-genchanges</prgn> - generates a <file>.changes</file>
9149 This program is usually called by package-independent
9150 automatic building scripts such as
9151 <prgn>dpkg-buildpackage</prgn>, but it may also be called
9156 It is usually called in the top level of a built source
9157 tree, and when invoked with no arguments will print out a
9158 straightforward <file>.changes</file> file based on the
9159 information in the source package's changelog and control
9160 file and the binary and source packages which should have
9166 <sect1 id="pkg-dpkg-parsechangelog">
9168 <prgn>dpkg-parsechangelog</prgn> - produces parsed
9169 representation of a changelog
9173 This program is used internally by
9174 <prgn>dpkg-source</prgn> et al. It may also occasionally
9175 be useful in <file>debian/rules</file> and elsewhere. It
9176 parses a changelog, <file>debian/changelog</file> by default,
9177 and prints a control-file format representation of the
9178 information in it to standard output.
9182 <sect1 id="pkg-dpkg-architecture">
9184 <prgn>dpkg-architecture</prgn> - information about the build and
9189 This program can be used manually, but is also invoked by
9190 <tt>dpkg-buildpackage</tt> or <file>debian/rules</file> to set
9191 to set environment or make variables which specify the build and
9192 host architecture for the package building process.
9197 <sect id="pkg-sourcetree">
9198 <heading>The Debianised source tree</heading>
9201 The source archive scheme described later is intended to
9202 allow a Debianised source tree with some associated control
9203 information to be reproduced and transported easily. The
9204 Debianised source tree is a version of the original program
9205 with certain files added for the benefit of the
9206 Debianisation process, and with any other changes required
9207 made to the rest of the source code and installation
9212 The extra files created for Debian are in the subdirectory
9213 <file>debian</file> of the top level of the Debianised source
9214 tree. They are described below.
9217 <sect1 id="pkg-debianrules">
9218 <heading><file>debian/rules</file> - the main building script</heading>
9221 See <ref id="debianrules">.
9226 <sect1 id="pkg-dpkgchangelog">
9227 <heading><file>debian/changelog</file></heading>
9230 See <ref id="dpkgchangelog">.
9234 It is recommended that the entire changelog be encoded in the
9235 <url id="http://www.cis.ohio-state.edu/cgi-bin/rfc/rfc2279.html" name="UTF-8">
9237 <url id="http://www.unicode.org/"
9238 name="Unicode">.<footnote>
9240 Support for Unicode, and specifically UTF-8, is
9241 steadily increasing among popular applications in
9242 Debian. For example, in unstable, GNOME 2 has
9243 excellent support (almost level 2) in almost all its
9244 applications; the big remaining one is gnome-terminal,
9245 of which one requires development versions in order to
9246 support UTF-8 (available in Debian experimental now if
9247 you want to play). I think that by the time sarge is
9248 released, UTF-8 support will start to hit critical
9251 I think it is fairly obvious that we need to
9252 eventually transition to UTF-8 for our package
9253 infrastructure; it is really the only sane charset in
9254 an international environment. Now, we can't switch to
9255 using UTF-8 for package control fields and the like
9256 until dpkg has better support, but one thing we can
9257 start doing today is requesting that Debian changelogs
9258 are UTF-8 encoded. At some point in time, we can start
9259 requiring them to do so.
9262 Checking for non-UTF8 characters in a changelog is
9263 trivial. Dump the file through
9264 <example>iconv -f utf-8 -t ucs-4</example>
9265 discard the output, and check the return
9266 value. If there are any characters in the stream
9267 which are invalid UTF-8 sequences, iconv will exit
9268 with an error code; and this will be the case for the
9269 vast majority of other character sets.
9274 <sect2><heading>Defining alternative changelog formats
9278 It is possible to use a different format to the standard
9279 one, by providing a parser for the format you wish to
9284 In order to have <tt>dpkg-parsechangelog</tt> run your
9285 parser, you must include a line within the last 40 lines
9286 of your file matching the Perl regular expression:
9287 <tt>\schangelog-format:\s+([0-9a-z]+)\W</tt> The part in
9288 parentheses should be the name of the format. For
9289 example, you might say:
9291 @@@ changelog-format: joebloggs @@@
9293 Changelog format names are non-empty strings of alphanumerics.
9297 If such a line exists then <tt>dpkg-parsechangelog</tt>
9298 will look for the parser as
9299 <file>/usr/lib/dpkg/parsechangelog/<var>format-name</var></file>
9301 <file>/usr/local/lib/dpkg/parsechangelog/<var>format-name</var></file>;
9302 it is an error for it not to find it, or for it not to
9303 be an executable program. The default changelog format
9304 is <tt>dpkg</tt>, and a parser for it is provided with
9305 the <tt>dpkg</tt> package.
9309 The parser will be invoked with the changelog open on
9310 standard input at the start of the file. It should read
9311 the file (it may seek if it wishes) to determine the
9312 information required and return the parsed information
9313 to standard output in the form of a series of control
9314 fields in the standard format. By default it should
9315 return information about only the most recent version in
9316 the changelog; it should accept a
9317 <tt>-v<var>version</var></tt> option to return changes
9318 information from all versions present <em>strictly
9319 after</em> <var>version</var>, and it should then be an
9320 error for <var>version</var> not to be present in the
9326 <list compact="compact">
9327 <item><qref id="f-Source"><tt>Source</tt></qref></item>
9328 <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
9329 <item><qref id="f-Distribution"><tt>Distribution</tt></qref> (mandatory)</item>
9330 <item><qref id="f-Urgency"><tt>Urgency</tt></qref> (mandatory)</item>
9331 <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
9332 <item><qref id="f-Date"><tt>Date</tt></qref></item>
9333 <item><qref id="f-Changes"><tt>Changes</tt></qref> (mandatory)</item>
9338 If several versions are being returned (due to the use
9339 of <tt>-v</tt>), the urgency value should be of the
9340 highest urgency code listed at the start of any of the
9341 versions requested followed by the concatenated
9342 (space-separated) comments from all the versions
9343 requested; the maintainer, version, distribution and
9344 date should always be from the most recent version.
9348 For the format of the <tt>Changes</tt> field see
9349 <ref id="f-Changes">.
9353 If the changelog format which is being parsed always or
9354 almost always leaves a blank line between individual
9355 change notes these blank lines should be stripped out,
9356 so as to make the resulting output compact.
9360 If the changelog format does not contain date or package
9361 name information this information should be omitted from
9362 the output. The parser should not attempt to synthesise
9363 it or find it from other sources.
9367 If the changelog does not have the expected format the
9368 parser should exit with a nonzero exit status, rather
9369 than trying to muddle through and possibly generating
9374 A changelog parser may not interact with the user at
9380 <sect1 id="pkg-srcsubstvars">
9381 <heading><file>debian/substvars</file> and variable substitutions</heading>
9384 See <ref id="substvars">.
9390 <heading><file>debian/files</file></heading>
9393 See <ref id="debianfiles">.
9397 <sect1><heading><file>debian/tmp</file>
9401 This is the canonical temporary location for the
9402 construction of binary packages by the <tt>binary</tt>
9403 target. The directory <file>tmp</file> serves as the root of
9404 the filesystem tree as it is being constructed (for
9405 example, by using the package's upstream makefiles install
9406 targets and redirecting the output there), and it also
9407 contains the <tt>DEBIAN</tt> subdirectory. See <ref
9408 id="pkg-bincreating">.
9412 If several binary packages are generated from the same
9413 source tree it is usual to use several
9414 <file>debian/tmp<var>something</var></file> directories, for
9415 example <file>tmp-a</file> or <file>tmp-doc</file>.
9419 Whatever <file>tmp</file> directories are created and used by
9420 <tt>binary</tt> must of course be removed by the
9421 <tt>clean</tt> target.</p></sect1>
9425 <sect id="pkg-sourcearchives"><heading>Source packages as archives
9429 As it exists on the FTP site, a Debian source package
9430 consists of three related files. You must have the right
9431 versions of all three to be able to use them.
9436 <tag>Debian source control file - <tt>.dsc</tt></tag>
9438 This file is a control file used by <prgn>dpkg-source</prgn>
9439 to extract a source package.
9440 See <ref id="debiansourcecontrolfiles">.
9444 Original source archive -
9446 <var>package</var>_<var>upstream-version</var>.orig.tar.gz
9453 This is a compressed (with <tt>gzip -9</tt>)
9454 <prgn>tar</prgn> file containing the source code from
9455 the upstream authors of the program. The tarfile
9456 unpacks into a directory
9457 <file><var>package</var>-<var>upstream-version</var>.orig</file>,
9458 and does not contain files anywhere other than in
9459 there or in its subdirectories.</p>
9463 Debianisation diff -
9465 <var>package</var>_<var>upstream_version-revision</var>.diff.gz
9471 This is a unified context diff (<tt>diff -u</tt>)
9472 giving the changes which are required to turn the
9473 original source into the Debian source. These changes
9474 may only include editing and creating plain files.
9475 The permissions of files, the targets of symbolic
9476 links and the characteristics of special files or
9477 pipes may not be changed and no files may be removed
9482 All the directories in the diff must exist, except the
9483 <file>debian</file> subdirectory of the top of the source
9484 tree, which will be created by
9485 <prgn>dpkg-source</prgn> if necessary when unpacking.
9489 The <prgn>dpkg-source</prgn> program will
9490 automatically make the <file>debian/rules</file> file
9491 executable (see below).</p></item>
9496 If there is no original source code - for example, if the
9497 package is specially prepared for Debian or the Debian
9498 maintainer is the same as the upstream maintainer - the
9499 format is slightly different: then there is no diff, and the
9501 <file><var>package</var>_<var>version</var>.tar.gz</file> and
9502 contains a directory
9503 <file><var>package</var>-<var>version</var></file>.
9508 <heading>Unpacking a Debian source package without <prgn>dpkg-source</prgn></heading>
9511 <tt>dpkg-source -x</tt> is the recommended way to unpack a
9512 Debian source package. However, if it is not available it
9513 is possible to unpack a Debian source archive as follows:
9514 <enumlist compact="compact">
9517 Untar the tarfile, which will create a <file>.orig</file>
9521 <p>Rename the <file>.orig</file> directory to
9522 <file><var>package</var>-<var>version</var></file>.</p>
9526 Create the subdirectory <file>debian</file> at the top of
9527 the source tree.</p>
9529 <item><p>Apply the diff using <tt>patch -p0</tt>.</p>
9531 <item><p>Untar the tarfile again if you want a copy of the original
9532 source code alongside the Debianised version.</p>
9537 It is not possible to generate a valid Debian source archive
9538 without using <prgn>dpkg-source</prgn>. In particular,
9539 attempting to use <prgn>diff</prgn> directly to generate the
9540 <file>.diff.gz</file> file will not work.
9544 <heading>Restrictions on objects in source packages</heading>
9547 The source package may not contain any hard links
9549 This is not currently detected when building source
9550 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
9557 </footnote>, device special files, sockets or setuid or
9560 Setgid directories are allowed.
9565 The source packaging tools manage the changes between the
9566 original and Debianised source using <prgn>diff</prgn> and
9567 <prgn>patch</prgn>. Turning the original source tree as
9568 included in the <file>.orig.tar.gz</file> into the debianised
9569 source must not involve any changes which cannot be
9570 handled by these tools. Problematic changes which cause
9571 <prgn>dpkg-source</prgn> to halt with an error when
9572 building the source package are:
9573 <list compact="compact">
9574 <item><p>Adding or removing symbolic links, sockets or pipes.</p>
9576 <item><p>Changing the targets of symbolic links.</p>
9578 <item><p>Creating directories, other than <file>debian</file>.</p>
9580 <item><p>Changes to the contents of binary files.</p></item>
9581 </list> Changes which cause <prgn>dpkg-source</prgn> to
9582 print a warning but continue anyway are:
9583 <list compact="compact">
9586 Removing files, directories or symlinks.
9588 Renaming a file is not treated specially - it is
9589 seen as the removal of the old file (which
9590 generates a warning, but is otherwise ignored),
9591 and the creation of the new one.
9597 Changed text files which are missing the usual final
9598 newline (either in the original or the modified
9603 Changes which are not represented, but which are not detected by
9604 <prgn>dpkg-source</prgn>, are:
9605 <list compact="compact">
9606 <item><p>Changing the permissions of files (other than
9607 <file>debian/rules</file>) and directories.</p></item>
9612 The <file>debian</file> directory and <file>debian/rules</file>
9613 are handled specially by <prgn>dpkg-source</prgn> - before
9614 applying the changes it will create the <file>debian</file>
9615 directory, and afterwards it will make
9616 <file>debian/rules</file> world-exectuable.
9622 <appendix id="pkg-controlfields">
9623 <heading>Control files and their fields (from old Packaging Manual)</heading>
9626 Many of the tools in the <prgn>dpkg</prgn> suite manipulate
9627 data in a common format, known as control files. Binary and
9628 source packages have control data as do the <file>.changes</file>
9629 files which control the installation of uploaded files, and
9630 <prgn>dpkg</prgn>'s internal databases are in a similar
9635 <heading>Syntax of control files</heading>
9638 See <ref id="controlsyntax">.
9642 It is important to note that there are several fields which
9643 are optional as far as <prgn>dpkg</prgn> and the related
9644 tools are concerned, but which must appear in every Debian
9645 package, or whose omission may cause problems.
9650 <heading>List of fields</heading>
9653 See <ref id="controlfieldslist">.
9657 This section now contains only the fields that didn't belong
9658 to the Policy manual.
9661 <sect1 id="pkg-f-Filename">
9662 <heading><tt>Filename</tt> and <tt>MSDOS-Filename</tt></heading>
9665 These fields in <tt>Packages</tt> files give the
9666 filename(s) of (the parts of) a package in the
9667 distribution directories, relative to the root of the
9668 Debian hierarchy. If the package has been split into
9669 several parts the parts are all listed in order, separated
9674 <sect1 id="pkg-f-Size">
9675 <heading><tt>Size</tt> and <tt>MD5sum</tt></heading>
9678 These fields in <file>Packages</file> files give the size (in
9679 bytes, expressed in decimal) and MD5 checksum of the
9680 file(s) which make(s) up a binary package in the
9681 distribution. If the package is split into several parts
9682 the values for the parts are listed in order, separated by
9687 <sect1 id="pkg-f-Status">
9688 <heading><tt>Status</tt></heading>
9691 This field in <prgn>dpkg</prgn>'s status file records
9692 whether the user wants a package installed, removed or
9693 left alone, whether it is broken (requiring
9694 reinstallation) or not and what its current state on the
9695 system is. Each of these pieces of information is a
9700 <sect1 id="pkg-f-Config-Version">
9701 <heading><tt>Config-Version</tt></heading>
9704 If a package is not installed or not configured, this
9705 field in <prgn>dpkg</prgn>'s status file records the last
9706 version of the package which was successfully
9711 <sect1 id="pkg-f-Conffiles">
9712 <heading><tt>Conffiles</tt></heading>
9715 This field in <prgn>dpkg</prgn>'s status file contains
9716 information about the automatically-managed configuration
9717 files held by a package. This field should <em>not</em>
9718 appear anywhere in a package!
9723 <heading>Obsolete fields</heading>
9726 These are still recognised by <prgn>dpkg</prgn> but should
9727 not appear anywhere any more.
9729 <taglist compact="compact">
9731 <tag><tt>Revision</tt></tag>
9732 <tag><tt>Package-Revision</tt></tag>
9733 <tag><tt>Package_Revision</tt></tag>
9735 The Debian revision part of the package version was
9736 at one point in a separate control file field. This
9737 field went through several names.
9740 <tag><tt>Recommended</tt></tag>
9741 <item>Old name for <tt>Recommends</tt>.</item>
9743 <tag><tt>Optional</tt></tag>
9744 <item>Old name for <tt>Suggests</tt>.</item>
9746 <tag><tt>Class</tt></tag>
9747 <item>Old name for <tt>Priority</tt>.</item>
9756 <appendix id="pkg-conffiles">
9757 <heading>Configuration file handling (from old Packaging Manual)</heading>
9760 <prgn>dpkg</prgn> can do a certain amount of automatic
9761 handling of package configuration files.
9765 Whether this mechanism is appropriate depends on a number of
9766 factors, but basically there are two approaches to any
9767 particular configuration file.
9771 The easy method is to ship a best-effort configuration in the
9772 package, and use <prgn>dpkg</prgn>'s conffile mechanism to
9773 handle updates. If the user is unlikely to want to edit the
9774 file, but you need them to be able to without losing their
9775 changes, and a new package with a changed version of the file
9776 is only released infrequently, this is a good approach.
9780 The hard method is to build the configuration file from
9781 scratch in the <prgn>postinst</prgn> script, and to take the
9782 responsibility for fixing any mistakes made in earlier
9783 versions of the package automatically. This will be
9784 appropriate if the file is likely to need to be different on
9788 <sect><heading>Automatic handling of configuration files by
9793 A package may contain a control area file called
9794 <tt>conffiles</tt>. This file should be a list of filenames
9795 of configuration files needing automatic handling, separated
9796 by newlines. The filenames should be absolute pathnames,
9797 and the files referred to should actually exist in the
9802 When a package is upgraded <prgn>dpkg</prgn> will process
9803 the configuration files during the configuration stage,
9804 shortly before it runs the package's <prgn>postinst</prgn>
9809 For each file it checks to see whether the version of the
9810 file included in the package is the same as the one that was
9811 included in the last version of the package (the one that is
9812 being upgraded from); it also compares the version currently
9813 installed on the system with the one shipped with the last
9818 If neither the user nor the package maintainer has changed
9819 the file, it is left alone. If one or the other has changed
9820 their version, then the changed version is preferred - i.e.,
9821 if the user edits their file, but the package maintainer
9822 doesn't ship a different version, the user's changes will
9823 stay, silently, but if the maintainer ships a new version
9824 and the user hasn't edited it the new version will be
9825 installed (with an informative message). If both have
9826 changed their version the user is prompted about the problem
9827 and must resolve the differences themselves.
9831 The comparisons are done by calculating the MD5 message
9832 digests of the files, and storing the MD5 of the file as it
9833 was included in the most recent version of the package.
9837 When a package is installed for the first time
9838 <prgn>dpkg</prgn> will install the file that comes with it,
9839 unless that would mean overwriting a file already on the
9844 However, note that <prgn>dpkg</prgn> will <em>not</em>
9845 replace a conffile that was removed by the user (or by a
9846 script). This is necessary because with some programs a
9847 missing file produces an effect hard or impossible to
9848 achieve in another way, so that a missing file needs to be
9849 kept that way if the user did it.
9853 Note that a package should <em>not</em> modify a
9854 <prgn>dpkg</prgn>-handled conffile in its maintainer
9855 scripts. Doing this will lead to <prgn>dpkg</prgn> giving
9856 the user confusing and possibly dangerous options for
9857 conffile update when the package is upgraded.</p>
9860 <sect><heading>Fully-featured maintainer script configuration
9865 For files which contain site-specific information such as
9866 the hostname and networking details and so forth, it is
9867 better to create the file in the package's
9868 <prgn>postinst</prgn> script.
9872 This will typically involve examining the state of the rest
9873 of the system to determine values and other information, and
9874 may involve prompting the user for some information which
9875 can't be obtained some other way.
9879 When using this method there are a couple of important
9880 issues which should be considered:
9884 If you discover a bug in the program which generates the
9885 configuration file, or if the format of the file changes
9886 from one version to the next, you will have to arrange for
9887 the postinst script to do something sensible - usually this
9888 will mean editing the installed configuration file to remove
9889 the problem or change the syntax. You will have to do this
9890 very carefully, since the user may have changed the file,
9891 perhaps to fix the very problem that your script is trying
9892 to deal with - you will have to detect these situations and
9893 deal with them correctly.
9897 If you do go down this route it's probably a good idea to
9898 make the program that generates the configuration file(s) a
9899 separate program in <file>/usr/sbin</file>, by convention called
9900 <file><var>package</var>config</file> and then run that if
9901 appropriate from the post-installation script. The
9902 <tt><var>package</var>config</tt> program should not
9903 unquestioningly overwrite an existing configuration - if its
9904 mode of operation is geared towards setting up a package for
9905 the first time (rather than any arbitrary reconfiguration
9906 later) you should have it check whether the configuration
9907 already exists, and require a <tt>--force</tt> flag to
9908 overwrite it.</p></sect>
9911 <appendix id="pkg-alternatives"><heading>Alternative versions of
9912 an interface - <prgn>update-alternatives</prgn> (from old
9917 When several packages all provide different versions of the
9918 same program or file it is useful to have the system select a
9919 default, but to allow the system administrator to change it
9920 and have their decisions respected.
9924 For example, there are several versions of the <prgn>vi</prgn>
9925 editor, and there is no reason to prevent all of them from
9926 being installed at once, each under their own name
9927 (<prgn>nvi</prgn>, <prgn>vim</prgn> or whatever).
9928 Nevertheless it is desirable to have the name <tt>vi</tt>
9929 refer to something, at least by default.
9933 If all the packages involved cooperate, this can be done with
9934 <prgn>update-alternatives</prgn>.
9938 Each package provides its own version under its own name, and
9939 calls <prgn>update-alternatives</prgn> in its postinst to
9940 register its version (and again in its prerm to deregister
9945 See the manpage <manref name="update-alternatives"
9946 section="8"> for details.
9950 If <prgn>update-alternatives</prgn> does not seem appropriate
9951 you may wish to consider using diversions instead.</p>
9954 <appendix id="pkg-diversions"><heading>Diversions - overriding a
9955 package's version of a file (from old Packaging Manual)
9959 It is possible to have <prgn>dpkg</prgn> not overwrite a file
9960 when it reinstalls the package it belongs to, and to have it
9961 put the file from the package somewhere else instead.
9965 This can be used locally to override a package's version of a
9966 file, or by one package to override another's version (or
9967 provide a wrapper for it).
9971 Before deciding to use a diversion, read <ref
9972 id="pkg-alternatives"> to see if you really want a diversion
9973 rather than several alternative versions of a program.
9977 There is a diversion list, which is read by <prgn>dpkg</prgn>,
9978 and updated by a special program <prgn>dpkg-divert</prgn>.
9979 Please see <manref name="dpkg-divert" section="8"> for full
9980 details of its operation.
9984 When a package wishes to divert a file from another, it should
9985 call <prgn>dpkg-divert</prgn> in its preinst to add the
9986 diversion and rename the existing file. For example,
9987 supposing that a <prgn>smailwrapper</prgn> package wishes to
9988 install a wrapper around <file>/usr/sbin/smail</file>:
9990 if [ install = "$1" ]; then
9991 dpkg-divert --package smailwrapper --add --rename \
9992 --divert /usr/sbin/smail.real /usr/sbin/smail
9994 </example> Testing <tt>$1</tt> is necessary so that the script
9995 doesn't try to add the diversion again when
9996 <prgn>smailwrapper</prgn> is upgraded. The <tt>--package
9997 smailwrapper</tt> ensures that <prgn>smailwrapper</prgn>'s
9998 copy of <file>/usr/sbin/smail</file> can bypass the diversion and
9999 get installed as the true version.
10003 The postrm has to do the reverse:
10005 if [ remove = "$1" ]; then
10006 dpkg-divert --package smailwrapper --remove --rename \
10007 --divert /usr/sbin/smail.real /usr/sbin/smail
10013 Do not attempt to divert a file which is vitally important for
10014 the system's operation - when using <prgn>dpkg-divert</prgn>
10015 there is a time, after it has been diverted but before
10016 <prgn>dpkg</prgn> has installed the new version, when the file
10017 does not exist.</p>
10022 <!-- vim:set ai et sts=2 sw=2 tw=76: -->