docs(port): the two steps a host needs that the container hides #67

fabi · 2026-09-26T15:57:34Z

fabi commented

2026-09-26 15:57:34 +00:00

Found by following RUNNING.md on fabi-Hyrican-PC from a clean checkout, to get export/ built so a human can judge P6. Both steps fail in a way that blames the wrong thing.

1. Without a prior import, the port looks like it does not compile

godot --path port on a checkout that has never imported produces thirty parse errors naming half the project — ScreenView, MenuAudio, Gamepad, MenuFlow, ExportTree all "not declared", each cascading into a Cannot infer the type of … — and then hangs.

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

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 godot --headless --path port --import, measured: zero errors, and main_menu loads 16 elements, 16 in paint order, settling at t=56 (0.933 s).

2. The exporter needs ffmpeg, and the documented image has none

It shells out to ffmpeg/ffprobe for the movies and the audio. 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 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 — the same shape this port keeps finding, something correct, documented and unexercised.

Also recorded

--headless cannot --capture: Godot's dummy renderer never emits frame_post_draw, so it would hang. The port already detects this and says so, and its message suggests xvfb-run — which is not installed on every host, including this one. Worth knowing before someone follows the advice.

Measured 2026-09-26 on `fabi-Hyrican-PC`


release build	31 s
export, end to end	4 min 11 s
`export/`	149 MB
`sylpheed-export check`	16 screens validate against `sylpheed.screen/3`
script errors after import	0

What to look at

Pass: on a checkout with no port/.godot, the two commands in §0 and §1 get you to a loading main_menu.
Fail: either step still needs something the page does not say.

Docs only — no code changes. tools/port/check-citations exits 0.

🤖 Generated with Claude Code

Found by following [`RUNNING.md`](docs/port/RUNNING.md) on `fabi-Hyrican-PC` from a clean checkout, to get `export/` built so a human can judge P6. Both steps fail in a way that blames the wrong thing. ### 1. Without a prior import, the port looks like it does not compile `godot --path port` on a checkout that has never imported produces **thirty** parse errors naming half the project — `ScreenView`, `MenuAudio`, `Gamepad`, `MenuFlow`, `ExportTree` all "not declared", each cascading into a `Cannot infer the type of …` — and then hangs. ``` 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". ``` 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 `godot --headless --path port --import`, measured: **zero** errors, and `main_menu` loads 16 elements, 16 in paint order, settling at t=56 (0.933 s). ### 2. The exporter needs ffmpeg, and the documented image has none It shells out to `ffmpeg`/`ffprobe` for the movies **and** the audio. `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 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 — the same shape this port keeps finding, something correct, documented and unexercised. ### Also recorded `--headless` **cannot** `--capture`: Godot's dummy renderer never emits `frame_post_draw`, so it would hang. The port already detects this and says so, and its message suggests `xvfb-run` — which is **not installed on every host**, including this one. Worth knowing before someone follows the advice. ### Measured 2026-09-26 on `fabi-Hyrican-PC` | | | |---|---| | release build | 31 s | | export, end to end | 4 min 11 s | | `export/` | 149 MB | | `sylpheed-export check` | 16 screens validate against `sylpheed.screen/3` | | script errors after import | **0** | ### What to look at **Pass:** on a checkout with no `port/.godot`, the two commands in §0 and §1 get you to a loading `main_menu`. **Fail:** either step still needs something the page does not say. Docs only — no code changes. `tools/port/check-citations` exits 0. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

fabi added 1 commit 2026-09-26 15:57:34 +00:00

docs(port): the two steps a host needs that the container hides

CI / Native — linux (pull_request) Failing after 1h21m4s

Details

CI / WASM — Web (pull_request) Successful in 29m43s

Details

CI / Formatting (pull_request) Successful in 24s

Details

147767c49d

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) <noreply@anthropic.com>

CI / Native — linux (pull_request) Failing after 1h21m4s

Details

CI / WASM — Web (pull_request) Successful in 29m43s

Details

CI / Formatting (pull_request) Successful in 24s

Details

This pull request doesn't have enough required approvals yet. 0 of 1 approvals granted from users or teams on the allowlist.

You are not authorized to merge this pull request.

View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u origin docs/running-import-step:docs/running-import-step

git checkout docs/running-import-step

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: fabi/Sylpheed#67