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

* 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) ",

* Run flatpak builder with the following commands:

> flatpak-builder --arch=x86_64 gimp-flatpak-build-x86-64 org.gimp.GIMP.json
> flatpak-builder --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 successfuly, 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

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