Information for packagers of KDEPIM
=====================================

This document gives some hints to packagers on what is needed to provide
a sane installation and packaging for KDE PIM.

KDE-PIM 4.4 is the first release that makes use of Akonadi. Akonadi depends
on several components to be properly installed and configured, which are
listed below.

Also, this document discusses other topics which are of importance for
packagers, such as the GPG support.


Nepomuk & Soprano
------------------
Akonadi uses Nepomuk and Soprano for all kind of searches. Nepomuk itself
requires two storage backends for full functionality. Thus, these are
hard requirements for KDEPIM:

  - Redland (for in-memory representation)
  - Virtuoso (for persistant storage on hard-disk)

For the Redland backend you need librdf from http://librdf.org which should
be available as package for all major distributions already.

The Virtuoso backend has a compile time and runtime dependency, both must be
fulfilled. The compile time dependency is libiodbc which is available from
http://www.iodbc.org and packages for all distributions should be available.
The runtime dependency is the Virtuoso server version 5.0.12 that can be
retrieved from http://virtuoso.openlinksw.com. Although the Virtuoso sources
are huge, the compilation can be speeded up by passing --disable-all-vads to
the configure script. After compilation has finished only the executable
  virtuoso-t
and the ODBC driver library
  virtodbc_r(.so)
are needed for the Soprano backend. We suggest splitting Virtuoso into
several sub-packages, two of which are the server binary and the ODBC drivers
to not force the user to install a full blown Virtuoso server.

Akonadi only requires Nepomuk, Strigi file indexing is not needed. You can
disable Stigi file indexing if you find that is uses too many resources. Only
the rest of Nepomuk needs to be running for Akonadi to work.
Akonadi uses some Strigi libraries to index e-mail content. These libraries are
needed at compile time.


Shared Desktop Ontologies
--------------------------
Nepomuk and Akonadi need some semantic ontologies to know how to interpret the content
of Sopranos RDF store. These ontologies are available at
  http://sourceforge.net/projects/oscaf/files
and version 0.2 should be used.


MySQL
-----
Akonadi needs a relation database to keep metadata about the PIM data it manages.
There exists different backends for MySQL, PostgreSQL and SQLite. While it might
be tempting to use the SQLite backend to reduce dependecies, we highly discourage
to use it, because it is not yet finished, can lose your data, has performance
problems and is not automatically tested yet!
The PostgreSQL backend has some more testing, however we discourage the use of it
as well, because it will make the migration path much harder once we'll switch
to Virtuoso as SQL backend in the future.
So please make MySQL a hard (runtime) dependency for Akonadi and compile the Qt
library with support for MySQL (can be done as plugin as well).


Akonadi
-------
Having a working installation of Nepomuk, Soprano, Virtuoso and MySQL should normally
result in a working installation of Akonadi.
Akonadi provides a self test dialog to make sure it really works. Please make sure all
tests in this self test dialog pass.
The test can be found in a control center module that is started with
'kcmshell4 kcm_akonadi'. The test is in the tab 'Akonadi Server Configuration' and is
started with the 'Test...' button.


Kontact Plugins
---------------
Kontact is a container application which embeds other PIM applications such as KMail
and KOrganizer.
For an application to be embedded in Kontact, it needs to provide a Kontact plugin.
These Kontact plugins reside under kontact/plugins, while the applications itself are
in the top-level folder.
This is important when splitting up the KDEPIM module in several packages. The Kontact
plugin should be packaged together with its application. It is an error to install a
Kontact plugin without installing the associated application, this will make Kontact
crash.
As an example, assume you want to provide a seperate package for KNode. This package
should contain KNode from the knode/ directory, and the Kontact plugin from the 
kontact/plugins/knode directory. kontact/plugins/knode should not be installed when
knode/ is not installed.


GPG Support
-----------
Crypto operations are supported in multiple places in KDEPIM: KMail provides support for
dealing with signed and encrypted mails, and Kleopatra is an application that manages
certificates and GPG keys.
For this to work, GPG needs to be installed and configured correctly.
An easy way to check if you have a working GPG installation is to run the self test in
Kleopatra, which checks many aspects of the GPG installation. After starting Kleopatra,
the self test can be found in the menu under 'Settings->Perform Self Test'. Please make
sure the self test passes.
Another way to test is sending an encrypted and signed message with KMail, and later
decrypting the received message. Note that saving as draft is not enough here, you need
to actually send the mail.

A common packaging error is that gpg-agent is not running or that it is wrongly
configured. This will result in KMail failing on crypto operations with error messages 
that give no indication of the real problem, such as 'bad passphrase'.


Runtime split
-------------

The KDEPIM sources have a top-level directory named 'runtime'. Please package this directory
seperatly. It contains applications and plugins that are needed by all applications making
use of the PIM API in kdepimlibs, such as Akonadi resources or KIO slaves.

By packaging 'runtime' seperatly, third-party applications which use the PIM API can be installed
without installing the rest of KDEPIM, only 'runtime' (and of course kdepimlibs) is needed.

If you don't install 'runtime' for third-party applications which use the PIM API of kdepimlibs,
these applications will fail to work at runtime.


Libraries inside KDEPIM
-----------------------

There are several libraries in the KDEPIM module, such as 'libkdepim', 'libkleo' or 'libksieve'.
There is no guarentee for a stable API or ABI in those libraries.
API and ABI stableness is only guaranteed for kdepimlibs.
The libraries of the KDEPIM module a generally work in progress and therefore change a lot,
API and ABI breakage can occur at any moment.

Therefore, please make sure to always ship the libraries with the exact same revision numbers as
the applications. This is always the case for the tags created for KDE SC versions.

As an example, shipping libkdepim from KDE SC 4.4.1 together with KMail from KDE SC 4.4.2 is an
error, and can result in failure at runtime, since this libkdepim is not binary compatible with
that KMail.


Further resources
-----------------

Some frequently occuring problems with Akonadi are collected under
http://userbase.kde.org/Akonadi#Some_Technical_Issues.

For further questions feel free to contact the KDE PIM developers on kde-pim@kde.org
or ask on freenode IRC channel #kontact or #akonadi
