evolution/flatpak

This directory contains files related to Flatpak build of Evolution. Apart
of Evolution itself, it builds also evolution-data-server, and uses it,
the same as evolution-ews for Exchange Web Services accounts.

=== Online version of the manual ===

An online version of this manual can be found here:
https://wiki.gnome.org/Apps/Evolution/Flatpak

=== Prerequisites ===

The build uses GNOME Flatpak SDK and runtime.

To build it, one can follow the below commands, which expect flatpak and
flatpak-builder installed. Refer to the Flatpak developer documentation
and command man pages for the meaning of respective arguments.

Note the actual versions of the GNOME SDK and Platform (below is used
version 3.34) can differ each release of Evolution. The exact expected
version can be seen (or changed) in the .json file, the runtime-version
key (line "runtime-version": "3.34",). Use the same version in the below
install commands as is written in the runtime-version key of the .json file.

Evolution uses GNOME SDK and Platform, which is current hosted on the flathub.
If there's preinstalled a flathub repository in the system, then skip
the flatpak remote-add command below. The GNOME SDK and Platform can be
installed with:

   flatpak remote-add --from flathub https://flathub.org/repo/flathub.flatpakrepo
   flatpak install flathub org.gnome.Platform//3.34
   flatpak install flathub org.gnome.Sdk//3.34

If it's required to install the GNOME SDK and Platform only for the current
user, rather than system wide (also to not require root password), then
install it with --user argument, like this:

   flatpak --user remote-add --from flathub https://flathub.org/repo/flathub.flatpakrepo
   flatpak --user install flathub org.gnome.Platform//3.34
   flatpak --user install flathub org.gnome.Sdk//3.34

And that's all with respect of prerequisites. All the rest is handled
by Flatpak and Evolution build script.

=== Prepare the build directory ===

Choose a directory where the Flatpak will build Evolution. Let's use
a directory in the user home, like ~/flatpak, which can be prepared by:

   mkdir ~/flatpak
   cd ~/flatpak

Get the build script now, using wget command:

   wget https://gitlab.gnome.org/GNOME/evolution/raw/master/flatpak/org.gnome.Evolution-stable.json

There's everything ready to start the build now.

=== Build Evolution ===

To build Evolution in Flatpak, run the below command:

   flatpak-builder --force-clean org.gnome.Evolution-stable org.gnome.Evolution-stable.json

and flatpak-builder will do everything what is needed to build Evolution,
including downloading other dependencies and building them.

=== Flatpak repository ===

Flatpak requires the local build to be part of a repository, thus create
one for it and add it to Flatpak:

   flatpak build-export repo-stable org.gnome.Evolution-stable
   flatpak --user remote-add --no-gpg-verify --if-not-exists evolution-repo-stable repo-stable

Evolution can be installed from this repository now:

   flatpak --user install evolution-repo-stable org.gnome.Evolution

=== Run Evolution ===

To run the built Evolution, use this command:

   flatpak run org.gnome.Evolution

And that's it.

=== Receiving updates ===

Evolution is built from git checkout, which allows to rebuild it from
the latest sources. To do so, move to the build folder and rebuild it:

   cd ~/flatpak
   flatpak-builder --force-clean org.gnome.Evolution-stable org.gnome.Evolution-stable.json

Once the build is done, its repository needs to be refreshed with the built
bits:

   flatpak build-export repo-stable org.gnome.Evolution-stable

Finally, update Evolution from the refreshed repository with:

   flatpak --user update org.gnome.Evolution

Then run Evolution as before:

   flatpak run org.gnome.Evolution

The Flatpak build of Evolution shows the git commit ID in Help->About at which
the Evolution was when it had been built. It can be used to verify that
the build contains the latest changes.

=== Clean up Flatpak data ===

As a quick reference, in case of removing the Flatpak version of Evolution
from the system, check what is installed first:

   flatpak list

and remove Evolution from there:

   flatpak --user uninstall org.gnome.Evolution

Then also check what repositories are installed:

   flatpak remotes

and remove the custom Evolution repository with:

   flatpak --user remote-delete evolution-repo-stable

Sometimes the build can fail or be stopped by the user, then
the flatpak-builder can left whole checkout without erasing it.
In such cases, the files are stored in ~/flatpak/.flatpak-builder/build.
The folder should be empty when nothing is building, thus remove anything
left there after the build ends.