kotlin-fork/GRADLE_PLUGIN.md

Kotlin/Native Gradle plugin

Note: The plugin DSL was changed in v0.3.4. See the details below.

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.3.4"
   }
}

apply plugin: 'konan'

The plugin downloads the compiler during its first run. You may specify a version of the compiler using konan.version project property:

konan.version=0.3

If you already downloaded the compiler manually you may specify the path to its root directory using konan.home project property (e.g. in gradle.properties). Note: the plugin ignores the konan.version property in this case.

konan.home=/home/user/kotlin-native-0.3

In this case the compiler will not be downloaded by the plugin.

Building artifacts

The Kotlin/Native Gradle plugin allows one to build artifacts of the following types:

• Executable
• Library
• Interoperability library - a special type of library providing an interoperability with some native API. See INTEROP.md for details
• LLVM bitcode

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:

konanArtifacts {
    program('foo')  // executable 'foo'
    library('bar')  // library 'bar'
    bitcode('baz')  // bitcode file 'baz'
    interop('qux')  // interoperability library 'qux'. Use it instead of konanInterop block.
}

All artifacts except interop libraries are built by the Kotlin/Native compiler. Such an artifact may be configured using its script block. Here one can specify source files, used libraries and compilation flags (see Plugin DSL section for details). The plugin uses src/main/kotlin/ as a default source directory for all compiler artifacts:

konanArtifacts {
    // Build foo.klib
    library('foo') {
        srcFiles fileTree('src/foo/kotlin') // Use custom source path
    }

    // Build executable 'bar'
    program('bar') {
        // The default source path is used (src/main/kotlin)

        // Optimize the output code
        enableOptimizations true

        libraries {
            // Use foo.klib as a library
            artifact 'foo'
        }
    }
}

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:

    konanArtifacts {
        // Interoperability library stdio.klib
        // Use the default def-file path: src/main/c_interop/stdio.def
        interop('stdio')

        // Interoperability library openal.klib
        interop('openal') {
            defFile 'src/openal/openal.def'
        }

        program('main') {
            libraries {
                // Link with stdio.klib
                artifact 'stdio'
            }
        }
    }

Building for different targets

All the artifacts declared in a project may be built for different targets. By default they are built only for host target i.e. a computer used for building. One may change the target list using the konan.targets project extension:

konan.targets = [ 'linux', 'android_arm64', 'android_arm32' ]

The plugin creates tasks to compile each artifact for all targets supported by current host and declared in the konan.targets list. One may perform additional configuration for a target using target method of an artifact configuration block:

konan.targets = [ 'linux', 'macbook', 'wasm32' ]

konanArtifacts {
    program('foo') {
        // This source file is used for all targets
        srcFiles 'common.kt'

        target('linux') {
            // For Linux common.kt and linux.kt will be compiled
            srcFiles 'linux.kt'
        }

        target('macbook') {
            // For MacOS common.kt and macbook.kt will be compiled
            srcFiles 'macbook.kt'
        }

        // Only common.kt will be compiled for wasm32
    }
}

One may access to a task for some target via artifact methods or properties:

// Both of them return a task building artifact 'foo' for MacOS
konanArtifacts.foo.getByTarget("macbook")
konanArtifacts.foo.macbook

Using libraries

One may specify used libraries for artifacts of all types using libraries script block:

program('foo') {
    libraries {
        // configure the libraries used
    }
}

There are several ways to describe a library used by an artifact:

• Specify a library file directly. One may specify it using the file method of the libraries script block. All objects accepted by the Project.file method may be passed there:

  libraries {
      file 'libs/foo.klib'
      files 'lib1.klib', 'lib2.klib'
  }
  

• Specify a Kotlin/Native artifact object or its name. In this case the plugin automatically chooses a library with correct target and set dependencies between building tasks.

  libraries {
      // Artifact object or just its name may be used
      artifact 'foo'
      artifact kotlinArtifacts.bar
  
      // Interopability libraries are also allowed
      // Use it instead of the `useInterop` method available in versions before 0.3.4
      artifact 'stdio'
  }
  

• Specify a project containing libraries. In this case all libraries built by the project specified will be used:

  libraries {
      allLibrariesFrom project(':subproject')
  
      // If we need only interoperability libraries
      allInteropLibrariesFrom project(':interop')
  }
  

• Specify only name of a library. In this case the compiler will look for the library in its repositories.

      libraries {
          klib 'foo'
          klibs 'lib1', 'lib2'
  
          // One may specify additional repositories
          // All objects accepted by the Project.file method may be used here
          useRepo 'build/libraries'
      }
  

Tasks

The Kotlin/Native plugin creates the following tasks:

• compileKonan. The plugin creates such a task for each target declared in konan.targets list and for each an artifact defined in a konanArtifacts block. Such a task may have different properties depending on the artifact type:

  Properties available for a compiler task (executable, library or bitcode building task):

  Property	Type	Description
  target	String	Target the artifact is built for. Read only
  artifactName	String	Base name for the output file (without an extension)
  destinationDir	File	Directory to place the output artifact
  artifact	File	The output artifact. Read only
  srcFiles	Collection<FileCollection>	Compiled files
  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
  enableOptimizations	boolean	Are the optimizations enabled
  enableAssertions	boolean	Is the assertion support enabled
  measureTime	boolean	Does the compiler print phase time

  Properties available for a cinterop task (task building an interoperability library):

  Property	Type	Description
  target	String	Target the artfact is built for. Read only.
  artifactName	String	Base name for the output file (without an extension)
  destinationDir	File	Directory to place the output artifact
  artifact	File	The output artifact. Read only.
  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

• compileKonan. Aggregate task allowing one to build an artifact for several targets. By default it builds the artifact for all supported targets declared for the project. One may change this behavior by specifying the space-separated target list in konan.build.targets project property:

  ./gradlew compileKonanFoo -Pkonan.build.targets='android_arm32 android_arm64'
  

  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 property also may be used to override the target list. 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 build.

Additional options

You can also pass additional command line keys to the compiler or cinterop tool using the extraOpts expression available in artifact configuration script block. For example this sample enables a verbose output for a link and bitcode generation stages and prints execution time for all compiler phases:

konanArtifacts {
    program('foo') {
        extraOpts '--verbose', 'linker', '--verbose', 'bitcode', '--time'
    }
}

Any command line key supported by the according tool (compiler or cinterop) can be used. Some of them are listed in the tables below.

Compiler additional options

Key	Description
--disable <Phase>	Disable backend phase
--enable <Phase>	Enable backend phase
--list_phases	List all backend phases
--time	Report execution time for compiler phases
--verbose <Phase>	Trace phase execution
-verbose	Enable verbose logging output

Cinterop additional options

Key	Description
-verbose <boolean>	Increase verbosity
-shims <boolean>	Add generation of shims tracing native library calls

Plugin DSL

// Targets to build for.
konan.targets = ['macbook', 'linux', 'wasm32']

// Language and API version.
konan.languageVersion = 'version'
konan.apiVersion = 'version'

konanArtifacts {
    program('foo') {

        // Directory with source files. The default path is src/main/kotlin.
        srcDir 'src/other'

        // Source files.
        srcFiles project.fileTree('src')
        srcFiles 'foo.kt', 'bar.kt'

        // Custom output artifact name (without extension).
        // The default is a name of the artifact
        artifactName 'customName'

        // Base Directory for the output artifacts.
        // Separate subdirectories for each target will be created
        // The default is build/konan/bin
        baseDir 'path/to/output/dir'

        libraries {
            // Library files
            file 'foo.klib'
            files 'file1.klib', file2.klib
            files project.files('file3.klib', 'file4.klib')

            // An artifact from the current project
            artifact konanArtifacts.bar
            artifact 'baz'

            // An artifact from another project
            artifact project(':path:to:a:project', 'artifcatName')

            // All libraries from anohter project
            allLibrariesFrom project(':some:project')

            // Only interoperability libraries from anohter project
            allInteropLibrariesFrom project(':some:interop:project')

            // Named libraries for search in repositoreis
            klib 'foo'
            klib 'bar', 'baz'

            // Custom repository paths
            useRepo 'path/to/a/repo'
            useRepos 'another/repo/1', 'another/repo/2'

        }

        // A naitve library (*.bc) for linking.
        nativeLibrary project.file('path/to/native/library.bc')
        nativeLibraries 'library1.bc', 'library2.bc'

        noStdLib true             // Don't link with stdlib (true/false).
        enableOptimizations true  // Enable compiler optimizations (true/false).
        enableAssertions true     // Enable assertions in binaries generated (true/false).
        enableDebug true          // Enable debugging for binaries generated (true/false).
        noDefaultLibs true        // Don't link with default libraries

        // Arguments to be passed to a linker.
        linkerOpts 'Some linker option', 'More linker options'

        // Print all parameters during the build.
        dumpParameters true

        // Print time of compilation phases (equivalent of the `--time` command line option).
        measureTime true

        // Add the `anotherTask` to the compilation task dependencies.
        dependsOn anotherTask

        // Pass additional command line options to the compiler.
        extraOpts '--time', '--verbose', 'linker'

        // Additional configuration for Linux.
        target('linux') {
            // Exact output directory for a file compile for the given target
            // The default is <baseDir>/<target>
            destinationDir 'exact/output/path'

            // Also all options described for this artifact above are available here.
        }
    }

    library('bar') {
        // Library has the same parameters as an executable
        // The default baseDir is build/konan/libs
    }

    bitcode('baz') {
        // Bitcode has the same parameters as an executable
        // The default baseDir is build/konan/bitcode
    }

    interop('qux') {
        // Def-file describing the native API.
        // The default path is src/main/c_interop/<interop-name>.def
        defFile project.file("deffile.def")

        // Custom output artifact name (without extension).
        // The default is a name of the artifact
        artifactName 'customName'

        // Base Directory for the output artifacts.
        // Separate subdirectories for each target will be created
        // The default is build/konan/libs
        baseDir 'path/to/output/dir'

        // Package to place the Kotlin API generated.
        packageName 'org.sample'

        libraries {
            // All library options from the executable example above are available here.
        }

        // Options to be passed to compiler and linker by cinterop tool.
        compilerOpts 'Options for native stubs compilation'
        linkerOpts 'Options for native stubs'

         // Additional headers to parse.
        headers project.files('header1.h', 'header2.h')

        // Directories to look for headers.
        includeDirs "include/directory" "another/directory"

        // Additional files to link with native stubs.
        link <files which will be linked with native stubs>

        // Print all parameters during the build.
        dumpParameters true

        // Add the `anotherTask` to the stub generation task dependencies.
        dependsOn anotherTask

        // Pass additional command line options to the cinterop tool.
        extraOpts '-shims', 'true'

        // Additional configuration for Linux.
        target('linux') {
            // Exact output directory for a file compile for the given target
            // The default is <baseDir>/<target>
            destinationDir 'exact/output/path'

            // Also all options described for this artifact above are available here.
        }
    }
}