gradle-plugin, readme: Add descriptions of task properties

GRADLE_PLUGIN.md

@@ -1,6 +1,7 @@
 # Kotlin/Native Gradle plugin
 
-#### Overview
+## Overview
+
 You may use the Gradle plugin to build _Kotlin/Native_ projects. To use it you need to include the following snippet in
 a build script (see projects in `samples` directory):
 
@@ -46,14 +47,33 @@ details). The plugin uses `src/main/kotlin/` as a default directory for sources.
        }
     }
 
-If you want to interact with native C libraries you need to define them in `konanInterop` block and add the defined
+## Using C interop
-interop in the artifact definition using `useInterop` method.
+
+Kotlin/Native provides an easy interaction with native C libraries. The detailed description of this mechanism
+can be found in `INTEROP.md` while this section describes how to use Gradle to build Kotlin/Native apps using
+C libraries.
+
+All the C libraies used should be defined in `konanInterop` block.
 
     konanInterop {
        stdio {
            defFile 'stdio.def'
        }
     }
+    
+Each element (interop) in this block corresponds to some native library described by a def-file (see `INTEROP.md` to
+read more about def-files). The default path to the def-file of an interop is `src/main/c_interop/<interop-name>.def`.
+
+Each interop is processed by the plugin in two steps:
+
+1. Stub generation. In this step the plugin uses `cinterop` tool to generate Kotlin and bitcode (*.bc) stubs for the
+library. You can specify additional parameters for this tool in the interop block (e.g. a custom def-file is specified
+in the example above). See **Plugin DSL** section below for available parameters and `INTEROP.md` for `cinterop` tool
+description.
+2. Stub compilation. In this step the plugin uses Kotlin/Native compiler to compile the stubs generated by the step (1)
+into a klib which can be linked with a Kotlin/Native application.
+
+To build some artifact with an interop add `useInterop` command in the artifact section:
 
     konanArtifacts {
        CsvParser {
@@ -62,35 +82,89 @@ interop in the artifact definition using `useInterop` method.
        }
     }
 
-Each element in the `konanInterop` block creates a task for `cinterop` tool exection (see `INTEROP.md` to read more
+You also can use an interop from another project:
-about this tool) so you can specify `cinterop` parameters here (see **Plugin DSL** section below). The default path to
-an interop def-file is `src/main/c_interop/<interop-name>.def`.
 
-One can get a task for Kotlin/Native compilation using the `compilationTask` artifact property or by name:
+    evaluationDependsOn 'anotherProject'
-`compileKonan<ArtifactName>`.
 
-    konanArtifacts['foo'].compilationTask    // The task name is "compileKonanFoo"
-
-One can get `cinterop` execution and stub compilation tasks using `generateStubsTask` and `compileStubsTask`
-interop properties or by names: `gen<InteropName>InteropStubs` (`cinterop` execution task) and
-`compile<InteropName>InteropStubs` (stub compilation task).
-
-    konanInterop['stdio'].generateStubsTask  // The task name is "genStdioInteropStubs"
-    konanInterop['stdio'].compileStubsTask   // The task name is "compileStdioInteropStubs"
-
-All the tasks contain a set of properties allowing one to obtain paths to artifacts built and parameters of compilation/cinterop
-execution. One may print all these parameters by specifying `dumpParamters(true)` in an interop or an artifact block:
-    
     konanArtifacts {
-       foo { dumpParameters(true) }
+       Foo {
-    }
+           useInterop project('anotherProject').konanInterop['someInterop']
-    
+       }
-The plugin creates two additional tasks: `compileKonan` and `run`. The first one is dependent on all compilation
+    }            
-tasks and allows one to build all the artifacts supported by the current host. The second one allows one to run all
-executable artifacts supported by the current host. Additional parameters can be passed using the `runArgs` project
-property:
 
+### Tasks
+
+The Kotlin/Native plugin creates the following tasks:
+* __compileKonan*ArtifactName*__. The plugin creates such a task for each an artifact defined in a `konanArtifacts` block.
+You may get this task using the `compilationTask` property of an artifact or by its name:
+
+    ```
+    // The task name is "compileKonanFoo"
+    konanArtifacts['foo'].compilationTask
+    ```
+    
+    Such a task compiles its artifact and has the following properties accessible from a build script:
+
+    |Property            |Type                        |Description                                       |
+    |--------------------|----------------------------|--------------------------------------------------|
+    |`outputDir         `|`File`                      |Directory to place the output artifact            |
+    |`artifact          `|`File`                      |The output artifact                               |
+    |`artifactPath      `|`String`                    |Absolute path to the artifact                     |
+    |`produce           `|`String`                    |Kind of the artifact (executable, klib or bitcode)|
+    |`inputFiles        `|`Collection<FileCollection>`|Compiled files                                    |
+    |`libraries         `|`Collection<FileCollection>`|*.klib libraries used by the artifact             |
+    |`nativeLibraries   `|`Collection<FileCollection>`|*.bc libraries used by the artifact               |
+    |`linkerOpts        `|`List<String>`              |Additional options passed to the linker           |
+    |`enableDebug       `|`boolean`                   |Is the debugging support enabled                  |
+    |`noStdLib          `|`boolean`                   |Is the artifact not linked with stdlib            |
+    |`noMain            `|`boolean`                   |Is the `main` function provided by a library used |
+    |`enableOptimization`|`boolean`                   |Is the optimization enabled                       |
+    |`enableAssertions  `|`boolean`                   |Is the assertion support enabled                  |
+    
+* __gen*InteropName*InteropStubs__. The plugin creates such a task for each an interop defined in a `konanInterop` block.
+You may get this task using `generateStubsTask` property of an interop object or by its name:
+
+    ```
+    // The task name is "genFooInteropStubs"
+    konanInterop['foo'].generateStubsTask
+    ```
+    
+    Such a task generates stubs for the library defined by the interop and has the following properties accessible
+    from a build script
+    
+    |Property       |Type                        |Description                                       |
+    |-------------- |----------------------------|--------------------------------------------------|
+    |`stubsDir     `|`File`                      |An output directory for the Kotlin stubs generated|
+    |`libsDir      `|`File`                      |An output directory for the compiled stubs        |
+    |`defFile      `|`File`                      |Def-file used by the interop                      |
+    |`compilerOpts `|`List<String>`              |Additional options passed to clang                |
+    |`linkerOpts   `|`List<String>`              |Additional options passed to a linker             |
+    |`headers      `|`Collection<FileCollection>`|Additional headers used for stub generation       |
+    |`linkFiles    `|`Collection<FileCollection>`|Additional files linked with the stubs            |
+    
+* __compile*InteropName*InteropStubs__. The plugin creates such a task for each interop defined in a `konanInterop` block.
+You may get this task using `compileStubsTask` property of an interop object or by its name:
+
+    ```
+    // The task name is "compileStdioInteropStubs"
+    konanInterop['stdio'].compileStubsTask 
+    
+    ```
+    
+    This task uses the Kotlin/Native compiler to compile the Kotlin stubs generated by the previous task. The task has the
+    same properties as __compileKonan*ArtifactName*__.
+    
+* __compileKonan__. This task is dependent on all compilation tasks and allows one to build all the artifacts supported
+by the current host. The task has no properties to use by a build script.
+
+* __run__. This task builds and runs all the executable artifacts supported by the current host. Additional run
+parameters can be passed using the `runArgs` project property:
+
+    ```
     ./gradlew run -PrunArgs='foo bar'
+    ```
+    
+    The task has no properties to use by a build script.
 
 The plugin also edits the default `build` and `clean` tasks so that the first one allows one 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
@@ -123,7 +197,7 @@ For this project the task graph will be the following:
                         genBarInteropStubs
     clean
 
-#### Plugin DSL
+### Plugin DSL
 
      konanArtifacts {
          artifactName {
@@ -173,7 +247,7 @@ For this project the task graph will be the following:
      konanInterop {
          interopName {
              defFile project.file("deffile.def")                    // Def-file for stub generation.
-             pkg 'org.sample'                                       // Package to place stubs generated.
+             pkg 'org.sample'                                       // Package to place the stubs generated.
              target 'macbook'                                       // Target platform.
 
              // Options to be passed to compiler and linker by cinterop tool.