Multiple binary package support
If your source package generates more than one binary package,
debhelper programs will default to acting on all binary packages
when run. If your source package happens to generate one
architecture dependent package, and another architecture
independent package, this is not the correct behavior, because
you need to generate the architecture dependent packages in the
binary-arch debian/rules target, and the architecture independent
packages in the binary-indep debian/rules target.
To facilitate this, as well as give you more control over which
packages are acted on by debhelper programs, all debhelper
programs accept the -a, -i, -p, and -s parameters. These
parameters are cumulative. If none are given, debhelper programs
default to acting on all packages listed in the control file,
with the exceptions below.
First, any package whose Architecture field in debian/control
does not match the DEB_HOST_ARCH architecture will be excluded
("Debian Policy, section 5.6.8").
Also, some additional packages may be excluded based on the
contents of the DEB_BUILD_PROFILES environment variable and
Build-Profiles fields in binary package stanzas in
debian/control, according to the draft policy at
<https://wiki.debian.org/BuildProfileSpec>.
Interaction between package selections and Build-Profiles
Build-Profiles affect which packages are included in the package
selections mechanisms in debhelper. Generally, the package
selections are described from the assumption that all packages
are enabled. This section describes how the selections react
when a package is disabled due to the active Build-Profiles (or
lack of active Build-Profiles).
-a/--arch, -i/--indep OR no selection options (a raw "dh_X" call)
The package disabled by Build-Profiles is silently excluded
from the selection.
Note you will receive a warning if all packages related to
these selections are disabled. In that case, it generally
does not make sense to do the build in the first place.
-N package / --no-package package
The option is accepted and effectively does nothing.
-p package / --package package
The option is accepted, but debhelper will not act on the
package.
Note that it does not matter whether a package is enabled or
disabled by default.
Automatic generation of Debian install scripts
Some debhelper commands will automatically generate parts of
Debian maintainer scripts. If you want these automatically
generated things included in your existing Debian maintainer
scripts, then you need to add #DEBHELPER# to your scripts, in the
place the code should be added. #DEBHELPER# will be replaced by
any auto-generated code when you run dh_installdeb.
If a script does not exist at all and debhelper needs to add
something to it, then debhelper will create the complete script.
All debhelper commands that automatically generate code in this
way let it be disabled by the -n parameter (see above).
Note that the inserted code will be shell code, so you cannot
directly use it in a Perl script. If you would like to embed it
into a Perl script, here is one way to do that (note that I made
sure that $1, $2, etc are set with the set command):
my $temp="set -e\nset -- @ARGV\n" . << 'EOF';
#DEBHELPER#
EOF
if (system($temp)) {
my $exit_code = ($? >> 8) & 0xff;
my $signal = $? & 0x7f;
if ($exit_code) {
die("The debhelper script failed with error code: ${exit_code}");
} else {
die("The debhelper script was killed by signal: ${signal}");
}
}
Automatic generation of miscellaneous dependencies.
Some debhelper commands may make the generated package need to
depend on some other packages. For example, if you use
dh_installdebconf(1), your package will generally need to depend
on debconf. Or if you use dh_installxfonts(1), your package will
generally need to depend on a particular version of xutils.
Keeping track of these miscellaneous dependencies can be annoying
since they are dependent on how debhelper does things, so
debhelper offers a way to automate it.
All commands of this type, besides documenting what dependencies
may be needed on their man pages, will automatically generate a
substvar called ${misc:Depends}. If you put that token into your
debian/control file, it will be expanded to the dependencies
debhelper figures you need.
This is entirely independent of the standard ${shlibs:Depends}
generated by dh_makeshlibs(1), and the ${perl:Depends} generated
by dh_perl(1). You can choose not to use any of these, if
debhelper's guesses don't match reality.
Package build directories
By default, all debhelper programs assume that the temporary
directory used for assembling the tree of files in a package is
debian/package.
Sometimes, you might want to use some other temporary directory.
This is supported by the -P flag. For example, "dh_installdocs
-Pdebian/tmp", will use debian/tmp as the temporary directory.
Note that if you use -P, the debhelper programs can only be
acting on a single package at a time. So if you have a package
that builds many binary packages, you will need to also use the
-p flag to specify which binary package the debhelper program
will act on.
udebs
Debhelper includes support for udebs. To create a udeb with
debhelper, add "Package-Type: udeb" to the package's stanza in
debian/control. Debhelper will try to create udebs that comply
with debian-installer policy, by making the generated package
files end in .udeb, not installing any documentation into a udeb,
skipping over preinst, postrm, prerm, and config scripts, etc.
