Build for Apple silicon

Before you build

Use an Apple silicon Mac with Xcode and Homebrew. The upstream README lists xcodegen, zstd, spirv-cross, glslang, the .NET SDK, and Python packages lz4, capstone, fonttools and the version-dependent backports.zstd. Follow the current README installation commands for your Python version, then use the development guide for build options. You need your own legally obtained game and prod.keys. This guide does not supply game files, keys or a downloadable app. Check the upstream prerequisites before installing anything: toolchain requirements can change between commits.

Choose the right target

The development host and a distributable Mac application are different targets. --platform mac is the development host. --platform mac-app produces the app intended to open from Finder. Neither command is an iPhone IPA build. Record the project commit and the game version before comparing results with an issue.

Build in deliberate steps

1. Read the upstream README and development guide at the commit you intend to use.
2. Prepare your own inputs using the directory layout documented by that revision. Do not post keys or game files in issue comments.
3. Follow the upstream build command with the Mac app target when you want a Finder app. Preserve the build output and any error message.
4. Before replacing an existing app, follow the save backup guide and keep a separate copy of your data.
5. Open the built app and confirm the expected title before continuing. A successful compilation alone does not demonstrate playable performance.

Build example to copy

From your prepared nxnative checkout, the documented Mac app route is:

python3 scripts/build_ipa_from_nsp.py ~/Games/MarioOdyssey -k ~/keys/prod.keys --platform mac-app

Replace ~/Games/MarioOdyssey with your own prepared game input directory and ~/keys/prod.keys with your own key file. Read the upstream input layout before running it. This command is displayed as a reference; this website never executes it.

The expected output is <NSP folder>/<game name>.app; the game name comes from the input’s control data. The -o option can specify another .app output path. The finished Mac app does not depend on keeping the build folder. Confirm that the app exists at the expected location before trying to open it from Finder.

Checkpoint and failure handling

If compilation fails, capture the first meaningful error, your toolchain version and commit. Compare with the requirements for that revision before changing random dependencies. If the app opens but stops at Preparing pipelines, use the dedicated troubleshooting guide. Do not delete your save folder to troubleshoot a build error.

Match the output to the task

What you have	What it is for	What to do next
A Finder .app bundle	Playing on an Apple silicon Mac	Open the expected title and check input and existing progress
A developer host build	Mac development and diagnostics	Follow the run command printed by that particular build
An IPA	iPhone/iPad installation	Use the mobile signing and installation route

If the terminal is still reporting a compiler error, changing in-game settings will not fix that build stage. If the bundle exists but fails on launch, preserve the launch error and log separately from the compiler output. If you have never prepared the project, return to the requirements checklist rather than guessing which dependency is missing.

Record a useful first run

Write down the Mac chip, macOS version, nxnative revision, game version, output target and the first screen reached. Check whether input responds and whether the intended save is visible. Our Odyssey dossier illustrates why a platform report should remain tied to its exact evidence. For a stalled preparation screen, continue with pipeline troubleshooting; before trying another build, use save backup.