@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.
- package/PLUGIN.md +106 -0
- package/README.md +8 -4
- package/docs/artifacts.mara.md +374 -0
- package/docs/caching.mara.md +999 -0
- package/docs/ci.mara.md +308 -0
- package/docs/configuration.mara.md +508 -0
- package/docs/decisions.mara.md +3267 -0
- package/docs/execution.mara.md +533 -0
- package/docs/index.mara.md +51 -0
- package/docs/product.mara.md +366 -0
- package/docs/release.mara.md +493 -0
- package/docs/setup.mara.md +486 -0
- package/docs/targets.mara.md +704 -0
- package/docs/testing.mara.md +431 -0
- package/docs/verification.mara.md +465 -0
- package/docs/workspaces.mara.md +445 -0
- package/package.json +1 -1
- package/src/cargo/build-settings.d.ts +8 -1
- package/src/cargo/build-settings.js +21 -11
- package/src/cargo/build-settings.js.map +1 -1
- package/src/cargo/metadata.d.ts +2 -0
- package/src/cargo/metadata.js.map +1 -1
- package/src/cargo/redirections.d.ts +4 -1
- package/src/cargo/redirections.js +7 -2
- package/src/cargo/redirections.js.map +1 -1
- package/src/cargo/warnings-setting.d.ts +24 -0
- package/src/cargo/warnings-setting.js +81 -0
- package/src/cargo/warnings-setting.js.map +1 -0
- package/src/executors/cargo/schema.json +4 -0
- package/src/executors/cargo-output.d.ts +8 -2
- package/src/executors/cargo-output.js +20 -6
- package/src/executors/cargo-output.js.map +1 -1
- package/src/executors/command.d.ts +13 -0
- package/src/executors/command.js +37 -7
- package/src/executors/command.js.map +1 -1
- package/src/executors/denied-warnings.d.ts +99 -0
- package/src/executors/denied-warnings.js +188 -0
- package/src/executors/denied-warnings.js.map +1 -0
- package/src/executors/group-run.d.ts +1 -1
- package/src/executors/group-run.js +23 -13
- package/src/executors/group-run.js.map +1 -1
- package/src/executors/groups.d.ts +7 -2
- package/src/executors/groups.js +22 -3
- package/src/executors/groups.js.map +1 -1
- package/src/executors/nextest.d.ts +6 -2
- package/src/executors/nextest.js +12 -6
- package/src/executors/nextest.js.map +1 -1
- package/src/executors/task-guards.js +7 -2
- package/src/executors/task-guards.js.map +1 -1
- package/src/executors/task.js +10 -3
- package/src/executors/task.js.map +1 -1
- package/src/executors/test-mode.d.ts +4 -1
- package/src/executors/test-mode.js +7 -1
- package/src/executors/test-mode.js.map +1 -1
- package/src/executors/test-steps.d.ts +20 -8
- package/src/executors/test-steps.js +45 -14
- package/src/executors/test-steps.js.map +1 -1
- package/src/graph/caching.js +5 -0
- package/src/graph/caching.js.map +1 -1
- package/src/graph/clippy-input.d.ts +53 -0
- package/src/graph/clippy-input.js +107 -0
- package/src/graph/clippy-input.js.map +1 -0
- package/src/graph/collisions.d.ts +7 -0
- package/src/graph/collisions.js.map +1 -1
- package/src/graph/discovery.d.ts +15 -0
- package/src/graph/discovery.js +5 -0
- package/src/graph/discovery.js.map +1 -1
- package/src/graph/inputs.d.ts +3 -1
- package/src/graph/inputs.js +11 -1
- package/src/graph/inputs.js.map +1 -1
- package/src/graph/projects.js +13 -2
- package/src/graph/projects.js.map +1 -1
- package/src/graph/rustfmt-config.d.ts +42 -0
- package/src/graph/rustfmt-config.js +173 -0
- package/src/graph/rustfmt-config.js.map +1 -0
- package/src/graph/targets.d.ts +11 -7
- package/src/graph/targets.js +12 -8
- package/src/graph/targets.js.map +1 -1
|
@@ -0,0 +1,445 @@
|
|
|
1
|
+
# Workspaces and projects
|
|
2
|
+
|
|
3
|
+
nx-rust finds every Cargo workspace in the repository and turns each member
|
|
4
|
+
crate into an Nx project. You do not list crates anywhere: the plugin asks
|
|
5
|
+
Cargo.
|
|
6
|
+
|
|
7
|
+
```text
|
|
8
|
+
.
|
|
9
|
+
├── nx.json
|
|
10
|
+
├── apps/web/ JS app -> project "web"
|
|
11
|
+
├── rust/ a Cargo workspace -> workspace project "rust"
|
|
12
|
+
│ ├── Cargo.toml [workspace] members = ["crates/*"]
|
|
13
|
+
│ ├── Cargo.lock
|
|
14
|
+
│ └── crates/
|
|
15
|
+
│ ├── api/ -> project "api"
|
|
16
|
+
│ └── core/ -> project "core"
|
|
17
|
+
└── tools/xtask/ a standalone crate -> project "xtask"
|
|
18
|
+
├── Cargo.toml
|
|
19
|
+
└── Cargo.lock
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## How workspaces are found
|
|
23
|
+
|
|
24
|
+
The plugin looks at every `Cargo.toml` in the repository and runs
|
|
25
|
+
`cargo metadata` once per Cargo workspace. Workspaces can sit anywhere,
|
|
26
|
+
including the repository root, and there can be any number of them. It asks
|
|
27
|
+
again each time Nx creates the graph and keeps no answer in between; for a
|
|
28
|
+
workspace of 600 crates that takes about 0.2 seconds on a fast machine.
|
|
29
|
+
|
|
30
|
+
- A crate outside every workspace is a **standalone crate**: a workspace of
|
|
31
|
+
one, with its own `Cargo.lock` and its own build directory. The plugin does
|
|
32
|
+
not hide that, so two standalone crates share no compiled dependencies.
|
|
33
|
+
- A crate that its workspace lists under `exclude` is also a standalone crate.
|
|
34
|
+
- The crates that `cargo vendor` writes are skipped by themselves. A crate
|
|
35
|
+
whose folder holds `.cargo-checksum.json`, which `cargo vendor` writes beside
|
|
36
|
+
each vendored `Cargo.toml`, gets no project and no edge, and the plugin runs
|
|
37
|
+
no Cargo for it, wherever the folder lies and whatever your Cargo
|
|
38
|
+
configuration says. Cargo itself builds from the vendored sources only with
|
|
39
|
+
the `[source]` tables that `cargo vendor` prints, in a `.cargo/config.toml`.
|
|
40
|
+
A vendored crate that one of your crates depends on by path is a member of
|
|
41
|
+
your workspace for Cargo, so it gets a project like any member. To keep Nx
|
|
42
|
+
from reading the folder at all, list it under `exclude` on the plugin's entry
|
|
43
|
+
or in `.nxignore`.
|
|
44
|
+
- Crates under paths ignored by `.gitignore` or `.nxignore` are skipped. Use
|
|
45
|
+
`exclude` on the plugin's entry in `nx.json` for generated crates or other
|
|
46
|
+
crates that are checked in ([Configuration](configuration.mara.md)). A crate that depends by
|
|
47
|
+
path on a skipped crate still gets that crate's files into its cache key
|
|
48
|
+
([Caching](caching.mara.md)), and an edge to every crate with a project that
|
|
49
|
+
Cargo builds for it through the skipped crate. To find them, the plugin still asks Cargo about
|
|
50
|
+
the skipped crate, so a broken manifest there fails the graph even when it
|
|
51
|
+
is excluded, just as plain cargo fails for the crate that depends on it.
|
|
52
|
+
A skipped crate that lies in another workspace's folder without being its
|
|
53
|
+
member is the exception: Cargo builds it as a dependency but will not
|
|
54
|
+
report on it, so the plugin warns, names the crate and leaves the path
|
|
55
|
+
dependencies behind it unread. List the crate under that workspace's
|
|
56
|
+
`members` or `exclude` to have them read. The same goes for a crate whose
|
|
57
|
+
`package.workspace` names a `Cargo.toml` without `[workspace]` or a folder
|
|
58
|
+
that does not exist: correct that key to have them read.
|
|
59
|
+
- If cargo is not installed, or `cargo metadata` fails for a manifest, the
|
|
60
|
+
graph fails with cargo's message. Nothing is left out silently, so every
|
|
61
|
+
machine that runs `nx` in the repository needs cargo
|
|
62
|
+
([Setup](setup.mara.md)).
|
|
63
|
+
- Building the graph needs no network and downloads no crates. The plugin asks
|
|
64
|
+
Cargo only about the workspace itself (`cargo metadata --no-deps`), which
|
|
65
|
+
also never touches `Cargo.lock`.
|
|
66
|
+
- Building the graph installs no toolchain either. The plugin runs Cargo in
|
|
67
|
+
each workspace's root folder, so the `rust-toolchain.toml` that applies there
|
|
68
|
+
counts. If it names a toolchain that is not installed, the graph fails with
|
|
69
|
+
rustup's message, which names the toolchain. Run `rustup toolchain install`
|
|
70
|
+
in that folder to install it. Plain `cargo` still installs it as before.
|
|
71
|
+
|
|
72
|
+
Everything Cargo scopes to a workspace stays per workspace: the lockfile, the
|
|
73
|
+
build directory and the toolchain file, and so will the batches of milestone
|
|
74
|
+
0.2 and the coverage baseline of milestone 0.3. That is
|
|
75
|
+
why a cache input is a real path such as `rust/Cargo.lock`, never one
|
|
76
|
+
repository-wide name for "the lockfile".
|
|
77
|
+
|
|
78
|
+
## Project names
|
|
79
|
+
|
|
80
|
+
A project is named after its crate. If two crates in the repository have the
|
|
81
|
+
same name, the graph fails: Nx's error names both folders, and nx-rust's error
|
|
82
|
+
after it names both manifests and how to rename one of them:
|
|
83
|
+
|
|
84
|
+
```toml
|
|
85
|
+
# tools/api/Cargo.toml - a second crate called "api"
|
|
86
|
+
[package.metadata.nx]
|
|
87
|
+
name = "tools-api"
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
A per-workspace prefix does the same for all members of a workspace:
|
|
91
|
+
|
|
92
|
+
```toml
|
|
93
|
+
# tools/Cargo.toml
|
|
94
|
+
[workspace.metadata.nx]
|
|
95
|
+
namePrefix = "tools-" # "api" becomes "tools-api"
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
The prefix is used as it is, with no separator added. A crate that sets its own
|
|
99
|
+
`name` gets exactly that name, without the prefix. Renaming the project changes
|
|
100
|
+
nothing for Cargo: every command still selects the crate by its package ID
|
|
101
|
+
specification, or by its package name for `cargo fmt`.
|
|
102
|
+
|
|
103
|
+
A crate whose folder is also a JS project takes that project's name, from its
|
|
104
|
+
`package.json` or its `project.json`, because Nx applies those files after
|
|
105
|
+
every plugin. Where Nx takes the name from one of those files, the crate's
|
|
106
|
+
`name` override has no effect; a `project.json` without a name and without a
|
|
107
|
+
`package.json` beside it keeps the name the plugin gives the crate. To choose
|
|
108
|
+
another name, set `name` in the folder's `project.json` if it has one, and
|
|
109
|
+
otherwise `nx.name` in its `package.json`. Such a name also settles a
|
|
110
|
+
collision between two crates. A crate and a JS project with the same name make
|
|
111
|
+
Nx fail with its own error, which names both folders. In such mixed cases, and
|
|
112
|
+
when three or more projects share a name, nx-rust's error may be missing or
|
|
113
|
+
incomplete; Nx's error always names every folder.
|
|
114
|
+
|
|
115
|
+
## Workspace-level tasks
|
|
116
|
+
|
|
117
|
+
Some tasks belong to a workspace, not to one crate: documentation, `cargo audit`,
|
|
118
|
+
`cargo deny` and lockfile updates, and the coverage
|
|
119
|
+
baseline, in a workspace with `affectedTests`. Each workspace has one
|
|
120
|
+
project for them, rooted at the workspace folder and depending on every member.
|
|
121
|
+
If the root `Cargo.toml` also defines a crate, that crate's project hosts these
|
|
122
|
+
targets and no extra project appears. Formatting is per crate: every crate has
|
|
123
|
+
its own `fmt` and `fmt-check`. The targets are listed under
|
|
124
|
+
[Targets](targets.mara.md#workspace-level-targets).
|
|
125
|
+
|
|
126
|
+
That project also has the `lockfile` task. It lets cargo bring the
|
|
127
|
+
workspace's `Cargo.lock` up to date and turns it into one digest per crate.
|
|
128
|
+
Every cached task of a crate except `fmt-check`, which reads no lockfile,
|
|
129
|
+
waits for it and reads the crate's digest, so a dependency update reruns only
|
|
130
|
+
the crates it reaches where the workspace uses the `hakari` feature strategy;
|
|
131
|
+
under `workspace-build` and `cargo` it reruns them all
|
|
132
|
+
([Caching](caching.mara.md#lockfile-changes)). With `hakari`, the project also
|
|
133
|
+
has the `hakari-check` task, which checks the hack crate before the crates'
|
|
134
|
+
tasks run ([Batching and features](execution.mara.md#when-the-hack-crate-is-enough)).
|
|
135
|
+
|
|
136
|
+
The workspace project is named after its folder's path from the root of the Nx
|
|
137
|
+
workspace, with each `/` replaced by `-`: a workspace in `rust/` gives `rust`,
|
|
138
|
+
one in `services/billing/` gives `services-billing`. A workspace at the root of
|
|
139
|
+
the Nx workspace itself is called `cargo-workspace`. A workspace's name prefix
|
|
140
|
+
applies to its crates, not to this project. To choose another name, or to give
|
|
141
|
+
the project tags or targets of its own, use the `project` table of the
|
|
142
|
+
workspace's metadata:
|
|
143
|
+
|
|
144
|
+
```toml
|
|
145
|
+
# services/billing/Cargo.toml
|
|
146
|
+
[workspace]
|
|
147
|
+
members = ["crates/*"]
|
|
148
|
+
|
|
149
|
+
[workspace.metadata.nx.project]
|
|
150
|
+
name = "billing-rust"
|
|
151
|
+
tags = ["scope:billing"]
|
|
152
|
+
|
|
153
|
+
[workspace.metadata.nx.project.targets.sqlx-prepare]
|
|
154
|
+
command = "cargo sqlx prepare --workspace"
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
The table is for a workspace whose root `Cargo.toml` defines no crate. When it
|
|
158
|
+
does, that crate's project is the workspace project, and its name and targets
|
|
159
|
+
go into `[package.metadata.nx]`; a `project` table there is an error.
|
|
160
|
+
|
|
161
|
+
Names are used as they are. A folder name that contains `,` or `:`, or starts
|
|
162
|
+
with `!`, gives a name that is awkward on Nx's command line: `,` and a leading
|
|
163
|
+
`!` change what `--projects` selects, and `:` separates the project from the
|
|
164
|
+
target in `nx run`. Set a name in the table to avoid that.
|
|
165
|
+
|
|
166
|
+
If the workspace folder already is an Nx project, because it has a
|
|
167
|
+
`project.json` or a `package.json` that Nx reads, Nx makes the two one project.
|
|
168
|
+
Nx reads a `package.json` when your package manager's workspace patterns
|
|
169
|
+
include it or a `project.json` sits beside it, and the root one also when it
|
|
170
|
+
has an `nx` key. Where Nx takes the name from the folder's `project.json` or
|
|
171
|
+
`package.json`, the `name` in the table has no effect: a `project.json` that
|
|
172
|
+
sets a name gives the name, and otherwise the `package.json` does. A
|
|
173
|
+
`project.json` without a name and without a `package.json` beside it keeps the
|
|
174
|
+
name from the table, or the default. At the root of the Nx workspace, a
|
|
175
|
+
`project.json` without a name, an `nx` key in the root `package.json` or a
|
|
176
|
+
workspace pattern that includes the root is enough to give the project the name
|
|
177
|
+
in the root `package.json`.
|
|
178
|
+
|
|
179
|
+
A workspace project with the same name as a crate, or two workspace projects
|
|
180
|
+
with one name, make the graph fail: Nx's error names both folders, and
|
|
181
|
+
nx-rust's error names both manifests, though not always for a project at the
|
|
182
|
+
root of the Nx workspace.
|
|
183
|
+
Default names can collide: a workspace in `services/billing/` and one in
|
|
184
|
+
`services-billing/` both get `services-billing`, and one at the root and one in
|
|
185
|
+
`cargo-workspace/` both get `cargo-workspace`. Set a `name` in the table of one
|
|
186
|
+
of them. A workspace project and a JS project with one name make Nx fail with
|
|
187
|
+
its own error.
|
|
188
|
+
|
|
189
|
+
You reach the workspace project by its name, as in `nx run rust:audit`, or with
|
|
190
|
+
the others through `nx run-many -t audit`. Nx also accepts its folder in place
|
|
191
|
+
of the name unless the folder's text matches a project name, as in
|
|
192
|
+
`nx audit services/billing`, and inside the folder `nx audit` is enough; at the
|
|
193
|
+
root of the Nx workspace, `nx audit .` works too.
|
|
194
|
+
|
|
195
|
+
## The dependency graph
|
|
196
|
+
|
|
197
|
+
- **All three kinds of Cargo dependency are edges:** normal, build and
|
|
198
|
+
dev-dependencies. A change in a crate that another crate uses only in its
|
|
199
|
+
tests still invalidates that crate's cached tests.
|
|
200
|
+
- **A path dependency into another workspace** is an edge to the one project
|
|
201
|
+
that crate already has. The crate stays in its home workspace, and its own
|
|
202
|
+
tests run there.
|
|
203
|
+
- **Crates that `[patch]`, `[replace]` or `paths` put in place of a registry or
|
|
204
|
+
git dependency** are dependencies too. The plugin reads these tables from the
|
|
205
|
+
workspace's root `Cargo.toml` and from the `.cargo/config.toml` files that
|
|
206
|
+
Cargo reads for the workspace, without running Cargo. A dependency whose
|
|
207
|
+
name and version requirement the redirected crate matches gets its edge.
|
|
208
|
+
Which other crates end up using a redirected crate is not in those files: a
|
|
209
|
+
crates.io crate can lead to it. So every member with a registry or git
|
|
210
|
+
dependency gets an edge to it, and the graph can show more edges than
|
|
211
|
+
`cargo tree`, never fewer, apart from edges that would form a cycle, for
|
|
212
|
+
which the files of the crate and of the crates it depends on count as inputs
|
|
213
|
+
instead. A redirected crate without
|
|
214
|
+
a project counts with its files, and the crates with a project that it
|
|
215
|
+
depends on by path, directly or through other crates without a project, are
|
|
216
|
+
dependencies of every crate that may use it. For a `paths` entry, the plugin
|
|
217
|
+
finds the crates below its folder as Cargo does, skipping only what Cargo
|
|
218
|
+
skips: hidden folders, folders that hold `.git` and `target` folders beside
|
|
219
|
+
a `Cargo.toml`. Like Cargo, it also counts the crates that those crates
|
|
220
|
+
depend on by path, of every kind and wherever they lie. A redirection in your
|
|
221
|
+
Cargo home's `config.toml` counts too, with a warning, because Nx does not
|
|
222
|
+
notice when a file outside the repository changes. So does one in a
|
|
223
|
+
`.cargo/config.toml` that `.gitignore` or `.nxignore` hides from Nx: stop
|
|
224
|
+
ignoring the file, or run `nx reset` after you change it.
|
|
225
|
+
- **External crates are not nodes.** `nx graph` shows the crates of the
|
|
226
|
+
repository only. A crate's cache key still follows the locked versions of
|
|
227
|
+
the external crates it reaches, through the `lockfile` task of its workspace
|
|
228
|
+
([Caching](caching.mara.md#lockfile-changes)).
|
|
229
|
+
- **Cycles are kept.** Cargo allows a crate's dev-dependency to depend back on
|
|
230
|
+
it. The edge stays in the graph. Nx fails only when tasks depend on each
|
|
231
|
+
other in a cycle, and the plugin's targets do not depend on other crates'
|
|
232
|
+
targets, only on the `lockfile` task of their workspace, which depends on
|
|
233
|
+
nothing, and with the `hakari` feature strategy on its `hakari-check` task,
|
|
234
|
+
which depends only on `lockfile` ([Targets](targets.mara.md)). If your own `dependsOn` creates such a
|
|
235
|
+
cycle, Nx names the tasks involved.
|
|
236
|
+
|
|
237
|
+
## Requirements
|
|
238
|
+
|
|
239
|
+
:::mara requirement REQ-INFERRED-PROJECTS
|
|
240
|
+
:mid: 01M78FHG7FTJGK8AM848F0DHR4
|
|
241
|
+
:title: Infer an Nx project for every workspace member
|
|
242
|
+
:status: accepted
|
|
243
|
+
:satisfies: NEED-ZERO-CONFIG
|
|
244
|
+
:satisfies: NEED-CARGO-UNCHANGED
|
|
245
|
+
|
|
246
|
+
Every member of every discovered Cargo workspace is an Nx project rooted at the crate's folder. The name, targets and dependencies that the plugin gives it are derived from Cargo's own description of the workspace. Where the crate's folder also is a JS project, Nx applies its `package.json` and `project.json` after every plugin, so the name Nx takes from them and their scripts and targets named like the plugin's take precedence ([[EVD-NX-PROJECT-MERGE]]). The plugin neither requires nor creates a `project.json` or any other file inside a crate.
|
|
247
|
+
:::
|
|
248
|
+
|
|
249
|
+
:::mara requirement REQ-MULTI-WORKSPACE
|
|
250
|
+
:mid: 01M78FHG7FM0VMSF1ZZQBRH77A
|
|
251
|
+
:title: Support any number of Cargo workspaces anywhere
|
|
252
|
+
:status: accepted
|
|
253
|
+
:satisfies: NEED-ANY-LAYOUT
|
|
254
|
+
|
|
255
|
+
The plugin handles any number of Cargo workspaces located anywhere in the repository, including the repository root. A crate outside every workspace, and a crate that its enclosing workspace excludes, is handled as a workspace with one member ([[TERM-STANDALONE-CRATE]]). Everything Cargo scopes to a workspace is kept per workspace ([[TERM-WORKSPACE-CONTEXT]]), and finding the projects costs one cargo invocation per workspace for the plugin entry that receives its manifests, and a second one where that entry does not receive the workspace's root manifest.
|
|
256
|
+
:::
|
|
257
|
+
|
|
258
|
+
:::mara requirement REQ-CROSS-WORKSPACE-DEPS
|
|
259
|
+
:mid: 01M78FHG7F66H6NHB2TKC89D15
|
|
260
|
+
:title: Keep a crate one project across workspaces
|
|
261
|
+
:status: accepted
|
|
262
|
+
:satisfies: NEED-ANY-LAYOUT
|
|
263
|
+
:satisfies: NEED-AFFECTED
|
|
264
|
+
|
|
265
|
+
A crate that a member of another Cargo workspace uses through a path dependency is exactly one Nx project. It belongs to the workspace that lists it as a member, and its own tasks run there. The consuming crate has a dependency edge to it.
|
|
266
|
+
:::
|
|
267
|
+
|
|
268
|
+
:::mara requirement REQ-SKIP-CRATES
|
|
269
|
+
:mid: 01M78FHG7FG8P6G2HEZA4XB0FT
|
|
270
|
+
:title: Leave ignored, excluded and vendored crates alone
|
|
271
|
+
:status: accepted
|
|
272
|
+
:satisfies: NEED-ANY-LAYOUT
|
|
273
|
+
|
|
274
|
+
Crates under paths ignored by `.gitignore` or `.nxignore`, crates matched by `exclude` on the plugin's entry in `nx.json`, and crates whose folder holds cargo's `.cargo-checksum.json`, such as those that `cargo vendor` writes, that no workspace lists among its members, do not become Nx projects.
|
|
275
|
+
:::
|
|
276
|
+
|
|
277
|
+
:::mara requirement REQ-PROJECT-NAMES
|
|
278
|
+
:mid: 01M78FHG7FHKQE34YBKH1C5WSN
|
|
279
|
+
:title: Name projects after crates and fail on collisions
|
|
280
|
+
:status: accepted
|
|
281
|
+
:satisfies: NEED-ZERO-CONFIG
|
|
282
|
+
|
|
283
|
+
An Nx project is named after its crate. When the crate's folder also is a JS project, the name set by its `package.json` or `project.json` applies instead, because Nx applies those files after every plugin ([[EVD-NX-PROJECT-MERGE]]). A [[TERM-WORKSPACE-PROJECT]] that is not a crate's project is named after the path of the workspace folder from the root of the Nx workspace, and a workspace at that root has a fixed name; the same exception applies to its folder, and a name set for it in the workspace's metadata replaces the default ([[ADR-WORKSPACE-PROJECT-NAME]]). When two projects of this plugin get the same name, graph creation fails. Nx's own error names their folders, and where the plugin can tell that the colliding projects are its own it adds an error that names their manifest paths and the remedies ([[DES-PROJECT-GRAPH]]). The plugin never renames a project on its own. A per-crate name, a per-workspace name prefix and a name for the workspace project resolve a collision. Whatever the project is called, every cargo command selects the crate by its package ID specification, or by its package name for `cargo fmt` ([[DES-INVOCATION]]).
|
|
284
|
+
:::
|
|
285
|
+
|
|
286
|
+
:::mara requirement REQ-WORKSPACE-PROJECT
|
|
287
|
+
:mid: 01M78FHG7FEH8W5X747EMPM5B1
|
|
288
|
+
:title: Give each workspace one project for workspace-level tasks
|
|
289
|
+
:status: accepted
|
|
290
|
+
:satisfies: NEED-ZERO-CONFIG
|
|
291
|
+
:satisfies: NEED-ANY-LAYOUT
|
|
292
|
+
|
|
293
|
+
Each Cargo workspace has exactly one Nx project for tasks that concern the workspace as a whole ([[TERM-WORKSPACE-PROJECT]]). It is rooted at the workspace folder and depends on every member. When the root manifest also defines a crate, that crate's project carries the workspace-level targets and no second project is created.
|
|
294
|
+
:::
|
|
295
|
+
|
|
296
|
+
:::mara requirement REQ-DEPENDENCY-EDGES
|
|
297
|
+
:mid: 01M78FHG7FCAFQC6190Y3J4B5A
|
|
298
|
+
:title: Put every kind of Cargo dependency in the graph
|
|
299
|
+
:status: accepted
|
|
300
|
+
:satisfies: NEED-AFFECTED
|
|
301
|
+
:satisfies: NEED-CORRECT-CACHE
|
|
302
|
+
|
|
303
|
+
The graph has an edge for every normal, build and dev-dependency between crates that are Nx projects. An edge is present even when it closes a cycle that Cargo permits. A crate that `[patch]`, `[replace]` or `paths` may put in place of a registry or git dependency counts as a dependency of every member that may use it, so the graph has at least the edges of the crates that Cargo builds; where such an edge would close a cycle that Cargo rejects, the member's cache keys cover the crate through inputs instead ([[ADR-REDIRECTION-EDGES]], [[REQ-INPUT-FILES]]).
|
|
304
|
+
:::
|
|
305
|
+
|
|
306
|
+
:::mara requirement REQ-EXTERNAL-DEPS
|
|
307
|
+
:mid: 01M78FHG7FCVSEDGQW30RSSCMA
|
|
308
|
+
:title: Invalidate a crate only for the external dependencies it uses
|
|
309
|
+
:status: accepted
|
|
310
|
+
:satisfies: NEED-AFFECTED
|
|
311
|
+
:satisfies: NEED-CORRECT-CACHE
|
|
312
|
+
|
|
313
|
+
A change in `Cargo.lock` changes a crate's cache keys when it changes a package among that crate's resolved dependencies, direct or transitive, as the lockfile of the crate's own workspace resolves them. Where the crate is built with the features of its whole workspace, every package that the lockfile resolves for a member of the workspace counts among them, because it can change the features of a dependency that the members share ([[DES-UNIFICATION]]). A lockfile change that leaves a crate's resolved dependencies untouched does not change that crate's cache keys, and a change to the lockfile of another workspace never does. No successful result is stored or restored under a key computed from a lockfile that cargo would still change, nor stored under a key whose digests no longer describe the lockfile that the task's cargo commands read, as when another command changes the lockfile during the run; unless `NX_CACHE_FAILURES=true`, no failure is stored under it either. After a change to a workspace's `Cargo.lock`, `nx affected` selects the cached targets of that workspace's crates, and those whose keys did not change are restored from the cache.
|
|
314
|
+
:::
|
|
315
|
+
|
|
316
|
+
:::mara requirement REQ-METADATA-DISK-CACHE
|
|
317
|
+
:mid: 01M78FHG7FM7J2WAZSP8WESWVG
|
|
318
|
+
:title: Reuse the cargo metadata report between Nx processes
|
|
319
|
+
:status: retired
|
|
320
|
+
:satisfies: NEED-EFFICIENT-BUILDS
|
|
321
|
+
|
|
322
|
+
The `cargo metadata` report of a workspace is reused across Nx processes for as long as the files it depends on are unchanged.
|
|
323
|
+
|
|
324
|
+
Retired on 13 November 2026: the report is requested afresh in every graph computation, because a stored report would save little and could go stale ([[ADR-NO-METADATA-CACHE]]).
|
|
325
|
+
:::
|
|
326
|
+
|
|
327
|
+
## Design
|
|
328
|
+
|
|
329
|
+
:::mara design DES-DISCOVERY
|
|
330
|
+
:mid: 01M78FHG7FJ3Z6F0AX0K80EH9D
|
|
331
|
+
:title: Workspace discovery
|
|
332
|
+
:status: accepted
|
|
333
|
+
:satisfies: REQ-MULTI-WORKSPACE
|
|
334
|
+
:satisfies: REQ-SKIP-CRATES
|
|
335
|
+
|
|
336
|
+
The plugin receives every `Cargo.toml` that Nx finds. Nx has already left out paths ignored by `.gitignore` and `.nxignore`, and the manifests matched by `exclude` on the plugin's entry in `nx.json`. That `exclude` is Nx's own filter for plugin entries ([[EVD-NX-24-INSPECTION]]); the plugin has no option of its own for it.
|
|
337
|
+
|
|
338
|
+
Discovery repeats one step until no manifest is unclaimed: take the shallowest unclaimed manifest and run `cargo metadata` in its folder. The report names the workspace root and its members, and those manifests are now claimed by that workspace. A manifest whose report has one member and no enclosing workspace is a [[TERM-STANDALONE-CRATE]]. A crate that an enclosing workspace excludes is still unclaimed after that workspace's step, so it gets a step of its own and becomes a standalone crate too. Each workspace costs one cargo call, and a second one where the first did not start in its root folder.
|
|
339
|
+
|
|
340
|
+
**Root folder.** Graph creation takes everything that Cargo's configuration decides for a workspace from the folder in which the workspace's tasks run cargo, its root folder ([[DES-INVOCATION]], [[ADR-WORKSPACE-ROOT]]): the artifact and build directories, the triples that `build.target` picks ([[DES-OUTPUTS]]), the redirections that are read, and the toolchain. Cargo finds its configuration files and resolves a relative `CARGO_TARGET_DIR` from the folder it starts in, and rustup picks the toolchain there, so a report from another folder can name an artifact directory that the tasks never write to ([[GOAL-TRUSTED-CACHE]]). The step's call starts in the root folder whenever Nx hands the root manifest to the plugin, since no manifest of the workspace is shallower. Where Nx does not, because the root manifest is ignored or excluded while members are not, the call starts in a member's folder; discovery then calls `cargo metadata` once more in the `workspace_root` that the report names and takes the workspace from that report. Only such workspaces cost the extra call, and a report that another entry in the same process requested in the root folder serves instead ([[DES-METADATA-REPORT]]). The first call still needs a toolchain in the member's folder, so a toolchain pinned there and not installed fails graph creation as well.
|
|
341
|
+
|
|
342
|
+
A member whose manifest was left out or removed gets no project, although the report lists it.
|
|
343
|
+
|
|
344
|
+
For each workspace, discovery also reads the crates that its `[patch]`, `[replace]` and `paths` tables redirect dependencies to, without cargo ([[DES-METADATA-REPORT]], [[ADR-REDIRECTION-EDGES]]).
|
|
345
|
+
|
|
346
|
+
A manifest whose folder also holds `.cargo-checksum.json` belongs to a package of a directory source, such as a crate that `cargo vendor` wrote, and discovery never reads it: the crate gets no project, no edge and no cargo call of its own, wherever its folder lies, whichever plugin entry receives the manifest and whatever Cargo's configuration says ([[ADR-SKIP-VENDORED-CRATES]]). A workspace whose report, requested for another manifest, lists such a crate among its members claims it like any member, as cargo enrols one that a member depends on by path, and the crate gets its project.
|
|
347
|
+
|
|
348
|
+
When cargo cannot be started, or `cargo metadata` fails for a manifest, graph creation fails with an error that names the manifest and carries cargo's message. A toolchain that the folder pins and that is not installed is such a failure, and rustup's message names the toolchain ([[DES-METADATA-REPORT]]). The plugin never leaves a workspace out of the graph to get past such a failure ([[ADR-CARGO-SOURCE-OF-TRUTH]]). A manifest matched by `exclude` gets no project and is not read as a workspace, but a crate that depends on it by path, or whose workspace's `[patch]` or `[replace]` redirects to it, still makes the plugin request one report for it, because its files are inputs of that crate.
|
|
349
|
+
|
|
350
|
+
**Entries.** Each entry of the plugin in `nx.json` discovers on its own, with its own options and the manifests that its `include` and `exclude` let through, and keeps what it found for its own `createDependencies` and `createMetadata` ([[DES-PROJECT-GRAPH]], [[DES-DIAGNOSTICS]]). Nothing that Nx passes to the hooks names the entry: Nx calls them on a copy of the plugin's module that it makes for each entry, calling the function of the copy's `createNodes`, a tuple of a glob and a function, as an element of that tuple, so that it does not receive the copy, and calling the later hooks as methods of the copy, and passes the entry's options, which are `undefined` for an entry without options ([[EVD-NX-24-PLUGIN-ENTRIES]]). The plugin's `createNodes` is therefore a getter, which gives each copy a `createNodes` of its own that holds the entry's state, and the later hooks find that state through the copy they are called on. Where a call shows that this does not hold, the hook fails graph creation with a message that says that the plugin cannot tell which of its entries Nx called it for and asks for a report, rather than answer with another entry's projects ([[GOAL-TRUSTED-CACHE]]): a later hook called other than as a method of an entry's copy, as after destructuring; a later hook called with other options than the entry's `createNodes` received, also where they are equal; and a `createNodes` call with other options than the copy's first call, which shows that entries share a copy. Where graph computations of one entry overlap, as when the daemon starts a computation before an earlier one has finished, the later hooks answer from the entry's newest `createNodes` call; which computation a call belongs to cannot be told from what Nx passes, so overlapping calls are not an error. Undetected stay a copy shared by entries with the same options object or without options, which Nx 24 never makes; an entry's manifests split between several `createNodes` calls of one computation, of which the later hooks would see only the newest, which Nx 24 never does either; and a later hook of one copy called as a method of another entry's copy with the same options, since the hooks are one function on every copy, which Nx's loader never does.
|
|
351
|
+
:::
|
|
352
|
+
|
|
353
|
+
:::mara design DES-METADATA-REPORT
|
|
354
|
+
:mid: 01M78FHG7FMJF63PW3D02BH53E
|
|
355
|
+
:title: One cargo metadata report per workspace
|
|
356
|
+
:status: accepted
|
|
357
|
+
:satisfies: REQ-INFERRED-PROJECTS
|
|
358
|
+
:satisfies: REQ-MULTI-WORKSPACE
|
|
359
|
+
|
|
360
|
+
Nodes, targets and edges of a workspace all come from one `cargo metadata` report. Project creation and dependency creation (the plugin's `createNodes` and `createDependencies` hooks) of one plugin entry in `nx.json` share that report, so the two hooks cannot disagree and a graph computation runs cargo once per workspace for the entry, twice for a workspace whose root manifest the entry does not receive ([[DES-DISCOVERY]]). One entry receives the manifests of a workspace ([[DES-PLUGIN-OPTIONS]], "Several entries"), but where `nx.json` lists the plugin more than once, each entry also reads the workspaces of the others for the comparison of artifact directories ([[DES-OUTPUTS]]). Such a workspace is then reported once in each process, because Nx runs each entry in a process of its own unless plugin isolation is off; entries in one process share the report that cargo gives in the workspace's root folder ([[EVD-NX-PLUGIN-ENTRIES]]). So that the report is shared whichever entry asks first, a request in one process waits for the requests in flight that may report its workspace, judged from manifests without running cargo. Where the requested manifest names a workspace root with `package.workspace` (a legacy `[project]` table counts as `[package]`) or is not valid TOML, the request waits for every request in flight, and every later request waits for it. Otherwise a manifest with a `[workspace]` table is its own only candidate root, whatever lies above it. A manifest without one has itself and every `Cargo.toml` in a folder above it as candidate roots, along the path as cargo normalises it as text and along its real path; where one of those names a workspace root with `package.workspace` or is not valid TOML, the request again waits for every request in flight, and every later request waits for it. A request waits for those in flight that share a candidate root with it, compared by real path; requests that share none run at the same time. Workspace and package metadata tables ([[DES-METADATA-TABLES]]) are read from the same report, not by parsing manifests. The report is requested afresh in every graph computation ([[ADR-NO-METADATA-CACHE]]).
|
|
361
|
+
|
|
362
|
+
The report is requested with `--no-deps` ([[ADR-METADATA-NO-DEPS]]). It then holds the members of the workspace with their targets, their declared dependencies and the metadata tables, and Cargo's two directories. It needs no network, downloads nothing and never creates or changes `Cargo.lock` ([[EVD-CARGO-NO-DEPS]]). A dependency on another crate in the repository is recognised by the path its entry carries. Dependencies are not resolved in this report, so the locked versions of external crates come from `Cargo.lock` itself ([[DES-LOCKFILE-HASHING]]). The lockfile task lets cargo bring that file up to date and reads it when it runs; graph creation does not read it.
|
|
363
|
+
|
|
364
|
+
**Redirections.** The report does not apply `[patch]`, `[replace]` or `paths`, and no report without dependency resolution holds them ([[EVD-CARGO-REDIRECTIONS]]). They are the one exception to reading everything from the report: the plugin parses Cargo's files for them itself ([[ADR-REDIRECTION-EDGES]]). For each workspace it reads the `[patch]` and `[replace]` entries with a `path` from the root manifest, and the `[patch]` entries with a `path` and the `paths` entries from the configuration of the workspace root, of every folder above it and of the Cargo home, following `include`. In each of these folders cargo reads `.cargo/config` where it exists and `.cargo/config.toml` otherwise, and in the Cargo home `config` or `config.toml` in the same way; these are the files that cargo reads for the workspace's tasks ([[DES-INVOCATION]]). A path resolves against the root manifest's folder, or in a configuration file against the folder above the one that holds the file. A `[patch]` in a member's manifest is ignored, as cargo ignores it. Reading runs no cargo and leaves `Cargo.lock` untouched. A root manifest or configuration file that cargo reads and the plugin cannot parse fails graph creation with an error that names it. A file that `include` names is skipped with a warning instead, because Cargo 1.91 ignores `include`.
|
|
365
|
+
|
|
366
|
+
A path dependency that is no member of the workspace appears only as that path, which names the crate at the real path of its folder ([[DES-PROJECT-GRAPH]]). When such a crate has no project of its own, the plugin requests a report for its manifest as well, to learn the path dependencies behind it ([[DES-INPUTS]]), unless the crate's folder holds `.cargo-checksum.json` ([[DES-DISCOVERY]]). So it does for a crate without a project that a `[patch]` or `[replace]` entry redirects to, and for each crate without a project that a `paths` entry can redirect to (below), from the root folder of the workspace that redirects, comparing folders through symbolic links, so that the crates with a project behind it are known ([[DES-PROJECT-GRAPH]]); an entry whose folder holds no `Cargo.toml` gets no report. A report that already describes such a crate, as the report of its workspace does for each member, serves for it, and a folder whose report describes no package there holds a virtual manifest and no crate. When cargo fails for such a redirected crate, as it does for a crate in a workspace's folder that is not its member, which cargo builds as a patch but does not report, graph creation goes on with a warning that names the manifest and carries cargo's message, and the path dependencies behind that crate are not followed; the warning says so in plain words, and that letting cargo report the crate or declaring the files behind it with `fileInputs` covers them ([[DES-DIAGNOSTICS]]). A path dependency gets the same treatment when cargo refuses its report for a reason that cargo checks only for the crate it reports, never for a dependency it builds ([[EVD-CARGO-UNREPORTED-CRATES]]). There are three such reasons. The crate lies in the folder of a workspace, or names one in `package.workspace`, without being its member, which the plugin recognises by cargo's message "current package believes it's in a workspace when it's not". The manifest that the crate's `package.workspace` names, or that of a crate above it, has no `[workspace]` table, which cargo reports as "root of a workspace inferred but wasn't a root". Or cargo cannot read that manifest, as where `package.workspace` names a missing folder, which cargo reports as "failed to read" a manifest other than the crate's own. The plugin takes the last two only as cargo's error itself, the first line of its output that starts with `error:`. Cargo also prints them as the cause below another error, for a manifest that takes a key from such a workspace, and then it rejects the crate as a dependency as well. The maintainer chose on 13 November 2026 to keep "failed to load manifest for workspace member" an error, which cargo gives for a crate in the folder of a workspace that lists a missing member: cargo gives the same message where the member that fails to load is one that the crate depends on, and then the build of the workspace that uses the crate fails too. Such a crate has no report, so its folder alone is an input of the crates that use it, as for any path dependency without a project ([[DES-INPUTS]]). Any other failure of a path dependency's report, such as for a manifest that cargo rejects, fails graph creation with an error that names the manifest and carries cargo's message. These calls come on top of the one per workspace.
|
|
367
|
+
|
|
368
|
+
**Crates below a `paths` folder.** Cargo takes the crates of a `paths` entry from the entry's whole folder ([[EVD-CARGO-REDIRECTIONS]]), so discovery looks for them there as cargo does, in the repositories that configure `paths` only, once per folder in a graph computation. It walks the folder to any depth, through a symbolic link given as the folder but through no link below it, and takes every folder that holds a `Cargo.toml`, going on below it, under a crate or a nested workspace alike. Below the folder itself it skips, as cargo does, every folder whose name starts with `.` and every folder that holds `.git`, and at every level a folder named `target` beside a `Cargo.toml`; a folder it cannot read is skipped as well. It skips nothing else, so it walks `node_modules` and Cargo's artifact and build directories below the folder too, where cargo finds crates as well. That costs about a tenth of a second for some ten thousand folders ([[EVD-CARGO-REDIRECTIONS]]), only in the repositories that configure `paths`, and cargo walks the same folders. Where cargo's rule cannot be followed exactly, the walk finds more: it takes both of two crates with one name, of which cargo takes the first, and a folder whose manifest cargo cannot parse, which cargo skips; a crate that cargo does not take only adds a possible use. The walk ignores `.gitignore` and `.nxignore`, as cargo does, so a crate there is a redirected crate whose files Nx cannot see ([[DES-INPUTS]]).
|
|
369
|
+
|
|
370
|
+
The crates that a `paths` entry can redirect to are the crates that the walk finds and, as cargo takes them as well, the path dependencies of each, of every kind, dev-dependencies and those for other platforms included, to any depth, inside or outside the folder, through crates with a project or without ([[EVD-CARGO-REDIRECTIONS]]). This is a walk of its own: the one that says what cargo builds with a crate takes normal and build dependencies only ([[DES-PROJECT-GRAPH]]), while cargo takes these crates as candidates whether or not it compiles the crate that names them. Each crate without a project among them gets a report as above, and cargo's failure for one, such as for a manifest that is no valid TOML, gives the warning above. With the Nx daemon, a `Cargo.toml` added below a `paths` folder that Nx sees is a change inside the repository, after which the daemon creates the graph again and the plugin walks the folder anew ([[EVD-CARGO-REDIRECTIONS]]). A `paths` folder outside the repository, or one that `.gitignore` or `.nxignore` hides, is walked whenever Nx creates the graph, like the rest of Cargo's configuration outside the repository, so a crate added there reaches the graph the next time Nx creates it for another reason.
|
|
371
|
+
|
|
372
|
+
Every cargo call of graph creation runs with `RUSTUP_AUTO_INSTALL=0`, set for these calls only, so a toolchain that is pinned for the folder the call starts in and that is not installed fails the call and graph creation instead of being installed ([[ADR-GRAPH-NO-TOOLCHAIN-INSTALL]]). rustup and Cargo choose the toolchain file and the configuration files by that folder ([[DES-INVOCATION]]). A workspace's report is the one that cargo gives in the workspace's root folder, where the workspace's tasks run as well ([[DES-DISCOVERY]]). Discovery first requests a report in the folder of the shallowest of the workspace's manifests that Nx hands to the plugin, which is the root folder whenever Nx hands the root manifest to the plugin. When Nx does not, because the root manifest is ignored or excluded while members are not, that first call starts in a member's folder, where a toolchain pinned and not installed fails graph creation with the same error, and a second call in the root folder gives the workspace's report, with the toolchain and configuration files that apply there. A report that a call outside the root folder gave serves for no workspace's report, only to find the workspace and, as for a path dependency, its packages. The report of a path dependency without a project starts in the root folder of the workspace whose member depends on it, directly or through other such crates.
|
|
373
|
+
:::
|
|
374
|
+
|
|
375
|
+
:::mara design DES-PROJECT-GRAPH
|
|
376
|
+
:mid: 01M78FHG7F2S7FX77PNWS621D6
|
|
377
|
+
:title: Projects, names and edges
|
|
378
|
+
:status: accepted
|
|
379
|
+
:satisfies: REQ-INFERRED-PROJECTS
|
|
380
|
+
:satisfies: REQ-PROJECT-NAMES
|
|
381
|
+
:satisfies: REQ-CROSS-WORKSPACE-DEPS
|
|
382
|
+
:satisfies: REQ-WORKSPACE-PROJECT
|
|
383
|
+
:satisfies: REQ-DEPENDENCY-EDGES
|
|
384
|
+
|
|
385
|
+
**Projects.** Each claimed member becomes a project rooted at the crate directory. Its name is the crate's `name` override when one is set, used as it is. Otherwise it is the package name, with the workspace's `namePrefix` put in front of it as it is, without a separator, when the workspace sets one, also for the crate of the root manifest ([[DES-METADATA-TABLES]]). In a folder that also is a JS project, Nx replaces that name with the one from `package.json` or `project.json` ([[EVD-NX-PROJECT-MERGE]]). Two projects of this plugin that hold one name once Nx has applied those files, whether crates or workspace projects, fail graph creation, and so does a collision with another plugin's project. Whether projects keep one name is known only once Nx has merged the projects of all plugins and of all entries of this plugin in `nx.json`, so each entry checks the names in `createDependencies`, against the merged projects that the hook receives. A project holds the name it has there, or, where another project took that name from it, the name under which Nx lists the files of its folder; a name that a `package.json` or `project.json` gave a project replaces the plugin's. To recognise another entry's projects there, each project carries in its metadata, under `cargo`, the name the plugin gives it, its manifest, the root manifest of its workspace and, for a crate, the package name and, as `nameOverride`, whether the crate's own `name` gave the name. Nx reports two projects with one name itself while it merges them, before it calls `createDependencies`, so its error "The following projects are defined in multiple locations", which names every folder, comes first. Commands never use the Nx name: they select the crate by its package ID specification, or by its package name for `cargo fmt` ([[DES-INVOCATION]]).
|
|
386
|
+
|
|
387
|
+
The plugin's own error names the manifest paths and the remedy for each: the crate's `name` override or the workspace's prefix for a crate, only the override for a crate that sets one, because the prefix does not change its name, and the `name` in `[workspace.metadata.nx.project]` for a workspace project. It is promised for two projects that collide under the names the plugin gave them, in one entry or across two entries. Elsewhere it is best effort: when a project that is not the plugin's holds the name too, when three or more projects hold it, when the common name comes from `package.json` or `project.json` files, or when one of the projects is at the repository root, the message can be missing, can name only some of the manifests, or can appear once per entry. In every case graph creation fails with Nx's error, which names every folder.
|
|
388
|
+
|
|
389
|
+
**Workspace project.** Each workspace gets one project rooted at the workspace folder, with a dependency on every member. If the root manifest has a `[package]` table, no extra project is created and the workspace-level targets attach to that crate's project, which is named like any crate; a `[workspace.metadata.nx.project]` table in that manifest fails graph creation with an error that names the manifest and points to `[package.metadata.nx]`. Otherwise the project is named after the path of the workspace folder from the root of the Nx workspace, with each `/` replaced by `-` and nothing else changed: `rust/` gives `rust` and `services/billing/` gives `services-billing`. A workspace at the root of the Nx workspace is called `cargo-workspace`. Two folders can give one default name, such as `services/billing/` and `services-billing/`, or the root and `cargo-workspace/`; that fails as a collision between two projects of this plugin. The `name` in `[workspace.metadata.nx.project]` replaces this default, and the workspace's prefix does not apply to it ([[DES-METADATA-TABLES]], [[ADR-WORKSPACE-PROJECT-NAME]]). When the workspace folder already is an Nx project, through a `project.json` or a `package.json` that Nx reads, Nx merges the two into one project. Nx reads a `package.json` when the package manager's workspace patterns include it or a `project.json` sits beside it, and the root one also when it has an `nx` key. A `project.json` that sets a name gives the name. Otherwise a `package.json` in the folder gives it, and a `project.json` without a name is enough to make Nx read that file. Only a `project.json` without a name and without a `package.json` beside it leaves the plugin's name. A `name` in the sub-table has no effect where Nx renames the project ([[EVD-NX-PROJECT-MERGE]], [[EVD-WORKSPACE-PROJECT-NAMES]]). The edges from the workspace project to its members name it by the project Nx has at the workspace folder, as listed in the projects that `createDependencies` receives.
|
|
390
|
+
|
|
391
|
+
**Edges.** For each member, every dependency of kind normal, build or dev that resolves to a crate with an Nx project becomes an edge. That includes a path dependency on a member of another workspace: the target crate keeps its single project in its home workspace, where its own targets run in that [[TERM-WORKSPACE-CONTEXT]]. A path names the crate at the real path of its folder, symbolic links resolved, wherever the graph matches a dependency's path to a project or to a crate that a report describes, because cargo builds the crate it finds there: a path through a link to a crate with a project is an edge to that project. A path dependency on a crate without an Nx project produces no edge to that crate; its files reach the cache key as inputs ([[DES-INPUTS]]). Through such crates, through any number of them, the member gets an edge to each crate with a project that it reaches, with the kinds that cargo builds for it: its own path dependencies of every kind, and behind them only the normal and build dependencies of each crate without a project, because cargo builds the dev-dependencies of no crate but the one it tests. Cargo builds that crate for the member, and its folder alone would miss the files it declares and what lies behind it, which the member's `^` inputs bring over the edge ([[GOAL-TRUSTED-CACHE]]). Behind a crate without a report, such as one whose folder holds `.cargo-checksum.json` or whose report failed ([[DES-METADATA-REPORT]]), what it depends on is unknown, and the plugin guesses no edge there. An entry's `createDependencies` gives the edges of the members that its own `createNodes` found, from its newest call where graph computations overlap, never another entry's, and fails where it can tell that the call is not its entry's ([[DES-DISCOVERY]], "Entries"). Each edge names its two projects by the name Nx gives the project at the crate's root, as listed in the projects that `createDependencies` receives, because a `package.json` or `project.json` may have renamed it ([[EVD-NX-PROJECT-MERGE]]). Edges have Nx's type `implicit`, which names no source file, so that Nx takes them as returned on every graph computation: for the other types, Nx puts back the file dependencies it cached in an earlier computation for each file whose hash is unchanged, and a crate's edges depend on more than its own manifest ([[EVD-NX-EDGE-CACHE]]). The maintainer accepted the cost on 13 November 2026: `nx graph` labels the edges implicit and shows no file for them, and the default dependency reading of Nx release skips implicit edges, so the release flow reads dependents from the manifests instead ([[ADR-RELEASE-DEPENDENTS]]).
|
|
392
|
+
|
|
393
|
+
**Redirected crates.** A workspace's redirections name crates ([[DES-METADATA-REPORT]]): the crate in the folder of a `[patch]` or `[replace]` entry, and for a `paths` entry every crate that discovery finds below its folder as cargo finds them, with every crate at or below that folder that a report describes or that has a project, or the folder itself, as a crate without a report, where it holds none. A folder whose report shows a virtual manifest holds no crate, also where a workspace project lies there. They are matched to projects by their real folders, through symbolic links ([[ADR-REDIRECTION-EDGES]]). The crates that discovery finds for a `paths` entry include the path dependencies, of every kind and inside or outside the folder, of the crates below it ([[DES-METADATA-REPORT]]).
|
|
394
|
+
|
|
395
|
+
- _Direct._ A dependency is redirected when its package name is the redirected crate's, the entry applies to its source (`crates-io`, the URL of a `[patch."<url>"]`, the URL of a `[replace]` specification, which is crates.io without one, or any source for `paths`), and the crate's version, from its report, satisfies the requirement. Cargo resolves it to that crate, so the edge is as real as a path dependency's. A member gets it for its own dependencies of every kind, and for those of the crates it reaches through normal or build dependencies without passing another member of the workspace, which has edges of its own. A requirement or a source that the plugin cannot evaluate, such as a pre-release or a registry named in `[patch.<name>]`, makes the dependency possible, not direct.
|
|
396
|
+
- _Possible._ A member that has a registry or git dependency, of its own or of a path crate that it reaches through normal or build dependencies, and no direct redirection to a redirected crate, gets an edge to it all the same, because a registry or git crate can lead there. The edge is left out where the redirected crate already reaches the member through real dependencies of kind normal or build, that is path dependencies and direct redirections, and where two redirected crates may only possibly use each other: cargo would reject the first as a cycle and can have at most one direction of the second. The member's targets then get the files of the crate and of what cargo builds with it as inputs instead, below.
|
|
397
|
+
- _Assumed._ A member whose only way to a registry or git dependency is a path crate without a report, whose dependencies are not known ([[DES-METADATA-REPORT]]), may use every redirected crate as well, but this weakest kind of use never removes or weakens an edge that exists without it. Its edge is left out, as for a possible use, where the redirected crate reaches the member through real dependencies of kind normal or build, and also where any other edge between the two projects points the opposite way, an edge through crates without a project included, which then stays; the member's targets get the files of the crate and of what cargo builds with it as inputs instead, below.
|
|
398
|
+
|
|
399
|
+
A member that uses a redirected crate without a project, in any of the three kinds, uses each crate with a project behind it as well: those that the redirected crate reaches through its path dependencies of kind normal or build, through any number of crates without a project, by their real folders, as for the edges through such crates above, but never through its dev-dependencies, which cargo builds only where it tests that crate. Such a use has the kind of the member's use of the redirected crate, and the strongest kind where several uses lead to one crate or the crate is redirected itself. It weighs against an edge in the opposite direction as a use of that kind of a redirected crate with a project, with no rule of its own: a direct use is always an edge, a possible or assumed one is left out where the crate reaches the member through real dependencies of kind normal or build, two possible uses in opposite directions are both left out, and an assumed one gives way to any other edge in the opposite direction, which leaves the member the inputs below. Cargo builds such a crate for the member, and the redirected crate's folder alone would miss it and what lies behind it ([[GOAL-TRUSTED-CACHE]]).
|
|
400
|
+
|
|
401
|
+
Where a use of a crate with a project is left out, the member's targets get as inputs what the edge would have brought through `^` inputs ([[DES-INPUTS]]): the files of that crate and of every crate that it reaches through dependencies of kind normal or build, to any depth, with a project or without, by path, matched by real folder, or through a direct redirection of the member's workspace, in which cargo builds them for the member. No dev-dependency counts, because cargo builds the dev-dependencies of none of these crates for the member. The walk ends at the member, which is never among them, so that a way back to it in a cycle brings neither the member nor the crates that depend on it; it also ends at a crate it has met before and at a crate without a report, whose folder counts alone. A registry or git dependency on the way adds no folder: the member's lockfile digest covers the registry and git crates that `Cargo.lock` resolves for it ([[DES-LOCKFILE-HASHING]]), and the member, whose left-out use is possible or assumed, has a use of every redirected crate of its workspace itself. Without these, a change to a crate behind the one whose edge is left out, which cargo compiles into the member, would leave the member's keys unchanged ([[GOAL-TRUSTED-CACHE]]).
|
|
402
|
+
|
|
403
|
+
The edges are thereby a superset of the crates that cargo builds for a member ([[EVD-CARGO-REDIRECTIONS]]). The member itself is never its own target, also behind a redirected crate, and a redirected crate without a project gives no edge to itself, only the input.
|
|
404
|
+
|
|
405
|
+
**External crates.** The graph has no node for an external crate ([[ADR-LOCKFILE-TASK]]). A crate's locked dependencies reach its cache key through the lockfile task of its workspace ([[DES-LOCKFILE-HASHING]]).
|
|
406
|
+
|
|
407
|
+
**Cycles.** A dev-dependency edge that closes a cycle is kept ([[ADR-ALL-DEP-KINDS]]), and so is an edge to a redirected crate or to a crate with a project behind one, apart from those the paragraph on redirected crates leaves out. An edge to a crate with a project behind path dependencies on crates without one is as real as a path dependency's, because cargo builds that crate for the member: it is kept where it closes a cycle, which cargo permits only through a dev-dependency, and it gives way to no other edge. Where it meets an assumed use in the opposite direction, the assumed use gives way and becomes a file input of its member. A dev-dependency that leads back to the member through crates without a project gives no edge, as the member is never its own target. The plugin's targets declare no dependencies on other crates' targets except the lockfile task, which depends on nothing, and under `hakari` the `hakari-check` target, which depends only on the lockfile task ([[REQ-NO-RUST-TASK-DEPS]], [[DES-UNIFICATION]]), so a project cycle does not become a task cycle through them.
|
|
408
|
+
:::
|
|
409
|
+
|
|
410
|
+
:::mara design DES-LOCKFILE-HASHING
|
|
411
|
+
:mid: 01M78FHG7FQWJY49AGS0FVGY2D
|
|
412
|
+
:title: Per-crate lockfile hashing through a lockfile task
|
|
413
|
+
:status: accepted
|
|
414
|
+
:satisfies: REQ-EXTERNAL-DEPS
|
|
415
|
+
|
|
416
|
+
Each Cargo workspace has one target, the lockfile task, that lets cargo bring `Cargo.lock` up to date and then writes a digest of it for each crate. It is named `lockfile` unless `targetNames` renames it, and it belongs to the [[TERM-WORKSPACE-PROJECT]], which is the root crate's project when the root manifest is a package ([[DES-WORKSPACE-TARGETS]]). The graph has no external nodes ([[ADR-LOCKFILE-TASK]]).
|
|
417
|
+
|
|
418
|
+
**Task.** The lockfile task is not cached. Each time it runs, it runs `cargo update --workspace` in the workspace root, with `--locked` in locked mode ([[DES-INVOCATION]]), and then writes the digests from the `Cargo.lock` that cargo leaves. Cargo leaves a current lockfile untouched, and it updates a stale one, or creates a missing one, byte for byte as the crates' own cargo commands would ([[EVD-CARGO-LOCK-CHECK]]). In locked mode cargo fails on a stale or missing lockfile and changes nothing. When cargo fails, for that or any other reason, the task fails with cargo's message, and Nx skips the tasks that depend on it, for which it stores nothing, also with `NX_CACHE_FAILURES=true` ([[DES-DIAGNOSTICS]], [[EVD-NX-24-BATCHES]]). The task uses an executor without a batch implementation, so it never joins a batch ([[TERM-GROUP]]). It must not be cached, because whether cargo changes the lockfile also depends on files outside the repository, such as a `[patch]` in the cargo home's configuration, which Nx cannot hash ([[EVD-NX-24-LOCKFILE-UPDATE]]).
|
|
419
|
+
|
|
420
|
+
**Inputs.** The task's inputs only decide what `nx affected` selects: `Cargo.lock` as a fileset that includes git-ignored files, the root `Cargo.toml`, the `Cargo.toml` of every member and of every path package inside the repository, at the real path of its folder, the configuration files that [[DES-INPUTS]] lists as workspace files, and the plugin input of [[DES-INPUTS]]. The manifests are named from the repository root, because a pattern under the workspace project's root misses the files of the nested crate projects ([[EVD-NX-24-LOCKFILE-UPDATE]]).
|
|
421
|
+
|
|
422
|
+
**Digest.** For each member, the task writes a SHA-256 over the part of the lockfile's graph that the member's entry reaches. The walk starts at the member's entry, takes every dependency an entry lists, passes through path packages and follows `replace = …` to the entry it names. A reference without a source that two entries share by name and version means the entry without a source. `[[patch.unused]]` entries stay out. Each reachable entry gives one line: its name, version, source, checksum and `replace` value, then the strings of its `dependencies` list as the lockfile writes them, in byte order, all joined by tab characters, with an empty field for a value the entry lacks. The digest is the SHA-256 of these lines in byte order, each ended by a line feed, in UTF-8. The dependency strings count, because two current lockfiles can lock the same packages and differ only in which version of a package another package uses ([[EVD-CARGO-LOCK-CHECK]]). The lockfile locks a member with all its features, platforms and dependency kinds, and while cargo calls the lockfile current, the packages cargo compiles for the crate lie in that closure ([[EVD-CARGO-LOCK-CHECK]]). The digest holds no features; those a crate asks for reach its key through its manifest and its target options ([[DES-INPUTS]]).
|
|
423
|
+
|
|
424
|
+
**Where the digests live.** The digests are the task's outputs, in one folder per workspace under `.nx/workspace-data/nx-rust/lockfile/` in the repository, one file per member named after its package name. The folder's name is one path segment: the workspace's root folder relative to the repository root, with `/` and every other byte than a letter, a digit, `.`, `_` and `-` written as `%` and two hexadecimal digits, and `%2E` for the repository root, so that the folders of nested workspaces never contain each other and a glob over them reads no character specially. Nx hashes a dependency's output only inside the repository ([[EVD-NX-24-LOCKFILE-TASK]]). `nx init` writes `.nx/workspace-data` into `.gitignore`, and Nx always leaves that folder out of its file map ([[EVD-NX-24-SETUP]]).
|
|
425
|
+
|
|
426
|
+
**Crate targets.** Every cached target of a member other than `fmt-check` depends on the lockfile task of the member's workspace and hashes the member's digest through a `dependentTasksOutputFiles` input; `doc` hashes the digests of all members, and so does every such target under the feature strategies that build with the whole workspace's features, `cargo` and `workspace-build` ([[DES-INPUTS]]). Under `hakari`, those targets also depend on the workspace's `hakari-check`, which depends on the lockfile task ([[DES-UNIFICATION]]). None of them has `Cargo.lock` as a plain file input: Nx hashes such a task before the run starts, before the lockfile task can rewrite the file, and restores the result for the old lockfile ([[EVD-NX-24-LOCKFILE-UPDATE]]). The dependency names the project by the workspace's root folder, through Nx's `directory:` project pattern, so that it holds where a `package.json` or `project.json` gives the workspace project another name ([[DES-PROJECT-GRAPH]]). `fmt` and `fmt-check` do not depend on the lockfile task, because `cargo fmt` reads no lockfile ([[EVD-CARGO-LOCK-CHECK]]). A crate that a member of another workspace uses by path runs its tasks in its home workspace, keyed on that workspace's digest. The consumer's digest covers that crate's dependencies as the consumer's lockfile resolves them.
|
|
427
|
+
|
|
428
|
+
**Post-check.** The plugin's `preTasksExecution` hook gives every `nx` command an id of its own in `NX_RUST_COMMAND_ID`, which no target names as an input. The lockfile task writes each digest to the shared digest file, which Nx hashes, and to a copy private to its command, in the folder `commands/<id>` of the workspace's digest folder, which no digest input reaches. After the last cargo call of a cached task that depends on the lockfile task, in a batch after the last call of its group ([[DES-BATCH]]), the executor computes again from `Cargo.lock` each digest that it compares. It compares every digest that the task's key holds: the crate's own, or the digests of all members for `doc` and for every target under the `cargo` and `workspace-build` strategies ([[DES-INPUTS]]), also in a group of one crate. Under `hakari`, a task that shared its command compares the digests of all members as well, although its key holds its own, because its result rests on the drift check, which judged the whole lockfile ([[DES-UNIFICATION]]); a task that ran in a group of one crate compares its own, which with the hack crate's manifest covers all that its command depends on. A task shared its command where the command selected more than its crate; a task whose group was left with that one task, because Nx restored the others or the command names one crate, selected its crate alone and compares its own, as the control plane settled on 16 November 2026, because its command resolves features for its crate alone, as in a group of one crate. The target's metadata names the crate's own member and says whether the key holds every member's digest; the other members come from the metadata of the lockfile task that the task depends on, which names them once for the workspace, so that the graph does not carry every member on every target. It compares the crate's own digest first, and its message names the first digest that differs, so that it names another member only where the crate's own stayed the same. The task passes only when each compared digest, its command's private copy and the shared digest file as it is then are equal. Otherwise it fails, as the check of [[DES-BUILD-INPUT-CHECK]] does, which runs in the same step, and so does a task whose command has no private copy. For such a failed task Nx stores nothing by default, and with `NX_CACHE_FAILURES=true` the failure, which it replays for the same key; it stores no successful result in either case ([[ADR-CACHED-FAILURES]]). They differ when a manifest or the lockfile changed while the run went on ([[EVD-NX-24-LOCKFILE-UPDATE]]), also through another `nx` command, whose lockfile task rewrites the shared file after Nx has hashed it, so that the shared file alone would describe the other command's lockfile. A lockfile change that moves only another member's packages, as a new commit of a git dependency that only a sibling reaches, can change the features that a build of the whole workspace gives the crate while its own digest stays the same ([[EVD-HAKARI-UNIFICATION]], "A sibling's lockfile change"), so comparing the crate's own digest alone would store its result under a key that no longer describes what cargo built. The command's `postTasksExecution` hook removes its private copies, and a lockfile task removes those older than a day, which a stopped command left. One window remains: two other commands that change the lockfile and change it back between this command's lockfile task and the hashing of its crate task give the key a digest that neither the private copy nor the final lockfile shows. A task of such a target whose task graph holds no dependency on the lockfile task, in a run that does not exclude task dependencies, has a key without a digest, and fails before cargo runs for the same reason, as where a `project.json` replaces the target's `dependsOn`, which [[DES-TARGET-DEFAULT-GUARD]] leaves to the repository.
|
|
429
|
+
|
|
430
|
+
**No lockfile task.** Where Nx hands a workspace's root manifest to no entry of the plugin, because the entries' `include` and `exclude`, `.gitignore` or `.nxignore` keep it out, no project of the plugin lies at the workspace's root folder, and the workspace has no lockfile task. The entry that receives the workspace's other manifests knows this from what Nx hands it: no other entry can receive the root manifest, because graph creation refuses two entries that receive manifests of one workspace ([[DES-PLUGIN-OPTIONS]], "Several entries"). It then leaves the crates' targets that would read a digest uncached, with the workspace's `Cargo.lock` as a file input for `nx affected` ([[DES-INPUTS]]), and warns, naming the root manifest ([[DES-DIAGNOSTICS]]), so that the crates' tasks run as plain cargo does. The failure before cargo stays for what graph creation cannot see.
|
|
431
|
+
|
|
432
|
+
**Excluded dependencies.** A command run with `--exclude-task-dependencies` runs no lockfile task, and a crate task's digest input then contributes nothing to its key ([[EVD-NX-24-LOCKFILE-UPDATE]]). The plugin's `preTasksExecution` hook, the one that [[DES-UNKNOWN-OPTIONS]] uses, parses the command's arguments as Nx does. It sets `NX_RUST_RUN_ID` to a value that no other run has when they exclude task dependencies, and to the empty string otherwise. Every cached crate target that depends on the lockfile task has that variable as an `env` input, so such a run runs those tasks, nothing it stores is restored again, and a normal run keeps its keys. A target default that replaces a crate target's `dependsOn` drops the lockfile task in the same way, and [[DES-TARGET-DEFAULT-GUARD]] reports it as an error.
|
|
433
|
+
|
|
434
|
+
**nx affected.** A change to `Cargo.lock` or to a manifest selects the lockfile task through its inputs and, through its output, every cached target of the workspace's crates that depends on it. Those whose digests in their keys did not change are restored from the cache ([[EVD-NX-24-LOCKFILE-UPDATE]]): under `hakari`, those whose own digest stayed the same; under `cargo` and `workspace-build`, none once any member's digest changed ([[DES-INPUTS]]). Nx counts the JS lockfile as configuration of a project at the repository root, so for a workspace whose project lies there, any change to the JS lockfile selects that project's tasks, the lockfile task among them, and through it the tasks of its crates; the crate tasks are restored from the cache, apart from those of a crate at the repository root and of the crates that depend on it, whose keys follow the JS lockfile as the workspace's `doc` does ([[DES-INPUTS]]), and the uncached lockfile task runs. This limit is accepted ([[EVD-NX-24-PLUGIN-VERSION]]).
|
|
435
|
+
|
|
436
|
+
**Batching.** Nx runs the lockfile task before the crate tasks of its workspace, which then become runnable together and form their groups as [[DES-BATCH]] describes ([[EVD-NX-24-LOCKFILE-TASK]]).
|
|
437
|
+
|
|
438
|
+
**Root package.** When the root manifest is a package, `Cargo.lock` lies in that crate's folder, as it does in the folder of every [[TERM-STANDALONE-CRATE]]. The crate's own files leave it out ([[DES-INPUTS]]), so that it reaches the keys of that crate and of the crates that depend on it only through the digests ([[EVD-NX-24-LOCKFILE-TASK]]).
|
|
439
|
+
|
|
440
|
+
**Workspace-level targets.** `audit`, `deny` and `update`, which are not cached, take the whole `Cargo.lock` as a file input together with the configuration of their tool; that input only decides what `nx affected` selects ([[DES-WORKSPACE-TARGETS]]).
|
|
441
|
+
|
|
442
|
+
**Merged project.** When the workspace folder also is an Nx project, a `package.json` script or a `project.json` target with the lockfile task's name replaces it, as it replaces any inferred target ([[EVD-NX-PROJECT-MERGE]], [[RISK-MIXED-PROJECT-MERGE]]). The crates' cached targets still depend on the target of that name, which writes no digest and no private copy, so their tasks fail and Nx stores no result for them: before cargo, where the executor finds no lockfile task among a task's dependencies, and after cargo through the check above, where it takes the replacement for one. With a `project.json` target that ran a command, cargo ran and the check after it failed, with a message that blames a change of the lockfile during the run ([[EVD-NX-MIXED-CONSUMER]]). Graph creation reports nothing ([[ADR-MIXED-PROJECT-TARGETS]]). Renaming the lockfile task through `targetNames`, or renaming the script or target, resolves it, as the user guidance of [[REQ-MIXED-PROJECTS]] says.
|
|
443
|
+
|
|
444
|
+
**Redirected crates.** A `paths` override, and the contents of a path package that a crate reaches only through `[patch]` or `[replace]`, leave no trace in the digest; the edges to redirected crates bring their files into the keys of the members that may use them through `^` inputs ([[DES-PROJECT-GRAPH]], [[ADR-REDIRECTION-EDGES]]).
|
|
445
|
+
:::
|
package/package.json
CHANGED
|
@@ -45,10 +45,17 @@ export interface UnreadableFile {
|
|
|
45
45
|
* @param env Where `CARGO_HOME` is read from.
|
|
46
46
|
*/
|
|
47
47
|
export declare function buildSettings(folder: string, env: Readonly<Record<string, string | undefined>>, key: string): BuildSetting[];
|
|
48
|
+
/**
|
|
49
|
+
* The values of `<table>.<key>` in the configuration files that cargo reads
|
|
50
|
+
* for a command started in `folder`, found and ordered as
|
|
51
|
+
* {@link buildSettings} finds those of `build.<key>`, such as the values of
|
|
52
|
+
* `env.CLIPPY_CONF_DIR`.
|
|
53
|
+
*/
|
|
54
|
+
export declare function tableSettings(folder: string, env: Readonly<Record<string, string | undefined>>, table: string, key: string): BuildSetting[];
|
|
48
55
|
/**
|
|
49
56
|
* {@link buildSettings}, with each file that exists but cannot be read or
|
|
50
57
|
* parsed in its place in the order, for a reader that must not guess past
|
|
51
58
|
* it. Only a file that does not exist counts as absent; a file whose folder
|
|
52
59
|
* is no folder, such as a `.cargo` that is a file, counts as unreadable.
|
|
53
60
|
*/
|
|
54
|
-
export declare function buildSettingsAndUnreadable(folder: string, env: Readonly<Record<string, string | undefined>>, key: string): (BuildSetting | UnreadableFile)[];
|
|
61
|
+
export declare function buildSettingsAndUnreadable(folder: string, env: Readonly<Record<string, string | undefined>>, key: string, table?: string): (BuildSetting | UnreadableFile)[];
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
3
|
exports.buildSettings = buildSettings;
|
|
4
|
+
exports.tableSettings = tableSettings;
|
|
4
5
|
exports.buildSettingsAndUnreadable = buildSettingsAndUnreadable;
|
|
5
6
|
const node_fs_1 = require("node:fs");
|
|
6
7
|
const node_path_1 = require("node:path");
|
|
@@ -33,7 +34,16 @@ const redirections_1 = require("./redirections");
|
|
|
33
34
|
* @param env Where `CARGO_HOME` is read from.
|
|
34
35
|
*/
|
|
35
36
|
function buildSettings(folder, env, key) {
|
|
36
|
-
return
|
|
37
|
+
return tableSettings(folder, env, "build", key);
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* The values of `<table>.<key>` in the configuration files that cargo reads
|
|
41
|
+
* for a command started in `folder`, found and ordered as
|
|
42
|
+
* {@link buildSettings} finds those of `build.<key>`, such as the values of
|
|
43
|
+
* `env.CLIPPY_CONF_DIR`.
|
|
44
|
+
*/
|
|
45
|
+
function tableSettings(folder, env, table, key) {
|
|
46
|
+
return buildSettingsAndUnreadable(folder, env, key, table).filter((entry) => !("unreadable" in entry));
|
|
37
47
|
}
|
|
38
48
|
/**
|
|
39
49
|
* {@link buildSettings}, with each file that exists but cannot be read or
|
|
@@ -41,7 +51,7 @@ function buildSettings(folder, env, key) {
|
|
|
41
51
|
* it. Only a file that does not exist counts as absent; a file whose folder
|
|
42
52
|
* is no folder, such as a `.cargo` that is a file, counts as unreadable.
|
|
43
53
|
*/
|
|
44
|
-
function buildSettingsAndUnreadable(folder, env, key) {
|
|
54
|
+
function buildSettingsAndUnreadable(folder, env, key, table = "build") {
|
|
45
55
|
const entries = [];
|
|
46
56
|
const walked = new Set();
|
|
47
57
|
for (const [legacy, current] of (0, redirections_1.configFiles)(folder, env)) {
|
|
@@ -50,15 +60,15 @@ function buildSettingsAndUnreadable(folder, env, key) {
|
|
|
50
60
|
walked.add(file);
|
|
51
61
|
// A record of its own, so that a file that a deeper file includes
|
|
52
62
|
// still counts here, where Cargo 1.91 reads it.
|
|
53
|
-
collect(file, key, false, new Set(), entries);
|
|
63
|
+
collect(file, table, key, false, new Set(), entries);
|
|
54
64
|
}
|
|
55
65
|
}
|
|
56
66
|
return entries;
|
|
57
67
|
}
|
|
58
|
-
// Adds the value of `file` and
|
|
59
|
-
// precedence: the file's own value, then its
|
|
60
|
-
// first, each with its own includes after it.
|
|
61
|
-
function collect(file, key, included, read, entries) {
|
|
68
|
+
// Adds the value of `<tableName>.<key>` in `file` and in the files it
|
|
69
|
+
// includes, in descending precedence: the file's own value, then its
|
|
70
|
+
// includes from the last to the first, each with its own includes after it.
|
|
71
|
+
function collect(file, tableName, key, included, read, entries) {
|
|
62
72
|
if (read.has(file)) {
|
|
63
73
|
return;
|
|
64
74
|
}
|
|
@@ -73,15 +83,15 @@ function collect(file, key, included, read, entries) {
|
|
|
73
83
|
}
|
|
74
84
|
return;
|
|
75
85
|
}
|
|
76
|
-
const
|
|
77
|
-
if (
|
|
78
|
-
entries.push({ file, value:
|
|
86
|
+
const settings = asTable(table[tableName]);
|
|
87
|
+
if (settings[key] !== undefined) {
|
|
88
|
+
entries.push({ file, value: settings[key], included });
|
|
79
89
|
}
|
|
80
90
|
const includes = Array.isArray(table.include) ? table.include : [table.include];
|
|
81
91
|
for (const include of [...includes].reverse()) {
|
|
82
92
|
const path = typeof include === "string" ? include : asTable(include).path;
|
|
83
93
|
if (typeof path === "string") {
|
|
84
|
-
collect((0, node_path_1.resolve)((0, node_path_1.dirname)(file), path), key, true, read, entries);
|
|
94
|
+
collect((0, node_path_1.resolve)((0, node_path_1.dirname)(file), path), tableName, key, true, read, entries);
|
|
85
95
|
}
|
|
86
96
|
}
|
|
87
97
|
}
|