From ae8b48c85ac719cb296c09974625242af4b8e750 Mon Sep 17 00:00:00 2001 From: QIU SHENGMING Date: Thu, 1 Oct 2026 15:12:45 +0800 Subject: [PATCH] Run anywhere: no author paths left, and CI that proves it tools/run_tests.sh defaults QEMU_SRC to a sibling of the checkout, which is where setup_qemu.sh puts it; the two defaults disagreed, so a fresh clone rebuilt nothing and reported a build that was not there. The interpreter list was also reading an empty $PY. tools/test_bk4819_readback.sh was the last test with the author's paths, and the only one that could not run elsewhere. It now takes QEMU, GDB and ELF from the environment or PATH like the python tests, skips with a reason when one is missing, and says so on a platform whose QEMU cannot make the unix socket it uses. tools/check_docs.py points UVK5_FW_DIR at a sibling and skips the file:line checks, with a message, when there is no firmware tree -- a fresh clone used to see thirteen failures it could do nothing about. Added .github/workflows/unit.yml (the fast half of run_tests.sh on every push and PR), requirements-dev.txt for the one pip dependency, and a Dockerfile. Flask is not always installed, so test_webui now skips through setUpModule rather than erroring. --- .github/workflows/unit.yml | 24 ++++++++++++++++++ CONTRIBUTING.md | 11 ++++++++ Dockerfile | 28 +++++++++++++++++++++ README.md | 19 ++++++++++++++ README.zh-CN.md | 16 ++++++++++++ requirements-dev.txt | 3 +++ tools/check_docs.py | 11 +++++++- tools/gpio_watch.py | 9 ++++++- tools/press_and_shot.sh | 2 +- tools/run_tests.sh | 7 ++++-- tools/test_bk4819_readback.sh | 47 ++++++++++++++++++++++++++--------- tools/test_webui.py | 17 ++++++++++++- 12 files changed, 176 insertions(+), 18 deletions(-) create mode 100644 .github/workflows/unit.yml create mode 100644 Dockerfile create mode 100644 requirements-dev.txt diff --git a/.github/workflows/unit.yml b/.github/workflows/unit.yml new file mode 100644 index 0000000..432e258 --- /dev/null +++ b/.github/workflows/unit.yml @@ -0,0 +1,24 @@ +name: unit tests + +# The fast half of tools/run_tests.sh: the test_uvk5_*.py unit tests plus check_docs.py. +# It needs no emulator, no firmware and no QEMU build, so it runs on a bare runner -- +# which is the point. Before this existed, nothing ran on anyone else's machine, and the +# suite quietly grew machine-specific defaults that a fresh clone could not satisfy. + +on: + push: + branches: [master] + pull_request: + +jobs: + unit: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.11" + - name: dependencies + run: python -m pip install -r requirements-dev.txt + - name: unit tests, and the docs against the code + run: bash tools/run_tests.sh -q diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 397b30c..b9c8231 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,6 +7,7 @@ Short version: build it, run the tests, and do not commit firmware or radio data QEMU_SRC=~/src/qemu-7.2 bash tools/setup_qemu.sh # patch a QEMU tree and build it python3 tools/fetch_firmware.py # a release image to run python3 tools/make_flash.py # the flash image it reads settings from + pip install -r requirements-dev.txt # flask, for the web UI tests bash tools/run_tests.sh -q # fast; no emulator needed bash tools/run_tests.sh # everything; needs the tree above @@ -24,8 +25,18 @@ works where the platform has unix sockets and TCP where it does not, and `tools/uvk5_testenv.py` finds a QEMU, a firmware and a gdb, skipping with a reason when one is absent. Use them rather than hardcoding a path or a socket family. +## What runs automatically + +`.github/workflows/unit.yml` runs `tools/run_tests.sh -q` on every push and pull request -- +the unit tests and the documentation check, which need nothing but Python. If you add a +test that needs an emulator, it belongs in the slow half of the runner, not here; if you +add one that needs nothing, make sure it is picked up by the `-q` path so CI covers it. + +`Dockerfile` gives you the same environment locally. + ## What not to commit + - **Firmware of any kind**, including released images, localised builds and bootloader dumps. `tools/fetch_firmware.py` fetches what a test needs into `assets/firmware/`, which is ignored. diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..973415a --- /dev/null +++ b/Dockerfile @@ -0,0 +1,28 @@ +# A box that can run the suite, and build the machine if you give it a QEMU tree. +# +# docker build -t uvk5 . && docker run --rm uvk5 # unit tests +# docker build -t uvk5 . && docker run --rm uvk5 bash tools/run_tests.sh +# +# The emulator tests need a patched QEMU build. Fetch a QEMU 7.2 tree first and mount it, +# because tools/setup_qemu.sh patches a tree rather than downloading one: +# +# docker run --rm -v /path/to/qemu-7.2:/qemu-7.2 -e QEMU_SRC=/qemu-7.2 uvk5 \ +# bash -lc 'bash tools/setup_qemu.sh && bash tools/run_tests.sh' + +FROM ubuntu:24.04 + +ENV DEBIAN_FRONTEND=noninteractive +RUN apt-get update && apt-get install -y --no-install-recommends \ + bash build-essential git ca-certificates curl \ + ninja-build pkg-config python3 \ + libglib2.0-dev libpixman-1-dev libfdt-dev zlib1g-dev \ + && rm -rf /var/lib/apt/lists/* + +WORKDIR /src +COPY . /src + +# Fast suite on build: it must pass without a QEMU tree, because that is what a +# contributor has on their first day. +RUN bash tools/run_tests.sh -q + +CMD ["bash", "tools/run_tests.sh"] diff --git a/README.md b/README.md index 056da2f..e6227bf 100644 --- a/README.md +++ b/README.md @@ -118,6 +118,25 @@ keypresses silently stop working. Run the test after touching that code; kept because they are quick to reach for, not because they are polished) harness/, stubs/, shim/, tests/ host build of the CW timing chain (stage A) +### Running it elsewhere: CI and a container + +`.github/workflows/unit.yml` installs `requirements-dev.txt` (flask) and runs `tools/run_tests.sh -q` +on every push and pull request: +the `test_uvk5_*.py` unit tests plus `check_docs.py`, which need no emulator, no firmware and +no QEMU build. That path is what keeps the suite honest on a machine that is not this one -- +before it existed, the runner's default paths were the author's, and a fresh clone could not +run anything without editing it. + +`Dockerfile` builds a box with the same tooling, and can run the emulator tests if you give +it a QEMU tree, because `tools/setup_qemu.sh` patches a tree rather than downloading one: + + docker build -t uvk5 . && docker run --rm uvk5 # unit tests + docker run --rm -v /path/to/qemu-7.2:/qemu-7.2 -e QEMU_SRC=/qemu-7.2 uvk5 \ + bash -lc 'bash tools/setup_qemu.sh && bash tools/run_tests.sh' + +The `file:line` checks in `check_docs.py` need the firmware sources, which are not in this +repository. Without them the checker skips those checks and says so; point `UVK5_FW_DIR` at +a tree to have them run. ## What is not in this repository Two things are deliberately absent, and neither should be committed: diff --git a/README.zh-CN.md b/README.zh-CN.md index 5e5b8e4..504ed16 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -106,6 +106,22 @@ VFO 重算了状态。在真机上你只看到"什么都没发生"，在这里 留着是因为随手就能用，不是因为它们打磨过） harness/, stubs/, shim/, tests/ CW 时序链的宿主机构建（阶段 A） +### 在别的机器上跑：CI 与容器 + +`.github/workflows/unit.yml` 会安装 `requirements-dev.txt`（flask）并跑 `tools/run_tests.sh -q`：即 +`test_uvk5_*.py` 单元测试加上 `check_docs.py`，它们不需要模拟器、不需要固件、也不需要 +编译 QEMU。这条路才是让套件在**别人的机器**上保持诚实的东西——在它出现之前，runner 的默认 +路径是作者本人的，新克隆不先改文件就什么也跑不了。 + +`Dockerfile` 构建同样的工具环境；若把 QEMU 源码树挂进去，还能跑模拟器测试（因为 +`tools/setup_qemu.sh` 是给已有源码树打补丁，而不是下载一份）： + + docker build -t uvk5 . && docker run --rm uvk5 # 单元测试 + docker run --rm -v /path/to/qemu-7.2:/qemu-7.2 -e QEMU_SRC=/qemu-7.2 uvk5 \ + bash -lc 'bash tools/setup_qemu.sh && bash tools/run_tests.sh' + +`check_docs.py` 里的 `file:line` 检查需要固件源码，而它不在本仓库里。没有它时检查器会**跳过** +那部分并明确说明；把 `UVK5_FW_DIR` 指向一份源码树即可让它生效。 ## 仓库里没有什么 有两类东西是刻意不放的，也都不应该提交： diff --git a/requirements-dev.txt b/requirements-dev.txt new file mode 100644 index 0000000..1a6df3b --- /dev/null +++ b/requirements-dev.txt @@ -0,0 +1,3 @@ +# What the fast half of tools/run_tests.sh needs beyond the standard library. +# The emulator half needs nothing from pip; it needs a QEMU build (tools/setup_qemu.sh). +flask diff --git a/tools/check_docs.py b/tools/check_docs.py index 0a95731..b277caf 100755 --- a/tools/check_docs.py +++ b/tools/check_docs.py @@ -36,7 +36,11 @@ SIM = pathlib.Path(__file__).resolve().parent.parent # Where the firmware sources are. Override when the tree is not at the default # path -- without that the checker cannot run anywhere but the machine it was # written on, and the file:line checks are the ones that catch drifting prose. -FW = pathlib.Path(os.environ.get("UVK5_FW_DIR", "/root/uvk5-port/uvk5-sat/App")) +# Firmware sources are not in this repository (see the README), so the default is a +# sibling of this checkout and the checks that need the tree are skipped without it. +# A fresh clone used to see thirteen failures it could do nothing about. +_fw_env = os.environ.get("UVK5_FW_DIR") +FW = pathlib.Path(_fw_env) if _fw_env else (SIM.parent / "uvk5-port" / "uvk5-sat" / "App") PAIRS = [ ("README.md", "README.zh-CN.md"), @@ -185,6 +189,11 @@ def check_documented_flags(): def check_line_refs(): print("firmware file:line references must point at what the docs claim") + if not FW.is_dir(): + print(f" SKIP no firmware tree at {FW}; set UVK5_FW_DIR to check " + f"{len(LINE_REFS)} file:line references") + return + for (name, line), needle in sorted(LINE_REFS.items()): path = resolve_fw(name) if path is None: diff --git a/tools/gpio_watch.py b/tools/gpio_watch.py index 6e165cb..3c984a6 100644 --- a/tools/gpio_watch.py +++ b/tools/gpio_watch.py @@ -24,7 +24,14 @@ QMP_SOCKET = "/tmp/uvk5-qmp.sock" GPIOB_BASE = 0x50000400 GPIO_IDR = 0x10 GPIO_ODR = 0x14 -ELF = "/root/uvk5-port/uvk5-sat/build/CW/nr7y.cw.elf" +ELF = os.environ.get("ELF") or os.environ.get("UVK5_FIRMWARE") or "" +if not ELF: # the same search order as tools/uvk5_testenv.py + import glob as _glob + for _pat in ("assets/firmware/*.elf", "work/*.elf"): + _hits = sorted(_glob.glob(str(pathlib.Path(__file__).resolve().parent.parent / _pat))) + if _hits: + ELF = _hits[0] + break class Qmp: diff --git a/tools/press_and_shot.sh b/tools/press_and_shot.sh index ff46df7..fd77317 100755 --- a/tools/press_and_shot.sh +++ b/tools/press_and_shot.sh @@ -7,7 +7,7 @@ set -uo pipefail TOOLS="$(cd "$(dirname "$0")" && pwd)" -OUT="${OUT:-/root/vm_screen.png}" +OUT="${OUT:-$PWD/vm_screen.png}" HOLD="${HOLD:-3}" SETTLE="${SETTLE:-3}" diff --git a/tools/run_tests.sh b/tools/run_tests.sh index 08ad822..55d6f13 100755 --- a/tools/run_tests.sh +++ b/tools/run_tests.sh @@ -18,7 +18,10 @@ set -u HERE=$(cd "$(dirname "$0")" && pwd) SIM=$(dirname "$HERE") -QEMU_SRC=${QEMU_SRC:-/root/qemu-build/qemu-7.2+dfsg} +# A sibling of this checkout by default, which is where tools/setup_qemu.sh puts it. +# The two defaults have to agree: they disagreed once, so a fresh clone rebuilt nothing +# and reported a build that was not there. +QEMU_SRC=${QEMU_SRC:-$SIM/../qemu-7.2} # One interpreter name, resolved once. This script used to spell $PY on every # line, which is a Windows problem (there is a python, not a python3) and a @@ -26,7 +29,7 @@ QEMU_SRC=${QEMU_SRC:-/root/qemu-build/qemu-7.2+dfsg} # from a runner that passes, which is the failure mode this script exists to avoid. PY=${PYTHON:-} if [ -z "$PY" ]; then - for candidate in $PY python; do + for candidate in python3 python; do if command -v "$candidate" >/dev/null 2>&1; then PY=$candidate; break; fi done fi diff --git a/tools/test_bk4819_readback.sh b/tools/test_bk4819_readback.sh index 0e7938c..84f6fac 100755 --- a/tools/test_bk4819_readback.sh +++ b/tools/test_bk4819_readback.sh @@ -13,24 +13,44 @@ # about alignment, not interrupt semantics. set -u -QEMU=${QEMU:-/root/qemu-build/qemu-7.2+dfsg/build/qemu-system-arm} -ELF=${ELF:-/root/uvk5-port/uvk5-sat/build/CW/nr7y.cw.elf} HERE=$(cd "$(dirname "$0")" && pwd) SIM=$(dirname "$HERE") SRC="$SIM/qemu/py32f071.c" -QSRC=/root/qemu-build/qemu-7.2+dfsg/hw/arm/py32f071.c + +# Same rules as the python tests (tools/uvk5_testenv.py): QEMU, GDB and ELF come from the +# environment, then PATH, then the checkout -- and a missing one is a SKIP with a reason +# rather than a failure. These were the author's home paths, which is why this was the one +# test that could not run anywhere else. +QEMU=${QEMU:-$(command -v qemu-system-arm || true)} +GDB=${GDB:-$(command -v gdb-multiarch || command -v arm-none-eabi-gdb || true)} +QEMU_SRC=${QEMU_SRC:-$SIM/../qemu-7.2} +QSRC="$QEMU_SRC/hw/arm/py32f071.c" +if [ -z "${ELF:-}" ]; then + for cand in "$SIM"/assets/firmware/*.elf "$SIM"/work/*.elf; do + [ -e "$cand" ] && ELF=$cand + done +fi +for t in "$QEMU" "$GDB" "${ELF:-}"; do + [ -n "$t" ] && [ -e "$t" ] || { + echo "SKIP missing ${t:-a prerequisite} (set QEMU, GDB and ELF; see the README Quick start)" + exit 0 + } +done + +# QMP travels over a unix socket here and a Windows QEMU cannot create one: say so rather +# than letting the launch fail and calling it a firmware problem. +if ! python3 -c "import socket; socket.socket(socket.AF_UNIX)" 2>/dev/null; then + echo "SKIP no unix sockets on this platform, so -qmp unix: is unavailable" + exit 0 +fi SEED=0x1248 PORT=1259 SOCK=/tmp/bk-readback.sock IMG=/tmp/bk-readback.img -for t in "$QEMU" "$ELF"; do - [ -e "$t" ] || { echo "SKIP missing $t"; exit 0; } -done - cp "$SRC" /tmp/bk-readback-orig.c -trap 'cp /tmp/bk-readback-orig.c "$SRC"; cp "$SRC" "$QSRC" 2>/dev/null || true; rm -f "$IMG" "$SOCK"' EXIT +trap 'cp /tmp/bk-readback-orig.c "$SRC"; [ -d "$QEMU_SRC/build" ] && cp "$SRC" "$QSRC" 2>/dev/null; rm -f "$IMG" "$SOCK" "$GDBFILE" 2>/dev/null' EXIT python3 - "$SRC" "$SEED" <<'PY' import sys @@ -42,8 +62,10 @@ if needle not in s: open(src, "w", encoding="utf-8").write(s.replace(needle, f"{needle}\n s->regs[0x0C] = {seed};", 1)) PY -cp "$SRC" "$QSRC" -if (cd /root/qemu-build/qemu-7.2+dfsg/build && ninja qemu-system-arm 2>&1 \ +if [ -d "$QEMU_SRC/build" ]; then + cp "$SRC" "$QSRC" +fi +if [ -d "$QEMU_SRC/build" ] && (cd "$QEMU_SRC/build" && ninja qemu-system-arm 2>&1 \ | grep -qE 'FAILED|error:'); then echo "FAIL build error" exit 1 @@ -59,7 +81,8 @@ sleep 24 # A command file, not a pile of -ex flags: a `commands` block cannot survive being # passed that way, and the failure looks exactly like "the firmware never read it". -cat > /tmp/bk-readback.gdb < "$GDBFILE" </dev/null \ +GOT=$(timeout 45 "$GDB" -batch -x "$GDBFILE" "$ELF" 2>/dev/null \ | grep -oE 'GOT 0x[0-9A-Fa-f]{4}' | head -1) kill $QPID 2>/dev/null || true diff --git a/tools/test_webui.py b/tools/test_webui.py index 6af0e09..b6766b6 100644 --- a/tools/test_webui.py +++ b/tools/test_webui.py @@ -10,7 +10,22 @@ import time import unittest import uvk5_image -import webui +# Flask is the one thing the fast suite needs from pip, so it is not always there. +# A missing dependency is a skip with a reason, not a failure -- but at *module* level +# raising SkipTest is reported as an error rather than a skip, so the check goes in +# setUpModule(), which unittest treats as skipping the whole file. +webui = None +try: + import webui # noqa: F811 +except ImportError: + pass + + +def setUpModule(): + if webui is None: + raise unittest.SkipTest( + "the web UI tests need flask; install it with " + "pip install -r requirements-dev.txt") from uvk5_supervisor import FlashSlot