programs in debhelper use pairs of files and destinations or slightly more
complicated formats.
-Note that if a package is the first (or only) binary package listed in
-F<debian/control>, debhelper will use F<debian/foo> if no F<debian/package.foo>
-file can be found.
+Note for the first (or only) binary package listed in
+F<debian/control>, debhelper will use F<debian/foo> when there's no
+F<debian/package.foo> file.
In some rare cases, you may want to have different versions of these files
for different architectures or OSes. If files named debian/I<package>.foo.I<ARCH>
"B<dpkg-architecture -qDEB_HOST_ARCH_OS>",
then they will be used in preference to other, more general files.
-In many cases, these config files are used to specify various types of
+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 (B<?> and B<*> and B<[>I<..>B<]> character classes) in the files.
-
You can also put comments in these files; lines beginning with B<#> are
ignored.
+The syntax of these files is intentionally kept very simple to make them
+easy to read, understand, and modify. If you prefer power and complexity,
+you can make the file executable, and write a program that outputs
+whatever content is appropriate for a given situation. When you do so,
+the output is not further processed to expand wildcards or strip comments.
+
=head1 SHARED DEBHELPER OPTIONS
The following command line options are supported by all debhelper programs.
=head1 BUILD SYSTEM OPTIONS
-All of the B<dh_auto_>I<*> debhelper programs set environment variables
-listed by B<dpkg-buildflags>, unless they are already set. They
-support DEB_BUILD_OPTIONS=noopt too.
-
The following command line options are supported by all of the B<dh_auto_>I<*>
debhelper programs. These programs support a variety of build systems,
and normally heuristically determine which to use, and how to use them.
You can use these command line options to override the default behavior.
+Typically these are passed to L<dh(1)>, which then passes them to all the
+B<dh_auto_>I<*> programs.
=over 4
=back
-=head1 COMPATABILITY LEVELS
+=head1 COMPATIBILITY LEVELS
From time to time, major non-backwards-compatible changes need to be made
to debhelper, to keep it clean and well-designed as needs change and its
it modifies its behavior in various ways.
Tell debhelper what compatibility level to use by writing a number to
-F<debian/compat>. For example, to turn on v8 mode:
+F<debian/compat>. For example, to turn on v9 mode:
+
+ % echo 9 > debian/compat
+
+Your package will also need a versioned build dependency on a version of
+debhelper equal to (or greater than) the compatibility level your package
+uses. So for compatibility level 9, ensure debian/control has:
- % echo 8 > debian/compat
+ Build-Depends: debhelper (>= 9)
Unless otherwise indicated, all debhelper documentation assumes that you
are using the most recent compatibility level, and in most cases does not
=item v8
-This is the recommended mode of operation.
-
Changes from v7 are:
=over 8
=item v9
-This compatibility level is still open for development; use with caution.
+This is the recommended mode of operation.
Changes from v8 are:
=item -
-dh allows defining custom build, build-arch, and build-indep targets
-in debian/rules, without needing to manually define the other targets
-that depend on them.
+dh is aware of the usual dependencies between targets in debian/rules.
+So, "dh binary" will run any build, build-arch, build-indep, install,
+etc targets that exist in the rules file. There's no need to define an
+explicit binary target with explicit dependencies on the other targets.
+
+=item -
+
+B<dh_strip> compresses debugging symbol files to reduce the installed
+size of -dbg packages.
=item -
B<dh> does not default to enabling --with=python-support
+=item -
+
+All of the B<dh_auto_>I<*> debhelper programs and B<dh> set
+environment variables listed by B<dpkg-buildflags>, unless
+they are already set.
+
+=item -
+
+B<dh_auto_configure> passes B<dpkg-buildflags> CFLAGS, CPPFLAGS, and
+LDFLAGS to perl F<Makefile.PL> and F<Build.PL>
+
+=item -
+
+B<dh_strip> puts separated debug symbols in a location based on their
+build-id.
+
+=item -
+
+Executable debhelper config files are run and their output used as the
+configuration.
+
+=back
+
+=item v10
+
+This compatibility level is still open for development; use with caution.
+
+Changes from v9 are:
+
+=over 8
+
+=item -
+
+None yet..
+
=back
=back
=head2 udebs
Debhelper includes support for udebs. To create a udeb with debhelper,
-add "B<Package-Type: udeb>" to the package's stanza in F<debian/control>, and
-build-depend on debhelper (>= 4.2). Debhelper will try to create udebs that
-comply with debian-installer policy, by making the generated package files
-end in F<.udeb>, not installing any documentation into a udeb, skipping over
+add "B<Package-Type: udeb>" to the package's stanza in F<debian/control>.
+Debhelper will try to create udebs that comply with debian-installer
+policy, by making the generated package files end in F<.udeb>, not
+installing any documentation into a udeb, skipping over
F<preinst>, F<postrm>, F<prerm>, and F<config> scripts, etc.
-=head2 Build depends
-
-Once your package uses debhelper to build, be sure to add
-debhelper to your Build-Depends line in F<debian/control>. You should
-build-depend on a version of debhelper equal to (or greater than) the
-debhelper compatibility level your package uses. So if your package used
-compatibility level 7:
-
- Build-Depends: debhelper (>= 7)
-
=head1 ENVIRONMENT
=over 4
=item B<DH_OPTIONS>
Anything in this variable will be prepended to the command line arguments
-of all debhelper commands. Command-specific options will be ignored by
-commands that do not support them.
+of all debhelper commands.
-This is useful in some situations, for example, if you need to pass B<-p> to
-all debhelper commands that will be run. One good way to set B<DH_OPTIONS> is
-by using "Target-specific Variable Values" in your F<debian/rules> file. See
-the make documentation for details on doing this.
+When using L<dh(1)>, it can be passed options that will be passed on to each
+debhelper command, which is generally better than using DH_OPTIONS.
=item B<DH_ALWAYS_EXCLUDE>
projects / debhelper.git / blobdiff