Before week one · C++23 toolchain primer

Build your studio.

You remember C++. Let’s make the build tools understandable again. Start from an empty folder, build your own tiny project, then bring the renderer to life. Take it one short session at a time.

SKETCHBOOK / 00 The tool bench · 6–8 short sessions · repeat as needed

Page 1 of 15: Three tools, three jobs

Start with the map

Three tools, three jobs

You know C++, but the build machinery may feel like a pile of forgotten incantations. Give each tool one job. CMake reads your project description, checks the toolchain during configuration, and generates a build graph. Ninja executes that graph efficiently. Clang compiles each C++ translation unit; the compiler driver also invokes a linker to combine the resulting object files and libraries.

A configure step may compile small probes, but it does not build your whole renderer. A successful build does not run your tests. CTest runs the tests you registered. Keeping these boundaries visible makes a failure easier to locate: configuration, compilation, linking, or runtime.

The native/ folder is a separate C++ project inside this SvelteKit course. Bun runs the learning website; it is not your C++ compiler. The first authored checkpoints start in your own empty my-checker folder; later renderer commands start from the explicitly named project directory. CMake 3.25 or later supports the shipped preset format. Use a Clang toolchain and standard library that implement the C++23 features used here, especially std::expected. Language mode and library support are separate requirements.

TRY IT IN YOUR STUDIO

Write the four words configure, compile, link, test. Put CMake, Ninja, Clang, the linker, and CTest next to the work each does. It is fine for one tool to orchestrate another.

LOOK CLOSER

CMakeLists.txt + compiler + preset
             │ configure / generate
             ▼
         build.ninja
             │ build
             ▼
    Clang → object files → linker → executable
                                     │ CTest
                                     ▼
                                test results

A build pipeline, not a command to execute. CMake also performs toolchain checks while configuring.

PREDICT BEFORE YOU RUNCMake configured successfully. What has that established?

From the page to your own work

Your studio assignment.

Build a small project from an empty folder, then use the same mental model to build the renderer. Work in short sessions and stop at a passing checkpoint.

A finish line you can see

Your own checker library, application, tests and presets; a locally built renderer and image; and a short build map with reproduction commands.

Author the one-file project and then the library/test version before comparing snapshots.
Demonstrate and repair a link failure and a test failure in your practice copy.
Use the Clang/Ninja presets to configure, build, and test the native renderer.
Explain PUBLIC versus PRIVATE using a real header dependency.
Record the scope of the sanitizer checks and one remaining platform limitation.
Leave the project passing and save your smallest next action.

Keep the evidence in your weekly notebook ↗

Explain it like an engineer

Try answering aloud before opening the review notes. Use your own implementation as evidence.

What happens between editing a .cpp file and running a new executable?

Describe configuration versus incremental build.
Explain compilation of translation units and linking definitions.
Distinguish building from running tests.

Why can changing a compiler in an existing build tree cause trouble?

CMake caches toolchain identity and probes.
Use a separate binary directory for incompatible toolchain changes.
Verify actual compiler and standard-library support rather than trusting the executable name.

These prompts support practice; they are not an automatic assessment of your work.

A tip for this exercise

Keep a build notebook with your working directory, compiler version, and the first failing command. Those three facts usually explain more than a page of flags when you return after a break.

Hints, when you need them.

Try a first step, then reveal as much help as you need. Each hint gets a little more specific.

1Hint 1 · Find a starting point

Start in your own empty my-checker folder. Label each command configure, build, test, or run; each step establishes only its own part of the pipeline.

2Hint 2 · Choose an approach

Author the one-file target, then the library and tests. Inspect verbose output to connect each source, object, and linked executable; record presets only after the manual commands work.

3Hint 3 · Check your reasoning

Your checker should print 32, 224, 32. Diagnose and repair a link failure and a test failure, then apply the same graph to native/ using the clang-debug, clang-release, and clang-sanitize presets.

A small creative variation ↗

In your own project, add a second tiny executable that links the same core library. Build that target alone and explain which requirements it inherited.

Optional. Save it for later if this chapter already feels full.

Coming back after a break? ↩

Stay in native/. Read your last compiler version, run the Debug build and tests, and name the next failing stage. Do not reinstall the toolchain just because a source file has an error.

Books & principles behind this study +

Original Parallax explanations and assignments, with these works for further reading.

YOUR MARGIN NOTES

Leave yourself a good question.

What changed your mind? What would you try next?

Notes for Build your studio

Notes are private to this browser and saved as you write.

A CHECKPOINT, NOT A SCORE

Can you explain the idea and try the exercise yourself?

Completion records your own assessment. It does not compile or test your C++.

Companion source 12 files