> ## Documentation Index
> Fetch the complete documentation index at: https://ios-on-switch.brunostjohn.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

> Building from source, trying your build on a Switch, and sending a pull request.

Pull requests are the only contributions this project takes. Issues are disabled, and there's no timeline for
reviews: a PR might be merged next week, much later or never. Slop won't be merged.

## Pull requests

The PR template has five sections: what the change does, how, why, testing and evidence, and risk. Each one needs
real content, and the checklist under them has to be fully ticked, or the **PR template** check fails. Evidence from a
real Switch OLED, such as log lines, screenshots or numbers from before and after, makes a PR much quicker to review.

Every PR also runs one workflow on GitHub's macOS runners. It checks formatting and lint, builds the debug and release
configurations and runs the tests, all through Bazel.

[AGENTS.md](https://github.com/brunostjohn/ios-on-switch-lmao/blob/main/AGENTS.md) has the rules the code follows. The
ones PRs most often run into:

* Drivers run on interrupts, and a lost interrupt is a one-line panic, with no fallback to polling.
* Data moves by DMA whenever the hardware can do it.
* A change must never make the system slower.
* A feature that misbehaves gets its cause found and fixed, and stays on.
* Everything renders at the panel's native pixels.
* Comments say only what the code can't.

## Building from source

The kernel has to be built with Apple's clang against the iOS SDK, and both come only with Xcode, which Apple's
licence doesn't let a build download. Install the Xcode version the build asks for, and Bazel fetches everything else,
pinned by hash. Installing iOS doesn't need any of this: the image builder uses prebuilt parts from the release.

| What | Command |
| - | - |
| Build the kernel, boot files and Metal driver | `bazelisk build //:boot //:gpu` |
| The same, in the release configuration | `bazelisk build --config=release //:boot //:gpu` |
| Run the tests | `bazelisk test //...` |
| Format everything | `bazelisk run //:format` |
| Check formatting and lint | `bazelisk test //:format_test //:lint_test //:clang_tidy_test` |

## Trying your build on a Switch

With the SD card in your Mac, `bazelisk run //deploy:sd -- disk4` shows what it would write, and adding `--yes` writes
it. It replaces the boot files and the files this project adds to iOS's Data volume, after copying the last boot's
logs off the card. `diskutil list external` tells you which disk the card is.

To read logs:

* `bazelisk run //deploy:pull_logs -- disk4` copies them off the card into a log archive you can open with
  `log show --archive`.
* With the Switch paired to your Mac over USB-C, `idevicesyslog` from libimobiledevice streams the live log.

### Boot options

Boot options go in `switchroot/ios/bootargs.txt` on the SD card. It's plain text: words separated by spaces or new
lines, with `#` starting a comment that runs to the end of the line. You don't need the file at all. Everything is on
by default, and a release build boots with no options.

In a debug build, `-v` shows a text console instead of the Apple logo.

Each of these turns one thing off, for when you're hunting a problem:

| Option | Turns off |
| - | - |
| `switch-no-bt` | Bluetooth and Joy-Con pairing on the rails, and sound with them |
| `switch-no-wlan` | Wi-Fi |
| `switch-no-gpu` | The GPU and Metal |
| `switch-no-nvdec` | Hardware video decoding and encoding |
| `switch-no-audio` | Sound |
| `switch-no-sleep` | Turning the screen off on lock, and with it sleep |
| `switch-no-sd-uhs` | The SD card's fast mode, so it stays at 48 MHz |
| `switch-no-dfll` | The CPU's on-demand clock, so it runs at a fixed 1670 MHz |

`switch-ui-scale=` sets how big everything on screen is. `1.6` is the default and gives 450x800 points, the size of an
iPad's screen. `1.25` gives 576x1024 and `1` gives 720x1280. Anything else counts as `1`, and the kernel log says so.
The new scale shows up on the next boot.

## Releases

Pushing a tag like `1.2.0` builds a release: a zip in SD-card layout and the image builder's prebuilt parts. The tag
has to match the version in `MODULE.bazel`. A tag with a suffix, like `1.2.0-beta`, makes a pre-release.

## These docs

The site is built with [Mintlify](https://mintlify.com) from `docs/`. To preview a change, install the CLI with
`npm i -g mint` and run `mint dev` in `docs/`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.