dpkg-1.16.1.1/man/dpkg-maintscript-helper.1 - nest-learning-thermostat/5.1/dpkg - Git at Google

 .TH dpkg\-maintscript\-helper 1 "2011-08-14" "Debian Project" "dpkg suite"
 .SH NAME
 dpkg\-maintscript\-helper \- works around known dpkg limitations in maintainer scripts
 .
 .SH SYNOPSIS
 .B dpkg\-maintscript\-helper
 .IR command " [" parameter "...] \fB\-\-\fP " maint-script-parameter ...
 .
 .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 \fBDPKG_MAINTSCRIPT_NAME\fP 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 \fBdpkg\-maintscript\-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
     dpkg\-maintscript\-helper rm_conffile \\
         \fIconffile\fP \fIlastversion\fP \fIpackage\fP \-\- "$@"
 .P
 \fIconffile\fP is the filename of the conffile to remove.
 \fIlastversion\fP is the last version of the package that contained the
 conffile (or the last version of the package that did not take care to
 remove the obsolete conffile if this was not immediately implemented).
 If \fIlastversion\fP is empty or omitted, then the operation is tried
 on every upgrade. \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\-backup\fP (if modified). In the
 \fBpostinst\fP, the latter file is renamed to \fIconffile\fP\fB.dpkg\-bak\fP
 and kept for reference as it contains user modifications but the former will
 be removed. 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
     dpkg\-maintscript\-helper mv_conffile \\
         \fIoldconffile\fP \fInewconffile\fP \fIlastversion\fP \fIpackage\fP \-\- "$@"
 .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. If \fIlastversion\fP 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). \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\-upgrade/abort\-install, the \fBpostrm\fP renames
 \fIoldconffile\fP\fB.dpkg\-remove\fP back to \fIoldconffile\fP if required.
 .
 .SH INTEGRATION IN PACKAGES
 .P
 Given that \fBdpkg\-maintscript\-helper\fP is used in the \fBpreinst\fP,
 using it unconditionally requires a pre-dependency to ensure that the
 required version of dpkg has been unpacked before. The required version
 depends on the command used, for \fBrm_conffile\fP and \fBmv_conffile\fP
 it is 1.15.7.2:
 .P
     \fBPre\-Depends:\fP dpkg (>= 1.15.7.2)
 .P
 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 dpkg:
 .P
     if dpkg\-maintscript\-helper supports \fIcommand\fP; then
         dpkg\-maintscript\-helper \fIcommand\fP ...
     fi
 .
 .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.
	.TH dpkg\-maintscript\-helper 1 "2011-08-14" "Debian Project" "dpkg suite"
	.SH NAME
	dpkg\-maintscript\-helper \- works around known dpkg limitations in maintainer scripts
	.
	.SH SYNOPSIS
	.B dpkg\-maintscript\-helper
	.IR command " [" parameter "...] \fB\-\-\fP " maint-script-parameter ...
	.
	.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 \fBDPKG_MAINTSCRIPT_NAME\fP 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 \fBdpkg\-maintscript\-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
	dpkg\-maintscript\-helper rm_conffile \\
	\fIconffile\fP \fIlastversion\fP \fIpackage\fP \-\- "$@"
	.P
	\fIconffile\fP is the filename of the conffile to remove.
	\fIlastversion\fP is the last version of the package that contained the
	conffile (or the last version of the package that did not take care to
	remove the obsolete conffile if this was not immediately implemented).
	If \fIlastversion\fP is empty or omitted, then the operation is tried
	on every upgrade. \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\-backup\fP (if modified). In the
	\fBpostinst\fP, the latter file is renamed to \fIconffile\fP\fB.dpkg\-bak\fP
	and kept for reference as it contains user modifications but the former will
	be removed. 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
	dpkg\-maintscript\-helper mv_conffile \\
	\fIoldconffile\fP \fInewconffile\fP \fIlastversion\fP \fIpackage\fP \-\- "$@"
	.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. If \fIlastversion\fP 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). \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\-upgrade/abort\-install, the \fBpostrm\fP renames
	\fIoldconffile\fP\fB.dpkg\-remove\fP back to \fIoldconffile\fP if required.
	.
	.SH INTEGRATION IN PACKAGES
	.P
	Given that \fBdpkg\-maintscript\-helper\fP is used in the \fBpreinst\fP,
	using it unconditionally requires a pre-dependency to ensure that the
	required version of dpkg has been unpacked before. The required version
	depends on the command used, for \fBrm_conffile\fP and \fBmv_conffile\fP
	it is 1.15.7.2:
	.P
	\fBPre\-Depends:\fP dpkg (>= 1.15.7.2)
	.P
	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 dpkg:
	.P
	if dpkg\-maintscript\-helper supports \fIcommand\fP; then
	dpkg\-maintscript\-helper \fIcommand\fP ...
	fi
	.
	.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.