`cargo_workspace`

Native Cargo project seed.

Description#

cargo_workspace runs Cargo metadata and emits ordinary first-party and external Rust targets. An existing Cargo.lock is used in locked mode. When it is absent, Cargo resolves dependencies and creates it. First-party packages become rust_library, rust_binary, rust_test, or rust_proc_macro targets. Locked external packages use the same fine-grained lowering as cargo_dependencies.

Cargo remains authoritative for workspace membership, targets, features, renamed dependencies, build scripts, versions, and checksums. By default, Once snapshots locked external package trees from Cargo's local cache into each target's output. The repository stays unchanged. A pre-existing vendored source directory can be selected explicitly. Targets whose required-features are not selected are omitted, matching Cargo's target selection. Generated tests, benchmarks, and examples include development dependencies. Each generated test runs from its own package root and receives a CARGO_BIN_EXE_<name> entry for every binary in its package, matching what Cargo gives an integration test. Entries in the [env] table of Cargo configuration reach the compiler, the build scripts, the test processes, and once run.

Packages are compiled once for the execution host. A second, host-only build of a package appears only when it would differ: when target names something other than the host, or when dep_rustc_flags carries a panic strategy that compiler plugins and build scripts must not inherit. Cargo target names are normalized to valid Rust crate identifiers while binary names retain their manifest spelling. Multi-output libraries emit one target per declared Rust library crate type. Cargo's workspace member list determines which packages are first-party, so local path dependencies outside that list remain ordinary dependency targets.

Attributes#

Attribute	Type	Required	Default	Description
`manifest`	string	no	`Cargo.toml`	Package-relative Cargo manifest
`lockfile`	string	no	`Cargo.lock`	Package-relative authoritative lockfile
`resolver_inputs`	list<string>	no	`srcs`	Text inputs available while deriving the graph
`metadata_file`	string	no		Optional checked Cargo metadata snapshot
`host_metadata_file`	string	no		Optional host metadata snapshot for cross-compilation
`vendor_dir`	string	no	Once-managed	Optional package-relative pre-vendored external sources
`features`	list<string>	no	`[]`	Selected Cargo features
`all_features`	bool	no	`false`	Select every Cargo feature
`no_default_features`	bool	no	`false`	Disable default Cargo features
`target`	string	no	host	Destination Rust target triple
`dep_rustc_flags`	list<string>	no	`[]`	Additional flags for external packages
`build_script_tools`	list<string>	no	`cmake`, `nasm`, `perl`, `pkg-config`, `protoc`, `python3`	Host tool names package build scripts may invoke; each is resolved on the search path during graph loading

Providers#

The target emits cargo_workspace.

Capabilities#

Capability	Output groups
`build`	none

Direct Use#

On a fresh clone, the first graph load can access the network while Cargo resolves or downloads dependencies. Once then imports the pinned graph from Cargo.lock and Cargo's local source cache.

Inspect the automatically derived graph:

bash

once query workspace
once query targets

No once.toml is required. To configure the resolver explicitly, author a target equivalent to:

toml

[[target]]
name = "cargo"
kind = "cargo_workspace"
srcs = ["Cargo.toml"]

[target.attrs]
resolver_inputs = ["Cargo.toml", "Cargo.lock", "**/Cargo.toml", ".cargo/config", ".cargo/config.toml"]

Keep this seed as the only Once target while Cargo metadata describes the complete build. Add explicit targets beside it for exceptional cross-language or packaging boundaries. Use a project Starlark module only when those exceptions share reusable behavior that the built-in target kinds cannot express.

Sources#

Cargo metadata defines the native integration graph.
The Cargo lockfile defines resolved versions and checksums.