<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<style type="text/css" style="display:none;"><!-- P {margin-top:0;margin-bottom:0;} --></style>
</head>
<body dir="ltr">
<div id="divtagdefaultwrapper" style="font-size:12pt;color:#000000;font-family:Calibri,Helvetica,sans-serif;" dir="ltr">
<div id="divtagdefaultwrapper" dir="ltr" style="font-size: 12pt; color: rgb(0, 0, 0); font-family: Calibri, Helvetica, sans-serif, Helvetica, EmojiFont, "Apple Color Emoji", "Segoe UI Emoji", NotoColorEmoji, "Segoe UI Symbol", "Android Emoji", EmojiSymbols;">
<p>Dear DUNE Developers,</p>
<p><br>
</p>
<p>We are pleased to announce that the main objectives of the CMake modernization in the DUNE core modules have been successfully achieved. The key improvements are:</p>
<p><b style="font-size:12pt"><br>
</b></p>
<p><b style="font-size:12pt">1. CMake Targets for Core Modules (<span style="font-family:"Courier New",monospace">master</span>)</b><br>
</p>
<p></p>
<blockquote style="margin:0 0 0 40px; border:none; padding:0px">
<p><span style="font-size:12pt">Each core module now provides a dedicated CMake target:
</span><span style="font-size:12pt; font-family:Consolas,Courier,monospace">Dune::Common</span><span style="font-size:12pt">,
</span><span style="font-size:12pt; font-family:Consolas,Courier,monospace">Dune::Geometry</span><span style="font-size:12pt">,
</span><span style="font-size:12pt; font-family:Consolas,Courier,monospace">Dune::Grid</span><span style="font-size:12pt">,
</span><span style="font-size:12pt; font-family:Consolas,Courier,monospace">Dune::ISTL</span><span style="font-size:12pt">, and
</span><span style="font-size:12pt; font-family:Consolas,Courier,monospace">Dune::LocalFunctions</span><span style="font-size:12pt">. Linking against these targets ensures that all necessary compilation information is correctly propagated, making integration
easier.</span></p>
</blockquote>
<b style="font-size:12pt">
<div><b style="font-size:12pt"><br>
</b></div>
2. Improved <span style="font-family:Consolas,Courier,monospace">find_package</span> Behavior (<span style="font-family:Consolas,Courier,monospace">releases/2.10</span>)</b><br>
<blockquote style="margin:0 0 0 40px; border:none; padding:0px">
<p>Using <span style="font-family:Consolas,Courier,monospace">find_package</span> to locate a DUNE module now fully resolves its dependencies and (in <span style="font-family:Consolas,Courier,monospace">master</span>) correctly propagates the corresponding
CMake targets automatically.</p>
</blockquote>
<p><br>
</p>
<p><b>3. Support for Super-Builds (<span style="font-family:Consolas,Courier,monospace">releases/2.10</span>)</b></p>
</div>
<blockquote style="margin: 0 0 0 40px; border: none; padding: 0px;">
<div dir="ltr" style="font-size: 12pt; color: rgb(0, 0, 0); font-family: Calibri, Helvetica, sans-serif, Helvetica, EmojiFont, "Apple Color Emoji", "Segoe UI Emoji", NotoColorEmoji, "Segoe UI Symbol", "Android Emoji", EmojiSymbols;">
<p>The core DUNE modules can now be included as subdirectories in a larger CMake project.</p>
</div>
</blockquote>
<div dir="ltr" style="font-size: 12pt; color: rgb(0, 0, 0); font-family: Calibri, Helvetica, sans-serif, Helvetica, EmojiFont, "Apple Color Emoji", "Segoe UI Emoji", NotoColorEmoji, "Segoe UI Symbol", "Android Emoji", EmojiSymbols;">
<p><span class="Apple-tab-span" style="white-space:pre"></span></p>
<p><br>
</p>
<p>These changes are already integrated into the current <span style="font-family:Consolas,Courier,monospace">master</span> branch of the core modules. The overall goal is to make DUNE more accessible to users unfamiliar with our build system by using the principle
of least surprise, i.e., standard CMake knowledge should be sufficient to use DUNE; No need to use home-grown scripts, CMake functions or directory layouts.</p>
<p><br>
</p>
<p>For example, points 1 and 2 allow users to consume DUNE as any other C++ library:</p>
<p><br>
</p>
<p>```</p>
<p><span style="font-family:Consolas,Courier,monospace">cmake_minimum_required(VERSION 3.13)</span></p>
<p><span style="font-family:Consolas,Courier,monospace">project(my-project CXX)</span></p>
<p><br>
</p>
<p><span style="font-family:Consolas,Courier,monospace"><b>find_package(dune-grid)</b></span></p>
<p><br>
</p>
<p><span style="font-family:Consolas,Courier,monospace">add_executable(my-app my-app.cc)</span></p>
<p><span style="font-family:Consolas,Courier,monospace">target_link_libraries(my-app PRIVATE
<b>Dune::Grid</b>)</span></p>
<p>```</p>
<p><br>
</p>
<p>By linking against the <span style="font-family:Consolas,Courier,monospace">Dune::Grid</span> target provided by the
<span style="font-family:Consolas,Courier,monospace">dune-grid</span> module, the executable target
<span style="font-family:Consolas,Courier,monospace">my-app</span> inherits all of the compiler and linker flags required to use the
<span style="font-family:Consolas,Courier,monospace">dune-grid</span> module within the source file
<span style="font-family:Consolas,Courier,monospace">my-app.cc</span>. That's all. Similarly, with point 3 the new super-build support allows us to bundle several modules in a single CMake project, simplifying the build process to one standard CMake call. A
quick guide on this is already available on our website[^1].</p>
<p><br>
</p>
<p><b><span style="font-size:14pt">Adapting Other DUNE Modules</span></b></p>
<p><br>
</p>
<p>We have tried our best to keep backward compatibility where possible. Indeed, no hard breaking changes in downstream modules have been introduced as far as we know. Nevertheless, in order to benefit from these modernizations in other library modules, some
changes are required:</p>
<p><br>
</p>
<p></p>
<ul style="margin-bottom:0px; margin-top:0px">
<li><b><span style="font-size:12pt"></span><span style="font-size:12pt"></span></b><span style="font-size:12pt"><b>Define a library target with proper include directories</b></span><br>
</li></ul>
<p></p>
<blockquote style="margin:0 0 0 40px; border:none; padding:0px">
<p>Use <span style="font-family:Consolas,Courier,monospace">dune_add_library</span>[^2] to create and export a library target. Make sure that the target sets up the includes directories appropriately. If you have a layout like most DUNE modules, you could use
the <span style="font-family:Consolas,Courier,monospace">dune_default_include_directories</span>[^3] function to ensure correct handling. Then, you will be able to use the new target to link your executables as shown above. In particular, tests should be ideally
linked against such target too. For this, you may use <span style="font-family:Consolas,Courier,monospace">
link_libraries</span> to link all targets under a directory (e.g., <span style="font-family:Consolas,Courier,monospace">
test/</span>) with a given target.</p>
</blockquote>
<p><br>
</p>
<p></p>
<ul style="margin-bottom:0px; margin-top:0px">
<li><span style="font-size:12pt"></span><span style="font-size:12pt"></span><b style="font-size:12pt">Resolve external dependencies automatically</b><br>
</li></ul>
<p></p>
<blockquote style="margin:0 0 0 40px; border:none; padding:0px">
<p>When a module is found via <span style="font-family:Consolas,Courier,monospace">
find_package</span>, external non-DUNE dependencies of that module should also be resolved so that its targets are functional. This can be achieved by appending the relevant logic to the
<span style="font-family:Consolas,Courier,monospace">DUNE_CUSTOM_PKG_CONFIG_SECTION</span> CMake variable. The contents of this variable will be executed by CMake once the library is found. As a rule of thumb: if an external library is used to set up an exported
target, it should <i>also</i> be searched and <span style="font-family:Consolas,Courier,monospace">
REQUIRED</span> when the module is found via the <span style="font-family:Consolas,Courier,monospace">
find_package</span>.</p>
</blockquote>
<p><br>
</p>
<p></p>
<ul style="margin-bottom:0px; margin-top:0px">
<li><span style="font-size:12pt"></span><span style="font-size:12pt"></span><b style="font-size:12pt">Fully resolved preprocessor definitions</b><br>
</li></ul>
<p></p>
<blockquote style="margin:0 0 0 40px; border:none; padding:0px">
<p>It used to be the case that a <span style="font-family:Consolas,Courier,monospace">
config.h</span> file was only generated by the downstream project and not by the module itself. The file contains critical preprocessor definitions required to use the library so using the libraries without the DUNE build system was nearly impossible. Since
version 2.10 this behavior was extended<span style="font-size: 12pt;"> </span><span style="font-size: 12pt;">and new headers with the name
</span><span style="font-size: 12pt; font-family: Consolas, Courier, monospace;"><module-name>-config.hh</span><span style="font-size: 12pt;"> are generated during configuration and installed alongside the library</span><span style="font-size: 12pt;">[^4]</span><span style="font-size: 12pt;">.
Both headers can be consumed simultaneously, but to benefit from the modernization, library developers need to eagerly include the new header whenever they use a preprocessor provided by the configuration files (e.g.
</span><span style="font-size: 12pt; font-family: Consolas, Courier, monospace;">DUNE_HAVE_CXX_EXPERIMENTAL_IS_DETECTED</span><span style="font-size: 12pt;"> or
</span><span style="font-size: 12pt; font-family: Consolas, Courier, monospace;"><DUNE-MODULE>_VERSION_MINOR</span><span style="font-size: 12pt;">). Otherwise, users that consume the library without the DUNE build system may be surprised to find undefined preprocessors
keywords.</span></p>
</blockquote>
<p><br>
</p>
<p>In most libraries following the DUNE layout, this should result in relatively small changes. For reference, you can check the core modules, specially in the root
<span style="font-family:Consolas,Courier,monospace">CMakeLists.txt</span> files. As an aid for this transition, we have included DUNE policies[^5] that change the behavior of the build system. When unset, they will issue a warning describing the change in
behavior. We recommend attaining to the <span style="font-family:Consolas,Courier,monospace">
NEW</span> behavior in order to benefit from the modernization.</p>
<p><br>
</p>
<p>We encourage you to try out these changes and share your feedback. Your input will help refine the modernization before the next release. If you have questions, or things do not work as expected, please reach out to us. While we might not have the time to
make the modifications for your specific module, we may give you useful hints on how to make things work.</p>
<p><br>
</p>
<p>Best regards,</p>
<p><br>
</p>
<p>Santiago, Simon, and Timo</p>
<p><br>
</p>
<p>---</p>
<p><br>
</p>
<p>[^1]: <a href="https://www.dune-project.org/doc/buildsystem/#cmake-superbuilds" style="font-size:12pt">https://www.dune-project.org/doc/buildsystem/#cmake-superbuilds</a><a href="https://www.dune-project.org/doc/buildsystem/" class="OWAAutoLink" id="LPlnk133154"></a></p>
<p><span style="font-size:12pt">[^2]: <a href="https://gitlab.dune-project.org/core/dune-common/-/blob/releases/2.10/cmake/modules/DuneAddLibrary.cmake" class="OWAAutoLink">
https://gitlab.dune-project.org/core/dune-common/-/blob/releases/2.10/cmake/modules/DuneAddLibrary.cmake</a> </span><br>
</p>
<p><span style="font-size:12pt">[^3]: <a href="https://gitlab.dune-project.org/core/dune-common/-/blob/c851ab55ca5ccebc5d744927d2349af3dea12903/cmake/modules/DuneDefaultIncludeDirectories.cmake" class="OWAAutoLink">
https://gitlab.dune-project.org/core/dune-common/-/blob/c851ab55ca5ccebc5d744927d2349af3dea12903/cmake/modules/DuneDefaultIncludeDirectories.cmake</a> </span><br>
</p>
<p><span style="font-size:12pt">[^4]: <a href="https://gitlab.dune-project.org/core/dune-common/-/merge_requests/1262" class="OWAAutoLink">
https://gitlab.dune-project.org/core/dune-common/-/merge_requests/1262</a> </span><br>
</p>
<p><span style="font-size:12pt">[^5]: <a href="https://gitlab.dune-project.org/core/dune-common/-/blob/releases/2.10/cmake/modules/DunePolicy.cmake" class="OWAAutoLink">
https://gitlab.dune-project.org/core/dune-common/-/blob/releases/2.10/cmake/modules/DunePolicy.cmake</a> </span><br>
</p>
<div><br>
</div>
</div>
</div>
</body>
</html>