Skip to content

Commit 721a9b5

Browse files
committed
chore: bye github!
1 parent 49fa08d commit 721a9b5

1 file changed

Lines changed: 1 addition & 226 deletions

File tree

β€ŽREADME.mdβ€Ž

Lines changed: 1 addition & 226 deletions
Original file line numberDiff line numberDiff line change
@@ -1,226 +1 @@
1-
![Zitrus Logo](https://github.com/GasInfinity/zitrus/blob/main/assets/zitrus-logo.png?raw=true)
2-
3-
---
4-
![Zig support](https://img.shields.io/badge/Zig-0.15.x-color?logo=zig&color=%23f3ab20)
5-
6-
3DS homebrew sdk written entirely in zig.
7-
8-
## Installation
9-
10-
> [!NOTE]
11-
> Not even the language this project is written in is 1.0
12-
>
13-
> You acknowledge that any amount of breaking changes may occur until
14-
> the first stable (minor) release, a.k.a `0.1.0`. No ETA is given.
15-
16-
```bash
17-
zig fetch --save git+https://github.com/GasInfinity/zitrus
18-
```
19-
20-
Then add this to your `build.zig`:
21-
```zig
22-
const zitrus = @import("zitrus");
23-
24-
const zitrus_dep = b.dependency("zitrus", .{});
25-
26-
// zitrus contains code useful for tooling outside of a 3DS environment.
27-
const zitrus_mod = zitrus_dep.module("zitrus");
28-
29-
const exe = b.addExecutable(.{
30-
.name = "panic.elf",
31-
.root_module = b.createModule(.{
32-
.root_source_file = b.path("src/main.zig"),
33-
.target = b.resolveTargetQuery(zitrus.target.arm11.horizon.query), // zig 0.16.0 will add 'arm-3ds' and this will be deprecated!
34-
.optimize = optimize,
35-
.single_threaded = true, // XXX: Currently needed for page_allocator.
36-
.imports = &.{
37-
.{ .name = "zitrus", .module = zitrus_mod },
38-
},
39-
}),
40-
});
41-
42-
// 3DSX's are PIE's
43-
exe.pie = true;
44-
45-
// Needed for any binary which targets the 3DS
46-
exe.setLinkerScript(zitrus_dep.path(zitrus.target.arm11.horizon.linker_script));
47-
48-
// You can skip installing the elf but it is recommended to keep it for debugging purposes
49-
b.installArtifact(exe);
50-
51-
const smdh: zitrus.MakeSmdh = .init(zitrus_dep, .{
52-
.settings = b.path("path-to-smdh-settings.zon"), // look at any demo for a quick sample.
53-
.icon = b.path("path-to-icon.png/jpg/..."), // supported formats depends on zigimg image decoding.
54-
});
55-
56-
// See `MakeRomFs` if you need something patchable unlike `@embedFile`.
57-
// WARNING: Won't be properly cached as there's an issue upstream.
58-
59-
// This step will convert your executable to 3dsx (the defacto homebrew executable format) to execute it in an emulator or real 3DS
60-
const final_3dsx: zitrus.Make3dsx = .init(zitrus_dep, .{ .exe = exe, .smdh = smdh });
61-
final_3dsx.install(b, .default);
62-
```
63-
64-
In your root file, you must also add this, as there's no way to implicitly tell zig to evaluate/import it automagically:
65-
```zig
66-
pub const panic = zitrus.horizon.panic;
67-
68-
comptime {
69-
_ = zitrus;
70-
}
71-
```
72-
73-
## Examples / Demos
74-
Currently there are multiple examples in the `demo/` directory. To build them, you must have `zig 0.15.1` in your path and run `zig build`.
75-
- [mango](demo/mango/) contains samples of how to use the mango graphics api.
76-
77-
- [panic](demo/panic/) is a simple example that panics when opened to test panics and traces.
78-
- [info](demo/info) is a simple app that currently shows the console region and model (will be updated to show more info over time).
79-
- [bitmap](demo/bitmap/) is a port of the bitmap example in libctru's 3ds-examples.
80-
- [flappy](demo/flappy) is a simple fully functional flappy bird clone written entirely with software blitting.
81-
- [gpu](demo/gpu/) is a playground for [mango](src/mango.zig), bleeding edge features are tested there. Not really an example per-se.
82-
83-
---
84-
85-
You can (and are encouraged) to look at the `tools` directory as it is a good example of how to use the API's `zitrus` provides outside (and inside!) of a 3DS environment. Almost all tools are self-contained and span 50-300 LOC.
86-
87-
# Coverage
88-
89-
### Legend
90-
⚠️ Feature regressed temporarily due to dependency or upstream (usually when zig updates this can happen)
91-
92-
β›” Blocked due to upstream. Impossible to do until something gets fixed or added, usually listed in https://github.com/GasInfinity/zitrus/issues/1
93-
94-
🟒 Fully implemented
95-
🟑 Partially implemented
96-
πŸ”΄ Implementation not started/missing critical things
97-
98-
πŸ”‹ High priority
99-
πŸͺ« Low priority
100-
101-
## Documentation
102-
103-
- 🟑 Mango
104-
- 🟑 Horizon
105-
106-
## Tests
107-
108-
- 🟑 Horizon
109-
- 🟑 Mango
110-
111-
## Formats (+ Tooling)
112-
- 🟒 Smdh (tools/Smdh): Make / Dump
113-
- 🟒 3dsx (tools/3dsx): Make / Dump
114-
- 🟒 Pica (tools/Pica): Assemble / Disassemble
115-
- 🟒 Assemble: Only **Z**itrus**P**ica**Sh**ader's are implemented as an output format.
116-
- 🟒 Disassemble: Outputs **Z**itrus**P**ica**A**sse**m**bly. Either RAW instructions, ZPSH's or DVL's (.shbin) can be disassembled.
117-
- 🟒 Firm (tools/Firm): Make / Info / Dump
118-
- 🟑 Ncch (tools/Ncch): Make CXI / Dump / Info
119-
- 🟒 ExeFS (tools/ExeFs): Make / List / Dump
120-
- 🟒 RomFS (tools/RomFs): Make / List / Dump
121-
- 🟑 Compression (tools/Compress):
122-
- 🟑 LZrev (Compress/LzRev): Decompression
123-
- 🟑 Yaz0 (Compress/Yaz): Decompression
124-
- 🟑 LZ10 (Compress/Lz10): Decompression
125-
- 🟑 LZ11 (Compress/Lz11): Decompression
126-
- 🟑 Archives (tools/Archive):
127-
- 🟒 Darc (Archive/Darc): Make / List / Dump
128-
- 🟑 Sarc (Archive/Sarc): List / Dump
129-
- 🟑 Layouts (tools/Layout):
130-
- 🟑 Image (Layout/Image): Dump
131-
- πŸ”΄ Layout
132-
- πŸ”΄ Animation
133-
- πŸ”΄ Cro0 / Crr0
134-
- πŸ”΄ Cia
135-
136-
## Horizon
137-
138-
### Runtime
139-
- πŸ”΄β›” `threadlocal` variables.
140-
- πŸŸ‘β›”πŸ”‹ Panic / error reporting and tracing.
141-
- πŸŸ‘β›”πŸ”‹ *Application* Test runner.
142-
143-
### Services
144-
145-
- 🟒 `srv:`
146-
- 🟒 `err:f`
147-
- 🟑 `APT:S/A/U`
148-
- 🟑 `hid:SPRV/USER`
149-
- 🟒 `ir:rst`
150-
- 🟑 `fs:USER/LDR`
151-
- 🟑 `cfg:u/s/i`
152-
- 🟒 `gsp::Gpu`
153-
- 🟑πŸͺ« `gsp::Lcd`
154-
- 🟑 `ns:s`
155-
- 🟒 `ns:p/c`
156-
- 🟑 `csnd:SND`
157-
- 🟑πŸͺ« `pm:app`
158-
- 🟒 `pm:dbg`
159-
- 🟑 `soc:U`
160-
- 🟑 `ps:ps`
161-
- 🟑 `pxi:ps9`
162-
- 🟑 `Loader`
163-
- πŸ”΄ All other [services](https://www.3dbrew.org/wiki/Services_API) not listed here
164-
165-
### Library Applets
166-
167-
- 🟒 `error`
168-
- 🟑 `swkbd`
169-
- πŸ”΄ All other [applets](https://www.3dbrew.org/wiki/NS_and_APT_Services#AppIDs) not listed here.
170-
171-
## Mango (PICA200 VK-like Graphics API)
172-
173-
### Backends
174-
- 🟒 Horizon
175-
- πŸ”΄ Interface (for `freestanding` usage)
176-
177-
### Objects
178-
- 🟒 Presentation engine: 240x400, 240x400x2, 240x800 + 240x320. `Double` or `Triple` buffered in `Mailbox` or `Fifo`.
179-
- 🟑 Queues
180-
- 🟑 Fill (clear and fill operations)
181-
- 🟑 Transfer (copy and blit operations)
182-
- 🟒 Submit (`CommandBuffer` submission)
183-
- 🟒 Present (see `PresentationEngine`)
184-
- 🟒 `Semaphore`s
185-
- 🟒 `DeviceMemory`
186-
- 🟒 `Buffer`s
187-
- 🟒 `Sampler`
188-
- 🟒 `Image`s / ImageViews
189-
- 🟒 `CommandPool`s
190-
- 🟑 `Pipeline`s
191-
- 🟒 Lighting
192-
- πŸ”΄ Shadows
193-
- πŸ”΄ Geometry shaders
194-
- πŸ”΄ Fog
195-
- πŸ”΄ Gas
196-
- 🟑 `CommandBuffer`s
197-
- πŸ”΄ Shadow Rendering
198-
- πŸ”΄ Gas Rendering
199-
- 🟑 Image Sampling
200-
- πŸ”΄ Shadow textures
201-
- πŸ”΄ Cubemaps
202-
203-
## Hardware
204-
205-
Whether register bits are present and/or relevant tooling (assemblers, disassemblers, etc...)
206-
207-
- 🟒 CSND
208-
- 🟒 PXI
209-
- 🟒 LGY
210-
- 🟒 HID
211-
- 🟒 I2C
212-
- 🟑 DSP
213-
- 🟑 PICA200: Missing typing of some documented registers, mostly done.
214-
215-
## Why?
216-
I wanted to learn arm and always wanted to develop 3DS homebrew, also I searched and I haven't found any kind of zig package that doesn't use libctru, so I just started reading a lot and doing things. Furthermore, using only zig has a lot of advantages:
217-
- Really simplified and easy development. You don't need complex toolchains, you just need the `zig` executable, that's it. The tools `zitrus` provides also have no dependencies, they'll work on any platform that zig supports! You can still use devkitPRO's binutils if you need.
218-
- Safety in `Debug` and `ReleaseSafe` modes. Zitrus currently uses the `ErrDisp` port to report panics and returned errors. The only missing thing is reporting return traces with debugging symbols (Currently only addresses are logged)
219-
- Really useful and simple build-system (as you've seen the example `build.zig` is really small and makefiles are really arcane)
220-
221-
# Credits
222-
- [3dbrew](https://www.3dbrew.org/wiki/Main_Page) is seriously the best resource if you need info about the 3DS hardware/software.
223-
- [gbatek](https://problemkaputt.de/gbatek.htm#3dsreference) is the second best resource for low level info about the 3DS hardware.
224-
- @devkitPro for the tooling, a starting point/reference for this project and reference for unknown/undocumented/unspecified things (e.g: libctru and how tf jumping to home menu worked).
225-
- @azahar-emu/[azahar](https://github.com/azahar-emu/azahar) for providing an emulator to quickly test changes and the initial iterations.
226-
- @LumaTeam/[Luma3DS](https://github.com/LumaTeam/Luma3DS/) for literally saving my life when trying to debug things in my 2DS.
1+
# Moved to [Codeberg](https://codeberg.org/GasInfinity/zitrus/src/branch/main)

0 commit comments

Comments
Β (0)