V2: WASI, -r flag, CI pipeline, examples & tests cleanup

WASI / wasm32 target support
- Auto-detect /usr/share/wasi-sysroot on Linux when target starts_with("wasm32")
- Skip -march/-mtune for wasm (clang rejects them)
- Apply -fno-exceptions -fno-c++-static-destructors -mllvm -wasm-enable-sjlj
  -D_WASI_EMULATED_SIGNAL to wasm builds (compile + std PCM, kept in sync)
- .wasm output extension in expectedOutputFor and link command
- EnableWasiBrowserRuntime(cfg): opt-in helper that drops index.html +
  runtime.js next to the .wasm; runtime.js reads window.CRAFTER_WASM_URL
  set in the templated index.html so a single shim handles any output name

-r run flag in the CLI: build then exec the artifact (host targets only;
  rejects libraries; auto .exe/.wasm extension handling)

CI pipeline (.forgejo/workflows/ci.yaml)
- Triggers: PR/push to master + manual dispatch
- Single arch-latest container job: install deps, bootstrap, self-rebuild,
  run tests, cross-compile mingw, package both archives, upload artifacts
- Rolling 'latest' release published only on push/dispatch to master

mingw cross-compile from Linux now works end-to-end:
- ExternalDependency cache key includes target so per-target glslang builds
  don't collide; CMAKE_BUILD_TYPE=Release pinned (otherwise glslang appends
  'd' to lib names and breaks linking); cross-compile cmake flags
  (CMAKE_SYSTEM_NAME=Windows, CMAKE_*_COMPILER_TARGET=...)
- project.cpp accepts --target=<triple>; Linux-only -Wl,--export-dynamic
  and -ldl are gated; mingw glslang skips the standalone exe (its libgcc_eh
  link pulls pthread which mingw doesn't link by default)
- mingw compile uses -femulated-tls so std::__once_callable etc reference
  the same emutls symbols libstdc++ provides
- mingw link auto-adds -lstdc++exp -lpthread

GetCrafterBuildHome() exposed from the Platform module; LoadProject (Linux
+ Windows) now both use it instead of duplicating the resolution.

Examples reorg: hello-world, library, with-module, wasi, tests — each with
its own README. Tests reorg: per-test directory with inner/ fixture, no
shared tests/fixtures/ tree. New Wasi test verifies .wasm magic bytes.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

examples/README.md

@@ -0,0 +1,12 @@
+# Examples
+
+Self-contained projects, ordered from simplest to most full-featured. Each example has its own README explaining what it shows.
+
+| Example | What it shows |
+|---|---|
+| [hello-world](hello-world/) | The minimum: `project.cpp` + `main.cpp` |
+| [with-module](with-module/) | Adding a C++ module interface |
+| [library](library/) | Library + executable, linked via `cfg.dependencies` |
+| [tests](tests/) | Auto-discovered tests + tests that link the parent library |
+
+Each example builds standalone: `cd examples/<name> && crafter-build`. Test examples: `crafter-build test`.

examples/hello-world/README.md

@@ -0,0 +1,11 @@
+# hello-world
+
+The smallest possible Crafter project: one `main.cpp`, one `project.cpp`.
+
+```sh
+cd examples/hello-world
+crafter-build
+./bin/hello-x86_64-pc-linux-gnu-native/hello
+```
+
+`project.cpp` returns a `Configuration` describing the build. `GetInterfacesAndImplementations` takes lists of source-file *stems* (no extension) — the build system appends `.cpp` to implementations and `.cppm` to interfaces.

examples/hello-world/main.cpp

@@ -0,0 +1,6 @@
+import std;
+
+int main() {
+    std::println("hello from crafter-build");
+    return 0;
+}

examples/hello-world/project.cpp

@@ -0,0 +1,18 @@
+import std;
+import Crafter.Build;
+namespace fs = std::filesystem;
+using namespace Crafter;
+
+extern "C" Configuration CrafterBuildProject(std::span<const std::string_view>) {
+    Configuration cfg;
+    cfg.path = "./";
+    cfg.name = "hello";
+    cfg.outputName = "hello";
+    cfg.target = "x86_64-pc-linux-gnu";
+    cfg.type = ConfigurationType::Executable;
+
+    std::array<fs::path, 0> ifaces = {};
+    std::array<fs::path, 1> impls = { "main" };
+    cfg.GetInterfacesAndImplementations(ifaces, impls);
+    return cfg;
+}

examples/library/README.md

@@ -0,0 +1,21 @@
+# library
+
+A static library + an executable that consumes it.
+
+```sh
+cd examples/library
+crafter-build
+./bin/math-app-x86_64-pc-linux-gnu-native/math-app
+```
+
+Layout:
+
+```
+mylib/MyMath.cppm     # the library's module interface
+main.cpp              # the consumer
+project.cpp           # declares both, with cfg.dependencies wiring them
+```
+
+Two `Configuration` objects: a `LibraryStatic` and an `Executable` whose `dependencies` points at the lib. The build runs them in parallel and links `libMyMath.a` into `math-app` automatically. `import MyMath;` in `main.cpp` resolves through the dep graph — no header paths to hand-wire.
+
+The `static unique_ptr<Configuration>` for the lib is the canonical lifetime pattern: the parent's `dependencies` is `vector<Configuration*>` (raw), so something needs to keep the lib alive across the function return. File-local `static` does it cleanly without a global pool.

examples/library/main.cpp

@@ -0,0 +1,8 @@
+import std;
+import MyMath;
+
+int main() {
+    std::println("Square(5) = {}", Square(5));
+    std::println("Cube(3)   = {}",  Cube(3));
+    return 0;
+}

examples/library/mylib/MyMath.cppm

@@ -0,0 +1,5 @@
+export module MyMath;
+import std;
+
+export int Square(int x) { return x * x; }
+export int Cube(int x)   { return x * x * x; }

examples/library/project.cpp

@@ -0,0 +1,37 @@
+import std;
+import Crafter.Build;
+namespace fs = std::filesystem;
+using namespace Crafter;
+
+extern "C" Configuration CrafterBuildProject(std::span<const std::string_view>) {
+    // The library — built into mylib/bin/MyMath-<target>-<march>/libMyMath.a
+    // and exposed to consumers via cfg.dependencies. The static unique_ptr
+    // keeps the Configuration alive for the duration of the build (the
+    // consumer holds a raw pointer to it).
+    static auto lib = std::make_unique<Configuration>();
+    lib->path = "./mylib/";
+    lib->name = "MyMath";
+    lib->outputName = "MyMath";
+    lib->target = "x86_64-pc-linux-gnu";
+    lib->type = ConfigurationType::LibraryStatic;
+    {
+        std::array<fs::path, 1> ifaces = { "MyMath" };
+        std::array<fs::path, 0> impls = {};
+        lib->GetInterfacesAndImplementations(ifaces, impls);
+    }
+
+    // The consumer — main.cpp imports MyMath. The build resolves the import
+    // through cfg.dependencies and links libMyMath.a automatically.
+    Configuration cfg;
+    cfg.path = "./";
+    cfg.name = "math-app";
+    cfg.outputName = "math-app";
+    cfg.target = "x86_64-pc-linux-gnu";
+    cfg.type = ConfigurationType::Executable;
+    cfg.dependencies = { lib.get() };
+
+    std::array<fs::path, 0> ifaces = {};
+    std::array<fs::path, 1> impls  = { "main" };
+    cfg.GetInterfacesAndImplementations(ifaces, impls);
+    return cfg;
+}

examples/tests/README.md

@@ -0,0 +1,54 @@
+# tests
+
+Two ways to write tests, in one project.
+
+```sh
+cd examples/tests
+crafter-build test
+```
+
+Layout:
+
+```
+mylib/MyMath.cppm                  # the library being tested
+project.cpp                        # declares the library
+
+tests/Smoke/main.cpp               # zero-config test (no project.cpp)
+tests/UnitMyMath/main.cpp          # test that links MyMath and exercises it
+tests/UnitMyMath/project.cpp       # required for tests with deps
+```
+
+## Auto-discovery
+
+Each `tests/<Name>/` directory becomes a test. Three layers, escalate only as needed:
+
+1. **`tests/<Name>/main.cpp`** with no `project.cpp` — discovery synthesizes a Configuration. Top-level `*.cpp` files become implementations, `interfaces/*.cppm` become module interfaces. `Smoke` is this case.
+2. **`tests/<Name>/project.cpp`** — full control. Use this when you need defines, dependencies, or non-default targets. `UnitMyMath` is this case (it depends on `MyMath`).
+3. Folders starting with `_` or `.` are skipped (e.g. `tests/_shared/` for cross-test helpers).
+
+## Test conventions
+
+- Exit code `0` = pass, anything nonzero = fail, **`77` = skipped** (autoconf convention). Use `std::exit(77)` for runtime skips like "tool not on PATH".
+- Each test runs in its own subprocess; a segfault doesn't take down the runner.
+- Default timeout is 60 s (`crafter-build test --timeout=N` overrides).
+- Filter by name: `crafter-build test 'Unit*'`. List without running: `crafter-build test --list`.
+
+## Linking the parent project
+
+`UnitMyMath/project.cpp` shows how a test links the project's own library:
+
+```cpp
+cfg.dependencies = { ParentLib("MyMath") };
+```
+
+`ParentLib("name")` looks up a `Configuration*` in the parent project (the root project's own config + its dependency graph) by `Configuration::name`. The fixture's project.cpp can omit `cfg.path`, `cfg.name`, etc. — the discovery loop fills folder-derived defaults.
+
+## Cross-target test runs
+
+Tests parse `--target=...` from the project args you pass on the command line:
+
+```sh
+crafter-build test --target=x86_64-w64-mingw32 --runner=cmd:wine
+```
+
+`--runner=<spec>` overrides the per-target runner for this invocation. Useful specs: `local`, `cmd:<command>` (prefix-exec, e.g. `cmd:wine`, `cmd:qemu-aarch64`), `ssh:<host>[:<remoteDir>]`, `sshwin:<host>[:<remoteDir>]`. Or persist via env var: `CRAFTER_BUILD_RUNNER_<normalized_target>=<spec>`.

examples/tests/mylib/MyMath.cppm

@@ -0,0 +1,5 @@
+export module MyMath;
+import std;
+
+export int Square(int x) { return x * x; }
+export int Cube(int x)   { return x * x * x; }

examples/tests/project.cpp

@@ -0,0 +1,20 @@
+import std;
+import Crafter.Build;
+namespace fs = std::filesystem;
+using namespace Crafter;
+
+// A pure library project: the root Configuration is the lib itself. Tests
+// under tests/ are auto-discovered (see tests/Smoke and tests/UnitMyMath).
+extern "C" Configuration CrafterBuildProject(std::span<const std::string_view>) {
+    Configuration cfg;
+    cfg.path = "./mylib/";
+    cfg.name = "MyMath";
+    cfg.outputName = "MyMath";
+    cfg.target = "x86_64-pc-linux-gnu";
+    cfg.type = ConfigurationType::LibraryStatic;
+
+    std::array<fs::path, 1> ifaces = { "MyMath" };
+    std::array<fs::path, 0> impls = {};
+    cfg.GetInterfacesAndImplementations(ifaces, impls);
+    return cfg;
+}

examples/tests/tests/Smoke/main.cpp

@@ -0,0 +1,8 @@
+// Single-file test: no project.cpp needed. The folder name "Smoke" becomes
+// the test name. Exit 0 = pass, anything else = fail, exit 77 = skipped.
+import std;
+
+int main() {
+    if (1 + 1 != 2) return 1;
+    return 0;
+}

examples/tests/tests/UnitMyMath/main.cpp

@@ -0,0 +1,8 @@
+import std;
+import MyMath;
+
+int main() {
+    if (Square(5) != 25) return 1;
+    if (Cube(3)   != 27) return 1;
+    return 0;
+}

examples/tests/tests/UnitMyMath/project.cpp

@@ -0,0 +1,22 @@
+import std;
+import Crafter.Build;
+namespace fs = std::filesystem;
+using namespace Crafter;
+
+// Test that links the parent project's library so it can `import MyMath;`
+// and call its functions. ParentLib(name) walks the parent project's
+// dependency graph (and the parent itself) to find a Configuration by name.
+extern "C" Configuration CrafterBuildProject(std::span<const std::string_view>) {
+    Configuration cfg;
+    cfg.path = "tests/UnitMyMath/";
+    cfg.name = "UnitMyMath";
+    cfg.outputName = "UnitMyMath";
+    cfg.target = "x86_64-pc-linux-gnu";
+    cfg.type = ConfigurationType::Executable;
+    cfg.dependencies = { ParentLib("MyMath") };
+
+    std::array<fs::path, 0> ifaces = {};
+    std::array<fs::path, 1> impls = { "main" };
+    cfg.GetInterfacesAndImplementations(ifaces, impls);
+    return cfg;
+}

examples/wasi/README.md

@@ -0,0 +1,40 @@
+# WASI
+
+Build a C++26 program for the `wasm32-wasi` target and run it in a browser.
+
+## Prerequisites
+
+- `wasi-libc`, `wasi-libc++`, `wasi-libc++abi` (Arch packages — provide
+  `/usr/share/wasi-sysroot/`, which `crafter-build` finds automatically).
+  Other distros: install the WASI SDK and set `cfg.sysroot` in `project.cpp`.
+
+## Build
+
+```bash
+crafter-build
+```
+
+Output lands in `bin/wasi-hello-wasm32-wasip1-native/`:
+
+- `wasi-hello.wasm` — the compiled module
+- `index.html` + `runtime.js` — a minimal in-browser WASI shim, dropped in by
+  `EnableWasiBrowserRuntime(cfg)` in `project.cpp`. Stdout goes to the browser
+  console.
+
+## Run in a browser
+
+```bash
+./serve.sh                  # any static file server works
+```
+
+Open `http://localhost:8080/`. The string from `main()` shows up in the
+DevTools console.
+
+## Run in a standalone runtime
+
+If you don't need the browser, drop the `EnableWasiBrowserRuntime(cfg)` line
+from `project.cpp` and run the `.wasm` directly:
+
+```bash
+wasmtime bin/wasi-hello-wasm32-wasip1-native/wasi-hello.wasm
+```

examples/wasi/main.cpp

@@ -0,0 +1,6 @@
+import std;
+
+int main() {
+    std::println("Hello, WASI!");
+    return 0;
+}

examples/wasi/project.cpp

@@ -0,0 +1,24 @@
+import std;
+import Crafter.Build;
+namespace fs = std::filesystem;
+using namespace Crafter;
+
+extern "C" Configuration CrafterBuildProject(std::span<const std::string_view>) {
+    Configuration cfg;
+    cfg.path = "./";
+    cfg.name = "wasi-hello";
+    cfg.outputName = "wasi-hello";
+    cfg.target = "wasm32-wasip1";
+    cfg.type = ConfigurationType::Executable;
+
+    std::array<fs::path, 0> ifaces = {};
+    std::array<fs::path, 1> impls = { "main" };
+    cfg.GetInterfacesAndImplementations(ifaces, impls);
+
+    // Drop a small index.html + runtime.js next to the .wasm so a static file
+    // server is enough to run it in the browser. Skip this call when targeting
+    // a standalone runtime like wasmtime — you don't need the shim then.
+    EnableWasiBrowserRuntime(cfg);
+
+    return cfg;
+}

examples/wasi/serve.sh

@@ -0,0 +1,2 @@
+#!/usr/bin/env sh
+caddy file-server --listen :8080 --root bin/wasi-hello-wasm32-wasip1-native

examples/with-module/README.md

@@ -0,0 +1,11 @@
+# with-module
+
+Adds a C++ module interface (`interfaces/Greeter.cppm`) imported by `main.cpp`.
+
+```sh
+cd examples/with-module
+crafter-build
+./bin/greeter-app-x86_64-pc-linux-gnu-native/greeter-app
+```
+
+Interfaces are listed by their stem path (relative to `cfg.path`, no `.cppm` extension). The build emits `Greeter.pcm` once and `main_impl.o` consumes it. Touching `interfaces/Greeter.cppm` causes only `main_impl.o` to recompile, not the whole world.

examples/with-module/interfaces/Greeter.cppm

@@ -0,0 +1,6 @@
+export module Greeter;
+import std;
+
+export std::string Greet(std::string_view name) {
+    return std::format("hello, {}!", name);
+}

examples/with-module/main.cpp

@@ -0,0 +1,7 @@
+import std;
+import Greeter;
+
+int main() {
+    std::println("{}", Greet("world"));
+    return 0;
+}

examples/with-module/project.cpp

@@ -0,0 +1,18 @@
+import std;
+import Crafter.Build;
+namespace fs = std::filesystem;
+using namespace Crafter;
+
+extern "C" Configuration CrafterBuildProject(std::span<const std::string_view>) {
+    Configuration cfg;
+    cfg.path = "./";
+    cfg.name = "greeter-app";
+    cfg.outputName = "greeter-app";
+    cfg.target = "x86_64-pc-linux-gnu";
+    cfg.type = ConfigurationType::Executable;
+
+    std::array<fs::path, 1> ifaces = { "interfaces/Greeter" };
+    std::array<fs::path, 1> impls  = { "main" };
+    cfg.GetInterfacesAndImplementations(ifaces, impls);
+    return cfg;
+}