@zackees/soldr 0.9.11 → 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
CHANGED
|
@@ -46,20 +46,133 @@ Current release line:
|
|
|
46
46
|
- the supported external integration boundary remains the `soldr` executable, not the internal Rust crates; see [docs/API_BOUNDARY.md](./docs/API_BOUNDARY.md)
|
|
47
47
|
- practical integration examples for local builds and GitHub Actions live in [INTEGRATION.md](./INTEGRATION.md)
|
|
48
48
|
|
|
49
|
-
##
|
|
49
|
+
## Quick start
|
|
50
50
|
|
|
51
51
|
```bash
|
|
52
|
-
|
|
53
|
-
|
|
52
|
+
# 1. Install or upgrade (same command)
|
|
53
|
+
uv tool install --upgrade soldr
|
|
54
|
+
|
|
55
|
+
# 2. Put `soldr` in front of every Rust command
|
|
56
|
+
soldr cargo build --release
|
|
57
|
+
soldr cargo test
|
|
58
|
+
soldr cargo clippy --workspace
|
|
59
|
+
|
|
60
|
+
# 3. See what the cache is doing
|
|
61
|
+
soldr status
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
That is the whole integration. The first cacheable compile starts the
|
|
65
|
+
`soldr-daemon` sidecar, pins the toolchain from `rust-toolchain.toml`, and
|
|
66
|
+
every later build on any branch or worktree hits the shared cache.
|
|
67
|
+
|
|
68
|
+
<details>
|
|
69
|
+
<summary><b>Command reference</b></summary>
|
|
70
|
+
|
|
71
|
+
### Everyday
|
|
72
|
+
|
|
73
|
+
| Command | What it does |
|
|
74
|
+
|---|---|
|
|
75
|
+
| `soldr cargo <args>` | Run cargo through the cache with the pinned toolchain |
|
|
76
|
+
| `soldr build --target <triple\|alias>` | Blessed cross-compile with a managed SDK (`win-x64`, `mac-arm64`, `linux-x64-musl`, ...) |
|
|
77
|
+
| `soldr cc` / `soldr c++` | Compile C / C++ with a catalogue-backed toolchain |
|
|
78
|
+
| `soldr lint` | Unified Rust and dependency lint suites |
|
|
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
|
+
| `soldr <tool>` | Fetch and run a pre-built ecosystem tool: `nextest`, `deny`, `audit`, `mdbook`, `just`, ... |
|
|
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>
|
|
54
107
|
```
|
|
55
108
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
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
|
+
|
|
125
|
+
### Toolchain
|
|
126
|
+
|
|
127
|
+
| Command | What it does |
|
|
128
|
+
|---|---|
|
|
129
|
+
| `soldr rustc`, `rustfmt`, `clippy-driver`, `rustdoc` | Pinned-toolchain passthroughs |
|
|
130
|
+
| `soldr rustup <args>` | Passthrough to rustup, toolchain-aware |
|
|
131
|
+
| `soldr toolchain ensure` | Bootstrap rustup, install the pinned channel, components, and targets |
|
|
132
|
+
| `soldr toolchain link --shim-dir <dir>` | Write PATH shims that re-enter soldr |
|
|
133
|
+
| `soldr doctor` | Report drift between `rust-toolchain.toml` and rustup |
|
|
134
|
+
| `soldr rust-analyzer`, `rust-gdb`, `rust-lldb` | Language server and debuggers |
|
|
135
|
+
|
|
136
|
+
### Cache
|
|
137
|
+
|
|
138
|
+
| Command | What it does |
|
|
139
|
+
|---|---|
|
|
140
|
+
| `soldr status` | Cache status and active toolchain |
|
|
141
|
+
| `soldr cache` | Inspect compilation cache entries |
|
|
142
|
+
| `soldr cook` | Prebuild dependencies via bundled cargo-chef |
|
|
143
|
+
| `soldr save` / `soldr load` | Bundle a build cache to `.tar.zst` and restore it on a fresh checkout |
|
|
144
|
+
| `soldr gc` | Review reclaimable cargo `target/` directories |
|
|
145
|
+
| `soldr clean` / `soldr purge` | Clear the build cache / purge every soldr-managed artifact |
|
|
146
|
+
| `soldr config` | Show or set configuration in `~/.soldr/config.toml` |
|
|
147
|
+
|
|
148
|
+
### Ops
|
|
149
|
+
|
|
150
|
+
| Command | What it does |
|
|
151
|
+
|---|---|
|
|
152
|
+
| `soldr daemon start\|stop` | Manage the long-lived `soldr-daemon` process |
|
|
153
|
+
| `soldr optimize` | Platform-specific hot-cache tuning |
|
|
154
|
+
| `soldr defender-exclusions` | Manage Windows Defender exclusions for soldr caches |
|
|
155
|
+
| `soldr help <command>` | Full help for any command |
|
|
156
|
+
|
|
157
|
+
</details>
|
|
158
|
+
|
|
159
|
+
Also on npm as `@zackees/soldr`: a small launcher that downloads the matching
|
|
160
|
+
GitHub Release binary during install and verifies it against the published
|
|
161
|
+
`SHA256SUMS` file.
|
|
59
162
|
|
|
60
163
|
Published npm archives and PyPI wheels support both Intel (`x86_64`) and Apple
|
|
61
|
-
Silicon (`arm64`) macOS.
|
|
62
|
-
|
|
164
|
+
Silicon (`arm64`) macOS. Both are cross-built through soldr's blessed Apple
|
|
165
|
+
SDK path on Linux; Intel artifacts are then smoke-tested inside a
|
|
166
|
+
[zackees/docker-mac-x64](https://github.com/zackees/docker-mac-x64) macOS
|
|
167
|
+
Recovery guest hosted on an ordinary Linux runner before release (no GitHub
|
|
168
|
+
Actions job runs on a native macOS runner). The same Recovery guest also
|
|
169
|
+
replays the real `x86_64-apple-darwin` nextest archive -- toolchain
|
|
170
|
+
provisioning included -- on every pull request and again at the release
|
|
171
|
+
commit before publish, so Intel macOS gets the same positively-owned native
|
|
172
|
+
test coverage every other cross-built target gets, without a native macOS
|
|
173
|
+
runner anywhere in the pipeline. Apple Silicon artifacts are cross-built the
|
|
174
|
+
same way but are not executed anywhere in CI until a follow-up issue
|
|
175
|
+
re-enables that before release.
|
|
63
176
|
|
|
64
177
|
## GitHub Actions setup
|
|
65
178
|
|
|
@@ -76,6 +189,8 @@ The current GitHub Actions entry point is the public `setup-soldr` action:
|
|
|
76
189
|
|
|
77
190
|
That action:
|
|
78
191
|
|
|
192
|
+
> **Deprecated (soldr#2996).** soldr no longer implements a target cache, so the `target-cache` / `target-cache-mode` / `target-dir` inputs and the `target-cache-hit` / `target-cache-mode` outputs are inert: nothing on the soldr side reads the environment they export. They remain listed because the pinned action still declares them; retiring the inputs themselves is an upstream change. Use `soldr cook`, which is the only durable compiler cache.
|
|
193
|
+
|
|
79
194
|
- installs `soldr`
|
|
80
195
|
- bootstraps `rustup` into the cached runner-local root when the runner does not already have it
|
|
81
196
|
- preinstalls the exact Rust toolchain from `rust-toolchain.toml` by default via `rustup`
|
|
@@ -24,11 +24,6 @@
|
|
|
24
24
|
"gate": "hard",
|
|
25
25
|
"command": "soldr --no-cache cargo nextest run -p soldr-cli --test cargo_front_door -E 'test(/^cli_cargo_wrappers::/)'"
|
|
26
26
|
},
|
|
27
|
-
{
|
|
28
|
-
"id": "rust-rust-plan",
|
|
29
|
-
"gate": "hard",
|
|
30
|
-
"command": "soldr --no-cache cargo nextest run -p soldr-cli --test cargo_front_door -E 'test(/^cli_rust_plan::/)'"
|
|
31
|
-
},
|
|
32
27
|
{
|
|
33
28
|
"id": "rust-cache-cli",
|
|
34
29
|
"gate": "hard",
|
|
@@ -124,26 +119,6 @@
|
|
|
124
119
|
"rust-cache-session"
|
|
125
120
|
]
|
|
126
121
|
},
|
|
127
|
-
{
|
|
128
|
-
"id": "rust-plan-cache",
|
|
129
|
-
"axis": "rust artifact plan",
|
|
130
|
-
"gate": "hard",
|
|
131
|
-
"covers": [
|
|
132
|
-
"in-process restore before cargo",
|
|
133
|
-
"in-process save after cargo",
|
|
134
|
-
"artifact bundle cache dir",
|
|
135
|
-
"partial restore warning",
|
|
136
|
-
"embedded compile counts drive warm-save decisions"
|
|
137
|
-
],
|
|
138
|
-
"test_files": [
|
|
139
|
-
"crates/soldr-cli/tests/cargo_front_door/cli_rust_plan.rs",
|
|
140
|
-
"crates/soldr-cli/src/rust_plan_tests",
|
|
141
|
-
"crates/soldr-cli/src/cargo_front_door/cache_plan.rs"
|
|
142
|
-
],
|
|
143
|
-
"validation_command_ids": [
|
|
144
|
-
"rust-rust-plan"
|
|
145
|
-
]
|
|
146
|
-
},
|
|
147
122
|
{
|
|
148
123
|
"id": "disabled-and-non-build",
|
|
149
124
|
"axis": "cache scoping",
|