A C++ product, end to end

The commands, in order

This chapter is the delivery loop on a C++ product whose manifest declares no task body at all. Here is what a person types, in order:

./cppdemo.sh support toolchain cpp 19    write the four toolchain commands into the manifest, once
./cppdemo.sh build configure             generate the build system, cmake inside the pinned image
./cppdemo.sh build compile               compile in the same image
./cppdemo.sh build unit                  the ctest suite
./cppdemo.sh build analyse               clang-tidy over the compile database configure wrote
./cppdemo.sh release tag v0.1.0          tag it
./cppdemo.sh dev deploy up               env-first: run the compiled binary on this host

The first line is the support command, and here it really is the first step rather than a hint beside one: until it has run, the product has no build commands at all. ./cppdemo.sh support install is the host preflight beside it.

Two things a C++ reader will look for and not find in that list. The CMakeLists.txt files are written by build:cmake-files, which cppdemo predates and does not declare - the section below has the walk that produced it. And there is no documentation command, because cppdemo declares no site: section; the Java chapter drove the documentation render instead.

Everything under this heading is the table below read as a sequence; the table is what says which rows were really run, on which date, and which of them did not work.

The product, and what it proves

The Python chapter walks one delivery loop with the kernel’s own language underneath it. The Java chapter walks the same loop with no Python in the product at all - and its product still writes a build body of its own, a Python function ending in a docker run, because when it was written there was nothing else to write.

This one is the same loop again with no task body at all. cppdemo’s manifest has no tasks: block: every command in it is an instance of a catalogue coordinate, and the four that build the product are the same coordinate, toolchain:run, differing only in the argv they hand a pinned silkeh/clang:19.

That is the before/after this chapter exists for, and it is worth stating plainly rather than implying it:

The second half of the chapter is why that is not yet the whole story. Driving cppdemo was the first time the si#95 path was walked end to end by a product, and it does not survive the walk: the ready-made configuration cannot be asked for, the shape it writes does not assemble, and the command it produces cannot report a verdict. Every one of those has a ticket and a row in the table below. Nothing on this page is a plan.

The product was scaffolded for this chapter and driven on one machine on 2026-09-09, against the kernel in this checkout rather than a released wheel. That is not a detail: simplon init pinned simplon==0.7.1 in the product’s own requirements, which is the newest release it knew of and predates toolchain:run entirely, so the first thing a C++ product has to change is the pin. It is about as small as a C++ product gets:

cppdemo.yaml                           the manifest - and there is no `tasks:` block in it
CMakeLists.txt                         the CMake project, three targets
src/calculator.h  src/calculator.cpp   three functions
src/main.cpp                           what `deploy up` runs
tests/calculator_test.cpp              three ctest cases
orchestrator/src/python/orchestrator/  five .py files - five scaffolded, zero written here

Zero lines of product code outside C++ and YAML. The five Python files are the scaffold’s adapter - the manifest path, the environment provider, the composition root - and this product added nothing to them and named none of their placeholder bodies.

The labels, and why they are on the page

Same rule as the other two cases, for the same reason: a page describing a pipeline nobody has driven is worse than no page, because the reader concludes they misread the site rather than that the site is inventing.

Of the 17 steps above, 11 are run, 3 are derived and 3 does not exist yet.

Three open rows is two more than the Java chapter carries, and that is the honest shape of a capability one week old: the toolchain itself does everything it promises, and the path from “I have a C++ product” to “I have those commands” is not joined up yet. Row 11 was the fourth until simplon#136, and how it stopped being one is worth the sentence: the key it needs had existed since simplon#106 and could not name the kind of command this product has, because every test behind that key used a Python stub. It is derived rather than run for the ordinary reason the other two are - this product declares no suites: section, so nobody ran it here.

What the kernel carries for C++

simplon.tasks.profiles is a table, and that is a design decision rather than an implementation detail: the kernel learns no CMake and no MSBuild, it learns to run a pinned image over a product tree as the calling user. What it carries per language is argv and paths, nothing callable. There are four profiles - cpp, java, dotnet and python - and the C++ one carried four commands when this chapter was measured:

Those are the four cppdemo runs, unedited. The manifest entry for one of them is the whole of what the product writes about compiling C++:

      compile:
        task: "toolchain:run"
        help: "Compile the product in the containerised toolchain."
        with:
          body:
            image: "silkeh/clang:19"
            workdir: /src
            argv: ["cmake", "--build", "build", "-j"]
          where: "build compile"
          extra: []

Compiler and version are manifest data, so moving to clang 20 is a one-line diff in a file a reviewer reads, not an edit to a script. And the same coordinate is filed under a different group further down, which is what makes toolchain:run a family rather than a placement - the binary this product ships is run by the same task that compiled it:

      up:
        task: "toolchain:run"
        help: "Run the compiled binary on this host (si#5: there is no further target)."
        with:
          body:
            image: "silkeh/clang:19"
            workdir: /src
            argv: ["./build/cppdemo"]
          where: "deploy up"
          extra: []

The three things between that table and a running command

The design says a product declares { language: cpp, version: "19" }, runs one command and receives the four. Driven, that path stops three times, and the shape above is what is left after going around all three. They are one ticket, simplon#105, because they are one story.

The version cannot be asked for. Every profile’s image is a template, and the catalogue declares exactly one parameter for the scaffolder - the language. simplon.signatures.bindable drops **kwargs, so there is no second value to pass and no manifest key that carries one:

$ ./cppdemo.sh support toolchain cpp
KeyError: 'version'

Pinning it in the manifest is refused rather than ignored, which is at least loud: support toolchain: with:/params: name parameter(s) the impl does not take: version.

The block the scaffolder writes does not assemble. Called with the version it cannot receive, the scaffolder does its job and writes four commands in the design’s own shape:

      compile:
        task: toolchain:run
        with:
          image: silkeh/clang:19
          workdir: /src
          argv:
          - cmake
          - --build
          - build
          - -j

That manifest LOADS. It does not ASSEMBLE, because toolchain:run’s body takes body, where, extra and network, and image/workdir/argv are the keys inside the first of those:

build configure: `with:`/`params:` name parameter(s) the impl does not take: argv, image, workdir

So the failure arrives at the first command anybody types afterwards, not at the scaffold - and the nesting in the manifest block above is what a product has to write by hand until that is decided.

And the toolchain asks for a lab instance it does not use. run_toolchain resolves the instance id before it looks at whether the command declares a cache volume at all, so a product with no caches still needs the section, and simplon init writes none:

instance:
  env_var: CPPDEMO_INSTANCE
  default: dev
  max_id_len: 2

build

One command, one container, and the kernel does not know what CMake is.

$ ./cppdemo.sh build configure
-- The CXX compiler identification is Clang 19.1.7
-- Configuring done
-- Generating done
-- Build files have been written to: /src/build

$ ./cppdemo.sh build compile
[ 16%] Building CXX object CMakeFiles/calculator.dir/src/calculator.cpp.o
[ 33%] Linking CXX static library libcalculator.a
[100%] Linking CXX executable cppdemo
[100%] Built target cppdemo

What stands behind both is one assembled argv, and it is worth reading once because every product on this kernel gets the same one:

docker run --rm --user 0:0 -v /tmp/cppdemo:/src -w /src silkeh/clang:19 cmake --build build -j

--user is there from the first line, and that is not tidiness. netctl’s hand-written gradle invocation does not carry it, and on 2026-09-08 that left a repo-root build/ owned by root, after which every CI run on a freshly cleared runner died at the next step that had to create a directory (netctl#1778). A product that declares its build here inherits the right answer instead of copying the wrong one - which is also why the Java chapter’s GRADLE_USER_HOME callout has no counterpart on this page.

The image goes through the kernel’s one image gate, with the toolchain’s own hint on the end of it. Written as silkeh/clang:latest and run, that manifest line answers:

[06:45:25] ERR build configure: 'image' must pin a version, not the moving tag 'latest' (got 'silkeh/clang:latest') - a build whose output depends on when it ran is not a build; a toolchain must name its version

docker.pinned_image is the gate the kernel puts its own images through - the Hugo image a site: section declares, the docToolchain tag docs:render reads. The difference from the Java chapter is where the product stands relative to it: javademo chose to call the gate from its own task body, and cppdemo cannot avoid it, because the image reference is a manifest key the kernel reads. The rule reaches the declaration, so nobody has to remember to keep it.

The argument the caller cannot add

The design’s other half is that the manifest pins the argv and the caller appends: build compile is a CI step by name, and a person at a terminal keeps the tool’s whole vocabulary behind it. toolchain.argv implements it, and no command line reaches it. extra is a required parameter of the body, so it has to be pinned in the manifest, and a pinned parameter leaves the command line entirely; toolchain:run also carries no passthrough_args, which is the mechanism that would have let the tail through:

$ ./cppdemo.sh build analyse src/calculator.cpp
Got unexpected extra argument (src/calculator.cpp)

That is row 10, and it is what made row 9 a refusal rather than a pass: clang-tidy -p build names no source file, so the profile’s analyse entry could not analyse anything, and the mechanism that was supposed to complete it was the one that was missing.

The file the product still wrote by hand

Read the tree listing at the top of this chapter again. Every line of cppdemo’s build is manifest data except one: CMakeLists.txt, three targets, written by a person. Nothing on this page labelled that a gap, because when the walk was taken there was nothing else to write - which is exactly the shape the chapter is about, one file lower down.

$ file build/src/plugin/libplugin.so build/src/calculator/libcalculator.a build/src/e2edemo/e2edemo
build/src/plugin/libplugin.so:        ELF 64-bit LSB shared object, x86-64 ... with debug_info, not stripped
build/src/calculator/libcalculator.a: current ar archive
build/src/e2edemo/e2edemo:            ELF 64-bit LSB pie executable, x86-64 ... with debug_info, not stripped

$ nm build/src/calculator/libcalculator.a
calculator.cpp.o:
0000000000000000 T _ZN4demo3addEii

mul.cpp.o:
0000000000000000 T _ZN4demo3mulEii

test

The suite runs, and it runs in the image the compile ran in - which is the one rule the design states about static analysis and testing, and the reason it states it: a checker that cannot see the dependencies it is checking against degrades into a blanket exception, and a test binary is no different from a checker in that respect.

$ ./cppdemo.sh build unit
    Start 1: adds
1/3 Test #1: adds .............................   Passed    0.00 sec
    Start 2: multiplies
2/3 Test #2: multiplies .......................   Passed    0.00 sec
    Start 3: divides
3/3 Test #3: divides ..........................   Passed    0.00 sec

100% tests passed, 0 tests failed out of 3

Break one assertion in demo::mul and it arrives red, with ctest’s own accounting of what failed:

2/3 Test #2: multiplies .......................***Failed    0.00 sec
multiplies: expected 20, got 9

67% tests passed, 1 tests failed out of 3

The following tests FAILED:
	  2 - multiplies (Failed)

The green that is not about the product

Three runs, one after another, on the same tree:

Read the third row. build compile failed on a cannot initialize a variable of type 'int' with an lvalue of type 'const char[11]', and build unit then ran the binaries the previous build left in build/ and reported every test passing. Nothing lied: ctest ran what was there, and what was there was last week’s answer.

The Java chapter has the same hazard and an answer for it. Its gate is an impl: - a callable the kernel runs for a verdict - so the kernel exports a marker path in SIMPLON_SETUP_FAILED before it, the runner writes the stage that broke into it, and the report comes out setup-failed and empty rather than plausible. A toolchain:run command has no callable to point at - and it does not need one, because it is a command, and a gate may name a command in the product’s own tree (simplon#106). A gate whose command: is the ctest command above and whose preamble: is the compile stops on the third row at the compile: the verdict is setup-failed, ctest is never asked about last week’s binaries, and the archive says the build fell over rather than that three tests passed. Nothing is copied out of the build commands - the image, the argv and the caches stay declared once, where they already are.

That pairing has since been driven rather than described - a real ctest in silkeh/clang:19, behind a real command: gate, green, red, and stopped at a failed compile (simplon#136, which is also what found that the key could not name a toolchain:run command at all until then). What it has not been driven on is this product: cppdemo declares no suites: section, which is why row 11 says derived.

The three runs above were measured before that key existed, and they are still exactly what the two commands do when they are run bare. That is the point of the third row rather than an artefact of it: the pairing is what a gate adds, and two commands nobody paired report the last good result.

cppdemo declares no suites: section, so what is above is what it does today; the block that closes the gap is three keys in one section and no Python, which leaves the claim this chapter opens with standing in the test phase as well as in the build.

What a gate is, what a level is and how a command backs one are all in Test levels; the five outcomes a gate can report, and which two of them are statements about the product, are in the Python chapter’s test section.

release

The tag is the version and the guard is the kernel’s, and neither of those has anything to do with the language. release:tag is placed in cppdemo’s manifest with one line and no body of its own, and it behaves exactly as it does for a Python or a Java product - which the chapter can show, because it refused: with no origin/main in the checkout the question “main carries this commit” has no answer, so ./cppdemo.sh release tag v0.1.0 exited 1 and git tag afterwards listed nothing. What the guard checks, and what it deliberately does not, is in Cutting a release.

What gets published is the part that differs, and cppdemo declares none of it: release:artifact reads an artifacts: section and release:image an images: one. Row 14 says derived for that reason and not because anything is missing - a stripped ELF binary and a jar are the same kind of thing to the kernel, which is the point.

deploy

Same answer as the other two chapters, and it is the state of the kernel rather than an omission here.

What exists is the local host, and for this product it is one more instance of the same coordinate: the binary runs in the image that compiled it, on the machine you typed the command on.

$ ./cppdemo.sh dev deploy up
cppdemo: 2 + 3 = 5

There is a real difference from the Java chapter hiding in that line, and it is not in cppdemo’s favour. javademo runs its jar in a JRE image rather than the JDK that built it - what ships is the artefact, and the thing that runs it is not the thing that made it. cppdemo runs its binary in the full clang image, because the product declared the same image twice and nothing suggested otherwise. A C++ product that cared would name a runtime image in the deploy up body, and the manifest is where that decision would be visible.

What does not exist is everything past that host. deploy is the rib the catalogue draws all but empty: the group name, the env-first gate, and two tasks that say which version goes out. simplon#5 is where that decision is open, and the empty rib is why leaving the rest of it empty is the expensive choice rather than the lazy one.

docs

Both documentation commands are language-agnostic, and this chapter drove neither. docs:render runs docToolchain in Docker and produces HTML and PDF from AsciiDoc; the Java chapter drove it and its transcript is there, including the ownership trap that makes the order of build and docs matter on a fresh tree. docs:site reads a site: section cppdemo does not declare. Row 17 says derived for both, and repeating a run that has nothing C++ about it would have been a third copy of the same evidence.

What this chapter does not repeat

Each of these is told once, elsewhere, and told properly:

• the same loop with the kernel’s own language underneath it - A Python product, end to end
• the same loop with a hand-written build body - A Java product, end to end
• what a gate is, how a level is declared, and how a foreign runner attaches - Test levels
• why the tag is the version and what the release guard refuses - Cutting a release
• why deploy and monitor are empty - The five phases
• getting a product to exist in the first place - Getting started