CargoCoverageOptions

interface in bldr/rust-tools

Extra knobs for Cargo.coverage.

Extends CargoOptions and not CargoTestOptions, even though this runs the tests: CargoTestOptions.compileOnly names targets that are compiled but never run, and a target that never runs contributes no coverage. Inheriting it would put a knob here that silently does nothing, which is the failure mode that option exists to prevent. Gate a compile-only target on the test target, where it is actually enforced.

Properties

allFeatures: boolean

property

Enable every feature the crate declares (--all-features).

binArgs: string[]

property

Extra arguments for the program cargo runs, placed after --.

Which program that is depends on the command: the test harness for a test run, the lint driver for clippy, rustdoc for a docs build. Kept separate from cargoArgs because the two are not interchangeable — cargo rejects a harness flag it does not know, and the harness never sees a flag left on cargo's side of the separator.

// Run only the tests whose name contains "parse", single-threaded.
c.test({ binArgs: ["parse", "--test-threads=1"] });

cargoArgs: string[]

property

Extra arguments for cargo itself, placed before the -- separator.

This is where target selectors and cargo flags go: ["--lib", "--tests"], ["--no-fail-fast"], ["--locked"].

c.test({ lib: true, noFailFast: true });

convert: CoverageConvertOptions

property

Overrides for the conversion into a CoverageReport (Cargo.coverage).

The defaults are derived from where this builder mounts things, which is right for a crate whose source is one member. Reach for this when it is not: a member with cross-member deps passes mappings naming their real members, since the builder knows those sources only by crate name and refuses to guess (see #coverageMappings).

See CoverageConvertOptions.

features: string[]

property

Features to enable (--features a,b).

formats: CargoCoverageFormat[]

property

Which formats to write. Defaults to both — they come from one instrumented run, so the second costs an llvm-cov export and nothing else, and a consumer added later needs no rebuild of the producer.

See CargoCoverageFormat.

ignoreFilenameRegex: string

property

An extra regex of source paths to leave out of the report, on top of the dependency sources cargo-llvm-cov already excludes.

For generated code that would otherwise dominate the numbers — a protobuf module nobody wrote is neither covered nor uncovered in any sense a reader cares about.

jobs: number

property

Cap cargo's parallelism (-j N). Left unset, cargo uses every core.

Worth setting for a large workspace. Peak memory scales with job count, so a 32-way compile can exceed the memory a build is allowed and be killed for it — which surfaces as a mysterious signal rather than as "out of memory". Fewer jobs is a little slower and finishes.

noDefaultFeatures: boolean

property

Turn off the crate's default features (--no-default-features).

package: string

property

Restrict the command to a single workspace package (-p <pkg>).

Right for an artifact, since a binary comes from exactly one package. Think twice for anything that tests: naming packages by hand is how a crate quietly ends up tested nowhere, and a crate whose tests never ran looks exactly like a crate whose tests pass. Prefer CargoConfig.workspace, which cannot leave a crate out because it never enumerates them.

profile: string

property

Which cargo profile to build ("dev" by default, or "release", or a profile the crate defines itself).

resources: DagResources

property

What this one command's run is admitted against and held to, overriding CargoConfig.resources. Commands differ by a lot — a check is not a test --no-run, which is not a release build — and a grant is both a ceiling and a reservation, so asking for the heaviest command's budget everywhere would needlessly stop builds running side by side.

See DagResources.

sccache: boolean

property

false runs this one command without the node's shared compile cache, whatever CargoConfig.sccache says. true cannot switch it on for a builder that turned it off — the builder's setting is the ceiling.

target: string

property

Cross-compile for a target triple (--target <triple>). The triple must be installed in the image — see CargoToolchainOptions.targets.

timeoutSecs: number

property

Wall-clock limit in seconds, after which the command is killed and the build fails.

Without one, a wedged test does not fail the build — it hangs it, and a build that never returns is far more annoying to diagnose than one that fails. Omit for no limit.