Awesome

Monomer Flatpak Example

A demonstration of the Monomer framework running inside Flatpak.

Flatpak provides a relatively easy way to deploy apps on Linux, using a standard package format that works on any supported Linux distrubution. It has runtime sandboxing and a "portals" system for access to the underlying operating system: this promises to be particularly useful for Monomer, because it provides things like file choosers that Monomer does not have natively.

The Flatpak manifest generated for this app builds everything from source. This is necessary to distribute the app on Flathub. If you don't care about Flathub and just want to distribute a standalone Flatpak with a binary executable inside it, then a Flatpak app bundle might be easier.

Current Status

The basic app is working as a Flatpak and has also been published onto Flathub. The app includes a basic portals demo.

How It Works

• A patched version of cabal-flatpak is used to generate the basic Flatpak manifest.
• Then an extra build step is injected that installs metadata files needed by Flathub.
• The process is automated in generate-manifest.sh, and is also setup to run via a Github action.
• The generated manifest can then be tested locally:

  FLATPAK=~/flatpak
  
  # build the flatpak manifest and install into a local repository
  flatpak-builder --force-clean --repo=$FLATPAK/repository --state-dir=$FLATPAK/builder/ $FLATPAK/build/io.github.Dretch.MonomerFlatpakExample flatpak/io.github.Dretch.MonomerFlatpakExample.yml
  
  # point our local flatpak at our local repository, and install the app from it
  flatpak --user remote-add --no-gpg-verify home-repository $FLATPAK/repository
  flatpak --user --reinstall install home-repository io.github.Dretch.MonomerFlatpakExample
  
  # finally run the app
  flatpak run io.github.Dretch.MonomerFlatpakExample
  

• You can also publish on Flathub, by following the normal process.

Portals

The XDG Desktop Portals APIs allow reading/writing files, accessing microphones/webcams, opening URIs, printing, etc. This app includes some buttons to demonstrate basic portal functionality (provided via the desktop-portal library).

Building a Flatpak bundle locally

It can sometimes be useful to build a Flatpak bundle locally, without first publishing to Hackage. This is possible without too many hacks, by building a regular executable and bundling that straight into a Flatpak, along with the assets. It does require an extra manifest though.

For example, to build and run this project locally:

# compile the executable and assets into files that can be injected into the flatpak bundle
stack clean --full
stack --local-bin-path flatpak/binary install
tar -cf flatpak/binary/assets.tar assets/*

# build a manifest that refers to the executable and assets, rather than the source code
flatpak-builder --user --install --force-clean flatpak/binary/build flatpak/io.github.Dretch.MonomerFlatpakExample.binary.yml

# run the app
flatpak run io.github.Dretch.MonomerFlatpakExample.binary

FAQs

• Q. How to load fonts/images within the app?
• A. Use the normal Cabal mechanism (for example, see how the fonts are loaded in this app).
• Q. How to install an application launcher for the app?
• Q. Put a .desktop file and icon file into your Cabal package and then install them into the right place in the Flatpak using cleanup-commands in the manifest.
• Q. How to install AppStream (app store) metadata?
• A. This can be done just like the desktop file, see this app for an example.
• Q. Why do we need a patched cabal-flatpak?
• A. The patches make cabal-flatpak include library executables (alex, happy, c2hs) into the Flatpak manifest. The author will try and get this change upstreamed.
• Q. Can portals be tested without building the Flatpak?
• A. Yes! The portal APIs work from regular executables, so long as your desktop environment supports portals.

Gotchas

• Flatpak is Linux only, whereas Monomer itself also works on Windows and MacOS.
• This process requires your application (not just the libraries it depends on) to be published on Hackage - this might not be something you would otherwise bother with. Changes to cabal-flatpak could in theory avoid this requirement - since Flatpak could pull directly from Git tags rather than from Hackage.
• All the libraries your app needs must be on Hackage too. Again in theory you could use Git to work around this.
• If any of the Haskell libraries your app depends on are building executables, these will be included in the Flatpak too, increasing the size. You will probably need to add the executables to cleanup to avoid this (see the manifest template for this example).
• Building the Flatpak the first time is really slow. Subsequent builds will be a bit faster, though.
• This project is currently x86_64 only, because the author lacks any other machines to test on (if you can test on other architectures, please open an issue/PR).

Development Guide

To format the source code

# Should use Ormolu 0.7.3.0
ormolu --mode inplace $(find app -name '*.hs')