dpkg/doc/programmer.lout

@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 {<unknown>}} (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