多平台 Gradle DSL 参考

Kotlin 多平台 Gradle 插件是用于创建 Kotlin 多平台项目的工具。 这里我们提供了它的参考；在为 Kotlin 多平台项目编写 Gradle 构建脚本时， 用它作提醒。 Learn the concepts of Kotlin Multiplatform projects, how to create and configure them.

id 与版本

Kotlin 多平台 Gradle 插件的全限定名是 org.jetbrains.kotlin.multiplatform。 如果你使用 Kotlin Gradle DSL，那么你可以通过 kotlin("multiplatform") 来应用插件。 插件版本与 Kotlin 发行版本相匹配。最新的版本是：2.1.20。

【Kotlin】

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

【Groovy】

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

顶层块

kotlin {} 是在 Gradle 构建脚本中用于配置多平台项目的顶层块。 kotlin {} 块内，你可以使用以下块：

目标

目标 是构建的一部分，负责编译、测试、以及针对某个已支持平台打包软件。 Kotlin provides targets for each platform, so you can instruct Kotlin to compile code for that specific target. Learn more about setting up targets.

Each target can have one or more compilations. In addition to default compilations for test and production purposes, you can create custom compilations.

多平台项目的目标在 kotlin {} 块中的相应代码块中描述，例如：jvm、androidTarget 以及 iosArm64。 以下是可用目标的完整列表：

A target that is not supported by the current host is ignored during building and, therefore, not published.

{style="note"}

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

目标的配置项可以包含这两个部分：

• 可用于所有目标的公共目标配置。
• 目标特定的配置项。

Each target can have one or more compilations.

公共目标配置

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

Web targets

The js {} block describes the configuration of Kotlin/JS targets, and the wasmJs {} block describes the configuration of Kotlin/Wasm targets interoperable with JavaScript. They can contain one of two blocks depending on the target execution environment:

Learn more about configuring Kotlin/JS projects.

A separate wasmWasi {} block describes the configuration of Kotlin/Wasm targets that support the WASI system interface. Here, only the nodejs execution environment is available:

kotlin {
    wasmWasi {
        nodejs()
        binaries.executable()
    }
}

All the web targets, js, wasmJs, and wasmWasi, also support the binaries.executable() call. It explicitly instructs the Kotlin compiler to emit executable files. For more information, see Execution environments in the Kotlin/JS documentation.

Browser

browser {} can contain the following configuration blocks:

kotlin {
    js().browser {
        webpackTask { /* ... */ }
        testRuns { /* ... */ }
        distribution {
            directory = File("$projectDir/customdir/")
        }
    }
}

Node.js

nodejs {} can contain configurations of test and run tasks:

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

原生目标

For native targets, the following specific blocks are available:

Binaries

There are the following kinds of binaries:

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

For binary configuration, the following parameters are available:

【Kotlin】

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
    }
}

【Groovy】

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
    }
}

Learn more about building 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:

【Kotlin】

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/.def
                definitionFile.set(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 compiler option).
                includeDirs.allHeaders("path1", "path2")

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

                // Header files to be included in the bindings.
                header("path/to/header.h")
                headers("path/to/header1.h", "path/to/header2.h")
            }

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

【Groovy】

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/.def
                    definitionFile = 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 compiler option).
                    includeDirs.allHeaders("path1", "path2")

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

                    // Header files to be included in the bindings.
                    header("path/to/header.h")
                    headers("path/to/header1.h", "path/to/header2.h")
                }

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

For more cinterop properties, see Definition file.

Android 目标

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

kotlin {
    androidTarget {
        publishLibraryVariants("release")
    }
}

Learn more about compilation for Android.

The androidTarget configuration inside the kotlin {} block doesn't replace the build configuration of any Android project. Learn more about writing build scripts for Android projects in Android developer documentation.

{style="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.

预定义源代码集

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.

【Kotlin】

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

【Groovy】

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

Learn more about source sets.

自定义源代码集

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.

【Kotlin】

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

【Groovy】

kotlin { 
    sourceSets { 
        myMain { /* ... */ } // create or configure a 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.

源代码集参数

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

【Kotlin】

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

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

【Groovy】

kotlin { 
    sourceSets { 
        commonMain {
            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. You 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.

Learn more about configuring compilations.

预定义编译项

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

【Kotlin】

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

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

【Groovy】

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

自定义编译项

In addition to predefined compilations, you can create your 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.

Learn more about creating a custom compilation.

【Kotlin】

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

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

【Groovy】

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

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

编译项参数

A compilation has the following parameters:

【Kotlin】

kotlin {
    jvm {
        val main by compilations.getting {
            compileTaskProvider.configure {
                compilerOptions {
                    // Set up the Kotlin compiler options for the 'main' compilation:
                    jvmTarget.set(JvmTarget.JVM_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:
    compilerOptions {
        allWarningsAsErrors.set(true)
    }
}

【Groovy】

kotlin {
    jvm {
        compilations.main {
            compileTaskProvider.configure {
                compilerOptions {
                    // Setup the Kotlin compiler options for the 'main' compilation:
                    jvmTarget = JvmTarget.JVM_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:
    compilerOptions {
        allWarningsAsErrors = true
    }
}

Compiler options

You can configure compiler options in your projects at three different levels:

• Extension level, in the kotlin {} block.
• Target level, in a target block.
• Compilation unit level, usually in a specific compilation task.

Settings at a higher level work as defaults for the level below:

• Compiler options set at the extension level are the default for target-level options, including shared source sets like commonMain, nativeMain, and commonTest.
• Compiler options set at the target level are the default for options at the compilation unit (task) level, like compileKotlinJvm and compileTestKotlinJvm tasks.

Configurations made at a lower level override similar settings at higher levels:

• Task-level compiler options override similar settings at the target or extension level.
• Target-level compiler options override similar settings at the extension level.

For the list of possible compiler options, see All compiler options.

Extension level

To configure compiler options for all targets in your project, use the compilerOptions {} block at the top level:

【Kotlin】

kotlin {
    // Configures all compilations of all targets
    compilerOptions {
        allWarningsAsErrors.set(true)
    }
}

【Groovy】

kotlin {
    // Configures all compilations of all targets:
    compilerOptions {
        allWarningsAsErrors = true
    }
}

Target level

To configure compiler options for a specific target in your project, use the compilerOptions {} block inside the target block:

【Kotlin】

kotlin {
    jvm {
        // Configures all compilations of the JVM target
        compilerOptions {
            allWarningsAsErrors.set(true)
        }
    }
}

【Groovy】

kotlin {
    jvm {
        // Configures all compilations of the JVM target
        compilerOptions {
            allWarningsAsErrors = true
        }
    }
}

Compilation unit level

To configure compiler options for a specific task, use the compilerOptions {} block inside the task:

【Kotlin】

task.named("compileKotlinJvm") {
    compilerOptions {
        allWarningsAsErrors.set(true)
    }
}

【Groovy】

task.named("compileKotlinJvm") {
    compilerOptions {
        allWarningsAsErrors = true
    }
}

To configure compiler options for a specific compilation, use the compilerOptions {} block within the compilation's task provider:

【Kotlin】

kotlin {
    jvm {
        compilations.named(KotlinCompilation.MAIN_COMPILATION_NAME) {
            compileTaskProvider.configure {
                // Configures the 'main' compilation:
                compilerOptions {
                    allWarningsAsErrors.set(true)
                }
            }
        }
    }
}

【Groovy】

kotlin {
    jvm {
        compilations.named(KotlinCompilation.MAIN_COMPILATION_NAME) {
            compileTaskProvider.configure {
                // Configures the 'main' compilation:
                compilerOptions {
                    allWarningsAsErrors = true
                }
            }
        }
    }
}

依赖项

The dependencies {} block of the source set declaration contains the dependencies of this source set.

Learn more about configuring dependencies.

There are four types of dependencies:

【Kotlin】

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

【Groovy】

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

Additionally, source sets can depend on each other and form a hierarchy. In this case, the dependsOn() relation 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 , for example, commonMainApi.

【Kotlin】

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

【Groovy】

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:

【Kotlin】

kotlin {
    sourceSets.all {
        languageSettings.apply {
            languageVersion = "2.1" // possible values: "1.8", "1.9", "2.0", "2.1"
            apiVersion = "2.1" // possible values: "1.8", "1.9", "2.0", "2.1"
            enableLanguageFeature("InlineClasses") // language feature name
            optIn("kotlin.ExperimentalUnsignedTypes") // annotation FQ-name
            progressiveMode = true // false by default
        }
    }
}

【Groovy】

kotlin {
    sourceSets.all {
        languageSettings {
            languageVersion = '2.1' // possible values: '1.8', '1.9', '2.0', '2.1'
            apiVersion = '2.1' // possible values: '1.8', '1.9', '2.0', '2.1'
            enableLanguageFeature('InlineClasses') // language feature name
            optIn('kotlin.ExperimentalUnsignedTypes') // annotation FQ-name
            progressiveMode = true // false by default
        }
    }
}