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 also requires a way to generate UUIDs.  On FreeBSD, NetBSD, and
  27 Microsoft Windows, Xapian makes use of built-in UUID APIs.  On Linux and
  28 Android, Xapian 1.4.2 and higher can read UUIDs from a special file under
  29 /proc.  Otherwise you need to install libuuid which you can find in
  30 util-linux-ng (http://userweb.kernel.org/~kzak/util-linux-ng/).  On Debian and
  31 Ubuntu, the package to install is uuid-dev, while on Fedora, it is
  32 libuuid-devel (on older Fedora versions you instead need e2fsprogs-devel).
  33
  34 Compilers
  35 =========
  36
  37 We aim to support compilation with any C++ compiler which support ISO C++11, or
  38 a reasonable approximation to it.
  39
  40 GCC
  41 ---
  42
  43 If you're using GCC, we currently recommend GCC 4.8 or newer (this is the
  44 oldest version we regularly test with).
  45
  46 The current hard minimum requirement is also GCC 4.8 (due to requiring good
  47 support for C++11, for example non-static data member initializers aren't
  48 supported by earlier versions).
  49
  50 If you really still need to use an older version of GCC, Xapian 1.4.x aims
  51 to support GCC 4.7, while Xapian 1.2.x doesn't require C++11 support and should
  52 build with older versions - probably as far back as GCC 3.1.
  53
  54 MSVC
  55 ----
  56
  57 If you're using MS Visual C++, you'll need at least MSVS 2015 for C++11
  58 support.
  59
  60 As of Xapian 1.4.6 building using MSVC is supported by the autotools build
  61 system.  You need to install a set of Unix-like tools first - we recommended
  62 MSYS2: https://www.msys2.org/
  63
  64 Then from a bash shell run configure like so::
  65
  66   ./configure CC="cl -nologo" CXX="$PWD/compile cl -nologo" CXXFLAGS=-EHsc AR=lib
  67
  68 You'll need to have the zlib library available.  You can also specify
  69 ``CPPFLAGS=-I/path/to/zlib LDFLAGS=-L/path/to/zlib`` to tell MSVC where to
  70 find the zlib headers and library.
  71
  72 We support 64-bit compilation with MSVS 2017.  With MSVS 2015 a 64-bit build
  73 fails to work - we haven't investigated why.
  74
  75 HP's aCC
  76 --------
  77
  78 When using HP's aCC, Xapian must be compiled with +std=c++11, which
  79 xapian-core's configure automatically detects and passes.  You don't have to
  80 pass this option when building code which uses Xapian, but you can.
  81
  82 Multi-Arch
  83 ==========
  84
  85 When using GCC on platforms which support multiple architecture, the simplest
  86 way to select a non-default architecture is to pass a CXX setting to configure
  87 which includes the appropriate -m option - e.g. to build for x86 on x86-64
  88 you would configure with:
  89
  90 ./configure CXX='g++ -m32'
  91
  92 Building in a separate directory
  93 ================================
  94
  95 If you wish to perform your build in a separate directory from the source,
  96 create and change to the build directory, and run the configure script (in
  97 the source directory) from the build directory, like so:
  98
  99   mkdir BUILD
 100   cd BUILD
 101   ../configure
 102
 103 Options to give to configure
 104 ============================
 105
 106 --enable-assertions
 107         You should use this to build a version of Xapian with many internal
 108         consistency checks.  This will run more slowly, but is useful if you
 109         suspect a bug in Xapian.
 110
 111 --enable-backend-glass
 112 --enable-backend-honey
 113 --enable-backend-inmemory
 114 --enable-backend-remote
 115         These options enable (or disable if --disable-backend-XXX is specified)
 116         the compiling of each backend (database access methods).  By default,
 117         all backends for which the appropriate libraries and OS support are
 118         available will be enabled.  Note: Currently disabling the remote
 119         backend also disables replication (because the network code is shared).
 120
 121 _FORTIFY_SOURCE
 122 ---------------
 123
 124 When compiling with GCC, by default Xapian will be built with _FORTIFY_SOURCE
 125 set to 2.  This enables some compile time and runtime checking of values passed
 126 to library functions when building with GCC >= 4.1 and glibc >= 2.34 (some
 127 Linux distros may have backported support to older GCC and/or glibc).  If you
 128 wish to disable this for any reason, you can just configure like so:
 129
 130 ./configure CPPFLAGS=-D_FORTIFY_SOURCE=0
 131
 132 Or you can set the "fortification level" to 1 instead of 2:
 133
 134 ./configure CPPFLAGS=-D_FORTIFY_SOURCE=1
 135
 136 If you're disabling it because it causes problems, please also report this to
 137 us (via the bug tracker or mailing lists).
 138
 139 -Bsymbolic-functions
 140 --------------------
 141
 142 If -Wl,-Bsymbolic-functions is supported (for example it is by GCC with modern
 143 ld) then it will be automatically used when linking the library.  This causes
 144 all references from inside the library to symbols inside the library to be
 145 resolved when the library is created, rather than when the shared library is
 146 loaded, which decreases the time taken to load the library, reduces its size,
 147 and is also likely to make the code run a little faster.
 148
 149 Should you wish to disable this for some reason, you can configure like so
 150 which disables the probe for -Bsymbolic-functions so it won't ever be used:
 151
 152 ./configure xo_cv_symbolic_functions=no
 153
 154 If you're disabling it because it causes problems, please also report this to
 155 us (via the bug tracker or mailing lists).
 156
 157 -fvisibility
 158 ------------
 159
 160 When compiling with GCC >= 4.0 for platforms which support symbol visibility,
 161 we automatically pass -fvisibility=hidden to g++ when building the library, and
 162 mark classes, methods, and functions which need exporting with attributes to
 163 make them visible.
 164
 165 Should you wish to disable this for some reason, you can configure like so:
 166
 167 ./configure --disable-visibility
 168
 169 If you're disabling it because it causes problems, please also report this to
 170 us (via the bug tracker or mailing lists).
 171
 172 Developers
 173 ==========
 174
 175 There are additional scripts and configure options to help people doing
 176 development work on Xapian itself, and people who are building from git.
 177 Read HACKING to find out about them.