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: Julian Gilbey </name>
37 <email>J.D.Gilbey@qmw.ac.uk</email>
40 <name>Maintainer: The Debian Policy group </name>
41 <email>debian-policy@lists.debian.org</email>
43 <version>version &version;, &date;</version>
46 This manual describes the technical aspects of creating Debian
47 binary and source packages. It does not deal with the Debian
48 Project policy requirements, and it assumes familiarity with
49 <prgn>dpkg</prgn>'s functions from the system administrator's
50 perspective. This package itself is maintained by a group of
51 maintainers that have no editorial powers. At the moment, the
52 list of maintainers is:
55 <p>Michael Alan Dorman <email>mdorman@debian.org</email></p>
58 <p>Richard Braakman <email>dark@xs4all.nl</email></p>
61 <p>Philip Hands <email>phil@hands.com</email></p>
64 <p>Julian Gilbey <email>J.D.Gilbey@qmw.ac.uk</email></p>
67 <p>Manoj Srivastava <email>srivasta@debian.org</email></p>
74 <copyrightsummary>Copyright ©1996 Ian Jackson.</copyrightsummary>
76 This manual is free software; you may redistribute it and/or
77 modify it under the terms of the GNU General Public License
78 as published by the Free Software Foundation; either version
79 2, or (at your option) any later version.
83 This is distributed in the hope that it will be useful, but
84 <em>without any warranty</em>; without even the implied
85 warranty of merchantability or fitness for a particular
86 purpose. See the GNU General Public License for more
91 A copy of the GNU General Public License is available as
92 <tt>/usr/doc/copyright/GPL</tt> in the Debian GNU/Linux
93 distribution or on the World Wide Web at
94 <tt>http://www.gnu.org/copyleft/gpl.html</tt>. You can also
95 obtain it by writing to the Free Software Foundation, Inc.,
96 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
102 <!-- Describes the technical interface between a package and dpkg.
104 How to safely put shared libraries in a package. Details of
105 dpkg's handling of individual files. Sections on when to use
106 which feature (eg Replaces vs. Replaces/Conflicts
107 vs. update-alternatives vs. diversions) Cross-references to the
108 policy document (see below) where appropriate. Description of the
109 interface between dselect and its access methods. Hints on where
110 to start with a new package (ie, the hello package). What to do
115 Manpages are required for: update-rc.d, diversions,
116 update-alternatives, install-info in a package.
121 <heading>Introduction and scope of this manual</heading>
124 <prgn>dpkg</prgn> is a suite of programs for creating binary
125 package files and installing and removing them on Unix
128 <prgn>dpkg</prgn> is targetted primarily at Debian
129 GNU/Linux, but may work on or be ported to other
136 The binary packages are designed for the management of
137 installed executable programs (usually compiled binaries) and
138 their associated data, though source code examples and
139 documentation are provided as part of some packages.</p>
142 This manual describes the technical aspects of creating Debian
143 binary packages (<tt>.deb</tt> files). It documents the
144 behaviour of the package management programs
145 <prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and the way
146 they interact with packages.</p>
149 It also documents the interaction between
150 <prgn>dselect</prgn>'s core and the access method scripts it
151 uses to actually install the selected packages, and describes
152 how to create a new access method.</p>
155 This manual does not go into detail about the options and
156 usage of the package building and installation tools. It
157 should therefore be read in conjuction with those programs'
162 The utility programs which are provided with <prgn>dpkg</prgn>
163 for managing various system configuration and similar issues,
164 such as <prgn>update-rc.d</prgn> and
165 <prgn>install-info</prgn>, are not described in detail here -
166 please see their manpages.
170 It does <em>not</em> describe the policy requirements imposed
171 on Debian packages, such as the permissions on files and
172 directories, documentation requirements, upload procedure, and
173 so on. You should see the Debian packaging policy manual for
174 these details. (Many of them will probably turn out to be
175 helpful even if you don't plan to upload your package and make
176 it available as part of the distribution.)
180 It is assumed that the reader is reasonably familiar with the
181 <prgn>dpkg</prgn> System Administrators' manual.
182 Unfortunately this manual does not yet exist.
186 The Debian version of the FSF's GNU hello program is provided
187 as an example for people wishing to create Debian
188 packages. The Debian <prgn>debmake</prgn> package is
189 recommended as a very helpful tool in creating and maintaining
190 Debian packages. However, while the tools and examples are
191 helpful, they do not replace the need to read and follow the
192 Policy and Programmer's Manual.</p>
195 <chapt id="binarypkg"><heading>Binary packages
199 The binary package has two main sections. The first part
200 consists of various control information files and scripts used
201 by <prgn>dpkg</prgn> when installing and removing. See <ref
206 The second part is an archive containing the files and
207 directories to be installed.
211 In the future binary packages may also contain other
212 components, such as checksums and digital signatures. The
213 format for the archive is described in full in the
214 <tt>deb(5)</tt> manpage.
218 <sect id="bincreating"><heading>Creating package files -
219 <prgn>dpkg-deb</prgn>
223 All manipulation of binary package files is done by
224 <prgn>dpkg-deb</prgn>; it's the only program that has
225 knowledge of the format. (<prgn>dpkg-deb</prgn> may be
226 invoked by calling <prgn>dpkg</prgn>, as <prgn>dpkg</prgn>
227 will spot that the options requested are appropriate to
228 <prgn>dpkg-deb</prgn> and invoke that instead with the same
233 In order to create a binary package you must make a
234 directory tree which contains all the files and directories
235 you want to have in the filesystem data part of the package.
236 In Debian-format source packages this directory is usually
237 <tt>debian/tmp</tt>, relative to the top of the package's
242 They should have the locations (relative to the root of the
243 directory tree you're constructing) ownerships and
244 permissions which you want them to have on the system when
249 With current versions of <prgn>dpkg</prgn> the uid/username
250 and gid/groupname mappings for the users and groups being
251 used should be the same on the system where the package is
252 built and the one where it is installed.
256 You need to add one special directory to the root of the
257 miniature filesystem tree you're creating:
258 <prgn>DEBIAN</prgn>. It should contain the control
259 information files, notably the binary package control file
260 (see <ref id="controlfile">).
264 The <prgn>DEBIAN</prgn> directory will not appear in the
265 filesystem archive of the package, and so won't be installed
266 by <prgn>dpkg</prgn> when the package is installed.
270 When you've prepared the package, you should invoke:
272 dpkg --build <var>directory</var>
277 This will build the package in
278 <tt><var>directory</var>.deb</tt>. (<prgn>dpkg</prgn> knows
279 that <tt>--build</tt> is a <prgn>dpkg-deb</prgn> option, so
280 it invokes <prgn>dpkg-deb</prgn> with the same arguments to
285 See the manpage <manref name="dpkg-deb" section="8"> for details of how
286 to examine the contents of this newly-created file. You may find the
287 output of following commands enlightening:
289 dpkg-deb --info <var>filename</var>.deb
290 dpkg-deb --contents <var>filename</var>.deb
291 dpkg --contents <var>filename</var>.deb
293 To view the copyright file for a package you could use this command:
295 dpkg --fsys-tarfile <var>filename</var>.deb | tar xof usr/doc/<var>\*</var>copyright | less
300 <sect id="controlarea">
302 Package control information files
306 The control information portion of a binary package is a
307 collection of files with names known to <prgn>dpkg</prgn>.
308 It will treat the contents of these files specially - some
309 of them contain information used by <prgn>dpkg</prgn> when
310 installing or removing the package; others are scripts which
311 the package maintainer wants <prgn>dpkg</prgn> to run.
315 It is possible to put other files in the package control
316 area, but this is not generally a good idea (though they
317 will largely be ignored).
321 Here is a brief list of the control info files supported by
322 <prgn>dpkg</prgn> and a summary of what they're used for.
327 <tag><tt>control</tt>
331 This is the key description file used by
332 <prgn>dpkg</prgn>. It specifies the package's name
333 and version, gives its description for the user,
334 states its relationships with other packages, and so
335 forth. See <ref id="controlfile">.
339 It is usually generated automatically from information
340 in the source package by the
341 <prgn>dpkg-gencontrol</prgn> program, and with
342 assistance from <prgn>dpkg-shlibdeps</prgn>. See <ref
343 id="sourcetools">.</p>
346 <tag><tt>postinst</tt>, <tt>preinst</tt>, <tt>postrm</tt>,
352 These are exectuable files (usually scripts) which
353 <prgn>dpkg</prgn> runs during installation, upgrade
354 and removal of packages. They allow the package to
355 deal with matters which are particular to that package
356 or require more complicated processing than that
357 provided by <prgn>dpkg</prgn>. Details of when and
358 how they are called are in <ref
359 id="maintainerscripts">.
363 It is very important to make these scripts
367 That means that if it runs successfully or fails
368 and then you call it again it doesn't bomb out,
369 but just ensures that everything is the way it
372 </footnote> This is so that if an error occurs, the
373 user interrupts <prgn>dpkg</prgn> or some other
374 unforeseen circumstance happens you don't leave the
375 user with a badly-broken package.
379 The maintainer scripts are guaranteed to run with a
380 controlling terminal and can interact with the user.
381 If they need to prompt for passwords, do full-screen
382 interaction or something similar you should do these
383 things to and from <tt>/dev/tty</tt>, since
384 <prgn>dpkg</prgn> will at some point redirect scripts'
385 standard input and output so that it can log the
386 installation process. Likewise, because these scripts
387 may be executed with standard output redirected into a
388 pipe for logging purposes, Perl scripts should set
389 unbuffered output by setting <tt>$|=1</tt> so that the
390 output is printed immediately rather than being
395 Each script should return a zero exit status for
396 success, or a nonzero one for failure.</p>
399 <tag><tt>conffiles</tt>
404 This file contains a list of configuration files which
405 are to be handled automatically by <prgn>dpkg</prgn>
406 (see <ref id="conffiles">). Note that not necessarily
407 every configuration file should be listed here.</p>
415 This file contains a list of the shared libraries
416 supplied by the package, with dependency details for
417 each. This is used by <prgn>dpkg-shlibdeps</prgn>
418 when it determines what dependencies are required in a
419 package control file. The <tt>shlibs</tt> file format
420 is described on <ref id="shlibs">.
426 <sect id="controlfile">
428 The main control information file: <tt>control</tt>
431 The most important control information file used by
432 <prgn>dpkg</prgn> when it installs a package is
433 <tt>control</tt>. It contains all the package's `vital
438 The binary package control files of packages built from
439 Debian sources are made by a special tool,
440 <prgn>dpkg-gencontrol</prgn>, which reads
441 <tt>debian/control</tt> and <tt>debian/changelog</tt> to
442 find the information it needs. See <ref id="sourcepkg"> for
447 The fields in binary package control files are:
448 <list compact="compact">
450 <p><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</p>
453 <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
455 <item><p><qref id="f-Architecture"><tt>Architecture</tt></qref>
459 This field should appear in all packages, though
460 <prgn>dpkg</prgn> doesn't require it yet so that
461 old packages can still be installed.
467 <p><qref id="relationships"><tt>Depends</tt>,
468 <tt>Provides</tt> et al.</qref></p>
471 <p><qref id="f-Essential"><tt>Essential</tt></qref></p>
474 <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
477 <p><qref id="f-classification"><tt>Section</tt>,
478 <tt>Priority</tt></qref></p>
481 <p><qref id="f-Source"><tt>Source</tt></qref></p>
484 <p><qref id="descriptions"><tt>Description</tt></qref></p>
488 <qref id="f-Installed-Size"><tt>Installed-Size</tt></qref>
494 A description of the syntax of control files and the purpose
495 of these fields is available in <ref id="controlfields">.
499 <heading>Time Stamps</heading>
501 Maintainers are encouraged to preserve the modification
502 times of the upstream source files in a package, as far as
503 is reasonably possible.
506 The rationale is that there is some information conveyed
507 by knowing the age of the file, for example, you could
508 recognize that some documentation is very old by looking
509 at the modification time, so it would be nice if the
510 modification time of the upstream source would be
518 <chapt id="sourcepkg">
519 <heading>Source packages</heading>
522 The Debian binary packages in the distribution are generated
523 from Debian sources, which are in a special format to assist
524 the easy and automatic building of binaries.
528 There was a previous version of the Debian source format,
529 which is now being phased out. Instructions for converting an
530 old-style package are given in the Debian policy manual.
533 <sect id="sourcetools">
534 <heading>Tools for processing source packages</heading>
537 Various tools are provided for manipulating source packages;
538 they pack and unpack sources and help build of binary
539 packages and help manage the distribution of new versions.
543 They are introduced and typical uses described here; see
544 <manref name="dpkg-source" section="1"> for full
545 documentation about their arguments and operation.
549 For examples of how to construct a Debian source package,
550 and how to use those utilities that are used by Debian
551 source packages, please see the <prgn>hello</prgn> example
557 <prgn>dpkg-source</prgn> - packs and unpacks Debian source
562 This program is frequently used by hand, and is also
563 called from package-independent automated building scripts
564 such as <prgn>dpkg-buildpackage</prgn>.
568 To unpack a package it is typically invoked with
570 dpkg-source -x <var>.../path/to/filename</var>.dsc
575 with the <tt><var>filename</var>.tar.gz</tt> and
576 <tt><var>filename</var>.diff.gz</tt> (if applicable) in
577 the same directory. It unpacks into
578 <tt><var>package</var>-<var>version</var></tt>, and if
580 <tt><var>package</var>-<var>version</var>.orig</tt>, in
581 the current directory.
585 To create a packed source archive it is typically invoked:
587 dpkg-source -b <var>package</var>-<var>version</var>
592 This will create the <tt>.dsc</tt>, <tt>.tar.gz</tt> and
593 <tt>.diff.gz</tt> (if appropriate) in the current
594 directory. <prgn>dpkg-source</prgn> does not clean the
595 source tree first - this must be done separately if it is
600 See also <ref id="sourcearchives">.</p>
606 <prgn>dpkg-buildpackage</prgn> - overall package-building
611 <prgn>dpkg-buildpackage</prgn> is a script which invokes
612 <prgn>dpkg-source</prgn>, the <tt>debian/rules</tt>
613 targets <prgn>clean</prgn>, <prgn>build</prgn> and
614 <prgn>binary</prgn>, <prgn>dpkg-genchanges</prgn> and
615 <prgn>pgp</prgn> to build a signed source and binary
620 It is usually invoked by hand from the top level of the
621 built or unbuilt source directory. It may be invoked with
622 no arguments; useful arguments include:
623 <taglist compact="compact">
624 <tag><tt>-uc</tt>, <tt>-us</tt></tag>
627 Do not PGP-sign the <tt>.changes</tt> file or the
628 source package <tt>.dsc</tt> file, respectively.</p>
630 <tag><tt>-p<var>pgp-command</var></tt></tag>
633 Invoke <var>pgp-command</var> instead of finding
634 <tt>pgp</tt> on the <prgn>PATH</prgn>.
635 <var>pgp-command</var> must behave just like
636 <prgn>pgp</prgn>.</p>
638 <tag><tt>-r<var>root-command</var></tt></tag>
641 When root privilege is required, invoke the command
642 <var>root-command</var>. <var>root-command</var>
643 should invoke its first argument as a command, from
644 the <prgn>PATH</prgn> if necessary, and pass its
645 second and subsequent arguments to the command it
646 calls. If no <var>root-command</var> is supplied
647 then <var>dpkg-buildpackage</var> will take no
648 special action to gain root privilege, so that for
649 most packages it will have to be invoked as root to
652 <tag><tt>-b</tt>, <tt>-B</tt></tag>
655 Two types of binary-only build and upload - see
656 <manref name="dpkg-source" section="1">.
665 <prgn>dpkg-gencontrol</prgn> - generates binary package
670 This program is usually called from <tt>debian/rules</tt>
671 (see <ref id="sourcetree">) in the top level of the source
676 This is usually done just before the files and directories in the
677 temporary directory tree where the package is being built have their
678 permissions and ownerships set and the package is constructed using
679 <prgn>dpkg-deb/</prgn>
682 This is so that the control file which is produced has
683 the right permissions
689 <prgn>dpkg-gencontrol</prgn> must be called after all the
690 files which are to go into the package have been placed in
691 the temporary build directory, so that its calculation of
692 the installed size of a package is correct.
696 It is also necessary for <prgn>dpkg-gencontrol</prgn> to
697 be run after <prgn>dpkg-shlibdeps</prgn> so that the
698 variable substitutions created by
699 <prgn>dpkg-shlibdeps</prgn> in <tt>debian/substvars</tt>
704 For a package which generates only one binary package, and
705 which builds it in <tt>debian/tmp</tt> relative to the top
706 of the source package, it is usually sufficient to call
707 <prgn>dpkg-gencontrol</prgn>.
711 Sources which build several binaries will typically need
714 dpkg-gencontrol -Pdebian/tmp-<var>pkg</var> -p<var>package</var>
715 </example> The <tt>-P</tt> tells
716 <prgn>dpkg-gencontrol</prgn> that the package is being
717 built in a non-default directory, and the <tt>-p</tt>
718 tells it which package's control file should be generated.
722 <prgn>dpkg-gencontrol</prgn> also adds information to the
723 list of files in <tt>debian/files</tt>, for the benefit of
724 (for example) a future invocation of
725 <prgn>dpkg-genchanges</prgn>.</p>
730 <prgn>dpkg-shlibdeps</prgn> - calculates shared library
735 This program is usually called from <tt>debian/rules</tt>
736 just before <prgn>dpkg-gencontrol</prgn> (see <ref
737 id="sourcetree">), in the top level of the source tree.
741 Its arguments are executables.
744 In a forthcoming dpkg version,
745 <prgn>dpkg-shlibdeps</prgn> would be required to be
746 called on shared libraries as well.
749 They may be specified either in the locations in the
750 source tree where they are created or in the locations
751 in the temporary build tree where they are installed
752 prior to binary package creation.
754 </footnote> for which shared library dependencies should
755 be included in the binary package's control file.
759 If some of the found shared libraries should only
760 warrant a <tt>Recommends</tt> or <tt>Suggests</tt>, or if
761 some warrant a <tt>Pre-Depends</tt>, this can be achieved
762 by using the <tt>-d<var>dependency-field</var></tt> option
763 before those executable(s). (Each <tt>-d</tt> option
764 takes effect until the next <tt>-d</tt>.)
768 <prgn>dpkg-shlibdeps</prgn> does not directly cause the
769 output control file to be modified. Instead by default it
770 adds to the <tt>debian/substvars</tt> file variable
771 settings like <tt>shlibs:Depends</tt>. These variable
772 settings must be referenced in dependency fields in the
773 appropriate per-binary-package sections of the source
778 For example, the <prgn>procps</prgn> package generates two
779 kinds of binaries, simple C binaries like <prgn>ps</prgn>
780 which require a predependency and full-screen ncurses
781 binaries like <prgn>top</prgn> which require only a
782 recommendation. It can say in its <tt>debian/rules</tt>:
784 dpkg-shlibdeps -dPre-Depends ps -dRecommends top
786 and then in its main control file <tt>debian/control</tt>:
790 Pre-Depends: ${shlibs:Pre-Depends}
791 Recommends: ${shlibs:Recommends}
797 Sources which produce several binary packages with
798 different shared library dependency requirements can use
799 the <tt>-p<var>varnameprefix</var></tt> option to override
800 the default <tt>shlib:</tt> prefix (one invocation of
801 <prgn>dpkg-shlibdeps</prgn> per setting of this option).
802 They can thus produce several sets of dependency
803 variables, each of the form
804 <tt><var>varnameprefix</var>:<var>dependencyfield</var></tt>,
805 which can be referred to in the appropriate parts of the
806 binary package control files.
813 <prgn>dpkg-distaddfile</prgn> - adds a file to
814 <tt>debian/files</tt>
818 Some packages' uploads need to include files other than
819 the source and binary package files.
823 <prgn>dpkg-distaddfile</prgn> adds a file to the
824 <tt>debian/files</tt> file so that it will be included in
825 the <tt>.changes</tt> file when
826 <prgn>dpkg-genchanges</prgn> is run.
830 It is usually invoked from the <prgn>binary</prgn> target of
831 <tt>debian/rules</tt>:
833 dpkg-distaddfile <var>filename</var> <var>section</var> <var>priority</var>
835 The <var>filename</var> is relative to the directory where
836 <prgn>dpkg-genchanges</prgn> will expect to find it - this
837 is usually the directory above the top level of the source
838 tree. The <tt>debian/rules</tt> target should put the
839 file there just before or just after calling
840 <prgn>dpkg-distaddfile</prgn>.
844 The <var>section</var> and <var>priority</var> are passed
845 unchanged into the resulting <tt>.changes</tt> file. See
846 <ref id="f-classification">.
851 <sect1><heading><prgn>dpkg-genchanges</prgn> - generates a <tt>.changes</tt> upload
856 This program is usually called by package-independent
857 automatic building scripts such as
858 <prgn>dpkg-buildpackage</prgn>, but it may also be called
863 It is usually called in the top level of a built source
864 tree, and when invoked with no arguments will print out a
865 straightforward <tt>.changes</tt> file based on the
866 information in the source package's changelog and control
867 file and the binary and source packages which should have
873 <sect1><heading><prgn>dpkg-parsechangelog</prgn> - produces parsed representation of
878 This program is used internally by
879 <prgn>dpkg-source</prgn> et al. It may also occasionally
880 be useful in <tt>debian/rules</tt> and elsewhere. It
881 parses a changelog, <tt>debian/changelog</tt> by default,
882 and prints a control-file format representation of the
883 information in it to standard output.
887 <sect1 id="dpkgarch"><heading><prgn>dpkg-architecture</prgn> -
888 information about the build and host system
892 This program can be used manually, but is also invoked by
893 <tt>dpkg-buildpackage</tt> or <tt>debian/rules</tt> to set
894 to set environment or make variables which specify the build and
895 host architecture for the package building process.
900 <sect id="sourcetree"><heading>The Debianised source tree
904 The source archive scheme described later is intended to
905 allow a Debianised source tree with some associated control
906 information to be reproduced and transported easily. The
907 Debianised source tree is a version of the original program
908 with certain files added for the benefit of the
909 Debianisation process, and with any other changes required
910 made to the rest of the source code and installation
915 The extra files created for Debian are in the subdirectory
916 <tt>debian</tt> of the top level of the Debianised source
917 tree. They are described below.
920 <sect1 id="debianrules"><heading><tt>debian/rules</tt> - the main building
925 This file is an executable makefile, and contains the
926 package-specific recipies for compiling the package and
927 building binary package(s) out of the source.
931 It must start with the line <tt>#!/usr/bin/make -f</tt>,
932 so that it can be invoked by saying its name rather than
933 invoking <prgn>make</prgn> explicitly.
937 Since an interactive <tt>debian/rules</tt> script makes it
938 impossible to autocompile that package and also makes it
939 hard for other people to reproduce the same binary
940 package, all <strong>required targets</strong> have to be
941 non-interactive. At a minimul, required targets are the
942 ones called by <prgn>dpkg-buildpackage</prgn>, namely,
943 <em>clean</em>, <em>binary</em>, <em>binary-arch</em>, and
944 <em>build</em>. It also follows that any target that these
945 targets depend on must also be non-interactive.
949 The targets which are required to be present are:
951 <tag><tt>build</tt></tag>
954 This should perform all non-interactive
955 configuration and compilation of the package. If a
956 package has an interactive pre-build configuration
957 routine, the Debianised source package should be
958 built after this has taken place, so that it can be
959 built without rerunning the configuration.
963 For some packages, notably ones where the same
964 source tree is compiled in different ways to produce
965 two binary packages, the <prgn>build</prgn> target
966 does not make much sense. For these packages it is
967 good enough to provide two (or more) targets
968 (<tt>build-a</tt> and <tt>build-b</tt> or whatever)
969 for each of the ways of building the package, and a
970 <prgn>build</prgn> target that does nothing. The
971 <prgn>binary</prgn> target will have to build the
972 package in each of the possible ways and make the
973 binary package out of each.
977 The <prgn>build</prgn> target must not do anything
978 that might require root privilege.
982 The <prgn>build</prgn> target may need to run
983 <prgn>clean</prgn> first - see below.
987 When a package has a configuration routine that
988 takes a long time, or when the makefiles are poorly
989 designed, or when <prgn>build</prgn> needs to run
990 <prgn>clean</prgn> first, it is a good idea to
991 <tt>touch build</tt> when the build process is
992 complete. This will ensure that if <tt>debian/rules
993 build</tt> is run again it will not rebuild the
998 <tag><tt>binary</tt>, <tt>binary-arch</tt>,
999 <tt>binary-indep</tt>
1003 The <prgn>binary</prgn> target should be all that is
1004 necessary for the user to build the binary
1005 package. All these targets are required to be
1006 non-interactive. It is split into two parts:
1007 <prgn>binary-arch</prgn> builds the packages' output
1008 files which are specific to a particular
1009 architecture, and <prgn>binary-indep</prgn> builds
1010 those which are not.
1014 <prgn>binary</prgn> should usually be a target with
1015 no commands which simply depends on
1016 <prgn>binary-arch</prgn> and
1017 <prgn>binary-indep</prgn>.
1021 Both <prgn>binary-*</prgn> targets should depend on
1022 the <prgn>build</prgn> target, above, so that the
1023 package is built if it has not been already. It
1024 should then create the relevant binary package(s),
1025 using <prgn>dpkg-gencontrol</prgn> to make their
1026 control files and <prgn>dpkg-deb</prgn> to build
1027 them and place them in the parent of the top level
1032 If one of the <prgn>binary-*</prgn> targets has
1033 nothing to do (this will be always be the case if
1034 the source generates only a single binary package,
1035 whether architecture-dependent or not) it
1036 <em>must</em> still exist, but should always
1041 <ref id="binarypkg"> describes how to construct
1046 The <prgn>binary</prgn> targets must be invoked as
1051 <tag><tt>clean</tt></tag>
1055 This should undo any effects that the
1056 <prgn>build</prgn> and <prgn>binary</prgn> targets
1057 may have had, except that it should leave alone any
1058 output files created in the parent directory by a
1059 run of <prgn>binary</prgn>. This target is required
1060 to be non-interactive.
1064 If a <prgn>build</prgn> file is touched at the end
1065 of the <prgn>build</prgn> target, as suggested
1066 above, it must be removed as the first thing that
1067 <prgn>clean</prgn> does, so that running
1068 <prgn>build</prgn> again after an interrupted
1069 <prgn>clean</prgn> doesn't think that everything is
1074 The <prgn>clean</prgn> target must be invoked as
1075 root if <prgn>binary</prgn> has been invoked since
1076 the last <prgn>clean</prgn>, or if
1077 <prgn>build</prgn> has been invoked as root (since
1078 <prgn>build</prgn> may create directories, for
1083 <tag><tt>get-orig-source</tt> (optional)</tag>
1087 This target fetches the most recent version of the
1088 original source package from a canonical archive
1089 site (via FTP or WWW, for example), does any
1090 necessary rearrangement to turn it into the original
1091 source tarfile format described below, and leaves it
1092 in the current directory.
1096 This target may be invoked in any directory, and
1097 should take care to clean up any temporary files it
1102 This target is optional, but providing it if
1103 possible is a good idea.
1109 The <prgn>build</prgn>, <prgn>binary</prgn> and
1110 <prgn>clean</prgn> targets must be invoked with a current
1111 directory of the package's top-level directory.
1116 Additional targets may exist in <tt>debian/rules</tt>,
1117 either as published or undocumented interfaces or for the
1118 package's internal use.
1122 The architecture we build on and build for is determined by make
1123 variables via dpkg-architecture (see <ref id="dpkgarch">). You can
1124 get the Debian architecture and the GNU style architecture
1125 specification string for the build machine as well as the host
1126 machine. Here is a list of supported make variables:
1127 <list compact="compact">
1129 <p><tt>DEB_*_ARCH</tt> (the Debian architecture)</p>
1132 <p><tt>DEB_*_GNU_TYPE</tt> (the GNU style architecture
1133 specification string)</p>
1136 <p><tt>DEB_*_GNU_CPU</tt> (the CPU part of DEB_*_GNU_TYPE)</p>
1139 <p><tt>DEB_*_GNU_SYSTEM</tt> (the System part of
1145 where <tt>*</tt> is either <tt>BUILD</tt> for specification of
1146 the build machine or <tt>HOST</tt> for specification of the machine
1151 Backward compatibility can be provided in the rules file
1152 by setting the needed variables to suitable default
1153 values, please refer to the documentation of
1154 dpkg-architecture for details.
1158 It is important to understand that the <tt>DEB_*_ARCH</tt>
1159 string does only determine which Debian architecture we
1160 build on resp. for. It should not be used to get the CPU
1161 or System information, the GNU style variables should be
1167 <sect1><heading><tt>debian/control</tt>
1171 This file contains version-independent details about the
1172 source package and about the binary packages it creates.
1176 It is a series of sets of control fields, each
1177 syntactically similar to a binary package control file.
1178 The sets are separated by one or more blank lines. The
1179 first set is information about the source package in
1180 general; each subsequent set describes one binary package
1181 that the source tree builds.
1185 The syntax and semantics of the fields are described below
1186 in <ref id="controlfields">.
1190 The general (binary-package-independent) fields are:
1191 <list compact="compact">
1193 <p><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</p>
1196 <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
1200 <qref id="f-classification"><tt>Section</tt> and
1201 <tt>Priority</tt></qref>
1202 (classification, mandatory)
1207 <qref id="relationships"><tt>Build-Depends</tt> et
1208 al.</qref> (source package interrelationships)
1213 <qref id="f-Standards-Version"><tt>Standards-Version</tt></qref>
1219 The per-binary-package fields are:
1220 <list compact="compact">
1222 <p><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</p>
1226 <qref id="f-Architecture"><tt>Architecture</tt></qref>
1230 <p><qref id="descriptions"><tt>Description</tt></qref></p>
1234 <qref id="f-classification"><tt>Section</tt> and
1235 <tt>Priority</tt></qref> (classification)</p>
1238 <p><qref id="f-Essential"><tt>Essential</tt></qref></p>
1242 <qref id="relationships"><tt>Depends</tt> et
1243 al.</qref> (binary package interrelationships)
1249 These fields are used by <prgn>dpkg-gencontrol</prgn> to
1250 generate control files for binary packages (see below), by
1251 <prgn>dpkg-genchanges</prgn> to generate the
1252 <tt>.changes</tt> file to accompany the upload, and by
1253 <prgn>dpkg-source</prgn> when it creates the <tt>.dsc</tt>
1254 source control file as part of a source archive.
1258 The fields here may contain variable references - their
1259 values will be substituted by
1260 <prgn>dpkg-gencontrol</prgn>, <prgn>dpkg-genchanges</prgn>
1261 or <prgn>dpkg-source</prgn> when they generate output
1262 control files. See <ref id="srcsubstvars"> for details.
1265 <p> <sect2><heading>User-defined fields
1269 Additional user-defined fields may be added to the
1270 source package control file. Such fields will be
1271 ignored, and not copied to (for example) binary or
1272 source package control files or upload control files.
1276 If you wish to add additional unsupported fields to
1277 these output files you should use the mechanism
1282 Fields in the main source control information file with
1283 names starting <tt>X</tt>, followed by one or more of
1284 the letters <tt>BCS</tt> and a hyphen <tt>-</tt>, will
1285 be copied to the output files. Only the part of the
1286 field name after the hyphen will be used in the output
1287 file. Where the letter <tt>B</tt> is used the field
1288 will appear in binary package control files, where the
1289 letter <tt>S</tt> is used in source package control
1290 files and where <tt>C</tt> is used in upload control
1291 (<tt>.changes</tt>) files.
1295 For example, if the main source information control file
1298 XBS-Comment: I stand between the candle and the star.
1300 then the binary and source package control files will contain the
1303 Comment: I stand between the candle and the star.
1310 <sect1 id="dpkgchangelog"><heading><tt>debian/changelog</tt>
1314 This file records the changes to the Debian-specific parts of the
1318 Though there is nothing stopping an author who is also
1319 the Debian maintainer from using it for all their
1320 changes, it will have to be renamed if the Debian and
1321 upstream maintainers become different
1328 It has a special format which allows the package building
1329 tools to discover which version of the package is being
1330 built and find out other release-specific information.
1334 That format is a series of entries like this:
1336 <var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
1338 * <var>change details</var>
1339 <var>more change details</var>
1340 * <var>even more change details</var>
1342 -- <var>maintainer name and email address</var> <var>date</var>
1347 <var>package</var> and <var>version</var> are the source
1348 package name and version number.
1352 <var>distribution(s)</var> lists the distributions where
1353 this version should be installed when it is uploaded - it
1354 is copied to the <tt>Distribution</tt> field in the
1355 <tt>.changes</tt> file. See <ref id="f-Distribution">.
1359 <var>urgency</var> is the value for the <tt>Urgency</tt>
1360 field in the <tt>.changes</tt> file for the upload. See
1361 <ref id="f-Urgency">. It is not possible to specify an
1362 urgency containing commas; commas are used to separate
1363 <tt><var>keyword</var>=<var>value</var></tt> settings in
1364 the <prgn>dpkg</prgn> changelog format (though there is
1365 currently only one useful <var>keyword</var>,
1370 The change details may in fact be any series of lines
1371 starting with at least two spaces, but conventionally each
1372 change starts with an asterisk and a separating space and
1373 continuation lines are indented so as to bring them in
1374 line with the start of the text above. Blank lines may be
1375 used here to separate groups of changes, if desired.
1379 The maintainer name and email address should <em>not</em>
1380 necessarily be those of the usual package maintainer.
1381 They should be the details of the person doing
1382 <em>this</em> version. The information here will be
1383 copied to the <tt>.changes</tt> file, and then later used
1384 to send an acknowledgement when the upload has been
1389 The <var>date</var> should be in RFC822 format
1392 This is generated by the <prgn>822-date</prgn>
1395 </footnote>; it should include the timezone specified
1396 numerically, with the timezone name or abbreviation
1397 optionally present as a comment.
1401 The first `title' line with the package name should start
1402 at the left hand margin; the `trailer' line with the
1403 maintainer and date details should be preceded by exactly
1404 one space. The maintainer details and the date must be
1405 separated by exactly two spaces.
1409 An Emacs mode for editing this format is available: it is
1410 called <tt>debian-changelog-mode</tt>. You can have this
1411 mode selected automatically when you edit a Debian
1412 changelog by adding a local variables clause to the end of
1416 <sect2><heading>Defining alternative changelog formats
1420 It is possible to use a different format to the standard
1421 one, by providing a parser for the format you wish to
1426 In order to have <tt>dpkg-parsechangelog</tt> run your
1427 parser, you must include a line within the last 40 lines
1428 of your file matching the Perl regular expression:
1429 <tt>\schangelog-format:\s+([0-9a-z]+)\W</tt> The part in
1430 parentheses should be the name of the format. For
1431 example, you might say:
1433 @@@ changelog-format: joebloggs @@@
1435 Changelog format names are non-empty strings of alphanumerics.
1439 If such a line exists then <tt>dpkg-parsechangelog</tt>
1440 will look for the parser as
1441 <tt>/usr/lib/dpkg/parsechangelog/<var>format-name</var></tt>
1443 <tt>/usr/local/lib/dpkg/parsechangelog/<var>format-name</var></tt>;
1444 it is an error for it not to find it, or for it not to
1445 be an executable program. The default changelog format
1446 is <tt>dpkg</tt>, and a parser for it is provided with
1447 the <tt>dpkg</tt> package.
1451 The parser will be invoked with the changelog open on
1452 standard input at the start of the file. It should read
1453 the file (it may seek if it wishes) to determine the
1454 information required and return the parsed information
1455 to standard output in the form of a series of control
1456 fields in the standard format. By default it should
1457 return information about only the most recent version in
1458 the changelog; it should accept a
1459 <tt>-v<var>version</var></tt> option to return changes
1460 information from all versions present <em>strictly
1461 after</em> <var>version</var>, and it should then be an
1462 error for <var>version</var> not to be present in the
1468 <list compact="compact">
1470 <p><qref id="f-Source"><tt>Source</tt></qref></p>
1473 <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
1477 <qref id="f-Distribution"><tt>Distribution</tt></qref>
1482 <p><qref id="f-Urgency"><tt>Urgency</tt></qref> (mandatory)</p>
1486 <qref id="f-Maintainer"><tt>Maintainer</tt></qref>
1491 <p><qref id="f-Date"><tt>Date</tt></qref></p>
1495 <qref id="f-Changes"><tt>Changes</tt></qref>
1502 If several versions are being returned (due to the use
1503 of <tt>-v</tt>), the urgency value should be of the
1504 highest urgency code listed at the start of any of the
1505 versions requested followed by the concatenated
1506 (space-separated) comments from all the versions
1507 requested; the maintainer, version, distribution and
1508 date should always be from the most recent version.
1512 For the format of the <tt>Changes</tt> field see <ref
1517 If the changelog format which is being parsed always or
1518 almost always leaves a blank line between individual
1519 change notes these blank lines should be stripped out,
1520 so as to make the resulting output compact.
1524 If the changelog format does not contain date or package
1525 name information this information should be omitted from
1526 the output. The parser should not attempt to synthesise
1527 it or find it from other sources.
1531 If the changelog does not have the expected format the
1532 parser should exit with a nonzero exit status, rather
1533 than trying to muddle through and possibly generating
1538 A changelog parser may not interact with the user at
1542 <sect1 id="srcsubstvars"><heading><tt>debian/substvars</tt>
1543 and variable substitutions
1547 When <prgn>dpkg-gencontrol</prgn>,
1548 <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
1549 generate control files they do variable substitutions on
1550 their output just before writing it. Variable
1551 substitutions have the form
1552 <tt>${<var>variable-name</var>}</tt>. The optional file
1553 <tt>debian/substvars</tt> contains variable substitutions
1554 to be used; variables can also be set directly from
1555 <tt>debian/rules</tt> using the <tt>-V</tt> option to the
1556 source packaging commands, and certain predefined
1557 variables are available.
1561 The is usually generated and modified dynamically by
1562 <tt>debian/rules</tt> targets; in this case it must be
1563 removed by the <prgn>clean</prgn> target.
1567 See <manref name="dpkg-source" section="1"> for full
1568 details about source variable substitutions, including the
1569 format of <tt>debian/substvars</tt>.</p>
1572 <sect1><heading><tt>debian/files</tt>
1576 This file is not a permanent part of the source tree; it
1577 is used while building packages to record which files are
1578 being generated. <prgn>dpkg-genchanges</prgn> uses it
1579 when it generates a <tt>.changes</tt> file.
1583 It should not exist in a shipped source package, and so it
1584 (and any backup files or temporary files such as
1588 <tt>files.new</tt> is used as a temporary file by
1589 <prgn>dpkg-gencontrol</prgn> and
1590 <prgn>dpkg-distaddfile</prgn> - they write a new
1591 version of <tt>files</tt> here before renaming it,
1592 to avoid leaving a corrupted copy if an error
1595 </footnote>) should be removed by the
1596 <prgn>clean</prgn> target. It may also be wise to
1597 ensure a fresh start by emptying or removing it at the
1598 start of the <prgn>binary</prgn> target.
1602 <prgn>dpkg-gencontrol</prgn> adds an entry to this file
1603 for the <tt>.deb</tt> file that will be created by
1604 <prgn>dpkg-deb</prgn> from the control file that it
1605 generates, so for most packages all that needs to be done
1606 with this file is to delete it in <prgn>clean</prgn>.
1610 If a package upload includes files besides the source
1611 package and any binary packages whose control files were
1612 made with <prgn>dpkg-gencontrol</prgn> then they should be
1613 placed in the parent of the package's top-level directory
1614 and <prgn>dpkg-distaddfile</prgn> should be called to add
1615 the file to the list in <tt>debian/files</tt>.</p>
1618 <sect1><heading><tt>debian/tmp</tt>
1622 This is the canonical temporary location for the
1623 construction of binary packages by the <prgn>binary</prgn>
1624 target. The directory <tt>tmp</tt> serves as the root of
1625 the filesystem tree as it is being constructed (for
1626 example, by using the package's upstream makefiles install
1627 targets and redirecting the output there), and it also
1628 contains the <tt>DEBIAN</tt> subdirectory. See <ref
1633 If several binary packages are generated from the same
1634 source tree it is usual to use several
1635 <tt>debian/tmp<var>something</var></tt> directories, for
1636 example <tt>tmp-a</tt> or <tt>tmp-doc</tt>.
1640 Whatever <tt>tmp</tt> directories are created and used by
1641 <prgn>binary</prgn> must of course be removed by the
1642 <prgn>clean</prgn> target.</p></sect1>
1646 <sect id="sourcearchives"><heading>Source packages as archives
1650 As it exists on the FTP site, a Debian source package
1651 consists of three related files. You must have the right
1652 versions of all three to be able to use them.
1657 <tag>Debian source control file - <tt>.dsc</tt></tag>
1661 This file contains a series of fields, identified and
1662 separated just like the fields in the control file of
1663 a binary package. The fields are listed below; their
1664 syntax is described above, in <ref id="controlfields">.
1665 <list compact="compact">
1667 <p><qref id="f-Source"><tt>Source</tt></qref></p>
1670 <p><qref id="versions"><tt>Version</tt></qref></p>
1673 <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
1676 <p><qref id="f-Binary"><tt>Binary</tt></qref></p>
1679 <p><qref id="f-Architecture"><tt>Architecture</tt></qref></p>
1683 <qref id="relationships"><tt>Build-Depends</tt> et
1684 al.</qref> (source package interrelationships)
1689 <qref id="f-Standards-Version"><tt>Standards-Version</tt></qref></p>
1692 <p><qref id="f-Files"><tt>Files</tt></qref></p>
1697 The source package control file is generated by
1698 <prgn>dpkg-source</prgn> when it builds the source
1699 archive, from other files in the source package,
1700 described above. When unpacking it is checked against
1701 the files and directories in the other parts of the
1702 source package, as described below.</p>
1706 Original source archive -
1708 <var>package</var>_<var>upstream-version</var>.orig.tar.gz
1715 This is a compressed (with <tt>gzip -9</tt>)
1716 <prgn>tar</prgn> file containing the source code from
1717 the upstream authors of the program. The tarfile
1718 unpacks into a directory
1719 <tt><var>package</var>-<var>upstream-version</var>.orig</tt>,
1720 and does not contain files anywhere other than in
1721 there or in its subdirectories.</p>
1725 Debianisation diff -
1727 <var>package</var>_<var>upstream_version-revision</var>.diff.gz
1733 This is a unified context diff (<tt>diff -u</tt>)
1734 giving the changes which are required to turn the
1735 original source into the Debian source. These changes
1736 may only include editing and creating plain files.
1737 The permissions of files, the targets of symbolic
1738 links and the characteristics of special files or
1739 pipes may not be changed and no files may be removed
1744 All the directories in the diff must exist, except the
1745 <tt>debian</tt> subdirectory of the top of the source
1746 tree, which will be created by
1747 <prgn>dpkg-source</prgn> if necessary when unpacking.
1751 The <prgn>dpkg-source</prgn> program will
1752 automatically make the <tt>debian/rules</tt> file
1753 executable (see below).</p></item>
1758 If there is no original source code - for example, if the
1759 package is specially prepared for Debian or the Debian
1760 maintainer is the same as the upstream maintainer - the
1761 format is slightly different: then there is no diff, and the
1763 <tt><var>package</var>_<var>version</var>.tar.gz</tt> and
1764 contains a directory
1765 <tt><var>package</var>-<var>version</var></tt>.
1769 <sect><heading>Unpacking a Debian source package without
1770 <prgn>dpkg-source</prgn>
1774 <tt>dpkg-source -x</tt> is the recommended way to unpack a
1775 Debian source package. However, if it is not available it
1776 is possible to unpack a Debian source archive as follows:
1777 <enumlist compact="compact">
1780 Untar the tarfile, which will create a <tt>.orig</tt>
1784 <p>Rename the <tt>.orig</tt> directory to
1785 <tt><var>package</var>-<var>version</var></tt>.</p>
1789 Create the subdirectory <tt>debian</tt> at the top of
1790 the source tree.</p>
1792 <item><p>Apply the diff using <tt>patch -p0</tt>.</p>
1794 <item><p>Untar the tarfile again if you want a copy of the original
1795 source code alongside the Debianised version.</p>
1800 It is not possible to generate a valid Debian source archive
1801 without using <prgn>dpkg-source</prgn>. In particular,
1802 attempting to use <prgn>diff</prgn> directly to generate the
1803 <tt>.diff.gz</tt> file will not work.
1806 <sect1><heading>Restrictions on objects in source packages
1810 The source package may not contain any hard links
1813 This is not currently detected when building source
1814 packages, but only when extracting
1820 Hard links may be permitted at some point in the
1821 future, but would require a fair amount of
1824 </footnote>, device special files, sockets or setuid or
1828 Setgid directories are allowed.
1834 The source packaging tools manage the changes between the
1835 original and Debianised source using <prgn>diff</prgn> and
1836 <prgn>patch</prgn>. Turning the original source tree as
1837 included in the <tt>.orig.tar.gz</tt> into the debianised
1838 source must not involve any changes which cannot be
1839 handled by these tools. Problematic changes which cause
1840 <prgn>dpkg-source</prgn> to halt with an error when
1841 building the source package are:
1842 <list compact="compact">
1843 <item><p>Adding or removing symbolic links, sockets or pipes.</p>
1845 <item><p>Changing the targets of symbolic links.</p>
1847 <item><p>Creating directories, other than <tt>debian</tt>.</p>
1849 <item><p>Changes to the contents of binary files.</p></item>
1850 </list> Changes which cause <prgn>dpkg-source</prgn> to
1851 print a warning but continue anyway are:
1852 <list compact="compact">
1855 Removing files, directories or symlinks.
1858 Renaming a file is not treated specially - it is
1859 seen as the removal of the old file (which
1860 generates a warning, but is otherwise ignored),
1861 and the creation of the new
1868 Changed text files which are missing the usual final
1869 newline (either in the original or the modified
1874 Changes which are not represented, but which are not detected by
1875 <prgn>dpkg-source</prgn>, are:
1876 <list compact="compact">
1877 <item><p>Changing the permissions of files (other than
1878 <tt>debian/rules</tt>) and directories.</p></item>
1883 The <tt>debian</tt> directory and <tt>debian/rules</tt>
1884 are handled specially by <prgn>dpkg-source</prgn> - before
1885 applying the changes it will create the <tt>debian</tt>
1886 directory, and afterwards it will make
1887 <tt>debian/rules</tt> world-exectuable.
1893 <chapt id="controlfields"><heading>Control files and their fields
1897 Many of the tools in the <prgn>dpkg</prgn> suite manipulate
1898 data in a common format, known as control files. Binary and
1899 source packages have control data as do the <tt>.changes</tt>
1900 files which control the installation of uploaded files, and
1901 <prgn>dpkg</prgn>'s internal databases are in a similar
1905 <sect><heading>Syntax of control files
1909 A file consists of one or more paragraphs of fields. The
1910 paragraphs are separated by blank lines. Some control files
1911 only allow one paragraph; others allow several, in which
1912 case each paragraph often refers to a different package.
1916 Each paragraph is a series of fields and values; each field
1917 consists of a name, followed by a colon and the value. It
1918 ends at the end of the line. Horizontal whitespace (spaces
1919 and tabs) may occur before or after the value and is ignored
1920 there; it is conventional to put a single space after the
1925 Some fields' values may span several lines; in this case
1926 each continuation line <em>must</em> start with a space or
1927 tab. Any trailing spaces or tabs at the end of individual
1928 lines of a field value are ignored.
1932 Except where otherwise stated only a single line of data is
1933 allowed and whitespace is not significant in a field body.
1934 Whitespace may never appear inside names (of packages,
1935 architectures, files or anything else), version numbers or
1936 in between the characters of multi-character version
1941 Field names are not case-sensitive, but it is usual to
1942 capitalise the field names using mixed case as shown below.
1946 Blank lines, or lines consisting only of spaces and tabs,
1947 are not allowed within field values or between fields - that
1948 would mean a new paragraph.
1952 It is important to note that there are several fields which
1953 are optional as far as <prgn>dpkg</prgn> and the related
1954 tools are concerned, but which must appear in every Debian
1955 package, or whose omission may cause problems. When writing
1956 the control files for Debian packages you <em>must</em> read
1957 the Debian policy manual in conjuction with the details
1958 below and the list of fields for the particular file.</p>
1961 <sect><heading>List of fields
1964 <sect1 id="f-Package"><heading><tt>Package</tt>
1968 The name of the binary package. Package names consist of
1969 the alphanumerics and <tt>+</tt> <tt>-</tt> <tt>.</tt>
1970 (plus, minus and full stop).
1973 The characters <tt>@</tt> <tt>:</tt> <tt>=</tt>
1974 <tt>%</tt> <tt>_</tt> (at, colon, equals, percent
1975 and underscore) used to be legal and are still
1976 accepted when found in a package file, but may not be
1977 used in new packages
1983 They must be at least two characters and must start with
1984 an alphanumeric. In current versions of dpkg they are
1985 sort of case-sensitive<footnote><p>This is a
1986 bug.</p></footnote>; use lowercase package names unless
1987 the package you're building (or referring to, in other
1988 fields) is already using uppercase.</p>
1991 <sect1 id="f-Version"><heading><tt>Version</tt>
1995 This lists the source or binary package's version number -
1996 see <ref id="versions">.
2001 <sect1 id="f-Architecture"><heading><tt>Architecture</tt>
2005 This is the architecture string; it is a single word for
2006 the Debian architecture.
2010 <prgn>dpkg</prgn> will check the declared architecture of
2011 a binary package against its own compiled-in value before
2016 The special value <tt>all</tt> indicates that the package
2017 is architecture-independent.
2021 In the main <tt>debian/control</tt> file in the source
2022 package, or in the source package control file
2023 <tt>.dsc</tt>, a list of architectures (separated by
2024 spaces) is also allowed, as is the special value
2025 <tt>any</tt>. A list indicates that the source will build
2026 an architecture-dependent package, and will only work
2027 correctly on the listed architectures. <tt>any</tt>
2028 indicates that though the source package isn't dependent
2029 on any particular architecture and should compile fine on
2030 any one, the binary package(s) produced are not
2031 architecture-independent but will instead be specific to
2032 whatever the current build architecture is.
2036 In a <tt>.changes</tt> file the <tt>Architecture</tt>
2037 field lists the architecture(s) of the package(s)
2038 currently being uploaded. This will be a list; if the
2039 source for the package is being uploaded too the special
2040 entry <tt>source</tt> is also present.
2044 See <ref id="debianrules"> for information how to get the
2045 architecture for the build process.
2049 <sect1 id="f-Maintainer"><heading><tt>Maintainer</tt>
2053 The package maintainer's name and email address. The name
2054 should come first, then the email address inside angle
2055 brackets <tt><></tt> (in RFC822 format).
2059 If the maintainer's name contains a full stop then the
2060 whole field will not work directly as an email address due
2061 to a misfeature in the syntax specified in RFC822; a
2062 program using this field as an address must check for this
2063 and correct the problem if necessary (for example by
2064 putting the name in round brackets and moving it to the
2065 end, and bringing the email address forward).
2069 In a <tt>.changes</tt> file or parsed changelog data this
2070 contains the name and email address of the person
2071 responsible for the particular version in question - this
2072 may not be the package's usual maintainer.
2076 This field is usually optional in as far as the
2077 <prgn>dpkg</prgn> are concerned, but its absence when
2078 building packages usually generates a warning.</p>
2081 <sect1 id="f-Source"><heading><tt>Source</tt>
2085 This field identifies the source package name.
2089 In a main source control information or a
2090 <tt>.changes</tt> or <tt>.dsc</tt> file or parsed
2091 changelog data this may contain only the name of the
2096 In the control file of a binary package (or in a
2097 <tt>Packages</tt> file) it may be followed by a version
2098 number in parentheses.
2101 It is usual to leave a space after the package name if
2102 a version number is specified.
2104 </footnote> This version number may be omitted (and is, by
2105 <prgn>dpkg-gencontrol</prgn>) if it has the same value as
2106 the <tt>Version</tt> field of the binary package in
2107 question. The field itself may be omitted from a binary
2108 package control file when the source package has the same
2109 name and version as the binary package.
2113 <sect1><heading>Package interrelationship fields:
2114 <tt>Depends</tt>, <tt>Pre-Depends</tt>,
2115 <tt>Recommends</tt> <tt>Suggests</tt>, <tt>Conflicts</tt>,
2116 <tt>Provides</tt>, <tt>Replaces</tt>
2120 These fields describe the package's relationships with
2121 other packages. Their syntax and semantics are described
2122 in <ref id="relationships">.</p>
2125 <sect1 id="f-Description"><heading><tt>Description</tt>
2129 In a binary package <tt>Packages</tt> file or main source
2130 control file this field contains a description of the
2131 binary package, in a special format. See <ref
2132 id="descriptions"> for details.
2136 In a <tt>.changes</tt> file it contains a summary of the
2137 descriptions for the packages being uploaded. The part of
2138 the field before the first newline is empty; thereafter
2139 each line has the name of a binary package and the summary
2140 description line from that binary package. Each line is
2141 indented by one space.</p>
2144 <sect1 id="f-Essential"><heading><tt>Essential</tt>
2148 This is a boolean field which may occur only in the
2149 control file of a binary package (or in the
2150 <tt>Packages</tt> file) or in a per-package fields
2151 paragraph of a main source control data file.
2155 If set to <tt>yes</tt> then <prgn>dpkg</prgn> and
2156 <prgn>dselect</prgn> will refuse to remove the package
2157 (though it can be upgraded and/or replaced). The other
2158 possible value is <tt>no</tt>, which is the same as not
2159 having the field at all.</p>
2162 <sect1 id="f-classification"><heading><tt>Section</tt> and
2167 These two fields classify the package. The
2168 <tt>Priority</tt> represents how important that it is that
2169 the user have it installed; the <tt>Section</tt>
2170 represents an application area into which the package has
2175 When they appear in the <tt>debian/control</tt> file these
2176 fields give values for the section and priority subfields
2177 of the <tt>Files</tt> field of the <tt>.changes</tt> file,
2178 and give defaults for the section and priority of the
2183 The section and priority are represented, though not as
2184 separate fields, in the information for each file in the
2185 <qref id="f-Files"><tt>-File</tt></qref>field of a
2186 <tt>.changes</tt> file. The section value in a
2187 <tt>.changes</tt> file is used to decide where to install
2188 a package in the FTP archive.
2192 These fields are not used by by <prgn>dpkg</prgn> proper,
2193 but by <prgn>dselect</prgn> when it sorts packages and
2194 selects defaults. See the Debian policy manual for the
2195 priorities in use and the criteria for selecting the
2196 priority for a Debian package, and look at the Debian FTP
2197 archive for a list of currently in-use priorities.
2201 These fields may appear in binary package control files,
2202 in which case they provide a default value in case the
2203 <tt>Packages</tt> files are missing the information.
2204 <prgn>dpkg</prgn> and <prgn>dselect</prgn> will only use
2205 the value from a <tt>.deb</tt> file if they have no other
2206 information; a value listed in a <tt>Packages</tt> file
2207 will always take precedence. By default
2208 <prgn>dpkg-gencontrol</prgn> does not include the section
2209 and priority in the control file of a binary package - use
2210 the <tt>-isp</tt>, <tt>-is</tt> or <tt>-ip</tt> options to
2211 achieve this effect.</p>
2214 <sect1 id="f-Binary"><heading><tt>Binary</tt>
2218 This field is a list of binary packages.
2222 When it appears in the <tt>.dsc</tt> file it is the list
2223 of binary packages which a source package can produce. It
2224 does not necessarily produce all of these binary packages
2225 for every architecture. The source control file doesn't
2226 contain details of which architectures are appropriate for
2227 which of the binary packages.
2231 When it appears in a <tt>.changes</tt> file it lists the
2232 names of the binary packages actually being uploaded.
2236 The syntax is a list of binary packages separated by
2240 A space after each comma is conventional.
2242 </footnote> Currently the packages must be separated using
2243 only spaces in the <tt>.changes</tt> file.</p>
2246 <sect1 id="f-Installed-Size"><heading><tt>Installed-Size</tt>
2250 This field appears in the control files of binary
2251 packages, and in the <tt>Packages</tt> files. It gives
2252 the total amount of disk space required to install the
2257 The disk space is represented in kilobytes as a simple
2261 <sect1 id="f-Files"><heading><tt>Files</tt>
2265 This field contains a list of files with information about
2266 each one. The exact information and syntax varies with
2267 the context. In all cases the the part of the field
2268 contents on the same line as the field name is empty. The
2269 remainder of the field is one line per file, each line
2270 being indented by one space and containing a number of
2271 sub-fields separated by spaces.
2275 In the <tt>.dsc</tt> (Debian source control) file each
2276 line contains the MD5 checksum, size and filename of the
2277 tarfile and (if applicable) diff file which make up the
2278 remainder of the source package.
2281 That is, the parts which are not the
2284 </footnote> The exact forms of the filenames are described
2285 in <ref id="sourcearchives">.
2289 In the <tt>.changes</tt> file this contains one line per
2290 file being uploaded. Each line contains the MD5 checksum,
2291 size, section and priority and the filename. The section
2292 and priority are the values of the corresponding fields in
2293 the main source control file - see <ref
2294 id="f-classification">. If no section or priority is
2295 specified then <tt>-</tt> should be used, though section
2296 and priority values must be specified for new packages to
2297 be installed properly.
2301 The special value <tt>byhand</tt> for the section in a
2302 <tt>.changes</tt> file indicates that the file in question
2303 is not an ordinary package file and must by installed by
2304 hand by the distribution maintainers. If the section is
2305 <tt>byhand</tt> the priority should be <tt>-</tt>.
2309 If a new Debian revision of a package is being shipped and
2310 no new original source archive is being distributed the
2311 <tt>.dsc</tt> must still contain the <tt>Files</tt> field
2312 entry for the original source archive
2313 <tt><var>package</var>-<var>upstream-version</var>.orig.tar.gz</tt>,
2314 but the <tt>.changes</tt> file should leave it out. In
2315 this case the original source archive on the distribution
2316 site must match exactly, byte-for-byte, the original
2317 source archive which was used to generate the
2318 <tt>.dsc</tt> file and diff which are being uploaded.</p>
2323 id="f-Standards-Version"><heading><tt>Standards-Version</tt>
2327 The most recent version of the standards (the
2328 <prgn>dpkg</prgn> programmers' and policy manuals and
2329 associated texts) with which the package complies. This
2330 is updated manually when editing the source package to
2331 conform to newer standards; it can sometimes be used to
2332 tell when a package needs attention.
2336 Its format is the same as that of a version number except
2337 that no epoch or Debian revision is allowed - see <ref
2342 <sect1 id="f-Distribution"><heading><tt>Distribution</tt>
2346 In a <tt>.changes</tt> file or parsed changelog output
2347 this contains the (space-separated) name(s) of the
2348 distribution(s) where this version of the package should
2349 be or was installed. Distribution names follow the rules
2350 for package names. (See <ref id="f-Package">).
2354 Current distribution values are:
2356 <tag><em>stable</em></tag>
2359 This is the current `released' version of Debian
2360 GNU/Linux. A new version is released approximately
2361 every 3 months after the <em>development</em> code has
2362 been <em>frozen</em> for a month of testing. Once the
2363 distribution is <em>stable</em> only major bug fixes
2364 are allowed. When changes are made to this
2365 distribution, the release number is increased
2366 (for example: 1.2r1 becomes 1.2r2 then 1.2r3, etc).
2370 <tag><em>unstable</em></tag>
2373 This distribution value refers to the
2374 <em>developmental</em> part of the Debian distribution
2375 tree. New packages, new upstream versions of packages
2376 and bug fixes go into the <em>unstable</em> directory
2377 tree. Download from this distribution at your own
2381 <tag><em>contrib</em></tag>
2384 The packages with this distribution value do not meet
2385 the criteria for inclusion in the main Debian
2386 distribution as defined by the Policy Manual, but meet
2387 the criteria for the <em>contrib</em>
2388 Distribution. There is currently no distinction
2389 between stable and unstable packages in the
2390 <em>contrib</em> or <em>non-free</em>
2391 distributions. Use your best judgement in downloading
2392 from this Distribution.</p>
2395 <tag><em>non-free</em></tag>
2398 Like the packages in the <em>contrib</em> seciton,
2399 the packages in <em>non-free</em> do not meet the
2400 criteria for inclusion in the main Debian distribution
2401 as defined by the Policy Manual. Again, use your best
2402 judgement in downloading from this Distribution.</p>
2404 <tag><em>experimental</em></tag>
2407 The packages with this distribution value are deemed
2408 by their maintainers to be high risk. Oftentimes they
2409 represent early beta or developmental packages from
2410 various sources that the maintainers want people to
2411 try, but are not ready to be a part of the other parts
2412 of the Debian distribution tree. Download at your own
2416 <tag><em>frozen</em></tag>
2419 From time to time, (currently, every 3 months) the
2420 <em>unstable</em> distribution enters a state of
2421 `code-freeze' in anticipation of release as a
2422 <em>stable</em> version. During this period of testing
2423 (usually 4 weeks) only fixes for existing or
2424 newly-discovered bugs will be allowed.
2427 </taglist> You should list <em>all</em> distributions that
2428 the package should be installed into. Except in unusual
2429 circumstances, installations to <em>stable</em> should also
2430 go into <em>frozen</em> (if it exists) and
2431 <em>unstable</em>. Likewise, installations into
2432 <em>frozen</em> should also go into <em>unstable</em>.</p>
2435 <sect1 id="f-Urgency"><heading><tt>Urgency</tt>
2439 This is a description of how important it is to upgrade to
2440 this version from previous ones. It consists of a single
2441 keyword usually taking one of the values <tt>LOW</tt>,
2442 <tt>MEDIUM</tt> or <tt>HIGH</tt>) followed by an optional
2443 commentary (separated by a space) which is usually in
2444 parentheses. For example:
2446 Urgency: LOW (HIGH for diversions users)
2451 This field appears in the <tt>.changes</tt> file and in
2452 parsed changelogs; its value appears as the value of the
2453 <tt>urgency</tt> attribute in a <prgn>dpkg</prgn>-style
2454 changelog (see <ref id="dpkgchangelog">).
2458 Urgency keywords are not case-sensitive.</p>
2461 <sect1 id="f-Date"><heading><tt>Date</tt>
2465 In <tt>.changes</tt> files and parsed changelogs, this
2466 gives the date the package was built or last edited.</p>
2469 <sect1 id="f-Format"><heading><tt>Format</tt>
2473 This field occurs in <tt>.changes</tt> files, and
2474 specifies a format revision for the file. The format
2475 described here is version <tt>1.5</tt>. The syntax of the
2476 format value is the same as that of a package version
2477 number except that no epoch or Debian revision is allowed
2478 - see <ref id="versions">.</p>
2481 <sect1 id="f-Changes"><heading><tt>Changes</tt>
2485 In a <tt>.changes</tt> file or parsed changelog this field
2486 contains the human-readable changes data, describing the
2487 differences between the last version and the current one.
2491 There should be nothing in this field before the first
2492 newline; all the subsequent lines must be indented by at
2493 least one space; blank lines must be represented by a line
2494 consiting only of a space and a full stop.
2498 Each version's change information should be preceded by a
2499 `title' line giving at least the version, distribution(s)
2500 and urgency, in a human-readable way.
2504 If data from several versions is being returned the entry
2505 for the most recent version should be returned first, and
2506 entries should be separated by the representation of a
2507 blank line (the `title' line may also be followed by the
2508 representation of blank line).</p>
2511 <sect1 id="f-Filename"><heading><tt>Filename</tt> and
2512 <tt>MSDOS-Filename</tt>
2516 These fields in <tt>Packages</tt> files give the
2517 filename(s) of (the parts of) a package in the
2518 distribution directories, relative to the root of the
2519 Debian hierarchy. If the package has been split into
2520 several parts the parts are all listed in order, separated
2524 <sect1 id="f-Size"><heading><tt>Size</tt> and <tt>MD5sum</tt>
2528 These fields in <tt>Packages</tt> files give the size (in
2529 bytes, expressed in decimal) and MD5 checksum of the
2530 file(s) which make(s) up a binary package in the
2531 distribution. If the package is split into several parts
2532 the values for the parts are listed in order, separated by
2536 <sect1 id="f-Status"><heading><tt>Status</tt>
2540 This field in <prgn>dpkg</prgn>'s status file records
2541 whether the user wants a package installed, removed or
2542 left alone, whether it is broken (requiring
2543 reinstallation) or not and what its current state on the
2544 system is. Each of these pieces of information is a
2548 <sect1 id="f-Config-Version"><heading><tt>Config-Version</tt>
2552 If a package is not installed or not configured, this
2553 field in <prgn>dpkg</prgn>'s status file records the last
2554 version of the package which was successfully
2558 <sect1 id="f-Conffiles"><heading><tt>Conffiles</tt>
2562 This field in <prgn>dpkg</prgn>'s status file contains
2563 information about the automatically-managed configuration
2564 files held by a package. This field should <em>not</em>
2565 appear anywhere in a package!</p>
2568 <sect1><heading>Obsolete fields
2572 These are still recognised by <prgn>dpkg</prgn> but should
2573 not appear anywhere any more.
2574 <taglist compact="compact">
2576 <tag><tt>Revision</tt></tag>
2577 <tag><tt>Package-Revision</tt></tag>
2578 <tag><tt>Package_Revision</tt></tag>
2581 The Debian revision part of the package version was
2582 at one point in a separate control file field. This
2583 field went through several names.</p>
2586 <tag><tt>Recommended</tt></tag>
2587 <item><p>Old name for <tt>Recommends</tt></p>
2590 <tag><tt>Optional</tt></tag>
2591 <item><p>Old name for <tt>Suggests</tt>.</p>
2593 <tag><tt>Class</tt></tag>
2594 <item><p>Old name for <tt>Priority</tt>.</p>
2602 <chapt id="versions"><heading>Version numbering
2606 Every package has a version number, in its <tt>Version</tt>
2611 <prgn>dpkg</prgn> imposes an ordering on version numbers, so
2612 that it can tell whether packages are being up- or downgraded
2613 and so that <prgn>dselect</prgn> can tell whether a package it
2614 finds available is newer than the one installed on the system.
2615 The version number format has the most significant parts (as
2616 far as comparison is concerned) at the beginning.
2620 The version number format is:
2621 &lsqb<var>epoch/<tt>:</tt>]<var>upstream-version</var>[<tt>-/<var>debian-revision</var>].</tt></var>
2625 The three components here are:
2627 <tag><var>epoch</var></tag>
2631 This is a single unsigned integer, which should usually
2632 be small. It may be omitted, in which case zero is
2633 assumed. If it is omitted then the
2634 <var>upstream-version</var> may not contain any colons.
2638 It is provided to allow mistakes in the version numbers
2639 of older versions of a package, and also a package's
2640 previous version numbering schemes, to be left behind.
2644 <prgn>dpkg</prgn> will not usually display the epoch
2645 unless it is essential (non-zero, or if the
2646 <var>upstream-version</var> contains a colon);
2647 <prgn>dselect</prgn> does not display epochs at all in
2648 the main part of the package selection display.</p>
2651 <tag><var>upstream-version</var></tag>
2655 This is the main part of the version. It is usually
2656 version number of the original (`upstream') package of
2657 which the <tt>.deb</tt> file has been made, if this is
2658 applicable. Usually this will be in the same format as
2659 that specified by the upstream author(s); however, it
2660 may need to be reformatted to fit into
2661 <prgn>dpkg</prgn>'s format and comparison scheme.
2665 The comparison behaviour of <prgn>dpkg</prgn> with
2666 respect to the <var>upstream-version</var> is described
2667 below. The <var>upstream-version</var> portion of the
2668 version number is mandatory.
2672 The <var>upstream-version</var> may contain only
2673 alphanumerics and the characters <tt>.</tt> <tt>+</tt>
2674 <tt>-</tt> <tt>:</tt> (full stop, plus, hyphen, colon)
2675 and should start with a digit. If there is no
2676 <var>debian-revision</var> then hyphens are not allowed;
2677 if there is no <var>epoch</var> then colons are not
2681 <tag><var>debian-revision</var></tag>
2685 This part of the version represents the version of the
2686 modifications that were made to the package to make it a
2687 Debian binary package. It is in the same format as the
2688 <var>upstream-version</var> and <prgn>dpkg</prgn>
2689 compares it in the same way.
2693 It is optional; if it isn't present then the
2694 <var>upstream-version</var> may not contain a hyphen.
2695 This format represents the case where a piece of
2696 software was written specifically to be turned into a
2697 Debian binary package, and so there is only one
2698 `debianization' of it and therefore no revision
2699 indication is required.
2703 It is conventional to restart the
2704 <var>debian-revision</var> at <tt>1</tt> each time the
2705 <var>upstream-version</var> is increased.
2709 <prgn>dpkg</prgn> will break the
2710 <var>upstream-version</var> and
2711 <var>debian-revision</var> apart at the last hyphen in
2712 the string. The absence of a <var>debian-revision</var>
2713 compares earlier than the presence of one (but note that
2714 the <var>debian-revision</var> is the least significant
2715 part of the version number).
2719 The <var>debian-revision</var> may contain only
2720 alphanumerics and the characters <tt>+</tt> and
2721 <tt>.</tt> (plus and full stop).
2725 The <var>upstream-version</var> and <var>debian-revision</var> parts are
2726 compared by <prgn>dpkg</prgn> using the same algorithm:
2730 The strings are compared from left to right.
2734 First the initial part of each string consisting entirely of
2735 non-digit characters is determined. These two parts (one of
2736 which may be empty) are compared lexically. If a difference
2737 is found it is returned. The lexical comparison is a
2738 comparison of ASCII values modified so that all the letters
2739 sort earlier than all the non-letters.
2743 Then the initial part of the remainder of each string which
2744 consists entirely of digit characters is determined. The
2745 numerical values of these two parts are compared, and any
2746 difference found is returned as the result of the comparison.
2747 For these purposes an empty string (which can only occur at
2748 the end of one or both version strings being compared) counts
2753 These two steps are repeated (chopping initial non-digit
2754 strings and initial digit strings off from the start) until a
2755 difference is found or both strings are exhausted.
2759 Note that the purpose of epochs is to allow us to leave behind
2760 mistakes in version numbering, and to cope with situations
2761 where the version numbering changes. It is <em>not</em> there
2762 to cope with version numbers containing strings of letters
2763 which <prgn>dpkg</prgn> cannot interpret (such as
2764 <tt>ALPHA</tt> or <tt>pre-</tt>), or with silly orderings (the
2765 author of this manual has heard of a package whose versions
2766 went <tt>1.1</tt>, <tt>1.2</tt>, <tt>1.3</tt>, <tt>1</tt>,
2767 <tt>2.1</tt>, <tt>2.2</tt>, <tt>2</tt> and so forth).
2771 If an upstream package has problematic version numbers they
2772 should be converted to a sane form for use in the
2773 <tt>Version</tt> field.
2777 If you need to compare version numbers in a script, you may use
2778 <tt>dpkg --compare-versions ...</tt>. Type <tt>dpkg
2779 --help</tt> for details on arguments.
2783 <heading>Version numbers based on dates</heading>
2785 In general, Debian packages should use the same version
2786 numbers as the upstream sources.</p>
2789 However, in some cases where the upstream version number is
2790 based on a date (e.g., a development `snapshot' release)
2791 dpkg cannot handle these version numbers currently, without
2792 epochs. For example, dpkg will consider `96May01' to be
2793 greater than `96Dec24'.</p>
2796 To prevent having to use epochs for every new upstream
2797 version, the version number should be changed to the
2798 following format in such cases: `19960501', `19961224'. It
2799 is up to the maintainer whether he/she wants to bother the
2800 upstream maintainer to change the version numbers upstream,
2804 Note, that other version formats based on dates which are
2805 parsed correctly by dpkg should <em>not</em> be changed.</p>
2808 Native Debian packages (i.e., packages which have been
2809 written especially for Debian) whose version numbers include
2810 dates should always use the `YYYYMMDD' format.</p>
2814 <chapt id="maintainerscripts"><heading>Package maintainer scripts
2815 and installation procedure
2818 <sect><heading>Introduction to package maintainer scripts
2822 It is possible to supply scripts as part of a package which
2823 <prgn>dpkg</prgn> will run for you when your package is
2824 installed, upgraded or removed.
2828 These scripts should be the files <tt>preinst</tt>,
2829 <tt>postinst</tt>, <tt>prerm</tt> and <tt>postrm</tt> in the
2830 control area of the package. They must be proper exectuable
2831 files; if they are scripts (which is recommended) they must
2832 start with the usual <tt>#!</tt> convention. They should be
2833 readable and executable to anyone, and not world-writeable.
2837 <prgn>dpkg</prgn> looks at the exit status from these
2838 scripts. It is important that they exit with a non-zero
2839 status if there is an error, so that <prgn>dpkg</prgn> can
2840 stop its processing. For shell scripts this means that you
2841 <em>almost always</em> need to use <tt>set -e</tt> (this is
2842 usually true when writing shell scripts, in fact). It is
2843 also important, of course, that they don't exit with a
2844 non-zero status if everything went well.
2848 It is necessary for the error recovery procedures that the
2849 scripts be idempotent: ie, invoking the same script several
2850 times in the same situation should do no harm. If the first
2851 call failed, or aborted half way through for some reason,
2852 the second call should merely do the things that were left
2853 undone the first time, if any, and exit with a success
2858 When a package is upgraded a combination of the scripts from
2859 the old and new packages is called in amongst the other
2860 steps of the upgrade procedure. If your scripts are going
2861 to be at all complicated you need to be aware of this, and
2862 may need to check the arguments to your scripts.
2866 Broadly speaking the <prgn>preinst</prgn> is called before
2867 (a particular version of) a package is installed, and the
2868 <prgn>postinst</prgn> afterwards; the <prgn>prerm</prgn>
2869 before (a version of) a package is removed and the
2870 <prgn>postrm</prgn> afterwards.
2873 next paragraph by Guy Maor to close bug #2481
2876 <p> Programs called from maintainer scripts should not
2877 normally have a path prepended to them. Before installation
2878 is started <prgn>dpkg</prgn> checks to see if the programs
2879 <prgn>ldconfig</prgn>, <prgn>start-stop-daemon</prgn>,
2880 <prgn>install-info</prgn>, and <prgn>update-rc.d</prgn> can
2881 be found via the <tt>PATH</tt> environment variable. Those
2882 programs, and any other program that one would expect to on
2883 the <tt>PATH</tt>, should thus be invoked without an
2884 absolute pathname. Maintainer scripts should also not reset
2885 the <tt>PATH</tt>, though they might choose to modify it by
2886 pre- or appending package-specific directories. These
2887 considerations really apply to all shell scripts.</p>
2890 <sect id="mscriptsinstact"><heading>Summary of ways maintainer
2895 <list compact="compact">
2897 <p><var>new-preinst</var> <tt>install</tt></p>
2900 <p><var>new-preinst</var> <tt>install</tt>
2901 <var>old-version</var></p>
2904 <p><var>new-preinst</var> <tt>upgrade</tt>
2905 <var>old-version</var></p>
2908 <p><var>old-preinst</var> <tt>abort-upgrade</tt>
2909 <var>new-version</var>
2915 <list compact="compact">
2917 <p><var>postinst</var> <tt>configure</tt>
2918 <var>most-recently-configured-version</var></p>
2921 <p><var>old-postinst</var> <tt>abort-upgrade</tt>
2922 <var>new version</var></p>
2925 <p><var>conflictor's-postinst</var> <tt>abort-remove</tt>
2926 <tt>in-favour</tt> <var>package</var>
2927 <var>new-version</var></p>
2931 <var>deconfigured's-postinst</var>
2932 <tt>abort-deconfigure</tt> <tt>in-favour</tt>
2933 <var>failed-install-package</var> <var>version</var>
2934 <tt>removing</tt> <var>conflicting-package</var>
2941 <list compact="compact">
2943 <p><var>prerm</var> <tt>remove</tt></p>
2946 <p><var>old-prerm</var> <tt>upgrade</tt>
2947 <var>new-version</var></p>
2950 <p><var>new-prerm</var> <tt>failed-upgrade</tt>
2951 <var>old-version</var></p>
2954 <p><var>conflictor's-prerm</var> <tt>remove</tt>
2955 <tt>in-favour</tt> <var>package</var>
2956 <var>new-version</var></p>
2960 <var>deconfigured's-prerm</var> <tt>deconfigure</tt>
2961 <tt>in-favour</tt> <var>package-being-installed</var>
2962 <var>version</var> <tt>removing</tt>
2963 <var>conflicting-package</var>
2970 <list compact="compact">
2972 <p><var>postrm</var> <tt>remove</tt></p>
2975 <p><var>postrm</var> <tt>purge</tt></p>
2979 <var>old-postrm</var> <tt>upgrade</tt>
2980 <var>new-version</var></p>
2983 <p><var>new-postrm</var> <tt>failed-upgrade</tt>
2984 <var>old-version</var></p>
2987 <p><var>new-postrm</var> <tt>abort-install</tt></p>
2990 <p><var>new-postrm</var> <tt>abort-install</tt>
2991 <var>old-version</var></p>
2994 <p><var>new-postrm</var> <tt>abort-upgrade</tt>
2995 <var>old-version</var></p>
2999 <var>disappearer's-postrm</var> <tt>disappear</tt>
3000 <var>overwriter</var>
3001 <var>overwriter-version</var></p></item>
3006 <sect id="unpackphase"><heading>Details of unpack phase of
3007 installation or upgrade
3011 The procedure on installation/upgrade/overwrite/disappear
3012 (ie, when running <tt>dpkg --unpack</tt>, or the unpack
3014 --install</tt>) is as follows. In each case if an error occurs the
3015 actions in are general run backwards - this means that the maintainer
3016 scripts are run with different arguments in reverse order. These are
3017 the `error unwind' calls listed below.
3024 <p>If a version the package is already
3027 <var>old-prerm</var> upgrade <var>new-version</var>
3032 If this gives an error (ie, a non-zero exit
3033 status), dpkg will attempt instead:
3035 <var>new-prerm</var> failed-upgrade <var>old-version</var>
3037 Error unwind, for both the above cases:
3039 <var>old-postinst</var> abort-upgrade <var>new-version</var>
3047 <p>If a `conflicting' package is being removed at the same time:
3051 If any packages depended on that conflicting
3052 package and <tt>--auto-deconfigure</tt> is
3053 specified, call, for each such package:
3055 <var>deconfigured's-prerm</var> deconfigure \
3056 in-favour <var>package-being-installed</var> <var>version</var> \
3057 removing <var>conflicting-package</var> <var>version</var>
3061 <var>deconfigured's-postinst</var> abort-deconfigure \
3062 in-favour <var>package-being-installed-but-failed</var> <var>version</var> \
3063 removing <var>conflicting-package</var> <var>version</var>
3065 The deconfigured packages are marked as
3066 requiring configuration, so that if
3067 <tt>--install</tt> is used they will be
3068 configured again if possible.</p>
3071 <p>To prepare for removal of the conflicting package, call:
3073 <var>conflictor's-prerm</var> remove in-favour <var>package</var> <var>new-version</var>
3077 <var>conflictor's-postinst</var> abort-remove \
3078 in-favour <var>package</var> <var>new-version</var>
3089 <p>If the package is being upgraded, call:
3091 <var>new-preinst</var> upgrade <var>old-version</var>
3096 Otherwise, if the package had some configuration
3097 files from a previous version installed (ie, it
3098 is in the `configuration files only' state):
3100 <var>new-preinst</var> install <var>old-version</var>
3104 <p>Otherwise (ie, the package was completely purged):
3106 <var>new-preinst</var> install
3108 Error unwind versions, respectively:
3110 <var>new-postrm</var> abort-upgrade <var>old-version</var>
3111 <var>new-postrm</var> abort-install <var>old-version</var>
3112 <var>new-postrm</var> abort-install
3122 The new package's files are unpacked, overwriting any
3123 that may be on the system already, for example any
3124 from the old version of the same package or from
3125 another package (backups of the old files are left
3126 around, and if anything goes wrong dpkg will attempt
3127 to put them back as part of the error unwind).
3131 It is an error for a package to contains files which
3132 are on the system in another package, unless
3133 <tt>Replaces</tt> is used (see <ref id="replaces">).
3134 Currently the <tt>--force-overwrite</tt> flag is
3135 enabled, downgrading it to a warning, but this may not
3140 It is a more serious error for a package to contain a
3141 plain file or other kind of nondirectory where another
3142 package has a directory (again, unless
3143 <tt>Replaces</tt> is used). This error can be
3144 overridden if desired using
3145 <tt>--force-overwrite-dir</tt>, but this is not
3150 Packages which overwrite each other's files produce
3151 behaviour which though deterministic is hard for the
3152 system administrator to understand. It can easily
3153 lead to `missing' programs if, for example, a package
3154 is installed which overwrites a file from another
3155 package, and is then removed again.
3158 Part of the problem is due to what is arguably a
3159 bug in <prgn>dpkg</prgn>.
3165 A directory will never be replaced by a symbolic links
3166 to a directory or vice versa; instead, the existing
3167 state (symlink or not) will be left alone and
3168 <prgn>dpkg</prgn> will follow the symlink if there is
3176 <p>If the package is being upgraded, call
3178 <var>old-postrm</var> upgrade <var>new-version</var>
3182 <p>If this fails, <prgn>dpkg</prgn> will attempt:
3184 <var>new-postrm</var> failed-upgrade <var>old-version</var>
3186 Error unwind, for both cases:
3188 <var>old-preinst</var> abort-upgrade <var>new-version</var>
3193 This is the point of no return - if <prgn>dpkg</prgn>
3194 gets this far, it won't back off past this point if an
3195 error occurs. This will leave the package in a fairly
3196 bad state, which will require a successful
3197 reinstallation to clear up, but it's when
3198 <prgn>dpkg</prgn> starts doing things that are
3203 Any files which were in the old version of the package
3204 but not in the new are removed.</p>
3207 <p>The new file list replaces the old.</p>
3210 <p>The new maintainer scripts replace the old.</p>
3214 <p>Any packages all of whose files have been overwritten during the
3215 installation, and which aren't required for
3216 dependencies, are considered to have been removed.
3217 For each such package,
3220 <p><prgn>dpkg</prgn> calls:
3222 <var>disappearer's-postrm</var> disappear \
3223 <var>overwriter</var> <var>overwriter-version</var>
3228 <p>The package's maintainer scripts are removed.
3233 It is noted in the status database as being in a
3234 sane state, namely not installed (any conffiles
3235 it may have are ignored, rather than being
3236 removed by <prgn>dpkg</prgn>). Note that
3237 disappearing packages do not have their prerm
3238 called, because <prgn>dpkg</prgn> doesn't know
3239 in advance that the package is going to
3248 Any files in the package we're unpacking that are also
3249 listed in the file lists of other packages are removed
3250 from those lists. (This will lobotomise the file list
3251 of the `conflicting' package if there is one.)
3256 The backup files made during installation, above, are
3263 The new package's status is now sane, and recorded as
3264 `unpacked'. Here is another point of no return - if
3265 the conflicting package's removal fails we do not
3266 unwind the rest of the installation; the conflicting
3267 package is left in a half-removed limbo.
3272 If there was a conflicting package we go and do the
3273 removal actions (described below), starting with the
3274 removal of the conflicting package's files (any that
3275 are also in the package being installed have already
3276 been removed from the conflicting package's file list,
3277 and so do not get removed now).
3284 <sect><heading>Details of configuration
3288 When we configure a package (this happens with <tt>dpkg
3289 --install</tt>, or with <tt>--configure</tt>), we first
3290 update the conffiles and then call:
3292 <var>postinst</var> configure <var>most-recently-configured-version</var>
3297 No attempt is made to unwind after errors during
3302 If there is no most recently configured version
3303 <prgn>dpkg</prgn> will pass a null argument; older versions
3304 of dpkg may pass <tt><unknown></tt> (including the
3305 angle brackets) in this case. Even older ones do not pass a
3306 second argument at all, under any circumstances.
3310 <sect><heading>Details of removal and/or configuration purging
3318 <var>prerm</var> remove
3324 The package's files are removed (except conffiles).
3329 <var>postrm</var> remove
3333 <p>All the maintainer scripts except the postrm are removed.
3337 If we aren't purging the package we stop here. Note
3338 that packages which have no postrm and no conffiles
3339 are automatically purged when removed, as there is no
3340 difference except for the <prgn>dpkg</prgn>
3345 The conffiles and any backup files (<tt>~</tt>-files,
3346 <tt>#*#</tt> files, <tt>%</tt>-files,
3347 <tt>.dpkg-{old,new,tmp}</tt>, etc.) are removed.</p>
3351 <var>postrm</var> purge
3355 <p>The package's file list is removed.</p>
3358 No attempt is made to unwind after errors during
3363 <chapt id="descriptions"><heading>Descriptions of packages - the
3364 <tt>Description</tt> field
3368 The <tt>Description</tt> control file field is used by
3369 <prgn>dselect</prgn> when the user is selecting which packages
3370 to install and by <prgn>dpkg</prgn> when it displays
3371 information about the status of packages and so forth. It is
3372 included on the FTP site in the <prgn>Packages</prgn> files,
3373 and may also be used by the Debian WWW pages.
3377 The description is intended to describe the program to a user
3378 who has never met it before so that they know whether they
3379 want to install it. It should also give information about the
3380 significant dependencies and conflicts between this package
3381 and others, so that the user knows why these dependencies and
3382 conflicts have been declared.
3386 The field's format is as follows:
3388 Description: <var>single line synopsis</var>
3389 <var>extended description over several lines</var>
3394 The synopsis is often printed in lists of packages and so
3395 forth, and should be as informative as possible. Every
3396 package should also have an extended description.
3399 <sect><heading>Types of formatting line in the extended
3407 Those starting with a single space are part of a
3408 paragraph. Successive lines of this form will be
3409 word-wrapped when displayed. The leading space will
3410 usually be stripped off.
3416 Those starting with two or more spaces. These will be
3417 displayed verbatim. If the display cannot be panned
3418 horizontally the displaying program will linewrap them
3419 `hard' (ie, without taking account of word breaks).
3420 If it can they will be allowed to trail off to the
3421 right. None, one or two initial spaces may be
3422 deleted, but the number of spaces deleted from each
3423 line will be the same (so that you can have indenting
3424 work correctly, for example).
3429 <p>Those containing a single space followed by a single full stop
3430 character. These are rendered as blank lines. This
3431 is the <em>only</em> way to get a blank line - see
3437 Those containing a space, a full stop and some more
3438 characters. These are for future expansion. Do not
3445 <sect><heading>Notes about writing descriptions
3449 <em>Always</em> start extended description lines with at least one
3450 whitespace character. Fields in the control file and in the Packages
3451 file are separated by field names starting in the first column, just
3452 as message header fields are in RFC822. Forgetting the whitespace
3453 will cause <prgn>dpkg-deb</prgn>
3456 Version 0.93.23 or later.
3458 </footnote> to produce a syntax error when trying to build
3459 the package. If you force it to build anyway
3460 <prgn>dpkg</prgn> will refuse to install the resulting
3465 <em>Do not</em> include any completely <em>empty</em>
3466 lines. These separate different records in the Packages file
3467 and different packages in the <tt>debian/control</tt> file,
3468 and are forbidden in package control files. See the
3469 previous paragraph for what happens if you get this wrong.
3473 The single line synopsis should be kept brief - certainly
3474 under 80 characters. <prgn>dselect</prgn> displays between
3475 25 and 49 characters without panning if you're using an
3476 80-column terminal, depending on what display options are in
3481 Do not include the package name in the synopsis line. The
3482 display software knows how to display this already, and you
3483 do not need to state it. Remember that in many situations
3484 the user may only see the synopsis line - make it as
3485 informative as you can.
3489 The extended description should describe what the package
3490 does and how it relates to the rest of the system (in terms
3491 of, for example, which subsystem it is which part of).
3495 The blurb that comes with a program in its announcements
3496 and/or <prgn>README</prgn> files is rarely suitable for use
3497 in a description. It is usually aimed at people who are
3498 already in the community where the package is used. The
3499 description field needs to make sense to anyone, even people
3500 who have no idea about any of the things the package deals
3505 Put important information first, both in the synopis and
3506 extended description. Sometimes only the first part of the
3507 synopsis or of the description will be displayed. You can
3508 assume that there will usually be a way to see the whole
3509 extended description.
3513 You may include information about dependencies and so forth
3514 in the extended description, if you wish.
3518 Do not use tab characters. Their effect is not predictable.
3522 Do not try to linewrap the summary (the part on the same
3523 line as the field name <tt>Description</tt>) into the
3524 extended description. This will not work correctly when the
3525 full description is displayed, and makes no sense where only
3526 the summary is available.</p>
3529 <sect><heading>Example description in control file for Smail
3535 Version: 3.1.29.1-13
3536 Maintainer: Ian Jackson <iwj10@cus.cam.ac.uk>
3537 Recommends: pine | mailx | elm | emacs | mail-user-agent
3539 Depends: cron, libc5
3541 Provides: mail-transport-agent
3542 Description: Electronic mail transport system.
3543 Smail is the recommended mail transport agent (MTA) for Debian.
3545 An MTA is the innards of the mail system - it takes messages from
3546 user-friendly mailer programs and arranges for them to be delivered
3547 locally or passed on to other systems as required.
3549 In order to make use of it you must have one or more user level
3550 mailreader programs such as elm, pine, mailx or Emacs (which has Rmail
3551 and VM as mailreaders) installed. If you wish to send messages other
3552 than just to other users of your system you must also have appropriate
3553 networking support, in the form of IP or UUCP.
3559 <chapt id="relationships"><heading>Declaring relationships between
3564 Packages can declare in their control file that they have
3565 certain relationships to other packages - for example, that
3566 they may not be installed at the same time as certain other
3567 packages, and/or that they depend on the presence of others,
3568 or that they should overwrite files in certain other packages
3573 This is done using the <tt>Depends</tt>, <tt>Recommends</tt>,
3574 <tt>Suggests</tt>, <tt>Conflicts</tt>, <tt>Provides</tt> and
3575 <tt>Replaces</tt> control file fields.
3579 Source packages may declare relationships to binary packages,
3580 saying that they require certain binary packages being
3581 installed or absent at the time of building the package.
3585 This is done using the <tt>Build-Depends</tt>,
3586 <tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt>, and
3587 <tt>Build-Conflicts-Indep</tt> control file fields.
3590 <sect id="depsyntax"><heading>Syntax of relationship fields
3594 These fields all have a uniform syntax. They are a list of
3595 package names separated by commas.
3599 In <tt>Depends</tt>, <tt>Recommends</tt>, <tt>Suggests</tt>,
3600 <tt>Pre-Depends</tt>, <tt>Build-Depends</tt> and
3601 <tt>Build-Depends-Indep</tt>(the fields which declare
3602 dependencies of the package in which they occur on other
3603 packages) these package names may also be lists of
3604 alternative package names, separated by vertical bar symbols
3605 <tt>|</tt> (pipe symbols).
3609 All the fields except <tt>Provides</tt> may restrict their
3610 applicability to particular versions of each named package.
3611 This is done in parentheses after each individual package
3612 name; the parentheses should contain a relation from the
3613 list below followed by a version number, in the format
3614 described in <ref id="versions">.
3618 The relations allowed are <tt><<</tt>, <tt><=</tt>,
3619 <tt>=</tt>, <tt>>=</tt> and <tt>>></tt> for
3620 strictly earlier, earlier or equal, exactly equal, later or
3621 equal and strictly later, respectively. The forms
3622 <tt><</tt> and <tt>></tt> were used to mean
3623 earlier/later or equal, rather than strictly earlier/later,
3624 so they should not appear in new packages (though
3625 <prgn>dpkg</prgn> still supports them).
3629 Whitespace may appear at any point in the version
3630 specification, and must appear where it's necessary to
3631 disambiguate; it is not otherwise significant. For
3632 consistency and in case of future changes to
3633 <prgn>dpkg</prgn> it is recommended that a single space be
3634 used after a version relationship and before a version
3635 number; it is usual also to put a single space after each
3636 comma, on either side of each vertical bar, and before each
3645 Depends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh
3650 All fields that specify build-time relationships
3651 (<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
3652 <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>)
3653 may be restricted to a certain set of architectures. This
3654 is done in brackets after each individual package name and
3655 the optional version specification. The brackets enclose a
3656 list of Debian architecture names separated by whitespace.
3657 An exclamation mark may be prepended to each name. If the
3658 current Debian host architecture is not in this list and
3659 there are no exclamation marks in the list, or it is in the
3660 list with a prepended exclamation mark, the package name and
3661 the associated version specification are ignored completely
3662 for the purposes of defining the relationships.
3669 Build-Depends-Indep: texinfo
3670 Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
3671 hurd-dev [hurd-i386], gnumach-dev [hurd-i386]
3677 <heading>Binary Dependencies - <tt>Depends</tt>,
3678 <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Pre-Depends</tt>
3682 These four fields are used to declare a dependency by one
3683 package on another. They appear in the depending package's
3688 All but <tt>Pre-Depends</tt> (discussed below) take effect
3689 <em>only</em> when a package is to be configured. They do
3690 not prevent a package being on the system in an unconfigured
3691 state while its dependencies are unsatisfied, and it is
3692 possible to replace a package whose dependencies are
3693 satisfied and which is properly installed with a different
3694 version whose dependencies are not and cannot be satisfied;
3695 when this is done the depending package will be left
3696 unconfigured (since attempts to configure it will give
3697 errors) and will not function properly.
3701 For this reason packages in an installation run are usually
3702 all unpacked first and all configured later; this gives
3703 later versions of packages with dependencies on later
3704 versions of other packages the opportunity to have their
3705 dependencies satisfied.
3709 Thus <tt>Depends</tt> allows package maintainers to impose
3710 an order in which packages should be configured.
3712 <tag><tt>Depends</tt></tag>
3715 <p>This declares an absolute dependency.
3719 <prgn>dpkg</prgn> will not configure packages whose
3720 dependencies aren't satisfied. If it is asked to make
3721 an installation which would cause an installed
3722 package's dependencies to become unsatisfied it will
3726 Current versions (1.2.4) of <prgn>dpkg</prgn> have
3727 a bug in this area which will cause some of these
3728 problems to be ignored.
3730 </footnote>, unless <tt>--auto-deconfigure</tt> is
3731 specified, in which case those packages will be
3732 deconfigured before the installation proceeds.
3736 <prgn>dselect</prgn> makes it hard for the user to
3737 select packages for installation, removal or upgrade
3738 in a way that would mean that packages'
3739 <prgn>Depends</prgn> fields would be unsatisfied. The
3740 user can override this if they wish, for example if
3741 they know that <prgn>dselect</prgn> has an out-of-date
3742 view of the real package relationships.
3746 The <tt>Depends</tt> field should be used if the
3747 depended-on package is required for the depending
3748 package to provide a significant amount of
3752 <tag><tt>Recommends</tt></tag>
3754 <p>This declares a strong, but not absolute, dependency.
3758 <tt>Recommends</tt> is ignored by <prgn>dpkg</prgn>,
3759 so that users using the command-line (who are presumed
3760 to know what they're doing) will not be impeded.
3764 It is treated by <prgn>dselect</prgn> exactly as
3765 <tt>Depends</tt> is; this makes it hard for the user
3766 to select things so as to leave <tt>Recommends</tt>
3767 fields unsatisfied, but they are able to do so by
3772 The <tt>Recommends</tt> field should list packages
3773 that would be found together with this one in all but
3774 unusual installations.</p>
3777 <tag><tt>Suggests</tt></tag>
3781 This is used to declare that one package may be more
3782 useful with one or more others. Using this field
3783 tells the packaging system and the user that the
3784 listed packages are related to this one and can
3785 perhaps enhance its usefulness, but that installing
3786 this one without them is perfectly reasonable.
3790 <prgn>dselect</prgn> will offer suggsted packages to
3791 the system administrator when they select the
3792 suggesting package, but the default is not to install
3793 the suggested package.</p>
3796 <tag><tt>Pre-Depends</tt></tag>
3799 <p>This field is like <tt>Depends</tt>, except that it also forces
3800 <prgn>dpkg</prgn> to complete installation of the
3801 packages named before even starting the installation
3802 of the package which declares the predependency.
3806 <prgn>dselect</prgn> checks for predependencies when
3807 it is doing an installation run, and will attempt to
3808 find the packages which are required to be installed
3809 first and do so in the right order.
3813 However, this process is slow (because it requires
3814 repeated invocations of <prgn>dpkg</prgn>) and
3815 troublesome (because it requires guessing where to
3816 find the appropriate files).
3820 For these reasons, and because this field imposes
3821 restrictions on the order in which packages may be
3822 unpacked (which can be difficult for installations
3823 from multipart media, for example),
3824 <tt>Pre-Depends</tt> should be used sparingly,
3825 preferably only by packages whose premature upgrade or
3826 installation would hamper the ability of the system to
3827 continue with any upgrade that might be in progress.
3831 When the package declaring it is being configured, a
3832 <tt>Pre-Dependency</tt> will be considered satisfied
3833 only if the depending package has been correctly
3834 configured, just as if an ordinary <tt>Depends</tt>
3839 However, when a package declaring a predependency is
3840 being unpacked the predependency can be satisfied even
3841 if the depended-on package(s) are only unpacked or
3842 half-configured, provided that they have been
3843 configured correctly at some point in the past (and
3844 not removed or partially removed since). In this case
3845 both the previously-configured and currently unpacked
3846 or half-configured versions must satisfy any version
3847 clause in the <tt>Pre-Depends</tt> field.
3853 When selecting which level of dependency to use you should
3854 consider how important the depended-on package is to the
3855 functionality of the one declaring the dependency. Some
3856 packages are composed of components of varying degrees of
3857 importance. Such a package should list using
3858 <tt>Depends</tt> the package(s) which are required by the
3859 more important components. The other components'
3860 requirements may be mentioned as Suggestions or
3861 Recommendations, as appropriate to the components' relative
3865 <sect1><heading>Dependencies on shared libraries
3869 The dependency fields listed above are used by packages
3870 which need shared libraries to declare dependencies on the
3871 appropriate packages.
3875 These dependencies are usually determined automatically
3876 using <prgn>dpkg-shlibdeps</prgn> and inserted in the
3877 package control file using the control file substitution
3878 variables mechanism; see <ref id="srcsubstvars"> and
3879 <ref id="sourcetools">.
3883 <sect1><heading>Deconfiguration due to removal during bulk
3888 If <prgn>dpkg</prgn> would like to remove a package due to a
3889 conflict, as described above, but this would violate a
3890 dependency of some other package on the system,
3891 <prgn>dpkg</prgn> will usually not remove the conflicting
3892 package and halt with an error.
3896 However, if the <tt>--auto-deconfigure</tt> (<tt>-B</tt>)
3897 option is used <prgn>dpkg</prgn> will automatically
3898 `deconfigure' the package with the problematic dependency,
3899 so that the conflicting package can be removed and the
3900 package we're trying to install can be installed. If
3901 <prgn>dpkg</prgn> is being asked to install packages (rather
3902 than just unpacking them) it will try to reconfigure the
3903 package when it has unpacked all its arguments, in the hope
3904 that one of the other packages it is installing will satisfy
3905 the problematic dependency.
3909 <prgn>dselect</prgn> supplies this argument to
3910 <prgn>dpkg</prgn> when it invokes it, so that bulk
3911 installations proceed smoothly.
3915 <sect id="conflicts"><heading>Alternative binary packages -
3916 <tt>Conflicts</tt> and <tt>Replaces</tt>
3920 When one binary package declares a conflict with another
3921 <prgn>dpkg</prgn> will refuse to allow them to be installed
3922 on the system at the same time.
3926 If one package is to be installed, the other must be removed
3927 first - if the package being installed is marked as
3928 replacing (<ref id="replaces">) the one on the system, or
3929 the one on the system is marked as deselected, or both
3930 packages are marked <tt>Essential</tt>, then
3931 <prgn>dpkg</prgn> will automatically remove the package
3932 which is causing the conflict, otherwise it will halt the
3933 installation of the new package with an error. This
3934 mechanism specifically doesn't work when the installed
3935 package is <tt>Essential</tt>, but the new package is not.
3939 <prgn>dselect</prgn> makes it hard to select conflicting
3940 packages, though the user can override this if they wish.
3941 If they do not override it then <prgn>dselect</prgn> will
3942 select one of the packages for removal, and the user must
3943 make sure it is the right one. In the future
3944 <prgn>dselect</prgn> will look for the presence of a
3945 <tt>Replaces</tt> field to help decide which package should
3946 be installed and which removed.
3950 A package will not cause a conflict merely because its
3951 configuration files are still installed; it must be at least
3956 A special exception is made for packages which declare a
3957 conflict with their own package name, or with a virtual
3958 package which they provide (see below): this does not
3959 prevent their installation, and allows a package to conflict
3960 with others providing a replacement for it. You use this
3961 feature when you want the package in question to be the only
3962 package providing something.
3966 A <tt>Conflicts</tt> entry should almost never have an
3967 `earlier than' version clause. This would prevent
3968 <prgn>dpkg</prgn> from upgrading or installing the package
3969 which declared such a conflict until the upgrade or removal
3970 of the conflicted-with package had been completed. This
3971 aspect of installation ordering is not handled by
3972 <prgn>dselect</prgn>, so that the use <tt>Conflicts</tt> in
3973 this way is likely to cause problems for `bulk run' upgrades
3978 <sect id="virtual"><heading>Virtual packages - <tt>Provides</tt>
3982 As well as the names of actual (`concrete') packages, the
3983 package relationship fields <tt>Depends</tt>,
3984 <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
3985 <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Conflicts</tt>,
3986 <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt> may
3987 mention virtual packages.
3991 A virtual package is one which appears in the
3992 <tt>Provides</tt> control file field of another package.
3993 The effect is as if the package(s) which provide a
3994 particular virtual package name had been listed by name
3995 everywhere the virtual package name appears.
3999 If there are both a real and a virtual package of the same
4000 name then the dependency may be satisfied (or the conflict
4001 caused) by either the real package or any of the virtual
4002 packages which provide it. This is so that, for example,
4008 and someone else releases an xemacs package they can say
4012 </example> and all will work in the interim (until a purely
4013 virtual package name is decided on and the <tt>emacs</tt>
4014 and <tt>vm</tt> packages are changed to use it).
4018 If a dependency or a conflict has a version number attached
4019 then only real packages will be considered to see whether
4020 the relationship is satisfied (or the prohibition violated,
4021 for a conflict) - it is assumed that a real package which
4022 provides virtual package is not of the `right' version. So,
4023 a <tt>Provides</tt> field may not contain version numbers,
4024 and the version number of the concrete package which
4025 provides a particular virtual package will not be looked at
4026 when considering a dependency on or conflict with the
4027 virtual package name.
4031 It is likely that the ability will be added in a future
4032 release of <prgn>dpkg</prgn> to specify a version number for
4033 each virtual package it provides. This feature is not yet
4034 present, however, and is expected to be used only
4039 If you want to specify which of a set of real packages should be the
4040 default to satisfy a particular dependency on a virtual package, you
4041 should list the real package as an alternative before the virtual.
4046 <sect id="replaces"><heading><tt>Replaces</tt> - overwriting
4047 files and replacing packages
4051 The <tt>Replaces</tt> control file field has two purposes,
4052 which come into play in different situations.
4056 Virtual packages (<ref id="virtual">) are not considered
4057 when looking at a <tt>Replaces</tt> field - the packages
4058 declared as being replaced must be mentioned by their real
4062 <sect1><heading>Overwriting files in other packages
4066 Firstly, as mentioned before, it is usually an error for a
4067 package to contains files which are on the system in
4068 another package, though currently the
4069 <tt>--force-overwrite</tt> flag is enabled by default,
4070 downgrading the error to a warning,
4074 If the overwriting package declares that it replaces the
4075 one containing the file being overwritten then
4076 <prgn>dpkg</prgn> will proceed, and replace the file from
4077 the old package with that from the new. The file will no
4078 longer be listed as `owned' by the old package.
4082 If a package is completely replaced in this way, so that
4083 <prgn>dpkg</prgn> does not know of any files it still
4084 contains, it is considered to have disappeared. It will
4085 be marked as not wanted on the system (selected for
4086 removal) and not installed. Any conffiles details noted
4087 in the package will be ignored, as they will have been
4088 taken over by the replacing package(s). The package's
4089 <prgn>postrm</prgn> script will be run to allow the
4090 package to do any final cleanup required. See <ref
4091 id="mscriptsinstact">.
4095 In the future <prgn>dpkg</prgn> will discard files which
4096 overwrite those from another package which declares that
4097 it replaces the one being installed (so that you can
4098 install an older version of a package without problems).
4102 This usage of <tt>Replaces</tt> only takes effect when
4103 both packages are at least partially on the system at
4104 once, so that it can only happen if they do not conflict
4105 or if the conflict has been overridden.</p>
4108 <sect1><heading>Replacing whole packages, forcing their
4113 Secondly, <tt>Replaces</tt> allows <prgn>dpkg</prgn> and
4114 <prgn>dselect</prgn> to resolve which package should be
4115 removed when there is a conflict - see <ref id="conflicts">. This
4116 usage only takes effect when the two packages <em>do</em>
4117 conflict, so that the two effects do not interfere with
4123 <sect><heading>Defaults for satisfying dependencies - ordering
4127 Ordering is significant in dependency fields.
4131 Usually dselect will suggest to the user that they select
4132 the package with the most `fundamental' class (eg, it will
4133 prefer Base packages to Optional ones), or the one that they
4134 `most wanted' to select in some sense.
4138 In the absence of other information <prgn>dselect</prgn>
4139 will offer a default selection of the first named package in
4140 a list of alternatives.
4144 However, there is no way to specify the `order' of several
4145 packages which all provide the same thing, when that thing
4146 is listed as a dependency.
4150 Therefore a dependency on a virtual package should contain a
4151 concrete package name as the first alternative, so that this
4156 For example, consider the set of packages:
4159 Recommends: info-browser
4162 Provides: info-browser
4165 Provides: info-browser
4170 If <prgn>emacs</prgn> and <prgn>info</prgn> both have the
4171 same priority then <prgn>dselect</prgn>'s choice is
4172 essentially random. Better would be
4175 Recommends: info | info-browser
4177 so that <prgn>dselect</prgn> defaults to selecting the
4178 lightweight standalone info browser.
4183 <sect><heading>Relationships between source and binary packages -
4184 <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
4185 <tt>Build-Conflicts</tt>, <tt>Build-Conflicts-Indep</tt>
4189 A source package may declare a dependency or a conflict on a
4190 binary package. This is done with the control file fields
4191 <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
4192 <tt>Build-Conflicts</tt>, and <tt>Build-Conflicts-Indep</tt>. Their
4193 semantics is that the dependencies and conflicts they define
4194 must be satisfied (as defined earlier for binary packages),
4195 when one of the targets in <tt>debian/rules</tt> that the
4196 particular field applies to is invoked.
4199 <tag><tt>Build-Depends</tt>, <tt>Build-Conflicts</tt></tag>
4202 The <tt>Build-Depends</tt> and
4203 <tt>Build-Conflicts</tt> fields apply to the targets
4204 <tt>build</tt>, <tt>binary</tt>, <tt>binary-arch</tt>
4205 and <tt>binary-indep</tt>.
4208 <tag><tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts-Indep</tt></tag>
4211 The <tt>Build-Depends-Indep</tt> and
4212 <tt>Build-Conflicts-Indep</tt> fields apply to the
4213 targets <tt>binary</tt> and <tt>binary-indep</tt>.
4224 <chapt id="conffiles"><heading>Configuration file handling
4228 <prgn>dpkg</prgn> can do a certain amount of automatic
4229 handling of package configuration files.
4233 Whether this mechanism is appropriate depends on a number of
4234 factors, but basically there are two approaches to any
4235 particular configuration file.
4239 The easy method is to ship a best-effort configuration in the
4240 package, and use <prgn>dpkg</prgn>'s conffile mechanism to
4241 handle updates. If the user is unlikely to want to edit the
4242 file, but you need them to be able to without losing their
4243 changes, and a new package with a changed version of the file
4244 is only released infrequently, this is a good approach.
4248 The hard method is to build the configuration file from
4249 scratch in the <prgn>postinst</prgn> script, and to take the
4250 responsibility for fixing any mistakes made in earlier
4251 versions of the package automatically. This will be
4252 appropriate if the file is likely to need to be different on
4256 <sect><heading>Automatic handling of configuration files by
4261 A package may contain a control area file called
4262 <tt>conffiles</tt>. This file should be a list of filenames
4263 of configuration files needing automatic handling, separated
4264 by newlines. The filenames should be absolute pathnames,
4265 and the files referred to should actually exist in the
4270 When a package is upgraded <prgn>dpkg</prgn> will process
4271 the configuration files during the configuration stage,
4272 shortly before it runs the package's <prgn>postinst</prgn>
4277 For each file it checks to see whether the version of the
4278 file included in the package is the same as the one that was
4279 included in the last version of the package (the one that is
4280 being upgraded from); it also compares the version currently
4281 installed on the system with the one shipped with the last
4286 If neither the user nor the package maintainer has changed
4287 the file, it is left alone. If one or the other has changed
4288 their version, then the changed version is preferred - i.e.,
4289 if the user edits their file, but the package maintainer
4290 doesn't ship a different version, the user's changes will
4291 stay, silently, but if the maintainer ships a new version
4292 and the user hasn't edited it the new version will be
4293 installed (with an informative message). If both have
4294 changed their version the user is prompted about the problem
4295 and must resolve the differences themselves.
4299 The comparisons are done by calculating the MD5 message
4300 digests of the files, and storing the MD5 of the file as it
4301 was included in the most recent version of the package.
4305 When a package is installed for the first time
4306 <prgn>dpkg</prgn> will install the file that comes with it,
4307 unless that would mean overwriting a file already on the
4312 However, note that <prgn>dpkg</prgn> will <em>not</em>
4313 replace a conffile that was removed by the user (or by a
4314 script). This is necessary because with some programs a
4315 missing file produces an effect hard or impossible to
4316 achieve in another way, so that a missing file needs to be
4317 kept that way if the user did it.
4321 Note that a package should <em>not</em> modify a
4322 <prgn>dpkg</prgn>-handled conffile in its maintainer
4323 scripts. Doing this will lead to <prgn>dpkg</prgn> giving
4324 the user confusing and possibly dangerous options for
4325 conffile update when the package is upgraded.</p>
4328 <sect><heading>Fully-featured maintainer script configuration
4333 For files which contain site-specific information such as
4334 the hostname and networking details and so forth, it is
4335 better to create the file in the package's
4336 <prgn>postinst</prgn> script.
4340 This will typically involve examining the state of the rest
4341 of the system to determine values and other information, and
4342 may involve prompting the user for some information which
4343 can't be obtained some other way.
4347 When using this method there are a couple of important
4348 issues which should be considered:
4352 If you discover a bug in the program which generates the
4353 configuration file, or if the format of the file changes
4354 from one version to the next, you will have to arrange for
4355 the postinst script to do something sensible - usually this
4356 will mean editing the installed configuration file to remove
4357 the problem or change the syntax. You will have to do this
4358 very carefully, since the user may have changed the file,
4359 perhaps to fix the very problem that your script is trying
4360 to deal with - you will have to detect these situations and
4361 deal with them correctly.
4365 If you do go down this route it's probably a good idea to
4366 make the program that generates the configuration file(s) a
4367 separate program in <tt>/usr/sbin</tt>, by convention called
4368 <tt><var>package</var>config</tt> and then run that if
4369 appropriate from the post-installation script. The
4370 <tt><var>package</var>config</tt> program should not
4371 unquestioningly overwrite an existing configuration - if its
4372 mode of operation is geared towards setting up a package for
4373 the first time (rather than any arbitrary reconfiguration
4374 later) you should have it check whether the configuration
4375 already exists, and require a <tt>--force</tt> flag to
4376 overwrite it.</p></sect>
4381 <chapt id="alternatives"><heading>Alternative versions of an interface -
4382 <prgn>update-alternatives</prgn>
4386 When several packages all provide different versions of the
4387 same program or file it is useful to have the system select a
4388 default, but to allow the system administrator to change it
4389 and have their decisions respected.
4393 For example, there are several versions of the <prgn>vi</prgn>
4394 editor, and there is no reason to prevent all of them from
4395 being installed at once, each under their own name
4396 (<prgn>nvi</prgn>, <prgn>vim</prgn> or whatever).
4397 Nevertheless it is desirable to have the name <tt>vi</tt>
4398 refer to something, at least by default.
4402 If all the packages involved cooperate, this can be done with
4403 <prgn>update-alternatives</prgn>.
4407 Each package provides its own version under its own name, and
4408 calls <prgn>update-alternatives</prgn> in its postinst to
4409 register its version (and again in its prerm to deregister
4414 See the manpage <manref name="update-alternatives"
4415 section="8"> for details.
4419 If <prgn>update-alternatives</prgn> does not seem appropriate
4420 you may wish to consider using diversions instead.</p>
4424 <chapt id="diversions"><heading>Diversions - overriding a
4425 package's version of a file
4429 It is possible to have <prgn>dpkg</prgn> not overwrite a file
4430 when it reinstalls the package it belongs to, and to have it
4431 put the file from the package somewhere else instead.
4435 This can be used locally to override a package's version of a
4436 file, or by one package to override another's version (or
4437 provide a wrapper for it).
4441 Before deciding to use a diversion, read <ref
4442 id="alternatives"> to see if you really want a diversion
4443 rather than several alternative versions of a program.
4447 There is a diversion list, which is read by <prgn>dpkg</prgn>,
4448 and updated by a special program <prgn>dpkg-divert</prgn>.
4449 Please see <manref name="dpkg-divert" section="8"> for full
4450 details of its operation.
4454 When a package wishes to divert a file from another, it should
4455 call <prgn>dpkg-divert</prgn> in its preinst to add the
4456 diversion and rename the existing file. For example,
4457 supposing that a <prgn>smailwrapper</prgn> package wishes to
4458 install a wrapper around <tt>/usr/sbin/smail</tt>:
4460 if [ install = "$1" -o upgrade = "$1" ]; then
4461 dpkg-divert --package smailwrapper --add --rename \
4462 --divert /usr/sbin/smail.real /usr/sbin/smail
4464 </example> Testing <tt>$1</tt> is necessary so that the script
4465 doesn't try to add the diversion again when
4466 <prgn>smailwrapper</prgn> is upgraded. The <tt>--package
4467 smailwrapper</tt> ensures that <prgn>smailwrapper</prgn>'s
4468 copy of <tt>/usr/sbin/smail</tt> can bypass the diversion and
4469 get installed as the true version.
4473 The postrm has to do the reverse:
4475 if [ remove = "$1" ]; then
4476 dpkg-divert --package smailwrapper --remove --rename \
4477 --divert /usr/sbin/smail.real /usr/sbin/smail
4483 Do not attempt to divert a file which is vitally important for
4484 the system's operation - when using <prgn>dpkg-divert</prgn>
4485 there is a time, after it has been diverted but before
4486 <prgn>dpkg</prgn> has installed the new version, when the file
4491 <chapt id="sharedlibs"><heading>Shared libraries
4495 Packages containing shared libraries must be constructed with
4496 a little care to make sure that the shared library is always
4497 available. This is especially important for packages whose
4498 shared libraries are vitally important, such as the libc.
4502 Firstly, your package should install the shared libraries
4503 under their normal names. For example, the
4504 <prgn>libgdbm1</prgn> package should install
4505 <tt>libgdbm.so.1.7.3</tt> as
4506 <tt>/usr/lib/libgdbm.so.1.7.3</tt>. The files should not be
4507 renamed or relinked by any prerm or postrm scripts;
4508 <prgn>dpkg</prgn> will take care of renaming things safely
4509 without affecting running programs, and attempts to interfere
4510 with this are likely to lead to problems.
4514 Secondly, your package should include the symlink that
4515 <prgn>ldconfig</prgn> would create for the shared libraries.
4516 For example, the <prgn>libgdbm1</prgn> package should include
4517 a symlink from <tt>/usr/lib/libgdbm.so.1</tt> to
4518 <tt>libgdbm.so.1.7.3</tt>. This is needed so that
4519 <prgn>ld.so</prgn> can find the library in between the time
4520 <prgn>dpkg</prgn> installs it and <prgn>ldconfig</prgn> is run
4521 in the <prgn>postinst</prgn> script. Futhermore, older
4522 versions of the package management system required the library
4523 must be placed before the symlink pointing to it in the
4524 <tt>.deb</tt> file. This is so that by the time
4525 <prgn>dpkg</prgn> comes to install the symlink (overwriting
4526 the previous symlink pointing at an older version of the
4527 library) the new shared library is already in place.
4528 Unfortunately, this was not not always possible, since it
4529 highly depends on the behaviour of the filesystem. Some
4530 filesystems (such as reisefs) will reorder the files so it
4531 doesn't matter in what order you create them. Starting with
4532 release <tt>1.7.0</tt> <prgn>dpkg</prgn> will reorder the
4533 files itself when building a package.
4537 next Paragraph added to close Bug #5299, Guy Maor
4541 Thirdly, the development package should contain a symlink for
4542 the shared library without a version number. For example, the
4543 <tt>libgdbm1-dev</tt> package should include a symlink from
4544 <tt>/usr/lib/libgdm.so</tt> to <tt>libgdm.so.1.7.3</tt>. This
4545 symlink is needed by <prgn>ld</prgn> when compiling packages
4546 as it will only look for <tt>libgdm.so</tt> and
4547 <tt>libgdm.a</tt> when compiling dynamically or statically,
4552 next paragraph changed by Christian Schwarz (see policy weekly #6)
4556 Any package installing shared libraries in a directory that's listed
4557 in <tt>/etc/ld.so.conf</tt> or in one of the default library
4558 directories of <prgn>ld.so</prgn> (currently, these are <tt>/usr/lib</tt>
4559 and <tt>/lib</tt>) must call <prgn>ldconfig</prgn> in its <prgn>postinst</prgn>
4560 script if and only if the first argument is `configure'. However, it
4561 is important not to call <prgn>ldconfig</prgn> in the postrm or preinst
4562 scripts in the case where the package is being upgraded (see <ref
4563 id="unpackphase">), as <prgn>ldconfig</prgn> will see the temporary names
4564 that <prgn>dpkg</prgn> uses for the files while it is
4565 installing them and will make the shared library links point
4566 to them, just before <prgn>dpkg</prgn> continues the
4567 installation and removes the links!
4571 moved from section 2.2 , DMorris
4574 <sect id="shlibs"><heading>The <tt>shlibs</tt> File Format
4578 This file is for use by <prgn>dpkg-shlibdeps</prgn> and is
4579 required when your package provides shared libraries.
4583 Each line is of the form:
4585 <var>library-name</var> <var>version-or-soname</var> <var>dependencies ...</var>
4590 <var>library-name</var> is the name of the shared library,
4591 for example <tt>libc5</tt>.
4595 <var>version-or-soname</var> is the soname of the library -
4596 ie, the thing that must exactly match for the library to be
4597 recognised by <prgn>ld.so</prgn>. Usually this is major
4598 version number of the library.
4602 <var>dependencies</var> has the same syntax as a dependency
4603 field in a binary package control file. It should give
4604 details of which package(s) are required to satisfy a binary
4605 built against the version of the library contained in the
4606 package. See <ref id="depsyntax">.
4610 For example, if the package <tt>foo</tt> contains
4611 <tt>libfoo.so.1.2.3</tt>, where the soname of the library is
4612 <tt>libfoo.so.1</tt>, and the first version of the package
4613 which contained a minor number of at least <tt>2.3</tt> was
4614 <var>1.2.3-1</var>, then the package's <var>shlibs</var>
4617 libfoo 1 foo (>= 1.2.3-1)
4622 The version-specific dependency is to avoid warnings from
4623 <prgn>ld.so</prgn> about using older shared libraries with
4627 <sect><heading>Further Technical information on
4628 <tt>shlibs</tt></heading>
4632 following section mostly provided by Heiko Schlittermann
4636 <sect1><heading><em>What</em> are the <tt>shlibs</tt> files?
4640 The <tt>debian/shlibs</tt> file provides a way of checking
4641 for shared library dependencies on packaged binaries.
4642 They are intended to be used by package maintainers to
4643 make their lives easier.
4647 Other <tt>shlibs</tt> files that exist on a Debian system are
4649 <item> <p><tt>/etc/dpkg/shlibs.default</tt></p></item>
4650 <item> <p><tt>/etc/dpkg/shlibs.override</tt></p></item>
4651 <item> <p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
4652 <item> <p><tt>debian/shlibs.local</tt></p></item>
4654 These files are used by <prgn>dpkg-shlibdeps</prgn> when
4655 creating a binary package.</p>
4658 <sect1><heading><em>How</em> does <prgn>dpkg-shlibdeps</prgn>
4662 <prgn>dpkg-shlibdeps</prgn>
4663 determines the shared libraries directly
4666 Currently, it calls <prgn>ldd</prgn>, but in a
4667 forthcoming version it shall call <prgn>objdump</prgn>
4668 to to this. This however changes will need a couple of
4669 changes in the way that packages are build.
4672 Suppose a binary <tt>foo</tt> directly use a library
4673 <tt>libbar</tt> if it is linked with that
4674 library. Other libraries that are needed by
4675 <tt>libbar</tt> are linked indirectly to <tt>foo</tt>,
4676 and the dynamic linker will load the automatically
4677 when it loads <tt>libbar</tt>. Using <prgn>ldd</prgn>
4678 lists all the libraries, used direcly and indirectly;
4679 but <prgn>objdump</prgn> only lists the directly
4680 linked libraries. A package only needs to depend on
4681 the libraries it is directly linked to, since the
4682 dependencies for those libraries should automatically
4683 pull in the other libraries.</p>
4686 This change does mean a change in the way packages are
4687 build though: currently dpkg-shlibdeps is only run on
4688 binaries. But since we will now depend on the
4689 libraries to depend on the libraries they need the
4690 packages containing those libraries will need to run
4691 dpkg-shlibdeps on the libraries.
4694 A good example where this would help us is the current
4695 mess with multiple version of the mesa library. With
4696 the ldd-based system every package that uses mesa need
4697 to add a dependency on svgalib|svgalib-dummy in order
4698 to handle the glide mesa variant. With an
4699 objdump-based system this isn't necessary anymore and
4700 would have saved everyone a lot of work.
4703 Another example: we could update libimlib with a new
4704 version that supports a new graphics format called
4705 dgf. If we use the old ldd method every package that
4706 uses libimlib would need to be recompiled so it would
4707 also depend on libdgf or it wouldn't run due to
4708 missing symbols. However with the new system packages
4709 using libimlib can depend on libimlib itself having
4710 the dependency on libgdh and wouldn't need to be
4714 used by the compiled binaries (and libraries, in a version
4715 of <prgn>dpkg-shlibdeps</prgn> coming soon) passed through
4716 on its command line.
4720 For each shared library, <prgn>dpkg-shlibdeps</prgn> needs to know
4721 <list compact="compact">
4722 <item><p>the package containing the library, and</p></item>
4723 <item><p>the library version number,</p></item>
4726 it scans the following files in this order.
4727 <enumlist compact="compact">
4728 <item><p><tt>debian/shlibs.local</tt></p></item>
4729 <item><p><tt>/etc/dpkg/shlibs.override</tt></p></item>
4730 <item><p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
4731 <item><p><tt>/etc/dpkg/shlibs.default</tt></p></item>
4735 <sect1><heading><em>Who</em> maintains the various
4736 <tt>shlibs</tt> files?
4740 <list compact="compact">
4742 <p><tt>/etc/dpkg/shlibs.default</tt> - the maintainer
4747 <tt>/var/lib/dpkg/info/<var>package</var>.shlibs</tt>
4748 - the maintainer of each package</p>
4752 <tt>/etc/dpkg/shlibs.override</tt> - the local
4753 system administrator</p>
4756 <p><tt>debian/shlibs.local</tt> - the maintainer of
4761 The <tt>shlibs.default</tt> file is managed by
4762 <prgn>dpkg</prgn>. The entries in <tt>shlibs.default</tt>
4763 that are provided by <prgn>dpkg</prgn> are just there to
4764 fix things until the shared library packages all have
4765 <tt>shlibs</tt> files.
4769 <sect1><heading><em>How</em> to use <prgn>dpkg-shlibdeps</prgn> and
4770 the <tt>shlibs</tt> files?
4773 <sect2><heading>If your package doesn't provide a shared
4778 Put a call to <prgn>dpkg-shlibdeps</prgn> into your
4779 <tt>debian/rules</tt> file. If your package contains
4780 only binaries (e.g. no scripts) use:
4782 dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/*
4784 If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
4785 done. If it does complain you might need to create your
4786 own <tt>debian/shlibs.local</tt> file.</p>
4789 <sect2><heading>If your package provides a shared library
4793 Create a <tt>debian/shlibs</tt> file and let
4794 <tt>debian/rules</tt> install it in the control area:
4796 install -m644 debian/shlibs debian/tmp/DEBIAN
4798 If your package contains additional binaries see above.
4803 <sect1><heading><em>How</em> to write
4804 <tt>debian/shlibs.local</tt>
4808 This file is intended only as a <em>temporary</em> fix if
4809 your binaries depend on a library which doesn't provide
4810 its own <tt>/var/lib/dpkg/info/*.shlibs</tt> file yet.
4814 Let's assume you are packaging a binary <tt>foo</tt>. Your
4815 output in building the package might look like this.
4818 libbar.so.1 => /usr/X11R6/lib/libbar.so.1.0
4819 libc.so.5 => /lib/libc.so.5.2.18
4820 libX11.so.6 => /usr/X11R6/lib/libX11.so.6.0
4822 And when you ran <prgn>dpkg-shlibdeps</prgn>
4824 $ dpkg-shlibdeps -o foo
4825 dpkg-shlibdeps: warning: unable to find dependency information
4826 for shared library libbar
4827 (soname 1, path /usr/X11R6/lib/libbar.so.1.0, dependency field Depends)
4828 shlibs:Depends=elf-x11r6lib, libc5 (>= 5.2.18)
4830 The <prgn>foo</prgn> binary depends on the
4831 <prgn>libbar</prgn> shared library, but no package seems
4832 to provide a <tt>*.shlibs</tt> file in
4833 <tt></tt>var/lib/dpkg/info/. Let's determine the package
4839 $ dpkg -S /usr/X11R6/lib/libbar.so.1.0
4840 bar1: /usr/X11R6/lib/libbar.so.1.0
4841 $ dpkg -s bar1 | grep Version
4844 This tells us that the <prgn>bar1</prgn> package, version
4845 1.0-1 is the one we are using. Now we can create our own
4846 <tt>debian/shlibs.local</tt> to temporarly fix the above
4847 problem. Include the following line into your
4848 <tt>debian/shlibs.local</tt> file.
4850 libbar 1 bar1 (>= 1.0-1)
4852 Now your package build should work. As soon as the
4853 maintainer of <prgn>libbar1</prgn> provides a
4854 <tt>shlibs</tt> file, you can remove your
4855 <tt>debian/shlibs.local</tt> file.
4861 <chapt id="methif"><heading><prgn>dselect</prgn>'s interface to
4862 its installation methods
4866 <prgn>dselect</prgn> calls scripts from its installation
4867 methods when it needs to actually access data from the
4868 distribution. The core program <prgn>dselect</prgn> itself
4869 just calls these scripts and provides the package and access
4870 method selection interfaces. The installation methods are
4871 responsible for invoking <prgn>dpkg</prgn> as appropriate.
4875 Each installation method has three scripts:
4876 <list compact="compact">
4877 <item><p>Setup installation parameters.</p></item>
4878 <item><p>Update list of available packages.</p></item>
4879 <item><p>Install.</p></item>
4883 <prgn>dselect</prgn> searches for methods in
4884 <tt>/usr/lib/dpkg/methods</tt> and
4885 <tt>/usr/local/lib/dpkg/methods</tt>.
4888 <sect><heading>Functions of the method scripts
4892 The setup script is run just after the user has chosen an
4893 installation method. It should prompt the user for
4894 parameters like the site to NFS-mount or FTP from, the
4895 directory to use, or the directory or filesystem where the
4896 <tt>.deb</tt> files can be found, or the tape or floppy
4897 device to install from. It should store the responses under
4898 <tt>/var/lib/dpkg/methods</tt> - see below. If no available
4899 packages list is available it should perhaps offer to scan
4900 the available packages.
4904 The update script should obtain a list of available packages
4905 if possible, and run <tt>dpkg --update-avail</tt>, <tt>dpkg
4906 --merge-avail</tt> and/or <tt>dpkg --forget-old-unavail</tt>
4907 to load it into <prgn>dpkg</prgn> and <prgn>dselect</prgn>'s
4908 database of available packages. If no packages list was
4909 available and the user was offered and accepted the option
4910 of scanning the actual files available this scan should be
4911 done here, using <tt>dpkg --record-avail</tt>.
4915 The install script should feed all the available
4916 <tt>.deb</tt> files to <tt>dpkg --iGOEB</tt> (this is
4917 equivalent to <tt>dpkg --install
4918 --refuse-downgrade --selected-only --skip-same-version
4919 --auto-deconfigure</tt>). The <tt>-R</tt>
4920 (<tt>--recursive</tt>) option for traversing subdirectories
4921 may also be useful here).
4925 If any of these scripts needs to display a message for the
4926 user, it should wait for the user to hit `return' before
4927 exiting so that dselect doesn't immediately rewrite the
4932 If a method script succeeds (returns a zero exit status)
4933 <prgn>dselect</prgn> will return immediately to the main
4934 menu, with the `next' option highlighted ready for the user
4935 to select it. If it fails <prgn>dselect</prgn> will display
4936 a message and wait for the user to hit return.</p>
4939 <sect><heading>Location and arguments of the method scripts
4943 A set of scripts (henceforth known as a group) may provide
4944 several methods on the `main menu' with different behaviour.
4945 For example, there might be a generic get-packages-by-FTP
4946 group which might provide methods in the main menu for
4947 installation directly from one of the Debian mirror sites as
4948 well as for installation from a user-specified site.
4952 Each group of methods implemented by the same set of scripts
4953 should have a subdirectory
4954 <tt>/usr/lib/dpkg/methods/<var>group</var></tt> or
4955 <tt>/usr/local/lib/dpkg/methods/<var>group</var></tt>,
4957 <taglist compact="compact">
4958 <tag><tt>names</tt></tag>
4959 <item><p>a list of user-visible methods provided by these scripts.</p>
4961 <tag><tt>setup</tt></tag>
4962 <tag><tt>update</tt></tag>
4963 <tag><tt>install</tt></tag>
4964 <item><p>executable programs, the scripts themselves.</p>
4966 <tag><tt>desc.<var>option</var></tt></tag>
4967 <item><p>description file.</p></item>
4972 <tt>names</tt> will be formatted as a list of lines, each containing:
4974 <var>sequence</var> <var>method</var> <var>summary</var>
4978 <var>sequence</var> is a two-digit number that will be used
4979 much like <tt>rc.d</tt> prefixes to control the order in the
4980 main menu. If in doubt use 50.
4984 <var>method</var> is a name which is displayed by
4985 <prgn>dselect</prgn> as the name of the method, and which
4986 will be passed to <tt>setup</tt>, <tt>update</tt> and
4987 <tt>unpack</tt> as their first argument.
4991 <var>summary</var> is the brief description string for
4992 <prgn>dselect</prgn>'s menu.
4996 Each of the three scripts gets the same three arguments:
4997 <var>vardir</var>, <var>group</var> and <var>method</var>.
4998 <var>vardir</var> is the base directory for storing
4999 <prgn>dpkg</prgn> and <prgn>dselect</prgn>'s state, usually
5000 <tt>/var/lib/dpkg</tt>; this is passed in so that the
5001 <tt>--admindir</tt> option to <prgn>dselect</prgn> is
5006 Each option may have an extended description in
5007 <tt>desc.<var>option</var></tt>. This should be formatted
5008 like the extended description part of a <tt>Description</tt>
5009 field entry <em>shifted one character to the left</em>.
5013 <tt><var>vardir</var>/methods</tt> will exist, and a method
5015 <tt><var>vardir</var>/methods/<var>group</var></tt>
5016 directory to store its state.
5020 The group name and method name must follow the rules for C
5026 <chapt id="conversion"><heading>Conversion procedure from old
5031 This is a brief summary of the procedure for converting a
5032 pre-2.0.0.0-format source package into the new format.
5036 You are strongly advised to download and examine the <prgn>hello</prgn>
5037 package, and to read the section in the <prgn>dpkg</prgn> programmers'
5038 manual describing the source packaging tools. More detail about the
5039 exact functionality of these tools is available in
5040 <manref name="dpkg-source" section="1">.
5047 Download the original source code from wherever it can
5048 be found and do any rearrangement required to make it
5049 look like the original tree of the Debian source. Put
5051 <tt><var>package</var>-<var>upstream-version</var>.orig/</tt>
5053 <tt><var>package</var>_<var>upstream-version</var>.orig.tar.gz</tt>.
5059 Rename all files <tt>debian.*</tt> to <tt>debian/*</tt>.
5060 There may be some exceptions to this, but this is a good
5066 Edit the <tt>debian/changelog</tt> - create or rename it
5067 if necessary. Add a new revision to the top with the
5068 appropriate details, and a local variables entry to the
5069 bottom to set Emacs to the right mode:
5072 mode: debian-changelog
5080 Edit/create <tt>debian/control</tt>:
5081 <list compact="compact">
5084 Remove the <tt>Version</tt> field. If it is
5085 generated unusually (not equal to the source
5086 version) you must use the -v option to
5087 dpkg-gencontrol (see below). <tt>Section</tt>,
5088 <tt>Priority</tt>, <tt>Maintainer</tt> go above
5089 the first blank line, most of the rest
5096 Reorder the fields and add a blank line at an
5097 appropriate point, separating the source package
5098 fields from the binary package fields.
5103 <p>Add the <tt>Source</tt> field.</p></item>
5107 Add the <tt>Standards-Version</tt> field. (Please
5108 check out the Debian Policy Manual for details
5109 about this field.)</p>
5114 Change the <tt>Architecture</tt> field for each
5115 package to <tt>any</tt>, <tt>all</tt> or whatever.
5116 If there isn't an <tt>Architecture</tt> field add
5122 If any other use of sed or things used to happen
5123 to make the binary control files use
5124 <prgn>dpkg-gencontrol</prgn>'s variable
5125 substitution features to achieve the same effect.
5126 Use <tt>debian/substvars</tt> if you need to put
5127 unusally-generated information (apart from details
5128 of <tt>.deb</tt> files) in the <tt>.changes</tt>
5136 <p>Edit the <tt>debian/rules</tt>:
5137 <list compact="compact">
5140 Remove the <prgn>source</prgn> and
5141 <prgn>diff</prgn> and any <prgn>changes</prgn> and
5142 <prgn>dist</prgn> targets. These things now
5143 happen in a package-independent way and are not
5144 done by <tt>debian/rules</tt>.</p>
5148 Split the <prgn>binary</prgn> target into
5149 <prgn>binary-arch</prgn> and
5150 <prgn>binary-indep</prgn>; in many cases all of
5151 <prgn>binary</prgn> should go into
5152 <prgn>binary-arch</prgn>. Create the
5153 <prgn>binary</prgn> target and the unused of the
5154 two other <prgn>binary-*</prgn> targets if there
5155 is one - you can copy the ones from the
5156 <prgn>hello</prgn> package.</p>
5160 Change the <prgn>binary</prgn> target to use
5161 <prgn>dpkg-gencontrol</prgn> to make the package
5162 control file(s). Move it to after all the files
5163 have been installed but just before the last
5164 <prgn>chown</prgn> and <prgn>chmod</prgn> in the
5169 Change occurrences of <tt>debian-tmp</tt> to
5170 <tt>debian/tmp</tt>.</p>
5174 Change occurrences of
5175 <tt>debian.{post,pre}{inst,rm}</tt> to
5176 <tt>debian/*</tt>.</p>
5180 Remove the version number setting at the top, if
5185 Ensure that the package's Debian-specific and
5186 upstream changelogs are installed.</p>
5194 Change the package to use <prgn>dpkg-shlibdeps</prgn> to
5195 determine its shared library dependencies and substitute
5196 them in. Shared library dependencies should no longer
5197 be hardwired in the source package.</p>
5202 Check that the <tt>debian/README</tt> is really the
5203 copyright file, and if so rename it to
5204 <tt>debian/copyright</tt> and edit <tt>debian/rules</tt>
5205 to cope with this and to change the installation of the
5207 <tt>/usr/doc/<var>package</var>/copyright</tt> to
5208 <tt>/usr/doc/copyright/<var>package</var></tt>. If it
5209 isn't then find <tt>debian/copyright</tt> and decide
5210 what to do with the <tt>README</tt>.</p>
5214 <p>Check for various other anachronisms and problems:
5215 <list compact="compact">
5218 Remove any <tt>Package_Revision</tt>,
5219 <tt>Package-Revision</tt> or <tt>Revision</tt>
5224 Rename <tt>Optional</tt> to <tt>Suggests</tt>,
5225 <tt>Recommended</tt> to
5226 <tt>Recommends</tt>.</p>
5231 <tt>/usr/doc/examples/<var>package</var></tt> to
5232 <tt>/usr/doc/<var>package</var>/examples</tt>.</p>
5236 Make sure that manpages are installed
5241 Check that the description has an extended
5242 description, is well-formatted and meaningful and
5243 helpful to people wanting to know whether to
5244 install a package.</p>
5251 <p>Look everything over.</p></item>
5255 Do a test build using <tt>dpkg-buildpackage -us -uc -sa
5256 -r<var>whatever</var></tt>. Check the permissions and
5257 locations of files in the resulting package by examining
5258 the output of <tt>dpkg-deb --contents</tt>, and check
5259 that the source build happened OK. Test install the
5260 binary package(s) and test extract the source
5266 Sign the release: either rebuild everything with
5267 <tt>dpkg-buildpackage -sa</tt>, or PGP-sign the
5268 <tt>.dsc</tt>, rebuild the <tt>.changes</tt> using
5269 <tt>dpkg-genchanges -sa</tt>, and then PGP-sign the
5270 <tt>.changes</tt>.</p>
5277 The use of <tt>-sa</tt> on <prgn>dpkg-buildpackage</prgn> and
5278 <prgn>dpkg-genchanges</prgn> is important when doing the first
5279 build/uploading of a new-format source package. Unless this
5280 happens to be Debian revision <tt>0</tt> or <tt>1</tt> by
5281 default the original source tarfile will not be included in
5282 the uploaded files listed in the <tt>.changes</tt> file, and
5283 so it won't be installed on the FTP site. <tt>-sa</tt>
5284 requests that the original source be included