Building flatpaks from manifests

This guide will help you build Flatpak applications on your Linux phone using manifest files. This way you can try apps, that are not packaged for your distribution and or not on Flathub yet.¹

Note: Building locally on device can stress the device to varying degree. So if you are building a Rust app, make sure that you are able to keep your phone cool to avoid damaging it. On the other hand, if it's pure Python, there's very likely no need to worry.

Installing flatpak-builder

Before you can build Flatpak applications, you'll need to install the flatpak-builder tool on your device. The installation process varies depending on your distribution.

Alpine Linux / postmarketOS

# Install flatpak and flatpak-builder
doas apk add flatpak flatpak-builder

# Add the Flathub repository
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

# Restart your device to ensure proper system integration

Arch Linux ARM

# Install flatpak and flatpak-builder
sudo pacman -S flatpak flatpak-builder

# Add the Flathub repository
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

# Enable the Flatpak systemd socket
sudo systemctl enable --now flatpak-system-helper.service

Debian / Ubuntu

# Install flatpak and flatpak-builder
sudo apt update
sudo apt install flatpak flatpak-builder

# Add the Flathub repository
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

# You may need to log out and back in for the integration to take effect

Fedora

# Install flatpak and flatpak-builder
sudo dnf install flatpak flatpak-builder

# Add the Flathub repository
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

NixOS

Add the following to your configuration.nix file:

# Enable flatpak in your configuration
services.flatpak.enable = true;

# Add flatpak-builder to system packages
environment.systemPackages = with pkgs; [
  flatpak-builder
];

Then rebuild your system:

sudo nixos-rebuild switch

# After rebuilding, add the Flathub repository
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

Installing SDKs and Platforms

After installing flatpak-builder, you'll need to install the SDK and runtime needed for building applications. If you're not sure, just check the manifest for the platform and version you will need.

# Install the basic GNOME SDK and Platform (latest stable version recommended)
flatpak install flathub org.gnome.Sdk
flatpak install flathub org.gnome.Platform

# For KDE applications, install the KDE SDK and Platform
# Note: Must match the Qt version specified in the project
flatpak install flathub org.kde.Sdk


# Other FreeDesktop applications (if you're installing a KDE
flatpak install flathub org.freedesktop.Sdk

Recommendation: Always try to use the latest SDK versions when possible, as they include security updates, newer dependencies, and better overall compatibility with modern applications. In our experience, replacing the stated version with the latest of said SDK/Platform works pretty often - but it certainly won't work all the time. You can also try and update other build dependencies if these are outdated. If you run into build-failures, always first try to understand what the issue could be before bothering project maintainers. Sometimes pasting the error you're getting into a search engine is enough.

Building Flatpaks from Manifests

Now you're ready to build Flatpak applications from manifest files.

Identifying manifest files

Flatpak manifest can often be found in the main directory of the apps code repository. This is often the case for KDE apps, where it sometimes is called .flatpak-manifest.json, e.g., with Powerplant, or GNOME apps, where the filename is often in line with the app id, e.g, with High Tide. Other common locations are folders called .build-aux or flatpak.

(If there's no flatpak manifest, you can comnsider creating one and submitting it upstream - but that's beyond the scope of this post.

Basic Building Process

# Clone a repository containing a Flatpak manifest or create your own
git clone ...
cd appname

# Build the application using flatpak-builder
flatpak-builder --user --install --force-clean build-dir com.example.App.json

# Run the built application
flatpak run com.example.App

Building Against a Specific SDK Version

If a manifest specifies an older SDK version, consider updating it to use a newer SDK version for features, fun profit and saving disk-space. Here's an example for a GNOME app:

# Open the manifest file
vim com.example.App.json  # or com.example.App.yml

# Update the SDK version (look for the "runtime-version" field)
# Change: "runtime-version": "46"
# To:     "runtime-version": "47"

Recommendation: When building applications, try to use a single SDK version for all your apps to conserve disk space. For example, standardize on GNOME SDK 47 instead of maintaining both 46 and 47. This reduces duplication of libraries and dependencies.

Example Manifest Editing

Here's a simple example of updating a manifest from GNOME 46 to GNOME 47:

{
  "app-id": "com.example.App",
  "runtime": "org.gnome.Platform",
  "runtime-version": "47",  // Updated from 46
  "sdk": "org.gnome.Sdk",
  "command": "example-app",
  // rest of manifest...
}

Memory and Space Considerations for Phones

Linux phones often have limited resources, so consider these build options:

# Build with fewer parallel jobs to avoid memory issues
flatpak-builder --jobs=2 --user --install build-dir com.example.App.json

# If you're extremely limited on space, use a temporary directory on external storage
flatpak-builder --user --install --build-dir=/path/to/external/storage/build-dir build-dir com.example.App.json

Optimizing Disk Space

Flatpak development can consume significant disk space. Here are techniques to keep your storage usage under control:

Remove Unused Runtimes and SDKs

# List all installed runtimes and SDKs
flatpak list --runtime

# Remove unused applications and runtimes
flatpak uninstall --unused

Repair Flatpak Installations

If you encounter issues or suspect corruption, run the repair command:

# Verify and repair the Flatpak installation
flatpak repair

# For more extensive repairs, you can try
flatpak repair --system

Clean Build Directories

# Remove old build directories after successful builds
rm -rf build-dir

# Or use the --delete-build-dirs option when building
flatpak-builder --delete-build-dirs --user --install build-dir com.example.App.json

Use a Shared Cache

For multiple builds, you can use a shared cache:

# Create a cache directory
mkdir -p ~/.cache/flatpak-builder

# Use the cache when building
flatpak-builder --ccache --user --install build-dir com.example.App.json

Advanced Tips for Mobile Devices

Optimize for Battery Life During Builds

# Use lower CPU priority for builds
nice -n 19 flatpak-builder --user --install build-dir com.example.App.json

# For longer builds, consider using the 'nohup' command to continue building if your terminal session closes (or just run your build session in tmux)
nohup flatpak-builder --user --install build-dir com.example.App.json &

Dealing with Limited RAM

# Enable swap if you don't have it already
sudo swapon -s  # Check if swap is enabled

# If not enabled and you're low on RAM, create a temporary swap file
sudo dd if=/dev/zero of=/swapfile bs=1M count=1024  # Creates 1GB swap file
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# After building, you can remove it
sudo swapoff /swapfile
sudo rm /swapfile

Troubleshooting

Common Build Errors

1. Missing Dependencies:

   flatpak-builder --user --install --force-clean build-dir com.example.App.json
   

   If you encounter missing dependency errors, make sure you have the correct SDK installed. Depending on the programming language, this may also occur if you miss the specific SDK extension.

Note: Sometimes the error message will give you a non-existing version of SDK, e.g. a version "47" of org.freedesktop.Sdk.rust-stable or something. In that specific case 24.08 is the correct version.

2. Network Issues: Network connectivity can be intermittent on mobile devices. Use the --download-only option first to download all dependencies before building:

   flatpak-builder --download-only build-dir com.example.App.json
   flatpak-builder --user --install --force-clean build-dir com.example.App.json
   

3. Out of Disk Space: You can run the following disk cleanup commands.

   flatpak uninstall --unused
   flatpak repair
   

   Another way to save disk space with flatpaks is reducing the number of configured languages/locales, to avoid installing a bunch of translations you do not use or need.

Tell us about your progress and contribute upstream!

If you've successfully built a Flatpak application that works well on Linux phones and that's not listed, consider sharing it in our Matrix chat! If you've made changes/improvements, make sure to submit them to the respective projects. The best way to do so is submitting your changes via pull request (PR), merge request (MR) or as patch via email, depending on the code forge. Opening an issue and attaching the files you've edited can be an alternative if you're not familiar with git (but... please learn git!).

Make sure to always be kind and understanding, as reviewing your work is also work for the maintainer. Even if everything seems fine with your changes on your side, there may be numerous reasons for the maintainer to not be accepting your change immediately.

Further Resources

• Flatpak Documentation
• Flatpak Builder Reference
• Flathub Submission Guidelines

Edit this page on Framagit