liveBook · Manning

Chapter 3: Project structure and configuration

What you will learn in chapter 3 of Embedded Software with Rust

The introduction explains why developers need to understand embedded Rust project structure beyond what a generated template provides.

After this chapter you will be able to

What it builds on

Section by section

Introduction

The introduction explains why developers need to understand embedded Rust project structure beyond what a generated template provides.

Key terms: cargo generate, project template, project structure

3.1 Understanding Rust embedded project structure

This introduction previews an overview of embedded Rust project files and configuration, including how they compare with desktop Rust projects.

3.1.1 A typical embedded Rust project layout

This section shows that an embedded Rust project resembles a standard Cargo project but adds files for hardware-specific build needs.

Key terms: bare-metal Rust project, memory.x, .cargo/config.toml, build.rs

3.1.2 The role of Cargo.toml in embedded projects

This section explains how Cargo.toml describes an embedded project and tailors its build to a microcontroller through profiles and dependency features.

Key terms: Cargo.toml, manifest, package metadata, dependencies, build profiles, release profile, opt-level = "z", link-time optimization, LTO, code footprint

3.1.3 Cargo.lock: Ensuring dependency reproducibility

This section explains how Cargo.lock keeps embedded builds reproducible by recording specific dependency versions.

Key terms: Cargo.lock, dependency tree, reproducibility

3.1.4 Optional: Embed.toml and advanced tool integration

This subsection explains the optional role of Embed.toml in cargo-embed workflows and why later examples use OpenOCD instead.

Key terms: Embed.toml, cargo-embed, probe-rs, RTT, GDB, OpenOCD, .cargo/config.toml, flashing/debugging backend

3.2 Build system & linker configuration

Introduces build-system and linker configuration as a way to tailor an embedded Rust project to its target hardware.

Key terms: build system, linker configurations, target hardware, reliable and reproducible embedded builds

3.2.1 Defining memory layout with memory.x

This section explains how a runtime-specific memory.x file describes a microcontroller’s memory regions so the linker can place firmware correctly.

Key terms: memory.x, link.x, linker script, cortex-m-rt, riscv-rt, FLASH, RAM, ORIGIN, LENGTH, access permissions

3.2.2 Optional build-time customization with build.rs

This section explains when an embedded Rust project needs an optional build.rs script and illustrates how it can generate a linker script at build time.

Key terms: build.rs, build script, Cargo, memory.x, OUT_DIR, linker’s search path

3.2.3 The role of .cargo/config.toml in embedded Rust

The section explains how .cargo/config.toml makes embedded builds consistent by setting the target, runner, and linker flags in one place.

Key terms: .cargo/config.toml, [build], target triple, rustflags, link.x, runner, gdb-multiarch, OpenOCD, probe-rs run, Embed.toml

3.3 Managing features & dependencies in Cargo

The section introduces feature and dependency management as the next topic for tailoring embedded Rust firmware to hardware variants and build scenarios.

3.3.1 The importance of features in embedded Rust

This section explains why Cargo features help embedded firmware include only needed functionality while supporting different hardware and build configurations.

Key terms: Cargo features, optional components, hardware variants, debugging and production configurations

3.3.2 Defining features in Cargo.toml

This section shows how Cargo features select optional embedded dependencies and how to run either a default panic-halt build or a semihosting build.

Key terms: Cargo.toml, optional, [features], semihosting, default, panic-halt, --no-default-features, --features semihosting, conditionally compiled, .cargo/config.toml

3.3.3 Target-specific dependencies

This section explains how Cargo restricts dependencies to particular target architectures or build environments.

Key terms: conditional dependency declarations, target-specific configuration options, support crates

3.3.4 Discovering and Understanding Features in Dependencies

This section shows how to find a dependency’s features, trace which ones are enabled, and avoid unsuitable defaults in bare-metal builds.

Key terms: features, Cargo.toml, [features], crates.io, docs.rs, cargo tree -e features, dependency tree, enabled features, default features, std

3.4 Configuring no_std for embedded systems

The section introduces why bare-metal microcontroller firmware uses Rust without the standard library.

Key terms: bare-metal microcontrollers, no_std, standard library

3.4.1 What does no_std mean in embedded Rust?

Explains why bare-metal Rust uses no_std, what core still provides, and which standard-library facilities are unavailable without additional support.

Key terms: std crate, no_std mode, core crate, dynamic memory allocation, allocator, entry point, runtime behavior

3.4.2 How to set-up a no_std project

This section explains the crate attributes and panic handler required for a bare-metal no_std project without a runtime crate.

Key terms: no_std, no_main, crate-level attributes, main.rs, lib.rs, panic handler, standard library’s panic support, infinite loop

3.4.3 A minimal bare-metal no_std example

This section describes a minimal bare-metal no_std application through its custom entry point, infinite loop, and lack of operating-system services.

Key terms: no_std, _start, custom program entry point, infinite loop, bare-metal

3.4.4 Platform-specific aspects: Cortex-M vs. RISC-V

This section compares the architecture-specific runtime support used to start no_std programs on Cortex-M and RISC-V.

Key terms: no_std, cortex-m-rt, riscv-rt, startup code, interrupt vector table, #[entry], main, panic-halt

3.5 Setting-up commonly used embedded crates

3.5.1 Core architecture crates

This section identifies the architecture-specific crates that provide CPU access and bare-metal runtime support for Cortex-M and RISC-V, along with crates for panic behavior and debug output.

Key terms: cortex-m, cortex-m-rt, riscv, riscv-rt, SysTick, NVIC, panic-halt, panic-semihosting, panic-itm, cortex-m-semihosting

3.5.2 Practical example: Using Cortex-M crates together

A SysTick example shows how three Cortex-M crates divide responsibility for peripheral access, runtime hooks, and panic behavior.

Key terms: SysTick, cortex-m, cortex-m-rt, #[entry], #[exception], panic-halt

3.5.3 The embedded HAL ecosystem

This section explains how embedded-hal traits let one sensor driver work across Linux and bare-metal hardware, while each platform supplies its own peripheral setup and trait implementations.

Key terms: embedded-hal, traits, I2C, delay provider, lsm303agr, I2cdev, peripheral clocks, PB6, PB7, alternate-function open-drain

3.5.4 Example: Implementing an embedded-hal trait for platform agnostic drivers

This section shows how trait-based peripheral interfaces let embedded Rust drivers work across microcontrollers while each chip’s HAL handles its hardware details.

Key terms: OutputPin, set_high(), set_low(), Result<(), Self::Error>, &mut self, HAL, strongly-typed pin, GPIO controller, memory-mapped GPIO registers, blink_led()

3.5.5 Peripheral access crates (PACs), Hardware Abstraction Layers (HALs), and Board Support Packages (BSPs)

Distinguishes PACs, HALs, and BSPs by the level of hardware access and support each provides.

Key terms: Peripheral Access Crates (PACs), Hardware Abstraction Layers (HALs), Board Support Packages (BSPs)

3.5.6 Expanding beyond Cortex-M and RISC-V

This section shows that embedded Rust support extends beyond Cortex-M and RISC-V, but varies in maturity across microcontroller families.

Key terms: Cortex-M, RISC-V, AVR, ESP32, TriCore, MSP430

3.6 Summary

Where this is used later

Concepts explained in this chapter

← Chapter 2: Setting up your Rust tool-chain Chapter 4: Startup and Initialization in Bare-Metal Rust →

These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.