sdlparser-scrap/docs/GETTING_STARTED.md

# Getting Started with SDL3 Parser

This guide will help you get up and running with the SDL3 header parser.

## Prerequisites

- Zig 0.15 or later
- SDL3 headers (included in `../SDL/include/SDL3/`)

## Installation

1. Navigate to the parser directory:
```bash
cd lib/sdl3/parser
```

2. Build the parser:
```bash
zig build
```

3. Run tests to verify installation:
```bash
zig build test
```

You should see: `All tests passed.`

## Your First Parse

### Step 1: Parse SDL_gpu.h

```bash
zig build run -- ../SDL/include/SDL3/SDL_gpu.h --output=my_gpu.zig
```

You'll see output like:
```
SDL3 Header Parser
==================

Parsing: ../SDL/include/SDL3/SDL_gpu.h

Found 169 declarations
  - Opaque types: 13
  - Typedefs: 6
  - Enums: 24
  - Structs: 35
  - Flags: 3
  - Functions: 94

Analyzing dependencies...
Found 5 missing types:
  - SDL_FColor
  - SDL_PropertiesID
  - SDL_Rect
  - SDL_Window
  - SDL_FlipMode

Resolving dependencies from included headers...
  ✓ Found SDL_FColor in SDL_pixels.h
  ✓ Found SDL_PropertiesID in SDL_properties.h
  ✓ Found SDL_Rect in SDL_rect.h
  ✓ Found SDL_Window in SDL_video.h
  ✓ Found SDL_FlipMode in SDL_surface.h

Combining 5 dependency declarations with primary declarations...
Generated: my_gpu.zig
```

### Step 2: Examine the Output

```bash
head -50 my_gpu.zig
```

You'll see clean Zig bindings:
```zig
pub const c = @import("c.zig").c;

// Dependencies (automatically included)
pub const FColor = extern struct {
    r: f32,
    g: f32,
    b: f32,
    a: f32,
};

pub const PropertiesID = u32;

pub const Rect = extern struct {
    x: c_int,
    y: c_int,
    w: c_int,
    h: c_int,
};

pub const Window = opaque {};

// Primary declarations
pub const GPUDevice = opaque {
    pub inline fn destroyGPUDevice(gpudevice: *GPUDevice) void {
        return c.SDL_DestroyGPUDevice(gpudevice);
    }
    // ... 93 more methods
};
```

### Step 3: Create c.zig Wrapper

Create a file `c.zig` that imports SDL:
```zig
pub const c = @cImport({
    @cInclude("SDL3/SDL.h");
});
```

### Step 4: Use in Your Project

```zig
const std = @import("std");
const gpu = @import("my_gpu.zig");

pub fn main() !void {
    const device = gpu.createGPUDevice(true);
    if (device) |d| {
        defer d.destroyGPUDevice();
        
        const driver = d.getGPUDeviceDriver();
        std.debug.print("GPU Driver: {s}\n", .{driver});
    }
}
```

## Command-Line Options

### Basic Options

```bash
# Output to file
zig build run -- header.h --output=output.zig

# Output to stdout
zig build run -- header.h
```

### Mock Generation

```bash
# Generate C mocks for testing
zig build run -- header.h --output=bindings.zig --mocks=mocks.c
```

The mock file contains stub implementations that return zero/null:
```c
void SDL_DestroyGPUDevice(SDL_GPUDevice *device) {
    // Mock implementation
}
```

## Understanding the Output

### Type Name Conversion

The parser follows consistent naming rules:

| C Name | Zig Name | Rule |
|--------|----------|------|
| `SDL_GPUDevice` | `GPUDevice` | Strip `SDL_` prefix |
| `SDL_GPU_PRIMITIVE_TYPE_TRIANGLELIST` | `primitiveTypeTrianglelist` | Strip prefix, camelCase |
| `SDL_CreateGPUDevice` | `createGPUDevice` | Strip `SDL_`, camelCase |

### Method Grouping

Functions are organized as methods when possible:

**C API**:
```c
void SDL_DestroyGPUDevice(SDL_GPUDevice *device);
const char* SDL_GetGPUDeviceDriver(SDL_GPUDevice *device);
```

**Generated Zig**:
```zig
pub const GPUDevice = opaque {
    pub inline fn destroyGPUDevice(self: *GPUDevice) void { ... }
    pub inline fn getGPUDeviceDriver(self: *GPUDevice) [*c]const u8 { ... }
};
```

Usage becomes:
```zig
device.destroyGPUDevice();  // Instead of SDL_DestroyGPUDevice(device)
```

### Dependency Inclusion

Dependencies are automatically detected and included at the top of the file:

```zig
// Dependencies from included headers
pub const FColor = extern struct { ... };
pub const Rect = extern struct { ... };
pub const Window = opaque {};

// Primary declarations from SDL_gpu.h
pub const GPUDevice = opaque { ... };
```

## Common Workflows

### Generate Bindings for a Module

```bash
# From lib/sdl3 directory
zig build regenerate-zig
```

This generates bindings for configured headers in `v2/` directory.

### Test Your Changes

After modifying the parser:

```bash
# Run unit tests
zig build test

# Test with a real header
zig build run -- ../SDL/include/SDL3/SDL_gpu.h --output=test.zig

# Verify output compiles
zig ast-check test.zig
```

### Debug Issues

If you encounter errors:

1. Check the console output for warnings about missing types
2. Look at the generated file for syntax errors
3. See [Known Issues](docs/KNOWN_ISSUES.md) for common problems

## Next Steps

- Read [Architecture](docs/ARCHITECTURE.md) to understand how it works
- See [Dependency Resolution](docs/DEPENDENCY_RESOLUTION.md) for details on automatic type extraction
- Check [Known Issues](docs/KNOWN_ISSUES.md) for current limitations
- Review [Development](docs/DEVELOPMENT.md) to contribute

## Quick Reference

```bash
# Build
zig build

# Test
zig build test

# Generate bindings
zig build run -- <header> --output=<output>

# Generate with mocks
zig build run -- <header> --output=<output> --mocks=<mocks>

# Generate all configured headers
cd .. && zig build regenerate-zig
```

## Getting Help

- **Documentation**: See `docs/` directory
- **Examples**: Check `test/` directory for usage examples
- **Issues**: See `docs/KNOWN_ISSUES.md`

---

**Next**: Read [Architecture](docs/ARCHITECTURE.md) to understand the parser internals.