AST Canopy overview#

ast_canopy parses CUDA C++ headers using LLVM’s clang tooling and produces a compact representation of top-level declarations for downstream consumption by Numbast.

What it provides#

  • Python API to parse a translation unit and retain a subset of files

  • Serialization of declarations (records, functions, templates, typedefs)

  • Utilities for mapping C++ semantics to Python-friendly constructs

Primary API#

import ast_canopy
ast_canopy.parse_declarations_from_source(
    source_file_path,
    files_to_retain,
    compute_capability,
    cccl_root=None,
    cudatoolkit_include_dir=None,
    cxx_standard="c++17",
)

Build and tests#

See Install for environment setup. To build and test from the repository root:

bash ast_canopy/build.sh
pytest ast_canopy/

Note

If you see errors like “cannot find header ‘cuda.h’”, please refer to FAQ for more details.

Folder structure#

  • cpp: C++ library that traverses clang AST (libastcanopy)

  • ast_canopy: Python bindings and high-level API

  • tests: Unit tests for bindings and API

Notes#

  • libastcanopy builds independently with CMake and is used via dynamic linking from Python

  • The Python package uses scikit-build-core and pybind11

Global constants#

parse_declarations_from_source automatically returns compile-time scalar constants from retained files in Declarations.global_constants. This includes namespace-scope const and constexpr declarations, including static and inline constants. Clang evaluates initializer expressions, so consumers receive the source type and evaluated value without copying values into a configuration file.

Each constant is an EvaluatedConstDecl exposing name, qual_name, type_, value_serialized, and the converted Python value. Its is_constexpr flag records whether the source declaration was explicitly constexpr. The existing value_from_constexpr_vardecl API also returns this type, but continues to look up only constexpr declarations.

Mutable or volatile variables, local and class-scope declarations, variable-template specializations, runtime initializers, and non-scalar objects are not included in the global collection. Enum members remain available through Declarations.enums.