tools/make_release_linux.py assembles the Linux release folder and packs it with the static type-2 AppImage runtime: python-build-standalone 3.14 with tkinter, LLVM 23.1.4 (clang, lld, llvm-ar) and the part of the Steam Runtime 3 sniper SDK sysroot a game build reads, so the game, hostcheck, hactool and the translator need no newer glibc than 2.31 and run on SteamOS. The game it builds needs only glibc, the system's Vulkan loader and the libSDL3.so.0 beside it; Opus, libvpx, zstd and libstdc++ are linked in. --prove builds generated/v121 with the folder alone and runs the probes. The installer runs on Linux: release and dev layouts, temp under the XDG cache (the AppImage mount is read-only), cancel through the CLI's process group, language from LANG, xdg-open and a PNG icon, texts that name the right executable, and a warning on kernels older than 6.7. hostcheck reads x86-64-v3 from CPUID, since clang's __builtin_cpu_supports reads it from libgcc, which before GCC 12 has no level bits. build_game.py takes --sysroot, build_hactool.py --cc and build_xlate.py --llvm/--sysroot; linux.c carries the Linux 6.7 write-watch definitions for older headers. Also: shader_census.py and package_build.py use the Linux executable names, and probe-shader writes its shader path with forward slashes.
10 KiB
Installer
A public release that turns the player's own game files into a playable TotK folder. The release carries no game data and no code derived from the game: the installer builds the game on the player's machine. The installed folder holds only the game; the installer and its tools stay outside it.
What the player does
- Downloads
TotK-Setup-<version>-windows.zipfrom GitHub Releases (none is published yet), unpacks it anywhere and startsTotK-Setup.exe. - Picks:
- the base game (XCI or NSP) and the 1.2.1 or 1.4.3 update (NSP);
- their
prod.keys; - the game language and the install folder.
- Waits for the setup, one time. The window shows each step and its progress.
- Plays
totk.exefrom the install folder. The installer and the source NSP or XCI can be deleted.
The install folder (main.c portable_paths() reads this layout; it stays portable):
<install folder>/
totk.exe, SDL3.dll, libopus-0.dll, totk_xlate.exe
totk.ini language; the other keys as commented defaults (totk.ini.example)
exefs/, romfs/ extracted from the player's files
profile/ saves
logs/ totk.log of the last run, totk.1.log to totk.4.log of the runs before it
shader and pipeline caches prepared by the setup
totk-install.json what built this folder: release version, input hashes, finished steps
Updating the port
The player runs a newer installer on the same folder. It reads totk-install.json, keeps romfs/, exefs/,
profile/ and totk.ini after checking their hashes, rebuilds totk.exe and re-prepares the shaders. A newer
release that changes nothing game-derived skips the rebuild.
Given another update file than the recorded one (1.2.1, then 1.4.3), the installer extracts and builds again from it and
keeps profile/. Saves carry over both ways: 1.4.3 converts a 1.2.1 save on load, and 1.2.1 loads the saves 1.4.3 wrote.
Setup steps
- Check before writing anything: the files open with the keys, the update is 1.2.1 or 1.4.3 (by hash, as
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. - Extract ExeFS and RomFS into the install folder and verify the hashes.
- Lift the ExeFS to C (
recomp/gen.py,recomp/patches-v121.txtorpatches-v143.txt) into a temp folder next to the installer. - Compile the generated C,
modules.c,romfs.c,patches.candov_zstd.c(they bake the per-install layout, RomFS hashes and the game version's patch page) and link them with the prebuilt runtime library intototk.exe(build_game.py --runtime-lib; about 3 min on 24 cores). - Prepare the RomFS patches and the shaders (
tools/make_romfs_patches.py,tools/prepare_shaders.py,totk.exe --prepare-shaders) in the install folder. - Clean up the temp folder (generated C and objects, about 1.3 GB).
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.jsononly--destis 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),space(bytes needed and free on the install disk and the temp disk),warning,error,end(installer/events.py). Messages are ids with parameters;installer/text/en.jsonholds their English text. The human-readable log goes to<temp>/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.
- Window (
python -m installer.gui,installer/gui.pydraws,installer/guilogic.pydecides): form, step list with progress, space line, collapsible log, Cancel (Ctrl+Break to the CLI's process group, then it waits for the exit), finish screen with Open folder. English or Russian, chosen from the Windows display language, switchable in the window; every sentence is an id ininstaller/text/<en|ru>.json. A folder withtotk-install.jsonneeds only the folder.--selftest [--shots DIR]builds every screen in both languages and closes itself. tests/installer_gui_test.py: event model, form, catalogs, cancel, the self-closing window and one end-to-end run of the CLI in--verifymode (needsbuild/install-testandbuild/extracted/v121; see its docstring).tests/installer_test.py: bookkeeping with fake steps.tests/installer_e2e.py: a dev-mode run with the files ofconfig.local.toml.
Release layout
The unpacked release; tools/make_release.py assembles it and --zip packs it:
TotK-Setup.exe starts python/pythonw.exe -m installer.gui (installer/launcher/launcher.c, no console)
installer/ the installer: steps, CLI, window, en/ru text catalog
python/ Python 3.14.9 embeddable + numpy, lz4, cryptography, cffi, pycparser (+ tkinter for the window)
recomp/, tools/ the lifter and the build, extraction and shader scripts the steps run (copied from the repo)
llvm/ llvm-mingw, x86_64-only subset (Apache-2.0 with LLVM exception; mingw-w64 parts permissive)
runtime/ libtotkrt.a and the headers the generated code and modules.c/romfs.c/patches.c include
bin/ totk_xlate.exe, hactool.exe, SDL3.dll, libopus-0.dll, ninja.exe
data/ shader_list.tsv (MacNativeGames, MIT)
THIRD_PARTY_NOTICES.md
totk.ini.example, VERSION the default ini; the release string (the repository's VERSION plus the commit)
- SDL3 comes from the upstream release, not MSYS2: MSYS2's DLL imports the LGPL libiconv.
- Every bundled third-party piece gets a row in
THIRD_PARTY_NOTICES.md. - The release contains nothing game-derived;
make_release.pyrunstools/check_content.pyover the folder before it finishes.
Linux release
tools/make_release_linux.py builds the same setup for Linux and packs it as TotK-Setup-x86_64.AppImage (the static
type-2 runtime: no libfuse2 needed on the host). The player makes it executable and starts it; on a Steam Deck, from
Desktop Mode. The setup builds the game into the folder they pick, as on Windows, and the game is totk there with
libSDL3.so.0 beside it. The folder inside the AppImage:
AppRun starts python/bin/python3 -m installer.gui (no bytecode written into the read-only mount)
totk-setup.desktop, totk-setup.png
installer/, recomp/, tools/, data/, licenses/, THIRD_PARTY_NOTICES.md, totk.ini.example, VERSION as on Windows
python/ python-build-standalone 3.14 (with tkinter) + the installer's packages; a .pth puts the folder,
tools/ and recomp/ on sys.path
llvm/ LLVM 23 (clang, lld, llvm-ar) and llvm/sysroot: the files of the Steam Runtime 3 "sniper" SDK the
game's compile and link read (about 130 files)
runtime/ libtotkrt.a, headers, the install-side sources, totk.png; deps/ with the Vulkan headers, VMA and a
static zstd
bin/ totk_xlate, hactool, ninja, libSDL3.so.0
- Everything that runs on the player's machine is built against the sniper sysroot (glibc 2.31): the game, hostcheck, hactool and the translator need no newer glibc, so they run on SteamOS and current distributions. The game links Opus, libvpx, zstd and libstdc++ statically and needs only glibc, the system's Vulkan loader and the SDL3 beside it.
- The setup's temp folder is
$XDG_CACHE_HOME/totk-setup(default~/.cache/totk-setup): the AppImage is mounted read-only. - The window follows
LANGfor English or Russian, cancels through SIGTERM to the CLI's process group (the CLI handles it as Ctrl+Break on Windows) and opens the finished folder withxdg-open. - Requirements beyond Windows': Linux 6.7 or later (the write watch,
docs/building.md), and enough space in the cache folder's file system for the generated C (about 1.3 GB).
Constraints
- The installer steps contain no Win32 calls: Linux runs the same steps with its own compiler ("Linux release").
- The keys file path is passed to the tools; key values never appear in the UI, logs or files.
- The window is a front end over the CLI (
python -m installer --base ... --update ... --keys ... --lang ... --dest ...), which prints one JSON progress event per line. Tests and CI use the CLI. - Paths may hold any Unicode characters (a Cyrillic user name puts the temp and install folders under it). Every exe
the setup runs or builds reads its arguments and paths as UTF-8 through an
activeCodePagemanifest: hactool (our patch, building.md), totk.exe (runtime/totk.rc), ninja (upstream). The Python steps write their files and logs as UTF-8, andbuild_game.pyquotes paths with spaces on its Ninja command lines. - A game file whose data fails its hash checks or ends early stops the setup with
check.input_damaged, which names the file and asks to copy it again (extract.DamagedFile). A failed merge checks the base Program NCA alone to tell which file is damaged. - Unsigned exe: SmartScreen warns on first start.
Later
- Re-warm the driver cache on start after a move, GPU or driver change.
- NSZ and XCZ input.