The control file
The control file contains metadata necessary for building the package. Some of the metadata ends up in the .dsc file, some ends up in the binary package, some in the .changes file, and some is only used at build time.
The canonical information about control fields and their meaning can be found at http://www.debian.org/doc/debian-policy/ch-controlfields.html
Sample control file
Source: rpncalc Section: utils Priority: extra Maintainer: Jonathan Reed <jdreed@mit.edu> Build-Depends: debhelper (>= 8.0.0) Standards-Version: 3.9.3 Package: rpncalc Architecture: any Depends: ${shlibs:Depends}, ${misc:Depends} Description: Simple RPN calculator in bash A simple RPN calculator, implemented in bash. Not legal for trade. This was taken from the O'Reilly bash cookbook.
As you may notice, the file is divided into 2 sections. The Source: section and the Package: section, which correspond to the source and binary packages, respectively. As noted earlier, a single source package can build multiple binary packages, and so control files may have multiple Package: sections. Section breaks are indicated by a blank line.
- Priority: Used by package managers to decide what to keep when there are conflicts. This is general optional or extra. You may also see required, or essential which will make it harder for package managers to resolve conflicts, and is generally reserved for things that are truly required, like the kernel, or libc.
- Section: The Section is mostly irrelevant; copy it from a package similar to yours. This field has a special format, section/subsection. The section part determines what component of a Debian repository (i.e. the things after the name of the distro in the /etc/apt/sources.list line) to upload the package to (in standard Debian, main, contrib, or non-free; in Debathena, debathena, debathena-standard, debathena-system, or openafs); if it is not specified the section is assumed to be main. The subsection field is simply used for organizing graphical user interfaces to the Debian archive.
- Standards-Version: Indicates what version of the Debian Policy Manual the package is compatible with. Should generally be the current version you're running. Used by Lintian. Get it using apt-cache show debian-policy | grep Version.
- Maintainer: Your contact information, e.g. Tim Abbott <tabbott@…>
- Build-Depends: List packages needed to build your package. You don’t need to include any Priority: essential packages or anything depended on by build-essential.
- Architecture: If your package is architecture-independent (e.g. a shell script), you want “all”. If your package only works on some architectures, list those architectures. Otherwise, you want “any”. In Debathena, we generally use 'any' or 'all'.
- Depends: A hard dependency; the package will not be installed unless the packages it depends on are installed. Necessary
shared libraries should be automatically added if you include “${shlibs:Depends}”. Other useful dependencies may be added by debhelper if you include “${misc:Depends}”. You don’t need to include any Priority: essential packages.
- Recommends: A soft dependency; aptitude and recent apt-get will prompt you to install the recommended packages along with your
package, but they will let you install your package without its recommended packages.
- Suggests: A dependency that doesn’t do anything. Modern package managers may tell the user that some packages are suggested, but will never automatically install them.
- Conflicts: A dependency that prevents both packages from being installed simultaneously.
- Provides: Assign virtual names to the package. Debian uses this for defining alternatives (e.g. mail-transport-agent is anything providing sendmail), but Provides is useful for many other applications.
- Replaces: When one package replaces or is a renaming of another, you want to specify Replaces: and Conflicts: against that package. Files from the named packages will be overwritten with the files from your package and it’ll make aptitude happier about the upgrade.
- Pre-Depends, Breaks: These are stronger versions of Depends and Conflicts, and should only be used in very specific situations.
- Description: A description of the package. This is a multi-line field. The first line is a short synopsis of the package, and the remaining lines (indented by a single space) is a longer description. Read Debian Policy for more information, as Lintian can be very pedantic about grammar and syntax in this field.