add kotlin-playground styles to GRADLE_PLUGIN.md (#2076)

GRADLE_PLUGIN.md

@@ -8,13 +8,22 @@ You may use the Gradle plugin to build _Kotlin/Native_ projects. Since version 0
 [available](https://plugins.gradle.org/plugin/org.jetbrains.kotlin.konan) at the Gradle plugin portal, so you can apply it
 using Gradle plugin DSL:
 
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 plugins {
     id "org.jetbrains.kotlin.konan" version "0.9"
 }
+```
+
+</div>
 
 __Note__: The 0.9 version of Kotlin/Native is based on Kotlin 1.3-M1 which is an EAP version and isn't available on
 the plugin portal. In this case you need to add a Kotlin EAP repository in your `settings.gradle`:
 
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 pluginManagement {
     repositories {
         gradlePluginPortal()
@@ -23,11 +32,17 @@ the plugin portal. In this case you need to add a Kotlin EAP repository in your
         }
     }
 }
+```
+
+</div>
 
 You also can get the plugin from a Bintray repository. In addition to releases, this repo contains old and development
 versions of the plugin which are not available at the plugin portal. To get the plugin from the Bintray repo, include
 the following snippet in your build script:
    
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 buildscript {
    repositories {
        mavenCentral()
@@ -45,6 +60,9 @@ the following snippet in your build script:
 }
 
 apply plugin: 'konan'
+```
+
+</div>
 
 The Kotlin/Native plugin depends on `org.jetbrains.kotlin:kotlin-gradle-plugin`. So if a build contains both these
 plugins as buildscript dependencies, it's recommended to **declare them in the same `build.gradle`** to avoid issues with
@@ -53,7 +71,13 @@ plugin classpath.
 By default the plugin downloads the Kotlin/Native compiler during the first run. If you have already downloaded the compiler
 manually you can specify the path to its root directory using `konan.home` project property (e.g. in `gradle.properties`).
 
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 konan.home=/home/user/kotlin-native-0.8
+```
+
+</div>
 
 In this case the compiler will not be downloaded by the plugin.
 
@@ -71,6 +95,10 @@ The Kotlin/Native Gradle plugin allows building artifacts of the following types
 All Kotlin/Native artifacts should be declared in the `konanArtifacts` block. Note that the `konanInterop` script block was removed in
 v0.3.4. Use the `interop` method of the `konanArtifact` block instead:
 
+
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 konanArtifacts {
     program('foo')  // executable 'foo'
     library('bar')  // library 'bar'
@@ -79,11 +107,17 @@ v0.3.4. Use the `interop` method of the `konanArtifact` block instead:
     dynamic('quux') // dynamic library
     framework ('quuux') // Objective-C framework
 }
+```
+
+</div>
 
 All artifacts except interop libraries are built by the Kotlin/Native compiler. Such an artifact may be configured using its script block.
 It is here that you can specify source directories, used libraries, and compilation flags (see [**Plugin DSL**](#plugin-dsl) section for details). The plugin
 uses `src/main/kotlin/` as a default source directory for all compiler artifacts:
 
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 konanArtifacts {
     // Build foo.klib
     library('foo') {
@@ -103,12 +137,18 @@ uses `src/main/kotlin/` as a default source directory for all compiler artifacts
         }
     }
 }
+```
+
+</div>
 
 Interop libraries are built using the `cinterop` tool. They also may have configuration blocks but the options available in these blocks
 differ from ones available for compiler artifacts. The input for such an artifact is a def-file describing a native API. By default the
 def-file path is `src/main/c_interop/<library-name>.def` but it may be changed using the `defFile` method of the configuration block of
 an interoperability library:
     
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 konanArtifacts {
     // Interoperability library stdio.klib
     // Use the default def-file path: src/main/c_interop/stdio.def
@@ -126,16 +166,28 @@ an interoperability library:
         }
     }
 }
+```
+
+</div>
 
 ## Building for different targets
 
 All the artifacts declared in a project may be built for different targets. By default they are built only for the `host` target i.e. a
 computer used for building. One may change the default target list using the `konan.targets` project extension:
 
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 konan.targets = [ 'linux', 'android_arm64', 'android_arm32' ]
+```
+
+</div>
 
 One may specify a custom target set for each particular artifact using the `targets` parameter of an artifact declaration:
 
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 konan.targets = [ 'linux', 'android_arm64' ]
 
 konanArtifacts {
@@ -150,11 +202,17 @@ One may specify a custom target set for each particular artifact using the `targ
     // these targets will be skipped and the artifact will be built only for iOS
     framework('baz', targets: [ 'linux', 'wasm32', 'iphone' ]) { /* ... */ }
 }
+```
+
+</div>
 
 
 The plugin creates tasks to compile each artifact for all the targets supported by the current host and declared in the `konan.targets` list.
 You can perform additional configuration for a target using the `target` method of an artifact configuration block:
 
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 konan.targets = [ 'linux', 'macbook', 'wasm32' ]
 
 konanArtifacts {
@@ -175,22 +233,37 @@ You can perform additional configuration for a target using the `target` method
         // Only common.kt will be compiled for wasm32
     }
 }
+```
+
+</div>
 
 One may access to a task for some target via artifact methods or properties:
 
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 // Both of them return a task building artifact 'foo' for MacOS
 konanArtifacts.foo.getByTarget("macbook")
 konanArtifacts.foo.macbook
+```
+
+</div>
 
 ## Using libraries
 
 You can specify used libraries for artifacts of all types using the `libraries` script block:
 
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 program('foo') {
     libraries {
         // configure the libraries used
     }
 }
+```
+
+</div>
 
 There are several ways to describe a library used by an artifact:
 
@@ -198,16 +271,23 @@ There are several ways to describe a library used by an artifact:
 the [`Project.file`](https://docs.gradle.org/current/dsl/org.gradle.api.Project.html#org.gradle.api.Project:file(java.lang.Object))
 method may be passed there:
 
-    ```
+    <div class="sample" markdown="1" theme="idea" mode="groovy">
+    
+    ```groovy
     libraries {
         file 'libs/foo.klib'
         files 'lib1.klib', 'lib2.klib'
     }
     ```
+    
+    </div>
+
 * Specify a Kotlin/Native artifact object or its name. In this case the plugin automatically chooses a library with the correct target
 and sets dependencies between building tasks.
 
-    ```
+    <div class="sample" markdown="1" theme="idea" mode="groovy">
+    
+    ```groovy
     libraries {
         // Artifact object or just its name may be used
         artifact 'foo'
@@ -221,9 +301,14 @@ and sets dependencies between building tasks.
         artifact 'stdio'
     }
     ```
+    
+    </div>
+
 * Specify a project containing libraries. In this case all libraries built by the project specified will be used:
 
-    ```
+    <div class="sample" markdown="1" theme="idea" mode="groovy">
+    
+    ```groovy
     libraries {
         allLibrariesFrom project(':subproject')
     
@@ -231,9 +316,14 @@ and sets dependencies between building tasks.
         allInteropLibrariesFrom project(':interop')
     }
     ```
+    
+    </div>
+
 * Specify only the name of a library. In this case the compiler will look for the library in its repositories.
 
-    ```
+    <div class="sample" markdown="1" theme="idea" mode="groovy">
+    
+    ```groovy
     libraries {
         klib 'foo'
         klibs 'lib1', 'lib2'
@@ -244,12 +334,17 @@ and sets dependencies between building tasks.
     }
     ```
     
+    </div>
+
 ## Multiplatform build
 
 Kotlin/Native, Kotlin/JVM, and Kotlin/JS, support multiplatform projects. Such support is included in the
 Kotlin/Native Gradle plugin by default and there is no need to apply any additional plugins to use it. By default
 multiplatform support is turned off, and can be enabled with the `enableMultiplatform` DSL method:
 
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 apply 'konan'
 
 konanArtifacts {
@@ -257,25 +352,41 @@ multiplatform support is turned off, and can be enabled with the `enableMultipla
         enableMultiplatform true
     }
 }
+```
+
+</div>
 
 The Gradle plugin adds an `expectedBy` dependency configuration that is used to specify a dependency from a Kotlin/Native
 project to a common project:
 
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 apply 'konan'
 
 dependencies {
     expectedBy project('commonProject')
 }
+```
+
+</div>
 
 When a common project is added as an `expectedBy` dependency, all the artifacts with the multiplatform support enabled
 will use its `main` source set as a common module. One may specify custom source sets for each artifact using the
 `commonSourceSets` DSL method. In this case the multiplatform support will be also enabled for this artifact.
 
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 konanArtifacts {
     program('foo') {
         commonSourceSets 'customSourceSet', 'anotherCustomSourceSet'
     }
 }
+```
+
+</div>
+
 
 See more about multiplatform projects [here](https://kotlinlang.org/docs/reference/multiplatform.html).
 
@@ -326,10 +437,14 @@ for each an artifact is defined in a `konanArtifacts` block. Such a task may hav
 the artifact for all the supported targets declared for the project. You can change this behavior by specifying the space-separated
 target list in the `konan.build.targets` project property:
 
-    ```
+    <div class="sample" markdown="1" theme="idea" mode="shell">
+    
+    ```bash
      ./gradlew compileKonanFoo -Pkonan.build.targets='android_arm32 android_arm64'
     ```
    
+    </div>
+
     The task has no properties to use by a build script.
 
 * __compileKonan__. Aggregate task to build all the Kotlin/Native artifacts for all available targets. `konan.build.targets` project
@@ -340,10 +455,15 @@ executable. The task is an instance of Gradle's [`Exec`](https://docs.gradle.org
 so it supports all the settings provided by `Exec`. Additionally, run parameters may be passed to the task using the `runArgs`
 project property:
 
-    ```
+    <div class="sample" markdown="1" theme="idea" mode="shell">
+        
+    ```bash
     ./gradlew runFoo -PrunArgs='foo bar'
     ```
         
+    </div>
+
+
 The plugin also edits the default `build` and `clean` tasks so that the first one allows you to build all the artifacts supported
 (it's dependent on the `compileKonan` task) and the second one removes the files created by the Kotlin/Native build.
 
@@ -360,7 +480,9 @@ Each task building a dynamic library produces two files: the library itself (a `
 on the target platform) and a C language header. Both of them may be accessed via properties of a building task
 (both properties have type `File`):
 
-    ```
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 konanArtifacts {
     // Build a dynamic library 
     dynamic('foo') { /* ... */ }
@@ -369,6 +491,9 @@ on the target platform) and a C language header. Both of them may be accessed vi
 konanArtifacts.foo.getByTarget('host').artifact    // Points to the library file
 konanArtifacts.foo.getByTarget('host').headerFile  // Points to the header file
 ```
+
+</div> 
+    
 Using a dynamic library is shown in the [python extension sample](samples/python_extension).
     
 ### Framework
@@ -377,7 +502,9 @@ An Objective-C framework can be built using the `framework` artifact block. This
 same options as other ones. One may access the framework built using `artifact` property of the building task
 (see the [**Tasks**](#tasks) section). Unlike other artifacts this property points to a directory instead of a regular file.
 
-    ```
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 konanArtifacts {
     // Build an Objective-C framework
     framework('foo') { /* ... */ }
@@ -385,6 +512,9 @@ same options as other ones. One may access the framework built using `artifact`
 
 konanArtifacts.foo.getByTarget('host').artifact // Points to the framework directory
 ```
+
+</div>    
+
 Using a framework is shown in the [calculator sample](samples/calculator).
 
 ## Additional options
@@ -393,11 +523,17 @@ You can also pass additional command line keys to the compiler or cinterop tool
 available in the artifact configuration script block. For example this sample enables a verbose output for a link and bitcode
 generation stages and prints the execution time for all the compiler phases:
 
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 konanArtifacts {
     program('foo') {
         extraOpts '--verbose', 'linker', '--verbose', 'bitcode', '--time'
     }
 }
+```
+
+</div>
 
 Any command line key supported by the according tool (compiler or cinterop) can be used. Some of them are listed in the
 tables below.
@@ -420,6 +556,9 @@ tables below.
 
 ## Plugin DSL
 
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 // Default targets to build for.
 konan.targets = ['macbook', 'linux', 'wasm32']
 
@@ -599,8 +738,16 @@ tables below.
     }
 }
 
+```
+
+</div>
+
+
 ## Multiplatform DSL
 
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 apply plugin: 'konan'
 
 // In this example common code is located in 'foo' and 'bar' source sets of ':common' project.
@@ -623,6 +770,9 @@ tables below.
     // Use the ':foo' project as a common project for multiplatform build.
     expectedBy project(':common')
 }
+```
+
+</div>
 
 ## Publishing to Maven
 
@@ -631,14 +781,22 @@ metadata feature. So some additional steps are required. First of all, the gradl
 than the gradle version of kotlin native plugin that it depends on (currently Gradle 4.7). Before Gradle 5.0, the feature 
 [GRADLE_METADATA](https://github.com/gradle/gradle/blob/master/subprojects/docs/src/docs/design/gradle-module-metadata-specification.md) 
 should be enabled for the build. e.g. in settings.gradle
-````
+
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 enableFeaturePreview('GRADLE_METADATA')
-````
+```
+
+</div> 
+
 
 Some Maven repositories require some declarations in the `pom` files, that should be present in all auxiliary `pom` files (
 platform x build types). To meet this requirement the Kotlin/Native plugin has the following syntax to do it:
 
- ````
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 konanArtifacts {
  interop('libcurl') {
      target('linux') {
@@ -656,8 +814,10 @@ platform x build types). To meet this requirement the Kotlin/Native plugin has t
      }
  }
 }
+```
+
+</div> 
 
- ````
  In this example `name` and `description` tags will be added to each generated `pom` file for _libcurl_ published artifact.
 
 ## Experimental plugin
@@ -668,18 +828,25 @@ for native languages and provides a new DSL which is much closer to the DSL of K
 plugins than the old one.
 The plugin is available at the Gradle plugin portal:
 
-```
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 plugins {
     id "org.jetbrains.kotlin.platform.native" version "0.9"
 }
 ```
 
+</div> 
+
+
 ### Source management
 
 Source management in the `kotlin.platform.native` plugin is uniform with other Kotlin plugins and is based on source sets. A source set is a group of Kotlin/Native source which may contain both common and platform-specific code. The plugin provides a top-level script block `sourceSets` allowing you to configure source sets. Also it creates the default source sets `main` and `test` (for production and test code respectively).
 By default the production sources are located in `src/main/kotlin` and the test sources - in `src/test/kotlin`.
 
-````
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 sourceSets {
     // Adding target-independent sources.
     main.kotlin.srcDirs += 'src/main/mySources'
@@ -687,13 +854,17 @@ sourceSets {
     // Adding Linux-specific code. It will be compiled in Linux binaries only.
     main.target('linux_x64').srcDirs += 'src/main/linux'
 }
-````
+```
+
+</div> 
 
 ### Targets and output kinds
 
 By default the plugin creates software components for the main and test source sets. You can access them via the `components` container provided by Gradle or via the `component` property of a corresponding source set:
 
-````
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 // Main component.
 components.main
 sourceSets.main.component
@@ -701,7 +872,9 @@ sourceSets.main.component
 // Test component.
 components.test
 sourceSets.test.component
-````
+```
+
+</div> 
 
 Components allow you to specify:
 
@@ -711,23 +884,32 @@ Components allow you to specify:
 
 Targets can be specified by setting a corresponding component property:
 
-````
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 components.main {
     // Compile this component for 64-bit MacOS, Linux and Windows.
     targets = ['macos_x64', 'linux_x64', 'mingw_x64']
 }
-````
+```
+
+</div> 
 
 The plugin uses the same notation as the compiler. By default, test component uses the same targets as specified for the main one.
 
 Output kinds can also be specified using a special property:
 
-````
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 components.main {
     // Compile the component into an executable and a Kotlin/Native library.
     outputKinds = [EXECUTABLE, KLIBRARY]
 }
-````
+```
+
+</div> 
+
 All constants used here are available inside a component configuration script block.
 The plugin supports producing binaries of the following kinds:
 
@@ -764,42 +946,63 @@ Basic lifecycle tasks like `assemble`, `build`, and `clean` are also available.
 The plugin builds a test executable for all the targets specified for the `test` component. If the current host platform is
 included in this list the test running tasks are also created. To run tests, execute the standard lifecycle `check` task:
 
+<div class="sample" markdown="1" theme="idea" mode="shell">
+
+```bash
 ./gradlew check
+```
+
+</div> 
 
 ### Dependencies
 
 The plugin allows you to declare dependencies on files and other projects using traditional Gradle's mechanism of
 configurations. The plugin supports Kotlin multiplatform projects allowing you to declare the `expectedBy` dependencies
 
-````
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 dependencies {
     implementation files('path/to/file/dependencies')
     implementation project('library')
     testImplementation project('testLibrary')
     expectedBy project('common')
 }
-````
+```
+
+</div> 
 
 It's possible to depend on a Kotlin/Native library published earlier in a maven repo. The plugin relies on Gradle's
 [metadata](https://github.com/gradle/gradle/blob/master/subprojects/docs/src/docs/design/gradle-module-metadata-specification.md)
 support so the corresponding feature must be enabled. Add the following line in your `settings.gradle`:
 
-````
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 enableFeaturePreview('GRADLE_METADATA')
-````
+```
+
+</div>
+
 
 Now you can declare a dependency on a Kotlin/Native library in the traditional `group:artifact:version` notation:
 
-````
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 dependencies {
     implementation 'org.sample.test:mylibrary:1.0'
     testImplementation 'org.sample.test:testlibrary:1.0'
 }
-````
+```
+
+</div>
 
 `implementation`-dependencies are also available in the component block:
 
-````
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 components.main {
     dependencies {
         implementation 'org.sample.test:mylibrary:1.0'
@@ -811,14 +1014,18 @@ components.test {
         implementation org.sample.test:testlibrary:1.0'
     }
 }
-````
+```
+
+</div>
 
 
 ### Using cinterop
 
 It's possible to declare a cinterop dependency for a component. The DSL here is similar to the one used in the `konan` plugin:
 
-````
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 components.main {
     dependencies {
         cinterop('mystdio') {
@@ -834,31 +1041,42 @@ components.main {
         }
     }
 }
-````
+```
+
+</div>
 
 Here an interop library will be built and added in the component dependencies.
 
 Often it's necessary to specify target-specific linker options for a Kotlin/Native binary using an interop. It can be
 done using the `target` script block:
 
-````
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 components.main {
     target('linux') {
         linkerOpts '-L/path/to/linux/libs'
     }
 }
-````
+```
+
+</div>
 
 Also the `allTargets` block is available 
 
-````
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 components.main {
     // Configure all targets.
     allTargets {
         linkerOpts '-L/path/to/libs'
     }
 }
-````
+```
+
+</div>
+
 
 ### Publishing
 
@@ -867,13 +1085,21 @@ metadata to publish the artifacts so this feature must be enabled (see the [depe
 
 Now you can publish the artifacts with the standard Gradle `publish` task:
 
+<div class="sample" markdown="1" theme="idea" mode="shell">
+
+```bash
 ./gradlew publish
+```
+
+</div>
     
 Only `EXECUTABLE` and `KLIBRARY` binaries are published currently.
 
 The plugin allows you to customize the pom generated for the publication with the `pom` code block available for every component:
 
-````
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 components.main {
     pom {
         withXml {
@@ -883,7 +1109,10 @@ components.main {
         }
     }
 }
-````
+```
+
+</div>
+
 
 ### DSL example
 
@@ -892,7 +1121,9 @@ See also the example projects that use this plugin, e.g.
 [Kotlinx.coroutines](https://github.com/Kotlin/kotlinx.coroutines),
 [MPP http client](https://github.com/e5l/http-client-common/tree/master/samples/ios-test-application)
 
-````
+<div class="sample" markdown="1" theme="idea" mode="groovy">
+
+```groovy
 plugins {
     id "org.jetbrains.kotlin.platform.native" version "0.9"
 }
@@ -988,10 +1219,6 @@ components.main {
     // Additional options passed to the compiler.
     extraOpts '--time'
 }
-````
+```
-
-
-
-
-
 
+</div>