Documentation for Kotlin/Native support

Author: elizarov

README.md

@@ -4,9 +4,7 @@
 [![GitHub license](https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg?style=flat)](http://www.apache.org/licenses/LICENSE-2.0)
 [![Download](https://api.bintray.com/packages/kotlin/kotlinx/kotlinx.coroutines/images/download.svg?version=0.23.4) ](https://bintray.com/kotlin/kotlinx/kotlinx.coroutines/0.23.4)
 
-Library support for Kotlin coroutines in
-[Kotlin/JVM](core/README.md) and
-[Kotlin/JS](js/README.md).
+Library support for Kotlin coroutines with [multiplatform](#multiplatform) support.
 This is a companion version for Kotlin 1.2.51 release.
 
 ```kotlin
@@ -22,12 +20,13 @@ launch {
   * `launch` and `async` coroutine builders;
   * `Job` and `Deferred` light-weight future with cancellation support;
   * `delay` and `yield` top-level suspending functions.
-* [js](js/README.md) — Kotlin/JS implementation of common coroutines with `Promise` support.
 * [core](core/README.md) — Kotlin/JVM implementation of common coroutines with additional features:
   * `CommonPool` coroutine context (default on JVM);
   * `Channel` and `Mutex` communication and synchronization primitives;
   * `produce` and `actor` coroutine builders;
   * `select` expression support and more.
+* [js](js/README.md) — Kotlin/JS implementation of common coroutines with `Promise` support.
+* [native](native/README.md) — Kotlin/Native implementation of common coroutines with `runBlocking` single-threaded event loop.
 * [reactive](reactive/README.md) — modules that provide builders and iteration support for various reactive streams libraries:
   * Reactive Streams, RxJava 1.x and 2.x and Project Reactor. 
 * [ui](ui/README.md) — modules that provide coroutine dispatchers for various single-threaded UI libraries:
@@ -100,10 +99,13 @@ repository {
 }
 ```
 
-### Kotlin/JS
+### Multiplatform
 
-Use `org.jetbrains.kotlinx:kotlinx-coroutines-core-js:<version>` artifact in your Gradle/Maven dependencies 
-or install [`kotlinx-coroutines-core`](https://www.npmjs.com/package/kotlinx-coroutines-core) package via NPM. 
+Core modules of `kotlinx.coroutines` are also available for 
+[Kotlin/JS](js/README.md) and [Kotlin/Native](native/README.md). If you write
+a common code that should get compiled or different platforms, add 
+[`org.jetbrains.kotlinx:kotlinx-coroutines-core-common:<version>`](common/kotlinx-coroutines-core-common/README.md) 
+to your common code dependencies.
 
 ### Android
 

common/kotlinx-coroutines-core-common/README.md

@@ -6,3 +6,4 @@ Common primitives to work with coroutines in
 Documentation is provided in platform-specific modules:
 * [kotlinx-coroutines-core](../../core/kotlinx-coroutines-core/README.md) for Kotlin/JVM.
 * [kotlinx-coroutines-core-js](../../js/kotlinx-coroutines-core-js/README.md) for Kotlin/JS.
+* [kotlinx-coroutines-core-native](../../native/kotlinx-coroutines-core-native/README.md) for Kotlin/Native.

gradle/dokka.gradle

@@ -42,7 +42,7 @@ if (platform == "jvm") {
             makeLinkMapping(it, rootProject.file("js/$project.name-js"))
             makeLinkMapping(it, rootProject.file("common/$project.name-common"))
             // source roots
-            impliedPlatforms = ['JVM', 'JS']
+            impliedPlatforms = ['JVM', 'JS', 'Native']
             sourceRoot {
                 path = rootProject.file("core/$project.name/src")
                 platforms = ['JVM']
@@ -51,10 +51,14 @@ if (platform == "jvm") {
                 path = rootProject.file("js/$project.name-js/src")
                 platforms = ['JS']
             }
+            sourceRoot {
+                path = rootProject.file("native/$project.name-native/src")
+                platforms = ['Native']
+            }
             sourceRoot {
                 path = rootProject.file("common/$project.name-common/src")
             }
-            // depends on JS & Common, too
+            // depends on other platforms, too
             afterEvaluate {
                 dependsOn(tasks.getByPath(":$project.name:classes"))
                 dependsOn(tasks.getByPath(":$project.name-js:classes"))

js/README.md

@@ -1,11 +1,16 @@
 # Coroutines core for Kotlin/JS
 
 This directory contains modules that provide core coroutines support on Kotlin/JS.
-Module name below corresponds to the artifact name in Maven/Gradle.
 
-## Modules
+## Using in your projects
 
-* [kotlinx-coroutines-core-js](kotlinx-coroutines-core-js/README.md) -- core coroutine builders and primitives.
+Use [`org.jetbrains.kotlinx:kotlinx-coroutines-core-js:<version>`](kotlinx-coroutines-core-js/README.md)
+module in your Gradle/Maven dependencies 
+or install [`kotlinx-coroutines-core`](https://www.npmjs.com/package/kotlinx-coroutines-core) package via NPM.
+
+Since Kotlin/JS does not generally provide binary compatibility between versions, 
+you should use the same version of Kotlin compiler as was used to build `kotlinx.coroutines`. 
+See [gradle.properties](../gradle.properties). 
 
 ## Examples
 

js/kotlinx-coroutines-core-js/README.md

@@ -59,10 +59,6 @@ helper function. [NonCancellable] job object is provided to suppress cancellatio
 | [Mutex][kotlinx.coroutines.experimental.sync.Mutex]          | [lock][kotlinx.coroutines.experimental.sync.Mutex.lock]                            | [onLock][kotlinx.coroutines.experimental.sync.Mutex.onLock]                   | [tryLock][kotlinx.coroutines.experimental.sync.Mutex.tryLock]
 | none            | [delay]                                        | [onTimeout][kotlinx.coroutines.experimental.selects.SelectBuilder.onTimeout]                   | none
 
-# Package kotlinx.coroutines.experimental
-
-General-purpose coroutine builders, contexts, and helper functions.
-
 <!--- MODULE kotlinx-coroutines-core -->
 <!--- INDEX kotlinx.coroutines.experimental -->
 [launch]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/launch.html

knit/resources/knit.properties

@@ -4,6 +4,6 @@
 
 site.root=https://kotlin.github.io/kotlinx.coroutines
 
-module.roots=common js core integration reactive ui
+module.roots=common js core integration native reactive ui
 module.marker=build.gradle
 module.docs=build/dokka

native/README.md

@@ -0,0 +1,62 @@
+# Coroutines core for Kotlin/Native
+
+This directory contains modules that provide core coroutines support on Kotlin/Native.
+
+## Using in your projects
+
+Use [`org.jetbrains.kotlinx:kotlinx-coroutines-core-native:<version>`](kotlinx-coroutines-core-native/README.md)
+module in your Gradle/Maven dependencies. 
+Only single-threaded code (JS-style) is currently supported. 
+
+Kotlin/Native supports only Gradle version 4.7 or later 
+and you should use `kotlin-platform-native` plugin.
+
+First of all, you'll need to enable Gradle metadata in your
+`settings.gradle` file:
+
+```groovy
+enableFeaturePreview('GRADLE_METADATA')
+```
+
+Then, you'll need to apply the corresponding plugin and add appropriate dependencies in your
+`build.gradle` file:
+
+```groovy
+buildscript {
+    repositories {
+        jcenter()
+        maven { url 'https://plugins.gradle.org/m2/' }
+        maven { url 'https://dl.bintray.com/jetbrains/kotlin-native-dependencies' }
+    }
+
+    dependencies {
+        classpath "org.jetbrains.kotlin:kotlin-native-gradle-plugin:$kotlin_native_version"
+    }
+
+}
+
+apply plugin: 'kotlin-platform-native'
+
+repositories {
+    jcenter()
+}
+
+dependencies {
+    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core-native:0.23.4'
+}
+
+sourceSets {
+    main {
+        component {
+            target "ios_arm64", "ios_arm32", "ios_x64", "macos_x64", "linux_x64", "mingw_x64" 
+            outputKinds = [EXECUTABLE]
+        }
+    }
+}
+```
+
+Since Kotlin/Native does not generally provide binary compatibility between versions, 
+you should use the same version of Kotlin/Native compiler as was used to build `kotlinx.coroutines`. 
+Add an appropriate `kotlin_native_version` to your `gradle.properties` file. 
+See [gradle.properties](../gradle.properties). 
+