[libcu++] Add cuda::hierarchy debugger pretty-printers

[ahmedtaha100]

@Jacobfaib

Description

closes #10089

Add the GDB and LLDB pretty-printers for cuda::hierarchy requested by issue #10089. The printers show the bottom unit and dimensions for each hierarchy level. They read static extents from type information and dynamic extents from stored values. They do not call functions in the debugged program.

Tests cover static and dynamic extents, partial hierarchies, derived descriptors, values in std::vector, and live updates.

Validation

• Hierarchy tests passed with GDB 15.1 and LLDB 20.1 using CUDA 13.3 at -g -O3.
• The neighboring tuple debugger tests passed.
• Ruff lint and format, clang-format, Gersemi, and codespell passed using the repository-pinned versions.

Checklist

• New or existing tests cover these changes.
• The documentation is up to date with these changes.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: f0e920b5-a689-4fe7-a6a2-bb872b5b8d0e

📥 Commits

Reviewing files that changed from the base of the PR and between 8548977 and 6f74ed7.

📒 Files selected for processing (9)

• libcudacxx/share/libcudacxx/gdb/__init__.py
• libcudacxx/share/libcudacxx/gdb/hierarchy.py
• libcudacxx/share/libcudacxx/lldb/__init__.py
• libcudacxx/share/libcudacxx/lldb/hierarchy.py
• libcudacxx/test/debugging/CMakeLists.txt
• libcudacxx/test/debugging/hierarchy/CMakeLists.txt
• libcudacxx/test/debugging/hierarchy/gdb.expected
• libcudacxx/test/debugging/hierarchy/lldb.expected
• libcudacxx/test/debugging/hierarchy/source.cu

---

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Added debugger visualization for CUDA hierarchy types in GDB and LLDB.
  • Hierarchy dimensions, levels, and bottom-unit classifications are now displayed clearly.
  • Supports static, dynamic, partial, derived, vector-indexed, and updated hierarchy values.

• Tests

  • Added comprehensive debugger coverage for CUDA hierarchy inspection in both GDB and LLDB.

Walkthrough

Changes

The PR adds GDB and LLDB pretty-printers for cuda::hierarchy and cuda::hierarchy_level_desc. It registers both printers and adds debugger tests for multiple hierarchy layouts and update states.

CUDA hierarchy pretty-printers

Layer / File(s)	Summary
GDB hierarchy printer libcudacxx/share/libcudacxx/gdb/...	GDB resolves hierarchy descriptors, extracts static and dynamic extents, formats dimensions and bottom units, and exposes hierarchy levels as children.
LLDB hierarchy formatter libcudacxx/share/libcudacxx/lldb/...	LLDB recognizes hierarchy types, formats summaries, exposes synthetic hierarchy-level children, and registers the formatter callbacks.
Hierarchy debugger test coverage libcudacxx/test/debugging/...	The new tests inspect static, dynamic, partial, derived, vector-backed, and updated hierarchy values with GDB and LLDB expected output.

Assessment against linked issues

Objective	Addressed	Explanation
Create GDB and LLDB pretty-printers under the required debugger directories [#10089]	✅
Add exhaustive hierarchy debugger tests under libcudacxx/test/debugging/hierarchy [#10089]	✅

Suggested reviewers: bernhardmgruber

---

_{Comment @coderabbitai help to get the list of available commands.}

[davebayer]

/ok to test 6f74ed7

[github-actions]

⏱️ CCCL compile-time benchmark comparison: Public headers compile-time bench

Result: 0 regression row(s), 2 improvement row(s) above threshold.

Run	Value
Config	public-headers-gcc13
Baseline	origin/main
Preset	all-dev
Targets	cub.headers.base, thrust.cpp.cuda.headers.base, libcudacxx.test.public_headers
GPU / launch args	rtx2080 / --cuda 13.3 --host gcc13

Artifacts: reports and traces

Direct file processing

-f file-processing exclusive --sort total

🟢 Direct file processing — Improvements

Rank	Improvement impact	Selected Δ	Baseline	Current	Event	Matched traces
1	0.547080	-0.547080	4.716315	4.169235	Processing Header File: libcudacxx/include/cuda/std/__cccl/prologue.h	550
2	0.210967	-0.210967	1.652809	1.441842	Processing Header File: libcudacxx/include/cuda/std/__cccl/epilogue.h	550

[github-actions]

AI failure analysis

1. RAPIDS repositories require conflicting rapids-logger major versions · 1 job

Explanation: The combined environment for the nvforest/cuml matrix requests both rapids-logger 0.2 and 0.3, so libmamba fails before any CCCL-dependent project is configured or built. The pull request only changes libcudacxx debugger support and does not modify RAPIDS dependency configuration.

Evidence:

Build RAPIDS (optional) / rmm ucxx raft cuvs nvforest cuml, step 6

2026-08-11T13:59:37.2955381Z error    libmamba Could not solve for environment specs
2026-08-11T13:59:37.2955767Z     The following packages are incompatible
2026-08-11T13:59:37.2956406Z     ├─ rapids-logger =0.2,>=0.0.0a0 * is requested and can be installed;

Root cause: Dependency files from the dynamically cloned RAPIDS repositories are out of sync: at least one requires rapids-logger 0.2 while another requires 0.3. The log does not preserve the individual generated environment files needed to attribute each constraint to a specific repository. Sources: .github/workflows/build-rapids.yml:67, ci/rapids/post-create-command.sh:141.

Suggested next steps: Inspect the per-repository generated conda environment files to identify the sources of both rapids-logger constraints, then pin or update the affected RAPIDS repository revisions so they agree. Reproduce with `RAPIDS_LIBS='rmm ucxx raft cuvs nvforest cuml' .devcontainer/launch.sh -d -c 13.3 -H rapids-conda -- ./ci/rapids/rapids-entrypoint.sh /bin/bash -li -c 'uninstall-all -j -qqq && clean-all -j && build-all -j0 -v || exec /bin/bash -li'`.

Copy this prompt into a coding agent

Repository: https://github.com/NVIDIA/cccl
Workflow run: https://github.com/NVIDIA/cccl/actions/runs/31498673275
Failure group: RAPIDS repositories require conflicting rapids-logger major versions
Affected jobs:
- Build RAPIDS (optional) / rmm ucxx raft cuvs nvforest cuml: https://github.com/NVIDIA/cccl/actions/runs/31498673275/job/93803014525

Reproduce the RAPIDS environment-resolution failure narrowly for `rmm ucxx raft cuvs nvforest cuml` under CUDA 13.3. Before environment creation, inspect or retain each repository's generated conda YAML and determine exactly which repository introduces `rapids-logger==0.2.*` and which introduces `rapids-logger==0.3.*`. Verify the incompatible upstream revisions, then implement the smallest CCCL-side stabilization—preferably pinning the affected `RAPIDS_<lib>_GIT_REPO` entry to a mutually compatible revision rather than weakening dependency constraints. Run the focused devcontainer reproduction and confirm environment creation proceeds to project configuration.

Jobs:

• Build RAPIDS (optional) / rmm ucxx raft cuvs nvforest cuml

2. CUDA 13.3 matrix cannot resolve available cuML 26.10 packages · 1 job

Explanation: The cugraph/wholegraph environment indirectly installs cuML 26.10, but the available cuML/libcuml builds require CUDA below 13 and rapids-logger 0.2 while the generated environment pins CUDA 13.3 and rapids-logger 0.3. Environment creation therefore fails before compilation.

Evidence:

Build RAPIDS (optional) / rmm ucxx raft cuvs cugraph wholegraph, step 6

2026-08-11T13:59:51.9826699Z error    libmamba Could not solve for environment specs
2026-08-11T13:59:51.9834129Z     ├─ cuda-version =13.3 * is requested and can be installed;
2026-08-11T13:59:51.9834675Z     ├─ cuml =26.10,>=0.0.0a0 * is installable with the potential options

Root cause: The workflow follows current RAPIDS repository branches while consuming nightly cuML packages that have not converged on the matrix's CUDA 13.3 and rapids-logger 0.3 requirements. The logs do not show an available cuML build compatible with both constraints. Sources: .github/workflows/build-rapids.yml:68, ci/rapids/cuda13.3-conda/devcontainer.json:17, ci/rapids/post-create-command.sh:141.

Suggested next steps: Check whether a newer cuML 26.10 nightly supports CUDA 13.3 and rapids-logger 0.3; otherwise pin the cugraph-related repositories to revisions compatible with currently published cuML packages. Reproduce with `RAPIDS_LIBS='rmm ucxx raft cuvs cugraph wholegraph' .devcontainer/launch.sh -d -c 13.3 -H rapids-conda -- ./ci/rapids/rapids-entrypoint.sh /bin/bash -li -c 'uninstall-all -j -qqq && clean-all -j && build-all -j0 -v || exec /bin/bash -li'`.

Copy this prompt into a coding agent

Repository: https://github.com/NVIDIA/cccl
Workflow run: https://github.com/NVIDIA/cccl/actions/runs/31498673275
Failure group: CUDA 13.3 matrix cannot resolve available cuML 26.10 packages
Affected jobs:
- Build RAPIDS (optional) / rmm ucxx raft cuvs cugraph wholegraph: https://github.com/NVIDIA/cccl/actions/runs/31498673275/job/93803014591

Reproduce the RAPIDS environment-resolution failure narrowly for `rmm ucxx raft cuvs cugraph wholegraph` under CUDA 13.3. Retain the generated environment inputs and identify which repository introduces the `cuml==26.10.*` dependency and `rapids-logger==0.3.*`. Check the nightly package metadata for a cuML/libcuml build supporting CUDA 13.3 and logger 0.3; if none exists, find a compatible upstream repository revision and pin it through the appropriate `RAPIDS_<lib>_GIT_REPO` workflow environment variable. Do not change the CUDA 13.3 matrix unless compatibility requirements explicitly permit it. Run the focused devcontainer reproduction and verify environment solving succeeds before running any broader validation.

Jobs:

• Build RAPIDS (optional) / rmm ucxx raft cuvs cugraph wholegraph

[davebayer]

Thank you for the contribution!