Feature/prepare cxx modules support (#194)

* Feat: pre-commit autoupdate and apply

* Feat: Prepare CXX_MODULES build support

* Make distclean better

* Add the execution.cppm module again

* Remove codespell hook from black section

---------

Co-authored-by: Dietmar Kühl <[email protected]>
Co-authored-by: Dietmar Kühl <[email protected]>

Author: ClausKlein

.cmake-format

@@ -37,12 +37,15 @@ CMakeUserPresets.json
 build
 .DS_store
 .vs
+.cache
 .vscode
+compile_commands.json
 stagedir
 
 # In-source builds are not allowed
 CMakeCache.txt
 CMakeFiles/
 
+*.log
 docs/html
 docs/latex

.gitignore

@@ -11,9 +11,18 @@ repos:
         exclude: ^\.clang-(format|tidy)$
       - id: check-added-large-files
 
+  # Config file: .codespellrc
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.1
+    hooks:
+      - id: codespell
+        files: ^.*\.(cmake|cpp|hpp|txt|md|json|in|yaml|yml|py|toml)$
+        args: ["--write", "--ignore-words", ".codespellignore" ]
+
   # Clang-format for C++
   # This brings in a portable version of clang-format.
   # See also: https://github.com/ssciwr/clang-format-wheel
+  # Config file: .clang-format
   - repo: https://github.com/pre-commit/mirrors-clang-format
     rev: v21.1.7
     hooks:
@@ -36,11 +45,18 @@ repos:
   #   hooks:
   #     - id: markdownlint
 
-  - repo: https://github.com/codespell-project/codespell
-    rev: v2.4.1
+  # Config file: pyproject.toml
+  # first Python sort imports
+  - repo: https://github.com/pycqa/isort
+    rev: 7.0.0
     hooks:
-      - id: codespell
-        files: ^.*\.(cmake|cpp|hpp|txt|md|json|in|yaml|yml)$
-        args: ["-w", "--ignore-words", ".codespellignore" ]
+      - id: isort
+
+  # Config file: pyproject.toml
+  # second Python code formatting
+  - repo: https://github.com/psf/black
+    rev: 25.11.0
+    hooks:
+      - id: black
 
 exclude: 'infra/'

.pre-commit-config.yaml

@@ -1,11 +1,28 @@
-# cmake-format: off
+# gersemi: off
 # /CMakeLists.txt -*-makefile-*-
 # SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
-# cmake-format: on
+# gersemi: on
 
 cmake_minimum_required(VERSION 3.25...4.2)
 
+#========================== pre project settings ===============================
+# gersemi: off
+if(CMAKE_VERSION VERSION_EQUAL 4.2)
+    set(CMAKE_EXPERIMENTAL_CXX_IMPORT_STD "d0edc3af-4c50-42ea-a356-e2862fe7a444")
+
+    if(CMAKE_CXX_STDLIB_MODULES_JSON)
+        message(
+            STATUS
+            "CMAKE_CXX_STDLIB_MODULES_JSON=${CMAKE_CXX_STDLIB_MODULES_JSON}"
+        )
+    endif()
+endif()
+# gersemi: on
+#===============================================================================
+
+#===================================================
 project(beman_execution VERSION 0.0.1 LANGUAGES CXX)
+#===================================================
 
 if(${CMAKE_SOURCE_DIR} STREQUAL ${CMAKE_BINARY_DIR})
     message(FATAL_ERROR "In-source builds are not allowed!")
@@ -17,7 +34,45 @@ set(TARGET_PREFIX ${TARGET_NAMESPACE}.${TARGET_NAME})
 set(TARGET_LIBRARY ${PROJECT_NAME})
 set(TARGET_ALIAS ${TARGET_NAMESPACE}::${TARGET_NAME})
 set(TARGET_PACKAGE_NAME ${PROJECT_NAME}-config)
-set(TARGETS_EXPORT_NAME ${PROJECT_NAME}-targets)
+set(TARGETS_EXPORT_NAME ${PROJECT_NAME}-config-targets)
+
+#========================== post project settings ==============================
+# Tell CMake that we explicitly want `import std`.
+# This will initialize the property on all targets declared after this to 1
+message(STATUS "CMAKE_CXX_COMPILER_IMPORT_STD=${CMAKE_CXX_COMPILER_IMPORT_STD}")
+if(${CMAKE_CXX_STANDARD} IN_LIST CMAKE_CXX_COMPILER_IMPORT_STD)
+    set(CMAKE_CXX_MODULE_STD ON)
+    message(STATUS "CMAKE_CXX_MODULE_STD=${CMAKE_CXX_MODULE_STD}")
+endif()
+
+if(CMAKE_CXX_SCAN_FOR_MODULES AND ${CMAKE_GENERATOR} STREQUAL Ninja)
+    set(BEMAN_USE_MODULES ON)
+    message(STATUS "BEMAN_USE_MODULES=${BEMAN_USE_MODULES}")
+else()
+    message(WARNING "Missing support for CMAKE_CXX_SCAN_FOR_MODULES!")
+endif()
+
+# gersemi: off
+if(CMAKE_EXPORT_COMPILE_COMMANDS)
+    set(CMAKE_CXX_STANDARD_INCLUDE_DIRECTORIES ${CMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES})
+    message(
+        STATUS
+        "CMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES=${CMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES}"
+    )
+endif()
+# gersemi: on
+
+# CMake requires the language standard to be specified as compile feature
+# when a target provides C++23 modules and the target will be installed
+add_library(${TARGET_NAME} STATIC)
+target_compile_features(${TARGET_NAME} PUBLIC cxx_std_23)
+
+if(BEMAN_USE_MODULES AND CMAKE_CXX_MODULE_STD)
+    target_compile_definitions(${TARGET_NAME} PUBLIC BEMAN_HAS_IMPORT_STD)
+else()
+    message(WARNING "Missing support for CMAKE_CXX_MODULE_STD!")
+endif()
+#===============================================================================
 
 option(
     BEMAN_EXECUTION_ENABLE_TESTING

CMakeLists.txt

@@ -8,8 +8,12 @@
       "binaryDir": "${sourceDir}/build/${presetName}",
       "cacheVariables": {
         "CMAKE_CXX_STANDARD": "23",
-        "CMAKE_EXPORT_COMPILE_COMMANDS": "ON",
-        "CMAKE_PROJECT_TOP_LEVEL_INCLUDES": "./infra/cmake/use-fetch-content.cmake"
+        "CMAKE_CXX_EXTENSIONS": true,
+        "CMAKE_CXX_SCAN_FOR_MODULES": false,
+        "CMAKE_CXX_STANDARD_REQUIRED": true,
+        "CMAKE_EXPORT_COMPILE_COMMANDS": true,
+        "CMAKE_SKIP_TEST_ALL_DEPENDENCY": false,
+        "CMAKE_PROJECT_TOP_LEVEL_INCLUDES": "infra/cmake/use-fetch-content.cmake"
       }
     },
     {

CMakePresets.json

@@ -31,14 +31,42 @@ endif
 LDFLAGS   ?=
 SAN_FLAGS ?=
 CXX_FLAGS ?= -g
+# TODO: SANITIZER := release
 SANITIZER ?= default
 SOURCEDIR = $(CURDIR)
 BUILDROOT = build
-SYSTEM    = $(shell uname -s)
-BUILD     = $(BUILDROOT)/$(SYSTEM)/$(SANITIZER)
+export hostSystemName:=$(shell uname -s)
+# TODO BUILD     := $(BUILDROOT)/$(SANITIZER)
+BUILD     ?= $(BUILDROOT)/$(hostSystemName)/$(SANITIZER)
 EXAMPLE   = beman.execution.examples.stop_token
 
-export CXX=$(COMPILER)
+################################################
+ifeq (${hostSystemName},Darwin)
+	export LLVM_PREFIX:=$(shell brew --prefix llvm)
+  export LLVM_DIR:=$(shell realpath ${LLVM_PREFIX})
+  export PATH:=${LLVM_DIR}/bin:${PATH}
+
+  # export CMAKE_CXX_STDLIB_MODULES_JSON=${LLVM_DIR}/lib/c++/libc++.modules.json
+  # export CXX=clang++
+  # export LDFLAGS=-L$(LLVM_DIR)/lib/c++ -lc++abi -lc++ # -lc++experimental
+  # export GCOV="llvm-cov gcov"
+
+  ### TODO: to test g++-15:
+  export GCC_PREFIX:=$(shell brew --prefix gcc)
+  export GCC_DIR:=$(shell realpath ${GCC_PREFIX})
+
+  export CMAKE_CXX_STDLIB_MODULES_JSON=${GCC_DIR}/lib/gcc/current/libstdc++.modules.json
+  export CXX:=g++-15
+  export CXXFLAGS:=-stdlib=libstdc++
+  export GCOV="gcov"
+else ifeq (${hostSystemName},Linux)
+  export LLVM_DIR=/usr/lib/llvm-20
+  export PATH:=${LLVM_DIR}/bin:${PATH}
+  export CXX=clang++-20
+else
+  export CXX=$(COMPILER)
+endif
+################################################
 
 ifeq ($(SANITIZER),release)
     CXX_FLAGS = -O3 -Wpedantic -Wall -Wextra -Wno-shadow -Werror
@@ -66,6 +94,9 @@ ifeq ($(SANITIZER),lsan)
     LDFLAGS = $(SAN_FLAGS)
 endif
 
+# TODO: beman.execution.examples.modules
+# FIXME: beman.execution.execution-module.test beman.execution.stop-token-module.test
+
 default: test
 
 all: $(SANITIZERS)
@@ -80,29 +111,33 @@ doc:
 # 	$(MAKE) SANITIZER=$@
 
 build:
-	cmake --fresh -G Ninja -S $(SOURCEDIR) -B  $(BUILD) $(TOOLCHAIN) $(SYSROOT) \
-	  -D CMAKE_EXPORT_COMPILE_COMMANDS=1 \
-	  -D CMAKE_SKIP_INSTALL_RULES=1 \
+	cmake --fresh -G Ninja -S $(SOURCEDIR) -B $(BUILD) $(TOOLCHAIN) $(SYSROOT) \
+	  -D CMAKE_EXPORT_COMPILE_COMMANDS=ON \
+	  -D CMAKE_SKIP_INSTALL_RULES=ON \
 	  -D CMAKE_CXX_STANDARD=23 \
+	  -D CMAKE_CXX_EXTENSIONS=ON \
+	  -D CMAKE_CXX_STANDARD_REQUIRED=ON \
 	  -D CMAKE_CXX_COMPILER=$(CXX) # XXX -D CMAKE_CXX_FLAGS="$(CXX_FLAGS) $(SAN_FLAGS)"
 	cmake --build $(BUILD)
 
-# NOTE: without install! CK
+# NOTE: without install, see CMAKE_SKIP_INSTALL_RULES! CK
 test: build
 	ctest --test-dir $(BUILD) --rerun-failed --output-on-failure
 
 install: test
 	cmake --install $(BUILD) --prefix /opt/local
 
-CMakeUserPresets.json: cmake/CMakeUserPresets.json
+CMakeUserPresets.json:: cmake/CMakeUserPresets.json
 	ln -s $< $@
 
 release: CMakeUserPresets.json
-	cmake --preset $@ --fresh --log-level=TRACE
+	cmake --preset $@ --log-level=TRACE # XXX --fresh
+	ln -fs $(BUILDROOT)/$@/compile_commands.json .
 	cmake --workflow --preset $@
 
 debug: CMakeUserPresets.json
-	cmake --preset $@ --fresh --log-level=TRACE
+	cmake --preset $@ --log-level=TRACE # XXX --fresh
+	ln -fs $(BUILDROOT)build/$@/compile_commands.json .
 	cmake --workflow --preset $@
 
 ce:
@@ -123,18 +158,21 @@ check:
 build/$(SANITIZER)/compile_commands.json: $(SANITIZER)
 
 clang-tidy: $(BUILD)/compile_commands.json
+	ln -fs $< .
 	run-clang-tidy -p $(BUILD) tests examples
 
 codespell:
-	codespell -L statics,snd,copyable,cancelled
+	pre-commit run $@
 
-format: cmake-format clang-format
+format:
+	pre-commit run --all
 
 cmake-format:
-	pre-commit run --all
+	pre-commit run gersemi
 
 clang-format:
-	git clang-format main
+	pre-commit run $@
+	# XXX TBD: git clang-format main
 
 todo:
 	bin/mk-todo.py
@@ -147,8 +185,17 @@ clean-doc:
 	$(RM) -r docs/html docs/latex
 
 clean: clean-doc
-	cmake --build $(BUILD) --target clean
-	$(RM) mkerr olderr *~
+	-cmake --build $(BUILD) --target clean
+	$(RM) mkerr olderr compile_commands.json
 
 distclean: clean
-	$(RM) -r $(BUILDROOT) stagedir
+	$(RM) -r $(BUILDROOT) stagedir CMakeUserPresets.json
+	find . -name '*~' -delete
+
+Makefile :: ;
+*.txt :: ;
+*.json :: ;
+
+# Anything we don't know how to build will use this rule.
+% ::
+	ninja -C $(BUILD) $(@)

Makefile

@@ -1,5 +1,5 @@
 {
-  "version": 6,
+  "version": 9,
   "include": [
     "CMakeGenericPresets.json"
   ],
@@ -8,6 +8,7 @@
       "name": "debug-base-Darwin",
       "hidden": true,
       "cacheVariables": {
+        "CMAKE_CXX_STDLIB_MODULES_JSON": "$env{CMAKE_CXX_STDLIB_MODULES_JSON}",
         "CMAKE_BUILD_TYPE": "Debug"
       },
       "condition": {
@@ -20,6 +21,7 @@
       "name": "release-base-Darwin",
       "hidden": true,
       "cacheVariables": {
+        "CMAKE_CXX_STDLIB_MODULES_JSON": "$env{CMAKE_CXX_STDLIB_MODULES_JSON}",
         "CMAKE_BUILD_TYPE": "RelWithDebInfo"
       },
       "condition": {

cmake/presets/CMakeDarwinPresets.json

@@ -12,8 +12,9 @@
           "type": "path",
           "value": "${sourceDir}/stagedir"
         },
-        "CMAKE_CXX_EXTENSIONS": true,
         "CMAKE_CXX_STANDARD": "23",
+        "CMAKE_CXX_EXTENSIONS": true,
+        "CMAKE_CXX_SCAN_FOR_MODULES": true,
         "CMAKE_CXX_STANDARD_REQUIRED": true,
         "CMAKE_EXPORT_COMPILE_COMMANDS": true,
         "CMAKE_SKIP_TEST_ALL_DEPENDENCY": false

cmake/presets/CMakeGenericPresets.json

@@ -8,6 +8,7 @@
       "name": "debug-base-Linux",
       "hidden": true,
       "cacheVariables": {
+        "CMAKE_CXX_STDLIB_MODULES_JSON": "$env{CMAKE_CXX_STDLIB_MODULES_JSON}",
         "CMAKE_BUILD_TYPE": "Debug"
       },
       "condition": {
@@ -20,6 +21,7 @@
       "name": "release-base-Linux",
       "hidden": true,
       "cacheVariables": {
+        "CMAKE_CXX_STDLIB_MODULES_JSON": "$env{CMAKE_CXX_STDLIB_MODULES_JSON}",
         "CMAKE_BUILD_TYPE": "RelWithDebInfo"
       },
       "condition": {

cmake/presets/CMakeLinuxPresets.json

@@ -1,7 +1,7 @@
-# cmake-format: off
+# gersemi: off
 # examples/CMakeLists.txt -*-makefile-*-
 # SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
-# cmake-format: on
+# gersemi: on
 
 list(
     APPEND EXAMPLES
@@ -21,6 +21,10 @@ list(
     doc-just_stopped
 )
 
+if(BEMAN_USE_MODULES)
+    list(APPEND EXAMPLES modules) # modules.cpp
+endif()
+
 foreach(EXAMPLE ${EXAMPLES})
     set(EXAMPLE_TARGET ${TARGET_PREFIX}.examples.${EXAMPLE})
     add_executable(${EXAMPLE_TARGET})