@convesoft/nx-rust 0.0.0 → 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 (418) hide show
  1. package/LICENSE-APACHE +201 -0
  2. package/LICENSE-MIT +21 -0
  3. package/PLUGIN.md +106 -0
  4. package/README.md +51 -1
  5. package/docs/artifacts.mara.md +374 -0
  6. package/docs/caching.mara.md +999 -0
  7. package/docs/ci.mara.md +308 -0
  8. package/docs/configuration.mara.md +508 -0
  9. package/docs/decisions.mara.md +3267 -0
  10. package/docs/execution.mara.md +533 -0
  11. package/docs/index.mara.md +51 -0
  12. package/docs/product.mara.md +366 -0
  13. package/docs/release.mara.md +493 -0
  14. package/docs/setup.mara.md +486 -0
  15. package/docs/targets.mara.md +704 -0
  16. package/docs/testing.mara.md +431 -0
  17. package/docs/verification.mara.md +465 -0
  18. package/docs/workspaces.mara.md +445 -0
  19. package/executors.json +35 -0
  20. package/generators.json +19 -0
  21. package/package.json +17 -4
  22. package/src/cargo/build-settings.d.ts +61 -0
  23. package/src/cargo/build-settings.js +103 -0
  24. package/src/cargo/build-settings.js.map +1 -0
  25. package/src/cargo/configured-runner.d.ts +36 -0
  26. package/src/cargo/configured-runner.js +99 -0
  27. package/src/cargo/configured-runner.js.map +1 -0
  28. package/src/cargo/configured-tools.d.ts +35 -0
  29. package/src/cargo/configured-tools.js +46 -0
  30. package/src/cargo/configured-tools.js.map +1 -0
  31. package/src/cargo/dep-info-basedir.d.ts +18 -0
  32. package/src/cargo/dep-info-basedir.js +38 -0
  33. package/src/cargo/dep-info-basedir.js.map +1 -0
  34. package/src/cargo/directories.d.ts +40 -0
  35. package/src/cargo/directories.js +89 -0
  36. package/src/cargo/directories.js.map +1 -0
  37. package/src/cargo/host-triple.d.ts +7 -0
  38. package/src/cargo/host-triple.js +21 -0
  39. package/src/cargo/host-triple.js.map +1 -0
  40. package/src/cargo/lockfile.d.ts +63 -0
  41. package/src/cargo/lockfile.js +157 -0
  42. package/src/cargo/lockfile.js.map +1 -0
  43. package/src/cargo/metadata.d.ts +114 -0
  44. package/src/cargo/metadata.js +37 -0
  45. package/src/cargo/metadata.js.map +1 -0
  46. package/src/cargo/package-specs.d.ts +54 -0
  47. package/src/cargo/package-specs.js +109 -0
  48. package/src/cargo/package-specs.js.map +1 -0
  49. package/src/cargo/paths-crates.d.ts +27 -0
  50. package/src/cargo/paths-crates.js +69 -0
  51. package/src/cargo/paths-crates.js.map +1 -0
  52. package/src/cargo/print-artifact-folders.d.ts +1 -0
  53. package/src/cargo/print-artifact-folders.js +58 -0
  54. package/src/cargo/print-artifact-folders.js.map +1 -0
  55. package/src/cargo/redirections.d.ts +90 -0
  56. package/src/cargo/redirections.js +200 -0
  57. package/src/cargo/redirections.js.map +1 -0
  58. package/src/cargo/run-cargo.d.ts +31 -0
  59. package/src/cargo/run-cargo.js +75 -0
  60. package/src/cargo/run-cargo.js.map +1 -0
  61. package/src/cargo/target-triples.d.ts +98 -0
  62. package/src/cargo/target-triples.js +265 -0
  63. package/src/cargo/target-triples.js.map +1 -0
  64. package/src/cargo/version-req.d.ts +12 -0
  65. package/src/cargo/version-req.js +122 -0
  66. package/src/cargo/version-req.js.map +1 -0
  67. package/src/cargo/warnings-setting.d.ts +24 -0
  68. package/src/cargo/warnings-setting.js +81 -0
  69. package/src/cargo/warnings-setting.js.map +1 -0
  70. package/src/compatibility/cargo-version.d.ts +43 -0
  71. package/src/compatibility/cargo-version.js +83 -0
  72. package/src/compatibility/cargo-version.js.map +1 -0
  73. package/src/compatibility/nx-bridge.d.ts +312 -0
  74. package/src/compatibility/nx-bridge.js +407 -0
  75. package/src/compatibility/nx-bridge.js.map +1 -0
  76. package/src/compatibility/nx-version.d.ts +104 -0
  77. package/src/compatibility/nx-version.js +272 -0
  78. package/src/compatibility/nx-version.js.map +1 -0
  79. package/src/executors/affected-inputs.d.ts +29 -0
  80. package/src/executors/affected-inputs.js +259 -0
  81. package/src/executors/affected-inputs.js.map +1 -0
  82. package/src/executors/affected-run.d.ts +54 -0
  83. package/src/executors/affected-run.js +394 -0
  84. package/src/executors/affected-run.js.map +1 -0
  85. package/src/executors/affected.d.ts +239 -0
  86. package/src/executors/affected.js +589 -0
  87. package/src/executors/affected.js.map +1 -0
  88. package/src/executors/baseline-context.d.ts +85 -0
  89. package/src/executors/baseline-context.js +227 -0
  90. package/src/executors/baseline-context.js.map +1 -0
  91. package/src/executors/baseline.d.ts +123 -0
  92. package/src/executors/baseline.js +356 -0
  93. package/src/executors/baseline.js.map +1 -0
  94. package/src/executors/batch.d.ts +75 -0
  95. package/src/executors/batch.js +434 -0
  96. package/src/executors/batch.js.map +1 -0
  97. package/src/executors/build-records.d.ts +110 -0
  98. package/src/executors/build-records.js +267 -0
  99. package/src/executors/build-records.js.map +1 -0
  100. package/src/executors/cargo/executor.d.ts +28 -0
  101. package/src/executors/cargo/executor.js +58 -0
  102. package/src/executors/cargo/executor.js.map +1 -0
  103. package/src/executors/cargo/schema.json +58 -0
  104. package/src/executors/cargo-invocation.d.ts +81 -0
  105. package/src/executors/cargo-invocation.js +109 -0
  106. package/src/executors/cargo-invocation.js.map +1 -0
  107. package/src/executors/cargo-output.d.ts +218 -0
  108. package/src/executors/cargo-output.js +660 -0
  109. package/src/executors/cargo-output.js.map +1 -0
  110. package/src/executors/command.d.ts +331 -0
  111. package/src/executors/command.js +547 -0
  112. package/src/executors/command.js.map +1 -0
  113. package/src/executors/coverage-baseline.d.ts +23 -0
  114. package/src/executors/coverage-baseline.js +284 -0
  115. package/src/executors/coverage-baseline.js.map +1 -0
  116. package/src/executors/declared-options.d.ts +21 -0
  117. package/src/executors/declared-options.js +58 -0
  118. package/src/executors/declared-options.js.map +1 -0
  119. package/src/executors/denied-warnings.d.ts +99 -0
  120. package/src/executors/denied-warnings.js +188 -0
  121. package/src/executors/denied-warnings.js.map +1 -0
  122. package/src/executors/digests.d.ts +94 -0
  123. package/src/executors/digests.js +190 -0
  124. package/src/executors/digests.js.map +1 -0
  125. package/src/executors/dotenv-check.d.ts +79 -0
  126. package/src/executors/dotenv-check.js +553 -0
  127. package/src/executors/dotenv-check.js.map +1 -0
  128. package/src/executors/group-invocations.d.ts +80 -0
  129. package/src/executors/group-invocations.js +253 -0
  130. package/src/executors/group-invocations.js.map +1 -0
  131. package/src/executors/group-run.d.ts +114 -0
  132. package/src/executors/group-run.js +601 -0
  133. package/src/executors/group-run.js.map +1 -0
  134. package/src/executors/groups.d.ts +118 -0
  135. package/src/executors/groups.js +304 -0
  136. package/src/executors/groups.js.map +1 -0
  137. package/src/executors/input-check.d.ts +52 -0
  138. package/src/executors/input-check.js +271 -0
  139. package/src/executors/input-check.js.map +1 -0
  140. package/src/executors/kept-files.d.ts +98 -0
  141. package/src/executors/kept-files.js +341 -0
  142. package/src/executors/kept-files.js.map +1 -0
  143. package/src/executors/lockfile/executor.d.ts +16 -0
  144. package/src/executors/lockfile/executor.js +37 -0
  145. package/src/executors/lockfile/executor.js.map +1 -0
  146. package/src/executors/lockfile/schema.json +50 -0
  147. package/src/executors/napi-build.d.ts +73 -0
  148. package/src/executors/napi-build.js +420 -0
  149. package/src/executors/napi-build.js.map +1 -0
  150. package/src/executors/nextest.d.ts +189 -0
  151. package/src/executors/nextest.js +504 -0
  152. package/src/executors/nextest.js.map +1 -0
  153. package/src/executors/nx-command.d.ts +95 -0
  154. package/src/executors/nx-command.js +205 -0
  155. package/src/executors/nx-command.js.map +1 -0
  156. package/src/executors/nx-task-files.d.ts +82 -0
  157. package/src/executors/nx-task-files.js +156 -0
  158. package/src/executors/nx-task-files.js.map +1 -0
  159. package/src/executors/print-test-mode.d.ts +1 -0
  160. package/src/executors/print-test-mode.js +25 -0
  161. package/src/executors/print-test-mode.js.map +1 -0
  162. package/src/executors/release-publish/executor.d.ts +24 -0
  163. package/src/executors/release-publish/executor.js +165 -0
  164. package/src/executors/release-publish/executor.js.map +1 -0
  165. package/src/executors/release-publish/schema.json +30 -0
  166. package/src/executors/run/executor.d.ts +12 -0
  167. package/src/executors/run/executor.js +27 -0
  168. package/src/executors/run/executor.js.map +1 -0
  169. package/src/executors/run/schema.json +45 -0
  170. package/src/executors/runner-script.d.ts +12 -0
  171. package/src/executors/runner-script.js +22 -0
  172. package/src/executors/runner-script.js.map +1 -0
  173. package/src/executors/runtime-input-check.d.ts +24 -0
  174. package/src/executors/runtime-input-check.js +87 -0
  175. package/src/executors/runtime-input-check.js.map +1 -0
  176. package/src/executors/shared-artifacts.d.ts +44 -0
  177. package/src/executors/shared-artifacts.js +132 -0
  178. package/src/executors/shared-artifacts.js.map +1 -0
  179. package/src/executors/split-words.d.ts +24 -0
  180. package/src/executors/split-words.js +111 -0
  181. package/src/executors/split-words.js.map +1 -0
  182. package/src/executors/stage.d.ts +163 -0
  183. package/src/executors/stage.js +526 -0
  184. package/src/executors/stage.js.map +1 -0
  185. package/src/executors/staged-run.d.ts +24 -0
  186. package/src/executors/staged-run.js +110 -0
  187. package/src/executors/staged-run.js.map +1 -0
  188. package/src/executors/task-env.d.ts +271 -0
  189. package/src/executors/task-env.js +494 -0
  190. package/src/executors/task-env.js.map +1 -0
  191. package/src/executors/task-execution.d.ts +61 -0
  192. package/src/executors/task-execution.js +122 -0
  193. package/src/executors/task-execution.js.map +1 -0
  194. package/src/executors/task-guards.d.ts +112 -0
  195. package/src/executors/task-guards.js +435 -0
  196. package/src/executors/task-guards.js.map +1 -0
  197. package/src/executors/task-options.d.ts +114 -0
  198. package/src/executors/task-options.js +258 -0
  199. package/src/executors/task-options.js.map +1 -0
  200. package/src/executors/task.d.ts +166 -0
  201. package/src/executors/task.js +527 -0
  202. package/src/executors/task.js.map +1 -0
  203. package/src/executors/test-mode.d.ts +185 -0
  204. package/src/executors/test-mode.js +397 -0
  205. package/src/executors/test-mode.js.map +1 -0
  206. package/src/executors/test-runner.d.ts +44 -0
  207. package/src/executors/test-runner.js +159 -0
  208. package/src/executors/test-runner.js.map +1 -0
  209. package/src/executors/test-steps.d.ts +121 -0
  210. package/src/executors/test-steps.js +566 -0
  211. package/src/executors/test-steps.js.map +1 -0
  212. package/src/executors/wasm-build.d.ts +56 -0
  213. package/src/executors/wasm-build.js +216 -0
  214. package/src/executors/wasm-build.js.map +1 -0
  215. package/src/generators/crate/binary.schema.json +28 -0
  216. package/src/generators/crate/crate.d.ts +24 -0
  217. package/src/generators/crate/crate.js +108 -0
  218. package/src/generators/crate/crate.js.map +1 -0
  219. package/src/generators/crate/enclosing-workspace.d.ts +25 -0
  220. package/src/generators/crate/enclosing-workspace.js +58 -0
  221. package/src/generators/crate/enclosing-workspace.js.map +1 -0
  222. package/src/generators/crate/library.schema.json +28 -0
  223. package/src/generators/init/graph-check.d.ts +81 -0
  224. package/src/generators/init/graph-check.js +299 -0
  225. package/src/generators/init/graph-check.js.map +1 -0
  226. package/src/generators/init/init.d.ts +23 -0
  227. package/src/generators/init/init.js +113 -0
  228. package/src/generators/init/init.js.map +1 -0
  229. package/src/generators/init/report.d.ts +19 -0
  230. package/src/generators/init/report.js +93 -0
  231. package/src/generators/init/report.js.map +1 -0
  232. package/src/generators/init/schema.json +9 -0
  233. package/src/graph/artifact-kinds.d.ts +29 -0
  234. package/src/graph/artifact-kinds.js +50 -0
  235. package/src/graph/artifact-kinds.js.map +1 -0
  236. package/src/graph/artifact-names.d.ts +97 -0
  237. package/src/graph/artifact-names.js +276 -0
  238. package/src/graph/artifact-names.js.map +1 -0
  239. package/src/graph/build-records.d.ts +74 -0
  240. package/src/graph/build-records.js +104 -0
  241. package/src/graph/build-records.js.map +1 -0
  242. package/src/graph/caching.d.ts +148 -0
  243. package/src/graph/caching.js +681 -0
  244. package/src/graph/caching.js.map +1 -0
  245. package/src/graph/clippy-input.d.ts +53 -0
  246. package/src/graph/clippy-input.js +107 -0
  247. package/src/graph/clippy-input.js.map +1 -0
  248. package/src/graph/collisions.d.ts +113 -0
  249. package/src/graph/collisions.js +156 -0
  250. package/src/graph/collisions.js.map +1 -0
  251. package/src/graph/computation-reports.d.ts +89 -0
  252. package/src/graph/computation-reports.js +216 -0
  253. package/src/graph/computation-reports.js.map +1 -0
  254. package/src/graph/declared-files.d.ts +190 -0
  255. package/src/graph/declared-files.js +600 -0
  256. package/src/graph/declared-files.js.map +1 -0
  257. package/src/graph/discovery.d.ts +190 -0
  258. package/src/graph/discovery.js +661 -0
  259. package/src/graph/discovery.js.map +1 -0
  260. package/src/graph/edges.d.ts +25 -0
  261. package/src/graph/edges.js +94 -0
  262. package/src/graph/edges.js.map +1 -0
  263. package/src/graph/entries.d.ts +83 -0
  264. package/src/graph/entries.js +259 -0
  265. package/src/graph/entries.js.map +1 -0
  266. package/src/graph/inputs.d.ts +422 -0
  267. package/src/graph/inputs.js +756 -0
  268. package/src/graph/inputs.js.map +1 -0
  269. package/src/graph/lockfile-task.d.ts +74 -0
  270. package/src/graph/lockfile-task.js +105 -0
  271. package/src/graph/lockfile-task.js.map +1 -0
  272. package/src/graph/names.d.ts +41 -0
  273. package/src/graph/names.js +34 -0
  274. package/src/graph/names.js.map +1 -0
  275. package/src/graph/napi.d.ts +107 -0
  276. package/src/graph/napi.js +206 -0
  277. package/src/graph/napi.js.map +1 -0
  278. package/src/graph/nx-glob.d.ts +36 -0
  279. package/src/graph/nx-glob.js +152 -0
  280. package/src/graph/nx-glob.js.map +1 -0
  281. package/src/graph/nx-internals.d.ts +57 -0
  282. package/src/graph/nx-internals.js +128 -0
  283. package/src/graph/nx-internals.js.map +1 -0
  284. package/src/graph/options.d.ts +32 -0
  285. package/src/graph/options.js +80 -0
  286. package/src/graph/options.js.map +1 -0
  287. package/src/graph/outputs.d.ts +75 -0
  288. package/src/graph/outputs.js +140 -0
  289. package/src/graph/outputs.js.map +1 -0
  290. package/src/graph/path-dependencies.d.ts +122 -0
  291. package/src/graph/path-dependencies.js +459 -0
  292. package/src/graph/path-dependencies.js.map +1 -0
  293. package/src/graph/plugin-package.d.ts +36 -0
  294. package/src/graph/plugin-package.js +132 -0
  295. package/src/graph/plugin-package.js.map +1 -0
  296. package/src/graph/plugin-version.d.ts +20 -0
  297. package/src/graph/plugin-version.js +153 -0
  298. package/src/graph/plugin-version.js.map +1 -0
  299. package/src/graph/projects.d.ts +141 -0
  300. package/src/graph/projects.js +193 -0
  301. package/src/graph/projects.js.map +1 -0
  302. package/src/graph/reached-projects.d.ts +46 -0
  303. package/src/graph/reached-projects.js +102 -0
  304. package/src/graph/reached-projects.js.map +1 -0
  305. package/src/graph/real-path.d.ts +47 -0
  306. package/src/graph/real-path.js +113 -0
  307. package/src/graph/real-path.js.map +1 -0
  308. package/src/graph/redirected-uses.d.ts +98 -0
  309. package/src/graph/redirected-uses.js +434 -0
  310. package/src/graph/redirected-uses.js.map +1 -0
  311. package/src/graph/registration.d.ts +121 -0
  312. package/src/graph/registration.js +233 -0
  313. package/src/graph/registration.js.map +1 -0
  314. package/src/graph/rustfmt-config.d.ts +42 -0
  315. package/src/graph/rustfmt-config.js +173 -0
  316. package/src/graph/rustfmt-config.js.map +1 -0
  317. package/src/graph/script-input.d.ts +46 -0
  318. package/src/graph/script-input.js +65 -0
  319. package/src/graph/script-input.js.map +1 -0
  320. package/src/graph/settings.d.ts +178 -0
  321. package/src/graph/settings.js +479 -0
  322. package/src/graph/settings.js.map +1 -0
  323. package/src/graph/target-defaults-causes.d.ts +33 -0
  324. package/src/graph/target-defaults-causes.js +202 -0
  325. package/src/graph/target-defaults-causes.js.map +1 -0
  326. package/src/graph/target-defaults-layers.d.ts +186 -0
  327. package/src/graph/target-defaults-layers.js +420 -0
  328. package/src/graph/target-defaults-layers.js.map +1 -0
  329. package/src/graph/target-defaults-meaning.d.ts +95 -0
  330. package/src/graph/target-defaults-meaning.js +292 -0
  331. package/src/graph/target-defaults-meaning.js.map +1 -0
  332. package/src/graph/target-defaults-report.d.ts +77 -0
  333. package/src/graph/target-defaults-report.js +242 -0
  334. package/src/graph/target-defaults-report.js.map +1 -0
  335. package/src/graph/target-defaults.d.ts +79 -0
  336. package/src/graph/target-defaults.js +425 -0
  337. package/src/graph/target-defaults.js.map +1 -0
  338. package/src/graph/target-fields.d.ts +16 -0
  339. package/src/graph/target-fields.js +134 -0
  340. package/src/graph/target-fields.js.map +1 -0
  341. package/src/graph/target-tables.d.ts +45 -0
  342. package/src/graph/target-tables.js +299 -0
  343. package/src/graph/target-tables.js.map +1 -0
  344. package/src/graph/targets.d.ts +371 -0
  345. package/src/graph/targets.js +408 -0
  346. package/src/graph/targets.js.map +1 -0
  347. package/src/graph/unification.d.ts +141 -0
  348. package/src/graph/unification.js +459 -0
  349. package/src/graph/unification.js.map +1 -0
  350. package/src/graph/unignored-directories.d.ts +25 -0
  351. package/src/graph/unignored-directories.js +89 -0
  352. package/src/graph/unignored-directories.js.map +1 -0
  353. package/src/graph/visibility.d.ts +17 -0
  354. package/src/graph/visibility.js +67 -0
  355. package/src/graph/visibility.js.map +1 -0
  356. package/src/graph/warnings.d.ts +38 -0
  357. package/src/graph/warnings.js +77 -0
  358. package/src/graph/warnings.js.map +1 -0
  359. package/src/graph/wasm.d.ts +56 -0
  360. package/src/graph/wasm.js +77 -0
  361. package/src/graph/wasm.js.map +1 -0
  362. package/src/index.d.ts +68 -0
  363. package/src/index.js +109 -0
  364. package/src/index.js.map +1 -0
  365. package/src/release/manifests.d.ts +95 -0
  366. package/src/release/manifests.js +164 -0
  367. package/src/release/manifests.js.map +1 -0
  368. package/src/release/places.d.ts +127 -0
  369. package/src/release/places.js +368 -0
  370. package/src/release/places.js.map +1 -0
  371. package/src/release/publish-cargo.d.ts +177 -0
  372. package/src/release/publish-cargo.js +351 -0
  373. package/src/release/publish-cargo.js.map +1 -0
  374. package/src/release/publish-crates.d.ts +124 -0
  375. package/src/release/publish-crates.js +242 -0
  376. package/src/release/publish-crates.js.map +1 -0
  377. package/src/release/publish-environments.d.ts +50 -0
  378. package/src/release/publish-environments.js +284 -0
  379. package/src/release/publish-environments.js.map +1 -0
  380. package/src/release/publish-messages.d.ts +66 -0
  381. package/src/release/publish-messages.js +273 -0
  382. package/src/release/publish-messages.js.map +1 -0
  383. package/src/release/publish-registry.d.ts +27 -0
  384. package/src/release/publish-registry.js +135 -0
  385. package/src/release/publish-registry.js.map +1 -0
  386. package/src/release/publish-settings.d.ts +26 -0
  387. package/src/release/publish-settings.js +56 -0
  388. package/src/release/publish-settings.js.map +1 -0
  389. package/src/release/publish.d.ts +59 -0
  390. package/src/release/publish.js +620 -0
  391. package/src/release/publish.js.map +1 -0
  392. package/src/release/repository.d.ts +73 -0
  393. package/src/release/repository.js +219 -0
  394. package/src/release/repository.js.map +1 -0
  395. package/src/release/requirements.d.ts +34 -0
  396. package/src/release/requirements.js +30 -0
  397. package/src/release/requirements.js.map +1 -0
  398. package/src/release/toml-edit.d.ts +67 -0
  399. package/src/release/toml-edit.js +453 -0
  400. package/src/release/toml-edit.js.map +1 -0
  401. package/src/release/version-actions.d.ts +133 -0
  402. package/src/release/version-actions.js +474 -0
  403. package/src/release/version-actions.js.map +1 -0
  404. package/src/release/version-checks.d.ts +21 -0
  405. package/src/release/version-checks.js +151 -0
  406. package/src/release/version-checks.js.map +1 -0
  407. package/src/release/version-lockfiles.d.ts +61 -0
  408. package/src/release/version-lockfiles.js +222 -0
  409. package/src/release/version-lockfiles.js.map +1 -0
  410. package/src/tools/napi-cli.d.ts +70 -0
  411. package/src/tools/napi-cli.js +63 -0
  412. package/src/tools/napi-cli.js.map +1 -0
  413. package/src/tools/optional-tools.d.ts +121 -0
  414. package/src/tools/optional-tools.js +303 -0
  415. package/src/tools/optional-tools.js.map +1 -0
  416. package/src/tools/print-napi-cli.d.ts +1 -0
  417. package/src/tools/print-napi-cli.js +24 -0
  418. package/src/tools/print-napi-cli.js.map +1 -0
@@ -0,0 +1,999 @@
1
+ # Caching
2
+
3
+ > **Status:** implemented as this page describes. A crate's key follows the
4
+ > feature strategy of its workspace: under `hakari` it holds the crate's own
5
+ > locked packages and the hack crate, under `workspace-build` and `cargo` what
6
+ > a build of the whole workspace reads, so that there a change to
7
+ > `Cargo.lock` that moves any member's packages runs every crate of the
8
+ > workspace again ([Lockfile changes](#lockfile-changes)).
9
+
10
+ Nx caches the **result** of a Rust task and, for a few targets, its **final
11
+ artifacts**. It never stores or restores Cargo's intermediate files: Cargo owns
12
+ its build directory, and Cargo's own incremental build does the rest.
13
+
14
+ The rule behind every choice on this page is cache correctness over cache
15
+ ambition. Running more than a cache key promises is fine. Running less is not.
16
+
17
+ ## What is in a cache key
18
+
19
+ | Input | Details |
20
+ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
21
+ | Crate files | Every file in the crate's folder, except the files a `napi-build` or `wasm-build` target generates there, and except `Cargo.lock` when the crate sits at the root of its workspace |
22
+ | Workspace files | The root `Cargo.toml`, and every `rust-toolchain.toml`, `.cargo/config.toml` and `.cargo/config` between the crate and the repository root |
23
+ | Dependency sources | The same files of every crate this one depends on, including dev- and build-dependencies, with the root `Cargo.toml` of its workspace. A path dependency that is not an Nx project counts with its whole folder, the files it declares and the variables and commands it adds, and a crate with a project behind it like a dependency of this one. |
24
+ | Declared files | Files outside the crate's folder that its `Cargo.toml` or its workspace's lists under `fileInputs`, and those that the crates it depends on list ([below](#files-outside-the-crate)) |
25
+ | External dependencies | The locked version, source and checksum of every package the crate reaches in its workspace's `Cargo.lock`, after the workspace's `lockfile` task has let cargo bring the file up to date; with the `cargo` or `workspace-build` feature strategy, of every package that any member of the workspace reaches |
26
+ | Member manifests | With the `cargo` or `workspace-build` feature strategy, the `Cargo.toml` of every member of the workspace; with `hakari`, the hack crate's `Cargo.toml` and `.config/hakari.toml` instead |
27
+ | Crates outside the workspace | With the `cargo` or `workspace-build` feature strategy, the folder of every path crate outside the workspace that any member uses, by path or through `[patch]`, `[replace]` or `paths`, with the files it declares and the variables and commands it adds |
28
+ | Plugin | The version of nx-rust and, where your JS lockfile lists nx-rust, the npm packages it depends on |
29
+ | Tool configuration | `clippy.toml` for `lint`, and where `CLIPPY_CONF_DIR` is set, in your environment or under `[env]` in Cargo's configuration, the `clippy.toml` or `.clippy.toml` that clippy finds from that folder upwards; `rustfmt.toml` for `fmt-check`, and `.config/nextest.toml` for tests that nextest runs |
30
+ | Environment | A fixed list of variables that change Rust builds, such as `RUSTFLAGS`, `RUSTDOCFLAGS`, `RUSTC_WRAPPER`, `CARGO_BUILD_TARGET`, `CC` and `CFLAGS`, and every `CARGO_PROFILE_*` and `CARGO_TARGET_*` variable but `CARGO_TARGET_DIR`. [[DES-INPUTS]] has the full list. You can add more. |
31
+ | Toolchain | The output of `rustc -Vv`, run in the root folder of the crate's workspace, and of `-Vv` of a compiler that `RUSTC`, `CARGO_BUILD_RUSTC` or `build.rustc` names; for `doc` and `test` also of a rustdoc that `RUSTDOC`, `CARGO_BUILD_RUSTDOC` or `build.rustdoc` names |
32
+ | Artifact folders | On `build` and `doc`, the triples that Cargo's configuration and `CARGO_BUILD_TARGET` pick when the task runs, also from a configuration file outside the repository, and the artifact directory that cargo reports then, also where only a task's `.env` file sets it |
33
+ | Test mode | On `test` in a workspace with `affectedTests`, the [[TERM-TEST-MODE]]: `full`, or `affected` with the commits of the coverage baseline |
34
+ | Options | Features, profile and target triple |
35
+
36
+ Never all environment variables: a key that changes with every shell is no
37
+ cache at all.
38
+
39
+ Entries of the `default` named input in your `nx.json` that are not patterns
40
+ under `{projectRoot}`, such as `sharedGlobals`, count for every crate as well.
41
+ A crate's own folder counts whole whatever your `default` says about it.
42
+
43
+ Nx also puts into every key what no input names: `nx.json`, and the
44
+ configuration of the crate's project and of the crates it depends on, such as
45
+ the options of each of their targets. A changed option of one target, also one
46
+ from a `project.json` or `targetDefaults`, runs every task of that crate and
47
+ of the crates that depend on it again, and any change to `nx.json` runs them
48
+ all again. That costs time, never a stale result.
49
+
50
+ A crate's warnings count too: when a warning that the plugin prints at the
51
+ start of the crate's tasks appears or goes away, those tasks and the tasks of
52
+ the crates that depend on it run again, so that a result restored from the
53
+ cache shows the warnings that apply now
54
+ ([Error messages and warnings](setup.mara.md#error-messages-and-warnings)). A
55
+ warning that names a path outside the repository, such as your Cargo home,
56
+ gives machines with different such paths different keys for the crates
57
+ concerned.
58
+
59
+ A crate that `[patch]`, `[replace]` or `paths` may put in place of a
60
+ dependency counts as a dependency of every crate that may use it, and so does
61
+ a crate with a project that such a crate without a project depends on by path
62
+ ([The dependency graph](workspaces.mara.md#the-dependency-graph)).
63
+
64
+ The whole crate folder is an input, so a README, a template or a migration
65
+ that a macro or build script reads is covered, at the price that a change to
66
+ any file in the crate runs its tasks again. You can leave files out with a
67
+ negated pattern in a target's `inputs`
68
+ ([Configuration](configuration.mara.md#changing-an-inferred-target)). That is
69
+ your statement that the target does not read them: if a macro such as
70
+ `include_str!`, a build script or a test still reads an excluded file, Nx
71
+ restores results produced with its old content.
72
+
73
+ If a build script or test reads something outside this list, add it: a file
74
+ ([below](#files-outside-the-crate)), an environment variable, or a command
75
+ whose output should be part of the key. Typical cases are a system library
76
+ version or a code generator.
77
+
78
+ ```toml
79
+ # rust/Cargo.toml
80
+ [workspace.metadata.nx]
81
+ envInputs = ["PROTOC", "DATABASE_URL"]
82
+ runtimeInputs = ["protoc --version"]
83
+ ```
84
+
85
+ `envInputs` and `runtimeInputs` work in the plugin options for every crate, in
86
+ `[workspace.metadata.nx]` for the members of a workspace and in
87
+ `[package.metadata.nx]` for one crate. The three add up. What they add joins
88
+ the crate's `default` named input, so it counts for every cached target of the
89
+ crate, and it also reaches the keys of the crates that depend on it, because
90
+ they compile it too. That holds for a path dependency without an Nx project
91
+ and for a crate whose edge the graph leaves out, as long as Cargo reports the
92
+ crate.
93
+
94
+ A variable or program that only the tests read, such as a test database's
95
+ address or a tool that a test starts from `PATH`, needs none of that reach.
96
+ Add it to the `inputs` of the crate's `test` target instead, after `"..."`,
97
+ and only that target's key holds it
98
+ ([Configuration](configuration.mara.md#changing-an-inferred-target)):
99
+
100
+ ```toml
101
+ # rust/crates/api/Cargo.toml
102
+ [package.metadata.nx.targets.test]
103
+ inputs = ["...", { env = "TEST_DATABASE_URL" }, { runtime = "tar --version" }]
104
+ ```
105
+
106
+ A new `TEST_DATABASE_URL`, or a `tar` of another version earlier on `PATH`,
107
+ then runs `api:test` again, while `api:build` and the crates that depend on
108
+ `api` are restored from the cache.
109
+
110
+ `nx affected` selects tasks by changed files only. A change that reaches a
111
+ task only through an environment variable or a command's output, such as a new
112
+ `RUSTFLAGS` or a toolchain update without a change to a `rust-toolchain.toml`,
113
+ changes the keys but selects no task. No stale result is restored, because a
114
+ task that runs misses the cache, but the tasks that the change reaches do not
115
+ run. After such a change, for example when your pipeline moves to a new
116
+ toolchain, run the targets for every project with `nx run-many` instead of
117
+ `nx affected`: the tasks whose keys stayed the same are restored from the
118
+ cache. A toolchain pinned to a version in `rust-toolchain.toml` changes only
119
+ with a commit, which `nx affected` sees.
120
+
121
+ ## Files outside the crate
122
+
123
+ A build script can name files outside its crate's folder with
124
+ `cargo::rerun-if-changed`, and a macro such as `include_str!` can pull them in,
125
+ for example protocol definitions that several crates share. The plugin does
126
+ not guess these paths: list them under `fileInputs`, as glob patterns relative
127
+ to the `Cargo.toml` that holds them.
128
+
129
+ ```toml
130
+ # rust/crates/api/Cargo.toml
131
+ [package.metadata.nx]
132
+ fileInputs = ["../../../proto/**/*.proto", "../../../README.md"]
133
+ ```
134
+
135
+ - The files count for every cached target of the crate and of every crate that
136
+ depends on it, from the first run on, and `nx affected` sees a change to
137
+ them.
138
+ - In `[workspace.metadata.nx]` the patterns apply to every member. A crate has
139
+ its workspace's patterns and its own.
140
+ - A pattern can name files of other crates and Nx projects, such as
141
+ `../*/src/**` for the sources of the crates beside this one. Nx counts what a
142
+ pattern names only for the project whose folder holds the place where the
143
+ pattern starts, so nx-rust adds a pattern for the folder of each project it
144
+ creates below that place. A project of another plugin there, such as one
145
+ that a `project.json` creates, stops graph creation with the pattern to add
146
+ for its folder. Each alternative of braces counts as a pattern of its own,
147
+ and a pattern that ends in `/`, or whose last part is a name such as
148
+ `../*/templates`, counts everything below the folders it names.
149
+ - Files that Git ignores can be listed too, and are hashed. `nx affected` does
150
+ not see a change to a file that the root `.gitignore` or `.nxignore` ignores,
151
+ though; `nx run-many` still runs the tasks again, because their keys change.
152
+ - A symbolic link in a pattern before its first wildcard counts as the file or
153
+ folder it points to. A wildcard does not follow links: `**` skips a linked
154
+ folder, and Nx keeps the first hash of a linked file that `*` matches, so
155
+ list the linked folder or file itself.
156
+ - A pattern that leaves the repository, also through a symbolic link, or
157
+ points into Cargo's build or artifact directory, stops graph creation, and
158
+ so does a `..` after a wildcard. Nx does not track files outside the
159
+ repository; cover those with a command under `runtimeInputs`. A pattern
160
+ whose folder holds Cargo's build or artifact directory, such as
161
+ `../../**`, leaves that directory out, so that a build changes no key.
162
+
163
+ Cargo's build and artifact directories, `target/` by default, are Cargo's,
164
+ and `fileInputs` refuses paths inside them: a key over Cargo's outputs would
165
+ change with every build, and the sources they are made from count already.
166
+ So keep test data such as fixtures, golden files or downloaded samples outside
167
+ them. In the crate's folder, every file that neither Git nor `.nxignore` ignores counts. A
168
+ file that Git ignores, such as a downloaded sample, and a file elsewhere in
169
+ the repository need a `fileInputs` pattern, which counts ignored files too.
170
+
171
+ Where a test reads files inside `target/`, for example ones that another step
172
+ puts beside the executable that `CARGO_BIN_EXE_<name>` names, no input covers
173
+ them. A `runtime` input on the crate's `test` target
174
+ ([above](#what-is-in-a-cache-key)) then has to print everything that decides
175
+ what the test reads. Where the files exist before Nx computes the key, a
176
+ command that prints their digest does that:
177
+
178
+ ```toml
179
+ # rust/crates/api/Cargo.toml
180
+ [package.metadata.nx.targets.test]
181
+ inputs = ["...", { runtime = "cksum rust/target/debug/golden.txt" }]
182
+ ```
183
+
184
+ The command runs in the repository root, and Nx keys what it prints on
185
+ standard output and standard error, whatever its exit status. A changed, empty
186
+ or missing file thus each gives another key, the missing one through cksum's
187
+ message, and the same content gives the same key again.
188
+
189
+ Where the step that writes the files runs after Nx has computed the key, key
190
+ every input of that step instead: its own input files, its options and the
191
+ version of the tool. The tool's version alone is enough only where nothing
192
+ else decides what it writes. A path relative to `CARGO_BIN_EXE_<name>` lies in
193
+ the artifact directory that `CARGO_TARGET_DIR` or `build.target-dir` sets, so
194
+ it moves with them, and the command has to name the same place; a path
195
+ relative to `env!("CARGO_MANIFEST_DIR")` does not move.
196
+
197
+ Whenever `build` runs cargo, also when nothing needs compiling, the plugin
198
+ reads the dependency files that Cargo writes beside the crate's library and
199
+ binaries, such as `target/debug/libapi.d` and `target/debug/api.d`. If one
200
+ names a file in the repository that none of the task's inputs covers, the task
201
+ fails, lists the files and shows the `fileInputs` line to add. Where Cargo's
202
+ configuration or `CARGO_BUILD_TARGET` picks the target triple, it reads them
203
+ in that triple's folder. A record that the plugin cannot attribute with
204
+ certainty, for example for a triple whose folder it cannot name, such as
205
+ `host-tuple`, is not read. With
206
+ `build.dep-info-basedir` set, Cargo records a path that runs through a symbolic
207
+ link and then `..` as the file that its text names, so the check can name a
208
+ file that was not read; the `fileInputs` line it shows still lets the build
209
+ pass. The other crates built in the same cargo call keep their results. A failed task is never cached as a success;
210
+ with `NX_CACHE_FAILURES=true`, Nx replays the failure until its key changes,
211
+ which adding the line does.
212
+
213
+ Other targets are not checked this way, because Cargo keeps their records only
214
+ inside its build directory. A file that only tests read is yours to list. So is
215
+ a file that a proc macro opens by itself: Cargo does not track it either, and
216
+ plain `cargo` will not rebuild when it changes.
217
+
218
+ ## Lockfile changes
219
+
220
+ A crate's key does not hold the whole `Cargo.lock`, only the packages the crate
221
+ reaches in it. Each workspace has a `lockfile` task that runs in every Nx run
222
+ that includes one of its crates' cached tasks. It runs
223
+ `cargo update --workspace`, which leaves an up-to-date lockfile alone and
224
+ updates an outdated one exactly as your next `cargo build` would. It then
225
+ writes one digest per crate into `.nx/workspace-data/nx-rust/lockfile`. Every
226
+ cached task of a crate except `fmt-check` waits for it and reads the crate's
227
+ digest. A digest covers the version, source and checksum of each package the
228
+ crate depends on, directly or through other crates, for every platform and
229
+ feature set, and which version of a package each of them uses.
230
+
231
+ ```text
232
+ rust/Cargo.lock: ryu 1.0.23 -> 1.0.24, which only "api" reaches
233
+
234
+ nx affected -t test
235
+ rust:lockfile runs and writes new digests
236
+ api:test runs: its digest changed
237
+ core:test restored from the cache: its digest is the same
238
+ ```
239
+
240
+ That holds under the `hakari` feature strategy. Under `workspace-build` and
241
+ `cargo`, which build every crate with the features of the whole workspace, a
242
+ package that only one member reaches can switch on a feature of a dependency
243
+ that the others share, so every crate's key holds the digests of all members
244
+ ([Batching and features](execution.mara.md#feature-unification)). There a
245
+ change to `Cargo.lock` that changes any member's digest runs every crate of
246
+ the workspace again; in the example, `core:test` runs as well. That costs
247
+ time, never a stale result.
248
+
249
+ After a change to `Cargo.lock` or to a manifest, `nx affected` selects the
250
+ cached tasks of every crate of that workspace, because Nx cannot tell which
251
+ ones the change reaches. The keys can: the crates whose keys stayed the same
252
+ are restored from the cache, so they cost a lookup, not a build.
253
+
254
+ - Add a dependency and run `nx build` as you would run `cargo build`: the
255
+ `lockfile` task lets cargo add it to `Cargo.lock` first, and the crates are
256
+ keyed on the result. A missing `Cargo.lock` is created the same way.
257
+ - In locked mode the `lockfile` task fails on an outdated or missing
258
+ `Cargo.lock` with cargo's message, and no task of that workspace's crates
259
+ runs.
260
+ - The `lockfile` task costs one cargo call per workspace in every run, also
261
+ when everything else is restored from the cache. On a machine whose Cargo
262
+ home is empty, that call fetches the registry index entries the build would
263
+ fetch anyway.
264
+ - Features are not part of the digest. `Cargo.lock` does not record them; the
265
+ features a crate asks for are in its `Cargo.toml` and its target options,
266
+ which are inputs anyway.
267
+ - A `Cargo.lock` that git ignores is read all the same.
268
+ - With `--exclude-task-dependencies` the `lockfile` task does not run. The
269
+ crates' cached tasks then run and store nothing that a later run restores.
270
+ - A cached crate task that runs without the `lockfile` task in a run that does
271
+ not exclude task dependencies, for example because a `project.json` replaces
272
+ its `dependsOn`, fails before cargo runs: its key would hold no digest. Keep
273
+ the dependency with `"..."`, as in `"dependsOn": ["...", "^codegen"]`.
274
+ - A cached task fails when `Cargo.lock` changes while it runs, for example
275
+ because you edited a manifest during the run, or because another `nx`
276
+ command that ran at the same time updated the lockfile, so that its key no
277
+ longer describes what cargo built. Under `workspace-build` and `cargo`, that
278
+ includes a change to packages that only another crate of the workspace
279
+ reaches, because the key holds every crate's digest. Nx stores no result for it, unless you set
280
+ `NX_CACHE_FAILURES=true` ([What is stored](#what-is-stored)); run it again.
281
+ - A workspace whose root `Cargo.toml` Nx hands to no entry of the plugin, for
282
+ example because an `exclude` of the plugin's entry in `nx.json` names it,
283
+ has no `lockfile` task. Its crates' `build`, `check`, `lint` and `test` then
284
+ run uncached, and graph creation warns.
285
+ - If the workspace folder also is a JS project with a script or target called
286
+ `lockfile`, that one replaces the plugin's task, as it would any target of
287
+ that name. Rename the plugin's task through `targetNames`
288
+ ([Configuration](configuration.mara.md)).
289
+
290
+ A change to your JS lockfile changes Rust keys only where it changes nx-rust or
291
+ a package that nx-rust depends on. Which Rust tasks `nx affected` then selects
292
+ depends on whether your JS lockfile lists nx-rust. If it does not, the Rust
293
+ targets name no npm package, and a JS lockfile change selects none of them. If
294
+ it does, the choice is `projectsAffectedByDependencyUpdates` in the `@nx/js`
295
+ section of `pluginsConfig` in `nx.json`. Nx's default, `all`, selects every
296
+ Rust task after any change to the JS lockfile, and those whose keys did not
297
+ change are restored from the cache. With `auto`, Nx selects them only when the
298
+ change reaches nx-rust or what it depends on.
299
+
300
+ A Cargo workspace or crate at the repository root is the exception, because it
301
+ shares its folder with your JS package. Nx counts the JS lockfile as
302
+ configuration of the project there, so any change to it selects that project's
303
+ tasks and the tasks of its crates. The folder is also an input, `package.json`
304
+ and the JS lockfile with it, and Nx links the project to the npm packages that
305
+ `package.json` lists. A change to either file therefore changes the keys of
306
+ `doc` on a workspace project there, of every cached target of a crate at the
307
+ root and of every crate that depends on that crate, directly or through other
308
+ crates: those tasks run, and so does the uncached `lockfile` task. The tasks of
309
+ the other crates are restored from the cache. A Cargo workspace in a
310
+ subfolder, such as `rust/`, avoids both.
311
+
312
+ ## Where cargo runs
313
+
314
+ The plugin starts every cargo command in the root folder of the crate's
315
+ workspace. rustup and Cargo choose `rust-toolchain.toml` and
316
+ `.cargo/config.toml` by the folder a command starts in, so the files that count
317
+ are those at the workspace root and above it.
318
+
319
+ - A toolchain or configuration file **inside a member crate** applies only to a
320
+ `cargo` you start in that crate's folder. It does not apply to Nx runs,
321
+ although a change to it still changes the cache key.
322
+ - Every command but `cargo fmt` selects the crate by its full package ID
323
+ specification, as `cargo pkgid` prints it, such as
324
+ `-p path+file:///home/me/repo/rust/crates/api#0.1.0`, so that a dependency
325
+ with the crate's name, such as an older version of the crate itself, makes
326
+ no command ambiguous. Each task asks cargo for it before its command. The
327
+ path in it reaches no cache key.
328
+ - The toolchain in the key is whatever `rustc -Vv` reports in the workspace
329
+ root. `RUSTUP_TOOLCHAIN`, `rustup override` and a toolchain installed without
330
+ rustup are all respected. Nx runs `rustc -Vv` with each task's environment, so
331
+ a `RUSTUP_TOOLCHAIN` in a crate's `.env` gives that crate's tasks another
332
+ toolchain, in their keys and when they run. Plain `cargo` does not read
333
+ `.env` files. If that toolchain is not installed, computing the
334
+ key does not install it: the task gets a key that matches no stored result
335
+ and runs, and its cargo installs the toolchain as plain `cargo` would.
336
+ - Where `RUSTC`, `CARGO_BUILD_RUSTC` or `build.rustc` names the compiler that
337
+ cargo runs, the key also holds that compiler's `-Vv`, and for `doc` and
338
+ `test` that of a rustdoc that `RUSTDOC`, `CARGO_BUILD_RUSTDOC` or
339
+ `build.rustdoc` names. The key follows the program at that path, also when
340
+ it is replaced while the path stays the same, as `rustup update` does for a
341
+ channel's path. A compiler that does not exist, or an empty `RUSTC`, gives
342
+ a key that matches no stored result, and cargo fails as it would without
343
+ Nx.
344
+ - The plugin reads `build.rustc` and `build.rustdoc` when Nx creates the
345
+ graph. The Nx daemon does not watch configuration files outside the repository, such
346
+ as `~/.cargo/config.toml`: after you change the compiler there, run
347
+ `nx reset` or stop the daemon with `nx daemon --stop`. Set `CARGO_HOME` in
348
+ the shell or the repository's root `.env`, not in a `.env` that Nx loads
349
+ only for a task.
350
+ - A wrapper that `RUSTC_WRAPPER`, `RUSTC_WORKSPACE_WRAPPER` or
351
+ `build.rustc-wrapper` names counts by its name only. If it runs another
352
+ compiler than the one cargo hands it, add a command that prints that
353
+ compiler's version to `runtimeInputs`.
354
+ - Cargo may create or update `Cargo.lock` during a task, as it does for plain
355
+ `cargo`. With the `locked` option, or `NX_RUST_LOCKED=true` for one run,
356
+ every cargo command of a task passes `--locked` and fails instead. Three
357
+ targets never pass it: `update`, which exists to change the lockfile, and
358
+ `fmt` and `fmt-check`, because `cargo fmt` reads no lockfile and rejects the
359
+ flag. `audit` runs cargo-audit, which only reads `Cargo.lock` and has no such
360
+ flag. Building the project graph never touches `Cargo.lock`.
361
+ - In locked mode, every run in which the `lockfile` task runs fails on an
362
+ outdated `Cargo.lock`, also when every crate task is then restored from the
363
+ cache. A run of `fmt` or `fmt-check` alone, one with
364
+ `--exclude-task-dependencies` and one without Rust tasks do not check it; for
365
+ that, see
366
+ [Continuous integration](ci.mara.md#cache-two-things-in-two-places).
367
+
368
+ ### Seeing the command
369
+
370
+ Run Nx with `--verbose`, or with `NX_VERBOSE_LOGGING=true` in the shell or the
371
+ repository's root `.env`, to see the cargo command of each task. Right before cargo starts, the task prints where cargo
372
+ runs and the command, as lines that you can paste into a shell:
373
+
374
+ ```text
375
+ good:test: @convesoft/nx-rust runs cargo as these lines do in a POSIX shell:
376
+ cd /home/me/repo/rust
377
+ cargo test -p 'path+file:///home/me/repo/rust/crates/good#0.1.0'
378
+ ```
379
+
380
+ ```sh
381
+ nx test good --verbose
382
+ nx affected -t test --verbose --skip-nx-cache # tasks with a cached result too
383
+ ```
384
+
385
+ - Without the flag, nothing of this is printed. Cargo's own hints, such as
386
+ ``to rerun pass `-p good --lib` ``, use the package name, which is ambiguous
387
+ where a dependency has the crate's name; the printed line is not.
388
+ - cargo runs with the environment that Nx gives the task: the shell's, with
389
+ the `.env` files that Nx loads for the task, such as one in the crate's
390
+ folder. The lines name only the variables that the plugin sets itself, none
391
+ at present, so set a variable that only such a file gives by hand.
392
+ - A task that Nx restores from the cache runs no cargo and prints what it
393
+ printed when its result was stored. A verbose run stores the lines with the
394
+ result, so a later hit, also without the flag and on another machine that
395
+ shares the cache, shows them with that run's folder, as cargo's own
396
+ `Compiling` lines show it. `--skip-nx-cache` runs the task, shows its
397
+ command and stores nothing.
398
+ - `--verbose` changes no cache key.
399
+ - The `lockfile` task prints its own `cargo update --workspace`. The lookups
400
+ that a task makes first, such as the `cargo metadata` call that gives the
401
+ package ID specification, are not printed.
402
+
403
+ ### Cargo configuration that Nx does not hash
404
+
405
+ Nx hashes no file outside the repository and no file that `.gitignore` or
406
+ `.nxignore` hides. A `.cargo/config.toml` in a folder above the repository or
407
+ in your Cargo home, and an ignored one inside the repository, is therefore in
408
+ no cache key. If such a file sets something that can change a build or a check
409
+ (`[build]`, `[target]`, `[host]`, `[profile]`, `[env]`, `[patch]`,
410
+ `[source]`, `paths`, `[unstable]` or `[doc]`), every task of the workspaces it
411
+ applies to starts with a warning that names the file. A file with only other
412
+ settings, such as `[alias]`, `[net]` or `[registries]`, draws none.
413
+
414
+ - A result that Nx cached before you change such a file can be restored
415
+ afterwards, because the key stays the same. After changing the file, run
416
+ `nx reset`, which empties the local cache.
417
+ - `--skip-nx-cache` makes one command run its tasks, but Nx stores none of
418
+ their results, so a later run without it can still restore a result from
419
+ before the change.
420
+ - Stop ignoring a file inside the repository, and Nx hashes it like the other
421
+ configuration files.
422
+ - Where the file redirects dependencies through `[patch]` or `paths`, the Nx
423
+ daemon also keeps the graph's edges, and whether a workspace can use the
424
+ `hakari` feature strategy, until it creates the graph again; `nx reset`
425
+ restarts it. Redirections in the root `Cargo.toml` or in a
426
+ `.cargo/config.toml` that Nx reads are followed at once.
427
+ - The warning itself stays out of the keys, so that your machine's Cargo
428
+ configuration does not give you keys of your own. A task restored from the
429
+ cache shows the warning as the run that stored the result printed it.
430
+
431
+ ### Rustfmt configuration outside the repository
432
+
433
+ rustfmt looks for `rustfmt.toml` or `.rustfmt.toml` from the folder of each
434
+ file it formats up to the file system's root. Where no folder between a
435
+ crate's source files and the repository root holds one, it takes one from a
436
+ folder above the repository, from your home folder (`~/.rustfmt.toml` or
437
+ `~/rustfmt.toml`) or from `$XDG_CONFIG_HOME/rustfmt/` (by default
438
+ `~/.config/rustfmt/`). Nx hashes none of these where they lie outside the repository, so the `fmt-check` and `fmt`
439
+ tasks of such crates start with a warning that names the file.
440
+
441
+ - A `fmt-check` result that Nx cached before you change the file can be
442
+ restored afterwards. Run `nx reset` after changing it; `--skip-nx-cache`
443
+ makes one command run its tasks without storing their results.
444
+ - A `rustfmt.toml` at the repository root, even an empty one, makes rustfmt
445
+ ignore the per-user files, formats the code alike on every machine and is
446
+ hashed like the other configuration files.
447
+ - The warning stays out of the keys, as the one about Cargo configuration
448
+ does. A task restored from the cache shows the warning as the run that
449
+ stored the result printed it, and with the Nx daemon, a file added or
450
+ removed outside the repository changes the warning only once Nx creates the
451
+ graph again, as after `nx reset`.
452
+
453
+ ## What is stored
454
+
455
+ | Target | Cached | Stored |
456
+ | ---------------------------------------------------------------------- | ------ | ----------------------------------------------------------------- |
457
+ | `check`, `lint`, `fmt-check`, `test` | Yes | Nothing but the result and the terminal output |
458
+ | `build` | Yes | Final artifacts only: executables, `cdylib` and `staticlib` files |
459
+ | `doc`, on the workspace project | Yes | The workspace's whole doc folder |
460
+ | `lockfile`, on the workspace project | No | Nothing; its digests stay in `.nx/workspace-data` |
461
+ | `hakari-check`, on the workspace project | No | Nothing |
462
+ | `fmt`, `bench`, `run`, `audit`, `deny`, `update`, `nx-release-publish` | No | Nothing |
463
+
464
+ A cache hit on `test` means "these tests passed for exactly these inputs", and
465
+ nothing is copied. A cache hit on `build` restores the binary. It does not
466
+ restore `rlib` files or anything else Cargo would need to continue compiling;
467
+ the next real compile uses whatever is in the build directory.
468
+
469
+ `cargo test` writes binaries too: for a crate with a binary and an integration
470
+ test, it builds the binary with the dev-dependencies' features and puts it
471
+ where `cargo build` put its own. In such crates `test` waits for `build`, so
472
+ that Nx always stores the binary of `cargo build`
473
+ ([Targets](targets.mara.md#tests-that-build-a-crates-binaries)). With
474
+ batching on, as by default, the `test` batch puts back the binaries that the
475
+ command's cached builds stored when it ends, so that after
476
+ `nx run-many -t build test` the artifact directory holds the binary of
477
+ `cargo build`, and a task that depends on `build` and runs after the tests
478
+ reads it. While the tests run, the binary there is that of `cargo test`.
479
+ With `--batch=false`, the artifact directory keeps the binary of
480
+ `cargo test`, as plain `cargo build && cargo test` leaves it, until the next
481
+ `build`, run or restored, puts its own back.
482
+
483
+ Cargo names a binary's file after the binary and a library's file after the
484
+ library, not after the crate. Where two crates that share an artifact
485
+ directory, in one workspace or in workspaces with the same `build.target-dir`,
486
+ have binaries, or `cdylib` or `staticlib` libraries, of one name, cargo keeps
487
+ a single file, that of the crate it built last, and warns of an
488
+ `output filename collision` when one command builds both. The same goes for
489
+ workspaces whose artifact directory lies inside another's, such as
490
+ `target/x86_64-unknown-linux-gnu` beside `target`, since a build for that
491
+ triple in the one writes the other's folder, and for workspaces that separate
492
+ entries of the plugin in `nx.json` receive. So that no cache
493
+ entry holds the other crate's file, the plugin runs the `build` of those
494
+ crates uncached, and their `test` too where integration tests run the binary,
495
+ and says so when Nx creates the graph and at the start of those crates'
496
+ tasks. Names that differ only in case count as one, because macOS takes them
497
+ for one file. Their other targets stay cached. A crate that another
498
+ installation of the plugin creates, registered in `nx.json` under another
499
+ name, is not seen when Nx creates the graph; a cached build or test that
500
+ would share such a file then fails when it starts, naming the other project.
501
+ `cargo doc` refuses a workspace whose binaries share a name, and so does its
502
+ `doc` target, until one binary is renamed or gets `doc = false`. Rename one
503
+ of the binaries, or
504
+ libraries with `[lib] name`, to cache them again, or, for crates of different
505
+ workspaces, give each workspace an artifact directory of its own, none inside
506
+ another:
507
+
508
+ ```toml
509
+ # rust/crates/beta/Cargo.toml
510
+ [[bin]]
511
+ name = "beta-cli"
512
+ path = "src/bin/cli.rs"
513
+ ```
514
+
515
+ By default Nx stores nothing for a task that fails, so the next run runs it
516
+ again. With `NX_CACHE_FAILURES=true`, your choice of an Nx setting, Nx stores
517
+ the failure and replays it, as a failure, for as long as the task's key stays
518
+ the same. A failure whose cause lies outside the key, such as a `Cargo.lock`
519
+ that changed during the run, a missing tool or the network, is then replayed
520
+ until an input of the task changes or you clear the cache with `nx reset`. No
521
+ setting makes Nx store or restore a failed task as a success.
522
+
523
+ Nx can store only files inside the repository. If Cargo's artifact directory
524
+ lies outside it, for example through `CARGO_TARGET_DIR` or a symbolic link,
525
+ `build` and `doc` run uncached, and the plugin says so. The plugin follows
526
+ symbolic links to the folder that cargo writes to, and names that folder. `doc` also runs uncached, with the same
527
+ notice, when two workspaces share one artifact directory, or one lies inside
528
+ the other's: restoring one workspace's doc folder would delete or replace the
529
+ other's files.
530
+
531
+ Where one workspace's artifact directory lies inside another's, such as
532
+ `target/x86_64-unknown-linux-gnu` inside `target`, a first build, while these
533
+ directories do not exist yet, can also fail in cargo with
534
+ `No such file or directory`. Cargo commands of the two workspaces that start
535
+ together, as Nx runs them, can get in each other's way while they create the
536
+ directories, and plain cargo does the same; the plugin's warning about such
537
+ directories says so. Run the command again: the second run finds the
538
+ directories and builds. Where every build can be a first one, as in CI, run
539
+ the command again on that error, or build such workspaces with `--parallel=1`
540
+ on a first run, or give each workspace an artifact directory of its own, none
541
+ inside another. Two workspaces with the same artifact directory do not meet
542
+ this.
543
+
544
+ The plugin has to know the folder that cargo writes to:
545
+
546
+ - Where `build.target` in Cargo's configuration or `CARGO_BUILD_TARGET`
547
+ picks the target triple, `build` and `doc` store the files in that
548
+ triple's folder, such as `target/x86_64-unknown-linux-musl/release`, and a
549
+ list of triples in each triple's folder. The `targetTriple` option wins
550
+ over both, as `--target` does for cargo.
551
+ - The plugin reads `CARGO_BUILD_TARGET`, and the artifact directory that
552
+ `CARGO_TARGET_DIR`, `CARGO_BUILD_TARGET_DIR` or a `CARGO_HOME` with its
553
+ own `config.toml` sets, when Nx creates the graph. Set them in the shell
554
+ or in the repository's root `.env`, not in a `.env` file that Nx loads
555
+ only for a task, such as one in the crate's or the workspace's folder or
556
+ a root `.env.build`: there a cached `build` or `doc` fails before cargo
557
+ runs, with a message that names both folders. Pass
558
+ `--targetTriple=<triple>` instead, or set `build.target-dir` in
559
+ `.cargo/config.toml`.
560
+ - The Nx daemon does not watch Cargo configuration files outside the
561
+ repository, such as `~/.cargo/config.toml`. After you change the triple
562
+ or `build.target-dir` there, a cached `build` or `doc` neither restores
563
+ the result of the old setting nor runs: it fails before cargo runs until
564
+ you run `nx reset`, or stop the daemon with `nx daemon --stop`.
565
+ - Where the configuration picks `host-tuple`, a target specification file,
566
+ or a triple only in a file that `include` adds, `build` and `doc` run
567
+ uncached, and the plugin says so. Give the triple as the `targetTriple`
568
+ option of those targets to cache them.
569
+ - A cached `build` or `doc` refuses the `targetTriple` values `host-tuple`
570
+ and a target specification file, whose folders cargo names otherwise.
571
+ Pass the host's triple itself, which the message names, in place of
572
+ `host-tuple`. For a specification file, set `cache = false` on the target.
573
+ - `build` and `doc` refuse the profiles `dev`, `test` and `bench`, whose
574
+ artifacts Cargo puts in the folders `debug` and `release`. Leave `profile`
575
+ unset for `dev` and `test`, and use `release` for `bench`.
576
+ - A `targetDefaults` entry in `nx.json` that sets `cache: true` on a target
577
+ that the plugin leaves uncached fails graph creation
578
+ ([Target defaults that reach Rust targets](targets.mara.md#target-defaults-that-reach-rust-targets)).
579
+ A `project.json` or `package.json`, or another plugin, that does so makes
580
+ the task fail before cargo runs, with the reason. Another plugin that takes
581
+ away or narrows inputs or outputs fails graph creation
582
+ ([Other plugins that reach Rust targets](targets.mara.md#other-plugins-that-reach-rust-targets)).
583
+
584
+ ## Cargo's two directories
585
+
586
+ Since Cargo 1.91, intermediate files and final artifacts can live in separate
587
+ directories:
588
+
589
+ ```toml
590
+ # .cargo/config.toml
591
+ [build]
592
+ build-dir = "{cargo-cache-home}/build/{workspace-path-hash}" # intermediate files
593
+ target-dir = "target" # final artifacts
594
+ ```
595
+
596
+ - Of Cargo's two directories, Nx outputs point only into the **artifact
597
+ directory**.
598
+ - The **build directory** should sit outside the repository. Nx never caches
599
+ it; in CI, cache it with your CI system's cache
600
+ ([Continuous integration](ci.mara.md)).
601
+ - The layout of the build directory is Cargo's business and has changed between
602
+ Cargo versions, so the plugin never names a path inside it.
603
+ - Splitting the directories does not remove lock contention: there is still one
604
+ lock per build directory. Batching deals with that
605
+ ([Batching and features](execution.mara.md)).
606
+
607
+ These settings live in `.cargo/config.toml`, so plain `cargo` and rust-analyzer
608
+ use the same directories as the plugin, and a build through one is reused by
609
+ the other.
610
+
611
+ ## Sharing the cache between machines
612
+
613
+ The toolchain input includes the host triple, and the target triple is an
614
+ option, so a result from Linux is never restored on macOS. Two machines with
615
+ the same triple can still differ in system libraries or linkers. If your crates
616
+ link against system libraries and you share the cache between unlike machines,
617
+ add an input that tells them apart ([[RISK-HOST-ENVIRONMENT]]).
618
+
619
+ ## Sharing the cache between checkouts
620
+
621
+ Nx 24 keeps its local cache, and the database of the task results in it, in
622
+ your home folder, under `~/.nx`, one per workspace rather than one per
623
+ checkout. It tells workspaces apart by the Nx Cloud id or access token in `nx.json`, or else by the git remote, or the first commit where there is none, together with the workspace's folder inside the repository. A checkout for which Nx finds none of these, such as a shallow clone without a remote or a folder that is no git repository, or whose folder under `~/.nx` Nx cannot use, keeps a cache of its own. Linked git worktrees of a
624
+ repository therefore share the cache, and so do separate clones that Nx takes
625
+ for the same workspace. Sharing is off for a checkout where `nx.json` sets
626
+ `cacheDirectory`, or the environment sets `NX_CACHE_DIRECTORY`,
627
+ `NX_WORKSPACE_DATA_DIRECTORY` or `NX_PROJECT_GRAPH_CACHE_DIRECTORY`. The
628
+ plugin puts the folder of the checkout into no key, so a result stored in one
629
+ checkout is restored in the others that share the cache, and `nx reset`
630
+ empties the cache that they share.
631
+
632
+ What a hit restores follows [What is stored](#what-is-stored):
633
+
634
+ - `check`, `lint`, `fmt-check` and `test` restore a result and the terminal
635
+ output, which can name the other checkout's folders, as cargo's
636
+ `Compiling` lines do.
637
+ - `build` restores the final artifacts only: executables, `cdylib` and
638
+ `staticlib` files. Never the `.d` files beside them, nor anything of Cargo's
639
+ build directory. Cargo in this checkout still compiles whatever it needs
640
+ when it next runs.
641
+ - A restored executable or library is the one that the other checkout built,
642
+ so the absolute paths compiled into it name that checkout: a value of
643
+ `env!("CARGO_MANIFEST_DIR")`, the folders in its debug information, and
644
+ `file!()` in a crate that cargo compiles by absolute path, such as a path
645
+ dependency outside the workspace. `--remap-path-prefix` in `RUSTFLAGS`
646
+ rewrites the source paths, but not what `env!` returns, and `RUSTFLAGS` is
647
+ part of the key, so a value that names the checkout gives each checkout
648
+ keys of its own.
649
+
650
+ Where artifacts have to come from the checkout they run in, give `build` a key
651
+ that names the checkout. A `runtime` input that prints the folder Nx runs it
652
+ in does that, for every member of a workspace at once:
653
+
654
+ ```toml
655
+ # rust/Cargo.toml
656
+ [workspace.metadata.nx.targets.build]
657
+ inputs = ["...", { runtime = "pwd" }]
658
+ ```
659
+
660
+ Each checkout then builds its own artifacts once and restores only those, also where a remote cache such as Nx Cloud is set up, because Nx looks the same key up there. Two checkouts at the same path, as on two machines or two CI runners, still get the same key. It costs the reuse of `build` results between checkouts, and between
661
+ CI and your machine, wherever their folders differ; the other targets are still
662
+ shared. Running such tasks with `--skip-nx-cache` also works, but it runs them
663
+ every time and stores nothing.
664
+
665
+ A cache directory of its own separates only the local cache. After a local
666
+ miss Nx still asks a remote cache for the same key, so a checkout with its own
667
+ directory can restore another checkout's or CI's artifacts from there. In
668
+ `nx.json`, a relative `cacheDirectory` is read against each checkout's folder:
669
+
670
+ ```json
671
+ {
672
+ "cacheDirectory": ".nx/cache"
673
+ }
674
+ ```
675
+
676
+ Nx hashes `nx.json` into every key, so each task runs once more after the
677
+ change. For one shell or one command, `NX_CACHE_DIRECTORY` does the same and
678
+ wins over `cacheDirectory`. The Nx daemon keeps the directories that it chose
679
+ when it started, also when later commands set the variable. Stop a running
680
+ daemon first with `nx daemon --stop` and then set the variable for every
681
+ command in that checkout, or set `NX_DAEMON=false` with it:
682
+
683
+ ```sh
684
+ NX_CACHE_DIRECTORY=.nx/cache NX_DAEMON=false nx run-many -t build test
685
+ ```
686
+
687
+ ## Requirements
688
+
689
+ :::mara requirement REQ-INPUT-FILES
690
+ :mid: 01M78FHG7F5EMJYNVQRAZX9C63
691
+ :title: Hash every file that can change a crate's result
692
+ :status: accepted
693
+ :satisfies: NEED-CORRECT-CACHE
694
+
695
+ The cache key of a crate's cached target covers every file in the crate's folder, except the `Cargo.lock` of its workspace when the crate sits at the workspace root, whose packages reach the key as [[REQ-EXTERNAL-DEPS]] says, and it covers the workspace files that apply to it, every `rust-toolchain.toml`, `.cargo/config.toml` and `.cargo/config` at any level between the crate and the repository root, the configuration files of the tool the target runs, and the files of every crate it depends on through normal, build or dev-dependencies, with the root manifest of each such crate's workspace, from which that crate inherits fields. A path dependency that has no Nx project contributes its whole folder to the key of every crate that depends on it. 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 ([[DES-PROJECT-GRAPH]]); where it has no Nx project, or where its edge is left out because it would close a cycle, its folder is an input of that member's targets. Inputs name real paths per project, because a repository can hold several lockfiles and toolchain files. A negated pattern in the repository's own configuration of a target removes the files it matches from that target's key, on the repository's responsibility.
696
+ :::
697
+
698
+ :::mara requirement REQ-ENV-ALLOWLIST
699
+ :mid: 01M78FHG7FB30V9FZNFF0TFHC1
700
+ :title: Hash a fixed, extendable list of environment variables
701
+ :status: accepted
702
+ :satisfies: NEED-CORRECT-CACHE
703
+
704
+ The cache key of a cached target includes the values of a fixed list of environment variables that are known to change Rust builds, and of every variable whose name starts with `CARGO_PROFILE_` or `CARGO_TARGET_`, which set a profile's or a target triple's settings, apart from `CARGO_TARGET_DIR`. A repository can add variables and commands whose output joins the key. The plugin never hashes the whole environment.
705
+ :::
706
+
707
+ :::mara requirement REQ-TOOLCHAIN-KEY
708
+ :mid: 01M78FHG7FRC3KSSDACETE745J
709
+ :title: Key each task on the toolchain it uses
710
+ :status: accepted
711
+ :satisfies: NEED-CORRECT-CACHE
712
+
713
+ The cache key of a cached target includes the identity of the Rust toolchain that the plugin's cargo commands use for that task, which is the one that applies in the root folder of its workspace with the task's environment. It covers the compiler that cargo runs for the task, whether rustup, `PATH`, an environment variable or Cargo's configuration chooses it, and for `doc` and `test`, which run rustdoc, also the rustdoc that cargo runs. Two tasks that use different toolchains never share a toolchain identity in their keys, and a toolchain update changes the keys of exactly the tasks that use it.
714
+ :::
715
+
716
+ :::mara requirement REQ-CACHE-OUTPUTS
717
+ :mid: 01M78FHG7FR6HKPFNAN6P607RX
718
+ :title: Cache results and final artifacts only
719
+ :status: accepted
720
+ :satisfies: NEED-CORRECT-CACHE
721
+ :satisfies: NEED-CARGO-UNCHANGED
722
+
723
+ The Nx cache holds task results and final artifacts. It never stores a file from Cargo's build directory, and restoring from the cache never writes into that directory.
724
+ :::
725
+
726
+ :::mara requirement REQ-CARGO-UNCHANGED
727
+ :mid: 01M78FHG7F5VCD6HDS9R6HDS3Z
728
+ :title: Leave plain cargo behaviour unchanged
729
+ :status: accepted
730
+ :satisfies: NEED-CARGO-UNCHANGED
731
+
732
+ A cargo command that the plugin runs uses the same build directory, the same artifact directory and the same default flags as the equivalent plain `cargo` command in that workspace, so that builds through Nx and builds through plain cargo or rust-analyzer reuse each other's work. The maintainer decided one exception on 20 November 2026, choosing "Stage artifacts (Recommended)" ([[ADR-STAGED-BUILDS]]). A `build` that selects the whole workspace and the compile of `napi-build` and `wasm-build` link their final artifacts into a stage of their own, with the same build directory, and a `build` moves only its own crates' final artifacts into the artifact directory. They reuse, and leave for plain cargo, the same compiled work, but they no longer refresh the final artifacts of crates whose `build` the command does not run. The plugin generates no files inside crates apart from the outputs of an artifact target that the user runs: the addon's `.node` file, `index.js` and `index.d.ts` that `napi-build` writes into the crate's folder ([[DES-NAPI]]) and the `pkg` folder that `wasm-build` writes there ([[DES-WASM]]). Nx's own data folder, `.nx/workspace-data`, which Nx and git ignore, belongs to no crate and to neither of Cargo's directories, also where it lies in the folder of a crate at the repository root.
733
+ :::
734
+
735
+ :::mara requirement REQ-VERBOSE-COMMAND
736
+ :mid: 01M7DPAR45N7ZNQ7JRNAWTWPTQ
737
+ :title: Show the cargo command of a task when Nx runs verbosely
738
+ :status: accepted
739
+ :satisfies: NEED-CARGO-UNCHANGED
740
+ :satisfies: NEED-CLEAR-FAILURES
741
+
742
+ When Nx runs verbosely, through its `--verbose` flag or `NX_VERBOSE_LOGGING=true`, each task of the plugin prints, before each cargo command that does its work, the folder where the command starts and the command, with its arguments as passed and the environment variables that the plugin sets for it, as lines that a POSIX shell runs as the same command. For a staged command, the arguments include the stage and the build directory ([[ADR-STAGED-BUILDS]]); the moving of files out of the stage afterwards is not printed. A run that is not verbose prints nothing of it, and verbose mode changes no task's cache key.
743
+ :::
744
+
745
+ :::mara requirement REQ-BUILD-SCRIPT-INPUTS
746
+ :mid: 01M78FHG7FC47G6VCHVQBY6JT2
747
+ :title: Hash the declared files outside a crate that build scripts and macros read
748
+ :status: accepted
749
+ :satisfies: NEED-CORRECT-CACHE
750
+ :satisfies: NEED-AFFECTED
751
+ :mitigates: RISK-UNDECLARED-INPUTS
752
+
753
+ A repository can declare files outside a crate's folder that the crate's build script, macros or tests read, such as files that a build script names with `cargo::rerun-if-changed` or that `include_str!` pulls in, also files in the folders of other crates and Nx projects. It declares them in the crate's manifest and, for every member of a workspace, in the workspace's root manifest; the declarations of the two add up. Declared files are part of the cache key of every cached target of the crate and of every crate that depends on it, also when Git ignores them. A change to a declared file makes those tasks affected, except for a file that the repository's root `.gitignore` or `.nxignore` ignores: Nx leaves such files out of the changed files it matches against inputs, so a change to one alone changes the keys and makes no task affected. A symbolic link that a declaration names counts as the file or folder it points to. A link that only a wildcard of a declaration reaches covers the file it points to in neither way: Nx keeps the hash of the link's destination until the link itself changes or `nx reset` clears the hashes Nx keeps, and does not descend into a linked folder, so a change there alone changes no key and makes no task affected; the linked file or folder itself is what has to be declared ([[EVD-NX-24-FILE-INPUTS]]). Declarations come from the manifests, not from earlier builds, so they apply from the first run ([[ADR-DECLARED-FILE-INPUTS]]). Files inside the crate's folder are inputs already ([[REQ-INPUT-FILES]]).
754
+ :::
755
+
756
+ :::mara requirement REQ-FILE-INPUTS-HASHABLE
757
+ :mid: 01M7AE8CZ89406C7ZQ4FS2ST0V
758
+ :title: Reject a declared file pattern that Nx cannot hash
759
+ :status: accepted
760
+ :satisfies: NEED-CORRECT-CACHE
761
+ :satisfies: NEED-CLEAR-FAILURES
762
+ :mitigates: RISK-UNDECLARED-INPUTS
763
+
764
+ A declaration of files outside a crate ([[REQ-BUILD-SCRIPT-INPUTS]]) that resolves outside the repository, or into Cargo's build or artifact directory, fails graph creation with a message that names the manifest and the declaration. For a declaration outside the repository, the message points to the commands whose output a repository can add to the key instead ([[REQ-ENV-ALLOWLIST]]). A declaration that names files in the folder of a project below the folder where it starts, which Nx would leave out of the key because another project's folder holds where it starts, keys them all the same; where the plugin cannot make Nx count them, graph creation fails with a message that names the manifest, the declaration, the crates whose keys it is for and the project, and gives the declaration to add beside it that covers them.
765
+ :::
766
+
767
+ :::mara requirement REQ-BUILD-INPUT-CHECK
768
+ :mid: 01M7ACMK1QH5F72B0567M3WNP1
769
+ :title: Fail a build that read a repository file outside its inputs
770
+ :status: accepted
771
+ :satisfies: NEED-CORRECT-CACHE
772
+ :satisfies: NEED-CLEAR-FAILURES
773
+ :mitigates: RISK-UNDECLARED-INPUTS
774
+
775
+ When the cargo call of a `build` task has built the task's crate without error, also when nothing needed compiling, and a record that Cargo exported for the crate's library or one of its binaries names a file inside the repository that none of the task's file inputs covers, the task fails, so that no success is cached for it. The plugin names these records from what it knows without asking cargo, and reads none that it cannot name with certainty. A file reached through a symbolic link counts as covered only when the inputs cover the file the link points to. The failure names each such file and the declaration that would cover it ([[REQ-BUILD-SCRIPT-INPUTS]]). Files outside the repository, files in Cargo's build or artifact directory, and files that Nx ignores inside a directory that Cargo records as one path are not reported. When one cargo call builds several crates, only the tasks of the crates that read such a file fail.
776
+ :::
777
+
778
+ ## Design
779
+
780
+ :::mara design DES-INPUTS
781
+ :mid: 01M78FHG7FX4MX7J2W6TW28PDP
782
+ :title: Cache inputs
783
+ :status: accepted
784
+ :satisfies: REQ-INPUT-FILES
785
+ :satisfies: REQ-ENV-ALLOWLIST
786
+ :satisfies: REQ-TOOLCHAIN-KEY
787
+ :satisfies: REQ-BUILD-SCRIPT-INPUTS
788
+ :satisfies: REQ-FILE-INPUTS-HASHABLE
789
+
790
+ Every cached target declares its inputs as Nx inputs. The plugin has no custom hasher ([[ADR-DECLARED-INPUTS]]).
791
+
792
+ | Input | Declared as |
793
+ | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
794
+ | Crate files | One fileset for the crate's project: every file under the crate's folder that belongs to no nested project, without the files an artifact target generates there ([[DES-ARTIFACT-STEPS]]). A list of source folders would miss files that macros and build scripts read, such as a README, templates or migrations ([[ADR-DECLARED-INPUTS]]). A negated pattern in the repository's own `inputs` of a target removes files from it, on the repository's responsibility ([[DES-PLUGIN-OPTIONS]]). For the crate at the root of its workspace, which every [[TERM-STANDALONE-CRATE]] is, the fileset also leaves out the workspace's `Cargo.lock`, which reaches the key only through the crate's digest ([[DES-LOCKFILE-HASHING]]). |
795
+ | Workspace files | The real paths of every `rust-toolchain.toml`, `rust-toolchain`, `.cargo/config.toml` and `.cargo/config` between the crate and the repository root, and of every file inside the repository that such a configuration adds with `include`, which cargo takes from the folder it starts in and not from a dependency's ([[EVD-CARGO-DEPENDENCY-SIDE]]); Cargo reads `.cargo/config` where both exist. The root `Cargo.toml` of the crate's workspace is in the crate's named input, because the crate inherits fields from it also where another workspace builds it. A repository-wide named input cannot point at several lockfiles, so these are per project. |
796
+ | Dependency sources | The crate-file inputs of all dependencies, through `^` inputs over the edges in [[DES-PROJECT-GRAPH]], among them the crates with a project that the crate reaches only through path dependencies on crates without one, or behind a redirected crate without one that it may use: each brings its folder, its declared files and its own dependencies. |
797
+ | Member manifests | Under the `cargo` and `workspace-build` strategies of [[DES-UNIFICATION]], the `Cargo.toml` of every member of the crate's workspace: a feature that one member switches on in a shared dependency also reaches the other members built with it ([[EVD-CARGO-LOCKFILE]]). Under `hakari` the input is not added. There the other members can change a crate's features only through the third-party crates that the [[TERM-HACK-CRATE]] unifies, which holds only for what the hack crate covers: no member asks a feature of another member, `platforms` lists the host and a triple that it does not list runs one crate per command, no crate outside the workspace reaches a member through normal or build dependencies, and the configuration leaves nothing out, which the four checks that choose the strategy establish; and only while the hack crate is current, which its drift check establishes before the crate's tasks run. The hack crate's manifest stands in for the other members' manifests (**Hack crate**). |
798
+ | Hack crate | Under `hakari`, on every target of the crate that has its digest (**External dependencies**), the `Cargo.toml` of the [[TERM-HACK-CRATE]] and the configuration file of cargo-hakari, `.config/hakari.toml` or else `.guppy/hakari.toml`, as file inputs. A member reaches the hack crate's folder already through its dependency on it, an edge with `^` inputs; the manifest is named directly as well, so that it is in the key also of a member whose dependency is missing, until the drift check reports that. Generating the hack crate again, as after a member asks a third-party crate for another feature, changes its manifest and so every crate's key, and a change to `platforms` or to the excludes of the configuration changes the configuration file ([[DES-UNIFICATION]], "What the keys hold"). |
799
+ | Crates outside the workspace | Under `cargo` and `workspace-build`, on every target of the crate that has its digest, a fileset for the folder of each path crate outside the workspace that any member of the workspace reaches, with the root manifest of that crate's workspace where that is another file, the files that it declares and the variables and commands that it adds, as a path dependency without a project has them (**Path dependencies**): by path from a member, through the member's dependencies of every kind and behind those through normal and build dependencies, through any number of crates with a project or without, and as the redirected crates that any member may use, with the crates with a project behind them ([[DES-PROJECT-GRAPH]]). In a build of the whole workspace, such a crate can switch on a feature of a member or of a shared dependency, whichever member reaches it, as `z` did in [[EVD-HAKARI-UNIFICATION]]; a command that it adds can stand for its manifest where Nx cannot see that, and a file that it declares can change how the workspace compiles, as a schema that its build script reads. A folder that the crate's inputs hold already, through its own path dependencies, redirections or `^` inputs, is not named again. A crate without a report adds its folder alone, as for a path dependency. |
800
+ | Declared files | Each pattern of `fileInputs` in the crate's `[package.metadata.nx]` and its workspace's `[workspace.metadata.nx]`, resolved against the folder of the manifest that holds it, as a fileset with `includeIgnored` in the crate-file input, with one more for each folder of the plugin's projects below where the pattern starts. Every cached target of the crate thereby has them, and its dependents through `^` ([[REQ-BUILD-SCRIPT-INPUTS]]). |
801
+ | Path dependencies | For a path dependency that is no Nx project, because it is excluded, ignored, outside the repository or a crate whose folder holds `.cargo-checksum.json`, a fileset for its folder, and the root manifest of its workspace where that is another file, on every crate that depends on it, directly or through other crates, with the variables and commands that it adds (**Added variables and commands**, below). This holds whether or not the plugin has a report for the crate; without one, the path dependencies behind it are not known. Each path names the crate at the real path of its folder, so a path through a symbolic link to a crate with a project is that project's edge and no fileset. A crate with a project behind it gets no fileset here, because the edge to it brings it with what lies behind it (dependency sources). Where Nx cannot see those files, the plugin warns ([[DES-DIAGNOSTICS]]). |
802
+ | Redirected crates | The crates of [[DES-PROJECT-GRAPH]]'s redirected uses, the crates with a project behind a redirected crate without one included: through the member's edge and `^` inputs; without an Nx project, like a path dependency without one, the warning included, and without a report its folder alone, its path dependencies not followed; where the edge is left out, as a fileset for the folder, the root manifest of the workspace, the declared files and the added variables and commands of the crate and of each crate that [[DES-PROJECT-GRAPH]] says the edge would have brought, on the member's targets, the warning of a path dependency without a project included for one that Nx cannot see. |
803
+ | External dependencies | On every cached target of a crate other than `fmt-check`, the crate's lockfile digest: a `dependentTasksOutputFiles` input for the crate's file among the outputs of its workspace's lockfile task, on which the target depends; on `doc`, the digests of all members ([[DES-LOCKFILE-HASHING]]). Under the `cargo` and `workspace-build` strategies of [[DES-UNIFICATION]], every such target of a crate hashes the digests of all members, as `doc` does: in a build of the whole workspace, a package that only another member reaches can switch on a feature of a dependency that the crate shares, as `cargo update -p g` did in [[EVD-HAKARI-UNIFICATION]], so a change to the lockfile that changes any member's digest runs every crate of the workspace again. Under `hakari`, the crate's own digest is enough, because the hack crate carries what the other members' packages ask of third-party crates while its drift check passes (**Hack crate**). No cached target that runs cargo has `Cargo.lock` as a file input: Nx hashes such a target before the run starts, before the lockfile task can update the file ([[EVD-NX-24-LOCKFILE-UPDATE]]). Each target with a digest input also has an `env` input for `NX_RUST_RUN_ID` ([[DES-LOCKFILE-HASHING]]). |
804
+ | Plugin | `externalDependencies: ["@convesoft/nx-rust"]` where Nx has a node for the package, so that the key holds the plugin's package and the packages it depends on, as the JS lockfile locks them, and no other external node of the Nx graph. Without an `externalDependencies` input, Nx hashes every external node, so each change to a JS lockfile would change the key of every Rust task ([[EVD-NX-24-EXTERNAL-NODES]]). Naming a package without a node fails the hash of every task that names it, and Nx creates a node only from a JS lockfile that it analyses and that lists the package ([[EVD-NX-24-PLUGIN-VERSION]]). Where the plugin cannot establish both, it declares `externalDependencies: []` and puts its own version into the option `pluginVersion` of every target it infers ([[DES-PLUGIN-OPTIONS]]). It establishes them as Nx's JS plugin decides: the lockfile is that of the package manager that `nx.json` names or whose lockfile is in the repository root, Nx analyses it unless `pluginsConfig` in `nx.json` says otherwise, Nx sees it, and it lists the package with a version from a registry; a plugin that `nx.json` names by path runs from another folder than the installed package and takes the option. Each of its executors declares that option, so it draws no warning, and leaves it out of the cargo command ([[DES-UNKNOWN-OPTIONS]]); Nx hashes it into each task of the project. Every inferred target has this input, the uncached ones too: on the lockfile task, `audit`, `deny` and `update` it only decides what `nx affected` selects, so that an upgrade of the plugin selects them and a change to the JS lockfile outside the plugin's package does not ([[EVD-NX-24-PLUGIN-VERSION]]). |
805
+ | Tool configuration | On `lint`, every `clippy.toml` and `.clippy.toml` between the crate and the repository root. On `fmt-check`, every `rustfmt.toml` and `.rustfmt.toml` on the same path. On `test` with the nextest runner, the workspace's `.config/nextest.toml`. Where `CLIPPY_CONF_DIR` is set, in the environment or under `[env]` in Cargo's configuration, `lint` also has a runtime input that prints the configuration file that clippy can take there (**Clippy's configuration folder**). |
806
+ | Environment | One `env` input per variable in the list below, plus the variables the repository adds. |
807
+ | Toolchain | A `runtime` input that runs, in the root folder of the crate's workspace where its cargo commands run ([[DES-INVOCATION]]), `rustc -Vv`, which names the toolchain of the task's cargo, and then `-Vv` of the compiler that cargo will run there where a setting names another: the one that `RUSTC` in the task's environment names, else `CARGO_BUILD_RUSTC`, else `build.rustc` of the configuration files that cargo reads in that folder, which graph creation resolves as cargo does, to an absolute path or a bare name; where the files read as Cargo 1.91 reads them, without `include`, and as later versions read them, with it, give different compilers, it asks both, and a file of cargo's walk counts in its own place also where a deeper file includes it ([[EVD-CARGO-COMPILER-SELECTION]]). `rustc -Vv` stays beside a named compiler because the task's cargo still comes from that toolchain and its version decides what cargo passes the compiler, so a named compiler only adds to the key. On `doc` and `test`, which run rustdoc, it does the same for the rustdoc that `RUSTDOC`, `CARGO_BUILD_RUSTDOC` or `build.rustdoc` names; without one, cargo runs the `rustdoc` of the toolchain that `rustc -Vv` names. It then prints the variables of the task's environment whose names start with `CARGO_PROFILE_` or `CARGO_TARGET_`, below. Each program is asked as cargo asks it: a rustup proxy through rustup's toolchain files, overrides and `RUSTUP_TOOLCHAIN`, a bare name through `PATH`, and a path, from the workspace root, as whatever lies there when the key is computed, so an update of the compiler at a named path changes the key ([[EVD-CARGO-COMPILER-SELECTION]]). Where nothing names a compiler or a rustdoc, the command prints what `rustc -Vv` and the variables print, as before these settings counted. The folder is part of the command, so workspaces with different toolchains never share one evaluation. |
808
+ | Artifact folders | On a cached `build` and `doc`, a `runtime` input, one per workspace, whose command runs the plugin's own script in the repository root with the task's environment and the workspace's root folder as its argument. It prints two lines and no path of the checkout. The first names the triples that cargo will build for in the workspace root without `--target`, read with the function that graph creation uses for the outputs ([[DES-OUTPUTS]]): the triples, none, or a triple that cannot be named with its reason. The second names the artifact directory that cargo reports there, with `cargo metadata --no-deps` and `RUSTUP_AUTO_INSTALL=0`, as the outputs name it: the folder that the system reaches, relative to the repository's real path, or that it lies outside the repository. The command names Node, the script and the folder by paths that reach no key, because Nx hashes what a runtime input prints and not its command ([[EVD-CARGO-TRIPLE-FOLDERS]]). Where the script cannot run, as for a plugin that Nx loads from its TypeScript source, or cargo fails, as for a pinned toolchain that is not installed, the command prints the line of a failure and a random value instead (**Failing runtime inputs**, below). Nx evaluates the command once for each task, not once for each workspace ([[EVD-CARGO-TRIPLE-FOLDERS]], [[EVD-NX-24-MOVED-ARTIFACT-DIRS]]), at about 29 ms each, which the design keeps (**Cost of the artifact folder input**, below). |
809
+ | Test mode | On `test` in a workspace with `affectedTests`, a `runtime` input whose command runs the plugin's own script in the repository root with the task's environment and the workspace's root folder as its argument, and prints the [[TERM-TEST-MODE]]: `full`, `affected:<baseline commits>`, or a line that names an invalid `NX_RUST_TEST_MODE`. The script reads cargo-affected's database without writing to it, starts no other program, and names no path of the checkout; where it cannot run, the command prints the line of a failure and a random value, new at each evaluation (**Failing runtime inputs**, below; [[DES-TEST-MODE]]). |
810
+ | napi CLI | On `napi-build`, a `runtime` input whose command runs the plugin's own script in the repository root with the crate's folder as its argument, which prints the version of the `@napi-rs/cli` that Node resolves from that folder, the one that the task post-processes with, and no path of the checkout; where the script cannot run, the line of a failure and a random value (**Failing runtime inputs**, below). Beside it an `env` input for `npm_new_version`, whose value `napi build` and `napi-build` write into `index.js`, and a fileset, with ignored files, for the `dtsHeaderFile` that the crate's napi settings name, where it lies inside the repository. The CLI's own dependencies are not in the key ([[DES-NAPI]]). |
811
+ | wasm-bindgen CLI | On `wasm-build`, a `runtime` input that prints what `wasm-bindgen --version` writes in the root folder of the crate's workspace, where the task finds the CLI on `PATH`, or a random value where that fails, and then one line for each variable that the CLI reads, `WASM_BINDGEN_ANYREF`, `WASM_BINDGEN_EXTERNREF` and `WASM_BINDGEN_MULTI_VALUE`, that says whether it is set, since the CLI acts on an empty value as on any other while Nx hashes an empty `env` input as an unset one; and an `env` input for the value of each ([[DES-WASM]], [[EVD-WASM-POSTPROCESS]]). |
812
+ | Options | Features, profile and target triple are target options, which Nx hashes. A triple that Cargo's configuration or the graph's environment picks is text in the outputs of `build` and `doc`, which Nx hashes with the project's configuration ([[DES-OUTPUTS]]). |
813
+ | Extra | Runtime commands the repository adds. |
814
+
815
+ The toolchain command prints what each `-Vv` writes to standard output, run with `RUSTUP_AUTO_INSTALL=0` and with its standard error discarded, and when one fails, as for a pinned toolchain that is not installed, for a named compiler that does not exist or for an empty `RUSTC`, on which cargo fails too, it prints a random value instead, new at each evaluation, so that no result stored under that key is ever restored and the task runs as plain cargo does ([[ADR-GRAPH-NO-TOOLCHAIN-INSTALL]]).
816
+
817
+ **Failing runtime inputs.** Nx 24 runs a runtime input through `sh -c` in the repository root with the task's environment, once for each task it hashes, takes what the command writes to standard output and to standard error, trims the whitespace at both ends of each, and keys the task on the two one after the other, whatever the exit status; bytes that are not UTF-8 fail the whole command; and it shows nothing of a runtime input on the terminal, also with `--verbose` ([[EVD-RUNTIME-INPUT-SCRIPTS]], [[EVD-RUSTUP-MISSING-TOOLCHAIN]]). So no runtime input can fail its task or print a message, and each of the plugin's ends, where its query fails, in a value that no other evaluation prints: Nx misses the cache and never restores what it stores under that key, so a task runs more often and never less ([[GOAL-TRUSTED-CACHE]]). That value comes from `od` and `/dev/urandom`, and where `od` is missing or fails, from `/dev/urandom` read with the shell's own `read` and `printf`, so that it needs no program besides the shell, which a `PATH` that lists only allowed tools can leave out together with the tool whose failure it covers, as awk; where `/dev/urandom` cannot be read, it is the process ids of the shell and its parent and, where `date` exists, the time. Every runtime command of the plugin that can fail ends in it: the toolchain's versions, its variables, the wasm-bindgen CLI and the script inputs; nextest's version alone prints `cargo-nextest: not found`, a state that holds as long as nextest is missing. The commands of the inputs that run one of the plugin's Node scripts, the artifact folders, the test mode and the napi CLI, print first, on a line of its own also after output without a final line break, `@convesoft/nx-rust: this runtime input failed`, and send the script's standard error to the file descriptor that `NX_RUST_INPUT_ERRORS` names, and to `/dev/null` where it is unset, as when Nx hashes; the artifact folder script writes there the reason and cargo's own standard error. Where such a task runs, its executor runs each of those commands of the task's target again, once every check that fails the task has passed, in the repository root with the task's environment, its dotenv values included and without `FORCE_COLOR`, with `NX_RUST_INPUT_ERRORS=2`, the command's own standard error, and without `NX_RUST_COMMAND_ID`, so that the mode command adds nothing to the command's record ([[DES-TEST-MODE]]). Where one prints that line, the task warns at the top of its output that the command failed when the executor ran it for the task, with the command and what the script wrote to standard error, and that if it failed the same way when Nx computed the task's key, the result is not restored from the cache: the executor cannot see what Nx hashed, so a failure in one of the two runs only says nothing of the other ([[DES-DIAGNOSTICS]]). The warning shows with the output styles `static` and `stream`; `summary` and `static-failures-only` do not show it inline for a successful run of several projects. The tasks of a batch that share a command and an environment run it once, a task that a batch leaves for a following batch runs it twice, and a failure that is gone by then gives no warning. The second run costs a task that runs, which runs cargo anyway, one start of Node, and for `build` and `doc` one more `cargo metadata --no-deps`, about 30 ms, beside the one evaluation of each hash; a task that Nx restores runs nothing. The other inputs that can fail need no such warning: a toolchain whose `-Vv` fails fails the task's cargo too, and a missing wasm-bindgen fails `wasm-build` before cargo ([[DES-DIAGNOSTICS]]). Not taken: a stable value with the script's error in place of the random one, which would let a failure that repeats restore its own results; and failing the task, which Nx does not offer for a runtime input and which the executor could do only through the same second run, while a task that runs gives no wrong result. A signal that kills the shell before its fallback, bytes that are not UTF-8, which collapse to one key where they arrive through the task's environment and abort Nx's hashing where a command prints them, variables whose names dash does not pass on, and the last resort without `/dev/urandom` and without `date`, whose process ids repeat in fresh process namespaces, remain open in nxr-ntvnds. Decided in nxr-aqgka5 on 20 November 2026, the fallback without `od` and the wording of the warning in its review, from [[GOAL-TRUSTED-CACHE]] and [[EVD-RUNTIME-INPUT-SCRIPTS]]; to undo the second run, drop it and the variable, which leaves such a failure silent again.
818
+
819
+ **Cost of the artifact folder input.** One evaluation took about 29 ms in `two-workspaces` with cargo 1.100.0 through rustup: about 12.5 ms to start Node, about 7 ms to load the script's modules, about 2 ms of them Node's `child_process`, and about 7 ms for `cargo metadata --no-deps`; the shell adds nothing that shows, and Node's compile cache saved nothing ([[EVD-RUNTIME-INPUT-SCRIPTS]]). The design keeps it, because no exact way costs less: the triples need the plugin's reading of Cargo's configuration in Node, since no stable cargo command reports them ([[EVD-CARGO-TRIPLE-FOLDERS]]); the artifact directory needs cargo, since working it out in Node would repeat how cargo finds and merges its configuration files, the Cargo home, the environment and `include`; and one cargo call for the tasks of a workspace in one run would need a record that hashing writes and that each task's own environment, dotenv files included, keys, since Nx runs every evaluation in a process of its own and passes nothing between them, to save about 7 ms a task. Decided in nxr-aqgka5 on 20 November 2026.
820
+
821
+ **What the toolchain input does not follow.** A wrapper that `RUSTC_WRAPPER`, `RUSTC_WORKSPACE_WRAPPER` or `build.rustc-wrapper` names counts by its name only: cargo asks the compiler's version through it, but the toolchain command does not start it, because a wrapper such as sccache may start a server. A wrapper that runs another compiler than the one it is handed is the repository's to key with `runtimeInputs`. A `build.rustc` or `build.rustdoc` in a configuration file outside the repository is read when Nx creates the graph; under the Nx daemon a change to it reaches the command once the graph is created again ([[RISK-HOST-ENVIRONMENT]]). The Cargo home is that of the graph's environment: a `CARGO_HOME` that only a dotenv file of the task sets is not followed. Where rustup is not installed, a `rustdoc` that `PATH` finds in another installation than `rustc` counts only through `rustc -Vv`.
822
+
823
+ The environment list:
824
+
825
+ - `RUSTFLAGS`, `CARGO_ENCODED_RUSTFLAGS`, `RUSTDOCFLAGS`, `CARGO_ENCODED_RUSTDOCFLAGS`, `RUSTC`, `RUSTC_WRAPPER`, `RUSTC_WORKSPACE_WRAPPER`, `RUSTDOC`, `RUSTC_BOOTSTRAP` and `CARGO_BUILD_TARGET`.
826
+ - The `CARGO_BUILD_*` forms of the same settings: `CARGO_BUILD_RUSTFLAGS`, `CARGO_BUILD_RUSTDOCFLAGS`, `CARGO_BUILD_RUSTC`, `CARGO_BUILD_RUSTC_WRAPPER`, `CARGO_BUILD_RUSTC_WORKSPACE_WRAPPER` and `CARGO_BUILD_RUSTDOC`.
827
+ - Every variable whose name starts with `CARGO_PROFILE_` or `CARGO_TARGET_`, which set a profile's or a triple's settings, other than `CARGO_TARGET_DIR`, which says where the artifacts go and not what they are. That still holds for every target whose outputs do not lie in the artifact directory, so their keys do not change with the directory. The outputs of `build` and `doc` do lie there, so their artifact folder input prints the directory that cargo will use, from `CARGO_TARGET_DIR`, `CARGO_BUILD_TARGET_DIR`, the configuration files and a Cargo home that only the task's environment names, in the form that the outputs name it: their keys then split only where their outputs do already, or where a dotenv file of the task moves the directory, which the executor refuses ([[DES-OUTPUTS]]). Their names hold a profile's or a triple's name, so no list of `env` inputs can name them all: the toolchain command prints each with its value, sorted bytewise, in the same process as `rustc -Vv`. It reads them with POSIX awk's `ENVIRON` and prints one line `NAME=value` each, where a backslash in the name or the value becomes two and a line break becomes `\n`, and after the last one the line `end of variables`. The lines of `env` cannot tell a line of a multi-line value from a variable, so the second line of a value left the key and a variable of another name whose value held a line such as `CARGO_PROFILE_DEV_OPT_LEVEL=1` entered it; and Nx trims the whitespace at both ends of what a runtime input prints, which took a trailing space off the last value, such as that of a linker that cargo then does not find ([[EVD-RUNTIME-INPUT-SCRIPTS]]). Decided in nxr-aqgka5 on 20 November 2026, from [[GOAL-TRUSTED-CACHE]]; the end line changed every key, which needs no migration while the plugin is not published ([[ADR-PUBLISHING-AT-1-0]]). Where awk fails, it prints a value that never repeats (**Failing runtime inputs**, below).
828
+ - On `test` with the nextest runner, every variable whose name starts with `NEXTEST_`, which choose nextest's profile, as `NEXTEST_PROFILE` does, or change what a run does, as `NEXTEST_RETRIES` does, so that the repository's nextest configuration reaches the key as the command applies it ([[DES-TEST-RUN]], "nextest's configuration"). No list can name them all either, and the toolchain command of such a target prints them in the same way. That command also prints, before the toolchain's versions, what `cargo nextest --version` writes in the workspace root, as cargo finds nextest there with the task's environment, or `cargo-nextest: not found` where that fails, so that another version of nextest, or none, changes the key, as another compiler does; the keys of targets that nextest does not run keep their command (decided by the control plane on 16 November 2026 in nxr-jb6g5y, after a review restored a result with nextest missing).
829
+ - `CC`, `CXX`, `AR`, `CFLAGS`, `CXXFLAGS`, `PKG_CONFIG_PATH` and `MACOSX_DEPLOYMENT_TARGET`.
830
+ - `OPENSSL_DIR`, `OPENSSL_LIB_DIR`, `OPENSSL_INCLUDE_DIR`, `OPENSSL_STATIC` and `OPENSSL_NO_VENDOR`.
831
+ - `CLIPPY_CONF_DIR`, on `lint` only. Its `env` input hashes the folder's path, and the runtime input of **Clippy's configuration folder** the file that clippy takes there and in each folder that Cargo's `[env]` names for it.
832
+ - `CARGO_BUILD_WARNINGS`, on every target that compiles: `build`, `check`, `lint`, `test`, `bench`, `run`, `doc` and the artifact targets, the uncached `bench` and `run` included. Cargo's `build.warnings` setting turns warnings into failures, also where the batch applies it to a command with JSON messages ([[DES-BATCH]], "Denied warnings"), so a result that passed with warnings allowed must not be restored where they are denied ([[EVD-CARGO-TARGET-COMMANDS]]). The configuration files in the repository that set it are inputs already, as workspace files of the table above.
833
+
834
+ **Clippy's configuration folder.** Where `CLIPPY_CONF_DIR` is set, clippy no longer starts in the crate's folder. It looks for `.clippy.toml` and `clippy.toml` in the folder that the variable names, a relative one from the workspace root, where cargo runs clippy-driver, and in each folder above it up to the file system's root, and takes the first folder that holds either; where both are there, it takes `.clippy.toml` ([[EVD-CLIPPY-RUSTFMT-CONFIG-LOOKUP]]). Clippy can be given the variable in two ways: from the task's environment, and from `[env]` in a configuration file that cargo reads, as a string or as a table with `value`, where cargo passes the value as written, and with `relative = true` resolves it against the folder that holds the file's `.cargo` folder; the environment's value wins unless the file sets `force = true`. The folder is often outside the repository, where Nx hashes no file, and the `env` input hashes only the environment's path, so a change to `too-many-arguments-threshold` in that folder's `clippy.toml` restored a cached passing `lint` in 1.0.0-rc.1, and so did one in a folder that only `[env]` named, inside the repository or outside it (nxr-rpcfg4). `lint` therefore has a runtime input that looks in every folder that clippy can be given: the environment's, where the variable is set, and each folder that `CLIPPY_CONF_DIR` under `[env]` names in the configuration files that cargo reads in the workspace root and in the files they include, which graph creation reads with the walk that serves `build.rustc`, written into the command as cargo would pass them. It does not repeat cargo's precedence between these sources: it prints the configuration of each, after a line that names its source, so that the key changes whenever any of them changes, which runs more than clippy needs but never less ([[GOAL-TRUSTED-CACHE]]). Where none is set, the command prints nothing, so that those keys hold nothing of it. For each folder, the command goes to the workspace root and from there to the folder, following symbolic links, and looks in it and above it as clippy does. In the first folder that holds either name, it prints each of the two that exists and is no folder, with its name, its size and its content: the key follows the file that clippy takes without the command deciding which of the two that is. It prints a fixed line where the value names no folder or is empty, where such a file cannot be read and where no folder holds one, in which cases clippy fails or uses its defaults whatever the key holds, and a value that no other evaluation prints where the workspace root is missing or the size or content of a file that it found readable cannot be read. It prints no path, so checkouts in other folders share the keys where the values are the same. Nx runs the command with the task's environment, its dotenv files included, each time it hashes the task ([[EVD-NX-24-INPUT-SEMANTICS]]), so the key follows the files also under the Nx daemon and where only a dotenv file sets the variable. A configuration file inside the repository that sets `[env]` is a workspace file input already and makes Nx create the graph again when it changes; one outside it, such as the Cargo home's, is read when the graph is created, and the warning about Cargo configuration that Nx does not hash names it, as for any `[env]` ([[RISK-HOST-ENVIRONMENT]], [[DES-DIAGNOSTICS]]). `nx affected` sees no change to a file outside the repository, as for every file outside it. The `clippy.toml` file inputs stay while the variable is set, which only splits keys more often than clippy needs.
835
+
836
+ **Whole-workspace builds.** A build of the whole workspace compiles a crate with the features that every member and every crate built with them ask for. [[EVD-HAKARI-UNIFICATION]] showed two changes that recompiled a member with other features of a shared dependency while its digest and every member's manifest stayed the same: a lockfile change of a package that only another member reaches, and a change to the manifest of a path crate outside the workspace that only another member depends on. The control plane decided on 14 November 2026, under [[GOAL-TRUSTED-CACHE]], not to accept this as a limit: running more than a key promises is allowed, running less is not. So under the `cargo` and `workspace-build` strategies a crate's key covers what can change the features that cargo compiles it with, the digests of all members (**External dependencies**) and the crates outside the workspace that any member reaches (**Crates outside the workspace**), beside every member's manifest. The cost is that a change to the lockfile, or to such a crate, runs every crate of the workspace again under these strategies. The key holds no other member's sources: it covers what can change the features that the crate is compiled with, and a result that it restores says that the crate's own tasks passed. A compile error in another member fails the `test` tasks that run in the same command, but is no reason to run a cached one again, and with `NX_CACHE_FAILURES=true` such a failure is stored under a key that does not hold its cause ([[ADR-CACHED-FAILURES]]); keying every task on every member's sources would end caching per crate under the default strategy. Under these strategies too, some groups run one crate per command, such as a non-host triple under `workspace-build` ([[DES-BATCH]], "Groups of one crate"); such a command depends only on the crate's own dependencies, of which these keys hold a superset.
837
+
838
+ **Named input.** The crate-file input is the project's named input `default`, which its targets name as `default` and `^default`. Every Nx project has a `default`, Nx's own or the one in `nx.json`, and a `^` input fails the hash of a task whose project depends on a project without that named input ([[EVD-NX-24-INPUTS-OUTPUTS]]), as a crate can depend on a JS project. A JS project that depends on a crate and hashes `^default` thereby hashes the crate's input. Besides the crate's folder, it holds the root manifest of the crate's workspace, from which the crate inherits fields such as its edition and lints also where another workspace builds it ([[EVD-CARGO-DEPENDENCY-SIDE]]).
839
+
840
+ **The repository's `default`.** A crate's `default` replaces the one in `nx.json` for the crate's project, so it keeps every entry of the repository's `default` but its file sets under `{projectRoot}`, negated or not: named inputs such as `sharedGlobals`, `env`, `runtime` and `externalDependencies` entries and file sets under `{workspaceRoot}` reach the crate's key and its dependents'. What a crate hashes of its own folder is the whole folder, which only the crate's own configuration of a target can narrow. The plugin's targets name no other named input, so `production` and the like reach no Rust target.
841
+
842
+ **Beyond the declared inputs.** Nx puts two parts into every task's key that no input names: the file `nx.json`, and the project's configuration, which is, for each of the project's targets, its executor, `inputs`, `outputs`, `options`, `configurations` and `parallelism`, and the project's root, named inputs and tags ([[EVD-NX-OPTION-VALIDATION]], "Cache key"). A key also holds the configuration of each project whose named input it hashes through `^` inputs ([[EVD-NX-24-PLUGIN-VERSION]]). Any change to `nx.json`, also one that reaches no Rust target, therefore changes every key. A changed option or configuration of one target of a crate, also from a `project.json`, a `package.json` or `targetDefaults`, changes the keys of every task of that crate and of the crates that depend on it, and so does a changed script in a `package.json` of the crate's folder that Nx reads, because Nx hashes the script with its `nx:run-script` target. Nx's hash of the project's configuration leaves out each target's `metadata`, `cache` and `dependsOn` and the project's `metadata`, so a change to them reaches a key only through the file it is written in, where that file is among the task's inputs, as a `project.json` in the crate's folder is. The plugin cannot take these parts out of a key. They make tasks run more often than their inputs require, never less. The plugin uses the named inputs for one purpose of its own: a project with warnings gets a named input that no target names and that holds a digest of them, so that a change of its warnings changes the keys of its tasks and of the tasks that depend on it ([[DES-DIAGNOSTICS]], "Warnings where they are seen").
843
+
844
+ **A project at the repository root.** A crate or a workspace project at the repository root shares its folder with the repository's JS package. Its crate-file input, the whole folder, then covers the root `package.json` and the JS lockfile, and Nx's JS plugin gives the project, which owns that `package.json`, an edge to each npm package it lists, so that the `^default` of the project's targets hashes those packages and the packages behind them, beside what the plugin input names ([[EVD-NX-24-EXTERNAL-NODES]], [[EVD-NX-24-PLUGIN-VERSION]]). Any change to either file, also outside the plugin's package, therefore changes the key of `doc` on a workspace project there, of every cached target of a crate at the repository root, and of every cached target of a crate that depends on that crate, directly or through other crates, because its `^default` holds that crate's folder. The lockfile task, whose inputs name neither the folder nor `^default`, keeps its key, and so do the tasks of the crates that do not depend on a crate at the repository root. A workspace in a subfolder shares no folder with the JS package, and the keys of its crates follow the JS lockfile only through the plugin input, unless they depend on a crate at the repository root. This limit is accepted: the tasks it reaches run after a change that cannot affect them, and none is restored with a stale result. What `nx affected` selects in this layout is in [[DES-LOCKFILE-HASHING]].
845
+
846
+ **Redirected uses.** Nx asks for a plugin's targets before it merges the projects of every plugin and entry, so the plugin works out the redirected uses for the inputs with the projects of its own entry. A redirected crate that another entry gives a project counts there as one without a project, and its folder joins the member's inputs beside the edge that the dependencies of the merged graph add.
847
+
848
+ **Uncached targets.** `fmt`, `bench` and `run` are not cached, but declare the inputs of `fmt-check`, `build` and `build`, so that `nx affected` selects them when what they read changes. They do not depend on the lockfile task, so `bench` and `run`, `build` and `doc` where the plugin leaves them uncached ([[DES-OUTPUTS]]), and the targets of the crates of a workspace without a lockfile task ([[DES-LOCKFILE-HASHING]]) name the workspace's `Cargo.lock`, read also where Git ignores it, in place of the digest and of `NX_RUST_RUN_ID`, as `audit` and `update` do ([[DES-WORKSPACE-TARGETS]]).
849
+
850
+ The variables and commands that the repository adds, with `envInputs` and `runtimeInputs` in the plugin options, in the workspace table or in a crate's table ([[DES-PLUGIN-OPTIONS]]), go into the crate's own named input, the one that its dependents hash through `^` inputs, and not onto single targets. A dependent's key therefore changes with them, also in another workspace, because Nx hashes the `env` and `runtime` entries of a dependency's named input into the dependent's key and those of a dependency's target into no other key ([[EVD-NX-24-OPTION-SEMANTICS]]).
851
+
852
+ **Declared files.** Task-based affected matches changed files against filesets, so `nx affected` selects the tasks of the crate and of its dependents when a declared file changes. `includeIgnored` makes Nx hash a declared file that Git ignores. Nx leaves a file that the root `.gitignore` or `.nxignore` ignores out of the changed files before it matches them, also when a fileset with `includeIgnored` names it, so a change to such a file changes the keys and makes no task affected. The workspace project receives its members' patterns through its dependency on every member ([[DES-WORKSPACE-TARGETS]]). The declared files of a crate travel with its folder: wherever the plugin puts a crate's folder into another crate's inputs beside the `^` inputs, as for a crate outside the workspace under the strategies that build the whole workspace (**Crates outside the workspace**), a path dependency without a project, the crates behind it, a redirected crate whose edge is left out with the crates that its edge would have brought, or an assumed use, it also puts there the filesets of the crate's own `fileInputs` and its workspace's, resolved and checked as for a project; they are read from the crate's report, so a crate without one, such as one whose folder holds `.cargo-checksum.json` or whose report failed, adds its folder alone.
853
+
854
+ The plugin resolves each pattern's fixed part, its segments before the first one with a glob character, to its real path, `..` and symbolic links included, and declares that path with the rest of the pattern, and also each link that the fixed part passes, at the path where the link itself lies. In these paths, and in the folders of the filesets below, it escapes each character that Nx would read as glob syntax, `*`, `?`, brackets, braces, parentheses and the backslash, with a backslash, so that a link to a folder named `real[1]` or `old(1)` gives the files of that folder and not those of `real1` or a group. Nx fails the hash of every task whose fileset with `includeIgnored` has a `.` or `..` segment. Nx keeps the hash of a link to a file until the link itself changes or `nx reset` clears the hashes Nx keeps, and matches changed files by their own paths, so a fileset for the link alone would change no key and make no task affected when the file or folder it points to changes, and one for the real path alone would make no task affected when the link is replaced by one that points elsewhere ([[EVD-NX-24-FILE-INPUTS]]). A link that passes outside the repository fails graph creation as a real path there does. A link that only the glob part reaches stays unresolved, because resolving it would mean walking the tree at graph creation: Nx's `**` does not descend into a linked folder, and a link to a file that a wildcard matches keeps its first hash, so the repository declares the linked folder or file itself. Graph creation fails with a message that names the manifest and the pattern for a pattern with a `..` segment after a glob character, which could lead anywhere; for one whose real path lies outside the repository, with a message that points to the runtime commands, because Nx hashes no file by a path that leaves the repository and `nx affected` sees no change to a file outside it; and for one whose real path lies in the build or artifact directory of the crate's workspace, whose files are Cargo's outputs ([[REQ-FILE-INPUTS-HASHABLE]], [[ADR-DECLARED-FILE-INPUTS]], [[DES-DIAGNOSTICS]]).
855
+
856
+ **Patterns over project folders.** Nx matches a fileset with `includeIgnored` only against the files of the deepest project whose folder holds the folder that the fileset is read from, the project at the repository root not counted, and leaves out the projects in folders below it; a fileset whose folder no project's folder holds reaches every file it names. Nx reads a fileset from its segments before the first one with glob syntax, after it has split each brace group of plain names into entries of their own ([[EVD-NX-24-FILESET-SCOPE]]). So `../*/src/**` in `rust/crates/api`, where `rust` is the folder of a workspace project, would reach none of the other crates' files. The plugin therefore first replaces each pattern's braces by their alternatives, nested ones and those with globs included, and treats each alternative as a pattern of its own from then on: its own fixed part, links, filesets and checks, with the pattern and the alternative in a message; a `..` after a glob character in the pattern as written stays an error. `../{app,web}/src/**` thus gives `rust/crates/app/src/**` and `rust/crates/web/src/**`, each read from inside its own project's folder. A pattern names folders where it ends in `/`, has no glob, or ends in a name after a glob, such as `../*/src`, which may be a folder's as well as a file's; it then counts everything below the folders it names. Nx does so for a path without a glob, and for a glob, whose trailing `/` Nx drops, the plugin adds the fileset with `/**` after it. A pattern that ends in a glob, such as `*` or `*.proto`, names files only, as Nx reads it. For each folder of a project that the plugin's entry creates below the folder that Nx reads an alternative from, the plugin adds a fileset with `includeIgnored` that starts in that folder and names the files below it that the alternative names: the rest of the alternative after the names of the folders in between, whose segments are matched against those names as Nx matches a fileset, through its own `matchGlobPaths`, with its reading of extended groups such as `@(a|b)`, `!(a)` and `*(a)`, of classes and of escapes, and `**` standing for any number of folders; and `<project folder>/**` where the alternative names folders and names that folder or one above it. Where the installed Nx lacks `matchGlobPaths`, a segment with a group is taken to match, and a pattern with more than 256 alternatives is taken to name everything below each project folder; both can only add files. `../*/src/**` from `rust/crates/api` thus gives `{workspaceRoot}/rust/crates/*/src/**` and `{workspaceRoot}/rust/crates/<crate>/src/**` for each crate there, `api` included, `../a*/src/main.rs` gives `rust/crates/<crate>/src/main.rs` for the crates whose names start with `a`, and `../{app,other}/` gives `<project folder>/**` for each project folder below `app` and `other`. The pattern's own fileset stays, so that the key keeps every file that it covered before, those of the project that holds its folder and those of no project among them. Where no project holds the folder, the added filesets name files that it covers already, and a pattern that starts at the repository root, which Nx never narrows, gets none. The added filesets travel with the pattern, to dependents and with the folder of a crate without a project. None of this depends on which files exist, so a file added later in a covered folder is hashed without graph creation running again.
857
+
858
+ **Cargo's directories.** Nx reads a fileset with `includeIgnored` from the disk and enters the folders that Git ignores, Cargo's build and artifact directories among them, so a pattern whose folder holds one, such as `../../**` or one that starts at the repository root, would put Cargo's outputs into the key, which a build then changes ([[EVD-NX-24-FILESET-SCOPE]]). Cargo's outputs stay out of the key ([[ADR-RESULTS-ONLY-CACHE]]): for each build and artifact directory inside the repository of a workspace that the plugin knows, those of the crates without a project included, that lies below the folder that one of a crate's patterns is read from, the crate's filesets get a negated fileset with `includeIgnored` for the directory, which Nx applies to all of them and does not walk into. A directory that a pattern of the crate is read from or points into, which only another workspace's can be, stays, as the repository declared it.
859
+
860
+ Nx calls each entry's `createNodes` at every computation of the graph, which the daemon starts when a file changes, and the plugin keeps nothing from one computation to the next, so a crate added later in a folder that a pattern names gets its fileset in the graph that follows. Projects of other plugins and entries are known only once Nx has merged the projects, which `createDependencies` receives. There, for each alternative whose folder a project's folder holds, every project folder below it whose files the alternative names, with its segments matched as above, must find among the crate's filesets the one that the plugin would give that folder, or one for the whole folder; otherwise graph creation fails with a message that names the manifest, the pattern and the alternative, the crates and the project, and gives the patterns to add beside it, relative to the manifest ([[REQ-FILE-INPUTS-HASHABLE]], [[DES-DIAGNOSTICS]]). A folder that the alternative does not reach fails nothing. A pattern that the repository adds there starts inside that project's folder, so Nx matches it against that project's files, and it is the fileset that the check looks for. A warning instead would leave the key without the files ([[ADR-DECLARED-FILE-INPUTS]]).
861
+
862
+ **Added variables and commands.** An edge brings, besides the crate's files, the `env` and `runtime` entries of its `default`: the variables and commands that the crate's own table and its workspace's add with `envInputs` and `runtimeInputs` ([[DES-PLUGIN-OPTIONS]]). Wherever the plugin puts a crate's folder into another crate's inputs in place of an edge, or as a crate outside the workspace under the strategies that build the whole workspace (**Crates outside the workspace**), it also puts there an `env` input for each variable and a `runtime` input for each command that the crate's own table and its workspace's add: for such a crate outside the workspace, for a path dependency without a project and the crates without a project behind it, for a redirected crate without a project, and for a redirected crate whose edge is left out and each crate, with a project or without, that [[DES-PROJECT-GRAPH]] says the edge would have brought. They are read from the crate's report, as its declared files are, so a crate without one adds none, while a crate whose files Nx cannot see adds them all the same, since they are no files. Those of the plugin options reach every crate of the plugin entry already. A path dependency's go into the crate's named input with its folder, so that the crate's dependents hash them too, and a left-out edge's onto the member's targets, beside its folder. Each variable and each command is declared once: once among what the plugin adds for the crates without an edge, however many of them add it, and not at all where the crate's own named input or another input of the target already names it. Nx runs a `runtime` input through `sh -c` in the repository root, whichever project's input names it ([[EVD-NX-24-INPUT-SEMANTICS]]), so the plugin passes each command unchanged: it runs in the folder where it runs for the crate that adds it, and a command tied to a folder names that folder from the repository root, for that crate as for the member. A value of the wrong type in either key fails graph creation with a message that names the manifest, as for a project ([[DES-PLUGIN-OPTIONS]]).
863
+
864
+ A `rust-toolchain.toml` or `.cargo/config.toml` inside a member crate is hashed with the crate's files, although it does not apply to the commands the plugin runs ([[DES-INVOCATION]]). An input the plugin cannot see is the repository's to declare, through `fileInputs` and the extra environment variables and commands. A `build` that read an undeclared file in the repository fails ([[DES-BUILD-INPUT-CHECK]], [[RISK-UNDECLARED-INPUTS]]).
865
+
866
+ **Nx Cloud Ultracache.** Every inferred Rust target sets `ultracache: { mode: "off" }` ([[EVD-NX-24-ULTRACACHE]]). Under Nx Cloud's default `on` mode, recorded IO replaces declared file inputs without `always: true` and stands in for declared outputs, which conflicts with Cargo's incremental `stat`-only checks, `#[cfg]`/feature branches, `NX_RUST_TEST_MODE=affected` subsets ([[GOAL-TRUSTED-CACHE]]), and Cargo's uncached build directory writes ([[ADR-RESULTS-ONLY-CACHE]]); `warn` still traces unbatched `cargo`/`rustc` process trees and would warn on those `target/` writes. Setting `mode: "off"` keeps declared inputs and outputs authoritative and suppresses IO tracing; a repository that explicitly wants Ultracache tracking can override `ultracache` in `[package.metadata.nx.targets.<name>]`, `project.json` or `targetDefaults`.
867
+ :::
868
+
869
+ :::mara design DES-BUILD-INPUT-CHECK
870
+ :mid: 01M7ACMK1QPYW1JQ7G9ETNAZ7H
871
+ :title: Check a build's dependency files against its inputs
872
+ :status: accepted
873
+ :satisfies: REQ-BUILD-INPUT-CHECK
874
+
875
+ The executor checks a `build` task after every cargo call that builds the task's crate without error, also when cargo compiled nothing because everything was fresh, since a run that skipped the check would cache a success for the same inputs that failed it before. After such a call the records are in place: cargo keeps them, and writes a missing one again without compiling. Whether it also gives them a new time differs between Cargo versions and crates, so the check does not depend on when a record was written ([[EVD-CARGO-DEP-INFO]]). A task is not checked when cargo failed for its crate, nor on an Nx cache hit, which runs nothing. Nor is it checked where the installed Nx lacks the internal parts of Nx through which the check lists the repository's files and matches them with the task's inputs, which only an Nx that the plugin does not support can: the task then prints a warning that the check did not run, and Nx caches its result without it ([[DES-DIAGNOSTICS]], [[REQ-COMPATIBILITY]]).
876
+
877
+ 1. **What it reads.** The records that `cargo build -p <crate>` exports for the call, named by the plugin from what it already knows, without asking cargo. The `build` task selects its crate with `-p` and no target flag ([[DES-TARGETS]]), so cargo builds the crate's library and each binary whose required features are on, and exports one record for each beside its file in the [[TERM-ARTIFACT-DIR]]. From the crate's targets in the `cargo metadata` report, with their kinds and `required-features`, and from the task's feature selection, profile and target triple, the plugin names:
878
+ - `lib<name>.d` for the library, whatever its crate types, with each `-` in the library's name replaced by `_`; and for a library with the crate type `cdylib` built for a wasm triple, whose file is `<name>.wasm`, `<name>.d` in its place, beside `lib<name>.d` where the library has another crate type too, as cargo writes them ([[EVD-WASM-POSTPROCESS]]). The worker of nxr-0ap8n4 corrected this on 16 November 2026, because the name `lib<name>.d` alone names no record of such a `cdylib`, so that the check of a `wasm-build`, or of a `build` for that triple, would read nothing; a graph made before the crate types were recorded names `lib<name>.d` alone;
879
+ - `<name>.d` for each binary whose required features are all features of the crate that the task's selection turns on, directly or through other features of the crate to any depth, as cargo resolves them: a `<dependency>/<feature>` entry for an optional dependency also turns on the crate's feature of the dependency's name, while `dep:<name>` and the weak `<dependency>?/<feature>` turn on none, and an optional dependency that a platform limits is not counted, so that a binary only it would turn on is not named ([[EVD-CARGO-DEP-INFO]]); a binary that requires a feature of a dependency is not named;
880
+ - for a proc macro's library, in `<artifact directory>/<profile folder>` whatever the triple, because cargo builds a proc macro for the host;
881
+ - for every other library and every binary, in `<artifact directory>/<triple>/<profile folder>` for each triple that the call builds for, and in `<artifact directory>/<profile folder>` where it builds for none. The triples are the task's own, or else those that `build.target` in Cargo's configuration and `CARGO_BUILD_TARGET` in the task's environment pick, read as the executor reads them when the task starts ([[DES-OUTPUTS]]).
882
+
883
+ The profile folder is `debug` for `dev` and `test`, `release` for `release` and `bench`, and the profile's own name for any other profile, also one that inherits from one of those four. The plugin passes cargo no flag for this ([[DES-INVOCATION]]) and reads nothing in the build directory ([[DES-BUILD-DIRS]]). What Nx caches as outputs plays no part, so a crate that is only an `rlib` is checked like any other.
884
+
885
+ A record at a name and folder that the rule derives for this call is this call's own. Cargo writes the record of every target that a call builds from that call: it rewrites a record whose content differs and writes a missing one again, also when nothing compiles, so a feature set that changes back restores the matching list ([[EVD-CARGO-DEP-INFO]]). Records that other builds left at other names or folders are never read, because the rule does not derive them: those of another profile, triple or feature set, of a binary whose required features are off or that was removed or renamed, and of the crate before it changed kind, such as a library built for a named triple that has since become a proc macro. In a batch, each group's records are read right after its call, before a later call can rewrite them. With cargo 1.91.0 and 1.100.0, for libraries of the crate types `rlib`, `cdylib`, `staticlib`, all three together and `proc-macro`, a binary alone, a library with a binary, and a proc macro with a binary, under the profiles `dev`, `release`, `test`, `bench` and a custom profile inheriting from each, without a triple, with the host triple and, with 1.100.0, another installed triple named by `--target`, and with `CARGO_BUILD_TARGET`, the names agreed exactly with the records that cargo reported wherever the build succeeded. Where Cargo's configuration chose the triple, names that knew no triple agreed for proc macros' libraries only ([[EVD-CARGO-DEP-INFO]]); the folders that [[DES-OUTPUTS]] names for such a configuration are those that cargo writes to ([[EVD-CARGO-TRIPLE-FOLDERS]]).
886
+
887
+ 2. **Records it cannot name with certainty.** The check reads none of these, so the reads that they record go unchecked:
888
+ - **A triple without a name.** When the task names no triple and Cargo's configuration or the task's environment picks one whose folder [[DES-OUTPUTS]] cannot name, such as `host-tuple`, the call's records can lie in a triple folder, while older records remain in `<artifact directory>/<profile folder>`. A record whose folder depends on the triple, which is every record but a proc macro's library record, is then read there only when no record of the same name lies in any `<artifact directory>/<folder>/<profile folder>`. Because cargo writes a record for every target it builds, the absence of one in a triple folder after the call shows that the call built for no triple. Where one exists, from this call or from an earlier build for another triple, that target is not checked. A proc macro's library record is read as named in this case too, since its folder does not depend on the triple, and that absence would prove nothing for it.
889
+ - **A shared name.** A record name that targets of two crates with the same artifact directory share, as **Files of one name** in [[DES-OUTPUTS]] counts artifact directories as the same, such as two binaries called `cli`, is not read: cargo warns of an output filename collision and keeps a single record, that of the crate it built last. Two binaries of one name share their executable as well, and two libraries of one name can share a `cdylib` or `staticlib` file; a `build` that declares such a shared file runs uncached ([[DES-OUTPUTS]], "Files of one name").
890
+ - **Features turned on by another crate.** When one call builds several crates, another selected crate can turn on a feature that a binary requires. Cargo then builds that binary and exports its record, but the rule knows only the task's own selection and does not name it, so reads that only the binary's own sources make are not checked.
891
+ 3. **What a record holds.** In Makefile syntax, with spaces escaped by a backslash, every path that Cargo would rebuild the target for: the crate's sources, the files that `include_str!` and `include_bytes!` read, the paths that the build script names with `rerun-if-changed`, and the same of the crate's path dependencies, but nothing of a registry crate. A path keeps the spelling it was given, a symbolic link's included, and a directory named with `rerun-if-changed` appears as one path. The paths are absolute, or relative to `build.dep-info-basedir` where that is set. Cargo writes such a relative path normalised as text, each `..` removed with the name before it, so that a path running through a symbolic link and then `..`, such as one that a build script names with `rerun-if-changed`, is recorded as another file than the one read. The check then names that file, and declaring it lets the build pass: the record no longer holds the path that was read.
892
+ 4. **Paths.** Each path is resolved to the file it names: against the folder that `build.dep-info-basedir` gives, with `..` removed, symbolic links followed and, on a file system that ignores case, with the case of the names stored on disk. A path whose file lies outside the repository root is left out: Nx cannot hash it, and [[RISK-HOST-ENVIRONMENT]] covers what it stands for. So is a path whose file lies in the build or artifact directory of the crate's workspace, as cargo reports them for the task, with `cargo metadata --no-deps` in the workspace root and the task's environment, such as code that a build script generates in `OUT_DIR`: a dotenv file that Nx loads only for the task can set `CARGO_BUILD_BUILD_DIR`, which graph creation does not see ([[EVD-NX-24-MOVED-ARTIFACT-DIRS]]). Cargo 1.91 names a file in a build directory apart from the artifact directory, such as one generated in `OUT_DIR`, by its path below the build directory placed below the artifact directory, where nothing need be; Cargo 1.92 names the file itself ([[EVD-CARGO-DEP-INFO]]). Either path lies in one of the two directories and is left out, so the check compares the same files with every supported Cargo. The records are read in that artifact directory too, which is the one the outputs name, since the executor fails a cached `build` before cargo runs where they differ ([[DES-OUTPUTS]]).
893
+ 5. **Directories.** A remaining path that is a directory is enumerated, and the enumeration prunes Cargo's build and artifact directories and everything that Nx ignores, that is what `.gitignore` and `.nxignore` exclude and Nx's fixed exclusions such as `node_modules` and `.git`, without entering them. It does not follow a symbolic link to a folder. Only the files that remain take part in the comparison. A directory such as the one that `rerun-if-changed=../..` names can hold the workspace's `target` folder, so the check never compares Cargo's outputs and never walks the build directory. A task's check lists the repository's files once, when it first enumerates a directory, and every directory it enumerates is taken from that list; the list serves that check alone, which begins after the cargo call it judges, and is not kept for another task or a later call. The list comes from Nx's workspace context, as do the files of the task's inputs in point 6. Nx makes that context in a process on first use and keeps it, also across the groups of a batch, which run in one process, so that a later group's check would miss what its own cargo call wrote ([[EVD-NX-24-WORKSPACE-CONTEXT]]). The executor therefore clears it with Nx's `resetWorkspaceContext` once after a group's cargo calls and before any check of that group, and once before the check of a task run on its own, so that the context the list and the input files are taken from is no older than the group's cargo call. A staged `build` moves its crates' final artifacts and records into the artifact directory right after its cargo call, inside the step, before that reset, so that the context is no older than the move either ([[DES-BATCH]], "Staged builds"). It clears it for a group only where a task whose crate cargo did not fail has this check, so not for the groups of `check`, `lint` or `test`, nor where cargo failed every crate. The checks of one group's tasks run at the same time from one context, so none clears it for itself. Each check makes and initializes its own `HashPlanInspector`, also in a group of several crates, and takes its own list. Measured on 21 November 2026 with Nx 24.0.6, a further inspector cost about 1.5 ms in a repository of about 1,000 files and 16 to 26 ms in one of 30,000, and the list about 0.9 ms and 10 to 16 ms, which the cargo call and the start of Nx outweigh, so a group shares neither ([[EVD-NX-24-WORKSPACE-CONTEXT]]). The reset is one of the internal parts of Nx that the check needs, beside the glob and `HashPlanInspector`: where the installed Nx lacks any of them, nothing is cleared and the check does not run, with the warning above. The list is no older than the cargo call unless another Nx process is walking the repository's files at that moment: Nx then hands the new context that process's walk, which can have listed a folder before cargo wrote into it (nxr-tfha8g). Patterns of `fileInputs`, which become filesets with `includeIgnored` ([[DES-INPUTS]]), are matched against the files on disk and do not depend on the context ([[EVD-NX-24-FILESET-SCOPE]]).
894
+ 6. **Compare.** A file is covered when Nx's own matching of the task's file inputs includes the file's resolved path: the crate's folder, a workspace file, the folder of a crate it depends on or of a path dependency without a project, or a `fileInputs` pattern of the crate, its workspace or a crate it depends on, with the filesets that it gives the project folders below where it starts ([[DES-INPUTS]]). The check thereby fails a build only when Nx's key leaves the file out. A file that a negated pattern in the task's own `inputs` leaves out is not covered either, so a `build` that reads such a file fails instead of being cached ([[DES-PLUGIN-OPTIONS]]). A file that the task's inputs reach only through a symbolic link, because only a pattern for the link matches, is not covered: Nx keeps the hash of a link's destination until the link itself changes or `nx reset` clears the hashes Nx keeps, so that key would miss a change to the file ([[EVD-NX-24-FILE-INPUTS]]). How the comparison treats case on a file system that ignores it is reasoned and not run, because no check runs on macOS yet ([[ADR-CI-LINUX-ONLY]]). Each task is compared with its own inputs, so a file that a shared path dependency reads can be covered for one task of a batch and not for another.
895
+ 7. **Fail.** If a file is not covered, the task fails. The message names the crate and each such file relative to the repository root, and shows the `fileInputs` line for the crate's `[package.metadata.nx]` that would cover them, with each file relative to the crate's folder; for a file reached through a symbolic link, it names the file the link points to and the link. For files found under a directory that the build script names, it names that directory as well, since a pattern for the directory also covers files added there later ([[DES-DIAGNOSTICS]]). A failed task is never stored as a success, so no success is cached under the incomplete key. By default Nx stores no failure either, and the next run builds and checks again. With `NX_CACHE_FAILURES=true`, Nx stores the failure and replays it while the key stays the same; adding the `fileInputs` line changes a manifest that is an input of the task, and with it the key ([[EVD-NX-24-FILE-INPUTS]]). A warning instead would leave a success in the cache under a key known to miss a file ([[ADR-DECLARED-FILE-INPUTS]]).
896
+
897
+ **Batches.** The check runs for each task after the cargo call of its group ([[DES-BATCH]]). A failure fails only the tasks whose records name an uncovered file. The other tasks of the group keep their own results and are cached as usual.
898
+
899
+ **Limits.** Only `cargo build` writes these files. `check`, `lint`, `test` and the workspace's `doc` keep their dependency files in the build directory, whose layout is internal to Cargo, so their reads are not checked: a file that only tests read, through `include_str!` or at run time, relies on its declaration. A file that a proc macro opens without an include macro appears in no dependency file, because Cargo does not track it ([[EVD-CARGO-DEP-INFO]], [[RISK-UNDECLARED-INPUTS]]).
900
+ :::
901
+
902
+ :::mara design DES-OUTPUTS
903
+ :mid: 01M78FHG7FRNE981T1QJYYVWC4
904
+ :title: Cached outputs
905
+ :status: accepted
906
+ :satisfies: REQ-CACHE-OUTPUTS
907
+
908
+ | Target | Cached | Outputs |
909
+ | ---------------------------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
910
+ | `check`, `lint`, `fmt-check`, `test` | Yes | None; the result only |
911
+ | `build` | Yes | Final artifacts only, in the [[TERM-ARTIFACT-DIR]]: the executables of `bin` targets and the `cdylib` and `staticlib` files of a library |
912
+ | `doc`, on the workspace project | Yes | The whole `doc` folder of the workspace's [[TERM-ARTIFACT-DIR]] ([[DES-WORKSPACE-TARGETS]]) |
913
+ | `napi-build` | Yes | The addon's file, `index.js` and `index.d.ts` in the crate's folder, outside Cargo's directories, wherever the [[TERM-ARTIFACT-DIR]] lies ([[DES-NAPI]]) |
914
+ | `wasm-build` | Yes | The folder `pkg` in the crate's folder, outside Cargo's directories, wherever the [[TERM-ARTIFACT-DIR]] lies ([[DES-WASM]]) |
915
+ | `lockfile`, on the workspace project | No | The crates' digests, in `.nx/workspace-data/nx-rust/lockfile/`, declared so that the crate tasks can hash them ([[DES-LOCKFILE-HASHING]]) |
916
+ | `hakari-check`, on the workspace project | No | None ([[DES-UNIFICATION]]) |
917
+ | `fmt`, `bench`, `run`, `audit`, `deny`, `update`, `nx-release-publish` | No | None |
918
+
919
+ `build` does not list `rlib` or `dylib` files or other files that only Cargo consumes, so a cache hit never puts such files back ([[ADR-RESULTS-ONLY-CACHE]]).
920
+
921
+ Nx can store only files inside the repository. The `cargo metadata` report names the artifact directory of each workspace, as cargo's configuration or `CARGO_TARGET_DIR` spells it, and cargo writes to the folder that the system reaches through that path ([[EVD-CARGO-DIRECTORIES]]). Where a symbolic link comes before a `..`, that is not the folder that the path names as text. The plugin therefore follows every symbolic link of the path, also one to a folder that does not exist yet, and takes the folder it reaches, relative to the repository's real path: that folder decides whether the directory lies inside the repository, whatever the reported path says, and the outputs and the plugin's warnings name it. When it lies outside the repository, the `build` and `doc` targets of that workspace are not cached, and the plugin says so when the graph is created ([[DES-DIAGNOSTICS]]). Targets that store only a result stay cached, and so do the artifact targets, whose outputs lie outside Cargo's directories ([[DES-ARTIFACT-STEPS]]).
922
+
923
+ When the reports of two or more workspaces name the same artifact directory, or one that lies inside another's, the `doc` targets of those workspaces are not cached either, and the plugin says so in the same way. Nx restores a folder output by replacing it, so restoring one workspace's `doc` folder would delete the pages of the others ([[EVD-NX-24-TARGETS]]), and the `doc` folder of a triple in one directory can be the `doc` folder of another directory that is that triple's folder. Cargo reports the directory as its configuration or `CARGO_TARGET_DIR` spells it, `..` segments, symbolic links and a trailing separator included ([[EVD-CARGO-DIRECTORIES]]). Two reports therefore name the same directory where their paths agree once `.` and `..` are taken as text, or once every symbolic link is followed as well, a link to a folder that does not exist yet included, also where the names differ only in case or in Unicode normalisation; and one lies inside the other where one such path continues the other. Either agreement counts: two folders taken for one only cost `doc` its caching, while one folder taken for two lets a restore delete pages. The workspaces compared are those of every entry of the plugin in `nx.json`. With several entries, each entry also reads the workspaces that the others receive and it does not, applying every entry's `include` and `exclude` to the `Cargo.toml` files of Nx's workspace context as Nx does ([[EVD-NX-24-ENTRY-CONTEXT]]), so that every entry compares the same workspaces and reaches the same verdict, whatever the order in which Nx runs them. The entries of one process share their reports; under plugin isolation each entry requests one more `cargo metadata --no-deps` for each workspace of the others, and a workspace whose report fails is left to the entry that receives it, which fails graph creation ([[EVD-CARGO-ARTIFACT-WRITERS]]). Sharing that begins through a configuration file outside the repository, which the Nx daemon does not watch, is seen only when Nx creates the graph again. Until then the other workspace's cached tasks fail with the `nx reset` message, its artifact directory being no longer the one that its outputs name, but a restored `doc` of the first workspace can replace pages that cargo wrote into the shared `doc` folder for the other; no task result is wrong, and once the graph is created again `doc` is uncached for both.
924
+
925
+ **Nested artifact directories.** Where one workspace's artifact directory lies inside another's and the outer one does not exist yet, as on a first build, in a fresh checkout or after `cargo clean`, two cargo commands of those workspaces that run at once can fail in cargo itself, before either takes its build lock: the inner command creates the outer directory as a plain folder, the parent of its own, and the outer command renames its new directory onto that still empty folder, so that the inner command fails with "No such file or directory" ([[EVD-CARGO-NESTED-DIRECTORY-CREATION]]). Plain cargo fails in the same way. A second run, which finds the directories, builds, and the failed task stores nothing. Workspaces with the same artifact directory are not exposed, because a folder that cargo renames into place is never empty. The maintainer decided on 15 November 2026 that the plugin says so and does nothing else: the warning about directories that lie one inside the other, inside the repository or outside it, adds that a first build, while these directories do not exist yet, can fail in cargo with "No such file or directory", and to run the command again, and the caching guide adds `--parallel=1` for a first run, as in CI; the warning about one shared directory does not ([[DES-DIAGNOSTICS]]). For a directory outside the repository, whose warning otherwise says only that Nx cannot store its files, the warning names the directory that it lies inside or holds. A directory inside the repository can lie inside one outside it only where that one holds the repository, and never holds one outside it. Such a setup is rare, the failure is a defect of cargo's own that a rerun gets past, and no cache result is wrong, since the task fails. Creating the directories before cargo runs was not chosen, because the plugin does not create cargo's folders. Keeping such commands from running at once was not chosen, because `parallelism: false` on every cargo target of those workspaces would slow every run of them, and the plugin adds no lock of its own for this. Refusing the configuration was not chosen, because cargo builds such workspaces and the plugin must not make a valid Cargo configuration unusable ([[REQ-CARGO-UNCHANGED]]).
926
+
927
+ **Paths.** Nx interpolates outputs from a task's options ([[EVD-NX-24-INPUTS-OUTPUTS]]). A run whose `targetTriple` option names a triple passes it as `--target`, which replaces what Cargo's configuration and environment pick. Without it, cargo builds for the triples that `build.target` in its configuration and `CARGO_BUILD_TARGET` pick, into each triple's folder, also for the host's own triple, and for no triple into the artifact directory itself ([[EVD-CARGO-TRIPLE-FOLDERS]], [[ADR-TRIPLE-OUTPUTS]]). Cargo reports these triples nowhere, so the plugin reads them when it creates the graph, as cargo does for a command started in the workspace root:
928
+
929
+ - `build.target` in the configuration files of the workspace root, of each folder above it and of the Cargo home, with the files they include, and of `.cargo/config` and `.cargo/config.toml` in one folder the former, as cargo reads them. A string in a deeper folder wins over one above it, a file's own value over the files it includes, and a later include over an earlier one. A file of that walk counts in its own place also where a deeper file includes it, as Cargo 1.91 reads it only there ([[EVD-CARGO-COMPILER-SELECTION]]). Lists from several files are joined, and cargo refuses a string beside a list, in `cargo metadata` too, so that graph creation fails.
930
+ - `CARGO_BUILD_TARGET` in the environment of graph creation: that of the `nx` command, with the repository's root `.env`, `.local.env` and `.env.local`, which Nx hands to the daemon as well ([[EVD-NX-24-SETUP]], [[EVD-CARGO-TRIPLE-FOLDERS]]). It replaces a string, or the absence of one, with one triple, its whole value, and adds its words to a list.
931
+
932
+ `build` names its files in `<artifact directory>/{options.targetTriple ?? <triple>}/{options.profile ?? debug}` for each picked triple, and in `<artifact directory>/{options.targetTriple ?? .}/{options.profile ?? debug}` where none is picked; `doc` names the `doc` folder in the same folders up to the triple. Nx counts equal outputs once, so a run that names a triple stores that triple's folder once. For an empty list, cargo builds nothing, and the outputs name `{options.targetTriple}` without a fallback, which Nx drops where the run names no triple. A library's `cdylib` and `staticlib` files are named for Linux and for macOS, and Nx stores the ones that exist. Nx stores every declared file that exists when the task ends, whoever wrote it, and a binary with `required-features` is declared also where the task does not turn them on, so that a file that an earlier build with those features, or plain `cargo build --features`, left at that path is stored in this task's entry and restored with it; this is a known limit (nxr-m1tfp3). Every other target declares an empty list of outputs, because Nx gives a target called `build` without outputs folders of its own. `build` and `doc` reject the profiles `dev`, `test` and `bench`, whose folders Cargo calls `debug`, `debug` and `release`: the executor fails such a task before cargo runs, and its message names the profile to use instead, none for `dev` and `test` and `release` for `bench`.
933
+
934
+ **Triples that cannot be named.** Nothing is cached where the plugin cannot name these folders. It cannot name the folder of `host-tuple`, which cargo replaces with the host's triple, of a target specification file, of an empty triple or of a value that is no triple name, nor the folders of a `build.target` that a file added by `include` sets where reading and ignoring that file pick different triples: Cargo 1.91 ignores `include`, and later versions apply it. Where Cargo's configuration or the graph's environment picks such a value, `build` and `doc` are inferred uncached unless their own options name a triple and no configuration of theirs clears it: Nx's `cache` belongs to the target, not to a configuration, so a triple that only a configuration names does not count. Their outputs then name `{options.targetTriple}` without a fallback. The plugin says so when the graph is created, naming the value, what picks it and the `targetTriple` option ([[DES-DIAGNOSTICS]]), and the executor fails a cached run that names no triple before cargo runs.
935
+
936
+ **Option values that cannot be named.** The outputs interpolate the `targetTriple` option as the triple's folder, but cargo writes elsewhere for two values that it accepts: it replaces `host-tuple` with the host's triple, and names the folder of a target specification file, any value that ends in `.json`, after the file ([[EVD-CARGO-TRIPLE-FOLDERS]]). The option arrives with the task, when Nx has decided to cache it already, so the executor fails a cached `build` or `doc` with such an option before cargo runs ([[ADR-TRIPLE-OUTPUTS]]). The message names the option and its value, says that the plugin cannot name the folder that cargo writes to for it, and says what to do: pass the host's triple, which it names as `rustc -vV` gives it in the workspace root, in place of `host-tuple`; for a specification file, build with a built-in triple or turn caching off for the target ([[DES-DIAGNOSTICS]]). A run of an uncached target passes the value to cargo. Cargo fails on the other values that the plugin cannot name, so that Nx stores nothing for them, or with `NX_CACHE_FAILURES=true` only the failure (**Failed tasks**, below).
937
+
938
+ **Triples that only a task picks.** Outputs are fixed when the graph is created, and an output reads no environment variable ([[EVD-CARGO-TRIPLE-FOLDERS]]). A `CARGO_BUILD_TARGET` that only a dotenv file of the task sets, such as a `.env` in the crate's folder or a root `.env.build`, is unknown then. So is a change to a configuration file that the Nx daemon does not watch, such as the Cargo home's or one above the repository: the daemon keeps the graph, and with it the outputs, that it created before. A cached `build` or `doc` therefore has a runtime input that prints the triples that cargo will use when the task runs ([[DES-INPUTS]]), so that its key follows them whatever the graph holds, and a result stored for one triple is not restored for another, apart from a change made while a command is running (**Keys**, below). When such a task whose run names no triple starts, the executor reads the triples again, from the task's environment and the configuration files as they are then, with the same function, and fails the task before cargo runs where they differ from those its outputs name or cannot be named. Where the configuration alone now picks other triples than at graph creation, the graph is out of date, and the message says that the configuration changed after Nx created the project graph and to run `nx reset`, or stop the daemon, and run the task again; otherwise it names the triples, what picks them and the `targetTriple` option ([[DES-DIAGNOSTICS]]). Nx stores nothing for the failed task, or with `NX_CACHE_FAILURES=true` only the failure (**Failed tasks**, below).
939
+
940
+ **An artifact directory that moves after graph creation.** The outputs name the artifact directory of the report that graph creation receives, with the environment of the `nx` command and the repository's root `.env`, `.local.env` and `.env.local`. Two things can move it afterwards ([[EVD-NX-24-MOVED-ARTIFACT-DIRS]]): a change to a configuration file that the Nx daemon does not watch, such as the Cargo home's or one above the repository, which leaves the daemon's graph and its outputs as they were; and a dotenv file that Nx loads only for the task, such as a `.env` in the crate's or the workspace's folder or a root `.env.build`, `.env.doc` or `.env.<configuration>`, that sets `CARGO_TARGET_DIR`, `CARGO_BUILD_TARGET_DIR` or `CARGO_HOME`. Cargo then writes elsewhere, and Nx would store under the task's key whatever lies at the declared paths, an older artifact or nothing, and restore it later. So the runtime input of a cached `build` and `doc` also prints the artifact directory that cargo will use ([[DES-INPUTS]]), and when such a task starts, the executor asks cargo for its directories with `cargo metadata --no-deps` in the workspace root and the task's environment, and fails the task before cargo builds where the artifact directory, as the system reaches it, is not the one that the outputs name ([[ADR-ARTIFACT-DIR-OUTPUTS]]). Tasks run as a group share their workspace and environment, so the executor asks once for the group ([[DES-BATCH]]). Asking cargo covers every source that it reads, an `include` as each version reads it and a Cargo home that only the task's environment names among them. Graph creation records the artifact directory and the values of those three variables in the metadata of `build` and `doc`. Where the task's environment gives the variables the values that graph creation saw, or those values would give another directory as well, Cargo's configuration has changed, and the message says so and to run `nx reset`, or stop the daemon, and run the task again; otherwise it names both folders and the variables, and says to set them in the environment of the `nx` command or in the root `.env`, or to set the folder as `build.target-dir` in a `.cargo/config.toml` of the workspace ([[DES-DIAGNOSTICS]]). Nx stores nothing for the failed task, or with `NX_CACHE_FAILURES=true` only the failure (**Failed tasks**, below). The plugin does not read a task's dotenv files when it creates the graph, so a folder that only they name is never cached.
941
+
942
+ **Keys.** The triples reach the key whichever way they are picked: the option as an option, and the triples that cargo will use as the output of the runtime input, which also covers `CARGO_BUILD_TARGET`, an `env` input of its own, and configuration files outside the repository, which no file input covers ([[DES-INPUTS]]). The picked triples are also text in the outputs, which Nx hashes with the project's configuration ([[EVD-CARGO-TRIPLE-FOLDERS]]). So is the artifact directory, which the same runtime input prints as well, as the outputs name it: relative to the repository's real path, so that checkouts in other folders share keys, and without a path where it lies outside the repository, where the executor fails the task. The executor's check compares what cargo picks when the task starts with what the graph's outputs name, not with what the runtime input printed when Nx computed the key. A stored result therefore holds the folders that its key names wherever Cargo's configuration and the task's environment stay the same from the computing of the task's key to the start of the task. A change made while a command is running, between those two moments, is outside what the check sees, as it is for every input of a key, such as a source file edited during a run: a configuration that moves to another folder and back can then store the artifacts of one folder under the key of the other ([[EVD-NX-24-MOVED-ARTIFACT-DIRS]]).
943
+
944
+ **Who writes the artifact directory.** Besides `cargo build`, `cargo test` writes the executables that `build` declares, in the crates whose `test` waits for their `build` ([[DES-TARGETS]]): it builds the crate's binaries for its integration tests, also for one with `test = false` that the `test` option selects ([[DES-TEST-RUN]], "One test target"), and for the benches it runs, with what dev-dependencies turn on and with the `test` profile, and replaces the uplifted files even when nothing compiles; its tests run that file as `CARGO_BIN_EXE_<name>` after cargo has released its build lock. `cargo bench` does the same in the folder of the bench profile. No other command of the plugin's targets writes them: `check`, `clippy` and `doc` leave them alone, `cdylib` and `staticlib` files are uplifted only for the crate that a command builds, only `doc` writes the `doc` folder, and `cargo run` writes the bytes of `build` where its options are those of `build` ([[EVD-CARGO-ARTIFACT-WRITERS]]). A `build` writes only its own crates' files: one that selects the whole workspace, which would link every member's, builds in a stage and moves only its own crates' files into the artifact directory, by rename and to the paths that the outputs name, and the compile of `napi-build` and `wasm-build` builds in a stage and moves none ([[DES-BATCH]], "Staged builds"; [[ADR-STAGED-BUILDS]]). Nx stores a task's outputs after its process has ended, and a batch's when the batch has ended ([[EVD-NX-24-BATCHES]]), so a `cargo test` beside a `build` could put its executable under the key of `build`, and a `build` beside a running test could replace the executable that the test runs. `test` therefore waits for the crate's own `build`, Nx stores `build` before `test` starts, and the tests run the executable that their own cargo call built; in a batch, `build` and `doc` run apart from the tasks that wait for them ([[DES-BATCH]]). `bench` runs alone ([[DES-TARGET-COMMANDS]]). A `test` or `bench` batch puts back the files of the command's builds when it ends, so that after a batched command that ran both, or restored `build` and ran `test`, the artifact directory holds what `build` stored ([[DES-BATCH]], "Files that a test batch puts back"); with tasks run on their own, it holds the executables of `cargo test`, as plain `cargo build && cargo test` leaves them, until the next `build`, run or restored, puts its own back. The entry of `build` stays right either way. `run` with other options than `build` and two `nx` commands at once remain ([[RISK-ARTIFACT-DIR-WRITERS]]); two crates whose files have one name are the subject of the next paragraph.
945
+
946
+ **Files of one name.** Cargo names a final artifact after its target, not its crate: the executable of a binary after the binary, and the file of a library `lib<name>`, each `-` of the library's name as `_`, with `.so` on Linux and `.dylib` on macOS for a `cdylib`, a `dylib` and a proc macro, and `.a` for a `staticlib`. Where two crates give a file one name, in one workspace or in workspaces whose artifact directories are the same or lie one inside the other, as `doc` counts them above, also through a third and also where separate entries of the plugin receive them, cargo writes one file in every folder that both build into, that of the crate it wrote last, also where that crate's unit was fresh, and warns of an output filename collision only where one call builds both ([[EVD-CARGO-ARTIFACT-WRITERS]]). A `build` of either crate could then store the other's file under its key. Graph creation therefore compares these names among all members of those workspaces, those without a project too, and takes two names for one where they differ only in case or in Unicode normalisation, as macOS's default file system does, on every host, so that Linux and macOS get one graph. Triples and profiles play no part. Every file that `build` declares lies one or two folder names, a triple's and a profile's, below its artifact directory, so the files of two different directories can lie at one path only where one directory lies inside the other; and the outputs interpolate the task's `targetTriple` and `profile` options, which a target table, a `project.json`, a configuration or the command line can give, so that runs of two crates of such directories can always build into one folder. The rule therefore depends on no option: a triple that only the command line names, which the check of **Triples that only a task picks** does not fail, since that check concerns runs that name no triple, cannot make two crates' files meet where the rule does not already leave their `build` uncached. Two targets of one crate count for nothing: one cargo command writes both, and a restore puts back what it left.
947
+
948
+ Where such a file is one that a crate's `build` declares, the executable of a binary or the file of a `cdylib` or `staticlib`, that `build` is not cached, whatever its other files: one cargo command writes them all, and outputs that left the shared file out would let a cache hit miss a file that the task writes. Where the file is the executable of a binary and `cargo test` builds the crate's binaries ([[DES-TARGETS]]), the crate's `test` is not cached either: its tests run that file as `CARGO_BIN_EXE_<name>`, which another crate's command can replace before they do, so that their result is not decided by the task's inputs. The dependency of `test` on `build` stays. The crate's other targets stay cached, and so does the `build` of a crate whose file of that name its `build` does not declare: a `dylib`, which cargo also copies there where it builds the library as another crate's dependency, or a proc macro, which it copies there for the crate that a command selects. Graph creation does not fail, because cargo builds such a workspace ([[REQ-CARGO-UNCHANGED]]), and an uncached task stores nothing ([[GOAL-TRUSTED-CACHE]]). It gives the crates concerned one warning per shared name, which names the crates, the file, the artifact directories and the targets that run uncached, and says to rename one binary or library or, where the crates belong to several workspaces, to give each workspace an artifact directory of its own, none inside another, after which they are cached again; the entry that holds the workspace of the first crate it names prints it ([[DES-DIAGNOSTICS]]). `cargo doc` refuses a workspace whose binaries have one name, with a document output filename collision, so the workspace's `doc` target fails as plain `cargo doc` does, until one of the binaries gets another name or `doc = false` ([[EVD-CARGO-ARTIFACT-WRITERS]]). Not compared are crates that no `cargo metadata --no-deps` report names, such as a registry crate whose `dylib` cargo copies into the artifact directory as a member's dependency ([[RISK-ARTIFACT-DIR-WRITERS]]).
949
+
950
+ **Two mechanisms.** Graph creation compares the workspaces of every entry of the installation of the plugin that runs it, the entries it takes for its own being those that name its package or a path to its entry point. What it cannot see, such as the projects that another installation of the plugin creates for an entry under another name, a check covers when a task starts. Before cargo runs, the executor of a cached `build`, `doc`, or `test` that waits for its `build`, looks at the whole project graph that Nx hands it. Where a target of another project, whichever installation created it, has an artifact directory that is the task's own or lies inside it or holds it, and writes a file of a name that the task declares, or for `doc` is another `doc` target, the task fails, naming both targets and the file, and saying to rename one binary or library or to register both workspaces through one installation of the plugin, which then leaves them uncached ([[DES-DIAGNOSTICS]]). For a `test`, the files are its crate's executables. The check reads each target's artifact directory relative to the repository's real path, which the metadata of `build` and `doc` records where it lies inside the repository, and the files that the metadata of every crate's `build` records, cached or not, or the binaries of its build records in a graph from an older version of the plugin. It compares them as graph creation does, and graph creation leaves uncached every pair among the projects it sees, so the check never fails a task of a repository without such a pair, and a task that graph creation left uncached does not run it. A failed task stores nothing, and graph creation still never fails for this. On the largest fixture the check takes about 3 µs a task ([[EVD-CARGO-ARTIFACT-WRITERS]]).
951
+
952
+ **Per project.** Each inferred target carries in its metadata, under `cargo.uncached`, why the plugin leaves it uncached in its project, for every target that it does not cache: by design, for one of the reasons above, or because a `targets.<name>` table of the crate's or the workspace's Cargo metadata sets `cache = false` on a target that the plugin would cache, which the reason names with the table's header and its manifest ([[DES-METADATA-TABLES]]). A `targetDefaults` entry that caches such a target fails graph creation ([[DES-TARGET-DEFAULT-GUARD]]), and the executor fails a task whose configuration caches it anyway, such as through a `project.json`, before cargo runs, so that Nx stores nothing for it, or with `NX_CACHE_FAILURES=true` only the failure (**Failed tasks**, below).
953
+
954
+ **Failed tasks.** By default Nx stores nothing for a task that fails, whether cargo fails it or the executor does, before or after cargo runs. With `NX_CACHE_FAILURES=true`, Nx stores the failure and replays it, as a failure, for the same key. In neither case does Nx store or restore a successful result for the task ([[ADR-CACHED-FAILURES]]).
955
+ :::
956
+
957
+ :::mara design DES-BUILD-DIRS
958
+ :mid: 01M78FHG7FMKCDSEX3Y6Q65F4Y
959
+ :title: Build and artifact directories
960
+ :status: accepted
961
+ :satisfies: REQ-CACHE-OUTPUTS
962
+ :satisfies: REQ-CARGO-UNCHANGED
963
+
964
+ Cargo 1.91 and later can keep intermediate files in a [[TERM-BUILD-DIR]] (`build.build-dir`) apart from final artifacts in the [[TERM-ARTIFACT-DIR]] (`build.target-dir`). The plugin relies on that split:
965
+
966
+ - Of Cargo's two directories, Nx outputs point only into the artifact directory.
967
+ - The recommended build directory sits outside the repository. CI caches it; Nx never does, wherever it lies.
968
+ - The plugin never references a path inside the build directory, because that layout is internal to Cargo and changed in Cargo 1.100.
969
+ - By default the plugin does not set either directory for its own commands. It uses what Cargo's configuration says, so plain cargo and rust-analyzer share both directories with it. There are two exceptions. One is the opt-in separate build directory for coverage builds ([[DES-BASELINE]]). The other is a `build` that selects the whole workspace and the compile of `napi-build` and `wasm-build`: they give cargo the build directory that its configuration names and, as artifact directory, a stage inside the configured artifact directory, and a `build` then moves its own crates' final artifacts into the configured artifact directory ([[DES-BATCH]], "Staged builds"; [[ADR-STAGED-BUILDS]]).
970
+
971
+ The split does not remove lock contention: there is one lock per build directory. Running tasks as few cargo invocations as possible is [[DES-BATCH]].
972
+ :::
973
+
974
+ :::mara design DES-INVOCATION
975
+ :mid: 01M78NVF8ETK5PJ64FK45AEDFB
976
+ :title: How the plugin invokes cargo
977
+ :status: accepted
978
+ :satisfies: REQ-CARGO-UNCHANGED
979
+ :satisfies: REQ-NO-MANIFEST-WRITES
980
+ :satisfies: REQ-VERBOSE-COMMAND
981
+
982
+ Every cargo command of a task starts in the root folder of the crate's workspace and selects its crates as **Selecting a crate** says. rustup and Cargo choose the toolchain file and the configuration files by the folder a command starts in and its parents, so the same toolchain and configuration files apply to all tasks of a workspace, which a single invocation for a group needs ([[DES-BATCH]]). A task's environment can still choose another toolchain, for example through `RUSTUP_TOOLCHAIN` in a crate's `.env`: the task then runs and is keyed with that toolchain ([[DES-INPUTS]]) and shares no cargo call with tasks whose environment differs. A `rust-toolchain.toml` or `.cargo/config.toml` inside a member crate applies only to a cargo that the user starts in that folder, not to the plugin's commands ([[ADR-WORKSPACE-ROOT]]).
983
+
984
+ **Selecting a crate.** A command selects each of its crates with `-p` and the crate's package ID specification as cargo reports it, the form that `cargo pkgid` prints for the crate's manifest: `path+file://<the crate's folder>#<version>`, with `<package name>@` before the version where the folder's name is not the package name, such as `path+file:///home/me/repo/rust/crates/core#core-lib@0.1.0`. Cargo keeps the package names of a workspace's members distinct, but it matches `-p <name>` against every package that the selected crates reach. The name is therefore ambiguous where one of them depends on another package of that name, from a path outside the workspace, a registry or git, and `<name>@<version>` is ambiguous where that package has the same version too ([[EVD-CARGO-PACKAGE-SPECS]]). The plugin reads the workspace without its dependencies ([[ADR-METADATA-NO-DEPS]]) and cannot tell where that happens, so it selects every crate in this form, also where the name would do, and a command for several crates selects each of them so. The form selects the same package as an unambiguous name, so the command builds what `-p <name>` builds.
985
+
986
+ Before its command, a task asks cargo for the specifications with `cargo metadata --format-version 1 --no-deps`, started in the workspace root with the task's environment and without `--manifest-path`, as the command starts, and takes the `id` of the member with the crate's package name, which is its specification. The specification holds the path through which cargo reached the workspace, which depends on the folder that cargo starts in: one asked through a symbolic link matches no package in the folder it leads to. `cargo pkgid` would need a `Cargo.lock`, and `cargo metadata --no-deps` neither needs nor writes one. Where cargo cannot give the report, the task fails before its command with cargo's message, and where the report has no member of that name, with a message that the project graph is out of date ([[DES-DIAGNOSTICS]]). `cargo fmt` takes package names only and matches them against the members alone, so `fmt` and `fmt-check` select the crate by its name ([[DES-TARGET-COMMANDS]]).
987
+
988
+ The specification holds the absolute path of the crate's folder. The task computes it when it runs and passes it to cargo only: no project graph, option, input or output holds it, so it reaches no cache key, and checkouts in different folders keep the same keys. What cargo prints still names the crate by its package name, the hints for running a failed test again included, such as `` `-p good --lib` ``, which cannot be pasted where the name is ambiguous ([[EVD-CARGO-PACKAGE-SPECS]]). The command that the task ran is printed in a verbose run only (**Printing the command**).
989
+
990
+ **Printing the command.** A task prints its cargo command only when Nx runs verbosely, and then for each cargo command that does the task's work, right before it starts and after every warning of the task ([[REQ-VERBOSE-COMMAND]], [[ADR-VERBOSE-COMMAND]]). Verbose means what it means to Nx: `--verbose` on `nx run`, `nx run-many` or `nx affected`, or `NX_VERBOSE_LOGGING=true` without the flag, where `--verbose=false` wins over the variable. A single task takes it from `isVerbose` in its executor's context alone (`taskRunsVerbosely` in `nx-rust/src/executors/cargo-invocation.ts`), never from its environment: Nx deletes from a task's environment each variable whose value a root `.env` file repeats and then loads the task's own dotenv files, so a crate's `.env` can give the task an `NX_VERBOSE_LOGGING` that differs from the run's. A batch implementation, whose context always says `isVerbose: false`, calls another function, `batchRunsVerbosely`, with its own process's environment: Nx copies that from the `nx` process after the flag has set `NX_VERBOSE_LOGGING` there, and loads no task's dotenv file into it ([[EVD-NX-24-VERBOSE]]). Neither reads a variable from a task's environment that the batch rebuilds, so a variable that only a task's dotenv file sets counts for no task, as it counts for nothing in Nx. Three lines go to the task's standard error. The first names the task: `<project>:<target>: @convesoft/nx-rust runs cargo as these lines do in a POSIX shell:`. The second, indented by two spaces as the third, is `cd` and the folder where cargo starts; a staged command's stage and build directory are among its arguments. The third is the command: `NAME=value` for each environment variable that the plugin sets for the command over the task's environment, which no command of this version does, then `cargo` and its arguments exactly as passed. A word that holds only letters, digits and `_ - . / : @ % + , =`, and does not start with `=`, which zsh expands, stays as it is; every other word is put in single quotes, a single quote written `'\''`. So a specification is quoted for its `#`, a folder for a space, and `%20` in a specification stays as it is, and the two lines run the same command where they are pasted into sh, bash or zsh. The lines are built from the same invocation that cargo is started with, in one place (`commandBlock` in `nx-rust/src/executors/cargo-invocation.ts`), so that they cannot differ from what runs.
991
+
992
+ The task's own environment is not printed, neither what the `nx` command inherits nor what Nx loads for the task from dotenv files: the plugin passes it on unchanged, apart from the few variables by which Nx tells a task how it runs and records it, which it leaves out for a task run on its own as in a batch ([[DES-BATCH]]), and it can hold secrets. A value that the plugin sets is its own choice, holds no secret and is printed in full. To reproduce a task whose dotenv files set a variable, such as a crate's `.env`, the user sets that variable as well. The lookups that a task makes before its command are not printed: the `cargo metadata` reports for the specification and for Cargo's directories, and the checks for a tool. They read and change nothing, a failure of one fails the task with a message that names it ([[DES-DIAGNOSTICS]]), and their lines would come before the command that a user reproduces. The lockfile task's `cargo update --workspace` is that task's own command, which it prints under its own name. In a batch, one cargo command serves several tasks: the batch process prints its lines itself, once per command and before it starts, with a first line that names the tasks of the command, through the same function that prints a task's lines (`printCommand` in `nx-rust/src/executors/cargo-invocation.ts`). They then belong to no task's terminal output, so that Nx stores them with no task's result and replays them on no hit, as a run that restores the batch's tasks shows; in the output styles that print task output they appear where the batch process writes them, for a batch of one task below a line `> nx run <task>` of their own, and Nx keeps the batch's own log, which holds them, in the cache folder's `batchOutputs` only where a style that does not print it, such as `summary` or the terminal UI, ran a batch in which a task failed (`announceBatchWorkerLog` in `tasks-runner/task-orchestrator.js` of Nx 24.0.6, read, not run; [[EVD-NX-24-BATCHES]]).
993
+
994
+ Nx stores a task's terminal output with its result and replays it on a cache hit, and Nx 24.0.6 gives an executor no way to the terminal that it does not store ([[EVD-NX-24-VERBOSE]]). A verbose run of a single task therefore stores the lines with the result, and a later hit, verbose or not, also on another machine that shares the cache, shows them with the folders of the run that stored the result, as it shows cargo's own lines, which name the crates' folders too ([[ADR-VERBOSE-COMMAND]]). A hit shows no lines where the run that stored the result was not verbose, because no cargo runs. `--skip-nx-cache --verbose` shows the command of a task whose result is stored, and Nx stores nothing of such a run ([[EVD-NX-24-WARNING-CHANNELS]]). Verbose mode is no input of any key: Nx hashes neither the flag nor the variable into the plugin's tasks, and the plugin declares neither as an input ([[EVD-NX-24-VERBOSE]]).
995
+
996
+ The plugin adds no flag that changes what Cargo builds, and passes only what the target's options ask for. It sets no build or artifact directory ([[DES-BUILD-DIRS]]), with one exception that the maintainer decided on 20 November 2026 ([[ADR-STAGED-BUILDS]]). A `build` that selects the whole workspace and the compile of `napi-build` and `wasm-build` pass `--target-dir` with their stage and `--config 'build.build-dir="<build directory>"'` with the build directory that cargo would use anyway, after the target's own arguments, and take both from the report of Cargo's directories that they ask for before the command ([[DES-BATCH]], "Staged builds"). The two flags change where cargo links the final artifacts, not what it builds or reuses, and a verbose run prints them with the rest of the command; the moving of files that follows is the plugin's and is not printed.
997
+
998
+ By default the plugin does not pass `--locked`. Cargo may then create or update `Cargo.lock` during a task, exactly as it does for the same plain cargo command. That is Cargo's write, not the plugin's. The lockfile task makes that write with `cargo update --workspace` before the crate tasks run, byte for byte as their own cargo commands would, also in a run where every crate task is then restored from the cache; it too is Cargo's write ([[DES-LOCKFILE-HASHING]]). With the `locked` option on, every cargo command of a task passes `--locked` and fails instead of changing the lockfile. Two kinds of command never pass the flag: `update`, whose purpose is to change the lockfile and which `--locked` fails whenever the lockfile would change, and the `cargo fmt` of `fmt` and `fmt-check`, which resolves no dependencies and rejects `--locked`. The `cargo update --workspace` of the lockfile task does pass it, and then only checks the lockfile. cargo-deny takes `--locked` like a cargo command, and cargo-audit only reads the lockfile ([[DES-WORKSPACE-TARGETS]]). Creating the graph never touches `Cargo.lock`, with or without the option, because its report is requested with `--no-deps` ([[DES-METADATA-REPORT]]). The environment variable `NX_RUST_LOCKED`, set to `true` or `false`, replaces the option for one run, which is how a pipeline switches it on without changing what developers get. Locked mode is no input of a task's key, so it guards only the tasks that run. Every run in which the lockfile task runs fails on an outdated lockfile, even when every crate task is then restored from the cache ([[DES-LOCKFILE-HASHING]]). A run of `fmt` or `fmt-check` alone, or one that excludes task dependencies, runs no lockfile task and does not check it. A pipeline that is to check the lockfile in such a run, or in one without Rust tasks, runs `cargo metadata --format-version 1 --locked` in each workspace root as a command of its own, outside Nx's cache, which fails on such a lockfile without changing it ([[EVD-CARGO-LOCKED-CHECK]]).
999
+ :::