cargo-rustc

Build the package and pass options to rustc

$ cargo rustc -- [rustc_options]

$ cargo rustc [[-r|--release]]

$ cargo rustc [[-r|--release]] -- -C target-cpu=native

$ cargo rustc -- -C opt-level [1|2|3]

$ cargo rustc -- -C opt-level [s|z]

$ cargo rustc --lib -- -D unsafe-code

$ cargo rustc [[-p|--package]] [package]

$ cargo rustc --bin [name]

cargo rustc [OPTIONS] [--] [rustcflags…]

--lib
    Build the crate's library target

--bin NAME
    Build the specified binary

--bins
    Build all binaries

--example NAME
    Build the specified example

--examples
    Build all examples

--bench NAME
    Build the specified benchmark

--release
    Build artifacts in release mode with optimizations

--profile PROFILE
    Build with the given profile (debug/release)

--target TRIPLE
    Target triple to build for

--target-dir DIR
    Directory for target artifacts

--package SPEC…
    Package(s) to build (see cargo pkgid)

--all
    Build all workspace packages

--workspace
    Build workspace members and dependencies

--jobs N
    Number of parallel jobs

--keep-going
    Build as many crates as possible despite errors

-v, --verbose
    Use verbose output

--quiet
    No output printed to stdout

--color WHEN
    Control colored output (auto/always/never)

--manifest-path PATH
    Path to Cargo.toml

-Z FLAG…
    Unstable Cargo flags

--
    Separator; following args passed to rustc

cargo rustc compiles a Rust crate using the rustc compiler directly, while leveraging Cargo's dependency resolution, metadata injection, and build configuration. This subcommand is designed for scenarios where users need to pass custom or advanced flags to rustc that Cargo's higher-level commands like cargo build do not expose.

Key use cases include enabling nightly features with -Z flags, custom codegen options via -C, conditional compilation with --cfg, or experimenting with compiler internals. Cargo first builds dependencies and generates rlibs, then invokes rustc on the target crate, injecting necessary metadata for proper linking and incremental compilation support.

Unlike standard Cargo commands, cargo rustc forwards all arguments after -- verbatim to rustc, offering low-level control. It supports most cargo build options for package, target, and profile selection but skips --test. This makes it ideal for plugin development, custom linking, or optimization tweaking in complex projects.

Incremental builds work when possible, but custom rustc flags often invalidate caches, triggering recompiles. Widely used in Rust ecosystem for advanced tooling and CI setups requiring precise compiler control.

Does not support --test; custom rustc flags after -- often invalidate incremental caches, causing rebuilds. Requires valid Cargo workspace.

Release build with custom opt:
cargo rustc --release -- -C opt-level=z

Nightly feature:
cargo rustc -- -Z unstable-options --cfg feature="nightly"

Specific target:
cargo rustc --target wasm32-unknown-unknown -- --emit wasm

Args after -- go directly to rustc: use -C for codegen (e.g., -C lto), -Z for unstable (nightly-only), --crate-type for outputs.

Introduced in Cargo 0.12.0 (May 2015), cargo rustc provided direct rustc access amid growing demand for compiler experimentation as Rust stabilized post-1.0. Evolved with Cargo's unification of build options in 0.20+ (2017), aligning closely with cargo build. Remains key for nightly Rust workflows.

cargo build(1), cargo check(1), rustc(1), cargo rustdoc(1)