
\chapter{Extending the build system}


\section{Prerequisites}

In order to efficiently tweak the build system, you will need to have
a good experience of some basic Unix utilities: \textit{cat}, \textit{grep},
\textit{sed}, \textit{awk}, \textit{cut}, \textit{tr}, \textit{tee},
\textit{wc}. A long familiarity with ABINIT and an active participation
to the developments occuring within the last six months, though mandatory,
will not suffice. You should already be fluent in the following areas
as well: 
\begin{itemize}
\item Bourne-type shell scripting \\
 (\url{http://en.wikipedia.org/wiki/Bourne_shell}); 
\item Perl scripting \\
 (\url{http://en.wikipedia.org/wiki/Perl}); 
\item Python scripting \\
 {\small (\url{http://en.wikipedia.org/wiki/Python_%28programming_language%29}
);}{\small \par}
\item {\small M4 scripting }\\
{\small{} (\url{http://en.wikipedia.org/wiki/M4_%28computer_language%29});}{\small \par}
\item Makefile writing\\
(\href{http://en.wikipedia.org/wiki/Makefile}{http://en.wikipedia.org/wiki/Makefile});
\item Link editing\\
(\href{http://en.wikipedia.org/wiki/Linker}{http://en.wikipedia.org/wiki/Linker});
\item Regular expression designing\\
(\href{http://en.wikipedia.org/wiki/Regular_expression}{http://en.wikipedia.org/wiki/Regular\_{}expression}).
\end{itemize}
Just as when developing for ABINIT, you will need a fully working
installation of the GNU Autotools. And here is what distinguishes
the maintainer from the developer: you will need to know how they
work and understand their principles. Their respective documentations
may be found at the following addresses:
\begin{itemize}
\item Autoconf $\longrightarrow$ \href{http://www.gnu.org/software/autoconf/manual/}{http://www.gnu.org/software/autoconf/manual/}
\item Automake $\longrightarrow$ \href{http://sources.redhat.com/automake/automake.html}{http://sources.redhat.com/automake/automake.html}
\item Libtool $\longrightarrow$ \href{http://www.gnu.org/software/libtool/manual.html}{http://www.gnu.org/software/libtool/manual.html}
\end{itemize}
We strongly urge you to read them if you want to know what you are
doing.\\


Last but not least, you will need to have Bazaar (\href{http://bazaar-vcs.org/}{http://bazaar-vcs.org/})
installed on your development machine, since the delicate character
of your contributions will require real-time interactions with other
maintainers and/or developers, be it for bug fixing or testing.


\section{Adding scripts}

If your extension influences exclusively the pre-build stage of ABINIT,
i.e. it prepares the way for the Autotools, you may add it in the
form of a script in \textit{\textasciitilde{}abinit/config/scripts/}.
Please follow the conventions already adopted for the other scripts.
When done, do not forget to add a call to your script in \textit{\textasciitilde{}abinit/config/scripts/makemake},
and remember that \textit{makemake} expects to be called from the
top-level directory of the source tree.\\


If your script is producing M4 macros, the names of the files containing
them must be prefixed by \textquotedbl{}auto-\textquotedbl{}.


\section{Adding M4 macros}

When you want to propagate information up to the Makefiles of ABINIT,
the recommended way to extend the build system is by writing M4 macros.
The best practice is to create a new file in \textit{\textasciitilde{}abinit/config/m4/},
following the conventions adopted for the other files. If at a later
time your contribution is approved, it may be redispatched into other
files.


\section{Editing \textit{configure.ac}}

The \textit{configure.ac} file is the spinal cord of the build system.
Every single character of this file plays a well-defined role, and
is present for a carefully-thought logical reason. In particular,
the order of the lines is of critical importance to the proper functioning
of the whole build system. That is why this file should only be edited
with \textbf{\underbar{extreme care}} by persons having a good knowledge
of shell-scripts, M4, Autoconf, Automake, Libtool and the ABINIT build
system. Messing-up with the instructions present there without a sufficient
experience in these matters will \textbf{\underbar{for sure}} lead
to catastrophic consequences, and may even result in massive loss
of data. To summarize, \textbf{\textcolor{red}{YOU EDIT THIS FILE
AT YOUR OWN RISKS}}. Believing you are more clever than the designers
of the ABINIT build system will not save you.\\


The \textit{configure} script is generated from \textit{configure.ac}
by Autoconf. As such, \textit{configure} should \textbf{\underbar{NEVER
EVER}} been edited. 
