Cross-Building.rst 4.3 KB
Newer Older
1 2 3 4 5
.. _`cross_building_flatpaks`:

Cross-Building Flatpaks
=======================

6 7 8
.. contents::
   :local:

9
Since the Librem 5 phone is based on a processor architecture (aarch64) that is
David Boddie's avatar
David Boddie committed
10 11 12
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.
13 14 15 16

Installing Runtimes and SDKs
----------------------------

David Boddie's avatar
David Boddie committed
17 18 19
The first difference is that we need to explicitly install the aarch64 versions
of the SDK and runtime used to build flatpaks.

20 21 22
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::
23 24 25 26

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

This ensures that the resources needed for applications on that architecture
David Boddie's avatar
David Boddie committed
27
are available when they are built to target it.
28 29 30 31

Installing Emulators
--------------------

David Boddie's avatar
David Boddie committed
32 33
As mentioned in the :ref:`dev_env_flatpak` section of the
:ref:`development_environment` chapter, a version of the `qemu`_ emulator is
34 35 36 37 38 39 40 41 42
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.

David Boddie's avatar
David Boddie committed
43 44
.. Some people mention binfmt and restarting systemd-binfmt.service.

45 46
.. _`cross_building_flatpaks_app`:

47 48 49 50 51
Cross-Building an Application
-----------------------------

As in the :ref:`building_flatpaks_building` section, ``flatpak-builder`` is
used to build an application for deployment in a flatpak. The command used to
David Boddie's avatar
David Boddie committed
52
do this now includes the ``--arch`` option::
53 54 55 56 57 58 59 60

   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::

Guido Gunther's avatar
Guido Gunther committed
61
   flatpak-builder --arch=aarch64 --repo=myrepo _flatpak sm.puri.Handy.Demo.json
62

David Boddie's avatar
David Boddie committed
63
The result is stored in the ``myrepo`` directory, which is a local repository.
64 65 66 67 68 69 70 71 72 73 74 75

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::

Guido Gunther's avatar
Guido Gunther committed
76
   flatpak build-bundle --arch=aarch64 myrepo app.flatpak sm.puri.Handy.Demo
77 78

This builds a bundle called ``app.flatpak`` from the application referred to by
Guido Gunther's avatar
Guido Gunther committed
79
``sm.puri.Handy.Demo`` from the ``myrepo`` directory. This bundle can be
80 81 82 83 84 85 86 87 88 89 90 91 92
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
93 94
build the application. For example, if you used the `Nightly GNOME Apps`_
repository (``gnome-nightly``) then this will need to be registered::
95

96
   flatpak --user remote-add --if-not-exists gnome-nightly https://nightly.gnome.org/gnome-nightly.flatpakrepo
97 98 99 100 101 102 103 104 105 106 107 108 109 110

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::

Guido Gunther's avatar
Guido Gunther committed
111
   flatpak run sm.puri.Handy.Demo
112 113 114 115

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

116
.. include:: /links.txt