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"
 3) Run "make install" to install Xapian


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

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

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

GCC's C++ support has improved a lot since GCC 2.95, and you may experience
spurious warning messages or even Internal Compiler Errors if you try to use
2.95 (in particular, GCC 2.95 for arm fails to compile Xapian).

The "GCC 2.96" supplied by RedHat 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.

Even older GCC compilers (including EGCS) are most unlikely to work at all
due to lack of support for various C++ features which Xapian uses.


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-debug
	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-*
	These options enable the compiling of each of the backends.  (Database
	access methods.)  Use "./configure --help" to get a full list of
	the backends.  By default, all backends for which the appropriate
	libraries and OS support are available will be enabled, except for the
	muscat36 backend which offers legacy support for databases built with
	the proprietary Muscat 3.6.


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 CVS.
Read HACKING to find out about them.
