@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,486 @@
1
+ # Setup and compatibility
2
+
3
+ > **Status:** milestones 0.1 to 0.5 are implemented on `main`, and 1.0 release
4
+ > candidates are published on npm under the `next` dist-tag
5
+ > (`nx add @convesoft/nx-rust@next`).
6
+
7
+ ## What you need
8
+
9
+ | | Supported |
10
+ | ----- | --------------- |
11
+ | Nx | 24 |
12
+ | Cargo | 1.91 and later |
13
+ | Host | Linux and macOS |
14
+
15
+ Windows hosts are not supported in v1. With an older Nx or Cargo the plugin
16
+ stops with an error that names the version it found and the one it needs. A
17
+ later Nx major is added once the plugin's end-to-end tests pass on it. Until
18
+ then that major stops the plugin in the same way. To try it anyway, set
19
+ `NX_RUST_ALLOW_UNSUPPORTED_NX=true`: the plugin continues with a warning, but
20
+ nobody has checked its cache keys and batching on that major.
21
+
22
+ macOS is supported, but for the moment the plugin's own CI runs on Linux only,
23
+ so macOS is not tested automatically yet ([[ADR-CI-LINUX-ONLY]]). Please report
24
+ anything that behaves differently there.
25
+
26
+ The plugin installs nothing. These tools are yours to install, and only when
27
+ you use the feature that needs them:
28
+
29
+ | Tool | Needed for |
30
+ | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
31
+ | A Rust toolchain: `cargo` and `rustc` on `PATH`, with rustup or not | Everything |
32
+ | [cargo-nextest](https://nexte.st) | `testRunner = "nextest"` |
33
+ | [cargo-affected](https://github.com/max-sixty/cargo-affected) | `affectedTests = true` |
34
+ | The `llvm-tools` component (`llvm-cov` and `llvm-profdata`) | The `coverage-baseline` target that `affectedTests = true` adds |
35
+ | [cargo-hakari](https://docs.rs/cargo-hakari) | The `hakari` feature-unification strategy |
36
+ | [cargo-audit](https://crates.io/crates/cargo-audit) | The `audit` target |
37
+ | [cargo-deny](https://crates.io/crates/cargo-deny) | The `deny` target, which a workspace has only with a cargo-deny configuration file |
38
+ | The `wasm-bindgen` CLI and the wasm target | `wasm-build` |
39
+ | The napi CLI | `napi-build` |
40
+
41
+ When one is missing, the task that needs it fails with a message that says which
42
+ tool, which feature asked for it, and how to get it. `nx add` tells you
43
+ beforehand which of them your settings need.
44
+
45
+ Every machine that runs `nx` in the repository needs cargo, also one that only
46
+ works on JS projects: Nx asks Cargo for the crates whenever it builds the
47
+ project graph. Without cargo the graph fails with a message that says so. The
48
+ plugin does not leave the Rust projects out instead, because that machine would
49
+ then compute other cache keys than everyone else.
50
+
51
+ ## Adding the plugin
52
+
53
+ ```sh
54
+ nx add @convesoft/nx-rust
55
+ ```
56
+
57
+ Nx first installs the package, which adds it to your `package.json` and
58
+ lockfile, and then runs the plugin's `init` generator. `init` registers the
59
+ plugin in `nx.json`, adds five empty entries to its `targetDefaults`, and changes
60
+ nothing else in your repository: no crate, no Cargo manifest, no
61
+ `.cargo/config.toml`.
62
+
63
+ Rust targets share names such as `build`, `lint` and `test` with JS targets, so
64
+ a target default keyed by one of those names would reach them too. `init`
65
+ therefore adds an empty entry keyed by each executor of the Rust targets, where
66
+ `targetDefaults` has none:
67
+
68
+ ```json
69
+ {
70
+ "targetDefaults": {
71
+ "build": { "dependsOn": ["^build"], "cache": true },
72
+ "@convesoft/nx-rust:cargo": {},
73
+ "@convesoft/nx-rust:cargo-outputs": {},
74
+ "@convesoft/nx-rust:run": {},
75
+ "@convesoft/nx-rust:lockfile": {},
76
+ "@convesoft/nx-rust:release-publish": {}
77
+ }
78
+ }
79
+ ```
80
+
81
+ Nx chooses an entry keyed by a target's executor before one keyed by its name,
82
+ so `build` keeps applying to your JS projects and leaves the Rust targets as the
83
+ plugin infers them
84
+ ([Targets](targets.mara.md#target-defaults-that-reach-rust-targets)). `init`
85
+ says which entries it added. It never changes or removes an entry that is there,
86
+ also not one keyed by these executors.
87
+
88
+ Before it writes anything, `init` checks the repository the way Nx will once
89
+ the plugin and those entries are in place. If Nx could not build the project
90
+ graph, for example because cargo is not installed or two crates have the same
91
+ name, `init` stops with that error and `nx.json` stays as it was. The package
92
+ stays installed. Fix the problem and run `nx add @convesoft/nx-rust` again.
93
+
94
+ Then it reports what it found:
95
+
96
+ - tools from the table above that your settings need and that are missing, as
97
+ warnings, and tools that are missing but not needed by your settings, on one
98
+ line. cargo-audit is always on that line when it is missing, because no
99
+ setting asks for `audit`; an `audit` task still needs it;
100
+ - the warnings that building the graph gives, such as a `target` folder that Nx
101
+ does not ignore;
102
+ - each Cargo workspace whose build directory is inside the repository, with the
103
+ setting that moves it out ([Caching](caching.mara.md#cargos-two-directories)).
104
+ `init` does not write that setting for you.
105
+
106
+ In a repository without any `Cargo.toml`, it registers the plugin and tells you
107
+ how to create your first crate. Running it again leaves your plugin entry in
108
+ `nx.json`, options included, and your `targetDefaults` as they are, adds an
109
+ empty entry only where one is missing, and prints the report again.
110
+
111
+ Afterwards:
112
+
113
+ ```sh
114
+ nx show projects # your crates are listed
115
+ nx graph # with their dependencies
116
+ nx run-many -t lint test # Rust and JS together
117
+ ```
118
+
119
+ To add the plugin by hand, put it into `nx.json`, with the entries that `init`
120
+ adds:
121
+
122
+ ```json
123
+ {
124
+ "plugins": ["@convesoft/nx-rust"],
125
+ "targetDefaults": {
126
+ "@convesoft/nx-rust:cargo": {},
127
+ "@convesoft/nx-rust:cargo-outputs": {},
128
+ "@convesoft/nx-rust:run": {},
129
+ "@convesoft/nx-rust:lockfile": {},
130
+ "@convesoft/nx-rust:release-publish": {}
131
+ }
132
+ }
133
+ ```
134
+
135
+ ### Several checkouts of one repository
136
+
137
+ Nx 24 normally shares one local cache, in your home folder, between the linked git
138
+ worktrees of a repository, and between separate clones that it takes for the
139
+ same workspace. Sharing is off for a checkout where `nx.json` sets
140
+ `cacheDirectory` or the environment sets `NX_CACHE_DIRECTORY`,
141
+ `NX_WORKSPACE_DATA_DIRECTORY` or `NX_PROJECT_GRAPH_CACHE_DIRECTORY`. A Rust
142
+ result stored in one checkout is then restored in the others. For `check`,
143
+ `lint`, `fmt-check` and `test` that is only the result. A restored `build`
144
+ brings the other checkout's executables, whose compiled-in paths, such as
145
+ `env!("CARGO_MANIFEST_DIR")`, name that checkout.
146
+ [Sharing the cache between checkouts](caching.mara.md#sharing-the-cache-between-checkouts)
147
+ says what is restored and how to give `build` keys of each checkout's own.
148
+
149
+ ## Creating crates
150
+
151
+ ```sh
152
+ nx g @convesoft/nx-rust:library rust/crates/core
153
+ nx g @convesoft/nx-rust:binary rust/crates/cli --name my-cli
154
+ ```
155
+
156
+ | Option | Meaning |
157
+ | ----------- | ------------------------------------------------------------------------------------------------------------------ |
158
+ | `directory` | The crate's folder, the first argument. As with Nx's own generators, it is relative to the folder you run `nx` in. |
159
+ | `--name` | The package name. Without it, the crate is named after its folder. |
160
+ | `--edition` | The Rust edition. Without it, the crate takes the workspace's `edition`, or Cargo's default. |
161
+
162
+ Both run `cargo new --vcs none` in that folder, and Cargo adds the crate to the
163
+ members of the workspace around it unless a glob already covers it. The result
164
+ is what `cargo new` gives you, so a crate you create with plain `cargo new`
165
+ works just as well: the plugin finds it on the next run.
166
+
167
+ - Outside every Cargo workspace the crate is a standalone crate, with its own
168
+ `Cargo.lock` and build directory, and the generator says so.
169
+ - In a folder that the enclosing workspace lists under `exclude`, the generator
170
+ stops instead of overriding your `exclude`.
171
+ - `--dry-run` prints the cargo command and changes nothing.
172
+
173
+ If you run `cargo new` yourself, pass `--vcs none` when the folder above the new
174
+ crate does not exist yet. Otherwise Cargo creates a git repository inside the
175
+ crate, even within your repository.
176
+
177
+ Migrating from `@monodon/rust` is not part of v1.
178
+
179
+ ## Error messages and warnings
180
+
181
+ Each message says what is wrong, where (the crate, workspace, manifest, option
182
+ or tool) and what to do. Messages have no error codes.
183
+
184
+ - An error found while Nx builds the project graph stops every Nx command that
185
+ requires the project graph, JS tasks included, until it is fixed. The plugin
186
+ never leaves a crate out to get past it.
187
+ - A missing tool fails only the task that needs it.
188
+ - A warning found while Nx builds the graph is printed there, but on your
189
+ machine the Nx daemon builds the graph in the background and writes it to its
190
+ log (`.nx/workspace-data/d/daemon.log`). So the plugin prints the warning
191
+ again at the start of each task of the crate concerned, or of the target
192
+ concerned for a warning about one target, such as one about `targetDefaults`,
193
+ and `nx add` prints it too. `NX_DAEMON=false` shows it directly.
194
+ - A crate's warnings are part of its tasks' cache keys. When a warning appears
195
+ or goes away, the crate's tasks, and those of the crates that depend on it,
196
+ run again, so a task that Nx restores from the cache shows the warnings that
197
+ apply now. With the daemon, a warning about a file outside the repository,
198
+ such as your Cargo home's `config.toml`, appears and goes away only once a
199
+ file in the repository changes or you run `nx reset`, as the warning says.
200
+ - The terminal UI's summary of several tasks, and Nx in CI by default, leave
201
+ out the output of tasks that succeeded, and with it these warnings. Run with
202
+ `--output-style=static` to see them.
203
+
204
+ Keep Cargo's folders out of what Nx sees. Apart from a few fixed folders such
205
+ as `node_modules`, Nx ignores only what `.gitignore` and `.nxignore` say, so a
206
+ `target` folder that neither covers is hashed with your sources, and the plugin
207
+ warns about it. On your machine Nx also follows `.git/info/exclude` and your
208
+ global git excludes file, but other clones and CI do not have them, so the
209
+ plugin warns all the same. Either file of the repository will do:
210
+
211
+ ```gitignore
212
+ target/
213
+ ```
214
+
215
+ ## Requirements
216
+
217
+ :::mara requirement REQ-COMPATIBILITY
218
+ :mid: 01M78FHG7FES2FR7DNAAPSDVWE
219
+ :title: Support Nx 24, Cargo 1.91+, Linux and macOS
220
+ :status: accepted
221
+ :satisfies: NEED-EASY-SETUP
222
+
223
+ The plugin works with Nx 24 and with Cargo 1.91 and later, on Linux and macOS hosts. A later Nx major is supported from the release whose end-to-end suite has passed on it, and the package's peer dependency range names exactly the supported majors. With an older Nx or Cargo the plugin stops with an error that names the version found and the version required, instead of continuing with reduced behaviour. With an Nx major newer than the supported ones it stops in the same way, unless `NX_RUST_ALLOW_UNSUPPORTED_NX` is set to `true`, in which case it continues with a warning that names the major found and the supported majors.
224
+ :::
225
+
226
+ :::mara requirement REQ-INIT
227
+ :mid: 01M78FHG7FCBH4HM2R3S09S9KV
228
+ :title: Set up the plugin with nx add
229
+ :status: accepted
230
+ :satisfies: NEED-EASY-SETUP
231
+
232
+ `nx add @convesoft/nx-rust` registers the plugin in `nx.json` and reports the tools that the repository's configuration needs and that are missing. It writes nothing into crates.
233
+ :::
234
+
235
+ :::mara requirement REQ-CRATE-GENERATORS
236
+ :mid: 01M78FHG7F7C38X583EWPV1J5J
237
+ :title: Generate library and binary crates
238
+ :status: accepted
239
+ :satisfies: NEED-EASY-SETUP
240
+
241
+ A `library` generator and a `binary` generator each create a crate with `cargo new` and add it to the members of the Cargo workspace it is created in. The result is the same as running `cargo new` and editing the workspace manifest by hand.
242
+ :::
243
+
244
+ :::mara requirement REQ-DIAGNOSTICS
245
+ :mid: 01M78FHG7FGW9BB3M4MCE52PEG
246
+ :title: Say what is missing and how to fix it
247
+ :status: accepted
248
+ :satisfies: NEED-CLEAR-FAILURES
249
+
250
+ When a required toolchain or tool is missing, a version is unsupported, or options contradict each other, the plugin fails with a message that names what is wrong, the crate, workspace or option concerned, and what the user can do. It does this at the earliest point where the problem can be known, and it never installs anything itself. A problem found while the graph is created stops graph creation: the plugin does not leave a workspace or a crate out of the graph to get past it. The one exception is an Nx major newer than the supported ones while `NX_RUST_ALLOW_UNSUPPORTED_NX` is `true`, which the plugin reports as a warning before it continues ([[REQ-COMPATIBILITY]]).
251
+ :::
252
+
253
+ :::mara requirement REQ-NO-MANIFEST-WRITES
254
+ :mid: 01M78FHG7F8PRTX5Q1T77QNQ1K
255
+ :title: Write Cargo files only when asked to
256
+ :status: accepted
257
+ :satisfies: NEED-CARGO-UNCHANGED
258
+
259
+ The plugin does not write `Cargo.toml`, `Cargo.lock` or `.cargo/config.toml`. The exceptions are generators, release, and tasks that the user runs in order to change those files, such as a lockfile update. Cargo's own update of `Cargo.lock` during a command the plugin runs, which the same plain cargo command would make as well, is not a write of the plugin. That includes the update that the lockfile task's `cargo update --workspace` makes before a run's crate tasks, which their own cargo commands would make in the same way ([[DES-LOCKFILE-HASHING]]). With the `locked` option the plugin's commands cannot make it.
260
+ :::
261
+
262
+ ## Design
263
+
264
+ :::mara design DES-GENERATORS
265
+ :mid: 01M78FHG7FWY1P7FPVC6ZYA9ND
266
+ :title: Generators
267
+ :status: accepted
268
+ :satisfies: REQ-INIT
269
+ :satisfies: REQ-CRATE-GENERATORS
270
+
271
+ **`init`**, which `nx add` runs after Nx has installed the package. In v1 it takes no options of its own: it registers the plugin, keeps target defaults keyed by target names away from the plugin's targets, and reports. Options can be added later without breaking anything. Its only changes are in `nx.json`: the plugin entry and empty `targetDefaults` entries. It works in three steps.
272
+
273
+ 1. **Check.** It runs the checks that graph creation runs on `nx.json` as step 2 will leave it ([[DES-DIAGNOSTICS]]): the Nx version and, for the `Cargo.toml` files that Nx would hand the plugin, cargo, the Cargo version and toolchain of each workspace, each workspace's `cargo metadata` report, the project names, and what the `targetDefaults` of `nx.json` do to the inferred targets ([[DES-TARGET-DEFAULT-GUARD]]). A problem that would stop graph creation stops `init` before it writes anything, with the message graph creation would give. A registered plugin whose graph fails stops every Nx command that requires the project graph, the tasks of JS projects and `nx g` included ([[EVD-NX-24-SETUP]]). In a repository without any `Cargo.toml`, only the Nx version is checked and no cargo runs.
274
+ 2. **Register.** It adds the plugin to `plugins` in `nx.json`. When `nx.json` lists the plugin already, that entry, with whatever options the user set, stays exactly as it is, and `init` still runs its checks, adds the entries below and prints its report.
275
+
276
+ For each executor of the plugin's targets ([[DES-TARGETS]]) that `targetDefaults` has no entry for, it adds an empty entry keyed by that executor. Nx chooses an entry keyed by a target's executor before one keyed by the target's name or a glob, even when it is empty ([[EVD-NX-TARGET-DEFAULTS]]), so entries keyed by names that Rust targets share with JS targets, such as `build`, keep applying to JS targets and do not reach the plugin's. An entry that is there, keyed by one of these executors or by anything else, stays exactly as it is, whatever it sets, and [[DES-TARGET-DEFAULT-GUARD]] judges it in step 1: `init` never changes or removes an entry of `targetDefaults`. Where `nx.json` extends another file and only that file has `targetDefaults`, the combined entries go into `nx.json`, which Nx then reads instead.
277
+
278
+ 3. **Report.** It prints, without writing anything:
279
+ - the `targetDefaults` entries it added, naming their executors and saying that entries keyed by a target's name or a glob reach the other projects and not the plugin's targets;
280
+ - the warnings that graph creation gives ([[DES-DIAGNOSTICS]]), among them an entry keyed by one of the plugin's executors that adds dependencies to inferred targets, with the ways to narrow it. The user applies the fix by hand;
281
+ - each tool of the table below that the repository's configuration needs and that is missing, as a warning that names the tool, what needs it and how to get it;
282
+ - the tools of the table that are missing and that nothing in the repository needs, on one informational line marked "not needed by your settings";
283
+ - each workspace whose build directory lies inside the repository, with the `build.build-dir` setting that the caching guidance suggests. `init` never writes that setting: where Cargo keeps its files stays the repository's choice ([[DES-BUILD-DIRS]], [[EVD-CARGO-DIRECTORIES]]);
284
+ - in a repository without any `Cargo.toml`, how to create a crate.
285
+
286
+ | Tool | Needed when |
287
+ | ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
288
+ | cargo-nextest | A workspace uses the nextest runner ([[DES-TEST-RUN]]) |
289
+ | cargo-affected | A workspace has `affectedTests` on ([[REQ-AFFECTED-TESTS]]) |
290
+ | The `llvm-tools` component, `llvm-cov` and `llvm-profdata`, in the toolchain's sysroot, through `xcrun` on macOS or on `PATH` | A workspace has `affectedTests` on, whose `coverage-baseline` target collects coverage with them ([[DES-BASELINE]]) |
291
+ | cargo-hakari | A workspace uses the `hakari` strategy ([[DES-UNIFICATION]]) |
292
+ | The `wasm-bindgen` CLI and the wasm target | A crate has a `wasm-build` target ([[DES-ARTIFACT-STEPS]]) |
293
+ | The napi CLI | A crate has a `napi-build` target ([[DES-ARTIFACT-STEPS]]) |
294
+ | cargo-deny | A workspace root holds a cargo-deny configuration file, which gives its workspace project a `deny` target ([[DES-WORKSPACE-TARGETS]]) |
295
+ | cargo-audit | Never: no setting asks for `audit`, so a missing cargo-audit goes on the informational line. An `audit` task still fails without it ([[DES-DIAGNOSTICS]]) |
296
+
297
+ **`library` and `binary`.** Each creates one crate with `cargo new`, with `--lib` for `library` and `--bin` for `binary`. They have three options and no others:
298
+
299
+ | Option | Required | Meaning |
300
+ | ----------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
301
+ | `directory` | Yes; the first positional one | The crate's folder, resolved as Nx's own generators resolve it: against the folder `nx` runs in ([[EVD-NX-24-SETUP]]) |
302
+ | `name` | No | The package name, passed as `--name`. Without it, cargo uses the folder's name. |
303
+ | `edition` | No | The edition, passed as `--edition`. Without it, cargo chooses: the edition that `[workspace.package]` sets, otherwise cargo's default ([[EVD-CARGO-NEW]]). |
304
+
305
+ - **Exclusion.** The generator first finds the workspace that will enclose the crate, as cargo does: the nearest manifest above the folder that has a `[workspace]` table. When that workspace's `exclude` matches the folder, the generator fails with a message that names the manifest and the entry, and runs no cargo. Cargo itself would add the folder to `members`, and an explicit member overrides `exclude` ([[EVD-CARGO-NEW]]).
306
+ - **Creation.** The generator writes nothing through Nx's file tree. The callback it returns runs `cargo new --vcs none` in place, with the options given. Cargo writes the crate, takes over what `[workspace.package]` and `[workspace.lints]` provide, and adds the folder to `members` of the enclosing workspace unless an entry already matches it, creating the list when there is none. The generator does not edit the workspace manifest itself. `--vcs none` is always passed, because cargo creates a git repository inside the new crate, even inside a git repository, when a folder on the way to it does not exist yet ([[EVD-CARGO-NEW]]).
307
+ - **Dry run.** With `--dry-run`, Nx does not run the callback ([[EVD-NX-24-SETUP]]). The generator prints the cargo command it would run and changes nothing.
308
+ - **Outside a workspace.** With no enclosing workspace, the crate is a [[TERM-STANDALONE-CRATE]], as with plain `cargo new`, and the generator says that it has its own `Cargo.lock` and build directory.
309
+ - **Failures.** When cargo fails, for example because the folder exists, the generator fails with cargo's message.
310
+
311
+ A generator that migrates a repository from `@monodon/rust` is not part of v1 ([[ADR-SETUP-GENERATORS]]).
312
+ :::
313
+
314
+ :::mara design DES-DIAGNOSTICS
315
+ :mid: 01M78FHG7F2T375STHFWNZZZYG
316
+ :title: Diagnostics
317
+ :status: accepted
318
+ :satisfies: REQ-DIAGNOSTICS
319
+ :satisfies: REQ-COMPATIBILITY
320
+
321
+ Every diagnostic names what is wrong, the crate, workspace, manifest, option or tool concerned, and what the user can do. Messages carry no error codes in v1 ([[ADR-NO-ERROR-CODES]]). Each row of the table is one problem; checks that later features add join it as rows.
322
+
323
+ | Problem | Detected | Severity |
324
+ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- | --------------------------------------------------------- |
325
+ | Nx older than the supported majors ([[REQ-COMPATIBILITY]]) | When the plugin loads; by `init` | Error |
326
+ | Nx newer than the supported majors ([[REQ-COMPATIBILITY]]) | When the plugin loads; by `init` | Error; a warning with `NX_RUST_ALLOW_UNSUPPORTED_NX=true` |
327
+ | The installed Nx lacks, or has changed, the internal parts of Nx through which `init` runs the checks of graph creation ([[REQ-COMPATIBILITY]]) | By `init`, before it writes | Error |
328
+ | The installed Nx lacks one of the internal parts of Nx that [[DES-TARGET-DEFAULT-GUARD]] runs, where a target of the plugin differs from what the plugin inferred | When the graph is created; by `init` | Error |
329
+ | `cargo` not found, `cargo metadata` fails for a manifest ([[DES-DISCOVERY]]), or a root manifest or configuration file that cargo reads is no valid TOML ([[DES-METADATA-REPORT]]) | When the graph is created | Error |
330
+ | Cargo older than 1.91 in a workspace | When the graph is created | Error |
331
+ | A toolchain that a workspace pins is not installed | When the graph is created | Error |
332
+ | Two projects of the plugin, crates or workspace projects, with one name ([[REQ-PROJECT-NAMES]]); the plugin's error after Nx's is promised under names it gave them, else best effort ([[DES-PROJECT-GRAPH]]) | When the graph is created | Error |
333
+ | A `[workspace.metadata.nx.project]` table in a root manifest that defines a crate; the message points to `[package.metadata.nx]` ([[DES-PROJECT-GRAPH]], [[DES-METADATA-TABLES]]) | When the graph is created | Error |
334
+ | `affectedTests` without the nextest runner ([[REQ-AFFECTED-TESTS]]) | When the graph is created | Error |
335
+ | An unknown key at the top level of a metadata table or of its `project` sub-table, or in the plugin options ([[DES-PLUGIN-OPTIONS]]) | When the graph is created | Error |
336
+ | A key under `options` or a configuration of a target table in Cargo metadata that the target's executor does not know or the target does not take, or `pluginVersion` ([[REQ-UNKNOWN-METADATA-OPTIONS]]) | When the graph is created | Error |
337
+ | `inputs` without `"..."` on an inferred target in a metadata table ([[DES-PLUGIN-OPTIONS]]) | When the graph is created | Error |
338
+ | A different `executor`, or a `command`, on an inferred target in a metadata table ([[DES-PLUGIN-OPTIONS]]) | When the graph is created | Error |
339
+ | A field of a target table in a metadata table whose type is not the one that Nx gives it, such as `options = "broken"` ([[DES-PLUGIN-OPTIONS]]) | When the graph is created | Error |
340
+ | `affectedTests = true` as an option of `test` in stored configuration, in a workspace without the `affectedTests` setting ([[DES-PLUGIN-OPTIONS]]) | When the graph is created | Error |
341
+ | `targetNames` gives two inferred targets of one project the same name ([[DES-PLUGIN-OPTIONS]]) | When the graph is created | Error |
342
+ | A key of `targetNames` that is not the default name of an inferred target, or a value in it that is no target name ([[DES-PLUGIN-OPTIONS]]) | When the graph is created | Error |
343
+ | `locked` in the plugin options is neither `true` nor `false` ([[DES-INVOCATION]]) | When the graph is created | Error |
344
+ | Two or more entries of the plugin in `nx.json` receive manifests of one Cargo workspace, the same or different ones; the message names the workspace, the entries by their place in `plugins` with a manifest that each receives, and says to give all but one of them an `exclude` for the workspace or to narrow their `include`. Also where the plugin cannot tell which manifests an entry receives, naming what it could not determine ([[DES-PLUGIN-OPTIONS]]) | When the graph is created | Error |
345
+ | An `implicitDependencies` entry starting with `!` ([[DES-PLUGIN-OPTIONS]]) | When the graph is created | Error |
346
+ | A `fileInputs` pattern that resolves outside the repository or into Cargo's build or artifact directory, or has a `..` segment after a glob character ([[REQ-FILE-INPUTS-HASHABLE]], [[DES-INPUTS]]) | When the graph is created | Error |
347
+ | A `fileInputs` pattern that names files in the folder of another plugin's project below where it starts, inside another project's folder; the message gives the pattern to add ([[REQ-FILE-INPUTS-HASHABLE]], [[DES-INPUTS]]) | When the graph is created | Error |
348
+ | A `targetDefaults` entry that turns on caching that the plugin leaves off, or replaces the `inputs`, `outputs` or `dependsOn` it declares, on a target of the plugin ([[DES-TARGET-DEFAULT-GUARD]]) | When the graph is created | Error |
349
+ | An inferred target whose `inputs`, `outputs` or `dependsOn` mean less than the plugin declares, by a lost entry, an added negated pattern or a named input defined anew, where neither a `targetDefaults` entry nor the `project.json` or `package.json` in the project's folder does it, such as another plugin listed after nx-rust; the message names the target, the fields, what was lost or left out and the plugins that `nx.json` lists after nx-rust, and gives the fixes ([[DES-TARGET-DEFAULT-GUARD]], "Other layers") | When the graph is created | Error |
350
+ | A `pluginVersion` on an inferred target that the plugin did not give it, from `targetDefaults`, a `project.json`, a `package.json` or another plugin; the message names the entry or file where the plugin can tell ([[DES-PLUGIN-OPTIONS]]) | When the graph is created | Error |
351
+ | A Cargo configuration file that cargo reads for a workspace, that Nx does not hash, because it lies outside the repository or an ignore rule leaves it out, and that sets a table that can change a build or a check (**Cargo configuration that Nx does not hash**), and a root manifest with `[patch]` or `[replace]` entries that Nx does not read; once per file and plugin entry ([[RISK-HOST-ENVIRONMENT]], [[ADR-REDIRECTION-EDGES]]) | When the graph is created | Warning |
352
+ | A rustfmt configuration file in a folder above the repository, the home folder or the user's configuration folder that rustfmt takes for crates, because no folder between the source file of one of a crate's targets and the repository root holds `rustfmt.toml` or `.rustfmt.toml` (**Rustfmt configuration outside the repository**); once per plugin entry ([[RISK-HOST-ENVIRONMENT]]) | When the graph is created | Warning |
353
+ | A file that `include` names that is no valid TOML, or a crate without a project that `[patch]` or `[replace]` redirects to and `cargo metadata` fails for ([[DES-METADATA-REPORT]]) | When the graph is created | Warning |
354
+ | A path dependency without a project that `cargo metadata` does not report for a reason that cargo checks only for the crate it reports: it is no member of the workspace whose folder holds it, or the manifest that its `package.workspace` names has no `[workspace]` table or cannot be read ([[DES-METADATA-REPORT]]) | When the graph is created | Warning |
355
+ | A path dependency without a project whose files Nx cannot see ([[DES-INPUTS]]) | When the graph is created | Warning |
356
+ | A `targetDefaults` entry that adds a dependency on tasks of other projects, such as `^build`, to a target of the plugin ([[DES-TARGET-DEFAULT-GUARD]]) | When the graph is created | Warning |
357
+ | A target of the plugin with caching on where the plugin leaves it off, which its tasks then refuse, or with an added `dependsOn` entry, where the plugin cannot tell which configuration did it, such as another plugin ([[DES-TARGET-DEFAULT-GUARD]]) | When the graph is created | Warning |
358
+ | An artifact directory outside the repository; where it and another workspace's lie one inside the other, it also names that directory and says that a first build, while these directories do not exist yet, can fail in cargo with "No such file or directory", and to run the command again ([[DES-OUTPUTS]], "Nested artifact directories") | When the graph is created | Warning |
359
+ | An artifact directory that two or more workspaces share, also as one inside the other's, and also where separate entries of the plugin receive them; where they lie one inside the other, it also says that a first build, while these directories do not exist yet, can fail in cargo with "No such file or directory", and to run the command again ([[DES-OUTPUTS]], "Nested artifact directories", [[EVD-CARGO-NESTED-DIRECTORY-CREATION]]) | When the graph is created | Warning |
360
+ | Crates whose artifact directories are the same or lie one inside the other, also where separate entries of the plugin receive their workspaces, and whose executables, or `cdylib`, `dylib`, proc-macro or `staticlib` files, have one file name, also where the names differ only in case, so that the `build` of each crate that declares such a file, and the `test` of each whose tests run such an executable, run uncached; one warning per shared name, among the warnings of every crate it names and printed by the entry that holds the first, naming the crates, the file, the artifact directories and those targets, and saying to rename one binary or library or, for crates of several workspaces, to give each workspace an artifact directory of its own ([[DES-OUTPUTS]]) | When the graph is created | Warning |
361
+ | A build or artifact directory inside the repository that Nx does not ignore | When the graph is created | Warning |
362
+ | Nx hands a workspace's root manifest to no entry of the plugin, so that the workspace has no lockfile task and its crates' `build`, `check`, `lint` and `test` run uncached; the message names the root manifest ([[DES-LOCKFILE-HASHING]]) | When the graph is created | Warning |
363
+ | A workspace with a cargo-hakari configuration, or whose `featureUnification` is `hakari`, uses `workspace-build`, because it fails a check of the `hakari` strategy: no configuration that names a member as the hack crate, a member that asks a feature of another member, a host's triple that `platforms` does not list, a crate outside the workspace that reaches a member or whose dependencies the plugin cannot know, or a setting of the configuration that the plugin does not accept, such as a non-empty `traversal-excludes` or `final-excludes`; the message names the check, the first crate, entry or setting that fails it, what would change the outcome, and that `featureUnification = "workspace-build"` ends the warning ([[DES-UNIFICATION]]) | When the graph is created | Warning |
364
+ | A workspace that uses the `hakari` strategy builds for a non-host triple that graph creation knows, from Cargo's configuration, `CARGO_BUILD_TARGET` or a `targetTriple` in a metadata table, and that `platforms` does not list, so that the tasks for that triple run one crate per cargo command; the message names the triple and `platforms` and says that adding the triple and running `cargo hakari generate` lets those tasks share commands ([[DES-UNIFICATION]]) | When the graph is created | Warning |
365
+ | Cargo fails in the `lockfile` task, such as on a stale or missing `Cargo.lock` in locked mode ([[DES-LOCKFILE-HASHING]]) | When the `lockfile` task runs | Error |
366
+ | `cargo hakari generate --diff` or `cargo hakari manage-deps --dry-run` fails in the `hakari-check` task, because the hack crate is stale or the package graph cannot be read, such as offline in a Cargo home without the packages; the message carries cargo-hakari's output and says to run `cargo hakari generate` and `cargo hakari manage-deps` ([[DES-UNIFICATION]]) | When the `hakari-check` task runs | Error |
367
+ | `Cargo.lock` or a digest of it changed during a cached task, also through another `nx` command, so that a digest that the task compares, every one that its key holds and those that the post-check adds under `hakari`, no longer matches the one its command's lockfile task wrote or the task's key ([[DES-LOCKFILE-HASHING]]) | When the cargo call of the task has finished | Error |
368
+ | A task of a cached target that the plugin makes depend on the lockfile task, or on `hakari-check`, runs without it in a run that does not exclude task dependencies, so that its key holds no digest or nothing checked the hack crate, as where a `project.json` replaces its `dependsOn` ([[DES-LOCKFILE-HASHING]], [[DES-UNIFICATION]]) | When the task starts, before cargo runs | Error |
369
+ | A `test` whose cargo commands replace the executables of a crate's `build`, its own or, under `workspace-build`, another crate's of the workspace, runs in a command that runs or restores that `build` without an order in which Nx finishes one before it starts the other, as where a `project.json` replaces the `dependsOn` of `test`; the message names both tasks and says to keep the plugin's entries with `"..."` ([[DES-TARGETS]]) | When the task starts, before cargo runs | Error |
370
+ | Under `workspace-build`, the record of the selecting runner does not show that every test executable of the task's crate that cargo's messages name ran to its end with the status 0: an executable without a record, a record without an end, an error entry, a record folder that cannot be read, a `build-finished` message that reports a failure, or none, an artifact message of no member, or a failed exit of cargo that nothing in the record explains; the message names the executable and what is missing, and where the runner left no record at all, the runner's command, with `NODE_OPTIONS` as a variable to look at ([[DES-TEST-RUN]]) | When the test binaries' step has finished | Error |
371
+ | Under `workspace-build`, a doctest of a crate outside the group failed in the doctest step, which runs the doctests of the whole workspace; the message names the crate and says that no task of the group fails for it ([[DES-TEST-RUN]]) | When the doctest step has finished | Warning |
372
+ | With the nextest runner, nextest exits with 100 and tests of the task's package that `cargo nextest list` names for the run do not appear in the JUnit report as run and passed, as after a global timeout, a signal or an interrupt; the message says that the run was not complete and names some of the tests that did not run, and where the list cannot be run or read, it says so ([[DES-TEST-RUN]]) | When the nextest step has finished | Error |
373
+ | With the nextest runner, a setup script of the repository's nextest configuration failed, which the JUnit report shows in a suite `@setup-script:<id>` or nextest's status 105; every task of the group fails, and the message names the script ([[DES-TEST-RUN]]) | When the nextest step has finished | Error |
374
+ | With the nextest runner, the JUnit report holds a suite that is neither a test binary nor a setup script; every task of the group fails, and the message names the suite ([[DES-TEST-RUN]]) | When the nextest step has finished | Error |
375
+ | With the nextest runner, nextest exits with 100 and the JUnit report that the plugin's tool configuration asks for is missing, because the repository's nextest profile sets its own `junit.path`; every task of the group fails, and the message names the setting and says that the plugin cannot tell which crate's test failed ([[DES-TEST-RUN]]) | When the nextest step has finished | Error |
376
+ | A tool that a task runs is missing: cargo-nextest, cargo-affected, the `llvm-tools` component, cargo-hakari, cargo-audit, cargo-deny, the `wasm-bindgen` CLI, the wasm target or the napi CLI | When the task starts | Error |
377
+ | cargo-affected missing in a workspace with `affectedTests`, in a run in mode `full` | When a `test` task starts | Warning |
378
+ | The collection of `coverage-baseline` fails or is stopped; the message says that the baseline has no record of its context, so that affected runs take the full suite until a collection succeeds, and that a failing test fails the collection ([[DES-BASELINE]]) | When cargo-affected has ended | Error |
379
+ | Another collection of the same checkout runs, by the lock in `target/affected`; the message names its process and says to run the target again once it has ended ([[DES-BASELINE]]) | When the task starts | Error |
380
+ | A collection finds a lock whose process no longer runs and the takeover marker `target/affected/nx-rust-collect.lock.takeover` beside it, because another collection takes the stale lock over or one was stopped while it did, so the takeover is refused; the message names both files and says to run the target again, and to remove both once no collection runs. A marker beside no lock fails nothing ([[DES-BASELINE]]) | When the task starts | Error |
381
+ | `coverage-baseline` with `diffOnly` where only a full collection would do; the message gives the reason and says that a run with `--fullCollect` collects ([[DES-BASELINE]]) | When `cargo affected status` has ended | Warning |
382
+ | A `build` task read a file in the repository that none of its inputs covers ([[REQ-BUILD-INPUT-CHECK]]) | When the cargo call of a `build` task has finished | Error |
383
+ | The installed Nx lacks `HashPlanInspector`, or the glob or the reset of the workspace context, through which the check of [[DES-BUILD-INPUT-CHECK]] lists a build's files and matches them with its inputs; the check does not run, and Nx caches the result | When the cargo call of a `build` task has finished | Warning |
384
+ | A value of `NX_RUST_TEST_MODE` other than `affected` and `full` ([[DES-TEST-MODE]]) | When a `test` task starts | Error |
385
+ | A value of `NX_RUST_LOCKED` other than `true` and `false`; an empty value counts as unset ([[DES-INVOCATION]]) | When a task starts, before cargo runs | Error |
386
+ | A `pluginVersion` for one run that differs from the target's, such as `--pluginVersion` on the command line ([[DES-PLUGIN-OPTIONS]]) | When a task starts, before cargo runs | Error |
387
+ | A target that names a plugin executor but was not inferred; the message says to use a target with a `command` instead ([[DES-TARGETS]]) | When the task starts, before cargo runs | Error |
388
+ | Cargo's configuration of a workspace, or the `CARGO_BUILD_TARGET` of graph creation, picks a triple whose folder the plugin cannot name, such as `host-tuple`, so that `build` and `doc` stay uncached unless their own options name a triple that no configuration clears; the message names the value, what picks it and the `targetTriple` option ([[DES-OUTPUTS]]) | When the graph is created | Warning |
389
+ | When a cached `build` or `doc` whose run names no triple starts, the task's environment and Cargo's configuration pick other triples than its outputs name, as a `CARGO_BUILD_TARGET` in a dotenv file of the task does, or a triple whose folder the plugin cannot name; the message names the triples, what picks them and the `targetTriple` option ([[DES-OUTPUTS]]) | When the task starts, before cargo runs | Error |
390
+ | When a cached `build` or `doc` starts, Cargo's configuration alone picks other triples than when Nx created the graph, where the run names no triple, or gives another artifact directory, as after a change to a configuration file outside the repository that the Nx daemon does not watch; the message says what changed and to run `nx reset`, or stop the daemon, and run the task again ([[DES-OUTPUTS]]) | When the task starts, before cargo runs | Error |
391
+ | When a cached `build` or `doc` starts, cargo reports, with the task's environment, another artifact directory than its outputs name, as where a dotenv file that Nx loads only for the task sets `CARGO_TARGET_DIR`, `CARGO_BUILD_TARGET_DIR` or `CARGO_HOME`; the message names both folders and the variables, and says to set them in the environment of the `nx` command or in the root `.env`, or to set the folder as `build.target-dir` in `.cargo/config.toml` ([[DES-OUTPUTS]]) | When the task starts, before cargo runs | Error |
392
+ | `cargo metadata` fails when a cached `build` or `doc`, or any `build`, starts, so that the plugin cannot tell Cargo's directories for the task; the message carries cargo's and says to correct what cargo reports ([[DES-OUTPUTS]], [[DES-BUILD-INPUT-CHECK]]) | When the task starts, before cargo runs | Error |
393
+ | `cargo metadata` fails when a task whose command selects its crate by its package ID specification starts, so that the plugin cannot name the crate to cargo; the message names the crate, carries cargo's and says to correct what cargo reports ([[DES-INVOCATION]]) | When the task starts, before cargo runs | Error |
394
+ | When a task starts, its workspace has no member with the crate's package name any more, so that the project graph is out of date; the message says to run `nx reset`, or stop the daemon, and run the task again ([[DES-INVOCATION]]) | When the task starts, before cargo runs | Error |
395
+ | The `targetTriple` option of a cached `build` or `doc` is `host-tuple` or a target specification file; the message names the option and its value, says that the plugin cannot name the folder that cargo writes to for it, and says to pass the host's triple, which it names, in place of `host-tuple`, or for a specification file to build with a built-in triple or with caching turned off for the target ([[DES-OUTPUTS]]) | When the task starts, before cargo runs | Error |
396
+ | The profile `dev`, `test` or `bench` on `build` or `doc`; the message names the profile to use instead ([[DES-OUTPUTS]]) | When the task starts, before cargo runs | Error |
397
+ | The configuration caches a target that the plugin leaves uncached in its project, such as through a `project.json`; the message gives the reason and how to find the setting ([[DES-OUTPUTS]]) | When the task starts, before cargo runs | Error |
398
+ | When a cached `build`, `doc`, or `test` that waits for its `build`, starts, a target of another project that graph creation did not see, such as one that another installation of the plugin creates, writes a file of a name that the task declares into the task's artifact directory or one inside or around it, or for `doc` has such a directory; the message names both targets and the file and says to rename one binary or library or to register both workspaces through one installation of the plugin ([[DES-OUTPUTS]]) | When the task starts, before cargo runs | Error |
399
+ | `--affectedTests=true` on the command line for a `test` task in a workspace without the `affectedTests` setting ([[DES-PLUGIN-OPTIONS]]) | When a `test` task starts, before cargo runs | Error |
400
+ | A task's dotenv files could make Nx look up a variable whose value where Nx expands them depends on how the task runs, written in a file (including in a default or alternative branch, through `$$NAME` indirection, or through `dotenv-expand`'s `split(null)` splitting an operator-less braced body on literal `"null"`) or reached through a value that the expansion substitutes; the message names the file, the variable whose value refers to it, the variable looked up and why its value differs, says to remove the reference, and never prints any character from a variable's value ([[DES-BATCH]], "Dotenv files") | When the task starts, on its own or in a batch, before cargo runs | Error |
401
+ | `DOTENV_KEY` is set and dotenv would read the task's variables from a vault: `.env.vault`, `.local.env.vault` or `.env.local.vault` at the root, also without the plain file and where Nx loads no dotenv files, or the vault beside the last of the task's files; the message names the vault and says to remove it or unset `DOTENV_KEY` for the command ([[DES-BATCH]], "Dotenv files") | When the task starts, on its own or in a batch, before cargo runs | Error |
402
+ | A task's dotenv files hold a dynamic or ambiguous `$` form from which the static check cannot tell which variables Nx looks up (a `${...}` key containing `$`, `{` or `}`, a top-level unclosed `${` followed by a matched reference, an empty `${}` or unclosed `${` inside a referenced value or default, `$${...}`, `$$$NAME`, `$$NAME` assembling a dynamic name, a `$&`/`$'`/`` $` `` replacement pattern — including after `\` — in a referenced value or default, a trailing `$` before `[A-Za-z_{$]`, or an unbraced reference that can join adjacent text or an earlier escaped copy); the message names the file, the variable being expanded, an optional static identifier written directly in the task's dotenv files, and the kind of form in words, says what to change, and never prints any character from a variable's value ([[DES-BATCH]], "Dotenv files") | When the task starts, on its own or in a batch, before cargo runs | Error |
403
+ | The installed Nx lacks or has changed a part that the dotenv check reads (`getEnvFilesForTask`, `dotenv.parse`, or the `nx/src/tasks-runner/task-env` module); the message names the part and says to use a supported Nx ([[DES-BATCH]], "Dotenv files") | When the task starts, on its own or in a batch, before cargo runs | Error |
404
+ | A task's dotenv file defines `NX_LOAD_DOT_ENV_FILES`, with whatever value, so that the task's environment cannot tell whether Nx loaded the files; the message names the files, says to remove the definition from them 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 ([[DES-BATCH]], "Dotenv files") | When the task starts, on its own or in a batch, before cargo runs | Error |
405
+ | A task of a batch waits, through an edge with `waitFor: "ready"`, for a continuous task whose `readyWhen` reports ready by `signal`, from which Nx gives the task run on its own `NX_READY_URL` and a batch nothing; the message names the task and the continuous tasks, and says to run the command with `--batch=false`, or to set `NX_BATCH_MODE=false` in the root `.env`, which turns batching off for every task of the repository, of every plugin ([[DES-BATCH]]) | When a batch starts, before cargo runs | Error |
406
+ | The batch cannot rebuild its tasks' environments, because the installed Nx lacks or has changed a part through which it does; each task's message names the part and says to run with `--batch=false` or use a supported Nx ([[DES-BATCH]]) | When a batch starts, before cargo runs | Error |
407
+ | A batch would end with a task that it did not report, which only a fault of the plugin causes, so that Nx would start it again in a new batch process, perhaps without end; the task fails without running, so that Nx stores no successful result for it, and the message says so, to run with `--batch=false` and to report the bug ([[DES-BATCH]], "Every task in the batch that receives it") | When a batch ends | Error |
408
+ | A group of a `test` or `bench` batch cannot look at, keep in its stage or put back a file that a cached `build` of the command stores and that the group's cargo commands link again, or the kept file was written in place or had its permissions changed while they ran, or the group cannot make its stage, get Cargo's directories, or load Nx's glob matching, which a glob output of such a `build` needs; every task of the group fails, and the message names the file, or the outputs, and the build and says to check that the artifact directory can be written and has space ([[ADR-TEST-AFTER-BUILD]], [[DES-BATCH]]) | When a group of a batch starts or has run | Error |
409
+ | 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 that Nx resolved for them name it, such as the crate's `build` beside its `build` in another configuration or a copy of the target under another name; each such task that runs fails before cargo runs, in a batch and run on its own, and the message names the tasks and the folder as the outputs name it and says to run them in separate commands; where Nx restores every such task from its cache, none runs and none fails ([[DES-BATCH]], "Files that a batch stores") | When a batch or a `build` task starts | Error |
410
+ | A staged command cannot make its stage or get the report of Cargo's directories that names the stage's place and the build directory, and every task of the group fails; or it cannot move a file of a crate out of the stage into the artifact directory, and the task of that crate fails; the message names the folder or file and the cause, or cargo's message ([[DES-BATCH]], "Staged builds") | When a staged group starts or has run | Error |
411
+ | `wasm-build` where the version that `wasm-bindgen --version` names differs from that of the `wasm-bindgen` crate that the crate's entry reaches in `Cargo.lock`, or where it reaches none or several; the message names both versions and the command that installs the matching CLI ([[DES-WASM]]) | When the task starts, before cargo runs | Error |
412
+ | `wasm-build` whose option `wasmTarget` is none of `bundler`, `web` and `nodejs`; the message names the value and the three wasm targets ([[DES-WASM]]) | When the task starts, before cargo runs | Error |
413
+ | After the compile step of `wasm-build`, cargo reported no `.wasm` file of the crate's `cdylib`, or more than one, or the `wasm-bindgen` CLI failed or ended without writing the package's `.wasm` file; the message says which, with the CLI's output, and no `pkg` folder is left ([[DES-WASM]]) | After the compile step | Error |
414
+ | `napi-build` cannot post-process a crate: `@napi-rs/cli` of another major or older than 3.4.0, or a crate of the addon's closure that depends on `napi-derive` of another major than 3 ([[DES-NAPI]], [[ADR-NAPI-RS-3]]) | When the task starts, before cargo runs | Error |
415
+ | A crate with a `napi-build` or `wasm-build` target gives its library the file name of another crate's `cdylib`, `dylib`, proc-macro or `staticlib` file, as [[DES-OUTPUTS]] compares them, so that cargo builds one file for both; the message names both crates and says to give them different `[lib] name`s ([[DES-NAPI]]) | When the task starts, before cargo runs | Error |
416
+ | `napi-build` of a crate whose folder has no `package.json`, from which `@napi-rs/cli` reads the addon's settings; the message says to add one ([[DES-NAPI]]) | When the task starts, before cargo runs | Error |
417
+ | `napi-build` where `rustc -vV` names no host triple in the workspace root, or Cargo's configuration or `CARGO_BUILD_TARGET` picks another triple there; the message names the host and the picked triples and says that the target builds for the host only ([[DES-NAPI]], [[ADR-V1-SCOPE]]) | When the task starts, before cargo runs | Error |
418
+ | A cached `napi-build` whose installed `@napi-rs/cli` names the addon's file otherwise than the outputs that graph creation declared; the message names both and says to run `nx reset` ([[DES-NAPI]]) | When the task starts, before cargo runs | Error |
419
+ | A cached `napi-build` whose napi settings name a `dtsHeaderFile` outside the repository, which Nx cannot hash, or another file than the inputs of the graph hold; the message names the file and says to move it into the repository or to run `nx reset` ([[DES-NAPI]]) | When the task starts, before cargo runs | Error |
420
+ | After the compile step of `napi-build`, a crate that the step forced, the addon or a crate it depends on that uses `napi-derive`, wrote no type information; every `napi-build` task whose addon is that crate or depends on it fails, and the message names the crate and says that its build script does not run `napi_build::setup()` or that it has no `#[napi]` item left and should drop its dependency on `napi-derive` ([[DES-NAPI]]) | When the compile step has finished | Error |
421
+ | A task of `nx-release-publish` receives Nx's `registry` option, from `nx release publish --registry` or from configuration; the message names the value and where it came from, gives Cargo's own ways to choose a registry and says how npm packages alone get one ([[DES-RELEASE]], [[ADR-PUBLISH-REGISTRY-OPTION]]) | When a publish task starts, before cargo runs | Error |
422
+ | Cargo cannot choose the registry for a crate to publish, such as a `publish` list that leaves out `registry.default`, or crates.io replaced and no default; the message carries cargo's ([[DES-RELEASE]]) | Before each `cargo publish` | Error |
423
+ | A crate to publish depends, with a version requirement, on a crate of the repository that is not published to the registry that its dependency entry points to, through `publish = false`, a `publish` list, or an entry without the `registry` key or with another one; the message names both crates and the registries and says what to change ([[DES-RELEASE]]) | Before each `cargo publish` | Error |
424
+ | A crate to publish depends, with a version requirement, on a crate of the repository whose version is not in that registry yet and that the same call does not publish; the message names the dependency, its version and the crate, and says to publish the dependency first ([[DES-RELEASE]]) | Before each `cargo publish` | Error |
425
+ | The plugin cannot establish which registry a lookup asked, as under a replacement of the registry, with two names for one index or offline, or that a dependency's entry and the dependency's registry are one registry, as between two Cargo workspaces; the message says what could not be established and how to configure Cargo plainly ([[DES-RELEASE]]) | Before each `cargo publish` | Error |
426
+ | A crate would publish to crates.io on a machine whose Cargo configuration replaces crates.io; the message says to publish it from a job whose configuration does not replace crates.io ([[ADR-PUBLISH-REPLACED-CRATES-IO]]) | Before each `cargo publish` | Error |
427
+ | An option that a task's executor does not know, from a target default, a `project.json` or `package.json`, or the command line ([[REQ-UNKNOWN-OPTIONS]]) | When the task starts | Warning |
428
+ | A crate in the release without a version, or inheriting one that `[workspace.package]` does not set, a project of the release whose current version is to come from a registry, or a project with the plugin's version actions that is no crate; the message names the manifest or the project ([[DES-RELEASE]]) | By `nx release version`, before it writes | Error |
429
+ | Crates that inherit one version but are not all in one fixed release group, or a run of `nx release version` that would version only some of them; the message names the crates and the groups ([[DES-RELEASE]]) | By `nx release version`, before it writes | Error |
430
+ | A requirement on a crate that its new version leaves, of a form that the plugin does not rewrite, such as a comparison or a wildcard; the message names the manifest, the table and the requirement ([[DES-RELEASE]]) | By `nx release version`, before it writes | Error |
431
+ | `cargo metadata` fails for a workspace that `nx release version` reads, the version actions find no entry in a manifest for a dependency that cargo reports, cannot change a manifest's version strings without changing anything else, cannot write a file that the run changes, also one that a symbolic link leads outside the repository, or cannot read a manifest, Cargo configuration file or lockfile that exists, or a lockfile is no valid TOML; the message names the workspace, the manifest or the file, and the reason it cannot be read ([[DES-RELEASE]]) | By `nx release version`, before it writes | Error |
432
+ | A `[replace]` entry, a registry requirement redirected by `[patch]` or a profile's package specification that a crate's new version would leave, or a requirement outside the repository that would have to change; the message names the file and what to do ([[DES-RELEASE]]) | By `nx release version`, before it writes | Error |
433
+ | A crate of the release whose requirement on a bumped crate the run would rewrite without bumping the crate; the message names the crate and its release group and says to release it in the same run ([[DES-RELEASE]]) | By `nx release version`, before it writes | Error |
434
+ | Nx bumps a fixed release group without a bump of its own through an edge of the project graph; the line names the group, the edge and what the edge is in Cargo ([[DES-RELEASE]]) | By `nx release version` | Warning |
435
+ | `cargo update --workspace` fails in the lockfile step, which runs after Nx has written the files; the message names each workspace, carries cargo's message, lists the files written and the lockfiles updated by their real paths, and prints the commands that go back or on, each path quoted for a POSIX shell ([[DES-RELEASE]]) | By `nx release version`, after it writes | Error |
436
+ | A runtime input of the plugin that runs one of its Node scripts, for the artifact folders, the test mode or the napi CLI, fails when the executor runs it again for the task; the warning names the command and what the script wrote to standard error, and says that if it failed the same way when Nx computed the task's key, the result is not restored from the cache. Nx stores the warning with the task's output, so a cache hit replays it, also where only the executor's run failed ([[DES-INPUTS]], "Failing runtime inputs") | When the task runs | Warning |
437
+
438
+ **Errors.** A problem found when the graph is created stops graph creation for the whole repository; the plugin never leaves a workspace or a crate out to get past it ([[REQ-DIAGNOSTICS]]). `init` runs the same checks and stops before it registers the plugin ([[DES-GENERATORS]]). An error found when a task starts, or when the cargo call of a `build` task has finished, fails that task, so that no success is cached for it. By default Nx stores no failure either; with `NX_CACHE_FAILURES=true` it stores the failure and replays it until an input of the task changes ([[EVD-NX-24-FILE-INPUTS]]).
439
+
440
+ **Warnings where they are seen.** Nx 24 gives a plugin no channel to the terminal of a command that uses the Nx daemon's graph. What graph creation prints goes to the daemon's log file ([[EVD-NX-24-SETUP]]). A line that a plugin worker sends to the daemon's clients reaches only a command that is waiting for that computation, and the daemon also creates the graph again in the background after a change. The `preTasksExecution` and `postTasksExecution` hooks run in the daemon as well ([[EVD-NX-24-WARNING-CHANNELS]]). Only a task's own output reaches the terminal there, and Nx stores it and replays it on a cache hit. The plugin therefore prints a warning found when the graph is created three times: when the graph is created, again from the executor at the start of each task of the crate, workspace or target it concerns, and from `init`. The warnings about Cargo configuration that Nx does not hash and about a rustfmt configuration outside the repository are the exceptions to this paragraph: the executor prints them as the others, the second only at the start of `fmt-check` and `fmt` tasks, but no digest holds them, so a cache hit can show an earlier state of them (**Cargo configuration that Nx does not hash**, **Rustfmt configuration outside the repository**). Graph creation records the warnings that concern a project in the project's metadata, under `cargo.warnings`, where the executor finds them; those about Cargo configuration that Nx does not hash stand under `cargo.configurationWarnings`, and the one about a rustfmt configuration outside the repository under `cargo.formattingWarnings`, apart from the others because no digest holds them. Each project comes from one entry of the plugin, because graph creation refuses entries that receive manifests of one workspace ([[DES-PLUGIN-OPTIONS]], "Several entries"), so the project's warnings, those about Cargo configuration and those that `createDependencies` finds, stand in its metadata once. A warning that names crates of several entries, as one about crates of two workspaces that write files of one name ([[DES-OUTPUTS]], "Files of one name"), is found by each of those entries and printed by the first of them by its place in `nx.json`; the warning for an Nx major newer than the supported ones, which `NX_RUST_ALLOW_UNSUPPORTED_NX` lets the plugin run with, concerns every project. Graph creation also gives a project with warnings a named input, `nx-rust-warnings`, which no target names and which holds a digest of them. A project without warnings gets none, so that its keys hold nothing of this. Nx hashes a project's named inputs into the key of each of its tasks and of the tasks that depend on it ([[EVD-NX-24-WARNING-CHANNELS]], [[DES-INPUTS]]). So when a project's warnings change, its cached tasks run again and print the new ones, and a cache hit replays the warnings of the graph that the command uses. With the daemon, that graph keeps a warning whose cause lies outside the files that Nx reads until the daemon creates the graph again for another reason. Where Nx shows no output of a task that succeeded, as in the terminal UI's summary of several tasks and by default in CI, only the copy from graph creation is seen, and only without the daemon.
441
+
442
+ The digest is SHA-256 over the project's warnings, each once and in a fixed order, with every path inside the repository written relative to the repository root, so that checkouts of one repository in different folders get the same keys. A path outside the repository stays as the warning names it, because it identifies the cause, such as an artifact directory outside the repository. Machines whose warnings name different such paths, such as artifact directories in different users' home folders, therefore compute different keys for the tasks of the projects concerned and share no cache entries for them through a shared or remote cache, until the cause is gone or moved into the repository.
443
+
444
+ What else the executor prints before cargo runs follows from the key, or the task fails:
445
+
446
+ | Line | Why a cache hit shows it as the task would print it |
447
+ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
448
+ | An option that the task ignores ([[DES-UNKNOWN-OPTIONS]]) | The options come from the target's options and configurations, which the project's configuration in every key holds, and from the command line, which Nx hashes as the task's overrides ([[EVD-NX-OPTION-VALIDATION]]) |
449
+ | The check of [[DES-BUILD-INPUT-CHECK]] did not run, because the installed Nx lacks a part | Only an Nx that the plugin does not support lacks one, and it runs only with `NX_RUST_ALLOW_UNSUPPORTED_NX`, whose warning names the version found and is in every project's digest |
450
+ | An error of a row of the table above detected when the task starts or when its cargo call has finished, such as a missing tool, an artifact directory or triples other than the outputs name, `cargo metadata` failing, or a `targetTriple` whose folder the plugin cannot name | The task fails and Nx stores no result, unless `NX_CACHE_FAILURES=true` (**Errors**) |
451
+
452
+ Three cases stay outside the key, because what they depend on is deliberately no input: whether a tool is on `PATH` decides the warning for cargo-affected missing in mode `full`, and, with `NX_CACHE_FAILURES=true`, the stored failure of a task whose tool was missing; and whether Nx runs verbosely decides whether a task prints its cargo command, which names the folders of the checkout that ran it ([[DES-INVOCATION]], "Printing the command"). A hit replays what the run that stored the result printed.
453
+
454
+ **Cargo configuration that Nx does not hash.** Nx hashes no file outside the repository and no file that an ignore rule leaves out of the files it reads, so no key holds such a configuration file that cargo reads for a workspace: one in a folder above the repository, the Cargo home's, or one inside the repository that `.gitignore`, `.nxignore` or git's exclude files leave out, as Nx's workspace context reports ([[EVD-CARGO-REDIRECTIONS]]). [[RISK-HOST-ENVIRONMENT]] accepts that a result cached before a change to such a file can be restored after it, and the plugin warns for each such file that sets one of these top-level tables, which can change what cargo builds or checks: `[build]`, `[target]`, `[host]`, `[profile]`, `[env]`, `[patch]`, `[source]`, `paths`, `[unstable]` and `[doc]`. A file that sets only other tables, such as `[alias]`, `[net]`, `[http]`, `[term]`, `[registry]`, `[registries]`, `[resolver]`, `[cargo-new]`, `[install]` or credentials, draws none, so that an ordinary global configuration stays quiet; `[resolver]` and the registries change only what `Cargo.lock` records, which the keys follow through the lockfile task. The list is short on purpose: a table missing from it means a missing warning, not a wrong build. The warning is printed often, so it has two lines, three where the file redirects dependencies. It names the file, the tables of the list that it sets and the workspaces it applies to, and says that Nx does not hash it, why, and that a result cached before a change to it can be restored afterwards. It says to run `nx reset` after each change, and that `--skip-nx-cache` covers only the command it is given to, because Nx stores no result of such a run ([[EVD-NX-24-WARNING-CHANNELS]]); for a file inside the repository, that not ignoring it makes Nx hash it. It points to the section "Cargo configuration that Nx does not hash" of the caching guide for the rest. Where the file redirects dependencies, the warning adds that with the Nx daemon the graph's edges, and whether a workspace can use the `hakari` strategy, follow a change only once Nx creates the graph again ([[ADR-REDIRECTION-EDGES]], [[DES-UNIFICATION]]). A root manifest with redirections that Nx does not read gets the warning about its redirections alone. The control plane settled the files, the list of tables, the text and where the warning shows on 14 November 2026, within the maintainer's answer that [[RISK-HOST-ENVIRONMENT]] records, and the same day moved the warning from the lockfile task alone to every task, once it was checked that Nx hides the lockfile task's output by default.
455
+
456
+ **Rustfmt configuration outside the repository.** rustfmt looks for `rustfmt.toml` or `.rustfmt.toml` from the folder of each file it formats. Where no folder from there up to the repository root holds one, it takes the first such file in a folder above the repository, then in the home folder and then in `rustfmt` in the user's configuration folder, `$XDG_CONFIG_HOME` where it is absolute and `~/.config` otherwise; an error other than a missing file or folder, such as a folder that cannot be searched, makes it fail instead ([[EVD-CLIPPY-RUSTFMT-CONFIG-LOOKUP]]). Nx hashes none of these files, and [[RISK-HOST-ENVIRONMENT]] accepts that. It records the maintainer's answer of 22 November 2026 for per-user rustfmt configuration; the warning for a file in a folder above the repository follows from his rule of 14 November 2026 for configuration outside the repository, "Keep the risk, warn clearly". When the graph is created, the plugin looks for that file the same way, from the repository's real path, with `HOME` and `XDG_CONFIG_HOME` of the graph's environment, the configuration folder also where no home folder is known, and on macOS in `Library/Application Support` of the home folder, as the `dirs` crate that rustfmt uses names it there, which is reasoned and not run ([[ADR-CI-LINUX-ONLY]]); where an error stops rustfmt, it warns about nothing, as rustfmt reports its own failure. Where it finds a file, it concerns every crate of the entry's workspaces of which the folder of a target's source file, as `src_path` in the `cargo metadata` report gives it, has no configuration file between it and the repository root; a target whose file lies outside the crate's folder, such as one that `[lib] path` places elsewhere, counts as well, and a configuration file below the folder of a target's file, which rustfmt takes for the files below it, does not keep a crate from the warning. A file that `HOME` or `XDG_CONFIG_HOME` places inside the repository does not concern the crates whose folder holds it, whose keys hold their folder's files. One warning, of two lines, is printed when the graph is created for each plugin entry, and a copy of it is recorded for each crate it concerns. The first line names the file and the workspaces of those crates; for a file outside the repository, it says that Nx does not hash it, and for one inside it, that it lies outside the folders of those crates, so their keys do not hold it; and in both cases that a `fmt-check` result cached before a change to it can be restored afterwards. The second says to add a `rustfmt.toml` to the repository root, so that every machine formats alike and Nx hashes it, or to run `nx reset` after each change, that `--skip-nx-cache` covers only the command it is given to, and points to the section "Rustfmt configuration outside the repository" of the caching guide. The executor prints it at the start of each `fmt-check` and `fmt` task of those crates and of no other task, since only rustfmt reads the file, and, as for the warning about Cargo configuration, no key holds it, so that a machine's rustfmt configuration gives no keys of their own. A `HOME` or `XDG_CONFIG_HOME` that only a task's dotenv file sets is not followed, and under the Nx daemon a file added or removed outside the repository changes the warning only once Nx creates the graph again.
457
+
458
+ Graph creation and `init` print the warning, and the executor prints it again at the start of every task of every project of each workspace it concerns, crates and workspace project alike, from the project's metadata under `cargo.configurationWarnings`. So it is in the task's own output, which Nx shows in its default output styles for the task that a command names: for `nx run <crate>:build` with the Nx daemon, in a terminal, without one and with `CI=true`, when the task runs and when the cache restores it ([[EVD-NX-24-WARNING-CHANNELS]]). Where Nx hides the output of a task that succeeded, as for a dependency task in those styles and in the terminal UI's summary of several tasks, that task's copy is hidden as well. The warning stays out of the digest of **Warnings where they are seen** and out of every key, because a warning about a file outside the repository names it by its absolute path, so that every machine with a Cargo configuration of its own would get keys of its own. Limit: a cache hit replays the output of the run that stored the result, so it can show an earlier state of this one warning, as where the file has changed since or the warning was not there yet. A workspace whose root manifest Nx hands to no entry has no workspace project; its crates print the warning, and their targets that would read a digest run uncached (**No lockfile task** in [[DES-LOCKFILE-HASHING]]).
459
+
460
+ **Warnings that `createDependencies` finds.** Those of [[DES-TARGET-DEFAULT-GUARD]] depend on the projects as Nx merged them, which only `createDependencies` receives, and that hook can change neither a project's metadata nor its named inputs. `createMetadata`, which Nx calls after it in the same process with the merged graph, gives each project whose targets they concern those warnings in its metadata, under `cargo.targetWarnings`, each with its target and with the text that graph creation prints; Nx merges that metadata into the project's and keeps it out of keys ([[EVD-NX-24-WARNING-CHANNELS]]). The executor prints each, once, at the start of a task of its target, after the project's warnings. The key follows their causes as far as Nx and `createNodes` can see them:
461
+
462
+ - An entry of `targetDefaults` in `nx.json` changes every key, because Nx hashes `nx.json` into each ([[EVD-NX-OPTION-VALIDATION]]). An entry from a file that `nx.json` extends, which Nx does not hash, reaches the key through the digest: it also covers the `dependsOn` entries that `targetDefaults` adds to the project's targets, as far as `createNodes` sees them, with the projects of its own entry, Nx's synthesis of target defaults, run once for each plugin that may be the source of the targets, and the `package.json` and `project.json` in the projects' folders ([[DES-TARGET-DEFAULT-GUARD]]). An entry whose `filter` selects projects by a tag, also through `!`, counts for every project of the plugin with a target that the entry's key can reach, because another plugin may give the tag and `createNodes` cannot tell; a filter by a project's name, folder or executor keeps its exact reading, and one by plugin counts where any plugin that may be the source of the target lets it apply. An entry that its form shows to add only tasks of the project itself, such as `"check"` or `{ "target": "check" }`, stays out of the digest. A project with an entry that counts gets the named input even without warnings.
463
+ - A target that changed where the plugin cannot tell why: a changed tag is part of the project's configuration that every key holds, and `cache` turned on where the plugin leaves it off fails the task when it starts, so that no success is stored for it, and by default nothing at all (**Errors**). A lost or narrowed `inputs`, `outputs` or `dependsOn` that the folder's files do not explain fails graph creation instead ([[DES-TARGET-DEFAULT-GUARD]], "Other layers").
464
+
465
+ Three limits remain. Where only the list of projects that a warning names changes, as when a crate is added elsewhere, a cache hit of another crate shows the earlier list until its key changes. An entry from an extended file that does not apply to a project, or adds only the project's own tasks, where `createNodes` cannot tell, changes the digest and causes one run without a warning: one filtered to a tag that the project does not have, or one with a `projects` pattern like `api*` that matches only `api`; in `nx.json`, any change to an entry runs every task again anyway. And a `dependsOn` that another plugin changes, from files that no key holds, changes no key: a hit can show the warning about that target from before the change, or miss it.
466
+
467
+ **Nx version.** When it loads, the plugin compares the major version of the installed `nx` with the majors in its peer dependency range, so an unsupported Nx fails graph creation also in a repository without a crate. The error names the major found and the supported majors. For a newer major, `NX_RUST_ALLOW_UNSUPPORTED_NX=true` turns the error into a warning that says the plugin has not been checked on that major, and the plugin continues ([[REQ-COMPATIBILITY]]). The variable has no effect on an older major. The installed `nx` is the one that resolves from the repository root, where Nx itself looks for it. The daemon takes over each client's environment and recomputes the graph when a variable changes, but it can keep a loaded plugin, so the plugin compares again each time it creates the graph and prints the warning there; the variable thus works with the daemon as well ([[EVD-NX-24-SETUP]], [[EVD-NX-24-VERSION-CHECK]]). The peer dependency range itself stops no install, because pnpm only warns about an unmet peer.
468
+
469
+ **Cargo version.** The `cargo metadata` report of a stable Cargo has a `build_directory` field from 1.91 on ([[EVD-CARGO-DIRECTORIES]]). A report without it therefore tells the check that the workspace's Cargo is too old, and while Cargo is supported the check adds no cargo call to the one that the workspace costs ([[REQ-MULTI-WORKSPACE]]). Only the error makes a second call, to name the version found.
470
+
471
+ **Toolchains.** Graph creation and the toolchain input of a task's cache key do not let rustup install a toolchain that a workspace pins and that is missing. Graph creation fails with a message that names the toolchain and the workspace. The toolchain input cannot fail a task, so it gives the task a key that matches no stored result, and the task keeps plain cargo's behaviour ([[ADR-GRAPH-NO-TOOLCHAIN-INSTALL]], [[DES-INPUTS]]).
472
+
473
+ **Directories that Nx does not ignore.** Of the files of a repository, Nx leaves out only what `.gitignore` and `.nxignore` exclude and a few fixed folders, `target` not among them, and `cargo new --vcs none` writes no `.gitignore` ([[EVD-NX-24-SETUP]], [[EVD-CARGO-NEW]]). By default Cargo puts both its directories in the workspace folder, which for a standalone crate is the crate's folder, all of whose files are inputs ([[EVD-CARGO-DIRECTORIES]], [[REQ-INPUT-FILES]]). When Cargo's build or artifact directory lies inside the repository and Nx does not ignore it, the warning names the directory and advises adding it to `.gitignore`. The directory is the folder that cargo writes to, which the system reaches through the path that the `cargo metadata` report gives, as for the outputs ([[DES-OUTPUTS]]): that folder, relative to the repository's real path, decides whether the directory lies inside the repository and whether Nx ignores it, and the warning names it and the line for `.gitignore` by it. So a directory that a symbolic link leads outside the repository draws no warning, and one that a link leads to another folder inside the repository is judged and named by that folder. Where links make that folder differ from the one that the reported path names as text, the warning adds the path exactly as cargo reports it in brackets, so that the setting behind it can be found. That path is not normalised: a `..` after a link leaves the folder that the link leads to, so taking it as text could name a folder that does not exist. `init` names a build directory inside the repository in the same way. The plugin applies these rules as Nx itself reads them from the ignore files on disk, so it warns also before Cargo has created the directory, and where the installed Nx lacks that reading it does not warn. On the machine where it runs, Nx also leaves out what `.git/info/exclude` and the user's global git excludes file exclude ([[EVD-NX-24-SETUP]]), but the warning stays where only one of these covers the directory: neither file is part of the repository, so other clones and CI do not leave the directory out, and the warning names a gap that the repository has. A directory that several workspaces use gets one warning, which names them all, and the tasks of each of them print it.
474
+
475
+ **Missing tools.** The message names the tool, the target or setting that needs it, and how to get it. The plugin installs nothing ([[ADR-V1-SCOPE]]).
476
+ :::
477
+
478
+ ## Scenario
479
+
480
+ :::mara scenario SCN-ADOPT
481
+ :mid: 01M78FHG7FBRMYNWBR4T2Z3PHJ
482
+ :title: A team adds the plugin to an existing mixed repository
483
+ :status: accepted
484
+
485
+ A team has an Nx monorepo with JS apps and a Cargo workspace under `rust/` that Nx does not know about; CI runs the Rust checks through a separate script. A developer runs `nx add @convesoft/nx-rust`. The plugin is registered in `nx.json`, and the command reports that nextest is not installed, which the workspace's settings do not need. No file under `rust/` changes. `nx show projects` now lists every crate, and `nx graph` shows the edges between crates. The team replaces the script with the `nx affected -t lint test build` step that CI already runs for JS. Developers who work only on Rust keep using `cargo` and rust-analyzer as before, and their builds and the Nx builds reuse each other's compiled dependencies.
486
+ :::