From 61702a64c05951325500aee2fc67f0e4315aead6 Mon Sep 17 00:00:00 2001 From: Ilya Matveev Date: Fri, 25 Oct 2019 16:05:35 +0300 Subject: [PATCH] Improve Gradle DSL in docs (#3481) --- FAQ.md | 79 +++++++++++++++++++++++++++++++++++-------------- OBJC_INTEROP.md | 31 ++++++++++++++++--- 2 files changed, 84 insertions(+), 26 deletions(-) diff --git a/FAQ.md b/FAQ.md index c25c679095a..37a45224f8a 100644 --- a/FAQ.md +++ b/FAQ.md @@ -16,13 +16,19 @@ garbage. ### Q: How do I create a shared library? A: Use the `-produce dynamic` compiler switch, or `binaries.sharedLib()` in Gradle, i.e. -```groovy -targets { - fromPreset(presets.iosArm64, 'mylib') { + +
+ +```kotlin +kotlin { + iosArm64("mylib") { binaries.sharedLib() } } ``` + +
+ It will produce a platform-specific shared object (.so on Linux, .dylib on macOS, and .dll on Windows targets) and a C language header, allowing the use of all public APIs available in your Kotlin/Native program from C/C++ code. See `samples/python_extension` for an example of using such a shared object to provide a bridge between Python and @@ -32,13 +38,19 @@ Kotlin/Native. ### Q: How do I create a static library or an object file? A: Use the `-produce static` compiler switch, or `binaries.staticLib()` in Gradle, i.e. -```groovy -targets { - fromPreset(presets.iosArm64, 'mylib') { + +
+ +```kotlin +kotlin { + iosArm64("mylib") { binaries.staticLib() } } ``` + +
+ It will produce a platform-specific static object (.a library format) and a C language header, allowing you to use all the public APIs available in your Kotlin/Native program from C/C++ code. @@ -54,26 +66,47 @@ or set it via the `JAVA_OPTS` environment variable. A: Use the `-module-name` compiler option or matching Gradle DSL statement, i.e. -
+
+
-```groovy -targets { - fromPreset(presets.iosArm64, 'myapp') { - binaries.framework() - compilations.main.extraOpts '-module-name', 'TheName' +```kotlin +kotlin { + iosArm64("myapp") { + binaries.framework { + freeCompilerArgs += listOf("-module-name", "TheName") + } } } ``` +
+
+ +
+
+ +```groovy +kotlin { + iosArm64("myapp") { + binaries.framework { + freeCompilerArgs += ["-module-name", "TheName"] + } + } +} +``` + +
### Q: How do I rename the iOS framework? (default name is _\_.framework) A: Use the `baseName` option. This will also set the module name. -```groovy -targets { - fromPreset(presets.iosArm64, 'myapp') { +
+ +```kotlin +kotlin { + iosArm64("myapp") { binaries { framework { baseName = "TheName" @@ -83,6 +116,8 @@ targets { } ``` +
+ ### Q: How do I enable bitcode for my Kotlin framework? A: By default gradle plugin adds it on iOS target. @@ -92,27 +127,27 @@ A: By default gradle plugin adds it on iOS target. Or commandline arguments: `-Xembed-bitcode` (for release) and `-Xembed-bitcode-marker` (debug) Setting this in a Gradle DSL: -
+
-```groovy -targets { - fromPreset(presets.iosArm64, 'myapp') { +```kotlin +kotlin { + iosArm64("myapp") { binaries { framework { // Use "marker" to embed the bitcode marker (for debug builds). // Use "disable" to disable embedding. - embedBitcode "bitcode" // for release binaries. + embedBitcode("bitcode") // for release binaries. } } } } ``` +
+ These options have nearly the same effect as clang's `-fembed-bitcode`/`-fembed-bitcode-marker` and swiftc's `-embed-bitcode`/`-embed-bitcode-marker`. -
- ### Q: Why do I see `InvalidMutabilityException`? A: It likely happens, because you are trying to mutate a frozen object. An object can transfer to the diff --git a/OBJC_INTEROP.md b/OBJC_INTEROP.md index e824da01245..46ec9871f58 100644 --- a/OBJC_INTEROP.md +++ b/OBJC_INTEROP.md @@ -237,13 +237,16 @@ but the features supported retain meaningful information. Generics are currently not enabled by default. To have the framework header written with generics, add an experimental flag to the compiler config: -``` -compilations.main { - outputKinds("framework") - extraOpts "-Xobjc-generics" +
+ +```kotlin +binaries.framework { + freeCompilerArgs += "-Xobjc-generics" } ``` +
+ #### Limitations Objective-C generics do not support all features of either Kotlin or Swift, so there will be some information lost @@ -256,31 +259,43 @@ Generics can only be defined on classes, not on interfaces (protocols in Objc an Kotlin and Swift both define nullability as part of the type specification, while Objc defines nullability on methods and properties of a type. As such, the following: +
+ ```kotlin class Sample(){ fun myVal():T } ``` +
+ will (logically) look like this: +
+ ```swift class Sample(){ fun myVal():T? } ``` +
+ In order to support a potentially nullable type, the Objc header needs to define `myVal` with a nullable return value. To mitigate this, when defining your generic classes, if the generic type should *never* be null, provide a non-null type constraint: +
+ ```kotlin class Sample(){ fun myVal():T } ``` +
+ That will force the Objc header to mark `myVal` as non-null. #### Variance @@ -288,16 +303,24 @@ That will force the Objc header to mark `myVal` as non-null. Objective-C allows generics to be declared covariant or contravariant. Swift has no support for variance. Generic classes coming from Objective-C can be force-cast as needed. +
+ ```kotlin data class SomeData(val num:Int = 42):BaseData() class GenVarOut(val arg:T) ``` +
+ +
+ ```swift let variOut = GenVarOut(arg: sd) let variOutAny : GenVarOut = variOut as! GenVarOut ``` +
+ #### Constraints In Kotlin you can provide upper bounds for a generic type. Objective-C also supports this, but that support is unavailable