Concepts and Terminology¶
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 GNOME Nightly repository is
https://sdk.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://sdk.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.
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.Example.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.
--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.
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 Cross-Building Flatpaks section gives an example of how to build an application for deployment on the Librem 5.