Update build instructions in ReadMe to include gradle build step.

Also update links and overall readme structure.

libraries/ReadMe.md

@@ -1,10 +1,14 @@
 ## Kotlin Libraries
 
-This area of the project is all written in Kotlin and assumes you've got the [Kotlin IDEA plugin installed](http://confluence.jetbrains.net/display/Kotlin/Getting+Started).
+This area of the project is all written in Kotlin and assumes you've got the [Kotlin IDEA plugin installed](../ReadMe.md#installing-plugin).
 
-This area of the project uses Maven for its build. You need to install a recent [Maven](http://maven.apache.org/) distribution and
-setup environment variables as following:
+This area of the project uses Gradle and Maven for its build. When you open this project directory in IDEA the first time, it suggests you to import both gradle and maven projects. After importing you'll be able to explore and run gradle tasks and maven goals directly from IDEA with the instruments on the right sidebar.
 
+### Building
+
+You need to install a recent [Maven](http://maven.apache.org/) distribution and setup environment variables as following:
+
+    JAVA_HOME="path to JDK 1.8"
     JDK_16="path to JDK 1.6"
     JDK_17="path to JDK 1.7"
     JDK_18="path to JDK 1.8"
@@ -13,15 +17,21 @@ The main part of the Kotlin standard library, `kotlin-stdlib`, is compiled again
 for the standard library, `kotlin-stdlib-jre7` and `kotlin-stdlib-jre8`, which are compiled against JDK 1.7 and 1.8 respectively,
 so you need to have all these JDKs installed.
 
-Then you'll be able to build tools and libraries with:
+Be sure to build Kotlin compiler distribution before launching Gradle and Maven: see [root ReadMe.md, section "Building"](../ReadMe.md#installing-plugin).
+
+Core libraries are built with gradle, you can run that build using the gradle wrapper script even without local gradle installation:
+    
+    ./gradlew build install
+    
+> Note: on Windows type `gradlew` without the leading `./`
+    
+This command executes the `build` task, which assembles the artifacts and run the tests, and the `install` task, which puts the artifacts to the local maven repository to be used by the subsequent maven build.
+
+The rest of tools and libraries are built with maven:
 
     mvn install
 
-For more details see the [Getting Started Guide](http://confluence.jetbrains.net/display/Kotlin/Getting+Started).
-
-Be sure to build Kotlin compiler distribution before launching Maven: see ReadMe.md at root level, section "Building".
-
-If your maven build is failing with Out-Of-Memory errors, set JVM options for maven in MAVEN_OPTS environment variable like this:
+If your maven build is failing with Out-Of-Memory errors, set JVM options for maven in `MAVEN_OPTS` environment variable like this:
 
     MAVEN_OPTS="-Xmx2G"
 
@@ -32,7 +42,7 @@ Gradle plugin sources can be found at the [kotlin-gradle-plugin](tools/kotlin-gr
 To build only gradle plugin and necessary dependencies use the following command:
 ```bash
 mvn clean install -pl :kotlin-gradle-plugin -am
-# to skip all tests also add -DskipTests
+# to skip all tests also add -DskipTests -PnoTest
 ```
 
 ### Gradle integration tests
@@ -41,7 +51,7 @@ Gradle integration tests can be found at the [kotlin-gradle-plugin-integration-t
 
 These tests are slow, so they are *skipped by default*.
 
-To run integration tests use the 'run-gradle-integration-tests' profile:
+To run integration tests use the `run-gradle-integration-tests` profile:
 ```bash
 mvn clean install -pl :kotlin-gradle-plugin-integration-tests -am -Prun-gradle-integration-tests
 ```

libraries/stdlib/ReadMe.md

@@ -1,14 +1,17 @@
 ## The Kotlin Standard Library
 
-This module creates the [standard library for kotlin](http://jetbrains.github.com/kotlin/versions/snapshot/apidocs/index.html).
+This module creates the [standard library for kotlin](http://kotlinlang.org/api/latest/jvm/stdlib/index.html).
 
 ### Notes for contributors
 
-We use some code generation to apply the various collection-like methods to various different types like arrays, strings, kotlin.Iterable and java.lang.Iterable etc.
+We use some code generation to generate the various utility extension function for the various collection-like types like arrays, strings, `Collection<T>`, `Sequence<T>`, `Map<K, V>` etc.
 
-To run the code generator from a kotlin checkout
+These sources are placed into `generated` folder and their names are prefixed with the underscore, for example `generated/_Collections.kt`
 
-    cd libraries/tools/kotlin-stdlib-gen
-    mvn compile exec:java
+To run the code generator from the `libraries` directory of a kotlin checkout, use the following command:
 
-This then runs the [GenerateStandardLib.kt](https://github.com/JetBrains/kotlin/blob/master/libraries/tools/kotlin-stdlib-gen/src/generators/GenerateStandardLib.kt) script to create the source from the files for java.lang.Iterable<T> and java.util.Collection etc.
+    ./gradlew :tools:kotlin-stdlib-gen:run
+
+> Note: on Windows type `gradlew` without the leading `./`
+
+This then runs the script which generates a significant part of stdlib sources from the [templates](https://github.com/JetBrains/kotlin/tree/master/libraries/tools/kotlin-stdlib-gen/src/templates) authored with a special kotlin based DSL.

libraries/stdlib/js/ReadMe.md

@@ -1,5 +1,9 @@
 ## Kotlin Standard Library for JS
 
+This module produces a `kotlin-stdlib-js` jar which contains all the Kotlin source code for the runtime and standard kotlin library code (both definitions and implementation code) compiled to JavaScript.
+
 The tests of this module can be run and debugged inside any browser by opening the **web/index.html** file in this directory to run the test cases using [Qunit](http://qunitjs.com/).
 
-You should execute `:karmaDependencies` gradle task before running these tests to fetch the required Qunit dependency.
+You should execute `karmaDependencies` gradle task before running these tests to fetch the required Qunit dependency.
+
+These tests are also run during CI build with [gradle karma plugin](https://github.com/craigburke/karma-gradle) in PhantomJS browser.

libraries/tools/binary-compatibility-validator/ReadMe.md

@@ -6,11 +6,13 @@ and ensure that the public binary API wasn't changed in a way that make this cha
 ## How to run
 
 Compile and run tests. `CasesPublicAPITest` verifies the tool itself, 
-and `RuntimePublicAPITest` dumps the public API of `kotlin-runtime` and `kotlin-stdlib` jars, 
-which must be built beforehand with maven. 
+and `RuntimePublicAPITest` dumps the public API of `kotlin-stdlib`, 
+`kotlin-stdlib-jre7/8` and `kotlin-reflect` jars, 
+which must be built beforehand with gradle. Use `clean assemble` tasks,
+since the incremental compilation currently doesn't produce all the required output.
 
 When substantial changes are made to the public API, it may be convenient to overwrite 
-the entire dump and compare changes later before commiting: pass `-Doverwrite.output=true` 
+the entire dump and compare changes later before committing: pass `-Doverwrite.output=true` 
 property to the test to do so. 
 
 Also you can use shared run configuration "Binary compatibility tests", which also 

libraries/tools/kotlin-stdlib-gen/ReadMe.md

@@ -1,11 +1,12 @@
 ## Code Generation for Standard Library
 
 Some of the code in the standard library is created by code generation based on templates.
-For example, many Array methods need to be implemented separately for Array<T>, ByteArray, ShortArray, IntArray, etc.
+For example, many `Array` methods need to be implemented separately for `Array<T>`, `ByteArray`, `ShortArray`, `IntArray`, etc.
 
-To run the code generator from a kotlin checkout
+To run the code generator from the `libraries` directory of a kotlin checkout, use the following command:
 
-    cd libraries/tools/kotlin-stdlib-gen
-    mvn compile exec:java
+    ./gradlew :tools:kotlin-stdlib-gen:run
 
-This then runs the [GenerateStandardLib.kt](https://github.com/JetBrains/kotlin/blob/master/libraries/tools/kotlin-stdlib-gen/src/generators/GenerateStandardLib.kt) script to create the source from the files for java.lang.Iterable<T> and java.util.Collection etc.
+> Note: on Windows type `gradlew` without the leading `./`
+
+This then runs the script which generates a significant part of stdlib sources from the [templates](https://github.com/JetBrains/kotlin/tree/master/libraries/tools/kotlin-stdlib-gen/src/templates) authored with a special kotlin based DSL.