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

Advice for packagers / maintainers
Updated August 2006 for QOF 0.7.1

    * Building against QOF
          o AUTOMAKE example
          o libqof1 API/ABI compatibility.
          o MAX_REQUIRED specifiers
          o DWI likely to be unsupported soon.
          o Mac OSX
    * 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
--------

Using automake, consider this example as the basis for your 
commands for in configure.ac:

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

QOF_REQUIRED=0.7.1
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, 0.7.x and 0.8.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.1

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 are likely to be 
removed in QOF 0.8.0 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


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.

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 supports 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 (new) : 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.

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.1-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.2 (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.

QOF 0.8.0

   1.
      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, expect for early 
		2007. Expected 0.8.0, still as libqof1.
   2.
      QofKvp

      Various Kvp functions need to be reviewed, a KVP_TYPE_BOOLEAN 
		is long overdue and the split between public and private Kvp 
		functions needs to be completely redone. Expected: Late 
		2006, early 2007.
   3.
      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.

Support for GLib GObject mapping (qofgobj.c) is not currently 
anticipated before QOF 0.8.0. 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> September 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.
