C++ Module Support

[sgerbino]

Summary

Add support for C++20 modules to improve compile times and provide a modern interface for users.

Motivation

C++20 modules offer several benefits over traditional header-based inclusion:

• Faster compile times - Modules are parsed once and cached, eliminating redundant parsing of headers across translation units
• Better encapsulation - Implementation details can be hidden without relying on naming conventions or separate detail headers
• No macro leakage - Macros defined in module implementation don't affect importers
• Explicit dependency declarations - import statements make dependencies clear and enforceable

As a coroutine-heavy library, capy would particularly benefit from modules since coroutine code tends to be header-heavy with significant template instantiation costs.

Proposed Approach

Phase 1: Primary Module Interface

Create a primary module interface that exports the public API:

// src/capy.cppm
export module boost.capy;

export import :task;
export import :when_all;
export import :async_run;
export import :thread_pool;
// ...

Phase 2: Module Partitions

Split into logical partitions for better organization:

boost.capy           - Primary module interface
boost.capy:task      - task<T> and related utilities
boost.capy:when_all  - when_all combinator
boost.capy:async_run - async_run launcher
boost.capy:concepts  - dispatcher, awaitable concepts
boost.capy:buffers   - Buffer types and utilities

Phase 3: Dual Support

Maintain header support alongside modules for backwards compatibility:

// Users can choose:
import boost.capy;           // Module import
// or
#include <boost/capy.hpp>    // Traditional header

Tasks

• Investigate CMake module support (requires CMake 3.28+)
• Audit headers for macro usage that would need adjustment
• Determine minimum compiler versions (GCC 14+, Clang 16+, MSVC 19.34+)
• Create module interface units (.cppm files)
• Add module build configuration to CMakeLists.txt
• Update CI to test module builds (VF: We don't want to fail builds for modules)
• Document module usage in README
• Ensure Boost compatibility guidelines are followed

Considerations

Compiler Support

Compiler	Minimum Version	Notes
GCC	14+	Full module support
Clang	16+	Full module support
MSVC	19.34+	VS 2022 17.4+

Build System

CMake 3.28+ has native C++20 module support via CXX_MODULES target property. Earlier versions require workarounds.

Boost Integration

Need to coordinate with Boost's broader modules strategy. Some dependencies (Boost.Assert, etc.) may not have module support yet, requiring careful handling at module boundaries.

Standard Library Modules

Consider whether to depend on import std; (C++23) or maintain compatibility with C++20's header units.

References

• P1103R3 - Merging Modules
• CMake C++20 Modules
• Boost C++ Libraries Modules Discussion