.. SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0

.. py:currentmodule:: cuda.pathfinder

``cuda-pathfinder`` 1.5.0 Release notes
=======================================

Breaking Change
---------------

* **CUDA environment variable priority changed**: ``CUDA_PATH`` now takes
  precedence over ``CUDA_HOME`` when both are set. Previously, ``CUDA_HOME`` had
  higher priority. If both variables are set and point to different locations,
  a warning will be issued and ``CUDA_PATH`` will be used. This change aligns
  with industry standards and NVIDIA's recommended practices.

  The ``found_via`` provenance field on ``LoadedDL``, ``LocatedHeaderDir``,
  ``LocatedStaticLib``, and ``LocatedBitcodeLib`` now reports ``"CUDA_PATH"``
  (previously ``"CUDA_HOME"``) when a library or header was discovered through
  the ``CUDA_PATH``/``CUDA_HOME`` environment variables. The label reflects
  the highest-priority variable name, not necessarily the variable that
  supplied the value.

  **Migration Guide**:

  - If you rely on ``CUDA_HOME``, consider switching to ``CUDA_PATH``
  - If you set both variables, ensure they point to the same CUDA Toolkit installation
  - If they differ intentionally, be aware that ``CUDA_PATH`` will now be used

Highlights
----------

* Added :py:func:`cuda.pathfinder.get_cuda_path_or_home`, a centralized
  function for resolving ``CUDA_PATH``/``CUDA_HOME``. Features:

  - Intelligent path comparison that handles symlinks, case sensitivity, and trailing slashes
  - Result caching for performance (first call determines the path for the process lifetime)
  - Clear warnings when both ``CUDA_PATH`` and ``CUDA_HOME`` are set but differ

  Future releases of ``cuda-bindings`` and ``cuda-core`` will adopt this
  function to ensure consistent ``CUDA_PATH`` > ``CUDA_HOME`` priority
  across all cuda-python packages.
  (`PR #1801 <https://github.com/NVIDIA/cuda-python/pull/1801>`_)
