Implementation:Vespa engine Vespa Bootstrap Cmake Sh

Overview

This page documents the implementation of the Vespa CMake configuration script: .buildkite/bootstrap-cmake.sh. This script sets up the build environment, resolves sanitizer and ccache options, and invokes CMake to generate Makefiles for the C++ build.

Type: External Tool Doc

Code Reference

#!/usr/bin/env bash
# .buildkite/bootstrap-cmake.sh (L1-35)

set -o errexit
set -o nounset
set -o pipefail

if [[ -n "${DEBUG:-}" ]]; then
    set -o xtrace
fi

echo "--- Configuring CMake build"
# shellcheck disable=1091
source /etc/profile.d/enable-gcc-toolset.sh

PATH=/opt/vespa-deps/bin:$PATH

VESPA_CMAKE_SANITIZERS_OPTION=""
VESPA_CMAKE_CCACHE_OPTION=""
if [[ $VESPA_USE_SANITIZER != null ]]; then
    echo "Enabling sanitizer: $VESPA_USE_SANITIZER"
    VESPA_CMAKE_SANITIZERS_OPTION="-DVESPA_USE_SANITIZER=$VESPA_USE_SANITIZER"
    VESPA_CMAKE_CCACHE_OPTION="-DVESPA_USE_CCACHE=false"
    VALGRIND_UNIT_TESTS=false
fi
if [[ $BUILDKITE_PULL_REQUEST != "false" ]]; then
    VALGRIND_UNIT_TESTS=false
fi

echo "Running CMake configuration..."
cmake -DVESPA_UNPRIVILEGED=no -DVALGRIND_UNIT_TESTS="$VALGRIND_UNIT_TESTS" \
  "$VESPA_CMAKE_SANITIZERS_OPTION" "$VESPA_CMAKE_CCACHE_OPTION" "$SOURCE_DIR"

I/O Contract

Inputs (Environment Variables)

Variable	Required	Description	Example
`VESPA_USE_SANITIZER`	Yes	Sanitizer type to enable, or `null` for none	`address`, `thread`, or `null`
`BUILDKITE_PULL_REQUEST`	Yes	PR number or `"false"` if this is not a PR build	`35801` or `false`
`VALGRIND_UNIT_TESTS`	Yes	Initial setting for Valgrind test enablement	`true` or `false`
`SOURCE_DIR`	Yes	Absolute path to the Vespa source checkout	`/vespa`
`DEBUG`	No	If set to a non-empty value, enables bash xtrace	`1`

Inputs (System Dependencies)

Dependency	Path	Purpose
GCC Toolset	`/etc/profile.d/enable-gcc-toolset.sh`	Activates the GCC 12+ compiler suite
Vespa Dependencies	`/opt/vespa-deps/bin`	Pre-built libraries (protobuf, abseil, gRPC, etc.)
CMake	System PATH (after deps setup)	Build system generator

Outputs (Files)

Output	Type	Description
`Makefile`	Generated file	Top-level Makefile for the C++ build
`CMakeCache.txt`	Generated file	Cache of all resolved CMake variables
Subdirectory Makefiles	Generated files	Per-module Makefiles for each CMakeLists.txt
Generated headers	Generated files	Platform-specific config headers (e.g., `config.h`)

Key Implementation Details

Sanitizer Option Resolution

The script determines sanitizer and ccache options through conditional logic:

VESPA_CMAKE_SANITIZERS_OPTION=""
VESPA_CMAKE_CCACHE_OPTION=""
if [[ $VESPA_USE_SANITIZER != null ]]; then
    VESPA_CMAKE_SANITIZERS_OPTION="-DVESPA_USE_SANITIZER=$VESPA_USE_SANITIZER"
    VESPA_CMAKE_CCACHE_OPTION="-DVESPA_USE_CCACHE=false"
    VALGRIND_UNIT_TESTS=false
fi

When a sanitizer is active:

The corresponding CMake variable is set (e.g., -DVESPA_USE_SANITIZER=address).
Ccache is explicitly disabled to prevent cache poisoning with sanitizer-instrumented object files.
Valgrind is disabled because sanitizers already provide memory error detection.

Pull Request Optimization

For pull request builds, Valgrind unit tests are unconditionally disabled:

if [[ $BUILDKITE_PULL_REQUEST != "false" ]]; then
    VALGRIND_UNIT_TESTS=false
fi

This reduces PR build times significantly since Valgrind adds 10-50x overhead to test execution. Full Valgrind testing is reserved for post-merge builds on the main branch.

CMake Variable Passing

The variables $VESPA_CMAKE_SANITIZERS_OPTION and $VESPA_CMAKE_CCACHE_OPTION are passed as unquoted arguments to CMake. When they are empty strings, Bash word splitting causes them to be omitted entirely, which is the desired behavior -- CMake receives no sanitizer or ccache flags when they are not configured.

GCC Toolset and Dependency Path

The script sets up the compilation environment before invoking CMake:

source /etc/profile.d/enable-gcc-toolset.sh
PATH=/opt/vespa-deps/bin:$PATH

This ensures that:

CMake detects the correct C++ compiler (GCC 12+ with C++20 support).
find_package() calls in CMakeLists.txt files can locate pre-built Vespa dependency libraries under /opt/vespa-deps/.

VESPA_UNPRIVILEGED Flag

The -DVESPA_UNPRIVILEGED=no flag tells CMake that the build targets a privileged (root) installation. This affects installation paths, file permissions, and systemd service configurations in the generated build system.

Execution Context

This script is invoked from the Buildkite pipeline after the Java bootstrap has completed. It runs in the build directory (not the source directory), creating an out-of-source build:

Buildkite Pipeline
  --> .buildkite/bootstrap.sh (Java bootstrap)
  --> cd $BUILD_DIR
  --> .buildkite/bootstrap-cmake.sh
        --> source enable-gcc-toolset.sh
        --> cmake ... $SOURCE_DIR
  --> .buildkite/cpp.sh (uses generated Makefiles)

Source File Locations

.buildkite/bootstrap-cmake.sh (Lines 1-35)

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment