From 9151cef0f52d583a4e82c5c8eaff68bf911e29e0 Mon Sep 17 00:00:00 2001 From: Valiantsin Dzerakh Date: Sat, 24 Oct 2026 08:41:50 +0300 Subject: [PATCH] Map the release's deps to runtime/deps and document the installer command line, events and the real peak disk space Co-Authored-By: Claude Opus 5.5 --- docs/installer.md | 24 +++++++++++++++++++++++- installer/layout.py | 9 +++++---- 2 files changed, 28 insertions(+), 5 deletions(-) diff --git a/docs/installer.md b/docs/installer.md index 441e22bc..1453b04a 100644 --- a/docs/installer.md +++ b/docs/installer.md @@ -35,7 +35,8 @@ release that changes nothing game-derived skips the rebuild. ## Setup steps 1. **Check** before writing anything: the files open with the keys, the update is 1.2.1 (by hash, as - `tools/extract.py`), the keys are new enough for the update, about 22 GB is free on the target disk, the CPU has + `tools/extract.py`), the keys are new enough for the update, enough space is free on the target disk (about 36 GiB at the peak of a + first install, 20 GiB after it), the CPU has AVX2 (`-march=x86-64-v3`), a Vulkan 1.3 GPU exists. Each failure is one clear message. 2. **Extract** ExeFS and RomFS into the install folder and verify the hashes. 3. **Lift** the ExeFS to C (`recomp/gen.py`, `recomp/patches-v121.txt`) into a temp folder next to the installer. @@ -48,6 +49,27 @@ release that changes nothing game-derived skips the rebuild. A cancelled or failed setup resumes from the last finished step (`totk-install.json`). +## Command line + +`installer/` (stdlib only; `installer/layout.py` maps the release folder and, in a repository, the dev toolchain): + +``` +python -m installer --base FILE --update FILE --keys FILE --lang CODE --dest DIR [--root DIR] [--temp DIR] [--verify] +``` + +- On a folder with `totk-install.json` only `--dest` is needed; the game files only when the extraction must run again. +- stdout: one JSON event per line, types `start`, `plan`, `step` (started, done, skipped), `progress` (step, phase, + done/total/unit), `warning`, `error`, `end` (`installer/events.py`). Messages are ids with parameters; + `installer/text/en.json` holds their English text. The human-readable log goes to `/logs/`. +- Exit codes: 0 done, 1 failed, 2 bad command line, 3 cancelled. The window cancels with Ctrl+Break to the + installer's process group. +- Each step records a key over its inputs (runner.py). A step with the recorded key and intact output is skipped, so + resume and update are one rule; output kept from another release is re-hashed first. +- Peak space on the install disk is about 36 GiB, not 22: the extraction copies both Program NCAs (16.3 GiB) next to + the merged RomFS (15.9 GiB) before it deletes them. The check computes the exact figure. +- `tests/installer_test.py`: bookkeeping with fake steps. `tests/installer_e2e.py`: a dev-mode run with the files of + `config.local.toml`. + ## Release layout The unpacked release; `tools/make_release.py` assembles it, CI zips it: diff --git a/installer/layout.py b/installer/layout.py index 4d290b50..42bb2544 100644 --- a/installer/layout.py +++ b/installer/layout.py @@ -2,11 +2,12 @@ Release (docs/installer.md "Release layout"), root = the unpacked folder: - python/python.exe runs every tool (numpy, lz4, cryptography, compression.zstd) + python/python.exe runs every tool (numpy, lz4, cryptography, compression.zstd); its ._pth puts .., ../tools + and ../recomp on sys.path, so `python -m installer` imports from the release folder recomp/, tools/ the lifter and the scripts; recomp/patches-v121.txt, tools/data/expected-v1.2.1.json llvm/ llvm-mingw (bin/clang.exe) - runtime/ libtotkrt.a, the headers and install-side sources (romfs.c), and include/ + lib/ of - Vulkan, SDL3, Opus, libvpx and VMA (build_game.py --deps) + runtime/ libtotkrt.a, the headers and install-side sources (romfs.c); runtime/deps/ holds + include/ + lib/ of Vulkan, SDL3, Opus, libvpx and VMA (build_game.py --deps) bin/ totk_xlate.exe (+ totk_xlate.id), hactool.exe, ninja.exe, SDL3.dll, libopus-0.dll data/shader_list.tsv the MacNativeGames shader list totk.ini.example @@ -79,7 +80,7 @@ def release_layout(root): python=root / 'python' / ('python' + EXE), tools=root / 'tools', recomp=root / 'recomp', patches=root / 'recomp' / 'patches-v121.txt', expected=root / 'tools' / 'data' / 'expected-v1.2.1.json', - llvm=root / 'llvm', deps=root / 'runtime', runtime=root / 'runtime', + llvm=root / 'llvm', deps=root / 'runtime' / 'deps', runtime=root / 'runtime', runtime_lib=root / 'runtime' / 'libtotkrt.a', ninja=root / 'bin' / ('ninja' + EXE), hactool=root / 'bin' / ('hactool' + EXE), xlate=root / 'bin' / ('totk_xlate' + EXE),