5_developingdumux.tex 5.02 KB
Newer Older
Thomas Fetzer's avatar
Thomas Fetzer committed
1 2 3 4
\section{Developing \Dumux}
\label{sc_developingdumux}

\subsection{Communicate with \Dumux Developers}
5

6 7
\paragraph{Issues and Bug Tracking}
The bug-tracking system \emph{GitLab Issues} offers the possibility to report bugs or discuss new development requests.
8
Feel free to register (if you don't have a \emph{Git} account already) and to contribute
9 10
at \url{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/issues}.

11 12 13 14
\paragraph{Commits, Merges, etc.}
To be up-to-date with the latest changes made to any git-repository you can use RSS Feeds.
Simply click on \emph{Issues} or \emph{Activity} and then select a tab you are interested in
and use your favorite RSS-application for receiving the news.
Thomas Fetzer's avatar
Thomas Fetzer committed
15 16 17 18

\paragraph{Automatic Testing Dashboard}
The automatic testing using \emph{BuildBot} helps to constantly check the
\Dumux problems for compiling and running correctly. It is available at
19
\url{https://git.iws.uni-stuttgart.de/buildbot/#/builders}.
Thomas Fetzer's avatar
Thomas Fetzer committed
20 21 22 23 24 25 26 27

\paragraph{The General Mailing List:}
If you have questions, specific problems (which you really struggle to solve on your own),
or hints for the \Dumux-developers, please contact the mailing list \url{dumux@iws.uni-stuttgart.de}.
You can subscribe to the mailing list via
\url{https://listserv.uni-stuttgart.de/mailman/listinfo/dumux}, then you
will be informed about upcoming releases or events.

28 29 30 31 32 33 34
\subsection{Coding Guidelines}
Writing code in a readable manner is very important, especially
for future code developers (e.g. for adding features, debugging, etc.).
For the style guide and instructions how to contribute to \Dumux visit
\url{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/blob/master/CONTRIBUTING.md}.


Thomas Fetzer's avatar
Thomas Fetzer committed
35 36 37 38
\subsection{Tips and Tricks}
\Dumux users and developers at the LH2 are also referred to the internal Wiki for
more information.

39
\paragraph{Optimized computation vs debugging}
Thomas Fetzer's avatar
Thomas Fetzer committed
40
\Dune and \Dumux are built with the help of \texttt{dunecontrol}, as explained on page \pageref{buildIt}.
41
Per default, \Dumux is compiled using optimization options, which leads to faster runtimes but is unsuitable
42 43
for debugging. For debug opts you can set \texttt{DCMAKE\textunderscore BUILD\textunderscore 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:
44

Thomas Fetzer's avatar
Thomas Fetzer committed
45
\begin{lstlisting}[style=Shell]
46
set(CMAKE_BUILD_TYPE Debug)
Thomas Fetzer's avatar
Thomas Fetzer committed
47
\end{lstlisting}
48

49
Afterwards rerun cmake again (run cmake <path-to-build-dir>).
50

Thomas Fetzer's avatar
Thomas Fetzer committed
51 52 53 54 55 56 57 58 59 60
\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
complex example would be the use of an additional module. Then you have to configure and build only \Dune{}-grid
and \Dumux by adding \texttt{--only=MODULE,dumux}.

\paragraph{Patching Files or Modules}
If you want to send changes to an other developer of \Dumux providing patches
can be quite smart. To create a patch simply type:
\begin{lstlisting}[style=Bash]
61
$ git diff > PATCHFILE
Thomas Fetzer's avatar
Thomas Fetzer committed
62 63 64 65 66
\end{lstlisting}
\noindent which creates a text file containing all your changes to the files
in the current folder or its subdirectories.
To apply a patch in the same directory type:
\begin{lstlisting}[style=Bash]
67
$ patch -p1 < PATCHFILE
Thomas Fetzer's avatar
Thomas Fetzer committed
68
\end{lstlisting}
69 70 71 72

%TODO: currently, no DUNE patches necessary! Thus, this section is commented and the missing refrence would be bad.
% Uncomment the following statement again when patches might be necessary.
% See \ref{sc:patchingDUNE} if you need to apply patches to \Dumux or \Dune.
Thomas Fetzer's avatar
Thomas Fetzer committed
73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101

\paragraph{File Name and Line Number by Predefined Macro}
If you want to  know where some output or debug information came from, use the predefined
macros \texttt{\_\_FILE\_\_} and \texttt{\_\_LINE\_\_}:
\begin{lstlisting}[style=DumuxCode]
std::cout << "# This was written from "<< __FILE__ << ", line " << __LINE__ << std::endl;
\end{lstlisting}

\paragraph{Using \Dune Debug Streams}
\Dune provides a helpful feature, for keeping your debug-output organized.
It uses simple streams like \texttt{std::cout}, but they can be switched on and off
for the whole project. You can chose five different levels of severity:
\begin{verbatim}
5 - grave (dgrave)
4 - warning (dwarn)
3 - info (dinfo)
2 - verbose (dverb)
1 - very verbose (dvverb)
\end{verbatim}
\noindent They are used as follows:
\begin{lstlisting}[style=DumuxCode]
// define the minimal debug level somewhere in your code
#define DUNE_MINIMAL_DEBUG_LEVEL 4
Dune::dgrave << "message"; // will be printed
Dune::dwarn << "message"; // will be printed
Dune::dinfo << "message"; // will NOT be printed
\end{lstlisting}

\paragraph{Make headercheck:}
102 103 104 105
To check one header file for all necessary includes to compile the contained code, use \texttt{make headercheck}.
Include the option \texttt{-DENABLE\_HEADERCHECK=1} in your opts file and run \texttt{dunecontrol}.
Then go to the top level in your build-directory and type \texttt{make headercheck} to check all headers
or press 'tab' to use the auto-completion to search for a specific header.