# Other files under the debian directory

The `dh_make` command had major updates since this old document was written. So some parts of this document aren't applicable any more.

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.

The `debmake` command is used in place of the `dh_make` command in my new Guide for Debian Maintainers.

To control most of what `debhelper` does while building the package, you put optional configuration files under the `debian` directory. This chapter will provide an overview of what each of these does and its format. Please read the Debian Policy Manual and Debian Developer's Reference for guidelines for packaging.

The `dh_make` command will create some template configuration files under the `debian` directory. Take a look at all of them.

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

Some template configuration files for `debhelper` may not be created by the `dh_make` command. In such cases, you need to create them with an editor.

If you wish or need to activate any of these, please do the following:

- rename the configuration files to use the actual binary package name in place of ``package``;

- modify template file contents to suit your needs;

- remove template files which you do not need;

- modify the `control` file (see control), if necessary;

- modify the `rules` file (see rules), if necessary.

Any `debhelper` configuration files without a ``package`` prefix, such as `install`, apply to the first binary package. When there are many binary packages, their configurations can be specified by prefixing their name to their configuration filenames such as ``package-1`.install`, ``package-2`.install`, etc.

## `README.Debian`

Any extra details or discrepancies between the original package and your Debian version should be documented here.

`dh_make` created a default one; this is what it looks like:

    gentoo for Debian
    -----------------
    <possible notes regarding this package - if none, delete this file>
     -- Josip Rodin <joy-mg@debian.org>, Wed, 11 Nov 1998 21:02:14 +0100

If you have nothing to be documented, remove this file. See

dh_installdocs

1 .

## `compat`

The `compat` file defines the `debhelper` compatibility level. Currently, you should set it to the `debhelper` v10 as follows:

    $ echo 10 > debian/compat

You may use compat level v9 in certain circumstances for compatibility with older systems. However, using any level below v9 is not recommended and should be avoided for new packages.

## `conffiles`

One of the most annoying things about software is when you spend a great deal of time and effort customizing a program, only to have an upgrade stomp all over your changes. Debian solves this problem by marking such configuration files as conffiles.

See

dpkg

1 and Debian Policy Manual, "D.2.5 Conffiles".
When you upgrade a package, you'll be asked whether you want to keep your old configuration files or not.

dh_installdeb

1 automatically flags any files under the `/etc` directory as conffiles, so if your program only has conffiles there you do not need to specify them in this file. For most package types, the only place conffiles should ever be is under `/etc`, and so this file doesn't need to exist.

If your program uses configuration files but also rewrites them on its own, it's best not to make them conffiles because `dpkg` will then prompt users to verify the changes all the time.

If the program you're packaging requires every user to modify the configuration files in the `/etc` directory, there are two popular ways to arrange for them to not be conffiles, keeping `dpkg` quiet:

- Create a symlink under the `/etc` directory pointing to a file under the `/var` directory generated by the maintainer scripts.

- Create a file generated by the maintainer scripts under the `/etc` directory.

For information on maintainer scripts, see maintscripts.

## ``package`.cron.*`

If your package requires regularly scheduled tasks to operate properly, you can use these files to set that up. You can set up regular tasks that either happen hourly, daily, weekly, or monthly, or alternatively happen at any other time that you wish. The filenames are:

- ``package`.cron.hourly` - Installed as `/etc/cron.hourly/`package``; run once an hour.

- ``package`.cron.daily` - Installed as `/etc/cron.daily/`package``; run once a day.

- ``package`.cron.weekly` - Installed as `/etc/cron.weekly/`package``; run once a week.

- ``package`.cron.monthly` - Installed as `/etc/cron.monthly/`package``: run once a month.

- ``package`.cron.d` - Installed as `/etc/cron.d/`package``: for any other time.

Most of these files are shell scripts, with the exception of ``package`.cron.d` which follows the format of

crontab

5 .

No explicit `cron.*` file is needed to set up log rotation; for that, see

dh_installlogrotate

1 and

logrotate

8.

## `dirs`

This file specifies any directories which we need but which are not created by the normal installation procedure (`make install DESTDIR=...` invoked by `dh_auto_install`). This generally means there is a problem with the `Makefile`.

Files listed in an `install` file don't need their directories created first. See install.

It is best to try to run the installation first and only use this if you run into trouble. There is no preceding slash on the directory names listed in the `dirs` file.

## ``package`.doc-base`

If your package has documentation other than manual and info pages, you should use the `doc-base` file to register it, so the user can find it with e.g.

dhelp

1 ,

dwww

1 , or

doccentral

1 .

This usually includes HTML, PS and PDF files, shipped in `/usr/share/doc/`packagename`/`.

This is what `gentoo`'s doc-base file `gentoo.doc-base` looks like:

    Document: gentoo
    Title: Gentoo Manual
    Author: Emil Brink
    Abstract: This manual describes what Gentoo is, and how it can be used.
    Section: File Management
    Format: HTML
    Index: /usr/share/doc/gentoo/html/index.html
    Files: /usr/share/doc/gentoo/html/*.html

For information on the file format, see

install-docs

8 and the Debian `doc-base` manual at the local copy `&doc-base;` provided by the `doc-base` package.

For more details on installing additional documentation, look in destdir.

## `docs`

This file specifies the file names of documentation files we can have

dh_installdocs

1 install into the temporary directory for us.

By default, it will include all existing files in the top-level source directory that are called `BUGS`, `README*`, `TODO` etc.

For `gentoo`, some other files are also included:

    BUGS
    CONFIG-CHANGES
    CREDITS
    NEWS
    README
    README.gtkrc
    TODO

## `emacsen-*`

If your package supplies Emacs files that can be bytecompiled at package installation time, you can use these files to set it up.

They are installed into the temporary directory by

dh_installemacsen

1 .

If you don't need these, remove them.

## ``package`.examples`

The

dh_installexamples

1 command installs files and directories listed in this file as example files.

## ``package`.init` and ``package`.default`

If your package is a daemon that needs to be run at system start-up, you've obviously disregarded my initial recommendation, haven't you? :-)

Please read

dh_installinit

1

dh_installsystemd

1 to provide startup script.

The ``package`.default` file will be installed as `/etc/default/`package``. This file sets defaults that are sourced by the init script. This ``package`.default` file is most often used to set some default flags or timeouts. If your init script has certain configurable features, you can set them in the ``package`.default` file, instead of in the init script itself.

If your upstream program provides a file for the init script, you can either use it or not. If you don't use their init script then create a new one in ``package`.init`. However if the upstream init script looks fine and installs in the right place you still need to set up the `rc*` symlinks. To do this you will need to override `dh_installinit` in the `rules` file with the following lines:

    override_dh_installinit:
            dh_installinit --onlyscripts

If you don't need this, remove the files.

## `install`

If there are files that need to be installed into your package but your standard `make install` won't do it, put the filenames and destinations into this `install` file. They are installed by

dh_install

1 .

This replaces the deprecated

dh_movefiles

1 command which is configured by the `files` file.
You should first check that there is not a more specific tool to use. For example, documents should be in the `docs` file and not in this one.

This `install` file has one line per file installed, with the name of the file (relative to the top build directory) then a space then the installation directory (relative to the install directory). One example of where this is used is if a binary `src/`bar`` is left uninstalled; the `install` file might look like:

    src/bar usr/bin

This means when this package is installed, there will be an executable command `/usr/bin/`bar``.

Alternatively, this `install` can have the name of the file only without the installation directory when the relative directory path does not change. This format is usually used for a large package that splits the output of its build into multiple binary packages using ``package-1`.install`, ``package-2`.install`, etc.

The `dh_install` command will fall back to looking in `debian/tmp` for files, if it doesn't find them in the current directory (or wherever you've told it to look using `--sourcedir`).

## ``package`.info`

If your package has info pages, you should install them using

dh_installinfo

1 by listing them in a ``package`.info` file.

## ``package`.links`

If you need to create additional symlinks in package build directories as package maintainer, you should install them using

dh_link

1 by listing their full paths of source and destination files in a ``package`.links` file.

## `{`package`.,source/}lintian-overrides`

If `lintian` reports an erroneous diagnostic for a case where Debian policy allows exceptions to some rule, you can use ``package`.lintian-overrides` or `source/lintian-overrides` to quieten it. Please read the Lintian User's Manual (`&lintian-doc;`) and refrain from abusing this.

``package`.lintian-overrides` is for the binary package named ``package`` and is installed into `usr/share/lintian/overrides/`package`` by the `dh_lintian` command.

`source/lintian-overrides` is for the source package. This is not installed.

## `manpage.*`

Your program(s) should have a manual page. If they don't, you should create them. The `dh_make` command creates some template files for manual pages. These need to be copied and edited for each command missing its manual page. Please make sure to remove unused templates.

### `manpage.1.ex`

Manual pages are normally written in

nroff

1 . The `manpage.1.ex` template is written in `nroff`, too. See the

man

7 manual page for a brief description of how to edit such a file.

The final manual page file name should give the name of the program it is documenting, so we will rename it from `manpage` to `gentoo`. The file name also includes `.1` as the first suffix, which means it's a manual page for a user command. Be sure to verify that this section is indeed the correct one. Here's a short list of manual page sections:

Section | Description | Notes
1 | User commands | Executable commands or scripts
2 | System calls | Functions provided by the kernel
3 | Library calls | Functions within system libraries
4 | Special files | Usually found in `/dev`
5 | File formats | E.g. `/etc/passwd`'s format
6 | Games | Games or other frivolous programs
7 | Macro packages | Such as `man` macros
8 | System administration | Programs typically only run by root
9 | Kernel routines | Non-standard calls and internals

So `gentoo`'s man page should be called `gentoo.1`. If there was no `gentoo.1` man page in the original source, you should create it by renaming the `manpage.1.ex` template to `gentoo.1` and editing it using information from the example and from the upstream docs.

You can use the `help2man` command to generate a man page out of the `--help` and `--version` output of each program, too.

Note that `help2man`'s placeholder man page will claim that more detailed documentation is available in the info system. If the command is missing an `info` page, you should manually edit the man page created by the `help2man` command.

### `manpage.sgml.ex`

If on the other hand you prefer writing SGML instead of `nroff`, you can use the `manpage.sgml.ex` template. If you do this, you have to:

- rename the file to something like `gentoo.sgml`.

- install the `docbook-to-man` package

- add `docbook-to-man` to the `Build-Depends` line in the `control` file

- add an `override_dh_auto_build` target to your `rules` file:

      override_dh_auto_build:
              docbook-to-man debian/gentoo.sgml > debian/gentoo.1
              dh_auto_build

### `manpage.xml.ex`

If you prefer XML over SGML, you can use the `manpage.xml.ex` template. If you do this, you have to:

- rename the source file to something like `gentoo.1.xml`

- install the `docbook-xsl` package and an XSLT processor like `xsltproc` (recommended)

- add the `docbook-xsl`, `docbook-xml`, and `xsltproc` packages to the `Build-Depends` line in the `control` file

- add an `override_dh_auto_build` target to your `rules` file:

      override_dh_auto_build:
              xsltproc --nonet \
               --param make.year.ranges 1 \
               --param make.single.year.ranges 1 \
               --param man.charmap.use.subset 0 \
               -o debian/ \
      http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl\
              debian/gentoo.1.xml
              dh_auto_build

## ``package`.manpages`

If your package has manual pages, you should install them using

dh_installman

1 by listing them in a ``package`.manpages` file.

To install `docs/gentoo.1` as a manpage for the `gentoo` package, create a `gentoo.manpages` file as follows:

    docs/gentoo.1

## `NEWS`

The

dh_installchangelogs

1 command installs this.

## `{pre,post}{inst,rm}`

These `postinst`, `preinst`, `postrm`, and `prerm` files

Despite this use of the `bash` shorthand expression `{pre,post}{inst,rm}` to indicate these filenames, you should use pure POSIX syntax for these maintainer scripts for compatibility with `dash` as the system shell.

are called maintainer scripts. They are scripts which are put in the control area of the package and run by `dpkg` when your package is installed, upgraded, or removed.

As a novice maintainer, you should avoid any manual editing of maintainer scripts because they are problematic. For more information refer to the Debian Policy Manual, 6 "Package maintainer scripts and installation procedure", and take a look at the example files provided by `dh_make`.

If you did not listen to me and have created custom maintainer scripts for a package, you should make sure to test them not only for install and upgrade but also for remove and purge.

Upgrades to the new version should be silent and non-intrusive (existing users should not notice the upgrade except by discovering that old bugs have been fixed and perhaps that there are new features).

When the upgrade is necessarily intrusive (eg., config files scattered through various home directories with totally different structure), you may consider as the last resort switching the package to a safe fallback state (e.g., disabling a service) and providing the proper documentation required by policy (`README.Debian` and `NEWS.Debian`). Don't bother the user with `debconf` notes invoked from these maintainer scripts for upgrades.

The `ucf` package provides a conffile-like handling infrastructure to preserve user changes for files that may not be labeled as conffiles such as those managed by the maintainer scripts. This should minimize issues associated with them.

These maintainer scripts are among the Debian enhancements that explain why people choose Debian. You must be very careful not to turn them into a source of annoyance.

## ``package`.symbols`

Packaging of a library is not easy for a novice maintainer and should be avoided. Having said it, if your package has libraries, you should have `debian/`package`.symbols` files. See librarysymbols.

## `TODO`

The

dh_installdocs

1 command installs this.

## `watch`

The `watch` file format is documented in the

uscan

1 manpage. The `watch` file configures the `uscan` program (in the `devscripts` package) to watch the site where you originally got the source. This is also used by the Debian Package Tracker service.

Here are its contents:

    # watch control file for uscan
    version=3
    &sf-net;/gentoo/gentoo-(.+)\.tar\.gz debian uupdate

Normally with a `watch` file, the URL at `&sf-net;/gentoo` is downloaded and searched for links of the form `<a href=...>`. The basename (just the part after the final `/`) of each linked URL is compared against the Perl regular expression pattern (see

perlre

1 ) `gentoo-(.+)\.tar\.gz`. Out of the files that match, the one with the greatest version number is downloaded and the `uupdate` program is run to create an updated source tree.

Although this is true for other sites, the SourceForge download service at is an exception. When the `watch` file has a URL matching the Perl regexp `^http://sf\.net/`, the `uscan` program replaces it with `&qa-do;watch/sf.php/` and then applies this rule. The URL redirector service at is designed to offer a stable redirect service to the desired file for any `watch` pattern of the form `&sf-net;/`project`/`tar-name`-(.+)\.tar\.gz`. This solves issues related to periodically changing SourceForge URLs.

If the upstream offers the cryptographic signature of the tarball, it is recommended to verify its authenticity using the `pgpsigurlmangle` option as described in

uscan

1 .

## `source/format`

In the `debian/source/format` file, there should be a single line indicating the desired format for the source package (check

dpkg-source

1 for an exhaustive list). After `squeeze`, it should say either:

- `3.0 (native)` for native Debian packages or

- `3.0 (quilt)` for everything else.

The newer `3.0 (quilt)` source format records modifications in a `quilt` patch series within `debian/patches`. Those changes are then automatically applied during extraction of the source package.

See DebSrc3.0 for a summary on the switch to the new `3.0 (quilt)` and `3.0 (native)` source formats.

The Debian modifications are simply stored in a `debian.tar.gz` archive containing all files under the `debian` directory. This new format supports inclusion of binary files such as PNG icons by the package maintainer without requiring tricks.

Actually, this new format also supports multiple upstream tarballs and more compression methods. These are beyond the scope of this document.

When `dpkg-source` extracts a source package in `3.0 (quilt)` source format, it automatically applies all patches listed in `debian/patches/series`. You can avoid applying patches at the end of the extraction with the `--skip-patches` option.

## `source/local-options`

When you want to manage Debian packaging activities under a VCS, you typically create one branch (e.g., `upstream`) tracking the upstream source and another branch (e.g., typically `master` for Git) tracking the Debian package. For the latter, you usually want to have unpatched upstream source with your `debian/*` files for the Debian packaging to ease merging of the new upstream source.

After you build a package, the source is normally left patched. You need to unpatch it manually by running `dquilt pop -a` before committing to the `master` branch. You can automate this by adding the optional `debian/source/local-options` file containing `unapply-patches`. This file is not included in the generated source package and changes the local build behavior only. This file may contain `abort-on-upstream-changes`, too (see

dpkg-source

1 ).

    unapply-patches
    abort-on-upstream-changes

## `source/options`

The autogenerated files in the source tree can be quite annoying for packaging since they generate meaningless large patch files. There are custom modules such as `dh_autoreconf` to ease this problem as described in customrules.

You can provide a Perl regular expression to the `--extend-diff-ignore` option argument of

dpkg-source

1 to ignore changes made to the autogenerated files while creating the source package.

As a general solution to address this problem of the autogenerated files, you can store such a `dpkg-source` option argument in the `source/options` file of the source package. The following will skip creating patch files for `config.sub`, `config.guess`, and `Makefile`.

    extend-diff-ignore = "(^|/)(config\.sub|config\.guess|Makefile)$"

## `patches/*`

The old `1.0` source format created a single large `diff.gz` file containing package maintenance files in `debian` and patch files for the source. Such a package is a bit cumbersome to inspect and understand for each source tree modification later. This is not so nice.

The newer `3.0 (quilt)` source format stores patches in `debian/patches/*` files using the `quilt` command. These patches and other package data which are all contained under the `debian` directory are packaged as the `debian.tar.gz` file. Since the `dpkg-source` command can handle `quilt` formatted patch data in the `3.0 (quilt)` source without the `quilt` package, it does not need a `Build-Depends` on `quilt`.

Several methods of patch set maintenance have been proposed and are in use for Debian packages. The `quilt` system is the preferred maintenance system in use. Others include `dpatch`, `dbs`, and `cdbs`. Many of these keep such patches as `debian/patches/*` files.

The `quilt` command is explained in

quilt

1 . It records modifications to the source as a stack of `-p1` patch files in the `debian/patches` directory and the source tree is untouched outside of the `debian` directory. The order of these patches is recorded in the `debian/patches/series` file. You can apply (=push), un-apply (=pop), and refresh patches easily.

If you are asking a sponsor to upload your package, this kind of clear separation and documentation of your changes is very important to expedite the package review by your sponsor.

For modify, we created three patches in `debian/patches`.

Since Debian patches are located in `debian/patches`, please make sure to set up the `dquilt` command properly as described in quiltrc.

When anyone (including yourself) provides a patch ``foo`.patch` to the source later, modifying a `3.0 (quilt)` source package is quite simple:

    $ dpkg-source -x gentoo_0.9.12.dsc
    $ cd gentoo-0.9.12
    $ dquilt import ../foo.patch
    $ dquilt push
    $ dquilt refresh
    $ dquilt header -e
    ... describe patch

The patches stored in the newer `3.0 (quilt)` source format must be fuzz free. You can ensure this with `dquilt pop -a; while dquilt push; do dquilt refresh; done`.