cudawrappers

This library is a C++ wrapper for the Nvidia C libraries (e.g. CUDA driver, nvrtc, cuFFT etc.). The main purposes are:

1. easier resource management, leading to lower risk of programming errors;
2. better fault handling (through exceptions);
3. more compact user code.

This library also supports AMD GPUs through the HIP: C++ Heterogeneous-Compute
Interface for Portability.

Originally, the API enforced RAII to even further reduce the risk of faulty code, but enforcing RAII and compatibility with (unmanaged) objects obtained outside this API are mutually exclusive.

Requirements

Usage

CMake is used to build cudawrappers. To build the library, run:

git clone https://github.com/nlesc-recruit/cudawrappers
cd cudawrappers
cmake -S . -B build
make -C build

This creates a build directory. Since cudawrappers is header-only, no library objects will be built.
For more details on the building requirements and testing, see the developer documentation.

To install cudawrappers to a specific location (e.g., ~/.local), use:

cmake -DCMAKE_INSTALL_PREFIX=$HOME/.local -S . -B build
make -C build
make -C build install

You can optionally select what cudawrappers components should be enabled by
specifying the CUDAWRAPPERS_COMPONENTS option. To build all components,
specify: -DCUDAWRAPPERS_COMPONENTS=all. By default, only the cu and nvrtc
components are enabled. The other components include: cufft, nvml (CUDA
only) and nvtx.

Enabling HIP Support

To enable HIP:

1. Add the following code to your project's CMakeLists.txt file:

   enable_language(HIP)
   set(CUDAWRAPPERS_BACKEND "HIP")
   

   Alternatively, use the -DCUDAWRAPPERS_BACKEND=HIP argument when running CMake.

2. Ensure that every target your project builds is 'hipfied'.
   This is done by marking relevant source files as 'HIP' compatible:

   set_source_files_properties(source.cpp PROPERTIES LANGUAGE HIP)
   

3. Optionally, use #ifdef (__HIP__) directives in your source code to enable/disable certain sections for HIP.

4. Build: ensure that the hipcc compiler is selected.
   This can be done via the command line:

   CXX=hipcc cmake -B build
   

Note: When building for both NVIDIA and AMD HIP,
using seperate build folders (e.g, build_nvidia and build_amd) is encouraged.
Additionally, please note that contrary to CUDA, the HIP backend does not implement GPU contexts. For library interoperability, it provides a (non-functioning) mock implementation.
Still, the usage of cu::Context is strongly discouraged, and has been marked deprecated since cudawrappers version 0.9.0. Support will likely be dropped in a future release.