koffice/README.PACKAGERS

Packaging Information for KOffice.
----------------------------------

We recommend building several binary packages from the KOffice source.

Splitting KOffice 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. Database drivers (MySQL, PostgreSQL)
2. Development files
 2.1. KexiDB development files
 2.2. Chalk development files 
3. Scripting support
4. Microsoft Access Import (optional, recommended)
5. Quick command-line tests of Kexi installation



1. Database drivers
-------------------

Kexi provides database drivers for MySQL and PostgreSQL.  We suggest
putting 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: libmysqlclient for MySQL; and
and libpqxx for PostgreSQL (libpqxx in turn depends on libpq).

Thus, the MySQL driver package could contain:
 lib/trinity/kexidb_mysqldriver.so
 lib/trinity/kexidb_mysqldriver.la
 lib/trinity/keximigrate_mysql.so
 lib/trinity/keximigrate_mysql.la
 share/services/kexidb_mysqldriver.desktop
 share/services/keximigrate_mysql.desktop

The PostgreSQL driver package consists of the following files:
 lib/trinity/kexidb_pqxxsqldriver.so
 lib/trinity/kexidb_pqxxsqldriver.la
 lib/trinity/keximigrate_pqxx.so
 lib/trinity/keximigrate_pqxx.la
 share/services/kexidb_pqxxsqldriver.desktop
 share/services/keximigrate_pqxx.desktop

Note that you SHOULD NOT care about SQLite database driver or adding 
dependencies for SQLite, because SQLite support is built into Kexi 
using a fork of SQLite source code.


2. Development files
--------------------

2.1. KexiDB development files

Location: koffice/kexi/kexiutils, koffice/kexi/kexidb, koffice/kexi/migration

KexiDB, the database abstraction library used in Kexi, installs some
development files which are required for building external plugins,
such as the MS Access import plugin described below.

We recommend providing KexiDB development files in a separate package.
The files are:
  include/kexidb/*.h
  include/kexiutils/*.h
  lib/libkexidb.la
  lib/libkexidb.so
  lib/libkexidbparser.so
  lib/libkexidbparser.la

The installation can be tested by building the MS Access import plugin
as described in the Microsoft Access import plugin section below.

2.2. Chalk development files 

Location: koffice/chalk/core, koffice/chalk/sdk,
koffice/chalk/chalkcolor, koffice/chalk/ui

These directories contain header files that are installed and can be
used by plugin developers to extend Chalk 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. Scripting support
--------------------

Preliminary support for Ruby and Python scripting is available for
Chalk and Kexi.
It can be disabled by passing the '--disable-scripting' option to
'configure'.

The 'Kross' scripting library (koffice/lib/kross) provides access to
the Python and Ruby scripting languages by the dynamically loaded
plugins.

Build time dependencies:
  Python and Ruby development packages need to be installed in order
  to build KOffice with full scripting support.  In addition, the Ruby
  interpreter is also required at build time.

Run time dependencies:
  Kross detects which of these libraries is installed dynamically, at
  run-time.  Therefore, KOffice packages need not have any run-time
  dependencies on any scripting interpreter.

The scripting language plugins can be found in:
  koffice/lib/kross/python; and
  koffice/lib/kross/ruby.
They install as:
  lib/trinity/krosspython.{la,so}; and
  lib/trinity/krossruby.{la,so}

It is recommended to put each interpreter plugin into a separate
package, and the user decide if they would like support for each
language individually.

For example, the Python scripting package may contain:
  lib/trinity/krosspython.so
  lib/trinity/krosspython.la
  share/apps/kexi/scripts/exportxhtml/ExportXHTML.py
  share/apps/kexi/scripts/exportxhtml/ExportXHTML.rc
  share/apps/kexi/scripts/importxhtml/ImportXHTML.py
  share/apps/kexi/scripts/importxhtml/ImportXHTML.rc
  share/apps/kexi/scripts/projectdocumentor/ProjectDocumentor.py
  share/apps/kexi/scripts/projectdocumentor/ProjectDocumentor.rc
  share/apps/chalk/scripts/invert.py
  share/apps/chalk/scripts/reshapehisto.py

and the Ruby scripting package may contain:
  lib/trinity/krossruby.so
  lib/trinity/krossruby.la
  share/apps/chalk/scripts/ruby/invert.rb
  share/apps/chalk/scripts/ruby/changecs.rb
  share/apps/chalk/scripts/ruby/randompaint.rb


4. Microsoft Access Import (optional, recommended)
-------------------------------------

A plugin to allow the import of MS Access (.mdb) files is available
for packaging separately.  It is called KexiMDB.

This package is based on a stripped-down and modified version of
mdbtools: http://mdbtools.sf.net/
The package should be built after KOffice.  It requires GLib, and the
Kexi development files as described above.

The version of the plugin for use with KOffice 1.5 should be available
from:
ftp://ftp.kde.org/pub/kde/stable/apps/KDE3.x/database/keximdb-1.0.tar.gz

Alternatively, it can be found in the KDE Subversion repository.  It
can be built as follows:
  svn export svn://anonsvn.kde.org/home/kde/branches/work/keximdb/koffice-1.5 keximdb-1.0
  cd keximdb-1.0
  make -f Makefile.cvs
  ./configure --enable-debug=full
  make
  make install

Configure may need to be informed of the location of the KexiDB
headers using the --with-kexidb-includes=... and the
--with-kexidb-libraries=... options.


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 message)
This will:
- create a new empty database file "testdb",
- open it,
- create a new empty form