docs: resolve the cargo target dir in rust build steps

[marc0olo]

Follow-up after reviewing #760.

Rust build steps that hardcode target/... compile successfully and then fail to find the wasm, because cargo does not necessarily write to ./target.

The dominant case is not an exotic env var. A build step runs in the canister directory (crates/icp/src/operations/build.rs:62 passes canister_path), so in the standard Rust monorepo layout the path is simply wrong:

repo/
├── Cargo.toml          # workspace root — cargo writes target/ HERE
├── target/
└── canisters/backend/
    ├── Cargo.toml      # workspace member
    └── icp.yaml        # build step runs HERE, so "target/" → canisters/backend/target → missing

CARGO_TARGET_DIR and build.target-dir move it too. Reproduced against examples/icp-rust:

mv: rename target/wasm32-unknown-unknown/release/icp_template_rust.wasm to …: No such file or directory

The official rust recipe fixed this in rust-v3.1.0. This applies the same lookup wherever we still hardcode the path, and bumps our pins.

Changes

• All rust build snippets in docs/ resolve the target dir via cargo metadata, in a |- block so the lookup and the copy read as two lines.
• examples/icp-rust, examples/icp-sync-plugin likewise. Both examples are flat, so this is defensive for them as-run — it matters because they are templates people copy into projects that are not flat.
• scripts/validate-examples.sh no longer assumes ./target/debug. This one was a live bug in our own tooling.
• Every @dfinity/rust pin bumped v3.0.0 → v3.4.0, in both the type: and release-URL forms. v3.0.0 predates the recipe's own fix.
• docs/guides/creating-recipes.md gains a short section explaining the rule and the |- block form.
• package is documented as optional, which the bump exposed: examples/icp-rust-recipe called it a required field in both its manifest comment and its README, but it has defaulted to the canister name since rust-v3.3.0. Dropped from the five snippets where it only repeated the canister name; kept where the crate name genuinely differs, and in the custom-recipe examples whose own package parameter is unrelated.

Notes for the reviewer

• The lookup and the copy are one commands: entry, written as a |- block. They must share a shell — each entry gets its own sh -c, so a naive split leaves $TARGET_DIR empty and fails with cp: /wasm32-unknown-unknown/…: No such file or directory — but they do not have to share a line.
• cp, not mv, matching the recipe: cargo materializes the top-level artifact from deps/, so a build step has no reason to remove its output. (It does not cause a rebuild either way — cargo re-creates the top-level file in ~0.03s.)
• The sed is inherited from the recipe, which avoids jq "in order not to introduce a dependency on jq". There is no better form on stable: --artifact-dir would remove the lookup entirely but is nightly-only (cargo#6790, open since 2019), cargo locate-project --workspace misses CARGO_TARGET_DIR, and tr/cut variants break on paths containing a comma.
• Only validate-examples.sh guards against an unresolved lookup, because an empty result there was genuinely silent — it prepended /debug to PATH and surfaced later as icp: not found. A build step needs no guard: the lookup only runs after a successful cargo build (a step aborts on its first failing command), and an empty result makes cp fail and fail the step.
• path: on a plugin sync step is a plain relative path with no expansion (crates/icp/src/manifest/adapter/plugin.rs:136), so it cannot reference the target dir. The sync plugin guide now says so.

Verification

• icp build on examples/icp-rust, with and without CARGO_TARGET_DIR: fails on main, passes here, no stray target/ in the source tree, artifact left in place by cp.
• Confirmed a naive split into two commands: entries does fail, and that the |- block does not.
• icp build with package omitted and the canister named after the crate: the recipe derives --package icp-canister and icp_canister.wasm, and the build succeeds.
• icp project show on the changed examples; the bumped pin resolves and renders v3.4.0's lookup.
• Parsed all 97 non-template YAML blocks across the changed docs.

Follow-up (separate repo)

These docs now differ from the recipe itself, which still uses the one-line form. The |- block is worth proposing upstream in icp-cli-recipes.

[Copilot]

🟢 Approval recommended

The changes consistently address the documented Cargo target-dir mismatch with low risk, with only a minor hardening suggestion noted in review comments.

Pull request overview

This PR updates Rust build examples and documentation to correctly locate Cargo’s actual target directory (including workspace and CARGO_TARGET_DIR/build.target-dir cases), preventing build steps from succeeding but then failing to find the produced .wasm.

Changes:

• Replace hardcoded target/... paths with a cargo metadata-derived target directory in Rust build snippets across docs and examples.
• Bump pinned @dfinity/rust recipe references from v3.0.0 to v3.4.0 throughout documentation and examples.
• Update the examples validation script to locate the built icp binary via Cargo’s target directory rather than assuming ./target/debug.

File summaries

File	Description
scripts/validate-examples.sh	Resolve Cargo target dir before adding the icp binary directory to PATH.
examples/icp-sync-plugin/icp.yaml	Use Cargo metadata target dir for the canister wasm move step.
examples/icp-rust/icp.yaml	Use Cargo metadata target dir for the canister wasm move step.
examples/icp-rust-recipe/README.md	Bump the documented recipe pin to @dfinity/rust@v3.4.0.
examples/icp-rust-recipe/icp.yaml	Bump the recipe pin to @dfinity/rust@v3.4.0.
docs/reference/environment-variables.md	Update Rust build snippet to copy wasm from Cargo metadata target dir.
docs/reference/configuration.md	Update Rust build snippets and recipe pin references to v3.4.0.
docs/reference/canister-settings.md	Update Rust build snippet to copy wasm from Cargo metadata target dir.
docs/migration/from-dfx.md	Update Rust recipe pins and build snippet to use Cargo metadata target dir.
docs/guides/writing-sync-plugins.md	Clarify where plugin wasm lands and limitations of sync.steps[].path expansion.
docs/guides/using-recipes.md	Bump @dfinity/rust pin and update Rust build snippet to use metadata target dir.
docs/guides/managing-environments.md	Update Rust build snippet to copy wasm from Cargo metadata target dir.
docs/guides/creating-templates.md	Bump Rust recipe pin in template example to v3.4.0.
docs/guides/creating-recipes.md	Update recipe examples to use metadata target dir; add guidance explaining why.
docs/concepts/recipes.md	Bump recipe pins and update Rust build snippet to use metadata target dir.
docs/concepts/project-model.md	Update Rust build snippet to copy wasm from Cargo metadata target dir.
docs/concepts/build-deploy-sync.md	Update Rust build snippet to copy wasm from Cargo metadata target dir.

Review details

• Files reviewed: 17/17 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟢 Approval recommended

The documentation, examples, and validation script consistently resolve Cargo output locations, and the referenced recipe release exists.

Review details

• Files reviewed: 17/17 changed files
• Comments generated: 0 new
• Review effort level: Balanced