CargoToolchainOptions

interface in bldr/rust-tools

How to build a CargoToolchain.

Properties

baseImage: any

property

The image to build on: a Rust toolchain image member, or one you derived yourself.

channel: string

property

Default toolchain channel ("stable", "nightly", "1.79.0") — set via rustup default (installed if missing).

components: string[]

property

rustup components to add up front (["clippy", "rustfmt"]). Cargo adds the ones its own commands need without being told, so this is for anything else that wants them.

env: Record<string, string>

property

Environment variables every command on this toolchain runs with.

Declared on the image's config, so they apply to the toolchain's own setup steps as well as to cargo — which is what you want for something like DEBIAN_FRONTEND, and why this is not a step you apply afterwards.

These win over the ones the toolchain sets for itself (CARGO_HOME, RUSTUP_HOME, PATH), so overriding one is possible and is your problem if cargo then cannot be found.

new CargoToolchain({
    baseImage: rust,
    targets: ["x86_64-unknown-linux-musl"],
    env: { RUSTFLAGS: "-C target-feature=+crt-static" },
})

hostArchitecture: string

property

Which architecture to select from a multi-architecture base image.

Defaults to "amd64", which is what nearly every build host is. Set it when building on or for something else — the name is the OCI architecture, so "arm64" rather than "aarch64".

scope: Scope

property

Where building this toolchain appears in the build tree.

Each call derives a new image, so placing it is unambiguous — unlike the shared base member it starts from.

Defaults to this member's own scope rather than being required: a toolchain is infrastructure that several members build on, and collecting every one of them under bldr/rust-tools keeps that shared cost in one place instead of repeating it inside each consumer's subtree.

See Scope.

targets: string[]

property

Target triples to install the standard library for, so CargoOptions.target can cross-compile to them.

Needed before a cross build will work: without the standard library for a triple, cargo fails with an error about a missing target rather than about a missing toolchain, which sends people looking in the wrong place.

const musl = new CargoToolchain({
    baseImage: rust,
    targets: ["x86_64-unknown-linux-musl"],
});