Briefcase Linux Flatpak Template

A Cookiecutter template for building Python apps that will run under Linux, packaged as a Flatpak.

Using this template

The easiest way to use this project is to not use it at all - at least, not directly. Briefcase is a tool that uses this template, rolling it out using data extracted from a pyproject.toml configuration file.

However, if you do want use this template directly...

1. Install cookiecutter. This is a tool used to bootstrap complex project templates:

   $ pip install cookiecutter
   

2. Run cookiecutter on the template:

   $ cookiecutter https://github.com/beeware/briefcase-linux-appimage-template
   

   This will ask you for a number of details of your application, including the [name]{.title-ref} of your application (which should be a valid PyPI identifier), and the [Formal Name]{.title-ref} of your application (the full name you use to describe your app). The remainder of these instructions will assume a [name]{.title-ref} of my-project, and a formal name of My Project.

3. Download an official Python source tarball, and place it in the My Project directory generated by the template.

4. Add your code to the template, into the My Project/src/app directory. At the very minimum, you need to have an app/<app name>/__main__.py file that defines an entry point that will start your application.

5. Add a [requirements.txt]{.title-ref} file in the root of your project, adding any dependencies of your application.

If you've done this correctly, a project with a formal name of My Project, with an app name of my-project using Python 3.10.6 should have a directory structure that looks something like:

My Project/
    icons/
        ...
    src/
        app/
            my_project/
                __init__.py
                __main__.py
                app.py
    bootstrap
    briefcase.toml
    com.example.my-project.desktop
    manifest.yml
    requirements.txt
    Python-3.10.6.tgz

This directory can then be compiled using flatpak-builder:

$ flatpak-builder --force-clean --install --user build manifest.yml

This will build and install the flatpak into your user flatpak store. The app can then be run with:

$ flatpak run com.example.my-project

Next steps

Of course, running Python code isn't very interesting by itself.

To do something interesting, you'll need to work with the native system libraries to draw widgets and respond to user input. The GTK+ GUI library provides Python bindings that you can use to build a user interface. Alternatively, you could use a cross-platform widget toolkit that supports Windows (such as Toga) to provide a GUI for your application.

If you have any external library dependencies (like Toga, or anything other third-party library), you should install the library code into the app_packages directory. This directory is the same as a site_packages directory on a desktop Python install.