Building my first Flatpak

bgstack15

2025-04-13 08:53

After seeing the ease of use for running Luanti in a flatpak, I wanted to try building a Flatpak. I had previously tried building an AppImage but ran into problems.

I picked a much more modest project this time: srb_tk from srb_lib, a Tkinter-based savegame editor for Snoopy vs. The Red Baron. I iterated many times (probably 4 or 5 dozen) but I did get an package built! It was fun, except for the very small things that tripped me up for way too long. I renamed the app/binary to srbsavegameeditor.

The code related to all this is that cgit link, under branch dev/build-flatpak

Humorous image of a Sony "My First Sony" tape recorder with the replaced object title "My First Flatpak"

Preparing the app

As part of building with Python, I needed to build a requirements.txt with the names of the pypi packages used, so just "Pillow." The Internet suggested that Tkinter is included in a base python package (when not provided by Devuan), which is slightly surprising because Devuan breaks it up into python3 and python3-tk.

I had to build a Makefile, so make install works. There are other buildsystems available but I know make. That whole topic is almost beyond the scope of this process. If you don't know how to build a Makefile, I'm sure there are tutorials out there. The gist is that all files from the project are placed down, usually binaries in /usr/bin, and extra contents in /usr/share/PROJECTNAME, and so on. Although flatpak seemed to want things in /app instead of /usr which threw off a few things, but nothing I couldn't solve.

I also needed a .desktop file which my app did not have yet. No biggie.

Due to how my python app loads its own libraries and images, I had to have it poke around in /app and /usr briefly to find where its files are. That was silly and there's probably a better way to handle it. This problem would look different for something not written in python.

Building the flatpak

To get flatpak-builder to work at all, I needed to install the Sdk.

flatpak install 'org.freedesktop.Sdk//24.08'

The main way to get a flatpak to build is with a com.example.rdns.appname.yml or even .json file. Apparently all the demos I found demonstrated yml, but, most files I found out there used json, and I don't know how to intrinsically convert from one to the other, so I struggled with getting attributes added to the right spots.

The main thing is to run the build command with the yml as a parameter. You can also specify where the application can be deployed as part of a flatpak repo (see the next blog post).

flatpak-builder build net.ddns.bgstack15.srbsavegameeditor.yml --force-clean --repo=/mnt/public/www/internal/repo/flatpak --verbose

During basic iteration, I would omit the --repo= parameter because it was slower than installing a very small python app. To install the app as a part of the build, add --user --install.

Also, because I used source type git, I needed to commit my branch and push for everything that wasn't just the yml file. I wonder if I should have researched pulling from . so I didn't have to commit every single iteration.

I had to add a python3-requirements.json which is a specific derivation from requirements.txt that flatpak wanted. It shows the checksums of the exact files to pull from pypi. And I found it necessary to run it in a venv. And I think all my venvs were out of date (python 3.12); I'm assuming that's why they basically no-opped the whole time. A new, fresh venv worked fine.

python3 -m venv ~/venv4-py3.13
source ~/venv4-py3.13/bin/activate
pip install flatpak-pip-generator requirements-parser
flatpak_pip_generator --requirements-file=~/dev/srb_lib/requirements.txt # generated python3-requirements.json

The metainfo.xml file was complicated. That took about the same amount of effort.

I didn't find a lot of example of the <developer id='name.rdns.again'><name>bgstack15</name></developer> in use. Most examples use the supposedly "legacy" syntax of <developer_name>asdf</developer_name>. I hate when something new like this already decides their first way of doing things is "legacy" and the linter throws warnings about it.

The requires and recommends were annoying. And I went way overboard with the content_rating but it was an experiment to see if I could get all the "unknown" values out of the gnome-software screen. And I suppose I'll never purge it of the "Uses legacy window system," because for some reason X11 is anathema to some people.

Surprising notes about building a flatpak

A flatpak needs exactly a 64x64 icon, per https://lists.freedesktop.org/archives/flatpak/2023-December/002325.html
To get icon to show up in gnome-software, I had to add the to the xml. Seems redundant, but that is what was required.
My funky Makefile requires make install DESTDIR=/app prefix='' for the app to work inside the flatpak.
I never got --filesystem=xdg-documents permissions attribute of package to work. It lists the required permission in the app store, but does not actually grant the contained app to access it. I had to do an override for that hardcoded path:
```
flatpak override --user net.ddns.bgstack15.srbsavegameeditor --filesystem=${HOME}/Documents
```
It's easy to place in a web repo (see the next blog post). I was pleasantly surprised! The docs say gpg signing is suggested, but you don't need to do that.

References

Weblinks

And for xml reference.

Knowledge Base

Preparing the app

Building the flatpak

Surprising notes about building a flatpak

References

Weblinks

Comments