mirror of
https://github.com/Colorado-Mesh/meshcore-bot-firmware.git
synced 2026-08-14 01:30:29 +00:00
60 lines
5.0 KiB
Markdown
60 lines
5.0 KiB
Markdown
# Step 2 Execution Plan: Add representative build and size-report tooling
|
|
|
|
## Goal
|
|
Create local and CI tooling that applies the MeshCore patch queue, builds the four representative companion environments, captures per-environment logs/artifacts, and emits a deterministic size JSON summary.
|
|
|
|
## Current Code Observations
|
|
- `vendor/MeshCore/build.sh` provides `build-firmware <target>` and copies artifacts to its own `out/` directory after each build.
|
|
- `vendor/MeshCore/build.sh` removes `vendor/MeshCore/out` at startup, so wrapper tooling must copy artifacts after each environment build before starting the next one.
|
|
- `vendor/MeshCore/build.sh` requires `FIRMWARE_VERSION` in the environment and uses the current MeshCore git SHA in artifact filenames.
|
|
- Upstream CI installs Python 3.11 and PlatformIO with `pip install --upgrade platformio`, then runs `build.sh build-companion-firmwares`.
|
|
- Representative envs exist in `variants/heltec_v3/platformio.ini` and `variants/rak4631/platformio.ini`; RAK4631 companion envs set `board_upload.maximum_size = 712704`.
|
|
- The wrapper currently has no `.gitignore`, no `.github/workflows/`, and no build output tooling.
|
|
|
|
## Files to Change
|
|
- `scripts/build-representative.sh` — new wrapper build script for patch application, four-env builds, logs, copied artifacts, and size summary generation.
|
|
- `scripts/parse-size-report.py` — new parser for PlatformIO RAM/flash output plus artifact byte sizes, with optional baseline/compare support.
|
|
- `.github/workflows/firmware-build.yml` — new GitHub Actions workflow using the same representative build script as local development.
|
|
- `.gitignore` — ignore generated `out/` and local PlatformIO/cache artifacts if needed.
|
|
- `README.md` — add the local representative build command and output locations.
|
|
|
|
## Ordered Implementation Checklist
|
|
1. Add output ignores for wrapper-level generated build artifacts.
|
|
2. Implement `scripts/parse-size-report.py` with ANSI stripping, PlatformIO RAM/flash line parsing, artifact byte discovery, deterministic JSON output, and optional `--baseline` / `--compare <json>` arguments.
|
|
3. Implement `scripts/build-representative.sh` with `--help`, `--baseline`, `--compare <baseline-json>`, PlatformIO availability checks, patch application, per-env `build.sh build-firmware` invocation, per-env log capture, artifact copying, and parser invocation.
|
|
4. Ensure `build-representative.sh` uses `REPRESENTATIVE_ENVS` from `scripts/meshcore-env.sh`, sets a default `FIRMWARE_VERSION` when absent, and preserves each env result rather than hiding failures.
|
|
5. Add `.github/workflows/firmware-build.yml` to check out submodules, install Python 3.11 and PlatformIO, run `bash scripts/build-representative.sh --baseline`, and upload `out/size` plus `out/firmware` artifacts.
|
|
6. Update `README.md` with the representative build command and generated output paths.
|
|
7. Run shell syntax and Python compile checks, then run script help and the parser against a small synthetic log fixture without requiring PlatformIO.
|
|
8. If PlatformIO is available locally, run the full baseline build; otherwise record that full build verification is deferred to CI or a local PlatformIO install.
|
|
|
|
## Interfaces and Data Contracts
|
|
- `scripts/build-representative.sh [--baseline|--compare <baseline-json>]` builds all envs from `REPRESENTATIVE_ENVS` and writes outputs under wrapper-level `out/`.
|
|
- `scripts/build-representative.sh --help` prints usage and exits successfully without requiring PlatformIO.
|
|
- `scripts/parse-size-report.py --logs <log-dir> --artifacts <artifact-dir> [--baseline|--compare <baseline-json>] [--output <json>]` emits JSON containing:
|
|
- `mode`
|
|
- `generated_at`
|
|
- `environments[]`
|
|
- per-env `env`, `ram_used`, `ram_total`, `flash_used`, `flash_total`, `artifact_bytes`, `log`, `metrics_found`, and optional `delta`
|
|
- Missing RAM/flash metrics are represented as `null` and `metrics_found: false`; the parser must not invent successful measurements.
|
|
- CI must use the same local scripts instead of duplicating build logic.
|
|
|
|
## Verification Plan
|
|
- Automated:
|
|
- `bash -n scripts/build-representative.sh scripts/meshcore-env.sh`
|
|
- `python3 -m py_compile scripts/parse-size-report.py`
|
|
- `bash scripts/build-representative.sh --help`
|
|
- Run `scripts/parse-size-report.py` against a synthetic log/artifact directory.
|
|
- If PlatformIO is installed: `bash scripts/build-representative.sh --baseline`
|
|
- Manual:
|
|
- Review generated JSON shape from the synthetic parser run.
|
|
- Confirm workflow env list comes from the wrapper script, not a duplicated matrix.
|
|
- Regression:
|
|
- `bash scripts/apply-patches.sh` still succeeds with an empty patch queue.
|
|
- Step 1 patch scripts remain unchanged in behavior.
|
|
|
|
## Stop Conditions
|
|
- Pause if upstream build env names differ from the planned four representative environments.
|
|
- Pause if implementing baseline comparison would require committing generated firmware artifacts.
|
|
- Pause if local PlatformIO installation or firmware build requires destructive cleanup outside wrapper-level `out/` or upstream `.pio` build directories.
|