@SysInclude{ fontdefs } @SysInclude{ langdefs } @SysInclude{ dl } @SysInclude{ docf } @Use { @DocumentLayout @ParaGap { 1.70vx } @InitialBreak { 1.0fx ragged hyphen } @PageHeaders { Titles } @OptimizePages { Yes } @RunningEvenTop { @B { @PageNum } } @RunningOddTop { @Right { @B { @PageNum } } } @RunningEvenFoot { version 0.2.0.0 (dpkg 1.3.7), 23 August 1996 @Right { {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} programmers' manual } } @RunningOddFoot { {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} programmers' manual @Right { version 0.2.0.0 (dpkg 1.3.7), 23 August 1996 } } @RunningStartEvenTop { @Null } @RunningStartOddTop { @Null } @RunningStartEvenFoot { version 0.2.0.0 (dpkg 1.3.7), 23 August 1996 @Right { {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} programmers' manual } } @RunningStartOddFoot { {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} programmers' manual @Right { version 0.2.0.0 (dpkg 1.3.7), 23 August 1996 } } # @RunningEvenTop { @B { @PageNum } @Centre { } @Right { @MinorNum } } # @RunningOddTop { @MinorNum @Centre { @MinorTitle } @Right { @B { @PageNum } } } # @RunningEvenFoot { version 0.2.0.0 (dpkg 1.3.7), 23 August 1996 @Right { {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} programmers' manual } } # @RunningOddFoot { {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} programmers' manual @Right { version 0.2.0.0 (dpkg 1.3.7), 23 August 1996 } } # @RunningStartEvenTop { @Null } # @RunningStartOddTop { @Null } # @RunningStartEvenFoot { version 0.2.0.0 (dpkg 1.3.7), 23 August 1996 @Right { {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} programmers' manual } } # @RunningStartOddFoot { {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} programmers' manual @Right { version 0.2.0.0 (dpkg 1.3.7), 23 August 1996 } } } @Use { @OrdinaryLayout } @Doc @Text @Begin @CenteredDisplay {clines 1.3v} @Break { +5p @Font Bold @Font { {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} programmers' manual } -2p @Font { Ian Jackson {{0.7 1.0} @Scale {Courier Bold} @Font {<"ijackson@gnu.ai.mit.edu">}} } version 0.2.0.0 (dpkg 1.3.7), 23 August 1996 } @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { 0.1.|0.5fe{ Abstract}}}} |0f }} //0.0fe @LP This manual describes the technical aspects of creating Debian binary and source packages. It also documents the interface between {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}} and its access method scripts. It does not deal with the Debian Project policy requirements, and it assumes familiarity with {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}}'s functions from the system administrator's perspective. @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { 0.2.|0.5fe{ Contents}}}} |0f }} //0.0fe //1vx//0.3vx Bold @Font @HAdjust { @HContract { { 1. } |5fx {Introduction and scope of this manual} } |2f @PageOf { ch-scope } } //1.00vx //0.3vx Bold @Font @HAdjust { @HContract { { 2. } |5fx {Binary packages} } |2f @PageOf { ch-binarypkg } } //1.00vx @HAdjust { @HContract { { 2.1. } |5fx {Creating package files "-" {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"deb"}}} } |2f @PageOf { s-bincreating } } //0.95vx @HAdjust { @HContract { { 2.2. } |5fx {Package control information files} } |2f @PageOf { s-controlarea } } //0.95vx @HAdjust { @HContract { { 2.3. } |5fx {The main control information file: {{0.7 1.0} @Scale {Courier Bold} @Font {control}}} } |2f @PageOf { s-controlfile } } //0.95vx //0.3vx Bold @Font @HAdjust { @HContract { { 3. } |5fx {Source packages} } |2f @PageOf { ch-sourcepkg } } //1.00vx @HAdjust { @HContract { { 3.1. } |5fx {Tools for processing source packages} } |2f @PageOf { s-sourcetools } } //0.95vx @HAdjust { @HContract { { 3.2. } |5fx {The Debianised source tree} } |2f @PageOf { s-sourcetree } } //0.95vx @HAdjust { @HContract { { 3.3. } |5fx {Source packages as archives} } |2f @PageOf { s-sourcearchives } } //0.95vx @HAdjust { @HContract { { 3.4. } |5fx {Unpacking a Debian source package without {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"source"}}} } |2f @PageOf { s3.4 } } //0.95vx //0.3vx Bold @Font @HAdjust { @HContract { { 4. } |5fx {Control files and their fields} } |2f @PageOf { ch-controlfields } } //1.00vx @HAdjust { @HContract { { 4.1. } |5fx {Syntax of control files} } |2f @PageOf { s4.1 } } //0.95vx @HAdjust { @HContract { { 4.2. } |5fx {List of fields } } |2f @PageOf { s4.2 } } //0.95vx //0.3vx Bold @Font @HAdjust { @HContract { { 5. } |5fx {Version numbering} } |2f @PageOf { ch-versions } } //1.00vx //0.3vx Bold @Font @HAdjust { @HContract { { 6. } |5fx {Package maintainer scripts and installation procedure} } |2f @PageOf { ch-maintainerscripts } } //1.00vx @HAdjust { @HContract { { 6.1. } |5fx {Introduction to package maintainer scripts} } |2f @PageOf { s6.1 } } //0.95vx @HAdjust { @HContract { { 6.2. } |5fx {Summary of ways maintainer scripts are called} } |2f @PageOf { s-mscriptsinstact } } //0.95vx @HAdjust { @HContract { { 6.3. } |5fx {Details of unpack phase of installation or upgrade} } |2f @PageOf { s6.3 } } //0.95vx @HAdjust { @HContract { { 6.4. } |5fx {Details of configuration} } |2f @PageOf { s6.4 } } //0.95vx @HAdjust { @HContract { { 6.5. } |5fx {Details of removal "and/or" configuration purging} } |2f @PageOf { s6.5 } } //0.95vx //0.3vx Bold @Font @HAdjust { @HContract { { 7. } |5fx {Descriptions of packages "-" the {{0.7 1.0} @Scale {Courier Bold} @Font {Description}} field} } |2f @PageOf { ch-descriptions } } //1.00vx @HAdjust { @HContract { { 7.1. } |5fx {Types of formatting line in the extended description} } |2f @PageOf { s7.1 } } //0.95vx @HAdjust { @HContract { { 7.2. } |5fx {Notes about writing descriptions} } |2f @PageOf { s7.2 } } //0.95vx @HAdjust { @HContract { { 7.3. } |5fx {Example description in control file for Smail} } |2f @PageOf { s7.3 } } //0.95vx //0.3vx Bold @Font @HAdjust { @HContract { { 8. } |5fx {Declaring relationships between packages} } |2f @PageOf { ch-relationships } } //1.00vx @HAdjust { @HContract { { 8.1. } |5fx {Syntax of relationship fields} } |2f @PageOf { s-depsyntax } } //0.95vx @HAdjust { @HContract { { 8.2. } |5fx {Dependencies "-" {{0.7 1.0} @Scale {Courier Bold} @Font {Depends}}, {{0.7 1.0} @Scale {Courier Bold} @Font {Recommends}}, {{0.7 1.0} @Scale {Courier Bold} @Font {Suggests}}, {{0.7 1.0} @Scale {Courier Bold} @Font {"Pre"--"Depends"}}} } |2f @PageOf { s8.2 } } //0.95vx @HAdjust { @HContract { { 8.3. } |5fx {Alternative packages "-" {{0.7 1.0} @Scale {Courier Bold} @Font {Conflicts}} and {{0.7 1.0} @Scale {Courier Bold} @Font {Replaces}}} } |2f @PageOf { s-conflicts } } //0.95vx @HAdjust { @HContract { { 8.4. } |5fx {Virtual packages "-" {{0.7 1.0} @Scale {Courier Bold} @Font {Provides}}} } |2f @PageOf { s-virtual } } //0.95vx @HAdjust { @HContract { { 8.5. } |5fx {{{0.7 1.0} @Scale {Courier Bold} @Font {Replaces}} "-" overwriting files and replacing packages} } |2f @PageOf { s-replaces } } //0.95vx @HAdjust { @HContract { { 8.6. } |5fx {Defaults for satisfying dependencies "-" ordering} } |2f @PageOf { s8.6 } } //0.95vx //0.3vx Bold @Font @HAdjust { @HContract { { 9. } |5fx {Configuration file handling} } |2f @PageOf { ch-conffiles } } //1.00vx @HAdjust { @HContract { { 9.1. } |5fx {Automatic handling of configuration files by {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}}} } |2f @PageOf { s9.1 } } //0.95vx @HAdjust { @HContract { { 9.2. } |5fx {"Fully-featured" maintainer script configuration handling} } |2f @PageOf { s9.2 } } //0.95vx //0.3vx Bold @Font @HAdjust { @HContract { { 10. } |5fx {Alternative versions of an interface "-" {{0.7 1.0} @Scale {Courier Bold} @Font {"update"--"alternatives"}}} } |2f @PageOf { ch-alternatives } } //1.00vx //0.3vx Bold @Font @HAdjust { @HContract { { 11. } |5fx {Diversions "-" overriding a package's version of a file} } |2f @PageOf { ch-diversions } } //1.00vx //0.3vx Bold @Font @HAdjust { @HContract { { 12. } |5fx {Shared libraries} } |2f @PageOf { ch-sharedlibs } } //1.00vx //0.3vx Bold @Font @HAdjust { @HContract { { 13. } |5fx {Configuration of {{0.7 1.0} @Scale {Courier Bold} @Font {init}}} } |2f @PageOf { ch-sysvinit } } //1.00vx @HAdjust { @HContract { { 13.1. } |5fx {Introduction to the {{0.7 1.0} @Scale {Courier Bold} @Font {init.d}} scheme} } |2f @PageOf { s13.1 } } //0.95vx @HAdjust { @HContract { { 13.2. } |5fx {Writing {{0.7 1.0} @Scale {Courier Bold} @Font {init.d}} scripts} } |2f @PageOf { s13.2 } } //0.95vx @HAdjust { @HContract { { 13.3. } |5fx {Managing the {{0.7 1.0} @Scale {Courier Bold} @Font {rc{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {n}}}}.d}} links "-" {{0.7 1.0} @Scale {Courier Bold} @Font {"update"--"rc.d"}}} } |2f @PageOf { s13.3 } } //0.95vx @HAdjust { @HContract { { 13.4. } |5fx {"Boot-time" initialisation "-" {{0.7 1.0} @Scale {Courier Bold} @Font {rc.boot}}} } |2f @PageOf { s13.4 } } //0.95vx @HAdjust { @HContract { { 13.5. } |5fx {Notes} } |2f @PageOf { s13.5 } } //0.95vx @HAdjust { @HContract { { 13.6. } |5fx {Example} } |2f @PageOf { s13.6 } } //0.95vx //0.3vx Bold @Font @HAdjust { @HContract { { 14. } |5fx {{{0.7 1.0} @Scale {Courier Bold} @Font {dselect}}'s interface to its installation methods} } |2f @PageOf { ch-methif } } //1.00vx @HAdjust { @HContract { { 14.1. } |5fx {Functions of the method scripts} } |2f @PageOf { s14.1 } } //0.95vx @HAdjust { @HContract { { 14.2. } |5fx {Location and arguments of the method scripts} } |2f @PageOf { s14.2 } } //0.95vx @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { 0.3.|0.5fe{ Copyright Notice}}}} |0f }} //0.0fe @LP Copyright ©1996 Ian Jackson. @LP This manual is free software; you may redistribute it "and/or" modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. @LP This is distributed in the hope that it will be useful, but {{Times Slope} @Font {without any warranty}}; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details. @LP You should have received a copy of the GNU General Public License with your Debian "GNU/Linux" system, in {{0.7 1.0} @Scale {Courier Bold} @Font {"/usr/doc/copyright/GPL"}}, or with the {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} source package as the file {{0.7 1.0} @Scale {Courier Bold} @Font {COPYING}}. If not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. @LP @NP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.2 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +5p @Font { 1.2vx @Break { {@PageMark ch-scope} 1.|0.5fe{ Introduction and scope of this manual}}}} |0f }} //0.0fe @LP {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} is a suite of programs for creating binary package files and installing and removing them on Unix systems.{@FootNote{ {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} is targetted primarily at Debian "GNU/Linux," but may work on or be ported to other systems.}} @LP The binary packages are designed for the management of installed executable programs (usually compiled binaries) and their associated data, though source code examples and documentation are provided as part of some packages. @LP This manual describes the technical aspects of creating Debian binary packages ({{0.7 1.0} @Scale {Courier Bold} @Font {.deb}} files). It documents the behaviour of the package management programs {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}}, {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}} et al. and and the way they interact with packages. @LP It also documents the interaction between {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}}'s core and the access method scripts it uses to actually install the selected packages, and describes how to create a new access method. @LP This manual does not go into detail about the options and usage of the package building and installation tools. It should therefore be read in conjuction with those programs' manpages. @LP The utility programs which are provided with {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} for managing various system configuration and similar issues, such as {{0.7 1.0} @Scale {Courier Bold} @Font {"update"--"rc.d"}} and {{0.7 1.0} @Scale {Courier Bold} @Font {"install"--"info"}}, are not described in detail here "-" please see their manpages. @LP It does {{Times Slope} @Font {not}} describe the policy requirements imposed on Debian packages, such as the permissions on files and directories, documentation requirements, upload procedure, and so on. You should see the Debian packaging policy manual for these details. (Many of them will probably turn out to be helpful even if you don't plan to upload your package and make it available as part of the distribution.) @LP It is assumed that the reader is reasonably familiar with the {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} System Administrators' manual. Unfortunately this manual does not yet exist. @LP The Debian version of the FSF's GNU hello program is provided as an example for people wishing to create Debian packages. @LP {{Times Slope} @Font {Note that this document is still a draft!}} @LP @NP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.2 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +5p @Font { 1.2vx @Break { {@PageMark ch-binarypkg} 2.|0.5fe{ Binary packages}}}} |0f }} //0.0fe @LP The binary package has two main sections. The first part consists of various control information files and scripts used by {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} when installing and removing. See `Package control information files', page @PageOf{s-controlarea}. @LP The second part is an archive (currently a {{0.7 1.0} @Scale {Courier Bold} @Font {tar}} archive) containing files and directories to be installed. @LP In the future binary packages may also contain other components, such as checksums and digital signatures. @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s-bincreating} 2.1.|0.5fe{ Creating package files "-" {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"deb"}}}}}} |0f }} //0.0fe @LP All manipulation of binary package files is done by {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"deb"}}; it's the only program that has knowledge of the format. ({{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"deb"}} may be invoked by calling {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}}, as {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} will spot that the options requested are appropriate to {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"deb"}} and invoke that instead with the same arguments.) @LP In order to create a binary package you must make a directory tree which contains all the files and directories you want to have in the filesystem data part of the package. In "Debian-format" source packages this directory is usually {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/tmp"}}, relative to the top of the package's source tree. @LP They should have the locations (relative to the root of the directory tree you're constructing) ownerships and permissions which you want them to have on the system when they are installed. @LP With current versions of {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} the "uid/username" and "gid/groupname" mappings for the users and groups being used should be the same on the system where the package is built and the one where it is installed. @LP You need to add one special directory to the root of the miniature filesystem tree you're creating: {{0.7 1.0} @Scale {Courier Bold} @Font {DEBIAN}}. It should contain the control information files, notably the binary package control file (see `The main control information file: {{0.7 1.0} @Scale {Courier Bold} @Font {control}}', page @PageOf{s-controlfile}). @LP The {{0.7 1.0} @Scale {Courier Bold} @Font {DEBIAN}} directory will not appear in the filesystem archive of the package, and so won't be installed by {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} when the package is installed. @LP When you've prepared the package, you should invoke: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { dpkg ""--""--"build" {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {directory}}}}}}} //0.2fe @LP This will build the package in {{0.7 1.0} @Scale {Courier Bold} @Font {{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {directory}}}}.deb}}. ({{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} knows that {{0.7 1.0} @Scale {Courier Bold} @Font {""--""--"build"}} is a {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"deb"}} option, so it invokes {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"deb"}} with the same arguments to build the package.) @LP See the manpage {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"deb(8)"}} for details of how to examine the contents of this "newly-created" file. You may find the output of following commands enlightening: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { "dpkg"--"deb" ""--""--"info" {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {filename}}}}.deb "dpkg"--"deb" ""--""--"contents" {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {filename}}}}.deb}}} //0.2fe @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s-controlarea} 2.2.|0.5fe{ Package control information files}}}} |0f }} //0.0fe @LP The control information portion of a binary package is a collection of files with names known to {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}}. It will treat the contents of these files specially "-" some of them contain information used by {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} when installing or removing the package; others are scripts which the package maintainer wants {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} to run. @LP It is possible to put other files in the package control area, but this is not generally a good idea (though they will largely be ignored). @LP Here is a brief list of the control info files supported by {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} and a summary of what they're used for. @LP {|0.5f {{{0.7 1.0} @Scale {Courier Bold} @Font {control}}}} //1.0vx @RawIndentedDisplay { This is the key description file used by {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}}. It specifies the package's name and version, gives its description for the user, states its relationships with other packages, and so forth. See `The main control information file: {{0.7 1.0} @Scale {Courier Bold} @Font {control}}', page @PageOf{s-controlfile}. @LP It is usually generated automatically from information in the source package by the {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"gencontrol"}} program, and with assistance from {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"shlibdeps"}}. See `Tools for processing source packages', page @PageOf{s-sourcetools}. } //0fe //1.2fx {|0.5f {{{0.7 1.0} @Scale {Courier Bold} @Font {postinst}}, {{0.7 1.0} @Scale {Courier Bold} @Font {preinst}}, {{0.7 1.0} @Scale {Courier Bold} @Font {postrm}}, {{0.7 1.0} @Scale {Courier Bold} @Font {prerm}}}} //1.0vx @RawIndentedDisplay { These are exectuable files (usually scripts) which {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} runs during installation, upgrade and removal of packages. They allow the package to deal with matters which are particular to that package or require more complicated processing than that provided by {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}}. Details of when and how they are called are in `Package maintainer scripts and installation procedure', page @PageOf{ch-maintainerscripts}. @LP It is very important to make these scripts itempotent.{@FootNote{ That means that if it runs successfully or fails and then you call it again it doesn't bomb out, but just ensures that everything is the way it ought to be.}} This is so that if an error occurs, the user interrupts {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} or some other unforeseen circumstance happens you don't leave the user with a "badly-broken" package. @LP The maintainer scripts are guaranteed to run with a controlling terminal and can interact with the user. If they need to prompt for passwords, do "full-screen" interaction or something similar you should do these things to and from {{0.7 1.0} @Scale {Courier Bold} @Font {"/dev/tty"}}, since {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} will at some point redirect scripts' standard input and output so that it can log the installation process. Likewise, because these scripts may be executed with standard output redirected into a pipe for logging purposes, Perl scripts should set unbuffered output by setting {{0.7 1.0} @Scale {Courier Bold} @Font {"$|=1"}} so that the output is printed immediately rather than being buffered. @LP Each script should return a zero exit status for success, or a nonzero one for failure. } //0fe //1.2fx {|0.5f {{{0.7 1.0} @Scale {Courier Bold} @Font {conffiles}}}} //1.0vx @RawIndentedDisplay { This file contains a list of configuration files which are to be handled automatically by {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} (see `Configuration file handling', page @PageOf{ch-conffiles}). Note that not necessarily every configuration file should be listed here. } //0fe //1.2fx {|0.5f {{{0.7 1.0} @Scale {Courier Bold} @Font {shlibs}}}} //1.0vx @RawIndentedDisplay { This file contains a list of the shared libraries supplied by the package, with dependency details for each. This is used by {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"shlibdeps"}} when it determines what dependencies are required in a package control file. @LP Each line is of the form: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"library"--"name"}}}} {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"version"--"or"--"soname"}}}} {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {dependencies ...}}}}}}} //0.2fe @LP {{Times Slope} @Font {"library-name"}} is the name of the shared library, for example {{0.7 1.0} @Scale {Courier Bold} @Font {libc5}}. @LP {{Times Slope} @Font {"version-or-soname"}} is the soname of the library "-" ie, the thing that must exactly match for the library to be recognised by {{0.7 1.0} @Scale {Courier Bold} @Font {ld.so}}. Usually this is major version number of the library. @LP {{Times Slope} @Font {dependencies}} has the same syntax as a dependency field in a binary package control file. It should give details of which package(s) are required to satisfy a binary built against the version of the library contained in the package. See `Syntax of relationship fields', page @PageOf{s-depsyntax}. @LP For example, if the package {{0.7 1.0} @Scale {Courier Bold} @Font {foo}} contains {{0.7 1.0} @Scale {Courier Bold} @Font {libfoo.so.1.2.3}}, where the soname of the library is {{0.7 1.0} @Scale {Courier Bold} @Font {libfoo.so.1}}, and the first version of the package which contained a minor number of at least {{0.7 1.0} @Scale {Courier Bold} @Font {2.3}} was {{Times Slope} @Font {"1.2.3-1"}}, then the package's {{Times Slope} @Font {shlibs}} could say: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { libfoo 1 foo (>= "1.2.3"--"1)"}}} //0.2fe @LP The "version-specific" dependency is to avoid warnings from {{0.7 1.0} @Scale {Courier Bold} @Font {ld.so}} about using older shared libraries with newer binaries. } //0fe @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s-controlfile} 2.3.|0.5fe{ The main control information file: {{0.7 1.0} @Scale {Courier Bold} @Font {control}}}}}} |0f }} //0.0fe @LP The most important control information file used by {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} when it installs a package is {{0.7 1.0} @Scale {Courier Bold} @Font {control}}. It contains all the package's `vital statistics'. @LP The binary package control files of packages built from Debian sources are made by a special tool, {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"gencontrol"}}, which reads {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/control"}} and {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/changelog"}} to find the information it needs. See `Source packages', page @PageOf{ch-sourcepkg} for more details. @LP The fields in binary package control files are: //1.0vx {@RawBulletList gap { 1.0vx } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Package}} (mandatory) } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Version}} (mandatory) } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Architecture}} (mandatory){@FootNote{ This field should appear in all packages, though {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} doesn't require it yet so that old packages can still be installed.}} } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Depends}}, {{0.7 1.0} @Scale {Courier Bold} @Font {Provides}} et al. } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Essential}} } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Maintainer}} } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Section}}, {{0.7 1.0} @Scale {Courier Bold} @Font {Priority}} } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Source}} } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Description}} } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {"Installed"--"Size"}} } @RawEndList}//0ve @LP A description of the syntax of control files and the purpose of these fields is available in `Control files and their fields', page @PageOf{ch-controlfields}. @LP @NP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.2 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +5p @Font { 1.2vx @Break { {@PageMark ch-sourcepkg} 3.|0.5fe{ Source packages}}}} |0f }} //0.0fe @LP The Debian binary packages in the distribution are generated from Debian sources, which are in a special format to assist the easy and automatic building of binaries. @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s-sourcetools} 3.1.|0.5fe{ Tools for processing source packages}}}} |0f }} //0.0fe @LP Various tools are provided for manipulating source packages; they pack and unpack sources and help build of binary packages and help manage the distribution of new versions. @LP They are introduced and typical uses described here; see {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"source(1)"}} for full documentation about their arguments and operation. @LP For examples of how to construct a Debian source package, and how to use those utilities that are used by Debian source packages, please see the {{0.7 1.0} @Scale {Courier Bold} @Font {hello}} example package. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s3.1.1} 3.1.1.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"source"}} "-" packs and unpacks Debian source packages}}}//0.2fe @LP This program is frequently used by hand, and is also called from "package-independent" automated building scripts such as {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"buildpackage"}}. @LP To unpack a package it is typically invoked with //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { "dpkg"--"source" ""--"x" {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {".../path/to/filename"}}}}.dsc}}} //0.2fe with the {{0.7 1.0} @Scale {Courier Bold} @Font {{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {filename}}}}.tar.gz}} and {{0.7 1.0} @Scale {Courier Bold} @Font {{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {filename}}}}.diff.gz}} (if applicable) in the same directory. It unpacks into {{0.7 1.0} @Scale {Courier Bold} @Font {{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {package}}}}""--""{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {version}}}}}}, and if applicable {{0.7 1.0} @Scale {Courier Bold} @Font {{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {package}}}}""--""{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {version}}}}.orig}}, in the current directory. @LP To create a packed source archive it is typically invoked: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { "dpkg"--"source" ""--"b" {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {package}}}}""--""{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {version}}}}}}} //0.2fe This will create the {{0.7 1.0} @Scale {Courier Bold} @Font {.dsc}}, {{0.7 1.0} @Scale {Courier Bold} @Font {.tar.gz}} and {{0.7 1.0} @Scale {Courier Bold} @Font {.diff.gz}} (if appropriate) in the current directory. {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"source"}} does not clean the source tree first "-" this must be done separately if it is required. @LP See also `Source packages as archives', page @PageOf{s-sourcearchives}. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s3.1.2} 3.1.2.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"buildpackage"}} "-" overall "package-building" control script}}}//0.2fe @LP {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"buildpackage"}} is a script which invokes {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"source"}}, the {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/rules"}} targets {{0.7 1.0} @Scale {Courier Bold} @Font {clean}}, {{0.7 1.0} @Scale {Courier Bold} @Font {build}} and {{0.7 1.0} @Scale {Courier Bold} @Font {binary}}, {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"genchanges"}} and {{0.7 1.0} @Scale {Courier Bold} @Font {pgp}} to build a signed source and binary package upload. @LP It is usually invoked by hand from the top level of the built or unbuilt source directory. It may be invoked with no arguments; useful arguments include: //1.0vx {|0.5f {{{0.7 1.0} @Scale {Courier Bold} @Font {""--"uc"}}, {{0.7 1.0} @Scale {Courier Bold} @Font {""--"us"}}}} //1.0vx {|2f { Do not "PGP-sign" the {{0.7 1.0} @Scale {Courier Bold} @Font {.changes}} file or the source package {{0.7 1.0} @Scale {Courier Bold} @Font {.dsc}} file, respectively. }} //1.0vx {|0.5f {{{0.7 1.0} @Scale {Courier Bold} @Font {""--"p"{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"pgp-command"}}}}}}}} //1.0vx {|2f { Invoke {{Times Slope} @Font {"pgp-command"}} instead of finding {{0.7 1.0} @Scale {Courier Bold} @Font {pgp}} on the {{0.7 1.0} @Scale {Courier Bold} @Font {PATH}}. {{Times Slope} @Font {"pgp-command"}} must behave just like {{0.7 1.0} @Scale {Courier Bold} @Font {pgp}}. }} //1.0vx {|0.5f {{{0.7 1.0} @Scale {Courier Bold} @Font {""--"r"{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"root-command"}}}}}}}} //1.0vx {|2f { When root privilege is required, invoke the command {{Times Slope} @Font {"root-command"}}. {{Times Slope} @Font {"root-command"}} should invoke its first argument as a command, from the {{0.7 1.0} @Scale {Courier Bold} @Font {PATH}} if necessary, and pass its second and subsequent arguments to the command it calls. If no {{Times Slope} @Font {"root-command"}} is supplied then {{Times Slope} @Font {"dpkg-buildpackage"}} will take no special action to gain root privilege, so that for most packages it will have to be invoked as root to start with. }} //1.0vx {|0.5f {{{0.7 1.0} @Scale {Courier Bold} @Font {""--"b"}}, {{0.7 1.0} @Scale {Courier Bold} @Font {""--"B"}}}} //1.0vx {|2f { Two types of "binary-only" build and upload "-" see {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"source(1)"}}. }} //0.2fe @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s3.1.3} 3.1.3.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"gencontrol"}} "-" generates binary package control files}}}//0.2fe @LP This program is usually called from {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/rules"}} (see `The Debianised source tree', page @PageOf{s-sourcetree}) in the top level of the source tree. @LP This is usually done just before the files and directories in the temporary directory tree where the package is being built have their permissions and ownerships set and the package is constructed using {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"deb"}}{@FootNote{ This is so that the control file which is produced has the right permissions}}. @LP {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"gencontrol"}} must be called after all the files which are to go into the package have been placed in the temporary build directory, so that its calculation of the installed size of a package is correct. @LP It is also necessary for {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"gencontrol"}} to be run after {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"shlibdeps"}} so that the variable substitutions created by {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"shlibdeps"}} in {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/substvars"}} are available. @LP For a package which generates only one binary package, and which builds it in {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/tmp"}} relative to the top of the source package, it is usually sufficient to call: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { "dpkg"--"gencontrol"}}} //0.2fe @LP Sources which build several binaries will typically need something like: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { "dpkg"--"gencontrol" ""--"Pdebian/tmp"--""{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {pkg}}}} ""--"p"{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {package}}}}}}} //0.2fe The {{0.7 1.0} @Scale {Courier Bold} @Font {""--"P"}} tells {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"gencontrol"}} that the package is being built in a "non-default" directory, and the {{0.7 1.0} @Scale {Courier Bold} @Font {""--"p"}} tells it which package's control file should be generated. @LP {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"gencontrol"}} also adds information to the list of files in {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/files"}}, for the benefit of (for example) a future invocation of {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"genchanges"}}. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s3.1.4} 3.1.4.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"shlibdeps"}} "-" calculates shared library dependencies}}}//0.2fe @LP This program is usually called from {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/rules"}} just before {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"gencontrol"}} (see `The Debianised source tree', page @PageOf{s-sourcetree}), in the top level of the source tree. @LP Its arguments are executables{@FootNote{ They may be specified either in the locations in the source tree where they are created or in the locations in the temporary build tree where they are installed prior to binary package creation.}} for which shared library dependencies should be included in the binary package's control file. @LP If some of the executable(s) shared libraries should only warrant a {{0.7 1.0} @Scale {Courier Bold} @Font {Recommends}} or {{0.7 1.0} @Scale {Courier Bold} @Font {Suggests}}, or if some warrant a {{0.7 1.0} @Scale {Courier Bold} @Font {"Pre"--"Depends"}}, this can be achieved by using the {{0.7 1.0} @Scale {Courier Bold} @Font {""--"d"{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"dependency-field"}}}}}} option before those executable(s). (Each {{0.7 1.0} @Scale {Courier Bold} @Font {""--"d"}} option takes effect until the next {{0.7 1.0} @Scale {Courier Bold} @Font {""--"d"}}.) @LP {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"shlibdeps"}} does not directly cause the output control file to be modified. Instead by default it adds to the {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/substvars"}} file variable settings like {{0.7 1.0} @Scale {Courier Bold} @Font {shlibs:Depends}}. These variable settings must be referenced in dependency fields in the appropriate "per-binary-package" sections of the source control file. @LP For example, the {{0.7 1.0} @Scale {Courier Bold} @Font {procps}} package generates two kinds of binaries, simple C binaries like {{0.7 1.0} @Scale {Courier Bold} @Font {ps}} which require a predependency and "full-screen" ncurses binaries like {{0.7 1.0} @Scale {Courier Bold} @Font {top}} which require only a recommendation. It can say in its {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/rules"}}: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { "dpkg"--"shlibdeps" ""--"dPre"--"Depends" ps ""--"dRecommends" top}}} //0.2fe and then in its main control file {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/control"}}: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {...}}}} Package: procps "Pre"--"Depends:" "${shlibs:Pre"--"Depends}" Recommends: "${shlibs:Recommends}" {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {...}}}}}}} //0.2fe @LP Sources which produce several binary packages with different shared library dependency requirements can use the {{0.7 1.0} @Scale {Courier Bold} @Font {""--"p"{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {varnameprefix}}}}}} option to override the default {{0.7 1.0} @Scale {Courier Bold} @Font {shlib:}} prefix (one invocation of {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"shlibdeps"}} per setting of this option). They can thus produce several sets of dependency variables, each of the form {{0.7 1.0} @Scale {Courier Bold} @Font {{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {varnameprefix}}}}:{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {dependencyfield}}}}}}, which can be referred to in the appropriate parts of the binary package control files. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s3.1.5} 3.1.5.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"distaddfile"}} "-" adds a file to {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/files"}}}}}//0.2fe @LP Some packages' uploads need to include files other than the source and binary package files. @LP {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"distaddfile"}} adds a file to the {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/files"}} file so that it will be included in the {{0.7 1.0} @Scale {Courier Bold} @Font {.changes}} file when {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"genchanges"}} is run. @LP It is usually invoked from the {{0.7 1.0} @Scale {Courier Bold} @Font {binary}} target of {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/rules"}}: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { "dpkg"--"distaddfile" {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {filename}}}} {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {section}}}} {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {priority}}}}}}} //0.2fe The {{Times Slope} @Font {filename}} is relative to the directory where {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"genchanges"}} will expect to find it "-" this is usually the directory above the top level of the source tree. The {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/rules"}} target should put the file there just before or just after calling {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"distaddfile"}}. @LP The {{Times Slope} @Font {section}} and {{Times Slope} @Font {priority}} are passed unchanged into the resulting {{0.7 1.0} @Scale {Courier Bold} @Font {.changes}} file. See `{{0.7 1.0} @Scale {Courier Bold} @Font {Section}} and {{0.7 1.0} @Scale {Courier Bold} @Font {Priority}}', page @PageOf{s-f-classification}. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s3.1.6} 3.1.6.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"genchanges"}} "-" generates a {{0.7 1.0} @Scale {Courier Bold} @Font {.changes}} upload control file}}}//0.2fe @LP This program is usually called by "package-independent" automatic building scripts such as {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"buildpackage"}}, but it may also be called by hand. @LP It is usually called in the top level of a built source tree, and when invoked with no arguments will print out a straightforward {{0.7 1.0} @Scale {Courier Bold} @Font {.changes}} file based on the information in the source package's changelog and control file and the binary and source packages which should have been built. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s3.1.7} 3.1.7.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"parsechangelog"}} "-" produces parsed representation of a changelog}}}//0.2fe @LP This program is used internally by {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"source"}} et al. It may also occasionally be useful in {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/rules"}} and elsewhere. It parses a changelog, {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/changelog"}} by default, and prints a "control-file" format representation of the information in it to standard output. @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s-sourcetree} 3.2.|0.5fe{ The Debianised source tree}}}} |0f }} //0.0fe @LP The source archive scheme described later is intended to allow a Debianised source tree with some associated control information to be reproduced and transported easily. The Debianised source tree is a version of the original program with certain files added for the benefit of the Debianisation process, and with any other changes required made to the rest of the source code and installation scripts. @LP The extra files created for Debian are in the subdirectory {{0.7 1.0} @Scale {Courier Bold} @Font {debian}} of the top level of the Debianised source tree. They are described below. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s3.2.1} 3.2.1.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/rules"}} "-" the main building script}}}//0.2fe @LP This file is an executable makefile, and contains the "package-specific" recipies for compiling the package and building binary package(s) out of the source. @LP It must start with the line {{0.7 1.0} @Scale {Courier Bold} @Font {"#!/usr/bin/make" ""--"f"}}, so that it can be invoked by saying its name rather than invoking {{0.7 1.0} @Scale {Courier Bold} @Font {make}} explicitly. @LP The targets which are required to be present are: @LP {|0.5f {{{0.7 1.0} @Scale {Courier Bold} @Font {build}}}} //1.0vx @RawIndentedDisplay { This should perform all "non-interactive" configuration and compilation of the package. If a package has an interactive "pre-build" configuration routine, the Debianised source package should be built after this has taken place, so that it can be built without rerunning the configuration. @LP For some packages, notably ones where the same source tree is compiled in different ways to produce two binary packages, the {{0.7 1.0} @Scale {Courier Bold} @Font {build}} target does not make much sense. For these packages it is good enough to provide two (or more) targets ({{0.7 1.0} @Scale {Courier Bold} @Font {"build"--"a"}} and {{0.7 1.0} @Scale {Courier Bold} @Font {"build"--"b"}} or whatever) for each of the ways of building the package, and a {{0.7 1.0} @Scale {Courier Bold} @Font {build}} target that does nothing. The {{0.7 1.0} @Scale {Courier Bold} @Font {binary}} target will have to build the package in each of the possible ways and make the binary package out of each. @LP The {{0.7 1.0} @Scale {Courier Bold} @Font {build}} target must not do anything that might require root privilege. @LP The {{0.7 1.0} @Scale {Courier Bold} @Font {build}} target may need to run {{0.7 1.0} @Scale {Courier Bold} @Font {clean}} first "-" see below. @LP When a package has a configuration routine that takes a long time, or when the makefiles are poorly designed, or when {{0.7 1.0} @Scale {Courier Bold} @Font {build}} needs to run {{0.7 1.0} @Scale {Courier Bold} @Font {clean}} first, it is a good idea to {{0.7 1.0} @Scale {Courier Bold} @Font {touch build}} when the build process is complete. This will ensure that if {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/rules" build}} is run again it will not rebuild the whole program. } //0fe //1.2fx {|0.5f {{{0.7 1.0} @Scale {Courier Bold} @Font {binary}}, {{0.7 1.0} @Scale {Courier Bold} @Font {"binary"--"arch"}}, {{0.7 1.0} @Scale {Courier Bold} @Font {"binary"--"indep"}}}} //1.0vx @RawIndentedDisplay { The {{0.7 1.0} @Scale {Courier Bold} @Font {binary}} target should be all that is necessary for the user to build the binary package. It is split into two parts: {{0.7 1.0} @Scale {Courier Bold} @Font {"binary"--"arch"}} builds the packages' output files which are specific to a particular architecture, and {{0.7 1.0} @Scale {Courier Bold} @Font {"binary"--"indep"}} builds those which are not. @LP {{0.7 1.0} @Scale {Courier Bold} @Font {binary}} should usually be a target with no commands which simply depends on {{0.7 1.0} @Scale {Courier Bold} @Font {"binary"--"arch"}} and {{0.7 1.0} @Scale {Courier Bold} @Font {"binary"--"indep"}}. @LP Both {{0.7 1.0} @Scale {Courier Bold} @Font {"binary"--"*"}} targets should depend on the {{0.7 1.0} @Scale {Courier Bold} @Font {build}} target, above, so that the package is built if it has not been already. It should then create the relevant binary package(s), using {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"gencontrol"}} to make their control files and {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"deb"}} to build them and place them in the parent of the top level directory. @LP If one of the {{0.7 1.0} @Scale {Courier Bold} @Font {"binary"--"*"}} targets has nothing to do (this will be always be the case if the source generates only a single binary package, whether "architecture-dependent" or not) it {{Times Slope} @Font {must}} still exist, but should always succeed. @LP `Binary packages', page @PageOf{ch-binarypkg} describes how to construct binary packages. @LP The {{0.7 1.0} @Scale {Courier Bold} @Font {binary}} targets must be invoked as root. } //0fe //1.2fx {|0.5f {{{0.7 1.0} @Scale {Courier Bold} @Font {clean}}}} //1.0vx @RawIndentedDisplay { This should undo any effects that the {{0.7 1.0} @Scale {Courier Bold} @Font {build}} and {{0.7 1.0} @Scale {Courier Bold} @Font {binary}} targets may have had, except that it should leave alone any output files created in the parent directory by a run of {{0.7 1.0} @Scale {Courier Bold} @Font {binary}}. @LP If a {{0.7 1.0} @Scale {Courier Bold} @Font {build}} file is touched at the end of the {{0.7 1.0} @Scale {Courier Bold} @Font {build}} target, as suggested above, it must be removed as the first thing that {{0.7 1.0} @Scale {Courier Bold} @Font {clean}} does, so that running {{0.7 1.0} @Scale {Courier Bold} @Font {build}} again after an interrupted {{0.7 1.0} @Scale {Courier Bold} @Font {clean}} doesn't think that everything is already done. @LP The {{0.7 1.0} @Scale {Courier Bold} @Font {clean}} target must be invoked as root if {{0.7 1.0} @Scale {Courier Bold} @Font {binary}} has been invoked since the last {{0.7 1.0} @Scale {Courier Bold} @Font {clean}}, or if {{0.7 1.0} @Scale {Courier Bold} @Font {build}} has been invoked as root (since {{0.7 1.0} @Scale {Courier Bold} @Font {build}} may create directories, for example). } //0fe //1.2fx {|0.5f {{{0.7 1.0} @Scale {Courier Bold} @Font {"get"--"orig"--"source"}}}} //1.0vx @RawIndentedDisplay { This target fetches the most recent version of the original source package from a canonical archive site (via FTP or WWW, for example), does any necessary rearrangement to turn it into the original source tarfile format described below, and leaves it in the current directory. @LP This target may be invoked in any directory, and should take care to clean up any temporary files it may have left. @LP This target is optional, but providing it if possible is a good idea. } //0fe @LP The {{0.7 1.0} @Scale {Courier Bold} @Font {build}}, {{0.7 1.0} @Scale {Courier Bold} @Font {binary}} and {{0.7 1.0} @Scale {Courier Bold} @Font {clean}} targets must be invoked with a current directory of the package's "top-level" directory. @LP Additional targets may exist in {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/rules"}}, either as published or undocumented interfaces or for the package's internal use. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s3.2.2} 3.2.2.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/control"}}}}}//0.2fe @LP This file contains "version-independent" details about the source package and about the binary packages it creates. @LP It is a series of sets of control fields, each syntactically similar to a binary package control file. The sets are separated by one or more blank lines. The first set is information about the source package in general; each subsequent set describes one binary package that the source tree builds. @LP The syntax and semantics of the fields are described below in `Control files and their fields', page @PageOf{ch-controlfields}. @LP The general "(binary-package-independent)" fields are: //1.0vx {@RawBulletList gap { 1.0vx } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Source}} (mandatory) } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Maintainer}} } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Section}} and {{0.7 1.0} @Scale {Courier Bold} @Font {Priority}} (classification, mandatory) } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {"Standards"--"Version"}} } @RawEndList}//0ve @LP The "per-binary-package" fields are: //1.0vx {@RawBulletList gap { 1.0vx } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Package}} (mandatory) } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Architecture}} (mandatory) } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Description}} } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Section}} and {{0.7 1.0} @Scale {Courier Bold} @Font {Priority}} (classification) } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Essential}} } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Depends}} et al. (package interrelationships) } @RawEndList}//0ve @LP These fields are used by {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"gencontrol"}} to generate control files for binary packages (see below), by {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"genchanges"}} to generate the {{0.7 1.0} @Scale {Courier Bold} @Font {.changes}} file to accompany the upload, and by {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"source"}} when it creates the {{0.7 1.0} @Scale {Courier Bold} @Font {.dsc}} source control file as part of a source archive. @LP The fields here may contain variable references "-" their values will be substituted by {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"gencontrol"}}, {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"genchanges"}} or {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"source"}} when they generate output control files. See `{{0.7 1.0} @Scale {Courier Bold} @Font {"debian/substvars"}} and variable substitutions', page @PageOf{s-srcsubstvars} for details. @LP @CNP @Heading +2p @Font { 1.2vx @Break { {@PageMark s3.2.2.1} 3.2.2.1.|0.5fe{ "User-defined" fields}}}//0.2fe @LP Additional "user-defined" fields may be added to the source package control file. Such fields will be ignored, and not copied to (for example) binary or source package control files or upload control files. @LP If you wish to add additional unsupported fields to these output files you should use the mechanism described here. @LP Fields in the main source control information file with names starting {{0.7 1.0} @Scale {Courier Bold} @Font {X}}, followed by one or more of the letters {{0.7 1.0} @Scale {Courier Bold} @Font {BCS}} and a hyphen {{0.7 1.0} @Scale {Courier Bold} @Font {""--""}}, will be copied to the output files. Only the part of the field name after the hyphen will be used in the output file. Where the letter {{0.7 1.0} @Scale {Courier Bold} @Font {B}} is used the field will appear in binary package control files, where the letter {{0.7 1.0} @Scale {Courier Bold} @Font {S}} is used in source package control files and where {{0.7 1.0} @Scale {Courier Bold} @Font {C}} is used in upload control ({{0.7 1.0} @Scale {Courier Bold} @Font {.changes}}) files. @LP For example, if the main source information control file contains the field //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { "XBS"--"Comment:" I stand between the candle and the star.}}} //0.2fe then the binary and source package control files will contain the field //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { Comment: I stand between the candle and the star.}}} //0.2fe @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s-dpkgchangelog} 3.2.3.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/changelog"}}}}}//0.2fe @LP This file records the changes to the "Debian-specific" parts of the package{@FootNote{ Though there is nothing stopping an author who is also the Debian maintainer from using it for all their changes, it will have to be renamed if the Debian and upstream maintainers become different people.}}. @LP It has a special format which allows the package building tools to discover which version of the package is being built and find out other "release-specific" information. @LP That format is a series of entries like this: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {package}}}} ({{1.4285714285 1.0} @Scale {{{Times Slope} @Font {version}}}}) {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {distribution(s)}}}}; urgency={{1.4285714285 1.0} @Scale {{{Times Slope} @Font {urgency}}}} * {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {change details}}}} {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {more change details}}}} * {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {even more change details}}}} ""--""--"" {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {maintainer name and email address}}}} {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {date}}}}}}} //0.2fe @LP {{Times Slope} @Font {package}} and {{Times Slope} @Font {version}} are the source package name and version number. {{Times Slope} @Font {distribution(s)}} lists the distributions where this version should be installed when it is uploaded "-" it is copied to the {{0.7 1.0} @Scale {Courier Bold} @Font {Distribution}} field in the {{0.7 1.0} @Scale {Courier Bold} @Font {.changes}} file. See `{{0.7 1.0} @Scale {Courier Bold} @Font {Distribution}}', page @PageOf{s-f-Distribution}. @LP {{Times Slope} @Font {urgency}} is the value for the {{0.7 1.0} @Scale {Courier Bold} @Font {Urgency}} field in the {{0.7 1.0} @Scale {Courier Bold} @Font {.changes}} file for the upload. See `{{0.7 1.0} @Scale {Courier Bold} @Font {Urgency}}', page @PageOf{s-f-Urgency}. It is not possible to specify an urgency containing commas; commas are used to separate {{0.7 1.0} @Scale {Courier Bold} @Font {{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {keyword}}}}={{1.4285714285 1.0} @Scale {{{Times Slope} @Font {value}}}}}} settings in the {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} changelog format (though there is currently only one useful {{Times Slope} @Font {keyword}}, {{0.7 1.0} @Scale {Courier Bold} @Font {urgency}}). @LP The change details may in fact be any series of lines starting with at least two spaces, but conventionally each change starts with an asterisk and a separating space and continuation lines are indented so as to bring them in line with the start of the text above. Blank lines may be used here to separate groups of changes, if desired. @LP The maintainer name and email address should {{Times Slope} @Font {not}} necessarily be those of the usual package maintainer. They should be the details of the person doing {{Times Slope} @Font {this}} version. The information here will be copied to the {{0.7 1.0} @Scale {Courier Bold} @Font {.changes}} file, and then later used to send an acknowledgement when the upload has been installed. @LP The {{Times Slope} @Font {date}} should be in RFC822 format; it should include the timezone specified numerically, with the timezone name or abbreviation optionally present as a comment. @LP The first `title' line with the package name should start at the left hand margin; the `trailer' line with the maintainer and date details should be preceded by exactly one space. The maintainer details and the date must be separated by exactly two spaces. @LP An Emacs mode for editing this format is available: it is called {{0.7 1.0} @Scale {Courier Bold} @Font {"debian"--"changelog"--"mode"}}. You can have this mode selected automatically when you edit a Debian changelog by adding a local variables clause to the end of the changelog. @LP @CNP @Heading +2p @Font { 1.2vx @Break { {@PageMark s3.2.3.1} 3.2.3.1.|0.5fe{ Defining alternative changelog formats}}}//0.2fe @LP It is possible to use a different format to the standard one, by providing a parser for the format you wish to use. @LP In order to have {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"parsechangelog"}} run your parser, you must include a line within the last 40 lines of your file matching the Perl regular expression: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { "\\schangelog"--"format:\\s+([0"--"9a"--"z]+)\\W"}}} //0.2fe The part in parentheses should be the name of the format. @LP If such a line exists then {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"parsechangelog"}} will look for the parser as {{0.7 1.0} @Scale {Courier Bold} @Font {"/usr/lib/dpkg/parsechangelog/"{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"format-name"}}}}}} or {{0.7 1.0} @Scale {Courier Bold} @Font {"/usr/local/lib/dpkg/parsechangelog/"{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"format-name"}}}}}}; it is an error for it not to find it, or for it not to be an executable program. The default changelog format is {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}}, and a parser for it is provided with the {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} package. @LP The parser will be invoked with the changelog open on standard input at the start of the file. It should read the file (it may seek if it wishes) to determine the information required and return the parsed information to standard output in the form of a series of control fields in the standard format. By default it should return information about only the most recent version in the changelog; it should accept a {{0.7 1.0} @Scale {Courier Bold} @Font {""--"v"{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {version}}}}}} option to return changes information from all versions present {{Times Slope} @Font {strictly after}} {{Times Slope} @Font {version}}, and it should then be an error for {{Times Slope} @Font {version}} not to be present in the changelog. @LP The fields are: //1.0vx {@RawBulletList gap { 1.0vx } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Source}} } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Version}} (mandatory) } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Distribution}} (mandatory) } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Urgency}} (mandatory) } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Maintainer}} (mandatory) } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Date}} } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Changes}} (mandatory) } @RawEndList}//0ve @LP If several versions are being returned (due to the use of {{0.7 1.0} @Scale {Courier Bold} @Font {""--"v"}}), the urgency value should be of the highest urgency code listed at the start of any of the versions requested followed by the concatenated "(space-separated)" comments from all the versions requested; the maintainer, version, distribution and date should always be from the most recent version. @LP For the format of the {{0.7 1.0} @Scale {Courier Bold} @Font {Changes}} field see `{{0.7 1.0} @Scale {Courier Bold} @Font {Changes}}', page @PageOf{s-f-Changes}. @LP If the changelog format which is being parsed always or almost always leaves a blank line between individual change notes these blank lines should be stripped out, so as to make the resulting output compact. @LP If the changelog format does not contain date or package name information this information should be omitted from the output. The parser should not attempt to synthesise it or find it from other sources. @LP If the changelog does not have the expected format the parser should exit with a nonzero exit status, rather than trying to muddle through and possibly generating incorrect output. @LP A changelog parser may not interact with the user at all. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s-srcsubstvars} 3.2.4.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/substvars"}} and variable substitutions}}}//0.2fe @LP When {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"gencontrol"}}, {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"genchanges"}} and {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"source"}} generate control files they do variable substitutions on their output just before writing it. Variable substitutions have the form {{0.7 1.0} @Scale {Courier Bold} @Font {"${"{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"variable-name"}}}}"}"}}. The optional file {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/substvars"}} contains variable substitutions to be used; variables can also be set directly from {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/rules"}} using the {{0.7 1.0} @Scale {Courier Bold} @Font {""--"V"}} option to the source packaging commands, and certain predefined variables are available. @LP The file may be a static part of the source archive, or generated and modified dynamically by {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/rules"}} targets. In the latter case it must be removed by the {{0.7 1.0} @Scale {Courier Bold} @Font {clean}} target. @LP See {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"source(1)"}} for full details about source variable substitutions, including the format of {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/substvars"}}. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s3.2.5} 3.2.5.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/files"}}}}}//0.2fe @LP This file is not a permanent part of the source tree; it is used while building packages to record which files are being generated. {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"genchanges"}} uses it when it generates a {{0.7 1.0} @Scale {Courier Bold} @Font {.changes}} file. @LP It should not exist in a shipped source package, and so it (and any backup files or temporary files such as {{0.7 1.0} @Scale {Courier Bold} @Font {files.new}}{@FootNote{ {{0.7 1.0} @Scale {Courier Bold} @Font {files.new}} is used as a temporary file by {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"gencontrol"}} and {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"distaddfile"}} "-" they write a new version of {{0.7 1.0} @Scale {Courier Bold} @Font {files}} here before renaming it, to avoid leaving a corrupted copy if an error occurs}}) should be removed by the {{0.7 1.0} @Scale {Courier Bold} @Font {clean}} target. It may also be wise to ensure a fresh start by emptying or removing it at the start of the {{0.7 1.0} @Scale {Courier Bold} @Font {binary}} target. @LP {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"gencontrol"}} adds an entry to this file for the {{0.7 1.0} @Scale {Courier Bold} @Font {.deb}} file that will be created by {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"deb"}} from the control file that it generates, so for most packages all that needs to be done with this file is to delete it in {{0.7 1.0} @Scale {Courier Bold} @Font {clean}}. @LP If a package upload includes files besides the source package and any binary packages whose control files were made with {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"gencontrol"}} then they should be placed in the parent of the package's "top-level" directory and {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"distaddfile"}} should be called to add the file to the list in {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/files"}}. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s3.2.6} 3.2.6.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/tmp"}}}}}//0.2fe @LP This is the canonical temporary location for the construction of binary packages by the {{0.7 1.0} @Scale {Courier Bold} @Font {binary}} target. The directory {{0.7 1.0} @Scale {Courier Bold} @Font {tmp}} serves as the root of the filesystem tree as it is being constructed (for example, by using the package's upstream makefiles install targets and redirecting the output there), and it also contains the {{0.7 1.0} @Scale {Courier Bold} @Font {DEBIAN}} subdirectory. See `Creating package files "-" {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"deb"}}', page @PageOf{s-bincreating}. @LP If several binary packages are generated from the same source tree it is usual to use several {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/tmp"{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {something}}}}}} directories, for example {{0.7 1.0} @Scale {Courier Bold} @Font {"tmp"--"a"}} or {{0.7 1.0} @Scale {Courier Bold} @Font {"tmp"--"doc"}}. @LP Whatever {{0.7 1.0} @Scale {Courier Bold} @Font {tmp}} directories are created and used by {{0.7 1.0} @Scale {Courier Bold} @Font {binary}} must of course be removed by the {{0.7 1.0} @Scale {Courier Bold} @Font {clean}} target. @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s-sourcearchives} 3.3.|0.5fe{ Source packages as archives}}}} |0f }} //0.0fe @LP As it exists on the FTP site, a Debian source package consists of three related files. You must have the right versions of all three to be able to use them. @LP {|0.5f {Debian source control file "-" {{0.7 1.0} @Scale {Courier Bold} @Font {.dsc}}}} //1.0vx @RawIndentedDisplay { This file contains a series of fields, identified and separated just like the fields in the control file of a binary package. The fields are listed below; their syntax is described above, in `Control files and their fields', page @PageOf{ch-controlfields}. //1.0vx {@RawBulletList gap { 1.0vx } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Source}} } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Version}} } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Maintainer}} } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Binary}} } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Architecture}} } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {"Standards"--"Version"}} } @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {Files}} } @RawEndList}//0ve @LP The source package control file is generated by {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"source"}} when it builds the source archive, from other files in the source package, described above. When unpacking it is checked against the files and directories in the other parts of the source package, as described below. } //0fe //1.2fx {|0.5f {Original source archive "-" {{0.7 1.0} @Scale {Courier Bold} @Font {{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {package}}}}_{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"upstream-version"}}}}.orig.tar.gz}}}} //1.0vx @RawIndentedDisplay { This is a compressed (with {{0.7 1.0} @Scale {Courier Bold} @Font {gzip ""--"9"}}) {{0.7 1.0} @Scale {Courier Bold} @Font {tar}} file containing the source code from the upstream authors of the program. The tarfile unpacks into a directory {{0.7 1.0} @Scale {Courier Bold} @Font {{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {package}}}}""--""{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"upstream-version"}}}}.orig}}, and does not contain files anywhere other than in there or in its subdirectories. } //0fe //1.2fx {|0.5f {Debianisation diff "-" {{0.7 1.0} @Scale {Courier Bold} @Font {{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {package}}}}_{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"version-revision"}}}}.diff.gz}}}} //1.0vx @RawIndentedDisplay { This is a unified context diff ({{0.7 1.0} @Scale {Courier Bold} @Font {diff ""--"u"}}) giving the changes which are required to turn the original source into the Debian source. These changes may only include editing and creating plain files. The permissions of files, the targets of symbolic links and the characteristics of special files or pipes may not be changed and no files may be removed or renamed. @LP All the directories in the diff must exist, except the {{0.7 1.0} @Scale {Courier Bold} @Font {debian}} subdirectory of the top of the source tree, which will be created by {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"source"}} if necessary when unpacking. @LP The {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"source"}} program will automatically make the {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/rules"}} file executable (see below). } //0fe @LP If there is no original source code "-" for example, if the package is specially prepared for Debian or the Debian maintainer is the same as the upstream maintainer "-" the format is slightly different: then there is no diff, and the tarfile is named {{0.7 1.0} @Scale {Courier Bold} @Font {{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {package}}}}_{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {version}}}}.tar.gz}} and contains a directory {{0.7 1.0} @Scale {Courier Bold} @Font {{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {package}}}}""--""{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {version}}}}}}. @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s3.4} 3.4.|0.5fe{ Unpacking a Debian source package without {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"source"}}}}}} |0f }} //0.0fe @LP {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"source" ""--"x"}} is the recommended way to unpack a Debian source package. However, if it is not available it is possible to unpack a Debian source archive as follows: //1.0vx {@RawNumberedList gap { 1.0vx } @ListItem { Untar the tarfile, which will create a {{0.7 1.0} @Scale {Courier Bold} @Font {.orig}} directory. } @ListItem { Rename the {{0.7 1.0} @Scale {Courier Bold} @Font {.orig}} directory to {{0.7 1.0} @Scale {Courier Bold} @Font {{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {package}}}}""--""{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {version}}}}}}. } @ListItem { Create the subdirectory {{0.7 1.0} @Scale {Courier Bold} @Font {debian}} at the top of the source tree. } @ListItem { Apply the diff using {{0.7 1.0} @Scale {Courier Bold} @Font {patch ""--"p0"}}. } @ListItem { Untar the tarfile again if you want a copy of the original source code alongside the Debianised version. } @RawEndList}//0ve @LP It is not possible to generate a valid Debian source archive without using {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"source"}}. In particular, attempting to use {{0.7 1.0} @Scale {Courier Bold} @Font {diff}} directly to generate the {{0.7 1.0} @Scale {Courier Bold} @Font {.diff.gz}} file will not work. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s3.4.1} 3.4.1.|0.5fe{ Restrictions on objects in source packages}}}//0.2fe @LP The source package may not contain any device special files, sockets or setuid or setgid files.{@FootNote{ Setgid directories are allowed.}} @LP The source packaging tools manage the changes between the original and Debianised source using {{0.7 1.0} @Scale {Courier Bold} @Font {diff}} and {{0.7 1.0} @Scale {Courier Bold} @Font {patch}}. Turning the original source tree as included in the {{0.7 1.0} @Scale {Courier Bold} @Font {.orig.tar.gz}} into the debianised source must not involve any changes which cannot be handled by these tools. Problematic changes which cause {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"source"}} to halt with an error when building the source package are: //1.0vx {@RawBulletList gap { 1.0vx } @ListItem { Adding or removing symbolic links, sockets or pipes. } @ListItem { Changing the targets of symbolic links. } @ListItem { Creating directories, other than {{0.7 1.0} @Scale {Courier Bold} @Font {debian}}. } @ListItem { Changes to the contents of binary files. } @RawEndList}//0ve Changes which cause {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"source"}} to print a warning but continue anyway are: //1.0vx {@RawBulletList gap { 1.0vx } @ListItem { Removing files, directories or symlinks. {@FootNote{ Renaming a file is not treated specially "-" it is seen as the removal of the old file (which generates a warning, but is otherwise ignored), and the creation of the new one.}} } @RawEndList}//0ve Changes which are not represented, but which are not detected by {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"source"}}, are: //1.0vx {@RawBulletList gap { 1.0vx } @ListItem { Changing the permissions of files (other than {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/rules"}}) and directories. } @RawEndList}//0ve @LP The {{0.7 1.0} @Scale {Courier Bold} @Font {debian}} directory and {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/rules"}} are handled specially by {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"source"}} "-" before applying the changes it will create the {{0.7 1.0} @Scale {Courier Bold} @Font {debian}} directory, and afterwards it will make {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/rules"}} "world-exectuable." @LP @NP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.2 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +5p @Font { 1.2vx @Break { {@PageMark ch-controlfields} 4.|0.5fe{ Control files and their fields}}}} |0f }} //0.0fe @LP Many of the tools in the {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} suite manipulate data in a common format, known as control files. Binary and source packages have control data as do the {{0.7 1.0} @Scale {Courier Bold} @Font {.changes}} files which control the installation of uploaded files, and {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}}'s internal databases are in a similar format. @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s4.1} 4.1.|0.5fe{ Syntax of control files}}}} |0f }} //0.0fe @LP A file consists of one or more paragraphs of fields. The paragraphs are separated by blank lines. Some control files only allow one paragraph; others allow several, in which case each paragraph often refers to a different package. @LP Each paragraph is a series of fields and values; each field consists of a name, followed by a colon and the value. It ends at the end of the line. Horizontal whitespace (spaces and tabs) may occur before or after the value and is ignored there; it is conventional to put a single space after the colon. @LP Some fields' values may span several lines; in this case each continuation line {{Times Slope} @Font {must}} start with a space or tab. Any trailing spaces or tabs at the end of individual lines of a field value are ignored. @LP Except where otherwise stated only a single line of data is allowed and whitespace is not significant in a field body. Whitespace may never appear inside names (of packages, architectures, files or anything else), version numbers or in between the characters of "multi-character" version relationships. @LP Field names are not "case-sensitive," but it is usual to capitalise the fields using mixed case as shown below. @LP Blank lines, or lines consisting only of spaces and tabs, are not allowed within field values or between fields "-" that would mean a new paragraph. @LP It is important to note that there are several fields which are optional as far as {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} and the related tools are concerned, but which must appear in every Debian package, or whose omission may cause problems. When writing the control files for Debian packages you {{Times Slope} @Font {must}} read the Debian policy manual in conjuction with the details below and the list of fields for the particular file. @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s4.2} 4.2.|0.5fe{ List of fields }}}} |0f }} //0.0fe @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s-f-Package} 4.2.1.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {Package}}}}}//0.2fe @LP The name of the binary package. Package names consist of the alphanumerics and {{0.7 1.0} @Scale {Courier Bold} @Font {+}} {{0.7 1.0} @Scale {Courier Bold} @Font {""--""}} {{0.7 1.0} @Scale {Courier Bold} @Font {.}} (plus, minus and full stop).{@FootNote{ The characters {{0.7 1.0} @Scale {Courier Bold} @Font {"@"}} {{0.7 1.0} @Scale {Courier Bold} @Font {:}} {{0.7 1.0} @Scale {Courier Bold} @Font {=}} {{0.7 1.0} @Scale {Courier Bold} @Font {%}} {{0.7 1.0} @Scale {Courier Bold} @Font {_}} (at, colon, equals, percent and underscore) used to be legal and are still accepted when found in a package file, but may not be used in new packages}} @LP They must be at least two characters and must start with an alphanumeric. In current versions of dpkg they are sort of "case-sensitive"{@FootNote{ This is a bug.}}; use lowercase package names unless the package you're building (or referring to, in other fields) is already using uppercase. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s-f-Version} 4.2.2.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {Version}}}}}//0.2fe @LP This lists the source or binary package's version number "-" see `Version numbering', page @PageOf{ch-versions}. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s-f-Architecture} 4.2.3.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {Architecture}}}}}//0.2fe @LP This is the architecture string; it is a single word for the CPU architecture. @LP {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} will check the declared architecture of a binary package against its own "compiled-in" value before it installs it. @LP The special value {{0.7 1.0} @Scale {Courier Bold} @Font {all}} indicates that the package is "architecture-independent." @LP In the main {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/control"}} file in the source package, or in the source package control file {{0.7 1.0} @Scale {Courier Bold} @Font {.dsc}}, a list of architectures (separated by spaces) is also allowed, as is the special value {{0.7 1.0} @Scale {Courier Bold} @Font {any}}. A list indicates that the source will build an "architecture-dependent" package, and will only work correctly on the listed architectures. {{0.7 1.0} @Scale {Courier Bold} @Font {any}} indicates that though the source package isn't dependent on any particular architecture and should compile fine on any one, the binary package(s) produced are not "architecture-independent" but will instead be specific to whatever the current build architecture is. @LP In a {{0.7 1.0} @Scale {Courier Bold} @Font {.changes}} file the {{0.7 1.0} @Scale {Courier Bold} @Font {Architecture}} field lists the architecture(s) of the package(s) currently being uploaded. This will be a list; if the source for the package is being uploaded too the special entry {{0.7 1.0} @Scale {Courier Bold} @Font {source}} is also present. @LP The current build architecture can be determined using {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg ""--""--"print"--"architecture"}}.{@FootNote{ This actually invokes //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { gcc ""--""--"print"--"libgcc"--"file"--"name"}}} //0.2fe and parses and decomposes the output and looks the CPU type from the GCC configuration in a table in {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}}. This is so that it will work if you're "cross-compiling."}} This value is automatically used by {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"gencontrol"}} when building the control file for a binary package for which the source control information doesn't specify architecture {{0.7 1.0} @Scale {Courier Bold} @Font {all}}. @LP There is a separate option, {{0.7 1.0} @Scale {Courier Bold} @Font {""--""--"print"--"installation"--"architecture"}}, for finding out what architecture {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} is willing to install. This information is also in the output of {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg ""--""--"version"}}. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s-f-Maintainer} 4.2.4.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {Maintainer}}}}}//0.2fe @LP The package maintainer's name and email address. The name should come first, then the email address inside angle brackets {{0.7 1.0} @Scale {Courier Bold} @Font {<>}} (in RFC822 format). @LP If the maintainer's name contains a full stop then the whole field will not work directly as an email address due to a misfeature in the syntax specified in RFC822; a program using this field as an address must check for this and correct the problem if necessary (for example by putting the name in round brackets and moving it to the end, and bringing the email address forward). @LP In a {{0.7 1.0} @Scale {Courier Bold} @Font {.changes}} file or parsed changelog data this contains the name and email address of the person responsible for the particular version in question "-" this may not be the package's usual maintainer. @LP This field is usually optional in as far as the {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} are concerned, but its absence when building packages usually generates a warning. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s-f-Source} 4.2.5.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {Source}}}}}//0.2fe @LP This field identifies the source package name. @LP In a main source control information or a {{0.7 1.0} @Scale {Courier Bold} @Font {.changes}} or {{0.7 1.0} @Scale {Courier Bold} @Font {.dsc}} file or parsed changelog data this may contain only the name of the source package. @LP In the control file of a binary package (or in a {{0.7 1.0} @Scale {Courier Bold} @Font {Packages}} file) it may be followed by a version number in parentheses.{@FootNote{ It is usual to leave a space after the package name if a version number is specified.}} This version number may be omitted (and is, by {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"gencontrol"}}) if it has the same value as the {{0.7 1.0} @Scale {Courier Bold} @Font {Version}} field of the binary package in question. The field itself may be omitted from a binary package control file when the source package has the same name and version as the binary package. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s4.2.6} 4.2.6.|0.5fe{ Package interrelationship fields: {{0.7 1.0} @Scale {Courier Bold} @Font {Depends}}, {{0.7 1.0} @Scale {Courier Bold} @Font {"Pre"--"Depends"}}, {{0.7 1.0} @Scale {Courier Bold} @Font {Recommends}} {{0.7 1.0} @Scale {Courier Bold} @Font {Suggests}}, {{0.7 1.0} @Scale {Courier Bold} @Font {Conflicts}}, {{0.7 1.0} @Scale {Courier Bold} @Font {Provides}}, {{0.7 1.0} @Scale {Courier Bold} @Font {Replaces}}}}}//0.2fe @LP These fields describe the package's relationships with other packages. Their syntax and semantics are described in `Declaring relationships between packages', page @PageOf{ch-relationships}. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s-f-Description} 4.2.7.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {Description}}}}}//0.2fe @LP In a binary package {{0.7 1.0} @Scale {Courier Bold} @Font {Packages}} file or main source control file this field contains a description of the binary package, in a special format. See `Descriptions of packages "-" the {{0.7 1.0} @Scale {Courier Bold} @Font {Description}} field', page @PageOf{ch-descriptions} for details. @LP In a {{0.7 1.0} @Scale {Courier Bold} @Font {.changes}} file it contains a summary of the descriptions for the packages being uploaded. The part of the field before the first newline is empty; thereafter each line has the name of a binary package and the summary description line from that binary package. Each line is indented by one space. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s-f-Essential} 4.2.8.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {Essential}}}}}//0.2fe @LP This is a boolean field which may occur only in the control file of a binary package (or in the {{0.7 1.0} @Scale {Courier Bold} @Font {Packages}} file) or in a "per-package" fields paragraph of a main source control data file. @LP If set to {{0.7 1.0} @Scale {Courier Bold} @Font {yes}} then {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} and {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}} will refuse to remove the package (though it can be upgraded "and/or" replaced). The other possible value is {{0.7 1.0} @Scale {Courier Bold} @Font {no}}, which is the same as not having the field at all. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s-f-classification} 4.2.9.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {Section}} and {{0.7 1.0} @Scale {Courier Bold} @Font {Priority}}}}}//0.2fe @LP These two fields classify the package. The {{0.7 1.0} @Scale {Courier Bold} @Font {Priority}} represents how important that it is that the user have it installed; the {{0.7 1.0} @Scale {Courier Bold} @Font {Section}} represents an application area into which the package has been classified. @LP When they appear in the {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/control"}} file these fields give values for the section and priority subfields of the {{0.7 1.0} @Scale {Courier Bold} @Font {Files}} field of the {{0.7 1.0} @Scale {Courier Bold} @Font {.changes}} file, and give defaults for the section and priority of the binary packages. @LP The section and priority are represented, though not as separate fields, in the information for each file in the {{0.7 1.0} @Scale {Courier Bold} @Font {Files}} field of a {{0.7 1.0} @Scale {Courier Bold} @Font {.changes}} file. The section value in a {{0.7 1.0} @Scale {Courier Bold} @Font {.changes}} file is used to decide where to install a package in the FTP archive. @LP These fields are not used by by {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} proper, but by {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}} when it sorts packages and selects defaults. See the Debian policy manual for the priorities in use and the criteria for selecting the priority for a Debian package, and look at the Debian FTP archive for a list of currently "in-use" priorities. @LP These fields may appear in binary package control files, in which case they provide a default value in case the {{0.7 1.0} @Scale {Courier Bold} @Font {Packages}} files are missing the information. {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} and {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}} will only use the value from a {{0.7 1.0} @Scale {Courier Bold} @Font {.deb}} file if they have no other information; a value listed in a {{0.7 1.0} @Scale {Courier Bold} @Font {Packages}} file will always take precedence. By default {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"genchanges"}} does not include the section and priority in the control file of a binary package "-" use the {{0.7 1.0} @Scale {Courier Bold} @Font {""--"isp"}}, {{0.7 1.0} @Scale {Courier Bold} @Font {""--"is"}} or {{0.7 1.0} @Scale {Courier Bold} @Font {""--"ip"}} options to achieve this effect. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s-f-Binary} 4.2.10.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {Binary}}}}}//0.2fe @LP This field is a list of binary packages. @LP When it appears in the {{0.7 1.0} @Scale {Courier Bold} @Font {.dsc}} file it is the list of binary packages which a source package can produce. It does not necessarily produce all of these binary packages for every architecture. The source control file doesn't contain details of which architectures are appropriate for which of the binary packages. @LP When it appears in a {{0.7 1.0} @Scale {Courier Bold} @Font {.changes}} file it lists the names of the binary packages actually being uploaded. @LP The syntax is a list of binary packages separated by commas.{@FootNote{ A space after each comma is conventional.}} Currently the packages must be separated using only spaces in the {{0.7 1.0} @Scale {Courier Bold} @Font {.changes}} file. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s-f-Installed-Size} 4.2.11.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {"Installed"--"Size"}}}}}//0.2fe @LP This field appears in the control files of binary packages, and in the {{0.7 1.0} @Scale {Courier Bold} @Font {Packages}} files. It gives the total amount of disk space required to install the named package. @LP The disk space is represented in kilobytes as a simple decimal number. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s-f-Files} 4.2.12.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {Files}}}}}//0.2fe @LP This field contains a list of files with information about each one. The exact information and syntax varies with the context. In all cases the the part of the field contents on the same line as the field name is empty. The remainder of the field is one line per file, each line being indented by one space and containing a number of "sub-fields" separated by spaces. @LP In the {{0.7 1.0} @Scale {Courier Bold} @Font {.dsc}} (Debian source control) file each line contains the MD5 checksum, size and filename of the tarfile and (if applicable) diff file which make up the remainder of the source package.{@FootNote{ That is, the parts which are not the {{0.7 1.0} @Scale {Courier Bold} @Font {.dsc}}.}} The exact forms of the filenames are described in `Source packages as archives', page @PageOf{s-sourcearchives}. @LP In the {{0.7 1.0} @Scale {Courier Bold} @Font {.changes}} file this contains one line per file being uploaded. Each line contains the MD5 checksum, size, section and priority and the filename. The section and priority are the values of the corresponding fields in the main source control file "-" see `{{0.7 1.0} @Scale {Courier Bold} @Font {Section}} and {{0.7 1.0} @Scale {Courier Bold} @Font {Priority}}', page @PageOf{s-f-classification}. If no section or priority is specified then {{0.7 1.0} @Scale {Courier Bold} @Font {""--""}} should be used, though section and priority values must be specified for new packages to be installed properly. @LP The special value {{0.7 1.0} @Scale {Courier Bold} @Font {byhand}} for the section in a {{0.7 1.0} @Scale {Courier Bold} @Font {.changes}} file indicates that the file in question is not an ordinary package file and must by installed by hand by the distribution maintainers. If the section is {{0.7 1.0} @Scale {Courier Bold} @Font {byhand}} the priority should be {{0.7 1.0} @Scale {Courier Bold} @Font {""--""}}. @LP If a new Debian revision of a package is being shipped and no new original source archive is being distributed the {{0.7 1.0} @Scale {Courier Bold} @Font {.dsc}} must still contain the {{0.7 1.0} @Scale {Courier Bold} @Font {Files}} field entry for the original source archive {{0.7 1.0} @Scale {Courier Bold} @Font {{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {package}}}}""--""{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"upstream-version"}}}}.orig.tar.gz}}, but the {{0.7 1.0} @Scale {Courier Bold} @Font {.changes}} file should leave it out. In this case the original source archive on the distribution site must match exactly, "byte-for-byte," the original source archive which was used to generate the {{0.7 1.0} @Scale {Courier Bold} @Font {.dsc}} file and diff which are being uploaded. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s-f-Standards-Version} 4.2.13.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {"Standards"--"Version"}}}}}//0.2fe @LP The most recent version of the standards (the {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} programmers' and policy manuals and associated texts) with which the package complies. This is updated manually when editing the source package to conform to newer standards; it can sometimes be used to tell when a package needs attention. @LP Its format is the same as that of a version number except that no epoch or Debian revision is allowed "-" see `Version numbering', page @PageOf{ch-versions}. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s-f-Distribution} 4.2.14.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {Distribution}}}}}//0.2fe @LP In a {{0.7 1.0} @Scale {Courier Bold} @Font {.changes}} file or parsed changelog output this contains the "(space-separated)" name(s) of the distribution(s) where this version of the package should be or was installed. Distribution names follow the rules for package names. (See `{{0.7 1.0} @Scale {Courier Bold} @Font {Package}}', page @PageOf{s-f-Package}). @LP Current distribution values are {{0.7 1.0} @Scale {Courier Bold} @Font {stable}}, {{0.7 1.0} @Scale {Courier Bold} @Font {unstable}}, {{0.7 1.0} @Scale {Courier Bold} @Font {contrib}}, {{0.7 1.0} @Scale {Courier Bold} @Font {"non"--"free"}} and {{0.7 1.0} @Scale {Courier Bold} @Font {experimental}}. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s-f-Urgency} 4.2.15.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {Urgency}}}}}//0.2fe @LP This is a description of how important it is to upgrade to this version from previous ones. It consists of a single keyword usually taking one of the values {{0.7 1.0} @Scale {Courier Bold} @Font {LOW}}, {{0.7 1.0} @Scale {Courier Bold} @Font {MEDIUM}} or {{0.7 1.0} @Scale {Courier Bold} @Font {HIGH}}) followed by an optional commentary (separated by a space) which is usually in parentheses. For example: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { Urgency: LOW (HIGH for diversions users)}}} //0.2fe @LP This field appears in the {{0.7 1.0} @Scale {Courier Bold} @Font {.changes}} file and in parsed changelogs; its value appears as the value of the {{0.7 1.0} @Scale {Courier Bold} @Font {urgency}} attribute in a {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}}"-style" changelog (see `{{0.7 1.0} @Scale {Courier Bold} @Font {"debian/changelog"}}', page @PageOf{s-dpkgchangelog}). @LP Urgency keywords are not "case-sensitive." @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s-f-Date} 4.2.16.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {Date}}}}}//0.2fe @LP In {{0.7 1.0} @Scale {Courier Bold} @Font {.changes}} files and parsed changelogs, this gives the date the package was built or last edited. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s-f-Format} 4.2.17.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {Format}}}}}//0.2fe @LP This field occurs in {{0.7 1.0} @Scale {Courier Bold} @Font {.changes}} files, and specifies a format revision for the file. The format described here is version {{0.7 1.0} @Scale {Courier Bold} @Font {1.5}}. The syntax of the format value is the same as that of a package version number except that no epoch or Debian revision is allowed "-" see `Version numbering', page @PageOf{ch-versions}. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s-f-Changes} 4.2.18.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {Changes}}}}}//0.2fe @LP In a {{0.7 1.0} @Scale {Courier Bold} @Font {.changes}} file or parsed changelog this field contains the "human-readable" changes data, describing the differences between the last version and the current one. @LP There should be nothing in this field before the first newline; all the subsequent lines must be indented by at least one space; blank lines must be represented by a line consiting only of a space and a full stop. @LP Each version's change information should be preceded by a `title' line giving at least the version, distribution(s) and urgency, in a "human-readable" way. @LP If data from several versions is being returned the entry for the most recent version should be returned first, and entries should be separated by the representation of a blank line (the `title' line may also be followed by the representation of blank line). @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s-f-Filename} 4.2.19.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {Filename}} and {{0.7 1.0} @Scale {Courier Bold} @Font {"MSDOS"--"Filename"}}}}}//0.2fe @LP These fields in {{0.7 1.0} @Scale {Courier Bold} @Font {Packages}} files give the filename(s) of (the parts of) a package in the distribution directories, relative to the root of the Debian hierarchy. If the package has been split into several parts the parts are all listed in order, separated by spaces. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s-f-Size} 4.2.20.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {Size}} and {{0.7 1.0} @Scale {Courier Bold} @Font {MD5sum}}}}}//0.2fe @LP These fields in {{0.7 1.0} @Scale {Courier Bold} @Font {Packages}} files give the size (in bytes, expressed in decimal) and MD5 checksum of the file(s) which make(s) up a binary package in the distribution. If the package is split into several parts the values for the parts are listed in order, separated by spaces. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s-f-Status} 4.2.21.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {Status}}}}}//0.2fe @LP This field in {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}}'s status file records whether the user wants a package installed, removed or left alone, whether it is broken (requiring reinstallation) or not and what its current state on the system is. Each of these pieces of information is a single word. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s-f-Config-Version} 4.2.22.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {"Config"--"Version"}}}}}//0.2fe @LP If a package is not installed or not configured, this field in {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}}'s status file records the last version of the package which was successfully configured. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s-f-Conffiles} 4.2.23.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {Conffiles}}}}}//0.2fe @LP This field in {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}}'s status file contains information about the "automatically-managed" configuration files held by a package. This field should {{Times Slope} @Font {not}} appear anywhere in a package! @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s4.2.24} 4.2.24.|0.5fe{ Obsolete fields}}}//0.2fe @LP These are still recognised by {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} but should not appear anywhere any more. //1.0vx {|0.5f {{{0.7 1.0} @Scale {Courier Bold} @Font {Revision}}}} //1.0vx {|0.5f {{{0.7 1.0} @Scale {Courier Bold} @Font {"Package"--"Revision"}}}} //1.0vx {|0.5f {{{0.7 1.0} @Scale {Courier Bold} @Font {Package_Revision}}}} //1.0vx {|2f { The Debian revision part of the package version was at one point in a separate control file field. This field went through several names. }} //1.0vx {|0.5f {{{0.7 1.0} @Scale {Courier Bold} @Font {Recommended}}}} //1.0vx {|2f { Old name for {{0.7 1.0} @Scale {Courier Bold} @Font {Recommends}} }} //1.0vx {|0.5f {{{0.7 1.0} @Scale {Courier Bold} @Font {Optional}}}} //1.0vx {|2f { Old name for {{0.7 1.0} @Scale {Courier Bold} @Font {Suggests}}. }} //1.0vx {|0.5f {{{0.7 1.0} @Scale {Courier Bold} @Font {Class}}}} //1.0vx {|2f { Old name for {{0.7 1.0} @Scale {Courier Bold} @Font {Priority}}. }} //0.2fe @LP @NP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.2 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +5p @Font { 1.2vx @Break { {@PageMark ch-versions} 5.|0.5fe{ Version numbering}}}} |0f }} //0.0fe @LP Every package has a version number, in its {{0.7 1.0} @Scale {Courier Bold} @Font {Version}} control file field. @LP {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} imposes an ordering on version numbers, so that it can tell whether packages are being "up-" or downgraded and so that {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}} can tell whether a package it finds available is newer than the one installed on the system. The version number format has the most significant parts (as far as comparison is concerned) at the beginning. @LP The version number format is: [{{Times Slope} @Font {epoch}}{{0.7 1.0} @Scale {Courier Bold} @Font {:}}]{{Times Slope} @Font {"upstream-version"}}[{{0.7 1.0} @Scale {Courier Bold} @Font {""--""}}{{Times Slope} @Font {"debian-revision"}}]. @LP The three components here are: @LP {|0.5f {{{Times Slope} @Font {epoch}}}} //1.0vx @RawIndentedDisplay { This is a single unsigned integer, which should usually be small. It may be omitted, in which case zero is assumed. If it is omitted then the {{Times Slope} @Font {"upstream-version"}} may not contain any colons. @LP It is provided to allow mistakes in the version numbers of older versions of a package, and also a package's previous version numbering schemes, to be left behind. @LP {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} will not usually display the epoch unless it is essential "(non-zero," or if the {{Times Slope} @Font {"upstream-version"}} contains a colon); {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}} does not display epochs at all in the main part of the package selection display. } //0fe //1.2fx {|0.5f {{{Times Slope} @Font {"upstream-version"}}}} //1.0vx @RawIndentedDisplay { This is the main part of the version. It is usually version number of the original (`upstream') package of which the {{0.7 1.0} @Scale {Courier Bold} @Font {.deb}} file has been made, if this is applicable. Usually this will be in the same format as that specified by the upstream author(s); however, it may need to be reformatted to fit into {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}}'s format and comparison scheme. @LP The comparison behaviour of {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} with respect to the {{Times Slope} @Font {"upstream-version"}} is described below. The {{Times Slope} @Font {"upstream-version"}} portion of the version number is mandatory. @LP The {{Times Slope} @Font {"upstream-version"}} may contain only alphanumerics and the characters {{0.7 1.0} @Scale {Courier Bold} @Font {+}} {{0.7 1.0} @Scale {Courier Bold} @Font {.}} {{0.7 1.0} @Scale {Courier Bold} @Font {""--""}} {{0.7 1.0} @Scale {Courier Bold} @Font {:}} (full stop, plus, hyphen, colon) and should start with a digit. If there is no {{Times Slope} @Font {"debian-revision"}} then hyphens are not allowed; if there is no {{Times Slope} @Font {epoch}} then colons are not allowed. } //0fe //1.2fx {|0.5f {{{Times Slope} @Font {"debian-revision"}}}} //1.0vx @RawIndentedDisplay { This part of the version represents the version of the modifications that were made to the package to make it a Debian binary package. It is in the same format as the {{Times Slope} @Font {"upstream-version"}} and {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} compares it in the same way. @LP It is optional; if it isn't present then the {{Times Slope} @Font {"upstream-version"}} may not contain a hyphen. This format represents the case where a piece of software was written specifically to be turned into a Debian binary package, and so there is only one `debianization' of it and therefore no revision indication is required. @LP It is conventional to restart the {{Times Slope} @Font {"debian-revision"}} at {{0.7 1.0} @Scale {Courier Bold} @Font {1}} each time the {{Times Slope} @Font {"upstream-version"}} is increased. @LP {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} will break the {{Times Slope} @Font {"upstream-version"}} and {{Times Slope} @Font {"debian-revision"}} apart at the last hyphen in the string. The absence of a {{Times Slope} @Font {"debian-revision"}} compares earlier than the presence of one (but note that the {{Times Slope} @Font {"debian-revision"}} is the least significant part of the version number). @LP The {{Times Slope} @Font {"debian-revision"}} may contain only alphanumerics and the characters {{0.7 1.0} @Scale {Courier Bold} @Font {+}} and {{0.7 1.0} @Scale {Courier Bold} @Font {.}} (plus and full stop). } //0fe @LP The {{Times Slope} @Font {"upstream-version"}} and {{Times Slope} @Font {"debian-revision"}} parts are compared by {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} using the same algorithm: @LP The strings are compared from left to right. @LP First the initial part of each string consisting entirely of "non-digit" characters is determined. These two parts (one of which may be empty) are compared lexically. If a difference is found it is returned. The lexical comparison is a comparison of ASCII values modified so that all the letters sort earlier than all the "non-letters." @LP Then the initial part of the remainder of each string which consists entirely of digit characters is determined. The numerical values of these two parts are compared, and any difference found is returned as the result of the comparison. For these purposes an empty string (which can only occur at the end of one or both version strings being compared) counts as zero. @LP These two steps are repeated (chopping initial "non-digit" strings and initial digit strings off from the start) until a difference is found or both strings are exhausted. @LP Note that the purpose of epochs is to allow us to leave behind mistakes in version numbering, and to cope with situations where the version numbering changes. It is {{Times Slope} @Font {not}} there to cope with version numbers containing strings of letters which {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} cannot interpret (such as {{0.7 1.0} @Scale {Courier Bold} @Font {ALPHA}} or {{0.7 1.0} @Scale {Courier Bold} @Font {"pre"--""}}), or with silly orderings (the author of this manual has heard of a package whose versions went {{0.7 1.0} @Scale {Courier Bold} @Font {1.1}}, {{0.7 1.0} @Scale {Courier Bold} @Font {1.2}}, {{0.7 1.0} @Scale {Courier Bold} @Font {1.3}}, {{0.7 1.0} @Scale {Courier Bold} @Font {1}}, {{0.7 1.0} @Scale {Courier Bold} @Font {2.1}}, {{0.7 1.0} @Scale {Courier Bold} @Font {2.2}}, {{0.7 1.0} @Scale {Courier Bold} @Font {2}} and so forth). @LP If an upstream package has problematic version numbers they should be converted to a sane form for use in the {{0.7 1.0} @Scale {Courier Bold} @Font {Version}} field. @LP @NP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.2 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +5p @Font { 1.2vx @Break { {@PageMark ch-maintainerscripts} 6.|0.5fe{ Package maintainer scripts and installation procedure}}}} |0f }} //0.0fe @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s6.1} 6.1.|0.5fe{ Introduction to package maintainer scripts}}}} |0f }} //0.0fe @LP It is possible supply scripts as part of a package which {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} will run for you when your package is installed, upgraded or removed. @LP These scripts should be the files {{0.7 1.0} @Scale {Courier Bold} @Font {preinst}}, {{0.7 1.0} @Scale {Courier Bold} @Font {postinst}}, {{0.7 1.0} @Scale {Courier Bold} @Font {prerm}} and {{0.7 1.0} @Scale {Courier Bold} @Font {postrm}} in the control area of the package. They must be proper exectuable files; if they are scripts (which is recommended) they must start with the usual {{0.7 1.0} @Scale {Courier Bold} @Font {"#!"}} convention. They should be readable and executable to anyone, and not "world-writeable." @LP {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} looks at the exit status from these scripts. It is important that they exit with a "non-zero" status if there is an error, so that {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} can stop its processing. For shell scripts this means that you {{Times Slope} @Font {almost always}} need to use {{0.7 1.0} @Scale {Courier Bold} @Font {set ""--"e"}} (this is usually true when writing shell scripts, in fact). It is also important, of course, that they don't exit with a "non-zero" status if everything went well. @LP It is necessary for the error recovery procedures that the scripts be idempotent: ie, invoking the same script several times in the same situation should do no harm. If the first call failed, or aborted half way through for some reason, the second call should merely do the things that were left undone the first time, if any, and exit with a success status. @LP When a package is upgraded a combination of the scripts from the old and new packages is called in amongst the other steps of the upgrade procedure. If your scripts are going to be at all complicated you need to be aware of this, and may need to check the arguments to your scripts. @LP Broadly speaking the {{0.7 1.0} @Scale {Courier Bold} @Font {preinst}} is called before (a particular version of) a package is installed, and the {{0.7 1.0} @Scale {Courier Bold} @Font {postinst}} afterwards; the {{0.7 1.0} @Scale {Courier Bold} @Font {prerm}} before (a version of) a package is removed and the {{0.7 1.0} @Scale {Courier Bold} @Font {postrm}} afterwards. @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s-mscriptsinstact} 6.2.|0.5fe{ Summary of ways maintainer scripts are called}}}} |0f }} //0.0fe @LP {@RawBulletList gap { 1.0vx } @ListItem { {{Times Slope} @Font {"new-preinst"}} {{0.7 1.0} @Scale {Courier Bold} @Font {install}} } @ListItem { {{Times Slope} @Font {"new-preinst"}} {{0.7 1.0} @Scale {Courier Bold} @Font {install}} {{Times Slope} @Font {"old-version"}} } @ListItem { {{Times Slope} @Font {"new-preinst"}} {{0.7 1.0} @Scale {Courier Bold} @Font {upgrade}} {{Times Slope} @Font {"old-version"}} } @ListItem { {{Times Slope} @Font {"old-preinst"}} {{0.7 1.0} @Scale {Courier Bold} @Font {"abort"--"upgrade"}} {{Times Slope} @Font {"new-version"}} } @RawEndList}//0ve @LP {@RawBulletList gap { 1.0vx } @ListItem { {{Times Slope} @Font {postinst}} {{0.7 1.0} @Scale {Courier Bold} @Font {configure}} {{Times Slope} @Font {"most-recently-configured-version"}} } @ListItem { {{Times Slope} @Font {"old-postinst"}} {{0.7 1.0} @Scale {Courier Bold} @Font {"abort"--"upgrade"}} {{Times Slope} @Font {new version}} } @ListItem { {{Times Slope} @Font {"conflictor's-postinst"}} {{0.7 1.0} @Scale {Courier Bold} @Font {"abort"--"remove"}} {{0.7 1.0} @Scale {Courier Bold} @Font {"in"--"favour"}} {{Times Slope} @Font {package}} {{Times Slope} @Font {"new-version"}} } @ListItem { {{Times Slope} @Font {"deconfigured's-postinst"}} {{0.7 1.0} @Scale {Courier Bold} @Font {"abort"--"deconfigure"}} {{0.7 1.0} @Scale {Courier Bold} @Font {"in"--"favour"}} {{Times Slope} @Font {"failed-install-package"}} {{Times Slope} @Font {version}} {{0.7 1.0} @Scale {Courier Bold} @Font {removing}} {{Times Slope} @Font {"conflicting-package"}} {{Times Slope} @Font {version}} } @RawEndList}//0ve @LP {@RawBulletList gap { 1.0vx } @ListItem { {{Times Slope} @Font {prerm}} {{0.7 1.0} @Scale {Courier Bold} @Font {remove}} } @ListItem { {{Times Slope} @Font {"old-prerm"}} {{0.7 1.0} @Scale {Courier Bold} @Font {upgrade}} {{Times Slope} @Font {"new-version"}} } @ListItem { {{Times Slope} @Font {"new-prerm"}} {{0.7 1.0} @Scale {Courier Bold} @Font {"failed"--"upgrade"}} {{Times Slope} @Font {"old-version"}} } @ListItem { {{Times Slope} @Font {"conflictor's-prerm"}} {{0.7 1.0} @Scale {Courier Bold} @Font {remove}} {{0.7 1.0} @Scale {Courier Bold} @Font {"in"--"favour"}} {{Times Slope} @Font {package}} {{Times Slope} @Font {"new-version"}} } @ListItem { {{Times Slope} @Font {"deconfigured's-prerm"}} {{0.7 1.0} @Scale {Courier Bold} @Font {deconfigure}} {{0.7 1.0} @Scale {Courier Bold} @Font {"in"--"favour"}} {{Times Slope} @Font {"package-being-installed"}} {{Times Slope} @Font {version}} {{0.7 1.0} @Scale {Courier Bold} @Font {removing}} {{Times Slope} @Font {"conflicting-package"}} {{Times Slope} @Font {version}} } @RawEndList}//0ve @LP {@RawBulletList gap { 1.0vx } @ListItem { {{Times Slope} @Font {postrm}} {{0.7 1.0} @Scale {Courier Bold} @Font {remove}} } @ListItem { {{Times Slope} @Font {postrm}} {{0.7 1.0} @Scale {Courier Bold} @Font {purge}} } @ListItem { {{Times Slope} @Font {"old-postrm"}} {{0.7 1.0} @Scale {Courier Bold} @Font {upgrade}} {{Times Slope} @Font {"new-version"}} } @ListItem { {{Times Slope} @Font {"new-postrm"}} {{0.7 1.0} @Scale {Courier Bold} @Font {"failed"--"upgrade"}} {{Times Slope} @Font {"old-version"}} } @ListItem { {{Times Slope} @Font {"new-postrm"}} {{0.7 1.0} @Scale {Courier Bold} @Font {"abort"--"install"}} } @ListItem { {{Times Slope} @Font {"new-postrm"}} {{0.7 1.0} @Scale {Courier Bold} @Font {"abort"--"install"}} {{Times Slope} @Font {"old-version"}} } @ListItem { {{Times Slope} @Font {"new-postrm"}} {{0.7 1.0} @Scale {Courier Bold} @Font {"abort"--"upgrade"}} {{Times Slope} @Font {"old-version"}} } @ListItem { {{Times Slope} @Font {"disappearer's-postrm"}} {{0.7 1.0} @Scale {Courier Bold} @Font {disappear}} {{Times Slope} @Font {overwriter}} {{Times Slope} @Font {"new-version"}} } @RawEndList}//0ve @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s6.3} 6.3.|0.5fe{ Details of unpack phase of installation or upgrade}}}} |0f }} //0.0fe @LP The procedure on "installation/upgrade/overwrite/disappear" (ie, when running {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg ""--""--"unpack"}}, or the unpack stage of {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg ""--""--"install"}}) is as follows. In each case if an error occurs the actions in are general run backwards "-" this means that the maintainer scripts are run with different arguments in reverse order. These are the `error unwind' calls listed below. @LP {@RawNumberedList @ListItem { {@RawRomanList @ListItem { If a version the package is already installed, call //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"old"--"prerm"}}}} upgrade {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"new"--"version"}}}}}}} //0.2fe } @ListItem { If this gives an error (ie, a "non-zero" exit status), dpkg will attempt instead: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"new"--"prerm"}}}} "failed"--"upgrade" {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"old"--"version"}}}}}}} //0.2fe Error unwind, for both the above cases: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"old"--"postinst"}}}} "abort"--"upgrade" {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"new"--"version"}}}}}}} //0.2fe } @RawEndList}//0ve } @ListItem { If a `conflicting' package is being removed at the same time: @LP {@RawRomanList @ListItem { If any packages depended on that conflicting package and {{0.7 1.0} @Scale {Courier Bold} @Font {""--""--"auto"--"deconfigure"}} is specified, call, for each such package: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"deconfigured's"--"prerm"}}}} deconfigure "\\" "in"--"favour" {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"package"--"being"--"installed"}}}} {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {version}}}} "\\" removing {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"conflicting"--"package"}}}} {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {version}}}}}}} //0.2fe Error unwind: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"deconfigured's"--"postinst"}}}} "abort"--"deconfigure" "\\" "in"--"favour" {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"package"--"being"--"installed"--"but"--"failed"}}}} {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {version}}}} "\\" removing {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"conflicting"--"package"}}}} {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {version}}}}}}} //0.2fe The deconfigured packages are marked as requiring configuration, so that if {{0.7 1.0} @Scale {Courier Bold} @Font {""--""--"install"}} is used they will be configured again if possible. } @ListItem { To prepare for removal of the conflicting package, call: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"conflictor's"--"prerm"}}}} remove "in"--"favour" {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {package}}}} {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"new"--"version"}}}}}}} //0.2fe Error unwind: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"conflictor's"--"postinst"}}}} "abort"--"remove" "\\" "in"--"favour" {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {package}}}} {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"new"--"version"}}}}}}} //0.2fe } @RawEndList}//0ve } @ListItem { {@RawRomanList @ListItem { If the package is being upgraded, call: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"new"--"preinst"}}}} upgrade {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"old"--"version"}}}}}}} //0.2fe } @ListItem { Otherwise, if the package had some configuration files from a previous version installed (ie, it is in the `configuration files only' state): //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"new"--"preinst"}}}} install {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"old"--"version"}}}}}}} //0.2fe } @ListItem { Otherwise (ie, the package was completely purged): //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"new"--"preinst"}}}} install}}} //0.2fe Error unwind versions, respectively: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"new"--"postrm"}}}} "abort"--"upgrade" {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"old"--"version"}}}} {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"new"--"postrm"}}}} "abort"--"install" {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"old"--"version"}}}} {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"new"--"postrm"}}}} "abort"--"install"}}} //0.2fe } @RawEndList}//0ve } @ListItem { The new package's files are unpacked, overwriting any that may be on the system already, for example any from the old version of the same package or from another package (backups of the old files are left around, and if anything goes wrong dpkg will attempt to put them back as part of the error unwind). @LP It is an error for a package to contains files which are on the system in another package, unless {{0.7 1.0} @Scale {Courier Bold} @Font {Replaces}} is used (see `{{0.7 1.0} @Scale {Courier Bold} @Font {Replaces}} "-" overwriting files and replacing packages', page @PageOf{s-replaces}). Currently the {{0.7 1.0} @Scale {Courier Bold} @Font {""--""--"force"--"overwrite"}} flag is enabled, downgrading it to a warning, but this may not always be the case. @LP Packages which overwrite each other's files produce behaviour which though deterministic is hard for the system administrator to understand. It can easily lead to `missing' programs if, for example, a package is installed which overwrites a file from another package, and is then removed again.{@FootNote{ Part of the problem is due to what is arguably a bug in {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}}.}} } @ListItem { {@RawRomanList @ListItem { If the package is being upgraded, call //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"old"--"postrm"}}}} upgrade {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"new"--"version"}}}}}}} //0.2fe } @ListItem { If this fails, {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} will attempt: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"new"--"postrm"}}}} "failed"--"upgrade" {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"old"--"version"}}}}}}} //0.2fe Error unwind, for both cases: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"old"--"preinst"}}}} "abort"--"upgrade" {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"new"--"version"}}}}}}} //0.2fe } @RawEndList}//0ve @LP This is the point of no return "-" if {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} gets this far, it won't back off past this point if an error occurs. This will leave the package in a fairly bad state, which will require a successful reinstallation to clear up, but it's when {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} starts doing things that are irreversible. } @ListItem { Any files which were in the old version of the package but not in the new are removed. } @ListItem { The new file list replaces the old. } @ListItem { The new maintainer scripts replace the old. } @ListItem { Any packages all of whose files have been overwritten during the installation, and which aren't required for dependencies, are considered to have been removed. For each such package, @LP {@RawRomanList @ListItem { {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} calls: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"disappearer's"--"postrm"}}}} disappear "\\" {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {overwriter}}}} {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"overwriter"--"version"}}}}}}} //0.2fe } @ListItem { The package's maintainer scripts are removed. } @ListItem { It is noted in the status database as being in a sane state, namely not installed (any conffiles it may have are ignored, rather than being removed by {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}}). Note that disappearing packages do not have their prerm called, because {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} doesn't know in advance that the package is going to vanish. } @RawEndList}//0ve } @ListItem { Any files in the package we're unpacking that are also listed in the file lists of other packages are removed from those lists. (This will lobotomise the file list of the `conflicting' package if there is one.) } @ListItem { The backup files made during installation, above, are deleted. } @ListItem { The new package's status is now sane, and recorded as `unpacked'. Here is another point of no return "-" if the conflicting package's removal fails we do not unwind the rest of the installation; the conflicting package is left in a "half-removed" limbo. } @ListItem { If there was a conflicting package we go and do the removal actions (described below), starting with the removal of the conflicting package's files (any that are also in the package being installed have already been removed from the conflicting package's file list, and so do not get removed now). } @RawEndList}//0ve @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s6.4} 6.4.|0.5fe{ Details of configuration}}}} |0f }} //0.0fe @LP When we configure a package (this happens with {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg ""--""--"install"}}, or with {{0.7 1.0} @Scale {Courier Bold} @Font {""--""--"configure"}}), we first update the conffiles and then call: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {postinst}}}} configure {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"most"--"recently"--"configured"--"version"}}}}}}} //0.2fe @LP No attempt is made to unwind after errors during configuration. @LP If there is no most recently configured version {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} will pass a null argument; older versions of dpkg may pass {{0.7 1.0} @Scale {Courier Bold} @Font {}} (including the angle brackets) in this case. Even older ones do not pass a second argument at all, under any circumstances. @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s6.5} 6.5.|0.5fe{ Details of removal "and/or" configuration purging}}}} |0f }} //0.0fe @LP {@RawNumberedList @ListItem { {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {prerm}}}} remove}}} //0.2fe } @ListItem { The package's files are removed (except conffiles). } @ListItem { {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {postrm}}}} remove}}} //0.2fe } @ListItem { All the maintainer scripts except the postrm are removed. @LP If we aren't purging the package we stop here. Note that packages which have no postrm and no conffiles are automatically purged when removed, as there is no difference except for the {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} status. } @ListItem { The conffiles and any backup files ({{0.7 1.0} @Scale {Courier Bold} @Font {~}}"-files," {{0.7 1.0} @Scale {Courier Bold} @Font {"#*#"}} files, {{0.7 1.0} @Scale {Courier Bold} @Font {%}}"-files," {{0.7 1.0} @Scale {Courier Bold} @Font {".dpkg"--"{old,new,tmp}"}}, etc.) are removed. } @ListItem { {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {postrm}}}} purge}}} //0.2fe } @ListItem { The package's file list is removed. } @RawEndList}//0ve @LP No attempt is made to unwind after errors during removal. @LP @NP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.2 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +5p @Font { 1.2vx @Break { {@PageMark ch-descriptions} 7.|0.5fe{ Descriptions of packages "-" the {{0.7 1.0} @Scale {Courier Bold} @Font {Description}} field}}}} |0f }} //0.0fe @LP The {{0.7 1.0} @Scale {Courier Bold} @Font {Description}} control file field is used by {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}} when the user is selecting which packages to install and by {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} when it displays information about the status of packages and so forth. It is included on the FTP site in the {{0.7 1.0} @Scale {Courier Bold} @Font {Packages}} files, and may also be used by the Debian WWW pages. @LP The description is intended to describe the program to a user who has never met it before so that they know whether they want to install it. It should also give information about the significant dependencies and conflicts between this package and others, so that the user knows why these dependencies and conflicts have been declared. @LP The field's format is as follows: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { Description: {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {single line synopsis}}}} {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {extended description over several lines}}}}}}} //0.2fe @LP The synopsis is often printed in lists of packages and so forth, and should be as informative as possible. Every package should also have an extended description. @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s7.1} 7.1.|0.5fe{ Types of formatting line in the extended description}}}} |0f }} //0.0fe @LP {@RawBulletList @ListItem { Those starting with a single space are part of a paragraph. Successive lines of this form will be "word-wrapped" when displayed. The leading space will usually be stripped off. } @ListItem { Those starting with two or more spaces. These will be displayed verbatim. If the display cannot be panned horizontally the displaying program will linewrap them `hard' (ie, without taking account of word breaks). If it can they will be allowed to trail off to the right. None, one or two initial spaces may be deleted, but the number of spaces deleted from each line will be the same (so that you can have indenting work correctly, for example). } @ListItem { Those containing a single space followed by a single full stop character. These are rendered as blank lines. This is the {{Times Slope} @Font {only}} way to get a blank line "-" see below. } @ListItem { Those containing a space, a full stop and some more characters. These are for future expansion. Do not use them. } @RawEndList}//0ve @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s7.2} 7.2.|0.5fe{ Notes about writing descriptions}}}} |0f }} //0.0fe @LP {{Times Slope} @Font {Always}} start extended description lines with at least one whitespace character. Fields in the control file and in the Packages file are separated by field names starting in the first column, just as message header fields are in RFC822. Forgetting the whitespace will cause {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"deb"}}{@FootNote{ Version 0.93.23 or later.}} to produce a syntax error when trying to build the package. If you force it to build anyway {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} will refuse to install the resulting mess. @LP {{Times Slope} @Font {Do not}} include any completely {{Times Slope} @Font {empty}} lines. These separate different records in the Packages file and different packages in the {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/control"}} file, and are forbidden in package control files. See the previous paragraph for what happens if you get this wrong. @LP The single line synopsis should be kept brief "-" certainly under 80 characters. {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}} displays between 25 and 49 characters without panning if you're using an "80-column" terminal, depending on what display options are in effect. @LP Do not include the package name in the synopsis line. The display software knows how to display this already, and you do not need to state it. Remember that in many situations the user may only see the synopsis line "-" make it as informative as you can. @LP The extended description should describe what the package does and how it relates to the rest of the system (in terms of, for example, which subsystem it is which part of). @LP The blurb that comes with a program in its announcements "and/or" {{0.7 1.0} @Scale {Courier Bold} @Font {README}} files is rarely suitable for use in a description. It is usually aimed at people who are already in the community where the package is used. The description field needs to make sense to anyone, even people who have no idea about any of the things the package deals with. @LP Put important information first, both in the synopis and extended description. Sometimes only the first part of the synopsis or of the description will be displayed. You can assume that there will usually be a way to see the whole extended description. @LP You may include information about dependencies and so forth in the extended description, if you wish. @LP Do not use tab characters. Their effect is not predictable. @LP Do not try to linewrap the summary (the part on the same line as the field name {{0.7 1.0} @Scale {Courier Bold} @Font {Description}}) into the extended description. This will not work correctly when the full description is displayed, and makes no sense where only the summary is available. @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s7.3} 7.3.|0.5fe{ Example description in control file for Smail}}}} |0f }} //0.0fe @LP {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { Package: smail Version: "3.1.29.1"--"13" Maintainer: Ian Jackson <"iwj10@cus.cam.ac.uk"> Recommends: pine "|" mailx "|" elm "|" emacs "|" "mail"--"user"--"agent" Suggests: metamail Depends: cron, libc5 Conflicts: sendmail Provides: "mail"--"transport"--"agent" Description: Electronic mail transport system. Smail is the recommended mail transport agent (MTA) for Debian. . An MTA is the innards of the mail system ""--"" it takes messages from "user"--"friendly" mailer programs and arranges for them to be delivered locally or passed on to other systems as required. . In order to make use of it you must have one or more user level mailreader programs such as elm, pine, mailx or Emacs (which has Rmail and VM as mailreaders) installed. If you wish to send messages other than just to other users of your system you must also have appropriate and VM as mailreaders) installed. If you wish to send messages other than just to other users of your system you must also have appropriate networking support, in the form of IP or UUCP.}}} //0.2fe @LP @NP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.2 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +5p @Font { 1.2vx @Break { {@PageMark ch-relationships} 8.|0.5fe{ Declaring relationships between packages}}}} |0f }} //0.0fe @LP Packages can declare in their control file that they have certain relationships to other packages "-" for example, that they may not be installed at the same time as certain other packages, "and/or" that they depend on the presence of others, or that they should overwrite files in certain other packages if present. @LP This is done using the {{0.7 1.0} @Scale {Courier Bold} @Font {Depends}}, {{0.7 1.0} @Scale {Courier Bold} @Font {Recommends}}, {{0.7 1.0} @Scale {Courier Bold} @Font {Suggests}}, {{0.7 1.0} @Scale {Courier Bold} @Font {Conflicts}}, {{0.7 1.0} @Scale {Courier Bold} @Font {Provides}} and {{0.7 1.0} @Scale {Courier Bold} @Font {Replaces}} control file fields. @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s-depsyntax} 8.1.|0.5fe{ Syntax of relationship fields}}}} |0f }} //0.0fe @LP These fields all have a uniform syntax. They are a list of package names separated by commas. @LP In {{0.7 1.0} @Scale {Courier Bold} @Font {Depends}}, {{0.7 1.0} @Scale {Courier Bold} @Font {Recommends}}, {{0.7 1.0} @Scale {Courier Bold} @Font {Suggests}} and {{0.7 1.0} @Scale {Courier Bold} @Font {"Pre"--"Depends"}} (the fields which declare dependencies of the package in which they occur on other packages) these package names may also be lists of alternative package names, separated by vertical bar symbols {{0.7 1.0} @Scale {Courier Bold} @Font {"|"}} (pipe symbols). @LP All the fields except {{0.7 1.0} @Scale {Courier Bold} @Font {Provides}} may restrict their applicability to particular versions of each named package. This is done in parentheses after each individual package name; the parentheses should contain a relation from the list below followed by a version number, in the format described in `Version numbering', page @PageOf{ch-versions}. @LP The relations allowed are {{0.7 1.0} @Scale {Courier Bold} @Font {<<}}, {{0.7 1.0} @Scale {Courier Bold} @Font {<=}}, {{0.7 1.0} @Scale {Courier Bold} @Font {=}}, {{0.7 1.0} @Scale {Courier Bold} @Font {>=}} and {{0.7 1.0} @Scale {Courier Bold} @Font {>>}} for strictly earlier, earlier or equal, exactly equal, later or equal and strictly later, respectively. The forms {{0.7 1.0} @Scale {Courier Bold} @Font {<}} and {{0.7 1.0} @Scale {Courier Bold} @Font {>}} were used to mean "earlier/later" or equal, rather than strictly "earlier/later," so they should not appear in new packages (though {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} still supports them). @LP Whitespace may appear at any point in the version specification, and must appear where it's necessary to disambiguate; it is not otherwise significant. For consistency and in case of future changes to {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} it is recommended that a single space be used after a version relationship and before a version number; it is usual also to put a single space after each comma, on either side of each vertical bar, and before each open parenthesis. @LP For example: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { Package: metamail Version: "2.7"--"3" Depends: libc5 (>= "5.2.18"--"4)," "mime"--"support," csh "|" tcsh}}} //0.2fe @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s8.2} 8.2.|0.5fe{ Dependencies "-" {{0.7 1.0} @Scale {Courier Bold} @Font {Depends}}, {{0.7 1.0} @Scale {Courier Bold} @Font {Recommends}}, {{0.7 1.0} @Scale {Courier Bold} @Font {Suggests}}, {{0.7 1.0} @Scale {Courier Bold} @Font {"Pre"--"Depends"}}}}}} |0f }} //0.0fe @LP These four fields are used to declare a dependency by one package on another. They appear in the depending package's control file. @LP All but {{0.7 1.0} @Scale {Courier Bold} @Font {"Pre"--"Depends"}} (discussed below) take effect {{Times Slope} @Font {only}} when a package is to be configured. They do not prevent a package being on the system in an unconfigured state while its dependencies are unsatisfied, and it is possible to replace a package whose dependencies are satisfied and which is properly installed with a different version whose dependencies are not and cannot be satisfied; when this is done the depending package will be left unconfigured (since attempts to configure it will give errors) and will not function properly. @LP For this reason packages in an installation run are usually all unpacked first and all configured later; this gives later versions of packages with dependencies on later versions of other packages the opportunity to have their dependencies satisfied. @LP Thus {{0.7 1.0} @Scale {Courier Bold} @Font {Depends}} allows package maintainers to impose an order in which packages should be configured. @LP {|0.5f {{{0.7 1.0} @Scale {Courier Bold} @Font {Depends}}}} //1.0vx @RawIndentedDisplay { This declares an absolute dependency. @LP {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} will not configure packages whose dependencies aren't satisfied. If it is asked to make an installation which would cause an installed package's dependencies to become unsatisfied it will complain{@FootNote{ Current versions (1.2.4) of {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} have a bug in this area which will cause some of these problems to be ignored.}}, unless {{0.7 1.0} @Scale {Courier Bold} @Font {""--""--"auto"--"deconfigure"}} is specified, in which case those packages will be deconfigured before the installation proceeds. @LP {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}} makes it hard for the user to select packages for installation, removal or upgrade in a way that would mean that packages' {{0.7 1.0} @Scale {Courier Bold} @Font {Depends}} fields would be unsatisfied. The user can override this if they wish, for example if they know that {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}} has an "out-of-date" view of the real package relationships. @LP The {{0.7 1.0} @Scale {Courier Bold} @Font {Depends}} field should be used if the "depended-on" package is required for the depending package to provide a significant amount of functionality. } //0fe //1.2fx {|0.5f {{{0.7 1.0} @Scale {Courier Bold} @Font {Recommends}}}} //1.0vx @RawIndentedDisplay { This declares a strong, but not absolute, dependency. @LP {{0.7 1.0} @Scale {Courier Bold} @Font {Recommends}} is ignored by {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}}, so that users using the "command-line" (who are presumed to know what they're doing) will not be impeded. @LP It is treated by {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}} exactly as {{0.7 1.0} @Scale {Courier Bold} @Font {Depends}} is; this makes it hard for the user to select things so as to leave {{0.7 1.0} @Scale {Courier Bold} @Font {Recommends}} fields unsatisfied, but they are able to do so by being persistent. @LP The {{0.7 1.0} @Scale {Courier Bold} @Font {Recommends}} field should list packages that would be found together with this one in all but unusual installations. } //0fe //1.2fx {|0.5f {{{0.7 1.0} @Scale {Courier Bold} @Font {Suggests}}}} //1.0vx @RawIndentedDisplay { This is used to declare that one package may be more useful with one or more others. Using this field tells the packaging system and the user that the listed packages are be related to this one and can perhaps enhance its usefulness, but that installing this one without them is perfectly reasonable. @LP {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}} will offer suggsted packages to the system administrator when they select the suggesting package, but the default is not to install the suggested package. } //0fe //1.2fx {|0.5f {{{0.7 1.0} @Scale {Courier Bold} @Font {"Pre"--"Depends"}}}} //1.0vx @RawIndentedDisplay { This field is like {{0.7 1.0} @Scale {Courier Bold} @Font {Depends}}, except that it also forces {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} to complete installation of the packages named before even starting the installation of the package which declares the predependency. @LP {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}} checks for predependencies when it is doing an installation run, and will attempt to find the packages which are required to be installed first and do so in the right order. @LP However, this process is slow (because it requires repeated invocations of {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}}) and troublesome (because it requires guessing where to find the appropriate files). @LP For these reasons, and because this field imposes restrictions on the order in which packages may be unpacked (which can be difficult for installations from multipart media, for example), {{0.7 1.0} @Scale {Courier Bold} @Font {"Pre"--"Depends"}} should be used sparingly, preferably only by packages whose premature upgrade or installation would hamper the ability of the system to continue with any upgrade that might be in progress. @LP When the package declaring it is being configured, a {{0.7 1.0} @Scale {Courier Bold} @Font {"Pre"--"Dependency"}} will be considered satisfied only if the depending package has been correctly configured, just as if an ordinary {{0.7 1.0} @Scale {Courier Bold} @Font {Depends}} had been used. @LP However, when a package declaring a predependency is being unpacked the predependency can be satisfied even if the "depended-on" package(s) are only unpacked or "half-configured," provided that they have been configured correctly at some point in the past (and not removed or partially removed since). In this case both the "previously-configured" and currently unpacked or "half-configured" versions must satisfy any version clause in the {{0.7 1.0} @Scale {Courier Bold} @Font {"Pre"--"Depends"}} field. } //0fe @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s8.2.1} 8.2.1.|0.5fe{ Dependencies on shared libraries}}}//0.2fe @LP The dependency fields listed above are used by packages which need shared libraries to declare dependencies on the appropriate packages. @LP These dependencies are usually determined automatically using {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"shlibdeps"}} and inserted in the package control file using the control file substitution variables mechanism; see `{{0.7 1.0} @Scale {Courier Bold} @Font {"debian/substvars"}} and variable substitutions', page @PageOf{s-srcsubstvars} and `Tools for processing source packages', page @PageOf{s-sourcetools}. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s8.2.2} 8.2.2.|0.5fe{ Deconfiguration due to removal during bulk installations}}}//0.2fe @LP If {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} would like to remove a package due to a conflict, as described above, but this would violate a dependency of some other package on the system, {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} will usually not remove the conflicting package and halt with an error. @LP However, if the {{0.7 1.0} @Scale {Courier Bold} @Font {""--""--"auto"--"deconfigure"}} ({{0.7 1.0} @Scale {Courier Bold} @Font {""--"B"}}) option is used {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} will automatically `deconfigure' the package with the problematic dependency, so that the conflicting package can be removed and the package we're trying to install can be installed. If {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} is being asked to install packages (rather than just unpacking them) it will try to reconfigure the package when it has unpacked all its arguments, in the hope that one of the other packages it is installing will satisfy the problematic dependency. @LP {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}} supplies this argument to {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} when it invokes it, so that bulk installations proceed smoothly. @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s-conflicts} 8.3.|0.5fe{ Alternative packages "-" {{0.7 1.0} @Scale {Courier Bold} @Font {Conflicts}} and {{0.7 1.0} @Scale {Courier Bold} @Font {Replaces}}}}}} |0f }} //0.0fe @LP When one package declares a conflict with another {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} will refuse to allow them to be installed on the system at the same time. @LP If one package is to be installed, the other must be removed first "-" if the package being installed is marked as replacing (`{{0.7 1.0} @Scale {Courier Bold} @Font {Replaces}} "-" overwriting files and replacing packages', page @PageOf{s-replaces}) the one on the system, or the one on the system is marked as deselected, or both packages are marked {{0.7 1.0} @Scale {Courier Bold} @Font {Essential}}, then {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} will automatically remove the package which is causing the conflict, otherwise it will halt the installation of the new package with an error. @LP {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}} makes it hard to select conflicting packages, though the user can override this if they wish. If they do not override it then {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}} will select one of the packages for removal, and the user must make sure it is the right one. In the future {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}} will look for the presence of a {{0.7 1.0} @Scale {Courier Bold} @Font {Replaces}} field to help decide which package should be installed and which removed. @LP A package will not cause a conflict merely because its configuration files are still installed; it must be at least "half-installed." @LP A special exception is made for packages which declare a conflict with their own package name, or with a virtual package which they provide (see below): this does not prevent their installation, and allows a package to conflict with others providing a replacement for it. You use this feature when you want the package in question to be the only package providing something. @LP A {{0.7 1.0} @Scale {Courier Bold} @Font {Conflicts}} entry should almost never have an `earlier than' version clause. This would prevent {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} from upgrading or installing the package which declared such a conflict until the upgrade or removal of the "conflicted-with" package had been completed. This aspect of installation ordering is not handled by {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}}, so that the use {{0.7 1.0} @Scale {Courier Bold} @Font {Conflicts}} in this way is likely to cause problems for `bulk run' upgrades and installations. @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s-virtual} 8.4.|0.5fe{ Virtual packages "-" {{0.7 1.0} @Scale {Courier Bold} @Font {Provides}}}}}} |0f }} //0.0fe @LP As well as the names of actual (`concrete') packages, the package relationship fields {{0.7 1.0} @Scale {Courier Bold} @Font {Depends}}, {{0.7 1.0} @Scale {Courier Bold} @Font {Recommends}}, {{0.7 1.0} @Scale {Courier Bold} @Font {Suggests}} and {{0.7 1.0} @Scale {Courier Bold} @Font {Conflicts}} may mention virtual packages. @LP A virtual package is one which appears in the {{0.7 1.0} @Scale {Courier Bold} @Font {Provides}} control file field of another package. The effect is as if the package(s) which provide a particular virtual package name had been listed by name everywhere were the virtual package name appears. @LP If there are both a real and a virtual package of the same name then the dependency may be satisfied (or the conflict caused) by either the real package or any of the virtual packages which provide it. This is so that, for example, supposing we have //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { Package: vm Depends: emacs}}} //0.2fe and someone else releases an xemacs package they can say //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { Package: xemacs Provides: emacs}}} //0.2fe and all will work in the interim (until a purely virtual package name is decided on and the {{0.7 1.0} @Scale {Courier Bold} @Font {emacs}} and {{0.7 1.0} @Scale {Courier Bold} @Font {vm}} packages are changed to use it). @LP If a dependency or a conflict has a version number attached then only real packages will be considered to see whether the relationship is satisfied (or the prohibition violated, for a conflict) "-" it is assumed that a real package which provides virtual package is not of the `right' version. So, a {{0.7 1.0} @Scale {Courier Bold} @Font {Provides}} field may not contain version numbers, and the version number of the concrete package which provides a particular virtual package will not be looked at when considering a dependency on or conflict with the virtual package name. @LP If you want to specify which of a set of real packages should be the default to satisfy a particular dependency on a virtual package, you should list the real package as alternative before the virtual. @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s-replaces} 8.5.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {Replaces}} "-" overwriting files and replacing packages}}}} |0f }} //0.0fe @LP The {{0.7 1.0} @Scale {Courier Bold} @Font {Replaces}} control file field has two purposes, which come into play in different situations. @LP Virtual packages (`Virtual packages "-" {{0.7 1.0} @Scale {Courier Bold} @Font {Provides}}', page @PageOf{s-virtual}) are not considered when looking at a {{0.7 1.0} @Scale {Courier Bold} @Font {Replaces}} field "-" the packages declared as being replaced must be mentioned by their real names. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s8.5.1} 8.5.1.|0.5fe{ Overwriting files in other packages}}}//0.2fe @LP Firstly, as mentioned before, it is usually an error for a package to contains files which are on the system in another package, though currently the {{0.7 1.0} @Scale {Courier Bold} @Font {""--""--"force"--"overwrite"}} flag is enabled by default, downgrading the error to a warning, @LP If the overwriting package declares that it replaces the one containing the file being overwritten then {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} will proceed, and replace the file from the old package with that from the new. The file will no longer be listed as `owned' by the old package. @LP If a package is completely replaced in this way, so that {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} does not know of any files it still contains, it is considered to have disappeared. It will be marked as not wanted on the system (selected for removal) and not installed. Any conffiles details noted in the package will be ignored, as they will have been taken over by the replacing package(s). The package's {{0.7 1.0} @Scale {Courier Bold} @Font {postrm}} script will be run to allow the package to do any final cleanup required. See `Summary of ways maintainer scripts are called', page @PageOf{s-mscriptsinstact}. @LP In the future {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} will discard files which overwrite those from another package which declares that it replaces the one being installed (so that you can install an older version of a package without problems). @LP This usage of {{0.7 1.0} @Scale {Courier Bold} @Font {Replaces}} only takes effect when both packages are at least partially on the system at once, so that it can only happen if they do not conflict or if the conflict has been overridden. @LP @CNP @Heading +3p @Font { 1.2vx @Break { {@PageMark s8.5.2} 8.5.2.|0.5fe{ Replacing whole packages, forcing their removal}}}//0.2fe @LP Secondly, {{0.7 1.0} @Scale {Courier Bold} @Font {Replaces}} allows {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} and {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}} to resolve which package should be removed when a conflict "-" see `Alternative packages "-" {{0.7 1.0} @Scale {Courier Bold} @Font {Conflicts}} and {{0.7 1.0} @Scale {Courier Bold} @Font {Replaces}}', page @PageOf{s-conflicts}. This usage only takes effect when the two packages {{Times Slope} @Font {do}} conflict, so that the two effects do not interfere with each other. @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s8.6} 8.6.|0.5fe{ Defaults for satisfying dependencies "-" ordering}}}} |0f }} //0.0fe @LP Ordering is significant in dependency fields. @LP Usually dselect will suggest to the user that they select the package with the most `fundamental' class (eg, it will prefer Base packages to Optional ones), or the one that they `most wanted' to select in some sense. @LP In the absence of other information {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}} will offer a default selection of the first named package in a list of alternatives. @LP However, there is no way to specify the `order' of several packages which all provide the same thing, when that thing is listed as a dependency. @LP Therefore a dependency on a virtual package should contain a concrete package name as the first alternative, so that this is the default. @LP For example, consider the set of packages: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { Package: glibcdoc Recommends: "info"--"browser" Package: info Provides: "info"--"browser" Package: emacs Provides: "info"--"browser"}}} //0.2fe @LP If {{0.7 1.0} @Scale {Courier Bold} @Font {emacs}} and {{0.7 1.0} @Scale {Courier Bold} @Font {info}} both have the same priority then {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}}'s choice is essentially random. Better would be //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { Package: glibcdoc Recommends: info "|" "info"--"browser"}}} //0.2fe so that {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}} defaults to selecting the lightweight standalone info browser. @LP @NP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.2 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +5p @Font { 1.2vx @Break { {@PageMark ch-conffiles} 9.|0.5fe{ Configuration file handling}}}} |0f }} //0.0fe @LP {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} can do a certain amount of automatic handling of package configuration files. @LP Whether this mechanism is appropriate depends on a number of factors, but basically there are two approaches to any particular configuration file. @LP The easy method is to ship a "best-effort" configuration in the package, and use {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}}'s conffile mechanism to handle updates. If the user is unlikely to want to edit the file, but you need them to be able to without losing their changes, and a new package with a changed version of the file is only released infrequently, this is a good approach. @LP The hard method is to build the configuration file from scratch in the {{0.7 1.0} @Scale {Courier Bold} @Font {postinst}} script, and to take the responsibility for fixing any mistakes made in earlier versions of the package automatically. This will be appropriate if the file is likely to need to be different on each system. @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s9.1} 9.1.|0.5fe{ Automatic handling of configuration files by {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}}}}}} |0f }} //0.0fe @LP A package may contain a control area file called {{0.7 1.0} @Scale {Courier Bold} @Font {conffiles}}. This file should be a list of filenames of configuration files needing automatic handling, separated by newlines. The filenames should be absolute pathnames, and the files referred to should actually exist in the package. @LP When a package is upgraded {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} will process the configuration files during the configuration stage, shortly before it runs the package's {{0.7 1.0} @Scale {Courier Bold} @Font {postinst}} script, @LP For each file it checks to see whether the version of the file included in the package is the same as the one that was included in the last version of the package (the one that is being upgraded from); it also compares the version currently installed on the system with the one shipped with the last version. @LP If neither the user nor the package maintainer has changed the file, it is left alone. If one or the other has changed their version, then the changed version is preferred "-" ie, if the user edits their file, but the package maintainer doesn't ship a different version, the user's changes will stay, silently, but if the maintainer ships a new version and the user hasn't edited it the new version will be installed (with an informative message). If both have changed their version the user is prompted about the problem and must resolve the differences themselves. @LP The comparisons are done by calculating the MD5 message digests of the files, and storing the MD5 of the file as it was included in the most recent version of the package. @LP When a package is installed for the first time {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} will install the file that comes with it, unless that would mean overwriting a file already on the filesystem. @LP However, note that {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} will {{Times Slope} @Font {not}} replace a conffile that was removed by the user (or by a script). This is necessary because with some programs a missing file produces an effect hard or impossible to achieve in another way, so that a missing file needs to be kept that way if the user did it. @LP Note that a package should {{Times Slope} @Font {not}} modify a {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}}"-handled" conffile in its maintainer scripts. Doing this will lead to {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} giving the user confusing and possibly dangerous options for conffile update when the package is upgraded. @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s9.2} 9.2.|0.5fe{ "Fully-featured" maintainer script configuration handling}}}} |0f }} //0.0fe @LP For files which contain "site-specific" information such as the hostname and networking details and so forth, it is better to create the file in the package's {{0.7 1.0} @Scale {Courier Bold} @Font {postinst}} script. @LP This will typically involve examining the state of the rest of the system to determine values and other information, and may involve prompting the user for some information which can't be obtained some other way. @LP When using this method there are a couple of important issues which should be considered: @LP If you discover a bug in the program which generates the configuration file, or if the format of the file changes from one version to the next, you will have to arrange for the postinst script to do something sensible "-" usually this will mean editing the installed configuration file to remove the problem or change the syntax. You will have to do this very carefully, since the user may have changed the file, perhaps to fix the very problem that your script is trying to deal with "-" you will have to detect these situations and deal with them correctly. @LP If you do go down this route it's probably a good idea to make the program that generates the configuration file(s) a separate program in {{0.7 1.0} @Scale {Courier Bold} @Font {"/usr/sbin"}}, by convention called {{0.7 1.0} @Scale {Courier Bold} @Font {{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {package}}}}config}} and then run that if appropriate from the "post-installation" script. The {{0.7 1.0} @Scale {Courier Bold} @Font {{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {package}}}}config}} program should not unquestioningly overwrite an existing configuration "-" if its mode of operation is geared towards setting up a package for the first time (rather than any arbitrary reconfiguration later) you should have it check whether the configuration already exists, and require a {{0.7 1.0} @Scale {Courier Bold} @Font {""--""--"force"}} flag to overwrite it. @LP @NP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.2 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +5p @Font { 1.2vx @Break { {@PageMark ch-alternatives} 10.|0.5fe{ Alternative versions of an interface "-" {{0.7 1.0} @Scale {Courier Bold} @Font {"update"--"alternatives"}}}}}} |0f }} //0.0fe @LP When several packages all provide different versions of the same program or file it is useful to have the system select a default, but to allow the system administrator to change it and have their decisions respected. @LP For example, there are several versions of the {{0.7 1.0} @Scale {Courier Bold} @Font {vi}} editor, and there is no reason to prevent all of them from being installed at once, each under their own name ({{0.7 1.0} @Scale {Courier Bold} @Font {nvi}}, {{0.7 1.0} @Scale {Courier Bold} @Font {vim}} or whatever). Nevertheless it is desirable to have the name {{0.7 1.0} @Scale {Courier Bold} @Font {vi}} refer to something, at least by default. @LP If all the packages involved cooperate, this can be done with {{0.7 1.0} @Scale {Courier Bold} @Font {"update"--"alternatives"}}. @LP Each package provides its own version under its own name, and calls {{0.7 1.0} @Scale {Courier Bold} @Font {"update"--"alternatives"}} in its postinst to register its version (and again in its prerm to deregister it). @LP See the manpage {{0.7 1.0} @Scale {Courier Bold} @Font {"update"--"alternatives(8)"}} for details. @LP If {{0.7 1.0} @Scale {Courier Bold} @Font {"update"--"alternatives"}} does not seem appropriate you may wish to consider using diversions instead. @LP @NP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.2 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +5p @Font { 1.2vx @Break { {@PageMark ch-diversions} 11.|0.5fe{ Diversions "-" overriding a package's version of a file}}}} |0f }} //0.0fe @LP It is possible to have {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} not overwrite a file when it reinstalls the package it belongs to, and to have it put the file from the package somewhere else instead. @LP This can be used locally to override a package's version of a file, or by one package to override another's version (or provide a wrapper for it). @LP Before deciding to use a diversion, read `Alternative versions of an interface "-" {{0.7 1.0} @Scale {Courier Bold} @Font {"update"--"alternatives"}}', page @PageOf{ch-alternatives} to see if you really want a diversion rather than several alternative versions of a program. @LP There is a diversion list, which is read by {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}}, and updated by a special program {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"divert"}}. Please see {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"divert(8)"}} for full details of its operation. @LP When a package wishes to divert a file from another, it should call {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"divert"}} in its preinst to add the diversion and rename the existing file. For example, supposing that a {{0.7 1.0} @Scale {Courier Bold} @Font {smailwrapper}} package wishes to install a wrapper around {{0.7 1.0} @Scale {Courier Bold} @Font {"/usr/sbin/smail"}}: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { if [ install = "\"$1\"" ]; then "dpkg"--"divert" ""--""--"package" smailwrapper ""--""--"add" ""--""--"rename" "\\" ""--""--"divert" "/usr/sbin/smail.real" "/usr/sbin/smail" fi}}} //0.2fe Testing {{0.7 1.0} @Scale {Courier Bold} @Font {$1}} is necessary so that the script doesn't try to add the diversion again when {{0.7 1.0} @Scale {Courier Bold} @Font {smailwrapper}} is upgraded. The {{0.7 1.0} @Scale {Courier Bold} @Font {""--""--"package" smailwrapper}} ensures that {{0.7 1.0} @Scale {Courier Bold} @Font {smailwrapper}}'s copy of {{0.7 1.0} @Scale {Courier Bold} @Font {"/usr/sbin/smail"}} can bypass the diversion and get installed as the true version. @LP The postrm has to do the reverse: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { if [ remove = "\"$1\"" ]; then "dpkg"--"divert" ""--""--"package" smailwrapper ""--""--"remove" ""--""--"rename" "\\" ""--""--"divert" "/usr/sbin/smail.real" "/usr/sbin/smail" fi}}} //0.2fe @LP Do not attempt to divert a file which is vitally important for the system's operation "-" when using {{0.7 1.0} @Scale {Courier Bold} @Font {"dpkg"--"divert"}} there is a time, after it has been diverted but before {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} has installed the new version, when the file does not exist. @LP @NP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.2 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +5p @Font { 1.2vx @Break { {@PageMark ch-sharedlibs} 12.|0.5fe{ Shared libraries}}}} |0f }} //0.0fe @LP Packages containing shared libraries must be constructed with a little care to make sure that the shared library is always available. This is especially important for packages whose shared libraries are vitally important, such as the libc. @LP Firstly, your package should install the shared libraries under their normal names. For example, the {{0.7 1.0} @Scale {Courier Bold} @Font {libgdbm1}} package should install {{0.7 1.0} @Scale {Courier Bold} @Font {libgdbm.so.1.7.3}} as {{0.7 1.0} @Scale {Courier Bold} @Font {"/usr/lib/libgdbm.so.1.7.3"}}. The files should not be renamed or relinked by any prerm or postrm scripts; {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} will take care of renaming things safely without affecting running programs, and attempts to interfere with this are likely to lead to problems. @LP Secondly, your package should include the symlink that {{0.7 1.0} @Scale {Courier Bold} @Font {ldconfig}} would create for the shared libraries. For example, the {{0.7 1.0} @Scale {Courier Bold} @Font {libgdbm1}} package should include a symlink from {{0.7 1.0} @Scale {Courier Bold} @Font {"/usr/lib/libgdbm.so.1"}} to {{0.7 1.0} @Scale {Courier Bold} @Font {libgdbm.so.1.7.3}}. This is needed so that {{0.7 1.0} @Scale {Courier Bold} @Font {ld.so}} can find the library in between the time {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} installs it and {{0.7 1.0} @Scale {Courier Bold} @Font {ldconfig}} is run in the {{0.7 1.0} @Scale {Courier Bold} @Font {postinst}} script. Futhermore, and {{Times Slope} @Font {this is very important}}, the symlink must be placed before the library it points to in the {{0.7 1.0} @Scale {Courier Bold} @Font {.deb}} file. Currently the way to ensure the ordering is done properly is to create the symlink in the appropriate {{0.7 1.0} @Scale {Courier Bold} @Font {"debian/tmp/.../lib"}} directory before installing the library when you build the package. @LP If you do the above your package does not need to call {{0.7 1.0} @Scale {Courier Bold} @Font {ldconfig}} in its maintainer scripts. It is especially important not to call {{0.7 1.0} @Scale {Courier Bold} @Font {ldconfig}} in the postrm or preinst scripts in the case where the package is being upgraded (see the programmer's manual), as {{0.7 1.0} @Scale {Courier Bold} @Font {ldconfig}} will see the temporary names that {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} uses for the files while it is installing them and will make the shared library links point to them, just before {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} continues the installation and removes the links! @LP @NP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.2 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +5p @Font { 1.2vx @Break { {@PageMark ch-sysvinit} 13.|0.5fe{ Configuration of {{0.7 1.0} @Scale {Courier Bold} @Font {init}}}}}} |0f }} //0.0fe @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s13.1} 13.1.|0.5fe{ Introduction to the {{0.7 1.0} @Scale {Courier Bold} @Font {init.d}} scheme}}}} |0f }} //0.0fe @LP The {{0.7 1.0} @Scale {Courier Bold} @Font {"/etc/init.d"}} directory contains the scripts executed by {{0.7 1.0} @Scale {Courier Bold} @Font {init}} when init state (or `runlevel') is changed (see {{0.7 1.0} @Scale {Courier Bold} @Font {init(8)}}). @LP These scripts are be referenced by symbolic links in the {{0.7 1.0} @Scale {Courier Bold} @Font {"/etc/rc"{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {n}}}}.d}} directories. When changing runlevels, init looks in the directory {{0.7 1.0} @Scale {Courier Bold} @Font {"/etc/rc"{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {n}}}}.d}} for the scripts it should execute, where {{Times Slope} @Font {n}} is the runlevel that is being changed to. @LP The names of the links all have the form {{0.7 1.0} @Scale {Courier Bold} @Font {S{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {mm}}}}{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {script}}}}}} or {{0.7 1.0} @Scale {Courier Bold} @Font {K{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {mm}}}}{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {script}}}}}} where {{Times Slope} @Font {mm}} is a "two-digit" number and {{Times Slope} @Font {script}} is the name of the script (this should be the same as the name of the actual script in {{0.7 1.0} @Scale {Courier Bold} @Font {"/etc/init.d"}}. When {{0.7 1.0} @Scale {Courier Bold} @Font {init}} changes runlevel first the targets of the links whose names starting with a {{0.7 1.0} @Scale {Courier Bold} @Font {K}} are executed, each with the single argument {{0.7 1.0} @Scale {Courier Bold} @Font {stop}}, followed by the scripts prefixed with an {{0.7 1.0} @Scale {Courier Bold} @Font {S}}, each with the single argument {{0.7 1.0} @Scale {Courier Bold} @Font {start}}. The {{0.7 1.0} @Scale {Courier Bold} @Font {K}} links are responsible for killing services and the {{0.7 1.0} @Scale {Courier Bold} @Font {S}} link for starting services upon entering the runlevel. @LP For example, if we are changing from runlevel 2 to runlevel 3, init will first execute all of the {{0.7 1.0} @Scale {Courier Bold} @Font {K}} prefixed scripts it finds in {{0.7 1.0} @Scale {Courier Bold} @Font {"/etc/rc3.d"}}, and then all of the {{0.7 1.0} @Scale {Courier Bold} @Font {S}} prefixed scripts. The links starting with {{0.7 1.0} @Scale {Courier Bold} @Font {K}} will cause the "referred-to" file to be executed with an argument of {{0.7 1.0} @Scale {Courier Bold} @Font {stop}}, and the {{0.7 1.0} @Scale {Courier Bold} @Font {S}} links with an argument of {{0.7 1.0} @Scale {Courier Bold} @Font {start}}. @LP The "two-digit" number {{Times Slope} @Font {mm}} is used to decide which order to start and stop things in "-" "low-numbered" links have their scripts run first. For example, the {{0.7 1.0} @Scale {Courier Bold} @Font {K20}} scripts will be executed before the {{0.7 1.0} @Scale {Courier Bold} @Font {K30}} scripts. This is used when a certain service must be started before another. For example, the name server {{0.7 1.0} @Scale {Courier Bold} @Font {bind}} might need to be started before the news server {{0.7 1.0} @Scale {Courier Bold} @Font {inn}} so that {{0.7 1.0} @Scale {Courier Bold} @Font {inn}} can set up its access lists. In this case, the script that starts {{0.7 1.0} @Scale {Courier Bold} @Font {bind}} should have a lower number than the script that starts {{0.7 1.0} @Scale {Courier Bold} @Font {inn}} so that it runs first: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { "/etc/rc2.d/S17bind" "/etc/rc2.d/S70inn"}}} //0.2fe @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s13.2} 13.2.|0.5fe{ Writing {{0.7 1.0} @Scale {Courier Bold} @Font {init.d}} scripts}}}} |0f }} //0.0fe @LP Packages can and should place scripts in {{0.7 1.0} @Scale {Courier Bold} @Font {"/etc/init.d"}} to start or stop services at boot time or during a change of runlevel. These scripts should be named {{0.7 1.0} @Scale {Courier Bold} @Font {"/etc/init.d/"{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {package}}}}}}, and they should accept one argument, saying what to do: {{0.7 1.0} @Scale {Courier Bold} @Font {start}}, meaning to starts the service, or {{0.7 1.0} @Scale {Courier Bold} @Font {stop}}, to stop the service. Optionally they can support {{0.7 1.0} @Scale {Courier Bold} @Font {reload}} which causes the configuration to be reloaded. @LP The {{0.7 1.0} @Scale {Courier Bold} @Font {init.d}} scripts should ensure that they will behave sensibly if invoked with {{0.7 1.0} @Scale {Courier Bold} @Font {start}} when the service is already running, or with {{0.7 1.0} @Scale {Courier Bold} @Font {stop}} when it isn't, and that they don't kill "unfortunately-named" user processes. The best way to achieve this is usually to use {{0.7 1.0} @Scale {Courier Bold} @Font {"start"--"stop"--"daemon"}}. @LP These scripts should not fail obscurely when the configuration files remain but the package has been removed, as the default in {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} is to leave configuration files on the system after the package has been removed. Only when it is executed with the {{0.7 1.0} @Scale {Courier Bold} @Font {""--""--"purge"}} option will dpkg remove configuration files. Therefore, you should include a {{0.7 1.0} @Scale {Courier Bold} @Font {test}} statement at the top of the script, like this: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { test ""--"f" {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {"program"--"executed"--"later"--"in"--"script"}}}} "||" exit 0}}} //0.2fe @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s13.3} 13.3.|0.5fe{ Managing the {{0.7 1.0} @Scale {Courier Bold} @Font {rc{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {n}}}}.d}} links "-" {{0.7 1.0} @Scale {Courier Bold} @Font {"update"--"rc.d"}}}}}} |0f }} //0.0fe @LP A program is provided, {{0.7 1.0} @Scale {Courier Bold} @Font {"update"--"rc.d"}}, to make it easier for package maintainers to arrange for the proper creation and removal of {{0.7 1.0} @Scale {Courier Bold} @Font {"/etc/rc"{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {n}}}}.d}} symbolic links from their postinst and postrm scripts. @LP You should use this script to make changes to {{0.7 1.0} @Scale {Courier Bold} @Font {"/etc/rc"{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {n}}}}.d}} and {{Times Slope} @Font {never}} include any {{0.7 1.0} @Scale {Courier Bold} @Font {"/etc/rc"{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {n}}}}.d}} symbolic links in the actual archive. @LP By default {{0.7 1.0} @Scale {Courier Bold} @Font {"update"--"rc.d"}} will start services in each of the "multi-user" state runlevels (2, 3, 4, and 5) and stop them in the halt runlevel (0), the "single-user" runlevel (1) and the reboot runlevel (6). The system administrator will have the opportunity to customize runlevels by simply adding, moving, or removing the symbolic links in {{0.7 1.0} @Scale {Courier Bold} @Font {"/etc/rc"{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {n}}}}.d}}. @LP To get the default behaviour for your package, put in your postinst script //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { "update"--"rc.d" {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {package}}}} default >"/dev/null"}}} //0.2fe and in your postrm //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { if [ purge = "\"$1\"" ]; then "update"--"rc.d" {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {package}}}} remove >"/dev/null" fi}}} //0.2fe @LP This will use a default sequence number of 20. If it does not matter when or in which order the script is run, use this default. If it does, then you should talk to the maintainer of the {{0.7 1.0} @Scale {Courier Bold} @Font {sysvinit}} package or post to {{0.7 1.0} @Scale {Courier Bold} @Font {"debian"--"devel"}}, and they will help you choose a number. @LP For more information about using {{0.7 1.0} @Scale {Courier Bold} @Font {"update"--"rc.d"}}, please consult its manpage {{0.7 1.0} @Scale {Courier Bold} @Font {"update"--"rc.d(8)"}}. @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s13.4} 13.4.|0.5fe{ "Boot-time" initialisation "-" {{0.7 1.0} @Scale {Courier Bold} @Font {rc.boot}}}}}} |0f }} //0.0fe @LP There is another directory, {{0.7 1.0} @Scale {Courier Bold} @Font {"/etc/rc.boot"}}, which contains scripts which are run once per machine boot. This facility is provided for initialisation of hardware devices, cleaning up of leftover files, and so forth. @LP For example, the {{0.7 1.0} @Scale {Courier Bold} @Font {kbd}} package provides a script here for initialising the keyboard layout and console font and mode. @LP The files in {{0.7 1.0} @Scale {Courier Bold} @Font {"/etc/rc.boot"}} should {{Times Slope} @Font {not}} be links into {{0.7 1.0} @Scale {Courier Bold} @Font {"/etc/init.d"}} "-" they should be the scripts themselves. @LP {{0.7 1.0} @Scale {Courier Bold} @Font {rc.boot}} should {{Times Slope} @Font {not}} be used for starting "general-purpose" daemons and similar activities. This should be done using the {{0.7 1.0} @Scale {Courier Bold} @Font {rc{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {n}}}}.d}} scheme, above, so that the services can be started and stopped cleanly when the runlevel changes or the machine is to be shut down or rebooted. @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s13.5} 13.5.|0.5fe{ Notes}}}} |0f }} //0.0fe @LP {{Times Slope} @Font {Do not}} include the {{0.7 1.0} @Scale {Courier Bold} @Font {"/etc/rc"{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {n}}}}".d/*"}} symbolic links in the {{0.7 1.0} @Scale {Courier Bold} @Font {.deb}} filesystem archive! {{Times Slope} @Font {This will cause problems!}} You should create them with {{0.7 1.0} @Scale {Courier Bold} @Font {"update"--"rc.d"}}, as above. @LP {{Times Slope} @Font {Do not}} include the {{0.7 1.0} @Scale {Courier Bold} @Font {"/etc/rc"{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {n}}}}".d/*"}} symbolic links in {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}}'s conffiles list! {{Times Slope} @Font {This will cause problems!}} {{Times Slope} @Font {Do}}, however, include the {{0.7 1.0} @Scale {Courier Bold} @Font {"/etc/init.d"}} scripts in conffiles. @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s13.6} 13.6.|0.5fe{ Example}}}} |0f }} //0.0fe @LP The {{0.7 1.0} @Scale {Courier Bold} @Font {bind}} DNS (nameserver) package wants to make sure that the nameserver is running in multiuser runlevels, and is properly shut down with the system. It puts a script in {{0.7 1.0} @Scale {Courier Bold} @Font {"/etc/init.d"}}, naming the script appropriately {{0.7 1.0} @Scale {Courier Bold} @Font {bind}}. As you can see, the script interprets the argument {{0.7 1.0} @Scale {Courier Bold} @Font {reload}} to send the nameserver a {{0.7 1.0} @Scale {Courier Bold} @Font {HUP}} signal (causing it to reload its configuration); this way the user can say {{0.7 1.0} @Scale {Courier Bold} @Font {"/etc/init.d/bind" reload}} to reload the nameserver. @LP {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { "#!/bin/sh" "#" Original version by Robert Leslie <"rob@mars.org">, edited by iwj test ""--"x" "/usr/sbin/named" "||" exit 0 case "\"$1\"" in start) test ""--"f" "/etc/named.boot" ""--"a" ""--"f" "/var/named/boot.options" "||" exit 0 "start"--"stop"--"daemon" ""--""--"start" ""--""--"verbose" ""--""--"exec" "/usr/sbin/named" ;; stop) "start"--"stop"--"daemon" ""--""--"stop" ""--""--"verbose" "\\" ""--""--"pidfile" "/var/run/named.pid" ""--""--"exec" "/usr/sbin/named" ;; reload) "start"--"stop"--"daemon" ""--""--"stop" ""--""--"signal" 1 ""--""--"verbose" "\\" ""--""--"pidfile" "/var/run/named.pid" ""--""--"exec" "/usr/sbin/named" ;; *) echo "\"Usage:" "/etc/init.d/bind" "{start|stop|reload}\"" ">&2" exit 1 ;; esac exit 0}}} //0.2fe @LP Another example on which to base your {{0.7 1.0} @Scale {Courier Bold} @Font {"/etc/init.d"}} scripts is in {{0.7 1.0} @Scale {Courier Bold} @Font {"/etc/init.d/skeleton"}}. @LP If this package is happy with the default setup from {{0.7 1.0} @Scale {Courier Bold} @Font {"update"--"rc.d"}}, namely an ordering number of 20 and having named running in all runlevels, it can say in its postinst: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { "update"--"rc.d" bind default ">/dev/null"}}} //0.2fe And in its postrm, to remove the links when the package is purged: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { if [ purge = "\"$1\"" ]; then "update"--"rc.d" acct remove ">/dev/null" fi}}} //0.2fe @LP @NP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.2 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +5p @Font { 1.2vx @Break { {@PageMark ch-methif} 14.|0.5fe{ {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}}'s interface to its installation methods}}}} |0f }} //0.0fe @LP {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}} calls scripts from its installation methods when it needs to actually access data from the distribution. The core program {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}} itself just calls these scripts and provides the package and access method selection interfaces. The installation methods are responsible for invoking {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} as appropriate. @LP Each installation method has three scripts: //1.0vx {@RawBulletList gap { 1.0vx } @ListItem { Setup installation parameters. } @ListItem { Update list of available packages. } @ListItem { Install. } @RawEndList}//0ve @LP {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}} searches for methods in {{0.7 1.0} @Scale {Courier Bold} @Font {"/usr/lib/dpkg/methods"}} and {{0.7 1.0} @Scale {Courier Bold} @Font {"/usr/local/lib/dpkg/methods"}}. @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s14.1} 14.1.|0.5fe{ Functions of the method scripts}}}} |0f }} //0.0fe @LP The setup script is run just after the user has chosen an installation method. It should prompt the user for parameters like the site to "NFS-mount" or FTP from, the directory to use, or the directory or filesystem where the {{0.7 1.0} @Scale {Courier Bold} @Font {.deb}} files can be found, or the tape or floppy device to install from. It should store the responses under {{0.7 1.0} @Scale {Courier Bold} @Font {"/var/lib/dpkg/methods"}} "-" see below. If no available packages list is available it should perhaps offer to scan the available packages. @LP The update script should obtain a list of available packages if possible, and run {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg ""--""--"update"--"avail"}}, {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg ""--""--"merge"--"avail"}} "and/or" {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg ""--""--"forget"--"old"--"unavail"}} to load it into {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} and {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}}'s database of available packages. If no packages list was available and the user was offered and accepted the option of scanning the actual files available this scan should be done here, using {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg ""--""--"record"--"avail"}}. @LP The install script should feed all the available {{0.7 1.0} @Scale {Courier Bold} @Font {.deb}} files to {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg ""--""--"iGOEB"}} (this is equivalent to {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg ""--""--"install" ""--""--"refuse"--"downgrade" ""--""--"selected"--"only" ""--""--"skip"--"same"--"version" ""--""--"auto"--"deconfigure"}}). The {{0.7 1.0} @Scale {Courier Bold} @Font {""--"R"}} ({{0.7 1.0} @Scale {Courier Bold} @Font {""--""--"recursive"}}) option for traversing subdirectories may also be useful here). @LP If any of these scripts needs to display a message for the user, it should wait for the user to hit `return' before exiting so that dselect doesn't immediately rewrite the screen. @LP If a method script succeeds (returns a zero exit status) {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}} will return immediately to the main menu, with the `next' option highlighted ready for the user to select it. If it fails {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}} will display a message and wait for the user to hit return. @LP @CNP { newpath 0 ysize 0.3 ft sub moveto xsize 0 rlineto 0 0.1 ft rlineto xsize neg 0 rlineto closepath fill } @Graphic { //1.6f @HAdjust { @HContract {@Heading +4p @Font { 1.2vx @Break { {@PageMark s14.2} 14.2.|0.5fe{ Location and arguments of the method scripts}}}} |0f }} //0.0fe @LP A set of scripts (henceforth known as a group) may provide several methods on the `main menu' with different behaviour. For example, there might be a generic "get-packages-by-FTP" group which might provide methods in the main menu for installation directly from one of the Debian mirror sites as well as for installation from a "user-specified" site. @LP Each group of methods implemented by the same set of scripts should have a subdirectory {{0.7 1.0} @Scale {Courier Bold} @Font {"/usr/lib/dpkg/methods/"{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {group}}}}}} or {{0.7 1.0} @Scale {Courier Bold} @Font {"/usr/local/lib/dpkg/methods/"{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {group}}}}}}, containing: //1.0vx {|0.5f {{{0.7 1.0} @Scale {Courier Bold} @Font {names}}}} //1.0vx {|2f { a list of "user-visible" methods provided by these scripts. }} //1.0vx {|0.5f {{{0.7 1.0} @Scale {Courier Bold} @Font {setup}}}} //1.0vx {|0.5f {{{0.7 1.0} @Scale {Courier Bold} @Font {update}}}} //1.0vx {|0.5f {{{0.7 1.0} @Scale {Courier Bold} @Font {install}}}} //1.0vx {|2f { executable programs, the scripts themselves. }} //1.0vx {|0.5f {{{0.7 1.0} @Scale {Courier Bold} @Font {desc.{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {option}}}}}}}} //1.0vx {|2f { description file. }} //0.2fe @LP {{0.7 1.0} @Scale {Courier Bold} @Font {names}} will be formatted as a list of lines, each containing: //1.0vx {@RawIndentedDisplay lines @Break { {0.7 1.0} @Scale {Courier Bold} @Font { {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {sequence}}}} {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {method}}}} {{1.4285714285 1.0} @Scale {{{Times Slope} @Font {summary}}}}}}} //0.2fe @LP {{Times Slope} @Font {sequence}} is a "two-digit" number that will be used much like {{0.7 1.0} @Scale {Courier Bold} @Font {rc.d}} prefixes to control the order in the main menu. If in doubt use 50. @LP {{Times Slope} @Font {method}} is a name which is displayed by {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}} as the name of the method, and which will be passed to {{0.7 1.0} @Scale {Courier Bold} @Font {setup}}, {{0.7 1.0} @Scale {Courier Bold} @Font {update}} and {{0.7 1.0} @Scale {Courier Bold} @Font {unpack}} as their first argument. @LP {{Times Slope} @Font {summary}} is the brief description string for {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}}'s menu. @LP Each of the three scripts gets the same three arguments: {{Times Slope} @Font {vardir}}, {{Times Slope} @Font {group}} and {{Times Slope} @Font {method}}. {{Times Slope} @Font {vardir}} is the base directory for storing {{0.7 1.0} @Scale {Courier Bold} @Font {dpkg}} and {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}}'s state, usually {{0.7 1.0} @Scale {Courier Bold} @Font {"/var/lib/dpkg"}}; this is passed in so that the {{0.7 1.0} @Scale {Courier Bold} @Font {""--""--"admindir"}} option to {{0.7 1.0} @Scale {Courier Bold} @Font {dselect}} is honoured). @LP Each option may have an extended description in {{0.7 1.0} @Scale {Courier Bold} @Font {desc.{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {option}}}}}}. This should be formatted like the extended description part of a {{0.7 1.0} @Scale {Courier Bold} @Font {Description}} field entry {{Times Slope} @Font {shifted one character to the left}}. @LP {{0.7 1.0} @Scale {Courier Bold} @Font {{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {vardir}}}}"/methods"}} will exist, and a method group may use a {{0.7 1.0} @Scale {Courier Bold} @Font {{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {vardir}}}}"/methods/"{{1.4285714285 1.0} @Scale {{{Times Slope} @Font {group}}}}}} directory to store its state. @LP The group name and method name must follow the rules for C identifiers. @End @Text