fbuild

2.2.3 verified Fri May 01 auth: no python

A platform-agnostic embedded build tool compatible with PlatformIO projects. Version 2.2.3 is the latest stable release. The project is actively maintained with a Rust core and Python CLI. Release cadence is irregular; check GitHub for updates.

pip install fbuild

Common errors

error ModuleNotFoundError: No module named 'fbuild' ↓

cause fbuild is not installed or installed in a different Python environment.

fix

Run pip install fbuild in the correct environment (e.g., virtual environment or base Python).

error AttributeError: module 'fbuild' has no attribute 'FBuild' ↓

cause You imported the package but are trying to access a symbol that was moved or removed in a newer version.

fix

Check that you are using the correct import: from fbuild import FBuild. In fbuild 2.x, FBuild is a top-level symbol. If using an older version, upgrade or adjust the import path.

error fbuild.exceptions.FBuildConfigError: 'board' is required ↓

cause You must specify a board when creating FBuildConfig; it's a mandatory field.

fix

Provide a valid board name, e.g., FBuildConfig(board='arduino_uno', ...).

error RuntimeError: Platform 'unknown' not supported. Check available platforms with fbuild list-platforms ↓

cause You supplied an invalid platform name.

fix

Use a supported platform. Run fbuild list-platforms in the terminal to see available platforms.

Warnings

breaking Python 3.11+ requirement: fbuild 2.x requires Python >=3.10. Earlier Python versions (3.8, 3.9) are not supported. ↓

fix Upgrade Python to 3.10 or later.

deprecated The `win_freestanding` and `linux_freestanding` platforms have been removed from fbuild 2.x. They were previously used for generating freestanding binaries. ↓

fix Use the standard platform: `win` or `linux` with appropriate config. Or switch to a different build system for freestanding targets.

gotcha When using fbuild on Windows, make sure your build tools (like GCC or MSVC) are available in PATH. fbuild does not install compilers automatically. ↓

fix Install a compiler (e.g., MinGW or MSVC) and ensure it's accessible.

gotcha If your PlatformIO project has custom `extra_scripts`, they might not run under fbuild. fbuild uses its own build process and may ignore PlatformIO's extra scripts. ↓

fix Port any necessary extra_script logic to fbuild's configuration or pre/post build hooks.

deprecated The command-line tool `fbuild` was renamed from `fb` in version 2.0.0. The old `fb` command is no longer available. ↓

fix Use `fbuild` instead of `fb` in scripts and documentation.

Imports

FBuild
wrong
```
from fbuild.fbuild import FBuild
```
correct
```
from fbuild import FBuild
```
One common mistake is importing from the module path incorrectly. fbuild exposes FBuild at the top level.
FBuildConfig
wrong
```
import fbuild.config
```
correct
```
from fbuild import FBuildConfig
```
FBuildConfig is a top-level symbol, not inside a config submodule.
fbuild.run_build
wrong
```
import fbuild; fbuild.run_build()
```
correct
```
from fbuild import run_build
```
run_build is a top-level function, not a module-level function.

Quickstart

Basic usage: configure and run an embedded build. Adjust board and platform to match your project.

from fbuild import FBuild, FBuildConfig

config = FBuildConfig(
    project_dir='./my_project',
    board='arduino_uno',
    platform='atmelavr'
)

builder = FBuild(config)
result = builder.build()
print('Build succeeded:', result.success)