Merge pull request #7587 from VersatusHPC/fix/issue-7399-cuda-samples-docs

docs: fix CUDA Samples verification

docs/source/advanced/gpu/nvidia/verify_cuda_install.rst

@@ -11,26 +11,46 @@ The following verification steps only apply to the ``cuda`` (full) installations
 
     nvcc -V
 
-#. Verify running CUDA GPU jobs by compiling the samples and executing the ``deviceQuery`` or ``bandwidthTest`` programs.
+#. Verify that the CUDA runtime can detect the installed GPUs by compiling and
+   executing NVIDIA's ``deviceQuery`` sample.
 
-   * Compile the samples: ::
+   CUDA Samples 12.8 and later require CMake 3.20 or later. Select a
+   `CUDA Samples release <https://github.com/NVIDIA/cuda-samples/releases>`_
+   that is compatible with the Toolkit version reported by ``nvcc -V``.
+   Replace ``<samples-tag>`` below with that release tag (for example,
+   ``v13.3`` for CUDA 13.3).
 
-        git clone https://github.com/NVIDIA/cuda-samples.git
-        cd cuda-samples/Samples/1_Utilities/deviceQuery
-        make
+   The sample's top-level directory has changed between releases. The
+   ``git ls-files`` command below locates it without hard-coding that directory.
+
+   * Clone the selected release and build only ``deviceQuery``: ::
+
+        git clone --branch <samples-tag> --depth 1 \
+          https://github.com/NVIDIA/cuda-samples.git
+        cd cuda-samples
+        sample_dir=$(dirname "$(git ls-files '*/1_Utilities/deviceQuery/CMakeLists.txt')")
+        cmake -S "$sample_dir" -B build \
+          -DCMAKE_BUILD_TYPE=Release \
+          -DCMAKE_RUNTIME_OUTPUT_DIRECTORY="$PWD/build" \
+          -DCMAKE_RUNTIME_OUTPUT_DIRECTORY_RELEASE="$PWD/build"
+        cmake --build build --target deviceQuery --config Release --parallel
 
    * Run the ``deviceQuery`` sample: ::
 
-        ./deviceQuery
+        ./build/deviceQuery
 
-     A successful run will end with ``Result = PASS``.
+     Confirm that the output lists each expected GPU and ends with
+     ``Result = PASS``.
 
-   * Run the ``bandwidthTest`` sample: ::
+.. note::
 
-        cd ../bandwidthTest
-        make
-        ./bandwidthTest
+   CUDA Samples releases before 12.8 use release-specific Makefiles. Follow
+   the build instructions in the README shipped with the selected tag instead
+   of the CMake commands above.
 
-     A successful run will end with ``Result = PASS``.
+.. note::
 
-    NOTE: The CUDA Samples are not meant for performance measurements. Results may vary when GPU Boost is enabled.
+   NVIDIA removed ``bandwidthTest`` from CUDA Samples 12.9 because it did not
+   produce accurate results. Use
+   `NVBandwidth <https://github.com/NVIDIA/nvbandwidth>`_ when bandwidth
+   measurements are required.