Static binding generation

Static binding generation produces a standalone Python module that depends only on Numba CUDA. It lets you distribute bindings without requiring Numbast at runtime.

When to use

• You want to ship bindings as a regular Python package/module.

• You want end users to avoid installing clang tooling or numbast.

• Your target environment is known and compatible with the generation environment.

Requirements

• CUDA Toolkit headers installed and discoverable.

• clangdev available in your development environment.

• A header entry point and a list of headers to retain.

Configuration file

The static-binding config contract is defined in numbast/src/numbast/tools/static_binding_generator.schema.yaml. The docs section below is generated from that schema at build time to avoid drift between implementation and documentation. For details on Function Argument Intents semantics and generated signatures, see Argument intents.

The experimental numba-cuda-mlir backend is selected with Backend: numba-cuda-mlir and is imported from numbast.experimental.mlir. See Numba-CUDA-MLIR support for the backend differences and migration guidance.

Config example:

# file: config.yml

# --- Required fields ---
Entry Point: /path/to/library/header.hpp
File List:
  - /path/to/library/header.hpp
  - /path/to/library/other_deps.hpp
GPU Arch: ["sm_80"]

# --- Optional fields ---
Exclude:
  Function: ["internal_helper", "deprecated_api"]
  Struct: ["__InternalState"]
Clang Include Paths:
  - /extra/include/dirs
Additional Import:
  - from numba import types
Predefined Macros:
  - SOME_MACRO=1
Output Name: bindings_my_lib.py
API Prefix Removal:
  Function: ["lib_"]
Module Callbacks:
  setup: "lambda x: print('setup')"
  teardown: "lambda x: print('teardown')"

Generate the binding

Use the CLI to generate a Python file:

# from repo root (ensure your development environment is active)
python -m numbast --cfg-path config.yml --output-dir ./output

This produces a module like ./output/bindings_my_lib.py (or <entry_point>.py if Output Name is not set).

Distribute and use

• Package the generated module into your project, or publish to PyPI.

• Users import it directly without having Numbast installed.

from bindings_my_lib import my_function, MyStruct

Notes and tips

• Use the same CUDA version (or backward compatible) between generation and target runtime environments.

• If multiple GPU architectures are needed, run the generator once per architecture.

• If your environment has ruff formatter installed, Numbast will attempt to run it on generated bindings.

Config Schema Reference

This section is generated directly from: numbast/src/numbast/tools/static_binding_generator.schema.yaml

Required keys

Entry Pointstring

Path to the input CUDA C/C++ header file.

Example:

Entry Point: /usr/local/cuda/include/cufp8.hpp

GPU Archarray

Target GPU architecture list. Exactly one architecture is currently supported per run.

Constraints:

• Min items: 1

• Max items: 1

• Item type: string

Example:

GPU Arch:
- sm_80

File Listarray

Header files to retain while parsing. Declarations from other transitively included files are ignored in generated output.

Constraints:

• Min items: 1

• Item type: string

Example:

File List:
- /usr/local/cuda/include/cufp8.hpp
- /usr/local/cuda/include/cufp8_conversions.hpp

Optional keys

Namestring

Optional config metadata field.

Versionstring | number

Optional config metadata field.

Typesobject

Mapping of struct names to Numba type class names.

Default: {}.

Example:

Types:
  __nv_fp8_e4m3: FP8e4m3Type

Data Modelsobject

Mapping of struct names to Numba datamodel class names.

Default: {}.

Example:

Data Models:
  __nv_fp8_e4m3: FP8e4m3Model

Excludeobject

Declaration names to skip during binding generation.

Default: {}.

Constraints:

• No unspecified sub-keys

Example:

Exclude:
  Function:
  - internal_helper
  Struct:
  - __InternalState

Clang Include Pathsarray

Additional include search paths for Clang parsing.

Default: [].

Constraints:

• Item type: string

Example:

Clang Include Paths:
- /usr/local/cuda/include
- /opt/extra/include

Additional Importarray

Extra Python import statements injected into the generated file.

Default: [].

Constraints:

• Item type: string

Example:

Additional Import:
- from nvshmem.bindings import module_init

Shim Include Overridestring | null

Override value used to compose the generated shim include line. If unset, the entry-point path is used.

Default: null.

Example:

Shim Include Override: cufp8.hpp

Predefined Macrosarray

Macros defined before parsing and prepended in shim generation.

Default: [].

Constraints:

• Item type: string

Example:

Predefined Macros:
- SOME_MACRO=1
- ENABLE_FEATURE

Output Namestring | null

Output filename for the Numba binding. Defaults to <entry-point-basename>.py. CUDA-Oxide uses its nested Output Name.

Default: null.

Example:

Output Name: bindings_my_lib.py

Cooperative Launch Required Functions Regexarray

Regex patterns. Matching function names are generated with cooperative launch handling.

Default: [].

Constraints:

• Item type: string

Example:

Cooperative Launch Required Functions Regex:
- ^cg_.*

API Prefix Removalobject

Prefixes removed from rendered declaration names.

Default: {}.

Constraints:

• No unspecified sub-keys

Example:

API Prefix Removal:
  Function:
  - lib_
  Struct:
  - lib_
  Enum:
  - LIB_

Module Callbacksobject

Optional module-level shim callback assignments.

Default: {}.

Constraints:

• No unspecified sub-keys

Example:

Module Callbacks:
  setup: 'lambda mod: print(''loaded'', mod)'
  teardown: 'lambda mod: print(''unloaded'', mod)'

Module Link Variables Usedarray

Experimental MLIR-backend-only linker metadata variables to mark as used. Requires Backend: numba-cuda-mlir.

Default: [].

Constraints:

• Item type: string

Example:

Module Link Variables Used:
- __numbast_module_used

Skip Prefixstring | null

Skip generating bindings for functions whose names start with this prefix.

Default: null.

Example:

Skip Prefix: __internal_

Use Separate Registryboolean

Generate separate typing/target registries instead of reusing Numba CUDA’s global registries.

Default: false.

Example:

Use Separate Registry: true

Function Argument Intentsobject

Numba-only per-function argument intent overrides. Function keys map to parameter-name or parameter-index entries. CUDA-Oxide ignores this backend-specific option. See Argument intents for intent semantics and generated signature behavior.

Default: {}.

Example:

Function Argument Intents:
  my_function:
    result: out_ptr
    0: in

Backendstring | array | null

Name of the emission backend, or a list of names. numba-cuda generates Numba bindings; numba-cuda-mlir routes generation to the experimental numbast.experimental.mlir backend, which requires a user-provided numba_cuda_mlir installation; cuda-oxide is registered for the Rust renderer but has no driver yet, so naming it is an error that says so. Defaults to numba-cuda. An unrecognised name is an error rather than a fallback. Naming more than one backend is an error for now, since a single run drives a single renderer.

Default: null.

Constraints:

• Item type: string

Example:

Backend: numba-cuda
Backend: numba-cuda-mlir

CUDA Oxideobject

Settings used when the shared document is consumed by the CUDA-Oxide backend. Their presence does not cause a Numba invocation to emit Rust.

Constraints:

• No unspecified sub-keys

Optional nested keys

Exclude

Functionarray

Function names to exclude.

Default: [].

Constraints:

• Item type: string

Example:

Function:
- internal_helper
- deprecated_api

Structarray

Struct names to exclude.

Default: [].

Constraints:

• Item type: string

Example:

Struct:
- __InternalState

API Prefix Removal

FunctiononeOf(string, array)

Prefix(es) removed from generated function names.

Example:

Function:
- lib_
- mylib_

StructoneOf(string, array)

Prefix(es) removed from generated struct names.

Example:

Struct:
- lib_

EnumoneOf(string, array)

Prefix(es) removed from generated enum names and values.

Example:

Enum:
- LIB_

Module Callbacks

setupstring

Python expression for setup callback.

Example:

setup: 'lambda mod: print(''loaded'', mod)'

teardownstring

Python expression for teardown callback.

Example:

teardown: 'lambda mod: print(''unloaded'', mod)'

CUDA Oxide

LTOIR Inputsarray

Ordered external CUDA LTOIR artifacts that provide the generated device symbols. Numbast records these paths but does not build them.

Constraints:

• Min items: 1

• Item type: string

Output Namestring

Rust output filename. Defaults to <entry-point-basename>.rs.

Constraints:

• Pattern: ^[^/\\]+$

Manifest Namestring

Optional output filename for the versioned JSON manifest. Defaults to the Rust output stem followed by .manifest.json.

Constraints:

• Pattern: ^[^/\\]+$

Symbol Inventorystring

Optional exact newline- or nm-style inventory of the selected public API. Generation fails if a symbol is present on only one side.

Type Aliasesobject

Supplemental C typedefs expressed as C-to-C mappings. Arbitrary Rust source is not accepted.

Default: {}.

Example:

Type Aliases:
  nvshmem_team_t: int

Constantsobject

Typed literal constants missing from the parsed AST.

Default: {}.

Bypass Parse Errorsboolean

Continue after recoverable Clang parser errors. Strict parsing is the default. Pair recovery mode with an exact Symbol Inventory to detect parser omissions.

Default: false.

Clang Binarystring

Optional clang++ executable used by AST Canopy.

Raw schema

# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
$schema: "https://json-schema.org/draft/2020-12/schema"
title: Numbast Binding Generator Config
description: >
  Canonical schema for a shared Numbast binding configuration. Parser and declaration-selection options are shared
  across backends, while backend-specific output settings remain in their own sections. The same document can
  therefore be used in separate Numba and CUDA-Oxide invocations.

type: object
additionalProperties: true
required:
  - Entry Point
  - GPU Arch
  - File List
properties:
  Name:
    type: string
    description: Optional config metadata field.
  Version:
    type: [string, number]
    description: Optional config metadata field.
  Entry Point:
    type: string
    description: Path to the input CUDA C/C++ header file.
    examples:
      - /usr/local/cuda/include/cufp8.hpp
  GPU Arch:
    type: array
    minItems: 1
    maxItems: 1
    items:
      type: string
      pattern: "^sm_[0-9]+a?$"
    description: >
      Target GPU architecture list. Exactly one architecture is currently supported per run.

    examples:
      - ["sm_80"]
  File List:
    type: array
    minItems: 1
    items:
      type: string
    description: >
      Header files to retain while parsing. Declarations from other transitively included files are ignored in
      generated output.

    examples:
      - - /usr/local/cuda/include/cufp8.hpp
        - /usr/local/cuda/include/cufp8_conversions.hpp
  Types:
    type: object
    default: {}
    additionalProperties:
      type: string
    description: Mapping of struct names to Numba type class names.
    examples:
      - {"__nv_fp8_e4m3": "FP8e4m3Type"}
  Data Models:
    type: object
    default: {}
    additionalProperties:
      type: string
    description: Mapping of struct names to Numba datamodel class names.
    examples:
      - {"__nv_fp8_e4m3": "FP8e4m3Model"}
  Exclude:
    type: object
    default: {}
    additionalProperties: false
    description: Declaration names to skip during binding generation.
    examples:
      - Function: ["internal_helper"]
        Struct: ["__InternalState"]
    properties:
      Function:
        type: array
        default: []
        items:
          type: string
        description: Function names to exclude.
        examples:
          - ["internal_helper", "deprecated_api"]
      Struct:
        type: array
        default: []
        items:
          type: string
        description: Struct names to exclude.
        examples:
          - ["__InternalState"]
  Clang Include Paths:
    type: array
    default: []
    items:
      type: string
    description: Additional include search paths for Clang parsing.
    examples:
      - - /usr/local/cuda/include
        - /opt/extra/include
  Additional Import:
    type: array
    default: []
    items:
      type: string
    description: Extra Python import statements injected into the generated file.
    examples:
      - - "from nvshmem.bindings import module_init"
  Shim Include Override:
    type: [string, "null"]
    default: null
    description: >
      Override value used to compose the generated shim include line. If unset, the entry-point path is used.

    examples:
      - "cufp8.hpp"
  Predefined Macros:
    type: array
    default: []
    items:
      type: string
    description: Macros defined before parsing and prepended in shim generation.
    examples:
      - - SOME_MACRO=1
        - ENABLE_FEATURE
  Output Name:
    type: [string, "null"]
    default: null
    description: >
      Output filename for the Numba binding. Defaults to `<entry-point-basename>.py`. CUDA-Oxide uses its nested
      ``Output Name``.

    examples:
      - bindings_my_lib.py
  Cooperative Launch Required Functions Regex:
    type: array
    default: []
    items:
      type: string
    description: >
      Regex patterns. Matching function names are generated with cooperative launch handling.

    examples:
      - - "^cg_.*"
  API Prefix Removal:
    type: object
    default: {}
    additionalProperties: false
    description: Prefixes removed from rendered declaration names.
    examples:
      - Function: ["lib_"]
        Struct: ["lib_"]
        Enum: ["LIB_"]
    properties:
      Function:
        oneOf:
          - type: string
          - type: array
            items:
              type: string
        description: Prefix(es) removed from generated function names.
        examples:
          - ["lib_", "mylib_"]
      Struct:
        oneOf:
          - type: string
          - type: array
            items:
              type: string
        description: Prefix(es) removed from generated struct names.
        examples:
          - ["lib_"]
      Enum:
        oneOf:
          - type: string
          - type: array
            items:
              type: string
        description: Prefix(es) removed from generated enum names and values.
        examples:
          - ["LIB_"]
  Module Callbacks:
    type: object
    default: {}
    additionalProperties: false
    description: Optional module-level shim callback assignments.
    examples:
      - setup: "lambda mod: print('loaded', mod)"
        teardown: "lambda mod: print('unloaded', mod)"
    properties:
      setup:
        type: string
        description: Python expression for setup callback.
        examples:
          - "lambda mod: print('loaded', mod)"
      teardown:
        type: string
        description: Python expression for teardown callback.
        examples:
          - "lambda mod: print('unloaded', mod)"
  Module Link Variables Used:
    type: array
    default: []
    items:
      type: string
    description: >
      Experimental MLIR-backend-only linker metadata variables to mark as used. Requires ``Backend:
      numba-cuda-mlir``.

    examples:
      - - "__numbast_module_used"
  Skip Prefix:
    type: [string, "null"]
    default: null
    description: Skip generating bindings for functions whose names start with this prefix.
    examples:
      - "__internal_"
  Use Separate Registry:
    type: boolean
    default: false
    description: >
      Generate separate typing/target registries instead of reusing Numba CUDA's global registries.

    examples:
      - true
  Function Argument Intents:
    type: object
    default: {}
    description: >
      Numba-only per-function argument intent overrides. Function keys map to parameter-name or parameter-index
      entries. CUDA-Oxide ignores this backend-specific option. See :doc:`/argument_intents` for intent semantics and
      generated signature behavior.

    examples:
      - my_function:
          result: out_ptr
          0: in
    additionalProperties:
      type: object
      additionalProperties:
        oneOf:
          - type: string
            enum: ["in", "inout_ptr", "out_ptr", "out_return"]
          - type: object
            properties:
              intent:
                type: string
                enum: ["in", "inout_ptr", "out_ptr", "out_return"]
            required: ["intent"]
  Backend:
    type: [string, array, "null"]
    items:
      type: string
    default: null
    description: >
      Name of the emission backend, or a list of names. ``numba-cuda`` generates Numba bindings; ``numba-cuda-mlir``
      routes generation to the experimental ``numbast.experimental.mlir`` backend, which requires a user-provided
      ``numba_cuda_mlir`` installation; ``cuda-oxide`` is registered for the Rust renderer but has no driver yet, so
      naming it is an error that says so. Defaults to ``numba-cuda``. An unrecognised name is an error rather than a
      fallback. Naming more than one backend is an error for now, since a single run drives a single renderer.

    examples:
      - "numba-cuda"
      - "numba-cuda-mlir"
  CUDA Oxide:
    type: object
    additionalProperties: false
    description: >
      Settings used when the shared document is consumed by the CUDA-Oxide backend. Their presence does not cause a
      Numba invocation to emit Rust.

    required: [LTOIR Inputs]
    properties:
      LTOIR Inputs:
        type: array
        minItems: 1
        items:
          type: string
        description: >
          Ordered external CUDA LTOIR artifacts that provide the generated device symbols. Numbast records these
          paths but does not build them.

      Output Name:
        type: string
        pattern: "^[^/\\\\]+$"
        not:
          enum: [., ..]
        description: >
          Rust output filename. Defaults to `<entry-point-basename>.rs`.

      Manifest Name:
        type: string
        pattern: "^[^/\\\\]+$"
        not:
          enum: [., ..]
        description: >
          Optional output filename for the versioned JSON manifest. Defaults to the Rust output stem followed by
          `.manifest.json`.

      Symbol Inventory:
        type: string
        description: >
          Optional exact newline- or nm-style inventory of the selected public API. Generation fails if a symbol is
          present on only one side.

      Type Aliases:
        type: object
        default: {}
        additionalProperties:
          type: string
        description: >
          Supplemental C typedefs expressed as C-to-C mappings. Arbitrary Rust source is not accepted.

        examples:
          - nvshmem_team_t: int
      Constants:
        type: object
        default: {}
        description: Typed literal constants missing from the parsed AST.
        additionalProperties:
          type: object
          additionalProperties: false
          required: [Type, Value]
          properties:
            Type:
              type: string
              description: C scalar type or configured C type alias.
            Value:
              type: [integer, boolean, string]
              description: Integer or Boolean literal; expressions are rejected.
      Bypass Parse Errors:
        type: boolean
        default: false
        description: >
          Continue after recoverable Clang parser errors. Strict parsing is the default. Pair recovery mode with an
          exact Symbol Inventory to detect parser omissions.

      Clang Binary:
        type: string
        description: Optional clang++ executable used by AST Canopy.