| .\" Author: Raul Miller |
| .\" Includes text from the debian Guidelines by Ian Jackson, Ian Murdock |
| .TH deb\-control 5 "2011-08-14" "Debian Project" "Debian" |
| .SH NAME |
| deb\-control \- Debian packages' master control file format |
| . |
| .SH SYNOPSIS |
| control |
| . |
| .SH DESCRIPTION |
| Each Debian package contains the master `control' file, which contains |
| a number of fields, or comments when the line starts with \fB'#'\fP. Each |
| field begins with a tag, such as |
| .B Package |
| or |
| .B Version |
| (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 |
| .B Description |
| field, see below). |
| . |
| .SH REQUIRED FIELDS |
| .TP |
| .BI Package: " package-name" |
| The value of this field determines the package name, and is used to |
| generate file names by most installation tools. |
| .TP |
| .BI Version: " version-string" |
| 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). The exact format and sorting algorithm |
| are described in |
| .BR deb\-version (5). |
| .TP |
| .BI Maintainer: " fullname-email" |
| Should be in the format `Joe Bloggs <jbloggs@foo.com>', and is typically |
| the person who created the package, as opposed to the author of the |
| software that was packaged. |
| .TP |
| .BI Description: " short-description" |
| .BI " " "long-description" |
| .br |
| The format for the package description is a short brief summary on the |
| first line (after the "Description" field). The following lines should 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 description must |
| contain a single '.' following the preceding space. |
| . |
| .SH OPTIONAL FIELDS |
| .TP |
| .BI Section: " section" |
| 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. |
| .TP |
| .BI Priority: " priority" |
| Sets the importance of this package in relation to the system as a whole. |
| Common priorities are `required', `standard', `optional', `extra' etc. |
| .LP |
| In Debian, the |
| .B Section |
| and |
| .B Priority |
| fields have a defined set of accepted values based on the Policy Manual. |
| A list of these values can be obtained from the latest version of the |
| .B debian\-policy |
| package. |
| .TP |
| .BR Essential: " \fByes\fP|\fBno\fP" |
| This field is usually only needed when the answer is \fByes\fP. It denotes |
| a package that is required for proper operation of the system. Dpkg |
| or any other installation tool will not allow an |
| .B Essential |
| package to be removed (at least not without using one of the force options). |
| .TP |
| .BR Architecture: " \fIarch\fP|\fBall\fP" |
| The architecture specifies which type of hardware this package was compiled |
| for. Common architectures are `i386', `m68k', `sparc', `alpha', `powerpc' |
| etc. Note that the |
| .B all |
| option is meant for packages that are architecture independent. Some examples |
| of this are shell and Perl scripts, and documentation. |
| .TP |
| .BI Origin: " name" |
| The name of the distribution this package is originating from. |
| .TP |
| .BI Bugs: " url" |
| The \fIurl\fP of the bug tracking system for this package. The current |
| used format is \fIbts-type\fP\fB://\fP\fIbts-address\fP, like |
| \fBdebbugs://bugs.debian.org\fP. |
| .TP |
| .BI Homepage: " url" |
| The upstream project home page \fIurl\fP. |
| .TP |
| .BI Tag: " tag-list" |
| List of tags describing the qualities of the package. The description and |
| list of supported tags can be found in the \fBdebtags\fP package. |
| .TP |
| .BR Multi\-Arch: " \fBsame\fP|\fBforeign\fP|\fBallowed\fP" |
| This field is used to indicate how this package should behave on a multi-arch |
| installations. The value \fBsame\fP means that the package is co-installable |
| with itself, but it must not be used to satisfy the dependency of any package |
| of a different architecture from itself. The value \fBforeign\fP means that |
| the package is not co-installable with itself, but should be allowed to |
| satisfy the dependency of a package of a different arch from itself. The |
| value \fBallowed\fP allows reverse-dependencies to indicate in their |
| Depends field that they need a package from a foreign architecture, but |
| has no effect otherwise. This field should not be present in packages |
| with the \fBArchitecture: all\fP field. |
| .TP |
| .BI Source: " source-name" |
| The name of the source package that this binary package came from, if |
| different than the name of the package itself. |
| |
| .TP |
| .PD 0 |
| .BI Subarchitecture: " value" |
| .TP |
| .PD 0 |
| .BI Kernel\-Version: " value" |
| .TP |
| .PD |
| .BI Installer\-Menu\-Item: " value" |
| These fields are used by the debian\-installer and are usually not needed. |
| See /usr/share/doc/debian\-installer/devel/modules.txt from the |
| .B debian\-installer |
| package for more details about them. |
| |
| .TP |
| .BI Depends: " package-list" |
| 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 |
| .B Depends |
| field aren't installed (at least not without using the force options). |
| In an installation, the postinst scripts of packages listed in Depends: |
| fields are run before those of the packages which depend on them. On the |
| opposite, in a removal, the prerm script of a package is run before |
| those of the packages listed in its Depends: field. |
| .TP |
| .BI Pre\-Depends: " package-list" |
| List of packages that must be installed |
| .B and |
| 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. |
| .TP |
| .BI Recommends: " package-list" |
| 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 |
| .B Recommends |
| field. |
| .TP |
| .BI Suggests: " package-list" |
| Lists packages that are related to this one and can perhaps enhance |
| its usefulness, but without which installing this package is perfectly |
| reasonable. |
| .LP |
| The syntax of |
| .BR Depends , |
| .BR Pre\-Depends , |
| .B Recommends |
| and |
| .B Suggests |
| fields is a list of groups of alternative packages. Each group is a list |
| of packages separated by vertical bar (or `pipe') symbols, `|'. The |
| groups are separated by commas. Commas are to be read as `AND', and pipes |
| as `OR', with pipes binding more tightly. Each package name is |
| optionally followed by a version number specification in parentheses. |
| .LP |
| A version number may start with a `>>', 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 ">>" for greater than, |
| "<<" for less than, ">=" for greater than or equal to, "<=" for less than |
| or equal to, and "=" for equal to. |
| .TP |
| .BI Breaks: " package-list" |
| Lists packages that this one breaks, for example by exposing bugs |
| when the named packages rely on this one. The package maintenance |
| software will not allow broken packages to be configured; generally |
| the resolution is to upgrade the packages named in a |
| .B Breaks |
| field. |
| .TP |
| .BI Conflicts: " package-list" |
| 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 |
| .B Conflicts |
| line mentioning the other. |
| .TP |
| .BI Replaces: " package-list" |
| 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 |
| .B Conflicts |
| field to force removal of the other package, if this one also has the |
| same files as the conflicted package. |
| .TP |
| .BI Provides: " package-list" |
| This is a list of virtual packages that this one provides. Usually this is |
| used in the case of several packages all providing the same service. |
| For example, sendmail and exim 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 satisfy 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. |
| .LP |
| The syntax of |
| .BR Breaks , |
| .BR Conflicts , |
| .B Replaces |
| and |
| .B Provides |
| is a list of package names, separated by commas (and optional whitespace). |
| In the |
| .B Breaks |
| and |
| .B Conflicts |
| fields, the comma should be read as `OR'. An optional version can also be |
| given with the same syntax as above for the |
| .BR Breaks , |
| .B Conflicts |
| and |
| .B Replaces |
| fields. |
| . |
| .TP |
| .BI Built\-Using: " package-list" |
| This field lists extra source packages that were used during the build of this |
| binary package. This is an indication to the archive maintenance software that |
| these extra source packages must be kept whilst this binary package is |
| maintained. This field must be a list of source package names with strict (=) |
| version relationships. Note that the archive maintenance software is likely to |
| refuse to accept an upload which declares a |
| .B Built\-Using |
| relationship which cannot be satisfied within the archive. |
| . |
| .SH EXAMPLE |
| .\" .RS |
| .nf |
| # Comment |
| Package: grep |
| Essential: yes |
| Priority: required |
| Section: base |
| Maintainer: Wichert Akkerman <wakkerma@debian.org> |
| Architecture: sparc |
| Version: 2.4\-1 |
| Pre\-Depends: libc6 (>= 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). |
| .fi |
| .\" .RE |
| . |
| .SH SEE ALSO |
| .BR deb (5), |
| .BR deb\-version (5), |
| .BR debtags (1), |
| .BR dpkg (1), |
| .BR dpkg\-deb (1). |