Packaging for Flatpak

Relevant source files

The following files were used as context for generating this wiki page:

• packaging/flatpak/org.badkiko.sofl.yml
• packaging/flatpak/build.sh
• packaging/flatpak/README.md
• sofl/importer/flatpak_source.py
• scripts/build_all.sh
• packaging/README.md

The Steam Online Fix Launcher (SOFL) project uses Flatpak as a universal packaging format for distribution across all Linux systems. This system provides a sandboxed environment, ensuring that the application and its dependencies are bundled together, which simplifies installation and enhances security. The packaging process is managed through a combination of a build script, manifest files, and integration with the application's import functionality.

The Flatpak build is a key part of the project's CI/CD pipeline and is designed to support both stable releases and rapid development cycles. It handles dependency management, build environment setup, and the creation of a distributable .flatpak bundle.

Sources: packaging/flatpak/README.md, packaging/README.md

Architecture and Key Files

The Flatpak packaging is primarily defined by three files within the packaging/flatpak/ directory.

File	Description
build.sh	The main shell script responsible for orchestrating the entire Flatpak build process. It handles dependency checks, build modes, and bundle creation.
org.badkiko.sofl.yml	The Flatpak manifest for the stable release version. It defines the application ID, runtime, SDK, sandbox permissions, and build modules.
org.badkiko.sofl.Devel.yml	The manifest for the development version. It is used for testing and development, with a distinct application ID to coexist with the stable version.

Sources: packaging/flatpak/README.md:3-6

Development vs. Stable Builds

The build system distinguishes between stable and development versions to facilitate parallel installation and testing without conflicts.

Feature	Stable Version	Development Version
App ID	org.badkiko.sofl	org.badkiko.sofl.Devel
Manifest	org.badkiko.sofl.yml	org.badkiko.sofl.Devel.yml
Repository Branch	stable	devel
Use Case	Production releases	Development and testing
Auto-run	No	Yes, if installed with install flag

This separation is controlled by the dev flag in the build.sh script, which selects the appropriate manifest and project name.

Sources: packaging/flatpak/build.sh:18-22, packaging/flatpak/README.md:86-94

Build Process

The build.sh script automates the Flatpak package creation. It can be invoked manually by developers or by higher-level scripts like scripts/build_all.sh.

Sources: packaging/flatpak/build.sh, scripts/build_all.sh:49-55

Build Flow

The following diagram illustrates the execution flow of the build.sh script.

This diagram shows the logic within build.sh, including mode selection, dependency handling, and final bundle creation/installation.
Sources: packaging/flatpak/build.sh

Build Script Parameters

The build.sh script accepts several command-line arguments to customize its behavior.

Parameter	Description	Example Usage
[version]	The application version string. Defaults to "unknown".	./build.sh 1.0.0
[output_dir]	The directory where the final .flatpak bundle will be saved. Defaults to the current directory (.).	./build.sh 1.0.0 ../dist
[mode]	Can be install to install the package locally after building, fast to skip dependency checks, or dev to build the development version.	./build.sh 1.0.0 . install fast

Sources: packaging/flatpak/build.sh:4-29, packaging/flatpak/README.md:20-25

Key Build Commands

The core of the build process is the flatpak-builder command. The script constructs the command with flags based on the selected mode.

# Example for a standard build
flatpak-builder \
    --force-clean \
    --user \
    --install-deps-from=flathub \
    --disable-rofiles-fuse \
    --ccache \
    --repo=sofl-repo \
    --default-branch=stable \
    flatpak-build \
    "org.badkiko.sofl.yml"

In fast mode, internet-dependent flags like --install-deps-from=flathub are omitted.
Sources: packaging/flatpak/build.sh:140-147

Flatpak Manifest

The org.badkiko.sofl.yml file is the blueprint for the Flatpak package. It defines the application's metadata, dependencies, and sandbox permissions.

Sandbox Permissions (finish-args)

The application requests specific permissions to function correctly while remaining sandboxed.

Permission Argument	Description
--share=ipc	Share IPC namespace with the host.
--socket=fallback-x11, --socket=wayland	Grants access to the Wayland and X11 display servers.
--socket=pulseaudio	Grants access to the PulseAudio sound server.
--filesystem=xdg-documents	Access to the user's Documents folder.
--filesystem=xdg-data/Steam:ro	Read-only access to Steam's data directory, required for importing games.
--share=network	Allows network access, necessary for downloading covers and game data.
--device=dri	Grants access to the Direct Rendering Infrastructure for hardware-accelerated graphics.
--talk-name=org.freedesktop.Notifications	Allows the application to send desktop notifications.
--env=STEAM_COMPAT...	Sets environment variables to help the application locate Steam compatibility data within the sandbox.

Sources: packaging/flatpak/org.badkiko.sofl.yml:6-24

Build Modules

The manifest defines several modules that are built and installed into the sandbox.

This diagram shows that the main sofl application module depends on the other modules being present in the build environment.
Sources: packaging/flatpak/org.badkiko.sofl.yml:26-121

• blueprint-compiler: A dependency for compiling .blp UI files used by GTK4.
• python3-modules: This module uses pip to install required Python libraries like PyYAML, Pillow, requests, vdf, and rarfile from local source archives. This ensures a reproducible build without relying on network access during the pip install phase.
• unrar: Compiles and installs the unrar command-line utility, which is used by the application for extracting game files from RAR archives.
• sofl: The main application module. It is built using Meson from the project's source code.

Sources: packaging/flatpak/org.badkiko.sofl.yml:26-121

Application Integration

The SOFL application includes a FlatpakSource class to discover and import games that are installed as Flatpaks on the user's system.

Game Discovery

The FlatpakSource class in sofl/importer/flatpak_source.py works by:

1. Searching for .desktop files in standard Flatpak application directories (/var/lib/flatpak/exports/share/applications and ~/.local/share/flatpak/exports/share/applications).
2. Parsing each .desktop file to check if it belongs to a game (i.e., contains Game in its Categories entry).
3. Ignoring certain applications based on a blacklist to prevent importing other game launchers (like Steam itself) or SOFL.

# sofl/importer/flatpak_source.py:46-65
blacklist = (
    {
        "hu.badkiko.SOFL",
        "hu.badkiko.SOFL.Devel",
        "org.badkiko.sofl",
        "org.badkiko.sofl.Devel",
    }
    if shared.schema.get_boolean("flatpak-import-launchers")
    else {
        "hu.badkiko.SOFL",
        "hu.badkiko.SOFL.Devel",
        "org.badkiko.sofl",
        "org.badkiko.sofl.Devel",
        "com.valvesoftware.Steam",
        "net.lutris.Lutris",
        "com.heroicgameslauncher.hgl",
        "com.usebottles.Bottles",
        "io.itch.itch",
        "org.libretro.RetroArch",
    }
)

This blacklist is dynamically adjusted based on the flatpak-import-launchers setting. The executable command for an imported Flatpak game is formatted as flatpak run {flatpak_id}.

Sources: sofl/importer/flatpak_source.py:46-65, 126-127