Backlog/lib/sdl3/parser/docs/README.md

SDL3 Parser - C to Zig Binding Generator

A robust parser that automatically generates idiomatic Zig bindings from SDL3 C header files.

Overview

The SDL3 Parser analyzes C header files and generates type-safe Zig code with proper naming conventions, memory safety, and zero-cost abstractions. It handles opaque types, enums, structs, flags, and function declarations.

Features

• ✅ Automatic binding generation - Parse C headers and output Zig code
• ✅ Idiomatic naming - Converts C naming to Zig conventions
• ✅ Type safety - Generates packed structs for flags, enums with backing types
• ✅ Zero overhead - Inline function wrappers with proper casts
• ✅ Memory safe - No memory leaks, validated with GPA
• ✅ Well tested - 18+ unit tests, integration tested with SDL_gpu.h

Quick Start

Build

cd lib/sdl3/parser
zig build

Parse a Header

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

# With C mocks (planned feature)
zig build run -- ../SDL/include/SDL3/SDL_gpu.h --mocks

Run Tests

# Unit tests
zig build test

# Test harness (planned)
cd test_project
zig build test

Output Example

Input (C):

typedef struct SDL_GPUDevice SDL_GPUDevice;

typedef enum SDL_GPUPrimitiveType {
    SDL_GPU_PRIMITIVETYPE_TRIANGLELIST,
    SDL_GPU_PRIMITIVETYPE_TRIANGLESTRIP,
} SDL_GPUPrimitiveType;

typedef Uint32 SDL_GPUTextureUsageFlags;
#define SDL_GPU_TEXTUREUSAGE_SAMPLER (1u << 0)
#define SDL_GPU_TEXTUREUSAGE_COLOR_TARGET (1u << 1)

extern SDL_DECLSPEC SDL_GPUDevice* SDLCALL SDL_CreateGPUDevice(bool debug_mode);

Output (Zig):

pub const GPUDevice = opaque {};

pub const GPUPrimitiveType = enum(c_int) {
    primitivetypeTrianglelist,
    primitivetypeTrianglestrip,
};

pub const GPUTextureUsageFlags = packed struct(u32) {
    textureusageSampler: bool = false,
    textureusageColorTarget: bool = false,
    pad0: u29 = 0,
    rsvd: bool = false,
};

pub inline fn createGPUDevice(debug_mode: bool) ?*GPUDevice {
    return @ptrCast(c.SDL_CreateGPUDevice(debug_mode));
}

Architecture

The parser consists of four main components:

1. Scanner (patterns.zig) - Lexical analysis and pattern matching
2. Naming (naming.zig) - C to Zig name conversion
3. Types (types.zig) - C to Zig type mapping
4. CodeGen (codegen.zig) - Zig code generation

See Architecture for details.

Documentation

• Architecture - System design and components
• Usage Guide - Detailed usage instructions
• Naming Conventions - How C names map to Zig
• Test Harness Plan - Planned testing infrastructure

Project Status

Completed ✅

• Core parser functionality
• All C declaration types supported
• Proper naming conventions
• Memory leak free
• Comprehensive unit tests
• Integration tested with SDL_gpu.h

Planned 🚧

• C mock generation (--mocks flag)
• Complete test harness with linkage testing
• Golden file regression testing
• Multiple header support
• Performance benchmarking

Requirements

• Zig 0.14+ (tested with 0.15.2)
• SDL3 headers (for input)
• No runtime dependencies

Contributing

The parser is currently under active development. See the Test Harness Plan for upcoming features.

Recent Changes

Version 2024-01 (Current)

• Fixed critical flag parsing bug (empty structs)
• Fixed invalid identifier generation (numeric prefixes)
• Implemented "first underscore" naming rule
• Added 13 new unit tests
• Memory leak fixes
• Comprehensive documentation

See IMPLEMENTATION_COMPLETE.md for detailed changes.

License

Part of the Backlog game engine project.