---

   debhelper    ( 7 )

---

DEBHELPER CONFIG FILES

Many debhelper commands make use of files in debian/ to control what they do. Besides the common debian/changelog and debian/control, which are in all packages, not just those using debhelper, some additional files can be used to configure the behavior of specific debhelper commands. These files are typically named debian/package.foo (where package of course, is replaced with the package that is being acted on).

For example, dh_installdocs uses files named debian/package.docs to list the documentation files it will install. See the man pages of individual commands for details about the names and formats of the files they use. Generally, these files will list files to act on, one file per line. Some programs in debhelper use pairs of files and destinations or slightly more complicated formats.

Note for the first (or only) binary package listed in debian/control, debhelper will use debian/foo when there's no debian/package.foo file. However, it is often a good idea to keep the package. prefix as it is more explicit. The primary exception to this are files that debhelper by default installs in every binary package when it does not have a package prefix (such as debian/copyright or debian/changelog).

In some rare cases, you may want to have different versions of these files for different architectures or OSes. If files named debian/package.foo.ARCH or debian/package.foo.OS exist, where ARCH and OS are the same as the output of "dpkg-architecture -qDEB_HOST_ARCH" / "dpkg-architecture -qDEB_HOST_ARCH_OS", then they will be used in preference to other, more general files.

Mostly, these config files are used to specify lists of various types of files. Documentation or example files to install, files to move, and so on. When appropriate, in cases like these, you can use standard shell wildcard characters (? and * and [..] character classes) in the files. You can also put comments in these files; lines beginning with # are ignored.

The syntax of these files is intentionally kept very simple to make them easy to read, understand, and modify.

Substitutions in debhelper config files In compatibility level 13 and later, it is possible to use simple substitutions in debhelper config files for the following tools:

• dh_clean

• dh_install

• dh_installcatalogs

• dh_installdeb

• dh_installdirs

• dh_installdocs

• dh_installexamples

• dh_installinfo

• dh_installman

• dh_installwm

• dh_link

• dh_missing

• dh_ucf

All substitution variables are of the form ${foo} and the braces are mandatory. Variable names are case-sensitive and consist of alphanumerics (a-zA-Z0-9), hyphens (-), underscores (_), and colons (:). The first character must be an alphanumeric.

If you need a literal dollar sign that cannot trigger a substitution, you can either use the ${Dollar} substitution or the sequence ${}.

The following expansions are available:

DEB_HOST_*, DEB_BUILD_*, DEB_TARGET_* Expands to the relevant dpkg-architecture(1) value (similar to dpkg-architecture -qVARIABLE_HERE).

When in doubt, the DEB_HOST_* variant is the one that will work both for native and cross builds.

For performance reasons, debhelper will attempt to resolve these names from the environment first before consulting dpkg-architecture(1). This is mostly mentioned for completeness as it will not matter for most cases.

Dollar Expands to a single literal $-symbol. This symbol will never be considered part of a substitution variable. That is:

# Triggers an error ${NO_SUCH_TOKEN} # Expands to the literal value "${NO_SUCH_TOKEN}" ${Dollar}{NO_SUCH_TOKEN}

This variable equivalent to the sequence ${} and the two can be used interchangeably.

Newline, Space, Tab Expands to a single ASCII newline, space and tab respectively.

This can be useful if you need to include a literal whitespace character (e.g. space) where it would otherwise be stripped or used as a separator.

env:NAME Expands to the environment variable NAME. The environment variable must be set (but can be set to the empty string).

Note that all variables must expand to a defined value. As an example, if debhelper sees ${env:FOO}, then it will insist that the environment variable FOO is set (it can be set to the empty string).

Substitution limits

To avoid infinite loops and resource exhaustion, debhelper will stop with an error if the text contains many substitution variables (50) or they expand beyond a certain size (4096 characters or 3x length of the original input - whichever is bigger).

Executable debhelper config files If you need additional flexibility, many of the debhelper tools (e.g. dh_install(1)) support executing a config file as a script.

To use this feature, simply mark the config file as executable (e.g. chmod +x debian/package.install) and the tool will attempt to execute it and use the output of the script. In many cases, you can use dh-exec(1) as interpreter of the config file to retain most of the original syntax while getting the additional flexibility you need.

When using executable debhelper config files, please be aware of the following:

• The executable config file must exit with success (i.e. its return code should indicate success).

• In compatibility level 13+, the output will be subject to substitutions (see "Substitutions in debhelper config files") where the tool support these. Remember to be careful if your generator also provides substitutions as this can cause unnecessary confusion.

Otherwise, the output will be used exactly as-is. Notably, debhelper will not expand wildcards or strip comments or strip whitespace in the output.

If you need the package to build on a file system where you cannot disable the executable bit, then you can use dh-exec(1) and its strip-output script.