From 72e3af71fa22229711ffb581ba3a584c55779799 Mon Sep 17 00:00:00 2001 From: Timo Koch <timokoch@uio.no> Date: Wed, 28 Jun 2023 23:25:58 +0200 Subject: [PATCH] [doxygen] Add section about developing dumux from handbook --- doc/doxygen/DoxygenDumuxLayout.xml | 1 + doc/doxygen/pages/developing.md | 87 +++++++++++++++++++++++ doc/handbook/0_dumux-handbook.tex | 1 - doc/handbook/5_developingdumux.tex | 108 ----------------------------- 4 files changed, 88 insertions(+), 109 deletions(-) create mode 100644 doc/doxygen/pages/developing.md delete mode 100644 doc/handbook/5_developingdumux.tex diff --git a/doc/doxygen/DoxygenDumuxLayout.xml b/doc/doxygen/DoxygenDumuxLayout.xml index 8b8bcd1348..b8dcb4f257 100644 --- a/doc/doxygen/DoxygenDumuxLayout.xml +++ b/doc/doxygen/DoxygenDumuxLayout.xml @@ -28,6 +28,7 @@ SPDX-License-Identifier: GPL-3.0-or-later <tab type="user" url="@ref python-bindings" visible="yes" title="Python bindings" intro=""/> <tab type="usergroup" title="Developer documentation"> <tab type="user" url="@ref dumux-and-dune" visible="yes" title="Dumux and Dune" intro=""/> + <tab type="user" url="@ref developing-dumux" visible="yes" title="Developing Dumux" intro=""/> <tab type="user" url="@ref building-the-documentation" visible="yes" title="Build doxygen documentation" intro=""/> </tab> <tab type="user" url="@ref citelist" visible="yes" title="Bibliography" intro=""/> diff --git a/doc/doxygen/pages/developing.md b/doc/doxygen/pages/developing.md new file mode 100644 index 0000000000..343e75b475 --- /dev/null +++ b/doc/doxygen/pages/developing.md @@ -0,0 +1,87 @@ +# Developing DuMux + +## Communicate with DuMux Developers + +### Issues and Bug Tracking +The bug-tracking system via [GitLab Issues](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/issues) +offers the possibility to report bugs, discuss new development requests, or ask questions. +Feel free to register (if you don't have an account yet) and to contribute by opening an issue. + +### Commits, Merges requests +To be up-to-date with the latest changes made to any git-repository, you can use RSS Feeds. +Simply navigate to [Issues](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/issues) +or [Activity](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/activity) +and hit the RSS subscribe button on the top right. + +### Automatic Testing +The automatic testing using `Gitlab-CI` helps to constantly check the +DuMux problems for compiling and running correctly. An overview over +[recently run pipelines is available on GitLab](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/pipelines). +`Gitlab-CI` is configured via the `.gitlab-ci.yml` file in the project root directory. + +### 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 `dumux@iws.uni-stuttgart.de`. +You can [subscribe to the mailing list](https://listserv.uni-stuttgart.de/mailman/listinfo/dumux) +to be informed about upcoming releases, events, and see other peoples questions and answers. + +### Coding Guidelines +Writing code in a readable manner is very important, especially +for future code developers (e.g. for adding features, debugging, etc.). +Therefore, we have a [contribution guide](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/blob/master/CONTRIBUTING.md) +iuncluding a [style guide](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/blob/master/doc/styleguide.md) +and tips on how to contribute effectively. + +## Various tips and tricks +In the following, we mention a couple of tips & tricks. There is also +a [small Wiki](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/wikis/home) containing more. + +### Optimized computation vs debugging +Dune and DuMux are built with the help of `dunecontrol`. +Per default, DuMux is compiled using optimization options, which leads to faster runtimes but is unsuitable +for debugging. For debug opts you can set `CMAKE_BUILD_TYPE` to `Debug` or `RelWithDebInfo` +in your options file. You can also do this in any of the `CMakeLists.txt` in DuMux by adding the line + +```cmake +set(CMAKE_BUILD_TYPE Debug) +``` + +Afterwards rerun `cmake <path-to-build-dir>`. + +### Dunecontrol for selected modules +A complete build using `dunecontrol` takes some time. In many cases not all modules need to be re-built. +Pass the flag `--only=dumux` to `dunecontrol` for configuring or building only DuMux. A more +complex example would be a case in which you have to configure and build only e.g. `dune-grid` +and DuMux. This is achieved by adding `--only=dune-grid,dumux`. + +### Using Dune Debug Streams +Dune provides a helpful feature for keeping your debug-output organized. +It uses simple streams like `std::cout`, but they can be switched on and off +for the whole project. You can choose five different levels of severity: + +``` +5 - grave (dgrave) +4 - warning (dwarn) +3 - info (dinfo) +2 - verbose (dverb) +1 - very verbose (dvverb) +``` + +They are used as shown in the following example + +```cpp +#include <dune/common/debugstream.hh> +// 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 +``` + +### Make headercheck + +When developing C++ it is important to always include what you use and not to rely on transitive includes. +To check one header file for all necessary includes to compile the contained code, use `make headercheck`. +Include the option `-DENABLE_HEADERCHECK=1` in your opts file and run `dunecontrol`. +Then go to the top level in your build-directory and type `make headercheck` to check all headers +or use bash auto-completion to find the target to build. diff --git a/doc/handbook/0_dumux-handbook.tex b/doc/handbook/0_dumux-handbook.tex index 1f1068a22d..caaf705b7b 100644 --- a/doc/handbook/0_dumux-handbook.tex +++ b/doc/handbook/0_dumux-handbook.tex @@ -117,7 +117,6 @@ Universit\"at Stuttgart, Paffenwaldring 61, D-70569 Stuttgart, Germany}\\ \chapter{Overview and Infrastructure} \input{5_structure} \input{5_newfoldersetup} -\input{5_developingdumux} \input{5_scripts} \input{5_assemblinglinearsystem} diff --git a/doc/handbook/5_developingdumux.tex b/doc/handbook/5_developingdumux.tex deleted file mode 100644 index b0fea83ac9..0000000000 --- a/doc/handbook/5_developingdumux.tex +++ /dev/null @@ -1,108 +0,0 @@ -% SPDX-FileCopyrightInfo: Copyright © DuMux Project contributors, see AUTHORS.md in root folder -% SPDX-License-Identifier: CC-BY-4.0 - -\section{Developing \Dumux} -\label{sc_developingdumux} - -\subsection{Communicate with \Dumux Developers} - -\paragraph{Issues and Bug Tracking} -The bug-tracking system \emph{GitLab Issues} offers the possibility to report bugs or discuss new development requests. -Feel free to register (if you don't have an account at out \emph{Git} yet) and to contribute -at \url{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/issues}. - -\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. - -\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 -\url{https://git.iws.uni-stuttgart.de/buildbot/#/builders}. - -\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. - -\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}. - - -\subsection{Tips and Tricks} -\Dumux users and developers at the LH2 are also referred to the internal confluence pages for -more information. - -\paragraph{Optimized computation vs debugging} -\Dune and \Dumux are built with the help of \texttt{dunecontrol}. -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\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: - -\begin{lstlisting}[style=Shell] -set(CMAKE_BUILD_TYPE Debug) -\end{lstlisting} - -Afterwards rerun cmake (run cmake \texttt{$<$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 -complex example would be a case in which you have to configure and build only e.g. \Dune{}-grid -and \Dumux. This is achieved 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] -$ git diff > PATCHFILE -\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] -$ patch -p1 < PATCHFILE -\end{lstlisting} - -%TODO: currently, no DUNE patches necessary! Thus, this section is commented and the missing reference 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. - -\paragraph{File Name and Line Number by Predefined Macro} -If you want to create output in order to later 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 choose 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:} -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. -- GitLab