Backlog/lib/sdl3/parser/docs/KNOWN_ISSUES.md

Known Issues and Limitations

This document lists current limitations of the SDL3 header parser.

Production Ready ✅

SDL_gpu.h

• Status: 100% working
• Dependencies: All resolved automatically
• Output: Production-ready Zig bindings
• Issue: 1 minor (field name type shadows keyword)

Known Limitations

1. Field Names That Shadow Zig Keywords

Issue: Fields named type, error, if, etc. cause compilation errors

Example:

typedef struct {
    int type;  // Shadows Zig keyword
} SDL_Something;

Error:

error: name shadows primitive 'type'

Workaround: Manual edit

// Change:
type: GPUTextureType,

// To:
@"type": GPUTextureType,

Priority: Low
Effort: ~30 minutes to auto-escape
Frequency: Rare (a few SDL structs)

2. Large Enum Parsing

Issue: Enums with 300+ values generate syntax errors

Affected:

• SDL_Scancode (300+ keyboard scancodes)
• SDL_Keycode (300+ key codes)

Example:

typedef enum {
    SDL_SCANCODE_A = 4,
    SDL_SCANCODE_B = 5,
    // ... 300 more values
} SDL_Scancode;

Error: 77+ syntax errors in generated enum

Root Cause: Special enum value expressions not fully supported

Workaround: Manual enum definition or use C directly

Priority: High (blocks SDL_keyboard.h)
Effort: ~1-2 hours
Status: Documented in MULTI_HEADER_TEST_RESULTS.md

3. Function Pointer Typedefs

Issue: Function pointer types not parsed

Example:

typedef void (*SDL_HitTest)(SDL_Window *window, const SDL_Point *pt, void *data);
typedef int (*SDL_EventFilter)(void *userdata, SDL_Event *event);

Impact: Callback types not auto-resolved

Workaround: Manual definition

pub const HitTest = *const fn(?*Window, *const Point, ?*anyopaque) callconv(.C) void;

Priority: Medium
Effort: ~2-3 hours
Frequency: Uncommon in SDL public API

4. SDL_UINT64_C Macro in Bit Positions

Issue: Some 64-bit flag patterns may not parse correctly

Example:

#define SDL_WINDOW_FULLSCREEN SDL_UINT64_C(0x0000000000000001)

Status: Enhanced support added, but not fully tested

Workaround: Manual flag definitions if needed

Priority: Medium
Effort: ~30 minutes validation
Affected: SDL_video.h WindowFlags

5. External Library Types

Issue: Types from external libraries (EGL, OpenGL) not found

Example:

SDL_EGLConfig
SDL_EGLDisplay
SDL_GLContext

Status: Expected behavior (not SDL types)

Workaround: Use C imports or manual definitions

Priority: N/A (expected)

6. Memory Leaks in Comment Handling

Issue: Small memory leaks (4-8 allocations per run) in struct comment parsing

Impact: ~1-2KB leaked per parse

Status: Functional but should be fixed

Priority: Low
Effort: ~30 minutes

7. Array Field Declarations

Issue: Array fields in multi-field syntax not supported

Example:

int array1[10], array2[20];  // Not handled

Workaround: Rare in SDL, can be manually defined

Priority: Low
Effort: ~1 hour

8. Bit Field Declarations

Issue: Bit fields not supported

Example:

struct {
    unsigned a : 4;
    unsigned b : 4;
};

Status: Not used in SDL public API

Priority: Very Low

Workaround Strategies

Strategy 1: Manual Type Definitions

Create a supplementary file with missing types:

// manual_types.zig
pub const HitTest = *const fn(?*Window, *const Point, ?*anyopaque) callconv(.C) void;
pub const Scancode = c_int;  // Simplified if full enum not needed

Strategy 2: Direct C Import

For problematic types, use C directly:

const c = @cImport(@cInclude("SDL3/SDL.h"));
pub const Scancode = c.SDL_Scancode;

Strategy 3: Selective Generation

Only generate for headers that work:

# These work well:
zig build run -- SDL_gpu.h --output=gpu.zig
zig build run -- SDL_properties.h --output=properties.zig

# These need work:
# SDL_keyboard.h, SDL_events.h (use C import for now)

Testing Results by Header

✅ Fully Working

Header	Declarations	Dependencies	Issues
SDL_gpu.h	169	5/5 (100%)	1 minor (field name)

⚠️ Partial Support

Header	Dependencies Resolved	Main Issue
SDL_keyboard.h	6/6 (100%)	Large enum syntax errors
SDL_video.h	5/14 (36%)	Bit position parsing
SDL_events.h	Unknown	Parse errors

Error Messages Explained

"Could not find definition for type: X"

Meaning: Type referenced but not found in any included header

Possible Causes:

1. Type is a function pointer (not supported)
2. Type is external (EGL, GL) (expected)
3. Type is in a header not included
4. Type uses unsupported pattern

Action: Check if type is needed, add manually if so

"Syntax errors detected in generated code"

Meaning: Generated Zig code doesn't parse

Possible Causes:

1. Large enum parsing issue
2. Field name shadows keyword
3. Unsupported C pattern

Action: Check line numbers in error, see if manual fix needed

"InvalidBitPosition"

Meaning: Flag value pattern not recognized

Possible Causes:

1. Uses SDL_UINT64_C macro (partially supported)
2. Complex bit expression
3. Non-standard format

Action: May need to manually define flags

Memory Leak Warnings

Meaning: Small allocations not freed

Impact: Minimal (1-2KB per run)

Status: Known issue in comment handling, functional

Action: None required (will be fixed in future)

Supported vs Unsupported

✅ Fully Supported

• Opaque types
• Simple structs
• Multi-field structs (int x, y;)
• Enums (up to ~100 values)
• Flags (with standard patterns)
• Typedefs (simple type aliases)
• Functions (extern declarations)
• Dependency resolution
• Type conversion
• Method grouping

⚠️ Partially Supported

• Large enums (300+ values) - needs work
• SDL_UINT64_C flags - enhanced but not fully tested
• Some bit position patterns

❌ Not Supported

• Function pointer typedefs
• #define-based type definitions (without typedef)
• Union types
• Bit field structs
• Complex macro expressions
• Non-SDL types

Reporting Issues

When encountering a new issue:

1. Check this document - May already be known
2. Test with simple case - Isolate the problem
3. Check generated output - Look at line numbers in errors
4. Document the pattern - Save example for future reference

Future Improvements

High Priority

1. Large enum support - Would enable SDL_keyboard.h
2. SDL_UINT64_C validation - Complete SDL_video.h support

Medium Priority

3. Function pointer typedefs - For callback types
4. Field name escaping - Auto-fix keyword shadowing
5. Memory leak cleanup - Fix comment handling

Low Priority

6. Union support - Rarely used in SDL
7. Bit field support - Not in SDL public API
8. Array fields - Uncommon pattern

Comparison with Manual Approach

Manual Binding Creation

Time: ~30 minutes per header Error Rate: High (missing fields, wrong types) Maintenance: Manual updates needed Consistency: Varies by developer

Parser Approach

Time: ~0.5 seconds Error Rate: Low (for supported patterns) Maintenance: Automatic with SDL updates Consistency: Perfect (deterministic)

Conclusion: Parser is vastly superior for supported patterns, with clear workarounds for unsupported cases.

---

Status: Production ready for SDL_gpu.h, partial support for other headers.
Recommendation: Use parser for SDL_gpu.h, evaluate others case-by-case.
Next: See Development for how to fix remaining issues.