Packaging and building against QOF
==================================

Advice for packagers / maintainers
Updated December 2006 for QOF 0.7.2

    * Building against QOF
          o AUTOMAKE example
          o libqof1 API/ABI compatibility.
          o MAX_REQUIRED specifiers
          o DWI now unsupported.
          o libgda versions.
    * Packaging QOF.
          o libqof-backend-qsf.la in libqof1
          o libxml2 >= 2.5.10
          o There is no QOF dependency on Gtk!
          o Which backend to use?
          o QOF for embedded devices
    * Using libqof-dev


BUILDING AGAINST QOF
====================

AUTOMAKE
--------

The simplest way to use QOF is with PKG_CHECK_MODULES in configure.ac:

dnl *************************************
dnl QOF
dnl *************************************

QOF_REQUIRED=0.7.2
PKG_CHECK_MODULES([QOF], [qof-1 >= ${QOF_REQUIRED}])
AC_SUBST(QOF_CFLAGS)
AC_SUBST(QOF_LIBS)


You can add further commands to retrieve other information:

    * QOF Version string:

      QOF_VERSION=`$PKG_CONFIG --silence-errors --modversion qof-1`

    * QOF prefix

      QOF_PREFIX=`$PKG_CONFIG --silence-errors --variable=prefix qof-1`

    * Location of QOF backend modules

      QOF_LIB_DIR=`$PKG_CONFIG --silence-errors --variable=libdir qof-1`

    * Location of the QSF XML schemas

      QOF_XML_DIR=`$PKG_CONFIG --silence-errors --variable=xmldir qof-1`

Or consider this more verbose example:

dnl *************************************
dnl QOF
dnl *************************************

QOF_REQUIRED=0.7.2
AC_PATH_PROG(PKG_CONFIG, pkg-config, no)
if test pkg-config = no; then
	AC_MSG_ERROR([Please install pkgconfig])
	exit 1
fi
AC_MSG_CHECKING([for QOF - version >= $QOF_REQUIRED])
QOF=`$PKG_CONFIG --silence-errors --exists 'qof-1 >= $QOF_REQUIRED'`
QOF_LIBS=`$PKG_CONFIG --silence-errors --libs qof-1`
QOF_CFLAGS=`$PKG_CONFIG --silence-errors --cflags qof-1`
QOF_VERSION=`$PKG_CONFIG --silence-errors --modversion qof-1`
QOF_PREFIX=`$PKG_CONFIG --silence-errors --variable=prefix qof-1`
QOF_LIB_DIR=`$PKG_CONFIG --silence-errors --variable=libdir qof-1`
QOF_XML_DIR=`$PKG_CONFIG --silence-errors --variable=xmldir qof-1`

AC_SUBST(QOF_CFLAGS)
AC_SUBST(QOF_LIBS)
AC_SUBST(QOF_PREFIX)
AC_SUBST(QOF_LIB_DIR)
AC_SUBST(QOF_XML_DIR)
if test x$QOF_XML_DIR = x; then
        AC_MSG_RESULT([no])
        AC_MSG_ERROR([
        The package requires the Query Object Framework: QOF.
        You need to install QOF >= ${QOF_REQUIRED} (libqof1).
        You can find it at http://qof.sourceforge.net/
])
        exit 1
else
        AC_MSG_RESULT([yes (found $QOF_VERSION)])
fi

For more information, see the source for Pilot-QOF, 
gpe-expenses or CashUtil which include an optional method 
to build from QOF CVS source as well as the package.

http://pilot-qof.sourceforge.net/

http://cashutil.sourceforge.net/

http://gpe-expenses.sourceforge.net/


libqof1 API/ABI compatibility.
------------------------------


During the life of the QOF the 0.6.x and 0.7.x trees, 
various functions will be deprecated and renamed - 
leaving a #define or deprecated version to support 
the old name. New code will be expected to use the new 
name and old code the deprecated version. Then when all 
such code has been sorted out, applications have two choices:

   1. Move to the new API with the library, or
   2. Integrate the #define's in a header of their own.

Either way, the deprecated functions will then be removed 
from QOF in a single operation that takes us smoothly 
from libqof1 to libqof2.


MAX_REQUIRED specifiers
------------------------------

Some packages have previously used:

LIBQOF_REQUIRED_MIN=0.5.2
LIBQOF_REQUIRED_MAX=0.5.2

The MAX value is no longer required. QOF will only 
change the API/ABI on a SONAME increment. So each 
release of libqof1 will always be API/ABI compatible 
with previous releases of libqof1. It is recommended 
to only specify a minimum and accept any later 
version of QOF.


DWI has stalled
------------------------------

Updated for QOF 0.7.2

DWI - Data With Interaction - was in development but 
it's SourceForge project has seen little recent 
activity and is now out of date with the main QOF 
library.

DWI development has stalled and it has not been 
tested against libqof1. QOF configuration checks 
for DWI have been removed in QOF 0.7.2 and there 
is unlikely to be any DWI support in libqof2.

If you decide to try using DWI against libqof1, 
please report your results (good or bad) to the 
QOF-devel mailing list.

http://lists.sourceforge.net/lists/listinfo/qof-devel


libgda versions
------------------------------

(See the notes on libgda module delays on the website.)

libda-2.0 is nearing release but is not yet ready - 
despite some distributions packaging the unreleased 
code. QOF only uses the SQL handling code from libgda 
at this time - until the GDA backend is reviewed. This 
SQL handling code was copied out of libgda at an earlier 
release and is built by QOF internally if libgda is not 
found.

This arrangement will continue until libgda-2.0 is on 
full release. QOF 0.7.2 does not support libgda-2.0 and 
will ignore libgda-2.0 on systems where it is installed. 
This is not a problem or a bug but a deliberate decision. 
Patches to support libgda-2.0 will not be accepted. It is 
preferable to let QOF build the SQL handling code internally. 
Once the gda backend is reviewed, support for libgda can 
be updated. See also libsql in QOF.


Mac OSX
------------------------------


Specify your Mac OSX compiler settings as environment 
variables. e.g. for fink use:

export CPPFLAGS="-I/sw/include"
export LDFLAGS="-L/sw/lib"
export LIBTOOL="glibtool"
export PATH="/sw/bin:$PATH"
export ACLOCAL_FLAGS="-I /sw/share/aclocal"

Helpful pair of settings for general manpage usage 
(to go into .bashrc in your home directory):

export MANPATH="/sw/share/man:<build_path>"
export PAGER="less -s"

To only use these for this one build, create a bash 
script and export the variables before calling 
./autogen.sh

QOF is no longer routinely built on OSX. If you 
encounter problems, post the 'config.h' file from 
the top directory of your build to the QOF-devel 
mailing list.

PACKAGING QOF
=============

libqof-backend-qsf.la in libqof1
--------------------------------

Updated

See the section on backends.


libxml2 >= 2.5.10
--------------------------------

The version string is vital. (Earlier versions will 
break the QSF backend horribly.)


There is no QOF dependency on Gtk!
--------------------------------

Do not list a QOF runtime or build dependency on libgtk. 
The one example that could use Gtk has now been removed 
from the distribution tarball along with the other 
(outdated) examples.

That's all there ever was to the Gtk stuff. It's 
important because projects like pilot-link will not accept 
code that links to GUI stuff for no good reason.



Which backend to use?
--------------------------------

QSF XML has always been a separate module, the new 
SQLite backend is also a separate module. 
When packaging QOF >=0.7.1, maintainers have the option to 
use one or both backends (QOF requires at least one backend 
to be available).

    * libqof-backend-qsf0 : Default XML backend for 
    	most applications.
    * libqof-backend-sqlite0 : SQLite backend intended 
    	for embedded applications where libxml2 is simply 
    	too large for the available storage space.
    * roll-your-own : Some applications already have 
    	their own backends for use via QOF.
    * Future backends : GnomeDB support is expected for 
    	a future QOF release. This will add a further 
    	module which in turn allow for other plugins for 
    	libgda itself. (See the notes on libgda module delays.)

QOF can be packaged separately from the modules but care is 
needed to ensure that existing applications can locate and 
load the necessary backend. Applications that cannot load 
the necessary backend will typically fail to start or be 
unable to load or save data.

At present, only pilot-qof and gpe-expenses support all 
available QOF backends. In most cases, it is wise to ensure 
that at least libqof-backend-qsf0 is available for all 
existing QOF applications. New applications and new versions 
of existing applications can be configured to load new and 
additional backends.


QOF for embedded devices
--------------------------------

libxml2 is getting quite large; too large for some embedded 
devices, especially as it is only a backend. The SQLite 
backend was written especially for embedded devices or other 
situations where QOF is to be used on systems with limited 
resources. QOF >= 0.7.1 provides two backend modules that 
can be packaged separately:

    * libqof-backend-qsf0 : Depends on libxml2.
    * libqof-backend-sqlite0 : Depends on libsqlite0.

libqof1 requires the installation of at least one backend 
module, QSF XML should be the default for all systems that 
can support libxml2 because the sqlite backend is not yet 
comprehensive. Full support is due in the next backend 
module based on GnomeDB (via libgda).

Q:	Packaging the QSF XML backend separately from the main 
	library does not actually remove libxml2 from the 
	dependency list of the library. Why?

A:	libgda includes a dependency on libxml2 that replaces 
	the dependency removed by packaging QSF XML separately. 
	If you've built QOF with libgda installed, the libxml2 
	dependency will be retained. I believe this is fixed in 
	libgda-2.0 (see QOF and GDA) but QOF 0.7.2 does not yet 
	support libgda-2.0. See also libsql in QOF. 

Q:	What's the solution?

A:	To remove libxml2 from the dependency list, also remove 
	libgda so that QOF uses the internal SQL handling. This 
	leaves only a dependency on glib and the inevitable GNU libc. 
	Using libqof-backend-sqlite0 only adds a dependency on 
	libsqlite0.

 Package: libqof1
 Version: 0.7.2-1
 Section: libs
 Priority: optional
 Architecture: amd64
 Depends: libc6 (>= 2.3.5-1), libglib2.0-0 (>= 2.10.0)


libqof-dev usage
--------------------------------


The QOF API specifies the use of:

#include "qof.h"

or

#include <qof.h>

- this is because some headers in libqof-dev need 
to be included in the correct sequence. Individual 
filenames and file contents are also subject to change 
during the life of libqof1 and packages using QOF need 
to only use qof.h to avoid problems moving to libqof2.


Replacement of lib/libsql
--------------------------------

The code in lib/libsql came from the libgda package at 
about v1.0.3 and is now commonly available, including 
on Mac OSX via fink - albeit at only v1.0.4-3.

Fedora Core 3 has 1.0.4, Fedora Core 4 has 1.2.0 and Debian has 1.2.2.

libgda comes in stable and unstable releases. At time of 
writing, the stable release is 1.2.3 (libgda2-3 in Debian). 
QOF does not support the unstable libgda releases. If your 
distribution has libgda 1.3.x or 1.9.x, please do not patch 
QOF to use the unstable code. Instead, let QOF use it's 
internal code. QOF currently uses a fraction of the libgda 
codebase and until a full QOF/GDA backend is available, 
QOF will not be supporting any of the unstable libgda releases.

This also helps complete the CashUtil project that will need 
the SQL handling in QOF and GnuCash itself which is likely 
to use more SQL directly in the future.


Roadmap
--------------------------------

Outline plan of the next few releases. All items are subject 
to change, but this is how it looks so far.

Note that the schedule for libqof2 has been postponed - 
the use of QOF in embedded systems is expected to prove 
useful in reorganising libqof1 in preparation for libqof2.

   1. libqof2

      Once these steps are complete, the rest of QOF will 
      be reviewed - including moving certain sections of 
      code around within the codebase to make the overview 
      clearer and the library easier to follow. A series of 
      pre-releases for libqof2 can then begin. Expect 
      pre-releases Summer 2007 and libqof2, QOF 1.0.0, 
      Autumn 2007. Note that libqof2 will start with the 
      last release of libqof1 but with all deprecated code 
      removed. Users who migrate with libqof1 will be able 
      to transfer to libqof2 without problems. The libqof2 
      API will then remain stable, just as with libqof1, 
      but with a reduced release cycle. No large changes 
      are anticipated in libqof2, the aim is to get all 
      those done in libqof1.

	2. QOF/GDA Backend

	  A more comprehensive backend based on libgda is planned, 
	  supporting various databases via GnomeDB plugins. This 
	  will not be implemented directly on embedded systems. 
	  This could be a relatively large amount of new code. 
	  Early work has now stalled, pending a new stable release 
	  of libgda upstream that allows the creation (and deletion) 
	  of tables within new or existing data sources. (See above.) 
	  Pending. Hopefully before liqof2, but delays in libgda will 
	  not delay libqof2.

Support for GLib GObject mapping (qofgobj.c) is not currently 
anticipated before libqof2. If everything else is ready for 
libqof2, libqof2 will proceed without GLib Gobject mapping.


Packaging documentation
--------------------------------

The doxy symlink in the website directory is provided for CVS 
users and the main SourceForge site. When packaging the website 
HTML alongside the Doxygen output, ignore the symlink and just 
package the Doxygen output:

    * doc/html/* => /usr/share/doc/libqof-doc/html/doxy/

and the website content:

    * website/*.html => /usr/share/doc/libqof-doc/html/
    * website/*.css => /usr/share/doc/libqof-doc/html/
    * website/*.png => /usr/share/doc/libqof-doc/html/
    * website/*.jpg => /usr/share/doc/libqof-doc/html/

Written by Neil Williams <linux@codehelp.co.uk> December 2005.

Last updated by Neil Williams <linux@codehelp.co.uk> December 2006.

The copyright licensing notice below applies to this text.
Copyright © 2005,2006 Neil Williams

Permission is granted to copy, distribute, and/or modify this 
document under the terms of the GNU Free Documentation License, 
Version 1.2 or any later version published by the Free Software 
Foundation; with no Invariant Sections, with no Front-Cover Texts, 
and with no Back-Cover Texts. In installed versions, the licence 
can be found in the copyright file.