@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,508 @@
1
+ # Configuration
2
+
3
+ > **Status:** implemented as this page describes.
4
+
5
+ Most repositories need no configuration. When a crate or workspace needs
6
+ something other than the default, you say so in the `Cargo.toml` that already
7
+ describes it. Repository-wide choices go into the plugin's entry in `nx.json`.
8
+
9
+ | Where | Scope | Typical use |
10
+ | ------------------------------------------------------------ | ------------------------------ | ---------------------------------------------------------------------- |
11
+ | `[package.metadata.nx]` in a crate's `Cargo.toml` | One crate | Project name, tags, options of a target, extra targets, artifacts |
12
+ | `[workspace.metadata.nx]` in the workspace root `Cargo.toml` | Every member of that workspace | Default tags, test runner, affected tests, a name prefix |
13
+ | `[workspace.metadata.nx.project]` in the same file | The workspace project | Its name, tags and targets |
14
+ | The plugin's entry in `nx.json` | The repository | Target names and locked mode in `options`, excluded paths in `exclude` |
15
+
16
+ A value for a crate wins over the workspace default, which wins over the
17
+ plugin options. Tags, `implicitDependencies`, `fileInputs`, `envInputs` and
18
+ `runtimeInputs` are the exceptions: they add up, so a crate has its workspace's
19
+ and its own. Which
20
+ setting goes where is listed under [All settings](#all-settings).
21
+
22
+ Nx applies some files after the plugin, and they win over all of these:
23
+ `targetDefaults` in `nx.json` first, then a `project.json` or `package.json`
24
+ in the project's folder. A target default that sets an option such as
25
+ `features` for `test` replaces the value a crate's `Cargo.toml` gives it,
26
+ unless the default is narrowed to other projects with a `filter`
27
+ ([Targets](targets.mara.md#no-build-between-crates)).
28
+
29
+ ## Per crate
30
+
31
+ The table has the shape of the `nx` property that Nx reads from a
32
+ `package.json`:
33
+
34
+ ```toml
35
+ # rust/crates/api/Cargo.toml
36
+ [package]
37
+ name = "api"
38
+
39
+ [package.metadata.nx]
40
+ name = "backend-api" # Nx project name; Cargo still sees "api"
41
+ tags = ["scope:backend"]
42
+ fileInputs = ["../../../proto/**/*.proto"] # files outside the crate that it reads
43
+
44
+ [package.metadata.nx.targets.test.options]
45
+ features = ["integration"] # option of the inferred "test" target
46
+
47
+ [package.metadata.nx.targets.migrate]
48
+ command = "cargo run -p api --bin migrate" # an extra target
49
+ ```
50
+
51
+ `fileInputs` patterns are relative to the `Cargo.toml` that holds them;
52
+ [Caching](caching.mara.md#files-outside-the-crate) says when you need them.
53
+
54
+ In a crate folder that also is a JS project, Nx applies its `package.json`
55
+ and `project.json` after this table. Where Nx takes the project's name from
56
+ them, `name` has no effect
57
+ ([Project names](workspaces.mara.md#project-names)). A script or target there
58
+ with the name of one of the crate's targets replaces that target, together with
59
+ the settings this table gives it, unless Nx merges the two
60
+ ([napi and wasm artifacts](artifacts.mara.md#things-to-know)).
61
+ Another plugin listed in `nx.json` may add to a crate's targets, but not take
62
+ away or narrow the inputs, outputs or dependencies that nx-rust declares; to
63
+ change them on purpose, write the change into the `project.json` in the crate's
64
+ folder
65
+ ([Other plugins that reach Rust targets](targets.mara.md#other-plugins-that-reach-rust-targets)).
66
+
67
+ The keys under `options`, and under each of the target's `configurations`,
68
+ have to be options of the target. A key that the plugin does not know, such as
69
+ a misspelt `feature`, makes graph creation fail with an error that names the
70
+ manifest, the target and the key. The same holds for the workspace table and
71
+ its `project` table. Options that reach a Rust target from `nx.json`, a
72
+ `project.json` or `package.json`, or the command line are ignored with a
73
+ warning instead: see [Targets](targets.mara.md#options-that-cargo-does-not-use).
74
+
75
+ ### Changing an inferred target
76
+
77
+ A `targets` entry for an inferred target is laid over it the way Nx lays a
78
+ `project.json` over a plugin's target: what you set replaces the inferred
79
+ value, and options are merged one by one. A list such as `inputs` replaces the
80
+ inferred list unless it contains `"..."`, which keeps the inferred entries in
81
+ that place:
82
+
83
+ ```toml
84
+ [package.metadata.nx.targets.test]
85
+ inputs = [
86
+ "...", # keep the inferred inputs
87
+ { env = "DATABASE_URL" }, # add a variable for this target
88
+ { runtime = "tar --version" }, # and the version of a program it runs
89
+ "!{projectRoot}/docs/**", # and leave the docs folder out
90
+ ]
91
+ ```
92
+
93
+ Two things fail when the graph is created, with a message that names the
94
+ manifest: `inputs` without `"..."` on an inferred target, because the cache key
95
+ would lose the toolchain, the environment and the files of the crate's
96
+ dependencies; and a different `executor`, or a `command`, on an inferred
97
+ target. To run another command, define an extra target under a name of its
98
+ own, as `migrate` above. Nx lays the `targetDefaults` of `nx.json` over an
99
+ extra target as over any target that a plugin infers, so an entry keyed by its
100
+ name replaces what the table sets, unless a list keeps it with `"..."`. The
101
+ plugin does not check this, because it infers nothing for the target.
102
+
103
+ Leaving files out, as `docs` above, is your statement that the target does not
104
+ read them. Nx then ignores changes to them, so if a macro such as
105
+ `include_str!`, a build script or a test still reads an excluded file, Nx
106
+ restores a result produced with the file's old content, a pass where plain
107
+ `cargo` would fail or the reverse. The check after a build catches this only
108
+ for an exclusion on `build`, and only for a read that Cargo records through an
109
+ include macro or a build script's `rerun-if-changed` in the crate's library or
110
+ binaries, by failing the task instead of caching it
111
+ ([Caching](caching.mara.md#files-outside-the-crate)); an exclusion on `check`,
112
+ `lint`, `test` or an artifact target, and a file that a proc macro opens
113
+ itself, stay unprotected.
114
+
115
+ An input on one target stays with that target: above, a new `DATABASE_URL` or
116
+ a `tar` on `PATH` that reports another version runs this crate's `test` again, and its `build` and
117
+ the tasks of the crates that depend on it are still restored from the cache.
118
+ That is the place for what only tests read. `envInputs` and `runtimeInputs`
119
+ reach further: they join the crate's `default` named input, and with it every
120
+ cached target of the crate and of the crates that depend on it. Use them when a
121
+ build script or macro reads the variable or runs the program, so that those
122
+ crates compile differently too
123
+ ([Caching](caching.mara.md#what-is-in-a-cache-key)).
124
+
125
+ `implicitDependencies` adds edges to projects that Cargo does not know about,
126
+ such as a JS project whose output a test reads. It only adds: an entry starting
127
+ with `!` is an error.
128
+
129
+ ```toml
130
+ [package.metadata.nx]
131
+ implicitDependencies = ["web"]
132
+ ```
133
+
134
+ ## Per workspace
135
+
136
+ ```toml
137
+ # rust/Cargo.toml
138
+ [workspace]
139
+ members = ["crates/*"]
140
+
141
+ [workspace.metadata.nx]
142
+ tags = ["lang:rust"]
143
+ namePrefix = "rust-" # members become "rust-api", "rust-core"
144
+ testRunner = "nextest"
145
+ affectedTests = true
146
+
147
+ [workspace.metadata.nx.project]
148
+ name = "rust-tools" # the workspace project, "rust" by default
149
+ tags = ["scope:tooling"]
150
+ ```
151
+
152
+ The `project` table configures the workspace project itself, the project for
153
+ workspace-level tasks, with the `name`, `tags` and `targets` keys of a crate's
154
+ table. The other keys of `[workspace.metadata.nx]` apply to the members. The
155
+ workspace project has the workspace's tags and its own, but a target set under
156
+ `[workspace.metadata.nx.targets]` is a default for the members only, and one
157
+ named like an inferred target applies only to the members that have it, such
158
+ as `bench` to the crates with benches. When the
159
+ root `Cargo.toml` also defines a crate, that crate is the workspace project and
160
+ is configured in its `[package.metadata.nx]` instead
161
+ ([Workspaces](workspaces.mara.md#workspace-level-tasks)).
162
+
163
+ `namePrefix` is used as it is, so include the separator you want. A crate that
164
+ sets its own `name` gets exactly that name. The workspace project gets no
165
+ prefix where it is a project of its own, because the root `Cargo.toml` defines
166
+ no crate; where the root `Cargo.toml` defines a crate, that crate is named like
167
+ any member, prefix included
168
+ ([Project names](workspaces.mara.md#project-names)).
169
+
170
+ A standalone crate is a workspace of one. It takes the workspace settings from
171
+ a `[workspace.metadata.nx]` table in its own `Cargo.toml`, beside
172
+ `[package.metadata.nx]`.
173
+
174
+ ## Target names
175
+
176
+ Inferred targets use the names Nx projects conventionally use, so the commands
177
+ a mixed repository already runs also cover Rust:
178
+
179
+ ```sh
180
+ nx affected -t lint test build
181
+ ```
182
+
183
+ `lint` runs clippy. Formatting is the one exception: `nx format` is a built-in
184
+ Nx command that cannot run rustfmt, so the Rust targets are `fmt-check` and
185
+ `fmt` ([Targets](targets.mara.md#formatting)). If you prefer Cargo's names
186
+ elsewhere too, rename targets in the plugin options:
187
+
188
+ ```json
189
+ {
190
+ "plugins": [
191
+ {
192
+ "plugin": "@convesoft/nx-rust",
193
+ "options": {
194
+ "targetNames": { "lint": "clippy" }
195
+ }
196
+ }
197
+ ]
198
+ }
199
+ ```
200
+
201
+ Two targets may not end up with one name: `{ "test": "build" }` fails graph
202
+ creation and names the project, both targets and the name. A key has to be the
203
+ default name of an inferred target, such as `bench`, also in a repository
204
+ without benches; `{ "clippy": "lint" }` fails graph creation and lists the names
205
+ that can be renamed. `nx-release-publish` keeps its name, because Nx release
206
+ runs the publish target only under that name ([Releasing](release.mara.md)). A
207
+ `targets` table in `Cargo.toml` uses a target's name after renaming.
208
+
209
+ The full list of targets is on the [Targets](targets.mara.md) page.
210
+
211
+ ## Options of targets
212
+
213
+ The plugin's targets take these options, each the cargo flag of the same
214
+ meaning, apart from `wasmTarget`, which `wasm-build` passes to the
215
+ `wasm-bindgen` CLI, and the options of `coverage-baseline`, which choose how
216
+ it collects. Set them under `targets.<name>.options` in either table, or on the
217
+ command line:
218
+
219
+ | Option | Cargo flag | Targets | Default |
220
+ | --------------------------------------------------------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | --------------------- |
221
+ | `features` | `--features` | `build`, `check`, `lint`, `test`, `bench`, `run`, `napi-build`, `wasm-build`, `doc` and `coverage-baseline` | none |
222
+ | `allFeatures` | `--all-features` | the same | `false` |
223
+ | `noDefaultFeatures` | `--no-default-features` | the same | `false` |
224
+ | `profile` | `--profile`; `--cargo-profile` for nextest | the same | Cargo's default |
225
+ | `targetTriple` | `--target` | the same, apart from `test`, `napi-build`, `wasm-build` and `coverage-baseline` | Cargo's default |
226
+ | `allTargets` | `--all-targets` | `check`, `lint` | `true` |
227
+ | `noDeps` | `--no-deps` | `doc`, on the workspace project | `true` |
228
+ | `bin` | `--bin` | `run` | Cargo's choice |
229
+ | `args` | the binary's arguments, after `--` | `run` | none |
230
+ | `test` | `--test`, for nextest too | `test` ([Testing](testing.mara.md#one-test-target)) | none: the whole suite |
231
+ | `affectedTests` | none | `test` | the workspace's |
232
+ | `wasmTarget` | `--target` of the `wasm-bindgen` CLI: `bundler`, `web` or `nodejs` | `wasm-build` | `bundler` |
233
+ | `fullCollectThreshold`, `fullCollect`, `diffOnly`, `separateBuildDir` | none | `coverage-baseline` ([Continuous integration](ci.mara.md#the-coverage-baseline)) | 100, off |
234
+
235
+ ```toml
236
+ # rust/crates/bench-heavy/Cargo.toml: benches that need nightly
237
+ [package.metadata.nx.targets.check.options]
238
+ allTargets = false
239
+
240
+ [package.metadata.nx.targets.lint.options]
241
+ allTargets = false
242
+ ```
243
+
244
+ ```sh
245
+ nx run api:run --bin=migrate # one of several binaries
246
+ nx build api --profile=release
247
+ ```
248
+
249
+ `profile` always names a Cargo profile. With `testRunner = "nextest"`, the
250
+ plugin passes it to nextest as `--cargo-profile`, because nextest's own
251
+ `--profile` selects a profile of `.config/nextest.toml`, and to the doctest step
252
+ as `--profile`.
253
+
254
+ `affectedTests = true` on a crate whose workspace does not use selection is an
255
+ error: in a `Cargo.toml` it stops graph creation, and as `--affectedTests=true`
256
+ on the command line it fails the task before cargo runs.
257
+
258
+ The triple is `targetTriple`, not `target`, because `nx run-many -t` and
259
+ `--target` already mean the Nx target. In v1 tests run on the host triple only.
260
+ `affectedTests` is described under [Testing](testing.mara.md#affected-tests).
261
+
262
+ ## Excluding crates
263
+
264
+ To keep crates that are checked in from becoming projects, such as generated
265
+ ones, list their manifests under `exclude` on the plugin's entry. This is Nx's
266
+ own filter for plugin entries, so it sits beside `options`, not inside:
267
+
268
+ ```json
269
+ {
270
+ "plugins": [
271
+ {
272
+ "plugin": "@convesoft/nx-rust",
273
+ "exclude": ["generated/**/*"]
274
+ }
275
+ ]
276
+ }
277
+ ```
278
+
279
+ The crates that `cargo vendor` writes need no entry here: the plugin skips
280
+ them by itself ([Workspaces](workspaces.mara.md#how-workspaces-are-found)).
281
+
282
+ ## All settings
283
+
284
+ | Setting | Plugin options | Workspace table | Crate's table | Described under |
285
+ | ----------------------------- | -------------- | --------------- | ------------- | ---------------------------------------------------------------------------------------------------- |
286
+ | `targetNames` | yes | | | [Target names](#target-names) |
287
+ | `locked` | yes | | | [Caching](caching.mara.md#where-cargo-runs) |
288
+ | `testRunner`, `affectedTests` | yes | yes | | [Testing](testing.mara.md#options) |
289
+ | `featureUnification` | yes | yes | | [Batching and features](execution.mara.md#feature-unification) |
290
+ | `namePrefix` | | yes | | [Per workspace](#per-workspace) |
291
+ | `name`, `artifacts` | | | yes | [Per crate](#per-crate), [napi and wasm artifacts](artifacts.mara.md#which-crates-get-these-targets) |
292
+ | `tags`, `targets` | | yes | yes | [Per crate](#per-crate) |
293
+ | `implicitDependencies` | | yes | yes | [Changing an inferred target](#changing-an-inferred-target) |
294
+ | `envInputs`, `runtimeInputs` | yes | yes | yes | [Caching](caching.mara.md#what-is-in-a-cache-key) |
295
+
296
+ The `project` table under `[workspace.metadata.nx]` takes `name`, `tags` and
297
+ `targets` for the workspace project. A key that this table does not list for a
298
+ place, in a `Cargo.toml` table or in the plugin options, fails graph creation
299
+ with a message that names the file and the key. That also catches a typo such
300
+ as `testrunner`, and a setting in the wrong table, such as `namePrefix` in a
301
+ crate's table.
302
+
303
+ `nx.json` can list the plugin more than once, for example to give two Cargo
304
+ workspaces different options. Each Cargo workspace belongs to one of those
305
+ entries: where the `include` and `exclude` of two entries both let manifests of
306
+ one workspace through, also when one entry gets the root manifest and another a
307
+ member's, graph creation fails and names the workspace and the entries. Give
308
+ the other entries an `exclude` for the workspace's folder, or narrow their
309
+ `include`:
310
+
311
+ ```json
312
+ {
313
+ "plugins": [
314
+ { "plugin": "@convesoft/nx-rust", "exclude": ["rust/**"] },
315
+ {
316
+ "plugin": "@convesoft/nx-rust",
317
+ "include": ["rust/**"],
318
+ "options": { "testRunner": "nextest" }
319
+ }
320
+ ]
321
+ }
322
+ ```
323
+
324
+ Three environment variables change one run and are no settings:
325
+ `NX_RUST_TEST_MODE` chooses the test mode ([Testing](testing.mara.md)),
326
+ `NX_RUST_LOCKED` replaces `locked` ([Continuous integration](ci.mara.md)), and
327
+ `NX_RUST_ALLOW_UNSUPPORTED_NX` lets the plugin run on a newer Nx major than it
328
+ supports ([Setup](setup.mara.md)).
329
+
330
+ ## Requirements
331
+
332
+ :::mara requirement REQ-METADATA-OVERRIDES
333
+ :mid: 01M78FHG7FJ4E8DDDAMXCG8AKF
334
+ :title: Override inferred configuration in Cargo manifests
335
+ :status: accepted
336
+ :satisfies: NEED-CONFIG-IN-CARGO
337
+
338
+ A crate's tags, Nx project name, options of inferred targets and additional targets can be set in `[package.metadata.nx]` of its manifest. Defaults for all members of a workspace can be set in `[workspace.metadata.nx]` of the workspace root manifest. When that manifest defines no crate, the name, tags, settings of inferred targets and additional targets of the workspace's own [[TERM-WORKSPACE-PROJECT]] can be set there as well, apart from the defaults for members. A value set for a crate takes precedence over the workspace default, except that a crate's tags, implicit dependencies and added cache inputs, `fileInputs`, `envInputs` and `runtimeInputs`, are added to those of its workspace. No file other than a Cargo manifest is needed to override what the plugin infers for a crate. Where a project's folder also is a JS project, its `package.json` and `project.json` take precedence over these settings, because Nx applies them after every plugin ([[EVD-NX-PROJECT-MERGE]]). The name Nx takes from them applies instead of the one set here ([[REQ-PROJECT-NAMES]]), and a script or target there with the name of one of the project's targets replaces that target, settings made here included, unless Nx merges the two. Tags from both are kept.
339
+ :::
340
+
341
+ :::mara requirement REQ-TARGET-NAMES
342
+ :mid: 01M78FHG7FP3Z0DWAES110WHYT
343
+ :title: Use Nx target names by default and allow renaming
344
+ :status: accepted
345
+ :satisfies: NEED-UNIFORM-COMMANDS
346
+
347
+ Inferred targets have, by default, the names that Nx projects conventionally use for the same job, so that `lint`, `test` and `build` cover Rust crates and JS projects alike. The name of every inferred target can be changed through the plugin's options.
348
+ :::
349
+
350
+ :::mara requirement REQ-UNKNOWN-OPTIONS
351
+ :mid: 01M7A93PSWRTX4KDZVJ0ACW62Y
352
+ :title: Run with a warning when a task gets an option the executor does not know
353
+ :status: accepted
354
+ :satisfies: NEED-CLEAR-FAILURES
355
+ :mitigates: RISK-TARGET-DEFAULTS
356
+
357
+ When a task of a target that runs one of the plugin's executors receives an option that its executor does not know, or one that its executor knows and the task's target does not take, from a `targetDefaults` entry in `nx.json`, a `project.json`, a `package.json` or the command line, the task runs as it would without that option, and the option fails no task. The task's own output carries one warning line per such option that names the option and the task and says that the option was passed on the command line, when that is certain, or else that it comes from the workspace's configuration, with the command that shows where. On a `run` task, the arguments after `--` on the command line go to its binary instead ([[DES-TARGET-COMMANDS]]).
358
+ :::
359
+
360
+ :::mara requirement REQ-UNKNOWN-METADATA-OPTIONS
361
+ :mid: 01M7A93PSWEY0RVZ0WCQM20EFG
362
+ :title: Reject target options in Cargo metadata that the executor does not know
363
+ :status: accepted
364
+ :satisfies: NEED-CLEAR-FAILURES
365
+
366
+ A key under `options` or under a configuration in `configurations` of a `targets.<name>` table in `[package.metadata.nx]`, `[workspace.metadata.nx]` or its `project` table, where the target runs one of the plugin's executors and that executor has no option of that name, fails graph creation with a message that names the manifest, the target, the configuration if any, and the key. So does, on an inferred target, a key that the executor has but the option reference does not give that target, with a message that says that the target does not take it, and `pluginVersion` on any such target, with a message that says that the plugin sets that option itself, because a value set by hand would replace the plugin's version in the cache key ([[GOAL-TRUSTED-CACHE]]).
367
+ :::
368
+
369
+ ## Design
370
+
371
+ :::mara design DES-METADATA-TABLES
372
+ :mid: 01M78FHG7FX2K81MEQEY7YQHTN
373
+ :title: The nx metadata tables
374
+ :status: accepted
375
+ :satisfies: REQ-METADATA-OVERRIDES
376
+
377
+ Overrides are read from the `metadata` values in the `cargo metadata` report ([[DES-METADATA-REPORT]]): `[package.metadata.nx]` for a crate and `[workspace.metadata.nx]` for a workspace ([[ADR-METADATA-KEY]]).
378
+
379
+ | Key | Table | Meaning |
380
+ | ----------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
381
+ | `name` | package | Nx project name. The Cargo package name is unchanged. |
382
+ | `tags` | package, workspace | Nx tags. A crate has its workspace's tags and its own. |
383
+ | `targets.<name>` | package, workspace | A table shaped like an Nx target. For an inferred target it overrides that target's settings, such as `options`. For any other name it defines an extra target. |
384
+ | `testRunner`, `affectedTests` | workspace | The test settings in [[DES-TEST-RUN]]. |
385
+ | `featureUnification` | workspace | The feature-unification strategy of [[DES-UNIFICATION]]. |
386
+ | `namePrefix` | workspace | Put in front of the package name of each member to give its project name ([[DES-PROJECT-GRAPH]]). |
387
+ | `artifacts` | package | The kinds of artifact the crate produces, in place of the inference of [[DES-ARTIFACT-STEPS]]. |
388
+ | `implicitDependencies` | package, workspace | Projects the crate depends on beyond its Cargo dependencies, as Nx's key of that name. Additions only; they add up. |
389
+ | `envInputs`, `runtimeInputs` | package, workspace | Environment variables and commands added to the crate's cache key ([[DES-INPUTS]]). They add up. |
390
+ | `fileInputs` | package, workspace | Glob patterns of files outside the crate that it reads, relative to the manifest's folder. They add up ([[REQ-BUILD-SCRIPT-INPUTS]]). |
391
+ | `project` | workspace | The [[TERM-WORKSPACE-PROJECT]] itself: its own `name`, `tags` and `targets.<name>`, as in a package table. An error in a root manifest that defines a crate. |
392
+
393
+ In the `project` table, `name` replaces the default name ([[DES-PROJECT-GRAPH]]), `tags` are added to the workspace's tags, and `targets.<name>` overrides a target of the workspace project or adds one. The workspace table's own `targets.<name>` do not reach the workspace project.
394
+
395
+ For a setting that both tables can hold, the crate's value wins over the workspace default; only tags, `implicitDependencies`, `fileInputs`, `envInputs` and `runtimeInputs` add up. Key names use the spelling of the matching Nx option, so one name works in `Cargo.toml`, in `nx.json` and on the command line. Where each setting can be set, the plugin options, the merge rules and the handling of unknown keys are in [[DES-PLUGIN-OPTIONS]].
396
+
397
+ The plugin puts these values on the project it returns. Where the project's folder also is a JS project, Nx applies `package.json` and `project.json` after them, with the effects [[REQ-METADATA-OVERRIDES]] states ([[EVD-NX-PROJECT-MERGE]]).
398
+ :::
399
+
400
+ :::mara design DES-PLUGIN-OPTIONS
401
+ :mid: 01M78FHG7F0KD92ZFBVS6GS65H
402
+ :title: Option reference
403
+ :status: accepted
404
+ :satisfies: REQ-TARGET-NAMES
405
+ :satisfies: REQ-METADATA-OVERRIDES
406
+
407
+ The settings of milestone 0.1, where each can be set, and its default. The plugin options are the `options` of the plugin's entry in `nx.json`, for the manifests that entry receives ([[DES-DISCOVERY]]); the workspace table is `[workspace.metadata.nx]` and the package table `[package.metadata.nx]` ([[DES-METADATA-TABLES]]). Later features add their rows when they are specified, among them the strict per-crate build check of the `hakari` strategy ([[DES-UNIFICATION]]) and rules that widen the selection of tests for non-Rust files ([[DES-TEST-RUN]]). The JS flavour of `wasm-build` is an option of that target, `wasmTarget`, in the table of options below.
408
+
409
+ | Setting | Plugin options | Workspace table | Package table | Default | Meaning |
410
+ | ---------------------- | -------------- | --------------- | ------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
411
+ | `targetNames` | yes | no | no | none: the names in [[DES-TARGETS]] | Map from the default name of an inferred target to the name to use, such as `{ "lint": "clippy" }`. Every inferred target can be renamed, the artifact targets and those of the workspace project included, apart from `nx-release-publish` ([[DES-RELEASE]]). |
412
+ | `locked` | yes | no | no | `false` | Locked mode for the plugin's commands, as [[DES-INVOCATION]] defines it. |
413
+ | `testRunner` | yes | yes | no | `cargo` | `cargo` or `nextest` ([[DES-TEST-RUN]]). |
414
+ | `affectedTests` | yes | yes | no | `false` | The workspace uses selection of affected tests ([[DES-TEST-MODE]]). A crate opts out through the target option of the same name. |
415
+ | `featureUnification` | yes | yes | no | `hakari` where the workspace has a cargo-hakari configuration, `workspace-build` elsewhere | `hakari`, `cargo` or `workspace-build` ([[DES-UNIFICATION]]). A workspace that fails a check of the `hakari` strategy uses `workspace-build`, with a warning, also where this setting says `hakari`. |
416
+ | `namePrefix` | no | yes | no | none | Put in front of the package name of each member, as it is and without a separator, to give the project name. A crate that sets `name` gets no prefix, and neither does the workspace project of a root manifest without a `[package]` table. A root manifest's own crate is a member and gets it ([[DES-PROJECT-GRAPH]]). |
417
+ | `name` | no | no | yes | the package name | Nx project name, used as it is ([[DES-PROJECT-GRAPH]]). |
418
+ | `artifacts` | no | no | yes | inferred | The kinds of artifact the crate produces, `napi` and `wasm`, in place of what the plugin infers. An empty list means none ([[DES-ARTIFACT-STEPS]]). |
419
+ | `tags` | no | yes | yes | none | Nx tags. |
420
+ | `targets.<name>` | no | yes | yes | none | A table shaped like an Nx target, merged as described below. |
421
+ | `implicitDependencies` | no | yes | yes | none | Projects the crate depends on in addition to its Cargo dependencies. |
422
+ | `envInputs` | yes | yes | yes | none | Environment variables added to the cache key of the crate's cached targets ([[DES-INPUTS]]). |
423
+ | `runtimeInputs` | yes | yes | yes | none | Commands whose output is added to that cache key ([[DES-INPUTS]]). |
424
+ | `fileInputs` | no | yes | yes | none | Glob patterns of files outside the crate's folder that it reads, resolved against the folder of the manifest that holds them and added to its cache key ([[REQ-BUILD-SCRIPT-INPUTS]], [[DES-INPUTS]]). |
425
+
426
+ The workspace table also holds the `project` sub-table for the [[TERM-WORKSPACE-PROJECT]] ([[DES-METADATA-TABLES]]). `exclude`, beside `options` on the plugin's entry, is Nx's own filter for plugin entries, not an option of the plugin ([[DES-DISCOVERY]]). A standalone crate takes the workspace settings from a `[workspace.metadata.nx]` table in its own manifest, which Cargo reports for a workspace of one ([[EVD-CARGO-NX-TABLES]]).
427
+
428
+ Options of inferred targets are set under `targets.<name>.options`, in a configuration of the target, or on the command line. Each comes from a flag of the cargo command, so the command passes only what the options ask for ([[DES-INVOCATION]]); `wasmTarget` comes from a flag of the `wasm-bindgen` CLI ([[DES-WASM]]). On a target that the table does not list for it, an option is left out of the command with a warning line ([[DES-UNKNOWN-OPTIONS]]):
429
+
430
+ | Option | Flag | Targets | Default |
431
+ | ---------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
432
+ | `features` | `--features` | `build`, `check`, `lint`, `test`, `bench`, `run`, `napi-build`, `wasm-build`, `doc` and `coverage-baseline` ([[DES-BASELINE]]) | none |
433
+ | `allFeatures` | `--all-features` | the same; the configuration for all features sets it ([[DES-FEATURE-SETS]]) | `false` |
434
+ | `noDefaultFeatures` | `--no-default-features` | the same | `false` |
435
+ | `profile` | `--profile`, or `--cargo-profile` for `cargo nextest run` | the same | none: Cargo's default profile for the command |
436
+ | `targetTriple` | `--target` | the same, apart from `test`, `coverage-baseline` and `napi-build`, which run and build for the host triple only in v1 ([[ADR-V1-SCOPE]]), and `wasm-build`, which builds for `wasm32-unknown-unknown` ([[DES-WASM]]) | none: the triple Cargo builds for without it |
437
+ | `allTargets` | `--all-targets` | `check`, `lint` ([[DES-TARGET-COMMANDS]]) | `true` |
438
+ | `noDeps` | `--no-deps` | `doc` of the workspace project ([[DES-WORKSPACE-TARGETS]]) | `true` |
439
+ | `bin` | `--bin` | `run` ([[DES-TARGET-COMMANDS]]) | none: `default-run` or the only binary, as Cargo chooses |
440
+ | `args` | the binary's arguments, after `--`: a string split into words as [[DES-TARGET-COMMANDS]] says | `run` ([[DES-TARGET-COMMANDS]]) | none |
441
+ | `test` | `--test`, for `cargo test` and `cargo nextest run` alike | `test` ([[DES-TEST-RUN]], "One test target") | none: every test of the crate, its doctests included |
442
+ | `affectedTests` | none | `test` | the workspace's `affectedTests` |
443
+ | `wasmTarget` | none of cargo's: the `--target` of the `wasm-bindgen` CLI, `bundler`, `web` or `nodejs` ([[DES-WASM]]) | `wasm-build` | `bundler`, which the inferred target sets |
444
+ | `fullCollectThreshold` | none: the commits that the oldest collection may lie behind `HEAD` before a full collection replaces `--diff`; | `coverage-baseline` ([[DES-BASELINE]]) | 100, which the inferred target sets |
445
+ | `fullCollect` | none: always a full collection, without `cargo affected status`; | `coverage-baseline` ([[DES-BASELINE]]) | `false` |
446
+ | `diffOnly` | none: never a full collection on the target's own choice; | `coverage-baseline` ([[DES-BASELINE]]) | `false` |
447
+ | `separateBuildDir` | none: `CARGO_BUILD_BUILD_DIR` for the collection; | `coverage-baseline` ([[DES-BASELINE]]) | `false` |
448
+ | `pluginVersion` | none | every target the plugin infers, where Nx has no node for the plugin's package | the plugin's version |
449
+
450
+ `pluginVersion` is set by the plugin and not meant to be set by hand. It is the one target option that the plugin sets itself and that comes from no flag of cargo or of the `wasm-bindgen` CLI: it carries the plugin's version into each task's key where Nx has no npm node for the plugin ([[DES-INPUTS]]), and each executor's schema declares it ([[DES-UNKNOWN-OPTIONS]]). A `targets.<name>` table in Cargo metadata that sets it fails graph creation, because a value set by hand would replace the plugin's version in the key ([[REQ-UNKNOWN-METADATA-OPTIONS]], [[GOAL-TRUSTED-CACHE]]).
451
+
452
+ A `pluginVersion` that the plugin did not set is an error wherever it comes from, never a warning and never ignored ([[GOAL-TRUSTED-CACHE]]). Nx lays `targetDefaults`, `project.json` and `package.json` over the plugin's targets (**Precedence**), and a value that covers every target of a task's project and of the projects whose configuration its key holds, as an entry keyed by the plugin's executors does, keeps the key when the plugin's version changes ([[EVD-NX-24-PLUGIN-VERSION]]). So graph creation fails, once Nx has merged these files, where an inferred target that still runs the plugin's executor has among its options a `pluginVersion` other than the one the plugin gave it, also where the plugin gave none because Nx has a node for its package, or has one in any of its configurations. The message lists the targets by project under the place the value comes from: the `project.json` or `package.json` in the project's folder, or the `targetDefaults` entry and element, as the layers that [[DES-TARGET-DEFAULT-GUARD]] rebuilds with Nx's own code show it (**Which layer**). Where those layers do not show the value, as when another plugin sets it, the message gives for each target the `nx show target` command whose `sourceMap` names the file. A value equal to the plugin's own cannot be told from it and fails once the plugin's version changes. Given for one run only, on the command line or by a task that forwards its options, the value reaches no configuration that graph creation sees. Nx then hashes it beside the target's own, so it takes the place of nothing, but the plugin did not set it either: the executor fails the task before cargo runs where the run's `pluginVersion` differs from the target's. Words after `--` that `run` passes to its binary are no option and fail nothing ([[DES-UNKNOWN-OPTIONS]]).
453
+
454
+ `profile` names a Cargo profile. With the nextest runner, `test` passes it to `cargo nextest run` as `--cargo-profile`, because nextest takes `--profile` for a profile of its own configuration, and to the doctest step, `cargo test --doc`, as `--profile` ([[DES-TEST-RUN]], [[EVD-NEXTEST-CARGO-FLAGS]]). nextest takes the other flags of the table as cargo does.
455
+
456
+ `test` names a test target of the crate as cargo's `--test` takes it, a name or a glob pattern that cargo matches against the crate's test targets, and the task then runs only what that flag selects ([[DES-TEST-RUN]], "One test target"). It takes one string, not a list, and no other target selector of cargo's is an option, such as `--lib`, `--bins`, `--example` or a filter of test names: a crate that runs several such targets on their own gives `test` one configuration per target, such as `[package.metadata.nx.targets.test.configurations.performance]` with `test = "performance"`, which `nx test <crate> -c performance` runs. The name follows the flag, as `bin` does for `run`; Nx 24.0.6 has no `--test` flag of its own on `nx run`, `nx run-many` or `nx affected`, so `nx test <crate> --test=<name>` reaches the task. Nx reads a value of digits only as a number there, as it does for `--args` of `run` ([[DES-TARGET-COMMANDS]]), which the schema's string type refuses before the executor runs, so such a name is set as a string in a configuration or a target table. The control plane decided this in nxr-k5y74e on 22 November 2026, from the maintainer's wording for the issue, to keep the option surface minimal and orthogonal, and from [[EVD-CARGO-TEST-TARGET-SELECTOR]]; to undo it, remove the option.
457
+
458
+ `affectedTests = false` as an option of `test` makes the task run the full suite in a workspace that uses selection, or, beside the `test` option, the target that it names. It is how a crate opts out of selection, `[package.metadata.nx.targets.test.options] affectedTests = false`, and what `--affectedTests=false` passes for one run ([[DES-TEST-RUN]]). In a workspace without the `affectedTests` setting, the option set to `true` in stored configuration, which is the plugin options, the workspace and package tables, or a target configuration that Nx holds in the graph, fails graph creation. Given as `--affectedTests=true` on the command line, which graph creation never sees, it makes the executor fail the task with the same message before it runs cargo; Nx hands such an override to the executor, also in a batch ([[EVD-NX-24-OPTION-SEMANTICS]]). The triple option is not called `target`, because `nx run`, `nx run-many` and `nx affected` take `--target` and `-t` themselves, so an option of that name could not be given on the command line. `--verbose` is Nx's own flag and no option of the plugin's targets; Nx adds `verbose: true` to the options of a single task only where the executor's schema declares `verbose` or sets `additionalProperties: true` ([[EVD-NX-24-OPTION-SEMANTICS]]).
459
+
460
+ Three environment variables act on a run and are no options: `NX_RUST_TEST_MODE` ([[DES-TEST-MODE]]), `NX_RUST_LOCKED`, which replaces `locked` for one run ([[DES-INVOCATION]]), and `NX_RUST_ALLOW_UNSUPPORTED_NX` ([[DES-DIAGNOSTICS]]).
461
+
462
+ **Precedence.** A setting takes its default, then the value in the plugin options, then the one in the workspace table, then the one in the package table, each replacing the one before. `tags`, `implicitDependencies`, `fileInputs`, `envInputs` and `runtimeInputs` add up instead: a crate has the values of every level, and no level removes what another set. This order is the plugin's own, applied to the projects it returns. Nx then applies `targetDefaults` from `nx.json`, and after them the `project.json` and `package.json` in the project's folder, so a value that either sets for a target, an option such as `features` included, replaces the one that the plugin gave it ([[EVD-NX-TARGET-DEFAULTS]], [[EVD-NX-PROJECT-MERGE]]).
463
+
464
+ **Target names.** When `targetNames` gives two inferred targets of one project the same name, graph creation fails with an error that names the project, the two inferred targets and the resulting name, and says to change `targetNames`. Neither target replaces the other, because [[DES-TARGETS]] gives the project both. A key of `targetNames` has to be the default name of an inferred target that this version of the plugin knows, whether or not a project of the repository has that target; any other key fails graph creation, as an unknown key does (**Unknown keys**), with a message that names the key and lists the names that can be renamed. So does the key `nx-release-publish`, with a message that says that Nx release runs the publish target only under that name ([[DES-RELEASE]]). A `targetNames` that is no object, or a value in it that is no non-empty string, fails graph creation with a message that names the key. Later milestones add the names of the targets they add. The rule for a `targets.<name>` table in Cargo metadata stands: under the name of an inferred target, which is its name after `targetNames`, it overrides that target, and under any other name it defines an extra target ([[DES-METADATA-TABLES]]).
465
+
466
+ **Several entries.** Each Cargo workspace belongs to one entry of the plugin in `nx.json`, whose options alone apply to its projects. When the `include` and `exclude` of two or more entries let manifests of one workspace through, whether the same manifests or different ones, such as the root manifest to one entry and a member's to another, graph creation fails with a message that names the workspace, the entries by their place in the `plugins` of `nx.json` with a manifest of the workspace that each receives, and says to give all but one of them an `exclude` that leaves out the workspace, or to narrow their `include`. The manifests of a workspace are its root manifest and those of its members, as its report gives them; a manifest that no report claims, such as that of a crate that `cargo vendor` wrote and that no workspace enrols as a member ([[DES-DISCOVERY]]), belongs to no workspace. Without the rule, Nx would merge the projects that two entries create for one folder key by key, so that a project's targets and inputs would mix the options of both in an order that depends on Nx, and join the lists in their metadata, so that each item stood there once per entry. The settings that hold for a whole workspace, `testRunner`, `affectedTests` and `featureUnification`, thereby come from one entry for each workspace. The maintainer chose this rule on 15 November 2026, over letting the first entry by its place create the projects and over requiring the entries to agree on every option that changes a project, and confirmed the same day that it refuses entries that split a workspace as well.
467
+
468
+ An entry learns of the others from the `plugins` of `nx.json` in the context Nx passes to its `createNodes`, which holds every entry, also under plugin isolation. It works out the manifests that each entry receives with Nx's own two steps for choosing an entry's files, called in the installed Nx: `globPluginFiles`, through `retrieveProjectConfigurationPaths` with that entry alone, which globs a narrow `include` natively and keeps the files that the plugin's pattern `**/Cargo.toml` matches, and then `findMatchingConfigFiles` with the entry's `include` and `exclude` ([[EVD-NX-24-ENTRY-CONTEXT]]). So it gets for each entry the files that Nx hands it, and compares them with the manifests of the workspaces that it discovered itself. An entry that receives a manifest of a workspace discovers that workspace, so every entry that takes part finds the others and fails with the same message, whatever the order in which Nx runs the entries and in whichever process; Nx prints the error of each entry that fails. No part of that choice is written anew, so the patterns mean what they mean to Nx; what can still differ is the moment, where a `Cargo.toml` is added or removed between Nx's listing and the entry's. Each entry therefore checks that one entry gets exactly the manifests that Nx handed it. Where none does, and where Nx's steps fail for an entry, as for an `include` or `exclude` that is no list of patterns, graph creation fails with a message that names what could not be determined, instead of assuming that the entries do not overlap ([[GOAL-TRUSTED-CACHE]]). Where a step of a later Nx could not be called and had to be approximated, the approximation has to give every entry at least the files that Nx hands it: a superset can only refuse entries that do not overlap, which the user resolves by narrowing a pattern, while a subset can miss an overlap and give a project the mixed options and doubled lists that the rule prevents. `findMatchingConfigFiles` applied to every `Cargo.toml` of the workspace context, which the plugin used before it called `globPluginFiles`, is such a superset in Nx 24.0.6: it refused an entry whose `include` named `rust/[[:upper:]]argo.toml` beside an entry for `rust/`, although Nx's native glob does not match that pattern. Before, the check that some entry got all the manifests that Nx handed this one could not misfire either way: the superset always held them for the entry itself, and where an earlier entry's superset held them as well, that entry counted as a receiver of this entry's workspaces, so the entries were refused, while an entry without a workspace needs no place. The entries that the plugin takes for its own are those that name its package or a path to its entry point; another installation of the plugin, registered under another name, is another plugin to it ([[DES-OUTPUTS]], "Two mechanisms").
469
+
470
+ **Targets.** A `targets.<name>` table is merged over the target the plugin infers under that name by Nx's own rule for laying one configuration of a target over another, in the order of precedence; the plugin calls Nx's `mergeTargetConfigurations` for it ([[EVD-NX-24-OPTION-SEMANTICS]]). A field the table sets replaces the inferred one, `options` and `configurations` are merged key by key, and a list replaces the inferred list unless it contains `"..."`, which stands for the inferred entries at that place. For a name under which the plugin infers no target, the table defines an extra target. A table in the workspace table under the name, after `targetNames`, of a target that the plugin infers applies only to the members that have that target and creates nothing on the others; under any other name it defines an extra target on every member. A field that an Nx target has, such as `options`, `outputs` or `continuous`, has to have the type that Nx's project schema gives it; another type fails graph creation with a message that names the manifest, the target and the field. Two more cases fail graph creation with a message that names the manifest, the target and the field: `inputs` without `"..."` on an inferred target, because it would drop inferred inputs such as the toolchain, the environment and the dependencies' files from the key; and a different `executor`, or a `command`, on an inferred target, which Nx would treat as another target and use in place of the inferred one; the inferred executor repeated is accepted. Another command runs as an extra target under another name. A negated pattern beside `"..."`, such as `"!{projectRoot}/docs/**"`, takes files out of the inferred inputs. This is allowed, as the repository's statement that the target does not read those files: a change to such a file changes no key, so where a macro, build script or test still reads it, Nx restores a result produced with the file's old content ([[EVD-NX-24-OPTION-SEMANTICS]]).
471
+
472
+ **Implicit dependencies.** Each entry of `implicitDependencies` adds an edge from the crate to the project it names, which may be a project of another plugin. The key only adds, so an entry starting with `!` fails graph creation, whatever it names.
473
+
474
+ **Added inputs.** `envInputs` and `runtimeInputs` of all three levels, and `fileInputs` of the two tables, go into the crate's own named input, which its dependents hash through `^` inputs ([[DES-INPUTS]]). A variable or command added for one crate therefore also reaches the keys of the crates that depend on it, in other workspaces too. The plugin options hold no `fileInputs`, because a pattern is resolved against the folder of the manifest that holds it ([[REQ-BUILD-SCRIPT-INPUTS]]). The names pair with Nx's input kinds `env` and `runtime`: a plain `env` would read as the option of `nx:run-commands` that sets variables for a command, and an extra target with a `command` is such a target ([[EVD-NX-24-OPTION-SEMANTICS]]).
475
+
476
+ **Unknown keys.** A key at the top level of a package table, of a workspace table or of its `project` sub-table, or in the plugin options, that this reference does not give for that place fails graph creation with a message that names the file, the manifest or `nx.json`, and the key. A setting given only for another place counts as unknown there, such as `namePrefix` in a package table. So do the other keys of an Nx project configuration, such as `root`, `sourceRoot`, `projectType`, `namedInputs` and `metadata`, and `release`: release configuration stays in `nx.json` and `project.json`, and the plugin sets each crate's version actions itself ([[DES-RELEASE]]). A key under a target's `options` or one of its configurations that the target's executor does not know fails graph creation as well ([[REQ-UNKNOWN-METADATA-OPTIONS]]).
477
+ :::
478
+
479
+ :::mara design DES-UNKNOWN-OPTIONS
480
+ :mid: 01M7A93PSWW34M2MF0BAD1S6PJ
481
+ :title: Options the executor does not know
482
+ :status: accepted
483
+ :satisfies: REQ-UNKNOWN-OPTIONS
484
+ :satisfies: REQ-UNKNOWN-METADATA-OPTIONS
485
+
486
+ The schema of each of the plugin's executors declares each target option with its type and leaves `additionalProperties` unset, so that Nx passes any other option on to the executor. Because no schema declares `verbose` or sets `additionalProperties: true`, Nx's own `--verbose` adds no option to a task and draws no warning about one ([[EVD-NX-24-OPTION-SEMANTICS]]); it makes each task print its cargo command ([[DES-INVOCATION]], "Printing the command"). Nx checks options against the schema before the batch implementation runs, and with `additionalProperties: false` one unknown option fails every task that Nx hands to the batch implementation, in every group, with a message that names neither the option nor a task ([[EVD-NX-OPTION-VALIDATION]], [[ADR-UNKNOWN-OPTIONS]]).
487
+
488
+ When a task starts, the executor compares the keys of the task's options with the options its schema declares. It leaves every other key out of the cargo command, so that such a key splits no group ([[TERM-GROUP]]), and writes one warning line per such key at the top of the task's own output. A key that the schema declares but that the option reference of [[DES-PLUGIN-OPTIONS]] does not give the task's target, such as `targetTriple` on `test` or `allTargets` on `build`, is treated the same way, because one schema serves every target of the cargo executor; its line says that the target does not take the option. The batch implementation and the implementation for a single task, which Nx uses with `--batch=false` and which is the only one that the executor of `run` has, both do this.
489
+
490
+ **Source.** Nx assembles a task's options from the plugin's target, `targetDefaults`, `package.json`, `project.json`, configurations, options forwarded from other tasks and the command line, and records which source gave a value only in its own source map ([[EVD-NX-OPTION-VALIDATION]]). The executor therefore does not work out the file or the `targetDefaults` entry, and the line takes one of two forms:
491
+
492
+ - When the option is among the command's own flags, as the next paragraph defines, the line says so and what to do, for example ``api:test: ignoring option `coverage`, passed on the command line. Remove it, or check its spelling.`` For an option that the target does not take, the line says to remove it, and for positional words, to remove them. On `run`, whose binary takes the arguments after `--` and the value of `args`, the line for an unknown option or for positional words also says to pass them to the binary after `--` or with `--args`. No other target passes arguments on: `test` has no option for arguments of the test binary, so its line for positional words only says to remove them.
493
+ - In every other case, the line says that the option comes from the workspace's configuration and names the command that shows Nx's own record, with the two fixes for a `targetDefaults` entry, for example ``api:test: ignoring option `passWithNoTests`, which the cargo executor does not know. It comes from the workspace's configuration: run `nx show target api:test --json` and look under `sourceMap` for the file and entry. If it is a `targetDefaults` entry in nx.json, add a `filter` to it or add an empty entry keyed by "@convesoft/nx-rust:cargo".`` The empty entry is keyed by the target's executor, which Nx then chooses for that executor's targets instead of entries keyed by a target name ([[EVD-NX-TARGET-DEFAULTS]]).
494
+
495
+ **Command line.** An option counts as passed on the command line only when three conditions hold. First, the task that the executor's context gives for the task holds the option among its overrides, under its name and with the value that this invocation received. Second, that task's own `__overrides_unparsed__` lists the option as `--<name>`, `--<name>=<value>`, `--no-<name>` or, for a one-letter name, `-<name>`. A word after a second `--` does not count: Nx keeps it as positional data under `_`, and the option keeps its configured value. Third, the same flag is among the arguments of the `nx` command, which the plugin's `preTasksExecution` hook records. Nx fills `__overrides_unparsed__` with the command's arguments for a task that the command started and for a dependency reached with `params: "forward"`. It leaves the list empty for every other dependency, also one that gets the dependent's options through `options: "forward"`. In every other case, also when the task, the list or the record is missing, the line has the second form. Positional words, which Nx hands a task as the option `_`, count as passed on the command line under the same three conditions, with the words in place of a flag: the overrides hold the same words, the task's own list parsed as Nx parses it gives them, and each word of that list that can be positional is among the recorded arguments.
496
+
497
+ **Started in code.** Devkit's `runExecutor` lets another executor start the target with options of its own while passing its own context on. The conditions above are then evaluated as they stand, against the task that the caller's task graph holds for the target, if it holds one, and with the options that Nx merged for the invocation. The form of the line, and what `run` forwards, can therefore differ from what the user typed on the command line. The plugin promises no particular result for such an invocation, only that an option its executor does not know is still ignored with a line, and that no task fails because of it ([[EVD-NX-OPTION-VALIDATION]]).
498
+
499
+ **Record.** The hook receives the command's arguments, `--` included, and records them on every command in an environment variable. Nx carries an assignment to `process.env` in that hook to the `nx` process, whose tasks inherit it, with the daemon and without. The record is in no task's cache key and is the same for every task of a command, so it splits no group. A dependency or continuous task inherits it as well, which is why both uses here also require the task's own `__overrides_unparsed__`. A record longer than 64 KiB is left empty and counts as missing, because Linux starts no process with an environment variable longer than 128 KiB, so a longer one would fail every task of the command.
500
+
501
+ **run.** The value of the `args` option and the arguments after `--` on the command line go to the binary ([[DES-TARGET-COMMANDS]]). The executor takes none of the arguments after `--` as an option and writes no line for them. Nx hands a task the arguments after `--` as options, in the same form as flags given without `--`, and when the command has `--` it hands over only those ([[EVD-NX-OPTION-VALIDATION]]). The executor therefore passes arguments after `--` to the binary only when three conditions hold. The record has `--`. The task's own `__overrides_unparsed__` equals the arguments after it. The invocation's options hold every option that Nx parsed from those arguments and that is not one of `run`'s own, with the same value. That holds for a task that the command started and for a dependency reached with `params: "forward"`. A dependency or continuous task reached with `params: "ignore"` has an empty list, so its binary gets none of them. For a target started in code, see **Started in code**. When the record is missing, the executor treats the command as having no `--`. Any other unknown option of a `run` task gets a line, as on every other target.
502
+
503
+ **Cache.** `run` is not cached. For other targets, a cache hit replays the output stored with the result, its lines included. The ignored option stays in the task's cache key: Nx hashes the `options` and `configurations` of every target of the project, and `nx.json`, into each task of the project, and the command line into each task of a run. A run that ignores the option therefore does the same work under its own key.
504
+
505
+ Known limitation: Nx checks the types of the declared options in the same place. A target default or `project.json` that gives a declared option a value of the wrong type, such as `profile: 1`, fails every task that Nx hands to the batch implementation with it, in every group, with Nx's own message, an unhandled `SchemaError` that names no option. With `--batch=false`, and on `run`, only the tasks that receive the value fail, each with Nx's message `Property '<option>' does not match the schema`. The types stay in the schema, because Nx converts values from the command line by them.
506
+
507
+ Options in the plugin's own tables are checked when the graph is created. While reading `[package.metadata.nx]`, `[workspace.metadata.nx]` and its `project` table ([[DES-METADATA-TABLES]]), the plugin compares the keys under `options` and under each configuration of each `targets.<name>` table whose target runs one of its executors with the options that executor declares. An unknown key stops graph creation with a message that names the manifest, the target, the configuration if any, and the key, as [[REQ-DIAGNOSTICS]] prescribes for problems found at that point. On an inferred target, so does a key that the executor declares but the option reference of [[DES-PLUGIN-OPTIONS]] does not give that target, such as `targetTriple` on `test`, with a message that says that the target does not take it.
508
+ :::