1 <!doctype debiandoc system[
2 <!-- include version information so we don't have to hard code it
3 within the document -->
4 <!entity % versiondata SYSTEM "version.ent"> %versiondata;
8 Debian GNU/Linux Packaging Manual.
9 Copyright (C)1996 Ian Jackson; released under the terms of the GNU
10 General Public License, version 2 or (at your option) any later.
11 Revised: David A. Morris (bweaver@debian.org)
12 Maintainer since 1998, Christian Schwarz <schwarz@debian.org>
18 <titlepag><title>Debian Packaging Manual</title>
20 <name>Ian Jackson </name>
21 <email>ijackson@gnu.ai.mit.edu</email>
24 <name>Revised: David A. Morris</name>
25 <email>bweaver@debian.org</email>
28 <name>Maintainer: Christian Schwarz </name>
29 <email>schwarz@debian.org</email>
32 <name>Maintainer: Manoj Srivastava </name>
33 <email>srivasta@debian.org</email>
36 <name>Maintainer: The Debian Policy group </name>
37 <email>debian-policy@lists.debian.org</email>
39 <version>version &version;, &date;</version>
42 This manual describes the technical aspects of creating Debian
43 binary and source packages. It also documents the interface
44 between <prgn>dselect</prgn> and its access method scripts.
45 It does not deal with the Debian Project policy requirements,
46 and it assumes familiarity with <prgn>dpkg</prgn>'s functions
47 from the system administrator's perspective. This
48 package itself is maintained by a group of maintainers
49 that have no editorial powers. At the moment, the list of
53 <p>Michael Alan Dorman <email>mdorman@debian.org</email></p>
56 <p>Richard Braakman <email>dark@xs4all.nl</email></p>
59 <p>Philip Hands <email>phil@hands.com</email></p>
62 <p>Manoj Srivastava <email>srivasta@debian.org</email></p>
69 <copyrightsummary>Copyright ©1996 Ian Jackson.</copyrightsummary>
71 This manual is free software; you may redistribute it and/or
72 modify it under the terms of the GNU General Public License
73 as published by the Free Software Foundation; either version
74 2, or (at your option) any later version.
78 This is distributed in the hope that it will be useful, but
79 <em>without any warranty</em>; without even the implied
80 warranty of merchantability or fitness for a particular
81 purpose. See the GNU General Public License for more
86 A copy of the GNU General Public License is available as
87 <tt>/usr/doc/copyright/GPL</tt> in the Debian GNU/Linux
88 distribution or on the World Wide Web at
89 <tt>http://www.gnu.org/copyleft/gpl.html</tt>. You can also
90 obtain it by writing to the Free Software Foundation, Inc.,
91 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
97 <!-- Describes the technical interface between a package and dpkg.
99 How to safely put shared libraries in a package. Details of
100 dpkg's handling of individual files. Sections on when to use
101 which feature (eg Replaces vs. Replaces/Conflicts
102 vs. update-alternatives vs. diversions) Cross-references to the
103 policy document (see below) where appropriate. Description of the
104 interface between dselect and its access methods. Hints on where
105 to start with a new package (ie, the hello package). What to do
110 Manpages are required for: update-rc.d, diversions,
111 update-alternatives, install-info in a package.
116 <heading>Introduction and scope of this manual</heading>
119 <prgn>dpkg</prgn> is a suite of programs for creating binary
120 package files and installing and removing them on Unix
123 <prgn>dpkg</prgn> is targetted primarily at Debian
124 GNU/Linux, but may work on or be ported to other
131 The binary packages are designed for the management of
132 installed executable programs (usually compiled binaries) and
133 their associated data, though source code examples and
134 documentation are provided as part of some packages.</p>
137 This manual describes the technical aspects of creating Debian
138 binary packages (<tt>.deb</tt> files). It documents the
139 behaviour of the package management programs
140 <prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and the way
141 they interact with packages.</p>
144 It also documents the interaction between
145 <prgn>dselect</prgn>'s core and the access method scripts it
146 uses to actually install the selected packages, and describes
147 how to create a new access method.</p>
150 This manual does not go into detail about the options and
151 usage of the package building and installation tools. It
152 should therefore be read in conjuction with those programs'
157 The utility programs which are provided with <prgn>dpkg</prgn>
158 for managing various system configuration and similar issues,
159 such as <prgn>update-rc.d</prgn> and
160 <prgn>install-info</prgn>, are not described in detail here -
161 please see their manpages.
165 It does <em>not</em> describe the policy requirements imposed
166 on Debian packages, such as the permissions on files and
167 directories, documentation requirements, upload procedure, and
168 so on. You should see the Debian packaging policy manual for
169 these details. (Many of them will probably turn out to be
170 helpful even if you don't plan to upload your package and make
171 it available as part of the distribution.)
175 It is assumed that the reader is reasonably familiar with the
176 <prgn>dpkg</prgn> System Administrators' manual.
177 Unfortunately this manual does not yet exist.
181 The Debian version of the FSF's GNU hello program is provided
182 as an example for people wishing to create Debian
183 packages. The Debian <prgn>debmake</prgn> package is
184 recommended as a very helpful tool in creating and maintaining
185 Debian packages. However, while the tools and examples are
186 helpful, they do not replace the need to read and follow the
187 Policy and Programmer's Manual.</p>
190 <chapt id="binarypkg"><heading>Binary packages
194 The binary package has two main sections. The first part
195 consists of various control information files and scripts used
196 by <prgn>dpkg</prgn> when installing and removing. See <ref
201 The second part is an archive containing the files and
202 directories to be installed.
206 In the future binary packages may also contain other
207 components, such as checksums and digital signatures. The
208 format for the archive is described in full in the
209 <tt>deb(5)</tt> manpage.
213 <sect id="bincreating"><heading>Creating package files -
214 <prgn>dpkg-deb</prgn>
218 All manipulation of binary package files is done by
219 <prgn>dpkg-deb</prgn>; it's the only program that has
220 knowledge of the format. (<prgn>dpkg-deb</prgn> may be
221 invoked by calling <prgn>dpkg</prgn>, as <prgn>dpkg</prgn>
222 will spot that the options requested are appropriate to
223 <prgn>dpkg-deb</prgn> and invoke that instead with the same
228 In order to create a binary package you must make a
229 directory tree which contains all the files and directories
230 you want to have in the filesystem data part of the package.
231 In Debian-format source packages this directory is usually
232 <tt>debian/tmp</tt>, relative to the top of the package's
237 They should have the locations (relative to the root of the
238 directory tree you're constructing) ownerships and
239 permissions which you want them to have on the system when
244 With current versions of <prgn>dpkg</prgn> the uid/username
245 and gid/groupname mappings for the users and groups being
246 used should be the same on the system where the package is
247 built and the one where it is installed.
251 You need to add one special directory to the root of the
252 miniature filesystem tree you're creating:
253 <prgn>DEBIAN</prgn>. It should contain the control
254 information files, notably the binary package control file
255 (see <ref id="controlfile">).
259 The <prgn>DEBIAN</prgn> directory will not appear in the
260 filesystem archive of the package, and so won't be installed
261 by <prgn>dpkg</prgn> when the package is installed.
265 When you've prepared the package, you should invoke:
267 dpkg --build <var>directory</var>
272 This will build the package in
273 <tt><var>directory</var>.deb</tt>. (<prgn>dpkg</prgn> knows
274 that <tt>--build</tt> is a <prgn>dpkg-deb</prgn> option, so
275 it invokes <prgn>dpkg-deb</prgn> with the same arguments to
280 See the manpage <manref name="dpkg-deb" section="8"> for details of how
281 to examine the contents of this newly-created file. You may find the
282 output of following commands enlightening:
284 dpkg-deb --info <var>filename</var>.deb
285 dpkg-deb --contents <var>filename</var>.deb
286 dpkg --contents <var>filename</var>.deb
288 To view the copyright file for a package you could use this command:
290 dpkg --fsys-tarfile <var>filename</var>.deb | tar xof usr/doc/<var>\*</var>copyright | less
295 <sect id="controlarea">
297 Package control information files
301 The control information portion of a binary package is a
302 collection of files with names known to <prgn>dpkg</prgn>.
303 It will treat the contents of these files specially - some
304 of them contain information used by <prgn>dpkg</prgn> when
305 installing or removing the package; others are scripts which
306 the package maintainer wants <prgn>dpkg</prgn> to run.
310 It is possible to put other files in the package control
311 area, but this is not generally a good idea (though they
312 will largely be ignored).
316 Here is a brief list of the control info files supported by
317 <prgn>dpkg</prgn> and a summary of what they're used for.
322 <tag><tt>control</tt>
326 This is the key description file used by
327 <prgn>dpkg</prgn>. It specifies the package's name
328 and version, gives its description for the user,
329 states its relationships with other packages, and so
330 forth. See <ref id="controlfile">.
334 It is usually generated automatically from information
335 in the source package by the
336 <prgn>dpkg-gencontrol</prgn> program, and with
337 assistance from <prgn>dpkg-shlibdeps</prgn>. See <ref
338 id="sourcetools">.</p>
341 <tag><tt>postinst</tt>, <tt>preinst</tt>, <tt>postrm</tt>,
347 These are exectuable files (usually scripts) which
348 <prgn>dpkg</prgn> runs during installation, upgrade
349 and removal of packages. They allow the package to
350 deal with matters which are particular to that package
351 or require more complicated processing than that
352 provided by <prgn>dpkg</prgn>. Details of when and
353 how they are called are in <ref
354 id="maintainerscripts">.
358 It is very important to make these scripts
362 That means that if it runs successfully or fails
363 and then you call it again it doesn't bomb out,
364 but just ensures that everything is the way it
367 </footnote> This is so that if an error occurs, the
368 user interrupts <prgn>dpkg</prgn> or some other
369 unforeseen circumstance happens you don't leave the
370 user with a badly-broken package.
374 The maintainer scripts are guaranteed to run with a
375 controlling terminal and can interact with the user.
376 If they need to prompt for passwords, do full-screen
377 interaction or something similar you should do these
378 things to and from <tt>/dev/tty</tt>, since
379 <prgn>dpkg</prgn> will at some point redirect scripts'
380 standard input and output so that it can log the
381 installation process. Likewise, because these scripts
382 may be executed with standard output redirected into a
383 pipe for logging purposes, Perl scripts should set
384 unbuffered output by setting <tt>$|=1</tt> so that the
385 output is printed immediately rather than being
390 Each script should return a zero exit status for
391 success, or a nonzero one for failure.</p>
394 <tag><tt>conffiles</tt>
399 This file contains a list of configuration files which
400 are to be handled automatically by <prgn>dpkg</prgn>
401 (see <ref id="conffiles">). Note that not necessarily
402 every configuration file should be listed here.</p>
410 This file contains a list of the shared libraries
411 supplied by the package, with dependency details for
412 each. This is used by <prgn>dpkg-shlibdeps</prgn>
413 when it determines what dependencies are required in a
414 package control file. The <tt>shlibs</tt> file format
415 is described on <ref id="shlibs">.
421 <sect id="controlfile">
423 The main control information file: <tt>control</tt>
426 The most important control information file used by
427 <prgn>dpkg</prgn> when it installs a package is
428 <tt>control</tt>. It contains all the package's `vital
433 The binary package control files of packages built from
434 Debian sources are made by a special tool,
435 <prgn>dpkg-gencontrol</prgn>, which reads
436 <tt>debian/control</tt> and <tt>debian/changelog</tt> to
437 find the information it needs. See <ref id="sourcepkg"> for
442 The fields in binary package control files are:
443 <list compact="compact">
445 <p><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</p>
448 <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
450 <item><p><qref id="f-Architecture"><tt>Architecture</tt></qref>
454 This field should appear in all packages, though
455 <prgn>dpkg</prgn> doesn't require it yet so that
456 old packages can still be installed.
462 <p><qref id="relationships"><tt>Depends</tt>,
463 <tt>Provides</tt> et al.</qref></p>
466 <p><qref id="f-Essential"><tt>Essential</tt></qref></p>
469 <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
472 <p><qref id="f-classification"><tt>Section</tt>,
473 <tt>Priority</tt></qref></p>
476 <p><qref id="f-Source"><tt>Source</tt></qref></p>
479 <p><qref id="descriptions"><tt>Description</tt></qref></p>
483 <qref id="f-Installed-Size"><tt>Installed-Size</tt></qref>
489 A description of the syntax of control files and the purpose
490 of these fields is available in <ref id="controlfields">.
494 <heading>Time Stamps</heading>
496 Maintainers are encouraged to preserve the modification
497 times of the upstream source files in a package, as far as
498 is reasonably possible.
501 The rationale is that there is some information conveyed
502 by knowing the age of the file, for example, you could
503 recognize that some documentation is very old by looking
504 at the modification time, so it would be nice if the
505 modification time of the upstream source would be
512 <chapt id="sourcepkg">
513 <heading>Source packages</heading>
516 The Debian binary packages in the distribution are generated
517 from Debian sources, which are in a special format to assist
518 the easy and automatic building of binaries.
522 There was a previous version of the Debian source format,
523 which is now being phased out. Instructions for converting an
524 old-style package are given in the Debian policy manual.
527 <sect id="sourcetools">
528 <heading>Tools for processing source packages</heading>
531 Various tools are provided for manipulating source packages;
532 they pack and unpack sources and help build of binary
533 packages and help manage the distribution of new versions.
537 They are introduced and typical uses described here; see
538 <manref name="dpkg-source" section="1"> for full
539 documentation about their arguments and operation.
543 For examples of how to construct a Debian source package,
544 and how to use those utilities that are used by Debian
545 source packages, please see the <prgn>hello</prgn> example
551 <prgn>dpkg-source</prgn> - packs and unpacks Debian source
556 This program is frequently used by hand, and is also
557 called from package-independent automated building scripts
558 such as <prgn>dpkg-buildpackage</prgn>.
562 To unpack a package it is typically invoked with
564 dpkg-source -x <var>.../path/to/filename</var>.dsc
569 with the <tt><var>filename</var>.tar.gz</tt> and
570 <tt><var>filename</var>.diff.gz</tt> (if applicable) in
571 the same directory. It unpacks into
572 <tt><var>package</var>-<var>version</var></tt>, and if
574 <tt><var>package</var>-<var>version</var>.orig</tt>, in
575 the current directory.
579 To create a packed source archive it is typically invoked:
581 dpkg-source -b <var>package</var>-<var>version</var>
586 This will create the <tt>.dsc</tt>, <tt>.tar.gz</tt> and
587 <tt>.diff.gz</tt> (if appropriate) in the current
588 directory. <prgn>dpkg-source</prgn> does not clean the
589 source tree first - this must be done separately if it is
594 See also <ref id="sourcearchives">.</p>
600 <prgn>dpkg-buildpackage</prgn> - overall package-building
605 <prgn>dpkg-buildpackage</prgn> is a script which invokes
606 <prgn>dpkg-source</prgn>, the <tt>debian/rules</tt>
607 targets <prgn>clean</prgn>, <prgn>build</prgn> and
608 <prgn>binary</prgn>, <prgn>dpkg-genchanges</prgn> and
609 <prgn>pgp</prgn> to build a signed source and binary
614 It is usually invoked by hand from the top level of the
615 built or unbuilt source directory. It may be invoked with
616 no arguments; useful arguments include:
617 <taglist compact="compact">
618 <tag><tt>-uc</tt>, <tt>-us</tt></tag>
621 Do not PGP-sign the <tt>.changes</tt> file or the
622 source package <tt>.dsc</tt> file, respectively.</p>
624 <tag><tt>-p<var>pgp-command</var></tt></tag>
627 Invoke <var>pgp-command</var> instead of finding
628 <tt>pgp</tt> on the <prgn>PATH</prgn>.
629 <var>pgp-command</var> must behave just like
630 <prgn>pgp</prgn>.</p>
632 <tag><tt>-r<var>root-command</var></tt></tag>
635 When root privilege is required, invoke the command
636 <var>root-command</var>. <var>root-command</var>
637 should invoke its first argument as a command, from
638 the <prgn>PATH</prgn> if necessary, and pass its
639 second and subsequent arguments to the command it
640 calls. If no <var>root-command</var> is supplied
641 then <var>dpkg-buildpackage</var> will take no
642 special action to gain root privilege, so that for
643 most packages it will have to be invoked as root to
646 <tag><tt>-b</tt>, <tt>-B</tt></tag>
649 Two types of binary-only build and upload - see
650 <manref name="dpkg-source" section="1">.
659 <prgn>dpkg-gencontrol</prgn> - generates binary package
664 This program is usually called from <tt>debian/rules</tt>
665 (see <ref id="sourcetree">) in the top level of the source
670 This is usually done just before the files and directories in the
671 temporary directory tree where the package is being built have their
672 permissions and ownerships set and the package is constructed using
673 <prgn>dpkg-deb/</prgn>
676 This is so that the control file which is produced has
677 the right permissions
683 <prgn>dpkg-gencontrol</prgn> must be called after all the
684 files which are to go into the package have been placed in
685 the temporary build directory, so that its calculation of
686 the installed size of a package is correct.
690 It is also necessary for <prgn>dpkg-gencontrol</prgn> to
691 be run after <prgn>dpkg-shlibdeps</prgn> so that the
692 variable substitutions created by
693 <prgn>dpkg-shlibdeps</prgn> in <tt>debian/substvars</tt>
698 For a package which generates only one binary package, and
699 which builds it in <tt>debian/tmp</tt> relative to the top
700 of the source package, it is usually sufficient to call
701 <prgn>dpkg-gencontrol</prgn>.
705 Sources which build several binaries will typically need
708 dpkg-gencontrol -Pdebian/tmp-<var>pkg</var> -p<var>package</var>
709 </example> The <tt>-P</tt> tells
710 <prgn>dpkg-gencontrol</prgn> that the package is being
711 built in a non-default directory, and the <tt>-p</tt>
712 tells it which package's control file should be generated.
716 <prgn>dpkg-gencontrol</prgn> also adds information to the
717 list of files in <tt>debian/files</tt>, for the benefit of
718 (for example) a future invocation of
719 <prgn>dpkg-genchanges</prgn>.</p>
724 <prgn>dpkg-shlibdeps</prgn> - calculates shared library
729 This program is usually called from <tt>debian/rules</tt>
730 just before <prgn>dpkg-gencontrol</prgn> (see <ref
731 id="sourcetree">), in the top level of the source tree.
735 Its arguments are executables
738 They may be specified either in the locations in the
739 source tree where they are created or in the locations
740 in the temporary build tree where they are installed
741 prior to binary package creation.
743 </footnote> for which shared library dependencies should
744 be included in the binary package's control file.
748 If some of the executable(s) shared libraries should only
749 warrant a <tt>Recommends</tt> or <tt>Suggests</tt>, or if
750 some warrant a <tt>Pre-Depends</tt>, this can be achieved
751 by using the <tt>-d<var>dependency-field</var></tt> option
752 before those executable(s). (Each <tt>-d</tt> option
753 takes effect until the next <tt>-d</tt>.)
757 <prgn>dpkg-shlibdeps</prgn> does not directly cause the
758 output control file to be modified. Instead by default it
759 adds to the <tt>debian/substvars</tt> file variable
760 settings like <tt>shlibs:Depends</tt>. These variable
761 settings must be referenced in dependency fields in the
762 appropriate per-binary-package sections of the source
767 For example, the <prgn>procps</prgn> package generates two
768 kinds of binaries, simple C binaries like <prgn>ps</prgn>
769 which require a predependency and full-screen ncurses
770 binaries like <prgn>top</prgn> which require only a
771 recommendation. It can say in its <tt>debian/rules</tt>:
773 dpkg-shlibdeps -dPre-Depends ps -dRecommends top
775 and then in its main control file <tt>debian/control</tt>:
779 Pre-Depends: ${shlibs:Pre-Depends}
780 Recommends: ${shlibs:Recommends}
786 Sources which produce several binary packages with
787 different shared library dependency requirements can use
788 the <tt>-p<var>varnameprefix</var></tt> option to override
789 the default <tt>shlib:</tt> prefix (one invocation of
790 <prgn>dpkg-shlibdeps</prgn> per setting of this option).
791 They can thus produce several sets of dependency
792 variables, each of the form
793 <tt><var>varnameprefix</var>:<var>dependencyfield</var></tt>,
794 which can be referred to in the appropriate parts of the
795 binary package control files.
802 <prgn>dpkg-distaddfile</prgn> - adds a file to
803 <tt>debian/files</tt>
807 Some packages' uploads need to include files other than
808 the source and binary package files.
812 <prgn>dpkg-distaddfile</prgn> adds a file to the
813 <tt>debian/files</tt> file so that it will be included in
814 the <tt>.changes</tt> file when
815 <prgn>dpkg-genchanges</prgn> is run.
819 It is usually invoked from the <prgn>binary</prgn> target of
820 <tt>debian/rules</tt>:
822 dpkg-distaddfile <var>filename</var> <var>section</var> <var>priority</var>
824 The <var>filename</var> is relative to the directory where
825 <prgn>dpkg-genchanges</prgn> will expect to find it - this
826 is usually the directory above the top level of the source
827 tree. The <tt>debian/rules</tt> target should put the
828 file there just before or just after calling
829 <prgn>dpkg-distaddfile</prgn>.
833 The <var>section</var> and <var>priority</var> are passed
834 unchanged into the resulting <tt>.changes</tt> file. See
835 <ref id="f-classification">.
840 <sect1><heading><prgn>dpkg-genchanges</prgn> - generates a <tt>.changes</tt> upload
845 This program is usually called by package-independent
846 automatic building scripts such as
847 <prgn>dpkg-buildpackage</prgn>, but it may also be called
852 It is usually called in the top level of a built source
853 tree, and when invoked with no arguments will print out a
854 straightforward <tt>.changes</tt> file based on the
855 information in the source package's changelog and control
856 file and the binary and source packages which should have
862 <sect1><heading><prgn>dpkg-parsechangelog</prgn> - produces parsed representation of
867 This program is used internally by
868 <prgn>dpkg-source</prgn> et al. It may also occasionally
869 be useful in <tt>debian/rules</tt> and elsewhere. It
870 parses a changelog, <tt>debian/changelog</tt> by default,
871 and prints a control-file format representation of the
872 information in it to standard output.
876 <sect1 id="dpkgarch"><heading><prgn>dpkg-architecture</prgn> -
877 information about the build and host system
881 This program can be used manually, but is also invoked by
882 <tt>dpkg-buildpackage</tt> or <tt>debian/rules</tt> to set
883 to set environment or make variables which specify the build and
884 host architecture for the package building process.
889 <sect id="sourcetree"><heading>The Debianised source tree
893 The source archive scheme described later is intended to
894 allow a Debianised source tree with some associated control
895 information to be reproduced and transported easily. The
896 Debianised source tree is a version of the original program
897 with certain files added for the benefit of the
898 Debianisation process, and with any other changes required
899 made to the rest of the source code and installation
904 The extra files created for Debian are in the subdirectory
905 <tt>debian</tt> of the top level of the Debianised source
906 tree. They are described below.
909 <sect1 id="debianrules"><heading><tt>debian/rules</tt> - the main building
914 This file is an executable makefile, and contains the
915 package-specific recipies for compiling the package and
916 building binary package(s) out of the source.
920 It must start with the line <tt>#!/usr/bin/make -f</tt>,
921 so that it can be invoked by saying its name rather than
922 invoking <prgn>make</prgn> explicitly.
926 Since an interactive <tt>debian/rules</tt> script makes it
927 impossible to autocompile that package and also makes it
928 hard for other people to reproduce the same binary
929 package, all <strong>required targets</strong> have to be
930 non-interactive. At a minimul, required targets are the
931 ones called by <prgn>dpkg-buildpackage</prgn>, namely,
932 <em>clean</em>, <em>binary</em>, <em>binary-arch</em>, and
933 <em>build</em>. It also follows that any target that these
934 targets depend on must also be non-interactive.
938 The targets which are required to be present are:
940 <tag><tt>build</tt></tag>
943 This should perform all non-interactive
944 configuration and compilation of the package. If a
945 package has an interactive pre-build configuration
946 routine, the Debianised source package should be
947 built after this has taken place, so that it can be
948 built without rerunning the configuration.
952 For some packages, notably ones where the same
953 source tree is compiled in different ways to produce
954 two binary packages, the <prgn>build</prgn> target
955 does not make much sense. For these packages it is
956 good enough to provide two (or more) targets
957 (<tt>build-a</tt> and <tt>build-b</tt> or whatever)
958 for each of the ways of building the package, and a
959 <prgn>build</prgn> target that does nothing. The
960 <prgn>binary</prgn> target will have to build the
961 package in each of the possible ways and make the
962 binary package out of each.
966 The <prgn>build</prgn> target must not do anything
967 that might require root privilege.
971 The <prgn>build</prgn> target may need to run
972 <prgn>clean</prgn> first - see below.
976 When a package has a configuration routine that
977 takes a long time, or when the makefiles are poorly
978 designed, or when <prgn>build</prgn> needs to run
979 <prgn>clean</prgn> first, it is a good idea to
980 <tt>touch build</tt> when the build process is
981 complete. This will ensure that if <tt>debian/rules
982 build</tt> is run again it will not rebuild the
987 <tag><tt>binary</tt>, <tt>binary-arch</tt>,
988 <tt>binary-indep</tt>
992 The <prgn>binary</prgn> target should be all that is
993 necessary for the user to build the binary
994 package. All these targets are required to be
995 non-interactive. It is split into two parts:
996 <prgn>binary-arch</prgn> builds the packages' output
997 files which are specific to a particular
998 architecture, and <prgn>binary-indep</prgn> builds
1003 <prgn>binary</prgn> should usually be a target with
1004 no commands which simply depends on
1005 <prgn>binary-arch</prgn> and
1006 <prgn>binary-indep</prgn>.
1010 Both <prgn>binary-*</prgn> targets should depend on
1011 the <prgn>build</prgn> target, above, so that the
1012 package is built if it has not been already. It
1013 should then create the relevant binary package(s),
1014 using <prgn>dpkg-gencontrol</prgn> to make their
1015 control files and <prgn>dpkg-deb</prgn> to build
1016 them and place them in the parent of the top level
1021 If one of the <prgn>binary-*</prgn> targets has
1022 nothing to do (this will be always be the case if
1023 the source generates only a single binary package,
1024 whether architecture-dependent or not) it
1025 <em>must</em> still exist, but should always
1030 <ref id="binarypkg"> describes how to construct
1035 The <prgn>binary</prgn> targets must be invoked as
1040 <tag><tt>clean</tt></tag>
1044 This should undo any effects that the
1045 <prgn>build</prgn> and <prgn>binary</prgn> targets
1046 may have had, except that it should leave alone any
1047 output files created in the parent directory by a
1048 run of <prgn>binary</prgn>. This target is required
1049 to be non-interactive.
1053 If a <prgn>build</prgn> file is touched at the end
1054 of the <prgn>build</prgn> target, as suggested
1055 above, it must be removed as the first thing that
1056 <prgn>clean</prgn> does, so that running
1057 <prgn>build</prgn> again after an interrupted
1058 <prgn>clean</prgn> doesn't think that everything is
1063 The <prgn>clean</prgn> target must be invoked as
1064 root if <prgn>binary</prgn> has been invoked since
1065 the last <prgn>clean</prgn>, or if
1066 <prgn>build</prgn> has been invoked as root (since
1067 <prgn>build</prgn> may create directories, for
1072 <tag><tt>get-orig-source</tt> (optional)</tag>
1076 This target fetches the most recent version of the
1077 original source package from a canonical archive
1078 site (via FTP or WWW, for example), does any
1079 necessary rearrangement to turn it into the original
1080 source tarfile format described below, and leaves it
1081 in the current directory.
1085 This target may be invoked in any directory, and
1086 should take care to clean up any temporary files it
1091 This target is optional, but providing it if
1092 possible is a good idea.
1098 The <prgn>build</prgn>, <prgn>binary</prgn> and
1099 <prgn>clean</prgn> targets must be invoked with a current
1100 directory of the package's top-level directory.
1105 Additional targets may exist in <tt>debian/rules</tt>,
1106 either as published or undocumented interfaces or for the
1107 package's internal use.
1111 The architecture we build on and build for is determined by make
1112 variables via dpkg-architecture (see <ref id="dpkgarch">). You can
1113 get the Debian architecture and the GNU style architecture
1114 specification string for the build machine as well as the host
1115 machine. Here is a list of supported make variables:
1116 <list compact="compact">
1118 <p><tt>DEB_*_ARCH</tt> (the Debian architecture)</p>
1121 <p><tt>DEB_*_GNU_TYPE</tt> (the GNU style architecture
1122 specification string)</p>
1125 <p><tt>DEB_*_GNU_CPU</tt> (the CPU part of DEB_*_GNU_TYPE)</p>
1128 <p><tt>DEB_*_GNU_SYSTEM</tt> (the System part of
1134 where <tt>*</tt> is either <tt>BUILD</tt> for specification of
1135 the build machine or <tt>HOST</tt> for specification of the machine
1140 Backward compatibility can be provided in the rules file
1141 by setting the needed variables to suitable default
1142 values, please refer to the documentation of
1143 dpkg-architecture for details.
1147 It is important to understand that the <tt>DEB_*_ARCH</tt>
1148 string does only determine which Debian architecture we
1149 build on resp. for. It should not be used to get the CPU
1150 or System information, the GNU style variables should be
1156 <sect1><heading><tt>debian/control</tt>
1160 This file contains version-independent details about the
1161 source package and about the binary packages it creates.
1165 It is a series of sets of control fields, each
1166 syntactically similar to a binary package control file.
1167 The sets are separated by one or more blank lines. The
1168 first set is information about the source package in
1169 general; each subsequent set describes one binary package
1170 that the source tree builds.
1174 The syntax and semantics of the fields are described below
1175 in <ref id="controlfields">.
1179 The general (binary-package-independent) fields are:
1180 <list compact="compact">
1182 <p><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</p>
1185 <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
1189 <qref id="f-classification"><tt>Section</tt> and
1190 <tt>Priority</tt></qref>
1191 (classification, mandatory)
1196 <qref id="relationships"><tt>Build-Depends</tt> et
1197 al.</qref> (source package interrelationships)
1202 <qref id="f-Standards-Version"><tt>Standards-Version</tt></qref>
1208 The per-binary-package fields are:
1209 <list compact="compact">
1211 <p><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</p>
1215 <qref id="f-Architecture"><tt>Architecture</tt></qref>
1219 <p><qref id="descriptions"><tt>Description</tt></qref></p>
1223 <qref id="f-classification"><tt>Section</tt> and
1224 <tt>Priority</tt></qref> (classification)</p>
1227 <p><qref id="f-Essential"><tt>Essential</tt></qref></p>
1231 <qref id="relationships"><tt>Depends</tt> et
1232 al.</qref> (binary package interrelationships)
1238 These fields are used by <prgn>dpkg-gencontrol</prgn> to
1239 generate control files for binary packages (see below), by
1240 <prgn>dpkg-genchanges</prgn> to generate the
1241 <tt>.changes</tt> file to accompany the upload, and by
1242 <prgn>dpkg-source</prgn> when it creates the <tt>.dsc</tt>
1243 source control file as part of a source archive.
1247 The fields here may contain variable references - their
1248 values will be substituted by
1249 <prgn>dpkg-gencontrol</prgn>, <prgn>dpkg-genchanges</prgn>
1250 or <prgn>dpkg-source</prgn> when they generate output
1251 control files. See <ref id="srcsubstvars"> for details.
1254 <p> <sect2><heading>User-defined fields
1258 Additional user-defined fields may be added to the
1259 source package control file. Such fields will be
1260 ignored, and not copied to (for example) binary or
1261 source package control files or upload control files.
1265 If you wish to add additional unsupported fields to
1266 these output files you should use the mechanism
1271 Fields in the main source control information file with
1272 names starting <tt>X</tt>, followed by one or more of
1273 the letters <tt>BCS</tt> and a hyphen <tt>-</tt>, will
1274 be copied to the output files. Only the part of the
1275 field name after the hyphen will be used in the output
1276 file. Where the letter <tt>B</tt> is used the field
1277 will appear in binary package control files, where the
1278 letter <tt>S</tt> is used in source package control
1279 files and where <tt>C</tt> is used in upload control
1280 (<tt>.changes</tt>) files.
1284 For example, if the main source information control file
1287 XBS-Comment: I stand between the candle and the star.
1289 then the binary and source package control files will contain the
1292 Comment: I stand between the candle and the star.
1299 <sect1 id="dpkgchangelog"><heading><tt>debian/changelog</tt>
1303 This file records the changes to the Debian-specific parts of the
1307 Though there is nothing stopping an author who is also
1308 the Debian maintainer from using it for all their
1309 changes, it will have to be renamed if the Debian and
1310 upstream maintainers become different
1317 It has a special format which allows the package building
1318 tools to discover which version of the package is being
1319 built and find out other release-specific information.
1323 That format is a series of entries like this:
1325 <var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
1327 * <var>change details</var>
1328 <var>more change details</var>
1329 * <var>even more change details</var>
1331 -- <var>maintainer name and email address</var> <var>date</var>
1336 <var>package</var> and <var>version</var> are the source
1337 package name and version number.
1341 <var>distribution(s)</var> lists the distributions where
1342 this version should be installed when it is uploaded - it
1343 is copied to the <tt>Distribution</tt> field in the
1344 <tt>.changes</tt> file. See <ref id="f-Distribution">.
1348 <var>urgency</var> is the value for the <tt>Urgency</tt>
1349 field in the <tt>.changes</tt> file for the upload. See
1350 <ref id="f-Urgency">. It is not possible to specify an
1351 urgency containing commas; commas are used to separate
1352 <tt><var>keyword</var>=<var>value</var></tt> settings in
1353 the <prgn>dpkg</prgn> changelog format (though there is
1354 currently only one useful <var>keyword</var>,
1359 The change details may in fact be any series of lines
1360 starting with at least two spaces, but conventionally each
1361 change starts with an asterisk and a separating space and
1362 continuation lines are indented so as to bring them in
1363 line with the start of the text above. Blank lines may be
1364 used here to separate groups of changes, if desired.
1368 The maintainer name and email address should <em>not</em>
1369 necessarily be those of the usual package maintainer.
1370 They should be the details of the person doing
1371 <em>this</em> version. The information here will be
1372 copied to the <tt>.changes</tt> file, and then later used
1373 to send an acknowledgement when the upload has been
1378 The <var>date</var> should be in RFC822 format
1381 This is generated by the <prgn>822-date</prgn>
1384 </footnote>; it should include the timezone specified
1385 numerically, with the timezone name or abbreviation
1386 optionally present as a comment.
1390 The first `title' line with the package name should start
1391 at the left hand margin; the `trailer' line with the
1392 maintainer and date details should be preceded by exactly
1393 one space. The maintainer details and the date must be
1394 separated by exactly two spaces.
1398 An Emacs mode for editing this format is available: it is
1399 called <tt>debian-changelog-mode</tt>. You can have this
1400 mode selected automatically when you edit a Debian
1401 changelog by adding a local variables clause to the end of
1405 <sect2><heading>Defining alternative changelog formats
1409 It is possible to use a different format to the standard
1410 one, by providing a parser for the format you wish to
1415 In order to have <tt>dpkg-parsechangelog</tt> run your
1416 parser, you must include a line within the last 40 lines
1417 of your file matching the Perl regular expression:
1418 <tt>\schangelog-format:\s+([0-9a-z]+)\W</tt> The part in
1419 parentheses should be the name of the format. For
1420 example, you might say:
1422 @@@ changelog-format: joebloggs @@@
1424 Changelog format names are non-empty strings of alphanumerics.
1428 If such a line exists then <tt>dpkg-parsechangelog</tt>
1429 will look for the parser as
1430 <tt>/usr/lib/dpkg/parsechangelog/<var>format-name</var></tt>
1432 <tt>/usr/local/lib/dpkg/parsechangelog/<var>format-name</var></tt>;
1433 it is an error for it not to find it, or for it not to
1434 be an executable program. The default changelog format
1435 is <tt>dpkg</tt>, and a parser for it is provided with
1436 the <tt>dpkg</tt> package.
1440 The parser will be invoked with the changelog open on
1441 standard input at the start of the file. It should read
1442 the file (it may seek if it wishes) to determine the
1443 information required and return the parsed information
1444 to standard output in the form of a series of control
1445 fields in the standard format. By default it should
1446 return information about only the most recent version in
1447 the changelog; it should accept a
1448 <tt>-v<var>version</var></tt> option to return changes
1449 information from all versions present <em>strictly
1450 after</em> <var>version</var>, and it should then be an
1451 error for <var>version</var> not to be present in the
1457 <list compact="compact">
1459 <p><qref id="f-Source"><tt>Source</tt></qref></p>
1462 <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
1466 <qref id="f-Distribution"><tt>Distribution</tt></qref>
1471 <p><qref id="f-Urgency"><tt>Urgency</tt></qref> (mandatory)</p>
1475 <qref id="f-Maintainer"><tt>Maintainer</tt></qref>
1480 <p><qref id="f-Date"><tt>Date</tt></qref></p>
1484 <qref id="f-Changes"><tt>Changes</tt></qref>
1491 If several versions are being returned (due to the use
1492 of <tt>-v</tt>), the urgency value should be of the
1493 highest urgency code listed at the start of any of the
1494 versions requested followed by the concatenated
1495 (space-separated) comments from all the versions
1496 requested; the maintainer, version, distribution and
1497 date should always be from the most recent version.
1501 For the format of the <tt>Changes</tt> field see <ref
1506 If the changelog format which is being parsed always or
1507 almost always leaves a blank line between individual
1508 change notes these blank lines should be stripped out,
1509 so as to make the resulting output compact.
1513 If the changelog format does not contain date or package
1514 name information this information should be omitted from
1515 the output. The parser should not attempt to synthesise
1516 it or find it from other sources.
1520 If the changelog does not have the expected format the
1521 parser should exit with a nonzero exit status, rather
1522 than trying to muddle through and possibly generating
1527 A changelog parser may not interact with the user at
1531 <sect1 id="srcsubstvars"><heading><tt>debian/substvars</tt>
1532 and variable substitutions
1536 When <prgn>dpkg-gencontrol</prgn>,
1537 <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
1538 generate control files they do variable substitutions on
1539 their output just before writing it. Variable
1540 substitutions have the form
1541 <tt>${<var>variable-name</var>}</tt>. The optional file
1542 <tt>debian/substvars</tt> contains variable substitutions
1543 to be used; variables can also be set directly from
1544 <tt>debian/rules</tt> using the <tt>-V</tt> option to the
1545 source packaging commands, and certain predefined
1546 variables are available.
1550 The is usually generated and modified dynamically by
1551 <tt>debian/rules</tt> targets; in this case it must be
1552 removed by the <prgn>clean</prgn> target.
1556 See <manref name="dpkg-source" section="1"> for full
1557 details about source variable substitutions, including the
1558 format of <tt>debian/substvars</tt>.</p>
1561 <sect1><heading><tt>debian/files</tt>
1565 This file is not a permanent part of the source tree; it
1566 is used while building packages to record which files are
1567 being generated. <prgn>dpkg-genchanges</prgn> uses it
1568 when it generates a <tt>.changes</tt> file.
1572 It should not exist in a shipped source package, and so it
1573 (and any backup files or temporary files such as
1577 <tt>files.new</tt> is used as a temporary file by
1578 <prgn>dpkg-gencontrol</prgn> and
1579 <prgn>dpkg-distaddfile</prgn> - they write a new
1580 version of <tt>files</tt> here before renaming it,
1581 to avoid leaving a corrupted copy if an error
1584 </footnote>) should be removed by the
1585 <prgn>clean</prgn> target. It may also be wise to
1586 ensure a fresh start by emptying or removing it at the
1587 start of the <prgn>binary</prgn> target.
1591 <prgn>dpkg-gencontrol</prgn> adds an entry to this file
1592 for the <tt>.deb</tt> file that will be created by
1593 <prgn>dpkg-deb</prgn> from the control file that it
1594 generates, so for most packages all that needs to be done
1595 with this file is to delete it in <prgn>clean</prgn>.
1599 If a package upload includes files besides the source
1600 package and any binary packages whose control files were
1601 made with <prgn>dpkg-gencontrol</prgn> then they should be
1602 placed in the parent of the package's top-level directory
1603 and <prgn>dpkg-distaddfile</prgn> should be called to add
1604 the file to the list in <tt>debian/files</tt>.</p>
1607 <sect1><heading><tt>debian/tmp</tt>
1611 This is the canonical temporary location for the
1612 construction of binary packages by the <prgn>binary</prgn>
1613 target. The directory <tt>tmp</tt> serves as the root of
1614 the filesystem tree as it is being constructed (for
1615 example, by using the package's upstream makefiles install
1616 targets and redirecting the output there), and it also
1617 contains the <tt>DEBIAN</tt> subdirectory. See <ref
1622 If several binary packages are generated from the same
1623 source tree it is usual to use several
1624 <tt>debian/tmp<var>something</var></tt> directories, for
1625 example <tt>tmp-a</tt> or <tt>tmp-doc</tt>.
1629 Whatever <tt>tmp</tt> directories are created and used by
1630 <prgn>binary</prgn> must of course be removed by the
1631 <prgn>clean</prgn> target.</p></sect1>
1635 <sect id="sourcearchives"><heading>Source packages as archives
1639 As it exists on the FTP site, a Debian source package
1640 consists of three related files. You must have the right
1641 versions of all three to be able to use them.
1646 <tag>Debian source control file - <tt>.dsc</tt></tag>
1650 This file contains a series of fields, identified and
1651 separated just like the fields in the control file of
1652 a binary package. The fields are listed below; their
1653 syntax is described above, in <ref id="controlfields">.
1654 <list compact="compact">
1656 <p><qref id="f-Source"><tt>Source</tt></qref></p>
1659 <p><qref id="versions"><tt>Version</tt></qref></p>
1662 <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
1665 <p><qref id="f-Binary"><tt>Binary</tt></qref></p>
1668 <p><qref id="f-Architecture"><tt>Architecture</tt></qref></p>
1672 <qref id="relationships"><tt>Build-Depends</tt> et
1673 al.</qref> (source package interrelationships)
1678 <qref id="f-Standards-Version"><tt>Standards-Version</tt></qref></p>
1681 <p><qref id="f-Files"><tt>Files</tt></qref></p>
1686 The source package control file is generated by
1687 <prgn>dpkg-source</prgn> when it builds the source
1688 archive, from other files in the source package,
1689 described above. When unpacking it is checked against
1690 the files and directories in the other parts of the
1691 source package, as described below.</p>
1695 Original source archive -
1697 <var>package</var>_<var>upstream-version</var>.orig.tar.gz
1704 This is a compressed (with <tt>gzip -9</tt>)
1705 <prgn>tar</prgn> file containing the source code from
1706 the upstream authors of the program. The tarfile
1707 unpacks into a directory
1708 <tt><var>package</var>-<var>upstream-version</var>.orig</tt>,
1709 and does not contain files anywhere other than in
1710 there or in its subdirectories.</p>
1714 Debianisation diff -
1716 <var>package</var>_<var>upstream_version-revision</var>.diff.gz
1722 This is a unified context diff (<tt>diff -u</tt>)
1723 giving the changes which are required to turn the
1724 original source into the Debian source. These changes
1725 may only include editing and creating plain files.
1726 The permissions of files, the targets of symbolic
1727 links and the characteristics of special files or
1728 pipes may not be changed and no files may be removed
1733 All the directories in the diff must exist, except the
1734 <tt>debian</tt> subdirectory of the top of the source
1735 tree, which will be created by
1736 <prgn>dpkg-source</prgn> if necessary when unpacking.
1740 The <prgn>dpkg-source</prgn> program will
1741 automatically make the <tt>debian/rules</tt> file
1742 executable (see below).</p></item>
1747 If there is no original source code - for example, if the
1748 package is specially prepared for Debian or the Debian
1749 maintainer is the same as the upstream maintainer - the
1750 format is slightly different: then there is no diff, and the
1752 <tt><var>package</var>_<var>version</var>.tar.gz</tt> and
1753 contains a directory
1754 <tt><var>package</var>-<var>version</var></tt>.
1758 <sect><heading>Unpacking a Debian source package without
1759 <prgn>dpkg-source</prgn>
1763 <tt>dpkg-source -x</tt> is the recommended way to unpack a
1764 Debian source package. However, if it is not available it
1765 is possible to unpack a Debian source archive as follows:
1766 <enumlist compact="compact">
1769 Untar the tarfile, which will create a <tt>.orig</tt>
1773 <p>Rename the <tt>.orig</tt> directory to
1774 <tt><var>package</var>-<var>version</var></tt>.</p>
1778 Create the subdirectory <tt>debian</tt> at the top of
1779 the source tree.</p>
1781 <item><p>Apply the diff using <tt>patch -p0</tt>.</p>
1783 <item><p>Untar the tarfile again if you want a copy of the original
1784 source code alongside the Debianised version.</p>
1789 It is not possible to generate a valid Debian source archive
1790 without using <prgn>dpkg-source</prgn>. In particular,
1791 attempting to use <prgn>diff</prgn> directly to generate the
1792 <tt>.diff.gz</tt> file will not work.
1795 <sect1><heading>Restrictions on objects in source packages
1799 The source package may not contain any hard links
1802 This is not currently detected when building source
1803 packages, but only when extracting
1809 Hard links may be permitted at some point in the
1810 future, but would require a fair amount of
1813 </footnote>, device special files, sockets or setuid or
1817 Setgid directories are allowed.
1823 The source packaging tools manage the changes between the
1824 original and Debianised source using <prgn>diff</prgn> and
1825 <prgn>patch</prgn>. Turning the original source tree as
1826 included in the <tt>.orig.tar.gz</tt> into the debianised
1827 source must not involve any changes which cannot be
1828 handled by these tools. Problematic changes which cause
1829 <prgn>dpkg-source</prgn> to halt with an error when
1830 building the source package are:
1831 <list compact="compact">
1832 <item><p>Adding or removing symbolic links, sockets or pipes.</p>
1834 <item><p>Changing the targets of symbolic links.</p>
1836 <item><p>Creating directories, other than <tt>debian</tt>.</p>
1838 <item><p>Changes to the contents of binary files.</p></item>
1839 </list> Changes which cause <prgn>dpkg-source</prgn> to
1840 print a warning but continue anyway are:
1841 <list compact="compact">
1844 Removing files, directories or symlinks.
1847 Renaming a file is not treated specially - it is
1848 seen as the removal of the old file (which
1849 generates a warning, but is otherwise ignored),
1850 and the creation of the new
1857 Changed text files which are missing the usual final
1858 newline (either in the original or the modified
1863 Changes which are not represented, but which are not detected by
1864 <prgn>dpkg-source</prgn>, are:
1865 <list compact="compact">
1866 <item><p>Changing the permissions of files (other than
1867 <tt>debian/rules</tt>) and directories.</p></item>
1872 The <tt>debian</tt> directory and <tt>debian/rules</tt>
1873 are handled specially by <prgn>dpkg-source</prgn> - before
1874 applying the changes it will create the <tt>debian</tt>
1875 directory, and afterwards it will make
1876 <tt>debian/rules</tt> world-exectuable.
1882 <chapt id="controlfields"><heading>Control files and their fields
1886 Many of the tools in the <prgn>dpkg</prgn> suite manipulate
1887 data in a common format, known as control files. Binary and
1888 source packages have control data as do the <tt>.changes</tt>
1889 files which control the installation of uploaded files, and
1890 <prgn>dpkg</prgn>'s internal databases are in a similar
1894 <sect><heading>Syntax of control files
1898 A file consists of one or more paragraphs of fields. The
1899 paragraphs are separated by blank lines. Some control files
1900 only allow one paragraph; others allow several, in which
1901 case each paragraph often refers to a different package.
1905 Each paragraph is a series of fields and values; each field
1906 consists of a name, followed by a colon and the value. It
1907 ends at the end of the line. Horizontal whitespace (spaces
1908 and tabs) may occur before or after the value and is ignored
1909 there; it is conventional to put a single space after the
1914 Some fields' values may span several lines; in this case
1915 each continuation line <em>must</em> start with a space or
1916 tab. Any trailing spaces or tabs at the end of individual
1917 lines of a field value are ignored.
1921 Except where otherwise stated only a single line of data is
1922 allowed and whitespace is not significant in a field body.
1923 Whitespace may never appear inside names (of packages,
1924 architectures, files or anything else), version numbers or
1925 in between the characters of multi-character version
1930 Field names are not case-sensitive, but it is usual to
1931 capitalise the field names using mixed case as shown below.
1935 Blank lines, or lines consisting only of spaces and tabs,
1936 are not allowed within field values or between fields - that
1937 would mean a new paragraph.
1941 It is important to note that there are several fields which
1942 are optional as far as <prgn>dpkg</prgn> and the related
1943 tools are concerned, but which must appear in every Debian
1944 package, or whose omission may cause problems. When writing
1945 the control files for Debian packages you <em>must</em> read
1946 the Debian policy manual in conjuction with the details
1947 below and the list of fields for the particular file.</p>
1950 <sect><heading>List of fields
1953 <sect1 id="f-Package"><heading><tt>Package</tt>
1957 The name of the binary package. Package names consist of
1958 the alphanumerics and <tt>+</tt> <tt>-</tt> <tt>.</tt>
1959 (plus, minus and full stop).
1962 The characters <tt>@</tt> <tt>:</tt> <tt>=</tt>
1963 <tt>%</tt> <tt>_</tt> (at, colon, equals, percent
1964 and underscore) used to be legal and are still
1965 accepted when found in a package file, but may not be
1966 used in new packages
1972 They must be at least two characters and must start with
1973 an alphanumeric. In current versions of dpkg they are
1974 sort of case-sensitive<footnote><p>This is a
1975 bug.</p></footnote>; use lowercase package names unless
1976 the package you're building (or referring to, in other
1977 fields) is already using uppercase.</p>
1980 <sect1 id="f-Version"><heading><tt>Version</tt>
1984 This lists the source or binary package's version number -
1985 see <ref id="versions">.
1990 <sect1 id="f-Architecture"><heading><tt>Architecture</tt>
1994 This is the architecture string; it is a single word for
1995 the Debian architecture.
1999 <prgn>dpkg</prgn> will check the declared architecture of
2000 a binary package against its own compiled-in value before
2005 The special value <tt>all</tt> indicates that the package
2006 is architecture-independent.
2010 In the main <tt>debian/control</tt> file in the source
2011 package, or in the source package control file
2012 <tt>.dsc</tt>, a list of architectures (separated by
2013 spaces) is also allowed, as is the special value
2014 <tt>any</tt>. A list indicates that the source will build
2015 an architecture-dependent package, and will only work
2016 correctly on the listed architectures. <tt>any</tt>
2017 indicates that though the source package isn't dependent
2018 on any particular architecture and should compile fine on
2019 any one, the binary package(s) produced are not
2020 architecture-independent but will instead be specific to
2021 whatever the current build architecture is.
2025 In a <tt>.changes</tt> file the <tt>Architecture</tt>
2026 field lists the architecture(s) of the package(s)
2027 currently being uploaded. This will be a list; if the
2028 source for the package is being uploaded too the special
2029 entry <tt>source</tt> is also present.
2033 See <ref id="debianrules"> for information how to get the
2034 architecture for the build process.
2038 <sect1 id="f-Maintainer"><heading><tt>Maintainer</tt>
2042 The package maintainer's name and email address. The name
2043 should come first, then the email address inside angle
2044 brackets <tt><></tt> (in RFC822 format).
2048 If the maintainer's name contains a full stop then the
2049 whole field will not work directly as an email address due
2050 to a misfeature in the syntax specified in RFC822; a
2051 program using this field as an address must check for this
2052 and correct the problem if necessary (for example by
2053 putting the name in round brackets and moving it to the
2054 end, and bringing the email address forward).
2058 In a <tt>.changes</tt> file or parsed changelog data this
2059 contains the name and email address of the person
2060 responsible for the particular version in question - this
2061 may not be the package's usual maintainer.
2065 This field is usually optional in as far as the
2066 <prgn>dpkg</prgn> are concerned, but its absence when
2067 building packages usually generates a warning.</p>
2070 <sect1 id="f-Source"><heading><tt>Source</tt>
2074 This field identifies the source package name.
2078 In a main source control information or a
2079 <tt>.changes</tt> or <tt>.dsc</tt> file or parsed
2080 changelog data this may contain only the name of the
2085 In the control file of a binary package (or in a
2086 <tt>Packages</tt> file) it may be followed by a version
2087 number in parentheses.
2090 It is usual to leave a space after the package name if
2091 a version number is specified.
2093 </footnote> This version number may be omitted (and is, by
2094 <prgn>dpkg-gencontrol</prgn>) if it has the same value as
2095 the <tt>Version</tt> field of the binary package in
2096 question. The field itself may be omitted from a binary
2097 package control file when the source package has the same
2098 name and version as the binary package.
2102 <sect1><heading>Package interrelationship fields:
2103 <tt>Depends</tt>, <tt>Pre-Depends</tt>,
2104 <tt>Recommends</tt> <tt>Suggests</tt>, <tt>Conflicts</tt>,
2105 <tt>Provides</tt>, <tt>Replaces</tt>
2109 These fields describe the package's relationships with
2110 other packages. Their syntax and semantics are described
2111 in <ref id="relationships">.</p>
2114 <sect1 id="f-Description"><heading><tt>Description</tt>
2118 In a binary package <tt>Packages</tt> file or main source
2119 control file this field contains a description of the
2120 binary package, in a special format. See <ref
2121 id="descriptions"> for details.
2125 In a <tt>.changes</tt> file it contains a summary of the
2126 descriptions for the packages being uploaded. The part of
2127 the field before the first newline is empty; thereafter
2128 each line has the name of a binary package and the summary
2129 description line from that binary package. Each line is
2130 indented by one space.</p>
2133 <sect1 id="f-Essential"><heading><tt>Essential</tt>
2137 This is a boolean field which may occur only in the
2138 control file of a binary package (or in the
2139 <tt>Packages</tt> file) or in a per-package fields
2140 paragraph of a main source control data file.
2144 If set to <tt>yes</tt> then <prgn>dpkg</prgn> and
2145 <prgn>dselect</prgn> will refuse to remove the package
2146 (though it can be upgraded and/or replaced). The other
2147 possible value is <tt>no</tt>, which is the same as not
2148 having the field at all.</p>
2151 <sect1 id="f-classification"><heading><tt>Section</tt> and
2156 These two fields classify the package. The
2157 <tt>Priority</tt> represents how important that it is that
2158 the user have it installed; the <tt>Section</tt>
2159 represents an application area into which the package has
2164 When they appear in the <tt>debian/control</tt> file these
2165 fields give values for the section and priority subfields
2166 of the <tt>Files</tt> field of the <tt>.changes</tt> file,
2167 and give defaults for the section and priority of the
2172 The section and priority are represented, though not as
2173 separate fields, in the information for each file in the
2174 <qref id="f-Files"><tt>-File</tt></qref>field of a
2175 <tt>.changes</tt> file. The section value in a
2176 <tt>.changes</tt> file is used to decide where to install
2177 a package in the FTP archive.
2181 These fields are not used by by <prgn>dpkg</prgn> proper,
2182 but by <prgn>dselect</prgn> when it sorts packages and
2183 selects defaults. See the Debian policy manual for the
2184 priorities in use and the criteria for selecting the
2185 priority for a Debian package, and look at the Debian FTP
2186 archive for a list of currently in-use priorities.
2190 These fields may appear in binary package control files,
2191 in which case they provide a default value in case the
2192 <tt>Packages</tt> files are missing the information.
2193 <prgn>dpkg</prgn> and <prgn>dselect</prgn> will only use
2194 the value from a <tt>.deb</tt> file if they have no other
2195 information; a value listed in a <tt>Packages</tt> file
2196 will always take precedence. By default
2197 <prgn>dpkg-genchanges</prgn> does not include the section
2198 and priority in the control file of a binary package - use
2199 the <tt>-isp</tt>, <tt>-is</tt> or <tt>-ip</tt> options to
2200 achieve this effect.</p>
2203 <sect1 id="f-Binary"><heading><tt>Binary</tt>
2207 This field is a list of binary packages.
2211 When it appears in the <tt>.dsc</tt> file it is the list
2212 of binary packages which a source package can produce. It
2213 does not necessarily produce all of these binary packages
2214 for every architecture. The source control file doesn't
2215 contain details of which architectures are appropriate for
2216 which of the binary packages.
2220 When it appears in a <tt>.changes</tt> file it lists the
2221 names of the binary packages actually being uploaded.
2225 The syntax is a list of binary packages separated by
2229 A space after each comma is conventional.
2231 </footnote> Currently the packages must be separated using
2232 only spaces in the <tt>.changes</tt> file.</p>
2235 <sect1 id="f-Installed-Size"><heading><tt>Installed-Size</tt>
2239 This field appears in the control files of binary
2240 packages, and in the <tt>Packages</tt> files. It gives
2241 the total amount of disk space required to install the
2246 The disk space is represented in kilobytes as a simple
2250 <sect1 id="f-Files"><heading><tt>Files</tt>
2254 This field contains a list of files with information about
2255 each one. The exact information and syntax varies with
2256 the context. In all cases the the part of the field
2257 contents on the same line as the field name is empty. The
2258 remainder of the field is one line per file, each line
2259 being indented by one space and containing a number of
2260 sub-fields separated by spaces.
2264 In the <tt>.dsc</tt> (Debian source control) file each
2265 line contains the MD5 checksum, size and filename of the
2266 tarfile and (if applicable) diff file which make up the
2267 remainder of the source package.
2270 That is, the parts which are not the
2273 </footnote> The exact forms of the filenames are described
2274 in <ref id="sourcearchives">.
2278 In the <tt>.changes</tt> file this contains one line per
2279 file being uploaded. Each line contains the MD5 checksum,
2280 size, section and priority and the filename. The section
2281 and priority are the values of the corresponding fields in
2282 the main source control file - see <ref
2283 id="f-classification">. If no section or priority is
2284 specified then <tt>-</tt> should be used, though section
2285 and priority values must be specified for new packages to
2286 be installed properly.
2290 The special value <tt>byhand</tt> for the section in a
2291 <tt>.changes</tt> file indicates that the file in question
2292 is not an ordinary package file and must by installed by
2293 hand by the distribution maintainers. If the section is
2294 <tt>byhand</tt> the priority should be <tt>-</tt>.
2298 If a new Debian revision of a package is being shipped and
2299 no new original source archive is being distributed the
2300 <tt>.dsc</tt> must still contain the <tt>Files</tt> field
2301 entry for the original source archive
2302 <tt><var>package</var>-<var>upstream-version</var>.orig.tar.gz</tt>,
2303 but the <tt>.changes</tt> file should leave it out. In
2304 this case the original source archive on the distribution
2305 site must match exactly, byte-for-byte, the original
2306 source archive which was used to generate the
2307 <tt>.dsc</tt> file and diff which are being uploaded.</p>
2312 id="f-Standards-Version"><heading><tt>Standards-Version</tt>
2316 The most recent version of the standards (the
2317 <prgn>dpkg</prgn> programmers' and policy manuals and
2318 associated texts) with which the package complies. This
2319 is updated manually when editing the source package to
2320 conform to newer standards; it can sometimes be used to
2321 tell when a package needs attention.
2325 Its format is the same as that of a version number except
2326 that no epoch or Debian revision is allowed - see <ref
2331 <sect1 id="f-Distribution"><heading><tt>Distribution</tt>
2335 In a <tt>.changes</tt> file or parsed changelog output
2336 this contains the (space-separated) name(s) of the
2337 distribution(s) where this version of the package should
2338 be or was installed. Distribution names follow the rules
2339 for package names. (See <ref id="f-Package">).
2343 Current distribution values are:
2345 <tag><em>stable</em></tag>
2348 This is the current `released' version of Debian
2349 GNU/Linux. A new version is released approximately
2350 every 3 months after the <em>development</em> code has
2351 been <em>frozen</em> for a month of testing. Once the
2352 distribution is <em>stable</em> only major bug fixes
2353 are allowed. When changes are made to this
2354 distribution, the release number is increased
2355 (for example: 1.2r1 becomes 1.2r2 then 1.2r3, etc).
2359 <tag><em>unstable</em></tag>
2362 This distribution value refers to the
2363 <em>developmental</em> part of the Debian distribution
2364 tree. New packages, new upstream versions of packages
2365 and bug fixes go into the <em>unstable</em> directory
2366 tree. Download from this distribution at your own
2370 <tag><em>contrib</em></tag>
2373 The packages with this distribution value do not meet
2374 the criteria for inclusion in the main Debian
2375 distribution as defined by the Policy Manual, but meet
2376 the criteria for the <em>contrib</em>
2377 Distribution. There is currently no distinction
2378 between stable and unstable packages in the
2379 <em>contrib</em> or <em>non-free</em>
2380 distributions. Use your best judgement in downloading
2381 from this Distribution.</p>
2384 <tag><em>non-free</em></tag>
2387 Like the packages in the <em>contrib</em> seciton,
2388 the packages in <em>non-free</em> do not meet the
2389 criteria for inclusion in the main Debian distribution
2390 as defined by the Policy Manual. Again, use your best
2391 judgement in downloading from this Distribution.</p>
2393 <tag><em>experimental</em></tag>
2396 The packages with this distribution value are deemed
2397 by their maintainers to be high risk. Oftentimes they
2398 represent early beta or developmental packages from
2399 various sources that the maintainers want people to
2400 try, but are not ready to be a part of the other parts
2401 of the Debian distribution tree. Download at your own
2405 <tag><em>frozen</em></tag>
2408 From time to time, (currently, every 3 months) the
2409 <em>unstable</em> distribution enters a state of
2410 `code-freeze' in anticipation of release as a
2411 <em>stable</em> version. During this period of testing
2412 (usually 4 weeks) only fixes for existing or
2413 newly-discovered bugs will be allowed.
2416 </taglist> You should list <em>all</em> distributions that
2417 the package should be installed into. Except in unusual
2418 circumstances, installations to <em>stable</em> should also
2419 go into <em>frozen</em> (if it exists) and
2420 <em>unstable</em>. Likewise, installations into
2421 <em>frozen</em> should also go into <em>unstable</em>.</p>
2424 <sect1 id="f-Urgency"><heading><tt>Urgency</tt>
2428 This is a description of how important it is to upgrade to
2429 this version from previous ones. It consists of a single
2430 keyword usually taking one of the values <tt>LOW</tt>,
2431 <tt>MEDIUM</tt> or <tt>HIGH</tt>) followed by an optional
2432 commentary (separated by a space) which is usually in
2433 parentheses. For example:
2435 Urgency: LOW (HIGH for diversions users)
2440 This field appears in the <tt>.changes</tt> file and in
2441 parsed changelogs; its value appears as the value of the
2442 <tt>urgency</tt> attribute in a <prgn>dpkg</prgn>-style
2443 changelog (see <ref id="dpkgchangelog">).
2447 Urgency keywords are not case-sensitive.</p>
2450 <sect1 id="f-Date"><heading><tt>Date</tt>
2454 In <tt>.changes</tt> files and parsed changelogs, this
2455 gives the date the package was built or last edited.</p>
2458 <sect1 id="f-Format"><heading><tt>Format</tt>
2462 This field occurs in <tt>.changes</tt> files, and
2463 specifies a format revision for the file. The format
2464 described here is version <tt>1.5</tt>. The syntax of the
2465 format value is the same as that of a package version
2466 number except that no epoch or Debian revision is allowed
2467 - see <ref id="versions">.</p>
2470 <sect1 id="f-Changes"><heading><tt>Changes</tt>
2474 In a <tt>.changes</tt> file or parsed changelog this field
2475 contains the human-readable changes data, describing the
2476 differences between the last version and the current one.
2480 There should be nothing in this field before the first
2481 newline; all the subsequent lines must be indented by at
2482 least one space; blank lines must be represented by a line
2483 consiting only of a space and a full stop.
2487 Each version's change information should be preceded by a
2488 `title' line giving at least the version, distribution(s)
2489 and urgency, in a human-readable way.
2493 If data from several versions is being returned the entry
2494 for the most recent version should be returned first, and
2495 entries should be separated by the representation of a
2496 blank line (the `title' line may also be followed by the
2497 representation of blank line).</p>
2500 <sect1 id="f-Filename"><heading><tt>Filename</tt> and
2501 <tt>MSDOS-Filename</tt>
2505 These fields in <tt>Packages</tt> files give the
2506 filename(s) of (the parts of) a package in the
2507 distribution directories, relative to the root of the
2508 Debian hierarchy. If the package has been split into
2509 several parts the parts are all listed in order, separated
2513 <sect1 id="f-Size"><heading><tt>Size</tt> and <tt>MD5sum</tt>
2517 These fields in <tt>Packages</tt> files give the size (in
2518 bytes, expressed in decimal) and MD5 checksum of the
2519 file(s) which make(s) up a binary package in the
2520 distribution. If the package is split into several parts
2521 the values for the parts are listed in order, separated by
2525 <sect1 id="f-Status"><heading><tt>Status</tt>
2529 This field in <prgn>dpkg</prgn>'s status file records
2530 whether the user wants a package installed, removed or
2531 left alone, whether it is broken (requiring
2532 reinstallation) or not and what its current state on the
2533 system is. Each of these pieces of information is a
2537 <sect1 id="f-Config-Version"><heading><tt>Config-Version</tt>
2541 If a package is not installed or not configured, this
2542 field in <prgn>dpkg</prgn>'s status file records the last
2543 version of the package which was successfully
2547 <sect1 id="f-Conffiles"><heading><tt>Conffiles</tt>
2551 This field in <prgn>dpkg</prgn>'s status file contains
2552 information about the automatically-managed configuration
2553 files held by a package. This field should <em>not</em>
2554 appear anywhere in a package!</p>
2557 <sect1><heading>Obsolete fields
2561 These are still recognised by <prgn>dpkg</prgn> but should
2562 not appear anywhere any more.
2563 <taglist compact="compact">
2565 <tag><tt>Revision</tt></tag>
2566 <tag><tt>Package-Revision</tt></tag>
2567 <tag><tt>Package_Revision</tt></tag>
2570 The Debian revision part of the package version was
2571 at one point in a separate control file field. This
2572 field went through several names.</p>
2575 <tag><tt>Recommended</tt></tag>
2576 <item><p>Old name for <tt>Recommends</tt></p>
2579 <tag><tt>Optional</tt></tag>
2580 <item><p>Old name for <tt>Suggests</tt>.</p>
2582 <tag><tt>Class</tt></tag>
2583 <item><p>Old name for <tt>Priority</tt>.</p>
2591 <chapt id="versions"><heading>Version numbering
2595 Every package has a version number, in its <tt>Version</tt>
2600 <prgn>dpkg</prgn> imposes an ordering on version numbers, so
2601 that it can tell whether packages are being up- or downgraded
2602 and so that <prgn>dselect</prgn> can tell whether a package it
2603 finds available is newer than the one installed on the system.
2604 The version number format has the most significant parts (as
2605 far as comparison is concerned) at the beginning.
2609 The version number format is:
2610 &lsqb<var>epoch/<tt>:</tt>]<var>upstream-version</var>[<tt>-/<var>debian-revision</var>].</tt></var>
2614 The three components here are:
2616 <tag><var>epoch</var></tag>
2620 This is a single unsigned integer, which should usually
2621 be small. It may be omitted, in which case zero is
2622 assumed. If it is omitted then the
2623 <var>upstream-version</var> may not contain any colons.
2627 It is provided to allow mistakes in the version numbers
2628 of older versions of a package, and also a package's
2629 previous version numbering schemes, to be left behind.
2633 <prgn>dpkg</prgn> will not usually display the epoch
2634 unless it is essential (non-zero, or if the
2635 <var>upstream-version</var> contains a colon);
2636 <prgn>dselect</prgn> does not display epochs at all in
2637 the main part of the package selection display.</p>
2640 <tag><var>upstream-version</var></tag>
2644 This is the main part of the version. It is usually
2645 version number of the original (`upstream') package of
2646 which the <tt>.deb</tt> file has been made, if this is
2647 applicable. Usually this will be in the same format as
2648 that specified by the upstream author(s); however, it
2649 may need to be reformatted to fit into
2650 <prgn>dpkg</prgn>'s format and comparison scheme.
2654 The comparison behaviour of <prgn>dpkg</prgn> with
2655 respect to the <var>upstream-version</var> is described
2656 below. The <var>upstream-version</var> portion of the
2657 version number is mandatory.
2661 The <var>upstream-version</var> may contain only
2662 alphanumerics and the characters <tt>.</tt> <tt>+</tt>
2663 <tt>-</tt> <tt>:</tt> (full stop, plus, hyphen, colon)
2664 and should start with a digit. If there is no
2665 <var>debian-revision</var> then hyphens are not allowed;
2666 if there is no <var>epoch</var> then colons are not
2670 <tag><var>debian-revision</var></tag>
2674 This part of the version represents the version of the
2675 modifications that were made to the package to make it a
2676 Debian binary package. It is in the same format as the
2677 <var>upstream-version</var> and <prgn>dpkg</prgn>
2678 compares it in the same way.
2682 It is optional; if it isn't present then the
2683 <var>upstream-version</var> may not contain a hyphen.
2684 This format represents the case where a piece of
2685 software was written specifically to be turned into a
2686 Debian binary package, and so there is only one
2687 `debianization' of it and therefore no revision
2688 indication is required.
2692 It is conventional to restart the
2693 <var>debian-revision</var> at <tt>1</tt> each time the
2694 <var>upstream-version</var> is increased.
2698 <prgn>dpkg</prgn> will break the
2699 <var>upstream-version</var> and
2700 <var>debian-revision</var> apart at the last hyphen in
2701 the string. The absence of a <var>debian-revision</var>
2702 compares earlier than the presence of one (but note that
2703 the <var>debian-revision</var> is the least significant
2704 part of the version number).
2708 The <var>debian-revision</var> may contain only
2709 alphanumerics and the characters <tt>+</tt> and
2710 <tt>.</tt> (plus and full stop).
2714 The <var>upstream-version</var> and <var>debian-revision</var> parts are
2715 compared by <prgn>dpkg</prgn> using the same algorithm:
2719 The strings are compared from left to right.
2723 First the initial part of each string consisting entirely of
2724 non-digit characters is determined. These two parts (one of
2725 which may be empty) are compared lexically. If a difference
2726 is found it is returned. The lexical comparison is a
2727 comparison of ASCII values modified so that all the letters
2728 sort earlier than all the non-letters.
2732 Then the initial part of the remainder of each string which
2733 consists entirely of digit characters is determined. The
2734 numerical values of these two parts are compared, and any
2735 difference found is returned as the result of the comparison.
2736 For these purposes an empty string (which can only occur at
2737 the end of one or both version strings being compared) counts
2742 These two steps are repeated (chopping initial non-digit
2743 strings and initial digit strings off from the start) until a
2744 difference is found or both strings are exhausted.
2748 Note that the purpose of epochs is to allow us to leave behind
2749 mistakes in version numbering, and to cope with situations
2750 where the version numbering changes. It is <em>not</em> there
2751 to cope with version numbers containing strings of letters
2752 which <prgn>dpkg</prgn> cannot interpret (such as
2753 <tt>ALPHA</tt> or <tt>pre-</tt>), or with silly orderings (the
2754 author of this manual has heard of a package whose versions
2755 went <tt>1.1</tt>, <tt>1.2</tt>, <tt>1.3</tt>, <tt>1</tt>,
2756 <tt>2.1</tt>, <tt>2.2</tt>, <tt>2</tt> and so forth).
2760 If an upstream package has problematic version numbers they
2761 should be converted to a sane form for use in the
2762 <tt>Version</tt> field.
2766 If you need to compare version numbers in a script, you may use
2767 <tt>dpkg --compare-versions ...</tt>. Type <tt>dpkg
2768 --help</tt> --> --for details on arguments.
2772 <heading>Version numbers based on dates</heading>
2774 In general, Debian packages should use the same version
2775 numbers as the upstream sources.</p>
2778 However, in some cases where the upstream version number is
2779 based on a date (e.g., a development `snapshot' release)
2780 dpkg cannot handle these version numbers currently, without
2781 epochs. For example, dpkg will consider `96May01' to be
2782 greater than `96Dec24'.</p>
2785 To prevent having to use epochs for every new upstream
2786 version, the version number should be changed to the
2787 following format in such cases: `19960501', `19961224'. It
2788 is up to the maintainer whether he/she wants to bother the
2789 upstream maintainer to change the version numbers upstream,
2793 Note, that other version formats based on dates which are
2794 parsed correctly by dpkg should <em>not</em> be changed.</p>
2797 Native Debian packages (i.e., packages which have been
2798 written especially for Debian) whose version numbers include
2799 dates should always use the `YYYYMMDD' format.</p>
2803 <chapt id="maintainerscripts"><heading>Package maintainer scripts
2804 and installation procedure
2807 <sect><heading>Introduction to package maintainer scripts
2811 It is possible to supply scripts as part of a package which
2812 <prgn>dpkg</prgn> will run for you when your package is
2813 installed, upgraded or removed.
2817 These scripts should be the files <tt>preinst</tt>,
2818 <tt>postinst</tt>, <tt>prerm</tt> and <tt>postrm</tt> in the
2819 control area of the package. They must be proper exectuable
2820 files; if they are scripts (which is recommended) they must
2821 start with the usual <tt>#!</tt> convention. They should be
2822 readable and executable to anyone, and not world-writeable.
2826 <prgn>dpkg</prgn> looks at the exit status from these
2827 scripts. It is important that they exit with a non-zero
2828 status if there is an error, so that <prgn>dpkg</prgn> can
2829 stop its processing. For shell scripts this means that you
2830 <em>almost always</em> need to use <tt>set -e</tt> (this is
2831 usually true when writing shell scripts, in fact). It is
2832 also important, of course, that they don't exit with a
2833 non-zero status if everything went well.
2837 It is necessary for the error recovery procedures that the
2838 scripts be idempotent: ie, invoking the same script several
2839 times in the same situation should do no harm. If the first
2840 call failed, or aborted half way through for some reason,
2841 the second call should merely do the things that were left
2842 undone the first time, if any, and exit with a success
2847 When a package is upgraded a combination of the scripts from
2848 the old and new packages is called in amongst the other
2849 steps of the upgrade procedure. If your scripts are going
2850 to be at all complicated you need to be aware of this, and
2851 may need to check the arguments to your scripts.
2855 Broadly speaking the <prgn>preinst</prgn> is called before
2856 (a particular version of) a package is installed, and the
2857 <prgn>postinst</prgn> afterwards; the <prgn>prerm</prgn>
2858 before (a version of) a package is removed and the
2859 <prgn>postrm</prgn> afterwards.
2862 next paragraph by Guy Maor to close bug #2481
2865 <p> Programs called from maintainer scripts should not
2866 normally have a path prepended to them. Before installation
2867 is started <prgn>dpkg</prgn> checks to see if the programs
2868 <prgn>ldconfig</prgn>, <prgn>start-stop-daemon</prgn>,
2869 <prgn>install-info</prgn>, and <prgn>update-rc.d</prgn> can
2870 be found via the <tt>PATH</tt> environment variable. Those
2871 programs, and any other program that one would expect to on
2872 the <tt>PATH</tt>, should thus be invoked without an
2873 absolute pathname. Maintainer scripts should also not reset
2874 the <tt>PATH</tt>, though they might choose to modify it by
2875 pre- or appending package-specific directories. These
2876 considerations really apply to all shell scripts.</p>
2879 <sect id="mscriptsinstact"><heading>Summary of ways maintainer
2884 <list compact="compact">
2886 <p><var>new-preinst</var> <tt>install</tt></p>
2889 <p><var>new-preinst</var> <tt>install</tt>
2890 <var>old-version</var></p>
2893 <p><var>new-preinst</var> <tt>upgrade</tt>
2894 <var>old-version</var></p>
2897 <p><var>old-preinst</var> <tt>abort-upgrade</tt>
2898 <var>new-version</var>
2904 <list compact="compact">
2906 <p><var>postinst</var> <tt>configure</tt>
2907 <var>most-recently-configured-version</var></p>
2910 <p><var>old-postinst</var> <tt>abort-upgrade</tt>
2911 <var>new version</var></p>
2914 <p><var>conflictor's-postinst</var> <tt>abort-remove</tt>
2915 <tt>in-favour</tt> <var>package</var>
2916 <var>new-version</var></p>
2920 <var>deconfigured's-postinst</var>
2921 <tt>abort-deconfigure</tt> <tt>in-favour</tt>
2922 <var>failed-install-package</var> <var>version</var>
2923 <tt>removing</tt> <var>conflicting-package</var>
2930 <list compact="compact">
2932 <p><var>prerm</var> <tt>remove</tt></p>
2935 <p><var>old-prerm</var> <tt>upgrade</tt>
2936 <var>new-version</var></p>
2939 <p><var>new-prerm</var> <tt>failed-upgrade</tt>
2940 <var>old-version</var></p>
2943 <p><var>conflictor's-prerm</var> <tt>remove</tt>
2944 <tt>in-favour</tt> <var>package</var>
2945 <var>new-version</var></p>
2949 <var>deconfigured's-prerm</var> <tt>deconfigure</tt>
2950 <tt>in-favour</tt> <var>package-being-installed</var>
2951 <var>version</var> <tt>removing</tt>
2952 <var>conflicting-package</var>
2959 <list compact="compact">
2961 <p><var>postrm</var> <tt>remove</tt></p>
2964 <p><var>postrm</var> <tt>purge</tt></p>
2968 <var>old-postrm</var> <tt>upgrade</tt>
2969 <var>new-version</var></p>
2972 <p><var>new-postrm</var> <tt>failed-upgrade</tt>
2973 <var>old-version</var></p>
2976 <p><var>new-postrm</var> <tt>abort-install</tt></p>
2979 <p><var>new-postrm</var> <tt>abort-install</tt>
2980 <var>old-version</var></p>
2983 <p><var>new-postrm</var> <tt>abort-upgrade</tt>
2984 <var>old-version</var></p>
2988 <var>disappearer's-postrm</var> <tt>disappear</tt>
2989 <var>overwriter</var>
2990 <var>overwriter-version</var></p></item>
2995 <sect id="unpackphase"><heading>Details of unpack phase of
2996 installation or upgrade
3000 The procedure on installation/upgrade/overwrite/disappear
3001 (ie, when running <tt>dpkg --unpack</tt>, or the unpack
3003 --install</tt>) is as follows. In each case if an error occurs the
3004 actions in are general run backwards - this means that the maintainer
3005 scripts are run with different arguments in reverse order. These are
3006 the `error unwind' calls listed below.
3013 <p>If a version the package is already
3016 <var>old-prerm</var> upgrade <var>new-version</var>
3021 If this gives an error (ie, a non-zero exit
3022 status), dpkg will attempt instead:
3024 <var>new-prerm</var> failed-upgrade <var>old-version</var>
3026 Error unwind, for both the above cases:
3028 <var>old-postinst</var> abort-upgrade <var>new-version</var>
3036 <p>If a `conflicting' package is being removed at the same time:
3040 If any packages depended on that conflicting
3041 package and <tt>--auto-deconfigure</tt> is
3042 specified, call, for each such package:
3044 <var>deconfigured's-prerm</var> deconfigure \
3045 in-favour <var>package-being-installed</var> <var>version</var> \
3046 removing <var>conflicting-package</var> <var>version</var>
3050 <var>deconfigured's-postinst</var> abort-deconfigure \
3051 in-favour <var>package-being-installed-but-failed</var> <var>version</var> \
3052 removing <var>conflicting-package</var> <var>version</var>
3054 The deconfigured packages are marked as
3055 requiring configuration, so that if
3056 <tt>--install</tt> is used they will be
3057 configured again if possible.</p>
3060 <p>To prepare for removal of the conflicting package, call:
3062 <var>conflictor's-prerm</var> remove in-favour <var>package</var> <var>new-version</var>
3066 <var>conflictor's-postinst</var> abort-remove \
3067 in-favour <var>package</var> <var>new-version</var>
3078 <p>If the package is being upgraded, call:
3080 <var>new-preinst</var> upgrade <var>old-version</var>
3085 Otherwise, if the package had some configuration
3086 files from a previous version installed (ie, it
3087 is in the `configuration files only' state):
3089 <var>new-preinst</var> install <var>old-version</var>
3093 <p>Otherwise (ie, the package was completely purged):
3095 <var>new-preinst</var> install
3097 Error unwind versions, respectively:
3099 <var>new-postrm</var> abort-upgrade <var>old-version</var>
3100 <var>new-postrm</var> abort-install <var>old-version</var>
3101 <var>new-postrm</var> abort-install
3111 The new package's files are unpacked, overwriting any
3112 that may be on the system already, for example any
3113 from the old version of the same package or from
3114 another package (backups of the old files are left
3115 around, and if anything goes wrong dpkg will attempt
3116 to put them back as part of the error unwind).
3120 It is an error for a package to contains files which
3121 are on the system in another package, unless
3122 <tt>Replaces</tt> is used (see <ref id="replaces">).
3123 Currently the <tt>--force-overwrite</tt> flag is
3124 enabled, downgrading it to a warning, but this may not
3129 It is a more serious error for a package to contain a
3130 plain file or other kind of nondirectory where another
3131 package has a directory (again, unless
3132 <tt>Replaces</tt> is used). This error can be
3133 overridden if desired using
3134 <tt>--force-overwrite-dir</tt>, but this is not
3139 Packages which overwrite each other's files produce
3140 behaviour which though deterministic is hard for the
3141 system administrator to understand. It can easily
3142 lead to `missing' programs if, for example, a package
3143 is installed which overwrites a file from another
3144 package, and is then removed again.
3147 Part of the problem is due to what is arguably a
3148 bug in <prgn>dpkg</prgn> .
3154 A directory will never be replaced by a symbolic links
3155 to a directory or vice versa; instead, the existing
3156 state (symlink or not) will be left alone and
3157 <prgn>dpkg</prgn> will follow the symlink if there is
3165 <p>If the package is being upgraded, call
3167 <var>old-postrm</var> upgrade <var>new-version</var>
3171 <p>If this fails, <prgn>dpkg</prgn> will attempt:
3173 <var>new-postrm</var> failed-upgrade <var>old-version</var>
3175 Error unwind, for both cases:
3177 <var>old-preinst</var> abort-upgrade <var>new-version</var>
3182 This is the point of no return - if <prgn>dpkg</prgn>
3183 gets this far, it won't back off past this point if an
3184 error occurs. This will leave the package in a fairly
3185 bad state, which will require a successful
3186 reinstallation to clear up, but it's when
3187 <prgn>dpkg</prgn> starts doing things that are
3192 Any files which were in the old version of the package
3193 but not in the new are removed.</p>
3196 <p>The new file list replaces the old.</p>
3199 <p>The new maintainer scripts replace the old.</p>
3203 <p>Any packages all of whose files have been overwritten during the
3204 installation, and which aren't required for
3205 dependencies, are considered to have been removed.
3206 For each such package,
3209 <p><prgn>dpkg</prgn> calls:
3211 <var>disappearer's-postrm</var> disappear \
3212 <var>overwriter</var> <var>overwriter-version</var>
3217 <p>The package's maintainer scripts are removed.
3222 It is noted in the status database as being in a
3223 sane state, namely not installed (any conffiles
3224 it may have are ignored, rather than being
3225 removed by <prgn>dpkg</prgn>). Note that
3226 disappearing packages do not have their prerm
3227 called, because <prgn>dpkg</prgn> doesn't know
3228 in advance that the package is going to
3237 Any files in the package we're unpacking that are also
3238 listed in the file lists of other packages are removed
3239 from those lists. (This will lobotomise the file list
3240 of the `conflicting' package if there is one.)
3245 The backup files made during installation, above, are
3252 The new package's status is now sane, and recorded as
3253 `unpacked'. Here is another point of no return - if
3254 the conflicting package's removal fails we do not
3255 unwind the rest of the installation; the conflicting
3256 package is left in a half-removed limbo.
3261 If there was a conflicting package we go and do the
3262 removal actions (described below), starting with the
3263 removal of the conflicting package's files (any that
3264 are also in the package being installed have already
3265 been removed from the conflicting package's file list,
3266 and so do not get removed now).
3273 <sect><heading>Details of configuration
3277 When we configure a package (this happens with <tt>dpkg
3278 --install</tt>, or with <tt>--configure</tt>), we first
3279 update the conffiles and then call:
3281 <var>postinst</var> configure <var>most-recently-configured-version</var>
3286 No attempt is made to unwind after errors during
3291 If there is no most recently configured version
3292 <prgn>dpkg</prgn> will pass a null argument; older versions
3293 of dpkg may pass <tt><unknown></tt> (including the
3294 angle brackets) in this case. Even older ones do not pass a
3295 second argument at all, under any circumstances.
3299 <sect><heading>Details of removal and/or configuration purging
3307 <var>prerm</var> remove
3313 The package's files are removed (except conffiles).
3318 <var>postrm</var> remove
3322 <p>All the maintainer scripts except the postrm are removed.
3326 If we aren't purging the package we stop here. Note
3327 that packages which have no postrm and no conffiles
3328 are automatically purged when removed, as there is no
3329 difference except for the <prgn>dpkg</prgn>
3334 The conffiles and any backup files (<tt>~</tt>-files,
3335 <tt>#*#</tt> files, <tt>%</tt>-files,
3336 <tt>.dpkg-{old,new,tmp}</tt>, etc.) are removed.</p>
3340 <var>postrm</var> purge
3344 <p>The package's file list is removed.</p>
3347 No attempt is made to unwind after errors during
3352 <chapt id="descriptions"><heading>Descriptions of packages - the
3353 <tt>Description</tt> field
3357 The <tt>Description</tt> control file field is used by
3358 <prgn>dselect</prgn> when the user is selecting which packages
3359 to install and by <prgn>dpkg</prgn> when it displays
3360 information about the status of packages and so forth. It is
3361 included on the FTP site in the <prgn>Packages</prgn> files,
3362 and may also be used by the Debian WWW pages.
3366 The description is intended to describe the program to a user
3367 who has never met it before so that they know whether they
3368 want to install it. It should also give information about the
3369 significant dependencies and conflicts between this package
3370 and others, so that the user knows why these dependencies and
3371 conflicts have been declared.
3375 The field's format is as follows:
3377 Description: <var>single line synopsis</var>
3378 <var>extended description over several lines</var>
3383 The synopsis is often printed in lists of packages and so
3384 forth, and should be as informative as possible. Every
3385 package should also have an extended description.
3388 <sect><heading>Types of formatting line in the extended
3396 Those starting with a single space are part of a
3397 paragraph. Successive lines of this form will be
3398 word-wrapped when displayed. The leading space will
3399 usually be stripped off.
3405 Those starting with two or more spaces. These will be
3406 displayed verbatim. If the display cannot be panned
3407 horizontally the displaying program will linewrap them
3408 `hard' (ie, without taking account of word breaks).
3409 If it can they will be allowed to trail off to the
3410 right. None, one or two initial spaces may be
3411 deleted, but the number of spaces deleted from each
3412 line will be the same (so that you can have indenting
3413 work correctly, for example).
3418 <p>Those containing a single space followed by a single full stop
3419 character. These are rendered as blank lines. This
3420 is the <em>only</em> way to get a blank line - see
3426 Those containing a space, a full stop and some more
3427 characters. These are for future expansion. Do not
3434 <sect><heading>Notes about writing descriptions
3438 <em>Always</em> start extended description lines with at least one
3439 whitespace character. Fields in the control file and in the Packages
3440 file are separated by field names starting in the first column, just
3441 as message header fields are in RFC822. Forgetting the whitespace
3442 will cause <prgn>dpkg-deb</prgn>
3445 Version 0.93.23 or later.
3447 </footnote> to produce a syntax error when trying to build
3448 the package. If you force it to build anyway
3449 <prgn>dpkg</prgn> will refuse to install the resulting
3454 <em>Do not</em> include any completely <em>empty</em>
3455 lines. These separate different records in the Packages file
3456 and different packages in the <tt>debian/control</tt> file,
3457 and are forbidden in package control files. See the
3458 previous paragraph for what happens if you get this wrong.
3462 The single line synopsis should be kept brief - certainly
3463 under 80 characters. <prgn>dselect</prgn> displays between
3464 25 and 49 characters without panning if you're using an
3465 80-column terminal, depending on what display options are in
3470 Do not include the package name in the synopsis line. The
3471 display software knows how to display this already, and you
3472 do not need to state it. Remember that in many situations
3473 the user may only see the synopsis line - make it as
3474 informative as you can.
3478 The extended description should describe what the package
3479 does and how it relates to the rest of the system (in terms
3480 of, for example, which subsystem it is which part of).
3484 The blurb that comes with a program in its announcements
3485 and/or <prgn>README</prgn> files is rarely suitable for use
3486 in a description. It is usually aimed at people who are
3487 already in the community where the package is used. The
3488 description field needs to make sense to anyone, even people
3489 who have no idea about any of the things the package deals
3494 Put important information first, both in the synopis and
3495 extended description. Sometimes only the first part of the
3496 synopsis or of the description will be displayed. You can
3497 assume that there will usually be a way to see the whole
3498 extended description.
3502 You may include information about dependencies and so forth
3503 in the extended description, if you wish.
3507 Do not use tab characters. Their effect is not predictable.
3511 Do not try to linewrap the summary (the part on the same
3512 line as the field name <tt>Description</tt>) into the
3513 extended description. This will not work correctly when the
3514 full description is displayed, and makes no sense where only
3515 the summary is available.</p>
3518 <sect><heading>Example description in control file for Smail
3524 Version: 3.1.29.1-13
3525 Maintainer: Ian Jackson <iwj10@cus.cam.ac.uk>
3526 Recommends: pine | mailx | elm | emacs | mail-user-agent
3528 Depends: cron, libc5
3530 Provides: mail-transport-agent
3531 Description: Electronic mail transport system.
3532 Smail is the recommended mail transport agent (MTA) for Debian.
3534 An MTA is the innards of the mail system - it takes messages from
3535 user-friendly mailer programs and arranges for them to be delivered
3536 locally or passed on to other systems as required.
3538 In order to make use of it you must have one or more user level
3539 mailreader programs such as elm, pine, mailx or Emacs (which has Rmail
3540 and VM as mailreaders) installed. If you wish to send messages other
3541 than just to other users of your system you must also have appropriate
3542 networking support, in the form of IP or UUCP.
3548 <chapt id="relationships"><heading>Declaring relationships between
3553 Packages can declare in their control file that they have
3554 certain relationships to other packages - for example, that
3555 they may not be installed at the same time as certain other
3556 packages, and/or that they depend on the presence of others,
3557 or that they should overwrite files in certain other packages
3562 This is done using the <tt>Depends</tt>, <tt>Recommends</tt>,
3563 <tt>Suggests</tt>, <tt>Conflicts</tt>, <tt>Provides</tt> and
3564 <tt>Replaces</tt> control file fields.
3568 Source packages may declare relationships to binary packages,
3569 saying that they require certain binary packages being
3570 installed or absent at the time of building the package.
3574 This is done using the <tt>Build-Depends</tt>,
3575 <tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt>, and
3576 <tt>Build-Conflicts-Indep</tt> control file fields.
3579 <sect id="depsyntax"><heading>Syntax of relationship fields
3583 These fields all have a uniform syntax. They are a list of
3584 package names separated by commas.
3588 In <tt>Depends</tt>, <tt>Recommends</tt>, <tt>Suggests</tt>,
3589 <tt>Pre-Depends</tt>, <tt>Build-Depends</tt> and
3590 <tt>Build-Depends-Indep</tt>(the fields which declare
3591 dependencies of the package in which they occur on other
3592 packages) these package names may also be lists of
3593 alternative package names, separated by vertical bar symbols
3594 <tt>|</tt> (pipe symbols).
3598 All the fields except <tt>Provides</tt> may restrict their
3599 applicability to particular versions of each named package.
3600 This is done in parentheses after each individual package
3601 name; the parentheses should contain a relation from the
3602 list below followed by a version number, in the format
3603 described in <ref id="versions">.
3607 The relations allowed are <tt><<</tt>, <tt><=</tt>,
3608 <tt>=</tt>, <tt>>=</tt> and <tt>>></tt> for
3609 strictly earlier, earlier or equal, exactly equal, later or
3610 equal and strictly later, respectively. The forms
3611 <tt><</tt> and <tt>></tt> were used to mean
3612 earlier/later or equal, rather than strictly earlier/later,
3613 so they should not appear in new packages (though
3614 <prgn>dpkg</prgn> still supports them).
3618 Whitespace may appear at any point in the version
3619 specification, and must appear where it's necessary to
3620 disambiguate; it is not otherwise significant. For
3621 consistency and in case of future changes to
3622 <prgn>dpkg</prgn> it is recommended that a single space be
3623 used after a version relationship and before a version
3624 number; it is usual also to put a single space after each
3625 comma, on either side of each vertical bar, and before each
3634 Depends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh
3639 All fields that specify build-time relationships
3640 (<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
3641 <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>)
3642 may be restricted to a certain set of architectures. This
3643 is done in brackets after each individual package name and
3644 the optional version specification. The brackets enclose a
3645 list of Debian architecture names separated by whitespace.
3646 An exclamation mark may be prepended to each name. If the
3647 current Debian host architecture is not in this list and
3648 there are no exclamation marks in the list, or it is in the
3649 list with a prepended exclamation mark, the package name and
3650 the associated version specification are ignored completely
3651 for the purposes of defining the relationships.
3658 Build-Depends-Indep: texinfo
3659 Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
3660 hurd-dev [hurd-i386], gnumach-dev [hurd-i386]
3666 <heading>Binary Dependencies - <tt>Depends</tt>,
3667 <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Pre-Depends</tt>
3671 These four fields are used to declare a dependency by one
3672 package on another. They appear in the depending package's
3677 All but <tt>Pre-Depends</tt> (discussed below) take effect
3678 <em>only</em> when a package is to be configured. They do
3679 not prevent a package being on the system in an unconfigured
3680 state while its dependencies are unsatisfied, and it is
3681 possible to replace a package whose dependencies are
3682 satisfied and which is properly installed with a different
3683 version whose dependencies are not and cannot be satisfied;
3684 when this is done the depending package will be left
3685 unconfigured (since attempts to configure it will give
3686 errors) and will not function properly.
3690 For this reason packages in an installation run are usually
3691 all unpacked first and all configured later; this gives
3692 later versions of packages with dependencies on later
3693 versions of other packages the opportunity to have their
3694 dependencies satisfied.
3698 Thus <tt>Depends</tt> allows package maintainers to impose
3699 an order in which packages should be configured.
3701 <tag><tt>Depends</tt></tag>
3704 <p>This declares an absolute dependency.
3708 <prgn>dpkg</prgn> will not configure packages whose
3709 dependencies aren't satisfied. If it is asked to make
3710 an installation which would cause an installed
3711 package's dependencies to become unsatisfied it will
3715 Current versions (1.2.4) of <prgn>dpkg</prgn> have
3716 a bug in this area which will cause some of these
3717 problems to be ignored.
3719 </footnote>, unless <tt>--auto-deconfigure</tt> is
3720 specified, in which case those packages will be
3721 deconfigured before the installation proceeds.
3725 <prgn>dselect</prgn> makes it hard for the user to
3726 select packages for installation, removal or upgrade
3727 in a way that would mean that packages'
3728 <prgn>Depends</prgn> fields would be unsatisfied. The
3729 user can override this if they wish, for example if
3730 they know that <prgn>dselect</prgn> has an out-of-date
3731 view of the real package relationships.
3735 The <tt>Depends</tt> field should be used if the
3736 depended-on package is required for the depending
3737 package to provide a significant amount of
3741 <tag><tt>Recommends</tt></tag>
3743 <p>This declares a strong, but not absolute, dependency.
3747 <tt>Recommends</tt> is ignored by <prgn>dpkg</prgn>,
3748 so that users using the command-line (who are presumed
3749 to know what they're doing) will not be impeded.
3753 It is treated by <prgn>dselect</prgn> exactly as
3754 <tt>Depends</tt> is; this makes it hard for the user
3755 to select things so as to leave <tt>Recommends</tt>
3756 fields unsatisfied, but they are able to do so by
3761 The <tt>Recommends</tt> field should list packages
3762 that would be found together with this one in all but
3763 unusual installations.</p>
3766 <tag><tt>Suggests</tt></tag>
3770 This is used to declare that one package may be more
3771 useful with one or more others. Using this field
3772 tells the packaging system and the user that the
3773 listed packages are related to this one and can
3774 perhaps enhance its usefulness, but that installing
3775 this one without them is perfectly reasonable.
3779 <prgn>dselect</prgn> will offer suggsted packages to
3780 the system administrator when they select the
3781 suggesting package, but the default is not to install
3782 the suggested package.</p>
3785 <tag><tt>Pre-Depends</tt></tag>
3788 <p>This field is like <tt>Depends</tt>, except that it also forces
3789 <prgn>dpkg</prgn> to complete installation of the
3790 packages named before even starting the installation
3791 of the package which declares the predependency.
3795 <prgn>dselect</prgn> checks for predependencies when
3796 it is doing an installation run, and will attempt to
3797 find the packages which are required to be installed
3798 first and do so in the right order.
3802 However, this process is slow (because it requires
3803 repeated invocations of <prgn>dpkg</prgn>) and
3804 troublesome (because it requires guessing where to
3805 find the appropriate files).
3809 For these reasons, and because this field imposes
3810 restrictions on the order in which packages may be
3811 unpacked (which can be difficult for installations
3812 from multipart media, for example),
3813 <tt>Pre-Depends</tt> should be used sparingly,
3814 preferably only by packages whose premature upgrade or
3815 installation would hamper the ability of the system to
3816 continue with any upgrade that might be in progress.
3820 When the package declaring it is being configured, a
3821 <tt>Pre-Dependency</tt> will be considered satisfied
3822 only if the depending package has been correctly
3823 configured, just as if an ordinary <tt>Depends</tt>
3828 However, when a package declaring a predependency is
3829 being unpacked the predependency can be satisfied even
3830 if the depended-on package(s) are only unpacked or
3831 half-configured, provided that they have been
3832 configured correctly at some point in the past (and
3833 not removed or partially removed since). In this case
3834 both the previously-configured and currently unpacked
3835 or half-configured versions must satisfy any version
3836 clause in the <tt>Pre-Depends</tt> field.
3842 When selecting which level of dependency to use you should
3843 consider how important the depended-on package is to the
3844 functionality of the one declaring the dependency. Some
3845 packages are composed of components of varying degrees of
3846 importance. Such a package should list using
3847 <tt>Depends</tt> the package(s) which are required by the
3848 more important components. The other components'
3849 requirements may be mentioned as Suggestions or
3850 Recommendations, as appropriate to the components' relative
3854 <sect1><heading>Dependencies on shared libraries
3858 The dependency fields listed above are used by packages
3859 which need shared libraries to declare dependencies on the
3860 appropriate packages.
3864 These dependencies are usually determined automatically
3865 using <prgn>dpkg-shlibdeps</prgn> and inserted in the
3866 package control file using the control file substitution
3867 variables mechanism; see <ref id="srcsubstvars"> and
3868 <ref id="sourcetools">.
3872 <sect1><heading>Deconfiguration due to removal during bulk
3877 If <prgn>dpkg</prgn> would like to remove a package due to a
3878 conflict, as described above, but this would violate a
3879 dependency of some other package on the system,
3880 <prgn>dpkg</prgn> will usually not remove the conflicting
3881 package and halt with an error.
3885 However, if the <tt>--auto-deconfigure</tt> (<tt>-B</tt>)
3886 option is used <prgn>dpkg</prgn> will automatically
3887 `deconfigure' the package with the problematic dependency,
3888 so that the conflicting package can be removed and the
3889 package we're trying to install can be installed. If
3890 <prgn>dpkg</prgn> is being asked to install packages (rather
3891 than just unpacking them) it will try to reconfigure the
3892 package when it has unpacked all its arguments, in the hope
3893 that one of the other packages it is installing will satisfy
3894 the problematic dependency.
3898 <prgn>dselect</prgn> supplies this argument to
3899 <prgn>dpkg</prgn> when it invokes it, so that bulk
3900 installations proceed smoothly.
3904 <sect id="conflicts"><heading>Alternative binary packages -
3905 <tt>Conflicts</tt> and <tt>Replaces</tt>
3909 When one binary package declares a conflict with another
3910 <prgn>dpkg</prgn> will refuse to allow them to be installed
3911 on the system at the same time.
3915 If one package is to be installed, the other must be removed first -
3916 if the package being installed is marked as replacing (<ref
3917 id="replaces">) the one on the system, or the one on the system is
3918 marked as deselected, or both packages are marked
3919 <tt>Essential</tt>, then <prgn>dpkg</prgn> will
3920 automatically remove the package which is causing the
3921 conflict, otherwise it will halt the installation of the new
3922 package with an error.
3926 <prgn>dselect</prgn> makes it hard to select conflicting
3927 packages, though the user can override this if they wish.
3928 If they do not override it then <prgn>dselect</prgn> will
3929 select one of the packages for removal, and the user must
3930 make sure it is the right one. In the future
3931 <prgn>dselect</prgn> will look for the presence of a
3932 <tt>Replaces</tt> field to help decide which package should
3933 be installed and which removed.
3937 A package will not cause a conflict merely because its
3938 configuration files are still installed; it must be at least
3943 A special exception is made for packages which declare a
3944 conflict with their own package name, or with a virtual
3945 package which they provide (see below): this does not
3946 prevent their installation, and allows a package to conflict
3947 with others providing a replacement for it. You use this
3948 feature when you want the package in question to be the only
3949 package providing something.
3953 A <tt>Conflicts</tt> entry should almost never have an
3954 `earlier than' version clause. This would prevent
3955 <prgn>dpkg</prgn> from upgrading or installing the package
3956 which declared such a conflict until the upgrade or removal
3957 of the conflicted-with package had been completed. This
3958 aspect of installation ordering is not handled by
3959 <prgn>dselect</prgn>, so that the use <tt>Conflicts</tt> in
3960 this way is likely to cause problems for `bulk run' upgrades
3965 <sect id="virtual"><heading>Virtual packages - <tt>Provides</tt>
3969 As well as the names of actual (`concrete') packages, the
3970 package relationship fields <tt>Depends</tt>,
3971 <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
3972 <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Conflicts</tt>,
3973 <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt> may
3974 mention virtual packages.
3978 A virtual package is one which appears in the
3979 <tt>Provides</tt> control file field of another package.
3980 The effect is as if the package(s) which provide a
3981 particular virtual package name had been listed by name
3982 everywhere the virtual package name appears.
3986 If there are both a real and a virtual package of the same
3987 name then the dependency may be satisfied (or the conflict
3988 caused) by either the real package or any of the virtual
3989 packages which provide it. This is so that, for example,
3995 and someone else releases an xemacs package they can say
3999 </example> and all will work in the interim (until a purely
4000 virtual package name is decided on and the <tt>emacs</tt>
4001 and <tt>vm</tt> packages are changed to use it).
4005 If a dependency or a conflict has a version number attached
4006 then only real packages will be considered to see whether
4007 the relationship is satisfied (or the prohibition violated,
4008 for a conflict) - it is assumed that a real package which
4009 provides virtual package is not of the `right' version. So,
4010 a <tt>Provides</tt> field may not contain version numbers,
4011 and the version number of the concrete package which
4012 provides a particular virtual package will not be looked at
4013 when considering a dependency on or conflict with the
4014 virtual package name.
4018 It is likely that the ability will be added in a future
4019 release of <prgn>dpkg</prgn> to specify a version number for
4020 each virtual package it provides. This feature is not yet
4021 present, however, and is expected to be used only
4026 If you want to specify which of a set of real packages should be the
4027 default to satisfy a particular dependency on a virtual package, you
4028 should list the real package as an alternative before the virtual.
4033 <sect id="replaces"><heading><tt>Replaces</tt> - overwriting
4034 files and replacing packages
4038 The <tt>Replaces</tt> control file field has two purposes,
4039 which come into play in different situations.
4043 Virtual packages (<ref id="virtual">) are not considered
4044 when looking at a <tt>Replaces</tt> field - the packages
4045 declared as being replaced must be mentioned by their real
4049 <sect1><heading>Overwriting files in other packages
4053 Firstly, as mentioned before, it is usually an error for a
4054 package to contains files which are on the system in
4055 another package, though currently the
4056 <tt>--force-overwrite</tt> flag is enabled by default,
4057 downgrading the error to a warning,
4061 If the overwriting package declares that it replaces the
4062 one containing the file being overwritten then
4063 <prgn>dpkg</prgn> will proceed, and replace the file from
4064 the old package with that from the new. The file will no
4065 longer be listed as `owned' by the old package.
4069 If a package is completely replaced in this way, so that
4070 <prgn>dpkg</prgn> does not know of any files it still
4071 contains, it is considered to have disappeared. It will
4072 be marked as not wanted on the system (selected for
4073 removal) and not installed. Any conffiles details noted
4074 in the package will be ignored, as they will have been
4075 taken over by the replacing package(s). The package's
4076 <prgn>postrm</prgn> script will be run to allow the
4077 package to do any final cleanup required. See <ref
4078 id="mscriptsinstact">.
4082 In the future <prgn>dpkg</prgn> will discard files which
4083 overwrite those from another package which declares that
4084 it replaces the one being installed (so that you can
4085 install an older version of a package without problems).
4089 This usage of <tt>Replaces</tt> only takes effect when
4090 both packages are at least partially on the system at
4091 once, so that it can only happen if they do not conflict
4092 or if the conflict has been overridden.</p>
4095 <sect1><heading>Replacing whole packages, forcing their
4100 Secondly, <tt>Replaces</tt> allows <prgn>dpkg</prgn> and
4101 <prgn>dselect</prgn> to resolve which package should be
4102 removed when there is a conflict - see <ref id="conflicts">. This
4103 usage only takes effect when the two packages <em>do</em>
4104 conflict, so that the two effects do not interfere with
4110 <sect><heading>Defaults for satisfying dependencies - ordering
4114 Ordering is significant in dependency fields.
4118 Usually dselect will suggest to the user that they select
4119 the package with the most `fundamental' class (eg, it will
4120 prefer Base packages to Optional ones), or the one that they
4121 `most wanted' to select in some sense.
4125 In the absence of other information <prgn>dselect</prgn>
4126 will offer a default selection of the first named package in
4127 a list of alternatives.
4131 However, there is no way to specify the `order' of several
4132 packages which all provide the same thing, when that thing
4133 is listed as a dependency.
4137 Therefore a dependency on a virtual package should contain a
4138 concrete package name as the first alternative, so that this
4143 For example, consider the set of packages:
4146 Recommends: info-browser
4149 Provides: info-browser
4152 Provides: info-browser
4157 If <prgn>emacs</prgn> and <prgn>info</prgn> both have the
4158 same priority then <prgn>dselect</prgn>'s choice is
4159 essentially random. Better would be
4162 Recommends: info | info-browser
4164 so that <prgn>dselect</prgn> defaults to selecting the
4165 lightweight standalone info browser.
4170 <sect><heading>Relationships between source and binary packages -
4171 <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
4172 <tt>Build-Conflicts</tt>, <tt>Build-Conflicts-Indep</tt>
4176 A source package may declare a dependency or a conflict on a
4177 binary package. This is done with the control file fields
4178 <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
4179 <tt>Build-Conflicts</tt>, and <tt>Build-Conflicts-Indep</tt>. Their
4180 semantics is that the dependencies and conflicts they define
4181 must be satisfied (as defined earlier for binary packages),
4182 when one of the targets in <tt>debian/rules</tt> that the
4183 particular field applies to is invoked.
4186 <tag><tt>Build-Depends</tt>, <tt>Build-Conflicts</tt></tag>
4189 The <tt>Build-Depends</tt> and <tt>Build-Conflicts</tt> fields apply
4191 <tt>build</tt>, <tt>binary</tt>, <tt>binary-arch</tt>
4192 and <tt>binary-indep</tt>.
4195 <tag><tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts-Indep</tt></tag>
4198 The <tt>Build-Depends-Indep</tt> and
4199 <tt>Build-Conflicts-Indep</tt> fields apply to the
4200 targets <tt>binary</tt> and <tt>binary-indep</tt>.
4211 <chapt id="conffiles"><heading>Configuration file handling
4215 <prgn>dpkg</prgn> can do a certain amount of automatic
4216 handling of package configuration files.
4220 Whether this mechanism is appropriate depends on a number of
4221 factors, but basically there are two approaches to any
4222 particular configuration file.
4226 The easy method is to ship a best-effort configuration in the
4227 package, and use <prgn>dpkg</prgn>'s conffile mechanism to
4228 handle updates. If the user is unlikely to want to edit the
4229 file, but you need them to be able to without losing their
4230 changes, and a new package with a changed version of the file
4231 is only released infrequently, this is a good approach.
4235 The hard method is to build the configuration file from
4236 scratch in the <prgn>postinst</prgn> script, and to take the
4237 responsibility for fixing any mistakes made in earlier
4238 versions of the package automatically. This will be
4239 appropriate if the file is likely to need to be different on
4243 <sect><heading>Automatic handling of configuration files by
4248 A package may contain a control area file called
4249 <tt>conffiles</tt>. This file should be a list of filenames
4250 of configuration files needing automatic handling, separated
4251 by newlines. The filenames should be absolute pathnames,
4252 and the files referred to should actually exist in the
4257 When a package is upgraded <prgn>dpkg</prgn> will process
4258 the configuration files during the configuration stage,
4259 shortly before it runs the package's <prgn>postinst</prgn>
4264 For each file it checks to see whether the version of the
4265 file included in the package is the same as the one that was
4266 included in the last version of the package (the one that is
4267 being upgraded from); it also compares the version currently
4268 installed on the system with the one shipped with the last
4273 If neither the user nor the package maintainer has changed
4274 the file, it is left alone. If one or the other has changed
4275 their version, then the changed version is preferred - i.e.,
4276 if the user edits their file, but the package maintainer
4277 doesn't ship a different version, the user's changes will
4278 stay, silently, but if the maintainer ships a new version
4279 and the user hasn't edited it the new version will be
4280 installed (with an informative message). If both have
4281 changed their version the user is prompted about the problem
4282 and must resolve the differences themselves.
4286 The comparisons are done by calculating the MD5 message
4287 digests of the files, and storing the MD5 of the file as it
4288 was included in the most recent version of the package.
4292 When a package is installed for the first time
4293 <prgn>dpkg</prgn> will install the file that comes with it,
4294 unless that would mean overwriting a file already on the
4299 However, note that <prgn>dpkg</prgn> will <em>not</em>
4300 replace a conffile that was removed by the user (or by a
4301 script). This is necessary because with some programs a
4302 missing file produces an effect hard or impossible to
4303 achieve in another way, so that a missing file needs to be
4304 kept that way if the user did it.
4308 Note that a package should <em>not</em> modify a
4309 <prgn>dpkg</prgn>-handled conffile in its maintainer
4310 scripts. Doing this will lead to <prgn>dpkg</prgn> giving
4311 the user confusing and possibly dangerous options for
4312 conffile update when the package is upgraded.</p>
4315 <sect><heading>Fully-featured maintainer script configuration
4320 For files which contain site-specific information such as
4321 the hostname and networking details and so forth, it is
4322 better to create the file in the package's
4323 <prgn>postinst</prgn> script.
4327 This will typically involve examining the state of the rest
4328 of the system to determine values and other information, and
4329 may involve prompting the user for some information which
4330 can't be obtained some other way.
4334 When using this method there are a couple of important
4335 issues which should be considered:
4339 If you discover a bug in the program which generates the
4340 configuration file, or if the format of the file changes
4341 from one version to the next, you will have to arrange for
4342 the postinst script to do something sensible - usually this
4343 will mean editing the installed configuration file to remove
4344 the problem or change the syntax. You will have to do this
4345 very carefully, since the user may have changed the file,
4346 perhaps to fix the very problem that your script is trying
4347 to deal with - you will have to detect these situations and
4348 deal with them correctly.
4352 If you do go down this route it's probably a good idea to
4353 make the program that generates the configuration file(s) a
4354 separate program in <tt>/usr/sbin</tt>, by convention called
4355 <tt><var>package</var>config</tt> and then run that if
4356 appropriate from the post-installation script. The
4357 <tt><var>package</var>config</tt> program should not
4358 unquestioningly overwrite an existing configuration - if its
4359 mode of operation is geared towards setting up a package for
4360 the first time (rather than any arbitrary reconfiguration
4361 later) you should have it check whether the configuration
4362 already exists, and require a <tt>--force</tt> flag to
4363 overwrite it.</p></sect>
4368 <chapt id="alternatives"><heading>Alternative versions of an interface -
4369 <prgn>update-alternatives</prgn>
4373 When several packages all provide different versions of the
4374 same program or file it is useful to have the system select a
4375 default, but to allow the system administrator to change it
4376 and have their decisions respected.
4380 For example, there are several versions of the <prgn>vi</prgn>
4381 editor, and there is no reason to prevent all of them from
4382 being installed at once, each under their own name
4383 (<prgn>nvi</prgn>, <prgn>vim</prgn> or whatever).
4384 Nevertheless it is desirable to have the name <tt>vi</tt>
4385 refer to something, at least by default.
4389 If all the packages involved cooperate, this can be done with
4390 <prgn>update-alternatives</prgn>.
4394 Each package provides its own version under its own name, and
4395 calls <prgn>update-alternatives</prgn> in its postinst to
4396 register its version (and again in its prerm to deregister
4401 See the manpage <manref name="update-alternatives"
4402 section="8"> for details.
4406 If <prgn>update-alternatives</prgn> does not seem appropriate
4407 you may wish to consider using diversions instead.</p>
4411 <chapt id="diversions"><heading>Diversions - overriding a
4412 package's version of a file
4416 It is possible to have <prgn>dpkg</prgn> not overwrite a file
4417 when it reinstalls the package it belongs to, and to have it
4418 put the file from the package somewhere else instead.
4422 This can be used locally to override a package's version of a
4423 file, or by one package to override another's version (or
4424 provide a wrapper for it).
4428 Before deciding to use a diversion, read <ref
4429 id="alternatives"> to see if you really want a diversion
4430 rather than several alternative versions of a program.
4434 There is a diversion list, which is read by <prgn>dpkg</prgn>,
4435 and updated by a special program <prgn>dpkg-divert</prgn>.
4436 Please see <manref name="dpkg-divert" section="8"> for full
4437 details of its operation.
4441 When a package wishes to divert a file from another, it should
4442 call <prgn>dpkg-divert</prgn> in its preinst to add the
4443 diversion and rename the existing file. For example,
4444 supposing that a <prgn>smailwrapper</prgn> package wishes to
4445 install a wrapper around <tt>/usr/sbin/smail</tt>:
4447 if [ install = "$1" ]; then
4448 dpkg-divert --package smailwrapper --add --rename \
4449 --divert /usr/sbin/smail.real /usr/sbin/smail
4451 </example> Testing <tt>$1</tt> is necessary so that the script
4452 doesn't try to add the diversion again when
4453 <prgn>smailwrapper</prgn> is upgraded. The <tt>--package
4454 smailwrapper</tt> ensures that <prgn>smailwrapper</prgn>'s
4455 copy of <tt>/usr/sbin/smail</tt> can bypass the diversion and
4456 get installed as the true version.
4460 The postrm has to do the reverse:
4462 if [ remove = "$1" ]; then
4463 dpkg-divert --package smailwrapper --remove --rename \
4464 --divert /usr/sbin/smail.real /usr/sbin/smail
4470 Do not attempt to divert a file which is vitally important for
4471 the system's operation - when using <prgn>dpkg-divert</prgn>
4472 there is a time, after it has been diverted but before
4473 <prgn>dpkg</prgn> has installed the new version, when the file
4478 <chapt id="sharedlibs"><heading>Shared libraries
4482 Packages containing shared libraries must be constructed with
4483 a little care to make sure that the shared library is always
4484 available. This is especially important for packages whose
4485 shared libraries are vitally important, such as the libc.
4489 Firstly, your package should install the shared libraries
4490 under their normal names. For example, the
4491 <prgn>libgdbm1</prgn> package should install
4492 <tt>libgdbm.so.1.7.3</tt> as
4493 <tt>/usr/lib/libgdbm.so.1.7.3</tt>. The files should not be
4494 renamed or relinked by any prerm or postrm scripts;
4495 <prgn>dpkg</prgn> will take care of renaming things safely
4496 without affecting running programs, and attempts to interfere
4497 with this are likely to lead to problems.
4501 Secondly, your package should include the symlink that
4502 <prgn>ldconfig</prgn> would create for the shared libraries.
4503 For example, the <prgn>libgdbm1</prgn> package should include
4504 a symlink from <tt>/usr/lib/libgdbm.so.1</tt> to
4505 <tt>libgdbm.so.1.7.3</tt>. This is needed so that
4506 <prgn>ld.so</prgn> can find the library in between the time
4507 <prgn>dpkg</prgn> installs it and <prgn>ldconfig</prgn> is run
4508 in the <prgn>postinst</prgn> script. Futhermore, and <em>this
4509 is very important</em>, the library must be placed before the
4510 symlink pointing to it in the <tt>.deb</tt> file. This is so
4511 that by the time <prgn>dpkg</prgn> comes to install the
4512 symlink (overwriting the previous symlink pointing at an older
4513 version of the library) the new shared library is already in
4514 place. Currently the way to ensure the ordering is done
4515 properly is to install the library in the appropriate
4516 <tt>debian/tmp/.../lib</tt> directory before creating the
4517 symlink, by putting the commands in the <tt>debian/rules</tt>
4518 in the appropriate order. Whether this has been done
4519 correctly can be checked by performing an <tt>ls -f</tt>.
4523 next Paragraph added to close Bug #5299, Guy Maor
4527 Thirdly, the development package should contain a symlink for
4528 the shared library without a version number. For example, the
4529 <tt>libgdbm1-dev</tt> package should include a symlink from
4530 <tt>/usr/lib/libgdm.so</tt> to <tt>libgdm.so.1.7.3</tt>. This
4531 symlink is needed by <prgn>ld</prgn> when compiling packages
4532 as it will only look for <tt>libgdm.so</tt> and
4533 <tt>libgdm.a</tt> when compiling dynamically or statically,
4538 next paragraph changed by Christian Schwarz (see policy weekly #6)
4542 Any package installing shared libraries in a directory that's listed
4543 in <tt>/etc/ld.so.conf</tt> or in one of the default library
4544 directories of <prgn>ld.so</prgn> (currently, these are <tt>/usr/lib</tt>
4545 and <tt>/lib</tt>) must call <prgn>ldconfig</prgn> in its <prgn>postinst</prgn>
4546 script if and only if the first argument is `configure'. However, it
4547 is important not to call <prgn>ldconfig</prgn> in the postrm or preinst
4548 scripts in the case where the package is being upgraded (see <ref
4549 id="unpackphase">), as <prgn>ldconfig</prgn> will see the temporary names
4550 that <prgn>dpkg</prgn> uses for the files while it is
4551 installing them and will make the shared library links point
4552 to them, just before <prgn>dpkg</prgn> continues the
4553 installation and removes the links!
4557 moved from section 2.2 , DMorris
4560 <sect id="shlibs"><heading>The <tt>shlibs</tt> File Format
4564 This file is for use by <prgn>dpkg-shlibdeps</prgn> and is
4565 required when your package provides shared libraries.
4569 Each line is of the form:
4571 <var>library-name</var> <var>version-or-soname</var> <var>dependencies ...</var>
4576 <var>library-name</var> is the name of the shared library,
4577 for example <tt>libc5</tt>.
4581 <var>version-or-soname</var> is the soname of the library -
4582 ie, the thing that must exactly match for the library to be
4583 recognised by <prgn>ld.so</prgn>. Usually this is major
4584 version number of the library.
4588 <var>dependencies</var> has the same syntax as a dependency
4589 field in a binary package control file. It should give
4590 details of which package(s) are required to satisfy a binary
4591 built against the version of the library contained in the
4592 package. See <ref id="depsyntax">.
4596 For example, if the package <tt>foo</tt> contains
4597 <tt>libfoo.so.1.2.3</tt>, where the soname of the library is
4598 <tt>libfoo.so.1</tt>, and the first version of the package
4599 which contained a minor number of at least <tt>2.3</tt> was
4600 <var>1.2.3-1</var>, then the package's <var>shlibs</var>
4603 libfoo 1 foo (>= 1.2.3-1)
4608 The version-specific dependency is to avoid warnings from
4609 <prgn>ld.so</prgn> about using older shared libraries with
4613 <sect><heading>Further Technical information on
4614 <tt>shlibs</tt></heading>
4618 following section mostly provided by Heiko Schlittermann
4622 <sect1><heading><em>What</em> are the <tt>shlibs</tt> files?
4626 The <tt>debian/shlibs</tt> file provides a way of checking
4627 for shared library dependencies on packaged binaries.
4628 They are intended to be used by package maintainers to
4629 make their lives easier.
4633 Other <tt>shlibs</tt> files that exist on a Debian system are
4635 <item> <p><tt>/etc/dpkg/shlibs.default</tt></p></item>
4636 <item> <p><tt>/etc/dpkg/shlibs.override</tt></p></item>
4637 <item> <p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
4638 <item> <p><tt>debian/shlibs.local</tt></p></item>
4640 These files are used by <prgn>dpkg-shlibdeps</prgn> when
4641 creating a binary package.</p>
4644 <sect1><heading><em>How</em> does <prgn>dpkg-shlibdeps</prgn>
4649 <prgn>dpkg-shlibdeps</prgn> calls <prgn>ldd</prgn> to
4650 determine the shared libraries used by the compiled
4651 binaries passed through its command line.
4655 For each shared library, <prgn>dpkg-shlibdeps</prgn> needs to know
4656 <list compact="compact">
4657 <item><p>the package containing the library, and</p></item>
4658 <item><p>the library version number,</p></item>
4661 it scans the following files in this order.
4662 <enumlist compact="compact">
4663 <item><p><tt>debian/shlibs.local</tt></p></item>
4664 <item><p><tt>/etc/dpkg/shlibs.override</tt></p></item>
4665 <item><p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
4666 <item><p><tt>/etc/dpkg/shlibs.default</tt></p></item>
4670 <sect1><heading><em>Who</em> maintains the various
4671 <tt>shlibs</tt> files?
4675 <list compact="compact">
4677 <p><tt>/etc/dpkg/shlibs.default</tt> - the maintainer
4682 <tt>/var/lib/dpkg/info/<var>package</var>.shlibs</tt>
4683 - the maintainer of each package</p>
4687 <tt>/etc/dpkg/shlibs.override</tt> - the local
4688 system administrator</p>
4691 <p><tt>debian/shlibs.local</tt> - the maintainer of
4696 The <tt>shlibs.default</tt> file is managed by
4697 <prgn>dpkg</prgn>. The entries in <tt>shlibs.default</tt>
4698 that are provided by <prgn>dpkg</prgn> are just there to
4699 fix things until the shared library packages all have
4700 <tt>shlibs</tt> files.
4704 <sect1><heading><em>How</em> to use <prgn>dpkg-shlibdeps</prgn> and
4705 the <tt>shlibs</tt> files?
4708 <sect2><heading>If your package doesn't provide a shared
4713 Put a call to <prgn>dpkg-shlibdeps</prgn> into your
4714 <tt>debian/rules</tt> file. If your package contains
4715 only binaries (e.g. no scripts) use:
4717 dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/*
4719 If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
4720 done. If it does complain you might need to create your
4721 own <tt>debian/shlibs.local</tt> file.</p>
4724 <sect2><heading>If your package provides a shared library
4728 Create a <tt>debian/shlibs</tt> file and let
4729 <tt>debian/rules</tt> install it in the control area:
4731 install -m644 debian/shlibs debian/tmp/DEBIAN
4733 If your package contains additional binaries see above.
4738 <sect1><heading><em>How</em> to write
4739 <tt>debian/shlibs.local</tt>
4743 This file is intended only as a <em>temporary</em> fix if
4744 your binaries depend on a library which doesn't provide
4745 its own <tt>/var/lib/dpkg/info/*.shlibs</tt> file yet.
4749 Let's assume you are packaging a binary <tt>foo</tt>. Your
4750 output in building the package might look like this.
4753 libbar.so.1 => /usr/X11R6/lib/libbar.so.1.0
4754 libc.so.5 => /lib/libc.so.5.2.18
4755 libX11.so.6 => /usr/X11R6/lib/libX11.so.6.0
4757 And when you ran <prgn>dpkg-shlibdeps</prgn>
4759 $ dpkg-shlibdeps -o foo
4760 dpkg-shlibdeps: warning: unable to find dependency information
4761 for shared library libbar
4762 (soname 1, path /usr/X11R6/lib/libbar.so.1.0, dependency field Depends)
4763 shlibs:Depends=elf-x11r6lib, libc5 (>= 5.2.18)
4765 The <prgn>foo</prgn> binary depends on the
4766 <prgn>libbar</prgn> shared library, but no package seems
4767 to provide a <tt>*.shlibs</tt> file in
4768 <tt></tt>var/lib/dpkg/info/. Let's determine the package
4774 $ dpkg -S /usr/X11R6/lib/libbar.so.1.0
4775 bar1: /usr/X11R6/lib/libbar.so.1.0
4776 $ dpkg -s bar1 | grep Version
4779 This tells us that the <prgn>bar1</prgn> package, version
4780 1.0-1 is the one we are using. Now we can create our own
4781 <tt>debian/shlibs.local</tt> to temporarly fix the above
4782 problem. Include the following line into your
4783 <tt>debian/shlibs.local</tt> file.
4785 libbar 1 bar1 (>= 1.0-1)
4787 Now your package build should work. As soon as the
4788 maintainer of <prgn>libbar1</prgn> provides a
4789 <tt>shlibs</tt> file, you can remove your
4790 <tt>debian/shlibs.local</tt> file.
4796 <chapt id="methif"><heading><prgn>dselect</prgn>'s interface to
4797 its installation methods
4801 <prgn>dselect</prgn> calls scripts from its installation
4802 methods when it needs to actually access data from the
4803 distribution. The core program <prgn>dselect</prgn> itself
4804 just calls these scripts and provides the package and access
4805 method selection interfaces. The installation methods are
4806 responsible for invoking <prgn>dpkg</prgn> as appropriate.
4810 Each installation method has three scripts:
4811 <list compact="compact">
4812 <item><p>Setup installation parameters.</p></item>
4813 <item><p>Update list of available packages.</p></item>
4814 <item><p>Install.</p></item>
4818 <prgn>dselect</prgn> searches for methods in
4819 <tt>/usr/lib/dpkg/methods</tt> and
4820 <tt>/usr/local/lib/dpkg/methods</tt>.
4823 <sect><heading>Functions of the method scripts
4827 The setup script is run just after the user has chosen an
4828 installation method. It should prompt the user for
4829 parameters like the site to NFS-mount or FTP from, the
4830 directory to use, or the directory or filesystem where the
4831 <tt>.deb</tt> files can be found, or the tape or floppy
4832 device to install from. It should store the responses under
4833 <tt>/var/lib/dpkg/methods</tt> - see below. If no available
4834 packages list is available it should perhaps offer to scan
4835 the available packages.
4839 The update script should obtain a list of available packages
4840 if possible, and run <tt>dpkg --update-avail</tt>, <tt>dpkg
4841 --merge-avail</tt> and/or <tt>dpkg --forget-old-unavail</tt>
4842 to load it into <prgn>dpkg</prgn> and <prgn>dselect</prgn>'s
4843 database of available packages. If no packages list was
4844 available and the user was offered and accepted the option
4845 of scanning the actual files available this scan should be
4846 done here, using <tt>dpkg --record-avail</tt>.
4850 The install script should feed all the available
4851 <tt>.deb</tt> files to <tt>dpkg --iGOEB</tt> (this is
4852 equivalent to <tt>dpkg --install
4853 --refuse-downgrade --selected-only --skip-same-version
4854 --auto-deconfigure</tt>). The <tt>-R</tt>
4855 (<tt>--recursive</tt>) option for traversing subdirectories
4856 may also be useful here).
4860 If any of these scripts needs to display a message for the
4861 user, it should wait for the user to hit `return' before
4862 exiting so that dselect doesn't immediately rewrite the
4867 If a method script succeeds (returns a zero exit status)
4868 <prgn>dselect</prgn> will return immediately to the main
4869 menu, with the `next' option highlighted ready for the user
4870 to select it. If it fails <prgn>dselect</prgn> will display
4871 a message and wait for the user to hit return.</p>
4874 <sect><heading>Location and arguments of the method scripts
4878 A set of scripts (henceforth known as a group) may provide
4879 several methods on the `main menu' with different behaviour.
4880 For example, there might be a generic get-packages-by-FTP
4881 group which might provide methods in the main menu for
4882 installation directly from one of the Debian mirror sites as
4883 well as for installation from a user-specified site.
4887 Each group of methods implemented by the same set of scripts
4888 should have a subdirectory
4889 <tt>/usr/lib/dpkg/methods/<var>group</var></tt> or
4890 <tt>/usr/local/lib/dpkg/methods/<var>group</var></tt>,
4892 <taglist compact="compact">
4893 <tag><tt>names</tt></tag>
4894 <item><p>a list of user-visible methods provided by these scripts.</p>
4896 <tag><tt>setup</tt></tag>
4897 <tag><tt>update</tt></tag>
4898 <tag><tt>install</tt></tag>
4899 <item><p>executable programs, the scripts themselves.</p>
4901 <tag><tt>desc.<var>option</var></tt></tag>
4902 <item><p>description file.</p></item>
4907 <tt>names</tt> will be formatted as a list of lines, each containing:
4909 <var>sequence</var> <var>method</var> <var>summary</var>
4913 <var>sequence</var> is a two-digit number that will be used
4914 much like <tt>rc.d</tt> prefixes to control the order in the
4915 main menu. If in doubt use 50.
4919 <var>method</var> is a name which is displayed by
4920 <prgn>dselect</prgn> as the name of the method, and which
4921 will be passed to <tt>setup</tt>, <tt>update</tt> and
4922 <tt>unpack</tt> as their first argument.
4926 <var>summary</var> is the brief description string for
4927 <prgn>dselect</prgn>'s menu.
4931 Each of the three scripts gets the same three arguments:
4932 <var>vardir</var>, <var>group</var> and <var>method</var>.
4933 <var>vardir</var> is the base directory for storing
4934 <prgn>dpkg</prgn> and <prgn>dselect</prgn>'s state, usually
4935 <tt>/var/lib/dpkg</tt>; this is passed in so that the
4936 <tt>--admindir</tt> option to <prgn>dselect</prgn> is
4941 Each option may have an extended description in
4942 <tt>desc.<var>option</var></tt>. This should be formatted
4943 like the extended description part of a <tt>Description</tt>
4944 field entry <em>shifted one character to the left</em>.
4948 <tt><var>vardir</var>/methods</tt> will exist, and a method
4950 <tt><var>vardir</var>/methods/<var>group</var></tt>
4951 directory to store its state.
4955 The group name and method name must follow the rules for C
4961 <chapt id="conversion"><heading>Conversion procedure from old
4966 This is a brief summary of the procedure for converting a
4967 pre-2.0.0.0-format source package into the new format.
4971 You are strongly advised to download and examine the <prgn>hello</prgn>
4972 package, and to read the section in the <prgn>dpkg</prgn> programmers'
4973 manual describing the source packaging tools. More detail about the
4974 exact functionality of these tools is available in
4975 <manref name="dpkg-source" section="1">.
4982 Download the original source code from wherever it can
4983 be found and do any rearrangement required to make it
4984 look like the original tree of the Debian source. Put
4986 <tt><var>package</var>-<var>upstream-version</var>.orig/</tt>
4988 <tt><var>package</var>_<var>upstream-version</var>.orig.tar.gz</tt>.
4994 Rename all files <tt>debian.*</tt> to <tt>debian/*</tt>.
4995 There may be some exceptions to this, but this is a good
5001 Edit the <tt>debian/changelog</tt> - create or rename it
5002 if necessary. Add a new revision to the top with the
5003 appropriate details, and a local variables entry to the
5004 bottom to set Emacs to the right mode:
5007 mode: debian-changelog
5015 Edit/create <tt>debian/control</tt>:
5016 <list compact="compact">
5019 Remove the <tt>Version</tt> field. If it is
5020 generated unusually (not equal to the source
5021 version) you must use the -v option to
5022 dpkg-gencontrol (see below). <tt>Section</tt>,
5023 <tt>Priority</tt>, <tt>Maintainer</tt> go above
5024 the first blank line, most of the rest
5031 Reorder the fields and add a blank line at an
5032 appropriate point, separating the source package
5033 fields from the binary package fields.
5038 <p>Add the <tt>Source</tt> field.</p></item>
5042 Add the <tt>Standards-Version</tt> field. (Please
5043 check out the Debian Policy Manual for details
5044 about this field.)</p>
5049 Change the <tt>Architecture</tt> field for each
5050 package to <tt>any</tt>, <tt>all</tt> or whatever.
5051 If there isn't an <tt>Architecture</tt> field add
5057 If any other use of sed or things used to happen
5058 to make the binary control files use
5059 <prgn>dpkg-gencontrol</prgn>'s variable
5060 substitution features to achieve the same effect.
5061 Use <tt>debian/substvars</tt> if you need to put
5062 unusally-generated information (apart from details
5063 of <tt>.deb</tt> files) in the <tt>.changes</tt>
5071 <p>Edit the <tt>debian/rules</tt>:
5072 <list compact="compact">
5075 Remove the <prgn>source</prgn> and
5076 <prgn>diff</prgn> and any <prgn>changes</prgn> and
5077 <prgn>dist</prgn> targets. These things now
5078 happen in a package-independent way and are not
5079 done by <tt>debian/rules</tt>.</p>
5083 Split the <prgn>binary</prgn> target into
5084 <prgn>binary-arch</prgn> and
5085 <prgn>binary-indep</prgn>; in many cases all of
5086 <prgn>binary</prgn> should go into
5087 <prgn>binary-arch</prgn>. Create the
5088 <prgn>binary</prgn> target and the unused of the
5089 two other <prgn>binary-*</prgn> targets if there
5090 is one - you can copy the ones from the
5091 <prgn>hello</prgn> package.</p>
5095 Change the <prgn>binary</prgn> target to use
5096 <prgn>dpkg-gencontrol</prgn> to make the package
5097 control file(s). Move it to after all the files
5098 have been installed but just before the last
5099 <prgn>chown</prgn> and <prgn>chmod</prgn> in the
5104 Change occurrences of <tt>debian-tmp</tt> to
5105 <tt>debian/tmp</tt>.</p>
5109 Change occurrences of
5110 <tt>debian.{post,pre}{inst,rm}</tt> to
5111 <tt>debian/*</tt>.</p>
5115 Remove the version number setting at the top, if
5120 Ensure that the package's Debian-specific and
5121 upstream changelogs are installed.</p>
5129 Change the package to use <prgn>dpkg-shlibdeps</prgn> to
5130 determine its shared library dependencies and substitute
5131 them in. Shared library dependencies should no longer
5132 be hardwired in the source package.</p>
5137 Check that the <tt>debian/README</tt> is really the
5138 copyright file, and if so rename it to
5139 <tt>debian/copyright</tt> and edit <tt>debian/rules</tt>
5140 to cope with this and to change the installation of the
5142 <tt>/usr/doc/<var>package</var>/copyright</tt> to
5143 <tt>/usr/doc/copyright/<var>package</var></tt>. If it
5144 isn't then find <tt>debian/copyright</tt> and decide
5145 what to do with the <tt>README</tt>.</p>
5149 <p>Check for various other anachronisms and problems:
5150 <list compact="compact">
5153 Remove any <tt>Package_Revision</tt>,
5154 <tt>Package-Revision</tt> or <tt>Revision</tt>
5159 Rename <tt>Optional</tt> to <tt>Suggests</tt>,
5160 <tt>Recommended</tt> to
5161 <tt>Recommends</tt>.</p>
5166 <tt>/usr/doc/examples/<var>package</var></tt> to
5167 <tt>/usr/doc/<var>package</var>/examples</tt>.</p>
5171 Make sure that manpages are installed
5176 Check that the description has an extended
5177 description, is well-formatted and meaningful and
5178 helpful to people wanting to know whether to
5179 install a package.</p>
5186 <p>Look everything over.</p></item>
5190 Do a test build using <tt>dpkg-buildpackage -us -uc -sa
5191 -r<var>whatever</var></tt>. Check the permissions and
5192 locations of files in the resulting package by examining
5193 the output of <tt>dpkg-deb --contents</tt>, and check
5194 that the source build happened OK. Test install the
5195 binary package(s) and test extract the source
5201 Sign the release: either rebuild everything with
5202 <tt>dpkg-buildpackage -sa</tt>, or PGP-sign the
5203 <tt>.dsc</tt>, rebuild the <tt>.changes</tt> using
5204 <tt>dpkg-genchanges -sa</tt>, and then PGP-sign the
5205 <tt>.changes</tt>.</p>
5212 The use of <tt>-sa</tt> on <prgn>dpkg-buildpackage</prgn> and
5213 <prgn>dpkg-genchanges</prgn> is important when doing the first
5214 build/uploading of a new-format source package. Unless this
5215 happens to be Debian revision <tt>0</tt> or <tt>1</tt> by
5216 default the original source tarfile will not be included in
5217 the uploaded files listed in the <tt>.changes</tt> file, and
5218 so it won't be installed on the FTP site. <tt>-sa</tt>
5219 requests that the original source be included