Skip to content

Building from Sources

Edit page

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.

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

  • pkg-config
  • Ninja (optional)
  • A C++20 compiler. The CI builds and the Docker image use GCC 13 on Linux, and the Homebrew bottles use Apple Clang on macOS; older compilers are not tested.
  • CMake 3.14 or newer. CMakeLists.txt declares 3.12 as its minimum, but it uses FetchContent_MakeAvailable, which CMake provides from 3.14, and FetchContent is how the libraries are fetched.

Xapiand makes use of quite a few libraries. Its search engine is strata, reached through the prospect search layout, and it and 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.

The external system dependencies you need to provide are:

  • zstd (required)
  • libuuid (required on Linux, uuid-dev or libuuid-devel; macOS and FreeBSD use the system’s UUID functions)
  • OpenSSL 3 (required unless you configure with -DTLS=OFF; TLS is on by default)
  • zlib (used when found)
  • libcap (used when found, Linux only)
  • libpthread (internally used by the Standard C++ thread library)

Asio is header-only and is fetched at configure time, unless you point ASIO_INCLUDE_DIR at an existing copy. On Ubuntu 24.04, the packages the Dockerfile builds with are g++-13 cmake ninja-build pkg-config libasio-dev libzstd-dev uuid-dev zlib1g-dev libcap-dev libssl-dev.


To install the requirements under macOS you need:

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:

Terminal window
# Install the command line developer tools:
xcode-select --install
Terminal window
brew install ninja
brew install pkg-config
brew install cmake
brew install openssl@3
brew install zstd

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

Terminal window
git clone -b master --single-branch --depth 1 \
"https://github.com/Kronuz/Xapiand.git"
Terminal window
cd Xapiand
mkdir build
cd build
Terminal window
cmake -GNinja -DBUILD_TESTS=ON ..

BUILD_TESTS is only needed to run the unit tests (ninja check, below).

Terminal window
ninja
ninja check # needs the BUILD_TESTS=ON configure above
ninja install

The binary is bin/xapiand in the build directory. The scripts in harness/ run the node end to end: harness/run_all.sh smoke e2e starts a node from build/bin/xapiand and runs a smoke test and every request example of this documentation against it (the e2e layer needs newman 6 or newer on the PATH).


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

OptionDefaultDescription
CMAKE_BUILD_TYPEReleaseBuild type (Release, RelWithDebInfo, Debug, …)
LTOONLink-Time Optimization
TLSONHTTPS for the REST API (--tls-cert, --tls-key); needs OpenSSL 3
LUAONThe Lua scripting engine (_script)
DATABASE_WALONDatabase write-ahead log (WAL)
DATA_STORAGEONData storage volumes
UUID_ENCODEDONAllow the encoded (base59) UUID representation (--uuid)
UUID_GUIDOFFAllow the GUID UUID representation (--uuid)
UUID_URNOFFAllow the URN UUID representation (--uuid)
TRACEBACKSOFF (ON in Debug)Tracebacks in exceptions
ASSERTSOFF (ON in Debug)Runtime assertions
TRACKED_MEMOFFAllocator that attributes memory to call sites
BUILD_TESTSOFFBuild the test suite, and the check target that runs it
ASANOFFAddressSanitizer (see Sanitizers)
UBSANOFFUndefinedBehaviorSanitizer
MSANOFFMemorySanitizer
TSANOFFThreadSanitizer
DEBUGINFO_EXTERNALIZEOFFExternalize debug information (macOS)

These options are for development and testing, and most users never set them:

OptionDefaultDescription
FUZZOFFBuild the libFuzzer targets (needs a clang with libFuzzer)
CRASH_POINTSOFFLet XAPIAND_STRATA_CRASH=point:n kill the process at a strata commit or replay point, for crash tests
ENGINE_CENSUSOFFCount the facilities each request uses at the engine seam (XAPIAND_ENGINE_CENSUS=file)
RANDOM_ERRORSOFFAdd the --random-errors-net, --random-errors-io and --random-errors-db options, which inject random errors
CHECK_IO_FDESOFFCheck file descriptors
CHECK_SIZESOFFPrint the objects sizes

For example, a debug build with tracebacks and assertions:

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

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

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:

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

UndefinedBehavior Sanitizer (ASAN + UBSAN)

Section titled “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:

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

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

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

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

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

  • 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.