## This repository: Crafter.Build

The execution contexts to enumerate, beside the charter's:
- `project.cpp` is compiled to a shared object and loaded into the running
  crafter-build, resolving `Crafter::` symbols from the executable
  (`--export-dynamic`); its static initialisers run at load. Its sibling
  projects (`GitProject`, `LocalProject`) load the same way into the same
  process, and its `#pragma crafter dependency` targets are built for the
  host first, on every load.
- The clang++, clang and llvm-ar the tool spawns, and the git and cmake it
  runs, are shell commands (`popen`, `std::system` in `:Platform`), many in
  parallel; such a step fails on its exit code, never because it printed.
  Running a test or a built artifact is a shell command too (`:Test`,
  `:Clang`). A path, file name or flag that reaches one with a space or a
  shell metacharacter in it is an input to attack. Other steps run inside
  the process, among them glslang's shader compiles, on a thread of their
  own per stale shader (`:Shader`), and lint's parse through the libclang
  the linter dlopens (`:Lint`).
- Several crafter-build processes share `~/.cache/crafter.build/` at once:
  the std and Crafter.Build PCMs per target and march (the
  `ConcurrentCacheRace` test), and the external clones with their `.lock`
  files.
- Three builds of the tool: the bootstrap from `build.sh` (without
  `CRAFTER_BUILD_HAS_ASSET`), the self-hosted binary on the host's LLVM, and
  the Flatpak on its own LLVM under `/app`, in a sandbox whose `/usr` is the
  Freedesktop SDK's. Their toolchains can be a release apart.
- Targets: the host triple, a sysroot (aarch64, musl), `x86_64-w64-mingw32`
  under wine, `wasm32-wasi*` under wasmtime (or wasmer for `-r`), and
  browser builds through the runtime in `wasi-runtime/`.
- Incremental builds: a first build, a rebuild after an edit, a rebuild
  after a toolchain or flag change and a build after `clean` start from
  different states; whatever changes what gets compiled has to reach
  `VariantId()`, or a stale artifact is reused.
- Tests: each its own subprocess, in parallel, with a 60 s timeout. A test
  that edits or touches files stages a copy under
  `fs::temp_directory_path()`; one that only builds its fixture builds it in
  place, into the fixture's own `bin/` and `build/` in the checkout.

Semantics to read on disk rather than recall: libc++ and clang as the host
installs them (`/run/host/usr/include/c++/v1`,
`/run/host/usr/share/libc++/v1/std.cppm`,
`/run/host/usr/lib/clang/<major>/include`), the dependencies as cloned
(`~/.cache/crafter.build/external/<Name>-<hash>/`), the vendored
`lib/DirStackFileIncluder.h`. The Flatpak's own LLVM is not readable from
here: a semantic that may differ between LLVM releases is unverified for
the Flatpak build.