# Rt Claw Build

> Use when building rt-claw, choosing a platform target, running QEMU, flashing hardware, or debugging C/Meson/native build failures.

- Skill: `zevorn/rt-claw-build` (Agent Skill)
- Install (CLI): `npx skillmds add zevorn/rt-claw-build`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zevorn/rt-claw-build/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: zevorn (https://skillmd.com/u/zevorn)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/zevorn/rt-claw-build

---


# rt-claw Build

Use the repository `Makefile` before inventing ad hoc commands. Meson builds
the platform-independent libraries; each platform target then uses its native
build system when needed.

## Quick Commands

| Task | Command |
|------|---------|
| Linux native build | `make build-linux` |
| Linux native run | `make run-linux` |
| Unit tests on Linux | `make test-unit-linux` |
| ESP32-C3 QEMU build | `make build-esp32c3-qemu` |
| ESP32-C3 QEMU run | `make run-esp32c3-qemu` |
| ESP32-C3 devkit build | `make build-esp32c3-devkit` |
| ESP32-C3 xiaozhi-xmini build | `make build-esp32c3-xiaozhi-xmini` |
| ESP32-C3 xiaozhi-xmini flash | `make flash-esp32c3-xiaozhi-xmini` |
| ESP32-S3 QEMU build | `make build-esp32s3-qemu` |
| ESP32-S3 hardware build | `make build-esp32s3` |
| ESP32-S3 hardware flash | `make flash-esp32s3` |
| vexpress-a9 QEMU build | `make vexpress-a9-qemu` |
| Zynq-A9 QEMU build | `make build-zynq-a9-qemu` |
| Zephyr Cortex-M3 QEMU build | `make build-zephyr-cortex-m3-qemu` |
| Zephyr Cortex-A9 QEMU build | `make build-zephyr-cortex-a9-qemu` |
| Style check | `scripts/check-patch.sh --staged` |

## Run Options

- Pass `GDB=1` to QEMU run targets to start in debug mode on port 1234.
- Pass `GRAPHICS=1` to ESP32 QEMU run targets when an LCD window is needed.
- Real hardware targets require the board to be connected before flash or
  monitor commands run.

## Target Selection

1. Use the platform named by the user.
2. If no platform is named, inspect changed paths:
   - `platform/linux/`, `osal/linux/`, or unit tests -> `make build-linux`
   - `platform/esp32c3/` or Espressif C3 drivers -> `make build-esp32c3-qemu`
   - `platform/esp32s3/` or shared Espressif changes -> `make build-esp32s3-qemu`
   - `platform/vexpress-a9/` or `osal/rtthread/` -> `make vexpress-a9-qemu`
   - `platform/zynq-a9/` or `osal/freertos/` -> `make build-zynq-a9-qemu`
   - `platform/zephyr/` or `osal/zephyr/` -> a Zephyr QEMU build target
3. Check branch names for platform hints such as `esp32c3`, `esp32s3`,
   `vexpress`, `zynq`, or `zephyr`.
4. If ambiguous, use `make build-linux` for the fastest compile check.

## Workflow

1. Confirm branch and worktree with `git status -sb`.
2. Read `CLAUDE.md` for current platform commands before changing a command.
3. Run the narrowest useful build while iterating.
4. Run `scripts/check-patch.sh --staged` before committing staged C changes.
5. For PR submission, build at least one affected platform. Broaden to more
   platforms when changing shared `claw/`, `include/`, `osal/`, `drivers/`, or
   build-system files.

## Failure Handling

- Preserve the first compiler or linker error; later failures may be follow-on
  noise.
- Report style failures from `scripts/check-patch.sh --staged`, but do not
  hide the build result behind style output.
- Check Meson source lists when a symbol is undefined or a new file is not
  compiled.
- Check include order and OSAL boundaries before adding headers.
- Do not edit unrelated platforms just because a matrix build visits them.
- Keep `build/` artifacts out of commits.