Environment:Ray project Ray Java Build Environment

Knowledge Sources	Ray build-jar-multiplatform.sh
Domains	Infrastructure, Distributed_Computing
Last Updated	2026-02-13 16:35 GMT

Overview

Java 8 build and runtime environment with Bazel 6.5.0, Maven, and platform-specific native library support for Linux and macOS.

Description

This environment provides the Java build toolchain for the Ray Java API, runtime, and Serve modules. It strictly requires JDK 8 (1.8) and uses Maven for dependency management with Bazel for native code compilation. Native shared libraries are packaged for Linux and Darwin (macOS) only; Windows is not supported for Java native binaries. The build produces multiplatform JAR files containing platform-specific native code extracted at runtime using a file-lock-based mechanism.

Usage

Use this environment for building Ray Java JARs, running Java-based Ray applications (tasks, actors, Serve deployments), or developing cross-language Java-Python-C++ integrations. It is the mandatory prerequisite for the Build and Release Pipeline Java JAR building step and all Java Serve deployments.

System Requirements

Category	Requirement	Notes
OS	Linux or macOS	Windows NOT supported for native libraries
Java	JDK 8 (1.8) exactly	Build script rejects all other versions
Build Tool	Bazel 6.5.0 (exact)	For native C++ code compilation
Build Tool	Maven 3.x	For Java dependency management and JAR packaging
Build Tool	Python (any)	Used by build helper scripts (gen_pom_files.py, etc.)

Dependencies

System Packages

`jdk8` (Java Development Kit 1.8)
`bazel` = 6.5.0
`maven` >= 3.x
`python` (for build scripts)

Java Dependencies (managed by Maven POM)

`com.google.guava:guava`
`com.google.protobuf:protobuf-java`
`org.apache.commons:commons-lang3`
`commons-io:commons-io`
`org.msgpack:msgpack-core` (for cross-language serialization)
`de.ruedigermoeller:fst` (for Java object serialization)
`org.testng:testng` (for testing)
`org.slf4j:slf4j-api` (for logging)

Credentials

No runtime credentials are required. Build environment variables:

`JAVA_HOME`: Must point to a JDK 8 installation
`RAY_INSTALL_JAVA`: Set to "1" to enable Java build in the Python setup process

Quick Install

# Verify Java 8 is installed
java -version  # Must show 1.8.x

# Build Java JARs for current platform
cd java && mvn clean install -DskipTests

# Build multiplatform JARs (requires Bazel)
bash java/build-jar-multiplatform.sh

Code Evidence

Java version enforcement from `java/build-jar-multiplatform.sh:19-26`:

check_java_version() {
  local VERSION
  VERSION=$(java  -version 2>&1 | awk -F '"' '/version/ {print $2}')
  if [[ ! $VERSION =~ 1.8 ]]; then
    echo "Java version is $VERSION. Please install jdk8."
    exit 1
  fi
}

Platform-specific native library extraction from `BinaryFileUtil.java:40-46`:

if (SystemUtils.IS_OS_MAC) {
    resourceDir = "native/darwin/";
} else if (SystemUtils.IS_OS_LINUX) {
    resourceDir = "native/linux/";
} else {
    throw new UnsupportedOperationException("Unsupported os " + SystemUtils.OS_NAME);
}

File-lock safety for concurrent native extraction from `BinaryFileUtil.java:38`:

try (FileLock ignored = new RandomAccessFile(lockFilePath, "rw").getChannel().lock()) {

Common Errors

Error Message	Cause	Solution
`Java version is X. Please install jdk8.`	Non-Java-8 JDK installed	Install JDK 8 and set JAVA_HOME accordingly
`UnsupportedOperationException: Unsupported os`	Running on Windows	Java native libraries only support Linux and macOS
`Couldn't rename temp file`	File permission or concurrent extraction race	Check file permissions in native library extraction directory
Native library crash during extraction (issue #19341)	Worker crashed mid-extraction	Fixed by temp-file-then-rename pattern; restart the worker

Compatibility Notes

Windows: Not supported for Java native libraries. The `BinaryFileUtil` explicitly throws `UnsupportedOperationException` on non-Linux/macOS platforms.
macOS: On non-Linux platforms, the node IP defaults to localhost to avoid security popups (see `RayConfig.java:120-129`).
JDK version: Strictly enforced to 1.8. Higher JDK versions (11, 17, 21) are explicitly rejected by the build script.
Multi-node Java tests: Not currently supported; only single-node tests are available.

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment