Building from Sources

To build from the sources, first you’ll need to fork and clone the repository from GitHub. Once you have a local copy, proceed with the building process.

Requirements

Xapiand is written in C++20 and it has the following build requirements:

• pkg-config
• Ninja (optional)
• A C++20 compiler: Clang >= 14 (Apple Clang >= 14) or GCC >= 13
• CMake >= 3.14 (FetchContent is used heavily)
• perl >= 5.6 (for a few building scripts)
• Tcl >= 8.6 (to generate unicode/unicode-data.cc)

---

Dependencies

Xapiand makes use of quite a few libraries. Its search engine is a vendored fork of Xapian 2.0.0, built as part of the tree, and most of the remaining building blocks (MessagePack, the storage codecs, logging, the Asio-based reactor runtime, the Lua scripting engine via sol2, and more) are pulled in automatically at configure time through CMake’s FetchContent from the standalone Kronuz libraries, so a network connection is required the first time you configure. (Earlier releases embedded ChaiScript and a libev event loop; those are now Lua and the Asio reactor.)

The Xapian fork is compiled automatically as part of the Xapiand build, so you don’t need to build or install it yourself. If you want to compile the search library standalone (for example, to work on the search core in isolation), see Building the Xapian Library.

The only external system dependencies you need to provide are:

• zlib
• libpthread (internally used by the Standard C++ thread library)
• ICU >= 54.1 (optional)

---

macOS

To install the requirements under macOS you need:

1. Configure Xcode

Simply installing Xcode will not install all of the command line developer tools, the first time you must execute the following in Terminal, before trying to build:

# Install the command line developer tools:
xcode-select --install

2. Install Homebrew

3. Install Requirements

brew install ninja
brew install pkg-config
brew install cmake
brew install icu

---

Building process

Get the Sources

First download and untar the Xapiand official distribution or clone the repository from https://github.com/Kronuz/Xapiand.git

git clone -b master --single-branch --depth 1 \
  "https://github.com/Kronuz/Xapiand.git"

Prepare the Build

cd Xapiand
mkdir build
cd build

Configure the Build

cmake -GNinja ..

The default build type is an optimized Release with Link-Time Optimization (LTO) enabled (the LTO option defaults on). The first configure downloads the fetched dependencies (see Dependencies), which can take a few minutes; subsequent configures reuse them.

Build, Test and Install

ninja
ninja check
ninja install

CPU Usage

When compiling using ninja, the whole machine could slow down while compiling, as ninja, by default, uses all available CPU cores; you can prevent this by telling ninja to use <number of cores> - 1 jobs. Example, for a system with 4 CPU cores: ninja -j3.

---

Build Options

The build is configured with CMake options, toggled at configure time with -D<OPTION>=ON / -D<OPTION>=OFF. The defaults produce an optimized, clustered release; you rarely need to change them for a normal build.

Option	Default	Description
CMAKE_BUILD_TYPE	Release	Build type (Release, RelWithDebInfo, Debug, …)
LTO	ON	Link-Time Optimization
CLUSTERING	ON	Remote clustering
DATABASE_WAL	ON	Database write-ahead log (WAL)
DATA_STORAGE	ON	Data storage volumes
TRACEBACKS	OFF (ON in Debug)	Tracebacks in exceptions
ASSERTS	OFF (ON in Debug)	Runtime assertions
TRACKED_MEM	OFF	Allocator that attributes memory to call sites
BUILD_TESTS	OFF	Build the test suite
ASAN	OFF	AddressSanitizer (see Sanitizers)
UBSAN	OFF	UndefinedBehaviorSanitizer
MSAN	OFF	MemorySanitizer
TSAN	OFF	ThreadSanitizer

For example, a debug build with tracebacks and assertions:

cmake -GNinja -DCMAKE_BUILD_TYPE=Debug -DTRACEBACKS=ON -DASSERTS=ON ..

---

Sanitizers

When building sanitized versions of Xapiand, you’ll need to Configure the Build using the proper library:

On macOS, build the sanitized binaries with Homebrew’s LLVM, not Apple Clang.

Recent Apple Clang toolchains ship an Address/Thread Sanitizer runtime that can hang on startup on Apple silicon. Install it with brew install llvm and point the build at it, for example CC=/opt/homebrew/opt/llvm/bin/clang CXX=/opt/homebrew/opt/llvm/bin/clang++ cmake -GNinja -DASAN=ON .., then run the resulting binary with DYLD_LIBRARY_PATH=/opt/homebrew/opt/llvm/lib.

Address Sanitizer (ASAN)

For developing and debugging, generally you’d want to enable the Address Sanitizer, tracebacks in exceptions and debugging symbols, so you’ll have to Configure the Build using something like:

cmake -GNinja -DCMAKE_BUILD_TYPE=RelWithDebInfo -DTRACEBACKS=ON -DASSERTS=ON -DASAN=ON ..

UndefinedBehavior Sanitizer (ASAN + UBSAN)

For developing and debugging, generally you’d want to enable the Address Sanitizer and UndefinedBehavior Sanitizer, tracebacks in exceptions and debugging symbols, so you’ll have to Configure the Build using something like:

cmake -GNinja -DCMAKE_BUILD_TYPE=RelWithDebInfo -DTRACEBACKS=ON -DASSERTS=ON -DASAN=ON -DUBSAN=ON ..

Memory Sanitizer (MSAN)

For debugging memory issues, enable Memory Sanitizer and debugging symbols in release mode, so you’ll have to Configure the Build using something like:

cmake -GNinja -DCMAKE_BUILD_TYPE=RelWithDebInfo -DTRACEBACKS=ON -DASSERTS=ON -DMSAN=ON ..

Thread Sanitizer (TSAN)

For debugging multithread issues, enable Thread Sanitizer and debugging symbols in release mode, so you’ll have to Configure the Build using something like:

cmake -GNinja -DCMAKE_BUILD_TYPE=RelWithDebInfo -DTRACEBACKS=ON -DASSERTS=ON -DTSAN=ON ..

---

See Also

• Architecture Overview — the layers and how a request flows through them.
• Dependencies — every fetched library, with links and a transitive tree.
• Internals — source layout, conventions, and load-bearing invariants.
• Building the Xapian Library — compiling the search core standalone.