From 830701e670b6e1267913710a6651829f01b1ed28 Mon Sep 17 00:00:00 2001 From: Julien Calixte Date: Sat, 11 Jul 2026 12:39:24 +0200 Subject: [PATCH] docs(firmware): document light vs git build modes --- firmware/README.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/firmware/README.md b/firmware/README.md index 3b7fc79..d5f5a56 100644 --- a/firmware/README.md +++ b/firmware/README.md @@ -182,6 +182,34 @@ cargo build --release The first build is slow (the esp-idf C sources are checked out and built under `.embuild/`). Subsequent builds are incremental. +### Build modes — light (default) vs git + +The editor firmware builds **light by default** — no git. Publishing (`:sync` → +git push) is expensive to build: it drags in libgit2 + mbedTLS (compiled as an +esp-idf component) and the `git2` crate. So it sits behind a switch, and the +nominal build leaves it off — ideal for iterating on the editor, EPD, USB, or +SD without paying for libgit2: + +| Build | Command | libgit2 component | `git2` crate | `:sync` | +| ----- | ------- | ----------------- | ------------ | ------- | +| **Light** (default) | `just build` / `just flash` | not compiled (empty no-op) | not linked | saves locally, skips push | +| **Full (git)** | `just build-firmware-git` / `just flash-firmware-git` | compiled | linked | save → push | + +Two independent switches make this work, and the justfile flips them together: + +1. **`git` Cargo feature** (`--features git`) — pulls the `git2` crate and + turns on the `#[cfg(feature = "git")]` publish path in + [`src/main.rs`](src/main.rs) (`publish()`). Off by default. +2. **`LIBGIT2_SRC` env** — the [libgit2 component](components/libgit2/CMakeLists.txt) + only compiles its sources when this points at the vendored tree; unset, it + registers an *empty* component. Only the `*-git` justfile recipes set it. + +Because git code in the firmware binary is only ever compiled under +`--features git`, an ordinary `just build` can never accidentally drag libgit2 +in. (Git isn't wired into `main.rs` yet, so `flash-firmware-git` currently just +builds slower and behaves like the light build — the seam is in place ahead of +the integration.) + ## Flash (when hardware is on the bench) `cargo run --release` triggers `espflash flash --monitor` via the runner