@convesoft/nx-rust 1.0.0-rc.1 → 1.0.0-rc.2

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.
Files changed (78) hide show
  1. package/PLUGIN.md +106 -0
  2. package/README.md +8 -4
  3. package/docs/artifacts.mara.md +374 -0
  4. package/docs/caching.mara.md +999 -0
  5. package/docs/ci.mara.md +308 -0
  6. package/docs/configuration.mara.md +508 -0
  7. package/docs/decisions.mara.md +3267 -0
  8. package/docs/execution.mara.md +533 -0
  9. package/docs/index.mara.md +51 -0
  10. package/docs/product.mara.md +366 -0
  11. package/docs/release.mara.md +493 -0
  12. package/docs/setup.mara.md +486 -0
  13. package/docs/targets.mara.md +704 -0
  14. package/docs/testing.mara.md +431 -0
  15. package/docs/verification.mara.md +465 -0
  16. package/docs/workspaces.mara.md +445 -0
  17. package/package.json +1 -1
  18. package/src/cargo/build-settings.d.ts +8 -1
  19. package/src/cargo/build-settings.js +21 -11
  20. package/src/cargo/build-settings.js.map +1 -1
  21. package/src/cargo/metadata.d.ts +2 -0
  22. package/src/cargo/metadata.js.map +1 -1
  23. package/src/cargo/redirections.d.ts +4 -1
  24. package/src/cargo/redirections.js +7 -2
  25. package/src/cargo/redirections.js.map +1 -1
  26. package/src/cargo/warnings-setting.d.ts +24 -0
  27. package/src/cargo/warnings-setting.js +81 -0
  28. package/src/cargo/warnings-setting.js.map +1 -0
  29. package/src/executors/cargo/schema.json +4 -0
  30. package/src/executors/cargo-output.d.ts +8 -2
  31. package/src/executors/cargo-output.js +20 -6
  32. package/src/executors/cargo-output.js.map +1 -1
  33. package/src/executors/command.d.ts +13 -0
  34. package/src/executors/command.js +37 -7
  35. package/src/executors/command.js.map +1 -1
  36. package/src/executors/denied-warnings.d.ts +99 -0
  37. package/src/executors/denied-warnings.js +188 -0
  38. package/src/executors/denied-warnings.js.map +1 -0
  39. package/src/executors/group-run.d.ts +1 -1
  40. package/src/executors/group-run.js +23 -13
  41. package/src/executors/group-run.js.map +1 -1
  42. package/src/executors/groups.d.ts +7 -2
  43. package/src/executors/groups.js +22 -3
  44. package/src/executors/groups.js.map +1 -1
  45. package/src/executors/nextest.d.ts +6 -2
  46. package/src/executors/nextest.js +12 -6
  47. package/src/executors/nextest.js.map +1 -1
  48. package/src/executors/task-guards.js +7 -2
  49. package/src/executors/task-guards.js.map +1 -1
  50. package/src/executors/task.js +10 -3
  51. package/src/executors/task.js.map +1 -1
  52. package/src/executors/test-mode.d.ts +4 -1
  53. package/src/executors/test-mode.js +7 -1
  54. package/src/executors/test-mode.js.map +1 -1
  55. package/src/executors/test-steps.d.ts +20 -8
  56. package/src/executors/test-steps.js +45 -14
  57. package/src/executors/test-steps.js.map +1 -1
  58. package/src/graph/caching.js +5 -0
  59. package/src/graph/caching.js.map +1 -1
  60. package/src/graph/clippy-input.d.ts +53 -0
  61. package/src/graph/clippy-input.js +107 -0
  62. package/src/graph/clippy-input.js.map +1 -0
  63. package/src/graph/collisions.d.ts +7 -0
  64. package/src/graph/collisions.js.map +1 -1
  65. package/src/graph/discovery.d.ts +15 -0
  66. package/src/graph/discovery.js +5 -0
  67. package/src/graph/discovery.js.map +1 -1
  68. package/src/graph/inputs.d.ts +3 -1
  69. package/src/graph/inputs.js +11 -1
  70. package/src/graph/inputs.js.map +1 -1
  71. package/src/graph/projects.js +13 -2
  72. package/src/graph/projects.js.map +1 -1
  73. package/src/graph/rustfmt-config.d.ts +42 -0
  74. package/src/graph/rustfmt-config.js +173 -0
  75. package/src/graph/rustfmt-config.js.map +1 -0
  76. package/src/graph/targets.d.ts +11 -7
  77. package/src/graph/targets.js +12 -8
  78. package/src/graph/targets.js.map +1 -1
@@ -0,0 +1,533 @@
1
+ # Batching and features
2
+
3
+ > **Status:** implemented as this page describes, apart from the optional
4
+ > strict per-crate build check of the `hakari` strategy, which is not designed
5
+ > yet (nxr-ys8rx5). Nx hands the plugin's tasks to its batch executors
6
+ > without a flag, tasks of one group share their cargo commands, and each
7
+ > task gets its own result, terminal output and cache entry, under each of
8
+ > the three strategies. With the nextest runner, the call for the selection
9
+ > of affected tests comes with milestone 0.3.
10
+
11
+ Nx schedules one task per crate. Running each as its own cargo process would
12
+ queue them behind Cargo's build lock and repeat work. The plugin instead runs
13
+ each group of them with **one cargo call**, not one per crate, and reports a
14
+ result for every crate. `test` with nextest needs one more call for the
15
+ doctests, and in affected mode one before it for the selection of tests
16
+ ([Testing](testing.mara.md)).
17
+
18
+ ```sh
19
+ nx run-many -t test
20
+ ```
21
+
22
+ ```text
23
+ Nx tasks cargo calls
24
+ api:test ┐
25
+ core:test ├─ rust/, default features, dev profile, host -> 1 call
26
+ cli:test ┘
27
+ xtask:test ── tools/xtask/ (standalone crate) -> 1 call
28
+
29
+ With nextest, each group takes 2 calls (tests, doctests), 3 in affected mode.
30
+ ```
31
+
32
+ You do not pass a flag for this. Nx still hashes, restores and stores each task
33
+ on its own, so a cache hit for `core:test` simply leaves `core` out of the
34
+ group.
35
+
36
+ ## What forms a group
37
+
38
+ A group is the tasks of one kind, such as `test` or `lint`, in one Cargo
39
+ workspace whose cargo commands would differ only in the crates they select: one
40
+ feature set, profile and target triple, and the same target options, such as a
41
+ crate's switch for `--all-targets`. Tasks that differ in any of these run
42
+ separately, one group after another. So do tasks whose `.env` files, such as
43
+ one in a crate's folder, give them different environment variables: each cargo
44
+ call runs with the environment its tasks were keyed with.
45
+
46
+ So that tasks of several crates can share an environment, a Rust build script
47
+ or test does not get the variables `NX_TASK_TARGET_PROJECT` and
48
+ `LERNA_PACKAGE_NAME`, whether its task runs on its own or in a batch, and
49
+ cannot read which Nx project it runs for; `CARGO_PKG_NAME`, which cargo sets,
50
+ names its crate.
51
+
52
+ Tasks in one group share their cargo calls: one for most targets, and with
53
+ nextest one for the tests, one for the doctests and, in affected mode, one for
54
+ the selection before them, with one more after the tests where a test failed,
55
+ which lists the tests that the run was to run. Every call of a group selects its crates the same
56
+ way, so they all compile with the same features
57
+ ([Feature unification](#feature-unification)).
58
+
59
+ Some tasks run one crate per group instead, each with its own cargo command,
60
+ as every task did in milestone 0.1: where cargo would give a crate other
61
+ features depending on which other crates the same command selects. That is
62
+ the case under `hakari` for a feature set given by flags, such as the
63
+ all-features configuration, and for a triple that `.config/hakari.toml` does
64
+ not list, and under `workspace-build` for a non-host triple and for `test`
65
+ where you configured a runner for your host
66
+ ([Tests under `workspace-build`](#tests-under-workspace-build)). So does a
67
+ `test` task with the `test` option, under every strategy, because cargo fails
68
+ an unknown test target only where no selected crate has it
69
+ ([One test target](testing.mara.md#one-test-target)). Those runs do
70
+ not batch, so they are slower, and a dependency that two such tasks need with
71
+ different features is compiled once for each, as in milestone 0.1. A crate's
72
+ result never depends on what else runs.
73
+
74
+ Known limit: while a batch runs, Nx starts no other task. In a mixed repository
75
+ JS tasks wait for the Rust batch ([[RISK-BATCH-BEHAVIOUR]]). A batch also runs
76
+ its groups one after another, so tasks of groups of one crate that
77
+ `--parallel` would run side by side, such as the tests of two crates, run in
78
+ sequence in a batch.
79
+
80
+ ## While a batch runs
81
+
82
+ A task's result appears when its group's cargo commands have ended, and one
83
+ group can take the whole run. So that you see that cargo is working:
84
+
85
+ - In Nx's terminal UI, the default in a terminal, the batch's pane shows
86
+ cargo's lines as they arrive.
87
+ - In every other output style, the batch prints one line each time it starts
88
+ a cargo command, such as
89
+ `@convesoft/nx-rust: cargo test for api, core, cli (step 1 of 3)`.
90
+
91
+ These lines belong to no task: Nx does not store them, and a cache hit does
92
+ not replay them. Each task's own output, which Nx stores, is the same either
93
+ way. Under GitHub Actions, Nx holds back every line of a batch until the batch
94
+ has ended.
95
+
96
+ A Rust task that depends on a continuous task, such as a database that
97
+ `docker compose up` starts, runs in the batch. The one exception is a task
98
+ that waits (`waitFor: "ready"`) for a continuous task whose `readyWhen` is
99
+ `{ "signal": true }`: Nx gives such a task, run on its own, the server's URL
100
+ as `NX_READY_URL`, which it cannot give a batch, so the task fails and says
101
+ so. Run that command with `--batch=false`, or set `NX_BATCH_MODE=false` in the
102
+ root `.env` to run every task of the repository on its own, which turns
103
+ batching off for the tasks of every plugin.
104
+
105
+ ## Two batches
106
+
107
+ `build`, `napi-build`, `wasm-build` and `doc`, whose files Nx stores, run through an
108
+ executor of their own, `@convesoft/nx-rust:cargo-outputs`; the other batched
109
+ targets run
110
+ `@convesoft/nx-rust:cargo`. Nx batches each executor's tasks apart and stores a
111
+ batch only when it ends, so the `build` batch is stored before a `test` batch
112
+ that waits for it starts, and no `cargo test` can change what Nx stores for a
113
+ `build` ([Targets](targets.mara.md#tests-that-build-a-crates-binaries)). A
114
+ command that runs both kinds shows a batch for each. Each batch forms its own
115
+ groups: a `build` that runs one crate per group still runs in the `build` batch.
116
+
117
+ - A `targetDefaults` entry keyed by `@convesoft/nx-rust:cargo` does not reach
118
+ `build`, `napi-build`, `wasm-build` and `doc`. Key it by `@convesoft/nx-rust:cargo-outputs` as well.
119
+ - `nx add` adds an empty entry for each executor of the plugin's targets,
120
+ this one included, where `targetDefaults` has none
121
+ ([Setup](setup.mara.md#adding-the-plugin)).
122
+
123
+ ## When something fails
124
+
125
+ A task is reported successful only when cargo's output shows that its crate
126
+ passed.
127
+
128
+ - A task fails when its own crate fails in any of its group's cargo calls, the
129
+ doctests included, or when a crate it depends on does not compile.
130
+ - `build`, `check` and `lint` keep going after an error, so every task whose
131
+ crate does not need the broken one still gets its own result.
132
+ - Under `workspace-build`, cargo also compiles crates you did not ask for. If
133
+ one of those fails in a `build`, `check` or `lint` run and nothing you asked
134
+ for depends on it, you get a warning, and no task fails.
135
+ - A failing test does not stop the others, so every other `test` task of the
136
+ group still gets its own result.
137
+ - A compile error stops a test run before any test runs, because cargo cannot
138
+ keep going there. Every `test` task of the group then fails, and the message
139
+ names the crate that did not compile and says that the other crates' tests
140
+ were not run. This is a cost of batching: when each task runs its own cargo
141
+ command, as in milestone 0.1, an unrelated crate's tests still pass.
142
+ - Under `workspace-build`, a test run compiles the tests and libraries of
143
+ every crate of the workspace. So a compile error in a crate you did not ask
144
+ to test also fails every `test` task of the group, while `check` only warns
145
+ about it.
146
+
147
+ Known limit: Nx 24 does not tell a batch about `--nx-bail`. Where a group
148
+ fails, the later groups of the same batch still run, apart from tasks whose
149
+ dependency failed, and Nx stores their results as in any run, so not with
150
+ `--skip-nx-cache` and not for targets that are not cached. Nx stops the
151
+ command only once the batch has ended. To stop closer
152
+ to the first failure, run the command with `--batch=false`, so that Nx
153
+ schedules each task on its own.
154
+
155
+ ### Two builds of one crate into one folder
156
+
157
+ Two `build` tasks of one crate in one command whose outputs name one folder,
158
+ the same artifact directory, triple and profile, such as the crate's `build`
159
+ beside its `build` in another configuration, would overwrite each other's
160
+ files. Whenever at least one of them runs, every such task that runs fails
161
+ before cargo starts, and the message names the tasks and the folder. Run them
162
+ in separate commands, so that the tasks of each command, with every task they
163
+ depend on, hold only one of the builds: a target that depends on both brings
164
+ both into one command.
165
+
166
+ Known limit: where Nx restores all of them from its cache, as after each ran
167
+ in a command of its own, no task runs and none fails. Nx writes the files of
168
+ each restored entry and removes none, so at each path the folder holds the
169
+ file of the build restored last, and a file that only the other
170
+ configuration builds, such as a binary with `required-features`, stays. A
171
+ command of its own does not clear such a file either: a `build` stores every
172
+ file at a path it declares, also one that an earlier build left there, and a
173
+ cache hit restores it. A task that reads the folder should read only the
174
+ files it needs.
175
+
176
+ ## Dotenv files
177
+
178
+ Nx gives a task the variables of its dotenv files, such as `.env` in the
179
+ crate's folder or `.env.test` at the root, and the plugin gives cargo exactly
180
+ those, in a batch as when the task runs on its own. Before cargo runs, it
181
+ checks that the files give the same values in every way of running the task.
182
+ Where they might not, the task fails, and the message says what to change:
183
+
184
+ | The task fails where | What to do |
185
+ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
186
+ | A value refers, also through other values, to a variable that Nx sets differently depending on how the task runs, such as `FORCE_COLOR` | Remove the reference |
187
+ | A dotenv file defines `NX_LOAD_DOT_ENV_FILES` | Remove the definition from that file. To switch the loading of dotenv files off, set `NX_LOAD_DOT_ENV_FILES=false` in the environment of the `nx` command: in your shell or CI |
188
+ | `DOTENV_KEY` is set and a vault exists: `.env.vault`, `.local.env.vault` or `.env.local.vault` at the root, even without the plain file, or beside a task file | Remove the vault, or unset `DOTENV_KEY` for the command |
189
+ | A value holds a dynamic or ambiguous `$` form from which the static check cannot tell which variables Nx looks up (such as `${X${Y}}`, `$${NAME}`, `$&` in a referenced value, or an unbraced reference that can join adjacent text) | Use plain `$NAME` or `${NAME}` references with static variable names, brace unbraced references before following text, or escape literal `$` as `\$` |
190
+ | The installed Nx lacks or has changed a part that the dotenv check reads | Use an Nx version that `@convesoft/nx-rust` supports |
191
+
192
+ ## Feature unification
193
+
194
+ Cargo merges the features of shared dependencies across whichever crates are
195
+ built together. If the plugin simply built "whatever is affected", that set
196
+ would change on every run: dependencies would be rebuilt again and again, and a
197
+ crate's result would depend on what else happened to be in its batch.
198
+
199
+ The plugin therefore resolves features for the **whole workspace** wherever
200
+ tasks share a cargo command, with one of three strategies, and runs a crate on
201
+ its own where they cannot:
202
+
203
+ | Strategy | Used when | How | Cost |
204
+ | ----------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
205
+ | `hakari` | The workspace has a cargo-hakari configuration and passes the checks below | Build only the selected crates; the hack crate keeps third-party features unified | The hack crate must be kept current, and a check of it runs in every run |
206
+ | `cargo` | You opt in; experimental | Cargo's `resolver.feature-unification = "workspace"`, with `-Zfeature-unification` | Needs a nightly toolchain until Cargo stabilises it; on stable its tasks fail; a lockfile change runs every crate again |
207
+ | `workspace-build` | Fallback | Build the whole workspace, then run only the test binaries you asked for, and every doctest | Compiles unaffected crates, and compiles and runs every library's doctests in each test run; a compile error in any crate fails every `test` task of the run; needs a warm build directory; a lockfile change runs every crate |
208
+
209
+ Under `workspace-build`, plain cargo shares the plugin's builds where it
210
+ builds the whole workspace too, as `cargo build --workspace` does; a plain
211
+ `cargo build -p api` resolves features for `api` alone and can compile again
212
+ what differs, as it would after a plain `cargo build --workspace`.
213
+
214
+ To choose a strategy yourself, set `featureUnification` in
215
+ `[workspace.metadata.nx]` of one workspace, or in the plugin options for all of
216
+ them ([Configuration](configuration.mara.md#all-settings)).
217
+
218
+ ### Tests under `workspace-build`
219
+
220
+ Cargo cannot leave crates out of a test run without resolving features for the
221
+ rest. So under `workspace-build` a group's `test` tasks compile the tests of the
222
+ whole workspace, also where only one task is left to run, and then:
223
+
224
+ - run only the group's own **test binaries**, through a runner that the plugin
225
+ passes to cargo for your host. Cargo hands every test executable to it, and
226
+ it runs those of the group's crates and skips the others;
227
+ - run the **doctests of every crate** of the workspace with a plain
228
+ `cargo test --doc`, and keep the results of the group's crates.
229
+
230
+ ```sh
231
+ cargo test --workspace --no-run
232
+ cargo test --workspace --tests --no-fail-fast --message-format=json-render-diagnostics \
233
+ --config 'target.x86_64-unknown-linux-gnu.runner=["/usr/bin/node", "…/test-runner.js"]'
234
+ cargo test --workspace --doc --no-fail-fast
235
+ ```
236
+
237
+ The runner is a small Node script, started with the Node that runs Nx. It
238
+ changes nothing that cargo compiles, is never written to a configuration file,
239
+ and passes cargo's environment on to the test unchanged. It records every test
240
+ binary it starts and how it ended, and a task passes only where that record
241
+ holds a passing run of every test binary that cargo's machine-readable messages
242
+ name for its crate; terminal settings such as `CARGO_TERM_QUIET`, and what tests
243
+ print, cannot change that. The doctests are decided by cargo and rustdoc as
244
+ without the plugin. Each task shows only its own crate's tests. With nextest,
245
+ the plugin selects the group's crates with a filterset, such as
246
+ `-E 'package(=api) | package(=core)'`, and nextest needs no runner. Your
247
+ nextest configuration applies as for a plain `cargo nextest run`: the profile
248
+ that `NEXTEST_PROFILE` chooses and its `default-filter`, so that a test that
249
+ the default filter leaves out is not run, and the task's output shows how many
250
+ tests nextest skipped.
251
+
252
+ What this costs:
253
+
254
+ - Every test run compiles and runs the doctests of every library in the
255
+ workspace, also of crates you did not ask to test. A slow doctest elsewhere
256
+ slows the run, one that hangs holds it up, and one with side effects, such as
257
+ writing files, has them in every run. A failing doctest of another crate
258
+ fails no task: each task warns and names the crate.
259
+ - A compile error in any crate's tests, examples or library stops the run, so
260
+ every `test` task of the group fails, also for a crate you did not ask to
261
+ test.
262
+ - A member that another member uses as a build-dependency is compiled a
263
+ second time, with the profile for build scripts, the first time a test run
264
+ follows a change or a plain `cargo test`, together with the member whose
265
+ build script uses it.
266
+ - The runner starts once for each test binary of the workspace, one after
267
+ another, which takes about 15 to 30 ms each.
268
+ - Where you configured a runner for your host, the plugin leaves it alone and
269
+ runs each crate's tests in a cargo command of its own, which does not batch.
270
+ It counts a runner as configured when `CARGO_TARGET_<TRIPLE>_RUNNER` is set
271
+ for the host, or when a Cargo configuration file sets `runner` under
272
+ `[target.<host triple>]` or any `[target.'cfg(…)']` table, also one that does
273
+ not match your host. Each such task says so in its output.
274
+ - On macOS the runner has not been tested yet: a test that loads a dynamic
275
+ library from the build folder may fail there, though never pass wrongly
276
+ ([[RISK-TEST-RUNNER-MACOS]]).
277
+
278
+ ### When the hack crate is enough
279
+
280
+ cargo-hakari unifies the features of third-party crates only. The plugin
281
+ therefore uses `hakari` only where it can show that this is enough, whether
282
+ `hakari` is the default or you set it. When Nx creates the graph, it checks
283
+ each workspace with a cargo-hakari configuration, `.config/hakari.toml`:
284
+
285
+ | Check | Fails when |
286
+ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
287
+ | Members | A member asks another member for a feature, in any form: a `features` list, `default-features = false` on a member that declares a `default` feature, even `default = []`, or `other/feature` and `other?/feature` in its `[features]`; or a member's dev-dependency on itself asks for features |
288
+ | Platforms | `platforms` in `.config/hakari.toml` does not list your host's triple. `cargo hakari init` leaves the list empty |
289
+ | Crates outside the workspace | A crate outside the workspace depends on a member through normal or build dependencies, a `[patch]`, `[replace]` or `paths` entry points at a member, or the plugin cannot see the dependencies of a path crate outside |
290
+ | Configuration | `.config/hakari.toml` has a non-empty `traversal-excludes`, `final-excludes` or `registries`, `workspace-hack-line-style = "version-only"`, or another setting that the plugin does not know to leave nothing to the selection |
291
+
292
+ If one fails, the whole workspace uses `workspace-build`, and the plugin says
293
+ why: a warning that names the check and the first crate or setting that
294
+ failed it, printed when the graph is created and at the start of every task of
295
+ the workspace. If that is how your workspace is meant to build, set
296
+ `featureUnification = "workspace-build"` in its `[workspace.metadata.nx]`: the
297
+ plugin then checks nothing and the warning goes away.
298
+
299
+ With `hakari`, the plugin also covers what the checks cannot see in advance:
300
+
301
+ - **A stale hack crate.** Every run that includes a cached task of the
302
+ workspace's crates first runs the workspace's `hakari-check` task, which runs
303
+ `cargo hakari generate --diff` and `cargo hakari manage-deps --dry-run`. If
304
+ the hack crate is stale, it fails with cargo-hakari's output and no task of
305
+ the workspace's crates runs. Run `cargo hakari generate` and
306
+ `cargo hakari manage-deps`, and commit the result. The check is not cached.
307
+ It reads the whole package graph, so on a machine whose Cargo home is empty
308
+ it downloads every package of the lockfile, also those for other platforms,
309
+ and offline it needs them there already, as `cargo fetch` leaves them.
310
+ - **Another triple.** Tasks that build for a triple that `platforms` does not
311
+ list run one crate per cargo command. Where the triple is set in the
312
+ repository, such as by `build.target` or a `targetTriple` in a crate's
313
+ table, the plugin also warns and names it; one you pass with
314
+ `--targetTriple` gets no warning.
315
+ - **Feature flags.** The all-features configuration, `noDefaultFeatures` and
316
+ `features` run one crate per cargo command, because cargo applies them to
317
+ the crates that a command selects. Only the default features batch.
318
+ - **Masked missing features.** A crate can stop declaring a feature it needs
319
+ because the hack crate enables it. An optional strict per-crate build check
320
+ catches this.
321
+
322
+ The hack crate is never published, and publishing a crate that depends on an
323
+ unpublished hack crate stops early with guidance
324
+ ([Releasing](release.mara.md#dependencies-that-are-not-published)).
325
+
326
+ Under `hakari` a crate's key holds the hack crate's manifest and
327
+ `.config/hakari.toml` in place of the other members' manifests. Under
328
+ `workspace-build` and `cargo`, which build with the features of the whole
329
+ workspace, it holds what any member can change: every member's manifest, the
330
+ locked packages of every member, and the path crates outside the workspace
331
+ that any member uses. A change to `Cargo.lock` that moves any member's
332
+ packages, or to such a crate, then runs every crate of the workspace again
333
+ ([Caching](caching.mara.md#lockfile-changes)). The key does not hold the
334
+ other members' sources: a compile error in another member fails the `test`
335
+ tasks that run in the same cargo command, but a crate's cached result, which
336
+ says that its own tests passed, is still restored. With
337
+ `NX_CACHE_FAILURES=true`, such a failure is stored under a key that does not
338
+ hold its cause ([What is stored](caching.mara.md#what-is-stored)).
339
+
340
+ ## Feature sets and target triples
341
+
342
+ - Feature sets are Nx configurations at workspace level: the default features
343
+ and all features.
344
+
345
+ ```sh
346
+ nx run-many -t test # default features
347
+ nx run-many -t test -c all-features
348
+ ```
349
+
350
+ - A crate that needs something else names it as `crate/feature`, or forms its
351
+ own group.
352
+ - Under `hakari`, every feature set but the default features runs one crate
353
+ per cargo command: these configurations do not batch. Under
354
+ `workspace-build`, the whole workspace builds with the flags, which then act
355
+ on every member, so they batch on the host.
356
+ - A platform triple for the same kind of artifact is a flag. A different kind
357
+ of artifact, such as wasm or a Node addon, gets its own target
358
+ ([napi and wasm artifacts](artifacts.mara.md)). Under `workspace-build`, a
359
+ non-host triple runs one crate per cargo command, because the whole
360
+ workspace may not build for it.
361
+ - v1 runs tests on the host triple only.
362
+
363
+ ## Requirements
364
+
365
+ :::mara requirement REQ-BATCHING
366
+ :mid: 01M78FHG7FRS15ZD38BR42JSK7
367
+ :title: Run a group of tasks with one cargo command per step
368
+ :status: accepted
369
+ :satisfies: NEED-EFFICIENT-BUILDS
370
+
371
+ Tasks of one [[TERM-GROUP]] that Nx runs in the same command are served together, without the user passing a flag: with one cargo command for each step of their target, so that the number of cargo commands depends on the target and not on how many tasks the group has. Each task still has its own result, its own terminal output and its own cache entry, and a task restored from the cache takes no part in the commands. A task fails when its own crate fails in any step, when a crate that it depends on does not compile, or where Cargo denies warnings and a step reports one, as this paragraph says below; a failing test of another crate does not fail it. `build`, `check` and `lint` keep going after a compile error, so there a compile error in a crate that the task's crate does not need does not fail it either, while a test step that a compile error stops, in whichever crate, fails every task of that step, because none of its tests ran. Where Cargo denies warnings, a step whose own diagnostics report a warning, a JSON compile step or a test step, fails every task of that step that passed, because cargo does not say which crates a warning fails. Tasks whose commands would differ in more than the crates they select are never served together. Serving tasks together never lets Nx store, under one task's key, files that another task's cargo command wrote.
372
+ :::
373
+
374
+ :::mara requirement REQ-STABLE-FEATURES
375
+ :mid: 01M78FHG7FNYQZJD8HRKA23YRY
376
+ :title: Make a crate's result independent of its batch
377
+ :status: accepted
378
+ :satisfies: NEED-CORRECT-CACHE
379
+ :satisfies: NEED-EFFICIENT-BUILDS
380
+
381
+ A crate's result does not depend on which other crates run in the same Nx command, so a cached result is valid whatever ran beside it. For the tasks of a group other than a group of one crate, however many tasks it holds, the features with which a crate and its dependencies are compiled are the same whatever the command selects: two runs that select different sets of crates from one workspace compile shared dependencies with the same features, so neither rebuilds what the other built. A task that runs its crate alone in its command for one of the reasons that [[DES-BATCH]] names under "Groups of one crate" is compiled with what its crate and its dependencies ask for, the same in every run, so its result depends only on what its own key holds. Between such tasks, a shared dependency can be compiled in more than one variant, which cargo keeps side by side, so that running them in another order compiles nothing that commands for one crate each would not.
382
+ :::
383
+
384
+ ## Design
385
+
386
+ :::mara design DES-BATCH
387
+ :mid: 01M78FHG7FY1VKFFHZ8G4WFDBJ
388
+ :title: Batch executor
389
+ :status: accepted
390
+ :satisfies: REQ-BATCHING
391
+ :mitigates: RISK-NX-INPUT-SEMANTICS
392
+
393
+ The plugin's cargo executor declares a `batchImplementation` and `preferBatch: true` in `executors.json`. Nx then hands the executor all runnable tasks of that executor at once, without `--batch`, and still hashes, restores and caches each task individually ([[ADR-BATCH-EXECUTOR]]).
394
+
395
+ **Two batch executors.** `build`, `napi-build`, `wasm-build` and `doc`, the targets whose files Nx stores ([[DES-OUTPUTS]]), run `@convesoft/nx-rust:cargo-outputs`, a second entry of `executors.json` with the same implementation and schema; the other batched targets run `@convesoft/nx-rust:cargo` ([[DES-TARGETS]]). Nx forms a batch from the runnable tasks of one executor and adds to it the tasks of the same executor that depend on them, stores the results and outputs of a batch only when the whole batch has ended, and awaits a batch, storing included, before it starts anything else ([[EVD-NX-24-BATCHES]]). With one executor, a crate's `build` and the `test` that waits for it ([[DES-TARGETS]]) would form one batch, the `test` group would run after the `build` group, and Nx would store the executable of `cargo test` under the key of `build`, as it did for 12 of 12 entries in [[EVD-CARGO-ARTIFACT-WRITERS]]. With two, such a `test` becomes runnable only once the batch of its `build` has run and been stored, and none of 12 entries was wrong. The batch implementation forms its groups inside each batch, below: the `cargo-outputs` batch holds the groups of `build` and `doc`, groups of one crate among them (**Groups of one crate**), and the other batch the groups of every other kind. Inside each batch the groups run one after another, in an order that the dependencies between their tasks allow, and Nx stores the batch only when all its groups have run, so splitting a group into groups of one crate changes how many cargo commands run, not when Nx stores, and no group of a `test`, of one crate or of several, runs inside the batch of the `build` it waits for. The groups of `build` and `doc` write different files, since `cargo doc` leaves the executables alone and only `doc` writes the `doc` folder. A `build` that ran or that Nx restored before a `test` batch runs is replaced on disk by the `cargo test` of that batch, which keeps the builds' files and puts them back once it has run, as the maintainer decided on 20 November 2026 ([[ADR-TEST-AFTER-BUILD]], nxr-5hzxra). The guard of [[DES-TARGETS]] reads the task graph of the command, which every batch receives whole. For users, the executor of `build` and `doc` is `@convesoft/nx-rust:cargo-outputs`: a `targetDefaults` entry keyed by `@convesoft/nx-rust:cargo` no longer reaches them, [[DES-TARGET-DEFAULT-GUARD]] judges each executor's entries for its own targets, and `init` adds an empty entry for each executor of the plugin's targets, this one included, where `targetDefaults` lacks one ([[DES-GENERATORS]]).
396
+
397
+ The batch implementation splits its tasks into groups ([[TERM-GROUP]]): tasks share a group only when their cargo commands would differ in nothing but the crates they select. A group has one kind of task, Cargo workspace, feature set, profile, target triple and set of command options, and one environment, as the next paragraph describes. It runs the groups one after another, because each cargo call already uses every core and the groups of one workspace share a build lock, those that select the whole workspace first among the tasks whose dependencies have run (**Files that a batch stores**).
398
+
399
+ **Groups of one crate.** A group never passes a flag whose effect on a crate depends on which other crates the same cargo command selects, never selects crates whose features cargo would then resolve for that selection alone, and never sets a runner where the user may have configured one. Where its command would do any of these, each of its tasks forms a group of its own, which selects that crate alone, by its package ID specification as every command selects its crates ([[DES-INVOCATION]], "Selecting a crate"), as milestone 0.1 does for every task and as a plain `cargo test` of that one crate with `--all-features` does; "one cargo command per step" holds for each such group. The control plane decided this on 14 November 2026 under [[GOAL-TRUSTED-CACHE]] and [[REQ-STABLE-FEATURES]], of which the maintainer is told, because it costs speed and never a result. It applies to the cases below and to no other task; a group that holds one task for another reason is no group of one crate:
400
+
401
+ - Under every strategy, to a task of `build`, `check`, `lint` or `test` whose own options give it a feature set: `features`, `allFeatures` or `noDefaultFeatures` in the crate's table, its `project.json` or a `targetDefaults` entry ([[DES-FEATURE-SETS]]). It forms a group of its own whatever else the batch holds, also where a configuration or the command line gives other tasks the same flags, so that its result does not depend on what else runs, and its command writes no other member's stored files (**Files that a batch stores**). The plugin cannot tell a `targetDefaults` entry from a crate's own options, which Nx merges, so a feature set given to every crate there runs one crate per command; given through a configuration, it shares a command. The control plane decided this on 16 November 2026 under [[GOAL-TRUSTED-CACHE]], after a review of nxr-8f9dz2 found that a crate whose table sets `allFeatures` shared the batch of another crate's whole-workspace build, which rewrote the other crate's executable with all features before Nx stored it.
402
+ - Under `hakari`, to a feature set given by flags: `--all-features`, `--no-default-features` and every `--features`. Cargo 1.91.0 and 1.100.0 apply `--all-features` and `--no-default-features` to the selected crates only, give an unqualified name in `--features` to each selected crate that has it, and accept `crate/feature` only where a selected crate is that crate or depends on it directly, so that a crate that another selected crate depends on is compiled with other features, or the command fails, depending on what else it selects ([[EVD-HAKARI-UNIFICATION]]). Only the default features share a command.
403
+ - Under `cargo`, to every `--features`, which cargo still checks against the selected crates; under workspace unification, `--all-features` and `--no-default-features` act on every member whatever the selection, and share a command ([[EVD-HAKARI-UNIFICATION]]).
404
+ - To a triple for which features are not resolved for the whole workspace: a non-host triple under `workspace-build`, whose groups cannot build the whole workspace ([[DES-FEATURE-SETS]]), and under `hakari` a triple, or a host, that `platforms` does not list ([[DES-UNIFICATION]]).
405
+ - Under every strategy, to a `test` task whose `test` option names a test target ([[DES-TEST-RUN]], "One test target"). Cargo fails `--test <name>` only where no package that the command selects has that target: `-p a -p c --test performance` ran `a`'s target and passed although `c` has none, which `-p c` alone fails, and `--workspace` behaves the same ([[EVD-CARGO-TEST-TARGET-SELECTOR]]). The batch implementation gives such a task no group to share, whatever the value of its option, so tasks with the same value do not share a command either, nor do tasks with different values. The control plane decided this in nxr-k5y74e on 22 November 2026 under [[GOAL-TRUSTED-CACHE]] and [[RISK-SUBSET-AS-FULL]].
406
+ - Under `workspace-build`, and `hakari` where it falls back to it, to the `test` tasks of a group on the host where a runner for the host is or may be configured: the selecting runner that such a group needs would replace that runner, or be combined with it or lose to it, depending on the cargo version ([[DES-TEST-RUN]], "A runner the user configured"). The control plane decided this on 14 November 2026, of which the maintainer is told.
407
+
408
+ Under `workspace-build` on the host, a group builds the whole workspace, so its flags act on every member, and it shares one command whatever its feature set. It does so however many tasks it holds: a group left with one task, because the command names one crate or Nx restored the others from the cache, still builds the whole workspace, with the selecting runner for `test` ([[DES-TEST-RUN]]), so that its crate compiles with the features of the whole workspace in every run, as its key promises. A command that selects one crate resolves features for that crate and what it depends on, so its result depends only on the crate's own dependencies, which every key of [[DES-INPUTS]] covers: the keys of the whole-workspace strategies are a superset of them, and under `hakari` a crate's key holds them with the hack crate's manifest. A crate that another task's crate depends on can then be compiled twice, once with its own task's flags and once as the dependency, and cargo keeps both builds side by side, so running the tasks in another order compiles nothing that per-crate commands would not ([[EVD-HAKARI-UNIFICATION]]). Such groups do not batch: they cost a cargo command, and its wait for the build lock, per crate and step.
409
+
410
+ **Files that a batch stores.** No cargo command of the plugin writes a final artifact of a crate whose `build` is not one of its own tasks: Nx stores a batch's outputs only once the batch has ended, as the files are then, whoever wrote them ([[EVD-NX-24-BATCHES]], "Storing"), and a task outside the batch reads them as they are when it starts ([[EVD-BATCH-FILES-ON-DISK]]). Of the `cargo-outputs` batch, only `build` groups and the compiles of `napi-build` and `wasm-build` write final artifacts. A `build` group that selects its crates with `-p`, a group of one crate or a group under `hakari` or `cargo`, writes only the files of the crates it selects, also where its feature set changes that of the crates they depend on, and no file of a dependency ([[EVD-CARGO-ARTIFACT-WRITERS]], "Feature sets of one crate"); those are its own tasks' files. A `build` group that selects the whole workspace, which would link every member's files again, also those of fresh units, and every compile of `napi-build` and `wasm-build`, whatever it selects, build in a stage of their own and move into the artifact directory only their own tasks' files, `napi-build` and `wasm-build` none (**Staged builds**). The addon and its JS files, and the wasm package, in the crate's folder are written only by the post-processing of their own task, from the library in the stage ([[DES-NAPI]], [[DES-WASM]]). No group therefore writes another task's files, whatever the order of the groups and whatever ran or was restored before the batch, and every group runs in the batch that receives it; the batch still runs the whole-workspace groups first, which nothing depends on any more. The exception is the one that [[DES-OUTPUTS]] names ("Files of one name"): crates whose final files share a name, which cargo writes to one path in any directory, a stage included. Their builds are not cached, and a task that reads such a file can get the other crate's. The one case that no stage helps is two `build` tasks of one crate in one command whose files lie in one folder, the same artifact directory, triple folder and profile folder as the outputs of `build` name them ([[DES-OUTPUTS]]): judged by the outputs that Nx resolved for each task in the command's task graph, an output of one being an output of the other or lying inside it, so that the plugin reads no option of a peer, such as a crate's `build` beside its `build` in another configuration that a dependency names, or a copy of the target under another name: each would store what the other's command wrote. The maintainer decided on 20 November 2026 that "two configurations of one crate into one folder fail with guidance instead of sharing a command" ([[ADR-STAGED-BUILDS]]): every such task fails before cargo runs, in a batch and run on its own, with a message that names the tasks and the folder as the outputs name it and says to run them in separate commands ([[DES-DIAGNOSTICS]]). Where Nx restores every such task from its cache, no executor runs and none fails: Nx writes the files that each entry holds and removes none, so the folder holds, at each path, the file of the entry restored last that holds it, beside any file that only another configuration builds, such as a binary with `required-features`, and an entry can itself hold such a file that an earlier build left at a path it declares ([[DES-OUTPUTS]]). The maintainer confirmed on 21 November 2026 that this limit stands for v1 and asked that the guide say so ("Agree, just document this"). Where Nx restores one and runs the other, the one that runs fails, since the restored task is still in the command's task graph. A `build` whose outputs name no folder, such as an uncached one, is not judged: Nx stores nothing for it. Two tasks whose outputs name one folder are refused also where their own dotenv files give cargo different artifact directories, as two uncached builds with different `CARGO_TARGET_DIR` values can: the refusal judges by the folder that the outputs name. `doc` is not concerned: it is a task of the workspace project, one per Cargo workspace, and writes only its workspace's `doc` folder, which no `build` writes, while Nx caches no `doc` whose artifact directory another workspace shares ([[DES-OUTPUTS]]). `check`, `lint` and `test` run in the other batch, whose tasks store no files, and a `test` waits for every `build` whose executables its commands replace ([[ADR-WORKSPACE-TEST-EXECUTABLES]]).
411
+
412
+ **Every task in the batch that receives it.** Since no group writes another's files, the batch leaves no task for a following batch process: it reports every task that it receives, each as soon as its group has run, and Nx stores them when the batch ends, as one batch process. The leaving of a group for a following batch that the control plane chose on 16 November 2026 (line 15 of nxr-5rrkay) ends with the maintainer's decision of 20 November 2026 ([[ADR-STAGED-BUILDS]]), and with it the key that a task left out kept from the first wave, computed before its dependencies ran, which gave a wrong cache hit where an input reads their outputs, such as `dependentTasksOutputFiles` (nxr-f04xen, [[EVD-STAGED-BUILDS]]). Within one batch process, Nx hashes such a task again once the process has reported it ([[EVD-NX-24-BATCHES]], "Tasks left out"). Nx 24 tells a batch implementation nothing of `--nx-bail`: neither its arguments nor its context hold it ([[EVD-STAGED-BUILDS]]). So where a group fails, the later groups of the same batch process still run and are stored, as the groups of a batch always did; Nx's bail ends the command after the batch. The control plane decided this on 20 November 2026, and the maintainer confirmed it on 21 November 2026, agreeing ("Agree with recommendation") that it stands as a documented limitation of Nx until Nx passes the flag to a batch; were Nx to tell a batch implementation of the bail through its arguments or context, the batch would start no further group after a failure. As it ends, the batch checks that it reported every task; a task that it did not report, which only a fault of the plugin can cause, fails with a message that says so, instead of having Nx start it again in a new batch process, perhaps without end ([[DES-DIAGNOSTICS]]). What Nx 24 does with tasks that a batch leaves unreported stays recorded in [[EVD-NX-24-BATCHES]] ("Tasks left out").
413
+
414
+ What this guarantees for builds is that each `build` stores its own files, and that from the moment it has ended its files in the artifact directory stay as it left them, until a command of a `build` of the same crate writes them again: no other build or command of the plugin writes them, so that a task outside the batch that depends on it, also one that is already running and a continuous one, reads them, with one exception. A `test` or `bench` batch replaces the executables of the crates that its tests build while it runs, so that a task that reads them during that batch can get those of `cargo test`, and puts back what the command's cached builds stored when it ends (below); cargo commands that Nx does not order remain ([[RISK-ARTIFACT-DIR-WRITERS]]).
415
+
416
+ **Files that a test batch puts back.** `cargo test` and `cargo bench` link again the executables that a `build` of the same crate stores, with what dev-dependencies turn on or with another profile, also where nothing compiles, and cannot build into a stage ([[EVD-CARGO-ARTIFACT-WRITERS]], [[EVD-STAGED-BUILDS]]). Nx restores a task's files only before it runs the task, never again within the command once it has ended, and a batch's result carries no outputs ([[EVD-BATCH-FILES-ON-DISK]]). So a task outside the plugin that depends on such a `build` and starts after the `test` batch, as one that also depends on the `test` does, would read the test build and, where it is cached, store what it made of it under a key that holds the build's hash. The maintainer decided on 20 November 2026 that a `test` or `bench` batch puts the builds' files back ([[ADR-TEST-AFTER-BUILD]]). Each group of `test` and `bench` in a batch therefore leaves the final files of the command's cached builds that its cargo commands can link again as it found them. The candidates are the final files of the crates that the group builds for its tests: of every member where it selects the whole workspace and of its own crates where it selects them, for `test` those with a binary and an integration test or bench, whose executables `cargo test` replaces, an integration test with `test = false` included, which the `test` option makes cargo build and run ([[DES-TARGETS]]), and for `bench` those with a binary. For each, they are the files that the outputs of a crate's `build` name, its executables and its `cdylib` and `staticlib` files ([[DES-OUTPUTS]]), in the folder of each triple that the group's command builds for, `host-tuple`, in the option or in Cargo's configuration, standing for the host's triple whose folder cargo writes, and of its profile, below the physical path of the artifact directory that cargo reports for the group. That report costs the group one `cargo metadata --no-deps` call wherever the command has a cached `build` that the group may keep files of, with an output inside the repository, and a crate of the group's can link files again, also where that build's outputs then name none of the candidates. A candidate is kept where a cached `build` task of the command's task graph stores it, judged from the outputs and the `cache` flag that Nx resolved for each task, so that the plugin reads no option of a peer: a `build` task of the plugin that is not one of the group's tasks, has `cache` on, and, for a group that selects its crates, belongs to one of their projects, one of whose outputs names the file or a folder above it, or is a glob that Nx's own glob matching accepts for that one path, with the output also followed by `/**`, so that a folder that a glob matches stands for its files, as Nx stores it; `!` exclusions go to the same matching. An absolute output inside the repository is compared relative to it, and one outside it is left out, since Nx cannot store it. No folder is listed and no file is searched for. Any other triple whose folder the plugin cannot name, such as a target specification file, gives no candidate, as no cached build names its folder. Only an existing regular file is kept: a missing file or a symbolic link is not, and a file that cannot be looked at for another reason fails every task of the group. Where an output needs Nx's glob matching and it cannot be loaded, or cargo reports no directories, every task of the group fails before cargo runs. Before its first step the group makes a stage of the artifact directory, as a staged build does (**Staged builds**), only where it keeps a file, and gives each kept file a hard link in it at the same path relative to the artifact directory, or a copy where the file system refuses a link. After its last step, it puts each file that the commands replaced or removed back with the stage's move, by rename, or by a copy beside it that is renamed onto it where the two lie on different file systems, and removes the stage, also where cargo or a check failed. Nx starts no other discrete task while a batch runs ([[EVD-NX-24-BATCHES]]), so such a file is one that a `build` of the command left, run or restored, or one that a `build` yet to run will write; putting it back is right for the first and changes nothing for the second. Cargo links the uplifted files again in every command, also of fresh units, and does not read them to decide what is fresh, so plain cargo afterwards compiles nothing more than it would have, and `cargo test` links its executables into place again ([[REQ-CARGO-UNCHANGED]]). Cargo and the linker replace such a file rather than write into it, so the stage's link keeps it as it was; where a file cannot be kept or put back, or the kept file was written in place or had its permissions changed while the commands ran, every task of the group fails with a message that names the file and the build ([[DES-DIAGNOSTICS]]), and a task that depends on them does not run. The cost is a hard link and at most a rename per file and group, and the report of the directories; no cargo command and no selection changes. Where the batch process is killed while a group runs, the files hold the test build until the next `build`, run or restored, puts its own back, as after plain `cargo test`, and the stage stays until the next staged command or test group that keeps files removes it, as it removes every stage whose process has ended. The outputs that the plugin infers never name a stage; an output that a user widens to the whole artifact directory also stores such a left stage until then (**Staged builds**). What this gives up: under an output that a user widens to a folder or a glob, only the build's final files are put back, and no Cargo intermediate or dependency record; a glob with an exclusion can keep a final file that Nx would not store, which costs only its link; a folder between the artifact directory and a candidate is not looked at either: where it is a symbolic link, the file behind it is kept although Nx stores nothing below a link, which is as harmless; and an output spelled through a symbolic link above the file does not name the physical path below the artifact directory, so that such a file is not kept. Not kept either: the files of a `build` whose outputs are empty or whose `cache` is off, since Nx stores nothing for it and no cached task can restore beside its entry (decided on 21 November 2026 for nxr-5hzxra; nxr-j55xdy closed the case of empty outputs for builds); those of a `build` that the command does not hold, such as where it names `test` with `--exclude-task-dependencies` alone, which the commands replace as plain cargo does; and those of a `test` run on its own, as with `--batch=false`, which leaves the executables of `cargo test` as plain `cargo build && cargo test` leaves them. A task that reads such a file while the tests run, such as a continuous one, can still get the executable of `cargo test`; the maintainer accepted both limits with the decision ([[RISK-ARTIFACT-DIR-WRITERS]]). The orchestrator of nxr-5hzxra chose on 21 November 2026, after the review and a second opinion, to start from the files that the commands can link again rather than expand each build's outputs into files, which would re-implement how Nx expands outputs, and to hold the kept files in a stage rather than beside them, where a later build with a folder or glob output could store a leftover.
417
+
418
+ **Staged builds.** A `build` group that selects the whole workspace, and the compile of every `napi-build` and `wasm-build` group, run cargo with an artifact directory of their own, a _stage_, and the build directory that cargo would use anyway, so that cargo builds and reuses exactly what it would, and links its final artifacts into the stage alone ([[ADR-STAGED-BUILDS]], [[EVD-STAGED-BUILDS]]). The same holds for such a task run on its own. The command gets `--target-dir <stage>` and `--config 'build.build-dir="<build directory>"'`, the build directory as a TOML string; the plugin takes both directories from the report of Cargo's directories that the group asks for with `cargo metadata --no-deps` in the workspace root and its environment ([[DES-OUTPUTS]]), `build_directory`, which follows `build.build-dir` and `CARGO_BUILD_BUILD_DIR` and is the artifact directory where nothing sets it, and `target_directory`. The stage is a new folder `.nx-rust-stage/<process id>-<counter>` in the artifact directory: on the file system of the files it replaces, among Cargo's directories, which the build input check skips, where cargo 1.91.0 spells files that build scripts generate in the dependency records ([[EVD-CARGO-DEP-INFO]]), and removed by `cargo clean`. Build scripts keep their `OUT_DIR` in the build directory, and the plugin sets no `CARGO_TARGET_DIR` for them, and cargo's lock on the build directory makes two commands take turns as before. After cargo, a `build` group moves, for each crate of its own tasks, the files that cargo's `compiler-artifact` messages name in the stage for the crate's `bin`, `cdylib` and `staticlib` targets, the split-debuginfo files among them, such as `.dwp`, and never an `rlib`, `dylib` or `rmeta` ([[ADR-RESULTS-ONLY-CACHE]]), to the same path relative to the artifact directory, by rename, which replaces the file in one step, or where that fails across file systems by a copy beside it that is renamed onto it; and the dependency record that cargo wrote beside a file of any target of those crates, also of a library that is only an `rlib` and of a proc macro, whose own files stay in the stage, since [[DES-BUILD-INPUT-CHECK]] reads them. A crate that cargo reports no file for, because it failed, gets none moved, and a file that cannot be moved fails its crate's task. Nothing outside the stage is taken and nothing outside the artifact directory is written. Both bounds are judged by path below the artifact directory's real path: a folder below it that is a symbolic link, such as a profile folder that a user keeps on another volume, is followed, as cargo follows it. Then the checks after cargo run as for any `build` ([[DES-BUILD-INPUT-CHECK]]). A `napi-build` or `wasm-build` compile moves nothing: its post-processing reads the library from the stage, and its checks after cargo read the records there. The stage is removed once the group is done, also where cargo or a check failed. Each stage holds a marker with its process's id and the time the process started as the system tells it: on Linux the start in clock ticks from `/proc/<pid>/stat`, elsewhere what `ps -o lstart=` prints. Before it makes its own, a staged command removes every stage in that artifact directory whose process no longer runs, as one that an interrupted command left, and every stage whose process id now belongs to a process that started at another time, which got the dead owner's id. A stage whose process runs, of another `nx` command, is left alone, also one not marked yet, in the moment between its folder and its marker, and one whose process start cannot be told; such a stage costs only disk until its process ends. Where a process finds a folder of its own id that it did not make, that folder is an earlier process's, and it is removed. Where the stage cannot be made or the report of the directories fails, every task of the group fails; where a file cannot be moved, the task of its crate fails; each with a message that says which ([[DES-DIAGNOSTICS]]). A `test` or `bench` group makes a stage of the same kind for a second use, to hold the files that it keeps, and builds nothing in it (**Files that a test batch puts back**); a stage that it leaves where its process is killed is removed in the same way. `cargo test`, `cargo bench`, `check`, `lint` and `doc` are never staged: `cargo test` would fix the stage's path into `CARGO_BIN_EXE_<name>` without counting it in the fingerprint, so that plain `cargo test` afterwards runs a missing executable ([[EVD-STAGED-BUILDS]]), and the others link no final artifact. A staged command costs no compile and no measurable time; the stage holds hard links of the build directory's files and the dependency records. Nothing that the plugin's own outputs and inputs name reaches the stage. The outputs of `build` name the files of the profile and triple folders and those of `doc` the `doc` folders, none of which holds `.nx-rust-stage` ([[DES-OUTPUTS]]), and every fileset that the plugin reads with `includeIgnored` leaves Cargo's directories out ([[DES-INPUTS]], "Cargo's directories"), while a crate's other file inputs leave out what git ignores. An output that a user widens to a glob over the artifact directory stores what lies there when the task ends, Cargo's intermediates included, as it would without stages; the group's own stage is gone by then, but another `nx` command's running stage can be among it, and so can a stage that an interrupted command left, of a build or of a test group's kept files, where the output takes in the whole artifact directory, such as `rust/target` or `rust/target/**`: it stays until the next staged command or test group that keeps files removes it, and a `build` that selects its crates is not staged and removes none. A later restore brings such a stage back as one whose process has ended, which the next staged command removes. The outputs that the plugin infers name no stage. Where a Cargo directory lies in a project's folder and git does not ignore it, Nx reads all of it, a stage that an interrupted command left included, until the next staged command removes it; [[DES-DIAGNOSTICS]] already warns of such a directory when the graph is created. Plain cargo, `cargo metadata` and `cargo clean -p` leave the folder alone, and `cargo clean` removes it with the artifact directory ([[EVD-STAGED-BUILDS]]). What it gives up: a `build` of the whole workspace no longer refreshes the final artifacts of members whose `build` the command does not run, which keep what was there, as after `cargo build -p` of the others; the dependency records that it moves name the stage as their rule's target; and a `napi-build` or `wasm-build` compile leaves the artifact directory as it was.
419
+
420
+ Nx computes each task's key with that task's environment, which includes the dotenv files it loads for the task: those in the crate's folder and those at the repository root named for the target or a configuration, such as `.env.test`. The batch process gets only the environment of the `nx` command and the root `.env`, `.env.local` and `.local.env` ([[EVD-NX-24-INPUT-SEMANTICS]]). A task's cargo gets, in a batch, exactly the environment that it gets when the task runs on its own. The batch implementation therefore rebuilds each task's whole environment as Nx builds it for the task run on its own, with the functions of Nx that do so, layer by layer as [[EVD-NX-24-BATCHES]] ("Task environment") records: the dotenv layer, Nx's per-task variables such as `NX_TASK_TARGET_PROJECT`, and the variables that Nx removes from every task. It splits a group further where those environments differ, and runs each cargo command with the environment of its tasks. No task runs with another environment than the one its key was computed with. Cargo gets the command's environment and the task's dotenv files, plus exactly the per-task variables that are the same in every way of running the task, alone or in a batch, in any output style, in a terminal or not, with the daemon or without; every other variable that Nx sets for a way of running is left out. Of those per-task variables, cargo never gets `NX_TASK_TARGET_PROJECT` and `LERNA_PACKAGE_NAME`, which name the task's project and alone differ between the tasks of one target and configuration, so that such tasks share an environment and a command ([[ADR-TASK-NAME-VARIABLES]]). Those are the variables by which Nx tells a task how it runs and records it, not what the task is ([[EVD-NX-24-BATCHES]], "Task environment"): its key `NX_TASK_HASH`, which Nx does not hand a batch; where Nx writes the task's terminal output and whether it captures standard error, streams or prefixes it, which follow the output style and the key; `FORCE_COLOR`, which Nx removes from a task whose output it writes to a file and sets for one whose output it pipes; `NX_PSEUDO_TERMINAL_EXEC_ARGV`, `NX_PSEUDO_IPC_PATH` and `NX_PSEUDO_IPC_FORK_ID`, which Nx's pseudo-terminal gives a task that runs on its own in a terminal, the first of them reaching the task empty; `NX_TUI_AUTO_EXIT`, `NX_VERBOSE_LOGGING` and `NX_ANALYTICS_SESSION_ID`, which the `nx` process sets from `--tui-auto-exit`, from `--verbose` and for its analytics; and `NX_SET_CLI`, `NX_ORIGINAL_FORCE_COLOR`, `NX_READY_SIGNAL_SOCKET` and `NX_READY_SIGNAL_TASK`, which Nx removes from every task and its pseudo-terminal gives back. The plugin leaves them out of every environment that it runs cargo with and asks cargo for reports with, for a task run on its own as in a batch, so that no cargo command, build script or test sees them and no result can depend on them. Nx's pseudo-terminal lays the environment that Nx built for a task over the `nx` process's own, so that a variable which Nx's per-task layer leaves without a value comes back with the `nx` process's value for a task in a terminal ([[EVD-NX-24-BATCHES]], "Task environment"); the plugin therefore gives cargo those variables as that layer gives them, in every way of running: `NX_SKIP_NX_CACHE` is `true` where the run skips the cache and absent otherwise, `NX_TASK_TARGET_CONFIGURATION` names the task's configuration or is absent, and `NX_READY_URL` reaches cargo only for a task that waits for a continuous task that reports ready by signal, the one case in which Nx gives it the variable. What Nx sets for a task run on its own after the per-task layer, `NX_FORKED_TASK_EXECUTOR` when it forks and `NX_CLI_SET` when the task's process starts, a batch process has from its start, before the batch lays the task's dotenv files over it; the batch sets both again after the task's own variables, in that order, so that a dotenv file that defines one changes the value in neither path. What then differs between two runs of a task is what differs between any two `nx` commands, `NX_INVOCATION_ANCESTOR_PIDS` and the plugin's `NX_RUST_COMMAND_ID` and `NX_RUST_NX_COMMAND`, and what the commands' own environments set differently. Nx gives a task run on its own `NX_READY_URL` only where an edge with `waitFor: "ready"` leads to a continuous task whose `readyWhen` reports ready by `signal`, the only check that reports a URL, and tells a batch nothing of it ([[EVD-NX-24-BATCHES]], "Continuous tasks"). The maintainer decided on 15 November 2026, asked what should happen with batching on by default, "Refuse only where it matters (Recommended)": a task of a batch with such an edge fails before cargo runs, with a message that names the continuous task and offers `--batch=false` for one command and `NX_BATCH_MODE=false` in the root `.env` for the repository, saying that the latter turns batching off for every task, of every plugin ([[DES-DIAGNOSTICS]]); every other continuous dependency, with another check or none, gives the task run on its own nothing that a batch lacks, and runs in the batch. So no result is stored under an environment that differs from the one of a run on its own. Not chosen: reading the URL from Nx's database of running tasks in the batch, keeping `NX_READY_URL` out of cargo's environment altogether, and an opt-out per target. A task whose preparation fails, also through an unexpected error of the plugin's own, fails alone, and the other tasks of the batch go on.
421
+
422
+ **Dotenv files.** Nx expands the dotenv files of a task run on its own in the `nx` process, before it adds the task's own variables, and the batch expands them in its own process, which Nx gives variables of its own. The variables that Nx sets, changes or removes on the way from the `nx` command to the process of a task or of a batch, or sets in its own process from the output style, the terminal UI or an option, can therefore have other values where the files are expanded, depending on how the task runs ([[EVD-NX-24-BATCHES]], "Task environment", names them). Every other variable has the same value in the `nx` process, the batch process and the task's process, so expanding a task's files gives the same values in every way of running unless the expansion could look one of those variables up. Before any cargo command, alone as in a batch, the plugin reads the dotenv files that Nx loads for the task, and nothing for a task without any, and runs a static check over their `$VAR`, `${VAR...}` and `$$VAR` references without re-implementing `dotenv-expand`'s loop or pinning its version at run time ([[EVD-DOTENV-STATIC-CHECK]]). The check follows what the installed `dotenv-expand` (`lib/main.js`, `expandValue`) actually matches (`/(?<!\\)\${([^{}]+)}|(?<!\\)\$([A-Za-z_][A-Za-z0-9_]*)/g`), splits (`/(:\+|\+|:-|-)/` and `expression.split(splitter)`, including `split(null)` on the literal text `"null"` when no operator matches), escapes (any `$` immediately preceded by `\`, including `\\$`), and replaces (`String.prototype.replace`), guarded by a source-text tripwire test on `dotenv-expand`'s `lib/main.js` in the same way a test guards Nx's wrapper. From every variable that the files define and that is not run-dependent, the check walks all references statically through the raw definitions and the ambient values in `env` of every variable reached, following both branches of every `:-`, `-`, `:+` and `+` (for `:+` and `+`, testing whether the condition variable itself is run-dependent without substituting its value, and walking the alternative body), with a visited set keyed by `(variable, followedByIdent, followedByRefStart, afterEscapedDollar)` so cycles terminate without rejecting self-references such as `RUSTFLAGS=${RUSTFLAGS} --cfg tokio_unstable` or `PATH=${PATH}:./bin`. Literal braced names with no `$`, `{` or `}` after splitting (`${APP.VERSION}`, `${1}`, `${SET:?error}`) are followed as single static lookups (without splitting unknown POSIX operators such as `:?`, which `dotenv-expand` keeps in the key), and top-level `${}` and unclosed `${` with no following matched reference pass as plain text. For `$$NAME`, where `dotenv-expand` leaves the first `$` in place and re-scans `$<value of NAME>`, the check inspects every candidate value of `NAME` (in the files, in `env`, or empty) and follows any single identifier that results (while still checking `NAME` itself). A task fails before cargo runs where:
423
+
424
+ - any reached reference names a run-dependent variable, whether directly, through a referenced variable's raw or ambient value, through `$$NAME` indirection (`SELECTED=FORCE_COLOR` with `VALUE=$$SELECTED`), inside a `:-`, `-`, `:+` or `+` branch (even when that branch would not be taken), or through `dotenv-expand`'s `split(null)` splitting an operator-less braced body on literal `"null"` (`${NX_FORKED_TASK_EXECUTORnull}`, `${Anull$FORCE_COLOR}`); the message names the file, the variable being expanded, the run-dependent variable and why its value differs; or
425
+ - any reached value holds a form from which a variable name could be assembled dynamically or `String.prototype.replace` could substitute into an unintended site: `${...}` with a key containing `$`, `{` or `}` (such as `${X${Y}}` or `${FORCE_${PART}}`), a top-level unclosed `${` followed by a matched reference that could supply `}` (such as `${FORCE_${PART}` with `PART=COLOR}`), an empty `${}` or unclosed `${` inside a referenced value or default/alternative body, `$${...}` or `$$$NAME`, `$$NAME` whose value holds `$`, starts with `{`, or can be empty where `[A-Za-z_{$]` follows, a `String.prototype.replace` pattern (`$&`, `$'`, `` $` ``, including after `\` since `replace` ignores backslashes) inside a referenced value or inside a `:-`, `-`, `:+` or `+` body, a trailing `$` or `$$` inside a referenced value or default/alternative body where the substitution site can precede `[A-Za-z_{$]` (such as `DOLLAR=$` with `${DOLLAR}NX_VERBOSE_LOGGING` or `PASSWORD=pa$$word` with `USE=${PASSWORD}COLOR`, while `PASSWORD=pa$$word` with `VALUE=${PASSWORD}` and `$!` / `$$!` secrets pass), or an unbraced `$NAME` or `$$NAME` at the end of a referenced value or default/alternative body where the substitution site can precede `[A-Za-z0-9_]` or where an earlier escaped `\$` appeared in an enclosing value so `String.prototype.replace` could substitute into that earlier escaped copy (such as `VALUE=${A:-$FORCE_}COLOR`, `PASSWORD=pa$$FORCE_` with `USE=${PASSWORD}COLOR`, `NAME=x$NX_FORKED_TASK_` with `VALUE=\$NAMEEXECUTOR $NAME`, or `\${A}COLOR ${B}` with `B="p${A} "` and `A="x$FORCE_"`). Diagnostics name the file, the variable being expanded, the kind of form in words (and, where helpful, a static identifier written directly in the task's dotenv files, never extracted from a file or environment value), and never print any character from a file or environment value ([[DES-DIAGNOSTICS]]).
426
+
427
+ On 20 November 2026 the maintainer chose `"Static, cycles allowed (Recommended)"` over the same static check with cycles refused (which would reject self-append idioms such as `RUSTFLAGS=${RUSTFLAGS} ...` and `PATH=${PATH}:./bin`) and over keeping the earlier step-by-step follower of `dotenv-expand` 12.0.3 (which pinned an exact patch version of Nx's dependency, [[RISK-UPSTREAM-CHANGES]]). Compared with that follower, the static check newly refuses dynamically assembled variable names (`${X${Y}}`, `$${Z}`), never-taken default or alternative branches naming a run-dependent variable (`${UNSET_TOO:+$NX_TUI}`), and stray `$` or joinable trailing unbraced references inside referenced values and defaults; it no longer refuses non-terminating cycles that reach no run-dependent variable (which already exhaust or hang plain Nx before the plugin runs, [[EVD-DOTENV-STATIC-CHECK]]) or long literal values under an artificial length bound.
428
+
429
+ A file that only defines a run-dependent variable changes nothing that cargo sees, since each of them is left out of cargo's environment, set or removed by Nx after the dotenv files for every task, set again by the batch after the task's own variables as Nx sets it after them for a task run on its own, or given to cargo as Nx's per-task layer gives it, and passes; so do Nx's own settings in the root `.env`, such as `NX_DAEMON`, `NX_VERBOSE_LOGGING`, `NX_PARALLEL` or `NX_SKIP_NX_CACHE`, which the `nx` process loads when it starts. The batch builds a task's dotenv layer as Nx's `getTaskSpecificEnv` builds it, with the functions of Nx that `getTaskSpecificEnv` calls and that take the environment they change as an argument, `unloadDotEnvFile`, `getEnvFilesForTask` and `loadAndExpandDotEnvFile`, on a copy of the batch process's environment, where `getTaskSpecificEnv` reads only the environment of the process that it runs in; the plugin writes nothing to the batch process's own environment. Which files Nx reads, in which order, and how their expansion sees earlier values stays Nx's own code. The plugin repeats three facts of Nx's wrapper: the three root files that it unloads, the order of the calls, and that it loads the task's files only where `NX_LOAD_DOT_ENV_FILES` is `true`. A test compares the layer with `getTaskSpecificEnv` itself, and another fails, saying what to bring in line, wherever the source of `getTaskSpecificEnv` or of the two functions of Nx that hold those facts differs in the installed Nx. One write remains that is not the plugin's: with `DOTENV_KEY` set and a vault beside a task's files, dotenv 16.4.7 parses the vault into the live environment before it decrypts it, so that Nx's loader sets the vault's `DOTENV_VAULT_<ENVIRONMENT>` on the environment of the process that it runs in, the `nx` process for a task run on its own as a batch process. The check refuses that task, but the variable reaches the cargo of the tasks whose environment Nx or the batch builds later in the run; which tasks those are depends on the order, so it can differ between a batch and the tasks run on their own (nxr-gcknzm). Known limit of batch ordering: in a batch, `taskDotenvLayer` runs before `dotenvProblem`, so a file whose expansion runs away only when a run-dependent variable is set (such as `B=x$B` with `VALUE=${NX_FORKED_TASK_EXECUTOR:+$B z}`) exhausts the batch process (V8 OOM) before the check can refuse it (nxr-vwpjg2). Not chosen for building the layer: writing to the batch process's environment around a call of `getTaskSpecificEnv`, which any other work in the process could see; computing the environments in a short-lived child process, where `getTaskSpecificEnv` itself could run on an environment of its own, which costs a process that loads Nx for each batch and the means to pass tasks and environments both ways, for what the test of the three facts guards; and Nx's `getGraphTimeDotEnvForTask`, which takes the environment as an argument but loads the files unless `NX_LOAD_DOT_ENV_FILES` is `false`, where `getTaskSpecificEnv` loads them only where it is `true`, and needs the target whose files Nx reads, which Nx finds in a function that it does not export. In that copy, the batch gives each of those variables that the task's files define a value of its own, so that dotenv-expand takes that value as it is, as it takes the `nx` process's own value for a task run on its own, such as `NX_ORIGINAL_FORCE_COLOR=0` under `FORCE_COLOR=0`, instead of expanding the file's value: the batch process lacks some of them, and where the file's value does not end, as `NX_ORIGINAL_FORCE_COLOR=${CMD}z` with `CMD=x${CMD}` in the command, it would run out of memory while the task alone passes ([[EVD-NX-24-BATCHES]], "Dotenv expansion").
430
+
431
+ Whether Nx loads the files at all, the `nx` process's `NX_LOAD_DOT_ENV_FILES` decides when Nx builds the task's dotenv layer, and the batch process has the same value; Nx sets it to `true` unless the command's environment or the root `.env` sets it to `false`. A dotenv file of the task can define the variable too, and the task's environment then ends with the file's value, which tells nothing of what decided: a task whose dotenv files define `NX_LOAD_DOT_ENV_FILES`, whatever the value, fails, and the message says to remove the definition from the files that it names and, to switch the loading of dotenv files off, to set `NX_LOAD_DOT_ENV_FILES=false` in the environment of the `nx` command, in the shell or the CI settings. Otherwise the task's environment has the value that decided. Where Nx loads no files, it still removes from the task each variable whose value the root `.env`, `.local.env` or `.env.local` gives, and loads nothing back, while its pseudo-terminal gives a task in a terminal the `nx` process's values back; the plugin then removes them again with Nx's own function, from every variable apart from those that Nx sets after the dotenv layer, alone as in a batch.
432
+
433
+ Unknown means fail: where dotenv would read the task's variables from a vault, where a value holds an ambiguous or dynamic `$` form that the static check cannot resolve to fixed variable names, and where the installed Nx lacks a part that the check reads, the task fails before cargo runs ([[DES-DIAGNOSTICS]]). The vault comes before every other part of the check, before the files that define `NX_LOAD_DOT_ENV_FILES`, before the return for a task without dotenv files and before the one for a run in which Nx loads none: with `DOTENV_KEY` set, in the command's environment or by a dotenv file, dotenv reads `.env.vault`, `.local.env.vault` or `.env.local.vault` at the root where Nx removes the root files' values from the task, also where the plain file is missing and whether or not Nx loads the task's files, and reads the vault beside the last of the task's files that exists where it loads them ([[EVD-NX-24-BATCHES]], "Dotenv expansion"); a task fails where any of these exists.
434
+
435
+ **Cargo's output while a batch runs.** A task's result, with its terminal output, can be reported only once its group's commands have ended, and a group can be the whole run. The maintainer decided on 15 November 2026, asked what users should see of cargo's output while a batch runs, "Live in the terminal UI, status line elsewhere (Recommended)": where Nx runs its terminal UI, which it tells the batch process with `NX_TUI=true`, the batch process writes cargo's lines to its own standard error as they arrive, beside the file that feeds each task's result, the rendered diagnostic of a JSON message in place of the message, so that the terminal UI shows them in the batch's pane; in every other output style, which the batch process cannot tell apart, it writes one line each time a cargo command starts, naming the command, the group's crates and the step, such as `@convesoft/nx-rust: cargo test for api, core, cli (step 1 of 3)` ([[EVD-NX-24-BATCHES]], "Terminal output"). Such lines belong to no task: Nx neither stores nor replays them, and no task's stored output and no environment changes. Not chosen: live output in the terminal UI only, live output in every style, which the static styles print twice, and no live output. Under GitHub Actions' grouping, Nx holds back every line of a batch until it has ended, whatever the batch writes.
436
+
437
+ A task that Nx runs on its own, as with `--batch=false`, is a group of one task: it runs the steps that the same group runs in a batch, with cargo's standard streams as its own where it selects its crate, and, where it selects the whole workspace, its part of the steps' output once they have ended, as its result in a batch holds it. Nx runs such tasks at the same time, up to `--parallel`, and stores each once it ends. A whole-workspace `build` and the compile of `napi-build` and `wasm-build` build in a stage on their own as in a batch (**Staged builds**), so that none replaces another task's executable, neither in the milliseconds before Nx copies it nor after. A `test` run on its own replaces the executables of `build` as plain `cargo test` does, and keeps nothing ([[ADR-TEST-AFTER-BUILD]]).
438
+
439
+ A group runs one cargo command for each step of its target, one after another. Every target has one step, apart from `test` with the nextest runner, which has the steps of [[DES-TEST-RUN]]: the selection in affected mode, the nextest run and the doctests; and `test` with the `cargo` runner under `workspace-build`, which has three: the build, the test binaries and the doctests ([[DES-TEST-RUN]], "Under `workspace-build`"). Every step starts in the workspace root ([[DES-INVOCATION]]) and selects the crates of the group's tasks in the same way, as [[DES-UNIFICATION]] prescribes, so that every step resolves the same features ([[REQ-STABLE-FEATURES]]) and reuses what the steps before it compiled. A step in which no crate of the group takes part, such as the doctests where no crate has a library, is left out, and so is every step after one that failed every task of the group, since no task can pass it any more. Before the step of a group of cached `build` or `doc` tasks, the plugin asks cargo once for the group's directories ([[DES-OUTPUTS]]).
440
+
441
+ The plugin maps the output of every step back to one result per task, whose terminal output holds its part of each step's output, in order. It matches cargo's human-readable lines without the terminal escape sequences that cargo adds where `CARGO_TERM_COLOR=always` or `term.hyperlinks` asks for them, as CI configurations set them, and keeps the lines as cargo wrote them in each task's output; cargo's JSON messages carry none. Unknown counts as failed: a step counts as passed or failed by cargo only where cargo exited with status 0 or with 101, the status that cargo gives a command that failed, and every task of a step whose cargo was stopped by a signal, exited with another status or did not start fails. So does every task of a step of several crates whose output is not whole: JSON messages that end without `build-finished`, which cargo prints when the build has ended, that hold a line cut short or that contradict the exit status, and a list of failed test targets that does not end cargo's output, is not exactly as long as its first line announces or holds a line that names no target. Only the last such list counts, so that a list that a test prints before cargo's own changes nothing. A group of one crate runs the command that its task runs outside a batch, without the flags below, which only tell the crates of a command apart, and passes a step where cargo exits successfully, with the whole output as its own: with one crate, a failed command is a failed crate. The checks that follow cargo run for each task after the last step of its group, a group of one crate included: the lockfile post-check, on the digests that [[DES-LOCKFILE-HASHING]] names, and for `build` the check of [[DES-BUILD-INPUT-CHECK]]. A task succeeds only when cargo reported its result. When a step's command succeeds, every task of the step has passed it, with one exception: in the test binaries' step under `workspace-build`, a task passes only where the selecting runner's record shows a passing run of every test executable of its crate, so that a command that exits with 0 without that evidence fails its tasks ([[DES-TEST-RUN]], "Evidence for test binaries"). When the command fails, a task passes the step only where cargo's output shows that its crate passed, and a task whose result the output does not show fails, with a message that says why. Each step runs even when a step before it failed for some crates. What cargo reports per crate after a failure was established by experiment ([[EVD-CARGO-BATCH-FAILURES]]):
442
+
443
+ - **Builds, checks and clippy.** `build`, `check` and `lint` pass `--keep-going` and read cargo's JSON messages. With `--keep-going`, cargo still builds every target that does not need a failed one; without it, cargo starts no new job after the first failure and leaves crates unbuilt that do not depend on the failed one. The messages report each target that cargo built as a `compiler-artifact`, also when it was fresh, and each rustc error as a `compiler-message` that names the package and the target. A failing build script appears only in cargo's human-readable error, and a target that cargo did not reach because something it needs failed does not appear at all. A task of a failed command therefore passes only when the messages report an artifact for every unit of its crate that the command builds whatever else is selected, and no error for any target of the crate. A unit is a target compiled in normal mode or as a test, which the messages tell apart by `profile.test`. Counting targets alone is not enough: with `--all-targets`, a dev-dependency that does not compile keeps cargo from compiling the crate's targets as tests, while it reports the crate's library and binaries as built and no error for the crate, whose check on its own fails ([[EVD-CARGO-BATCH-FAILURES]]). The units are those of the library and the binaries, tests, examples and benchmarks that the command's flags select and whose required features the task's own selection turns on, named from the `cargo metadata` report that the group asks for the package ID specifications, as [[DES-BUILD-INPUT-CHECK]] names the targets of `build`: without `--all-targets`, the library and the binaries in normal mode; with it, also the examples in normal mode, and, as tests, the library, the binaries and the benchmarks, whose `bench` flag the report does not give, and the tests and examples whose `test` flag is on. A unit counted although the crate turned it off fails the task only when the command fails, while a unit left out could pass a task whose crate failed. A target that only another selected crate's features turn on can fail the task only through an error message. So, apart from denied warnings (next point), a task fails when its own crate fails or when it needs a crate that failed, and its message names the crates that cargo reported as failed. A failure in a crate that the task does not need does not fail it. When that crate is outside the selection, which can happen under `workspace-build`, the failure is reported as a warning and fails no task.
444
+ - **Denied warnings.** Under `--message-format=json`, cargo neither fails on the warnings that `build.warnings = "deny"` or `CARGO_BUILD_WARNINGS=deny` denies nor says that they are denied, and `--message-format=json-render-diagnostics`, which fails, prints the diagnostics without the package they belong to ([[EVD-CARGO-TARGET-COMMANDS]]). The JSON compile steps, those of `build`, `check`, `lint`, `napi-build` and `wasm-build` that pass `--message-format=json`, keep it, so that they compile as plain cargo and rust-analyzer do and reuse their work, and the plugin applies the setting to the step's result itself, with the step's own command as the reference: had cargo applied the setting to that command, the command would have failed as a whole. So where the messages of such a step report a warning, a `compiler-message` of level `warning`, and a task of the step passed, the plugin reads the setting as cargo reads it for the command: from `CARGO_BUILD_WARNINGS` in the step's environment, or else from the first configuration file that sets `build.warnings` among those that cargo reads in the workspace root, the files of that folder, of each folder above it and of the Cargo home that `CARGO_HOME`, or else `HOME`, in the step's environment names, each before the files it includes. The plugin passes no `--config` that sets it. Warnings are denied where the value is `deny` and `cargo --version`, in the workspace root with the step's environment, names 1.97 or later, the first version that honours the setting; an answer that cannot be read counts as such a version, so that unknown counts as failed. Then every task of the step that passed fails, as [[REQ-BATCHING]] says, with a message that names the packages with warnings and what denies them, and says that cargo does not tell which crates a warning fails. This fails more tasks than a cargo command of each crate would, such as one whose crate does not use the crate with the warning, and never fewer of those that the step's command covers. Every `compiler-message` of level `warning` counts, also one without a lint code, which cargo's own count of denied warnings leaves out. Under `workspace-build` a step compiles with the workspace's feature selection ([[DES-UNIFICATION]]), so a warning that only another selection produces, such as one behind a feature that another member turns on, is not reported, as an error of that kind is not either. Where cargo's own verdict applies, the plugin applies no verdict of its own: a group of one crate that runs its task's plain command passes no JSON flag and adds nothing, and the test steps print cargo's own diagnostics and take cargo's verdict, while their message names its cause ([[DES-TEST-RUN]], "Denied warnings in a test step"). `CARGO_BUILD_WARNINGS` and the configuration files in the repository are cache inputs of every target that compiles ([[DES-INPUTS]]). Not taken: running cargo again without JSON messages, which would compile again what failed and repeat the output; `cargo config get`, which is unstable; and attributing warnings to the crates that reach the warned package through the path dependencies of the members' report, which a review of nxr-tjxcvx defeated with three false passes on Cargo 1.100.0: a path patch of a registry dependency to a member, a path dependency outside the workspace that leads back to a member, and a warning that only the crate's own feature selection produces (nxr-hwkc7z keeps per-crate attribution in the backlog). Decided in nxr-tjxcvx on 22 November 2026, after the maintainer decided not to add an `args` option to `lint`, which would split Cargo's build cache from plain `cargo clippy`; failing every task of the step, with the amendment of [[REQ-BATCHING]], is the maintainer's decision of the same day: "Amend `REQ-BATCHING` (my recommendation). Add one sentence: where cargo denies warnings and a step reports a warning, every task of that step that passed fails."
445
+ - **Test runs.** `cargo test` and `cargo test --doc` pass `--no-fail-fast`, so a failing test binary or doctest does not stop the ones after it. `cargo test` has no `--keep-going`: a compile error in any crate that the command compiles stops it before any test runs, the tests of the crates that compiled included. nextest builds all test binaries before it runs one, so its run stops in the same way. Every test task of such a step fails, with a message that names the crates that failed to compile and says that the tests of the others were not run. Under `workspace-build` the step compiles the tests and the library of every crate of the workspace, so a compile error in a crate outside the group fails every test task of the group as well, while a `check` run only warns about it; the message then says that the crate is outside the selection. Where Cargo denies warnings, a warning stops such a step in the same way, and the message names the packages with warnings and what denies them ([[DES-TEST-RUN]], "Denied warnings in a test step"). The plugin does not run the step again without the failing crate, because that would be a further command with another selection of crates. This is a cost of batching: a task that runs its own cargo command runs its crate's tests whatever the state of an unrelated crate. How the output of a test run is attributed to tasks is part of [[DES-TEST-RUN]].
446
+
447
+ Known issue: since Nx 22.7, no other task starts while a batch runs, so JS tasks wait for a Rust batch ([[RISK-BATCH-BEHAVIOUR]]).
448
+ :::
449
+
450
+ :::mara design DES-UNIFICATION
451
+ :mid: 01M78FHG7F43VP2172VYY8A41Q
452
+ :title: Feature unification strategies
453
+ :status: accepted
454
+ :satisfies: REQ-STABLE-FEATURES
455
+ :mitigates: RISK-HAKARI-GAPS
456
+
457
+ Features are never resolved for the set of crates that happens to be selected ([[ADR-WORKSPACE-FEATURES]]): a group that shares a cargo command resolves them for the whole workspace, and a task whose group cannot runs its crate alone ([[DES-BATCH]], "Groups of one crate"). One option chooses how the whole workspace is resolved:
458
+
459
+ | Strategy | Used when | How | Cost |
460
+ | ----------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
461
+ | `hakari` | The workspace has a cargo-hakari configuration and passes the checks below | Build only the selected crates; the [[TERM-HACK-CRATE]] keeps third-party features unified | The hack crate must be kept current; an uncached drift check in every run |
462
+ | `cargo` | Opted in; experimental | `resolver.feature-unification = "workspace"` with `-Zfeature-unification`, both on the command line; select the crates with `-p` | Needs a nightly toolchain until Cargo stabilises it, and fails on stable; keys follow the whole workspace ([[DES-INPUTS]]) |
463
+ | `workspace-build` | Fallback, also for a workspace that fails a check below | Build the whole workspace; test binaries run through a selecting runner that skips the other crates, and the doctests of every crate run, of which the group keeps its own results ([[DES-TEST-RUN]]) | Compiles unaffected crates, and in every test run compiles and runs the doctests of every library; a compile error in any crate fails every test task of the group; needs a warm build directory; keys follow the whole workspace ([[DES-INPUTS]]) |
464
+
465
+ **How each strategy selects.** Every step of a group selects its crates in the same way ([[DES-BATCH]]), the selection of affected tests and the doctests included ([[DES-TEST-RUN]]):
466
+
467
+ - `hakari`, where it applies, and `cargo` select each crate with `-p` and its package ID specification ([[DES-INVOCATION]]).
468
+ - `cargo` passes `--config 'resolver.feature-unification="workspace"'` and `-Zfeature-unification` on the command line, of every command that compiles: the groups' steps, a group of one crate's included, and the commands of `doc`, `bench` and `run`, which the control plane settled on 16 November 2026 so that every command of such a workspace resolves features as its keys assume. Stable cargo ignores the setting without the flag, with a warning, and then resolves features for the selected crates alone, while it rejects the flag with an error ([[EVD-WORKSPACE-TEST-SELECTION]]). With the flag, a task on a stable toolchain fails with cargo's error instead of compiling with narrowed features. The control plane decided this on 14 November 2026 under [[GOAL-TRUSTED-CACHE]], of which the maintainer is told.
469
+ - `workspace-build`, and `hakari` where it falls back to it, select the whole workspace with `--workspace`. `build`, `check` and `lint` tell the crates apart by cargo's messages ([[DES-BATCH]]). For `test`, stable cargo has no flag that leaves out crates without narrowing features, so a group's test binaries run through the selecting runner of [[DES-TEST-RUN]], and with nextest through a filterset, and its doctests run for the whole workspace without a runner, of which the group keeps its own results ([[ADR-TEST-SELECTING-RUNNER]]). Where a runner for the host is or may be configured, the group's `test` tasks run one crate per command instead ([[DES-TEST-RUN]], "A runner the user configured").
470
+ - `-p` for one crate alone belongs only to the tasks that [[DES-BATCH]] names under "Groups of one crate": a feature set given by flags that act on the selected crates, a triple for which features are not resolved for the whole workspace, a runner that the user may have configured for the host, and a `test` task whose `test` option names a test target, which runs alone under every strategy and whose key holds the option: under `workspace-build` it compiles with its crate's own features in every run of that key, under `hakari` with those features and the hack crate's, as every command of that strategy that selects with `-p`, and under `cargo` with the workspace's feature unification, which its command still asks for ([[DES-TEST-RUN]], "One test target"). Each of those selects its crate with `-p` and needs no selecting runner. Every other group selects as its strategy prescribes, however many tasks it holds: under `workspace-build`, a group left with one task, because the command names one crate or Nx restored the other tasks from the cache, selects the whole workspace, with the selecting runner for `test`, and compiles with the features of the whole workspace, as its key promises. With `-p` it would compile with its crate's own features under the same key, and a test that depends on them would pass alone and fail in a larger run, or the other way round ([[EVD-TEST-RUNNER-EVIDENCE]]).
471
+
472
+ cargo-hakari unifies neither the features of workspace members nor those of a third-party crate that depends on a member through normal or build dependencies, and a feature that only a platform-specific dependency table asks for it unifies only on the platforms that its configuration lists ([[EVD-HAKARI-UNIFICATION]]). The `hakari` strategy therefore adds the following to what hakari does.
473
+
474
+ **When the hack crate is enough.** The maintainer decided on 14 November 2026 to keep the strategy in milestone 0.2 with full detection: the plugin uses the hack crate only where it can show that doing so is safe, and otherwise falls back to `workspace-build` with a message that says why. Moving the strategy out of milestone 0.2 was the option not taken. A workspace thus uses `hakari`, whether it is the default or `featureUnification` sets it, only when it has a configuration that cargo-hakari reads, `.config/hakari.toml` in the workspace root or else `.guppy/hakari.toml` ([[EVD-HAKARI-UNIFICATION]]), that parses and whose `hakari-package` names a member, and when it passes four checks, which graph creation makes from what it reads anyway; the drift check runs before the tasks (**Drift**, below).
475
+
476
+ 1. **No member asks a feature of another member, in any form.** In the `--no-deps` report ([[DES-METADATA-REPORT]]), take every dependency of a member whose path is the folder of another member, of every kind (normal, build and dev) and under every platform table, renamed, optional and inherited with `workspace = true` ones included, for which the report gives the features of `[workspace.dependencies]` and of the member merged. The check fails where such a dependency has a non-empty `features` list, or turns off default features while the other member's `features` table declares `default`, also as `default = []`, which still gives the member `feature = "default"` when it is selected itself; or where an entry of the member's `features` table names a feature of it as `<name>/<feature>` or `<name>?/<feature>`, by the dependency's name or its rename. It fails as well where a member's dev-dependency on itself, whose path is its own folder, has a non-empty `features` list: when the member is selected for its tests or with `--all-targets`, cargo compiles it with those features for every crate of the command that links it. A plain dependency with default features asks nothing beyond what the member has when it is selected itself, and turning off default features of a member that declares no `default` changes nothing ([[EVD-HAKARI-UNIFICATION]], "Features that no manifest asks for"). A use of a member through a registry or git dependency that a redirection replaces is the third check's.
477
+ 2. **`platforms` lists the host.** `platforms` in the configuration lists the host's triple, as `rustc -vV` names it in the workspace root, run as graph creation runs cargo ([[DES-METADATA-REPORT]]). The host counts for every task, also one that builds for another triple, because build scripts and proc macros are compiled for it. So a workspace whose `platforms` is empty, as in the configuration that `cargo hakari init` writes ([[EVD-HAKARI-UNIFICATION]]), or lists other triples only, falls back to `workspace-build`: running every task one crate per command would give up batching altogether, while `workspace-build` batches the whole workspace. Machines with different hosts can thereby use different strategies for one workspace; their keys differ anyway, because the toolchain input names the host ([[DES-INPUTS]]). A non-host triple that `platforms` does not list makes nothing fall back. The maintainer chose on 14 November 2026 "Keep `hakari`; that triple runs per crate (Recommended)", which refines his first answer, under which the whole workspace fell back; that falling back was the option not taken. The tasks that build for such a triple run one crate per command (**Triples that `platforms` does not list**), whether graph creation knows the triple, from `build.target` or `CARGO_BUILD_TARGET` ([[DES-OUTPUTS]]) or from a `targetTriple` that the metadata tables give a target of a member or one of its configurations ([[DES-PLUGIN-OPTIONS]]), or only a task names it. A target specification file is never listed.
478
+ 3. **No crate outside the workspace reaches a member through normal or build dependencies.** cargo-hakari leaves such a crate out of the hack crate, so its features, and those that it asks of the member, follow the selection; a crate that reaches a member only through a dev-dependency goes into the hack crate and passes ([[EVD-HAKARI-UNIFICATION]]). The `--no-deps` report does not show crates outside the workspace, and the full report that does is ruled out at graph creation ([[ADR-METADATA-NO-DEPS]]), so the check uses the crates outside the workspace whose dependencies the plugin knows from the reports it requests anyway ([[DES-METADATA-REPORT]]): the path crates that the members reach by path, through their dependencies of every kind and behind those through normal and build dependencies, through any number of such crates with a project or without; and the crates that the workspace's `[patch]`, `[replace]` and `paths` entries name, with the crates behind them by path ([[DES-PROJECT-GRAPH]]). The check fails where one of them reaches a member, matched by real folder, through normal or build dependencies, directly or through other such crates. Where the plugin cannot tell without the full report, it does not assume safety, and the check fails in exactly these shapes:
479
+ - a redirection of the workspace whose crate is a member: a `[patch]` or `[replace]` entry whose path is a member's folder, or a `paths` entry below whose folder discovery finds a member. Any registry or git crate that depends on that name then depends on the member, and only `Cargo.lock` or the full report shows whether one does; graph creation reads neither ([[DES-METADATA-REPORT]]);
480
+ - a crate among those above without a report, whose dependencies are unknown: one whose folder holds `.cargo-checksum.json` ([[ADR-SKIP-VENDORED-CRATES]]), and one whose report cargo refused with a warning ([[DES-METADATA-REPORT]]).
481
+
482
+ No other crate can reach a member: a registry crate names no path, and what a git crate names by path lies in its own repository, so either reaches a member only through such a redirection.
483
+
484
+ 4. **The configuration leaves nothing to the selection.** Some settings of cargo-hakari's configuration leave packages out of unification, and `generate --diff` and `verify` still pass ([[EVD-HAKARI-UNIFICATION]]). The control plane decided on 14 November 2026, under [[GOAL-TRUSTED-CACHE]] and with the maintainer told, that what is not shown to be safe counts as unsafe. The check therefore passes only where every key of the configuration is one of these, with a value for which experiments with cargo-hakari 0.9.39 found the features of every third-party crate the same in every selection ([[EVD-HAKARI-UNIFICATION]]):
485
+ - `hakari-package`, which names a member, and `platforms` (the second check);
486
+ - `resolver`: `"1"`, `"2"` or `"3"`, whatever the workspace's resolver;
487
+ - `unify-target-host`: `"auto"`, `"none"`, `"unify-if-both"` or `"replicate-target-on-host"`;
488
+ - `dep-format-version`: `"1"` to `"4"`; `exact-versions` and `output-single-feature`: `true` or `false`;
489
+ - `workspace-hack-line-style`: `"full"` or `"workspace-dotted"`;
490
+ - `traversal-excludes`, `final-excludes` and `registries`, only where they are empty.
491
+
492
+ It fails for a non-empty `traversal-excludes` or `final-excludes`, which leave members or third-party crates out of unification; for `workspace-hack-line-style = "version-only"`, with which the members' dependency on the hack crate names no path and features followed the selection; for a non-empty `registries`, which was not tried; and for any other key or value. The configuration that `cargo hakari init` writes passes once `platforms` is filled in.
493
+
494
+ The control plane settled on 16 November 2026, under [[GOAL-TRUSTED-CACHE]] and the rule that what the plugin cannot determine falls back, what the checks do where the files leave them no answer: a configuration that is no valid TOML falls back as one without `hakari-package`, before the first check; a `platforms` that is no list of strings, and a host that `rustc -vV` names no triple for, fail the second check; a list or table of the fourth check counts as empty only where every list in it, at any depth, is empty. A target table's `targetTriple` of `host-tuple` or a target specification file is no triple that the warning about `platforms` names. To undo one, change the function of `nx-rust/src/graph/unification.ts` that makes it and this paragraph.
495
+
496
+ **Fallback.** When a check fails, the whole workspace uses `workspace-build`: its crates' targets get that strategy's inputs ([[DES-INPUTS]]), it has no `hakari-check` target, and its groups build the whole workspace ([[DES-BATCH]]). Graph creation warns, and the warning names the workspace, the check, and the first member, crate, entry or setting that fails it, in a fixed order: the checks as numbered above, and members and crates by the path of their manifests. It says what would change the outcome: for the platforms, to add the host's triple to `platforms` and run `cargo hakari generate`; for the configuration, what is missing in which file, or the key and value of the setting that the plugin does not accept; and in every case that `featureUnification = "workspace-build"` in the workspace table makes the choice explicit, which ends the warning. The warning concerns every project of the workspace, crates and workspace project, and goes the way of the other warnings found when the graph is created: printed then, by `init`, and at the start of every task of those projects, with its digest in their named input `nx-rust-warnings`, so that the keys of their tasks change when it appears or goes away ([[DES-DIAGNOSTICS]], "Warnings where they are seen"). A workspace whose strategy is `cargo` or `workspace-build`, by default or by setting, is not checked and draws no warning.
497
+
498
+ **Where the executor reads it.** Graph creation records the strategy that a workspace uses, and under `hakari` the triples of `platforms`, in the metadata of each of its projects, beside the workspace's root manifest ([[DES-PROJECT-GRAPH]]), where it gives the same graph the inputs of that strategy; the executor reads both from there and takes a project whose metadata names no strategy, as from a graph made before the strategies existed, for `workspace-build`, whose keys such a graph holds. Under `hakari`, the batch reads the host's triple and the task's triples when it forms the groups; where `rustc -vV` names no host, or a triple's folder cannot be named ([[DES-OUTPUTS]]), the task forms a group of one crate, which costs speed and never a result. The control plane settled both on 16 November 2026.
499
+
500
+ **What the choice depends on.** The checks read the members' manifests and the root manifest, through the report; the configuration file of cargo-hakari; the manifests of the crates outside the workspace and the redirection tables of the root manifest and of Cargo's configuration files, with the folders below a `paths` entry, as for the graph's edges ([[DES-METADATA-REPORT]]); and, for the host, the toolchain in the workspace root. The other triples that graph creation knows, from Cargo's configuration files, `CARGO_BUILD_TARGET` and the members' metadata tables, decide only the warning about a triple that `platforms` does not list. Graph creation reads all of them afresh in every computation ([[ADR-NO-METADATA-CACHE]]). Without the Nx daemon, every command creates the graph. With the daemon, a change to a file inside the repository that Nx sees, such as a member's manifest or `.config/hakari.toml`, makes it run every plugin's `createNodes` again, as does a command that brings another environment ([[EVD-CARGO-REDIRECTIONS]], [[EVD-NX-24-WARNING-CHANNELS]]). The new graph gives the workspace's targets the inputs of the strategy that now applies, which are part of the project configuration that Nx hashes into every key, and adds or removes the warning, whose digest is in the keys as well ([[DES-INPUTS]], "Beyond the declared inputs"). A change that flips the answer therefore changes the key of every task of the workspace's crates. A file outside the repository or one that Nx ignores, such as a `[patch]` in the Cargo home's configuration, and a toolchain switched outside the repository reach the choice only when Nx creates the graph again, as they reach the edges ([[ADR-REDIRECTION-EDGES]]); the warning about such a configuration file says so ([[DES-DIAGNOSTICS]]), and a host that changed is handled as below.
501
+
502
+ **Triples that `platforms` does not list.** When the batch implementation forms the groups of a workspace that uses `hakari`, it reads the triples that each task's cargo commands build for, as it reads them for the outputs ([[DES-OUTPUTS]]), and the host's triple with `rustc -vV` in the workspace root and the task's environment. Where one of them is not among the `platforms` that graph creation recorded in the project's metadata, the hack crate does not unify the dependencies under that platform's tables, and the task forms a group of one crate ([[DES-BATCH]], "Groups of one crate"): its command resolves features for its crate alone, which its key under `hakari` covers. That holds for a non-host triple that graph creation knows, for which it also warns, naming the triple and `platforms`, saying that the tasks for it run one crate per command and that adding it to `platforms` and running `cargo hakari generate` lets them share commands. The warning concerns every project of the workspace and is printed and keyed like the fallback warning ([[DES-DIAGNOSTICS]]). It holds as well, without a warning, for a triple that graph creation does not see: one that the command line, a `project.json`, `targetDefaults` or a dotenv file of the task gives, or one that a configuration file outside the repository picks after the daemon created the graph, and for a host whose toolchain changed since. A triple that `platforms` lists shares a command as designed: the hack crate unifies third-party features on that platform, the first check fixes the features of members, and a feature set given by flags runs one crate per command (**Feature flags**).
503
+
504
+ **Feature flags.** Cargo applies `--all-features`, `--no-default-features` and `--features` to the crates that a command selects, so under `hakari` a group with a feature set given by flags runs one crate per command ([[DES-BATCH]], "Groups of one crate"). A member that is only a dependency in such a command is then built with what its dependents ask, which the first check fixes to its default features, whatever else the Nx command runs; and the hack crate carries the third-party features that every member asks for with all its features, which `generate` takes into account ([[EVD-HAKARI-UNIFICATION]]). Under `cargo`, `--features` runs one crate per command, while `--all-features` and `--no-default-features` act on every member and share one.
505
+
506
+ **Drift.** A workspace that uses `hakari` has the target `hakari-check` on its workspace project ([[DES-WORKSPACE-TARGETS]]). It runs `cargo hakari generate --diff` and then `cargo hakari manage-deps --dry-run` in the workspace root, and fails when either fails, with cargo-hakari's output and a message that says to run `cargo hakari generate` and `cargo hakari manage-deps` and commit the result. `cargo hakari verify` is not used: it passes for a member without the dependency on the hack crate, while these two commands caught every stale case tried, a missing feature, a new member without the dependency and a hack crate that gives more than the members ask for ([[EVD-HAKARI-UNIFICATION]]). Neither command writes a file. Following the pattern of the lockfile task ([[DES-LOCKFILE-HASHING]]):
507
+
508
+ - The target is not cached and runs whenever a task that depends on it runs. Every cached target of the workspace's crates that depends on the lockfile task, and the workspace's `doc`, depends on it, and it depends on the lockfile task, so that cargo-hakari reads the lockfile that the crates' keys hold. When it fails, Nx skips the tasks that depend on it and stores nothing for a skipped task, also with `NX_CACHE_FAILURES=true` ([[EVD-NX-24-BATCHES]], "Dependents of a failed task"). It is not cached because its verdict depends on the whole package graph, which also follows files outside the repository, such as a `[patch]` in the Cargo home's configuration, as the lockfile task's verdict does. It uses an executor without a batch implementation, so it never joins a batch.
509
+ - It is the second exception that [[REQ-NO-RUST-TASK-DEPS]] makes: a target of the workspace project, not of another crate, that depends on nothing but the lockfile task, so it adds no task cycle ([[DES-PROJECT-GRAPH]]). A cached crate task whose task graph holds no dependency on it, in a run that does not exclude task dependencies, as where a `project.json` replaces the target's `dependsOn`, fails before cargo runs, as one without the lockfile task does. A run with `--exclude-task-dependencies` runs neither, and `NX_RUST_RUN_ID` keeps whatever the crate tasks store from being restored ([[DES-LOCKFILE-HASHING]], "Excluded dependencies").
510
+ - cargo-hakari is the user's to install ([[ADR-V1-SCOPE]]). Where it is missing, the task fails with the message for a missing tool ([[DES-DIAGNOSTICS]]).
511
+ - Both commands read the whole package graph through `cargo metadata`, which needs the manifest of every package in the lockfile, for every platform ([[EVD-HAKARI-UNIFICATION]], [[ADR-METADATA-NO-DEPS]]). On a machine whose Cargo home lacks them, the check downloads them, also those that the build itself does not need. Offline, through `CARGO_NET_OFFLINE` or `net.offline`, it fails until they are there, as `cargo fetch` without `--target` leaves them.
512
+ - cargo-hakari passes cargo no `--locked` and takes no such flag ([[EVD-HAKARI-UNIFICATION]]). It needs none: in locked mode the lockfile task before it fails on a stale or missing `Cargo.lock`, and cargo leaves a current one alone ([[DES-INVOCATION]]). A lockfile that changes while the run goes on fails the crate tasks through the lockfile task's post-check ([[DES-LOCKFILE-HASHING]], "Post-check").
513
+
514
+ **What the keys hold.** Under `hakari`, a crate's key leaves out the other members' manifests and holds only its own digest. In their place it holds the hack crate's manifest and the configuration file of cargo-hakari ([[DES-INPUTS]], "Hack crate"). The drift check passes only where the hack crate is what cargo-hakari generates from the members' manifests, the lockfile and its configuration, so that the hack crate's manifest then stands for what the other members ask of third-party crates, and the four graph-time checks establish that this is all that the other members can change. With a stale hack crate, a crate's result would depend on its batch under a key that does not change; but then the drift check fails and no task of the workspace's crates runs, so nothing is stored. Generating the hack crate again changes its manifest and with it every key, and undoing the change that made it stale brings back the state for which the stored results hold.
515
+
516
+ **Masked missing features.** A crate can stop declaring a feature it needs because the hack crate enables it. An optional strict per-crate build target catches this. Decided by the control plane on 16 November 2026 and confirmed by the maintainer on 20 November 2026, under [[REQ-NO-MANIFEST-WRITES]] and [[ADR-V1-SCOPE]]: the target is not designed yet and does not exist, and nxr-ys8rx5 holds it. A command line cannot build a crate without the hack crate: a `[patch]` given with `--config` cannot replace the hack crate, which is a member, and cargo-hakari's own way, `cargo hakari disable`, writes the hack crate's manifest ([[EVD-HAKARI-UNIFICATION]], "Without the hack crate"). To undo, design the target as nxr-ys8rx5 asks, which needs the user's agreement on how it builds without the hack crate.
517
+
518
+ **Publishing.** The plugin never publishes the hack crate. Publishing a crate that depends on a hack crate with `publish = false` fails before cargo runs and points to cargo-hakari's ways of publishing such a crate ([[DES-RELEASE]]).
519
+
520
+ [[RISK-HAKARI-GAPS]] records what remains that no check sees.
521
+ :::
522
+
523
+ :::mara design DES-FEATURE-SETS
524
+ :mid: 01M78FHG7FBXD8XDCTFPZQD2QA
525
+ :title: Feature sets and target triples
526
+ :status: accepted
527
+ :satisfies: REQ-BATCHING
528
+ :satisfies: REQ-STABLE-FEATURES
529
+
530
+ Feature sets are Nx configurations at workspace level: the default features and all features. Every inferred target that compiles, `build`, `check`, `lint`, `test`, `bench`, `run` and the workspace's `doc`, has the default features in its options and a configuration `all-features` that sets `allFeatures`, so that `nx run-many -t test -c all-features` runs every crate with all features; a target table can lay a configuration of that name of its own over it ([[DES-METADATA-TABLES]]). A crate that needs another set either names single features as `crate/feature` or forms its own group: a task of `build`, `check`, `lint` or `test` whose own options give it a feature set, `features`, `allFeatures` or `noDefaultFeatures` from the crate's table, its `project.json` or a `targetDefaults` entry, is a group of one crate that selects only its crate, whatever else the batch holds, so that its result does not depend on what else runs and its command writes no other member's stored files ([[DES-BATCH]], "Groups of one crate"). Because features are target options, Nx hashes them ([[DES-INPUTS]]). A feature set that a configuration or the command line gives every task of a run shares a cargo command only where the flags act on every member whatever the command selects: under `workspace-build` on the host, which builds the whole workspace, and for `--all-features` and `--no-default-features` under `cargo`. Elsewhere, and so under `hakari` for every feature set but the default features, each crate gets a command of its own ([[DES-BATCH]], "Groups of one crate").
531
+
532
+ A platform triple for the same kind of artifact is an option of the target, `targetTriple` ([[DES-PLUGIN-OPTIONS]]). Without it, `build.target` in Cargo's configuration or `CARGO_BUILD_TARGET` can pick triples, and the outputs follow them ([[DES-OUTPUTS]]). A different kind of artifact gets its own named target ([[ADR-ARTIFACT-TARGET-NAMES]]). A non-host triple is a group of its own and builds only the selected crates, because building a whole workspace for such a triple would include crates that cannot target it. Under `workspace-build`, nothing else resolves the features of such a group for the whole workspace, so each of its crates gets a command of its own, which resolves features for that crate and what it depends on ([[DES-BATCH]], "Groups of one crate"). The keys of `workspace-build` hold every member's manifest and digest and the crates outside the workspace that any member reaches ([[DES-INPUTS]]), a superset of what such a command depends on. Under `hakari`, the crates of a group for a triple that `platforms` lists share a command, in a workspace that passes every check: the hack crate unifies the third-party features on that platform, the first check fixes the features of members, and a feature set given by flags runs one crate per command; a triple that `platforms` does not list runs one crate per command ([[DES-UNIFICATION]]). v1 runs tests on the host triple only.
533
+ :::