From 147767c49d040556e439ba9b5c57500ad663ed3f Mon Sep 17 00:00:00 2001 From: MechaCat02 Date: Sat, 26 Sep 2026 17:56:52 +0200 Subject: [PATCH] docs(port): the two steps a host needs that the container hides Both were found by following RUNNING.md on this host from a clean checkout, and both fail in a way that blames the wrong thing. `godot --path port` without a prior `--import` produces THIRTY parse errors naming half the project -- ScreenView, MenuAudio, Gamepad, MenuFlow, ExportTree all "not declared", each cascading into "cannot infer the type of ..." -- and then hangs. That reads like a port that does not compile. It is one gitignored file: `port/.godot/global_script_class_cache.cfg`, which Godot writes at import time and which `class_name` resolution needs. After `--headless --path port --import`: zero errors, `main_menu` loads 16 elements and settles at t=56. The exporter shells out to ffmpeg and ffprobe for the movies AND the audio, and `sylph-ci:local` has neither -- so the documented `cargo run` fails minutes in, after the screens are already written and it looks like it is working. The image to use is `sylph-ci:ffmpeg`. Neither bites in the agent container: its image carries an imported tree and its own ffmpeg. That is exactly why neither was ever written down. Also recorded: `--headless` CANNOT `--capture` (the dummy renderer never emits `frame_post_draw`; the port detects this and says so), and `xvfb-run`, which its message suggests, is not installed on every host -- it is not on this one. Measured 2026-09-26 on fabi-Hyrican-PC: 31 s build, 4 min 11 s export, 149 MB, `sylpheed-export check` validates all 16 screens against sylpheed.screen/3. Co-Authored-By: Claude Opus 5 (1M context) --- docs/port/RUNNING.md | 46 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 45 insertions(+), 1 deletion(-) diff --git a/docs/port/RUNNING.md b/docs/port/RUNNING.md index 0eccadb7..4d26f81c 100644 --- a/docs/port/RUNNING.md +++ b/docs/port/RUNNING.md @@ -9,6 +9,36 @@ Everything below has been run. Where a number is quoted it was measured in this container, and where the container distorts it that is said rather than left for the reader to discover. +## 0. Import the project once, on a checkout that has never run it + +```bash +godot --headless --path port --import +``` + +🔴 **Skip this and the port looks broken rather than unimported.** Godot resolves +`class_name` through `port/.godot/global_script_class_cache.cfg`, which is +gitignored and is written at import time. Without it **every** class fails — +`ScreenView`, `MenuAudio`, `Gamepad`, `MenuFlow`, `ExportTree` — and each failure +cascades into a dozen more: + +``` +SCRIPT ERROR: Parse Error: Could not find type "ScreenView" in the current scope. +SCRIPT ERROR: Parse Error: Cannot infer the type of "_pad" variable … +ERROR: Failed to load script "res://scripts/boot.gd" with error "Parse error". +``` + +Thirty-odd parse errors naming half the project reads like a port that does not +compile. It is one missing cache, and the import takes seconds. Measured on a +fresh checkout 2026-09-26: before, 30 errors and a hang; after, **zero**. + +The container does not hit this because its image carries an imported tree, which +is exactly why the step was never written down. + +⚠️ `--headless` **cannot capture**. Godot's dummy renderer never emits +`frame_post_draw`, so `--capture=` under `--headless` would hang; the port +detects it and says so. A capture needs a display — `xvfb-run -a godot …`, and +note that **`xvfb-run` is not installed on every host**. + ## 1. Build the asset tree The Godot project reads `export/`, never the disc. @@ -17,7 +47,21 @@ The Godot project reads `export/`, never the disc. cargo run --release -p sylpheed-export -- export --disc /disc --out export ``` -Roughly four minutes, most of it transcoding two movies. It **rewrites `export/` +Roughly four minutes, most of it transcoding two movies. + +🔴 **The exporter needs `ffmpeg` and `ffprobe` on PATH** — it shells out to them +for both the movies and the audio. On a host, that means running it through the +CI container built WITH them: + +```bash +SYLPH_CI_IMAGE=sylph-ci:ffmpeg docker/ci/run \ + cargo run --release -p sylpheed-export -- export --disc /disc --out export +``` + +`sylph-ci:local` has neither, and the failure arrives several minutes in, after +the screens have already been written. Measured 2026-09-26 on `fabi-Hyrican-PC`: +31 s to build, 4 min 11 s end to end, 149 MB of `export/`, and +`sylpheed-export check` then validates all 16 screens. It **rewrites `export/` wholesale** — never hand-edit anything in there; hand-written decisions live in `authored/` beside it, and survive a re-export.