From e4203ec86c10a2541e8f64e0b70b5bbafcde6136 Mon Sep 17 00:00:00 2001 From: Ilya Matveev Date: Fri, 31 Mar 2017 18:32:27 +0700 Subject: [PATCH] gradle-plugin: Add gradle plugin description --- GRADLE_PLUGIN.md | 126 ++++++++++++++++++ samples/csvparser/build.gradle | 8 +- samples/gitchurn/build.gradle | 42 ++++++ .../src/main/kotlin/KonanCompilerConfig.kt | 1 - 4 files changed, 173 insertions(+), 4 deletions(-) create mode 100644 GRADLE_PLUGIN.md diff --git a/GRADLE_PLUGIN.md b/GRADLE_PLUGIN.md new file mode 100644 index 00000000000..1593477c777 --- /dev/null +++ b/GRADLE_PLUGIN.md @@ -0,0 +1,126 @@ +# Kotlin/Native Gradle plugin + +#### 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): + + buildscript { + repositories { + mavenCentral() + maven { + url "https://dl.bintray.com/jetbrains/kotlin-native-dependencies" + } + } + + dependencies { + classpath "org.jetbrains.kotlin:kotlin-native-gradle-plugin:0.1" + } + } + + apply plugin: 'konan' + +The plugin downloads the compiler during its first run. If you already downloaded the compiler manually you may specify +the path to it using `konan.home` project property (e.g. in `gradle.properties`): + + konan.home=/path/to/already/downloaded/compiler + +In this case the compiler will not be downloaded by the plugin. + +To use the plugin you need to define artifacts you want to build in the `konanArtifacts` block. Here you can specify +source files and compilation parameters (e.g. a target platform) for each artifact (see **Plugin DSL** section below for +details). + + konanArtifacts { + foo { + inputFiles = fileTree('foo/src') + } + + bar { + inputFiles = fileTree('bar/src') + target = iphone + } + } + +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. + + konanInterop { + stdio { + defFile 'stdio.def' + } + } + + konanArtifacts { + CsvParser { + inputFiles project.file('CsvParser.kt') + useInterop 'stdio' + } + } + +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). + +You can get a task for Kotlin/Native compilation using `compilationTask` property of an artifact: + + konanArtifacts['foo'].compilationTask + +You can get a task for `cinterop` execution and a stub compilation task using `generateStubsTask` and `compileStubsTask` +of an interop defined: + + konanInterop['stdio'].generateStubsTask + konanInterop['stdio'].compileStubsTask + +All tasks contain a set of properties allowing one to obtain paths to artifacts built and paramters of compilation and +cinterop execution (see the `dumpParameters` task in `samles/csvparser/build.gradle` for example). + +#### Plugin DSL + + konanArtifacts { + artifactName { + // Source files + inputFiles project.fileTree('src') + + // Directory for output artifact (default: build/konan/bin/). + outputDir 'path/to/output/dir' + + // *.kt.bc library for linking. + library project.file('path/to/library') + + // naitve library for linking. + nativeLibrary project.file('path/to/native/library/') + + noStdLib() // Don't link with stdlib. + noLink() // Don't link, just produce a bitcode file. + enableOptimization() // Enable compiler optimizations. + + // Arguments to be passed to a linker. + linkerOpts 'Some linker opts' + + // Target platform. Available values: "macbook", "linux", "iphone", "raspberrypi". + target 'macbook' + + // Language and API version. + languageVersion 'version' + apiVersion 'version' + + // Native interop to use in the artifact. + useInerop "interopName" + } + } + + konanInterop { + interopName { + defFile project.file("deffile.def") // Def-file for stub generation. + pkg 'org.sample' // Package to place stubs generated. + target 'macbook' // Target platform. + + // Options to be passed to compiler and linker by cinterop tool. + compilerOpts 'Options for native stubs compilation' + linkerOpts 'Options for native stubs' + + headers project.files('header1.h', 'header2.h') // Additional headers to parse. + includeDirs "include/directory" "another/directory" // Directories to look for headers. + + link // Additional files to link with native stubs. + } + } \ No newline at end of file diff --git a/samples/csvparser/build.gradle b/samples/csvparser/build.gradle index 6b33262bc21..3b6f236e655 100644 --- a/samples/csvparser/build.gradle +++ b/samples/csvparser/build.gradle @@ -36,17 +36,18 @@ build { } void dumpCompilatioTask(Task task) { + println() println("Compilation task: ${task.name}") println("outputDir : ${task.outputDir}") println("artifactPath : ${task.artifactPath}") - println("inputFiles : ${task.inputFiles}") + println("inputFiles : ${task.inputFiles.files}") println("libraries : ${task.libraries}") println("nativeLibraries : ${task.nativeLibraries}") println("linkerOpts : ${task.linkerOpts}") println("noStdLib : ${task.noStdLib}") println("noLink : ${task.noLink}") println("noMain : ${task.noMain}") - println("enableOptimization : ${task.enableOptimizatio}") + println("enableOptimization : ${task.enableOptimization}") println("enableAssertions : ${task.enableAssertions}") println("target : ${task.target}") println("languageVersion : ${task.languageVersion}") @@ -54,6 +55,7 @@ void dumpCompilatioTask(Task task) { } void dumpInteropTask(Task task) { + println() println("Stub generation task: ${task.name}") println("stubsDir : ${task.stubsDir}") println("libsDir : ${task.libsDir}") @@ -63,7 +65,7 @@ void dumpInteropTask(Task task) { println("linker : ${task.linker}") println("compilerOpts : ${task.compilerOpts}") println("linkerOpts : ${task.linkerOpts}") - println("headers : ${task.headers}") + println("headers : ${task.headers.files}") println("linkFiles : ${task.linkFiles}") } diff --git a/samples/gitchurn/build.gradle b/samples/gitchurn/build.gradle index ff0cb7a5cbc..1dd8c53fc0b 100644 --- a/samples/gitchurn/build.gradle +++ b/samples/gitchurn/build.gradle @@ -37,4 +37,46 @@ build { into projectDir.canonicalPath } } +} + +void dumpCompilatioTask(Task task) { + println() + println("Compilation task: ${task.name}") + println("outputDir : ${task.outputDir}") + println("artifactPath : ${task.artifactPath}") + println("inputFiles : ${task.inputFiles.files}") + println("libraries : ${task.libraries}") + println("nativeLibraries : ${task.nativeLibraries}") + println("linkerOpts : ${task.linkerOpts}") + println("noStdLib : ${task.noStdLib}") + println("noLink : ${task.noLink}") + println("noMain : ${task.noMain}") + println("enableOptimization : ${task.enableOptimization}") + println("enableAssertions : ${task.enableAssertions}") + println("target : ${task.target}") + println("languageVersion : ${task.languageVersion}") + println("apiVersion : ${task.apiVersion}") +} + +void dumpInteropTask(Task task) { + println() + println("Stub generation task: ${task.name}") + println("stubsDir : ${task.stubsDir}") + println("libsDir : ${task.libsDir}") + println("defFile : ${task.defFile}") + println("target : ${task.target}") + println("pkg : ${task.pkg}") + println("linker : ${task.linker}") + println("compilerOpts : ${task.compilerOpts}") + println("linkerOpts : ${task.linkerOpts}") + println("headers : ${task.headers.files}") + println("linkFiles : ${task.linkFiles}") +} + +task dumpParameters { + doLast { + dumpCompilatioTask(konanArtifacts['GitChurn'].compilationTask) + dumpInteropTask(konanInterop['libgit2'].generateStubsTask) + dumpCompilatioTask(konanInterop['libgit2'].compileStubsTask) + } } \ No newline at end of file diff --git a/tools/gradle-plugin/src/main/kotlin/KonanCompilerConfig.kt b/tools/gradle-plugin/src/main/kotlin/KonanCompilerConfig.kt index 95c7cd5dd3c..0d1d2d6f94d 100644 --- a/tools/gradle-plugin/src/main/kotlin/KonanCompilerConfig.kt +++ b/tools/gradle-plugin/src/main/kotlin/KonanCompilerConfig.kt @@ -12,7 +12,6 @@ import java.io.File * * artifactName1 { * - * inputDir "path/to/files" * inputFiles "files" "to" "be" "compiled" * * outputDir "path/to/output/dir"