{"id":51494966,"url":"https://github.com/coderonion/zcuda","last_synced_at":"2026-07-07T14:02:00.739Z","repository":{"id":339983859,"uuid":"1157731519","full_name":"coderonion/zcuda","owner":"coderonion","description":"zCUDA: 🔗 CUDA Binding Layer | ⚡ CUDA Kernel DSL. Write CUDA kernels in pure Zig. Or keep your C++ kernels. Ship them all to GPU. ","archived":false,"fork":false,"pushed_at":"2026-02-22T16:08:08.000Z","size":380,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-12T05:30:22.400Z","etag":null,"topics":["binding","cpp","cublas","cuda","cudaz","cudnn","dsl","gpu","kernel","llm","llvm","mlir","openclaw","ptx","rust","transformer","zig","zigcuda","ziglang"],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coderonion.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-14T07:48:59.000Z","updated_at":"2026-05-04T13:39:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/coderonion/zcuda","commit_stats":null,"previous_names":["coderonion/zcuda"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/coderonion/zcuda","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coderonion%2Fzcuda","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coderonion%2Fzcuda/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coderonion%2Fzcuda/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coderonion%2Fzcuda/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coderonion","download_url":"https://codeload.github.com/coderonion/zcuda/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coderonion%2Fzcuda/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35230519,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-07T02:00:07.222Z","response_time":90,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["binding","cpp","cublas","cuda","cudaz","cudnn","dsl","gpu","kernel","llm","llvm","mlir","openclaw","ptx","rust","transformer","zig","zigcuda","ziglang"],"created_at":"2026-07-07T14:01:59.928Z","updated_at":"2026-07-07T14:02:00.719Z","avatar_url":"https://github.com/coderonion.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zCUDA\n\n**Write CUDA kernels in pure Zig. Or keep your C++ kernels. Ship them all to GPU.**\n\nzCUDA is a dual-ecosystem GPU programming framework for [Zig](https://ziglang.org/):\n\n- 🔗 **CUDA Binding Layer** — Complete, type-safe Zig bindings for CUDA C++ libraries (driver API, cuBLAS, cuDNN, cuFFT, cuSOLVER, cuSPARSE, cuRAND, NVRTC, NVTX, CUPTI, cuFile, and beyond). Seamlessly call existing, battle-tested CUDA C++ kernels (`.cu` files) from Zig — JIT compile via NVRTC or load pre-compiled PTX. Your mature C++ kernel ecosystem stays intact.\n- ⚡ **CUDA Kernel DSL** — A zero-overhead device-side API (`zcuda_kernel`) that compiles pure Zig directly to PTX at build time. No CUDA C++. No `nvcc`. Just Zig, all the way down to the CUDA registers — with full compile-time type safety, auto-discovery, and type-safe bridge generation.\n\n**The best of both worlds**: Reuse the industry's vast collection of mature CUDA C++ kernels via NVRTC JIT or pre-compiled PTX — zero rewrite, zero migration friction. Write new custom kernels in pure Zig with auto-discovery, type-safe bridges, and `zig build` integration. Both paths produce PTX, both launch through the same `stream.launch()` API, and both ship in your final binary. Start with C++, migrate to Zig at your own pace, or keep both forever.\n\n**Why pure Zig?** Zig brings a rare combination to GPU programming: C-level real-time performance (zero-cost abstractions, no GC, no hidden allocations, deterministic memory layout), Python-like readability (clean syntax, no header files, no forward declarations, no preprocessor macros. One unified toolchain: `zig build` handles build, test, package, and deploy — with built-in package manager (`build.zig.zon`, reproducible hashes, semantic versioning), built-in unit test runner, and first-class cross-compilation to any CUDA-capable platform (x86_64, aarch64, riscv64, and beyond) from any host. Compile-time type safety catches errors at build time and `defer`-based resource management.\n\n\n## Overview\n\n| Metric           | Value                         |\n| ---------------- | ----------------------------- |\n| **Zig**          | 0.16.0-dev.2535+b5bd49460     |\n| **CUDA Toolkit** | 12.8                          |\n| **Modules**      | 11 (driver, nvrtc, cublas, cublaslt, curand, cudnn, cusolver, cusparse, cufft, nvtx, cupti) |\n| **Tests**        | 39 files (22 unit + 17 integration) |\n| **Host Examples**| 58 across 10 categories (50 `run-xxx` targets) + 24 integration |\n| **Kernel Examples** | 80 pure-Zig GPU kernels across 11 categories |\n| **GPU Validated** | ✅ sm_86 (RTX 3080 Ti, CUDA 12.8) — all unit + integration tests PASS, **50/50 run-xxx examples PASS**, **zcuda-demo** All correctness PASSED (`zig build test` + `zig build run` EXIT=0) |\n\n## Features\n\n**CUDA Binding Layer:**\n- ✅ **Type-safe** — Idiomatic Zig API with compile-time type checking, Zig error unions instead of C error codes\n- ✅ **Memory-safe** — RAII-style resource management with `defer`, no leaked GPU memory, streams, or contexts\n- ✅ **Zero-cost** — Direct C API calls via `@cImport`, zero-overhead wrappers, no runtime reflection\n- ✅ **Comprehensive** — 11 CUDA library bindings (driver, nvrtc, cublas, cublaslt, curand, cudnn, cusolver, cusparse, cufft, nvtx, cupti) with full API coverage\n- ✅ **Three-layer architecture** — `sys` (raw FFI) → `result` (error wrapping) → `safe` (ergonomic user API)\n- ✅ **Modular** — Enable only the libraries you need via `-D` build flags, unused modules are zero-cost\n- ✅ **C++ Compatible** — Call existing CUDA C++ kernels via NVRTC JIT or pre-compiled PTX, zero migration friction\n\n**CUDA Kernel DSL:**\n- ✅ **Pure Zig Kernels** — Write CUDA kernels in pure Zig with `zcuda_kernel`, compile to PTX at `zig build` time\n- ✅ **Auto-discovery** — Kernels detected by content (`export fn`), no manual registration or config files\n- ✅ **Full device intrinsics** — shared memory, atomics (`atomicAdd`, `atomicCAS`), warp shuffles (`__shfl_sync`, `__shfl_xor_sync`), `__syncthreads`, `printf`, thread/block/grid indexing\n- ✅ **Tensor Core support** — WMMA and MMA intrinsics for f16, bf16, tf32, int8, fp8 matrix operations\n- ✅ **Type-safe bridge generation** — Auto-generated `Fn` enum per kernel, function name typos caught at compile time\n\n**Ecosystem \u0026 Tooling:**\n- ✅ **5 kernel loading methods** — filesystem PTX, NVRTC JIT (inline), `@embedFile` JIT, `@embedFile` PTX, build.zig auto-generated bridge module\n- ✅ **Hybrid Ready** — Mix CUDA C++ and Zig kernels in the same project, both produce PTX, both use the same `stream.launch()` API\n- ✅ **Cross-compilation** — Target x86_64, aarch64, riscv64, and beyond from any host\n- ✅ **Downstream export** — Use as a Zig package via `build.zig.zon`, exposes `pub const build_helpers` for downstream kernel compilation\n- ✅ **Built-in testing** — comptime-verifiable unit tests, `zig build test` with no external test framework\n\n## Quick Start\n\n### Prerequisites\n\n- **Zig** 0.16.0-dev.2535+b5bd49460\n- **CUDA Toolkit 12.x** (with `nvcc`, `libcuda`, `libcudart`, `libnvrtc`)\n- **cuDNN 9.x** (optional, for `cudnn` module)\n- **NVIDIA GPU** with Compute Capability 7.0+ (Volta and later)\n\n### Build \u0026 Test\n\n```bash\ngit clone https://github.com/coderonion/zcuda\ncd zcuda\n\nzig build                                    # Build library (driver + nvrtc + cublas + curand)\nzig build test                               # Run all tests (unit + integration)\nzig build test-unit                          # Unit tests only\nzig build test-integration                   # Integration tests only\n\n# Enable optional modules\nzig build -Dcudnn=true -Dcusolver=true\n\n# All modules\nzig build -Dcublas=true -Dcublaslt=true -Dcurand=true -Dcudnn=true \\\n          -Dcusolver=true -Dcusparse=true -Dcufft=true -Dnvtx=true\n```\n\n### Basic Usage\n\n```zig\nconst std = @import(\"std\");\nconst cuda = @import(\"zcuda\");\n\npub fn main() !void {\n    const allocator = std.heap.page_allocator;\n\n    // Create a CUDA context on device 0\n    const ctx = try cuda.driver.CudaContext.new(0);\n    defer ctx.deinit();\n\n    const stream = ctx.defaultStream();\n\n    // Allocate and transfer data\n    const host_data = [_]f32{ 1.0, 2.0, 3.0, 4.0 };\n    const dev_data = try stream.cloneHtoD(f32, \u0026host_data);\n    defer dev_data.deinit();\n\n    // Compile and launch a kernel\n    const ptx = try cuda.nvrtc.compilePtx(allocator,\n        \\\\extern \"C\" __global__ void add1(float *data, int n) {\n        \\\\    int i = blockIdx.x * blockDim.x + threadIdx.x;\n        \\\\    if (i \u003c n) data[i] += 1.0f;\n        \\\\}\n    );\n    defer allocator.free(ptx);\n\n    const module = try ctx.loadModule(ptx);\n    defer module.deinit();\n    const kernel = try module.getFunction(\"add1\");\n\n    try stream.launch(kernel, cuda.LaunchConfig.forNumElems(4),\n        .{ \u0026dev_data, @as(i32, 4) });\n    try stream.synchronize();\n\n    // Read back results\n    var result: [4]f32 = undefined;\n    try stream.memcpyDtoH(f32, \u0026result, dev_data);\n    // result = { 2.0, 3.0, 4.0, 5.0 }\n}\n```\n\n## 📦 Use as Zig Package\n\nAdd zCUDA as a dependency — CUDA library linking, kernel compilation, and bridge generation are all handled automatically.\n\n\u003e [!TIP]\n\u003e **[`zcuda-demo`](https://github.com/coderonion/zcuda-demo)** is a fully worked reference project that imports zcuda as a local package.\n\u003e It covers NVRTC JIT, pure Zig GPU kernels (bridge module), cuBLAS SGEMM, cross-validation, and performance benchmarking.\n\u003e Clone it alongside `zcuda` to see a complete, runnable example of every step below:\n\u003e ```bash\n\u003e git clone https://github.com/coderonion/zcuda\n\u003e git clone https://github.com/coderonion/zcuda-demo\n\u003e cd zcuda-demo \u0026\u0026 zig build run -Dgpu-arch=sm_86\n\u003e # → ✓ All correctness checks PASSED (Sections 1–4)\n\u003e ```\n\n### Step 1: Add dependency to `build.zig.zon`\n\n**Local path (for development):**\n\n```zig\n.dependencies = .{\n    .zcuda = .{\n        .path = \"../zcuda\",\n    },\n},\n```\n\n**Git URL (for release):**\n\n```zig\n.dependencies = .{\n    .zcuda = .{\n        .url = \"https://github.com/coderonion/zcuda/archive/v0.1.0.tar.gz\",\n        .hash = \"HASH_VALUE\",\n    },\n},\n```\n\n\u003e [!TIP]\n\u003e **How to get the hash:** Add `.url` without `.hash`, then run `zig build`. Zig will display the correct hash in the error output — copy it into your `build.zig.zon`.\n\n### Step 2: Configure `build.zig`\n\nA typical `build.zig` has three parts: **1. import zcuda**, **2. discover \u0026 compile kernels**, **3. wire everything to your executable**.\n\n#### 1. Import zcuda dependency\n\n**Option A — Simple (hardcoded flags):**\n\n```zig\nconst zcuda = b.dependency(\"zcuda\", .{\n    .target    = target,\n    .optimize  = optimize,\n    .cublas    = true,   // cuBLAS     (default: true)\n    .cublaslt  = true,   // cuBLAS LT  (default: true)\n    .curand    = true,   // cuRAND     (default: true)\n    .nvrtc     = true,   // NVRTC      (default: true)\n    .cudnn     = false,  // cuDNN      (default: false)\n    .cusolver  = false,  // cuSOLVER   (default: false)\n    .cusparse  = false,  // cuSPARSE   (default: false)\n    .cufft     = false,  // cuFFT      (default: false)\n    .cupti     = false,  // CUPTI      (default: false)\n    .cufile    = false,  // cuFile     (default: false)\n    .nvtx      = false,  // NVTX       (default: false)\n    // .@\"cuda-path\" = \"/usr/local/cuda\",  // optional: override auto-detect\n});\n```\n\n**Option B — Dynamic (forward to CLI):**\n\nExpose zcuda flags as your project's build options, so users can toggle modules at build time:\n\n```zig\nconst enable_cublas   = b.option(bool, \"cublas\",   \"Enable cuBLAS\")   orelse true;\nconst enable_cublaslt = b.option(bool, \"cublaslt\", \"Enable cuBLAS LT\") orelse true;\nconst enable_curand   = b.option(bool, \"curand\",   \"Enable cuRAND\")   orelse true;\nconst enable_nvrtc    = b.option(bool, \"nvrtc\",    \"Enable NVRTC\")    orelse true;\nconst enable_cudnn    = b.option(bool, \"cudnn\",    \"Enable cuDNN\")    orelse false;\nconst enable_cusolver = b.option(bool, \"cusolver\", \"Enable cuSOLVER\") orelse false;\nconst enable_cusparse = b.option(bool, \"cusparse\", \"Enable cuSPARSE\") orelse false;\nconst enable_cufft    = b.option(bool, \"cufft\",    \"Enable cuFFT\")    orelse false;\nconst enable_nvtx     = b.option(bool, \"nvtx\",     \"Enable NVTX\")    orelse false;\nconst cuda_path       = b.option([]const u8, \"cuda-path\", \"Path to CUDA installation (default: auto-detect)\");\n\nconst zcuda = b.dependency(\"zcuda\", .{\n    .target    = target,\n    .optimize  = optimize,\n    .cublas    = enable_cublas,\n    .cublaslt  = enable_cublaslt,\n    .curand    = enable_curand,\n    .nvrtc     = enable_nvrtc,\n    .cudnn     = enable_cudnn,\n    .cusolver  = enable_cusolver,\n    .cusparse  = enable_cusparse,\n    .cufft     = enable_cufft,\n    .nvtx      = enable_nvtx,\n    .@\"cuda-path\" = cuda_path,\n});\n```\n\n#### 2. Set up GPU architecture target\n\n`build_helpers` provides ready-made helpers so you don't need to copy GPU arch\nboilerplate into every downstream project:\n\n```zig\nconst bridge    = @import(\"zcuda\").build_helpers;\nconst gpu_arch  = b.option([]const u8, \"gpu-arch\", \"Target GPU SM arch (default: sm_80)\") orelse \"sm_80\";\nconst embed_ptx = b.option(bool, \"embed-ptx\", \"Embed PTX in binary\") orelse false;\n\n// Resolve nvptx64 target from \"sm_XX\" string (one call, no boilerplate)\nconst nvptx_target = bridge.resolveNvptxTarget(b, gpu_arch);\n\n// Create the GPU-side device intrinsics module (compiled for nvptx64, not the host)\n// sm_version build_options and internal paths are handled automatically\nconst device_mod = bridge.makeDeviceModule(b, zcuda_dep, nvptx_target, gpu_arch);\n```\n\nSupported SM versions: `sm_52`, `sm_60`, `sm_70`, `sm_75`, `sm_80`, `sm_86`, `sm_89`, `sm_90`, `sm_100`.\n\n#### 3. Discover \u0026 compile GPU kernels\n\n```zig\nconst kernel_step = b.step(\"compile-kernels\", \"Compile Zig GPU kernels to PTX\");\nconst kernel_dir  = b.option([]const u8, \"kernel-dir\",\n    \"Root dir for kernel discovery (default: src/kernel/)\") orelse \"src/kernel/\";\n\n// Recursively scan kernel directory for .zig files containing `export fn`\nconst kernels = bridge.discoverKernels(b, kernel_dir);\n\n// Compile Zig → PTX + generate type-safe bridge modules\nconst result = bridge.addBridgeModules(b, kernels, .{\n    .embed_ptx        = embed_ptx,\n    .zcuda_bridge_mod = zcuda_dep.module(\"zcuda_bridge\"),\n    .zcuda_mod        = zcuda_dep.module(\"zcuda\"),\n    .device_mod       = device_mod,\n    .nvptx_target     = nvptx_target,\n    .kernel_step      = kernel_step,\n    .target           = target,\n    .optimize         = optimize,\n});\n```\n\n#### 4. Create executable + wire imports\n\n```zig\nconst exe = b.addExecutable(.{\n    .name = \"my_app\",\n    .root_module = b.createModule(.{\n        .root_source_file = b.path(\"src/main.zig\"),\n        .target   = target,\n        .optimize = optimize,\n    }),\n});\n\nexe.root_module.addImport(\"zcuda\", zcuda_dep.module(\"zcuda\"));\n\n// Link libc + CUDA libraries.\n// Zig 0.16.0-dev does not propagate mod.linkSystemLibrary to downstream exe,\n// so these must match the flags you passed to b.dependency(\"zcuda\", ...).\nexe.root_module.link_libc = true;\nexe.root_module.linkSystemLibrary(\"cuda\",   .{});\nexe.root_module.linkSystemLibrary(\"cudart\", .{});\n// Add libraries matching your enabled dependency flags, e.g.:\n// if (enable_nvrtc)    exe.root_module.linkSystemLibrary(\"nvrtc\",    .{});\n// if (enable_cublas)   exe.root_module.linkSystemLibrary(\"cublas\",   .{});\n// if (enable_cublaslt) exe.root_module.linkSystemLibrary(\"cublasLt\", .{});\n// if (enable_curand)   exe.root_module.linkSystemLibrary(\"curand\",   .{});\n\n// Mount kernel bridge modules (choose one):\n//\n// Option A — Mount all (single-exe projects):\nfor (result.modules) |entry| {\n    exe.root_module.addImport(entry.name, entry.module);\n    // For disk-mode (non-embedded) PTX, ensure PTX is installed before exe:\n    if (entry.install_step) |s| b.getInstallStep().dependOn(s);\n}\n//\n// Option B — Selective (multi-exe projects):\n// if (bridge.findBridge(result.modules, \"my_kernel\")) |mod| {\n//     exe.root_module.addImport(\"my_kernel\", mod);\n// }\n\nb.installArtifact(exe);\n\nconst run_cmd = b.addRunArtifact(exe);\nrun_cmd.step.dependOn(b.getInstallStep());\nb.step(\"run\", \"Build and run\").dependOn(\u0026run_cmd.step);\n```\n\n\u003e [!NOTE]\n\u003e **`linkSystemLibrary` is not auto-propagated** in Zig 0.16.0-dev.\n\u003e You must call `linkSystemLibrary` on your `exe` for each library you enabled in\n\u003e `b.dependency(\"zcuda\", ...)`. Using **Option B** (flag-forwarding) lets you keep\n\u003e these in sync automatically:\n\u003e ```zig\n\u003e if (enable_cublas) exe.root_module.linkSystemLibrary(\"cublas\", .{});\n\u003e ```\n\n\u003e [!TIP]\n\u003e **Mount all** adds every discovered kernel bridge — ideal for single-app projects.\n\u003e **Selective** uses `findBridge()` to pick specific kernels — useful when multiple executables each need different kernels.\n\n### Step 3: Write your code\n\n#### GPU kernel (`zcuda_kernel`)\n\nCreate `.zig` files anywhere under your kernel directory. Import `zcuda_kernel` for the full device-side API:\n\n```zig\n// kernels/my_kernel.zig\nconst cuda = @import(\"zcuda_kernel\");\n\nexport fn myAdd(\n    A: [*]const f32, B: [*]const f32, C: [*]f32, n: u32,\n) callconv(.kernel) void {\n    const i = cuda.blockIdx().x * cuda.blockDim().x + cuda.threadIdx().x;\n    if (i \u003c n) C[i] = A[i] + B[i];\n}\n```\n\n\u003e [!NOTE]\n\u003e Detection is **content-based**: any `.zig` file containing `export fn` is auto-recognized as a kernel. No naming conventions or manual registration required.\n\n**`zcuda_kernel` API quick reference** — naming matches CUDA C++ for seamless migration:\n\n| Category | Zig (`zcuda_kernel`) | CUDA C++ Equivalent |\n|---|---|---|\n| **Thread Indexing** | `cuda.threadIdx()`, `cuda.blockIdx()`, `cuda.blockDim()`, `cuda.gridDim()` | `threadIdx.x`, `blockIdx.x`, `blockDim.x`, `gridDim.x` |\n| **Synchronization** | `cuda.__syncthreads()`, `cuda.__threadfence()`, `cuda.__syncwarp(mask)` | `__syncthreads()`, `__threadfence()`, `__syncwarp()` |\n| **Atomics** | `cuda.atomicAdd(ptr, val)`, `atomicCAS`, `atomicExch`, `atomicMin/Max`, `atomicAnd/Or/Xor`, `atomicInc/Dec` | `atomicAdd()`, `atomicCAS()`, etc. |\n| **Warp Shuffle** | `cuda.__shfl_sync(mask, val, src, w)`, `__shfl_down_sync`, `__shfl_up_sync`, `__shfl_xor_sync` | `__shfl_sync()`, `__shfl_down_sync()`, etc. |\n| **Warp Vote** | `cuda.__ballot_sync(mask, pred)`, `__all_sync`, `__any_sync`, `__activemask()` | `__ballot_sync()`, `__all_sync()`, etc. |\n| **Warp Reduce** *(sm_80+)* | `cuda.__reduce_add_sync(mask, val)`, `__reduce_min/max/and/or/xor_sync` | `__reduce_add_sync()`, etc. |\n| **Fast Math** | `cuda.__sinf(x)`, `__cosf`, `__expf`, `__logf`, `__log2f`, `rsqrtf`, `sqrtf`, `__fmaf_rn`, `__powf` | `__sinf()`, `__cosf()`, etc. |\n| **Integer** | `cuda.__clz(x)`, `__popc`, `__brev`, `__ffs`, `__byte_perm`, `__dp4a` | `__clz()`, `__popc()`, etc. |\n| **Cache Hints** | `cuda.__ldg(ptr)`, `__ldca`, `__ldcs`, `__ldcg`, `__stcg`, `__stcs`, `__stwb` | `__ldg()`, etc. |\n| **Shared Memory** | `cuda.shared_mem.SharedArray(f32, 256)`, `.dynamicShared(f32)`, `.reduceSum(...)` | `__shared__ float tile[256]`, `extern __shared__` |\n| **Tensor Cores** *(sm_70+)* | `cuda.tensor_core.wmma_mma_f16_f32(a, b, c)`, `mma_f16_f32`, `mma_bf16_f32`, `mma_tf32_f32` | `wmma::mma_sync()`, `mma` PTX |\n| **Debug** | `cuda.debug.assertf(cond)`, `.assertInBounds(i, n)`, `.CycleTimer`, `ErrorFlag` | `assert()`, `__trap()` |\n| **Shared Types** | `cuda.shared.Vec2/Vec3/Vec4`, `.Matrix3x3`, `.Matrix4x4` | `float2/float3/float4` |\n| **Clock** | `cuda.clock()`, `cuda.clock64()`, `cuda.globaltimer()` | `clock()`, `clock64()` |\n| **Misc** | `cuda.warpSize` (32), `cuda.FULL_MASK`, `cuda.SM`, `cuda.__nanosleep(ns)` | `warpSize`, `__nanosleep()` |\n\n**Kernel examples:**\n\n```zig\nconst cuda = @import(\"zcuda_kernel\");\n\n// ── Vector addition ──\nexport fn vectorAdd(A: [*]const f32, B: [*]const f32, C: [*]f32, n: u32) callconv(.kernel) void {\n    const i = cuda.blockIdx().x * cuda.blockDim().x + cuda.threadIdx().x;\n    if (i \u003c n) C[i] = A[i] + B[i];\n}\n```\n\n#### Host application\n\nUse zcuda bindings + kernel bridge together:\n\n```zig\n// src/main.zig\nconst std = @import(\"std\");\nconst cuda = @import(\"zcuda\");          // zcuda binding API\nconst my_kernel = @import(\"my_kernel\"); // type-safe kernel bridge\n\npub fn main() !void {\n    // ── Driver API (from zcuda bindings) ──\n    var ctx = try cuda.driver.CudaContext.new(0);\n    defer ctx.deinit();\n    var stream = try ctx.newStream();\n    defer stream.deinit();\n\n    // ── Allocate GPU memory ──\n    const n: u32 = 1024;\n    var d_a = try stream.alloc(f32, n);\n    defer d_a.deinit();\n    var d_b = try stream.alloc(f32, n);\n    defer d_b.deinit();\n    var d_c = try stream.alloc(f32, n);\n    defer d_c.deinit();\n\n    // ── Load kernel (auto-detects embedded PTX vs disk file) ──\n    const module = try my_kernel.load(ctx);\n    defer module.deinit();\n\n    // Function names are compile-time enums — typos cause build errors!\n    const func = try my_kernel.getFunction(module, .myAdd);\n\n    // ── Launch kernel ──\n    try stream.launch(func,\n        cuda.LaunchConfig.forNumElems(n),\n        .{ d_a.ptr, d_b.ptr, d_c.ptr, n },\n    );\n    try stream.synchronize();\n\n    // ── Read back results ──\n    var result: [1024]f32 = undefined;\n    try stream.memcpyDtoH(f32, \u0026result, d_c);\n}\n```\n\n#### Using CUDA C++ kernels (`.cu` files)\n\nzCUDA fully supports existing CUDA C++ kernels — you don't need to rewrite anything in Zig. There are three ways to integrate C++ kernels:\n\n**Way 1 — NVRTC JIT compilation (inline C++ source):**\n\nEmbed CUDA C++ source as a string in Zig and compile at runtime via NVRTC. Best for small kernels or rapid prototyping:\n\n```zig\nconst std = @import(\"std\");\nconst cuda = @import(\"zcuda\");\n\npub fn main() !void {\n    const allocator = std.heap.page_allocator;\n\n    var ctx = try cuda.driver.CudaContext.new(0);\n    defer ctx.deinit();\n    const stream = ctx.defaultStream();\n\n    // ── Existing CUDA C++ kernel, used as-is ──\n    const cuda_cpp_source =\n        \\\\extern \"C\" __global__ void saxpy(float a, float *x, float *y, int n) {\n        \\\\    int i = blockIdx.x * blockDim.x + threadIdx.x;\n        \\\\    if (i \u003c n) y[i] = a * x[i] + y[i];\n        \\\\}\n    ;\n\n    // JIT compile C++ → PTX at runtime\n    const ptx = try cuda.nvrtc.compilePtx(allocator, cuda_cpp_source);\n    defer allocator.free(ptx);\n\n    const module = try ctx.loadModule(ptx);\n    defer module.deinit();\n    const kernel = try module.getFunction(\"saxpy\");\n\n    // Allocate + launch, same API as Zig kernels\n    const n: u32 = 1024;\n    var d_x = try stream.alloc(f32, n);\n    defer d_x.deinit();\n    var d_y = try stream.alloc(f32, n);\n    defer d_y.deinit();\n\n    try stream.launch(kernel, cuda.LaunchConfig.forNumElems(n),\n        .{ @as(f32, 2.0), d_x.ptr, d_y.ptr, @as(i32, @intCast(n)) });\n    try stream.synchronize();\n}\n```\n\n**Way 2 — NVRTC JIT compilation (read `.cu` file from disk):**\n\nLoad an existing `.cu` file and JIT compile it. Perfect for reusing large, mature C++ kernel libraries:\n\n```zig\n// Read existing .cu file — no modification needed\nconst cu_source = @embedFile(\"kernels/matmul_optimized.cu\");\n\n// Or load at runtime from any path:\n// const cu_source = try std.fs.cwd().readFileAlloc(allocator, \"vendor/kernels/matmul.cu\", 1024 * 1024);\n// defer allocator.free(cu_source);\n\nconst ptx = try cuda.nvrtc.compilePtx(allocator, cu_source);\ndefer allocator.free(ptx);\n\nconst module = try ctx.loadModule(ptx);\ndefer module.deinit();\nconst kernel = try module.getFunction(\"matmul_optimized\");\n\n// Launch with the same zcuda API\ntry stream.launch(kernel, .{ .grid = .{ .x = grid_x, .y = grid_y }, .block = .{ .x = 16, .y = 16 } },\n    .{ d_A.ptr, d_B.ptr, d_C.ptr, @as(i32, @intCast(N)) });\n```\n\n**Way 3 — Pre-compiled PTX (offline `nvcc` compilation):**\n\nUse `nvcc` to compile `.cu` → `.ptx` offline, then load the PTX in Zig. Best for production or when you need `nvcc`-specific flags:\n\n```bash\n# Compile with nvcc (your existing build pipeline)\nnvcc -ptx -arch=sm_80 -o matmul.ptx matmul.cu\n```\n\n```zig\n// Load pre-compiled PTX at build time (embed in binary)\nconst ptx = @embedFile(\"matmul.ptx\");\nconst module = try ctx.loadModule(ptx);\ndefer module.deinit();\nconst kernel = try module.getFunction(\"matmul\");\n\n// Same launch API — it's all PTX under the hood\ntry stream.launch(kernel, config, .{ d_A.ptr, d_B.ptr, d_C.ptr, @as(i32, @intCast(N)) });\n```\n\n\u003e [!TIP]\n\u003e **Migration strategy**: Start by wrapping your existing C++ kernels with Way 1 or 2 — zero rewrite needed. Then gradually port performance-critical kernels to pure Zig (Step 3 above) and enjoy compile-time type safety and `zig build` integration. Both C++ and Zig kernels produce PTX, both use the same `stream.launch()` API, and both can coexist in the same project.\n\n### Step 4: Build \u0026 Run\n\n#### Common commands\n\n```bash\nzig build                    # Build with defaults (driver + nvrtc + cublas + curand)\nzig build run                # Build \u0026 run your application\nzig build test               # Run all tests\n```\n\n#### CUDA module flags\n\nEnable/disable CUDA library bindings at build time. These flags control which libraries get linked:\n\n| Flag | Default | Module | Description |\n|------|---------|--------|-------------|\n| `-Dcublas=BOOL` | `true` | **cuBLAS** | BLAS Level 1/2/3 (SAXPY, SGEMM, DGEMM, etc.) |\n| `-Dcublaslt=BOOL` | `true` | **cuBLAS LT** | Lightweight GEMM with algorithm heuristics |\n| `-Dcurand=BOOL` | `true` | **cuRAND** | GPU random number generation |\n| `-Dnvrtc=BOOL` | `true` | **NVRTC** | Runtime kernel compilation |\n| `-Dcudnn=BOOL` | `false` | **cuDNN** | Convolution, activation, pooling, softmax, batch norm |\n| `-Dcusolver=BOOL` | `false` | **cuSOLVER** | LU, QR, SVD, Cholesky, eigenvalue decomposition |\n| `-Dcusparse=BOOL` | `false` | **cuSPARSE** | SpMV, SpMM, SpGEMM with CSR/COO formats |\n| `-Dcufft=BOOL` | `false` | **cuFFT** | 1D/2D/3D Fast Fourier Transform |\n| `-Dcupti=BOOL` | `false` | **CUPTI** | Profiling and tracing via CUDA Profiling Tools Interface |\n| `-Dcufile=BOOL` | `false` | **cuFile** | GPUDirect Storage for direct GPU↔storage I/O |\n| `-Dnvtx=BOOL` | `false` | **NVTX** | Profiling annotations for Nsight |\n\n\u003e **Driver API** is always enabled (no flag needed).\n\n```bash\nzig build                                  # defaults (cublas + cublaslt + curand + nvrtc)\nzig build -Dcudnn=true -Dcusolver=true     # add cuDNN + cuSOLVER\nzig build -Dcublas=false                   # disable cuBLAS\nzig build -Dcublas=true -Dcudnn=true -Dcufft=true  # multi-module combo\n```\n\n#### GPU kernel flags\n\nControl kernel compilation and PTX handling:\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `-Dgpu-arch=ARCH` | `sm_80` | Target GPU architecture (e.g. `sm_75`, `sm_89`, `sm_90`) |\n| `-Dembed-ptx=BOOL` | `false` | Embed PTX in binary — no `.ptx` files needed at runtime |\n| `-Dkernel-dir=PATH` | `src/kernel/` | Root directory for kernel auto-discovery |\n\n```bash\nzig build compile-kernels                     # Compile all Zig kernels to PTX\nzig build kernel-my_kernel                    # Compile single kernel only\nzig build compile-kernels -Dgpu-arch=sm_80    # Target Ampere GPUs\nzig build -Dembed-ptx=true                    # Production: PTX baked into binary\nzig build compile-kernels -Dkernel-dir=my/kernels/  # Custom Zig kernels location\n```\n\nPTX output: `zig-out/bin/kernel/*.ptx`\n\n#### Path overrides\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `-Dcuda-path=PATH` | auto-detect | Path to CUDA toolkit installation |\n| `-Dkernel-dir=PATH` | `src/kernel/` | Root directory for kernel auto-discovery |\n\n\u003e **💡 Combining flags**: Module flags and kernel flags are orthogonal — use them together freely:\n\u003e ```bash\n\u003e zig build compile-kernels -Dgpu-arch=sm_80 -Dcublas=true -Dcufft=true -Dembed-ptx=true\n\u003e ```\n\n## Examples\n\n### Host Examples (58 files, 74 build targets)\n\nWorking host-side examples in the [`examples/`](examples/) directory. See [examples/README.md](examples/README.md) for the full categorized index.\n\n```bash\n# Build and run\nzig build run-basics-vector_add\nzig build run-cublas-gemm\nzig build run-cusolver-gesvd -Dcusolver=true\nzig build run-cudnn-conv2d -Dcudnn=true\nzig build run-cufft-fft_2d -Dcufft=true\n```\n\n| Category      | Count | Examples                                  | What You'll Learn                             |\n| ------------- | ----- | ----------------------------------------- | --------------------------------------------- |\n| **Basics**    | 16    | vector_add, streams, device_info, alloc_patterns, async_memcpy, pinned_memory, unified_memory, … | Contexts, streams, events, kernels, multi-GPU, memory patterns |\n| **cuBLAS**    | 19    | gemm, axpy, trsm, cosine_similarity, gemm_batched, gemm_ex, dgmm, … | L1/L2/L3 BLAS, batched GEMM, mixed-precision  |\n| **cuDNN**     | 3     | conv2d, activation, pooling_softmax       | Neural network primitives                     |\n| **cuFFT**     | 4     | fft_1d_c2c, fft_2d, fft_3d, fft_1d_r2c    | 1D/2D/3D FFT, filtering                       |\n| **cuRAND**    | 3     | distributions, generators, monte_carlo_pi | RNG types, Monte Carlo                        |\n| **cuSOLVER**  | 5     | getrf, gesvd, potrf, syevd, geqrf         | LU, SVD, Cholesky, QR, eigensolve             |\n| **cuSPARSE**  | 4     | spmv_csr, spmm_csr, spmv_coo, spgemm      | CSR/COO SpMV, SpMM, SpGEMM                    |\n| **cuBLAS LT** | 1     | lt_sgemm                                  | GEMM with algorithm heuristics                |\n| **NVRTC**     | 2     | jit_compile, template_kernel              | Runtime compilation                           |\n| **NVTX**      | 1     | profiling                                 | Nsight annotations                            |\n\n### Kernel Examples (80 files, 11 categories)\n\nGPU kernel source files in [`examples/kernel/`](examples/kernel/), organized by difficulty and feature:\n\n| Category | Count | Kernels | Features Demonstrated |\n| -------- | ----- | ------- | --------------------- |\n| **0_Basic** | 8 | vector_add, saxpy, grid_stride, dot_product, relu, scale_bias, residual_norm, vec3_normalize | Thread indexing, grid-stride loops, elementwise ops |\n| **1_Reduction** | 5 | reduce_sum, reduce_warp, reduce_multiblock, prefix_sum, scalar_product | Parallel reduction patterns |\n| **2_Matrix** | 6 | matmul_naive, matmul_tiled, matvec, transpose, extract_diag, pad_2d | Matrix operations, tiling, 2D indexing |\n| **3_Atomics** | 5 | histogram, histogram_256bin, atomic_ops, system_atomics, warp_aggregated_atomics | Atomic operations, histogramming |\n| **4_SharedMemory** | 3 | shared_mem_demo, dynamic_smem, stencil_1d | Static/dynamic shared memory, stencils |\n| **5_Warp** | 5 | warp shuffle, vote, reduce, ballot, cooperative | Warp-level primitives |\n| **6_MathAndTypes** | 8 | fast_math, half_precision, integer_intrinsics, type_conversion, sigmoid, signal_gen, complex_mul, freq_filter | Math intrinsics, type conversion, signal processing |\n| **7_Debug** | 2 | debug kernels | Debug assertions, error flags |\n| **8_TensorCore** | 6 | WMMA GEMM, fragment ops | Tensor core operations (sm_70+) |\n| **9_Advanced** | 8 | softmax, async_copy, cooperative_groups, thread_fence, gbm_paths, particle_init/step, intrinsics_coverage | Advanced patterns, simulation |\n| **10_Integration** | 24 | Driver lifecycle, streams, CUDA graphs, cuBLAS pipelines, cuFFT pipelines, cuRAND apps, end-to-end, tensor core pipelines, **perf benchmark (Zig vs cuBLAS)** | Multi-library integration, end-to-end workflows, performance comparison |\n\n## Testing\n\n```bash\nzig build test                               # All tests (unit + integration)\nzig build test-unit                          # Unit tests only\nzig build test-integration                   # Integration tests only\n\n# Enable all optional module tests\nzig build test -Dcudnn=true -Dcusolver=true -Dcusparse=true -Dcufft=true -Dnvtx=true\n```\n\n### Test Summary\n\n| Category | Files | Tests | Requires GPU |\n|----------|-------|-------|:---:|\n| **Unit — kernel types** (pure Zig) | 10 | 222 | ❌ |\n| **Unit — core** (driver, runtime, nvrtc) | 4 | — | ✅ |\n| **Unit — conditional** (cublas, cudnn, etc.) | 8 | — | ✅ |\n| **Integration — core** | 10 | — | ✅ |\n| **Integration — kernel GPU** | 7 | — | ✅ |\n| **Total** | **39** | **222+** | |\n\n\u003e [!NOTE]\n\u003e **222 pure-Zig tests** verify kernel DSL types, compile-time logic, and memory layouts — they run on any machine without CUDA.\n\u003e GPU-dependent tests require CUDA libraries and will fail to link on macOS or systems without CUDA installed.\n\n### Test Architecture\n\nThe 10 kernel type test files (`test/unit/kernel/`) test **pure Zig data structures** that don't call any CUDA APIs:\n\n- `kernel_shared_types_test` — Vec2/3/4, Matrix, LaunchConfig struct layout\n- `kernel_types_test` — SharedMemory type tag validation\n- `kernel_arch_test` — SM architecture enum \u0026 feature tables\n- `kernel_device_types_test` — DevicePtr, GridStrideIterator struct verification\n- `kernel_debug_test` — Printf format string compile-time logic\n- `kernel_shared_mem_test` — SharedMemory compile-time meta-info\n- `kernel_intrinsics_host_test` — Intrinsic function signatures \u0026 type inference\n- `kernel_tensor_core_host_test` — WMMA fragment type definitions\n- `kernel_grid_stride_test` — GridStrideIterator field validation\n- `kernel_device_test` — Device pointer load/store patterns\n\n## Architecture\n\nEach module follows a consistent three-layer design:\n\n```\n┌──────────────────────────────────────────────┐\n│  Safe Layer (safe.zig)                       │  ← Recommended API\n│  Type-safe abstractions, RAII, Zig idioms    │\n├──────────────────────────────────────────────┤\n│  Result Layer (result.zig)                   │  ← Error wrapping\n│  C error codes → Zig error unions            │\n├──────────────────────────────────────────────┤\n│  Sys Layer (sys.zig)                         │  ← Raw FFI\n│  Direct @cImport of C headers               │\n└──────────────────────────────────────────────┘\n```\n\n### Project Structure\n\n```\nzcuda/\n├── src/                           # Zig API layer (11 modules)\n│   ├── cuda.zig                   # Root module — re-exports all modules\n│   ├── types.zig                  # Shared types (Dim3, LaunchConfig, DevicePtr)\n│   ├── driver/                    # CUDA Driver API (sys, result, safe)\n│   ├── nvrtc/                     # NVRTC (runtime compilation)\n│   ├── kernel/                    # GPU Kernel DSL (pure Zig → PTX, no CUDA C++ needed)\n│   │   ├── device.zig             #   Module root (re-exports all sub-modules)\n│   │   ├── types.zig              #   DeviceSlice(T), DevicePtr(T), GridStrideIterator\n│   │   ├── shared_types.zig       #   Vec2/3/4, Int2/3, Matrix3x3/4x4, LaunchConfig\n│   │   ├── arch.zig               #   SmVersion enum, requireSM comptime guard\n│   │   ├── intrinsics.zig         #   98 inline fns: threadIdx, atomics, warp, math, cache\n│   │   ├── shared_mem.zig         #   SharedArray(T,N), dynamicShared, cooperative utils\n│   │   ├── tensor_core.zig        #   56 inline fns: WMMA/MMA/wgmma/TMA/cluster/tcgen05\n│   │   ├── bridge_gen.zig         #   Type-safe kernel bridge (Fn enum, load, getFunction)\n│   │   └── debug.zig              #   assertf, ErrorFlag, printf, CycleTimer, __trap\n│   └── ...                        # 8 more binding modules (cublas, cudnn, ...)\n├── examples/                      # 58 host-side examples\n│   ├── basics/                    #   16 fundamentals (vector_add, streams, ...)\n│   ├── cublas/                    #   19 BLAS examples\n│   ├── cudnn/                     #   3 neural network examples\n│   ├── cufft/                     #   4 FFT examples\n│   ├── curand/                    #   3 RNG examples\n│   ├── cusolver/                  #   5 linear algebra examples\n│   ├── cusparse/                  #   4 sparse matrix examples\n│   ├── cublaslt/                  #   1 LT GEMM example\n│   ├── nvrtc/                     #   2 JIT compilation examples\n│   ├── nvtx/                      #   1 profiling example\n│   └── kernel/                    #   79 GPU kernel source files\n│       ├── 0_Basic/               #     8 basic kernels\n│       ├── 1_Reduction/           #     5 reduction kernels\n│       ├── 2_Matrix/              #     6 matrix kernels\n│       ├── 3_Atomics/             #     5 atomic kernels\n│       ├── 4_SharedMemory/        #     3 shared memory kernels\n│       ├── 5_Warp/                #     5 warp-level kernels\n│       ├── 6_MathAndTypes/        #     8 math/type kernels\n│       ├── 7_Debug/               #     2 debug kernels\n│       ├── 8_TensorCore/          #     6 tensor core kernels\n│       ├── 9_Advanced/            #     8 advanced kernels\n│       └── 10_Integration/        #     24 integration host examples\n├── test/                          # 39 test files\n│   ├── unit/                      #   12 core unit tests\n│   │   └── kernel/                #   10 kernel type tests (pure Zig, no GPU)\n│   └── integration/               #   10 core integration tests\n│       └── kernel/                #   7 kernel GPU integration tests\n├── docs/                          # Comprehensive API documentation\n├── build.zig                      # Build configuration + pub const build_helpers\n├── build_helpers.zig              # Kernel discovery, PTX compilation, bridge generation\n├── build.zig.zon                  # Package manifest\n└── BUG_TRACKER.md                 # Known issues and fixes\n```\n\n\u003e **Users should only use the Safe Layer.** The `result` and `sys` layers are implementation details — all public types and functions are re-exported from each module's top-level file.\n\n## Build System\n\nThe build system (`build.zig` + `build_helpers.zig`) provides:\n\n- **Auto-detection**: CUDA installation path discovery across common locations\n- **Modular linking**: Only link libraries you enable via `-D` flags\n- **Kernel pipeline**: `discoverKernels()` → content-based scan → `addBridgeModules()` → Zig→PTX compilation + type-safe bridge generation\n- **Downstream export**: `pub const build_helpers = @import(\"build_helpers.zig\")` — downstream packages access via `@import(\"zcuda\").build_helpers`\n- **Configurable paths**: `-Dkernel-dir`, `-Dcuda-path`, `-Dgpu-arch`, `-Dembed-ptx`\n\n## Documentation\n\nComprehensive documentation is available in the [`docs/`](docs/) directory:\n\n- **[Documentation Index](docs/README.md)** — Full navigation guide\n- **[API Reference](docs/API.md)** — Complete safe-layer API for all binding modules + Kernel DSL overview\n- **[Kernel DSL API](docs/kernel/API.md)** — Full device-side intrinsics, smem, Tensor Cores, bridge_gen\n- **[CUDA C++ → Zig Migration](docs/kernel/MIGRATION.md)** — Side-by-side migration guide\n- **[Examples](examples/README.md)** — 58 host + 80 kernel examples with build commands\n- **[Project Structure](STRUCTURE.md)** — Source code organization and module overview\n\nEach module has its own detailed README in `docs/\u003cmodule\u003e/README.md`.\n\n## Contributing\n\n1. ⭐ Star and Fork this repository\n2. Create a feature branch (`git checkout -b feature/new-module`)\n3. Implement sys/result/safe layers in `src/\u003cmodule\u003e/`\n4. Add unit tests in `test/unit/` and integration tests in `test/integration/`\n5. Create a host example in `examples/\u003cmodule\u003e/`\n6. Add kernel examples in `examples/kernel/\u003ccategory\u003e/`\n7. Update documentation in `docs/\u003cmodule\u003e/`\n8. Submit a Pull Request\n\n## License\n\nMIT License\n\n## Acknowledgments\n\nBuilt with gratitude on the shoulders of giants:\n\n- **[Zig](https://ziglang.org/)** — A modern systems programming language focused on safety, performance, and simplicity, created by Andrew Kelley and the Zig Software Foundation.\n\n- **[CUDA](https://developer.nvidia.com/cuda-toolkit)** — NVIDIA's parallel computing platform and API, providing the underlying runtime, compiler, and libraries.\n\n- **[cudarc](https://github.com/coreylowman/cudarc)** — A safe Rust wrapper for CUDA whose three-layer architecture (sys → result → safe) served as the foundational reference for this project.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoderonion%2Fzcuda","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoderonion%2Fzcuda","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoderonion%2Fzcuda/lists"}