From b814972c64e54c410c8e43f6d515a1859fb923f9 Mon Sep 17 00:00:00 2001
From: Timo Koch <timo.koch@iws.uni-stuttgart.de>
Date: Wed, 19 Dec 2018 14:17:22 +0000
Subject: [PATCH] Merge branch 'fix/handbook-build-guide' into 'master'
[doc][handbook] do not mention debug opts
See merge request dumux-repositories/dumux!1433
(cherry picked from commit cdb21e771abe22892a7607cc8224d7457d6d4c9b)
8169ce21 [doc][handbook] do not mention debug opts
---
doc/handbook/2_detailedinstall.tex | 16 +++++-----------
doc/handbook/4_developingdumux.tex | 21 ++++++++-------------
doc/handbook/installDumux.sh | 2 +-
3 files changed, 14 insertions(+), 25 deletions(-)
diff --git a/doc/handbook/2_detailedinstall.tex b/doc/handbook/2_detailedinstall.tex
index a4b8286eeb..e152c7b234 100644
--- a/doc/handbook/2_detailedinstall.tex
+++ b/doc/handbook/2_detailedinstall.tex
@@ -165,19 +165,13 @@ $ ./dune-common/bin/dunecontrol --configure-opts="CXXFLAGS=-fno-strict-aliasing"
\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
+Larger sets of options are kept in them. If you are going to compile with modified options, the following
can be a starting point:
\begin{lstlisting}[style=Bash]
$ # make sure you are in the common root directory
-$ 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
+$ cp dumux/cmake.opts my-cmake.opts # create a personal version
+$ gedit my-cmake.opts # optional editing the options file
+$ ./dune-common/bin/dunecontrol --opts=my-cmake.opts all
\end{lstlisting}
Sometimes, it is necessary to have additional options which
@@ -257,7 +251,7 @@ Make sure that it uses the same library as \Dune when configuring the external l
Some of the libraries are then compiled within that directory and are not installed in
a different place, but \Dune may need to know their location. Thus, one may have to refer to
-them as options for \texttt{dunecontrol}, for example via the options file \texttt{my-debug.opts}.
+them as options for \texttt{dunecontrol}, for example via the options file \texttt{my-cmake.opts}.
Make sure you compile the required external libraries before you run \texttt{dunecontrol}.
An easy way to install some of the libraries and modules given below is the
diff --git a/doc/handbook/4_developingdumux.tex b/doc/handbook/4_developingdumux.tex
index c6ee4c559b..2d78d850d6 100644
--- a/doc/handbook/4_developingdumux.tex
+++ b/doc/handbook/4_developingdumux.tex
@@ -36,23 +36,18 @@ For the style guide and instructions how to contribute to \Dumux visit
\Dumux users and developers at the LH2 are also referred to the internal Wiki for
more information.
-\paragraph{Option Files optim.opts and debug.opts}
+\paragraph{Optimized computation vs debugging}
\Dune and \Dumux are built with the help of \texttt{dunecontrol}, as explained on page \pageref{buildIt}.
-The options needed to be specified for that are provided using option files like
-\texttt{debug.opts} and \texttt{optim.opts}. These two compile \Dune and \Dumux
-either for debugging or for fast simulation. Programs compiled with optimization options
-can lead to a speedup of factor up to ten!\par
-In contrast programs that are compiled with optimization can hardly be debugged.
-You can modify the files and change the compiler, the name of the build director,
-add third-party dependencies, add additional compiler flags, ... .
+Per default, \Dumux is compiled using optimization options, which leads to faster runtimes but is unsuitable
+for debugging. For debug opts you can set \texttt{DCMAKE_BUILD_TYPE} to \texttt{Debug} or \texttt{RelWithDebInfo}
+in your options file. You can also do this in any of the \texttt{CMakeLists.txt} in Dumux by adding
+
\begin{lstlisting}[style=Shell]
-BUILDDIR=build-clang
-CMAKE_FLAGS="\
- -DCMAKE_C_COMPILER=/usr/bin/clang \
- -DCMAKE_CXX_COMPILER=/usr/bin/clang++ \
- -DUG_DIR=./externals/ug-3.12.1"
+set(CMAKE_BUILD_TYPE Debug)
\end{lstlisting}
+Afterwarde rerun cmake again (run cmake <path-to-build-dir>).
+
\paragraph{Dunecontrol for selected modules}
A complete build using \texttt{dunecontrol} takes some time. In many cases not all modules need to be re-built.
Pass the flag \texttt{--only=dumux} to \texttt{dunecontrol} for configuring or building only \Dumux. A more
diff --git a/doc/handbook/installDumux.sh b/doc/handbook/installDumux.sh
index 74b14f05cb..0e84314ccc 100644
--- a/doc/handbook/installDumux.sh
+++ b/doc/handbook/installDumux.sh
@@ -42,7 +42,7 @@ 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/optim.opts all
+./dune-common/bin/dunecontrol --opts=dumux/cmake.opts all
#
if [ $? -ne 0 ]; then
echo "*************************************************"
--
GitLab