mirror of
https://bitbucket.org/smil3y/kde-playground.git
synced 2025-02-23 18:32:51 +00:00
127 lines
5.7 KiB
Text
127 lines
5.7 KiB
Text
|
Information for packagers of KDEPIM
|
||
|
|
=====================================
|
||
|
|
|
||
|
|
This document gives some hints to packagers on what is needed to provide
|
||
|
|
a sane installation and packaging for KDEPIM.
|
||
|
|
|
||
|
|
Akonadi is a key component of KDEPIM that is used by almost all applications.
|
||
|
|
It 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.
|
||
|
|
|
||
|
|
|
||
|
|
Baloo
|
||
|
|
------------------
|
||
|
|
Akonadi uses Baloo for all kind of searches.
|
||
|
|
|
||
|
|
MySQL
|
||
|
|
-----
|
||
|
|
Akonadi needs a relational 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 dependencies,
|
||
|
|
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 Baloo 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.
|
||
|
|
|
||
|
|
|
||
|
|
KDEPIM-Runtime
|
||
|
|
--------------
|
||
|
|
(most of) The kdepim applications can use one or several Akonadi Resources in order
|
||
|
|
to fetch and store PIM data.
|
||
|
|
|
||
|
|
It is usually a good idea to install the kdepim-runtime package when installing
|
||
|
|
one of the KDEPIM applications. As the module name indicates, it is only needed at
|
||
|
|
runtime.
|
||
|
|
|
||
|
|
The kdepim-runtime module contains applications and plugins, for example
|
||
|
|
Akonadi resources or KIO slaves, that are needed by all applications making use
|
||
|
|
of the PIM API in kdepimlibs.
|
||
|
|
|
||
|
|
Third-party applications which use the PIM API can be installed without installing
|
||
|
|
the rest of KDEPIM, only KDEPIM-Runtime (and of course kdepimlibs) is needed.
|
||
|
|
|
||
|
|
If you don't install KDEPIM-Runtime for third-party applications which use the PIM
|
||
|
|
API of kdepimlibs, these applications will fail to work at runtime.
|
||
|
|
|
||
|
|
Note that not all parts of kdepimlibs require KDEPIM-Runtime at runtime, only
|
||
|
|
the parts that access the Akonadi store in some way, like 'kcalcore', 'kabc' or
|
||
|
|
'akonadi'. Other parts, like 'kmime' or 'gpgme++' are not accessing the Akonadi
|
||
|
|
store and therefore don't need KDEPIM-Runtime.
|
||
|
|
|
||
|
|
|
||
|
|
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 separate 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'.
|
||
|
|
|
||
|
|
|
||
|
|
Libraries inside KDEPIM
|
||
|
|
-----------------------
|
||
|
|
There are several libraries in the KDEPIM module, such as 'libkdepim', 'libkleo'
|
||
|
|
or 'libksieve'. There is no guarantee for a stable API or ABI in those
|
||
|
|
libraries. API and ABI stability is only guaranteed for kdepimlibs. The
|
||
|
|
libraries of the KDEPIM module are 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 occurring 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
|
||
|
|
|