Building Evolution from sources
- Evolution-Data-Server dependency
- Download sources
- Set up environment
- Build the sources
- Run built Evolution
- Building code changes
- 3rd-party modules
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.
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:
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 git://git.gnome.org/evolution-data-server $ git clone git://git.gnome.org/evolution
Even there is no difference between tarball releases download and the git clone in the below chapters, let's try to build Evolution's gnome-3-24 branch 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. I chose gnome-3-24 intentionally, because it's using CMake as its build system. Previous versions use Autotools, where the only change in this article will be to call Autotools commands, instead of CMake commands. All the rest is the same. See Build evolution-rss below for an Autotools based project build.
Run below commands as a regular user to create the 'sources' directory, clone related sources into it, switch the clone to gnome-3-24 branch and make a _build directory, in which will be run the actual build:
$ mkdir $HOME/sources $ cd $HOME/sources $ git clone git://git.gnome.org/evolution-data-server $ git clone git://git.gnome.org/evolution $ cd evolution-data-server $ git checkout -b gnome-3-24 origin/gnome-3-24 $ mkdir _build $ cd ../evolution $ git checkout -b gnome-3-24 origin/gnome-3-24 $ mkdir _build
Set up environment
The sources are ready to by 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 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 (like gtk+ 3.10 is the minimum required version), but the latest versions deprecate many used symbols (for gtk+ the latest as of now is 3.22), 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 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.
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_GOOGLE_AUTH=ON \ -DENABLE_GTK=ON \ -DENABLE_UOA=OFF \ -DENABLE_EXAMPLES=ON \ -DENABLE_INTROSPECTION=ON \ -DENABLE_VALA_BINDINGS=ON \ -DENABLE_INSTALLED_TESTS=ON \ -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 25):
$ 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-devel \ libsecret-devel \ libxml2-devel \ nspr-devel \ nss-devel \ openldap-devel \ sqlite-devel \ webkitgtk4-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".
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 \ enchant-devel \ gsettings-desktop-schemas-devel \ gtkspell3-devel \ libcryptui-devel \ libnotify-devel \ libytnef-devel
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.
GNOME git hosts also some 3rd-party modules for Evolution-Data-Server and Evolution, namely evolution-rss (an RSS reader), 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.
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).
$ cd $HOME/sources/ $ git clone git://git.gnome.org/evolution-ews $ cd evolution-ews $ git checkout -b gnome-3-24 origin/gnome-3-24 $ mkdir _build $ cd _build $ cmake .. -G "Unix Makefiles" \ -DCMAKE_BUILD_TYPE=Debug \ -DCMAKE_INSTALL_PREFIX=$PREFIX \ -DLIB_SUFFIX= $ make && make install
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.
This module doesn't use CMake, but Autotools. Most of the dependencies are already installed, except some Autotools-related tools, like gnome-common and GConf2-devel. The GConf2 is not used these days, but the configure still searches for it.
Follows usual code checkout and build preparation. See that this time the branch was not changed. It's because evolution-rss doesn't follow GNOME release cycle, thus it's usually okay to build the master branch of it. Also note that this Autotools based project is built inside source tree, not in the _build subdirectory. It's partly intentional, but only in this article. Autotools also allows to build out of the source tree. The steps below use ./autogen.sh, which also calls ./configure, but if it's not available or any other software doesn't use it, then call instead of ./autogen.sh that ./configure, or call ./configure after ./autogen.sh, with the same arguments.
$ cd $HOME/sources/ $ git clone git://git.gnome.org/evolution-rss $ cd evolution-rss $ ./autogen.sh --prefix=$PREFIX $ make && make install
Even evolution-rss installs modules for Evolution-Data-Server and Evolution, it's not necessary to restart background processes (strictly speaking, it would be better, but the Evolution-Data-Server module only takes care of the cache-reaper, which is a module which deletes unused ~/.cache files).
Once built, run Evolution:
And add to it your RSS feeds in Edit->Preferences->News and Blogs section.
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:
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.
See below some common build issues and what to do to address them. The most important is to have proper build environment set.
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.