README.packagers

   1 Information for packagers of KDEPIM
   2 =====================================
   3
   4 This document gives some hints to packagers on what is needed to provide
   5 a sane installation and packaging for KDEPIM.
   6
   7 Akonadi is a key component of KDEPIM that is used by almost all applications.
   8 It depends on several components to be properly installed and configured,
   9 which are listed below.
  10
  11 Also, this document discusses other topics which are of importance for
  12 packagers, such as the GPG support.
  13
  14
  15 Nepomuk & Soprano
  16 ------------------
  17 Akonadi uses Nepomuk and Soprano for all kind of searches. Nepomuk itself
  18 requires two storage backends for full functionality. Thus, these are
  19 hard requirements for KDEPIM:
  20
  21 - Redland (for in-memory representation)
  22 - Virtuoso (for persistent storage on hard-disk)
  23
  24 For the Redland backend you need librdf from http://librdf.org which should
  25 be available as package for all major distributions already.
  26
  27 The Virtuoso backend has a compile time and runtime dependency, both must be
  28 fulfilled. The compile time dependency is libiodbc which is available from
  29 http://www.iodbc.org and packages for all distributions should be available.
  30 The runtime dependency is the Virtuoso server version 5.0.12 that can be
  31 retrieved from http://virtuoso.openlinksw.com. Although the Virtuoso sources
  32 are huge, the compilation can be sped up by passing --disable-all-vads to
  33 the configure script. After compilation has finished only the executable
  34 virtuoso-t and the ODBC driver library virtodbc_r(.so) are needed for the
  35 Soprano backend. We suggest splitting Virtuoso into several sub-packages,
  36 two of which are the server binary and the ODBC drivers to not force the
  37 user to install a full blown Virtuoso server.
  38
  39 Akonadi only requires Nepomuk, Strigi file indexing is not needed. You can
  40 disable Strigi file indexing if you find that is uses too many resources. Only
  41 the rest of Nepomuk needs to be running for Akonadi to work.  Akonadi uses
  42 some Strigi libraries to index e-mail content. These libraries are needed at
  43 compile time.
  44
  45
  46 Shared Desktop Ontologies
  47 --------------------------
  48 Nepomuk and Akonadi need some semantic ontologies to know how to interpret the
  49 content of Sopranos RDF store. These ontologies are available at
  50 http://sourceforge.net/projects/oscaf/files and version 0.2 should be used.
  51
  52
  53 MySQL
  54 -----
  55 Akonadi needs a relational database to keep metadata about the PIM data it
  56 manages.  There exists different backends for MySQL, PostgreSQL and SQLite.
  57 While it might be tempting to use the SQLite backend to reduce dependencies,
  58 we highly discourage to use it, because it is not yet finished, can lose
  59 your data, has performance problems and is not automatically tested yet!
  60
  61 The PostgreSQL backend has some more testing, however we discourage the
  62 use of it as well, because it will make the migration path much harder once
  63 we'll switch to Virtuoso as SQL backend in the future.  So please make MySQL a
  64 hard (runtime) dependency for Akonadi and compile the Qt library with support
  65 for MySQL (can be done as plugin as well).
  66
  67
  68 Akonadi
  69 -------
  70 Having a working installation of Nepomuk, Soprano, Virtuoso and MySQL should
  71 normally result in a working installation of Akonadi.  Akonadi provides a self
  72 test dialog to make sure it really works. Please make sure all tests in this
  73 self test dialog pass.  The test can be found in a control center module that is
  74 started with 'kcmshell4 kcm_akonadi'. The test is in the tab 'Akonadi Server
  75 Configuration' and is started with the 'Test...' button.
  76
  77
  78 Kontact Plugins
  79 ---------------
  80 Kontact is a container application which embeds other PIM applications such as
  81 KMail and KOrganizer.  For an application to be embedded in Kontact, it needs to
  82 provide a Kontact plugin.  These Kontact plugins reside under kontact/plugins,
  83 while the applications itself are in the top-level folder.  This is important
  84 when splitting up the KDEPIM module in several packages. The Kontact plugin
  85 should be packaged together with its application. It is an error to install a
  86 Kontact plugin without installing the associated application, this will make
  87 Kontact crash.  As an example, assume you want to provide a separate package for
  88 KNode. This package should contain KNode from the knode/ directory, and the
  89 Kontact plugin from the kontact/plugins/knode directory. kontact/plugins/knode
  90 should not be installed when knode/ is not installed.
  91
  92
  93 GPG Support
  94 -----------
  95 Crypto operations are supported in multiple places in KDEPIM: KMail provides
  96 support for dealing with signed and encrypted mails, and Kleopatra is an
  97 application that manages certificates and GPG keys.  For this to work, GPG needs
  98 to be installed and configured correctly.  An easy way to check if you have a
  99 working GPG installation is to run the self test in Kleopatra, which checks many
 100 aspects of the GPG installation. After starting Kleopatra, the self test can be
 101 found in the menu under 'Settings->Perform Self Test'. Please make sure the self
 102 test passes.  Another way to test is sending an encrypted and signed message
 103 with KMail, and later decrypting the received message. Note that saving as draft
 104 is not enough here, you need to actually send the mail.
 105
 106 A common packaging error is that gpg-agent is not running or that it is wrongly
 107 configured. This will result in KMail failing on crypto operations with error
 108 messages that give no indication of the real problem, such as 'bad passphrase'.
 109
 110
 111 Runtime split
 112 -------------
 113 The KDEPIM sources have a top-level directory named 'runtime'. Please package
 114 this directory separately. It contains applications and plugins, for example
 115 Akonadi resources or KIO slaves, that are needed by all applications making use
 116 of the PIM API in kdepimlibs.
 117
 118 By packaging 'runtime' separately, third-party applications which use the PIM
 119 API can be installed without installing the rest of KDEPIM, only 'runtime' (and
 120 of course kdepimlibs) is needed.
 121
 122 If you don't install 'runtime' for third-party applications which use the PIM
 123 API of kdepimlibs, these applications will fail to work at runtime.
 124
 125 Note that not all parts of kdepimlibs require kdepim/runtime at runtime, only
 126 the parts that access the Akonadi store in some way, like 'kcal', 'kabc' or
 127 'akonadi'. Other parts, like 'kmime' or 'gpgme++' are not accessing the Akonadi
 128 store and therefore don't need kdepim/runtime.
 129
 130 The tarballs released by the KDE project are already split, there is a 'kdepim'
 131 tarball as well as a 'kdepim-runtime' tarball.
 132
 133
 134 Libraries inside KDEPIM
 135 -----------------------
 136 There are several libraries in the KDEPIM module, such as 'libkdepim', 'libkleo'
 137 or 'libksieve'.  There is no guarantee for a stable API or ABI in those
 138 libraries.  API and ABI stability is only guaranteed for kdepimlibs.  The
 139 libraries of the KDEPIM module are generally work in progress and therefore
 140 change a lot, API and ABI breakage can occur at any moment.
 141
 142 Therefore, please make sure to always ship the libraries with the exact same
 143 revision numbers as the applications. This is always the case for the tags
 144 created for KDE SC versions.
 145
 146 As an example, shipping libkdepim from KDE SC 4.4.1 together with KMail from KDE
 147 SC 4.4.2 is an error, and can result in failure at runtime, since this libkdepim
 148 is not binary compatible with that KMail.
 149
 150
 151 Further resources
 152 ----------------
 153 Some frequently occurring problems with Akonadi are collected under
 154 http://userbase.kde.org/Akonadi#Some_Technical_Issues.
 155
 156 For further questions feel free to contact the KDE PIM developers on
 157 kde-pim@kde.org or ask on freenode IRC channel #kontact or #akonadi
 158