[FEA] Centralize CUDA environment variable handling and prioritize CUDA_PATH over CUDA_HOME

[rparolin]

This PR introduces centralized CUDA environment variable handling across cuda-python packages with improved consistency and better handling of conflicting environment variable configurations.

The previous implicit priority of CUDA_HOME over CUDA_PATH was inconsistent with:

• NVIDIA's own CUDA Toolkit installers (which set CUDA_PATH by default)
• CMake's FindCUDAToolkit module (prioritizes CUDA_PATH)

Key Changes

Breaking Change - Environment Variable Priority

Changed the search order priority from CUDA_HOME > CUDA_PATH to CUDA_PATH > CUDA_HOME to align with NVIDIA tooling standards and industry conventions. This affects all packages that query CUDA Toolkit locations (cuda.pathfinder, cuda.core, cuda.bindings).

New Module: cuda.pathfinder._utils.env_var_constants

• Defines canonical search order CUDA_ENV_VARS_ORDERED = ("CUDA_PATH", "CUDA_HOME")
• Zero-dependency module safe for bootstrap scenarios
• Single source of truth for environment variable ordering

Enhanced cuda.pathfinder._utils.env_vars

• Improved get_cuda_home_or_path() with robust path comparison using os.path.samefile()
• Handles symlinks, junctions, trailing slashes, and case-insensitivity correctly
• Warns users when multiple environment variables are set but point to different locations
• Result is cached for process lifetime for consistent behavior
• Preserves empty strings when explicitly set

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.