xtool Documentation

xtool is a cross-platform (Linux, WSL, and macOS) tool designed to replicate Xcode functionality using open standards. It allows developers to:

• Build SwiftPM packages into iOS applications.
• Sign and install iOS apps.
• Interact with Apple Developer Services programmatically.

To add entitlements (e.g., for HomeKit), create an .entitlements file and reference it in xtool.yml using the entitlementsPath key.

Troubleshooting Entitlements:

• Some entitlements (like Network Extension) require a paid Apple Developer Program account.
• Some require special permission from Apple (like User Notifications Filtering).
• Many entitlements require specific 'Capabilities' to be enabled. xtool handles the mapping for supported capabilities, but if you encounter an unhandled one, you may need to report it.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.developer.homekit</key>
    <true/>
</dict>
</plist>

Although xtool does not use the Xcode build system, you must have Xcode installed for the iOS SDK and toolchain.

1. Install Xcode and launch it once to complete any installation prompts.
2. Verify the iOS SDK is available using xcrun:

xcrun -sdk iphoneos -show-sdk-path

3. Verify Swift is installed:

swift --version

You can install xtool using Homebrew or by manual download.

Using Homebrew: Run the following command:

brew install xtool-org/tap/xtool

Manual Installation:

1. Download xtool.app from the latest GitHub release.
2. Move xtool.app into /Applications.
3. Launch the app and run the suggested script to add the xtool command to your PATH.

Verify the installation by running:

xtool --help

To install xtool, download the latest xtool.AppImage for your architecture from the GitHub Releases page, rename it to xtool, make it executable, and move it to a directory in your PATH (e.g., /usr/local/bin/).

Verify the installation by running xtool --help.

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/

# Verify
xtool --help

To build the macOS version of xtool, you must use XcodeGen to generate the Xcode project. Follow these steps:

1. Install XcodeGen.
2. Navigate to the ./macOS directory within the repository.
3. Run the xcodegen command to generate the project files.
4. Open the generated Xcode project.
5. Build the XToolMac scheme.

To use xtool on Windows, you must use the Windows Subsystem for Linux (WSL).

Additionally, you must configure USB passthrough to allow WSL to access your iOS device. Follow Microsoft's instructions to install and use USBIPD to bind your iOS device to the WSL instance.

Before installing xtool, ensure the following dependencies are met:

• Swift: Install the Swift 6.3 toolchain (or newer) from swift.org.
• usbmuxd: Required for communicating with iOS devices. On Ubuntu/Debian, install via sudo apt-get install usbmuxd. It is also recommended to install libimobiledevice-utils for additional device interaction tools (like ideviceinfo).
• Xcode: Download Xcode 26 (or the version required by your workflow) from the Apple Developer website. You will need the path to the .xip file during xtool setup.

Update your app's bundle ID by editing the bundleID field in xtool.yml.

Note: xtool adds a prefix (e.g., XTL-1234.com.example.Hello) when signing and installing on real devices to prevent bundle ID conflicts between different users of free Apple Developer accounts.

After installation, run xtool setup to perform a one-time configuration. This process involves two main steps:

1. Login: Choose between two authentication modes:

   • 0: API Key: Recommended for paid Apple Developer Program members. Requires a Team Key with the App Manager role generated via App Store Connect.
   • 1: Password: For users without a paid membership. Uses private Apple APIs and requires email, password, and 2FA.

2. SDK Setup: Provide the local path to your downloaded Xcode.xip file. xtool will extract it to generate and install the necessary iOS Swift SDK.

Verify the SDK installation with swift sdk list.

xtool setup

# After setup, verify the SDK
swift sdk list

Add a new .library product and a corresponding .target to your Package.swift file to represent the extension.

let package = Package(
    name: "Hello",
    platforms: [.iOS(.v17)],
    products: [
        .library(
            name: "Hello",
            targets: ["Hello"]
        ),
        .library(
            name: "HelloWidget",
            targets: ["HelloWidget"]
        ),
    ],
    targets: [
        .target(name: "Hello"),
        .target(name: "HelloWidget"),
    ]
)