From 097b17124b9da0555f0cc8554198f6b356dac3db Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois?= Date: Sat, 30 May 2026 13:18:32 +0200 Subject: [PATCH] docs: README editor-support + AppImage, DESIGN build_all, release note 0.2 README: add the AppImage release, an 'Editor support' section (testium lsp / schema, [lsp] extra, the testium_assist client), note the LSP ships in every channel. DESIGN.md: document build_all parallelism, --ram tmpfs mode and the Ctrl+C job-tree kill. release_note.txt: 0.2 entries for the language server and the build_all parallel/--ram work. Co-Authored-By: Claude Opus 4.8 --- DESIGN.md | 8 ++++++++ README.md | 37 +++++++++++++++++++++++++++++++++++++ release_note.txt | 11 +++++++++++ 3 files changed, 56 insertions(+) diff --git a/DESIGN.md b/DESIGN.md index 6261ac6..22a685e 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -224,6 +224,13 @@ Four distribution channels coexist, all sharing the single `src/testium/` packag The `.deb` work-in-progress lives in `package/deb/`: - `test_distro.sh debian:bookworm | debian:trixie | ubuntu:24.04` spins up a Docker/Podman container, reports system package availability, falls back to pip for what's missing (`pyside6` on bookworm/ubuntu, `telnetlib3`, `junit_xml`), runs the validation suite. Currently green on the three targets. +### Building all channels (`build_all.sh`) + +`build_all.sh` builds every artifact into `dist/` (manual PDF, wheel, PyInstaller binary, Flatpak bundle, AppImage). It reuses `scripts/build_env.sh` + `set_env.sh` so the venv at `test/tmp/.venv` stays the single source of Python deps; `build`/`pyinstaller`/`sphinx`/`linuxdoc` (and `pygls`, via the `[lsp]` extra) are installed there on demand. A step is skipped if its artifact already exists; `--clean` forces a rebuild. + +- **Parallelism (default).** A serial *prep* phase does everything that writes the shared venv (the `pip install`s) plus the Flatpak runtime install and the wheel (the AppImage installs it). Then manual + PyInstaller + Flatpak + AppImage build concurrently — they only *read* the venv, so there is no concurrent-pip race. Per-step output goes to `dist/.build-logs/.log`; results print in completion order (`wait -n`), and a failing step's log is dumped at the end. `--serial` builds one at a time. Ctrl+C is trapped to kill each job's whole process tree (subshell + grandchildren: podman container, flatpak-builder, pyinstaller), so no orphans survive. +- **`--ram` (slow/flash storage).** Redirects the build scratch to `/dev/shm` and skips UPX, a large win when building from a USB stick / SD card (I/O-bound on flash): `TMPDIR` + `PIP_CACHE_DIR`, the PyInstaller `--workpath` (`PYI_WORKPATH`), and a tmpfs bind-mount at the in-container AppImage AppDir (`APPIMAGE_APPDIR_TMPFS`); UPX is disabled via `TESTIUM_NO_UPX` (read by the `.spec`). **Flatpak is excluded** — `flatpak-builder` mounts its state dir with `rofiles-fuse` and FUSE cannot mount on `/dev/shm` (`fusermount: Permission denied`), so it builds on disk. Each `package/*/build.sh` honours these env vars with on-disk defaults, so behaviour is unchanged without `--ram`; the tmpfs scratch is freed on exit. On a RAM-limited machine combine with `--serial`. + ### Host-only py_func / lua_func in sandboxed bundles (Flatpak, AppImage) The bundled Python (Flatpak's runtime python, AppImage's `python3.11`) is reserved for the **main process only**. Subprocesses (`py_func`, `lua_func`, `git`, the `run` item's sub-instance) must use the host's interpreters and tools so user-installed modules (pyserial, junit_xml, …) are visible. This is enforced by `interpreter/utils/bins.py`: @@ -272,6 +279,7 @@ The `testium_assist` editor extension is a thin LSP client that spawns `testium Both Flatpak and AppImage export `TESTIUM_VERSION` from a launcher (Flatpak: launcher script in `org.testium.Testium.yaml`; AppImage: `runtime.env` in `AppImageBuilder.yml`). `get_testium_version()` checks `/.flatpak-info` / `APPIMAGE` and reads `TESTIUM_VERSION` rather than relying on package metadata or repo introspection. ## Recent fixes / notable changes +- `build_all.sh`: builds the four heavy channels in parallel (serial prep for the shared venv + wheel), results in completion order, Ctrl+C kills the whole job tree; `--ram` puts the build scratch on tmpfs (`/dev/shm`) + skips UPX for fast builds on USB/SD storage (Flatpak excluded — rofiles-fuse can't mount tmpfs). See the "Building all channels" section. - LSP across packaging channels: `testium lsp` (and the `testium_assist` editor extension that spawns it) now works from source, wheel, PyInstaller, Flatpak and AppImage. Two enablers — (1) action items declare a class-level `ACTIONS = {key: class}` registry (like `PARAMS`), so `lsp/schema.py` builds the full schema from class attributes with no `inspect.getsource`/AST (which broke under frozen PyInstaller); (2) the `[lsp]` extra (pygls) is wired into every full-app channel. `test/validation/lsp_check.py`, run by `run.sh` before the suite, asserts per-channel that `schema` keeps its actions and `lsp` answers `initialize`. See the matching architecture sections. - Declarative test item parameters (v0.2): each `TestItem` subclass exposes a `PARAMS = ParamSet(...)` class attribute consumed by the base `__init__`. Catches unknown YAML keys (typo warnings listing the accepted names) and missing required params (load-time errors with `.tum` context). Lays the schema foundation for a future LSP server and auto-generated manual sections. See the matching architecture section. - Flatpak: `py_func` / `lua_func` / `run` sub-instance now execute on the host via `flatpak-spawn --host`. The previous attempt to inject host lib dirs into the sandbox's `LD_LIBRARY_PATH` was abandoned — host shared libs are ABI-incompatible with the Flatpak runtime's glibc and would trip `_dl_call_libc_early_init`. The manifest gained `--talk-name=org.freedesktop.Flatpak` so the spawn proxy call is allowed. The testium package is staged once per process under `/tmp` (shared with the host) so the host interpreter can locate `py_func` / `lua_func`. diff --git a/README.md b/README.md index 969a125..ba35961 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,20 @@ Pre-built artifacts are published at `testium` command is available in the terminal (requires `~/.local/bin` in `PATH`, which most modern distributions provide by default). +* **AppImage** (`Testium--x86_64.AppImage`) — a single self-contained + executable bundling its own Python. Make it executable and run it: + + ```sh + chmod +x Testium-*-x86_64.AppImage + ./Testium-*-x86_64.AppImage -b mytest.tum + ``` + + As with the binary and Flatpak, `py_func` / `lua_func` items run under the + *host* Python / Lua so your own modules stay visible. + +Every channel ships the language server, so `testium lsp` (see +[Editor support](#editor-support)) works out of the box from any of them. + ## Quick start From a checkout of the repository: @@ -82,6 +96,29 @@ python3 src/testium # GUI python3 src/testium -b mytest.tum # batch ``` +## Editor support + +testium ships a Language Server Protocol (LSP) server that gives `.tum` files +completion of item types, hover documentation, and an outline view in any +LSP-capable editor: + +```sh +testium lsp # speaks LSP over stdio; an editor's LSP client drives it +testium schema # dumps the item/parameter schema as JSON (what the LSP serves) +``` + +The server is bundled in every pre-built release (wheel, binary, Flatpak, +AppImage). For a source / wheel install, pull the language-server extra: + +```sh +pip install 'testium[lsp]' # from PyPI / a wheel +pip install -e /path/to/testium/src[lsp] # from a source checkout +``` + +A VSCode / VSCodium client extension (`testium_assist`) wraps `testium lsp`; +the schema is built from testium itself, so new item types and parameters +appear in the editor on the next testium upgrade with no client change. + ## Troubleshooting ### `wl_proxy_marshal_flags` symbol error diff --git a/release_note.txt b/release_note.txt index 0b15c84..91d1b78 100644 --- a/release_note.txt +++ b/release_note.txt @@ -5,6 +5,17 @@ version 0.2 WARN listing the accepted names instead of being silently ignored; missing required parameters error out at load time with the source ``.tum`` file as context. No change to valid existing tests. +- Editor support: testium now ships a language server. ``testium lsp`` + gives ``.tum`` files item-type completion, hover documentation and an + outline view in any LSP-capable editor (a VSCode / VSCodium client is + provided separately). ``testium schema`` dumps the item/parameter + schema as JSON. The server works from every channel — bundled in the + binary / Flatpak / AppImage, and pulled by ``pip install testium[lsp]`` + for wheel installs. +- build_all.sh: the four heavy channels now build in parallel (results + reported as each finishes; Ctrl+C stops them cleanly). New ``--ram`` + option builds on a tmpfs (``/dev/shm``) and skips UPX for much faster + packaging on USB-stick / SD-card storage. version 0.1.3 ==============