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 C++,
  37 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.1 or newer (this is the
  43 oldest version we regularly test with).
  44
  45 The minimum required GCC version is 3.1 (2.95.2 and earlier don't have
  46 the <sstream> header; 3.0 adds support for the <limits> header and has
  47 <streambuf> as well as <streambuf.h>, but widespread adoption of GCC3
  48 didn't happen until after 3.0, and 3.1 was released on 2002-05-15 so
  49 we now require this as it eliminates some preprocessor conditionals which we
  50 aren't able to test regularly as we don't have easy access to such old GCC
  51 versions).  If you really still need to use an older version of GCC, Xapian
  52 1.0.x should build with GCC 2.95.3 or GCC 3.0.x.
  53
  54 When using HP's aCC, Xapian must be compiled with -AA ("ANSI mode"), which
  55 xapian-core's configure automatically detects and passes.  This means your code
  56 must also be compiled with -AA (and "xapian-config --cxxflags" will include
  57 "-AA" automatically in this situation).  Compiling with -AP (non-ANSI mode)
  58 would require adjusting Xapian away from standard ISO C++, and is only required
  59 if you need to link to Xapian and another library not available in -AA form.
  60 HP recommend ISVs to supply libraries in -AA form, so this isn't a likely
  61 scenario.
  62
  63 When building on IRIX with SGI's compiler, Omega has to be built with "-ptused"
  64 in CXXFLAGS (this is now added automatically by Omega's configure).  You may
  65 need to do the same when building your own applications.  We don't fully
  66 understand the issues here yet, but perhaps "-ptused" should be automatically
  67 set by xapian-config.  Feedback from developers on IRIX is invited.
  68
  69 Multi-Arch
  70 ==========
  71
  72 When using GCC on platforms which support multiple architecture, the simplest
  73 way to select a non-default architecture is to pass a CXX setting to configure
  74 which includes the appropriate -m option - e.g. to build for x86 on x86-64
  75 you would configure with:
  76
  77 ./configure CXX='g++ -m32'
  78
  79 Building in a separate directory
  80 ================================
  81
  82 If you wish to perform your build in a separate directory from the source,
  83 create and change to the build directory, and run the configure script (in
  84 the source directory) from the build directory, like so:
  85
  86   mkdir BUILD
  87   cd BUILD
  88   ../configure
  89
  90 IRIX make doesn't handle this correctly - either build in the source tree or
  91 use "smake -M" (or better still, just use GNU make if you have it installed!)
  92
  93 Options to give to configure
  94 ============================
  95
  96 --enable-assertions
  97         You should use this to build a version of Xapian with many internal
  98         consistency checks.  This will run more slowly, but is useful if you
  99         suspect a bug in Xapian.
 100
 101 --enable-backend-brass
 102 --enable-backend-chert
 103 --enable-backend-flint
 104 --enable-backend-inmemory
 105 --enable-backend-remote
 106         These options enable (or disable if --disable-backend-XXX is specified)
 107         the compiling of each backend (database access methods).  By default,
 108         all backends for which the appropriate libraries and OS support are
 109         available will be enabled.
 110
 111 _FORTIFY_SOURCE
 112 ---------------
 113
 114 When compiling with GCC, by default Xapian will be built with _FORTIFY_SOURCE
 115 set to 2.  This enables some compile time and runtime checking of values passed
 116 to library functions when building with GCC >= 4.1 and glibc >= 2.34 (some
 117 Linux distros may have backported support to older GCC and/or glibc).  If you
 118 wish to disable this for any reason, you can just configure like so:
 119
 120 ./configure CPPFLAGS=-D_FORTIFY_SOURCE=0
 121
 122 Or you can set the "fortification level" to 1 instead of 2:
 123
 124 ./configure CPPFLAGS=-D_FORTIFY_SOURCE=1
 125
 126 If you're disabling it because it causes problems, please also report this to
 127 us (via the bug tracker or mailing lists).
 128
 129 -Bsymbolic-functions
 130 --------------------
 131
 132 When compiling with GCC and using a sufficiently new version of ld, configure
 133 we automatically cause -Wl,-Bsymbolic-functions to be used when linking the
 134 library.  This causes all references from inside the library to symbols inside
 135 the library to be resolved when the library is created, rather than when the
 136 shared library is loaded, which decreases the time taken to load the library,
 137 reduces its size, and is also likely to make the code run a little faster.
 138
 139 Should you wish to disable this for some reason, you can configure like so
 140 which disables the probe for -Bsymbolic-functions so it won't ever be used:
 141
 142 ./configure xo_cv_symbolic_functions=no
 143
 144 If you're disabling it because it causes problems, please also report this to
 145 us (via the bug tracker or mailing lists).
 146
 147 -fvisibility
 148 ------------
 149
 150 When compiling with GCC >= 4.0 for platforms which support symbol visibility,
 151 we automatically pass -fvisibility=hidden to g++ when building the library, and
 152 mark classes, methods, and functions which need exporting with attributes to
 153 make them visible.
 154
 155 Should you wish to disable this for some reason, you can configure like so:
 156
 157 ./configure --disable-visibility
 158
 159 If you're disabling it because it causes problems, please also report this to
 160 us (via the bug tracker or mailing lists).
 161
 162 Compiling with STLport
 163 ======================
 164
 165 C++ implementations have improved significantly since we started writing
 166 Xapian, and these days the STL which comes with your compiler should work well.
 167
 168 But if you wish, you can use STLport instead.  STLport is a freely available
 169 replacement C++ STL implementation, downloadable from:
 170
 171 http://stlport.sourceforge.net/
 172
 173 To compile with STLport:
 174
 175  1) Install STLport, either from a package if your operating system has one,
 176     or by downloading the source, and compiling and installing it.
 177
 178  2) Tell Xapian to use STLport when you configure in, like so:
 179
 180     ./configure CXXFLAGS='-I/usr/include/stlport -pthread' LDFLAGS=-lstlport
 181
 182     Replace /usr/include/stlport with the path to the STLport headers if they
 183     are in a different location.
 184
 185  3) Compile Xapian as normal, by running make.
 186
 187  4) You'll also need to compile code which uses Xapian with STLport, by
 188     arranging for the options above to be passed to the compiler when you
 189     compile and link that code.
 190
 191 Note that, unless you compile statically, you must make sure that the
 192 STLport library is on the library path at runtime.  If it isn't by
 193 default, on Linux you could do this by setting the LD_LIBRARY_PATH environment
 194 variable to point to the directory containing the STLport library.
 195
 196 Developers
 197 ==========
 198
 199 There are additional scripts and configure options to help people doing
 200 development work on Xapian itself, and people who are building from git.
 201 Read HACKING to find out about them.