A Cargo-inspired build system for C++23 Modules, written in Rust.
中文文档
What is cppx?
cppx is a build system designed for modern C++ projects that fully embrace C++20/23 Modules (no #include). It aims to provide the same developer experience as Rust's Cargo:
cppx new my-project # Create a new project
cppx build # Just works
cppx run # Build and run
cppx run -- arg1 arg2 # Pass arguments to the binary
cppx test # Build and run tests
cppx fuzz fuzz_math::add # Fuzz testing
cppx clean # Clean build artifacts
Why cppx?
C++ Modules fundamentally change how C++ code is compiled. Unlike traditional #include, modules require:
- BMI (Binary Module Interface) must exist before consumers compile — compilation order matters
- Module names are decoupled from file paths — an external scan phase is needed
- An external dependency scanner is required —
clang-scan-deps implements P1689
Existing build systems (CMake, Meson, etc.) treat modules as an add-on to their existing model. cppx is built from the ground up for modules, automating the entire scan → schedule → compile pipeline.
Status
⚠️ Experimental — cppx is in early development (v0.1.0). The API and configuration format may change.
Features
- 🚀 Zero-config — Convention over configuration; file paths determine module names
- 🔍 Automatic dependency scanning —
clang-scan-deps → DAG → topological parallel compilation
- ⚡ Incremental builds — Fingerprint-based cache (content hash for sources, mtime+size for PCM deps)
- 📦 Dependency management —
[dependencies] in cppx.toml with SemVer + PubGrub resolution
- 🧪 Built-in test runner —
cppx test auto-discovers and runs tests
- 🐛 Native fuzz testing —
cppx fuzz with libFuzzer, dual signature support, crash reproduction
- 🏗️ Library support — Static and dynamic libraries with BMI distribution
Quick Start
Prerequisites
- Rust toolchain (for building cppx itself)
- A C++ compiler with full C++20/23 Modules support:
- Clang 19+ with
clang-scan-deps (macOS, Linux)
- MSVC (Visual Studio 2022 17.6+) on Windows
Windows Setup (MSVC)
On Windows, cppx needs the MSVC environment variables (PATH, INCLUDE, LIB) to be configured. The easiest way:
Option A: Use the Developer Command Prompt (recommended)
Open "x64 Native Tools Command Prompt for VS 2022" from the Start Menu, then run cppx build from there.
Option B: Run vcvarsall.bat manually
:: Common locations (adjust edition: Community / Professional / Enterprise):
"C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvarsall.bat" x64
:: Then use cppx normally:
cppx build
Option C: Set CPPX_CL environment variable
set CPPX_CL=C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC\14.43.34808\bin\Hostx64\x64\cl.exe
Note: The version number (14.43.34808) varies by installation. Check your VC\Tools\MSVC\ directory for the actual version.
Install
# Clone and build from source
git clone https://github.com/a1393323447/cppx.git
cd cppx
cargo build --release
# Add to PATH
export PATH="$PWD/target/release:$PATH"
Create a Project
# Create a binary project
cppx new hello-world
# Or a library project
cppx new my-lib --lib
Project Structure
hello-world/
├── cppx.toml # Project configuration
├── src/
│ └── main.cpp # Entry point
└── tests/ # Test files (auto-discovered)
cppx.toml
[package]
name = "hello-world"
version = "0.1.0"
edition = "c++23"
[build]
stdlib = "libc++"
flags = ["-Wall", "-Wextra"]
[profile.release]
opt-level = "2"
lto = false
[dependencies]
math = { path = "../math" }
# utils = { git = "https://github.com/user/utils.git", tag = "v1.0.0" }
Build & Run
cppx build # Debug build
cppx build --release # Release build (with optimizations)
cppx run # Build and run
cppx run -- arg1 arg2 # Pass arguments to the binary
Module Conventions
cppx uses a Cargo-inspired convention where file paths determine module names:
| File Pattern |
Module Name |
Example |
src/foo.cppm |
foo |
src/math.cppm → module math |
src/foo.cpp |
foo (impl unit) |
src/math.cpp → module math; |
src/foo/foo.cppm |
foo (directory module) |
src/greeter/greeter.cppm → module greeter |
src/foo/bar.cppm |
foo:bar (partition) |
src/greeter/impl.cppm → module greeter:impl |
src/a/b/c.cppm |
a.b.c (nested) |
src/net/http/client.cppm → module net.http.client |
src/main.cpp |
(binary entry point) |
No module declaration |
src/lib.cppm |
(library root) |
module <package_name> |
Architecture
graph LR
subgraph "cppx build pipeline"
P0["<b>Phase 0</b><br/>Std Precompile<br/><br/><i>Trait:</i><br/>StdPrecompiler"]
P1["<b>Phase 1</b><br/>Dep Scan<br/><br/><i>Trait:</i><br/>DepScanner"]
P2["<b>Phase 2</b><br/>Schedule<br/><br/><i>Trait:</i><br/>Scheduler"]
P3["<b>Phase 3</b><br/>Compile<br/>(parallel by level)<br/><i>Trait:</i><br/>Compiler"]
P35["<b>Phase 3.5</b><br/>Link<br/><br/><i>Trait:</i><br/>Linker"]
end
P0 --> P1 --> P2 --> P3 --> P35
Loading
Every pipeline stage is defined as a Rust trait, making it straightforward to add new compiler backends. See the design documents for details.
Fuzz Testing
cppx has built-in fuzz testing support powered by libFuzzer:
# Initialize a fuzz target
cppx fuzz init fuzz_math
# Run a fuzz target
cppx fuzz fuzz_math::add
# List all fuzz targets
cppx fuzz list
# Reproduce a crash
cppx fuzz fuzz_math::add --crash <crash_id>
Two function signatures are supported:
// Raw bytes (classic)
void cppx_fuzz_test_add(const std::uint8_t* data, std::size_t size);
// Structured reader (recommended)
void cppx_fuzz_test_add(cppx::Fuzzer& fuzzer);
Documentation
Detailed design documents are available in the docs/ directory:
Roadmap
- Phase 1 — MVP: build, run, clean
- Phase 2 — Incremental builds,
cppx new, cppx test, library support, IDE integration
- Phase 3 — Dependency management (PubGrub resolver, path/git deps, lockfile)
- Phase 4 — Fuzz testing (libFuzzer, dual signatures, crash reproduction)
- Future —
cppx fmt, cppx lint, cross-compilation, workspace support, GCC backend
Contributing
Contributions are welcome! Since the project is in early experimental stage, please open an issue first to discuss what you'd like to change.
License
This project is dual-licensed under either of:
at your option.
Author
朕与将军解战袍 (@a1393323447)