Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Flatpak Packaging and Sandbox Model

To distribute the Weather App in a clean and reliable way, the application is packaged using Flatpak. Flatpak uses a manifest file that explains how the application should be built, which runtime environment it needs, and what permissions it requires.

In this project, the manifest file is named:

com.example.Weather.yaml

This file works like a build instruction file. It tells Flatpak how to build the Rust project, which GNOME environment should be used, and how the application should run inside a sandbox.

Flatpak is very useful for GTK4 and Libadwaita applications because it provides the same runtime environment on every Linux system. This means the Weather App does not depend on the libraries installed on the user’s computer. Instead, it runs in a controlled environment defined by the manifest.

Why Flatpak Is Used

During development, the Weather App can be run using:

cargo run

In this case, the program uses the local system libraries. This is convenient for development, but it can cause problems when the project is moved to another computer.

For example, another system might have:

  • a different GTK version
  • missing dependencies
  • incompatible libraries

Flatpak solves this problem by packaging the application with a fixed runtime environment.

For the Weather App, Flatpak ensures that:

  • the correct GNOME runtime is used
  • Rust compilation works correctly
  • the application can access the internet for API requests
  • the application can store user data such as saved_cities.csv

Because of this, Flatpak is a good solution for distributing GTK applications.

The Flatpak Manifest File

The main file used for packaging is:

com.example.Weather.yaml

This manifest file defines:

  • the application identity
  • the runtime and SDK
  • the Rust extension
  • the build commands
  • the project source
  • the permissions given to the application

In simple terms, this file tells Flatpak everything needed to build and run the Weather App.

Application Identity

At the top of the manifest file, the application ID is defined:

id: com.example.Weather

This ID uniquely identifies the application in the Flatpak system.

The ID is important because it connects to:

  • desktop integration
  • installation directories
  • the sandbox identity of the application

It should be the same or very similar to the application ID used inside the GTK application code.

Runtime and SDK

The runtime and SDK define the environment used to build and run the application.

runtime: org.gnome.Platform
runtime-version: '49'
sdk: org.gnome.Sdk

The runtime provides the libraries needed when the application runs. For GTK applications, this includes GTK, Libadwaita, and other system libraries.

The SDK provides the development environment. It includes:

  • compilers
  • development tools
  • build dependencies

So the runtime is used when the app runs, and the SDK is used when the app is built.

This makes sure the Weather App works the same on every system.

Rust SDK Extension

Since the Weather App is written in Rust, the build environment also needs the Rust compiler.

This is added with the Rust SDK extension:

sdk-extensions:
  - org.freedesktop.Sdk.Extension.rust-stable

This extension provides:

  • the Rust compiler
  • Cargo package manager

inside the Flatpak build environment.

Without this extension, commands like cargo build would not work during the Flatpak build process.

Build Commands

The build process is defined inside the modules section of the manifest.

The Weather App is built using Cargo:

build-commands:
  - cargo build --release --verbose
  - install -Dm755 target/release/weatherapp /app/bin/weatherapp

The first command compiles the Rust project in release mode.

The second command copies the compiled program into:

/app/bin/weatherapp

Inside Flatpak, /app/bin is the standard location for application executables.

This step turns the Rust project into an installable application inside the Flatpak environment.

Source Definition

The manifest also defines the project source:

sources:
  - type: dir
    path: .

This tells Flatpak to use the current project directory as the source.

Flatpak copies the project files into its own isolated build environment and then runs the build commands there.

This helps create a clean and reproducible build because the result does not depend on the developer’s local system configuration.

Permissions and Finish Arguments

Flatpak applications run inside a sandbox. By default, this sandbox blocks most system access.

The application cannot automatically access:

  • the internet
  • the display server
  • the user’s home directory

To allow necessary features, permissions must be declared in the manifest.

These permissions are defined using finish-args:

finish-args:
  - --share=network
  - --share=ipc
  - --socket=wayland
  - --socket=fallback-x11
  - --filesystem=home

These permissions allow the Weather App to use certain system resources.

For example:

  • --share=network allows internet access
  • --share=ipc allows communication between processes
  • --socket=wayland allows connection to Wayland display server
  • --socket=fallback-x11 allows fallback support for X11
  • --filesystem=home allows access to the user’s home directory

Flatpak requires developers to explicitly declare these permissions.

How This Connects to the Weather App

The Weather App runs normally with cargo run. However, when it is packaged with Flatpak, it runs inside a sandbox environment.

This means the application cannot automatically access system resources.

Instead, everything must be declared in the manifest.

For the Weather App, this includes:

  • network access to fetch weather data
  • display access to show the GUI window
  • filesystem access to save the CSV file containing cities

So the Flatpak manifest directly reflects the needs of the application.

Building the Weather App as a Flatpak

To make building easier, the project can include a small Makefile.

The Makefile helps automate the build process so developers do not need to type long commands manually.

The Makefile can:

  • install required runtimes
  • install the GNOME SDK
  • install the Rust extension
  • build the Flatpak package
  • run the application

This makes it easier for beginners to run the project.

Step 1 - Install the Build Tool

First install the Flatpak builder tool:

sudo apt install flatpak-builder

This tool reads the Flatpak manifest and performs the build process.

Step 2 - Install Dependencies

Inside the project directory, run:

make dep

This installs the required runtimes and SDK components.

Step 3 - Build and Run the Application

Now build the application using:

make

The Makefile will automatically install the required runtimes, build the application, and run it inside the Flatpak environment.

After the build finishes, a Libadwaita window should appear.

What the Makefile Does Internally

The Makefile internally runs commands similar to the following:

flatpak install --user org.gnome.Platform//49
flatpak install --user org.gnome.Sdk//49
flatpak install --user org.freedesktop.Sdk.Extension.rust-stable//25.08
flatpak-builder --user --install --force-clean repo com.example.Weather.yaml
flatpak run com.example.Weather

These commands install the GNOME runtime, the GNOME SDK, the Rust extension, and then build and run the application.

This is useful for developers who clone the repository and want to run the application quickly.

Understanding the Sandbox Model

When the Weather App is packaged with Flatpak, it does not run like a normal application. Instead, it runs inside a sandbox.

A sandbox is an isolated environment that limits access to the system.

This improves security and stability. Even if the application has a bug, it cannot freely access sensitive system resources.

What Sandboxing Means in Practice

By default, Flatpak applications cannot:

  • access the internet
  • access the user’s home directory
  • access many system resources

The developer must explicitly declare what the application needs.

In the Weather App, this is done using finish-args.

Network Permission

The Weather App fetches weather data from the Open-Meteo API.

To allow this, the manifest includes:

- --share=network

This permission allows the application to send HTTP requests.

Without this permission, the weather API requests would fail inside the Flatpak environment.

Display Server Access

GTK applications need access to a display server to show windows.

The Weather App includes these permissions:

- --socket=wayland
- --socket=fallback-x11

These allow the application to connect to Wayland or X11.

Without these permissions, the application window would not appear.

File System Access

The Weather App stores saved cities in a CSV file:

#![allow(unused)]
fn main() {
const CSV_FILE: &str = "saved_cities.csv";
}

To allow this file to be created and updated, the manifest includes:

- --filesystem=home

This allows the application to access the user’s home directory.

Without this permission, the application would not be able to save the CSV file when running inside Flatpak.

Why the Sandbox Model Matters

The sandbox model improves security because applications cannot access system resources unless permission is granted.

This ensures that:

  • applications cannot access sensitive files automatically
  • permissions are transparent
  • users have better control over installed applications
  • applications run in a predictable environment

The Weather App only requests the permissions it needs:

  • network access for API calls
  • display access for the GUI
  • home directory access for CSV storage

This makes the Weather App a good beginner example of how Flatpak packaging and sandbox permissions work together.