1 # Building HAT
 2 
 3 ----
 4 
 5 * [Contents](hat-00.md)
 6 * House Keeping
 7     * [Project Layout](hat-01-01-project-layout.md)
 8     * [Building Babylon](hat-01-02-building-babylon.md)
 9     * [Building HAT](hat-01-03-building-hat.md)
10         * [Enabling the CUDA Backend](hat-01-05-building-hat-for-cuda.md)
11 * Programming Model
12     * [Programming Model](hat-03-programming-model.md)
13 * Interface Mapping
14     * [Interface Mapping Overview](hat-04-01-interface-mapping.md)
15     * [Cascade Interface Mapping](hat-04-02-cascade-interface-mapping.md)
16 * Implementation Detail
17     * [Walkthrough Of Accelerator.compute()](hat-accelerator-compute.md)
18     * [How we minimize buffer transfers](hat-minimizing-buffer-transfers.md)
19 
20 ----
21 
22 This guide provides step-by-step instructions to configure Babylon/HAT for CUDA-based GPU acceleration.
23 
24 ### Prerequisites
25 
26 To run Babylon/HAT with the CUDA backend, ensure the following components are properly installed:
27 
28 1. **The NVIDIA GPU Driver:** Download and install the latest appropriate driver for your operating system from the [NVIDIA Drivers page](https://www.nvidia.com/en-us/drivers/)
29 2. **The CUDA Toolkit (SDK):** Download the matching CUDA Toolkit from the [NVIDIA CUDA Downloads page](https://developer.nvidia.com/cuda-downloads).
30 
31 The CUDA Toolkit version must be compatible with your installed NVIDIA driver.
32 For example, as of June 2025, the stable NVIDIA driver for Linux is `570.169`, which supports CUDA Toolkit version `12.8`.
33 
34 
35 Always verify compatibility before installation to prevent runtime errors:
36 - You can find previous CUDA Toolkit versions on the [NVIDIA CUDA Toolkit Archive](https://developer.nvidia.com/cuda-toolkit-archive)
37 - Review supported CUDA versions and PTX ISA implementations in the [NVIDIA Parallel Thread Execution documentation](https://docs.nvidia.com/cuda/parallel-thread-execution/index.html#release-notes).
38 
39 
40 ### Troubleshooting: Unsupported CUDA/PTX Versions
41 
42 If Babylon/HAT runs with an incompatible CUDA/PTX version, you may encounter an error similar to:
43 
44 ```bash
45 cuModuleLoadDataEx CUDA error = 222 CUDA_ERROR_UNSUPPORTED_PTX_VERSION
46       /<path/to/babylon>/hat/backends/ffi/cuda/src/main/native/cpp/cuda_backend.cpp line 220
47 ```
48 
49 If this is your case, you can:
50   - **update your GPU driver**.
51   - **or downgrade your CUDA version.**
52 
53 ### Building HAT for the CUDA backend
54 
55 If the NVIDIA driver and the CUDA Toolkit SDK are installed, the HAT build process will automatically compile
56 all sources to dispatch with the CUDA backend.
57 
58 ```bash
59 java @hat/bld
60 ```
61 
62 ### Run HAT with the CUDA Backend
63 
64 You can enable the CUDA backend by using the `ffi-cuda` option from HAT.
65 For example, to run the Matrix Multiplication example:
66 
67 ```bash
68 java @hat/run ffi-cuda matmul 1D
69 ```