From b86570f63e533abcbcb97c2572e0e5732a96307b Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 27 Apr 2024 11:40:31 +0200 Subject: Adding upstream version 1.20.13. Signed-off-by: Daniel Baumann --- man/dpkg-maintscript-helper.pod | 326 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 326 insertions(+) create mode 100644 man/dpkg-maintscript-helper.pod (limited to 'man/dpkg-maintscript-helper.pod') diff --git a/man/dpkg-maintscript-helper.pod b/man/dpkg-maintscript-helper.pod new file mode 100644 index 0000000..7e2953a --- /dev/null +++ b/man/dpkg-maintscript-helper.pod @@ -0,0 +1,326 @@ +# dpkg manual page - dpkg-maintscript-helper(1) +# +# Copyright © 2010-2012 Raphaël Hertzog +# Copyright © 2011-2015 Guillem Jover +# +# This is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + +=encoding utf8 + +=head1 NAME + +dpkg-maintscript-helper - works around known dpkg limitations in maintainer scripts + +=head1 SYNOPSIS + +B +I [I...] B<--> I... + +=head1 COMMANDS AND PARAMETERS + +=over + +=item B I + +=item B I [I [I]] + +=item B I I [I [I]] + +=item B I I [I [I]] + +=item B I I [I [I]] + +=back + +=head1 DESCRIPTION + +This program is designed to be run within maintainer scripts to achieve +some tasks that B can't (yet) handle natively either because of +design decisions or due to current limitations. + +Many of those tasks require coordinated actions from several maintainer +scripts (B, B, B, B). To +avoid mistakes the same call simply needs to be put in all scripts and the +program will automatically adapt its behaviour based on the environment +variable B and on the maintainer scripts arguments +that you have to forward after a double hyphen. + +=head1 COMMON PARAMETERS + +=over + +=item I + +Defines the latest version of the package whose upgrade should trigger the +operation. It is important to calculate I correctly so +that the operations are correctly performed even if the user rebuilt the +package with a local version. If I is empty or omitted, +then the operation is tried on every upgrade (note: it's safer to give +the version and have the operation tried only once). + +If the conffile has not been shipped for several versions, and you are +now modifying the maintainer scripts to clean up the obsolete file, +I should be based on the version of the package that +you are now preparing, not the first version of the package that lacked +the conffile. This applies to all other actions in the same way. + +For example, for a conffile removed in version B<2.0-1> of a package, +I should be set to B<2.0-1~>. This will cause the +conffile to be removed even if the user rebuilt the previous version +B<1.0-1> as B<1.0-1local1>. Or a package switching a path from +a symlink (shipped in version B<1.0-1>) to a directory (shipped in +version B<2.0-1>), but only performing the actual switch in the +maintainer scripts in version B<3.0-1>, should set I +to B<3.0-1~>. + +=item I + +The package name owning the pathname(s). +When the package is “Multi-Arch: same” this parameter +must include the architecture qualifier, otherwise it should B +usually include the architecture qualifier (as it would disallow +cross-grades, or switching from being architecture specific to +architecture B or vice versa). +If the parameter is empty or omitted, the B +and B environment variables (as set by B +when running the maintainer scripts) will be used to generate an +arch-qualified package name. + +=item B<--> + +All the parameters of the maintainer scripts have to be forwarded to the +program after B<-->. + +=back + +=head1 CONFFILE RELATED TASKS + +When upgrading a package, B will not automatically remove a conffile +(a configuration file for which B should preserve user changes) if +it is not present in the newer version. There are two principal reasons for +this; the first is that the conffile could've been dropped by accident and +the next version could restore it, users wouldn't want their changes +thrown away. The second is to allow packages to transition files from a +dpkg-maintained conffile to a file maintained by the package's maintainer +scripts, usually with a tool like debconf or ucf. + +This means that if a package is intended to rename or remove a conffile, +it must explicitly do so and B can be used +to implement graceful deletion and moving of conffiles within maintainer +scripts. + +=head2 Removing a conffile + +Note: This can be replaced in most cases by the C +flag in F (since dpkg 1.20.6), see L. + +If a conffile is completely removed, it should be removed from disk, +unless the user has modified it. If there are local modifications, they +should be preserved. If the package upgrades aborts, the newly obsolete +conffile should not disappear. + +All of this is implemented by putting the following shell snippet in the +B, B and B maintainer scripts: + +=over + +Z<> + dpkg-maintscript-helper rm_conffile \ + I I I -- "$@" + +=back + +I is the filename of the conffile to remove. + +Current implementation: in the B, it checks if the conffile +was modified and renames it either to IB<.dpkg-remove> (if not +modified) or to IB<.dpkg-backup> (if modified). In the +B, the latter file is renamed to IB<.dpkg-bak> +and kept for reference as it contains user modifications but the former will +be removed. If the package upgrade aborts, the B reinstalls the +original conffile. During purge, the B will also delete the +B<.dpkg-bak> file kept up to now. + +=head2 Renaming a conffile + +If a conffile is moved from one location to another, you need to make sure +you move across any changes the user has made. This may seem a simple +change to the B script at first, however that will result in +the user being prompted by B to approve the conffile edits even +though they are not responsible of them. + +Graceful renaming can be implemented by putting the following shell +snippet in the B, B and B maintainer +scripts: + +=over + +Z<> + dpkg-maintscript-helper mv_conffile \ + I I I I -- "$@" + +=back + +I and I are the old and new name of the +conffile to rename. + +Current implementation: the B checks if the conffile has been +modified, if yes it's left on place otherwise it's renamed to +IB<.dpkg-remove>. On configuration, the B +removes IB<.dpkg-remove> and renames I +to I if I is still available. On +abort-upgrade/abort-install, the B renames +IB<.dpkg-remove> back to I if required. + +=head1 SYMLINK AND DIRECTORY SWITCHES + +When upgrading a package, B will not automatically switch a symlink +to a directory or vice-versa. Downgrades are not supported and the path +will be left as is. + +=head2 Switching a symlink to directory + +If a symlink is switched to a real directory, you need to make sure +before unpacking that the symlink is removed. This may seem a simple +change to the B script at first, however that will result +in some problems in case of admin local customization of the symlink +or when downgrading the package. + +Graceful renaming can be implemented by putting the following shell +snippet in the B, B and B maintainer +scripts: + +=over + +Z<> + dpkg-maintscript-helper symlink_to_dir \ + I I I I -- "$@" + +=back + +I is the absolute name of the old symlink (the path will be a +directory at the end of the installation) and I is +the target name of the former symlink at I. It can either be +absolute or relative to the directory containing I. + +Current implementation: the B checks if the symlink exists +and points to I, if not then it's left in place, otherwise +it's renamed to IB<.dpkg-backup>. On configuration, +the B removes IB<.dpkg-backup> if +IB<.dpkg-backup> is still a symlink. On +abort-upgrade/abort-install, the B renames +IB<.dpkg-backup> back to I if required. + +=head2 Switching a directory to symlink + +If a real directory is switched to a symlink, you need to make sure +before unpacking that the directory is removed. This may seem a simple +change to the B script at first, however that will result +in some problems in case the directory contains conffiles, pathnames +owned by other packages, locally created pathnames, or when downgrading +the package. + +Graceful switching can be implemented by putting the following shell +snippet in the B, B and B maintainer +scripts: + +=over + +Z<> + dpkg-maintscript-helper dir_to_symlink \ + I I I I -- "$@" + +=back + +I is the absolute name of the old directory (the path +will be a symlink at the end of the installation) and I is +the target of the new symlink at I. It can either be absolute +or relative to the directory containing I. + +Current implementation: the B checks if the directory +exists, does not contain conffiles, pathnames owned by other packages, +or locally created pathnames, if not then it's left in place, otherwise +it's renamed to IB<.dpkg-backup>, and an empty staging +directory named I is created, marked with a file so that +dpkg can track it. On configuration, the B finishes the +switch if IB<.dpkg-backup> is still a directory and +I is the staging directory; it removes the staging directory +mark file, moves the newly created files inside the staging directory +to the symlink target I/, replaces the now empty staging +directory I with a symlink to I, and +removes IB<.dpkg-backup>. On +abort-upgrade/abort-install, the B renames +IB<.dpkg-backup> back to I if required. + +=head1 INTEGRATION IN PACKAGES + +When using a packaging helper, please check if it has native +B integration, which might make your life +easier. See for example B(1). + +Given that B is used in the B, +using it unconditionally requires a pre-dependency to ensure that the +required version of B has been unpacked before. The required version +depends on the command used, for B and B +it is 1.15.7.2, for B and B +it is 1.17.14: + +=over + + Pre-Depends: dpkg (>= 1.17.14) + +=back + +But in many cases the operation done by the program is not critical for +the package, and instead of using a pre-dependency we can call the +program only if we know that the required command is supported by +the currently installed B: + +=over + +Z<> + if dpkg-maintscript-helper supports I; then + dpkg-maintscript-helper I ... + fi + +=back + +The command B will return 0 on success, 1 otherwise. The +B command will check if the environment variables as set +by dpkg and required by the script are present, and will consider it a +failure in case the environment is not sufficient. + +=head1 ENVIRONMENT + +=over + +=item B + +If set, it will be used as the filesystem root directory. + +=item B + +If set, it will be used as the B data directory. + +=item B + +Sets the color mode (since dpkg 1.19.1). +The currently accepted values are: B (default), B and +B. + +=back + +=head1 SEE ALSO + +B(1). -- cgit v1.2.3