358 lines
12 KiB
Text
358 lines
12 KiB
Text
# 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 behavior based on the environment
|
|
variable B<DPKG_MAINTSCRIPT_NAME> and on the maintainer scripts arguments
|
|
that you have to forward after a double hyphen.
|
|
|
|
This program was introduced in dpkg 1.15.7.
|
|
|
|
=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
|
|
|
|
B<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 upgrade 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.
|
|
|
|
B<Note>: The symlinks and directories created during these switches need to
|
|
be shipped in the new packages, or B<dpkg> will not be able to remove them
|
|
on purge.
|
|
|
|
=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 L<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
|
|
|
|
L<dh_installdeb(1)>.
|