Welcome to Xapian
=================

Xapian's build system is built using GNU autoconf, automake, and libtool.
If you've installed other Open Source projects from source, you should
find yourself in familiar territory.  Building and installing involves
the following 3 simple steps:

 1) Run "./configure", possibly with some extra arguments (see below)
 2) Run "make" to build Xapian
 3) Run "make install" to install Xapian


Prerequisites:
==============

You'll need to install zlib (http://www.zlib.net/) before you can build Xapian.
The zlib library is very widely used, so you'll probably have it installed
already if you're using Linux, FreeBSD, or similar.  You may need to install a
"zlib development" package to get the zlib library headers.  We recommend using
zlib 1.2.x as it apparently fixes a memory leak in deflateInit2 (which Xapian
uses) and decompression is supposed to be about 20% faster than with 1.1.x.

Compilers:
==========

We aim to support compilation with any C++ compiler which supports ISO C++,
or a reasonable approximation to it.

If you're using MS Visual C++, see the Xapian download page for a link to
a set of suitable makefiles: http://xapian.org/download.php

If you're using GCC, we currently recommend GCC 3.3 or newer.

The minimum required GCC version is 2.95.3 (2.95.2 and earlier don't have
the <sstream> header).  We still regularly peform test builds with 2.95.4 on
x86 with the aim of maintaining compatibility.  However, you may experience
spurious warning messages with this version, and on some architectures you
might get Internal Compiler Errors (in particular, GCC 2.95 for arm usually
fails to compile Xapian).

The "GCC 2.96" supplied with older RedHat releases is also best avoided.  This
isn't based on an official GCC release, but rather on a snapshot of GCC
somewhere between 2.95 and 3.0.

Building in a separate directory:
=================================

If you wish to perform your build in a separate directory from the source,
create and change to the build directory, and run the configure script (in
the source directory) from the build directory, like so:

  mkdir BUILD
  cd BUILD
  ../configure


Options to give to configure:
=============================

--enable-assertions
	You should use this to build a version of Xapian with debugging
	symbols and assertions to help with debugging.  Recommended for
	initial development with Xapian - this helps to ensure that you
	are using the API correctly.  It also enables many internal
	consistency checks, so is useful if you suspect a bug in Xapian.

--enable-backend-flint
--enable-backend-inmemory
--enable-backend-quartz
--enable-backend-remote
	These options enable (or disable if --disable-backend-XXX is specified)
	the compiling of each backend (database access methods).  By default,
	all backends for which the appropriate libraries and OS support are
	available will be enabled.

_FORTIFY_SOURCE:
----------------

When compiling with GCC, by default Xapian will be built with _FORTIFY_SOURCE
set to 2.  This enables some compile time and runtime checking of values passed
to library functions when building with GCC >= 4.1 and glibc >= 2.34 (some
Linux distros may have backported support to older GCC and/or glibc).  If you
wish to disable this for any reason, you can just configure like so:

./configure CPPFLAGS=-D_FORTIFY_SOURCE=0

Or you can set the "fortification level" to 1 instead of 2:

./configure CPPFLAGS=-D_FORTIFY_SOURCE=1

If you're disabling it because it causes problems, please also report this to
us (via the bug tracker or mailing lists).

-Bsymbolic-functions:
---------------------

When compiling with GCC and using a sufficiently new version of ld, configure
we automatically cause -Wl,-Bsymbolic-functions to be used when linking the
library.  This causes all references from inside the library to symbols inside
the library to be resolved when the library is created, rather than when the
shared library is loaded, which decreases the time taken to load the library,
reduces its size, and is also likely to make the code run a little faster.

Should you wish to disable this for some reason, you can configure like so
which disables the probe for -Bsymbolic-functions so it won't ever be used:

./configure xo_cv_symbolic_functions=no

If you're disabling it because it causes problems, please also report this to
us (via the bug tracker or mailing lists).

-fvisibility:
-------------

When compiling with GCC >= 4.0, we automatically pass -fvisibility=hidden to
g++ when building the library, and mark classes, methods, and functions which
need exporting with attributes to make them visible.

Should you wish to disable this for some reason, you can configure like so:

./configure --disable-visibility

If you're disabling it because it causes problems, please also report this to
us (via the bug tracker or mailing lists).

Compiling with STLport
======================

C++ implementations have improved significantly since we started writing
Xapian, so your native C++ standard library and STL will probably work
well.

But if you wish, you can use STLport instead.  STLport is a freely available
replacement C++ STL implementation, downloadable from:

http://stlport.sourceforge.net/

To compile with STLport:

 1) Download, build, and optionally install STLport.
 2) Configure Xapian, by running ./configure, supplying the following
    arguments:

    --with-stlport=<path>, where <path> is the path to the STLport
        software.  The directory pointed to by <path> should contain
        stlport/ and lib/ subdirectories.

    --with-stlport-compiler=<name>, where <name> is the name of the
        compiler you are using.  This must correspond to the compiler
        name in the name of the STLport library.  For example, with
        GCC, the STLport library would be called libstlport_gcc, and
        you should give --with-stlport-compiler=gcc.

 3) Compile and use Xapian as normal, by running make.

Note that, unless you compile statically, you must make sure that the
STLport library is on the library path at runtime: on Linux you could
do this by setting the LD_LIBRARY_PATH environment variable to point
to the directory containing the library.


Developers:
===========

There are additional scripts and configure options to help people doing
development work on Xapian itself, and people who are building from SVN.
Read HACKING to find out about them.
