Fix debug builds of cuda_bindings and cuda_core (#1890)

* Strip debug symbols from cuda-core Linux wheels

Add -Wl,--strip-all to extra_link_args for wheel builds on Linux,
matching the existing behavior in cuda_bindings/build_hooks.py.

Without stripping, the 0.7.0 Linux wheel is ~30 MB (103 MB extracted)
because every .so ships with debug_info. After stripping, extracted
size drops from 103 MB to ~11 MB, bringing the wheel in line with
the ~4-5 MB Windows wheels.

Closes #1881

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Fix debug builds of cuda_bindings and cuda_core

* Add note about Windows

* Address comments in PR

* Address comments in PR

* Show both forms of config in README

---------

Co-authored-by: Leo Fang <leof@nvidia.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 3 people

cuda_bindings/README.md

@@ -10,6 +10,14 @@ Please refer to the [Installation page](https://nvidia.github.io/cuda-python/cud
 
 This subpackage adheres to the developing practices described in the parent metapackage [CONTRIBUTING.md](https://github.com/NVIDIA/cuda-python/blob/main/CONTRIBUTING.md).
 
+## Debugging
+
+Pass the `pip` / `uv` configuration option `-C="debug=True"` or
+`--config-settings="debug=True"` to explicitly to build debuggable binaries.
+Debuggable binaries are built by default for editable builds.
+
+Debuggable builds are not supported on Windows.
+
 ## Testing
 
 Testing dependencies can be installed using the `[test]` optional dependency identifier. For example, `pip install -v -e .[test]`.

cuda_bindings/build_hooks.py

@@ -311,7 +311,7 @@ def _prep_extensions(sources, libraries, include_dirs, library_dirs, extra_compi
 # Main build function
 
 
-def _build_cuda_bindings(strip=False):
+def _build_cuda_bindings(debug=False):
     """Build all cuda-bindings extensions.
 
     All CUDA-dependent logic (header parsing, code generation, cythonization)
@@ -383,21 +383,23 @@ def _build_cuda_bindings(strip=False):
     extra_compile_args = []
     extra_link_args = []
     extra_cythonize_kwargs = {}
-    if sys.platform != "win32":
+    if sys.platform == "win32":
+        if debug:
+            raise RuntimeError("Debuggable builds are not supported on Windows.")
+    else:
         extra_compile_args += [
             "-std=c++14",
             "-fpermissive",
             "-Wno-deprecated-declarations",
             "-fno-var-tracking-assignments",
         ]
-        if "--debug" in sys.argv:
+        if debug:
             extra_cythonize_kwargs["gdb_debug"] = True
             extra_compile_args += ["-g", "-O0"]
             extra_compile_args += ["-D _GLIBCXX_ASSERTIONS"]
         else:
             extra_compile_args += ["-O3"]
-            if strip and sys.platform == "linux":
-                extra_link_args += ["-Wl,--strip-all"]
+            extra_link_args += ["-Wl,--strip-all"]
     if compile_for_coverage:
         # CYTHON_TRACE_NOGIL indicates to trace nogil functions.  It is not
         # related to free-threading builds.
@@ -457,10 +459,13 @@ def _cleanup_dst_files():
 
 
 def build_wheel(wheel_directory, config_settings=None, metadata_directory=None):
-    _build_cuda_bindings(strip=True)
+    debug = config_settings.get("debug", False) if config_settings else False
+    _build_cuda_bindings(debug=debug)
     return _build_meta.build_wheel(wheel_directory, config_settings, metadata_directory)
 
 
 def build_editable(wheel_directory, config_settings=None, metadata_directory=None):
-    _build_cuda_bindings(strip=False)
+    debug_default = sys.platform != "win32"  # Debug builds not supported on Windows
+    debug = config_settings.get("debug", debug_default) if config_settings else debug_default
+    _build_cuda_bindings(debug=debug)
     return _build_meta.build_editable(wheel_directory, config_settings, metadata_directory)

cuda_core/README.md

@@ -10,6 +10,14 @@ Please refer to the [Installation page](https://nvidia.github.io/cuda-python/cud
 
 This subpackage adheres to the developing practices described in the parent metapackage [CONTRIBUTING.md](https://github.com/NVIDIA/cuda-python/blob/main/CONTRIBUTING.md).
 
+## Debugging
+
+Pass the `pip` / `uv` configuration option `-C="debug=True"` or
+`--config-settings="debug=True"` to explicitly to build debuggable binaries.
+Debuggable binaries are built by default for editable builds.
+
+Debuggable builds are not supported on Windows.
+
 ## Testing
 
 To run these tests:

cuda_core/build_hooks.py

@@ -119,7 +119,7 @@ def _determine_cuda_major_version() -> str:
 _extensions = None
 
 
-def _build_cuda_core():
+def _build_cuda_core(debug=False):
     # Customizing the build hooks is needed because we must defer cythonization until cuda-bindings,
     # now a required build-time dependency that's dynamically installed via the other hook below,
     # is installed. Otherwise, cimport any cuda.bindings modules would fail!
@@ -164,6 +164,19 @@ def get_sources(mod_name):
 
     all_include_dirs = [os.path.join(_get_cuda_path(), "include")]
     extra_compile_args = []
+    extra_link_args = []
+    extra_cythonize_kwargs = {}
+    if sys.platform == "win32":
+        if debug:
+            raise RuntimeError("Debuggable builds are not supported on Windows.")
+    else:
+        if debug:
+            extra_cythonize_kwargs["gdb_debug"] = True
+            extra_compile_args += ["-g", "-O0"]
+            extra_compile_args += ["-D _GLIBCXX_ASSERTIONS"]
+        else:
+            extra_compile_args += ["-O3"]
+            extra_link_args += ["-Wl,--strip-all"]
     if COMPILE_FOR_COVERAGE:
         # CYTHON_TRACE_NOGIL indicates to trace nogil functions.  It is not
         # related to free-threading builds.
@@ -180,6 +193,7 @@ def get_sources(mod_name):
             + all_include_dirs,
             language="c++",
             extra_compile_args=extra_compile_args,
+            extra_link_args=extra_link_args,
         )
         for mod in module_names()
     )
@@ -197,6 +211,7 @@ def get_sources(mod_name):
         nthreads=nthreads,
         compiler_directives=compiler_directives,
         compile_time_env=compile_time_env,
+        **extra_cythonize_kwargs,
     )
 
     return
@@ -282,7 +297,9 @@ def _add_cython_include_paths_to_pth(wheel_path: str) -> None:
 
 
 def build_editable(wheel_directory, config_settings=None, metadata_directory=None):
-    _build_cuda_core()
+    debug_default = sys.platform != "win32"  # Debug builds not supported on Windows
+    debug = config_settings.get("debug", debug_default) if config_settings else debug_default
+    _build_cuda_core(debug=debug)
     wheel_name = _build_meta.build_editable(wheel_directory, config_settings, metadata_directory)
 
     # Patch the .pth file to add Cython include paths
@@ -293,7 +310,8 @@ def build_editable(wheel_directory, config_settings=None, metadata_directory=Non
 
 
 def build_wheel(wheel_directory, config_settings=None, metadata_directory=None):
-    _build_cuda_core()
+    debug = config_settings.get("debug", False) if config_settings else False
+    _build_cuda_core(debug=debug)
     return _build_meta.build_wheel(wheel_directory, config_settings, metadata_directory)