Building & Testing

Commands for building the firmware, flashing it, and running the host-side tests and linters. For an end-user flashing guide see Flashing the Firmware.

Toolchain setup

The Rust toolchain is pinned to channel = "esp" in rust-toolchain.toml. The default target is xtensa-esp32-espidf (classic e-paper build); the JC3248W535C touchscreen build uses xtensa-esp32s3-espidf. Both use ESP-IDF v5.5. Install the toolchain with espup:

cargo install espup --locked
espup install --toolchain-version 1.90.0.0
cat $HOME/export-esp.sh >> ~/.bashrc
source ~/.bashrc
cargo install cargo-generate espflash ldproxy

rust-toolchain.toml pins only the toolchain name, not its version, so --toolchain-version has to be given explicitly: a release after 1.90.0.0 regressed the Xtensa LLVM backend, which then fails to compile serde_json’s f32 path with Cannot select: XtensaISD::PCREL_WRAPPER TargetConstantPool. CI pins the same version — see .github/workflows/ci.yml.

Build & flash

cargo build                       # debug build
cargo build --release             # release build

cargo run                         # flash + monitor (espflash runner in .cargo/config.toml)
cargo espflash flash --monitor    # alternative

# JC3248W535C touchscreen (ESP32-S3):
cargo build --features jc3248 --target xtensa-esp32s3-espidf
cargo run --features jc3248 --target xtensa-esp32s3-espidf

Unit tests

The platform-independent modules are tested on the host (x86), not on the ESP32:

cargo test --lib --no-default-features --target x86_64-unknown-linux-gnu

Linting

cargo fmt --all -- --check
# Clippy, per build configuration. There is no single command that covers all
# four: ``--all-targets --all-features`` cannot work, because the binary needs
# the ESP toolchain and target while the lib tests need the host one.
cargo clippy -- -D warnings
cargo clippy --target xtensa-esp32s3-espidf --features jc3248 -- -D warnings
cargo clippy --target xtensa-esp32s3-espidf --features screen_test -- -D warnings
RUSTUP_TOOLCHAIN=stable cargo clippy --lib --tests --no-default-features \
    --target x86_64-unknown-linux-gnu -- -D warnings