\chapter{The \textit{configure} script}

\section{Running configure}

Autoconf is a tool producing a shell script that automatically
configures software source code to adapt to many kinds of environments.
\textbf{The configuration script produced by Autoconf is independent
of Autoconf when it is run, so that its users do not need to install
Autoconf}. In other words: you do not need have Autoconf installed
to build ABINIT.
Moreover this configuration script requires no
manual user intervention when run; it do not normally even need an
argument specifying the system type. Instead, it individually tests
for the presence of each feature that the software package it is tuned
to might need.
However it does not yet have paranormal powers, and in particular has
no access to what you have in mind. You still have to explicitely
interact with it for now, and the best way to do it is through the
numerous options of this \textit{configure} script.
\\

The \textit{configure} script accepts two classes of parameters:

\begin{itemize}
\item
script-provided options, composed of triggers (\textit{enable/disable})
and specifiers (\textit{with/without}), plus a few special options;
\item
environment variables, which influence the overall behaviour of the
script.
\end{itemize}

A typical call looks like:

\begin{verbatim}
     ./configure [OPTION] ... [VAR=VALUE] ...
\end{verbatim}

Here is what [OPTION] stands for:

\begin{center}
\begin{tabular}{|l|p{7cm}|}
\hline
\textbf{Type ...} & \textbf{if you want to ...} \\
\hline
\texttt{-{-}enable-FEATURE[=ARG]} & activate FEATURE [ARG=yes] \\
\texttt{-{-}disable-FEATURE}      & do not activate FEATURE
                                  (same as \hbox{-{-}enable-FEATURE}=no) \\
\hline
\texttt{-{-}with-PACKAGE[=ARG]}   & use PACKAGE [ARG=yes] \\
\texttt{-{-}without-PACKAGE}      & do not use PACKAGE (same as
                                  \hbox{-{-}with-PACKAGE}=no) \\
\hline
\end{tabular}
\end{center}

To assign environment variables (e.g., CPP, FC, \ldots), you specify
them as \texttt{VAR=VALUE} couples on the command line. Please note that
there must be no spaces around the '=' sign. Moreover, \texttt{VALUE}
must be quoted when it contains spaces. If some assignements are ignored
by the configure script, just try the other way around:

\begin{verbatim}
     VAR=VALUE ... ./configure [OPTION] ...
\end{verbatim}

If you run \textit{configure} from a build directory, which we highly recommend, you
will of course type \texttt{../configure} instead of \texttt{./configure}.
\\

In this chapter, the defaults for the options are specified
in square brackets. No brackets means that there is no default value.

\section{Compiler options}

ABINIT provides an comprehensive database of optimization flags. They
will suit your needs in most cases. You may however tune them using the
options listed on table \ref{tab:opt-compilers}. When set, they
replace the flags that would automatically be fetched from the
database otherwise.
\\

Linking additional libraries should be done through the use of the
\textit{CC\_LIBS} (C programs), \textit{CXX\_LIBS} (C++ programs) and
\textit{FC\_LIBS} (Fortran programs) environment variables. When
specified, they replace the settings provided by the build system during
the optimization process. \textit{FC\_LIBS} is currently the only
variable producing visible effects, but this will change in the future.
More details may be found in the "Environment variables" section below.
\\

The build system provides 3 different possible optimization levels,
controlled by the \textit{\hbox{-{-}enable-optlevel}} option:
\begin{itemize}
 \item \textit{safe};
 \item \textit{standard};
 \item \textit{aggressive}.
\end{itemize}
Their names are self-explanatory, and the default is of course
\textit{standard}, which corresponds to the optimization database
present in the previous versions of ABINIT. It is obvious that
the \textit{aggressive} level should be used with extreme care.
\\

There are 3 levels of debugging as well, available through
\textit{\hbox{-{-}enable-debug}}:
\begin{itemize}
 \item \textit{no}: do not produce debugging information (default);
 \item \textit{yes}: produce debugging information if the compilers support it
 and turn-off optimizations;
 \item \textit{symbols}: produce debugging information whenever
 possible, while keeping optimizations.
\end{itemize}

Please note that the support for 64-bit architectures is still
incomplete and will be reworked during the next development cycle of
ABINIT.

\begin{table}
\begin{center}
\begin{tabular}{|l|p{9cm}|}
\hline
\textbf{Option} & \textbf{Description} \\
\hline
\texttt{-{-}enable-64-bit-flags}        & Use 64-bit flags with all compilers \\
\texttt{-{-}enable-debug}               & Activate debug mode (no optimizations)
                                        [default=no] \\
\texttt{-{-}enable-optlevel}            & Set optimization level [default=standard] \\
\texttt{-{-}enable-tricks}              & Enable compiler tips and tricks
                                       (recommended) [default=yes] \\
\hline
\texttt{-{-}with-cppflags=FLAGS}        & Set preprocessing options \\
\hline
\texttt{-{-}with-cc-optflags=FLAGS}     & Set optimizations of C routines \\
\texttt{-{-}with-cc-ld-optflags=FLAGS}  & Prepend flags when calling the C linker \\
\texttt{-{-}with-cc-ld-optlibs=LIBS}  & Append libraries when calling the C linker \\
\hline
\texttt{-{-}with-cxx-optflags=FLAGS}    & Set optimizations of C++ routines \\
\texttt{-{-}with-cxx-ld-optflags=FLAGS} & Prepend flags when calling the C++ linker \\
\texttt{-{-}with-cxx-ld-optlibs=LIBS}  & Append libraries when calling the C++ linker \\
\hline
\texttt{-{-}enable-fc-wrapper}          & Wrap Fortran compiler calls
                                        [default=guessed] \\
\texttt{-{-}with-fc-optflags=FLAGS}     & Set-up optimization of Fortran routines \\
\texttt{-{-}with-fc-ld-optflags=FLAGS}  & Prepend flags when calling the Fortran linker \\
\texttt{-{-}with-fc-ld-optlibs=LIBS}  & Append libraries when calling the Fortran linker \\
\hline
\end{tabular}
\end{center}
\caption{ABINIT compiler options.}
\label{tab:opt-compilers}
\end{table}

\section{MPI options}

In addition to serial optimization, ABINIT provides parallel binaries
relying upon the MPI library. If you do not know what MPI stands for,
then you \underline{really} need the help of a computer scientist before
reading this section.  First let us make clear that we cannot provide
you with any support to install MPI. If you need to do it, we advise you
to ask help to your system and/or network administrators, because it
will likely require special permissions and fair technical skills.  In
many cases you will already have a working installation of MPI at your
disposal, and will at most need some information about its location.
\\

Providing extended support for MPI is extremely delicate: there is no
standard location for the package, there are concurrent implementations
following different philosophies, and Fortran support is
compiler-dependent.  Moreover, there might be several versions of MPI
installed on your system, and you have to choose one of them carefully.
In particular, if you want to enable the build of parallel code in
ABINIT --- which you will likely do --- you have to build ABINIT with
the same Fortran compiler that has been used for MPI. This is why the
configure script will tell you that it selected other compilers than
those you specified if it needs to preserve self-consistency between the
sequential and parallel versions of the code.
\\

Up to ABINIT 5.3, the interface to MPI support in the build system
was a little bit confusing, and was permanently undergoing a lot of
changes. The users' needs have first been clarified in the lifespan of
ABINIT 5.4, and the implementation has been heavily fixed between ABINIT
5.5.1 and 5.5.2, leading to some more adjustments. The user interface
has now reached a sufficient level of consistency to be frozen.
The MPI options provided by the build system are summarized in table
\ref{tab:opt-mpi}. They are valid from the 5.5.2 version of ABINIT on.
\\


\begin{table}
\begin{center}
\begin{tabular}{|l|l|}
\hline
\textbf{Option} & \textbf{Description} \\
\hline
\texttt{-{-}enable-mpi}                 & Enable MPI support [default=guessed] \\
\texttt{-{-}enable-mpi-io}              & Enable parallel I/O [default=no] \\
\texttt{-{-}enable-mpi-trace}           & Enable MPI time tracing [default=no] \\
\hline
\texttt{-{-}with-mpi-prefix=PATH}       & Prefix for the MPI installation \\
\hline
\texttt{-{-}with-mpi-cppflags=FLAGS}    & MPI preprocessing flags for parallel code \\
\hline
\texttt{-{-}with-mpi-cflags=FLAGS}      & MPI compile flags for C parallel code \\
\texttt{-{-}with-mpi-cc-ldflags=FLAGS}  & MPI link flags to prepend for parallel C programs \\
\texttt{-{-}with-mpi-cc-libs=LIBS}     & MPI libraries to append for parallel C programs \\
\hline
\texttt{-{-}with-mpi-cxxflags=FLAGS}    & MPI compile flags for C++ parallel code \\
\texttt{-{-}with-mpi-cxx-ldflags=FLAGS}  & MPI link flags to prepend for parallel C++ programs \\
\texttt{-{-}with-mpi-cxx-libs=LIBS}     & MPI libraries to append for parallel C++ programs \\
\hline
\texttt{-{-}with-mpi-fcflags=FLAGS}     & MPI compile flags for Fortran parallel code \\
\texttt{-{-}with-mpi-fc-ldflags=FLAGS}  & MPI link flags to prepend for parallel Fortran programs \\
\texttt{-{-}with-mpi-fc-libs=LIBS}     & MPI libraries to append for parallel Fortran programs \\
\hline
\texttt{-{-}with-mpi-runner=PROG}       & Full path to the MPI runner program \\
\hline
\end{tabular}
\end{center}
\caption{MPI options of ABINIT.}
\label{tab:opt-mpi}
\end{table}

The "\hbox{-{-}enable-mpi" and "-{-}}with-mpi-prefix" options to the "configure"
script are controlling all the others:
\begin{itemize}
 \item
 "-{-}enable-mpi=no" switches off the build of parallel code and is the
 default, because misconfigured MPI installations may crash the
 \textit{configure} script (see the "Environment variables" section for
 a discussion about this);
 \item
 "-{-}enable-mpi=yes" triggers MPI auto-detection, leaving a lot of
 decisional freedom to the build system;
 \item
 "-{-}enable-mpi=manual" bypasses auto-detection and takes user-specified
 build parameters as-is; the parallel code will be built independently
 of the relevance and correctness of these parameters.
\end{itemize}

If "-{-}enable-mpi" is set to "yes", the parallel code will be built only if
a usable MPI implementation can be detected. If the "-{-}with-mpi-prefix"
option is provided, \textit{enable\_mpi} is automatically set to "yes"
and the build system tries to find a usable generic MPI installation at
the specified location very early during the configuration. If this step
is successful, the compilers and the runner provided by MPI are used in
\textit{lieu} of the user-specified ones, and no further test is
performed. If "-{-}with-mpi-prefix" is not present, the build of parallel
code will be deactivated unless "-{-}enable-mpi" is explicitely set to
"yes".
\\

If the first attempt fails, a second one is undertaken once the
compilers have been configured. The build system then checks whether the
compilers are able to build MPI source code natively, taking advantage
of the user-specified parameters. If successful, a MPI runner will be
looked for using the \textit{PATH} environment variable. If something
goes wrong, the build of parallel code will be automatically disabled.
In such a case, and as a last resort, the user may force the build
through the use of "-{-}enable-mpi=manual".
\\

Additional levels of parallelization may be activated, though they
are still experimental and meant to be used by developers only:
\begin{itemize}
 \item
 "-{-}enable-mpi-io": parallel file I/O;
 \item
 "-{-}enable-mpi-trace": parallel time tracing.
\end{itemize}

You will find a detailed description of all these options in the source
package of ABINIT, within the MPI support section of the
"{~}abinit/doc/config/build-config.ac" template. We warmly recommend you
to have a close look at this file and to use it as much as you will.

\section{External libraries}

The \textit{configure} script of ABINIT provides a unified way of
dealing with external libraries, by means of a trigger (enable/disable)
and two specifiers (for include and link flags) for each package.
Below the surface, things are however much more complex: some libraries
are required by ABINIT, others not; some are contained within the source
package, others are too big to be included; a few of them depend on
other external libraries, which may or may not be found within the
package. The current situation is summarized in table
\ref{tab:dsc-extlibs}, and the corresponding options are described in
table \ref{tab:opt-extlibs}.
\\

\begin{table}
\begin{center}
\begin{tabular}{|c|c|c|c|c|}
\hline
\textbf{Library} & \textbf{Internal} & \textbf{Required} &
\textbf{Depends} & \textbf{Note} \\
\hline
bigdft    & yes & no  & ---    & \\
\hline
etsf-io   & yes & no  & netcdf & \\
\hline
etsf-xc   & yes & no  & ---    & \textit{Needs more testing} \\
\hline
fftw      & no  & no  & ---    & \\
\hline
fox       & yes & no  & ---    & \textit{Currently unsupported} \\
\hline
linalg    & yes & yes & ---    & \\
\hline
netcdf    & yes & no  & ---    & \\
\hline
wannier90 & yes & no  & ---    & \textit{Test library for the plug-in
                                 feature} \\
\hline
xmlf90    & yes & no  & ---    & \textit{Soon replaced by FoX} \\
\hline
\end{tabular}
\end{center}
\caption{Specifications of the ABINIT libraries.}
\label{tab:dsc-extlibs}
\end{table}

When a library is required and cannot be found outside the source
package, the build system systematically restores consistency by
ignoring user requests and disabling the corresponding support.
\\

Providing automatic external library detection lead to complicate the
build system too much, and jeopardized its maintainability.
Hence we decided to aim at maximum simplicity.
This means that you need to provide the include and link flags yourself,
just as you would do when directly calling the compiler, e.g.:

{\small
\begin{verbatim}
     ./configure \
        --enable-netcdf \
        --with-netcdf-includes="-I/opt/etsf/include/g95" \
        --with-netcdf-libs="-L/opt/etsf/lib -lnetcdf"
\end{verbatim}
}

\begin{table}
\begin{center}
\begin{tabular}{|l|p{9cm}|}
\hline
\textbf{Option} & \textbf{Description} \\
\hline
\texttt{-{-}enable-bigdft} & Enable support for the BigDFT wavelet library
                  [default=yes] \\
\texttt{-{-}with-bigdft-includes} & Include flags for the BigDFT library \\
\texttt{-{-}with-bigdft-libs} & Library flags for the BigDFT library \\
\hline
\texttt{-{-}enable-etsf-io} & Enable support for the ETSF I/O library
                   [default=no] \\
\texttt{-{-}with-etsf-io-includes} & Include flags for the ETSF I/O library \\
\texttt{-{-}with-etsf-io-libs} & Library flags for the ETSF I/O library \\
\hline
\texttt{-{-}enable-etsf-xc} & Enable support for the ETSF exchange-correlation library
                   [default=no] \\
\texttt{-{-}with-etsf-xc-includes} & Include flags for the XC library \\
\texttt{-{-}with-etsf-xc-libs} & Library flags for the ETSF XC library \\
\hline
\texttt{-{-}enable-fftw} & Enable support for the FFTW library
                [default=no] \\
\texttt{-{-}enable-fftw-threads} & Enable support for the threaded FFTW library
                        [default=no] \\
\texttt{-{-}with-fftw-libs} & Library flags for the FFTW library \\
\hline
\texttt{-{-}enable-fox} & Enable support for the FoX I/O library
                [default=no] \\
\texttt{-{-}with-fox-includes} & Include flags for the FoX I/O library \\
\texttt{-{-}with-fox-libs} & Library flags for the FoX I/O library \\
\hline
\texttt{-{-}with-linalg-libs} & Library flags for the linalg library \\
\hline
\texttt{-{-}enable-netcdf} & Enable support for the NetCDF I/O library
                  [default=no] \\
\texttt{-{-}with-netcdf-includes} & Include flags for the NetCDF library \\
\texttt{-{-}with-netcdf-libs} & Library flags for the NetCDF library \\
\hline
\texttt{-{-}enable-wannier90} & Enable support for the Wannier90 library
                  [default=no] \\
\texttt{-{-}with-wannier90-includes} & Include flags for the Wannier90 library \\
\texttt{-{-}with-wannier90-libs} & Library flags for the Wannier90 library \\
\hline
\texttt{-{-}enable-xmlf90} & Enable support for the XML Fortran 90 I/O library
                  [default=no] \\
\texttt{-{-}with-xmlf90-includes} & Include flags for the XMLF90 library \\
\texttt{-{-}with-xmlf90-libs} & Library flags for the XMLF90 library \\
\hline
\end{tabular}
\end{center}
\caption{External library options of ABINIT.}
\label{tab:opt-extlibs}
\end{table}

\section{Other options}

The \textit{configure} script provides a few more options. Though most
of them will only be used in specific situations, they might prove very
convenient in these cases. The full list of special options may be found
in table \ref{tab:opt-special}.
\\

The build system of ABINIT makes it possible to use config files to
store your preferred build parameters. A fully documented template is
provided in the source code under
\textit{~abinit/doc/config/build-config.ac}, along with a few examples
in \textit{~abinit/doc/config/build-examples/}. After editing this file
to suit your needs, you may save it as
\textit{\$HOME/.abinit/build/$<$hostname$>$.ac} to keep these parameters
as per-user defaults. Just replace \textit{$<$hostname$>$} by the name
of your machine, excluding the domain name. E.g.: if your machine is
called \textit{myhost.mydomain}, you will save this file as
\textit{\$HOME/.abinit/build/myhost.ac}. You may put this file at the
top level of an ABINIT source tree as well, in which case its
definitions will apply to this particular tree only. Using config files
is highly recommended, since it saves you from typing all the options on
the command-line each time you build a new version of ABINIT.
\\

\begin{table}
\begin{center}
\begin{tabular}{|l|l|}
\hline
\textbf{Option} & \textbf{Description} \\
\hline
\texttt{-{-}enable-config-file}    & Read options from config files [default=yes] \\
\texttt{-{-}with-config-file=FILE} & Specify config file to read options from \\
\hline
\texttt{-{-}enable-cclock}         & Use C clock for timings [default=no] \\
\hline
\texttt{-{-}enable-stdin}          & Read file lists from standard input
                                   [default=yes] \\
\hline
\end{tabular}
\end{center}
\caption{Special options of ABINIT.}
\label{tab:opt-special}
\end{table}

\section{Options provided by Autoconf}

Every \textit{configure} script generated by Autoconf provides a basic
set of options, whatever the package and the environment. They either
give information on the tunable parameters of the package or influence
globally the build process. In most cases you will only need a few of
them, if any.
\\

Overall configuration:

\begin{center}
\begin{tabular}{|r l|l|}
\hline
\multicolumn{2}{|l|}{\textbf{Option}} & \textbf{Description} \\
\hline
-h, & -{-}help            & display all options and exit \\
    & -{-}help=short      & display options specific to the ABINIT package \\
    & -{-}help=recursive  & display the short help of all the included
                          packages \\
-V, & -{-}version         & display version information and exit \\
-q, & -{-}quiet, -{-}silent & do not print `checking...' messages \\
    & -{-}cache-file=FILE & cache test results in FILE [disabled] \\
-C, & -{-}config-cache    & alias for `-{-}cache-file=config.cache' \\
-n, & -{-}no-create       & do not create output files \\
    & -{-}srcdir=DIR      & find the sources in DIR [configure dir or `..'] \\
\hline
\end{tabular}
\end{center}

Installation directories:

\begin{center}
\begin{tabular}{|l|p{9cm}|}
\hline
\textbf{Option} & \textbf{Description} \\
\hline
\texttt{-{-}prefix=PREFIX}       & install architecture-independent files in PREFIX
                         [/opt] \\
\texttt{-{-}exec-prefix=EPREFIX} & install architecture-dependent files in EPREFIX
                        [PREFIX] \\
\hline
\end{tabular}
\end{center}

By default, \texttt{make install} will install all the files in subdirectories
of \textit{/opt/abinit/$<$version$>$}.  You can specify an installation prefix
other than \textit{/opt} using \texttt{\hbox{-{-}prefix}}, for instance
\texttt{\hbox{-{-}prefix=\$HOME}}.
\\

For a finer-grained control, use the options below.
\\

Fine tuning of the installation directories:

\begin{center}
\begin{tabular}{|l|l|}
\hline
\textbf{Option} & \textbf{Description} \\
\hline
\texttt{-{-}bindir=DIR}         & user executables [EPREFIX/bin] \\
\texttt{-{-}sbindir=DIR}        & system admin executables [EPREFIX/sbin] \\
\texttt{-{-}libexecdir=DIR}     & program executables [EPREFIX/libexec] \\
\texttt{-{-}datadir=DIR}        & read-only architecture-independent data [PREFIX/share] \\
\texttt{-{-}sysconfdir=DIR}     & read-only single-machine data [PREFIX/etc] \\
\texttt{-{-}sharedstatedir=DIR} & modifiable architecture-independent data [PREFIX/com] \\
\texttt{-{-}localstatedir=DIR}  & modifiable single-machine data [PREFIX/var] \\
\texttt{-{-}libdir=DIR}         & object code libraries [EPREFIX/lib] \\
\texttt{-{-}includedir=DIR}     & C header files [PREFIX/include] \\
\texttt{-{-}oldincludedir=DIR}  & C header files for non-gcc [/usr/include] \\
\texttt{-{-}infodir=DIR}        & info documentation [PREFIX/info] \\
\texttt{-{-}mandir=DIR}         & man documentation [PREFIX/man] \\
\hline
\end{tabular}
\end{center}

Program names:

\begin{center}
\begin{tabular}{|l|p{7cm}|}
\hline
\textbf{Option} & \textbf{Description} \\
\hline
\texttt{-{-}program-prefix=PREFIX}          & prepend PREFIX to installed program names \\
\texttt{-{-}program-suffix=SUFFIX}          & append SUFFIX to installed program names \\
\texttt{-{-}program-transform-name=PROGRAM} & run sed PROGRAM on installed program names \\
\hline
\end{tabular}
\end{center}

System types:

\begin{center}
\begin{tabular}{|l|l|}
\hline
\textbf{Option} & \textbf{Description} \\
\hline
\texttt{-{-}build=BUILD}   & configure for building on BUILD [guessed] \\
\texttt{-{-}host=HOST}     & cross-compile to build programs to run on HOST [BUILD] \\
\texttt{-{-}target=TARGET} & configure for building compilers for TARGET [HOST] \\
\hline
\end{tabular}
\end{center}

Developer options:

\begin{center}
\begin{tabular}{|l|l|}
\hline
\textbf{Option} & \textbf{Description} \\
\hline
\texttt{-{-}enable-shared[=PKGS]}        & build shared libraries [default=no] \\
\texttt{-{-}enable-dependency-tracking} & speeds up one-time build \\
\texttt{-{-}enable-dependency-tracking}  & do not reject slow dependency extractors \\
\texttt{-{-}with-gnu-ld}                 & assume the C compiler uses GNU ld [default=no] \\
\hline
\end{tabular}
\end{center}

\section{Environment variables}

In table \ref{tab:env-summary}, you will find short descriptions of the
most useful variables recognized by the configure script of ABINIT.
Use these variables to override the choices made by \texttt{configure}
or to help it to find libraries and programs with nonstandard
names/locations. Please note that they always have precedence over
command-line options.
\\

\begin{table}
\begin{center}
\begin{tabular}{|l|p{12cm}|}
\hline
\textbf{Option} & \textbf{Description} \\
\hline
AR           & Archiver \\
ARFLAGS      & Archiver flags \\
\hline
CPP          & C preprocessor \\
CPPFLAGS     & C/C++ preprocessor flags, e.g. \texttt{-I$<$include\_dir$>$}
               if you have headers in a non-standard directory named
               \textit{$\mathit{<}$include\_dir$\mathit{>}$} \\
\hline
CC           & C compiler command \\
CFLAGS       & C compiler flags \\
CC\_LDFLAGS  & C link flags to prepend to the command line \\
CC\_LIBS     & Libraries to append when linking a C program \\
\hline
CXX          & C++ compiler command \\
CXXFLAGS     & C++ compiler flags \\
CXX\_LDFLAGS & C++ link flags to prepend to the command line \\
CXX\_LIBS    & Libraries to append when linking a C++ program \\
\hline
FC           & Fortran compiler command \\
FCFLAGS      & Fortran compiler flags \\
FC\_LDFLAGS  & Fortran link flags to prepend to the command line \\
FC\_LIBS     & Libraries to append when linking a Fortran program \\
\hline
\end{tabular}
\end{center}
\caption{Influencial environment variables for the build system of ABINIT.}
\label{tab:env-summary}
\end{table}

There are 2 environment variables of critical importance to the build
system, though they cannot be managed by \textit{configure}:
\begin{itemize}
 \item \textit{PATH}, which defines the order in which the compilers
 will be found, and the number of hits;
 \item \textit{LD\_LIBRARY\_PATH}, which will greatly help the build
 system find usable external libraries, in particular MPI.
\end{itemize}
Improper settings of these 2 variables may cause a great confusion to
the configure script in some cases, in particular when looking for MPI
compilers and libraries. A typical issue encountered is the following
crash:

{\scriptsize
\begin{verbatim}
checking for gcc... /home/pouillon/hpc/openmpi-1.2.4-gcc4.1/bin/mpicc
checking for C compiler default output file name... a.out
checking whether the C compiler works... configure: error: cannot run C compiled programs.
If you meant to cross compile, use `--host'.
See `config.log' for more details.
\end{verbatim}
}

And a look at config.log shows:

{\scriptsize
\begin{verbatim}
...
configure:6613: checking whether the C compiler works
configure:6623: ./a.out
./a.out: error while loading shared libraries: libmpi.so.0: cannot open shared
object file: No such file or directory
configure:6626: $? = 127
configure:6635: error: cannot run C compiled programs.
...
\end{verbatim}
}

This kind of error results from a missing path in the
\textit{LD\_LIBRARY\_PATH} environment variable, and can be solved very
easily, in the present case this way:

{\scriptsize
\begin{verbatim}
export LD_LIBRARY_PATH="/home/pouillon/hpc/openmpi-1.2.4-gcc4.1/lib:${LD_LIBRARY_PATH}"
\end{verbatim}
}

in the case of a BASH shell, and by:

{\scriptsize
\begin{verbatim}
setenv LD_LIBRARY_PATH "/home/pouillon/hpc/openmpi-1.2.4-gcc4.1/lib:${LD_LIBRARY_PATH}"
\end{verbatim}
}

for a C shell.

\section{The configuration process}

Configuring ABINIT is a delicate step-by-step process, because each
component is interacting permanently with most others. This is reflected
in the output of \textit{configure}, that we describe in this section.
\\

The process starts with an overall startup, where the basic parameters
required by Autoconf and Automake are set. During the second part of
this step, the build system of ABINIT reads the options from the command
line and from a config file, making sure that the environment variables
will always have precedence over the command-line options, which in turn
override the options read from the config file. It then reports about
changes in the user interface of the build system, warning the user if
they have used an obsolete option.
\\

The next step is about ensuring the overall consistency of the options
provided to configure. The build system takes the necessary decisions so
that the code may be built safely. It then parses the options, and
issues an error if the user has provided invalid options. The error
messages give all the information needed to fix the problems.
\\

Then comes the MPI startup stage, which the first half of the
configuration of MPI support. This must happen \underline{before} any
Autoconf compiler test, in order to give the build system the
possibility to consistently select the MPI compilers that have been
detected. This step is mandatory to avoid configuration issues later on,
due to mismatches between the sequential and parallel compilers.
\\

The next step is to find the various utilities that the build system may
need along the rest of the configuration process. This runs usually very
smoothly, since these tools are found on most of the platforms ABINIT
runs on.
\\

The preprocessing step is where serious things really start. The C
preprocessor is searched for, which involves in turn the search for a
working C compiler. At this point, all compilers must already have been
selected. This is also typically where \textit{configure} may crash if
the MPI installation detected is broken or misconfigured (see
"Environment variables" section within this chapter), because the C
compiler will not be able to produce executables. This is why MPI
support is disabled by default, and we are open to any suggestion.
\\

The three next steps involve the search for suitable C, C++ and Fortran
compilers, the detection of their type, and the application of tricks to
have them work properly on the user's platform. These are also stages
where the configuration may fail, in particular if no suitable Fortran
compiler is found.
\\

Then the build system configures the use of the archiver, to build the
numerous libraries that are part of ABINIT.
\\

The two next steps are about fine-tuning the compile flags so that the
build will work fine if the architecture is 64-bit (work still in
progress), and to set the adequate level of optimization according to
the platform parameters identified so far.
\\

Here comes the probably most critical step of the configuration: MPI
support. If everything could be set during the MPI startup stage, no
further test is performed, and the parallel code is marked for building.
If not, the build system will try to detect whether the compilers are
able to build MPI source code and set the MPI options accordingly.
\\

Once all this is done, the build system can set the parameters for the
linear algebra and FFT libraries (work still in progress), before
turning to the plug-ins.
\\

One last configuration step is dedicated to the nightly build support,
which is now working but still at an early stage of development.
\\

The very last step is to output the configuration to the numerous
makefiles, as well as to a few other important files. At the end, a
warning is issued if the Fortran compiler in use is known to cause
trouble.
