Environment:Vespa engine Vespa Java 17 Build Runtime

Knowledge Sources	Vespa Engine parent/pom.xml
Domains	Infrastructure, Build_System
Last Updated	2026-02-09 00:00 GMT

Overview

Linux build environment with Java 17 (primary), Maven 3.9.12, and multi-JDK support for Java 21 and 25.

Description

This environment provides the Java build context for the Vespa search engine. The primary compile target is Java 17 (set in parent/pom.xml line 92), with additional Maven profiles for Java 21 (jdk21 profile, activation range [21,22)) and Java 25 (ffm-native profile with Foreign Function & Memory support). Vespa client libraries target Java 11 as baseline. Maven 3.9.12 is used via the Maven wrapper, with batch-mode and no-snapshot-updates for reproducible builds.

Usage

Use this environment for all Java compilation, Maven builds, and bootstrap operations. It is the mandatory prerequisite for running the Bootstrap_And_Java_Sh and Prepare_Sh implementations. The Java build must complete before C++ builds can proceed, as C++ tests depend on JAR artifacts produced during bootstrap.

System Requirements

Category	Requirement	Notes
OS	Linux (AlmaLinux 8 or 9)	x86_64 or aarch64 architectures
Hardware	Multi-core CPU	Maven uses 2/3 of cores for parallel builds
Memory	1GB minimum + 1GB per Maven thread	MAVEN_OPTS: -Xms1g -Xmx$(NUM_MVN_THREADS)g
Disk	20GB+ SSD	Maven local repo, JAR artifacts, build outputs

Dependencies

System Packages

Java 17 JDK (primary compile target)
Java 21 JDK (optional, for jdk21 Maven profile)
Java 25 JDK (optional, for ffm-native Maven profile)
Maven 3.9.12 (installed via Maven wrapper)

Build Tool Configuration

Compiler release target: 17 (default)
Compiler warnings as errors: -Werror
Xlint options enabled (excluding serial, try, processing)
Preview features enabled via ${vespaCompilerArgs.preview}
Vespa client libraries target: Java 11

Credentials

The following environment variables must be set for full CI builds:

VESPA_MAVEN_COMMAND: Maven executable path (default: $(pwd)/mvnw)
VESPA_MAVEN_EXTRA_OPTS: Additional Maven options (default: --show-version --batch-mode --no-snapshot-updates)
VESPA_MAVEN_TARGET: Maven target (default: install, or deploy for main branch)
MAVEN_OPTS: JVM heap settings (default: -Xms1g -Xmx$(NUM_MVN_THREADS)g)
LOCAL_MVN_REPO: Path to local Maven repository

Quick Install

# Java 17 is required; install via your package manager
# Maven wrapper is auto-configured during bootstrap:
./bootstrap.sh

# For manual Maven wrapper setup only:
./bootstrap.sh wrapper

Code Evidence

Java version configuration from parent/pom.xml:89-103:

<release>17</release>
<compilerArgs>
  <arg>-Werror</arg>
  <arg>-Xlint:all</arg>
  <arg>-Xlint:-serial</arg>
  <arg>-Xlint:-try</arg>
  <arg>-Xlint:-processing</arg>
  ${vespaCompilerArgs.preview}
</compilerArgs>

Maven version from bootstrap.sh:64:

mvn_install -N -Dmaven=3.9.12 -pl :maven-wrapper

Thread allocation from .buildkite/Makefile:

export NUM_CPU_LIMIT ?= $(shell nproc)
export NUM_MVN_THREADS := $(shell echo $$(( $(NUM_CPU_LIMIT)*2/3 )))
export MAVEN_OPTS ?= -Xms1g -Xmx$(NUM_MVN_THREADS)g

Common Errors

Error Message	Cause	Solution
`release version 17 not supported`	JDK older than 17	Install JDK 17 or later
`OutOfMemoryError: Java heap space`	Insufficient Maven heap	Increase `MAVEN_OPTS` max heap (e.g., `-Xmx8g`)
`mvnw: command not found`	Maven wrapper not set up	Run `./bootstrap.sh wrapper` first

Compatibility Notes

Java 21: Activated via Maven profile jdk21 (JDK range [21,22)). Compiler release target switches to 21.
Java 25: Activated via Maven profile ffm-native (JDK range [25,26)). Enables Foreign Function & Memory support.
Client Libraries: Built with Java 11 baseline (vespaClients.jdk.releaseVersion=11).
PR Builds: Source and javadoc JAR generation is skipped for faster builds.

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment