headerkit: A CLI tool and Python library for parsing C/C++ headers.

Generates:

• Bindings: ctypes modules, CFFI definitions, Cython .pxd files, and LuaJIT FFI.
• Data: JSON Intermediate Representation (IR) and API diffs.
• LLMs: Token-optimized header summaries for prompt windows.
• Builds: PEP 517 backend for standard Python packaging.

Parse once. Build anywhere.

Every example below assumes this input header:

// mylib.h
typedef struct { int x, y; } Point;
int distance(const Point *a, const Point *b);

ctypes -- drop-in Python module, no build step:

headerkit mylib.h -w ctypes -o ctypes:bindings.py

# generated bindings.py
class Point(ctypes.Structure):
    _fields_ = [
        ("x", ctypes.c_int),
        ("y", ctypes.c_int),
    ]

_lib.distance.argtypes = [ctypes.POINTER(Point), ctypes.POINTER(Point)]
_lib.distance.restype = ctypes.c_int

CFFI -- declarations for ffibuilder.cdef():

headerkit mylib.h -w cffi -o cffi:_defs.cdef.txt

/* generated  _defs.cdef.txt */
typedef struct Point {
    int x;
    int y;
} Point;
int distance(const Point *a, const Point *b);

Cython -- .pxd for compiled C/C++ interop:

headerkit mylib.h -w cython -o cython:mylib.pxd

# generated mylib.pxd
cdef extern from "mylib.h":

    ctypedef struct Point:
        int x
        int y

    int distance(const Point *a, const Point *b)

LuaJIT FFI -- ffi.cdef bindings for LuaJIT:

headerkit mylib.h -w lua -o lua:mylib_ffi.lua

/* generated mylib_ffi.lua */
local ffi = require("ffi")

ffi.cdef[[

/* Structs */
typedef struct {
    int x;
    int y;
} Point;

/* Functions */
int distance(const Point *a, const Point *b);

]]

JSON -- full IR for custom tooling:

headerkit mylib.h -w json -o json:mylib.json

{
  "path": "mylib.h",
  "declarations": [
    {"kind": "struct", "name": "Point", "fields": [
      {"name": "x", "type": {"kind": "ctype", "name": "int"}},
      {"name": "y", "type": {"kind": "ctype", "name": "int"}}
    ]},
    {"kind": "function", "name": "distance", ...}
  ]
}

Prompt -- token-optimized summary for LLM context windows:

headerkit mylib.h -w prompt

// mylib.h (headerkit compact)
STRUCT Point {x:int, y:int}
FUNC distance(a:const Point*, b:const Point*) -> int

Diff -- API compatibility reports between header versions:

from headerkit.backends import get_backend
from headerkit.writers.diff import DiffWriter

backend = get_backend("libclang")
old = backend.parse('#include "mylib_v1.h"', "v1.h")
new = backend.parse('#include "mylib_v2.h"', "v2.h")
print(DiffWriter(baseline=old, format="markdown").write(new))

## Breaking Changes
### function_signature_changed
- **distance**: parameter 0 type changed from 'const Point *' to 'const Point3D *'

Build backend -- generate cacheable bindings at pip install time:

# In your project's pyproject.toml:
[build-system]
requires = ["headerkit", "hatchling"]
build-backend = "headerkit.build_backend"

Python API -- parse and generate from code:

from headerkit import generate

output = generate("mylib.h", "cffi")

graph LR
    A[C/C++ headers] --> B[backend]
    B --> C[IR]
    C --> D[writer]
    D --> E[output]

• One parse, many outputs: generate multiple bindings in a single pass with -w ctypes -w cython -o ctypes:lib.py -o cython:lib.pxd
• Config file support: .headerkit.toml or [tool.headerkit] in pyproject.toml
• Multi-header merging: pass multiple .h files and they are merged into a single umbrella header

pip install headerkit

Requires Python 3.10+.

Then install libclang (if not already present):

headerkit install-libclang

Or install it manually:

Supports LLVM 18, 19, 20, and 21.

headerkit [options] FILE [FILE ...]

When no -o flag is given for a writer, output goes to stdout. At most one writer may write to stdout.

Pass writer options with --writer-opt:

headerkit mylib.h -w cffi --writer-opt cffi:exclude_patterns=^__
headerkit mylib.h -w ctypes -o ctypes:mylib.py --writer-opt ctypes:lib_name=mylib

headerkit searches from the current directory upward for .headerkit.toml, or for a [tool.headerkit] section in pyproject.toml. Use --no-config to skip this.

# .headerkit.toml
backend = "libclang"
writers = ["cffi"]
include_dirs = ["/usr/local/include"]
plugins = ["mypkg.headerkit_plugin"]

[writer.cffi]
exclude_patterns = ["^__", "^_internal"]

[writer.ctypes]
lib_name = "mylib"

Config string values support ${VAR} environment variable expansion at load time, which is useful for build-time paths injected by CMake or similar tools (e.g., include_dirs = ["${MY_INCLUDE_DIR}"]).

Command-line flags override config file values.

For projects using CFFI with cffi_buildtool, see the CFFI Integration Guide.

Register third-party backends and writers via Python entry points:

# In your package's pyproject.toml
[project.entry-points."headerkit.backends"]
mybackend = "mypkg.backend:MyBackend"

[project.entry-points."headerkit.writers"]
mywriter = "mypkg.writer:MyWriter"

Or load plugins explicitly from the config file:

# .headerkit.toml
plugins = ["mypkg.headerkit_plugin"]

headerkit includes a two-layer cache that stores parsed IR and generated output in .headerkit/. Commit the cache to version control and downstream consumers can build without libclang installed.

from headerkit import generate

# First run: parses with libclang, caches result
output = generate("mylib.h", "cffi")

# Second run: loads from cache, no libclang needed
output = generate("mylib.h", "cffi")

# CLI: generate with caching (on by default)
headerkit mylib.h -w cffi -o cffi:mylib.cdef.txt --store-dir .headerkit

headerkit also ships a PEP 517 build backend. Consumer projects declare it in pyproject.toml and get bindings generated automatically during pip install or python -m build, with no libclang required when the cache is committed:

[build-system]
requires = ["headerkit", "hatchling"]
build-backend = "headerkit.build_backend"

Generate cache entries for multiple platforms using Docker:

# Populate for common Linux targets
headerkit cache populate mylib.h -w cffi \
    --platform linux/amd64 --platform linux/arm64

# Auto-detect platforms from cibuildwheel config
headerkit cache populate mylib.h -w cffi --cibuildwheel

# Commit the populated cache
git add .headerkit/
git commit -m "cache: populate for linux amd64 + arm64"

When .headerkit/ contains entries for all target platforms, downstream builds never need libclang installed.

See the Cache Strategy Guide for cache layout, bypass flags, and CI integration, and the Build Backend Guide for full setup instructions.

from headerkit.backends import get_backend
from headerkit.writers import get_writer

backend = get_backend("libclang")
header = backend.parse('#include "mylib.h"', "wrapper.h", include_dirs=["/path/to/include"])

writer = get_writer("cffi")
print(writer.write(header))

Full documentation, guides, and API reference: axiomantic.github.io/headerkit

headerkit's build backend populates .headerkit/ during wheel builds. To keep the store updated across platforms in CI, see the CI Store Population guide. For projects using cibuildwheel, see the cibuildwheel Integration guide for Linux Docker volume mount configuration.

git clone https://github.com/axiomantic/headerkit.git
cd headerkit
pip install -e '.[dev]'
pytest

This project is licensed under the MIT License.

The vendored clang Python bindings in headerkit/_clang/v*/ are from the LLVM Project and are licensed under the Apache License v2.0 with LLVM Exceptions.