Reader: a developer deciding whether mcpp fits the work in front of them, and which of its features that work will use.
The question this chapter answers: what kinds of project does mcpp serve, and for one kind, which features are used and in what order.
Not here: the field reference, which is 04; the catalogue of examples, which is 03 and is indexed by example rather than by scenario; and the command lookup, which is 09. This chapter is indexed by the work.
Each scenario states the situation, what mcpp contributes to it, the path through the chapters, one project to run, and the one thing that surprises people. Read only the scenario that matches; they do not build on each other.
| scenario | run | |
|---|---|---|
| 1 | a command-line tool or a service | examples/01-hello → 03-pack-static |
| 2 | a library other projects import | examples/11-features, 05-lib-distribution |
| 3 | a repository with several packages | examples/04-workspace |
| 4 | a graphical application | mcpp new … --template ocornut.imgui |
| 5 | building for another operating system | examples/06-openkal-cross |
| 6 | a target with no operating system | mcpp new … --template riscv-virt-rt |
| 7 | compute on a GPU or an accelerator | examples/09-heterogeneous |
| 8 | graphics rendering | examples/10-graphics/offscreen |
| 9 | a build step the project needs, and sharing it | examples/08-build-rules, 12-a-new-device-language |
| 10 | packaging a tool, a driver or a board for others | the descriptors in xim-pkgindex and mcpp-index |
The situation. A program built from C++23 modules, with a few dependencies, that has to run on a machine that does not have mcpp.
What mcpp contributes. import std works with no configuration; the
compiler is a pinned payload rather than whatever the machine has; and one
command produces a binary that carries what it needs.
The path.
- 00 — What mcpp Is — the five nouns.
- 01 — Getting Started — a program on the screen.
- 05 — Dependencies and Resolution —
[dependencies], the lock file. - 08 — Testing —
tests/**/*.cpp. - 20 — Toolchain Management — when the compiler's version matters, or the project must pin one.
- 10 — Packaging an Application —
mcpp pack.
Run. examples/01-hello, then
02-with-deps, then
03-pack-static.
What surprises people. A debug build and a release build do not invalidate
each other. Each configuration gets its own fingerprinted directory under
target/, so alternating between them is not a rebuild.
The situation. Code that other packages will name in their
[dependencies], possibly with optional parts.
What mcpp contributes. A module interface is the published surface; a feature makes part of it optional without a second package; and a prebuilt binary can state which toolchains it is compatible with.
The path.
- 04 — The mcpp.toml Manifest —
[lib], the library root. - 06 — Features and Capabilities — optional parts, and the dependencies they pull.
- 08 — Testing —
[dev-dependencies]. - 11 — Publishing a Library — the descriptor.
- 12 — Distributing a Prebuilt Library — if binaries ship too.
Run. examples/11-features declares all three
shapes of feature; 05-lib-distribution is
the producer and consumer pair.
What surprises people. The criterion for an optional backend is not that the default build still works — it is that the default build's resolution does not name the optional package. A dependency that is resolved and merely unused still costs a download.
The situation. Several packages developed together, depending on each other by path.
What mcpp contributes. One command builds or tests the set; a member resolves its siblings without a registry; and each member keeps its own manifest and identity.
The path.
- 07 — Workspaces —
[workspace], path dependencies. - 05 — Dependencies and Resolution — what a path dependency does and does not do.
- 08 — Testing — the fan-out.
Run. examples/04-workspace.
What surprises people. A workspace member is not a root. Tooling that enumerates "every package" has to say which of the two it means, and the answer changes what gets built.
The situation. A desktop program with a window, a renderer and fonts.
What mcpp contributes. The window and rendering stack are ordinary dependencies; a template scaffolds a working project; and what the artifact needs at run time is declared rather than discovered.
The path.
- 01 — Getting Started —
mcpp new --template. - 05 — Dependencies and Resolution — the stack.
- 10 — Packaging an Application — what ships beside the executable.
Run. mcpp new myapp --template ocornut.imgui.
What surprises people. On Linux an mcpp artifact runs behind a private
loader that does not consult /usr/lib. Anything the host must supply — a
graphics driver, a Vulkan ICD — is reached through an adapter package the
project declares, not by being installed on the machine.
The situation. One source tree that has to produce binaries for Linux, Windows and macOS.
What mcpp contributes. The target is an argument, not a second checkout; the cross toolchain is a payload; and a target this host cannot serve is refused rather than quietly built for the host.
The path.
- 21 — The Target Triple — how a target is named, and which host serves which.
- 24 — Cross-Compilation Over openkal — the mechanism.
- 22 — The Target Side — when the manifest must differ per target.
Run. examples/06-openkal-cross — one
program built for four targets from any host.
What surprises people. --target does not require the machine to already
have that toolchain. What it does require is that the target be servable from
this host; the support matrix in 21 says which are.
The situation. Firmware for a board or a microcontroller: no OS, no libc by default, a linker script and a vector table.
What mcpp contributes. A board-support package supplies the whole target
world — the linker script, the startup code, and the runner — so mcpp run
is the same command on an emulator and on hardware.
The path.
- 40 — Bare-Metal and Freestanding Targets — the target,
the tiers, what of
stdsurvives. - 41 — Reaching a Device — runners, named runners.
- 08 — Testing — tests that run on the board.
Run. mcpp new blinky --template riscv-virt-rt.
What surprises people. The emulator and the physical board are one package
and one feature apart, not two packages. mcpp run --features hardware moves
the default runner; the command a developer types does not change.
The situation. Part of the program is a kernel compiled by a vendor's compiler and linked into an ordinary binary.
What mcpp contributes. The device toolkit is declared by the rule package and installed by the build; the accelerator is one axis stated once; and the artifact records which devices it carries code for.
The path.
- 42 — Heterogeneous Builds —
accel, the island, the seam. - 30 — Build Programs — how a rule reaches the graph.
- 06 — Features and Capabilities — the feature that selects a lane.
Run. examples/09-heterogeneous/boundary
first — it needs no device — then
…/cuda.
What surprises people. A build that names no accelerator downloads nothing.
Two gates must open before a byte of a multi-gigabyte toolkit is fetched: the
feature that selects the rule, and the cfg(accelerator = …) selector that says
this build actually compiles for the device.
The situation. Shaders compiled to SPIR-V, a pipeline, and pixels that have to be right.
What mcpp contributes. The shader compiler is a declared payload; compiled shaders arrive as a module rather than as a generated header nobody named; and a rendering result can be asserted without a GPU.
The path.
- 42 — Heterogeneous Builds — the shader lane.
- 30 — Build Programs — the one line that asks for the module surface.
- 10 — Packaging an Application — shipping it.
Run. examples/10-graphics/offscreen —
renders a triangle offscreen and compares the pixels against a software
rasteriser.
What surprises people. A software device is not automatically a substitute for hardware. A framework may reject one on its device type even when it advertises every feature the framework requires, and that is the framework's policy rather than a packaging defect.
The situation. Code generation, an embedded asset, a check, or a second compiler — something the engine has no rule for.
What mcpp contributes. The step becomes edges in the same graph as everything else: ordered, fingerprinted, incremental, and reported by name when it fails. It is not a pre-build script.
The path.
- 30 — Build Programs —
mcpp::action, the four roles. - 31 — Authoring a Rule Package — if other projects should use the step too.
- 23 — The Project Environment — declaring the tools the step runs.
Run. examples/08-build-rules for a rule
that checks and embeds;
12-a-new-device-language for one that
teaches mcpp a language the engine has never heard of.
What surprises people. The tool the step invokes is an input of the step. Without that, editing the generator leaves every edge clean and the artifact keeps the bytes the previous generator produced — a green build over a stale result.
The situation. Something other projects should be able to declare and get: a compiler, a shader compiler, an emulator, a host graphics driver, a board.
What mcpp contributes. A consumer declares it by name and gets a working program — the payload is installed, its libraries are on the artifact's search path, and the tier decides whether a build that never runs pays for it at all.
The path.
- 32 — Authoring a Payload — a tool or a prebuilt library mcpp installs.
- 33 — Authoring a Runtime Adapter — when the library belongs to the host and cannot be redistributed.
- 34 — Authoring a Board-Support Package — a board, its memory map, and the way in.
- 31 — Authoring a Rule Package — if a build step drives the tool.
Run. The descriptors themselves: xim-pkgindex/pkgs/g/glslang.lua for a
payload, mcpp-index/pkgs/c/compat.vulkan-runtime.lua for an adapter,
mcpplibs/cortex-m-rt for a board.
What surprises people. Which answer applies is decided by the licence and the ABI, not by preference. A driver whose userspace is in lockstep with a kernel module and whose licence forbids redistribution cannot be a payload; it is a host capability, and the adapter is how an artifact reaches it. An open driver is a payload, and a machine using one needs no adapter at all.
- The scenarios here are the ones with a runnable project or a published template behind them. A scenario mcpp serves but nothing in this repository demonstrates is not listed, because a path with no project to run is a claim rather than a scenario.
- Adopting mcpp inside an existing build system is not a scenario here. mcpp builds a project it owns; interoperating with another build system's outputs is not documented and is not covered by any example.