|
4 | 4 |
|
5 | 5 | 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. |
6 | 6 |
|
7 | | -************************************************************************* |
8 | | -## 🔑🔑 Improving the iOS dev experience is key to KMP adoption. |
| 7 | +## [Documentation](https://touchlab.co/xcodekotlin) |
9 | 8 |
|
10 | | -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. |
11 | | - |
12 | | -Let us know how you're using (or will use) the xcode-kotlin plugin by taking our 5-minute survey. |
13 | | - |
14 | | -> [Open Touchlab Xcode Plugin User Survey](https://touchlabwaitlist.typeform.com/xcodepluginuser) |
15 | | -************************************************************************* |
16 | | - |
17 | | -## 💥 Xcode 15+ support 💥 |
18 | | - |
19 | | -Xcode 15 introduced a bug where it crashes if you have any non-Apple Xcode plugin installed. |
20 | | -Until the bug is fixed, we have found a workaround that's built into the `xcode-kotlin` CLI. |
21 | | -All your Xcode 15 installations will have the workaround applied to them during `install`, |
22 | | -`sync` and a new `fix-xcode15` commands. |
23 | | - |
24 | | -The workaround works like this: |
25 | | -1. Disabling Xcode Kotlin plugin (if it's installed) |
26 | | -2. Enabling `IDEPerformanceDebugger` plugin that's in Xcode |
27 | | -3. Running each Xcode 15 installation you have (15.0, 15.0.1, etc.) |
28 | | -4. Disabling `IDEPerformanceDebugger` plugin |
29 | | -5. Re-enabling Xcode Kotlin plugin (if it's installed) |
30 | | - |
31 | | -This lets Xcode create a valid plugin cache and use it the next time it runs. |
32 | | -When the plugin cache isn't used, |
33 | | -Xcode tries to scan all plugins and due to a bug freezes extension points that are used by custom plugins, |
34 | | -like Xcode Kotlin. |
35 | | -When the plugin cache is used, the execution goes through a different path so those extension points are not frozen, |
36 | | -allowing Xcode Kotlin to load properly. |
37 | | - |
38 | | -The reason Xcode doesn't use the cache otherwise is |
39 | | -that it expects to find an entry for `IDEPerformanceDebugger.framework`. |
40 | | -But for some reason, |
41 | | -Xcode doesn't add the `IDEPerformanceDebugger` entry to the plugin cache unless the plugin is enabled. |
42 | | -So essentially, performing these steps should also lead to faster Xcode startup time, what a bargain! |
43 | | - |
44 | | -In case your Xcode starts crashing again, run `xcode-kotlin fix-xcode15` (or `xcode-kotlin sync`). |
45 | | -This will reapply the workaround and should make your Xcode work again. |
46 | | - |
47 | | -## Getting Help |
48 | | - |
49 | | -Xcode-kotlin support can be found in the Kotlin Community Slack, [request access here](http://slack.kotlinlang.org/). Post in the "[#touchlab-tools](https://kotlinlang.slack.com/archives/CTJB58X7X)" channel. |
50 | | - |
51 | | -For direct assistance, please [contact Touchlab](https://go.touchlab.co/contactus-gh) to discuss support options. |
52 | | - |
53 | | -## Overview |
54 | | - |
55 | | -The `xcode-kotlin` project consists of two main parts: the CLI manager, and the Xcode plugin itself. |
56 | | - |
57 | | -### CLI |
58 | | - |
59 | | -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: |
60 | | - |
61 | | -- Homebrew installation |
62 | | -- Better Xcode integration (No more "Load Bundle" popups!) |
63 | | -- Easier management of multiple Xcode installations |
64 | | -- Automatic "sync". When Xcode updates, we need to update the plugin config. This previously required updating the `xcode-kotlin` project GitHub repo, pulling, and reinstalling. The CLI can do this locally. |
65 | | -- Better diagnostic info and support for install issues. |
66 | | - |
67 | | -### Xcode Plugin |
68 | | - |
69 | | -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](https://github.com/JetBrains/kotlin/blob/master/kotlin-native/llvmDebugInfoC/src/scripts/konan_lldb.py). |
70 | | - |
71 | | -## Installation |
72 | | - |
73 | | -First you need to install the CLI that takes care of installing the plugin into Xcode. The CLI is available through Homebrew: |
74 | | - |
75 | | -```shell |
76 | | -brew install xcode-kotlin |
77 | | -``` |
78 | | - |
79 | | -Once installed, run the CLI: |
80 | | - |
81 | | -```shell |
82 | | -xcode-kotlin install |
83 | | -``` |
84 | | - |
85 | | -This will install the plugin with support for all of your currently installed Xcode installations. |
86 | | - |
87 | | -## Manual Install |
88 | | - |
89 | | -The CLI installer is a significant improvement over our original install process, but is also more complex. |
90 | | -Please let us know if you encounter any issues. |
91 | | -If there is a crash using the tool, it will ask if you want to upload a report. |
92 | | -Please do. |
93 | | -For other problems, [please file an issue in Github](https://github.com/touchlab/xcode-kotlin/issues). |
94 | | - |
95 | | -We aren't anticipating any major problems, but If you cannot get the plugin to install properly, |
96 | | -you can follow the [MANUAL_INSTALL](MANUAL_INSTALL.md) instructions as a workaround. |
97 | | - |
98 | | -## Sync |
99 | | - |
100 | | -When you update Xcode versions, you'll need to enable the plugin for that version. Run: |
101 | | - |
102 | | -```shell |
103 | | -xcode-kotlin sync |
104 | | -``` |
105 | | - |
106 | | -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](https://github.com/touchlab/xcode-kotlin/pull/37/files). |
107 | | - |
108 | | -## Plugin Usage |
109 | | - |
110 | | -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: |
111 | | - |
112 | | -1. Add a New Group to the Xcode project. |
113 | | -2. Add Files to the newly created group (Kotlin Debug in this instance). |
114 | | -3. Select the folders in the Kotlin library that are directly relevant to the iOS build, which will usually be `commonMain` and `iosMain`. Make sure "Copy items into destination group's folder (if needed)" is unchecked. |
115 | | - |
116 | | -<img src="https://tl-navigator-images.s3.us-east-1.amazonaws.com/docimages/2022-04-27_08-31-XcodeKotlinFileReferencesSteps.png" alt="XcodeKotlinFileReferencesSteps" style="zoom: 25%;" /> |
117 | | - |
118 | | -When you're done, your Xcode project structure should look something like this: |
119 | | - |
120 | | - |
121 | | - |
122 | | -### Sample |
123 | | - |
124 | | -The project used as an example above is [KaMPKit](https://github.com/touchlab/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. |
125 | | - |
126 | | -## Troubleshooting |
127 | | - |
128 | | -If you're having any issues, try reinstalling the plugin: |
129 | | - |
130 | | -```shell |
131 | | -xcode-kotlin uninstall |
132 | | -xcode-kotlin install |
133 | | -``` |
134 | | - |
135 | | -If it doesn't fix the issue, run: |
136 | | - |
137 | | -```shell |
138 | | -xcode-kotlin info |
139 | | -``` |
140 | | - |
141 | | -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: |
142 | | - |
143 | | -``` |
144 | | -xcode-kotlin sync /Volumes/ExternalVolume1/Xcode.app |
145 | | -``` |
146 | | - |
147 | | -If the issue still persists, open a new GitHub issue and include the output of the `info` command. |
148 | | - |
149 | | -## About |
150 | | - |
151 | | -Our Xcode plugin incorporates the work of other brave souls around the web exploring the undocumented corners of Xcode. See [ABOUT](ABOUT.md). |
152 | | - |
153 | | -*********************** |
154 | | -> ## Subscribe! |
155 | | -> |
156 | | -> We build solutions that get teams started smoothly with Kotlin Multiplatform Mobile and ensure their success in production. Join our community to learn how your peers are adopting KMM. |
157 | | - [Sign up here](https://go.touchlab.co/newsletter-gh)! |
| 9 | +The main documentation for Xcode Kotlin lives [here](https://touchlab.co/xcodekotlin). For info on contributing, see [CONTRIBUTING.md](CONTRIBUTING.md). |
0 commit comments