Use this skill when changing Cargo manifests, configuration, dependency workflows, builds, workspaces, packaging, publishing, Cargo scripts, or unstable Cargo features. Inspect the repository and installed toolchain before applying the guidance: project manifests, lockfiles, configuration, tests, and observed behavior take precedence.
Working method
- Run
cargo --versionand identify whether the repository pins a toolchain. - Inspect
Cargo.toml,Cargo.lock,.cargo/config.toml, workspace manifests, and CI commands relevant to the task. - Separate stable behavior from features that still require nightly Cargo
and
-Zflags. - Check the compatibility and removal notes before copying an older command line or configuration key.
- Open the task-specific reference from the index and preserve the repository's minimum supported Rust version.
- Validate manifest and configuration changes with the narrowest applicable Cargo command before running the full project test suite.
Reference index
| Reference | Topics |
|---|---|
| upgrades-and-compatibility.md | Security fixes, removals, deprecations, changed defaults, platform requirements, migration hazards |
| configuration-networking-and-cache.md | Configuration merging and includes, cache cleanup, Git and SSH, proxies, runners, warning policy |
| builds-targets-and-artifacts.md | Editions, targets, build directories, rustc and rustdoc, profiles, doctests, artifacts, cleaning |
| workspaces-dependencies-and-metadata.md | Workspaces, feature unification, dependency trees, metadata, vendoring, target filtering |
| packaging-publishing-and-registries.md | Package validation, archives, workspace publishing, registry data and APIs |
| scripts-build-scripts-and-subcommands.md | Cargo scripts, build-script environment and metadata, external subcommands, completions and help |
| unstable-analysis-and-lints.md | Build analysis, timings, SBOM data, Cargo lints, unit graphs, experimental build controls |
Breaking changes and migration checks
Upgrade vulnerable Cargo installations
Treat crate extraction as a security boundary. Affected older Cargo versions on Unix-like systems can allow malicious archives to alter permissions outside the extraction tree. Use a toolchain containing the extraction fix before handling untrusted crates.
Replace removed interfaces
- Replace the removed unstable
build-planfeature with plumbing commands,--unit-graph, or structured build-analysis logs. - Replace removed unstable
--out-dirwith--artifact-dir. - Replace removed
--lockfile-pathcommand-line usage withresolver.lockfile-pathunder-Zlockfile-path, while accounting for command-specific behavior. - Do not pass a format value to
--timings; use build-analysis logs for machine-readable data andcargo report timingsfor an HTML report. - For public dependencies, use
cargo tree --edges public, not the earlier--depth publicspelling.
Recheck changed defaults
cargo fixandcargo clippy --fixoperate on default targets unless--all-targetsis requested. Edition migration modes still imply all targets.cargo publishdoes not retain the generated.cratearchive. Runcargo packagewhen a local archive is required.cargo metadatais independent ofCARGO_BUILD_TARGET; use--filter-platformwhen platform filtering is required.cargo installignores a configuredresolver.lockfile-path.cargo packageincludesCargo.lock, but--exclude-lockfilecan skip verification of a present lockfile.
Audit configuration layering
Program-and-argument settings such as runners, credential providers,
credential aliases, and documentation browsers are atomic values when
configuration layers merge. Nested non-mergeable lists replace rather than
merge, and a --config value takes precedence over the corresponding
environment value.
High-value stable features
Control build output and warnings
[build]
build-dir = "build"
warnings = "deny"
build.build-dir relocates intermediate artifacts, but its internal layout is
not a supported interface. build.warnings accepts warn, allow, or deny;
the environment equivalent is CARGO_BUILD_WARNINGS. Warning policy does not
change compiler flags used to identify cached artifacts.
Reuse shared configuration
Top-level include can compose Cargo configuration files:
include = ["../shared/cargo.toml"]
Nightly optional includes use list form with { path, optional = true }.
Do not use glob or template syntax for include paths.
Select the current host portably
Use host-tuple where Cargo accepts a target:
cargo build --target host-tuple
cargo metadata --filter-platform host-tuple
This avoids hard-coding the host target triple.
Use current command conveniences
-m is the short form of --manifest-path:
cargo build -m crates/app/Cargo.toml
cargo clean --workspace limits cleaning to workspace members. An explicit
cargo clean --target-dir now rejects paths that do not resemble Cargo target
directories.
Publish related workspace crates
cargo publish --workspace
cargo publish -p core -p app
Cargo can order and publish workspace crates that depend on one another. Publishing is not transactional: a registry failure can leave only part of the requested set published.
Configure proxy trust
[http]
proxy-cainfo = "proxy-ca.pem"
Use http.proxy-cainfo for the CA bundle used by TLS connections through a
proxy. Keep registry API URLs free of a trailing slash.
Set profile and target behavior
Profiles accept an immediate-abort panic strategy:
[profile.release]
panic = "immediate-abort"
Target tables selected by cfg expressions can set rustdocflags:
[target.'cfg(unix)']
rustdocflags = ["--cfg", "docsrs"]
Boolean literals are valid cfg predicates in manifests and configuration.
Build scripts and Cargo scripts
Build scripts receive activated features through CARGO_CFG_FEATURE and the
profile's debug-assertion state through CARGO_CFG_DEBUG_ASSERTIONS.
rerun-if-env-changed observes values supplied through Cargo's [env]
configuration.
Cargo-script behavior remains gated by -Zscript. Script configuration and
lockfiles are relative to the script, scripts ignore enclosing workspaces, and
their manifests accept only script-valid fields with strict frontmatter
fences. Read the scripts reference before relying on build-directory or
lockfile placement.
Nightly feature discipline
Do not remove a required -Z flag merely because a related component became
stable. The following areas still include unstable controls:
- feature unification and public-dependency handling;
- standard-library builds and custom JSON target specifications;
- multiple build scripts and arbitrary build-script metadata;
- Cargo lints, Unicode diagnostics, and mergeable rustdoc information;
- build analysis, section timings, SBOM precursors, and experimental build directory layout;
- Cargo scripts, configurable lockfile paths, and artifact dependencies.
Confirm the exact flag and current behavior in the relevant reference. Keep nightly-only configuration isolated when stable Cargo must still parse the project.
Validation checklist
- Confirm the installed Cargo version and pinned toolchain.
- Parse all touched manifests and configuration with the project's supported toolchains.
- Run
cargo metadataafter workspace, dependency, feature, or target changes. - Run
cargo package --listwhen package contents change. - Run
cargo packagewhen archive generation or publication readiness matters. - Test both host and cross-target paths when runners, doctests, build scripts, or target-specific flags change.
- Treat registry publishing as externally visible and non-atomic.
- Avoid depending on internal target or build-directory layouts.
- Record why an unstable flag is needed and which commands require it.