147 lines
3.7 KiB
Markdown
147 lines
3.7 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
cd lib/sdl3/parser
|
|
zig build
|
|
```
|
|
|
|
### Parse a Header
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Unit tests
|
|
zig build test
|
|
|
|
# Test harness (planned)
|
|
cd test_project
|
|
zig build test
|
|
```
|
|
|
|
## Output Example
|
|
|
|
**Input (C):**
|
|
```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):**
|
|
```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](architecture.md) for details.
|
|
|
|
## Documentation
|
|
|
|
- [Architecture](architecture.md) - System design and components
|
|
- [Usage Guide](usage.md) - Detailed usage instructions
|
|
- [Naming Conventions](naming.md) - How C names map to Zig
|
|
- [Test Harness Plan](../TEST_HARNESS_PLAN_V2.md) - 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](../TEST_HARNESS_PLAN_V2.md) 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](../IMPLEMENTATION_COMPLETE.md) for detailed changes.
|
|
|
|
## License
|
|
|
|
Part of the Backlog game engine project.
|