Move everything under kotlin-native folder

I was forced to manually do update the following files, because otherwise they would be ignored according .gitignore settings. Probably they should be deleted from repo. Interop/.idea/compiler.xml Interop/.idea/gradle.xml Interop/.idea/libraries/Gradle__org_jetbrains_kotlin_kotlin_runtime_1_0_3.xml Interop/.idea/libraries/Gradle__org_jetbrains_kotlin_kotlin_stdlib_1_0_3.xml Interop/.idea/modules.xml Interop/.idea/modules/Indexer/Indexer.iml Interop/.idea/modules/Runtime/Runtime.iml Interop/.idea/modules/StubGenerator/StubGenerator.iml backend.native/backend.native.iml backend.native/bc.frontend/bc.frontend.iml backend.native/cli.bc/cli.bc.iml backend.native/cli.bc/src/org/jetbrains/kotlin/cli/bc/K2Native.kt backend.native/cli.bc/src/org/jetbrains/kotlin/cli/bc/K2NativeCompilerArguments.kt backend.native/tests/link/lib/foo.kt backend.native/tests/link/lib/foo2.kt backend.native/tests/teamcity-test.property
2020-10-27 21:00:28 +03:00
parent 91e4162dad
commit f624800b84
2830 changed files with 0 additions and 0 deletions
@@ -0,0 +1,74 @@
+# Symbolicating iOS crash reports
+
+Debugging an iOS application crash sometimes involves analyzing crash reports.
+More info about crash reports can be found
+[in the official documentation](https://developer.apple.com/library/archive/technotes/tn2151/_index.html).
+
+Crash reports generally require symbolication to become properly readable:
+symbolication turns machine code addresses into human-readable source locations.
+The document below describes some specific details of symbolicating crash reports
+from iOS applications using Kotlin.
+
+## Producing .dSYM for release Kotlin binaries
+
+To symbolicate addresses in Kotlin code (e.g. for stack trace elements
+corresponding to Kotlin code) `.dSYM` bundle for Kotlin code is required.
+
+By default Kotlin/Native compiler produces `.dSYM` for release
+(i.e. optimized) binaries on Darwin platforms. This can be disabled with `-Xadd-light-debug=disable`
+compiler flag. At the same time this option is disabled by default for other platforms, to enable it use `-Xadd-light-debug=enable`.
+To control option in Gradle, use
+
+```kotlin
+kotlin {
+    targets.withType<org.jetbrains.kotlin.gradle.plugin.mpp.KotlinNativeTarget> {
+        binaries.all {
+            freeCompilerArgs += "-Xadd-light-debug={enable|disable}"
+        }
+    }
+}
+```
+
+(in Kotlin DSL).
+
+In projects created from IntelliJ IDEA or AppCode templates these `.dSYM` bundles
+are then discovered by Xcode automatically.
+
+## Make frameworks static when using rebuild from bitcode
+
+Rebuilding Kotlin-produced framework from bitcode invalidates the original `.dSYM`.
+If it is performed locally, make sure the updated `.dSYM` is used when symbolicating
+crash reports.
+
+If rebuilding is performed on App Store side, then `.dSYM` of rebuilt *dynamic* framework
+seems discarded and not downloadable from App Store Connect.
+So in this case it may be required to make the framework static, e.g. with
+
+```kotlin
+kotlin {
+    targets.withType<org.jetbrains.kotlin.gradle.plugin.mpp.KotlinNativeTarget> {
+        binaries.withType<org.jetbrains.kotlin.gradle.plugin.mpp.Framework> {
+            isStatic = true
+        }
+    }
+}
+```
+
+(in Kotlin DSL).
+
+## Decode inlined stack frames
+
+Xcode doesn't seem to properly decode stack trace elements of inlined function
+calls (these aren't only Kotlin `inline` functions but also functions that are
+inlined when optimizing machine code). So some stack trace elements may be
+missing. If this is the case, consider using `lldb` to process crash report
+that is already symbolicated by Xcode, for example:
+
+```bash
+$ lldb -b -o "script import lldb.macosx" -o "crashlog file.crash"
+```
+
+This command should output crash report that is additionally processed and
+includes inlined stack trace elements.
+
+More details can be found in [LLDB documentation](https://lldb.llvm.org/use/symbolication.html).