[Dune] [Dune-Commit] dune-common r5239 - trunk/doc/buildsystem
Christian Engwer
christi at uni-hd.de
Sat Jul 5 10:02:11 CEST 2008
> das Packages svninfo scheint nicht bei jeder Linux-Distribution vorhanden
> zu sein. Ich würde vorschlagen, entweder darauf zu verzichten, oder es mit
> einzuchecken
Please mind that the list language is english.
You are right, svninfo has the draw back that it is not necessarily
available on for latex distributions. I update the file such that the
date has to me set manually.
> (und zwar so, dass es auch benutzt wird).
??? I don't think I understand what you are trying to tell me here :-(
Christian
> Viele Grüße,
>
> Martin
>
> christi at dune-project.org wrote:
> >Author: christi
> >Date: 2008-07-04 18:22:42 +0200 (Fri, 04 Jul 2008)
> >New Revision: 5239
> >
> >Modified:
> > trunk/doc/buildsystem/buildsystem.tex
> >Log:
> >updated the buildsystem howto to the latest buildsystem changes
> >
> >Modified: trunk/doc/buildsystem/buildsystem.tex
> >===================================================================
> >--- trunk/doc/buildsystem/buildsystem.tex 2008-07-04 16:22:21 UTC (rev
> >5238)
> >+++ trunk/doc/buildsystem/buildsystem.tex 2008-07-04 16:22:42 UTC (rev
> >5239)
> >@@ -1,4 +1,5 @@
> > \documentclass[11pt,a4paper,headinclude,footinclude,DIV16,normalheadings]{scrartcl}
> >+\usepackage[today,nofancy]{svninfo}
> > \usepackage[automark]{scrpage2}
> > \usepackage[ansinew]{inputenc}
> > %\usepackage{german}
> >@@ -6,14 +7,13 @@
> > \usepackage{amsmath}
> > \usepackage{amsfonts}
> > \usepackage{theorem}
> >+\usepackage{pst-all}
> > \usepackage{color}
> > \usepackage{listings}
> > \lstset{language=bash, basicstyle=\normalfont\ttfamily\scriptsize,
> > keywordstyle=\color{black}\bfseries, tabsize=4,
> > stringstyle=\ttfamily, commentstyle=\it, extendedchars=true}
> > \usepackage{hyperref}
> >-\usepackage{psfrag}
> >-\usepackage{pstricks}
> > \usepackage{makeidx}
> > \usepackage{xspace}
> >
> >@@ -24,7 +24,7 @@
> > \newcommand{\dune}{\texttt{DUNE}\xspace}
> > \newcommand{\autoconf}{\texttt{autoconf}\xspace}
> > \newcommand{\automake}{\texttt{automake}\xspace}
> >-\newcommand{\autogen}{\texttt{autogen.sh}\xspace}
> >+\newcommand{\autogen}{\texttt{dune-autogen}\xspace}
> > \newcommand{\libtool}{\texttt{libtool}\xspace}
> > \newcommand{\configure}{\texttt{configure}\xspace}
> > \newcommand{\configureac}{\texttt{configure.ac}\xspace}
> >@@ -38,6 +38,7 @@
> > \newcommand{\dunecontrol}{\texttt{dunecontrol}\xspace}
> > \newcommand{\dunemodule}{\texttt{dune.module}\xspace}
> > \newcommand{\make}{\texttt{make}\xspace}
> >+\newcommand{\topsrc}{\$(top\_srcdir)}
> >
> > \pagestyle{scrheadings}
> >
> >@@ -45,7 +46,7 @@
> >
> > \author{Christian Engwer$^\ast$}
> >
> >-\date{\today}
> >+\date{\svnToday}
> >
> > \publishers{%
> > {\normalsize $^\ast$Interdisziplin???res Zentrum f???r Wissenschaftliches
> > Rechnen,
> >@@ -154,7 +155,7 @@
> > \ref{am_includes}). The \texttt{am} directory is in the \dunecommon
> > module and each module intending to use one of these includes has to
> > create symlink; this is usually done by \autogen (see
> >-\ref{autogen.sh}).
> >+\ref{autogen}).
> >
> > \begin{center}
> > \psset{unit=0.5mm}
> >@@ -440,22 +441,30 @@
> > We offer a set of macros that can be used in your \configureac:
> >
> > \begin{itemize}
> >-\item \texttt{DUNE\_CHECK\_ALL\_M}
> >- runs all checks usually needed by a {\em \dune module}.
> >- This macros takes list of other \dune modules it should search for
> >- as parameters.
> >-\begin{lstlisting}[language=make]
> >-DUNE_CHECK_ALL_M([dunecommon], [dunegrid])
> >-\end{lstlisting}
> >- will search for \texttt{dune-common} and \texttt{dune-grid}
> >- (Attention: you have to provide the modules in such an order that
> >- the dependencies are checked already).
> > \item \texttt{DUNE\_CHECK\_ALL}
> >- same as \texttt{DUNE\_CHECK\_ALL\_M}, except that it only runs the
> >- tests needed for a {\em \dune application}
> >+ runs all checks usually needed by a {\em \dune module}.
> >+ It checks for all dependencies and suggestions and for their
> >+ prerequisites.
> >+ In order to make the dependencies knwon to \configure \autogen calls
> >+ \texttt{dunecontrol m4create} and write a file
> >+ \texttt{dependencies.m4}.
> >+\item \texttt{DUNE\_SYMLINK}
> >+ creates symlink \texttt{\$(top\_srcdir)/dune} $\rightarrow$
> >+ \texttt{\$(top\_srcdir)}. The programming guidelines (\ref{guidelines})
> >+ require that the include statements be like \texttt{\#include
> >+ <dune/...>}. If your module has a directory structure
> >+ \texttt{\topsrc/foo}, you will need such a link. However, you are
> >+ encouraged to store the files directly in a directory structure
> >+ \texttt{\topsrc/dune/foo} in order to avoid any inconvience when
> >+ copying the files. This will also eliminate the necessity for
> >+ \texttt{DUNE\_SYMLINK}.
> >+\item \texttt{DUNE\_AUTOBUILD\_FLAGS}
> >+ adds configure flags needed to create log files for
> >+ \texttt{dune-autobuild}. If you want to add your module to the
> >+ \texttt{dune-autobuild} system, you have to call this macro.
> > \item \texttt{DUNE\_SUMMARY\_ALL}
> > prints information on the results of all major checks run by
> >- \texttt{DUNE\_CHECK\_ALL} or \texttt{DUNE\_CHECK\_ALL\_M}.
> >+ \texttt{DUNE\_CHECK\_ALL}.
> > \end{itemize}
> >
> > \texttt{DUNE\_CHECK\_ALL} and \texttt{DUNE\_CHECK\_ALL\_M} define certain
> >@@ -485,8 +494,8 @@
> > After you told \autoconf which files to create you have to actually
> > trigger their creation with command \texttt{AC\_OUTPUT}
> >
> >-\subsection{autogen.sh}
> >-\label{autogen.sh}
> >+\subsection{dune-autogen}
> >+\label{autogen}
> >
> > The \autogen script is used to bring the freshly checked out module
> > into that state that you expect from a module received via the
> >@@ -495,6 +504,8 @@
> > \autogen runs
> > \begin{itemize}
> > \item \texttt{libtoolize} (prepare the module for \libtool)
> >+\item \texttt{dunecontrol m4create} (create an m4 file containing the
> >+ dependencies of this module)
> > \item \texttt{aclocal} (collect all \autoconf macros needed for this
> > module)
> > \item \texttt{autoheader} (create the \texttt{config.h.in})
> > \item \texttt{automake} (create the \makefilein)
> >@@ -504,6 +515,53 @@
> > If needed it will also create the symbolic link to the
> > \texttt{dune-common/am/} directory (see \ref{am_includes}).
> >
> >+\subsection{m4 files}
> >+\label{m4files}
> >+
> >+\texttt{m4} files contain macros which are then composed into
> >+\configure and are run during execution of \configure.
> >+
> >+\minisec{private m4 macros}
> >+
> >+You can add new tests to configure by providing additional macro files
> >+in the directory \texttt{module/m4/}.
> >+
> >+\minisec{dependencies.m4}
> >+
> >+\texttt{\topsrc/dependencies.m4} hold all information about the
> >+dependencies and suggestions of this module. It is an automatically
> >+generated file. It is generated by \texttt{dunecontrol m4create}.
> >+
> >+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
> >+check all prerequisites for your module.
> >+
> >+What you just read implies that you have to provide the two macros
> >+\texttt{\emph{MODULE}\_CHECKS} and
> >+\texttt{\emph{MODULE}\_CHECK\_MODULE} for your module. These should be
> >+written to a \texttt{m4/*.m4} file.
> >+
> >+Here follows an example for the module \texttt{dune-foo}:
> >+
> >+\begin{lstlisting}
> >+AC_DEFUN([DUNE_FOO_CHECKS])
> >+AC_DEFUN([DUNE_FOO_CHECK_MODULE],[
> >+ DUNE_CHECK_MODULES([dune-foo], dnl module name
> >+ [foo/foo.hh], dnl header file
> >+ [Dune::FooFnkt]) dnl symbol in libdunefoo
> >+])
> >+\end{lstlisting}
> >+
> >+The first one calls all checks required to make use of
> >+\texttt{dune-foo}. The dependency checks are not to be included, they
> >+are run automatically. The second macro tells how to check for your
> >+module. In case you are only writing an application and don't want to
> >+make this module available to other modules, you can just leave it
> >+empty. If you have to provide some way to find your module. The
> >+easiest is to use the \texttt{DUNE\_CHECK\_MODULES} macro, which is
> >+defined in \texttt{dune-common/m4/dune.m4}.
> >+
> > \subsection{dunecontrol}
> > \label{dunecontrol}
> > \dunecontrol helps you building the different \dune modules in the
> >@@ -576,6 +634,11 @@
> > You can further control the behavior of \dunecontrol by certain
> > environment variables.
> > \begin{itemize}
> >+\item \texttt{DUNE\_CONTROL\_PATH} specifies the paths, where
> >+ \dunecontrol is searcing for modules. All entries have to be colon
> >+ seperated and should point to either a directory (which is search
> >+ recursively for \texttt{dune.module} files) or a directly
> >+ \texttt{dune.module} file.
> > \item \texttt{DUNE\_OPTS\_FILE} specifies the opts file that should be
> > read by dunecontrol. This variable will be overwritten by the
> > \texttt{--opts=} option.
> >@@ -609,7 +672,7 @@
> > PARAMS="$PARAMS \"--with-alberta=$PATH_Alberta\""
> > fi
> > if test "x$HAVE_Alu3d" == "xyes"; then
> >- PARAMS="$PARAMS \"--with-alberta=$PATH_Alu3d\""
> >+ PARAMS="$PARAMS \"--with-alugrid=$PATH_Alu3d\""
> > fi
> > # call the default implementation
> > run_default_configure
> >@@ -641,27 +704,43 @@
> > implementation of the command via
> > \texttt{run\_default\_\textit{command}}.
> >
> >-\section{Creating a new Dune module}
> >+\section{Creating a new Dune project}
> >
> >+From a buildsystem point of view there is no difference between a \dune
> >+application and a \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.
> >+be used by \dune applications. Therefore \dune modules offer libraries
> >+and/or header files. A \dune module needs to comply to a certain rules
> >+(see \ref{guidelines}).
> >
> >-In order to create new \dune module, you have to provide
> >+In order to create new \dune project, 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 \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}.
> > \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
> >+ important part is the call to \texttt{DUNE\_CHECK\_ALL} which
> > runs all checks needed for a \dune module, plus the checks for the
> > dependencies.
> >+\item a basic \texttt{m4} file\\
> > \end{itemize}
> >
> >+\emph{Note:} The program \texttt{duneproject} (found in
> >+\texttt{dune-common/bin}) can assist you in setting up the basic
> >+buildsystem files for your project. In case you are using unstable
> >+\dune you should be aware that the buildsystem is a running target,
> >+just like the source code. Therefore it might be that
> >+\texttt{duneproject} is not up to date with the latest changes.
> >+
> >+\section{Dune module guidelines}
> >+\label{guidelines}
> >+
> > A \dune module should comply with the following rules:
> > \begin{itemize}
> > \item Documentation is located under \texttt{doc/} and gets
> >@@ -669,120 +748,18 @@
> > \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.sh}).
> >+ \autogen (see \ref{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{DUNE\_SYMLINK} command in 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.
> >-
> >-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}[language=bash]
> >-
> >-#!/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 -d "$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 documentation}
> >
> > \minisec{automake \& Makefile.am}
> >@@ -817,6 +794,7 @@
> >
> > \end{document}
> >
> >+%%% Local IspellDict: "american"
> > %%% Local Variables:
> > %%% mode: latex
> > %%% TeX-master: t
> >
> >
> >
> >
> >------------------------------------------------------------------------
> >
> >_______________________________________________
> >Dune-Commit mailing list
> >Dune-Commit at dune-project.org
> >http://lists.dune-project.org/mailman/listinfo/dune-commit
>
More information about the Dune
mailing list