@zackees/soldr 0.9.12 → 0.9.13
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +44 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -76,9 +76,52 @@ every later build on any branch or worktree hits the shared cache.
|
|
|
76
76
|
| `soldr build --target <triple\|alias>` | Blessed cross-compile with a managed SDK (`win-x64`, `mac-arm64`, `linux-x64-musl`, ...) |
|
|
77
77
|
| `soldr cc` / `soldr c++` | Compile C / C++ with a catalogue-backed toolchain |
|
|
78
78
|
| `soldr lint` | Unified Rust and dependency lint suites |
|
|
79
|
-
| `soldr ci-test` | The prescribed host-validation DAG used in CI |
|
|
79
|
+
| `soldr ci-test` | **The supported way to test soldr-built projects.** The prescribed host-validation DAG used in CI — see [Testing strategy](#testing-strategy) |
|
|
80
80
|
| `soldr <tool>` | Fetch and run a pre-built ecosystem tool: `nextest`, `deny`, `audit`, `mdbook`, `just`, ... |
|
|
81
81
|
|
|
82
|
+
### Testing strategy
|
|
83
|
+
|
|
84
|
+
**Use `soldr ci-test`.** It is the supported long-term testing path and the
|
|
85
|
+
fastest one available: a frozen DAG that maximizes sharing by compile domain, so
|
|
86
|
+
stable host Clippy subsumes `cargo check`, nextest test-profile compilation
|
|
87
|
+
completes before execution overlaps the Dylint branch, and doctests join both.
|
|
88
|
+
Hand-rolled sequences of `cargo fmt` + `cargo clippy` + `cargo nextest` + doctests
|
|
89
|
+
recompile the same crates several times over and drift apart from what CI runs.
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
soldr ci-test # the whole host-validation DAG
|
|
93
|
+
soldr ci-test --explain-plan --format json # inspect the plan, no compiler work
|
|
94
|
+
soldr ci-test --package soldr-core # host-scope narrowing
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
**Know the one boundary.** `ci-test` validates on the *host* and deliberately
|
|
98
|
+
**rejects** `--target`, `--toolchain` and `--profile` rather than silently
|
|
99
|
+
creating a different compile domain. So it is not the tool for *executing*
|
|
100
|
+
binaries built for another platform. For that, build a nextest archive on the
|
|
101
|
+
cross-build lane and replay it on the target:
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
soldr cargo nextest archive --target <triple> --archive-file tests.tar.zst
|
|
105
|
+
# then, on (or emulating) the target:
|
|
106
|
+
cargo-nextest nextest run --archive-file tests.tar.zst --workspace-remap <checkout>
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Two things bite consumers here, both observed rather than hypothesised:
|
|
110
|
+
|
|
111
|
+
* `cargo-nextest` is a **cargo subcommand shim**. Invoked as `cargo-nextest run`
|
|
112
|
+
it proxies to cargo, which replies `unrecognized subcommand 'run'` — an error
|
|
113
|
+
that reads like a broken archive. The `nextest` verb is required.
|
|
114
|
+
* A replay needs the **project source**, because the archive records its
|
|
115
|
+
workspace root. Without it: `error: workspace root manifest at ... does not
|
|
116
|
+
exist`. `--workspace-remap` must point at a real checkout.
|
|
117
|
+
|
|
118
|
+
A blessed `--execution container` mode that does all of this for you is proposed
|
|
119
|
+
in soldr#3084.
|
|
120
|
+
|
|
121
|
+
And a caution soldr learned the hard way (soldr#2945): **a green CI lane only
|
|
122
|
+
proves the verb CI runs.** When a tool has more than one entry point, check that
|
|
123
|
+
they resolve their inputs through one implementation, or expect them to drift.
|
|
124
|
+
|
|
82
125
|
### Toolchain
|
|
83
126
|
|
|
84
127
|
| Command | What it does |
|