xtool-termux-ios-dev

name	xtool-termux-ios-dev
description	Build, install, and run iOS apps from a rooted Android Termux environment using xtool and USB. Use this whenever the user mentions xtool on Termux, iPhone over USB, provisioning/auth/TLS issues, usbmuxd hangs, trust prompts not appearing, or install/launch failures on this setup.

xtool iOS dev from rooted Android Termux

Use this workflow on the moto g34 5G LineageOS Termux environment where xtool cross-builds and installs iOS apps over USB.

What this skill does

• Build iOS targets with xtool from Termux.
• Stabilize USB host mode + usbmuxd for iPhone detection.
• Install signed apps to a connected iPhone.
• Fix known auth/TLS/provisioning failures in this environment.
• Apply battle-tested recovery for flaky detection, locks, and permissions.

Assumptions

• Device is rooted (Magisk) and su works.
• swift, xtool, and libimobiledevice tools are installed in Termux.
• App project exists locally.

Standard run order (happy path)

1) One-time shell prep

cd ~/projects/<your-project>
export USBMUXD_SOCKET_ADDRESS=UNIX:/data/data/com.termux/files/usr/var/run/usbmuxd
pkg install -y zip

2) Make Android the USB host + trigger trust prompt

Use this when Android is charging from iPhone or device is not detected.

su -c 'echo source > /sys/class/typec/port0/power_role; echo host > /sys/class/typec/port0/data_role; svc usb resetUsbPort 0'
su -c '/data/data/com.termux/files/usr/bin/usbmuxd -f -v'

When it works, logs usually include:

• Changing configuration of device ... 1 -> 4
• Got serial ...
• Connected to v2.0 device ...

Then switch to daemon mode:

su -c 'pkill usbmuxd || true; rm -f /data/data/com.termux/files/usr/var/run/usbmuxd /data/data/com.termux/files/usr/var/run/usbmuxd.pid; /data/data/com.termux/files/usr/bin/usbmuxd -f -v -l /data/data/com.termux/files/home/tmp/usbmuxd.log >/dev/null 2>&1 &'

3) Optional anti-conflict USB step

su -c 'pm disable-user --user 0 com.android.mtp'

Re-enable after done:

su -c 'pm enable com.android.mtp'

4) Verify iPhone detection

USBMUXD_SOCKET_ADDRESS=UNIX:/data/data/com.termux/files/usr/var/run/usbmuxd idevice_id -l
USBMUXD_SOCKET_ADDRESS=UNIX:/data/data/com.termux/files/usr/var/run/usbmuxd idevicepair validate

5) Build

USBMUXD_SOCKET_ADDRESS=UNIX:/data/data/com.termux/files/usr/var/run/usbmuxd xtool dev build

6) Install (root context + SSL env)

su -c 'PATH=/data/data/com.termux/files/usr/bin:/system/bin:/system/xbin:$PATH HOME=/data/data/com.termux/files/home TMPDIR=/data/data/com.termux/files/home/tmp \
  SSL_CERT_FILE=/data/data/com.termux/files/home/.config/xtool/apple-ca-bundle.pem \
  SSL_CERT_DIR=/data/data/com.termux/files/usr/etc/tls/certs \
  USBMUXD_SOCKET_ADDRESS=UNIX:/data/data/com.termux/files/usr/var/run/usbmuxd \
  /data/data/com.termux/files/home/bin/xtool install --usb \
  --udid <YOUR_UDID> \
  /data/data/com.termux/files/home/projects/<your-project>/xtool/<app>.app'

Expected: Successfully installed!

Important launch note

• Provisioned bundle IDs are rewritten by xtool:
  • XTL-<TEAM_ID>.<original_bundle_id>
  • Example: XTL-6JKMV57Y77.com.example.helloworldiosxtool

Full troubleshooting playbook

A) xtool devices hangs / no device in idevice_id -l

1. Ensure Termux socket env is set:

export USBMUXD_SOCKET_ADDRESS=UNIX:/data/data/com.termux/files/usr/var/run/usbmuxd

2. Force host mode and reset USB-C port:

su -c 'echo source > /sys/class/typec/port0/power_role; echo host > /sys/class/typec/port0/data_role; svc usb resetUsbPort 0'

3. Restart usbmuxd cleanly:

su -c 'pkill usbmuxd || true; rm -f /data/data/com.termux/files/usr/var/run/usbmuxd /data/data/com.termux/files/usr/var/run/usbmuxd.pid; /data/data/com.termux/files/usr/bin/usbmuxd -f -v -l /data/data/com.termux/files/home/tmp/usbmuxd.log >/dev/null 2>&1 &'

4. If Apple device exists in kernel but not in idevice_id, find holder and kill it:

su -c 'for d in /sys/bus/usb/devices/*; do [ -f "$d/idVendor" ] || continue; vid=$(cat "$d/idVendor" 2>/dev/null); pid=$(cat "$d/idProduct" 2>/dev/null); bn=$(cat "$d/busnum" 2>/dev/null); dn=$(cat "$d/devnum" 2>/dev/null); [ -n "$vid" ] && echo "$d bus=$bn dev=$dn vid=$vid pid=$pid"; done'
su -c 'lsof /dev/bus/usb/002/002'
su -c 'kill -9 <PID_FROM_LSOF> || true'

5. Retry detect/pair:

USBMUXD_SOCKET_ADDRESS=UNIX:/data/data/com.termux/files/usr/var/run/usbmuxd idevicepair pair
USBMUXD_SOCKET_ADDRESS=UNIX:/data/data/com.termux/files/usr/var/run/usbmuxd idevice_id -l

B) Trust prompt does not show

• Run foreground usbmuxd -f -v once after force host reset (this is the known trigger):

su -c 'echo source > /sys/class/typec/port0/power_role; echo host > /sys/class/typec/port0/data_role; svc usb resetUsbPort 0'
su -c '/data/data/com.termux/files/usr/bin/usbmuxd -f -v'

Then daemonize and continue.

C) xtool auth / provisioning TLS failure (NIOSSL...unknownError([]))

1. Build CA bundle with Apple root:

mkdir -p ~/.config/xtool
cp /data/data/com.termux/files/usr/etc/tls/cert.pem ~/.config/xtool/apple-ca-bundle.pem
cat ~/tmp/apple-root-ca.pem >> ~/.config/xtool/apple-ca-bundle.pem

2. Ensure wrapper exports cert envs before exec:

export SSL_CERT_FILE=/data/data/com.termux/files/home/.config/xtool/apple-ca-bundle.pem
export SSL_CERT_DIR=/data/data/com.termux/files/usr/etc/tls/certs

3. Provide /etc/ssl/certs/ca-certificates.crt via Magisk overlay (required on read-only /system):

su -c 'mkdir -p /data/adb/modules/xtool-ca-fix/system/etc/ssl/certs'
su -c 'cp /data/data/com.termux/files/home/.config/xtool/apple-ca-bundle.pem /data/adb/modules/xtool-ca-fix/system/etc/ssl/certs/ca-certificates.crt'
su -c 'chmod 644 /data/adb/modules/xtool-ca-fix/system/etc/ssl/certs/ca-certificates.crt'
su -c 'cat > /data/adb/modules/xtool-ca-fix/module.prop <<"EOF"
id=xtool-ca-fix
name=xtool CA bundle overlay
version=1.0
versionCode=1
author=local
description=Provide /system/etc/ssl/certs/ca-certificates.crt for xtool on Termux
EOF'
su -c ': > /data/adb/modules/xtool-ca-fix/auto_mount; touch /data/adb/modules/xtool-ca-fix/update'

Reboot once, then verify:

su -c 'ls -l /system/etc/ssl/certs/ca-certificates.crt'

4. Pre-extract Anisette libs:

rm -rf ~/.config/xtool/Anisette/libs ~/.config/xtool/Anisette/tmp/lib
unzip -q ~/.config/xtool/Anisette/tmp/applemusic.apk \
  "lib/arm64-v8a/libCoreADI.so" \
  "lib/arm64-v8a/libstoreservicescore.so" \
  -d ~/.config/xtool/Anisette/tmp
mv ~/.config/xtool/Anisette/tmp/lib/arm64-v8a ~/.config/xtool/Anisette/libs

If xtool auth traps with epoll_ctl ... Operation not permitted under su, skip auth in that context and continue with install flow after CA overlay is active.

D) Install hangs at Waiting for device to be connected...

• Repeat USB recovery (force roles + foreground usbmuxd once), then retry install.

E) zip not found

pkg install -y zip

F) File permission/ownership errors after mixed root/user runs

Fix ownership on build/temp paths:

su -c 'chown -R u0_a210:u0_a210 /data/data/com.termux/files/usr/tmp/sh.xtool'
su -c 'chown -R u0_a210:u0_a210 /data/data/com.termux/files/home/projects/<your-project>/.build /data/data/com.termux/files/home/projects/<your-project>/xtool'

G) Swift SDK mismatch / parser weirdness / lock issues

1. Kill stale processes and remove lock files:

pkill -f "swift-build|swift-driver|swift-frontend|swift-package|xtool dev" || true
rm -f ~/projects/<your-project>/.build/.lock
rm -f ~/projects/<your-project>/xtool/.xtool-tmp/.build/.lock

2. Reinstall clean SDK bundle and verify toolchain match:

• SDK must be built from Xcode Swift matching Termux Swift (swiftlang-... must match).
• Exclude AppleDouble files (._*) when exporting from macOS.

3. Ensure Android host triples are present in SDK info.json:

"supportedTriples": [
  "aarch64-unknown-linux-gnu",
  "x86_64-unknown-linux-gnu",
  "aarch64-unknown-linux-android24",
  "aarch64-unknown-linux-android"
]

4. If redefinition of module 'libxml2' appears, remove duplicate modulemaps:

rm -f ~/.swiftpm/swift-sdks/darwin.clean.artifactbundle/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS26.1.sdk/usr/include/libxml/module.modulemap
rm -f ~/.swiftpm/swift-sdks/darwin.clean.artifactbundle/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/usr/include/libxml/module.modulemap

5. If compilation is slow/stuck or OOM:

• Run with -j 1
• Close heavy apps
• Retry

Quick validation commands

swift --version
swift sdk list
USBMUXD_SOCKET_ADDRESS=UNIX:/data/data/com.termux/files/usr/var/run/usbmuxd idevice_id -l
USBMUXD_SOCKET_ADDRESS=UNIX:/data/data/com.termux/files/usr/var/run/usbmuxd ideviceinfo -k DeviceName

Expected outcomes

• Build path: project xtool/*.app exists.
• Install path: command ends with Successfully installed!.
• Launch ID format is XTL-<TEAM_ID>.<original_bundle_id> when launching/debugging by ID.