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] -- [RUSTC_OPTIONS...]

--target
    Build for the specified target triple (e.g., x86_64-unknown-linux-gnu). This affects the architecture and operating system for which the code is compiled.

--profile
    Build with the given build profile (e.g., dev, release, or a custom profile defined in Cargo.toml). This overrides the default profile for the current invocation.

--release
    Build with the release profile (optimized build). This is a convenient shortcut for --profile release.

-Z
    Unstable (nightly-only) Cargo flags, used for experimental Cargo features or diagnostics. For example, -Z build-std.

--features
    Space-separated list of features to activate. For example, --features "serde_derive json".

--all-features
    Activate all available features of the selected package.

--no-default-features
    Do not activate the default feature.

--package , -p
    Build only the specified package. This option may be specified multiple times. SPEC can be a package name or a path.

--lib
    Build the package's library.

--bin
    Build the specified binary. This option may be specified multiple times. If no NAME is given, all binaries are built.

--example
    Build the specified example. This option may be specified multiple times. If no NAME is given, all examples are built.

--test
    Build the specified test. This option may be specified multiple times. If no NAME is given, all tests are built.

--bench
    Build the specified benchmark. This option may be specified multiple times. If no NAME is given, all benchmarks are built.

--verbose, -v
    Use verbose output. May be specified twice for even more output (-vv).

--quiet, -q
    Do not print Cargo log messages, only output from rustc itself or errors.

--color
    Control when colors are used in output. Possible values: auto (default), always, never.

--manifest-path
    Path to the Cargo.toml file. By default, Cargo searches for Cargo.toml in the current directory or parent directories.

--workspace
    Build all members in the current workspace. This option is only valid if the current directory is within a workspace.

--frozen, --locked, --offline
    Controls network access for fetching dependencies. --frozen ensures no new lockfile updates, --locked ensures no new lockfile updates and uses existing, --offline works without network.

--
    A mandatory separator indicating that all subsequent arguments are to be passed directly to the rustc compiler. Any arguments following this separator will not be interpreted by Cargo.

RUSTC_OPTIONS...
    One or more options/flags that will be passed directly to the rustc compiler. Examples include -C opt-level=z, -C link-arg="-lc++", --emit=asm, -Z unstable-options, etc. Refer to rustc --help for a full list.

cargo rustc is a Cargo subcommand that compiles a package and allows passing arbitrary command-line arguments directly to the underlying rustc compiler. This command acts as a wrapper around the compilation process, primarily extending the functionality of cargo build or cargo check by exposing the full power of rustc. It is particularly useful for advanced scenarios where fine-grained control over the compilation is required, such as enabling unstable compiler features, setting specific optimization levels, or adding linker arguments that Cargo does not expose directly. When invoked, cargo rustc first resolves dependencies and prepares the build environment, then executes rustc with the specified target and the user-provided flags. The command respects Cargo's build configuration, including Cargo.toml profiles and environment variables.

1. Mandatory Separator: The -- separator is crucial. All arguments intended for rustc must come after it; arguments before it are consumed by Cargo.
2. Toolchain Dependency: Some rustc flags (especially those starting with -Z) are unstable and only available on the nightly Rust toolchain. Using them on stable will result in an error.
3. Conflict Risk: Passing certain rustc flags might conflict with Cargo's default build process or cause unexpected behavior. Exercise caution and understand the implications of the flags you pass.
4. Limited Scope: cargo rustc focuses solely on the compilation step. It doesn't affect other Cargo commands like cargo test or cargo run directly, though their compilation steps might be influenced if they implicitly call rustc with the same configuration.

1. Enabling Unstable Features: Used to enable experimental rustc features that are not yet stable. For example, cargo rustc -- -Z build-std to build the standard library from source.
2. Passing Linker Flags: Essential for linking against specific libraries or frameworks, especially in C/C++ interop or when building for embedded systems. Example: cargo rustc -- -C link-arg="-framework CoreFoundation" (on macOS).
3. Custom Optimization Levels: Overriding profile-defined optimization for specific needs, like smallest size (opt-level=z) or maximum performance (opt-level=3). Example: cargo rustc --release -- -C opt-level=z.
4. Emitting Compiler Artifacts: Generating intermediate files such as assembly code, LLVM IR, or MIR for debugging or analysis. Example: cargo rustc -- --emit=asm.

cargo rustc honors the build profiles defined in Cargo.toml (e.g., dev, release). You can specify a profile using --profile <NAME> or --release. Any rustc options passed via -- will then be applied in addition to or potentially overriding the options set by that profile. This allows for fine-tuning specific builds without altering your Cargo.toml for every experimental compile.

cargo rustc has been a fundamental subcommand within the Cargo toolchain since its early days, reflecting the Rust ecosystem's commitment to both high-level package management and low-level compiler control. Its evolution is intertwined with the development of rustc itself, as new compiler features and flags often become accessible via cargo rustc before or alongside more direct Cargo.toml configurations. It serves as a vital escape hatch for power users, enabling experimentation with cutting-edge compiler optimizations, custom linking, or addressing specific platform requirements not natively handled by default Cargo settings. While many common needs are now met by Cargo itself or build scripts, cargo rustc remains indispensable for niche or advanced scenarios, ensuring that developers are never entirely restricted from direct compiler interaction.

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