type: doc layout: reference

title: "以 Gradle 构建多平台项目"

Kotlin 多平台 Gradle DSL 参考

Multiplatform projects are an experimental feature in Kotlin 1.2 and 1.3. All of the language and tooling features described in this document are subject to change in future Kotlin versions. {:.note}

The Kotlin Multiplatform Gradle plugin is a tool for creating Kotlin multiplatform projects. Here we provide a reference of its contents; use it as a reminder when writing Gradle build scripts for Kotlin multiplatform projects. For the concepts of Kotlin multiplatform projects and instructions on writing build scripts with the plugin, see Building Multiplatform Projects with Gradle.

目录

• id 与版本
• 顶层块
• 目标
  • 公共目标配置
  • JVM 目标
  • JavaScript 目标
  • Native 目标
  • Android 目标
• 源集
  • 预定义源集
  • 自定义源集
  • 源集参数
• 编译项
  • 预定义编译项
  • 自定义编译项
  • 编译项参数
• 依赖项
• 语言设置

id 与版本

The fully qualified name of the Kotlin Multiplatform Gradle plugin is org.jetbrains.kotlin.multiplatform. If you use the Kotlin Gradle DSL, you can apply the plugin with kotlin(“multiplatform”). The plugin versions match the Kotlin release versions. The most recent version is .

Groovy DSL

plugins {
    id 'org.jetbrains.kotlin.multiplatform' version ''
}

Kotlin DSL

plugins {
    kotlin("multiplatform") version ""
}

顶层块

kotlin is the top-level block for multiplatform project configuration in the Gradle build script. Inside kotlin, you can write the following blocks:

目标

Target is a part of the build responsible for compiling, testing, and packaging a piece of software aimed for one of the supported platforms. The targets of a multiplatform project are described in the corresponding blocks inside kotlin, for example, jvm, android, iosArm64. The complete list of available targets is the following:

Groovy DSL

kotlin {
    jvm()
    iosX64()
    macosX64()
    js().browser()
}

Configuration of a target can include two parts:

• Common configuration available for all targets.
• Target-specific configuration.

公共目标配置

In any target block, you can use the following declarations:

JVM 目标

In addition to common target configuration, jvm targets have a specific function:

Use this function for projects that contain both Java and Kotlin source files. Note that the default source directories for Java sources don't follow the Java plugin's defaults. Instead, they are derived from the Kotlin source sets. For example, if the JVM target has the default name jvm, the paths are src/jvmMain/java (for production Java sources) and src/jvmTest/java for test Java sources. For more information, see Java support in JVM targets.

Kotlin DSL

kotlin {
    jvm {
        withJava()
    } 
}

JavaScript 目标

The js block describes the configuration of JavaScript targets. It can contain one of two blocks depending on the target execution environment:

For details about configuring Kotlin/JS projects, see Setting up a Kotlin/JS project.

Browser

browser can contain the following configuration blocks:

Kotlin DSL

kotlin {
    js().browser {
        webpackTask { /* ... */ }
        testRuns { /* ... */ }
        dceTask {
            keep("myKotlinJsApplication.org.example.keepFromDce")
        }
        distribution {
            directory = File("$projectDir/customdir/")
        }        
    }
}

Node.js

nodejs can contain configurations of test and run tasks:

Kotlin DSL

kotlin {
    js().nodejs {
        runTask { /* ... */ }
        testRuns { /* ... */ }
    }
}

Native 目标

For native targets, the following specific blocks are available:

Binaries

There are the following kinds of binaries:

Kotlin DSL

kotlin {
    linuxX64 { // Use your target instead.
        binaries {
            executable {
                // Binary configuration.
            }
        }
    }
}

For binaries configuration, the following parameters are available:

Groovy DSL

binaries {
    executable('my_executable', [RELEASE]) {
        // Build a binary on the basis of the test compilation.
        compilation = compilations.test

        // Custom command line options for the linker.
        linkerOpts = ['-L/lib/search/path', '-L/another/search/path', '-lmylib']

        // Base name for the output file.
        baseName = 'foo'

        // Custom entry point function.
        entryPoint = 'org.example.main'

        // Accessing the output file.
        println("Executable path: ${outputFile.absolutePath}")

        // Accessing the link task.
        linkTask.dependsOn(additionalPreprocessingTask)

        // Accessing the run task.
        // Note that the runTask is null for non-host platforms.
        runTask?.dependsOn(prepareForRun)
    }

    framework('my_framework' [RELEASE]) {
        // Include a static library instead of a dynamic one into the framework.
        isStatic = true
    }
}

Kotlin DSL

binaries {
    executable("my_executable", listOf(RELEASE)) {
        // Build a binary on the basis of the test compilation.
        compilation = compilations["test"]

        // Custom command line options for the linker.
        linkerOpts = mutableListOf("-L/lib/search/path", "-L/another/search/path", "-lmylib")

        // Base name for the output file.
        baseName = "foo"

        // Custom entry point function.
        entryPoint = "org.example.main"

        // Accessing the output file.
        println("Executable path: ${outputFile.absolutePath}")

        // Accessing the link task.
        linkTask.dependsOn(additionalPreprocessingTask)

        // Accessing the run task.
        // Note that the runTask is null for non-host platforms.
        runTask?.dependsOn(prepareForRun)
    }

    framework("my_framework" listOf(RELEASE)) {
        // Include a static library instead of a dynamic one into the framework.
        isStatic = true
    }
}

For more information on configuring binaries, see Building final native binaries.

CInterops

cinterops is a collection of descriptions for interop with native libraries. To provide an interop with a library, add an entry to cinterops and define its parameters:

For more information on Kotlin interop with C libraries, see CInterop support.

Groovy DSL

kotlin {
    linuxX64 { // Replace with a target you need.
        compilations.main {
            cinterops {
                myInterop {
                    // Def-file describing the native API.
                    // The default path is src/nativeInterop/cinterop/<interop-name>.def
                    defFile project.file("def-file.def")

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

                    // Options to be passed to compiler by cinterop tool.
                    compilerOpts '-Ipath/to/headers'

                    // Directories for header search (an analogue of the -I<path> compiler option).
                    includeDirs.allHeaders("path1", "path2")

                    // A shortcut for includeDirs.allHeaders.
                    includeDirs("include/directory", "another/directory")
                }

                anotherInterop { /* ... */ }
            }
        }
    }
}

Kotlin DSL

kotlin {
    linuxX64 {  // Replace with a target you need.
        compilations.getByName("main") {
            val myInterop by cinterops.creating {
                // Def-file describing the native API.
                // The default path is src/nativeInterop/cinterop/<interop-name>.def
                defFile(project.file("def-file.def"))

                // Package to place the Kotlin API generated.
                packageName("org.sample")

                // Options to be passed to compiler by cinterop tool.
                compilerOpts("-Ipath/to/headers")

                // Directories for header search (an analogue of the -I<path> compiler option).
                includeDirs.allHeaders("path1", "path2")

                // A shortcut for includeDirs.allHeaders.
                includeDirs("include/directory", "another/directory")
            }

            val anotherInterop by cinterops.creating { /* ... */ }
        }
    }
}

Android 目标

The Kotlin multiplatform plugin contains two specific functions for android targets. Two functions help you configure build variants:

Kotlin DSL

kotlin {
    android {
        publishLibraryVariants("release", "debug")
    }
}

For more details about configuring Android targets of multiplatform projects, see Android Support.

Note that the android configuration inside kotlin doesn’t replace the build configuration of any Android project. For information on writing build scripts for Android projects, see the Android developer documentation. {:.note}

源集

The sourceSets block describes source sets of the project. A source set contains Kotlin source files that participate in compilations together, along with their resources, dependencies, and language settings.

A multiplatform project contains predefined source sets for its targets; developers can also create custom source sets for their needs. For instructions on creating and configuring source sets, see Configuring source sets.

预定义源集

Predefined source sets are set up automatically upon creation of a multiplatform project. Available predefined source sets are the following:

With Kotlin Gradle DSL, the sections of predefined source sets should be marked by getting.

Groovy DSL

kotlin { 
    sourceSets { 
        commonMain { /* ... */ } 
    }
}

Kotlin DSL

kotlin { 
    sourceSets { 
        val commonMain by getting { /* ... */ } 
    }
}

For more information about the predefined source sets, see Default Project Layout.

自定义源集

Custom source sets are created by the project developers manually. To create a custom source set, add a section with its name inside the sourceSets section. If using Kotlin Gradle DSL, mark custom source sets by creating.

Groovy DSL

kotlin { 
    sourceSets { 
        myMain { /* ... */ } // create or configure a source set by the name 'myMain' 
    }
}

Kotlin DSL

kotlin { 
    sourceSets { 
        val myMain by creating { /* ... */ } // create a new source set by the name 'MyMain'
    }
}

Note that a newly created source set isn’t connected to other ones. To use it in the project’s compilations, connect it with other source sets as described in Connecting source sets.

源集参数

Configurations of source sets are stored inside the corresponding blocks of sourceSets. A source set has the following parameters:

Groovy DSL

kotlin { 
    sourceSets { 
        commonMain {
            kotlin.srcDir('src')
            resources.srcDir('res')

            dependencies {
                /* ... */
            }           
        } 
    }
}

Kotlin DSL

kotlin { 
    sourceSets { 
        val commonMain by getting {
            kotlin.srcDir("src")
            resources.srcDir("res")

            dependencies {
                /* ... */
            } 
        } 
    }
}

编译项

A target can have one or more compilations, for example, for production or testing. There are predefined compilations that are added automatically upon target creation. Developers can additionally create custom compilations.

To refer to all or some particular compilations of a target, use the compilations object collection. From compilations, you can refer to a compilation by its name.

预定义编译项

Predefined compilations are created automatically for each target of a project except for Android targets. Available predefined compilations are the following:

Groovy DSL

kotlin {
    jvm {
        compilations.main.output // get the main compilation output
        compilations.test.runtimeDependencyFiles // get the test runtime classpath
    }
}

Kotlin DSL

kotlin {
    jvm {
        val main by compilations.getting {
            output // get the main compilation output
        }

        compilations["test"].runtimeDependencyFiles // get the test runtime classpath
    }
}

自定义编译项

In addition to predefined compilations, developers can create their own custom compilations. To create a custom compilation, add a new item into the compilations collection. If using Kotlin Gradle DSL, mark custom compilations by creating.

Groovy DSL

kotlin {
    jvm() {
        compilations.create('integrationTest') {
            defaultSourceSet {
                dependencies {
                    /* ... */
                }
            }

            // Create a test task to run the tests produced by this compilation:
            tasks.create('jvmIntegrationTest', Test) {
                /* ... */
            }
        }
    }
}

Kotlin DSL

kotlin {
    jvm() {
        compilations {
            val integrationTest by compilations.creating {
                defaultSourceSet {
                    dependencies {
                        /* ... */
                    }
                }

                // Create a test task to run the tests produced by this compilation:
                tasks.create<Test>("integrationTest") {
                    /* ... */
                }
            }
        }
    }
}

编译项参数

A compilation has the following parameters:

Groovy DSL

kotlin {
    jvm {
        compilations.main.kotlinOptions { 
            // Setup the Kotlin compiler options for the 'main' compilation:
            jvmTarget = "1.8"
        }

        compilations.main.compileKotlinTask // get the Kotlin task 'compileKotlinJvm' 
        compilations.main.output // get the main compilation output
        compilations.test.runtimeDependencyFiles // get the test runtime classpath
    }

    // Configure all compilations of all targets:
    targets.all {
        compilations.all {
            kotlinOptions {
                allWarningsAsErrors = true
            }
        }
    }
}

Kotlin DSL

kotlin {
    jvm {
        val main by compilations.getting {
            kotlinOptions { 
                // Setup the Kotlin compiler options for the 'main' compilation:
                jvmTarget = "1.8"
            }

            compileKotlinTask // get the Kotlin task 'compileKotlinJvm' 
            output // get the main compilation output
        }

        compilations["test"].runtimeDependencyFiles // get the test runtime classpath
    }

    // Configure all compilations of all targets:
    targets.all {
        compilations.all {
            kotlinOptions {
                allWarningsAsErrors = true
            }
        }
    }
}

依赖项

The dependencies block of the source set declaration contains the dependencies of this source set. There are four kinds of dependencies:

Groovy DSL

kotlin {
    sourceSets {
        commonMain {
            dependencies {
                api 'com.example:foo-metadata:1.0'
            }
        }
        jvm6Main {
            dependencies {
                implementation 'com.example:foo-jvm6:1.0'
            }
        }
    }
}

Kotlin DSL

kotlin {
    sourceSets {
        val commonMain by getting {
            dependencies {
                api("com.example:foo-metadata:1.0")
            }
        }
        val jvm6Main by getting {
            dependencies {
                implementation("com.example:foo-jvm6:1.0")
            }
        }
    }
}

Additionally, source sets can depend on each other. In this case, the dependsOn() function is used. Source set dependencies can also be declared in the top-level dependencies block of the build script. In this case, their declarations follow the pattern <sourceSetName><DependencyKind>, for example, commonMainApi.

Groovy DSL

dependencies {
    commonMainApi 'com.example:foo-common:1.0'
    jvm6MainApi 'com.example:foo-jvm6:1.0'
}

Kotlin DSL

dependencies {
    "commonMainApi"("com.example:foo-common:1.0")
    "jvm6MainApi"("com.example:foo-jvm6:1.0")
}

语言设置

The languageSettings block of a source set defines certain aspects of project analysis and build. The following language settings are available:

Groovy DSL

kotlin {
    sourceSets {
        commonMain {
            languageSettings {
                languageVersion = '1.3' // possible values: '1.0', '1.1', '1.2', '1.3'
                apiVersion = '1.3' // possible values: '1.0', '1.1', '1.2', '1.3'
                enableLanguageFeature('InlineClasses') // language feature name
                useExperimentalAnnotation('kotlin.ExperimentalUnsignedTypes') // annotation FQ-name
                progressiveMode = true // false by default
            }
        }
    }
}

Kotlin DSL

kotlin {
    sourceSets {
        val commonMain by getting {
            languageSettings.apply {
                languageVersion = "1.3" // possible values: '1.0', '1.1', '1.2', '1.3'
                apiVersion = "1.3" // possible values: '1.0', '1.1', '1.2', '1.3'
                enableLanguageFeature("InlineClasses") // language feature name
                useExperimentalAnnotation("kotlin.ExperimentalUnsignedTypes") // annotation FQ-name
                progressiveMode = true // false by default
            }
        }
    }
}