Developing With The Flatpak CLI

Flatpak is a very powerful tool for development, and is well-integrated into GNOME Builder. This is what I’d recommend for most developers. But what if you use a plain text editor? Barring Visual Studio Code, there aren’t many extensions for common text editors to use flatpak. This tutorial will go over how to use flatpak to build and test your apps with only the command line.

Building & Testing Your App

First, you’ll need to have flatpak installed and a flatpak manifest. You’ll also need the right runtime and SDK installed. Then, you’ll need to set up the environment to build your application. Navigate to your project directory from the terminal. Once there run the following command:

# $MODULE_NAME is the name of your application's flatpak module
$ flatpak-builder --repo=repo --build-only --stop-at=$MODULE_NAME --force-clean flatpak_app $APP_ID.json

This will fetch all the dependencies declared in the flatpak manifest and build each one, stopping with your app. Then, you need to use flatpak build to run the build commands for your application.

First you configure the buildsystem:

# $CONFIG_OPTS should match the `config-opts` for the module in your flatpak manifest
$ flatpak build --filesystem=host flatpak_app meson _build --prefix=/app $CONFIG_OPTS

Then run the build & install command:

# $BUILD_OPTS should match the build-options in the flatpak manifest.
# `append-path` turns into `--env=PATH=$PATH:$APPEND_PATH`
$ flatpak build --filesystem=host $BUILD_OPTS flatpak_app ninja -C _build install

After that, you can also use flatpak build to test the application:

# $FINISH_ARGS would be the `finish-args` from your flatpak manifest
$ flatpak build --filesystem=host $FINISH_ARGS flatpak_app $APP_EXECUTABLE_NAME

Creating Dist Tarballs

One of the responsibilities an app maintainer has is creating tarballs of their applications for distribution. This can be challenging, as the maintainer needs to build using an environment that has all dependencies – including versions of dependencies that aren’t yet released.

Flatpak allows for developers to do this in a simple way. If you haven’t run the
command above to fetch and build your dependencies, do so now.
Also run the configuration step. Now you should be ready to run the dist command:

$ flatpak build --filesystem=host flatpak_app ninja -C _build dist

Now you should have a release tarball ready in _build/meson-dist.


While this method works for development, it’s a bit clumsy. I highly recommend using GNOME Builder or Visual Studio Code with the flatpak extension. These tools handle the clumsiness for you, allowing you to focus entirely on development. However, if you find yourself wanting to develop using flatpak and don’t want to use either of the above options, this is the way to do so.

Developing GNOME: The Basics

I’ve been working in the GNOME community for a little under a year and a half now. During my time contributing to the project, I’ve seen a lot of misunderstandings from the community about how we work. So, I’ve decided to write a multi-part series on how development on GNOME works.

This first post will cover the basics. In future I’ll explain our tooling, how apps are created, and how changes happen across the ecosystem.

The Release Cycle

At the center of GNOME development is the release cycle. Every 6 months we put out a major release, with patch releases in-between. Major releases typically happen in September and March, and are named after the city of the most recent conference. GNOME 3.30 was named after the city we held GUADEC in, and 3.32 is named after where GNOME.Asia took place.

At different intervals in the cycle we have freeze periods, after which no changes can be made to certain parts of the code. Core apps, such as Web, Files, and Settings all strictly follow the release cycle and freezes. Apps outside of the core set like Polari, Builder, and Fractal can follow their own schedules or versioning schemes, but tend to put out releases alongside the GNOME core.

The freeze deadlines often determine what contributions make it into a release. For example, if a UI change is submitted after the UI freeze, maintainers need to seek approval from the Design and Release teams before the change can be merged. Freezes are staggered, and come in the following order:

  • UI, Feature, and API/ABI Freezes
  • String Freeze
  • Hard Code Freeze

The hard code freeze ends once the major release for the cycle is out. If you want to apply a change that violates the other freezes, you need to create a branch for the latest stable release. So, if I need to merge a UI change after the 3.32 release is out, I need to first create a gnome-3-32 branch before I accept the change onto master. This branch will then be used to cherry-pick changes for the 3.32.X releases.

How Apps Are Maintained

Each project within GNOME has its own developers. The Music developers aren’t necessarily the same people working on the Shell, and the Shell developers generally aren’t the same people working on GTK. While many developers work across the ecosystem on different projects, there is no one team of developers. This is why “GNOME decided such and such” is often inaccurate.

The maintainers of a project have full say over what contributions are or are not accepted. While certain things can be proposed, maintainers have the right to reject proposals. This is, for example, is why Terminal did not have a HeaderBar until 3.32 and doesn’t enable it by default. Nobody is forced to do anything, but often developers and designers will agree on a direction for an app, or the ecosystem at large.

Contrary to popular belief, most maintainers are not paid by Red Hat although some core components like Files and GNOME Shell do have Red Hat employees employed to work on them. Other companies such as Canonical, Purism, and Endless employ developers to work on the parts of the stack that matter to them. That said, most contributors are not on company time even if they are employed by the likes of Red Hat. And of course those that are employed to work on GNOME still aren’t paid for all of their work on GNOME. Most of our work is done on our own time, as limited by the rest of our lives.

It’s also worth noting that GNOME is built with a wide range of technologies; while GTK is written exclusively in C, Music is a Python project and Calculator is implemented with Vala. The Python developers working on Music are great with Python and GStreamer, but they aren’t going to be much help fixing a rounding error in Calculator as a general rule, and as volunteers it wouldn’t be fair to expect them to be, either.

tl;dr: GNOME is a community of individuals each with their own motivations and vision for their own part of the project doing their best to build a great platform for users.