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.
50 <copyrightsummary>Copyright ©1996 Ian Jackson.</copyrightsummary>
52 This manual is free software; you may redistribute it and/or
53 modify it under the terms of the GNU General Public License
54 as published by the Free Software Foundation; either version
55 2, or (at your option) any later version.
59 This is distributed in the hope that it will be useful, but
60 <em>without any warranty</em>; without even the implied
61 warranty of merchantability or fitness for a particular
62 purpose. See the GNU General Public License for more
67 A copy of the GNU General Public License is available as
68 <tt>/usr/doc/copyright/GPL</tt> in the Debian GNU/Linux
69 distribution or on the World Wide Web at
70 <tt>http://www.gnu.org/copyleft/gpl.html</tt>. You can also
71 obtain it by writing to the Free Software Foundation, Inc.,
72 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
78 <!-- Describes the technical interface between a package and dpkg.
80 How to safely put shared libraries in a package. Details of
81 dpkg's handling of individual files. Sections on when to use
82 which feature (eg Replaces vs. Replaces/Conflicts
83 vs. update-alternatives vs. diversions) Cross-references to the
84 policy document (see below) where appropriate. Description of the
85 interface between dselect and its access methods. Hints on where
86 to start with a new package (ie, the hello package). What to do
91 Manpages are required for: update-rc.d, diversions,
92 update-alternatives, install-info in a package.
97 <heading>Introduction and scope of this manual</heading>
100 <prgn>dpkg</prgn> is a suite of programs for creating binary
101 package files and installing and removing them on Unix
104 <prgn>dpkg</prgn> is targetted primarily at Debian
105 GNU/Linux, but may work on or be ported to other
112 The binary packages are designed for the management of
113 installed executable programs (usually compiled binaries) and
114 their associated data, though source code examples and
115 documentation are provided as part of some packages.</p>
118 This manual describes the technical aspects of creating Debian
119 binary packages (<tt>.deb</tt> files). It documents the
120 behaviour of the package management programs
121 <prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and and the way
122 they interact with packages.</p>
125 It also documents the interaction between
126 <prgn>dselect</prgn>'s core and the access method scripts it
127 uses to actually install the selected packages, and describes
128 how to create a new access method.</p>
131 This manual does not go into detail about the options and
132 usage of the package building and installation tools. It
133 should therefore be read in conjuction with those programs'
138 The utility programs which are provided with <prgn>dpkg</prgn>
139 for managing various system configuration and similar issues,
140 such as <prgn>update-rc.d</prgn> and
141 <prgn>install-info</prgn>, are not described in detail here -
142 please see their manpages.
146 It does <em>not</em> describe the policy requirements imposed
147 on Debian packages, such as the permissions on files and
148 directories, documentation requirements, upload procedure, and
149 so on. You should see the Debian packaging policy manual for
150 these details. (Many of them will probably turn out to be
151 helpful even if you don't plan to upload your package and make
152 it available as part of the distribution.)
156 It is assumed that the reader is reasonably familiar with the
157 <prgn>dpkg</prgn> System Administrators' manual.
158 Unfortunately this manual does not yet exist.
162 The Debian version of the FSF's GNU hello program is provided
163 as an example for people wishing to create Debian
164 packages. The Debian <prgn>debmake</prgn> package is
165 recommended as a very helpful tool in creating and maintaining
166 Debian packages. However, while the tools and examples are
167 helpful, they do not replace the need to read and follow the
168 Policy and Programmer's Manual.</p>
171 <chapt id="binarypkg"><heading>Binary packages
175 The binary package has two main sections. The first part
176 consists of various control information files and scripts used
177 by <prgn>dpkg</prgn> when installing and removing. See <ref
182 The second part is an archive containing the files and
183 directories to be installed.
187 In the future binary packages may also contain other
188 components, such as checksums and digital signatures. The
189 format for the archive is described in full in the
190 <tt>deb(5)</tt> manpage.
194 <sect id="bincreating"><heading>Creating package files -
195 <prgn>dpkg-deb</prgn>
199 All manipulation of binary package files is done by
200 <prgn>dpkg-deb</prgn>; it's the only program that has
201 knowledge of the format. (<prgn>dpkg-deb</prgn> may be
202 invoked by calling <prgn>dpkg</prgn>, as <prgn>dpkg</prgn>
203 will spot that the options requested are appropriate to
204 <prgn>dpkg-deb</prgn> and invoke that instead with the same
209 In order to create a binary package you must make a
210 directory tree which contains all the files and directories
211 you want to have in the filesystem data part of the package.
212 In Debian-format source packages this directory is usually
213 <tt>debian/tmp</tt>, relative to the top of the package's
218 They should have the locations (relative to the root of the
219 directory tree you're constructing) ownerships and
220 permissions which you want them to have on the system when
225 With current versions of <prgn>dpkg</prgn> the uid/username
226 and gid/groupname mappings for the users and groups being
227 used should be the same on the system where the package is
228 built and the one where it is installed.
232 You need to add one special directory to the root of the
233 miniature filesystem tree you're creating:
234 <prgn>DEBIAN</prgn>. It should contain the control
235 information files, notably the binary package control file
236 (see <ref id="controlfile">).
240 The <prgn>DEBIAN</prgn> directory will not appear in the
241 filesystem archive of the package, and so won't be installed
242 by <prgn>dpkg</prgn> when the package is installed.
246 When you've prepared the package, you should invoke:
248 dpkg --build <var>directory</var>
253 This will build the package in
254 <tt><var>directory</var>.deb</tt>. (<prgn>dpkg</prgn> knows
255 that <tt>--build</tt> is a <prgn>dpkg-deb</prgn> option, so
256 it invokes <prgn>dpkg-deb</prgn> with the same arguments to
261 See the manpage <manref name="dpkg-deb" section="8"> for details of how
262 to examine the contents of this newly-created file. You may find the
263 output of following commands enlightening:
265 dpkg-deb --info <var>filename</var>.deb
266 dpkg-deb --contents <var>filename</var>.deb
267 dpkg --contents <var>filename</var>.deb
269 To view the copyright file for a package you could use this command:
271 dpkg --fsys-tarfile <var>filename</var>.deb | tar xof usr/doc/<var>\*</var>copyright | less
276 <sect id="controlarea">
278 Package control information files
282 The control information portion of a binary package is a
283 collection of files with names known to <prgn>dpkg</prgn>.
284 It will treat the contents of these files specially - some
285 of them contain information used by <prgn>dpkg</prgn> when
286 installing or removing the package; others are scripts which
287 the package maintainer wants <prgn>dpkg</prgn> to run.
291 It is possible to put other files in the package control
292 area, but this is not generally a good idea (though they
293 will largely be ignored).
297 Here is a brief list of the control info files supported by
298 <prgn>dpkg</prgn> and a summary of what they're used for.
303 <tag><tt>control</tt>
307 This is the key description file used by
308 <prgn>dpkg</prgn>. It specifies the package's name
309 and version, gives its description for the user,
310 states its relationships with other packages, and so
311 forth. See <ref id="controlfile">.
315 It is usually generated automatically from information
316 in the source package by the
317 <prgn>dpkg-gencontrol</prgn> program, and with
318 assistance from <prgn>dpkg-shlibdeps</prgn>. See <ref
319 id="sourcetools">.</p>
322 <tag><tt>postinst</tt>, <tt>preinst</tt>, <tt>postrm</tt>,
328 These are exectuable files (usually scripts) which
329 <prgn>dpkg</prgn> runs during installation, upgrade
330 and removal of packages. They allow the package to
331 deal with matters which are particular to that package
332 or require more complicated processing than that
333 provided by <prgn>dpkg</prgn>. Details of when and
334 how they are called are in <ref
335 id="maintainerscripts">.
339 It is very important to make these scripts
343 That means that if it runs successfully or fails
344 and then you call it again it doesn't bomb out,
345 but just ensures that everything is the way it
348 </footnote> This is so that if an error occurs, the
349 user interrupts <prgn>dpkg</prgn> or some other
350 unforeseen circumstance happens you don't leave the
351 user with a badly-broken package.
355 The maintainer scripts are guaranteed to run with a
356 controlling terminal and can interact with the user.
357 If they need to prompt for passwords, do full-screen
358 interaction or something similar you should do these
359 things to and from <tt>/dev/tty</tt>, since
360 <prgn>dpkg</prgn> will at some point redirect scripts'
361 standard input and output so that it can log the
362 installation process. Likewise, because these scripts
363 may be executed with standard output redirected into a
364 pipe for logging purposes, Perl scripts should set
365 unbuffered output by setting <tt>$|=1</tt> so that the
366 output is printed immediately rather than being
371 Each script should return a zero exit status for
372 success, or a nonzero one for failure.</p>
375 <tag><tt>conffiles</tt>
380 This file contains a list of configuration files which
381 are to be handled automatically by <prgn>dpkg</prgn>
382 (see <ref id="conffiles">). Note that not necessarily
383 every configuration file should be listed here.</p>
391 This file contains a list of the shared libraries
392 supplied by the package, with dependency details for
393 each. This is used by <prgn>dpkg-shlibdeps</prgn>
394 when it determines what dependencies are required in a
395 package control file. The <tt>shlibs</tt> file format
396 is described on <ref id="shlibs">.
402 <sect id="controlfile">
404 The main control information file: <tt>control</tt>
407 The most important control information file used by
408 <prgn>dpkg</prgn> when it installs a package is
409 <tt>control</tt>. It contains all the package's `vital
414 The binary package control files of packages built from
415 Debian sources are made by a special tool,
416 <prgn>dpkg-gencontrol</prgn>, which reads
417 <tt>debian/control</tt> and <tt>debian/changelog</tt> to
418 find the information it needs. See <ref id="sourcepkg"> for
423 The fields in binary package control files are:
424 <list compact="compact">
426 <p><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</p>
429 <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
431 <item><p><qref id="f-Architecture"><tt>Architecture</tt></qref>
435 This field should appear in all packages, though
436 <prgn>dpkg</prgn> doesn't require it yet so that
437 old packages can still be installed.
443 <p><qref id="relationships"><tt>Depends</tt>,
444 <tt>Provides</tt> et al.</qref></p>
447 <p><qref id="f-Essential"><tt>Essential</tt></qref></p>
450 <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
453 <p><qref id="f-classification"><tt>Section</tt>,
454 <tt>Priority</tt></qref></p>
457 <p><qref id="f-Source"><tt>Source</tt></qref></p>
460 <p><qref id="descriptions"><tt>Description</tt></qref></p>
464 <qref id="f-Installed-Size"><tt>Installed-Size</tt></qref>
470 A description of the syntax of control files and the purpose
471 of these fields is available in <ref id="controlfields">.
475 <heading>Time Stamps</heading>
477 Maintainers are encouraged to preserve the modification
478 times of the upstream source files in a package, as far as
479 is reasonably possible.
482 The rationale is that there is some information conveyed
483 by knowing the age of the file, for example, you could
484 recognize that some documentation is very old by looking
485 at the modification time, so it would be nice if the
486 modification time of the upstream source would be
493 <chapt id="sourcepkg">
494 <heading>Source packages</heading>
497 The Debian binary packages in the distribution are generated
498 from Debian sources, which are in a special format to assist
499 the easy and automatic building of binaries.
503 There was a previous version of the Debian source format,
504 which is now being phased out. Instructions for converting an
505 old-style package are given in the Debian policy manual.
508 <sect id="sourcetools">
509 <heading>Tools for processing source packages</heading>
512 Various tools are provided for manipulating source packages;
513 they pack and unpack sources and help build of binary
514 packages and help manage the distribution of new versions.
518 They are introduced and typical uses described here; see
519 <manref name="dpkg-source" section="1"> for full
520 documentation about their arguments and operation.
524 For examples of how to construct a Debian source package,
525 and how to use those utilities that are used by Debian
526 source packages, please see the <prgn>hello</prgn> example
532 <prgn>dpkg-source</prgn> - packs and unpacks Debian source
537 This program is frequently used by hand, and is also
538 called from package-independent automated building scripts
539 such as <prgn>dpkg-buildpackage</prgn>.
543 To unpack a package it is typically invoked with
545 dpkg-source -x <var>.../path/to/filename</var>.dsc
550 with the <tt><var>filename</var>.tar.gz</tt> and
551 <tt><var>filename</var>.diff.gz</tt> (if applicable) in
552 the same directory. It unpacks into
553 <tt><var>package</var>-<var>version</var></tt>, and if
555 <tt><var>package</var>-<var>version</var>.orig</tt>, in
556 the current directory.
560 To create a packed source archive it is typically invoked:
562 dpkg-source -b <var>package</var>-<var>version</var>
567 This will create the <tt>.dsc</tt>, <tt>.tar.gz</tt> and
568 <tt>.diff.gz</tt> (if appropriate) in the current
569 directory. <prgn>dpkg-source</prgn> does not clean the
570 source tree first - this must be done separately if it is
575 See also <ref id="sourcearchives">.</p>
581 <prgn>dpkg-buildpackage</prgn> - overall package-building
586 <prgn>dpkg-buildpackage</prgn> is a script which invokes
587 <prgn>dpkg-source</prgn>, the <tt>debian/rules</tt>
588 targets <prgn>clean</prgn>, <prgn>build</prgn> and
589 <prgn>binary</prgn>, <prgn>dpkg-genchanges</prgn> and
590 <prgn>pgp</prgn> to build a signed source and binary
595 It is usually invoked by hand from the top level of the
596 built or unbuilt source directory. It may be invoked with
597 no arguments; useful arguments include:
598 <taglist compact="compact">
599 <tag><tt>-uc</tt>, <tt>-us</tt></tag>
602 Do not PGP-sign the <tt>.changes</tt> file or the
603 source package <tt>.dsc</tt> file, respectively.</p>
605 <tag><tt>-p<var>pgp-command</var></tt></tag>
608 Invoke <var>pgp-command</var> instead of finding
609 <tt>pgp</tt> on the <prgn>PATH</prgn>.
610 <var>pgp-command</var> must behave just like
611 <prgn>pgp</prgn>.</p>
613 <tag><tt>-r<var>root-command</var></tt></tag>
616 When root privilege is required, invoke the command
617 <var>root-command</var>. <var>root-command</var>
618 should invoke its first argument as a command, from
619 the <prgn>PATH</prgn> if necessary, and pass its
620 second and subsequent arguments to the command it
621 calls. If no <var>root-command</var> is supplied
622 then <var>dpkg-buildpackage</var> will take no
623 special action to gain root privilege, so that for
624 most packages it will have to be invoked as root to
627 <tag><tt>-b</tt>, <tt>-B</tt></tag>
630 Two types of binary-only build and upload - see
631 <manref name="dpkg-source" section="1">.
640 <prgn>dpkg-gencontrol</prgn> - generates binary package
645 This program is usually called from <tt>debian/rules</tt>
646 (see <ref id="sourcetree">) in the top level of the source
651 This is usually done just before the files and directories in the
652 temporary directory tree where the package is being built have their
653 permissions and ownerships set and the package is constructed using
654 <prgn>dpkg-deb/</prgn>
657 This is so that the control file which is produced has
658 the right permissions
664 <prgn>dpkg-gencontrol</prgn> must be called after all the
665 files which are to go into the package have been placed in
666 the temporary build directory, so that its calculation of
667 the installed size of a package is correct.
671 It is also necessary for <prgn>dpkg-gencontrol</prgn> to
672 be run after <prgn>dpkg-shlibdeps</prgn> so that the
673 variable substitutions created by
674 <prgn>dpkg-shlibdeps</prgn> in <tt>debian/substvars</tt>
679 For a package which generates only one binary package, and
680 which builds it in <tt>debian/tmp</tt> relative to the top
681 of the source package, it is usually sufficient to call
682 <prgn>dpkg-gencontrol</prgn>.
686 Sources which build several binaries will typically need
689 dpkg-gencontrol -Pdebian/tmp-<var>pkg</var> -p<var>package</var>
690 </example> The <tt>-P</tt> tells
691 <prgn>dpkg-gencontrol</prgn> that the package is being
692 built in a non-default directory, and the <tt>-p</tt>
693 tells it which package's control file should be generated.
697 <prgn>dpkg-gencontrol</prgn> also adds information to the
698 list of files in <tt>debian/files</tt>, for the benefit of
699 (for example) a future invocation of
700 <prgn>dpkg-genchanges</prgn>.</p>
705 <prgn>dpkg-shlibdeps</prgn> - calculates shared library
710 This program is usually called from <tt>debian/rules</tt>
711 just before <prgn>dpkg-gencontrol</prgn> (see <ref
712 id="sourcetree">), in the top level of the source tree.
716 Its arguments are executables
719 They may be specified either in the locations in the
720 source tree where they are created or in the locations
721 in the temporary build tree where they are installed
722 prior to binary package creation.
724 </footnote> for which shared library dependencies should
725 be included in the binary package's control file.
729 If some of the executable(s) shared libraries should only
730 warrant a <tt>Recommends</tt> or <tt>Suggests</tt>, or if
731 some warrant a <tt>Pre-Depends</tt>, this can be achieved
732 by using the <tt>-d<var>dependency-field</var></tt> option
733 before those executable(s). (Each <tt>-d</tt> option
734 takes effect until the next <tt>-d</tt>.)
738 <prgn>dpkg-shlibdeps</prgn> does not directly cause the
739 output control file to be modified. Instead by default it
740 adds to the <tt>debian/substvars</tt> file variable
741 settings like <tt>shlibs:Depends</tt>. These variable
742 settings must be referenced in dependency fields in the
743 appropriate per-binary-package sections of the source
748 For example, the <prgn>procps</prgn> package generates two
749 kinds of binaries, simple C binaries like <prgn>ps</prgn>
750 which require a predependency and full-screen ncurses
751 binaries like <prgn>top</prgn> which require only a
752 recommendation. It can say in its <tt>debian/rules</tt>:
754 dpkg-shlibdeps -dPre-Depends ps -dRecommends top
756 and then in its main control file <tt>debian/control</tt>:
760 Pre-Depends: ${shlibs:Pre-Depends}
761 Recommends: ${shlibs:Recommends}
767 Sources which produce several binary packages with
768 different shared library dependency requirements can use
769 the <tt>-p<var>varnameprefix</var></tt> option to override
770 the default <tt>shlib:</tt> prefix (one invocation of
771 <prgn>dpkg-shlibdeps</prgn> per setting of this option).
772 They can thus produce several sets of dependency
773 variables, each of the form
774 <tt><var>varnameprefix</var>:<var>dependencyfield</var></tt>,
775 which can be referred to in the appropriate parts of the
776 binary package control files.
783 <prgn>dpkg-distaddfile</prgn> - adds a file to
784 <tt>debian/files</tt>
788 Some packages' uploads need to include files other than
789 the source and binary package files.
793 <prgn>dpkg-distaddfile</prgn> adds a file to the
794 <tt>debian/files</tt> file so that it will be included in
795 the <tt>.changes</tt> file when
796 <prgn>dpkg-genchanges</prgn> is run.
800 It is usually invoked from the <prgn>binary</prgn> target of
801 <tt>debian/rules</tt>:
803 dpkg-distaddfile <var>filename</var> <var>section</var> <var>priority</var>
805 The <var>filename</var> is relative to the directory where
806 <prgn>dpkg-genchanges</prgn> will expect to find it - this
807 is usually the directory above the top level of the source
808 tree. The <tt>debian/rules</tt> target should put the
809 file there just before or just after calling
810 <prgn>dpkg-distaddfile</prgn>.
814 The <var>section</var> and <var>priority</var> are passed
815 unchanged into the resulting <tt>.changes</tt> file. See
816 <ref id="f-classification">.
821 <sect1><heading><prgn>dpkg-genchanges</prgn> - generates a <tt>.changes</tt> upload
826 This program is usually called by package-independent
827 automatic building scripts such as
828 <prgn>dpkg-buildpackage</prgn>, but it may also be called
833 It is usually called in the top level of a built source
834 tree, and when invoked with no arguments will print out a
835 straightforward <tt>.changes</tt> file based on the
836 information in the source package's changelog and control
837 file and the binary and source packages which should have
843 <sect1><heading><prgn>dpkg-parsechangelog</prgn> - produces parsed representation of
848 This program is used internally by
849 <prgn>dpkg-source</prgn> et al. It may also occasionally
850 be useful in <tt>debian/rules</tt> and elsewhere. It
851 parses a changelog, <tt>debian/changelog</tt> by default,
852 and prints a control-file format representation of the
853 information in it to standard output.
858 <sect id="sourcetree"><heading>The Debianised source tree
862 The source archive scheme described later is intended to
863 allow a Debianised source tree with some associated control
864 information to be reproduced and transported easily. The
865 Debianised source tree is a version of the original program
866 with certain files added for the benefit of the
867 Debianisation process, and with any other changes required
868 made to the rest of the source code and installation
873 The extra files created for Debian are in the subdirectory
874 <tt>debian</tt> of the top level of the Debianised source
875 tree. They are described below.
878 <sect1><heading><tt>debian/rules</tt> - the main building
883 This file is an executable makefile, and contains the
884 package-specific recipies for compiling the package and
885 building binary package(s) out of the source.
889 It must start with the line <tt>#!/usr/bin/make -f</tt>,
890 so that it can be invoked by saying its name rather than
891 invoking <prgn>make</prgn> explicitly.
895 Since an interactive <tt>debian/rules</tt> script makes it
896 impossible to autocompile that package and also makes it
897 hard for other people to reproduce the same binary
898 package, all <strong>required targets</strong> have to be
899 non-interactive. At a minimul, required targets are the
900 ones called by <prgn>dpkg-buildpackage</prgn>, namely,
901 <em>clean</em>, <em>binary</em>, <em>binary-arch</em>, and
902 <em>build</em>. It also follows that any target that these
903 targets depend on must also be non-interactive.
907 The targets which are required to be present are:
909 <tag><tt>build</tt></tag>
912 This should perform all non-interactive
913 configuration and compilation of the package. If a
914 package has an interactive pre-build configuration
915 routine, the Debianised source package should be
916 built after this has taken place, so that it can be
917 built without rerunning the configuration.
921 For some packages, notably ones where the same
922 source tree is compiled in different ways to produce
923 two binary packages, the <prgn>build</prgn> target
924 does not make much sense. For these packages it is
925 good enough to provide two (or more) targets
926 (<tt>build-a</tt> and <tt>build-b</tt> or whatever)
927 for each of the ways of building the package, and a
928 <prgn>build</prgn> target that does nothing. The
929 <prgn>binary</prgn> target will have to build the
930 package in each of the possible ways and make the
931 binary package out of each.
935 The <prgn>build</prgn> target must not do anything
936 that might require root privilege.
940 The <prgn>build</prgn> target may need to run
941 <prgn>clean</prgn> first - see below.
945 When a package has a configuration routine that
946 takes a long time, or when the makefiles are poorly
947 designed, or when <prgn>build</prgn> needs to run
948 <prgn>clean</prgn> first, it is a good idea to
949 <tt>touch build</tt> when the build process is
950 complete. This will ensure that if <tt>debian/rules
951 build</tt> is run again it will not rebuild the
956 <tag><tt>binary</tt>, <tt>binary-arch</tt>,
957 <tt>binary-indep</tt>
961 The <prgn>binary</prgn> target should be all that is
962 necessary for the user to build the binary
963 package. All these targets are required to be
964 non-interactive. It is split into two parts:
965 <prgn>binary-arch</prgn> builds the packages' output
966 files which are specific to a particular
967 architecture, and <prgn>binary-indep</prgn> builds
972 <prgn>binary</prgn> should usually be a target with
973 no commands which simply depends on
974 <prgn>binary-arch</prgn> and
975 <prgn>binary-indep</prgn>.
979 Both <prgn>binary-*</prgn> targets should depend on
980 the <prgn>build</prgn> target, above, so that the
981 package is built if it has not been already. It
982 should then create the relevant binary package(s),
983 using <prgn>dpkg-gencontrol</prgn> to make their
984 control files and <prgn>dpkg-deb</prgn> to build
985 them and place them in the parent of the top level
990 If one of the <prgn>binary-*</prgn> targets has
991 nothing to do (this will be always be the case if
992 the source generates only a single binary package,
993 whether architecture-dependent or not) it
994 <em>must</em> still exist, but should always
999 <ref id="binarypkg"> describes how to construct
1004 The <prgn>binary</prgn> targets must be invoked as
1009 <tag><tt>clean</tt></tag>
1013 This should undo any effects that the
1014 <prgn>build</prgn> and <prgn>binary</prgn> targets
1015 may have had, except that it should leave alone any
1016 output files created in the parent directory by a
1017 run of <prgn>binary</prgn>. This target is required
1018 to be non-interactive.
1022 If a <prgn>build</prgn> file is touched at the end
1023 of the <prgn>build</prgn> target, as suggested
1024 above, it must be removed as the first thing that
1025 <prgn>clean</prgn> does, so that running
1026 <prgn>build</prgn> again after an interrupted
1027 <prgn>clean</prgn> doesn't think that everything is
1032 The <prgn>clean</prgn> target must be invoked as
1033 root if <prgn>binary</prgn> has been invoked since
1034 the last <prgn>clean</prgn>, or if
1035 <prgn>build</prgn> has been invoked as root (since
1036 <prgn>build</prgn> may create directories, for
1041 <tag><tt>get-orig-source</tt> (optional)</tag>
1045 This target fetches the most recent version of the
1046 original source package from a canonical archive
1047 site (via FTP or WWW, for example), does any
1048 necessary rearrangement to turn it into the original
1049 source tarfile format described below, and leaves it
1050 in the current directory.
1054 This target may be invoked in any directory, and
1055 should take care to clean up any temporary files it
1060 This target is optional, but providing it if
1061 possible is a good idea.
1067 The <prgn>build</prgn>, <prgn>binary</prgn> and
1068 <prgn>clean</prgn> targets must be invoked with a current
1069 directory of the package's top-level directory.
1074 Additional targets may exist in <tt>debian/rules</tt>,
1075 either as published or undocumented interfaces or for the
1076 package's internal use.
1081 <sect1><heading><tt>debian/control</tt>
1085 This file contains version-independent details about the
1086 source package and about the binary packages it creates.
1090 It is a series of sets of control fields, each
1091 syntactically similar to a binary package control file.
1092 The sets are separated by one or more blank lines. The
1093 first set is information about the source package in
1094 general; each subsequent set describes one binary package
1095 that the source tree builds.
1099 The syntax and semantics of the fields are described below
1100 in <ref id="controlfields">.
1104 The general (binary-package-independent) fields are:
1105 <list compact="compact">
1107 <p><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</p>
1110 <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
1114 <qref id="f-classification"><tt>Section</tt> and
1115 <tt>Priority</tt></qref>
1116 (classification, mandatory)
1121 <qref id="f-Standards-Version"><tt>Standards-Version</tt></qref>
1127 The per-binary-package fields are:
1128 <list compact="compact">
1130 <p><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</p>
1134 <qref id="f-Architecture"><tt>Architecture</tt></qref>
1138 <p><qref id="descriptions"><tt>Description</tt></qref></p>
1142 <qref id="f-classification"><tt>Section</tt> and
1143 <tt>Priority</tt></qref> (classification)</p>
1146 <p><qref id="f-Essential"><tt>Essential</tt></qref></p>
1150 <qref id="relationships"><tt>Depends</tt> et
1151 al.</qref> (package interrelationships)
1157 These fields are used by <prgn>dpkg-gencontrol</prgn> to
1158 generate control files for binary packages (see below), by
1159 <prgn>dpkg-genchanges</prgn> to generate the
1160 <tt>.changes</tt> file to accompany the upload, and by
1161 <prgn>dpkg-source</prgn> when it creates the <tt>.dsc</tt>
1162 source control file as part of a source archive.
1166 The fields here may contain variable references - their
1167 values will be substituted by
1168 <prgn>dpkg-gencontrol</prgn>, <prgn>dpkg-genchanges</prgn>
1169 or <prgn>dpkg-source</prgn> when they generate output
1170 control files. See <ref id="srcsubstvars"> for details.
1173 <p> <sect2><heading>User-defined fields
1177 Additional user-defined fields may be added to the
1178 source package control file. Such fields will be
1179 ignored, and not copied to (for example) binary or
1180 source package control files or upload control files.
1184 If you wish to add additional unsupported fields to
1185 these output files you should use the mechanism
1190 Fields in the main source control information file with
1191 names starting <tt>X</tt>, followed by one or more of
1192 the letters <tt>BCS</tt> and a hyphen <tt>-</tt>, will
1193 be copied to the output files. Only the part of the
1194 field name after the hyphen will be used in the output
1195 file. Where the letter <tt>B</tt> is used the field
1196 will appear in binary package control files, where the
1197 letter <tt>S</tt> is used in source package control
1198 files and where <tt>C</tt> is used in upload control
1199 (<tt>.changes</tt>) files.
1203 For example, if the main source information control file
1206 XBS-Comment: I stand between the candle and the star.
1208 then the binary and source package control files will contain the
1211 Comment: I stand between the candle and the star.
1218 <sect1 id="dpkgchangelog"><heading><tt>debian/changelog</tt>
1222 This file records the changes to the Debian-specific parts of the
1226 Though there is nothing stopping an author who is also
1227 the Debian maintainer from using it for all their
1228 changes, it will have to be renamed if the Debian and
1229 upstream maintainers become different
1236 It has a special format which allows the package building
1237 tools to discover which version of the package is being
1238 built and find out other release-specific information.
1242 That format is a series of entries like this:
1244 <var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
1246 * <var>change details</var>
1247 <var>more change details</var>
1248 * <var>even more change details</var>
1250 -- <var>maintainer name and email address</var> <var>date</var>
1255 <var>package</var> and <var>version</var> are the source
1256 package name and version number.
1260 <var>distribution(s)</var> lists the distributions where
1261 this version should be installed when it is uploaded - it
1262 is copied to the <tt>Distribution</tt> field in the
1263 <tt>.changes</tt> file. See <ref id="f-Distribution">.
1267 <var>urgency</var> is the value for the <tt>Urgency</tt>
1268 field in the <tt>.changes</tt> file for the upload. See
1269 <ref id="f-Urgency">. It is not possible to specify an
1270 urgency containing commas; commas are used to separate
1271 <tt><var>keyword</var>=<var>value</var></tt> settings in
1272 the <prgn>dpkg</prgn> changelog format (though there is
1273 currently only one useful <var>keyword</var>,
1278 The change details may in fact be any series of lines
1279 starting with at least two spaces, but conventionally each
1280 change starts with an asterisk and a separating space and
1281 continuation lines are indented so as to bring them in
1282 line with the start of the text above. Blank lines may be
1283 used here to separate groups of changes, if desired.
1287 The maintainer name and email address should <em>not</em>
1288 necessarily be those of the usual package maintainer.
1289 They should be the details of the person doing
1290 <em>this</em> version. The information here will be
1291 copied to the <tt>.changes</tt> file, and then later used
1292 to send an acknowledgement when the upload has been
1297 The <var>date</var> should be in RFC822 format
1300 This is generated by the <prgn>822-date</prgn>
1303 </footnote>; it should include the timezone specified
1304 numerically, with the timezone name or abbreviation
1305 optionally present as a comment.
1309 The first `title' line with the package name should start
1310 at the left hand margin; the `trailer' line with the
1311 maintainer and date details should be preceded by exactly
1312 one space. The maintainer details and the date must be
1313 separated by exactly two spaces.
1317 An Emacs mode for editing this format is available: it is
1318 called <tt>debian-changelog-mode</tt>. You can have this
1319 mode selected automatically when you edit a Debian
1320 changelog by adding a local variables clause to the end of
1324 <sect2><heading>Defining alternative changelog formats
1328 It is possible to use a different format to the standard
1329 one, by providing a parser for the format you wish to
1334 In order to have <tt>dpkg-parsechangelog</tt> run your
1335 parser, you must include a line within the last 40 lines
1336 of your file matching the Perl regular expression:
1337 <tt>\schangelog-format:\s+([0-9a-z]+)\W</tt> The part in
1338 parentheses should be the name of the format. For
1339 example, you might say:
1341 @@@ changelog-format: joebloggs @@@
1343 Changelog format names are non-empty strings of alphanumerics.
1347 If such a line exists then <tt>dpkg-parsechangelog</tt>
1348 will look for the parser as
1349 <tt>/usr/lib/dpkg/parsechangelog/<var>format-name</var></tt>
1351 <tt>/usr/local/lib/dpkg/parsechangelog/<var>format-name</var></tt>;
1352 it is an error for it not to find it, or for it not to
1353 be an executable program. The default changelog format
1354 is <tt>dpkg</tt>, and a parser for it is provided with
1355 the <tt>dpkg</tt> package.
1359 The parser will be invoked with the changelog open on
1360 standard input at the start of the file. It should read
1361 the file (it may seek if it wishes) to determine the
1362 information required and return the parsed information
1363 to standard output in the form of a series of control
1364 fields in the standard format. By default it should
1365 return information about only the most recent version in
1366 the changelog; it should accept a
1367 <tt>-v<var>version</var></tt> option to return changes
1368 information from all versions present <em>strictly
1369 after</em> <var>version</var>, and it should then be an
1370 error for <var>version</var> not to be present in the
1376 <list compact="compact">
1378 <p><qref id="f-Source"><tt>Source</tt></qref></p>
1381 <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
1385 <qref id="f-Distribution"><tt>Distribution</tt></qref>
1390 <p><qref id="f-Urgency"><tt>Urgency</tt></qref> (mandatory)</p>
1394 <qref id="f-Maintainer"><tt>Maintainer</tt></qref>
1399 <p><qref id="f-Date"><tt>Date</tt></qref></p>
1403 <qref id="f-Changes"><tt>Changes</tt></qref>
1410 If several versions are being returned (due to the use
1411 of <tt>-v</tt>), the urgency value should be of the
1412 highest urgency code listed at the start of any of the
1413 versions requested followed by the concatenated
1414 (space-separated) comments from all the versions
1415 requested; the maintainer, version, distribution and
1416 date should always be from the most recent version.
1420 For the format of the <tt>Changes</tt> field see <ref
1425 If the changelog format which is being parsed always or
1426 almost always leaves a blank line between individual
1427 change notes these blank lines should be stripped out,
1428 so as to make the resulting output compact.
1432 If the changelog format does not contain date or package
1433 name information this information should be omitted from
1434 the output. The parser should not attempt to synthesise
1435 it or find it from other sources.
1439 If the changelog does not have the expected format the
1440 parser should exit with a nonzero exit status, rather
1441 than trying to muddle through and possibly generating
1446 A changelog parser may not interact with the user at
1450 <sect1 id="srcsubstvars"><heading><tt>debian/substvars</tt>
1451 and variable substitutions
1455 When <prgn>dpkg-gencontrol</prgn>,
1456 <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
1457 generate control files they do variable substitutions on
1458 their output just before writing it. Variable
1459 substitutions have the form
1460 <tt>${<var>variable-name</var>}</tt>. The optional file
1461 <tt>debian/substvars</tt> contains variable substitutions
1462 to be used; variables can also be set directly from
1463 <tt>debian/rules</tt> using the <tt>-V</tt> option to the
1464 source packaging commands, and certain predefined
1465 variables are available.
1469 The is usually generated and modified dynamically by
1470 <tt>debian/rules</tt> targets; in this case it must be
1471 removed by the <prgn>clean</prgn> target.
1475 See <manref name="dpkg-source" section="1"> for full
1476 details about source variable substitutions, including the
1477 format of <tt>debian/substvars</tt>.</p>
1480 <sect1><heading><tt>debian/files</tt>
1484 This file is not a permanent part of the source tree; it
1485 is used while building packages to record which files are
1486 being generated. <prgn>dpkg-genchanges</prgn> uses it
1487 when it generates a <tt>.changes</tt> file.
1491 It should not exist in a shipped source package, and so it
1492 (and any backup files or temporary files such as
1496 <tt>files.new</tt> is used as a temporary file by
1497 <prgn>dpkg-gencontrol</prgn> and
1498 <prgn>dpkg-distaddfile</prgn> - they write a new
1499 version of <tt>files</tt> here before renaming it,
1500 to avoid leaving a corrupted copy if an error
1503 </footnote>) should be removed by the
1504 <prgn>clean</prgn> target. It may also be wise to
1505 ensure a fresh start by emptying or removing it at the
1506 start of the <prgn>binary</prgn> target.
1510 <prgn>dpkg-gencontrol</prgn> adds an entry to this file
1511 for the <tt>.deb</tt> file that will be created by
1512 <prgn>dpkg-deb</prgn> from the control file that it
1513 generates, so for most packages all that needs to be done
1514 with this file is to delete it in <prgn>clean</prgn>.
1518 If a package upload includes files besides the source
1519 package and any binary packages whose control files were
1520 made with <prgn>dpkg-gencontrol</prgn> then they should be
1521 placed in the parent of the package's top-level directory
1522 and <prgn>dpkg-distaddfile</prgn> should be called to add
1523 the file to the list in <tt>debian/files</tt>.</p>
1526 <sect1><heading><tt>debian/tmp</tt>
1530 This is the canonical temporary location for the
1531 construction of binary packages by the <prgn>binary</prgn>
1532 target. The directory <tt>tmp</tt> serves as the root of
1533 the filesystem tree as it is being constructed (for
1534 example, by using the package's upstream makefiles install
1535 targets and redirecting the output there), and it also
1536 contains the <tt>DEBIAN</tt> subdirectory. See <ref
1541 If several binary packages are generated from the same
1542 source tree it is usual to use several
1543 <tt>debian/tmp<var>something</var></tt> directories, for
1544 example <tt>tmp-a</tt> or <tt>tmp-doc</tt>.
1548 Whatever <tt>tmp</tt> directories are created and used by
1549 <prgn>binary</prgn> must of course be removed by the
1550 <prgn>clean</prgn> target.</p></sect1>
1554 <sect id="sourcearchives"><heading>Source packages as archives
1558 As it exists on the FTP site, a Debian source package
1559 consists of three related files. You must have the right
1560 versions of all three to be able to use them.
1565 <tag>Debian source control file - <tt>.dsc</tt></tag>
1569 This file contains a series of fields, identified and
1570 separated just like the fields in the control file of
1571 a binary package. The fields are listed below; their
1572 syntax is described above, in <ref id="controlfields">.
1573 <list compact="compact">
1575 <p><qref id="f-Source"><tt>Source</tt></qref></p>
1578 <p><qref id="versions"><tt>Version</tt></qref></p>
1581 <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
1584 <p><qref id="f-Binary"><tt>Binary</tt></qref></p>
1587 <p><qref id="f-Architecture"><tt>Architecture</tt></qref></p>
1591 <qref id="f-Standards-Version"><tt>Standards-Version</tt></qref></p>
1594 <p><qref id="f-Files"><tt>Files</tt></qref></p>
1599 The source package control file is generated by
1600 <prgn>dpkg-source</prgn> when it builds the source
1601 archive, from other files in the source package,
1602 described above. When unpacking it is checked against
1603 the files and directories in the other parts of the
1604 source package, as described below.</p>
1608 Original source archive -
1610 <var>package</var>_<var>upstream-version</var>.orig.tar.gz
1617 This is a compressed (with <tt>gzip -9</tt>)
1618 <prgn>tar</prgn> file containing the source code from
1619 the upstream authors of the program. The tarfile
1620 unpacks into a directory
1621 <tt><var>package</var>-<var>upstream-version</var>.orig</tt>,
1622 and does not contain files anywhere other than in
1623 there or in its subdirectories.</p>
1627 Debianisation diff -
1629 <var>package</var>_<var>upstream_version-revision</var>.diff.gz
1635 This is a unified context diff (<tt>diff -u</tt>)
1636 giving the changes which are required to turn the
1637 original source into the Debian source. These changes
1638 may only include editing and creating plain files.
1639 The permissions of files, the targets of symbolic
1640 links and the characteristics of special files or
1641 pipes may not be changed and no files may be removed
1646 All the directories in the diff must exist, except the
1647 <tt>debian</tt> subdirectory of the top of the source
1648 tree, which will be created by
1649 <prgn>dpkg-source</prgn> if necessary when unpacking.
1653 The <prgn>dpkg-source</prgn> program will
1654 automatically make the <tt>debian/rules</tt> file
1655 executable (see below).</p></item>
1660 If there is no original source code - for example, if the
1661 package is specially prepared for Debian or the Debian
1662 maintainer is the same as the upstream maintainer - the
1663 format is slightly different: then there is no diff, and the
1665 <tt><var>package</var>_<var>version</var>.tar.gz</tt> and
1666 contains a directory
1667 <tt><var>package</var>-<var>version</var></tt>.
1671 <sect><heading>Unpacking a Debian source package without
1672 <prgn>dpkg-source</prgn>
1676 <tt>dpkg-source -x</tt> is the recommended way to unpack a
1677 Debian source package. However, if it is not available it
1678 is possible to unpack a Debian source archive as follows:
1679 <enumlist compact="compact">
1682 Untar the tarfile, which will create a <tt>.orig</tt>
1686 <p>Rename the <tt>.orig</tt> directory to
1687 <tt><var>package</var>-<var>version</var></tt>.</p>
1691 Create the subdirectory <tt>debian</tt> at the top of
1692 the source tree.</p>
1694 <item><p>Apply the diff using <tt>patch -p0</tt>.</p>
1696 <item><p>Untar the tarfile again if you want a copy of the original
1697 source code alongside the Debianised version.</p>
1702 It is not possible to generate a valid Debian source archive
1703 without using <prgn>dpkg-source</prgn>. In particular,
1704 attempting to use <prgn>diff</prgn> directly to generate the
1705 <tt>.diff.gz</tt> file will not work.
1708 <sect1><heading>Restrictions on objects in source packages
1712 The source package may not contain any hard links
1715 This is not currently detected when building source
1716 packages, but only when extracting
1722 Hard links may be permitted at some point in the
1723 future, but would require a fair amount of
1726 </footnote>, device special files, sockets or setuid or
1730 Setgid directories are allowed.
1736 The source packaging tools manage the changes between the
1737 original and Debianised source using <prgn>diff</prgn> and
1738 <prgn>patch</prgn>. Turning the original source tree as
1739 included in the <tt>.orig.tar.gz</tt> into the debianised
1740 source must not involve any changes which cannot be
1741 handled by these tools. Problematic changes which cause
1742 <prgn>dpkg-source</prgn> to halt with an error when
1743 building the source package are:
1744 <list compact="compact">
1745 <item><p>Adding or removing symbolic links, sockets or pipes.</p>
1747 <item><p>Changing the targets of symbolic links.</p>
1749 <item><p>Creating directories, other than <tt>debian</tt>.</p>
1751 <item><p>Changes to the contents of binary files.</p></item>
1752 </list> Changes which cause <prgn>dpkg-source</prgn> to
1753 print a warning but continue anyway are:
1754 <list compact="compact">
1757 Removing files, directories or symlinks.
1760 Renaming a file is not treated specially - it is
1761 seen as the removal of the old file (which
1762 generates a warning, but is otherwise ignored),
1763 and the creation of the new
1770 Changed text files which are missing the usual final
1771 newline (either in the original or the modified
1776 Changes which are not represented, but which are not detected by
1777 <prgn>dpkg-source</prgn>, are:
1778 <list compact="compact">
1779 <item><p>Changing the permissions of files (other than
1780 <tt>debian/rules</tt>) and directories.</p></item>
1785 The <tt>debian</tt> directory and <tt>debian/rules</tt>
1786 are handled specially by <prgn>dpkg-source</prgn> - before
1787 applying the changes it will create the <tt>debian</tt>
1788 directory, and afterwards it will make
1789 <tt>debian/rules</tt> world-exectuable.
1795 <chapt id="controlfields"><heading>Control files and their fields
1799 Many of the tools in the <prgn>dpkg</prgn> suite manipulate
1800 data in a common format, known as control files. Binary and
1801 source packages have control data as do the <tt>.changes</tt>
1802 files which control the installation of uploaded files, and
1803 <prgn>dpkg</prgn>'s internal databases are in a similar
1807 <sect><heading>Syntax of control files
1811 A file consists of one or more paragraphs of fields. The
1812 paragraphs are separated by blank lines. Some control files
1813 only allow one paragraph; others allow several, in which
1814 case each paragraph often refers to a different package.
1818 Each paragraph is a series of fields and values; each field
1819 consists of a name, followed by a colon and the value. It
1820 ends at the end of the line. Horizontal whitespace (spaces
1821 and tabs) may occur before or after the value and is ignored
1822 there; it is conventional to put a single space after the
1827 Some fields' values may span several lines; in this case
1828 each continuation line <em>must</em> start with a space or
1829 tab. Any trailing spaces or tabs at the end of individual
1830 lines of a field value are ignored.
1834 Except where otherwise stated only a single line of data is
1835 allowed and whitespace is not significant in a field body.
1836 Whitespace may never appear inside names (of packages,
1837 architectures, files or anything else), version numbers or
1838 in between the characters of multi-character version
1843 Field names are not case-sensitive, but it is usual to
1844 capitalise the fields using mixed case as shown below.
1848 Blank lines, or lines consisting only of spaces and tabs,
1849 are not allowed within field values or between fields - that
1850 would mean a new paragraph.
1854 It is important to note that there are several fields which
1855 are optional as far as <prgn>dpkg</prgn> and the related
1856 tools are concerned, but which must appear in every Debian
1857 package, or whose omission may cause problems. When writing
1858 the control files for Debian packages you <em>must</em> read
1859 the Debian policy manual in conjuction with the details
1860 below and the list of fields for the particular file.</p>
1863 <sect><heading>List of fields
1866 <sect1 id="f-Package"><heading><tt>Package</tt>
1870 The name of the binary package. Package names consist of
1871 the alphanumerics and <tt>+</tt> <tt>-</tt> <tt>.</tt>
1872 (plus, minus and full stop).
1875 The characters <tt>@</tt> <tt>:</tt> <tt>=</tt>
1876 <tt>t</tt>t> <tt>_</tt> (at, colon, equals, percent
1877 and underscore) used to be legal and are still
1878 accepted when found in a package file, but may not be
1879 used in new packages
1885 They must be at least two characters and must start with
1886 an alphanumeric. In current versions of dpkg they are
1887 sort of case-sensitive<footnote><p>This is a
1888 bug.</p></footnote>; use lowercase package names unless
1889 the package you're building (or referring to, in other
1890 fields) is already using uppercase.</p>
1893 <sect1 id="f-Version"><heading><tt>Version</tt>
1897 This lists the source or binary package's version number -
1898 see <ref id="versions">.
1903 <sect1 id="f-Architecture"><heading><tt>Architecture</tt>
1907 This is the architecture string; it is a single word for
1908 the CPU architecture.
1912 <prgn>dpkg</prgn> will check the declared architecture of
1913 a binary package against its own compiled-in value before
1918 The special value <tt>all</tt> indicates that the package
1919 is architecture-independent.
1923 In the main <tt>debian/control</tt> file in the source
1924 package, or in the source package control file
1925 <tt>.dsc</tt>, a list of architectures (separated by
1926 spaces) is also allowed, as is the special value
1927 <tt>any</tt>. A list indicates that the source will build
1928 an architecture-dependent package, and will only work
1929 correctly on the listed architectures. <tt>any</tt>
1930 indicates that though the source package isn't dependent
1931 on any particular architecture and should compile fine on
1932 any one, the binary package(s) produced are not
1933 architecture-independent but will instead be specific to
1934 whatever the current build architecture is.
1938 In a <tt>.changes</tt> file the <tt>Architecture</tt>
1939 field lists the architecture(s) of the package(s)
1940 currently being uploaded. This will be a list; if the
1941 source for the package is being uploaded too the special
1942 entry <tt>source</tt> is also present.
1946 The current build architecture can be determined using <tt>dpkg
1947 --print-architecture</tt>.
1950 This actually invokes
1952 gcc --print-libgcc-file-name
1953 </example> and parses and decomposes the output and
1954 looks the CPU type from the GCC configuration in a
1955 table in <prgn>dpkg</prgn>. This is so that it will
1956 work if you're cross-compiling.
1958 </footnote> This value is automatically used by
1959 <prgn>dpkg-gencontrol</prgn> when building the control
1960 file for a binary package for which the source control
1961 information doesn't specify architecture <tt>all</tt>.
1965 There is a separate option,
1966 <tt>--print-installation-architecture</tt>, for finding
1967 out what architecture <prgn>dpkg</prgn> is willing to
1968 install. This information is also in the output of
1969 <tt>dpkg --version</tt>.</p>
1972 <sect1 id="f-Maintainer"><heading><tt>Maintainer</tt>
1976 The package maintainer's name and email address. The name
1977 should come first, then the email address inside angle
1978 brackets <tt><></tt> (in RFC822 format).
1982 If the maintainer's name contains a full stop then the
1983 whole field will not work directly as an email address due
1984 to a misfeature in the syntax specified in RFC822; a
1985 program using this field as an address must check for this
1986 and correct the problem if necessary (for example by
1987 putting the name in round brackets and moving it to the
1988 end, and bringing the email address forward).
1992 In a <tt>.changes</tt> file or parsed changelog data this
1993 contains the name and email address of the person
1994 responsible for the particular version in question - this
1995 may not be the package's usual maintainer.
1999 This field is usually optional in as far as the
2000 <prgn>dpkg</prgn> are concerned, but its absence when
2001 building packages usually generates a warning.</p>
2004 <sect1 id="f-Source"><heading><tt>Source</tt>
2008 This field identifies the source package name.
2012 In a main source control information or a
2013 <tt>.changes</tt> or <tt>.dsc</tt> file or parsed
2014 changelog data this may contain only the name of the
2019 In the control file of a binary package (or in a
2020 <tt>Packages</tt> file) it may be followed by a version
2021 number in parentheses.
2024 It is usual to leave a space after the package name if
2025 a version number is specified.
2027 </footnote> This version number may be omitted (and is, by
2028 <prgn>dpkg-gencontrol</prgn>) if it has the same value as
2029 the <tt>Version</tt> field of the binary package in
2030 question. The field itself may be omitted from a binary
2031 package control file when the source package has the same
2032 name and version as the binary package.
2036 <sect1><heading>Package interrelationship fields:
2037 <tt>Depends</tt>, <tt>Pre-Depends</tt>,
2038 <tt>Recommends</tt> <tt>Suggests</tt>, <tt>Conflicts</tt>,
2039 <tt>Provides</tt>, <tt>Replaces</tt>
2043 These fields describe the package's relationships with
2044 other packages. Their syntax and semantics are described
2045 in <ref id="relationships">.</p>
2048 <sect1 id="f-Description"><heading><tt>Description</tt>
2052 In a binary package <tt>Packages</tt> file or main source
2053 control file this field contains a description of the
2054 binary package, in a special format. See <ref
2055 id="descriptions"> for details.
2059 In a <tt>.changes</tt> file it contains a summary of the
2060 descriptions for the packages being uploaded. The part of
2061 the field before the first newline is empty; thereafter
2062 each line has the name of a binary package and the summary
2063 description line from that binary package. Each line is
2064 indented by one space.</p>
2067 <sect1 id="f-Essential"><heading><tt>Essential</tt>
2071 This is a boolean field which may occur only in the
2072 control file of a binary package (or in the
2073 <tt>Packages</tt> file) or in a per-package fields
2074 paragraph of a main source control data file.
2078 If set to <tt>yes</tt> then <prgn>dpkg</prgn> and
2079 <prgn>dselect</prgn> will refuse to remove the package
2080 (though it can be upgraded and/or replaced). The other
2081 possible value is <tt>no</tt>, which is the same as not
2082 having the field at all.</p>
2085 <sect1 id="f-classification"><heading><tt>Section</tt> and
2090 These two fields classify the package. The
2091 <tt>Priority</tt> represents how important that it is that
2092 the user have it installed; the <tt>Section</tt>
2093 represents an application area into which the package has
2098 When they appear in the <tt>debian/control</tt> file these
2099 fields give values for the section and priority subfields
2100 of the <tt>Files</tt> field of the <tt>.changes</tt> file,
2101 and give defaults for the section and priority of the
2106 The section and priority are represented, though not as
2107 separate fields, in the information for each file in the
2108 <qref id="f-Files"><tt>-File</tt></qref>field of a
2109 <tt>.changes</tt> file. The section value in a
2110 <tt>.changes</tt> file is used to decide where to install
2111 a package in the FTP archive.
2115 These fields are not used by by <prgn>dpkg</prgn> proper,
2116 but by <prgn>dselect</prgn> when it sorts packages and
2117 selects defaults. See the Debian policy manual for the
2118 priorities in use and the criteria for selecting the
2119 priority for a Debian package, and look at the Debian FTP
2120 archive for a list of currently in-use priorities.
2124 These fields may appear in binary package control files,
2125 in which case they provide a default value in case the
2126 <tt>Packages</tt> files are missing the information.
2127 <prgn>dpkg</prgn> and <prgn>dselect</prgn> will only use
2128 the value from a <tt>.deb</tt> file if they have no other
2129 information; a value listed in a <tt>Packages</tt> file
2130 will always take precedence. By default
2131 <prgn>dpkg-genchanges</prgn> does not include the section
2132 and priority in the control file of a binary package - use
2133 the <tt>-isp</tt>, <tt>-is</tt> or <tt>-ip</tt> options to
2134 achieve this effect.</p>
2137 <sect1 id="f-Binary"><heading><tt>Binary</tt>
2141 This field is a list of binary packages.
2145 When it appears in the <tt>.dsc</tt> file it is the list
2146 of binary packages which a source package can produce. It
2147 does not necessarily produce all of these binary packages
2148 for every architecture. The source control file doesn't
2149 contain details of which architectures are appropriate for
2150 which of the binary packages.
2154 When it appears in a <tt>.changes</tt> file it lists the
2155 names of the binary packages actually being uploaded.
2159 The syntax is a list of binary packages separated by
2163 A space after each comma is conventional.
2165 </footnote> Currently the packages must be separated using
2166 only spaces in the <tt>.changes</tt> file.</p>
2169 <sect1 id="f-Installed-Size"><heading><tt>Installed-Size</tt>
2173 This field appears in the control files of binary
2174 packages, and in the <tt>Packages</tt> files. It gives
2175 the total amount of disk space required to install the
2180 The disk space is represented in kilobytes as a simple
2184 <sect1 id="f-Files"><heading><tt>Files</tt>
2188 This field contains a list of files with information about
2189 each one. The exact information and syntax varies with
2190 the context. In all cases the the part of the field
2191 contents on the same line as the field name is empty. The
2192 remainder of the field is one line per file, each line
2193 being indented by one space and containing a number of
2194 sub-fields separated by spaces.
2198 In the <tt>.dsc</tt> (Debian source control) file each
2199 line contains the MD5 checksum, size and filename of the
2200 tarfile and (if applicable) diff file which make up the
2201 remainder of the source package.
2204 That is, the parts which are not the
2207 </footnote> The exact forms of the filenames are described
2208 in <ref id="sourcearchives">.
2212 In the <tt>.changes</tt> file this contains one line per
2213 file being uploaded. Each line contains the MD5 checksum,
2214 size, section and priority and the filename. The section
2215 and priority are the values of the corresponding fields in
2216 the main source control file - see <ref
2217 id="f-classification">. If no section or priority is
2218 specified then <tt>-</tt> should be used, though section
2219 and priority values must be specified for new packages to
2220 be installed properly.
2224 The special value <tt>byhand</tt> for the section in a
2225 <tt>.changes</tt> file indicates that the file in question
2226 is not an ordinary package file and must by installed by
2227 hand by the distribution maintainers. If the section is
2228 <tt>byhand</tt> the priority should be <tt>-</tt>.
2232 If a new Debian revision of a package is being shipped and
2233 no new original source archive is being distributed the
2234 <tt>.dsc</tt> must still contain the <tt>Files</tt> field
2235 entry for the original source archive
2236 <tt><var>package</var>-<var>upstream-version</var>.orig.tar.gz</tt>,
2237 but the <tt>.changes</tt> file should leave it out. In
2238 this case the original source archive on the distribution
2239 site must match exactly, byte-for-byte, the original
2240 source archive which was used to generate the
2241 <tt>.dsc</tt> file and diff which are being uploaded.</p>
2246 id="f-Standards-Version"><heading><tt>Standards-Version</tt>
2250 The most recent version of the standards (the
2251 <prgn>dpkg</prgn> programmers' and policy manuals and
2252 associated texts) with which the package complies. This
2253 is updated manually when editing the source package to
2254 conform to newer standards; it can sometimes be used to
2255 tell when a package needs attention.
2259 Its format is the same as that of a version number except
2260 that no epoch or Debian revision is allowed - see <ref
2265 <sect1 id="f-Distribution"><heading><tt>Distribution</tt>
2269 In a <tt>.changes</tt> file or parsed changelog output
2270 this contains the (space-separated) name(s) of the
2271 distribution(s) where this version of the package should
2272 be or was installed. Distribution names follow the rules
2273 for package names. (See <ref id="f-Package">).
2277 Current distribution values are:
2279 <tag><em>stable</em></tag>
2282 This is the current `released' version of Debian
2283 GNU/Linux. A new version is released approximately
2284 every 3 months after the <em>development</em> code has
2285 been <em>frozen</em> for a month of testing. Once the
2286 distribution is <em>stable</em> only major bug fixes
2287 are allowed. When changes are made to this
2288 distribution, the minor version number is increased
2289 (for example: 1.2 becomes 1.2.1 then 1.2.2, etc).
2293 <tag><em>unstable</em></tag>
2296 This distribution value refers to the
2297 <em>developmental</em> part of the Debian distribution
2298 tree. New packages, new upstream versions of packages
2299 and bug fixes go into the <em>unstable</em> directory
2300 tree. Download from this distribution at your own
2304 <tag><em>contrib</em></tag>
2307 The packages with this distribution value do not meet
2308 the criteria for inclusion in the main Debian
2309 distribution as defined by the Policy Manual, but meet
2310 the criteria for the <em>contrib</em>
2311 Distribution. There is currently no distinction
2312 between stable and unstable packages in the
2313 <em>contrib</em> or <em>non-free</em>
2314 distributions. Use your best judgement in downloading
2315 from this Distribution.</p>
2318 <tag><em>non-free</em></tag>
2321 Like the packages in the <em>contrib</em> seciton,
2322 the packages in <em>non-free</em> do not meet the
2323 criteria for inclusion in the main Debian distribution
2324 as defined by the Policy Manual. Again, use your best
2325 judgement in downloading from this Distribution.</p>
2327 <tag><em>experimental</em></tag>
2330 The packages with this distribution value are deemed
2331 by their maintainers to be high risk. Oftentimes they
2332 represent early beta or developmental packages from
2333 various sources that the maintainers want people to
2334 try, but are not ready to be a part of the other parts
2335 of the Debian distribution tree. Download at your own
2339 <tag><em>frozen</em></tag>
2342 From time to time, (currently, every 3 months) the
2343 <em>unstable</em> distribution enters a state of
2344 `code-freeze' in anticipation of release as a
2345 <em>stable</em> version. During this period of testing
2346 (usually 4 weeks) only fixes for existing or
2347 newly-discovered bugs will be allowed.
2350 </taglist> You should list <em>all</em> distributions that
2351 the package should be installed into. Except in unusual
2352 circumstances, installations to <em>stable</em> should also
2353 go into <em>frozen</em> (if it exists) and
2354 <em>unstable</em>. Likewise, installations into
2355 <em>frozen</em> should also go into <em>unstable</em>.</p>
2358 <sect1 id="f-Urgency"><heading><tt>Urgency</tt>
2362 This is a description of how important it is to upgrade to
2363 this version from previous ones. It consists of a single
2364 keyword usually taking one of the values <tt>LOW</tt>,
2365 <tt>MEDIUM</tt> or <tt>HIGH</tt>) followed by an optional
2366 commentary (separated by a space) which is usually in
2367 parentheses. For example:
2369 Urgency: LOW (HIGH for diversions users)
2374 This field appears in the <tt>.changes</tt> file and in
2375 parsed changelogs; its value appears as the value of the
2376 <tt>urgency</tt> attribute in a <prgn>dpkg</prgn>-style
2377 changelog (see <ref id="dpkgchangelog">).
2381 Urgency keywords are not case-sensitive.</p>
2384 <sect1 id="f-Date"><heading><tt>Date</tt>
2388 In <tt>.changes</tt> files and parsed changelogs, this
2389 gives the date the package was built or last edited.</p>
2392 <sect1 id="f-Format"><heading><tt>Format</tt>
2396 This field occurs in <tt>.changes</tt> files, and
2397 specifies a format revision for the file. The format
2398 described here is version <tt>1.5</tt>. The syntax of the
2399 format value is the same as that of a package version
2400 number except that no epoch or Debian revision is allowed
2401 - see <ref id="versions">.</p>
2404 <sect1 id="f-Changes"><heading><tt>Changes</tt>
2408 In a <tt>.changes</tt> file or parsed changelog this field
2409 contains the human-readable changes data, describing the
2410 differences between the last version and the current one.
2414 There should be nothing in this field before the first
2415 newline; all the subsequent lines must be indented by at
2416 least one space; blank lines must be represented by a line
2417 consiting only of a space and a full stop.
2421 Each version's change information should be preceded by a
2422 `title' line giving at least the version, distribution(s)
2423 and urgency, in a human-readable way.
2427 If data from several versions is being returned the entry
2428 for the most recent version should be returned first, and
2429 entries should be separated by the representation of a
2430 blank line (the `title' line may also be followed by the
2431 representation of blank line).</p>
2434 <sect1 id="f-Filename"><heading><tt>Filename</tt> and
2435 <tt>MSDOS-Filename</tt>
2439 These fields in <tt>Packages</tt> files give the
2440 filename(s) of (the parts of) a package in the
2441 distribution directories, relative to the root of the
2442 Debian hierarchy. If the package has been split into
2443 several parts the parts are all listed in order, separated
2447 <sect1 id="f-Size"><heading><tt>Size</tt> and <tt>MD5sum</tt>
2451 These fields in <tt>Packages</tt> files give the size (in
2452 bytes, expressed in decimal) and MD5 checksum of the
2453 file(s) which make(s) up a binary package in the
2454 distribution. If the package is split into several parts
2455 the values for the parts are listed in order, separated by
2459 <sect1 id="f-Status"><heading><tt>Status</tt>
2463 This field in <prgn>dpkg</prgn>'s status file records
2464 whether the user wants a package installed, removed or
2465 left alone, whether it is broken (requiring
2466 reinstallation) or not and what its current state on the
2467 system is. Each of these pieces of information is a
2471 <sect1 id="f-Config-Version"><heading><tt>Config-Version</tt>
2475 If a package is not installed or not configured, this
2476 field in <prgn>dpkg</prgn>'s status file records the last
2477 version of the package which was successfully
2481 <sect1 id="f-Conffiles"><heading><tt>Conffiles</tt>
2485 This field in <prgn>dpkg</prgn>'s status file contains
2486 information about the automatically-managed configuration
2487 files held by a package. This field should <em>not</em>
2488 appear anywhere in a package!</p>
2491 <sect1><heading>Obsolete fields
2495 These are still recognised by <prgn>dpkg</prgn> but should
2496 not appear anywhere any more.
2497 <taglist compact="compact">
2499 <tag><tt>Revision</tt></tag>
2500 <tag><tt>Package-Revision</tt></tag>
2501 <tag><tt>Package_Revision</tt></tag>
2504 The Debian revision part of the package version was
2505 at one point in a separate control file field. This
2506 field went through several names.</p>
2509 <tag><tt>Recommended</tt></tag>
2510 <item><p>Old name for <tt>Recommends</tt></p>
2513 <tag><tt>Optional</tt></tag>
2514 <item><p>Old name for <tt>Suggests</tt>.</p>
2516 <tag><tt>Class</tt></tag>
2517 <item><p>Old name for <tt>Priority</tt>.</p>
2525 <chapt id="versions"><heading>Version numbering
2529 Every package has a version number, in its <tt>Version</tt>
2534 <prgn>dpkg</prgn> imposes an ordering on version numbers, so
2535 that it can tell whether packages are being up- or downgraded
2536 and so that <prgn>dselect</prgn> can tell whether a package it
2537 finds available is newer than the one installed on the system.
2538 The version number format has the most significant parts (as
2539 far as comparison is concerned) at the beginning.
2543 The version number format is:
2544 &lsqb<var>epoch/<tt>:</tt>]<var>upstream-version</var>[<tt>-/<var>debian-revision</var>].</tt></var>
2548 The three components here are:
2550 <tag><var>epoch</var></tag>
2554 This is a single unsigned integer, which should usually
2555 be small. It may be omitted, in which case zero is
2556 assumed. If it is omitted then the
2557 <var>upstream-version</var> may not contain any colons.
2561 It is provided to allow mistakes in the version numbers
2562 of older versions of a package, and also a package's
2563 previous version numbering schemes, to be left behind.
2567 <prgn>dpkg</prgn> will not usually display the epoch
2568 unless it is essential (non-zero, or if the
2569 <var>upstream-version</var> contains a colon);
2570 <prgn>dselect</prgn> does not display epochs at all in
2571 the main part of the package selection display.</p>
2574 <tag><var>upstream-version</var></tag>
2578 This is the main part of the version. It is usually
2579 version number of the original (`upstream') package of
2580 which the <tt>.deb</tt> file has been made, if this is
2581 applicable. Usually this will be in the same format as
2582 that specified by the upstream author(s); however, it
2583 may need to be reformatted to fit into
2584 <prgn>dpkg</prgn>'s format and comparison scheme.
2588 The comparison behaviour of <prgn>dpkg</prgn> with
2589 respect to the <var>upstream-version</var> is described
2590 below. The <var>upstream-version</var> portion of the
2591 version number is mandatory.
2595 The <var>upstream-version</var> may contain only
2596 alphanumerics and the characters <tt>+</tt> <tt>.</tt>
2597 <tt>-</tt> <tt>:</tt> (full stop, plus, hyphen, colon)
2598 and should start with a digit. If there is no
2599 <var>debian-revision</var> then hyphens are not allowed;
2600 if there is no <var>epoch</var> then colons are not
2604 <tag><var>debian-revision</var></tag>
2608 This part of the version represents the version of the
2609 modifications that were made to the package to make it a
2610 Debian binary package. It is in the same format as the
2611 <var>upstream-version</var> and <prgn>dpkg</prgn>
2612 compares it in the same way.
2616 It is optional; if it isn't present then the
2617 <var>upstream-version</var> may not contain a hyphen.
2618 This format represents the case where a piece of
2619 software was written specifically to be turned into a
2620 Debian binary package, and so there is only one
2621 `debianization' of it and therefore no revision
2622 indication is required.
2626 It is conventional to restart the
2627 <var>debian-revision</var> at <tt>1</tt> each time the
2628 <var>upstream-version</var> is increased.
2632 <prgn>dpkg</prgn> will break the
2633 <var>upstream-version</var> and
2634 <var>debian-revision</var> apart at the last hyphen in
2635 the string. The absence of a <var>debian-revision</var>
2636 compares earlier than the presence of one (but note that
2637 the <var>debian-revision</var> is the least significant
2638 part of the version number).
2642 The <var>debian-revision</var> may contain only
2643 alphanumerics and the characters <tt>+</tt> and
2644 <tt>.</tt> (plus and full stop).
2648 The <var>upstream-version</var> and <var>debian-revision</var> parts are
2649 compared by <prgn>dpkg</prgn> using the same algorithm:
2653 The strings are compared from left to right.
2657 First the initial part of each string consisting entirely of
2658 non-digit characters is determined. These two parts (one of
2659 which may be empty) are compared lexically. If a difference
2660 is found it is returned. The lexical comparison is a
2661 comparison of ASCII values modified so that all the letters
2662 sort earlier than all the non-letters.
2666 Then the initial part of the remainder of each string which
2667 consists entirely of digit characters is determined. The
2668 numerical values of these two parts are compared, and any
2669 difference found is returned as the result of the comparison.
2670 For these purposes an empty string (which can only occur at
2671 the end of one or both version strings being compared) counts
2676 These two steps are repeated (chopping initial non-digit
2677 strings and initial digit strings off from the start) until a
2678 difference is found or both strings are exhausted.
2682 Note that the purpose of epochs is to allow us to leave behind
2683 mistakes in version numbering, and to cope with situations
2684 where the version numbering changes. It is <em>not</em> there
2685 to cope with version numbers containing strings of letters
2686 which <prgn>dpkg</prgn> cannot interpret (such as
2687 <tt>ALPHA</tt> or <tt>pre-</tt>), or with silly orderings (the
2688 author of this manual has heard of a package whose versions
2689 went <tt>1.1</tt>, <tt>1.2</tt>, <tt>1.3</tt>, <tt>1</tt>,
2690 <tt>2.1</tt>, <tt>2.2</tt>, <tt>2</tt> and so forth).
2694 If an upstream package has problematic version numbers they
2695 should be converted to a sane form for use in the
2696 <tt>Version</tt> field.
2700 If you need to compare version numbers in a script, you may use
2701 <tt>dpkg --compare-versions ...</tt>. Type <tt>dpkg
2702 --help</tt> --> --for details on arguments.
2706 <chapt id="maintainerscripts"><heading>Package maintainer scripts
2707 and installation procedure
2710 <sect><heading>Introduction to package maintainer scripts
2714 It is possible supply scripts as part of a package which
2715 <prgn>dpkg</prgn> will run for you when your package is
2716 installed, upgraded or removed.
2720 These scripts should be the files <tt>preinst</tt>,
2721 <tt>postinst</tt>, <tt>prerm</tt> and <tt>postrm</tt> in the
2722 control area of the package. They must be proper exectuable
2723 files; if they are scripts (which is recommended) they must
2724 start with the usual <tt>#!</tt> convention. They should be
2725 readable and executable to anyone, and not world-writeable.
2729 <prgn>dpkg</prgn> looks at the exit status from these
2730 scripts. It is important that they exit with a non-zero
2731 status if there is an error, so that <prgn>dpkg</prgn> can
2732 stop its processing. For shell scripts this means that you
2733 <em>almost always</em> need to use <tt>set -e</tt> (this is
2734 usually true when writing shell scripts, in fact). It is
2735 also important, of course, that they don't exit with a
2736 non-zero status if everything went well.
2740 It is necessary for the error recovery procedures that the
2741 scripts be idempotent: ie, invoking the same script several
2742 times in the same situation should do no harm. If the first
2743 call failed, or aborted half way through for some reason,
2744 the second call should merely do the things that were left
2745 undone the first time, if any, and exit with a success
2750 When a package is upgraded a combination of the scripts from
2751 the old and new packages is called in amongst the other
2752 steps of the upgrade procedure. If your scripts are going
2753 to be at all complicated you need to be aware of this, and
2754 may need to check the arguments to your scripts.
2758 Broadly speaking the <prgn>preinst</prgn> is called before
2759 (a particular version of) a package is installed, and the
2760 <prgn>postinst</prgn> afterwards; the <prgn>prerm</prgn>
2761 before (a version of) a package is removed and the
2762 <prgn>postrm</prgn> afterwards.
2765 next paragraph by Guy Maor to close bug #2481
2768 <p> Programs called from maintainer scripts should not
2769 normally have a path prepended to them. Before installation
2770 is started <prgn>dpkg</prgn> checks to see if the programs
2771 <prgn>ldconfig</prgn>, <prgn>start-stop-daemon</prgn>,
2772 <prgn>install-info</prgn>, and <prgn>update-rc.d</prgn> can
2773 be found via the <tt>PATH</tt> environment variable. Those
2774 programs, and any other program that one would expect to on
2775 the <tt>PATH</tt>, should thus be invoked without an
2776 absolute pathname. Maintainer scripts should also not reset
2777 the <tt>PATH</tt>, though they might choose to modify it by
2778 pre- or appending package-specific directories. These
2779 considerations really apply to all shell scripts.</p>
2782 <sect id="mscriptsinstact"><heading>Summary of ways maintainer
2787 <list compact="compact">
2789 <p><var>new-preinst</var> <tt>install</tt></p>
2792 <p><var>new-preinst</var> <tt>install</tt>
2793 <var>old-version</var></p>
2796 <p><var>new-preinst</var> <tt>upgrade</tt>
2797 <var>old-version</var></p>
2800 <p><var>old-preinst</var> <tt>abort-upgrade</tt>
2801 <var>new-version</var>
2807 <list compact="compact">
2809 <p><var>postinst</var> <tt>configure</tt>
2810 <var>most-recently-configured-version</var></p>
2813 <p><var>old-postinst</var> <tt>abort-upgrade</tt>
2814 <var>new version</var></p>
2817 <p><var>conflictor's-postinst</var> <tt>abort-remove</tt>
2818 <tt>in-favour</tt> <var>package</var>
2819 <var>new-version</var></p>
2823 <var>deconfigured's-postinst</var>
2824 <tt>abort-deconfigure</tt> <tt>in-favour</tt>
2825 <var>failed-install-package</var> <var>version</var>
2826 <tt>removing</tt> <var>conflicting-package</var>
2833 <list compact="compact">
2835 <p><var>prerm</var> <tt>remove</tt></p>
2838 <p><var>old-prerm</var> <tt>upgrade</tt>
2839 <var>new-version</var></p>
2842 <p><var>new-prerm</var> <tt>failed-upgrade</tt>
2843 <var>old-version</var></p>
2846 <p><var>conflictor's-prerm</var> <tt>remove</tt>
2847 <tt>in-favour</tt> <var>package</var>
2848 <var>new-version</var></p>
2852 <var>deconfigured's-prerm</var> <tt>deconfigure</tt>
2853 <tt>in-favour</tt> <var>package-being-installed</var>
2854 <var>version</var> <tt>removing</tt>
2855 <var>conflicting-package</var>
2862 <list compact="compact">
2864 <p><var>postrm</var> <tt>remove</tt></p>
2867 <p><var>postrm</var> <tt>purge</tt></p>
2871 <var>old-postrm</var> <tt>upgrade</tt>
2872 <var>new-version</var></p>
2875 <p><var>new-postrm</var> <tt>failed-upgrade</tt>
2876 <var>old-version</var></p>
2879 <p><var>new-postrm</var> <tt>abort-install</tt></p>
2882 <p><var>new-postrm</var> <tt>abort-install</tt>
2883 <var>old-version</var></p>
2886 <p><var>new-postrm</var> <tt>abort-upgrade</tt>
2887 <var>old-version</var></p>
2891 <var>disappearer's-postrm</var> <tt>disappear</tt>
2892 <var>r>overwrit</var>r>
2893 <var>new-version</var></p></item>
2898 <sect id="unpackphase"><heading>Details of unpack phase of
2899 installation or upgrade
2903 The procedure on installation/upgrade/overwrite/disappear
2904 (ie, when running <tt>dpkg --unpack</tt>, or the unpack
2906 --install</tt>) is as follows. In each case if an error occurs the
2907 actions in are general run backwards - this means that the maintainer
2908 scripts are run with different arguments in reverse order. These are
2909 the `error unwind' calls listed below.
2916 <p>If a version the package is already
2919 <var>old-prerm</var> upgrade <var>new-version</var>
2924 If this gives an error (ie, a non-zero exit
2925 status), dpkg will attempt instead:
2927 <var>new-prerm</var> failed-upgrade <var>old-version</var>
2929 Error unwind, for both the above cases:
2931 <var>old-postinst</var> abort-upgrade <var>new-version</var>
2939 <p>If a `conflicting' package is being removed at the same time:
2943 If any packages depended on that conflicting
2944 package and <tt>--auto-deconfigure</tt> is
2945 specified, call, for each such package:
2947 <var>deconfigured's-prerm</var> deconfigure \
2948 in-favour <var>package-being-installed</var> <var>version</var> \
2949 removing <var>conflicting-package</var> <var>version</var>
2953 <var>deconfigured's-postinst</var> abort-deconfigure \
2954 in-favour <var>package-being-installed-but-failed</var> <var>version</var> \
2955 removing <var>conflicting-package</var> <var>version</var>
2957 The deconfigured packages are marked as
2958 requiring configuration, so that if
2959 <tt>--install</tt> is used they will be
2960 configured again if possible.</p>
2963 <p>To prepare for removal of the conflicting package, call:
2965 <var>conflictor's-prerm</var> remove in-favour <var>package</var> <var>new-version</var>
2969 <var>conflictor's-postinst</var> abort-remove \
2970 in-favour <var>package</var> <var>new-version</var>
2981 <p>If the package is being upgraded, call:
2983 <var>new-preinst</var> upgrade <var>old-version</var>
2988 Otherwise, if the package had some configuration
2989 files from a previous version installed (ie, it
2990 is in the `configuration files only' state):
2992 <var>new-preinst</var> install <var>old-version</var>
2996 <p>Otherwise (ie, the package was completely purged):
2998 <var>new-preinst</var> install
3000 Error unwind versions, respectively:
3002 <var>new-postrm</var> abort-upgrade <var>old-version</var>
3003 <var>new-postrm</var> abort-install <var>old-version</var>
3004 <var>new-postrm</var> abort-install
3014 The new package's files are unpacked, overwriting any
3015 that may be on the system already, for example any
3016 from the old version of the same package or from
3017 another package (backups of the old files are left
3018 around, and if anything goes wrong dpkg will attempt
3019 to put them back as part of the error unwind).
3023 It is an error for a package to contains files which
3024 are on the system in another package, unless
3025 <tt>Replaces</tt> is used (see <ref id="replaces">).
3026 Currently the <tt>--force-overwrite</tt> flag is
3027 enabled, downgrading it to a warning, but this may not
3032 It is a more serious error for a package to contain a
3033 plain file or other kind of nondirectory where another
3034 package has a directory (again, unless
3035 <tt>Replaces</tt> is used). This error can be
3036 overridden if desired using
3037 <tt>--force-overwrite-dir</tt>, but this is not
3042 Packages which overwrite each other's files produce
3043 behaviour which though deterministic is hard for the
3044 system administrator to understand. It can easily
3045 lead to `missing' programs if, for example, a package
3046 is installed which overwrites a file from another
3047 package, and is then removed again.
3050 Part of the problem is due to what is arguably a
3051 bug in <prgn>dpkg</prgn> .
3057 A directory will never be replaced by a symbolic links
3058 to a directory or vice versa; instead, the existing
3059 state (symlink or not) will be left alone and
3060 <prgn>dpkg</prgn> will follow the symlink if there is
3068 <p>If the package is being upgraded, call
3070 <var>old-postrm</var> upgrade <var>new-version</var>
3074 <p>If this fails, <prgn>dpkg</prgn> will attempt:
3076 <var>new-postrm</var> failed-upgrade <var>old-version</var>
3078 Error unwind, for both cases:
3080 <var>old-preinst</var> abort-upgrade <var>new-version</var>
3085 This is the point of no return - if <prgn>dpkg</prgn>
3086 gets this far, it won't back off past this point if an
3087 error occurs. This will leave the package in a fairly
3088 bad state, which will require a successful
3089 reinstallation to clear up, but it's when
3090 <prgn>dpkg</prgn> starts doing things that are
3095 Any files which were in the old version of the package
3096 but not in the new are removed.</p>
3099 <p>The new file list replaces the old.</p>
3102 <p>The new maintainer scripts replace the old.</p>
3106 <p>Any packages all of whose files have been overwritten during the
3107 installation, and which aren't required for
3108 dependencies, are considered to have been removed.
3109 For each such package,
3112 <p><prgn>dpkg</prgn> calls:
3114 <var>disappearer's-postrm</var> disappear \
3115 <var>overwriter</var> <var>overwriter-version</var>
3120 <p>The package's maintainer scripts are removed.
3125 It is noted in the status database as being in a
3126 sane state, namely not installed (any conffiles
3127 it may have are ignored, rather than being
3128 removed by <prgn>dpkg</prgn>). Note that
3129 disappearing packages do not have their prerm
3130 called, because <prgn>dpkg</prgn> doesn't know
3131 in advance that the package is going to
3140 Any files in the package we're unpacking that are also
3141 listed in the file lists of other packages are removed
3142 from those lists. (This will lobotomise the file list
3143 of the `conflicting' package if there is one.)
3148 The backup files made during installation, above, are
3155 The new package's status is now sane, and recorded as
3156 `unpacked'. Here is another point of no return - if
3157 the conflicting package's removal fails we do not
3158 unwind the rest of the installation; the conflicting
3159 package is left in a half-removed limbo.
3164 If there was a conflicting package we go and do the
3165 removal actions (described below), starting with the
3166 removal of the conflicting package's files (any that
3167 are also in the package being installed have already
3168 been removed from the conflicting package's file list,
3169 and so do not get removed now).
3176 <sect><heading>Details of configuration
3180 When we configure a package (this happens with <tt>dpkg
3181 --install</tt>, or with <tt>--configure</tt>), we first
3182 update the conffiles and then call:
3184 <var>postinst</var> configure <var>most-recently-configured-version</var>
3189 No attempt is made to unwind after errors during
3194 If there is no most recently configured version
3195 <prgn>dpkg</prgn> will pass a null argument; older versions
3196 of dpkg may pass <tt><unknown></tt> (including the
3197 angle brackets) in this case. Even older ones do not pass a
3198 second argument at all, under any circumstances.
3202 <sect><heading>Details of removal and/or configuration purging
3210 <var>prerm</var> remove
3216 The package's files are removed (except conffiles).
3221 <var>postrm</var> remove
3225 <p>All the maintainer scripts except the postrm are removed.
3229 If we aren't purging the package we stop here. Note
3230 that packages which have no postrm and no conffiles
3231 are automatically purged when removed, as there is no
3232 difference except for the <prgn>dpkg</prgn>
3237 The conffiles and any backup files (<tt>~</tt>-files,
3238 <tt>#*#</tt> files, <tt>%</tt>-files,
3239 <tt>.dpkg-{old,new,tmp}</tt>, etc.) are removed.</p>
3243 <var>postrm</var> purge
3247 <p>The package's file list is removed.</p>
3250 No attempt is made to unwind after errors during
3255 <chapt id="descriptions"><heading>Descriptions of packages - the
3256 <tt>Description</tt> field
3260 The <tt>Description</tt> control file field is used by
3261 <prgn>dselect</prgn> when the user is selecting which packages
3262 to install and by <prgn>dpkg</prgn> when it displays
3263 information about the status of packages and so forth. It is
3264 included on the FTP site in the <prgn>Packages</prgn> files,
3265 and may also be used by the Debian WWW pages.
3269 The description is intended to describe the program to a user
3270 who has never met it before so that they know whether they
3271 want to install it. It should also give information about the
3272 significant dependencies and conflicts between this package
3273 and others, so that the user knows why these dependencies and
3274 conflicts have been declared.
3278 The field's format is as follows:
3280 Description: <var>single line synopsis</var>
3281 <var>extended description over several lines</var>
3286 The synopsis is often printed in lists of packages and so
3287 forth, and should be as informative as possible. Every
3288 package should also have an extended description.
3291 <sect><heading>Types of formatting line in the extended
3299 Those starting with a single space are part of a
3300 paragraph. Successive lines of this form will be
3301 word-wrapped when displayed. The leading space will
3302 usually be stripped off.
3308 Those starting with two or more spaces. These will be
3309 displayed verbatim. If the display cannot be panned
3310 horizontally the displaying program will linewrap them
3311 `hard' (ie, without taking account of word breaks).
3312 If it can they will be allowed to trail off to the
3313 right. None, one or two initial spaces may be
3314 deleted, but the number of spaces deleted from each
3315 line will be the same (so that you can have indenting
3316 work correctly, for example).
3321 <p>Those containing a single space followed by a single full stop
3322 character. These are rendered as blank lines. This
3323 is the <em>only</em> way to get a blank line - see
3329 Those containing a space, a full stop and some more
3330 characters. These are for future expansion. Do not
3337 <sect><heading>Notes about writing descriptions
3341 <em>Always</em> start extended description lines with at least one
3342 whitespace character. Fields in the control file and in the Packages
3343 file are separated by field names starting in the first column, just
3344 as message header fields are in RFC822. Forgetting the whitespace
3345 will cause <prgn>dpkg-deb</prgn>
3348 Version 0.93.23 or later.
3350 </footnote> to produce a syntax error when trying to build
3351 the package. If you force it to build anyway
3352 <prgn>dpkg</prgn> will refuse to install the resulting
3357 <em>Do not</em> include any completely <em>empty</em>
3358 lines. These separate different records in the Packages file
3359 and different packages in the <tt>debian/control</tt> file,
3360 and are forbidden in package control files. See the
3361 previous paragraph for what happens if you get this wrong.
3365 The single line synopsis should be kept brief - certainly
3366 under 80 characters. <prgn>dselect</prgn> displays between
3367 25 and 49 characters without panning if you're using an
3368 80-column terminal, depending on what display options are in
3373 Do not include the package name in the synopsis line. The
3374 display software knows how to display this already, and you
3375 do not need to state it. Remember that in many situations
3376 the user may only see the synopsis line - make it as
3377 informative as you can.
3381 The extended description should describe what the package
3382 does and how it relates to the rest of the system (in terms
3383 of, for example, which subsystem it is which part of).
3387 The blurb that comes with a program in its announcements
3388 and/or <prgn>README</prgn> files is rarely suitable for use
3389 in a description. It is usually aimed at people who are
3390 already in the community where the package is used. The
3391 description field needs to make sense to anyone, even people
3392 who have no idea about any of the things the package deals
3397 Put important information first, both in the synopis and
3398 extended description. Sometimes only the first part of the
3399 synopsis or of the description will be displayed. You can
3400 assume that there will usually be a way to see the whole
3401 extended description.
3405 You may include information about dependencies and so forth
3406 in the extended description, if you wish.
3410 Do not use tab characters. Their effect is not predictable.
3414 Do not try to linewrap the summary (the part on the same
3415 line as the field name <tt>Description</tt>) into the
3416 extended description. This will not work correctly when the
3417 full description is displayed, and makes no sense where only
3418 the summary is available.</p>
3421 <sect><heading>Example description in control file for Smail
3427 Version: 3.1.29.1-13
3428 Maintainer: Ian Jackson <iwj10@cus.cam.ac.uk>
3429 Recommends: pine | mailx | elm | emacs | mail-user-agent
3431 Depends: cron, libc5
3433 Provides: mail-transport-agent
3434 Description: Electronic mail transport system.
3435 Smail is the recommended mail transport agent (MTA) for Debian.
3437 An MTA is the innards of the mail system - it takes messages from
3438 user-friendly mailer programs and arranges for them to be delivered
3439 locally or passed on to other systems as required.
3441 In order to make use of it you must have one or more user level
3442 mailreader programs such as elm, pine, mailx or Emacs (which has Rmail
3443 and VM as mailreaders) installed. If you wish to send messages other
3444 than just to other users of your system you must also have appropriate
3445 networking support, in the form of IP or UUCP.
3451 <chapt id="relationships"><heading>Declaring relationships between
3456 Packages can declare in their control file that they have
3457 certain relationships to other packages - for example, that
3458 they may not be installed at the same time as certain other
3459 packages, and/or that they depend on the presence of others,
3460 or that they should overwrite files in certain other packages
3465 This is done using the <tt>Depends</tt>, <tt>Recommends</tt>,
3466 <tt>Suggests</tt>, <tt>Conflicts</tt>, <tt>Provides</tt> and
3467 <tt>Replaces</tt> control file fields.
3470 <sect id="depsyntax"><heading>Syntax of relationship fields
3474 These fields all have a uniform syntax. They are a list of
3475 package names separated by commas.
3479 In <tt>Depends</tt>, <tt>Recommends</tt>, <tt>Suggests</tt>
3480 and <tt>Pre-Depends</tt> (the fields which declare
3481 dependencies of the package in which they occur on other
3482 packages) these package names may also be lists of
3483 alternative package names, separated by vertical bar symbols
3484 <tt>|</tt> (pipe symbols).
3488 All the fields except <tt>Provides</tt> may restrict their
3489 applicability to particular versions of each named package.
3490 This is done in parentheses after each individual package
3491 name; the parentheses should contain a relation from the
3492 list below followed by a version number, in the format
3493 described in <ref id="versions">.
3497 The relations allowed are <tt><<</tt>, <tt><=</tt>,
3498 <tt>=</tt>, <tt>>=</tt> and <tt>>></tt> for
3499 strictly earlier, earlier or equal, exactly equal, later or
3500 equal and strictly later, respectively. The forms
3501 <tt><</tt> and <tt>></tt> were used to mean
3502 earlier/later or equal, rather than strictly earlier/later,
3503 so they should not appear in new packages (though
3504 <prgn>dpkg</prgn> still supports them).
3508 Whitespace may appear at any point in the version
3509 specification, and must appear where it's necessary to
3510 disambiguate; it is not otherwise significant. For
3511 consistency and in case of future changes to
3512 <prgn>dpkg</prgn> it is recommended that a single space be
3513 used after a version relationship and before a version
3514 number; it is usual also to put a single space after each
3515 comma, on either side of each vertical bar, and before each
3524 Depends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh
3529 <sect><heading>Dependencies - <tt>Depends</tt>, <tt>Recommends</tt>,
3530 <tt>tt>Sugge</tt>tt>, <tt>Pre-Depends</tt>
3534 These four fields are used to declare a dependency by one
3535 package on another. They appear in the depending package's
3540 All but <tt>Pre-Depends</tt> (discussed below) take effect
3541 <em>only</em> when a package is to be configured. They do
3542 not prevent a package being on the system in an unconfigured
3543 state while its dependencies are unsatisfied, and it is
3544 possible to replace a package whose dependencies are
3545 satisfied and which is properly installed with a different
3546 version whose dependencies are not and cannot be satisfied;
3547 when this is done the depending package will be left
3548 unconfigured (since attempts to configure it will give
3549 errors) and will not function properly.
3553 For this reason packages in an installation run are usually
3554 all unpacked first and all configured later; this gives
3555 later versions of packages with dependencies on later
3556 versions of other packages the opportunity to have their
3557 dependencies satisfied.
3561 Thus <tt>Depends</tt> allows package maintainers to impose
3562 an order in which packages should be configured.
3564 <tag><tt>Depends</tt></tag>
3567 <p>This declares an absolute dependency.
3571 <prgn>dpkg</prgn> will not configure packages whose
3572 dependencies aren't satisfied. If it is asked to make
3573 an installation which would cause an installed
3574 package's dependencies to become unsatisfied it will
3578 Current versions (1.2.4) of <prgn>dpkg</prgn> have
3579 a bug in this area which will cause some of these
3580 problems to be ignored.
3582 </footnote>, unless <tt>--auto-deconfigure</tt> is
3583 specified, in which case those packages will be
3584 deconfigured before the installation proceeds.
3588 <prgn>dselect</prgn> makes it hard for the user to
3589 select packages for installation, removal or upgrade
3590 in a way that would mean that packages'
3591 <prgn>Depends</prgn> fields would be unsatisfied. The
3592 user can override this if they wish, for example if
3593 they know that <prgn>dselect</prgn> has an out-of-date
3594 view of the real package relationships.
3598 The <tt>Depends</tt> field should be used if the
3599 depended-on package is required for the depending
3600 package to provide a significant amount of
3604 <tag><tt>Recommends</tt></tag>
3606 <p>This declares a strong, but not absolute, dependency.
3610 <tt>Recommends</tt> is ignored by <prgn>dpkg</prgn>,
3611 so that users using the command-line (who are presumed
3612 to know what they're doing) will not be impeded.
3616 It is treated by <prgn>dselect</prgn> exactly as
3617 <tt>Depends</tt> is; this makes it hard for the user
3618 to select things so as to leave <tt>Recommends</tt>
3619 fields unsatisfied, but they are able to do so by
3624 The <tt>Recommends</tt> field should list packages
3625 that would be found together with this one in all but
3626 unusual installations.</p>
3629 <tag><tt>Suggests</tt></tag>
3633 This is used to declare that one package may be more
3634 useful with one or more others. Using this field
3635 tells the packaging system and the user that the
3636 listed packages are be related to this one and can
3637 perhaps enhance its usefulness, but that installing
3638 this one without them is perfectly reasonable.
3642 <prgn>dselect</prgn> will offer suggsted packages to
3643 the system administrator when they select the
3644 suggesting package, but the default is not to install
3645 the suggested package.</p>
3648 <tag><tt>Pre-Depends</tt></tag>
3651 <p>This field is like <tt>Depends</tt>, except that it also forces
3652 <prgn>dpkg</prgn> to complete installation of the
3653 packages named before even starting the installation
3654 of the package which declares the predependency.
3658 <prgn>dselect</prgn> checks for predependencies when
3659 it is doing an installation run, and will attempt to
3660 find the packages which are required to be installed
3661 first and do so in the right order.
3665 However, this process is slow (because it requires
3666 repeated invocations of <prgn>dpkg</prgn>) and
3667 troublesome (because it requires guessing where to
3668 find the appropriate files).
3672 For these reasons, and because this field imposes
3673 restrictions on the order in which packages may be
3674 unpacked (which can be difficult for installations
3675 from multipart media, for example),
3676 <tt>Pre-Depends</tt> should be used sparingly,
3677 preferably only by packages whose premature upgrade or
3678 installation would hamper the ability of the system to
3679 continue with any upgrade that might be in progress.
3683 When the package declaring it is being configured, a
3684 <tt>Pre-Dependency</tt> will be considered satisfied
3685 only if the depending package has been correctly
3686 configured, just as if an ordinary <tt>Depends</tt>
3691 However, when a package declaring a predependency is
3692 being unpacked the predependency can be satisfied even
3693 if the depended-on package(s) are only unpacked or
3694 half-configured, provided that they have been
3695 configured correctly at some point in the past (and
3696 not removed or partially removed since). In this case
3697 both the previously-configured and currently unpacked
3698 or half-configured versions must satisfy any version
3699 clause in the <tt>Pre-Depends</tt> field.
3705 When selecting which level of dependency to use you should
3706 consider how important the depended-on package is to the
3707 functionality of the one declaring the dependency. Some
3708 packages are composed of components of varying degrees of
3709 importance. Such a package should list using
3710 <tt>Depends</tt> the package(s) which are required by the
3711 more important components. The other components'
3712 requirements may be mentioned as Suggestions or
3713 Recommendations, as appropriate to the components' relative
3717 <sect1><heading>Dependencies on shared libraries
3721 The dependency fields listed above are used by packages
3722 which need shared libraries to declare dependencies on the
3723 appropriate packages.
3727 These dependencies are usually determined automatically
3728 using <prgn>dpkg-shlibdeps</prgn> and inserted in the
3729 package control file using the control file substitution
3730 variables mechanism; see <ref id="srcsubstvars"> and
3731 <ref id="sourcetools">.
3735 <sect1><heading>Deconfiguration due to removal during bulk
3740 If <prgn>dpkg</prgn> would like to remove a package due to a
3741 conflict, as described above, but this would violate a
3742 dependency of some other package on the system,
3743 <prgn>dpkg</prgn> will usually not remove the conflicting
3744 package and halt with an error.
3748 However, if the <tt>--auto-deconfigure</tt> (<tt>-B</tt>)
3749 option is used <prgn>dpkg</prgn> will automatically
3750 `deconfigure' the package with the problematic dependency,
3751 so that the conflicting package can be removed and the
3752 package we're trying to install can be installed. If
3753 <prgn>dpkg</prgn> is being asked to install packages (rather
3754 than just unpacking them) it will try to reconfigure the
3755 package when it has unpacked all its arguments, in the hope
3756 that one of the other packages it is installing will satisfy
3757 the problematic dependency.
3761 <prgn>dselect</prgn> supplies this argument to
3762 <prgn>dpkg</prgn> when it invokes it, so that bulk
3763 installations proceed smoothly.
3767 <sect id="conflicts"><heading>Alternative packages -
3768 <tt>tt>Confli</tt>tt> and <tt>Replaces</tt>
3772 When one package declares a conflict with another
3773 <prgn>dpkg</prgn> will refuse to allow them to be installed
3774 on the system at the same time.
3778 If one package is to be installed, the other must be removed first -
3779 if the package being installed is marked as replacing (<ref
3780 id="replaces">) the one on the system, or the one on the system is
3781 marked as deselected, or both packages are marked
3782 <tt>Essential</tt>, then <prgn>dpkg</prgn> will
3783 automatically remove the package which is causing the
3784 conflict, otherwise it will halt the installation of the new
3785 package with an error.
3789 <prgn>dselect</prgn> makes it hard to select conflicting
3790 packages, though the user can override this if they wish.
3791 If they do not override it then <prgn>dselect</prgn> will
3792 select one of the packages for removal, and the user must
3793 make sure it is the right one. In the future
3794 <prgn>dselect</prgn> will look for the presence of a
3795 <tt>Replaces</tt> field to help decide which package should
3796 be installed and which removed.
3800 A package will not cause a conflict merely because its
3801 configuration files are still installed; it must be at least
3806 A special exception is made for packages which declare a
3807 conflict with their own package name, or with a virtual
3808 package which they provide (see below): this does not
3809 prevent their installation, and allows a package to conflict
3810 with others providing a replacement for it. You use this
3811 feature when you want the package in question to be the only
3812 package providing something.
3816 A <tt>Conflicts</tt> entry should almost never have an
3817 `earlier than' version clause. This would prevent
3818 <prgn>dpkg</prgn> from upgrading or installing the package
3819 which declared such a conflict until the upgrade or removal
3820 of the conflicted-with package had been completed. This
3821 aspect of installation ordering is not handled by
3822 <prgn>dselect</prgn>, so that the use <tt>Conflicts</tt> in
3823 this way is likely to cause problems for `bulk run' upgrades
3828 <sect id="virtual"><heading>Virtual packages - <tt>Provides</tt>
3832 As well as the names of actual (`concrete') packages, the
3833 package relationship fields <tt>Depends</tt>,
3834 <tt>Recommends</tt>, <tt>Suggests</tt> and
3835 <tt>Conflicts</tt> may mention virtual packages.
3839 A virtual package is one which appears in the
3840 <tt>Provides</tt> control file field of another package.
3841 The effect is as if the package(s) which provide a
3842 particular virtual package name had been listed by name
3843 everywhere were the virtual package name appears.
3847 If there are both a real and a virtual package of the same
3848 name then the dependency may be satisfied (or the conflict
3849 caused) by either the real package or any of the virtual
3850 packages which provide it. This is so that, for example,
3856 and someone else releases an xemacs package they can say
3860 </example> and all will work in the interim (until a purely
3861 virtual package name is decided on and the <tt>emacs</tt>
3862 and <tt>vm</tt> packages are changed to use it).
3866 If a dependency or a conflict has a version number attached
3867 then only real packages will be considered to see whether
3868 the relationship is satisfied (or the prohibition violated,
3869 for a conflict) - it is assumed that a real package which
3870 provides virtual package is not of the `right' version. So,
3871 a <tt>Provides</tt> field may not contain version numbers,
3872 and the version number of the concrete package which
3873 provides a particular virtual package will not be looked at
3874 when considering a dependency on or conflict with the
3875 virtual package name.
3879 It is likely that the ability will be added in a future
3880 release of <prgn>dpkg</prgn> to specify a version number for
3881 each virtual package it provides. This feature is not yet
3882 present, however, and is expected to be used only
3887 If you want to specify which of a set of real packages should be the
3888 default to satisfy a particular dependency on a virtual package, you
3889 should list the real package as alternative before the virtual.
3894 <sect id="replaces"><heading><tt>Replaces</tt> - overwriting
3895 files and replacing packages
3899 The <tt>Replaces</tt> control file field has two purposes,
3900 which come into play in different situations.
3904 Virtual packages (<ref id="virtual">) are not considered
3905 when looking at a <tt>Replaces</tt> field - the packages
3906 declared as being replaced must be mentioned by their real
3910 <sect1><heading>Overwriting files in other packages
3914 Firstly, as mentioned before, it is usually an error for a
3915 package to contains files which are on the system in
3916 another package, though currently the
3917 <tt>--force-overwrite</tt> flag is enabled by default,
3918 downgrading the error to a warning,
3922 If the overwriting package declares that it replaces the
3923 one containing the file being overwritten then
3924 <prgn>dpkg</prgn> will proceed, and replace the file from
3925 the old package with that from the new. The file will no
3926 longer be listed as `owned' by the old package.
3930 If a package is completely replaced in this way, so that
3931 <prgn>dpkg</prgn> does not know of any files it still
3932 contains, it is considered to have disappeared. It will
3933 be marked as not wanted on the system (selected for
3934 removal) and not installed. Any conffiles details noted
3935 in the package will be ignored, as they will have been
3936 taken over by the replacing package(s). The package's
3937 <prgn>postrm</prgn> script will be run to allow the
3938 package to do any final cleanup required. See <ref
3939 id="mscriptsinstact">.
3943 In the future <prgn>dpkg</prgn> will discard files which
3944 overwrite those from another package which declares that
3945 it replaces the one being installed (so that you can
3946 install an older version of a package without problems).
3950 This usage of <tt>Replaces</tt> only takes effect when
3951 both packages are at least partially on the system at
3952 once, so that it can only happen if they do not conflict
3953 or if the conflict has been overridden.</p>
3956 <sect1><heading>Replacing whole packages, forcing their
3961 Secondly, <tt>Replaces</tt> allows <prgn>dpkg</prgn> and
3962 <prgn>dselect</prgn> to resolve which package should be
3963 removed when a conflict - see <ref id="conflicts">. This
3964 usage only takes effect when the two packages <em>do</em>
3965 conflict, so that the two effects do not interfere with
3971 <sect><heading>Defaults for satisfying dependencies - ordering
3975 Ordering is significant in dependency fields.
3979 Usually dselect will suggest to the user that they select
3980 the package with the most `fundamental' class (eg, it will
3981 prefer Base packages to Optional ones), or the one that they
3982 `most wanted' to select in some sense.
3986 In the absence of other information <prgn>dselect</prgn>
3987 will offer a default selection of the first named package in
3988 a list of alternatives.
3992 However, there is no way to specify the `order' of several
3993 packages which all provide the same thing, when that thing
3994 is listed as a dependency.
3998 Therefore a dependency on a virtual package should contain a
3999 concrete package name as the first alternative, so that this
4004 For example, consider the set of packages:
4007 Recommends: info-browser
4010 Provides: info-browser
4013 Provides: info-browser
4018 If <prgn>emacs</prgn> and <prgn>info</prgn> both have the
4019 same priority then <prgn>dselect</prgn>'s choice is
4020 essentially random. Better would be
4023 Recommends: info | info-browser
4025 so that <prgn>dselect</prgn> defaults to selecting the
4026 lightweight standalone info browser.
4031 <chapt id="conffiles"><heading>Configuration file handling
4035 <prgn>dpkg</prgn> can do a certain amount of automatic
4036 handling of package configuration files.
4040 Whether this mechanism is appropriate depends on a number of
4041 factors, but basically there are two approaches to any
4042 particular configuration file.
4046 The easy method is to ship a best-effort configuration in the
4047 package, and use <prgn>dpkg</prgn>'s conffile mechanism to
4048 handle updates. If the user is unlikely to want to edit the
4049 file, but you need them to be able to without losing their
4050 changes, and a new package with a changed version of the file
4051 is only released infrequently, this is a good approach.
4055 The hard method is to build the configuration file from
4056 scratch in the <prgn>postinst</prgn> script, and to take the
4057 responsibility for fixing any mistakes made in earlier
4058 versions of the package automatically. This will be
4059 appropriate if the file is likely to need to be different on
4063 <sect><heading>Automatic handling of configuration files by
4068 A package may contain a control area file called
4069 <tt>conffiles</tt>. This file should be a list of filenames
4070 of configuration files needing automatic handling, separated
4071 by newlines. The filenames should be absolute pathnames,
4072 and the files referred to should actually exist in the
4077 When a package is upgraded <prgn>dpkg</prgn> will process
4078 the configuration files during the configuration stage,
4079 shortly before it runs the package's <prgn>postinst</prgn>
4084 For each file it checks to see whether the version of the
4085 file included in the package is the same as the one that was
4086 included in the last version of the package (the one that is
4087 being upgraded from); it also compares the version currently
4088 installed on the system with the one shipped with the last
4093 If neither the user nor the package maintainer has changed
4094 the file, it is left alone. If one or the other has changed
4095 their version, then the changed version is preferred - ie,
4096 if the user edits their file, but the package maintainer
4097 doesn't ship a different version, the user's changes will
4098 stay, silently, but if the maintainer ships a new version
4099 and the user hasn't edited it the new version will be
4100 installed (with an informative message). If both have
4101 changed their version the user is prompted about the problem
4102 and must resolve the differences themselves.
4106 The comparisons are done by calculating the MD5 message
4107 digests of the files, and storing the MD5 of the file as it
4108 was included in the most recent version of the package.
4112 When a package is installed for the first time
4113 <prgn>dpkg</prgn> will install the file that comes with it,
4114 unless that would mean overwriting a file already on the
4119 However, note that <prgn>dpkg</prgn> will <em>not</em>
4120 replace a conffile that was removed by the user (or by a
4121 script). This is necessary because with some programs a
4122 missing file produces an effect hard or impossible to
4123 achieve in another way, so that a missing file needs to be
4124 kept that way if the user did it.
4128 Note that a package should <em>not</em> modify a
4129 <prgn>dpkg</prgn>-handled conffile in its maintainer
4130 scripts. Doing this will lead to <prgn>dpkg</prgn> giving
4131 the user confusing and possibly dangerous options for
4132 conffile update when the package is upgraded.</p>
4135 <sect><heading>Fully-featured maintainer script configuration
4140 For files which contain site-specific information such as
4141 the hostname and networking details and so forth, it is
4142 better to create the file in the package's
4143 <prgn>postinst</prgn> script.
4147 This will typically involve examining the state of the rest
4148 of the system to determine values and other information, and
4149 may involve prompting the user for some information which
4150 can't be obtained some other way.
4154 When using this method there are a couple of important
4155 issues which should be considered:
4159 If you discover a bug in the program which generates the
4160 configuration file, or if the format of the file changes
4161 from one version to the next, you will have to arrange for
4162 the postinst script to do something sensible - usually this
4163 will mean editing the installed configuration file to remove
4164 the problem or change the syntax. You will have to do this
4165 very carefully, since the user may have changed the file,
4166 perhaps to fix the very problem that your script is trying
4167 to deal with - you will have to detect these situations and
4168 deal with them correctly.
4172 If you do go down this route it's probably a good idea to
4173 make the program that generates the configuration file(s) a
4174 separate program in <tt>/usr/sbin</tt>, by convention called
4175 <tt><var>package</var>config</tt> and then run that if
4176 appropriate from the post-installation script. The
4177 <tt><var>package</var>config</tt> program should not
4178 unquestioningly overwrite an existing configuration - if its
4179 mode of operation is geared towards setting up a package for
4180 the first time (rather than any arbitrary reconfiguration
4181 later) you should have it check whether the configuration
4182 already exists, and require a <tt>--force</tt> flag to
4183 overwrite it.</p></sect>
4188 <chapt id="alternatives"><heading>Alternative versions of an interface -
4189 <prgn>update-alternatives</prgn>
4193 When several packages all provide different versions of the
4194 same program or file it is useful to have the system select a
4195 default, but to allow the system administrator to change it
4196 and have their decisions respected.
4200 For example, there are several versions of the <prgn>vi</prgn>
4201 editor, and there is no reason to prevent all of them from
4202 being installed at once, each under their own name
4203 (<prgn>nvi</prgn>, <prgn>vim</prgn> or whatever).
4204 Nevertheless it is desirable to have the name <tt>vi</tt>
4205 refer to something, at least by default.
4209 If all the packages involved cooperate, this can be done with
4210 <prgn>update-alternatives</prgn>.
4214 Each package provides its own version under its own name, and
4215 calls <prgn>update-alternatives</prgn> in its postinst to
4216 register its version (and again in its prerm to deregister
4221 See the manpage <manref name="update-alternatives"
4222 section="8"> for details.
4226 If <prgn>update-alternatives</prgn> does not seem appropriate
4227 you may wish to consider using diversions instead.</p>
4231 <chapt id="diversions"><heading>Diversions - overriding a
4232 package's version of a file
4236 It is possible to have <prgn>dpkg</prgn> not overwrite a file
4237 when it reinstalls the package it belongs to, and to have it
4238 put the file from the package somewhere else instead.
4242 This can be used locally to override a package's version of a
4243 file, or by one package to override another's version (or
4244 provide a wrapper for it).
4248 Before deciding to use a diversion, read <ref
4249 id="alternatives"> to see if you really want a diversion
4250 rather than several alternative versions of a program.
4254 There is a diversion list, which is read by <prgn>dpkg</prgn>,
4255 and updated by a special program <prgn>dpkg-divert</prgn>.
4256 Please see <manref name="dpkg-divert" section="8"> for full
4257 details of its operation.
4261 When a package wishes to divert a file from another, it should
4262 call <prgn>dpkg-divert</prgn> in its preinst to add the
4263 diversion and rename the existing file. For example,
4264 supposing that a <prgn>smailwrapper</prgn> package wishes to
4265 install a wrapper around <tt>/usr/sbin/smail</tt>:
4267 if [ install = "$1" ]; then
4268 dpkg-divert --package smailwrapper --add --rename \
4269 --divert /usr/sbin/smail.real /usr/sbin/smail
4271 </example> Testing <tt>$1</tt> is necessary so that the script
4272 doesn't try to add the diversion again when
4273 <prgn>smailwrapper</prgn> is upgraded. The <tt>--package
4274 smailwrapper</tt> ensures that <prgn>smailwrapper</prgn>'s
4275 copy of <tt>/usr/sbin/smail</tt> can bypass the diversion and
4276 get installed as the true version.
4280 The postrm has to do the reverse:
4282 if [ remove = "$1" ]; then
4283 dpkg-divert --package smailwrapper --remove --rename \
4284 --divert /usr/sbin/smail.real /usr/sbin/smail
4290 Do not attempt to divert a file which is vitally important for
4291 the system's operation - when using <prgn>dpkg-divert</prgn>
4292 there is a time, after it has been diverted but before
4293 <prgn>dpkg</prgn> has installed the new version, when the file
4298 <chapt id="sharedlibs"><heading>Shared libraries
4302 Packages containing shared libraries must be constructed with
4303 a little care to make sure that the shared library is always
4304 available. This is especially important for packages whose
4305 shared libraries are vitally important, such as the libc.
4309 Firstly, your package should install the shared libraries
4310 under their normal names. For example, the
4311 <prgn>libgdbm1</prgn> package should install
4312 <tt>libgdbm.so.1.7.3</tt> as
4313 <tt>/usr/lib/libgdbm.so.1.7.3</tt>. The files should not be
4314 renamed or relinked by any prerm or postrm scripts;
4315 <prgn>dpkg</prgn> will take care of renaming things safely
4316 without affecting running programs, and attempts to interfere
4317 with this are likely to lead to problems.
4321 Secondly, your package should include the symlink that
4322 <prgn>ldconfig</prgn> would create for the shared libraries.
4323 For example, the <prgn>libgdbm1</prgn> package should include
4324 a symlink from <tt>/usr/lib/libgdbm.so.1</tt> to
4325 <tt>libgdbm.so.1.7.3</tt>. This is needed so that
4326 <prgn>ld.so</prgn> can find the library in between the time
4327 <prgn>dpkg</prgn> installs it and <prgn>ldconfig</prgn> is run
4328 in the <prgn>postinst</prgn> script. Futhermore, and <em>this
4329 is very important</em>, the library must be placed before the
4330 symlink pointing to it in the <tt>.deb</tt> file. This is so
4331 that by the time <prgn>dpkg</prgn> comes to install the
4332 symlink (overwriting the previous symlink pointing at an older
4333 version of the library) the new shared library is already in
4334 place. Currently the way to ensure the ordering is done
4335 properly is to install the library in the appropriate
4336 <tt>debian/tmp/.../lib</tt> directory before creating the
4337 symlink, by putting the commands in the <tt>debian/rules</tt>
4338 in the appropriate order.
4342 next Paragraph added to close Bug #5299, Guy Maor
4346 Thirdly, the development package should contain a symlink for
4347 the shared library without a version number. For example, the
4348 <tt>libgdbm1-dev</tt> package should include a symlink from
4349 <tt>/usr/lib/libgdm.so</tt> to <tt>libgdm.so.1.7.3</tt>. This
4350 symlink is needed by <prgn>ld</prgn> when compiling packages
4351 as it will only look for <tt>libgdm.so</tt> and
4352 <tt>libgdm.a</tt> when compiling dynamically or statically,
4357 next paragraph changed by Christian Schwarz (see policy weekly #6)
4361 Any package installing shared libraries in a directory that's listed
4362 in <tt>/etc/ld.so.conf</tt> or in one of the default library
4363 directories of <prgn>ld.so</prgn> (currently, these are <tt>/usr/lib</tt>
4364 and <tt>/lib</tt>) must call <prgn>ldconfig</prgn> in its <prgn>postinst</prgn>
4365 script if and only if the first argument is `configure'. However, it
4366 is important not to call <prgn>ldconfig</prgn> in the postrm or preinst
4367 scripts in the case where the package is being upgraded (see <ref
4368 id="unpackphase">), as <prgn>ldconfig</prgn> will see the temporary names
4369 that <prgn>dpkg</prgn> uses for the files while it is
4370 installing them and will make the shared library links point
4371 to them, just before <prgn>dpkg</prgn> continues the
4372 installation and removes the links!
4376 moved from section 2.2 , DMorris
4379 <sect id="shlibs"><heading>The <tt>shlibs</tt> File Format
4383 This file is for use by <prgn>dpkg-shlibdeps</prgn> and is
4384 required when your package provides shared libraries.
4388 Each line is of the form:
4390 <var>library-name</var> <var>version-or-soname</var> <var>dependencies ...</var>
4395 <var>library-name</var> is the name of the shared library,
4396 for example <tt>libc5</tt>.
4400 <var>version-or-soname</var> is the soname of the library -
4401 ie, the thing that must exactly match for the library to be
4402 recognised by <prgn>ld.so</prgn>. Usually this is major
4403 version number of the library.
4407 <var>dependencies</var> has the same syntax as a dependency
4408 field in a binary package control file. It should give
4409 details of which package(s) are required to satisfy a binary
4410 built against the version of the library contained in the
4411 package. See <ref id="depsyntax">.
4415 For example, if the package <tt>foo</tt> contains
4416 <tt>libfoo.so.1.2.3</tt>, where the soname of the library is
4417 <tt>libfoo.so.1</tt>, and the first version of the package
4418 which contained a minor number of at least <tt>2.3</tt> was
4419 <var>1.2.3-1</var>, then the package's <var>shlibs</var>
4422 libfoo 1 foo (>= 1.2.3-1)
4427 The version-specific dependency is to avoid warnings from
4428 <prgn>ld.so</prgn> about using older shared libraries with
4432 <sect><heading>Further Technical information on
4433 <tt>shlibs</tt></heading>
4437 following section mostly provided by Heiko Schlittermann
4441 <sect1><heading><em>What</em> are the <tt>shlibs</tt> files?
4445 The <tt>debian/shlibs</tt> file provides a way of checking
4446 for shared library dependencies on packaged binaries.
4447 They are intended to be used by package maintainers to
4448 make their lives easier.
4452 Other <tt>shlibs</tt> files that exist on a Debian system are
4454 <item> <p><tt>/etc/dpkg/shlibs.default</tt></p></item>
4455 <item> <p><tt>/etc/dpkg/shlibs.override</tt></p></item>
4456 <item> <p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
4457 <item> <p><tt>debian/shlibs.local</tt></p></item>
4459 These files are used by <prgn>dpkg-shlibdeps</prgn> when
4460 creating a binary package.</p>
4463 <sect1><heading><em>How</em> does <prgn>dpkg-shlibdeps</prgn>
4468 <prgn>dpkg-shlibdeps</prgn> calls <prgn>ldd</prgn> to
4469 determine the shared libraries used by the compiled
4470 binaries passed through its command line.
4474 For each shared library, <prgn>dpkg-shlibdeps</prgn> needs to know
4475 <list compact="compact">
4476 <item><p>the package containing the library, and</p></item>
4477 <item><p>the library version number,</p></item>
4480 it scans the following files in this order.
4481 <enumlist compact="compact">
4482 <item><p><tt>debian/shlibs.local</tt></p></item>
4483 <item><p><tt>/etc/dpkg/shlibs.override</tt></p></item>
4484 <item><p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
4485 <item><p><tt>/etc/dpkg/shlibs.default</tt></p></item>
4489 <sect1><heading><em>Who</em> maintains the various
4490 <tt>shlibs</tt> files?
4494 <list compact="compact">
4496 <p><tt>/etc/dpkg/shlibs.default</tt> - the maintainer
4501 <tt>/var/lib/dpkg/info/<var>package</var>.shlibs</tt>
4502 - the maintainer of each package</p>
4506 <tt>/etc/dpkg/shlibs.override</tt> - the local
4507 system administrator</p>
4510 <p><tt>debian/shlibs.local</tt> - the maintainer of
4515 The <tt>shlibs.default</tt> file is managed by
4516 <prgn>dpkg</prgn>. The entries in <tt>shlibs.default</tt>
4517 that are provided by <prgn>dpkg</prgn> are just there to
4518 fix things until the shared library packages all have
4519 <tt>shlibs</tt> files.
4523 <sect1><heading><em>How</em> to use <prgn>dpkg-shlibdeps</prgn> and
4524 the <tt>shlibs</tt> files?
4527 <sect2><heading>If your package doesn't provide a shared
4532 Put a call to <prgn>dpkg-shlibdeps</prgn> into your
4533 <tt>debian/rules</tt> file. If your package contains
4534 only binaries (e.g. no scripts) use:
4536 dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/*
4538 If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
4539 done. If it does complain you might need to create your
4540 own <tt>debian/shlibs.local</tt> file.</p>
4543 <sect2><heading>If your package provides a shared library
4547 Create a <tt>debian/shlibs</tt> file and let
4548 <tt>debian/rules</tt> install it in the control area:
4550 install -m644 debian/shlibs debian/tmp/DEBIAN
4552 If your package contains additional binaries see above.
4557 <sect1><heading><em>How</em> to write
4558 <tt>debian/shlibs.local</tt>
4562 This file is intended only as a <em>temporary</em> fix if
4563 your binaries depend on a library which doesn't provide
4564 its own <tt>/var/lib/dpkg/*.shlibs</tt> file yet.
4568 Let's assume you are packaging a binary <tt>foo</tt>. Your
4569 output in building the package might look like this.
4572 libbar.so.1 => /usr/X11R6/lib/libbar.so.1.0
4573 libc.so.5 => /lib/libc.so.5.2.18
4574 libX11.so.6 => /usr/X11R6/lib/libX11.so.6.0
4576 And when you ran <prgn>dpkg-shlibdeps</prgn>
4578 $ dpkg-shlibdeps -o foo
4579 dpkg-shlibdeps: warning: unable to find dependency information
4580 for shared library libbar
4581 (soname 1, path /usr/X11R6/lib/libbar.so.1.0, dependency field Depends)
4582 shlibs:Depends=elf-x11r6lib, libc5 (>= 5.2.18)
4584 The <prgn>foo</prgn> binary depends on the
4585 <prgn>libbar</prgn> shared library, but no package seems
4586 to provide a <tt>*.shlibs</tt> file in
4587 <tt></tt>var/lib/dpkg/info/. Let's determine the package
4593 $ dpkg -S /usr/X11R6/lib/libbar.so.1.0
4594 bar1: /usr/X11R6/lib/libbar.so.1.0
4595 $ dpkg -s bar1 | grep Version
4598 This tells us that the <prgn>bar1</prgn> package, version
4599 1.0-1 is the one we are using. Now we can create our own
4600 <tt>debian/shlibs.local</tt> to temporarly fix the above
4601 problem. Include the following line into your
4602 <tt>debian/shlibs.local</tt> file.
4604 libbar 1 bar1 (>= 1.0-1)
4606 Now your package build should work. As soon as the
4607 maintainer of <prgn>libbar1</prgn> provides a
4608 <tt>shlibs</tt> file, you can remove your
4609 <tt>debian/shlibs.local</tt> file.
4615 <chapt id="methif"><heading><prgn>dselect</prgn>'s interface to
4616 its installation methods
4620 <prgn>dselect</prgn> calls scripts from its installation
4621 methods when it needs to actually access data from the
4622 distribution. The core program <prgn>dselect</prgn> itself
4623 just calls these scripts and provides the package and access
4624 method selection interfaces. The installation methods are
4625 responsible for invoking <prgn>dpkg</prgn> as appropriate.
4629 Each installation method has three scripts:
4630 <list compact="compact">
4631 <item><p>Setup installation parameters.</p></item>
4632 <item><p>Update list of available packages.</p></item>
4633 <item><p>Install.</p></item>
4637 <prgn>dselect</prgn> searches for methods in
4638 <tt>/usr/lib/dpkg/methods</tt> and
4639 <tt>/usr/local/lib/dpkg/methods</tt>.
4642 <sect><heading>Functions of the method scripts
4646 The setup script is run just after the user has chosen an
4647 installation method. It should prompt the user for
4648 parameters like the site to NFS-mount or FTP from, the
4649 directory to use, or the directory or filesystem where the
4650 <tt>.deb</tt> files can be found, or the tape or floppy
4651 device to install from. It should store the responses under
4652 <tt>/var/lib/dpkg/methods</tt> - see below. If no available
4653 packages list is available it should perhaps offer to scan
4654 the available packages.
4658 The update script should obtain a list of available packages
4659 if possible, and run <tt>dpkg --update-avail</tt>, <tt>dpkg
4660 --merge-avail</tt> and/or <tt>dpkg --forget-old-unavail</tt>
4661 to load it into <prgn>dpkg</prgn> and <prgn>dselect</prgn>'s
4662 database of available packages. If no packages list was
4663 available and the user was offered and accepted the option
4664 of scanning the actual files available this scan should be
4665 done here, using <tt>dpkg --record-avail</tt>.
4669 The install script should feed all the available
4670 <tt>.deb</tt> files to <tt>dpkg --iGOEB</tt> (this is
4671 equivalent to <tt>dpkg --install
4672 --refuse-downgrade --selected-only --skip-same-version
4673 --auto-deconfigure</tt>). The <tt>-R</tt>
4674 (<tt>--recursive</tt>) option for traversing subdirectories
4675 may also be useful here).
4679 If any of these scripts needs to display a message for the
4680 user, it should wait for the user to hit `return' before
4681 exiting so that dselect doesn't immediately rewrite the
4686 If a method script succeeds (returns a zero exit status)
4687 <prgn>dselect</prgn> will return immediately to the main
4688 menu, with the `next' option highlighted ready for the user
4689 to select it. If it fails <prgn>dselect</prgn> will display
4690 a message and wait for the user to hit return.</p>
4693 <sect><heading>Location and arguments of the method scripts
4697 A set of scripts (henceforth known as a group) may provide
4698 several methods on the `main menu' with different behaviour.
4699 For example, there might be a generic get-packages-by-FTP
4700 group which might provide methods in the main menu for
4701 installation directly from one of the Debian mirror sites as
4702 well as for installation from a user-specified site.
4706 Each group of methods implemented by the same set of scripts
4707 should have a subdirectory
4708 <tt>/usr/lib/dpkg/methods/<var>group</var></tt> or
4709 <tt>/usr/local/lib/dpkg/methods/<var>group</var></tt>,
4711 <taglist compact="compact">
4712 <tag><tt>names</tt></tag>
4713 <item><p>a list of user-visible methods provided by these scripts.</p>
4715 <tag><tt>setup</tt></tag>
4716 <tag><tt>update</tt></tag>
4717 <tag><tt>install</tt></tag>
4718 <item><p>executable programs, the scripts themselves.</p>
4720 <tag><tt>desc.<var>option</var></tt></tag>
4721 <item><p>description file.</p></item>
4726 <tt>names</tt> will be formatted as a list of lines, each containing:
4728 <var>sequence</var> <var>method</var> <var>summary</var>
4732 <var>sequence</var> is a two-digit number that will be used
4733 much like <tt>rc.d</tt> prefixes to control the order in the
4734 main menu. If in doubt use 50.
4738 <var>method</var> is a name which is displayed by
4739 <prgn>dselect</prgn> as the name of the method, and which
4740 will be passed to <tt>setup</tt>, <tt>update</tt> and
4741 <tt>unpack</tt> as their first argument.
4745 <var>summary</var> is the brief description string for
4746 <prgn>dselect</prgn>'s menu.
4750 Each of the three scripts gets the same three arguments:
4751 <var>vardir</var>, <var>group</var> and <var>method</var>.
4752 <var>vardir</var> is the base directory for storing
4753 <prgn>dpkg</prgn> and <prgn>dselect</prgn>'s state, usually
4754 <tt>/var/lib/dpkg</tt>; this is passed in so that the
4755 <tt>--admindir</tt> option to <prgn>dselect</prgn> is
4760 Each option may have an extended description in
4761 <tt>desc.<var>option</var></tt>. This should be formatted
4762 like the extended description part of a <tt>Description</tt>
4763 field entry <em>shifted one character to the left</em>.
4767 <tt><var>vardir</var>/methods</tt> will exist, and a method
4769 <tt><var>vardir</var>/methods/<var>group</var></tt>
4770 directory to store its state.
4774 The group name and method name must follow the rules for C
4780 <chapt id="conversion"><heading>Conversion procedure from old
4785 This is a brief summary of the procedure for converting a
4786 pre-2.0.0.0-format source package into the new format.
4790 You are strongly advised to download and examine the <prgn>hello</prgn>
4791 package, and to read the section in the <prgn>dpkg</prgn> programmers'
4792 manual describing the source packaging tools. More detail about the
4793 exact functionality of these tools is available in
4794 <manref name="dpkg-source" section="1">.
4801 Download the original source code from wherever it can
4802 be found and do any rearrangement required to make it
4803 look like the original tree of the Debian source. Put
4805 <tt><var>package</var>-<var>upstream-version</var>.orig/</tt>
4807 <tt><var>package</var>_<var>upstream-version</var>.orig.tar.gz</tt>.
4813 Rename all files <tt>debian.*</tt> to <tt>debian/*</tt>.
4814 There may be some exceptions to this, but this is a good
4820 Edit the <tt>debian/changelog</tt> - create or rename it
4821 if necessary. Add a new revision to the top with the
4822 appropriate details, and a local variables entry to the
4823 bottom to set Emacs to the right mode:
4826 mode: debian-changelog
4834 Edit/create <tt>debian/control</tt>:
4835 <list compact="compact">
4838 Remove the <tt>Version</tt> field. If it is
4839 generated unusually (not equal to the source
4840 version) you must use the -v option to
4841 dpkg-gencontrol (see below). <tt>Section</tt>,
4842 <tt>Priority</tt>, <tt>Maintainer</tt> go above
4843 the first blank line, most of the rest
4850 Reorder the fields and add a blank line at an
4851 appropriate point, separating the source package
4852 fields from the binary package fields.
4857 <p>Add the <tt>Source</tt> field.</p></item>
4861 Add the <tt>Standards-Version</tt> field. (Please
4862 check out the Debian Policy Manual for details
4863 about this field.)</p>
4868 Change the <tt>Architecture</tt> field for each
4869 package to <tt>any</tt>, <tt>all</tt> or whatever.
4870 If there isn't an <tt>Architecture</tt> field add
4876 If any other use of sed or things used to happen
4877 to make the binary control files use
4878 <prgn>dpkg-gencontrol</prgn>'s variable
4879 substitution features to achieve the same effect.
4880 Use <tt>debian/substvars</tt> if you need to put
4881 unusally-generated information (apart from details
4882 of <tt>.deb</tt> files) in the <tt>.changes</tt>
4890 <p>Edit the <tt>debian/rules</tt>:
4891 <list compact="compact">
4894 Remove the <prgn>source</prgn> and
4895 <prgn>diff</prgn> and any <prgn>changes</prgn> and
4896 <prgn>dist</prgn> targets. These things now
4897 happen in a package-independent way and are not
4898 done by <tt>debian/rules</tt>.</p>
4902 Split the <prgn>binary</prgn> target into
4903 <prgn>binary-arch</prgn> and
4904 <prgn>binary-indep</prgn>; in many cases all of
4905 <prgn>binary</prgn> should go into
4906 <prgn>binary-arch</prgn>. Create the
4907 <prgn>binary</prgn> target and the unused of the
4908 two other <prgn>binary-*</prgn> targets if there
4909 is one - you can copy the ones from the
4910 <prgn>hello</prgn> package.</p>
4914 Change the <prgn>binary</prgn> target to use
4915 <prgn>dpkg-gencontrol</prgn> to make the package
4916 control file(s). Move it to after all the files
4917 have been installed but just before the last
4918 <prgn>chown</prgn> and <prgn>chmod</prgn> in the
4923 Change occurrences of <tt>debian-tmp</tt> to
4924 <tt>debian/tmp</tt>.</p>
4928 Change occurrences of
4929 <tt>debian.{post,pre}{inst,rm}</tt> to
4930 <tt>debian/*</tt>.</p>
4934 Remove the version number setting at the top, if
4939 Ensure that the package's Debian-specific and
4940 upstream changelogs are installed.</p>
4948 Change the package to use <prgn>dpkg-shlibdeps</prgn> to
4949 determine its shared library dependencies and substitute
4950 them in. Shared library dependencies should no longer
4951 be hardwired in the source package.</p>
4956 Check that the <tt>debian/README</tt> is really the
4957 copyright file, and if so rename it to
4958 <tt>debian/copyright</tt> and edit <tt>debian/rules</tt>
4959 to cope with this and to change the installation of the
4961 <tt>/usr/doc/<var>package</var>/copyright</tt> to
4962 <tt>/usr/doc/copyright/<var>package</var></tt>. If it
4963 isn't then find <tt>debian/copyright</tt> and decide
4964 what to do with the <tt>README</tt>.</p>
4968 <p>Check for various other anachronisms and problems:
4969 <list compact="compact">
4972 Remove any <tt>Package_Revision</tt>,
4973 <tt>Package-Revision</tt> or <tt>Revision</tt>
4978 Rename <tt>Optional</tt> to <tt>Suggests</tt>,
4979 <tt>Recommended</tt> to
4980 <tt>Recommends</tt>.</p>
4985 <tt>/usr/doc/examples/<var>package</var></tt> to
4986 <tt>/usr/doc/<var>package</var>/examples</tt>.</p>
4990 Make sure that manpages are installed
4995 Check that the description has an extended
4996 description, is well-formatted and meaningful and
4997 helpful to people wanting to know whether to
4998 install a package.</p>
5005 <p>Look everything over.</p></item>
5009 Do a test build using <tt>dpkg-buildpackage -us -uc -sa
5010 -r<var>whatever</var></tt>. Check the permissions and
5011 locations of files in the resulting package by examining
5012 the output of <tt>dpkg-deb --contents</tt>, and check
5013 that the source build happened OK. Test install the
5014 binary package(s) and test extract the source
5020 Sign the release: either rebuild everything with
5021 <tt>dpkg-buildpackage -sa</tt>, or PGP-sign the
5022 <tt>.dsc</tt>, rebuild the <tt>.changes</tt> using
5023 <tt>dpkg-genchanges -sa</tt>, and then PGP-sign the
5024 <tt>.changes</tt>.</p>
5031 The use of <tt>-sa</tt> on <prgn>dpkg-buildpackage</prgn> and
5032 <prgn>dpkg-genchanges</prgn> is important when doing the first
5033 build/uploading of a new-format source package. Unless this
5034 happens to be Debian revision <tt>0</tt> or <tt>1</tt> by
5035 default the original source tarfile will not be included in
5036 the uploaded files listed in the <tt>.changes</tt> file, and
5037 so it won't be installed on the FTP site. <tt>-sa</tt>
5038 requests that the original source be included