From 9d7e2495595543550a6c2db97791810c728a1bf6 Mon Sep 17 00:00:00 2001
From: Alexander Gorshenev <alexander.gorshenev@jetbrains.com>
Date: Tue, 20 Jun 2017 22:06:23 +0300
Subject: [PATCH] Added an examplar workflow to LIBRARIES.md.

---
 LIBRARIES.md | 159 ++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 113 insertions(+), 46 deletions(-)

diff --git a/LIBRARIES.md b/LIBRARIES.md
index 4ad4d3d29d4..66e40407d7e 100644
--- a/LIBRARIES.md
+++ b/LIBRARIES.md
@@ -1,6 +1,116 @@
- ## Kotlin/Native library format
+ # Kotlin/Native libraries
 
-**WARNING**: the format is *very* preliminary. It is subject to change right under your fingers.
+  ## Kotlin compiler specifics
+
+To produce a library with Kotlin/Native compiler use `-produce library` or `-p library` flag. For example:
+
+    $ kotlic foo.kt -p library -o bar
+
+the above command will produce a `bar.klib` with compiled contents of `foo.kt`.
+
+To link a library use `-library <name>` or `-l <name>` flag. For example:
+
+    $ kotlinc qux.kt -l bar
+
+the above command will produce `program.kexe` out of `qux.kt` and `bar.klib`
+
+
+  ## 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
+
+    $ cinterop -def  ./samples/csvparser/src/main/c_interop/stdio.def  -o stdio
+
+we obtain `stdio.klib`. 
+
+
+  ## klib utility
+
+The **klib** library management utility allows one to inspect and install the libraries.
+
+The following commands are available.
+
+To list library contents:
+
+        $ klib contents <name>
+
+To inspect the bookkeeping details of the library 
+
+        $ klib info <name>
+
+To install the library to the default location use
+
+        $ klib install <name>
+
+To remove the library from the default repository use 
+
+        $ klib remove <name>
+
+All of the above commands accept an additional `-repository <directory>` argument to specify a repository other than the default one. 
+
+        $ klib <command> <name> -repository <directory>
+
+
+  ## Several examples
+
+First lets create a library:
+
+    $ cinterop -h /usr/include/math.h -pkg libc.math -o math
+
+The library has been created in the current directory:
+
+    $ ls math.klib
+    math.klib
+
+Now let's check out the contents of the library:
+
+    $ klib contents math
+
+We can install `math` to the default repository:
+
+    $ klib install math
+
+Remove any traces of it and its build process from the current directory:
+
+    $ rm -rf ./math*
+
+Create a very short program and place it into a `sin.kt` :
+
+    import libc.math.*
+    fun main(args: Array<String>) {
+        println(sin(2.0))
+    }
+
+Now compile the program linking with the library we have just created:
+
+    $ kotlinc sin.kt -l math -o mysin
+
+And run your program:
+
+    $ ./mysin.kexe
+    0.9092974268256817
+
+Have fun!
+
+  # Advanced topics
+
+ ## Library search sequence
+
+When given `-library foo` flag, the compiler searches the `foo`  library in the following order:
+
+    * Current compilation directory or an absolute path.
+
+    * All repositories specified with `-repo` flag.
+
+    * Libraries installed in the default repository (For now the default is  `~/.konan` ).
+
+    * Libraries installed in `$installation/klib` directory.
+
+
+ ## 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.
 
 Kotlin/Native libraries are zip files containing predefined 
 directory structure, with the following layout:
@@ -22,48 +132,5 @@ directory structure, with the following layout:
       - 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** directory of your installation.
-
- ## Library search sequence
-
-When given **-library foo** flag, the compiler searches the libraries in the following order:
-
-    * Current compilation directory or an absolute path.
-
-    * All repositories specified with *-repo* flag.
-
-    * Libraries installed in .konan directory.
-
-    * Libraries installed in $installation/klib directory.
-
-  ## **cinterop* tool specifics
-
-The **cinterop** tool produces **klib** wrappers for native libraries. 
-
-
-  ## **klib** utility
-
-The **klib** library management utility allows one to inspect and install the libraries.
-
-The following commands are available.
-
-To list library contents:
-
-        $ klib contents foo
-
-To ask the details of the library 
-
-        $ klib info foo
-
-To install the library to the default location use
-
-        $ klib install foo
-
-To install the library to another location run
-
-        $ klib install foo -repository <directory>
-
-To remove the library from the repository use
-
-        $ klib remove foo [-repository <directory>]
+    An exemplar layout can be found in `klib/stdlib` directory of your installation.