GIMP Flatpak HowTo
==================

Stable build
~~~~~~~~~~~~

The stable manifest is maintained at flathub: https://github.com/flathub/org.gimp.GIMP

To prepare a new build:

* A few hours before the release, update the manifest to point to last
  master commit (even if the release is not tagged yet).
* Commit in a branch and push (DO NOT PUSH TO MASTER):

> git checkout -b test-gimp-2-10-4-release
> git commit -a
> git push origin HEAD:test-gimp-2-10-4-release

* Create a pull-request from this branch.
* In the comment section, just write "bot, build".
  This will trigger test builds to test the manifest.
* Check the test build on https://flathub.org/builds/
* At release time, assuming the last test build succeeded, update the
  manifest to track the release tag instead.
* Merge the pull request to master.
* Check the final build on https://flathub.org/builds/

See also:
https://github.com/flathub/flathub/wiki/App-Maintenance#test-builds-and-pull-requests

Development and nightly builds
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Flathub does not host non-stable builds, therefore they are maintained
separately on the GIMP repository. Nevertheless they should remain as
close to the stable manifest as possible since they are meant to become
stable too eventually.

Building
--------

* Dependencies:
  - flatpak (at least 0.9.5)
  - flatpak-builder (at least 0.9.5)
  - appstream-compose
  - a GPG key to sign the builds

Note: there are packages of `flatpak` and `flatpak-builder` for most
      distributions. Check: 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:

> flatpak remote-add --from gnome https://sdk.gnome.org/gnome.flatpakrepo
> flatpak install gnome org.gnome.Platform/x86_64/3.28 org.gnome.Sdk/x86_64/3.28
> flatpak install gnome org.gnome.Platform/i386/3.28 org.gnome.Sdk/i386/3.28
> flatpak install gnome org.gnome.Platform/arm/3.28 org.gnome.Sdk/arm/3.28
> flatpak install gnome org.gnome.Platform/aarch64/3.28 org.gnome.Sdk/aarch64/3.28

Or simply update them if you have already installed them:

> flatpak update

* Run the build script:

> ./gimp-flatpak-cron.sh <GPGKEY> <REPO> <LOGDIR> <BUILDDIR>

Note that it is named with the "-cron" suffix because it is a good cron
script for nightlies.

The parameters:

GPGKEY: your GPG key used to sign the builds
REPO: the directory where the repository is locally.
      For instance, it could be /var/www/html/flatpak/ (which could map
      to https://download.gimp.org/flatpak/ for instance)
LOGDIR: where the logs of the build will be kept (under subdirectories
        by date).
BUILDDIR: where the built prefix will be kept for later review.

The export commands will output a commit hash. Save it for further
verification.

Maintaining the manifests
~~~~~~~~~~~~~~~~~~~~~~~~~

* GIMP uses Flatpak's GNOME runtime, which contains a base of libraries,
  some of which are dependencies of GIMP.
  Check out the available versions at: http://flatpak.org/runtimes.html
  Verify that we use the last runtime version in `org.gimp.GIMP.json`:

> "runtime-version": "3.28"

* Other GIMP dependencies which are not available in the GNOME runtime
  should be built along as modules within GIMP's flatpak.
  Check format in `org.gimp.GIMP-nightly.json` and add modules if
  necessary.  For more information and 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,
  some modules may no longer be necessary.
  For instance, at time of writing, GNOME runtime 3.22 includes libpng
  1.6.17 but GIMP requires "libpng >= 1.6.25".
  Similarly lcms2 was available in the runtime but on a low version.
  On a higher version runtime, these modules can likely be removed from
  our manifest.

  A flatpak is a layered set of modules. Our GIMP 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:

> flatpak run --devel --command=bash org.gnome.Sdk//3.28

Or if you already have a build:

> flatpak run --devel --command=bash org.gimp.GIMP

  GIMP manifest available at:

> less /app/manifest.json

  GNOME module list:

> less /usr/manifest.json

  Freedesktop module list:

> less /usr/manifest-base-1.json

  Finally the contents of the yocto-built image:

> less /usr/manifest.base

* Some sources have set a x-checker-data property which makes it possible
  to check for their 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:
  $ cd <path-to-gimp-repo>/flatpak/build
  $ podman run --rm --privileged -v "$(pwd):/run/host:rw" ghcr.io/flathub/flatpak-external-data-checker:latest /run/host/org.gimp.GIMP-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 a stable release, remove the following line from the manifest:

>  "desktop-file-name-prefix": "(Dev) ",

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

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

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

* Test it locally with:

> flatpak --user remote-add --no-gpg-verify gimp /path/to/repo

Or remotely:

> flatpak --user remote-add --no-gpg-verify gimp http://example.com/repo

> flatpak --user install gimp org.gimp.GIMP

  Once installed check that the commit hash outputted at export is the
  same as the one from the local command:

> flatpak list --user -d

  You can also run your flatpaked GIMP:

> flatpak run org.gimp.GIMP

  Also an entry "(Dev) GNU Image Manipulation Software" should now be
  available in your menus (or GNOME Overview). This will run the flatpak
  build.
