1980 lines
69 KiB
HTML
1980 lines
69 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of debhelper</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>debhelper</H1>
|
|
Section: Debhelper (7)<BR>Updated: 2020-03-27<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
debhelper - the debhelper tool suite
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
<B>dh_</B><I>*</I> [<B>-v</B>] [<B>-a</B>] [<B>-i</B>] [<B>--no-act</B>] [<B>-p</B><I>package</I>] [<B>-N</B><I>package</I>] [<B>-P</B><I>tmpdir</I>]
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
Debhelper is used to help you build a Debian package. The philosophy behind
|
|
debhelper is to provide a collection of small, simple, and easily
|
|
understood tools that are used in <I>debian/rules</I> to automate various common
|
|
aspects of building a package. This means less work for you, the packager.
|
|
It also, to some degree means that these tools can be changed if Debian
|
|
policy changes, and packages that use them will require only a rebuild to
|
|
comply with the new policy.
|
|
<P>
|
|
|
|
A typical <I>debian/rules</I> file that uses debhelper will call several debhelper
|
|
commands in sequence, or use <B><A HREF="/cgi-bin/man/man2html?1+dh">dh</A></B>(1) to automate this process. Examples of
|
|
rules files that use debhelper are in <I>/usr/share/doc/debhelper/examples/</I>
|
|
<P>
|
|
|
|
To create a new Debian package using debhelper, you can just copy one of
|
|
the sample rules files and edit it by hand. Or you can try the <B>dh-make</B>
|
|
package, which contains a dh_make command that partially
|
|
automates the process. For a more gentle introduction, the <B>maint-guide</B> Debian
|
|
package contains a tutorial about making your first package using debhelper.
|
|
<P>
|
|
|
|
Except where tool explicitly denotes otherwise, all of the debhelper
|
|
tools assumes that they run from root directory of an unpacked source
|
|
package. This is so they can locate find files like <I>debian/control</I>
|
|
when needed.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>DEBHELPER COMMANDS</H2>
|
|
|
|
|
|
|
|
Here is the list of debhelper commands you can use. See their man
|
|
pages for additional documentation.
|
|
<DL COMPACT>
|
|
<DT id="1"><B><A HREF="/cgi-bin/man/man2html?1+dh_auto_build">dh_auto_build</A></B>(1)<DD>
|
|
|
|
|
|
automatically builds a package
|
|
<DT id="2"><B><A HREF="/cgi-bin/man/man2html?1+dh_auto_clean">dh_auto_clean</A></B>(1)<DD>
|
|
|
|
|
|
automatically cleans up after a build
|
|
<DT id="3"><B><A HREF="/cgi-bin/man/man2html?1+dh_auto_configure">dh_auto_configure</A></B>(1)<DD>
|
|
|
|
|
|
automatically configure a package prior to building
|
|
<DT id="4"><B><A HREF="/cgi-bin/man/man2html?1+dh_auto_install">dh_auto_install</A></B>(1)<DD>
|
|
|
|
|
|
automatically runs make install or similar
|
|
<DT id="5"><B><A HREF="/cgi-bin/man/man2html?1+dh_auto_test">dh_auto_test</A></B>(1)<DD>
|
|
|
|
|
|
automatically runs a package's test suites
|
|
<DT id="6"><B><A HREF="/cgi-bin/man/man2html?1+dh_bugfiles">dh_bugfiles</A></B>(1)<DD>
|
|
|
|
|
|
install bug reporting customization files into package build directories
|
|
<DT id="7"><B><A HREF="/cgi-bin/man/man2html?1+dh_builddeb">dh_builddeb</A></B>(1)<DD>
|
|
|
|
|
|
build Debian binary packages
|
|
<DT id="8"><B><A HREF="/cgi-bin/man/man2html?1+dh_clean">dh_clean</A></B>(1)<DD>
|
|
|
|
|
|
clean up package build directories
|
|
<DT id="9"><B><A HREF="/cgi-bin/man/man2html?1+dh_compress">dh_compress</A></B>(1)<DD>
|
|
|
|
|
|
compress files and fix symlinks in package build directories
|
|
<DT id="10"><B><A HREF="/cgi-bin/man/man2html?1+dh_dwz">dh_dwz</A></B>(1)<DD>
|
|
|
|
|
|
optimize <FONT SIZE="-1">DWARF</FONT> debug information in <FONT SIZE="-1">ELF</FONT> binaries via dwz
|
|
<DT id="11"><B><A HREF="/cgi-bin/man/man2html?1+dh_fixperms">dh_fixperms</A></B>(1)<DD>
|
|
|
|
|
|
fix permissions of files in package build directories
|
|
<DT id="12"><B><A HREF="/cgi-bin/man/man2html?1+dh_gencontrol">dh_gencontrol</A></B>(1)<DD>
|
|
|
|
|
|
generate and install control file
|
|
<DT id="13"><B><A HREF="/cgi-bin/man/man2html?1+dh_icons">dh_icons</A></B>(1)<DD>
|
|
|
|
|
|
Update caches of Freedesktop icons
|
|
<DT id="14"><B><A HREF="/cgi-bin/man/man2html?1+dh_install">dh_install</A></B>(1)<DD>
|
|
|
|
|
|
install files into package build directories
|
|
<DT id="15"><B><A HREF="/cgi-bin/man/man2html?1+dh_installcatalogs">dh_installcatalogs</A></B>(1)<DD>
|
|
|
|
|
|
install and register <FONT SIZE="-1">SGML</FONT> Catalogs
|
|
<DT id="16"><B><A HREF="/cgi-bin/man/man2html?1+dh_installchangelogs">dh_installchangelogs</A></B>(1)<DD>
|
|
|
|
|
|
install changelogs into package build directories
|
|
<DT id="17"><B><A HREF="/cgi-bin/man/man2html?1+dh_installcron">dh_installcron</A></B>(1)<DD>
|
|
|
|
|
|
install cron scripts into etc/cron.*
|
|
<DT id="18"><B><A HREF="/cgi-bin/man/man2html?1+dh_installdeb">dh_installdeb</A></B>(1)<DD>
|
|
|
|
|
|
install files into the <FONT SIZE="-1">DEBIAN</FONT> directory
|
|
<DT id="19"><B><A HREF="/cgi-bin/man/man2html?1+dh_installdebconf">dh_installdebconf</A></B>(1)<DD>
|
|
|
|
|
|
install files used by debconf in package build directories
|
|
<DT id="20"><B><A HREF="/cgi-bin/man/man2html?1+dh_installdirs">dh_installdirs</A></B>(1)<DD>
|
|
|
|
|
|
create subdirectories in package build directories
|
|
<DT id="21"><B><A HREF="/cgi-bin/man/man2html?1+dh_installdocs">dh_installdocs</A></B>(1)<DD>
|
|
|
|
|
|
install documentation into package build directories
|
|
<DT id="22"><B><A HREF="/cgi-bin/man/man2html?1+dh_installemacsen">dh_installemacsen</A></B>(1)<DD>
|
|
|
|
|
|
register an Emacs add on package
|
|
<DT id="23"><B><A HREF="/cgi-bin/man/man2html?1+dh_installexamples">dh_installexamples</A></B>(1)<DD>
|
|
|
|
|
|
install example files into package build directories
|
|
<DT id="24"><B><A HREF="/cgi-bin/man/man2html?1+dh_installgsettings">dh_installgsettings</A></B>(1)<DD>
|
|
|
|
|
|
install GSettings overrides and set dependencies
|
|
<DT id="25"><B><A HREF="/cgi-bin/man/man2html?1+dh_installifupdown">dh_installifupdown</A></B>(1)<DD>
|
|
|
|
|
|
install if-up and if-down hooks
|
|
<DT id="26"><B><A HREF="/cgi-bin/man/man2html?1+dh_installinfo">dh_installinfo</A></B>(1)<DD>
|
|
|
|
|
|
install info files
|
|
<DT id="27"><B><A HREF="/cgi-bin/man/man2html?1+dh_installinit">dh_installinit</A></B>(1)<DD>
|
|
|
|
|
|
install service init files into package build directories
|
|
<DT id="28"><B><A HREF="/cgi-bin/man/man2html?1+dh_installinitramfs">dh_installinitramfs</A></B>(1)<DD>
|
|
|
|
|
|
install initramfs hooks and setup maintscripts
|
|
<DT id="29"><B><A HREF="/cgi-bin/man/man2html?1+dh_installlogcheck">dh_installlogcheck</A></B>(1)<DD>
|
|
|
|
|
|
install logcheck rulefiles into etc/logcheck/
|
|
<DT id="30"><B><A HREF="/cgi-bin/man/man2html?1+dh_installlogrotate">dh_installlogrotate</A></B>(1)<DD>
|
|
|
|
|
|
install logrotate config files
|
|
<DT id="31"><B><A HREF="/cgi-bin/man/man2html?1+dh_installman">dh_installman</A></B>(1)<DD>
|
|
|
|
|
|
install man pages into package build directories
|
|
<DT id="32"><B><A HREF="/cgi-bin/man/man2html?1+dh_installmenu">dh_installmenu</A></B>(1)<DD>
|
|
|
|
|
|
install Debian menu files into package build directories
|
|
<DT id="33"><B><A HREF="/cgi-bin/man/man2html?1+dh_installmime">dh_installmime</A></B>(1)<DD>
|
|
|
|
|
|
install mime files into package build directories
|
|
<DT id="34"><B><A HREF="/cgi-bin/man/man2html?1+dh_installmodules">dh_installmodules</A></B>(1)<DD>
|
|
|
|
|
|
register kernel modules
|
|
<DT id="35"><B><A HREF="/cgi-bin/man/man2html?1+dh_installpam">dh_installpam</A></B>(1)<DD>
|
|
|
|
|
|
install pam support files
|
|
<DT id="36"><B><A HREF="/cgi-bin/man/man2html?1+dh_installppp">dh_installppp</A></B>(1)<DD>
|
|
|
|
|
|
install ppp ip-up and ip-down files
|
|
<DT id="37"><B><A HREF="/cgi-bin/man/man2html?1+dh_installsystemd">dh_installsystemd</A></B>(1)<DD>
|
|
|
|
|
|
install systemd unit files
|
|
<DT id="38"><B><A HREF="/cgi-bin/man/man2html?1+dh_installsystemduser">dh_installsystemduser</A></B>(1)<DD>
|
|
|
|
|
|
install systemd unit files
|
|
<DT id="39"><B><A HREF="/cgi-bin/man/man2html?1+dh_installtmpfiles">dh_installtmpfiles</A></B>(1)<DD>
|
|
|
|
|
|
install tmpfiles.d configuration files
|
|
<DT id="40"><B><A HREF="/cgi-bin/man/man2html?1+dh_installudev">dh_installudev</A></B>(1)<DD>
|
|
|
|
|
|
install udev rules files
|
|
<DT id="41"><B><A HREF="/cgi-bin/man/man2html?1+dh_installwm">dh_installwm</A></B>(1)<DD>
|
|
|
|
|
|
register a window manager
|
|
<DT id="42"><B><A HREF="/cgi-bin/man/man2html?1+dh_installxfonts">dh_installxfonts</A></B>(1)<DD>
|
|
|
|
|
|
register X fonts
|
|
<DT id="43"><B><A HREF="/cgi-bin/man/man2html?1+dh_link">dh_link</A></B>(1)<DD>
|
|
|
|
|
|
create symlinks in package build directories
|
|
<DT id="44"><B><A HREF="/cgi-bin/man/man2html?1+dh_lintian">dh_lintian</A></B>(1)<DD>
|
|
|
|
|
|
install lintian override files into package build directories
|
|
<DT id="45"><B><A HREF="/cgi-bin/man/man2html?1+dh_listpackages">dh_listpackages</A></B>(1)<DD>
|
|
|
|
|
|
list binary packages debhelper will act on
|
|
<DT id="46"><B><A HREF="/cgi-bin/man/man2html?1+dh_makeshlibs">dh_makeshlibs</A></B>(1)<DD>
|
|
|
|
|
|
automatically create shlibs file and call dpkg-gensymbols
|
|
<DT id="47"><B><A HREF="/cgi-bin/man/man2html?1+dh_md5sums">dh_md5sums</A></B>(1)<DD>
|
|
|
|
|
|
generate DEBIAN/md5sums file
|
|
<DT id="48"><B><A HREF="/cgi-bin/man/man2html?1+dh_missing">dh_missing</A></B>(1)<DD>
|
|
|
|
|
|
check for missing files
|
|
<DT id="49"><B><A HREF="/cgi-bin/man/man2html?1+dh_movefiles">dh_movefiles</A></B>(1)<DD>
|
|
|
|
|
|
move files out of debian/tmp into subpackages
|
|
<DT id="50"><B><A HREF="/cgi-bin/man/man2html?1+dh_perl">dh_perl</A></B>(1)<DD>
|
|
|
|
|
|
calculates Perl dependencies and cleans up after MakeMaker
|
|
<DT id="51"><B><A HREF="/cgi-bin/man/man2html?1+dh_prep">dh_prep</A></B>(1)<DD>
|
|
|
|
|
|
perform cleanups in preparation for building a binary package
|
|
<DT id="52"><B><A HREF="/cgi-bin/man/man2html?1+dh_shlibdeps">dh_shlibdeps</A></B>(1)<DD>
|
|
|
|
|
|
calculate shared library dependencies
|
|
<DT id="53"><B><A HREF="/cgi-bin/man/man2html?1+dh_strip">dh_strip</A></B>(1)<DD>
|
|
|
|
|
|
strip executables, shared libraries, and some static libraries
|
|
<DT id="54"><B><A HREF="/cgi-bin/man/man2html?1+dh_systemd_enable">dh_systemd_enable</A></B>(1)<DD>
|
|
|
|
|
|
enable/disable systemd unit files
|
|
<DT id="55"><B><A HREF="/cgi-bin/man/man2html?1+dh_systemd_start">dh_systemd_start</A></B>(1)<DD>
|
|
|
|
|
|
start/stop/restart systemd unit files
|
|
<DT id="56"><B><A HREF="/cgi-bin/man/man2html?1+dh_testdir">dh_testdir</A></B>(1)<DD>
|
|
|
|
|
|
test directory before building Debian package
|
|
<DT id="57"><B><A HREF="/cgi-bin/man/man2html?1+dh_testroot">dh_testroot</A></B>(1)<DD>
|
|
|
|
|
|
ensure that a package is built with necessary level of root permissions
|
|
<DT id="58"><B><A HREF="/cgi-bin/man/man2html?1+dh_ucf">dh_ucf</A></B>(1)<DD>
|
|
|
|
|
|
register configuration files with ucf
|
|
<DT id="59"><B><A HREF="/cgi-bin/man/man2html?1+dh_update_autotools_config">dh_update_autotools_config</A></B>(1)<DD>
|
|
|
|
|
|
Update autotools config files
|
|
<DT id="60"><B><A HREF="/cgi-bin/man/man2html?1+dh_usrlocal">dh_usrlocal</A></B>(1)<DD>
|
|
|
|
|
|
migrate usr/local directories to maintainer scripts
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H3>Deprecated Commands</H3>
|
|
|
|
|
|
|
|
A few debhelper commands are deprecated and should not be used.
|
|
<DL COMPACT>
|
|
<DT id="61"><B><A HREF="/cgi-bin/man/man2html?1+dh_gconf">dh_gconf</A></B>(1)<DD>
|
|
|
|
|
|
install GConf defaults files and register schemas (deprecated)
|
|
<DT id="62"><B><A HREF="/cgi-bin/man/man2html?1+dh_installmanpages">dh_installmanpages</A></B>(1)<DD>
|
|
|
|
|
|
old-style man page installer (deprecated)
|
|
</DL>
|
|
<A NAME="lbAG"> </A>
|
|
<H3>Other Commands</H3>
|
|
|
|
|
|
|
|
If a program's name starts with <B>dh_</B>, and the program is not on the above
|
|
lists, then it is not part of the debhelper package, but it should still
|
|
work like the other programs described on this page.
|
|
<A NAME="lbAH"> </A>
|
|
<H2>DEBHELPER CONFIG FILES</H2>
|
|
|
|
|
|
|
|
Many debhelper commands make use of files in <I>debian/</I> to control what they
|
|
do. Besides the common <I>debian/changelog</I> and <I>debian/control</I>, 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/<I>package</I>.foo (where <I>package</I> of course,
|
|
is replaced with the package that is being acted on).
|
|
<P>
|
|
|
|
For example, <B>dh_installdocs</B> uses files named <I>debian/package.docs</I> 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.
|
|
<P>
|
|
|
|
Note for the first (or only) binary package listed in
|
|
<I>debian/control</I>, debhelper will use <I>debian/foo</I> when there's no
|
|
<I>debian/package.foo</I> file. However, it is often a good idea to keep
|
|
the <I>package.</I> 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
|
|
<I>debian/copyright</I> or <I>debian/changelog</I>).
|
|
<P>
|
|
|
|
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</I>.foo.<I></I><FONT SIZE="-1"><I>ARCH</I></FONT><I></I>
|
|
or debian/<I>package</I>.foo.<I></I><FONT SIZE="-1"><I>OS</I></FONT><I></I> exist, where <I></I><FONT SIZE="-1"><I>ARCH</I></FONT><I></I> and <I></I><FONT SIZE="-1"><I>OS</I></FONT><I></I> are the same as the
|
|
output of "<B>dpkg-architecture -qDEB_HOST_ARCH</B>`` /
|
|
''<B>dpkg-architecture -qDEB_HOST_ARCH_OS</B>",
|
|
then they will be used in preference to other, more general files.
|
|
<P>
|
|
|
|
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>?</B> and <B>*</B> and <B>[</B><I>..</I><B>]</B> character classes) in the files.
|
|
You can also put comments in these files; lines beginning with <B>#</B> are
|
|
ignored.
|
|
<P>
|
|
|
|
The syntax of these files is intentionally kept very simple to make them
|
|
easy to read, understand, and modify.
|
|
<A NAME="lbAI"> </A>
|
|
<H3>Substitutions in debhelper config files</H3>
|
|
|
|
|
|
|
|
In compatibility level 13 and later, it is possible to use simple
|
|
substitutions in <I>some</I> debhelper config files (particularly,
|
|
the configuration files for <B><A HREF="/cgi-bin/man/man2html?1+dh_install">dh_install</A></B>(1)).
|
|
<P>
|
|
|
|
All substitution variables are of the form <I>${foo}</I> 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.
|
|
<P>
|
|
|
|
If you need a literal dollar sign that cannot trigger a substitution,
|
|
you can either use the <B>${Dollar}</B> substitution or the sequence <B>${}</B>.
|
|
<P>
|
|
|
|
The following expansions are available:
|
|
<DL COMPACT>
|
|
<DT id="63"><B>DEB_HOST_*</B>, <B>DEB_BUILD_*</B>, <B>DEB_TARGET_*</B><DD>
|
|
|
|
|
|
Expands to the relevant <B><A HREF="/cgi-bin/man/man2html?1+dpkg-architecture">dpkg-architecture</A></B>(1) value (similar to
|
|
<I>dpkg-architecture -qVARIABLE_HERE</I>).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
When in doubt, the <B>DEB_HOST_*</B> variant is the one that will work both
|
|
for native and cross builds.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
For performance reasons, debhelper will attempt to resolve these
|
|
names from the environment first before consulting
|
|
<B><A HREF="/cgi-bin/man/man2html?1+dpkg-architecture">dpkg-architecture</A></B>(1). This is mostly mentioned for completeness
|
|
as it will not matter for most cases.
|
|
<DT id="64"><B>Dollar</B><DD>
|
|
|
|
|
|
Expands to a single literal <B>$</B>-symbol. This symbol will <I>never</I>
|
|
be considered part of a substitution variable. That is:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
# Triggers an error
|
|
${NO_SUCH_TOKEN}
|
|
# Expands to the literal value "${NO_SUCH_TOKEN}"
|
|
${Dollar}{NO_SUCH_TOKEN}
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This variable equivalent to the sequence <B>${}</B> and the two can be
|
|
used interchangeably.
|
|
<DT id="65"><B>Newline</B>, <B>Space</B>, <B>Tab</B><DD>
|
|
|
|
|
|
Expands to a single <FONT SIZE="-1">ASCII</FONT> newline, space and tab respectively.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
<DT id="66"><B>env:</B><FONT SIZE="-1">NAME</FONT><B></B><DD>
|
|
|
|
|
|
Expands to the environment variable <I></I><FONT SIZE="-1"><I>NAME</I></FONT><I></I>. The environment
|
|
variable must be set (but can be set to the empty string).
|
|
</DL>
|
|
<P>
|
|
|
|
Note that all variables must expand to a defined value. As an example,
|
|
if debhelper sees <I>${env:FOO}</I>, then it will insist that the environment
|
|
variable <I></I><FONT SIZE="-1"><I>FOO</I></FONT><I></I> is set (it can be set to the empty string).
|
|
<P>
|
|
|
|
<I>Substitution limits</I>
|
|
|
|
|
|
<P>
|
|
|
|
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).
|
|
<A NAME="lbAJ"> </A>
|
|
<H3>Executable debhelper config files</H3>
|
|
|
|
|
|
|
|
If you need additional flexibility, many of the debhelper tools
|
|
(e.g. <B><A HREF="/cgi-bin/man/man2html?1+dh_install">dh_install</A></B>(1)) support executing a config file as a script.
|
|
<P>
|
|
|
|
To use this feature, simply mark the config file as executable
|
|
(e.g. <B>chmod +x debian/</B>package<B>.install</B>) and the tool will
|
|
attempt to execute it and use the output of the script. In many
|
|
cases, you can use <B><A HREF="/cgi-bin/man/man2html?1+dh-exec">dh-exec</A></B>(1) as interpreter of the config file to
|
|
retain most of the original syntax while getting the additional
|
|
flexibility you need.
|
|
<P>
|
|
|
|
When using executable debhelper config files, please be aware of the
|
|
following:
|
|
<DL COMPACT>
|
|
<DT id="67">•<DD>
|
|
The executable config file <B>must</B> exit with success (i.e. its return
|
|
code should indicate success).
|
|
<DT id="68">•<DD>
|
|
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 <I>also</I> provides
|
|
substitutions as this can cause unnecessary confusion.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Otherwise, the output will be used exactly as-is. Notably, debhelper
|
|
will <I>not</I> expand wildcards or strip comments or strip whitespace
|
|
in the output.
|
|
</DL>
|
|
<P>
|
|
|
|
If you need the package to build on a file system where you cannot
|
|
disable the executable bit, then you can use <B><A HREF="/cgi-bin/man/man2html?1+dh-exec">dh-exec</A></B>(1) and its
|
|
<B>strip-output</B> script.
|
|
<A NAME="lbAK"> </A>
|
|
<H2>SHARED DEBHELPER OPTIONS</H2>
|
|
|
|
|
|
|
|
The following command line options are supported by all debhelper programs.
|
|
<DL COMPACT>
|
|
<DT id="69"><B>-v</B>, <B>--verbose</B><DD>
|
|
|
|
|
|
Verbose mode: show all commands that modify the package build directory.
|
|
<DT id="70"><B>--no-act</B><DD>
|
|
|
|
|
|
Do not really do anything. If used with -v, the result is that the command
|
|
will output what it would have done.
|
|
<DT id="71"><B>-a</B>, <B>--arch</B><DD>
|
|
|
|
|
|
Act on architecture dependent packages that should be built for the
|
|
<B></B><FONT SIZE="-1"><B>DEB_HOST_ARCH</B></FONT><B></B> architecture.
|
|
<DT id="72"><B>-i</B>, <B>--indep</B><DD>
|
|
|
|
|
|
Act on all architecture independent packages.
|
|
<DT id="73"><B>-p</B><I>package</I>, <B>--package=</B><I>package</I><DD>
|
|
|
|
|
|
Act on the package named <I>package</I>. This option may be specified multiple
|
|
times to make debhelper operate on a given set of packages.
|
|
<DT id="74"><B>-s</B>, <B>--same-arch</B><DD>
|
|
|
|
|
|
Deprecated alias of <B>-a</B>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This option is removed in compat 12.
|
|
<DT id="75"><B>-N</B><I>package</I>, <B>--no-package=</B><I>package</I><DD>
|
|
|
|
|
|
Do not act on the specified package even if an <B>-a</B>, <B>-i</B>, or <B>-p</B> option lists
|
|
the package as one that should be acted on.
|
|
<DT id="76"><B>--remaining-packages</B><DD>
|
|
|
|
|
|
Do not act on the packages which have already been acted on by this debhelper
|
|
command earlier (i.e. if the command is present in the package debhelper log).
|
|
For example, if you need to call the command with special options only for a
|
|
couple of binary packages, pass this option to the last call of the command to
|
|
process the rest of packages with default settings.
|
|
<DT id="77"><B>-P</B><I>tmpdir</I>, <B>--tmpdir=</B><I>tmpdir</I><DD>
|
|
|
|
|
|
Use <I>tmpdir</I> for package build directory. The default is debian/<I>package</I>
|
|
<DT id="78"><B>--mainpackage=</B><I>package</I><DD>
|
|
|
|
|
|
This little-used option changes the package which debhelper considers the
|
|
``main package'', that is, the first one listed in <I>debian/control</I>, and the
|
|
one for which <I>debian/foo</I> files can be used instead of the usual
|
|
<I>debian/package.foo</I> files.
|
|
<DT id="79"><B>-O=</B><I>option</I>|<I>bundle</I><DD>
|
|
|
|
|
|
This is used by <B><A HREF="/cgi-bin/man/man2html?1+dh">dh</A></B>(1) when passing user-specified options to all the
|
|
commands it runs. If the command supports the specified option or option
|
|
bundle, it will take effect. If the command does not support the option (or
|
|
any part of an option bundle), it will be ignored.
|
|
</DL>
|
|
<A NAME="lbAL"> </A>
|
|
<H2>COMMON DEBHELPER OPTIONS</H2>
|
|
|
|
|
|
|
|
The following command line options are supported by some debhelper programs.
|
|
See the man page of each program for a complete explanation of what each
|
|
option does.
|
|
<DL COMPACT>
|
|
<DT id="80"><B>-n</B><DD>
|
|
|
|
|
|
Do not modify <I>postinst</I>, <I>postrm</I>, etc. scripts.
|
|
<DT id="81"><B>-X</B><I>item</I>, <B>--exclude=</B><I>item</I><DD>
|
|
|
|
|
|
Exclude an item from processing. This option may be used multiple times,
|
|
to exclude more than one thing. The <I>item</I> is typically part of a
|
|
filename, and any file containing the specified text will be excluded.
|
|
<DT id="82"><B>-A</B>, <B>--all</B><DD>
|
|
|
|
|
|
Makes files or other items that are specified on the command line take effect
|
|
in <FONT SIZE="-1">ALL</FONT> packages acted on, not just the first.
|
|
</DL>
|
|
<A NAME="lbAM"> </A>
|
|
<H2>BUILD SYSTEM OPTIONS</H2>
|
|
|
|
|
|
|
|
The following command line options are supported by all of the <B>dh_auto_</B><I>*</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 <B><A HREF="/cgi-bin/man/man2html?1+dh">dh</A></B>(1), which then passes them to all the
|
|
<B>dh_auto_</B><I>*</I> programs.
|
|
<DL COMPACT>
|
|
<DT id="83"><B>-S</B><I>buildsystem</I>, <B>--buildsystem=</B><I>buildsystem</I><DD>
|
|
|
|
|
|
Force use of the specified <I>buildsystem</I>, instead of trying to auto-select
|
|
one which might be applicable for the package.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Pass <B>none</B> as <I>buildsystem</I> to disable auto-selection.
|
|
<DT id="84"><B>-D</B><I>directory</I>, <B>--sourcedir=</B><I>directory</I>, <B>--sourcedirectory=</B><I>directory</I><DD>
|
|
|
|
|
|
Assume that the original package source tree is at the specified
|
|
<I>directory</I> rather than the top level directory of the Debian
|
|
source package tree.
|
|
<DT id="85"><B>-B</B>[<I>directory</I>], <B>--builddir</B>[<I>=directory</I>], <B>--builddirectory</B>[<I>=directory</I>]<DD>
|
|
|
|
|
|
Enable out of source building and use the specified <I>directory</I> as the build
|
|
directory. If <I>directory</I> parameter is omitted, a default build directory
|
|
will be chosen.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If this option is not specified, building will be done in source by default
|
|
unless the build system requires or prefers out of source tree building.
|
|
In such a case, the default build directory will be used even if
|
|
<B>--builddirectory</B> is not specified.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If the build system prefers out of source tree building but still
|
|
allows in source building, the latter can be re-enabled by passing a build
|
|
directory path that is the same as the source directory path.
|
|
<DT id="86"><B>--parallel</B>, <B>--no-parallel</B><DD>
|
|
|
|
|
|
Control whether parallel builds should be used if underlying build
|
|
system supports them. The number of parallel jobs is controlled by
|
|
the <B></B><FONT SIZE="-1"><B>DEB_BUILD_OPTIONS</B></FONT><B></B> environment variable (``Debian Policy,
|
|
section 4.9.1'') at build time. It might also be subject to a build
|
|
system specific limit.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If neither option is specified, debhelper currently defaults to
|
|
<B>--parallel</B> in compat 10 (or later) and <B>--no-parallel</B> otherwise.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
As an optimization, <B>dh</B> will try to avoid passing these options to
|
|
subprocesses, if they are unnecessary and the only options passed.
|
|
Notably this happens when <B></B><FONT SIZE="-1"><B>DEB_BUILD_OPTIONS</B></FONT><B></B> does not have a
|
|
<I>parallel</I> parameter (or its value is 1).
|
|
<DT id="87"><B>--max-parallel=</B><I>maximum</I><DD>
|
|
|
|
|
|
This option implies <B>--parallel</B> and allows further limiting the number of
|
|
jobs that can be used in a parallel build. If the package build is known to
|
|
only work with certain levels of concurrency, you can set this to the maximum
|
|
level that is known to work, or that you wish to support.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Notably, setting the maximum to 1 is effectively the same as using
|
|
<B>--no-parallel</B>.
|
|
<DT id="88"><B>--reload-all-buildenv-variables</B><DD>
|
|
|
|
|
|
By default, <B><A HREF="/cgi-bin/man/man2html?1+dh">dh</A></B>(1) will compute several environment (e.g. by using
|
|
<B><A HREF="/cgi-bin/man/man2html?1+dpkg-buildflags">dpkg-buildflags</A></B>(1)) and cache them to avoid having all <B>dh_auto_*</B>
|
|
tool recompute them.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
When passing this option, the concrete <B>dh_auto_*</B> tool will ignore
|
|
the cache from <B><A HREF="/cgi-bin/man/man2html?1+dh">dh</A></B>(1) and retrigger a rebuild of these variables.
|
|
This is useful in the very rare case where the package need to do
|
|
multiple builds but with different <B>...FLAGS</B> options. A concrete
|
|
example would be needing to change the <B>-O</B> parameter in <B></B><FONT SIZE="-1"><B>CFLAGS</B></FONT><B></B> in
|
|
the second build:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
export DEB_CFLAGS_MAINT_APPEND=-O3
|
|
|
|
%:
|
|
dh $@
|
|
|
|
override_dh_auto_configure:
|
|
dh_auto_configure -Bbuild-deb ...
|
|
DEB_CFLAGS_MAINT_APPEND=-Os dh_auto_configure \
|
|
--reload-all-buildenv-variables -Bbuild-udeb ...
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Without <B>--reload-all-buildenv-variables</B> in the second call to
|
|
<B><A HREF="/cgi-bin/man/man2html?1+dh_auto_configure">dh_auto_configure</A></B>(1), the change in <B></B><FONT SIZE="-1"><B>DEB_CFLAGS_MAINT_APPEND</B></FONT><B></B>
|
|
would be ignored as <B><A HREF="/cgi-bin/man/man2html?1+dh_auto_configure">dh_auto_configure</A></B>(1) would use the cached value
|
|
of <B></B><FONT SIZE="-1"><B>CFLAGS</B></FONT><B></B> set by <B><A HREF="/cgi-bin/man/man2html?1+dh">dh</A></B>(1).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This option is only available with <B>debhelper (>= 12.7~)</B> when
|
|
the package uses compatibility level 9 or later.
|
|
<DT id="89"><B>--list</B>, <B>-l</B><DD>
|
|
|
|
|
|
List all build systems supported by debhelper on this system. The list
|
|
includes both default and third party build systems (marked as such). Also
|
|
shows which build system would be automatically selected, or which one
|
|
is manually specified with the <B>--buildsystem</B> option.
|
|
</DL>
|
|
<A NAME="lbAN"> </A>
|
|
<H2>COMPATIBILITY LEVELS</H2>
|
|
|
|
|
|
|
|
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
|
|
author gains more experience. To prevent such major changes from breaking
|
|
existing packages, the concept of debhelper compatibility levels was
|
|
introduced. You must tell debhelper which compatibility level it should use, and
|
|
it modifies its behavior in various ways.
|
|
<P>
|
|
|
|
In current debhelper, you can specify the compatibility level in
|
|
<I>debian/control</I> by adding a Build-Depends on the debhelper-compat package.
|
|
For example, to use v12 mode, ensure <I>debian/control</I> has:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
Build-Depends: debhelper-compat (= 12)
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
This also serves as an appropriate versioned build dependency on a sufficient
|
|
version of the debhelper package, so you do not need to specify a separate
|
|
versioned build dependency on the debhelper package unless you need a specific
|
|
point release of debhelper (such as for the introduction of a new feature or
|
|
bugfix within a compatibility level).
|
|
<P>
|
|
|
|
Note that debhelper does not provide debhelper-compat for experimental or beta
|
|
compatibility levels; packages experimenting with those compatibility levels
|
|
should use <I>debian/compat</I> or <B></B><FONT SIZE="-1"><B>DH_COMPAT</B></FONT><B></B>.
|
|
<P>
|
|
|
|
Prior versions of debhelper required specifying the compatibility level in the
|
|
file <I>debian/compat</I>, and current debhelper still supports this for backward
|
|
compatibility, though a package may not specify a compatibility level via
|
|
multiple methods at once. To use this method, <I>debian/compat</I> should contain
|
|
the compatibility level as a single number, and no other content. If you
|
|
specify the compatibility level by this method, your package will also need a
|
|
versioned build dependency on a version of the debhelper package equal to (or
|
|
greater than) the compatibility level your package uses. So, if you specify
|
|
compatibility level 12 in <I>debian/compat</I>, ensure
|
|
<I>debian/control</I> has:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
Build-Depends: debhelper (>= 12~)
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Unless otherwise indicated, all debhelper documentation assumes that you
|
|
are using the most recent compatibility level, and in most cases does not
|
|
indicate if the behavior is different in an earlier compatibility level, so
|
|
if you are not using the most recent compatibility level, you're advised to
|
|
read below for notes about what is different in earlier compatibility
|
|
levels.
|
|
<A NAME="lbAO"> </A>
|
|
<H3>Supported compatibility levels</H3>
|
|
|
|
|
|
|
|
These are the available compatibility levels:
|
|
<DL COMPACT>
|
|
<DT id="90">v5<DD>
|
|
|
|
|
|
This is the lowest supported compatibility level.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If you are upgrading from an earlier compatibility level, please
|
|
review <B><A HREF="/cgi-bin/man/man2html?7+debhelper-obsolete-compat">debhelper-obsolete-compat</A></B>(7).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This mode is deprecated.
|
|
<DT id="91">v6<DD>
|
|
|
|
|
|
Changes from v5 are:
|
|
<DL COMPACT><DT id="92"><DD>
|
|
<DL COMPACT>
|
|
<DT id="93">-<DD>
|
|
Commands that generate maintainer script fragments will order the
|
|
fragments in reverse order for the <I>prerm</I> and <I>postrm</I> scripts.
|
|
<DT id="94">-<DD>
|
|
<B>dh_installwm</B> will install a slave manpage link for <I>x-window-manager.1.gz</I>,
|
|
if it sees the man page in <I>usr/share/man/man1</I> in the package build
|
|
directory.
|
|
<DT id="95">-<DD>
|
|
<B>dh_builddeb</B> did not previously delete everything matching
|
|
<B></B><FONT SIZE="-1"><B>DH_ALWAYS_EXCLUDE</B></FONT><B></B>, if it was set to a list of things to exclude, such as
|
|
<B></B><FONT SIZE="-1"><B>CVS:</B></FONT><B>.svn:.git</B>. Now it does.
|
|
<DT id="96">-<DD>
|
|
<B>dh_installman</B> allows overwriting existing man pages in the package build
|
|
directory. In previous compatibility levels it silently refuses to do this.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="97"><DD>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This mode is deprecated.
|
|
</DL>
|
|
|
|
<DT id="98">v7<DD>
|
|
|
|
|
|
Changes from v6 are:
|
|
<DL COMPACT><DT id="99"><DD>
|
|
<DL COMPACT>
|
|
<DT id="100">-<DD>
|
|
<B>dh_install</B>, will fall back to looking for files in <I>debian/tmp</I> if it doesn't
|
|
find them in the current directory (or wherever you tell it look using
|
|
<B>--sourcedir</B>). This allows <B>dh_install</B> to interoperate with <B>dh_auto_install</B>,
|
|
which installs to <I>debian/tmp</I>, without needing any special parameters.
|
|
<DT id="101">-<DD>
|
|
<B>dh_clean</B> will read <I>debian/clean</I> and delete files listed there.
|
|
<DT id="102">-<DD>
|
|
<B>dh_clean</B> will delete toplevel <I>*-stamp</I> files.
|
|
<DT id="103">-<DD>
|
|
<B>dh_installchangelogs</B> will guess at what file is the upstream changelog if
|
|
none is specified.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="104"><DD>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This mode is deprecated.
|
|
</DL>
|
|
|
|
<DT id="105">v8<DD>
|
|
|
|
|
|
Changes from v7 are:
|
|
<DL COMPACT><DT id="106"><DD>
|
|
<DL COMPACT>
|
|
<DT id="107">-<DD>
|
|
Commands will fail rather than warning when they are passed unknown options.
|
|
<DT id="108">-<DD>
|
|
<B>dh_makeshlibs</B> will run <B>dpkg-gensymbols</B> on all shared libraries that it
|
|
generates shlibs files for. So <B>-X</B> can be used to exclude libraries.
|
|
Also, libraries in unusual locations that <B>dpkg-gensymbols</B> would not
|
|
have processed before will be passed to it, a behavior change that
|
|
can cause some packages to fail to build.
|
|
<DT id="109">-<DD>
|
|
<B>dh</B> requires the sequence to run be specified as the first parameter, and
|
|
any switches come after it. Ie, use "<B>dh $@ --foo</B>``, not ''<B>dh --foo $@</B>".
|
|
<DT id="110">-<DD>
|
|
<B>dh_auto_</B><I>*</I> prefer to use Perl's <B>Module::Build</B> in preference to <I>Makefile.PL</I>.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="111"><DD>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This mode is deprecated.
|
|
</DL>
|
|
|
|
<DT id="112">v9<DD>
|
|
|
|
|
|
Changes from v8 are:
|
|
<DL COMPACT><DT id="113"><DD>
|
|
<DL COMPACT>
|
|
<DT id="114">-<DD>
|
|
Multiarch support. In particular, <B>dh_auto_configure</B> passes
|
|
multiarch directories to autoconf in --libdir and --libexecdir.
|
|
<DT id="115">-<DD>
|
|
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.
|
|
<DT id="116">-<DD>
|
|
<B>dh_strip</B> compresses debugging symbol files to reduce the installed
|
|
size of -dbg packages.
|
|
<DT id="117">-<DD>
|
|
<B>dh_auto_configure</B> does not include the source package name
|
|
in --libexecdir when using autoconf.
|
|
<DT id="118">-<DD>
|
|
<B>dh</B> does not default to enabling --with=python-support
|
|
|
|
|
|
<P>
|
|
|
|
|
|
(Obsolete: As the <B>dh_pysupport</B> tool was removed from Debian
|
|
stretch. Since debhelper/10.3, <B>dh</B> no longer enables this sequence
|
|
add-on regardless of compat level)
|
|
<DT id="119">-<DD>
|
|
All of the <B>dh_auto_</B><I>*</I> debhelper programs and <B>dh</B> set
|
|
environment variables listed by <B>dpkg-buildflags</B>, unless
|
|
they are already set.
|
|
<DT id="120">-<DD>
|
|
<B>dh_auto_configure</B> passes <B>dpkg-buildflags</B> <FONT SIZE="-1">CFLAGS, CPPFLAGS,</FONT> and
|
|
<FONT SIZE="-1">LDFLAGS</FONT> to perl <I>Makefile.PL</I> and <I>Build.PL</I>
|
|
<DT id="121">-<DD>
|
|
<B>dh_strip</B> puts separated debug symbols in a location based on their
|
|
build-id.
|
|
<DT id="122">-<DD>
|
|
Executable debhelper config files are run and their output used as the
|
|
configuration.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="123"><DD>
|
|
</DL>
|
|
|
|
<DT id="124">v10<DD>
|
|
|
|
|
|
Changes from v9 are:
|
|
<DL COMPACT><DT id="125"><DD>
|
|
<DL COMPACT>
|
|
<DT id="126">-<DD>
|
|
<B>dh_installinit</B> will no longer install a file named debian/<I>package</I>
|
|
as an init script.
|
|
<DT id="127">-<DD>
|
|
<B>dh_installdocs</B> will error out if it detects links created with
|
|
--link-doc between packages of architecture ``all'' and non-``all'' as it
|
|
breaks binNMUs.
|
|
<DT id="128">-<DD>
|
|
<B>dh_installdeb</B> no longer installs a maintainer-provided
|
|
debian/<I>package</I>.shlibs file. This is now done by <B>dh_makeshlibs</B>
|
|
instead.
|
|
<DT id="129">-<DD>
|
|
<B>dh_installwm</B> refuses to create a broken package if no man page
|
|
can be found (required to register for the x-window-manager alternative).
|
|
<DT id="130">-<DD>
|
|
Debhelper will default to <B>--parallel</B> for all buildsystems that
|
|
support parallel building. This can be disabled by using either
|
|
<B>--no-parallel</B> or passing <B>--max-parallel</B> with a value of 1.
|
|
<DT id="131">-<DD>
|
|
The <B>dh</B> command will not accept any of the deprecated ``manual
|
|
sequence control'' parameters (<B>--before</B>, <B>--after</B>, etc.). Please
|
|
use override targets instead.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
<B>Retroactively applied to earlier compat levels</B>: <B>dh</B> no longer
|
|
accepts any of these since debhelper/12.4.
|
|
<DT id="132">-<DD>
|
|
The <B>dh</B> command will no longer use log files to track which commands
|
|
have been run. The <B>dh</B> command <I>still</I> keeps track of whether it
|
|
already ran the ``build'' sequence and skip it if it did.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The main effects of this are:
|
|
<DL COMPACT><DT id="133"><DD>
|
|
<DL COMPACT>
|
|
<DT id="134">-<DD>
|
|
With this, it is now easier to debug the <I>install</I> or/and <I>binary</I>
|
|
sequences because they can now trivially be re-run (without having to
|
|
do a full ``clean and rebuild'' cycle)
|
|
<DT id="135">-<DD>
|
|
The main caveat is that <B>dh_*</B> now only keeps track of what happened
|
|
in a single override target. When all the calls to a given <B>dh_cmd</B>
|
|
command happens in the same override target everything will work as
|
|
before.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Example of where it can go wrong:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
override_dh_foo:
|
|
dh_foo -pmy-pkg
|
|
|
|
override_dh_bar:
|
|
dh_bar
|
|
dh_foo --remaining
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
In this case, the call to <B>dh_foo --remaining</B> will <I>also</I> include
|
|
<I>my-pkg</I>, since <B>dh_foo -pmy-pkg</B> was run in a separate override
|
|
target. This issue is not limited to <B>--remaining</B>, but also includes
|
|
<B>-a</B>, <B>-i</B>, etc.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="136"><DD>
|
|
</DL>
|
|
|
|
<DT id="137">-<DD>
|
|
The <B>dh_installdeb</B> command now shell-escapes the lines in the
|
|
<I>maintscript</I> config file. This was the original intent but it did
|
|
not work properly and packages have begun to rely on the incomplete
|
|
shell escaping (e.g. quoting file names).
|
|
<DT id="138">-<DD>
|
|
The <B>dh_installinit</B> command now defaults to
|
|
<B>--restart-after-upgrade</B>. For packages needing the previous
|
|
behaviour, please use <B>--no-restart-after-upgrade</B>.
|
|
<DT id="139">-<DD>
|
|
The <B>autoreconf</B> sequence is now enabled by default. Please pass
|
|
<B>--without autoreconf</B> to <B>dh</B> if this is not desirable for a given
|
|
package
|
|
<DT id="140">-<DD>
|
|
The <B>systemd</B> sequence is now enabled by default. Please pass
|
|
<B>--without systemd</B> to <B>dh</B> if this is not desirable for a given
|
|
package.
|
|
<DT id="141">-<DD>
|
|
<B>Retroactively removed</B>: <B>dh</B> no longer creates the package build
|
|
directory when skipping running debhelper commands. This will not
|
|
affect packages that only build with debhelper commands, but it may
|
|
expose bugs in commands not included in debhelper.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This compatibility feature had a bug since its inception in
|
|
debhelper/9.20130516 that made it fail to apply in compat 9 and
|
|
earlier. As there has been no reports of issues caused by this bug in
|
|
those ~5 years, this item have been removed rather than fixed.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="142"><DD>
|
|
</DL>
|
|
|
|
<DT id="143">v11<DD>
|
|
|
|
|
|
This mode is discouraged.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The compat 11 is discouraged for new packages as it suffers from
|
|
feature interaction between dh_installinit and dh_installsystemd
|
|
causing services to not run correctly in some cases. Please consider
|
|
using compatibility mode 10 or 12 instead. More details about the
|
|
issue are available in Debian#887904 and
|
|
<<A HREF="https://lists.debian.org/debian-release/2019/04/msg01442.html">https://lists.debian.org/debian-release/2019/04/msg01442.html</A>>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Changes from v10 are:
|
|
<DL COMPACT><DT id="144"><DD>
|
|
<DL COMPACT>
|
|
<DT id="145">-<DD>
|
|
<B>dh_installinit</B> no longer installs <I>service</I> or <I>tmpfile</I> files,
|
|
nor generates maintainer scripts for those files. Please use the new
|
|
<B>dh_installsystemd</B> helper.
|
|
<DT id="146">-<DD>
|
|
The <B>dh_systemd_enable</B> and <B>dh_systemd_start</B> helpers have been
|
|
replaced by the new <B>dh_installsystemd</B> helper. For the same reason,
|
|
the <B>systemd</B> sequence for <B>dh</B> has also been removed. If you need
|
|
to disable the <B>dh_installsystemd</B> helper tool, please use an empty
|
|
override target.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Please note that the <B>dh_installsystemd</B> tool has a slightly
|
|
different behaviour in some cases (e.g. when using the <B>--name</B>
|
|
parameter).
|
|
<DT id="147">-<DD>
|
|
<B>dh_installdirs</B> no longer creates debian/<I>package</I> directories
|
|
unless explicitly requested (or it has to create a subdirectory in
|
|
it).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The vast majority of all packages will be unaffected by this change.
|
|
<DT id="148">-<DD>
|
|
The <B>makefile</B> buildsystem now passes <B>INSTALL=``install
|
|
--strip-program=true''</B> to <B><A HREF="/cgi-bin/man/man2html?1+make">make</A></B>(1). Derivative buildsystems
|
|
(e.g. <B>configure</B> or <B>cmake</B>) are unaffected by this change.
|
|
<DT id="149">-<DD>
|
|
The <B>autoconf</B> buildsystem now passes <B>--runstatedir=/run</B> to
|
|
<I>./configure</I>.
|
|
<DT id="150">-<DD>
|
|
The <B>cmake</B> buildsystem now passes
|
|
<B>-DCMAKE_INSTALL_RUNSTATEDIR=/run</B> to <B><A HREF="/cgi-bin/man/man2html?1+cmake">cmake</A></B>(1).
|
|
<DT id="151">-<DD>
|
|
<B>dh_installman</B> will now prefer detecting the language from the
|
|
path name rather than the extension.
|
|
<DT id="152">-<DD>
|
|
<B>dh_auto_install</B> will now only create the destination
|
|
directory it needs. Previously, it would create the package build
|
|
directory for all packages. This will not affect packages that only
|
|
build with debhelper commands, but it may expose bugs in commands not
|
|
included in debhelper.
|
|
<DT id="153">-<DD>
|
|
The helpers <B>dh_installdocs</B>, <B>dh_installexamples</B>, <B>dh_installinfo</B>,
|
|
and <B>dh_installman</B> now error out if their config has a pattern that
|
|
does not match anything or reference a path that does not exist.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Known exceptions include building with the <B>nodoc</B> profile, where the
|
|
above tools will silently permit failed matches where the patterns
|
|
are used to specify documentation.
|
|
<DT id="154">-<DD>
|
|
The helpers <B>dh_installdocs</B>, <B>dh_installexamples</B>, <B>dh_installinfo</B>,
|
|
and <B>dh_installman</B> now accept the parameter <B>--sourcedir</B> with same
|
|
meaning as <B>dh_install</B>. Furthermore, they now also fall back to
|
|
<I>debian/tmp</I> like <B>dh_install</B>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Migration note: A bug in debhelper 11 up to 11.1.5 made
|
|
<B>dh_installinfo</B> incorrectly ignore <B>--sourcedir</B>.
|
|
<DT id="155">-<DD>
|
|
The <B>perl-makemaker</B> and <B>perl-build</B> build systems no longer pass
|
|
<B>-I.</B> to perl. Packages that still need this behaviour can emulate
|
|
it by using the <B></B><FONT SIZE="-1"><B>PERL5LIB</B></FONT><B></B> environment variable. E.g. by adding
|
|
<B>export PERL5LIB=.</B> in their debian/rules file (or similar).
|
|
<DT id="156">-<DD>
|
|
The <B></B><FONT SIZE="-1"><B>PERL_USE_UNSAFE_INC</B></FONT><B></B> environment variable is no longer set by
|
|
<B>dh</B> or any of the <B>dh_auto_*</B> tools. It was added as a temporary
|
|
work around to avoid a lot of packages failing to build at the same
|
|
time.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Note this item will eventually become obsolete as upstream intends
|
|
to drop support for the <B></B><FONT SIZE="-1"><B>PERL_USE_UNSAFE_INC</B></FONT><B></B> environment variable.
|
|
When perl drops support for it, then this variable will be removed
|
|
retroactively from existing compat levels as well.
|
|
<DT id="157">-<DD>
|
|
The <B>dh_makeshlibs</B> helper will now exit with an error if objdump
|
|
returns a non-zero exit from analysing a given file.
|
|
<DT id="158">-<DD>
|
|
The <B>dh_installdocs</B> and <B>dh_installexamples</B> tools may now install
|
|
<I>most</I> of the documentation in a different path to comply with the
|
|
recommendation from Debian policy §12.3 (since version 3.9.7).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Note that if a given source package only contains a single binary
|
|
package in <I>debian/control</I> or none of the packages are <I>-doc</I>
|
|
packages, then this change is not relevant for that source package and
|
|
you can skip to the next change.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
By default, these tools will now attempt to determine a ``main package
|
|
for the documentation'' (called a <I>doc-main-package</I> from here on) for
|
|
every <I>-doc</I> package. If they find such a <I>doc-main-package</I>, they
|
|
will now install the documentation into the path <I>/usr/share/doc/doc-main-package</I> in the given doc package.
|
|
I.e. the path can change but the documentation is still shipped in the
|
|
<I>-doc</I> package.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <B>--doc-main-package</B> option can be used when the auto-detection
|
|
is insufficient or to reset the path to its previous value if there is
|
|
a reason to diverge from Debian policy recommendation.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Some documentation will not be affected by this change. These
|
|
exceptions include the copyright file, changelog files, <FONT SIZE="-1">README</FONT>.Debian,
|
|
etc. These files will still be installed in the path <I>/usr/share/doc/package</I>.
|
|
<DT id="159">-<DD>
|
|
The <B>dh_strip</B> and <B>dh_shlibdeps</B> tools no longer uses filename
|
|
patterns to determine which files to process. Instead, they open the
|
|
file and look for an <FONT SIZE="-1">ELF</FONT> header to determine if a given file is an
|
|
shared object or an <FONT SIZE="-1">ELF</FONT> executable.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This change may cause the tools to process more files than previously.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="160"><DD>
|
|
</DL>
|
|
|
|
<DT id="161">v12<DD>
|
|
|
|
|
|
This is the recommended mode of operation.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Changes from v11 are:
|
|
<DL COMPACT><DT id="162"><DD>
|
|
<DL COMPACT>
|
|
<DT id="163">-<DD>
|
|
The <B>dh_makeshlibs</B> tool now generates shlibs files with versioned
|
|
dependency by default. This means that <B>-VUpstream-Version</B>
|
|
(a.k.a. <B>-V</B>) is now the default.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If an unversioned dependency in the shlibs file is wanted, this can be
|
|
obtained by passing <B>-VNone</B> instead. However, please see
|
|
<B><A HREF="/cgi-bin/man/man2html?1+dh_makeshlibs">dh_makeshlibs</A></B>(1) for the caveat of unversioned dependencies.
|
|
<DT id="164">-<DD>
|
|
The <B>-s</B> (<B>--same-arch</B>) option is removed. Please use <B>-a</B> (<B>--arch</B>) instead.
|
|
<DT id="165">-<DD>
|
|
Invoking <B>dh_clean -k</B> now causes an error instead of a deprecation
|
|
warning.
|
|
<DT id="166">-<DD>
|
|
The <B>--no-restart-on-upgrade</B> option in <B>dh_installinit</B> has been removed.
|
|
Please use the new name <B>--no-stop-on-upgrade</B>
|
|
<DT id="167">-<DD>
|
|
There was a bug in the <B>doit</B> (and similar) functions from
|
|
Debian::Debhelper::Dh_Lib that made them spawn a shell in one
|
|
particular circumstance. This bug is now removed and will cause
|
|
helpers that rely on the bug to fail with a ``command not found''-error.
|
|
<DT id="168">-<DD>
|
|
The <B>--list-missing</B> and <B>--fail-missing</B> in <B>dh_install</B> has been
|
|
removed. Please use <B>dh_missing</B> and its corresponding options,
|
|
which can also see the files installed by other helpers.
|
|
<DT id="169">-<DD>
|
|
The <B>dh_installinit</B> helper no longer installs configuration for
|
|
the upstart init system. Instead, it will abort the build if it
|
|
finds an old upstart configuration file. The error is there to
|
|
remind the package maintainer to ensure the proper removal of the
|
|
conffiles shipped in previous versions of the package (if any).
|
|
<DT id="170">-<DD>
|
|
The <B>dh_installdeb</B> tool will do basic validation of some
|
|
<B><A HREF="/cgi-bin/man/man2html?1+dpkg-maintscript-helper">dpkg-maintscript-helper</A></B>(1) commands and will error out if the
|
|
commands appear to be invalid.
|
|
<DT id="171">-<DD>
|
|
The <B>dh_missing</B> tool will now default to <B>--list-missing</B>.
|
|
<DT id="172">-<DD>
|
|
The <B>dh_makeshlibs</B> tool will now only pass libraries to <B><A HREF="/cgi-bin/man/man2html?1+dpkg-gensymbols">dpkg-gensymbols</A></B>(1)
|
|
if the <FONT SIZE="-1">ELF</FONT> binary has a <FONT SIZE="-1">SONAME</FONT> (containing ``.so'').
|
|
<DT id="173">-<DD>
|
|
The <B>dh_compress</B> tool no longer compresses examples (i.e. anything installed
|
|
in <I></usr/share/doc/package/examples</I>>.)
|
|
<DT id="174">-<DD>
|
|
The standard sequence in <B>dh</B> now includes <B>dh_dwz</B> and
|
|
<B>dh_installinitramfs</B> by default. This makes the <B>dwz</B> and
|
|
<B>installinitramfs</B> sequences obsolete and they will now fail with an
|
|
error. If you want to skip these commands, then please insert an
|
|
empty override target for them in <I>debian/rules</I>
|
|
(e.g. <I>override_dh_dwz:</I>)
|
|
<DT id="175">-<DD>
|
|
The build systems <B>meson</B> and <B>autoconf</B> no longer explicitly set
|
|
the <B>--libexecdir</B> variable and thus relies on the build system
|
|
default - which should be <B>/usr/libexec</B> (per <FONT SIZE="-1">FHS 3.0,</FONT> adopted in
|
|
Debian Policy 4.1.5).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If a particular upstream package does not use the correct default, the
|
|
parameter can often be passed manually via <B><A HREF="/cgi-bin/man/man2html?1+dh_auto_configure">dh_auto_configure</A></B>(1). E.g.
|
|
via the following example:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
override_dh_auto_configure:
|
|
dh_auto_configure -- --libexecdir=/usr/libexec
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Note the <B>--</B> before the <B>--libexecdir</B> parameter.
|
|
<DT id="176">-<DD>
|
|
The <B>dh_installdeb</B> tool no longer installs the maintainer provided
|
|
<I>conffiles</I> file. The file has mostly been obsolete since
|
|
compatibility level 3, where <B>dh_installdeb</B> began to automatically
|
|
compute the resulting <I>conffiles</I> control file.
|
|
<DT id="177">-<DD>
|
|
The <B>dh_installsystemd</B> tool no longer relies on <B>dh_installinit</B> for
|
|
handling systemd services that have a sysvinit alternative. Both tools
|
|
must now be used in such a case to ensure the service is properly started
|
|
under both sysvinit and systemd.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If you have an override for <B>dh_installinit</B> (e.g. to call it with
|
|
<B>--no-start</B>) then you will probably need one for
|
|
<B>dh_installsystemd</B> as well now.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This change makes <B>dh_installinit</B> inject a <I>misc:Pre-Depends</I> for
|
|
<B>init-system-helpers (>= 1.54~)</B>. Please ensure that the package
|
|
lists <B>${misc:Pre-Depends}</B> in its <B>Pre-Depends</B> field before
|
|
upgrading to compat 12.
|
|
<DT id="178">-<DD>
|
|
The third-party <B>dh_golang</B> tool (from <B>dh-golang</B> package) now defaults on
|
|
honoring <B></B><FONT SIZE="-1"><B>DH_GOLANG_EXCLUDES</B></FONT><B></B> variable for source installation in -dev
|
|
packages and not only during the building process. Please set
|
|
<B></B><FONT SIZE="-1"><B>DH_GOLANG_EXCLUDES_ALL</B></FONT><B></B> to false to revert to the previous behaviour. See
|
|
<B><A HREF="/cgi-bin/man/man2html?3pm+Debian::Debhelper::Buildsystem::golang">Debian::Debhelper::Buildsystem::golang</A>(3pm)</B> for details and examples.
|
|
<DT id="179">-<DD>
|
|
<B>dh_installsystemduser</B> is now included in the <B>dh</B> standard
|
|
sequence by default.
|
|
<DT id="180">-<DD>
|
|
The <B>python-distutils</B> buildsystem is now removed. Please use the
|
|
third-party build system <B>pybuild</B> instead.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="181"><DD>
|
|
</DL>
|
|
|
|
<DT id="182">v13<DD>
|
|
|
|
|
|
This compatibility level is still open for development; use with caution.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Changes from v12 are:
|
|
<DL COMPACT><DT id="183"><DD>
|
|
<DL COMPACT>
|
|
<DT id="184">-<DD>
|
|
The <B>meson+ninja</B> build system now uses <B>meson test</B> instead of
|
|
<B>ninja test</B> when running the test suite. Any override of
|
|
<B>dh_auto_test</B> that passes extra parameters to upstream test runner
|
|
should be reviewed as <B>meson test</B> is not command line compatible
|
|
with <B>ninja test</B>.
|
|
<DT id="185">-<DD>
|
|
All debhelper like tools based on the official debhelper library
|
|
(including <B>dh</B> and the official <B>dh_*</B> tools) no longer accepts
|
|
abbreviated command parameters. At the same time, <B>dh</B> now
|
|
optimizes out calls to redundant <B>dh_*</B> helpers even when passed
|
|
long command line options.
|
|
<DT id="186">-<DD>
|
|
The <FONT SIZE="-1">ELF</FONT> related debhelper tools (<B>dh_dwz</B>, <B>dh_strip</B>,
|
|
<B>dh_makeshlibs</B>, <B>dh_shlibdeps</B>) are now only run for arch dependent
|
|
packages by default (i.e. they are excluded from <B>*-indep</B> targets
|
|
and are passed <B>-a</B> by default). If you need them for <B>*-indep</B>
|
|
targets, you can add an explicit Build-Depends on
|
|
<B>dh-sequence-elf-tools</B>.
|
|
<DT id="187">-<DD>
|
|
The third-party <B>gradle</B> build system (from <B>gradle-debian-helper</B>
|
|
package) now runs the upstream-provided test suite automatically. To
|
|
suppress such behavior, override <B>dh_auto_test</B>.
|
|
<DT id="188">-<DD>
|
|
The <B>dh_installman</B> tool now aborts if it sees conflicting
|
|
definitions of a manpage. This typically happens if the upstream
|
|
build system is installing a compressed version and the package lists
|
|
an uncompressed version of the manpage in <I>debian/package.manpages</I>. Often the easiest fix is to remove the
|
|
manpage from <I>debian/package.manpages</I> (assuming both versions
|
|
are identical).
|
|
<DT id="189">-<DD>
|
|
The <B>dh_auto_*</B> helpers now resets the environment variables <B></B><FONT SIZE="-1"><B>HOME</B></FONT><B></B>
|
|
and common <B>XDG_*</B> variable. <B></B><FONT SIZE="-1"><B>HOME</B></FONT><B></B> and <B></B><FONT SIZE="-1"><B>XDG_RUNTIME_DIR</B></FONT><B></B> are each
|
|
set to a distinct writable directory. The rest of the environment
|
|
variables are cleared.
|
|
<DT id="190">-<DD>
|
|
The <B>dh</B> command will now error if an override or hook target for an
|
|
obsolete command are present in <I>debian/rules</I>
|
|
(e.g. <B>override_dh_systemd_enable:</B>).
|
|
<DT id="191">-<DD>
|
|
The <B>dh_missing</B> command will now default to <B>--fail-missing</B>. This
|
|
can be reverted to a non-fatal warning by explicitly passing
|
|
<B>--list-missing</B> like it was in compat 12.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If you do not want the warning either, please omit the call to
|
|
<B>dh_missing</B>. If you use the <B>dh</B> command sequencer, then you can
|
|
do this by inserting the an empty override target in the
|
|
<I>debian/rules</I> file of the relevant package. As an example:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
# Disable dh_missing
|
|
override_dh_missing:
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="192">-<DD>
|
|
The <B>dh</B> command sequencer now runs <B>dh_installtmpfiles</B> in the
|
|
default sequence. The <B>dh_installtmpfiles</B> takes over handling of
|
|
tmpfiles.d configuration files. Related functionality in
|
|
<B>dh_installsystemd</B> is now disabled.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Note that <B>dh_installtmpfiles</B> responds to
|
|
<I>debian/package.tmpfiles</I> where <B>dh_installsystemd</B> used
|
|
a name without the trailing ``s''.
|
|
<DT id="193">-<DD>
|
|
Many <B>dh_*</B> tools now support limited variable expansion via the
|
|
<B>${foo}</B> syntax. In many cases, this can be used to reference paths
|
|
that contain either spaces or <B><A HREF="/cgi-bin/man/man2html?1+dpkg-architecture">dpkg-architecture</A></B>(1) values. While
|
|
this can reduce the need for <B><A HREF="/cgi-bin/man/man2html?1+dh-exec">dh-exec</A></B>(1) in some cases, it is <B>not</B>
|
|
a replacement <B><A HREF="/cgi-bin/man/man2html?1+dh-exec">dh-exec</A></B>(1) in general. If you need filtering,
|
|
renaming, etc., the package will still need <B><A HREF="/cgi-bin/man/man2html?1+dh-exec">dh-exec</A></B>(1).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Please see ``Substitutions in debhelper config files'' for syntax and
|
|
available substitution variables. To <B>dh_*</B> tool writers, substitution
|
|
expansion occurs as a part of the <B>filearray</B> and <B>filedoublearray</B>
|
|
functions.
|
|
<DT id="194">-<DD>
|
|
The <B>dh</B> command sequencer will now skip all hook and override targets
|
|
for <B>dh_auto_test</B>, <B>dh_dwz</B> and <B>dh_strip</B> when <B></B><FONT SIZE="-1"><B>DEB_BUILD_OPTIONS</B></FONT><B></B>
|
|
lists the relevant <B>nocheck</B> / <B>nostrip</B> options.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Any package relying on these targets to always be run should instead
|
|
move relevant logic out of those targets. E.g. non-test related
|
|
packaging code from <B>override_dh_auto_test</B> would have to be moved to
|
|
<B>execute_after_dh_auto_build</B> or <B>execute_before_dh_auto_install</B>.
|
|
<DT id="195">-<DD>
|
|
The <B>cmake</B> buildsystem now passes <B>-DCMAKE_SKIP_INSTALL_ALL_DEPENDENCY=ON</B>
|
|
to <B><A HREF="/cgi-bin/man/man2html?1+cmake">cmake</A></B>(1) to speed up automatic installation process. If for some reason
|
|
you need previous behavior, override the flag:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
dh_auto_configure -- -DCMAKE_SKIP_INSTALL_ALL_DEPENDENCY=OFF ...
|
|
|
|
</PRE>
|
|
|
|
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="196"><DD>
|
|
</DL>
|
|
|
|
</DL>
|
|
<A NAME="lbAP"> </A>
|
|
<H2>NOTES</H2>
|
|
|
|
|
|
|
|
<A NAME="lbAQ"> </A>
|
|
<H3>Multiple binary package support</H3>
|
|
|
|
|
|
|
|
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 <I>debian/rules</I> target, and the architecture independent packages
|
|
in the binary-indep <I>debian/rules</I> target.
|
|
<P>
|
|
|
|
To facilitate this, as well as give you more control over which packages
|
|
are acted on by debhelper programs, all debhelper programs accept the
|
|
<B>-a</B>, <B>-i</B>, <B>-p</B>, and <B>-s</B> 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.
|
|
<P>
|
|
|
|
First, any package whose <B>Architecture</B> field in <B>debian/control</B> does not
|
|
match the <B></B><FONT SIZE="-1"><B>DEB_HOST_ARCH</B></FONT><B></B> architecture will be excluded
|
|
(``Debian Policy, section 5.6.8'').
|
|
<P>
|
|
|
|
Also, some additional packages may be excluded based on the contents of the
|
|
<B></B><FONT SIZE="-1"><B>DEB_BUILD_PROFILES</B></FONT><B></B> environment variable and <B>Build-Profiles</B> fields in
|
|
binary package stanzas in <B>debian/control</B>, according to the draft policy at
|
|
<<A HREF="https://wiki.debian.org/BuildProfileSpec">https://wiki.debian.org/BuildProfileSpec</A>>.
|
|
<P>
|
|
|
|
<I>Interaction between package selections and Build-Profiles</I>
|
|
|
|
|
|
<P>
|
|
|
|
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).
|
|
<DL COMPACT>
|
|
<DT id="197">-a/--arch, -i/--indep <FONT SIZE="-1">OR</FONT> no selection options (a raw "dh_X" call)<DD>
|
|
|
|
|
|
|
|
|
|
The package disabled by Build-Profiles is silently excluded from the
|
|
selection.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Note you will receive a warning if <I>all</I> packages related to these
|
|
selections are disabled. In that case, it generally does not make
|
|
sense to do the build in the first place.
|
|
<DT id="198">-N <I>package</I> / --no-package <I>package</I><DD>
|
|
|
|
|
|
The option is accepted and effectively does nothing.
|
|
<DT id="199">-p <I>package</I> / --package <I>package</I><DD>
|
|
|
|
|
|
The option is accepted, but debhelper will not act on the package.
|
|
</DL>
|
|
<P>
|
|
|
|
Note that it does not matter whether a package is enabled or disabled
|
|
by default.
|
|
<A NAME="lbAR"> </A>
|
|
<H3>Automatic generation of Debian install scripts</H3>
|
|
|
|
|
|
|
|
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
|
|
<B>#DEBHELPER#</B> to your scripts, in the place the code should be added.
|
|
<B>#DEBHELPER#</B> will be replaced by any auto-generated code when you run
|
|
<B>dh_installdeb</B>.
|
|
<P>
|
|
|
|
If a script does not exist at all and debhelper needs to add something to
|
|
it, then debhelper will create the complete script.
|
|
<P>
|
|
|
|
All debhelper commands that automatically generate code in this way let it
|
|
be disabled by the -n parameter (see above).
|
|
<P>
|
|
|
|
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 <TT>$1</TT>, <TT>$2</TT>, etc are set with
|
|
the set command):
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
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}");
|
|
}
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAS"> </A>
|
|
<H3>Automatic generation of miscellaneous dependencies.</H3>
|
|
|
|
|
|
|
|
Some debhelper commands may make the generated package need to depend on
|
|
some other packages. For example, if you use <B><A HREF="/cgi-bin/man/man2html?1+dh_installdebconf">dh_installdebconf</A></B>(1), your
|
|
package will generally need to depend on debconf. Or if you use
|
|
<B><A HREF="/cgi-bin/man/man2html?1+dh_installxfonts">dh_installxfonts</A></B>(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.
|
|
<P>
|
|
|
|
All commands of this type, besides documenting what dependencies may be
|
|
needed on their man pages, will automatically generate a substvar called
|
|
<B>${misc:Depends}</B>. If you put that token into your <I>debian/control</I> file, it
|
|
will be expanded to the dependencies debhelper figures you need.
|
|
<P>
|
|
|
|
This is entirely independent of the standard <B>${shlibs:Depends}</B> generated by
|
|
<B><A HREF="/cgi-bin/man/man2html?1+dh_makeshlibs">dh_makeshlibs</A></B>(1), and the <B>${perl:Depends}</B> generated by <B><A HREF="/cgi-bin/man/man2html?1+dh_perl">dh_perl</A></B>(1).
|
|
You can choose not to use any of these, if debhelper's guesses don't match
|
|
reality.
|
|
<A NAME="lbAT"> </A>
|
|
<H3>Package build directories</H3>
|
|
|
|
|
|
|
|
By default, all debhelper programs assume that the temporary directory used
|
|
for assembling the tree of files in a package is debian/<I>package</I>.
|
|
<P>
|
|
|
|
Sometimes, you might want to use some other temporary directory. This is
|
|
supported by the <B>-P</B> flag. For example, "<B>dh_installdocs -Pdebian/tmp</B>", will
|
|
use <B>debian/tmp</B> as the temporary directory. Note that if you use <B>-P</B>, 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 <B>-p</B> flag to specify which binary package the debhelper program will
|
|
act on.
|
|
<A NAME="lbAU"> </A>
|
|
<H3>udebs</H3>
|
|
|
|
|
|
|
|
Debhelper includes support for udebs. To create a udeb with debhelper,
|
|
add "<B>Package-Type: udeb</B>" to the package's stanza in <I>debian/control</I>.
|
|
Debhelper will try to create udebs that comply with debian-installer
|
|
policy, by making the generated package files end in <I>.udeb</I>, not
|
|
installing any documentation into a udeb, skipping over
|
|
<I>preinst</I>, <I>postrm</I>, <I>prerm</I>, and <I>config</I> scripts, etc.
|
|
<A NAME="lbAV"> </A>
|
|
<H2>ENVIRONMENT</H2>
|
|
|
|
|
|
|
|
The following environment variables can influence the behavior of debhelper.
|
|
It is important to note that these must be actual environment variables in
|
|
order to function properly (not simply <I>Makefile</I> variables). To specify
|
|
them properly in <I>debian/rules</I>, be sure to "<B>export</B>`` them. For example,
|
|
''<B>export </B><FONT SIZE="-1"><B>DH_VERBOSE</B></FONT><B></B>".
|
|
<DL COMPACT>
|
|
<DT id="200"><B></B><FONT SIZE="-1"><B>DH_VERBOSE</B></FONT><B></B><DD>
|
|
|
|
|
|
Set to <B>1</B> to enable verbose mode. Debhelper will output every command it
|
|
runs. Also enables verbose build logs for some build systems like autoconf.
|
|
<DT id="201"><B></B><FONT SIZE="-1"><B>DH_QUIET</B></FONT><B></B><DD>
|
|
|
|
|
|
Set to <B>1</B> to enable quiet mode. Debhelper will not output commands calling
|
|
the upstream build system nor will dh print which subcommands are called
|
|
and depending on the upstream build system might make that more quiet, too.
|
|
This makes it easier to spot important messages but makes the output quite
|
|
useless as buildd log.
|
|
Ignored if <FONT SIZE="-1">DH_VERBOSE</FONT> is also set.
|
|
<DT id="202"><B></B><FONT SIZE="-1"><B>DH_COMPAT</B></FONT><B></B><DD>
|
|
|
|
|
|
Temporarily specifies what compatibility level debhelper should run at,
|
|
overriding any value specified via Build-Depends on debhelper-compat or via the
|
|
<I>debian/compat</I> file.
|
|
<DT id="203"><B></B><FONT SIZE="-1"><B>DH_NO_ACT</B></FONT><B></B><DD>
|
|
|
|
|
|
Set to <B>1</B> to enable no-act mode.
|
|
<DT id="204"><B></B><FONT SIZE="-1"><B>DH_OPTIONS</B></FONT><B></B><DD>
|
|
|
|
|
|
All debhelper tools will parse command line arguments listed in this variable
|
|
before any command option (as if they had been prepended to the command
|
|
line arguments). Unfortunately, some third-party provided tools may not
|
|
support this variable and will ignore these command line arguments.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
When using <B><A HREF="/cgi-bin/man/man2html?1+dh">dh</A></B>(1), it can be passed options that will be passed on to each
|
|
debhelper command, which is generally better than using <FONT SIZE="-1">DH_OPTIONS.</FONT>
|
|
<DT id="205"><B></B><FONT SIZE="-1"><B>DH_ALWAYS_EXCLUDE</B></FONT><B></B><DD>
|
|
|
|
|
|
If set, this adds the value the variable is set to to the <B>-X</B> options of all
|
|
commands that support the <B>-X</B> option. Moreover, <B>dh_builddeb</B> will <B>rm -rf</B>
|
|
anything that matches the value in your package build tree.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This can be useful if you are doing a build from a <FONT SIZE="-1">CVS</FONT> source tree, in
|
|
which case setting <B>DH_ALWAYS_EXCLUDE=CVS</B> will prevent any <FONT SIZE="-1">CVS</FONT> directories
|
|
from sneaking into the package you build. Or, if a package has a source
|
|
tarball that (unwisely) includes <FONT SIZE="-1">CVS</FONT> directories, you might want to export
|
|
<B>DH_ALWAYS_EXCLUDE=CVS</B> in <I>debian/rules</I>, to make it take effect wherever
|
|
your package is built.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Multiple things to exclude can be separated with colons, as in
|
|
<B>DH_ALWAYS_EXCLUDE=CVS:.svn</B>
|
|
<DT id="206"><B></B><FONT SIZE="-1"><B>DH_EXTRA_ADDONS</B></FONT><B></B><DD>
|
|
|
|
|
|
If set, this adds the specified dh addons to be run in the appropriate places
|
|
in the sequence of commands. This is equivalent to specifying the addon to run
|
|
with the --with flag in the debian/rules file. Any --without calls specifying
|
|
an addon in this environment variable will not be run.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This is intended to be used by downstreams or specific local configurations
|
|
that require a debhelper addon to be run during multiple builds without
|
|
having to patch a large number of rules file. If at all possible, this should
|
|
be avoided in favor of a --with flag in the rules file.
|
|
<DT id="207"><B></B><FONT SIZE="-1"><B>DH_COLORS</B></FONT><B></B>, <B></B><FONT SIZE="-1"><B>DPKG_COLORS</B></FONT><B></B><DD>
|
|
|
|
|
|
These variables can be used to control whether debhelper commands should use
|
|
colors in their textual output. Can be set to ``always'', ``auto'' (the default),
|
|
or ``never''.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Note that <B></B><FONT SIZE="-1"><B>DPKG_COLOR</B></FONT><B></B> also affects a number of dpkg related tools and
|
|
debhelper uses it on the assumption that you want the same color setting for
|
|
dpkg and debhelper. In the off-hand chance you want different color setting
|
|
for debhelper, you can use <B></B><FONT SIZE="-1"><B>DH_COLORS</B></FONT><B></B> instead or in addition to
|
|
<B></B><FONT SIZE="-1"><B>DPKG_COLORS</B></FONT><B></B>.
|
|
<DT id="208"><B></B><FONT SIZE="-1"><B>NO_COLOR</B></FONT><B></B><DD>
|
|
|
|
|
|
If no explicit request for color has been given (e.g. <B></B><FONT SIZE="-1"><B>DH_COLORS</B></FONT><B></B> and
|
|
<B></B><FONT SIZE="-1"><B>DPKG_COLORS</B></FONT><B></B> are both unset), the presence of this environment variable
|
|
cause the default color setting to be ``never''.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The variable is defined according to <<A HREF="https://no-color.org/">https://no-color.org/</A>>. In this
|
|
project, the environment variables (such as <B></B><FONT SIZE="-1"><B>DH_COLORS</B></FONT><B></B>) are considered
|
|
an explicit request for color.
|
|
<DT id="209"><B></B><FONT SIZE="-1"><B>CFLAGS</B></FONT><B></B>, <B></B><FONT SIZE="-1"><B>CPPFLAGS</B></FONT><B></B>, <B></B><FONT SIZE="-1"><B>CXXFLAGS</B></FONT><B></B>, <B></B><FONT SIZE="-1"><B>OBJCFLAGS</B></FONT><B></B>, <B></B><FONT SIZE="-1"><B>OBJCXXFLAGS</B></FONT><B></B>, <B></B><FONT SIZE="-1"><B>GCJFLAGS</B></FONT><B></B>, <B></B><FONT SIZE="-1"><B>FFLAGS</B></FONT><B></B>, <B></B><FONT SIZE="-1"><B>FCFLAGS</B></FONT><B></B>, <B></B><FONT SIZE="-1"><B>LDFLAGS</B></FONT><B></B><DD>
|
|
|
|
|
|
By default (in any non-deprecated compat level), debhelper will automatically
|
|
set these flags by using <B><A HREF="/cgi-bin/man/man2html?1+dpkg-buildflags">dpkg-buildflags</A></B>(1), when they are unset. If you
|
|
need to change the default flags, please use the features from
|
|
<B><A HREF="/cgi-bin/man/man2html?1+dpkg-buildflags">dpkg-buildflags</A></B>(1) to do this (e.g. <B>DEB_BUILD_MAINT_OPTIONS=hardening=all</B>
|
|
or <B>DEB_CPPFLAGS_MAINT_APPEND=-DCUSTOM_MACRO=true</B>) rather than setting the
|
|
concrete variable directly.
|
|
<DT id="210"><B></B><FONT SIZE="-1"><B>HOME</B></FONT><B></B>, <B>XDG_*</B><DD>
|
|
|
|
|
|
In compat 13 and later, these environment variables are reset before invoking
|
|
the upstream build system via the <B>dh_auto_*</B> helpers. The variables <B></B><FONT SIZE="-1"><B>HOME</B></FONT><B></B>
|
|
and <B></B><FONT SIZE="-1"><B>XDG_RUNTIME_DIR</B></FONT><B></B> will be set to a writable directory. The remaining
|
|
variables will be cleared.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The directories will be created as empty directories but they will be reused
|
|
between calls to <B>dh_auto_*</B>. Any content will persist until explicitly
|
|
deleted or <B>dh_clean</B>.
|
|
</DL>
|
|
<A NAME="lbAW"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="211"><I>/usr/share/doc/debhelper/examples/</I><DD>
|
|
|
|
|
|
A set of example <I>debian/rules</I> files that use debhelper.
|
|
<DT id="212"><<A HREF="http://joeyh.name/code/debhelper/">http://joeyh.name/code/debhelper/</A>><DD>
|
|
|
|
|
|
Debhelper web site.
|
|
</DL>
|
|
<A NAME="lbAX"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
|
|
|
|
Joey Hess <<A HREF="mailto:joeyh@debian.org">joeyh@debian.org</A>>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="213"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="214"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="215"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="216"><A HREF="#lbAE">DEBHELPER COMMANDS</A><DD>
|
|
<DL>
|
|
<DT id="217"><A HREF="#lbAF">Deprecated Commands</A><DD>
|
|
<DT id="218"><A HREF="#lbAG">Other Commands</A><DD>
|
|
</DL>
|
|
<DT id="219"><A HREF="#lbAH">DEBHELPER CONFIG FILES</A><DD>
|
|
<DL>
|
|
<DT id="220"><A HREF="#lbAI">Substitutions in debhelper config files</A><DD>
|
|
<DT id="221"><A HREF="#lbAJ">Executable debhelper config files</A><DD>
|
|
</DL>
|
|
<DT id="222"><A HREF="#lbAK">SHARED DEBHELPER OPTIONS</A><DD>
|
|
<DT id="223"><A HREF="#lbAL">COMMON DEBHELPER OPTIONS</A><DD>
|
|
<DT id="224"><A HREF="#lbAM">BUILD SYSTEM OPTIONS</A><DD>
|
|
<DT id="225"><A HREF="#lbAN">COMPATIBILITY LEVELS</A><DD>
|
|
<DL>
|
|
<DT id="226"><A HREF="#lbAO">Supported compatibility levels</A><DD>
|
|
</DL>
|
|
<DT id="227"><A HREF="#lbAP">NOTES</A><DD>
|
|
<DL>
|
|
<DT id="228"><A HREF="#lbAQ">Multiple binary package support</A><DD>
|
|
<DT id="229"><A HREF="#lbAR">Automatic generation of Debian install scripts</A><DD>
|
|
<DT id="230"><A HREF="#lbAS">Automatic generation of miscellaneous dependencies.</A><DD>
|
|
<DT id="231"><A HREF="#lbAT">Package build directories</A><DD>
|
|
<DT id="232"><A HREF="#lbAU">udebs</A><DD>
|
|
</DL>
|
|
<DT id="233"><A HREF="#lbAV">ENVIRONMENT</A><DD>
|
|
<DT id="234"><A HREF="#lbAW">SEE ALSO</A><DD>
|
|
<DT id="235"><A HREF="#lbAX">AUTHOR</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:06:08 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|