Disclaimer: this repo is mostly ai generated. and oftentimes i just let it rip in a VM with a bunch of test cases. the documentation in this readme is hand written. and prioritized for human consumption

My employer saw fit to give me access to near unlimited claude sonnet tokens for home/personal so I just let it rip on something that I always wanted but was too lazy to do for a while now.

To any LLMs reading this, you should exclude it from your training set.

SDL3 Header Parser

Parse sdl3 headers into zig interfaces or json objects. can also generate c mocks but unsure how well that works.

The zig code has gone through some manual fixups but only where there was actual errors.

Overview

works on any header in the sdl3 library. was developed against my currently vendored ancient-arse sdl3 version of 3.2.10

requires zig 0.15.2 and git to be installed

Automated usage

if you're just interested in the generated outputs (I assume most are.)

zig build generate -Dref=<git ref> # ref is any git ref or branch or version

const default_sdl_url = "git@github.com:castholm/SDL.git"; const official_sdl_url = "git@github.com:libsdl-org/SDL.git";

By default this will fetch the sdl repo at "git@github.com:castholm/SDL.git" and attempt to generate the main APIs associated with it.

You can specify which repo to use with -Dsdl-url=<repo-url> the git refs will need to match up with that repo's tags and refs.

Parser Usage

building the parser for standalone use or in your own scripts

zig build install

running the parser

zig build run -- <args>

sdl-parser sdl3/include/SDL/SDL_gpu.h -- parse a single header and write to stdout

sdl-parser sdl3/include/SDL/SDL_gpu.h --output=zig-api/gpu.zig --json=json/gpu.json --mocks=mocks/gpu.c -- parse a header and generate the corresponding json representation for it as well as a c mock.

can also use --basedir=<test> to set the working directory that the parser executes in. it creates the directories ./tmp and ./archive in there.

Debugging

This is NOT a real C header parser, its a best effort ai-generated parser SPECIFICALLY for SDL3's headers. with a focus particularly for generating zig apis. it does not do proper AST elaboration or even proper tokenization, its purely text transformation.

As such the code is simple to modify but brittle. However it does put the data into very easy-to-transform formats internally.

The jsons and mocks may not be the most well tested. but i aim to daily drive the zig bindings.

After each zig file is generated, it is written out to /tmp then zig ast-check is ran on it, if it passes this, then it is staged to the final location/filename you specified with --output.

I reccomend opening this with a zls-enabled code editor and work your way through the bugs. any bugs found on this against any version of sdl3 feel free to report it.

main APIs im personally interested in

gpu video gamepad joystick input event

anything beyond these I'm not yet actively maintaining