Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,4 @@ SPEC.md
# LIGHTFORGE_TRACE=frames writes this next to the binary you ran.
frames.log
packaging/aur/*/*.tar.gz
/flatpak-build/
82 changes: 82 additions & 0 deletions FLATPAK.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
# Building the Flatpak

The Flatpak manifest is [packaging/flatpak/pro.tuxcore.Lightforge.yml](packaging/flatpak/pro.tuxcore.Lightforge.yml). It builds both Lightforge binaries from the checked-out source and reuses the project's desktop entry, AppStream metadata and icons.

## Requirements

Install Flatpak, `flatpak-builder`, and the Freedesktop 26.08 runtime and SDK. On Fedora, for example:

```sh
sudo dnf install flatpak flatpak-builder
flatpak install flathub \
org.freedesktop.Platform//26.08 \
org.freedesktop.Sdk//26.08 \
org.freedesktop.Sdk.Extension.rust-stable//26.08
```

The Rust extension is used by the manifest to provide Cargo inside the SDK. The first build downloads the crates named by `Cargo.lock`, so the build needs network access.

The manifest also requests Freedesktop's 32-bit compatibility and graphics extensions. They are required because Battle.net's installer is a 32-bit Windows program; they are downloaded as part of the Flatpak installation.

## Build and run locally

From the repository root:

```sh
flatpak-builder --force-clean --user --install-deps-from=flathub --install \
flatpak-build/build-dir \
packaging/flatpak/pro.tuxcore.Lightforge.yml
flatpak run pro.tuxcore.Lightforge
```

The manifest uses the working tree as its source, so changes must be saved before running `flatpak-builder`. The generated build directory lives under `flatpak-build/`, which is ignored by Git. Remove that directory, or keep `--force-clean`, when switching branches or troubleshooting a stale build.

## Permissions and game files

The manifest grants read/write access to `~/Games/Blizzard` by default, which is the standard Lightforge library path. It intentionally grants no access to other directories or mounted drives. Add every additional directory that Lightforge should be allowed to use yourself. This keeps the Flatpak from exposing your whole home directory or every mounted drive by default.

Lightforge needs write access to the directories containing its settings, Proton builds, Wine prefixes, and game libraries. File and folder selection still goes through the desktop portal, but a selected directory must also be allowed by the Flatpak permission system.

### Using Flatseal

1. Install and open **Flatseal**.
2. Select **Lightforge** (`pro.tuxcore.Lightforge`).
3. Under **Filesystem**, add the directories Lightforge should use in **Other files**.
4. Give each entry read/write access when Lightforge needs to download or update files.
5. Restart Lightforge after changing permissions.

Do not add `~/.var/app/pro.tuxcore.Lightforge` as a permission. Flatpak automatically gives the application access to its private app-data directory there. The native-install path `~/.local/share/lightforge` is not the path used by the Flatpak.

For example, add `/home/you/Games/WorldOfWarcraft` for a game library outside the default path or the mount point containing it. Use the actual paths on your system; do not copy this example path literally.

### Using the command line

Repeat `--filesystem` for each directory. The `:rw` suffix grants read/write access:

```sh
flatpak override --user \
--filesystem=/home/you/Games/WorldOfWarcraft:rw \
pro.tuxcore.Lightforge
```

To allow all of your home directory, use this broader permission instead:

```sh
flatpak override --user --filesystem=home:rw pro.tuxcore.Lightforge
```

To inspect the current permissions:

```sh
flatpak override --user --show pro.tuxcore.Lightforge
```

Flatpak stores the application's private configuration, data, and cache below `~/.var/app/pro.tuxcore.Lightforge/`. The exact subdirectories are managed through the XDG environment inside the sandbox; they do not need to be added manually.

The Flatpak does not bundle Wine, Proton, or Blizzard game data. Lightforge downloads and manages Proton itself; Battle.net or other Windows components still need the host's compatible 32-bit support.

## Updating the manifest

The application ID must remain `pro.tuxcore.Lightforge`; it matches the desktop entry, AppStream metadata, and GUI window ID. When the project version changes, update the normal project metadata in `Cargo.toml` and the release metadata as usual. The manifest intentionally does not duplicate that version.

For a distributable or Flathub build, replace the local directory source with a tagged source and generate pinned Cargo sources with `flatpak-cargo-generator.py`. The local-tree source and network-enabled Cargo build are intended for building this project from a checkout; they are not a Flathub submission recipe.
11 changes: 11 additions & 0 deletions packaging/flatpak/flatpak-runtime.patch
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
diff --git a/crates/core/src/runtime.rs b/crates/core/src/runtime.rs
--- a/crates/core/src/runtime.rs
+++ b/crates/core/src/runtime.rs
@@ -32,4 +32,7 @@ const LOADER_CANDIDATES: &[&str] = &[
"/lib32/ld-linux.so.2",
"/usr/lib/ld-linux.so.2",
"/usr/lib32/ld-linux.so.2",
+ // Freedesktop's 32-bit compatibility extension is mounted here by the
+ // Flatpak manifest.
+ "/app/lib/i386-linux-gnu/ld-linux.so.2",
];
77 changes: 77 additions & 0 deletions packaging/flatpak/pro.tuxcore.Lightforge.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
app-id: pro.tuxcore.Lightforge
runtime: org.freedesktop.Platform
runtime-version: '26.08'
sdk: org.freedesktop.Sdk
sdk-extensions:
- org.freedesktop.Sdk.Extension.rust-stable
command: lightforge-gui

# Battle.net's installer is 32-bit. These runtime extensions provide the
# 32-bit loader, libraries and graphics stack inside the Flatpak sandbox.
add-extensions:
org.freedesktop.Platform.Compat.i386:
directory: lib/i386-linux-gnu
version: '26.08'
org.freedesktop.Platform.GL32:
directory: lib/i386-linux-gnu/GL
add-ld-path: lib
download-if: active-gl-driver
enable-if: active-gl-driver
autoprune-unless: active-gl-driver
no-autodownload: true
version: '1.4'

finish-args:
# Native windowing and rendering backends used by iced/wgpu.
- --share=ipc
- --socket=wayland
- --socket=fallback-x11
- --socket=pulseaudio
- --device=dri
# Lightforge downloads Blizzard content, Proton builds and addons.
- --share=network
# The launcher can manage games and prefixes on the user's normal drives.
- --filesystem=~/Games/Blizzard:rw
# - --filesystem=/run/media:rw
# - --filesystem=/mnt:rw
# Gamepads are read through libudev.
- --device=input

modules:
- name: lightforge
buildsystem: simple
build-options:
# The Rust extension is supplied by the Freedesktop SDK.
append-path: /usr/lib/sdk/rust-stable/bin
build-args:
- --share=network
env:
CARGO_HOME: /run/build/lightforge/cargo
CARGO_NET_OFFLINE: 'false'
build-commands:
- cargo build --release --locked
# Runtime extensions are mounted at these paths and need their mount
# points to exist in the immutable application image.
- install -d /app/lib/i386-linux-gnu/GL
- install -Dm755 target/release/lightforge-gui /app/bin/lightforge-gui
- install -Dm755 target/release/lightforge /app/bin/lightforge
- install -Dm644 packaging/pro.tuxcore.Lightforge.desktop /app/share/applications/pro.tuxcore.Lightforge.desktop
- install -Dm644 packaging/pro.tuxcore.Lightforge.metainfo.xml /app/share/metainfo/pro.tuxcore.Lightforge.metainfo.xml
- install -Dm644 LICENSE /app/share/licenses/pro.tuxcore.Lightforge/LICENSE
- install -Dm644 packaging/icons/hicolor/16x16/apps/pro.tuxcore.Lightforge.png /app/share/icons/hicolor/16x16/apps/pro.tuxcore.Lightforge.png
- install -Dm644 packaging/icons/hicolor/22x22/apps/pro.tuxcore.Lightforge.png /app/share/icons/hicolor/22x22/apps/pro.tuxcore.Lightforge.png
- install -Dm644 packaging/icons/hicolor/24x24/apps/pro.tuxcore.Lightforge.png /app/share/icons/hicolor/24x24/apps/pro.tuxcore.Lightforge.png
- install -Dm644 packaging/icons/hicolor/32x32/apps/pro.tuxcore.Lightforge.png /app/share/icons/hicolor/32x32/apps/pro.tuxcore.Lightforge.png
- install -Dm644 packaging/icons/hicolor/48x48/apps/pro.tuxcore.Lightforge.png /app/share/icons/hicolor/48x48/apps/pro.tuxcore.Lightforge.png
- install -Dm644 packaging/icons/hicolor/64x64/apps/pro.tuxcore.Lightforge.png /app/share/icons/hicolor/64x64/apps/pro.tuxcore.Lightforge.png
- install -Dm644 packaging/icons/hicolor/128x128/apps/pro.tuxcore.Lightforge.png /app/share/icons/hicolor/128x128/apps/pro.tuxcore.Lightforge.png
- install -Dm644 packaging/icons/hicolor/256x256/apps/pro.tuxcore.Lightforge.png /app/share/icons/hicolor/256x256/apps/pro.tuxcore.Lightforge.png
- install -Dm644 packaging/icons/hicolor/512x512/apps/pro.tuxcore.Lightforge.png /app/share/icons/hicolor/512x512/apps/pro.tuxcore.Lightforge.png
- install -Dm644 packaging/icons/hicolor/scalable/apps/pro.tuxcore.Lightforge.svg /app/share/icons/hicolor/scalable/apps/pro.tuxcore.Lightforge.svg
sources:
- type: dir
path: ../..
# Keep the upstream source unchanged; this Flatpak-only patch teaches
# the runtime probe where the compat.i386 extension is mounted.
- type: patch
path: flatpak-runtime.patch