
\chapter{Preprocessing macros}


\section{Propagating information to the source code}

While many arguments of the configure script control the way ABINIT
is built, some of them -{-}- in addition to the results of the tests
performed at configure-time -{-}- greatly influence \underline{what}
will be built. In the latter case, the information has to be propagated
up to the source code, which is done by means of preprocessing macros.
They are created by the \texttt{AC\_DEFINE} macro of Autoconf, or
specified by the user on the command line. \\


Macros are \textit{(name,value)} pairs allowing the mapping of a sequence
to another. Names are usually single words, while values usually range
from simple numbers to very complex sequences of instructions. During
compilation, \textit{name} is replaced by \textit{value} every time
it is encountered, this process being called \textit{macro expansion}.
Special lines, starting with the '\#' character in C, allow for more
operations on macros, like setting, unsetting or tests. Last but not
least, the concept of macro is not limited to any programming language,
and macros are indeed ubiquitous in the programming world. \\


The build of ABINIT leads to the creation of many preprocessing macros
(73 in ABINIT 5.5), which are stored in \textit{config.h}. Besides
command-line options, this file is the only link between the build
system and the source code of ABINIT, and this is the reason why all
of them must include it at their very beginning.


\section{Naming conventions}

As far as preprocessing directive names are concerned, ABINIT abides
strictly by the GNU Coding Standards. This means in particular that: 
\begin{itemize}
\item all user-defined compiler directives must be upper case; 
\item all names must start with a letter; 
\item names may contain capital letters, digits and underscores only; 
\end{itemize}
Directives related to features that may or may not be present depending
on the configuration must begin by the keyword \textit{HAVE\_{*}},
e.g. \textit{HAVE\_CONFIG\_H}, \textit{HAVE\_NETCDF}, \textit{HAVE\_ETSF\_XC},
etc.


\section{If statements}

\textit{If} statements should all begin with '\texttt{\#if}'. We kindly
ask you not to use '\texttt{\#ifdef}', but \hbox{'\texttt{\#if defined}'}
instead. A line ending an \textit{if} statement must contain the '\texttt{\#endif}'
keyword only. The same holds for '\texttt{\#else}'. \\


Here is a typical example:

{\small \begin{verbatim} \#if defined HAVECONFIGH \#include \textquotedbl{}config.h\textquotedbl{}
\#endif \end{verbatim} }{\small \par}

We thank you in advance for following these simple rules, as it will
greatly simplify the automatic checks and fixes of the source code.


\section{Preprocessing macros of ABINIT 5}


\subsection{Generic macros}

\begin{center}
\begin{tabular}{ll}
CONTRACT  & Design-by-contract code \tabularnewline
HAVE\_CONFIG\_H  & Mandatory: use config.h if present \tabularnewline
\end{tabular}
\par\end{center}


\subsection{Architecture-related macros}

\begin{center}
\begin{tabular}{ll}
OS\_IRIX  & IRIX operating system \tabularnewline
OS\_LINUX  & Linux operating system \tabularnewline
OS\_MACOSX  & Mac OS X operating system \tabularnewline
OS\_WINDOWS  & DOS/Windows operating system \tabularnewline
VMS  & VAX/VMS architecture \tabularnewline
\end{tabular}
\par\end{center}


\subsection{Optional library macros}

\begin{center}
\begin{tabular}{ll}
HAVE\_COMPAQ\_FFT  & HP/Compaq/DEC FFT library \tabularnewline
HAVE\_FFTW  & FFTW library \tabularnewline
HAVE\_FFTWTHREADS  & FFTW library (threaded version) \tabularnewline
HAVE\_FFTW3  & FFTW3 library \tabularnewline
HAVE\_FFTW3THREADS  & FFTW3 library (threaded version) \tabularnewline
\hline 
HAVE\_HP\_MLIB  & HP mathematical library \tabularnewline
HAVE\_SCALAPACK  & SCALAPACK linear algebra library \tabularnewline
HAVE\_SGI\_MATH  & SGI mathematical library \tabularnewline
HAVE\_IBM\_ESSL  & IBM mathematical library \tabularnewline
HAVE\_IBM\_ESSL\_OLD  & IBM mathematical library (old version) \tabularnewline
HAVE\_NEC\_ASL  & NEC mathematical library \tabularnewline
\hline 
HAVE\_NETCDF  & NetCDF file I/O library \tabularnewline
\hline 
HAVE\_BIGDFT  & BigDFT wavelet library \tabularnewline
HAVE\_ETSF\_IO  & ETSF file I/O library \tabularnewline
HAVE\_FOX  & Fortran XML I/O library \tabularnewline
HAVE\_LIBXC  & Octopus exchange-correlation library \tabularnewline
\end{tabular}
\par\end{center}


\subsection{MPI macros}

MPI macros may not be included in the \textit{config.h} file, as it
would preclude the build of sequential code. They should be specified
within the compiler command line. The following table gives the full
list of permitted MPI macros and the way they are managed. Manual
handling is done through the \textit{-{-}with-mpi-cppflags} option
of configure.

\begin{center}
\begin{tabular}{|l|l|l|}
\hline 
\textbf{Option}  & \textbf{Description}  & \textbf{Management} \tabularnewline
\hline 
MPI  & MPI statements follow  & Build system \tabularnewline
\hline 
MPI1  & MPI version 1  & Manual \tabularnewline
MPI2  & MPI version 2  & Manual \tabularnewline
MPI3  & MPI version 3  & Manual \tabularnewline
\hline 
MPI\_EXT  & MPI HTOR routines (?)  & Manual \tabularnewline
MPI\_FFT  & Parallel FFT  & Build system \tabularnewline
MPI\_IO  & Parallel I/O  & Build system \tabularnewline
MPI\_TRACE  & Timing within parallel routines  & Build system \tabularnewline
\hline
\end{tabular}
\par\end{center}


\subsection{Compiler macros}

\begin{center}
\begin{tabular}{ll}
FC\_ABSOFT  & ABSoft Fortran compiler \tabularnewline
FC\_COMPAQ  & HP/Compaq/DEC Fortran compiler \tabularnewline
FC\_FUJITSU  & Fujitsu Fortran compiler \tabularnewline
FC\_GNU  & GNU Fortran compiler (gfortran) \tabularnewline
FC\_G95  & G95 Fortran compiler (g95) \tabularnewline
FC\_HITACHI  & Hitachi Fortran compiler \tabularnewline
FC\_HP  & HP Fortran compiler \tabularnewline
FC\_IBM  & IBM XL Fortran compiler \tabularnewline
FC\_INTEL  & Intel Fortran compiler \tabularnewline
FC\_MIPSPRO  & SGI MipsPro Fortran compiler \tabularnewline
FC\_NAG  & NAGWare Fortran compiler \tabularnewline
FC\_NEC  & NEC Fortran compiler \tabularnewline
FC\_PGI  & PGI Fortran compiler \tabularnewline
FC\_SUN  & Sun Fortran compiler \tabularnewline
\end{tabular}
\par\end{center}

The same holds for C and C++ compilers.


\subsection{Fortran-specific macros}

\begin{center}
\begin{tabular}{ll}
HAVE\_FORTRAN\_EXIT  & The Fortran compiler accepts exit() \tabularnewline
USE\_CCLOCK  & Use C clock for timings \tabularnewline
\end{tabular}
\par\end{center}


\subsection{Renamed macros}

\begin{center}
\begin{tabular}{|l|l|l|}
\hline 
\textbf{Option}  & \textbf{Replaced by}  & \textbf{Version} \tabularnewline
\hline 
\_\_IFC  & FC\_INTEL  & 5.1 \tabularnewline
ibm  & FC\_IBM  & 5.1 \tabularnewline
NAGf95  & FC\_NAG  & 5.1 \tabularnewline
\hline 
mpi  & MPI  & 5.1 \tabularnewline
MPIEXT  & MPI\_EXT  & 5.1 \tabularnewline
TRACE  & MPI\_TRACE  & 5.1 \tabularnewline
\hline 
FFTW  & HAVE\_FFTW  & 5.1 \tabularnewline
FFTWTHREADS  & HAVE\_FFTWTHREADS  & 5.1 \tabularnewline
\hline 
bim  & HAVE\_IBM\_ESSL  & 5.1 \tabularnewline
bmi  & HAVE\_IBM\_ESSL  & 5.1 \tabularnewline
cen  & HAVE\_NEC\_ASL, FC\_NEC  & 5.1 \tabularnewline
dec\_alpha  & FC\_COMPAQ  & 5.1 \tabularnewline
hp  & HAVE\_HP\_MLIB, FC\_HP  & 5.1 \tabularnewline
hpux  & HAVE\_HP\_MLIB  & 5.1 \tabularnewline
nec  & HAVE\_NEC\_ASL, FC\_NEC  & 5.1 \tabularnewline
nolib  & HAVE\_COMPAQ\_FFT  & 5.1 \tabularnewline
sgi  & HAVE\_SGI\_MATH, FC\_MIPSPRO  & 5.1 \tabularnewline
sr8k  & FC\_HITACHI  & 5.1 \tabularnewline
vpp  & FC\_FUJITSU  & 5.1 \tabularnewline
\hline 
\_\_VMS  & VMS  & 5.1 \tabularnewline
P6  & i386  & 5.1 \tabularnewline
macosx  & OS\_MACOSX  & 5.1 \tabularnewline
\hline 
CHGSTDIO  & READ\_FROM\_FILE  & 5.1 \tabularnewline
\hline
\end{tabular}
\par\end{center}


\subsection{Unmaintained macros}

\begin{center}
\begin{tabular}{ll}
OPENMP  & OpenMP parallelism \tabularnewline
T3E  & Cray T3E architecture \tabularnewline
TEST\_AIM  & Optional checks for AIM \tabularnewline
\end{tabular}
\par\end{center}


\subsection{Removed macros}

The following preprocessing macros have been removed from the ABINIT
source code.

\begin{center}
\begin{tabular}{|l|l|p{9cm}|}
\hline 
\textbf{Option}  & \textbf{Last version}  & \textbf{Comments} \tabularnewline
\hline 
OLD\_INIT  & 4.6  & Was used in \textit{src/04wfs/wfconv.F90} to initialize the wavefunctions,
and has been replaced for a long time by a more efficient method. \tabularnewline
\hline 
PGIWin  & 4.6  & The PGI Fortran compiler is no longer used to build Abinit under Windows,
since it is too buggy. \tabularnewline
\hline 
ultrix  & 4.6  & Ultrix was an operating system based on a 4.2BSD Unix with some features
from System V. It was first released in 1984. Its purpose was to provide
a DEC-supported native Unix for VAX. The last major release of Ultrix
was version 4.5 in 1995, which supported DECstations and VAXen. There
were some subsequent Y2K patches. There has been no ABINIT user on
Ultrix quite some time. \tabularnewline
\hline
\end{tabular}
\par\end{center}
