Implementation:Vespa engine Vespa Prepare Sh

Overview

This page documents the implementation of the Vespa version preparation scripts: prepare.sh and replace-vespa-version-in-poms.sh. These scripts form the first stage of the Vespa CI/CD build pipeline and are responsible for injecting a release version string into all Maven POM files and creating the artifact directory structure.

Type: External Tool Doc

Code Reference

prepare.sh

#!/usr/bin/env bash
# .buildkite/prepare.sh (L1-21)

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

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

echo "--- Preparing build environment"
echo "Updating Vespa version in POMs to $VESPA_VERSION..."
"$SOURCE_DIR/.buildkite/replace-vespa-version-in-poms.sh" "$VESPA_VERSION" "$SOURCE_DIR"

echo "Creating artifact directories..."
mkdir -p "$WORKDIR/artifacts/$ARCH/rpms"
mkdir -p "$WORKDIR/artifacts/$ARCH/maven-repo"

replace-vespa-version-in-poms.sh

#!/usr/bin/env bash
# .buildkite/replace-vespa-version-in-poms.sh (L1-46)

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

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

if [[ $# -ne 2 ]]; then
    echo "Usage: $(basename "$0") <Vespa version> <path>"
    exit 1
fi

readonly VESPA_VERSION=$1
readonly DIR=$2

# Fail if DIR does not exist or is not a directory
if [[ ! -d "$DIR" ]]; then
    echo "Directory $DIR does not exist or is not a directory."
    exit 1
fi

if [[ -z $(find -L "$DIR" -name "pom.xml") ]]; then
    echo "No pom.xml files found in $DIR"
    exit 0
fi

echo "Updating version strings in POM files..."
if [[ "$(uname)" == "Darwin" ]]; then
    SED_INPLACE=(sed -i '')
else
    SED_INPLACE=(sed -i)
fi

find -L "$DIR" -name "pom.xml" -exec "${SED_INPLACE[@]}" \
     -e "s,<version>.*SNAPSHOT.*</version>,<version>$VESPA_VERSION</version>," \
     -e "s,<vespaversion>.*project.version.*</vespaversion>,<vespaversion>$VESPA_VERSION</vespaversion>," \
     -e "s,<test-framework.version>.*project.version.*</test-framework.version>,<test-framework.version>$VESPA_VERSION</test-framework.version>," \
     {} \;

I/O Contract

Inputs (Environment Variables)

Variable	Required	Description	Example
`VESPA_VERSION`	Yes	Target version string to inject into POM files	`8.432.17`
`SOURCE_DIR`	Yes	Absolute path to the Vespa source checkout root	`/vespa`
`WORKDIR`	Yes	Working directory for build artifacts	`/tmp/vespa-build`
`ARCH`	Yes	CPU architecture identifier	`x86_64` or `aarch64`
`DEBUG`	No	If set to a non-empty value, enables bash xtrace for debugging	`1`

Inputs (Arguments to replace-vespa-version-in-poms.sh)

Position	Description	Example
`$1`	Vespa version string	`8.432.17`
`$2`	Path to directory containing POM files	`/vespa`

Outputs (Files)

Output	Type	Description
Modified `pom.xml` files	In-place file modification	All POM files under `$SOURCE_DIR` have SNAPSHOT versions replaced
`$WORKDIR/artifacts/$ARCH/rpms/`	Directory	Empty directory for RPM artifacts
`$WORKDIR/artifacts/$ARCH/maven-repo/`	Directory	Empty directory for Maven repository artifacts

Key Implementation Details

sed Substitution Patterns

The find ... -exec sed command applies three substitution expressions to each POM file:

Module version replacement: Matches any <version> tag containing the string SNAPSHOT and replaces the entire content with the target version. The regex uses .*SNAPSHOT.* to match version strings like 8.999.1-SNAPSHOT or 8-SNAPSHOT.
Vespa dependency version replacement: Matches <vespaversion> tags that contain Maven property expressions like ${project.version} and replaces them with the literal version string.
Test framework version replacement: Same as above, but for the <test-framework.version> tag used by Vespa's test modules.

All three patterns use commas as the sed delimiter (s,pattern,replacement,) to avoid conflicts with forward slashes in XML tag syntax.

Platform Detection

The script detects macOS vs. Linux to handle the sed -i syntax difference:

if [[ "$(uname)" == "Darwin" ]]; then
    SED_INPLACE=(sed -i '')   # macOS BSD sed requires empty string argument
else
    SED_INPLACE=(sed -i)      # GNU sed on Linux
fi

This allows the script to be used both in CI (Linux) and during local development on macOS.

Symbolic Link Following

The find -L flag follows symbolic links during directory traversal. This is important because the Vespa source tree may contain symlinked modules or directories.

Error Handling

Both scripts use strict Bash error handling:

set -o errexit: Exit immediately if any command fails.
set -o nounset: Treat unset variables as errors.
set -o pipefail: Return the exit code of the first failed command in a pipeline.

The POM replacement script also validates its arguments, checking that exactly two arguments are provided and that the directory exists.

Execution Context

These scripts are invoked by the Buildkite pipeline as the first step of the build process. The typical invocation chain is:

Buildkite Pipeline
  --> .buildkite/prepare.sh
        --> .buildkite/replace-vespa-version-in-poms.sh $VESPA_VERSION $SOURCE_DIR
        --> mkdir -p $WORKDIR/artifacts/$ARCH/rpms
        --> mkdir -p $WORKDIR/artifacts/$ARCH/maven-repo

Source File Locations

.buildkite/prepare.sh (Lines 1-21)
.buildkite/replace-vespa-version-in-poms.sh (Lines 1-46)

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment