xapian-core/INSTALL

   1 Welcome to Xapian
   2 =================
   3
   4 Xapian's build system is built using GNU autoconf, automake, and libtool.
   5 If you've installed other Open Source projects from source, you should
   6 find yourself in familiar territory.  Building and installing involves
   7 the following 3 simple steps:
   8
   9  1) Run "./configure", possibly with some extra arguments (see below)
  10  2) Run "make" to build Xapian
  11  3) Run "make install" to install Xapian
  12
  13 Prerequisites
  14 =============
  15
  16 You'll need to have zlib installed (http://www.zlib.net/) before you can build
  17 Xapian.  The zlib library is very widely used, so you'll probably have it
  18 installed already if you're using Linux, FreeBSD, or similar, but you may need
  19 to install a "zlib development" package to get the zlib library headers.
  20
  21 We recommend using zlib 1.2.x as it apparently fixes a memory leak in
  22 deflateInit2 (which Xapian uses) and decompression is supposed to be about 20%
  23 faster than with 1.1.x, but it's pretty unlikely you'll have an older version
  24 installed these days.
  25
  26 Xapian 1.1.0 and higher also requires a library which can generate UUIDs.
  27 On FreeBSD, NetBSD, and Microsoft Windows, Xapian makes use of built-in UUID
  28 APIs.  On other platforms, you need to install libuuid which you can find in
  29 util-linux-ng (http://userweb.kernel.org/~kzak/util-linux-ng/).  On Debian and
  30 Ubuntu, the package to install is uuid-dev, while on Fedora, it is
  31 libuuid-devel (on older Fedora versions you instead need e2fsprogs-devel).
  32
  33 Compilers
  34 =========
  35
  36 We aim to support compilation with any C++ compiler which conforms to ISO
  37 C++11, or a reasonable approximation to it.
  38
  39 If you're using MS Visual C++, see the Xapian download page for a link to
  40 a set of suitable makefiles: http://xapian.org/download
  41
  42 If you're using GCC, we currently recommend GCC 4.7 or newer (this is the
  43 oldest version we regularly test with).
  44
  45 The current hard minimum requirement is at least GCC 4.4 (due to requiring
  46 C++11 support).
  47
  48 If you really still need to use an older version of GCC, Xapian 1.2.x doesn't
  49 require C++11 support and should build with older versions - probably as far
  50 back as GCC 3.1.
  51
  52 When using HP's aCC, Xapian must be compiled with +std=c++11, which
  53 xapian-core's configure automatically detects and passes.  You don't have to
  54 pass this option when building code which uses Xapian, but you can.
  55
  56 Multi-Arch
  57 ==========
  58
  59 When using GCC on platforms which support multiple architecture, the simplest
  60 way to select a non-default architecture is to pass a CXX setting to configure
  61 which includes the appropriate -m option - e.g. to build for x86 on x86-64
  62 you would configure with:
  63
  64 ./configure CXX='g++ -m32'
  65
  66 Building in a separate directory
  67 ================================
  68
  69 If you wish to perform your build in a separate directory from the source,
  70 create and change to the build directory, and run the configure script (in
  71 the source directory) from the build directory, like so:
  72
  73   mkdir BUILD
  74   cd BUILD
  75   ../configure
  76
  77 Options to give to configure
  78 ============================
  79
  80 --enable-assertions
  81         You should use this to build a version of Xapian with many internal
  82         consistency checks.  This will run more slowly, but is useful if you
  83         suspect a bug in Xapian.
  84
  85 --enable-backend-chert
  86 --enable-backend-glass
  87 --enable-backend-inmemory
  88 --enable-backend-remote
  89         These options enable (or disable if --disable-backend-XXX is specified)
  90         the compiling of each backend (database access methods).  By default,
  91         all backends for which the appropriate libraries and OS support are
  92         available will be enabled.
  93
  94 _FORTIFY_SOURCE
  95 ---------------
  96
  97 When compiling with GCC, by default Xapian will be built with _FORTIFY_SOURCE
  98 set to 2.  This enables some compile time and runtime checking of values passed
  99 to library functions when building with GCC >= 4.1 and glibc >= 2.34 (some
 100 Linux distros may have backported support to older GCC and/or glibc).  If you
 101 wish to disable this for any reason, you can just configure like so:
 102
 103 ./configure CPPFLAGS=-D_FORTIFY_SOURCE=0
 104
 105 Or you can set the "fortification level" to 1 instead of 2:
 106
 107 ./configure CPPFLAGS=-D_FORTIFY_SOURCE=1
 108
 109 If you're disabling it because it causes problems, please also report this to
 110 us (via the bug tracker or mailing lists).
 111
 112 -Bsymbolic-functions
 113 --------------------
 114
 115 When compiling with GCC and using a sufficiently new version of ld, configure
 116 we automatically cause -Wl,-Bsymbolic-functions to be used when linking the
 117 library.  This causes all references from inside the library to symbols inside
 118 the library to be resolved when the library is created, rather than when the
 119 shared library is loaded, which decreases the time taken to load the library,
 120 reduces its size, and is also likely to make the code run a little faster.
 121
 122 Should you wish to disable this for some reason, you can configure like so
 123 which disables the probe for -Bsymbolic-functions so it won't ever be used:
 124
 125 ./configure xo_cv_symbolic_functions=no
 126
 127 If you're disabling it because it causes problems, please also report this to
 128 us (via the bug tracker or mailing lists).
 129
 130 -fvisibility
 131 ------------
 132
 133 When compiling with GCC >= 4.0 for platforms which support symbol visibility,
 134 we automatically pass -fvisibility=hidden to g++ when building the library, and
 135 mark classes, methods, and functions which need exporting with attributes to
 136 make them visible.
 137
 138 Should you wish to disable this for some reason, you can configure like so:
 139
 140 ./configure --disable-visibility
 141
 142 If you're disabling it because it causes problems, please also report this to
 143 us (via the bug tracker or mailing lists).
 144
 145 Developers
 146 ==========
 147
 148 There are additional scripts and configure options to help people doing
 149 development work on Xapian itself, and people who are building from git.
 150 Read HACKING to find out about them.