# Debian packaging manual - chapter 3
Source packages

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.

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.

## 3.1 Tools for processing source packages

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.

They are introduced and typical uses described here; see `dpkg-source(1)` for full documentation about their arguments and operation.

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 `hello` example package.

### 3.1.1 `dpkg-source` - packs and unpacks Debian source packages

This program is frequently used by hand, and is also called from package-independent automated building scripts such as `dpkg-buildpackage`.

To unpack a package it is typically invoked with

    dpkg-source -x .../path/to/filename.dsc

with the ``filename`.tar.gz` and ``filename`.diff.gz` (if applicable) in the same directory. It unpacks into ``package`-`version``, and if applicable ``package`-`version`.orig`, in the current directory.

To create a packed source archive it is typically invoked:

    dpkg-source -b package-version

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

See also Source packages as archives, section 3.3.

### 3.1.2 `dpkg-buildpackage` - overall package-building control script

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

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:

`-uc`, `-us`
  Do not PGP-sign the `.changes` file or the source package `.dsc` file, respectively.
`-p` pgp-command``
  Invoke pgp-command instead of finding `pgp` on the `PATH`. pgp-command must behave just like `pgp`.
`-r` root-command``
  When root privilege is required, invoke the command root-command. root-command should invoke its first argument as a command, from the `PATH` if necessary, and pass its second and subsequent arguments to the command it calls. If no root-command is supplied then dpkg-buildpackage 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.
`-b`, `-B`
  Two types of binary-only build and upload - see `dpkg-source(1)`.

### 3.1.3 `dpkg-gencontrol` - generates binary package control files

This program is usually called from `debian/rules` (see The Debianised source tree, section 3.2) in the top level of the source tree.

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 `dpkg-deb`[4].

`dpkg-gencontrol` 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.

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

For a package which generates only one binary package, and which builds it in `debian/tmp` relative to the top of the source package, it is usually sufficient to call:

    dpkg-gencontrol

Sources which build several binaries will typically need something like:

    dpkg-gencontrol -Pdebian/tmp-pkg -ppackage

The `-P` tells `dpkg-gencontrol` that the package is being built in a non-default directory, and the `-p` tells it which package's control file should be generated.

`dpkg-gencontrol` also adds information to the list of files in `debian/files`, for the benefit of (for example) a future invocation of `dpkg-genchanges`.

### 3.1.4 `dpkg-shlibdeps` - calculates shared library dependencies

This program is usually called from `debian/rules` just before `dpkg-gencontrol` (see The Debianised source tree, section 3.2), in the top level of the source tree.

Its arguments are executables[5] for which shared library dependencies should be included in the binary package's control file.

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

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

For example, the `procps` package generates two kinds of binaries, simple C binaries like `ps` which require a predependency and full-screen ncurses binaries like `top` which require only a recommendation. It can say in its `debian/rules`:

    dpkg-shlibdeps -dPre-Depends ps -dRecommends top

and then in its main control file `debian/control`:

    ...
    Package: procps
    Pre-Depends: ${shlibs:Pre-Depends}
    Recommends: ${shlibs:Recommends}
    ...

Sources which produce several binary packages with different shared library dependency requirements can use the `-p` varnameprefix`` option to override the default `shlib:` prefix (one invocation of `dpkg-shlibdeps` per setting of this option). They can thus produce several sets of dependency variables, each of the form ``varnameprefix`:`dependencyfield``, which can be referred to in the appropriate parts of the binary package control files.

### 3.1.5 `dpkg-distaddfile` - adds a file to `debian/files`

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

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

It is usually invoked from the `binary` target of `debian/rules`:

    dpkg-distaddfile filename section priority

The filename is relative to the directory where `dpkg-genchanges` will expect to find it - this is usually the directory above the top level of the source tree. The `debian/rules` target should put the file there just before or just after calling `dpkg-distaddfile`.

The section and priority are passed unchanged into the resulting `.changes` file. See `Section` and `Priority`, subsection 4.2.9.

### 3.1.6 `dpkg-genchanges` - generates a `.changes` upload control file

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

It is usually called in the top level of a built source tree, and when invoked with no arguments will print out a straightforward `.changes` 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.

### 3.1.7 `dpkg-parsechangelog` - produces parsed representation of a changelog

This program is used internally by `dpkg-source` et al. It may also occasionally be useful in `debian/rules` and elsewhere. It parses a changelog, `debian/changelog` by default, and prints a control-file format representation of the information in it to standard output.

## 3.2 The Debianised source tree

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.

The extra files created for Debian are in the subdirectory `debian` of the top level of the Debianised source tree. They are described below.

### 3.2.1 `debian/rules` - the main building script

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.

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

The targets which are required to be present are:

`build`
  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.

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

  The `build` target must not do anything that might require root privilege.

  The `build` target may need to run `clean` first - see below.

  When a package has a configuration routine that takes a long time, or when the makefiles are poorly designed, or when `build` needs to run `clean` first, it is a good idea to `touch build` when the build process is complete. This will ensure that if `debian/rules build` is run again it will not rebuild the whole program.

`binary`, `binary-arch`, `binary-indep`
  The `binary` target should be all that is necessary for the user to build the binary package. It is split into two parts: `binary-arch` builds the packages' output files which are specific to a particular architecture, and `binary-indep` builds those which are not.

  `binary` should usually be a target with no commands which simply depends on `binary-arch` and `binary-indep`.

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

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

  Binary packages, chapter 2 describes how to construct binary packages.

  The `binary` targets must be invoked as root.

`clean`
  This should undo any effects that the `build` and `binary` targets may have had, except that it should leave alone any output files created in the parent directory by a run of `binary`.

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

  The `clean` target must be invoked as root if `binary` has been invoked since the last `clean`, or if `build` has been invoked as root (since `build` may create directories, for example).

`get-orig-source` (optional)
  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.

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

  This target is optional, but providing it if possible is a good idea.

The `build`, `binary` and `clean` targets must be invoked with a current directory of the package's top-level directory.

Additional targets may exist in `debian/rules`, either as published or undocumented interfaces or for the package's internal use.

### 3.2.2 `debian/control`

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

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.

The syntax and semantics of the fields are described below in Control files and their fields, chapter 4.

The general (binary-package-independent) fields are:

- `Source` (mandatory)
- `Maintainer`
- `Section` and `Priority` (classification, mandatory)
- `Standards-Version`

The per-binary-package fields are:

- `Package` (mandatory)
- `Architecture` (mandatory)
- `Description`
- `Section` and `Priority` (classification)
- `Essential`
- `Depends` et al. (package interrelationships)

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

The fields here may contain variable references - their values will be substituted by `dpkg-gencontrol`, `dpkg-genchanges` or `dpkg-source` when they generate output control files. See `debian/substvars` and variable substitutions, subsection 3.2.4 for details.

#### 3.2.2.1 User-defined fields

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.

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

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

For example, if the main source information control file contains the field

    XBS-Comment: I stand between the candle and the star.

then the binary and source package control files will contain the field

    Comment: I stand between the candle and the star.

### 3.2.3 `debian/changelog`

This file records the changes to the Debian-specific parts of the package[6].

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.

That format is a series of entries like this:

    package (version) distribution(s); urgency=urgency

      * change details
        more change details
      * even more change details

     -- maintainer name and email address  date

package and version are the source package name and version number.

distribution(s) lists the distributions where this version should be installed when it is uploaded - it is copied to the `Distribution` field in the `.changes` file. See `Distribution`, subsection 4.2.14.

urgency is the value for the `Urgency` field in the `.changes` file for the upload. See `Urgency`, subsection 4.2.15. It is not possible to specify an urgency containing commas; commas are used to separate ``keyword`=`value`` settings in the `dpkg` changelog format (though there is currently only one useful keyword, `urgency`).

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.

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

The date should be in RFC822 format[7]; it should include the timezone specified numerically, with the timezone name or abbreviation optionally present as a comment.

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.

An Emacs mode for editing this format is available: it is called `debian-changelog-mode`. 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.

#### 3.2.3.1 Defining alternative changelog formats

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

In order to have `dpkg-parsechangelog` run your parser, you must include a line within the last 40 lines of your file matching the Perl regular expression: `\schangelog-format:\s+([0-9a-z]+)\W` The part in parentheses should be the name of the format. For example, you might say:

    @@@ changelog-format: joebloggs @@@

Changelog format names are non-empty strings of alphanumerics.

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

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

The fields are:

- `Source`
- `Version` (mandatory)
- `Distribution` (mandatory)
- `Urgency` (mandatory)
- `Maintainer` (mandatory)
- `Date`
- `Changes` (mandatory)

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

For the format of the `Changes` field see `Changes`, subsection 4.2.18.

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.

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.

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.

A changelog parser may not interact with the user at all.

### 3.2.4 `debian/substvars` and variable substitutions

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

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

See `dpkg-source(1)` for full details about source variable substitutions, including the format of `debian/substvars`.

### 3.2.5 `debian/files`

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

It should not exist in a shipped source package, and so it (and any backup files or temporary files such as `files.new`[8]) should be removed by the `clean` target. It may also be wise to ensure a fresh start by emptying or removing it at the start of the `binary` target.

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

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

### 3.2.6 `debian/tmp`

This is the canonical temporary location for the construction of binary packages by the `binary` target. The directory `tmp` 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 `DEBIAN` subdirectory. See Creating package files - `dpkg-deb`, section 2.1.

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

Whatever `tmp` directories are created and used by `binary` must of course be removed by the `clean` target.

## 3.3 Source packages as archives

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.

Debian source control file - `.dsc`
  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 Control files and their fields, chapter 4.
  - `Source`
  - `Version`
  - `Maintainer`
  - `Binary`
  - `Architecture`
  - `Standards-Version`
  - `Files`

  The source package control file is generated by `dpkg-source` 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.

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

  All the directories in the diff must exist, except the `debian` subdirectory of the top of the source tree, which will be created by `dpkg-source` if necessary when unpacking.

  The `dpkg-source` program will automatically make the `debian/rules` file executable (see below).

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 ``package`_`version`.tar.gz` and contains a directory ``package`-`version``.

## 3.4 Unpacking a Debian source package without `dpkg-source`

`dpkg-source -x` 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:

1. Untar the tarfile, which will create a `.orig` directory.
2. Rename the `.orig` directory to ``package`-`version``.
3. Create the subdirectory `debian` at the top of the source tree.
4. Apply the diff using `patch -p0`.
5. Untar the tarfile again if you want a copy of the original source code alongside the Debianised version.

It is not possible to generate a valid Debian source archive without using `dpkg-source`. In particular, attempting to use `diff` directly to generate the `.diff.gz` file will not work.

### 3.4.1 Restrictions on objects in source packages

The source package may not contain any hard links[9][10], device special files, sockets or setuid or setgid files.[11]

The source packaging tools manage the changes between the original and Debianised source using `diff` and `patch`. Turning the original source tree as included in the `.orig.tar.gz` into the debianised source must not involve any changes which cannot be handled by these tools. Problematic changes which cause `dpkg-source` to halt with an error when building the source package are:

- Adding or removing symbolic links, sockets or pipes.
- Changing the targets of symbolic links.
- Creating directories, other than `debian`.
- Changes to the contents of binary files.

Changes which cause `dpkg-source` to print a warning but continue anyway are:

- Removing files, directories or symlinks. [12]
- Changed text files which are missing the usual final newline (either in the original or the modified source tree).

Changes which are not represented, but which are not detected by `dpkg-source`, are:

- Changing the permissions of files (other than `debian/rules`) and directories.

The `debian` directory and `debian/rules` are handled specially by `dpkg-source` - before applying the changes it will create the `debian` directory, and afterwards it will make `debian/rules` world-exectuable.

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