User guide

Building an application, running it on hardware, and running it in the emulator, with the collection's own tools. THE_LOOP.md explains how these steps feed each other; BUILDING.md covers the toolchain and bin/oops.

The tools

The host tools are Rust and run natively on Windows and Linux. Target code is freestanding C, cross-compiled with clang 21 - from a local toolchain on PATH where there is one, else the silkeh/clang:21 container, else a WSL distribution (./bin/oops setup). A local toolchain is much the fastest of the three and is what CONVENTIONS section 8 asks for first.

./bin/oops build selfish prosperous orbistoun

Every host tool keeps its data under one root, %APPDATA%\OOPS on Windows, or beside the binary in portable mode. The oops-libs guide gives the layout and its overrides.

From source to title

[C source]
    | make, with a local clang 21 (else the container, else WSL)
    v
[app.elf] -- selfish --format title --> [title directory, e.g. GLCB00001/]
                                            |-- pros restore, pros launch --> hardware
                                            '-- orbistoun run ----------------> emulator

Build and package an app

./bin/oops-apps make src/oops-gl/gl1-cube

Or directly from the app's directory:

cd oops-apps/src/oops-gl/gl1-cube
make title

make title compiles the app, and calls selfish --format title to lay out build/title/GLCB00001/ with eboot.bin, sce_module/ and sce_sys/ (param.json, icon0.png and the other metadata a title carries).

Run it on hardware

pros register <address> --name <name>
pros check
./bin/oops-apps restore src/oops-gl/gl1-cube
pros logs            # in a second terminal, before launching
pros launch GLCB00001

Or directly with pros restore:

pros restore oops-apps/src/oops-gl/gl1-cube/build/title/GLCB00001 /data/homebrew/GLCB00001

pros check expects the target's services on ports 9021 (payload loader), 2121 (FTP), 3232 (kernel log), 2323 (shell) and 8084 (payload manager).

Run it in the emulator

cd orbistoun
./bin/orbistoun run GLCB00001

run finds the title in the title library, runs it until it exits, faults or stops, and reports the verdict against the previous run. orbistoun-cli questions ranks what guests asked for that is still unknown, and orbistoun-cli worklist ranks what to implement next.

Per-project guides

• Prosperous: getting started, targets, logs, files, titles, library, shell, payloads
• Orbistoun: features
• SELFish: user guide
• obSCEne: user guide
• oops-sdk: user guide
• oops-apps: user guide
• oops-libs: user guide

Troubleshooting

pros check times out:

• The address registered with pros register is the target's current address.
• The payload loader and the services run in memory, so a restarted target needs them started again.
• No firewall on the host blocks ports 9021, 2121, 3232, 2323 or 8084.