man-pages/man1/dh_installdeb.1.html
2021-03-31 01:06:50 +01:00

379 lines
9.2 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML><HEAD><TITLE>Man page of DH_INSTALLDEB</TITLE>
</HEAD><BODY>
<H1>DH_INSTALLDEB</H1>
Section: Debhelper (1)<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">&nbsp;</A>
<H2>NAME</H2>
dh_installdeb - install files into the DEBIAN directory
<A NAME="lbAC">&nbsp;</A>
<H2>SYNOPSIS</H2>
<B>dh_installdeb</B> [<I>debhelper options</I>]
<A NAME="lbAD">&nbsp;</A>
<H2>DESCRIPTION</H2>
<B>dh_installdeb</B> is a debhelper program that is responsible for installing
files into the <I></I><FONT SIZE="-1"><I>DEBIAN</I></FONT><I></I> directories in package build directories with the
correct permissions.
<A NAME="lbAE">&nbsp;</A>
<H2>FILES</H2>
<DL COMPACT>
<DT id="1"><I>package</I>.postinst<DD>
<DT id="2"><I>package</I>.preinst<DD>
<DT id="3"><I>package</I>.postrm<DD>
<DT id="4"><I>package</I>.prerm<DD>
These maintainer scripts are installed into the <I></I><FONT SIZE="-1"><I>DEBIAN</I></FONT><I></I> directory.
<P>
<B>dh_installdeb</B> will perform substitution of known tokens of
the pattern <B>#TOKEN#</B>. In generally, scripts will want to
include the <B>#DEBHELPER#</B> to benefit from the shell scripts
generated by debhelper commands (including those from
<B>dh_installdeb</B> when it processes <I>package</I>.maintscript files).
<P>
The <B>#DEBHELPER#</B> token should be placed on its own line as it is
often replaced by a multi-line shell script.
<DT id="5"><I>package</I>.triggers<DD>
<DT id="6"><I>package</I>.shlibs<DD>
These control files are installed into the <I></I><FONT SIZE="-1"><I>DEBIAN</I></FONT><I></I> directory.
<P>
Note that <I>package</I>.shlibs is only installed in compat level 9 and
earlier. In compat 10, please use <B><A HREF="/cgi-bin/man/man2html?1+dh_makeshlibs">dh_makeshlibs</A></B>(1).
<DT id="7"><I>package</I>.conffiles<DD>
Historically, this file was needed to manually mark files files as
conffiles. However, it has become de facto obsolete since debhelper
automatically computed which files should be marked as conffiles.
<P>
In compatibility level up and including 11, this control file will be
installed into the <I></I><FONT SIZE="-1"><I>DEBIAN</I></FONT><I></I> directory. In compatibility level 12 and
later, the file is silently ignored.
<DT id="8"><I>package</I>.maintscript<DD>
Lines in this file correspond to <B><A HREF="/cgi-bin/man/man2html?1+dpkg-maintscript-helper">dpkg-maintscript-helper</A></B>(1)
commands and parameters. However, the ``maint-script-parameters''
should <I>not</I> be included as debhelper will add those automatically.
<P>
Example:
<P>
<PRE>
# Correct
rm_conffile /etc/obsolete.conf 0.2~ foo
# INCORRECT
rm_conffile /etc/obsolete.conf 0.2~ foo -- &quot;$@&quot;
</PRE>
<P>
In compat 10 or later, any shell metacharacters will be escaped, so
arbitrary shell code cannot be inserted here. For example, a line
such as <TT>&quot;mv_conffile /etc/oldconffile /etc/newconffile&quot;</TT> will insert
maintainer script snippets into all maintainer scripts sufficient to
move that conffile.
<P>
It was also the intention to escape shell metacharacters in previous
compat levels. However, it did not work properly and as such it was
possible to embed arbitrary shell code in earlier compat levels.
<P>
The <B>dh_installdeb</B> tool will do some basic validation of some of
the commands listed in this file to catch common mistakes. The
validation is enabled as a warning since compat 10 and as a hard
error in compat 12.
<P>
Supports substitution variables in compat 13 and later as
documented in <B><A HREF="/cgi-bin/man/man2html?7+debhelper">debhelper</A></B>(7).
</DL>
<A NAME="lbAF">&nbsp;</A>
<H2>OPTIONS</H2>
<DL COMPACT>
<DT id="9"><B>-D</B><I>TOKEN=VALUE</I>, <B>--define</B> <I>TOKEN=VALUE</I><DD>
Define tokens to be replaced inside the maintainer scripts when
it is generated. Please note that the limitations described in
``Limitations in token names'' also applies to tokens defined
on the command line. Invalid token names will trigger an error.
<P>
In the simple case, this parameter will cause <B>#</B><FONT SIZE="-1">TOKEN</FONT><B>#</B>
to be replaced by <I></I><FONT SIZE="-1"><I>VALUE</I></FONT><I></I>. If <I></I><FONT SIZE="-1"><I>VALUE</I></FONT><I></I> starts with a literal
<I>@</I>-sign, then <I></I><FONT SIZE="-1"><I>VALUE</I></FONT><I></I> is expected to point to a file
containing the actual value to insert.
<P>
An explicit declared token with this parameter will replace built-in
tokens.
<P>
Test examples to aid with the understanding:
<P>
<PRE>
cat &gt;&gt; debian/postinst &lt;&lt;EOF
#SIMPLE#
#FILEBASED#
EOF
echo -n &quot;Complex value&quot; &gt; some-file
dh_installdeb --define SIMPLE=direct --define FILEBASED=@some-file
</PRE>
<P>
In this example, <B>#SIMPLE#</B> will expand to <B>direct</B> and <B>#FILEBASED#</B>
will expand to <B>Complex value</B>.
<P>
It is also possible to set package-specific values for a given
token. This is useful when <B>dh_installdeb</B> is acting on multiple
packages that need different values for the same token. This is
done by prefixing the token name with <B>pkg.</B>package-name<B>.</B>.
<P>
This can be used as in the following example:
<P>
<PRE>
cat &gt;&gt; debian/foo.postinst &lt;&lt;EOF
# Script for #PACKAGE#
#TOKEN#
EOF
cat &gt;&gt; debian/bar.postinst &lt;&lt;EOF
# Script for #PACKAGE#
#TOKEN#
EOF
cat &gt;&gt; debian/baz.postinst &lt;&lt;EOF
# Script for #PACKAGE#
#TOKEN#
EOF
dh_installdeb -pfoo -pbar -pbaz --define TOKEN=default --define pkg.bar.TOKEN=unique-bar-value \
--define pkg.baz.TOKEN=unique-baz-value
</PRE>
<P>
In this example, <B>#TOKEN#</B> will expand to <B>default</B> in <I>debian/foo.postinst</I>,
to <B>unique-bar-value</B> in <I>debian/bar.postinst</I> and to <B>unique-baz-value</B>
in <I>debian/baz.postinst</I>.
<P>
Note that the <B>#pkg.*#</B> tokens will be visible in all scripts acted on. E.g.
you can refer to <B>#pkg.bar.TOKEN#</B> inside <I>debian/foo.postinst</I> and it will
be replaced by <B>unique-bar-value</B>.
</DL>
<A NAME="lbAG">&nbsp;</A>
<H2>SUBSTITUTION IN MAINTAINER SCRIPTS</H2>
The <B>dh_installdeb</B> will automatically replace the following tokens
inside a provided maintainer script (if not replaced via <B>-D</B>/<B>--define</B>):
<DL COMPACT>
<DT id="10">#DEBHELPER#<DD>
This token is by default replaced with generated shell snippets debhelper
commands. This includes the snippets generated by
<B>dh_installdeb</B> from <I>package</I>.maintscript file (if present).
<DT id="11">#DEB_HOST_<I></I><FONT SIZE="-1"><I>NAME</I></FONT><I></I>#, #DEB_BUILD_<I></I><FONT SIZE="-1"><I>NAME</I></FONT><I></I>#, #DEB_TARGET_<I></I><FONT SIZE="-1"><I>NAME</I></FONT><I></I>#<DD>
These tokens are replaced with the respective variable from
<B><A HREF="/cgi-bin/man/man2html?1+dpkg-architecture">dpkg-architecture</A></B>(1). In almost all cases, you will want
use the <B>#DEB_HOST_</B><FONT SIZE="-1">NAME</FONT><B></B> variant in a script to ensure
you get the right value when cross-building.
<P>
On a best effort, tokens of this pattern that do not match
a variable in <B><A HREF="/cgi-bin/man/man2html?1+dpkg-architecture">dpkg-architecture</A></B>(1) will be left as-is.
<DT id="12">#ENV.<I></I><FONT SIZE="-1"><I>NAME</I></FONT><I></I>#<DD>
These tokens of this form will be replaced with value of the
corresponding environment variable. If the environment
variable is unset, the token is replaced with the empty
string.
<P>
Note that there are limits on which names can be used (see
``Limitations in token names'').
<DT id="13">#PACKAGE#<DD>
This token is by default replaced by the package name, which will contain
the concrete script.
</DL>
<A NAME="lbAH">&nbsp;</A>
<H3>Limitations in token names</H3>
All tokens intended to be substituted must match the regex: #[A-Za-z0-9_.+]+#
<P>
Tokens that do not match that regex will be silently ignored if found in the
script template. Invalid token names passed to <B>-D</B> or <B>--define</B> will
cause <B>dh_installdeb</B> to reject the command with an error in most cases.
<A NAME="lbAI">&nbsp;</A>
<H2>SEE ALSO</H2>
<B><A HREF="/cgi-bin/man/man2html?7+debhelper">debhelper</A></B>(7)
<P>
This program is a part of debhelper.
<A NAME="lbAJ">&nbsp;</A>
<H2>AUTHOR</H2>
Joey Hess &lt;<A HREF="mailto:joeyh@debian.org">joeyh@debian.org</A>&gt;
<P>
<HR>
<A NAME="index">&nbsp;</A><H2>Index</H2>
<DL>
<DT id="14"><A HREF="#lbAB">NAME</A><DD>
<DT id="15"><A HREF="#lbAC">SYNOPSIS</A><DD>
<DT id="16"><A HREF="#lbAD">DESCRIPTION</A><DD>
<DT id="17"><A HREF="#lbAE">FILES</A><DD>
<DT id="18"><A HREF="#lbAF">OPTIONS</A><DD>
<DT id="19"><A HREF="#lbAG">SUBSTITUTION IN MAINTAINER SCRIPTS</A><DD>
<DL>
<DT id="20"><A HREF="#lbAH">Limitations in token names</A><DD>
</DL>
<DT id="21"><A HREF="#lbAI">SEE ALSO</A><DD>
<DT id="22"><A HREF="#lbAJ">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:05:10 GMT, March 31, 2021
</BODY>
</HTML>