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