1 <!doctype debiandoc system[
2 <!-- include version information so we don't have to hard code it
3 within the document -->
4 <!entity % versiondata SYSTEM "version.ent"> %versiondata;
8 Debian GNU/Linux Packaging Manual.
9 Copyright (C)1996 Ian Jackson; released under the terms of the GNU
10 General Public License, version 2 or (at your option) any later.
11 Revised: David A. Morris (bweaver@debian.org)
12 Maintainer since 1998, Christian Schwarz <schwarz@debian.org>
18 <titlepag><title>Debian Packaging Manual</title>
20 <name>Ian Jackson </name>
21 <email>ijackson@gnu.ai.mit.edu</email>
24 <name>Revised: David A. Morris</name>
25 <email>bweaver@debian.org</email>
28 <name>Maintainer: Christian Schwarz </name>
29 <email>schwarz@debian.org</email>
32 <name>Maintainer: Manoj Srivastava </name>
33 <email>srivasta@debian.org</email>
36 <name>Maintainer: The Debian Policy group </name>
37 <email>debian-policy@lists.debian.org</email>
39 <version>version &version;, &date;</version>
42 This manual describes the technical aspects of creating Debian
43 binary and source packages. It also documents the interface
44 between <prgn>dselect</prgn> and its access method scripts.
45 It does not deal with the Debian Project policy requirements,
46 and it assumes familiarity with <prgn>dpkg</prgn>'s functions
47 from the system administrator's perspective. This
48 package itself is maintained by a group of maintainers
49 that have no editorial powers. At the moment, the list of
53 <p>Michael Alan Dorman <email>mdorman@debian.org</email></p>
56 <p>Richard Braakman <email>dark@xs4all.nl</email></p>
59 <p>Philip Hands <email>phil@hands.com</email></p>
62 <p>Manoj Srivastava <email>srivasta@debian.org</email></p>
69 <copyrightsummary>Copyright ©1996 Ian Jackson.</copyrightsummary>
71 This manual is free software; you may redistribute it and/or
72 modify it under the terms of the GNU General Public License
73 as published by the Free Software Foundation; either version
74 2, or (at your option) any later version.
78 This is distributed in the hope that it will be useful, but
79 <em>without any warranty</em>; without even the implied
80 warranty of merchantability or fitness for a particular
81 purpose. See the GNU General Public License for more
86 A copy of the GNU General Public License is available as
87 <tt>/usr/doc/copyright/GPL</tt> in the Debian GNU/Linux
88 distribution or on the World Wide Web at
89 <tt>http://www.gnu.org/copyleft/gpl.html</tt>. You can also
90 obtain it by writing to the Free Software Foundation, Inc.,
91 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
97 <!-- Describes the technical interface between a package and dpkg.
99 How to safely put shared libraries in a package. Details of
100 dpkg's handling of individual files. Sections on when to use
101 which feature (eg Replaces vs. Replaces/Conflicts
102 vs. update-alternatives vs. diversions) Cross-references to the
103 policy document (see below) where appropriate. Description of the
104 interface between dselect and its access methods. Hints on where
105 to start with a new package (ie, the hello package). What to do
110 Manpages are required for: update-rc.d, diversions,
111 update-alternatives, install-info in a package.
116 <heading>Introduction and scope of this manual</heading>
119 <prgn>dpkg</prgn> is a suite of programs for creating binary
120 package files and installing and removing them on Unix
123 <prgn>dpkg</prgn> is targetted primarily at Debian
124 GNU/Linux, but may work on or be ported to other
131 The binary packages are designed for the management of
132 installed executable programs (usually compiled binaries) and
133 their associated data, though source code examples and
134 documentation are provided as part of some packages.</p>
137 This manual describes the technical aspects of creating Debian
138 binary packages (<tt>.deb</tt> files). It documents the
139 behaviour of the package management programs
140 <prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and the way
141 they interact with packages.</p>
144 It also documents the interaction between
145 <prgn>dselect</prgn>'s core and the access method scripts it
146 uses to actually install the selected packages, and describes
147 how to create a new access method.</p>
150 This manual does not go into detail about the options and
151 usage of the package building and installation tools. It
152 should therefore be read in conjuction with those programs'
157 The utility programs which are provided with <prgn>dpkg</prgn>
158 for managing various system configuration and similar issues,
159 such as <prgn>update-rc.d</prgn> and
160 <prgn>install-info</prgn>, are not described in detail here -
161 please see their manpages.
165 It does <em>not</em> describe the policy requirements imposed
166 on Debian packages, such as the permissions on files and
167 directories, documentation requirements, upload procedure, and
168 so on. You should see the Debian packaging policy manual for
169 these details. (Many of them will probably turn out to be
170 helpful even if you don't plan to upload your package and make
171 it available as part of the distribution.)
175 It is assumed that the reader is reasonably familiar with the
176 <prgn>dpkg</prgn> System Administrators' manual.
177 Unfortunately this manual does not yet exist.
181 The Debian version of the FSF's GNU hello program is provided
182 as an example for people wishing to create Debian
183 packages. The Debian <prgn>debmake</prgn> package is
184 recommended as a very helpful tool in creating and maintaining
185 Debian packages. However, while the tools and examples are
186 helpful, they do not replace the need to read and follow the
187 Policy and Programmer's Manual.</p>
190 <chapt id="binarypkg"><heading>Binary packages
194 The binary package has two main sections. The first part
195 consists of various control information files and scripts used
196 by <prgn>dpkg</prgn> when installing and removing. See <ref
201 The second part is an archive containing the files and
202 directories to be installed.
206 In the future binary packages may also contain other
207 components, such as checksums and digital signatures. The
208 format for the archive is described in full in the
209 <tt>deb(5)</tt> manpage.
213 <sect id="bincreating"><heading>Creating package files -
214 <prgn>dpkg-deb</prgn>
218 All manipulation of binary package files is done by
219 <prgn>dpkg-deb</prgn>; it's the only program that has
220 knowledge of the format. (<prgn>dpkg-deb</prgn> may be
221 invoked by calling <prgn>dpkg</prgn>, as <prgn>dpkg</prgn>
222 will spot that the options requested are appropriate to
223 <prgn>dpkg-deb</prgn> and invoke that instead with the same
228 In order to create a binary package you must make a
229 directory tree which contains all the files and directories
230 you want to have in the filesystem data part of the package.
231 In Debian-format source packages this directory is usually
232 <tt>debian/tmp</tt>, relative to the top of the package's
237 They should have the locations (relative to the root of the
238 directory tree you're constructing) ownerships and
239 permissions which you want them to have on the system when
244 With current versions of <prgn>dpkg</prgn> the uid/username
245 and gid/groupname mappings for the users and groups being
246 used should be the same on the system where the package is
247 built and the one where it is installed.
251 You need to add one special directory to the root of the
252 miniature filesystem tree you're creating:
253 <prgn>DEBIAN</prgn>. It should contain the control
254 information files, notably the binary package control file
255 (see <ref id="controlfile">).
259 The <prgn>DEBIAN</prgn> directory will not appear in the
260 filesystem archive of the package, and so won't be installed
261 by <prgn>dpkg</prgn> when the package is installed.
265 When you've prepared the package, you should invoke:
267 dpkg --build <var>directory</var>
272 This will build the package in
273 <tt><var>directory</var>.deb</tt>. (<prgn>dpkg</prgn> knows
274 that <tt>--build</tt> is a <prgn>dpkg-deb</prgn> option, so
275 it invokes <prgn>dpkg-deb</prgn> with the same arguments to
280 See the manpage <manref name="dpkg-deb" section="8"> for details of how
281 to examine the contents of this newly-created file. You may find the
282 output of following commands enlightening:
284 dpkg-deb --info <var>filename</var>.deb
285 dpkg-deb --contents <var>filename</var>.deb
286 dpkg --contents <var>filename</var>.deb
288 To view the copyright file for a package you could use this command:
290 dpkg --fsys-tarfile <var>filename</var>.deb | tar xof usr/doc/<var>\*</var>copyright | less
295 <sect id="controlarea">
297 Package control information files
301 The control information portion of a binary package is a
302 collection of files with names known to <prgn>dpkg</prgn>.
303 It will treat the contents of these files specially - some
304 of them contain information used by <prgn>dpkg</prgn> when
305 installing or removing the package; others are scripts which
306 the package maintainer wants <prgn>dpkg</prgn> to run.
310 It is possible to put other files in the package control
311 area, but this is not generally a good idea (though they
312 will largely be ignored).
316 Here is a brief list of the control info files supported by
317 <prgn>dpkg</prgn> and a summary of what they're used for.
322 <tag><tt>control</tt>
326 This is the key description file used by
327 <prgn>dpkg</prgn>. It specifies the package's name
328 and version, gives its description for the user,
329 states its relationships with other packages, and so
330 forth. See <ref id="controlfile">.
334 It is usually generated automatically from information
335 in the source package by the
336 <prgn>dpkg-gencontrol</prgn> program, and with
337 assistance from <prgn>dpkg-shlibdeps</prgn>. See <ref
338 id="sourcetools">.</p>
341 <tag><tt>postinst</tt>, <tt>preinst</tt>, <tt>postrm</tt>,
347 These are exectuable files (usually scripts) which
348 <prgn>dpkg</prgn> runs during installation, upgrade
349 and removal of packages. They allow the package to
350 deal with matters which are particular to that package
351 or require more complicated processing than that
352 provided by <prgn>dpkg</prgn>. Details of when and
353 how they are called are in <ref
354 id="maintainerscripts">.
358 It is very important to make these scripts
362 That means that if it runs successfully or fails
363 and then you call it again it doesn't bomb out,
364 but just ensures that everything is the way it
367 </footnote> This is so that if an error occurs, the
368 user interrupts <prgn>dpkg</prgn> or some other
369 unforeseen circumstance happens you don't leave the
370 user with a badly-broken package.
374 The maintainer scripts are guaranteed to run with a
375 controlling terminal and can interact with the user.
376 If they need to prompt for passwords, do full-screen
377 interaction or something similar you should do these
378 things to and from <tt>/dev/tty</tt>, since
379 <prgn>dpkg</prgn> will at some point redirect scripts'
380 standard input and output so that it can log the
381 installation process. Likewise, because these scripts
382 may be executed with standard output redirected into a
383 pipe for logging purposes, Perl scripts should set
384 unbuffered output by setting <tt>$|=1</tt> so that the
385 output is printed immediately rather than being
390 Each script should return a zero exit status for
391 success, or a nonzero one for failure.</p>
394 <tag><tt>conffiles</tt>
399 This file contains a list of configuration files which
400 are to be handled automatically by <prgn>dpkg</prgn>
401 (see <ref id="conffiles">). Note that not necessarily
402 every configuration file should be listed here.</p>
410 This file contains a list of the shared libraries
411 supplied by the package, with dependency details for
412 each. This is used by <prgn>dpkg-shlibdeps</prgn>
413 when it determines what dependencies are required in a
414 package control file. The <tt>shlibs</tt> file format
415 is described on <ref id="shlibs">.
421 <sect id="controlfile">
423 The main control information file: <tt>control</tt>
426 The most important control information file used by
427 <prgn>dpkg</prgn> when it installs a package is
428 <tt>control</tt>. It contains all the package's `vital
433 The binary package control files of packages built from
434 Debian sources are made by a special tool,
435 <prgn>dpkg-gencontrol</prgn>, which reads
436 <tt>debian/control</tt> and <tt>debian/changelog</tt> to
437 find the information it needs. See <ref id="sourcepkg"> for
442 The fields in binary package control files are:
443 <list compact="compact">
445 <p><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</p>
448 <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
450 <item><p><qref id="f-Architecture"><tt>Architecture</tt></qref>
454 This field should appear in all packages, though
455 <prgn>dpkg</prgn> doesn't require it yet so that
456 old packages can still be installed.
462 <p><qref id="relationships"><tt>Depends</tt>,
463 <tt>Provides</tt> et al.</qref></p>
466 <p><qref id="f-Essential"><tt>Essential</tt></qref></p>
469 <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
472 <p><qref id="f-classification"><tt>Section</tt>,
473 <tt>Priority</tt></qref></p>
476 <p><qref id="f-Source"><tt>Source</tt></qref></p>
479 <p><qref id="descriptions"><tt>Description</tt></qref></p>
483 <qref id="f-Installed-Size"><tt>Installed-Size</tt></qref>
489 A description of the syntax of control files and the purpose
490 of these fields is available in <ref id="controlfields">.
494 <heading>Time Stamps</heading>
496 Maintainers are encouraged to preserve the modification
497 times of the upstream source files in a package, as far as
498 is reasonably possible.
501 The rationale is that there is some information conveyed
502 by knowing the age of the file, for example, you could
503 recognize that some documentation is very old by looking
504 at the modification time, so it would be nice if the
505 modification time of the upstream source would be
512 <chapt id="sourcepkg">
513 <heading>Source packages</heading>
516 The Debian binary packages in the distribution are generated
517 from Debian sources, which are in a special format to assist
518 the easy and automatic building of binaries.
522 There was a previous version of the Debian source format,
523 which is now being phased out. Instructions for converting an
524 old-style package are given in the Debian policy manual.
527 <sect id="sourcetools">
528 <heading>Tools for processing source packages</heading>
531 Various tools are provided for manipulating source packages;
532 they pack and unpack sources and help build of binary
533 packages and help manage the distribution of new versions.
537 They are introduced and typical uses described here; see
538 <manref name="dpkg-source" section="1"> for full
539 documentation about their arguments and operation.
543 For examples of how to construct a Debian source package,
544 and how to use those utilities that are used by Debian
545 source packages, please see the <prgn>hello</prgn> example
551 <prgn>dpkg-source</prgn> - packs and unpacks Debian source
556 This program is frequently used by hand, and is also
557 called from package-independent automated building scripts
558 such as <prgn>dpkg-buildpackage</prgn>.
562 To unpack a package it is typically invoked with
564 dpkg-source -x <var>.../path/to/filename</var>.dsc
569 with the <tt><var>filename</var>.tar.gz</tt> and
570 <tt><var>filename</var>.diff.gz</tt> (if applicable) in
571 the same directory. It unpacks into
572 <tt><var>package</var>-<var>version</var></tt>, and if
574 <tt><var>package</var>-<var>version</var>.orig</tt>, in
575 the current directory.
579 To create a packed source archive it is typically invoked:
581 dpkg-source -b <var>package</var>-<var>version</var>
586 This will create the <tt>.dsc</tt>, <tt>.tar.gz</tt> and
587 <tt>.diff.gz</tt> (if appropriate) in the current
588 directory. <prgn>dpkg-source</prgn> does not clean the
589 source tree first - this must be done separately if it is
594 See also <ref id="sourcearchives">.</p>
600 <prgn>dpkg-buildpackage</prgn> - overall package-building
605 <prgn>dpkg-buildpackage</prgn> is a script which invokes
606 <prgn>dpkg-source</prgn>, the <tt>debian/rules</tt>
607 targets <prgn>clean</prgn>, <prgn>build</prgn> and
608 <prgn>binary</prgn>, <prgn>dpkg-genchanges</prgn> and
609 <prgn>pgp</prgn> to build a signed source and binary
614 It is usually invoked by hand from the top level of the
615 built or unbuilt source directory. It may be invoked with
616 no arguments; useful arguments include:
617 <taglist compact="compact">
618 <tag><tt>-uc</tt>, <tt>-us</tt></tag>
621 Do not PGP-sign the <tt>.changes</tt> file or the
622 source package <tt>.dsc</tt> file, respectively.</p>
624 <tag><tt>-p<var>pgp-command</var></tt></tag>
627 Invoke <var>pgp-command</var> instead of finding
628 <tt>pgp</tt> on the <prgn>PATH</prgn>.
629 <var>pgp-command</var> must behave just like
630 <prgn>pgp</prgn>.</p>
632 <tag><tt>-r<var>root-command</var></tt></tag>
635 When root privilege is required, invoke the command
636 <var>root-command</var>. <var>root-command</var>
637 should invoke its first argument as a command, from
638 the <prgn>PATH</prgn> if necessary, and pass its
639 second and subsequent arguments to the command it
640 calls. If no <var>root-command</var> is supplied
641 then <var>dpkg-buildpackage</var> will take no
642 special action to gain root privilege, so that for
643 most packages it will have to be invoked as root to
646 <tag><tt>-b</tt>, <tt>-B</tt></tag>
649 Two types of binary-only build and upload - see
650 <manref name="dpkg-source" section="1">.
659 <prgn>dpkg-gencontrol</prgn> - generates binary package
664 This program is usually called from <tt>debian/rules</tt>
665 (see <ref id="sourcetree">) in the top level of the source
670 This is usually done just before the files and directories in the
671 temporary directory tree where the package is being built have their
672 permissions and ownerships set and the package is constructed using
673 <prgn>dpkg-deb/</prgn>
676 This is so that the control file which is produced has
677 the right permissions
683 <prgn>dpkg-gencontrol</prgn> must be called after all the
684 files which are to go into the package have been placed in
685 the temporary build directory, so that its calculation of
686 the installed size of a package is correct.
690 It is also necessary for <prgn>dpkg-gencontrol</prgn> to
691 be run after <prgn>dpkg-shlibdeps</prgn> so that the
692 variable substitutions created by
693 <prgn>dpkg-shlibdeps</prgn> in <tt>debian/substvars</tt>
698 For a package which generates only one binary package, and
699 which builds it in <tt>debian/tmp</tt> relative to the top
700 of the source package, it is usually sufficient to call
701 <prgn>dpkg-gencontrol</prgn>.
705 Sources which build several binaries will typically need
708 dpkg-gencontrol -Pdebian/tmp-<var>pkg</var> -p<var>package</var>
709 </example> The <tt>-P</tt> tells
710 <prgn>dpkg-gencontrol</prgn> that the package is being
711 built in a non-default directory, and the <tt>-p</tt>
712 tells it which package's control file should be generated.
716 <prgn>dpkg-gencontrol</prgn> also adds information to the
717 list of files in <tt>debian/files</tt>, for the benefit of
718 (for example) a future invocation of
719 <prgn>dpkg-genchanges</prgn>.</p>
724 <prgn>dpkg-shlibdeps</prgn> - calculates shared library
729 This program is usually called from <tt>debian/rules</tt>
730 just before <prgn>dpkg-gencontrol</prgn> (see <ref
731 id="sourcetree">), in the top level of the source tree.
735 Its arguments are executables
738 They may be specified either in the locations in the
739 source tree where they are created or in the locations
740 in the temporary build tree where they are installed
741 prior to binary package creation.
743 </footnote> for which shared library dependencies should
744 be included in the binary package's control file.
748 If some of the executable(s) shared libraries should only
749 warrant a <tt>Recommends</tt> or <tt>Suggests</tt>, or if
750 some warrant a <tt>Pre-Depends</tt>, this can be achieved
751 by using the <tt>-d<var>dependency-field</var></tt> option
752 before those executable(s). (Each <tt>-d</tt> option
753 takes effect until the next <tt>-d</tt>.)
757 <prgn>dpkg-shlibdeps</prgn> does not directly cause the
758 output control file to be modified. Instead by default it
759 adds to the <tt>debian/substvars</tt> file variable
760 settings like <tt>shlibs:Depends</tt>. These variable
761 settings must be referenced in dependency fields in the
762 appropriate per-binary-package sections of the source
767 For example, the <prgn>procps</prgn> package generates two
768 kinds of binaries, simple C binaries like <prgn>ps</prgn>
769 which require a predependency and full-screen ncurses
770 binaries like <prgn>top</prgn> which require only a
771 recommendation. It can say in its <tt>debian/rules</tt>:
773 dpkg-shlibdeps -dPre-Depends ps -dRecommends top
775 and then in its main control file <tt>debian/control</tt>:
779 Pre-Depends: ${shlibs:Pre-Depends}
780 Recommends: ${shlibs:Recommends}
786 Sources which produce several binary packages with
787 different shared library dependency requirements can use
788 the <tt>-p<var>varnameprefix</var></tt> option to override
789 the default <tt>shlib:</tt> prefix (one invocation of
790 <prgn>dpkg-shlibdeps</prgn> per setting of this option).
791 They can thus produce several sets of dependency
792 variables, each of the form
793 <tt><var>varnameprefix</var>:<var>dependencyfield</var></tt>,
794 which can be referred to in the appropriate parts of the
795 binary package control files.
802 <prgn>dpkg-distaddfile</prgn> - adds a file to
803 <tt>debian/files</tt>
807 Some packages' uploads need to include files other than
808 the source and binary package files.
812 <prgn>dpkg-distaddfile</prgn> adds a file to the
813 <tt>debian/files</tt> file so that it will be included in
814 the <tt>.changes</tt> file when
815 <prgn>dpkg-genchanges</prgn> is run.
819 It is usually invoked from the <prgn>binary</prgn> target of
820 <tt>debian/rules</tt>:
822 dpkg-distaddfile <var>filename</var> <var>section</var> <var>priority</var>
824 The <var>filename</var> is relative to the directory where
825 <prgn>dpkg-genchanges</prgn> will expect to find it - this
826 is usually the directory above the top level of the source
827 tree. The <tt>debian/rules</tt> target should put the
828 file there just before or just after calling
829 <prgn>dpkg-distaddfile</prgn>.
833 The <var>section</var> and <var>priority</var> are passed
834 unchanged into the resulting <tt>.changes</tt> file. See
835 <ref id="f-classification">.
840 <sect1><heading><prgn>dpkg-genchanges</prgn> - generates a <tt>.changes</tt> upload
845 This program is usually called by package-independent
846 automatic building scripts such as
847 <prgn>dpkg-buildpackage</prgn>, but it may also be called
852 It is usually called in the top level of a built source
853 tree, and when invoked with no arguments will print out a
854 straightforward <tt>.changes</tt> file based on the
855 information in the source package's changelog and control
856 file and the binary and source packages which should have
862 <sect1><heading><prgn>dpkg-parsechangelog</prgn> - produces parsed representation of
867 This program is used internally by
868 <prgn>dpkg-source</prgn> et al. It may also occasionally
869 be useful in <tt>debian/rules</tt> and elsewhere. It
870 parses a changelog, <tt>debian/changelog</tt> by default,
871 and prints a control-file format representation of the
872 information in it to standard output.
876 <sect1 id="dpkgarch"><heading><prgn>dpkg-architecture</prgn> -
877 information about the build and host system
881 This program can be used manually, but is also invoked by
882 <tt>dpkg-buildpackage</tt> or <tt>debian/rules</tt> to set
883 to set environment or make variables which specify the build and
884 host architecture for the package building process.
889 <sect id="sourcetree"><heading>The Debianised source tree
893 The source archive scheme described later is intended to
894 allow a Debianised source tree with some associated control
895 information to be reproduced and transported easily. The
896 Debianised source tree is a version of the original program
897 with certain files added for the benefit of the
898 Debianisation process, and with any other changes required
899 made to the rest of the source code and installation
904 The extra files created for Debian are in the subdirectory
905 <tt>debian</tt> of the top level of the Debianised source
906 tree. They are described below.
909 <sect1 id="debianrules"><heading><tt>debian/rules</tt> - the main building
914 This file is an executable makefile, and contains the
915 package-specific recipies for compiling the package and
916 building binary package(s) out of the source.
920 It must start with the line <tt>#!/usr/bin/make -f</tt>,
921 so that it can be invoked by saying its name rather than
922 invoking <prgn>make</prgn> explicitly.
926 Since an interactive <tt>debian/rules</tt> script makes it
927 impossible to autocompile that package and also makes it
928 hard for other people to reproduce the same binary
929 package, all <strong>required targets</strong> have to be
930 non-interactive. At a minimul, required targets are the
931 ones called by <prgn>dpkg-buildpackage</prgn>, namely,
932 <em>clean</em>, <em>binary</em>, <em>binary-arch</em>, and
933 <em>build</em>. It also follows that any target that these
934 targets depend on must also be non-interactive.
938 The targets which are required to be present are:
940 <tag><tt>build</tt></tag>
943 This should perform all non-interactive
944 configuration and compilation of the package. If a
945 package has an interactive pre-build configuration
946 routine, the Debianised source package should be
947 built after this has taken place, so that it can be
948 built without rerunning the configuration.
952 For some packages, notably ones where the same
953 source tree is compiled in different ways to produce
954 two binary packages, the <prgn>build</prgn> target
955 does not make much sense. For these packages it is
956 good enough to provide two (or more) targets
957 (<tt>build-a</tt> and <tt>build-b</tt> or whatever)
958 for each of the ways of building the package, and a
959 <prgn>build</prgn> target that does nothing. The
960 <prgn>binary</prgn> target will have to build the
961 package in each of the possible ways and make the
962 binary package out of each.
966 The <prgn>build</prgn> target must not do anything
967 that might require root privilege.
971 The <prgn>build</prgn> target may need to run
972 <prgn>clean</prgn> first - see below.
976 When a package has a configuration routine that
977 takes a long time, or when the makefiles are poorly
978 designed, or when <prgn>build</prgn> needs to run
979 <prgn>clean</prgn> first, it is a good idea to
980 <tt>touch build</tt> when the build process is
981 complete. This will ensure that if <tt>debian/rules
982 build</tt> is run again it will not rebuild the
987 <tag><tt>binary</tt>, <tt>binary-arch</tt>,
988 <tt>binary-indep</tt>
992 The <prgn>binary</prgn> target should be all that is
993 necessary for the user to build the binary
994 package. All these targets are required to be
995 non-interactive. It is split into two parts:
996 <prgn>binary-arch</prgn> builds the packages' output
997 files which are specific to a particular
998 architecture, and <prgn>binary-indep</prgn> builds
1003 <prgn>binary</prgn> should usually be a target with
1004 no commands which simply depends on
1005 <prgn>binary-arch</prgn> and
1006 <prgn>binary-indep</prgn>.
1010 Both <prgn>binary-*</prgn> targets should depend on
1011 the <prgn>build</prgn> target, above, so that the
1012 package is built if it has not been already. It
1013 should then create the relevant binary package(s),
1014 using <prgn>dpkg-gencontrol</prgn> to make their
1015 control files and <prgn>dpkg-deb</prgn> to build
1016 them and place them in the parent of the top level
1021 If one of the <prgn>binary-*</prgn> targets has
1022 nothing to do (this will be always be the case if
1023 the source generates only a single binary package,
1024 whether architecture-dependent or not) it
1025 <em>must</em> still exist, but should always
1030 <ref id="binarypkg"> describes how to construct
1035 The <prgn>binary</prgn> targets must be invoked as
1040 <tag><tt>clean</tt></tag>
1044 This should undo any effects that the
1045 <prgn>build</prgn> and <prgn>binary</prgn> targets
1046 may have had, except that it should leave alone any
1047 output files created in the parent directory by a
1048 run of <prgn>binary</prgn>. This target is required
1049 to be non-interactive.
1053 If a <prgn>build</prgn> file is touched at the end
1054 of the <prgn>build</prgn> target, as suggested
1055 above, it must be removed as the first thing that
1056 <prgn>clean</prgn> does, so that running
1057 <prgn>build</prgn> again after an interrupted
1058 <prgn>clean</prgn> doesn't think that everything is
1063 The <prgn>clean</prgn> target must be invoked as
1064 root if <prgn>binary</prgn> has been invoked since
1065 the last <prgn>clean</prgn>, or if
1066 <prgn>build</prgn> has been invoked as root (since
1067 <prgn>build</prgn> may create directories, for
1072 <tag><tt>get-orig-source</tt> (optional)</tag>
1076 This target fetches the most recent version of the
1077 original source package from a canonical archive
1078 site (via FTP or WWW, for example), does any
1079 necessary rearrangement to turn it into the original
1080 source tarfile format described below, and leaves it
1081 in the current directory.
1085 This target may be invoked in any directory, and
1086 should take care to clean up any temporary files it
1091 This target is optional, but providing it if
1092 possible is a good idea.
1098 The <prgn>build</prgn>, <prgn>binary</prgn> and
1099 <prgn>clean</prgn> targets must be invoked with a current
1100 directory of the package's top-level directory.
1105 Additional targets may exist in <tt>debian/rules</tt>,
1106 either as published or undocumented interfaces or for the
1107 package's internal use.
1111 The architecture we build on and build for is determined by make
1112 variables via dpkg-architecture (see <ref id="dpkgarch">). You can
1113 get the Debian architecture and the GNU style architecture
1114 specification string for the build machine as well as the host
1115 machine. Here is a list of supported make variables:
1116 <list compact="compact">
1118 <p><tt>DEB_*_ARCH</tt> (the Debian architecture)</p>
1121 <p><tt>DEB_*_GNU_TYPE</tt> (the GNU style architecture
1122 specification string)</p>
1125 <p><tt>DEB_*_GNU_CPU</tt> (the CPU part of DEB_*_GNU_TYPE)</p>
1128 <p><tt>DEB_*_GNU_SYSTEM</tt> (the System part of
1134 where <tt>*</tt> is either <tt>BUILD</tt> for specification of
1135 the build machine or <tt>HOST</tt> for specification of the machine
1140 Backward compatibility can be provided in the rules file
1141 by setting the needed variables to suitable default
1142 values, please refer to the documentation of
1143 dpkg-architecture for details.
1147 It is important to understand that the <tt>DEB_*_ARCH</tt>
1148 string does only determine which Debian architecture we
1149 build on resp. for. It should not be used to get the CPU
1150 or System information, the GNU style variables should be
1156 <sect1><heading><tt>debian/control</tt>
1160 This file contains version-independent details about the
1161 source package and about the binary packages it creates.
1165 It is a series of sets of control fields, each
1166 syntactically similar to a binary package control file.
1167 The sets are separated by one or more blank lines. The
1168 first set is information about the source package in
1169 general; each subsequent set describes one binary package
1170 that the source tree builds.
1174 The syntax and semantics of the fields are described below
1175 in <ref id="controlfields">.
1179 The general (binary-package-independent) fields are:
1180 <list compact="compact">
1182 <p><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</p>
1185 <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
1189 <qref id="f-classification"><tt>Section</tt> and
1190 <tt>Priority</tt></qref>
1191 (classification, mandatory)
1196 <qref id="f-Standards-Version"><tt>Standards-Version</tt></qref>
1202 The per-binary-package fields are:
1203 <list compact="compact">
1205 <p><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</p>
1209 <qref id="f-Architecture"><tt>Architecture</tt></qref>
1213 <p><qref id="descriptions"><tt>Description</tt></qref></p>
1217 <qref id="f-classification"><tt>Section</tt> and
1218 <tt>Priority</tt></qref> (classification)</p>
1221 <p><qref id="f-Essential"><tt>Essential</tt></qref></p>
1225 <qref id="relationships"><tt>Depends</tt> et
1226 al.</qref> (package interrelationships)
1232 These fields are used by <prgn>dpkg-gencontrol</prgn> to
1233 generate control files for binary packages (see below), by
1234 <prgn>dpkg-genchanges</prgn> to generate the
1235 <tt>.changes</tt> file to accompany the upload, and by
1236 <prgn>dpkg-source</prgn> when it creates the <tt>.dsc</tt>
1237 source control file as part of a source archive.
1241 The fields here may contain variable references - their
1242 values will be substituted by
1243 <prgn>dpkg-gencontrol</prgn>, <prgn>dpkg-genchanges</prgn>
1244 or <prgn>dpkg-source</prgn> when they generate output
1245 control files. See <ref id="srcsubstvars"> for details.
1248 <p> <sect2><heading>User-defined fields
1252 Additional user-defined fields may be added to the
1253 source package control file. Such fields will be
1254 ignored, and not copied to (for example) binary or
1255 source package control files or upload control files.
1259 If you wish to add additional unsupported fields to
1260 these output files you should use the mechanism
1265 Fields in the main source control information file with
1266 names starting <tt>X</tt>, followed by one or more of
1267 the letters <tt>BCS</tt> and a hyphen <tt>-</tt>, will
1268 be copied to the output files. Only the part of the
1269 field name after the hyphen will be used in the output
1270 file. Where the letter <tt>B</tt> is used the field
1271 will appear in binary package control files, where the
1272 letter <tt>S</tt> is used in source package control
1273 files and where <tt>C</tt> is used in upload control
1274 (<tt>.changes</tt>) files.
1278 For example, if the main source information control file
1281 XBS-Comment: I stand between the candle and the star.
1283 then the binary and source package control files will contain the
1286 Comment: I stand between the candle and the star.
1293 <sect1 id="dpkgchangelog"><heading><tt>debian/changelog</tt>
1297 This file records the changes to the Debian-specific parts of the
1301 Though there is nothing stopping an author who is also
1302 the Debian maintainer from using it for all their
1303 changes, it will have to be renamed if the Debian and
1304 upstream maintainers become different
1311 It has a special format which allows the package building
1312 tools to discover which version of the package is being
1313 built and find out other release-specific information.
1317 That format is a series of entries like this:
1319 <var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
1321 * <var>change details</var>
1322 <var>more change details</var>
1323 * <var>even more change details</var>
1325 -- <var>maintainer name and email address</var> <var>date</var>
1330 <var>package</var> and <var>version</var> are the source
1331 package name and version number.
1335 <var>distribution(s)</var> lists the distributions where
1336 this version should be installed when it is uploaded - it
1337 is copied to the <tt>Distribution</tt> field in the
1338 <tt>.changes</tt> file. See <ref id="f-Distribution">.
1342 <var>urgency</var> is the value for the <tt>Urgency</tt>
1343 field in the <tt>.changes</tt> file for the upload. See
1344 <ref id="f-Urgency">. It is not possible to specify an
1345 urgency containing commas; commas are used to separate
1346 <tt><var>keyword</var>=<var>value</var></tt> settings in
1347 the <prgn>dpkg</prgn> changelog format (though there is
1348 currently only one useful <var>keyword</var>,
1353 The change details may in fact be any series of lines
1354 starting with at least two spaces, but conventionally each
1355 change starts with an asterisk and a separating space and
1356 continuation lines are indented so as to bring them in
1357 line with the start of the text above. Blank lines may be
1358 used here to separate groups of changes, if desired.
1362 The maintainer name and email address should <em>not</em>
1363 necessarily be those of the usual package maintainer.
1364 They should be the details of the person doing
1365 <em>this</em> version. The information here will be
1366 copied to the <tt>.changes</tt> file, and then later used
1367 to send an acknowledgement when the upload has been
1372 The <var>date</var> should be in RFC822 format
1375 This is generated by the <prgn>822-date</prgn>
1378 </footnote>; it should include the timezone specified
1379 numerically, with the timezone name or abbreviation
1380 optionally present as a comment.
1384 The first `title' line with the package name should start
1385 at the left hand margin; the `trailer' line with the
1386 maintainer and date details should be preceded by exactly
1387 one space. The maintainer details and the date must be
1388 separated by exactly two spaces.
1392 An Emacs mode for editing this format is available: it is
1393 called <tt>debian-changelog-mode</tt>. You can have this
1394 mode selected automatically when you edit a Debian
1395 changelog by adding a local variables clause to the end of
1399 <sect2><heading>Defining alternative changelog formats
1403 It is possible to use a different format to the standard
1404 one, by providing a parser for the format you wish to
1409 In order to have <tt>dpkg-parsechangelog</tt> run your
1410 parser, you must include a line within the last 40 lines
1411 of your file matching the Perl regular expression:
1412 <tt>\schangelog-format:\s+([0-9a-z]+)\W</tt> The part in
1413 parentheses should be the name of the format. For
1414 example, you might say:
1416 @@@ changelog-format: joebloggs @@@
1418 Changelog format names are non-empty strings of alphanumerics.
1422 If such a line exists then <tt>dpkg-parsechangelog</tt>
1423 will look for the parser as
1424 <tt>/usr/lib/dpkg/parsechangelog/<var>format-name</var></tt>
1426 <tt>/usr/local/lib/dpkg/parsechangelog/<var>format-name</var></tt>;
1427 it is an error for it not to find it, or for it not to
1428 be an executable program. The default changelog format
1429 is <tt>dpkg</tt>, and a parser for it is provided with
1430 the <tt>dpkg</tt> package.
1434 The parser will be invoked with the changelog open on
1435 standard input at the start of the file. It should read
1436 the file (it may seek if it wishes) to determine the
1437 information required and return the parsed information
1438 to standard output in the form of a series of control
1439 fields in the standard format. By default it should
1440 return information about only the most recent version in
1441 the changelog; it should accept a
1442 <tt>-v<var>version</var></tt> option to return changes
1443 information from all versions present <em>strictly
1444 after</em> <var>version</var>, and it should then be an
1445 error for <var>version</var> not to be present in the
1451 <list compact="compact">
1453 <p><qref id="f-Source"><tt>Source</tt></qref></p>
1456 <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
1460 <qref id="f-Distribution"><tt>Distribution</tt></qref>
1465 <p><qref id="f-Urgency"><tt>Urgency</tt></qref> (mandatory)</p>
1469 <qref id="f-Maintainer"><tt>Maintainer</tt></qref>
1474 <p><qref id="f-Date"><tt>Date</tt></qref></p>
1478 <qref id="f-Changes"><tt>Changes</tt></qref>
1485 If several versions are being returned (due to the use
1486 of <tt>-v</tt>), the urgency value should be of the
1487 highest urgency code listed at the start of any of the
1488 versions requested followed by the concatenated
1489 (space-separated) comments from all the versions
1490 requested; the maintainer, version, distribution and
1491 date should always be from the most recent version.
1495 For the format of the <tt>Changes</tt> field see <ref
1500 If the changelog format which is being parsed always or
1501 almost always leaves a blank line between individual
1502 change notes these blank lines should be stripped out,
1503 so as to make the resulting output compact.
1507 If the changelog format does not contain date or package
1508 name information this information should be omitted from
1509 the output. The parser should not attempt to synthesise
1510 it or find it from other sources.
1514 If the changelog does not have the expected format the
1515 parser should exit with a nonzero exit status, rather
1516 than trying to muddle through and possibly generating
1521 A changelog parser may not interact with the user at
1525 <sect1 id="srcsubstvars"><heading><tt>debian/substvars</tt>
1526 and variable substitutions
1530 When <prgn>dpkg-gencontrol</prgn>,
1531 <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
1532 generate control files they do variable substitutions on
1533 their output just before writing it. Variable
1534 substitutions have the form
1535 <tt>${<var>variable-name</var>}</tt>. The optional file
1536 <tt>debian/substvars</tt> contains variable substitutions
1537 to be used; variables can also be set directly from
1538 <tt>debian/rules</tt> using the <tt>-V</tt> option to the
1539 source packaging commands, and certain predefined
1540 variables are available.
1544 The is usually generated and modified dynamically by
1545 <tt>debian/rules</tt> targets; in this case it must be
1546 removed by the <prgn>clean</prgn> target.
1550 See <manref name="dpkg-source" section="1"> for full
1551 details about source variable substitutions, including the
1552 format of <tt>debian/substvars</tt>.</p>
1555 <sect1><heading><tt>debian/files</tt>
1559 This file is not a permanent part of the source tree; it
1560 is used while building packages to record which files are
1561 being generated. <prgn>dpkg-genchanges</prgn> uses it
1562 when it generates a <tt>.changes</tt> file.
1566 It should not exist in a shipped source package, and so it
1567 (and any backup files or temporary files such as
1571 <tt>files.new</tt> is used as a temporary file by
1572 <prgn>dpkg-gencontrol</prgn> and
1573 <prgn>dpkg-distaddfile</prgn> - they write a new
1574 version of <tt>files</tt> here before renaming it,
1575 to avoid leaving a corrupted copy if an error
1578 </footnote>) should be removed by the
1579 <prgn>clean</prgn> target. It may also be wise to
1580 ensure a fresh start by emptying or removing it at the
1581 start of the <prgn>binary</prgn> target.
1585 <prgn>dpkg-gencontrol</prgn> adds an entry to this file
1586 for the <tt>.deb</tt> file that will be created by
1587 <prgn>dpkg-deb</prgn> from the control file that it
1588 generates, so for most packages all that needs to be done
1589 with this file is to delete it in <prgn>clean</prgn>.
1593 If a package upload includes files besides the source
1594 package and any binary packages whose control files were
1595 made with <prgn>dpkg-gencontrol</prgn> then they should be
1596 placed in the parent of the package's top-level directory
1597 and <prgn>dpkg-distaddfile</prgn> should be called to add
1598 the file to the list in <tt>debian/files</tt>.</p>
1601 <sect1><heading><tt>debian/tmp</tt>
1605 This is the canonical temporary location for the
1606 construction of binary packages by the <prgn>binary</prgn>
1607 target. The directory <tt>tmp</tt> serves as the root of
1608 the filesystem tree as it is being constructed (for
1609 example, by using the package's upstream makefiles install
1610 targets and redirecting the output there), and it also
1611 contains the <tt>DEBIAN</tt> subdirectory. See <ref
1616 If several binary packages are generated from the same
1617 source tree it is usual to use several
1618 <tt>debian/tmp<var>something</var></tt> directories, for
1619 example <tt>tmp-a</tt> or <tt>tmp-doc</tt>.
1623 Whatever <tt>tmp</tt> directories are created and used by
1624 <prgn>binary</prgn> must of course be removed by the
1625 <prgn>clean</prgn> target.</p></sect1>
1629 <sect id="sourcearchives"><heading>Source packages as archives
1633 As it exists on the FTP site, a Debian source package
1634 consists of three related files. You must have the right
1635 versions of all three to be able to use them.
1640 <tag>Debian source control file - <tt>.dsc</tt></tag>
1644 This file contains a series of fields, identified and
1645 separated just like the fields in the control file of
1646 a binary package. The fields are listed below; their
1647 syntax is described above, in <ref id="controlfields">.
1648 <list compact="compact">
1650 <p><qref id="f-Source"><tt>Source</tt></qref></p>
1653 <p><qref id="versions"><tt>Version</tt></qref></p>
1656 <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
1659 <p><qref id="f-Binary"><tt>Binary</tt></qref></p>
1662 <p><qref id="f-Architecture"><tt>Architecture</tt></qref></p>
1666 <qref id="f-Standards-Version"><tt>Standards-Version</tt></qref></p>
1669 <p><qref id="f-Files"><tt>Files</tt></qref></p>
1674 The source package control file is generated by
1675 <prgn>dpkg-source</prgn> when it builds the source
1676 archive, from other files in the source package,
1677 described above. When unpacking it is checked against
1678 the files and directories in the other parts of the
1679 source package, as described below.</p>
1683 Original source archive -
1685 <var>package</var>_<var>upstream-version</var>.orig.tar.gz
1692 This is a compressed (with <tt>gzip -9</tt>)
1693 <prgn>tar</prgn> file containing the source code from
1694 the upstream authors of the program. The tarfile
1695 unpacks into a directory
1696 <tt><var>package</var>-<var>upstream-version</var>.orig</tt>,
1697 and does not contain files anywhere other than in
1698 there or in its subdirectories.</p>
1702 Debianisation diff -
1704 <var>package</var>_<var>upstream_version-revision</var>.diff.gz
1710 This is a unified context diff (<tt>diff -u</tt>)
1711 giving the changes which are required to turn the
1712 original source into the Debian source. These changes
1713 may only include editing and creating plain files.
1714 The permissions of files, the targets of symbolic
1715 links and the characteristics of special files or
1716 pipes may not be changed and no files may be removed
1721 All the directories in the diff must exist, except the
1722 <tt>debian</tt> subdirectory of the top of the source
1723 tree, which will be created by
1724 <prgn>dpkg-source</prgn> if necessary when unpacking.
1728 The <prgn>dpkg-source</prgn> program will
1729 automatically make the <tt>debian/rules</tt> file
1730 executable (see below).</p></item>
1735 If there is no original source code - for example, if the
1736 package is specially prepared for Debian or the Debian
1737 maintainer is the same as the upstream maintainer - the
1738 format is slightly different: then there is no diff, and the
1740 <tt><var>package</var>_<var>version</var>.tar.gz</tt> and
1741 contains a directory
1742 <tt><var>package</var>-<var>version</var></tt>.
1746 <sect><heading>Unpacking a Debian source package without
1747 <prgn>dpkg-source</prgn>
1751 <tt>dpkg-source -x</tt> is the recommended way to unpack a
1752 Debian source package. However, if it is not available it
1753 is possible to unpack a Debian source archive as follows:
1754 <enumlist compact="compact">
1757 Untar the tarfile, which will create a <tt>.orig</tt>
1761 <p>Rename the <tt>.orig</tt> directory to
1762 <tt><var>package</var>-<var>version</var></tt>.</p>
1766 Create the subdirectory <tt>debian</tt> at the top of
1767 the source tree.</p>
1769 <item><p>Apply the diff using <tt>patch -p0</tt>.</p>
1771 <item><p>Untar the tarfile again if you want a copy of the original
1772 source code alongside the Debianised version.</p>
1777 It is not possible to generate a valid Debian source archive
1778 without using <prgn>dpkg-source</prgn>. In particular,
1779 attempting to use <prgn>diff</prgn> directly to generate the
1780 <tt>.diff.gz</tt> file will not work.
1783 <sect1><heading>Restrictions on objects in source packages
1787 The source package may not contain any hard links
1790 This is not currently detected when building source
1791 packages, but only when extracting
1797 Hard links may be permitted at some point in the
1798 future, but would require a fair amount of
1801 </footnote>, device special files, sockets or setuid or
1805 Setgid directories are allowed.
1811 The source packaging tools manage the changes between the
1812 original and Debianised source using <prgn>diff</prgn> and
1813 <prgn>patch</prgn>. Turning the original source tree as
1814 included in the <tt>.orig.tar.gz</tt> into the debianised
1815 source must not involve any changes which cannot be
1816 handled by these tools. Problematic changes which cause
1817 <prgn>dpkg-source</prgn> to halt with an error when
1818 building the source package are:
1819 <list compact="compact">
1820 <item><p>Adding or removing symbolic links, sockets or pipes.</p>
1822 <item><p>Changing the targets of symbolic links.</p>
1824 <item><p>Creating directories, other than <tt>debian</tt>.</p>
1826 <item><p>Changes to the contents of binary files.</p></item>
1827 </list> Changes which cause <prgn>dpkg-source</prgn> to
1828 print a warning but continue anyway are:
1829 <list compact="compact">
1832 Removing files, directories or symlinks.
1835 Renaming a file is not treated specially - it is
1836 seen as the removal of the old file (which
1837 generates a warning, but is otherwise ignored),
1838 and the creation of the new
1845 Changed text files which are missing the usual final
1846 newline (either in the original or the modified
1851 Changes which are not represented, but which are not detected by
1852 <prgn>dpkg-source</prgn>, are:
1853 <list compact="compact">
1854 <item><p>Changing the permissions of files (other than
1855 <tt>debian/rules</tt>) and directories.</p></item>
1860 The <tt>debian</tt> directory and <tt>debian/rules</tt>
1861 are handled specially by <prgn>dpkg-source</prgn> - before
1862 applying the changes it will create the <tt>debian</tt>
1863 directory, and afterwards it will make
1864 <tt>debian/rules</tt> world-exectuable.
1870 <chapt id="controlfields"><heading>Control files and their fields
1874 Many of the tools in the <prgn>dpkg</prgn> suite manipulate
1875 data in a common format, known as control files. Binary and
1876 source packages have control data as do the <tt>.changes</tt>
1877 files which control the installation of uploaded files, and
1878 <prgn>dpkg</prgn>'s internal databases are in a similar
1882 <sect><heading>Syntax of control files
1886 A file consists of one or more paragraphs of fields. The
1887 paragraphs are separated by blank lines. Some control files
1888 only allow one paragraph; others allow several, in which
1889 case each paragraph often refers to a different package.
1893 Each paragraph is a series of fields and values; each field
1894 consists of a name, followed by a colon and the value. It
1895 ends at the end of the line. Horizontal whitespace (spaces
1896 and tabs) may occur before or after the value and is ignored
1897 there; it is conventional to put a single space after the
1902 Some fields' values may span several lines; in this case
1903 each continuation line <em>must</em> start with a space or
1904 tab. Any trailing spaces or tabs at the end of individual
1905 lines of a field value are ignored.
1909 Except where otherwise stated only a single line of data is
1910 allowed and whitespace is not significant in a field body.
1911 Whitespace may never appear inside names (of packages,
1912 architectures, files or anything else), version numbers or
1913 in between the characters of multi-character version
1918 Field names are not case-sensitive, but it is usual to
1919 capitalise the fields using mixed case as shown below.
1923 Blank lines, or lines consisting only of spaces and tabs,
1924 are not allowed within field values or between fields - that
1925 would mean a new paragraph.
1929 It is important to note that there are several fields which
1930 are optional as far as <prgn>dpkg</prgn> and the related
1931 tools are concerned, but which must appear in every Debian
1932 package, or whose omission may cause problems. When writing
1933 the control files for Debian packages you <em>must</em> read
1934 the Debian policy manual in conjuction with the details
1935 below and the list of fields for the particular file.</p>
1938 <sect><heading>List of fields
1941 <sect1 id="f-Package"><heading><tt>Package</tt>
1945 The name of the binary package. Package names consist of
1946 the alphanumerics and <tt>+</tt> <tt>-</tt> <tt>.</tt>
1947 (plus, minus and full stop).
1950 The characters <tt>@</tt> <tt>:</tt> <tt>=</tt>
1951 <tt>t</tt>t> <tt>_</tt> (at, colon, equals, percent
1952 and underscore) used to be legal and are still
1953 accepted when found in a package file, but may not be
1954 used in new packages
1960 They must be at least two characters and must start with
1961 an alphanumeric. In current versions of dpkg they are
1962 sort of case-sensitive<footnote><p>This is a
1963 bug.</p></footnote>; use lowercase package names unless
1964 the package you're building (or referring to, in other
1965 fields) is already using uppercase.</p>
1968 <sect1 id="f-Version"><heading><tt>Version</tt>
1972 This lists the source or binary package's version number -
1973 see <ref id="versions">.
1978 <sect1 id="f-Architecture"><heading><tt>Architecture</tt>
1982 This is the architecture string; it is a single word for
1983 the Debian architecture.
1987 <prgn>dpkg</prgn> will check the declared architecture of
1988 a binary package against its own compiled-in value before
1993 The special value <tt>all</tt> indicates that the package
1994 is architecture-independent.
1998 In the main <tt>debian/control</tt> file in the source
1999 package, or in the source package control file
2000 <tt>.dsc</tt>, a list of architectures (separated by
2001 spaces) is also allowed, as is the special value
2002 <tt>any</tt>. A list indicates that the source will build
2003 an architecture-dependent package, and will only work
2004 correctly on the listed architectures. <tt>any</tt>
2005 indicates that though the source package isn't dependent
2006 on any particular architecture and should compile fine on
2007 any one, the binary package(s) produced are not
2008 architecture-independent but will instead be specific to
2009 whatever the current build architecture is.
2013 In a <tt>.changes</tt> file the <tt>Architecture</tt>
2014 field lists the architecture(s) of the package(s)
2015 currently being uploaded. This will be a list; if the
2016 source for the package is being uploaded too the special
2017 entry <tt>source</tt> is also present.
2021 See <ref id="debianrules"> for information how to get the
2022 architecture for the build process.
2026 <sect1 id="f-Maintainer"><heading><tt>Maintainer</tt>
2030 The package maintainer's name and email address. The name
2031 should come first, then the email address inside angle
2032 brackets <tt><></tt> (in RFC822 format).
2036 If the maintainer's name contains a full stop then the
2037 whole field will not work directly as an email address due
2038 to a misfeature in the syntax specified in RFC822; a
2039 program using this field as an address must check for this
2040 and correct the problem if necessary (for example by
2041 putting the name in round brackets and moving it to the
2042 end, and bringing the email address forward).
2046 In a <tt>.changes</tt> file or parsed changelog data this
2047 contains the name and email address of the person
2048 responsible for the particular version in question - this
2049 may not be the package's usual maintainer.
2053 This field is usually optional in as far as the
2054 <prgn>dpkg</prgn> are concerned, but its absence when
2055 building packages usually generates a warning.</p>
2058 <sect1 id="f-Source"><heading><tt>Source</tt>
2062 This field identifies the source package name.
2066 In a main source control information or a
2067 <tt>.changes</tt> or <tt>.dsc</tt> file or parsed
2068 changelog data this may contain only the name of the
2073 In the control file of a binary package (or in a
2074 <tt>Packages</tt> file) it may be followed by a version
2075 number in parentheses.
2078 It is usual to leave a space after the package name if
2079 a version number is specified.
2081 </footnote> This version number may be omitted (and is, by
2082 <prgn>dpkg-gencontrol</prgn>) if it has the same value as
2083 the <tt>Version</tt> field of the binary package in
2084 question. The field itself may be omitted from a binary
2085 package control file when the source package has the same
2086 name and version as the binary package.
2090 <sect1><heading>Package interrelationship fields:
2091 <tt>Depends</tt>, <tt>Pre-Depends</tt>,
2092 <tt>Recommends</tt> <tt>Suggests</tt>, <tt>Conflicts</tt>,
2093 <tt>Provides</tt>, <tt>Replaces</tt>
2097 These fields describe the package's relationships with
2098 other packages. Their syntax and semantics are described
2099 in <ref id="relationships">.</p>
2102 <sect1 id="f-Description"><heading><tt>Description</tt>
2106 In a binary package <tt>Packages</tt> file or main source
2107 control file this field contains a description of the
2108 binary package, in a special format. See <ref
2109 id="descriptions"> for details.
2113 In a <tt>.changes</tt> file it contains a summary of the
2114 descriptions for the packages being uploaded. The part of
2115 the field before the first newline is empty; thereafter
2116 each line has the name of a binary package and the summary
2117 description line from that binary package. Each line is
2118 indented by one space.</p>
2121 <sect1 id="f-Essential"><heading><tt>Essential</tt>
2125 This is a boolean field which may occur only in the
2126 control file of a binary package (or in the
2127 <tt>Packages</tt> file) or in a per-package fields
2128 paragraph of a main source control data file.
2132 If set to <tt>yes</tt> then <prgn>dpkg</prgn> and
2133 <prgn>dselect</prgn> will refuse to remove the package
2134 (though it can be upgraded and/or replaced). The other
2135 possible value is <tt>no</tt>, which is the same as not
2136 having the field at all.</p>
2139 <sect1 id="f-classification"><heading><tt>Section</tt> and
2144 These two fields classify the package. The
2145 <tt>Priority</tt> represents how important that it is that
2146 the user have it installed; the <tt>Section</tt>
2147 represents an application area into which the package has
2152 When they appear in the <tt>debian/control</tt> file these
2153 fields give values for the section and priority subfields
2154 of the <tt>Files</tt> field of the <tt>.changes</tt> file,
2155 and give defaults for the section and priority of the
2160 The section and priority are represented, though not as
2161 separate fields, in the information for each file in the
2162 <qref id="f-Files"><tt>-File</tt></qref>field of a
2163 <tt>.changes</tt> file. The section value in a
2164 <tt>.changes</tt> file is used to decide where to install
2165 a package in the FTP archive.
2169 These fields are not used by by <prgn>dpkg</prgn> proper,
2170 but by <prgn>dselect</prgn> when it sorts packages and
2171 selects defaults. See the Debian policy manual for the
2172 priorities in use and the criteria for selecting the
2173 priority for a Debian package, and look at the Debian FTP
2174 archive for a list of currently in-use priorities.
2178 These fields may appear in binary package control files,
2179 in which case they provide a default value in case the
2180 <tt>Packages</tt> files are missing the information.
2181 <prgn>dpkg</prgn> and <prgn>dselect</prgn> will only use
2182 the value from a <tt>.deb</tt> file if they have no other
2183 information; a value listed in a <tt>Packages</tt> file
2184 will always take precedence. By default
2185 <prgn>dpkg-genchanges</prgn> does not include the section
2186 and priority in the control file of a binary package - use
2187 the <tt>-isp</tt>, <tt>-is</tt> or <tt>-ip</tt> options to
2188 achieve this effect.</p>
2191 <sect1 id="f-Binary"><heading><tt>Binary</tt>
2195 This field is a list of binary packages.
2199 When it appears in the <tt>.dsc</tt> file it is the list
2200 of binary packages which a source package can produce. It
2201 does not necessarily produce all of these binary packages
2202 for every architecture. The source control file doesn't
2203 contain details of which architectures are appropriate for
2204 which of the binary packages.
2208 When it appears in a <tt>.changes</tt> file it lists the
2209 names of the binary packages actually being uploaded.
2213 The syntax is a list of binary packages separated by
2217 A space after each comma is conventional.
2219 </footnote> Currently the packages must be separated using
2220 only spaces in the <tt>.changes</tt> file.</p>
2223 <sect1 id="f-Installed-Size"><heading><tt>Installed-Size</tt>
2227 This field appears in the control files of binary
2228 packages, and in the <tt>Packages</tt> files. It gives
2229 the total amount of disk space required to install the
2234 The disk space is represented in kilobytes as a simple
2238 <sect1 id="f-Files"><heading><tt>Files</tt>
2242 This field contains a list of files with information about
2243 each one. The exact information and syntax varies with
2244 the context. In all cases the the part of the field
2245 contents on the same line as the field name is empty. The
2246 remainder of the field is one line per file, each line
2247 being indented by one space and containing a number of
2248 sub-fields separated by spaces.
2252 In the <tt>.dsc</tt> (Debian source control) file each
2253 line contains the MD5 checksum, size and filename of the
2254 tarfile and (if applicable) diff file which make up the
2255 remainder of the source package.
2258 That is, the parts which are not the
2261 </footnote> The exact forms of the filenames are described
2262 in <ref id="sourcearchives">.
2266 In the <tt>.changes</tt> file this contains one line per
2267 file being uploaded. Each line contains the MD5 checksum,
2268 size, section and priority and the filename. The section
2269 and priority are the values of the corresponding fields in
2270 the main source control file - see <ref
2271 id="f-classification">. If no section or priority is
2272 specified then <tt>-</tt> should be used, though section
2273 and priority values must be specified for new packages to
2274 be installed properly.
2278 The special value <tt>byhand</tt> for the section in a
2279 <tt>.changes</tt> file indicates that the file in question
2280 is not an ordinary package file and must by installed by
2281 hand by the distribution maintainers. If the section is
2282 <tt>byhand</tt> the priority should be <tt>-</tt>.
2286 If a new Debian revision of a package is being shipped and
2287 no new original source archive is being distributed the
2288 <tt>.dsc</tt> must still contain the <tt>Files</tt> field
2289 entry for the original source archive
2290 <tt><var>package</var>-<var>upstream-version</var>.orig.tar.gz</tt>,
2291 but the <tt>.changes</tt> file should leave it out. In
2292 this case the original source archive on the distribution
2293 site must match exactly, byte-for-byte, the original
2294 source archive which was used to generate the
2295 <tt>.dsc</tt> file and diff which are being uploaded.</p>
2300 id="f-Standards-Version"><heading><tt>Standards-Version</tt>
2304 The most recent version of the standards (the
2305 <prgn>dpkg</prgn> programmers' and policy manuals and
2306 associated texts) with which the package complies. This
2307 is updated manually when editing the source package to
2308 conform to newer standards; it can sometimes be used to
2309 tell when a package needs attention.
2313 Its format is the same as that of a version number except
2314 that no epoch or Debian revision is allowed - see <ref
2319 <sect1 id="f-Distribution"><heading><tt>Distribution</tt>
2323 In a <tt>.changes</tt> file or parsed changelog output
2324 this contains the (space-separated) name(s) of the
2325 distribution(s) where this version of the package should
2326 be or was installed. Distribution names follow the rules
2327 for package names. (See <ref id="f-Package">).
2331 Current distribution values are:
2333 <tag><em>stable</em></tag>
2336 This is the current `released' version of Debian
2337 GNU/Linux. A new version is released approximately
2338 every 3 months after the <em>development</em> code has
2339 been <em>frozen</em> for a month of testing. Once the
2340 distribution is <em>stable</em> only major bug fixes
2341 are allowed. When changes are made to this
2342 distribution, the minor version number is increased
2343 (for example: 1.2 becomes 1.2.1 then 1.2.2, etc).
2347 <tag><em>unstable</em></tag>
2350 This distribution value refers to the
2351 <em>developmental</em> part of the Debian distribution
2352 tree. New packages, new upstream versions of packages
2353 and bug fixes go into the <em>unstable</em> directory
2354 tree. Download from this distribution at your own
2358 <tag><em>contrib</em></tag>
2361 The packages with this distribution value do not meet
2362 the criteria for inclusion in the main Debian
2363 distribution as defined by the Policy Manual, but meet
2364 the criteria for the <em>contrib</em>
2365 Distribution. There is currently no distinction
2366 between stable and unstable packages in the
2367 <em>contrib</em> or <em>non-free</em>
2368 distributions. Use your best judgement in downloading
2369 from this Distribution.</p>
2372 <tag><em>non-free</em></tag>
2375 Like the packages in the <em>contrib</em> seciton,
2376 the packages in <em>non-free</em> do not meet the
2377 criteria for inclusion in the main Debian distribution
2378 as defined by the Policy Manual. Again, use your best
2379 judgement in downloading from this Distribution.</p>
2381 <tag><em>experimental</em></tag>
2384 The packages with this distribution value are deemed
2385 by their maintainers to be high risk. Oftentimes they
2386 represent early beta or developmental packages from
2387 various sources that the maintainers want people to
2388 try, but are not ready to be a part of the other parts
2389 of the Debian distribution tree. Download at your own
2393 <tag><em>frozen</em></tag>
2396 From time to time, (currently, every 3 months) the
2397 <em>unstable</em> distribution enters a state of
2398 `code-freeze' in anticipation of release as a
2399 <em>stable</em> version. During this period of testing
2400 (usually 4 weeks) only fixes for existing or
2401 newly-discovered bugs will be allowed.
2404 </taglist> You should list <em>all</em> distributions that
2405 the package should be installed into. Except in unusual
2406 circumstances, installations to <em>stable</em> should also
2407 go into <em>frozen</em> (if it exists) and
2408 <em>unstable</em>. Likewise, installations into
2409 <em>frozen</em> should also go into <em>unstable</em>.</p>
2412 <sect1 id="f-Urgency"><heading><tt>Urgency</tt>
2416 This is a description of how important it is to upgrade to
2417 this version from previous ones. It consists of a single
2418 keyword usually taking one of the values <tt>LOW</tt>,
2419 <tt>MEDIUM</tt> or <tt>HIGH</tt>) followed by an optional
2420 commentary (separated by a space) which is usually in
2421 parentheses. For example:
2423 Urgency: LOW (HIGH for diversions users)
2428 This field appears in the <tt>.changes</tt> file and in
2429 parsed changelogs; its value appears as the value of the
2430 <tt>urgency</tt> attribute in a <prgn>dpkg</prgn>-style
2431 changelog (see <ref id="dpkgchangelog">).
2435 Urgency keywords are not case-sensitive.</p>
2438 <sect1 id="f-Date"><heading><tt>Date</tt>
2442 In <tt>.changes</tt> files and parsed changelogs, this
2443 gives the date the package was built or last edited.</p>
2446 <sect1 id="f-Format"><heading><tt>Format</tt>
2450 This field occurs in <tt>.changes</tt> files, and
2451 specifies a format revision for the file. The format
2452 described here is version <tt>1.5</tt>. The syntax of the
2453 format value is the same as that of a package version
2454 number except that no epoch or Debian revision is allowed
2455 - see <ref id="versions">.</p>
2458 <sect1 id="f-Changes"><heading><tt>Changes</tt>
2462 In a <tt>.changes</tt> file or parsed changelog this field
2463 contains the human-readable changes data, describing the
2464 differences between the last version and the current one.
2468 There should be nothing in this field before the first
2469 newline; all the subsequent lines must be indented by at
2470 least one space; blank lines must be represented by a line
2471 consiting only of a space and a full stop.
2475 Each version's change information should be preceded by a
2476 `title' line giving at least the version, distribution(s)
2477 and urgency, in a human-readable way.
2481 If data from several versions is being returned the entry
2482 for the most recent version should be returned first, and
2483 entries should be separated by the representation of a
2484 blank line (the `title' line may also be followed by the
2485 representation of blank line).</p>
2488 <sect1 id="f-Filename"><heading><tt>Filename</tt> and
2489 <tt>MSDOS-Filename</tt>
2493 These fields in <tt>Packages</tt> files give the
2494 filename(s) of (the parts of) a package in the
2495 distribution directories, relative to the root of the
2496 Debian hierarchy. If the package has been split into
2497 several parts the parts are all listed in order, separated
2501 <sect1 id="f-Size"><heading><tt>Size</tt> and <tt>MD5sum</tt>
2505 These fields in <tt>Packages</tt> files give the size (in
2506 bytes, expressed in decimal) and MD5 checksum of the
2507 file(s) which make(s) up a binary package in the
2508 distribution. If the package is split into several parts
2509 the values for the parts are listed in order, separated by
2513 <sect1 id="f-Status"><heading><tt>Status</tt>
2517 This field in <prgn>dpkg</prgn>'s status file records
2518 whether the user wants a package installed, removed or
2519 left alone, whether it is broken (requiring
2520 reinstallation) or not and what its current state on the
2521 system is. Each of these pieces of information is a
2525 <sect1 id="f-Config-Version"><heading><tt>Config-Version</tt>
2529 If a package is not installed or not configured, this
2530 field in <prgn>dpkg</prgn>'s status file records the last
2531 version of the package which was successfully
2535 <sect1 id="f-Conffiles"><heading><tt>Conffiles</tt>
2539 This field in <prgn>dpkg</prgn>'s status file contains
2540 information about the automatically-managed configuration
2541 files held by a package. This field should <em>not</em>
2542 appear anywhere in a package!</p>
2545 <sect1><heading>Obsolete fields
2549 These are still recognised by <prgn>dpkg</prgn> but should
2550 not appear anywhere any more.
2551 <taglist compact="compact">
2553 <tag><tt>Revision</tt></tag>
2554 <tag><tt>Package-Revision</tt></tag>
2555 <tag><tt>Package_Revision</tt></tag>
2558 The Debian revision part of the package version was
2559 at one point in a separate control file field. This
2560 field went through several names.</p>
2563 <tag><tt>Recommended</tt></tag>
2564 <item><p>Old name for <tt>Recommends</tt></p>
2567 <tag><tt>Optional</tt></tag>
2568 <item><p>Old name for <tt>Suggests</tt>.</p>
2570 <tag><tt>Class</tt></tag>
2571 <item><p>Old name for <tt>Priority</tt>.</p>
2579 <chapt id="versions"><heading>Version numbering
2583 Every package has a version number, in its <tt>Version</tt>
2588 <prgn>dpkg</prgn> imposes an ordering on version numbers, so
2589 that it can tell whether packages are being up- or downgraded
2590 and so that <prgn>dselect</prgn> can tell whether a package it
2591 finds available is newer than the one installed on the system.
2592 The version number format has the most significant parts (as
2593 far as comparison is concerned) at the beginning.
2597 The version number format is:
2598 &lsqb<var>epoch/<tt>:</tt>]<var>upstream-version</var>[<tt>-/<var>debian-revision</var>].</tt></var>
2602 The three components here are:
2604 <tag><var>epoch</var></tag>
2608 This is a single unsigned integer, which should usually
2609 be small. It may be omitted, in which case zero is
2610 assumed. If it is omitted then the
2611 <var>upstream-version</var> may not contain any colons.
2615 It is provided to allow mistakes in the version numbers
2616 of older versions of a package, and also a package's
2617 previous version numbering schemes, to be left behind.
2621 <prgn>dpkg</prgn> will not usually display the epoch
2622 unless it is essential (non-zero, or if the
2623 <var>upstream-version</var> contains a colon);
2624 <prgn>dselect</prgn> does not display epochs at all in
2625 the main part of the package selection display.</p>
2628 <tag><var>upstream-version</var></tag>
2632 This is the main part of the version. It is usually
2633 version number of the original (`upstream') package of
2634 which the <tt>.deb</tt> file has been made, if this is
2635 applicable. Usually this will be in the same format as
2636 that specified by the upstream author(s); however, it
2637 may need to be reformatted to fit into
2638 <prgn>dpkg</prgn>'s format and comparison scheme.
2642 The comparison behaviour of <prgn>dpkg</prgn> with
2643 respect to the <var>upstream-version</var> is described
2644 below. The <var>upstream-version</var> portion of the
2645 version number is mandatory.
2649 The <var>upstream-version</var> may contain only
2650 alphanumerics and the characters <tt>+</tt> <tt>.</tt>
2651 <tt>-</tt> <tt>:</tt> (full stop, plus, hyphen, colon)
2652 and should start with a digit. If there is no
2653 <var>debian-revision</var> then hyphens are not allowed;
2654 if there is no <var>epoch</var> then colons are not
2658 <tag><var>debian-revision</var></tag>
2662 This part of the version represents the version of the
2663 modifications that were made to the package to make it a
2664 Debian binary package. It is in the same format as the
2665 <var>upstream-version</var> and <prgn>dpkg</prgn>
2666 compares it in the same way.
2670 It is optional; if it isn't present then the
2671 <var>upstream-version</var> may not contain a hyphen.
2672 This format represents the case where a piece of
2673 software was written specifically to be turned into a
2674 Debian binary package, and so there is only one
2675 `debianization' of it and therefore no revision
2676 indication is required.
2680 It is conventional to restart the
2681 <var>debian-revision</var> at <tt>1</tt> each time the
2682 <var>upstream-version</var> is increased.
2686 <prgn>dpkg</prgn> will break the
2687 <var>upstream-version</var> and
2688 <var>debian-revision</var> apart at the last hyphen in
2689 the string. The absence of a <var>debian-revision</var>
2690 compares earlier than the presence of one (but note that
2691 the <var>debian-revision</var> is the least significant
2692 part of the version number).
2696 The <var>debian-revision</var> may contain only
2697 alphanumerics and the characters <tt>+</tt> and
2698 <tt>.</tt> (plus and full stop).
2702 The <var>upstream-version</var> and <var>debian-revision</var> parts are
2703 compared by <prgn>dpkg</prgn> using the same algorithm:
2707 The strings are compared from left to right.
2711 First the initial part of each string consisting entirely of
2712 non-digit characters is determined. These two parts (one of
2713 which may be empty) are compared lexically. If a difference
2714 is found it is returned. The lexical comparison is a
2715 comparison of ASCII values modified so that all the letters
2716 sort earlier than all the non-letters.
2720 Then the initial part of the remainder of each string which
2721 consists entirely of digit characters is determined. The
2722 numerical values of these two parts are compared, and any
2723 difference found is returned as the result of the comparison.
2724 For these purposes an empty string (which can only occur at
2725 the end of one or both version strings being compared) counts
2730 These two steps are repeated (chopping initial non-digit
2731 strings and initial digit strings off from the start) until a
2732 difference is found or both strings are exhausted.
2736 Note that the purpose of epochs is to allow us to leave behind
2737 mistakes in version numbering, and to cope with situations
2738 where the version numbering changes. It is <em>not</em> there
2739 to cope with version numbers containing strings of letters
2740 which <prgn>dpkg</prgn> cannot interpret (such as
2741 <tt>ALPHA</tt> or <tt>pre-</tt>), or with silly orderings (the
2742 author of this manual has heard of a package whose versions
2743 went <tt>1.1</tt>, <tt>1.2</tt>, <tt>1.3</tt>, <tt>1</tt>,
2744 <tt>2.1</tt>, <tt>2.2</tt>, <tt>2</tt> and so forth).
2748 If an upstream package has problematic version numbers they
2749 should be converted to a sane form for use in the
2750 <tt>Version</tt> field.
2754 If you need to compare version numbers in a script, you may use
2755 <tt>dpkg --compare-versions ...</tt>. Type <tt>dpkg
2756 --help</tt> --> --for details on arguments.
2760 <chapt id="maintainerscripts"><heading>Package maintainer scripts
2761 and installation procedure
2764 <sect><heading>Introduction to package maintainer scripts
2768 It is possible to supply scripts as part of a package which
2769 <prgn>dpkg</prgn> will run for you when your package is
2770 installed, upgraded or removed.
2774 These scripts should be the files <tt>preinst</tt>,
2775 <tt>postinst</tt>, <tt>prerm</tt> and <tt>postrm</tt> in the
2776 control area of the package. They must be proper exectuable
2777 files; if they are scripts (which is recommended) they must
2778 start with the usual <tt>#!</tt> convention. They should be
2779 readable and executable to anyone, and not world-writeable.
2783 <prgn>dpkg</prgn> looks at the exit status from these
2784 scripts. It is important that they exit with a non-zero
2785 status if there is an error, so that <prgn>dpkg</prgn> can
2786 stop its processing. For shell scripts this means that you
2787 <em>almost always</em> need to use <tt>set -e</tt> (this is
2788 usually true when writing shell scripts, in fact). It is
2789 also important, of course, that they don't exit with a
2790 non-zero status if everything went well.
2794 It is necessary for the error recovery procedures that the
2795 scripts be idempotent: ie, invoking the same script several
2796 times in the same situation should do no harm. If the first
2797 call failed, or aborted half way through for some reason,
2798 the second call should merely do the things that were left
2799 undone the first time, if any, and exit with a success
2804 When a package is upgraded a combination of the scripts from
2805 the old and new packages is called in amongst the other
2806 steps of the upgrade procedure. If your scripts are going
2807 to be at all complicated you need to be aware of this, and
2808 may need to check the arguments to your scripts.
2812 Broadly speaking the <prgn>preinst</prgn> is called before
2813 (a particular version of) a package is installed, and the
2814 <prgn>postinst</prgn> afterwards; the <prgn>prerm</prgn>
2815 before (a version of) a package is removed and the
2816 <prgn>postrm</prgn> afterwards.
2819 next paragraph by Guy Maor to close bug #2481
2822 <p> Programs called from maintainer scripts should not
2823 normally have a path prepended to them. Before installation
2824 is started <prgn>dpkg</prgn> checks to see if the programs
2825 <prgn>ldconfig</prgn>, <prgn>start-stop-daemon</prgn>,
2826 <prgn>install-info</prgn>, and <prgn>update-rc.d</prgn> can
2827 be found via the <tt>PATH</tt> environment variable. Those
2828 programs, and any other program that one would expect to on
2829 the <tt>PATH</tt>, should thus be invoked without an
2830 absolute pathname. Maintainer scripts should also not reset
2831 the <tt>PATH</tt>, though they might choose to modify it by
2832 pre- or appending package-specific directories. These
2833 considerations really apply to all shell scripts.</p>
2836 <sect id="mscriptsinstact"><heading>Summary of ways maintainer
2841 <list compact="compact">
2843 <p><var>new-preinst</var> <tt>install</tt></p>
2846 <p><var>new-preinst</var> <tt>install</tt>
2847 <var>old-version</var></p>
2850 <p><var>new-preinst</var> <tt>upgrade</tt>
2851 <var>old-version</var></p>
2854 <p><var>old-preinst</var> <tt>abort-upgrade</tt>
2855 <var>new-version</var>
2861 <list compact="compact">
2863 <p><var>postinst</var> <tt>configure</tt>
2864 <var>most-recently-configured-version</var></p>
2867 <p><var>old-postinst</var> <tt>abort-upgrade</tt>
2868 <var>new version</var></p>
2871 <p><var>conflictor's-postinst</var> <tt>abort-remove</tt>
2872 <tt>in-favour</tt> <var>package</var>
2873 <var>new-version</var></p>
2877 <var>deconfigured's-postinst</var>
2878 <tt>abort-deconfigure</tt> <tt>in-favour</tt>
2879 <var>failed-install-package</var> <var>version</var>
2880 <tt>removing</tt> <var>conflicting-package</var>
2887 <list compact="compact">
2889 <p><var>prerm</var> <tt>remove</tt></p>
2892 <p><var>old-prerm</var> <tt>upgrade</tt>
2893 <var>new-version</var></p>
2896 <p><var>new-prerm</var> <tt>failed-upgrade</tt>
2897 <var>old-version</var></p>
2900 <p><var>conflictor's-prerm</var> <tt>remove</tt>
2901 <tt>in-favour</tt> <var>package</var>
2902 <var>new-version</var></p>
2906 <var>deconfigured's-prerm</var> <tt>deconfigure</tt>
2907 <tt>in-favour</tt> <var>package-being-installed</var>
2908 <var>version</var> <tt>removing</tt>
2909 <var>conflicting-package</var>
2916 <list compact="compact">
2918 <p><var>postrm</var> <tt>remove</tt></p>
2921 <p><var>postrm</var> <tt>purge</tt></p>
2925 <var>old-postrm</var> <tt>upgrade</tt>
2926 <var>new-version</var></p>
2929 <p><var>new-postrm</var> <tt>failed-upgrade</tt>
2930 <var>old-version</var></p>
2933 <p><var>new-postrm</var> <tt>abort-install</tt></p>
2936 <p><var>new-postrm</var> <tt>abort-install</tt>
2937 <var>old-version</var></p>
2940 <p><var>new-postrm</var> <tt>abort-upgrade</tt>
2941 <var>old-version</var></p>
2945 <var>disappearer's-postrm</var> <tt>disappear</tt>
2946 <var>r>overwrit</var>r>
2947 <var>new-version</var></p></item>
2952 <sect id="unpackphase"><heading>Details of unpack phase of
2953 installation or upgrade
2957 The procedure on installation/upgrade/overwrite/disappear
2958 (ie, when running <tt>dpkg --unpack</tt>, or the unpack
2960 --install</tt>) is as follows. In each case if an error occurs the
2961 actions in are general run backwards - this means that the maintainer
2962 scripts are run with different arguments in reverse order. These are
2963 the `error unwind' calls listed below.
2970 <p>If a version the package is already
2973 <var>old-prerm</var> upgrade <var>new-version</var>
2978 If this gives an error (ie, a non-zero exit
2979 status), dpkg will attempt instead:
2981 <var>new-prerm</var> failed-upgrade <var>old-version</var>
2983 Error unwind, for both the above cases:
2985 <var>old-postinst</var> abort-upgrade <var>new-version</var>
2993 <p>If a `conflicting' package is being removed at the same time:
2997 If any packages depended on that conflicting
2998 package and <tt>--auto-deconfigure</tt> is
2999 specified, call, for each such package:
3001 <var>deconfigured's-prerm</var> deconfigure \
3002 in-favour <var>package-being-installed</var> <var>version</var> \
3003 removing <var>conflicting-package</var> <var>version</var>
3007 <var>deconfigured's-postinst</var> abort-deconfigure \
3008 in-favour <var>package-being-installed-but-failed</var> <var>version</var> \
3009 removing <var>conflicting-package</var> <var>version</var>
3011 The deconfigured packages are marked as
3012 requiring configuration, so that if
3013 <tt>--install</tt> is used they will be
3014 configured again if possible.</p>
3017 <p>To prepare for removal of the conflicting package, call:
3019 <var>conflictor's-prerm</var> remove in-favour <var>package</var> <var>new-version</var>
3023 <var>conflictor's-postinst</var> abort-remove \
3024 in-favour <var>package</var> <var>new-version</var>
3035 <p>If the package is being upgraded, call:
3037 <var>new-preinst</var> upgrade <var>old-version</var>
3042 Otherwise, if the package had some configuration
3043 files from a previous version installed (ie, it
3044 is in the `configuration files only' state):
3046 <var>new-preinst</var> install <var>old-version</var>
3050 <p>Otherwise (ie, the package was completely purged):
3052 <var>new-preinst</var> install
3054 Error unwind versions, respectively:
3056 <var>new-postrm</var> abort-upgrade <var>old-version</var>
3057 <var>new-postrm</var> abort-install <var>old-version</var>
3058 <var>new-postrm</var> abort-install
3068 The new package's files are unpacked, overwriting any
3069 that may be on the system already, for example any
3070 from the old version of the same package or from
3071 another package (backups of the old files are left
3072 around, and if anything goes wrong dpkg will attempt
3073 to put them back as part of the error unwind).
3077 It is an error for a package to contains files which
3078 are on the system in another package, unless
3079 <tt>Replaces</tt> is used (see <ref id="replaces">).
3080 Currently the <tt>--force-overwrite</tt> flag is
3081 enabled, downgrading it to a warning, but this may not
3086 It is a more serious error for a package to contain a
3087 plain file or other kind of nondirectory where another
3088 package has a directory (again, unless
3089 <tt>Replaces</tt> is used). This error can be
3090 overridden if desired using
3091 <tt>--force-overwrite-dir</tt>, but this is not
3096 Packages which overwrite each other's files produce
3097 behaviour which though deterministic is hard for the
3098 system administrator to understand. It can easily
3099 lead to `missing' programs if, for example, a package
3100 is installed which overwrites a file from another
3101 package, and is then removed again.
3104 Part of the problem is due to what is arguably a
3105 bug in <prgn>dpkg</prgn> .
3111 A directory will never be replaced by a symbolic links
3112 to a directory or vice versa; instead, the existing
3113 state (symlink or not) will be left alone and
3114 <prgn>dpkg</prgn> will follow the symlink if there is
3122 <p>If the package is being upgraded, call
3124 <var>old-postrm</var> upgrade <var>new-version</var>
3128 <p>If this fails, <prgn>dpkg</prgn> will attempt:
3130 <var>new-postrm</var> failed-upgrade <var>old-version</var>
3132 Error unwind, for both cases:
3134 <var>old-preinst</var> abort-upgrade <var>new-version</var>
3139 This is the point of no return - if <prgn>dpkg</prgn>
3140 gets this far, it won't back off past this point if an
3141 error occurs. This will leave the package in a fairly
3142 bad state, which will require a successful
3143 reinstallation to clear up, but it's when
3144 <prgn>dpkg</prgn> starts doing things that are
3149 Any files which were in the old version of the package
3150 but not in the new are removed.</p>
3153 <p>The new file list replaces the old.</p>
3156 <p>The new maintainer scripts replace the old.</p>
3160 <p>Any packages all of whose files have been overwritten during the
3161 installation, and which aren't required for
3162 dependencies, are considered to have been removed.
3163 For each such package,
3166 <p><prgn>dpkg</prgn> calls:
3168 <var>disappearer's-postrm</var> disappear \
3169 <var>overwriter</var> <var>overwriter-version</var>
3174 <p>The package's maintainer scripts are removed.
3179 It is noted in the status database as being in a
3180 sane state, namely not installed (any conffiles
3181 it may have are ignored, rather than being
3182 removed by <prgn>dpkg</prgn>). Note that
3183 disappearing packages do not have their prerm
3184 called, because <prgn>dpkg</prgn> doesn't know
3185 in advance that the package is going to
3194 Any files in the package we're unpacking that are also
3195 listed in the file lists of other packages are removed
3196 from those lists. (This will lobotomise the file list
3197 of the `conflicting' package if there is one.)
3202 The backup files made during installation, above, are
3209 The new package's status is now sane, and recorded as
3210 `unpacked'. Here is another point of no return - if
3211 the conflicting package's removal fails we do not
3212 unwind the rest of the installation; the conflicting
3213 package is left in a half-removed limbo.
3218 If there was a conflicting package we go and do the
3219 removal actions (described below), starting with the
3220 removal of the conflicting package's files (any that
3221 are also in the package being installed have already
3222 been removed from the conflicting package's file list,
3223 and so do not get removed now).
3230 <sect><heading>Details of configuration
3234 When we configure a package (this happens with <tt>dpkg
3235 --install</tt>, or with <tt>--configure</tt>), we first
3236 update the conffiles and then call:
3238 <var>postinst</var> configure <var>most-recently-configured-version</var>
3243 No attempt is made to unwind after errors during
3248 If there is no most recently configured version
3249 <prgn>dpkg</prgn> will pass a null argument; older versions
3250 of dpkg may pass <tt><unknown></tt> (including the
3251 angle brackets) in this case. Even older ones do not pass a
3252 second argument at all, under any circumstances.
3256 <sect><heading>Details of removal and/or configuration purging
3264 <var>prerm</var> remove
3270 The package's files are removed (except conffiles).
3275 <var>postrm</var> remove
3279 <p>All the maintainer scripts except the postrm are removed.
3283 If we aren't purging the package we stop here. Note
3284 that packages which have no postrm and no conffiles
3285 are automatically purged when removed, as there is no
3286 difference except for the <prgn>dpkg</prgn>
3291 The conffiles and any backup files (<tt>~</tt>-files,
3292 <tt>#*#</tt> files, <tt>%</tt>-files,
3293 <tt>.dpkg-{old,new,tmp}</tt>, etc.) are removed.</p>
3297 <var>postrm</var> purge
3301 <p>The package's file list is removed.</p>
3304 No attempt is made to unwind after errors during
3309 <chapt id="descriptions"><heading>Descriptions of packages - the
3310 <tt>Description</tt> field
3314 The <tt>Description</tt> control file field is used by
3315 <prgn>dselect</prgn> when the user is selecting which packages
3316 to install and by <prgn>dpkg</prgn> when it displays
3317 information about the status of packages and so forth. It is
3318 included on the FTP site in the <prgn>Packages</prgn> files,
3319 and may also be used by the Debian WWW pages.
3323 The description is intended to describe the program to a user
3324 who has never met it before so that they know whether they
3325 want to install it. It should also give information about the
3326 significant dependencies and conflicts between this package
3327 and others, so that the user knows why these dependencies and
3328 conflicts have been declared.
3332 The field's format is as follows:
3334 Description: <var>single line synopsis</var>
3335 <var>extended description over several lines</var>
3340 The synopsis is often printed in lists of packages and so
3341 forth, and should be as informative as possible. Every
3342 package should also have an extended description.
3345 <sect><heading>Types of formatting line in the extended
3353 Those starting with a single space are part of a
3354 paragraph. Successive lines of this form will be
3355 word-wrapped when displayed. The leading space will
3356 usually be stripped off.
3362 Those starting with two or more spaces. These will be
3363 displayed verbatim. If the display cannot be panned
3364 horizontally the displaying program will linewrap them
3365 `hard' (ie, without taking account of word breaks).
3366 If it can they will be allowed to trail off to the
3367 right. None, one or two initial spaces may be
3368 deleted, but the number of spaces deleted from each
3369 line will be the same (so that you can have indenting
3370 work correctly, for example).
3375 <p>Those containing a single space followed by a single full stop
3376 character. These are rendered as blank lines. This
3377 is the <em>only</em> way to get a blank line - see
3383 Those containing a space, a full stop and some more
3384 characters. These are for future expansion. Do not
3391 <sect><heading>Notes about writing descriptions
3395 <em>Always</em> start extended description lines with at least one
3396 whitespace character. Fields in the control file and in the Packages
3397 file are separated by field names starting in the first column, just
3398 as message header fields are in RFC822. Forgetting the whitespace
3399 will cause <prgn>dpkg-deb</prgn>
3402 Version 0.93.23 or later.
3404 </footnote> to produce a syntax error when trying to build
3405 the package. If you force it to build anyway
3406 <prgn>dpkg</prgn> will refuse to install the resulting
3411 <em>Do not</em> include any completely <em>empty</em>
3412 lines. These separate different records in the Packages file
3413 and different packages in the <tt>debian/control</tt> file,
3414 and are forbidden in package control files. See the
3415 previous paragraph for what happens if you get this wrong.
3419 The single line synopsis should be kept brief - certainly
3420 under 80 characters. <prgn>dselect</prgn> displays between
3421 25 and 49 characters without panning if you're using an
3422 80-column terminal, depending on what display options are in
3427 Do not include the package name in the synopsis line. The
3428 display software knows how to display this already, and you
3429 do not need to state it. Remember that in many situations
3430 the user may only see the synopsis line - make it as
3431 informative as you can.
3435 The extended description should describe what the package
3436 does and how it relates to the rest of the system (in terms
3437 of, for example, which subsystem it is which part of).
3441 The blurb that comes with a program in its announcements
3442 and/or <prgn>README</prgn> files is rarely suitable for use
3443 in a description. It is usually aimed at people who are
3444 already in the community where the package is used. The
3445 description field needs to make sense to anyone, even people
3446 who have no idea about any of the things the package deals
3451 Put important information first, both in the synopis and
3452 extended description. Sometimes only the first part of the
3453 synopsis or of the description will be displayed. You can
3454 assume that there will usually be a way to see the whole
3455 extended description.
3459 You may include information about dependencies and so forth
3460 in the extended description, if you wish.
3464 Do not use tab characters. Their effect is not predictable.
3468 Do not try to linewrap the summary (the part on the same
3469 line as the field name <tt>Description</tt>) into the
3470 extended description. This will not work correctly when the
3471 full description is displayed, and makes no sense where only
3472 the summary is available.</p>
3475 <sect><heading>Example description in control file for Smail
3481 Version: 3.1.29.1-13
3482 Maintainer: Ian Jackson <iwj10@cus.cam.ac.uk>
3483 Recommends: pine | mailx | elm | emacs | mail-user-agent
3485 Depends: cron, libc5
3487 Provides: mail-transport-agent
3488 Description: Electronic mail transport system.
3489 Smail is the recommended mail transport agent (MTA) for Debian.
3491 An MTA is the innards of the mail system - it takes messages from
3492 user-friendly mailer programs and arranges for them to be delivered
3493 locally or passed on to other systems as required.
3495 In order to make use of it you must have one or more user level
3496 mailreader programs such as elm, pine, mailx or Emacs (which has Rmail
3497 and VM as mailreaders) installed. If you wish to send messages other
3498 than just to other users of your system you must also have appropriate
3499 networking support, in the form of IP or UUCP.
3505 <chapt id="relationships"><heading>Declaring relationships between
3510 Packages can declare in their control file that they have
3511 certain relationships to other packages - for example, that
3512 they may not be installed at the same time as certain other
3513 packages, and/or that they depend on the presence of others,
3514 or that they should overwrite files in certain other packages
3519 This is done using the <tt>Depends</tt>, <tt>Recommends</tt>,
3520 <tt>Suggests</tt>, <tt>Conflicts</tt>, <tt>Provides</tt> and
3521 <tt>Replaces</tt> control file fields.
3524 <sect id="depsyntax"><heading>Syntax of relationship fields
3528 These fields all have a uniform syntax. They are a list of
3529 package names separated by commas.
3533 In <tt>Depends</tt>, <tt>Recommends</tt>, <tt>Suggests</tt>
3534 and <tt>Pre-Depends</tt> (the fields which declare
3535 dependencies of the package in which they occur on other
3536 packages) these package names may also be lists of
3537 alternative package names, separated by vertical bar symbols
3538 <tt>|</tt> (pipe symbols).
3542 All the fields except <tt>Provides</tt> may restrict their
3543 applicability to particular versions of each named package.
3544 This is done in parentheses after each individual package
3545 name; the parentheses should contain a relation from the
3546 list below followed by a version number, in the format
3547 described in <ref id="versions">.
3551 The relations allowed are <tt><<</tt>, <tt><=</tt>,
3552 <tt>=</tt>, <tt>>=</tt> and <tt>>></tt> for
3553 strictly earlier, earlier or equal, exactly equal, later or
3554 equal and strictly later, respectively. The forms
3555 <tt><</tt> and <tt>></tt> were used to mean
3556 earlier/later or equal, rather than strictly earlier/later,
3557 so they should not appear in new packages (though
3558 <prgn>dpkg</prgn> still supports them).
3562 Whitespace may appear at any point in the version
3563 specification, and must appear where it's necessary to
3564 disambiguate; it is not otherwise significant. For
3565 consistency and in case of future changes to
3566 <prgn>dpkg</prgn> it is recommended that a single space be
3567 used after a version relationship and before a version
3568 number; it is usual also to put a single space after each
3569 comma, on either side of each vertical bar, and before each
3578 Depends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh
3583 <sect><heading>Dependencies - <tt>Depends</tt>, <tt>Recommends</tt>,
3584 <tt>Suggests</tt>, <tt>Pre-Depends</tt>
3588 These four fields are used to declare a dependency by one
3589 package on another. They appear in the depending package's
3594 All but <tt>Pre-Depends</tt> (discussed below) take effect
3595 <em>only</em> when a package is to be configured. They do
3596 not prevent a package being on the system in an unconfigured
3597 state while its dependencies are unsatisfied, and it is
3598 possible to replace a package whose dependencies are
3599 satisfied and which is properly installed with a different
3600 version whose dependencies are not and cannot be satisfied;
3601 when this is done the depending package will be left
3602 unconfigured (since attempts to configure it will give
3603 errors) and will not function properly.
3607 For this reason packages in an installation run are usually
3608 all unpacked first and all configured later; this gives
3609 later versions of packages with dependencies on later
3610 versions of other packages the opportunity to have their
3611 dependencies satisfied.
3615 Thus <tt>Depends</tt> allows package maintainers to impose
3616 an order in which packages should be configured.
3618 <tag><tt>Depends</tt></tag>
3621 <p>This declares an absolute dependency.
3625 <prgn>dpkg</prgn> will not configure packages whose
3626 dependencies aren't satisfied. If it is asked to make
3627 an installation which would cause an installed
3628 package's dependencies to become unsatisfied it will
3632 Current versions (1.2.4) of <prgn>dpkg</prgn> have
3633 a bug in this area which will cause some of these
3634 problems to be ignored.
3636 </footnote>, unless <tt>--auto-deconfigure</tt> is
3637 specified, in which case those packages will be
3638 deconfigured before the installation proceeds.
3642 <prgn>dselect</prgn> makes it hard for the user to
3643 select packages for installation, removal or upgrade
3644 in a way that would mean that packages'
3645 <prgn>Depends</prgn> fields would be unsatisfied. The
3646 user can override this if they wish, for example if
3647 they know that <prgn>dselect</prgn> has an out-of-date
3648 view of the real package relationships.
3652 The <tt>Depends</tt> field should be used if the
3653 depended-on package is required for the depending
3654 package to provide a significant amount of
3658 <tag><tt>Recommends</tt></tag>
3660 <p>This declares a strong, but not absolute, dependency.
3664 <tt>Recommends</tt> is ignored by <prgn>dpkg</prgn>,
3665 so that users using the command-line (who are presumed
3666 to know what they're doing) will not be impeded.
3670 It is treated by <prgn>dselect</prgn> exactly as
3671 <tt>Depends</tt> is; this makes it hard for the user
3672 to select things so as to leave <tt>Recommends</tt>
3673 fields unsatisfied, but they are able to do so by
3678 The <tt>Recommends</tt> field should list packages
3679 that would be found together with this one in all but
3680 unusual installations.</p>
3683 <tag><tt>Suggests</tt></tag>
3687 This is used to declare that one package may be more
3688 useful with one or more others. Using this field
3689 tells the packaging system and the user that the
3690 listed packages are related to this one and can
3691 perhaps enhance its usefulness, but that installing
3692 this one without them is perfectly reasonable.
3696 <prgn>dselect</prgn> will offer suggsted packages to
3697 the system administrator when they select the
3698 suggesting package, but the default is not to install
3699 the suggested package.</p>
3702 <tag><tt>Pre-Depends</tt></tag>
3705 <p>This field is like <tt>Depends</tt>, except that it also forces
3706 <prgn>dpkg</prgn> to complete installation of the
3707 packages named before even starting the installation
3708 of the package which declares the predependency.
3712 <prgn>dselect</prgn> checks for predependencies when
3713 it is doing an installation run, and will attempt to
3714 find the packages which are required to be installed
3715 first and do so in the right order.
3719 However, this process is slow (because it requires
3720 repeated invocations of <prgn>dpkg</prgn>) and
3721 troublesome (because it requires guessing where to
3722 find the appropriate files).
3726 For these reasons, and because this field imposes
3727 restrictions on the order in which packages may be
3728 unpacked (which can be difficult for installations
3729 from multipart media, for example),
3730 <tt>Pre-Depends</tt> should be used sparingly,
3731 preferably only by packages whose premature upgrade or
3732 installation would hamper the ability of the system to
3733 continue with any upgrade that might be in progress.
3737 When the package declaring it is being configured, a
3738 <tt>Pre-Dependency</tt> will be considered satisfied
3739 only if the depending package has been correctly
3740 configured, just as if an ordinary <tt>Depends</tt>
3745 However, when a package declaring a predependency is
3746 being unpacked the predependency can be satisfied even
3747 if the depended-on package(s) are only unpacked or
3748 half-configured, provided that they have been
3749 configured correctly at some point in the past (and
3750 not removed or partially removed since). In this case
3751 both the previously-configured and currently unpacked
3752 or half-configured versions must satisfy any version
3753 clause in the <tt>Pre-Depends</tt> field.
3759 When selecting which level of dependency to use you should
3760 consider how important the depended-on package is to the
3761 functionality of the one declaring the dependency. Some
3762 packages are composed of components of varying degrees of
3763 importance. Such a package should list using
3764 <tt>Depends</tt> the package(s) which are required by the
3765 more important components. The other components'
3766 requirements may be mentioned as Suggestions or
3767 Recommendations, as appropriate to the components' relative
3771 <sect1><heading>Dependencies on shared libraries
3775 The dependency fields listed above are used by packages
3776 which need shared libraries to declare dependencies on the
3777 appropriate packages.
3781 These dependencies are usually determined automatically
3782 using <prgn>dpkg-shlibdeps</prgn> and inserted in the
3783 package control file using the control file substitution
3784 variables mechanism; see <ref id="srcsubstvars"> and
3785 <ref id="sourcetools">.
3789 <sect1><heading>Deconfiguration due to removal during bulk
3794 If <prgn>dpkg</prgn> would like to remove a package due to a
3795 conflict, as described above, but this would violate a
3796 dependency of some other package on the system,
3797 <prgn>dpkg</prgn> will usually not remove the conflicting
3798 package and halt with an error.
3802 However, if the <tt>--auto-deconfigure</tt> (<tt>-B</tt>)
3803 option is used <prgn>dpkg</prgn> will automatically
3804 `deconfigure' the package with the problematic dependency,
3805 so that the conflicting package can be removed and the
3806 package we're trying to install can be installed. If
3807 <prgn>dpkg</prgn> is being asked to install packages (rather
3808 than just unpacking them) it will try to reconfigure the
3809 package when it has unpacked all its arguments, in the hope
3810 that one of the other packages it is installing will satisfy
3811 the problematic dependency.
3815 <prgn>dselect</prgn> supplies this argument to
3816 <prgn>dpkg</prgn> when it invokes it, so that bulk
3817 installations proceed smoothly.
3821 <sect id="conflicts"><heading>Alternative packages -
3822 <tt>Conflicts</tt> and <tt>Replaces</tt>
3826 When one package declares a conflict with another
3827 <prgn>dpkg</prgn> will refuse to allow them to be installed
3828 on the system at the same time.
3832 If one package is to be installed, the other must be removed first -
3833 if the package being installed is marked as replacing (<ref
3834 id="replaces">) the one on the system, or the one on the system is
3835 marked as deselected, or both packages are marked
3836 <tt>Essential</tt>, then <prgn>dpkg</prgn> will
3837 automatically remove the package which is causing the
3838 conflict, otherwise it will halt the installation of the new
3839 package with an error.
3843 <prgn>dselect</prgn> makes it hard to select conflicting
3844 packages, though the user can override this if they wish.
3845 If they do not override it then <prgn>dselect</prgn> will
3846 select one of the packages for removal, and the user must
3847 make sure it is the right one. In the future
3848 <prgn>dselect</prgn> will look for the presence of a
3849 <tt>Replaces</tt> field to help decide which package should
3850 be installed and which removed.
3854 A package will not cause a conflict merely because its
3855 configuration files are still installed; it must be at least
3860 A special exception is made for packages which declare a
3861 conflict with their own package name, or with a virtual
3862 package which they provide (see below): this does not
3863 prevent their installation, and allows a package to conflict
3864 with others providing a replacement for it. You use this
3865 feature when you want the package in question to be the only
3866 package providing something.
3870 A <tt>Conflicts</tt> entry should almost never have an
3871 `earlier than' version clause. This would prevent
3872 <prgn>dpkg</prgn> from upgrading or installing the package
3873 which declared such a conflict until the upgrade or removal
3874 of the conflicted-with package had been completed. This
3875 aspect of installation ordering is not handled by
3876 <prgn>dselect</prgn>, so that the use <tt>Conflicts</tt> in
3877 this way is likely to cause problems for `bulk run' upgrades
3882 <sect id="virtual"><heading>Virtual packages - <tt>Provides</tt>
3886 As well as the names of actual (`concrete') packages, the
3887 package relationship fields <tt>Depends</tt>,
3888 <tt>Recommends</tt>, <tt>Suggests</tt> and
3889 <tt>Conflicts</tt> may mention virtual packages.
3893 A virtual package is one which appears in the
3894 <tt>Provides</tt> control file field of another package.
3895 The effect is as if the package(s) which provide a
3896 particular virtual package name had been listed by name
3897 everywhere the virtual package name appears.
3901 If there are both a real and a virtual package of the same
3902 name then the dependency may be satisfied (or the conflict
3903 caused) by either the real package or any of the virtual
3904 packages which provide it. This is so that, for example,
3910 and someone else releases an xemacs package they can say
3914 </example> and all will work in the interim (until a purely
3915 virtual package name is decided on and the <tt>emacs</tt>
3916 and <tt>vm</tt> packages are changed to use it).
3920 If a dependency or a conflict has a version number attached
3921 then only real packages will be considered to see whether
3922 the relationship is satisfied (or the prohibition violated,
3923 for a conflict) - it is assumed that a real package which
3924 provides virtual package is not of the `right' version. So,
3925 a <tt>Provides</tt> field may not contain version numbers,
3926 and the version number of the concrete package which
3927 provides a particular virtual package will not be looked at
3928 when considering a dependency on or conflict with the
3929 virtual package name.
3933 It is likely that the ability will be added in a future
3934 release of <prgn>dpkg</prgn> to specify a version number for
3935 each virtual package it provides. This feature is not yet
3936 present, however, and is expected to be used only
3941 If you want to specify which of a set of real packages should be the
3942 default to satisfy a particular dependency on a virtual package, you
3943 should list the real package as an alternative before the virtual.
3948 <sect id="replaces"><heading><tt>Replaces</tt> - overwriting
3949 files and replacing packages
3953 The <tt>Replaces</tt> control file field has two purposes,
3954 which come into play in different situations.
3958 Virtual packages (<ref id="virtual">) are not considered
3959 when looking at a <tt>Replaces</tt> field - the packages
3960 declared as being replaced must be mentioned by their real
3964 <sect1><heading>Overwriting files in other packages
3968 Firstly, as mentioned before, it is usually an error for a
3969 package to contains files which are on the system in
3970 another package, though currently the
3971 <tt>--force-overwrite</tt> flag is enabled by default,
3972 downgrading the error to a warning,
3976 If the overwriting package declares that it replaces the
3977 one containing the file being overwritten then
3978 <prgn>dpkg</prgn> will proceed, and replace the file from
3979 the old package with that from the new. The file will no
3980 longer be listed as `owned' by the old package.
3984 If a package is completely replaced in this way, so that
3985 <prgn>dpkg</prgn> does not know of any files it still
3986 contains, it is considered to have disappeared. It will
3987 be marked as not wanted on the system (selected for
3988 removal) and not installed. Any conffiles details noted
3989 in the package will be ignored, as they will have been
3990 taken over by the replacing package(s). The package's
3991 <prgn>postrm</prgn> script will be run to allow the
3992 package to do any final cleanup required. See <ref
3993 id="mscriptsinstact">.
3997 In the future <prgn>dpkg</prgn> will discard files which
3998 overwrite those from another package which declares that
3999 it replaces the one being installed (so that you can
4000 install an older version of a package without problems).
4004 This usage of <tt>Replaces</tt> only takes effect when
4005 both packages are at least partially on the system at
4006 once, so that it can only happen if they do not conflict
4007 or if the conflict has been overridden.</p>
4010 <sect1><heading>Replacing whole packages, forcing their
4015 Secondly, <tt>Replaces</tt> allows <prgn>dpkg</prgn> and
4016 <prgn>dselect</prgn> to resolve which package should be
4017 removed when there is a conflict - see <ref id="conflicts">. This
4018 usage only takes effect when the two packages <em>do</em>
4019 conflict, so that the two effects do not interfere with
4025 <sect><heading>Defaults for satisfying dependencies - ordering
4029 Ordering is significant in dependency fields.
4033 Usually dselect will suggest to the user that they select
4034 the package with the most `fundamental' class (eg, it will
4035 prefer Base packages to Optional ones), or the one that they
4036 `most wanted' to select in some sense.
4040 In the absence of other information <prgn>dselect</prgn>
4041 will offer a default selection of the first named package in
4042 a list of alternatives.
4046 However, there is no way to specify the `order' of several
4047 packages which all provide the same thing, when that thing
4048 is listed as a dependency.
4052 Therefore a dependency on a virtual package should contain a
4053 concrete package name as the first alternative, so that this
4058 For example, consider the set of packages:
4061 Recommends: info-browser
4064 Provides: info-browser
4067 Provides: info-browser
4072 If <prgn>emacs</prgn> and <prgn>info</prgn> both have the
4073 same priority then <prgn>dselect</prgn>'s choice is
4074 essentially random. Better would be
4077 Recommends: info | info-browser
4079 so that <prgn>dselect</prgn> defaults to selecting the
4080 lightweight standalone info browser.
4085 <chapt id="conffiles"><heading>Configuration file handling
4089 <prgn>dpkg</prgn> can do a certain amount of automatic
4090 handling of package configuration files.
4094 Whether this mechanism is appropriate depends on a number of
4095 factors, but basically there are two approaches to any
4096 particular configuration file.
4100 The easy method is to ship a best-effort configuration in the
4101 package, and use <prgn>dpkg</prgn>'s conffile mechanism to
4102 handle updates. If the user is unlikely to want to edit the
4103 file, but you need them to be able to without losing their
4104 changes, and a new package with a changed version of the file
4105 is only released infrequently, this is a good approach.
4109 The hard method is to build the configuration file from
4110 scratch in the <prgn>postinst</prgn> script, and to take the
4111 responsibility for fixing any mistakes made in earlier
4112 versions of the package automatically. This will be
4113 appropriate if the file is likely to need to be different on
4117 <sect><heading>Automatic handling of configuration files by
4122 A package may contain a control area file called
4123 <tt>conffiles</tt>. This file should be a list of filenames
4124 of configuration files needing automatic handling, separated
4125 by newlines. The filenames should be absolute pathnames,
4126 and the files referred to should actually exist in the
4131 When a package is upgraded <prgn>dpkg</prgn> will process
4132 the configuration files during the configuration stage,
4133 shortly before it runs the package's <prgn>postinst</prgn>
4138 For each file it checks to see whether the version of the
4139 file included in the package is the same as the one that was
4140 included in the last version of the package (the one that is
4141 being upgraded from); it also compares the version currently
4142 installed on the system with the one shipped with the last
4147 If neither the user nor the package maintainer has changed
4148 the file, it is left alone. If one or the other has changed
4149 their version, then the changed version is preferred - i.e.,
4150 if the user edits their file, but the package maintainer
4151 doesn't ship a different version, the user's changes will
4152 stay, silently, but if the maintainer ships a new version
4153 and the user hasn't edited it the new version will be
4154 installed (with an informative message). If both have
4155 changed their version the user is prompted about the problem
4156 and must resolve the differences themselves.
4160 The comparisons are done by calculating the MD5 message
4161 digests of the files, and storing the MD5 of the file as it
4162 was included in the most recent version of the package.
4166 When a package is installed for the first time
4167 <prgn>dpkg</prgn> will install the file that comes with it,
4168 unless that would mean overwriting a file already on the
4173 However, note that <prgn>dpkg</prgn> will <em>not</em>
4174 replace a conffile that was removed by the user (or by a
4175 script). This is necessary because with some programs a
4176 missing file produces an effect hard or impossible to
4177 achieve in another way, so that a missing file needs to be
4178 kept that way if the user did it.
4182 Note that a package should <em>not</em> modify a
4183 <prgn>dpkg</prgn>-handled conffile in its maintainer
4184 scripts. Doing this will lead to <prgn>dpkg</prgn> giving
4185 the user confusing and possibly dangerous options for
4186 conffile update when the package is upgraded.</p>
4189 <sect><heading>Fully-featured maintainer script configuration
4194 For files which contain site-specific information such as
4195 the hostname and networking details and so forth, it is
4196 better to create the file in the package's
4197 <prgn>postinst</prgn> script.
4201 This will typically involve examining the state of the rest
4202 of the system to determine values and other information, and
4203 may involve prompting the user for some information which
4204 can't be obtained some other way.
4208 When using this method there are a couple of important
4209 issues which should be considered:
4213 If you discover a bug in the program which generates the
4214 configuration file, or if the format of the file changes
4215 from one version to the next, you will have to arrange for
4216 the postinst script to do something sensible - usually this
4217 will mean editing the installed configuration file to remove
4218 the problem or change the syntax. You will have to do this
4219 very carefully, since the user may have changed the file,
4220 perhaps to fix the very problem that your script is trying
4221 to deal with - you will have to detect these situations and
4222 deal with them correctly.
4226 If you do go down this route it's probably a good idea to
4227 make the program that generates the configuration file(s) a
4228 separate program in <tt>/usr/sbin</tt>, by convention called
4229 <tt><var>package</var>config</tt> and then run that if
4230 appropriate from the post-installation script. The
4231 <tt><var>package</var>config</tt> program should not
4232 unquestioningly overwrite an existing configuration - if its
4233 mode of operation is geared towards setting up a package for
4234 the first time (rather than any arbitrary reconfiguration
4235 later) you should have it check whether the configuration
4236 already exists, and require a <tt>--force</tt> flag to
4237 overwrite it.</p></sect>
4242 <chapt id="alternatives"><heading>Alternative versions of an interface -
4243 <prgn>update-alternatives</prgn>
4247 When several packages all provide different versions of the
4248 same program or file it is useful to have the system select a
4249 default, but to allow the system administrator to change it
4250 and have their decisions respected.
4254 For example, there are several versions of the <prgn>vi</prgn>
4255 editor, and there is no reason to prevent all of them from
4256 being installed at once, each under their own name
4257 (<prgn>nvi</prgn>, <prgn>vim</prgn> or whatever).
4258 Nevertheless it is desirable to have the name <tt>vi</tt>
4259 refer to something, at least by default.
4263 If all the packages involved cooperate, this can be done with
4264 <prgn>update-alternatives</prgn>.
4268 Each package provides its own version under its own name, and
4269 calls <prgn>update-alternatives</prgn> in its postinst to
4270 register its version (and again in its prerm to deregister
4275 See the manpage <manref name="update-alternatives"
4276 section="8"> for details.
4280 If <prgn>update-alternatives</prgn> does not seem appropriate
4281 you may wish to consider using diversions instead.</p>
4285 <chapt id="diversions"><heading>Diversions - overriding a
4286 package's version of a file
4290 It is possible to have <prgn>dpkg</prgn> not overwrite a file
4291 when it reinstalls the package it belongs to, and to have it
4292 put the file from the package somewhere else instead.
4296 This can be used locally to override a package's version of a
4297 file, or by one package to override another's version (or
4298 provide a wrapper for it).
4302 Before deciding to use a diversion, read <ref
4303 id="alternatives"> to see if you really want a diversion
4304 rather than several alternative versions of a program.
4308 There is a diversion list, which is read by <prgn>dpkg</prgn>,
4309 and updated by a special program <prgn>dpkg-divert</prgn>.
4310 Please see <manref name="dpkg-divert" section="8"> for full
4311 details of its operation.
4315 When a package wishes to divert a file from another, it should
4316 call <prgn>dpkg-divert</prgn> in its preinst to add the
4317 diversion and rename the existing file. For example,
4318 supposing that a <prgn>smailwrapper</prgn> package wishes to
4319 install a wrapper around <tt>/usr/sbin/smail</tt>:
4321 if [ install = "$1" ]; then
4322 dpkg-divert --package smailwrapper --add --rename \
4323 --divert /usr/sbin/smail.real /usr/sbin/smail
4325 </example> Testing <tt>$1</tt> is necessary so that the script
4326 doesn't try to add the diversion again when
4327 <prgn>smailwrapper</prgn> is upgraded. The <tt>--package
4328 smailwrapper</tt> ensures that <prgn>smailwrapper</prgn>'s
4329 copy of <tt>/usr/sbin/smail</tt> can bypass the diversion and
4330 get installed as the true version.
4334 The postrm has to do the reverse:
4336 if [ remove = "$1" ]; then
4337 dpkg-divert --package smailwrapper --remove --rename \
4338 --divert /usr/sbin/smail.real /usr/sbin/smail
4344 Do not attempt to divert a file which is vitally important for
4345 the system's operation - when using <prgn>dpkg-divert</prgn>
4346 there is a time, after it has been diverted but before
4347 <prgn>dpkg</prgn> has installed the new version, when the file
4352 <chapt id="sharedlibs"><heading>Shared libraries
4356 Packages containing shared libraries must be constructed with
4357 a little care to make sure that the shared library is always
4358 available. This is especially important for packages whose
4359 shared libraries are vitally important, such as the libc.
4363 Firstly, your package should install the shared libraries
4364 under their normal names. For example, the
4365 <prgn>libgdbm1</prgn> package should install
4366 <tt>libgdbm.so.1.7.3</tt> as
4367 <tt>/usr/lib/libgdbm.so.1.7.3</tt>. The files should not be
4368 renamed or relinked by any prerm or postrm scripts;
4369 <prgn>dpkg</prgn> will take care of renaming things safely
4370 without affecting running programs, and attempts to interfere
4371 with this are likely to lead to problems.
4375 Secondly, your package should include the symlink that
4376 <prgn>ldconfig</prgn> would create for the shared libraries.
4377 For example, the <prgn>libgdbm1</prgn> package should include
4378 a symlink from <tt>/usr/lib/libgdbm.so.1</tt> to
4379 <tt>libgdbm.so.1.7.3</tt>. This is needed so that
4380 <prgn>ld.so</prgn> can find the library in between the time
4381 <prgn>dpkg</prgn> installs it and <prgn>ldconfig</prgn> is run
4382 in the <prgn>postinst</prgn> script. Futhermore, and <em>this
4383 is very important</em>, the library must be placed before the
4384 symlink pointing to it in the <tt>.deb</tt> file. This is so
4385 that by the time <prgn>dpkg</prgn> comes to install the
4386 symlink (overwriting the previous symlink pointing at an older
4387 version of the library) the new shared library is already in
4388 place. Currently the way to ensure the ordering is done
4389 properly is to install the library in the appropriate
4390 <tt>debian/tmp/.../lib</tt> directory before creating the
4391 symlink, by putting the commands in the <tt>debian/rules</tt>
4392 in the appropriate order.
4396 next Paragraph added to close Bug #5299, Guy Maor
4400 Thirdly, the development package should contain a symlink for
4401 the shared library without a version number. For example, the
4402 <tt>libgdbm1-dev</tt> package should include a symlink from
4403 <tt>/usr/lib/libgdm.so</tt> to <tt>libgdm.so.1.7.3</tt>. This
4404 symlink is needed by <prgn>ld</prgn> when compiling packages
4405 as it will only look for <tt>libgdm.so</tt> and
4406 <tt>libgdm.a</tt> when compiling dynamically or statically,
4411 next paragraph changed by Christian Schwarz (see policy weekly #6)
4415 Any package installing shared libraries in a directory that's listed
4416 in <tt>/etc/ld.so.conf</tt> or in one of the default library
4417 directories of <prgn>ld.so</prgn> (currently, these are <tt>/usr/lib</tt>
4418 and <tt>/lib</tt>) must call <prgn>ldconfig</prgn> in its <prgn>postinst</prgn>
4419 script if and only if the first argument is `configure'. However, it
4420 is important not to call <prgn>ldconfig</prgn> in the postrm or preinst
4421 scripts in the case where the package is being upgraded (see <ref
4422 id="unpackphase">), as <prgn>ldconfig</prgn> will see the temporary names
4423 that <prgn>dpkg</prgn> uses for the files while it is
4424 installing them and will make the shared library links point
4425 to them, just before <prgn>dpkg</prgn> continues the
4426 installation and removes the links!
4430 moved from section 2.2 , DMorris
4433 <sect id="shlibs"><heading>The <tt>shlibs</tt> File Format
4437 This file is for use by <prgn>dpkg-shlibdeps</prgn> and is
4438 required when your package provides shared libraries.
4442 Each line is of the form:
4444 <var>library-name</var> <var>version-or-soname</var> <var>dependencies ...</var>
4449 <var>library-name</var> is the name of the shared library,
4450 for example <tt>libc5</tt>.
4454 <var>version-or-soname</var> is the soname of the library -
4455 ie, the thing that must exactly match for the library to be
4456 recognised by <prgn>ld.so</prgn>. Usually this is major
4457 version number of the library.
4461 <var>dependencies</var> has the same syntax as a dependency
4462 field in a binary package control file. It should give
4463 details of which package(s) are required to satisfy a binary
4464 built against the version of the library contained in the
4465 package. See <ref id="depsyntax">.
4469 For example, if the package <tt>foo</tt> contains
4470 <tt>libfoo.so.1.2.3</tt>, where the soname of the library is
4471 <tt>libfoo.so.1</tt>, and the first version of the package
4472 which contained a minor number of at least <tt>2.3</tt> was
4473 <var>1.2.3-1</var>, then the package's <var>shlibs</var>
4476 libfoo 1 foo (>= 1.2.3-1)
4481 The version-specific dependency is to avoid warnings from
4482 <prgn>ld.so</prgn> about using older shared libraries with
4486 <sect><heading>Further Technical information on
4487 <tt>shlibs</tt></heading>
4491 following section mostly provided by Heiko Schlittermann
4495 <sect1><heading><em>What</em> are the <tt>shlibs</tt> files?
4499 The <tt>debian/shlibs</tt> file provides a way of checking
4500 for shared library dependencies on packaged binaries.
4501 They are intended to be used by package maintainers to
4502 make their lives easier.
4506 Other <tt>shlibs</tt> files that exist on a Debian system are
4508 <item> <p><tt>/etc/dpkg/shlibs.default</tt></p></item>
4509 <item> <p><tt>/etc/dpkg/shlibs.override</tt></p></item>
4510 <item> <p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
4511 <item> <p><tt>debian/shlibs.local</tt></p></item>
4513 These files are used by <prgn>dpkg-shlibdeps</prgn> when
4514 creating a binary package.</p>
4517 <sect1><heading><em>How</em> does <prgn>dpkg-shlibdeps</prgn>
4522 <prgn>dpkg-shlibdeps</prgn> calls <prgn>ldd</prgn> to
4523 determine the shared libraries used by the compiled
4524 binaries passed through its command line.
4528 For each shared library, <prgn>dpkg-shlibdeps</prgn> needs to know
4529 <list compact="compact">
4530 <item><p>the package containing the library, and</p></item>
4531 <item><p>the library version number,</p></item>
4534 it scans the following files in this order.
4535 <enumlist compact="compact">
4536 <item><p><tt>debian/shlibs.local</tt></p></item>
4537 <item><p><tt>/etc/dpkg/shlibs.override</tt></p></item>
4538 <item><p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
4539 <item><p><tt>/etc/dpkg/shlibs.default</tt></p></item>
4543 <sect1><heading><em>Who</em> maintains the various
4544 <tt>shlibs</tt> files?
4548 <list compact="compact">
4550 <p><tt>/etc/dpkg/shlibs.default</tt> - the maintainer
4555 <tt>/var/lib/dpkg/info/<var>package</var>.shlibs</tt>
4556 - the maintainer of each package</p>
4560 <tt>/etc/dpkg/shlibs.override</tt> - the local
4561 system administrator</p>
4564 <p><tt>debian/shlibs.local</tt> - the maintainer of
4569 The <tt>shlibs.default</tt> file is managed by
4570 <prgn>dpkg</prgn>. The entries in <tt>shlibs.default</tt>
4571 that are provided by <prgn>dpkg</prgn> are just there to
4572 fix things until the shared library packages all have
4573 <tt>shlibs</tt> files.
4577 <sect1><heading><em>How</em> to use <prgn>dpkg-shlibdeps</prgn> and
4578 the <tt>shlibs</tt> files?
4581 <sect2><heading>If your package doesn't provide a shared
4586 Put a call to <prgn>dpkg-shlibdeps</prgn> into your
4587 <tt>debian/rules</tt> file. If your package contains
4588 only binaries (e.g. no scripts) use:
4590 dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/*
4592 If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
4593 done. If it does complain you might need to create your
4594 own <tt>debian/shlibs.local</tt> file.</p>
4597 <sect2><heading>If your package provides a shared library
4601 Create a <tt>debian/shlibs</tt> file and let
4602 <tt>debian/rules</tt> install it in the control area:
4604 install -m644 debian/shlibs debian/tmp/DEBIAN
4606 If your package contains additional binaries see above.
4611 <sect1><heading><em>How</em> to write
4612 <tt>debian/shlibs.local</tt>
4616 This file is intended only as a <em>temporary</em> fix if
4617 your binaries depend on a library which doesn't provide
4618 its own <tt>/var/lib/dpkg/*.shlibs</tt> file yet.
4622 Let's assume you are packaging a binary <tt>foo</tt>. Your
4623 output in building the package might look like this.
4626 libbar.so.1 => /usr/X11R6/lib/libbar.so.1.0
4627 libc.so.5 => /lib/libc.so.5.2.18
4628 libX11.so.6 => /usr/X11R6/lib/libX11.so.6.0
4630 And when you ran <prgn>dpkg-shlibdeps</prgn>
4632 $ dpkg-shlibdeps -o foo
4633 dpkg-shlibdeps: warning: unable to find dependency information
4634 for shared library libbar
4635 (soname 1, path /usr/X11R6/lib/libbar.so.1.0, dependency field Depends)
4636 shlibs:Depends=elf-x11r6lib, libc5 (>= 5.2.18)
4638 The <prgn>foo</prgn> binary depends on the
4639 <prgn>libbar</prgn> shared library, but no package seems
4640 to provide a <tt>*.shlibs</tt> file in
4641 <tt></tt>var/lib/dpkg/info/. Let's determine the package
4647 $ dpkg -S /usr/X11R6/lib/libbar.so.1.0
4648 bar1: /usr/X11R6/lib/libbar.so.1.0
4649 $ dpkg -s bar1 | grep Version
4652 This tells us that the <prgn>bar1</prgn> package, version
4653 1.0-1 is the one we are using. Now we can create our own
4654 <tt>debian/shlibs.local</tt> to temporarly fix the above
4655 problem. Include the following line into your
4656 <tt>debian/shlibs.local</tt> file.
4658 libbar 1 bar1 (>= 1.0-1)
4660 Now your package build should work. As soon as the
4661 maintainer of <prgn>libbar1</prgn> provides a
4662 <tt>shlibs</tt> file, you can remove your
4663 <tt>debian/shlibs.local</tt> file.
4669 <chapt id="methif"><heading><prgn>dselect</prgn>'s interface to
4670 its installation methods
4674 <prgn>dselect</prgn> calls scripts from its installation
4675 methods when it needs to actually access data from the
4676 distribution. The core program <prgn>dselect</prgn> itself
4677 just calls these scripts and provides the package and access
4678 method selection interfaces. The installation methods are
4679 responsible for invoking <prgn>dpkg</prgn> as appropriate.
4683 Each installation method has three scripts:
4684 <list compact="compact">
4685 <item><p>Setup installation parameters.</p></item>
4686 <item><p>Update list of available packages.</p></item>
4687 <item><p>Install.</p></item>
4691 <prgn>dselect</prgn> searches for methods in
4692 <tt>/usr/lib/dpkg/methods</tt> and
4693 <tt>/usr/local/lib/dpkg/methods</tt>.
4696 <sect><heading>Functions of the method scripts
4700 The setup script is run just after the user has chosen an
4701 installation method. It should prompt the user for
4702 parameters like the site to NFS-mount or FTP from, the
4703 directory to use, or the directory or filesystem where the
4704 <tt>.deb</tt> files can be found, or the tape or floppy
4705 device to install from. It should store the responses under
4706 <tt>/var/lib/dpkg/methods</tt> - see below. If no available
4707 packages list is available it should perhaps offer to scan
4708 the available packages.
4712 The update script should obtain a list of available packages
4713 if possible, and run <tt>dpkg --update-avail</tt>, <tt>dpkg
4714 --merge-avail</tt> and/or <tt>dpkg --forget-old-unavail</tt>
4715 to load it into <prgn>dpkg</prgn> and <prgn>dselect</prgn>'s
4716 database of available packages. If no packages list was
4717 available and the user was offered and accepted the option
4718 of scanning the actual files available this scan should be
4719 done here, using <tt>dpkg --record-avail</tt>.
4723 The install script should feed all the available
4724 <tt>.deb</tt> files to <tt>dpkg --iGOEB</tt> (this is
4725 equivalent to <tt>dpkg --install
4726 --refuse-downgrade --selected-only --skip-same-version
4727 --auto-deconfigure</tt>). The <tt>-R</tt>
4728 (<tt>--recursive</tt>) option for traversing subdirectories
4729 may also be useful here).
4733 If any of these scripts needs to display a message for the
4734 user, it should wait for the user to hit `return' before
4735 exiting so that dselect doesn't immediately rewrite the
4740 If a method script succeeds (returns a zero exit status)
4741 <prgn>dselect</prgn> will return immediately to the main
4742 menu, with the `next' option highlighted ready for the user
4743 to select it. If it fails <prgn>dselect</prgn> will display
4744 a message and wait for the user to hit return.</p>
4747 <sect><heading>Location and arguments of the method scripts
4751 A set of scripts (henceforth known as a group) may provide
4752 several methods on the `main menu' with different behaviour.
4753 For example, there might be a generic get-packages-by-FTP
4754 group which might provide methods in the main menu for
4755 installation directly from one of the Debian mirror sites as
4756 well as for installation from a user-specified site.
4760 Each group of methods implemented by the same set of scripts
4761 should have a subdirectory
4762 <tt>/usr/lib/dpkg/methods/<var>group</var></tt> or
4763 <tt>/usr/local/lib/dpkg/methods/<var>group</var></tt>,
4765 <taglist compact="compact">
4766 <tag><tt>names</tt></tag>
4767 <item><p>a list of user-visible methods provided by these scripts.</p>
4769 <tag><tt>setup</tt></tag>
4770 <tag><tt>update</tt></tag>
4771 <tag><tt>install</tt></tag>
4772 <item><p>executable programs, the scripts themselves.</p>
4774 <tag><tt>desc.<var>option</var></tt></tag>
4775 <item><p>description file.</p></item>
4780 <tt>names</tt> will be formatted as a list of lines, each containing:
4782 <var>sequence</var> <var>method</var> <var>summary</var>
4786 <var>sequence</var> is a two-digit number that will be used
4787 much like <tt>rc.d</tt> prefixes to control the order in the
4788 main menu. If in doubt use 50.
4792 <var>method</var> is a name which is displayed by
4793 <prgn>dselect</prgn> as the name of the method, and which
4794 will be passed to <tt>setup</tt>, <tt>update</tt> and
4795 <tt>unpack</tt> as their first argument.
4799 <var>summary</var> is the brief description string for
4800 <prgn>dselect</prgn>'s menu.
4804 Each of the three scripts gets the same three arguments:
4805 <var>vardir</var>, <var>group</var> and <var>method</var>.
4806 <var>vardir</var> is the base directory for storing
4807 <prgn>dpkg</prgn> and <prgn>dselect</prgn>'s state, usually
4808 <tt>/var/lib/dpkg</tt>; this is passed in so that the
4809 <tt>--admindir</tt> option to <prgn>dselect</prgn> is
4814 Each option may have an extended description in
4815 <tt>desc.<var>option</var></tt>. This should be formatted
4816 like the extended description part of a <tt>Description</tt>
4817 field entry <em>shifted one character to the left</em>.
4821 <tt><var>vardir</var>/methods</tt> will exist, and a method
4823 <tt><var>vardir</var>/methods/<var>group</var></tt>
4824 directory to store its state.
4828 The group name and method name must follow the rules for C
4834 <chapt id="conversion"><heading>Conversion procedure from old
4839 This is a brief summary of the procedure for converting a
4840 pre-2.0.0.0-format source package into the new format.
4844 You are strongly advised to download and examine the <prgn>hello</prgn>
4845 package, and to read the section in the <prgn>dpkg</prgn> programmers'
4846 manual describing the source packaging tools. More detail about the
4847 exact functionality of these tools is available in
4848 <manref name="dpkg-source" section="1">.
4855 Download the original source code from wherever it can
4856 be found and do any rearrangement required to make it
4857 look like the original tree of the Debian source. Put
4859 <tt><var>package</var>-<var>upstream-version</var>.orig/</tt>
4861 <tt><var>package</var>_<var>upstream-version</var>.orig.tar.gz</tt>.
4867 Rename all files <tt>debian.*</tt> to <tt>debian/*</tt>.
4868 There may be some exceptions to this, but this is a good
4874 Edit the <tt>debian/changelog</tt> - create or rename it
4875 if necessary. Add a new revision to the top with the
4876 appropriate details, and a local variables entry to the
4877 bottom to set Emacs to the right mode:
4880 mode: debian-changelog
4888 Edit/create <tt>debian/control</tt>:
4889 <list compact="compact">
4892 Remove the <tt>Version</tt> field. If it is
4893 generated unusually (not equal to the source
4894 version) you must use the -v option to
4895 dpkg-gencontrol (see below). <tt>Section</tt>,
4896 <tt>Priority</tt>, <tt>Maintainer</tt> go above
4897 the first blank line, most of the rest
4904 Reorder the fields and add a blank line at an
4905 appropriate point, separating the source package
4906 fields from the binary package fields.
4911 <p>Add the <tt>Source</tt> field.</p></item>
4915 Add the <tt>Standards-Version</tt> field. (Please
4916 check out the Debian Policy Manual for details
4917 about this field.)</p>
4922 Change the <tt>Architecture</tt> field for each
4923 package to <tt>any</tt>, <tt>all</tt> or whatever.
4924 If there isn't an <tt>Architecture</tt> field add
4930 If any other use of sed or things used to happen
4931 to make the binary control files use
4932 <prgn>dpkg-gencontrol</prgn>'s variable
4933 substitution features to achieve the same effect.
4934 Use <tt>debian/substvars</tt> if you need to put
4935 unusally-generated information (apart from details
4936 of <tt>.deb</tt> files) in the <tt>.changes</tt>
4944 <p>Edit the <tt>debian/rules</tt>:
4945 <list compact="compact">
4948 Remove the <prgn>source</prgn> and
4949 <prgn>diff</prgn> and any <prgn>changes</prgn> and
4950 <prgn>dist</prgn> targets. These things now
4951 happen in a package-independent way and are not
4952 done by <tt>debian/rules</tt>.</p>
4956 Split the <prgn>binary</prgn> target into
4957 <prgn>binary-arch</prgn> and
4958 <prgn>binary-indep</prgn>; in many cases all of
4959 <prgn>binary</prgn> should go into
4960 <prgn>binary-arch</prgn>. Create the
4961 <prgn>binary</prgn> target and the unused of the
4962 two other <prgn>binary-*</prgn> targets if there
4963 is one - you can copy the ones from the
4964 <prgn>hello</prgn> package.</p>
4968 Change the <prgn>binary</prgn> target to use
4969 <prgn>dpkg-gencontrol</prgn> to make the package
4970 control file(s). Move it to after all the files
4971 have been installed but just before the last
4972 <prgn>chown</prgn> and <prgn>chmod</prgn> in the
4977 Change occurrences of <tt>debian-tmp</tt> to
4978 <tt>debian/tmp</tt>.</p>
4982 Change occurrences of
4983 <tt>debian.{post,pre}{inst,rm}</tt> to
4984 <tt>debian/*</tt>.</p>
4988 Remove the version number setting at the top, if
4993 Ensure that the package's Debian-specific and
4994 upstream changelogs are installed.</p>
5002 Change the package to use <prgn>dpkg-shlibdeps</prgn> to
5003 determine its shared library dependencies and substitute
5004 them in. Shared library dependencies should no longer
5005 be hardwired in the source package.</p>
5010 Check that the <tt>debian/README</tt> is really the
5011 copyright file, and if so rename it to
5012 <tt>debian/copyright</tt> and edit <tt>debian/rules</tt>
5013 to cope with this and to change the installation of the
5015 <tt>/usr/doc/<var>package</var>/copyright</tt> to
5016 <tt>/usr/doc/copyright/<var>package</var></tt>. If it
5017 isn't then find <tt>debian/copyright</tt> and decide
5018 what to do with the <tt>README</tt>.</p>
5022 <p>Check for various other anachronisms and problems:
5023 <list compact="compact">
5026 Remove any <tt>Package_Revision</tt>,
5027 <tt>Package-Revision</tt> or <tt>Revision</tt>
5032 Rename <tt>Optional</tt> to <tt>Suggests</tt>,
5033 <tt>Recommended</tt> to
5034 <tt>Recommends</tt>.</p>
5039 <tt>/usr/doc/examples/<var>package</var></tt> to
5040 <tt>/usr/doc/<var>package</var>/examples</tt>.</p>
5044 Make sure that manpages are installed
5049 Check that the description has an extended
5050 description, is well-formatted and meaningful and
5051 helpful to people wanting to know whether to
5052 install a package.</p>
5059 <p>Look everything over.</p></item>
5063 Do a test build using <tt>dpkg-buildpackage -us -uc -sa
5064 -r<var>whatever</var></tt>. Check the permissions and
5065 locations of files in the resulting package by examining
5066 the output of <tt>dpkg-deb --contents</tt>, and check
5067 that the source build happened OK. Test install the
5068 binary package(s) and test extract the source
5074 Sign the release: either rebuild everything with
5075 <tt>dpkg-buildpackage -sa</tt>, or PGP-sign the
5076 <tt>.dsc</tt>, rebuild the <tt>.changes</tt> using
5077 <tt>dpkg-genchanges -sa</tt>, and then PGP-sign the
5078 <tt>.changes</tt>.</p>
5085 The use of <tt>-sa</tt> on <prgn>dpkg-buildpackage</prgn> and
5086 <prgn>dpkg-genchanges</prgn> is important when doing the first
5087 build/uploading of a new-format source package. Unless this
5088 happens to be Debian revision <tt>0</tt> or <tt>1</tt> by
5089 default the original source tarfile will not be included in
5090 the uploaded files listed in the <tt>.changes</tt> file, and
5091 so it won't be installed on the FTP site. <tt>-sa</tt>
5092 requests that the original source be included