1 <!doctype debiandoc system[
2 <!-- include version information so we don't have to hard code it
3 within the document -->
4 <!entity % versiondata SYSTEM "version.ent"> %versiondata;
8 Debian GNU/Linux Packaging Manual.
9 Copyright (C)1996 Ian Jackson; released under the terms of the GNU
10 General Public License, version 2 or (at your option) any later.
11 Revised: David A. Morris (bweaver@debian.org)
12 Maintainer since 1998, Christian Schwarz <schwarz@debian.org>
18 <titlepag><title>Debian Packaging Manual</title>
20 <name>Ian Jackson </name>
21 <email>ijackson@gnu.ai.mit.edu</email>
24 <name>Revised: David A. Morris</name>
25 <email>bweaver@debian.org</email>
28 <name>Maintainer: Christian Schwarz </name>
29 <email>schwarz@debian.org</email>
32 <name>Maintainer: Manoj Srivastava </name>
33 <email>srivasta@debian.org</email>
36 <name>Maintainer: The Debian Policy group </name>
37 <email>debian-policy@lists.debian.org</email>
39 <version>version &version;, &date;</version>
42 This manual describes the technical aspects of creating Debian
43 binary and source packages. It also documents the interface
44 between <prgn>dselect</prgn> and its access method scripts.
45 It does not deal with the Debian Project policy requirements,
46 and it assumes familiarity with <prgn>dpkg</prgn>'s functions
47 from the system administrator's perspective. This
48 package itself is maintained by a group of maintainers
49 that have no editorial powers. At the moment, the list of
53 <p>Michael Alan Dorman <email>mdorman@debian.org</email></p>
56 <p>Richard Braakman <email>dark@xs4all.nl</email></p>
59 <p>Philip Hands <email>phil@hands.com</email></p>
62 <p>Manoj Srivastava <email>srivasta@debian.org</email></p>
69 <copyrightsummary>Copyright ©1996 Ian Jackson.</copyrightsummary>
71 This manual is free software; you may redistribute it and/or
72 modify it under the terms of the GNU General Public License
73 as published by the Free Software Foundation; either version
74 2, or (at your option) any later version.
78 This is distributed in the hope that it will be useful, but
79 <em>without any warranty</em>; without even the implied
80 warranty of merchantability or fitness for a particular
81 purpose. See the GNU General Public License for more
86 A copy of the GNU General Public License is available as
87 <tt>/usr/doc/copyright/GPL</tt> in the Debian GNU/Linux
88 distribution or on the World Wide Web at
89 <tt>http://www.gnu.org/copyleft/gpl.html</tt>. You can also
90 obtain it by writing to the Free Software Foundation, Inc.,
91 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
97 <!-- Describes the technical interface between a package and dpkg.
99 How to safely put shared libraries in a package. Details of
100 dpkg's handling of individual files. Sections on when to use
101 which feature (eg Replaces vs. Replaces/Conflicts
102 vs. update-alternatives vs. diversions) Cross-references to the
103 policy document (see below) where appropriate. Description of the
104 interface between dselect and its access methods. Hints on where
105 to start with a new package (ie, the hello package). What to do
110 Manpages are required for: update-rc.d, diversions,
111 update-alternatives, install-info in a package.
116 <heading>Introduction and scope of this manual</heading>
119 <prgn>dpkg</prgn> is a suite of programs for creating binary
120 package files and installing and removing them on Unix
123 <prgn>dpkg</prgn> is targetted primarily at Debian
124 GNU/Linux, but may work on or be ported to other
131 The binary packages are designed for the management of
132 installed executable programs (usually compiled binaries) and
133 their associated data, though source code examples and
134 documentation are provided as part of some packages.</p>
137 This manual describes the technical aspects of creating Debian
138 binary packages (<tt>.deb</tt> files). It documents the
139 behaviour of the package management programs
140 <prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and the way
141 they interact with packages.</p>
144 It also documents the interaction between
145 <prgn>dselect</prgn>'s core and the access method scripts it
146 uses to actually install the selected packages, and describes
147 how to create a new access method.</p>
150 This manual does not go into detail about the options and
151 usage of the package building and installation tools. It
152 should therefore be read in conjuction with those programs'
157 The utility programs which are provided with <prgn>dpkg</prgn>
158 for managing various system configuration and similar issues,
159 such as <prgn>update-rc.d</prgn> and
160 <prgn>install-info</prgn>, are not described in detail here -
161 please see their manpages.
165 It does <em>not</em> describe the policy requirements imposed
166 on Debian packages, such as the permissions on files and
167 directories, documentation requirements, upload procedure, and
168 so on. You should see the Debian packaging policy manual for
169 these details. (Many of them will probably turn out to be
170 helpful even if you don't plan to upload your package and make
171 it available as part of the distribution.)
175 It is assumed that the reader is reasonably familiar with the
176 <prgn>dpkg</prgn> System Administrators' manual.
177 Unfortunately this manual does not yet exist.
181 The Debian version of the FSF's GNU hello program is provided
182 as an example for people wishing to create Debian
183 packages. The Debian <prgn>debmake</prgn> package is
184 recommended as a very helpful tool in creating and maintaining
185 Debian packages. However, while the tools and examples are
186 helpful, they do not replace the need to read and follow the
187 Policy and Programmer's Manual.</p>
190 <chapt id="binarypkg"><heading>Binary packages
194 The binary package has two main sections. The first part
195 consists of various control information files and scripts used
196 by <prgn>dpkg</prgn> when installing and removing. See <ref
201 The second part is an archive containing the files and
202 directories to be installed.
206 In the future binary packages may also contain other
207 components, such as checksums and digital signatures. The
208 format for the archive is described in full in the
209 <tt>deb(5)</tt> manpage.
213 <sect id="bincreating"><heading>Creating package files -
214 <prgn>dpkg-deb</prgn>
218 All manipulation of binary package files is done by
219 <prgn>dpkg-deb</prgn>; it's the only program that has
220 knowledge of the format. (<prgn>dpkg-deb</prgn> may be
221 invoked by calling <prgn>dpkg</prgn>, as <prgn>dpkg</prgn>
222 will spot that the options requested are appropriate to
223 <prgn>dpkg-deb</prgn> and invoke that instead with the same
228 In order to create a binary package you must make a
229 directory tree which contains all the files and directories
230 you want to have in the filesystem data part of the package.
231 In Debian-format source packages this directory is usually
232 <tt>debian/tmp</tt>, relative to the top of the package's
237 They should have the locations (relative to the root of the
238 directory tree you're constructing) ownerships and
239 permissions which you want them to have on the system when
244 With current versions of <prgn>dpkg</prgn> the uid/username
245 and gid/groupname mappings for the users and groups being
246 used should be the same on the system where the package is
247 built and the one where it is installed.
251 You need to add one special directory to the root of the
252 miniature filesystem tree you're creating:
253 <prgn>DEBIAN</prgn>. It should contain the control
254 information files, notably the binary package control file
255 (see <ref id="controlfile">).
259 The <prgn>DEBIAN</prgn> directory will not appear in the
260 filesystem archive of the package, and so won't be installed
261 by <prgn>dpkg</prgn> when the package is installed.
265 When you've prepared the package, you should invoke:
267 dpkg --build <var>directory</var>
272 This will build the package in
273 <tt><var>directory</var>.deb</tt>. (<prgn>dpkg</prgn> knows
274 that <tt>--build</tt> is a <prgn>dpkg-deb</prgn> option, so
275 it invokes <prgn>dpkg-deb</prgn> with the same arguments to
280 See the manpage <manref name="dpkg-deb" section="8"> for details of how
281 to examine the contents of this newly-created file. You may find the
282 output of following commands enlightening:
284 dpkg-deb --info <var>filename</var>.deb
285 dpkg-deb --contents <var>filename</var>.deb
286 dpkg --contents <var>filename</var>.deb
288 To view the copyright file for a package you could use this command:
290 dpkg --fsys-tarfile <var>filename</var>.deb | tar xof usr/doc/<var>\*</var>copyright | less
295 <sect id="controlarea">
297 Package control information files
301 The control information portion of a binary package is a
302 collection of files with names known to <prgn>dpkg</prgn>.
303 It will treat the contents of these files specially - some
304 of them contain information used by <prgn>dpkg</prgn> when
305 installing or removing the package; others are scripts which
306 the package maintainer wants <prgn>dpkg</prgn> to run.
310 It is possible to put other files in the package control
311 area, but this is not generally a good idea (though they
312 will largely be ignored).
316 Here is a brief list of the control info files supported by
317 <prgn>dpkg</prgn> and a summary of what they're used for.
322 <tag><tt>control</tt>
326 This is the key description file used by
327 <prgn>dpkg</prgn>. It specifies the package's name
328 and version, gives its description for the user,
329 states its relationships with other packages, and so
330 forth. See <ref id="controlfile">.
334 It is usually generated automatically from information
335 in the source package by the
336 <prgn>dpkg-gencontrol</prgn> program, and with
337 assistance from <prgn>dpkg-shlibdeps</prgn>. See <ref
338 id="sourcetools">.</p>
341 <tag><tt>postinst</tt>, <tt>preinst</tt>, <tt>postrm</tt>,
347 These are exectuable files (usually scripts) which
348 <prgn>dpkg</prgn> runs during installation, upgrade
349 and removal of packages. They allow the package to
350 deal with matters which are particular to that package
351 or require more complicated processing than that
352 provided by <prgn>dpkg</prgn>. Details of when and
353 how they are called are in <ref
354 id="maintainerscripts">.
358 It is very important to make these scripts
362 That means that if it runs successfully or fails
363 and then you call it again it doesn't bomb out,
364 but just ensures that everything is the way it
367 </footnote> This is so that if an error occurs, the
368 user interrupts <prgn>dpkg</prgn> or some other
369 unforeseen circumstance happens you don't leave the
370 user with a badly-broken package.
374 The maintainer scripts are guaranteed to run with a
375 controlling terminal and can interact with the user.
376 If they need to prompt for passwords, do full-screen
377 interaction or something similar you should do these
378 things to and from <tt>/dev/tty</tt>, since
379 <prgn>dpkg</prgn> will at some point redirect scripts'
380 standard input and output so that it can log the
381 installation process. Likewise, because these scripts
382 may be executed with standard output redirected into a
383 pipe for logging purposes, Perl scripts should set
384 unbuffered output by setting <tt>$|=1</tt> so that the
385 output is printed immediately rather than being
390 Each script should return a zero exit status for
391 success, or a nonzero one for failure.</p>
394 <tag><tt>conffiles</tt>
399 This file contains a list of configuration files which
400 are to be handled automatically by <prgn>dpkg</prgn>
401 (see <ref id="conffiles">). Note that not necessarily
402 every configuration file should be listed here.</p>
410 This file contains a list of the shared libraries
411 supplied by the package, with dependency details for
412 each. This is used by <prgn>dpkg-shlibdeps</prgn>
413 when it determines what dependencies are required in a
414 package control file. The <tt>shlibs</tt> file format
415 is described on <ref id="shlibs">.
421 <sect id="controlfile">
423 The main control information file: <tt>control</tt>
426 The most important control information file used by
427 <prgn>dpkg</prgn> when it installs a package is
428 <tt>control</tt>. It contains all the package's `vital
433 The binary package control files of packages built from
434 Debian sources are made by a special tool,
435 <prgn>dpkg-gencontrol</prgn>, which reads
436 <tt>debian/control</tt> and <tt>debian/changelog</tt> to
437 find the information it needs. See <ref id="sourcepkg"> for
442 The fields in binary package control files are:
443 <list compact="compact">
445 <p><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</p>
448 <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
450 <item><p><qref id="f-Architecture"><tt>Architecture</tt></qref>
454 This field should appear in all packages, though
455 <prgn>dpkg</prgn> doesn't require it yet so that
456 old packages can still be installed.
462 <p><qref id="relationships"><tt>Depends</tt>,
463 <tt>Provides</tt> et al.</qref></p>
466 <p><qref id="f-Essential"><tt>Essential</tt></qref></p>
469 <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
472 <p><qref id="f-classification"><tt>Section</tt>,
473 <tt>Priority</tt></qref></p>
476 <p><qref id="f-Source"><tt>Source</tt></qref></p>
479 <p><qref id="descriptions"><tt>Description</tt></qref></p>
483 <qref id="f-Installed-Size"><tt>Installed-Size</tt></qref>
489 A description of the syntax of control files and the purpose
490 of these fields is available in <ref id="controlfields">.
494 <heading>Time Stamps</heading>
496 Maintainers are encouraged to preserve the modification
497 times of the upstream source files in a package, as far as
498 is reasonably possible.
501 The rationale is that there is some information conveyed
502 by knowing the age of the file, for example, you could
503 recognize that some documentation is very old by looking
504 at the modification time, so it would be nice if the
505 modification time of the upstream source would be
512 <chapt id="sourcepkg">
513 <heading>Source packages</heading>
516 The Debian binary packages in the distribution are generated
517 from Debian sources, which are in a special format to assist
518 the easy and automatic building of binaries.
522 There was a previous version of the Debian source format,
523 which is now being phased out. Instructions for converting an
524 old-style package are given in the Debian policy manual.
527 <sect id="sourcetools">
528 <heading>Tools for processing source packages</heading>
531 Various tools are provided for manipulating source packages;
532 they pack and unpack sources and help build of binary
533 packages and help manage the distribution of new versions.
537 They are introduced and typical uses described here; see
538 <manref name="dpkg-source" section="1"> for full
539 documentation about their arguments and operation.
543 For examples of how to construct a Debian source package,
544 and how to use those utilities that are used by Debian
545 source packages, please see the <prgn>hello</prgn> example
551 <prgn>dpkg-source</prgn> - packs and unpacks Debian source
556 This program is frequently used by hand, and is also
557 called from package-independent automated building scripts
558 such as <prgn>dpkg-buildpackage</prgn>.
562 To unpack a package it is typically invoked with
564 dpkg-source -x <var>.../path/to/filename</var>.dsc
569 with the <tt><var>filename</var>.tar.gz</tt> and
570 <tt><var>filename</var>.diff.gz</tt> (if applicable) in
571 the same directory. It unpacks into
572 <tt><var>package</var>-<var>version</var></tt>, and if
574 <tt><var>package</var>-<var>version</var>.orig</tt>, in
575 the current directory.
579 To create a packed source archive it is typically invoked:
581 dpkg-source -b <var>package</var>-<var>version</var>
586 This will create the <tt>.dsc</tt>, <tt>.tar.gz</tt> and
587 <tt>.diff.gz</tt> (if appropriate) in the current
588 directory. <prgn>dpkg-source</prgn> does not clean the
589 source tree first - this must be done separately if it is
594 See also <ref id="sourcearchives">.</p>
600 <prgn>dpkg-buildpackage</prgn> - overall package-building
605 <prgn>dpkg-buildpackage</prgn> is a script which invokes
606 <prgn>dpkg-source</prgn>, the <tt>debian/rules</tt>
607 targets <prgn>clean</prgn>, <prgn>build</prgn> and
608 <prgn>binary</prgn>, <prgn>dpkg-genchanges</prgn> and
609 <prgn>pgp</prgn> to build a signed source and binary
614 It is usually invoked by hand from the top level of the
615 built or unbuilt source directory. It may be invoked with
616 no arguments; useful arguments include:
617 <taglist compact="compact">
618 <tag><tt>-uc</tt>, <tt>-us</tt></tag>
621 Do not PGP-sign the <tt>.changes</tt> file or the
622 source package <tt>.dsc</tt> file, respectively.</p>
624 <tag><tt>-p<var>pgp-command</var></tt></tag>
627 Invoke <var>pgp-command</var> instead of finding
628 <tt>pgp</tt> on the <prgn>PATH</prgn>.
629 <var>pgp-command</var> must behave just like
630 <prgn>pgp</prgn>.</p>
632 <tag><tt>-r<var>root-command</var></tt></tag>
635 When root privilege is required, invoke the command
636 <var>root-command</var>. <var>root-command</var>
637 should invoke its first argument as a command, from
638 the <prgn>PATH</prgn> if necessary, and pass its
639 second and subsequent arguments to the command it
640 calls. If no <var>root-command</var> is supplied
641 then <var>dpkg-buildpackage</var> will take no
642 special action to gain root privilege, so that for
643 most packages it will have to be invoked as root to
646 <tag><tt>-b</tt>, <tt>-B</tt></tag>
649 Two types of binary-only build and upload - see
650 <manref name="dpkg-source" section="1">.
659 <prgn>dpkg-gencontrol</prgn> - generates binary package
664 This program is usually called from <tt>debian/rules</tt>
665 (see <ref id="sourcetree">) in the top level of the source
670 This is usually done just before the files and directories in the
671 temporary directory tree where the package is being built have their
672 permissions and ownerships set and the package is constructed using
673 <prgn>dpkg-deb/</prgn>
676 This is so that the control file which is produced has
677 the right permissions
683 <prgn>dpkg-gencontrol</prgn> must be called after all the
684 files which are to go into the package have been placed in
685 the temporary build directory, so that its calculation of
686 the installed size of a package is correct.
690 It is also necessary for <prgn>dpkg-gencontrol</prgn> to
691 be run after <prgn>dpkg-shlibdeps</prgn> so that the
692 variable substitutions created by
693 <prgn>dpkg-shlibdeps</prgn> in <tt>debian/substvars</tt>
698 For a package which generates only one binary package, and
699 which builds it in <tt>debian/tmp</tt> relative to the top
700 of the source package, it is usually sufficient to call
701 <prgn>dpkg-gencontrol</prgn>.
705 Sources which build several binaries will typically need
708 dpkg-gencontrol -Pdebian/tmp-<var>pkg</var> -p<var>package</var>
709 </example> The <tt>-P</tt> tells
710 <prgn>dpkg-gencontrol</prgn> that the package is being
711 built in a non-default directory, and the <tt>-p</tt>
712 tells it which package's control file should be generated.
716 <prgn>dpkg-gencontrol</prgn> also adds information to the
717 list of files in <tt>debian/files</tt>, for the benefit of
718 (for example) a future invocation of
719 <prgn>dpkg-genchanges</prgn>.</p>
724 <prgn>dpkg-shlibdeps</prgn> - calculates shared library
729 This program is usually called from <tt>debian/rules</tt>
730 just before <prgn>dpkg-gencontrol</prgn> (see <ref
731 id="sourcetree">), in the top level of the source tree.
735 Its arguments are executables
738 They may be specified either in the locations in the
739 source tree where they are created or in the locations
740 in the temporary build tree where they are installed
741 prior to binary package creation.
743 </footnote> for which shared library dependencies should
744 be included in the binary package's control file.
748 If some of the executable(s) shared libraries should only
749 warrant a <tt>Recommends</tt> or <tt>Suggests</tt>, or if
750 some warrant a <tt>Pre-Depends</tt>, this can be achieved
751 by using the <tt>-d<var>dependency-field</var></tt> option
752 before those executable(s). (Each <tt>-d</tt> option
753 takes effect until the next <tt>-d</tt>.)
757 <prgn>dpkg-shlibdeps</prgn> does not directly cause the
758 output control file to be modified. Instead by default it
759 adds to the <tt>debian/substvars</tt> file variable
760 settings like <tt>shlibs:Depends</tt>. These variable
761 settings must be referenced in dependency fields in the
762 appropriate per-binary-package sections of the source
767 For example, the <prgn>procps</prgn> package generates two
768 kinds of binaries, simple C binaries like <prgn>ps</prgn>
769 which require a predependency and full-screen ncurses
770 binaries like <prgn>top</prgn> which require only a
771 recommendation. It can say in its <tt>debian/rules</tt>:
773 dpkg-shlibdeps -dPre-Depends ps -dRecommends top
775 and then in its main control file <tt>debian/control</tt>:
779 Pre-Depends: ${shlibs:Pre-Depends}
780 Recommends: ${shlibs:Recommends}
786 Sources which produce several binary packages with
787 different shared library dependency requirements can use
788 the <tt>-p<var>varnameprefix</var></tt> option to override
789 the default <tt>shlib:</tt> prefix (one invocation of
790 <prgn>dpkg-shlibdeps</prgn> per setting of this option).
791 They can thus produce several sets of dependency
792 variables, each of the form
793 <tt><var>varnameprefix</var>:<var>dependencyfield</var></tt>,
794 which can be referred to in the appropriate parts of the
795 binary package control files.
802 <prgn>dpkg-distaddfile</prgn> - adds a file to
803 <tt>debian/files</tt>
807 Some packages' uploads need to include files other than
808 the source and binary package files.
812 <prgn>dpkg-distaddfile</prgn> adds a file to the
813 <tt>debian/files</tt> file so that it will be included in
814 the <tt>.changes</tt> file when
815 <prgn>dpkg-genchanges</prgn> is run.
819 It is usually invoked from the <prgn>binary</prgn> target of
820 <tt>debian/rules</tt>:
822 dpkg-distaddfile <var>filename</var> <var>section</var> <var>priority</var>
824 The <var>filename</var> is relative to the directory where
825 <prgn>dpkg-genchanges</prgn> will expect to find it - this
826 is usually the directory above the top level of the source
827 tree. The <tt>debian/rules</tt> target should put the
828 file there just before or just after calling
829 <prgn>dpkg-distaddfile</prgn>.
833 The <var>section</var> and <var>priority</var> are passed
834 unchanged into the resulting <tt>.changes</tt> file. See
835 <ref id="f-classification">.
840 <sect1><heading><prgn>dpkg-genchanges</prgn> - generates a <tt>.changes</tt> upload
845 This program is usually called by package-independent
846 automatic building scripts such as
847 <prgn>dpkg-buildpackage</prgn>, but it may also be called
852 It is usually called in the top level of a built source
853 tree, and when invoked with no arguments will print out a
854 straightforward <tt>.changes</tt> file based on the
855 information in the source package's changelog and control
856 file and the binary and source packages which should have
862 <sect1><heading><prgn>dpkg-parsechangelog</prgn> - produces parsed representation of
867 This program is used internally by
868 <prgn>dpkg-source</prgn> et al. It may also occasionally
869 be useful in <tt>debian/rules</tt> and elsewhere. It
870 parses a changelog, <tt>debian/changelog</tt> by default,
871 and prints a control-file format representation of the
872 information in it to standard output.
876 <sect1 id="dpkgarch"><heading><prgn>dpkg-architecture</prgn> -
877 information about the build and host system
881 This program can be used manually, but is also invoked by
882 <tt>dpkg-buildpackage</tt> or <tt>debian/rules</tt> to set
883 to set environment or make variables which specify the build and
884 host architecture for the package building process.
889 <sect id="sourcetree"><heading>The Debianised source tree
893 The source archive scheme described later is intended to
894 allow a Debianised source tree with some associated control
895 information to be reproduced and transported easily. The
896 Debianised source tree is a version of the original program
897 with certain files added for the benefit of the
898 Debianisation process, and with any other changes required
899 made to the rest of the source code and installation
904 The extra files created for Debian are in the subdirectory
905 <tt>debian</tt> of the top level of the Debianised source
906 tree. They are described below.
909 <sect1 id="debianrules"><heading><tt>debian/rules</tt> - the main building
914 This file is an executable makefile, and contains the
915 package-specific recipies for compiling the package and
916 building binary package(s) out of the source.
920 It must start with the line <tt>#!/usr/bin/make -f</tt>,
921 so that it can be invoked by saying its name rather than
922 invoking <prgn>make</prgn> explicitly.
926 Since an interactive <tt>debian/rules</tt> script makes it
927 impossible to autocompile that package and also makes it
928 hard for other people to reproduce the same binary
929 package, all <strong>required targets</strong> have to be
930 non-interactive. At a minimul, required targets are the
931 ones called by <prgn>dpkg-buildpackage</prgn>, namely,
932 <em>clean</em>, <em>binary</em>, <em>binary-arch</em>, and
933 <em>build</em>. It also follows that any target that these
934 targets depend on must also be non-interactive.
938 The targets which are required to be present are:
940 <tag><tt>build</tt></tag>
943 This should perform all non-interactive
944 configuration and compilation of the package. If a
945 package has an interactive pre-build configuration
946 routine, the Debianised source package should be
947 built after this has taken place, so that it can be
948 built without rerunning the configuration.
952 For some packages, notably ones where the same
953 source tree is compiled in different ways to produce
954 two binary packages, the <prgn>build</prgn> target
955 does not make much sense. For these packages it is
956 good enough to provide two (or more) targets
957 (<tt>build-a</tt> and <tt>build-b</tt> or whatever)
958 for each of the ways of building the package, and a
959 <prgn>build</prgn> target that does nothing. The
960 <prgn>binary</prgn> target will have to build the
961 package in each of the possible ways and make the
962 binary package out of each.
966 The <prgn>build</prgn> target must not do anything
967 that might require root privilege.
971 The <prgn>build</prgn> target may need to run
972 <prgn>clean</prgn> first - see below.
976 When a package has a configuration routine that
977 takes a long time, or when the makefiles are poorly
978 designed, or when <prgn>build</prgn> needs to run
979 <prgn>clean</prgn> first, it is a good idea to
980 <tt>touch build</tt> when the build process is
981 complete. This will ensure that if <tt>debian/rules
982 build</tt> is run again it will not rebuild the
987 <tag><tt>binary</tt>, <tt>binary-arch</tt>,
988 <tt>binary-indep</tt>
992 The <prgn>binary</prgn> target should be all that is
993 necessary for the user to build the binary
994 package. All these targets are required to be
995 non-interactive. It is split into two parts:
996 <prgn>binary-arch</prgn> builds the packages' output
997 files which are specific to a particular
998 architecture, and <prgn>binary-indep</prgn> builds
1003 <prgn>binary</prgn> should usually be a target with
1004 no commands which simply depends on
1005 <prgn>binary-arch</prgn> and
1006 <prgn>binary-indep</prgn>.
1010 Both <prgn>binary-*</prgn> targets should depend on
1011 the <prgn>build</prgn> target, above, so that the
1012 package is built if it has not been already. It
1013 should then create the relevant binary package(s),
1014 using <prgn>dpkg-gencontrol</prgn> to make their
1015 control files and <prgn>dpkg-deb</prgn> to build
1016 them and place them in the parent of the top level
1021 If one of the <prgn>binary-*</prgn> targets has
1022 nothing to do (this will be always be the case if
1023 the source generates only a single binary package,
1024 whether architecture-dependent or not) it
1025 <em>must</em> still exist, but should always
1030 <ref id="binarypkg"> describes how to construct
1035 The <prgn>binary</prgn> targets must be invoked as
1040 <tag><tt>clean</tt></tag>
1044 This should undo any effects that the
1045 <prgn>build</prgn> and <prgn>binary</prgn> targets
1046 may have had, except that it should leave alone any
1047 output files created in the parent directory by a
1048 run of <prgn>binary</prgn>. This target is required
1049 to be non-interactive.
1053 If a <prgn>build</prgn> file is touched at the end
1054 of the <prgn>build</prgn> target, as suggested
1055 above, it must be removed as the first thing that
1056 <prgn>clean</prgn> does, so that running
1057 <prgn>build</prgn> again after an interrupted
1058 <prgn>clean</prgn> doesn't think that everything is
1063 The <prgn>clean</prgn> target must be invoked as
1064 root if <prgn>binary</prgn> has been invoked since
1065 the last <prgn>clean</prgn>, or if
1066 <prgn>build</prgn> has been invoked as root (since
1067 <prgn>build</prgn> may create directories, for
1072 <tag><tt>get-orig-source</tt> (optional)</tag>
1076 This target fetches the most recent version of the
1077 original source package from a canonical archive
1078 site (via FTP or WWW, for example), does any
1079 necessary rearrangement to turn it into the original
1080 source tarfile format described below, and leaves it
1081 in the current directory.
1085 This target may be invoked in any directory, and
1086 should take care to clean up any temporary files it
1091 This target is optional, but providing it if
1092 possible is a good idea.
1098 The <prgn>build</prgn>, <prgn>binary</prgn> and
1099 <prgn>clean</prgn> targets must be invoked with a current
1100 directory of the package's top-level directory.
1105 Additional targets may exist in <tt>debian/rules</tt>,
1106 either as published or undocumented interfaces or for the
1107 package's internal use.
1111 The architecture we build on and build for is determined by make
1112 variables via dpkg-architecture (see <ref id="dpkgarch">). You can
1113 get the Debian architecture and the GNU style architecture
1114 specification string for the build machine as well as the host
1115 machine. Here is a list of supported make variables:
1118 <list compact="compact">
1120 <p><tt>DEB_*_ARCH</tt> (the Debian architecture)</p>
1123 <p><tt>DEB_*_GNU_TYPE</tt> (the GNU style architecture
1124 specification string)</p>
1127 <p><tt>DEB_*_GNU_CPU</tt> (the CPU part of DEB_*_GNU_TYPE)</p>
1130 <p><tt>DEB_*_GNU_SYSTEM</tt> (the System part of
1135 where <tt>*</tt> is either <tt>BUILD</tt> for specification of
1136 the build machine or <tt>HOST</tt> for specification of the machine
1141 Backward compatibility can be provided in the rules file
1142 by setting the needed variables to suitable default
1143 values, please refer to the documentation of
1144 dpkg-architecture for details.
1148 It is important to understand that the <tt>DEB_*_ARCH</tt>
1149 string does only determine which Debian architecture we
1150 build on resp. for. It should not be used to get the CPU
1151 or System information, the GNU style variables should be
1157 <sect1><heading><tt>debian/control</tt>
1161 This file contains version-independent details about the
1162 source package and about the binary packages it creates.
1166 It is a series of sets of control fields, each
1167 syntactically similar to a binary package control file.
1168 The sets are separated by one or more blank lines. The
1169 first set is information about the source package in
1170 general; each subsequent set describes one binary package
1171 that the source tree builds.
1175 The syntax and semantics of the fields are described below
1176 in <ref id="controlfields">.
1180 The general (binary-package-independent) fields are:
1181 <list compact="compact">
1183 <p><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</p>
1186 <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
1190 <qref id="f-classification"><tt>Section</tt> and
1191 <tt>Priority</tt></qref>
1192 (classification, mandatory)
1197 <qref id="f-Standards-Version"><tt>Standards-Version</tt></qref>
1203 The per-binary-package fields are:
1204 <list compact="compact">
1206 <p><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</p>
1210 <qref id="f-Architecture"><tt>Architecture</tt></qref>
1214 <p><qref id="descriptions"><tt>Description</tt></qref></p>
1218 <qref id="f-classification"><tt>Section</tt> and
1219 <tt>Priority</tt></qref> (classification)</p>
1222 <p><qref id="f-Essential"><tt>Essential</tt></qref></p>
1226 <qref id="relationships"><tt>Depends</tt> et
1227 al.</qref> (package interrelationships)
1233 These fields are used by <prgn>dpkg-gencontrol</prgn> to
1234 generate control files for binary packages (see below), by
1235 <prgn>dpkg-genchanges</prgn> to generate the
1236 <tt>.changes</tt> file to accompany the upload, and by
1237 <prgn>dpkg-source</prgn> when it creates the <tt>.dsc</tt>
1238 source control file as part of a source archive.
1242 The fields here may contain variable references - their
1243 values will be substituted by
1244 <prgn>dpkg-gencontrol</prgn>, <prgn>dpkg-genchanges</prgn>
1245 or <prgn>dpkg-source</prgn> when they generate output
1246 control files. See <ref id="srcsubstvars"> for details.
1249 <p> <sect2><heading>User-defined fields
1253 Additional user-defined fields may be added to the
1254 source package control file. Such fields will be
1255 ignored, and not copied to (for example) binary or
1256 source package control files or upload control files.
1260 If you wish to add additional unsupported fields to
1261 these output files you should use the mechanism
1266 Fields in the main source control information file with
1267 names starting <tt>X</tt>, followed by one or more of
1268 the letters <tt>BCS</tt> and a hyphen <tt>-</tt>, will
1269 be copied to the output files. Only the part of the
1270 field name after the hyphen will be used in the output
1271 file. Where the letter <tt>B</tt> is used the field
1272 will appear in binary package control files, where the
1273 letter <tt>S</tt> is used in source package control
1274 files and where <tt>C</tt> is used in upload control
1275 (<tt>.changes</tt>) files.
1279 For example, if the main source information control file
1282 XBS-Comment: I stand between the candle and the star.
1284 then the binary and source package control files will contain the
1287 Comment: I stand between the candle and the star.
1294 <sect1 id="dpkgchangelog"><heading><tt>debian/changelog</tt>
1298 This file records the changes to the Debian-specific parts of the
1302 Though there is nothing stopping an author who is also
1303 the Debian maintainer from using it for all their
1304 changes, it will have to be renamed if the Debian and
1305 upstream maintainers become different
1312 It has a special format which allows the package building
1313 tools to discover which version of the package is being
1314 built and find out other release-specific information.
1318 That format is a series of entries like this:
1320 <var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
1322 * <var>change details</var>
1323 <var>more change details</var>
1324 * <var>even more change details</var>
1326 -- <var>maintainer name and email address</var> <var>date</var>
1331 <var>package</var> and <var>version</var> are the source
1332 package name and version number.
1336 <var>distribution(s)</var> lists the distributions where
1337 this version should be installed when it is uploaded - it
1338 is copied to the <tt>Distribution</tt> field in the
1339 <tt>.changes</tt> file. See <ref id="f-Distribution">.
1343 <var>urgency</var> is the value for the <tt>Urgency</tt>
1344 field in the <tt>.changes</tt> file for the upload. See
1345 <ref id="f-Urgency">. It is not possible to specify an
1346 urgency containing commas; commas are used to separate
1347 <tt><var>keyword</var>=<var>value</var></tt> settings in
1348 the <prgn>dpkg</prgn> changelog format (though there is
1349 currently only one useful <var>keyword</var>,
1354 The change details may in fact be any series of lines
1355 starting with at least two spaces, but conventionally each
1356 change starts with an asterisk and a separating space and
1357 continuation lines are indented so as to bring them in
1358 line with the start of the text above. Blank lines may be
1359 used here to separate groups of changes, if desired.
1363 The maintainer name and email address should <em>not</em>
1364 necessarily be those of the usual package maintainer.
1365 They should be the details of the person doing
1366 <em>this</em> version. The information here will be
1367 copied to the <tt>.changes</tt> file, and then later used
1368 to send an acknowledgement when the upload has been
1373 The <var>date</var> should be in RFC822 format
1376 This is generated by the <prgn>822-date</prgn>
1379 </footnote>; it should include the timezone specified
1380 numerically, with the timezone name or abbreviation
1381 optionally present as a comment.
1385 The first `title' line with the package name should start
1386 at the left hand margin; the `trailer' line with the
1387 maintainer and date details should be preceded by exactly
1388 one space. The maintainer details and the date must be
1389 separated by exactly two spaces.
1393 An Emacs mode for editing this format is available: it is
1394 called <tt>debian-changelog-mode</tt>. You can have this
1395 mode selected automatically when you edit a Debian
1396 changelog by adding a local variables clause to the end of
1400 <sect2><heading>Defining alternative changelog formats
1404 It is possible to use a different format to the standard
1405 one, by providing a parser for the format you wish to
1410 In order to have <tt>dpkg-parsechangelog</tt> run your
1411 parser, you must include a line within the last 40 lines
1412 of your file matching the Perl regular expression:
1413 <tt>\schangelog-format:\s+([0-9a-z]+)\W</tt> The part in
1414 parentheses should be the name of the format. For
1415 example, you might say:
1417 @@@ changelog-format: joebloggs @@@
1419 Changelog format names are non-empty strings of alphanumerics.
1423 If such a line exists then <tt>dpkg-parsechangelog</tt>
1424 will look for the parser as
1425 <tt>/usr/lib/dpkg/parsechangelog/<var>format-name</var></tt>
1427 <tt>/usr/local/lib/dpkg/parsechangelog/<var>format-name</var></tt>;
1428 it is an error for it not to find it, or for it not to
1429 be an executable program. The default changelog format
1430 is <tt>dpkg</tt>, and a parser for it is provided with
1431 the <tt>dpkg</tt> package.
1435 The parser will be invoked with the changelog open on
1436 standard input at the start of the file. It should read
1437 the file (it may seek if it wishes) to determine the
1438 information required and return the parsed information
1439 to standard output in the form of a series of control
1440 fields in the standard format. By default it should
1441 return information about only the most recent version in
1442 the changelog; it should accept a
1443 <tt>-v<var>version</var></tt> option to return changes
1444 information from all versions present <em>strictly
1445 after</em> <var>version</var>, and it should then be an
1446 error for <var>version</var> not to be present in the
1452 <list compact="compact">
1454 <p><qref id="f-Source"><tt>Source</tt></qref></p>
1457 <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
1461 <qref id="f-Distribution"><tt>Distribution</tt></qref>
1466 <p><qref id="f-Urgency"><tt>Urgency</tt></qref> (mandatory)</p>
1470 <qref id="f-Maintainer"><tt>Maintainer</tt></qref>
1475 <p><qref id="f-Date"><tt>Date</tt></qref></p>
1479 <qref id="f-Changes"><tt>Changes</tt></qref>
1486 If several versions are being returned (due to the use
1487 of <tt>-v</tt>), the urgency value should be of the
1488 highest urgency code listed at the start of any of the
1489 versions requested followed by the concatenated
1490 (space-separated) comments from all the versions
1491 requested; the maintainer, version, distribution and
1492 date should always be from the most recent version.
1496 For the format of the <tt>Changes</tt> field see <ref
1501 If the changelog format which is being parsed always or
1502 almost always leaves a blank line between individual
1503 change notes these blank lines should be stripped out,
1504 so as to make the resulting output compact.
1508 If the changelog format does not contain date or package
1509 name information this information should be omitted from
1510 the output. The parser should not attempt to synthesise
1511 it or find it from other sources.
1515 If the changelog does not have the expected format the
1516 parser should exit with a nonzero exit status, rather
1517 than trying to muddle through and possibly generating
1522 A changelog parser may not interact with the user at
1526 <sect1 id="srcsubstvars"><heading><tt>debian/substvars</tt>
1527 and variable substitutions
1531 When <prgn>dpkg-gencontrol</prgn>,
1532 <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
1533 generate control files they do variable substitutions on
1534 their output just before writing it. Variable
1535 substitutions have the form
1536 <tt>${<var>variable-name</var>}</tt>. The optional file
1537 <tt>debian/substvars</tt> contains variable substitutions
1538 to be used; variables can also be set directly from
1539 <tt>debian/rules</tt> using the <tt>-V</tt> option to the
1540 source packaging commands, and certain predefined
1541 variables are available.
1545 The is usually generated and modified dynamically by
1546 <tt>debian/rules</tt> targets; in this case it must be
1547 removed by the <prgn>clean</prgn> target.
1551 See <manref name="dpkg-source" section="1"> for full
1552 details about source variable substitutions, including the
1553 format of <tt>debian/substvars</tt>.</p>
1556 <sect1><heading><tt>debian/files</tt>
1560 This file is not a permanent part of the source tree; it
1561 is used while building packages to record which files are
1562 being generated. <prgn>dpkg-genchanges</prgn> uses it
1563 when it generates a <tt>.changes</tt> file.
1567 It should not exist in a shipped source package, and so it
1568 (and any backup files or temporary files such as
1572 <tt>files.new</tt> is used as a temporary file by
1573 <prgn>dpkg-gencontrol</prgn> and
1574 <prgn>dpkg-distaddfile</prgn> - they write a new
1575 version of <tt>files</tt> here before renaming it,
1576 to avoid leaving a corrupted copy if an error
1579 </footnote>) should be removed by the
1580 <prgn>clean</prgn> target. It may also be wise to
1581 ensure a fresh start by emptying or removing it at the
1582 start of the <prgn>binary</prgn> target.
1586 <prgn>dpkg-gencontrol</prgn> adds an entry to this file
1587 for the <tt>.deb</tt> file that will be created by
1588 <prgn>dpkg-deb</prgn> from the control file that it
1589 generates, so for most packages all that needs to be done
1590 with this file is to delete it in <prgn>clean</prgn>.
1594 If a package upload includes files besides the source
1595 package and any binary packages whose control files were
1596 made with <prgn>dpkg-gencontrol</prgn> then they should be
1597 placed in the parent of the package's top-level directory
1598 and <prgn>dpkg-distaddfile</prgn> should be called to add
1599 the file to the list in <tt>debian/files</tt>.</p>
1602 <sect1><heading><tt>debian/tmp</tt>
1606 This is the canonical temporary location for the
1607 construction of binary packages by the <prgn>binary</prgn>
1608 target. The directory <tt>tmp</tt> serves as the root of
1609 the filesystem tree as it is being constructed (for
1610 example, by using the package's upstream makefiles install
1611 targets and redirecting the output there), and it also
1612 contains the <tt>DEBIAN</tt> subdirectory. See <ref
1617 If several binary packages are generated from the same
1618 source tree it is usual to use several
1619 <tt>debian/tmp<var>something</var></tt> directories, for
1620 example <tt>tmp-a</tt> or <tt>tmp-doc</tt>.
1624 Whatever <tt>tmp</tt> directories are created and used by
1625 <prgn>binary</prgn> must of course be removed by the
1626 <prgn>clean</prgn> target.</p></sect1>
1630 <sect id="sourcearchives"><heading>Source packages as archives
1634 As it exists on the FTP site, a Debian source package
1635 consists of three related files. You must have the right
1636 versions of all three to be able to use them.
1641 <tag>Debian source control file - <tt>.dsc</tt></tag>
1645 This file contains a series of fields, identified and
1646 separated just like the fields in the control file of
1647 a binary package. The fields are listed below; their
1648 syntax is described above, in <ref id="controlfields">.
1649 <list compact="compact">
1651 <p><qref id="f-Source"><tt>Source</tt></qref></p>
1654 <p><qref id="versions"><tt>Version</tt></qref></p>
1657 <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
1660 <p><qref id="f-Binary"><tt>Binary</tt></qref></p>
1663 <p><qref id="f-Architecture"><tt>Architecture</tt></qref></p>
1667 <qref id="f-Standards-Version"><tt>Standards-Version</tt></qref></p>
1670 <p><qref id="f-Files"><tt>Files</tt></qref></p>
1675 The source package control file is generated by
1676 <prgn>dpkg-source</prgn> when it builds the source
1677 archive, from other files in the source package,
1678 described above. When unpacking it is checked against
1679 the files and directories in the other parts of the
1680 source package, as described below.</p>
1684 Original source archive -
1686 <var>package</var>_<var>upstream-version</var>.orig.tar.gz
1693 This is a compressed (with <tt>gzip -9</tt>)
1694 <prgn>tar</prgn> file containing the source code from
1695 the upstream authors of the program. The tarfile
1696 unpacks into a directory
1697 <tt><var>package</var>-<var>upstream-version</var>.orig</tt>,
1698 and does not contain files anywhere other than in
1699 there or in its subdirectories.</p>
1703 Debianisation diff -
1705 <var>package</var>_<var>upstream_version-revision</var>.diff.gz
1711 This is a unified context diff (<tt>diff -u</tt>)
1712 giving the changes which are required to turn the
1713 original source into the Debian source. These changes
1714 may only include editing and creating plain files.
1715 The permissions of files, the targets of symbolic
1716 links and the characteristics of special files or
1717 pipes may not be changed and no files may be removed
1722 All the directories in the diff must exist, except the
1723 <tt>debian</tt> subdirectory of the top of the source
1724 tree, which will be created by
1725 <prgn>dpkg-source</prgn> if necessary when unpacking.
1729 The <prgn>dpkg-source</prgn> program will
1730 automatically make the <tt>debian/rules</tt> file
1731 executable (see below).</p></item>
1736 If there is no original source code - for example, if the
1737 package is specially prepared for Debian or the Debian
1738 maintainer is the same as the upstream maintainer - the
1739 format is slightly different: then there is no diff, and the
1741 <tt><var>package</var>_<var>version</var>.tar.gz</tt> and
1742 contains a directory
1743 <tt><var>package</var>-<var>version</var></tt>.
1747 <sect><heading>Unpacking a Debian source package without
1748 <prgn>dpkg-source</prgn>
1752 <tt>dpkg-source -x</tt> is the recommended way to unpack a
1753 Debian source package. However, if it is not available it
1754 is possible to unpack a Debian source archive as follows:
1755 <enumlist compact="compact">
1758 Untar the tarfile, which will create a <tt>.orig</tt>
1762 <p>Rename the <tt>.orig</tt> directory to
1763 <tt><var>package</var>-<var>version</var></tt>.</p>
1767 Create the subdirectory <tt>debian</tt> at the top of
1768 the source tree.</p>
1770 <item><p>Apply the diff using <tt>patch -p0</tt>.</p>
1772 <item><p>Untar the tarfile again if you want a copy of the original
1773 source code alongside the Debianised version.</p>
1778 It is not possible to generate a valid Debian source archive
1779 without using <prgn>dpkg-source</prgn>. In particular,
1780 attempting to use <prgn>diff</prgn> directly to generate the
1781 <tt>.diff.gz</tt> file will not work.
1784 <sect1><heading>Restrictions on objects in source packages
1788 The source package may not contain any hard links
1791 This is not currently detected when building source
1792 packages, but only when extracting
1798 Hard links may be permitted at some point in the
1799 future, but would require a fair amount of
1802 </footnote>, device special files, sockets or setuid or
1806 Setgid directories are allowed.
1812 The source packaging tools manage the changes between the
1813 original and Debianised source using <prgn>diff</prgn> and
1814 <prgn>patch</prgn>. Turning the original source tree as
1815 included in the <tt>.orig.tar.gz</tt> into the debianised
1816 source must not involve any changes which cannot be
1817 handled by these tools. Problematic changes which cause
1818 <prgn>dpkg-source</prgn> to halt with an error when
1819 building the source package are:
1820 <list compact="compact">
1821 <item><p>Adding or removing symbolic links, sockets or pipes.</p>
1823 <item><p>Changing the targets of symbolic links.</p>
1825 <item><p>Creating directories, other than <tt>debian</tt>.</p>
1827 <item><p>Changes to the contents of binary files.</p></item>
1828 </list> Changes which cause <prgn>dpkg-source</prgn> to
1829 print a warning but continue anyway are:
1830 <list compact="compact">
1833 Removing files, directories or symlinks.
1836 Renaming a file is not treated specially - it is
1837 seen as the removal of the old file (which
1838 generates a warning, but is otherwise ignored),
1839 and the creation of the new
1846 Changed text files which are missing the usual final
1847 newline (either in the original or the modified
1852 Changes which are not represented, but which are not detected by
1853 <prgn>dpkg-source</prgn>, are:
1854 <list compact="compact">
1855 <item><p>Changing the permissions of files (other than
1856 <tt>debian/rules</tt>) and directories.</p></item>
1861 The <tt>debian</tt> directory and <tt>debian/rules</tt>
1862 are handled specially by <prgn>dpkg-source</prgn> - before
1863 applying the changes it will create the <tt>debian</tt>
1864 directory, and afterwards it will make
1865 <tt>debian/rules</tt> world-exectuable.
1871 <chapt id="controlfields"><heading>Control files and their fields
1875 Many of the tools in the <prgn>dpkg</prgn> suite manipulate
1876 data in a common format, known as control files. Binary and
1877 source packages have control data as do the <tt>.changes</tt>
1878 files which control the installation of uploaded files, and
1879 <prgn>dpkg</prgn>'s internal databases are in a similar
1883 <sect><heading>Syntax of control files
1887 A file consists of one or more paragraphs of fields. The
1888 paragraphs are separated by blank lines. Some control files
1889 only allow one paragraph; others allow several, in which
1890 case each paragraph often refers to a different package.
1894 Each paragraph is a series of fields and values; each field
1895 consists of a name, followed by a colon and the value. It
1896 ends at the end of the line. Horizontal whitespace (spaces
1897 and tabs) may occur before or after the value and is ignored
1898 there; it is conventional to put a single space after the
1903 Some fields' values may span several lines; in this case
1904 each continuation line <em>must</em> start with a space or
1905 tab. Any trailing spaces or tabs at the end of individual
1906 lines of a field value are ignored.
1910 Except where otherwise stated only a single line of data is
1911 allowed and whitespace is not significant in a field body.
1912 Whitespace may never appear inside names (of packages,
1913 architectures, files or anything else), version numbers or
1914 in between the characters of multi-character version
1919 Field names are not case-sensitive, but it is usual to
1920 capitalise the fields using mixed case as shown below.
1924 Blank lines, or lines consisting only of spaces and tabs,
1925 are not allowed within field values or between fields - that
1926 would mean a new paragraph.
1930 It is important to note that there are several fields which
1931 are optional as far as <prgn>dpkg</prgn> and the related
1932 tools are concerned, but which must appear in every Debian
1933 package, or whose omission may cause problems. When writing
1934 the control files for Debian packages you <em>must</em> read
1935 the Debian policy manual in conjuction with the details
1936 below and the list of fields for the particular file.</p>
1939 <sect><heading>List of fields
1942 <sect1 id="f-Package"><heading><tt>Package</tt>
1946 The name of the binary package. Package names consist of
1947 the alphanumerics and <tt>+</tt> <tt>-</tt> <tt>.</tt>
1948 (plus, minus and full stop).
1951 The characters <tt>@</tt> <tt>:</tt> <tt>=</tt>
1952 <tt>t</tt>t> <tt>_</tt> (at, colon, equals, percent
1953 and underscore) used to be legal and are still
1954 accepted when found in a package file, but may not be
1955 used in new packages
1961 They must be at least two characters and must start with
1962 an alphanumeric. In current versions of dpkg they are
1963 sort of case-sensitive<footnote><p>This is a
1964 bug.</p></footnote>; use lowercase package names unless
1965 the package you're building (or referring to, in other
1966 fields) is already using uppercase.</p>
1969 <sect1 id="f-Version"><heading><tt>Version</tt>
1973 This lists the source or binary package's version number -
1974 see <ref id="versions">.
1979 <sect1 id="f-Architecture"><heading><tt>Architecture</tt>
1983 This is the architecture string; it is a single word for
1984 the Debian architecture.
1988 <prgn>dpkg</prgn> will check the declared architecture of
1989 a binary package against its own compiled-in value before
1994 The special value <tt>all</tt> indicates that the package
1995 is architecture-independent.
1999 In the main <tt>debian/control</tt> file in the source
2000 package, or in the source package control file
2001 <tt>.dsc</tt>, a list of architectures (separated by
2002 spaces) is also allowed, as is the special value
2003 <tt>any</tt>. A list indicates that the source will build
2004 an architecture-dependent package, and will only work
2005 correctly on the listed architectures. <tt>any</tt>
2006 indicates that though the source package isn't dependent
2007 on any particular architecture and should compile fine on
2008 any one, the binary package(s) produced are not
2009 architecture-independent but will instead be specific to
2010 whatever the current build architecture is.
2014 In a <tt>.changes</tt> file the <tt>Architecture</tt>
2015 field lists the architecture(s) of the package(s)
2016 currently being uploaded. This will be a list; if the
2017 source for the package is being uploaded too the special
2018 entry <tt>source</tt> is also present.
2022 See <ref id="debianrules"> for information how to get the
2023 architecture for the build process.
2027 <sect1 id="f-Maintainer"><heading><tt>Maintainer</tt>
2031 The package maintainer's name and email address. The name
2032 should come first, then the email address inside angle
2033 brackets <tt><></tt> (in RFC822 format).
2037 If the maintainer's name contains a full stop then the
2038 whole field will not work directly as an email address due
2039 to a misfeature in the syntax specified in RFC822; a
2040 program using this field as an address must check for this
2041 and correct the problem if necessary (for example by
2042 putting the name in round brackets and moving it to the
2043 end, and bringing the email address forward).
2047 In a <tt>.changes</tt> file or parsed changelog data this
2048 contains the name and email address of the person
2049 responsible for the particular version in question - this
2050 may not be the package's usual maintainer.
2054 This field is usually optional in as far as the
2055 <prgn>dpkg</prgn> are concerned, but its absence when
2056 building packages usually generates a warning.</p>
2059 <sect1 id="f-Source"><heading><tt>Source</tt>
2063 This field identifies the source package name.
2067 In a main source control information or a
2068 <tt>.changes</tt> or <tt>.dsc</tt> file or parsed
2069 changelog data this may contain only the name of the
2074 In the control file of a binary package (or in a
2075 <tt>Packages</tt> file) it may be followed by a version
2076 number in parentheses.
2079 It is usual to leave a space after the package name if
2080 a version number is specified.
2082 </footnote> This version number may be omitted (and is, by
2083 <prgn>dpkg-gencontrol</prgn>) if it has the same value as
2084 the <tt>Version</tt> field of the binary package in
2085 question. The field itself may be omitted from a binary
2086 package control file when the source package has the same
2087 name and version as the binary package.
2091 <sect1><heading>Package interrelationship fields:
2092 <tt>Depends</tt>, <tt>Pre-Depends</tt>,
2093 <tt>Recommends</tt> <tt>Suggests</tt>, <tt>Conflicts</tt>,
2094 <tt>Provides</tt>, <tt>Replaces</tt>
2098 These fields describe the package's relationships with
2099 other packages. Their syntax and semantics are described
2100 in <ref id="relationships">.</p>
2103 <sect1 id="f-Description"><heading><tt>Description</tt>
2107 In a binary package <tt>Packages</tt> file or main source
2108 control file this field contains a description of the
2109 binary package, in a special format. See <ref
2110 id="descriptions"> for details.
2114 In a <tt>.changes</tt> file it contains a summary of the
2115 descriptions for the packages being uploaded. The part of
2116 the field before the first newline is empty; thereafter
2117 each line has the name of a binary package and the summary
2118 description line from that binary package. Each line is
2119 indented by one space.</p>
2122 <sect1 id="f-Essential"><heading><tt>Essential</tt>
2126 This is a boolean field which may occur only in the
2127 control file of a binary package (or in the
2128 <tt>Packages</tt> file) or in a per-package fields
2129 paragraph of a main source control data file.
2133 If set to <tt>yes</tt> then <prgn>dpkg</prgn> and
2134 <prgn>dselect</prgn> will refuse to remove the package
2135 (though it can be upgraded and/or replaced). The other
2136 possible value is <tt>no</tt>, which is the same as not
2137 having the field at all.</p>
2140 <sect1 id="f-classification"><heading><tt>Section</tt> and
2145 These two fields classify the package. The
2146 <tt>Priority</tt> represents how important that it is that
2147 the user have it installed; the <tt>Section</tt>
2148 represents an application area into which the package has
2153 When they appear in the <tt>debian/control</tt> file these
2154 fields give values for the section and priority subfields
2155 of the <tt>Files</tt> field of the <tt>.changes</tt> file,
2156 and give defaults for the section and priority of the
2161 The section and priority are represented, though not as
2162 separate fields, in the information for each file in the
2163 <qref id="f-Files"><tt>-File</tt></qref>field of a
2164 <tt>.changes</tt> file. The section value in a
2165 <tt>.changes</tt> file is used to decide where to install
2166 a package in the FTP archive.
2170 These fields are not used by by <prgn>dpkg</prgn> proper,
2171 but by <prgn>dselect</prgn> when it sorts packages and
2172 selects defaults. See the Debian policy manual for the
2173 priorities in use and the criteria for selecting the
2174 priority for a Debian package, and look at the Debian FTP
2175 archive for a list of currently in-use priorities.
2179 These fields may appear in binary package control files,
2180 in which case they provide a default value in case the
2181 <tt>Packages</tt> files are missing the information.
2182 <prgn>dpkg</prgn> and <prgn>dselect</prgn> will only use
2183 the value from a <tt>.deb</tt> file if they have no other
2184 information; a value listed in a <tt>Packages</tt> file
2185 will always take precedence. By default
2186 <prgn>dpkg-genchanges</prgn> does not include the section
2187 and priority in the control file of a binary package - use
2188 the <tt>-isp</tt>, <tt>-is</tt> or <tt>-ip</tt> options to
2189 achieve this effect.</p>
2192 <sect1 id="f-Binary"><heading><tt>Binary</tt>
2196 This field is a list of binary packages.
2200 When it appears in the <tt>.dsc</tt> file it is the list
2201 of binary packages which a source package can produce. It
2202 does not necessarily produce all of these binary packages
2203 for every architecture. The source control file doesn't
2204 contain details of which architectures are appropriate for
2205 which of the binary packages.
2209 When it appears in a <tt>.changes</tt> file it lists the
2210 names of the binary packages actually being uploaded.
2214 The syntax is a list of binary packages separated by
2218 A space after each comma is conventional.
2220 </footnote> Currently the packages must be separated using
2221 only spaces in the <tt>.changes</tt> file.</p>
2224 <sect1 id="f-Installed-Size"><heading><tt>Installed-Size</tt>
2228 This field appears in the control files of binary
2229 packages, and in the <tt>Packages</tt> files. It gives
2230 the total amount of disk space required to install the
2235 The disk space is represented in kilobytes as a simple
2239 <sect1 id="f-Files"><heading><tt>Files</tt>
2243 This field contains a list of files with information about
2244 each one. The exact information and syntax varies with
2245 the context. In all cases the the part of the field
2246 contents on the same line as the field name is empty. The
2247 remainder of the field is one line per file, each line
2248 being indented by one space and containing a number of
2249 sub-fields separated by spaces.
2253 In the <tt>.dsc</tt> (Debian source control) file each
2254 line contains the MD5 checksum, size and filename of the
2255 tarfile and (if applicable) diff file which make up the
2256 remainder of the source package.
2259 That is, the parts which are not the
2262 </footnote> The exact forms of the filenames are described
2263 in <ref id="sourcearchives">.
2267 In the <tt>.changes</tt> file this contains one line per
2268 file being uploaded. Each line contains the MD5 checksum,
2269 size, section and priority and the filename. The section
2270 and priority are the values of the corresponding fields in
2271 the main source control file - see <ref
2272 id="f-classification">. If no section or priority is
2273 specified then <tt>-</tt> should be used, though section
2274 and priority values must be specified for new packages to
2275 be installed properly.
2279 The special value <tt>byhand</tt> for the section in a
2280 <tt>.changes</tt> file indicates that the file in question
2281 is not an ordinary package file and must by installed by
2282 hand by the distribution maintainers. If the section is
2283 <tt>byhand</tt> the priority should be <tt>-</tt>.
2287 If a new Debian revision of a package is being shipped and
2288 no new original source archive is being distributed the
2289 <tt>.dsc</tt> must still contain the <tt>Files</tt> field
2290 entry for the original source archive
2291 <tt><var>package</var>-<var>upstream-version</var>.orig.tar.gz</tt>,
2292 but the <tt>.changes</tt> file should leave it out. In
2293 this case the original source archive on the distribution
2294 site must match exactly, byte-for-byte, the original
2295 source archive which was used to generate the
2296 <tt>.dsc</tt> file and diff which are being uploaded.</p>
2301 id="f-Standards-Version"><heading><tt>Standards-Version</tt>
2305 The most recent version of the standards (the
2306 <prgn>dpkg</prgn> programmers' and policy manuals and
2307 associated texts) with which the package complies. This
2308 is updated manually when editing the source package to
2309 conform to newer standards; it can sometimes be used to
2310 tell when a package needs attention.
2314 Its format is the same as that of a version number except
2315 that no epoch or Debian revision is allowed - see <ref
2320 <sect1 id="f-Distribution"><heading><tt>Distribution</tt>
2324 In a <tt>.changes</tt> file or parsed changelog output
2325 this contains the (space-separated) name(s) of the
2326 distribution(s) where this version of the package should
2327 be or was installed. Distribution names follow the rules
2328 for package names. (See <ref id="f-Package">).
2332 Current distribution values are:
2334 <tag><em>stable</em></tag>
2337 This is the current `released' version of Debian
2338 GNU/Linux. A new version is released approximately
2339 every 3 months after the <em>development</em> code has
2340 been <em>frozen</em> for a month of testing. Once the
2341 distribution is <em>stable</em> only major bug fixes
2342 are allowed. When changes are made to this
2343 distribution, the minor version number is increased
2344 (for example: 1.2 becomes 1.2.1 then 1.2.2, etc).
2348 <tag><em>unstable</em></tag>
2351 This distribution value refers to the
2352 <em>developmental</em> part of the Debian distribution
2353 tree. New packages, new upstream versions of packages
2354 and bug fixes go into the <em>unstable</em> directory
2355 tree. Download from this distribution at your own
2359 <tag><em>contrib</em></tag>
2362 The packages with this distribution value do not meet
2363 the criteria for inclusion in the main Debian
2364 distribution as defined by the Policy Manual, but meet
2365 the criteria for the <em>contrib</em>
2366 Distribution. There is currently no distinction
2367 between stable and unstable packages in the
2368 <em>contrib</em> or <em>non-free</em>
2369 distributions. Use your best judgement in downloading
2370 from this Distribution.</p>
2373 <tag><em>non-free</em></tag>
2376 Like the packages in the <em>contrib</em> seciton,
2377 the packages in <em>non-free</em> do not meet the
2378 criteria for inclusion in the main Debian distribution
2379 as defined by the Policy Manual. Again, use your best
2380 judgement in downloading from this Distribution.</p>
2382 <tag><em>experimental</em></tag>
2385 The packages with this distribution value are deemed
2386 by their maintainers to be high risk. Oftentimes they
2387 represent early beta or developmental packages from
2388 various sources that the maintainers want people to
2389 try, but are not ready to be a part of the other parts
2390 of the Debian distribution tree. Download at your own
2394 <tag><em>frozen</em></tag>
2397 From time to time, (currently, every 3 months) the
2398 <em>unstable</em> distribution enters a state of
2399 `code-freeze' in anticipation of release as a
2400 <em>stable</em> version. During this period of testing
2401 (usually 4 weeks) only fixes for existing or
2402 newly-discovered bugs will be allowed.
2405 </taglist> You should list <em>all</em> distributions that
2406 the package should be installed into. Except in unusual
2407 circumstances, installations to <em>stable</em> should also
2408 go into <em>frozen</em> (if it exists) and
2409 <em>unstable</em>. Likewise, installations into
2410 <em>frozen</em> should also go into <em>unstable</em>.</p>
2413 <sect1 id="f-Urgency"><heading><tt>Urgency</tt>
2417 This is a description of how important it is to upgrade to
2418 this version from previous ones. It consists of a single
2419 keyword usually taking one of the values <tt>LOW</tt>,
2420 <tt>MEDIUM</tt> or <tt>HIGH</tt>) followed by an optional
2421 commentary (separated by a space) which is usually in
2422 parentheses. For example:
2424 Urgency: LOW (HIGH for diversions users)
2429 This field appears in the <tt>.changes</tt> file and in
2430 parsed changelogs; its value appears as the value of the
2431 <tt>urgency</tt> attribute in a <prgn>dpkg</prgn>-style
2432 changelog (see <ref id="dpkgchangelog">).
2436 Urgency keywords are not case-sensitive.</p>
2439 <sect1 id="f-Date"><heading><tt>Date</tt>
2443 In <tt>.changes</tt> files and parsed changelogs, this
2444 gives the date the package was built or last edited.</p>
2447 <sect1 id="f-Format"><heading><tt>Format</tt>
2451 This field occurs in <tt>.changes</tt> files, and
2452 specifies a format revision for the file. The format
2453 described here is version <tt>1.5</tt>. The syntax of the
2454 format value is the same as that of a package version
2455 number except that no epoch or Debian revision is allowed
2456 - see <ref id="versions">.</p>
2459 <sect1 id="f-Changes"><heading><tt>Changes</tt>
2463 In a <tt>.changes</tt> file or parsed changelog this field
2464 contains the human-readable changes data, describing the
2465 differences between the last version and the current one.
2469 There should be nothing in this field before the first
2470 newline; all the subsequent lines must be indented by at
2471 least one space; blank lines must be represented by a line
2472 consiting only of a space and a full stop.
2476 Each version's change information should be preceded by a
2477 `title' line giving at least the version, distribution(s)
2478 and urgency, in a human-readable way.
2482 If data from several versions is being returned the entry
2483 for the most recent version should be returned first, and
2484 entries should be separated by the representation of a
2485 blank line (the `title' line may also be followed by the
2486 representation of blank line).</p>
2489 <sect1 id="f-Filename"><heading><tt>Filename</tt> and
2490 <tt>MSDOS-Filename</tt>
2494 These fields in <tt>Packages</tt> files give the
2495 filename(s) of (the parts of) a package in the
2496 distribution directories, relative to the root of the
2497 Debian hierarchy. If the package has been split into
2498 several parts the parts are all listed in order, separated
2502 <sect1 id="f-Size"><heading><tt>Size</tt> and <tt>MD5sum</tt>
2506 These fields in <tt>Packages</tt> files give the size (in
2507 bytes, expressed in decimal) and MD5 checksum of the
2508 file(s) which make(s) up a binary package in the
2509 distribution. If the package is split into several parts
2510 the values for the parts are listed in order, separated by
2514 <sect1 id="f-Status"><heading><tt>Status</tt>
2518 This field in <prgn>dpkg</prgn>'s status file records
2519 whether the user wants a package installed, removed or
2520 left alone, whether it is broken (requiring
2521 reinstallation) or not and what its current state on the
2522 system is. Each of these pieces of information is a
2526 <sect1 id="f-Config-Version"><heading><tt>Config-Version</tt>
2530 If a package is not installed or not configured, this
2531 field in <prgn>dpkg</prgn>'s status file records the last
2532 version of the package which was successfully
2536 <sect1 id="f-Conffiles"><heading><tt>Conffiles</tt>
2540 This field in <prgn>dpkg</prgn>'s status file contains
2541 information about the automatically-managed configuration
2542 files held by a package. This field should <em>not</em>
2543 appear anywhere in a package!</p>
2546 <sect1><heading>Obsolete fields
2550 These are still recognised by <prgn>dpkg</prgn> but should
2551 not appear anywhere any more.
2552 <taglist compact="compact">
2554 <tag><tt>Revision</tt></tag>
2555 <tag><tt>Package-Revision</tt></tag>
2556 <tag><tt>Package_Revision</tt></tag>
2559 The Debian revision part of the package version was
2560 at one point in a separate control file field. This
2561 field went through several names.</p>
2564 <tag><tt>Recommended</tt></tag>
2565 <item><p>Old name for <tt>Recommends</tt></p>
2568 <tag><tt>Optional</tt></tag>
2569 <item><p>Old name for <tt>Suggests</tt>.</p>
2571 <tag><tt>Class</tt></tag>
2572 <item><p>Old name for <tt>Priority</tt>.</p>
2580 <chapt id="versions"><heading>Version numbering
2584 Every package has a version number, in its <tt>Version</tt>
2589 <prgn>dpkg</prgn> imposes an ordering on version numbers, so
2590 that it can tell whether packages are being up- or downgraded
2591 and so that <prgn>dselect</prgn> can tell whether a package it
2592 finds available is newer than the one installed on the system.
2593 The version number format has the most significant parts (as
2594 far as comparison is concerned) at the beginning.
2598 The version number format is:
2599 &lsqb<var>epoch/<tt>:</tt>]<var>upstream-version</var>[<tt>-/<var>debian-revision</var>].</tt></var>
2603 The three components here are:
2605 <tag><var>epoch</var></tag>
2609 This is a single unsigned integer, which should usually
2610 be small. It may be omitted, in which case zero is
2611 assumed. If it is omitted then the
2612 <var>upstream-version</var> may not contain any colons.
2616 It is provided to allow mistakes in the version numbers
2617 of older versions of a package, and also a package's
2618 previous version numbering schemes, to be left behind.
2622 <prgn>dpkg</prgn> will not usually display the epoch
2623 unless it is essential (non-zero, or if the
2624 <var>upstream-version</var> contains a colon);
2625 <prgn>dselect</prgn> does not display epochs at all in
2626 the main part of the package selection display.</p>
2629 <tag><var>upstream-version</var></tag>
2633 This is the main part of the version. It is usually
2634 version number of the original (`upstream') package of
2635 which the <tt>.deb</tt> file has been made, if this is
2636 applicable. Usually this will be in the same format as
2637 that specified by the upstream author(s); however, it
2638 may need to be reformatted to fit into
2639 <prgn>dpkg</prgn>'s format and comparison scheme.
2643 The comparison behaviour of <prgn>dpkg</prgn> with
2644 respect to the <var>upstream-version</var> is described
2645 below. The <var>upstream-version</var> portion of the
2646 version number is mandatory.
2650 The <var>upstream-version</var> may contain only
2651 alphanumerics and the characters <tt>+</tt> <tt>.</tt>
2652 <tt>-</tt> <tt>:</tt> (full stop, plus, hyphen, colon)
2653 and should start with a digit. If there is no
2654 <var>debian-revision</var> then hyphens are not allowed;
2655 if there is no <var>epoch</var> then colons are not
2659 <tag><var>debian-revision</var></tag>
2663 This part of the version represents the version of the
2664 modifications that were made to the package to make it a
2665 Debian binary package. It is in the same format as the
2666 <var>upstream-version</var> and <prgn>dpkg</prgn>
2667 compares it in the same way.
2671 It is optional; if it isn't present then the
2672 <var>upstream-version</var> may not contain a hyphen.
2673 This format represents the case where a piece of
2674 software was written specifically to be turned into a
2675 Debian binary package, and so there is only one
2676 `debianization' of it and therefore no revision
2677 indication is required.
2681 It is conventional to restart the
2682 <var>debian-revision</var> at <tt>1</tt> each time the
2683 <var>upstream-version</var> is increased.
2687 <prgn>dpkg</prgn> will break the
2688 <var>upstream-version</var> and
2689 <var>debian-revision</var> apart at the last hyphen in
2690 the string. The absence of a <var>debian-revision</var>
2691 compares earlier than the presence of one (but note that
2692 the <var>debian-revision</var> is the least significant
2693 part of the version number).
2697 The <var>debian-revision</var> may contain only
2698 alphanumerics and the characters <tt>+</tt> and
2699 <tt>.</tt> (plus and full stop).
2703 The <var>upstream-version</var> and <var>debian-revision</var> parts are
2704 compared by <prgn>dpkg</prgn> using the same algorithm:
2708 The strings are compared from left to right.
2712 First the initial part of each string consisting entirely of
2713 non-digit characters is determined. These two parts (one of
2714 which may be empty) are compared lexically. If a difference
2715 is found it is returned. The lexical comparison is a
2716 comparison of ASCII values modified so that all the letters
2717 sort earlier than all the non-letters.
2721 Then the initial part of the remainder of each string which
2722 consists entirely of digit characters is determined. The
2723 numerical values of these two parts are compared, and any
2724 difference found is returned as the result of the comparison.
2725 For these purposes an empty string (which can only occur at
2726 the end of one or both version strings being compared) counts
2731 These two steps are repeated (chopping initial non-digit
2732 strings and initial digit strings off from the start) until a
2733 difference is found or both strings are exhausted.
2737 Note that the purpose of epochs is to allow us to leave behind
2738 mistakes in version numbering, and to cope with situations
2739 where the version numbering changes. It is <em>not</em> there
2740 to cope with version numbers containing strings of letters
2741 which <prgn>dpkg</prgn> cannot interpret (such as
2742 <tt>ALPHA</tt> or <tt>pre-</tt>), or with silly orderings (the
2743 author of this manual has heard of a package whose versions
2744 went <tt>1.1</tt>, <tt>1.2</tt>, <tt>1.3</tt>, <tt>1</tt>,
2745 <tt>2.1</tt>, <tt>2.2</tt>, <tt>2</tt> and so forth).
2749 If an upstream package has problematic version numbers they
2750 should be converted to a sane form for use in the
2751 <tt>Version</tt> field.
2755 If you need to compare version numbers in a script, you may use
2756 <tt>dpkg --compare-versions ...</tt>. Type <tt>dpkg
2757 --help</tt> --> --for details on arguments.
2761 <chapt id="maintainerscripts"><heading>Package maintainer scripts
2762 and installation procedure
2765 <sect><heading>Introduction to package maintainer scripts
2769 It is possible to supply scripts as part of a package which
2770 <prgn>dpkg</prgn> will run for you when your package is
2771 installed, upgraded or removed.
2775 These scripts should be the files <tt>preinst</tt>,
2776 <tt>postinst</tt>, <tt>prerm</tt> and <tt>postrm</tt> in the
2777 control area of the package. They must be proper exectuable
2778 files; if they are scripts (which is recommended) they must
2779 start with the usual <tt>#!</tt> convention. They should be
2780 readable and executable to anyone, and not world-writeable.
2784 <prgn>dpkg</prgn> looks at the exit status from these
2785 scripts. It is important that they exit with a non-zero
2786 status if there is an error, so that <prgn>dpkg</prgn> can
2787 stop its processing. For shell scripts this means that you
2788 <em>almost always</em> need to use <tt>set -e</tt> (this is
2789 usually true when writing shell scripts, in fact). It is
2790 also important, of course, that they don't exit with a
2791 non-zero status if everything went well.
2795 It is necessary for the error recovery procedures that the
2796 scripts be idempotent: ie, invoking the same script several
2797 times in the same situation should do no harm. If the first
2798 call failed, or aborted half way through for some reason,
2799 the second call should merely do the things that were left
2800 undone the first time, if any, and exit with a success
2805 When a package is upgraded a combination of the scripts from
2806 the old and new packages is called in amongst the other
2807 steps of the upgrade procedure. If your scripts are going
2808 to be at all complicated you need to be aware of this, and
2809 may need to check the arguments to your scripts.
2813 Broadly speaking the <prgn>preinst</prgn> is called before
2814 (a particular version of) a package is installed, and the
2815 <prgn>postinst</prgn> afterwards; the <prgn>prerm</prgn>
2816 before (a version of) a package is removed and the
2817 <prgn>postrm</prgn> afterwards.
2820 next paragraph by Guy Maor to close bug #2481
2823 <p> Programs called from maintainer scripts should not
2824 normally have a path prepended to them. Before installation
2825 is started <prgn>dpkg</prgn> checks to see if the programs
2826 <prgn>ldconfig</prgn>, <prgn>start-stop-daemon</prgn>,
2827 <prgn>install-info</prgn>, and <prgn>update-rc.d</prgn> can
2828 be found via the <tt>PATH</tt> environment variable. Those
2829 programs, and any other program that one would expect to on
2830 the <tt>PATH</tt>, should thus be invoked without an
2831 absolute pathname. Maintainer scripts should also not reset
2832 the <tt>PATH</tt>, though they might choose to modify it by
2833 pre- or appending package-specific directories. These
2834 considerations really apply to all shell scripts.</p>
2837 <sect id="mscriptsinstact"><heading>Summary of ways maintainer
2842 <list compact="compact">
2844 <p><var>new-preinst</var> <tt>install</tt></p>
2847 <p><var>new-preinst</var> <tt>install</tt>
2848 <var>old-version</var></p>
2851 <p><var>new-preinst</var> <tt>upgrade</tt>
2852 <var>old-version</var></p>
2855 <p><var>old-preinst</var> <tt>abort-upgrade</tt>
2856 <var>new-version</var>
2862 <list compact="compact">
2864 <p><var>postinst</var> <tt>configure</tt>
2865 <var>most-recently-configured-version</var></p>
2868 <p><var>old-postinst</var> <tt>abort-upgrade</tt>
2869 <var>new version</var></p>
2872 <p><var>conflictor's-postinst</var> <tt>abort-remove</tt>
2873 <tt>in-favour</tt> <var>package</var>
2874 <var>new-version</var></p>
2878 <var>deconfigured's-postinst</var>
2879 <tt>abort-deconfigure</tt> <tt>in-favour</tt>
2880 <var>failed-install-package</var> <var>version</var>
2881 <tt>removing</tt> <var>conflicting-package</var>
2888 <list compact="compact">
2890 <p><var>prerm</var> <tt>remove</tt></p>
2893 <p><var>old-prerm</var> <tt>upgrade</tt>
2894 <var>new-version</var></p>
2897 <p><var>new-prerm</var> <tt>failed-upgrade</tt>
2898 <var>old-version</var></p>
2901 <p><var>conflictor's-prerm</var> <tt>remove</tt>
2902 <tt>in-favour</tt> <var>package</var>
2903 <var>new-version</var></p>
2907 <var>deconfigured's-prerm</var> <tt>deconfigure</tt>
2908 <tt>in-favour</tt> <var>package-being-installed</var>
2909 <var>version</var> <tt>removing</tt>
2910 <var>conflicting-package</var>
2917 <list compact="compact">
2919 <p><var>postrm</var> <tt>remove</tt></p>
2922 <p><var>postrm</var> <tt>purge</tt></p>
2926 <var>old-postrm</var> <tt>upgrade</tt>
2927 <var>new-version</var></p>
2930 <p><var>new-postrm</var> <tt>failed-upgrade</tt>
2931 <var>old-version</var></p>
2934 <p><var>new-postrm</var> <tt>abort-install</tt></p>
2937 <p><var>new-postrm</var> <tt>abort-install</tt>
2938 <var>old-version</var></p>
2941 <p><var>new-postrm</var> <tt>abort-upgrade</tt>
2942 <var>old-version</var></p>
2946 <var>disappearer's-postrm</var> <tt>disappear</tt>
2947 <var>r>overwrit</var>r>
2948 <var>new-version</var></p></item>
2953 <sect id="unpackphase"><heading>Details of unpack phase of
2954 installation or upgrade
2958 The procedure on installation/upgrade/overwrite/disappear
2959 (ie, when running <tt>dpkg --unpack</tt>, or the unpack
2961 --install</tt>) is as follows. In each case if an error occurs the
2962 actions in are general run backwards - this means that the maintainer
2963 scripts are run with different arguments in reverse order. These are
2964 the `error unwind' calls listed below.
2971 <p>If a version the package is already
2974 <var>old-prerm</var> upgrade <var>new-version</var>
2979 If this gives an error (ie, a non-zero exit
2980 status), dpkg will attempt instead:
2982 <var>new-prerm</var> failed-upgrade <var>old-version</var>
2984 Error unwind, for both the above cases:
2986 <var>old-postinst</var> abort-upgrade <var>new-version</var>
2994 <p>If a `conflicting' package is being removed at the same time:
2998 If any packages depended on that conflicting
2999 package and <tt>--auto-deconfigure</tt> is
3000 specified, call, for each such package:
3002 <var>deconfigured's-prerm</var> deconfigure \
3003 in-favour <var>package-being-installed</var> <var>version</var> \
3004 removing <var>conflicting-package</var> <var>version</var>
3008 <var>deconfigured's-postinst</var> abort-deconfigure \
3009 in-favour <var>package-being-installed-but-failed</var> <var>version</var> \
3010 removing <var>conflicting-package</var> <var>version</var>
3012 The deconfigured packages are marked as
3013 requiring configuration, so that if
3014 <tt>--install</tt> is used they will be
3015 configured again if possible.</p>
3018 <p>To prepare for removal of the conflicting package, call:
3020 <var>conflictor's-prerm</var> remove in-favour <var>package</var> <var>new-version</var>
3024 <var>conflictor's-postinst</var> abort-remove \
3025 in-favour <var>package</var> <var>new-version</var>
3036 <p>If the package is being upgraded, call:
3038 <var>new-preinst</var> upgrade <var>old-version</var>
3043 Otherwise, if the package had some configuration
3044 files from a previous version installed (ie, it
3045 is in the `configuration files only' state):
3047 <var>new-preinst</var> install <var>old-version</var>
3051 <p>Otherwise (ie, the package was completely purged):
3053 <var>new-preinst</var> install
3055 Error unwind versions, respectively:
3057 <var>new-postrm</var> abort-upgrade <var>old-version</var>
3058 <var>new-postrm</var> abort-install <var>old-version</var>
3059 <var>new-postrm</var> abort-install
3069 The new package's files are unpacked, overwriting any
3070 that may be on the system already, for example any
3071 from the old version of the same package or from
3072 another package (backups of the old files are left
3073 around, and if anything goes wrong dpkg will attempt
3074 to put them back as part of the error unwind).
3078 It is an error for a package to contains files which
3079 are on the system in another package, unless
3080 <tt>Replaces</tt> is used (see <ref id="replaces">).
3081 Currently the <tt>--force-overwrite</tt> flag is
3082 enabled, downgrading it to a warning, but this may not
3087 It is a more serious error for a package to contain a
3088 plain file or other kind of nondirectory where another
3089 package has a directory (again, unless
3090 <tt>Replaces</tt> is used). This error can be
3091 overridden if desired using
3092 <tt>--force-overwrite-dir</tt>, but this is not
3097 Packages which overwrite each other's files produce
3098 behaviour which though deterministic is hard for the
3099 system administrator to understand. It can easily
3100 lead to `missing' programs if, for example, a package
3101 is installed which overwrites a file from another
3102 package, and is then removed again.
3105 Part of the problem is due to what is arguably a
3106 bug in <prgn>dpkg</prgn> .
3112 A directory will never be replaced by a symbolic links
3113 to a directory or vice versa; instead, the existing
3114 state (symlink or not) will be left alone and
3115 <prgn>dpkg</prgn> will follow the symlink if there is
3123 <p>If the package is being upgraded, call
3125 <var>old-postrm</var> upgrade <var>new-version</var>
3129 <p>If this fails, <prgn>dpkg</prgn> will attempt:
3131 <var>new-postrm</var> failed-upgrade <var>old-version</var>
3133 Error unwind, for both cases:
3135 <var>old-preinst</var> abort-upgrade <var>new-version</var>
3140 This is the point of no return - if <prgn>dpkg</prgn>
3141 gets this far, it won't back off past this point if an
3142 error occurs. This will leave the package in a fairly
3143 bad state, which will require a successful
3144 reinstallation to clear up, but it's when
3145 <prgn>dpkg</prgn> starts doing things that are
3150 Any files which were in the old version of the package
3151 but not in the new are removed.</p>
3154 <p>The new file list replaces the old.</p>
3157 <p>The new maintainer scripts replace the old.</p>
3161 <p>Any packages all of whose files have been overwritten during the
3162 installation, and which aren't required for
3163 dependencies, are considered to have been removed.
3164 For each such package,
3167 <p><prgn>dpkg</prgn> calls:
3169 <var>disappearer's-postrm</var> disappear \
3170 <var>overwriter</var> <var>overwriter-version</var>
3175 <p>The package's maintainer scripts are removed.
3180 It is noted in the status database as being in a
3181 sane state, namely not installed (any conffiles
3182 it may have are ignored, rather than being
3183 removed by <prgn>dpkg</prgn>). Note that
3184 disappearing packages do not have their prerm
3185 called, because <prgn>dpkg</prgn> doesn't know
3186 in advance that the package is going to
3195 Any files in the package we're unpacking that are also
3196 listed in the file lists of other packages are removed
3197 from those lists. (This will lobotomise the file list
3198 of the `conflicting' package if there is one.)
3203 The backup files made during installation, above, are
3210 The new package's status is now sane, and recorded as
3211 `unpacked'. Here is another point of no return - if
3212 the conflicting package's removal fails we do not
3213 unwind the rest of the installation; the conflicting
3214 package is left in a half-removed limbo.
3219 If there was a conflicting package we go and do the
3220 removal actions (described below), starting with the
3221 removal of the conflicting package's files (any that
3222 are also in the package being installed have already
3223 been removed from the conflicting package's file list,
3224 and so do not get removed now).
3231 <sect><heading>Details of configuration
3235 When we configure a package (this happens with <tt>dpkg
3236 --install</tt>, or with <tt>--configure</tt>), we first
3237 update the conffiles and then call:
3239 <var>postinst</var> configure <var>most-recently-configured-version</var>
3244 No attempt is made to unwind after errors during
3249 If there is no most recently configured version
3250 <prgn>dpkg</prgn> will pass a null argument; older versions
3251 of dpkg may pass <tt><unknown></tt> (including the
3252 angle brackets) in this case. Even older ones do not pass a
3253 second argument at all, under any circumstances.
3257 <sect><heading>Details of removal and/or configuration purging
3265 <var>prerm</var> remove
3271 The package's files are removed (except conffiles).
3276 <var>postrm</var> remove
3280 <p>All the maintainer scripts except the postrm are removed.
3284 If we aren't purging the package we stop here. Note
3285 that packages which have no postrm and no conffiles
3286 are automatically purged when removed, as there is no
3287 difference except for the <prgn>dpkg</prgn>
3292 The conffiles and any backup files (<tt>~</tt>-files,
3293 <tt>#*#</tt> files, <tt>%</tt>-files,
3294 <tt>.dpkg-{old,new,tmp}</tt>, etc.) are removed.</p>
3298 <var>postrm</var> purge
3302 <p>The package's file list is removed.</p>
3305 No attempt is made to unwind after errors during
3310 <chapt id="descriptions"><heading>Descriptions of packages - the
3311 <tt>Description</tt> field
3315 The <tt>Description</tt> control file field is used by
3316 <prgn>dselect</prgn> when the user is selecting which packages
3317 to install and by <prgn>dpkg</prgn> when it displays
3318 information about the status of packages and so forth. It is
3319 included on the FTP site in the <prgn>Packages</prgn> files,
3320 and may also be used by the Debian WWW pages.
3324 The description is intended to describe the program to a user
3325 who has never met it before so that they know whether they
3326 want to install it. It should also give information about the
3327 significant dependencies and conflicts between this package
3328 and others, so that the user knows why these dependencies and
3329 conflicts have been declared.
3333 The field's format is as follows:
3335 Description: <var>single line synopsis</var>
3336 <var>extended description over several lines</var>
3341 The synopsis is often printed in lists of packages and so
3342 forth, and should be as informative as possible. Every
3343 package should also have an extended description.
3346 <sect><heading>Types of formatting line in the extended
3354 Those starting with a single space are part of a
3355 paragraph. Successive lines of this form will be
3356 word-wrapped when displayed. The leading space will
3357 usually be stripped off.
3363 Those starting with two or more spaces. These will be
3364 displayed verbatim. If the display cannot be panned
3365 horizontally the displaying program will linewrap them
3366 `hard' (ie, without taking account of word breaks).
3367 If it can they will be allowed to trail off to the
3368 right. None, one or two initial spaces may be
3369 deleted, but the number of spaces deleted from each
3370 line will be the same (so that you can have indenting
3371 work correctly, for example).
3376 <p>Those containing a single space followed by a single full stop
3377 character. These are rendered as blank lines. This
3378 is the <em>only</em> way to get a blank line - see
3384 Those containing a space, a full stop and some more
3385 characters. These are for future expansion. Do not
3392 <sect><heading>Notes about writing descriptions
3396 <em>Always</em> start extended description lines with at least one
3397 whitespace character. Fields in the control file and in the Packages
3398 file are separated by field names starting in the first column, just
3399 as message header fields are in RFC822. Forgetting the whitespace
3400 will cause <prgn>dpkg-deb</prgn>
3403 Version 0.93.23 or later.
3405 </footnote> to produce a syntax error when trying to build
3406 the package. If you force it to build anyway
3407 <prgn>dpkg</prgn> will refuse to install the resulting
3412 <em>Do not</em> include any completely <em>empty</em>
3413 lines. These separate different records in the Packages file
3414 and different packages in the <tt>debian/control</tt> file,
3415 and are forbidden in package control files. See the
3416 previous paragraph for what happens if you get this wrong.
3420 The single line synopsis should be kept brief - certainly
3421 under 80 characters. <prgn>dselect</prgn> displays between
3422 25 and 49 characters without panning if you're using an
3423 80-column terminal, depending on what display options are in
3428 Do not include the package name in the synopsis line. The
3429 display software knows how to display this already, and you
3430 do not need to state it. Remember that in many situations
3431 the user may only see the synopsis line - make it as
3432 informative as you can.
3436 The extended description should describe what the package
3437 does and how it relates to the rest of the system (in terms
3438 of, for example, which subsystem it is which part of).
3442 The blurb that comes with a program in its announcements
3443 and/or <prgn>README</prgn> files is rarely suitable for use
3444 in a description. It is usually aimed at people who are
3445 already in the community where the package is used. The
3446 description field needs to make sense to anyone, even people
3447 who have no idea about any of the things the package deals
3452 Put important information first, both in the synopis and
3453 extended description. Sometimes only the first part of the
3454 synopsis or of the description will be displayed. You can
3455 assume that there will usually be a way to see the whole
3456 extended description.
3460 You may include information about dependencies and so forth
3461 in the extended description, if you wish.
3465 Do not use tab characters. Their effect is not predictable.
3469 Do not try to linewrap the summary (the part on the same
3470 line as the field name <tt>Description</tt>) into the
3471 extended description. This will not work correctly when the
3472 full description is displayed, and makes no sense where only
3473 the summary is available.</p>
3476 <sect><heading>Example description in control file for Smail
3482 Version: 3.1.29.1-13
3483 Maintainer: Ian Jackson <iwj10@cus.cam.ac.uk>
3484 Recommends: pine | mailx | elm | emacs | mail-user-agent
3486 Depends: cron, libc5
3488 Provides: mail-transport-agent
3489 Description: Electronic mail transport system.
3490 Smail is the recommended mail transport agent (MTA) for Debian.
3492 An MTA is the innards of the mail system - it takes messages from
3493 user-friendly mailer programs and arranges for them to be delivered
3494 locally or passed on to other systems as required.
3496 In order to make use of it you must have one or more user level
3497 mailreader programs such as elm, pine, mailx or Emacs (which has Rmail
3498 and VM as mailreaders) installed. If you wish to send messages other
3499 than just to other users of your system you must also have appropriate
3500 networking support, in the form of IP or UUCP.
3506 <chapt id="relationships"><heading>Declaring relationships between
3511 Packages can declare in their control file that they have
3512 certain relationships to other packages - for example, that
3513 they may not be installed at the same time as certain other
3514 packages, and/or that they depend on the presence of others,
3515 or that they should overwrite files in certain other packages
3520 This is done using the <tt>Depends</tt>, <tt>Recommends</tt>,
3521 <tt>Suggests</tt>, <tt>Conflicts</tt>, <tt>Provides</tt> and
3522 <tt>Replaces</tt> control file fields.
3525 <sect id="depsyntax"><heading>Syntax of relationship fields
3529 These fields all have a uniform syntax. They are a list of
3530 package names separated by commas.
3534 In <tt>Depends</tt>, <tt>Recommends</tt>, <tt>Suggests</tt>
3535 and <tt>Pre-Depends</tt> (the fields which declare
3536 dependencies of the package in which they occur on other
3537 packages) these package names may also be lists of
3538 alternative package names, separated by vertical bar symbols
3539 <tt>|</tt> (pipe symbols).
3543 All the fields except <tt>Provides</tt> may restrict their
3544 applicability to particular versions of each named package.
3545 This is done in parentheses after each individual package
3546 name; the parentheses should contain a relation from the
3547 list below followed by a version number, in the format
3548 described in <ref id="versions">.
3552 The relations allowed are <tt><<</tt>, <tt><=</tt>,
3553 <tt>=</tt>, <tt>>=</tt> and <tt>>></tt> for
3554 strictly earlier, earlier or equal, exactly equal, later or
3555 equal and strictly later, respectively. The forms
3556 <tt><</tt> and <tt>></tt> were used to mean
3557 earlier/later or equal, rather than strictly earlier/later,
3558 so they should not appear in new packages (though
3559 <prgn>dpkg</prgn> still supports them).
3563 Whitespace may appear at any point in the version
3564 specification, and must appear where it's necessary to
3565 disambiguate; it is not otherwise significant. For
3566 consistency and in case of future changes to
3567 <prgn>dpkg</prgn> it is recommended that a single space be
3568 used after a version relationship and before a version
3569 number; it is usual also to put a single space after each
3570 comma, on either side of each vertical bar, and before each
3579 Depends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh
3584 <sect><heading>Dependencies - <tt>Depends</tt>, <tt>Recommends</tt>,
3585 <tt>Suggests</tt>, <tt>Pre-Depends</tt>
3589 These four fields are used to declare a dependency by one
3590 package on another. They appear in the depending package's
3595 All but <tt>Pre-Depends</tt> (discussed below) take effect
3596 <em>only</em> when a package is to be configured. They do
3597 not prevent a package being on the system in an unconfigured
3598 state while its dependencies are unsatisfied, and it is
3599 possible to replace a package whose dependencies are
3600 satisfied and which is properly installed with a different
3601 version whose dependencies are not and cannot be satisfied;
3602 when this is done the depending package will be left
3603 unconfigured (since attempts to configure it will give
3604 errors) and will not function properly.
3608 For this reason packages in an installation run are usually
3609 all unpacked first and all configured later; this gives
3610 later versions of packages with dependencies on later
3611 versions of other packages the opportunity to have their
3612 dependencies satisfied.
3616 Thus <tt>Depends</tt> allows package maintainers to impose
3617 an order in which packages should be configured.
3619 <tag><tt>Depends</tt></tag>
3622 <p>This declares an absolute dependency.
3626 <prgn>dpkg</prgn> will not configure packages whose
3627 dependencies aren't satisfied. If it is asked to make
3628 an installation which would cause an installed
3629 package's dependencies to become unsatisfied it will
3633 Current versions (1.2.4) of <prgn>dpkg</prgn> have
3634 a bug in this area which will cause some of these
3635 problems to be ignored.
3637 </footnote>, unless <tt>--auto-deconfigure</tt> is
3638 specified, in which case those packages will be
3639 deconfigured before the installation proceeds.
3643 <prgn>dselect</prgn> makes it hard for the user to
3644 select packages for installation, removal or upgrade
3645 in a way that would mean that packages'
3646 <prgn>Depends</prgn> fields would be unsatisfied. The
3647 user can override this if they wish, for example if
3648 they know that <prgn>dselect</prgn> has an out-of-date
3649 view of the real package relationships.
3653 The <tt>Depends</tt> field should be used if the
3654 depended-on package is required for the depending
3655 package to provide a significant amount of
3659 <tag><tt>Recommends</tt></tag>
3661 <p>This declares a strong, but not absolute, dependency.
3665 <tt>Recommends</tt> is ignored by <prgn>dpkg</prgn>,
3666 so that users using the command-line (who are presumed
3667 to know what they're doing) will not be impeded.
3671 It is treated by <prgn>dselect</prgn> exactly as
3672 <tt>Depends</tt> is; this makes it hard for the user
3673 to select things so as to leave <tt>Recommends</tt>
3674 fields unsatisfied, but they are able to do so by
3679 The <tt>Recommends</tt> field should list packages
3680 that would be found together with this one in all but
3681 unusual installations.</p>
3684 <tag><tt>Suggests</tt></tag>
3688 This is used to declare that one package may be more
3689 useful with one or more others. Using this field
3690 tells the packaging system and the user that the
3691 listed packages are be related to this one and can
3692 perhaps enhance its usefulness, but that installing
3693 this one without them is perfectly reasonable.
3697 <prgn>dselect</prgn> will offer suggsted packages to
3698 the system administrator when they select the
3699 suggesting package, but the default is not to install
3700 the suggested package.</p>
3703 <tag><tt>Pre-Depends</tt></tag>
3706 <p>This field is like <tt>Depends</tt>, except that it also forces
3707 <prgn>dpkg</prgn> to complete installation of the
3708 packages named before even starting the installation
3709 of the package which declares the predependency.
3713 <prgn>dselect</prgn> checks for predependencies when
3714 it is doing an installation run, and will attempt to
3715 find the packages which are required to be installed
3716 first and do so in the right order.
3720 However, this process is slow (because it requires
3721 repeated invocations of <prgn>dpkg</prgn>) and
3722 troublesome (because it requires guessing where to
3723 find the appropriate files).
3727 For these reasons, and because this field imposes
3728 restrictions on the order in which packages may be
3729 unpacked (which can be difficult for installations
3730 from multipart media, for example),
3731 <tt>Pre-Depends</tt> should be used sparingly,
3732 preferably only by packages whose premature upgrade or
3733 installation would hamper the ability of the system to
3734 continue with any upgrade that might be in progress.
3738 When the package declaring it is being configured, a
3739 <tt>Pre-Dependency</tt> will be considered satisfied
3740 only if the depending package has been correctly
3741 configured, just as if an ordinary <tt>Depends</tt>
3746 However, when a package declaring a predependency is
3747 being unpacked the predependency can be satisfied even
3748 if the depended-on package(s) are only unpacked or
3749 half-configured, provided that they have been
3750 configured correctly at some point in the past (and
3751 not removed or partially removed since). In this case
3752 both the previously-configured and currently unpacked
3753 or half-configured versions must satisfy any version
3754 clause in the <tt>Pre-Depends</tt> field.
3760 When selecting which level of dependency to use you should
3761 consider how important the depended-on package is to the
3762 functionality of the one declaring the dependency. Some
3763 packages are composed of components of varying degrees of
3764 importance. Such a package should list using
3765 <tt>Depends</tt> the package(s) which are required by the
3766 more important components. The other components'
3767 requirements may be mentioned as Suggestions or
3768 Recommendations, as appropriate to the components' relative
3772 <sect1><heading>Dependencies on shared libraries
3776 The dependency fields listed above are used by packages
3777 which need shared libraries to declare dependencies on the
3778 appropriate packages.
3782 These dependencies are usually determined automatically
3783 using <prgn>dpkg-shlibdeps</prgn> and inserted in the
3784 package control file using the control file substitution
3785 variables mechanism; see <ref id="srcsubstvars"> and
3786 <ref id="sourcetools">.
3790 <sect1><heading>Deconfiguration due to removal during bulk
3795 If <prgn>dpkg</prgn> would like to remove a package due to a
3796 conflict, as described above, but this would violate a
3797 dependency of some other package on the system,
3798 <prgn>dpkg</prgn> will usually not remove the conflicting
3799 package and halt with an error.
3803 However, if the <tt>--auto-deconfigure</tt> (<tt>-B</tt>)
3804 option is used <prgn>dpkg</prgn> will automatically
3805 `deconfigure' the package with the problematic dependency,
3806 so that the conflicting package can be removed and the
3807 package we're trying to install can be installed. If
3808 <prgn>dpkg</prgn> is being asked to install packages (rather
3809 than just unpacking them) it will try to reconfigure the
3810 package when it has unpacked all its arguments, in the hope
3811 that one of the other packages it is installing will satisfy
3812 the problematic dependency.
3816 <prgn>dselect</prgn> supplies this argument to
3817 <prgn>dpkg</prgn> when it invokes it, so that bulk
3818 installations proceed smoothly.
3822 <sect id="conflicts"><heading>Alternative packages -
3823 <tt>Conflicts</tt> and <tt>Replaces</tt>
3827 When one package declares a conflict with another
3828 <prgn>dpkg</prgn> will refuse to allow them to be installed
3829 on the system at the same time.
3833 If one package is to be installed, the other must be removed first -
3834 if the package being installed is marked as replacing (<ref
3835 id="replaces">) the one on the system, or the one on the system is
3836 marked as deselected, or both packages are marked
3837 <tt>Essential</tt>, then <prgn>dpkg</prgn> will
3838 automatically remove the package which is causing the
3839 conflict, otherwise it will halt the installation of the new
3840 package with an error.
3844 <prgn>dselect</prgn> makes it hard to select conflicting
3845 packages, though the user can override this if they wish.
3846 If they do not override it then <prgn>dselect</prgn> will
3847 select one of the packages for removal, and the user must
3848 make sure it is the right one. In the future
3849 <prgn>dselect</prgn> will look for the presence of a
3850 <tt>Replaces</tt> field to help decide which package should
3851 be installed and which removed.
3855 A package will not cause a conflict merely because its
3856 configuration files are still installed; it must be at least
3861 A special exception is made for packages which declare a
3862 conflict with their own package name, or with a virtual
3863 package which they provide (see below): this does not
3864 prevent their installation, and allows a package to conflict
3865 with others providing a replacement for it. You use this
3866 feature when you want the package in question to be the only
3867 package providing something.
3871 A <tt>Conflicts</tt> entry should almost never have an
3872 `earlier than' version clause. This would prevent
3873 <prgn>dpkg</prgn> from upgrading or installing the package
3874 which declared such a conflict until the upgrade or removal
3875 of the conflicted-with package had been completed. This
3876 aspect of installation ordering is not handled by
3877 <prgn>dselect</prgn>, so that the use <tt>Conflicts</tt> in
3878 this way is likely to cause problems for `bulk run' upgrades
3883 <sect id="virtual"><heading>Virtual packages - <tt>Provides</tt>
3887 As well as the names of actual (`concrete') packages, the
3888 package relationship fields <tt>Depends</tt>,
3889 <tt>Recommends</tt>, <tt>Suggests</tt> and
3890 <tt>Conflicts</tt> may mention virtual packages.
3894 A virtual package is one which appears in the
3895 <tt>Provides</tt> control file field of another package.
3896 The effect is as if the package(s) which provide a
3897 particular virtual package name had been listed by name
3898 everywhere the virtual package name appears.
3902 If there are both a real and a virtual package of the same
3903 name then the dependency may be satisfied (or the conflict
3904 caused) by either the real package or any of the virtual
3905 packages which provide it. This is so that, for example,
3911 and someone else releases an xemacs package they can say
3915 </example> and all will work in the interim (until a purely
3916 virtual package name is decided on and the <tt>emacs</tt>
3917 and <tt>vm</tt> packages are changed to use it).
3921 If a dependency or a conflict has a version number attached
3922 then only real packages will be considered to see whether
3923 the relationship is satisfied (or the prohibition violated,
3924 for a conflict) - it is assumed that a real package which
3925 provides virtual package is not of the `right' version. So,
3926 a <tt>Provides</tt> field may not contain version numbers,
3927 and the version number of the concrete package which
3928 provides a particular virtual package will not be looked at
3929 when considering a dependency on or conflict with the
3930 virtual package name.
3934 It is likely that the ability will be added in a future
3935 release of <prgn>dpkg</prgn> to specify a version number for
3936 each virtual package it provides. This feature is not yet
3937 present, however, and is expected to be used only
3942 If you want to specify which of a set of real packages should be the
3943 default to satisfy a particular dependency on a virtual package, you
3944 should list the real package as an alternative before the virtual.
3949 <sect id="replaces"><heading><tt>Replaces</tt> - overwriting
3950 files and replacing packages
3954 The <tt>Replaces</tt> control file field has two purposes,
3955 which come into play in different situations.
3959 Virtual packages (<ref id="virtual">) are not considered
3960 when looking at a <tt>Replaces</tt> field - the packages
3961 declared as being replaced must be mentioned by their real
3965 <sect1><heading>Overwriting files in other packages
3969 Firstly, as mentioned before, it is usually an error for a
3970 package to contains files which are on the system in
3971 another package, though currently the
3972 <tt>--force-overwrite</tt> flag is enabled by default,
3973 downgrading the error to a warning,
3977 If the overwriting package declares that it replaces the
3978 one containing the file being overwritten then
3979 <prgn>dpkg</prgn> will proceed, and replace the file from
3980 the old package with that from the new. The file will no
3981 longer be listed as `owned' by the old package.
3985 If a package is completely replaced in this way, so that
3986 <prgn>dpkg</prgn> does not know of any files it still
3987 contains, it is considered to have disappeared. It will
3988 be marked as not wanted on the system (selected for
3989 removal) and not installed. Any conffiles details noted
3990 in the package will be ignored, as they will have been
3991 taken over by the replacing package(s). The package's
3992 <prgn>postrm</prgn> script will be run to allow the
3993 package to do any final cleanup required. See <ref
3994 id="mscriptsinstact">.
3998 In the future <prgn>dpkg</prgn> will discard files which
3999 overwrite those from another package which declares that
4000 it replaces the one being installed (so that you can
4001 install an older version of a package without problems).
4005 This usage of <tt>Replaces</tt> only takes effect when
4006 both packages are at least partially on the system at
4007 once, so that it can only happen if they do not conflict
4008 or if the conflict has been overridden.</p>
4011 <sect1><heading>Replacing whole packages, forcing their
4016 Secondly, <tt>Replaces</tt> allows <prgn>dpkg</prgn> and
4017 <prgn>dselect</prgn> to resolve which package should be
4018 removed when there is a conflict - see <ref id="conflicts">. This
4019 usage only takes effect when the two packages <em>do</em>
4020 conflict, so that the two effects do not interfere with
4026 <sect><heading>Defaults for satisfying dependencies - ordering
4030 Ordering is significant in dependency fields.
4034 Usually dselect will suggest to the user that they select
4035 the package with the most `fundamental' class (eg, it will
4036 prefer Base packages to Optional ones), or the one that they
4037 `most wanted' to select in some sense.
4041 In the absence of other information <prgn>dselect</prgn>
4042 will offer a default selection of the first named package in
4043 a list of alternatives.
4047 However, there is no way to specify the `order' of several
4048 packages which all provide the same thing, when that thing
4049 is listed as a dependency.
4053 Therefore a dependency on a virtual package should contain a
4054 concrete package name as the first alternative, so that this
4059 For example, consider the set of packages:
4062 Recommends: info-browser
4065 Provides: info-browser
4068 Provides: info-browser
4073 If <prgn>emacs</prgn> and <prgn>info</prgn> both have the
4074 same priority then <prgn>dselect</prgn>'s choice is
4075 essentially random. Better would be
4078 Recommends: info | info-browser
4080 so that <prgn>dselect</prgn> defaults to selecting the
4081 lightweight standalone info browser.
4086 <chapt id="conffiles"><heading>Configuration file handling
4090 <prgn>dpkg</prgn> can do a certain amount of automatic
4091 handling of package configuration files.
4095 Whether this mechanism is appropriate depends on a number of
4096 factors, but basically there are two approaches to any
4097 particular configuration file.
4101 The easy method is to ship a best-effort configuration in the
4102 package, and use <prgn>dpkg</prgn>'s conffile mechanism to
4103 handle updates. If the user is unlikely to want to edit the
4104 file, but you need them to be able to without losing their
4105 changes, and a new package with a changed version of the file
4106 is only released infrequently, this is a good approach.
4110 The hard method is to build the configuration file from
4111 scratch in the <prgn>postinst</prgn> script, and to take the
4112 responsibility for fixing any mistakes made in earlier
4113 versions of the package automatically. This will be
4114 appropriate if the file is likely to need to be different on
4118 <sect><heading>Automatic handling of configuration files by
4123 A package may contain a control area file called
4124 <tt>conffiles</tt>. This file should be a list of filenames
4125 of configuration files needing automatic handling, separated
4126 by newlines. The filenames should be absolute pathnames,
4127 and the files referred to should actually exist in the
4132 When a package is upgraded <prgn>dpkg</prgn> will process
4133 the configuration files during the configuration stage,
4134 shortly before it runs the package's <prgn>postinst</prgn>
4139 For each file it checks to see whether the version of the
4140 file included in the package is the same as the one that was
4141 included in the last version of the package (the one that is
4142 being upgraded from); it also compares the version currently
4143 installed on the system with the one shipped with the last
4148 If neither the user nor the package maintainer has changed
4149 the file, it is left alone. If one or the other has changed
4150 their version, then the changed version is preferred - i.e.,
4151 if the user edits their file, but the package maintainer
4152 doesn't ship a different version, the user's changes will
4153 stay, silently, but if the maintainer ships a new version
4154 and the user hasn't edited it the new version will be
4155 installed (with an informative message). If both have
4156 changed their version the user is prompted about the problem
4157 and must resolve the differences themselves.
4161 The comparisons are done by calculating the MD5 message
4162 digests of the files, and storing the MD5 of the file as it
4163 was included in the most recent version of the package.
4167 When a package is installed for the first time
4168 <prgn>dpkg</prgn> will install the file that comes with it,
4169 unless that would mean overwriting a file already on the
4174 However, note that <prgn>dpkg</prgn> will <em>not</em>
4175 replace a conffile that was removed by the user (or by a
4176 script). This is necessary because with some programs a
4177 missing file produces an effect hard or impossible to
4178 achieve in another way, so that a missing file needs to be
4179 kept that way if the user did it.
4183 Note that a package should <em>not</em> modify a
4184 <prgn>dpkg</prgn>-handled conffile in its maintainer
4185 scripts. Doing this will lead to <prgn>dpkg</prgn> giving
4186 the user confusing and possibly dangerous options for
4187 conffile update when the package is upgraded.</p>
4190 <sect><heading>Fully-featured maintainer script configuration
4195 For files which contain site-specific information such as
4196 the hostname and networking details and so forth, it is
4197 better to create the file in the package's
4198 <prgn>postinst</prgn> script.
4202 This will typically involve examining the state of the rest
4203 of the system to determine values and other information, and
4204 may involve prompting the user for some information which
4205 can't be obtained some other way.
4209 When using this method there are a couple of important
4210 issues which should be considered:
4214 If you discover a bug in the program which generates the
4215 configuration file, or if the format of the file changes
4216 from one version to the next, you will have to arrange for
4217 the postinst script to do something sensible - usually this
4218 will mean editing the installed configuration file to remove
4219 the problem or change the syntax. You will have to do this
4220 very carefully, since the user may have changed the file,
4221 perhaps to fix the very problem that your script is trying
4222 to deal with - you will have to detect these situations and
4223 deal with them correctly.
4227 If you do go down this route it's probably a good idea to
4228 make the program that generates the configuration file(s) a
4229 separate program in <tt>/usr/sbin</tt>, by convention called
4230 <tt><var>package</var>config</tt> and then run that if
4231 appropriate from the post-installation script. The
4232 <tt><var>package</var>config</tt> program should not
4233 unquestioningly overwrite an existing configuration - if its
4234 mode of operation is geared towards setting up a package for
4235 the first time (rather than any arbitrary reconfiguration
4236 later) you should have it check whether the configuration
4237 already exists, and require a <tt>--force</tt> flag to
4238 overwrite it.</p></sect>
4243 <chapt id="alternatives"><heading>Alternative versions of an interface -
4244 <prgn>update-alternatives</prgn>
4248 When several packages all provide different versions of the
4249 same program or file it is useful to have the system select a
4250 default, but to allow the system administrator to change it
4251 and have their decisions respected.
4255 For example, there are several versions of the <prgn>vi</prgn>
4256 editor, and there is no reason to prevent all of them from
4257 being installed at once, each under their own name
4258 (<prgn>nvi</prgn>, <prgn>vim</prgn> or whatever).
4259 Nevertheless it is desirable to have the name <tt>vi</tt>
4260 refer to something, at least by default.
4264 If all the packages involved cooperate, this can be done with
4265 <prgn>update-alternatives</prgn>.
4269 Each package provides its own version under its own name, and
4270 calls <prgn>update-alternatives</prgn> in its postinst to
4271 register its version (and again in its prerm to deregister
4276 See the manpage <manref name="update-alternatives"
4277 section="8"> for details.
4281 If <prgn>update-alternatives</prgn> does not seem appropriate
4282 you may wish to consider using diversions instead.</p>
4286 <chapt id="diversions"><heading>Diversions - overriding a
4287 package's version of a file
4291 It is possible to have <prgn>dpkg</prgn> not overwrite a file
4292 when it reinstalls the package it belongs to, and to have it
4293 put the file from the package somewhere else instead.
4297 This can be used locally to override a package's version of a
4298 file, or by one package to override another's version (or
4299 provide a wrapper for it).
4303 Before deciding to use a diversion, read <ref
4304 id="alternatives"> to see if you really want a diversion
4305 rather than several alternative versions of a program.
4309 There is a diversion list, which is read by <prgn>dpkg</prgn>,
4310 and updated by a special program <prgn>dpkg-divert</prgn>.
4311 Please see <manref name="dpkg-divert" section="8"> for full
4312 details of its operation.
4316 When a package wishes to divert a file from another, it should
4317 call <prgn>dpkg-divert</prgn> in its preinst to add the
4318 diversion and rename the existing file. For example,
4319 supposing that a <prgn>smailwrapper</prgn> package wishes to
4320 install a wrapper around <tt>/usr/sbin/smail</tt>:
4322 if [ install = "$1" ]; then
4323 dpkg-divert --package smailwrapper --add --rename \
4324 --divert /usr/sbin/smail.real /usr/sbin/smail
4326 </example> Testing <tt>$1</tt> is necessary so that the script
4327 doesn't try to add the diversion again when
4328 <prgn>smailwrapper</prgn> is upgraded. The <tt>--package
4329 smailwrapper</tt> ensures that <prgn>smailwrapper</prgn>'s
4330 copy of <tt>/usr/sbin/smail</tt> can bypass the diversion and
4331 get installed as the true version.
4335 The postrm has to do the reverse:
4337 if [ remove = "$1" ]; then
4338 dpkg-divert --package smailwrapper --remove --rename \
4339 --divert /usr/sbin/smail.real /usr/sbin/smail
4345 Do not attempt to divert a file which is vitally important for
4346 the system's operation - when using <prgn>dpkg-divert</prgn>
4347 there is a time, after it has been diverted but before
4348 <prgn>dpkg</prgn> has installed the new version, when the file
4353 <chapt id="sharedlibs"><heading>Shared libraries
4357 Packages containing shared libraries must be constructed with
4358 a little care to make sure that the shared library is always
4359 available. This is especially important for packages whose
4360 shared libraries are vitally important, such as the libc.
4364 Firstly, your package should install the shared libraries
4365 under their normal names. For example, the
4366 <prgn>libgdbm1</prgn> package should install
4367 <tt>libgdbm.so.1.7.3</tt> as
4368 <tt>/usr/lib/libgdbm.so.1.7.3</tt>. The files should not be
4369 renamed or relinked by any prerm or postrm scripts;
4370 <prgn>dpkg</prgn> will take care of renaming things safely
4371 without affecting running programs, and attempts to interfere
4372 with this are likely to lead to problems.
4376 Secondly, your package should include the symlink that
4377 <prgn>ldconfig</prgn> would create for the shared libraries.
4378 For example, the <prgn>libgdbm1</prgn> package should include
4379 a symlink from <tt>/usr/lib/libgdbm.so.1</tt> to
4380 <tt>libgdbm.so.1.7.3</tt>. This is needed so that
4381 <prgn>ld.so</prgn> can find the library in between the time
4382 <prgn>dpkg</prgn> installs it and <prgn>ldconfig</prgn> is run
4383 in the <prgn>postinst</prgn> script. Futhermore, and <em>this
4384 is very important</em>, the library must be placed before the
4385 symlink pointing to it in the <tt>.deb</tt> file. This is so
4386 that by the time <prgn>dpkg</prgn> comes to install the
4387 symlink (overwriting the previous symlink pointing at an older
4388 version of the library) the new shared library is already in
4389 place. Currently the way to ensure the ordering is done
4390 properly is to install the library in the appropriate
4391 <tt>debian/tmp/.../lib</tt> directory before creating the
4392 symlink, by putting the commands in the <tt>debian/rules</tt>
4393 in the appropriate order.
4397 next Paragraph added to close Bug #5299, Guy Maor
4401 Thirdly, the development package should contain a symlink for
4402 the shared library without a version number. For example, the
4403 <tt>libgdbm1-dev</tt> package should include a symlink from
4404 <tt>/usr/lib/libgdm.so</tt> to <tt>libgdm.so.1.7.3</tt>. This
4405 symlink is needed by <prgn>ld</prgn> when compiling packages
4406 as it will only look for <tt>libgdm.so</tt> and
4407 <tt>libgdm.a</tt> when compiling dynamically or statically,
4412 next paragraph changed by Christian Schwarz (see policy weekly #6)
4416 Any package installing shared libraries in a directory that's listed
4417 in <tt>/etc/ld.so.conf</tt> or in one of the default library
4418 directories of <prgn>ld.so</prgn> (currently, these are <tt>/usr/lib</tt>
4419 and <tt>/lib</tt>) must call <prgn>ldconfig</prgn> in its <prgn>postinst</prgn>
4420 script if and only if the first argument is `configure'. However, it
4421 is important not to call <prgn>ldconfig</prgn> in the postrm or preinst
4422 scripts in the case where the package is being upgraded (see <ref
4423 id="unpackphase">), as <prgn>ldconfig</prgn> will see the temporary names
4424 that <prgn>dpkg</prgn> uses for the files while it is
4425 installing them and will make the shared library links point
4426 to them, just before <prgn>dpkg</prgn> continues the
4427 installation and removes the links!
4431 moved from section 2.2 , DMorris
4434 <sect id="shlibs"><heading>The <tt>shlibs</tt> File Format
4438 This file is for use by <prgn>dpkg-shlibdeps</prgn> and is
4439 required when your package provides shared libraries.
4443 Each line is of the form:
4445 <var>library-name</var> <var>version-or-soname</var> <var>dependencies ...</var>
4450 <var>library-name</var> is the name of the shared library,
4451 for example <tt>libc5</tt>.
4455 <var>version-or-soname</var> is the soname of the library -
4456 ie, the thing that must exactly match for the library to be
4457 recognised by <prgn>ld.so</prgn>. Usually this is major
4458 version number of the library.
4462 <var>dependencies</var> has the same syntax as a dependency
4463 field in a binary package control file. It should give
4464 details of which package(s) are required to satisfy a binary
4465 built against the version of the library contained in the
4466 package. See <ref id="depsyntax">.
4470 For example, if the package <tt>foo</tt> contains
4471 <tt>libfoo.so.1.2.3</tt>, where the soname of the library is
4472 <tt>libfoo.so.1</tt>, and the first version of the package
4473 which contained a minor number of at least <tt>2.3</tt> was
4474 <var>1.2.3-1</var>, then the package's <var>shlibs</var>
4477 libfoo 1 foo (>= 1.2.3-1)
4482 The version-specific dependency is to avoid warnings from
4483 <prgn>ld.so</prgn> about using older shared libraries with
4487 <sect><heading>Further Technical information on
4488 <tt>shlibs</tt></heading>
4492 following section mostly provided by Heiko Schlittermann
4496 <sect1><heading><em>What</em> are the <tt>shlibs</tt> files?
4500 The <tt>debian/shlibs</tt> file provides a way of checking
4501 for shared library dependencies on packaged binaries.
4502 They are intended to be used by package maintainers to
4503 make their lives easier.
4507 Other <tt>shlibs</tt> files that exist on a Debian system are
4509 <item> <p><tt>/etc/dpkg/shlibs.default</tt></p></item>
4510 <item> <p><tt>/etc/dpkg/shlibs.override</tt></p></item>
4511 <item> <p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
4512 <item> <p><tt>debian/shlibs.local</tt></p></item>
4514 These files are used by <prgn>dpkg-shlibdeps</prgn> when
4515 creating a binary package.</p>
4518 <sect1><heading><em>How</em> does <prgn>dpkg-shlibdeps</prgn>
4523 <prgn>dpkg-shlibdeps</prgn> calls <prgn>ldd</prgn> to
4524 determine the shared libraries used by the compiled
4525 binaries passed through its command line.
4529 For each shared library, <prgn>dpkg-shlibdeps</prgn> needs to know
4530 <list compact="compact">
4531 <item><p>the package containing the library, and</p></item>
4532 <item><p>the library version number,</p></item>
4535 it scans the following files in this order.
4536 <enumlist compact="compact">
4537 <item><p><tt>debian/shlibs.local</tt></p></item>
4538 <item><p><tt>/etc/dpkg/shlibs.override</tt></p></item>
4539 <item><p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
4540 <item><p><tt>/etc/dpkg/shlibs.default</tt></p></item>
4544 <sect1><heading><em>Who</em> maintains the various
4545 <tt>shlibs</tt> files?
4549 <list compact="compact">
4551 <p><tt>/etc/dpkg/shlibs.default</tt> - the maintainer
4556 <tt>/var/lib/dpkg/info/<var>package</var>.shlibs</tt>
4557 - the maintainer of each package</p>
4561 <tt>/etc/dpkg/shlibs.override</tt> - the local
4562 system administrator</p>
4565 <p><tt>debian/shlibs.local</tt> - the maintainer of
4570 The <tt>shlibs.default</tt> file is managed by
4571 <prgn>dpkg</prgn>. The entries in <tt>shlibs.default</tt>
4572 that are provided by <prgn>dpkg</prgn> are just there to
4573 fix things until the shared library packages all have
4574 <tt>shlibs</tt> files.
4578 <sect1><heading><em>How</em> to use <prgn>dpkg-shlibdeps</prgn> and
4579 the <tt>shlibs</tt> files?
4582 <sect2><heading>If your package doesn't provide a shared
4587 Put a call to <prgn>dpkg-shlibdeps</prgn> into your
4588 <tt>debian/rules</tt> file. If your package contains
4589 only binaries (e.g. no scripts) use:
4591 dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/*
4593 If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
4594 done. If it does complain you might need to create your
4595 own <tt>debian/shlibs.local</tt> file.</p>
4598 <sect2><heading>If your package provides a shared library
4602 Create a <tt>debian/shlibs</tt> file and let
4603 <tt>debian/rules</tt> install it in the control area:
4605 install -m644 debian/shlibs debian/tmp/DEBIAN
4607 If your package contains additional binaries see above.
4612 <sect1><heading><em>How</em> to write
4613 <tt>debian/shlibs.local</tt>
4617 This file is intended only as a <em>temporary</em> fix if
4618 your binaries depend on a library which doesn't provide
4619 its own <tt>/var/lib/dpkg/*.shlibs</tt> file yet.
4623 Let's assume you are packaging a binary <tt>foo</tt>. Your
4624 output in building the package might look like this.
4627 libbar.so.1 => /usr/X11R6/lib/libbar.so.1.0
4628 libc.so.5 => /lib/libc.so.5.2.18
4629 libX11.so.6 => /usr/X11R6/lib/libX11.so.6.0
4631 And when you ran <prgn>dpkg-shlibdeps</prgn>
4633 $ dpkg-shlibdeps -o foo
4634 dpkg-shlibdeps: warning: unable to find dependency information
4635 for shared library libbar
4636 (soname 1, path /usr/X11R6/lib/libbar.so.1.0, dependency field Depends)
4637 shlibs:Depends=elf-x11r6lib, libc5 (>= 5.2.18)
4639 The <prgn>foo</prgn> binary depends on the
4640 <prgn>libbar</prgn> shared library, but no package seems
4641 to provide a <tt>*.shlibs</tt> file in
4642 <tt></tt>var/lib/dpkg/info/. Let's determine the package
4648 $ dpkg -S /usr/X11R6/lib/libbar.so.1.0
4649 bar1: /usr/X11R6/lib/libbar.so.1.0
4650 $ dpkg -s bar1 | grep Version
4653 This tells us that the <prgn>bar1</prgn> package, version
4654 1.0-1 is the one we are using. Now we can create our own
4655 <tt>debian/shlibs.local</tt> to temporarly fix the above
4656 problem. Include the following line into your
4657 <tt>debian/shlibs.local</tt> file.
4659 libbar 1 bar1 (>= 1.0-1)
4661 Now your package build should work. As soon as the
4662 maintainer of <prgn>libbar1</prgn> provides a
4663 <tt>shlibs</tt> file, you can remove your
4664 <tt>debian/shlibs.local</tt> file.
4670 <chapt id="methif"><heading><prgn>dselect</prgn>'s interface to
4671 its installation methods
4675 <prgn>dselect</prgn> calls scripts from its installation
4676 methods when it needs to actually access data from the
4677 distribution. The core program <prgn>dselect</prgn> itself
4678 just calls these scripts and provides the package and access
4679 method selection interfaces. The installation methods are
4680 responsible for invoking <prgn>dpkg</prgn> as appropriate.
4684 Each installation method has three scripts:
4685 <list compact="compact">
4686 <item><p>Setup installation parameters.</p></item>
4687 <item><p>Update list of available packages.</p></item>
4688 <item><p>Install.</p></item>
4692 <prgn>dselect</prgn> searches for methods in
4693 <tt>/usr/lib/dpkg/methods</tt> and
4694 <tt>/usr/local/lib/dpkg/methods</tt>.
4697 <sect><heading>Functions of the method scripts
4701 The setup script is run just after the user has chosen an
4702 installation method. It should prompt the user for
4703 parameters like the site to NFS-mount or FTP from, the
4704 directory to use, or the directory or filesystem where the
4705 <tt>.deb</tt> files can be found, or the tape or floppy
4706 device to install from. It should store the responses under
4707 <tt>/var/lib/dpkg/methods</tt> - see below. If no available
4708 packages list is available it should perhaps offer to scan
4709 the available packages.
4713 The update script should obtain a list of available packages
4714 if possible, and run <tt>dpkg --update-avail</tt>, <tt>dpkg
4715 --merge-avail</tt> and/or <tt>dpkg --forget-old-unavail</tt>
4716 to load it into <prgn>dpkg</prgn> and <prgn>dselect</prgn>'s
4717 database of available packages. If no packages list was
4718 available and the user was offered and accepted the option
4719 of scanning the actual files available this scan should be
4720 done here, using <tt>dpkg --record-avail</tt>.
4724 The install script should feed all the available
4725 <tt>.deb</tt> files to <tt>dpkg --iGOEB</tt> (this is
4726 equivalent to <tt>dpkg --install
4727 --refuse-downgrade --selected-only --skip-same-version
4728 --auto-deconfigure</tt>). The <tt>-R</tt>
4729 (<tt>--recursive</tt>) option for traversing subdirectories
4730 may also be useful here).
4734 If any of these scripts needs to display a message for the
4735 user, it should wait for the user to hit `return' before
4736 exiting so that dselect doesn't immediately rewrite the
4741 If a method script succeeds (returns a zero exit status)
4742 <prgn>dselect</prgn> will return immediately to the main
4743 menu, with the `next' option highlighted ready for the user
4744 to select it. If it fails <prgn>dselect</prgn> will display
4745 a message and wait for the user to hit return.</p>
4748 <sect><heading>Location and arguments of the method scripts
4752 A set of scripts (henceforth known as a group) may provide
4753 several methods on the `main menu' with different behaviour.
4754 For example, there might be a generic get-packages-by-FTP
4755 group which might provide methods in the main menu for
4756 installation directly from one of the Debian mirror sites as
4757 well as for installation from a user-specified site.
4761 Each group of methods implemented by the same set of scripts
4762 should have a subdirectory
4763 <tt>/usr/lib/dpkg/methods/<var>group</var></tt> or
4764 <tt>/usr/local/lib/dpkg/methods/<var>group</var></tt>,
4766 <taglist compact="compact">
4767 <tag><tt>names</tt></tag>
4768 <item><p>a list of user-visible methods provided by these scripts.</p>
4770 <tag><tt>setup</tt></tag>
4771 <tag><tt>update</tt></tag>
4772 <tag><tt>install</tt></tag>
4773 <item><p>executable programs, the scripts themselves.</p>
4775 <tag><tt>desc.<var>option</var></tt></tag>
4776 <item><p>description file.</p></item>
4781 <tt>names</tt> will be formatted as a list of lines, each containing:
4783 <var>sequence</var> <var>method</var> <var>summary</var>
4787 <var>sequence</var> is a two-digit number that will be used
4788 much like <tt>rc.d</tt> prefixes to control the order in the
4789 main menu. If in doubt use 50.
4793 <var>method</var> is a name which is displayed by
4794 <prgn>dselect</prgn> as the name of the method, and which
4795 will be passed to <tt>setup</tt>, <tt>update</tt> and
4796 <tt>unpack</tt> as their first argument.
4800 <var>summary</var> is the brief description string for
4801 <prgn>dselect</prgn>'s menu.
4805 Each of the three scripts gets the same three arguments:
4806 <var>vardir</var>, <var>group</var> and <var>method</var>.
4807 <var>vardir</var> is the base directory for storing
4808 <prgn>dpkg</prgn> and <prgn>dselect</prgn>'s state, usually
4809 <tt>/var/lib/dpkg</tt>; this is passed in so that the
4810 <tt>--admindir</tt> option to <prgn>dselect</prgn> is
4815 Each option may have an extended description in
4816 <tt>desc.<var>option</var></tt>. This should be formatted
4817 like the extended description part of a <tt>Description</tt>
4818 field entry <em>shifted one character to the left</em>.
4822 <tt><var>vardir</var>/methods</tt> will exist, and a method
4824 <tt><var>vardir</var>/methods/<var>group</var></tt>
4825 directory to store its state.
4829 The group name and method name must follow the rules for C
4835 <chapt id="conversion"><heading>Conversion procedure from old
4840 This is a brief summary of the procedure for converting a
4841 pre-2.0.0.0-format source package into the new format.
4845 You are strongly advised to download and examine the <prgn>hello</prgn>
4846 package, and to read the section in the <prgn>dpkg</prgn> programmers'
4847 manual describing the source packaging tools. More detail about the
4848 exact functionality of these tools is available in
4849 <manref name="dpkg-source" section="1">.
4856 Download the original source code from wherever it can
4857 be found and do any rearrangement required to make it
4858 look like the original tree of the Debian source. Put
4860 <tt><var>package</var>-<var>upstream-version</var>.orig/</tt>
4862 <tt><var>package</var>_<var>upstream-version</var>.orig.tar.gz</tt>.
4868 Rename all files <tt>debian.*</tt> to <tt>debian/*</tt>.
4869 There may be some exceptions to this, but this is a good
4875 Edit the <tt>debian/changelog</tt> - create or rename it
4876 if necessary. Add a new revision to the top with the
4877 appropriate details, and a local variables entry to the
4878 bottom to set Emacs to the right mode:
4881 mode: debian-changelog
4889 Edit/create <tt>debian/control</tt>:
4890 <list compact="compact">
4893 Remove the <tt>Version</tt> field. If it is
4894 generated unusually (not equal to the source
4895 version) you must use the -v option to
4896 dpkg-gencontrol (see below). <tt>Section</tt>,
4897 <tt>Priority</tt>, <tt>Maintainer</tt> go above
4898 the first blank line, most of the rest
4905 Reorder the fields and add a blank line at an
4906 appropriate point, separating the source package
4907 fields from the binary package fields.
4912 <p>Add the <tt>Source</tt> field.</p></item>
4916 Add the <tt>Standards-Version</tt> field. (Please
4917 check out the Debian Policy Manual for details
4918 about this field.)</p>
4923 Change the <tt>Architecture</tt> field for each
4924 package to <tt>any</tt>, <tt>all</tt> or whatever.
4925 If there isn't an <tt>Architecture</tt> field add
4931 If any other use of sed or things used to happen
4932 to make the binary control files use
4933 <prgn>dpkg-gencontrol</prgn>'s variable
4934 substitution features to achieve the same effect.
4935 Use <tt>debian/substvars</tt> if you need to put
4936 unusally-generated information (apart from details
4937 of <tt>.deb</tt> files) in the <tt>.changes</tt>
4945 <p>Edit the <tt>debian/rules</tt>:
4946 <list compact="compact">
4949 Remove the <prgn>source</prgn> and
4950 <prgn>diff</prgn> and any <prgn>changes</prgn> and
4951 <prgn>dist</prgn> targets. These things now
4952 happen in a package-independent way and are not
4953 done by <tt>debian/rules</tt>.</p>
4957 Split the <prgn>binary</prgn> target into
4958 <prgn>binary-arch</prgn> and
4959 <prgn>binary-indep</prgn>; in many cases all of
4960 <prgn>binary</prgn> should go into
4961 <prgn>binary-arch</prgn>. Create the
4962 <prgn>binary</prgn> target and the unused of the
4963 two other <prgn>binary-*</prgn> targets if there
4964 is one - you can copy the ones from the
4965 <prgn>hello</prgn> package.</p>
4969 Change the <prgn>binary</prgn> target to use
4970 <prgn>dpkg-gencontrol</prgn> to make the package
4971 control file(s). Move it to after all the files
4972 have been installed but just before the last
4973 <prgn>chown</prgn> and <prgn>chmod</prgn> in the
4978 Change occurrences of <tt>debian-tmp</tt> to
4979 <tt>debian/tmp</tt>.</p>
4983 Change occurrences of
4984 <tt>debian.{post,pre}{inst,rm}</tt> to
4985 <tt>debian/*</tt>.</p>
4989 Remove the version number setting at the top, if
4994 Ensure that the package's Debian-specific and
4995 upstream changelogs are installed.</p>
5003 Change the package to use <prgn>dpkg-shlibdeps</prgn> to
5004 determine its shared library dependencies and substitute
5005 them in. Shared library dependencies should no longer
5006 be hardwired in the source package.</p>
5011 Check that the <tt>debian/README</tt> is really the
5012 copyright file, and if so rename it to
5013 <tt>debian/copyright</tt> and edit <tt>debian/rules</tt>
5014 to cope with this and to change the installation of the
5016 <tt>/usr/doc/<var>package</var>/copyright</tt> to
5017 <tt>/usr/doc/copyright/<var>package</var></tt>. If it
5018 isn't then find <tt>debian/copyright</tt> and decide
5019 what to do with the <tt>README</tt>.</p>
5023 <p>Check for various other anachronisms and problems:
5024 <list compact="compact">
5027 Remove any <tt>Package_Revision</tt>,
5028 <tt>Package-Revision</tt> or <tt>Revision</tt>
5033 Rename <tt>Optional</tt> to <tt>Suggests</tt>,
5034 <tt>Recommended</tt> to
5035 <tt>Recommends</tt>.</p>
5040 <tt>/usr/doc/examples/<var>package</var></tt> to
5041 <tt>/usr/doc/<var>package</var>/examples</tt>.</p>
5045 Make sure that manpages are installed
5050 Check that the description has an extended
5051 description, is well-formatted and meaningful and
5052 helpful to people wanting to know whether to
5053 install a package.</p>
5060 <p>Look everything over.</p></item>
5064 Do a test build using <tt>dpkg-buildpackage -us -uc -sa
5065 -r<var>whatever</var></tt>. Check the permissions and
5066 locations of files in the resulting package by examining
5067 the output of <tt>dpkg-deb --contents</tt>, and check
5068 that the source build happened OK. Test install the
5069 binary package(s) and test extract the source
5075 Sign the release: either rebuild everything with
5076 <tt>dpkg-buildpackage -sa</tt>, or PGP-sign the
5077 <tt>.dsc</tt>, rebuild the <tt>.changes</tt> using
5078 <tt>dpkg-genchanges -sa</tt>, and then PGP-sign the
5079 <tt>.changes</tt>.</p>
5086 The use of <tt>-sa</tt> on <prgn>dpkg-buildpackage</prgn> and
5087 <prgn>dpkg-genchanges</prgn> is important when doing the first
5088 build/uploading of a new-format source package. Unless this
5089 happens to be Debian revision <tt>0</tt> or <tt>1</tt> by
5090 default the original source tarfile will not be included in
5091 the uploaded files listed in the <tt>.changes</tt> file, and
5092 so it won't be installed on the FTP site. <tt>-sa</tt>
5093 requests that the original source be included