Concepts and Terminology

This document tries to give an overview of the concepts and terminology used by Flatpak. A more comprehensive guide can be found in the Basic concepts section of the Flatpak documentation.

Repositories and Remotes

Applications are stored in repositories, either locally on the user’s system or on remote servers. Repositories are referred to by remotes which are just names that are used to identify repositories.

For example, the location of the Nightly GNOME Apps repository is https://nightly.gnome.org/gnome-nightly.flatpakrepo but it is typically referred to using the remote, gnome-nightly, when the user or system administrator adds the remote to their system:

flatpak remote-add --if-not-exists gnome-nightly https://nightly.gnome.org/gnome-nightly.flatpakrepo

Once a remote has been associated with a repository it is used to refer to it instead of the URL used for the repository itself.

Runtimes and SDKs

When an application is prepared for distribution as a flatpak it is built against a particular runtime. This is a collection of libraries and resources that the application will need when it is run. The flatpak contains information about the runtime that it uses so that it can be installed when the flatpak itself is installed on the phone.

An application is built using a particular SDK which contains the tools needed to build the application for the corresponding runtime. SDKs are just runtimes that contain these specialized tools and libraries.

If you are building applications based on GNOME technologies you will need to install the relevant runtime and SDK, as described in Setting up Flatpak for GNOME Development.

Manifests

A Flatpak manifest is a JSON file that contains information about the application, the resources it needs to run, and what permissions it needs. It also contains information about its build environment and dependencies, describing how Flatpak should obtain the code for them and which build system it should use to build them.

For example, the libhandy library is supplied with an example program in its examples directory that can be built and packaged as a flatpak using its sm.puri.Handy.Demo.json manifest file.

User and System Installations

Runtimes and applications can be installed system-wide so that all users can access them. They can also be installed on a per-user basis so that each user has their own collection of applications while still being able to access those on the system.

The --user option passed to flatpak-builder tells the tool to use the runtimes installed in the user’s own collection when building a flatpak. The same option can also be used with the flatpak tool to install an application just for that user. If you run the tools without this option then they will ask you for authentication if you are performing an operation such as installation that requires modification of the system-wide collection of runtimes and applications.

Architectures

By default, flatpaks are built for the processor architecture of the system that builds them. Since the Librem 5 uses a 64-bit ARM architecture, it is usually necessary to specify this when building flatpaks for the phone or development board. This is done by passing the --arch=aarch64 option to the flatpak and flatpak-builder tools.

The Cross-Building Flatpaks section gives an example of how to build an application for deployment on the Librem 5.