Xcode Kotlin - Xcode support for Kotlin browsing and debugging
The xcode-kotlin plugin allows debugging of Kotlin code running in an iOS application, directly from Xcode.
This enables a smoother development and integration experience for iOS developers using shared code from Kotlin, and a more accessible experience for larger teams where everyone may not be editing the shared code directly.
🔑🔑 Improving the iOS dev experience is key to KMP adoption.
One of Touchlab’s core goals is to improve the developer experience with KMP, particularly around tooling and especially for iOS developers. We believe that improving the iOS dev experience is key to KMP adoption and we’re going to continue to work on ways to support the iOS KMP community.
Let us know how you’re using (or will use) the xcode-kotlin plugin by taking our 5-minute survey.
💥 Xcode 15+ support 💥
Xcode 15 introduced a bug where it crashes if you have any non-Apple Xcode plugin installed.
Until the bug is fixed, we have found a workaround that’s built into the
All your Xcode 15 installations will have the workaround applied to them during
sync and a new
The workaround works like this:
- Disabling Xcode Kotlin plugin (if it’s installed)
IDEPerformanceDebuggerplugin that’s in Xcode
- Running each Xcode 15 installation you have (15.0, 15.0.1, etc.)
- Re-enabling Xcode Kotlin plugin (if it’s installed)
This lets Xcode create a valid plugin cache and use it the next time it runs. When the plugin cache isn’t used, Xcode tries to scan all plugins and due to a bug freezes extension points that are used by custom plugins, like Xcode Kotlin. When the plugin cache is used, the execution goes through a different path so those extension points are not frozen, allowing Xcode Kotlin to load properly.
The reason Xcode doesn’t use the cache otherwise is
that it expects to find an entry for
But for some reason,
Xcode doesn’t add the
IDEPerformanceDebugger entry to the plugin cache unless the plugin is enabled.
So essentially, performing these steps should also lead to faster Xcode startup time, what a bargain!
In case your Xcode starts crashing again, run
xcode-kotlin fix-xcode15 (or
This will reapply the workaround and should make your Xcode work again.
For direct assistance, please contact Touchlab to discuss support options.
xcode-kotlin project consists of two main parts: the CLI manager, and the Xcode plugin itself.
The CLI (command line interface) is an executable that is installed on your machine and manages the plugin installation(s). For existing users of
xcode-kotlin, the CLI is new. The CLI was added to enable the following:
- Homebrew installation
- Better Xcode integration (No more “Load Bundle” popups!)
- Easier management of multiple Xcode installations
- Automatic “sync”. When Xcode updates, we need to update the plugin config. This previously required updating the
xcode-kotlinproject GitHub repo, pulling, and reinstalling. The CLI can do this locally.
- Better diagnostic info and support for install issues.
Xcode does not generally allow plugins, but it does allow for language definitions and lldb integrations. There is no official process for including these things, which is why the CLI is necessary. However, lldb is an open standard and debugging integrations are a common use case. We share, and contribute to, the official Kotlin language lldb extensions.
First you need to install the CLI that takes care of installing the plugin into Xcode. The CLI is available through Homebrew:
brew install xcode-kotlin
Once installed, run the CLI:
This will install the plugin with support for all of your currently installed Xcode installations.
The CLI installer is a significant improvement over our original install process, but is also more complex. Please let us know if you encounter any issues. If there is a crash using the tool, it will ask if you want to upload a report. Please do. For other problems, please file an issue in Github.
We aren’t anticipating any major problems, but If you cannot get the plugin to install properly, you can follow the MANUAL_INSTALL instructions as a workaround.
When you update Xcode versions, you’ll need to enable the plugin for that version. Run:
This process adds the UUID for the new Xcode version to the local plugin configuration. For users familiar with earlier versions of
xcode-kotlin, Xcode updates would previously require an update from GitHub.
If properly set up, you should be able to add Kotlin source to Xcode, set up breakpoints, and step through code. To add Kotlin source to Xcode, follow these steps:
- Add a New Group to the Xcode project.
- Add Files to the newly created group (Kotlin Debug in this instance).
- Select the folders in the Kotlin library that are directly relevant to the iOS build, which will usually be
iosMain. Make sure “Copy items into destination group’s folder (if needed)” is unchecked.
When you’re done, your Xcode project structure should look something like this:
The project used as an example above is KaMPKit. Check it out if you want to see a project that already includes Kotlin file references in Xcode. It’s an excellent template for Kotlin multiplatform mobile projects.
If you’re having any issues, try reinstalling the plugin:
xcode-kotlin uninstall xcode-kotlin install
If it doesn’t fix the issue, run:
This will show you status of the plugin and a list of found Xcode installations. If the Xcode you want to use isn’t listed you can run the
sync command and provide it with paths to Xcode installations to add support for:
xcode-kotlin sync /Volumes/ExternalVolume1/Xcode.app
If the issue still persists, open a new GitHub issue and include the output of the
Our Xcode plugin incorporates the work of other brave souls around the web exploring the undocumented corners of Xcode. See ABOUT.