Documentation

Everything you need to know about cmod

Overview

cmod is a Cargo-inspired, Git-native package and build tool for modern C++20 modules. It handles dependency resolution, build orchestration, workspace management, artifact caching, and supply-chain security — all in a single tool.

Installation

# Clone and build from source
git clone https://github.com/satishbabariya/cmod.git
cd cmod
cargo build --release

# Add to PATH
export PATH="$PWD/target/release:$PATH"

# Verify installation
cmod --help

Requirements: Rust 1.74+, Clang 18+ with clang-scan-deps, Git 2.25+

Configuration: cmod.toml

Every cmod project has a cmod.toml manifest at its root. Here's the full schema:

[package]

[package]
name = "my_project"        # Project name
version = "1.0.0"          # Semver version
edition = "2024"            # C++ module edition
authors = ["Name <email>"] # Authors list
license = "MIT"             # SPDX license identifier
description = "..."         # Short description
repository = "..."          # Git repository URL

[module]

[module]
name = "com.github.user.my_project"  # Reverse-domain module name
root = "src/my_project.cppm"         # Module interface file

Module names follow reverse-domain Git path format: com.github.user.project_name

[dependencies]

[dependencies]
"github.com/fmtlib/fmt" = ">=10.0"         # Minimum version
"github.com/nlohmann/json" = "^3.11"       # Compatible version
"gitlab.com/org/lib" = "~2.0"              # Patch-compatible
"github.com/user/fork" = { branch = "dev" } # Branch pin
"../local-lib" = { path = "../local-lib" }  # Local path dep

[toolchain]

[toolchain]
compiler = "clang"      # Compiler (clang, gcc, msvc)
version = ">=18.0"      # Compiler version constraint
std = "c++23"           # C++ standard
stdlib = "libc++"       # Standard library
target = "x86_64-linux" # Target triple

[build]

[build]
type = "binary"         # binary | library | header-only
optimization = "2"      # 0, 1, 2, 3, s, z
lto = false             # Link-time optimization
parallel = true         # Parallel compilation

[workspace]

[workspace]
members = [
  "core",
  "app",
  "tests"
]

CLI Reference

Core Workflow

cmod init [name] [--workspace]     # Initialize project
cmod build [--release] [--jobs N]  # Build
cmod test [--release]              # Build and run tests
cmod run [--release] [-- args...]  # Build and run binary
cmod clean                         # Remove build artifacts

Dependency Management

cmod add <dep>[@version]            # Add dependency
cmod remove <name>                 # Remove dependency
cmod resolve                       # Resolve deps, generate lockfile
cmod update [name] [--patch]       # Update dependencies
cmod deps [--tree] [--why <name>]  # Inspect dependency graph
cmod tidy [--apply]                # Remove unused deps
cmod vendor [--sync]               # Vendor for offline builds
cmod search <query>                # Search for modules

Build Tools

cmod graph [--format dot|json]     # Visualize module DAG
cmod explain <module>              # Why would this rebuild?
cmod compile-commands              # Generate compile_commands.json
cmod lint                          # Run clang-tidy
cmod fmt [--check]                 # Run clang-format
cmod check                         # Validate module structure

Cache & Security

cmod cache status|clean|gc         # Manage cache
cmod cache push|pull               # Sync with remote cache
cmod verify [--signatures]         # Verify integrity
cmod audit                         # Audit for vulnerabilities
cmod sbom [--output <file>]        # Generate SBOM
cmod publish [--dry-run]           # Publish (create Git tag)

Workspace & Project

cmod workspace list|add|remove     # Manage workspace
cmod status                        # Project overview
cmod toolchain show|check          # Manage toolchain
cmod plugin list|run               # Manage plugins

Global Flags

--locked              # Strict lockfile mode (fail if outdated)
--offline             # No network access
--verbose / -v        # Verbose output
--target <triple>     # Target triple override
--features <list>     # Enable features
--no-default-features # Disable default features
--no-cache            # Skip build cache
--untrusted           # Skip trust verification

Exit Codes

0  Success
1  Build failure
2  Resolution error
3  Security violation

Lockfile: cmod.lock

The lockfile is generated by cmod resolve and records:

  • Exact Git commit hash for every dependency
  • Resolved version for every constraint
  • Toolchain version used for resolution

Always commit cmod.lock to version control. Use --locked in CI to enforce it.

C++20 Modules

cmod treats C++20 modules as the fundamental unit of compilation:

  • Module interface units (.cppm) define the public API
  • Module implementation units (.cpp) contain the implementation
  • Module partitions split large modules into logical pieces
  • BMIs (Binary Module Interfaces) are compiled once and cached

cmod uses clang-scan-deps to automatically discover the module dependency graph. The full graph is resolved before any compilation begins, enabling optimal parallelism.

Security Model

  • Mandatory lockfiles — Exact commit hashes prevent silent updates
  • TOFU trust — First-use identity is recorded; changes trigger alerts
  • Hash verification — Source integrity verified against lockfile
  • Signature verification — Cryptographic proof (planned full support)
  • SBOM generation — Full dependency inventory for compliance
  • Audit — Check dependencies for known vulnerabilities

Architecture

cmod is implemented in Rust as a Cargo workspace with 8 crates:

Crate Responsibility
cmod-coreCore types, config parsing, manifest/lockfile, error model
cmod-cliCLI frontend, clap-based argument parsing, subcommand dispatch
cmod-resolverGit fetch, semver solving, lockfile generation, module registry, feature resolution
cmod-buildModule DAG, build plan IR, Clang invocation, parallel execution, distributed builds, incremental rebuilds
cmod-cacheContent-addressed caching with SHA-256 keys, remote cache protocol, BMI distribution
cmod-workspaceMonorepo management, unified dependency resolution
cmod-securityHash/signature verification, TOFU trust, policy enforcement, cryptographic signing (PGP/SSH/Sigstore)
cmod-lspLanguage Server Protocol server with completion and diagnostics

Dependencies flow downward: cli → {resolver, build, cache, workspace, security, lsp} → core.

Examples

Working example projects are available in the examples/ directory:

  • hello/ — Minimal binary, no dependencies
  • library/ — Static library with module partitions
  • shared-lib/ — Shared (dynamic) library build
  • with-deps/ — Git dependencies (fmt + json)
  • workspace/ — Multi-member monorepo
  • path-deps/ — Local path dependencies
  • nested-deps/ — Path dep with transitive git dependencies
  • header-only/ — Header-only library as a path dependency
  • include-dirs/ — Using include/ directory convention with modules
  • ixx-modules/ — .ixx module extension (MSVC-style)
  • multi-binary/ — Multiple binaries sharing a module library
  • with-tests/ — Testing with cmod test
  • plugin/ — Plugin system with JSON IPC

Editor Extensions

cmod ships with first-class IDE integrations for the two most popular C++ editors:

VS Code Extension

  • LSP integration via cmod lsp for diagnostics, completions, and hover
  • Build, test, run, clean commands with Clang problem matcher
  • Interactive module graph visualization (force-directed D3.js)
  • Dependency tree view parsed from cmod.toml
  • Format-on-save and lint-on-save
  • C++20 module snippets (module, import, partition, export)
  • File associations for .cppm, .ixx, .mxx

Install: search "cmod" in the VS Code Marketplace, or see editors/vscode/

CLion / IntelliJ Plugin

  • LSP integration with completions, diagnostics, and go-to-definition
  • Run configurations for build, test, and run with profile/sanitizer options
  • Tool window with module graph, dependency tree, and cache status panels
  • Build/test/run/clean/format/lint actions in the Build menu
  • Format-on-save and lint-on-save
  • File type support for .cppm, .ixx, .mxx, and cmod.toml

Install: search "cmod" in JetBrains Marketplace, or see editors/clion/

Design Specifications

cmod's design is specified in 21 RFCs organized by priority tier:

  • Core (Tier 0): RFC-0001 through RFC-0004, RFC-UNIFIED — manifest schema, resolver, build system, lockfile
  • Tier 1: RFC-0005 through RFC-0008 — caching, workspaces, security, toolchain
  • Tier 2: RFC-0009, RFC-0010 — developer experience, IDE integration
  • Tier 3: RFC-0011 through RFC-0014 — distributed features, advanced builds
  • Tier 4: RFC-0015 through RFC-0019 — ecosystem, plugins, visualization

Full specifications: docs/rfc/

Further Reading