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

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

## Basic Usage

### Parse a Header

```bash
# 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):
```c
typedef struct SDL_GPUDevice SDL_GPUDevice;
extern SDL_DECLSPEC void SDLCALL SDL_DestroyGPUDevice(SDL_GPUDevice *device);
```

**Output** (`gpu.zig`):
```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

```bash
# 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**:
   ```bash
   zig build run -- ../SDL/include/SDL3/SDL_gpu.h --output=gpu.zig
   ```

2. **Check the output**:
   ```bash
   cat gpu.zig | head -50
   ```

3. **Create c.zig wrapper**:
   ```zig
   pub const c = @cImport({
       @cInclude("SDL3/SDL.h");
   });
   ```

4. **Use in your project**:
   ```zig
   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