Commit 25688435 authored by Beatrix Becker's avatar Beatrix Becker
Browse files

[handbook] restructure installation chapter and add detail to documentation guidelines

parent fcfdfb43
......@@ -24,6 +24,7 @@
\usepackage{units}
\usepackage{url}
\usepackage{xspace}
\usepackage{accsupp}
\hypersetup{bookmarksdepth=3}
\usetikzlibrary{arrows}
\usetikzlibrary{backgrounds}
......@@ -109,10 +110,13 @@ Universit\"at Stuttgart, Paffenwaldring 61, D-70569 Stuttgart, Germany}\\
\input{1_introduction}
\chapter{Getting started}
First, we briefly describe the installation procedure.
Then we provide a quick start guide for the first \Dumux experience.
In this chapter we provide a quick start guide to
your first \Dumux experience.
The first section contains instructions on how to very quickly install \Dumux.
More detailed information on how to obtain source code, build and test \Dune and \Dumux
follows in the second section of this chapter. The second section also contains information on
how to build the documentation and about external libraries and modules.
\input{2_quickinstall}
\input{2_quickstartguide}
\input{2_detailedinstall}
\chapter{Tutorial}\label{chp:tutorial}
......
......@@ -4,6 +4,7 @@
inputencoding=ansinew,
breaklines=true,
tabsize=4,
columns=flexible,
literate={0}{{\textcolordigits{0}}}{1}%
{1}{{\textcolordigits{1}}}{1}%
{2}{{\textcolordigits{2}}}{1}%
......@@ -68,7 +69,7 @@
language=sh,
numbers=left,
numbersep=5pt,
numberstyle=\tiny,
numberstyle=\tiny\noncopynumber,
basicstyle=\ttfamily\scriptsize,
stringstyle=\color{BrickRed}\ttfamily\let\textcolor\textcolordummy,
commentstyle=\color[gray]{0.35}\ttfamily\itshape\let\textcolor\textcolordummy,
......@@ -81,7 +82,7 @@
escapeinside={/*@}{@*/}, % escape the long comments
numbers=left,
numbersep=5pt,
numberstyle=\tiny,
numberstyle=\tiny\noncopynumber,
basicstyle=\ttfamily\scriptsize,
keywordstyle=\color{dumuxBlue}\ttfamily\let\textcolor\textcolordummy,
stringstyle=\color{BrickRed}\ttfamily\let\textcolor\textcolordummy,
......@@ -100,9 +101,15 @@
language=sh,
numbers=left,
numbersep=5pt,
numberstyle=\tiny,
numberstyle=\tiny\noncopynumber,
basicstyle=\ttfamily\scriptsize,
stringstyle=\color{BrickRed}\ttfamily\let\textcolor\textcolordummy,
commentstyle=\color[gray]{0.35}\ttfamily\itshape\let\textcolor\textcolordummy,
morecomment=[l][\color{dumuxBlue}\let\textcolor\textcolordummy]{[},
}
\newcommand{\noncopynumber}[1]{
\BeginAccSupp{method=escape,ActualText={}}
#1
\EndAccSupp{}
}
This diff is collapsed.
\section{Quick Installation of \Dumux}
\label{quick-install}
This only provides one quick way of installing \Dumux.
You should have a recent working Linux environment, no \Dune core modules should be installed.
If you need more information,
This section only provides one quick way of installing \Dumux.
You should have a recent working Linux environment and no \Dune core modules should be installed.
If you need more information or
have \Dune already installed, please have a look at the detailed installation
instructions in Section \ref{install}.
\subsection{Obtaining the Code with the Script \texttt{checkout-dumux}}
The shell-script \texttt{checkout-dumux}
facilitates setting up a {\Dune}/{\Dumux} directory tree.
It is available after obtaining a download link via \url{http://www.dumux.org/download/}.
For example the second line below will check out the required \Dune modules and \texttt{dumux},
\texttt{dumux-devel} and the \texttt{external} folder, which contains some useful external software and libraries.
Again, \texttt{joeuser} needs to be replaced by the actual user name.
\begin{lstlisting}[style=Bash]
$ checkout-dumux -h # show help,
$ checkout-dumux -gme -u joeuser -p password -d DUMUX
\end{lstlisting}
Be aware that you cannot get \texttt{dumux-devel} or the external libraries from \texttt{dumux-external} unless
you have an GitLab account with the right privileges.
If you want to install \Dune and \Dumux without the help of \texttt{checkout-dumux} script a complete installation
guide can be found in chapter \ref{install}.
\subsection{Build of \Dune and \Dumux}
\label{buildIt}
Building of \Dune and \Dumux is done by the command-line script \texttt{dunecontrol} as described in
\Dune Installation Notes\footnote{\url{https://www.dune-project.org/doc/installation/}}.
More details about the build-system can be found in the \Dune buildsystem documentation\footnote{\url{https://www.dune-project.org/buildsystem/}}.
If something fails during the execution of \texttt{dunecontrol} feel free to report it to the \Dune or \Dumux developer mailing list,
but also try to include error details.
It is possible to compile \Dumux with nearly no explicit options to the build system.
However, for the successful compilation of \Dune and \Dumux, it is currently necessary to pass
the option \texttt{-fno-strict-aliasing} to the \Cplusplus compiler,
which is done here via a command-line argument to \texttt{dunecontrol}:
\begin{lstlisting}[style=Bash]
$ # make sure you are in the directory DUNE-Root
$ ./dune-common/bin/dunecontrol --configure-opts="CXXFLAGS=-fno-strict-aliasing" --use-cmake all
\subsection{Prerequisites} \label{sec:prerequisites}
For this quick start guide the following software packages are required:
\begin{itemize}
\item GitLab client
\item A standard compliant C++ compiler supporting C++11 and the C++14 feature set of GCC 4.9. We support GCC 4.9 or newer and Clang 3.8 or newer.
\item CMake 2.8.12 or newer
\item pkg-config
\item paraview (to visualize the results)
\end{itemize}
The building of included documentation like this handbook requires \LaTeX{} and auxiliary tools
\texttt{bibtex}. One usually chooses a \LaTeX{} distribution like \texttt{texlive} for this purpose.
It is possible to switch off the building of the documentation by setting the switch \texttt{--disable-documentation}
in the \texttt{CONFIGURE\_FLAGS} of the building options, see Chapter \ref{buildIt}.
\subsection{Obtaining code and configuring all modules with a script}
We provide you with a shell-script \texttt{installDumux.sh} that facilitates setting up a {\Dune}/{\Dumux} directory tree
and configures all modules with CMake.
It is available after obtaining a download link via \url{http://www.dumux.org/download/} or
by copying the following lines into a text-file named \texttt{installDumux.sh}:
\lstinputlisting[style=DumuxCode, numbersep=5pt, firstline=1, firstnumber=1]{installDumux.sh}
Place the \texttt{installDumux.sh} script in the directory where you want to install \Dumux and \Dune (a single
root folder \texttt{DUMUX} will be produced, so you do not need to provide one).
Run the script by typing into the terminal: \texttt{./installDumux.sh}
Configuring \Dune and \Dumux is done by the command-line script \texttt{dunecontrol}
using optimized configure options, see the line entitled \texttt{\# run build} in the \texttt{installDumux.sh} script.
More details about the build-system can be found in section \ref{buildIt}.
\subsection{A first test run of \Dumux}
When the \texttt{installDumux.sh} script from the subsection above has run successfully, you can execute a second script that
will compile and run a simple one-phase ground water flow example and will visualize the result using paraview.
The test script can be obtained by copying the following lines into a text-file named \texttt{test\_dumux.sh}
that has to be located in the same directory as the installation script.
\begin{lstlisting}[style=DumuxCode]
cd DUMUX/dumux/build-cmake/test/porousmediumflow/1p/implicit
make -B test_1pcctpfa
./test_1pcctpfa test_1pcctpfa.input
paraview *pvd
\end{lstlisting}
Too many options can make life hard. That's why usually option files are being used together with \texttt{dunecontrol} and its sub-tools.
Larger sets of options are kept in them. If you are going to compile with options suited for debugging the code, the following
can be a starting point:
\begin{lstlisting}[style=Bash]
$ # make sure you are in the directory DUNE-Root
$ cp dumux/debug.opts my-debug.opts # create a personal version
$ gedit my-debug.opts # optional editing the options file
$ ./dune-common/bin/dunecontrol --opts=my-debug.opts --use-cmake all
\end{lstlisting}
More optimized code, which is typically not usable for standard debugging tasks, can be produced by
\begin{lstlisting}[style=Bash]
$ cp dumux/optim.opts my-optim.opts
$ ./dune-common/bin/dunecontrol --opts=my-optim.opts --use-cmake all
\end{lstlisting}
Sometimes it is necessary to have additional options which
are specific to a package set of an operating system or
sometimes you have your own preferences.
Feel free to work with your own set of options, which may evolve over time.
The option files above are to be understood more as a starting point
for setting up an own customization than as something which is fixed.
The use of external libraries can make it necessary to add quite many options in an option file.
It can be helpful to give your customized option file its own name, as done above.
One avoids confusing it with the option files which came out of the distribution.
The script \texttt{test\_dumux.sh} can be executed by typing into the terminal: \texttt{./test\_dumux.sh}.
If everything works fine, a paraview-window with the result should open automatically.
\section[Quick Start Guide]{Quick Start Guide: The First Run of a Test Application}
\label{quick-start-guide}
The previous section showed how to install and compile \Dumux. This chapter
shall give a very brief introduction how to run a first test application and how
to visualize the first output files. A more detailed explanations can be found in
the tutorials in the following chapter.\\
All executables are compiled in the \texttt{build} subdirectories of \Dumux.
If not given differently in the input files, this is \texttt{build-cmake} as default.
\begin{enumerate}
\item Go to the directory \texttt{build-cmake/test}. There, various test application
folders can be found. Let us consider as example \texttt{porousmediumflow/2p/implicit/test{\_}box2p}:
\item Enter the folder \texttt{porousmediumflow/2p/implicit}. Type \texttt{make test{\_}box2p} in order
to compile the application \texttt{test{\_}box2p}. To run the simulation, type\\
\texttt{./test{\_}box2p -parameterFile ./test\_box2p.input}\\
into the console. The parameter \texttt{-parameterFile} specifies that all
important parameters (like first timestep size, end of simulation and location
of the grid file) can be found in a text file in the same directory with the
name \texttt{test\_box2p.input}.
\item The simulation starts and produces some .vtu output files and also a .pvd
file. The .pvd file can be used to examine time series and summarizes the .vtu
files. It is possible to stop a running application by pressing $<$Ctrl$><$c$>$.
\item You can display the results using the visualization tool ParaView (or
alternatively VisIt). Just type \texttt{paraview} in the console and open the
.pvd file. On the left hand side, you can choose the desired parameter to be displayed.
\end{enumerate}
......@@ -3,32 +3,88 @@
Writing code in a readable manner is very important, especially
for future code developers (e.g. for adding features, debugging, etc.).
This section is inspired by the DUNE coding guidelines
% this site is currently down (27.02.2017), hope it will be online soon again
\url{http://www.dune-project.org/doc/devel/codingstyle.html}, which is strongly recommended.
\url{https://www.dune-project.org/dev/codingstyle/}, which is strongly recommended.
\paragraph{Documentation:}
Please document freely what each part of your code does. All comments/ documentation
is in \textbf{English}.
\subsection{Documentation:}
Please document freely what each part of your code \emph{should} do. All comments/documentation
is in English.
We proclaim the Doc-Me Dogma, which means whatever you do, please document
it least with
it at least with:
\begin{lstlisting}[style=DumuxCode]
/*! \todo Please doc me! */
\todo Please doc me!
\end{lstlisting}
That way at least the absence of documentation is documented, and it is easier
to get rid of it systematically. Please comment \textbf{all}:
to get rid of it systematically.
In the following we will describe several ways for
commenting code in \Dumux.\\
There are four ways to comment a \textbf{single line} of code:
\begin{lstlisting}[style=DumuxCode]
Line of code 1 // Short comment on line of code 1 that will not show in doxygen
Line of code 2 //!< Short comment on line of code 2 that will show in doxygen
//! Short comment on the following line (line of code 3) that will show in doxygen
Line of code 3
/*!
* Longer comment on line of code 4
* with several lines of length
* that will show in doxygen
*/
Line of code 4
\end{lstlisting}
The third and fourth of the above shown options can also be used to document functions with
neither method parameters nor return value.\\
For doxygen to be able to group the \textbf{files} correctly, please add before the headerguard:
\begin{lstlisting}[style=DumuxCode]
/*!
* \file
* \ingroup GroupName
* \brief A short description of the file.
*/
#ifndef HEADERGUARD
#define HEADERGUARD
\end{lstlisting}
For doxygen to be able to group the \textbf{classes} correctly, please add before each class:
\begin{lstlisting}[style=DumuxCode]
/*!
* \ingroup GroupName
* \brief A short description of the class.
*
* Optional detailed description of the class
* over several lines.
*/
template <class TypeTag>
\end{lstlisting}
For an overview over all available groups and to add new groups please
see the file\\ \texttt{doc/doxygen/modules.txt} from the \texttt{dumux} module.\\
Please add before each \textbf{function} with method parameters or return value:
\begin{lstlisting}[style=DumuxCode]
/*!
* \brief A short description of the function.
*
* Optional detailed description of the function
* over several lines.
*
* \param paramName Very short description of paramName
* \return returnName Very short description of returnName
*/
paramType functionName(paramType paramName)
{
...
return returnName
}
\end{lstlisting}
Furthermore, please comment \textit{all}:
\begin{itemize}
\item Method Parameters (in / out)
\item Template Parameters
\item Exceptions thrown by a method
\item Method parameters which are not self-explanatory should always
have a meaningful comment at calling sites. Example:
\begin{lstlisting}[style=DumuxCode]
localResidual.eval(/*includeBoundaries=*/true);
\end{lstlisting}
\item Template Parameters
\item Return Values
\item Exceptions thrown by a method
\end{itemize}
\paragraph{Naming:}
\subsection{Naming:}
To avoid duplicated types or variables and for a better understanding and usability
of the code we have the following naming conventions:
\begin{itemize}
......
......@@ -4,7 +4,6 @@ set(TEX_INPUTS
1_introduction.tex
2_detailedinstall.tex
2_quickinstall.tex
2_quickstartguide.tex
3_tutorial.tex
3_furtherpractice.tex
4_assemblinglinearsystem.tex
......@@ -19,7 +18,8 @@ set(TEX_INPUTS
5_grids.tex
5_models.tex
5_propertysystem.tex
5_spatialdiscretizations.tex)
5_spatialdiscretizations.tex
installDumux.sh)
set(TEX_IMAGES
PNG/box_disc.png
......
# One click install script for dumux
# make a new folder containing everything
mkdir $(pwd)/DUMUX
cd DUMUX
echo "*************************************************"
echo "(1/2) Cloning repositories. This may take a while.
Make sure to be connected to the internet."
echo "*************************************************"
# the core modules
for MOD in common geometry grid localfunctions istl; do
if [ ! -d "dune-$MOD" ]; then
git clone -b releases/2.5 https://gitlab.dune-project.org/core/dune-$MOD.git
else
echo "Skip cloning dune-$MOD because the folder already exists."
cd dune-$MOD
git checkout releases/2.5
cd ..
fi
done
# dumux
if [ ! -d "dumux" ]; then
git clone -b releases/3.0-alpha https://git.iws.uni-stuttgart.de/dumux-repositories/dumux.git
else
echo "Skip cloning dumux because the folder already exists."
cd dumux
git checkout releases/3.0-alpha
cd ..
fi
if [ $? -ne 0 ]; then
echo "*************************************************"
echo "Failed to clone the repositories."
echo "*************************************************"
exit $?
fi
echo "*************************************************"
echo "(2/2) Configure dune modules and dumux. Build the
dune libaries. This may take several minutes."
echo "*************************************************"
# run build
./dune-common/bin/dunecontrol --opts=dumux/myoptim.opts all
#
if [ $? -ne 0 ]; then
echo "*************************************************"
echo "Failed to build the dune libaries."
echo "*************************************************"
exit $?
fi
# echo result
echo "*************************************************"
echo "Successfully configured and built dune and dumux."
echo "Please run the test_dumux.sh script to confirm everything works."
echo "*************************************************"
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment