a2nr
/
velxio
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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-<commit>
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.
This commit is contained in:
David Montero Crespo 2026-08-25 00:24:50 +02:00
parent f035bebf45
commit af55a9efb8
5 changed files with 59 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
docs/wiki/docker-infrastructure.md
View File

@ -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-<commit>` 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-<commit> (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

9
docs/wiki/esp32-cache-disable-runtime-crash.md
View File

@ -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 |

5
docs/wiki/esp32-spi-display-performance.md
View File

@ -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.
---

19
docs/wiki/esp32-wifi-emulation-fixes.md
View File

@ -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-<commit>` 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
"

6
test/backend/e2e/README.md
View File

@ -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/<asset>?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.