2.9 KiB

Raw Blame History

SDL3 Parser - Overview

What It Does

Automatically generates type-safe Zig bindings and C mock implementations from SDL3 C headers.

How It Works

1. Lexical Analysis (patterns.zig)

Scans C header files for SDL API patterns
Extracts 5 declaration types:
- Opaque types: typedef struct SDL_Type SDL_Type;
- Enums: typedef enum { ... } SDL_Type;
- Structs: typedef struct { ... } SDL_Type;
- Flags: Packed bitfields from enums
- Functions: extern SDL_DECLSPEC RetType SDLCALL SDL_Func(...);

2. Type Conversion (types.zig)

Maps C types to Zig equivalents:
- bool → bool
- Uint32 → u32
- SDL_Type* → ?*Type (nullable) or *Type (non-null)
- void* → ?*anyopaque
- const char* → [*c]const u8

3. Naming Convention (naming.zig)

Strips SDL_ prefix
Removes first underscore for grouping: SDL_GPU_Device → GPUDevice
Converts to camelCase: SDL_CreateGPUDevice → createGPUDevice

4. Code Generation (codegen.zig)

Groups methods: Functions with matching first parameter go inside opaque type
Generates inline wrappers: Handle casting between Zig and C types
Formats output: Uses Zig AST for proper formatting

5. Mock Generation (mock_codegen.zig)

Creates C stub implementations for testing
Includes actual SDL headers for type definitions
Returns null/0/false for all functions

Example

Input (SDL_gpu.h):

typedef struct SDL_GPUDevice SDL_GPUDevice;
extern SDL_DECLSPEC SDL_GPUDevice* SDLCALL SDL_CreateGPUDevice(bool debug);

Output Zig (gpu.zig):

pub const GPUDevice = opaque {};

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

Output Mock (gpu_mock.c):

#include <SDL3/SDL_gpu.h>

SDL_GPUDevice* SDL_CreateGPUDevice(bool debug) {
    (void)debug;
    return NULL;
}

Usage

# Generate bindings only
zig build run -- SDL_gpu.h --output=gpu.zig

# Generate bindings + mocks
zig build run -- SDL_gpu.h --output=gpu.zig --mocks=gpu_mock.c

# Test with SDL_gpu.h
zig build test-mocks

Architecture

C Header → Scanner → AST → Type Mapper → Code Generator → Zig Bindings
                                      ↓
                                  Mock Generator → C Mocks

Statistics (SDL_gpu.h)

Input: 169 declarations
Output: 1,229 lines of Zig, 577 lines of C mocks
Compilation: 71KB static library, 94 exported functions
Tests: 7/7 passing

Key Features

✅ Type-safe pointer handling (nullable vs non-null) ✅ Automatic method grouping in opaque types ✅ Minimal casting (only where needed) ✅ AST-based formatting ✅ C mocks with real SDL headers ✅ Handles large headers (169+ declarations)

Limitations

No dependency resolution (types from other headers)
No #define parsing (except simple enums)
No function pointer types
No union types
Requires manual c.zig for imports

2.9 KiB Raw Blame History