Julian's versions

[debian/debian-policy.git] / packaging.sgml

<!doctype debiandoc system[
<!-- include version information so we don't have to hard code it
     within the document -->
<!entity % versiondata SYSTEM "version.ent"> %versiondata;
]>

<!--
 Debian GNU/Linux Packaging Manual.
 Copyright (C)1996 Ian Jackson; released under the terms of the GNU
 General Public License, version 2 or (at your option) any later.
 Revised: David A. Morris (bweaver@debian.org)
 Maintainer since 1998, Christian Schwarz <schwarz@debian.org>
 -->

<debiandoc>
  <book>

    <titlepag><title>Debian Packaging Manual</title>
      <author>
        <name>Ian Jackson </name>
        <email>ijackson@gnu.ai.mit.edu</email>
      </author>
      <author>
        <name>Revised: David A. Morris</name>
        <email>bweaver@debian.org</email>
      </author>
      <author>
        <name>Maintainer: Christian Schwarz </name>
        <email>schwarz@debian.org</email>
      </author>
      <author>
        <name>Maintainer: Manoj Srivastava </name>
        <email>srivasta@debian.org</email>
      </author>
      <author>
        <name>Maintainer: The Debian Policy group </name>
        <email>debian-policy@lists.debian.org</email>
      </author>
      <version>version &version;, &date;</version>
        
      <abstract>
        This manual describes the technical aspects of creating Debian
        binary and source packages.  It also documents the interface
        between <prgn>dselect</prgn> and its access method scripts.
        It does not deal with the Debian Project policy requirements,
        and it assumes familiarity with <prgn>dpkg</prgn>'s functions
        from the system administrator's perspective.  This
        package itself is maintained by a group of maintainers
        that have no editorial powers. At the moment, the list of
        maintainers is:
        <enumlist>
          <item>
            <p>Michael Alan Dorman <email>mdorman@debian.org</email></p>
          </item>
          <item>
            <p>Richard Braakman <email>dark@xs4all.nl</email></p>
          </item>
          <item>
            <p>Philip Hands <email>phil@hands.com</email></p>
          </item>
          <item>
            <p>Manoj Srivastava <email>srivasta@debian.org</email></p>
          </item>
        </enumlist>
      </abstract>


      <copyright>
        <copyrightsummary>Copyright &copy;1996 Ian Jackson.</copyrightsummary>
        <p>
          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.
        </p>

        <p>
          This is distributed in the hope that it will be useful, but
          <em>without any warranty</em>; without even the implied
          warranty of merchantability or fitness for a particular
          purpose.  See the GNU General Public License for more
          details.
          </p>

        <p>
          A copy of the GNU General Public License is available as
          <tt>/usr/doc/copyright/GPL</tt> in the Debian GNU/Linux
          distribution or on the World Wide Web at
          <tt>http://www.gnu.org/copyleft/gpl.html</tt>. You can also
          obtain it by writing to the Free Software Foundation, Inc.,
          59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
        </p>
      </copyright>

    <toc detail="sect">

    <!-- Describes the technical interface between a package and dpkg.

    How to safely put shared libraries in a package.  Details of
    dpkg's handling of individual files.  Sections on when to use
    which feature (eg Replaces vs. Replaces/Conflicts
    vs. update-alternatives vs. diversions) Cross-references to the
    policy document (see below) where appropriate.  Description of the
    interface between dselect and its access methods.  Hints on where
    to start with a new package (ie, the hello package).  What to do
    about file aliasing.
    
    file aliasing
    
    Manpages are required for: update-rc.d, diversions,
    update-alternatives, install-info in a package.

    -->

    <chapt id="scope">
      <heading>Introduction and scope of this manual</heading>

      <p>
        <prgn>dpkg</prgn> is a suite of programs for creating binary
        package files and installing and removing them on Unix
        systems.<footnote>
          <p>
            <prgn>dpkg</prgn> is targetted primarily at Debian
            GNU/Linux, but may work on or be ported to other
            systems.
          </p>
        </footnote>
      </p>

      <p>
        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.</p>

      <p>
        This manual describes the technical aspects of creating Debian
        binary packages (<tt>.deb</tt> files).  It documents the
        behaviour of the package management programs
        <prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and the way
        they interact with packages.</p>

      <p>
        It also documents the interaction between
        <prgn>dselect</prgn>'s core and the access method scripts it
        uses to actually install the selected packages, and describes
        how to create a new access method.</p>
        
      <p>
        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.
      </p>      

      <p>
        The utility programs which are provided with <prgn>dpkg</prgn>
        for managing various system configuration and similar issues,
        such as <prgn>update-rc.d</prgn> and
        <prgn>install-info</prgn>, are not described in detail here -
        please see their manpages.
      </p>
        
      <p>
        It does <em>not</em> 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.)
      </p>
        
      <p>
        It is assumed that the reader is reasonably familiar with the
        <prgn>dpkg</prgn> System Administrators' manual.
        Unfortunately this manual does not yet exist.
      </p>
        
      <p>
        The Debian version of the FSF's GNU hello program is provided
        as an example for people wishing to create Debian
        packages. The Debian <prgn>debmake</prgn> package is
        recommended as a very helpful tool in creating and maintaining
        Debian packages. However, while the tools and examples are
        helpful, they do not replace the need to read and follow the
        Policy and Programmer's Manual.</p>
    </chapt>
      
    <chapt id="binarypkg"><heading>Binary packages
      </heading>
        
      <p>
        The binary package has two main sections.  The first part
        consists of various control information files and scripts used
        by <prgn>dpkg</prgn> when installing and removing.  See <ref
        id="controlarea">.
      </p>
        
      <p>
        The second part is an archive containing the files and
        directories to be installed.
      </p>
        
      <p>
        In the future binary packages may also contain other
        components, such as checksums and digital signatures. The
        format for the archive is described in full in the
        <tt>deb(5)</tt> manpage.
      </p>
        
        
      <sect id="bincreating"><heading>Creating package files -
      <prgn>dpkg-deb</prgn>
        </heading>
          
        <p>
          All manipulation of binary package files is done by
          <prgn>dpkg-deb</prgn>; it's the only program that has
          knowledge of the format.  (<prgn>dpkg-deb</prgn> may be
          invoked by calling <prgn>dpkg</prgn>, as <prgn>dpkg</prgn>
          will spot that the options requested are appropriate to
          <prgn>dpkg-deb</prgn> and invoke that instead with the same
          arguments.)
        </p>
          
        <p>
          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
          <tt>debian/tmp</tt>, relative to the top of the package's
          source tree.
        </p>
          
        <p>
          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.
        </p>
          
        <p>
          With current versions of <prgn>dpkg</prgn> 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.
        </p>
          
        <p>
          You need to add one special directory to the root of the
          miniature filesystem tree you're creating:
          <prgn>DEBIAN</prgn>.  It should contain the control
          information files, notably the binary package control file
          (see <ref id="controlfile">).
        </p>
          
        <p>
          The <prgn>DEBIAN</prgn> directory will not appear in the
          filesystem archive of the package, and so won't be installed
          by <prgn>dpkg</prgn> when the package is installed.
        </p>
          
        <p>
          When you've prepared the package, you should invoke:
          <example>
  dpkg --build <var>directory</var>
          </example>
        </p>
          
        <p>
          This will build the package in
          <tt><var>directory</var>.deb</tt>.  (<prgn>dpkg</prgn> knows
          that <tt>--build</tt> is a <prgn>dpkg-deb</prgn> option, so
          it invokes <prgn>dpkg-deb</prgn> with the same arguments to
          build the package.)
        </p>
          
        <p>
          See the manpage <manref name="dpkg-deb" section="8"> for details of how
          to examine the contents of this newly-created file.  You may find the
          output of following commands enlightening:
          <example>
  dpkg-deb --info <var>filename</var>.deb
  dpkg-deb --contents <var>filename</var>.deb
  dpkg --contents <var>filename</var>.deb
          </example>
          To view the copyright file for a package you could use this command:
          <example>
  dpkg --fsys-tarfile <var>filename</var>.deb | tar xof usr/doc/<var>\*</var>copyright | less
          </example>
        </p>
      </sect>

      <sect id="controlarea">
        <heading>
          Package control information files
        </heading>
          
        <p>
          The control information portion of a binary package is a
          collection of files with names known to <prgn>dpkg</prgn>.
          It will treat the contents of these files specially - some
          of them contain information used by <prgn>dpkg</prgn> when
          installing or removing the package; others are scripts which
          the package maintainer wants <prgn>dpkg</prgn> to run.
        </p>
          
        <p>
          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).
        </p>
          
        <p>
          Here is a brief list of the control info files supported by
          <prgn>dpkg</prgn> and a summary of what they're used for.
        </p>
          
        <p>
          <taglist>
            <tag><tt>control</tt>
            <item>
              
              <p>
                This is the key description file used by
                <prgn>dpkg</prgn>.  It specifies the package's name
                and version, gives its description for the user,
                states its relationships with other packages, and so
                forth.  See <ref id="controlfile">.
              </p>
                
              <p>
                It is usually generated automatically from information
                in the source package by the
                <prgn>dpkg-gencontrol</prgn> program, and with
                assistance from <prgn>dpkg-shlibdeps</prgn>.  See <ref
                id="sourcetools">.</p>
            </item>
              
            <tag><tt>postinst</tt>, <tt>preinst</tt>, <tt>postrm</tt>,
            <tt>prerm</tt>
            </tag>
            <item>
              
              <p>
                These are exectuable files (usually scripts) which
                <prgn>dpkg</prgn> 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 <prgn>dpkg</prgn>.  Details of when and
                how they are called are in <ref
                id="maintainerscripts">.
              </p>
                
              <p>
                It is very important to make these scripts
                idempotent.
                <footnote>
                  <p>
                    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.
                  </p>
                </footnote> This is so that if an error occurs, the
                user interrupts <prgn>dpkg</prgn> or some other
                unforeseen circumstance happens you don't leave the
                user with a badly-broken package.
              </p>
                
              <p>
                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 <tt>/dev/tty</tt>, since
                <prgn>dpkg</prgn> 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 <tt>$|=1</tt> so that the
                output is printed immediately rather than being
                buffered.
              </p>
                
              <p>
                Each script should return a zero exit status for
                success, or a nonzero one for failure.</p>
            </item>
              
            <tag><tt>conffiles</tt>
            </tag>
            <item>
              
              <p>
                This file contains a list of configuration files which
                are to be handled automatically by <prgn>dpkg</prgn>
                (see <ref id="conffiles">).  Note that not necessarily
                every configuration file should be listed here.</p>
            </item>
              
            <tag><tt>shlibs</tt>
            </tag>
            <item>
              
              <p>
                This file contains a list of the shared libraries
                supplied by the package, with dependency details for
                each.  This is used by <prgn>dpkg-shlibdeps</prgn>
                when it determines what dependencies are required in a
                package control file. The <tt>shlibs</tt> file format
                is described on <ref id="shlibs">.
              </p>
            </item>
          </taglist>
        </p>
        
      <sect id="controlfile">
        <heading>
          The main control information file: <tt>control</tt>
        </heading>
        <p>
          The most important control information file used by
          <prgn>dpkg</prgn> when it installs a package is
          <tt>control</tt>.  It contains all the package's `vital
          statistics'.
        </p>

        <p>       
          The binary package control files of packages built from
          Debian sources are made by a special tool,
          <prgn>dpkg-gencontrol</prgn>, which reads
          <tt>debian/control</tt> and <tt>debian/changelog</tt> to
          find the information it needs.  See <ref id="sourcepkg"> for
          more details.
        </p>

        <p>       
          The fields in binary package control files are:
          <list compact="compact">
            <item>
              <p><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</p>
            </item>
            <item>
              <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
            </item>
            <item><p><qref id="f-Architecture"><tt>Architecture</tt></qref>
                (mandatory)
                <footnote>
                  <p>
                    This field should appear in all packages, though
                    <prgn>dpkg</prgn> doesn't require it yet so that
                    old packages can still be installed.
                  </p>
                </footnote>
              </p>
            </item>
            <item>
              <p><qref id="relationships"><tt>Depends</tt>,
                  <tt>Provides</tt> et al.</qref></p>
            </item>
            <item>
              <p><qref id="f-Essential"><tt>Essential</tt></qref></p>
            </item>
            <item>
              <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
            </item>
            <item>
              <p><qref id="f-classification"><tt>Section</tt>,
                  <tt>Priority</tt></qref></p>
            </item>
            <item>
              <p><qref id="f-Source"><tt>Source</tt></qref></p>
            </item>
            <item>
              <p><qref id="descriptions"><tt>Description</tt></qref></p>
            </item>
            <item>
              <p>
                <qref id="f-Installed-Size"><tt>Installed-Size</tt></qref>
              </p>
            </item> 
          </list>
            
        <p>
          A description of the syntax of control files and the purpose
          of these fields is available in <ref id="controlfields">.
        </p>
      </sect>
      <sect>
        <heading>Time Stamps</heading>
        <p>
          Maintainers are encouraged to preserve the modification
          times of the upstream source files in a package, as far as
          is reasonably possible. 
          <footnote>
            <p>
              The rationale is that there is some information conveyed
              by knowing the age of the file, for example, you could
              recognize that some documentation is very old by looking
              at the modification time, so it would be nice if the
              modification time of the upstream source would be
              preserved.
            </p>
          </footnote>
        </p>
      </sect>
      
    <chapt id="sourcepkg">
      <heading>Source packages</heading>

      <p>       
        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.
      </p>

      <p>       
        There was a previous version of the Debian source format,
        which is now being phased out.  Instructions for converting an
        old-style package are given in the Debian policy manual.
      </p>
        
      <sect id="sourcetools">
        <heading>Tools for processing source packages</heading> 

        <p>       
          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.
        </p>

        <p>       
          They are introduced and typical uses described here; see
          <manref name="dpkg-source" section="1"> for full
          documentation about their arguments and operation.
        </p>

        <p>       
          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 <prgn>hello</prgn> example
          package.
        </p>
          
        <sect1>
          <heading>
            <prgn>dpkg-source</prgn> - packs and unpacks Debian source
            packages
          </heading>

          <p>       
            This program is frequently used by hand, and is also
            called from package-independent automated building scripts
            such as <prgn>dpkg-buildpackage</prgn>.
          </p>

          <p>       
            To unpack a package it is typically invoked with
            <example>
  dpkg-source -x <var>.../path/to/filename</var>.dsc
            </example> 
          </p>

           <p>  
            with the <tt><var>filename</var>.tar.gz</tt> and
            <tt><var>filename</var>.diff.gz</tt> (if applicable) in
            the same directory.  It unpacks into
            <tt><var>package</var>-<var>version</var></tt>, and if
            applicable
            <tt><var>package</var>-<var>version</var>.orig</tt>, in
            the current directory.
          </p>

          <p>       
            To create a packed source archive it is typically invoked:
            <example>
  dpkg-source -b <var>package</var>-<var>version</var>
          </example>
          </p>

          <p>
            This will create the <tt>.dsc</tt>, <tt>.tar.gz</tt> and
            <tt>.diff.gz</tt> (if appropriate) in the current
            directory.  <prgn>dpkg-source</prgn> does not clean the
            source tree first - this must be done separately if it is
            required.
          </p>

          <p>       
            See also <ref id="sourcearchives">.</p>
        </sect1>
          
          
        <sect1>
          <heading>
            <prgn>dpkg-buildpackage</prgn> - overall package-building
            control script
          </heading>

          <p>       
            <prgn>dpkg-buildpackage</prgn> is a script which invokes
            <prgn>dpkg-source</prgn>, the <tt>debian/rules</tt>
            targets <prgn>clean</prgn>, <prgn>build</prgn> and
            <prgn>binary</prgn>, <prgn>dpkg-genchanges</prgn> and
            <prgn>pgp</prgn> to build a signed source and binary
            package upload.
          </p>

          <p>       
            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:
            <taglist compact="compact">
              <tag><tt>-uc</tt>, <tt>-us</tt></tag>
              <item>
                <p>
                  Do not PGP-sign the <tt>.changes</tt> file or the
                  source package <tt>.dsc</tt> file, respectively.</p>
              </item>
              <tag><tt>-p<var>pgp-command</var></tt></tag>
              <item>
                <p>
                  Invoke <var>pgp-command</var> instead of finding
                  <tt>pgp</tt> on the <prgn>PATH</prgn>.
                  <var>pgp-command</var> must behave just like
                  <prgn>pgp</prgn>.</p>
              </item>
              <tag><tt>-r<var>root-command</var></tt></tag>
              <item>
                <p>
                  When root privilege is required, invoke the command
                  <var>root-command</var>.  <var>root-command</var>
                  should invoke its first argument as a command, from
                  the <prgn>PATH</prgn> if necessary, and pass its
                  second and subsequent arguments to the command it
                  calls.  If no <var>root-command</var> is supplied
                  then <var>dpkg-buildpackage</var> 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.</p>
              </item>
              <tag><tt>-b</tt>, <tt>-B</tt></tag>
              <item>
                <p>
                  Two types of binary-only build and upload - see
                  <manref name="dpkg-source" section="1">.
                </p>
              </item>
            </taglist>
          </p>
        </sect1>
          
        <sect1>
          <heading>
            <prgn>dpkg-gencontrol</prgn> - generates binary package
            control files
          </heading>

          <p>       
            This program is usually called from <tt>debian/rules</tt>
            (see <ref id="sourcetree">) in the top level of the source
            tree.
          </p>

          <p>       
            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
            <prgn>dpkg-deb/</prgn>
              <footnote>
              <p>
                This is so that the control file which is produced has
                the right permissions
              </p>
            </footnote>.
          </p>

          <p>       
            <prgn>dpkg-gencontrol</prgn> 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.
          </p>

          <p>       
            It is also necessary for <prgn>dpkg-gencontrol</prgn> to
            be run after <prgn>dpkg-shlibdeps</prgn> so that the
            variable substitutions created by
            <prgn>dpkg-shlibdeps</prgn> in <tt>debian/substvars</tt>
            are available.
          </p>

          <p>       
            For a package which generates only one binary package, and
            which builds it in <tt>debian/tmp</tt> relative to the top
            of the source package, it is usually sufficient to call
            <prgn>dpkg-gencontrol</prgn>.
          </p>

          <p>       
            Sources which build several binaries will typically need
            something like:
            <example>
  dpkg-gencontrol -Pdebian/tmp-<var>pkg</var> -p<var>package</var>
            </example> The <tt>-P</tt> tells
            <prgn>dpkg-gencontrol</prgn> that the package is being
            built in a non-default directory, and the <tt>-p</tt>
            tells it which package's control file should be generated.
          </p>

          <p>       
            <prgn>dpkg-gencontrol</prgn> also adds information to the
            list of files in <tt>debian/files</tt>, for the benefit of
            (for example) a future invocation of
            <prgn>dpkg-genchanges</prgn>.</p>
        </sect1>
          
        <sect1>
          <heading>
            <prgn>dpkg-shlibdeps</prgn> - calculates shared library
            dependencies
          </heading>

          <p>       
            This program is usually called from <tt>debian/rules</tt>
            just before <prgn>dpkg-gencontrol</prgn> (see <ref
            id="sourcetree">), in the top level of the source tree.
          </p>

          <p>       
            Its arguments are executables
            <footnote>
              <p>
                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.
              </p>
            </footnote> for which shared library dependencies should
            be included in the binary package's control file.
          </p>

          <p>       
            If some of the executable(s) shared libraries should only
            warrant a <tt>Recommends</tt> or <tt>Suggests</tt>, or if
            some warrant a <tt>Pre-Depends</tt>, this can be achieved
            by using the <tt>-d<var>dependency-field</var></tt> option
            before those executable(s).  (Each <tt>-d</tt> option
            takes effect until the next <tt>-d</tt>.)
          </p>

          <p>       
            <prgn>dpkg-shlibdeps</prgn> does not directly cause the
            output control file to be modified.  Instead by default it
            adds to the <tt>debian/substvars</tt> file variable
            settings like <tt>shlibs:Depends</tt>.  These variable
            settings must be referenced in dependency fields in the
            appropriate per-binary-package sections of the source
            control file.
          </p>

          <p>       
            For example, the <prgn>procps</prgn> package generates two
            kinds of binaries, simple C binaries like <prgn>ps</prgn>
            which require a predependency and full-screen ncurses
            binaries like <prgn>top</prgn> which require only a
            recommendation.  It can say in its <tt>debian/rules</tt>:
            <example>
  dpkg-shlibdeps -dPre-Depends ps -dRecommends top
            </example>
            and then in its main control file <tt>debian/control</tt>:
            <example>
  <var>...</var>
  Package: procps
  Pre-Depends: ${shlibs:Pre-Depends}
  Recommends: ${shlibs:Recommends}
  <var>...</var>
            </example>
          </p>

          <p>       
            Sources which produce several binary packages with
            different shared library dependency requirements can use
            the <tt>-p<var>varnameprefix</var></tt> option to override
            the default <tt>shlib:</tt> prefix (one invocation of
            <prgn>dpkg-shlibdeps</prgn> per setting of this option).
            They can thus produce several sets of dependency
            variables, each of the form
            <tt><var>varnameprefix</var>:<var>dependencyfield</var></tt>,
            which can be referred to in the appropriate parts of the
            binary package control files.
          </p>
        </sect1>
          
          
        <sect1>
          <heading>
            <prgn>dpkg-distaddfile</prgn> - adds a file to
            <tt>debian/files</tt>
          </heading>

          <p>       
            Some packages' uploads need to include files other than
            the source and binary package files.
          </p>

          <p>       
            <prgn>dpkg-distaddfile</prgn> adds a file to the
            <tt>debian/files</tt> file so that it will be included in
            the <tt>.changes</tt> file when
            <prgn>dpkg-genchanges</prgn> is run.
          </p>

          <p>       
            It is usually invoked from the <prgn>binary</prgn> target of
            <tt>debian/rules</tt>:
            <example>
  dpkg-distaddfile <var>filename</var> <var>section</var> <var>priority</var>
            </example>
            The <var>filename</var> is relative to the directory where
            <prgn>dpkg-genchanges</prgn> will expect to find it - this
            is usually the directory above the top level of the source
            tree.  The <tt>debian/rules</tt> target should put the
            file there just before or just after calling
            <prgn>dpkg-distaddfile</prgn>.
          </p>

          <p>       
            The <var>section</var> and <var>priority</var> are passed
            unchanged into the resulting <tt>.changes</tt> file.  See
            <ref id="f-classification">.
          </p>
        </sect1>
          
          
        <sect1><heading><prgn>dpkg-genchanges</prgn> - generates a <tt>.changes</tt> upload
            control file
          </heading>

          <p>       
            This program is usually called by package-independent
            automatic building scripts such as
            <prgn>dpkg-buildpackage</prgn>, but it may also be called
            by hand.
          </p>

          <p>       
            It is usually called in the top level of a built source
            tree, and when invoked with no arguments will print out a
            straightforward <tt>.changes</tt> 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.
          </p>
        </sect1>
          
          
        <sect1><heading><prgn>dpkg-parsechangelog</prgn> - produces parsed representation of
            a changelog
          </heading>

          <p>       
            This program is used internally by
            <prgn>dpkg-source</prgn> et al.  It may also occasionally
            be useful in <tt>debian/rules</tt> and elsewhere.  It
            parses a changelog, <tt>debian/changelog</tt> by default,
            and prints a control-file format representation of the
            information in it to standard output.
          </p>
        </sect1>
 
        <sect1 id="dpkgarch"><heading><prgn>dpkg-architecture</prgn> -
            information about the build and host system 
          </heading>
 
          <p>
            This program can be used manually, but is also invoked by
            <tt>dpkg-buildpackage</tt> or <tt>debian/rules</tt> to set
            to set environment or make variables which specify the build and
            host architecture for the package building process.
          </p>
        </sect1>
      </sect>
        
      <sect id="sourcetree"><heading>The Debianised source tree
        </heading>

        <p>       
          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.
        </p>

        <p>       
          The extra files created for Debian are in the subdirectory
          <tt>debian</tt> of the top level of the Debianised source
          tree.  They are described below.
        </p>
          
        <sect1 id="debianrules"><heading><tt>debian/rules</tt> - the main building
        script
          </heading>

          <p>       
            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.
          </p>

          <p>       
            It must start with the line <tt>#!/usr/bin/make -f</tt>,
            so that it can be invoked by saying its name rather than
            invoking <prgn>make</prgn> explicitly.
          </p>

          <p>
            Since an interactive <tt>debian/rules</tt> script makes it
            impossible to autocompile that package and also makes it
            hard for other people to reproduce the same binary
            package, all <strong>required targets</strong> have to be
            non-interactive. At a minimul, required targets are the
            ones called by <prgn>dpkg-buildpackage</prgn>, namely,
            <em>clean</em>, <em>binary</em>, <em>binary-arch</em>, and
            <em>build</em>. It also follows that any target that these
            targets depend on must also be non-interactive.
          </p>

          <p>       
            The targets which are required to be present are:       
            <taglist>
              <tag><tt>build</tt></tag>
              <item>
                <p>
                  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.
                </p>

                <p>               
                  For some packages, notably ones where the same
                  source tree is compiled in different ways to produce
                  two binary packages, the <prgn>build</prgn> target
                  does not make much sense.  For these packages it is
                  good enough to provide two (or more) targets
                  (<tt>build-a</tt> and <tt>build-b</tt> or whatever)
                  for each of the ways of building the package, and a
                  <prgn>build</prgn> target that does nothing.  The
                  <prgn>binary</prgn> target will have to build the
                  package in each of the possible ways and make the
                  binary package out of each.
                </p>

                <p>               
                  The <prgn>build</prgn> target must not do anything
                  that might require root privilege.
                </p>

                <p>               
                  The <prgn>build</prgn> target may need to run
                  <prgn>clean</prgn> first - see below.
                </p>

                <p>               
                  When a package has a configuration routine that
                  takes a long time, or when the makefiles are poorly
                  designed, or when <prgn>build</prgn> needs to run
                  <prgn>clean</prgn> first, it is a good idea to
                  <tt>touch build</tt> when the build process is
                  complete.  This will ensure that if <tt>debian/rules
                    build</tt> is run again it will not rebuild the
                    whole program.
                </p>
              </item>
                
              <tag><tt>binary</tt>, <tt>binary-arch</tt>,
                <tt>binary-indep</tt>
              </tag> 
              <item>
                <p>
                  The <prgn>binary</prgn> target should be all that is
                  necessary for the user to build the binary
                  package. All these targets are required to be
                  non-interactive.  It is split into two parts:
                  <prgn>binary-arch</prgn> builds the packages' output
                  files which are specific to a particular
                  architecture, and <prgn>binary-indep</prgn> builds
                  those which are not.
                </p>

                <p>               
                  <prgn>binary</prgn> should usually be a target with
                  no commands which simply depends on
                  <prgn>binary-arch</prgn> and
                  <prgn>binary-indep</prgn>.
                </p>

                <p>               
                  Both <prgn>binary-*</prgn> targets should depend on
                  the <prgn>build</prgn> target, above, so that the
                  package is built if it has not been already.  It
                  should then create the relevant binary package(s),
                  using <prgn>dpkg-gencontrol</prgn> to make their
                  control files and <prgn>dpkg-deb</prgn> to build
                  them and place them in the parent of the top level
                  directory.
                </p>

                <p>               
                  If one of the <prgn>binary-*</prgn> 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
                  <em>must</em> still exist, but should always
                  succeed.
                </p>

                <p>               
                  <ref id="binarypkg"> describes how to construct
                  binary packages.
                </p>

                <p>               
                  The <prgn>binary</prgn> targets must be invoked as
                  root.
                </p>
              </item>
                
              <tag><tt>clean</tt></tag>
              <item>
                
                <p>
                  This should undo any effects that the
                  <prgn>build</prgn> and <prgn>binary</prgn> targets
                  may have had, except that it should leave alone any
                  output files created in the parent directory by a
                  run of <prgn>binary</prgn>. This target is required
                  to be non-interactive.
                </p>

                <p>               
                  If a <prgn>build</prgn> file is touched at the end
                  of the <prgn>build</prgn> target, as suggested
                  above, it must be removed as the first thing that
                  <prgn>clean</prgn> does, so that running
                  <prgn>build</prgn> again after an interrupted
                  <prgn>clean</prgn> doesn't think that everything is
                  already done.
                </p>

                <p>               
                  The <prgn>clean</prgn> target must be invoked as
                  root if <prgn>binary</prgn> has been invoked since
                  the last <prgn>clean</prgn>, or if
                  <prgn>build</prgn> has been invoked as root (since
                  <prgn>build</prgn> may create directories, for
                  example).
                </p>
              </item>
                
              <tag><tt>get-orig-source</tt> (optional)</tag>
              <item>
                
                <p>
                  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.
                </p>

                <p>               
                  This target may be invoked in any directory, and
                  should take care to clean up any temporary files it
                  may have left.
                </p>

                <p>               
                  This target is optional, but providing it if
                  possible is a good idea.
                </p>
              </item>
            </taglist>
              
          <p>
            The <prgn>build</prgn>, <prgn>binary</prgn> and
            <prgn>clean</prgn> targets must be invoked with a current
            directory of the package's top-level directory.
          </p>
            

          <p>       
            Additional targets may exist in <tt>debian/rules</tt>,
            either as published or undocumented interfaces or for the
            package's internal use.
          </p>
 
          <p>
            The architecture we build on and build for is determined by make
            variables via dpkg-architecture (see <ref id="dpkgarch">). You can
            get the Debian architecture and the GNU style architecture
            specification string for the build machine as well as the host
            machine. Here is a list of supported make variables:
            <list compact="compact">
              <item>
                <p><tt>DEB_*_ARCH</tt> (the Debian architecture)</p>
              </item>
              <item>
                <p><tt>DEB_*_GNU_TYPE</tt> (the GNU style architecture
                  specification string)</p> 
              </item>
              <item>
                <p><tt>DEB_*_GNU_CPU</tt> (the CPU part of DEB_*_GNU_TYPE)</p>
              </item>
              <item>
                <p><tt>DEB_*_GNU_SYSTEM</tt> (the System part of
                  DEB_*_GNU_TYPE)</p>
            </list>
          </p>
 
          <p>
            where <tt>*</tt> is either <tt>BUILD</tt> for specification of
            the build machine or <tt>HOST</tt> for specification of the machine
            we build for.
          </p>
          
          <p>
            Backward compatibility can be provided in the rules file
            by setting the needed variables to suitable default
            values, please refer to the documentation of
            dpkg-architecture for details.
          </p>
 
          <p>
            It is important to understand that the <tt>DEB_*_ARCH</tt>
            string does only determine which Debian architecture we
            build on resp. for. It should not be used to get the CPU
            or System information, the GNU style variables should be
            used for that.
          </p>
        </sect1>
          
          
        <sect1><heading><tt>debian/control</tt>
          </heading>

          <p>       
            This file contains version-independent details about the
            source package and about the binary packages it creates.
          </p>

          <p>       
            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.
          </p>

          <p>       
            The syntax and semantics of the fields are described below
            in <ref id="controlfields">.
          </p>

          <p>       
            The general (binary-package-independent) fields are:
            <list compact="compact">
              <item>
                <p><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</p>
              </item>
              <item>
                <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
              </item>
              <item>
                <p>
                  <qref id="f-classification"><tt>Section</tt> and
                    <tt>Priority</tt></qref> 
                  (classification, mandatory)
                </p>
              </item>
               <item>
                 <p>
                   <qref id="relationships"><tt>Build-Depends</tt> et
                     al.</qref> (source package interrelationships)
                 </p>
               </item>
              <item>
                <p>
                  <qref id="f-Standards-Version"><tt>Standards-Version</tt></qref>
                </p>
              </item> 
            </list>

          <p>       
            The per-binary-package fields are:
            <list compact="compact">
              <item>
                <p><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</p>
              </item>
              <item>
                <p>
                  <qref id="f-Architecture"><tt>Architecture</tt></qref>
                  (mandatory)</p>
              </item>
              <item>
                <p><qref id="descriptions"><tt>Description</tt></qref></p>
              </item>
              <item>
                <p>
                  <qref id="f-classification"><tt>Section</tt> and
                    <tt>Priority</tt></qref> (classification)</p>
              </item>
              <item>
                <p><qref id="f-Essential"><tt>Essential</tt></qref></p>
              </item>
              <item>
                <p>
                  <qref id="relationships"><tt>Depends</tt> et
                  al.</qref> (binary package interrelationships)
                </p>
              </item>
            </list>

          <p>       
            These fields are used by <prgn>dpkg-gencontrol</prgn> to
            generate control files for binary packages (see below), by
            <prgn>dpkg-genchanges</prgn> to generate the
            <tt>.changes</tt> file to accompany the upload, and by
            <prgn>dpkg-source</prgn> when it creates the <tt>.dsc</tt>
            source control file as part of a source archive.
          </p>

          <p>       
            The fields here may contain variable references - their
            values will be substituted by
            <prgn>dpkg-gencontrol</prgn>, <prgn>dpkg-genchanges</prgn>
            or <prgn>dpkg-source</prgn> when they generate output
            control files.  See <ref id="srcsubstvars"> for details.
          </p>

          <p> <sect2><heading>User-defined fields
            </heading>

            <p>       
              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.
            </p>

            <p>       
              If you wish to add additional unsupported fields to
              these output files you should use the mechanism
              described here.
            </p>

            <p>       
              Fields in the main source control information file with
              names starting <tt>X</tt>, followed by one or more of
              the letters <tt>BCS</tt> and a hyphen <tt>-</tt>, 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 <tt>B</tt> is used the field
              will appear in binary package control files, where the
              letter <tt>S</tt> is used in source package control
              files and where <tt>C</tt> is used in upload control
              (<tt>.changes</tt>) files.
            </p>

            <p>       
              For example, if the main source information control file
              contains the field
              <example>
  XBS-Comment: I stand between the candle and the star.
              </example>
              then the binary and source package control files will contain the
              field
              <example>
  Comment: I stand between the candle and the star.
              </example>
            </p>
          </sect2>
        
        </sect1>

        <sect1 id="dpkgchangelog"><heading><tt>debian/changelog</tt>
          </heading>

          <p>       
            This file records the changes to the Debian-specific parts of the
            package
            <footnote>
              <p>
                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.
              </p>
            </footnote>.
          </p>

          <p>       
            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.
          </p>

          <p>
            That format is a series of entries like this:       
            <example>
  <var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>

   * <var>change details</var>
   <var>more change details</var>
   * <var>even more change details</var>
              
  -- <var>maintainer name and email address</var>  <var>date</var>
            </example>
          </p>

          <p>       
            <var>package</var> and <var>version</var> are the source
            package name and version number.
          </p> 

          <p>       
            <var>distribution(s)</var> lists the distributions where
            this version should be installed when it is uploaded - it
            is copied to the <tt>Distribution</tt> field in the
            <tt>.changes</tt> file.  See <ref id="f-Distribution">.
          </p>

          <p>       
            <var>urgency</var> is the value for the <tt>Urgency</tt>
            field in the <tt>.changes</tt> file for the upload.  See
            <ref id="f-Urgency">.  It is not possible to specify an
            urgency containing commas; commas are used to separate
            <tt><var>keyword</var>=<var>value</var></tt> settings in
            the <prgn>dpkg</prgn> changelog format (though there is
            currently only one useful <var>keyword</var>,
            <tt>urgency</tt>).
          </p>

          <p>       
            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.
          </p>

          <p>       
            The maintainer name and email address should <em>not</em>
            necessarily be those of the usual package maintainer.
            They should be the details of the person doing
            <em>this</em> version.  The information here will be
            copied to the <tt>.changes</tt> file, and then later used
            to send an acknowledgement when the upload has been
            installed.
          </p>

          <p>       
            The <var>date</var> should be in RFC822 format
            <footnote>
              <p>
                This is generated by the <prgn>822-date</prgn>
                program.
              </p>
            </footnote>; it should include the timezone specified
            numerically, with the timezone name or abbreviation
            optionally present as a comment.
          </p>

          <p>       
            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.
          </p>

          <p>       
            An Emacs mode for editing this format is available: it is
            called <tt>debian-changelog-mode</tt>.  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.
          </p>
            
          <sect2><heading>Defining alternative changelog formats
            </heading>

            <p>       
              It is possible to use a different format to the standard
              one, by providing a parser for the format you wish to
              use.
            </p>

            <p>       
              In order to have <tt>dpkg-parsechangelog</tt> run your
              parser, you must include a line within the last 40 lines
              of your file matching the Perl regular expression:
              <tt>\schangelog-format:\s+([0-9a-z]+)\W</tt> The part in
              parentheses should be the name of the format.  For
              example, you might say:
              <example>
  @@@ changelog-format: joebloggs @@@
              </example>
              Changelog format names are non-empty strings of alphanumerics.
            </p>

            <p>       
              If such a line exists then <tt>dpkg-parsechangelog</tt>
              will look for the parser as
              <tt>/usr/lib/dpkg/parsechangelog/<var>format-name</var></tt>
              or
              <tt>/usr/local/lib/dpkg/parsechangelog/<var>format-name</var></tt>;
              it is an error for it not to find it, or for it not to
              be an executable program.  The default changelog format
              is <tt>dpkg</tt>, and a parser for it is provided with
              the <tt>dpkg</tt> package.
            </p>

            <p>       
              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
              <tt>-v<var>version</var></tt> option to return changes
              information from all versions present <em>strictly
              after</em> <var>version</var>, and it should then be an
              error for <var>version</var> not to be present in the
              changelog.
            </p>

            <p>       
              The fields are:
              <list compact="compact">
                <item>
                  <p><qref id="f-Source"><tt>Source</tt></qref></p>
                </item>
                <item>
                  <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
                </item>
                <item>
                  <p>
                    <qref id="f-Distribution"><tt>Distribution</tt></qref>
                    (mandatory)
                  </p> 
                </item>
                <item>
                  <p><qref id="f-Urgency"><tt>Urgency</tt></qref> (mandatory)</p>
                </item>
                <item>
                  <p>
                    <qref id="f-Maintainer"><tt>Maintainer</tt></qref>
                    (mandatory)
                  </p>
                </item>
                <item>
                  <p><qref id="f-Date"><tt>Date</tt></qref></p>
                </item>
                <item>
                  <p>
                    <qref id="f-Changes"><tt>Changes</tt></qref>
                    (mandatory)
                  </p>
                </item>
              </list>

            <p>       
              If several versions are being returned (due to the use
              of <tt>-v</tt>), 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.
            </p>

            <p>       
              For the format of the <tt>Changes</tt> field see <ref
              id="f-Changes">.
            </p>

            <p>       
              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.
            </p>

            <p>       
              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.
            </p>

            <p>       
              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.
            </p>

            <p>       
              A changelog parser may not interact with the user at
              all.</p></sect2>
        </sect1>
          
        <sect1 id="srcsubstvars"><heading><tt>debian/substvars</tt>
        and variable substitutions
          </heading>

          <p>       
            When <prgn>dpkg-gencontrol</prgn>,
            <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
            generate control files they do variable substitutions on
            their output just before writing it.  Variable
            substitutions have the form
            <tt>${<var>variable-name</var>}</tt>.  The optional file
            <tt>debian/substvars</tt> contains variable substitutions
            to be used; variables can also be set directly from
            <tt>debian/rules</tt> using the <tt>-V</tt> option to the
            source packaging commands, and certain predefined
            variables are available.
          </p>

          <p>       
            The is usually generated and modified dynamically by
            <tt>debian/rules</tt> targets; in this case it must be
            removed by the <prgn>clean</prgn> target.
          </p>

          <p>
            See <manref name="dpkg-source" section="1"> for full
            details about source variable substitutions, including the
            format of <tt>debian/substvars</tt>.</p>
        </sect1>
          
        <sect1><heading><tt>debian/files</tt>
          </heading>

          <p>       
            This file is not a permanent part of the source tree; it
            is used while building packages to record which files are
            being generated.  <prgn>dpkg-genchanges</prgn> uses it
            when it generates a <tt>.changes</tt> file.
          </p>

          <p>       
            It should not exist in a shipped source package, and so it
            (and any backup files or temporary files such as
            <tt>files.new</tt>
              <footnote>
                <p>
                  <tt>files.new</tt> is used as a temporary file by
                  <prgn>dpkg-gencontrol</prgn> and
                  <prgn>dpkg-distaddfile</prgn> - they write a new
                  version of <tt>files</tt> here before renaming it,
                  to avoid leaving a corrupted copy if an error
                  occurs
                </p>
              </footnote>) should be removed by the
              <prgn>clean</prgn> target.  It may also be wise to
              ensure a fresh start by emptying or removing it at the
              start of the <prgn>binary</prgn> target.
          </p>

          <p>       
            <prgn>dpkg-gencontrol</prgn> adds an entry to this file
            for the <tt>.deb</tt> file that will be created by
            <prgn>dpkg-deb</prgn> 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 <prgn>clean</prgn>.
          </p>

          <p>       
            If a package upload includes files besides the source
            package and any binary packages whose control files were
            made with <prgn>dpkg-gencontrol</prgn> then they should be
            placed in the parent of the package's top-level directory
            and <prgn>dpkg-distaddfile</prgn> should be called to add
            the file to the list in <tt>debian/files</tt>.</p>
        </sect1>
          
        <sect1><heading><tt>debian/tmp</tt>
          </heading>

          <p>       
            This is the canonical temporary location for the
            construction of binary packages by the <prgn>binary</prgn>
            target.  The directory <tt>tmp</tt> 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 <tt>DEBIAN</tt> subdirectory.  See <ref
            id="bincreating">.
          </p>

          <p>       
            If several binary packages are generated from the same
            source tree it is usual to use several
            <tt>debian/tmp<var>something</var></tt> directories, for
            example <tt>tmp-a</tt> or <tt>tmp-doc</tt>.
          </p>

          <p>       
            Whatever <tt>tmp</tt> directories are created and used by
            <prgn>binary</prgn> must of course be removed by the
            <prgn>clean</prgn> target.</p></sect1>
      </sect>
        
        
      <sect id="sourcearchives"><heading>Source packages as archives
        </heading>

        <p>       
          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.
        </p>

        <p>       
          <taglist>
            <tag>Debian source control file - <tt>.dsc</tt></tag>
            <item>
              
              <p>
                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 <ref id="controlfields">.
                <list compact="compact">
                  <item>
                    <p><qref id="f-Source"><tt>Source</tt></qref></p>
                  </item>
                  <item>
                    <p><qref id="versions"><tt>Version</tt></qref></p>
                  </item>
                  <item>
                    <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
                  </item>
                  <item>
                    <p><qref id="f-Binary"><tt>Binary</tt></qref></p>
                  </item>
                  <item>
                    <p><qref id="f-Architecture"><tt>Architecture</tt></qref></p>
                  </item>
                  <item>
                     <p>
                       <qref id="relationships"><tt>Build-Depends</tt> et
                         al.</qref> (source package interrelationships)
                     </p>
                  </item>
                  <item>
                    <p>
                      <qref id="f-Standards-Version"><tt>Standards-Version</tt></qref></p>
                  </item>
                  <item>
                    <p><qref id="f-Files"><tt>Files</tt></qref></p>
                  </item>
                </list>

              <p>               
                The source package control file is generated by
                <prgn>dpkg-source</prgn> 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.</p>
            </item>
              
            <tag>
              Original source archive -
              <tt>
                <var>package</var>_<var>upstream-version</var>.orig.tar.gz
              </tt>
            </tag> 

            <item>
              
              <p>
                This is a compressed (with <tt>gzip -9</tt>)
                <prgn>tar</prgn> file containing the source code from
                the upstream authors of the program.  The tarfile
                unpacks into a directory
                <tt><var>package</var>-<var>upstream-version</var>.orig</tt>,
                and does not contain files anywhere other than in
                there or in its subdirectories.</p>
            </item>
              
            <tag>
              Debianisation diff -
              <tt>
                <var>package</var>_<var>upstream_version-revision</var>.diff.gz
              </tt>
            </tag> 
            <item>
              
              <p>
                This is a unified context diff (<tt>diff -u</tt>)
                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.
              </p>

              <p>               
                All the directories in the diff must exist, except the
                <tt>debian</tt> subdirectory of the top of the source
                tree, which will be created by
                <prgn>dpkg-source</prgn> if necessary when unpacking.
              </p>

              <p>               
                The <prgn>dpkg-source</prgn> program will
                automatically make the <tt>debian/rules</tt> file
                executable (see below).</p></item>
          </taglist>
            

        <p>       
          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
          <tt><var>package</var>_<var>version</var>.tar.gz</tt> and
          contains a directory
          <tt><var>package</var>-<var>version</var></tt>.
        </p>
      </sect>
        
      <sect><heading>Unpacking a Debian source package without
      <prgn>dpkg-source</prgn>
        </heading>

        <p>       
          <tt>dpkg-source -x</tt> 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:
        <enumlist compact="compact">
          <item> 
            <p>
              Untar the tarfile, which will create a <tt>.orig</tt>
              directory.</p>
          </item>
          <item>
            <p>Rename the <tt>.orig</tt> directory to
              <tt><var>package</var>-<var>version</var></tt>.</p>
          </item>
            <item>
            <p>
              Create the subdirectory <tt>debian</tt> at the top of
              the source tree.</p>
          </item>
          <item><p>Apply the diff using <tt>patch -p0</tt>.</p>
          </item>
          <item><p>Untar the tarfile again if you want a copy of the original
              source code alongside the Debianised version.</p>
          </item>
        </enumlist>
        
        <p>       
          It is not possible to generate a valid Debian source archive
          without using <prgn>dpkg-source</prgn>.  In particular,
          attempting to use <prgn>diff</prgn> directly to generate the
          <tt>.diff.gz</tt> file will not work.
        </p>
          
        <sect1><heading>Restrictions on objects in source packages
          </heading>

          <p>       
            The source package may not contain any hard links
            <footnote>
              <p>
                This is not currently detected when building source
                packages, but only when extracting
                them.
              </p>
            </footnote>
            <footnote>
              <p>
                Hard links may be permitted at some point in the
                future, but would require a fair amount of
                work.
              </p>
            </footnote>, device special files, sockets or setuid or
            setgid files.
            <footnote>
              <p>
                Setgid directories are allowed.
              </p>
            </footnote>
          </p>

          <p>       
            The source packaging tools manage the changes between the
            original and Debianised source using <prgn>diff</prgn> and
            <prgn>patch</prgn>.  Turning the original source tree as
            included in the <tt>.orig.tar.gz</tt> into the debianised
            source must not involve any changes which cannot be
            handled by these tools.  Problematic changes which cause
            <prgn>dpkg-source</prgn> to halt with an error when
            building the source package are:
            <list compact="compact">
              <item><p>Adding or removing symbolic links, sockets or pipes.</p>
              </item>
              <item><p>Changing the targets of symbolic links.</p>
              </item>
              <item><p>Creating directories, other than <tt>debian</tt>.</p>
              </item>
              <item><p>Changes to the contents of binary files.</p></item>
            </list> Changes which cause <prgn>dpkg-source</prgn> to
            print a warning but continue anyway are:
            <list compact="compact">
              <item>
                <p>
                  Removing files, directories or symlinks.
                  <footnote>
                    <p>
                      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.</p>
                  </footnote>
                </p>
              </item>
              <item>
                <p>
                  Changed text files which are missing the usual final
                  newline (either in the original or the modified
                  source tree).
                </p>
              </item>
            </list>
            Changes which are not represented, but which are not detected by
            <prgn>dpkg-source</prgn>, are:
            <list compact="compact">
              <item><p>Changing the permissions of files (other than
                  <tt>debian/rules</tt>) and directories.</p></item>
            </list>
          </p>

          <p>       
            The <tt>debian</tt> directory and <tt>debian/rules</tt>
            are handled specially by <prgn>dpkg-source</prgn> - before
            applying the changes it will create the <tt>debian</tt>
            directory, and afterwards it will make
            <tt>debian/rules</tt> world-exectuable.
          </p>
        </sect1>
      </sect>
    </chapt>
      
    <chapt id="controlfields"><heading>Control files and their fields
      </heading>

      <p>       
        Many of the tools in the <prgn>dpkg</prgn> suite manipulate
        data in a common format, known as control files.  Binary and
        source packages have control data as do the <tt>.changes</tt>
        files which control the installation of uploaded files, and
        <prgn>dpkg</prgn>'s internal databases are in a similar
        format.
      </p>
        
      <sect><heading>Syntax of control files
        </heading>

        <p>       
          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.
        </p>

        <p>       
          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.
        </p>

        <p>       
          Some fields' values may span several lines; in this case
          each continuation line <em>must</em> start with a space or
          tab.  Any trailing spaces or tabs at the end of individual
          lines of a field value are ignored.
        </p>

        <p>       
          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.
        </p>

        <p>       
          Field names are not case-sensitive, but it is usual to
          capitalise the field names using mixed case as shown below.
        </p>

        <p>       
          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.
        </p>

        <p>       
          It is important to note that there are several fields which
          are optional as far as <prgn>dpkg</prgn> 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 <em>must</em> read
          the Debian policy manual in conjuction with the details
          below and the list of fields for the particular file.</p>
      </sect>
        
      <sect><heading>List of fields
        </heading>
          
        <sect1 id="f-Package"><heading><tt>Package</tt>
          </heading>

          <p>       
            The name of the binary package.  Package names consist of
            the alphanumerics and <tt>+</tt> <tt>-</tt> <tt>.</tt>
            (plus, minus and full stop).
            <footnote>
              <p>
                The characters <tt>@</tt> <tt>:</tt> <tt>=</tt>
                <tt>%</tt> <tt>_</tt> (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
              </p>
            </footnote>
          </p>

          <p>       
            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><p>This is a
            bug.</p></footnote>; use lowercase package names unless
            the package you're building (or referring to, in other
            fields) is already using uppercase.</p>
        </sect1>
          
        <sect1 id="f-Version"><heading><tt>Version</tt>
          </heading>

          <p>       
            This lists the source or binary package's version number -
            see <ref id="versions">.
          </p>

        </sect1>
          
        <sect1 id="f-Architecture"><heading><tt>Architecture</tt>
          </heading>

          <p>       
            This is the architecture string; it is a single word for
            the Debian architecture.
          </p>

          <p>       
            <prgn>dpkg</prgn> will check the declared architecture of
            a binary package against its own compiled-in value before
            it installs it.
          </p>

          <p>       
            The special value <tt>all</tt> indicates that the package
            is architecture-independent.
          </p>

          <p>       
            In the main <tt>debian/control</tt> file in the source
            package, or in the source package control file
            <tt>.dsc</tt>, a list of architectures (separated by
            spaces) is also allowed, as is the special value
            <tt>any</tt>.  A list indicates that the source will build
            an architecture-dependent package, and will only work
            correctly on the listed architectures.  <tt>any</tt>
            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.
          </p>

          <p>       
            In a <tt>.changes</tt> file the <tt>Architecture</tt>
            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 <tt>source</tt> is also present.
          </p>

          <p>       
            See <ref id="debianrules"> for information how to get the
            architecture for the build process. 
          </p>
        </sect1>
          
        <sect1 id="f-Maintainer"><heading><tt>Maintainer</tt>
          </heading>

          <p>       
            The package maintainer's name and email address.  The name
            should come first, then the email address inside angle
            brackets <tt>&lt;&gt</tt> (in RFC822 format).
          </p>

          <p>       
            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).
          </p>

          <p>       
            In a <tt>.changes</tt> 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.
          </p>

          <p>       
            This field is usually optional in as far as the
            <prgn>dpkg</prgn> are concerned, but its absence when
            building packages usually generates a warning.</p>
        </sect1>
          
        <sect1 id="f-Source"><heading><tt>Source</tt>
          </heading>

          <p>       
            This field identifies the source package name.
          </p>

          <p>       
            In a main source control information or a
            <tt>.changes</tt> or <tt>.dsc</tt> file or parsed
            changelog data this may contain only the name of the
            source package.
          </p>

          <p>       
            In the control file of a binary package (or in a
            <tt>Packages</tt> file) it may be followed by a version
            number in parentheses.
            <footnote>
              <p>
                It is usual to leave a space after the package name if
                a version number is specified.
              </p>
            </footnote> This version number may be omitted (and is, by
            <prgn>dpkg-gencontrol</prgn>) if it has the same value as
            the <tt>Version</tt> 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.
          </p>
        </sect1>
          
        <sect1><heading>Package interrelationship fields:
            <tt>Depends</tt>, <tt>Pre-Depends</tt>,
            <tt>Recommends</tt> <tt>Suggests</tt>, <tt>Conflicts</tt>,
            <tt>Provides</tt>, <tt>Replaces</tt>
          </heading>

          <p>       
            These fields describe the package's relationships with
            other packages.  Their syntax and semantics are described
            in <ref id="relationships">.</p>
        </sect1>
          
        <sect1 id="f-Description"><heading><tt>Description</tt>
          </heading>

          <p>       
            In a binary package <tt>Packages</tt> file or main source
            control file this field contains a description of the
            binary package, in a special format.  See <ref
            id="descriptions"> for details.
          </p>

          <p>       
            In a <tt>.changes</tt> 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.</p>
        </sect1>
          
        <sect1 id="f-Essential"><heading><tt>Essential</tt>
          </heading>

          <p>       
            This is a boolean field which may occur only in the
            control file of a binary package (or in the
            <tt>Packages</tt> file) or in a per-package fields
            paragraph of a main source control data file.
          </p>

          <p>       
            If set to <tt>yes</tt> then <prgn>dpkg</prgn> and
            <prgn>dselect</prgn> will refuse to remove the package
            (though it can be upgraded and/or replaced).  The other
            possible value is <tt>no</tt>, which is the same as not
            having the field at all.</p>
        </sect1>
          
        <sect1 id="f-classification"><heading><tt>Section</tt> and
        <tt>Priority</tt>
          </heading>

          <p>       
            These two fields classify the package.  The
            <tt>Priority</tt> represents how important that it is that
            the user have it installed; the <tt>Section</tt>
            represents an application area into which the package has
            been classified.
          </p>

          <p>       
            When they appear in the <tt>debian/control</tt> file these
            fields give values for the section and priority subfields
            of the <tt>Files</tt> field of the <tt>.changes</tt> file,
            and give defaults for the section and priority of the
            binary packages.
          </p>

          <p>       
            The section and priority are represented, though not as
            separate fields, in the information for each file in the
            <qref id="f-Files"><tt>-File</tt></qref>field of a
            <tt>.changes</tt> file.  The section value in a
            <tt>.changes</tt> file is used to decide where to install
            a package in the FTP archive.
          </p>

          <p>       
            These fields are not used by by <prgn>dpkg</prgn> proper,
            but by <prgn>dselect</prgn> 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.
          </p>

          <p>       
            These fields may appear in binary package control files,
            in which case they provide a default value in case the
            <tt>Packages</tt> files are missing the information.
            <prgn>dpkg</prgn> and <prgn>dselect</prgn> will only use
            the value from a <tt>.deb</tt> file if they have no other
            information; a value listed in a <tt>Packages</tt> file
            will always take precedence.  By default
            <prgn>dpkg-genchanges</prgn> does not include the section
            and priority in the control file of a binary package - use
            the <tt>-isp</tt>, <tt>-is</tt> or <tt>-ip</tt> options to
            achieve this effect.</p>
        </sect1>
          
        <sect1 id="f-Binary"><heading><tt>Binary</tt>
          </heading>

          <p>       
            This field is a list of binary packages.
          </p>

          <p>       
            When it appears in the <tt>.dsc</tt> 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.
          </p>

          <p>       
            When it appears in a <tt>.changes</tt> file it lists the
            names of the binary packages actually being uploaded.
          </p>

          <p>       
            The syntax is a list of binary packages separated by
            commas.
            <footnote>
              <p>
                A space after each comma is conventional.
              </p>
            </footnote> Currently the packages must be separated using
            only spaces in the <tt>.changes</tt> file.</p>
        </sect1>
          
        <sect1 id="f-Installed-Size"><heading><tt>Installed-Size</tt>
          </heading>

          <p>       
            This field appears in the control files of binary
            packages, and in the <tt>Packages</tt> files.  It gives
            the total amount of disk space required to install the
            named package.
          </p>

          <p>       
            The disk space is represented in kilobytes as a simple
            decimal number.</p>
        </sect1>
          
        <sect1 id="f-Files"><heading><tt>Files</tt>
          </heading>

          <p>       
            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.
          </p>

          <p>       
            In the <tt>.dsc</tt> (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>
              <p>
                That is, the parts which are not the
                <tt>.dsc</tt>.
              </p>
            </footnote> The exact forms of the filenames are described
            in <ref id="sourcearchives">.
          </p>

          <p>       
            In the <tt>.changes</tt> 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 <ref
            id="f-classification">.  If no section or priority is
            specified then <tt>-</tt> should be used, though section
            and priority values must be specified for new packages to
            be installed properly.
          </p>

          <p>       
            The special value <tt>byhand</tt> for the section in a
            <tt>.changes</tt> 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
            <tt>byhand</tt> the priority should be <tt>-</tt>.
          </p>

          <p>       
            If a new Debian revision of a package is being shipped and
            no new original source archive is being distributed the
            <tt>.dsc</tt> must still contain the <tt>Files</tt> field
            entry for the original source archive
            <tt><var>package</var>-<var>upstream-version</var>.orig.tar.gz</tt>,
            but the <tt>.changes</tt> 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
            <tt>.dsc</tt> file and diff which are being uploaded.</p>
        </sect1>
          
          
        <sect1
        id="f-Standards-Version"><heading><tt>Standards-Version</tt>
          </heading>

          <p>       
            The most recent version of the standards (the
            <prgn>dpkg</prgn> 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.
          </p>

          <p>       
            Its format is the same as that of a version number except
            that no epoch or Debian revision is allowed - see <ref
            id="versions">.</p>
        </sect1>
          
          
        <sect1 id="f-Distribution"><heading><tt>Distribution</tt>
          </heading>

          <p>       
            In a <tt>.changes</tt> 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 <ref id="f-Package">).
          </p>

          <p>       
            Current distribution values are:
          <taglist>
            <tag><em>stable</em></tag>
            <item>
              <p> 
                This is the current `released' version of Debian
                GNU/Linux.  A new version is released approximately
                every 3 months after the <em>development</em> code has
                been <em>frozen</em> for a month of testing.  Once the
                distribution is <em>stable</em> only major bug fixes
                are allowed. When changes are made to this
                distribution, the release number is increased
                (for example: 1.2r1 becomes 1.2r2 then 1.2r3, etc).
              </p>
            </item>
                
            <tag><em>unstable</em></tag>
            <item>
              <p>
                This distribution value refers to the
                <em>developmental</em> part of the Debian distribution
                tree. New packages, new upstream versions of packages
                and bug fixes go into the <em>unstable</em> directory
                tree. Download from this distribution at your own
                risk.</p>
            </item>
            
            <tag><em>contrib</em></tag>
            <item>
              <p>
                The packages with this distribution value do not meet
                the criteria for inclusion in the main Debian
                distribution as defined by the Policy Manual, but meet
                the criteria for the <em>contrib</em>
                Distribution. There is currently no distinction
                between stable and unstable packages in the
                <em>contrib</em> or <em>non-free</em>
                distributions. Use your best judgement in downloading
                from this Distribution.</p>
            </item>
                
            <tag><em>non-free</em></tag>
            <item>
              <p>
                Like the packages in the <em>contrib</em> seciton,
                the packages in <em>non-free</em> do not meet the
                criteria for inclusion in the main Debian distribution
                as defined by the Policy Manual. Again, use your best
                judgement in downloading from this Distribution.</p>
              
            <tag><em>experimental</em></tag>
            <item>
              <p>
                The packages with this distribution value are deemed
                by their maintainers to be high risk. Oftentimes they
                represent early beta or developmental packages from
                various sources that the maintainers want people to
                try, but are not ready to be a part of the other parts
                of the Debian distribution tree. Download at your own
                risk.</p>
            </item>
                
            <tag><em>frozen</em></tag>
            <item>
              <p>
                From time to time, (currently, every 3 months) the
                <em>unstable</em> distribution enters a state of
                `code-freeze' in anticipation of release as a
                <em>stable</em> version. During this period of testing
                (usually 4 weeks) only fixes for existing or
                newly-discovered bugs will be allowed.
              </p>
            </item>
          </taglist> You should list <em>all</em> distributions that
          the package should be installed into. Except in unusual
          circumstances, installations to <em>stable</em> should also
          go into <em>frozen</em> (if it exists) and
          <em>unstable</em>. Likewise, installations into
          <em>frozen</em> should also go into <em>unstable</em>.</p>
        </sect1>
          
        <sect1 id="f-Urgency"><heading><tt>Urgency</tt>
          </heading>

          <p>       
            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 <tt>LOW</tt>,
            <tt>MEDIUM</tt> or <tt>HIGH</tt>) followed by an optional
            commentary (separated by a space) which is usually in
            parentheses.  For example:
            <example>
  Urgency: LOW (HIGH for diversions users)
            </example>
          </p>

          <p>       
            This field appears in the <tt>.changes</tt> file and in
            parsed changelogs; its value appears as the value of the
            <tt>urgency</tt> attribute in a <prgn>dpkg</prgn>-style
            changelog (see <ref id="dpkgchangelog">).
          </p>

          <p>       
            Urgency keywords are not case-sensitive.</p>
        </sect1>
          
        <sect1 id="f-Date"><heading><tt>Date</tt>
          </heading>

          <p>       
            In <tt>.changes</tt> files and parsed changelogs, this
            gives the date the package was built or last edited.</p>
        </sect1>
          
        <sect1 id="f-Format"><heading><tt>Format</tt>
          </heading>

          <p>       
            This field occurs in <tt>.changes</tt> files, and
            specifies a format revision for the file.  The format
            described here is version <tt>1.5</tt>.  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 <ref id="versions">.</p>
        </sect1>
          
        <sect1 id="f-Changes"><heading><tt>Changes</tt>
          </heading>

          <p>       
            In a <tt>.changes</tt> file or parsed changelog this field
            contains the human-readable changes data, describing the
            differences between the last version and the current one.
          </p>

          <p>       
            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.
          </p>

          <p>       
            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.
          </p>

          <p>       
            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).</p>
        </sect1>
          
        <sect1 id="f-Filename"><heading><tt>Filename</tt> and
        <tt>MSDOS-Filename</tt>
          </heading>

          <p>       
            These fields in <tt>Packages</tt> 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.</p>
        </sect1>
          
        <sect1 id="f-Size"><heading><tt>Size</tt> and <tt>MD5sum</tt>
          </heading>

          <p>       
            These fields in <tt>Packages</tt> 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.</p>
        </sect1>
          
        <sect1 id="f-Status"><heading><tt>Status</tt>
          </heading>

          <p>       
            This field in <prgn>dpkg</prgn>'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.</p>
        </sect1>
          
        <sect1 id="f-Config-Version"><heading><tt>Config-Version</tt>
          </heading>

          <p>       
            If a package is not installed or not configured, this
            field in <prgn>dpkg</prgn>'s status file records the last
            version of the package which was successfully
            configured.</p>
        </sect1>
          
        <sect1 id="f-Conffiles"><heading><tt>Conffiles</tt>
          </heading>

          <p>       
            This field in <prgn>dpkg</prgn>'s status file contains
            information about the automatically-managed configuration
            files held by a package.  This field should <em>not</em>
            appear anywhere in a package!</p>
        </sect1>
          
        <sect1><heading>Obsolete fields
          </heading>

          <p>       
            These are still recognised by <prgn>dpkg</prgn> but should
            not appear anywhere any more.
            <taglist compact="compact">
              
              <tag><tt>Revision</tt></tag>
              <tag><tt>Package-Revision</tt></tag>
              <tag><tt>Package_Revision</tt></tag>
              <item>
                <p>
                  The Debian revision part of the package version was
                  at one point in a separate control file field.  This
                  field went through several names.</p>
              </item>
                  
              <tag><tt>Recommended</tt></tag>
              <item><p>Old name for <tt>Recommends</tt></p>
              </item>
                
              <tag><tt>Optional</tt></tag>
              <item><p>Old name for <tt>Suggests</tt>.</p>
              </item>
              <tag><tt>Class</tt></tag>
              <item><p>Old name for <tt>Priority</tt>.</p>
              </item>
            </taglist>
          </p>
        </sect1>
      </sect>
    </chapt>

    <chapt id="versions"><heading>Version numbering
      </heading>

      <p>       
        Every package has a version number, in its <tt>Version</tt>
        control file field.
      </p>

      <p>       
        <prgn>dpkg</prgn> imposes an ordering on version numbers, so
        that it can tell whether packages are being up- or downgraded
        and so that <prgn>dselect</prgn> 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.
      </p>

      <p>       
        The version number format is:
        &lsqb<var>epoch/<tt>:</tt>&rsqb;<var>upstream-version</var>&lsqb;<tt>-/<var>debian-revision</var>&rsqb;.</tt></var>
      </p>

      <p>       
        The three components here are:
        <taglist>
          <tag><var>epoch</var></tag>
          <item>
            
            <p>
              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
              <var>upstream-version</var> may not contain any colons.
            </p>

            <p>       
              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.
            </p>

            <p>       
              <prgn>dpkg</prgn> will not usually display the epoch
              unless it is essential (non-zero, or if the
              <var>upstream-version</var> contains a colon);
              <prgn>dselect</prgn> does not display epochs at all in
              the main part of the package selection display.</p>
          </item>
            
          <tag><var>upstream-version</var></tag>
          <item>
            
            <p>
              This is the main part of the version.  It is usually
              version number of the original (`upstream') package of
              which the <tt>.deb</tt> 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
              <prgn>dpkg</prgn>'s format and comparison scheme.
            </p>

            <p>       
              The comparison behaviour of <prgn>dpkg</prgn> with
              respect to the <var>upstream-version</var> is described
              below.  The <var>upstream-version</var> portion of the
              version number is mandatory.
            </p>

            <p>       
              The <var>upstream-version</var> may contain only
              alphanumerics and the characters <tt>.</tt> <tt>+</tt>
              <tt>-</tt> <tt>:</tt> (full stop, plus, hyphen, colon)
              and should start with a digit.  If there is no
              <var>debian-revision</var> then hyphens are not allowed;
              if there is no <var>epoch</var> then colons are not
              allowed.</p>
          </item>
            
          <tag><var>debian-revision</var></tag>
          <item>
            
            <p>
              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
              <var>upstream-version</var> and <prgn>dpkg</prgn>
              compares it in the same way.
            </p>

            <p>       
              It is optional; if it isn't present then the
              <var>upstream-version</var> 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.
            </p>

            <p>       
              It is conventional to restart the
              <var>debian-revision</var> at <tt>1</tt> each time the
              <var>upstream-version</var> is increased.
            </p>

            <p>       
              <prgn>dpkg</prgn> will break the
              <var>upstream-version</var> and
              <var>debian-revision</var> apart at the last hyphen in
              the string.  The absence of a <var>debian-revision</var>
              compares earlier than the presence of one (but note that
              the <var>debian-revision</var> is the least significant
              part of the version number).
            </p>

            <p>       
              The <var>debian-revision</var> may contain only
              alphanumerics and the characters <tt>+</tt> and
              <tt>.</tt> (plus and full stop).
            </p>
          </item>
        </taglist>
        The <var>upstream-version</var> and <var>debian-revision</var> parts are
        compared by <prgn>dpkg</prgn> using the same algorithm:
      </p>

      <p>       
        The strings are compared from left to right.
      </p>

      <p>       
        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.
      </p>

      <p>       
        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.
      </p>

      <p>       
        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.
      </p>

      <p>       
        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 <em>not</em> there
        to cope with version numbers containing strings of letters
        which <prgn>dpkg</prgn> cannot interpret (such as
        <tt>ALPHA</tt> or <tt>pre-</tt>), or with silly orderings (the
        author of this manual has heard of a package whose versions
        went <tt>1.1</tt>, <tt>1.2</tt>, <tt>1.3</tt>, <tt>1</tt>,
        <tt>2.1</tt>, <tt>2.2</tt>, <tt>2</tt> and so forth).
      </p>

      <p>       
        If an upstream package has problematic version numbers they
        should be converted to a sane form for use in the
        <tt>Version</tt> field.
      </p>

      <p>       
        If you need to compare version numbers in a script, you may use
        <tt>dpkg --compare-versions ...</tt>. Type <tt>dpkg
        --help</tt> --> --for details on arguments.
      </p>

      <sect>
        <heading>Version numbers based on dates</heading>
        <p>
          In general, Debian packages should use the same version
          numbers as the upstream sources.</p>

        <p>
          However, in some cases where the upstream version number is
          based on a date (e.g., a development `snapshot' release)
          dpkg cannot handle these version numbers currently, without
          epochs. For example, dpkg will consider `96May01' to be
          greater than `96Dec24'.</p>

        <p>
          To prevent having to use epochs for every new upstream
          version, the version number should be changed to the
          following format in such cases: `19960501', `19961224'. It
          is up to the maintainer whether he/she wants to bother the
          upstream maintainer to change the version numbers upstream,
          too.</p>

        <p>
          Note, that other version formats based on dates which are
          parsed correctly by dpkg should <em>not</em> be changed.</p>

        <p>
          Native Debian packages (i.e., packages which have been
          written especially for Debian) whose version numbers include
          dates should always use the `YYYYMMDD' format.</p>
      </sect>
    </chapt>
      
    <chapt id="maintainerscripts"><heading>Package maintainer scripts
        and installation procedure
      </heading>

      <sect><heading>Introduction to package maintainer scripts
        </heading>

        <p>       
          It is possible to supply scripts as part of a package which
          <prgn>dpkg</prgn> will run for you when your package is
          installed, upgraded or removed.
        </p>

        <p>       
          These scripts should be the files <tt>preinst</tt>,
          <tt>postinst</tt>, <tt>prerm</tt> and <tt>postrm</tt> 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 <tt>#!</tt> convention.  They should be
          readable and executable to anyone, and not world-writeable.
        </p>

        <p>       
          <prgn>dpkg</prgn> 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 <prgn>dpkg</prgn> can
          stop its processing.  For shell scripts this means that you
          <em>almost always</em> need to use <tt>set -e</tt> (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.
        </p>

        <p>       
          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.
        </p>

        <p>       
          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.
        </p>

        <p>       
          Broadly speaking the <prgn>preinst</prgn> is called before
          (a particular version of) a package is installed, and the
          <prgn>postinst</prgn> afterwards; the <prgn>prerm</prgn>
          before (a version of) a package is removed and the
          <prgn>postrm</prgn> afterwards.       
        </p>
          <!--
          next paragraph by Guy Maor to close bug #2481
          -->
 
          <p> Programs called from maintainer scripts should not
          normally have a path prepended to them. Before installation
          is started <prgn>dpkg</prgn> checks to see if the programs
          <prgn>ldconfig</prgn>, <prgn>start-stop-daemon</prgn>,
          <prgn>install-info</prgn>, and <prgn>update-rc.d</prgn> can
          be found via the <tt>PATH</tt> environment variable. Those
          programs, and any other program that one would expect to on
          the <tt>PATH</tt>, should thus be invoked without an
          absolute pathname. Maintainer scripts should also not reset
          the <tt>PATH</tt>, though they might choose to modify it by
          pre- or appending package-specific directories. These
          considerations really apply to all shell scripts.</p>
      </sect>
        
      <sect id="mscriptsinstact"><heading>Summary of ways maintainer
      scripts are called
        </heading>

        <p>       
          <list compact="compact">
            <item>
              <p><var>new-preinst</var> <tt>install</tt></p>
            </item>
            <item>
              <p><var>new-preinst</var> <tt>install</tt>
              <var>old-version</var></p>
            </item>
            <item>
              <p><var>new-preinst</var> <tt>upgrade</tt>
              <var>old-version</var></p>
            </item>
            <item>
              <p><var>old-preinst</var> <tt>abort-upgrade</tt>
              <var>new-version</var>
              </p>
            </item> 
          </list>

        <p>       
          <list compact="compact">
            <item>
              <p><var>postinst</var> <tt>configure</tt>
                <var>most-recently-configured-version</var></p>
            </item>
            <item>
              <p><var>old-postinst</var> <tt>abort-upgrade</tt>
              <var>new version</var></p>
            </item>
            <item>
              <p><var>conflictor's-postinst</var> <tt>abort-remove</tt>
                <tt>in-favour</tt> <var>package</var>
                <var>new-version</var></p>
            </item>
            <item>
              <p>
                <var>deconfigured's-postinst</var>
                <tt>abort-deconfigure</tt> <tt>in-favour</tt>
                <var>failed-install-package</var> <var>version</var>
                <tt>removing</tt> <var>conflicting-package</var>
                <var>version</var>
              </p>
            </item>
          </list>

        <p>       
          <list compact="compact">
            <item>
              <p><var>prerm</var> <tt>remove</tt></p>
            </item>
            <item>
              <p><var>old-prerm</var> <tt>upgrade</tt>
                <var>new-version</var></p>
            </item>
            <item>
              <p><var>new-prerm</var> <tt>failed-upgrade</tt>
                <var>old-version</var></p>
            </item>
            <item>
              <p><var>conflictor's-prerm</var> <tt>remove</tt>
                <tt>in-favour</tt> <var>package</var>
                <var>new-version</var></p>
            </item>
            <item>
              <p>
                <var>deconfigured's-prerm</var> <tt>deconfigure</tt>
                <tt>in-favour</tt> <var>package-being-installed</var>
                <var>version</var> <tt>removing</tt>
                <var>conflicting-package</var>
                <var>version</var>
              </p>
            </item>
          </list>

        <p>       
          <list compact="compact">
            <item>
              <p><var>postrm</var> <tt>remove</tt></p>
            </item>
            <item>
              <p><var>postrm</var> <tt>purge</tt></p>
            </item>
            <item>
              <p>
                <var>old-postrm</var> <tt>upgrade</tt>
                <var>new-version</var></p>
            </item>
            <item>
              <p><var>new-postrm</var> <tt>failed-upgrade</tt>
                <var>old-version</var></p>
            </item>
            <item>
              <p><var>new-postrm</var> <tt>abort-install</tt></p>
            </item>
            <item>
              <p><var>new-postrm</var> <tt>abort-install</tt>
                <var>old-version</var></p>
            </item>
            <item>
              <p><var>new-postrm</var> <tt>abort-upgrade</tt>
                <var>old-version</var></p>
            </item>
            <item>
              <p>
                <var>disappearer's-postrm</var> <tt>disappear</tt>
                <var>overwriter</var>
                <var>overwriter-version</var></p></item>
          </list>
        </p>
        
        
      <sect id="unpackphase"><heading>Details of unpack phase of
      installation or upgrade
        </heading>

        <p>       
          The procedure on installation/upgrade/overwrite/disappear
          (ie, when running <tt>dpkg --unpack</tt>, or the unpack
          stage of <tt>dpkg
            --install</tt>) 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.
          
          <enumlist>
            <item>
              <p>
                <enumlist>
                  <item>
                    <p>If a version the package is already
                      installed, call
                      <example>
  <var>old-prerm</var> upgrade <var>new-version</var>
                      </example></p>
                  </item>
                  <item>
                    <p>
                      If this gives an error (ie, a non-zero exit
                      status), dpkg will attempt instead:
                      <example>
  <var>new-prerm</var> failed-upgrade <var>old-version</var>
                      </example>
                      Error unwind, for both the above cases:
                      <example>
  <var>old-postinst</var> abort-upgrade <var>new-version</var>
                      </example>
                    </p>
                  </item>
                </enumlist>
              </p>
            </item>
            <item>
              <p>If a `conflicting' package is being removed at the same time:
                <enumlist>
                  <item>
                    <p>
                      If any packages depended on that conflicting
                      package and <tt>--auto-deconfigure</tt> is
                      specified, call, for each such package:
                      <example>
  <var>deconfigured's-prerm</var> deconfigure \
   in-favour <var>package-being-installed</var> <var>version</var> \
    removing <var>conflicting-package</var> <var>version</var>
                      </example>
                      Error unwind:
                      <example>
  <var>deconfigured's-postinst</var> abort-deconfigure \
    in-favour <var>package-being-installed-but-failed</var> <var>version</var> \
      removing <var>conflicting-package</var> <var>version</var>
                      </example> 
                      The deconfigured packages are marked as
                      requiring configuration, so that if
                      <tt>--install</tt> is used they will be
                      configured again if possible.</p>
                  </item>
                  <item>
                    <p>To prepare for removal of the conflicting package, call:
                      <example>
  <var>conflictor's-prerm</var> remove in-favour <var>package</var> <var>new-version</var>
                      </example>
                      Error unwind:
                      <example>
  <var>conflictor's-postinst</var> abort-remove \
    in-favour <var>package</var> <var>new-version</var>
                      </example>
                    </p>
                  </item>
                </enumlist>
              </p>
            </item>
            <item>
              <p>
                <enumlist>
                  <item>
                    <p>If the package is being upgraded, call:
                      <example>
  <var>new-preinst</var> upgrade <var>old-version</var>
                      </example></p>
                  </item>
                  <item>
                    <p>
                      Otherwise, if the package had some configuration
                      files from a previous version installed (ie, it
                      is in the `configuration files only' state):
                      <example>
  <var>new-preinst</var> install <var>old-version</var>
                      </example></p>
                    
                  <item>
                    <p>Otherwise (ie, the package was completely purged):
                      <example>
  <var>new-preinst</var> install
                      </example>
                      Error unwind versions, respectively:
                      <example>
  <var>new-postrm</var> abort-upgrade <var>old-version</var>
    <var>new-postrm</var> abort-install <var>old-version</var>
      <var>new-postrm</var> abort-install
                      </example>
                    </p>
                  </item>
                </enumlist>
              </p>
            </item>
            <item>

              <p>
                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).
              </p>

              <p>               
                It is an error for a package to contains files which
                are on the system in another package, unless
                <tt>Replaces</tt> is used (see <ref id="replaces">).
                Currently the <tt>--force-overwrite</tt> flag is
                enabled, downgrading it to a warning, but this may not
                always be the case.
              </p>

              <p>               
                It is a more serious error for a package to contain a
                plain file or other kind of nondirectory where another
                package has a directory (again, unless
                <tt>Replaces</tt> is used).  This error can be
                overridden if desired using
                <tt>--force-overwrite-dir</tt>, but this is not
                advisable.
              </p>

              <p>               
                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>
                  <p>
                    Part of the problem is due to what is arguably a
                    bug in <prgn>dpkg</prgn> .
                  </p>
                </footnote>
              </p>

              <p>               
                A directory will never be replaced by a symbolic links
                to a directory or vice versa; instead, the existing
                state (symlink or not) will be left alone and
                <prgn>dpkg</prgn> will follow the symlink if there is
                one.</p>
            </item>
              
            <item>
              
              <p><enumlist>
                  <item>
                    <p>If the package is being upgraded, call
                      <example>
  <var>old-postrm</var> upgrade <var>new-version</var>
                      </example></p>
                  </item>
                  <item>
                    <p>If this fails, <prgn>dpkg</prgn> will attempt:
                      <example>
  <var>new-postrm</var> failed-upgrade <var>old-version</var>
                      </example>
                      Error unwind, for both cases:
                      <example>
  <var>old-preinst</var> abort-upgrade <var>new-version</var>
                      </example>
                    </p>
                  </item>
                </enumlist>
                This is the point of no return - if <prgn>dpkg</prgn>
                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
                <prgn>dpkg</prgn> starts doing things that are
                irreversible.</p>
            </item>
            <item>
              <p>               
                Any files which were in the old version of the package
                but not in the new are removed.</p>
            </item>
            <item>
                <p>The new file list replaces the old.</p>
            </item>
            <item>
                <p>The new maintainer scripts replace the old.</p>
            </item>
                
            <item>
              <p>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,
                <enumlist>
                  <item>
                    <p><prgn>dpkg</prgn> calls:
                      <example>
  <var>disappearer's-postrm</var> disappear \
    <var>overwriter</var> <var>overwriter-version</var>
                      </example>
                    </p>
                  </item>
                  <item>
                      <p>The package's maintainer scripts are removed.
                    </p>
                  </item>
                  <item>
                    <p>
                      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 <prgn>dpkg</prgn>).  Note that
                      disappearing packages do not have their prerm
                      called, because <prgn>dpkg</prgn> doesn't know
                      in advance that the package is going to
                      vanish.
                    </p>
                  </item>
                </enumlist>
              </p>
            </item>
            <item>
              <p>
                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.)
              </p>
            </item>
            <item>
              <p>
                The backup files made during installation, above, are
                deleted.
              </p>
            </item>
                
            <item>
              <p>
                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.
              </p>
            </item>
            <item>
              <p>
                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).
              </p>
            </item>
          </enumlist>
        </p>
      </sect>

      <sect><heading>Details of configuration
        </heading>

        <p>       
          When we configure a package (this happens with <tt>dpkg
          --install</tt>, or with <tt>--configure</tt>), we first
          update the conffiles and then call:
          <example>
  <var>postinst</var> configure <var>most-recently-configured-version</var>
          </example>
        </p>

        <p>       
          No attempt is made to unwind after errors during
          configuration.
        </p>

        <p>       
          If there is no most recently configured version
          <prgn>dpkg</prgn> will pass a null argument; older versions
          of dpkg may pass <tt>&lt;unknown&gt;</tt> (including the
          angle brackets) in this case.  Even older ones do not pass a
          second argument at all, under any circumstances.
        </p>
      </sect>
        
      <sect><heading>Details of removal and/or configuration purging
        </heading>

        <p>       
          <enumlist>
            <item>
              <p>
                <example>
  <var>prerm</var> remove
                </example>
              </p>
            </item>
            <item>
              <p>
                The package's files are removed (except conffiles).
              </p>
            </item>
            <item>
              <p><example>
  <var>postrm</var> remove
                </example></p>
            </item>
            <item>
              <p>All the maintainer scripts except the postrm are removed.
              </p>

              <p>               
                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 <prgn>dpkg</prgn>
                status.</p>
            </item>
            <item>
              <p>
                The conffiles and any backup files (<tt>~</tt>-files,
                <tt>#*#</tt> files, <tt>%</tt>-files,
                <tt>.dpkg-{old,new,tmp}</tt>, etc.) are removed.</p>
            </item>
            <item>
              <p><example>
  <var>postrm</var> purge
                </example></p>
            </item>
            <item>
                <p>The package's file list is removed.</p>
            </item>
          </enumlist>
          No attempt is made to unwind after errors during
          removal.</p>
      </sect>
    </chapt>
      
    <chapt id="descriptions"><heading>Descriptions of packages - the
        <tt>Description</tt> field
      </heading>

      <p>       
        The <tt>Description</tt> control file field is used by
        <prgn>dselect</prgn> when the user is selecting which packages
        to install and by <prgn>dpkg</prgn> when it displays
        information about the status of packages and so forth.  It is
        included on the FTP site in the <prgn>Packages</prgn> files,
        and may also be used by the Debian WWW pages.
      </p>

      <p>       
        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.
      </p>

      <p>       
        The field's format is as follows:
        <example>
  Description: <var>single line synopsis</var>
  <var>extended description over several lines</var>
        </example>
      </p>

      <p>       
        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.
      </p>

      <sect><heading>Types of formatting line in the extended
          description
        </heading>

        <p>       
          <list>
            <item>
              <p>
                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.
              </p>
            </item>
                
            <item>
              <p>
                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).
              </p>
            </item>
                
            <item>
              <p>Those containing a single space followed by a single full stop
                character.  These are rendered as blank lines.  This
                is the <em>only</em> way to get a blank line - see
                below.</p>
            </item>
              
            <item>
              <p>
                Those containing a space, a full stop and some more
                characters.  These are for future expansion.  Do not
                use them.</p>
            </item>
          </list>
        </p>
      </sect>

      <sect><heading>Notes about writing descriptions
        </heading>

        <p>       
          <em>Always</em> 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 <prgn>dpkg-deb</prgn>
          <footnote>
            <p>
              Version 0.93.23 or later.
            </p>
          </footnote> to produce a syntax error when trying to build
          the package.  If you force it to build anyway
          <prgn>dpkg</prgn> will refuse to install the resulting
          mess.
        </p>

        <p>       
          <em>Do not</em> include any completely <em>empty</em>
          lines. These separate different records in the Packages file
          and different packages in the <tt>debian/control</tt> file,
          and are forbidden in package control files.  See the
          previous paragraph for what happens if you get this wrong.
        </p>

        <p>       
          The single line synopsis should be kept brief - certainly
          under 80 characters.  <prgn>dselect</prgn> displays between
          25 and 49 characters without panning if you're using an
          80-column terminal, depending on what display options are in
          effect.
        </p>

        <p>       
          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.
        </p>

        <p>       
          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).
        </p>

        <p>       
          The blurb that comes with a program in its announcements
          and/or <prgn>README</prgn> 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.
        </p>

        <p>       
          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.
        </p>

        <p>       
          You may include information about dependencies and so forth
          in the extended description, if you wish.
        </p>

        <p>       
          Do not use tab characters.  Their effect is not predictable.
        </p>

        <p>       
          Do not try to linewrap the summary (the part on the same
          line as the field name <tt>Description</tt>) 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.</p>
      </sect>
        
      <sect><heading>Example description in control file for Smail
        </heading>

        <p>       
          <example>
  Package: smail
  Version: 3.1.29.1-13
  Maintainer: Ian Jackson &lt;iwj10@cus.cam.ac.uk&gt;
  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
  networking support, in the form of IP or UUCP.
          </example>
        </p>
      </sect>
    </chapt>

    <chapt id="relationships"><heading>Declaring relationships between
    packages
      </heading>

      <p>       
        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.
      </p>

      <p>       
        This is done using the <tt>Depends</tt>, <tt>Recommends</tt>,
        <tt>Suggests</tt>, <tt>Conflicts</tt>, <tt>Provides</tt> and
        <tt>Replaces</tt> control file fields.
      </p>

      <p>
        Source packages may declare relationships to binary packages,
        saying that they require certain binary packages being
        installed or absent at the time of building the package.
      </p>
        
      <p>
        This is done using the <tt>Build-Depends</tt>,
        <tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt>, and
        <tt>Build-Conflicts-Indep</tt> control file fields.
      </p>

      <sect id="depsyntax"><heading>Syntax of relationship fields
        </heading>

        <p>       
          These fields all have a uniform syntax.  They are a list of
          package names separated by commas.
        </p>

        <p>
          In <tt>Depends</tt>, <tt>Recommends</tt>, <tt>Suggests</tt>,
          <tt>Pre-Depends</tt>, <tt>Build-Depends</tt> and
          <tt>Build-Depends-Indep</tt>(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
          <tt>|</tt> (pipe symbols).
        </p>

        <p>       
          All the fields except <tt>Provides</tt> 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 <ref id="versions">.
        </p>

        <p>       
          The relations allowed are <tt>&lt;&lt;</tt>, <tt>&lt;=</tt>,
          <tt>=</tt>, <tt>&gt;=</tt> and <tt>&gt;&gt;</tt> for
          strictly earlier, earlier or equal, exactly equal, later or
          equal and strictly later, respectively.  The forms
          <tt>&lt;</tt> and <tt>&gt;</tt> were used to mean
          earlier/later or equal, rather than strictly earlier/later,
          so they should not appear in new packages (though
          <prgn>dpkg</prgn> still supports them).
        </p>

        <p>       
          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
          <prgn>dpkg</prgn> 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.
        </p>

        <p>       
          For example:
          <example>
  Package: metamail
  Version: 2.7-3
  Depends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh
          </example>
        </p>
 
        <p>
          All fields that specify build-time relationships
          (<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
          <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>)
          may be restricted to a certain set of architectures.  This
          is done in brackets after each individual package name and
          the optional version specification.  The brackets enclose a
          list of Debian architecture names separated by whitespace.
          An exclamation mark may be prepended to each name. If the
          current Debian host architecture is not in this list and
          there are no exclamation marks in the list, or it is in the
          list with a prepended exclamation mark, the package name and
          the associated version specification are ignored completely
          for the purposes of defining the relationships.
         </p>
 
         <p>
           For example:
           <example>
   Source: glibc
   Build-Depends-Indep: texinfo
   Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
                  hurd-dev [hurd-i386], gnumach-dev [hurd-i386]
           </example>
         </p> 
      </sect>
  
      <sect>
        <heading>Binary Dependencies - <tt>Depends</tt>,
          <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Pre-Depends</tt>
        </heading>

        <p>       
          These four fields are used to declare a dependency by one
          package on another.  They appear in the depending package's
          control file.
        </p>

        <p>       
          All but <tt>Pre-Depends</tt> (discussed below) take effect
          <em>only</em> 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.
        </p>

        <p>       
          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.
        </p>

        <p>       
          Thus <tt>Depends</tt> allows package maintainers to impose
          an order in which packages should be configured.
          <taglist>
            <tag><tt>Depends</tt></tag>
            <item>
              
              <p>This declares an absolute dependency.
              </p>

              <p>               
                <prgn>dpkg</prgn> 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>
                  <p>
                    Current versions (1.2.4) of <prgn>dpkg</prgn> have
                    a bug in this area which will cause some of these
                    problems to be ignored.
                  </p>
                </footnote>, unless <tt>--auto-deconfigure</tt> is
                specified, in which case those packages will be
                deconfigured before the installation proceeds.
              </p>

              <p>               
                <prgn>dselect</prgn> makes it hard for the user to
                select packages for installation, removal or upgrade
                in a way that would mean that packages'
                <prgn>Depends</prgn> fields would be unsatisfied.  The
                user can override this if they wish, for example if
                they know that <prgn>dselect</prgn> has an out-of-date
                view of the real package relationships.
              </p>

              <p>               
                The <tt>Depends</tt> field should be used if the
                depended-on package is required for the depending
                package to provide a significant amount of
                functionality.</p>
            </item>
              
            <tag><tt>Recommends</tt></tag>
            <item>
              <p>This declares a strong, but not absolute, dependency.
              </p>

              <p>               
                <tt>Recommends</tt> is ignored by <prgn>dpkg</prgn>,
                so that users using the command-line (who are presumed
                to know what they're doing) will not be impeded.
              </p>

              <p>               
                It is treated by <prgn>dselect</prgn> exactly as
                <tt>Depends</tt> is; this makes it hard for the user
                to select things so as to leave <tt>Recommends</tt>
                fields unsatisfied, but they are able to do so by
                being persistent.
              </p>

              <p>               
                The <tt>Recommends</tt> field should list packages
                that would be found together with this one in all but
                unusual installations.</p>
            </item>
              
            <tag><tt>Suggests</tt></tag>
            <item>
              
              <p>
                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 related to this one and can
                perhaps enhance its usefulness, but that installing
                this one without them is perfectly reasonable.
              </p>

              <p>               
                <prgn>dselect</prgn> will offer suggsted packages to
                the system administrator when they select the
                suggesting package, but the default is not to install
                the suggested package.</p>
            </item>
              
            <tag><tt>Pre-Depends</tt></tag>
            <item>
              
              <p>This field is like <tt>Depends</tt>, except that it also forces
                <prgn>dpkg</prgn> to complete installation of the
                packages named before even starting the installation
                of the package which declares the predependency.
              </p>

              <p>               
                <prgn>dselect</prgn> 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.
              </p>

              <p>               
                However, this process is slow (because it requires
                repeated invocations of <prgn>dpkg</prgn>) and
                troublesome (because it requires guessing where to
                find the appropriate files).
              </p>

              <p>               
                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),
                <tt>Pre-Depends</tt> 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.
              </p>

              <p>               
                When the package declaring it is being configured, a
                <tt>Pre-Dependency</tt> will be considered satisfied
                only if the depending package has been correctly
                configured, just as if an ordinary <tt>Depends</tt>
                had been used.
              </p>

              <p>               
                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 <tt>Pre-Depends</tt> field.
              </p>
            </item>
          </taglist>
        </p>
        <p> 
          When selecting which level of dependency to use you should
          consider how important the depended-on package is to the
          functionality of the one declaring the dependency.  Some
          packages are composed of components of varying degrees of
          importance.  Such a package should list using
          <tt>Depends</tt> the package(s) which are required by the
          more important components.  The other components'
          requirements may be mentioned as Suggestions or
          Recommendations, as appropriate to the components' relative
          importance.
        </p>

      <sect1><heading>Dependencies on shared libraries
        </heading>
        
        <p>         
            The dependency fields listed above are used by packages
            which need shared libraries to declare dependencies on the
            appropriate packages.
        </p>

        <p>         
          These dependencies are usually determined automatically
          using <prgn>dpkg-shlibdeps</prgn> and inserted in the
          package control file using the control file substitution
          variables mechanism; see <ref id="srcsubstvars"> and 
          <ref id="sourcetools">.
        </p>
      </sect1>
          
      <sect1><heading>Deconfiguration due to removal during bulk
      installations
        </heading>
          
        <p>         
          If <prgn>dpkg</prgn> 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,
          <prgn>dpkg</prgn> will usually not remove the conflicting
          package and halt with an error.
        </p>
          
        <p>         
          However, if the <tt>--auto-deconfigure</tt> (<tt>-B</tt>)
          option is used <prgn>dpkg</prgn> 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
          <prgn>dpkg</prgn> 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.
        </p>

          <p>       
            <prgn>dselect</prgn> supplies this argument to
            <prgn>dpkg</prgn> when it invokes it, so that bulk
            installations proceed smoothly.
        </p>
      </sect1>

      <sect id="conflicts"><heading>Alternative binary packages -
          <tt>Conflicts</tt> and <tt>Replaces</tt>
        </heading>

        <p>       
          When one binary package declares a conflict with another
          <prgn>dpkg</prgn> will refuse to allow them to be installed
          on the system at the same time.
        </p>

        <p>       
          If one package is to be installed, the other must be removed first -
          if the package being installed is marked as replacing (<ref
                                                                      id="replaces">) the one on the system, or the one on the system is
          marked as deselected, or both packages are marked
          <tt>Essential</tt>, then <prgn>dpkg</prgn> will
          automatically remove the package which is causing the
          conflict, otherwise it will halt the installation of the new
          package with an error.
        </p>

        <p>       
          <prgn>dselect</prgn> makes it hard to select conflicting
          packages, though the user can override this if they wish.
          If they do not override it then <prgn>dselect</prgn> will
          select one of the packages for removal, and the user must
          make sure it is the right one.  In the future
          <prgn>dselect</prgn> will look for the presence of a
          <tt>Replaces</tt> field to help decide which package should
          be installed and which removed.
        </p>

        <p>       
          A package will not cause a conflict merely because its
          configuration files are still installed; it must be at least
          half-installed.
        </p>

        <p>       
          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.
        </p>

        <p>       
          A <tt>Conflicts</tt> entry should almost never have an
          `earlier than' version clause.  This would prevent
          <prgn>dpkg</prgn> 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
          <prgn>dselect</prgn>, so that the use <tt>Conflicts</tt> in
          this way is likely to cause problems for `bulk run' upgrades
          and installations.
        </p>
      </sect>
        
      <sect id="virtual"><heading>Virtual packages - <tt>Provides</tt>
        </heading>

        <p> 
           As well as the names of actual (`concrete') packages, the
           package relationship fields <tt>Depends</tt>,
           <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
           <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Conflicts</tt>,
           <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt> may
           mention virtual packages.
        </p>

        <p>       
          A virtual package is one which appears in the
          <tt>Provides</tt> 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 the virtual package name appears.
        </p>

        <p>       
          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
          <example>
  Package: vm
  Depends: emacs
          </example>
          and someone else releases an xemacs package they can say
          <example>
  Package: xemacs
  Provides: emacs
          </example> and all will work in the interim (until a purely
          virtual package name is decided on and the <tt>emacs</tt>
          and <tt>vm</tt> packages are changed to use it).
        </p>

        <p>       
          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 <tt>Provides</tt> 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.
        </p>

        <p>       
          It is likely that the ability will be added in a future
          release of <prgn>dpkg</prgn> to specify a version number for
          each virtual package it provides.  This feature is not yet
          present, however, and is expected to be used only
          infrequently.
        </p>

        <p>       
          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 an alternative before the virtual.
        </p>
      </sect>
        
        
      <sect id="replaces"><heading><tt>Replaces</tt> - overwriting
      files and replacing packages
        </heading>

        <p>       
          The <tt>Replaces</tt> control file field has two purposes,
          which come into play in different situations.
        </p>

        <p>       
          Virtual packages (<ref id="virtual">) are not considered
          when looking at a <tt>Replaces</tt> field - the packages
          declared as being replaced must be mentioned by their real
          names.
        </p>
          
        <sect1><heading>Overwriting files in other packages
          </heading>

          <p>       
            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
            <tt>--force-overwrite</tt> flag is enabled by default,
            downgrading the error to a warning,
          </p>

          <p>       
            If the overwriting package declares that it replaces the
            one containing the file being overwritten then
            <prgn>dpkg</prgn> 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.
          </p>

          <p>       
            If a package is completely replaced in this way, so that
            <prgn>dpkg</prgn> 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
            <prgn>postrm</prgn> script will be run to allow the
            package to do any final cleanup required.  See <ref
            id="mscriptsinstact">.
          </p>

          <p>       
            In the future <prgn>dpkg</prgn> 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).
          </p>

          <p>       
            This usage of <tt>Replaces</tt> 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.</p>
        </sect1>
          
        <sect1><heading>Replacing whole packages, forcing their
        removal
          </heading>

          <p>       
            Secondly, <tt>Replaces</tt> allows <prgn>dpkg</prgn> and
            <prgn>dselect</prgn> to resolve which package should be
            removed when there is a conflict - see <ref id="conflicts">.  This
            usage only takes effect when the two packages <em>do</em>
            conflict, so that the two effects do not interfere with
            each other.
          </p>
        </sect1>
      </sect>
        
      <sect><heading>Defaults for satisfying dependencies - ordering
        </heading>

        <p>       
          Ordering is significant in dependency fields.
        </p>

        <p>       
          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.
        </p>

        <p>       
          In the absence of other information <prgn>dselect</prgn>
          will offer a default selection of the first named package in
          a list of alternatives.
        </p>

        <p>       
          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.
        </p>

        <p>       
          Therefore a dependency on a virtual package should contain a
          concrete package name as the first alternative, so that this
          is the default.
        </p>

        <p>       
          For example, consider the set of packages:
          <example>
  Package: glibcdoc
  Recommends: info-browser
  
  Package: info
  Provides: info-browser
  
  Package: emacs
  Provides: info-browser
          </example>
        </p>

        <p>       
          If <prgn>emacs</prgn> and <prgn>info</prgn> both have the
          same priority then <prgn>dselect</prgn>'s choice is
          essentially random.  Better would be
          <example>
  Package: glibcdoc
  Recommends: info | info-browser
          </example>
          so that <prgn>dselect</prgn> defaults to selecting the
          lightweight standalone info browser.
        </p>
      </sect>
      
  
      <sect><heading>Relationships between source and binary packages -
              <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
              <tt>Build-Conflicts</tt>, <tt>Build-Conflicts-Indep</tt>
           </heading>

        <p>
          A source package may declare a dependency or a conflict on a
          binary package.  This is done with the control file fields
          <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
          <tt>Build-Conflicts</tt>, and <tt>Build-Conflicts-Indep</tt>.  Their
          semantics is that the dependencies and conflicts they define
          must be satisfied (as defined earlier for binary packages),
          when one of the targets in <tt>debian/rules</tt> that the
          particular field applies to is invoked.

        <taglist>
          <tag><tt>Build-Depends</tt>, <tt>Build-Conflicts</tt></tag>
          <item>
            <p>
              The <tt>Build-Depends</tt> and <tt>Build-Conflicts</tt> fields apply
              to the targets
              <tt>build</tt>, <tt>binary</tt>, <tt>binary-arch</tt>
              and <tt>binary-indep</tt>.
            </p>
          </item>
          <tag><tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts-Indep</tt></tag>
          <item>
            <p>
              The <tt>Build-Depends-Indep</tt> and
              <tt>Build-Conflicts-Indep</tt> fields apply to the
              targets <tt>binary</tt> and <tt>binary-indep</tt>.
            </p>
          </item>
        </taglist>

      </p>

    </sect>


   </chapt>
    <chapt id="conffiles"><heading>Configuration file handling
      </heading>

      <p>       
        <prgn>dpkg</prgn> can do a certain amount of automatic
        handling of package configuration files.
      </p>

      <p>       
        Whether this mechanism is appropriate depends on a number of
        factors, but basically there are two approaches to any
        particular configuration file.
      </p>

      <p>       
        The easy method is to ship a best-effort configuration in the
        package, and use <prgn>dpkg</prgn>'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.
      </p>

      <p>       
        The hard method is to build the configuration file from
        scratch in the <prgn>postinst</prgn> 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.
      </p>
        
      <sect><heading>Automatic handling of configuration files by
      <prgn>dpkg</prgn>
        </heading>

        <p>       
          A package may contain a control area file called
          <tt>conffiles</tt>.  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.
        </p>

        <p>       
          When a package is upgraded <prgn>dpkg</prgn> will process
          the configuration files during the configuration stage,
          shortly before it runs the package's <prgn>postinst</prgn>
          script,
        </p>

        <p>       
          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.
        </p>

        <p>       
          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 - i.e.,
          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.
        </p>

        <p>       
          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.
        </p>

        <p>       
          When a package is installed for the first time
          <prgn>dpkg</prgn> will install the file that comes with it,
          unless that would mean overwriting a file already on the
          filesystem.
        </p>

        <p>       
          However, note that <prgn>dpkg</prgn> will <em>not</em>
          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.
        </p>

        <p>       
          Note that a package should <em>not</em> modify a
          <prgn>dpkg</prgn>-handled conffile in its maintainer
          scripts.  Doing this will lead to <prgn>dpkg</prgn> giving
          the user confusing and possibly dangerous options for
          conffile update when the package is upgraded.</p>
      </sect>
        
      <sect><heading>Fully-featured maintainer script configuration
      handling
        </heading>

        <p>       
          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
          <prgn>postinst</prgn> script.
        </p>

        <p>       
          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.
        </p>

        <p>       
          When using this method there are a couple of important
          issues which should be considered:
        </p>

        <p>       
          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.
        </p>

        <p>       
          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 <tt>/usr/sbin</tt>, by convention called
          <tt><var>package</var>config</tt> and then run that if
          appropriate from the post-installation script.  The
          <tt><var>package</var>config</tt> 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 <tt>--force</tt> flag to
          overwrite it.</p></sect>
    </chapt>
      
      
      
    <chapt id="alternatives"><heading>Alternative versions of an interface -
        <prgn>update-alternatives</prgn>
      </heading>

      <p>       
        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.
      </p>

      <p>       
        For example, there are several versions of the <prgn>vi</prgn>
        editor, and there is no reason to prevent all of them from
        being installed at once, each under their own name
        (<prgn>nvi</prgn>, <prgn>vim</prgn> or whatever).
        Nevertheless it is desirable to have the name <tt>vi</tt>
        refer to something, at least by default.
      </p>

      <p>       
        If all the packages involved cooperate, this can be done with
        <prgn>update-alternatives</prgn>.
      </p>

      <p>       
        Each package provides its own version under its own name, and
        calls <prgn>update-alternatives</prgn> in its postinst to
        register its version (and again in its prerm to deregister
        it).
      </p>

      <p>       
        See the manpage <manref name="update-alternatives"
        section="8"> for details.
      </p>

      <p>       
        If <prgn>update-alternatives</prgn> does not seem appropriate
        you may wish to consider using diversions instead.</p>
    </chapt>
      
      
    <chapt id="diversions"><heading>Diversions - overriding a
    package's version of a file
      </heading>

      <p>       
        It is possible to have <prgn>dpkg</prgn> 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.
      </p>

      <p>       
        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).
      </p>

      <p>       
        Before deciding to use a diversion, read <ref
        id="alternatives"> to see if you really want a diversion
        rather than several alternative versions of a program.
      </p>

      <p>       
        There is a diversion list, which is read by <prgn>dpkg</prgn>,
        and updated by a special program <prgn>dpkg-divert</prgn>.
        Please see <manref name="dpkg-divert" section="8"> for full
        details of its operation.
      </p>

      <p>       
        When a package wishes to divert a file from another, it should
        call <prgn>dpkg-divert</prgn> in its preinst to add the
        diversion and rename the existing file.  For example,
        supposing that a <prgn>smailwrapper</prgn> package wishes to
        install a wrapper around <tt>/usr/sbin/smail</tt>:
        <example>
  if [ install = "$1" ]; then
     dpkg-divert --package smailwrapper --add --rename \
        --divert /usr/sbin/smail.real /usr/sbin/smail
  fi
        </example> Testing <tt>$1</tt> is necessary so that the script
        doesn't try to add the diversion again when
        <prgn>smailwrapper</prgn> is upgraded.  The <tt>--package
        smailwrapper</tt> ensures that <prgn>smailwrapper</prgn>'s
        copy of <tt>/usr/sbin/smail</tt> can bypass the diversion and
        get installed as the true version.
      </p>

      <p>       
        The postrm has to do the reverse:
        <example>
  if [ remove = "$1" ]; then
     dpkg-divert --package smailwrapper --remove --rename \
        --divert /usr/sbin/smail.real /usr/sbin/smail
  fi
        </example>
      </p>

      <p>       
        Do not attempt to divert a file which is vitally important for
        the system's operation - when using <prgn>dpkg-divert</prgn>
        there is a time, after it has been diverted but before
        <prgn>dpkg</prgn> has installed the new version, when the file
        does not exist.</p>
    </chapt>
      
      
    <chapt id="sharedlibs"><heading>Shared libraries
      </heading>

      <p>       
        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.
      </p>

      <p>       
        Firstly, your package should install the shared libraries
        under their normal names.  For example, the
        <prgn>libgdbm1</prgn> package should install
        <tt>libgdbm.so.1.7.3</tt> as
        <tt>/usr/lib/libgdbm.so.1.7.3</tt>.  The files should not be
        renamed or relinked by any prerm or postrm scripts;
        <prgn>dpkg</prgn> will take care of renaming things safely
        without affecting running programs, and attempts to interfere
        with this are likely to lead to problems.
      </p>

      <p>       
        Secondly, your package should include the symlink that
        <prgn>ldconfig</prgn> would create for the shared libraries.
        For example, the <prgn>libgdbm1</prgn> package should include
        a symlink from <tt>/usr/lib/libgdbm.so.1</tt> to
        <tt>libgdbm.so.1.7.3</tt>.  This is needed so that
        <prgn>ld.so</prgn> can find the library in between the time
        <prgn>dpkg</prgn> installs it and <prgn>ldconfig</prgn> is run
        in the <prgn>postinst</prgn> script.  Futhermore, and <em>this
        is very important</em>, the library must be placed before the
        symlink pointing to it in the <tt>.deb</tt> file.  This is so
        that by the time <prgn>dpkg</prgn> comes to install the
        symlink (overwriting the previous symlink pointing at an older
        version of the library) the new shared library is already in
        place.  Currently the way to ensure the ordering is done
        properly is to install the library in the appropriate
        <tt>debian/tmp/.../lib</tt> directory before creating the
        symlink, by putting the commands in the <tt>debian/rules</tt>
        in the appropriate order.  Whether this has been done
        correctly can be checked by performing an <tt>ls -f</tt>.
      </p>

        <!--
        next Paragraph added to close Bug #5299, Guy Maor
        -->
        
      <p>       
        Thirdly, the development package should contain a symlink for
        the shared library without a version number.  For example, the
        <tt>libgdbm1-dev</tt> package should include a symlink from
        <tt>/usr/lib/libgdm.so</tt> to <tt>libgdm.so.1.7.3</tt>.  This
        symlink is needed by <prgn>ld</prgn> when compiling packages
        as it will only look for <tt>libgdm.so</tt> and
        <tt>libgdm.a</tt> when compiling dynamically or statically,
        respectively.
      </p>

        <!--
        next paragraph changed by Christian Schwarz (see policy weekly #6)
        -->
        
      <p>       
        Any package installing shared libraries in a directory that's listed
        in <tt>/etc/ld.so.conf</tt> or in one of the default library
        directories of <prgn>ld.so</prgn> (currently, these are <tt>/usr/lib</tt>
        and <tt>/lib</tt>) must call <prgn>ldconfig</prgn> in its <prgn>postinst</prgn>
        script if and only if the first argument is `configure'. However, it
        is important not to call <prgn>ldconfig</prgn> in the postrm or preinst
        scripts in the case where the package is being upgraded (see <ref
                                                                          id="unpackphase">), as <prgn>ldconfig</prgn> will see the temporary names
        that <prgn>dpkg</prgn> uses for the files while it is
        installing them and will make the shared library links point
        to them, just before <prgn>dpkg</prgn> continues the
        installation and removes the links!
      </p>

        <!-- 
        moved from section 2.2 , DMorris 
        -->
        
      <sect id="shlibs"><heading>The <tt>shlibs</tt> File Format
        </heading>

        <p>       
          This file is for use by <prgn>dpkg-shlibdeps</prgn> and is
          required when your package provides shared libraries.
        </p>

        <p>       
          Each line is of the form:
          <example>
 <var>library-name</var> <var>version-or-soname</var> <var>dependencies ...</var>
          </example>
        </p>

        <p>       
          <var>library-name</var> is the name of the shared library,
          for example <tt>libc5</tt>.
        </p>

        <p>       
          <var>version-or-soname</var> is the soname of the library -
          ie, the thing that must exactly match for the library to be
          recognised by <prgn>ld.so</prgn>.  Usually this is major
          version number of the library.
        </p>

        <p>       
          <var>dependencies</var> 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 <ref id="depsyntax">.
        </p>

        <p>       
          For example, if the package <tt>foo</tt> contains
          <tt>libfoo.so.1.2.3</tt>, where the soname of the library is
          <tt>libfoo.so.1</tt>, and the first version of the package
          which contained a minor number of at least <tt>2.3</tt> was
          <var>1.2.3-1</var>, then the package's <var>shlibs</var>
          could say:
          <example>
  libfoo 1      foo (>= 1.2.3-1)
          </example>
        </p>

        <p>       
          The version-specific dependency is to avoid warnings from
          <prgn>ld.so</prgn> about using older shared libraries with
          newer binaries.</p>
      </sect>
        
      <sect><heading>Further Technical information on
          <tt>shlibs</tt></heading>

        
        <!-- 
        following section mostly provided by Heiko Schlittermann
        edited by DMorris
        -->
        
        <sect1><heading><em>What</em> are the <tt>shlibs</tt> files?
          </heading>

          <p>       
            The <tt>debian/shlibs</tt> file provides a way of checking
            for shared library dependencies on packaged binaries.
            They are intended to be used by package maintainers to
            make their lives easier.
          </p>

          <p>       
            Other <tt>shlibs</tt> files that exist on a Debian system are
            <list>
              <item> <p><tt>/etc/dpkg/shlibs.default</tt></p></item>
              <item> <p><tt>/etc/dpkg/shlibs.override</tt></p></item>
              <item> <p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
              <item> <p><tt>debian/shlibs.local</tt></p></item>
            </list> 
            These files are used by <prgn>dpkg-shlibdeps</prgn> when
            creating a binary package.</p>
        </sect1>
          
        <sect1><heading><em>How</em> does <prgn>dpkg-shlibdeps</prgn>
        work?
          </heading>

          <p>       
            <prgn>dpkg-shlibdeps</prgn> calls <prgn>ldd</prgn> to
            determine the shared libraries used by the compiled
            binaries passed through its command line.
          </p>

          <p>       
            For each shared library, <prgn>dpkg-shlibdeps</prgn> needs to know 
            <list compact="compact">
              <item><p>the package containing the library, and</p></item>
              <item><p>the library version number,</p></item>

            </list>       <p>
            it scans the following files in this order.
            <enumlist compact="compact">
              <item><p><tt>debian/shlibs.local</tt></p></item>
              <item><p><tt>/etc/dpkg/shlibs.override</tt></p></item>
              <item><p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
              <item><p><tt>/etc/dpkg/shlibs.default</tt></p></item>
            </enumlist></p>
        </sect1>
          
        <sect1><heading><em>Who</em> maintains the various
        <tt>shlibs</tt> files?
          </heading>

          <p>       
            <list compact="compact">
              <item>
                <p><tt>/etc/dpkg/shlibs.default</tt> - the maintainer
                  of dpkg</p>
              </item>
              <item>
                <p>
                  <tt>/var/lib/dpkg/info/<var>package</var>.shlibs</tt>
                  - the maintainer of each package</p>
              </item>
              <item>
                <p>
                  <tt>/etc/dpkg/shlibs.override</tt> - the local
                  system administrator</p>
              </item>
              <item>
                <p><tt>debian/shlibs.local</tt> - the maintainer of
                the package
                </p>
              </item> 
            </list> 
            The <tt>shlibs.default</tt> file is managed by
            <prgn>dpkg</prgn>. The entries in <tt>shlibs.default</tt>
            that are provided by <prgn>dpkg</prgn> are just there to
            fix things until the shared library packages all have
            <tt>shlibs</tt> files.
          </p>
        </sect1>

        <sect1><heading><em>How</em> to use <prgn>dpkg-shlibdeps</prgn> and
            the <tt>shlibs</tt> files?
          </heading>
            
          <sect2><heading>If your package doesn't provide a shared
          library
            </heading>

            <p>       
              Put a call to <prgn>dpkg-shlibdeps</prgn> into your
              <tt>debian/rules</tt> file.  If your package contains
              only binaries (e.g. no scripts) use:
              <example>
  dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/*
              </example>
              If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
              done. If it does complain you might need to create your
              own <tt>debian/shlibs.local</tt> file.</p>
          </sect2>

          <sect2><heading>If your package provides a shared library
            </heading>

            <p>       
              Create a <tt>debian/shlibs</tt> file and let
              <tt>debian/rules</tt> install it in the control area:           
              <example>
  install -m644 debian/shlibs debian/tmp/DEBIAN
              </example>
              If your package contains additional binaries see above.
            </p>
          </sect2>
        </sect1>

        <sect1><heading><em>How</em> to write
        <tt>debian/shlibs.local</tt>
          </heading>

          <p>       
            This file is intended only as a <em>temporary</em> fix if
            your binaries depend on a library which doesn't provide
            its own <tt>/var/lib/dpkg/info/*.shlibs</tt> file yet.
          </p>

          <p>       
            Let's assume you are packaging a binary <tt>foo</tt>. Your
            output in building the package might look like this.            
            <example>
  $ ldd foo
  libbar.so.1 => /usr/X11R6/lib/libbar.so.1.0
  libc.so.5 => /lib/libc.so.5.2.18
  libX11.so.6 => /usr/X11R6/lib/libX11.so.6.0
            </example>
            And when you ran <prgn>dpkg-shlibdeps</prgn>
            <example>
  $ dpkg-shlibdeps -o foo
  dpkg-shlibdeps: warning: unable to find dependency information 
  for shared library libbar 
  (soname 1, path /usr/X11R6/lib/libbar.so.1.0, dependency field Depends)
  shlibs:Depends=elf-x11r6lib, libc5 (>= 5.2.18)
            </example>
            The <prgn>foo</prgn> binary depends on the
            <prgn>libbar</prgn> shared library, but no package seems
            to provide a <tt>*.shlibs</tt> file in
            <tt></tt>var/lib/dpkg/info/.  Let's determine the package
            responsible:
          </p>

          <p>
            <example>
  $ dpkg -S /usr/X11R6/lib/libbar.so.1.0
  bar1: /usr/X11R6/lib/libbar.so.1.0
  $ dpkg -s bar1 | grep Version
  Version: 1.0-1
            </example>
            This tells us that the <prgn>bar1</prgn> package, version
            1.0-1 is the one we are using. Now we can create our own
            <tt>debian/shlibs.local</tt> to temporarly fix the above
            problem. Include the following line into your
            <tt>debian/shlibs.local</tt> file.
            <example>
  libbar 1 bar1 (>= 1.0-1)
            </example>
            Now your package build should work. As soon as the
            maintainer of <prgn>libbar1</prgn> provides a
            <tt>shlibs</tt> file, you can remove your
            <tt>debian/shlibs.local</tt> file.
          </p>
        </sect1>
      </sect>
    </chapt>

    <chapt id="methif"><heading><prgn>dselect</prgn>'s interface to
    its installation methods
      </heading>

      <p>       
        <prgn>dselect</prgn> calls scripts from its installation
        methods when it needs to actually access data from the
        distribution.  The core program <prgn>dselect</prgn> itself
        just calls these scripts and provides the package and access
        method selection interfaces.  The installation methods are
        responsible for invoking <prgn>dpkg</prgn> as appropriate.
      </p>

      <p>       
        Each installation method has three scripts:
        <list compact="compact">
          <item><p>Setup installation parameters.</p></item>
          <item><p>Update list of available packages.</p></item>
          <item><p>Install.</p></item>
        </list>

      <p>       
        <prgn>dselect</prgn> searches for methods in
        <tt>/usr/lib/dpkg/methods</tt> and
        <tt>/usr/local/lib/dpkg/methods</tt>.
      </p>
        
      <sect><heading>Functions of the method scripts
        </heading>

        <p>       
          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
          <tt>.deb</tt> files can be found, or the tape or floppy
          device to install from.  It should store the responses under
          <tt>/var/lib/dpkg/methods</tt> - see below.  If no available
          packages list is available it should perhaps offer to scan
          the available packages.
        </p>

        <p>       
          The update script should obtain a list of available packages
          if possible, and run <tt>dpkg --update-avail</tt>, <tt>dpkg
          --merge-avail</tt> and/or <tt>dpkg --forget-old-unavail</tt>
          to load it into <prgn>dpkg</prgn> and <prgn>dselect</prgn>'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 <tt>dpkg --record-avail</tt>.
        </p>

        <p>       
          The install script should feed all the available
          <tt>.deb</tt> files to <tt>dpkg --iGOEB</tt> (this is
          equivalent to <tt>dpkg --install
            --refuse-downgrade --selected-only --skip-same-version
            --auto-deconfigure</tt>).  The <tt>-R</tt>
          (<tt>--recursive</tt>) option for traversing subdirectories
          may also be useful here).
        </p>

        <p>       
          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.
        </p>

        <p>       
          If a method script succeeds (returns a zero exit status)
          <prgn>dselect</prgn> will return immediately to the main
          menu, with the `next' option highlighted ready for the user
          to select it.  If it fails <prgn>dselect</prgn> will display
          a message and wait for the user to hit return.</p>
      </sect>
        
      <sect><heading>Location and arguments of the method scripts
        </heading>

        <p>       
          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.
        </p>

        <p>       
          Each group of methods implemented by the same set of scripts
          should have a subdirectory
          <tt>/usr/lib/dpkg/methods/<var>group</var></tt> or
          <tt>/usr/local/lib/dpkg/methods/<var>group</var></tt>,
          containing:
          <taglist compact="compact">
            <tag><tt>names</tt></tag>
            <item><p>a list of user-visible methods provided by these scripts.</p>
            </item>
            <tag><tt>setup</tt></tag>
            <tag><tt>update</tt></tag>
            <tag><tt>install</tt></tag>
            <item><p>executable programs, the scripts themselves.</p>
            </item>
            <tag><tt>desc.<var>option</var></tt></tag>
            <item><p>description file.</p></item>
          </taglist>
        </p>

        <p>       
          <tt>names</tt> will be formatted as a list of lines, each containing:
          <example>
 <var>sequence</var> <var>method</var> <var>summary</var>
          </example>
        </p>
        <p>       
          <var>sequence</var> is a two-digit number that will be used
          much like <tt>rc.d</tt> prefixes to control the order in the
          main menu.  If in doubt use 50.
        </p>

        <p>       
          <var>method</var> is a name which is displayed by
          <prgn>dselect</prgn> as the name of the method, and which
          will be passed to <tt>setup</tt>, <tt>update</tt> and
          <tt>unpack</tt> as their first argument.
        </p>

        <p>       
          <var>summary</var> is the brief description string for
          <prgn>dselect</prgn>'s menu.
        </p>

        <p>       
          Each of the three scripts gets the same three arguments:
          <var>vardir</var>, <var>group</var> and <var>method</var>.
          <var>vardir</var> is the base directory for storing
          <prgn>dpkg</prgn> and <prgn>dselect</prgn>'s state, usually
          <tt>/var/lib/dpkg</tt>; this is passed in so that the
          <tt>--admindir</tt> option to <prgn>dselect</prgn> is
          honoured).
        </p>

        <p>       
          Each option may have an extended description in
          <tt>desc.<var>option</var></tt>.  This should be formatted
          like the extended description part of a <tt>Description</tt>
          field entry <em>shifted one character to the left</em>.
        </p>

        <p>       
          <tt><var>vardir</var>/methods</tt> will exist, and a method
          group may use a
          <tt><var>vardir</var>/methods/<var>group</var></tt>
          directory to store its state.
        </p>

        <p>       
          The group name and method name must follow the rules for C
          identifiers.
        </p>
      </sect>
    </chapt>
      
    <chapt id="conversion"><heading>Conversion procedure from old
    source packages
      </heading>

      <p>       
        This is a brief summary of the procedure for converting a
        pre-2.0.0.0-format source package into the new format.
      </p>

      <p>       
        You are strongly advised to download and examine the <prgn>hello</prgn>
        package, and to read the section in the <prgn>dpkg</prgn> programmers'
        manual describing the source packaging tools.  More detail about the
        exact functionality of these tools is available in 
        <manref name="dpkg-source"  section="1">.
      </p>

      <p>       
        <list>
          <item>
            <p>
              Download the original source code from wherever it can
              be found and do any rearrangement required to make it
              look like the original tree of the Debian source.  Put
              it in
              <tt><var>package</var>-<var>upstream-version</var>.orig/</tt>
              or
              <tt><var>package</var>_<var>upstream-version</var>.orig.tar.gz</tt>.
            </p>
          </item>
          
          <item>
            <p>
              Rename all files <tt>debian.*</tt> to <tt>debian/*</tt>.
              There may be some exceptions to this, but this is a good
              start.</p>
          </item>

          <item>
            <p>
              Edit the <tt>debian/changelog</tt> - create or rename it
              if necessary.  Add a new revision to the top with the
              appropriate details, and a local variables entry to the
              bottom to set Emacs to the right mode:
              <example>
  Local variables:
  mode: debian-changelog
  End:
              </example>
            </p>
          </item>
          
          <item>
            <p>
              Edit/create <tt>debian/control</tt>:
              <list compact="compact">
                <item>
                  <p>
                    Remove the <tt>Version</tt> field.  If it is
                    generated unusually (not equal to the source
                    version) you must use the -v option to
                    dpkg-gencontrol (see below).  <tt>Section</tt>,
                    <tt>Priority</tt>, <tt>Maintainer</tt> go above
                    the first blank line, most of the rest
                    below.
                  </p>
                </item>
                
                <item>
                  <p>
                    Reorder the fields and add a blank line at an
                    appropriate point, separating the source package
                    fields from the binary package fields.
                  </p>
                </item>
                
                <item>
                  <p>Add the <tt>Source</tt> field.</p></item>
                
                <item>
                  <p>
                    Add the <tt>Standards-Version</tt> field.  (Please
                    check out the Debian Policy Manual for details
                    about this field.)</p>
                </item>
                
                <item>
                  <p>
                    Change the <tt>Architecture</tt> field for each
                    package to <tt>any</tt>, <tt>all</tt> or whatever.
                    If there isn't an <tt>Architecture</tt> field add
                    one.</p>
                </item>
                
                <item>
                  <p>
                    If any other use of sed or things used to happen
                    to make the binary control files use
                    <prgn>dpkg-gencontrol</prgn>'s variable
                    substitution features to achieve the same effect.
                    Use <tt>debian/substvars</tt> if you need to put
                    unusally-generated information (apart from details
                    of <tt>.deb</tt> files) in the <tt>.changes</tt>
                    file too.</p>
                </item>
              </list>
            </p>
          </item>
          
          <item>
            <p>Edit the <tt>debian/rules</tt>:
              <list compact="compact">
                <item>
                  <p>
                    Remove the <prgn>source</prgn> and
                    <prgn>diff</prgn> and any <prgn>changes</prgn> and
                    <prgn>dist</prgn> targets.  These things now
                    happen in a package-independent way and are not
                    done by <tt>debian/rules</tt>.</p>
                </item>
                <item>
                  <p>
                    Split the <prgn>binary</prgn> target into
                    <prgn>binary-arch</prgn> and
                    <prgn>binary-indep</prgn>; in many cases all of
                    <prgn>binary</prgn> should go into
                    <prgn>binary-arch</prgn>.  Create the
                    <prgn>binary</prgn> target and the unused of the
                    two other <prgn>binary-*</prgn> targets if there
                    is one - you can copy the ones from the
                    <prgn>hello</prgn> package.</p>
                </item>
                <item>
                  <p>
                    Change the <prgn>binary</prgn> target to use
                    <prgn>dpkg-gencontrol</prgn> to make the package
                    control file(s).  Move it to after all the files
                    have been installed but just before the last
                    <prgn>chown</prgn> and <prgn>chmod</prgn> in the
                    target.</p>
                </item>
                <item>
                  <p>
                    Change occurrences of <tt>debian-tmp</tt> to
                    <tt>debian/tmp</tt>.</p>
                </item>
                <item>
                  <p>
                    Change occurrences of
                    <tt>debian.{post,pre}{inst,rm}</tt> to
                    <tt>debian/*</tt>.</p>
                </item>
                <item>
                  <p>
                    Remove the version number setting at the top, if
                    there is one.</p>
                </item>
                <item>
                  <p>
                    Ensure that the package's Debian-specific and
                    upstream changelogs are installed.</p>
                </item>
              </list>
            </p>
          </item>
          
          <item>
            <p>
              Change the package to use <prgn>dpkg-shlibdeps</prgn> to
              determine its shared library dependencies and substitute
              them in.  Shared library dependencies should no longer
              be hardwired in the source package.</p>
          </item>
          
          <item>
            <p>
              Check that the <tt>debian/README</tt> is really the
              copyright file, and if so rename it to
              <tt>debian/copyright</tt> and edit <tt>debian/rules</tt>
              to cope with this and to change the installation of the
              copyright file from
              <tt>/usr/doc/<var>package</var>/copyright</tt> to
              <tt>/usr/doc/copyright/<var>package</var></tt>.  If it
              isn't then find <tt>debian/copyright</tt> and decide
              what to do with the <tt>README</tt>.</p>
          </item>
          
          <item>
            <p>Check for various other anachronisms and problems:
              <list compact="compact">
                <item>
                  <p>
                    Remove any <tt>Package_Revision</tt>,
                    <tt>Package-Revision</tt> or <tt>Revision</tt>
                    fields.</p>
                </item>
                <item>
                  <p>
                    Rename <tt>Optional</tt> to <tt>Suggests</tt>,
                    <tt>Recommended</tt> to
                    <tt>Recommends</tt>.</p>
                </item>
                <item>
                  <p>
                    Change
                    <tt>/usr/doc/examples/<var>package</var></tt> to
                    <tt>/usr/doc/<var>package</var>/examples</tt>.</p>
                </item>
                <item>
                  <p>
                    Make sure that manpages are installed
                    compressed.</p>
                </item>
                <item>
                  <p>
                    Check that the description has an extended
                    description, is well-formatted and meaningful and
                    helpful to people wanting to know whether to
                    install a package.</p>
                </item>
              </list>
            </p>
          </item>
          
          <item>
            <p>Look everything over.</p></item>
          
          <item>
            <p>
              Do a test build using <tt>dpkg-buildpackage -us -uc -sa
                -r<var>whatever</var></tt>.  Check the permissions and
              locations of files in the resulting package by examining
              the output of <tt>dpkg-deb --contents</tt>, and check
              that the source build happened OK.  Test install the
              binary package(s) and test extract the source
              package(s).</p>
          </item>
          
          <item>
            <p>
              Sign the release: either rebuild everything with
              <tt>dpkg-buildpackage -sa</tt>, or PGP-sign the
              <tt>.dsc</tt>, rebuild the <tt>.changes</tt> using
              <tt>dpkg-genchanges -sa</tt>, and then PGP-sign the
              <tt>.changes</tt>.</p>
          </item>
          
        </list>
      </p>

      <p>       
        The use of <tt>-sa</tt> on <prgn>dpkg-buildpackage</prgn> and
        <prgn>dpkg-genchanges</prgn> is important when doing the first
        build/uploading of a new-format source package.  Unless this
        happens to be Debian revision <tt>0</tt> or <tt>1</tt> by
        default the original source tarfile will not be included in
        the uploaded files listed in the <tt>.changes</tt> file, and
        so it won't be installed on the FTP site.  <tt>-sa</tt>
        requests that the original source be included
        regardless.</p>
    </chapt>
    
  </book>
</debiandoc>