214 lines
5.5 KiB
Markdown
214 lines
5.5 KiB
Markdown
# SDL3 Parser - Project Structure
|
|
|
|
```
|
|
parser/
|
|
├── README.md # Project overview and quick start
|
|
├── build.zig # Build configuration
|
|
├── build.zig.zon # Dependencies
|
|
│
|
|
├── src/ # Source code (900 lines)
|
|
│ ├── parser.zig # Main entry point, CLI
|
|
│ ├── patterns.zig # Pattern matching & scanning
|
|
│ ├── types.zig # C to Zig type conversion
|
|
│ ├── naming.zig # Naming convention handling
|
|
│ ├── codegen.zig # Zig code generation
|
|
│ ├── mock_codegen.zig # C mock generation
|
|
│ └── dependency_resolver.zig # Dependency analysis (NEW)
|
|
│
|
|
├── test/ # Test files
|
|
│ ├── integration/ # Integration tests
|
|
│ │ ├── test_multifield_*.zig
|
|
│ │ ├── test_typedef_*.zig
|
|
│ │ └── test_flow_*.zig
|
|
│ └── (pattern test files)
|
|
│
|
|
├── docs/ # Documentation (5,500+ lines)
|
|
│ ├── INDEX.md # Documentation index
|
|
│ │
|
|
│ ├── GETTING_STARTED.md # Installation and first use
|
|
│ ├── QUICKSTART.md # Quick reference
|
|
│ ├── API_REFERENCE.md # Command-line options
|
|
│ │
|
|
│ ├── ARCHITECTURE.md # System design
|
|
│ ├── DEPENDENCY_RESOLUTION.md # How deps work
|
|
│ ├── KNOWN_ISSUES.md # Limitations
|
|
│ │
|
|
│ ├── DEVELOPMENT.md # Contributing guide
|
|
│ ├── ROADMAP.md # Future plans
|
|
│ │
|
|
│ ├── DEPENDENCY_FLOW.md # Technical deep dive
|
|
│ ├── VISUAL_FLOW.md # Flow diagrams
|
|
│ ├── MULTI_FIELD_IMPLEMENTATION.md
|
|
│ ├── TYPEDEF_IMPLEMENTATION.md
|
|
│ ├── MULTI_HEADER_TEST_RESULTS.md
|
|
│ │
|
|
│ └── archive/ # Historical documents
|
|
│ └── (planning and status docs)
|
|
│
|
|
└── zig-out/ # Build artifacts
|
|
└── bin/sdl-parser # Executable
|
|
```
|
|
|
|
## Documentation Organization
|
|
|
|
### User Documentation (Start Here)
|
|
1. README.md - Project overview
|
|
2. GETTING_STARTED.md - Tutorial
|
|
3. QUICKSTART.md - Quick reference
|
|
4. API_REFERENCE.md - Complete reference
|
|
|
|
### Technical Documentation
|
|
5. ARCHITECTURE.md - System design
|
|
6. DEPENDENCY_RESOLUTION.md - Feature details
|
|
7. DEPENDENCY_FLOW.md - Implementation walkthrough
|
|
8. VISUAL_FLOW.md - Diagrams
|
|
|
|
### Development Documentation
|
|
9. DEVELOPMENT.md - Contributing guide
|
|
10. KNOWN_ISSUES.md - Current limitations
|
|
11. ROADMAP.md - Future plans
|
|
|
|
### Implementation Documentation
|
|
12. MULTI_FIELD_IMPLEMENTATION.md - Struct parsing
|
|
13. TYPEDEF_IMPLEMENTATION.md - Typedef support
|
|
14. MULTI_HEADER_TEST_RESULTS.md - Test results
|
|
|
|
## Source Code Organization
|
|
|
|
### Core Pipeline
|
|
|
|
```
|
|
parser.zig (main)
|
|
↓
|
|
patterns.zig (scan)
|
|
↓
|
|
dependency_resolver.zig (resolve)
|
|
↓
|
|
codegen.zig (generate)
|
|
↓
|
|
Output (Zig/C)
|
|
```
|
|
|
|
### Supporting Modules
|
|
|
|
- `types.zig` - Type conversion utilities
|
|
- `naming.zig` - Naming convention utilities
|
|
- `mock_codegen.zig` - C mock generation
|
|
|
|
## Build Outputs
|
|
|
|
### Local Build
|
|
|
|
```
|
|
zig-out/
|
|
├── bin/
|
|
│ └── sdl-parser # Executable
|
|
└── (test outputs)
|
|
```
|
|
|
|
### Integration with lib/sdl3
|
|
|
|
```
|
|
lib/sdl3/
|
|
├── v2/ # Generated bindings
|
|
│ ├── gpu.zig # SDL_gpu.h bindings
|
|
│ ├── video.zig # SDL_video.h (if working)
|
|
│ └── ...
|
|
└── zig-out/
|
|
├── gpu_test.zig # Test bindings
|
|
└── gpu_test_mock.c # Test mocks
|
|
```
|
|
|
|
## Test Organization
|
|
|
|
### Unit Tests (in source files)
|
|
|
|
Each src/*.zig file contains tests at the bottom:
|
|
- Pattern matching tests
|
|
- Type conversion tests
|
|
- Naming convention tests
|
|
|
|
### Integration Tests (test/integration/)
|
|
|
|
- `test_multifield_*.zig` - Multi-field struct parsing
|
|
- `test_typedef_*.zig` - Typedef scanning
|
|
- `test_flow_*.zig` - Dependency resolution
|
|
- `test_*.c` - Test input files
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# All tests
|
|
zig build test
|
|
|
|
# Specific test file
|
|
zig test test/integration/test_typedef_simple.zig
|
|
```
|
|
|
|
## Documentation Categories
|
|
|
|
### For Users
|
|
- Getting started, quickstart, API reference
|
|
- Focus: How to use the tool
|
|
|
|
### For Understanding
|
|
- Architecture, dependency resolution
|
|
- Focus: How it works internally
|
|
|
|
### For Developers
|
|
- Development guide, implementation docs
|
|
- Focus: How to extend and contribute
|
|
|
|
### For Reference
|
|
- Technical deep dives, flow diagrams
|
|
- Focus: Complete implementation details
|
|
|
|
## File Size Reference
|
|
|
|
### Source Code
|
|
- Total: ~900 lines production code
|
|
- Average: ~150 lines per module
|
|
- Largest: dependency_resolver.zig (454 lines)
|
|
|
|
### Documentation
|
|
- Total: ~5,500 lines
|
|
- User guides: ~1,500 lines
|
|
- Technical docs: ~2,500 lines
|
|
- Implementation details: ~1,500 lines
|
|
|
|
### Tests
|
|
- Unit tests: ~400 lines (in source files)
|
|
- Integration tests: ~500 lines (separate files)
|
|
- Total: ~900 lines
|
|
|
|
## Quick Navigation
|
|
|
|
```bash
|
|
# Main documentation entry point
|
|
cat README.md
|
|
|
|
# Start tutorial
|
|
cat docs/GETTING_STARTED.md
|
|
|
|
# Command reference
|
|
cat docs/API_REFERENCE.md
|
|
|
|
# Understand internals
|
|
cat docs/ARCHITECTURE.md
|
|
|
|
# Fix issues
|
|
cat docs/KNOWN_ISSUES.md
|
|
|
|
# Contribute
|
|
cat docs/DEVELOPMENT.md
|
|
|
|
# All docs
|
|
ls docs/
|
|
```
|
|
|
|
---
|
|
|
|
**Last Updated**: 2026-01-22
|
|
**Documentation Version**: 2.1
|
|
**Status**: Clean and organized ✅
|