57 lines
2.1 KiB
Markdown
57 lines
2.1 KiB
Markdown
# 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.
|
|
|
|
```zig
|
|
// 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.
|