dpkg/man/en/deb-control.5.sgml

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

<refentry id="deb-control.5">
  <refmeta>
    <refentrytitle>deb-control</refentrytitle>
    <manvolnum>5</manvolnum>
    <refmiscinfo class="source">Debian Project</refmiscinfo>
    <refmiscinfo class="manual">dpkg utilities</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>deb-control</refname>
    <refpurpose>Debian packages' master control file format</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <synopsis><filename>control</filename></synopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para>
      Each Debian package contains the master <filename>control</filename>
      file, which contains a number of fields. Each field begins with a tag,
      such as <emphasis>Package</emphasis> or <emphasis>Version</emphasis>
      (case insensitive), followed by a colon, and the body of the field.
      Fields are delimited only by field tags. In other words, field text may
      be multiple lines in length, but the installation tools will generally
      join lines when processing the body of the field (except in the case of
      the <emphasis>Description</emphasis> field, see below).
    </para>
  </refsect1>

  <refsect1>
    <title>Required Fields</title>

    <variablelist>
      <varlistentry>
	<term>
	  <cmdsynopsis>
	    <arg choice="plain">Package: <replaceable>package_name</replaceable></arg>
	  </cmdsynopsis>
	</term>

	<listitem>
	  <para>
	    The value of this field determines the package name, and is used to
	    generate file names by most installation tools.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <cmdsynopsis>
	    <arg choice="plain">Version: <replaceable>version_string</replaceable></arg>
	  </cmdsynopsis>
	</term>

	<listitem>
	  <para>
	    Typically, this is the original package's version number in
	    whatever form the program's author uses. It may also include a
	    Debian revision number (for non-native packages). If both version
	    and revision are supplied, they are seperated by a hyphen
	    (<keycap>-</keycap>. For this reason, the original version may not
	    have a hyphen in its version number.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <cmdsynopsis>
	    <arg choice="plain">Maintainer: <replaceable>fullname</replaceable> <replaceable>email</replaceable></arg>
	  </cmdsynopsis>
	</term>

	<listitem>
	  <para>
	    Should be in the format `Joe Bloggs &lt;jbloggs@foo.com&gt;', and
	    is typically the person who created the package, as opposed to the
	    author of the software that was packaged.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <cmdsynopsis>
	    <arg choice="plain">Description: <replaceable>short description</replaceable><sbr> <replaceable>long description</replaceable></arg>
	  </cmdsynopsis>
	</term>

	<listitem>
	  <para>
	    The format for the package description is a short brief summary on
	    the first line (after the "Description" field). The following lines
	    can be used as a longer, more detailed description. Each line of
	    the long description must be preceded by a space, and blank lines
	    in the long desription must contain a single '.' following the
	    preceding space.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Optional Fields</title>

    <variablelist>
      <varlistentry>
	<term>
	  <cmdsynopsis>
	    <arg choice="plain">Section: <replaceable>section</replaceable></arg>
	  </cmdsynopsis>
	</term>

	<listitem>
	  <para>
	    This is a general field that gives the package a category based on
	    the software that it installs. Some common sections are `utils',
	    `net', `mail', `text', `x11' etc.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <cmdsynopsis>
	    <arg choice="plain">Priority: <replaceable>priority</replaceable></arg>
	  </cmdsynopsis>
	</term>

	<listitem>
	  <para>
	    Sets the importance of this package in relation to the system as a
	    whole.  Common priorities are `required', `standard', `optional',
	    `extra' etc.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      In Debian, the <emphasis>Section</emphasis> and
      <emphasis>Priority</emphasis> fields have a defined set of accepted
      values based on the Policy Manual. They are used to decide how the
      packages are layed out in the archive. A list of these can be
      obtained from the latest version of
      <emphasis>debian-policy</emphasis> package.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <cmdsynopsis>
	    <arg choice="plain">Essential: 
	      <group choice="req">
	        <arg>yes</arg>
		<arg>no</arg>
	      </group>
	    </arg>
	  </cmdsynopsis>
	</term>

	<listitem>
	  <para>
	    This field is usually only needed when the answer is `yes'. It
	    denotes a package that is required for proper operation of the
	    system. <command>dpkg</command> or any other installation tool will
	    not allow an <emphasis>Essential</emphasis> package to be removed
	    (at least not without using one of the force options).
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <cmdsynopsis>
	    <arg choice="plain">Architecture:
	      <group choice="req">
	        <arg>&lt;arch&gt;</arg>
		<arg>all</arg>
	      </group>
	    </arg>
	  </cmdsynopsis>
	</term>

	<listitem>
	  <para>
	    The architecture specifies which type of hardware this package was
	    compiled for. Common architectures are `i386', `m68k', `sparc',
	    `alpha', `powerpc' etc. Note that the <emphasis>all</emphasis>
	    option is meant for packages that are architecture independent.
	    Some examples of this are shell or python scripts, or
	    documentation.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <cmdsynopsis>
	    <arg choice="plain">Source: <replaceable>source_name</replaceable></arg>
	  </cmdsynopsis>
	</term>

	<listitem>
	  <para>
	    The name of the source package that this binary package came from,
	    if different than the name of the package itself.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <cmdsynopsis>
	    <arg choice="plain" rep="repeat">Depends: <replaceable>package</replaceable></arg>
	  </cmdsynopsis>
	</term>

	<listitem>
	  <para>
	    List of packages that are required for this package to provide a
	    non-trivial amount of functionality.  The package maintenance
	    software will not allow a package to be installed if the packages
	    listed in its <emphasis>Depends</emphasis> field are not installed
	    (at least not without using the force options), and will run the
	    postinst scripts of packages listed in Depends: fields before those
	    of the packages which depend on them, and run prerm scripts before.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <cmdsynopsis>
	    <arg choice="plain" rep="repeat">Pre-Depends: <replaceable>package</replaceable></arg>
	  </cmdsynopsis>
	</term>

	<listitem>
	  <para>
	    List of packages that must be installed <emphasis>and</emphasis>
	    configured before this one can be installed. This is usually used
	    in the case where this package requires another package for running
	    its preinst script.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <cmdsynopsis>
	    <arg choice="plain" rep="repeat">Recommends: <replaceable>package</replaceable></arg>
	  </cmdsynopsis>
	</term>

	<listitem>
	  <para>
	    Lists packages that would be found together with this one in all
	    but unusual installations.  The package maintenance software will
	    warn the user if they install a package without those listed in its
	    <emphasis>Recommends</emphasis> field.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <cmdsynopsis>
	    <arg choice="plain" rep="repeat">Suggests: <replaceable>package</replaceable></arg>
	  </cmdsynopsis>
	</term>

	<listitem>
	  <para>
	    Lists packages that are related to this one and can perhaps enhance
	    its usefulness, but without which installing this package is
	    perfectly reasonable.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      The syntax of <emphasis>Depends</emphasis>,
      <emphasis>Pre-Depends</emphasis>, <emphasis>Recommends</emphasis> and
      <emphasis>Suggests</emphasis> fields is a list of groups of alternative
      packages.  Each group is a list of packages separated by vertical bar (or
      <keysym>pipe</keysym>) symbols, `<keycode>|</keycode>'.  The groups are
      separated by commas.  Commas are to be read as `AND', and pipes as `OR',
      with pipes binding more tightly.  Each item is a package name optionally
      followed by a version number specification in parentheses.
    </para>

    <para>
      A version number may start with a `&gt;&gt;', in which case any later
      version will match, and may specify or omit the Debian packaging revision
      (separated by a hyphen). Accepted version relationships are "&gt;&gt;"
      for greater than, "&lt;&lt;" for less than, "&gt;=" for greater than or
      equal to, "&lt;=" for less than or equal to, and "=" for equal to.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <cmdsynopsis>
	    <arg choice="plain" rep="repeat">Conflicts: <replaceable>package</replaceable></arg>
	  </cmdsynopsis>
	</term>

	<listitem>
	  <para>
	    Lists packages that conflict with this one, for example by
	    containing files with the same names. The package maintenance
	    software will not allow conflicting packages to be installed at the
	    same time. Two conflicting packages should each include a
	    <emphasis>Conflicts</emphasis> line mentioning the other.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <cmdsynopsis>
	    <arg choice="plain" rep="repeat">Replaces: <replaceable>package</replaceable></arg>
	  </cmdsynopsis>
	</term>

	<listitem>
	  <para>
	    List of packages files from which this one replaces. This is used
	    for allowing this package to overwrite the files of another package
	    and is usually used with the <emphasis>Conflicts</emphasis> field
	    to force removal of the other package, if this one also has the
	    same files as the conflicted package.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <cmdsynopsis>
	    <arg choice="plain" rep="repeat">Provides: <replaceable>package</replaceable></arg>
	  </cmdsynopsis>
	</term>

	<listitem>
	  <para>
	    This is a list of virtual packages that this one provides. Usuaully
	    this is used in the case of several packages all providing the same
	    service. For example, sendmail and exim can can serve as a mail
	    server, so they provide a common package (`mail-transport-agent')
	    on which other packages can depend. This will allow sendmail or
	    exim to serve as a valid option to satisy the dependency. This
	    prevents the packages that depend on a mail server from having to
	    know the package names for all of them, and using `|' to separate
	    the list.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      The syntax of <emphasis>Conflicts</emphasis>,
      <emphasis>Replaces</emphasis> and <emphasis>Provides</emphasis> is a list
      of package names, separated by commas (and optional whitespace). In the
      <emphasis>Conflicts</emphasis> field, the comma should be read as `OR'.
      An optional version can also be given with the same syntax as above for
      the <emphasis>Conflicts</emphasis> and <emphasis>Replaces</emphasis>
      fields.
    </para>
  </refsect1>

  <refsect1><title>Example</title>

    <literallayout>
Package: grep
Essential: yes
Priority: required
Section: base
Maintainer: Wichert Akkerman &lt;wakkerma@debian.org&gt;
Architecture: sparc
Version: 2.4-1
Pre-Depends: libc6 (&gt;= 2.0.105)
Provides: rgrep
Conflicts: rgrep
Description: GNU grep, egrep and fgrep.
 The GNU family of grep utilities may be the "fastest grep in the west".
 GNU grep is based on a fast lazy-state deterministic matcher (about
 twice as fast as stock Unix egrep) hybridized with a Boyer-Moore-Gosper
 search for a fixed string that eliminates impossible text from being
 considered by the full regexp matcher without necessarily having to
 look at every character. The result is typically many times faster
 than Unix grep or egrep. (Regular expressions containing backreferencing
 will run more slowly, however.)
     </literallayout>
  </refsect1>

  <refsect1>
    <title>See Also</title>

    <para>
      <citerefentry>
        <refentrytitle>deb</refentrytitle>
	<manvolnum>5</manvolnum>
      </citerefentry>,

      <citerefentry>
        <refentrytitle>dpkg</refentrytitle>
	<manvolnum>8</manvolnum>
      </citerefentry>,

      <citerefentry>
        <refentrytitle>dpkg-deb</refentrytitle>
	<manvolnum>1</manvolnum>
      </citerefentry>
    </para>
  </refsect1>
</refentry>