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.

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 binding filename. Defaults to <entry-point-basename>.py.

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)'

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

Per-function argument intent overrides. Function keys map to parameter-name or parameter-index entries. See Argument intents for intent semantics and generated signature behavior.

Default: {}.

Example:

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

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)'

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 Static Binding Generator Config
description: >
  Canonical schema describing supported YAML keys and value shapes accepted by the Numbast static binding generator
  configuration loader.

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]+$"
    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 binding filename. Defaults to `<entry-point-basename>.py`.
    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)"
  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: >
      Per-function argument intent overrides. Function keys map to parameter-name or parameter-index entries. 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"]