summaryrefslogtreecommitdiffstats
path: root/dh_installdeb
diff options
context:
space:
mode:
Diffstat (limited to 'dh_installdeb')
-rwxr-xr-xdh_installdeb429
1 files changed, 429 insertions, 0 deletions
diff --git a/dh_installdeb b/dh_installdeb
new file mode 100755
index 0000000..b9fd72b
--- /dev/null
+++ b/dh_installdeb
@@ -0,0 +1,429 @@
+#!/usr/bin/perl
+
+=head1 NAME
+
+dh_installdeb - install files into the DEBIAN directory
+
+=cut
+
+use strict;
+use warnings;
+use Debian::Debhelper::Dh_Lib;
+
+our $VERSION = DH_BUILTIN_VERSION;
+
+=head1 SYNOPSIS
+
+B<dh_installdeb> [S<I<debhelper options>>]
+
+=head1 DESCRIPTION
+
+B<dh_installdeb> is a debhelper program that is responsible for installing
+files into the F<DEBIAN> directories in package build directories with the
+correct permissions.
+
+=head1 FILES
+
+=over 4
+
+=item I<package>.postinst
+
+=item I<package>.preinst
+
+=item I<package>.postrm
+
+=item I<package>.prerm
+
+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).
+
+The B<#DEBHELPER#> token should be placed on its own line as it is
+often replaced by a multi-line shell script.
+
+=item I<package>.triggers
+
+=item I<package>.shlibs
+
+These control files are installed into the F<DEBIAN> directory.
+
+Note that I<package>.shlibs is only installed in compat level 9 and
+earlier. In compat 10, please use L<dh_makeshlibs(1)>.
+
+=item I<package>.conffiles
+
+This file will be installed into the F<DEBIAN> directory. The
+provided file will be enriched by debhelper to include all the
+B<conffiles> auto-detected by debhelper (the maintainer should
+not list there as debhelper assumes it should handle that part).
+
+This file is primarily useful for using "special" entries such as
+the B<< remove-on-upgrade >> feature from dpkg.
+
+=item I<package>.maintscript
+
+Lines in this file correspond to L<dpkg-maintscript-helper(1)>
+commands and parameters. However, the "maint-script-parameters"
+should I<not> be included as debhelper will add those automatically.
+
+Example:
+
+ # Correct
+ rm_conffile /etc/obsolete.conf 0.2~ foo
+ # INCORRECT
+ rm_conffile /etc/obsolete.conf 0.2~ foo -- "$@"
+
+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 C<mv_conffile /etc/oldconffile /etc/newconffile> will insert
+maintainer script snippets into all maintainer scripts sufficient to
+move that conffile.
+
+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.
+
+The B<dh_installdeb> 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.
+
+Where possible, B<dh_installdeb> may choose to rewrite some or all
+of the entries into equivalent features supported in dpkg without
+relying on maintainer scripts at its sole discretion (examples
+include rewriting B<rm_conffile> into dpkg's B<remove-on-upgrade>).
+The minimum requirement for activating this feature is that debhelper
+runs in compat 10 or later.
+
+Supports substitution variables in compat 13 and later as
+documented in L<debhelper(7)>.
+
+=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 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 by 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
+
+my %PROVIDED_SUBST;
+
+init(options => {
+ 'define|D=s%' => \%PROVIDED_SUBST,
+});
+
+# dpkg-maintscript-helper commands with their associated dpkg pre-dependency
+# versions.
+my %maintscript_predeps = (
+ "rm_conffile" => "",
+ "mv_conffile" => "",
+ "symlink_to_dir" => "",
+ "dir_to_symlink" => "",
+);
+my %maintscript_validator = (
+ "rm_conffile" => \&_validate_conffile_args,
+ "mv_conffile" => \&_validate_conffile_args,
+);
+
+foreach my $package (@{$dh{DOPACKAGES}}) {
+ my $tmp=tmpdir($package);
+
+ install_dir("$tmp/DEBIAN");
+
+ if (is_udeb($package)) {
+ # For udebs, only do the postinst, and no #DEBHELPER#.
+ # Udebs also support menutest and isinstallable scripts.
+ foreach my $script (qw{postinst menutest isinstallable}) {
+ my $f=pkgfile($package,$script);
+ if ($f) {
+ install_prog($f, "$tmp/DEBIAN/$script");
+ }
+ }
+
+ # stop here for udebs
+ next;
+ }
+
+ my $maintscriptfile=pkgfile($package, "maintscript");
+ my @special_conffiles_entries;
+ if ($maintscriptfile) {
+ if (compat(9)) {
+ foreach my $line (filedoublearray($maintscriptfile)) {
+ my $cmd=$line->[0];
+ error("unknown dpkg-maintscript-helper command: $cmd")
+ unless exists $maintscript_predeps{$cmd};
+ addsubstvar($package, "misc:Pre-Depends", "dpkg",
+ ">= $maintscript_predeps{$cmd}")
+ if length $maintscript_predeps{$cmd};
+ my $params=escape_shell(@$line);
+ foreach my $script (qw{postinst preinst prerm postrm}) {
+ autoscript($package, $script, "maintscript-helper",
+ "s!#PARAMS#!$params!g");
+ }
+ }
+ } else {
+ my @maintscripts = filedoublearray($maintscriptfile);
+ my @params;
+ foreach my $line (@maintscripts) {
+ my $cmd=$line->[0];
+ error("unknown dpkg-maintscript-helper command: $cmd")
+ unless exists $maintscript_predeps{$cmd};
+ addsubstvar($package, "misc:Pre-Depends", "dpkg",
+ ">= $maintscript_predeps{$cmd}")
+ if length $maintscript_predeps{$cmd};
+ if (my $validator = $maintscript_validator{$cmd}) {
+ $validator->($package, @{$line});
+ }
+ if (0) { # Disabled for now: #994919 + #994903
+ my $current_conffile = $line->[1];
+ push(@special_conffiles_entries, "remove-on-upgrade ${current_conffile}");
+ addsubstvar($package, "misc:Pre-Depends", "dpkg (>= 1.20.6~)");
+ next;
+ }
+ push(@params, escape_shell(@{$line}) );
+ }
+ if (@params) {
+ foreach my $script (qw{postinst preinst prerm postrm}) {
+ my $subst = sub {
+ my @res;
+ chomp;
+ for my $param (@params) {
+ my $line = $_;
+ $line =~ s{#PARAMS#}{$param}g;
+ push(@res, $line);
+ }
+ $_ = join("\n", @res) . "\n";
+ };
+ autoscript($package, $script, "maintscript-helper", $subst);
+ }
+ }
+ }
+ }
+
+ # Install debian scripts.
+ my $package_subst = debhelper_script_per_package_subst($package, \%PROVIDED_SUBST);
+ foreach my $script (qw{postinst preinst prerm postrm}) {
+ debhelper_script_subst($package, $script, $package_subst);
+ }
+
+ # Install non-executable files
+ my @non_exec_files;
+ # Removed in compat 12.
+ push(@non_exec_files, 'conffiles');
+ # In compat 10, we let dh_makeshlibs handle "shlibs".
+ push(@non_exec_files, 'shlibs') if compat(9);
+ foreach my $file (@non_exec_files) {
+ my $f=pkgfile($package,$file);
+ if ($f) {
+ install_file($f, "$tmp/DEBIAN/$file");
+ }
+ }
+
+ install_triggers($package, $tmp);
+ if (@special_conffiles_entries) {
+ open(my $fd, '>>', "$tmp/DEBIAN/conffiles");
+ for my $line (@special_conffiles_entries) {
+ print {$fd} "${line}\n";
+ }
+ close($fd);
+ }
+
+ # Automatic conffiles registration: If it is in /etc, it is a
+ # conffile.
+ if ( -d "$tmp/etc") {
+ complex_doit("find $tmp/etc -type f -printf '/etc/%P\n' | LC_ALL=C sort >> $tmp/DEBIAN/conffiles");
+ # Anything found?
+ if (-z "$tmp/DEBIAN/conffiles") {
+ rm_files("$tmp/DEBIAN/conffiles");
+ }
+ }
+
+ if ( -f "$tmp/DEBIAN/conffiles") {
+ reset_perm_and_owner(0644, "$tmp/DEBIAN/conffiles");
+ }
+}
+
+sub install_triggers {
+ my ($package, $tmp) = @_;
+ my $generated = generated_file($package, 'triggers', 0);
+ my @sources = grep { -f $_ } (
+ pkgfile($package, 'triggers'),
+ $generated,
+ );
+ my $target = "$tmp/DEBIAN/triggers";
+ return if not @sources;
+ if (@sources > 1) {
+ my $merged = "${generated}.merged";
+ open(my $ofd, '>', $merged)
+ or error("open ${target} failed: $!");
+ for my $src (@sources) {
+ open(my $ifd, '<', $src)
+ or error("open ${src} failed: $!");
+ print {$ofd} $_ while <$ifd>;
+ close($ifd);
+ }
+ close($ofd) or error("close ${merged} failed: $!");
+ @sources = ($merged);
+ }
+ install_file($sources[0], $target);
+}
+
+sub _validate_conffile_args {
+ my ($package, $cmd, @args) = @_;
+ my ($current_conffile, $new_conffile, $prior_version, $owning_package, $other);
+ for my $arg (@args) {
+ if ($arg eq '--') {
+ _maybe_error("The maintscripts file for $package includes a \"--\" for one of the ${cmd} commands, but it should not");
+ }
+ }
+ if ($cmd eq 'rm_conffile') {
+ ($current_conffile, $prior_version, $owning_package, $other) = @args;
+ } else {
+ ($current_conffile, $new_conffile, $prior_version, $owning_package, $other) = @args;
+ }
+ $current_conffile //= '';
+ _maybe_error("The current conffile path for ${cmd} must be present and absolute, got ${current_conffile}")
+ if not $current_conffile or substr($current_conffile, 0, 1) ne '/';
+ _maybe_error("The new conffile path for ${cmd} must be present and absolute, got ${new_conffile}")
+ if $cmd eq 'mv_conffile' and (not $new_conffile or substr($new_conffile, 0, 1) ne '/');
+
+ _maybe_error("The version for ${cmd} ${current_conffile} is not valid, got ${prior_version}")
+ if $prior_version and $prior_version !~ m{^${Debian::Debhelper::Dh_Lib::PKGVERSION_REGEX}$}o;
+ _maybe_error("The owning package for ${cmd} ${current_conffile} is not valid, got ${owning_package}")
+ if $owning_package and $owning_package !~ m{^${Debian::Debhelper::Dh_Lib::PKGNAME_REGEX}$}o;
+ if (defined($other)) {
+ warning("Too many arguments for ${cmd} ${current_conffile}");
+ }
+}
+
+sub _maybe_error {
+ my ($msg) = @_;
+ if (compat(11)) {
+ warning($msg);
+ } else {
+ error($msg);
+ }
+}
+
+=head1 SEE ALSO
+
+L<debhelper(7)>
+
+This program is a part of debhelper.
+
+=head1 AUTHOR
+
+Joey Hess <joeyh@debian.org>
+
+=cut