Packaging the Application

The app directory contains a com.example.first_application.json manifest file for use with Flatpak. This describes where the application source code can be obtained from, how the application is built, the dependencies that need to be built with it, and the permissions it needs when it is run.

Writing the Manifest

The manifest for this simple application is short, so we include the whole file here to provide an overview before looking at the details:

{
    "app-id": "com.example.first_application",
    "runtime": "org.gnome.Platform",
    "runtime-version": "3.34",
    "sdk": "org.gnome.Sdk",
    "command": "your-first-application",
    "finish-args": [
        "--socket=wayland"
    ],
    "modules": [
        {
            "name": "first_application",
            "buildsystem": "meson",
            "builddir": true,
            "sources": [
                {
                    "type": "dir",
                    "path": "."
                }
            ]
        }
    ]
}

We examine the three main parts of the manifest individually.

Application Information

In the manifest we record information about the application, including its ID and the command used to run it:

{
    "app-id": "com.example.first_application",
    "runtime": "org.gnome.Platform",
    "runtime-version": "3.34",
    "sdk": "org.gnome.Sdk",
    "command": "your-first-application",

The runtime and runtime-version values define precisely which collection of libraries the application needs to run. The corresponding sdk value tells Flatpak which SDK is needed to build the application. When building applications for a GNOME-based platform the corresponding SDK is required.

Permissions

The finish-args list is typically used to state which permissions the application needs. In this case it will need access to the Wayland display server to be able to show a window:

    "finish-args": [
        "--socket=wayland"
    ],

Other permissions will be required if you want to store and modify settings for your application, access peripherals, and perform other tasks that require the user’s consent.

Modules

The modules list describes the application components (or modules), including any dependencies that need to be bundled with it, in a list of dictionaries:

    "modules": [
        {
            "name": "first_application",
            "buildsystem": "meson",
            "builddir": true,

The name of the application should be unique in the list of modules but can be otherwise freely assigned. We indicate that we are using the Meson build system and instruct Flatpak to use a separate build directory.

After this, we describe where the sources of the application should be obtained from. For many applications we would describe the location of a repository. However, to make things simple, we indicate that the sources are in the same directory as the manifest:

            "sources": [
                {
                    "type": "dir",
                    "path": "."
                }
            ]
        }
    ]
}

This concludes the description of the main (and only) module.

Building the Application

Following the instructions in Cross-Building an Application, we use flatpak-builder to build a flatpak for the application. To do this we need to install the runtime and SDK that the application depends on. These are the same as those mentioned in Setting up Flatpak for GNOME Development except that we need the ones for the aarch64 architecture:

flatpak --user install flathub org.gnome.Platform/aarch64/45 org.gnome.Sdk/aarch64/45

After installing these, build the application with flatpak-builder:

flatpak-builder --arch=aarch64 --repo=myrepo _flatpak com.example.first_application.json

The result is stored in the myrepo directory, which is a local repository. It can be exported from the repository as a binary bundle for deployment on the target device. We do this by running flatpak with the build-bundle command, passing the repository, the name of the bundle to create and the application ID:

flatpak build-bundle --arch=aarch64 myrepo app.flatpak com.example.first_application

In this case the bundle is written to the app.flatpak file. This can be copied to the phone or development board for installation.

Installing the Application

One way to install the application is to use the flatpak tool on the command line to install the binary bundle. Other more user-friendly ways are also possible.

First of all, copy the bundle to the target device and make it readable by the purism user. Then, log in to the device and ensure that the flathub remote is registered for the user:

flatpak --user remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

Assuming that the app.flatpak file is in the current directory, install it for the user by running the install command:

flatpak --user install app.flatpak

Flatpak will resolve the dependencies of the bundle using the remote we registered and ask you if you want to install them if they are not already present. It will then install the application itself.

You can run the application using flatpak in the usual way:

flatpak run com.example.first_application

When you are finished with the application and want to uninstall it, use the following command:

flatpak uninstall com.example.first_application

You can also uninstall the runtime needed by the application, but it may be useful to keep it installed for future use.