.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "DH_INSTALLDEBCONF 1"
.TH DH_INSTALLDEBCONF 1 "2022-11-26" "13.11.1~bpo11+1" "Debhelper"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
dh_installdebconf \- install files used by debconf in package build directories
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBdh_installdebconf\fR [\fIdebhelper options\fR] [\fB\-n\fR] [\fB\-\-\fR \fIparams\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBdh_installdebconf\fR is a debhelper program that is responsible for installing
files used by debconf into package build directories.
.PP
It also automatically generates the \fIpostrm\fR commands needed to interface
with debconf. The commands are added to the maintainer scripts by
\&\fBdh_installdeb\fR. See \fBdh_installdeb\fR\|(1) for an explanation of how that
works.
.PP
Note that if you use debconf, your package probably needs to depend on it
(it will be added to \fB${misc:Depends}\fR by this program).
.PP
Note that for your config script to be called by \fBdpkg\fR, your \fIpostinst\fR
needs to source debconf's confmodule. \fBdh_installdebconf\fR does not
install this statement into the \fIpostinst\fR automatically as it is too
hard to do it right.
.SH "FILES"
.IX Header "FILES"
.IP "debian/\fIpackage\fR.config" 4
.IX Item "debian/package.config"
This is the debconf \fIconfig\fR script, and is installed into the \fI\s-1DEBIAN\s0\fR
directory in the package build directory.
.Sp
Inside the script, the token \fB#DEBHELPER#\fR is replaced with
shell script snippets generated by other debhelper commands.
.IP "debian/\fIpackage\fR.templates" 4
.IX Item "debian/package.templates"
This is the debconf \fItemplates\fR file, and is installed into the \fI\s-1DEBIAN\s0\fR
directory in the package build directory.
.IP "\fIdebian/po/\fR" 4
.IX Item "debian/po/"
If this directory is present, this program will automatically use
\&\fBpo2debconf\fR\|(1) to generate merged templates
files that include the translations from there.
.Sp
For this to work, your package should build-depend on \fIpo-debconf\fR.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-n\fR, \fB\-\-no\-scripts\fR" 4
.IX Item "-n, --no-scripts"
Do not modify \fIpostrm\fR script.
.IP "\fB\-\-\fR \fIparams\fR" 4
.IX Item "-- params"
Pass the params to \fBpo2debconf\fR.
.IP "\fB\-D\fR\fITOKEN=VALUE\fR, \fB\-\-define\fR \fITOKEN=VALUE\fR" 4
.IX Item "-DTOKEN=VALUE, --define TOKEN=VALUE"
Define tokens to be replaced inside the maintainer scripts when
it is generated.  Please note that the limitations described in
\&\*(L"Limitations in token names\*(R" also applies to tokens defined
on the command line.  Invalid token names will trigger an error.
.Sp
In the simple case, this parameter will cause \fB#\f(BI\s-1TOKEN\s0\fB#\fR
to be replaced by \fI\s-1VALUE\s0\fR.  If \fI\s-1VALUE\s0\fR starts with a literal
\&\fI@\fR\-sign, then \fI\s-1VALUE\s0\fR is expected to point to a file
containing the actual value to insert.
.Sp
An explicit declared token with this parameter will replace built-in
tokens.
.Sp
Test examples to aid with the understanding:
.Sp
.Vb 6
\&        cat >> debian/config <<EOF
\&        #SIMPLE#
\&        #FILEBASED#
\&        EOF
\&        echo \-n "Complex value" > some\-file
\&    dh_installdeb \-\-define SIMPLE=direct \-\-define FILEBASED=@some\-file
.Ve
.Sp
In this example, \fB#SIMPLE#\fR will expand to \fBdirect\fR and \fB#FILEBASED#\fR
will expand to \fBComplex value\fR.
.Sp
It is also possible to set package-specific values for a given
token.  This is useful when \fBdh_installdebconf\fR is acting on multiple
packages that need different values for the same token.  This is
done by prefixing the token name with \fBpkg.\f(BIpackage-name\fB.\fR.
.Sp
This can be used as in the following example:
.Sp
.Vb 10
\&        cat >> debian/foo.config <<EOF
\&        # Script for #PACKAGE#
\&        #TOKEN#
\&        EOF
\&        cat >> debian/bar.config <<EOF
\&        # Script for #PACKAGE#
\&        #TOKEN#
\&        EOF
\&        cat >> debian/baz.config <<EOF
\&        # Script for #PACKAGE#
\&        #TOKEN#
\&        EOF
\&    dh_installdebconf \-pfoo \-pbar \-pbaz  \-\-define TOKEN=default \-\-define pkg.bar.TOKEN=unique\-bar\-value \e
\&      \-\-define pkg.baz.TOKEN=unique\-baz\-value
.Ve
.Sp
In this example, \fB#TOKEN#\fR will expand to \fBdefault\fR in \fIdebian/foo.config\fR,
to \fBunique-bar-value\fR in \fIdebian/bar.config\fR and to \fBunique-baz-value\fR
in \fIdebian/baz.config\fR.
.Sp
Note that the \fB#pkg.*#\fR tokens will be visible in all scripts acted on.  E.g.
you can refer to \fB#pkg.bar.TOKEN#\fR inside \fIdebian/foo.config\fR and it will
be replaced by \fBunique-bar-value\fR.
.SH "SUBSTITUTION IN MAINTAINER SCRIPTS"
.IX Header "SUBSTITUTION IN MAINTAINER SCRIPTS"
The \fBdh_installdebconf\fR will automatically replace the following tokens
inside a provided maintainer script (if not replaced via \fB\-D\fR/\fB\-\-define\fR):
.IP "#DEB_HOST_\fI\s-1NAME\s0\fR#, #DEB_BUILD_\fI\s-1NAME\s0\fR#, #DEB_TARGET_\fI\s-1NAME\s0\fR#" 4
.IX Item "#DEB_HOST_NAME#, #DEB_BUILD_NAME#, #DEB_TARGET_NAME#"
These tokens are replaced with the respective variable from
\&\fBdpkg\-architecture\fR\|(1).  In almost all cases, you will want
use the \fB#DEB_HOST_\f(BI\s-1NAME\s0\fB\fR variant in a script to ensure
you get the right value when cross-building.
.Sp
On a best effort, tokens of this pattern that do not match
a variable in \fBdpkg\-architecture\fR\|(1) will be left as-is.
.IP "#ENV.\fI\s-1NAME\s0\fR#" 4
.IX Item "#ENV.NAME#"
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.
.Sp
Note that there are limits on which names can be used (see
\&\*(L"Limitations in token names\*(R").
.IP "#PACKAGE#" 4
.IX Item "#PACKAGE#"
This token is by default replaced by the package name, which will contain
the concrete script.
.SS "Limitations in token names"
.IX Subsection "Limitations in token names"
All tokens intended to be substituted must match the regex: #[A\-Za\-z0\-9_.+]+#
.PP
Tokens that do not match that regex will be silently ignored if found in the
script template.  Invalid token names passed to \fB\-D\fR or \fB\-\-define\fR will
cause \fBdh_installdebconf\fR to reject the command with an error in most cases.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBdebhelper\fR\|(7)
.PP
This program is a part of debhelper.
.SH "AUTHOR"
.IX Header "AUTHOR"
Joey Hess <joeyh@debian.org>