Backlog/lib/sdl3/parser/README.md

SDL3 Header Parser

A Zig tool that automatically generates idiomatic Zig bindings from SDL3 C headers with automatic dependency resolution.

Features

✅ Automatic Dependency Resolution - Detects and extracts missing types from included headers
✅ Multi-Field Struct Parsing - Handles compact C syntax like int x, y;
✅ Type Conversion - Converts C types to idiomatic Zig types
✅ Method Organization - Groups functions as methods on opaque types
✅ Mock Generation - Creates C stub implementations for testing
✅ Production Ready - 100% dependency resolution for SDL_gpu.h

Quick Start

Installation

cd parser/
zig build          # Build the parser
zig build test     # Run tests (26+ tests)

Basic Usage

# Generate Zig bindings
zig build run -- ../SDL/include/SDL3/SDL_gpu.h --output=gpu.zig

# Generate with C mocks for testing
zig build run -- ../SDL/include/SDL3/SDL_gpu.h --output=gpu.zig --mocks=gpu_mock.c

Example Output

Input (SDL_gpu.h):

typedef struct SDL_GPUDevice SDL_GPUDevice;
extern SDL_DECLSPEC void SDLCALL SDL_DestroyGPUDevice(SDL_GPUDevice *device);

Output (gpu.zig):

pub const GPUDevice = opaque {
    pub inline fn destroyGPUDevice(gpudevice: *GPUDevice) void {
        return c.SDL_DestroyGPUDevice(gpudevice);
    }
};

Supported C Patterns

Type Declarations

• Opaque types: typedef struct SDL_Type SDL_Type;
• Structs: typedef struct { int x, y; } SDL_Rect; (multi-field support!)
• Enums: typedef enum { VALUE1, VALUE2 } SDL_Enum;
• Flags: Bitfield enums with #define values
• Typedefs: typedef Uint32 SDL_PropertiesID;

Functions

• Extern functions: extern SDL_DECLSPEC RetType SDLCALL SDL_Func(...);
• Method grouping: Functions with opaque first parameter become methods

Automatic Type Conversion

C Type	Zig Type
bool	bool
Uint32	u32
int	c_int
SDL_Type*	?*Type
const SDL_Type*	*const Type
void*	?*anyopaque

Dependency Resolution

The parser automatically:

1. Detects types referenced but not defined
2. Searches included headers for definitions
3. Extracts required types
4. Generates unified output with all dependencies

Example:

SDL_gpu.h references SDL_Window
  → Parser finds #include <SDL3/SDL_video.h>
  → Extracts SDL_Window definition
  → Includes in output automatically

Success Rate: 100% for SDL_gpu.h (5/5 dependencies)

Documentation

Start Here: Getting Started Guide

User Guides

• Getting Started - Installation and first steps
• Quickstart - Quick reference
• API Reference - All command-line options

Technical Docs

• Architecture - How the parser works
• Dependency Resolution - Automatic type extraction
• Known Issues - Current limitations

Development

• Development Guide - Contributing and extending
• Roadmap - Future plans

Complete Index

• Documentation Index - All documentation

Project Status

Production Ready ✅

• SDL_gpu.h: 100% working
• 26+ tests passing
• Comprehensive documentation
• Zero manual intervention needed

Tested Headers

Header	Status	Dependencies	Notes
SDL_gpu.h	✅ Complete	5/5 (100%)	Production ready
SDL_keyboard.h	⚠️ Partial	6/6 resolved	Enum syntax issues
SDL_video.h	⚠️ Partial	5/14 resolved	Needs fixes
SDL_events.h	⚠️ Partial	Unknown	Needs fixes

See Known Issues for details.

Performance

• Small headers (<100 decls): ~100ms
• Large headers (SDL_gpu.h, 169 decls): ~520ms
• Memory usage: ~2-5MB peak
• Output: ~1KB per declaration

Requirements

• Zig 0.15+
• SDL3 headers (included in parent directory)

Examples

Parse a Header

zig build run -- ../SDL/include/SDL3/SDL_gpu.h --output=gpu.zig

Use Generated Bindings

const gpu = @import("gpu.zig");

pub fn main() !void {
    const device = gpu.createGPUDevice(true);
    defer if (device) |d| d.destroyGPUDevice();
    
    // All dependency types available automatically
}

Run Tests

zig build test

Contributing

See DEVELOPMENT.md for:

• Architecture overview
• Adding new patterns
• Testing guidelines
• Code style

License

Part of the Backlog game engine project.

Acknowledgments

Developed for automatic SDL3 binding generation in the Backlog engine.

---

Version: 2.1
Status: Production ready for SDL_gpu.h
Last Updated: 2026-01-22