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.
[1menv: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.
