From af55a9efb8f51096ab45768afc1edef1ab398305 Mon Sep 17 00:00:00 2001 From: David Montero Crespo Date: Tue, 25 Aug 2026 00:24:50 +0200 Subject: [PATCH] docs: stop sending readers to a release that no longer has the binaries The QEMU libraries left the public `qemu-prebuilt` release: they are GPL-2.0 derivatives of QEMU, and distributing one obliges us to hand the recipient the corresponding source, so binary and source now live in one place -- velxio.dev's gated endpoint, where the qemu-source- archive sits beside them. Six documents still pointed at the release. Two of them shipped runnable commands that now 404: the deploy-to-container curl pair in the WiFi notes, and the e2e README's claim about where CI gets its libraries (that workflow had in fact moved to the gated endpoint some time ago -- only the README was stale). Also corrects two things that were already wrong before today: QEMU_RELEASE_URL is documented with the release as its default, but Dockerfile.standalone defaults it to empty and reaches the binaries via VELXIO_LICENSE_KEY; and the asset inventory omitted the macOS, Windows and esp32s3_rev0_rom entries. --- docs/wiki/docker-infrastructure.md | 49 ++++++++++++------- .../wiki/esp32-cache-disable-runtime-crash.md | 9 ++-- docs/wiki/esp32-spi-display-performance.md | 5 +- docs/wiki/esp32-wifi-emulation-fixes.md | 19 +++++-- test/backend/e2e/README.md | 6 ++- 5 files changed, 59 insertions(+), 29 deletions(-) diff --git a/docs/wiki/docker-infrastructure.md b/docs/wiki/docker-infrastructure.md index 2985dd69..0a0d39fb 100644 --- a/docs/wiki/docker-infrastructure.md +++ b/docs/wiki/docker-infrastructure.md @@ -111,13 +111,21 @@ The Dockerfile uses **4 stages** to minimize final image size while building all **Base image:** `ubuntu:22.04` -**Purpose:** Downloads pre-built QEMU shared libraries (`.so`) and ESP32 ROM binary files from a GitHub Release. These are the QEMU emulation libraries built from the `qemu-lcgamboa` fork that enable ESP32 and ESP32-C3 simulation. +**Purpose:** Provides the pre-built QEMU shared libraries (`.so`) and ESP32 ROM binary files. These are the QEMU emulation libraries built from the `qemu-lcgamboa` fork that enable ESP32 and ESP32-C3 simulation. + +Three sources, tried in order: local files in `prebuilt/qemu/`, then velxio.dev's +gated endpoint when `VELXIO_LICENSE_KEY` is set, then a fail-fast error. They are +no longer published to a GitHub Release — see `docs/BUILD-QEMU.md`. ```dockerfile FROM ubuntu:22.04 AS qemu-provider ARG TARGETARCH -ARG QEMU_RELEASE_URL=https://github.com/davidmonterocrespo24/velxio/releases/download/qemu-prebuilt +ARG VELXIO_LICENSE_KEY= +ARG VELXIO_BINARY_BASE_URL=https://velxio.dev/api/pro/license/downloads +# Legacy escape hatch for forks proxying the binaries from their own +# mirror. Empty by default; when set it takes precedence. +ARG QEMU_RELEASE_URL= ``` **Key details:** @@ -349,21 +357,26 @@ The workflow has two jobs: - ROM files are only collected from the amd64 job (they're architecture-independent) - Uploads as GitHub Actions artifacts -2. **`upload-release`** (runs after both build jobs complete): - - Downloads both artifact archives - - Uploads all files to the `qemu-prebuilt` tag on the `davidmonterocrespo24/velxio` repository - - Uses `--clobber` to overwrite existing files if the release already exists - - Requires the `VELXIO_RELEASE_TOKEN` secret (a PAT with `contents:write` on the velxio repo) +2. **Publication is manual, and never to GitHub.** + Each platform job uploads its `out/` directory as a build artifact with a + 3-day retention. Collect the artifact and load each file into velxio.dev's + asset store with `scripts/upload-binary.sh`. -**Release structure at `github.com/davidmonterocrespo24/velxio/releases/tag/qemu-prebuilt`:** + The libraries are GPL-2.0 derivatives of QEMU. Distributing one obliges us to + hand the recipient the corresponding source, so binary and source live in one + place — the gated endpoint, where the `qemu-source-` archive sits + beside them. A public release with no source next to it is the shape that does + not comply. + +**Assets served from `velxio.dev/api/pro/license/downloads`:** ``` -libqemu-xtensa-amd64.so -libqemu-xtensa-arm64.so -libqemu-riscv32-amd64.so -libqemu-riscv32-arm64.so -esp32-v3-rom.bin -esp32-v3-rom-app.bin -esp32c3-rom.bin +libqemu-xtensa-amd64 libqemu-riscv32-amd64 +libqemu-xtensa-arm64 libqemu-riscv32-arm64 +libqemu-xtensa-macos-arm64 libqemu-riscv32-macos-arm64 +libqemu-xtensa-windows-amd64 libqemu-riscv32-windows-amd64 +esp32-v3-rom esp32-v3-rom-app +esp32c3-rom esp32s3_rev0_rom +qemu-source- (GPL-2.0 corresponding source) ``` --- @@ -791,7 +804,9 @@ healthcheck: | Arg | Default | Description | |-----|---------|-------------| | `TARGETARCH` | (auto-injected by Buildx) | Target architecture: `amd64` or `arm64` | -| `QEMU_RELEASE_URL` | `https://github.com/davidmonterocrespo24/velxio/releases/download/qemu-prebuilt` | URL prefix for QEMU binary downloads | +| `VELXIO_LICENSE_KEY` | (empty) | Licence key for the gated binary download; free personal keys at velxio.dev/license/signup | +| `VELXIO_BINARY_BASE_URL` | `https://velxio.dev/api/pro/license/downloads` | Gated endpoint serving the QEMU binaries and their GPL source | +| `QEMU_RELEASE_URL` | (empty) | Legacy escape hatch: URL prefix for a private mirror of the binaries. Takes precedence when set | | `ESPIDF_IMAGE` | (unused, legacy) | Was used for external ESP-IDF image reference | --- @@ -859,7 +874,7 @@ docker buildx build \ **Problem:** Running `docker pull` on Apple Silicon Mac fails because the image was built for amd64 only. **Solution:** The multi-platform build was added in the `docker-publish.yml` workflow with `platforms: linux/amd64,linux/arm64`. Ensure: -1. The `build-libqemu.yml` workflow has run successfully for both architectures (check that `libqemu-xtensa-arm64.so` exists in the `qemu-prebuilt` release) +1. The `build-libqemu.yml` workflow has run successfully for both architectures, and its arm64 artifact has been uploaded to velxio.dev (check that `libqemu-xtensa-arm64` appears in `GET /api/pro/license/downloads`) 2. The `docker-publish.yml` workflow has run after the QEMU ARM64 binaries were uploaded 3. The `docker/setup-qemu-action@v3` step is present in the workflow diff --git a/docs/wiki/esp32-cache-disable-runtime-crash.md b/docs/wiki/esp32-cache-disable-runtime-crash.md index d709d1a5..04c2e7d1 100644 --- a/docs/wiki/esp32-cache-disable-runtime-crash.md +++ b/docs/wiki/esp32-cache-disable-runtime-crash.md @@ -278,13 +278,16 @@ The patch is already in the source tree `build_libqemu-esp32.sh` (Linux/macOS) and `build_libqemu-esp32-win.sh` (Windows MSYS2 MINGW64). -### 8.1 Recommended — let the CI publish the release +### 8.1 Recommended — let the CI build, then publish to velxio.dev `third-party/qemu-lcgamboa/.github/workflows/build-libqemu.yml` builds the patched libraries for **every host Velxio supports natively** and -uploads them to the `qemu-prebuilt` release of the velxio repo: +leaves them as 3-day build artifacts. Collect the artifact and load each +file into the asset store with `scripts/upload-binary.sh`; nothing is +published to GitHub, because the GPL-2.0 corresponding source has to sit +beside the binary and velxio.dev is where it does. -| Asset name in release | Host | +| Asset name | Host | |---|---| | `libqemu-xtensa-amd64.so` / `libqemu-riscv32-amd64.so` | Linux x86_64 | | `libqemu-xtensa-arm64.so` / `libqemu-riscv32-arm64.so` | Linux ARM64 | diff --git a/docs/wiki/esp32-spi-display-performance.md b/docs/wiki/esp32-spi-display-performance.md index 7a92ccac..7ad286c0 100644 --- a/docs/wiki/esp32-spi-display-performance.md +++ b/docs/wiki/esp32-spi-display-performance.md @@ -361,8 +361,9 @@ Building `libqemu-xtensa.dll` on the Windows dev box (MSYS2 MINGW64): resolves these already; a bare `ctypes.CDLL` test needs `os.add_dll_directory(r'C:\msys64\mingw64\bin')`. -The Linux/CI build (`build_libqemu-esp32.sh` + the `qemu-prebuilt` release) needs -the same source change; bump the prebuilt DLLs there to ship the fix. +The Linux/CI build (`build_libqemu-esp32.sh`, whose output is collected from the +workflow artifact and uploaded to velxio.dev) needs the same source change; bump +the prebuilt DLLs there to ship the fix. --- diff --git a/docs/wiki/esp32-wifi-emulation-fixes.md b/docs/wiki/esp32-wifi-emulation-fixes.md index 748e21bd..c59fd053 100644 --- a/docs/wiki/esp32-wifi-emulation-fixes.md +++ b/docs/wiki/esp32-wifi-emulation-fixes.md @@ -865,23 +865,32 @@ branch: picsimlab-esp32 Every push to `picsimlab-esp32` triggers `.github/workflows/build-libqemu.yml`. The workflow compiles both `libqemu-xtensa.so` (ESP32) and `libqemu-riscv32.so` (ESP32-C3) -and uploads them as assets to the `qemu-prebuilt` release in the velxio repo. +and leaves them as 3-day build artifacts. + +Nothing is published to GitHub. These libraries are GPL-2.0 derivatives of QEMU, +so binary and corresponding source belong in one place: collect the artifact and +load it into velxio.dev's asset store with `scripts/upload-binary.sh`, where the +`qemu-source-` archive sits beside it. ### Deploy to container ```bash +# $KEY is a Velxio licence key — free personal keys at +# https://velxio.dev/license/signup +BASE=https://velxio.dev/api/pro/license/downloads + # Deploy ESP32 library docker exec velxio-app bash -c " - curl -L -H 'Authorization: token TOKEN' \ - 'https://github.com/davidmonterocrespo24/velxio/releases/download/qemu-prebuilt/libqemu-xtensa.so' \ + curl -fSL \ + '$BASE/libqemu-xtensa-amd64?key=$KEY' \ -o /app/lib/libqemu-xtensa.so.new && \ mv /app/lib/libqemu-xtensa.so.new /app/lib/libqemu-xtensa.so " # Deploy ESP32-C3 library docker exec velxio-app bash -c " - curl -L -H 'Authorization: token TOKEN' \ - 'https://github.com/davidmonterocrespo24/velxio/releases/download/qemu-prebuilt/libqemu-riscv32.so' \ + curl -fSL \ + '$BASE/libqemu-riscv32-amd64?key=$KEY' \ -o /app/lib/libqemu-riscv32.so.new && \ mv /app/lib/libqemu-riscv32.so.new /app/lib/libqemu-riscv32.so " diff --git a/test/backend/e2e/README.md b/test/backend/e2e/README.md index cdc0a940..a503a5f0 100644 --- a/test/backend/e2e/README.md +++ b/test/backend/e2e/README.md @@ -9,8 +9,10 @@ These tests **run in GitHub Actions** via `.github/workflows/backend-e2e-tests.y The CI workflow: -1. Downloads `libqemu-xtensa-amd64.so` and `libqemu-riscv32-amd64.so` from the - [qemu-prebuilt](https://github.com/davidmonterocrespo24/velxio/releases/tag/qemu-prebuilt) release. +1. Downloads `libqemu-xtensa-amd64` and `libqemu-riscv32-amd64` from velxio.dev's + gated endpoint (`$VELXIO_BINARY_BASE_URL/?key=$VELXIO_LICENSE_KEY`), using + the `VELXIO_LICENSE_KEY` repository secret. Free personal keys at + https://velxio.dev/license/signup. 2. Downloads ROM files: `esp32-v3-rom.bin`, `esp32-v3-rom-app.bin`, `esp32c3-rom.bin`. 3. Installs arduino-cli + `esp32:esp32` core. 4. Starts `uvicorn app.main:app --port 8001` with `QEMU_ESP32_LIB` and `QEMU_RISCV32_LIB` set.