fbuild

fbuild is a fast, multi-platform compiler, deployer, emulator runner, and serial monitor for embedded development. It reads the same platformio.ini files already used by PlatformIO sketches, but uses a Rust-native, data-driven build pipeline.

Build Matrix

These board builds are part of the front door. They show the platform breadth that fbuild actively protects in CI.

AVR

MegaAVR

Renesas

ESP8266

ESP32

CH32V (RISC-V)

CH32X (RISC-V, USB PD)

Teensy

STM32

SAM / SAMD

RP2040 / RP2350

Nordic NRF52

Apollo3

NXP LPC (Cortex-M0+)

Silicon Labs

Raspberry Pi Pico

Board descriptions and family deep-dives live in docs/BOARD_STATUS.md.

Build performance

The chart is regenerated nightly from clean-output (cold) and immediate repeat (warm) Arduino Uno Blink builds. Raw measurements are discoverable through the benchmark manifest.

Installation

pip install fbuild

For source installs, platform notes, and first-run cache behavior, start with the getting started guide.

Command Quick Start

fbuild reads the same platformio.ini files as PlatformIO. Use these commands as direct replacements for the most common PlatformIO workflows:

fbuild	PlatformIO equivalent	Use it to
fbuild build	pio run	Compile the project.
fbuild build --clean	pio run --target clean, then pio run	Clean and compile the project.
fbuild deploy	pio run --target upload	Build and upload firmware.
fbuild deploy --clean	Clean, then pio run --target upload	Clean, build, and upload firmware.
fbuild monitor	pio device monitor	Monitor serial output without flashing.
fbuild ci	pio ci	Build one or more sketches for CI.

Pass --platformio to build, deploy, or monitor to delegate that workflow to the installed PlatformIO CLI. fbuild ci is a fbuild-native, PlatformIO-compatible CI command; detailed flags and nested commands are in the CLI reference.

fbuild-only commands

These commands extend beyond the PlatformIO workflow surface:

Command	Purpose
fbuild symbols	Report per-symbol firmware size and bloat details.
fbuild bloat	Inspect symbol back-references and generate bloat graphs.
fbuild reset	Reset a device without flashing it.
fbuild purge	Purge downloaded packages or run cache garbage collection.
fbuild sync	Resolve platformio.ini dependencies into a deterministic lock file.
fbuild daemon	Manage the background build daemon, locks, and cache.
fbuild show	Show daemon logs and other runtime information.
fbuild device	List devices and manage device leases.
fbuild mcp	Start the Model Context Protocol server for AI integrations.
fbuild clang-tidy	Run clang-tidy static analysis on project sources.
fbuild iwyu	Run include-what-you-use analysis on project sources.
fbuild clangd-config	Generate clangd and VS Code configuration for the project.
fbuild test-emu	Build and run firmware in an emulator for testing.
fbuild clang-query	Run a clang-query matcher against project sources.
fbuild lnk	Fetch, verify, and create .lnk resource pointers.
fbuild lib-select	Diagnose the LDF-style library selection result.
fbuild compile-many	Compile many sketches against one board in parallel stages.
fbuild serial	Probe serial ports and read them with board-aware settings.
fbuild bringup	Orchestrate build, flash, reset, monitor, and bring-up steps.
fbuild port	Scan serial ports with vendor and product identification.
fbuild cache	Save, restore, list, and verify portable cache archives.

See fbuild help <command> or the full CLI reference for options and nested subcommands.

Quick Start

Create a minimal Arduino project:

mkdir my-project
cd my-project
mkdir src

Add platformio.ini:

[env:uno]platform = atmelavr
board = uno
framework = arduino

Add src/main.ino:

voidsetup() {
pinMode(LED_BUILTIN, OUTPUT);
}
voidloop() {
digitalWrite(LED_BUILTIN, HIGH);
delay(1000);
digitalWrite(LED_BUILTIN, LOW);
delay(1000);
}

Build it:

fbuild build

On the first build, fbuild downloads the toolchain and framework packages it needs, then caches them for later builds. A successful Uno build writes .fbuild/build/uno/firmware.hex.

Examples

Common workflows:

fbuild build
fbuild deploy --clean
fbuild deploy --monitor
fbuild test-emu . -e uno
fbuild monitor --timeout 60 --halt-on-success "TEST PASSED"

Detailed build, deploy, monitor, and emulator examples live in the CLI reference and emulator testing guide.

Docs Index

The full FAQ-style map is docs/INDEX.md. Common entry points:

Goal	Start here
Install fbuild and run the first build	docs/getting-started/
Use build, deploy, monitor, or test-emu	docs/reference/cli.md
Configure platformio.ini	docs/reference/platformio-ini.md
Check board and platform support	docs/platforms/
Understand the project rationale	docs/WHY.md
Work on fbuild itself	docs/development/
Read architecture internals	docs/architecture/overview.md

Key Features

• platformio.ini compatibility for existing Arduino and ESP32 sketches
• Fast incremental builds with cached toolchains, frameworks, and libraries
• URL-based package and library management, including GitHub lib_deps
• Build, deploy, serial monitor, and emulator test workflows from one CLI
• Cross-platform support on Windows, macOS, and Linux
• Transparent architecture with Rust workspace internals documented under docs/architecture/

See docs/WHY.md for the full rationale, benefits, and performance notes.

CLI Usage

The user-facing command reference is docs/reference/cli.md. It covers core workflows (build, deploy, monitor, test-emu) and diagnostics such as symbols, bloat, lib-select, compile-many, and ci.

Configuration

fbuild reads platformio.ini project files. The configuration reference, including default_envs, build_flags, lib_deps, upload and monitor settings, and compatibility notes, lives in docs/reference/platformio-ini.md.

Emulator Testing

fbuild can build firmware and run it without hardware via fbuild test-emu or fbuild deploy --to emu. Emulator backends, auto-detection rules, QEMU notes, and known limitations live in docs/guides/emulator-testing.md.

PlatformIO Compatibility: .eh_frame Strip

On supported release builds, fbuild may strip unused GCC .eh_frame unwind metadata to reduce firmware size. The policy, opt-out controls, and rationale are documented in docs/reference/platformio-compatibility.md.

Supported Platforms

fbuild supports AVR, MegaAVR, Renesas RA, ESP8266, ESP32 variants, CH32 RISC-V, Teensy, STM32, SAM/SAMD, RP2040/RP2350, Nordic NRF52, Apollo3, Silicon Labs EFR32, NXP LPC, and WASM via Emscripten.

For the canonical per-board CI badge matrix, support table, and board-family notes, see docs/BOARD_STATUS.md or the platforms docs.

Project Structure

The repository is a Rust workspace with a Python package boundary. The human development guide is docs/development/, and the crate dependency map is crates/CLAUDE.md.

Architecture

Architecture docs are decentralized under docs/architecture/. Start with docs/architecture/overview.md, then follow the subsystem-specific docs.

Development

Testing, troubleshooting, linting, release, and local setup instructions live in docs/development/. Project-wide rules for contributors and LLM agents are in CLAUDE.md.

License

In the spirit of Dan Garcia's permissively licensed software, fbuild is presented as free software.

BSD 3-Clause License