Update cuvs-lucene build scripts

Author: Igor Motov

.github/workflows/build.yaml

@@ -189,6 +189,32 @@ jobs:
       artifact-name: "cuvs-java-cuda${{ matrix.CUDA_VER }}"
       file_to_upload: "java/cuvs-java/target/"
       sha: ${{ inputs.sha }}
+  lucene-build:
+    # Depends on the Java job for the cuvs-java artifact that cuvs-lucene builds against.
+    needs: [java-build-matrix, java-build]
+    permissions:
+      actions: read
+      contents: read
+      id-token: write
+      packages: read
+      pull-requests: read
+    secrets: inherit # zizmor: ignore[secrets-inherit]
+    uses: rapidsai/shared-workflows/.github/workflows/custom-job.yaml@main
+    # Artifacts are not published from these jobs, so it's safe to run for multiple CUDA versions.
+    # If these jobs start producing artifacts, the names will have to differentiate between CUDA versions.
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJSON(needs.java-build-matrix.outputs.matrix) }}
+    with:
+      build_type: ${{ inputs.build_type || 'branch' }}
+      branch: ${{ inputs.branch }}
+      arch: "amd64"
+      date: ${{ inputs.date }}
+      container_image: "rapidsai/ci-conda:26.10-cuda${{ matrix.CUDA_VER }}-${{ matrix.LINUX_VER }}-py${{ matrix.PY_VER }}"
+      script: "ci/build_lucene.sh cuvs-java-cuda${{ matrix.CUDA_VER }}"
+      artifact-name: "cuvs-lucene-cuda${{ matrix.CUDA_VER }}"
+      file_to_upload: "java/cuvs-lucene/target/"
+      sha: ${{ inputs.sha }}
   python-build:
     needs: [build-details, cpp-build]
     permissions:

.github/workflows/pr.yaml

@@ -26,6 +26,7 @@ jobs:
       - rocky8-clib-tests
       - conda-java-build-and-tests-matrix
       - conda-java-build-and-tests
+      - conda-lucene-build-and-tests
       - rust-build-matrix
       - rust-build
       - go-build-matrix
@@ -143,12 +144,17 @@ jobs:
           - '!README.md'
           - '!SECURITY.md'
           - '!ci/build_docs.sh'
+          - '!ci/build_go.sh'
+          - '!ci/build_java.sh'
+          - '!ci/build_lucene.sh'
           - '!ci/build_python.sh'
+          - '!ci/build_rust.sh'
           - '!ci/build_wheel*.sh'
           - '!ci/check_style.sh'
           - '!ci/release/update-version.sh'
           - '!ci/run_cuvs_pytests.sh'
           - '!ci/test_java.sh'
+          - '!ci/test_lucene.sh'
           - '!ci/test_python.sh'
           - '!ci/test_wheel_cuvs.sh'
           - '!ci/validate_wheel.sh'
@@ -238,12 +244,14 @@ jobs:
           - '!.yamllint.yaml'
           - '!ci/build_go.sh'
           - '!ci/build_java.sh'
+          - '!ci/build_lucene.sh'
           - '!ci/build_rust.sh'
           - '!ci/check_style.sh'
           - '!ci/release/update-version.sh'
           - '!ci/run_ctests.sh'
           - '!ci/test_cpp.sh'
           - '!ci/test_java.sh'
+          - '!ci/test_lucene.sh'
           - '!ci/test_standalone_c.sh'
           - '!ci/test_wheel_cuvs.sh'
           - '!ci/validate_wheel.sh'
@@ -289,6 +297,7 @@ jobs:
           - '!ci/build_docs.sh'
           - '!ci/build_go.sh'
           - '!ci/build_java.sh'
+          - '!ci/build_lucene.sh'
           - '!ci/build_python.sh'
           - '!ci/build_rust.sh'
           - '!ci/build_standalone_c.sh'
@@ -297,6 +306,7 @@ jobs:
           - '!ci/run_ctests.sh'
           - '!ci/test_cpp.sh'
           - '!ci/test_java.sh'
+          - '!ci/test_lucene.sh'
           - '!ci/test_python.sh'
           - '!ci/test_standalone_c.sh'
           - '!ci/validate_wheel.sh'
@@ -346,6 +356,7 @@ jobs:
           - '!ci/build_docs.sh'
           - '!ci/build_go.sh'
           - '!ci/build_java.sh'
+          - '!ci/build_lucene.sh'
           - '!ci/build_python.sh'
           - '!ci/build_wheel*.sh'
           - '!ci/check_style.sh'
@@ -354,6 +365,7 @@ jobs:
           - '!ci/run_cuvs_pytests.sh'
           - '!ci/test_cpp.sh'
           - '!ci/test_java.sh'
+          - '!ci/test_lucene.sh'
           - '!ci/test_python.sh'
           - '!ci/test_wheel_cuvs.sh'
           - '!ci/validate_wheel.sh'
@@ -394,6 +406,7 @@ jobs:
           - '!SECURITY.md'
           - '!ci/build_docs.sh'
           - '!ci/build_java.sh'
+          - '!ci/build_lucene.sh'
           - '!ci/build_python.sh'
           - '!ci/build_rust.sh'
           - '!ci/build_wheel*.sh'
@@ -403,6 +416,7 @@ jobs:
           - '!ci/run_cuvs_pytests.sh'
           - '!ci/test_cpp.sh'
           - '!ci/test_java.sh'
+          - '!ci/test_lucene.sh'
           - '!ci/test_python.sh'
           - '!ci/test_standalone_c.sh'
           - '!ci/test_wheel_cuvs.sh'
@@ -599,6 +613,31 @@ jobs:
       script: "ci/test_java.sh"
       artifact-name: "cuvs-java-cuda${{ matrix.CUDA_VER }}"
       file_to_upload: "java/cuvs-java/target/"
+  conda-lucene-build-and-tests:
+    # Depends on the Java job for the cuvs-java artifact that cuvs-lucene builds against, and
+    # reuses its matrix so the two always agree on the set of CUDA versions.
+    needs: [conda-java-build-and-tests-matrix, conda-java-build-and-tests]
+    permissions:
+      actions: read
+      contents: read
+      id-token: write
+      packages: read
+      pull-requests: read
+    secrets: inherit # zizmor: ignore[secrets-inherit]
+    uses: rapidsai/shared-workflows/.github/workflows/custom-job.yaml@main
+    # Artifacts are not published from these jobs, so it's safe to run for multiple CUDA versions.
+    # If these jobs start producing artifacts, the names will have to differentiate between CUDA versions.
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJSON(needs.conda-java-build-and-tests-matrix.outputs.matrix) }}
+    with:
+      build_type: pull-request
+      node_type: "gpu-l4-latest-1"
+      arch: "amd64"
+      container_image: "rapidsai/ci-conda:26.10-cuda${{ matrix.CUDA_VER }}-${{ matrix.LINUX_VER }}-py${{ matrix.PY_VER }}"
+      script: "ci/test_lucene.sh cuvs-java-cuda${{ matrix.CUDA_VER }}"
+      artifact-name: "cuvs-lucene-cuda${{ matrix.CUDA_VER }}"
+      file_to_upload: "java/cuvs-lucene/target/"
   rust-build-matrix:
     needs: [conda-cpp-build, changed-files]
     permissions:

.github/workflows/test.yaml

@@ -104,6 +104,34 @@ jobs:
       script: "ci/test_java.sh"
       artifact-name: "cuvs-java-cuda${{ matrix.CUDA_VER }}"
       file_to_upload: "java/cuvs-java/target/"
+  conda-lucene-build-and-tests:
+    # Depends on the Java job for the cuvs-java artifact that cuvs-lucene builds against, and
+    # reuses its matrix so the two always agree on the set of CUDA versions.
+    needs: [conda-java-build-and-tests-matrix, conda-java-build-and-tests]
+    permissions:
+      actions: read
+      contents: read
+      id-token: write
+      packages: read
+      pull-requests: read
+    secrets: inherit # zizmor: ignore[secrets-inherit]
+    uses: rapidsai/shared-workflows/.github/workflows/custom-job.yaml@main
+    # Artifacts are not published from these jobs, so it's safe to run for multiple CUDA versions.
+    # If these jobs start producing artifacts, the names will have to differentiate between CUDA versions.
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJSON(needs.conda-java-build-and-tests-matrix.outputs.matrix) }}
+    with:
+      build_type: ${{ inputs.build_type }}
+      branch: ${{ inputs.branch }}
+      date: ${{ inputs.date }}
+      sha: ${{ inputs.sha }}
+      node_type: "gpu-l4-latest-1"
+      arch: "amd64"
+      container_image: "rapidsai/ci-conda:26.10-cuda${{ matrix.CUDA_VER }}-${{ matrix.LINUX_VER }}-py${{ matrix.PY_VER }}"
+      script: "ci/test_lucene.sh cuvs-java-cuda${{ matrix.CUDA_VER }}"
+      artifact-name: "cuvs-lucene-cuda${{ matrix.CUDA_VER }}"
+      file_to_upload: "java/cuvs-lucene/target/"
   wheel-tests-cuvs:
     permissions:
       actions: read

.pre-commit-config.yaml

@@ -97,7 +97,7 @@ repos:
         name: spotless-fmt
         entry: ci/checks/run_spotless.sh
         pass_filenames: false
-        files: ^java/cuvs-java/src/.*\.java$
+        files: ^java/(cuvs-java|cuvs-lucene)/([^/]+/)?src/.*\.java$
         exclude: .*/panama/.*
         language: script
       - id: clang-format-with-cmake-placeholders

build.sh

@@ -19,7 +19,7 @@ ARGS=$*
 # scripts, and that this script resides in the repo dir!
 REPODIR=$(cd "$(dirname "$0")"; pwd)
 
-VALIDARGS="clean libcuvs python rust go java docs tests bench-ann examples --uninstall  -v -g -n --allgpuarch --no-mg --mnmg-tests --no-cpu --cpu-only --no-shared-libs --no-nvtx --show_depr_warn --incl-cache-stats --time -h --run-java-tests"
+VALIDARGS="clean libcuvs python rust go java lucene docs tests bench-ann examples --uninstall  -v -g -n --allgpuarch --no-mg --mnmg-tests --no-cpu --cpu-only --no-shared-libs --no-nvtx --show_depr_warn --incl-cache-stats --time -h --run-java-tests"
 HELP="$0 [<target> ...] [<flag> ...] [--cmake-args=\"<args>\"] [--cache-tool=<tool>] [--limit-tests=<targets>] [--limit-bench-ann=<targets>] [--build-metrics=<filename>]
  where <target> is:
    clean            - remove all existing build artifacts and configuration (start over)
@@ -29,6 +29,7 @@ HELP="$0 [<target> ...] [<flag> ...] [--cmake-args=\"<args>\"] [--cache-tool=<to
    rust             - build the cuvs Rust bindings
    go               - build the cuvs Go bindings
    java             - build the cuvs Java bindings
+   lucene           - build the cuvs-lucene Apache Lucene codecs (requires the Java bindings)
    docs             - build the documentation
    tests            - build the tests
    bench-ann        - build end-to-end ann benchmarks
@@ -74,7 +75,8 @@ FERN_DOCS_DIR=${REPODIR}/fern
 PYTHON_BUILD_DIR=${REPODIR}/python/cuvs/_skbuild
 RUST_BUILD_DIR=${REPODIR}/rust/target
 JAVA_BUILD_DIR=${REPODIR}/java/cuvs-java/target
-BUILD_DIRS="${LIBCUVS_BUILD_DIR} ${PYTHON_BUILD_DIR} ${RUST_BUILD_DIR} ${JAVA_BUILD_DIR}"
+LUCENE_BUILD_DIR=${REPODIR}/java/cuvs-lucene/target
+BUILD_DIRS="${LIBCUVS_BUILD_DIR} ${PYTHON_BUILD_DIR} ${RUST_BUILD_DIR} ${JAVA_BUILD_DIR} ${LUCENE_BUILD_DIR}"
 
 # Set defaults for vars modified by flags to this script
 CMAKE_LOG_LEVEL=""
@@ -555,6 +557,19 @@ if (( NUMARGS == 0 )) || hasArg java; then
     fi
 fi
 
+# Build the cuvs-lucene codecs
+if (( NUMARGS == 0 )) || hasArg lucene; then
+    if ! hasArg java; then
+        echo "Please add 'java' to this script's arguments (ex. './build.sh libcuvs java lucene') if the cuvs Java bindings are not already built"
+    fi
+    cd "${REPODIR}"/java/cuvs-lucene
+    if hasArg --run-java-tests; then
+        ./build.sh --run-java-tests
+    else
+        ./build.sh
+    fi
+fi
+
 RAPIDS_VERSION="$(sed -E -e 's/^([0-9]{2})\.([0-9]{2})\.([0-9]{2}).*$/\1.\2.\3/' "${REPODIR}/VERSION")"
 export RAPIDS_VERSION
 RAPIDS_VERSION_MAJOR_MINOR="$(sed -E -e 's/^([0-9]{2})\.([0-9]{2})\.([0-9]{2}).*$/\1.\2/' "${REPODIR}/VERSION")"

ci/build_lucene.sh

@@ -0,0 +1,98 @@
+#!/bin/bash
+# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+set -euo pipefail
+
+# Takes the name of the cuvs-java artifact uploaded by the Java job, plus an optional
+# --run-java-tests flag.
+# TODO: Remove the flag handling when build and test workflows are separated,
+#       and test_lucene.sh no longer calls build_lucene.sh
+#       ref: https://github.com/rapidsai/cuvs/issues/868
+EXTRA_BUILD_ARGS=()
+CUVS_JAVA_ARTIFACT=""
+for arg in "$@"; do
+  case "${arg}" in
+    --run-java-tests) EXTRA_BUILD_ARGS+=("${arg}") ;;
+    *) CUVS_JAVA_ARTIFACT="${arg}" ;;
+  esac
+done
+
+if [ -z "${CUVS_JAVA_ARTIFACT}" ]; then
+  echo "Error: name of the cuvs-java artifact is missing" >&2
+  exit 1
+fi
+
+if [ -e "/opt/conda/etc/profile.d/conda.sh" ]; then
+  . /opt/conda/etc/profile.d/conda.sh
+fi
+
+rapids-logger "Configuring conda strict channel priority"
+conda config --set channel_priority strict
+
+rapids-logger "Downloading artifacts from previous jobs"
+CPP_CHANNEL=$(rapids-download-from-github "$(rapids-artifact-name conda_cpp libcuvs cuvs --cuda "$RAPIDS_CUDA_VERSION")")
+CUVS_JAVA_DIR=$(rapids-download-from-github "${CUVS_JAVA_ARTIFACT}")
+
+rapids-logger "Generate Java testing dependencies"
+
+ENV_YAML_DIR="$(mktemp -d)"
+
+rapids-dependency-file-generator \
+  --output conda \
+  --file-key java \
+  --prepend-channel "${CPP_CHANNEL}" \
+  --matrix "cuda=${RAPIDS_CUDA_VERSION%.*};arch=$(arch)" | tee "${ENV_YAML_DIR}/env.yaml"
+
+rapids-mamba-retry env create --yes -f "${ENV_YAML_DIR}/env.yaml" -n java
+
+# Temporarily allow unbound variables for conda activation.
+set +u
+conda activate java
+set -u
+
+rapids-print-env
+
+# libcuvs comes from the conda environment here. cuvs-lucene depends on the plain cuvs-java jar,
+# which bundles no native libraries, so the JVM resolves libcuvs_c.so through the dynamic loader
+# and the environment's lib directory has to be on LD_LIBRARY_PATH.
+export LD_LIBRARY_PATH="${CONDA_PREFIX}/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}"
+
+rapids-logger "Install the cuvs-java artifact into the local Maven repository"
+
+# cuvs-lucene resolves cuvs-java from the local Maven repository. Rather than rebuilding the Java
+# bindings here, install the jar built by the Java job. Its pom.xml travels with the artifact and
+# supplies the coordinates, so no version needs to be hardcoded.
+CUVS_JAVA_POM="${CUVS_JAVA_DIR}/pom.xml"
+if [ ! -f "${CUVS_JAVA_POM}" ]; then
+  echo "Could not find pom.xml in the cuvs-java artifact at ${CUVS_JAVA_DIR}" >&2
+  exit 1
+fi
+
+# The artifact also carries the per-architecture native jar and the sources/javadoc/test jars;
+# cuvs-lucene depends on the plain one.
+mapfile -t CUVS_JAVA_JARS < <(find "${CUVS_JAVA_DIR}" -maxdepth 1 -name 'cuvs-java-*.jar' \
+  ! -name '*-sources.jar' ! -name '*-javadoc.jar' ! -name '*-tests.jar' ! -name '*-cuda*.jar')
+if [ "${#CUVS_JAVA_JARS[@]}" -ne 1 ]; then
+  echo "Expected exactly one cuvs-java jar in ${CUVS_JAVA_DIR}, found: ${CUVS_JAVA_JARS[*]:-none}" >&2
+  exit 1
+fi
+
+# Install cuvs jar into .m2, cd is needed to pick up pom.xml in order to avoid rate limit of main maven repo
+pushd java/cuvs-lucene
+mvn --batch-mode install:install-file -Dfile="${CUVS_JAVA_JARS[0]}" -DpomFile="${CUVS_JAVA_POM}"
+popd
+
+EXITCODE=0
+trap "EXITCODE=1" ERR
+set +e
+
+rapids-logger "Run cuvs-lucene build"
+
+RAPIDS_CUDA_MAJOR="${RAPIDS_CUDA_VERSION%%.*}"
+export RAPIDS_CUDA_MAJOR
+
+bash ./build.sh lucene "${EXTRA_BUILD_ARGS[@]}"
+
+rapids-logger "Test script exiting with value: $EXITCODE"
+exit ${EXITCODE}

ci/checks/run_spotless.sh

@@ -2,7 +2,8 @@
 # SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
-# pre-commit hook wrapper that runs 'spotless:apply' to format the Java client sources.
+# pre-commit hook wrapper that runs 'spotless:apply' to format the Java sources of every Maven
+# project under java/.
 #
 # Most cuvs contributors do not work on the Java client and do not have Maven installed. For them
 # (running outside CI without Maven) this skips gracefully, so that 'pre-commit run --all-files'
@@ -20,4 +21,13 @@ if ! command -v mvn >/dev/null 2>&1; then
   exit 0
 fi
 
-exec mvn --batch-mode --quiet -f java/cuvs-java/pom.xml spotless:apply
+POMS=(
+  java/cuvs-java/pom.xml
+  java/cuvs-lucene/pom.xml
+  java/cuvs-lucene/bench/pom.xml
+  java/cuvs-lucene/examples/pom.xml
+)
+
+for pom in "${POMS[@]}"; do
+  mvn --batch-mode --quiet -f "${pom}" spotless:apply
+done

ci/release/update-version.sh

@@ -169,10 +169,17 @@ done
 # Update Java API version
 NEXT_FULL_JAVA_TAG="${NEXT_SHORT_TAG}.${PATCH_PEP440}"
 sed_runner "s/VERSION=\".*\"/VERSION=\"${NEXT_FULL_JAVA_TAG}\"/g" java/build.sh
-for FILE in java/*/pom.xml; do
+sed_runner "s/VERSION=\".*\"/VERSION=\"${NEXT_FULL_JAVA_TAG}\"/g" java/cuvs-lucene/build.sh
+for FILE in java/*/pom.xml java/cuvs-lucene/bench/pom.xml java/cuvs-lucene/examples/pom.xml; do
   sed_runner "/<!--CUVS_JAVA#VERSION_UPDATE_MARKER_START-->.*<!--CUVS_JAVA#VERSION_UPDATE_MARKER_END-->/s//<!--CUVS_JAVA#VERSION_UPDATE_MARKER_START--><version>${NEXT_FULL_JAVA_TAG}<\/version><!--CUVS_JAVA#VERSION_UPDATE_MARKER_END-->/g" "${FILE}"
 done
 
 sed_runner "s| CuVS [[:digit:]]\{2\}\.[[:digit:]]\{2\} | CuVS ${NEXT_SHORT_TAG} |g" java/README.md
 sed_runner "s|-[[:digit:]]\{2\}\.[[:digit:]]\{2\}\.[[:digit:]]\{1,2\}\.jar|-${NEXT_FULL_JAVA_TAG}\.jar|g" java/examples/README.md
 sed_runner "s|/[[:digit:]]\{2\}\.[[:digit:]]\{2\}\.[[:digit:]]\{1,2\}/|/${NEXT_FULL_JAVA_TAG}/|g" java/examples/README.md
+
+# This pattern is deliberately narrow: java/cuvs-lucene/README.md also links to a blog post whose
+# title contains a release number, and that reference must not be rewritten.
+sed_runner "s|<version>[[:digit:]]\{2\}\.[[:digit:]]\{2\}\.[[:digit:]]\{1,2\}</version>|<version>${NEXT_FULL_JAVA_TAG}</version>|g" java/cuvs-lucene/README.md
+
+sed_runner "s|target/examples-[\.0-9]*-jar|target/examples-${NEXT_FULL_JAVA_TAG}-jar|g" java/cuvs-lucene/examples/README.md