PIKApp/build/flatpak/README.md

# PIKA Flatpak HowTo

## Stable and Development releases

The Flathub repository hosts our stable and development point releases:
https://github.com/flathub/technology.heckin.PIKA

We recommend to look at the `README.md` file in respectively the `master` or
`beta` branches of this repository to know more about release procedures.

## Nightly builds

Flathub does not host nightly builds, therefore we publish them on GNOME's
Nightly repository. Our "nightlies" are actually "weeklies" through a [Gitlab job
schedule named "Flatpak
nightly"](https://gitlab.gnome.org/GNOME/pika/-/pipeline_schedules).

This job will build whatever is on PIKA's repository `master` branch (this
branch should be kept buildable and usable at all time, not only for scheduled
jobs, but also for all contributors to be able to improve PIKA at all time).

The nightly manifest file is: `build/flatpak/technology.heckin.PIKA-nightly.json`

This file should remain as close as possible to the development manifest
(`technology.heckin.PIKA.json` file on the `beta` branch of the Flathub repository) which
itself should remain as close as possible to the stable manifest
(`technology.heckin.PIKA.json` file on the `master` branch of the Flathub repository),
since the nightly manifest is meant to become beta eventually, which itself is
meant to become stable eventually.

Base rule to update the nightly build manifest:

* Regularly `technology.heckin.PIKA-nightly.json` should be diffed and synced with
  development and stable `technology.heckin.PIKA.json`, in particular for all the
  dependencies (which are mostly the same across all 3 builds).
* A merge request with the label `5. Flatpak package` will contain the `flatpak`
  job, hence allowing theoretically to build a standalone flatpak (without being
  published to the nightly repository) for MR code. In practice, jobs have an
  1-hour timeout and our flatpak takes longer than 1 hour to build (there is an
  exception in our repository, but only for the `master` branch), so we often
  need to publish to `master` after mostly a visual review.

## Custom Flatpak builds (for development)

Most contributors simply build PIKA the "old-school" way, nevertheless some
projects are starting to use `flatpak` as a development environment. Here is how
this can be done, as far as our knowledge goes.

Note 1
: The below process is about using flatpak as a development environment, not for
  proper [releases to a
  repository](https://docs.flatpak.org/en/latest/flatpak-builder.html), neither
  for creating [standalone
  bundles](https://docs.flatpak.org/en/latest/single-file-bundles.html)

Note 2
: since we usually only use flatpak for releases, not for development, there may
  be better ways to make a flatpak development environment. We welcome any
  proposed improvement to this file.

* Dependencies:
  - flatpak (at least 0.9.5)
  - flatpak-builder (at least 0.9.5, when the option `--export-only` has been
    added to `flatpak-builder` so that the build and the export can be made in 2
    separate steps while using the high level procedure.)
  - appstream-compose

  Note 1
  : there are packages of `flatpak` and `flatpak-builder` for [most
  distributions](http://flatpak.org/getting.html).

  Note 2
  : `appstream-compose` is used to parse the appdata file and generate the
    appstream (metadata like comments, etc.).
    On Fedora, this is provided by the package `libappstream-glib`, on Ubuntu by
    `appstream-util`…

* Install the runtimes and the corresponding SDKs if you haven't already:

  ```sh
  flatpak remote-add --user --from gnome https://nightly.gnome.org/gnome-nightly.flatpakrepo
  flatpak install --user gnome org.gnome.Platform/x86_64/master org.gnome.Sdk/x86_64/master
  flatpak install --user gnome org.gnome.Platform/aarch64/master org.gnome.Sdk/aarch64/master
  ```

  Or simply update them if you have already installed them:

  ```sh
  flatpak update
  ```

* Setup some recommended build options:

  ```sh
  export BUILD_OPTIONS="--ccache --keep-build-dirs --force-clean"
  ```

  We recommend using `ccache` to improve build speed, and to keep build dirs
  (these will be found in `.flatpak-builder/build/` relatively to the work
  directory; you may manually delete these once you are done to save space) for
  later debugging if ever any configuration or build issue arises.

* Choose what architecture to build and where you will "install" your flatpak:

  ```sh
  # Architectures supported with PIKA flatpak are one of 'x86_64' or 'aarch64':
  export ARCH="x86_64"
  # Path where build files are stored
  export INSTALLDIR="`pwd`/${ARCH}"
  ```

* Build the flatpak up to PIKA itself (not included):

  ```sh
  flatpak-builder $BUILD_OPTIONS --arch="$ARCH" --stop-at=pika \
                  "${INSTALLDIR}" technology.heckin.PIKA-nightly.json 2>&1 \
                  | tee pika-nightly-flatpak.log
  ```

  The build log will be outputted on `stdout` as well as being stored in a file
  `pika-nightly-flatpak.log`.

* Now we'll want to build PIKA itself, yet not from a clean repository clone
  (which is what the manifest provides) but from your local checkout, so that
  you can include any custom code:

  ```sh
  flatpak build "${INSTALLDIR}" meson setup --prefix=/app/ --libdir=/app/lib/ _pika ../../ 2>&1 | tee -a pika-nightly-flatpak.log
  flatpak build "${INSTALLDIR}" ninja -C _pika 2>&1 | tee -a pika-nightly-flatpak.log
  flatpak build "${INSTALLDIR}" ninja -C _pika install 2>&1 | tee -a pika-nightly-flatpak.log
  ```

  This assumes you are currently within `build/flatpak/`, therefore the
  repository source is 2 parent-folders away (`../../`). The build artifacts
  will be inside the `_pika/` subfolders, and finally it will be installed with
  the rest of the flatpak inside `$INSTALLDIR`.

* For development purpose, you don't need to export the flatpak to a repository
  or even install it. Just run it directly from your build directory:

  ```sh
  flatpak-builder --run "${INSTALLDIR}" technology.heckin.PIKA-nightly.json pika-2.99
  ```

## Maintaining the manifests

* PIKA uses Flatpak's [GNOME runtime](http://flatpak.org/runtimes.html), which
  contains a base of libraries, some of which are dependencies of PIKA.
  While both the stable and development versions should use the latest stable
  runtime version, the nightly manifest uses the `master` version, which is more
  of a *rolling release*.

* Other PIKA dependencies which are not available in the GNOME runtime
  should be built along as modules within PIKA's flatpak.
  Check format in `technology.heckin.PIKA-nightly.json` and add modules if
  necessary. For more options, check [flatpak builder's manifest
  format](http://flatpak.org/flatpak/flatpak-docs.html#flatpak-builder).

* On the other hand, if we increased the runtime version in particular (or when
  the `master` runtime evolves), some modules may no longer be necessary and can
  be removed from our manifest.

  A flatpak is a layered set of modules. Our PIKA build in particular is
  built over the GNOME runtime, itself built over the Freedesktop
  runtime, itself based on a yocto-built image.
  Other than by trial and error, you can find the installed dependencies
  by running:

```sh
flatpak run --devel --command=bash org.gnome.Sdk//master
```

Or if you already have a build:

```
flatpak run --devel --command=bash technology.heckin.PIKA//master
```

Inside the flatpak sandbox, PIKA's manifest can be read with:

```sh
 less /app/manifest.json
```

GNOME and Freedesktop's module lists (generated manifest as the SDK is built
from BuildStream):

```sh
less /usr/manifest.json
```

* Some sources have set a `x-checker-data` property which makes it possible to
  check for updates using
  [flatpak-external-data-checker](https://github.com/flathub/flatpak-external-data-checker).
  To run the tool either install it locally, via flatpak or via OCI image.

  The OCI image is not straightforward at first but is the least intrusive
  if you already have docker or podman installed:

```sh
cd <path-to-pika-repo>/flatpak/build
podman run --rm --privileged -v "$(pwd):/run/host:rw" ghcr.io/flathub/flatpak-external-data-checker:latest /run/host/technology.heckin.PIKA-nightly.json
```

  Our prefered backend for the checker is Anitya, a database maintained
  by the Fedora project. To set up a new dependency check by Anitya:

  1. verify it is available in the database: https://release-monitoring.org/
  2. then copy the project ID which is the number in the project URI
     within the database.
  3. Finally add a "x-checker-data" field within the "source" dictionary
     in the manifest with type "anitya", the "project-id" and a
     "url-template".
  4. We usually want to depend on stable releases only, i.e. set
     "stable-only to `true`. On exceptional cases, for very valid
     reasons only, we might bypass this limitation, adding a comment
     explaining why we use an unstable release.

* For the development releases and nightly builds, we added the
  `desktop-file-name-prefix` property. For a stable release, the property line
  can be removed from the manifest.

* For a stable release, set top `"branch":"stable"`, and inside the
  "pika", "babl" and "gegl" modules, set "tag" to the git tag (ex:
  `PIKA_2_10_34`) and "commit" to the git commit hash for this tag.

* For a development release, set top `"branch":"beta"`, and inside the
  "pika", "babl" and "gegl" modules, set "tag" to the git tag (ex:
  `PIKA_2_99_14`) and "commit" to the git commit hash for this tag.

* For a nightly build, set top "branch":"master", and inside the
  "pika", "babl" and "gegl" modules, set "branch" to "master", and
  remove any "commit" line.