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 does not deal with the Debian
44 Project policy requirements, and it assumes familiarity with
45 <prgn>dpkg</prgn>'s functions from the system administrator's
46 perspective. This package itself is maintained by a group of
47 maintainers that have no editorial powers. At the moment, the
48 list of maintainers is:
51 <p>Michael Alan Dorman <email>mdorman@debian.org</email></p>
54 <p>Richard Braakman <email>dark@xs4all.nl</email></p>
57 <p>Philip Hands <email>phil@hands.com</email></p>
60 <p>Manoj Srivastava <email>srivasta@debian.org</email></p>
67 <copyrightsummary>Copyright ©1996 Ian Jackson.</copyrightsummary>
69 This manual is free software; you may redistribute it and/or
70 modify it under the terms of the GNU General Public License
71 as published by the Free Software Foundation; either version
72 2, or (at your option) any later version.
76 This is distributed in the hope that it will be useful, but
77 <em>without any warranty</em>; without even the implied
78 warranty of merchantability or fitness for a particular
79 purpose. See the GNU General Public License for more
84 A copy of the GNU General Public License is available as
85 <tt>/usr/doc/copyright/GPL</tt> in the Debian GNU/Linux
86 distribution or on the World Wide Web at
87 <tt>http://www.gnu.org/copyleft/gpl.html</tt>. You can also
88 obtain it by writing to the Free Software Foundation, Inc.,
89 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
95 <!-- Describes the technical interface between a package and dpkg.
97 How to safely put shared libraries in a package. Details of
98 dpkg's handling of individual files. Sections on when to use
99 which feature (eg Replaces vs. Replaces/Conflicts
100 vs. update-alternatives vs. diversions) Cross-references to the
101 policy document (see below) where appropriate. Description of the
102 interface between dselect and its access methods. Hints on where
103 to start with a new package (ie, the hello package). What to do
108 Manpages are required for: update-rc.d, diversions,
109 update-alternatives, install-info in a package.
114 <heading>Introduction and scope of this manual</heading>
117 <prgn>dpkg</prgn> is a suite of programs for creating binary
118 package files and installing and removing them on Unix
121 <prgn>dpkg</prgn> is targetted primarily at Debian
122 GNU/Linux, but may work on or be ported to other
129 The binary packages are designed for the management of
130 installed executable programs (usually compiled binaries) and
131 their associated data, though source code examples and
132 documentation are provided as part of some packages.</p>
135 This manual describes the technical aspects of creating Debian
136 binary packages (<tt>.deb</tt> files). It documents the
137 behaviour of the package management programs
138 <prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and the way
139 they interact with packages.</p>
142 It also documents the interaction between
143 <prgn>dselect</prgn>'s core and the access method scripts it
144 uses to actually install the selected packages, and describes
145 how to create a new access method.</p>
148 This manual does not go into detail about the options and
149 usage of the package building and installation tools. It
150 should therefore be read in conjuction with those programs'
155 The utility programs which are provided with <prgn>dpkg</prgn>
156 for managing various system configuration and similar issues,
157 such as <prgn>update-rc.d</prgn> and
158 <prgn>install-info</prgn>, are not described in detail here -
159 please see their manpages.
163 It does <em>not</em> describe the policy requirements imposed
164 on Debian packages, such as the permissions on files and
165 directories, documentation requirements, upload procedure, and
166 so on. You should see the Debian packaging policy manual for
167 these details. (Many of them will probably turn out to be
168 helpful even if you don't plan to upload your package and make
169 it available as part of the distribution.)
173 It is assumed that the reader is reasonably familiar with the
174 <prgn>dpkg</prgn> System Administrators' manual.
175 Unfortunately this manual does not yet exist.
179 The Debian version of the FSF's GNU hello program is provided
180 as an example for people wishing to create Debian
181 packages. The Debian <prgn>debmake</prgn> package is
182 recommended as a very helpful tool in creating and maintaining
183 Debian packages. However, while the tools and examples are
184 helpful, they do not replace the need to read and follow the
185 Policy and Programmer's Manual.</p>
188 <chapt id="binarypkg"><heading>Binary packages
192 The binary package has two main sections. The first part
193 consists of various control information files and scripts used
194 by <prgn>dpkg</prgn> when installing and removing. See <ref
199 The second part is an archive containing the files and
200 directories to be installed.
204 In the future binary packages may also contain other
205 components, such as checksums and digital signatures. The
206 format for the archive is described in full in the
207 <tt>deb(5)</tt> manpage.
211 <sect id="bincreating"><heading>Creating package files -
212 <prgn>dpkg-deb</prgn>
216 All manipulation of binary package files is done by
217 <prgn>dpkg-deb</prgn>; it's the only program that has
218 knowledge of the format. (<prgn>dpkg-deb</prgn> may be
219 invoked by calling <prgn>dpkg</prgn>, as <prgn>dpkg</prgn>
220 will spot that the options requested are appropriate to
221 <prgn>dpkg-deb</prgn> and invoke that instead with the same
226 In order to create a binary package you must make a
227 directory tree which contains all the files and directories
228 you want to have in the filesystem data part of the package.
229 In Debian-format source packages this directory is usually
230 <tt>debian/tmp</tt>, relative to the top of the package's
235 They should have the locations (relative to the root of the
236 directory tree you're constructing) ownerships and
237 permissions which you want them to have on the system when
242 With current versions of <prgn>dpkg</prgn> the uid/username
243 and gid/groupname mappings for the users and groups being
244 used should be the same on the system where the package is
245 built and the one where it is installed.
249 You need to add one special directory to the root of the
250 miniature filesystem tree you're creating:
251 <prgn>DEBIAN</prgn>. It should contain the control
252 information files, notably the binary package control file
253 (see <ref id="controlfile">).
257 The <prgn>DEBIAN</prgn> directory will not appear in the
258 filesystem archive of the package, and so won't be installed
259 by <prgn>dpkg</prgn> when the package is installed.
263 When you've prepared the package, you should invoke:
265 dpkg --build <var>directory</var>
270 This will build the package in
271 <tt><var>directory</var>.deb</tt>. (<prgn>dpkg</prgn> knows
272 that <tt>--build</tt> is a <prgn>dpkg-deb</prgn> option, so
273 it invokes <prgn>dpkg-deb</prgn> with the same arguments to
278 See the manpage <manref name="dpkg-deb" section="8"> for details of how
279 to examine the contents of this newly-created file. You may find the
280 output of following commands enlightening:
282 dpkg-deb --info <var>filename</var>.deb
283 dpkg-deb --contents <var>filename</var>.deb
284 dpkg --contents <var>filename</var>.deb
286 To view the copyright file for a package you could use this command:
288 dpkg --fsys-tarfile <var>filename</var>.deb | tar xof usr/doc/<var>\*</var>copyright | less
293 <sect id="controlarea">
295 Package control information files
299 The control information portion of a binary package is a
300 collection of files with names known to <prgn>dpkg</prgn>.
301 It will treat the contents of these files specially - some
302 of them contain information used by <prgn>dpkg</prgn> when
303 installing or removing the package; others are scripts which
304 the package maintainer wants <prgn>dpkg</prgn> to run.
308 It is possible to put other files in the package control
309 area, but this is not generally a good idea (though they
310 will largely be ignored).
314 Here is a brief list of the control info files supported by
315 <prgn>dpkg</prgn> and a summary of what they're used for.
320 <tag><tt>control</tt>
324 This is the key description file used by
325 <prgn>dpkg</prgn>. It specifies the package's name
326 and version, gives its description for the user,
327 states its relationships with other packages, and so
328 forth. See <ref id="controlfile">.
332 It is usually generated automatically from information
333 in the source package by the
334 <prgn>dpkg-gencontrol</prgn> program, and with
335 assistance from <prgn>dpkg-shlibdeps</prgn>. See <ref
336 id="sourcetools">.</p>
339 <tag><tt>postinst</tt>, <tt>preinst</tt>, <tt>postrm</tt>,
345 These are exectuable files (usually scripts) which
346 <prgn>dpkg</prgn> runs during installation, upgrade
347 and removal of packages. They allow the package to
348 deal with matters which are particular to that package
349 or require more complicated processing than that
350 provided by <prgn>dpkg</prgn>. Details of when and
351 how they are called are in <ref
352 id="maintainerscripts">.
356 It is very important to make these scripts
360 That means that if it runs successfully or fails
361 and then you call it again it doesn't bomb out,
362 but just ensures that everything is the way it
365 </footnote> This is so that if an error occurs, the
366 user interrupts <prgn>dpkg</prgn> or some other
367 unforeseen circumstance happens you don't leave the
368 user with a badly-broken package.
372 The maintainer scripts are guaranteed to run with a
373 controlling terminal and can interact with the user.
374 If they need to prompt for passwords, do full-screen
375 interaction or something similar you should do these
376 things to and from <tt>/dev/tty</tt>, since
377 <prgn>dpkg</prgn> will at some point redirect scripts'
378 standard input and output so that it can log the
379 installation process. Likewise, because these scripts
380 may be executed with standard output redirected into a
381 pipe for logging purposes, Perl scripts should set
382 unbuffered output by setting <tt>$|=1</tt> so that the
383 output is printed immediately rather than being
388 Each script should return a zero exit status for
389 success, or a nonzero one for failure.</p>
392 <tag><tt>conffiles</tt>
397 This file contains a list of configuration files which
398 are to be handled automatically by <prgn>dpkg</prgn>
399 (see <ref id="conffiles">). Note that not necessarily
400 every configuration file should be listed here.</p>
408 This file contains a list of the shared libraries
409 supplied by the package, with dependency details for
410 each. This is used by <prgn>dpkg-shlibdeps</prgn>
411 when it determines what dependencies are required in a
412 package control file. The <tt>shlibs</tt> file format
413 is described on <ref id="shlibs">.
419 <sect id="controlfile">
421 The main control information file: <tt>control</tt>
424 The most important control information file used by
425 <prgn>dpkg</prgn> when it installs a package is
426 <tt>control</tt>. It contains all the package's `vital
431 The binary package control files of packages built from
432 Debian sources are made by a special tool,
433 <prgn>dpkg-gencontrol</prgn>, which reads
434 <tt>debian/control</tt> and <tt>debian/changelog</tt> to
435 find the information it needs. See <ref id="sourcepkg"> for
440 The fields in binary package control files are:
441 <list compact="compact">
443 <p><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</p>
446 <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
448 <item><p><qref id="f-Architecture"><tt>Architecture</tt></qref>
452 This field should appear in all packages, though
453 <prgn>dpkg</prgn> doesn't require it yet so that
454 old packages can still be installed.
460 <p><qref id="relationships"><tt>Depends</tt>,
461 <tt>Provides</tt> et al.</qref></p>
464 <p><qref id="f-Essential"><tt>Essential</tt></qref></p>
467 <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
470 <p><qref id="f-classification"><tt>Section</tt>,
471 <tt>Priority</tt></qref></p>
474 <p><qref id="f-Source"><tt>Source</tt></qref></p>
477 <p><qref id="descriptions"><tt>Description</tt></qref></p>
481 <qref id="f-Installed-Size"><tt>Installed-Size</tt></qref>
487 A description of the syntax of control files and the purpose
488 of these fields is available in <ref id="controlfields">.
492 <heading>Time Stamps</heading>
494 Maintainers are encouraged to preserve the modification
495 times of the upstream source files in a package, as far as
496 is reasonably possible.
499 The rationale is that there is some information conveyed
500 by knowing the age of the file, for example, you could
501 recognize that some documentation is very old by looking
502 at the modification time, so it would be nice if the
503 modification time of the upstream source would be
511 <chapt id="sourcepkg">
512 <heading>Source packages</heading>
515 The Debian binary packages in the distribution are generated
516 from Debian sources, which are in a special format to assist
517 the easy and automatic building of binaries.
521 There was a previous version of the Debian source format,
522 which is now being phased out. Instructions for converting an
523 old-style package are given in the Debian policy manual.
526 <sect id="sourcetools">
527 <heading>Tools for processing source packages</heading>
530 Various tools are provided for manipulating source packages;
531 they pack and unpack sources and help build of binary
532 packages and help manage the distribution of new versions.
536 They are introduced and typical uses described here; see
537 <manref name="dpkg-source" section="1"> for full
538 documentation about their arguments and operation.
542 For examples of how to construct a Debian source package,
543 and how to use those utilities that are used by Debian
544 source packages, please see the <prgn>hello</prgn> example
550 <prgn>dpkg-source</prgn> - packs and unpacks Debian source
555 This program is frequently used by hand, and is also
556 called from package-independent automated building scripts
557 such as <prgn>dpkg-buildpackage</prgn>.
561 To unpack a package it is typically invoked with
563 dpkg-source -x <var>.../path/to/filename</var>.dsc
568 with the <tt><var>filename</var>.tar.gz</tt> and
569 <tt><var>filename</var>.diff.gz</tt> (if applicable) in
570 the same directory. It unpacks into
571 <tt><var>package</var>-<var>version</var></tt>, and if
573 <tt><var>package</var>-<var>version</var>.orig</tt>, in
574 the current directory.
578 To create a packed source archive it is typically invoked:
580 dpkg-source -b <var>package</var>-<var>version</var>
585 This will create the <tt>.dsc</tt>, <tt>.tar.gz</tt> and
586 <tt>.diff.gz</tt> (if appropriate) in the current
587 directory. <prgn>dpkg-source</prgn> does not clean the
588 source tree first - this must be done separately if it is
593 See also <ref id="sourcearchives">.</p>
599 <prgn>dpkg-buildpackage</prgn> - overall package-building
604 <prgn>dpkg-buildpackage</prgn> is a script which invokes
605 <prgn>dpkg-source</prgn>, the <tt>debian/rules</tt>
606 targets <prgn>clean</prgn>, <prgn>build</prgn> and
607 <prgn>binary</prgn>, <prgn>dpkg-genchanges</prgn> and
608 <prgn>pgp</prgn> to build a signed source and binary
613 It is usually invoked by hand from the top level of the
614 built or unbuilt source directory. It may be invoked with
615 no arguments; useful arguments include:
616 <taglist compact="compact">
617 <tag><tt>-uc</tt>, <tt>-us</tt></tag>
620 Do not PGP-sign the <tt>.changes</tt> file or the
621 source package <tt>.dsc</tt> file, respectively.</p>
623 <tag><tt>-p<var>pgp-command</var></tt></tag>
626 Invoke <var>pgp-command</var> instead of finding
627 <tt>pgp</tt> on the <prgn>PATH</prgn>.
628 <var>pgp-command</var> must behave just like
629 <prgn>pgp</prgn>.</p>
631 <tag><tt>-r<var>root-command</var></tt></tag>
634 When root privilege is required, invoke the command
635 <var>root-command</var>. <var>root-command</var>
636 should invoke its first argument as a command, from
637 the <prgn>PATH</prgn> if necessary, and pass its
638 second and subsequent arguments to the command it
639 calls. If no <var>root-command</var> is supplied
640 then <var>dpkg-buildpackage</var> will take no
641 special action to gain root privilege, so that for
642 most packages it will have to be invoked as root to
645 <tag><tt>-b</tt>, <tt>-B</tt></tag>
648 Two types of binary-only build and upload - see
649 <manref name="dpkg-source" section="1">.
658 <prgn>dpkg-gencontrol</prgn> - generates binary package
663 This program is usually called from <tt>debian/rules</tt>
664 (see <ref id="sourcetree">) in the top level of the source
669 This is usually done just before the files and directories in the
670 temporary directory tree where the package is being built have their
671 permissions and ownerships set and the package is constructed using
672 <prgn>dpkg-deb/</prgn>
675 This is so that the control file which is produced has
676 the right permissions
682 <prgn>dpkg-gencontrol</prgn> must be called after all the
683 files which are to go into the package have been placed in
684 the temporary build directory, so that its calculation of
685 the installed size of a package is correct.
689 It is also necessary for <prgn>dpkg-gencontrol</prgn> to
690 be run after <prgn>dpkg-shlibdeps</prgn> so that the
691 variable substitutions created by
692 <prgn>dpkg-shlibdeps</prgn> in <tt>debian/substvars</tt>
697 For a package which generates only one binary package, and
698 which builds it in <tt>debian/tmp</tt> relative to the top
699 of the source package, it is usually sufficient to call
700 <prgn>dpkg-gencontrol</prgn>.
704 Sources which build several binaries will typically need
707 dpkg-gencontrol -Pdebian/tmp-<var>pkg</var> -p<var>package</var>
708 </example> The <tt>-P</tt> tells
709 <prgn>dpkg-gencontrol</prgn> that the package is being
710 built in a non-default directory, and the <tt>-p</tt>
711 tells it which package's control file should be generated.
715 <prgn>dpkg-gencontrol</prgn> also adds information to the
716 list of files in <tt>debian/files</tt>, for the benefit of
717 (for example) a future invocation of
718 <prgn>dpkg-genchanges</prgn>.</p>
723 <prgn>dpkg-shlibdeps</prgn> - calculates shared library
728 This program is usually called from <tt>debian/rules</tt>
729 just before <prgn>dpkg-gencontrol</prgn> (see <ref
730 id="sourcetree">), in the top level of the source tree.
734 Its arguments are executables
737 They may be specified either in the locations in the
738 source tree where they are created or in the locations
739 in the temporary build tree where they are installed
740 prior to binary package creation.
742 </footnote> for which shared library dependencies should
743 be included in the binary package's control file.
747 If some of the executable(s) shared libraries should only
748 warrant a <tt>Recommends</tt> or <tt>Suggests</tt>, or if
749 some warrant a <tt>Pre-Depends</tt>, this can be achieved
750 by using the <tt>-d<var>dependency-field</var></tt> option
751 before those executable(s). (Each <tt>-d</tt> option
752 takes effect until the next <tt>-d</tt>.)
756 <prgn>dpkg-shlibdeps</prgn> does not directly cause the
757 output control file to be modified. Instead by default it
758 adds to the <tt>debian/substvars</tt> file variable
759 settings like <tt>shlibs:Depends</tt>. These variable
760 settings must be referenced in dependency fields in the
761 appropriate per-binary-package sections of the source
766 For example, the <prgn>procps</prgn> package generates two
767 kinds of binaries, simple C binaries like <prgn>ps</prgn>
768 which require a predependency and full-screen ncurses
769 binaries like <prgn>top</prgn> which require only a
770 recommendation. It can say in its <tt>debian/rules</tt>:
772 dpkg-shlibdeps -dPre-Depends ps -dRecommends top
774 and then in its main control file <tt>debian/control</tt>:
778 Pre-Depends: ${shlibs:Pre-Depends}
779 Recommends: ${shlibs:Recommends}
785 Sources which produce several binary packages with
786 different shared library dependency requirements can use
787 the <tt>-p<var>varnameprefix</var></tt> option to override
788 the default <tt>shlib:</tt> prefix (one invocation of
789 <prgn>dpkg-shlibdeps</prgn> per setting of this option).
790 They can thus produce several sets of dependency
791 variables, each of the form
792 <tt><var>varnameprefix</var>:<var>dependencyfield</var></tt>,
793 which can be referred to in the appropriate parts of the
794 binary package control files.
801 <prgn>dpkg-distaddfile</prgn> - adds a file to
802 <tt>debian/files</tt>
806 Some packages' uploads need to include files other than
807 the source and binary package files.
811 <prgn>dpkg-distaddfile</prgn> adds a file to the
812 <tt>debian/files</tt> file so that it will be included in
813 the <tt>.changes</tt> file when
814 <prgn>dpkg-genchanges</prgn> is run.
818 It is usually invoked from the <prgn>binary</prgn> target of
819 <tt>debian/rules</tt>:
821 dpkg-distaddfile <var>filename</var> <var>section</var> <var>priority</var>
823 The <var>filename</var> is relative to the directory where
824 <prgn>dpkg-genchanges</prgn> will expect to find it - this
825 is usually the directory above the top level of the source
826 tree. The <tt>debian/rules</tt> target should put the
827 file there just before or just after calling
828 <prgn>dpkg-distaddfile</prgn>.
832 The <var>section</var> and <var>priority</var> are passed
833 unchanged into the resulting <tt>.changes</tt> file. See
834 <ref id="f-classification">.
839 <sect1><heading><prgn>dpkg-genchanges</prgn> - generates a <tt>.changes</tt> upload
844 This program is usually called by package-independent
845 automatic building scripts such as
846 <prgn>dpkg-buildpackage</prgn>, but it may also be called
851 It is usually called in the top level of a built source
852 tree, and when invoked with no arguments will print out a
853 straightforward <tt>.changes</tt> file based on the
854 information in the source package's changelog and control
855 file and the binary and source packages which should have
861 <sect1><heading><prgn>dpkg-parsechangelog</prgn> - produces parsed representation of
866 This program is used internally by
867 <prgn>dpkg-source</prgn> et al. It may also occasionally
868 be useful in <tt>debian/rules</tt> and elsewhere. It
869 parses a changelog, <tt>debian/changelog</tt> by default,
870 and prints a control-file format representation of the
871 information in it to standard output.
875 <sect1 id="dpkgarch"><heading><prgn>dpkg-architecture</prgn> -
876 information about the build and host system
880 This program can be used manually, but is also invoked by
881 <tt>dpkg-buildpackage</tt> or <tt>debian/rules</tt> to set
882 to set environment or make variables which specify the build and
883 host architecture for the package building process.
888 <sect id="sourcetree"><heading>The Debianised source tree
892 The source archive scheme described later is intended to
893 allow a Debianised source tree with some associated control
894 information to be reproduced and transported easily. The
895 Debianised source tree is a version of the original program
896 with certain files added for the benefit of the
897 Debianisation process, and with any other changes required
898 made to the rest of the source code and installation
903 The extra files created for Debian are in the subdirectory
904 <tt>debian</tt> of the top level of the Debianised source
905 tree. They are described below.
908 <sect1 id="debianrules"><heading><tt>debian/rules</tt> - the main building
913 This file is an executable makefile, and contains the
914 package-specific recipies for compiling the package and
915 building binary package(s) out of the source.
919 It must start with the line <tt>#!/usr/bin/make -f</tt>,
920 so that it can be invoked by saying its name rather than
921 invoking <prgn>make</prgn> explicitly.
925 Since an interactive <tt>debian/rules</tt> script makes it
926 impossible to autocompile that package and also makes it
927 hard for other people to reproduce the same binary
928 package, all <strong>required targets</strong> have to be
929 non-interactive. At a minimul, required targets are the
930 ones called by <prgn>dpkg-buildpackage</prgn>, namely,
931 <em>clean</em>, <em>binary</em>, <em>binary-arch</em>, and
932 <em>build</em>. It also follows that any target that these
933 targets depend on must also be non-interactive.
937 The targets which are required to be present are:
939 <tag><tt>build</tt></tag>
942 This should perform all non-interactive
943 configuration and compilation of the package. If a
944 package has an interactive pre-build configuration
945 routine, the Debianised source package should be
946 built after this has taken place, so that it can be
947 built without rerunning the configuration.
951 For some packages, notably ones where the same
952 source tree is compiled in different ways to produce
953 two binary packages, the <prgn>build</prgn> target
954 does not make much sense. For these packages it is
955 good enough to provide two (or more) targets
956 (<tt>build-a</tt> and <tt>build-b</tt> or whatever)
957 for each of the ways of building the package, and a
958 <prgn>build</prgn> target that does nothing. The
959 <prgn>binary</prgn> target will have to build the
960 package in each of the possible ways and make the
961 binary package out of each.
965 The <prgn>build</prgn> target must not do anything
966 that might require root privilege.
970 The <prgn>build</prgn> target may need to run
971 <prgn>clean</prgn> first - see below.
975 When a package has a configuration routine that
976 takes a long time, or when the makefiles are poorly
977 designed, or when <prgn>build</prgn> needs to run
978 <prgn>clean</prgn> first, it is a good idea to
979 <tt>touch build</tt> when the build process is
980 complete. This will ensure that if <tt>debian/rules
981 build</tt> is run again it will not rebuild the
986 <tag><tt>binary</tt>, <tt>binary-arch</tt>,
987 <tt>binary-indep</tt>
991 The <prgn>binary</prgn> target should be all that is
992 necessary for the user to build the binary
993 package. All these targets are required to be
994 non-interactive. It is split into two parts:
995 <prgn>binary-arch</prgn> builds the packages' output
996 files which are specific to a particular
997 architecture, and <prgn>binary-indep</prgn> builds
1002 <prgn>binary</prgn> should usually be a target with
1003 no commands which simply depends on
1004 <prgn>binary-arch</prgn> and
1005 <prgn>binary-indep</prgn>.
1009 Both <prgn>binary-*</prgn> targets should depend on
1010 the <prgn>build</prgn> target, above, so that the
1011 package is built if it has not been already. It
1012 should then create the relevant binary package(s),
1013 using <prgn>dpkg-gencontrol</prgn> to make their
1014 control files and <prgn>dpkg-deb</prgn> to build
1015 them and place them in the parent of the top level
1020 If one of the <prgn>binary-*</prgn> targets has
1021 nothing to do (this will be always be the case if
1022 the source generates only a single binary package,
1023 whether architecture-dependent or not) it
1024 <em>must</em> still exist, but should always
1029 <ref id="binarypkg"> describes how to construct
1034 The <prgn>binary</prgn> targets must be invoked as
1039 <tag><tt>clean</tt></tag>
1043 This should undo any effects that the
1044 <prgn>build</prgn> and <prgn>binary</prgn> targets
1045 may have had, except that it should leave alone any
1046 output files created in the parent directory by a
1047 run of <prgn>binary</prgn>. This target is required
1048 to be non-interactive.
1052 If a <prgn>build</prgn> file is touched at the end
1053 of the <prgn>build</prgn> target, as suggested
1054 above, it must be removed as the first thing that
1055 <prgn>clean</prgn> does, so that running
1056 <prgn>build</prgn> again after an interrupted
1057 <prgn>clean</prgn> doesn't think that everything is
1062 The <prgn>clean</prgn> target must be invoked as
1063 root if <prgn>binary</prgn> has been invoked since
1064 the last <prgn>clean</prgn>, or if
1065 <prgn>build</prgn> has been invoked as root (since
1066 <prgn>build</prgn> may create directories, for
1071 <tag><tt>get-orig-source</tt> (optional)</tag>
1075 This target fetches the most recent version of the
1076 original source package from a canonical archive
1077 site (via FTP or WWW, for example), does any
1078 necessary rearrangement to turn it into the original
1079 source tarfile format described below, and leaves it
1080 in the current directory.
1084 This target may be invoked in any directory, and
1085 should take care to clean up any temporary files it
1090 This target is optional, but providing it if
1091 possible is a good idea.
1097 The <prgn>build</prgn>, <prgn>binary</prgn> and
1098 <prgn>clean</prgn> targets must be invoked with a current
1099 directory of the package's top-level directory.
1104 Additional targets may exist in <tt>debian/rules</tt>,
1105 either as published or undocumented interfaces or for the
1106 package's internal use.
1110 The architecture we build on and build for is determined by make
1111 variables via dpkg-architecture (see <ref id="dpkgarch">). You can
1112 get the Debian architecture and the GNU style architecture
1113 specification string for the build machine as well as the host
1114 machine. Here is a list of supported make variables:
1115 <list compact="compact">
1117 <p><tt>DEB_*_ARCH</tt> (the Debian architecture)</p>
1120 <p><tt>DEB_*_GNU_TYPE</tt> (the GNU style architecture
1121 specification string)</p>
1124 <p><tt>DEB_*_GNU_CPU</tt> (the CPU part of DEB_*_GNU_TYPE)</p>
1127 <p><tt>DEB_*_GNU_SYSTEM</tt> (the System part of
1133 where <tt>*</tt> is either <tt>BUILD</tt> for specification of
1134 the build machine or <tt>HOST</tt> for specification of the machine
1139 Backward compatibility can be provided in the rules file
1140 by setting the needed variables to suitable default
1141 values, please refer to the documentation of
1142 dpkg-architecture for details.
1146 It is important to understand that the <tt>DEB_*_ARCH</tt>
1147 string does only determine which Debian architecture we
1148 build on resp. for. It should not be used to get the CPU
1149 or System information, the GNU style variables should be
1155 <sect1><heading><tt>debian/control</tt>
1159 This file contains version-independent details about the
1160 source package and about the binary packages it creates.
1164 It is a series of sets of control fields, each
1165 syntactically similar to a binary package control file.
1166 The sets are separated by one or more blank lines. The
1167 first set is information about the source package in
1168 general; each subsequent set describes one binary package
1169 that the source tree builds.
1173 The syntax and semantics of the fields are described below
1174 in <ref id="controlfields">.
1178 The general (binary-package-independent) fields are:
1179 <list compact="compact">
1181 <p><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</p>
1184 <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
1188 <qref id="f-classification"><tt>Section</tt> and
1189 <tt>Priority</tt></qref>
1190 (classification, mandatory)
1195 <qref id="relationships"><tt>Build-Depends</tt> et
1196 al.</qref> (source package interrelationships)
1201 <qref id="f-Standards-Version"><tt>Standards-Version</tt></qref>
1207 The per-binary-package fields are:
1208 <list compact="compact">
1210 <p><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</p>
1214 <qref id="f-Architecture"><tt>Architecture</tt></qref>
1218 <p><qref id="descriptions"><tt>Description</tt></qref></p>
1222 <qref id="f-classification"><tt>Section</tt> and
1223 <tt>Priority</tt></qref> (classification)</p>
1226 <p><qref id="f-Essential"><tt>Essential</tt></qref></p>
1230 <qref id="relationships"><tt>Depends</tt> et
1231 al.</qref> (binary package interrelationships)
1237 These fields are used by <prgn>dpkg-gencontrol</prgn> to
1238 generate control files for binary packages (see below), by
1239 <prgn>dpkg-genchanges</prgn> to generate the
1240 <tt>.changes</tt> file to accompany the upload, and by
1241 <prgn>dpkg-source</prgn> when it creates the <tt>.dsc</tt>
1242 source control file as part of a source archive.
1246 The fields here may contain variable references - their
1247 values will be substituted by
1248 <prgn>dpkg-gencontrol</prgn>, <prgn>dpkg-genchanges</prgn>
1249 or <prgn>dpkg-source</prgn> when they generate output
1250 control files. See <ref id="srcsubstvars"> for details.
1253 <p> <sect2><heading>User-defined fields
1257 Additional user-defined fields may be added to the
1258 source package control file. Such fields will be
1259 ignored, and not copied to (for example) binary or
1260 source package control files or upload control files.
1264 If you wish to add additional unsupported fields to
1265 these output files you should use the mechanism
1270 Fields in the main source control information file with
1271 names starting <tt>X</tt>, followed by one or more of
1272 the letters <tt>BCS</tt> and a hyphen <tt>-</tt>, will
1273 be copied to the output files. Only the part of the
1274 field name after the hyphen will be used in the output
1275 file. Where the letter <tt>B</tt> is used the field
1276 will appear in binary package control files, where the
1277 letter <tt>S</tt> is used in source package control
1278 files and where <tt>C</tt> is used in upload control
1279 (<tt>.changes</tt>) files.
1283 For example, if the main source information control file
1286 XBS-Comment: I stand between the candle and the star.
1288 then the binary and source package control files will contain the
1291 Comment: I stand between the candle and the star.
1298 <sect1 id="dpkgchangelog"><heading><tt>debian/changelog</tt>
1302 This file records the changes to the Debian-specific parts of the
1306 Though there is nothing stopping an author who is also
1307 the Debian maintainer from using it for all their
1308 changes, it will have to be renamed if the Debian and
1309 upstream maintainers become different
1316 It has a special format which allows the package building
1317 tools to discover which version of the package is being
1318 built and find out other release-specific information.
1322 That format is a series of entries like this:
1324 <var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
1326 * <var>change details</var>
1327 <var>more change details</var>
1328 * <var>even more change details</var>
1330 -- <var>maintainer name and email address</var> <var>date</var>
1335 <var>package</var> and <var>version</var> are the source
1336 package name and version number.
1340 <var>distribution(s)</var> lists the distributions where
1341 this version should be installed when it is uploaded - it
1342 is copied to the <tt>Distribution</tt> field in the
1343 <tt>.changes</tt> file. See <ref id="f-Distribution">.
1347 <var>urgency</var> is the value for the <tt>Urgency</tt>
1348 field in the <tt>.changes</tt> file for the upload. See
1349 <ref id="f-Urgency">. It is not possible to specify an
1350 urgency containing commas; commas are used to separate
1351 <tt><var>keyword</var>=<var>value</var></tt> settings in
1352 the <prgn>dpkg</prgn> changelog format (though there is
1353 currently only one useful <var>keyword</var>,
1358 The change details may in fact be any series of lines
1359 starting with at least two spaces, but conventionally each
1360 change starts with an asterisk and a separating space and
1361 continuation lines are indented so as to bring them in
1362 line with the start of the text above. Blank lines may be
1363 used here to separate groups of changes, if desired.
1367 The maintainer name and email address should <em>not</em>
1368 necessarily be those of the usual package maintainer.
1369 They should be the details of the person doing
1370 <em>this</em> version. The information here will be
1371 copied to the <tt>.changes</tt> file, and then later used
1372 to send an acknowledgement when the upload has been
1377 The <var>date</var> should be in RFC822 format
1380 This is generated by the <prgn>822-date</prgn>
1383 </footnote>; it should include the timezone specified
1384 numerically, with the timezone name or abbreviation
1385 optionally present as a comment.
1389 The first `title' line with the package name should start
1390 at the left hand margin; the `trailer' line with the
1391 maintainer and date details should be preceded by exactly
1392 one space. The maintainer details and the date must be
1393 separated by exactly two spaces.
1397 An Emacs mode for editing this format is available: it is
1398 called <tt>debian-changelog-mode</tt>. You can have this
1399 mode selected automatically when you edit a Debian
1400 changelog by adding a local variables clause to the end of
1404 <sect2><heading>Defining alternative changelog formats
1408 It is possible to use a different format to the standard
1409 one, by providing a parser for the format you wish to
1414 In order to have <tt>dpkg-parsechangelog</tt> run your
1415 parser, you must include a line within the last 40 lines
1416 of your file matching the Perl regular expression:
1417 <tt>\schangelog-format:\s+([0-9a-z]+)\W</tt> The part in
1418 parentheses should be the name of the format. For
1419 example, you might say:
1421 @@@ changelog-format: joebloggs @@@
1423 Changelog format names are non-empty strings of alphanumerics.
1427 If such a line exists then <tt>dpkg-parsechangelog</tt>
1428 will look for the parser as
1429 <tt>/usr/lib/dpkg/parsechangelog/<var>format-name</var></tt>
1431 <tt>/usr/local/lib/dpkg/parsechangelog/<var>format-name</var></tt>;
1432 it is an error for it not to find it, or for it not to
1433 be an executable program. The default changelog format
1434 is <tt>dpkg</tt>, and a parser for it is provided with
1435 the <tt>dpkg</tt> package.
1439 The parser will be invoked with the changelog open on
1440 standard input at the start of the file. It should read
1441 the file (it may seek if it wishes) to determine the
1442 information required and return the parsed information
1443 to standard output in the form of a series of control
1444 fields in the standard format. By default it should
1445 return information about only the most recent version in
1446 the changelog; it should accept a
1447 <tt>-v<var>version</var></tt> option to return changes
1448 information from all versions present <em>strictly
1449 after</em> <var>version</var>, and it should then be an
1450 error for <var>version</var> not to be present in the
1456 <list compact="compact">
1458 <p><qref id="f-Source"><tt>Source</tt></qref></p>
1461 <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
1465 <qref id="f-Distribution"><tt>Distribution</tt></qref>
1470 <p><qref id="f-Urgency"><tt>Urgency</tt></qref> (mandatory)</p>
1474 <qref id="f-Maintainer"><tt>Maintainer</tt></qref>
1479 <p><qref id="f-Date"><tt>Date</tt></qref></p>
1483 <qref id="f-Changes"><tt>Changes</tt></qref>
1490 If several versions are being returned (due to the use
1491 of <tt>-v</tt>), the urgency value should be of the
1492 highest urgency code listed at the start of any of the
1493 versions requested followed by the concatenated
1494 (space-separated) comments from all the versions
1495 requested; the maintainer, version, distribution and
1496 date should always be from the most recent version.
1500 For the format of the <tt>Changes</tt> field see <ref
1505 If the changelog format which is being parsed always or
1506 almost always leaves a blank line between individual
1507 change notes these blank lines should be stripped out,
1508 so as to make the resulting output compact.
1512 If the changelog format does not contain date or package
1513 name information this information should be omitted from
1514 the output. The parser should not attempt to synthesise
1515 it or find it from other sources.
1519 If the changelog does not have the expected format the
1520 parser should exit with a nonzero exit status, rather
1521 than trying to muddle through and possibly generating
1526 A changelog parser may not interact with the user at
1530 <sect1 id="srcsubstvars"><heading><tt>debian/substvars</tt>
1531 and variable substitutions
1535 When <prgn>dpkg-gencontrol</prgn>,
1536 <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
1537 generate control files they do variable substitutions on
1538 their output just before writing it. Variable
1539 substitutions have the form
1540 <tt>${<var>variable-name</var>}</tt>. The optional file
1541 <tt>debian/substvars</tt> contains variable substitutions
1542 to be used; variables can also be set directly from
1543 <tt>debian/rules</tt> using the <tt>-V</tt> option to the
1544 source packaging commands, and certain predefined
1545 variables are available.
1549 The is usually generated and modified dynamically by
1550 <tt>debian/rules</tt> targets; in this case it must be
1551 removed by the <prgn>clean</prgn> target.
1555 See <manref name="dpkg-source" section="1"> for full
1556 details about source variable substitutions, including the
1557 format of <tt>debian/substvars</tt>.</p>
1560 <sect1><heading><tt>debian/files</tt>
1564 This file is not a permanent part of the source tree; it
1565 is used while building packages to record which files are
1566 being generated. <prgn>dpkg-genchanges</prgn> uses it
1567 when it generates a <tt>.changes</tt> file.
1571 It should not exist in a shipped source package, and so it
1572 (and any backup files or temporary files such as
1576 <tt>files.new</tt> is used as a temporary file by
1577 <prgn>dpkg-gencontrol</prgn> and
1578 <prgn>dpkg-distaddfile</prgn> - they write a new
1579 version of <tt>files</tt> here before renaming it,
1580 to avoid leaving a corrupted copy if an error
1583 </footnote>) should be removed by the
1584 <prgn>clean</prgn> target. It may also be wise to
1585 ensure a fresh start by emptying or removing it at the
1586 start of the <prgn>binary</prgn> target.
1590 <prgn>dpkg-gencontrol</prgn> adds an entry to this file
1591 for the <tt>.deb</tt> file that will be created by
1592 <prgn>dpkg-deb</prgn> from the control file that it
1593 generates, so for most packages all that needs to be done
1594 with this file is to delete it in <prgn>clean</prgn>.
1598 If a package upload includes files besides the source
1599 package and any binary packages whose control files were
1600 made with <prgn>dpkg-gencontrol</prgn> then they should be
1601 placed in the parent of the package's top-level directory
1602 and <prgn>dpkg-distaddfile</prgn> should be called to add
1603 the file to the list in <tt>debian/files</tt>.</p>
1606 <sect1><heading><tt>debian/tmp</tt>
1610 This is the canonical temporary location for the
1611 construction of binary packages by the <prgn>binary</prgn>
1612 target. The directory <tt>tmp</tt> serves as the root of
1613 the filesystem tree as it is being constructed (for
1614 example, by using the package's upstream makefiles install
1615 targets and redirecting the output there), and it also
1616 contains the <tt>DEBIAN</tt> subdirectory. See <ref
1621 If several binary packages are generated from the same
1622 source tree it is usual to use several
1623 <tt>debian/tmp<var>something</var></tt> directories, for
1624 example <tt>tmp-a</tt> or <tt>tmp-doc</tt>.
1628 Whatever <tt>tmp</tt> directories are created and used by
1629 <prgn>binary</prgn> must of course be removed by the
1630 <prgn>clean</prgn> target.</p></sect1>
1634 <sect id="sourcearchives"><heading>Source packages as archives
1638 As it exists on the FTP site, a Debian source package
1639 consists of three related files. You must have the right
1640 versions of all three to be able to use them.
1645 <tag>Debian source control file - <tt>.dsc</tt></tag>
1649 This file contains a series of fields, identified and
1650 separated just like the fields in the control file of
1651 a binary package. The fields are listed below; their
1652 syntax is described above, in <ref id="controlfields">.
1653 <list compact="compact">
1655 <p><qref id="f-Source"><tt>Source</tt></qref></p>
1658 <p><qref id="versions"><tt>Version</tt></qref></p>
1661 <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
1664 <p><qref id="f-Binary"><tt>Binary</tt></qref></p>
1667 <p><qref id="f-Architecture"><tt>Architecture</tt></qref></p>
1671 <qref id="relationships"><tt>Build-Depends</tt> et
1672 al.</qref> (source package interrelationships)
1677 <qref id="f-Standards-Version"><tt>Standards-Version</tt></qref></p>
1680 <p><qref id="f-Files"><tt>Files</tt></qref></p>
1685 The source package control file is generated by
1686 <prgn>dpkg-source</prgn> when it builds the source
1687 archive, from other files in the source package,
1688 described above. When unpacking it is checked against
1689 the files and directories in the other parts of the
1690 source package, as described below.</p>
1694 Original source archive -
1696 <var>package</var>_<var>upstream-version</var>.orig.tar.gz
1703 This is a compressed (with <tt>gzip -9</tt>)
1704 <prgn>tar</prgn> file containing the source code from
1705 the upstream authors of the program. The tarfile
1706 unpacks into a directory
1707 <tt><var>package</var>-<var>upstream-version</var>.orig</tt>,
1708 and does not contain files anywhere other than in
1709 there or in its subdirectories.</p>
1713 Debianisation diff -
1715 <var>package</var>_<var>upstream_version-revision</var>.diff.gz
1721 This is a unified context diff (<tt>diff -u</tt>)
1722 giving the changes which are required to turn the
1723 original source into the Debian source. These changes
1724 may only include editing and creating plain files.
1725 The permissions of files, the targets of symbolic
1726 links and the characteristics of special files or
1727 pipes may not be changed and no files may be removed
1732 All the directories in the diff must exist, except the
1733 <tt>debian</tt> subdirectory of the top of the source
1734 tree, which will be created by
1735 <prgn>dpkg-source</prgn> if necessary when unpacking.
1739 The <prgn>dpkg-source</prgn> program will
1740 automatically make the <tt>debian/rules</tt> file
1741 executable (see below).</p></item>
1746 If there is no original source code - for example, if the
1747 package is specially prepared for Debian or the Debian
1748 maintainer is the same as the upstream maintainer - the
1749 format is slightly different: then there is no diff, and the
1751 <tt><var>package</var>_<var>version</var>.tar.gz</tt> and
1752 contains a directory
1753 <tt><var>package</var>-<var>version</var></tt>.
1757 <sect><heading>Unpacking a Debian source package without
1758 <prgn>dpkg-source</prgn>
1762 <tt>dpkg-source -x</tt> is the recommended way to unpack a
1763 Debian source package. However, if it is not available it
1764 is possible to unpack a Debian source archive as follows:
1765 <enumlist compact="compact">
1768 Untar the tarfile, which will create a <tt>.orig</tt>
1772 <p>Rename the <tt>.orig</tt> directory to
1773 <tt><var>package</var>-<var>version</var></tt>.</p>
1777 Create the subdirectory <tt>debian</tt> at the top of
1778 the source tree.</p>
1780 <item><p>Apply the diff using <tt>patch -p0</tt>.</p>
1782 <item><p>Untar the tarfile again if you want a copy of the original
1783 source code alongside the Debianised version.</p>
1788 It is not possible to generate a valid Debian source archive
1789 without using <prgn>dpkg-source</prgn>. In particular,
1790 attempting to use <prgn>diff</prgn> directly to generate the
1791 <tt>.diff.gz</tt> file will not work.
1794 <sect1><heading>Restrictions on objects in source packages
1798 The source package may not contain any hard links
1801 This is not currently detected when building source
1802 packages, but only when extracting
1808 Hard links may be permitted at some point in the
1809 future, but would require a fair amount of
1812 </footnote>, device special files, sockets or setuid or
1816 Setgid directories are allowed.
1822 The source packaging tools manage the changes between the
1823 original and Debianised source using <prgn>diff</prgn> and
1824 <prgn>patch</prgn>. Turning the original source tree as
1825 included in the <tt>.orig.tar.gz</tt> into the debianised
1826 source must not involve any changes which cannot be
1827 handled by these tools. Problematic changes which cause
1828 <prgn>dpkg-source</prgn> to halt with an error when
1829 building the source package are:
1830 <list compact="compact">
1831 <item><p>Adding or removing symbolic links, sockets or pipes.</p>
1833 <item><p>Changing the targets of symbolic links.</p>
1835 <item><p>Creating directories, other than <tt>debian</tt>.</p>
1837 <item><p>Changes to the contents of binary files.</p></item>
1838 </list> Changes which cause <prgn>dpkg-source</prgn> to
1839 print a warning but continue anyway are:
1840 <list compact="compact">
1843 Removing files, directories or symlinks.
1846 Renaming a file is not treated specially - it is
1847 seen as the removal of the old file (which
1848 generates a warning, but is otherwise ignored),
1849 and the creation of the new
1856 Changed text files which are missing the usual final
1857 newline (either in the original or the modified
1862 Changes which are not represented, but which are not detected by
1863 <prgn>dpkg-source</prgn>, are:
1864 <list compact="compact">
1865 <item><p>Changing the permissions of files (other than
1866 <tt>debian/rules</tt>) and directories.</p></item>
1871 The <tt>debian</tt> directory and <tt>debian/rules</tt>
1872 are handled specially by <prgn>dpkg-source</prgn> - before
1873 applying the changes it will create the <tt>debian</tt>
1874 directory, and afterwards it will make
1875 <tt>debian/rules</tt> world-exectuable.
1881 <chapt id="controlfields"><heading>Control files and their fields
1885 Many of the tools in the <prgn>dpkg</prgn> suite manipulate
1886 data in a common format, known as control files. Binary and
1887 source packages have control data as do the <tt>.changes</tt>
1888 files which control the installation of uploaded files, and
1889 <prgn>dpkg</prgn>'s internal databases are in a similar
1893 <sect><heading>Syntax of control files
1897 A file consists of one or more paragraphs of fields. The
1898 paragraphs are separated by blank lines. Some control files
1899 only allow one paragraph; others allow several, in which
1900 case each paragraph often refers to a different package.
1904 Each paragraph is a series of fields and values; each field
1905 consists of a name, followed by a colon and the value. It
1906 ends at the end of the line. Horizontal whitespace (spaces
1907 and tabs) may occur before or after the value and is ignored
1908 there; it is conventional to put a single space after the
1913 Some fields' values may span several lines; in this case
1914 each continuation line <em>must</em> start with a space or
1915 tab. Any trailing spaces or tabs at the end of individual
1916 lines of a field value are ignored.
1920 Except where otherwise stated only a single line of data is
1921 allowed and whitespace is not significant in a field body.
1922 Whitespace may never appear inside names (of packages,
1923 architectures, files or anything else), version numbers or
1924 in between the characters of multi-character version
1929 Field names are not case-sensitive, but it is usual to
1930 capitalise the field names using mixed case as shown below.
1934 Blank lines, or lines consisting only of spaces and tabs,
1935 are not allowed within field values or between fields - that
1936 would mean a new paragraph.
1940 It is important to note that there are several fields which
1941 are optional as far as <prgn>dpkg</prgn> and the related
1942 tools are concerned, but which must appear in every Debian
1943 package, or whose omission may cause problems. When writing
1944 the control files for Debian packages you <em>must</em> read
1945 the Debian policy manual in conjuction with the details
1946 below and the list of fields for the particular file.</p>
1949 <sect><heading>List of fields
1952 <sect1 id="f-Package"><heading><tt>Package</tt>
1956 The name of the binary package. Package names consist of
1957 the alphanumerics and <tt>+</tt> <tt>-</tt> <tt>.</tt>
1958 (plus, minus and full stop).
1961 The characters <tt>@</tt> <tt>:</tt> <tt>=</tt>
1962 <tt>%</tt> <tt>_</tt> (at, colon, equals, percent
1963 and underscore) used to be legal and are still
1964 accepted when found in a package file, but may not be
1965 used in new packages
1971 They must be at least two characters and must start with
1972 an alphanumeric. In current versions of dpkg they are
1973 sort of case-sensitive<footnote><p>This is a
1974 bug.</p></footnote>; use lowercase package names unless
1975 the package you're building (or referring to, in other
1976 fields) is already using uppercase.</p>
1979 <sect1 id="f-Version"><heading><tt>Version</tt>
1983 This lists the source or binary package's version number -
1984 see <ref id="versions">.
1989 <sect1 id="f-Architecture"><heading><tt>Architecture</tt>
1993 This is the architecture string; it is a single word for
1994 the Debian architecture.
1998 <prgn>dpkg</prgn> will check the declared architecture of
1999 a binary package against its own compiled-in value before
2004 The special value <tt>all</tt> indicates that the package
2005 is architecture-independent.
2009 In the main <tt>debian/control</tt> file in the source
2010 package, or in the source package control file
2011 <tt>.dsc</tt>, a list of architectures (separated by
2012 spaces) is also allowed, as is the special value
2013 <tt>any</tt>. A list indicates that the source will build
2014 an architecture-dependent package, and will only work
2015 correctly on the listed architectures. <tt>any</tt>
2016 indicates that though the source package isn't dependent
2017 on any particular architecture and should compile fine on
2018 any one, the binary package(s) produced are not
2019 architecture-independent but will instead be specific to
2020 whatever the current build architecture is.
2024 In a <tt>.changes</tt> file the <tt>Architecture</tt>
2025 field lists the architecture(s) of the package(s)
2026 currently being uploaded. This will be a list; if the
2027 source for the package is being uploaded too the special
2028 entry <tt>source</tt> is also present.
2032 See <ref id="debianrules"> for information how to get the
2033 architecture for the build process.
2037 <sect1 id="f-Maintainer"><heading><tt>Maintainer</tt>
2041 The package maintainer's name and email address. The name
2042 should come first, then the email address inside angle
2043 brackets <tt><></tt> (in RFC822 format).
2047 If the maintainer's name contains a full stop then the
2048 whole field will not work directly as an email address due
2049 to a misfeature in the syntax specified in RFC822; a
2050 program using this field as an address must check for this
2051 and correct the problem if necessary (for example by
2052 putting the name in round brackets and moving it to the
2053 end, and bringing the email address forward).
2057 In a <tt>.changes</tt> file or parsed changelog data this
2058 contains the name and email address of the person
2059 responsible for the particular version in question - this
2060 may not be the package's usual maintainer.
2064 This field is usually optional in as far as the
2065 <prgn>dpkg</prgn> are concerned, but its absence when
2066 building packages usually generates a warning.</p>
2069 <sect1 id="f-Source"><heading><tt>Source</tt>
2073 This field identifies the source package name.
2077 In a main source control information or a
2078 <tt>.changes</tt> or <tt>.dsc</tt> file or parsed
2079 changelog data this may contain only the name of the
2084 In the control file of a binary package (or in a
2085 <tt>Packages</tt> file) it may be followed by a version
2086 number in parentheses.
2089 It is usual to leave a space after the package name if
2090 a version number is specified.
2092 </footnote> This version number may be omitted (and is, by
2093 <prgn>dpkg-gencontrol</prgn>) if it has the same value as
2094 the <tt>Version</tt> field of the binary package in
2095 question. The field itself may be omitted from a binary
2096 package control file when the source package has the same
2097 name and version as the binary package.
2101 <sect1><heading>Package interrelationship fields:
2102 <tt>Depends</tt>, <tt>Pre-Depends</tt>,
2103 <tt>Recommends</tt> <tt>Suggests</tt>, <tt>Conflicts</tt>,
2104 <tt>Provides</tt>, <tt>Replaces</tt>
2108 These fields describe the package's relationships with
2109 other packages. Their syntax and semantics are described
2110 in <ref id="relationships">.</p>
2113 <sect1 id="f-Description"><heading><tt>Description</tt>
2117 In a binary package <tt>Packages</tt> file or main source
2118 control file this field contains a description of the
2119 binary package, in a special format. See <ref
2120 id="descriptions"> for details.
2124 In a <tt>.changes</tt> file it contains a summary of the
2125 descriptions for the packages being uploaded. The part of
2126 the field before the first newline is empty; thereafter
2127 each line has the name of a binary package and the summary
2128 description line from that binary package. Each line is
2129 indented by one space.</p>
2132 <sect1 id="f-Essential"><heading><tt>Essential</tt>
2136 This is a boolean field which may occur only in the
2137 control file of a binary package (or in the
2138 <tt>Packages</tt> file) or in a per-package fields
2139 paragraph of a main source control data file.
2143 If set to <tt>yes</tt> then <prgn>dpkg</prgn> and
2144 <prgn>dselect</prgn> will refuse to remove the package
2145 (though it can be upgraded and/or replaced). The other
2146 possible value is <tt>no</tt>, which is the same as not
2147 having the field at all.</p>
2150 <sect1 id="f-classification"><heading><tt>Section</tt> and
2155 These two fields classify the package. The
2156 <tt>Priority</tt> represents how important that it is that
2157 the user have it installed; the <tt>Section</tt>
2158 represents an application area into which the package has
2163 When they appear in the <tt>debian/control</tt> file these
2164 fields give values for the section and priority subfields
2165 of the <tt>Files</tt> field of the <tt>.changes</tt> file,
2166 and give defaults for the section and priority of the
2171 The section and priority are represented, though not as
2172 separate fields, in the information for each file in the
2173 <qref id="f-Files"><tt>-File</tt></qref>field of a
2174 <tt>.changes</tt> file. The section value in a
2175 <tt>.changes</tt> file is used to decide where to install
2176 a package in the FTP archive.
2180 These fields are not used by by <prgn>dpkg</prgn> proper,
2181 but by <prgn>dselect</prgn> when it sorts packages and
2182 selects defaults. See the Debian policy manual for the
2183 priorities in use and the criteria for selecting the
2184 priority for a Debian package, and look at the Debian FTP
2185 archive for a list of currently in-use priorities.
2189 These fields may appear in binary package control files,
2190 in which case they provide a default value in case the
2191 <tt>Packages</tt> files are missing the information.
2192 <prgn>dpkg</prgn> and <prgn>dselect</prgn> will only use
2193 the value from a <tt>.deb</tt> file if they have no other
2194 information; a value listed in a <tt>Packages</tt> file
2195 will always take precedence. By default
2196 <prgn>dpkg-gencontrol</prgn> does not include the section
2197 and priority in the control file of a binary package - use
2198 the <tt>-isp</tt>, <tt>-is</tt> or <tt>-ip</tt> options to
2199 achieve this effect.</p>
2202 <sect1 id="f-Binary"><heading><tt>Binary</tt>
2206 This field is a list of binary packages.
2210 When it appears in the <tt>.dsc</tt> file it is the list
2211 of binary packages which a source package can produce. It
2212 does not necessarily produce all of these binary packages
2213 for every architecture. The source control file doesn't
2214 contain details of which architectures are appropriate for
2215 which of the binary packages.
2219 When it appears in a <tt>.changes</tt> file it lists the
2220 names of the binary packages actually being uploaded.
2224 The syntax is a list of binary packages separated by
2228 A space after each comma is conventional.
2230 </footnote> Currently the packages must be separated using
2231 only spaces in the <tt>.changes</tt> file.</p>
2234 <sect1 id="f-Installed-Size"><heading><tt>Installed-Size</tt>
2238 This field appears in the control files of binary
2239 packages, and in the <tt>Packages</tt> files. It gives
2240 the total amount of disk space required to install the
2245 The disk space is represented in kilobytes as a simple
2249 <sect1 id="f-Files"><heading><tt>Files</tt>
2253 This field contains a list of files with information about
2254 each one. The exact information and syntax varies with
2255 the context. In all cases the the part of the field
2256 contents on the same line as the field name is empty. The
2257 remainder of the field is one line per file, each line
2258 being indented by one space and containing a number of
2259 sub-fields separated by spaces.
2263 In the <tt>.dsc</tt> (Debian source control) file each
2264 line contains the MD5 checksum, size and filename of the
2265 tarfile and (if applicable) diff file which make up the
2266 remainder of the source package.
2269 That is, the parts which are not the
2272 </footnote> The exact forms of the filenames are described
2273 in <ref id="sourcearchives">.
2277 In the <tt>.changes</tt> file this contains one line per
2278 file being uploaded. Each line contains the MD5 checksum,
2279 size, section and priority and the filename. The section
2280 and priority are the values of the corresponding fields in
2281 the main source control file - see <ref
2282 id="f-classification">. If no section or priority is
2283 specified then <tt>-</tt> should be used, though section
2284 and priority values must be specified for new packages to
2285 be installed properly.
2289 The special value <tt>byhand</tt> for the section in a
2290 <tt>.changes</tt> file indicates that the file in question
2291 is not an ordinary package file and must by installed by
2292 hand by the distribution maintainers. If the section is
2293 <tt>byhand</tt> the priority should be <tt>-</tt>.
2297 If a new Debian revision of a package is being shipped and
2298 no new original source archive is being distributed the
2299 <tt>.dsc</tt> must still contain the <tt>Files</tt> field
2300 entry for the original source archive
2301 <tt><var>package</var>-<var>upstream-version</var>.orig.tar.gz</tt>,
2302 but the <tt>.changes</tt> file should leave it out. In
2303 this case the original source archive on the distribution
2304 site must match exactly, byte-for-byte, the original
2305 source archive which was used to generate the
2306 <tt>.dsc</tt> file and diff which are being uploaded.</p>
2311 id="f-Standards-Version"><heading><tt>Standards-Version</tt>
2315 The most recent version of the standards (the
2316 <prgn>dpkg</prgn> programmers' and policy manuals and
2317 associated texts) with which the package complies. This
2318 is updated manually when editing the source package to
2319 conform to newer standards; it can sometimes be used to
2320 tell when a package needs attention.
2324 Its format is the same as that of a version number except
2325 that no epoch or Debian revision is allowed - see <ref
2330 <sect1 id="f-Distribution"><heading><tt>Distribution</tt>
2334 In a <tt>.changes</tt> file or parsed changelog output
2335 this contains the (space-separated) name(s) of the
2336 distribution(s) where this version of the package should
2337 be or was installed. Distribution names follow the rules
2338 for package names. (See <ref id="f-Package">).
2342 Current distribution values are:
2344 <tag><em>stable</em></tag>
2347 This is the current `released' version of Debian
2348 GNU/Linux. A new version is released approximately
2349 every 3 months after the <em>development</em> code has
2350 been <em>frozen</em> for a month of testing. Once the
2351 distribution is <em>stable</em> only major bug fixes
2352 are allowed. When changes are made to this
2353 distribution, the release number is increased
2354 (for example: 1.2r1 becomes 1.2r2 then 1.2r3, etc).
2358 <tag><em>unstable</em></tag>
2361 This distribution value refers to the
2362 <em>developmental</em> part of the Debian distribution
2363 tree. New packages, new upstream versions of packages
2364 and bug fixes go into the <em>unstable</em> directory
2365 tree. Download from this distribution at your own
2369 <tag><em>contrib</em></tag>
2372 The packages with this distribution value do not meet
2373 the criteria for inclusion in the main Debian
2374 distribution as defined by the Policy Manual, but meet
2375 the criteria for the <em>contrib</em>
2376 Distribution. There is currently no distinction
2377 between stable and unstable packages in the
2378 <em>contrib</em> or <em>non-free</em>
2379 distributions. Use your best judgement in downloading
2380 from this Distribution.</p>
2383 <tag><em>non-free</em></tag>
2386 Like the packages in the <em>contrib</em> seciton,
2387 the packages in <em>non-free</em> do not meet the
2388 criteria for inclusion in the main Debian distribution
2389 as defined by the Policy Manual. Again, use your best
2390 judgement in downloading from this Distribution.</p>
2392 <tag><em>experimental</em></tag>
2395 The packages with this distribution value are deemed
2396 by their maintainers to be high risk. Oftentimes they
2397 represent early beta or developmental packages from
2398 various sources that the maintainers want people to
2399 try, but are not ready to be a part of the other parts
2400 of the Debian distribution tree. Download at your own
2404 <tag><em>frozen</em></tag>
2407 From time to time, (currently, every 3 months) the
2408 <em>unstable</em> distribution enters a state of
2409 `code-freeze' in anticipation of release as a
2410 <em>stable</em> version. During this period of testing
2411 (usually 4 weeks) only fixes for existing or
2412 newly-discovered bugs will be allowed.
2415 </taglist> You should list <em>all</em> distributions that
2416 the package should be installed into. Except in unusual
2417 circumstances, installations to <em>stable</em> should also
2418 go into <em>frozen</em> (if it exists) and
2419 <em>unstable</em>. Likewise, installations into
2420 <em>frozen</em> should also go into <em>unstable</em>.</p>
2423 <sect1 id="f-Urgency"><heading><tt>Urgency</tt>
2427 This is a description of how important it is to upgrade to
2428 this version from previous ones. It consists of a single
2429 keyword usually taking one of the values <tt>LOW</tt>,
2430 <tt>MEDIUM</tt> or <tt>HIGH</tt>) followed by an optional
2431 commentary (separated by a space) which is usually in
2432 parentheses. For example:
2434 Urgency: LOW (HIGH for diversions users)
2439 This field appears in the <tt>.changes</tt> file and in
2440 parsed changelogs; its value appears as the value of the
2441 <tt>urgency</tt> attribute in a <prgn>dpkg</prgn>-style
2442 changelog (see <ref id="dpkgchangelog">).
2446 Urgency keywords are not case-sensitive.</p>
2449 <sect1 id="f-Date"><heading><tt>Date</tt>
2453 In <tt>.changes</tt> files and parsed changelogs, this
2454 gives the date the package was built or last edited.</p>
2457 <sect1 id="f-Format"><heading><tt>Format</tt>
2461 This field occurs in <tt>.changes</tt> files, and
2462 specifies a format revision for the file. The format
2463 described here is version <tt>1.5</tt>. The syntax of the
2464 format value is the same as that of a package version
2465 number except that no epoch or Debian revision is allowed
2466 - see <ref id="versions">.</p>
2469 <sect1 id="f-Changes"><heading><tt>Changes</tt>
2473 In a <tt>.changes</tt> file or parsed changelog this field
2474 contains the human-readable changes data, describing the
2475 differences between the last version and the current one.
2479 There should be nothing in this field before the first
2480 newline; all the subsequent lines must be indented by at
2481 least one space; blank lines must be represented by a line
2482 consiting only of a space and a full stop.
2486 Each version's change information should be preceded by a
2487 `title' line giving at least the version, distribution(s)
2488 and urgency, in a human-readable way.
2492 If data from several versions is being returned the entry
2493 for the most recent version should be returned first, and
2494 entries should be separated by the representation of a
2495 blank line (the `title' line may also be followed by the
2496 representation of blank line).</p>
2499 <sect1 id="f-Filename"><heading><tt>Filename</tt> and
2500 <tt>MSDOS-Filename</tt>
2504 These fields in <tt>Packages</tt> files give the
2505 filename(s) of (the parts of) a package in the
2506 distribution directories, relative to the root of the
2507 Debian hierarchy. If the package has been split into
2508 several parts the parts are all listed in order, separated
2512 <sect1 id="f-Size"><heading><tt>Size</tt> and <tt>MD5sum</tt>
2516 These fields in <tt>Packages</tt> files give the size (in
2517 bytes, expressed in decimal) and MD5 checksum of the
2518 file(s) which make(s) up a binary package in the
2519 distribution. If the package is split into several parts
2520 the values for the parts are listed in order, separated by
2524 <sect1 id="f-Status"><heading><tt>Status</tt>
2528 This field in <prgn>dpkg</prgn>'s status file records
2529 whether the user wants a package installed, removed or
2530 left alone, whether it is broken (requiring
2531 reinstallation) or not and what its current state on the
2532 system is. Each of these pieces of information is a
2536 <sect1 id="f-Config-Version"><heading><tt>Config-Version</tt>
2540 If a package is not installed or not configured, this
2541 field in <prgn>dpkg</prgn>'s status file records the last
2542 version of the package which was successfully
2546 <sect1 id="f-Conffiles"><heading><tt>Conffiles</tt>
2550 This field in <prgn>dpkg</prgn>'s status file contains
2551 information about the automatically-managed configuration
2552 files held by a package. This field should <em>not</em>
2553 appear anywhere in a package!</p>
2556 <sect1><heading>Obsolete fields
2560 These are still recognised by <prgn>dpkg</prgn> but should
2561 not appear anywhere any more.
2562 <taglist compact="compact">
2564 <tag><tt>Revision</tt></tag>
2565 <tag><tt>Package-Revision</tt></tag>
2566 <tag><tt>Package_Revision</tt></tag>
2569 The Debian revision part of the package version was
2570 at one point in a separate control file field. This
2571 field went through several names.</p>
2574 <tag><tt>Recommended</tt></tag>
2575 <item><p>Old name for <tt>Recommends</tt></p>
2578 <tag><tt>Optional</tt></tag>
2579 <item><p>Old name for <tt>Suggests</tt>.</p>
2581 <tag><tt>Class</tt></tag>
2582 <item><p>Old name for <tt>Priority</tt>.</p>
2590 <chapt id="versions"><heading>Version numbering
2594 Every package has a version number, in its <tt>Version</tt>
2599 <prgn>dpkg</prgn> imposes an ordering on version numbers, so
2600 that it can tell whether packages are being up- or downgraded
2601 and so that <prgn>dselect</prgn> can tell whether a package it
2602 finds available is newer than the one installed on the system.
2603 The version number format has the most significant parts (as
2604 far as comparison is concerned) at the beginning.
2608 The version number format is:
2609 &lsqb<var>epoch/<tt>:</tt>]<var>upstream-version</var>[<tt>-/<var>debian-revision</var>].</tt></var>
2613 The three components here are:
2615 <tag><var>epoch</var></tag>
2619 This is a single unsigned integer, which should usually
2620 be small. It may be omitted, in which case zero is
2621 assumed. If it is omitted then the
2622 <var>upstream-version</var> may not contain any colons.
2626 It is provided to allow mistakes in the version numbers
2627 of older versions of a package, and also a package's
2628 previous version numbering schemes, to be left behind.
2632 <prgn>dpkg</prgn> will not usually display the epoch
2633 unless it is essential (non-zero, or if the
2634 <var>upstream-version</var> contains a colon);
2635 <prgn>dselect</prgn> does not display epochs at all in
2636 the main part of the package selection display.</p>
2639 <tag><var>upstream-version</var></tag>
2643 This is the main part of the version. It is usually
2644 version number of the original (`upstream') package of
2645 which the <tt>.deb</tt> file has been made, if this is
2646 applicable. Usually this will be in the same format as
2647 that specified by the upstream author(s); however, it
2648 may need to be reformatted to fit into
2649 <prgn>dpkg</prgn>'s format and comparison scheme.
2653 The comparison behaviour of <prgn>dpkg</prgn> with
2654 respect to the <var>upstream-version</var> is described
2655 below. The <var>upstream-version</var> portion of the
2656 version number is mandatory.
2660 The <var>upstream-version</var> may contain only
2661 alphanumerics and the characters <tt>.</tt> <tt>+</tt>
2662 <tt>-</tt> <tt>:</tt> (full stop, plus, hyphen, colon)
2663 and should start with a digit. If there is no
2664 <var>debian-revision</var> then hyphens are not allowed;
2665 if there is no <var>epoch</var> then colons are not
2669 <tag><var>debian-revision</var></tag>
2673 This part of the version represents the version of the
2674 modifications that were made to the package to make it a
2675 Debian binary package. It is in the same format as the
2676 <var>upstream-version</var> and <prgn>dpkg</prgn>
2677 compares it in the same way.
2681 It is optional; if it isn't present then the
2682 <var>upstream-version</var> may not contain a hyphen.
2683 This format represents the case where a piece of
2684 software was written specifically to be turned into a
2685 Debian binary package, and so there is only one
2686 `debianization' of it and therefore no revision
2687 indication is required.
2691 It is conventional to restart the
2692 <var>debian-revision</var> at <tt>1</tt> each time the
2693 <var>upstream-version</var> is increased.
2697 <prgn>dpkg</prgn> will break the
2698 <var>upstream-version</var> and
2699 <var>debian-revision</var> apart at the last hyphen in
2700 the string. The absence of a <var>debian-revision</var>
2701 compares earlier than the presence of one (but note that
2702 the <var>debian-revision</var> is the least significant
2703 part of the version number).
2707 The <var>debian-revision</var> may contain only
2708 alphanumerics and the characters <tt>+</tt> and
2709 <tt>.</tt> (plus and full stop).
2713 The <var>upstream-version</var> and <var>debian-revision</var> parts are
2714 compared by <prgn>dpkg</prgn> using the same algorithm:
2718 The strings are compared from left to right.
2722 First the initial part of each string consisting entirely of
2723 non-digit characters is determined. These two parts (one of
2724 which may be empty) are compared lexically. If a difference
2725 is found it is returned. The lexical comparison is a
2726 comparison of ASCII values modified so that all the letters
2727 sort earlier than all the non-letters.
2731 Then the initial part of the remainder of each string which
2732 consists entirely of digit characters is determined. The
2733 numerical values of these two parts are compared, and any
2734 difference found is returned as the result of the comparison.
2735 For these purposes an empty string (which can only occur at
2736 the end of one or both version strings being compared) counts
2741 These two steps are repeated (chopping initial non-digit
2742 strings and initial digit strings off from the start) until a
2743 difference is found or both strings are exhausted.
2747 Note that the purpose of epochs is to allow us to leave behind
2748 mistakes in version numbering, and to cope with situations
2749 where the version numbering changes. It is <em>not</em> there
2750 to cope with version numbers containing strings of letters
2751 which <prgn>dpkg</prgn> cannot interpret (such as
2752 <tt>ALPHA</tt> or <tt>pre-</tt>), or with silly orderings (the
2753 author of this manual has heard of a package whose versions
2754 went <tt>1.1</tt>, <tt>1.2</tt>, <tt>1.3</tt>, <tt>1</tt>,
2755 <tt>2.1</tt>, <tt>2.2</tt>, <tt>2</tt> and so forth).
2759 If an upstream package has problematic version numbers they
2760 should be converted to a sane form for use in the
2761 <tt>Version</tt> field.
2765 If you need to compare version numbers in a script, you may use
2766 <tt>dpkg --compare-versions ...</tt>. Type <tt>dpkg
2767 --help</tt> for details on arguments.
2771 <heading>Version numbers based on dates</heading>
2773 In general, Debian packages should use the same version
2774 numbers as the upstream sources.</p>
2777 However, in some cases where the upstream version number is
2778 based on a date (e.g., a development `snapshot' release)
2779 dpkg cannot handle these version numbers currently, without
2780 epochs. For example, dpkg will consider `96May01' to be
2781 greater than `96Dec24'.</p>
2784 To prevent having to use epochs for every new upstream
2785 version, the version number should be changed to the
2786 following format in such cases: `19960501', `19961224'. It
2787 is up to the maintainer whether he/she wants to bother the
2788 upstream maintainer to change the version numbers upstream,
2792 Note, that other version formats based on dates which are
2793 parsed correctly by dpkg should <em>not</em> be changed.</p>
2796 Native Debian packages (i.e., packages which have been
2797 written especially for Debian) whose version numbers include
2798 dates should always use the `YYYYMMDD' format.</p>
2802 <chapt id="maintainerscripts"><heading>Package maintainer scripts
2803 and installation procedure
2806 <sect><heading>Introduction to package maintainer scripts
2810 It is possible to supply scripts as part of a package which
2811 <prgn>dpkg</prgn> will run for you when your package is
2812 installed, upgraded or removed.
2816 These scripts should be the files <tt>preinst</tt>,
2817 <tt>postinst</tt>, <tt>prerm</tt> and <tt>postrm</tt> in the
2818 control area of the package. They must be proper exectuable
2819 files; if they are scripts (which is recommended) they must
2820 start with the usual <tt>#!</tt> convention. They should be
2821 readable and executable to anyone, and not world-writeable.
2825 <prgn>dpkg</prgn> looks at the exit status from these
2826 scripts. It is important that they exit with a non-zero
2827 status if there is an error, so that <prgn>dpkg</prgn> can
2828 stop its processing. For shell scripts this means that you
2829 <em>almost always</em> need to use <tt>set -e</tt> (this is
2830 usually true when writing shell scripts, in fact). It is
2831 also important, of course, that they don't exit with a
2832 non-zero status if everything went well.
2836 It is necessary for the error recovery procedures that the
2837 scripts be idempotent: ie, invoking the same script several
2838 times in the same situation should do no harm. If the first
2839 call failed, or aborted half way through for some reason,
2840 the second call should merely do the things that were left
2841 undone the first time, if any, and exit with a success
2846 When a package is upgraded a combination of the scripts from
2847 the old and new packages is called in amongst the other
2848 steps of the upgrade procedure. If your scripts are going
2849 to be at all complicated you need to be aware of this, and
2850 may need to check the arguments to your scripts.
2854 Broadly speaking the <prgn>preinst</prgn> is called before
2855 (a particular version of) a package is installed, and the
2856 <prgn>postinst</prgn> afterwards; the <prgn>prerm</prgn>
2857 before (a version of) a package is removed and the
2858 <prgn>postrm</prgn> afterwards.
2861 next paragraph by Guy Maor to close bug #2481
2864 <p> Programs called from maintainer scripts should not
2865 normally have a path prepended to them. Before installation
2866 is started <prgn>dpkg</prgn> checks to see if the programs
2867 <prgn>ldconfig</prgn>, <prgn>start-stop-daemon</prgn>,
2868 <prgn>install-info</prgn>, and <prgn>update-rc.d</prgn> can
2869 be found via the <tt>PATH</tt> environment variable. Those
2870 programs, and any other program that one would expect to on
2871 the <tt>PATH</tt>, should thus be invoked without an
2872 absolute pathname. Maintainer scripts should also not reset
2873 the <tt>PATH</tt>, though they might choose to modify it by
2874 pre- or appending package-specific directories. These
2875 considerations really apply to all shell scripts.</p>
2878 <sect id="mscriptsinstact"><heading>Summary of ways maintainer
2883 <list compact="compact">
2885 <p><var>new-preinst</var> <tt>install</tt></p>
2888 <p><var>new-preinst</var> <tt>install</tt>
2889 <var>old-version</var></p>
2892 <p><var>new-preinst</var> <tt>upgrade</tt>
2893 <var>old-version</var></p>
2896 <p><var>old-preinst</var> <tt>abort-upgrade</tt>
2897 <var>new-version</var>
2903 <list compact="compact">
2905 <p><var>postinst</var> <tt>configure</tt>
2906 <var>most-recently-configured-version</var></p>
2909 <p><var>old-postinst</var> <tt>abort-upgrade</tt>
2910 <var>new version</var></p>
2913 <p><var>conflictor's-postinst</var> <tt>abort-remove</tt>
2914 <tt>in-favour</tt> <var>package</var>
2915 <var>new-version</var></p>
2919 <var>deconfigured's-postinst</var>
2920 <tt>abort-deconfigure</tt> <tt>in-favour</tt>
2921 <var>failed-install-package</var> <var>version</var>
2922 <tt>removing</tt> <var>conflicting-package</var>
2929 <list compact="compact">
2931 <p><var>prerm</var> <tt>remove</tt></p>
2934 <p><var>old-prerm</var> <tt>upgrade</tt>
2935 <var>new-version</var></p>
2938 <p><var>new-prerm</var> <tt>failed-upgrade</tt>
2939 <var>old-version</var></p>
2942 <p><var>conflictor's-prerm</var> <tt>remove</tt>
2943 <tt>in-favour</tt> <var>package</var>
2944 <var>new-version</var></p>
2948 <var>deconfigured's-prerm</var> <tt>deconfigure</tt>
2949 <tt>in-favour</tt> <var>package-being-installed</var>
2950 <var>version</var> <tt>removing</tt>
2951 <var>conflicting-package</var>
2958 <list compact="compact">
2960 <p><var>postrm</var> <tt>remove</tt></p>
2963 <p><var>postrm</var> <tt>purge</tt></p>
2967 <var>old-postrm</var> <tt>upgrade</tt>
2968 <var>new-version</var></p>
2971 <p><var>new-postrm</var> <tt>failed-upgrade</tt>
2972 <var>old-version</var></p>
2975 <p><var>new-postrm</var> <tt>abort-install</tt></p>
2978 <p><var>new-postrm</var> <tt>abort-install</tt>
2979 <var>old-version</var></p>
2982 <p><var>new-postrm</var> <tt>abort-upgrade</tt>
2983 <var>old-version</var></p>
2987 <var>disappearer's-postrm</var> <tt>disappear</tt>
2988 <var>overwriter</var>
2989 <var>overwriter-version</var></p></item>
2994 <sect id="unpackphase"><heading>Details of unpack phase of
2995 installation or upgrade
2999 The procedure on installation/upgrade/overwrite/disappear
3000 (ie, when running <tt>dpkg --unpack</tt>, or the unpack
3002 --install</tt>) is as follows. In each case if an error occurs the
3003 actions in are general run backwards - this means that the maintainer
3004 scripts are run with different arguments in reverse order. These are
3005 the `error unwind' calls listed below.
3012 <p>If a version the package is already
3015 <var>old-prerm</var> upgrade <var>new-version</var>
3020 If this gives an error (ie, a non-zero exit
3021 status), dpkg will attempt instead:
3023 <var>new-prerm</var> failed-upgrade <var>old-version</var>
3025 Error unwind, for both the above cases:
3027 <var>old-postinst</var> abort-upgrade <var>new-version</var>
3035 <p>If a `conflicting' package is being removed at the same time:
3039 If any packages depended on that conflicting
3040 package and <tt>--auto-deconfigure</tt> is
3041 specified, call, for each such package:
3043 <var>deconfigured's-prerm</var> deconfigure \
3044 in-favour <var>package-being-installed</var> <var>version</var> \
3045 removing <var>conflicting-package</var> <var>version</var>
3049 <var>deconfigured's-postinst</var> abort-deconfigure \
3050 in-favour <var>package-being-installed-but-failed</var> <var>version</var> \
3051 removing <var>conflicting-package</var> <var>version</var>
3053 The deconfigured packages are marked as
3054 requiring configuration, so that if
3055 <tt>--install</tt> is used they will be
3056 configured again if possible.</p>
3059 <p>To prepare for removal of the conflicting package, call:
3061 <var>conflictor's-prerm</var> remove in-favour <var>package</var> <var>new-version</var>
3065 <var>conflictor's-postinst</var> abort-remove \
3066 in-favour <var>package</var> <var>new-version</var>
3077 <p>If the package is being upgraded, call:
3079 <var>new-preinst</var> upgrade <var>old-version</var>
3084 Otherwise, if the package had some configuration
3085 files from a previous version installed (ie, it
3086 is in the `configuration files only' state):
3088 <var>new-preinst</var> install <var>old-version</var>
3092 <p>Otherwise (ie, the package was completely purged):
3094 <var>new-preinst</var> install
3096 Error unwind versions, respectively:
3098 <var>new-postrm</var> abort-upgrade <var>old-version</var>
3099 <var>new-postrm</var> abort-install <var>old-version</var>
3100 <var>new-postrm</var> abort-install
3110 The new package's files are unpacked, overwriting any
3111 that may be on the system already, for example any
3112 from the old version of the same package or from
3113 another package (backups of the old files are left
3114 around, and if anything goes wrong dpkg will attempt
3115 to put them back as part of the error unwind).
3119 It is an error for a package to contains files which
3120 are on the system in another package, unless
3121 <tt>Replaces</tt> is used (see <ref id="replaces">).
3122 Currently the <tt>--force-overwrite</tt> flag is
3123 enabled, downgrading it to a warning, but this may not
3128 It is a more serious error for a package to contain a
3129 plain file or other kind of nondirectory where another
3130 package has a directory (again, unless
3131 <tt>Replaces</tt> is used). This error can be
3132 overridden if desired using
3133 <tt>--force-overwrite-dir</tt>, but this is not
3138 Packages which overwrite each other's files produce
3139 behaviour which though deterministic is hard for the
3140 system administrator to understand. It can easily
3141 lead to `missing' programs if, for example, a package
3142 is installed which overwrites a file from another
3143 package, and is then removed again.
3146 Part of the problem is due to what is arguably a
3147 bug in <prgn>dpkg</prgn>.
3153 A directory will never be replaced by a symbolic links
3154 to a directory or vice versa; instead, the existing
3155 state (symlink or not) will be left alone and
3156 <prgn>dpkg</prgn> will follow the symlink if there is
3164 <p>If the package is being upgraded, call
3166 <var>old-postrm</var> upgrade <var>new-version</var>
3170 <p>If this fails, <prgn>dpkg</prgn> will attempt:
3172 <var>new-postrm</var> failed-upgrade <var>old-version</var>
3174 Error unwind, for both cases:
3176 <var>old-preinst</var> abort-upgrade <var>new-version</var>
3181 This is the point of no return - if <prgn>dpkg</prgn>
3182 gets this far, it won't back off past this point if an
3183 error occurs. This will leave the package in a fairly
3184 bad state, which will require a successful
3185 reinstallation to clear up, but it's when
3186 <prgn>dpkg</prgn> starts doing things that are
3191 Any files which were in the old version of the package
3192 but not in the new are removed.</p>
3195 <p>The new file list replaces the old.</p>
3198 <p>The new maintainer scripts replace the old.</p>
3202 <p>Any packages all of whose files have been overwritten during the
3203 installation, and which aren't required for
3204 dependencies, are considered to have been removed.
3205 For each such package,
3208 <p><prgn>dpkg</prgn> calls:
3210 <var>disappearer's-postrm</var> disappear \
3211 <var>overwriter</var> <var>overwriter-version</var>
3216 <p>The package's maintainer scripts are removed.
3221 It is noted in the status database as being in a
3222 sane state, namely not installed (any conffiles
3223 it may have are ignored, rather than being
3224 removed by <prgn>dpkg</prgn>). Note that
3225 disappearing packages do not have their prerm
3226 called, because <prgn>dpkg</prgn> doesn't know
3227 in advance that the package is going to
3236 Any files in the package we're unpacking that are also
3237 listed in the file lists of other packages are removed
3238 from those lists. (This will lobotomise the file list
3239 of the `conflicting' package if there is one.)
3244 The backup files made during installation, above, are
3251 The new package's status is now sane, and recorded as
3252 `unpacked'. Here is another point of no return - if
3253 the conflicting package's removal fails we do not
3254 unwind the rest of the installation; the conflicting
3255 package is left in a half-removed limbo.
3260 If there was a conflicting package we go and do the
3261 removal actions (described below), starting with the
3262 removal of the conflicting package's files (any that
3263 are also in the package being installed have already
3264 been removed from the conflicting package's file list,
3265 and so do not get removed now).
3272 <sect><heading>Details of configuration
3276 When we configure a package (this happens with <tt>dpkg
3277 --install</tt>, or with <tt>--configure</tt>), we first
3278 update the conffiles and then call:
3280 <var>postinst</var> configure <var>most-recently-configured-version</var>
3285 No attempt is made to unwind after errors during
3290 If there is no most recently configured version
3291 <prgn>dpkg</prgn> will pass a null argument; older versions
3292 of dpkg may pass <tt><unknown></tt> (including the
3293 angle brackets) in this case. Even older ones do not pass a
3294 second argument at all, under any circumstances.
3298 <sect><heading>Details of removal and/or configuration purging
3306 <var>prerm</var> remove
3312 The package's files are removed (except conffiles).
3317 <var>postrm</var> remove
3321 <p>All the maintainer scripts except the postrm are removed.
3325 If we aren't purging the package we stop here. Note
3326 that packages which have no postrm and no conffiles
3327 are automatically purged when removed, as there is no
3328 difference except for the <prgn>dpkg</prgn>
3333 The conffiles and any backup files (<tt>~</tt>-files,
3334 <tt>#*#</tt> files, <tt>%</tt>-files,
3335 <tt>.dpkg-{old,new,tmp}</tt>, etc.) are removed.</p>
3339 <var>postrm</var> purge
3343 <p>The package's file list is removed.</p>
3346 No attempt is made to unwind after errors during
3351 <chapt id="descriptions"><heading>Descriptions of packages - the
3352 <tt>Description</tt> field
3356 The <tt>Description</tt> control file field is used by
3357 <prgn>dselect</prgn> when the user is selecting which packages
3358 to install and by <prgn>dpkg</prgn> when it displays
3359 information about the status of packages and so forth. It is
3360 included on the FTP site in the <prgn>Packages</prgn> files,
3361 and may also be used by the Debian WWW pages.
3365 The description is intended to describe the program to a user
3366 who has never met it before so that they know whether they
3367 want to install it. It should also give information about the
3368 significant dependencies and conflicts between this package
3369 and others, so that the user knows why these dependencies and
3370 conflicts have been declared.
3374 The field's format is as follows:
3376 Description: <var>single line synopsis</var>
3377 <var>extended description over several lines</var>
3382 The synopsis is often printed in lists of packages and so
3383 forth, and should be as informative as possible. Every
3384 package should also have an extended description.
3387 <sect><heading>Types of formatting line in the extended
3395 Those starting with a single space are part of a
3396 paragraph. Successive lines of this form will be
3397 word-wrapped when displayed. The leading space will
3398 usually be stripped off.
3404 Those starting with two or more spaces. These will be
3405 displayed verbatim. If the display cannot be panned
3406 horizontally the displaying program will linewrap them
3407 `hard' (ie, without taking account of word breaks).
3408 If it can they will be allowed to trail off to the
3409 right. None, one or two initial spaces may be
3410 deleted, but the number of spaces deleted from each
3411 line will be the same (so that you can have indenting
3412 work correctly, for example).
3417 <p>Those containing a single space followed by a single full stop
3418 character. These are rendered as blank lines. This
3419 is the <em>only</em> way to get a blank line - see
3425 Those containing a space, a full stop and some more
3426 characters. These are for future expansion. Do not
3433 <sect><heading>Notes about writing descriptions
3437 <em>Always</em> start extended description lines with at least one
3438 whitespace character. Fields in the control file and in the Packages
3439 file are separated by field names starting in the first column, just
3440 as message header fields are in RFC822. Forgetting the whitespace
3441 will cause <prgn>dpkg-deb</prgn>
3444 Version 0.93.23 or later.
3446 </footnote> to produce a syntax error when trying to build
3447 the package. If you force it to build anyway
3448 <prgn>dpkg</prgn> will refuse to install the resulting
3453 <em>Do not</em> include any completely <em>empty</em>
3454 lines. These separate different records in the Packages file
3455 and different packages in the <tt>debian/control</tt> file,
3456 and are forbidden in package control files. See the
3457 previous paragraph for what happens if you get this wrong.
3461 The single line synopsis should be kept brief - certainly
3462 under 80 characters. <prgn>dselect</prgn> displays between
3463 25 and 49 characters without panning if you're using an
3464 80-column terminal, depending on what display options are in
3469 Do not include the package name in the synopsis line. The
3470 display software knows how to display this already, and you
3471 do not need to state it. Remember that in many situations
3472 the user may only see the synopsis line - make it as
3473 informative as you can.
3477 The extended description should describe what the package
3478 does and how it relates to the rest of the system (in terms
3479 of, for example, which subsystem it is which part of).
3483 The blurb that comes with a program in its announcements
3484 and/or <prgn>README</prgn> files is rarely suitable for use
3485 in a description. It is usually aimed at people who are
3486 already in the community where the package is used. The
3487 description field needs to make sense to anyone, even people
3488 who have no idea about any of the things the package deals
3493 Put important information first, both in the synopis and
3494 extended description. Sometimes only the first part of the
3495 synopsis or of the description will be displayed. You can
3496 assume that there will usually be a way to see the whole
3497 extended description.
3501 You may include information about dependencies and so forth
3502 in the extended description, if you wish.
3506 Do not use tab characters. Their effect is not predictable.
3510 Do not try to linewrap the summary (the part on the same
3511 line as the field name <tt>Description</tt>) into the
3512 extended description. This will not work correctly when the
3513 full description is displayed, and makes no sense where only
3514 the summary is available.</p>
3517 <sect><heading>Example description in control file for Smail
3523 Version: 3.1.29.1-13
3524 Maintainer: Ian Jackson <iwj10@cus.cam.ac.uk>
3525 Recommends: pine | mailx | elm | emacs | mail-user-agent
3527 Depends: cron, libc5
3529 Provides: mail-transport-agent
3530 Description: Electronic mail transport system.
3531 Smail is the recommended mail transport agent (MTA) for Debian.
3533 An MTA is the innards of the mail system - it takes messages from
3534 user-friendly mailer programs and arranges for them to be delivered
3535 locally or passed on to other systems as required.
3537 In order to make use of it you must have one or more user level
3538 mailreader programs such as elm, pine, mailx or Emacs (which has Rmail
3539 and VM as mailreaders) installed. If you wish to send messages other
3540 than just to other users of your system you must also have appropriate
3541 networking support, in the form of IP or UUCP.
3547 <chapt id="relationships"><heading>Declaring relationships between
3552 Packages can declare in their control file that they have
3553 certain relationships to other packages - for example, that
3554 they may not be installed at the same time as certain other
3555 packages, and/or that they depend on the presence of others,
3556 or that they should overwrite files in certain other packages
3561 This is done using the <tt>Depends</tt>, <tt>Recommends</tt>,
3562 <tt>Suggests</tt>, <tt>Conflicts</tt>, <tt>Provides</tt> and
3563 <tt>Replaces</tt> control file fields.
3567 Source packages may declare relationships to binary packages,
3568 saying that they require certain binary packages being
3569 installed or absent at the time of building the package.
3573 This is done using the <tt>Build-Depends</tt>,
3574 <tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt>, and
3575 <tt>Build-Conflicts-Indep</tt> control file fields.
3578 <sect id="depsyntax"><heading>Syntax of relationship fields
3582 These fields all have a uniform syntax. They are a list of
3583 package names separated by commas.
3587 In <tt>Depends</tt>, <tt>Recommends</tt>, <tt>Suggests</tt>,
3588 <tt>Pre-Depends</tt>, <tt>Build-Depends</tt> and
3589 <tt>Build-Depends-Indep</tt>(the fields which declare
3590 dependencies of the package in which they occur on other
3591 packages) these package names may also be lists of
3592 alternative package names, separated by vertical bar symbols
3593 <tt>|</tt> (pipe symbols).
3597 All the fields except <tt>Provides</tt> may restrict their
3598 applicability to particular versions of each named package.
3599 This is done in parentheses after each individual package
3600 name; the parentheses should contain a relation from the
3601 list below followed by a version number, in the format
3602 described in <ref id="versions">.
3606 The relations allowed are <tt><<</tt>, <tt><=</tt>,
3607 <tt>=</tt>, <tt>>=</tt> and <tt>>></tt> for
3608 strictly earlier, earlier or equal, exactly equal, later or
3609 equal and strictly later, respectively. The forms
3610 <tt><</tt> and <tt>></tt> were used to mean
3611 earlier/later or equal, rather than strictly earlier/later,
3612 so they should not appear in new packages (though
3613 <prgn>dpkg</prgn> still supports them).
3617 Whitespace may appear at any point in the version
3618 specification, and must appear where it's necessary to
3619 disambiguate; it is not otherwise significant. For
3620 consistency and in case of future changes to
3621 <prgn>dpkg</prgn> it is recommended that a single space be
3622 used after a version relationship and before a version
3623 number; it is usual also to put a single space after each
3624 comma, on either side of each vertical bar, and before each
3633 Depends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh
3638 All fields that specify build-time relationships
3639 (<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
3640 <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>)
3641 may be restricted to a certain set of architectures. This
3642 is done in brackets after each individual package name and
3643 the optional version specification. The brackets enclose a
3644 list of Debian architecture names separated by whitespace.
3645 An exclamation mark may be prepended to each name. If the
3646 current Debian host architecture is not in this list and
3647 there are no exclamation marks in the list, or it is in the
3648 list with a prepended exclamation mark, the package name and
3649 the associated version specification are ignored completely
3650 for the purposes of defining the relationships.
3657 Build-Depends-Indep: texinfo
3658 Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
3659 hurd-dev [hurd-i386], gnumach-dev [hurd-i386]
3665 <heading>Binary Dependencies - <tt>Depends</tt>,
3666 <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Pre-Depends</tt>
3670 These four fields are used to declare a dependency by one
3671 package on another. They appear in the depending package's
3676 All but <tt>Pre-Depends</tt> (discussed below) take effect
3677 <em>only</em> when a package is to be configured. They do
3678 not prevent a package being on the system in an unconfigured
3679 state while its dependencies are unsatisfied, and it is
3680 possible to replace a package whose dependencies are
3681 satisfied and which is properly installed with a different
3682 version whose dependencies are not and cannot be satisfied;
3683 when this is done the depending package will be left
3684 unconfigured (since attempts to configure it will give
3685 errors) and will not function properly.
3689 For this reason packages in an installation run are usually
3690 all unpacked first and all configured later; this gives
3691 later versions of packages with dependencies on later
3692 versions of other packages the opportunity to have their
3693 dependencies satisfied.
3697 Thus <tt>Depends</tt> allows package maintainers to impose
3698 an order in which packages should be configured.
3700 <tag><tt>Depends</tt></tag>
3703 <p>This declares an absolute dependency.
3707 <prgn>dpkg</prgn> will not configure packages whose
3708 dependencies aren't satisfied. If it is asked to make
3709 an installation which would cause an installed
3710 package's dependencies to become unsatisfied it will
3714 Current versions (1.2.4) of <prgn>dpkg</prgn> have
3715 a bug in this area which will cause some of these
3716 problems to be ignored.
3718 </footnote>, unless <tt>--auto-deconfigure</tt> is
3719 specified, in which case those packages will be
3720 deconfigured before the installation proceeds.
3724 <prgn>dselect</prgn> makes it hard for the user to
3725 select packages for installation, removal or upgrade
3726 in a way that would mean that packages'
3727 <prgn>Depends</prgn> fields would be unsatisfied. The
3728 user can override this if they wish, for example if
3729 they know that <prgn>dselect</prgn> has an out-of-date
3730 view of the real package relationships.
3734 The <tt>Depends</tt> field should be used if the
3735 depended-on package is required for the depending
3736 package to provide a significant amount of
3740 <tag><tt>Recommends</tt></tag>
3742 <p>This declares a strong, but not absolute, dependency.
3746 <tt>Recommends</tt> is ignored by <prgn>dpkg</prgn>,
3747 so that users using the command-line (who are presumed
3748 to know what they're doing) will not be impeded.
3752 It is treated by <prgn>dselect</prgn> exactly as
3753 <tt>Depends</tt> is; this makes it hard for the user
3754 to select things so as to leave <tt>Recommends</tt>
3755 fields unsatisfied, but they are able to do so by
3760 The <tt>Recommends</tt> field should list packages
3761 that would be found together with this one in all but
3762 unusual installations.</p>
3765 <tag><tt>Suggests</tt></tag>
3769 This is used to declare that one package may be more
3770 useful with one or more others. Using this field
3771 tells the packaging system and the user that the
3772 listed packages are related to this one and can
3773 perhaps enhance its usefulness, but that installing
3774 this one without them is perfectly reasonable.
3778 <prgn>dselect</prgn> will offer suggsted packages to
3779 the system administrator when they select the
3780 suggesting package, but the default is not to install
3781 the suggested package.</p>
3784 <tag><tt>Pre-Depends</tt></tag>
3787 <p>This field is like <tt>Depends</tt>, except that it also forces
3788 <prgn>dpkg</prgn> to complete installation of the
3789 packages named before even starting the installation
3790 of the package which declares the predependency.
3794 <prgn>dselect</prgn> checks for predependencies when
3795 it is doing an installation run, and will attempt to
3796 find the packages which are required to be installed
3797 first and do so in the right order.
3801 However, this process is slow (because it requires
3802 repeated invocations of <prgn>dpkg</prgn>) and
3803 troublesome (because it requires guessing where to
3804 find the appropriate files).
3808 For these reasons, and because this field imposes
3809 restrictions on the order in which packages may be
3810 unpacked (which can be difficult for installations
3811 from multipart media, for example),
3812 <tt>Pre-Depends</tt> should be used sparingly,
3813 preferably only by packages whose premature upgrade or
3814 installation would hamper the ability of the system to
3815 continue with any upgrade that might be in progress.
3819 When the package declaring it is being configured, a
3820 <tt>Pre-Dependency</tt> will be considered satisfied
3821 only if the depending package has been correctly
3822 configured, just as if an ordinary <tt>Depends</tt>
3827 However, when a package declaring a predependency is
3828 being unpacked the predependency can be satisfied even
3829 if the depended-on package(s) are only unpacked or
3830 half-configured, provided that they have been
3831 configured correctly at some point in the past (and
3832 not removed or partially removed since). In this case
3833 both the previously-configured and currently unpacked
3834 or half-configured versions must satisfy any version
3835 clause in the <tt>Pre-Depends</tt> field.
3841 When selecting which level of dependency to use you should
3842 consider how important the depended-on package is to the
3843 functionality of the one declaring the dependency. Some
3844 packages are composed of components of varying degrees of
3845 importance. Such a package should list using
3846 <tt>Depends</tt> the package(s) which are required by the
3847 more important components. The other components'
3848 requirements may be mentioned as Suggestions or
3849 Recommendations, as appropriate to the components' relative
3853 <sect1><heading>Dependencies on shared libraries
3857 The dependency fields listed above are used by packages
3858 which need shared libraries to declare dependencies on the
3859 appropriate packages.
3863 These dependencies are usually determined automatically
3864 using <prgn>dpkg-shlibdeps</prgn> and inserted in the
3865 package control file using the control file substitution
3866 variables mechanism; see <ref id="srcsubstvars"> and
3867 <ref id="sourcetools">.
3871 <sect1><heading>Deconfiguration due to removal during bulk
3876 If <prgn>dpkg</prgn> would like to remove a package due to a
3877 conflict, as described above, but this would violate a
3878 dependency of some other package on the system,
3879 <prgn>dpkg</prgn> will usually not remove the conflicting
3880 package and halt with an error.
3884 However, if the <tt>--auto-deconfigure</tt> (<tt>-B</tt>)
3885 option is used <prgn>dpkg</prgn> will automatically
3886 `deconfigure' the package with the problematic dependency,
3887 so that the conflicting package can be removed and the
3888 package we're trying to install can be installed. If
3889 <prgn>dpkg</prgn> is being asked to install packages (rather
3890 than just unpacking them) it will try to reconfigure the
3891 package when it has unpacked all its arguments, in the hope
3892 that one of the other packages it is installing will satisfy
3893 the problematic dependency.
3897 <prgn>dselect</prgn> supplies this argument to
3898 <prgn>dpkg</prgn> when it invokes it, so that bulk
3899 installations proceed smoothly.
3903 <sect id="conflicts"><heading>Alternative binary packages -
3904 <tt>Conflicts</tt> and <tt>Replaces</tt>
3908 When one binary package declares a conflict with another
3909 <prgn>dpkg</prgn> will refuse to allow them to be installed
3910 on the system at the same time.
3914 If one package is to be installed, the other must be removed
3915 first - if the package being installed is marked as
3916 replacing (<ref id="replaces">) the one on the system, or
3917 the one on the system is marked as deselected, or both
3918 packages are marked <tt>Essential</tt>, then
3919 <prgn>dpkg</prgn> will automatically remove the package
3920 which is causing the conflict, otherwise it will halt the
3921 installation of the new package with an error. This
3922 mechanism specifically doesn't work when the installed
3923 package is <tt>Essential</tt>, but the new package is not.
3927 <prgn>dselect</prgn> makes it hard to select conflicting
3928 packages, though the user can override this if they wish.
3929 If they do not override it then <prgn>dselect</prgn> will
3930 select one of the packages for removal, and the user must
3931 make sure it is the right one. In the future
3932 <prgn>dselect</prgn> will look for the presence of a
3933 <tt>Replaces</tt> field to help decide which package should
3934 be installed and which removed.
3938 A package will not cause a conflict merely because its
3939 configuration files are still installed; it must be at least
3944 A special exception is made for packages which declare a
3945 conflict with their own package name, or with a virtual
3946 package which they provide (see below): this does not
3947 prevent their installation, and allows a package to conflict
3948 with others providing a replacement for it. You use this
3949 feature when you want the package in question to be the only
3950 package providing something.
3954 A <tt>Conflicts</tt> entry should almost never have an
3955 `earlier than' version clause. This would prevent
3956 <prgn>dpkg</prgn> from upgrading or installing the package
3957 which declared such a conflict until the upgrade or removal
3958 of the conflicted-with package had been completed. This
3959 aspect of installation ordering is not handled by
3960 <prgn>dselect</prgn>, so that the use <tt>Conflicts</tt> in
3961 this way is likely to cause problems for `bulk run' upgrades
3966 <sect id="virtual"><heading>Virtual packages - <tt>Provides</tt>
3970 As well as the names of actual (`concrete') packages, the
3971 package relationship fields <tt>Depends</tt>,
3972 <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
3973 <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Conflicts</tt>,
3974 <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt> may
3975 mention virtual packages.
3979 A virtual package is one which appears in the
3980 <tt>Provides</tt> control file field of another package.
3981 The effect is as if the package(s) which provide a
3982 particular virtual package name had been listed by name
3983 everywhere the virtual package name appears.
3987 If there are both a real and a virtual package of the same
3988 name then the dependency may be satisfied (or the conflict
3989 caused) by either the real package or any of the virtual
3990 packages which provide it. This is so that, for example,
3996 and someone else releases an xemacs package they can say
4000 </example> and all will work in the interim (until a purely
4001 virtual package name is decided on and the <tt>emacs</tt>
4002 and <tt>vm</tt> packages are changed to use it).
4006 If a dependency or a conflict has a version number attached
4007 then only real packages will be considered to see whether
4008 the relationship is satisfied (or the prohibition violated,
4009 for a conflict) - it is assumed that a real package which
4010 provides virtual package is not of the `right' version. So,
4011 a <tt>Provides</tt> field may not contain version numbers,
4012 and the version number of the concrete package which
4013 provides a particular virtual package will not be looked at
4014 when considering a dependency on or conflict with the
4015 virtual package name.
4019 It is likely that the ability will be added in a future
4020 release of <prgn>dpkg</prgn> to specify a version number for
4021 each virtual package it provides. This feature is not yet
4022 present, however, and is expected to be used only
4027 If you want to specify which of a set of real packages should be the
4028 default to satisfy a particular dependency on a virtual package, you
4029 should list the real package as an alternative before the virtual.
4034 <sect id="replaces"><heading><tt>Replaces</tt> - overwriting
4035 files and replacing packages
4039 The <tt>Replaces</tt> control file field has two purposes,
4040 which come into play in different situations.
4044 Virtual packages (<ref id="virtual">) are not considered
4045 when looking at a <tt>Replaces</tt> field - the packages
4046 declared as being replaced must be mentioned by their real
4050 <sect1><heading>Overwriting files in other packages
4054 Firstly, as mentioned before, it is usually an error for a
4055 package to contains files which are on the system in
4056 another package, though currently the
4057 <tt>--force-overwrite</tt> flag is enabled by default,
4058 downgrading the error to a warning,
4062 If the overwriting package declares that it replaces the
4063 one containing the file being overwritten then
4064 <prgn>dpkg</prgn> will proceed, and replace the file from
4065 the old package with that from the new. The file will no
4066 longer be listed as `owned' by the old package.
4070 If a package is completely replaced in this way, so that
4071 <prgn>dpkg</prgn> does not know of any files it still
4072 contains, it is considered to have disappeared. It will
4073 be marked as not wanted on the system (selected for
4074 removal) and not installed. Any conffiles details noted
4075 in the package will be ignored, as they will have been
4076 taken over by the replacing package(s). The package's
4077 <prgn>postrm</prgn> script will be run to allow the
4078 package to do any final cleanup required. See <ref
4079 id="mscriptsinstact">.
4083 In the future <prgn>dpkg</prgn> will discard files which
4084 overwrite those from another package which declares that
4085 it replaces the one being installed (so that you can
4086 install an older version of a package without problems).
4090 This usage of <tt>Replaces</tt> only takes effect when
4091 both packages are at least partially on the system at
4092 once, so that it can only happen if they do not conflict
4093 or if the conflict has been overridden.</p>
4096 <sect1><heading>Replacing whole packages, forcing their
4101 Secondly, <tt>Replaces</tt> allows <prgn>dpkg</prgn> and
4102 <prgn>dselect</prgn> to resolve which package should be
4103 removed when there is a conflict - see <ref id="conflicts">. This
4104 usage only takes effect when the two packages <em>do</em>
4105 conflict, so that the two effects do not interfere with
4111 <sect><heading>Defaults for satisfying dependencies - ordering
4115 Ordering is significant in dependency fields.
4119 Usually dselect will suggest to the user that they select
4120 the package with the most `fundamental' class (eg, it will
4121 prefer Base packages to Optional ones), or the one that they
4122 `most wanted' to select in some sense.
4126 In the absence of other information <prgn>dselect</prgn>
4127 will offer a default selection of the first named package in
4128 a list of alternatives.
4132 However, there is no way to specify the `order' of several
4133 packages which all provide the same thing, when that thing
4134 is listed as a dependency.
4138 Therefore a dependency on a virtual package should contain a
4139 concrete package name as the first alternative, so that this
4144 For example, consider the set of packages:
4147 Recommends: info-browser
4150 Provides: info-browser
4153 Provides: info-browser
4158 If <prgn>emacs</prgn> and <prgn>info</prgn> both have the
4159 same priority then <prgn>dselect</prgn>'s choice is
4160 essentially random. Better would be
4163 Recommends: info | info-browser
4165 so that <prgn>dselect</prgn> defaults to selecting the
4166 lightweight standalone info browser.
4171 <sect><heading>Relationships between source and binary packages -
4172 <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
4173 <tt>Build-Conflicts</tt>, <tt>Build-Conflicts-Indep</tt>
4177 A source package may declare a dependency or a conflict on a
4178 binary package. This is done with the control file fields
4179 <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
4180 <tt>Build-Conflicts</tt>, and <tt>Build-Conflicts-Indep</tt>. Their
4181 semantics is that the dependencies and conflicts they define
4182 must be satisfied (as defined earlier for binary packages),
4183 when one of the targets in <tt>debian/rules</tt> that the
4184 particular field applies to is invoked.
4187 <tag><tt>Build-Depends</tt>, <tt>Build-Conflicts</tt></tag>
4190 The <tt>Build-Depends</tt> and
4191 <tt>Build-Conflicts</tt> fields apply to the targets
4192 <tt>build</tt>, <tt>binary</tt>, <tt>binary-arch</tt>
4193 and <tt>binary-indep</tt>.
4196 <tag><tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts-Indep</tt></tag>
4199 The <tt>Build-Depends-Indep</tt> and
4200 <tt>Build-Conflicts-Indep</tt> fields apply to the
4201 targets <tt>binary</tt> and <tt>binary-indep</tt>.
4212 <chapt id="conffiles"><heading>Configuration file handling
4216 <prgn>dpkg</prgn> can do a certain amount of automatic
4217 handling of package configuration files.
4221 Whether this mechanism is appropriate depends on a number of
4222 factors, but basically there are two approaches to any
4223 particular configuration file.
4227 The easy method is to ship a best-effort configuration in the
4228 package, and use <prgn>dpkg</prgn>'s conffile mechanism to
4229 handle updates. If the user is unlikely to want to edit the
4230 file, but you need them to be able to without losing their
4231 changes, and a new package with a changed version of the file
4232 is only released infrequently, this is a good approach.
4236 The hard method is to build the configuration file from
4237 scratch in the <prgn>postinst</prgn> script, and to take the
4238 responsibility for fixing any mistakes made in earlier
4239 versions of the package automatically. This will be
4240 appropriate if the file is likely to need to be different on
4244 <sect><heading>Automatic handling of configuration files by
4249 A package may contain a control area file called
4250 <tt>conffiles</tt>. This file should be a list of filenames
4251 of configuration files needing automatic handling, separated
4252 by newlines. The filenames should be absolute pathnames,
4253 and the files referred to should actually exist in the
4258 When a package is upgraded <prgn>dpkg</prgn> will process
4259 the configuration files during the configuration stage,
4260 shortly before it runs the package's <prgn>postinst</prgn>
4265 For each file it checks to see whether the version of the
4266 file included in the package is the same as the one that was
4267 included in the last version of the package (the one that is
4268 being upgraded from); it also compares the version currently
4269 installed on the system with the one shipped with the last
4274 If neither the user nor the package maintainer has changed
4275 the file, it is left alone. If one or the other has changed
4276 their version, then the changed version is preferred - i.e.,
4277 if the user edits their file, but the package maintainer
4278 doesn't ship a different version, the user's changes will
4279 stay, silently, but if the maintainer ships a new version
4280 and the user hasn't edited it the new version will be
4281 installed (with an informative message). If both have
4282 changed their version the user is prompted about the problem
4283 and must resolve the differences themselves.
4287 The comparisons are done by calculating the MD5 message
4288 digests of the files, and storing the MD5 of the file as it
4289 was included in the most recent version of the package.
4293 When a package is installed for the first time
4294 <prgn>dpkg</prgn> will install the file that comes with it,
4295 unless that would mean overwriting a file already on the
4300 However, note that <prgn>dpkg</prgn> will <em>not</em>
4301 replace a conffile that was removed by the user (or by a
4302 script). This is necessary because with some programs a
4303 missing file produces an effect hard or impossible to
4304 achieve in another way, so that a missing file needs to be
4305 kept that way if the user did it.
4309 Note that a package should <em>not</em> modify a
4310 <prgn>dpkg</prgn>-handled conffile in its maintainer
4311 scripts. Doing this will lead to <prgn>dpkg</prgn> giving
4312 the user confusing and possibly dangerous options for
4313 conffile update when the package is upgraded.</p>
4316 <sect><heading>Fully-featured maintainer script configuration
4321 For files which contain site-specific information such as
4322 the hostname and networking details and so forth, it is
4323 better to create the file in the package's
4324 <prgn>postinst</prgn> script.
4328 This will typically involve examining the state of the rest
4329 of the system to determine values and other information, and
4330 may involve prompting the user for some information which
4331 can't be obtained some other way.
4335 When using this method there are a couple of important
4336 issues which should be considered:
4340 If you discover a bug in the program which generates the
4341 configuration file, or if the format of the file changes
4342 from one version to the next, you will have to arrange for
4343 the postinst script to do something sensible - usually this
4344 will mean editing the installed configuration file to remove
4345 the problem or change the syntax. You will have to do this
4346 very carefully, since the user may have changed the file,
4347 perhaps to fix the very problem that your script is trying
4348 to deal with - you will have to detect these situations and
4349 deal with them correctly.
4353 If you do go down this route it's probably a good idea to
4354 make the program that generates the configuration file(s) a
4355 separate program in <tt>/usr/sbin</tt>, by convention called
4356 <tt><var>package</var>config</tt> and then run that if
4357 appropriate from the post-installation script. The
4358 <tt><var>package</var>config</tt> program should not
4359 unquestioningly overwrite an existing configuration - if its
4360 mode of operation is geared towards setting up a package for
4361 the first time (rather than any arbitrary reconfiguration
4362 later) you should have it check whether the configuration
4363 already exists, and require a <tt>--force</tt> flag to
4364 overwrite it.</p></sect>
4369 <chapt id="alternatives"><heading>Alternative versions of an interface -
4370 <prgn>update-alternatives</prgn>
4374 When several packages all provide different versions of the
4375 same program or file it is useful to have the system select a
4376 default, but to allow the system administrator to change it
4377 and have their decisions respected.
4381 For example, there are several versions of the <prgn>vi</prgn>
4382 editor, and there is no reason to prevent all of them from
4383 being installed at once, each under their own name
4384 (<prgn>nvi</prgn>, <prgn>vim</prgn> or whatever).
4385 Nevertheless it is desirable to have the name <tt>vi</tt>
4386 refer to something, at least by default.
4390 If all the packages involved cooperate, this can be done with
4391 <prgn>update-alternatives</prgn>.
4395 Each package provides its own version under its own name, and
4396 calls <prgn>update-alternatives</prgn> in its postinst to
4397 register its version (and again in its prerm to deregister
4402 See the manpage <manref name="update-alternatives"
4403 section="8"> for details.
4407 If <prgn>update-alternatives</prgn> does not seem appropriate
4408 you may wish to consider using diversions instead.</p>
4412 <chapt id="diversions"><heading>Diversions - overriding a
4413 package's version of a file
4417 It is possible to have <prgn>dpkg</prgn> not overwrite a file
4418 when it reinstalls the package it belongs to, and to have it
4419 put the file from the package somewhere else instead.
4423 This can be used locally to override a package's version of a
4424 file, or by one package to override another's version (or
4425 provide a wrapper for it).
4429 Before deciding to use a diversion, read <ref
4430 id="alternatives"> to see if you really want a diversion
4431 rather than several alternative versions of a program.
4435 There is a diversion list, which is read by <prgn>dpkg</prgn>,
4436 and updated by a special program <prgn>dpkg-divert</prgn>.
4437 Please see <manref name="dpkg-divert" section="8"> for full
4438 details of its operation.
4442 When a package wishes to divert a file from another, it should
4443 call <prgn>dpkg-divert</prgn> in its preinst to add the
4444 diversion and rename the existing file. For example,
4445 supposing that a <prgn>smailwrapper</prgn> package wishes to
4446 install a wrapper around <tt>/usr/sbin/smail</tt>:
4448 if [ install = "$1" -o upgrade = "$1" ]; then
4449 dpkg-divert --package smailwrapper --add --rename \
4450 --divert /usr/sbin/smail.real /usr/sbin/smail
4452 </example> Testing <tt>$1</tt> is necessary so that the script
4453 doesn't try to add the diversion again when
4454 <prgn>smailwrapper</prgn> is upgraded. The <tt>--package
4455 smailwrapper</tt> ensures that <prgn>smailwrapper</prgn>'s
4456 copy of <tt>/usr/sbin/smail</tt> can bypass the diversion and
4457 get installed as the true version.
4461 The postrm has to do the reverse:
4463 if [ remove = "$1" ]; then
4464 dpkg-divert --package smailwrapper --remove --rename \
4465 --divert /usr/sbin/smail.real /usr/sbin/smail
4471 Do not attempt to divert a file which is vitally important for
4472 the system's operation - when using <prgn>dpkg-divert</prgn>
4473 there is a time, after it has been diverted but before
4474 <prgn>dpkg</prgn> has installed the new version, when the file
4479 <chapt id="sharedlibs"><heading>Shared libraries
4483 Packages containing shared libraries must be constructed with
4484 a little care to make sure that the shared library is always
4485 available. This is especially important for packages whose
4486 shared libraries are vitally important, such as the libc.
4490 Firstly, your package should install the shared libraries
4491 under their normal names. For example, the
4492 <prgn>libgdbm1</prgn> package should install
4493 <tt>libgdbm.so.1.7.3</tt> as
4494 <tt>/usr/lib/libgdbm.so.1.7.3</tt>. The files should not be
4495 renamed or relinked by any prerm or postrm scripts;
4496 <prgn>dpkg</prgn> will take care of renaming things safely
4497 without affecting running programs, and attempts to interfere
4498 with this are likely to lead to problems.
4502 Secondly, your package should include the symlink that
4503 <prgn>ldconfig</prgn> would create for the shared libraries.
4504 For example, the <prgn>libgdbm1</prgn> package should include
4505 a symlink from <tt>/usr/lib/libgdbm.so.1</tt> to
4506 <tt>libgdbm.so.1.7.3</tt>. This is needed so that
4507 <prgn>ld.so</prgn> can find the library in between the time
4508 <prgn>dpkg</prgn> installs it and <prgn>ldconfig</prgn> is run
4509 in the <prgn>postinst</prgn> script. Futhermore, older
4510 versions of the package management system required the library
4511 must be placed before the symlink pointing to it in the
4512 <tt>.deb</tt> file. This is so that by the time
4513 <prgn>dpkg</prgn> comes to install the symlink (overwriting
4514 the previous symlink pointing at an older version of the
4515 library) the new shared library is already in place.
4516 Unfortunately, this was not not always possible, since it
4517 highly depends on the behaviour of the filesystem. Some
4518 filesystems (such as reisefs) will reorder the files so it
4519 doesn't matter in what order you create them. In newer
4520 versions of <prgn>dpkg</prgn>, this is handled automatically.
4524 next Paragraph added to close Bug #5299, Guy Maor
4528 Thirdly, the development package should contain a symlink for
4529 the shared library without a version number. For example, the
4530 <tt>libgdbm1-dev</tt> package should include a symlink from
4531 <tt>/usr/lib/libgdm.so</tt> to <tt>libgdm.so.1.7.3</tt>. This
4532 symlink is needed by <prgn>ld</prgn> when compiling packages
4533 as it will only look for <tt>libgdm.so</tt> and
4534 <tt>libgdm.a</tt> when compiling dynamically or statically,
4539 next paragraph changed by Christian Schwarz (see policy weekly #6)
4543 Any package installing shared libraries in a directory that's listed
4544 in <tt>/etc/ld.so.conf</tt> or in one of the default library
4545 directories of <prgn>ld.so</prgn> (currently, these are <tt>/usr/lib</tt>
4546 and <tt>/lib</tt>) must call <prgn>ldconfig</prgn> in its <prgn>postinst</prgn>
4547 script if and only if the first argument is `configure'. However, it
4548 is important not to call <prgn>ldconfig</prgn> in the postrm or preinst
4549 scripts in the case where the package is being upgraded (see <ref
4550 id="unpackphase">), as <prgn>ldconfig</prgn> will see the temporary names
4551 that <prgn>dpkg</prgn> uses for the files while it is
4552 installing them and will make the shared library links point
4553 to them, just before <prgn>dpkg</prgn> continues the
4554 installation and removes the links!
4558 moved from section 2.2 , DMorris
4561 <sect id="shlibs"><heading>The <tt>shlibs</tt> File Format
4565 This file is for use by <prgn>dpkg-shlibdeps</prgn> and is
4566 required when your package provides shared libraries.
4570 Each line is of the form:
4572 <var>library-name</var> <var>version-or-soname</var> <var>dependencies ...</var>
4577 <var>library-name</var> is the name of the shared library,
4578 for example <tt>libc5</tt>.
4582 <var>version-or-soname</var> is the soname of the library -
4583 ie, the thing that must exactly match for the library to be
4584 recognised by <prgn>ld.so</prgn>. Usually this is major
4585 version number of the library.
4589 <var>dependencies</var> has the same syntax as a dependency
4590 field in a binary package control file. It should give
4591 details of which package(s) are required to satisfy a binary
4592 built against the version of the library contained in the
4593 package. See <ref id="depsyntax">.
4597 For example, if the package <tt>foo</tt> contains
4598 <tt>libfoo.so.1.2.3</tt>, where the soname of the library is
4599 <tt>libfoo.so.1</tt>, and the first version of the package
4600 which contained a minor number of at least <tt>2.3</tt> was
4601 <var>1.2.3-1</var>, then the package's <var>shlibs</var>
4604 libfoo 1 foo (>= 1.2.3-1)
4609 The version-specific dependency is to avoid warnings from
4610 <prgn>ld.so</prgn> about using older shared libraries with
4614 <sect><heading>Further Technical information on
4615 <tt>shlibs</tt></heading>
4619 following section mostly provided by Heiko Schlittermann
4623 <sect1><heading><em>What</em> are the <tt>shlibs</tt> files?
4627 The <tt>debian/shlibs</tt> file provides a way of checking
4628 for shared library dependencies on packaged binaries.
4629 They are intended to be used by package maintainers to
4630 make their lives easier.
4634 Other <tt>shlibs</tt> files that exist on a Debian system are
4636 <item> <p><tt>/etc/dpkg/shlibs.default</tt></p></item>
4637 <item> <p><tt>/etc/dpkg/shlibs.override</tt></p></item>
4638 <item> <p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
4639 <item> <p><tt>debian/shlibs.local</tt></p></item>
4641 These files are used by <prgn>dpkg-shlibdeps</prgn> when
4642 creating a binary package.</p>
4645 <sect1><heading><em>How</em> does <prgn>dpkg-shlibdeps</prgn>
4650 <prgn>dpkg-shlibdeps</prgn> calls <prgn>ldd</prgn> to
4651 determine the shared libraries used by the compiled
4652 binaries passed through its command line.
4656 For each shared library, <prgn>dpkg-shlibdeps</prgn> needs to know
4657 <list compact="compact">
4658 <item><p>the package containing the library, and</p></item>
4659 <item><p>the library version number,</p></item>
4662 it scans the following files in this order.
4663 <enumlist compact="compact">
4664 <item><p><tt>debian/shlibs.local</tt></p></item>
4665 <item><p><tt>/etc/dpkg/shlibs.override</tt></p></item>
4666 <item><p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
4667 <item><p><tt>/etc/dpkg/shlibs.default</tt></p></item>
4671 <sect1><heading><em>Who</em> maintains the various
4672 <tt>shlibs</tt> files?
4676 <list compact="compact">
4678 <p><tt>/etc/dpkg/shlibs.default</tt> - the maintainer
4683 <tt>/var/lib/dpkg/info/<var>package</var>.shlibs</tt>
4684 - the maintainer of each package</p>
4688 <tt>/etc/dpkg/shlibs.override</tt> - the local
4689 system administrator</p>
4692 <p><tt>debian/shlibs.local</tt> - the maintainer of
4697 The <tt>shlibs.default</tt> file is managed by
4698 <prgn>dpkg</prgn>. The entries in <tt>shlibs.default</tt>
4699 that are provided by <prgn>dpkg</prgn> are just there to
4700 fix things until the shared library packages all have
4701 <tt>shlibs</tt> files.
4705 <sect1><heading><em>How</em> to use <prgn>dpkg-shlibdeps</prgn> and
4706 the <tt>shlibs</tt> files?
4709 <sect2><heading>If your package doesn't provide a shared
4714 Put a call to <prgn>dpkg-shlibdeps</prgn> into your
4715 <tt>debian/rules</tt> file. If your package contains
4716 only binaries (e.g. no scripts) use:
4718 dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/*
4720 If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
4721 done. If it does complain you might need to create your
4722 own <tt>debian/shlibs.local</tt> file.</p>
4725 <sect2><heading>If your package provides a shared library
4729 Create a <tt>debian/shlibs</tt> file and let
4730 <tt>debian/rules</tt> install it in the control area:
4732 install -m644 debian/shlibs debian/tmp/DEBIAN
4734 If your package contains additional binaries see above.
4739 <sect1><heading><em>How</em> to write
4740 <tt>debian/shlibs.local</tt>
4744 This file is intended only as a <em>temporary</em> fix if
4745 your binaries depend on a library which doesn't provide
4746 its own <tt>/var/lib/dpkg/info/*.shlibs</tt> file yet.
4750 Let's assume you are packaging a binary <tt>foo</tt>. Your
4751 output in building the package might look like this.
4754 libbar.so.1 => /usr/X11R6/lib/libbar.so.1.0
4755 libc.so.5 => /lib/libc.so.5.2.18
4756 libX11.so.6 => /usr/X11R6/lib/libX11.so.6.0
4758 And when you ran <prgn>dpkg-shlibdeps</prgn>
4760 $ dpkg-shlibdeps -o foo
4761 dpkg-shlibdeps: warning: unable to find dependency information
4762 for shared library libbar
4763 (soname 1, path /usr/X11R6/lib/libbar.so.1.0, dependency field Depends)
4764 shlibs:Depends=elf-x11r6lib, libc5 (>= 5.2.18)
4766 The <prgn>foo</prgn> binary depends on the
4767 <prgn>libbar</prgn> shared library, but no package seems
4768 to provide a <tt>*.shlibs</tt> file in
4769 <tt></tt>var/lib/dpkg/info/. Let's determine the package
4775 $ dpkg -S /usr/X11R6/lib/libbar.so.1.0
4776 bar1: /usr/X11R6/lib/libbar.so.1.0
4777 $ dpkg -s bar1 | grep Version
4780 This tells us that the <prgn>bar1</prgn> package, version
4781 1.0-1 is the one we are using. Now we can create our own
4782 <tt>debian/shlibs.local</tt> to temporarly fix the above
4783 problem. Include the following line into your
4784 <tt>debian/shlibs.local</tt> file.
4786 libbar 1 bar1 (>= 1.0-1)
4788 Now your package build should work. As soon as the
4789 maintainer of <prgn>libbar1</prgn> provides a
4790 <tt>shlibs</tt> file, you can remove your
4791 <tt>debian/shlibs.local</tt> file.
4797 <chapt id="methif"><heading><prgn>dselect</prgn>'s interface to
4798 its installation methods
4802 <prgn>dselect</prgn> calls scripts from its installation
4803 methods when it needs to actually access data from the
4804 distribution. The core program <prgn>dselect</prgn> itself
4805 just calls these scripts and provides the package and access
4806 method selection interfaces. The installation methods are
4807 responsible for invoking <prgn>dpkg</prgn> as appropriate.
4811 Each installation method has three scripts:
4812 <list compact="compact">
4813 <item><p>Setup installation parameters.</p></item>
4814 <item><p>Update list of available packages.</p></item>
4815 <item><p>Install.</p></item>
4819 <prgn>dselect</prgn> searches for methods in
4820 <tt>/usr/lib/dpkg/methods</tt> and
4821 <tt>/usr/local/lib/dpkg/methods</tt>.
4824 <sect><heading>Functions of the method scripts
4828 The setup script is run just after the user has chosen an
4829 installation method. It should prompt the user for
4830 parameters like the site to NFS-mount or FTP from, the
4831 directory to use, or the directory or filesystem where the
4832 <tt>.deb</tt> files can be found, or the tape or floppy
4833 device to install from. It should store the responses under
4834 <tt>/var/lib/dpkg/methods</tt> - see below. If no available
4835 packages list is available it should perhaps offer to scan
4836 the available packages.
4840 The update script should obtain a list of available packages
4841 if possible, and run <tt>dpkg --update-avail</tt>, <tt>dpkg
4842 --merge-avail</tt> and/or <tt>dpkg --forget-old-unavail</tt>
4843 to load it into <prgn>dpkg</prgn> and <prgn>dselect</prgn>'s
4844 database of available packages. If no packages list was
4845 available and the user was offered and accepted the option
4846 of scanning the actual files available this scan should be
4847 done here, using <tt>dpkg --record-avail</tt>.
4851 The install script should feed all the available
4852 <tt>.deb</tt> files to <tt>dpkg --iGOEB</tt> (this is
4853 equivalent to <tt>dpkg --install
4854 --refuse-downgrade --selected-only --skip-same-version
4855 --auto-deconfigure</tt>). The <tt>-R</tt>
4856 (<tt>--recursive</tt>) option for traversing subdirectories
4857 may also be useful here).
4861 If any of these scripts needs to display a message for the
4862 user, it should wait for the user to hit `return' before
4863 exiting so that dselect doesn't immediately rewrite the
4868 If a method script succeeds (returns a zero exit status)
4869 <prgn>dselect</prgn> will return immediately to the main
4870 menu, with the `next' option highlighted ready for the user
4871 to select it. If it fails <prgn>dselect</prgn> will display
4872 a message and wait for the user to hit return.</p>
4875 <sect><heading>Location and arguments of the method scripts
4879 A set of scripts (henceforth known as a group) may provide
4880 several methods on the `main menu' with different behaviour.
4881 For example, there might be a generic get-packages-by-FTP
4882 group which might provide methods in the main menu for
4883 installation directly from one of the Debian mirror sites as
4884 well as for installation from a user-specified site.
4888 Each group of methods implemented by the same set of scripts
4889 should have a subdirectory
4890 <tt>/usr/lib/dpkg/methods/<var>group</var></tt> or
4891 <tt>/usr/local/lib/dpkg/methods/<var>group</var></tt>,
4893 <taglist compact="compact">
4894 <tag><tt>names</tt></tag>
4895 <item><p>a list of user-visible methods provided by these scripts.</p>
4897 <tag><tt>setup</tt></tag>
4898 <tag><tt>update</tt></tag>
4899 <tag><tt>install</tt></tag>
4900 <item><p>executable programs, the scripts themselves.</p>
4902 <tag><tt>desc.<var>option</var></tt></tag>
4903 <item><p>description file.</p></item>
4908 <tt>names</tt> will be formatted as a list of lines, each containing:
4910 <var>sequence</var> <var>method</var> <var>summary</var>
4914 <var>sequence</var> is a two-digit number that will be used
4915 much like <tt>rc.d</tt> prefixes to control the order in the
4916 main menu. If in doubt use 50.
4920 <var>method</var> is a name which is displayed by
4921 <prgn>dselect</prgn> as the name of the method, and which
4922 will be passed to <tt>setup</tt>, <tt>update</tt> and
4923 <tt>unpack</tt> as their first argument.
4927 <var>summary</var> is the brief description string for
4928 <prgn>dselect</prgn>'s menu.
4932 Each of the three scripts gets the same three arguments:
4933 <var>vardir</var>, <var>group</var> and <var>method</var>.
4934 <var>vardir</var> is the base directory for storing
4935 <prgn>dpkg</prgn> and <prgn>dselect</prgn>'s state, usually
4936 <tt>/var/lib/dpkg</tt>; this is passed in so that the
4937 <tt>--admindir</tt> option to <prgn>dselect</prgn> is
4942 Each option may have an extended description in
4943 <tt>desc.<var>option</var></tt>. This should be formatted
4944 like the extended description part of a <tt>Description</tt>
4945 field entry <em>shifted one character to the left</em>.
4949 <tt><var>vardir</var>/methods</tt> will exist, and a method
4951 <tt><var>vardir</var>/methods/<var>group</var></tt>
4952 directory to store its state.
4956 The group name and method name must follow the rules for C
4962 <chapt id="conversion"><heading>Conversion procedure from old
4967 This is a brief summary of the procedure for converting a
4968 pre-2.0.0.0-format source package into the new format.
4972 You are strongly advised to download and examine the <prgn>hello</prgn>
4973 package, and to read the section in the <prgn>dpkg</prgn> programmers'
4974 manual describing the source packaging tools. More detail about the
4975 exact functionality of these tools is available in
4976 <manref name="dpkg-source" section="1">.
4983 Download the original source code from wherever it can
4984 be found and do any rearrangement required to make it
4985 look like the original tree of the Debian source. Put
4987 <tt><var>package</var>-<var>upstream-version</var>.orig/</tt>
4989 <tt><var>package</var>_<var>upstream-version</var>.orig.tar.gz</tt>.
4995 Rename all files <tt>debian.*</tt> to <tt>debian/*</tt>.
4996 There may be some exceptions to this, but this is a good
5002 Edit the <tt>debian/changelog</tt> - create or rename it
5003 if necessary. Add a new revision to the top with the
5004 appropriate details, and a local variables entry to the
5005 bottom to set Emacs to the right mode:
5008 mode: debian-changelog
5016 Edit/create <tt>debian/control</tt>:
5017 <list compact="compact">
5020 Remove the <tt>Version</tt> field. If it is
5021 generated unusually (not equal to the source
5022 version) you must use the -v option to
5023 dpkg-gencontrol (see below). <tt>Section</tt>,
5024 <tt>Priority</tt>, <tt>Maintainer</tt> go above
5025 the first blank line, most of the rest
5032 Reorder the fields and add a blank line at an
5033 appropriate point, separating the source package
5034 fields from the binary package fields.
5039 <p>Add the <tt>Source</tt> field.</p></item>
5043 Add the <tt>Standards-Version</tt> field. (Please
5044 check out the Debian Policy Manual for details
5045 about this field.)</p>
5050 Change the <tt>Architecture</tt> field for each
5051 package to <tt>any</tt>, <tt>all</tt> or whatever.
5052 If there isn't an <tt>Architecture</tt> field add
5058 If any other use of sed or things used to happen
5059 to make the binary control files use
5060 <prgn>dpkg-gencontrol</prgn>'s variable
5061 substitution features to achieve the same effect.
5062 Use <tt>debian/substvars</tt> if you need to put
5063 unusally-generated information (apart from details
5064 of <tt>.deb</tt> files) in the <tt>.changes</tt>
5072 <p>Edit the <tt>debian/rules</tt>:
5073 <list compact="compact">
5076 Remove the <prgn>source</prgn> and
5077 <prgn>diff</prgn> and any <prgn>changes</prgn> and
5078 <prgn>dist</prgn> targets. These things now
5079 happen in a package-independent way and are not
5080 done by <tt>debian/rules</tt>.</p>
5084 Split the <prgn>binary</prgn> target into
5085 <prgn>binary-arch</prgn> and
5086 <prgn>binary-indep</prgn>; in many cases all of
5087 <prgn>binary</prgn> should go into
5088 <prgn>binary-arch</prgn>. Create the
5089 <prgn>binary</prgn> target and the unused of the
5090 two other <prgn>binary-*</prgn> targets if there
5091 is one - you can copy the ones from the
5092 <prgn>hello</prgn> package.</p>
5096 Change the <prgn>binary</prgn> target to use
5097 <prgn>dpkg-gencontrol</prgn> to make the package
5098 control file(s). Move it to after all the files
5099 have been installed but just before the last
5100 <prgn>chown</prgn> and <prgn>chmod</prgn> in the
5105 Change occurrences of <tt>debian-tmp</tt> to
5106 <tt>debian/tmp</tt>.</p>
5110 Change occurrences of
5111 <tt>debian.{post,pre}{inst,rm}</tt> to
5112 <tt>debian/*</tt>.</p>
5116 Remove the version number setting at the top, if
5121 Ensure that the package's Debian-specific and
5122 upstream changelogs are installed.</p>
5130 Change the package to use <prgn>dpkg-shlibdeps</prgn> to
5131 determine its shared library dependencies and substitute
5132 them in. Shared library dependencies should no longer
5133 be hardwired in the source package.</p>
5138 Check that the <tt>debian/README</tt> is really the
5139 copyright file, and if so rename it to
5140 <tt>debian/copyright</tt> and edit <tt>debian/rules</tt>
5141 to cope with this and to change the installation of the
5143 <tt>/usr/doc/<var>package</var>/copyright</tt> to
5144 <tt>/usr/doc/copyright/<var>package</var></tt>. If it
5145 isn't then find <tt>debian/copyright</tt> and decide
5146 what to do with the <tt>README</tt>.</p>
5150 <p>Check for various other anachronisms and problems:
5151 <list compact="compact">
5154 Remove any <tt>Package_Revision</tt>,
5155 <tt>Package-Revision</tt> or <tt>Revision</tt>
5160 Rename <tt>Optional</tt> to <tt>Suggests</tt>,
5161 <tt>Recommended</tt> to
5162 <tt>Recommends</tt>.</p>
5167 <tt>/usr/doc/examples/<var>package</var></tt> to
5168 <tt>/usr/doc/<var>package</var>/examples</tt>.</p>
5172 Make sure that manpages are installed
5177 Check that the description has an extended
5178 description, is well-formatted and meaningful and
5179 helpful to people wanting to know whether to
5180 install a package.</p>
5187 <p>Look everything over.</p></item>
5191 Do a test build using <tt>dpkg-buildpackage -us -uc -sa
5192 -r<var>whatever</var></tt>. Check the permissions and
5193 locations of files in the resulting package by examining
5194 the output of <tt>dpkg-deb --contents</tt>, and check
5195 that the source build happened OK. Test install the
5196 binary package(s) and test extract the source
5202 Sign the release: either rebuild everything with
5203 <tt>dpkg-buildpackage -sa</tt>, or PGP-sign the
5204 <tt>.dsc</tt>, rebuild the <tt>.changes</tt> using
5205 <tt>dpkg-genchanges -sa</tt>, and then PGP-sign the
5206 <tt>.changes</tt>.</p>
5213 The use of <tt>-sa</tt> on <prgn>dpkg-buildpackage</prgn> and
5214 <prgn>dpkg-genchanges</prgn> is important when doing the first
5215 build/uploading of a new-format source package. Unless this
5216 happens to be Debian revision <tt>0</tt> or <tt>1</tt> by
5217 default the original source tarfile will not be included in
5218 the uploaded files listed in the <tt>.changes</tt> file, and
5219 so it won't be installed on the FTP site. <tt>-sa</tt>
5220 requests that the original source be included