Cross-Building Flatpaks

Since the Librem 5 phone is based on a processor architecture (aarch64) that is different to the architectures used by most development workstations, the way that applications are built for the phone is a bit different to the way that applications are built and tested on a workstation.

Installing Runtimes and SDKs

The first difference is that we need to explicitly install the aarch64 versions of the SDK and runtime used to build flatpaks.

For example, when using the runtimes from the Nightly GNOME Apps repository (gnome-nightly), we need to install versions of those for the aarch64 architecture:

flatpak install gnome-nightly org.gnome.Platform/aarch64 org.gnome.Sdk/aarch64

This ensures that the resources needed for applications on that architecture are available when they are built to target it.

Installing Emulators

As mentioned in the Flatpak section of the Setting up a Development Environment chapter, a version of the qemu emulator is used to help Flatpak with cross-building. This needs to be installed before applications are built for the target architecture. On Debian-based systems, this command will install the relevant package:

sudo apt -y install qemu-user-static

It should not be necessary to perform any further configuration on your workstation if you are using a recent distribution of GNU/Linux.

Cross-Building an Application

As in the Building an Application section, flatpak-builder is used to build an application for deployment in a flatpak. The command used to do this now includes the --arch option:

flatpak-builder --arch=<arch> --repo=<repo> <build-dir> <manifest>

In the case of the Librem 5, <arch> is aarch64.

The example used previously is the example program supplied with the libhandy library, which we now build with the additional option:

flatpak-builder --arch=aarch64 --repo=myrepo _flatpak sm.puri.Handy.Demo.json

The result is stored in the myrepo directory, which is a local repository.

Note that we did not try to use the --install option to build and install the application locally. This would only make sense if the workstation we are using has an aarch64 architecture.

Creating a Bundle

Following the general advice for building flatpaks given earlier, we can export a binary bundle from the local repository so that it can be tested on the target system:

flatpak build-bundle --arch=aarch64 myrepo app.flatpak sm.puri.Handy.Demo

This builds a bundle called app.flatpak from the application referred to by sm.puri.Handy.Demo from the myrepo directory. This bundle can be copied to the phone or development board for testing.

Deploying a Bundle for Testing

Before the application can be installed on the target system, both Flatpak and the appropriate runtime must be installed. Flatpak should already be installed on the Librem 5 and the Librem 5 development board. However, if you need to install it again, the following command will do this:

sudo apt -y install flatpak

Flatpak on the target system will need to know about the remotes you used to build the application. For example, if you used the Nightly GNOME Apps repository (gnome-nightly) then this will need to be registered:

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

We do this with the --user option for convenience. It can also be added to the system-wide list of remotes if sudo is used instead.

This bundle can now be installed, again as a normal user:

flatpak --user install app.flatpak

Flatpak will resolve the dependencies of the bundle using the remote we registered and begin to install them if they are not already present, before installing the application itself.

The application can then be run using flatpak in the usual way:

flatpak run sm.puri.Handy.Demo

The commands for managing applications, runtimes and remotes are all the same on the target system as they are on the workstation.