Skip to content

technical.md

Latest commit

 

History

History
82 lines (54 loc) · 2.72 KB

technical.md

File metadata and controls

82 lines (54 loc) · 2.72 KB
Raw

Flatpak Technical Details

Technical notes for developers working on the Flatpak build.

Build Pipeline

Offline-first: flatpak-node-generator converts Yarn lockfiles into generated-sources.json so builds need no network. Yarn pulls from an offline mirror inside the sandbox.

Build stages (in the SDK sandbox):

  1. yarn install -- offline dependency fetch
  2. _install_app, subprojects_app, _assets_app, build_dist -- compile to app/
  3. electron-builder -- package app with Electron runtime to dist/linux-unpacked/
  4. Copy dist/linux*-unpacked/ to /app/main
  5. dotnet-runtime module -- stage .NET runtime

See flatpak/com.nexusmods.vortex.yaml for per-phase commands and environment variables.

Testing Approaches

Quick Development Testing (flatpak_run.py)

Builds/installs when needed, then runs the installed app:

python flatpak/scripts/flatpak_run.py

UX Testing (flatpak_install.py)

Exports to a local OSTree repo and installs the app:

python flatpak/scripts/flatpak_install.py

This approach:

  1. Exports build to flatpak/flatpak-repo/ (OSTree repository)
  2. Adds the repo as a flatpak remote
  3. Installs the app from the repo
  4. The app now appears in software centers (KDE Discover, GNOME Software)

Use this to test the actual user installation experience.

Yarn Config (flatpak/yarnrc)

  • child-concurrency 1 -- deterministic, avoids cache races
  • yarn-offline-mirror -- tarball store inside the sandbox
  • yarn-offline-mirror-pruning false -- don't delete needed tarballs
  • cache-folder -- writable cache in the sandbox

Launch Mechanism

flatpak/run.sh launches with zypak-wrapper /app/main/vortex.

  • Zypak runs Electron inside the sandbox (see Zypak docs)
  • Desktop file points to run.sh
  • Entrypoint must use Zypak per Flatpak Electron guidance

Why These Choices

  • Full host filesystem access: Game installs can be anywhere. Deployment uses hardlinks, symlinks, and moves. Portals are not viable because scanning and deployment are background operations that cannot wait for user prompts.

  • Offline builds: Required for Flathub and reproducible builds. All Yarn and NPM dependencies must be in generated-sources.json.

  • Zypak wrapper: Required by the Electron BaseApp to run Chromium's sandbox inside Flatpak's sandbox.

  • .NET runtime staging: Framework-dependent tools such as dotnetprobe need DOTNET_ROOT pointing to the staged runtime at /app/lib/dotnet.

  • Electron builder: We use electron-builder with the dir target to package the app with the Electron runtime. This creates a complete distribution in dist/linux-unpacked/ that gets copied to /app/main.