xtool

https://github.com/xtool-org/xtool
Admin
xtool is a cross-platform Xcode replacement that enables building and deploying iOS apps using...
Tokens:8,481
Snippets:92
Trust Score:7
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Run xtool setup

Source: https://github.com/xtool-org/xtool/blob/main/Documentation/xtool.docc/Installation-macOS.md

Run the one-time setup command to configure xtool. You will be prompted to choose a login mode and provide credentials.

```bash
xtool setup
```

--------------------------------

### Install xtool with Homebrew

Source: https://github.com/xtool-org/xtool/blob/main/Documentation/xtool.docc/Installation-macOS.md

Install xtool using Homebrew from the xtool-org tap.

```bash
brew install xtool-org/tap/xtool
```

--------------------------------

### Verify xtool installation with xtool --help

Source: https://github.com/xtool-org/xtool/blob/main/Documentation/xtool.docc/Installation-macOS.md

Confirm that xtool is installed correctly by displaying its help output.

```bash
xtool --help
# OVERVIEW: Cross-platform Xcode replacement
# ...
```

--------------------------------

### Install usbmuxd on Ubuntu/Debian

Source: https://github.com/xtool-org/xtool/blob/main/Documentation/xtool.docc/Installation-Linux.md

Install usbmuxd on Ubuntu/Debian if it is not already present.

```bash
sudo apt-get install usbmuxd
```

--------------------------------

### Download and install xtool

Source: https://github.com/xtool-org/xtool/blob/main/Documentation/xtool.docc/Installation-Linux.md

Download the latest xtool.AppImage for your architecture, rename it to xtool, make it executable, and move it to a directory in your PATH.

```bash
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/
```

--------------------------------

### Install libimobiledevice-utils and use ideviceinfo

Source: https://github.com/xtool-org/xtool/blob/main/Documentation/xtool.docc/Installation-Linux.md

Install additional libimobiledevice tools like ideviceinfo, which provide many ways to interact with your iOS device from the command line.

```bash
sudo apt-get install libimobiledevice-utils
# The following NEW packages will be installed:
#   libimobiledevice-utils
# 0 upgraded, 1 newly installed
ideviceinfo
# DeviceName: Kabir's iPhone
# SerialNumber: ...
# UniqueDeviceID: ...
# ...
```

--------------------------------

### Verify Swift installation

Source: https://github.com/xtool-org/xtool/blob/main/Documentation/xtool.docc/Installation-Linux.md

Verify that the Swift 6.4 toolchain is installed correctly after following the installation steps for your Linux distribution.

```bash
swift --version
# should say something like:
# Swift version 6.4 (swift-6.4-RELEASE)
```

--------------------------------

### xtool setup Xcode.xip path prompt

Source: https://github.com/xtool-org/xtool/blob/main/Documentation/xtool.docc/Installation-Linux.md

After logging in, xtool asks for the path to the Xcode.xip file you downloaded earlier.

```text
Choice (0-1): 0
...
Path to Xcode.xip:
```

--------------------------------

### Verify iOS Swift SDK installation

Source: https://github.com/xtool-org/xtool/blob/main/Documentation/xtool.docc/Installation-Linux.md

Confirm that the iOS Swift SDK was generated and installed by listing available SDKs.

```bash
swift sdk list
# darwin
```

--------------------------------

### xtool setup login mode prompt

Source: https://github.com/xtool-org/xtool/blob/main/Documentation/xtool.docc/Installation-macOS.md

The interactive prompt shown by xtool setup, asking you to choose between API Key (0) or Password (1) login mode.

```text
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):
```

--------------------------------

### Check Swift version with swift --version

Source: https://github.com/xtool-org/xtool/blob/main/Documentation/xtool.docc/Installation-macOS.md

Verify that Swift is installed and available. The output shows the Swift version and target platform.

```bash
swift --version
# swift-driver version: 1.120.5 Apple Swift version 6.1 (swiftlang-6.1.0.110.21 clang-1700.0.13.3)
# Target: arm64-apple-macosx15.0
```

--------------------------------

### Create App.entitlements file

Source: https://github.com/xtool-org/xtool/blob/main/Documentation/xtool.docc/Control.md

Create an App.entitlements file with the necessary entitlements, for example the com.apple.developer.homekit entitlement.

```plist
<?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>
```

--------------------------------

### Check usbmuxd availability

Source: https://github.com/xtool-org/xtool/blob/main/Documentation/xtool.docc/Installation-Linux.md

Check if usbmuxd is already installed on your system. If the command is not found, install it using your package manager.

```bash
usbmuxd --help
# Usage: usbmuxd [OPTIONS]
# ...
```

--------------------------------

### Custom Info.plist example

Source: https://github.com/xtool-org/xtool/blob/main/Documentation/xtool.docc/Control.md

Example Info.plist that sets landscape-only orientations and a display name. The default Info.plist has portrait orientation, so this replaces it. The CFBundleDisplayName key is added because it is not present by default.

```plist
<?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>UISupportedInterfaceOrientations</key>
    <array>
        <string>UIInterfaceOrientationLandscapeLeft</string>
        <string>UIInterfaceOrientationLandscapeRight</string>
    </array>
    <key>CFBundleDisplayName</key>
    <string>My App</string>
</dict>
</plist>
```

--------------------------------

### Check Xcode iOS SDK path with xcrun

Source: https://github.com/xtool-org/xtool/blob/main/Documentation/xtool.docc/Installation-macOS.md

Verify that Xcode is installed and configured with the iOS SDK. The expected output shows the path to the iPhoneOS SDK.

```bash
xcrun -sdk iphoneos -show-sdk-path
# /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS18.4.sdk
```

--------------------------------

### Create Widget.swift with WidgetKit widget code

Source: https://github.com/xtool-org/xtool/blob/main/Documentation/xtool.docc/Appex.md

Defines a WidgetBundle with a HelloWidget StaticConfiguration. The provider returns a single timeline entry and refreshes after one hour. Use this as a minimal starting point for a WidgetKit widget.

```swift
import WidgetKit
import SwiftUI

@main struct Bundle: WidgetBundle {
    var body: some Widget {
        HelloWidget()
    }
}

struct HelloWidget: Widget {
    var body: some WidgetConfiguration {
        StaticConfiguration(
            kind: "HelloWidget",
            provider: Provider()
        ) { entry in
            VStack {
                Text(entry.date, style: .date)
            }
            .containerBackground(.fill.tertiary, for: .widget)
        }
        .configurationDisplayName("HelloWidget")
        .description("This is an example widget.")
    }

    struct Entry: TimelineEntry {
        var date = Date()
    }

    struct Provider: TimelineProvider {
        func placeholder(in context: Context) -> Entry {
            Entry()
        }

        func getSnapshot(
            in context: Context,
            completion: @escaping (Entry) -> Void
        ) {
            completion(Entry())
        }

        func getTimeline(
            in context: Context,
            completion: @escaping (Timeline<Entry>) -> Void
        ) {
            completion(Timeline(
                entries: [Entry()],
                policy: .after(.now + 3600)
            ))
        }
    }
}
```

--------------------------------

### Run xtool demos: ./Examples/test.sh

Source: https://github.com/xtool-org/xtool/blob/main/Examples/README.md

Runs all or a specific demo for integration testing. Options: --build or --run; omitting both builds and runs, omitting the demo name loops through all demos.

```bash
./Examples/test.sh [--build | --run] [DemoName]
```

--------------------------------

### xtool --help command output

Source: https://github.com/xtool-org/xtool/blob/main/README.md

Shows the xtool command-line help output. Lists configuration, development, and device subcommands. Use `xtool help <subcommand>` for detailed help on a specific subcommand.

```bash
$ xtool --help
OVERVIEW: Cross-platform Xcode replacement

USAGE: xtool <subcommand>

OPTIONS:
  -h, --help              Show help information.

CONFIGURATION SUBCOMMANDS:
  setup                   Set up xtool for iOS development
  auth                    Manage Apple Developer Services authentication
  sdk                     Manage the Darwin Swift SDK

DEVELOPMENT SUBCOMMANDS:
  new                     Create a new xtool SwiftPM project
  dev                     Build and run an xtool SwiftPM project
  ds                      Interact with Apple Developer Services

DEVICE SUBCOMMANDS:
  devices                 List devices
  install                 Install an ipa file to your device
  uninstall               Uninstall an installed app
  launch                  Launch an installed app

  See 'xtool help <subcommand>' for detailed help.
```

--------------------------------

### Create xtool.yml with version and bundleID

Source: https://github.com/xtool-org/xtool/blob/main/Documentation/xtool.docc/Control.md

Creates a minimal xtool.yml file with version 1 and a bundle ID. This is the default template generated by `xtool new`.

```bash
cat > xtool.yml << EOF
version: 1
bundleID: com.example.Hello
EOF
```

--------------------------------

### Update xtool.yml with extension configuration

Source: https://github.com/xtool-org/xtool/blob/main/Documentation/xtool.docc/Appex.md

Adds the product and extensions configuration to the xtool.yml file, specifying the widget product and its Info.plist path.

```diff
  version: 1
  bundleID: com.example.Hello
+ product: Hello
+ extensions:
+   - product: HelloWidget
+     infoPath: HelloWidget-Info.plist
```

--------------------------------

### Add a new product to Package.swift

Source: https://github.com/xtool-org/xtool/blob/main/Documentation/xtool.docc/Appex.md

Adds a new library product and target for the widget extension to the package manifest. The diff shows the required additions.

```diff
  // swift-tools-version: 6.0
  
  import PackageDescription
  
  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"),
      ]
  )
```

--------------------------------

### Top-level resources in xtool.yml

Source: https://github.com/xtool-org/xtool/blob/main/Documentation/xtool.docc/Control.md

Add a resources array to xtool.yml to copy files directly to the root of the app bundle. The file will be copied to Hello.app/GoogleServices-Info.plist.

```yaml
resources:
- Resources/GoogleServices-Info.plist
```

--------------------------------

### Load resource image with Bundle.module

Source: https://github.com/xtool-org/xtool/blob/main/Documentation/xtool.docc/Control.md

Use Bundle.module to load a resource image that was included via SwiftPM resources.

```swift
Image("Blob", bundle: Bundle.module)
```

--------------------------------

### Run xtool container and forward usbmuxd

Source: https://github.com/xtool-org/xtool/blob/main/Linux/README.md

Used to run and access the xtool container. The first command spawns a shell with the xtool root bind-mounted at /xtool. The second keeps the host's usbmuxd forwarded to port 27015 so the container's libusbmuxd can reach iOS devices.

```bash
docker compose run --rm xtool
```

```bash
socat -dd TCP-LISTEN:27015,range=127.0.0.1/32,reuseaddr,fork UNIX-CLIENT:/var/run/usbmuxd
```

--------------------------------

### Configure xtool.yml with entitlementsPath

Source: https://github.com/xtool-org/xtool/blob/main/Documentation/xtool.docc/Control.md

Tell xtool about the entitlements file by setting the entitlementsPath key in xtool.yml.

```yaml
entitlementsPath: App.entitlements
```

--------------------------------

### Create Info.plist for Widget Extension

Source: https://github.com/xtool-org/xtool/blob/main/Documentation/xtool.docc/Appex.md

Use this XML to create the Info.plist file at ./HelloWidget-Info.plist. The NSExtensionPointIdentifier value com.apple.widgetkit-extension tells the system this is a Widget Extension. For other extension types, the value and possibly other keys like NSExtensionPrincipalClass may differ.

```xml
<?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>NSExtension</key>
    <dict>
        <key>NSExtensionPointIdentifier</key>
        <string>com.apple.widgetkit-extension</string>
    </dict>
</dict>
</plist>
```

--------------------------------

### SwiftPM resources in Package.swift

Source: https://github.com/xtool-org/xtool/blob/main/Documentation/xtool.docc/Control.md

Add a resource file to your Swift package target using the .copy resource. This is the easiest way to include non-code files like images.

```swift
targets: [
    .target(
        name: "Hello",
        resources: [.copy("Blob.png")]
    ),
]
```

--------------------------------

### XKit SwiftPM dependency

Source: https://github.com/xtool-org/xtool/blob/main/README.md

Shows how to add XKit as a SwiftPM dependency in your own app. Use the package dependency and target dependency lines in your Package.swift file.

```swift
// package dependency:
.package(url: "https://github.com/xtool-org/xtool", .upToNextMinor(from: "1.2.0"))
// target dependency:
.product(name: "XKit", package: "xtool")
```

--------------------------------

### Add infoPath key to xtool.yml

Source: https://github.com/xtool-org/xtool/blob/main/Documentation/xtool.docc/Control.md

Adds the `infoPath` key to xtool.yml to point to a custom Info.plist file. This tells xtool to use the specified file for adding/updating Info.plist keys.

```yaml
infoPath: path/to/Info.plist
```

--------------------------------

### Set app icon with iconPath in xtool.yml

Source: https://github.com/xtool-org/xtool/blob/main/Documentation/xtool.docc/Control.md

Set the iconPath key in xtool.yml to use a PNG file as your app icon. The icon should ideally be 1024x1024px.

```yaml
iconPath: Resources/AppIcon.png
```
Tokens:
Raw