Tips & Tricks

Debugging

To debug a flatpak application, these steps might be helpful:

1. install the SDK, for example with flatpak --user install gnome-nightly org.gnome.Sdk. This is needed to have debug symbols. Omit the --user flag and change the repo if necessary.
2. open a flatpak debug shell, for example with sh: flatpak run -d --command=sh org.gnome.Gitg. You might want to choose a different shell or start a different application.
3. in this shell, run gdb gitg or replace gitg with the application you chose in step 2.

Debugging a failing build

If you're using flatpak-builder and some module mysteriously fails to build, you can get a shell in the build tree by using:

host $ flatpak-builder --run appdir org.my.Manifest.json sh
sh-4.3$ cd /run/build/failed-modulename

Now you're in a shell with the build directory and can start debugging the failure.

Note: Only the failed module build directory will be there to look at. If you specify --keep-build-dirs to flatpak-builder you can also see the other build dirs.

Running/Testing an uninstalled application

If you've just built an application and want to test it, you don't have to export the appdir to a repo and then install it. Instead you can use flatpak build appdir bash to get a shell in the application, so you can test it.

Note: This will be a typical "build" environment, so the app may not have access to all the permissions it requests. If you need these you have to manually specify them again. If you're using flatpak-builder to build the app you can use the flatpak-builder --run helper which will automatically call flatpak build with all the finish-args that your manifest specified.

Testing an app with a different runtime

You can (for testing) run an application with a different runtime than it typically uses. For instance, to run stable gedit with the latest unstable gnome runtime you can do:

flatpak run --runtime-version=master org.gnome.gedit

You can also use a completely different runtime (but same version number):

flatpak run --runtime=org.gnome.Sdk org.gnome.gedit

Note: If you just want to use the sdk instead of the platform like the above, a better approach is to use -d.

Downgrading

It is possible to install an older build of an application (or runtime). Currently, this involves the ostree commandline utility.

Here is an example of it can be done. In the example, /var/lib/flatpak/ is the (system-wide) flatpak installation where the application is installed, recipes is the name of the remote, and app/org.gnome.Recipes/x86_64/master is the flatpak ref, which is used as the ostree branch name.

First, you pull older revisions into the ostree repository:

ostree --repo=/var/lib/flatpak/repo \
       pull --depth=250 --commit-metadata-only \
       recipes app/org.gnome.Recipes/x86_64/master

Then, you look for the commit you are interested in:

ostree --repo=/var/lib/flatpak/repo \
       log app/org.gnome.Recipes/x86_64/master

Finally, you deploy the commit:

flatpak update \
    --commit=ec07ad6c54e803d1428e5580426a41315e50a14376af033458e7a65bfb2b64f0 \
    org.gnome.Recipes

Building 32-bit apps

Flatpak repositories can easily host builds for multiple architectures. An interesting case is hosting both x86_64 and i386 builds in the same repository. Since it is very easy, here are the steps to do it:

Make sure you have the i386 version of the sdk installed:

flatpak install gnome org.gnome.Sdk/i386/3.24

Build your application like before, but add --arch=i386 to the flatpak-builder invokation:

flatpak-builder --force-clean --repo=repo --ccache \
                --arch=i386 \
                --gpg-homedir=gpg --gpg-sign=${RELEASE_GPG_KEY} \
                --from-git=git://git.gnome.org/recipes --from-git-branch=master \
                recipes flatpak/org.gnome.Recipes.json

Note that you only need to call flatpak build-update-repo once, after building all architectures:

flatpak-builder --force-clean --repo=repo --ccache \
                --gpg-homedir=gpg --gpg-sign=${RELEASE_GPG_KEY} \
                --from-git=git://git.gnome.org/recipes --from-git-branch=master \
                recipes flatpak/org.gnome.Recipes.json
flatpak-builder --force-clean --repo=repo --ccache \
                --arch=i386 \
                --gpg-homedir=gpg --gpg-sign=${RELEASE_GPG_KEY} \
                --from-git=git://git.gnome.org/recipes --from-git-branch=master \
                recipes flatpak/org.gnome.Recipes.json
flatpak build-update-repo --generate-static-deltas \
                          --gpg-homedir=gpg --gpg-sign=${RELEASE_GPG_KEY} \
                          repo

Note that if you use --require-changes when doing several builds for different architectures from the same git commit, you may see some scary git output in the log about 'detached HEADs' - those are safe to ignore here.