Add cuda-compat to images built using the latest CUDA toolkit.

.devcontainer/main/devcontainer.json

@@ -1,5 +1,5 @@
 {
-  "image": "mcr.microsoft.com/devcontainers/javascript-node:0-18",
+  "image": "mcr.microsoft.com/devcontainers/javascript-node:24",
   "customizations": {
     "vscode": {
       "extensions": [
@@ -8,7 +8,9 @@
     }
   },
   "features": {
-    "ghcr.io/devcontainers/features/docker-in-docker:2": {}
+    "ghcr.io/devcontainers/features/docker-in-docker:4.1.3": {
+      "moby": false
+    }
   },
   "remoteUser": "node",
   "updateContentCommand": "sudo apt update && sudo apt install -y bash-completion && npm i -g @devcontainers/cli"

features/src/cuda/.bashrc

@@ -5,6 +5,7 @@ __cuda_version="${CUDA_VERSION:-${CUDA_VERSION}}";
 __cuda_version_major="${CUDA_VERSION_MAJOR:-${CUDA_VERSION_MAJOR}}";
 __cuda_version_minor="${CUDA_VERSION_MINOR:-${CUDA_VERSION_MINOR}}";
 __cuda_version_patch="${CUDA_VERSION_PATCH:-${CUDA_VERSION_PATCH}}";
+__cuda_compat_installed="${CUDA_COMPAT_INSTALLED:-${CUDA_COMPAT_INSTALLED}}";
 
 export NVARCH="${__nvarch}";
 export CUDA_HOME="${__cuda_home}";
@@ -13,6 +14,7 @@ export CUDA_VERSION="${__cuda_version}";
 export CUDA_VERSION_MAJOR="${__cuda_version_major}";
 export CUDA_VERSION_MINOR="${__cuda_version_minor}";
 export CUDA_VERSION_PATCH="${__cuda_version_patch}";
+export CUDA_COMPAT_INSTALLED="${__cuda_compat_installed}";
 
 if [ -n "${PATH##*"/usr/local/nvidia/bin:${__cuda_home}/bin"*}" ]; then
     export PATH="/usr/local/nvidia/bin:${__cuda_home}/bin:${PATH}";
@@ -28,4 +30,4 @@ if [ -z "${LD_LIBRARY_PATH:-}" ] \
     export LD_LIBRARY_PATH="/usr/local/nvidia/lib:/usr/local/nvidia/lib64${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
 fi
 
-unset __nvarch __cuda_home __cuda_path __cuda_version __cuda_version_major __cuda_version_minor __cuda_version_patch
+unset __nvarch __cuda_home __cuda_path __cuda_version __cuda_version_major __cuda_version_minor __cuda_version_patch __cuda_compat_installed

features/src/cuda/README.md

@@ -26,6 +26,7 @@ A feature to install the NVIDIA CUDA Toolkit
 | installcuTensor | Install CUDA Tensor Linear Algebra Library (cuTensor) | boolean | false |
 | installNCCL | Install NVIDIA Collective Communications Library (NCCL) | boolean | true |
 | installCUDARuntime | Install CUDA Runtime Library (cudart) | boolean | true |
+| installCudaCompat | Install CUDA Compatibility Package (cuda-compat) | boolean | false |
 | installNVRTC | Install NVIDIA Runtime Compilation Library (NVRTC) | boolean | false |
 | installOpenCL | Install NVIDIA CUDA OpenCL Library | boolean | false |
 | installcuBLAS | Install CUDA Basic Linear Algebra Library (cuBLAS) | boolean | false |

features/src/cuda/devcontainer-feature.json

@@ -1,7 +1,7 @@
 {
   "name": "CUDA Toolkit",
   "id": "cuda",
-  "version": "26.12.1",
+  "version": "26.12.2",
   "description": "A feature to install the NVIDIA CUDA Toolkit",
   "options": {
     "version": {
@@ -86,6 +86,11 @@
       "default": true,
       "description": "Install CUDA Runtime Library (cudart)"
     },
+    "installCudaCompat": {
+      "type": "boolean",
+      "default": false,
+      "description": "Install CUDA Compatibility Package (cuda-compat)"
+    },
     "installNVRTC": {
       "type": "boolean",
       "default": false,

features/src/cuda/install.sh

@@ -201,6 +201,10 @@ if "${INSTALLCUDSS:-false}"; then
     PKGS+=("cudss-cuda-${cuda_ver_major}");
 fi
 
+if [ "${INSTALLCUDACOMPAT:-false}" = true ]; then
+    PKGS+=("cuda-compat-${cuda_ver}");
+fi
+
 if [ "${INSTALLNCCL:-false}" = true ] \
 && test -n "$(apt-cache search libnccl2 2>/dev/null)" \
 && apt-cache policy libnccl2 2>/dev/null | grep -q "+${cuda_tag}"; then
@@ -270,6 +274,15 @@ export CUDA_VERSION_MAJOR;
 export CUDA_VERSION_MINOR;
 export CUDA_VERSION_PATCH;
 
+# Track whether the cuda-compat forward compatibility package was
+# installed, so container entrypoints (via setup-cuda-compat) can decide
+# whether to configure the system to use it.
+CUDA_COMPAT_INSTALLED="false";
+if [ "${INSTALLCUDACOMPAT:-false}" = true ]; then
+    CUDA_COMPAT_INSTALLED="true";
+fi
+export CUDA_COMPAT_INSTALLED;
+
 if [ "${INSTALLCUTENSOR:-false}" = true ]; then
     # Remove extra libcutensor versions
     source ./prune-extra-cutensor-libs.sh;
@@ -282,6 +295,7 @@ vars_+=('$CUDA_VERSION');
 vars_+=('$CUDA_VERSION_MAJOR');
 vars_+=('$CUDA_VERSION_MINOR');
 vars_+=('$CUDA_VERSION_PATCH');
+vars_+=('$CUDA_COMPAT_INSTALLED');
 printf -v vars_ '%s,' "${vars_[@]}";
 
 # export envvars in bashrc files
@@ -296,6 +310,9 @@ cat <<EOF > /etc/ld.so.conf.d/nvidia.conf
 /usr/local/nvidia/lib64
 EOF
 
+# Install the cuda-compat setup script for use by container entrypoints.
+install -m 0755 setup-cuda-compat.sh /usr/local/bin/setup-cuda-compat;
+
 # Clean up
 # rm -rf /tmp/*;
 rm -rf /var/tmp/*;

features/src/cuda/setup-cuda-compat.sh

@@ -0,0 +1,45 @@
+#! /usr/bin/env bash
+
+# Configures the system to use the CUDA forward compatibility libraries
+# (cuda-compat) in preference to the host driver libraries.
+#
+# This script is installed into the image by the `cuda` feature and is
+# intended to be invoked from container entrypoints. It is a no-op unless
+# the feature was installed with `installCudaCompat: true`, which sets
+# CUDA_COMPAT_INSTALLED=true in the container environment.
+
+set -euo pipefail;
+
+# Only configure the system if cuda-compat was installed by the cuda feature.
+if [ "${CUDA_COMPAT_INSTALLED:-false}" != "true" ]; then
+    exit 0;
+fi
+
+# WSL hosts pass the Windows driver through to containers, so the compat
+# libraries are unnecessary there.
+if grep -qi microsoft /proc/version 2>/dev/null; then
+    echo "WSL host detected, skipping cuda-compat configuration.";
+    exit 0;
+fi
+
+compat_dir="${CUDA_HOME:-/usr/local/cuda}/compat";
+
+if [ ! -d "${compat_dir}" ]; then
+    echo "CUDA_COMPAT_INSTALLED is true, but '${compat_dir}' does not exist." >&2;
+    exit 1;
+fi
+
+# Run privileged commands via sudo unless already running as root.
+if [ "$(id -u)" = 0 ]; then
+    as_root() { "$@"; };
+else
+    as_root() { sudo "$@"; };
+fi
+
+# Point the dynamic linker at the compat libraries so they take precedence
+# over the host driver libs. The conf file sorts before the system library
+# dirs in ldconfig's search order, giving the compat libs precedence.
+as_root tee /etc/ld.so.conf.d/cuda-compat.conf <<< "${compat_dir}" > /dev/null;
+as_root ldconfig;
+
+echo "cuda-compat forward compatibility libraries configured from '${compat_dir}'.";

matrix.yml

@@ -1,7 +1,7 @@
 x-cuda-prev-min: &cuda_prev_min { name: "cuda", version: "12.0" }
 x-cuda-prev-max: &cuda_prev_max { name: "cuda", version: "12.9" }
 x-cuda-curr-min: &cuda_curr_min { name: "cuda", version: "13.0" }
-x-cuda-curr-max: &cuda_curr_max { name: "cuda", version: "13.4" }
+x-cuda-curr-max: &cuda_curr_max { name: "cuda", version: "13.4", installCudaCompat: true }
 x-cuda-prev-max-rapids: &cuda_prev_max_rapids { name: "cuda", version: "12.9" }
 x-cuda-curr-max-rapids: &cuda_curr_max_rapids { name: "cuda", version: "13.3" }