diff options
Diffstat (limited to 'man')
-rw-r--r-- | man/Makefile.am | 3 | ||||
-rw-r--r-- | man/maintscript-helper.1 | 117 | ||||
-rw-r--r-- | man/po/po4a.cfg | 5 |
3 files changed, 124 insertions, 1 deletions
diff --git a/man/Makefile.am b/man/Makefile.am index 834883254..1dcb2dd95 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -118,7 +118,8 @@ dist_man_MANS = \ dpkg-trigger.1 \ dpkg-vendor.1 \ dpkg.1 \ - dpkg.cfg.5 + dpkg.cfg.5 \ + maintscript-helper.1 if WITH_DSELECT dist_man_MANS += \ diff --git a/man/maintscript-helper.1 b/man/maintscript-helper.1 new file mode 100644 index 000000000..f1ead944d --- /dev/null +++ b/man/maintscript-helper.1 @@ -0,0 +1,117 @@ +.TH maintscript\-helper 1 "2010-04-16" "Debian Project" "dpkg suite" +.SH NAME +maintscript\-helper \- works around known dpkg limitations in maintainer scripts +. +.SH SYNOPSIS +.B $DPKG_LIBDIR/maintscript\-helper +.IR command " [" parameters "...] \-\- " maint-script-parameters +. +.SH COMMANDS AND PARAMETERS +.P +\fBrm_conffile\fP \fIconffile\fP \fIlastversion\fP [\fIpackage\fP] +.P +\fBmv_conffile\fP \fIoldconffile\fP \fInewconffile\fP \fIlastversion\fP [\fIpackage\fP] +. +.SH DESCRIPTION +.P +This program is designed to be run within maintainer scripts to achieve +some tasks that dpkg can't (yet) handle natively either because of design +decisions or due to current limitations. +.P +Many of those tasks require coordinated actions from several maintainer +scripts (\fBpreinst\fP, \fBpostinst\fP, \fBprerm\fP, \fBpostrm\fP). 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 DPKG_MAINTSCRIPT_NAME and on the maintainer scripts arguments +that you have to forward after a double dash. +. +.SH CONFFILE RELATED TASKS +.P +When upgrading a package, dpkg will not automatically remove a conffile (a +configuration file for which 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. +.P +This means that if a package is intended to rename or remove a conffile, +it must explicitly do so and \fBmaintscript\-helper\fP can be used to implement +graceful deletion and moving of conffiles within maintainer scripts. +. +.SS REMOVING A CONFFILE +.P +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. +.P +All of this is implemented by putting the following shell snippet in the +\fBpreinst\fP, \fBpostinst\fP and \fBpostrm\fP maintainer scripts: +.P + if [ \-x $DPKG_LIBDIR/maintscript\-helper ]; then + $DPKG_LIBDIR/maintscript\-helper rm_conffile \\ + \fIconffile\fP \fIlastversion\fP \fIpackage\fP \-\- "$@" + fi +.P +\fIconffile\fP is the filename of the conffile to remove. +\fIlastversion\fP is the last version of the package that contained the +conffile. \fIpackage\fP is the package name, it's optional as it will +default to $DPKG_MAINTSCRIPT_PACKAGE (this variable is set by dpkg to the +name of the package acted upon). All the parameters of the maintainer +scripts have to be forwarded to the program after "\-\-". +.P +Current implementation: in the \fBpreinst\fP, it checks if the conffile +was modified and renames it either to \fIconffile\fP\fB.dpkg\-remove\fP (if not +modified) or to \fIconffile\fP\fB.dpkg\-bak\fP (if modified). The latter file is +kept for reference as it contains user modifications but the former will +be removed in the \fBpostinst\fP. If the package upgrade aborts, the +\fBpostrm\fP reinstalls the original conffile. During purge, the +\fBpostrm\fP will also delete the \fB.dpkg\-bak\fP file kept up to now. +. +.SS RENAMING A CONFFILE +.P +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 \fBpreinst\fP script at first, however that will result in +the user being prompted by dpkg to approve the conffile edits even though +they are not responsible of them. +.P +Graceful renaming can be implemented by putting the following shell +snippet in the \fBpreinst\fP, \fBpostinst\fP and \fBpostrm\fP maintainer +scripts: +.P + if [ \-x $DPKG_LIBDIR/maintscript\-helper ]; then + $DPKG_LIBDIR/maintscript\-helper mv_conffile \\ + \fIoldconffile\fP \fInewconffile\fP \fIlastversion\fP \fIpackage\fP \-\- "$@" + fi +.P +\fIoldconffile\fP and \fInewconffile\fP are the old and new name of the +conffile to rename. \fIlastversion\fP is the last version of the package +that contained the conffile with the old name. \fIpackage\fP is the +package name, it's optional as it will default to +$DPKG_MAINTSCRIPT_PACKAGE (this variable is set by dpkg to the name of the +package acted upon). All the parameters of the maintainer scripts have to +be forwarded to the program after "\-\-". +.P +Current implementation: the \fBpreinst\fP checks if the conffile has been +modified, if yes it's left on place otherwise it's renamed to +\fIoldconffile\fP\fB.dpkg\-remove\fP. On configuration, the \fBpostinst\fP +removes \fIoldconffile\fP\fB.dpkg\-remove\fP and renames \fIoldconffile\fP +to \fInewconffile\fP if \fIoldconffile\fP is still available. On +abort\-ugrade/abort\-install, the \fBpostrm\fP renames +\fIoldconffile\fP\fB.dpkg\-remove\fP back to \fIoldconffile\fP if required. +. +.SH AUTHORS +Copyright \(co 2010 Rapha\[:e]l Hertzog +.br +Copyright \(co 2008 Joey Hess +.br +Copyright \(co 2007 Guillem Jover +.br +Copyright \(co 2005 Scott James Remnant +.sp +This is free software; see the GNU General Public Licence version 2 or +later for copying conditions. There is NO WARRANTY. + diff --git a/man/po/po4a.cfg b/man/po/po4a.cfg index 80089ae40..92e52a178 100644 --- a/man/po/po4a.cfg +++ b/man/po/po4a.cfg @@ -193,6 +193,11 @@ add_$lang:po/$lang.add +[type:man] maintscript-helper.1 \ + $lang:$(builddir)/$lang/maintscript-helper.1 \ + add_$lang:po/$lang.add + + [type:man] start-stop-daemon.8 \ $lang:$(builddir)/$lang/start-stop-daemon.8 \ add_$lang:po/$lang.add |