Building an Application

Note

It is assumed that you have already installed the flatpak and flatpak-builder tools. See Flatpak for instructions on how to do this.

To build an application, run flatpak-builder with the build directory and manifest file as described in the Flatpak Builder documentation:

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

The documentation describes a number of ways this tool can be used to build flatpaks. Some of these are more convenient than others to use at the cost of flexibility.

Building and Installing Directly

It can be useful to quickly test that an application can be built and deployed using Flatpak. Perhaps the most convenient command for this is the command to build and install an application for immediate testing, skipping the intermediate steps related to using a local repository.

Here, we build and install the example program supplied with the libhandy library:

flatpak-builder --install _flatpak sm.puri.Handy.Demo.json

This builds the application in the _flatpak directory and installs it on the system. If the --user option is given then it only installs it for the current user. A .flatpak-builder cache directory is also created.

The application can be run using flatpak:

flatpak run sm.puri.Handy.Demo

It can then be uninstalled with this command:

flatpak uninstall sm.puri.Handy.Demo

While this approach is useful for testing, it is often necessary to export or publish the application, and this is covered in the following sections.

Building into a Local Repository

The first way of using flatpak-builder involves the use of a local repository.

In the case of the libhandy example, we can build a flatpak from the project’s examples directory with the following command:

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

This will use _flatpak as the build directory and also create a .flatpak-builder directory in the current directory. The result is stored in the myrepo directory, which is a local repository.

Creating a Bundle

Once the application has been built, it can be exported from the local repository in the form of a binary bundle by running flatpak with the build-bundle command:

flatpak build-bundle 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 other systems or installed locally:

flatpak install app.flatpak

The application can be run using flatpak:

flatpak run sm.puri.Handy.Demo

It can then be uninstalled with this command:

flatpak uninstall sm.puri.Handy.Demo

This way of building an application is very convenient when preparing flatpaks for testing on another system, such as the Librem 5 phone or development board. When building applications for devices like these that have a different processor architecture, extra options are required to ensure that the flatpaks are built correctly and have the appropriate dependencies. See Cross-Building Flatpaks for more details.

Installing from a Local Repository

The contents of the myrepo directory can be made available to the system with this command:

flatpak remote-add --no-gpg-verify my-local-repo myrepo

This gives the repository the name my-local-repo which is the remote that we use when installing the libhandy example application from it:

flatpak install my-local-repo sm.puri.Handy.Demo

The application can then be run using flatpak:

flatpak run sm.puri.Handy.Demo

It can also be uninstalled when no longer needed:

flatpak uninstall sm.puri.Handy.Demo

When there are no longer any installed applications from the local repository, the my-local-repo remote can be deleted from the list of those registerd with Flatpak on the system:

flatpak remote-delete my-local-repo

The repository itself is not deleted – the myrepo directory can still be found in the current directory.