liveBook · Manning

Runner configuration

As explained in Embedded Software with Rust

A Cargo runner is a target-specific setting that specifies the command used to launch or flash a built program.

A Cargo runner is the command Cargo invokes to run an embedded program. Set it in .cargo/config.toml so cargo run can launch firmware on a physical board or in an emulator. section 3.2.3 section 2.7.2

[target.thumbv7m-none-eabi]
runner = "gdb-multiarch -q -x openocd.gdb"

rustflags = [
  "-C", "link-arg=-Tlink.x",
]

[build]
target = "thumbv7m-none-eabi"

This configuration pairs a Cortex-M3 target with a gdb-multiarch runner and linker flags; the runner command can be changed to use another tool. section 3.2.3

Choose the runner command to match how you want to run the firmware:

  • Use probe-rs to flash and run a Blue Pill, specifying the STM32F103C8 chip. section 2.6.4
  • Use gdb-multiarch with a GDB script to automate flashing and debugging through OpenOCD. section 3.2.3
  • Use QEMU to run firmware in an emulated environment; the runner command differs from the one used for a physical board. section 2.7.2

Keep the runner aligned with the selected target and the intended execution environment. Centralizing it in .cargo/config.toml avoids repeating lengthy command-line arguments. section 3.2.3 section 2.7.2

How Embedded Software with Rust covers it

How deep it goes
Defines the runner as a configured command and contrasts board and emulator choices, without detailing runner internals.
Examples
Uses probe-rs for a Blue Pill, gdb-multiarch with OpenOCD, and QEMU for emulation.
What it assumes
Assumes an embedded target and a chosen board or emulator; it explains runner configuration rather than tool installation.
What you can do after
Apply the setting to configure Cargo to invoke probe-rs, gdb-multiarch, or QEMU when running firmware.
How it connects
Links Cargo and .cargo/config.toml with probe-rs, OpenOCD, GDB, and QEMU.

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.