sdlparser-scrap/docs/QUICKSTART.md

SDL3 Parser - Quick Start Guide

What It Does

Automatically generates Zig bindings from SDL3 C headers with automatic dependency resolution.

Installation & Build

cd parser/
zig build          # Build parser executable
zig build test     # Run all tests

Basic Usage

Parse a Header

# Output to stdout
zig build run -- ../SDL/include/SDL3/SDL_gpu.h

# Output to file
zig build run -- ../SDL/include/SDL3/SDL_gpu.h --output=gpu.zig

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

What It Generates

Input (SDL_gpu.h excerpt):

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);
    }
};

Features

✅ Supported C Patterns

• Opaque types: typedef struct SDL_Type SDL_Type;
• Enums: typedef enum { VALUE1, VALUE2 } SDL_Type;
• Structs: typedef struct { int field; } SDL_Type;
• Flags: Packed bitfield enums
• Functions: extern SDL_DECLSPEC RetType SDLCALL SDL_Func(...);

✅ Automatic Dependency Resolution

• Detects types referenced but not defined
• Searches included headers for definitions
• Automatically includes needed types in output
• Handles: SDL_FColor, SDL_Rect, SDL_Window, SDL_FlipMode, etc.

✅ Type Conversion

C Type	Zig Type
bool	bool
Uint32	u32
SDL_Type*	?*Type (nullable)
const SDL_Type*	*const Type
void*	?*anyopaque
const char*	[*c]const u8

✅ Naming Conventions

• Strip SDL_ prefix: SDL_GPUDevice → GPUDevice
• Remove first underscore: SDL_GPU_Type → GPUType
• camelCase functions: SDL_CreateDevice → createDevice

Current Limitations

⚠️ Not Yet Supported

1. Multi-field structs: int x, y; (parsed as single field)

   • Workaround: Manually expand or wait for next version

2. Simple typedefs: typedef Uint32 SDL_Type;

   • Workaround: Add manually to output

3. #define constants: #define VALUE (1u << 0)

   • Workaround: Use clang preprocessor or manual definitions

Project Structure

parser/
├── src/
│   ├── parser.zig              # Main entry point
│   ├── patterns.zig            # Pattern matching & scanning
│   ├── types.zig               # C to Zig type conversion
│   ├── naming.zig              # Naming conventions
│   ├── codegen.zig             # Zig code generation
│   ├── mock_codegen.zig        # C mock generation
│   └── dependency_resolver.zig # Dependency analysis [NEW]
├── test/                       # Test files
├── docs/                       # Documentation
├── build.zig                   # Build configuration
└── README.md                   # Full documentation

Documentation

• PARSER_OVERVIEW.md - How the parser works
• DEPENDENCY_PLAN.md - Original dependency design
• DEPENDENCY_IMPLEMENTATION_STATUS.md - Current status
• IMPLEMENTATION_SUMMARY.md - Session summary
• AGENTS.md - Zig 0.15 guidelines for AI agents
• TODO.md - Next steps

Testing

# Run all tests
zig build test

# Test with specific header
zig build run -- ../SDL/include/SDL3/SDL_gpu.h --output=test_output.zig

# Verify output compiles (requires c.zig)
zig ast-check test_output.zig

Example Workflow

1. Parse header with dependencies:

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

2. Check the output:

   cat gpu.zig | head -50
   

3. Create c.zig wrapper:

   pub const c = @cImport({
       @cInclude("SDL3/SDL.h");
   });
   

4. Use in your project:

   const gpu = @import("gpu.zig");
   
   pub fn main() !void {
       const device = gpu.createGPUDevice(true);
       defer device.?.destroyGPUDevice();
   }
   

Common Issues

"FileNotFound" error

• Check header path is correct relative to working directory
• Use absolute path: /full/path/to/SDL/include/SDL3/SDL_gpu.h

"Syntax errors detected"

• Usually multi-field struct issue (known limitation)
• Check output file for specific line numbers
• Manually fix or wait for parser update

"Warning: Could not find definition for type"

• Type might be typedef (not yet supported)
• Type might be in different include (check manually)
• Type might be #define-based (use manual definition)

Performance

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

Getting Help

1. Check DEPENDENCY_IMPLEMENTATION_STATUS.md for known issues
2. Look at TODO.md for planned improvements
3. Read AGENTS.md if you're an AI agent working on this
4. Check test files in test/ for usage examples

Version Info

• Parser Version: 2.0 (with dependency resolution)
• Zig Version: 0.15.2
• SDL Version: 3.2.0
• Status: Operational with known limitations ✅

---

Last Updated: 2026-01-22 Next Milestone: Fix multi-field struct parsing