Development Guide
This page gets you from a fresh clone to a running build and a passing make check. When you are
ready to submit, read the Contributing Guide.
Prerequisites
-
git-lfs (mandatory)
Images, icons, and fonts are stored in Git LFS. Cloning without it gives confusing "missing asset" errors at build time or runtime. If you already cloned without it, rungit lfs install && git lfs pull. -
Rust, stable toolchain (edition 2024)
rustup is the easiest way to get it. Nightly is not needed. -
Platform libraries:
Ubuntu and other Debian-based distributionsmake setup-debian-depsFedoramake setup-fedora-deps
Clone and run
git lfs install
git clone https://github.com/beagleboard/bb-imager-rs.git
cd bb-imager-rs
cargo run -p bb-imager-gui
cargo run -p bb-imager-cli -- --help
When flashing real hardware or benchmarking, use a release build (--release).
|
make help lists every Makefile target and tunable variable (TARGET, feature toggles such as
PB2_MSPM0/ZEPTO_I2C/UPDATER, packaging variables).
Workspace layout
The workspace is layered: front-ends → bb-flasher → per-target flasher crates → support crates.
| Crate | Purpose |
|---|---|
Front-ends |
|
|
The GUI, built with Iced (Elm architecture). The top-level |
|
Screen views (one module per page) used by the GUI. |
|
Reusable Iced widgets. |
|
The CLI, built with |
Flashing core |
|
|
The common façade both front-ends program against. Re-exports and feature-gates the concrete flashers below. Most capabilities are off by default. |
|
OS images to SD cards (Linux udev, macOS authopen, Windows). |
|
BeagleConnect Freedom CC1352P7 and its MSP430 USB-UART bridge. |
|
MSPM0 co-processors (BeagleConnect Zepto, PocketBeagle 2) over UART/I2C. |
|
USB DFU. |
Support |
|
|
Parses and generates the board/image catalog ( |
|
Async downloader with caching. |
|
Shared utilities (cancellation, progress-reporting readers, file streaming). |
|
Enumerates destination drives (Rust port of Balena’s drivelist). |
|
bmap parsing for sparse-image flashing. |
|
Generates |
Check and test: use the Makefile
Large parts of the code are behind cargo features (per-board flashers, static vs. shared linking,
platform SD backends). Plain cargo check / cargo test at the workspace root silently skips
feature-gated modules. The Makefile passes the same feature sets as CI:
make check # clippy (falls back to cargo check) over CLI, GUI and libraries
make test # same coverage, runs cargo test
make check-cli # or check-gui / test-cli / test-gui
To run a single test, target the crate and enable the features it needs:
cargo test -p bb-imager-gui <test_name>
cargo test -p bb-flasher -F sd <test_name>
Run cargo fmt and make sure make check is clean before submitting. rustfmt and clippy are
mandatory.
Feature flags
Features cascade from front-end → bb-flasher → flasher crates, so always build with the intended
set:
-
The GUI links statically by default (
static: bundled SQLite, rustls).system-depsswitches to system libraries and native TLS. -
static-hidraw/shared-hidrawchoose how USB HID is linked. The CLI defaults to static because distribution hidraw is often too old. -
Board support (
bcf_cc1352p7,bcf_msp430,pb2_mspm0,zepto_uart,zepto_i2c,dfu) is opt-in per binary. See CLI features. -
The
_check_common,_check_cli, and_check_guirecipes in theMakefiledefine which combinations must compile.
Debugging the GUI
The GUI can run in a debug mode that exposes comet, Iced’s
inspector/debugger. Press F12 in the running application to open it.
This needs the Dioxus CLI (dx), since
debug mode uses its serve command:
cargo install dioxus-cli
make debug-gui
Hot-reloading is meant to work in this mode but is currently unreliable. With dx, code
changes are picked up but the application resets to the start screen, so App state is lost.
cargo-hot does not work at all. Debugging with comet works regardless.
|
Building these docs
The documentation is an Antora component in docs/. Build and serve it
at http://localhost:8000 with Podman (or Docker, via CONTAINER=docker):
make docs-serve
make docs only builds. Inside a git worktree, the docs are staged and built under target/docs.
Screenshots in docs/modules/ROOT/images are a symlink to assets/screenshots.