# Debian packaging manual - chapter 2
Binary packages

The binary package has two main sections. The first part consists of various control information files and scripts used by `dpkg` when installing and removing. See Package control information files, section 2.2.

The second part is an archive containing the files and directories to be installed.

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 `deb(5)` manpage.

## 2.1 Creating package files - `dpkg-deb`

All manipulation of binary package files is done by `dpkg-deb`; it's the only program that has knowledge of the format. (`dpkg-deb` may be invoked by calling `dpkg`, as `dpkg` will spot that the options requested are appropriate to `dpkg-deb` and invoke that instead with the same arguments.)

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 `debian/tmp`, relative to the top of the package's source tree.

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.

With current versions of `dpkg` the uid/username and gid/groupname mappings for the users and groups being used should be the same on the system where the package is built and the one where it is installed.

You need to add one special directory to the root of the miniature filesystem tree you're creating: `DEBIAN`. It should contain the control information files, notably the binary package control file (see The main control information file: `control`, section 2.3).

The `DEBIAN` directory will not appear in the filesystem archive of the package, and so won't be installed by `dpkg` when the package is installed.

When you've prepared the package, you should invoke:

    dpkg --build directory

This will build the package in ``directory`.deb`. (`dpkg` knows that `--build` is a `dpkg-deb` option, so it invokes `dpkg-deb` with the same arguments to build the package.)

See the manpage `dpkg-deb(8)` for details of how to examine the contents of this newly-created file. You may find the output of following commands enlightening:

    dpkg-deb --info filename.deb
    dpkg-deb --contents filename.deb
    dpkg --contents filename.deb

To view the copyright file for a package you could use this command:

    dpkg --fsys-tarfile filename.deb | tar xof usr/doc/\*copyright | less

## 2.2 Package control information files

The control information portion of a binary package is a collection of files with names known to `dpkg`. It will treat the contents of these files specially - some of them contain information used by `dpkg` when installing or removing the package; others are scripts which the package maintainer wants `dpkg` to run.

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

Here is a brief list of the control info files supported by `dpkg` and a summary of what they're used for.

`control`
  This is the key description file used by `dpkg`. It specifies the package's name and version, gives its description for the user, states its relationships with other packages, and so forth. See The main control information file: `control`, section 2.3.

  It is usually generated automatically from information in the source package by the `dpkg-gencontrol` program, and with assistance from `dpkg-shlibdeps`. See Tools for processing source packages, section 3.1.

`postinst`, `preinst`, `postrm`, `prerm`
  These are exectuable files (usually scripts) which `dpkg` runs during installation, upgrade and removal of packages. They allow the package to deal with matters which are particular to that package or require more complicated processing than that provided by `dpkg`. Details of when and how they are called are in Package maintainer scripts and installation procedure, chapter 6.

  It is very important to make these scripts idempotent.[2] This is so that if an error occurs, the user interrupts `dpkg` or some other unforeseen circumstance happens you don't leave the user with a badly-broken package.

  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 `/dev/tty`, since `dpkg` will at some point redirect scripts' standard input and output so that it can log the installation process. Likewise, because these scripts may be executed with standard output redirected into a pipe for logging purposes, Perl scripts should set unbuffered output by setting `$|=1` so that the output is printed immediately rather than being buffered.

  Each script should return a zero exit status for success, or a nonzero one for failure.

`conffiles`
  This file contains a list of configuration files which are to be handled automatically by `dpkg` (see Configuration file handling, chapter 9). Note that not necessarily every configuration file should be listed here.

`shlibs`
  This file contains a list of the shared libraries supplied by the package, with dependency details for each. This is used by `dpkg-shlibdeps` when it determines what dependencies are required in a package control file. The `shlibs` file format is described on The `shlibs` File Format, section 12.1.

## 2.3 The main control information file: `control`

The most important control information file used by `dpkg` when it installs a package is `control`. It contains all the package's `vital statistics'.

The binary package control files of packages built from Debian sources are made by a special tool, `dpkg-gencontrol`, which reads `debian/control` and `debian/changelog` to find the information it needs. See Source packages, chapter 3 for more details.

The fields in binary package control files are:

- `Package` (mandatory)
- `Version` (mandatory)
- `Architecture` (mandatory)[3]
- `Depends`, `Provides` et al.
- `Essential`
- `Maintainer`
- `Section`, `Priority`
- `Source`
- `Description`
- `Installed-Size`

A description of the syntax of control files and the purpose of these fields is available in Control files and their fields, chapter 4.

Debian packaging manual - Copyright ©1996 Ian Jackson.
Contents; abstract; next; back.