多平台 Gradle DSL 參考
Kotlin 多平台 Gradle 外掛程式是建立 Kotlin 多平台專案的工具。 在此提供其內容參考;您可以在撰寫 Kotlin 多平台專案的 Gradle 建置指令碼時,將其作為提示使用。了解 Kotlin 多平台專案的概念、如何建立和設定它們。
ID 與版本
Kotlin 多平台 Gradle 外掛程式的完全限定名稱為 org.jetbrains.kotlin.multiplatform
。 如果您使用 Kotlin Gradle DSL,可以使用 kotlin("multiplatform")
來套用此外掛程式。 此外掛程式版本與 Kotlin 發行版本相符。最新版本為 2.2.0。
plugins {
kotlin("multiplatform") version "2.2.0"
}
plugins {
id 'org.jetbrains.kotlin.multiplatform' version '2.2.0'
}
頂層區塊
kotlin {}
是 Gradle 建置指令碼中用於多平台專案配置的頂層區塊。 在 kotlin {}
內部,您可以撰寫以下區塊:
區塊 | 描述 |
---|---|
<targetName> | 宣告專案的特定目標。可用目標的名稱列於「目標」區段中。 |
targets | 列出專案的所有目標。 |
sourceSets | 設定預定義並宣告專案的自訂原始碼集。 |
compilerOptions | 指定共同的擴充層級編譯器選項,這些選項將作為所有目標和共享原始碼集的預設值。 |
目標
目標 是建置的一部分,負責編譯、測試和打包針對其中一個支援平台的軟體。Kotlin 為每個平台提供目標,因此您可以指示 Kotlin 為該特定目標編譯程式碼。深入了解設定目標。
每個目標可以有一個或多個編譯。除了用於測試和生產目的的預設編譯之外,您還可以建立自訂編譯。
多平台專案的目標在 kotlin {}
內部對應的區塊中描述,例如 jvm
、androidTarget
、iosArm64
。 可用目標的完整列表如下:
目標平台 | 目標 | 備註 |
---|---|---|
Kotlin/JVM | jvm | |
Kotlin/Wasm | wasmJs | 如果您計畫在 JavaScript 執行時環境中執行專案,請使用此項。 |
wasmWasi | 如果您需要支援 WASI 系統介面,請使用此項。 | |
Kotlin/JS | js | 選擇執行環境:
在設定 Kotlin/JS 專案中了解更多資訊。 |
Kotlin/Native | 在Kotlin/Native 目標支援中了解 macOS、Linux 和 Windows 主機目前支援的目標。 | |
Android 應用程式與函式庫 | androidTarget | 手動套用 Android Gradle 外掛程式: 每個 Gradle 子專案只能建立一個 Android 目標。 |
建置期間,不支援目前主機的目標將被忽略,因此不會發佈。
kotlin {
jvm()
iosArm64()
macosX64()
js().browser()
}
目標的配置可以包含兩部分:
- 適用於所有目標的共同配置。
- 目標特定配置。
每個目標可以有一個或多個編譯。
共同目標配置
在任何目標區塊中,您可以使用以下宣告:
名稱 | 描述 |
---|---|
platformType | 此目標的 Kotlin 平台。可用值:jvm 、androidJvm 、js 、wasm 、native 、common 。 |
artifactsTaskName | 建置此目標結果產物的任務名稱。 |
components | 用於設定 Gradle 發佈的元件。 |
compilerOptions | 用於目標的編譯器選項。此宣告會覆寫在頂層配置的任何 compilerOptions {} 。 |
Web 目標
js {}
區塊描述 Kotlin/JS 目標的配置,而 wasmJs {}
區塊描述可與 JavaScript 互通的 Kotlin/Wasm 目標的配置。它們可以根據目標執行環境包含以下兩個區塊之一:
名稱 | 描述 |
---|---|
browser | 瀏覽器目標的配置。 |
nodejs | Node.js 目標的配置。 |
深入了解配置 Kotlin/JS 專案。
獨立的 wasmWasi {}
區塊描述支援 WASI 系統介面的 Kotlin/Wasm 目標的配置。 在這裡,只有 nodejs
執行環境可用:
kotlin {
wasmWasi {
nodejs()
binaries.executable()
}
}
所有 web 目標,js
、wasmJs
和 wasmWasi
,也支援 binaries.executable()
呼叫。它明確地指示 Kotlin 編譯器發出可執行檔。如需更多資訊,請參閱 Kotlin/JS 文件中的執行環境。
瀏覽器
browser {}
可以包含以下配置區塊:
名稱 | 描述 |
---|---|
testRuns | 測試執行的配置。 |
runTask | 專案執行的配置。 |
webpackTask | 使用 Webpack 捆綁專案的配置。 |
distribution | 輸出檔案的路徑。 |
kotlin {
js().browser {
webpackTask { /* ... */ }
testRuns { /* ... */ }
distribution {
directory = File("$projectDir/customdir/")
}
}
}
Node.js
nodejs {}
可以包含測試和執行任務的配置:
名稱 | 描述 |
---|---|
testRuns | 測試執行的配置。 |
runTask | 專案執行的配置。 |
kotlin {
js().nodejs {
runTask { /* ... */ }
testRuns { /* ... */ }
}
}
原生目標
對於原生目標,提供以下特定區塊:
名稱 | 描述 |
---|---|
binaries | 要產生的二進位檔配置。 |
cinterops | 與 C 函式庫互通的配置。 |
二進位檔
二進位檔有以下幾種:
名稱 | 描述 |
---|---|
executable | 產品可執行檔。 |
test | 測試可執行檔。 |
sharedLib | 共享函式庫。 |
staticLib | 靜態函式庫。 |
framework | Objective-C 框架。 |
kotlin {
linuxX64 { // 請改用您的目標。
binaries {
executable {
// 二進位檔配置。
}
}
}
}
對於二進位檔配置,以下參數可用:
名稱 | 描述 |
---|---|
compilation | 建置二進位檔的編譯。預設情況下,test 二進位檔基於 test 編譯,而其他二進位檔則基於 main 編譯。 |
linkerOpts | 在二進位檔建置期間傳遞給系統連結器的選項。 |
baseName | 輸出檔案的自訂基本名稱。最終檔案名稱將透過向此基本名稱添加與系統相關的前綴和後綴來形成。 |
entryPoint | 可執行二進位檔的進入點函數。預設為根套件中的 main() 。 |
outputFile | 存取輸出檔案。 |
linkTask | 存取連結任務。 |
runTask | 存取可執行二進位檔的執行任務。對於 linuxX64 、macosX64 或 mingwX64 以外的目標,其值為 null 。 |
isStatic | 適用於 Objective-C 框架。包含靜態函式庫而非動態函式庫。 |
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
}
}
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 的套件前綴。 |
compilerOpts | cinterop 工具要傳遞給編譯器的選項。 |
includeDirs | 尋找標頭的目錄。 |
header | 要包含在綁定中的標頭。 |
headers | 要包含在綁定中的標頭列表。 |
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 { /* ... */ }
}
}
}
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 {
androidTarget {
publishLibraryVariants("release")
}
}
深入了解Android 的編譯。
kotlin {}
區塊內的androidTarget
配置不會取代任何 Android 專案的建置配置。 深入了解在 Android 開發者文件中撰寫 Android 專案的建置指令碼。
原始碼集
sourceSets {}
區塊描述專案的原始碼集。原始碼集包含一同參與編譯的 Kotlin 原始碼檔案,以及它們的資源和依賴項。
多平台專案包含其目標的預定義原始碼集;開發人員也可以根據需要建立自訂原始碼集。
預定義原始碼集
預定義原始碼集在建立多平台專案時自動設定。 可用的預定義原始碼集如下:
名稱 | 描述 |
---|---|
commonMain | 在所有平台之間共享的程式碼和資源。在所有多平台專案中可用。用於專案的所有主要編譯。 |
commonTest | 在所有平台之間共享的測試程式碼和資源。在所有多平台專案中可用。用於專案的所有測試編譯。 |
<targetName><compilationName> | 目標特定編譯的原始碼。<targetName> 是預定義目標的名稱,<compilationName> 是此目標編譯的名稱。範例:jsTest 、jvmMain 。 |
kotlin {
//...
sourceSets {
commonMain { /* ... */ }
}
}
kotlin {
//...
sourceSets {
commonMain { /* ... */ }
}
}
深入了解原始碼集。
自訂原始碼集
自訂原始碼集由專案開發人員手動建立。 要建立自訂原始碼集,請在 sourceSets
區段內添加一個帶有其名稱的區段。 如果使用 Kotlin Gradle DSL,請將自訂原始碼集標記為 by creating
。
kotlin {
//...
sourceSets {
val myMain by creating { /* ... */ } // create a new source set by the name 'MyMain'
}
}
kotlin {
//...
sourceSets {
myMain { /* ... */ } // create or configure a source set by the name 'myMain'
}
}
請注意,新建立的原始碼集未與其他原始碼集連接。要在專案的編譯中使用它,請將其與其他原始碼集連接。
原始碼集參數
原始碼集的配置儲存在 sourceSets {}
對應的區塊中。原始碼集具有以下參數:
名稱 | 描述 |
---|---|
kotlin.srcDir | 原始碼集目錄中 Kotlin 原始碼檔案的位置。 |
resources.srcDir | 原始碼集目錄中資源的位置。 |
dependsOn | 與另一個原始碼集的連接。 |
dependencies | 原始碼集的依賴項。 |
languageSettings | 應用於共享原始碼集的語言設定。 |
kotlin {
//...
sourceSets {
commonMain {
kotlin.srcDir("src")
resources.srcDir("res")
dependencies {
/* ... */
}
}
}
}
kotlin {
//...
sourceSets {
commonMain {
kotlin.srcDir('src')
resources.srcDir('res')
dependencies {
/* ... */
}
}
}
}
編譯
一個目標可以有一個或多個編譯,例如,用於生產或測試。有預定義的編譯在目標建立時自動添加。您還可以額外建立自訂編譯。
要引用目標的所有或某些特定編譯,請使用 compilations
物件集合。 從 compilations
中,您可以按名稱引用編譯。
深入了解配置編譯。
預定義編譯
預定義編譯會為專案的每個目標自動建立,Android 目標除外。 可用的預定義編譯如下:
名稱 | 描述 |
---|---|
main | 用於生產原始碼的編譯。 |
test | 用於測試的編譯。 |
kotlin {
jvm {
val main by compilations.getting {
output // get the main compilation output
}
compilations["test"].runtimeDependencyFiles // get the test runtime classpath
}
}
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 {
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)
}
}
}
}
}
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 任務。 |
compileKotlinTaskName | compileKotlinTask 的名稱。 |
compileAllTaskName | 編譯編譯所有原始碼的 Gradle 任務名稱。 |
output | 編譯輸出。 |
compileDependencyFiles | 編譯的編譯時依賴檔案(classpath)。對於所有 Kotlin/Native 編譯,這會自動包含標準函式庫和平台依賴項。 |
runtimeDependencyFiles | 編譯的運行時依賴檔案(classpath)。 |
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)
}
}
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 {}
區塊中。 - 目標層級:在目標區塊中。
- 編譯單元層級:通常在特定的編譯任務中。
較高層級的設定作為較低層級的預設值:
- 在擴充層級設定的編譯器選項是目標層級選項的預設值,包括
commonMain
、nativeMain
和commonTest
等共享原始碼集。 - 在目標層級設定的編譯器選項是編譯單元(任務)層級選項的預設值,例如
compileKotlinJvm
和compileTestKotlinJvm
任務。
較低層級的配置會覆寫較高層級的類似設定:
- 任務層級的編譯器選項會覆寫目標或擴充層級的類似設定。
- 目標層級的編譯器選項會覆寫擴充層級的類似設定。
有關可能的編譯器選項列表,請參閱所有編譯器選項。
擴充層級
要為專案中的所有目標配置編譯器選項,請在頂層使用 compilerOptions {}
區塊:
kotlin {
// Configures all compilations of all targets
compilerOptions {
allWarningsAsErrors.set(true)
}
}
kotlin {
// Configures all compilations of all targets:
compilerOptions {
allWarningsAsErrors = true
}
}
目標層級
要為專案中的特定目標配置編譯器選項,請在目標區塊內使用 compilerOptions {}
區塊:
kotlin {
jvm {
// Configures all compilations of the JVM target
compilerOptions {
allWarningsAsErrors.set(true)
}
}
}
kotlin {
jvm {
// Configures all compilations of the JVM target
compilerOptions {
allWarningsAsErrors = true
}
}
}
編譯單元層級
要為特定任務配置編譯器選項,請在任務內部使用 compilerOptions {}
區塊:
task.named<KotlinJvmCompile>("compileKotlinJvm") {
compilerOptions {
allWarningsAsErrors.set(true)
}
}
task.named<KotlinJvmCompile>("compileKotlinJvm") {
compilerOptions {
allWarningsAsErrors = true
}
}
要為特定編譯配置編譯器選項,請在編譯的任務提供者中,使用 compilerOptions {}
區塊:
kotlin {
jvm {
compilations.named(KotlinCompilation.MAIN_COMPILATION_NAME) {
compileTaskProvider.configure {
// Configures the 'main' compilation:
compilerOptions {
allWarningsAsErrors.set(true)
}
}
}
}
}
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 {
//...
sourceSets {
commonMain {
dependencies {
api("com.example:foo-metadata:1.0")
}
}
jvmMain {
dependencies {
implementation("com.example:foo-jvm:1.0")
}
}
}
}
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 {
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
}
}
}
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
}
}
}