Backlog/lib/sdl3/parser/docs/archive/CRITICAL_ISSUE.md

Critical Issue: Missing Cross-Header Dependencies

The Problem

The parser successfully generates code from SDL_gpu.h, but the generated code doesn't compile on its own because it references types from other SDL headers that aren't defined.

Example

Generated code (gpu_test.zig):

pub inline fn windowSupportsGPUSwapchainComposition(
    gpudevice: *GPUDevice, 
    window: ?*Window,  // ❌ Window is undefined!
    swapchain_composition: GPUSwapchainComposition
) bool { ... }

pub inline fn setGPUScissor(
    gpurenderpass: *GPURenderPass, 
    scissor: *const Rect  // ❌ Rect is undefined!
) void { ... }

pub inline fn setGPUBlendConstants(
    gpurenderpass: *GPURenderPass, 
    blend_constants: FColor  // ❌ FColor is undefined!
) void { ... }

If you try to import the generated file:

const gpu = @import("zig-out/gpu_test.zig"); // FAILS!

// Error: use of undeclared identifier 'Window'
// Error: use of undeclared identifier 'Rect'
// Error: use of undeclared identifier 'FColor'

Missing Types

From SDL_gpu.h's includes, these types are referenced but not defined:

Type	Source Header	Usage Count	Used In
Window	SDL_video.h	8+ functions	Window management functions
Rect	SDL_rect.h	2+ functions	Scissor rectangle, viewport
FColor	SDL_pixels.h	2+ functions	Blend constants, clear color
FlipMode	SDL_surface.h	1+ functions	GPU blit operations
PropertiesID	SDL_properties.h	5+ functions	Extension properties

Why Tests Still Pass

Our current test suite (mock_test.zig) manually defines these types as a workaround:

// We had to add these manually!
pub const Window = opaque {};
pub const Rect = extern struct { x: i32, y: i32, w: i32, h: i32 };
pub const FColor = extern struct { r: f32, g: f32, b: f32, a: f32 };

This hides the problem. If anyone tries to actually USE the generated gpu_test.zig, it won't compile.

The Real-World Impact

# This works (generates code)
zig build regenerate-test-mocks

# This works (tests with manual definitions)
zig build test-mocks  # 9/9 passing

# This FAILS (try to use generated code)
const gpu = @import("gpu_test.zig");
# error: use of undeclared identifier 'Window'
# error: use of undeclared identifier 'Rect'
# error: use of undeclared identifier 'FColor'

Proof of Issue

Run:

zig build test-import-issue

This demonstrates:

1. The generated code references undefined types
2. Tests only pass because we manually defined them
3. Real usage would fail

The Solution (See DEPENDENCY_PLAN.md)

The parser needs to:

1. Detect missing types - Scan generated declarations for types not defined in the current header
2. Parse included headers - Extract definitions from SDL_video.h, SDL_rect.h, etc.
3. Generate dependency modules - Create video.zig, rect.zig, pixels.zig with ONLY needed types
4. Add imports - Generate imports at top of gpu.zig:

   pub const Window = @import("video.zig").Window;
   pub const Rect = @import("rect.zig").Rect;
   // etc.
   

Current Status

• ✅ Parser generates syntactically valid code
• ✅ Parser handles all SDL_gpu.h declarations (169 total)
• ✅ Tests pass (with manual type definitions)
• ❌ Generated code doesn't compile standalone
• ❌ Cannot be used without manual intervention

Next Steps

Implement dependency resolution as outlined in DEPENDENCY_PLAN.md:

1. Phase 1: Dependency detection (scan for undefined types)
2. Phase 2: Selective type extraction (parse included headers)
3. Phase 3: Code generation (create dependency modules)
4. Phase 4: Import generation (link everything together)

This is the critical blocker for production use of the parser.

---

Date: 2026-01-22 Status: Critical Issue Identified 🔴 Tests: 9/9 passing (but hiding the issue)