Skip to content

多平台 Gradle DSL 參考

Kotlin 多平台 Gradle 外掛程式是建立 Kotlin 多平台專案的工具。 在此提供其內容參考;您可以在撰寫 Kotlin 多平台專案的 Gradle 建置指令碼時,將其作為提示使用。了解 Kotlin 多平台專案的概念、如何建立和設定它們

ID 與版本

Kotlin 多平台 Gradle 外掛程式的完全限定名稱為 org.jetbrains.kotlin.multiplatform。 如果您使用 Kotlin Gradle DSL,可以使用 kotlin("multiplatform") 來套用此外掛程式。 此外掛程式版本與 Kotlin 發行版本相符。最新版本為 2.2.0。

kotlin
plugins {
    kotlin("multiplatform") version "2.2.0"
}
groovy
plugins {
    id 'org.jetbrains.kotlin.multiplatform' version '2.2.0'
}

頂層區塊

kotlin {} 是 Gradle 建置指令碼中用於多平台專案配置的頂層區塊。 在 kotlin {} 內部,您可以撰寫以下區塊:

區塊描述
<targetName>宣告專案的特定目標。可用目標的名稱列於「目標」區段中。
targets列出專案的所有目標。
sourceSets設定預定義並宣告專案的自訂原始碼集
compilerOptions指定共同的擴充層級編譯器選項,這些選項將作為所有目標和共享原始碼集的預設值。

目標

目標 是建置的一部分,負責編譯、測試和打包針對其中一個支援平台的軟體。Kotlin 為每個平台提供目標,因此您可以指示 Kotlin 為該特定目標編譯程式碼。深入了解設定目標

每個目標可以有一個或多個編譯。除了用於測試和生產目的的預設編譯之外,您還可以建立自訂編譯

多平台專案的目標在 kotlin {} 內部對應的區塊中描述,例如 jvmandroidTargetiosArm64。 可用目標的完整列表如下:

目標平台目標備註
Kotlin/JVMjvm
Kotlin/WasmwasmJs如果您計畫在 JavaScript 執行時環境中執行專案,請使用此項。
wasmWasi如果您需要支援 WASI 系統介面,請使用此項。
Kotlin/JSjs

選擇執行環境:

  • browser {} 用於在瀏覽器中執行的應用程式。
  • nodejs {} 用於在 Node.js 上執行的應用程式。

設定 Kotlin/JS 專案中了解更多資訊。

Kotlin/Native

Kotlin/Native 目標支援中了解 macOS、Linux 和 Windows 主機目前支援的目標。

Android 應用程式與函式庫androidTarget

手動套用 Android Gradle 外掛程式:com.android.applicationcom.android.library

每個 Gradle 子專案只能建立一個 Android 目標。

建置期間,不支援目前主機的目標將被忽略,因此不會發佈。

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

目標的配置可以包含兩部分:

  • 適用於所有目標的共同配置
  • 目標特定配置。

每個目標可以有一個或多個編譯

共同目標配置

在任何目標區塊中,您可以使用以下宣告:

名稱描述
platformType此目標的 Kotlin 平台。可用值:jvmandroidJvmjswasmnativecommon
artifactsTaskName建置此目標結果產物的任務名稱。
components用於設定 Gradle 發佈的元件。
compilerOptions用於目標的編譯器選項。此宣告會覆寫在頂層配置的任何 compilerOptions {}

Web 目標

js {} 區塊描述 Kotlin/JS 目標的配置,而 wasmJs {} 區塊描述可與 JavaScript 互通的 Kotlin/Wasm 目標的配置。它們可以根據目標執行環境包含以下兩個區塊之一:

名稱描述
browser瀏覽器目標的配置。
nodejsNode.js 目標的配置。

深入了解配置 Kotlin/JS 專案

獨立的 wasmWasi {} 區塊描述支援 WASI 系統介面的 Kotlin/Wasm 目標的配置。 在這裡,只有 nodejs 執行環境可用:

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

所有 web 目標,jswasmJswasmWasi,也支援 binaries.executable() 呼叫。它明確地指示 Kotlin 編譯器發出可執行檔。如需更多資訊,請參閱 Kotlin/JS 文件中的執行環境

瀏覽器

browser {} 可以包含以下配置區塊:

名稱描述
testRuns測試執行的配置。
runTask專案執行的配置。
webpackTask使用 Webpack 捆綁專案的配置。
distribution輸出檔案的路徑。
kotlin
kotlin {
    js().browser {
        webpackTask { /* ... */ }
        testRuns { /* ... */ }
        distribution {
            directory = File("$projectDir/customdir/")
        }
    }
}

Node.js

nodejs {} 可以包含測試和執行任務的配置:

名稱描述
testRuns測試執行的配置。
runTask專案執行的配置。
kotlin
kotlin {
    js().nodejs {
        runTask { /* ... */ }
        testRuns { /* ... */ }
    }
}

原生目標

對於原生目標,提供以下特定區塊:

名稱描述
binaries要產生的二進位檔配置。
cinteropsC 函式庫互通的配置。

二進位檔

二進位檔有以下幾種:

名稱描述
executable產品可執行檔。
test測試可執行檔。
sharedLib共享函式庫。
staticLib靜態函式庫。
frameworkObjective-C 框架。
kotlin
kotlin {
    linuxX64 { // 請改用您的目標。
        binaries {
            executable {
                // 二進位檔配置。
            }
        }
    }
}

對於二進位檔配置,以下參數可用:

名稱描述
compilation建置二進位檔的編譯。預設情況下,test 二進位檔基於 test 編譯,而其他二進位檔則基於 main 編譯。
linkerOpts在二進位檔建置期間傳遞給系統連結器的選項。
baseName輸出檔案的自訂基本名稱。最終檔案名稱將透過向此基本名稱添加與系統相關的前綴和後綴來形成。
entryPoint可執行二進位檔的進入點函數。預設為根套件中的 main()
outputFile存取輸出檔案。
linkTask存取連結任務。
runTask存取可執行二進位檔的執行任務。對於 linuxX64macosX64mingwX64 以外的目標,其值為 null
isStatic適用於 Objective-C 框架。包含靜態函式庫而非動態函式庫。
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
    }
}

深入了解建置原生二進位檔

C 互通

cinterops 是與原生函式庫互通的描述集合。 要提供與函式庫的互通,請將一個條目添加到 cinterops 並定義其參數:

名稱描述
definitionFile描述原生 API 的 .def 檔案。
packageName生成的 Kotlin API 的套件前綴。
compilerOptscinterop 工具要傳遞給編譯器的選項。
includeDirs尋找標頭的目錄。
header要包含在綁定中的標頭。
headers要包含在綁定中的標頭列表。
kotlin
kotlin {
    linuxX64 { // Replace with a target you need.
        compilations.getByName("main") {
            val myInterop by cinterops.creating {
                // Definition file describing the native API.
                // The default path is src/nativeInterop/cinterop/<interop-name>.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<path> 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 {
                    // Definition file describing the native API.
                    // The default path is src/nativeInterop/cinterop/<interop-name>.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<path> 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 { /* ... */ }
            }
        }
    }
}

如需更多 cinterop 屬性,請參閱定義檔

Android 目標

Kotlin 多平台外掛程式具有特定功能,可協助您為 Android 目標配置建置變體

名稱描述
publishLibraryVariants()指定要發佈的建置變體。深入了解發佈 Android 函式庫
kotlin
kotlin {
    androidTarget {
        publishLibraryVariants("release")
    }
}

深入了解Android 的編譯

kotlin {} 區塊內的 androidTarget 配置不會取代任何 Android 專案的建置配置。 深入了解在 Android 開發者文件中撰寫 Android 專案的建置指令碼。

原始碼集

sourceSets {} 區塊描述專案的原始碼集。原始碼集包含一同參與編譯的 Kotlin 原始碼檔案,以及它們的資源和依賴項。

多平台專案包含其目標的預定義原始碼集;開發人員也可以根據需要建立自訂原始碼集

預定義原始碼集

預定義原始碼集在建立多平台專案時自動設定。 可用的預定義原始碼集如下:

名稱描述
commonMain在所有平台之間共享的程式碼和資源。在所有多平台專案中可用。用於專案的所有主要編譯
commonTest在所有平台之間共享的測試程式碼和資源。在所有多平台專案中可用。用於專案的所有測試編譯。
<targetName><compilationName>目標特定編譯的原始碼。<targetName> 是預定義目標的名稱,<compilationName> 是此目標編譯的名稱。範例:jsTestjvmMain
kotlin
kotlin {
    //...
    sourceSets {
        commonMain { /* ... */ }
    }
}
groovy
kotlin {
    //...
    sourceSets { 
        commonMain { /* ... */ }
    }
}

深入了解原始碼集

自訂原始碼集

自訂原始碼集由專案開發人員手動建立。 要建立自訂原始碼集,請在 sourceSets 區段內添加一個帶有其名稱的區段。 如果使用 Kotlin Gradle DSL,請將自訂原始碼集標記為 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' 
    }
}

請注意,新建立的原始碼集未與其他原始碼集連接。要在專案的編譯中使用它,請將其與其他原始碼集連接

原始碼集參數

原始碼集的配置儲存在 sourceSets {} 對應的區塊中。原始碼集具有以下參數:

名稱描述
kotlin.srcDir原始碼集目錄中 Kotlin 原始碼檔案的位置。
resources.srcDir原始碼集目錄中資源的位置。
dependsOn與另一個原始碼集的連接
dependencies原始碼集的依賴項
languageSettings應用於共享原始碼集的語言設定
kotlin
kotlin { 
    //...
    sourceSets { 
        commonMain {
            kotlin.srcDir("src")
            resources.srcDir("res")

            dependencies {
                /* ... */
            }
        }
    }
}
groovy
kotlin { 
    //...
    sourceSets { 
        commonMain {
            kotlin.srcDir('src')
            resources.srcDir('res')

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

編譯

一個目標可以有一個或多個編譯,例如,用於生產或測試。有預定義的編譯在目標建立時自動添加。您還可以額外建立自訂編譯

要引用目標的所有或某些特定編譯,請使用 compilations 物件集合。 從 compilations 中,您可以按名稱引用編譯。

深入了解配置編譯

預定義編譯

預定義編譯會為專案的每個目標自動建立,Android 目標除外。 可用的預定義編譯如下:

名稱描述
main用於生產原始碼的編譯。
test用於測試的編譯。
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
    }
}

自訂編譯

除了預定義編譯之外,您還可以建立自己的自訂編譯。 為此,請在新的編譯和 main 編譯之間建立 associateWith 關係。如果您使用 Kotlin Gradle DSL,請將自訂編譯標記為 by creating

kotlin
kotlin {
    jvm {
        compilations {
            val main by getting
            val integrationTest by creating {
                // Import main and its classpath as dependencies and establish internal visibility
                associateWith(main)
                defaultSourceSet {
                    dependencies {
                        implementation(kotlin("test-junit"))
                        /* ... */
                    }
                }

                // Create a test task to run the tests produced by this compilation
                testRuns.create("integration") {
                    // Configure the test task
                    setExecutionSourceFrom(integrationTest)
                }
            }
        }
    }
}
groovy
kotlin {
    jvm {
        compilations.create('integrationTest') {
            def main = compilations.main
            // Import main and its classpath as dependencies and establish internal visibility
            associateWith(main)
            defaultSourceSet {
                dependencies {
                    implementation kotlin('test-junit')
                    /* ... */
                }
            }

            // Create a test task to run the tests produced by this compilation
            testRuns.create('integration') {
                // Configure the test task
                setExecutionSourceFrom(compilations.integrationTest)
            }
        }
    }
}

透過關聯編譯,您可以將主要編譯輸出添加為依賴項,並在編譯之間建立 internal 可見性。

深入了解建立自訂編譯

編譯參數

一個編譯具有以下參數:

名稱描述
defaultSourceSet編譯的預設原始碼集。
kotlinSourceSets參與編譯的原始碼集。
allKotlinSourceSets參與編譯的原始碼集及其透過 dependsOn() 的連接。
compilerOptions應用於編譯的編譯器選項。有關可用選項的列表,請參閱編譯器選項
compileKotlinTask編譯 Kotlin 原始碼的 Gradle 任務。
compileKotlinTaskNamecompileKotlinTask 的名稱。
compileAllTaskName編譯編譯所有原始碼的 Gradle 任務名稱。
output編譯輸出。
compileDependencyFiles編譯的編譯時依賴檔案(classpath)。對於所有 Kotlin/Native 編譯,這會自動包含標準函式庫和平台依賴項。
runtimeDependencyFiles編譯的運行時依賴檔案(classpath)。
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
    }
}

編譯器選項

您可以在專案中配置三個不同層級的編譯器選項:

  • 擴充層級:在 kotlin {} 區塊中。
  • 目標層級:在目標區塊中。
  • 編譯單元層級:通常在特定的編譯任務中。

Kotlin compiler options levels

較高層級的設定作為較低層級的預設值:

  • 在擴充層級設定的編譯器選項是目標層級選項的預設值,包括 commonMainnativeMaincommonTest 等共享原始碼集。
  • 在目標層級設定的編譯器選項是編譯單元(任務)層級選項的預設值,例如 compileKotlinJvmcompileTestKotlinJvm 任務。

較低層級的配置會覆寫較高層級的類似設定:

  • 任務層級的編譯器選項會覆寫目標或擴充層級的類似設定。
  • 目標層級的編譯器選項會覆寫擴充層級的類似設定。

有關可能的編譯器選項列表,請參閱所有編譯器選項

擴充層級

要為專案中的所有目標配置編譯器選項,請在頂層使用 compilerOptions {} 區塊:

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

目標層級

要為專案中的特定目標配置編譯器選項,請在目標區塊內使用 compilerOptions {} 區塊:

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

編譯單元層級

要為特定任務配置編譯器選項,請在任務內部使用 compilerOptions {} 區塊:

kotlin
task.named<KotlinJvmCompile>("compileKotlinJvm") {
    compilerOptions {
        allWarningsAsErrors.set(true)
    }
}
groovy
task.named<KotlinJvmCompile>("compileKotlinJvm") {
    compilerOptions {
        allWarningsAsErrors = true
    }
}

要為特定編譯配置編譯器選項,請在編譯的任務提供者中,使用 compilerOptions {} 區塊:

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

kotlinOptions {} 遷移到 compilerOptions {}

在 Kotlin 2.2.0 之前,您可以使用 kotlinOptions {} 區塊配置編譯器選項。由於 kotlinOptions {} 區塊在 Kotlin 2.2.0 中已棄用,您需要在建置指令碼中使用 compilerOptions {} 區塊。 有關更多資訊,請參閱kotlinOptions{} 遷移到 compilerOptions{}

依賴項

原始碼集宣告的 dependencies {} 區塊包含此原始碼集的依賴項。

深入了解配置依賴項

依賴項有四種類型:

名稱描述
api在目前模組的 API 中使用的依賴項。
implementation在模組中使用但未向外部公開的依賴項。
compileOnly僅用於目前模組編譯的依賴項。
runtimeOnly在運行時可用但在任何模組編譯期間不可見的依賴項。
kotlin
kotlin {
    //...
    sourceSets {
        commonMain {
            dependencies {
                api("com.example:foo-metadata:1.0")
            }
        }
        jvmMain {
            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'
            }
        }
    }
}

此外,原始碼集可以相互依賴並形成層次結構。 在這種情況下,使用 dependsOn() 關係。

語言設定

原始碼集中的 languageSettings {} 區塊定義了專案分析和編譯的某些方面。僅當設定專門適用於共享原始碼集時,才使用 languageSettings {} 區塊。對於所有其他情況,請使用 compilerOptions {} 區塊在擴充或目標層級配置編譯器選項

以下語言設定可用:

名稱描述
languageVersion提供與指定 Kotlin 版本相容的原始碼。
apiVersion允許僅使用指定 Kotlin 捆綁函式庫版本中的宣告。
enableLanguageFeature啟用指定的語言功能。可用值對應於目前實驗性或在某個時候引入的語言功能。
optIn允許使用指定的選擇性加入註解
progressiveMode啟用漸進模式
kotlin
kotlin {
    sourceSets.all {
        languageSettings.apply {
            languageVersion = "2.2" // possible values: "1.8", "1.9", "2.0", "2.1"
            apiVersion = "2.2" // 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.2' // possible values: '1.8', '1.9', '2.0', '2.1'
            apiVersion = '2.2' // 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
        }
    }
}