SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsfw-toolchain

fw-toolchain

Deployment & operations

View repository

Updated 10-15 21:48

About this skill

Firmware Cross-Toolchain (Hosting-First and Version Anchoring)

Core stance: prioritize letting the platform build system host the toolchain; do not hand-assemble the sysroot. Toolchain version drift = headers/libc/linker mismatch with the target environment, and the artifact's behavior on the device is unexplainable and non-reproducible. Each of the three major toolchain families has a "host": first ask "who hosts it", then discuss how to use it.

Determine Task Type

  1. OpenWrt userspace cross-compilation(e.g., compiling Rust/static small tools for aarch64 devices) → Workflow A.
  2. ESP32 toolchain（xtensa-esp-elf / riscv32-esp-elf）→ Workflow B：Do not install manually, IDF's built-in toolchain management hosts it; engineering issues are handed off to esp32-idf。
  3. OpenWrt kernel/image build toolchain → hosted by buildroot/IB; build requirements are handed off entirely to openwrt-image-build。
  4. Version mismatch troubleshooting / reproducible builds → Workflow C + version-pinning。

Prerequisites / Preflight

uname -m                                                    # 宿主架构（IB 与交叉工具链官方形态多为 Linux x86_64）
command -v aarch64-linux-gnu-gcc || true                    # 宿主交叉链接器在不在
rustup target list --installed 2>/dev/null | grep aarch64 || true
idf.py --version 2>/dev/null || echo "IDF not in PATH"      # ESP 链路：IDF 托管是否就绪

First distinguish the three version axes (do not mix them up)：

Version axis How to confirm Determines what
Local toolchain Measured by the commands above What the current machine can compile
Project lock rust-toolchain.toml / dependencies.lock / IB pinned-version tarball Actual project behavior and team consistency
Upstream latest Official release page (baseline date see Offline Baseline) Upgrade evaluation reference,not automatically adopted

Offline Baseline

  • OpenWrt baseline = 25.12.5(read through 2026-09-02, not automatically updated); the official IB release form is Linux-x86_64 (.tar.zst, older versions .tar.xz）。
  • ESP-IDF baseline = v6.1(read through 2026-09-02, not automatically updated); the toolchain is hosted by the IDF distribution's install/activate tooling.
  • For behavior changes in later versions, defer to official sources; do not assert from memory.

Contracts (Hosting Contracts)

  1. Hosting matrix (the first contract of this Skill): the toolchain of each chain has a unique host—OpenWrt userspace = host cross-toolchain + language-layer target; ESP32 = IDF's built-in toolchain management; OpenWrt kernel/image = buildroot/IB. See each item in hosting-matrix。
  2. Hand-assembling the sysroot is prohibited: manually cobbling together "header directory + arbitrary cross gcc + libc copied from elsewhere" is a version-drift machine; missing dependencies should go back to the host (IB's sysroot is provided by IB itself, IDF's libc is provided by IDF).
  3. Manually installing the ESP toolchain by bypassing IDF is prohibited: the xtensa/riscv toolchain installed via apt/brew does not match the project's IDF; at best the configuration script fails, at worst the produced image behavior is unexplainable.
  4. Anchor versions into version control：IDF=dependencies.lock + pin the IDF checkout version; OpenWrt = pinned-version IB tarball + SOURCE_DATE_EPOCH; Rust/musl = pin rust-toolchain.toml + target. See version-pinning。
  5. Artifact architecture must be empirically verified (file output), not based on "it compiled so it must be right".

Capability Boundaries + Hand-off

Not done: project skeleton (esp32-idf), image build itself (openwrt-image-build), boardless verification (fw-emulation), real-device acceptance (fw-hil-testing), release naming/checksums (fw-release-gate).

User Intent Skill
ESP-IDF project creation/build/flashing (including toolchain activation details) esp32-idf
OpenWrt image build / IB usage / FILES injection openwrt-image-build
Fabricated image starts first for validation without a board fw-emulation
Artifact accepted on real hardware in the loop fw-hil-testing
Artifact naming / checksum / release gate fw-release-gate

Workflow A — Cross-compiling an aarch64 static binary (OpenWrt user space, including the macOS scenario)

  1. Choose the host: the mode is based on the Linux host(both the official cross packages and the IB form are like this). Do not force macOS/Windows on the host—use Docker/Linux containersto run the same mode (consistent with IB's macOS usage).
  2. Install the host cross linker (inside the Linux container/host): the distribution's cross gcc package (e.g. Ubuntu apt-get install gcc-aarch64-linux-gnu）；Do nothand-build a sysroot for it.
  3. Add the language-layer target: for Rust projects rustup target add aarch64-unknown-linux-musl, and lock the target and toolchain into rust-toolchain.toml(the mode has been verified in a real project: the TinyNAS instance produced an aarch64 static binary with the combination of "rustup target + host cross gcc"—cited only as a mode reference).
  4. Linker wiring: in .cargo/config.toml , specify the linker for the target (pointing to the cross gcc from step 2). Note the boundary: pure Rust dependencies usually work with musl self-contained linking; once C dependencies are introduced, a cross toolchain matching the target libc is required, and the link configuration must be based on actual testing (verified at runtime).
  5. Artifact verification：
file target/aarch64-unknown-linux-musl/release/<bin>
# 期望：ELF 64-bit ARM aarch64 ... statically linked
  1. It only counts if the static binary is thrown onto the target device and runs: no board → fw-emulation(boot smoke test/host unit test); with board → fw-hil-testing。

Workflow B — Correction of the "install xtensa gcc" request (handoff stance)

The user says "compiling ESP32 reports xtensa-esp-elf-gcc not found, just install one with apt"—correct it, do not comply：

  1. The ESP toolchain is managed by ESP-IDF: install it all at once with its installation tool along with the IDF distribution package (versions strictly matched to IDF), and each terminal enters the environment via IDF's activation script (the export family)—versions installed manually via apt/brew are not controlled by IDF and constitute version drift.
  2. The fix path = fix the IDF environment itself: confirm that idf.py --version is consistent with the project's locked IDF, and re-run IDF's installation/activation process.
  3. Project-side details (installation process, activation, CI environment) are handed off to esp32-idf, and this Skill does not repeat its steps.

Workflow C — Troubleshooting toolchain version inconsistency

  1. Test each of the three version axes one by one (Preflight command) to locate which axis has drifted.
  2. Check whether the anchoring files are committed and followed:rust-toolchain.toml / dependencies.lock / IB version pin / SOURCE_DATE_EPOCH(against the command list in version-pinning ).
  3. The fix direction is always "align to the project's locked axis", not "everyone upgrades to latest".
  4. After fixing, rebuild the artifact and compare file/sha256; artifact release verification → fw-release-gate。

Validation Gates

  1. The three version axes have written records (locally measured values + project lock file paths + baseline date).
  2. Artifact file output is consistent with the target architecture/link form (aarch64 + statically linked, etc., documented verbatim).
  3. No traces of a manual sysroot: the build command contains no header/libc directories pointing to something hastily assembled.
  4. Two machines in the team build artifacts with identical sha256 per the lockfile (reproducibility spot check).
  5. The conclusion "it can run on the device" must have real-device evidence (fw-hil-testing), otherwise mark it Build Verification Only。

Pitfalls

  1. Do nothand-assemble a sysroot—if headers/libs are missing, ask the maintainer; do not piece things together from three directories.
  2. Do notmanually install the xtensa/riscv ESP toolchain via apt/brew—anything outside IDF hosting is drift.
  3. Do notmix the three version axes—"my machine has latest" cannot be the basis for project builds.
  4. Do notuse an IB directory without a version pin—only a fixed-version tarball + SOURCE_DATE_EPOCH is reproducible.
  5. Do notforce Linux cross-compilation on a macOS host—enter a Linux container and use the baseline mode.
  6. Do notcite an undated "latest version number"—always include "as of 2026-09-02" and note to verify at runtime.

Official Sources

Privacy

This Skill only operates the local build environment and official download sources; it does not collect or upload user data or credentials. Sensitive information such as internal source addresses and mirror site credentials must not be written into build scripts or CI configurations.