1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
|
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.
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 persistent 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 sped 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 Strigi 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 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 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.
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
|