This document provides a comprehensive technical overview of cmkr, a build system generator that transforms TOML configuration files into CMake build scripts. This page explains cmkr's architecture, core components, operational modes, and design philosophy at a system level.
For step-by-step usage instructions, see Getting Started. For detailed cmake.toml syntax, see cmake.toml Configuration Reference. For internal implementation details of individual subsystems, see Core Architecture.
Sources: README.md1-78 docs/index.md1-82 docs/philosophy.md1-83
cmkr (pronounced "cmaker") is a build system generator built on CMake and TOML. It accepts human-readable cmake.toml configuration files and produces idiomatic CMakeLists.txt files that integrate seamlessly with the CMake ecosystem.
This 6-line configuration generates a complete, modern CMakeLists.txt file with proper target definitions, property propagation, and CMake best practices.
| Characteristic | Implementation |
|---|---|
| Zero Installation | Self-bootstraps using only CMake + C++ compiler |
| Transparent Operation | Automatic regeneration when cmake.toml changes |
| CI-Friendly | Bootstrap skipped in CI; pre-generated files committed |
| CMake Compatible | Generates standard CMake; can "eject" at any time |
| Version Pinning | Bootstrap script contains exact cmkr version hash |
Sources: README.md5-18 docs/index.md9-22 docs/philosophy.md20-44
Analysis: The system consists of three primary layers: (1) User Input (TOML configuration and CLI), (2) Core Processing (parser and generator with highest importance score of 199.42), and (3) Bootstrap System (111.24 importance). The parser::Project class serves as the central data structure connecting input validation to output generation.
Sources: README.md5-41 High-level architecture diagrams
The input pipeline transforms user-written TOML into the parser::Project object, which serves as the canonical internal representation of the build configuration. The TomlChecker validates references and detects typos before the data model is constructed.
Sources: Architecture Diagram 2, Architecture Diagram 4
The gen::generate_cmake function orchestrates specialized generators that write CMake commands to an in-memory buffer. The Command Builder provides a fluent API for generating syntactically correct CMake code.
Sources: Architecture Diagram 4
cmkr operates in two distinct modes that provide both explicit control and automatic convenience:
| Command | Handler | Description |
|---|---|---|
cmkr init | args::handle_args | Create new project with template files |
cmkr gen | args::handle_args → gen::generate_cmake | Regenerate CMakeLists.txt from cmake.toml |
cmkr build | args::handle_args → build::run | Generate + configure + build |
cmkr install | args::handle_args → build::install | Run CMake installation |
cmkr clean | args::handle_args → build::clean | Remove build directory |
Sources: README.md54-67 docs/index.md57-71 Architecture Diagram 3
The cmkr.cmake bootstrap script is included at the top of generated CMakeLists.txt files. It monitors cmake.toml for changes and triggers automatic regeneration during CMake configuration, eliminating manual cmkr gen invocations during development.
Sources: Architecture Diagram 3, Architecture Diagram 5
The bootstrap script (cmkr.cmake, approximately 250 lines) handles the entire installation process:
Distribution Strategy:
| File | Committed to Source Control | Purpose |
|---|---|---|
cmake.toml | ✓ Yes | Source of truth for build configuration |
CMakeLists.txt | ✓ Yes | Pre-generated for CI and git diffs |
cmkr.cmake | ✓ Yes | Bootstrap script for developers |
build/cmkr | ✗ No | Cached binary (build artifact) |
Sources: README.md20-41 docs/philosophy.md61-82 Architecture Diagram 5
External Dependencies (documented in README.md70-78):
Sources: README.md69-78 include/literals.hpp1-101
The cmkr init command generates boilerplate code from templates defined in include/literals.hpp1-101 Available project types:
| Type | Template | Generated Files |
|---|---|---|
executable | toml_executable | cmake.toml, src/{name}/main.cpp |
library / static | toml_library + cpp_library + hpp_library | cmake.toml, src/{name}/{name}.cpp, include/{name}/{name}.hpp |
shared | toml_library (type=shared) | Same as static library |
interface | toml_interface + hpp_interface | cmake.toml, include/{name}/{name}.hpp |
Example template structure from toml_executable:
The @name placeholder is replaced with the user-provided project name during initialization.
Sources: include/literals.hpp51-100 README.md54-67
CMake's Turing-complete scripting language creates unnecessary complexity for simple projects. While powerful for complex builds, the barrier to entry discourages adoption and good practices.
| Challenge | cmkr's Approach |
|---|---|
| Learning curve | Declarative TOML syntax instead of imperative scripting |
| Ecosystem compatibility | Generates standard CMake; no lock-in |
| Installation friction | Zero dependencies beyond CMake + compiler |
| Workflow disruption | Transparent automatic regeneration |
| CI overhead | Pre-generated files committed; bootstrap skipped |
| Version control | All artifacts committed for reproducibility |
cmkr generates CMake (which generates native build files), creating multiple abstraction layers. This is mitigated by:
cmkr.cmake is ~250 lines of readable CMake codeCMakeLists.txt is human-readable; can stop using cmkr at any timeSources: docs/philosophy.md10-83
cmkr is a build system generator architected around three core principles:
The system centers on the parser::Project data model, which connects TOML input to CMake output through a validated, strongly-typed representation. The bootstrap system (cmkr.cmake) enables distribution without pre-built binaries, while the dual-mode operation (CLI + automatic) provides flexibility for different workflows.
For implementation details of individual subsystems, see Core Architecture. For usage instructions, see Getting Started.
Sources: All provided files and architecture diagrams
Refresh this wiki