Packaging Information for Calligra Suite
----------------------------------------

We recommend building several binary packages from the Calligra source.

Splitting Calligra into packages:
 * gives users a better choice of which components they have
   installed;
 * allows users to install just the applications without unnecessary
   dependencies;
 * helps to reduce packaging conflicts for users with non-standard
   package selections.


Table Of Contents
-----------------
1. Kexi
1.1. Kexi database and migration drivers to package separately
1.2. Other Kexi plugins to package separately
1.3. Kexi development files
1.4. Quick command-line tests of Kexi installation
2. Krita
2.1. Krita development files
3. Debug information
4. Calligra plugins
5. Calligra libraries
5.1. Calligra default database driver: SQLite
6. WARNING against qt 4.8.0 and 4.8.1
7. IMPORTANT On using CPU vector capabilities in Calligra Libs and Krita
8. Plan
8.1. Runtime dependency of Plan's import filters


1. Kexi
=======

1.1. Kexi database and migration drivers to package separately
--------------------------------------------------------------

Kexi provides database drivers and migration drivers for a number of
database types or data sources.

We encourage to put each driver in a separate package, and that installation of
these packages be optional.  Each driver package may then depend on the corresponding
'native' libraries. For example libmysqlclient for MySQL and libpqxx for PostgreSQL
(libpqxx in turn depends on libpq).

The following matrix lists the packages and dependencies.

 Suggested Name            Details
 ------------------------------------------------------------------------
 kexi-mysql-driver         Description: Kexi MySQL driver
                           Database driver files:
                               kexidb_mysqldriver.so
                               kexidb_mysqldriver.desktop
                           Migration driver files:
                               keximigrate_mysql.so
                               keximigrate_mysql.desktop
                           Dependencies:
                               libmysqlclient
 ------------------------------------------------------------------------
 kexi-postgresql-driver    Description: Kexi PostgreSQL driver
                           Database driver files:
                               kexidb_pqxxsqldriver.so
                               kexidb_pqxxsqldriver.desktop
                           Migration driver files:
                               keximigrate_pqxx.so
                               keximigrate_pqxx.desktop
                           Dependencies:
                               libpq
                               libpqxx
 ------------------------------------------------------------------------
 kexi-sybase-driver        Description: Kexi Sybase & MS SQL driver
                           Database driver files:
                               kexidb_sybasedriver.so
                               kexidb_sybasedriver.desktop
                           Migration driver files:
                               keximigrate_sybase.so
                               keximigrate_sybase.desktop
                           Dependencies:
                               libsybdb (FreeTDS)
 ------------------------------------------------------------------------
 kexi-xbase-driver         Description: Kexi XBase driver
                           Database driver files:
                               kexidb_xbasedriver.so
                               kexidb_xbasedriver.desktop
                           Migration driver files:
                               keximigrate_xbase.so
                               keximigrate_xbase.desktop
                           Dependencies:
                               libxbase
 ------------------------------------------------------------------------
 kexi-spreadsheet-import   Description: Spreadsheet-to-Kexi-table import plugin
                           Files:
                               keximigrate_spreadsheet.so
                               keximigrate_spreadsheet.desktop
                           Translation File:
                               keximigrate_spreadsheet.mo
                           Dependencies:
                               sheets (Calligra Sheets)
 ------------------------------------------------------------------------


Plugin .so files are typically installed to $KDEDIR/lib/kde4/,
and .desktop service files are installed to $KDEDIR/share/services/.

Notes:
* Oracle driver is not currently distributed.

TODOs:
* Add minimal versions of dependencies.


1.2. Other Kexi plugins to package separately
---------------------------------------------

Kexi provides less a number of plugin types that are optional either because 
are less frequently used or because have larger dependencies. We encourage 
to put each driver in a separate package, and that installation of these
packages be optional. 

The following matrix lists the packages and dependencies.

 Suggested Name            Details
 ------------------------------------------------------------------------
 kexi-web-form-widget      Description: Kexi web form widget
                           Contents:
                               kformdesigner_webbrowser.so
                               kformdesigner_webbrowser.desktop
                           Translation File:
                               kformdesigner_webbrowser.mo
                           Dependencies:
                               libqt4-webkit or libQtWebKit4 (provides QtWebKit)
 ------------------------------------------------------------------------
 calligra-reports-web-element Description: Web element for Calligra Reports
                           Contents:
                               koreport_webplugin.so
                               koreport_webplugin.desktop
                           Translation File:
                               koreport_webplugin.mo
                           Dependencies:
                               libqt4-webkit or libQtWebKit4 (provides QtWebKit)
 ------------------------------------------------------------------------
 kexi-map-form-widget      Description: Kexi map form widget
                           Contents:
                               kformdesigner_mapbrowser.so
                               kformdesigner_mapbrowser.desktop
                           Translation File:
                               kformdesigner_mapbrowser.mo
                           Dependencies:
                               libmarble4-kde4 or marble
                                                      (provides libmarblewidget)
 ------------------------------------------------------------------------
 calligra-reports-map-element Description: Map element for Calligra Reports
                           Contents:
                               koreport_mapsplugin.so
                               koreport_mapsplugin.desktop
                           Translation File:
                               koreport_mapsplugin.mo
                           Dependencies:
                               libmarble4-kde4 or marble
                                                      (provides libmarblewidget)

1.3. Kexi development files
---------------------------

Kexi ships no development files at the moment, so -devel packages are not needed.


1.4. Quick command-line tests of Kexi installation
--------------------------------------------------

If you don't want to click through Kexi interface but still want
to make (almost) sure the application is properly packaged, please 
install it and type the following from the command line:

 kexi --create-opendb --drv sqlite3 --new form testdb

(ignore possible warning messages)
This will:
- create a new empty database file "testdb",
- open it,
- create a new empty form


2. Krita
========

2.1. Krita development files
----------------------------

Location: calligra/krita/image, calligra/krita/ui

These directories contain header files that are installed and can be
used by plugin developers to extend Krita with new tools, colorspaces,
paint-ops and more.  If your distribution packages development files
separately, it may be a good idea to make a package with these headers.


3. Debug information
====================

For alpha and beta packages, please build with debug output enabled, but for
production packages the -DCMAKE_CXX_FLAGS="-DKDE_NO_DEBUG_OUTPUT" is recommended.
A significant performance increase will be the result.


4. Calligra plugins
===================

Calligra applications can use plugins, placed in plugins/ subdirectory.
Some of them are very special and/or have extra dependencies so should
be packaged separately.


 Suggested Name            Details
 ------------------------------------------------------------------------
 calligra-semanticitems  Description: Calligra semantic item plugins
                           Contents:
                               calligra_semanticitem_contact.so
                               calligra_semanticitem_contact.desktop
                               calligra_semanticitem_event.so
                               calligra_semanticitem_event.desktop
                               calligra_semanticitem_location.so
                               calligra_semanticitem_location.desktop
                           Translation File:
                               calligra_semanticitem_contact.mo
                               calligra_semanticitem_contact.mo
                               calligra_semanticitem_location.mo
                           Dependencies:
                               libkdepimlibs (kabc, kcalcore, akonadi)
                               libmarble4-kde4 or marble
                                                      (provides libmarblewidget)

If Calligra is build with support for RDF enabled, it is STRONGLY RECOMMENDED to
separate the semantic item plugins coming from "plugins/semanticitems" into
their own package. That package should not be an automatic dependency on any
other Calligra package, but only installed explicitely by the user. Reason are
the external dependencies with these plugins, especially kdepimlibs.

So if e.g. a user just installs the Krita package, this should not pull in all
the things that KDEPIM/Akonadi pulls in.


5. Calligra libraries
====================

Calligra share common functionality within libraries, placed in libs/
subdirectory. Calligra libraries should be placed in a single package,
separate from Calligra applications. Below is the list of the libraries.

Name       Conditional compilation flag    Globally used in Calligra?   Public API
                                                                       (headers installed)
           (default: NO)                   (default: YES)              (default: YES)
------------------------------------------------------------------------------------------

flake
kokross                                                                NO
kopageapp
koplugin                                                               NO
koproperty                                 Kexi, Plan                  NO
koreports                                  Kexi, Plan                  NO
kotext
komain
koodf
kordf                                      Words/Author, Active
pigment
kowidgets


5.1. Calligra default database driver: SQLite
---------------------------------------------

In contrast to the all other Kexi database drivers, SQLite 3 driver SHOULD BE PART
of the Calligra libraries package nor Kexi package, and it SOULD NOT be in optional.
Thus, the Calligra libraries package should depend on SQLite 3 package.

The SQLite 3 driver depends on the calligradb library, and not on Kexi itself.

Recommended version of SQLite package is defined in the source code and can
be obtained by executing this command in calligra/ directory:
 % grep SQLITE_RECOMMENDED_VERSION CMakeLists.txt

Minimal version of SQLite package is defined in the source code and can
be obtained by executing this command in calligra/ directory:
 % grep CalligraSqlite CMakeLists.txt

Without SQLite in at least this version Calligra will not compile.


6. WARNING against qt 4.8.0 and 4.8.1
====================
Using Qt 4.8.0 and 4.8.1 causes crashes. As a result Words and Stage will not be built. Please upgrade to 4.8.2. You can also patch Qt and when building Calligra set IHAVEPATCHEDQT. Patch against Qt can be found in qt48setx.patch in this directory


7. IMPORTANT On using CPU vector capabilities in Calligra Libs and Krita
====================

IN BRIEF: 1) Intall Vc library [1] and don't forget to activate
             PACKAGERS_BUILD=ON option when building a package.
          2) Vc libary should be present on the building system only,
             it need not be installed on all the client systems.

Krita and Pigment can make use of the vector capabilities of the
user's CPU. To make it possible Vc library [1] should be present in
the host system. This is a static library and fully included into the
final Pigment/Krita binary, so it is not necessary to have it
installed in the client system.

The code generation is generally controlled by two factors: the
presence of the Vc library and a special cmake option
'PACKAGERS_BUILD'. Consider three cases:

1) Vc library is not present. PACKAGERS_BUILD=<don't care>.

The calligra is build with default compiller options. The resulting
binary is non-optimized and portable among different CPU
architectures.

2) Vc library is present. PACKAGERS_BUILD=OFF (default).

All the calligra binaries are optimized for the host CPU. This is the
most efficient type of build of Krita. But be careful, because such
binaries are not portable among different CPU architectures! Using
this build for packages distributed to many users will most probably
result in SIGILL crashes on the client system. Use this option for
private builds only.

3) Vc library is present. PACKAGERS_BUILD=ON.

This option disables CPU optimizations for the most of Calligra, but
gnerates several versions of the code for its hottest parts. The
specific implementation of the code is chosen on the fly when Calligra
starts. This version is a bit slower than 2) but much faster than 1)
and is *portable* among all the CPU architectures. Use this type of
build for building distributable packages.

[1] - http://code.compeng.uni-frankfurt.de/projects/vc


8. Plan
=======

8.1. Runtime dependency of Plan's import filters
------------------------------------------------
The two current import filters, for project files from MS Project and Planner,
both are based on mpxj (http://mpxj.sourceforge.net/, in Java) and Apache
POI.
Thus java needs to know how to locate the mpxj and Apache POI jar files:
if not installed in the normal place where Java finds them, the location will
have to be given by the PLAN_CLASSPATH environment variable, e.g:
$ PLAN_CLASSPATH=/path/to/mpxj/mpxj.jar:/path/to/poi/poi.jar calligraplan&

If your distribution is not yet able to provide those dependencies, please
disable the Plan import filters by patching the toplevel CMakeLists.txt
in the line before calligra_drop_unbuildable_products() with
calligra_disable_product(FILTER_MPXJ_IMPORT "missing runtime deps")
