add c++20 module support (#157)

* add constexpr alternatives for const macros

* add condy.cppm module interface

* add condy_module target and module-hello example

* add docs for module support

* add module ci check

Author: wokron

.github/workflows/ci-toolchain.yml

@@ -57,3 +57,23 @@ jobs:
         timeout-minutes: 5
         working-directory: ${{github.workspace}}/build
         run: ctest --verbose
+
+      - name: Build module-hello
+        # liburing < 2.13 exposes TU-local entities that break GCC modules
+        # https://github.com/axboe/liburing/issues/1457
+        if: >
+          matrix.generator == 'Ninja'
+          && !(matrix.compiler.cc == 'gcc' && matrix.liburing-version == '2.3')
+        run: |
+          cmake -B ${{github.workspace}}/build_module -G Ninja \
+              -DBUILD_MODULE=ON \
+              -DBUILD_EXAMPLES=ON \
+              -DCMAKE_C_COMPILER=${{ matrix.compiler.cc }} \
+              -DCMAKE_CXX_COMPILER=${{ matrix.compiler.cxx }}
+          ninja -C ${{github.workspace}}/build_module module-hello
+
+      - name: Run module-hello
+        if: >
+          matrix.generator == 'Ninja'
+          && !(matrix.compiler.cc == 'gcc' && matrix.liburing-version == '2.3')
+        run: ${{github.workspace}}/build_module/examples/module-hello

CMakeLists.txt

@@ -5,6 +5,7 @@ project(condy LANGUAGES CXX)
 option(BUILD_EXAMPLES "Build examples" OFF)
 option(BUILD_BENCHMARKS "Build benchmarks" OFF)
 option(BUILD_TESTS "Build tests" OFF)
+option(BUILD_MODULE "Build C++ module interface" OFF)
 option(ENABLE_CLANG_TIDY "Enable clang-tidy static analysis" OFF)
 option(TESTS_STATIC_LINK "Use static linking for tests" OFF)
 option(TESTS_TSAN "Enable thread sanitizer for tests" OFF)
@@ -25,7 +26,7 @@ add_library(condy INTERFACE)
 target_include_directories(condy INTERFACE include)
 target_compile_features(condy INTERFACE cxx_std_20)
 
-if(BUILD_EXAMPLES OR BUILD_BENCHMARKS OR BUILD_TESTS OR LINK_LIBURING)
+if(BUILD_EXAMPLES OR BUILD_BENCHMARKS OR BUILD_TESTS OR LINK_LIBURING OR BUILD_MODULE)
     enable_language(C)
     include(ExternalProject)
 
@@ -60,6 +61,12 @@ if(LINK_LIBURING)
     target_link_libraries(condy INTERFACE uring)
 endif()
 
+if(BUILD_MODULE)
+    set(CMAKE_CXX_SCAN_FOR_MODULES ON)
+    message(STATUS "Configuring C++ module interface in ${CMAKE_CURRENT_SOURCE_DIR}/module")
+    add_subdirectory(module)
+endif()
+
 # Warnings as errors
 add_compile_options(-Wall -Wextra -Werror)
 if(CMAKE_CXX_COMPILER_ID MATCHES "GNU")

docs/build.md

@@ -68,6 +68,42 @@ ctest --test-dir build
 ./build/examples/link-cp from.bin to.bin
 ```
 
+## C++20 Module Support
+
+Condy provides an optional C++20 module interface as an alternative to `#include <condy.hpp>`.
+
+```cpp
+import condy;
+```
+
+### Requirements
+
+- **CMake 3.28+** with **Ninja** generator
+- **GCC 14+** or **Clang 16+**
+
+### Building the Example
+
+```bash
+cmake -B build -S . -G Ninja \
+    -DBUILD_MODULE=ON \
+    -DBUILD_EXAMPLES=ON
+ninja -C build module-hello
+
+./build/examples/module-hello
+# Hello, Condy (via module)!
+```
+
+### Using in Your Project
+
+The module target is `condy_module`:
+
+```cmake
+set(BUILD_MODULE ON CACHE BOOL "")
+add_subdirectory(third_party/condy)
+add_executable(my_app src/main.cpp)
+target_link_libraries(my_app PRIVATE condy_module)
+```
+
 ## Version Compatibility
 
 Condy supports **liburing ≥ 2.3**. When building with a specific version of liburing, Condy assumes that all related interfaces provided by that version are already supported by your Linux kernel.

docs/examples.md

@@ -19,3 +19,6 @@
 
 - [queue-kernel-futex.cpp](queue-kernel-futex_8cpp_source.html)
     Builds a producer-consumer queue through asynchronous futex syscalls (`condy::async_futex_wait()`), implementing an asynchronous semaphore for synchronization.
+
+- [module-hello.cpp](module-hello_8cpp_source.html)
+    Demonstrates using Condy as a C++20 module via `import condy;`. Requires CMake 3.28+, Ninja, and GCC 14+ or Clang 16+. Build with `-DBUILD_MODULE=ON`.

examples/CMakeLists.txt

@@ -14,4 +14,9 @@ add_executable(queue-kernel-futex queue-kernel-futex.cpp)
 target_link_libraries(queue-kernel-futex PRIVATE condy uring)
 
 add_executable(queue-condy-futex queue-condy-futex.cpp)
-target_link_libraries(queue-condy-futex PRIVATE condy uring)
+target_link_libraries(queue-condy-futex PRIVATE condy uring)
+
+if(BUILD_MODULE)
+    add_executable(module-hello module-hello.cpp)
+    target_link_libraries(module-hello PRIVATE condy_module uring)
+endif()

examples/module-hello.cpp

@@ -0,0 +1,12 @@
+#include <coroutine>
+#include <string>
+#include <unistd.h>
+
+import condy;
+
+condy::Coro<> co_main() {
+    std::string msg = "Hello, Condy (via module)!\n";
+    co_await condy::async_write(STDOUT_FILENO, condy::buffer(msg), 0);
+}
+
+int main() noexcept(false) { condy::sync_wait(co_main()); }

include/condy/helpers.hpp

@@ -26,6 +26,11 @@
 
 namespace condy {
 
+/**
+ * @brief Placeholder to let io_uring allocate a direct file descriptor.
+ */
+inline constexpr unsigned file_index_alloc = CONDY_FILE_INDEX_ALLOC;
+
 /**
  * @brief Helper to build an invocable that spawns a coroutine on invocation.
  * @tparam CoroFunc Type of the coroutine function.

include/condy/version.hpp

@@ -4,5 +4,26 @@
 
 #pragma once
 
+/**
+ * @brief Condy major version.
+ */
 #define CONDY_VERSION_MAJOR 1
+
+/**
+ * @brief Condy minor version.
+ */
 #define CONDY_VERSION_MINOR 8
+
+namespace condy {
+
+/**
+ * @brief Condy major version.
+ */
+inline constexpr int version_major = CONDY_VERSION_MAJOR;
+
+/**
+ * @brief Condy minor version.
+ */
+inline constexpr int version_minor = CONDY_VERSION_MINOR;
+
+} // namespace condy

module/CMakeLists.txt

@@ -0,0 +1,9 @@
+cmake_minimum_required(VERSION 3.28)
+
+add_library(condy_module)
+target_sources(condy_module
+    PUBLIC FILE_SET CXX_MODULES
+    FILES condy.cppm
+)
+target_compile_features(condy_module PUBLIC cxx_std_20)
+target_link_libraries(condy_module PUBLIC condy)