kodeOS internals

Test pipeline

The checks each repository carries as scripts, run on a computer before a change is merged: what each one runs, which risk it covers, and the rule that merges a change.

What it is

The checks of kodeOS, the SDK and the C5's firmware are scripts in each repository. Nothing runs them for you: whoever opens a pull request runs them on a computer before asking for the merge, and the reviewer runs the ones the change touches again. A green result is a terminal that ends in ok or all passing, not a mark on GitHub.

This page lists the scripts per repository, which risk each one covers and the rule that merges a change. The release, built by hand from a clean clone of its tag, is on internals/release-pipeline.

How it is connected

flowchart LR
change["a change on a branch"] --> fast["the fast checks<br/>no ESP-IDF"]
fast --> host["the host suites<br/>ESP-IDF v6.1"]
host --> fw["the firmware build<br/>and its four checks"]
fw --> pr["pull request"]
pr --> review["one approval"]
review --> main["main"]
class change ext
class main store

The checks run from the order of their cost: the fast ones first, so a broken rule is found in seconds and nobody waits for a firmware build to hear about it.

kodeOS runs its checks on the SDK as pinned by the sdk submodule. A suite that passed in the SDK says nothing about the commit kodeOS builds from, so the submodule must be where the change leaves it: git submodule update --init --recursive before you trust a result.

Specifications

kodeOS

From the root of the repository, with ESP-IDF v6.1 loaded (. ~/.espressif/v6.1/esp-idf/export.sh).

Details of the build's checks:

tools/check_todo_refs.sh reads only the lines a change adds. A TODO, FIXME, HACK or XXX there must name its issue right after it, as in TODO(#42) or FIXME kodediy/kode-sdk#7.

tools/check_starts.sh reads the archives a build made. It fails when an Active Object's start is not in the object that holds its queue: in an app, kode_init() names each optional start weakly, so a door linked without its start would post to an AO with no queue and loop the boot. --all also asks that every AO is in the image; --absent asks that the named ones are not.

The SDK

From the root of the SDK repository. The first four steps need no ESP-IDF.

A variant is the file tests/target/sdkconfig.<variant> on top of the defaults, named by KODE_TARGET_VARIANT. A build directory holds one variant and refuses another, so rm -rf build between two. In tests/target, with ESP-IDF v6.1 loaded:

After each build, ../../tools/check_ram.sh build/kode_target.elf <budget> and ../../tools/check_starts.sh build <rule>. The twelve owners a minimal app never uses are AO_Radio, AO_Net, AO_Display, AO_Storage, AO_AppMgr, AO_Ir, AO_Nfc, AO_Rfid, AO_Audio, AO_Imu, AO_Haptic and AO_Touch.

tests/target links every SDK component with every option on, except the camera, so its static use of internal RAM is what the SDK costs an app before the app adds a line. check_example_pins.sh checks that every example's main/idf_component.yml and the SDK's README name the same SDK version, and that it is not older than the newest v* tag. An example builds against the tag it pins, not against the tree it sits in. In a shallow clone with no tags it checks only the first rule and says so.

The C5's firmware

From the root of kode_slave_c5 (in kodeOS, sdk/c5/).

The closed image needs ESP-IDF v6.1: the bootloader of 6.0.2 revokes the free key digest slots on its first boot, whatever the configuration says.

What is tested where

What no script covers

How a change reaches main

The approval is where the checks are vouched for: the pull request says which of the steps above ran and how they ended, and the reviewer asks for any the change touches that it does not name. The rulesets of kodeOS and the SDK also list required status checks (static, host, firmware in kodeOS; host-tests, esp32p4, esp32p4 (nowifi) in the SDK). No workflow reports them, so every merge goes through the bypass of the main-approvers team.

The workflow files under .github/workflows/ stay in the three repositories, and GitHub Actions does not run them. They hold the same commands as the tables above, so they are also a written record of each check.

Gotchas

Example code

Run kodeOS's checks before you open a pull request, from the root of the repository.

1. Run tools/check_layers.sh. Every line reads ok and the exit status is 0.
2. Run tools/tool_tests.sh. It ends with tool tests, all passing.
3. Run KODE_REQUIRE_C5=1 sdk/tools/check_wire_twins.sh and sh sdk/c5/test/run.sh.
4. Load ESP-IDF v6.1 and run tools/host_tests.sh. It ends with cases across 6 suites, all passing.
5. Build with idf.py build, then run tools/check_os_size.sh build/kodeos.bin. It prints the image size against its ceiling.
6. Run sdk/tools/check_ram.sh build/kodeos.elf tools/ram_budget.txt and sdk/tools/check_starts.sh build --all.
7. Run sdk/tools/check_misra.sh build/compile_commands.json tools/misra_baseline.txt sdk/components components/kgui with the baseline's cppcheck version on your path.
8. If you added a TODO, run tools/check_todo_refs.sh BASE, where BASE is the commit your branch started from.
9. Run git status. The build left no change in a tracked file.

In the SDK

• tools: kodeOS's checks, with their tests in tools/tests.
• tools: the SDK's checks and the gates kodeOS calls from sdk/tools/.
• tests/target: the project that builds every component for the chip, with its variants and RAM budgets.