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

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

The stable manifest is maintained at flathub: https://github.com/flathub/org.gimp.GIMP
This repository is pulled in GIMP repository as a submodule so that we
can share as much code as possible with the other builds.

To prepare a new build:

* A few hours before the release, test with the last master commit (even
  if the release is not tagged yet) in the manifest.
* Make it a branch, and create a pull-request instead of pushing to
  master.
* In the comment section, just write "bot, build".
  This will trigger test builds to test the manifest.
* At release time, if the last test build succeeded, update the manifest
  to track the release tag instead.
* Merge 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.

Building and maintaining
~~~~~~~~~~~~~~~~~~~~~~~~

* Init the submodule if this is the first time:

> git submodule init

* Update it:

> git submodule update

* Install flatpak and flatpak-builder. There are packages for most
  distributions. Check: http://flatpak.org/getting.html
  Use at least flatpak 0.9.5.

* Make sure `appstream-compose` is installed as well. This is used to parse the
  appdata file and generate the appstream (metadata like comments, etc.).
  For instance on Fedora, this is provided by the package `libappstream-glib`,
  on Ubuntu by `appstream-util`…

* 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.24"

* Install this runtime and the corresponding SDK 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.24 org.gnome.Sdk/x86_64/3.24
> flatpak install gnome org.gnome.Platform/i386/3.24 org.gnome.Sdk/i386/3.24

Or simply update them:

> flatpak update

* 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.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.24

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

* 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.

* Run flatpak builder with the following commands:

> flatpak-builder --ccache --arch=x86_64 gimp-flatpak-build-x86-64 org.gimp.GIMP.json
> flatpak-builder --ccache --arch=i386 gimp-flatpak-build-i386 org.gimp.GIMP.json

  Note: if you ever want to check the `config.log` of any of the module which
  failed to compile, it is available in a hidden directory of your working path.
  For instance GIMP build dir will be `.flatpak-builder/build/gimp-1/`.
  The number will be incrementing at each build.
  If you want to check build directories even if the builds are successful, add
  `--keep-build-dirs` option to your command.

  If it ends successfully, this will have built GIMP in new folders,
  `gimp-flatpak-build-x86-64/` and `gimp-flatpak-build-i386/`
  respectively.

* Export the 2 builds:

> flatpak-builder --export-only --gpg-sign=YOUR_GPG_KEY --repo=/path/to/repo --arch=x86_64 gimp-flatpak-build-x86-64 org.gimp.GIMP.json
> flatpak-builder --export-only --gpg-sign=YOUR_GPG_KEY --repo=/path/to/repo --arch=i386 gimp-flatpak-build-i386 org.gimp.GIMP.json

  If you key was protected with a passphrase, you will need to input it.
  The same repository will contain all the builds.
  Note: do not use `flatpak build-export` which is an internal low-level
  command. See https://github.com/flatpak/flatpak/issues/824

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

* 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.

* TODO: this is my current state. I still have to probably write a
  `.flatpakrepo` file which we can upload on `gimp.org` and should allow
  GNU/Linux users to install GIMP and our flatpak repo in a few clicks.
  We will also have to sign the repo with GPG, etc.

* TODO: Windows builds are defined in: build/windows/jhbuild/build.jhbuildrc
  It would be a good idea to compare contents and maybe deactivate some
  useless options from dependencies. Also if all builds end up having a
  very similar dependency list, maybe there could be a meta-format from
  which both the jhbuild and the flatpak manifest could be generated.
