feat: move to a cuda example

henryiii · henryiii · commit 5a3452ba7f64 · 2026-06-18T18:05:35.000-04:00
Assisted-by: ClaudeCode:claude-opus-4.8
Signed-off-by: Henry Schreiner &lt;henryfs@princeton.edu&gt;
diff --git a/.github/workflows/cibw-cuda.yaml b/.github/workflows/cibw-cuda.yaml
@@ -0,0 +1,45 @@
+name: CIBW CUDA
+
+on:
+  workflow_dispatch:
+  pull_request:
+    branches:
+      - master
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: CUDA ${{ matrix.cuda-version }} wheels on ${{ matrix.target.arch }}
+    runs-on: ${{ matrix.target.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # The CUDA Toolkit lives inside the custom manylinux images below, so
+        # any runner works. See the list of available images at
+        # https://github.com/pypa/cibuildwheel/pull/2896
+        manylinux-base: [manylinux_2_28]
+        cuda-version: [12_9, 13_1]
+        target:
+          - arch: x86_64
+            runner: ubuntu-24.04
+          - arch: aarch64
+            runner: ubuntu-24.04-arm
+
+    steps:
+    - uses: actions/checkout@v6
+
+    - uses: pypa/cibuildwheel@v3.4
+      env:
+        CIBW_BUILD: cp312-manylinux_${{ matrix.target.arch }}
+        CIBW_MANYLINUX_X86_64_IMAGE: >-
+          quay.io/manylinux_cuda/${{ matrix.manylinux-base }}_x86_64_cuda${{ matrix.cuda-version }}:latest
+        CIBW_MANYLINUX_AARCH64_IMAGE: >-
+          quay.io/manylinux_cuda/${{ matrix.manylinux-base }}_aarch64_cuda${{ matrix.cuda-version }}:latest
+
+    - uses: actions/upload-artifact@v7
+      with:
+        name: cibw-cuda-${{ matrix.manylinux-base }}-cuda${{ matrix.cuda-version }}-${{ matrix.target.arch }}
+        path: wheelhouse/*.whl
diff --git a/.github/workflows/conda.yml b/.github/workflows/conda.yml
@@ -38,7 +38,7 @@ jobs:
         run: conda build conda.recipe
 
       - name: Install
-        run: conda install -c ${CONDA_PREFIX}/conda-bld/ scikit_build_example
+        run: conda install -c ${CONDA_PREFIX}/conda-bld/ cuda_example
 
       - name: Test
         run: pytest tests
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -49,15 +49,6 @@ repos:
   - id: remove-tabs
     exclude: ^(docs)
 
-# CMake formatting
-- repo: https://github.com/cheshirekow/cmake-format-precommit
-  rev: v0.6.13
-  hooks:
-  - id: cmake-format
-    additional_dependencies: [pyyaml]
-    types: [file]
-    files: (\.cmake|CMakeLists.txt)(.in)?$
-
 # Suggested hook if you add a .clang-format file
 # - repo: https://github.com/pre-commit/mirrors-clang-format
 #  rev: v13.0.0
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -1,6 +1,6 @@
-# Require CMake 3.15+ (matching scikit-build-core) Use new versions of all
-# policies up to CMake 4.0
-cmake_minimum_required(VERSION 3.15...4.0)
+# Require CMake 3.18+ (matching scikit-build-core and supporting modern CUDA).
+# Use new versions of all policies up to CMake 4.0
+cmake_minimum_required(VERSION 3.18...4.0)
 
 # Scikit-build-core sets these values for you, or you can just hard-code the
 # name and version.
@@ -12,13 +12,37 @@ project(
 # Find pybind11 and Python
 find_package(pybind11 CONFIG REQUIRED)
 
+# Enable CUDA if a compiler (nvcc) is available. This lets the example build
+# everywhere: with the CUDA Toolkit it compiles the real kernel, and without it
+# it falls back to a CPU implementation.
+include(CheckLanguage)
+check_language(CUDA)
+if(CMAKE_CUDA_COMPILER)
+  enable_language(CUDA)
+  message(STATUS "CUDA found: building the GPU implementation")
+  set(ADD_SOURCE src/add.cu)
+else()
+  message(STATUS "CUDA not found: building the CPU fallback")
+  set(ADD_SOURCE src/add_cpu.cpp)
+endif()
+
 # Add a library using FindPython's tooling (pybind11 also provides a helper like
 # this)
-python_add_library(_core MODULE src/main.cpp WITH_SOABI)
+python_add_library(_core MODULE src/main.cpp ${ADD_SOURCE} WITH_SOABI)
 target_link_libraries(_core PRIVATE pybind11::headers)
 
 # This is passing in the version as a define just as an example
 target_compile_definitions(_core PRIVATE VERSION_INFO=${PROJECT_VERSION})
 
+if(CMAKE_CUDA_COMPILER)
+  # Build for all major architectures so the wheel is portable, and link the
+  # CUDA runtime statically so the wheel does not depend on libcudart.
+  if(NOT DEFINED CMAKE_CUDA_ARCHITECTURES)
+    set_property(TARGET _core PROPERTY CUDA_ARCHITECTURES all-major)
+  endif()
+  set_property(TARGET _core PROPERTY CUDA_RUNTIME_LIBRARY Static)
+  target_compile_definitions(_core PRIVATE WITH_CUDA)
+endif()
+
 # The install directory is the output (wheel) directory
-install(TARGETS _core DESTINATION scikit_build_example)
+install(TARGETS _core DESTINATION cuda_example)
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# scikit_build_example
+# cuda_example
 
 [![Gitter][gitter-badge]][gitter-link]
 
@@ -8,42 +8,78 @@
 | pip builds           | [![Pip Actions Status][actions-pip-badge]][actions-pip-link] |
 
 
-An example project built with [pybind11][] and [scikit-build-core][]. Python
-3.9+ (see older commits for 3.7+, or even older versions of Python using [scikit-build (classic)][]).
+An example project built with [pybind11][], [CUDA][], and
+[scikit-build-core][]. Python 3.9+.
+
+The extension exposes a tiny `add` function that runs on the GPU with a CUDA
+kernel when a device is available, and otherwise falls back to the CPU. The
+build is conditional: if the CUDA Toolkit (`nvcc`) is found at configure time,
+the real kernel in `src/add.cu` is compiled; otherwise the CPU implementation in
+`src/add_cpu.cpp` is used. This keeps the example buildable everywhere (macOS,
+Windows, PyPy, Pyodide, ...) while still demonstrating a real CUDA build on
+Linux.
 
 
 [gitter-badge]:            https://badges.gitter.im/pybind/Lobby.svg
 [gitter-link]:             https://gitter.im/pybind/Lobby
-[actions-badge]:           https://github.com/pybind/scikit_build_example/workflows/Tests/badge.svg
-[actions-conda-link]:      https://github.com/pybind/scikit_build_example/actions?query=workflow%3AConda
-[actions-conda-badge]:     https://github.com/pybind/scikit_build_example/workflows/Conda/badge.svg
-[actions-pip-link]:        https://github.com/pybind/scikit_build_example/actions?query=workflow%3APip
-[actions-pip-badge]:       https://github.com/pybind/scikit_build_example/workflows/Pip/badge.svg
-[actions-wheels-link]:     https://github.com/pybind/scikit_build_example/actions?query=workflow%3AWheels
-[actions-wheels-badge]:    https://github.com/pybind/scikit_build_example/workflows/Wheels/badge.svg
+[actions-badge]:           https://github.com/pybind/cuda_example/workflows/Tests/badge.svg
+[actions-conda-link]:      https://github.com/pybind/cuda_example/actions?query=workflow%3AConda
+[actions-conda-badge]:     https://github.com/pybind/cuda_example/workflows/Conda/badge.svg
+[actions-pip-link]:        https://github.com/pybind/cuda_example/actions?query=workflow%3APip
+[actions-pip-badge]:       https://github.com/pybind/cuda_example/workflows/Pip/badge.svg
+[actions-wheels-link]:     https://github.com/pybind/cuda_example/actions?query=workflow%3AWheels
+[actions-wheels-badge]:    https://github.com/pybind/cuda_example/workflows/Wheels/badge.svg
 
 ## Installation
 
 - Clone this repository
-- `pip install ./scikit_build_example`
+- `pip install ./cuda_example`
+
+If the CUDA Toolkit is installed, the GPU implementation is built automatically.
 
 ## Test call
 
 ```python
-import scikit_build_example
+import cuda_example
 
-scikit_build_example.add(1, 2)
+cuda_example.add(1, 2)       # 3 (on the GPU if one is available)
+cuda_example.cuda_available()  # True if a CUDA device is visible at runtime
+cuda_example.WITH_CUDA         # True if the wheel was compiled with CUDA
 ```
 
+## Building CUDA wheels
+
+The default `Wheels` workflow builds the CPU fallback on every platform using
+[cibuildwheel][]. To build CUDA-enabled Linux wheels, the
+`.github/workflows/cibw-cuda.yaml` workflow points cibuildwheel at the custom
+manylinux images that ship the CUDA Toolkit (see
+[pypa/cibuildwheel#2896][cibw-cuda]):
+
+```yaml
+- uses: pypa/cibuildwheel@v3.4
+  env:
+    CIBW_MANYLINUX_X86_64_IMAGE: quay.io/manylinux_cuda/manylinux_2_28_x86_64_cuda13_1:latest
+    CIBW_MANYLINUX_AARCH64_IMAGE: quay.io/manylinux_cuda/manylinux_2_28_aarch64_cuda13_1:latest
+```
+
+The CUDA runtime is linked statically (`CUDA_RUNTIME_LIBRARY Static`), so the
+resulting wheels do not depend on `libcudart` and remain importable on machines
+without a GPU (where `add` transparently falls back to the CPU). GitHub-hosted
+runners have no GPU, so the wheels are compiled and imported, but the kernel
+itself only runs on a machine with a CUDA device.
+
 ## Files
 
 This example has several files that are a good idea, but aren't strictly
 necessary. The necessary files are:
 
 * `pyproject.toml`: The Python project file
-* `CMakeLists.txt`: The CMake configuration file
-* `src/main.cpp`: The source file for the C++ build
-* `src/scikit_build_example/__init__.py`: The Python portion of the module. The root of the module needs to be `<package_name>`, `src/<package_name>`, or `python/<package_name>` to be auto-discovered.
+* `CMakeLists.txt`: The CMake configuration file, which conditionally enables CUDA
+* `src/main.cpp`: The pybind11 bindings
+* `src/add.cu`: The CUDA kernel implementation (built when CUDA is available)
+* `src/add_cpu.cpp`: The CPU fallback (built when CUDA is not available)
+* `src/add.h`: The shared declarations
+* `src/cuda_example/__init__.py`: The Python portion of the module. The root of the module needs to be `<package_name>`, `src/<package_name>`, or `python/<package_name>` to be auto-discovered.
 
 These files are also expected and highly recommended:
 
@@ -71,9 +107,10 @@ choice.
 
 ### CI Examples
 
-There are examples for CI in `.github/workflows`. A simple way to produces
+There are examples for CI in `.github/workflows`. A simple way to produce
 binary "wheels" for all platforms is illustrated in the "wheels.yml" file,
-using [cibuildwheel][].
+using [cibuildwheel][]. The "cibw-cuda.yaml" file shows how to build
+CUDA-enabled wheels on Linux.
 
 ## License
 
@@ -82,11 +119,12 @@ file. By using, distributing, or contributing to this project, you agree to the
 terms and conditions of this license.
 
 [cibuildwheel]: https://cibuildwheel.readthedocs.io
+[cibw-cuda]: https://github.com/pypa/cibuildwheel/pull/2896
+[cuda]: https://developer.nvidia.com/cuda-toolkit
 [scientific-python development guide]: https://learn.scientific-python.org/development
 [dependabot]: https://docs.github.com/en/code-security/dependabot
 [github actions]: https://docs.github.com/en/actions
 [pre-commit]: https://pre-commit.com
 [nox]: https://nox.thea.codes
 [pybind11]: https://pybind11.readthedocs.io
 [scikit-build-core]: https://scikit-build-core.readthedocs.io
-[scikit-build (classic)]: https://scikit-build.readthedocs.io
diff --git a/conda.recipe/meta.yaml b/conda.recipe/meta.yaml
@@ -1,5 +1,5 @@
 package:
-  name: scikit_build_example
+  name: cuda_example
   version: 0.0.1
 
 source:
@@ -22,15 +22,15 @@ requirements:
     - python
     - pip
     - scikit-build-core
-    - pybind11 >=2.10.0
+    - pybind11 >=3.0.0
 
   run:
     - python
 
 
 test:
   imports:
-    - scikit_build_example
+    - cuda_example
   requires:
     - pytest
   source_files:
@@ -39,5 +39,5 @@ test:
     - pytest tests
 
 about:
-  summary: An example project built with pybind11 and scikit-build.
+  summary: An example project built with pybind11, CUDA, and scikit-build-core.
   license_file: LICENSE
diff --git a/docs/conf.py b/docs/conf.py
@@ -49,7 +49,7 @@
 master_doc = 'index'
 
 # General information about the project.
-project = 'python_example'
+project = 'cuda_example'
 copyright = '2016, Sylvain Corlay'
 author = 'Sylvain Corlay'
 
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,5 +1,5 @@
-python_example Documentation
-============================
+cuda_example Documentation
+==========================
 
 Contents:
 
diff --git a/docs/python_example.rst b/docs/python_example.rst
@@ -1 +1 @@
-.. automodule:: scikit_build_example
+.. automodule:: cuda_example
diff --git a/pyproject.toml b/pyproject.toml
@@ -4,11 +4,11 @@ build-backend = "scikit_build_core.build"
 
 
 [project]
-name = "scikit_build_example"
+name = "cuda_example"
 version = "0.0.1"
 license = "MIT"
 license-files = ["LICENSE"]
-description="A minimal example package (with pybind11)"
+description="A minimal example package (with pybind11 and CUDA)"
 readme = "README.md"
 authors = [
   { name = "My Name", email = "me@email.com" },
diff --git a/src/add.cu b/src/add.cu
@@ -0,0 +1,28 @@
+#include "add.h"
+
+#include <cuda_runtime.h>
+
+__global__ void add_kernel(int i, int j, int *result) { *result = i + j; }
+
+bool cuda_available() {
+    int count = 0;
+    cudaError_t status = cudaGetDeviceCount(&count);
+    return status == cudaSuccess && count > 0;
+}
+
+int add(int i, int j) {
+    // No device (e.g. running the CUDA-enabled wheel on a machine without a
+    // GPU): compute on the CPU so the function still works.
+    if (!cuda_available()) {
+        return i + j;
+    }
+
+    int *d_result = nullptr;
+    cudaMalloc(&d_result, sizeof(int));
+    add_kernel<<<1, 1>>>(i, j, d_result);
+
+    int result = 0;
+    cudaMemcpy(&result, d_result, sizeof(int), cudaMemcpyDeviceToHost);
+    cudaFree(d_result);
+    return result;
+}
diff --git a/src/add.h b/src/add.h
@@ -0,0 +1,9 @@
+#pragma once
+
+// Returns true if a CUDA-capable device is present at runtime. Always false
+// when the extension was built without the CUDA Toolkit (CPU fallback).
+bool cuda_available();
+
+// Adds two integers. Uses a CUDA kernel when a device is available, otherwise
+// falls back to a plain CPU addition so the extension is usable everywhere.
+int add(int i, int j);
diff --git a/src/add_cpu.cpp b/src/add_cpu.cpp
@@ -0,0 +1,9 @@
+#include "add.h"
+
+// CPU fallback used when the CUDA Toolkit is not available at build time. This
+// keeps the example buildable on platforms without CUDA (macOS, Windows without
+// the toolkit, PyPy/Pyodide wheels, ...).
+
+bool cuda_available() { return false; }
+
+int add(int i, int j) { return i + j; }
diff --git a/src/cuda_example/__init__.py b/src/cuda_example/__init__.py
@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from ._core import (
+    WITH_CUDA,
+    __doc__,
+    __version__,
+    add,
+    cuda_available,
+    subtract,
+)
+
+__all__ = [
+    "WITH_CUDA",
+    "__doc__",
+    "__version__",
+    "add",
+    "cuda_available",
+    "subtract",
+]
diff --git a/src/cuda_example/__init__.pyi b/src/cuda_example/__init__.pyi
diff --git a/src/main.cpp b/src/main.cpp
diff --git a/src/scikit_build_example/__init__.py b/src/scikit_build_example/__init__.py
diff --git a/src/scikit_build_example/__init__.pyi b/src/scikit_build_example/__init__.pyi
diff --git a/tests/test_basic.py b/tests/test_basic.py

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-.. automodule:: scikit_build_example`
	`1`	`+.. automodule:: cuda_example`