1 <!doctype debiandoc system[
2 <!-- include version information so we don't have to hard code it
3 within the document -->
4 <!entity % versiondata SYSTEM "version.ent"> %versiondata;
8 Debian GNU/Linux Packaging Manual.
9 Copyright (C)1996 Ian Jackson; released under the terms of the GNU
10 General Public License, version 2 or (at your option) any later.
11 Revised: David A. Morris (bweaver@debian.org)
12 Maintainer since 1998, Christian Schwarz <schwarz@debian.org>
18 <titlepag><title>Debian Packaging Manual</title>
20 <name>Ian Jackson </name>
21 <email>ijackson@gnu.ai.mit.edu</email>
24 <name>Revised: David A. Morris</name>
25 <email>bweaver@debian.org</email>
28 <name>Maintainer: Christian Schwarz </name>
29 <email>schwarz@debian.org</email>
32 <name>Maintainer: Manoj Srivastava </name>
33 <email>srivasta@debian.org</email>
36 <name>Maintainer: The Debian Policy group </name>
37 <email>debian-policy@lists.debian.org</email>
39 <version>version &version;, &date;</version>
42 This manual describes the technical aspects of creating Debian
43 binary and source packages. It also documents the interface
44 between <prgn>dselect</prgn> and its access method scripts.
45 It does not deal with the Debian Project policy requirements,
46 and it assumes familiarity with <prgn>dpkg</prgn>'s functions
47 from the system administrator's perspective. This
48 package itself is maintained by a group of maintainers
49 that have no editorial powers. At the moment, the list of
53 <p>Michael Alan Dorman <email>mdorman@debian.org</email></p>
56 <p>Richard Braakman <email>dark@xs4all.nl</email></p>
59 <p>Philip Hands <email>phil@hands.com</email></p>
62 <p>Manoj Srivastava <email>srivasta@debian.org</email></p>
69 <copyrightsummary>Copyright ©1996 Ian Jackson.</copyrightsummary>
71 This manual is free software; you may redistribute it and/or
72 modify it under the terms of the GNU General Public License
73 as published by the Free Software Foundation; either version
74 2, or (at your option) any later version.
78 This is distributed in the hope that it will be useful, but
79 <em>without any warranty</em>; without even the implied
80 warranty of merchantability or fitness for a particular
81 purpose. See the GNU General Public License for more
86 A copy of the GNU General Public License is available as
87 <tt>/usr/doc/copyright/GPL</tt> in the Debian GNU/Linux
88 distribution or on the World Wide Web at
89 <tt>http://www.gnu.org/copyleft/gpl.html</tt>. You can also
90 obtain it by writing to the Free Software Foundation, Inc.,
91 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
97 <!-- Describes the technical interface between a package and dpkg.
99 How to safely put shared libraries in a package. Details of
100 dpkg's handling of individual files. Sections on when to use
101 which feature (eg Replaces vs. Replaces/Conflicts
102 vs. update-alternatives vs. diversions) Cross-references to the
103 policy document (see below) where appropriate. Description of the
104 interface between dselect and its access methods. Hints on where
105 to start with a new package (ie, the hello package). What to do
110 Manpages are required for: update-rc.d, diversions,
111 update-alternatives, install-info in a package.
116 <heading>Introduction and scope of this manual</heading>
119 <prgn>dpkg</prgn> is a suite of programs for creating binary
120 package files and installing and removing them on Unix
123 <prgn>dpkg</prgn> is targetted primarily at Debian
124 GNU/Linux, but may work on or be ported to other
131 The binary packages are designed for the management of
132 installed executable programs (usually compiled binaries) and
133 their associated data, though source code examples and
134 documentation are provided as part of some packages.</p>
137 This manual describes the technical aspects of creating Debian
138 binary packages (<tt>.deb</tt> files). It documents the
139 behaviour of the package management programs
140 <prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and the way
141 they interact with packages.</p>
144 It also documents the interaction between
145 <prgn>dselect</prgn>'s core and the access method scripts it
146 uses to actually install the selected packages, and describes
147 how to create a new access method.</p>
150 This manual does not go into detail about the options and
151 usage of the package building and installation tools. It
152 should therefore be read in conjuction with those programs'
157 The utility programs which are provided with <prgn>dpkg</prgn>
158 for managing various system configuration and similar issues,
159 such as <prgn>update-rc.d</prgn> and
160 <prgn>install-info</prgn>, are not described in detail here -
161 please see their manpages.
165 It does <em>not</em> describe the policy requirements imposed
166 on Debian packages, such as the permissions on files and
167 directories, documentation requirements, upload procedure, and
168 so on. You should see the Debian packaging policy manual for
169 these details. (Many of them will probably turn out to be
170 helpful even if you don't plan to upload your package and make
171 it available as part of the distribution.)
175 It is assumed that the reader is reasonably familiar with the
176 <prgn>dpkg</prgn> System Administrators' manual.
177 Unfortunately this manual does not yet exist.
181 The Debian version of the FSF's GNU hello program is provided
182 as an example for people wishing to create Debian
183 packages. The Debian <prgn>debmake</prgn> package is
184 recommended as a very helpful tool in creating and maintaining
185 Debian packages. However, while the tools and examples are
186 helpful, they do not replace the need to read and follow the
187 Policy and Programmer's Manual.</p>
190 <chapt id="binarypkg"><heading>Binary packages
194 The binary package has two main sections. The first part
195 consists of various control information files and scripts used
196 by <prgn>dpkg</prgn> when installing and removing. See <ref
201 The second part is an archive containing the files and
202 directories to be installed.
206 In the future binary packages may also contain other
207 components, such as checksums and digital signatures. The
208 format for the archive is described in full in the
209 <tt>deb(5)</tt> manpage.
213 <sect id="bincreating"><heading>Creating package files -
214 <prgn>dpkg-deb</prgn>
218 All manipulation of binary package files is done by
219 <prgn>dpkg-deb</prgn>; it's the only program that has
220 knowledge of the format. (<prgn>dpkg-deb</prgn> may be
221 invoked by calling <prgn>dpkg</prgn>, as <prgn>dpkg</prgn>
222 will spot that the options requested are appropriate to
223 <prgn>dpkg-deb</prgn> and invoke that instead with the same
228 In order to create a binary package you must make a
229 directory tree which contains all the files and directories
230 you want to have in the filesystem data part of the package.
231 In Debian-format source packages this directory is usually
232 <tt>debian/tmp</tt>, relative to the top of the package's
237 They should have the locations (relative to the root of the
238 directory tree you're constructing) ownerships and
239 permissions which you want them to have on the system when
244 With current versions of <prgn>dpkg</prgn> the uid/username
245 and gid/groupname mappings for the users and groups being
246 used should be the same on the system where the package is
247 built and the one where it is installed.
251 You need to add one special directory to the root of the
252 miniature filesystem tree you're creating:
253 <prgn>DEBIAN</prgn>. It should contain the control
254 information files, notably the binary package control file
255 (see <ref id="controlfile">).
259 The <prgn>DEBIAN</prgn> directory will not appear in the
260 filesystem archive of the package, and so won't be installed
261 by <prgn>dpkg</prgn> when the package is installed.
265 When you've prepared the package, you should invoke:
267 dpkg --build <var>directory</var>
272 This will build the package in
273 <tt><var>directory</var>.deb</tt>. (<prgn>dpkg</prgn> knows
274 that <tt>--build</tt> is a <prgn>dpkg-deb</prgn> option, so
275 it invokes <prgn>dpkg-deb</prgn> with the same arguments to
280 See the manpage <manref name="dpkg-deb" section="8"> for details of how
281 to examine the contents of this newly-created file. You may find the
282 output of following commands enlightening:
284 dpkg-deb --info <var>filename</var>.deb
285 dpkg-deb --contents <var>filename</var>.deb
286 dpkg --contents <var>filename</var>.deb
288 To view the copyright file for a package you could use this command:
290 dpkg --fsys-tarfile <var>filename</var>.deb | tar xof usr/doc/<var>\*</var>copyright | less
295 <sect id="controlarea">
297 Package control information files
301 The control information portion of a binary package is a
302 collection of files with names known to <prgn>dpkg</prgn>.
303 It will treat the contents of these files specially - some
304 of them contain information used by <prgn>dpkg</prgn> when
305 installing or removing the package; others are scripts which
306 the package maintainer wants <prgn>dpkg</prgn> to run.
310 It is possible to put other files in the package control
311 area, but this is not generally a good idea (though they
312 will largely be ignored).
316 Here is a brief list of the control info files supported by
317 <prgn>dpkg</prgn> and a summary of what they're used for.
322 <tag><tt>control</tt>
326 This is the key description file used by
327 <prgn>dpkg</prgn>. It specifies the package's name
328 and version, gives its description for the user,
329 states its relationships with other packages, and so
330 forth. See <ref id="controlfile">.
334 It is usually generated automatically from information
335 in the source package by the
336 <prgn>dpkg-gencontrol</prgn> program, and with
337 assistance from <prgn>dpkg-shlibdeps</prgn>. See <ref
338 id="sourcetools">.</p>
341 <tag><tt>postinst</tt>, <tt>preinst</tt>, <tt>postrm</tt>,
347 These are exectuable files (usually scripts) which
348 <prgn>dpkg</prgn> runs during installation, upgrade
349 and removal of packages. They allow the package to
350 deal with matters which are particular to that package
351 or require more complicated processing than that
352 provided by <prgn>dpkg</prgn>. Details of when and
353 how they are called are in <ref
354 id="maintainerscripts">.
358 It is very important to make these scripts
362 That means that if it runs successfully or fails
363 and then you call it again it doesn't bomb out,
364 but just ensures that everything is the way it
367 </footnote> This is so that if an error occurs, the
368 user interrupts <prgn>dpkg</prgn> or some other
369 unforeseen circumstance happens you don't leave the
370 user with a badly-broken package.
374 The maintainer scripts are guaranteed to run with a
375 controlling terminal and can interact with the user.
376 If they need to prompt for passwords, do full-screen
377 interaction or something similar you should do these
378 things to and from <tt>/dev/tty</tt>, since
379 <prgn>dpkg</prgn> will at some point redirect scripts'
380 standard input and output so that it can log the
381 installation process. Likewise, because these scripts
382 may be executed with standard output redirected into a
383 pipe for logging purposes, Perl scripts should set
384 unbuffered output by setting <tt>$|=1</tt> so that the
385 output is printed immediately rather than being
390 Each script should return a zero exit status for
391 success, or a nonzero one for failure.</p>
394 <tag><tt>conffiles</tt>
399 This file contains a list of configuration files which
400 are to be handled automatically by <prgn>dpkg</prgn>
401 (see <ref id="conffiles">). Note that not necessarily
402 every configuration file should be listed here.</p>
410 This file contains a list of the shared libraries
411 supplied by the package, with dependency details for
412 each. This is used by <prgn>dpkg-shlibdeps</prgn>
413 when it determines what dependencies are required in a
414 package control file. The <tt>shlibs</tt> file format
415 is described on <ref id="shlibs">.
421 <sect id="controlfile">
423 The main control information file: <tt>control</tt>
426 The most important control information file used by
427 <prgn>dpkg</prgn> when it installs a package is
428 <tt>control</tt>. It contains all the package's `vital
433 The binary package control files of packages built from
434 Debian sources are made by a special tool,
435 <prgn>dpkg-gencontrol</prgn>, which reads
436 <tt>debian/control</tt> and <tt>debian/changelog</tt> to
437 find the information it needs. See <ref id="sourcepkg"> for
442 The fields in binary package control files are:
443 <list compact="compact">
445 <p><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</p>
448 <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
450 <item><p><qref id="f-Architecture"><tt>Architecture</tt></qref>
454 This field should appear in all packages, though
455 <prgn>dpkg</prgn> doesn't require it yet so that
456 old packages can still be installed.
462 <p><qref id="relationships"><tt>Depends</tt>,
463 <tt>Provides</tt> et al.</qref></p>
466 <p><qref id="f-Essential"><tt>Essential</tt></qref></p>
469 <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
472 <p><qref id="f-classification"><tt>Section</tt>,
473 <tt>Priority</tt></qref></p>
476 <p><qref id="f-Source"><tt>Source</tt></qref></p>
479 <p><qref id="descriptions"><tt>Description</tt></qref></p>
483 <qref id="f-Installed-Size"><tt>Installed-Size</tt></qref>
489 A description of the syntax of control files and the purpose
490 of these fields is available in <ref id="controlfields">.
494 <heading>Time Stamps</heading>
496 Maintainers are encouraged to preserve the modification
497 times of the upstream source files in a package, as far as
498 is reasonably possible.
501 The rationale is that there is some information conveyed
502 by knowing the age of the file, for example, you could
503 recognize that some documentation is very old by looking
504 at the modification time, so it would be nice if the
505 modification time of the upstream source would be
513 <chapt id="sourcepkg">
514 <heading>Source packages</heading>
517 The Debian binary packages in the distribution are generated
518 from Debian sources, which are in a special format to assist
519 the easy and automatic building of binaries.
523 There was a previous version of the Debian source format,
524 which is now being phased out. Instructions for converting an
525 old-style package are given in the Debian policy manual.
528 <sect id="sourcetools">
529 <heading>Tools for processing source packages</heading>
532 Various tools are provided for manipulating source packages;
533 they pack and unpack sources and help build of binary
534 packages and help manage the distribution of new versions.
538 They are introduced and typical uses described here; see
539 <manref name="dpkg-source" section="1"> for full
540 documentation about their arguments and operation.
544 For examples of how to construct a Debian source package,
545 and how to use those utilities that are used by Debian
546 source packages, please see the <prgn>hello</prgn> example
552 <prgn>dpkg-source</prgn> - packs and unpacks Debian source
557 This program is frequently used by hand, and is also
558 called from package-independent automated building scripts
559 such as <prgn>dpkg-buildpackage</prgn>.
563 To unpack a package it is typically invoked with
565 dpkg-source -x <var>.../path/to/filename</var>.dsc
570 with the <tt><var>filename</var>.tar.gz</tt> and
571 <tt><var>filename</var>.diff.gz</tt> (if applicable) in
572 the same directory. It unpacks into
573 <tt><var>package</var>-<var>version</var></tt>, and if
575 <tt><var>package</var>-<var>version</var>.orig</tt>, in
576 the current directory.
580 To create a packed source archive it is typically invoked:
582 dpkg-source -b <var>package</var>-<var>version</var>
587 This will create the <tt>.dsc</tt>, <tt>.tar.gz</tt> and
588 <tt>.diff.gz</tt> (if appropriate) in the current
589 directory. <prgn>dpkg-source</prgn> does not clean the
590 source tree first - this must be done separately if it is
595 See also <ref id="sourcearchives">.</p>
601 <prgn>dpkg-buildpackage</prgn> - overall package-building
606 <prgn>dpkg-buildpackage</prgn> is a script which invokes
607 <prgn>dpkg-source</prgn>, the <tt>debian/rules</tt>
608 targets <prgn>clean</prgn>, <prgn>build</prgn> and
609 <prgn>binary</prgn>, <prgn>dpkg-genchanges</prgn> and
610 <prgn>pgp</prgn> to build a signed source and binary
615 It is usually invoked by hand from the top level of the
616 built or unbuilt source directory. It may be invoked with
617 no arguments; useful arguments include:
618 <taglist compact="compact">
619 <tag><tt>-uc</tt>, <tt>-us</tt></tag>
622 Do not PGP-sign the <tt>.changes</tt> file or the
623 source package <tt>.dsc</tt> file, respectively.</p>
625 <tag><tt>-p<var>pgp-command</var></tt></tag>
628 Invoke <var>pgp-command</var> instead of finding
629 <tt>pgp</tt> on the <prgn>PATH</prgn>.
630 <var>pgp-command</var> must behave just like
631 <prgn>pgp</prgn>.</p>
633 <tag><tt>-r<var>root-command</var></tt></tag>
636 When root privilege is required, invoke the command
637 <var>root-command</var>. <var>root-command</var>
638 should invoke its first argument as a command, from
639 the <prgn>PATH</prgn> if necessary, and pass its
640 second and subsequent arguments to the command it
641 calls. If no <var>root-command</var> is supplied
642 then <var>dpkg-buildpackage</var> will take no
643 special action to gain root privilege, so that for
644 most packages it will have to be invoked as root to
647 <tag><tt>-b</tt>, <tt>-B</tt></tag>
650 Two types of binary-only build and upload - see
651 <manref name="dpkg-source" section="1">.
660 <prgn>dpkg-gencontrol</prgn> - generates binary package
665 This program is usually called from <tt>debian/rules</tt>
666 (see <ref id="sourcetree">) in the top level of the source
671 This is usually done just before the files and directories in the
672 temporary directory tree where the package is being built have their
673 permissions and ownerships set and the package is constructed using
674 <prgn>dpkg-deb/</prgn>
677 This is so that the control file which is produced has
678 the right permissions
684 <prgn>dpkg-gencontrol</prgn> must be called after all the
685 files which are to go into the package have been placed in
686 the temporary build directory, so that its calculation of
687 the installed size of a package is correct.
691 It is also necessary for <prgn>dpkg-gencontrol</prgn> to
692 be run after <prgn>dpkg-shlibdeps</prgn> so that the
693 variable substitutions created by
694 <prgn>dpkg-shlibdeps</prgn> in <tt>debian/substvars</tt>
699 For a package which generates only one binary package, and
700 which builds it in <tt>debian/tmp</tt> relative to the top
701 of the source package, it is usually sufficient to call
702 <prgn>dpkg-gencontrol</prgn>.
706 Sources which build several binaries will typically need
709 dpkg-gencontrol -Pdebian/tmp-<var>pkg</var> -p<var>package</var>
710 </example> The <tt>-P</tt> tells
711 <prgn>dpkg-gencontrol</prgn> that the package is being
712 built in a non-default directory, and the <tt>-p</tt>
713 tells it which package's control file should be generated.
717 <prgn>dpkg-gencontrol</prgn> also adds information to the
718 list of files in <tt>debian/files</tt>, for the benefit of
719 (for example) a future invocation of
720 <prgn>dpkg-genchanges</prgn>.</p>
725 <prgn>dpkg-shlibdeps</prgn> - calculates shared library
730 This program is usually called from <tt>debian/rules</tt>
731 just before <prgn>dpkg-gencontrol</prgn> (see <ref
732 id="sourcetree">), in the top level of the source tree.
736 Its arguments are executables
739 They may be specified either in the locations in the
740 source tree where they are created or in the locations
741 in the temporary build tree where they are installed
742 prior to binary package creation.
744 </footnote> for which shared library dependencies should
745 be included in the binary package's control file.
749 If some of the executable(s) shared libraries should only
750 warrant a <tt>Recommends</tt> or <tt>Suggests</tt>, or if
751 some warrant a <tt>Pre-Depends</tt>, this can be achieved
752 by using the <tt>-d<var>dependency-field</var></tt> option
753 before those executable(s). (Each <tt>-d</tt> option
754 takes effect until the next <tt>-d</tt>.)
758 <prgn>dpkg-shlibdeps</prgn> does not directly cause the
759 output control file to be modified. Instead by default it
760 adds to the <tt>debian/substvars</tt> file variable
761 settings like <tt>shlibs:Depends</tt>. These variable
762 settings must be referenced in dependency fields in the
763 appropriate per-binary-package sections of the source
768 For example, the <prgn>procps</prgn> package generates two
769 kinds of binaries, simple C binaries like <prgn>ps</prgn>
770 which require a predependency and full-screen ncurses
771 binaries like <prgn>top</prgn> which require only a
772 recommendation. It can say in its <tt>debian/rules</tt>:
774 dpkg-shlibdeps -dPre-Depends ps -dRecommends top
776 and then in its main control file <tt>debian/control</tt>:
780 Pre-Depends: ${shlibs:Pre-Depends}
781 Recommends: ${shlibs:Recommends}
787 Sources which produce several binary packages with
788 different shared library dependency requirements can use
789 the <tt>-p<var>varnameprefix</var></tt> option to override
790 the default <tt>shlib:</tt> prefix (one invocation of
791 <prgn>dpkg-shlibdeps</prgn> per setting of this option).
792 They can thus produce several sets of dependency
793 variables, each of the form
794 <tt><var>varnameprefix</var>:<var>dependencyfield</var></tt>,
795 which can be referred to in the appropriate parts of the
796 binary package control files.
803 <prgn>dpkg-distaddfile</prgn> - adds a file to
804 <tt>debian/files</tt>
808 Some packages' uploads need to include files other than
809 the source and binary package files.
813 <prgn>dpkg-distaddfile</prgn> adds a file to the
814 <tt>debian/files</tt> file so that it will be included in
815 the <tt>.changes</tt> file when
816 <prgn>dpkg-genchanges</prgn> is run.
820 It is usually invoked from the <prgn>binary</prgn> target of
821 <tt>debian/rules</tt>:
823 dpkg-distaddfile <var>filename</var> <var>section</var> <var>priority</var>
825 The <var>filename</var> is relative to the directory where
826 <prgn>dpkg-genchanges</prgn> will expect to find it - this
827 is usually the directory above the top level of the source
828 tree. The <tt>debian/rules</tt> target should put the
829 file there just before or just after calling
830 <prgn>dpkg-distaddfile</prgn>.
834 The <var>section</var> and <var>priority</var> are passed
835 unchanged into the resulting <tt>.changes</tt> file. See
836 <ref id="f-classification">.
841 <sect1><heading><prgn>dpkg-genchanges</prgn> - generates a <tt>.changes</tt> upload
846 This program is usually called by package-independent
847 automatic building scripts such as
848 <prgn>dpkg-buildpackage</prgn>, but it may also be called
853 It is usually called in the top level of a built source
854 tree, and when invoked with no arguments will print out a
855 straightforward <tt>.changes</tt> file based on the
856 information in the source package's changelog and control
857 file and the binary and source packages which should have
863 <sect1><heading><prgn>dpkg-parsechangelog</prgn> - produces parsed representation of
868 This program is used internally by
869 <prgn>dpkg-source</prgn> et al. It may also occasionally
870 be useful in <tt>debian/rules</tt> and elsewhere. It
871 parses a changelog, <tt>debian/changelog</tt> by default,
872 and prints a control-file format representation of the
873 information in it to standard output.
877 <sect1 id="dpkgarch"><heading><prgn>dpkg-architecture</prgn> -
878 information about the build and host system
882 This program can be used manually, but is also invoked by
883 <tt>dpkg-buildpackage</tt> or <tt>debian/rules</tt> to set
884 to set environment or make variables which specify the build and
885 host architecture for the package building process.
890 <sect id="sourcetree"><heading>The Debianised source tree
894 The source archive scheme described later is intended to
895 allow a Debianised source tree with some associated control
896 information to be reproduced and transported easily. The
897 Debianised source tree is a version of the original program
898 with certain files added for the benefit of the
899 Debianisation process, and with any other changes required
900 made to the rest of the source code and installation
905 The extra files created for Debian are in the subdirectory
906 <tt>debian</tt> of the top level of the Debianised source
907 tree. They are described below.
910 <sect1 id="debianrules"><heading><tt>debian/rules</tt> - the main building
915 This file is an executable makefile, and contains the
916 package-specific recipies for compiling the package and
917 building binary package(s) out of the source.
921 It must start with the line <tt>#!/usr/bin/make -f</tt>,
922 so that it can be invoked by saying its name rather than
923 invoking <prgn>make</prgn> explicitly.
927 Since an interactive <tt>debian/rules</tt> script makes it
928 impossible to autocompile that package and also makes it
929 hard for other people to reproduce the same binary
930 package, all <strong>required targets</strong> have to be
931 non-interactive. At a minimul, required targets are the
932 ones called by <prgn>dpkg-buildpackage</prgn>, namely,
933 <em>clean</em>, <em>binary</em>, <em>binary-arch</em>, and
934 <em>build</em>. It also follows that any target that these
935 targets depend on must also be non-interactive.
939 The targets which are required to be present are:
941 <tag><tt>build</tt></tag>
944 This should perform all non-interactive
945 configuration and compilation of the package. If a
946 package has an interactive pre-build configuration
947 routine, the Debianised source package should be
948 built after this has taken place, so that it can be
949 built without rerunning the configuration.
953 For some packages, notably ones where the same
954 source tree is compiled in different ways to produce
955 two binary packages, the <prgn>build</prgn> target
956 does not make much sense. For these packages it is
957 good enough to provide two (or more) targets
958 (<tt>build-a</tt> and <tt>build-b</tt> or whatever)
959 for each of the ways of building the package, and a
960 <prgn>build</prgn> target that does nothing. The
961 <prgn>binary</prgn> target will have to build the
962 package in each of the possible ways and make the
963 binary package out of each.
967 The <prgn>build</prgn> target must not do anything
968 that might require root privilege.
972 The <prgn>build</prgn> target may need to run
973 <prgn>clean</prgn> first - see below.
977 When a package has a configuration routine that
978 takes a long time, or when the makefiles are poorly
979 designed, or when <prgn>build</prgn> needs to run
980 <prgn>clean</prgn> first, it is a good idea to
981 <tt>touch build</tt> when the build process is
982 complete. This will ensure that if <tt>debian/rules
983 build</tt> is run again it will not rebuild the
988 <tag><tt>binary</tt>, <tt>binary-arch</tt>,
989 <tt>binary-indep</tt>
993 The <prgn>binary</prgn> target should be all that is
994 necessary for the user to build the binary
995 package. All these targets are required to be
996 non-interactive. It is split into two parts:
997 <prgn>binary-arch</prgn> builds the packages' output
998 files which are specific to a particular
999 architecture, and <prgn>binary-indep</prgn> builds
1000 those which are not.
1004 <prgn>binary</prgn> should usually be a target with
1005 no commands which simply depends on
1006 <prgn>binary-arch</prgn> and
1007 <prgn>binary-indep</prgn>.
1011 Both <prgn>binary-*</prgn> targets should depend on
1012 the <prgn>build</prgn> target, above, so that the
1013 package is built if it has not been already. It
1014 should then create the relevant binary package(s),
1015 using <prgn>dpkg-gencontrol</prgn> to make their
1016 control files and <prgn>dpkg-deb</prgn> to build
1017 them and place them in the parent of the top level
1022 If one of the <prgn>binary-*</prgn> targets has
1023 nothing to do (this will be always be the case if
1024 the source generates only a single binary package,
1025 whether architecture-dependent or not) it
1026 <em>must</em> still exist, but should always
1031 <ref id="binarypkg"> describes how to construct
1036 The <prgn>binary</prgn> targets must be invoked as
1041 <tag><tt>clean</tt></tag>
1045 This should undo any effects that the
1046 <prgn>build</prgn> and <prgn>binary</prgn> targets
1047 may have had, except that it should leave alone any
1048 output files created in the parent directory by a
1049 run of <prgn>binary</prgn>. This target is required
1050 to be non-interactive.
1054 If a <prgn>build</prgn> file is touched at the end
1055 of the <prgn>build</prgn> target, as suggested
1056 above, it must be removed as the first thing that
1057 <prgn>clean</prgn> does, so that running
1058 <prgn>build</prgn> again after an interrupted
1059 <prgn>clean</prgn> doesn't think that everything is
1064 The <prgn>clean</prgn> target must be invoked as
1065 root if <prgn>binary</prgn> has been invoked since
1066 the last <prgn>clean</prgn>, or if
1067 <prgn>build</prgn> has been invoked as root (since
1068 <prgn>build</prgn> may create directories, for
1073 <tag><tt>get-orig-source</tt> (optional)</tag>
1077 This target fetches the most recent version of the
1078 original source package from a canonical archive
1079 site (via FTP or WWW, for example), does any
1080 necessary rearrangement to turn it into the original
1081 source tarfile format described below, and leaves it
1082 in the current directory.
1086 This target may be invoked in any directory, and
1087 should take care to clean up any temporary files it
1092 This target is optional, but providing it if
1093 possible is a good idea.
1099 The <prgn>build</prgn>, <prgn>binary</prgn> and
1100 <prgn>clean</prgn> targets must be invoked with a current
1101 directory of the package's top-level directory.
1106 Additional targets may exist in <tt>debian/rules</tt>,
1107 either as published or undocumented interfaces or for the
1108 package's internal use.
1112 The architecture we build on and build for is determined by make
1113 variables via dpkg-architecture (see <ref id="dpkgarch">). You can
1114 get the Debian architecture and the GNU style architecture
1115 specification string for the build machine as well as the host
1116 machine. Here is a list of supported make variables:
1117 <list compact="compact">
1119 <p><tt>DEB_*_ARCH</tt> (the Debian architecture)</p>
1122 <p><tt>DEB_*_GNU_TYPE</tt> (the GNU style architecture
1123 specification string)</p>
1126 <p><tt>DEB_*_GNU_CPU</tt> (the CPU part of DEB_*_GNU_TYPE)</p>
1129 <p><tt>DEB_*_GNU_SYSTEM</tt> (the System part of
1135 where <tt>*</tt> is either <tt>BUILD</tt> for specification of
1136 the build machine or <tt>HOST</tt> for specification of the machine
1141 Backward compatibility can be provided in the rules file
1142 by setting the needed variables to suitable default
1143 values, please refer to the documentation of
1144 dpkg-architecture for details.
1148 It is important to understand that the <tt>DEB_*_ARCH</tt>
1149 string does only determine which Debian architecture we
1150 build on resp. for. It should not be used to get the CPU
1151 or System information, the GNU style variables should be
1157 <sect1><heading><tt>debian/control</tt>
1161 This file contains version-independent details about the
1162 source package and about the binary packages it creates.
1166 It is a series of sets of control fields, each
1167 syntactically similar to a binary package control file.
1168 The sets are separated by one or more blank lines. The
1169 first set is information about the source package in
1170 general; each subsequent set describes one binary package
1171 that the source tree builds.
1175 The syntax and semantics of the fields are described below
1176 in <ref id="controlfields">.
1180 The general (binary-package-independent) fields are:
1181 <list compact="compact">
1183 <p><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</p>
1186 <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
1190 <qref id="f-classification"><tt>Section</tt> and
1191 <tt>Priority</tt></qref>
1192 (classification, mandatory)
1197 <qref id="relationships"><tt>Build-Depends</tt> et
1198 al.</qref> (source package interrelationships)
1203 <qref id="f-Standards-Version"><tt>Standards-Version</tt></qref>
1209 The per-binary-package fields are:
1210 <list compact="compact">
1212 <p><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</p>
1216 <qref id="f-Architecture"><tt>Architecture</tt></qref>
1220 <p><qref id="descriptions"><tt>Description</tt></qref></p>
1224 <qref id="f-classification"><tt>Section</tt> and
1225 <tt>Priority</tt></qref> (classification)</p>
1228 <p><qref id="f-Essential"><tt>Essential</tt></qref></p>
1232 <qref id="relationships"><tt>Depends</tt> et
1233 al.</qref> (binary package interrelationships)
1239 These fields are used by <prgn>dpkg-gencontrol</prgn> to
1240 generate control files for binary packages (see below), by
1241 <prgn>dpkg-genchanges</prgn> to generate the
1242 <tt>.changes</tt> file to accompany the upload, and by
1243 <prgn>dpkg-source</prgn> when it creates the <tt>.dsc</tt>
1244 source control file as part of a source archive.
1248 The fields here may contain variable references - their
1249 values will be substituted by
1250 <prgn>dpkg-gencontrol</prgn>, <prgn>dpkg-genchanges</prgn>
1251 or <prgn>dpkg-source</prgn> when they generate output
1252 control files. See <ref id="srcsubstvars"> for details.
1255 <p> <sect2><heading>User-defined fields
1259 Additional user-defined fields may be added to the
1260 source package control file. Such fields will be
1261 ignored, and not copied to (for example) binary or
1262 source package control files or upload control files.
1266 If you wish to add additional unsupported fields to
1267 these output files you should use the mechanism
1272 Fields in the main source control information file with
1273 names starting <tt>X</tt>, followed by one or more of
1274 the letters <tt>BCS</tt> and a hyphen <tt>-</tt>, will
1275 be copied to the output files. Only the part of the
1276 field name after the hyphen will be used in the output
1277 file. Where the letter <tt>B</tt> is used the field
1278 will appear in binary package control files, where the
1279 letter <tt>S</tt> is used in source package control
1280 files and where <tt>C</tt> is used in upload control
1281 (<tt>.changes</tt>) files.
1285 For example, if the main source information control file
1288 XBS-Comment: I stand between the candle and the star.
1290 then the binary and source package control files will contain the
1293 Comment: I stand between the candle and the star.
1300 <sect1 id="dpkgchangelog"><heading><tt>debian/changelog</tt>
1304 This file records the changes to the Debian-specific parts of the
1308 Though there is nothing stopping an author who is also
1309 the Debian maintainer from using it for all their
1310 changes, it will have to be renamed if the Debian and
1311 upstream maintainers become different
1318 It has a special format which allows the package building
1319 tools to discover which version of the package is being
1320 built and find out other release-specific information.
1324 That format is a series of entries like this:
1326 <var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
1328 * <var>change details</var>
1329 <var>more change details</var>
1330 * <var>even more change details</var>
1332 -- <var>maintainer name and email address</var> <var>date</var>
1337 <var>package</var> and <var>version</var> are the source
1338 package name and version number.
1342 <var>distribution(s)</var> lists the distributions where
1343 this version should be installed when it is uploaded - it
1344 is copied to the <tt>Distribution</tt> field in the
1345 <tt>.changes</tt> file. See <ref id="f-Distribution">.
1349 <var>urgency</var> is the value for the <tt>Urgency</tt>
1350 field in the <tt>.changes</tt> file for the upload. See
1351 <ref id="f-Urgency">. It is not possible to specify an
1352 urgency containing commas; commas are used to separate
1353 <tt><var>keyword</var>=<var>value</var></tt> settings in
1354 the <prgn>dpkg</prgn> changelog format (though there is
1355 currently only one useful <var>keyword</var>,
1360 The change details may in fact be any series of lines
1361 starting with at least two spaces, but conventionally each
1362 change starts with an asterisk and a separating space and
1363 continuation lines are indented so as to bring them in
1364 line with the start of the text above. Blank lines may be
1365 used here to separate groups of changes, if desired.
1369 The maintainer name and email address should <em>not</em>
1370 necessarily be those of the usual package maintainer.
1371 They should be the details of the person doing
1372 <em>this</em> version. The information here will be
1373 copied to the <tt>.changes</tt> file, and then later used
1374 to send an acknowledgement when the upload has been
1379 The <var>date</var> should be in RFC822 format
1382 This is generated by the <prgn>822-date</prgn>
1385 </footnote>; it should include the timezone specified
1386 numerically, with the timezone name or abbreviation
1387 optionally present as a comment.
1391 The first `title' line with the package name should start
1392 at the left hand margin; the `trailer' line with the
1393 maintainer and date details should be preceded by exactly
1394 one space. The maintainer details and the date must be
1395 separated by exactly two spaces.
1399 An Emacs mode for editing this format is available: it is
1400 called <tt>debian-changelog-mode</tt>. You can have this
1401 mode selected automatically when you edit a Debian
1402 changelog by adding a local variables clause to the end of
1406 <sect2><heading>Defining alternative changelog formats
1410 It is possible to use a different format to the standard
1411 one, by providing a parser for the format you wish to
1416 In order to have <tt>dpkg-parsechangelog</tt> run your
1417 parser, you must include a line within the last 40 lines
1418 of your file matching the Perl regular expression:
1419 <tt>\schangelog-format:\s+([0-9a-z]+)\W</tt> The part in
1420 parentheses should be the name of the format. For
1421 example, you might say:
1423 @@@ changelog-format: joebloggs @@@
1425 Changelog format names are non-empty strings of alphanumerics.
1429 If such a line exists then <tt>dpkg-parsechangelog</tt>
1430 will look for the parser as
1431 <tt>/usr/lib/dpkg/parsechangelog/<var>format-name</var></tt>
1433 <tt>/usr/local/lib/dpkg/parsechangelog/<var>format-name</var></tt>;
1434 it is an error for it not to find it, or for it not to
1435 be an executable program. The default changelog format
1436 is <tt>dpkg</tt>, and a parser for it is provided with
1437 the <tt>dpkg</tt> package.
1441 The parser will be invoked with the changelog open on
1442 standard input at the start of the file. It should read
1443 the file (it may seek if it wishes) to determine the
1444 information required and return the parsed information
1445 to standard output in the form of a series of control
1446 fields in the standard format. By default it should
1447 return information about only the most recent version in
1448 the changelog; it should accept a
1449 <tt>-v<var>version</var></tt> option to return changes
1450 information from all versions present <em>strictly
1451 after</em> <var>version</var>, and it should then be an
1452 error for <var>version</var> not to be present in the
1458 <list compact="compact">
1460 <p><qref id="f-Source"><tt>Source</tt></qref></p>
1463 <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
1467 <qref id="f-Distribution"><tt>Distribution</tt></qref>
1472 <p><qref id="f-Urgency"><tt>Urgency</tt></qref> (mandatory)</p>
1476 <qref id="f-Maintainer"><tt>Maintainer</tt></qref>
1481 <p><qref id="f-Date"><tt>Date</tt></qref></p>
1485 <qref id="f-Changes"><tt>Changes</tt></qref>
1492 If several versions are being returned (due to the use
1493 of <tt>-v</tt>), the urgency value should be of the
1494 highest urgency code listed at the start of any of the
1495 versions requested followed by the concatenated
1496 (space-separated) comments from all the versions
1497 requested; the maintainer, version, distribution and
1498 date should always be from the most recent version.
1502 For the format of the <tt>Changes</tt> field see <ref
1507 If the changelog format which is being parsed always or
1508 almost always leaves a blank line between individual
1509 change notes these blank lines should be stripped out,
1510 so as to make the resulting output compact.
1514 If the changelog format does not contain date or package
1515 name information this information should be omitted from
1516 the output. The parser should not attempt to synthesise
1517 it or find it from other sources.
1521 If the changelog does not have the expected format the
1522 parser should exit with a nonzero exit status, rather
1523 than trying to muddle through and possibly generating
1528 A changelog parser may not interact with the user at
1532 <sect1 id="srcsubstvars"><heading><tt>debian/substvars</tt>
1533 and variable substitutions
1537 When <prgn>dpkg-gencontrol</prgn>,
1538 <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
1539 generate control files they do variable substitutions on
1540 their output just before writing it. Variable
1541 substitutions have the form
1542 <tt>${<var>variable-name</var>}</tt>. The optional file
1543 <tt>debian/substvars</tt> contains variable substitutions
1544 to be used; variables can also be set directly from
1545 <tt>debian/rules</tt> using the <tt>-V</tt> option to the
1546 source packaging commands, and certain predefined
1547 variables are available.
1551 The is usually generated and modified dynamically by
1552 <tt>debian/rules</tt> targets; in this case it must be
1553 removed by the <prgn>clean</prgn> target.
1557 See <manref name="dpkg-source" section="1"> for full
1558 details about source variable substitutions, including the
1559 format of <tt>debian/substvars</tt>.</p>
1562 <sect1><heading><tt>debian/files</tt>
1566 This file is not a permanent part of the source tree; it
1567 is used while building packages to record which files are
1568 being generated. <prgn>dpkg-genchanges</prgn> uses it
1569 when it generates a <tt>.changes</tt> file.
1573 It should not exist in a shipped source package, and so it
1574 (and any backup files or temporary files such as
1578 <tt>files.new</tt> is used as a temporary file by
1579 <prgn>dpkg-gencontrol</prgn> and
1580 <prgn>dpkg-distaddfile</prgn> - they write a new
1581 version of <tt>files</tt> here before renaming it,
1582 to avoid leaving a corrupted copy if an error
1585 </footnote>) should be removed by the
1586 <prgn>clean</prgn> target. It may also be wise to
1587 ensure a fresh start by emptying or removing it at the
1588 start of the <prgn>binary</prgn> target.
1592 <prgn>dpkg-gencontrol</prgn> adds an entry to this file
1593 for the <tt>.deb</tt> file that will be created by
1594 <prgn>dpkg-deb</prgn> from the control file that it
1595 generates, so for most packages all that needs to be done
1596 with this file is to delete it in <prgn>clean</prgn>.
1600 If a package upload includes files besides the source
1601 package and any binary packages whose control files were
1602 made with <prgn>dpkg-gencontrol</prgn> then they should be
1603 placed in the parent of the package's top-level directory
1604 and <prgn>dpkg-distaddfile</prgn> should be called to add
1605 the file to the list in <tt>debian/files</tt>.</p>
1608 <sect1><heading><tt>debian/tmp</tt>
1612 This is the canonical temporary location for the
1613 construction of binary packages by the <prgn>binary</prgn>
1614 target. The directory <tt>tmp</tt> serves as the root of
1615 the filesystem tree as it is being constructed (for
1616 example, by using the package's upstream makefiles install
1617 targets and redirecting the output there), and it also
1618 contains the <tt>DEBIAN</tt> subdirectory. See <ref
1623 If several binary packages are generated from the same
1624 source tree it is usual to use several
1625 <tt>debian/tmp<var>something</var></tt> directories, for
1626 example <tt>tmp-a</tt> or <tt>tmp-doc</tt>.
1630 Whatever <tt>tmp</tt> directories are created and used by
1631 <prgn>binary</prgn> must of course be removed by the
1632 <prgn>clean</prgn> target.</p></sect1>
1636 <sect id="sourcearchives"><heading>Source packages as archives
1640 As it exists on the FTP site, a Debian source package
1641 consists of three related files. You must have the right
1642 versions of all three to be able to use them.
1647 <tag>Debian source control file - <tt>.dsc</tt></tag>
1651 This file contains a series of fields, identified and
1652 separated just like the fields in the control file of
1653 a binary package. The fields are listed below; their
1654 syntax is described above, in <ref id="controlfields">.
1655 <list compact="compact">
1657 <p><qref id="f-Source"><tt>Source</tt></qref></p>
1660 <p><qref id="versions"><tt>Version</tt></qref></p>
1663 <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
1666 <p><qref id="f-Binary"><tt>Binary</tt></qref></p>
1669 <p><qref id="f-Architecture"><tt>Architecture</tt></qref></p>
1673 <qref id="relationships"><tt>Build-Depends</tt> et
1674 al.</qref> (source package interrelationships)
1679 <qref id="f-Standards-Version"><tt>Standards-Version</tt></qref></p>
1682 <p><qref id="f-Files"><tt>Files</tt></qref></p>
1687 The source package control file is generated by
1688 <prgn>dpkg-source</prgn> when it builds the source
1689 archive, from other files in the source package,
1690 described above. When unpacking it is checked against
1691 the files and directories in the other parts of the
1692 source package, as described below.</p>
1696 Original source archive -
1698 <var>package</var>_<var>upstream-version</var>.orig.tar.gz
1705 This is a compressed (with <tt>gzip -9</tt>)
1706 <prgn>tar</prgn> file containing the source code from
1707 the upstream authors of the program. The tarfile
1708 unpacks into a directory
1709 <tt><var>package</var>-<var>upstream-version</var>.orig</tt>,
1710 and does not contain files anywhere other than in
1711 there or in its subdirectories.</p>
1715 Debianisation diff -
1717 <var>package</var>_<var>upstream_version-revision</var>.diff.gz
1723 This is a unified context diff (<tt>diff -u</tt>)
1724 giving the changes which are required to turn the
1725 original source into the Debian source. These changes
1726 may only include editing and creating plain files.
1727 The permissions of files, the targets of symbolic
1728 links and the characteristics of special files or
1729 pipes may not be changed and no files may be removed
1734 All the directories in the diff must exist, except the
1735 <tt>debian</tt> subdirectory of the top of the source
1736 tree, which will be created by
1737 <prgn>dpkg-source</prgn> if necessary when unpacking.
1741 The <prgn>dpkg-source</prgn> program will
1742 automatically make the <tt>debian/rules</tt> file
1743 executable (see below).</p></item>
1748 If there is no original source code - for example, if the
1749 package is specially prepared for Debian or the Debian
1750 maintainer is the same as the upstream maintainer - the
1751 format is slightly different: then there is no diff, and the
1753 <tt><var>package</var>_<var>version</var>.tar.gz</tt> and
1754 contains a directory
1755 <tt><var>package</var>-<var>version</var></tt>.
1759 <sect><heading>Unpacking a Debian source package without
1760 <prgn>dpkg-source</prgn>
1764 <tt>dpkg-source -x</tt> is the recommended way to unpack a
1765 Debian source package. However, if it is not available it
1766 is possible to unpack a Debian source archive as follows:
1767 <enumlist compact="compact">
1770 Untar the tarfile, which will create a <tt>.orig</tt>
1774 <p>Rename the <tt>.orig</tt> directory to
1775 <tt><var>package</var>-<var>version</var></tt>.</p>
1779 Create the subdirectory <tt>debian</tt> at the top of
1780 the source tree.</p>
1782 <item><p>Apply the diff using <tt>patch -p0</tt>.</p>
1784 <item><p>Untar the tarfile again if you want a copy of the original
1785 source code alongside the Debianised version.</p>
1790 It is not possible to generate a valid Debian source archive
1791 without using <prgn>dpkg-source</prgn>. In particular,
1792 attempting to use <prgn>diff</prgn> directly to generate the
1793 <tt>.diff.gz</tt> file will not work.
1796 <sect1><heading>Restrictions on objects in source packages
1800 The source package may not contain any hard links
1803 This is not currently detected when building source
1804 packages, but only when extracting
1810 Hard links may be permitted at some point in the
1811 future, but would require a fair amount of
1814 </footnote>, device special files, sockets or setuid or
1818 Setgid directories are allowed.
1824 The source packaging tools manage the changes between the
1825 original and Debianised source using <prgn>diff</prgn> and
1826 <prgn>patch</prgn>. Turning the original source tree as
1827 included in the <tt>.orig.tar.gz</tt> into the debianised
1828 source must not involve any changes which cannot be
1829 handled by these tools. Problematic changes which cause
1830 <prgn>dpkg-source</prgn> to halt with an error when
1831 building the source package are:
1832 <list compact="compact">
1833 <item><p>Adding or removing symbolic links, sockets or pipes.</p>
1835 <item><p>Changing the targets of symbolic links.</p>
1837 <item><p>Creating directories, other than <tt>debian</tt>.</p>
1839 <item><p>Changes to the contents of binary files.</p></item>
1840 </list> Changes which cause <prgn>dpkg-source</prgn> to
1841 print a warning but continue anyway are:
1842 <list compact="compact">
1845 Removing files, directories or symlinks.
1848 Renaming a file is not treated specially - it is
1849 seen as the removal of the old file (which
1850 generates a warning, but is otherwise ignored),
1851 and the creation of the new
1858 Changed text files which are missing the usual final
1859 newline (either in the original or the modified
1864 Changes which are not represented, but which are not detected by
1865 <prgn>dpkg-source</prgn>, are:
1866 <list compact="compact">
1867 <item><p>Changing the permissions of files (other than
1868 <tt>debian/rules</tt>) and directories.</p></item>
1873 The <tt>debian</tt> directory and <tt>debian/rules</tt>
1874 are handled specially by <prgn>dpkg-source</prgn> - before
1875 applying the changes it will create the <tt>debian</tt>
1876 directory, and afterwards it will make
1877 <tt>debian/rules</tt> world-exectuable.
1883 <chapt id="controlfields"><heading>Control files and their fields
1887 Many of the tools in the <prgn>dpkg</prgn> suite manipulate
1888 data in a common format, known as control files. Binary and
1889 source packages have control data as do the <tt>.changes</tt>
1890 files which control the installation of uploaded files, and
1891 <prgn>dpkg</prgn>'s internal databases are in a similar
1895 <sect><heading>Syntax of control files
1899 A file consists of one or more paragraphs of fields. The
1900 paragraphs are separated by blank lines. Some control files
1901 only allow one paragraph; others allow several, in which
1902 case each paragraph often refers to a different package.
1906 Each paragraph is a series of fields and values; each field
1907 consists of a name, followed by a colon and the value. It
1908 ends at the end of the line. Horizontal whitespace (spaces
1909 and tabs) may occur before or after the value and is ignored
1910 there; it is conventional to put a single space after the
1915 Some fields' values may span several lines; in this case
1916 each continuation line <em>must</em> start with a space or
1917 tab. Any trailing spaces or tabs at the end of individual
1918 lines of a field value are ignored.
1922 Except where otherwise stated only a single line of data is
1923 allowed and whitespace is not significant in a field body.
1924 Whitespace may never appear inside names (of packages,
1925 architectures, files or anything else), version numbers or
1926 in between the characters of multi-character version
1931 Field names are not case-sensitive, but it is usual to
1932 capitalise the field names using mixed case as shown below.
1936 Blank lines, or lines consisting only of spaces and tabs,
1937 are not allowed within field values or between fields - that
1938 would mean a new paragraph.
1942 It is important to note that there are several fields which
1943 are optional as far as <prgn>dpkg</prgn> and the related
1944 tools are concerned, but which must appear in every Debian
1945 package, or whose omission may cause problems. When writing
1946 the control files for Debian packages you <em>must</em> read
1947 the Debian policy manual in conjuction with the details
1948 below and the list of fields for the particular file.</p>
1951 <sect><heading>List of fields
1954 <sect1 id="f-Package"><heading><tt>Package</tt>
1958 The name of the binary package. Package names consist of
1959 the alphanumerics and <tt>+</tt> <tt>-</tt> <tt>.</tt>
1960 (plus, minus and full stop).
1963 The characters <tt>@</tt> <tt>:</tt> <tt>=</tt>
1964 <tt>%</tt> <tt>_</tt> (at, colon, equals, percent
1965 and underscore) used to be legal and are still
1966 accepted when found in a package file, but may not be
1967 used in new packages
1973 They must be at least two characters and must start with
1974 an alphanumeric. In current versions of dpkg they are
1975 sort of case-sensitive<footnote><p>This is a
1976 bug.</p></footnote>; use lowercase package names unless
1977 the package you're building (or referring to, in other
1978 fields) is already using uppercase.</p>
1981 <sect1 id="f-Version"><heading><tt>Version</tt>
1985 This lists the source or binary package's version number -
1986 see <ref id="versions">.
1991 <sect1 id="f-Architecture"><heading><tt>Architecture</tt>
1995 This is the architecture string; it is a single word for
1996 the Debian architecture.
2000 <prgn>dpkg</prgn> will check the declared architecture of
2001 a binary package against its own compiled-in value before
2006 The special value <tt>all</tt> indicates that the package
2007 is architecture-independent.
2011 In the main <tt>debian/control</tt> file in the source
2012 package, or in the source package control file
2013 <tt>.dsc</tt>, a list of architectures (separated by
2014 spaces) is also allowed, as is the special value
2015 <tt>any</tt>. A list indicates that the source will build
2016 an architecture-dependent package, and will only work
2017 correctly on the listed architectures. <tt>any</tt>
2018 indicates that though the source package isn't dependent
2019 on any particular architecture and should compile fine on
2020 any one, the binary package(s) produced are not
2021 architecture-independent but will instead be specific to
2022 whatever the current build architecture is.
2026 In a <tt>.changes</tt> file the <tt>Architecture</tt>
2027 field lists the architecture(s) of the package(s)
2028 currently being uploaded. This will be a list; if the
2029 source for the package is being uploaded too the special
2030 entry <tt>source</tt> is also present.
2034 See <ref id="debianrules"> for information how to get the
2035 architecture for the build process.
2039 <sect1 id="f-Maintainer"><heading><tt>Maintainer</tt>
2043 The package maintainer's name and email address. The name
2044 should come first, then the email address inside angle
2045 brackets <tt><></tt> (in RFC822 format).
2049 If the maintainer's name contains a full stop then the
2050 whole field will not work directly as an email address due
2051 to a misfeature in the syntax specified in RFC822; a
2052 program using this field as an address must check for this
2053 and correct the problem if necessary (for example by
2054 putting the name in round brackets and moving it to the
2055 end, and bringing the email address forward).
2059 In a <tt>.changes</tt> file or parsed changelog data this
2060 contains the name and email address of the person
2061 responsible for the particular version in question - this
2062 may not be the package's usual maintainer.
2066 This field is usually optional in as far as the
2067 <prgn>dpkg</prgn> are concerned, but its absence when
2068 building packages usually generates a warning.</p>
2071 <sect1 id="f-Source"><heading><tt>Source</tt>
2075 This field identifies the source package name.
2079 In a main source control information or a
2080 <tt>.changes</tt> or <tt>.dsc</tt> file or parsed
2081 changelog data this may contain only the name of the
2086 In the control file of a binary package (or in a
2087 <tt>Packages</tt> file) it may be followed by a version
2088 number in parentheses.
2091 It is usual to leave a space after the package name if
2092 a version number is specified.
2094 </footnote> This version number may be omitted (and is, by
2095 <prgn>dpkg-gencontrol</prgn>) if it has the same value as
2096 the <tt>Version</tt> field of the binary package in
2097 question. The field itself may be omitted from a binary
2098 package control file when the source package has the same
2099 name and version as the binary package.
2103 <sect1><heading>Package interrelationship fields:
2104 <tt>Depends</tt>, <tt>Pre-Depends</tt>,
2105 <tt>Recommends</tt> <tt>Suggests</tt>, <tt>Conflicts</tt>,
2106 <tt>Provides</tt>, <tt>Replaces</tt>
2110 These fields describe the package's relationships with
2111 other packages. Their syntax and semantics are described
2112 in <ref id="relationships">.</p>
2115 <sect1 id="f-Description"><heading><tt>Description</tt>
2119 In a binary package <tt>Packages</tt> file or main source
2120 control file this field contains a description of the
2121 binary package, in a special format. See <ref
2122 id="descriptions"> for details.
2126 In a <tt>.changes</tt> file it contains a summary of the
2127 descriptions for the packages being uploaded. The part of
2128 the field before the first newline is empty; thereafter
2129 each line has the name of a binary package and the summary
2130 description line from that binary package. Each line is
2131 indented by one space.</p>
2134 <sect1 id="f-Essential"><heading><tt>Essential</tt>
2138 This is a boolean field which may occur only in the
2139 control file of a binary package (or in the
2140 <tt>Packages</tt> file) or in a per-package fields
2141 paragraph of a main source control data file.
2145 If set to <tt>yes</tt> then <prgn>dpkg</prgn> and
2146 <prgn>dselect</prgn> will refuse to remove the package
2147 (though it can be upgraded and/or replaced). The other
2148 possible value is <tt>no</tt>, which is the same as not
2149 having the field at all.</p>
2152 <sect1 id="f-classification"><heading><tt>Section</tt> and
2157 These two fields classify the package. The
2158 <tt>Priority</tt> represents how important that it is that
2159 the user have it installed; the <tt>Section</tt>
2160 represents an application area into which the package has
2165 When they appear in the <tt>debian/control</tt> file these
2166 fields give values for the section and priority subfields
2167 of the <tt>Files</tt> field of the <tt>.changes</tt> file,
2168 and give defaults for the section and priority of the
2173 The section and priority are represented, though not as
2174 separate fields, in the information for each file in the
2175 <qref id="f-Files"><tt>-File</tt></qref>field of a
2176 <tt>.changes</tt> file. The section value in a
2177 <tt>.changes</tt> file is used to decide where to install
2178 a package in the FTP archive.
2182 These fields are not used by by <prgn>dpkg</prgn> proper,
2183 but by <prgn>dselect</prgn> when it sorts packages and
2184 selects defaults. See the Debian policy manual for the
2185 priorities in use and the criteria for selecting the
2186 priority for a Debian package, and look at the Debian FTP
2187 archive for a list of currently in-use priorities.
2191 These fields may appear in binary package control files,
2192 in which case they provide a default value in case the
2193 <tt>Packages</tt> files are missing the information.
2194 <prgn>dpkg</prgn> and <prgn>dselect</prgn> will only use
2195 the value from a <tt>.deb</tt> file if they have no other
2196 information; a value listed in a <tt>Packages</tt> file
2197 will always take precedence. By default
2198 <prgn>dpkg-genchanges</prgn> does not include the section
2199 and priority in the control file of a binary package - use
2200 the <tt>-isp</tt>, <tt>-is</tt> or <tt>-ip</tt> options to
2201 achieve this effect.</p>
2204 <sect1 id="f-Binary"><heading><tt>Binary</tt>
2208 This field is a list of binary packages.
2212 When it appears in the <tt>.dsc</tt> file it is the list
2213 of binary packages which a source package can produce. It
2214 does not necessarily produce all of these binary packages
2215 for every architecture. The source control file doesn't
2216 contain details of which architectures are appropriate for
2217 which of the binary packages.
2221 When it appears in a <tt>.changes</tt> file it lists the
2222 names of the binary packages actually being uploaded.
2226 The syntax is a list of binary packages separated by
2230 A space after each comma is conventional.
2232 </footnote> Currently the packages must be separated using
2233 only spaces in the <tt>.changes</tt> file.</p>
2236 <sect1 id="f-Installed-Size"><heading><tt>Installed-Size</tt>
2240 This field appears in the control files of binary
2241 packages, and in the <tt>Packages</tt> files. It gives
2242 the total amount of disk space required to install the
2247 The disk space is represented in kilobytes as a simple
2251 <sect1 id="f-Files"><heading><tt>Files</tt>
2255 This field contains a list of files with information about
2256 each one. The exact information and syntax varies with
2257 the context. In all cases the the part of the field
2258 contents on the same line as the field name is empty. The
2259 remainder of the field is one line per file, each line
2260 being indented by one space and containing a number of
2261 sub-fields separated by spaces.
2265 In the <tt>.dsc</tt> (Debian source control) file each
2266 line contains the MD5 checksum, size and filename of the
2267 tarfile and (if applicable) diff file which make up the
2268 remainder of the source package.
2271 That is, the parts which are not the
2274 </footnote> The exact forms of the filenames are described
2275 in <ref id="sourcearchives">.
2279 In the <tt>.changes</tt> file this contains one line per
2280 file being uploaded. Each line contains the MD5 checksum,
2281 size, section and priority and the filename. The section
2282 and priority are the values of the corresponding fields in
2283 the main source control file - see <ref
2284 id="f-classification">. If no section or priority is
2285 specified then <tt>-</tt> should be used, though section
2286 and priority values must be specified for new packages to
2287 be installed properly.
2291 The special value <tt>byhand</tt> for the section in a
2292 <tt>.changes</tt> file indicates that the file in question
2293 is not an ordinary package file and must by installed by
2294 hand by the distribution maintainers. If the section is
2295 <tt>byhand</tt> the priority should be <tt>-</tt>.
2299 If a new Debian revision of a package is being shipped and
2300 no new original source archive is being distributed the
2301 <tt>.dsc</tt> must still contain the <tt>Files</tt> field
2302 entry for the original source archive
2303 <tt><var>package</var>-<var>upstream-version</var>.orig.tar.gz</tt>,
2304 but the <tt>.changes</tt> file should leave it out. In
2305 this case the original source archive on the distribution
2306 site must match exactly, byte-for-byte, the original
2307 source archive which was used to generate the
2308 <tt>.dsc</tt> file and diff which are being uploaded.</p>
2313 id="f-Standards-Version"><heading><tt>Standards-Version</tt>
2317 The most recent version of the standards (the
2318 <prgn>dpkg</prgn> programmers' and policy manuals and
2319 associated texts) with which the package complies. This
2320 is updated manually when editing the source package to
2321 conform to newer standards; it can sometimes be used to
2322 tell when a package needs attention.
2326 Its format is the same as that of a version number except
2327 that no epoch or Debian revision is allowed - see <ref
2332 <sect1 id="f-Distribution"><heading><tt>Distribution</tt>
2336 In a <tt>.changes</tt> file or parsed changelog output
2337 this contains the (space-separated) name(s) of the
2338 distribution(s) where this version of the package should
2339 be or was installed. Distribution names follow the rules
2340 for package names. (See <ref id="f-Package">).
2344 Current distribution values are:
2346 <tag><em>stable</em></tag>
2349 This is the current `released' version of Debian
2350 GNU/Linux. A new version is released approximately
2351 every 3 months after the <em>development</em> code has
2352 been <em>frozen</em> for a month of testing. Once the
2353 distribution is <em>stable</em> only major bug fixes
2354 are allowed. When changes are made to this
2355 distribution, the release number is increased
2356 (for example: 1.2r1 becomes 1.2r2 then 1.2r3, etc).
2360 <tag><em>unstable</em></tag>
2363 This distribution value refers to the
2364 <em>developmental</em> part of the Debian distribution
2365 tree. New packages, new upstream versions of packages
2366 and bug fixes go into the <em>unstable</em> directory
2367 tree. Download from this distribution at your own
2371 <tag><em>contrib</em></tag>
2374 The packages with this distribution value do not meet
2375 the criteria for inclusion in the main Debian
2376 distribution as defined by the Policy Manual, but meet
2377 the criteria for the <em>contrib</em>
2378 Distribution. There is currently no distinction
2379 between stable and unstable packages in the
2380 <em>contrib</em> or <em>non-free</em>
2381 distributions. Use your best judgement in downloading
2382 from this Distribution.</p>
2385 <tag><em>non-free</em></tag>
2388 Like the packages in the <em>contrib</em> seciton,
2389 the packages in <em>non-free</em> do not meet the
2390 criteria for inclusion in the main Debian distribution
2391 as defined by the Policy Manual. Again, use your best
2392 judgement in downloading from this Distribution.</p>
2394 <tag><em>experimental</em></tag>
2397 The packages with this distribution value are deemed
2398 by their maintainers to be high risk. Oftentimes they
2399 represent early beta or developmental packages from
2400 various sources that the maintainers want people to
2401 try, but are not ready to be a part of the other parts
2402 of the Debian distribution tree. Download at your own
2406 <tag><em>frozen</em></tag>
2409 From time to time, (currently, every 3 months) the
2410 <em>unstable</em> distribution enters a state of
2411 `code-freeze' in anticipation of release as a
2412 <em>stable</em> version. During this period of testing
2413 (usually 4 weeks) only fixes for existing or
2414 newly-discovered bugs will be allowed.
2417 </taglist> You should list <em>all</em> distributions that
2418 the package should be installed into. Except in unusual
2419 circumstances, installations to <em>stable</em> should also
2420 go into <em>frozen</em> (if it exists) and
2421 <em>unstable</em>. Likewise, installations into
2422 <em>frozen</em> should also go into <em>unstable</em>.</p>
2425 <sect1 id="f-Urgency"><heading><tt>Urgency</tt>
2429 This is a description of how important it is to upgrade to
2430 this version from previous ones. It consists of a single
2431 keyword usually taking one of the values <tt>LOW</tt>,
2432 <tt>MEDIUM</tt> or <tt>HIGH</tt>) followed by an optional
2433 commentary (separated by a space) which is usually in
2434 parentheses. For example:
2436 Urgency: LOW (HIGH for diversions users)
2441 This field appears in the <tt>.changes</tt> file and in
2442 parsed changelogs; its value appears as the value of the
2443 <tt>urgency</tt> attribute in a <prgn>dpkg</prgn>-style
2444 changelog (see <ref id="dpkgchangelog">).
2448 Urgency keywords are not case-sensitive.</p>
2451 <sect1 id="f-Date"><heading><tt>Date</tt>
2455 In <tt>.changes</tt> files and parsed changelogs, this
2456 gives the date the package was built or last edited.</p>
2459 <sect1 id="f-Format"><heading><tt>Format</tt>
2463 This field occurs in <tt>.changes</tt> files, and
2464 specifies a format revision for the file. The format
2465 described here is version <tt>1.5</tt>. The syntax of the
2466 format value is the same as that of a package version
2467 number except that no epoch or Debian revision is allowed
2468 - see <ref id="versions">.</p>
2471 <sect1 id="f-Changes"><heading><tt>Changes</tt>
2475 In a <tt>.changes</tt> file or parsed changelog this field
2476 contains the human-readable changes data, describing the
2477 differences between the last version and the current one.
2481 There should be nothing in this field before the first
2482 newline; all the subsequent lines must be indented by at
2483 least one space; blank lines must be represented by a line
2484 consiting only of a space and a full stop.
2488 Each version's change information should be preceded by a
2489 `title' line giving at least the version, distribution(s)
2490 and urgency, in a human-readable way.
2494 If data from several versions is being returned the entry
2495 for the most recent version should be returned first, and
2496 entries should be separated by the representation of a
2497 blank line (the `title' line may also be followed by the
2498 representation of blank line).</p>
2501 <sect1 id="f-Filename"><heading><tt>Filename</tt> and
2502 <tt>MSDOS-Filename</tt>
2506 These fields in <tt>Packages</tt> files give the
2507 filename(s) of (the parts of) a package in the
2508 distribution directories, relative to the root of the
2509 Debian hierarchy. If the package has been split into
2510 several parts the parts are all listed in order, separated
2514 <sect1 id="f-Size"><heading><tt>Size</tt> and <tt>MD5sum</tt>
2518 These fields in <tt>Packages</tt> files give the size (in
2519 bytes, expressed in decimal) and MD5 checksum of the
2520 file(s) which make(s) up a binary package in the
2521 distribution. If the package is split into several parts
2522 the values for the parts are listed in order, separated by
2526 <sect1 id="f-Status"><heading><tt>Status</tt>
2530 This field in <prgn>dpkg</prgn>'s status file records
2531 whether the user wants a package installed, removed or
2532 left alone, whether it is broken (requiring
2533 reinstallation) or not and what its current state on the
2534 system is. Each of these pieces of information is a
2538 <sect1 id="f-Config-Version"><heading><tt>Config-Version</tt>
2542 If a package is not installed or not configured, this
2543 field in <prgn>dpkg</prgn>'s status file records the last
2544 version of the package which was successfully
2548 <sect1 id="f-Conffiles"><heading><tt>Conffiles</tt>
2552 This field in <prgn>dpkg</prgn>'s status file contains
2553 information about the automatically-managed configuration
2554 files held by a package. This field should <em>not</em>
2555 appear anywhere in a package!</p>
2558 <sect1><heading>Obsolete fields
2562 These are still recognised by <prgn>dpkg</prgn> but should
2563 not appear anywhere any more.
2564 <taglist compact="compact">
2566 <tag><tt>Revision</tt></tag>
2567 <tag><tt>Package-Revision</tt></tag>
2568 <tag><tt>Package_Revision</tt></tag>
2571 The Debian revision part of the package version was
2572 at one point in a separate control file field. This
2573 field went through several names.</p>
2576 <tag><tt>Recommended</tt></tag>
2577 <item><p>Old name for <tt>Recommends</tt></p>
2580 <tag><tt>Optional</tt></tag>
2581 <item><p>Old name for <tt>Suggests</tt>.</p>
2583 <tag><tt>Class</tt></tag>
2584 <item><p>Old name for <tt>Priority</tt>.</p>
2592 <chapt id="versions"><heading>Version numbering
2596 Every package has a version number, in its <tt>Version</tt>
2601 <prgn>dpkg</prgn> imposes an ordering on version numbers, so
2602 that it can tell whether packages are being up- or downgraded
2603 and so that <prgn>dselect</prgn> can tell whether a package it
2604 finds available is newer than the one installed on the system.
2605 The version number format has the most significant parts (as
2606 far as comparison is concerned) at the beginning.
2610 The version number format is:
2611 &lsqb<var>epoch/<tt>:</tt>]<var>upstream-version</var>[<tt>-/<var>debian-revision</var>].</tt></var>
2615 The three components here are:
2617 <tag><var>epoch</var></tag>
2621 This is a single unsigned integer, which should usually
2622 be small. It may be omitted, in which case zero is
2623 assumed. If it is omitted then the
2624 <var>upstream-version</var> may not contain any colons.
2628 It is provided to allow mistakes in the version numbers
2629 of older versions of a package, and also a package's
2630 previous version numbering schemes, to be left behind.
2634 <prgn>dpkg</prgn> will not usually display the epoch
2635 unless it is essential (non-zero, or if the
2636 <var>upstream-version</var> contains a colon);
2637 <prgn>dselect</prgn> does not display epochs at all in
2638 the main part of the package selection display.</p>
2641 <tag><var>upstream-version</var></tag>
2645 This is the main part of the version. It is usually
2646 version number of the original (`upstream') package of
2647 which the <tt>.deb</tt> file has been made, if this is
2648 applicable. Usually this will be in the same format as
2649 that specified by the upstream author(s); however, it
2650 may need to be reformatted to fit into
2651 <prgn>dpkg</prgn>'s format and comparison scheme.
2655 The comparison behaviour of <prgn>dpkg</prgn> with
2656 respect to the <var>upstream-version</var> is described
2657 below. The <var>upstream-version</var> portion of the
2658 version number is mandatory.
2662 The <var>upstream-version</var> may contain only
2663 alphanumerics and the characters <tt>.</tt> <tt>+</tt>
2664 <tt>-</tt> <tt>:</tt> (full stop, plus, hyphen, colon)
2665 and should start with a digit. If there is no
2666 <var>debian-revision</var> then hyphens are not allowed;
2667 if there is no <var>epoch</var> then colons are not
2671 <tag><var>debian-revision</var></tag>
2675 This part of the version represents the version of the
2676 modifications that were made to the package to make it a
2677 Debian binary package. It is in the same format as the
2678 <var>upstream-version</var> and <prgn>dpkg</prgn>
2679 compares it in the same way.
2683 It is optional; if it isn't present then the
2684 <var>upstream-version</var> may not contain a hyphen.
2685 This format represents the case where a piece of
2686 software was written specifically to be turned into a
2687 Debian binary package, and so there is only one
2688 `debianization' of it and therefore no revision
2689 indication is required.
2693 It is conventional to restart the
2694 <var>debian-revision</var> at <tt>1</tt> each time the
2695 <var>upstream-version</var> is increased.
2699 <prgn>dpkg</prgn> will break the
2700 <var>upstream-version</var> and
2701 <var>debian-revision</var> apart at the last hyphen in
2702 the string. The absence of a <var>debian-revision</var>
2703 compares earlier than the presence of one (but note that
2704 the <var>debian-revision</var> is the least significant
2705 part of the version number).
2709 The <var>debian-revision</var> may contain only
2710 alphanumerics and the characters <tt>+</tt> and
2711 <tt>.</tt> (plus and full stop).
2715 The <var>upstream-version</var> and <var>debian-revision</var> parts are
2716 compared by <prgn>dpkg</prgn> using the same algorithm:
2720 The strings are compared from left to right.
2724 First the initial part of each string consisting entirely of
2725 non-digit characters is determined. These two parts (one of
2726 which may be empty) are compared lexically. If a difference
2727 is found it is returned. The lexical comparison is a
2728 comparison of ASCII values modified so that all the letters
2729 sort earlier than all the non-letters.
2733 Then the initial part of the remainder of each string which
2734 consists entirely of digit characters is determined. The
2735 numerical values of these two parts are compared, and any
2736 difference found is returned as the result of the comparison.
2737 For these purposes an empty string (which can only occur at
2738 the end of one or both version strings being compared) counts
2743 These two steps are repeated (chopping initial non-digit
2744 strings and initial digit strings off from the start) until a
2745 difference is found or both strings are exhausted.
2749 Note that the purpose of epochs is to allow us to leave behind
2750 mistakes in version numbering, and to cope with situations
2751 where the version numbering changes. It is <em>not</em> there
2752 to cope with version numbers containing strings of letters
2753 which <prgn>dpkg</prgn> cannot interpret (such as
2754 <tt>ALPHA</tt> or <tt>pre-</tt>), or with silly orderings (the
2755 author of this manual has heard of a package whose versions
2756 went <tt>1.1</tt>, <tt>1.2</tt>, <tt>1.3</tt>, <tt>1</tt>,
2757 <tt>2.1</tt>, <tt>2.2</tt>, <tt>2</tt> and so forth).
2761 If an upstream package has problematic version numbers they
2762 should be converted to a sane form for use in the
2763 <tt>Version</tt> field.
2767 If you need to compare version numbers in a script, you may use
2768 <tt>dpkg --compare-versions ...</tt>. Type <tt>dpkg
2769 --help</tt> for details on arguments.
2773 <heading>Version numbers based on dates</heading>
2775 In general, Debian packages should use the same version
2776 numbers as the upstream sources.</p>
2779 However, in some cases where the upstream version number is
2780 based on a date (e.g., a development `snapshot' release)
2781 dpkg cannot handle these version numbers currently, without
2782 epochs. For example, dpkg will consider `96May01' to be
2783 greater than `96Dec24'.</p>
2786 To prevent having to use epochs for every new upstream
2787 version, the version number should be changed to the
2788 following format in such cases: `19960501', `19961224'. It
2789 is up to the maintainer whether he/she wants to bother the
2790 upstream maintainer to change the version numbers upstream,
2794 Note, that other version formats based on dates which are
2795 parsed correctly by dpkg should <em>not</em> be changed.</p>
2798 Native Debian packages (i.e., packages which have been
2799 written especially for Debian) whose version numbers include
2800 dates should always use the `YYYYMMDD' format.</p>
2804 <chapt id="maintainerscripts"><heading>Package maintainer scripts
2805 and installation procedure
2808 <sect><heading>Introduction to package maintainer scripts
2812 It is possible to supply scripts as part of a package which
2813 <prgn>dpkg</prgn> will run for you when your package is
2814 installed, upgraded or removed.
2818 These scripts should be the files <tt>preinst</tt>,
2819 <tt>postinst</tt>, <tt>prerm</tt> and <tt>postrm</tt> in the
2820 control area of the package. They must be proper exectuable
2821 files; if they are scripts (which is recommended) they must
2822 start with the usual <tt>#!</tt> convention. They should be
2823 readable and executable to anyone, and not world-writeable.
2827 <prgn>dpkg</prgn> looks at the exit status from these
2828 scripts. It is important that they exit with a non-zero
2829 status if there is an error, so that <prgn>dpkg</prgn> can
2830 stop its processing. For shell scripts this means that you
2831 <em>almost always</em> need to use <tt>set -e</tt> (this is
2832 usually true when writing shell scripts, in fact). It is
2833 also important, of course, that they don't exit with a
2834 non-zero status if everything went well.
2838 It is necessary for the error recovery procedures that the
2839 scripts be idempotent: ie, invoking the same script several
2840 times in the same situation should do no harm. If the first
2841 call failed, or aborted half way through for some reason,
2842 the second call should merely do the things that were left
2843 undone the first time, if any, and exit with a success
2848 When a package is upgraded a combination of the scripts from
2849 the old and new packages is called in amongst the other
2850 steps of the upgrade procedure. If your scripts are going
2851 to be at all complicated you need to be aware of this, and
2852 may need to check the arguments to your scripts.
2856 Broadly speaking the <prgn>preinst</prgn> is called before
2857 (a particular version of) a package is installed, and the
2858 <prgn>postinst</prgn> afterwards; the <prgn>prerm</prgn>
2859 before (a version of) a package is removed and the
2860 <prgn>postrm</prgn> afterwards.
2863 next paragraph by Guy Maor to close bug #2481
2866 <p> Programs called from maintainer scripts should not
2867 normally have a path prepended to them. Before installation
2868 is started <prgn>dpkg</prgn> checks to see if the programs
2869 <prgn>ldconfig</prgn>, <prgn>start-stop-daemon</prgn>,
2870 <prgn>install-info</prgn>, and <prgn>update-rc.d</prgn> can
2871 be found via the <tt>PATH</tt> environment variable. Those
2872 programs, and any other program that one would expect to on
2873 the <tt>PATH</tt>, should thus be invoked without an
2874 absolute pathname. Maintainer scripts should also not reset
2875 the <tt>PATH</tt>, though they might choose to modify it by
2876 pre- or appending package-specific directories. These
2877 considerations really apply to all shell scripts.</p>
2880 <sect id="mscriptsinstact"><heading>Summary of ways maintainer
2885 <list compact="compact">
2887 <p><var>new-preinst</var> <tt>install</tt></p>
2890 <p><var>new-preinst</var> <tt>install</tt>
2891 <var>old-version</var></p>
2894 <p><var>new-preinst</var> <tt>upgrade</tt>
2895 <var>old-version</var></p>
2898 <p><var>old-preinst</var> <tt>abort-upgrade</tt>
2899 <var>new-version</var>
2905 <list compact="compact">
2907 <p><var>postinst</var> <tt>configure</tt>
2908 <var>most-recently-configured-version</var></p>
2911 <p><var>old-postinst</var> <tt>abort-upgrade</tt>
2912 <var>new version</var></p>
2915 <p><var>conflictor's-postinst</var> <tt>abort-remove</tt>
2916 <tt>in-favour</tt> <var>package</var>
2917 <var>new-version</var></p>
2921 <var>deconfigured's-postinst</var>
2922 <tt>abort-deconfigure</tt> <tt>in-favour</tt>
2923 <var>failed-install-package</var> <var>version</var>
2924 <tt>removing</tt> <var>conflicting-package</var>
2931 <list compact="compact">
2933 <p><var>prerm</var> <tt>remove</tt></p>
2936 <p><var>old-prerm</var> <tt>upgrade</tt>
2937 <var>new-version</var></p>
2940 <p><var>new-prerm</var> <tt>failed-upgrade</tt>
2941 <var>old-version</var></p>
2944 <p><var>conflictor's-prerm</var> <tt>remove</tt>
2945 <tt>in-favour</tt> <var>package</var>
2946 <var>new-version</var></p>
2950 <var>deconfigured's-prerm</var> <tt>deconfigure</tt>
2951 <tt>in-favour</tt> <var>package-being-installed</var>
2952 <var>version</var> <tt>removing</tt>
2953 <var>conflicting-package</var>
2960 <list compact="compact">
2962 <p><var>postrm</var> <tt>remove</tt></p>
2965 <p><var>postrm</var> <tt>purge</tt></p>
2969 <var>old-postrm</var> <tt>upgrade</tt>
2970 <var>new-version</var></p>
2973 <p><var>new-postrm</var> <tt>failed-upgrade</tt>
2974 <var>old-version</var></p>
2977 <p><var>new-postrm</var> <tt>abort-install</tt></p>
2980 <p><var>new-postrm</var> <tt>abort-install</tt>
2981 <var>old-version</var></p>
2984 <p><var>new-postrm</var> <tt>abort-upgrade</tt>
2985 <var>old-version</var></p>
2989 <var>disappearer's-postrm</var> <tt>disappear</tt>
2990 <var>overwriter</var>
2991 <var>overwriter-version</var></p></item>
2996 <sect id="unpackphase"><heading>Details of unpack phase of
2997 installation or upgrade
3001 The procedure on installation/upgrade/overwrite/disappear
3002 (ie, when running <tt>dpkg --unpack</tt>, or the unpack
3004 --install</tt>) is as follows. In each case if an error occurs the
3005 actions in are general run backwards - this means that the maintainer
3006 scripts are run with different arguments in reverse order. These are
3007 the `error unwind' calls listed below.
3014 <p>If a version the package is already
3017 <var>old-prerm</var> upgrade <var>new-version</var>
3022 If this gives an error (ie, a non-zero exit
3023 status), dpkg will attempt instead:
3025 <var>new-prerm</var> failed-upgrade <var>old-version</var>
3027 Error unwind, for both the above cases:
3029 <var>old-postinst</var> abort-upgrade <var>new-version</var>
3037 <p>If a `conflicting' package is being removed at the same time:
3041 If any packages depended on that conflicting
3042 package and <tt>--auto-deconfigure</tt> is
3043 specified, call, for each such package:
3045 <var>deconfigured's-prerm</var> deconfigure \
3046 in-favour <var>package-being-installed</var> <var>version</var> \
3047 removing <var>conflicting-package</var> <var>version</var>
3051 <var>deconfigured's-postinst</var> abort-deconfigure \
3052 in-favour <var>package-being-installed-but-failed</var> <var>version</var> \
3053 removing <var>conflicting-package</var> <var>version</var>
3055 The deconfigured packages are marked as
3056 requiring configuration, so that if
3057 <tt>--install</tt> is used they will be
3058 configured again if possible.</p>
3061 <p>To prepare for removal of the conflicting package, call:
3063 <var>conflictor's-prerm</var> remove in-favour <var>package</var> <var>new-version</var>
3067 <var>conflictor's-postinst</var> abort-remove \
3068 in-favour <var>package</var> <var>new-version</var>
3079 <p>If the package is being upgraded, call:
3081 <var>new-preinst</var> upgrade <var>old-version</var>
3086 Otherwise, if the package had some configuration
3087 files from a previous version installed (ie, it
3088 is in the `configuration files only' state):
3090 <var>new-preinst</var> install <var>old-version</var>
3094 <p>Otherwise (ie, the package was completely purged):
3096 <var>new-preinst</var> install
3098 Error unwind versions, respectively:
3100 <var>new-postrm</var> abort-upgrade <var>old-version</var>
3101 <var>new-postrm</var> abort-install <var>old-version</var>
3102 <var>new-postrm</var> abort-install
3112 The new package's files are unpacked, overwriting any
3113 that may be on the system already, for example any
3114 from the old version of the same package or from
3115 another package (backups of the old files are left
3116 around, and if anything goes wrong dpkg will attempt
3117 to put them back as part of the error unwind).
3121 It is an error for a package to contains files which
3122 are on the system in another package, unless
3123 <tt>Replaces</tt> is used (see <ref id="replaces">).
3124 Currently the <tt>--force-overwrite</tt> flag is
3125 enabled, downgrading it to a warning, but this may not
3130 It is a more serious error for a package to contain a
3131 plain file or other kind of nondirectory where another
3132 package has a directory (again, unless
3133 <tt>Replaces</tt> is used). This error can be
3134 overridden if desired using
3135 <tt>--force-overwrite-dir</tt>, but this is not
3140 Packages which overwrite each other's files produce
3141 behaviour which though deterministic is hard for the
3142 system administrator to understand. It can easily
3143 lead to `missing' programs if, for example, a package
3144 is installed which overwrites a file from another
3145 package, and is then removed again.
3148 Part of the problem is due to what is arguably a
3149 bug in <prgn>dpkg</prgn>.
3155 A directory will never be replaced by a symbolic links
3156 to a directory or vice versa; instead, the existing
3157 state (symlink or not) will be left alone and
3158 <prgn>dpkg</prgn> will follow the symlink if there is
3166 <p>If the package is being upgraded, call
3168 <var>old-postrm</var> upgrade <var>new-version</var>
3172 <p>If this fails, <prgn>dpkg</prgn> will attempt:
3174 <var>new-postrm</var> failed-upgrade <var>old-version</var>
3176 Error unwind, for both cases:
3178 <var>old-preinst</var> abort-upgrade <var>new-version</var>
3183 This is the point of no return - if <prgn>dpkg</prgn>
3184 gets this far, it won't back off past this point if an
3185 error occurs. This will leave the package in a fairly
3186 bad state, which will require a successful
3187 reinstallation to clear up, but it's when
3188 <prgn>dpkg</prgn> starts doing things that are
3193 Any files which were in the old version of the package
3194 but not in the new are removed.</p>
3197 <p>The new file list replaces the old.</p>
3200 <p>The new maintainer scripts replace the old.</p>
3204 <p>Any packages all of whose files have been overwritten during the
3205 installation, and which aren't required for
3206 dependencies, are considered to have been removed.
3207 For each such package,
3210 <p><prgn>dpkg</prgn> calls:
3212 <var>disappearer's-postrm</var> disappear \
3213 <var>overwriter</var> <var>overwriter-version</var>
3218 <p>The package's maintainer scripts are removed.
3223 It is noted in the status database as being in a
3224 sane state, namely not installed (any conffiles
3225 it may have are ignored, rather than being
3226 removed by <prgn>dpkg</prgn>). Note that
3227 disappearing packages do not have their prerm
3228 called, because <prgn>dpkg</prgn> doesn't know
3229 in advance that the package is going to
3238 Any files in the package we're unpacking that are also
3239 listed in the file lists of other packages are removed
3240 from those lists. (This will lobotomise the file list
3241 of the `conflicting' package if there is one.)
3246 The backup files made during installation, above, are
3253 The new package's status is now sane, and recorded as
3254 `unpacked'. Here is another point of no return - if
3255 the conflicting package's removal fails we do not
3256 unwind the rest of the installation; the conflicting
3257 package is left in a half-removed limbo.
3262 If there was a conflicting package we go and do the
3263 removal actions (described below), starting with the
3264 removal of the conflicting package's files (any that
3265 are also in the package being installed have already
3266 been removed from the conflicting package's file list,
3267 and so do not get removed now).
3274 <sect><heading>Details of configuration
3278 When we configure a package (this happens with <tt>dpkg
3279 --install</tt>, or with <tt>--configure</tt>), we first
3280 update the conffiles and then call:
3282 <var>postinst</var> configure <var>most-recently-configured-version</var>
3287 No attempt is made to unwind after errors during
3292 If there is no most recently configured version
3293 <prgn>dpkg</prgn> will pass a null argument; older versions
3294 of dpkg may pass <tt><unknown></tt> (including the
3295 angle brackets) in this case. Even older ones do not pass a
3296 second argument at all, under any circumstances.
3300 <sect><heading>Details of removal and/or configuration purging
3308 <var>prerm</var> remove
3314 The package's files are removed (except conffiles).
3319 <var>postrm</var> remove
3323 <p>All the maintainer scripts except the postrm are removed.
3327 If we aren't purging the package we stop here. Note
3328 that packages which have no postrm and no conffiles
3329 are automatically purged when removed, as there is no
3330 difference except for the <prgn>dpkg</prgn>
3335 The conffiles and any backup files (<tt>~</tt>-files,
3336 <tt>#*#</tt> files, <tt>%</tt>-files,
3337 <tt>.dpkg-{old,new,tmp}</tt>, etc.) are removed.</p>
3341 <var>postrm</var> purge
3345 <p>The package's file list is removed.</p>
3348 No attempt is made to unwind after errors during
3353 <chapt id="descriptions"><heading>Descriptions of packages - the
3354 <tt>Description</tt> field
3358 The <tt>Description</tt> control file field is used by
3359 <prgn>dselect</prgn> when the user is selecting which packages
3360 to install and by <prgn>dpkg</prgn> when it displays
3361 information about the status of packages and so forth. It is
3362 included on the FTP site in the <prgn>Packages</prgn> files,
3363 and may also be used by the Debian WWW pages.
3367 The description is intended to describe the program to a user
3368 who has never met it before so that they know whether they
3369 want to install it. It should also give information about the
3370 significant dependencies and conflicts between this package
3371 and others, so that the user knows why these dependencies and
3372 conflicts have been declared.
3376 The field's format is as follows:
3378 Description: <var>single line synopsis</var>
3379 <var>extended description over several lines</var>
3384 The synopsis is often printed in lists of packages and so
3385 forth, and should be as informative as possible. Every
3386 package should also have an extended description.
3389 <sect><heading>Types of formatting line in the extended
3397 Those starting with a single space are part of a
3398 paragraph. Successive lines of this form will be
3399 word-wrapped when displayed. The leading space will
3400 usually be stripped off.
3406 Those starting with two or more spaces. These will be
3407 displayed verbatim. If the display cannot be panned
3408 horizontally the displaying program will linewrap them
3409 `hard' (ie, without taking account of word breaks).
3410 If it can they will be allowed to trail off to the
3411 right. None, one or two initial spaces may be
3412 deleted, but the number of spaces deleted from each
3413 line will be the same (so that you can have indenting
3414 work correctly, for example).
3419 <p>Those containing a single space followed by a single full stop
3420 character. These are rendered as blank lines. This
3421 is the <em>only</em> way to get a blank line - see
3427 Those containing a space, a full stop and some more
3428 characters. These are for future expansion. Do not
3435 <sect><heading>Notes about writing descriptions
3439 <em>Always</em> start extended description lines with at least one
3440 whitespace character. Fields in the control file and in the Packages
3441 file are separated by field names starting in the first column, just
3442 as message header fields are in RFC822. Forgetting the whitespace
3443 will cause <prgn>dpkg-deb</prgn>
3446 Version 0.93.23 or later.
3448 </footnote> to produce a syntax error when trying to build
3449 the package. If you force it to build anyway
3450 <prgn>dpkg</prgn> will refuse to install the resulting
3455 <em>Do not</em> include any completely <em>empty</em>
3456 lines. These separate different records in the Packages file
3457 and different packages in the <tt>debian/control</tt> file,
3458 and are forbidden in package control files. See the
3459 previous paragraph for what happens if you get this wrong.
3463 The single line synopsis should be kept brief - certainly
3464 under 80 characters. <prgn>dselect</prgn> displays between
3465 25 and 49 characters without panning if you're using an
3466 80-column terminal, depending on what display options are in
3471 Do not include the package name in the synopsis line. The
3472 display software knows how to display this already, and you
3473 do not need to state it. Remember that in many situations
3474 the user may only see the synopsis line - make it as
3475 informative as you can.
3479 The extended description should describe what the package
3480 does and how it relates to the rest of the system (in terms
3481 of, for example, which subsystem it is which part of).
3485 The blurb that comes with a program in its announcements
3486 and/or <prgn>README</prgn> files is rarely suitable for use
3487 in a description. It is usually aimed at people who are
3488 already in the community where the package is used. The
3489 description field needs to make sense to anyone, even people
3490 who have no idea about any of the things the package deals
3495 Put important information first, both in the synopis and
3496 extended description. Sometimes only the first part of the
3497 synopsis or of the description will be displayed. You can
3498 assume that there will usually be a way to see the whole
3499 extended description.
3503 You may include information about dependencies and so forth
3504 in the extended description, if you wish.
3508 Do not use tab characters. Their effect is not predictable.
3512 Do not try to linewrap the summary (the part on the same
3513 line as the field name <tt>Description</tt>) into the
3514 extended description. This will not work correctly when the
3515 full description is displayed, and makes no sense where only
3516 the summary is available.</p>
3519 <sect><heading>Example description in control file for Smail
3525 Version: 3.1.29.1-13
3526 Maintainer: Ian Jackson <iwj10@cus.cam.ac.uk>
3527 Recommends: pine | mailx | elm | emacs | mail-user-agent
3529 Depends: cron, libc5
3531 Provides: mail-transport-agent
3532 Description: Electronic mail transport system.
3533 Smail is the recommended mail transport agent (MTA) for Debian.
3535 An MTA is the innards of the mail system - it takes messages from
3536 user-friendly mailer programs and arranges for them to be delivered
3537 locally or passed on to other systems as required.
3539 In order to make use of it you must have one or more user level
3540 mailreader programs such as elm, pine, mailx or Emacs (which has Rmail
3541 and VM as mailreaders) installed. If you wish to send messages other
3542 than just to other users of your system you must also have appropriate
3543 networking support, in the form of IP or UUCP.
3549 <chapt id="relationships"><heading>Declaring relationships between
3554 Packages can declare in their control file that they have
3555 certain relationships to other packages - for example, that
3556 they may not be installed at the same time as certain other
3557 packages, and/or that they depend on the presence of others,
3558 or that they should overwrite files in certain other packages
3563 This is done using the <tt>Depends</tt>, <tt>Recommends</tt>,
3564 <tt>Suggests</tt>, <tt>Conflicts</tt>, <tt>Provides</tt> and
3565 <tt>Replaces</tt> control file fields.
3569 Source packages may declare relationships to binary packages,
3570 saying that they require certain binary packages being
3571 installed or absent at the time of building the package.
3575 This is done using the <tt>Build-Depends</tt>,
3576 <tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt>, and
3577 <tt>Build-Conflicts-Indep</tt> control file fields.
3580 <sect id="depsyntax"><heading>Syntax of relationship fields
3584 These fields all have a uniform syntax. They are a list of
3585 package names separated by commas.
3589 In <tt>Depends</tt>, <tt>Recommends</tt>, <tt>Suggests</tt>,
3590 <tt>Pre-Depends</tt>, <tt>Build-Depends</tt> and
3591 <tt>Build-Depends-Indep</tt>(the fields which declare
3592 dependencies of the package in which they occur on other
3593 packages) these package names may also be lists of
3594 alternative package names, separated by vertical bar symbols
3595 <tt>|</tt> (pipe symbols).
3599 All the fields except <tt>Provides</tt> may restrict their
3600 applicability to particular versions of each named package.
3601 This is done in parentheses after each individual package
3602 name; the parentheses should contain a relation from the
3603 list below followed by a version number, in the format
3604 described in <ref id="versions">.
3608 The relations allowed are <tt><<</tt>, <tt><=</tt>,
3609 <tt>=</tt>, <tt>>=</tt> and <tt>>></tt> for
3610 strictly earlier, earlier or equal, exactly equal, later or
3611 equal and strictly later, respectively. The forms
3612 <tt><</tt> and <tt>></tt> were used to mean
3613 earlier/later or equal, rather than strictly earlier/later,
3614 so they should not appear in new packages (though
3615 <prgn>dpkg</prgn> still supports them).
3619 Whitespace may appear at any point in the version
3620 specification, and must appear where it's necessary to
3621 disambiguate; it is not otherwise significant. For
3622 consistency and in case of future changes to
3623 <prgn>dpkg</prgn> it is recommended that a single space be
3624 used after a version relationship and before a version
3625 number; it is usual also to put a single space after each
3626 comma, on either side of each vertical bar, and before each
3635 Depends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh
3640 All fields that specify build-time relationships
3641 (<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
3642 <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>)
3643 may be restricted to a certain set of architectures. This
3644 is done in brackets after each individual package name and
3645 the optional version specification. The brackets enclose a
3646 list of Debian architecture names separated by whitespace.
3647 An exclamation mark may be prepended to each name. If the
3648 current Debian host architecture is not in this list and
3649 there are no exclamation marks in the list, or it is in the
3650 list with a prepended exclamation mark, the package name and
3651 the associated version specification are ignored completely
3652 for the purposes of defining the relationships.
3659 Build-Depends-Indep: texinfo
3660 Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
3661 hurd-dev [hurd-i386], gnumach-dev [hurd-i386]
3667 <heading>Binary Dependencies - <tt>Depends</tt>,
3668 <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Pre-Depends</tt>
3672 These four fields are used to declare a dependency by one
3673 package on another. They appear in the depending package's
3678 All but <tt>Pre-Depends</tt> (discussed below) take effect
3679 <em>only</em> when a package is to be configured. They do
3680 not prevent a package being on the system in an unconfigured
3681 state while its dependencies are unsatisfied, and it is
3682 possible to replace a package whose dependencies are
3683 satisfied and which is properly installed with a different
3684 version whose dependencies are not and cannot be satisfied;
3685 when this is done the depending package will be left
3686 unconfigured (since attempts to configure it will give
3687 errors) and will not function properly.
3691 For this reason packages in an installation run are usually
3692 all unpacked first and all configured later; this gives
3693 later versions of packages with dependencies on later
3694 versions of other packages the opportunity to have their
3695 dependencies satisfied.
3699 Thus <tt>Depends</tt> allows package maintainers to impose
3700 an order in which packages should be configured.
3702 <tag><tt>Depends</tt></tag>
3705 <p>This declares an absolute dependency.
3709 <prgn>dpkg</prgn> will not configure packages whose
3710 dependencies aren't satisfied. If it is asked to make
3711 an installation which would cause an installed
3712 package's dependencies to become unsatisfied it will
3716 Current versions (1.2.4) of <prgn>dpkg</prgn> have
3717 a bug in this area which will cause some of these
3718 problems to be ignored.
3720 </footnote>, unless <tt>--auto-deconfigure</tt> is
3721 specified, in which case those packages will be
3722 deconfigured before the installation proceeds.
3726 <prgn>dselect</prgn> makes it hard for the user to
3727 select packages for installation, removal or upgrade
3728 in a way that would mean that packages'
3729 <prgn>Depends</prgn> fields would be unsatisfied. The
3730 user can override this if they wish, for example if
3731 they know that <prgn>dselect</prgn> has an out-of-date
3732 view of the real package relationships.
3736 The <tt>Depends</tt> field should be used if the
3737 depended-on package is required for the depending
3738 package to provide a significant amount of
3742 <tag><tt>Recommends</tt></tag>
3744 <p>This declares a strong, but not absolute, dependency.
3748 <tt>Recommends</tt> is ignored by <prgn>dpkg</prgn>,
3749 so that users using the command-line (who are presumed
3750 to know what they're doing) will not be impeded.
3754 It is treated by <prgn>dselect</prgn> exactly as
3755 <tt>Depends</tt> is; this makes it hard for the user
3756 to select things so as to leave <tt>Recommends</tt>
3757 fields unsatisfied, but they are able to do so by
3762 The <tt>Recommends</tt> field should list packages
3763 that would be found together with this one in all but
3764 unusual installations.</p>
3767 <tag><tt>Suggests</tt></tag>
3771 This is used to declare that one package may be more
3772 useful with one or more others. Using this field
3773 tells the packaging system and the user that the
3774 listed packages are related to this one and can
3775 perhaps enhance its usefulness, but that installing
3776 this one without them is perfectly reasonable.
3780 <prgn>dselect</prgn> will offer suggsted packages to
3781 the system administrator when they select the
3782 suggesting package, but the default is not to install
3783 the suggested package.</p>
3786 <tag><tt>Pre-Depends</tt></tag>
3789 <p>This field is like <tt>Depends</tt>, except that it also forces
3790 <prgn>dpkg</prgn> to complete installation of the
3791 packages named before even starting the installation
3792 of the package which declares the predependency.
3796 <prgn>dselect</prgn> checks for predependencies when
3797 it is doing an installation run, and will attempt to
3798 find the packages which are required to be installed
3799 first and do so in the right order.
3803 However, this process is slow (because it requires
3804 repeated invocations of <prgn>dpkg</prgn>) and
3805 troublesome (because it requires guessing where to
3806 find the appropriate files).
3810 For these reasons, and because this field imposes
3811 restrictions on the order in which packages may be
3812 unpacked (which can be difficult for installations
3813 from multipart media, for example),
3814 <tt>Pre-Depends</tt> should be used sparingly,
3815 preferably only by packages whose premature upgrade or
3816 installation would hamper the ability of the system to
3817 continue with any upgrade that might be in progress.
3821 When the package declaring it is being configured, a
3822 <tt>Pre-Dependency</tt> will be considered satisfied
3823 only if the depending package has been correctly
3824 configured, just as if an ordinary <tt>Depends</tt>
3829 However, when a package declaring a predependency is
3830 being unpacked the predependency can be satisfied even
3831 if the depended-on package(s) are only unpacked or
3832 half-configured, provided that they have been
3833 configured correctly at some point in the past (and
3834 not removed or partially removed since). In this case
3835 both the previously-configured and currently unpacked
3836 or half-configured versions must satisfy any version
3837 clause in the <tt>Pre-Depends</tt> field.
3843 When selecting which level of dependency to use you should
3844 consider how important the depended-on package is to the
3845 functionality of the one declaring the dependency. Some
3846 packages are composed of components of varying degrees of
3847 importance. Such a package should list using
3848 <tt>Depends</tt> the package(s) which are required by the
3849 more important components. The other components'
3850 requirements may be mentioned as Suggestions or
3851 Recommendations, as appropriate to the components' relative
3855 <sect1><heading>Dependencies on shared libraries
3859 The dependency fields listed above are used by packages
3860 which need shared libraries to declare dependencies on the
3861 appropriate packages.
3865 These dependencies are usually determined automatically
3866 using <prgn>dpkg-shlibdeps</prgn> and inserted in the
3867 package control file using the control file substitution
3868 variables mechanism; see <ref id="srcsubstvars"> and
3869 <ref id="sourcetools">.
3873 <sect1><heading>Deconfiguration due to removal during bulk
3878 If <prgn>dpkg</prgn> would like to remove a package due to a
3879 conflict, as described above, but this would violate a
3880 dependency of some other package on the system,
3881 <prgn>dpkg</prgn> will usually not remove the conflicting
3882 package and halt with an error.
3886 However, if the <tt>--auto-deconfigure</tt> (<tt>-B</tt>)
3887 option is used <prgn>dpkg</prgn> will automatically
3888 `deconfigure' the package with the problematic dependency,
3889 so that the conflicting package can be removed and the
3890 package we're trying to install can be installed. If
3891 <prgn>dpkg</prgn> is being asked to install packages (rather
3892 than just unpacking them) it will try to reconfigure the
3893 package when it has unpacked all its arguments, in the hope
3894 that one of the other packages it is installing will satisfy
3895 the problematic dependency.
3899 <prgn>dselect</prgn> supplies this argument to
3900 <prgn>dpkg</prgn> when it invokes it, so that bulk
3901 installations proceed smoothly.
3905 <sect id="conflicts"><heading>Alternative binary packages -
3906 <tt>Conflicts</tt> and <tt>Replaces</tt>
3910 When one binary package declares a conflict with another
3911 <prgn>dpkg</prgn> will refuse to allow them to be installed
3912 on the system at the same time.
3916 If one package is to be installed, the other must be removed first -
3917 if the package being installed is marked as replacing (<ref
3918 id="replaces">) the one on the system, or the one on the system is
3919 marked as deselected, or both packages are marked
3920 <tt>Essential</tt>, then <prgn>dpkg</prgn> will
3921 automatically remove the package which is causing the
3922 conflict, otherwise it will halt the installation of the new
3923 package with an error.
3927 <prgn>dselect</prgn> makes it hard to select conflicting
3928 packages, though the user can override this if they wish.
3929 If they do not override it then <prgn>dselect</prgn> will
3930 select one of the packages for removal, and the user must
3931 make sure it is the right one. In the future
3932 <prgn>dselect</prgn> will look for the presence of a
3933 <tt>Replaces</tt> field to help decide which package should
3934 be installed and which removed.
3938 A package will not cause a conflict merely because its
3939 configuration files are still installed; it must be at least
3944 A special exception is made for packages which declare a
3945 conflict with their own package name, or with a virtual
3946 package which they provide (see below): this does not
3947 prevent their installation, and allows a package to conflict
3948 with others providing a replacement for it. You use this
3949 feature when you want the package in question to be the only
3950 package providing something.
3954 A <tt>Conflicts</tt> entry should almost never have an
3955 `earlier than' version clause. This would prevent
3956 <prgn>dpkg</prgn> from upgrading or installing the package
3957 which declared such a conflict until the upgrade or removal
3958 of the conflicted-with package had been completed. This
3959 aspect of installation ordering is not handled by
3960 <prgn>dselect</prgn>, so that the use <tt>Conflicts</tt> in
3961 this way is likely to cause problems for `bulk run' upgrades
3966 <sect id="virtual"><heading>Virtual packages - <tt>Provides</tt>
3970 As well as the names of actual (`concrete') packages, the
3971 package relationship fields <tt>Depends</tt>,
3972 <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
3973 <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Conflicts</tt>,
3974 <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt> may
3975 mention virtual packages.
3979 A virtual package is one which appears in the
3980 <tt>Provides</tt> control file field of another package.
3981 The effect is as if the package(s) which provide a
3982 particular virtual package name had been listed by name
3983 everywhere the virtual package name appears.
3987 If there are both a real and a virtual package of the same
3988 name then the dependency may be satisfied (or the conflict
3989 caused) by either the real package or any of the virtual
3990 packages which provide it. This is so that, for example,
3996 and someone else releases an xemacs package they can say
4000 </example> and all will work in the interim (until a purely
4001 virtual package name is decided on and the <tt>emacs</tt>
4002 and <tt>vm</tt> packages are changed to use it).
4006 If a dependency or a conflict has a version number attached
4007 then only real packages will be considered to see whether
4008 the relationship is satisfied (or the prohibition violated,
4009 for a conflict) - it is assumed that a real package which
4010 provides virtual package is not of the `right' version. So,
4011 a <tt>Provides</tt> field may not contain version numbers,
4012 and the version number of the concrete package which
4013 provides a particular virtual package will not be looked at
4014 when considering a dependency on or conflict with the
4015 virtual package name.
4019 It is likely that the ability will be added in a future
4020 release of <prgn>dpkg</prgn> to specify a version number for
4021 each virtual package it provides. This feature is not yet
4022 present, however, and is expected to be used only
4027 If you want to specify which of a set of real packages should be the
4028 default to satisfy a particular dependency on a virtual package, you
4029 should list the real package as an alternative before the virtual.
4034 <sect id="replaces"><heading><tt>Replaces</tt> - overwriting
4035 files and replacing packages
4039 The <tt>Replaces</tt> control file field has two purposes,
4040 which come into play in different situations.
4044 Virtual packages (<ref id="virtual">) are not considered
4045 when looking at a <tt>Replaces</tt> field - the packages
4046 declared as being replaced must be mentioned by their real
4050 <sect1><heading>Overwriting files in other packages
4054 Firstly, as mentioned before, it is usually an error for a
4055 package to contains files which are on the system in
4056 another package, though currently the
4057 <tt>--force-overwrite</tt> flag is enabled by default,
4058 downgrading the error to a warning,
4062 If the overwriting package declares that it replaces the
4063 one containing the file being overwritten then
4064 <prgn>dpkg</prgn> will proceed, and replace the file from
4065 the old package with that from the new. The file will no
4066 longer be listed as `owned' by the old package.
4070 If a package is completely replaced in this way, so that
4071 <prgn>dpkg</prgn> does not know of any files it still
4072 contains, it is considered to have disappeared. It will
4073 be marked as not wanted on the system (selected for
4074 removal) and not installed. Any conffiles details noted
4075 in the package will be ignored, as they will have been
4076 taken over by the replacing package(s). The package's
4077 <prgn>postrm</prgn> script will be run to allow the
4078 package to do any final cleanup required. See <ref
4079 id="mscriptsinstact">.
4083 In the future <prgn>dpkg</prgn> will discard files which
4084 overwrite those from another package which declares that
4085 it replaces the one being installed (so that you can
4086 install an older version of a package without problems).
4090 This usage of <tt>Replaces</tt> only takes effect when
4091 both packages are at least partially on the system at
4092 once, so that it can only happen if they do not conflict
4093 or if the conflict has been overridden.</p>
4096 <sect1><heading>Replacing whole packages, forcing their
4101 Secondly, <tt>Replaces</tt> allows <prgn>dpkg</prgn> and
4102 <prgn>dselect</prgn> to resolve which package should be
4103 removed when there is a conflict - see <ref id="conflicts">. This
4104 usage only takes effect when the two packages <em>do</em>
4105 conflict, so that the two effects do not interfere with
4111 <sect><heading>Defaults for satisfying dependencies - ordering
4115 Ordering is significant in dependency fields.
4119 Usually dselect will suggest to the user that they select
4120 the package with the most `fundamental' class (eg, it will
4121 prefer Base packages to Optional ones), or the one that they
4122 `most wanted' to select in some sense.
4126 In the absence of other information <prgn>dselect</prgn>
4127 will offer a default selection of the first named package in
4128 a list of alternatives.
4132 However, there is no way to specify the `order' of several
4133 packages which all provide the same thing, when that thing
4134 is listed as a dependency.
4138 Therefore a dependency on a virtual package should contain a
4139 concrete package name as the first alternative, so that this
4144 For example, consider the set of packages:
4147 Recommends: info-browser
4150 Provides: info-browser
4153 Provides: info-browser
4158 If <prgn>emacs</prgn> and <prgn>info</prgn> both have the
4159 same priority then <prgn>dselect</prgn>'s choice is
4160 essentially random. Better would be
4163 Recommends: info | info-browser
4165 so that <prgn>dselect</prgn> defaults to selecting the
4166 lightweight standalone info browser.
4171 <sect><heading>Relationships between source and binary packages -
4172 <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
4173 <tt>Build-Conflicts</tt>, <tt>Build-Conflicts-Indep</tt>
4177 A source package may declare a dependency or a conflict on a
4178 binary package. This is done with the control file fields
4179 <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
4180 <tt>Build-Conflicts</tt>, and <tt>Build-Conflicts-Indep</tt>. Their
4181 semantics is that the dependencies and conflicts they define
4182 must be satisfied (as defined earlier for binary packages),
4183 when one of the targets in <tt>debian/rules</tt> that the
4184 particular field applies to is invoked.
4187 <tag><tt>Build-Depends</tt>, <tt>Build-Conflicts</tt></tag>
4190 The <tt>Build-Depends</tt> and
4191 <tt>Build-Conflicts</tt> fields apply to the targets
4192 <tt>build</tt>, <tt>binary</tt>, <tt>binary-arch</tt>
4193 and <tt>binary-indep</tt>.
4196 <tag><tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts-Indep</tt></tag>
4199 The <tt>Build-Depends-Indep</tt> and
4200 <tt>Build-Conflicts-Indep</tt> fields apply to the
4201 targets <tt>binary</tt> and <tt>binary-indep</tt>.
4212 <chapt id="conffiles"><heading>Configuration file handling
4216 <prgn>dpkg</prgn> can do a certain amount of automatic
4217 handling of package configuration files.
4221 Whether this mechanism is appropriate depends on a number of
4222 factors, but basically there are two approaches to any
4223 particular configuration file.
4227 The easy method is to ship a best-effort configuration in the
4228 package, and use <prgn>dpkg</prgn>'s conffile mechanism to
4229 handle updates. If the user is unlikely to want to edit the
4230 file, but you need them to be able to without losing their
4231 changes, and a new package with a changed version of the file
4232 is only released infrequently, this is a good approach.
4236 The hard method is to build the configuration file from
4237 scratch in the <prgn>postinst</prgn> script, and to take the
4238 responsibility for fixing any mistakes made in earlier
4239 versions of the package automatically. This will be
4240 appropriate if the file is likely to need to be different on
4244 <sect><heading>Automatic handling of configuration files by
4249 A package may contain a control area file called
4250 <tt>conffiles</tt>. This file should be a list of filenames
4251 of configuration files needing automatic handling, separated
4252 by newlines. The filenames should be absolute pathnames,
4253 and the files referred to should actually exist in the
4258 When a package is upgraded <prgn>dpkg</prgn> will process
4259 the configuration files during the configuration stage,
4260 shortly before it runs the package's <prgn>postinst</prgn>
4265 For each file it checks to see whether the version of the
4266 file included in the package is the same as the one that was
4267 included in the last version of the package (the one that is
4268 being upgraded from); it also compares the version currently
4269 installed on the system with the one shipped with the last
4274 If neither the user nor the package maintainer has changed
4275 the file, it is left alone. If one or the other has changed
4276 their version, then the changed version is preferred - i.e.,
4277 if the user edits their file, but the package maintainer
4278 doesn't ship a different version, the user's changes will
4279 stay, silently, but if the maintainer ships a new version
4280 and the user hasn't edited it the new version will be
4281 installed (with an informative message). If both have
4282 changed their version the user is prompted about the problem
4283 and must resolve the differences themselves.
4287 The comparisons are done by calculating the MD5 message
4288 digests of the files, and storing the MD5 of the file as it
4289 was included in the most recent version of the package.
4293 When a package is installed for the first time
4294 <prgn>dpkg</prgn> will install the file that comes with it,
4295 unless that would mean overwriting a file already on the
4300 However, note that <prgn>dpkg</prgn> will <em>not</em>
4301 replace a conffile that was removed by the user (or by a
4302 script). This is necessary because with some programs a
4303 missing file produces an effect hard or impossible to
4304 achieve in another way, so that a missing file needs to be
4305 kept that way if the user did it.
4309 Note that a package should <em>not</em> modify a
4310 <prgn>dpkg</prgn>-handled conffile in its maintainer
4311 scripts. Doing this will lead to <prgn>dpkg</prgn> giving
4312 the user confusing and possibly dangerous options for
4313 conffile update when the package is upgraded.</p>
4316 <sect><heading>Fully-featured maintainer script configuration
4321 For files which contain site-specific information such as
4322 the hostname and networking details and so forth, it is
4323 better to create the file in the package's
4324 <prgn>postinst</prgn> script.
4328 This will typically involve examining the state of the rest
4329 of the system to determine values and other information, and
4330 may involve prompting the user for some information which
4331 can't be obtained some other way.
4335 When using this method there are a couple of important
4336 issues which should be considered:
4340 If you discover a bug in the program which generates the
4341 configuration file, or if the format of the file changes
4342 from one version to the next, you will have to arrange for
4343 the postinst script to do something sensible - usually this
4344 will mean editing the installed configuration file to remove
4345 the problem or change the syntax. You will have to do this
4346 very carefully, since the user may have changed the file,
4347 perhaps to fix the very problem that your script is trying
4348 to deal with - you will have to detect these situations and
4349 deal with them correctly.
4353 If you do go down this route it's probably a good idea to
4354 make the program that generates the configuration file(s) a
4355 separate program in <tt>/usr/sbin</tt>, by convention called
4356 <tt><var>package</var>config</tt> and then run that if
4357 appropriate from the post-installation script. The
4358 <tt><var>package</var>config</tt> program should not
4359 unquestioningly overwrite an existing configuration - if its
4360 mode of operation is geared towards setting up a package for
4361 the first time (rather than any arbitrary reconfiguration
4362 later) you should have it check whether the configuration
4363 already exists, and require a <tt>--force</tt> flag to
4364 overwrite it.</p></sect>
4369 <chapt id="alternatives"><heading>Alternative versions of an interface -
4370 <prgn>update-alternatives</prgn>
4374 When several packages all provide different versions of the
4375 same program or file it is useful to have the system select a
4376 default, but to allow the system administrator to change it
4377 and have their decisions respected.
4381 For example, there are several versions of the <prgn>vi</prgn>
4382 editor, and there is no reason to prevent all of them from
4383 being installed at once, each under their own name
4384 (<prgn>nvi</prgn>, <prgn>vim</prgn> or whatever).
4385 Nevertheless it is desirable to have the name <tt>vi</tt>
4386 refer to something, at least by default.
4390 If all the packages involved cooperate, this can be done with
4391 <prgn>update-alternatives</prgn>.
4395 Each package provides its own version under its own name, and
4396 calls <prgn>update-alternatives</prgn> in its postinst to
4397 register its version (and again in its prerm to deregister
4402 See the manpage <manref name="update-alternatives"
4403 section="8"> for details.
4407 If <prgn>update-alternatives</prgn> does not seem appropriate
4408 you may wish to consider using diversions instead.</p>
4412 <chapt id="diversions"><heading>Diversions - overriding a
4413 package's version of a file
4417 It is possible to have <prgn>dpkg</prgn> not overwrite a file
4418 when it reinstalls the package it belongs to, and to have it
4419 put the file from the package somewhere else instead.
4423 This can be used locally to override a package's version of a
4424 file, or by one package to override another's version (or
4425 provide a wrapper for it).
4429 Before deciding to use a diversion, read <ref
4430 id="alternatives"> to see if you really want a diversion
4431 rather than several alternative versions of a program.
4435 There is a diversion list, which is read by <prgn>dpkg</prgn>,
4436 and updated by a special program <prgn>dpkg-divert</prgn>.
4437 Please see <manref name="dpkg-divert" section="8"> for full
4438 details of its operation.
4442 When a package wishes to divert a file from another, it should
4443 call <prgn>dpkg-divert</prgn> in its preinst to add the
4444 diversion and rename the existing file. For example,
4445 supposing that a <prgn>smailwrapper</prgn> package wishes to
4446 install a wrapper around <tt>/usr/sbin/smail</tt>:
4448 if [ install = "$1" ]; then
4449 dpkg-divert --package smailwrapper --add --rename \
4450 --divert /usr/sbin/smail.real /usr/sbin/smail
4452 </example> Testing <tt>$1</tt> is necessary so that the script
4453 doesn't try to add the diversion again when
4454 <prgn>smailwrapper</prgn> is upgraded. The <tt>--package
4455 smailwrapper</tt> ensures that <prgn>smailwrapper</prgn>'s
4456 copy of <tt>/usr/sbin/smail</tt> can bypass the diversion and
4457 get installed as the true version.
4461 The postrm has to do the reverse:
4463 if [ remove = "$1" ]; then
4464 dpkg-divert --package smailwrapper --remove --rename \
4465 --divert /usr/sbin/smail.real /usr/sbin/smail
4471 Do not attempt to divert a file which is vitally important for
4472 the system's operation - when using <prgn>dpkg-divert</prgn>
4473 there is a time, after it has been diverted but before
4474 <prgn>dpkg</prgn> has installed the new version, when the file
4479 <chapt id="sharedlibs"><heading>Shared libraries
4483 Packages containing shared libraries must be constructed with
4484 a little care to make sure that the shared library is always
4485 available. This is especially important for packages whose
4486 shared libraries are vitally important, such as the libc.
4490 Firstly, your package should install the shared libraries
4491 under their normal names. For example, the
4492 <prgn>libgdbm1</prgn> package should install
4493 <tt>libgdbm.so.1.7.3</tt> as
4494 <tt>/usr/lib/libgdbm.so.1.7.3</tt>. The files should not be
4495 renamed or relinked by any prerm or postrm scripts;
4496 <prgn>dpkg</prgn> will take care of renaming things safely
4497 without affecting running programs, and attempts to interfere
4498 with this are likely to lead to problems.
4502 Secondly, your package should include the symlink that
4503 <prgn>ldconfig</prgn> would create for the shared libraries.
4504 For example, the <prgn>libgdbm1</prgn> package should include
4505 a symlink from <tt>/usr/lib/libgdbm.so.1</tt> to
4506 <tt>libgdbm.so.1.7.3</tt>. This is needed so that
4507 <prgn>ld.so</prgn> can find the library in between the time
4508 <prgn>dpkg</prgn> installs it and <prgn>ldconfig</prgn> is run
4509 in the <prgn>postinst</prgn> script. Futhermore, and <em>this
4510 is very important</em>, the library must be placed before the
4511 symlink pointing to it in the <tt>.deb</tt> file. This is so
4512 that by the time <prgn>dpkg</prgn> comes to install the
4513 symlink (overwriting the previous symlink pointing at an older
4514 version of the library) the new shared library is already in
4515 place. Currently the way to ensure the ordering is done
4516 properly is to install the library in the appropriate
4517 <tt>debian/tmp/.../lib</tt> directory before creating the
4518 symlink, by putting the commands in the <tt>debian/rules</tt>
4519 in the appropriate order. Whether this has been done
4520 correctly can be checked by performing an <tt>ls -f</tt>.
4524 next Paragraph added to close Bug #5299, Guy Maor
4528 Thirdly, the development package should contain a symlink for
4529 the shared library without a version number. For example, the
4530 <tt>libgdbm1-dev</tt> package should include a symlink from
4531 <tt>/usr/lib/libgdm.so</tt> to <tt>libgdm.so.1.7.3</tt>. This
4532 symlink is needed by <prgn>ld</prgn> when compiling packages
4533 as it will only look for <tt>libgdm.so</tt> and
4534 <tt>libgdm.a</tt> when compiling dynamically or statically,
4539 next paragraph changed by Christian Schwarz (see policy weekly #6)
4543 Any package installing shared libraries in a directory that's listed
4544 in <tt>/etc/ld.so.conf</tt> or in one of the default library
4545 directories of <prgn>ld.so</prgn> (currently, these are <tt>/usr/lib</tt>
4546 and <tt>/lib</tt>) must call <prgn>ldconfig</prgn> in its <prgn>postinst</prgn>
4547 script if and only if the first argument is `configure'. However, it
4548 is important not to call <prgn>ldconfig</prgn> in the postrm or preinst
4549 scripts in the case where the package is being upgraded (see <ref
4550 id="unpackphase">), as <prgn>ldconfig</prgn> will see the temporary names
4551 that <prgn>dpkg</prgn> uses for the files while it is
4552 installing them and will make the shared library links point
4553 to them, just before <prgn>dpkg</prgn> continues the
4554 installation and removes the links!
4558 moved from section 2.2 , DMorris
4561 <sect id="shlibs"><heading>The <tt>shlibs</tt> File Format
4565 This file is for use by <prgn>dpkg-shlibdeps</prgn> and is
4566 required when your package provides shared libraries.
4570 Each line is of the form:
4572 <var>library-name</var> <var>version-or-soname</var> <var>dependencies ...</var>
4577 <var>library-name</var> is the name of the shared library,
4578 for example <tt>libc5</tt>.
4582 <var>version-or-soname</var> is the soname of the library -
4583 ie, the thing that must exactly match for the library to be
4584 recognised by <prgn>ld.so</prgn>. Usually this is major
4585 version number of the library.
4589 <var>dependencies</var> has the same syntax as a dependency
4590 field in a binary package control file. It should give
4591 details of which package(s) are required to satisfy a binary
4592 built against the version of the library contained in the
4593 package. See <ref id="depsyntax">.
4597 For example, if the package <tt>foo</tt> contains
4598 <tt>libfoo.so.1.2.3</tt>, where the soname of the library is
4599 <tt>libfoo.so.1</tt>, and the first version of the package
4600 which contained a minor number of at least <tt>2.3</tt> was
4601 <var>1.2.3-1</var>, then the package's <var>shlibs</var>
4604 libfoo 1 foo (>= 1.2.3-1)
4609 The version-specific dependency is to avoid warnings from
4610 <prgn>ld.so</prgn> about using older shared libraries with
4614 <sect><heading>Further Technical information on
4615 <tt>shlibs</tt></heading>
4619 following section mostly provided by Heiko Schlittermann
4623 <sect1><heading><em>What</em> are the <tt>shlibs</tt> files?
4627 The <tt>debian/shlibs</tt> file provides a way of checking
4628 for shared library dependencies on packaged binaries.
4629 They are intended to be used by package maintainers to
4630 make their lives easier.
4634 Other <tt>shlibs</tt> files that exist on a Debian system are
4636 <item> <p><tt>/etc/dpkg/shlibs.default</tt></p></item>
4637 <item> <p><tt>/etc/dpkg/shlibs.override</tt></p></item>
4638 <item> <p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
4639 <item> <p><tt>debian/shlibs.local</tt></p></item>
4641 These files are used by <prgn>dpkg-shlibdeps</prgn> when
4642 creating a binary package.</p>
4645 <sect1><heading><em>How</em> does <prgn>dpkg-shlibdeps</prgn>
4650 <prgn>dpkg-shlibdeps</prgn> calls <prgn>ldd</prgn> to
4651 determine the shared libraries used by the compiled
4652 binaries passed through its command line.
4656 For each shared library, <prgn>dpkg-shlibdeps</prgn> needs to know
4657 <list compact="compact">
4658 <item><p>the package containing the library, and</p></item>
4659 <item><p>the library version number,</p></item>
4662 it scans the following files in this order.
4663 <enumlist compact="compact">
4664 <item><p><tt>debian/shlibs.local</tt></p></item>
4665 <item><p><tt>/etc/dpkg/shlibs.override</tt></p></item>
4666 <item><p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
4667 <item><p><tt>/etc/dpkg/shlibs.default</tt></p></item>
4671 <sect1><heading><em>Who</em> maintains the various
4672 <tt>shlibs</tt> files?
4676 <list compact="compact">
4678 <p><tt>/etc/dpkg/shlibs.default</tt> - the maintainer
4683 <tt>/var/lib/dpkg/info/<var>package</var>.shlibs</tt>
4684 - the maintainer of each package</p>
4688 <tt>/etc/dpkg/shlibs.override</tt> - the local
4689 system administrator</p>
4692 <p><tt>debian/shlibs.local</tt> - the maintainer of
4697 The <tt>shlibs.default</tt> file is managed by
4698 <prgn>dpkg</prgn>. The entries in <tt>shlibs.default</tt>
4699 that are provided by <prgn>dpkg</prgn> are just there to
4700 fix things until the shared library packages all have
4701 <tt>shlibs</tt> files.
4705 <sect1><heading><em>How</em> to use <prgn>dpkg-shlibdeps</prgn> and
4706 the <tt>shlibs</tt> files?
4709 <sect2><heading>If your package doesn't provide a shared
4714 Put a call to <prgn>dpkg-shlibdeps</prgn> into your
4715 <tt>debian/rules</tt> file. If your package contains
4716 only binaries (e.g. no scripts) use:
4718 dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/*
4720 If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
4721 done. If it does complain you might need to create your
4722 own <tt>debian/shlibs.local</tt> file.</p>
4725 <sect2><heading>If your package provides a shared library
4729 Create a <tt>debian/shlibs</tt> file and let
4730 <tt>debian/rules</tt> install it in the control area:
4732 install -m644 debian/shlibs debian/tmp/DEBIAN
4734 If your package contains additional binaries see above.
4739 <sect1><heading><em>How</em> to write
4740 <tt>debian/shlibs.local</tt>
4744 This file is intended only as a <em>temporary</em> fix if
4745 your binaries depend on a library which doesn't provide
4746 its own <tt>/var/lib/dpkg/info/*.shlibs</tt> file yet.
4750 Let's assume you are packaging a binary <tt>foo</tt>. Your
4751 output in building the package might look like this.
4754 libbar.so.1 => /usr/X11R6/lib/libbar.so.1.0
4755 libc.so.5 => /lib/libc.so.5.2.18
4756 libX11.so.6 => /usr/X11R6/lib/libX11.so.6.0
4758 And when you ran <prgn>dpkg-shlibdeps</prgn>
4760 $ dpkg-shlibdeps -o foo
4761 dpkg-shlibdeps: warning: unable to find dependency information
4762 for shared library libbar
4763 (soname 1, path /usr/X11R6/lib/libbar.so.1.0, dependency field Depends)
4764 shlibs:Depends=elf-x11r6lib, libc5 (>= 5.2.18)
4766 The <prgn>foo</prgn> binary depends on the
4767 <prgn>libbar</prgn> shared library, but no package seems
4768 to provide a <tt>*.shlibs</tt> file in
4769 <tt></tt>var/lib/dpkg/info/. Let's determine the package
4775 $ dpkg -S /usr/X11R6/lib/libbar.so.1.0
4776 bar1: /usr/X11R6/lib/libbar.so.1.0
4777 $ dpkg -s bar1 | grep Version
4780 This tells us that the <prgn>bar1</prgn> package, version
4781 1.0-1 is the one we are using. Now we can create our own
4782 <tt>debian/shlibs.local</tt> to temporarly fix the above
4783 problem. Include the following line into your
4784 <tt>debian/shlibs.local</tt> file.
4786 libbar 1 bar1 (>= 1.0-1)
4788 Now your package build should work. As soon as the
4789 maintainer of <prgn>libbar1</prgn> provides a
4790 <tt>shlibs</tt> file, you can remove your
4791 <tt>debian/shlibs.local</tt> file.
4797 <chapt id="methif"><heading><prgn>dselect</prgn>'s interface to
4798 its installation methods
4802 <prgn>dselect</prgn> calls scripts from its installation
4803 methods when it needs to actually access data from the
4804 distribution. The core program <prgn>dselect</prgn> itself
4805 just calls these scripts and provides the package and access
4806 method selection interfaces. The installation methods are
4807 responsible for invoking <prgn>dpkg</prgn> as appropriate.
4811 Each installation method has three scripts:
4812 <list compact="compact">
4813 <item><p>Setup installation parameters.</p></item>
4814 <item><p>Update list of available packages.</p></item>
4815 <item><p>Install.</p></item>
4819 <prgn>dselect</prgn> searches for methods in
4820 <tt>/usr/lib/dpkg/methods</tt> and
4821 <tt>/usr/local/lib/dpkg/methods</tt>.
4824 <sect><heading>Functions of the method scripts
4828 The setup script is run just after the user has chosen an
4829 installation method. It should prompt the user for
4830 parameters like the site to NFS-mount or FTP from, the
4831 directory to use, or the directory or filesystem where the
4832 <tt>.deb</tt> files can be found, or the tape or floppy
4833 device to install from. It should store the responses under
4834 <tt>/var/lib/dpkg/methods</tt> - see below. If no available
4835 packages list is available it should perhaps offer to scan
4836 the available packages.
4840 The update script should obtain a list of available packages
4841 if possible, and run <tt>dpkg --update-avail</tt>, <tt>dpkg
4842 --merge-avail</tt> and/or <tt>dpkg --forget-old-unavail</tt>
4843 to load it into <prgn>dpkg</prgn> and <prgn>dselect</prgn>'s
4844 database of available packages. If no packages list was
4845 available and the user was offered and accepted the option
4846 of scanning the actual files available this scan should be
4847 done here, using <tt>dpkg --record-avail</tt>.
4851 The install script should feed all the available
4852 <tt>.deb</tt> files to <tt>dpkg --iGOEB</tt> (this is
4853 equivalent to <tt>dpkg --install
4854 --refuse-downgrade --selected-only --skip-same-version
4855 --auto-deconfigure</tt>). The <tt>-R</tt>
4856 (<tt>--recursive</tt>) option for traversing subdirectories
4857 may also be useful here).
4861 If any of these scripts needs to display a message for the
4862 user, it should wait for the user to hit `return' before
4863 exiting so that dselect doesn't immediately rewrite the
4868 If a method script succeeds (returns a zero exit status)
4869 <prgn>dselect</prgn> will return immediately to the main
4870 menu, with the `next' option highlighted ready for the user
4871 to select it. If it fails <prgn>dselect</prgn> will display
4872 a message and wait for the user to hit return.</p>
4875 <sect><heading>Location and arguments of the method scripts
4879 A set of scripts (henceforth known as a group) may provide
4880 several methods on the `main menu' with different behaviour.
4881 For example, there might be a generic get-packages-by-FTP
4882 group which might provide methods in the main menu for
4883 installation directly from one of the Debian mirror sites as
4884 well as for installation from a user-specified site.
4888 Each group of methods implemented by the same set of scripts
4889 should have a subdirectory
4890 <tt>/usr/lib/dpkg/methods/<var>group</var></tt> or
4891 <tt>/usr/local/lib/dpkg/methods/<var>group</var></tt>,
4893 <taglist compact="compact">
4894 <tag><tt>names</tt></tag>
4895 <item><p>a list of user-visible methods provided by these scripts.</p>
4897 <tag><tt>setup</tt></tag>
4898 <tag><tt>update</tt></tag>
4899 <tag><tt>install</tt></tag>
4900 <item><p>executable programs, the scripts themselves.</p>
4902 <tag><tt>desc.<var>option</var></tt></tag>
4903 <item><p>description file.</p></item>
4908 <tt>names</tt> will be formatted as a list of lines, each containing:
4910 <var>sequence</var> <var>method</var> <var>summary</var>
4914 <var>sequence</var> is a two-digit number that will be used
4915 much like <tt>rc.d</tt> prefixes to control the order in the
4916 main menu. If in doubt use 50.
4920 <var>method</var> is a name which is displayed by
4921 <prgn>dselect</prgn> as the name of the method, and which
4922 will be passed to <tt>setup</tt>, <tt>update</tt> and
4923 <tt>unpack</tt> as their first argument.
4927 <var>summary</var> is the brief description string for
4928 <prgn>dselect</prgn>'s menu.
4932 Each of the three scripts gets the same three arguments:
4933 <var>vardir</var>, <var>group</var> and <var>method</var>.
4934 <var>vardir</var> is the base directory for storing
4935 <prgn>dpkg</prgn> and <prgn>dselect</prgn>'s state, usually
4936 <tt>/var/lib/dpkg</tt>; this is passed in so that the
4937 <tt>--admindir</tt> option to <prgn>dselect</prgn> is
4942 Each option may have an extended description in
4943 <tt>desc.<var>option</var></tt>. This should be formatted
4944 like the extended description part of a <tt>Description</tt>
4945 field entry <em>shifted one character to the left</em>.
4949 <tt><var>vardir</var>/methods</tt> will exist, and a method
4951 <tt><var>vardir</var>/methods/<var>group</var></tt>
4952 directory to store its state.
4956 The group name and method name must follow the rules for C
4962 <chapt id="conversion"><heading>Conversion procedure from old
4967 This is a brief summary of the procedure for converting a
4968 pre-2.0.0.0-format source package into the new format.
4972 You are strongly advised to download and examine the <prgn>hello</prgn>
4973 package, and to read the section in the <prgn>dpkg</prgn> programmers'
4974 manual describing the source packaging tools. More detail about the
4975 exact functionality of these tools is available in
4976 <manref name="dpkg-source" section="1">.
4983 Download the original source code from wherever it can
4984 be found and do any rearrangement required to make it
4985 look like the original tree of the Debian source. Put
4987 <tt><var>package</var>-<var>upstream-version</var>.orig/</tt>
4989 <tt><var>package</var>_<var>upstream-version</var>.orig.tar.gz</tt>.
4995 Rename all files <tt>debian.*</tt> to <tt>debian/*</tt>.
4996 There may be some exceptions to this, but this is a good
5002 Edit the <tt>debian/changelog</tt> - create or rename it
5003 if necessary. Add a new revision to the top with the
5004 appropriate details, and a local variables entry to the
5005 bottom to set Emacs to the right mode:
5008 mode: debian-changelog
5016 Edit/create <tt>debian/control</tt>:
5017 <list compact="compact">
5020 Remove the <tt>Version</tt> field. If it is
5021 generated unusually (not equal to the source
5022 version) you must use the -v option to
5023 dpkg-gencontrol (see below). <tt>Section</tt>,
5024 <tt>Priority</tt>, <tt>Maintainer</tt> go above
5025 the first blank line, most of the rest
5032 Reorder the fields and add a blank line at an
5033 appropriate point, separating the source package
5034 fields from the binary package fields.
5039 <p>Add the <tt>Source</tt> field.</p></item>
5043 Add the <tt>Standards-Version</tt> field. (Please
5044 check out the Debian Policy Manual for details
5045 about this field.)</p>
5050 Change the <tt>Architecture</tt> field for each
5051 package to <tt>any</tt>, <tt>all</tt> or whatever.
5052 If there isn't an <tt>Architecture</tt> field add
5058 If any other use of sed or things used to happen
5059 to make the binary control files use
5060 <prgn>dpkg-gencontrol</prgn>'s variable
5061 substitution features to achieve the same effect.
5062 Use <tt>debian/substvars</tt> if you need to put
5063 unusally-generated information (apart from details
5064 of <tt>.deb</tt> files) in the <tt>.changes</tt>
5072 <p>Edit the <tt>debian/rules</tt>:
5073 <list compact="compact">
5076 Remove the <prgn>source</prgn> and
5077 <prgn>diff</prgn> and any <prgn>changes</prgn> and
5078 <prgn>dist</prgn> targets. These things now
5079 happen in a package-independent way and are not
5080 done by <tt>debian/rules</tt>.</p>
5084 Split the <prgn>binary</prgn> target into
5085 <prgn>binary-arch</prgn> and
5086 <prgn>binary-indep</prgn>; in many cases all of
5087 <prgn>binary</prgn> should go into
5088 <prgn>binary-arch</prgn>. Create the
5089 <prgn>binary</prgn> target and the unused of the
5090 two other <prgn>binary-*</prgn> targets if there
5091 is one - you can copy the ones from the
5092 <prgn>hello</prgn> package.</p>
5096 Change the <prgn>binary</prgn> target to use
5097 <prgn>dpkg-gencontrol</prgn> to make the package
5098 control file(s). Move it to after all the files
5099 have been installed but just before the last
5100 <prgn>chown</prgn> and <prgn>chmod</prgn> in the
5105 Change occurrences of <tt>debian-tmp</tt> to
5106 <tt>debian/tmp</tt>.</p>
5110 Change occurrences of
5111 <tt>debian.{post,pre}{inst,rm}</tt> to
5112 <tt>debian/*</tt>.</p>
5116 Remove the version number setting at the top, if
5121 Ensure that the package's Debian-specific and
5122 upstream changelogs are installed.</p>
5130 Change the package to use <prgn>dpkg-shlibdeps</prgn> to
5131 determine its shared library dependencies and substitute
5132 them in. Shared library dependencies should no longer
5133 be hardwired in the source package.</p>
5138 Check that the <tt>debian/README</tt> is really the
5139 copyright file, and if so rename it to
5140 <tt>debian/copyright</tt> and edit <tt>debian/rules</tt>
5141 to cope with this and to change the installation of the
5143 <tt>/usr/doc/<var>package</var>/copyright</tt> to
5144 <tt>/usr/doc/copyright/<var>package</var></tt>. If it
5145 isn't then find <tt>debian/copyright</tt> and decide
5146 what to do with the <tt>README</tt>.</p>
5150 <p>Check for various other anachronisms and problems:
5151 <list compact="compact">
5154 Remove any <tt>Package_Revision</tt>,
5155 <tt>Package-Revision</tt> or <tt>Revision</tt>
5160 Rename <tt>Optional</tt> to <tt>Suggests</tt>,
5161 <tt>Recommended</tt> to
5162 <tt>Recommends</tt>.</p>
5167 <tt>/usr/doc/examples/<var>package</var></tt> to
5168 <tt>/usr/doc/<var>package</var>/examples</tt>.</p>
5172 Make sure that manpages are installed
5177 Check that the description has an extended
5178 description, is well-formatted and meaningful and
5179 helpful to people wanting to know whether to
5180 install a package.</p>
5187 <p>Look everything over.</p></item>
5191 Do a test build using <tt>dpkg-buildpackage -us -uc -sa
5192 -r<var>whatever</var></tt>. Check the permissions and
5193 locations of files in the resulting package by examining
5194 the output of <tt>dpkg-deb --contents</tt>, and check
5195 that the source build happened OK. Test install the
5196 binary package(s) and test extract the source
5202 Sign the release: either rebuild everything with
5203 <tt>dpkg-buildpackage -sa</tt>, or PGP-sign the
5204 <tt>.dsc</tt>, rebuild the <tt>.changes</tt> using
5205 <tt>dpkg-genchanges -sa</tt>, and then PGP-sign the
5206 <tt>.changes</tt>.</p>
5213 The use of <tt>-sa</tt> on <prgn>dpkg-buildpackage</prgn> and
5214 <prgn>dpkg-genchanges</prgn> is important when doing the first
5215 build/uploading of a new-format source package. Unless this
5216 happens to be Debian revision <tt>0</tt> or <tt>1</tt> by
5217 default the original source tarfile will not be included in
5218 the uploaded files listed in the <tt>.changes</tt> file, and
5219 so it won't be installed on the FTP site. <tt>-sa</tt>
5220 requests that the original source be included