Chapter 4. Required files under the `debian` directory

# Chapter 4. Required files under the `debian` directory

The rewrite of this tutorial document with updated contents and more practical examples is available as Guide for Debian Maintainers. Please use this new tutorial as the primary tutorial document.

There is a new subdirectory under the program's source directory, called `debian`. There are a number of files in this directory that we should edit in order to customize the behavior of the package. The most important of them are `control`, `changelog`, `copyright`, and `rules`, which are required for all packages. [27]

## 4.1. `control`

This file contains various values which dpkg, dselect, apt-get, apt-cache, aptitude, and other package management tools will use to manage the package. It is defined by the Debian Policy Manual, 5 "Control files and their fields".

Here is the `control` file dh_make created for us:

     1 Source: gentoo
     2 Section: unknown
     3 Priority: optional
     4 Maintainer: Josip Rodin <joy-mg@debian.org>
     5 Build-Depends: debhelper (>=10)
     6 Standards-Version: 4.0.0
     7 Homepage: <insert the upstream URL, if relevant>
     8
     9 Package: gentoo
    10 Architecture: any
    11 Depends: ${shlibs:Depends}, ${misc:Depends}
    12 Description: <insert up to 60 chars description>
    13  <insert long description, indented with spaces>

(I've added the line numbers.)

Lines 1–7 are the control information for the source package. Lines 9–13 are the control information for the binary package.

Line 1 is the name of the source package.

Line 2 is the section of the distribution the source package goes into.

As you may have noticed, the Debian archive is divided into multiple areas: `main` (the free software), `non-free` (the not really free software) and `contrib` (free software that depends on non-free software). Each of these is divided into sections that classify packages into rough categories. So we have `admin` for administrator-only programs, `devel` for programmer tools, `doc` for documentation, `libs` for libraries, `mail` for email readers and daemons, `net` for network apps and daemons, `x11` for X11 programs that don't fit anywhere else, and many more. [28]

Let's change it then to x11. (A `main/` prefix is implied so we can omit it.)

Line 3 describes how important it is that the user installs this package. [29]

- The `optional` priority will usually work for new packages that do not conflict with others claiming `required`, `important`, or `standard` priority.

Section and priority are used by front-ends like aptitude when they sort packages and select defaults. Once you upload the package to Debian, the value of these two fields can be overridden by the archive maintainers, in which case you will be notified by email.

As this is a normal priority package and doesn't conflict with anything else, we will change the priority to `optional`.

Line 4 is the name and email address of the maintainer. Make sure that this field includes a valid `To` header for email, because after you upload it, the bug tracking system will use it to deliver bug emails to you. Avoid using commas, ampersands, or parentheses.

Line 5 includes the list of packages required to build your package as the `Build-Depends` field. You can also have the `Build-Depends-Indep` field as an additional line here. [30] Some packages like `gcc` and `make` which are required by the `build-essential` package are implied. If you need to have other tools to build your package, you should add them to these fields. Multiple entries are separated with commas; read on for the explanation of binary package dependencies to find out more about the syntax of these lines.

- For all packages packaged with the dh command in the `debian/rules` file, you must have `debhelper (>=9)` in the `Build-Depends` field to satisfy the Debian Policy requirement for the `clean` target.

- Source packages which have binary packages with `Architecture: any` are rebuilt by the autobuilder. Since this autobuilder procedure installs only the packages listed in the `Build-Depends` field before running `debian/rules build` (see Section 6.2, “Autobuilder”), the `Build-Depends` field needs to list practically all the required packages, and `Build-Depends-Indep` is rarely used.

- For source packages with binary packages all of which are `Architecture: all`, the `Build-Depends-Indep` field may list all the required packages unless they are already listed in the `Build-Depends` field to satisfy the Debian Policy requirement for the `clean` target.

If you are not sure which one should be used, use the `Build-Depends` field to be on the safe side. [31]

To find out what packages your package needs to be built run the command:

    $ dpkg-depcheck -d ./configure

To manually find exact build dependencies for `/usr/bin/foo`, execute

    $ objdump -p /usr/bin/foo | grep NEEDED

and for each library listed (e.g., libfoo.so.6), execute

    $ dpkg -S libfoo.so.6

Then just take the `-dev` version of every package as a `Build-Depends` entry. If you use ldd for this purpose, it will report indirect lib dependencies as well, resulting in the problem of excessive build dependencies.

`gentoo` also happens to require `xlibs-dev`, `libgtk1.2-dev` and `libglib1.2-dev` to build, so we'll add them here next to `debhelper`.

Line 6 is the version of the Debian Policy Manual standards this package follows, the one you read while making your package.

On line 7 you can put the URL of the software's upstream homepage.

Line 9 is the name of the binary package. This is usually the same as the name of the source package, but it doesn't necessarily have to be that way.

Line 10 describes the architectures the binary package can be compiled for. This value is usually one of the following depending on the type of the binary package: [32]

- `Architecture: any`

  - The generated binary package is an architecture dependent one usually in a compiled language.

- `Architecture: all`

  - The generated binary package is an architecture independent one usually consisting of text, images, or scripts in an interpreted language.

We leave line 10 as is since this is written in C. dpkg-gencontrol(1) will fill in the appropriate architecture value for any machine this source package gets compiled on.

If your package is architecture independent (for example, a shell or Perl script, or a document), change this to `all`, and read later in Section 4.4, “`rules`” about using the `binary-indep` rule instead of `binary-arch` for building the package.

Line 11 shows one of the most powerful features of the Debian packaging system. Packages can relate to each other in various ways. Apart from `Depends`, other relationship fields are `Recommends`, `Suggests`, `Pre-Depends`, `Breaks`, `Conflicts`, `Provides`, and `Replaces`.

The package management tools usually behave the same way when dealing with these relations; if not, it will be explained. (See dpkg(8), dselect(8), apt(8), aptitude(1), etc.)

Here is a simplified description of package relationships: [33]

- `Depends`

  The package will not be installed unless the packages it depends on are installed. Use this if your program absolutely will not run (or will cause severe breakage) unless a particular package is present.

- `Recommends`

  Use this for packages that are not strictly necessary but are typically used with your program. When a user installs your program, all front-ends will probably prompt them to install the recommended packages. aptitude and apt-get install recommended packages along with your package by default (but the user can disable this behavior). dpkg will ignore this field.

- `Suggests`

  Use this for packages which will work nicely with your program but are not at all necessary. When a user installs your program, they will probably not be prompted to install suggested packages. aptitude can be configured to install suggested packages along with your package but this is not its default. dpkg and apt-get will ignore this field.

- `Pre-Depends`

  This is stronger than `Depends`. The package will not be installed unless the packages it pre-depends on are installed and correctly configured. Use this very sparingly and only after discussing it on the debian-devel@lists.debian.org mailing list. Read: don't use it at all. :-)

- `Conflicts`

  The package will not be installed until all the packages it conflicts with have been removed. Use this if your program absolutely will not run or will cause severe problems if a particular package is present.

- `Breaks`

  When installed the package will break all the listed packages. Normally a `Breaks` entry specifies that it applies to versions earlier than a certain value. The resolution is generally to use higher-level package management tools to upgrade the listed packages.

- `Provides`

  For some types of packages where there are multiple alternatives, virtual names have been defined. You can get the full list in the virtual-package-names-list.txt.gz file. Use this if your program provides a function of an existing virtual package.

- `Replaces`

  Use this when your program replaces files from another package, or completely replaces another package (used in conjunction with `Conflicts`). Files from the named packages will be overwritten with the files from your package.

All these fields have uniform syntax. They are a list of package names separated by commas. These package names may also be lists of alternative package names, separated by vertical bar symbols `|` (pipe symbols).

The fields may restrict their applicability to particular versions of each named package. The restriction of each individual package is listed in parentheses after its name, and should contain a relation from the list below followed by a version number value. The relations allowed are: `<<`, `<=`, `=`, `>=`, and `>>` for strictly lower, lower or equal, exactly equal, greater or equal, and strictly greater, respectively. For example,

    Depends: foo (>= 1.2), libbar1 (= 1.3.4)
    Conflicts: baz
    Recommends: libbaz4 (>> 4.0.7)
    Suggests: quux
    Replaces: quux (<< 5), quux-foo (<= 7.6)

The last feature you need to know about is `${shlibs:Depends}`, `${perl:Depends}`, `${misc:Depends}`, etc.

dh_shlibdeps(1) calculates shared library dependencies for binary packages. It generates a list of ELF executables and shared libraries it has found for each binary package. This list is used for substituting `${shlibs:Depends}`.

dh_perl(1) calculates Perl dependencies. It generates a list of a dependencies on `perl` or `perlapi` for each binary package. This list is used for substituting `${perl:Depends}`.

Some `debhelper` commands may cause the generated package to depend on some additional packages. All such commands generate a list of required packages for each binary package. This list is used for substituting `${misc:Depends}`.

dh_gencontrol(1) generates `DEBIAN/control` for each binary package while substituting `${shlibs:Depends}`, `${perl:Depends}`, `${misc:Depends}`, etc.

Having said all that, we can leave the `Depends` field exactly as it is now, and insert another line after it saying `Suggests: file`, because `gentoo` can use some features provided by the `file` package.

Line 9 is the Homepage URL. Let's assume this to be at http://www.obsession.se/gentoo/.

Line 12 is the short description. Terminals are conventionally 80 columns wide so this shouldn't be longer than about 60 characters. I'll change it to `fully GUI-configurable, two-pane X file manager`.

Line 13 is where the long description goes. This should be a paragraph which gives more details about the package. Column 1 of each line should be empty. There must be no blank lines, but you can put a single `.` (dot) in a column to simulate that. Also, there must be no more than one blank line after the long description. [34]

We can insert `Vcs-*` fields to document the Version Control System (VCS) location between lines 6 and 7. [35] Let's assume that the `gentoo` package has its VCS located in the Debian Alioth Git Service at `git://git.debian.org/git/collab-maint/gentoo.git`.

Finally, here is the updated `control` file:

     1 Source: gentoo
     2 Section: x11
     3 Priority: optional
     4 Maintainer: Josip Rodin <joy-mg@debian.org>
     5 Build-Depends: debhelper (>=10), xlibs-dev, libgtk1.2-dev, libglib1.2-dev
     6 Standards-Version: 4.0.0
     7 Vcs-Git: https://anonscm.debian.org/git/collab-maint/gentoo.git
     8 Vcs-browser: https://anonscm.debian.org/git/collab-maint/gentoo.git
     9 Homepage: http://www.obsession.se/gentoo/
    10
    11 Package: gentoo
    12 Architecture: any
    13 Depends: ${shlibs:Depends}, ${misc:Depends}
    14 Suggests: file
    15 Description: fully GUI-configurable, two-pane X file manager
    16  gentoo is a two-pane file manager for the X Window System. gentoo lets the
    17  user do (almost) all of the configuration and customizing from within the
    18  program itself. If you still prefer to hand-edit configuration files,
    19  they're fairly easy to work with since they are written in an XML format.
    20  .
    21  gentoo features a fairly complex and powerful file identification system,
    22  coupled to an object-oriented style system, which together give you a lot
    23  of control over how files of different types are displayed and acted upon.
    24  Additionally, over a hundred pixmap images are available for use in file
    25  type descriptions.
    26  .
    29  gentoo was written from scratch in ANSI C, and it utilizes the GTK+ toolkit
    30  for its interface.

(I've added the line numbers.)

## 4.2. `copyright`

This file contains information about the copyright and license of the upstream sources. Debian Policy Manual, 12.5 "Copyright information" dictates its content and DEP-5: Machine-parseable `debian/copyright` provides guidelines for its format.

dh_make can give you a template `copyright` file. Let's use the `--copyright gpl2` option here to get a template file for the `gentoo` package released under GPL-2.

You must fill in missing information to complete this file, such as the place you got the package from, the actual copyright notice, and the license. For certain common free software licenses (GNU GPL-1, GNU GPL-2, GNU GPL-3, LGPL-2, LGPL-2.1, LGPL-3, GNU FDL-1.2, GNU FDL-1.3, Apache-2.0, 3-Clause BSD, CC0-1.0, MPL-1.1, MPL-2.0 or the Artistic license), you can just refer to the appropriate file in the `/usr/share/common-licenses/` directory that exists on every Debian system. Otherwise, you must include the complete license.

In short, here's what `gentoo`'s `copyright` file should look like:

     1 Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
     2 Upstream-Name: gentoo
     3 Upstream-Contact: Emil Brink <emil@obsession.se>
     4 Source: http://sourceforge.net/projects/gentoo/files/
     5
     6 Files: *
     7 Copyright: 1998-2010 Emil Brink <emil@obsession.se>
     8 License: GPL-2+
     9
    10 Files: icons/*
    11 Copyright: 1998 Johan Hanson <johan@tiq.com>
    12 License: GPL-2+
    13
    14 Files: debian/*
    15 Copyright: 1998-2010 Josip Rodin <joy-mg@debian.org>
    16 License: GPL-2+
    17
    18 License: GPL-2+
    19  This program is free software; you can redistribute it and/or modify
    20  it under the terms of the GNU General Public License as published by
    21  the Free Software Foundation; either version 2 of the License, or
    22  (at your option) any later version.
    23  .
    24  This program is distributed in the hope that it will be useful,
    25  but WITHOUT ANY WARRANTY; without even the implied warranty of
    26  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    27  GNU General Public License for more details.
    28  .
    29  You should have received a copy of the GNU General Public License along
    30  with this program; if not, write to the Free Software Foundation, Inc.,
    31  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
    32  .
    33  On Debian systems, the full text of the GNU General Public
    34  License version 2 can be found in the file
    35  '/usr/share/common-licenses/GPL-2'.

(I've added the line numbers.)

Please follow the HOWTO provided by the ftpmasters and sent to debian-devel-announce: http://lists.debian.org/debian-devel-announce/2006/03/msg00023.html.

## 4.3. `changelog`

This is a required file, which has a special format described in Debian Policy Manual, 4.4 "debian/changelog". This format is used by dpkg and other programs to obtain the version number, revision, distribution, and urgency of your package.

For you, it is also important, since it is good to have documented all changes you have done. It will help people downloading your package to see whether there are issues with the package that they should know about. It will be saved as `/usr/share/doc/gentoo/changelog.Debian.gz` in the binary package.

dh_make created a default one, and this is what it looks like:

    1  gentoo (0.9.12-1) unstable; urgency=medium
    2
    3   * Initial release. (Closes: #nnnn)  <nnnn is the bug number of your ITP>
    4
    5  -- Josip Rodin <joy-mg@debian.org>  Mon, 22 Mar 2010 00:37:31 +0100
    6

(I've added the line numbers.)

Line 1 is the package name, version, distribution, and urgency. The name must match the source package name; distribution should be `unstable`, and urgency should be set to medium unless there is any particular reason for other values.

Lines 3-5 are a log entry, where you document changes made in this package revision (not the upstream changes — there is a special file for that purpose, created by the upstream authors, which you will later install as `/usr/share/doc/gentoo/changelog.gz`). Let's assume your ITP (Intent To Package) bug report number was `12345`. New lines must be inserted just below the uppermost line that begins with `*` (asterisk). You can do it with dch(1). You can edit this manually with a text editor as long as you follow the formatting convention used by the dch(1).

In order to prevent a package being accidentally uploaded before completing the package, it is a good idea to change the distribution value to an invalid distribution value of `UNRELEASED`.

You will end up with something like this:

    1  gentoo (0.9.12-1) UNRELEASED; urgency=low
    2
    3   * Initial Release. Closes: #12345
    4   * This is my first Debian package.
    5   * Adjusted the Makefile to fix $(DESTDIR) problems.
    6
    7  -- Josip Rodin <joy-mg@debian.org>  Mon, 22 Mar 2010 00:37:31 +0100
    8

(I've added the line numbers.)

Once you are satisfied with all the changes and documented them in `changelog`, you should change the distribution value from `UNRELEASED` to the target distribution value `unstable` (or even `experimental`). [36]

You can read more about updating the `changelog` file later in Chapter 8, Updating the package.

## 4.4. `rules`

Now we need to take a look at the exact rules that dpkg-buildpackage(1) will use to actually create the package. This file is in fact another `Makefile`, but different from the one(s) in the upstream source. Unlike other files in `debian`, this one is marked as executable.

### 4.4.1. Targets of the `rules` file

Every `rules` file, like any other `Makefile`, consists of several rules, each of which defines a target and how it is carried out. [37] A new rule begins with its target declaration in the first column. The following lines beginning with the TAB code (ASCII 9) specify the recipe for carrying out that target. Empty lines and lines beginning with `#` (hash) are treated as comments and ignored. [38]

A rule that you want to execute is invoked by its target name as a command line argument. For example, `debian/rules `build`` and `fakeroot make -f debian/rules `binary`` execute rules for ``build`` and ``binary`` targets, respectively.

Here is a simplified explanation of the targets:

- `clean` target: to clean all compiled, generated, and useless files in the build-tree. (Required)

- `build` target: to build the source into compiled programs and formatted documents in the build-tree. (Required)

- `build-arch` target: to build the source into arch-dependent compiled programs in the build-tree. (Required)

- `build-indep` target: to build the source into arch-independent formatted documents in the build-tree. (Required)

- `install` target: to install files into a file tree for each binary package under the `debian` directory. If defined, `binary*` targets effectively depend on this target. (Optional)

- `binary` target: to create all binary packages (effectively a combination of `binary-arch` and `binary-indep` targets). (Required)[39]

- `binary-arch` target: to create arch-dependent (`Architecture: any`) binary packages in the parent directory. (Required)[40]

- `binary-indep` target: to create arch-independent (`Architecture: all`) binary packages in the parent directory. (Required)[41]

- `get-orig-source` target: to obtain the most recent version of the original source package from an upstream archive. (Optional)

You are probably overwhelmed by now, but things are much simpler upon examination of the `rules` file that dh_make gives us as a default.

### 4.4.2. Default `rules` file

Newer dh_make generates a very simple but powerful default `rules` file using the dh command:

     1 #!/usr/bin/make -f
     2 # See debhelper(7) (uncomment to enable)
     3 # output every command that modifies files on the build system.
     4 #DH_VERBOSE = 1
     5
     6 # see FEATURE AREAS in dpkg-buildflags(1)
     7 #export DEB_BUILD_MAINT_OPTIONS = hardening=+all
     8
     9 # see ENVIRONMENT in dpkg-buildflags(1)
    10 # package maintainers to append CFLAGS
    11 #export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
    12 # package maintainers to append LDFLAGS
    13 #export DEB_LDFLAGS_MAINT_APPEND = -Wl,--as-needed
    14
    15
    16 %:
    17         dh $@

(I've added the line numbers and trimmed some comments. In the actual `rules` file, the leading spaces are a TAB code.)

You are probably familiar with lines like line 1 from shell and Perl scripts. It tells the operating system that this file is to be processed with `/usr/bin/make`.

Line 4 can be uncommented to set the `DH_VERBOSE` variable to 1, so that the dh command outputs which dh_* commands it is executing. You can also add a line `export DH_OPTIONS=-v` here, so that each dh_* command outputs which commands it is executing. This helps you to understand exactly what is going on behind this simple `rules` file and to debug its problems. This new dh is designed to form a core part of the `debhelper` tools, and not to hide anything from you.

Lines 16 and 17 are where all the work is done with an implicit rule using the pattern rule. The percent sign means "any targets", which then call a single program, dh, with the target name. [42] The dh command is a wrapper script that runs appropriate sequences of dh_* programs depending on its argument. [43]

- `debian/rules clean` runs `dh clean`, which in turn runs the following:

      dh_testdir
      dh_auto_clean
      dh_clean

- `debian/rules build` runs `dh build`, which in turn runs the following:

      dh_testdir
      dh_auto_configure
      dh_auto_build
      dh_auto_test

- `fakeroot debian/rules binary` runs `fakeroot dh binary`, which in turn runs the following[44]:

      dh_testroot
      dh_prep
      dh_installdirs
      dh_auto_install
      dh_install
      dh_installdocs
      dh_installchangelogs
      dh_installexamples
      dh_installman
      dh_installcatalogs
      dh_installcron
      dh_installdebconf
      dh_installemacsen
      dh_installifupdown
      dh_installinfo
      dh_installinit
      dh_installmenu
      dh_installmime
      dh_installmodules
      dh_installlogcheck
      dh_installlogrotate
      dh_installpam
      dh_installppp
      dh_installudev
      dh_installwm
      dh_installxfonts
      dh_bugfiles
      dh_lintian
      dh_gconf
      dh_icons
      dh_perl
      dh_usrlocal
      dh_link
      dh_compress
      dh_fixperms
      dh_strip
      dh_makeshlibs
      dh_shlibdeps
      dh_installdeb
      dh_gencontrol
      dh_md5sums
      dh_builddeb

- `fakeroot debian/rules binary-arch` runs `fakeroot dh binary-arch`, which in turn runs the same sequence as `fakeroot dh binary` but with the `-a` option appended for each command.

- `fakeroot debian/rules binary-indep` runs `fakeroot dh binary-indep`, which in turn runs almost the same sequence as `fakeroot dh binary` but excluding dh_strip, dh_makeshlibs, and dh_shlibdeps with the `-i` option appended for each remaining command.

The functions of dh_* commands are largely self-evident from their names. [45] There are a few notable ones that are worth giving (over)simplified explanations here assuming a typical build environment based on a `Makefile`: [46]

- dh_auto_clean usually executes the following if a `Makefile` exists with the `distclean` target. [47]

      make distclean

- dh_auto_configure usually executes the following if `./configure` exists (arguments abbreviated for readability).

      ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var ...

- dh_auto_build usually executes the following to execute the first target of `Makefile` if it exists.

      make

- dh_auto_test usually executes the following if a `Makefile` exists with the `test` target. [48]

      make test

- dh_auto_install usually executes the following if a `Makefile` exists with the `install` target (line folded for readability).

      make install \
        DESTDIR=/path/to/package_version-revision/debian/package

All targets which require the fakeroot command will contain dh_testroot, which exits with an error if you are not using this command to pretend to be root.

The important part to know about the `rules` file created by dh_make is that it is just a suggestion. It will work for most packages but for more complicated ones, don't be afraid to customize it to fit your needs.

Although `install` is not a required target, it is supported. `fakeroot dh install` behaves like `fakeroot dh binary` but stops after dh_fixperms.

### 4.4.3. Customization of `rules` file

There are many ways to customize the `rules` file created with the new dh command.

The `dh $@` command can be customized as follows: [49]

- Add support for the dh_python2 command. (The best choice for Python.) [50]

  - Include the `python` package in `Build-Depends`.

  - Use `dh $@ --with python2`.

  - This handles Python modules using the `python` framework.

- Add support for the dh_pysupport command. (deprecated)

  - Include the `python-support` package in `Build-Depends`.

  - Use `dh $@ --with pysupport`.

  - This handles Python modules using the `python-support` framework.

- Add support for the dh_pycentral command. (deprecated)

  - Include the `python-central` package in `Build-Depends`.

  - Use `dh $@ --with python-central` instead.

  - This also deactivates the dh_pysupport command.

  - This handles Python modules using the `python-central` framework.

- Add support for the dh_installtex command.

  - Include the `tex-common` package in `Build-Depends`.

  - Use `dh $@ --with tex` instead.

  - This registers Type 1 fonts, hyphenation patterns, and formats with TeX.

- Add support for the dh_quilt_patch and dh_quilt_unpatch commands.

  - Include the `quilt` package in `Build-Depends`.

  - Use `dh $@ --with quilt` instead.

  - This applies and un-applies patches to the upstream source from files in the `debian/patches` directory for a source package in the `1.0` format.

  - This is not needed if you use the new `3.0 (quilt)` source package format.

- Add support for the dh_dkms command.

  - Include the `dkms` package in `Build-Depends`.

  - Use `dh $@ --with dkms` instead.

  - This correctly handles DKMS usage by kernel module packages.

- Add support for the dh_autotools-dev_updateconfig and dh_autotools-dev_restoreconfig commands.

  - Include the `autotools-dev` package in `Build-Depends`.

  - Use `dh $@ --with autotools-dev` instead.

  - This updates and restores `config.sub` and `config.guess`.

- Add support for the dh_autoreconf and dh_autoreconf_clean commands.

  - Include the `dh-autoreconf` package in `Build-Depends`.

  - Use `dh $@ --with autoreconf` instead.

  - This updates the GNU Build System files and restores them after the build.

- Add support for the dh_girepository command.

  - Includes the `gobject-introspection` package in `Build-Depends`.

  - Use `dh $@ --with gir` instead.

  - This computes dependencies for packages shipping GObject introspection data and generates the `${gir:Depends}` substitution variable for the package dependency.

- Add support for the bash completion feature.

  - Includes the `bash-completion` package in `Build-Depends`.

  - Use `dh $@ --with bash-completion` instead.

  - This installs bash completions using a configuration file at `debian/`package`.bash-completion`.

Many dh_* commands invoked by the new dh command can be customized by the corresponding configuration files in the `debian` directory. See Chapter 5, Other files under the `debian` directory and the manpage of each command for the customization of such features.

You may need to run dh_* commands invoked via the new dh with added arguments, or to run additional commands with them, or to skip them. For such cases, you create an `override_dh_`foo`` target with its rule in the `rules` file defining an `override_dh_`foo`` target for the dh_`foo` command you want to change. It basically says run me instead. [51]

Please note that the dh_auto_* commands tend to do more than what has been discussed in this (over)simplified explanation to take care of all the corner cases. It is a bad idea to use `override_dh_*` targets to substitute simplified equivalent commands (except for the `override_dh_auto_clean` target) since it may bypass such smart `debhelper` features.

So, for instance, if you want to store system configuration data in the `/etc/gentoo` directory instead of the usual `/etc` directory for the recent `gentoo` package using Autotools, you can override the default `--sysconfig=/etc` argument given by the dh_auto_configure command to the ./configure command by the following:

    override_dh_auto_configure:
            dh_auto_configure -- --sysconfig=/etc/gentoo

The arguments given after `--` are appended to the default arguments of the auto-executed program to override them. Using the dh_auto_configure command is better than directly invoking the ./configure command here since it will only override the `--sysconfig` argument and retain any other, benign arguments to the ./configure command.

If the `Makefile` in the source for `gentoo` requires you to specify `build` as its target to build it [52], you create an `override_dh_auto_build` target to enable this.

    override_dh_auto_build:
            dh_auto_build -- build

This ensures `$(MAKE)` is run with all the default arguments given by the dh_auto_build command plus the `build` argument.

If the `Makefile` in the source for `gentoo` requires you to specify the `packageclean` target to clean it for the Debian package instead of using `distclean` or `clean` targets, you can create an `override_dh_auto_clean` target to enable it.

    override_dh_auto_clean:
            $(MAKE) packageclean

If the `Makefile` in the source for `gentoo` contains a `test` target which you do not want to run for the Debian package building process, you can use an empty `override_dh_auto_test` target to skip it.

    override_dh_auto_test:

If `gentoo` has an unusual upstream changelog file called `FIXES`, dh_installchangelogs will not install that file by default. The dh_installchangelogs command requires `FIXES` as its argument to install it. [53]

    override_dh_installchangelogs:
            dh_installchangelogs FIXES

When you use the new dh command, use of explicit targets such as the ones listed in Section 4.4.1, “Targets of the `rules` file”, other than the `get-orig-source` target, may make it difficult to understand their exact effects. Please limit explicit targets to `override_dh_*` targets and completely independent ones, if possible.

[27] In this chapter, files in the `debian` directory are referred to without the leading `debian/` for simplicity whenever the meaning is obvious.

[28] See Debian Policy Manual, 2.4 "Sections" and List of sections in `sid`.

[29] See Debian Policy Manual, 2.5 "Priorities".

[30] See Debian Policy Manual, 7.7 "Relationships between source and binary packages - Build-Depends, Build-Depends-Indep, Build-Conflicts, Build-Conflicts-Indep".

[31] This somewhat strange situation is a feature well documented in the Debian Policy Manual, Footnotes 55. This is not due to the use of the dh command in the `debian/rules` file but due to how the dpkg-buildpackage works. The same situation applies to the auto build system for Ubuntu.

[32] See Debian Policy Manual, 5.6.8 "Architecture" for exact details.

[33] See Debian Policy Manual, 7 "Declaring relationships between packages".

[34] These descriptions are in English. Translations of these descriptions are provided by The Debian Description Translation Project - DDTP.

[35] See Debian Developer's Reference, 6.2.5. "Version Control System location".

[36] If you use the `dch -r` command to make this last change, please make sure to save the `changelog` file explicitly by the editor.

[37] You can start learning how to write a `Makefile` from Debian Reference, 12.2. "Make". The full documentation is available as http://www.gnu.org/software/make/manual/html_node/index.html or as the `make-doc` package in the `non-free` archive area.

[38] Debian Policy Manual, 4.9 "Main building script: debian/rules" explains the details.

[39] This target is used by `dpkg-buildpackage` as in Section 6.1, “Complete (re)build”.

[40] This target is used by `dpkg-buildpackage -B` as in Section 6.2, “Autobuilder”.

[41] This target is used by `dpkg-buildpackage -A`.

[42] This uses the new `debhelper` v7+ features. Its design concepts are explained in Not Your Grandpa's Debhelper presented at DebConf9 by the `debhelper` upstream. Under `lenny`, dh_make created a much more complicated `rules` file with explicit rules and many dh_* scripts listed for each one, most of which are now unnecessary (and show the package's age). The new dh command is simpler and frees us from doing the routine work "manually". You still have full power to customize the process with `override_dh_*` targets. See Section 4.4.3, “Customization of `rules` file”. It is based only on the `debhelper` package and does not obfuscate the package building process as the `cdbs` package tends to do.

[43] You can verify the actual sequences of dh_* programs invoked for a given ``target`` without really running them by invoking `dh `target` --no-act` or `debian/rules -- '`target` --no-act'`.

[44] The following example assumes your `debian/compat` has a value equal or more than 9 to avoid invoking any python support commands automatically.

[45] For complete information on what all these dh_* scripts do exactly, and what their other options are, please read their respective manual pages and the `debhelper` documentation.

[46] These commands support other build environments, such as `setup.py`, which can be listed by executing `dh_auto_build --list` in a package source directory.

[47] It actually looks for the first available target in the `Makefile` out of `distclean`, `realclean`, or `clean`, and executes that.

[48] It actually looks for the first available target in the `Makefile` out of `test` or `check`, and executes that.

[49] If a package installs the `/usr/share/perl5/Debian/Debhelper/Sequence/`custom_name`.pm` file, you should activate its customization function by `dh $@ --with `custom-name``.

[50] Use of the dh_python2 command is preferred over use of dh_pysupport or dh_pycentral commands. Do not use the dh_python command.

[51] Under `lenny`, if you wanted to change the behavior of a dh_* script you found the relevant line in the `rules` file and adjusted it.

[52] dh_auto_build without any arguments will execute the first target in the `Makefile`.

[53] The `debian/changelog` and `debian/NEWS` files are always automatically installed. The upstream changelog is found by converting filenames to lower case and matching them against `changelog`, `changes`, `changelog.txt`, and `changes.txt`.

Chapter 3. Modifying the source |  | Chapter 5. Other files under the `debian` directory