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 / SAME
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:
void setup() {
pinMode(LED_BUILTIN, OUTPUT);
}
void loop() {
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.inicompatibility 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
fbuild is free software licensed under the GNU Affero General Public
License v3.0 only (AGPL-3.0-only). See LICENSE.
1 maintainer
Metadata
1 maintainer
Release files for fbuild 2.5.23
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| fbuild-2.5.23-cp310-abi3-win_amd64.whl | CPython 3.10 | abi3 | Windows x86-64 | Details |
| fbuild-2.5.23-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl | CPython 3.10 | abi3 | Linux glibc 2.17+ x86-64 | Details |
| fbuild-2.5.23-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | CPython 3.10 | abi3 | Linux glibc 2.17+ ARM64 | Details |
| fbuild-2.5.23-cp310-abi3-macosx_11_0_arm64.macosx_10_12_x86_64.whl | CPython 3.10 | abi3 | macOS 11.0+ ARM64, macOS 10.12+ x86-64 | Details |
Total release size: 129.5 MB
Release files / fbuild-2.5.23-cp310-abi3-win_amd64.whl
| Download URL | fbuild-2.5.23-cp310-abi3-win_amd64.whl |
|---|---|
| Size | 30.8 MB |
| Tags | CPython 3.10 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
290fccdc6d348f7d0db3ce4e7506fa38a9018ddc89ebfbd416ea016031cf8cf5
|
|
BLAKE2b-256 checksum How to use checksums |
55034a1c613c4457f423aad44bc4c8a98792c140abce0d557e10e3a0437e02c9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 6, 2026.
Transparency logRelease files / fbuild-2.5.23-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | fbuild-2.5.23-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 32.0 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
05b107813c5108b2b5b32ae6dbe51ebdfcf6f3fc020b4edeece7201a44d147ce
|
|
BLAKE2b-256 checksum How to use checksums |
63fb2a45341d0c764d1db228d270d89606f5ec310f7d56d68e70fbe3043b944f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 6, 2026.
Transparency logRelease files / fbuild-2.5.23-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | fbuild-2.5.23-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 34.8 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
80636a61c6aa208c9fe3a9a71b3d36537306802952f7c5a69ab89c48204a56a3
|
|
BLAKE2b-256 checksum How to use checksums |
db474f8c7018e0c24d132291a09b050e89578188f76b97f417e1336e8a14f97e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 6, 2026.
Transparency logRelease files / fbuild-2.5.23-cp310-abi3-macosx_11_0_arm64.macosx_10_12_x86_64.whl
| Download URL | fbuild-2.5.23-cp310-abi3-macosx_11_0_arm64.macosx_10_12_x86_64.whl |
|---|---|
| Size | 31.8 MB |
| Tags | CPython 3.10 abi3 macOS 10.12+ x86-64 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
3ec88bf3b722e10f79c36b33c272ac5f26b0ced1e7608c14fa7cb0c943a59f4e
|
|
BLAKE2b-256 checksum How to use checksums |
c1414103e03a45f0ac9e05548387ace9cf4bbae1c54782aac52da9caa56d65f4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 6, 2026.
Transparency log
