Installing xapian-bindings
==========================

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

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, then run the configure script (in
the source directory) from the build directory, like so:

  mkdir BUILD
  cd BUILD
  ../configure
  make
  make install

Known Issues
------------

 * The bindings glue code generated by SWIG is quite large and can be slow
   and resource-intensive to compile.  Things have improved a lot since older
   Xapian versions.  E.g. 1.4.30's Python 3 bindings take about 40 seconds
   to compile and link with peak memory usage of 507MB on x86-64 using GCC
   15.2).

   If your system doesn't have much memory or defaults to imposing resource
   limits on process size, you may still have problems building the bindings.
   If you are hitting resource limits, you can adjust these using `ulimit`.

   If you need to make the build use less memory and/or run faster, you can
   build without optimisation (but the bindings will be slower at runtime):

     make CXXFLAGS=-g

 * Typically the bindings need to be installed a directory which the target
   language interpreter searches or else they won't be found.  For this reason,
   xapian-bindings build system probes for a suitable location and installs
   the bindings there.  Installing outside of the specified prefix is unusual
   behaviour for autotools-based build systems but this seems a more helpful
   default behaviour than installing something which doesn't work.

   The specified prefix is used for installing documentation and examples.

   If you don't have root access, read the section "Installing without root
   access" below.

Prerequisites
=============

 * xapian-core: We recommend using matching versions of xapian-core and
   xapian-bindings as we don't test non-matching versions.  If you install
   xapian-core from a package, make sure you also install the development files
   which are often packaged separately (e.g. in libxapian-dev or
   xapian-core-devel).

 * You'll also need tools specific to the language(s) you want to build
   bindings for.  Package systems often separate the files you need to build
   the bindings into a separate package with a `-dev` or `-devel` suffix.
   Additional per-language dependencies are:

   + Python 2:
     - Sphinx Documentation Generator: https://www.sphinx-doc.org/
       The package you want might be python-sphinx.
   + Python 3:
     - Sphinx Documentation Generator: https://www.sphinx-doc.org/
       The package you want might be named python3-sphinx.

Compilers
=========

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

GCC
---

If you're using GCC, we currently recommend GCC 4.7 or newer (this is the
oldest version we regularly test with).

The current hard minimum requirement is also GCC 4.7 (due to requiring good
support for C++11, for example non-static data member initializers aren't
supported by earlier versions).

If you really still need to use an older version of GCC, Xapian 1.2.x doesn't
require C++11 support and should build with older versions - probably as far
back as GCC 3.1.

Clang
-----

Clang 6.0 is known to work.  We haven't identified the exact minimum
requirement, but it's probably at least Clang 3.2.

MSVC
----

Xapian-core can be built using MS Visual C++.  Theoretically xapian-bindings
can be too but we haven't tested this.  If you want to get this working, see
the xapian-core installation instructions for a starting point.

HP's aCC
--------

When using HP's aCC, Xapian must be compiled with +std=c++11, which
xapian-core's configure automatically detects and passes.  You don't have to
pass this option when building code which uses Xapian, but you can.

Sun C++ Compiler
----------------

With this compiler, shared library builds of xapian-core fail (tested most
recently with version 12.6).  The bindings are usually built as shared objects
so you are likely to struggle with similar problems if you want to build the
bindings with this compiler.

Command-line options to pass to configure
=========================================

You can see a full list of the command-line options supported by configure
using:

./configure --help

First we highlight a few of the more commonly used options, then we show
the options to use for some particular scenarios.

By default, configure will enable building of bindings for all languages
which it can find the required tools for.  Alternatively you can specify
exactly which bindings you want to build by passing one or more of the
following options to configure:

   --with-csharp        enable CSharp bindings
   --with-java          enable Java bindings
   --with-lua           enable Lua bindings
   --with-perl          enable Perl bindings
   --with-php           enable PHP bindings
   --with-python        enable Python 2 bindings
   --with-python3       enable Python 3 bindings
   --with-ruby          enable Ruby bindings
   --with-tcl           enable Tcl bindings

If you've requested particular bindings using these options, then
configure will fail with an error if it is missing the prerequisite
tools, libraries, header files, etc required to build bindings for
any of the requested languages.

The following variables can be specified as environment variables, or on the
configure command line, e.g.:

export CXX=/usr/bin/g++-15
./configure

or:

./configure CXX=/usr/bin/g++-15

  CXX         C++ compiler command
  CXXFLAGS    C++ compiler flags
  LDFLAGS     linker flags, e.g. -L<lib dir> if you have libraries in a
              nonstandard directory <lib dir>
  LIBS        libraries to pass to the linker, e.g. -l<library>
  CPPFLAGS    C/C++ preprocessor flags, e.g. -I<include dir> if you have
              headers in a nonstandard directory <include dir>

By default, xapian-bindings will search `PATH` to find `xapian-config` for
the xapian-core install to use.  If your xapian-core is installed in a
prefix which isn't listed in `PATH`, or if you have multiple xapian-core
versions installed, you can point xapian-binding's `configure` to the
`xapian-config` to use, for example:

./configure XAPIAN_CONFIG=/opt/bin/xapian-config

If you have more than one version of a particular language installed
you can tell `configure` which to build the bindings for by setting
variables on the configure command line.  For a full list of such
variables, see the output of 'configure --help' - for example, for
Python you might use, for example:

./configure PYTHON3=/opt/bin/python3.13

Multi-Arch
----------

When using GCC on platforms which support multiple architectures, the simplest
way to select a non-default architecture is to set `CXX` to include the
appropriate `-m` option - e.g. to build for x86 on x86-64 you would configure
with:

./configure CXX='g++ -m32'

-fvisibility
------------

We automatically pass -fvisibility=hidden to the compiler when building the
bindings when we detect that the compiler supports this option and the platform
supports symbol visibility.

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).

Installing without root access
==============================

By default the bindings for all languages apart from Java and C# will
automatically detect where the language interpreter expects extension modules
to be installed and try to install there.

Java and C# are different because they're compiled languages, and you can build
an application using the bindings by pointing the compiler to the bindings.

For the interpreted languages, this is a problem if you want to install them
and don't have root access.  In this case follow the instructions for the
particular language below (note: you still build bindings for several languages
at once - just merge the lists of additional command line options.)

Note that you also need to pass a "--prefix" option to configure so that
the documentation and examples can be installed.

  Perl:

     ./configure --with-perl --prefix=$HOME/install PERL_LIB=$HOME/my_perl_modules
     make
     make install

     And then you'll need to tell Perl to look for modules in this directory:

     perl -I$HOME/my_perl_modules myscript.pl

  PHP:

     With current releases of PHP, there doesn't seem to be a good way to
     install the PHP bindings without root access such that they can be used
     from PHP run from a webserver, which is what most users want to do.

     If you're only interested in running code from the command line (via PHP's
     CLI SAPI) then the following will work:

     ./configure --with-php --prefix=$HOME/install PHP_EXTENSION_DIR=$HOME/my_php_extensions
     make
     make install

     You can specify the extension directory using `extension_dir` but
     doing so will stop PHP from looking in the default place for extensions!
     So a better approach is to specify the full path to the extension to
     load like so:

     php -d extension="$HOME/my_php_extensions/xapian.so" myscript.php

     A drawback is that this requires the exact filename of the extension which
     varies by platform: not all Unix platforms use `.so` and on Microsoft
     Windows it is `php_xapian.dll`.  PHP 7.2 and later allow `extension=xapian`
     as a portable way to deal with the simple case, but this doesn't work when
     you include a path to the extension.

  Python 2:

     ./configure --with-python --prefix=$HOME/install PYTHON_LIB=$HOME/.local
     make
     make install

     Python 2.6 and later will look in ~/.local for packages automatically
     so the above is all that is required by default.  If you set PYTHON_LIB to
     a different directory, you'll need to tell Python to look for modules in
     that directory.  Here are two possible ways to do that:

     setenv PYTHONPATH=$HOME/mypymods python myscript.py

     Or you can add this to the start of your Python scripts:

     import os
     import sys
     sys.path.insert(0, os.environ['HOME'] + "/mypymods")
     import xapian

  Python 3:

     ./configure --with-python3 --prefix=$HOME/install PYTHON3_LIB=$HOME/.local
     make
     make install

     Python 3 looks in ~/.local for packages automatically, so you don't need
     to do anything special to use bindings installed there.

  Ruby:

     ./configure --with-ruby --prefix=$HOME/install RUBY_LIB=$HOME/my_ruby_modules RUBY_LIB_ARCH=$HOME/my_ruby_modules
     make
     make install

     And then you'll need to tell Ruby to look for modules in this directory:

     ruby -I$HOME/my_ruby_modules myscript.rb

  Tcl8:

     ./configure --with-tcl --prefix=$HOME/install TCL_LIB=$HOME/my_tcl_modules
     make
     make install

     And then add the following to the start of your script to load Xapian:

     load [file join "/home/USERNAME/my_tcl_modules" xapian.so]

Developers
==========

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