Debug Kotlin with Xcode References

I’m going to share a very (very) simple, helpful, little trick if you want to debug a Kotlin shared framework within an iOS application. Adding Xcode references to the Kotlin files in your shared library will enable you to do frequently used development practices, such as setting breakpoints or opening files from a memory debugger.

Before getting started though, it’s important to note that your shared Kotlin framework needs to be dynamic for these file references to be useful. If it isn’t, then any breakpoints you set in your Kotlin files in Xcode will not be hit. Other debugging tools and practices will not yield useful results such as function names and line numbers.

If you don’t know how to get your shared Kotlin library to produce a dynamic framework, we’re using Touchlab’s fork of the Kotlin Multiplatform Cocoapods plugin.

Double or right click in the Project Navigator, which is the left side pane of Xcode that shows the project’s structure (shown below).

First select New Group from the dropdown and create a directory (“Kotlin Debug” in the example below). This is where we’re going to put the references.

Next, double or right click your new directory in the Project Navigator and select Add Files to [Directory Name].

In the Finder window that appears, navigate to your shared Kotlin library. Feel free to add as many of the library files as you like, but I recommend just [Shared Kotlin Library]/src/commonMain/ and [Shared Kotlin Library]/src/iosMain/. Together, those two directories contain all of the Kotlin files you may need to debug from your iOS application.

If you’re using Instruments to debug memory issues in your shared Kotlin library, then you may need to close and reopen Xcode before Instruments is able to open your Kotlin files in the Xcode window containing your iOS project.