From 6eea4d89a2a527234793178635478c3cf4e83311 Mon Sep 17 00:00:00 2001
From: Christian Engwer <christi@dune-project.org>
Date: Wed, 8 Sep 2010 09:28:58 +0000
Subject: [PATCH] documentation on {MODULE}_CHECK_MODULE * make the
documentation appear more promimently * link from different parts * add some
more details to the example
[[Imported from SVN: r6121]]
---
doc/buildsystem/buildsystem.tex | 27 ++++++++++++++++++++++-----
1 file changed, 22 insertions(+), 5 deletions(-)
diff --git a/doc/buildsystem/buildsystem.tex b/doc/buildsystem/buildsystem.tex
index a77316751..f7a41c662 100644
--- a/doc/buildsystem/buildsystem.tex
+++ b/doc/buildsystem/buildsystem.tex
@@ -91,7 +91,7 @@ application and a \dune module.\\
\dune modules are packages that offer a certain functionality that can
be used by \dune applications. Therefore \dune modules offer libraries
and/or header files. A \dune module needs to comply with certain rules
-(see \ref{guidelines}).
+(see~\ref{guidelines}).
Creating a new \dune project has been covered in detail in
\ref{section::creating_dune_module} using \texttt{duneproject} to take
@@ -105,7 +105,7 @@ the bare minimum you have to provide in order to create a new project:
\item \emph{Note:} an \autogen script is \emph{not} needed any more!
\item a basic m4 file\\
You need to provide two macros \texttt{\emph{MODULE}\_CHECKS}
- and \texttt{\emph{MODULE}\_CHECK\_MODULE}.
+ and \texttt{\emph{MODULE}\_CHECK\_MODULE} (see~\ref{m4files}).
\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} which
@@ -257,8 +257,12 @@ A \dune module should comply with the following rules:
\item \automake includes are located in \dunecommon. To use them, you
will have to make a symbolic link to \texttt{dune-common/am/} (see
\ref{am_includes}). The symlink creation should be handled by the
- \autogen (see \ref{autogen}).
+ \autogen (see~\ref{autogen}).
\item The \texttt{am/} directory does not get included in the tarball.
+\item Additional configure tests are located in the \texttt{m4/}
+ directory. You should at least provide the macros \texttt{\emph{MODULE}\_CHECKS}
+ and \texttt{\emph{MODULE}\_CHECK\_MODULE}, in order to setup and
+ find your module (see~\ref{m4files}).
\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
@@ -1145,12 +1149,12 @@ tarball. That means it runs all necessary steps so that you can call
\end{itemize}
If needed it will also create the symbolic link to the
-\texttt{dune-common/am/} directory (see \ref{am_includes}).
+\texttt{dune-common/am/} directory (see~\ref{am_includes}).
\subsection{m4 files}
\label{m4files}
-\texttt{m4} files contain macros which are then composed into
+\texttt{m4/} files contain macros which are then composed into
\configure and are run during execution of \configure.
\minisec{private m4 macros}
@@ -1164,6 +1168,7 @@ in the directory \texttt{module/m4/}.
dependencies and suggestions of this module. It is an automatically
generated file. It is generated by \texttt{dunecontrol m4create}.
+\minisec{m4 module checks}
For each dependencies of your module \texttt{\emph{MODULE}\_CHECKS}
and \texttt{\emph{MODULE}\_CHECK\_MODULE} is called. Last
\texttt{\emph{MODULE}\_CHECKS} is called for your module, in order to
@@ -1177,7 +1182,19 @@ written to a \texttt{m4/*.m4} file.
Here follows an example for the module \texttt{dune-foo}:
\begin{lstlisting}
+dnl -*- autoconf -*-
+# Macros needed to find dune-foo and dependent libraries. They are
+# called by the macros in ${top_src_dir}/dependencies.m4, which is
+# generated by "dunecontrol autogen"
+
+# Additional checks needed to build dune-foo
+# This macro should be invoked by every module which depends on
+# dune-foo, as well as by dune-foo itself
AC_DEFUN([DUNE_FOO_CHECKS])
+
+# Additional checks needed to find dune-foo
+# This macro should be invoked by every module which depends on dumux, but
+# _not_ by dune-foo itself
AC_DEFUN([DUNE_FOO_CHECK_MODULE],[
DUNE_CHECK_MODULES([dune-foo], dnl module name
[foo/foo.hh], dnl header file
--
GitLab