[Dune-devel] Announcement: CMake Modernization in DUNE Core Modules

[Ospina De Los Rios, Santiago]

Dear DUNE Developers,


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:


1. CMake Targets for Core Modules (master)

Each core module now provides a dedicated CMake target: Dune::Common, Dune::Geometry, Dune::Grid, Dune::ISTL, and Dune::LocalFunctions. Linking against these targets ensures that all necessary compilation information is correctly propagated, making integration easier.

2. Improved find_package Behavior (releases/2.10)

Using find_package to locate a DUNE module now fully resolves its dependencies and (in master) correctly propagates the corresponding CMake targets automatically.


3. Support for Super-Builds (releases/2.10)

The core DUNE modules can now be included as subdirectories in a larger CMake project.


These changes are already integrated into the current master 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.


For example, points 1 and 2 allow users to consume DUNE as any other C++ library:


```

cmake_minimum_required(VERSION 3.13)

project(my-project CXX)


find_package(dune-grid)


add_executable(my-app my-app.cc)

target_link_libraries(my-app PRIVATE Dune::Grid)

```


By linking against the Dune::Grid target provided by the dune-grid module, the executable target my-app inherits all of the compiler and linker flags required to use the dune-grid module within the source file my-app.cc. 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].


Adapting Other DUNE Modules


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:


  *   Define a library target with proper include directories

Use dune_add_library[^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 dune_default_include_directories[^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 link_libraries to link all targets under a directory (e.g., test/) with a given target.


  *   Resolve external dependencies automatically

When a module is found via find_package, 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 DUNE_CUSTOM_PKG_CONFIG_SECTION 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 also be searched and REQUIRED when the module is found via the find_package.


  *   Fully resolved preprocessor definitions

It used to be the case that a config.h 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 and new headers with the name <module-name>-config.hh are generated during configuration and installed alongside the library[^4]. 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. DUNE_HAVE_CXX_EXPERIMENTAL_IS_DETECTED or <DUNE-MODULE>_VERSION_MINOR). Otherwise, users that consume the library without the DUNE build system may be surprised to find undefined preprocessors keywords.


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 CMakeLists.txt 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 NEW behavior in order to benefit from the modernization.


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.


Best regards,


Santiago, Simon, and Timo


---


[^1]: https://www.dune-project.org/doc/buildsystem/#cmake-superbuilds<https://www.dune-project.org/doc/buildsystem/>

[^2]: https://gitlab.dune-project.org/core/dune-common/-/blob/releases/2.10/cmake/modules/DuneAddLibrary.cmake

[^3]: https://gitlab.dune-project.org/core/dune-common/-/blob/c851ab55ca5ccebc5d744927d2349af3dea12903/cmake/modules/DuneDefaultIncludeDirectories.cmake

[^4]: https://gitlab.dune-project.org/core/dune-common/-/merge_requests/1262

[^5]: https://gitlab.dune-project.org/core/dune-common/-/blob/releases/2.10/cmake/modules/DunePolicy.cmake

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.dune-project.org/pipermail/dune-devel/attachments/20250310/00501b54/attachment.htm>