QOMPASS AI

Library — Zig bindings for NVIDIA CUDA (driver, NVRTC, cuRAND)

Qudaz

Qudaz

Version 1.00Source on GitHub

OVERVIEW

Qudaz is the "Qompass AI Cuda library for Zig": it provides a high-level interface to communicate with NVIDIA GPUs from Zig, and it can detect a CUDA installation and link it into a project's binary on Linux/macOS.

HOW IT WORKS

  1. 1Depend on the library from your Zig project's `build.zig` and fetch its `qudaz` module (the root `build.zig` registers it with `b.addModule("qudaz", ...)` rooted at `src/lib.zig`).
  2. 2At build time the library locates CUDA: it checks the `-DCUDA_PATH` option first, otherwise probes `/usr`, `/usr/local/cuda`, `/opt/cuda`, `/usr/lib/cuda`, and a Windows v12.3 toolkit path for `include/cuda.h`.
  3. 3Link libc plus the `cuda`, `nvrtc`, `curand`, and `cudart` system libraries, as the test build does.
  4. 4In code, create a device with `Device.new(gpu)` or `Device.default()`, allocate with `alloc`/`allocZeros`, and copy with `htodCopy`.
  5. 5Compile CUDA source to PTX at runtime via the `Compile` module (`cudaText`/`cudaFile`/`getPtx`) and load it with `Device.loadPtx`/`loadPtxText`.
How it works, step by step — each step as the project's own documentation states it.

CONCEPTS

ZIG ON TOP — CUDA UNDERNEATH, LINKED AT BUILD TIMEYOUR ZIG CODEDevice.default() · alloc · htodCopypublic API: Device · Compile · Rng · CudaSliceQUDAZ — src/lib.zighigh-level Zig bindings, CAPI underneathLaunchConfig · CudaError · Compile → PTXCUDA DRIVER APIlibcudadevices · memory · modulesDevice calls land hereNVRTClibnvrtcCUDA source → PTX at runtimeCompile.cudaText / cudaFileCURANDlibcurandGPU random numbersthe Rng exportBUILD TIME — build.zig FINDS AND LINKS CUDA-DCUDA_PATH first, else probe /usr · /usr/local/cuda · /opt/cuda · /usr/lib/cudalinks libc + cuda · nvrtc · curand · cudartminimum Zig 0.14.0 · package version 0.1.0 — the build.zig.zon contract
The qudaz stack: Zig code calls the library's public API (Device, Compile, Rng, CudaSlice, LaunchConfig, CudaError); the bindings sit over NVIDIA's CUDA driver API, NVRTC runtime compilation, and cuRAND libraries; and build.zig locates the CUDA installation at build time (-DCUDA_PATH first, then probed roots) and links libc plus the cuda, nvrtc, curand, and cudart system libraries.

CONFIGURATION

OptionDefaultWhat it does
CUDA_PATH (build option `-DCUDA_PATH`)auto-detected"locally installed Cuda's path" — manual CUDA installation path given at build time
CUDA auto-detection roots/usr`, `/usr/local/cuda`, `/opt/cuda`, `/usr/lib/cuda`, `C:/Program Files/NVIDIA GPU Computing Toolkit/CUDA/v12.3Probed in order for `include/cuda.h`; build fails with `CUDA_INSTALLATION_NOT_FOUND` if none match
version0.1.0Package version
minimum_zig_version0.14.0Minimum Zig version
Public API surface—`CudaSlice`, `Device`, `Compile`, `LaunchConfig`, `CAPI`, `Rng`, `CudaError` exported from the module root

CONTROLS

ActionControl
Run the library testszig build test
Run one test file`zig build test-<name>` (per-file "Individual Test" steps registered by the build)
Clean cache/artifact folders`zig build clean` ("Cleans the cache folders")
Run an example`zig build run` (in an example project)
Give a custom CUDA path in an exampleb.dependency("cudaz", .{ .CUDA_PATH = "<your cuda path>" })

NOT COVERED

- The README's "Customization" anchor is referenced ("Check Customization to give cuda manual path") but the README as fetched contains no Usage/Installation/Customization section — the only install/usage evidence is `build.zig` and the examples. - Naming is inconsistent in sources: the current root `build.zig` registers the module as `qudaz`, while `example/increment/build.zig` and its Readme still use the old `cudaz` name and clone URL (`git@github.com:akhildevelops/cudaz.git`, and the Readme says to open `example/custom_type` from the increment page). Example instructions were recorded verbatim, not reconciled. - No published package/registry install command (e.g. `zig fetch`) is documented in the repo.

REFERENCES

  1. CUDA Driver API documentation (NVIDIA)The driver-level API qudaz's Device and CAPI layers bind: contexts, memory, and module (PTX) loading.
  2. NVRTC — CUDA runtime compilation documentation (NVIDIA)The runtime compilation library behind qudaz's Compile module, which turns CUDA source into PTX at runtime.
  3. cuRAND library documentation (NVIDIA)The GPU random-number library behind qudaz's Rng export.
  4. Zig language reference (0.14.0)The language reference for the Zig version qudaz requires as its minimum (build.zig.zon: minimum_zig_version 0.14.0), including its C interop and build system.