Overview of debian/ directory

This article explains the different files important to the packaging of Ubuntu packages that are contained in the debian/ directory. The most important of them are:

  • debian/changelog

  • debian/control

  • debian/copyright

  • debian/rules

These are required for all packages. A number of additional files in the debian/ directory may be used to customize and configure the behavior of the package. Some of these files are discussed in this article, but this is not meant to be a complete list.

The changelog file

This file is a listing of the changes made in each version. It has a specific format that gives the package name, version, distribution changes, and who made the changes at a given time. The following is a template debian/changelog:

package (version) distribution; urgency=urgency
[optional blank line(s), stripped]
  * change details
    - more change details
  * even more change details
[optional blank line(s), stripped]
 -- maintainer name <email address>[two spaces]  date

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

The distribution field lists the distribution(s) in which this release should be installed.

urgency describes how important an upgrade is. Its value can be one of the following: low, medium, high, emergency, or critical.

The change details consist of lines indented by at least two spaces, but these conventionally are a list. Major bullet points use an asterisk *, while minor bullet points are indicated by a dash -.

The changelog entry ends with a line indented by one space that contains the name, email of the maintainer, and date of change. The maintainer here is the one responsible for the release, but it need not be the package maintainer.

If you have a signing key, use the same name and email address in debian/changelog entry as you have in your key.

Important

The date should be in RFC 5322 format, which can be obtained by using the command date -R. For convenience, the command dch may be used to edit the changelog. It updates the date automatically. For further information, see dch(1) and Updating the changelog.

When packaging from scratch, use dch --create (dch is in the devscripts package) to create a standard debian/changelog.

A sample debian/changelog file for the hello package:

hello (2.8-0ubuntu1) trusty; urgency=low

 * New upstream release with lots of bug fixes and feature improvements.

-- Jane Doe <[email protected]>  Thu, 21 Oct 2013 11:12:00 -0400

Notice that the version has -0ubuntu1 appended to it. This is the distribution revision – used so that the package can be updated (to fix bugs for example) with new uploads within the same source release version.

Ubuntu and Debian have slightly different package versioning schemes to avoid conflicting packages with the same source version. If a Debian package has been changed in Ubuntu, it has ubuntuX (where X is the Ubuntu revision number) appended to the end of the Debian version. So if the Debian hello 2.6-1 package is changed by Ubuntu, the version string is 2.6-1ubuntu1. If a package for the application does not exist in Debian, then the Debian revision is 0 (e.g. 2.6-0ubuntu1).

For further information, see the changelog section (Section 4.4) of the Debian Policy Manual.

The control file

The debian/control file contains the information that the package manager (such as APT) uses, build-time dependencies, maintainer information, and much more. The file consists of one or more stanzas of fields, with each stanza separated by empty lines. The fields consist of key-value pairs separated by a colon :; conventionally, a single space follows the colon.

For the Ubuntu hello package, the debian/control file looks something like this:

Source: hello
Section: devel
Priority: optional
Maintainer: Ubuntu Developers <[email protected]>
XSBC-Original-Maintainer: Jane Doe <[email protected]>
Standards-Version: 4.6.2
Build-Depends: debhelper-compat (= 13), help2man, texinfo
Homepage: https://www.gnu.org/software/hello/

Package: hello
Architecture: any
Depends: ${misc:Depends}, ${shlibs:Depends}
Description: The classic greeting, and a good example
 The GNU hello program produces a familiar, friendly greeting. It
 allows non-programmers to use a classic computer science tool which
 would otherwise be unavailable to them. Seriously, though: this is
 an example of how to do a Debian package. It is the Debian version of
 the GNU Project's `hello world' program (which is itself an example
 for the GNU Project).

The first stanza describes the source package. It contains the following fields:

  • Source (required): The name of the source package.

  • Maintainer (required): The name and email of the package maintainer.

Note

In Ubuntu, we set the Maintainer field to a general address because anyone can change any package (this differs from Debian where changing packages is usually restricted to an individual or a team). Packages in Ubuntu should generally have the Maintainer field set to Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com>.

If the Maintainer field is modified, the old value should be saved in the XSBC-Original-Maintainer field. This can be done automatically with the update-maintainer script available in the ubuntu-dev-tools package.

  • Uploaders: The list of names and email addresses of co-maintainers.

  • Section (recommended): The application area into which the package has been classified.

  • Priority (recommended): How important the package is.

  • Build-Depends fields: Lists the packages required to build the package from source.

  • Standards-Version (required): The version of Debian Policy that the package complies with.

  • Homepage: The upstream home page.

  • Version Control System fields:

  • Testsuite: A comma-separated list of values allowing test execution environments to discover packages which provide tests.

  • Rules-Requires-Root: Defines whether the source package requires root access during selected targets.

Each additional stanza describes a binary package to be built. These stanzas contain the following fields:

  • Package (required): The name of the binary package.

  • Architecture (required): The architectures supported.

  • Section (recommended): The application area into which the package has been classified.

  • Priority (recommended): How important the package is.

  • Essential: Optional boolean field to prevent the package manager from removing the package when set to yes. When this field is absent, the default behavior is no.

  • Depends fields:

    • TODO

  • Description (required): Contains a description of the binary package. This field consists of a synopsis and a long description.

  • Homepage: The upstream home page.

  • Built-Using: This field is used in cases where the package incorporates parts of other packages and relies on specific versions.

  • Package-Type: Indicates the type of the package, for example: deb or udeb.

For further information, see the control file section (Chapter 5) of the Debian Policy Manual.

The rules file

The debian/rules file does all the work for creating a package. It is a Makefile with targets to compile and install the application, then create the .deb file from the installed files. It also has a target to clean all the build files, so only a source package remains after a build.

The debian/rules file has the following targets:

  • build (required)

    Configures and compiles the package.

  • build-arch (required)

    Configures and compiles architecture-dependent binary packages (distinguished by not having the all value in the Architecture field).

  • build-indep (required)

    Configures and compiles architecture-independent binary packages (distinguished by the all value for the Architecture field).

  • binary (required)

    Builds binary package(s) from the source package. It is typically an empty target that depends on its two parts: binary-arch and binary-indep.

binary-arch (required)

Builds the binary packages that are architecture-dependent.

binary-indep (required)

Builds the binary packages that are architecture-independent.

  • clean (required)

    Undoes the effects of the build and binary targets, but it does not affect output files that a binary target creates in the parent directory.

  • patch (optional)

    Prepares the source for editing. For example, it may unpack additional upstream archives, apply patches, etc.

A simplified version of the debian/rules file created by dh_make (from the dh-make package):

#!/usr/bin/make -f
# -*- makefile -*-

# Uncomment this to turn on verbose mode.
#export DH_VERBOSE=1

%:
    dh $@

This passes every build target that debian/rules is called with as an argument to /usr/bin/dh, which itself calls the necessary dh_* commands.

dh runs a sequence of debhelper commands. The supported sequences correspond to the targets of a debian/rules file: build, clean, install, binary-arch, binary-indep, and binary. To see what commands are run in each target, run:

dh binary-arch --no-act

  • Commands in the binary-indep sequence are passed the -i option to ensure they only work on binary independent packages.

  • Commands in the binary-arch sequences are passed the -a option to ensure they only work on architecture dependent packages.

Each debhelper command records successful runs in debian/package.debhelper.log (which dh_clean deletes). So, dh can tell which commands have already been run, for which packages, and skip running those commands again.

Each time dh is run, it examines the log, and finds the last logged command that is in the specified sequence. It then continues with the next command in the sequence. The --until, --before, --after, and --remaining options can override this behavior.

If debian/rules contains a target with a name like override_dh_command, then when it gets to that command in the sequence, dh runs that target from the rules file rather than running the actual command. The override target can then run the command with additional options or run entirely different commands instead.

Note

To use the override feature, set Build-Depend on debhelper version 7.0.50 or above.

Look at /usr/share/doc/debhelper/examples/ and dh(1) for more examples. Also see the rules section (Section 4.9) of the Debian Policy Manual.

Additional files

The install file

The install file is used by dh_install to install files into the binary package. It has two standard use cases:

  • Installing files into your package that are not handled by the upstream build system.

  • Splitting a single large source package into multiple binary packages.

In the first case, the install file should have one line per file installed, specifying both the file and the installation directory. For example, the following install file installs the script example from the root directory of the source package to usr/bin and a desktop file from the debian directory to usr/share/applications:

example usr/bin
debian/example.desktop usr/share/applications

When a source package is producing multiple binary packages, dh installs the files into debian/tmp rather than directly into debian/<package>. Files installed into debian/tmp can then be moved into separate binary packages using multiple $package_name.install files. This is often done to split large amounts of architecture independent data out of architecture dependent packages and into Architecture: all packages. In this case, only the name of the files (or directories) to be installed are needed without the installation directory. For example, example.install containing only the architecture dependent files might look like:

usr/bin/
usr/lib/example/*.so

While the example-common.install containing only the architecture independent file might look like:

/usr/share/doc/
/usr/share/icons/
/usr/share/example/
/usr/share/locale/

This creates two binary packages, example and example-common. Both would require their own stanza in debian/control.

See dh_install(1) and the install file section (Section 5.11) of the Debian New Maintainers’ Guide for additional details.

The watch file

The debian/watch file automatically checks for new upstream versions using the tool uscan found in the devscripts package. The first line of the watch file must be the format version (4, at the time of this writing), while the following lines contain any URLs to parse. For example:

version=4
http://ftp.gnu.org/gnu/hello/hello-(.*).tar.gz

Note

For tarballs on Launchpad, the debian/watch file is a little more complicated (see Question 21146 and Bug 231797 for why this is). In that case, use something like:

version=4
https://launchpad.net/flufl.enum/+download http://launchpad.net/flufl.enum/.*/flufl.enum-(.+).tar.gz

Running uscan in the root source directory now compares the upstream version number in the debian/changelog with the latest upstream version. If a new upstream version is found, it is automatically downloaded. For example:

$ uscan
hello: Newer version (2.7) available on remote site:
    http://ftp.gnu.org/gnu/hello/hello-2.7.tar.gz
    (local version is 2.6)
hello: Successfully downloaded updated package hello-2.7.tar.gz
    and symlinked hello_2.7.orig.tar.gz to it

For further information, see uscan(1) and the watch file section (Section 4.11) of the Debian Policy Manual.

The source/format file

This file indicates the format of the source package. It contains a single line indicating the desired format:

  • 3.0 (native) for Debian native packages (no upstream version)

  • 3.0 (quilt) for packages with a separate upstream tarball

  • 1.0 for packages wishing to explicitly declare the default format

Note

The debian/source/format file should always exist. If the file cannot be found, the format 1.0 is assumed for backwards compatibility, but lintian(1) warns you about it when you try to build a source package.

It is recommended to use the newer 3.0 source format. It provides a number of new features:

  • Support for additional compression formats: bzip2, lzma and xz

  • Support for multiple upstream tarballs

  • Not necessary to repack the upstream tarball to strip the debian directory

  • Debian-specific changes are no longer stored in a single .diff.gz but in multiple patches compatible with quilt under debian/patches/. The patches to be applied automatically are listed in the debian/patches/series file.

The Debian DebSrc3.0 page summarizes additional information concerning the switch to the 3.0 source package formats.

See dpkg-source(1) and the source/format section (Section 5.21) of the Debian New Maintainers’ Guide for additional details.

Further reading

In addition to the links to the Debian Policy Manual in each section above, the Debian New Maintainers’ Guide has more detailed descriptions of each file. Chapter 4, “Required files under the debian directory” further discusses the control, changelog, copyright, and rules files. Chapter 5, “Other files under the debian directory” discusses additional files that may be used.