[dist] Add build variants: full, minimal, legacy

Breakthrough · Breakthrough · commit 6cf1105b69de · 2026-02-01T19:41:49.000-05:00
* full: SASS for all architectures, PTX for 10.0
 * minimal: SASS/PTX for 5.0 only
 * legacy: SASS/PTX for 3.5 only
diff --git a/.github/workflows/build_wheels_windows.yml b/.github/workflows/build_wheels_windows.yml
@@ -40,35 +40,42 @@ jobs:
       matrix:
         python-version: ['3.13']
         platform: [x64]
-        cuda-version: ['12']
+        # Build variants control binary size vs JIT compilation tradeoff:
+        # - full: CUDA 12, native SASS for all GPUs (5.0-10.0), largest binary, no JIT needed
+        # - minimal: CUDA 12, only PTX/SASS 5.0, smallest binary, JIT required for non-Maxwell GPUs
+        # - legacy: CUDA 11, PTX/SASS 3.5, for older GPUs (Kepler+) and systems with older drivers
+        build-variant: ['full', 'minimal', 'legacy']
         include:
-          # CUDA 12: Supports Maxwell (5.0) through Blackwell (10.0)
-          # TODO(@Breakthrough): Expand PTX legacy support back to 5.0, it doesn't make the final
-          # distribution that much larger and may help users with older GPUs.
+          # CUDA 12 - Full variant: All SASS targets for maximum performance
           - cuda-version: '12'
+            build-variant: 'full'
             runs-on: 'windows-2025'
             cuda-installer: 'cuda_12.9.1_windows_network.exe'
             cuda-path-version: 'v12.9'
             cudnn-archive: 'cudnn-windows-x86_64-9.18.1.3_cuda12-archive.zip'
             cudnn-folder: 'cudnn-windows-x86_64-9.18.1.3_cuda12-archive'
+            cudnn-dll-path: 'bin/x64'
             video-codec-sdk-archive: 'Video_Codec_SDK_13.0.37.zip'
             video-codec-sdk-folder: 'Video_Codec_SDK_13.0.37'
             cuda-arch-bin: '5.0;5.2;6.0;6.1;7.0;7.5;8.0;8.6;8.9;9.0;10.0'
             cuda-arch-ptx: '10.0'
             cache-key: 'nvidia-deps-cuda-12.9.1-cudnn-9.18.1.3'
-          # TODO: Re-enable CUDA 13 after updating to OpenCV 4.13+
-          # CUDA 13: Supports Turing (7.5) through Blackwell (12.0)
-          # - cuda-version: '13'
-          #   runs-on: 'windows-2025'
-          #   cuda-installer: 'cuda_13.1.1_windows_network.exe'
-          #   cuda-path-version: 'v13.1'
-          #   cudnn-archive: 'cudnn-windows-x86_64-9.18.1.3_cuda13-archive.zip'
-          #   cudnn-folder: 'cudnn-windows-x86_64-9.18.1.3_cuda13-archive'
-          #   video-codec-sdk-archive: 'Video_Codec_SDK_13.0.37.zip'
-          #   video-codec-sdk-folder: 'Video_Codec_SDK_13.0.37'
-          #   cuda-arch-bin: '7.5;8.0;8.6;8.9;9.0;10.0;12.0'
-          #   cuda-arch-ptx: '12.0'
-          #   cache-key: 'nvidia-deps-cuda-13.1.1-cudnn-9.18.1.3'
+          # CUDA 11 - Legacy variant: For older GPUs (Kepler+) and systems with older drivers
+          # NOTE: CUDA 11.8 only supports VS2017-VS2022, so we use the v142 toolset on windows-2025
+          - cuda-version: '11'
+            build-variant: 'legacy'
+            runs-on: 'windows-2025'
+            cmake-toolset: 'v142'
+            cuda-installer: 'cuda_11.8.0_windows_network.exe'
+            cuda-path-version: 'v11.8'
+            cudnn-archive: 'cudnn-windows-x86_64-8.9.7.29_cuda11-archive.zip'
+            cudnn-folder: 'cudnn-windows-x86_64-8.9.7.29_cuda11-archive'
+            cudnn-dll-path: 'bin'
+            video-codec-sdk-archive: 'Video_Codec_SDK_13.0.37.zip'
+            video-codec-sdk-folder: 'Video_Codec_SDK_13.0.37'
+            cuda-arch-bin: '3.5'
+            cuda-arch-ptx: '3.5'
+            cache-key: 'nvidia-deps-cuda-11.8.0-cudnn-8.9.7.29'
     env:
       ACTIONS_ALLOW_UNSECURE_COMMANDS: true
       SDIST: 0
@@ -139,7 +146,7 @@ jobs:
         $CUDNN_PATH = "D:/a/opencv-python-cuda/opencv-python-cuda/${{ matrix.cudnn-folder }}"
         echo "CUDNN_LIBRARY=$CUDNN_PATH/lib/x64/cudnn.lib" | Out-File -FilePath $env:GITHUB_ENV -Append
         echo "CUDNN_INCLUDE_DIR=$CUDNN_PATH/include" | Out-File -FilePath $env:GITHUB_ENV -Append
-        Copy-Item -Path "$CUDNN_PATH/bin/x64/*" -Destination .  -Include "*.dll"
+        Copy-Item -Path "$CUDNN_PATH/${{ matrix.cudnn-dll-path }}/*" -Destination .  -Include "*.dll"
       shell: pwsh
     - name: 🔧 Install NVIDIA Video Codec SDK
       run: |
@@ -160,9 +167,9 @@ jobs:
       if: ${{ inputs.restore_build_cache && !inputs.rolling_build }}
       with:
         path: _skbuild
-        key: ${{ runner.os }}-${{ matrix.python-version }}-cuda${{ matrix.cuda-version }}-${{ hashFiles('**/CMakeLists.txt') }}
+        key: ${{ runner.os }}-${{ matrix.python-version }}-cuda${{ matrix.cuda-version }}-${{ matrix.build-variant }}-${{ hashFiles('**/CMakeLists.txt') }}
         restore-keys: |
-          ${{ runner.os }}-${{ matrix.python-version }}-cuda${{ matrix.cuda-version }}-
+          ${{ runner.os }}-${{ matrix.python-version }}-cuda${{ matrix.cuda-version }}-${{ matrix.build-variant }}-
 
     - name: Build a package
       # CMake 3.25 regression fix. See https://stackoverflow.com/questions/74162633/problem-compiling-from-source-opencv-with-mvsc2019-in-64-bit-version
@@ -176,6 +183,11 @@ jobs:
         if (Test-Path _skbuild) {
           $SKIP_CMAKE = "--skip-cmake"
         }
+        # Set CMake toolset if specified (e.g., v142 for CUDA 11 compatibility with VS2019)
+        if ("${{ matrix.cmake-toolset }}") {
+          $env:CMAKE_ARGS = "-T ${{ matrix.cmake-toolset }}"
+          echo "Using CMake toolset: ${{ matrix.cmake-toolset }}"
+        }
         python setup.py $SKIP_CMAKE bdist_wheel --py-limited-api=cp37 --dist-dir="$PWD\wheelhouse" -v
       shell: pwsh
 
@@ -184,11 +196,11 @@ jobs:
       if: ${{ inputs.save_build_cache && !inputs.rolling_build }}
       with:
         path: _skbuild
-        key: ${{ runner.os }}-${{ matrix.python-version }}-cuda${{ matrix.cuda-version }}-${{ hashFiles('**/CMakeLists.txt') }}
+        key: ${{ runner.os }}-${{ matrix.python-version }}-cuda${{ matrix.cuda-version }}-${{ matrix.build-variant }}-${{ hashFiles('**/CMakeLists.txt') }}
     - name: Saving all wheels
       uses: actions/upload-artifact@v4
       with:
-        name: wheel-cuda${{ matrix.cuda-version }}-${{ matrix.platform }}
+        name: opencv-python-cuda-${{ matrix.build-variant }}-${{ matrix.platform }}
         path: wheelhouse/opencv*
 
   Test:
@@ -202,11 +214,10 @@ jobs:
       matrix:
         python-version: ['3.12']
         platform: [x64]
-        cuda-version: ['12']  # TODO: Re-enable '13' after updating to OpenCV 4.13+
+        build-variant: ['full', 'minimal', 'legacy']
     env:
       ACTIONS_ALLOW_UNSECURE_COMMANDS: true
       OPENCV_TEST_DATA_PATH: ${{ github.workspace }}\opencv_extra\testdata
-      PlatformToolset: v143
     steps:
     - name: Cleanup
       shell: bash
@@ -227,7 +238,7 @@ jobs:
     - name: Download a wheel accordingly to matrix
       uses: actions/download-artifact@v4
       with:
-        name: wheel-cuda${{ matrix.cuda-version }}-${{ matrix.platform }}
+        name: opencv-python-cuda-${{ matrix.build-variant }}-${{ matrix.platform }}
         path: wheelhouse/
     - name: Package installation
       run: |
diff --git a/docs/cuda-compatibility.md b/docs/cuda-compatibility.md
@@ -33,7 +33,6 @@
 PTX is forward-compatible only (e.g. PTX 10.0 works on GPUs ≥10.0, not older). SASS is required for older GPUs that are lower than the PTX version. A GPU needs either matching SASS or older PTX which it can JIT compile.
 
 
-
 ## References
 
 - [CUDA Toolkit Archive](https://developer.nvidia.com/cuda-toolkit-archive)
