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 Baloo
  16 ------------------
  17 Akonadi uses Baloo for all kind of searches.
  18
  19 MySQL
  20 -----
  21 Akonadi needs a relational database to keep metadata about the PIM data it
  22 manages.  There exists different backends for MySQL, PostgreSQL and SQLite.
  23 While it might be tempting to use the SQLite backend to reduce dependencies,
  24 we highly discourage to use it, because it is not yet finished, can lose
  25 your data, has performance problems and is not automatically tested yet!
  26
  27 The PostgreSQL backend has some more testing, however we discourage the
  28 use of it as well, because it will make the migration path much harder once
  29 we'll switch to Virtuoso as SQL backend in the future.  So please make MySQL a
  30 hard (runtime) dependency for Akonadi and compile the Qt library with support
  31 for MySQL (can be done as plugin as well).
  32
  33
  34 Akonadi
  35 -------
  36 Having a working installation of Baloo and MySQL should
  37 normally result in a working installation of Akonadi.  Akonadi provides a self
  38 test dialog to make sure it really works. Please make sure all tests in this
  39 self test dialog pass.
  40
  41
  42 KDEPIM-Runtime
  43 --------------
  44 (most of) The kdepim applications can use one or several Akonadi Resources in order
  45 to fetch and store PIM data.
  46
  47 It is usually a good idea to install the kdepim-runtime package when installing
  48 one of the KDEPIM applications. As the module name indicates, it is only needed at
  49 runtime.
  50
  51 The kdepim-runtime module contains applications and plugins, for example
  52 Akonadi resources or KIO slaves, that are needed by all applications making use
  53 of the PIM API in kdepimlibs.
  54
  55 Third-party applications which use the PIM API can be installed without installing
  56 the rest of KDEPIM, only KDEPIM-Runtime (and of course kdepimlibs) is needed.
  57
  58 If you don't install KDEPIM-Runtime for third-party applications which use the PIM
  59 API of kdepimlibs, these applications will fail to work at runtime.
  60
  61 Note that not all parts of kdepimlibs require KDEPIM-Runtime at runtime, only
  62 the parts that access the Akonadi store in some way, like 'kcalcore', 'kabc' or
  63 'akonadi'. Other parts, like 'kmime' or 'gpgme++' are not accessing the Akonadi
  64 store and therefore don't need KDEPIM-Runtime.
  65
  66
  67 Kontact Plugins
  68 ---------------
  69 Kontact is a container application which embeds other PIM applications such as
  70 KMail and KOrganizer.  For an application to be embedded in Kontact, it needs to
  71 provide a Kontact plugin.  These Kontact plugins reside under kontact/plugins,
  72 while the applications itself are in the top-level folder.  This is important
  73 when splitting up the KDEPIM module in several packages. The Kontact plugin
  74 should be packaged together with its application. It is an error to install a
  75 Kontact plugin without installing the associated application, this will make
  76 Kontact crash.  As an example, assume you want to provide a separate package for
  77 KNode. This package should contain KMail from the kmail/ directory.
  78
  79
  80 GPG Support
  81 -----------
  82 Crypto operations are supported in multiple places in KDEPIM: KMail provides
  83 support for dealing with signed and encrypted mails, and Kleopatra is an
  84 application that manages certificates and GPG keys.  For this to work, GPG needs
  85 to be installed and configured correctly.  An easy way to check if you have a
  86 working GPG installation is to run the self test in Kleopatra, which checks many
  87 aspects of the GPG installation. After starting Kleopatra, the self test can be
  88 found in the menu under 'Settings->Perform Self Test'. Please make sure the self
  89 test passes.  Another way to test is sending an encrypted and signed message
  90 with KMail, and later decrypting the received message. Note that saving as draft
  91 is not enough here, you need to actually send the mail.
  92
  93 A common packaging error is that gpg-agent is not running or that it is wrongly
  94 configured. This will result in KMail failing on crypto operations with error
  95 messages that give no indication of the real problem, such as 'bad passphrase'.
  96
  97
  98 Libraries inside KDEPIM
  99 -----------------------
 100 There are several libraries in the KDEPIM module, such as 'libkdepim', 'libkleo'
 101 or 'libksieve'.  There is no guarantee for a stable API or ABI in those
 102 libraries.  API and ABI stability is only guaranteed for kdepimlibs.  The
 103 libraries of the KDEPIM module are generally work in progress and therefore
 104 change a lot, API and ABI breakage can occur at any moment.
 105
 106 Therefore, please make sure to always ship the libraries with the exact same
 107 revision numbers as the applications. This is always the case for the tags
 108 created for KDE SC versions.
 109
 110 As an example, shipping libkdepim from KDE SC 4.4.1 together with KMail from KDE
 111 SC 4.4.2 is an error, and can result in failure at runtime, since this libkdepim
 112 is not binary compatible with that KMail.
 113
 114
 115 Further resources
 116 ----------------
 117 Some frequently occurring problems with Akonadi are collected under
 118 http://userbase.kde.org/Akonadi#Some_Technical_Issues.
 119
 120 For further questions feel free to contact the KDE PIM developers on
 121 kde-pim@kde.org or ask on freenode IRC channel #kontact or #akonadi
 122