gradle-plugin, readme: Add descriptions of task properties
This commit is contained in:
Ilya Matveev
+103
-29
@@ -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/<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
|
||||
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`.
|
||||
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<ArtifactName>`.
|
||||
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: `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) }
|
||||
}
|
||||
|
||||
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<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.
|
||||
|
||||
Reference in New Issue
Block a user