Справочник Kotlin Multiplatform Gradle DSL
Многоплатформенные проекты находятся в альфа-стадии. Функциональные возможности языка и инструменты могут измениться в будущих версиях Kotlin.
Плагин Kotlin Multiplatform Gradle предназначен для создания многоплатформенных проектов Kotlin. Здесь представлена справка по его содержимому; используйте её в качестве напоминания при написании скриптов сборки Gradle для многоплатформенных проектов Kotlin. Ознакомьтесь с концепциями многоплатформенных проектов Kotlin, а также с их созданием и настройкой.
Содержание
- Идентификатор и версия
- Блоки верхнего уровня
- Цели
- Наборы исходных кодов
- Сборки
- Зависимости
- Настройки языка
Идентификатор и версия
Полное квалифицированное имя плагина Kotlin Multiplatform Gradle — org.jetbrains.kotlin.multiplatform. Если вы используете Kotlin Gradle DSL, вы можете применить плагин с помощью kotlin(“multiplatform”). Версии плагина соответствуют версиям Kotlin. Самая последняя версия — 1.4.10.
plugins {
id 'org.jetbrains.kotlin.multiplatform' version '1.4.10'
}
plugins {
kotlin("multiplatform") version "1.4.10"
}
Блоки верхнего уровня
kotlin — это блок верхнего уровня для настройки многоплатформенного проекта в скрипте Gradle. Внутри kotlin, вы можете записать следующие блоки:
| Блок | Описание |
|---|---|
| <targetName> | Объявляет конкретную цель проекта. Названия доступных целей указаны в разделе Цели. |
targets | Все цели проекта. |
presets | Все предопределённые цели. Используйте это для одновременной настройки нескольких предопределённых целей. |
sourceSets | Настраивает предопределённые и объявляет настраиваемые наборы исходных кодов проекта. |
Цели
Цель — часть сборки, отвечающая за компиляцию, тестирование и упаковку программного обеспечения, предназначенного для одной из поддерживаемых платформ.
Каждая цель может иметь одну или несколько сборок. Помимо стандартных сборок для целей тестирования и производства, вы можете создать пользовательские сборки.
Цели многоплатформенного проекта описываются в соответствующих блоках в kotlin, например, jvm, android, iosArm64 . Полный список доступных целей:
| Имя | Описание |
|---|---|
jvm | Виртуальная машина Java |
js | JavaScript |
android | Android (APK) |
androidNativeArm32 | Android NDK на платформах ARM (ARM32) |
androidNativeArm64 | Android NDK на платформах ARM64 |
androidNativeX86 | Android NDK на платформах x86 |
androidNativeX64 | Android NDK на платформах x86_64 |
iosArm32 | Apple iOS на платформах ARM (ARM32) (Apple iPhone 5 и более ранние) |
iosArm64 | Apple iOS на платформах ARM64 (Apple iPhone 5s и более поздние) |
iosX64 | Симулятор Apple iOS 64-бит |
watchosArm32 | Apple watchOS на платформах ARM (ARM32) (Apple Watch Series 3 и более ранние) |
watchosArm64 | Apple watchOS на платформах ARM64_32 (Apple Watch Series 4 и более поздние) |
watchosX86 | Симулятор Apple watchOS |
tvosArm64 | Apple tvOS на платформах ARM64 (Apple TV 4-го поколения и более поздние) |
tvosX64 | Симулятор Apple tvOS |
linuxArm64 | Linux на платформах ARM64, например, Raspberry Pi |
linuxArm32Hfp | Linux на платформах ARM (ARM32) с поддержкой hard-float |
linuxMips32 | Linux на платформах MIPS |
linuxMipsel32 | Linux на платформах MIPS с little-endian (mipsel) |
linuxX64 | Linux на платформах x86_64 |
macosX64 | Apple macOS |
mingwX64 | 64-разрядная Microsoft Windows |
mingwX86 | 32-разрядная Microsoft Windows |
wasm32 | WebAssembly |
kotlin {
jvm()
iosX64()
macosX64()
js().browser()
}
Конфигурация цели может включать две части:
- Общая конфигурация, доступная для всех целей.
- Конфигурация, специфичная для цели.
Каждая цель может иметь одну или несколько сборок.
Общая конфигурация цели
В любом блоке цели вы можете использовать следующие объявления:
| Имя | Описание |
|---|---|
attributes | Атрибуты, используемые для различения целевых платформ для одной платформы. |
preset | Пресет, из которого была создана целевая платформа, если таковой имеется. |
platformType | Определяет Kotlin платформу для данной целевой платформы. Доступные значения: jvm, androidJvm, js, native, common. |
artifactsTaskName | Имя задачи, которая собирает результирующие артефакты данной целевой платформы. |
components | Компоненты, используемые для настройки публикаций Gradle. |
JVM целевые платформы
В дополнение к общей конфигурации целевых платформ, целевые платформы jvm имеют специфическую функцию:
| Имя | Описание |
|---|---|
withJava() | Включает Java исходники в компиляции JVM целевой платформы. |
Используйте эту функцию для проектов, содержащих как Java, так и Kotlin исходные файлы. Обратите внимание, что стандартные каталоги для Java исходных файлов не следуют умолчаниям Java плагина. Вместо этого, они выведены из Kotlin наборов исходных кодов. Например, если JVM целевая платформа имеет стандартное имя jvm, пути будут src/jvmMain/java (для Java исходников производства) и src/jvmTest/java для Java исходников тестирования. Узнайте, как включить Java исходные файлы в JVM компиляции.
kotlin {
jvm {
withJava()
}
}
JavaScript целевые платформы
Блок js описывает конфигурацию JavaScript целевых платформ. Он может содержать один из двух блоков в зависимости от среды выполнения целевой платформы:
| Имя | Описание |
|---|---|
browser | Конфигурация целевой платформы браузера. |
nodejs | Конфигурация целевой платформы Node.js. |
Узнайте больше о конфигурировании Kotlin/JS проектов.
Браузер
browser может содержать следующие блоки конфигурации:
| Имя | Описание |
|---|---|
testRuns | Конфигурация выполнения тестов. |
runTask | Конфигурация запуска проекта. |
webpackTask | Конфигурация сборки проекта с использованием Webpack. |
dceTask | Конфигурация исключения неиспользуемого кода. |
distribution | Путь к выходным файлам. |
kotlin {
js().browser {
webpackTask { /* ... */ }
testRuns { /* ... */ }
dceTask {
keep("myKotlinJsApplication.org.example.keepFromDce")
}
distribution {
directory = File("$projectDir/customdir/")
}
}
}
Node.js
nodejs может содержать конфигурации задач тестирования и запуска:
| Имя | Описание |
|---|---|
testRuns | Конфигурация выполнения тестов. |
runTask | Конфигурация запуска проекта. |
kotlin {
js().nodejs {
runTask { /* ... */ }
testRuns { /* ... */ }
}
}
Целевые платформы native
Для целевых платформ native доступны следующие специфические блоки:
| Имя | Описание |
|---|---|
binaries | Конфигурация бинарных файлов для создания. |
cinterops | Конфигурация взаимодействия с C библиотеками. |
Бинарные файлы
Существуют следующие виды бинарных файлов:
| Имя | Описание |
|---|---|
executable | Исполняемый файл продукта. |
test | Исполняемый файл теста. |
sharedLib | Динамическая библиотека. |
staticLib | Статическая библиотека. |
framework | Фреймворк Objective-C. |
kotlin {
linuxX64 { // Use your target instead.
binaries {
executable {
// Binary configuration.
}
}
}
}
Для конфигурации бинарных файлов доступны следующие параметры:
| Имя | Описание |
|---|---|
compilation | Компиляция, из которой создаётся бинарный файл. По умолчанию, бинарные файлы test основаны на компиляции test, в то время как другие бинарные файлы - на компиляции main. |
linkerOpts | Параметры, передаваемые системному линковщику во время сборки бинарных файлов. |
baseName | Пользовательское базовое имя для выходного файла. Имя итогового файла будет сформировано путём добавления зависящих от системы префикса и постфикса к этому базовому имени. |
entryPoint | Функция точки входа для исполняемых бинарных файлов. По умолчанию, это main() в корневом пакете. |
outputFile | Доступ к выходному файлу. |
linkTask | Доступ к задаче линковки. |
runTask | Доступ к задаче запуска для исполняемых бинарных файлов. Для целевых платформ, отличных от linuxX64, macosX64, или mingwX64, значение равно null. |
isStatic | Для Objective-C фреймворков. Включает статическую библиотеку вместо динамической. |
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
}
}
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
}
}
Узнайте больше о создании бинарных файлов native.
CInterops
cinterops — это набор описаний для взаимодействия с нативными библиотеками. Чтобы обеспечить взаимодействие с библиотекой, добавьте запись в cinterops и определите её параметры:
| Имя | Описание |
|---|---|
defFile |
Файл def описывающий нативный API. |
packageName | Префикс пакета для сгенерированного Kotlin API. |
compilerOpts | Параметры, передаваемые компилятору инструментом cinterop. |
includeDirs | Директории для поиска заголовков. |
Узнайте больше о конфигурации взаимодействия с нативными языками.
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 {
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
Плагин Kotlin multiplatform содержит две специфические функции для целевых платформ Android. Эти две функции помогут вам настроить варианты сборки:
| Имя | Описание |
|---|---|
publishLibraryVariants() | Указывает варианты сборки для публикации. Узнайте больше о публикации библиотек Android. |
publishAllLibraryVariants() | Опубликовывает все варианты сборки. |
kotlin {
android {
publishLibraryVariants("release", "debug")
}
}
Узнайте больше о компиляции для Android.
Настройка
androidвнутриkotlinне заменяет настройки сборки любого проекта Android. Узнайте больше о написании скриптов сборки для проектов Android в документации разработчика Android.
Наборы исходных кодов
Блок sourceSets описывает наборы исходных кодов проекта. Набор исходных кодов содержит Kotlin-файлы исходного кода, участвующие в компиляции вместе, вместе с их ресурсами, зависимостями и настройками языка.
Многоплатформенный проект содержит предопределённые наборы исходных кодов для своих целевых платформ; разработчики также могут создавать пользовательские наборы исходных кодов для своих потребностей.
Предопределённые наборы исходных кодов
Предопределённые наборы исходных кодов настраиваются автоматически при создании многоплатформенного проекта. Доступные предопределённые наборы исходных кодов:
| Имя | Описание |
|---|---|
commonMain | Код и ресурсы, общие для всех платформ. Доступны во всех многоплатформенных проектах. Используются во всех основных компиляциях проекта. |
commonTest | Тестовый код и ресурсы, общие для всех платформ. Доступны во всех многоплатформенных проектах. Используются во всех тестовых компиляциях проекта. |
| <targetName><compilationName> | Исходные коды, специфичные для целевой платформы, для компиляции. <targetName> — имя предопределённой целевой платформы, а <compilationName> — имя компиляции для этой целевой платформы. Примеры: jsTest, jvmMain. |
В Kotlin Gradle DSL разделы предопределённых наборов исходных кодов должны быть помечены by getting.
kotlin {
sourceSets {
commonMain { /* ... */ }
}
}
kotlin {
sourceSets {
val commonMain by getting { /* ... */ }
}
}
Узнайте больше о наборах исходных кодов.
Пользовательские наборы исходных кодов
Пользовательские наборы исходных кодов создаются разработчиками проекта вручную. Для создания пользовательского набора исходных кодов добавьте раздел с его именем внутри раздела sourceSets. При использовании Kotlin Gradle DSL пометьте пользовательские наборы исходных кодов by creating.
kotlin {
sourceSets {
myMain { /* ... */ } // create or configure a source set by the name 'myMain'
}
}
kotlin {
sourceSets {
val myMain by creating { /* ... */ } // create a new 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 {
val commonMain by getting {
kotlin.srcDir("src")
resources.srcDir("res")
dependencies {
/* ... */
}
}
}
}
Компиляции
Целевая платформа может иметь одну или несколько компиляций, например, для производства или тестирования. Существуют предопределённые компиляции, которые добавляются автоматически при создании целевой платформы. Вы также можете создать пользовательские компиляции.
Для ссылки на все или некоторые конкретные компиляции целевой платформы используйте коллекцию объектов compilations. Из compilations, вы можете обратиться к компиляции по её имени.
Узнайте больше о настройке компиляций.
Предопределённые компиляции
Предопределённые компиляции создаются автоматически для каждой целевой платформы проекта, за исключением целевых платформ Android. Доступные предопределённые компиляции:
| Имя | Описание |
|---|---|
main | Компиляция для исходных кодов производства. |
test | Компиляция для тестов. |
kotlin {
jvm {
compilations.main.output // get the main compilation output
compilations.test.runtimeDependencyFiles // get the test runtime classpath
}
}
kotlin {
jvm {
val main by compilations.getting {
output // get the main compilation output
}
compilations["test"].runtimeDependencyFiles // get the test runtime classpath
}
}
Пользовательские компиляции
Помимо предопределённых компиляций, вы можете создавать свои собственные пользовательские компиляции. Для создания пользовательской компиляции добавьте новый элемент в коллекцию compilations. При использовании Kotlin Gradle DSL пометьте пользовательские компиляции by creating.
Узнайте больше о создании пользовательской компиляции.
kotlin {
jvm() {
compilations.create('integrationTest') {
defaultSourceSet {
dependencies {
/* ... */
}
}
// Create a test task to run the tests produced by this compilation:
tasks.create('jvmIntegrationTest', Test) {
/* ... */
}
}
}
}
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") {
/* ... */
}
}
}
}
}
Параметры компиляции
Компиляция имеет следующие параметры:
| Имя | Описание |
|---|---|
defaultSourceSet | Набор исходных кодов по умолчанию для компиляции. |
kotlinSourceSets | Наборы исходных кодов, участвующие в компиляции. |
allKotlinSourceSets | Наборы исходных кодов, участвующие в компиляции, и их связи через dependsOn(). |
kotlinOptions | Параметры компилятора, применённые к компиляции. Список доступных параметров см. в параметрах компилятора. |
compileKotlinTask | Задача Gradle для компиляции Kotlin исходных кодов. |
compileKotlinTaskName | Имя compileKotlinTask. |
compileAllTaskName | Имя задачи Gradle для компиляции всех исходных кодов компиляции. |
output | Вывод компиляции. |
compileDependencyFiles | Файлы зависимостей времени компиляции (classpath) компиляции. |
runtimeDependencyFiles | Файлы зависимостей времени выполнения (classpath) компиляции. |
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 {
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
}
}
}
}
Зависимости
Блок dependencies объявления набора исходных данных содержит зависимости этого набора.
Подробнее о настройке зависимостей.
Существует четыре типа зависимостей:
| Имя | Описание |
|---|---|
api | Зависимости, используемые в API текущего модуля. |
implementation | Зависимости, используемые в модуле, но не экспортируемые за его пределы. |
compileOnly | Зависимости, используемые только для компиляции текущего модуля. |
runtimeOnly | Зависимости, доступные во время выполнения, но не видимые во время компиляции любого модуля. |
kotlin {
sourceSets {
commonMain {
dependencies {
api 'com.example:foo-metadata:1.0'
}
}
jvm6Main {
dependencies {
implementation 'com.example:foo-jvm6:1.0'
}
}
}
}
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")
}
}
}
}
Кроме того, наборы исходных данных могут зависеть друг от друга иерархически. В этом случае используется отношение dependsOn().
Зависимости наборов исходных данных также могут быть объявлены в верхнем уровневом блоке dependencies скрипта сборки. В этом случае их объявления следуют схеме <sourceSetName><DependencyKind>, например, commonMainApi.
dependencies {
commonMainApi 'com.example:foo-common:1.0'
jvm6MainApi 'com.example:foo-jvm6:1.0'
}
dependencies {
"commonMainApi"("com.example:foo-common:1.0")
"jvm6MainApi"("com.example:foo-jvm6:1.0")
}
Настройки языка
Блок languageSettings набора исходных данных определяет некоторые аспекты анализа проекта и сборки. Доступны следующие настройки языка:
| Имя | Описание |
|---|---|
languageVersion | Обеспечивает совместимость исходного кода с указанной версией Kotlin. |
apiVersion | Разрешает использовать объявления только из указанной версии связанных библиотек Kotlin. |
enableLanguageFeature | Включает указанную языковую функцию. Доступные значения соответствуют языковым функциям, которые в настоящее время являются экспериментальными или были введены как таковые в какой-то момент. |
useExperimentalAnnotation | Разрешает использование указанного аннотации opt-in. |
progressiveMode | Включает постепенный режим. |
kotlin {
sourceSets.all {
languageSettings {
languageVersion = '1.4' // possible values: '1.0', '1.1', '1.2', '1.3', '1.4'
apiVersion = '1.4' // possible values: '1.0', '1.1', '1.2', '1.3', '1.4'
enableLanguageFeature('InlineClasses') // language feature name
useExperimentalAnnotation('kotlin.ExperimentalUnsignedTypes') // annotation FQ-name
progressiveMode = true // false by default
}
}
}
kotlin {
sourceSets.all {
languageSettings.apply {
languageVersion = "1.4" // possible values: "1.0", "1.1", "1.2", "1.3", "1.4"
apiVersion = "1.4" // possible values: "1.0", "1.1", "1.2", "1.3", "1.4"
enableLanguageFeature("InlineClasses") // language feature name
useExperimentalAnnotation("kotlin.ExperimentalUnsignedTypes") // annotation FQ-name
progressiveMode = true // false by default
}
}
}
© 2010–2020 JetBrains s.r.o. and Kotlin Programming Language contributors
Licensed under the Apache License, Version 2.0.
https://kotlinlang.org/docs/reference/mpp-dsl-reference.html