.\" $HeadURL$ $LastChangedRevision$
.\"
.TH AODMS-HELPER 1 "ADE_APP_TOKEN_RELEASE_DATE_MAN"
.SH NAME
aodms-helper \- Debian maintainer scripts generator
.br
.ne 5
.SH SYNOPSIS
.B aodms-helper
[
.B \-V
|
.B \-\-version
] [
.B \-v
|
.B \-\-verbose
|
.B \-d
.I level
|
.B \-\-debug=\fIlevel\fR 
] [
.B \-h
|
.B \-\-help
] [
.B \-p
|
.B \-\-list\-paths
]
{
[
.B \-\-stand\-alone
]
.I app\-functions\-file
|
.B \-\-clean
}
.br
.ne 5
.SH DESCRIPTION
.B Aodms-helper
takes a file 
.I app\-functions\-file
specified on the command line, which should contain shell functions
and generates the Debian maintainer scripts 
.B preinst\fR,
.B postinst\fR,
.B prerm
and
.B postrm
from it.
.PP
If the
.I app\-functions\-file
file contains functions with specific names (see USER-PROVIDED FUNCTIONS
below) then they will be be called at the appropriate time by the generated
maintainer scripts. If a function with one of these specific names does not
exist then, obviously, it will not be called; but it is not an error for
a function not to exist.
.PP
These user-provided functions may make use of functions provided by
.B aodms\fR(8) 
(see AODMS-PROVIDED FUNCTIONS below).
.SH USER-PROVIDED FUNCTIONS
In this version of
.B aodms\-helper
the following functions may be specified in
.I app\-functions\-file
(synopsis of functions is shown in standard syntax):
.TP 25
.B app_settings
This is called once before all other functions. It is expected to set any
shell variables used in other functions.
.TP 
.B app_create_groups
blah blah
.RE
.SH AODMS-PROVIDED FUNCTIONS
The user-provided functions may choose to make use of the following
functions provided by 
.B aodms\fR(8):
.TP 25
.B create_group \fIgroup\-name
blah blah
.TP 
.B delete_group \fIgroup\-name
blah blah
.RE
.br
.ne 5
.SH CONFIGURATION
None.
.br
.ne 5
.SH OPTIONS
.TP 25
.B \-\-clean
.B Aodms\-helper
should be called with this option from the recipe for the 
.B clean
target in the 
.B debian/rules 
file.
.TP 25
.B \-d \fIlevel\fR, \fB\-\-debug=\fIlevel\fR
Determines how verbose
.B aodms-helper
will be. The message types displayed for the different values of 
.I level
are as follows:
.RS 25
.TP 5
.B 0
internal errors only
.TP
.B 1
internal errors and normal errors 
.TP
.B 2
internal errors, normal errors and warnings
.TP 
.B 3
internal errors, normal errors, warnings and informational messages
.TP 
.B >3
all the above plus application-specific debug messages.
.RE
.TP
.B \-h\fR, \fB\-\-help
Displays a brief usage message.
.TP
.B \-p\fR, \fB\-\-list\-paths
List the compiled-in paths of various files and directories that
.B aodms-helper
uses.
.TP
.B \-\-stand\-alone
Maintainer scripts should be built with 
.B aodms\fR(8)
embedded inside them so as to facilitate removing the 
.B aodms 
Debian package from the run-time dependency list.
.TP 
.B \-v\fR, \fB\-\-verbose
Equivalent to
.B \-d 3\fR.
.TP
.B \-V\fR, \fB\-\-version
Print the program's version number and exit.
.br
.ne 5
.SH EXIT STATUS
On success
.B aodms-helper
returns zero. On failure it returns non-zero and displays a diagnostic
message.
.br
.ne 5
.SH FILES
.TP 25
.B .aodms\-helper\-checksums
.B Aodms
maintains the checksums of the maintainer scripts in this file in order
to determine if the maintainer scripts were generated by itself, and if
not, then in order not to overwite them.
.br
.ne 5
.SH ENVIRONMENT VARIABLES
None.
.br
.ne 5
.SH EXAMPLES
The following 
.I app\-functions\-file
could be used to create a database administrator account for a database
application:
.IP
.nf
.fam C
app_settings()
{
    DBA_GROUP=dba
    DBA_USER=dba
    DBA_HOME=/var/lib/my-database-system
}

app_create_groups()
{
   create_group $DBA_GROUP
}

app_create_users()
{
   create_user $DBA_USER $DBA_GROUP $DBA_HOME
}

app_delete_groups()
{
   delete_group $DBA_GROUP
}

app_delete_users()
{
   delete_user $DBA_USER
}
.fam T
.fi
.br
.ne 5
.SH CAVEATS
The effect of the 
.B \-\-stand\-alone 
option will probably become the default bahaviour.
.br
.ne 5
.SH STANDARDS
This manual page documents version ADE_APP_TOKEN_RELEASE_ID of
.B aodms-helper\fR.
.br
.ne 5
.SH SEE ALSO
dpkg-buildpackage(1), aodms(8)
.br
.ne 5
.SH AUTHOR
ADE_APP_TOKEN_AUTHOR_NAME <ADE_APP_TOKEN_AUTHOR_EMAIL>
.br
.ne 5
.SH COPYRIGHT & DISTRIBUTION POLICY
Copyright (C) 2004-ADE_APP_TOKEN_RELEASE_YEAR ADE_APP_TOKEN_AUTHOR_NAME
.PP
This program 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.
.PP
This program 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.
.PP
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.