Provide killswitch for JPMS & improve building.md (#2105)

Add idea.active to disableJPMS check to avoid red code in IDE.

Also add stdlib-jdk8 to Hocon dependencies explicitly for java.time.Duration.toKotlinDuration()
(not sure why it was available without this dep though)

Author: sandwwraith

README.md

@@ -35,6 +35,8 @@ Kotlin serialization consists of a compiler plugin, that generates visitor code
 * **Additional links**
   * [Kotlin Serialization Guide](docs/serialization-guide.md)
   * [Full API reference](https://kotlinlang.org/api/kotlinx.serialization/)
+  * [Submitting issues and PRs](CONTRIBUTING.md)
+  * [Building this library](docs/building.md)
 
 ## Introduction and references
 

buildSrc/src/main/kotlin/Java9Modularity.kt

@@ -19,6 +19,9 @@ object Java9Modularity {
     @JvmStatic
     @JvmOverloads
     fun Project.configureJava9ModuleInfo(multiRelease: Boolean = true) {
+        val disableJPMS = this.rootProject.extra.has("disableJPMS")
+        val ideaActive = System.getProperty("idea.active") == "true"
+        if (disableJPMS || ideaActive) return
         val kotlin = extensions.findByType<KotlinProjectExtension>() ?: return
         val jvmTargets = kotlin.targets.filter { it is KotlinJvmTarget || it is KotlinWithJavaTarget<*> }
         if (jvmTargets.isEmpty()) {

docs/building.md

@@ -2,15 +2,22 @@
 
 ## JDK version
 
-To build Kotlin Serialization JDK version 9 or higher is required.
+To build Kotlin Serialization JDK version 11 or higher is required. Make sure this is your default JDK (`JAVA_HOME` is set accordingly).
 This is needed to compile the `module-info` file included for JPMS support.
 
+In case you are determined to use different JDK version, or experience problems with JPMS you can turn off compilation of modules
+completely with `disableJPMS` property: add `disableJPMS=true` to gradle.properties or `-PdisableJPMS` to Gradle CLI invocation.
+
 ## Runtime library
 
 Kotlin Serialization runtime library itself is a [multiplatform](http://kotlinlang.org/docs/reference/multiplatform.html) project.
-To build library from the source and run all tests, use `./gradlew build`. Corresponding platform tasks like `jvmTest`, `jsTest` and so on are also available.
+To build library from the source and run all tests, use `./gradlew build`. Corresponding platform tasks like `jvmTest`, `jsIrTest`, `nativeTest` and so on are also available.
+
+Project can be opened in in Intellij IDEA without additional prerequisites.
+In case you want to work with Protobuf tests, you may need to run `./gradlew generateTestProto` beforehand.
+
 
-To install it into the local Maven repository, run `./gradlew publishToMavenLocal`. 
+To install runtime library into the local Maven repository, run `./gradlew publishToMavenLocal`. 
 After that, you can include this library in arbitrary projects like usual gradle dependency:
 
 ```gradle
@@ -23,17 +30,19 @@ dependencies {
 }
 ```
 
-To open project in Intellij IDEA, first run `./gradlew generateTestProto` from console.
-Make sure you've set an option 'Use Gradle wrapper' on import to use a correct version of Gradle.
-You may also need to mark `runtime/build/generated/source/proto/test/java` as 'Generated source root' to build project/run tests in IDE without delegating a build to Gradle.
-This requires Kotlin 1.3.11 and higher.
+Note that by default, only one Native target is built (the one that is the current host, e.g. `macosX64` on Intel Mac machines, `linuxX64` on linux machines, etc).
+To compile and publish all Native artifacts, not only the host one, use Gradle property `native.deploy=true`.
 
-To use snapshot version of compiler (if you have built it from sources), use flag `-Pbootstrap`. To compile and publish all Native artifacts, not only the host one, use `-Pnative.deploy=true`.
+To use snapshot version of compiler (if you have built and install it from sources), use flag `-Pbootstrap`.
+If you have built both Kotlin and Kotlin/Native compilers, set `KONAN_LOCAL_DIST` environment property to the path with Kotlin/Native distribution
+(usually `kotlin-native/dist` folder inside Kotlin project).
 
-`master` branch of library should be binary compatible with latest released compiler plugin. In case you want to test some new features from other branches, which are still in development and may not be compatible in terms of bytecode produced by plugin, you'll need to build the plugin by yourself.
+`master` and `dev` branches of library should be binary compatible with latest released compiler plugin. In case you want to test some new features from other branches,
+which are still in development and may not be compatible in terms of bytecode produced by plugin, you'll need to build the plugin by yourself.
 
 ## Compiler plugin
 
 Compiler plugin for Gradle/Maven and IntelliJ plugin, starting from Kotlin 1.3, are embedded into the Kotlin compiler. 
 
-Sources and steps to build it are located [here](https://github.com/JetBrains/kotlin/blob/master/plugins/kotlin-serialization/kotlin-serialization-compiler/). In general, you'll just need to run `./gradlew dist install` to get `1.x.255` versions of Kotlin compiler, stdlib and serialization plugins in the Maven local repository.
+Sources and steps to build it are located [here](https://github.com/JetBrains/kotlin/tree/master/plugins/kotlinx-serialization).
+In short, you'll just need to run `./gradlew dist install` to get `1.x.255-SNAPSHOT` versions of Kotlin compiler, stdlib and serialization plugins in the Maven local repository.

formats/hocon/build.gradle

@@ -21,6 +21,7 @@ java {
 dependencies {
     api project(':kotlinx-serialization-core')
     api 'org.jetbrains.kotlin:kotlin-stdlib'
+    api 'org.jetbrains.kotlin:kotlin-stdlib-jdk8'
 
     api 'com.typesafe:config:1.4.1'