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

Advice for packagers / maintainers
Updated December 2005 for QOF 0.6.1

(This file contains the text from 
http://qof.sourceforge.net/hacking.html )

Contents
-------------------------
Building against QOF 
AUTOMAKE example
libqof1 API/ABI compatibility.
MAX_REQUIRED specifiers
DWI is optional
Mac OSX
Packaging QOF. 
libqof-backend-qsf.la in libqof1
libxml2 >= 2.5.10
There is no QOF dependency on Gtk!
Using libqof-dev
lib/libsql
--------------------------

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.6.0
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 >= 0.6.0 (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 and CashUtil which 
include an optional method to build from QOF CVS source as well as the
package.

 http://pilot-qof.sourceforge.net/
 http://linux.codehelp.co.uk/cashutil/

libqof1 API/ABI compatibility.

During the life of the QOF 0.6.x tree, various functions will be 
deprecated and renamed - leaving a #define to support the old name. New 
code will be expected to use the new name and old code the #define 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 is optional

DWI - Data With Interaction - is a QOF backend in development and it 
has it's own SourceForge project and homepage.

 http://dwi.sourceforge.net/

DWI development seems to have stalled and it has not been tested against 
libqof1. QOF still checks for DWI but DWI is completely optional and there 
is no reason to include DWI with QOF at this time.
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


PACKAGING QOF

libqof-backend-qsf.la in libqof1

This section has been re-written in the light of real usage of the QOF 
library, in particular on embedded systems. The previous statements about 
the .la files mainly reflected a previous implementation before the switch 
to GModule. I would recommend that the .la files are installed with the main 
library where possible but it is no longer a requirement of QOF. 

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.

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.1-2.
Therefore, libgda will be used wherever possible and lib/libsql will 
eventually be reserved only for systems that cannot use libgda.
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.
