Adding upstream version 1.20.13.upstream/1.20.13upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 326 insertions, 0 deletions

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 <hertzog@debian.org>
+# Copyright © 2011-2015 Guillem Jover <guillem@debian.org>
+#
+# 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 <https://www.gnu.org/licenses/>.
+
+=encoding utf8
+
+=head1 NAME
+
+dpkg-maintscript-helper - works around known dpkg limitations in maintainer scripts
+
+=head1 SYNOPSIS
+
+B<dpkg-maintscript-helper>
+I<command> [I<parameter>...] B<--> I<maint-script-parameter>...
+
+=head1 COMMANDS AND PARAMETERS
+
+=over
+
+=item B<supports> I<command>
+
+=item B<rm_conffile> I<conffile> [I<prior-version> [I<package>]]
+
+=item B<mv_conffile> I<old-conffile> I<new-conffile> [I<prior-version> [I<package>]]
+
+=item B<symlink_to_dir> I<pathname> I<old-target> [I<prior-version> [I<package>]]
+
+=item B<dir_to_symlink> I<pathname> I<new-target> [I<prior-version> [I<package>]]
+
+=back
+
+=head1 DESCRIPTION
+
+This program is designed to be run within maintainer scripts to achieve
+some tasks that B<dpkg> 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<preinst>, B<postinst>, B<prerm>, B<postrm>). 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<DPKG_MAINTSCRIPT_NAME> and on the maintainer scripts arguments
+that you have to forward after a double hyphen.
+
+=head1 COMMON PARAMETERS
+
+=over
+
+=item I<prior-version>
+
+Defines the latest version of the package whose upgrade should trigger the
+operation. It is important to calculate I<prior-version> correctly so
+that the operations are correctly performed even if the user rebuilt the
+package with a local version. If I<prior-version> 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<prior-version> 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<prior-version> 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<prior-version>
+to B<3.0-1~>.
+
+=item I<package>
+
+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<not>
+usually include the architecture qualifier (as it would disallow
+cross-grades, or switching from being architecture specific to
+architecture B<all> or vice versa).
+If the parameter is empty or omitted, the B<DPKG_MAINTSCRIPT_PACKAGE>
+and B<DPKG_MAINTSCRIPT_ARCH> environment variables (as set by B<dpkg>
+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<dpkg> will not automatically remove a conffile
+(a configuration file for which B<dpkg> 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<dpkg-maintscript-helper> 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<remove-on-upgrade>
+flag in F<DEBIAN/conffiles> (since dpkg 1.20.6), see L<deb-conffiles(5)>.
+
+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<preinst>, B<postinst> and B<postrm> maintainer scripts:
+
+=over
+
+Z<>
+ dpkg-maintscript-helper rm_conffile \
+    I<conffile> I<prior-version> I<package> -- "$@"
+
+=back
+
+I<conffile> is the filename of the conffile to remove.
+
+Current implementation: in the B<preinst>, it checks if the conffile
+was modified and renames it either to I<conffile>B<.dpkg-remove> (if not
+modified) or to I<conffile>B<.dpkg-backup> (if modified). In the
+B<postinst>, the latter file is renamed to I<conffile>B<.dpkg-bak>
+and kept for reference as it contains user modifications but the former will
+be removed. If the package upgrade aborts, the B<postrm> reinstalls the
+original conffile. During purge, the B<postrm> 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<preinst> script at first, however that will result in
+the user being prompted by B<dpkg> 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<preinst>, B<postinst> and B<postrm> maintainer
+scripts:
+
+=over
+
+Z<>
+ dpkg-maintscript-helper mv_conffile \
+    I<old-conffile> I<new-conffile> I<prior-version> I<package> -- "$@"
+
+=back
+
+I<old-conffile> and I<new-conffile> are the old and new name of the
+conffile to rename.
+
+Current implementation: the B<preinst> checks if the conffile has been
+modified, if yes it's left on place otherwise it's renamed to
+I<old-conffile>B<.dpkg-remove>. On configuration, the B<postinst>
+removes I<old-conffile>B<.dpkg-remove> and renames I<old-conffile>
+to I<new-conffile> if I<old-conffile> is still available. On
+abort-upgrade/abort-install, the B<postrm> renames
+I<old-conffile>B<.dpkg-remove> back to I<old-conffile> if required.
+
+=head1 SYMLINK AND DIRECTORY SWITCHES
+
+When upgrading a package, B<dpkg> 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<preinst> 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<preinst>, B<postinst> and B<postrm> maintainer
+scripts:
+
+=over
+
+Z<>
+ dpkg-maintscript-helper symlink_to_dir \
+    I<pathname> I<old-target> I<prior-version> I<package> -- "$@"
+
+=back
+
+I<pathname> is the absolute name of the old symlink (the path will be a
+directory at the end of the installation) and I<old-target> is
+the target name of the former symlink at I<pathname>. It can either be
+absolute or relative to the directory containing I<pathname>.
+
+Current implementation: the B<preinst> checks if the symlink exists
+and points to I<old-target>, if not then it's left in place, otherwise
+it's renamed to I<pathname>B<.dpkg-backup>. On configuration,
+the B<postinst> removes I<pathname>B<.dpkg-backup> if
+I<pathname>B<.dpkg-backup> is still a symlink. On
+abort-upgrade/abort-install, the B<postrm> renames
+I<pathname>B<.dpkg-backup> back to I<pathname> 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<preinst> 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<preinst>, B<postinst> and B<postrm> maintainer
+scripts:
+
+=over
+
+Z<>
+ dpkg-maintscript-helper dir_to_symlink \
+    I<pathname> I<new-target> I<prior-version> I<package> -- "$@"
+
+=back
+
+I<pathname> is the absolute name of the old directory (the path
+will be a symlink at the end of the installation) and I<new-target> is
+the target of the new symlink at I<pathname>. It can either be absolute
+or relative to the directory containing I<pathname>.
+
+Current implementation: the B<preinst> 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 I<pathname>B<.dpkg-backup>, and an empty staging
+directory named I<pathname> is created, marked with a file so that
+dpkg can track it. On configuration, the B<postinst> finishes the
+switch if I<pathname>B<.dpkg-backup> is still a directory and
+I<pathname> 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<new-target>/, replaces the now empty staging
+directory I<pathname> with a symlink to I<new-target>, and
+removes I<pathname>B<.dpkg-backup>. On
+abort-upgrade/abort-install, the B<postrm> renames
+I<pathname>B<.dpkg-backup> back to I<pathname> if required.
+
+=head1 INTEGRATION IN PACKAGES
+
+When using a packaging helper, please check if it has native
+B<dpkg-maintscript-helper> integration, which might make your life
+easier. See for example B<dh_installdeb>(1).
+
+Given that B<dpkg-maintscript-helper> is used in the B<preinst>,
+using it unconditionally requires a pre-dependency to ensure that the
+required version of B<dpkg> has been unpacked before. The required version
+depends on the command used, for B<rm_conffile> and B<mv_conffile>
+it is 1.15.7.2, for B<symlink_to_dir> and B<dir_to_symlink>
+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<dpkg>:
+
+=over
+
+Z<>
+ if dpkg-maintscript-helper supports I<command>; then
+    dpkg-maintscript-helper I<command> ...
+ fi
+
+=back
+
+The command B<supports> will return 0 on success, 1 otherwise. The
+B<supports> 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<DPKG_ROOT>
+
+If set, it will be used as the filesystem root directory.
+
+=item B<DPKG_ADMINDIR>
+
+If set, it will be used as the B<dpkg> data directory.
+
+=item B<DPKG_COLORS>
+
+Sets the color mode (since dpkg 1.19.1).
+The currently accepted values are: B<auto> (default), B<always> and
+B<never>.
+
+=back
+
+=head1 SEE ALSO
+
+B<dh_installdeb>(1).