From 50564803c27c30f58d513ed4a24cb5fd521d9caa Mon Sep 17 00:00:00 2001 From: Ilya Matveev Date: Fri, 11 Aug 2017 18:18:33 +0700 Subject: [PATCH] gradle-plugin, readme: Add descriptions of task properties --- GRADLE_PLUGIN.md | 132 ++++++++++++++++++++++++++++++++++++----------- 1 file changed, 103 insertions(+), 29 deletions(-) diff --git a/GRADLE_PLUGIN.md b/GRADLE_PLUGIN.md index 575400b2ce2..8023b9e8c15 100644 --- a/GRADLE_PLUGIN.md +++ b/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 -interop in the artifact definition using `useInterop` method. +## Using C interop + +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/.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 -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/.def`. +You also can use an interop from another project: -One can get a task for Kotlin/Native compilation using the `compilationTask` artifact property or by name: -`compileKonan`. + evaluationDependsOn 'anotherProject' - 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: `genInteropStubs` (`cinterop` execution task) and -`compileInteropStubs` (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) } - } - -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: + Foo { + useInterop project('anotherProject').konanInterop['someInterop'] + } + } +### 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`|Compiled files | + |`libraries `|`Collection`|*.klib libraries used by the artifact | + |`nativeLibraries `|`Collection`|*.bc libraries used by the artifact | + |`linkerOpts `|`List` |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` |Additional options passed to clang | + |`linkerOpts `|`List` |Additional options passed to a linker | + |`headers `|`Collection`|Additional headers used for stub generation | + |`linkFiles `|`Collection`|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.