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 (https://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, OpenBSD,
  27 AIX and Microsoft Windows, Xapian makes use of built-in UUID APIs.  On Linux
  28 and 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 (https://github.com/karelzak/util-linux).  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.7 or newer (this is the
  44 oldest version we regularly test with).
  45
  46 The current hard minimum requirement is also GCC 4.7 (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.2.x doesn't
  51 require C++11 support and should build with older versions - probably as far
  52 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 We support 64-bit compilation with MSVS 2017, 2019 and 2022.  With MSVS 2015 a
  61 64-bit build fails to work - we haven't investigated why.
  62
  63 As of Xapian 1.4.6 building using MSVC is supported by the autotools build
  64 system.  You need to install a set of Unix-like tools first - we recommended
  65 MSYS2: https://www.msys2.org/
  66
  67 You also need to have the MSVC command line tools on your PATH.  This is done
  68 by running a batch file in the MSVC install in the terminal before building.
  69 The exact details vary by MSVC version, 32- vs 64-bit, and the directory and
  70 drive where MSVC is installed.  For MSVC 2017 it should be something like::
  71
  72   "C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvars32.bat"
  73
  74 or::
  75
  76   "C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvars64.bat"
  77
  78 And for MSVC 2015 32-bit use::
  79
  80   "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" x86
  81
  82 MSVC 2015 64-bit isn't currently supported, but would use the above command but
  83 with ``x64`` instead of ``x86``.
  84
  85 You'll need to have the zlib library available.  You can add
  86 ``CPPFLAGS=-I/path/to/zlib LDFLAGS=-L/path/to/zlib`` to the configure command
  87 line to tell MSVC where to find the zlib headers and library.
  88
  89 To build, first run configure from a bash shell like so::
  90
  91   ./configure CC="cl -nologo" CXX="$PWD/compile cl -nologo" CXXFLAGS=-EHsc AR=lib
  92
  93 Then build using GNU make::
  94
  95   make
  96
  97 HP's aCC
  98 --------
  99
 100 When using HP's aCC, Xapian must be compiled with +std=c++11, which
 101 xapian-core's configure automatically detects and passes.  You don't have to
 102 pass this option when building code which uses Xapian, but you can.
 103
 104 Sun C++ Compiler
 105 ----------------
 106
 107 With this compiler, shared library builds fail (tested most recently with
 108 version 12.6).  You can work around this problem by disabling shared libraries
 109 at configure time like so::
 110
 111   ./configure --disable-shared
 112
 113 Multi-Arch
 114 ==========
 115
 116 When using GCC on platforms which support multiple architectures, the simplest
 117 way to select a non-default architecture is to pass a CXX setting to configure
 118 which includes the appropriate -m option - e.g. to build for x86 on x86-64
 119 you would configure with:
 120
 121 ./configure CXX='g++ -m32'
 122
 123 Building in a separate directory
 124 ================================
 125
 126 If you wish to perform your build in a separate directory from the source,
 127 create and change to the build directory, and run the configure script (in
 128 the source directory) from the build directory, like so:
 129
 130   mkdir BUILD
 131   cd BUILD
 132   ../configure
 133
 134 Options to give to configure
 135 ============================
 136
 137 --enable-assertions
 138         You should use this to build a version of Xapian with many internal
 139         consistency checks.  This will run more slowly, but is useful if you
 140         suspect a bug in Xapian.
 141
 142 --enable-backend-chert
 143 --enable-backend-glass
 144 --enable-backend-inmemory
 145 --enable-backend-remote
 146         These options enable (or disable if --disable-backend-XXX is specified)
 147         the compiling of each backend (database access methods).  By default,
 148         all backends for which the appropriate libraries and OS support are
 149         available will be enabled.  Note: Currently disabling the remote
 150         backend also disables replication (because the network code is shared).
 151
 152 _FORTIFY_SOURCE
 153 ---------------
 154
 155 When compiling with GCC, by default Xapian will be built with _FORTIFY_SOURCE
 156 set to 2 (except on mingw-w64).  This enables some compile time and runtime
 157 checking of values passed to library functions when building with glibc >=
 158 2.34.  If you wish to disable this for any reason, you can just configure like
 159 so:
 160
 161 ./configure CPPFLAGS=-D_FORTIFY_SOURCE=0
 162
 163 Or you can set the "fortification level" to 1 instead of 2:
 164
 165 ./configure CPPFLAGS=-D_FORTIFY_SOURCE=1
 166
 167 If you're disabling it because it causes problems, please also report this to
 168 us (via the bug tracker or mailing lists).
 169
 170 On mingw-w64 Xapian doesn't automatically enable _FORTIFY_SOURCE as an extra
 171 library is needed.  You can enable it by hand and specify this library like
 172 so:
 173
 174 ./configure CPPFLAGS=-D_FORTIFY_SOURCE=2 LIBS=-lssp
 175
 176 -Bsymbolic-functions
 177 --------------------
 178
 179 If -Wl,-Bsymbolic-functions is supported (for example it is by GCC with modern
 180 ld) then it will be automatically used when linking the library.  This causes
 181 all references from inside the library to symbols inside the library to be
 182 resolved when the library is created, rather than when the shared library is
 183 loaded, which decreases the time taken to load the library, reduces its size,
 184 and is also likely to make the code run a little faster.
 185
 186 Should you wish to disable this for some reason, you can configure like so
 187 which disables the probe for -Bsymbolic-functions so it won't ever be used:
 188
 189 ./configure xo_cv_symbolic_functions=no
 190
 191 If you're disabling it because it causes problems, please also report this to
 192 us (via the bug tracker or mailing lists).
 193
 194 -fvisibility
 195 ------------
 196
 197 When compiling with GCC >= 4.0 for platforms which support symbol visibility,
 198 we automatically pass -fvisibility=hidden to g++ when building the library, and
 199 mark classes, methods, and functions which need exporting with attributes to
 200 make them visible.
 201
 202 Should you wish to disable this for some reason, you can configure like so:
 203
 204 ./configure --disable-visibility
 205
 206 If you're disabling it because it causes problems, please also report this to
 207 us (via the bug tracker or mailing lists).
 208
 209 Developers
 210 ==========
 211
 212 There are additional scripts and configure options to help people doing
 213 development work on Xapian itself, and people who are building from git.
 214 Read HACKING to find out about them.