new tests

examples/tests/README.md

@@ -1,6 +1,7 @@
 # tests
 
-Two ways to write tests, in one project.
+Tests are declared in `project.cpp` via `cfg.AddTest(name)`. One line per
+test; deps and other options chain off the returned builder.
 
 ```sh
 cd examples/tests
@@ -11,20 +12,31 @@ Layout:
 
 ```
 mylib/MyMath.cppm                  # the library being tested
-project.cpp                        # declares the library
+project.cpp                        # declares the library and its tests
 
-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
+tests/Smoke/main.cpp               # zero-config test
+tests/UnitMyMath/main.cpp          # test that links MyMath
 ```
 
-## Auto-discovery
+`project.cpp` does:
 
-Each `tests/<Name>/` directory becomes a test. Three layers, escalate only as needed:
+```cpp
+cfg.AddTest("Smoke");                                  // exit 0 = pass
+cfg.AddTest("UnitMyMath").Dependencies({ &cfg });      // imports MyMath
+```
 
-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).
+`AddTest(name)` defaults the source to `tests/<name>/main.cpp` (resolved at
+the project root) and the target/march/mtune to the parent project's. The
+builder methods overlay overrides:
+
+- `.Target(triple)` / `.March(...)` / `.Mtune(...)` / `.Sysroot(path)`
+- `.Define(name, value)` / `.Debug()`
+- `.Timeout(seconds)`
+- `.Args(vec)`  &mdash; runtime args
+- `.Requires("tool:foo")` / `.Requires("file:/path")` / `.Requires("env:VAR")`
+- `.Dependencies({ &otherCfg, ... })`
+- `.Path(p)` &mdash; rebase the test's source-resolution path
+- `.LinkFlag(s)` / `.CompileFlag(s)`
 
 ## Test conventions
 
@@ -35,20 +47,46 @@ Each `tests/<Name>/` directory becomes a test. Three layers, escalate only as ne
 
 ## 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.
+`UnitMyMath` depends on the library via `.Dependencies({ &cfg })` &mdash; the
+test imports `MyMath` and the build engine links `cfg`'s output into the
+test exe.
 
 ## Cross-target test runs
 
-Tests parse `--target=...` from the project args you pass on the command line:
+`AddTest` inherits the parent project's target; for per-test cross-arch
+runs, override via the builder:
 
-```sh
-crafter-build test --target=x86_64-w64-mingw32 --runner=cmd:wine
+```cpp
+cfg.AddTest("CrossArchAarch64")
+   .Target("aarch64-linux-gnu")
+   .Sysroot("/opt/aarch64-rootfs")
+   .Requires("tool:qemu-aarch64");
 ```
 
-`--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>`.
+`crafter-build test` sweeps every distinct target declared across the
+project's tests plus the host triple, so cross-arch tests run by default.
+`--target=<triple>` restricts the run to that target.
+
+`--runner=<spec>` overrides the per-target runner for one invocation.
+Useful specs: `local`, `cmd:<command>` (e.g. `cmd:wine`, `cmd:qemu-aarch64`).
+Persistent override via env: `CRAFTER_BUILD_RUNNER_<normalized_target>=<spec>`.
+
+## SIMD march fan-out
+
+For libraries with per-march SIMD codegen (e.g. Crafter.Math), use
+`AddMarchVariants` to produce one Test per tier sharing the same source
+and interface set:
+
+```cpp
+constexpr MarchTier tiers[] = {
+    {"sapphirerapids", "native"},
+    {"x86-64-v4",      "generic"},
+    {"x86-64-v3",      "generic"},
+};
+cfg.AddMarchVariants("Vector", libInterfaces, tiers);
+```
+
+Each tier becomes a Test named `Vector-<march>`, with the library's
+interfaces rebuilt under that tier's `-march`/`-mtune` (so codegen actually
+varies). Per-arch gating is just an `if (target.starts_with("x86_64"))`
+guard around the call &mdash; no special toml syntax.