/*!
 * \page configurationAppendix

\section configurationAppendix Configuration

\subsection ConfigurationOverview Overview

The \b configure script automates much of the setup activity
associated with building large suites of programs like Acro on
various hardware platforms. This includes
<ol>
<li> making symbolic links so that files used for configuration can be
      accessed from one location

<li> generating Makefiles so that objects, libraries, executables and other
      'targets' can be created for specific and unique hardware platforms

<li> calling itself recursively so that sub-directories can also be configured
</ol>
There are a number of configuration options
that can be used to customize the installation.
The core %parameter list for the \b configure script is:
\verbatim
   configure hosttype [--target=target] [--srcdir=dir] [--rm]
                      [--site=site] [--prefix=dir] [--exec-prefix=dir]
                      [--program-prefix=string] [--tmpdir=dir]
                      [--with-package[=yes/no]] [--without-package]
                      [--enable-feature[=yes/no]] [--disable-feature]
                      [--norecursion] [--nfp] [-s] [-v] [-V | --version]
                      [--help]
\endverbatim
Many of these options are not necessary since system information can be
often acquired from your local machine.  Refer to the Cygnus \b configure
documentation for complete information.  


\subsection ConfigurationOptions Standard Options

The following options are either
commonly used or specific to Acro packages:

<table>
<tr>
<td>[--with-compiler=\<gcc,CC\>]</td>
<td>Sets up a specific compiler; The native compiler is the default.  </td>
</tr>

<tr>
<td> [--target=\<solaris\>] </td>
<td> Optional flag to specify the target machine that you are cross-compiling for.  </td>
</tr>

<tr>
<td> [--site=\<snl980\>] </td>
<td> Specifies the site-specific locations for MPI, etc. </td>
</tr>

<tr>
<td> [--with-debugging] </td>
<td> Turns on the DEBUGGING macro and sets the OPTIMIZATION macro to \<flag\> (code is compiled with -g by default).  </td>
</tr>

<tr>
<td> [--with-mpi] </td>
<td> Turns on the use of the MPI package. </td>
</tr>

<tr>
<td> [--with-mpe] </td>
<td> Turns on the use of the MPE package.  </td>
</tr>

<tr>
<td> [--with-swig] </td>
<td> Enables the use of swig to wrap Acro packages for use with the Python scripting language.  </td>
</tr>

<tr>
<td> [--with-static] </td>
<td> Enables the compilation of statically linked libraries (the default).  </td>
</tr>

<tr>
<td> [--with-insure] </td>
<td> Enables the compilation with the insure++ debugging tool.  </td>
</tr>

<tr>
<td> [--with-shared] </td>
<td> Enables the compilation of dynamically linked libraries, which can be shared.  </td>
</tr>

<tr>
<td> [--with-optimization=\<level\>] </td>
<td> Sets the optimization level used when compiling the source files.  This is overridden by the --with-debugging flag.  </td>
</tr>

<tr>
<td> [--with-gprof] </td>
<td> Sets the compiler to use flags that force executables to dump output files that can be read by the unix <b>gprof</b> utility to profile the code.  </td>
</tr>

</table>


\subsection ConfigurationDetails Details of the Configuration Process


The \b configure script creates Makefiles from \b Makefile.in template
files, which outline the basic `targets' that need to get built.
This script can be customized using the \b configure.in file.
Variables that are package, site or hardware dependent are stored in
individual `fragment' files.  These `fragment' files are added to the
custom created Makefiles using the host, target, package and/or
site parameters.
After the \b configure command is completed, three files will be
generated in each configured directory.

<ol>
<li>    Makefile-${target}

The suffix, ${target}, will depend on the target architecture, which
defaults to the host architecture; native builds have identical host
and target values.

<li> Makefile

This will be a symbolic link to \b Makefile-${target}. Consequently,
when \b make is executed, the default behavior is to use the last
generated Makefile-${target} file.

<li> config.status

A `recording' of the configuration process (i.e., what configure options
were used to generate the current makefile). 
</ol>

Running \b configure takes a while, so be patient. Verbose output will
always be displayed unless the %parameter `--silent'  is used. 
Further, the %parameter '--norecursion' can be used to configure
only the current directory.  All
generated \b config.status files include this %parameter as a default for
easy makefile re-generation;  after editing a \b Makefile.in file, you can
construct the associate Makefile file by executing \b config.status.

The \b configure command supports multi-platform
environments using Makefile fragment files.
The fragment files for these platforms and for the packages that Acro
relies on are located in the \b acro/config directory.  There are five
types of files in this directory:
\verbatim
    mh-<host>
    Fragments that define the utilities provided by the host (e.g. the
    definition of MAKE).

    mp-<target>-<site>
    Fragments that define information for the packages that are used by
    Acro (e.g. MPI).

    ms-<site>
    Fragments that define the site-specific general configuration
    information. If this does not exist for a given site, then the
    default ms-default fragment is used.

    mt-<target>
    Fragments needed to specfy how to compile code for a target
    architecture (e.g. compiler name/location).

    mf-<host>-<target>-<site>
    Automatically generated by the configure scripts.
\endverbatim


\subsection ConfigurationPlatforms Platforms Supported

Acro can be configured for code development and
execution on the following platforms:
\verbatim
    SUN		Solaris 2.8		CC v5.4		solaris
    PC		Red Hat LINUX 9		g++ v3.2.2	linux
    SGI		IRIX 6.5		CC v7.41	irix
    DEC		OSF 5.1			cxx v6.3-002	osf
    IBM		AIX 5.1			xlC v6		aix
    TFLOP	Cougar (compute)	ciCC v4.4.0	cougar
    TFLOP	OS (service)		iCC  v4.4.0	tflop
    Cplant	Compute OS		c++		cplant
    Cplant  	Service OS		g++		cplant
    PC		Windows (Cygwin)	g++		cygwin
    Mac		OSX (Darwin)		g++		darwin
    HP		HP-UX 10.20		CC		hpux
\endverbatim
The last column shows the configuration target used to configure Makefiles
for each of these systems.

The standard configure and build process described in Section \ref install
works on almost all of these platforms.  A noteable exception are 
cougar builds, which generate executables for the ASCI Red compute nodes.
These builds need to performed with a cross-compiler.  For example, when 
building on sasn100.sandia.gov, you would configure as follows:
\verbatim
    ./configure --site=sasn100 --target=cougar
\endverbatim

*/
