/Qeatrix/steam-online-fix-launcher

Wiki directory

Browse AI-generated documentation for any repository.

Development Environment Setup

Relevant source files

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

The development environment for SOFL is designed to be straightforward, relying on the Meson build system and a helper script, scripts/dev.sh, to automate most of the setup, build, and execution process. The project is built with Python, GTK4, and LibAdwaita, following modern GNOME development practices.

This guide covers the necessary prerequisites, the process for setting up a local development environment, and the tools used for building, testing, and maintaining code quality. The central piece of the local development workflow is the dev.sh script, which handles the creation of a local application prefix, building the project, and running it with the correct environment variables.

Prerequisites

To build and run SOFL for development, your system must have the following software installed.

Component	Minimum Version	Description	Source(s)
Python	3.10+	The core programming language for the application.	`conventions.md:21`
GTK4	4.14+	The toolkit for creating the graphical user interface.	`conventions.md:22`
LibAdwaita	1.4+	Provides GNOME HIG-compliant widgets and styles.	`conventions.md:23`
Meson	-	The build system used to configure and build the project.	`CONTRIBUTING.md:80`
Ninja	-	The build tool executed by Meson.	`scripts/dev.sh:66`
blueprint-compiler	-	Used to compile `.blp` UI definition files.	`scripts/dev.sh:67`

Sources: conventions.md:20-23, CONTRIBUTING.md:80, scripts/dev.sh:65-67

Quick Start

Setting up a development environment involves forking the repository, cloning it locally, and using the dev.sh script to run the application.

Fork and Clone the repository from GitHub.
Create a new branch for your feature or bug fix.
Run the application using the development script.

# 1. Fork the repository on GitHub
# 2. Clone your fork
git clone https://github.com/YOUR_USERNAME/steam-online-fix-launcher.git
cd steam-online-fix-launcher

# 3. Create a working branch
git checkout -b my-feature

# 4. Run the application for development
./scripts/dev.sh

This command will automatically set up the build directory, compile the project, install it into a local .local directory, and run the application.

Sources: CONTRIBUTING.md:12-23

The `dev.sh` Helper Script

The scripts/dev.sh script is the primary tool for local development. It automates the entire lifecycle of configuring, building, installing, and running the application in a sandboxed local environment within the project directory.

Key Directories

The script manages two main local directories:

builddir/: The Meson build directory where all compiled artifacts are stored.
.local/: The local installation prefix where the application is installed. This mimics a system installation without requiring root privileges.

Sources: scripts/dev.sh:10-11

Commands

The script accepts several commands to perform specific actions in the development lifecycle.

Command	Description
`setup`	Configures the Meson project in `builddir` with a local prefix (`.local`) and the `development` profile.
`build`	Compiles the project using `meson compile`.
`install`	Installs the built application into the `.local` prefix and compiles GSettings schemas.
`deps`	Creates a Python virtual environment in `.venv` and installs runtime dependencies (`requests`, `pillow`, `rarfile`, `vdf`).
`smart`	(Recommended) Automatically checks if setup, build, or install steps are needed and runs them before executing the application.
`run`	Runs the application, automatically performing setup, build, and install if necessary. Can accept arguments to pass to the app (e.g., `./scripts/dev.sh run -- --search "doom"`).
`rebuild-run`	Cleans the `builddir` and then performs a full setup, build, install, and run cycle.
`shell`	Starts an interactive shell with all necessary environment variables set for development.
`clean`	Removes the `builddir` and `.local` directories.
`all`	(Default) Performs `setup`, `build`, `install`, and `run` in sequence.
`help`	Displays the usage information.

Sources: scripts/dev.sh:16-45, scripts/dev.sh:220-255

Workflow

The smart and run commands provide an intelligent workflow that avoids unnecessary rebuilds by checking file timestamps.

The following diagram illustrates the process executed by the dev.sh smart command:

Generating architecture diagram...

This diagram shows the automated workflow of the smart command, which checks for necessary setup, build, and install steps before running the application.

Sources: scripts/dev.sh:202-219, scripts/dev.sh:80-125

Environment Variables

To ensure the locally installed application can find its resources (like GSettings schemas, icons, and Python modules), the dev.sh script exports several environment variables before running the app or a shell.

GSETTINGS_SCHEMA_DIR: Points to the schemas directory within the local prefix (.local/share/glib-2.0/schemas).
XDG_DATA_DIRS: Prepends the local share directory (.local/share) to ensure local data files are found first.
PYTHONPATH: Prepends the site-packages directory from both the local prefix and the .venv (if it exists) to ensure Python can import all necessary modules.

# scripts/dev.sh

export_env() {
    # Export runtime env so the app sees local schemas/resources
    export GSETTINGS_SCHEMA_DIR="$SCHEMAS_DIR"
    # Prepend our .local/share to XDG_DATA_DIRS
    if [ -n "${XDG_DATA_DIRS:-}" ]; then
        export XDG_DATA_DIRS="$DATA_SHARE:$XDG_DATA_DIRS"
    else
        export XDG_DATA_DIRS="$DATA_SHARE:/usr/local/share:/usr/share"
    fi

    # ... PYTHONPATH setup ...
}

Sources: scripts/dev.sh:150-188

Python Dependencies

Runtime Python dependencies are managed via a local virtual environment (.venv). The deps command handles its creation and installs the required packages.

# scripts/dev.sh:140-148
do_deps() {
    require_bin python3
    if [ ! -d "$PROJECT_DIR/.venv" ]; then
        echo "[dev] creating venv: $PROJECT_DIR/.venv"
        python3 -m venv "$PROJECT_DIR/.venv"
    fi
    # shellcheck disable=SC1091
    source "$PROJECT_DIR/.venv/bin/activate"
    python -m pip install -U pip setuptools wheel
    python -m pip install requests pillow rarfile vdf
}

This ensures that development dependencies do not conflict with system-wide Python packages.

Sources: scripts/dev.sh:139-148

Code Quality and Style

The project enforces a consistent code style and quality using automated tools. Developers are expected to run these checks before committing changes.

Formatting: Black is used for automatic code formatting with a line length of 88 characters.
Type Checking: Pyright is used for static type analysis.

The following commands can be used to verify code quality:

# Check formatting
black --check .

# Check typing
pyright

These checks are also part of the quality gates in the CI/CD pipeline.

Sources: conventions.md:14, conventions.md:70-72, CONTRIBUTING.md:94-97

Development with Flatpak

For testing the application in a more isolated environment similar to production, developers can use the Flatpak build scripts. The build system supports a dedicated development mode.

To build and run a development version of the Flatpak package:

cd packaging/flatpak

# Build, install, and run the development version
./build.sh dev . dev install

This command uses the org.badkiko.sofl.Devel.yml manifest, creating a separate org.badkiko.sofl.Devel application that can be installed alongside the stable version without conflicts. The fast flag can also be added to skip dependency checks and network operations for quicker rebuilds.

Sources: packaging/flatpak/build.sh:21-26, packaging/flatpak/build.sh:230-241, packaging/README.md:37-45

Development Environment Setup

Relevant source files

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

Prerequisites

To build and run SOFL for development, your system must have the following software installed.

Component	Minimum Version	Description	Source(s)
Python	3.10+	The core programming language for the application.	`conventions.md:21`
GTK4	4.14+	The toolkit for creating the graphical user interface.	`conventions.md:22`
LibAdwaita	1.4+	Provides GNOME HIG-compliant widgets and styles.	`conventions.md:23`
Meson	-	The build system used to configure and build the project.	`CONTRIBUTING.md:80`
Ninja	-	The build tool executed by Meson.	`scripts/dev.sh:66`
blueprint-compiler	-	Used to compile `.blp` UI definition files.	`scripts/dev.sh:67`

Sources: conventions.md:20-23, CONTRIBUTING.md:80, scripts/dev.sh:65-67

Quick Start

Setting up a development environment involves forking the repository, cloning it locally, and using the dev.sh script to run the application.

Fork and Clone the repository from GitHub.
Create a new branch for your feature or bug fix.
Run the application using the development script.

# 1. Fork the repository on GitHub
# 2. Clone your fork
git clone https://github.com/YOUR_USERNAME/steam-online-fix-launcher.git
cd steam-online-fix-launcher

# 3. Create a working branch
git checkout -b my-feature

# 4. Run the application for development
./scripts/dev.sh

This command will automatically set up the build directory, compile the project, install it into a local .local directory, and run the application.

Sources: CONTRIBUTING.md:12-23

The `dev.sh` Helper Script

Key Directories

The script manages two main local directories:

builddir/: The Meson build directory where all compiled artifacts are stored.
.local/: The local installation prefix where the application is installed. This mimics a system installation without requiring root privileges.

Sources: scripts/dev.sh:10-11

Commands

The script accepts several commands to perform specific actions in the development lifecycle.

Command	Description
`setup`	Configures the Meson project in `builddir` with a local prefix (`.local`) and the `development` profile.
`build`	Compiles the project using `meson compile`.
`install`	Installs the built application into the `.local` prefix and compiles GSettings schemas.
`deps`	Creates a Python virtual environment in `.venv` and installs runtime dependencies (`requests`, `pillow`, `rarfile`, `vdf`).
`smart`	(Recommended) Automatically checks if setup, build, or install steps are needed and runs them before executing the application.
`run`	Runs the application, automatically performing setup, build, and install if necessary. Can accept arguments to pass to the app (e.g., `./scripts/dev.sh run -- --search "doom"`).
`rebuild-run`	Cleans the `builddir` and then performs a full setup, build, install, and run cycle.
`shell`	Starts an interactive shell with all necessary environment variables set for development.
`clean`	Removes the `builddir` and `.local` directories.
`all`	(Default) Performs `setup`, `build`, `install`, and `run` in sequence.
`help`	Displays the usage information.

Sources: scripts/dev.sh:16-45, scripts/dev.sh:220-255

Workflow

The smart and run commands provide an intelligent workflow that avoids unnecessary rebuilds by checking file timestamps.

The following diagram illustrates the process executed by the dev.sh smart command:

Generating architecture diagram...

This diagram shows the automated workflow of the smart command, which checks for necessary setup, build, and install steps before running the application.

Sources: scripts/dev.sh:202-219, scripts/dev.sh:80-125

Environment Variables

GSETTINGS_SCHEMA_DIR: Points to the schemas directory within the local prefix (.local/share/glib-2.0/schemas).
XDG_DATA_DIRS: Prepends the local share directory (.local/share) to ensure local data files are found first.
PYTHONPATH: Prepends the site-packages directory from both the local prefix and the .venv (if it exists) to ensure Python can import all necessary modules.

# scripts/dev.sh

export_env() {
    # Export runtime env so the app sees local schemas/resources
    export GSETTINGS_SCHEMA_DIR="$SCHEMAS_DIR"
    # Prepend our .local/share to XDG_DATA_DIRS
    if [ -n "${XDG_DATA_DIRS:-}" ]; then
        export XDG_DATA_DIRS="$DATA_SHARE:$XDG_DATA_DIRS"
    else
        export XDG_DATA_DIRS="$DATA_SHARE:/usr/local/share:/usr/share"
    fi

    # ... PYTHONPATH setup ...
}

Sources: scripts/dev.sh:150-188

Python Dependencies

Runtime Python dependencies are managed via a local virtual environment (.venv). The deps command handles its creation and installs the required packages.

# scripts/dev.sh:140-148
do_deps() {
    require_bin python3
    if [ ! -d "$PROJECT_DIR/.venv" ]; then
        echo "[dev] creating venv: $PROJECT_DIR/.venv"
        python3 -m venv "$PROJECT_DIR/.venv"
    fi
    # shellcheck disable=SC1091
    source "$PROJECT_DIR/.venv/bin/activate"
    python -m pip install -U pip setuptools wheel
    python -m pip install requests pillow rarfile vdf
}

This ensures that development dependencies do not conflict with system-wide Python packages.

Sources: scripts/dev.sh:139-148

Code Quality and Style

The project enforces a consistent code style and quality using automated tools. Developers are expected to run these checks before committing changes.

Formatting: Black is used for automatic code formatting with a line length of 88 characters.
Type Checking: Pyright is used for static type analysis.

The following commands can be used to verify code quality:

# Check formatting
black --check .

# Check typing
pyright

These checks are also part of the quality gates in the CI/CD pipeline.

Sources: conventions.md:14, conventions.md:70-72, CONTRIBUTING.md:94-97

Development with Flatpak

For testing the application in a more isolated environment similar to production, developers can use the Flatpak build scripts. The build system supports a dedicated development mode.

To build and run a development version of the Flatpak package:

cd packaging/flatpak

# Build, install, and run the development version
./build.sh dev . dev install

Sources: packaging/flatpak/build.sh:21-26, packaging/flatpak/build.sh:230-241, packaging/README.md:37-45

Development Environment Setup

Prerequisites

Quick Start

The dev.sh Helper Script

Key Directories

Commands

Workflow

Environment Variables

Python Dependencies

Code Quality and Style

Development with Flatpak

Development Environment Setup

Prerequisites

Quick Start

The dev.sh Helper Script

Key Directories

Commands

Workflow

Environment Variables

Python Dependencies

Code Quality and Style

Development with Flatpak

The `dev.sh` Helper Script

The `dev.sh` Helper Script