Run and debug

Three ways to start (Build & Run, Run and Attach), what you see if a step fails after F5, panels and output during a debug session, launch.json fields and Dart debugging for Flutter.

Select your iPhone, set a breakpoint in your code and press F5. The extension builds, signs, installs and launches the app, then attaches the debugger, with no configuration. When a breakpoint hits you get the standard VS Code debug view. Here's an app running and debugging on a device from Windows.

Three ways to start

Mode	Where	What it does
Build & Run	F5, ▶ in the view title bar, or the target row button	Builds with the current configuration, signs, installs on the selected device, launches and attaches the debugger
Run	KXBuild: Run, or the target row button	Skips the build. Installs the most recent build and launches it.
Attach	KXBuild: Attach to Running App	Lists the apps running on the iPhone and attaches the debugger to the one you pick

The build runs before the debug session starts, so the Restart button on the debug toolbar doesn't recompile. After changing code, stop and press F5 again.

Common errors

Every step after the build shows a progress notification you can cancel. If a step fails, the message names that step. Click "Show Output" for the full log.

Message	Fix
No iOS device selected	Select a device in the KXBuild view
Developer Mode is off	Turn on Developer Mode on the iPhone and restart it
Developer Disk Image is not mounted	Reconnect the iPhone or run doctor
The device is not paired/trusted	Unlock the iPhone and tap Trust
Not enough free space on the device	Free up storage on the iPhone and try again
No valid provisioning profile, or the device is not in the provisioning profile	See Certificates and signing
did not report the app as launched in time	Unlock the iPhone and check the connection
didn't start in time	The app may be crashing on launch. Check the device log.

While debugging

You can set breakpoints in Swift, Objective-C, C / C++ and the Kotlin code of Kotlin Multiplatform projects. Stepping, variables, the call stack, watch expressions and the Debug Console all work as in any VS Code debug session, and you can type lldb commands in the Debug Console. When you stop somewhere without source, open the assembly view. App output goes to Output > KXBuild Console and the build log to Output > KXBuild. Stopping the session quits the app on the iPhone, as Xcode does.

launch.json

F5 works without a launch.json. Add one only when you want to pin a device, target or build configuration. Set the debugger type to kxbuild. Here's an example and the available fields.

{
  "version": "0.2.0",
  "configurations": [
    { "type": "kxbuild", "request": "launch", "name": "KXBuild: Build & Run", "build": true },
    { "type": "kxbuild", "request": "launch", "name": "KXBuild: Run",         "build": false },
    { "type": "kxbuild", "request": "attach", "name": "KXBuild: Attach",      "attachPid": 0 }
  ]
}

Field	Description
build	`true` builds before installing. `false` installs the most recent build.
device	Device UDID. Omit to use the device selected in the view.
bundle	Bundle ID of the app target to run. Omit to use the project's only app target. If there are several, you're asked to pick one.
configuration	Debug or Release. Omit to use the one selected in the view.
attachPid	Process ID to attach to. `0` shows a list to pick from when the session starts.

Flutter

In Flutter projects, F5 debugs the native Objective-C and Swift code right away. Debugging Dart code needs the VS Code Dart extension. If KXBuild detects a Flutter project without it, you're offered a one-click install. Afterwards run Build & Run again, and native and Dart breakpoints both work, with hot reload.

React Native

For React Native and Expo, KXBuild debugs the native side. For JS breakpoints, use the Metro / Hermes debugger. An imported uni-app project is a native shell around a WebView. Debug the native part in KXBuild and the page JS with the tools built into HBuilderX.

Next steps

Code completion and indexing

Completion, go to definition and error checking for Swift, Objective-C and C/C++, ready as soon as you open the project. When you need to build once first, and what to do when completion misbehaves.

Troubleshooting

Run kxbuild doctor first. Then look up your error message by category: install, project, signing, device, release or extension. Also covers where to find the logs.