.\"<!-- $Id: sysconftool1.sgml,v 1.2 2005/07/16 18:37:24 mrsam Exp $ -->
.\"<!-- Copyright 2000-2003 Double Precision, Inc.  See COPYING for -->
.\"<!-- distribution information. -->
.\" This manpage has been automatically generated by docbook2man 
.\" from a DocBook document.  This tool can be found at:
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
.\" Please send any bug reports, improvements, comments, patches, 
.\" etc. to Steve Cheng <steve@ggi-project.org>.
.TH "SYSCONFTOOL" "1" "16 July 2005" "Double Precision, Inc." ""

.SH NAME
sysconftool \- install configuration files
.SH SYNOPSIS

\fBsysconftool\fR [ \fBoptions\fR ] [ \fBfilename.dist\fR\fI ...\fR ]

.SH "DESCRIPTION"
.PP
\fBsysconftool\fR is a development utility that helps to install
application configuration files. \fBsysconftool\fR allows an
existing
application to be upgraded without losing the older version's configuration
settings.
.PP
A new version of an application often introduces new configuration
settings. Sometimes obsolete configuration settings are removed.  Existing
configuration settings may also now have additional options, or certain
options are no longer valid any more.  Because of this, an application upgrade
usually installs a fresh set of configuration files, containing a default
configuration that's known to work.  Keeping the existing files carries the
risk of the application failing to function properly due to a configuration
that is no longer valid.
.PP
A typical application installation script copies over configuration files
with default settings.  Existing configuration files are backed up or
overwritten. With \fBsysconftool\fR, an application will install a
configuration file names \fIfilename.dist\fR, instead of
\fIfilename\fR\&.
Then, the application's installation script runs
\fBsysconftool\fR\&.
\fBsysconftool\fR copies \fIfilename.dist\fR to
\fIfilename\fR, but
also checks if \fIfilename\fR from an older version of the
application
already exist. If \fIfilename\fR an older
\fBsysconftool\fR-installed
configuration file, it's configuration settings replace the defaults in
\fIfilename.dist\fR, which is then subsequently installed
as \fIfilename\fR\&.
\fBsysconftool\fR is smart enough to:
.TP 0.2i
\(bu
Remove configuration settings that no longer exist.
.TP 0.2i
\(bu
Add new configuration settings.
.TP 0.2i
\(bu
Do not preserve an
older configuration setting if there's a possibility that it is no longer
valid in the new version of the application.
.PP
\fBsysconftool\fR produces a short report when it runs. The report
lists every configuration setting in
\fI$filename.dist\fR, and its disposition.
The possible dispositions are:
.TP
\fBnew\fR
This a new configuration setting that wasn't
found in the existing \fI$filename\fR\&.
.TP
\fBunchanged\fR
This setting's value was taken
from the existing \fI$filename\fR,
replacing the default value provided by
\fI$filename.dist\fR\&.
.TP
\fBUPDATED\fR
This setting has been previously set in \fI$filename\fR,
but the setting's value may no longer be valid in the new version of the
application, so its default value is taken from
\fI$filename.dist\fR, and it may
need to be manually adjusted.
.PP
All this logic is based on some additional metadata that must be included
in each configuration file, that \fBsysconftool\fR reads.
For this to work, both the old and the new version of the
application must be \fBsysconftool\fR-ized.
\fBsysconftool\fR
operates in a fail-safe mode.  If the old version did not use
\fBsysconftool\fR, \fI$filename\fR is backed up to
\fI$filename.bak\fR, and \fI$filename\fR is
copied to \fI$filename\fR\&. This
is what would essentially happen anyway without \fBsysconftool\fR\&.
The local configuration needs to be reentered into
\fI$filename\fR, so
nothing is lost.  However, the next upgrade will see
\fBsysconftool\fR do its job.
.SH "ADDING SYSCONFTOOL SUPPORT TO AN EXISTING APPLICATION"
.PP
\fBsysconftool\fR requires the application to use
\fBautoconf\fR and \fBautomake\fR\&. The first step
is to run the
\fBsysconftoolize\fR script from the application's source
directory.
\fBsysconftoolize\fR copies the \fBsysconftool\fR
script to the
current directory, and appends a default install-configure
rule to
\fIMakefile.am\fR\&. After running
\fBsysconftoolize\fR the macro
AC_PROG_SYSCONFTOOL must be manually added to
\fIconfigure.in\fR, and \fIMakefile.am\fR must be modified as
follows.
.PP
\fIMakefile.am\fR must be modified to install configuration
files as
\fIfilename.dist\fR instead of
\fIfilename\fR\&.  The default
install-configure rule assumes that
sysconf_DATA lists all
configuration files in
\fIsysconfdir\fR, and runs \fBsysconftool\fR on
them.
This will usually have to be modified, according to the application's
individual needs. Finally, \fIMakefile.am\fR must be modified to
distribute the \fBsysconftool\fR script in the application's
source
distribution.  Adding \fBsysconftool\fR to
EXTRA_DIST is what's needed in most cases.
.PP
Finally, certain \fBsysconftool\fR magic incantations must be
added to the application's configuration files, see \fBsysconftool\fR(7) for more information. The last
step involves updating the application's
\fIINSTALL\fR instructions, so that the
application can be properly installed.  The following instructions must be
added to \fIINSTALL\fR:
.TP 3
1. 
Run "make install-configure" after "make install".
.TP 3
2. 
If this is the first \fBsysconftool\fR-ized version, DO NOT
simply copy over the old configuration files, and overwrite the new
configuration files.  Instead, manually edit each configuration file, and
manually reset each configuration setting.  This is because the new
configuration files include the magic code for \fBsysconftool\fR, which
would be lost when the configuration file is overwritten.
.TP 3
3. 
If this is not the first \fBsysconftool\fR-ized version, the
output of \fBmake install-configure\fR must be reviewed in
order to
manually adjust or tweak what \fBsysconftool\fR did.  Many large
configuration files can result in lots of output, so the output of
\fBmake
install-configure\fR should be saved into a file, and reviewed.
.SH "SEE ALSO"
.PP
\fBsysconftoolcheck\fR(1),
\fBsysconftool\fR(7)\&.
