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

Breakthrough · Breakthrough · commit 129f38e8d089 · 2026-02-03T20:10:51.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/.claude/settings.local.json b/.claude/settings.local.json
@@ -7,7 +7,8 @@
       "Bash(gh run view:*)",
       "Bash(gh workflow:*)",
       "Bash(unzip:*)",
-      "Bash(ls:*)"
+      "Bash(ls:*)",
+      "Bash(gh run list:*)"
     ]
   }
 }
diff --git a/.github/workflows/build_wheels_windows.yml b/.github/workflows/build_wheels_windows.yml
@@ -38,37 +38,47 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
+        # 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
+        # - legacy: CUDA 11, PTX/SASS 3.5, for older GPUs (Kepler+) and systems with older drivers
+        build-variant: ['full', 'legacy']
         python-version: ['3.13']
         platform: [x64]
-        cuda-version: ['12']
         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-version: '12'
+          # CUDA 12 - Full variant: All SASS targets for maximum performance
+          - build-variant: 'full'
             runs-on: 'windows-2025'
+            cuda-version: '12'
+            cmake-toolset: 'v143'
+            cuda-nvcc-flags: '-Xcompiler /Zc:preprocessor'
             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
+          # TODO: Figure out how to setup a build environment so we don't need --allow-unsupported-compiler.
+          #       CUDA 11.8's host_config.h rejects newer _MSC_VER values even though they're compatible.
+          - build-variant: 'legacy'
+            runs-on: 'windows-2025'
+            cuda-version: '11'
+            cmake-toolset: 'v143'
+            cuda-nvcc-flags: '--allow-unsupported-compiler'
+            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 +149,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 +170,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
@@ -171,11 +181,22 @@ jobs:
         python -m pip install --upgrade pip
         python -m pip install --upgrade setuptools
         python -m pip install cmake==3.24.2
-        python -m pip install toml && python -c "import toml; c = toml.load('pyproject.toml'); print('\n'.join(c['build-system']['requires']))" >> requirements.txt | python -m pip install -r requirements.txt
+        python -m pip install toml
+        python -c "import toml; c = toml.load('pyproject.toml'); print('\n'.join(c['build-system']['requires']))" > requirements.txt
+        python -m pip install -r requirements.txt
         $CI_BUILD = 1
         if (Test-Path _skbuild) {
           $SKIP_CMAKE = "--skip-cmake"
         }
+        # Set CMake generator and toolset (e.g., v142 for CUDA 11, v143 for CUDA 12)
+        # Note: Toolset (-T) requires Visual Studio generator, not Ninja
+        # Using environment variables avoids quoting issues with CMAKE_ARGS
+        $env:CMAKE_GENERATOR = "Visual Studio 17 2022"
+        $env:CMAKE_GENERATOR_PLATFORM = "x64"
+        $env:CMAKE_GENERATOR_TOOLSET = "${{ matrix.cmake-toolset }}"
+        $env:CUDA_NVCC_FLAGS = "${{ matrix.cuda-nvcc-flags }}"
+        echo "Using CMake generator: Visual Studio 17 2022, platform: x64, toolset: ${{ matrix.cmake-toolset }}"
+        echo "Using CUDA NVCC flags: ${{ matrix.cuda-nvcc-flags }}"
         python setup.py $SKIP_CMAKE bdist_wheel --py-limited-api=cp37 --dist-dir="$PWD\wheelhouse" -v
       shell: pwsh
 
@@ -184,11 +205,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 +223,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', '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 +247,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)
diff --git a/setup.py b/setup.py
@@ -153,8 +153,11 @@ def main():
     # Raw paths relative to sourcetree root.
     files_outside_package_dir = {"cv2": ["LICENSE.txt", "LICENSE-3RD-PARTY.txt","*.dll"]}
 
+    # CMake generator and toolset configuration
+    # The toolset can be overridden via CMAKE_GENERATOR_TOOLSET env var (e.g., v142 for CUDA 11.x)
+    cmake_toolset = os.environ.get("CMAKE_GENERATOR_TOOLSET", "v143")
     ci_cmake_generator = (
-        ["-G", "Visual Studio 17 2022", "-T", "v143"]
+        ["-G", "Visual Studio 17 2022", "-T", cmake_toolset]
         if os.name == "nt"
         else ["-G", "Unix Makefiles"]
     )
@@ -214,10 +217,12 @@ def main():
             else []
         )
         + (
-            # CUDA 12.9+ requires MSVC's conformant preprocessor for CCCL headers.
-            # -Xcompiler passes the flag from nvcc to the host compiler (MSVC).
-            # See: https://github.com/NVIDIA/cccl/issues/5166
-            ["-DCUDA_NVCC_FLAGS=-Xcompiler /Zc:preprocessor"]
+            # NVCC flags for Windows builds:
+            # - CUDA 12.9+ requires MSVC's conformant preprocessor (-Xcompiler /Zc:preprocessor)
+            #   See: https://github.com/NVIDIA/cccl/issues/5166
+            # - CUDA 11.x needs --allow-unsupported-compiler for newer MSVC versions
+            #   where _MSC_VER exceeds what host_config.h expects
+            ["-DCUDA_NVCC_FLAGS=" + os.environ.get("CUDA_NVCC_FLAGS", "-Xcompiler /Zc:preprocessor")]
             if sys.platform == "win32"
             else []
         )

Original file line number	Diff line number	Diff line change
`@@ -7,7 +7,8 @@`
`7`	`7`	`"Bash(gh run view:*)",`
`8`	`8`	`"Bash(gh workflow:*)",`
`9`	`9`	`"Bash(unzip:*)",`
`10`		`- "Bash(ls:*)"`
	`10`	`+ "Bash(ls:*)",`
	`11`	`+ "Bash(gh run list:*)"`
`11`	`12`	`]`
`12`	`13`	`}`
`13`	`14`	`}`