.\"  $HeadURL$ $LastChangedRevision$
.\"
.TH ADE\-APP\-CONFIG 1 "ADE_APP_TOKEN_RELEASE_DATE_MAN"
.ne 5
.SH NAME
ade\-app\-config \- display application's core configuration variables
.br
.ne 5
.SH SYNOPSIS
.B ade\-app\-config
[
.B \-V
|
.B \-\-version
] [
.B \-v
|
.B \-\-verbose
|
.B \-d
.I level
|
.B \-\-debug=\fIlevel\fR
] [
.B \-h
|
.B \-\-help
] 
[
.B \-\-format=\fIformat\fR
] [ 
.B \-\-\fR[\fBin\fR]\fBdirect 
] [ 
.B \-a \fIappname\fR
| 
.B \-\-appname=\fIappname\fR
]
.I variable\fR ...
.br
.I app\fB\-config ...
.ne 5
.SH DESCRIPTION
The application\-specific 
.I app\fR\-config
program invokes
.B ade\-app\-config\fR,
passing it variable assignments on the latter's standard input. A variable
which is not specified will be derived from other variables' values or defaulted,
depending what has been specified.
.B Ade\-app\-config
then displays these assignments in a syntax that one of several other programs
can understand (default 
.B plain
text format).
.PP
If no arguments are specified, all variable assignments are displayed. If
lower case variable lines are specified as arguments then only these
are displayed.
.PP
Neither
.B ade\-app\-config
nor
.I app\fB\-config
are intended to be called directly by users. They are intended to be called
by Makefiles needing to know where to install files, by programs looking for 
their libraries and configuration files, etc.
.br
.ne 5
.SH CONFIGURATION
.B Ade\-app\-config 
requires no configuration. 
.I App\fB\-config
requires only compile\-time configuration (as detailed in the installation 
instructions in the application's source distribution.
.br
.ne 5
.SH OPTIONS
.TP 25
.B \-d \fIlevel\fR, \fB\-\-debug=\fIlevel\fR
Determines how verbose
.B ade\-app\-config
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 \-\-direct
variable assignments are written to standard output (this is the default).
.TP
.B \-\-format=\fIformat\fR
Display the variable settings in the syntax specified by
.I format\fR, 
which may be one of the following, which result in format described:
.RS 25
.TP 20
.B shell
.I variable\fB=\fIvalue
.TP
.B man
\fB.ds \fIvariable\fB \fIvalue\fB
.TP
.B perl
\fB$\fIvariable\fB = "\fIvalue\fB";
.TP
.B plain
.I value
.TP
.B make
.I variable\fB = \fIvalue
.TP
.B encapsulated\-make
a complex single statement with embedded assignments capable of being parsed by GNU 
.B make\fR(1)
only.
.TP
.B c
.B #define
.I variable
\fB"\fIvalue\fB"\fR
.RE
.TP
.B \-h\fR, \fB\-\-help
Displays a brief usage message.
.TP
.B \-\-indirect
variable assignments are written to a temporary file, and code in the format
specified by the
.B \-\-format
option is generated to read that file. 
Using format
.B plain
makes little sense with this option.
Using format
.B encapsulated\-make
is not supported with this option.
.TP
.B \-p\fR, \fB\-\-list\-paths
List the compiled\-in paths of various files and directories that
.B ade\-app\-config
uses.
.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 ade\-app\-config
returns zero. On failure it returns non\-zero and displays a diagnostic
message.
.br
.ne 5
.SH FILES
None.
.br
.ne 5
.SH ENVIRONMENT VARIABLES
The values of all variables managed by 
.I app\fB\-config
may be overruled by setting the capitalised version of the same variable name in the environment. (See 
.B EXAMPLES 
below.)
.br
.ne 5
.SH EXAMPLES
In the following examples bear in mind that ADE's own application\-specific 
.I app\fB\-config
is called
.B app\-config
.IP
.nf
.fam C
.B ade\-config \-\-format=perl ade_lib_prefix
$ade_lib_prefix = "/usr/lib/ade";
.B ade\-config \-\-format=shell \-\-indirect     
\&. /tmp/ade\-app\-config.WeXa3541
.B rm /tmp/ade\-app\-config.WeXa3541
.B ADE_MAN_PREFIX=/home/fred/ade.development-version/lib ade-config --format=make ade_man1_prefix
ADE_MAN1_PREFIX = /home/fred/ade.development-version/lib/man1
.fam T
.fi
.br
.ne 5
.SH CAVEATS
The 
.B man
output format is intented to be parsed by
.B groff\fR(1)
but with its 
.B \-U
option to enable processing of so-called 'unsafe' requests. 
.B Man\fR(1)
does not invoke 
.B groff\fR(1) 
(actually
.B nroff\fR(1))
with this option. Information on how to fix this 
can be found in the INSTALL.generic document included with the ADE sources
and installed as part of ADE's installation.
.br
.ne 5
.SH STANDARDS
This manual page documents version ADE_APP_TOKEN_RELEASE_ID of
.B ade\-app\-config\fR.
.br
.ne 5
.SH SEE ALSO
bash(1), make(1), perl(1)
.br
.ne 5
.SH AUTHOR
ADE_APP_TOKEN_AUTHOR_NAME <ADE_APP_TOKEN_AUTHOR_EMAIL>
.br
.ne 5
.SH COPYRIGHT & DISTRIBUTION POLICY
Copyright (C) 2007-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.