C++ Modules

STX provides full C++23 modules support as an alternative to traditional header-only usage, offering faster compilation times and better dependency management.

Why Use Modules?

Faster Compilation

Modules are compiled once and reused, reducing rebuild times

Better Isolation

No macro leakage or header pollution between translation units

Cleaner Imports

Replace #include with clean import statements

Improved Build Scaling

Better parallelization and dependency tracking

System Requirements

C++ Modules require modern toolchains. Ensure you meet these minimum requirements:

Build System

CMake: 3.28 or later
Xmake: 2.8.0 or later

Compilers

Compiler	Minimum Version	Notes
Clang	16.0+	Recommended for best modules support
GCC	14.0+	Requires `-fmodules-ts` flag
MSVC	19.34+ (VS 2022 17.4+)	Windows only

Available Modules

STX provides these module units:

Module	Import Statement	Description
stx	`import lbyte.stx;`	All STX utilities (recommended)
core	`import lbyte.stx.core;`	Core types and utilities
mem	`import lbyte.stx.mem;`	Memory utilities
time	`import lbyte.stx.time;`	Time and stopwatch utilities

Setup Instructions

CMake
Xmake

Enable modules in CMake

Set the module option before adding STX:

set(STX_USE_MODULES ON CACHE BOOL "" FORCE)
add_subdirectory(extern/stx)
# or with FetchContent:
# FetchContent_MakeAvailable(stx)

Link against STX

target_link_libraries(your-target PRIVATE lbyte::stx)

Use in your code

import lbyte.stx;

using namespace stx;

auto main() -> int {
    // Use STX utilities
    return 0;
}

Enable modules in package config

add_requires( "zethcxx.stx v2.0.0", { 
    configs = { use_modules = true } 
})

Configure target policies

target("your-target")
    set_kind("binary")
    set_languages("cxx23")
    add_packages("zethcxx.stx")
    
    -- Enable module compilation
    set_policy("build.c++.modules", true)
    
    -- Optional: disable if std module issues occur
    set_policy("build.c++.modules.std", false)

Use in your code

import lbyte.stx;

using namespace stx;

auto main() -> int {
    // Use STX utilities
    return 0;
}

Troubleshooting

Missing Clang Resource Headers

When using C++ Modules with Clang, you might encounter errors like:

fatal error: 'stddef.h' file not found
fatal error: '__stddef_max_align_t.h' file not found

Cause: The compiler cannot locate its internal resource directory.

Identify your Clang version

clang++ --version

Find the resource directory

clang++ -print-resource-dir
# Example output: /usr/lib/clang/21

Export the include path

Add the include subdirectory to your environment:

# For Clang 21 (adjust version as needed)
export CPLUS_INCLUDE_PATH="/usr/lib/clang/21/include/:$CPLUS_INCLUDE_PATH"

Make this permanent by adding to your shell profile (~/.bashrc, ~/.zshrc, etc.)

Rebuild your project

cmake --build build --clean-first
# or
xmake -r

This issue is most common on Linux systems with manually installed Clang. System-provided Clang packages typically configure this automatically.

Module BMI Cache Issues

If you encounter stale module cache errors:

# Clear CMake cache and rebuild
rm -rf build/
cmake -B build
cmake --build build

Standard Library Module Conflicts

With Xmake, if you encounter issues with standard library modules:

set_policy("build.c++.modules.std", false)

This disables automatic standard library module imports, resolving conflicts with certain compiler configurations.

Compiler-Specific Notes

Clang

Use Clang 16+ for stable modules support
Clang 18+ recommended for best compatibility
Ensure libc++ is available if using on Linux

GCC

Requires GCC 14+ with -fmodules-ts
Module support is experimental; prefer Clang if issues arise
May require additional flags: -std=c++23 -fmodules-ts

MSVC

Requires Visual Studio 2022 17.4+ (MSVC 19.34+)
Enable in project properties: C/C++ → Language → Enable C++ Modules: Yes
Ensure /std:c++latest is set

Performance Considerations

First Build

Initial module compilation may take longer as BMI (Binary Module Interface) files are generated

Incremental Builds

Subsequent builds are significantly faster since modules are pre-compiled

Fallback to Header-Only

If you encounter persistent issues with modules, STX gracefully falls back to header-only mode:

# Simply omit or set to OFF
set(STX_USE_MODULES OFF)
add_subdirectory(extern/stx)

Then use traditional includes:

#include <lbyte/stx.hpp>

Get Started

Core Concepts

Integration

Examples

C++ Modules

Why Use Modules?

Faster Compilation

Better Isolation

Cleaner Imports

Improved Build Scaling

System Requirements

Build System

Compilers

Available Modules

Setup Instructions

Troubleshooting

Missing Clang Resource Headers

Module BMI Cache Issues

Standard Library Module Conflicts

Compiler-Specific Notes

Performance Considerations

First Build

Incremental Builds

Fallback to Header-Only

Next Steps

CMake Integration

Xmake Integration

Build docs developers (and LLMs) love

Get Started

Core Concepts

Integration

Examples

​Why Use Modules?

Faster Compilation

Better Isolation

Cleaner Imports

Improved Build Scaling

​System Requirements

​Build System

​Compilers

​Available Modules

​Setup Instructions

​Troubleshooting

​Missing Clang Resource Headers

​Module BMI Cache Issues

​Standard Library Module Conflicts

​Compiler-Specific Notes

​Performance Considerations

First Build

Incremental Builds

​Fallback to Header-Only

​Next Steps

CMake Integration

Xmake Integration

Build docs developers (and LLMs) love

Why Use Modules?

System Requirements

Build System

Compilers

Available Modules

Setup Instructions

Troubleshooting

Missing Clang Resource Headers

Module BMI Cache Issues

Standard Library Module Conflicts

Compiler-Specific Notes

Performance Considerations

Fallback to Header-Only

Next Steps