diff options
Diffstat (limited to 'dh_installdeb')
| -rwxr-xr-x | dh_installdeb | 429 |
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 |