sdlparser-scrap/AGENTS.md

SDL3 Header Parser - Agent Documentation

Project Overview

This is an SDL3 header parser that converts C header files into Zig interfaces, JSON objects, and C mocks. Built specifically for SDL3 headers (developed against SDL 3.2.10), it focuses on generating Zig APIs.

Key Points:

• Not a real C parser - best-effort text transformation specifically for SDL3 headers
• Does not do proper AST elaboration or tokenization
• Simple to modify but brittle
• Requires Zig 0.15.2 and git

Architecture

The codebase consists of several modules:

• parser.zig - Main entry point and orchestration
• patterns.zig - SDL3 pattern matching and declaration scanning
• codegen.zig - Zig code generation
• mock_codegen.zig - C mock generation
• json_serializer.zig - JSON output generation
• dependency_resolver.zig - Type dependency resolution
• header_cache.zig - Header caching for cross-file type resolution
• io.zig - Error handling utilities
• types.zig - Type mapping and conversions
• naming.zig - Naming conventions

Developing

Error Handling

CRITICAL: Whenever actual errors are encountered (parsing failures, invalid declarations, missing types, etc.), you MUST call io.emitError to report them properly. Do NOT use std.debug.print for actual errors.

// Good - proper error reporting
try io.emitError(allocator, "Failed to parse struct field: {s}", .{field_name});

// Bad - don't use for errors
std.debug.print("Error: Failed to parse...\n", .{});

Validation Process

After generating Zig code:

1. Output written to tmp/ directory
2. zig ast-check runs on the temporary file
3. If passes: zig fmt runs, then copied to final destination
4. If fails: debug output written to debug/ with _fmterror.zig suffix

Memory Management

• Two cleanup functions exist with identical logic:
  • freeDecls() - frees a slice of declarations
  • freeDeclDeep() - frees a single declaration
• Both free all nested allocations (names, types, doc comments, params/fields/values/flags)

Main APIs (Priority)

Focus areas: gpu, video, gamepad, joystick, input, event

Anything beyond these is not actively maintained.