Building Evolution from sources

This describes how to build Evolution from sources, which can be sometimes problematic due to dependencies, even Evolution itself doesn't depend on any recent versions. Due to that Evolution can use development packages of the most modern distributions. There is also BuildStream, which is meant to make things easier, thus if you want to use it, then follow its documentation page instead. This article will describe manual build of Evolution.

Evolution-Data-Server dependency

Evolution itself depends on Evolution-Data-Server, as much as the version of Evolution-Data-Server should be the same as version of Evolution itself. That means that when building Evolution, you'll most likely need to build Evolution-Data-Server as well. Due to Evolution-Data-Server being core part of the GNOME, and other applications are also connecting to it. For example GNOME Contacts, GNOME ToDo, GNOME Calendar and other are connection to Evolution-Data-Server. Building those applications instead of Evolution is possible too, the only thing to do is to basically replace Evolution with that particular application in the below steps.

There is (one known) caveat with GNOME Shell. Its gnome-shell-calendar-server process, which shows events and tasks in the clock popover, keeps restarting evolution-calendar-factory when it is closed (it's provided by Evolution-Data-Server), which makes it harder to develop those background processes, not talking that it's not intended to replace the system GNOME Shell by a custom build. There are some options, like moving away the gnome-shell-calendar-server process, thus the clock popover will not show any events, but the background processes will not be restarted in the background.

Download sources

The sources can be downloaded either in form of a tarball release or to make a git clone. It's better to use git clone in case any modifications are planned to be done in the code. The tarball releases can be found here:

https://download.gnome.org/sources/evolution-data-server/

https://download.gnome.org/sources/evolution/

Commands to make a git clone are below. They are using the GNOME git repository, because it's the official place for the sources. There is a github copy of those repositories, but they are not used, neither monitored, by the Evolution team members.

$ git clone https://gitlab.gnome.org/GNOME/evolution-data-server.git
$ git clone https://gitlab.gnome.org/GNOME/evolution.git

Even there is no difference between tarball releases download and the git clone in the below chapters, let's try to build Evolution from the git clone. First of all, pick a folder where the sources will be saved. It can be basically anywhere, thus use for example $HOME/sources. Evolution uses CMake as its build system. Versions before Evolution 3.24 used Autotools, where the only change in this article will be to call Autotools commands, instead of CMake commands. All the rest is the same.

Run below commands as a regular user to create the 'sources' directory, clone related sources into it, optionally switch the clone to a different branch than the unstable "git master" branch if wanted, and make a _build directory, in which will be run the actual build:

$ mkdir $HOME/sources
$ cd $HOME/sources
$ git clone https://gitlab.gnome.org/GNOME/evolution-data-server.git
$ git clone https://gitlab.gnome.org/GNOME/evolution.git
$ cd evolution-data-server
$ mkdir _build
$ cd ../evolution
$ mkdir _build

If you do not want to develop but only use Evolution, you want to switch to the stable branch first before running both the "mkdir _build" commands. Before both "mkdir _build" commands, enter this command:

$ git checkout -b gnome-3-XX origin/gnome-3-XX

and replace the XX by the actual last stable version number. See https://wiki.gnome.org/Apps/Evolution#Get_the_Source_Code

Set up environment

The sources are ready to be build right now. It's the time to decide where the build will be installed and set the environment accordingly. It's not that hard as it might look like, but it can be tricky. It's important to know that any environment changes, as done in this article, are local for the terminal in which they were executed.

First of all, choose the PREFIX, which is the folder where you want to install built sources. It can be anywhere. Let's choose a place which will not require a root login (to limit root requirement to minimum), thus build again under $HOME, say into $HOME/build. Note that due to the environment being local for the terminal it had been used in, there can be multiple versions compiled in parallel and they can be run independently, but not at the same time. The only tricky part is to have set up proper environment variables and having started correct background processes (those from Evolution-Data-Server).

The below set of commands set up the build environment and the PREFIX variable, which will be used later.

$ export PREFIX=$HOME/build
$ export PATH=$PREFIX/bin:$PATH
$ export XDG_DATA_DIRS=$PREFIX/share:$XDG_DATA_DIRS
$ export LD_LIBRARY_PATH=$PREFIX/lib
$ export PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig:$PREFIX/share/pkgconfig
$ export GSETTINGS_SCHEMA_DIR=$PREFIX/share/glib-2.0/schemas

More variables can be added, as needed. One of useful variables is to modify CFLAGS. Due to Evolution being able to build against some older versions of its dependencies (for example gtk+), but the latest versions deprecate many used symbols, then the warnings about deprecated symbols would easily hide important compiler warnings, thus the CFLAGS is used to not warn about deprecated symbols.

$ export CFLAGS="-Wno-deprecated-declarations"

As can be seen, there are plenty of the variables to be set properly before building and running the built sources. There is a 'source' binary, which can make things simpler by passing it a script, which does all of that, always in the same way. Such script would contain all these environment setting commands, thus it might look like this:

#!/bin/bash

export PREFIX=$HOME/build
export PATH=$PREFIX/bin:$PATH
export XDG_DATA_DIRS=$PREFIX/share:$XDG_DATA_DIRS
export LD_LIBRARY_PATH=$PREFIX/lib
export PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig:$PREFIX/share/pkgconfig
export GSETTINGS_SCHEMA_DIR=$PREFIX/share/glib-2.0/schemas
export CFLAGS="-Wno-deprecated-declarations"

Save it somewhere in the PATH ideally, then it can be used without path, but for now let's save it under $HOME/sources/build. Why to name it 'build'? Once you'd like to use multiple versions it's not that bad idea to name the setup environment script based on the PREFIX it's using. Make sure the script has executable bits set, like with this command:

$ chmod o+x $HOME/sources/build

Finally make the environment for this terminal use the variables from the 'build' script:

$ source $HOME/sources/build

Build the sources

The build order is given by the dependencies. As stated above, most modern distributions provide development packages for the dependencies in new-enough versions, which makes things easier. When any dependency is not satisfied, the CMake build script claims an error. Depending whether the dependency is required or optional, the error message contain either only what is missing or also a way how to disable certain part.

Build Evolution-Data-Server

Let's start with Evolution-Data-Server and show with it what can happen.

$ cd $HOME/sources/evolution-data-server/_build
$ cmake .. -G "Unix Makefiles" \
        -DCMAKE_BUILD_TYPE=Debug \
        -DCMAKE_INSTALL_PREFIX=$PREFIX \
        -DLIB_SUFFIX= \
        -DENABLE_FILE_LOCKING=fcntl \
        -DENABLE_DOT_LOCKING=OFF \
        -DENABLE_CANBERRA=OFF \
        -DENABLE_OAUTH2=ON \
        -DENABLE_GTK=ON \
        -DENABLE_UOA=OFF \
        -DENABLE_EXAMPLES=ON \
        -DENABLE_INTROSPECTION=ON \
        -DENABLE_VALA_BINDINGS=ON \
        -DENABLE_INSTALLED_TESTS=OFF \
        -DENABLE_GTK_DOC=OFF \
        -DWITH_PRIVATE_DOCS=OFF \
        -DWITH_PHONENUMBER=OFF \
        -DWITH_LIBDB=OFF

The command instructs CMake to configure with Unix Makefiles, but feel free to change it to anything else. There is also forced to use empty LIB_SUFFIX, just to make sure that $HOME/build/lib/ will not be $HOME/build/lib64/ or anything else. The other options are more or less optional, having some expected defaults. Note of the -DENABLE_GTK_DOC=OFF, it's used to speed up the build, because it's not always needed to run gtk-doc when fixing something in the code. The command above also enables GTK and Google authentication to be built. It's good to have these on, because Evolution itself depends on the GTK part (libedataserverui) and the Google authentication is needed for built-in OAuth2 support.

Here starts the boring part to satisfy all the dependencies. See the Troubleshooting section for some examples of possible issues.

As the above cmake arguments are set, the development packages to be installed are (for Fedora 30):

$ sudo dnf install cmake gcc-c++ gperf intltool redhat-rpm-config vala \
        gcr-devel \
        glib2-devel \
        gnome-online-accounts-devel \
        gobject-introspection-devel \
        gtk3-devel \
        json-glib-devel \
        krb5-devel \
        libgdata-devel \
        libgweather-devel \
        libical-glib-devel \
        libsecret-devel \
        libxml2-devel \
        nspr-devel \
        nss-devel \
        openldap-devel \
        sqlite-devel \
        webkit2gtk3-devel

Upon successful configuration a list of "Configure options" is printed, showing what values had been used for which configurable option. Any of these can be changed by adding them to the cmake command.

Assume the configure finished successfully, then build and install the Evolution-Data-Server:

$ make && make install

Note of the "-j" option of the "make" command. It's used for parallel builds. The number of parallel jobs can be limited, without the number is uses as many as possible. To limit for example to 2 jobs, use "make -j2".

Build Evolution

After having Evolution-Data-Server ready, do basically the same with Evolution sources. Configure it first, and install missing dependencies as needed. Luckily, Evolution shares most of the dependencies with Evolution-Data-Server, thus most of them are already installed.

Some to have installed for the below configuration options:

$ sudo dnf install \
        enchant2-devel \
        gsettings-desktop-schemas-devel \
        gspell-devel \
        libnotify-devel \
        libytnef-devel \
        cmark-devel \
        highlight

Configure the build:

$ cd $HOME/sources/evolution/_build
$ cmake .. -G "Unix Makefiles" \
        -DCMAKE_BUILD_TYPE=Debug \
        -DCMAKE_INSTALL_PREFIX=$PREFIX \
        -DLIB_SUFFIX= \
        -DENABLE_AUTOAR=OFF \
        -DENABLE_CANBERRA=OFF \
        -DENABLE_CONTACT_MAPS=OFF \
        -DENABLE_GNOME_DESKTOP=OFF \
        -DENABLE_INSTALLED_TESTS=OFF \
        -DENABLE_PST_IMPORT=OFF \
        -DENABLE_GTK_DOC=OFF \
        -DWITH_GLADE_CATALOG=OFF \
        -DWITH_HELP=OFF

And finally build it:

$ make && make install

Upon successful compilation both Evolution-Data-Server and Evolution are built and installed in the PREFIX.

Run built Evolution

To run Evolution from the build PREFIX, also Evolution-Data-Server processes should be run, for the same version as the Evolution is. If the Evolution is of the same version as the system Evolution-Data-Server, then even the build of Evolution-Data-Server can be skipped and only the development package of Evolution-Data-Server can be used. Here's what to do when the Evolution-Data-Server version is not the same as the built Evolution, in other words, when Evolution-Data-Server had been built as well.

The order is important (also note of the issue with GNOME Shell from the top of this article) and it might take a bit to the D-Bus to register all the interfaces, eventually to load the binaries at all. Open a terminal and run there these commands as a regular user:

$ source $HOME/sources/build
$ $PREFIX/libexec/evolution-source-registry &
$ sleep 1
$ $PREFIX/libexec/evolution-calendar-factory -r &
$ sleep 1
$ $PREFIX/libexec/evolution-addressbook-factory -r &
$ sleep 1
$ $PREFIX/bin/evolution

And that's it.

The -r argument of the factories is meant to keep factory running until killed. Another option is -w, which waits for the first client and closes approximately 10 seconds after the last client disappears. Running the factory without one of these arguments causes it to close automatically if nothing connects to it within approximately 10 seconds.

Building code changes

After a code change is done the project should be built and installed. Depending on the change itself, either build the project only or reconfigure and build it. The other projects might need to be rebuilt too, especially in case of API or ABI change in some public header, like for example in Evolution-Data-Server, then everything what had been built against it should be rebuilt as well. Assume that there had been done such change, then the steps to rebuild it are:

$ cd $HOME/sources/evolution-data-server/_build
$ make && make install
$ cd $HOME/sources/evolution/_build
$ make && make install

Then run the changed code as described in Run built Evolution.

3rd-party modules

GNOME git hosts also some 3rd-party modules for Evolution-Data-Server and Evolution, namely evolution-ews (an Exchange connector, which uses Exchange Web Services protocol), evolution-mapi (an Exchange connector, which uses MAPI protocol with OpenChange) and evolution-activesync (an ActiveSync connector). Note that some modules are maintained more actively, some less. For example evolution-mapi is in a maintenance mode only, it's kept alive only for users whom need to connect to Exchange servers before version 2007. All other users are encouraged to use evolution-ews instead, which is better in some aspects and has less dependencies.

Some modules can install additional files for either Evolution only or also for Evolution-Data-Server, in which case the background processes should be restarted too, to have the changes in effect.

Build evolution-ews

The steps are similar as before, clone the repository, switch to the right branch, create the _build directory, configure the build, make and make install. It's better to build it with libmspack, thus install its development package first (libmspack-devel on Fedora, libmspack-dev on Ubuntu).

$ cd $HOME/sources/
$ git clone https://gitlab.gnome.org/GNOME/evolution-ews.git
$ cd evolution-ews
$ mkdir _build
$ cd _build
$ cmake .. -G "Unix Makefiles" \
        -DCMAKE_BUILD_TYPE=Debug \
        -DCMAKE_INSTALL_PREFIX=$PREFIX \
        -DLIB_SUFFIX= \
        -DWITH_MSPACK=ON
$ make && make install

If you do not want to develop but only use evolution-ews, you want to switch to the stable branch first before running the "mkdir _build" command. Before the "mkdir _build" command, enter this command:

$ git checkout -b gnome-3-XX origin/gnome-3-XX

and replace the XX by the actual last stable version number. See https://wiki.gnome.org/Apps/Evolution#Get_the_Source_Code

After successful build, run Evolution with background processes as above Run built Evolution and in File->New->Mail Account will be shown also "Exchange Web Services" account type.

Build example module

The Example Module contains an example code to build a module for Evolution. More description can be seen there. Download it and unpack it to $HOME/sources/example-module and build it as for example evolution-ews (it's also a CMake project). Supposing the example-module.zip had been downloaded to ~/Downloads/example-module.zip file, the commands might be:

$ cd $HOME/sources/
$ unzip ~/Downloads/example-module.zip
$ cd example-module
$ mkdir _build
$ cd _build
$ cmake .. -G "Unix Makefiles" \
        -DCMAKE_BUILD_TYPE=Debug \
        -DCMAKE_INSTALL_PREFIX=$PREFIX
$ make && make install

After successful build, run Evolution:

$ $PREFIX/bin/evolution

and see the newly added menu items from the example module, like in the Mail view in Message->My Message Action... and "My Maildir Folder Action..." in the context menu above a folder in the left folder tree.

Troubleshooting

See below some common build issues and what to do to address them. The most important is to have proper build environment set.

Build environment

Always make sure, whenever you open a new terminal, that it has set correct environment variables. That can be done with:

$ source $HOME/sources/build

Also make sure that correct evolution background processes are running. One way to see what processes are there is to use:

$ ps ax | grep evolution

which shows also paths to those processes, which should point to $PREFIX. See Run built Evolution for more details. That set of commands can be made a script as well, for convenience.

There can be used:

$ evolution --force-shutdown

to stop all Evolution and Evolution-Data-Server background processes. Be aware of the issue with gnome-shell-calendar-server as mentioned at the top of this article.

Stale CMake files

It can sometimes happen than a reinvoke of the cmake command doesn't notice newly installed dependencies or any changes in the code. Then the easiest is to remove the whole CMake cache in the _build directory and let the CMake configure from scratch. That is:

$ cd $HOME/sources/PROJECT/_build
$ rm -r *
$ cmake .. -G .....
$ make && make install

Missing dependencies - one module

Unfortunately, CMake's PkgConfig module error reporting is not that powerful as in Autotools (at least for CMake 3.6.2). Below is an error shown when is checked for one module and it is missing:

-- Checking for module 'gobject-introspection-1.0'
--   No package 'gobject-introspection-1.0' found
CMake Error at cmake/modules/PkgConfigEx.cmake:32 (message):
  Necessary libraries not found or not enough version.  If you want to
  disable GObject introspection, please use -DENABLE_INTROSPECTION=OFF
  argument to cmake command.

There are two options now. Either find which package provides the missing gobject-introspection-1.0.pc file (it's gobject-introspection-devel on Fedora), or pass -DENABLE_INTROSPECTION=OFF to cmake command, as the error string suggest. When it's possible then such hint is shown. This way an optional part of the code is disabled and not built.

Missing dependencies - multiple modules

The below error message shows an issue when search for a set of libraries failed. One or more modules can be missing. This is where the Autotools gave better results, because from the "Checking for modules" line it's pretty hard to know which module(s) is (are) the problem with.

-- Checking for modules 'gio-2.0;libical>=0.43;libsoup-2.4;libxml-2.0;libsecret-1'
--   
CMake Error at /usr/share/cmake/Modules/FindPkgConfig.cmake:424 (message):
  A required package was not found

One way to deal with this is to get the list of the modules, remove from it the version checks and then replace semicolons with spaces and then check one by one. For this concrete example, it can be done with this command:

$ for pkg in gio-2.0 libical libsoup-2.4 libxml-2.0 libsecret-1 ; do \
     echo -n "$pkg is version "; pkg-config --modversion $pkg; done

whose result is:

gio-2.0 is version 2.50.3
libical is version Package libical was not found in the pkg-config search path.
Perhaps you should add the directory containing `libical.pc'
to the PKG_CONFIG_PATH environment variable
No package 'libical' found
libsoup-2.4 is version 2.56.0
libxml-2.0 is version 2.9.3
libsecret-1 is version 0.18.5

It shows that only libical is missing and should be installed. For modules which had version check the module can be installed, but with not enough version. Then make sure the returned versions satisfy the check.

Dependencies on Ubuntu 18.04

The development packages in Ubuntu are named ...-dev and it can be searched for them with apt with command like this:

$ apt list *-dev

The only tricky part is to pick the right one to install. When searching for example for WebKitGTK, use:

$ apt list *webkit*-dev

which returns something like this:

libkf5webkit-dev/bionic 5.44.0-0ubuntu1 amd64
libqt5webkit5-dev/bionic 5.212.0~alpha2-7ubuntu1 amd64
libqtwebkit-dev/bionic 2.3.2-0ubuntu13 amd64
libwebkit2-sharp-4.0-cil-dev/bionic 2.10.9+git20160917-1.1 amd64
libwebkit2gtk-4.0-dev/bionic-updates,bionic-security 2.28.1-0ubuntu0.18.04.1 amd64
libwebkitgtk-3.0-dev/bionic 2.4.11-3ubuntu3 amd64
libwebkitgtk-dev/bionic 2.4.11-3ubuntu3 amd64

The evolution-data-server and evolution depends on webkit2gtk3, which is named libwebkit2gtk-4.0 in Ubuntu, thus to install its development files use:

$ sudo apt install libwebkit2gtk-4.0-dev

There are also required some build tools to be installed, which can be done with:

$ sudo apt install cmake git gperf intltool  valac

Prepare Evolution-Data-Server dependencies

Install them with:

$ sudo apt install libgcr-3-dev \
        libglib2.0-dev \
        libgoa-1.0-dev \
        libgirepository1.0-dev \
        libgtk-3-dev \
        libjson-glib-dev \
        libkrb5-dev \
        libgdata-dev \
        libgweather-3-dev \
        libsecret-1-dev \
        libxml2-dev \
        libnspr4-dev \
        libnss3-dev \
        libldap2-dev \
        libsqlite3-dev \
        libwebkit2gtk-4.0-dev

Ubuntu 18.04 doesn't provide new-enough libical, thus it needs to built manually, before building evolution-data-server. It's similar to any other module. Simple steps (after installing evolution-data-server dependencies):

$ cd $HOME/sources/
$ git clone --branch 3.0 https://github.com/libical/libical.git libical
$ cd libical
$ mkdir _build
$ cd _build
$ cmake .. -G "Unix Makefiles" \
        -DCMAKE_BUILD_TYPE=Debug \
        -DCMAKE_INSTALL_PREFIX=$PREFIX \
        -DCMAKE_INSTALL_LIBDIR:PATH=${PREFIX}/lib \
        -DGOBJECT_INTROSPECTION=ON \
        -DENABLE_GTK_DOC=OFF \
        -DUSE_BUILTIN_TZDATA=OFF \
        -DICAL_GLIB_VAPI=ON
$ make && make install

Prepare Evolution dependencies

Install them with:

$ sudo apt install libenchant-dev \
        gsettings-desktop-schemas-dev \
        libgspell-1-dev \
        libnotify-dev \
        libytnef0-dev \
        libgail-3-dev \
        libcmark-dev \
        highlight

Newer Ubuntu might use libenchant-2-dev.