Building from Sources
Edit pageTo 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
Section titled “Requirements”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.txtdeclares 3.12 as its minimum, but it usesFetchContent_MakeAvailable, which CMake provides from 3.14, andFetchContentis how the libraries are fetched.
Dependencies
Section titled “Dependencies”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-devorlibuuid-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:
1. Configure Xcode
Section titled “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 --install3. Install Requirements
Section titled “3. Install Requirements”brew install ninjabrew install pkg-configbrew install cmakebrew install openssl@3brew install zstdBuilding process
Section titled “Building process”Get the Sources
Section titled “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
Section titled “Prepare the Build”cd Xapiandmkdir buildcd buildConfigure the Build
Section titled “Configure the Build”cmake -GNinja -DBUILD_TESTS=ON ..BUILD_TESTS is only needed to run the unit tests (ninja check, below).
Build, Test and Install
Section titled “Build, Test and Install”ninjaninja check # needs the BUILD_TESTS=ON configure aboveninja installThe 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).
Build Options
Section titled “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
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 |
TLS | ON | HTTPS for the REST API (--tls-cert, --tls-key); needs OpenSSL 3 |
LUA | ON | The Lua scripting engine (_script) |
DATABASE_WAL | ON | Database write-ahead log (WAL) |
DATA_STORAGE | ON | Data storage volumes |
UUID_ENCODED | ON | Allow the encoded (base59) UUID representation (--uuid) |
UUID_GUID | OFF | Allow the GUID UUID representation (--uuid) |
UUID_URN | OFF | Allow the URN UUID representation (--uuid) |
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, and the check target that runs it |
ASAN | OFF | AddressSanitizer (see Sanitizers) |
UBSAN | OFF | UndefinedBehaviorSanitizer |
MSAN | OFF | MemorySanitizer |
TSAN | OFF | ThreadSanitizer |
DEBUGINFO_EXTERNALIZE | OFF | Externalize debug information (macOS) |
These options are for development and testing, and most users never set them:
| Option | Default | Description |
|---|---|---|
FUZZ | OFF | Build the libFuzzer targets (needs a clang with libFuzzer) |
CRASH_POINTS | OFF | Let XAPIAND_STRATA_CRASH=point:n kill the process at a strata commit or replay point, for crash tests |
ENGINE_CENSUS | OFF | Count the facilities each request uses at the engine seam (XAPIAND_ENGINE_CENSUS=file) |
RANDOM_ERRORS | OFF | Add the --random-errors-net, --random-errors-io and --random-errors-db options, which inject random errors |
CHECK_IO_FDES | OFF | Check file descriptors |
CHECK_SIZES | OFF | Print the objects sizes |
For example, a debug build with tracebacks and assertions:
cmake -GNinja -DCMAKE_BUILD_TYPE=Debug -DTRACEBACKS=ON -DASSERTS=ON ..Sanitizers
Section titled “Sanitizers”When building sanitized versions of Xapiand, you’ll need to Configure the Build using the proper library:
Address Sanitizer (ASAN)
Section titled “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)
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:
cmake -GNinja -DCMAKE_BUILD_TYPE=RelWithDebInfo -DTRACEBACKS=ON -DASSERTS=ON -DASAN=ON -DUBSAN=ON ..Memory Sanitizer (MSAN)
Section titled “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)
Section titled “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
Section titled “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.