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. Kexi default database driver: SQLite
1.4. Other Kexi plugins to package separately
1.4. Kexi development files
1.5. Quick command-line tests of Kexi installation
2. Krita
2.1. Krita development files
3. Debug information
4. Calligra plugins
5. Calligra libraries
6. WARNING against qt 4.8.0 and 4.8.1

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. Kexi default database driver: SQLite
-----------------------------------------

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

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 Kexi will not compile and run.


1.3. 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.4. Kexi development files
---------------------------

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


1.5. 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-map-shape      Description: Map shape for Calligra applications
                           Contents:
                               mapshape.so
                               mapshape.desktop
                           Translation File:
                               MapShape.mo
                           Dependencies:
                               libmarble4-kde4 or marble
                                                      (provides libmarblewidget)

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
main
odf
pigment
widgets

5. 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
