How gasinfinity/zitrus works
Project type and purpose
• This is Zitrus, a 3DS homebrew SDK written entirely in Zig. It provides:
• A core library (modules for Horizon OS, PICA200‐style graphics “Mango,” hardware definitions, compression, formatting, memory management)
• A suite of command‐line tools (assemblers, packers, format inspectors)
• Example/demo applications (bitmap, flappy bird, GPU playground, info, panic, mango/hello_triangle, etc.)
• Build scripts and CI/CD for packaging libraries and demos into .elf/.3dsx
File structure
Top‐level directories:
• src – the core SDK modules:
– horizon/… (OS services, IPC, memory, panic, heap)
– hardware/… (register definitions, drivers: csnd, hid, pica, etc.)
– mango/… (Vulkan‐style graphics API wrappers)
– compress, fmt, math, memory, c (bindings), zitrus.zig root
• tools – host‐side CLI tools: 3dsx, RomFs, ExeFs, Smdh, Pica assembler/disassembler, Firm/Ncch, LZrev compressor
• demo – sample apps built on Zitrus (each with its own build.zig and sources)
• scripts – helpers (e.g., generate SPIR-V spec)
• test – unit/integration tests for Horizon and Mango modules
• build.zig, flake.nix/flake.lock – project‐wide build definition & Nix support
• docs – markdown docs and images for PICA shader formats, etc.
Architectural patterns:
• Layered library architecture:
– Lowest layer: hardware register definitions
– Next: Horizon OS bindings & services
– Next: Mango graphics abstraction over PICA200
– Cross‐cutting modules: compress, fmt, memory, math
• “Tools” are independent Zig executables that consume core modules to manipulate homebrew formats
• “Demo” apps are Zig executables that import the Zitrus library and use its modules to build .elf → .3dsx packages
README for insights
• Targets ARM11/horizon on real 3DS hardware or emulator
• Uses Zig’s build system (build.zig + dependency API) to wire up modules and linker scripts
• Provides MakeSmdh, Make3dsx, MakeRomFs helpers for final packaging
• Demonstrates high‐level usage: import zitrus, create Executable, set linker script, embed assets, produce .3dsx
Elements
• Clear labels: “Demo Apps,” “Zitrus Core,” “Tools,” “Build System,” “3DS Runtime,” “Hardware”
– Demo → Core (import/depends)
– Core → Horizon OS services (API calls)
– Core → Hardware modules → actual registers
– Build System → CLI Tools → final artifact
– 3DS Launcher → .3dsx → runtime flow
– Orange for Tools (CLI executables)
– Gray for Build System elements (build.zig, flake)
– Red for 3DS Runtime & Hardware blocks
• Annotations for key data flows (compilation, packaging, runtime calls, GPU submission)
Final advice
• Break the system into as many meaningful components as needed, but group related modules into logical clusters (e.g., “Horizon Services,” “Mango Graphics,” “Hardware Drivers”).
• Both the compile‐time dependency graph (demo → core → horizon/hardware) and the run‐time call flows (application → Horizon services → hardware).
• Be detailed in labeling module names, build steps, and format conversions.