Portable standalone tarball build with Docker

.devcontainer/cuda12.9-conda/devcontainer.json

@@ -8,7 +8,7 @@
       "BASE": "rapidsai/devcontainers:26.10-cpp-mambaforge"
     },
     "cacheFrom": [
-      "ghcr.io/rapidsai/cuvs/devcontainer:26.08-cuda12.9-conda"
+      "ghcr.io/rapidsai/cuvs/devcontainer:26.10-cuda12.9-conda"
     ]
   },
   "runArgs": [

.devcontainer/cuda12.9-pip/devcontainer.json

@@ -8,7 +8,7 @@
       "BASE": "rapidsai/devcontainers:26.10-cpp-cuda12.9-ucx1.19.0-openmpi5.0.10"
     },
     "cacheFrom": [
-      "ghcr.io/rapidsai/cuvs/devcontainer:26.08-cuda12.9-pip"
+      "ghcr.io/rapidsai/cuvs/devcontainer:26.10-cuda12.9-pip"
     ]
   },
   "runArgs": [

.devcontainer/cuda13.3-conda/devcontainer.json

@@ -8,7 +8,7 @@
       "BASE": "rapidsai/devcontainers:26.10-cpp-mambaforge"
     },
     "cacheFrom": [
-      "ghcr.io/rapidsai/cuvs/devcontainer:26.08-cuda13.3-conda"
+      "ghcr.io/rapidsai/cuvs/devcontainer:26.10-cuda13.3-conda"
     ]
   },
   "runArgs": [

.devcontainer/cuda13.3-pip/devcontainer.json

@@ -8,7 +8,7 @@
       "BASE": "rapidsai/devcontainers:26.10-cpp-cuda13.3-ucx1.19.0-openmpi5.0.10"
     },
     "cacheFrom": [
-      "ghcr.io/rapidsai/cuvs/devcontainer:26.08-cuda13.3-pip"
+      "ghcr.io/rapidsai/cuvs/devcontainer:26.10-cuda13.3-pip"
     ]
   },
   "runArgs": [

.github/workflows/build.yaml

@@ -65,30 +65,61 @@ jobs:
       matrix_name: conda-cpp-build
   rocky8-clib-standalone-build:
     needs: [build-details, rocky8-clib-standalone-build-matrix]
+    runs-on: linux-${{ matrix.ARCH }}-cpu16
+    env:
+      RAPIDS_ARTIFACTS_DIR: ${{ github.workspace }}/artifacts
+      RAPIDS_BUILD_TYPE: ${{ inputs.build_type || 'branch' }}
+      RAPIDS_DATETIME_STRING: ${{ needs.build-details.outputs.build-datetime }}
     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
     strategy:
       fail-fast: false
       matrix: ${{ fromJSON(needs.rocky8-clib-standalone-build-matrix.outputs.matrix) }}
-    with:
-      build_type: ${{ inputs.build_type || 'branch' }}
-      build-datetime: ${{ needs.build-details.outputs.build-datetime }}
-      branch: ${{ inputs.branch }}
-      arch: "${{matrix.ARCH}}"
-      date: ${{ inputs.date }}
-      container_image: "rapidsai/ci-wheel:26.10-cuda${{ matrix.CUDA_VER }}-${{ matrix.LINUX_VER }}-py${{ matrix.PY_VER }}"
-      node_type: "cpu16"
-      requires_license_builder: true
-      script: "ci/build_standalone_c.sh"
-      artifact-name: "libcuvs_c_${{ matrix.CUDA_VER }}_${{ matrix.ARCH }}.tar.gz"
-      file_to_upload: "libcuvs_c.tar.gz"
-      sha: ${{ inputs.sha }}
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          ref: ${{ inputs.sha || github.sha }}
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Standardize repository information
+        uses: rapidsai/shared-actions/rapids-github-info@main
+        with:
+          branch: ${{ inputs.branch }}
+          date: ${{ inputs.date }}
+          sha: ${{ inputs.sha }}
+      - uses: aws-actions/configure-aws-credentials@7474bc4690e29a8392af63c5b98e7449536d5c3a # v4
+        with:
+          role-to-assume: ${{ vars.AWS_ROLE_ARN }}
+          aws-region: ${{ vars.AWS_REGION }}
+          role-duration-seconds: 43200
+      - name: Setup sccache-dist
+        uses: rapidsai/shared-actions/setup-sccache-dist@main
+        with:
+          log-file: ${{ env.RAPIDS_ARTIFACTS_DIR }}/sccache.log
+          request-timeout: 7140
+      - name: Get RAPIDS License Builder
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          repository: rapidsai/spdx-license-builder
+          ref: refs/heads/main
+          path: ./tool/
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Build and run standalone C Docker image
+        env:
+          CUDA_VERSION: ${{ matrix.CUDA_VER }}
+          PYTHON_VERSION: ${{ matrix.PY_VER }}
+          RAPIDS_AUX_SECRET_1: ${{ secrets.GIST_REPO_READ_ORG_GITHUB_TOKEN }}
+        run: ci/run_standalone_c_docker.sh
+      - name: Upload file to GitHub Artifact
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: libcuvs_c_${{ matrix.CUDA_VER }}_${{ matrix.ARCH }}.tar.gz
+          path: libcuvs_c.tar.gz
   rust-build-matrix:
     needs: cpp-build
     permissions:

.github/workflows/pr.yaml

@@ -512,30 +512,54 @@ jobs:
       build_type: pull-request
       matrix_name: conda-cpp-build
   rocky8-clib-standalone-build:
-    needs: [build-details, rocky8-clib-standalone-build-matrix]
+    needs: rocky8-clib-standalone-build-matrix
+    runs-on: linux-${{ matrix.ARCH }}-cpu16
+    env:
+      RAPIDS_ARTIFACTS_DIR: ${{ github.workspace }}/artifacts
     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
     strategy:
       fail-fast: false
       matrix: ${{ fromJSON(needs.rocky8-clib-standalone-build-matrix.outputs.matrix) }}
-    with:
-      build_type: pull-request
-      build-datetime: ${{ needs.build-details.outputs.build-datetime }}
-      arch: "${{matrix.arch}}"
-      date: ${{ inputs.date }}_c
-      container_image: "rapidsai/ci-wheel:26.10-cuda${{ matrix.CUDA_VER }}-${{ matrix.LINUX_VER }}-py${{ matrix.PY_VER }}"
-      node_type: "cpu16"
-      requires_license_builder: true
-      script: "ci/build_standalone_c.sh --build-tests"
-      artifact-name: "libcuvs_c_${{ matrix.CUDA_VER }}_${{ matrix.ARCH }}.tar.gz"
-      file_to_upload: "libcuvs_c.tar.gz"
-      sha: ${{ inputs.sha }}
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          ref: ${{ inputs.sha || github.sha }}
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: aws-actions/configure-aws-credentials@7474bc4690e29a8392af63c5b98e7449536d5c3a # v4
+        with:
+          role-to-assume: ${{ vars.AWS_ROLE_ARN }}
+          aws-region: ${{ vars.AWS_REGION }}
+          role-duration-seconds: 43200
+      - name: Setup sccache-dist
+        uses: rapidsai/shared-actions/setup-sccache-dist@main
+        with:
+          log-file: ${{ env.RAPIDS_ARTIFACTS_DIR }}/sccache.log
+          request-timeout: 7140
+      - name: Get RAPIDS License Builder
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          repository: rapidsai/spdx-license-builder
+          ref: refs/heads/main
+          path: ./tool/
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Build and run standalone C Docker image
+        env:
+          CUDA_VERSION: ${{ matrix.CUDA_VER }}
+          PYTHON_VERSION: ${{ matrix.PY_VER }}
+          RAPIDS_AUX_SECRET_1: ${{ secrets.GIST_REPO_READ_ORG_GITHUB_TOKEN }}
+        run: ci/run_standalone_c_docker.sh --tarball-build-tests
+      - name: Upload file to GitHub Artifact
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: libcuvs_c_${{ matrix.CUDA_VER }}_${{ matrix.ARCH }}.tar.gz
+          path: libcuvs_c.tar.gz
   rocky8-clib-tests-matrix:
     needs: [rocky8-clib-standalone-build, changed-files]
     permissions:

Dockerfile.standalone

@@ -0,0 +1,57 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Environment and runner for the standalone C build (see ci/standalone_c/build_standalone_c.sh).
+# Build args: CUDA_VERSION (default 13.0), PYTHON_VERSION (default 3.11).
+#
+# End-user instructions: https://docs.nvidia.com/cuvs/installation#build-the-standalone-c-library-with-docker
+# Quick run: docker run -v $(pwd):/workspace -v $(pwd)/build:/build <image> [--tarball-build-tests]
+
+ARG CUDA_VERSION=13.0
+ARG PYTHON_VERSION=3.11
+FROM rapidsai/ci-wheel:26.10-cuda${CUDA_VERSION}-rockylinux8-py${PYTHON_VERSION}
+
+ARG NINJA_VERSION=v1.13.1
+
+# System packages required by ci/standalone_c/build_standalone_c.sh
+RUN dnf install -y \
+    patch \
+    tar \
+    unzip \
+    wget \
+    && dnf clean all
+
+# Install ninja (architecture-aware)
+RUN set -euo pipefail; \
+    if ! command -V ninja >/dev/null 2>&1; then \
+        case "$(uname -m)" in \
+            x86_64) \
+                wget --no-hsts -q -O /tmp/ninja-linux.zip "https://github.com/ninja-build/ninja/releases/download/${NINJA_VERSION}/ninja-linux.zip"; \
+                ;; \
+            aarch64) \
+                wget --no-hsts -q -O /tmp/ninja-linux.zip "https://github.com/ninja-build/ninja/releases/download/${NINJA_VERSION}/ninja-linux-aarch64.zip"; \
+                ;; \
+            *) \
+                echo "Unrecognized platform '$(uname -m)'" >&2; exit 1; \
+                ;; \
+        esac; \
+        unzip -d /usr/bin /tmp/ninja-linux.zip; \
+        chmod +x /usr/bin/ninja; \
+        rm /tmp/ninja-linux.zip; \
+    fi
+
+# CMake; sccache/date are configured at runtime by ci/standalone_c/build_standalone_c.sh
+RUN rapids-pip-retry install cmake \
+    && pyenv rehash
+
+# Output directory for the standalone archive. Bind-mount a host folder here
+# (e.g. -v $(pwd)/build:/build) so libcuvs_c.tar.gz is written to the host.
+ENV BUILD_OUTPUT_DIR=/build
+ENV CUVS_TARBALL_IN_CONTAINER=1
+
+# Run from repo root; the repo is expected to be bind-mounted at /workspace.
+WORKDIR /workspace
+
+# Run the build script, which writes the standalone tarball to the mounted output dir.
+# Example: docker run -v $(pwd):/workspace -v $(pwd)/build:/build <image> [--tarball-build-tests]
+ENTRYPOINT ["/bin/bash", "-c", "ci/standalone_c/build_standalone_c.sh \"$@\"", "--"]

README.md

@@ -84,6 +84,10 @@ cuVS comes with pre-built packages that can be installed through [conda](https:/
 
 Please see the [Build and Install Guide](https://docs.rapids.ai/api/cuvs/nightly/build/) for more information on installing the available cuVS packages and building from source.
 
+### Standalone C library (Docker)
+
+To build the standalone C library tarball (`libcuvs_c.tar.gz`) for use in your own C/C++ projects, see **[Building the standalone C library with Docker](https://docs.nvidia.com/cuvs/installation#build-the-standalone-c-library-with-docker)**. That guide covers prerequisites, Docker build/run commands, custom CUDA/Python versions, and where the output is written.
+
 ## Getting Started
 
 The following code snippets train an approximate nearest neighbors index for the CAGRA algorithm in the various different languages supported by cuVS.

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 docs tests bench-ann examples tarball --tarball-build-tests --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)
@@ -33,6 +33,7 @@ HELP="$0 [<target> ...] [<flag> ...] [--cmake-args=\"<args>\"] [--cache-tool=<to
    tests            - build the tests
    bench-ann        - build end-to-end ann benchmarks
    examples         - build the examples
+   tarball          - build the standalone C library tarball with Docker
 
  and <flag> is:
    -v                          - verbose build mode
@@ -56,6 +57,7 @@ HELP="$0 [<target> ...] [<flag> ...] [--cmake-args=\"<args>\"] [--cache-tool=<to
    --no-shared-libs            - build without shared libraries
    --show_depr_warn            - show cmake deprecation warnings
    --run-java-tests            - run Java tests after building
+   --tarball-build-tests       - include the C library tests in the standalone tarball
    --build-metrics             - filename for generating build metrics report for libcuvs
    --incl-cache-stats          - include cache statistics in build metrics report
    --cmake-args=\\\"<args>\\\" - pass arbitrary list of CMake configuration options (escape all quotes in argument)
@@ -574,3 +576,61 @@ if hasArg examples; then
     ./build.sh
     popd
 fi
+
+################################################################################
+# Build the standalone C library tarball (if requested)
+
+if hasArg tarball; then
+    if [[ "${CUVS_TARBALL_IN_CONTAINER:-0}" == "1" ]]; then
+        BUILD_OUTPUT_DIR="${BUILD_OUTPUT_DIR:-${REPODIR}}"
+        tar czf "${BUILD_OUTPUT_DIR}/libcuvs_c.tar.gz" -C "${REPODIR}/c/build/install" .
+        ls -lh "${BUILD_OUTPUT_DIR}/libcuvs_c.tar.gz"
+    else
+        CUDA_VERSION="${CUDA_VERSION:-13.0}"
+        PYTHON_VERSION="${PYTHON_VERSION:-3.11}"
+        BUILD_OUTPUT_DIR="${BUILD_OUTPUT_DIR:-${REPODIR}/build}"
+        IMAGE_NAME="${IMAGE_NAME:-cuvs-standalone-c}"
+
+        BUILD_ARGS=()
+        if hasArg --tarball-build-tests; then
+            BUILD_ARGS+=(--tarball-build-tests)
+        fi
+
+        mkdir -p "${BUILD_OUTPUT_DIR}"
+        BUILD_OUTPUT_DIR_ABS=$(cd "${BUILD_OUTPUT_DIR}"; pwd)
+
+        echo "Building Docker image ${IMAGE_NAME} (CUDA ${CUDA_VERSION}, Python ${PYTHON_VERSION})..."
+        docker build -f "${REPODIR}/Dockerfile.standalone" \
+            --build-arg CUDA_VERSION="${CUDA_VERSION}" \
+            --build-arg PYTHON_VERSION="${PYTHON_VERSION}" \
+            -t "${IMAGE_NAME}" \
+            "${REPODIR}"
+
+        DOCKER_ENV=()
+        for var in ${CUVS_TARBALL_DOCKER_ENV_VARS:-}; do
+            if [[ ! "${var}" =~ ^[a-zA-Z_][a-zA-Z0-9_]*$ ]]; then
+                echo "Invalid Docker environment variable name: ${var}" >&2
+                exit 1
+            fi
+            if [[ -n "${!var:-}" ]]; then
+                DOCKER_ENV+=(-e "${var}=${!var}")
+            fi
+        done
+
+        echo "Running standalone C build in container..."
+        docker run --rm \
+            -v "${REPODIR}:/workspace" \
+            -v "${BUILD_OUTPUT_DIR_ABS}:/build" \
+            "${DOCKER_ENV[@]}" \
+            "${IMAGE_NAME}" \
+            "${BUILD_ARGS[@]}"
+
+        if [[ ! -f "${BUILD_OUTPUT_DIR_ABS}/libcuvs_c.tar.gz" ]]; then
+            echo "Expected tarball not found at ${BUILD_OUTPUT_DIR_ABS}/libcuvs_c.tar.gz" >&2
+            exit 1
+        fi
+
+        cp -v "${BUILD_OUTPUT_DIR_ABS}/libcuvs_c.tar.gz" "${REPODIR}/libcuvs_c.tar.gz"
+        echo "Copied libcuvs_c.tar.gz to ${REPODIR}/libcuvs_c.tar.gz"
+    fi
+fi

ci/run_standalone_c_docker.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Pass CI-specific environment variables to the standalone tarball build.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+export CUVS_TARBALL_DOCKER_ENV_VARS="AWS_REGION AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN RAPIDS_AUX_SECRET_1 RAPIDS_ARTIFACTS_DIR RAPIDS_BUILD_TYPE RAPIDS_DATETIME_STRING RAPIDS_REPOSITORY RAPIDS_SHA RAPIDS_REF_NAME RAPIDS_NIGHTLY_DATE"
+
+exec "${REPO_ROOT}/build.sh" tarball "$@"