diff --git a/README.md b/README.md index d7a91bf..8ff9927 100644 --- a/README.md +++ b/README.md @@ -58,6 +58,7 @@ scenario tests (portal, OTA apply, display + touch, watchdog). | `drivers/` | hardened hardware-facing drivers: HAL seams, test harnesses | | `kernel/` | forward-port provenance and bring-up records (`patches/` is canonical) | | `tools/` | `config-lint` (static memory-map gates) and dev tooling | +| `build/vendor.manifest` | the third-party trees this platform builds against (LVGL, the vendor RV1106 SDK), pinned to exact commits; `build/fetch-vendor.sh` obtains and verifies them | | `docs/` | architecture, ADRs (`decisions/`), CI/CD | ## Architecture diff --git a/build/fetch-vendor.sh b/build/fetch-vendor.sh new file mode 100755 index 0000000..8392075 --- /dev/null +++ b/build/fetch-vendor.sh @@ -0,0 +1,88 @@ +#!/usr/bin/env bash +# Obtain (or verify) the third-party trees pinned in build/vendor.manifest. +# +# These trees are shared between worktrees and are far too large to live in git +# (the vendor SDK alone is 21 GB, and its host tools bake in absolute paths, so +# it must sit at ONE stable path anyway). What belongs in git is the answer to +# "which commit" -- that is the manifest, and this is the only thing that reads +# it. +# +# fetch-vendor.sh --check [DIR] report each tree's state; non-zero if any +# is missing or off its pin (default: check) +# fetch-vendor.sh --fetch [DIR] clone what is missing, then check +# +# DIR defaults to $WARDEN_VENDOR_DIR, else the conventional shared location +# alongside a flare-edge checkout. Nothing is ever moved or reset: a tree that +# has drifted is REPORTED, because a local change to a vendor tree is usually +# someone's debugging session, not something to silently throw away. +set -uo pipefail + +HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +MANIFEST="$HERE/vendor.manifest" +MODE="check" +DIR="" + +while [ $# -gt 0 ]; do + case "$1" in + --check) MODE="check"; shift ;; + --fetch) MODE="fetch"; shift ;; + -h|--help) sed -n '2,18p' "$0"; exit 0 ;; + *) DIR="$1"; shift ;; + esac +done + +[ -r "$MANIFEST" ] || { echo "FATAL: no manifest at $MANIFEST" >&2; exit 1; } +command -v git >/dev/null || { echo "FATAL: git not on PATH" >&2; exit 1; } + +if [ -z "$DIR" ]; then + DIR="${WARDEN_VENDOR_DIR:-$HOME/projects/scada/flare-edge}" +fi + +# Where each tree conventionally lives. lvgl sits under ui/ because that is the +# shared tree flare-edge worktrees symlink into (ui-src/lvgl). +tree_path() { + case "$1" in + lvgl) echo "$DIR/ui/lvgl" ;; + luckfox-pico) echo "$DIR/sdk" ;; + *) echo "$DIR/$1" ;; + esac +} + +rc=0 +while IFS=$'\t' read -r name url commit desc; do + case "$name" in ''|\#*) continue ;; esac + path="$(tree_path "$name")" + + # -e, not -d: a git worktree or submodule has a .git FILE, and lvgl is + # checked out as one here. + if [ ! -e "$path/.git" ]; then + if [ "$MODE" = "fetch" ]; then + echo "== cloning $name -> $path" + mkdir -p "$(dirname "$path")" + git clone --quiet "$url" "$path" || { echo " FAILED to clone $name" >&2; rc=1; continue; } + git -C "$path" checkout --quiet "$commit" || { echo " FAILED to check out $commit" >&2; rc=1; continue; } + else + echo "MISSING $name ($path)" + rc=1 + continue + fi + fi + + have="$(git -C "$path" rev-parse HEAD 2>/dev/null)" + if [ "$have" = "$commit" ]; then + # Local changes are reported but are NOT a failure. The vendor SDK is + # expected to carry them: tools/build-firmware.sh applies our sdk-patches + # series into that tree as part of every build, so a clean luckfox-pico + # checkout is the unusual state, not the healthy one. + dirty="" + [ -n "$(git -C "$path" status --porcelain 2>/dev/null | head -1)" ] && dirty=" (locally modified)" + echo "OK $name ${commit:0:12}$dirty" + else + echo "DRIFTED $name want ${commit:0:12} have ${have:0:12} ($path)" + echo " not reset automatically: check whether that is deliberate, then" + echo " either 'git -C $path checkout $commit' or update the manifest." + rc=1 + fi +done < "$MANIFEST" + +exit "$rc" diff --git a/build/vendor.manifest b/build/vendor.manifest new file mode 100644 index 0000000..59a9694 --- /dev/null +++ b/build/vendor.manifest @@ -0,0 +1,19 @@ +# Third-party trees this platform is built against, pinned to an exact commit. +# +# WHY A PIN AND NOT A COPY. Between them these are ~21 GB; the vendor SDK alone +# is 21 GB of build tree with absolute paths baked into its host tools. Copying +# that into git would make every clone of this repo unusable and would still not +# make the result reproducible. What makes a build reproducible is knowing +# EXACTLY which tree was used, and that is a commit id -- the same reasoning +# build/fetch-kernel-tarball.sh already applies to the kernel, where a sha256 +# pin stands in for vendoring 150 MB of tarball. +# +# So this file is the single place that answers "which LVGL, which vendor SDK", +# and fetch-vendor.sh is the only thing that acts on it. A checkout that has +# drifted off its pin is reported, never silently used. +# +# Format: nameurlcommitdescription +# Blank lines and lines starting with '#' are ignored. + +lvgl https://github.com/lvgl/lvgl.git 066d8db0b54819223357731f68961a90b3d785b4 LVGL v9.5.0-383-g066d8db0b: the UI toolkit warden-ui links against +luckfox-pico https://github.com/LuckfoxTECH/luckfox-pico.git 824b817f889c2cbff1d48fcdb18ab494a68f69d1 Vendor RV1106 SDK: buildroot userspace, U-Boot and the host packaging tools. Being replaced by this repo; still the source of the rootfs and the FIT/resource host tools.