Initial commit

docs/building.md

@@ -0,0 +1,55 @@
+# Building Unheard City
+
+The build is a PyInstaller **one-folder** bundle: Python, Qt (incl. Qt Multimedia), libsndfile (libvorbis,
+FLAC, opus, mpg123) and soxr are all inside; nothing else is installed or needed at runtime. Build on each
+target OS (no cross-compiling).
+
+## Windows (x86-64) - tested
+```
+py -3.14 -m venv .venv            (Python 3.10-3.14)
+.venv\Scripts\python -m pip install -e .[app,dev]
+.venv\Scripts\python -m pytest -q
+.venv\Scripts\python tools\build_app.py
+```
+That one command does everything, offline. If `app/assets/` (git-ignored icon and wallpaper) is missing, it is
+made from `bac_logo_full.png` and `wallpaper.jpg` in `Downloads\Arkham City` (or `--art FOLDER`); without those
+images the build still works, with a plain icon and no wallpaper.
+Output: `dist\UnheardCity\UnheardCity.exe` and `dist\UnheardCity-<ver>-windows-amd64.zip`
+(~78 MB zip, ~190 MB unpacked). The build also writes `THIRD_PARTY_LICENSES.txt` (license texts come from the
+wheels and from `tools/licenses/`).
+
+**Installer.** On Windows the folder (and zip) also contains `Install.cmd`, `install.ps1` and `uninstall.ps1`
+(sources in `tools/installer/`, version filled in by the build). It is a plain PowerShell installer, so no
+installer tool is needed to build it: per-user install to `%LOCALAPPDATA%\Programs\UnheardCity`, Start menu and
+optional desktop shortcut, an uninstall entry in Settings > Apps (`HKCU`), upgrade in place. User data in
+`%APPDATA%\UnheardCity` is kept on uninstall unless the user chooses otherwise. Unattended:
+`install.ps1 -Quiet -Desktop no [-Target DIR]`, `uninstall.ps1 -Quiet`.
+
+Verify the bundle is self-contained (PATH stripped to Windows folders):
+```
+set PATH=C:\Windows\System32;C:\Windows
+dist\UnheardCity\UnheardCity.exe --smoke-test --report smoke.txt    & type smoke.txt
+dist\UnheardCity\UnheardCity.exe --quit-after 8 --screenshot shot.png
+```
+
+## Linux (x86-64) - procedure (not executed on the development machine)
+Use the oldest distribution you want to support (glibc compatibility), e.g. Ubuntu 22.04:
+```
+sudo apt install python3 python3-venv libxcb-cursor0 libxkbcommon-x11-0 libegl1 libpulse0
+python3 -m venv .venv && . .venv/bin/activate
+pip install -e .[app,dev]
+QT_QPA_PLATFORM=offscreen pytest -q
+python tools/build_app.py          # -> dist/UnheardCity-<ver>-linux-x86_64.tar.gz
+QT_QPA_PLATFORM=offscreen dist/UnheardCity/UnheardCity --smoke-test --game /path/to/game
+```
+Notes:
+- The `soundfile` and `soxr` wheels for manylinux bundle libsndfile/libsoxr; the PySide6 wheels bundle Qt and
+  Qt Multimedia's FFmpeg backend (PulseAudio/PipeWire output). The target desktop only needs the usual X11/
+  Wayland and PulseAudio/PipeWire client libraries that every desktop distribution has.
+- Game folders under Proton are found automatically in `~/.steam/steam`, `~/.local/share/Steam`, Flatpak
+  (`~/.var/app/com.valvesoftware.Steam/...`) and Snap Steam libraries, including extra libraries from
+  `libraryfolders.vdf`. The game language is read from the Proton prefix
+  (`steamapps/compatdata/200260/pfx/drive_c/users/steamuser/Documents/WB Games/...`).
+- The in-game test harness (`ackit verify --ingame`) is Windows-only; everything else is portable.
+
+A GitHub Actions workflow that builds both platforms is in `.github/workflows/build.yml`.