xapian-core/docs/install.rst

   1 Installing Xapian
   2 =================
   3
   4 Introduction
   5 ------------
   6
   7 This document is intended to give a quick guide to how to install
   8 Xapian. You can find more detailed instructions in the ``INSTALL`` file
   9 which is in top level directory of each source tree.
  10
  11 Xapian can be built on UNIX systems (including MacOS X), and also
  12 Microsoft Windows systems using GCC with mingw or cygwin, or MSVC.
  13
  14 Packaged binary versions
  15 ------------------------
  16
  17 Pre-built Xapian packages are available for a number of platforms,
  18 including most of the popular Linux distributions and BSD variants, and
  19 also Cygwin and MSVC. If you are using such a platform, you'll probably
  20 find it easiest to use pre-built packages - it saves having to compile
  21 by hand and you'll generally get updates automatically.
  22
  23 There are some links on our `download
  24 page <https://xapian.org/download>`_ but it's likely that Xapian packages
  25 are available for platforms we aren't aware of. Feel free to let us know
  26 and we'll add a link.
  27
  28 In some cases, the version packaged may be rather old, in which case you
  29 can either request the packager to update, or build from source. If you
  30 find we're linking to a package which isn't being updated, please let us
  31 know so we can remove the link.
  32
  33 Installing from Source
  34 ----------------------
  35
  36 Download
  37 ~~~~~~~~
  38
  39 The first step is to obtain a copy of the software from the `Xapian
  40 download page <https://xapian.org/download>`_.
  41
  42 Unpacking
  43 ~~~~~~~~~
  44
  45 Use the usual tools to unpack the archives. For example, on a Linux
  46 system::
  47
  48      tar xf xapian-core-<versionnumber>.tar.xz
  49      tar xf xapian-omega-<versionnumber>.tar.xz
  50      tar xf xapian-bindings-<versionnumber>.tar.xz
  51
  52 If tar on your system doesn't support xz decompression, you can instead use::
  53
  54      xz -dc xapian-core-<versionnumber>.tar.xz|tar xf -
  55      xz -dc xapian-omega-<versionnumber>.tar.xz|tar xf -
  56      xz -dc xapian-bindings-<versionnumber>.tar.xz|tar xf -
  57
  58 These commands should unpack the archives into separate subdirectories
  59 (``xapian-core-<versionnumber>``, ``xapian-omega-<versionnumber>`` and
  60 ``xapian-bindings-<versionnumber>``).
  61
  62 Configuring and building the Xapian library
  63 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  64
  65 For full details of the different options available when configuring and
  66 building, read the file "INSTALL" in the top level directory of your
  67 newly unpacked source tree. But in many cases, the following quick
  68 summary is all you need to know.
  69
  70 Each directory contains a ``configure`` script which checks various
  71 features of your system. Assuming this runs successfully, you can then
  72 run ``make`` to build the software, and ``make install`` to actually
  73 install it. By default, the software installs under ``/usr/local``, but
  74 you can change this by passing ``--prefix=/path/to/install`` to
  75 ``configure``. So for example, you might use the following series of
  76 commands to build and install xapian-core under ``/opt``::
  77
  78      cd xapian-core-<version>
  79      ./configure --prefix=/opt
  80      make
  81      sudo make install
  82
  83 If you don't have root access to install Xapian, you can specify a
  84 prefix in your home directory, for example::
  85
  86      ./configure --prefix=/home/jenny/xapian-install
  87
  88 Configuring and building Omega
  89 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  90
  91 Omega can be built in almost exactly the same way as the core library.
  92 Omega's ``configure`` script will try to locate your Xapian installation
  93 by looking for the ``xapian-config`` script, which is installed as
  94 ``<prefix>/bin/xapian-config``. If ``<prefix>/bin/xapian-config`` isn't
  95 on your ``PATH``, or you have multiple installations of Xapian (perhaps
  96 a debug and non-debug build, or two different versions), you can specify
  97 a ``xapian-config`` to use by passing ``XAPIAN_CONFIG`` on the configure
  98 command line, as shown below::
  99
 100      cd xapian-omega-<version>
 101      ./configure --prefix=/opt XAPIAN_CONFIG=/opt/bin/xapian-config
 102      make
 103      sudo make install
 104
 105 Note that we use GNU libtool, which will set the runtime library search
 106 path if your Xapian installation isn't in the dynamic linker search
 107 path, so there's no need to mess around with setting
 108 ``LD_LIBRARY_PATH``.
 109
 110 Configuring and building Xapian-bindings
 111 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 112
 113 Xapian-bindings is built much like Omega. One thing to be aware of is
 114 that by default we install the built bindings where they need to go to
 115 work without further intervention, so they may get installed under
 116 ``/usr`` even if the prefix is elsewhere. See the ``INSTALL`` file for
 117 xapian-bindings for details of how you can override this, and what steps
 118 you'll need to take to run scripts which use the bindings if you do.
 119
 120 Building from git
 121 ~~~~~~~~~~~~~~~~~
 122
 123 If you wish to help develop Xapian, read `how to build from the Xapian
 124 git repository <https://xapian.org/bleeding>`_.