\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 HAVE_CONFIG_H
    #include "config.h"
    #endif
\end{verbatim}
}

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}{l l}
  CONTRACT & Design-by-contract code \\
  HAVE\_CONFIG\_H & Mandatory: use config.h if present \\
 \end{tabular}
\end{center}



\subsection{Architecture-related macros}

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



\subsection{Optional library macros}

\begin{center}
 \begin{tabular}{l l}
  HAVE\_COMPAQ\_FFT & HP/Compaq/DEC FFT library  \\
  HAVE\_FFTW & FFTW library \\
  HAVE\_FFTWTHREADS & FFTW library (threaded version) \\
  \hline
  HAVE\_HP\_MLIB & HP mathematical library \\
  HAVE\_SCALAPACK & SCALAPACK linear algebra library \\
  HAVE\_SGI\_MATH & SGI mathematical library \\
  HAVE\_IBM\_ESSL & IBM mathematical library \\
  HAVE\_IBM\_ESSL\_OLD & IBM mathematical library (old version) \\
  HAVE\_NEC\_ASL & NEC mathematical library \\
  \hline
  HAVE\_NETCDF & NetCDF file I/O library \\
  \hline
  HAVE\_BIGDFT & BigDFT wavelet library \\
  HAVE\_ETSF\_IO & ETSF file I/O library \\
  HAVE\_ETSF\_XC & ETSF exchange-correlation library \\
  HAVE\_XMLF90 & XML Fortran I/O library \\
 \end{tabular}
\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} \\
  \hline
  MPI & MPI statements follow & Build system \\
  \hline
  MPI1 & MPI version 1 & Manual \\
  MPI2 & MPI version 2 & Manual \\
  MPI3 & MPI version 3 & Manual \\
  \hline
  MPI\_EXT & MPI HTOR routines (?) & Manual \\
  MPI\_FFT & Parallel FFT & Build system \\
  MPI\_IO & Parallel I/O & Build system \\
  MPI\_TRACE & Timing within parallel routines & Build system \\
  \hline
 \end{tabular}
\end{center}



\subsection{Compiler macros}

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

The same holds for C and C++ compilers.



\subsection{Fortran-specific macros}

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



\subsection{Renamed macros}

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



\subsection{Unmaintained macros}

\begin{center}
 \begin{tabular}{l l}
  OPENMP & OpenMP parallelism \\
  T3E & Cray T3E architecture \\
  TEST\_AIM & Optional checks for AIM \\
 \end{tabular}
\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} \\
  \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. \\
  \hline
  PGIWin & 4.6 &
  The PGI Fortran compiler is no longer used to build Abinit under
  Windows, since it is too buggy. \\
  \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. \\
  \hline
 \end{tabular}
\end{center}

