Environment:Vespa engine Vespa CMake Cpp23 Build Environment

Knowledge Sources	Vespa Engine CMakeLists.txt cxx_settings.cmake
Domains	Infrastructure, Build_System
Last Updated	2026-02-09 00:00 GMT

Overview

Linux C++23 build environment with CMake 3.20+, GCC 5.3+ (optimized for GCC 13+), and architecture-specific tuning for x86_64 and aarch64.

Description

This environment provides the C++ compilation context for the Vespa search engine. The build system uses CMake 3.20 minimum, targets the C++23 standard, and compiles with -O3 optimization. Architecture-specific tuning targets Haswell/Skylake-AVX512 on x86_64 and ARMv8.2-a with Neoverse N1 on aarch64. The build uses ccache by default for faster rebuilds and supports optional sanitizers (address, thread, undefined behavior).

Usage

Use this environment for all C++ compilation, CMake configuration, and C++ testing operations. It is the mandatory prerequisite for running the Bootstrap_Cmake_Sh, Cpp_Sh, and Build_Rpms_Sh implementations.

System Requirements

Category	Requirement	Notes
OS	Linux (AlmaLinux 8 or 9)	x86_64 or aarch64
Hardware	Multi-core CPU	C++ build uses 2/3 of cores; install/test uses all cores
Memory	8GB+ RAM	Large C++ compilation; more for link-time with LTO
Disk	30GB+ SSD	Object files, shared libraries, test binaries
Dependencies Prefix	`/opt/vespa-deps`	Pre-built third-party libraries (LLVM, Protobuf, GTest)

Dependencies

System Packages

CMake >= 3.20
GCC >= 5.3.0 (optimized for GCC 13+; GCC toolset from /etc/profile.d/enable-gcc-toolset.sh)
LLVM (required, detected via CMake)
GTest (required for unit tests)
Protobuf (required)
liburing (optional, auto-detected)
ccache (optional, enabled by default)

Compiler Flags

-g -O3 -fno-omit-frame-pointer -fPIC -DXXH_INLINE_ALL -DBOOST_DISABLE_ASSERTS
x86_64: -march=haswell -mtune=skylake-avx512
aarch64: -march=armv8.2-a+fp16+dotprod+crypto -mtune=neoverse-n1

Credentials

The following environment variables control the build:

VESPA_USE_SANITIZER: Sanitizer type (address, thread, undefined, or combined)
VESPA_USE_LTO: Enable Link-Time Optimization (disabled by default)
NUM_CPP_THREADS: Number of compilation threads (default: 2/3 of nproc)
VALGRIND_UNIT_TESTS: Run tests under Valgrind (default: false)
VESPA_CPP_TEST_JARS: Directory for Java test JARs needed by C++ tests

Quick Install

# Source GCC toolset if available
source /etc/profile.d/enable-gcc-toolset.sh 2>/dev/null || true

# Configure CMake
cmake -DVESPA_UNPRIVILEGED=no \
  -DVALGRIND_UNIT_TESTS=false \
  "$SOURCE_DIR"

# Build with 2/3 of available cores
make -j "$(( $(nproc) * 2 / 3 ))"

Code Evidence

CMake version requirement from CMakeLists.txt:5:

cmake_minimum_required(VERSION 3.20 FATAL_ERROR)

C++ standard from cxx_settings.cmake:

set(CMAKE_CXX_STANDARD 23)

Compiler flags from cxx_settings.cmake:

set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -g -O3 -fno-omit-frame-pointer -fPIC -DXXH_INLINE_ALL -DBOOST_DISABLE_ASSERTS")

GCC minimum version from functions.cmake:504:

if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU" AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS 5.3.0)
    message(FATAL_ERROR "GCC version must be at least 5.3.0")
endif()

ccache integration from build_settings.cmake:

set(VESPA_USE_CCACHE TRUE CACHE BOOL "If TRUE, use ccache (if available)")
if (VESPA_USE_CCACHE)
    find_program(CCACHE_EXECUTABLE ccache)
    if(CCACHE_EXECUTABLE)
        set_property(GLOBAL PROPERTY RULE_LAUNCH_COMPILE ${CCACHE_EXECUTABLE})
        set_property(GLOBAL PROPERTY RULE_LAUNCH_LINK ${CCACHE_EXECUTABLE})
    endif()
endif()

Common Errors

Error Message	Cause	Solution
`CMake version must be at least 3.20`	Old CMake	Install CMake 3.20+
`GCC version must be at least 5.3.0`	Old GCC	Source `/etc/profile.d/enable-gcc-toolset.sh`
`Could not find LLVM`	LLVM not installed	Install LLVM to `/opt/vespa-deps`

Compatibility Notes

GCC 13+: Special warning handling for dangling references, overloaded virtual, stringop issues.
GCC 14+: Additional warning suppression for newer diagnostics.
Clang 17+: Requires -fno-assume-unique-vtables.
Clang 18+: ABI compatibility flag -fclang-abi-compat=17.
Sanitizers: Disable ccache when sanitizers are enabled (incompatible).
LTO: Disabled by default; can be enabled via -DVESPA_USE_LTO=TRUE.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment