Merge https://salsa.debian.org/debian/debhelper

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)>