Skip to main content

​
Prerequisites

MCC requires:
  • Rust 1.93.0 or later - MCC uses Rust 2024 edition features
  • A C compiler - For preprocessing, assembling, and linking (typically cc or clang)
  • Git - To clone the repository with submodules
MCC delegates preprocessing, assembly, and linking to your system’s C compiler. Make sure cc or clang is available in your PATH.

​
Install Rust

If you don’t have Rust installed, use rustup: 
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Verify your installation: 
rustc --version
cargo --version
You should see Rust 1.93.0 or later.

​
Clone the Repository

Clone MCC with its submodules (includes the writing-a-c-compiler-tests suite): 
git clone --recursive https://github.com/Michael-F-Bryan/mcc.git
cd mcc
If you already cloned without --recursive, initialize submodules: 
git submodule update --init --recursive

​
Build from Source

MCC uses a Cargo workspace with multiple crates. Build the entire workspace: 
# Fast compilation, slower runtime (good for development)
cargo build --workspace --locked
The --locked flag ensures you use the exact dependency versions from Cargo.lock.
The debug binary will be at target/debug/mcc and the release binary at target/release/mcc.

​
Verify Installation

Check that the compiler builds successfully: 
cargo check --workspace --locked
Run the test suite to verify everything works: 
# Install nextest for faster test execution
cargo install cargo-nextest --locked

# Run all tests
cargo nextest run --workspace --locked

# Run doc tests
cargo test --doc --workspace --locked
Tests require a C compiler (clang or gcc) to be available. Set the CC environment variable if you need to use a specific compiler: CC=clang cargo nextest run

​
Install the Binary (Optional)

To install mcc to your Cargo bin directory (~/.cargo/bin): 
cargo install --path crates/mcc-driver --locked
Now you can run mcc from anywhere: 
mcc --help

​
Project Structure

After building, you’ll have this structure: 
mcc/
├── crates/
│   ├── mcc/              # Core compiler library
│   ├── mcc-syntax/       # Tree-sitter AST integration
│   ├── mcc-driver/       # CLI binary (the `mcc` command)
│   ├── mcc-macros/       # Procedural macros
│   └── xtask/            # Build utilities
├── integration-tests/    # Test framework
│   └── writing-a-c-compiler-tests/  # Test suite (submodule)
├── target/
│   ├── debug/mcc         # Debug binary
│   └── release/mcc       # Release binary
└── Cargo.toml            # Workspace configuration

​
Development Setup

​
Install Additional Tools

For development, install these optional tools: 
# rustfmt is included with rustup
cargo fmt --all -- --check

​
IDE Integration

MCC works well with rust-analyzer:
  • VS Code: Install the rust-analyzer extension
  • Vim/Neovim: Use coc-rust-analyzer or native LSP
  • IntelliJ IDEA: Use the Rust plugin
The workspace configuration in Cargo.toml ensures rust-analyzer understands the multi-crate structure.

​
Running CI Checks Locally

Before committing, run the same checks as CI: 
# Type check
cargo check --workspace --locked

# Build
cargo build --workspace --locked

# Test
cargo nextest run --workspace --locked
cargo test --doc --workspace --locked

# Format
cargo fmt --all -- --check

# Lint
cargo clippy --workspace
The CI runs on both Ubuntu and macOS to ensure cross-platform compatibility. All tests must pass on both platforms.

​
Integration Tests

MCC includes comprehensive integration tests based on the writing-a-c-compiler-tests suite: 
# Run integration tests (default chapter cap)
cargo test -p integration-tests --test integration

# Run all tests including ignored ones
cargo test -p integration-tests --test integration -- --ignored

# Test specific chapters
cargo test -p integration-tests --test integration -- chapter_1
See the Testing Framework documentation for details on:
  • Test organization by chapters (1-20)
  • Stage-specific testing (lex, parse, tacky, codegen)
  • Extra credit features (bitwise, compound, increment, goto, switch)

​
Environment Variables

MCC respects these environment variables:
VariableDescriptionDefault
CCC compiler for preprocessing/linkingcc
RUST_LOGLogging level (mcc=debug, mcc-syntax=debug)warn
Example: 
CC=clang RUST_LOG=mcc=debug cargo run -- input.c

​
Troubleshooting

​
Build Fails with “could not find Cargo.toml”

Make sure you’re in the repository root, not a subdirectory.

​
Tests Fail with “cc: command not found”

Install a C compiler: 
# Ubuntu/Debian
sudo apt-get install build-essential

# macOS (installs clang)
xcode-select --install

​
Submodule Not Found

Initialize submodules: 
git submodule update --init --recursive

​
Rust Version Too Old

Update Rust: 
rustup update stable

​
Next Steps

Quick Start

Compile your first C program with MCC

Build docs developers (and LLMs) love

Get started for freeTalk to us