Skip to content

About

Build, sign and ship iOS apps from Linux with xtool: widgets, Live Activities, Apple Watch, TestFlight, and a Siri (App Intents) metadata generator

Topics

Resources

Stars

16 stars

Watchers

0 watching

Forks

Latest commit

 

History

3 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

xtool-on-linux

Build, sign and ship an iPhone app from Linux, with no Mac on the desk.

These are the scripts and notes behind my reel about building my assistant app on Linux with xtool. xtool does the heavy lifting. This repo is everything I had to add around it to get widgets, Live Activities, an Apple Watch app, Siri and TestFlight.

Clean build Peak memory App size
3 min 37 s 4.5 GB 29 MB

Measured on a clean build of my own app (217.36 s).

From the reel: 3 steps

The short version of what the reel shows: plain xtool, no Mac, a starter app on your iPhone. The widgets, Siri, the watch app and TestFlight are the rest of this repo.

The catch: you still need an Apple account and Apple's Xcode download (the .xip). xtool pulls the iOS SDK out of that file. Xcode itself never runs.

1. Install Swift and xtool (on Linux, once)

  • Swift: follow swift.org/install/linux, then check it with swift --version.

  • The iPhone's USB tools. On Ubuntu or Debian:

    sudo apt-get install usbmuxd libimobiledevice-utils

    On Arch, the package list is in docs/SETUP.md.

  • xtool, one AppImage:

    curl -fL "https://github.com/xtool-org/xtool/releases/latest/download/xtool-$(uname -m).AppImage" -o xtool
    chmod +x xtool
    sudo mv xtool /usr/local/bin/
    xtool --help      # OVERVIEW: Cross-platform Xcode replacement
  • On Windows: do all of this inside WSL, and pass the iPhone through to it with usbipd. xtool's Linux and Windows install guide covers both.

2. Sign in and give xtool the SDK (once)

  1. In your browser, sign in at developer.apple.com/download/all and download Xcode's .xip. The page needs your login, so curl will not work. I used Xcode_26.6_Universal.xip.

  2. Run the setup, pick a login mode, then give it the path to the .xip:

    $ xtool setup
    Select login mode
    0: API Key (requires paid Apple Developer Program membership)
    1: Password (works with any Apple ID but uses private APIs)
    Choice (0-1): 0
    ...
    Path to Xcode.xip: ~/Downloads/Xcode_26.6_Universal.xip

    I use the API key, which needs the paid Apple Developer Program. The password mode goes through Apple's private APIs, and xtool's guide suggests a spare Apple account for it. I have not tried it.

3. Plug in your iPhone (every build)

  1. Turn on Developer Mode: Settings › Privacy & Security › Developer Mode. The phone restarts; unlock it and confirm Turn On. If the switch is not there yet, do steps 2 and 3 once and look again.

  2. Plug the phone into the Linux machine. Tap Trust on Trust This Computer? and enter your passcode.

  3. Make an app and run it:

    xtool new Hello && cd Hello
    xtool dev

    It builds, signs and installs Hello, and it appears on your home screen. If iOS says Untrusted Developer, go to Settings › General › VPN & Device Management, tap your account and trust it.

From here, ios-ota in this repo does the same build with Siri, the watch app and an install-over-the-air page. See the Quick start.

What works

Feature Status Where it is built
iOS app ✅ Linux, plain xtool
Widgets ✅ Linux, xtool's app-extension support
Live Activities (Lock Screen and Dynamic Island) ✅ Linux, same extension
Siri, Shortcuts and Spotlight (App Intents) ✅ Linux, with the workaround
Apple Watch app ✅ compiled on a GitHub macOS runner, assembled and signed on Linux
Watch-face complication ⚠️ builds and signs, not yet confirmed on a real watch face
Install over the air or over USB ✅ Linux
Xcode .xcconfig build settings and $(VAR)s in Info.plist ✅ Linux, details
TestFlight ✅ signed on Linux, uploaded by a GitHub macOS runner

"No Mac" means no Mac of your own. Three steps have no Linux equivalent and borrow a GitHub-hosted macOS runner for a few seconds each: compiling the watch app, compiling the app icon (actool), and the App Store upload (altool). Everything else runs on your Linux box.

The Siri catch

App Intents compile fine on Linux, and then Siri and Shortcuts act as if the app has none. No error anywhere.

The reason: on a Mac, Xcode runs a closed-source tool (appintentsmetadataprocessor) after the compile. It writes an index of your intents into the app at Metadata.appintents/. iOS only reads that index. No index, no Siri.

The input to that tool is not secret, though. The Swift compiler already emits it, on Linux too (-emit-const-values). So appintents/appintents-gen.py writes the index itself, and ios-ota puts it into the app before signing. It is checked against a bundle that Apple's real tool generated:

$ python3 appintents/test_golden.py
ok — matches Apple's golden bundle (7 known differences)

How it works, what the known differences are, and what is not covered: docs/SIRI.md.

Quick start

git clone https://github.com/cyberneel/xtool-on-linux
export PATH="$PWD/xtool-on-linux/bin:$PATH"

cd MyApp          # any xtool project
ios-ota .         # build, add Siri metadata, sign, publish an install page, USB-install if plugged in

That is the short version. The one-time setup (Swift, xtool, the SDK, signing identity) is in docs/SETUP.md, along with the watch app and TestFlight steps.

What is in here

bin/
  ios-ota               the pipeline: build, Siri metadata, watch embed, sign, publish
  ios-testflight        same pipeline, distribution-signed, then uploaded
  ios-xcconfig          applies Xcode .xcconfig build settings to the built app
  xtool-gen-appintents  runs the Siri generator against a built .app
  xtool-embed-watch     builds the watch app on CI and embeds it
  provision.py          signing certificates and profiles via the App Store Connect API
  ios-upload            couriers a signed .ipa to a macOS runner for altool
  ios-appicon           compiles the app icon on a macOS runner
  ios-host              finds which machine the iPhone is plugged into
  gh-retry              gh, retried on GitHub 5xx errors
appintents/             the Siri workaround: generator, protocol list, golden test
ci/                     the GitHub workflows, to copy into repos of your own
systemd/                share a plugged-in iPhone with another machine
example/                config files for an app with a widget and a watch app
docs/                   SETUP.md and SIRI.md

What you need

  • A Linux machine. I use Arch. xtool targets Ubuntu, so Arch needs a few extra packages (listed in the setup doc).
  • A paid Apple Developer account. The scripts sign through an App Store Connect API key.
  • Xcode's .xip from Apple, for the SDK. It is not included here and you should not get it anywhere else.
  • A GitHub account, only for the watch app and TestFlight.

Versions I run: xtool 1.17.0, Swift 6.3.3, the Xcode 26.6 SDK, rcodesign 0.29.0.

Not included

No Apple binaries, no SDK, no signing keys. The scripts create your own certificates and keep them in ~/.local/share/ios-ota/, which never belongs in a repo.

Credit

xtool by Kabir Oberai and contributors is what makes any of this possible. The Siri generator's output format started from xtool PR #217.

MIT licensed. Not affiliated with Apple.

About

Build, sign and ship iOS apps from Linux with xtool: widgets, Live Activities, Apple Watch, TestFlight, and a Siri (App Intents) metadata generator

Topics

Resources

Stars

16 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages