diff options
Diffstat (limited to 'dh_installdeb')
| -rwxr-xr-x | dh_installdeb | 144 |
1 files changed, 142 insertions, 2 deletions
diff --git a/dh_installdeb b/dh_installdeb index 111f3bb6..d15fb0e3 100755 --- a/dh_installdeb +++ b/dh_installdeb @@ -36,6 +36,13 @@ correct permissions. These maintainer scripts are installed into the F<DEBIAN> directory. +B<dh_installdeb> will perform substitution of known tokens of +the pattern B<#TOKEN#>. In generally, scripts will want to +include the B<#DEBHELPER#> to benefit from the shell scripts +generated by debhelper commands (including those from +B<dh_installdeb> when it processes I<package>.maintscript files) + +For more information on what tokens Inside the scripts, the token B<#DEBHELPER#> is replaced with shell script snippets generated by other debhelper commands. @@ -88,9 +95,124 @@ error in compat 12. =back +=head1 OPTIONS + +=over 4 + +=item B<-D>I<TOKEN=VALUE>, B<--define> I<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> also applies to tokens defined +on the command line. Invalid token names will trigger an error. + +In the simple case, this parameter will cause B<< #I<TOKEN># >> +to be replaced by I<VALUE>. If I<VALUE> starts with a literal +I<@>-sign, then I<VALUE> is expected to point to a file +containing the actual value to insert. + +An explicit declared token with this parameter will replace built-in +tokens. + +Test examples to aid with the understanding: + + cat >> debian/postinst <<EOF + #SIMPLE# + #FILEBASED# + EOF + echo -n "Complex value" > some-file + dh_installdeb --define SIMPLE=direct --define FILEBASED=@some-file + +In this example, B<#SIMPLE#> will expand to B<direct> and B<#FILEBASED#> +will expand to B<Complex value>. + +It is also possible to do set package-specific values for a given +token. This is useful when B<dh_installdeb> is acting on multiple +packages that need different values for the same token. This is +done by prefixing the token name with B<< pkg.I<package-name>. >>. + +This can be used as in the following example: + + cat >> debian/foo.postinst <<EOF + # Script for #PACKAGE# + #TOKEN# + EOF + cat >> debian/bar.postinst <<EOF + # Script for #PACKAGE# + #TOKEN# + EOF + cat >> debian/baz.postinst <<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 + +In this example, B<#TOKEN#> will expand to B<default> in F<debian/foo.postinst>, +to B<unique-bar-value> in F<debian/bar.postinst> and to B<unique-baz-value> +in F<debian/baz.postinst>. + +Note that the B<#pkg.*#> tokens will be visible in all scripts acted on. E.g. +you can refer to B<#pkg.bar.TOKEN#> inside F<debian/foo.postinst> and it will +be replaced by B<unique-bar-value>. + +=back + +=head1 SUBSTITUTION IN MAINTAINER SCRIPTS + +The B<dh_installdeb> will automatically replace the following tokens +inside a provided maintainer script (if not replaced via B<-D>/B<--define>): + +=over 4 + +=item #DEBHELPER# + +This token is by default replaced with generated shell snippets debhelper +commands. This includes the snippets generated by +B<dh_installdeb> from I<package>.maintscript file (if present). + +=item #DEB_HOST_I<NAME>#, #DEB_BUILD_I<NAME>#, #DEB_TARGET_I<NAME># + +These tokens are replaced with the respective variable from +L<dpkg-architecture(1)>. In almost all cases, you will want +use the B<< #DEB_HOST_I<NAME> >> variant in a script to ensure +you get the right value when cross-building. + +On a best effort, tokens of this pattern that do not match +a variable in L<dpkg-architecture(1)> will be left as-is. + +=item #ENV.I<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. + +Note that there are limits on which names can be used (see +L</Limitations in token names>). + +=item #PACKAGE# + +This token is by default replaced the package name, which will contain +the concrete script. + +=back + +=head2 Limitations in token names + +All tokens intended to be substituted must match the regex: #[A-Za-z0-9_.+]+# + +Tokens that do not match that regex will be silently ignored if found in the +script template. Invalid token names passed to B<-D> or B<--define> will +cause B<dh_installdeb> to reject the command with an error in most cases. + =cut -init(); +my %PROVIDED_SUBST; + +init(options => { + 'define|D=s%' => \%PROVIDED_SUBST, +}); # dpkg-maintscript-helper commands with their associated dpkg pre-dependency # versions. @@ -172,8 +294,9 @@ foreach my $package (@{$dh{DOPACKAGES}}) { } # Install debian scripts. + my $package_subst = per_package_subst($package, \%PROVIDED_SUBST); foreach my $script (qw{postinst preinst prerm postrm}) { - debhelper_script_subst($package, $script); + debhelper_script_subst($package, $script, $package_subst); } # Install non-executable files @@ -267,6 +390,23 @@ sub _maybe_error { } } +sub per_package_subst { + my ($package, $provided_subst) = @_; + my %vars = %{$provided_subst}; + $vars{'PACKAGE'} = $package if not exists($vars{'PACKAGE'}); + for my $var (keys(%{$provided_subst})) { + if ($var !~ $Debian::Debhelper::Dh_Lib::MAINTSCRIPT_TOKEN_REGEX) { + warning("User defined token ${var} does not match ${Debian::Debhelper::Dh_Lib::MAINTSCRIPT_TOKEN_REGEX}"); + error("Invalid provided token ${var}: It cannot be substituted as it does not follow the token name rules"); + } + if ($var =~ m/^pkg[.]\Q${package}\E[.](.+)$/) { + my $new_key = $1; + $vars{$new_key} = $provided_subst->{$var}; + } + } + return \%vars; +} + =head1 SEE ALSO L<debhelper(7)> |