update documentation to include it to kotlinlang.org (#2015)

2018-09-06 19:22:29 +03:00
parent 710c691aa8
commit 7ee04b3108
11 changed files with 122 additions and 21 deletions
@@ -1,3 +1,9 @@
+---
+type: doc
+layout: reference
+title: "Concurrency in Kotlin/Native"
+---
+
 ### Concurrency in Kotlin/Native

  Kotlin/Native runtime doesn't encourage a classical thread-oriented concurrency
@@ -12,7 +18,7 @@
   * Raw shared memory using C globals
   * Coroutines for blocking operations (not covered in this document)

- ## Workers
+## Workers

  Instead of threads Kotlin/Native runtime offers concept of workers: concurrently executing
 control flow streams with an associated request queue. Workers are very similar to actors
@@ -55,7 +61,7 @@
 in the Kotlin/Native repository.


- ## <a name="transfer"></a>Object transfer and freezing
+## <a name="transfer"></a>Object transfer and freezing

   Important invariant that Kotlin/Native runtime maintains is that object is either owned by a single
  thread/worker, or is immutable (_shared XOR mutable_). This ensures that the same data has a single mutator, and so no need for
@@ -76,7 +82,7 @@
 is allowed. Currently, Kotlin/Native runtime only freezes enum objects after creation, although additional
 autofreezing of certain provably immutable objects could be implemented in the future.

-  ## <a name="detach"></a>Object subgraph detachment
+## <a name="detach"></a>Object subgraph detachment

   Object subgraph without external references could be disconnected using `detachObjectGraph` to
  a `COpaquePointer` value, which could be stored in `void*` data, so disconnected object subgraphs
@@ -84,7 +90,7 @@
  or worker. Combined with [raw memory sharing](#shared) it allows side channel object transfer between
  concurrent threads, if worker mechanisms are insufficient for the particular task.

- ## <a name="shared"></a>Raw shared memory
+## <a name="shared"></a>Raw shared memory

  Considering strong ties of Kotlin/Native with C via interoperability, in conjunction with other mechanisms
 mentioned above one could build popular data structures, like concurrent hashmap or shared cache with
@@ -112,7 +118,7 @@ class SharedData(rawPtr: NativePtr) : CStructVar(rawPtr) {
 So combined with the top level variable declared above, it allows seeing the same memory from different
 threads and building traditional concurrent structures with platform-specific synchronization primitives.

- ## <a name="top_level"></a>Global variables and singletons
+## <a name="top_level"></a>Global variables and singletons

  Frequently, global variables are a source of unintended concurrency issues, so _Kotlin/Native_ implements
 following mechanisms to prevent unintended sharing of state via global objects:
@@ -1,3 +1,9 @@
+---
+type: doc
+layout: reference
+title: "Debugging"
+---
+
 ## Debugging

 Currently Kotlin native compiler produces debug info compatible with DWARF 2 specification, so modern debugger tools could
@@ -1,3 +1,8 @@
+---
+type: doc
+layout: reference
+title: "FAQ"
+---
 ### Q: How do I run my program?

 A: Define top level function `fun main(args: Array<String>)`, please ensure it's not
@@ -1,3 +1,9 @@
+---
+type: doc
+layout: reference
+title: "Kotlin/Native Gradle plugin"
+---
+
 # Kotlin/Native Gradle plugin

 _Note: For the experimental DSL see the [corresponding section](#experimental-plugin)_.
@@ -1,3 +1,9 @@
+---
+type: doc
+layout: reference
+title: "Immutability in Kotlin/Native"
+---
+
 # Immutability in Kotlin/Native

 Kotlin/Native implements strict mutability checks, ensuring
@@ -1,3 +1,9 @@
+---
+type: doc
+layout: reference
+title: "Kotlin/Native interoperability"
+---
+
 # _Kotlin/Native_ interoperability #

 ## Introduction ##
@@ -1,6 +1,12 @@
- # Kotlin/Native libraries
+---
+type: doc
+layout: reference
+title: "Kotlin/Native libraries"
+---

-  ## Kotlin compiler specifics
+# Kotlin/Native libraries
+
+## Kotlin compiler specifics

 To produce a library with Kotlin/Native compiler use `-produce library` or `-p library` flag. For example:

@@ -15,7 +21,7 @@ To link a library use `-library <name>` or `-l <name>` flag. For example:
 the above command will produce `program.kexe` out of `qux.kt` and `bar.klib`


-  ## cinterop tool specifics
+## cinterop tool specifics

 The **cinterop** tool produces `.klib` wrappers for native libraries as its main output. 
 For example using the simple `stdio.def` native library definition file provided in your Kotlin/Native distribution
@@ -25,7 +31,7 @@ For example using the simple `stdio.def` native library definition file provided
 we obtain `stdio.klib`. 


-  ## klib utility
+## klib utility

 The **klib** library management utility allows one to inspect and install the libraries.

@@ -52,7 +58,7 @@ All of the above commands accept an additional `-repository <directory>` argumen
        $ klib <command> <name> -repository <directory>


-  ## Several examples
+## Several examples

 First lets create a library:

@@ -93,9 +99,9 @@ And run your program:

 Have fun!

-  # Advanced topics
+# Advanced topics

- ## Library search sequence
+## Library search sequence

 When given `-library foo` flag, the compiler searches the `foo`  library in the following order:

@@ -108,7 +114,7 @@ When given `-library foo` flag, the compiler searches the `foo`  library in the
    * Libraries installed in `$installation/klib` directory.


- ## The library format
+## The library format

 **WARNING**: the library format is *very* preliminary. It is subject to change right under your fingers. And it can incompatibly change from release to release until Kotlin/Native is stabilized.

@@ -117,6 +123,7 @@ directory structure, with the following layout:

 **foo.klib** when unpacked as **foo/** gives us:

+```
  - foo/
    - targets/
      - $platform/
@@ -131,6 +138,7 @@ directory structure, with the following layout:
    - resources/
      - General resources such as images. (Not used yet).
    - manifest - A file in *java property* format describing the library.
+```

-    An exemplar layout can be found in `klib/stdlib` directory of your installation.
+An exemplar layout can be found in `klib/stdlib` directory of your installation.

@@ -1,3 +1,9 @@
+---
+type: doc
+layout: reference
+title: "Kotlin/Native in multiplatform projects"
+---
+
 # Kotlin/Native in multiplatform projects

 While Kotlin/Native could be used as the only Kotlin compiler in the project, it is pretty common to combine
@@ -1,3 +1,9 @@
+---
+type: doc
+layout: reference
+title: "Kotlin/Native interoperability with Swift/Objective-C"
+---
+
 # _Kotlin/Native_ interoperability with Swift/Objective-C

 This documents covers some details of Kotlin/Native interoperability with
@@ -1,12 +1,18 @@
- # Platform libraries
+---
+type: doc
+layout: reference
+title: "Platform libraries"
+---

-  ## Overview
+# Platform libraries
+
+## Overview

 To provide access to user's native operating system services,
 `Kotlin/Native` distribution includes a set of prebuilt libraries specific to
 each target. We call them **Platform Libraries**.

-  ### POSIX bindings
+### POSIX bindings

 For all `Unix` or `Windows` based targets (including `Android` and
 `iPhone`) we provide the `posix` platform lib. It contains bindings
@@ -22,7 +28,7 @@ Note that the content of `platform.posix` is NOT identical on
 different platforms, in the same way as different `POSIX` implementations
 are a little different.

-  ### OS specific libraries
+### OS specific libraries

 We've gone a little further and provided access to more specific
 native OS services. One needs to import the proper packages
@@ -38,7 +44,7 @@ on each of the platform. Choose what matches your target platform:

    import platform.ios.*

-  ### Popular native libraries
+### Popular native libraries

 There are many more platform libraries available for host and
 cross-compilation targets.  `Kotlin/Native` distribution provides access to
@@ -49,7 +55,7 @@ On Apple platforms `objc` library is provided for interoperability with [Objecti

 Inspect the contents of `dist/klib/platform/$target` of the distribution for the details.

-  ## Availability by default
+## Availability by default

 The packages from platform libraries are available by default. No
 special link flags need to be specified to use them. `Kotlin/Native`
@@ -61,7 +67,7 @@ just wrappers and bindings to the native libraries.  That means the
 native libraries themselves (`.so`, `.a`, `.dylib`, `.dll` etc)
 should be installed on the machine.

-  ## Examples
+## Examples

 `Kotlin/Native` installation provides a wide spectrum of examples
 demonstrating the use of platform libraries. 
@@ -0,0 +1,40 @@
+- md: CONCURRENCY.md
+  url: concurrency.html
+  title: "Concurrency"
+
+- md: IMMUTABILITY.md
+  url: immutability.html
+  title: "Immutability"
+
+- md: LIBRARIES.md
+  url: libraries.html
+  title: "Kotlin Libraries"
+
+- md: PLATFORM_LIBS.md
+  url: platform_libs.html
+  title: "Platform Libraries"
+
+- md: MULTIPLATFORM.md
+  url: multiplatform.html
+  title: "Multiplatform Projects"
+
+- md: INTEROP.md
+  url: c_interop.html
+  title: "C Interop"
+
+- md: OBJC_INTEROP.md
+  url: objc_interop.html
+  title: "Objective-C and Swift Interop"
+
+- md: GRADLE_PLUGIN.md
+  url: gradle_plugin.html
+  title: "Gradle Plugin"
+
+- md: DEBUGGING.md
+  url: debugging.html
+  title: "Debugging"
+
+- md: FAQ.md
+  url: faq.html
+  title: "FAQ"
+