Tutorial

Getting Started with cmod

From zero to building in under a minute

Prerequisites

  • Rust 1.74+ — Install from rustup.rs
  • Clang 18+ with clang-scan-deps — for C++ module compilation
  • Git 2.25+

Install cmod

git clone https://github.com/satishbabariya/cmod.git
cd cmod
cargo build --release

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

Create Your First Project

# Initialize a new project
cmod init hello
cd hello

This creates a clean project structure with a cmod.toml manifest and a src/ directory.

hello/
├── cmod.toml
└── src/
    └── main.cpp

Build and run:

cmod build
cmod run

Add Dependencies

Dependencies are Git URLs. No registry needed.

# Add fmt library
cmod add github.com/fmtlib/fmt@10.0

# Add JSON library
cmod add github.com/nlohmann/json@3.11

# Resolve and build
cmod resolve
cmod build

cmod clones the repositories, resolves the best matching version from Git tags, pins the exact commit hash in cmod.lock, and compiles everything.

The Lockfile

After resolving, check in your cmod.lock to version control. This guarantees reproducible builds across your team and CI.

# In CI, always use --locked
cmod build --locked

Explore Your Dependencies

# Dependency tree
cmod deps --tree

# Visual graph (DOT format)
cmod graph --format dot > deps.dot

# Why is a module included?
cmod deps --why fmt

Test, Lint, Format

cmod test              # Run tests
cmod test --release    # Release-mode tests
cmod lint              # Run clang-tidy
cmod fmt               # Format with clang-format
cmod fmt --check       # Check without modifying

IDE Integration

cmod has first-class editor extensions with LSP support, module graph visualization, and build integration:

VS Code

Install the cmod extension from the VS Code Marketplace (or search "cmod" in Extensions). You get:

  • LSP-powered diagnostics, completions, and hover info
  • Build/test/run commands with Ctrl+Shift+B / Cmd+Shift+B
  • Interactive module graph visualization
  • Dependency tree view and build status
  • C++20 module snippets and format-on-save

CLion / IntelliJ

Install the cmod plugin from JetBrains Marketplace (Settings > Plugins > Marketplace). You get:

  • LSP-powered code intelligence
  • Run configurations for build, test, and run
  • Tool window with graph, dependencies, and cache panels
  • Build menu actions and format/lint-on-save

Other Editors

# Generate compile_commands.json for any LSP-compatible editor
cmod compile-commands

This enables code intelligence in Neovim, Emacs, Sublime Text, and other editors with clangd support.

Work Offline

# Build without network access
cmod build --offline

Set Up a Workspace

For monorepo-style projects with multiple modules:

cmod init my_workspace --workspace
cd my_workspace

cmod workspace add core
cmod workspace add app
cmod workspace add tests

# Build everything
cmod build

Verify & Audit

# Verify dependency integrity
cmod verify

# Audit for security issues
cmod audit

# Generate SBOM
cmod sbom --output sbom.json

Common Workflows

Daily development

cmod build            # Incremental build
cmod test             # Run tests
cmod run -- arg1      # Run with arguments

CI pipeline

cmod build --locked --release
cmod test --release
cmod verify
cmod sbom --output sbom.json

Update dependencies

cmod update              # Update all
cmod update fmt          # Update specific dep
cmod update --patch      # Patch-level only
cmod tidy --apply        # Remove unused deps

Next Steps