.gitlab-ci.yml

-image: gitlab-registry.mpcdf.mpg.de/mpcdf/module-image
+image: gitlab-registry.mpcdf.mpg.de/mpcdf/ci-module-image/intel_2024_0-impi_2021_11:2024
 
 check-recipes:
   before_script:
+    - zypper install -y doxygen
     - module purge
-    - module load cmake/3.24 doxygen git
-    - module load intel/21.5.0
+    - module load cmake
+    - module load intel/2024.0 impi/2021.11
     - module load gsl
     - module list
     - cmake --version
@@ -69,14 +70,18 @@ check-recipes:
     - cmake --build 10_production
     - ./10_production/app
 
+    - CXXFLAGS="-O3 -g" cmake -S 11_customization -B 11_build
+    - cmake --build 11_build --verbose
+    - ./11_build/hallo_world
+
 check-links:
   before_script:
     - module purge
-    - module load anaconda/3/2021.11
+    - module load anaconda/3/2023.03
     - module list
 
     - pip3 install linkcheckmd
 
   script:
-    - /root/.local/bin/linkcheckMarkdown -vr .
+    - linkcheckMarkdown -vr .
 

01_third_party_libraries/CMakeLists.txt

@@ -7,9 +7,9 @@ find_package(OpenMP REQUIRED)
 
 set(MKL_ARCH intel64)
 set(MKL_LINK dynamic)
-set(MKL_THREADING intel_thread)
-set(MKL_INTERFACE lp64)
-set(MKL_MPI openmpi)
+set(MKL_THREADING sequential)
+set(MKL_INTERFACE ilp64)
+set(MKL_MPI intelmpi)
 find_package(MKL REQUIRED)
 
 add_executable(main)

11_customization/CMakeLists.txt

+cmake_minimum_required(VERSION 3.20)
+
+project(11_customization
+        LANGUAGES CXX)
+
+##########################
+# EXECUTABLE
+##########################
+add_executable(hallo_world)
+target_sources(hallo_world PRIVATE main.cpp)
+

11_customization/README.md

+# How can I influence the build process as a user?
+
+There are situations where you as a user need to influence the build process.
+This can be adding custom compiler flags, include directories, linker flags, etc.  
+**If you are the library author you should consider using CMake for doing these thing.
+The following is mainly intended for the end-user.**
+
+## Automatic flags added by `CMAKE_BUILD_TYPE`
+
+Targets provide modularization and encapsulation. A target
+encapsulates everything needed for a certain build job. It also
+is some kind of container that allows efficient use as a building 
+block.
+
+| CMAKE_BUILD_TYPE | Compiler Flags                           | Linker Flags     |
+|------------------|------------------------------------------|------------------|
+| Debug            | `-g`                                     |                  |
+| Release          | `-O3 -DNDEBUG`                           |                  |
+| RelWithDebInfo   | `-O2 -g -DNDEBUG`                        |                  |
+| MinSizeRel       | `-Os -DNDEBUG`                           |                  |
+
+There is no default build type! If you do not specify a build types no flags will be added.
+
+## CMake uses common environment variables to modify the compiler and linker commands.
+CMake uses environment variables like `CFLAGS`, `CXXFLAGS`, `LDFLAGS`, ... to initialize its internal variables [[Ref]](https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_FLAGS.html#variable:CMAKE_%3CLANG%3E_FLAGS).  
+**CAUTION! the internal variables are set during the first configure call and are cached. Meaning, subsequent changes to the environment variables will not be followed by CMake. To make CMake aware of this you can either delete and recreate the build folder or use `--fresh`[[Ref]](https://cmake.org/cmake/help/latest/manual/cmake.1.html#cmdoption-cmake-fresh).**
+
+## Set target properties
+| Aim                                    | Command                                                                                                   |
+|----------------------------------------|-----------------------------------------------------------------------------------------------------------|
+| add definitions                        | [target_compile_definitions](https://cmake.org/cmake/help/latest/command/target_compile_definitions.html) | 
+| add compile flags                      | [target_compile_options](https://cmake.org/cmake/help/latest/command/target_compile_options.html)         |
+| add include directories                | [target_include_directories](https://cmake.org/cmake/help/latest/command/target_include_directories.html) |
+| add a dependency, link against library | [target_link_libraries](https://cmake.org/cmake/help/latest/command/target_link_libraries.html)           |
+| add linker options                     | [target_link_options](https://cmake.org/cmake/help/latest/command/target_link_options.html)               |
+| add sources                            | [target_sources](https://cmake.org/cmake/help/latest/command/target_sources.html)                         |
+
+## Usage requirements
+https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#transitive-usage-requirements
+
+| keyword       | result                                                       |
+|---------------|--------------------------------------------------------------|
+| **PRIVATE**   | required to build the target, but not required when using it |
+| **INTERFACE** | not required to build the target, but required when using it |
+| **PUBLIC**    | required for for building the target and for using it        |
+
+## How to link against a "supported" third-party library?
+Find the library with [find_package](https://cmake.org/cmake/help/latest/command/find_package.html) and link against 
+the imported target with [target_link_libraries](https://cmake.org/cmake/help/latest/command/target_link_libraries.html).
\ No newline at end of file

11_customization/main.cpp

+#include <iostream>
+
+int main(int /*argc*/, char** /*argv*/)
+{
+    std::cout << "Hallo World" << std::endl;
+    exit(EXIT_SUCCESS);
+}

README.md

@@ -20,6 +20,7 @@ we run them in our CI.
  * [How to manage all the tests in your project?](08_ctest)
  * [How to install a project with CMake?](09_install)
  * [How to add compilation configurations to your project?](10_presets)
+ * [How can I influence the build process as a user?](11_customization)
 
 ## Why CMake?
  * Automatically search for programs, libraries, and header files
@@ -65,26 +66,28 @@ environment variable `LibraryName_ROOT` for the library.
  * https://cliutils.gitlab.io/modern-cmake/
  * https://cmake.org/cmake/help/book/mastering-cmake/
  * https://jeremimucha.com/category/cmake/
+ * https://github.com/friendlyanon/cmake-init (C++)
+ * https://github.com/fortuno-repos/cookiecutter-fortran-project (Fortran)
 
 ### What minimum required version should I choose?
 OS support:
- * 3.4: The bare minimum. Never set less.
- * 3.7: Debian old-stable.
- * 3.10: Ubuntu 18.04.
- * 3.11: CentOS 8 (use EPEL or AppSteams)
- * 3.13: Debian stable.
+ * 3.14: **The bare minimum. Never set less.** (FWIW, this is also what [cmake-init](https://github.com/friendlyanon/cmake-init) uses)
  * 3.16: Ubuntu 20.04.
+ * 3.18: Debian 11 (oldstable).
  * 3.19: First to support Apple Silicon.
+ * 3.20: CentOS 8/9 (use AppSteam; 3.26 also available).
+ * 3.22: Ubuntu 22.04.
+ * 3.25: Debian 12 (stable).
+ * 3.28: Ubuntu 24.04.
  * latest: pip/conda-forge/homebew/chocolaty
 
 Features:
- * 3.8: C++ meta features, CUDA, lots more
- * 3.11: IMPORTED INTERFACE setting, faster, FetchContent, COMPILE_LANGUAGE in IDEs
- * 3.12: C++20, cmake --build build -j N, SHELL:, FindPython
  * 3.14/3.15: CLI, FindPython updates
  * 3.16: Unity builds / precompiled headers, CUDA meta features
  * 3.17/3.18: Lots more CUDA, metaprogramming
+ * 3.21: HIP language support
+ * 3.25: compiling HIP for NVIDIA GPUs
 
-[Source](https://cliutils.gitlab.io/modern-cmake/chapters/intro/dodonot.html)
+Adapted from [Do's and Don'ts (Modern CMake)](https://cliutils.gitlab.io/modern-cmake/chapters/intro/dodonot.html)