01-examples.md

01 — Examples

The repository's examples/ directory provides a set of progressively more advanced minimal projects, covering common scenarios from a single-file import std to a fully static release package. Each example can be entered on its own and built with mcpp build.

How to Run

git clone https://github.com/mcpp-community/mcpp
cd mcpp/examples/01-hello
mcpp build && mcpp run

Each example ships with its own README that only explains the new concepts it introduces relative to the previous one. Common material such as installation steps and toolchain initialization lives in 00 — Getting Started and is not repeated within the examples.

Example List

#	Path	Description	Key Concepts
01	examples/01-hello	Minimal single-file project with import std	The minimal package shape (mcpp new also emits tests/test_smoke.cpp)
02	examples/02-with-deps	Adds the mcpplibs.cmdline dependency to parse command-line arguments	[dependencies], SemVer, mcpp.lock
03	examples/03-pack-static	Produces a fully static release package via mcpp pack --mode static	[target.<triple>] and [pack] configuration
04	examples/04-workspace	A multi-package workspace: two libraries and an application sharing one namespace	[workspace], path dependencies, mcpp build --workspace
05	examples/05-lib-distribution	A prebuilt library and its consumer, interesting only together	mcpp pack for a library, a C header and a C++ module from one source, a distribution package
06	examples/06-openkal-cross	One program asking each machine what it is, built for four targets from any host	--target, openkal, cross-compilation without editing the source
07	examples/07-project-subos	A build program that finds its tools in the environment the project declared	[xlings] subos, [xlings.workspace], a build program whose PATH is the environment the project named
08	examples/08-build-rules	Two rule packages and a project that uses both	host-module = true, [build-dependencies], mcpp::action with role = "check"
09	examples/09-heterogeneous	One computation on a device, in several programming models, with a CPU fallback in each; plus one artifact carrying several backends at once	accel, constrained source globs, the seam module, rule packages from mcpp:plugins, cfg(accelerator = …)
09a	…/cuda	A CUDA kernel behind a seam module	mcpp.rules.cuda, mcpp::action with role = "object", the driver stated as a fact and a floor
09b	…/vulkan	The same computation as a Vulkan compute shader, on a GPU or on the CPU	mcpp.rules.spirv, mcpp::action with role = "source", generated headers, a software driver as a payload
09c	…/sycl	The same computation as a SYCL kernel, compiled by a second compiler	mcpp.rules.sycl, the .sycl device extension, a chained mcpp::action for the device link, compat:sycl-runtime
09d	…/hip	The same computation in HIP, reaching an NVIDIA device	mcpp.rules.hip, HIP as a header layer over the CUDA runtime, a two-chunk accel
09e	…/multi-backend	Several backends in ONE artifact, chosen at run time — the library shape, not the program shape	accel as a set, cfg(accelerator = "none") and its negation, a dispatch chain, a module seam over a C island boundary
09f	…/cann	An Ascend C kernel behind the same seam. Does not build yet — its README names the two missing pieces	the .asc device extension, op_kernel/op_host as an island CANN already has, accelerator = "none" for the fallback
10	examples/10-graphics	Graphics rather than compute: a rendering pipeline whose result is pixels	mcpp.rules.spirv for the vertex and fragment stages, offscreen rendering as the assertable form
10a	…/offscreen	A triangle rasterised by Vulkan into a buffer, and the same triangle by a software rasteriser behind the same seam	two shader stages from one glob, a render pass with no window or swapchain, a pixel as the criterion

Suggested Reading Order

We recommend reading them in numerical order:

1. 01-hello shows the minimal package skeleton (mcpp.toml and src/main.cpp) and demonstrates the basic usage of import std. The current mcpp new scaffold also emits tests/test_smoke.cpp.
2. 02-with-deps builds on the previous example by introducing an external dependency, covering the lock-file mechanism and how the modular package index works.
3. 03-pack-static demonstrates how to package build artifacts into a standalone, independently distributable single-file binary; for packaging details, see 02 — Packaging and Release.

Adding a New Example

Example projects follow a consistent directory structure: mcpp.toml + src/ + README.md. To add a new example, create a numbered directory under examples/ (e.g. 04-xxx/), briefly describe the concept it demonstrates in its README, and then open a PR. For contribution guidelines, see 04 — Build from Source & Contributing.