nearly finished buildsystem howto

[[Imported from SVN: r4515]]

doc/buildsystem/.gitignore

+*.aux
+*.log
+*.dvi
+*.ps
+*.toc
+*.out
+Makefile.in
+Makefile
+auto

doc/buildsystem/buildsystem.tex

@@ -165,9 +165,18 @@ create symlink; this is usually done by \autogen (see
 How to write a \configureac for \dune is described in \ref{configure.ac}
 
 \minisec{libtool}
-
-\libtool is used to build libraries on all platforms. This way we
-don't have to deal will platform specific issues.
+\libtool is a wrapper around the compiler and
+linker. It offers a generic interface for creating static and shared
+libraries, regardless of the platform it is running on.
+
+\libtool hides all the platform specific aspects of library creation
+and library usage. When linking a library or an executable you (or
+\automake) can call the compiler via \libtool. \libtool will then take
+care of
+\begin{itemize}
+\item \em platform specific \em commandline parameters for the linker
+\item library dependencies
+\end{itemize}
 
 \subsection{Makefile.am}
 \label{makefile.am}
@@ -358,10 +367,9 @@ Webpages are created from wml sources, using the program \texttt{wml}
 (\texttt{\url{http://thewml.org/}}).\\
 \texttt{\$(top\_srcdir)/am/webstuff} containes the necessary rules.
 
-
 \begin{lst}[File Makefile.am] \mbox{}
 
-\lstinputlisting[basicstyle=\ttfamily\scriptsize,numbers=left,
+\lstinputlisting[basicstyle=\ttfamily\scriptsize,numbers=none,
 numberstyle=\tiny, numbersep=5pt]{../Makefile.am}
 \end{lst}
 
@@ -386,7 +394,7 @@ and transformed into a shell script.
 
 \begin{lst}[File dune-common/configure.ac] \mbox{}
 
-\lstinputlisting[basicstyle=\ttfamily\scriptsize,numbers=left,
+\lstinputlisting[basicstyle=\ttfamily\scriptsize,numbers=none,
 numberstyle=\tiny, numbersep=5pt]{../../configure.ac}
 \end{lst}
 
@@ -428,6 +436,8 @@ For further information have a look at the autoconf manual \\
 \subsection{autogen.sh}
 \label{autogen.sh}
 
+TODO
+
 \subsection{dunecontrol}
 \label{dunecontrol}
 \dunecontrol helps you building the different \dune modules in the
@@ -442,14 +452,14 @@ and extended in the \dunemodule file.
 
 The commands you are interested in right now are
 \begin{itemize}
-\item \texttt{autogen} runs \autogensh for each module. A list of
+\item \texttt{autogen} runs \autogen for each module. A list of
   directories containing \dunemodule files and the parameters given on
-  the commandline are passed as paramters to \autogensh.
+  the commandline are passed as paramters to \autogen.
 \item \texttt{configure} runs \configure for each
   module. \texttt{--with-dune\textit{module}} parameters are created
   for a set of known \dune modules.
 \item \texttt{make} runs \make for each module.
-\item \texttt{all} runs \autogensh, \configure and \make for each module.
+\item \texttt{all} runs \autogen, \configure and \make for each module.
 \end{itemize}
 
 In order to build \dune the first time you will need the \texttt{all}
@@ -481,27 +491,220 @@ dunecontrol make clean
 
 \minisec{opts files}
 You can also let \dunecontrol read the command parameters from a file.
+For each command you can specify parameters. THe parameters are stored
+in a varible called \texttt{\textit{COMMAND}\,\_FLAGS} with
+\texttt{\textit{COMMAND}} writen in capital letters.
+
+\begin{lst}[File examle.opts] \mbox{}
+\lstinputlisting[basicstyle=\ttfamily\scriptsize,numbers=none,
+numberstyle=\tiny, numbersep=5pt]{../../bin/example.opts}
+\end{lst}
+
+When you specify an opts file and command line paramters
+\begin{lstlisting}[basicstyle=\ttfamily\scriptsize]
+dunecontrol --opts=some.opts configure --with-foo=bar
+\end{lstlisting}
+dunecontrol will ignore the parameters specified in the opts file and
+you will get a warning.
 
 \minisec{dune.module}
 
-\begin{lst}[File dune.module] \mbox{}
+The \dunemodule file is split into two parts. First we have the
+parameter section where you specify parameters describing the module.
+Then we have the command section where you can overload the default
+implementation of a command called via \dunecontrol.
 
-\lstinputlisting[basicstyle=\ttfamily\scriptsize,numbers=left,
-numberstyle=\tiny, numbersep=5pt]{../../dune.module}
+\begin{lst}[File dune.module] \mbox{}
+\begin{lstlisting}[basicstyle=\ttfamily\scriptsize,numbers=none,
+numberstyle=\tiny, numbersep=5pt]
+# paramters for dune control
+Module: dune_grid
+Depends: dune_common
+Suggests: UG Alberta Alu3d
+
+# overload the run_configure command
+run_configure () {
+  # lets extend the paramter list $PARAMS
+  if test "x$HAVE_UG" == "xyes"; then
+    PARAMS="$PARAMS \"--with-ug=$PATH_UG\""
+  fi
+  if test "x$HAVE_Alberta" == "xyes"; then
+    PARAMS="$PARAMS \"--with-alberta=$PATH_Alberta\""
+  fi  
+  if test "x$HAVE_Alu3d" == "xyes"; then
+    PARAMS="$PARAMS \"--with-alberta=$PATH_Alu3d\""
+  fi
+  # call the default implementation
+  run_default_configure
+}
+\end{lstlisting}
 \end{lst}
 
+The parameter section will be parsed by \dunecontrol will affect
+i.e. the order in which the modules are built. The parameters and
+their values are speperated by colon. Possible parameters are
+\begin{itemize}
+\item \texttt{Module} (\em required\em) is the name of the module. The
+  name is of the form \texttt{[a-zA-Z0-9\_]+}.
+\item \texttt{Depends} (\em required\em) takes a space seperated list
+  of required modules. This module is not functional without these
+  other modules.
+\item \texttt{Suggests} (\em optional\em) takes a space seperated list
+  of optional modules. This module is functional without these
+  other modules, but can offer further functionality if one or more of
+  the suggested modules are found.
+\end{itemize}
 
+The command section lets you overload the default implementation
+provided by \dunecontrol. For each command \dunecontrol call the
+function \texttt{run\_\textit{command}}. The parameters from the
+commandline or the opts file are store in the variable
+\texttt{\$PARAMS}. If you just want to create additional parameters
+you can add these to \texttt{\$PARAMS} and then call the default
+implementation of the command via
+\texttt{run\_default\_\textit{command}}.
 
 \section{Creating a new Dune module}
 
+\dune modules are packages that offer a certain functionality that can
+be used by \dune applications. Therefor \dune modules offer libraries
+and/or header files.
+
 In order to create new \dune module, you have to provide 
+\begin{itemize}
+\item a \dunemodule file\\
+  Usually you will only need to specify the parameters \texttt{Module}
+  and \texttt{Depends}.
+\item an \autogen script\\
+  For most of the modules it should be sufficient to copy the \autogen
+  from \dunegrid.
+\item a \configureac file\\
+  Have look at the \configureac in \dunegrid for example. The most
+  important part is the call to \texttt{DUNE\_CHECK\_ALL\_M} which
+  runs all checks needed for a \dune module, plus the checks for the
+  dependencies.
+\end{itemize}
+
+A \dune module should comply with the following rules:
+\begin{itemize}
+\item Documentation is located under \texttt{doc/} and gets
+  web-installed under \texttt{BASEDIR/doc/}.
+\item \automake includes are located in \dunecommon. To use them, you
+  will have to make a symbolic link to \texttt{dune-common/am/}. The
+  symlink creation should be handled by the \autogen.
+\item The \texttt{am/} directory does not get included in the tarball.
+\item Header files that can be used by other \dune modules should be
+  accessible via \verb!#include <dune/foo/bar.hh>!. In order to work
+  with a freshly checkout version of your module you will usually need
+  to create a local symbolic link \texttt{dune ->
+    \textit{module-direcotry/}}. This link gets created by the
+  \texttt{DUNE\_CHECK\_ALL\_M} command of your \configureac. When running
+  \texttt{make install} all header files should be installed into
+  \texttt{\textit{prefix}/include/dune/}.
+\end{itemize}
 
 \section{Creating a new Dune application}
 
+A \dune application does not differ a lot from a \dune module.
+The only difference is that it does not offer functionality to other
+\dune projects. This make somethings a little bit easier.
 
-\section{Futher questions}
+In order to create new \dune module, you have to provide 
+\begin{itemize}
+\item a \dunemodule file\\
+  Usually you will only need to specify the parameters \texttt{Module}
+  and \texttt{Depends}.
+\item an \autogen script\\
+  For most of the application the \autogen following further below
+  should be sufficient.
+\item a \configureac file\\
+  The \configureac looks more less the same as for a \dune module
+  except that you call \texttt{DUNE\_CHECK\_ALL} instead of
+  \texttt{DUNE\_CHECK\_ALL\_M}.
+\end{itemize}
 
+\begin{lst}{Example autogen.sh for a \dune application}
+\label{example_autogen.sh}
+\begin{lstlisting}[basicstyle=\ttfamily\scriptsize]
+#!/bin/sh
+
+set -e
+
+usage () {
+    echo "Usage: ./autogen.sh [options]"
+    echo "  --ac=, --acversion=VERSION   use a specific VERSION of autoconf"
+    echo "  --am=, --amversion=VERSION   use a specific VERSION of automake"
+    echo "  -h,    --help                you already found this :-)"
+}
 
+for OPT in "$@"; do
+    set +e
+    # stolen from configure...
+    # when no option is set, this returns an error code
+    arg=`expr "x$OPT" : 'x[^=]*=\(.*\)'`
+    set -e
+
+    case "$OPT" in
+	--ac=*|--acversion=*)
+			if test "x$arg" == "x"; then
+				usage; 
+				exit 1;
+			fi
+			ACVERSION=$arg
+			;;
+	--am=*|--amversion=*)
+			if test "x$arg" == "x"; then
+				usage; 
+				exit 1;
+			fi
+			AMVERSION=$arg
+			;;
+	-h|--help) usage ; exit 0 ;;
+	*)
+            if test -f "$OPT/m4"; then
+              ACLOCAL_FLAGS="$ACLOCAL_FLAGS -I $(cd $OPT/m4; pwd)"
+            fi
+            if test -d "$OPT/am"; then
+              am_dir="$OPT/am"
+            fi
+            ;;
+    esac
+done
+
+if test x$1 = "x" ; then
+  usage
+  exit 0
+fi
+
+if test "x$ACLOCAL_FLAGS" = "x"; then
+  echo dune-common/m4 not found. Please supply directory!
+  usage
+  exit 1
+fi
+
+if test -d m4 ; then
+  ACLOCAL_FLAGS="$ACLOCAL_FLAGS -I m4"
+fi
+
+if test "x$AMVERS" != x ; then
+  echo Warning: explicitly using automake version $AMVERS
+  # binaries are called automake-$AMVERS
+  AMVERS="-$AMVERS"
+fi
+
+aclocal$AMVERSION $ACLOCAL_FLAGS
+
+libtoolize --automake --force
+
+autoheader$ACVERSION
+
+automake$AMVERSION --add-missing
+
+autoconf$ACVERSION
+\end{lstlisting}
+\end{lst}
+
+\section{Futher questions}
 
 \end{document}