# omarchy-apple-dev: Building iOS Apps on Linux

> omarchy-apple-dev installs a Linux-based Swift and iOS deployment toolchain for Omarchy systems, including an experimental mode that avoids downloading Xcode. It is most suitable for physical-device development that accepts substantial setup and version-matching constraints.

**joshuaswarren/omarchy-apple-dev** — Build and deploy iOS SwiftUI apps from Omarchy Linux on any PC (x86_64 or Apple Silicon), no Xcode required

- Repository: https://github.com/joshuaswarren/omarchy-apple-dev
- Stars: 1,702 · Forks: 97
- Language: Python
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/joshuaswarren-omarchy-apple-dev

## Why omarchy-apple-dev Exists for Linux-Based iPhone Development

omarchy-apple-dev targets developers who want to compile SwiftUI or Flutter applications from an Omarchy Linux machine and install those applications on a physical iPhone over USB. The intended host can be an x86_64 Linux computer or an Apple Silicon Mac, but macOS and an installed Xcode application are not part of the normal workflow. The repository presents itself as a bridge between Linux compilation and Apple-platform deployment, not as a complete replacement for every Xcode function.

The boundary is important. The full mode downloads the Xcode distribution from Apple because the project needs the iPhoneOS SDK artifacts that exist inside it. It does not install Xcode as a macOS application. The README says the archive is the one external requirement that cannot be automated away in this mode. A free Apple ID is sufficient for device installation, although paid membership is needed for the documented TestFlight and App Store paths.

This approach is aimed at teams whose source development already happens on Linux and whose validation target is real iPhone hardware. It is a poor fit when simulator debugging, hot reload, App Store review work, or Apple's complete native development environment is a firm requirement. The distinction turns on what must happen on the Apple side, not merely where the Swift code is edited.

## Full and Experimental no-Xcode Toolchain Modes

The installer selects between two distinct environments. `./install-toolchain.sh` asks for a mode in a terminal, while `--mode full` and `--mode no-xcode` skip that question. The selected mode is recorded in `~/.config/omarchy-apple-dev/mode`, and the documented fallback in a noninteractive environment is full mode.

Full mode provides the SDK from an Xcode archive matched to the installed Swift compiler. The README specifically pairs Xcode 27 with `swift-bin` 6.4 and Xcode 26 with Swift 6.3. It covers Swift, SwiftUI, Objective-C, C, and C++, along with the system frameworks in the Xcode SDK. Extensions, widgets, and macOS applications are listed as supported in this mode.

The experimental no-Xcode mode is materially narrower. Its language surface includes Objective-C, C, Swift's standard library, async/await, and Foundation, plus a small SwiftUI subset containing `App`, `WindowGroup`, `Text`, `VStack`, `Button`, and `@State`. Its framework list is also limited. Extensions, widgets, and macOS apps are not yet available according to the README. This mode should be treated as a deliberately constrained compatibility layer, not as a general SwiftUI distribution.

Version matching is a concrete setup risk. The installer identifies the matching Xcode when it reaches the SDK step, but users still need to keep the Swift toolchain and selected Xcode release aligned. The mode also changes what Flutter plugins can compile, so an existing application may fit one environment and fail in the other.

## Omarchy Installation and First SwiftUI Workflow

The repository's basic installation path clones the project and runs its installer. On Omarchy, the README also documents a menu route, `Install > Development > iOS`, which runs the same setup steps. Start from the default branch:

```bash
git clone https://github.com/joshuaswarren/omarchy-apple-dev
cd omarchy-apple-dev
./install-toolchain.sh
```

The installer selects full or no-Xcode mode unless a mode argument is supplied. Full mode then reaches the SDK stage, where it expects a compatible `Xcode.xip` downloaded from `developer.apple.com`. The README does not provide a complete application scaffold command in the excerpt, so it would be misleading to invent one here.

For a first hardware-oriented use, the confirmed endpoint is a physical iPhone connected by USB. The repository contains `device-run.sh`, while the Flutter documentation demonstrates `xtool install` as the operation that signs and places an app on the phone. For native SwiftUI work, `docs/TEST-MATRIX.md` is the documented place to distinguish operations that have run on an iPhone from capabilities that merely compile.

The verified hardware record is narrower than the broad host claim. The README says the device install and LLDB loop were proven on an M1 with Swift 6.3.3, xtool 1.19.0, and the iOS 26.5 SDK. It states that this run was not repeated with the listed Swift 6.4 set. Full-mode Swift 6.4 setup was verified on x86_64 Arch with the install script as a fresh user.

## Flutter Release Builds and USB Installation

Flutter support can produce an IPA for a physical iPhone, but the normal build is unsigned and release-mode; signing is a separate step. The README says there is no debug mode, hot reload, or simulator support in this pipeline. It also reports that aarch64 hosts are untested, while the recorded Flutter verification used x86_64 with Flutter 3.47.6. Flutter 3.47.x must be on `PATH`, and one-time setup requires about 7 GB of disk.

The documented sequence installs Linux build dependencies, prepares the Flutter version, creates or selects an app, builds an unsigned archive, optionally signs it, and installs it on the phone:

```bash
sudo pacman -S --needed llvm rsync
flutter/setup.sh
flutter create --platforms ios counter
flutter/build.sh counter
tools/sign-dev.sh counter/build/ios-linux/Payload/Runner.app Runner-dev.ipa
```

The unsigned result is `counter/build/ios-linux/Runner.ipa`. On a free Apple ID, the README says signing can be skipped and installation performed in one command:

```bash
flutter/build.sh --install counter
```

That path uses `xtool install` to sign the app and place it on the connected phone. Development signing with a device-specific profile is a separate route and requires configuration described in `GETTING-STARTED.md`. The documented App Store Connect API key is needed for that signing path, but the excerpt does not supply its configuration command, so no invented environment variable or credential format is appropriate.

Flutter plugins must include a `Package.swift`. In no-Xcode mode, plugin compatibility is narrower still, with Objective-C plugins and the Swift plugins `shared_preferences` and `url_launcher` listed as supported. The output is an IPA intended for device deployment, not a general-purpose Swift build system.

## Operational Limits, Validation Scope, and App Distribution

The largest operational cost is setup and compatibility management. Full mode uses roughly 3 GB of the Xcode archive, while no-Xcode mode needs about 7 GB of temporary disk. Flutter setup also needs about 7 GB. These are substantial workspace requirements for a toolchain that removes Xcode from the host rather than eliminating Apple's SDK distribution constraints.

Hardware support is documented unevenly. x86_64 Arch is recorded as verified for the current Swift 6.4 install path. Apple Silicon installation is claimed by the project, and an earlier M1 run proved device installation and LLDB, but not with that exact current version set. Flutter aarch64 hosts are explicitly untested. These distinctions matter because host architecture, Swift version, SDK version, and device workflow are separate compatibility boundaries.

The distribution path also has edges. Device installation works with a free Apple ID. Full mode documents TestFlight and App Store support with a paid account. No-Xcode mode documents Flutter TestFlight upload through `sdk-free/ship.sh --upload`, but the README says App Store review was not tried. Those are different claims: upload support does not establish a completed review workflow.

The README also distinguishes a Linux `ibtool` for Flutter storyboards from the broader native toolchain. If an application depends on an extension, widget, simulator, unsupported SwiftUI type, broad system framework, or unlisted plugin, full Xcode on macOS remains the more predictable environment.

## Maintenance Signals, MIT Terms, and the macOS Alternative

The repository is not archived. Its last push was on 2026-10-15, followed by releases v0.4.0 on 2026-10-14, v0.3.0 on 2026-10-12, and v0.2.0 on 2026-10-11. This is recent release activity, although the README itself marks no-Xcode mode as experimental and Flutter aarch64 support as untested. Those qualifiers matter more than release frequency when deciding whether a workflow is production-ready for a particular app.

Upgrade work is not limited to running an installer again. Swift, xtool, the iOS SDK, Flutter, LLDB, and plugins participate in the build, and Xcode must match Swift. The repository includes `CHANGELOG.md`, `FINDINGS.md`, compatibility directories, tests, patches, and a test matrix, but the README does not document a rollback procedure or guarantee compatibility across every toolchain upgrade.

The project is distributed under the MIT License. That permits use, modification, distribution, and sublicensing subject to the License terms, including preservation of its copyright and permission notice. This is a summary of the stated license, not legal advice.

The real alternative is Apple's normal macOS and Xcode workflow. Xcode includes the native SDK and build integration in one supported environment, and it supplies simulator and debugging paths that omarchy-apple-dev does not reproduce. In exchange, it requires macOS and Xcode. omarchy-apple-dev instead offers Linux hosts, physical-device deployment, and a no-Xcode mode that may still obtain SDK data from Apple's public iOS update. The choice is between a fuller Apple-native environment and a Linux-oriented toolchain with narrower documented coverage.

## Conclusion

Adopt omarchy-apple-dev if the team deliberately develops on Omarchy, has a physical iPhone for validation, and accepts responsibility for SDK compatibility. Do not adopt it as a general replacement for macOS Xcode, simulator-based development, or complete App Store workflows. Verify the selected mode, matching Xcode and Swift versions, available disk space, signing credentials, and the project's entry in docs/TEST-MATRIX.md before moving application work onto it.

## FAQ

### Can omarchy-apple-dev build an iOS app without Xcode?

Yes, its experimental no-Xcode mode supports a limited Swift and SwiftUI surface and restricted system frameworks. It does not yet cover extensions, widgets, or macOS apps.

### Does omarchy-apple-dev support SwiftUI apps and Flutter apps?

Yes. It supports SwiftUI and Flutter application builds, although Flutter builds are release-only and have no hot reload or simulator support.

### Can a free Apple ID install an app built with omarchy-apple-dev?

Yes. The README states that a free Apple ID supports device installation, while paid membership is required for the documented TestFlight and App Store paths.

## Sources

- [Issues](https://github.com/joshuaswarren/omarchy-apple-dev/issues)
- [joshuaswarren/omarchy-apple-dev on GitHub](https://github.com/joshuaswarren/omarchy-apple-dev)
- [License: MIT](https://github.com/joshuaswarren/omarchy-apple-dev/blob/main/LICENSE)
- [README](https://github.com/joshuaswarren/omarchy-apple-dev/blob/main/README.md)
- [Releases](https://github.com/joshuaswarren/omarchy-apple-dev/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/joshuaswarren-omarchy-apple-dev