\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});
 }
 \item
 M4 scripting \\
 (\url{http://en.wikipedia.org/wiki/M4_%28computer_language%29});
 \item
 Makefile writing \\
 (\url{http://en.wikipedia.org/wiki/Makefile});
 \item
 Link editing \\
 (\url{http://en.wikipedia.org/wiki/Linker});
 \item
 Regular expression designing \\
 (\url{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$ \url{http://www.gnu.org/software/autoconf/manual/}
 \item
 Automake
 $\longrightarrow$ \url{http://sources.redhat.com/automake/automake.html}
 \item
 Libtool
 $\longrightarrow$ \url{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
(\url{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{\~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{\~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 "\texttt{do-not-edit-}".

\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{\~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 spine 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
\underline{\textbf{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 \underline{\textbf{for
sure}} lead to catastrophic consequences, and may even result in massive
loss of data. To summarize, \textcolor{red}{\textbf{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 \textit{Autoconf}. As such, \textbf{\textit{configure} should
\underline{NEVER EVER} been edited}.

