liveBook · Manning

Cargo feature

As explained in Embedded Software with Rust

A Cargo feature is a named compile-time option that conditionally enables code or dependencies in a Rust package.

A Cargo feature is a named compile-time switch that selects optional code or dependencies. In embedded Rust, features help tailor firmware to a microcontroller, peripheral set, or build scenario without including every available component. This can reduce binary size and build time. section 3.1.2 section 3.3.1

Select a dependency’s features in Cargo.toml. For example, stm32f1xx-hal uses the stm32f103 feature to select the matching device support and medium to configure the HAL for that variant. Other features can enable runtime integration or hardware-specific behavior. section 3.1.2 section 4.6.6

[package]
name = "cortex-m-blinky"
edition = "2024"
version = "0.1.0"

[dependencies]
cortex-m = "0.7"
cortex-m-rt = "0.7"
cortex-m-semihosting = "0.5"
panic-halt = "1.0.0"
stm32f1xx-hal = { version = "0.11.0", features = ["stm32f103", "medium"] }

[profile.release]
opt-level = 'z'
codegen-units = 1
lto = true

The dependency declaration selects two HAL features; the release profile separately configures size optimization. section 3.1.2

A package can also define its own features in a [features] table. Mark dependencies optional when they are not always needed, then group them under a named feature. The special default entry selects features for ordinary builds. section 3.3.2

[package]
name = "feature-demo"
version = "0.1.0"
edition = "2024"

[dependencies]
cortex-m = "0.7.7"
cortex-m-rt = "0.7.5"

panic-halt = { version = "1.0.0", optional = true }
panic-semihosting = { version = "0.6", optional = true }
cortex-m-semihosting = { version = "0.5", optional = true }

[features]
default = ["panic-halt"]
semihosting = ["dep:panic-semihosting", "dep:cortex-m-semihosting"]

This manifest enables panic-halt by default and groups two optional dependencies under semihosting. section 3.3.2

Use #[cfg(feature = "name")] to include Rust code only when a feature is active. The following example also uses compile_error! to reject builds with both panic backends enabled or neither selected. section 3.3.2

#![no_std]
#![no_main]

use cortex_m_rt::entry;

// If both are enabled, fail with a message
#[cfg(all(feature = "semihosting", feature = "panic-halt"))]
compile_error!(
    "Do not enable both semihosting and panic-halt. \
Use: --no-default-features --features semihosting"
);

// Ensure a panic backend is selected
#[cfg(not(any(feature = "semihosting", feature = "panic-halt")))]
compile_error!(
    "No panic backend selected. Enable default features (panic-halt) \
or build with --features semihosting."
);

#[cfg(feature = "semihosting")]
use {
    cortex_m_semihosting::hprintln,
    panic_semihosting as _,
};

#[cfg(feature = "panic-halt")]
use panic_halt as _;

#[entry]
fn main() -> ! {
    #[cfg(feature = "semihosting")]
    {
        let _ = hprintln!("Semihosting I/O is enabled.");
    }

    panic!("This will halt (panic-halt) or print via semihosting
    (semihosting feature).");
}

Conditional imports select the panic backend, while compile-time checks guard against invalid combinations. section 3.3.2

Choose a panic backend

With the example manifest, cargo run uses the default panic-halt backend. Use cargo run --no-default-features --features semihosting to select semihosting instead; disabling defaults avoids enabling both backends. Flashing and running through probe-rs requires a runner configured for the embedded target. section 3.3.2

A feature can also be an empty flag that only controls source code. For example, debug-panic = [] can select semihosting panic output with #[cfg], while the default build uses a silent halt. section 6.4.5

Check dependency features before using them in bare-metal firmware:

  • Look at the crate’s Features listing on crates.io, or inspect its Cargo.toml on docs.rs or in the upstream repository. section 3.3.4
  • Run cargo tree -e features to see enabled features and how they propagate through the dependency graph. section 3.3.4
  • If desktop defaults pull in std, consider disabling them with default-features = false and enabling only what the firmware needs. section 3.3.4

How Embedded Software with Rust covers it

How deep it goes
Explains feature declarations, optional dependencies, conditional compilation, build commands, and dependency-feature inspection.
Examples
Uses STM32 HAL selection, semihosting and panic backends, and a single-core critical-section feature.
What you can do after
Apply it via Cargo to configure dependencies, select conditional code, and inspect enabled features.
How it connects
Connects features to conditional compilation, optional dependencies, hardware abstraction layers, no_std, and panic handlers.

Also explained in

Compare how 3 books explain cargo feature →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Embedded Software with Rust. The section links point to the parts of the book it draws on.