abi-forge 1.0.0

ABI governance and polyglot binding generator for C shared libraries

abi-forge

Reusable ABI governance and polyglot binding generator for C shared libraries.

From a single C header, abi-forge produces a versioned IDL snapshot and generates bindings for every language you need — with built-in breakage detection and governance.

What it does

Stage	What happens
Parse	Clang-preprocesses your C header into a stable IDL JSON snapshot
Govern	Diffs every new snapshot against the baseline; flags removals, signature changes, enum shifts as typed errors (ABI001–ABI007, SARIF-compatible)
Generate	Runs your chosen language generators from the IDL: C#, Python, Rust, TypeScript, Go
Enforce	CI fails on ABI regressions; waivers require explicit approval with TTL

Language targets

Language	Output	Mechanism
C# (.NET)	P/Invoke + SafeHandle wrappers + async layer	Roslyn source generator (generator_sdk/csharp/)
Python	ctypes module with IntEnum, OOP handles, CFUNCTYPE	generator_sdk/python_bindings_generator.py
Rust	#[repr(C)] enums + extern "C" block	generator_sdk/rust_ffi_generator.py
TypeScript	ffi-napi + OOP wrappers with [Symbol.dispose]	generator_sdk/typescript_bindings_generator.py
Go	cgo package with struct wrappers and runtime.SetFinalizer	generator_sdk/go_bindings_generator.py

Real-world example

LumenRTC — a .NET wrapper over libwebrtc — uses abi-forge to govern its C ABI and generate all language bindings from a single IDL snapshot. See abi/config.json there for a complete production configuration.

Quick start

Requirements

• Python 3.10+
• clang (for header parsing)
• .NET SDK 10+ (optional, only for C# bindings)

Bootstrap a new target

# Add abi-forge as a submodule
git submodule add https://github.com/vitkuz573/abi-forge.git tools/abi_framework

# Bootstrap: scaffolds abi/config.json + initial metadata
python3 tools/abi_framework/abi_framework.py bootstrap \
  --target mylib \
  --header path/to/mylib.h \
  --namespace MyLib \
  --generate-python \
  --generate-rust

# Parse header → IDL snapshot
python3 tools/abi_framework/abi_framework.py generate \
  --config abi/config.json --skip-binary

# Generate all bindings from IDL
python3 tools/abi_framework/abi_framework.py codegen \
  --config abi/config.json --skip-binary

# Lock current IDL as baseline (first time)
python3 tools/abi_framework/abi_framework.py generate-baseline --target mylib

ABI governance in CI

# Fail on regressions
python3 tools/abi_framework/abi_framework.py check \
  --config abi/config.json --skip-binary

# Full SARIF report for GitHub code scanning
python3 tools/abi_framework/abi_framework.py check-all \
  --config abi/config.json --skip-binary --sarif-out abi-report.sarif

Health dashboard

python3 tools/abi_framework/abi_framework.py status --config abi/config.json

Repository structure

abi-forge/
├── abi_framework.py            # CLI entry point
├── src/abi_framework_core/     # core: parse, diff, snapshot, policy, orchestration
│   └── commands/               # subcommands: generate, codegen, check, release, status, …
├── generator_sdk/              # language generators (Python, Rust, TypeScript, Go, C#-scaffold)
│   └── plugin.manifest.json    # plugin declarations for all built-in generators
├── abi_codegen_core/           # shared codegen primitives (native exports, required functions)
├── abi_roslyn_codegen/         # Roslyn source generator for C# P/Invoke + managed API
├── tests/                      # 99 tests covering orchestration, generators, governance
└── schemas/                    # JSON schemas for IDL, config, managed_api

Config overview (abi/config.json)

{
  "targets": {
    "mylib": {
      "header": {
        "path": "include/mylib.h",
        "symbol_prefix": "mylib_",
        "api_macro": "MYLIB_API"
      },
      "codegen": {
        "idl_output": "abi/generated/mylib/mylib.idl.json"
      },
      "baseline_path": "abi/baselines/mylib.json",
      "bindings": {
        "generators": [
          {
            "manifest": "{repo_root}/tools/abi_framework/generator_sdk/plugin.manifest.json",
            "plugins": [
              "abi_framework.python_bindings",
              "abi_framework.rust_ffi",
              "abi_framework.typescript_bindings",
              "abi_framework.go_bindings"
            ]
          }
        ]
      }
    }
  }
}

ABI error types (SARIF rules)

Rule	Meaning
ABI001	Function removed from public API
ABI002	Function signature changed
ABI003	Enum value added, removed, or renumbered
ABI004	Struct layout changed
ABI005	Bindings metadata mismatch
ABI006	Version policy violation
ABI007	Warning (non-breaking)

License

MIT