Set up your device
Get your computer to recognize your iPhone. Install the driver, trust the computer and turn on Developer Mode, download device symbols before your first debug session, and choose between multiple devices.
Install the device driver
If your computer doesn't have the Apple device drivers, the device node in the KXBuild view says "click to set up". Click it. On the command line, run kxdevice doctor.
> kxdevice doctor| OS | What happens |
|---|---|
| Windows | Starts the Apple device service, which needs one administrator approval. Install Apple Devices from the Microsoft Store and open it first so the driver gets installed. |
| WSL | The driver lives on the Windows side. Plug the iPhone into Windows and WSL can use it directly. Don't pass the iPhone through to WSL with usbipd. |
| Linux | Installs and starts usbmuxd, which needs sudo |
| macOS | Nothing to do |
Set up the iPhone
Trust This Computer
The first time you connect, the iPhone asks whether to trust this computer. Unlock it and tap Trust. The prompt doesn't appear if you're using a charge-only cable or the iPhone is locked. If you tapped Don't Trust before, go to Settings > General > Transfer or Reset iPhone > Reset > Reset Location & Privacy, then unplug and reconnect.
Turn on Developer Mode
Go to Settings > Privacy & Security > Developer Mode, turn it on and let the iPhone restart. The switch only appears after the iPhone has been connected to a computer.
Wait for device symbols
The first time you debug on a given iOS version, KXBuild downloads its device symbols. It's a few GB and takes about ten minutes, but only once. Progress shows in a notification, and an interrupted download resumes next time.
Select a device
When your iPhone appears under the device node in the KXBuild view, click it to make it the active device. You can also switch from the Status Bar. On the command line, run kxdevice device list. The first column is the UDID. With several devices, pass --udid to choose one. Otherwise the first is used.
> kxdevice device listThe same iPhone may appear twice, once over USB and once over Wi-Fi. USB is more reliable for installing and debugging. If the list is empty, try another cable or USB port, and unlock the iPhone to check for a prompt. If Apple Devices can see the iPhone, so can KXBuild.
Next steps
Certificates and signing
You can build without a certificate, but you can't install on a device. Put your .p12 and .mobileprovision in the keychain folder and every build signs automatically. Also covers choosing a certificate in the project and overriding it on the command line.
Build and configure
Debug versus Release, choosing a scheme, target and configuration, overriding build settings, where build products go, when you get an .ipa and when Swift package dependencies resolve.