Справочник по Gradle DSL для многоплатформенных проектов
Плагин Kotlin Multiplatform Gradle — инструмент для создания многоплатформенных проектов Kotlin. Здесь вы найдете справку по его содержимому; используйте ее в качестве напоминания при написании скриптов сборки Gradle для многоплатформенных проектов Kotlin. Ознакомьтесь с концепциями многоплатформенных проектов Kotlin, как их создать и настроить.
Идентификатор и версия
Полное имя плагина Kotlin Multiplatform Gradle — org.jetbrains.kotlin.multiplatform. Если вы используете Kotlin Gradle DSL, вы можете применить плагин с помощью kotlin("multiplatform"). Версии плагина соответствуют версиям Kotlin. Самая последняя версия — 1.7.20.
plugins {
kotlin("multiplatform") version "1.7.20"
}
plugins {
id 'org.jetbrains.kotlin.multiplatform' version '1.7.20'
}
Основные блоки
kotlin — это основной блок для настройки многоплатформенного проекта в скрипте сборки Gradle. Внутри kotlin, вы можете записать следующие блоки:
Блок |
Описание |
|---|---|
<targetName> |
Объявляет конкретную цель проекта. Имена доступных целей перечислены в разделе Цели. |
|
Все цели проекта. |
|
Все предопределенные цели. Используйте для настройки нескольких предопределенных целей одновременно. |
|
Настраивает предопределенные и объявляет пользовательские наборы исходных данных проекта. |
Цели
Цель является частью сборки, ответственной за компиляцию, тестирование и упаковку программного обеспечения, предназначенного для одной из поддерживаемых платформ. Kotlin предоставляет предустановленные цели для каждой платформы. Узнайте, как использовать предустановленную цель.
Каждая цель может иметь одну или несколько компиляций. В дополнение к компиляциям по умолчанию для тестирования и производственных целей, вы можете создать пользовательские компиляции.
Цели многоплатформенного проекта описываются в соответствующих блоках внутри kotlin, например, jvm, android, iosArm64. Полный список доступных целей следующий:
Платформа цели |
Предустановка цели |
Комментарии |
|---|---|---|
Kotlin/JVM |
|
|
Kotlin/JS |
|
Выберите среду выполнения:
Узнайте больше в Настройка проекта Kotlin/JS. |
Приложения и библиотеки для Android |
|
Вручную примените плагин Android Gradle – Вы можете создать только одну цель Android на подпроект Gradle. |
Android NDK |
|
Для 64-разрядной цели требуется хост Linux или macOS. Вы можете собрать 32-разрядную цель на любом поддерживаемом хосте. |
iOS |
|
Требуется хост macOS с установленным Xcode и его инструментами командной строки. |
watchOS |
|
Требуется хост macOS с установленным Xcode и его инструментами командной строки. |
tvOS |
|
Требуется хост macOS с установленным Xcode и его инструментами командной строки. |
macOS |
|
Требуется хост macOS с установленным Xcode и его инструментами командной строки. |
Linux |
|
Для целей Linux MIPS ( Вы можете собрать другие цели Linux на любом поддерживаемом хосте. |
Windows |
|
|
WebAssembly |
|
kotlin {
jvm()
iosX64()
macosX64()
js().browser()
}
Конфигурация цели может включать две части:
Общая конфигурация, доступная для всех целей.
Конфигурация, специфичная для цели.
Каждая цель может иметь одну или несколько компиляций.
Общая конфигурация цели
В любом блоке цели вы можете использовать следующие объявления:
Имя |
Описание |
|---|---|
|
Атрибуты, используемые для различения целей для одной платформы. |
|
Предустановка, из которой была создана цель, если таковая имеется. |
|
Обозначает платформу Kotlin этой цели. Доступные значения: |
|
Имя задачи, которая создает результирующие артефакты этой цели. |
|
Компоненты, используемые для настройки публикаций Gradle. |
Цели JVM
В дополнение к общей конфигурации цели, jvm цели имеют специфическую функцию:
Имя |
Описание |
|---|---|
|
Включает 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-целей. Он может содержать один из двух блоков в зависимости от среды выполнения целевой задачи:
Имя |
Описание |
|---|---|
|
Конфигурация целевой задачи браузера. |
|
Конфигурация целевой задачи Node.js. |
Узнайте больше о конфигурировании Kotlin/JS-проектов.
Браузер
browser может содержать следующие блоки конфигурации:
Имя |
Описание |
|---|---|
|
Конфигурация выполнения тестов. |
|
Конфигурация запуска проекта. |
|
Конфигурация сборки проекта с помощью Webpack. |
|
Конфигурация удаления неиспользуемого кода. |
|
Путь к выходным файлам. |
kotlin {
js().browser {
webpackTask { /* ... */ }
testRuns { /* ... */ }
dceTask {
keep("myKotlinJsApplication.org.example.keepFromDce")
}
distribution {
directory = File("$projectDir/customdir/")
}
}
}
Node.js
nodejs может содержать конфигурации задач тестирования и запуска:
Имя |
Описание |
|---|---|
|
Конфигурация выполнения тестов. |
|
Конфигурация запуска проекта. |
kotlin {
js().nodejs {
runTask { /* ... */ }
testRuns { /* ... */ }
}
}
Цели нативных платформ
Для нативных целей доступны следующие специфические блоки:
Имя |
Описание |
|---|---|
|
Конфигурация бинарных файлов для создания. |
|
Конфигурация взаимодействия с C-библиотеками. |
Бинарные файлы
Существуют следующие типы бинарных файлов:
Имя |
Описание |
|---|---|
|
Исполняемый файл продукта. |
|
Исполняемый файл теста. |
|
Динамическая библиотека. |
|
Статическая библиотека. |
|
Фреймворк Objective-C. |
kotlin {
linuxX64 { // Use your target instead.
binaries {
executable {
// Binary configuration.
}
}
}
}
Для конфигурации бинарных файлов доступны следующие параметры:
Имя |
Описание |
|---|---|
|
Компиляция, из которой создаётся бинарный файл. По умолчанию, бинарные файлы |
|
Опции, передаваемые системному линковщику во время создания бинарного файла. |
|
Пользовательское базовое имя для выходного файла. Имя конечного файла будет сформировано путём добавления системно-зависимого префикса и постфикса к этому базовому имени. |
|
Функция точки входа для исполняемых бинарных файлов. По умолчанию, это |
|
Доступ к выходному файлу. |
|
Доступ к задаче линковки. |
|
Доступ к задаче запуска для исполняемых бинарных файлов. Для целей, отличных от |
|
Для фреймворков 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
}
}
Узнайте больше о создании нативных бинарных файлов.
CInterops
cinterops — это набор описаний для взаимодействия с нативными библиотеками. Чтобы обеспечить взаимодействие с библиотекой, добавьте запись в cinterops и определите её параметры:
Имя |
Описание |
|---|---|
|
Файл |
|
Префикс пакета для сгенерированного Kotlin API. |
|
Опции для передачи компилятору инструментом cinterop. |
|
Каталоги для поиска заголовков. |
Узнайте больше о том, как настроить взаимодействие с нативными языками.
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 { /* ... */ }
}
}
}
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 { /* ... */ }
}
}
}
}
Цели Android
Плагин Kotlin Multiplatform содержит две специальные функции для целей Android. Две функции помогают настроить варианты сборки:
Имя |
Описание |
|---|---|
|
Указывает варианты сборки для публикации. Узнайте больше о публикации библиотек Android. |
|
Опубликовывает все варианты сборки. |
kotlin {
android {
publishLibraryVariants("release", "debug")
}
}
Узнайте больше о компиляции для Android.
Наборы исходных кодов
Блок sourceSets описывает наборы исходных кодов проекта. Набор исходных кодов содержит файлы Kotlin исходного кода, которые участвуют в компиляции вместе, а также их ресурсы, зависимости и параметры языка.
Проект multiplatform содержит предопределенные наборы исходных кодов для своих целей; разработчики также могут создавать пользовательские наборы исходных кодов для своих нужд.
Предопределенные наборы исходных кодов
Предопределенные наборы исходных кодов автоматически настраиваются при создании проекта multiplatform. Доступные предопределенные наборы исходных кодов:
Имя |
Описание |
|---|---|
|
Код и ресурсы, общие для всех платформ. Доступны во всех проектах multiplatform. Используются во всех основных компиляциях проекта. |
|
Тестовый код и ресурсы, общие для всех платформ. Доступны во всех проектах multiplatform. Используются во всех тестовых компиляциях проекта. |
<targetName><compilationName> |
Источники, специфичные для целевой платформы, для компиляции. <targetName> — имя предопределенной цели, <compilationName> — имя компиляции для этой цели. Примеры: |
В Kotlin Gradle DSL разделы предопределенных наборов исходных кодов должны быть помечены by getting.
kotlin {
sourceSets {
val commonMain by getting { /* ... */ }
}
}
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 исходного кода в каталоге набора исходных кодов. |
|
Расположение ресурсов в каталоге набора исходных кодов. |
|
|
|
Зависимости набора исходных кодов. |
|
Настройки языка, применяемые к набору исходных кодов. |
kotlin {
sourceSets {
val commonMain by getting {
kotlin.srcDir("src")
resources.srcDir("res")
dependencies {
/* ... */
}
}
}
}
kotlin {
sourceSets {
commonMain {
kotlin.srcDir('src')
resources.srcDir('res')
dependencies {
/* ... */
}
}
}
}
Компиляции
Цель может иметь одну или несколько компиляций, например, для производства или тестирования. Существуют предварительно определённые компиляции, которые добавляются автоматически при создании цели. Вы также можете создать собственные компиляции.
Для обращения ко всем или к некоторым конкретным компиляциям цели используйте коллекцию объектов compilations. Из compilations, вы можете обратиться к компиляции по её имени.
Узнайте больше о настройке компиляций.
Предварительно определённые компиляции
Предварительно определённые компиляции создаются автоматически для каждой цели проекта, за исключением целей для Android. Доступные предварительно определённые компиляции:
Имя |
Описание |
|---|---|
|
Компиляция для исходных кодов производства. |
|
Компиляция для тестов. |
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
}
}
Пользовательские компиляции
В дополнение к предварительно определённым компиляциям вы можете создать собственные пользовательские компиляции. Для создания пользовательской компиляции добавьте новый элемент в коллекцию compilations. При использовании Kotlin Gradle DSL помечайте пользовательские компиляции by creating.
Узнайте больше о создании пользовательской компиляции.
kotlin {
jvm() {
compilations {
val integrationTest by compilations.creating {
defaultSourceSet {
dependencies {
/* ... */
}
}
// Create a test task to run the tests produced by this compilation:
tasks.register<Test>("integrationTest") {
/* ... */
}
}
}
}
}
kotlin {
jvm() {
compilations.create('integrationTest') {
defaultSourceSet {
dependencies {
/* ... */
}
}
// Create a test task to run the tests produced by this compilation:
tasks.register('jvmIntegrationTest', Test) {
/* ... */
}
}
}
}
Параметры компиляции
Компиляция имеет следующие параметры:
Имя |
Описание |
|---|---|
|
Набор исходных файлов по умолчанию компиляции. |
|
Наборы исходных файлов, участвующих в компиляции. |
|
Наборы исходных файлов, участвующие в компиляции, и их связи через |
|
Параметры компилятора, применяемые к компиляции. Список доступных параметров см. в Параметрах компилятора. |
|
Задача Gradle для компиляции исходных кодов Kotlin. |
|
Имя |
|
Имя задачи Gradle для компиляции всех исходных кодов компиляции. |
|
Вывод компиляции. |
|
Файлы зависимостей времени компиляции (classpath) компиляции. |
|
Файлы зависимостей времени выполнения (classpath) компиляции. |
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
}
}
}
}
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
}
}
}
}
Зависимости
Блок dependencies объявления набора исходных файлов содержит зависимости этого набора исходных файлов.
Узнайте больше о настройке зависимостей.
Существует четыре типа зависимостей:
Имя |
Описание |
|---|---|
|
Зависимости, используемые в API текущего модуля. |
|
Зависимости, используемые в модуле, но не экспонируемые за его пределы. |
|
Зависимости, используемые только для компиляции текущего модуля. |
|
Зависимости, доступные во время выполнения, но невидимые во время компиляции любого модуля. |
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")
}
}
}
}
kotlin {
sourceSets {
commonMain {
dependencies {
api 'com.example:foo-metadata:1.0'
}
}
jvm6Main {
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 набора исходных файлов определяет определённые аспекты анализа проекта и сборки. Доступны следующие параметры языка:
Имя |
Описание |
|---|---|
|
Обеспечивает совместимость исходного кода со указанной версией Kotlin. |
|
Позволяет использовать объявления только из указанной версии Kotlin-библиотек. |
|
Включает указанную языковую функцию. Доступные значения соответствуют языковым функциям, которые в настоящее время являются экспериментальными или были введены как таковые в какой-то момент. |
|
Позволяет использовать указанный атрибут включения. |
|
Включает постепенный режим. |
kotlin {
sourceSets.all {
languageSettings.apply {
languageVersion = "1.7" // possible values: "1.4", "1.5", "1.6", "1.7"
apiVersion = "1.7" // possible values: "1.3", "1.4", "1.5", "1.6", "1.7"
enableLanguageFeature("InlineClasses") // language feature name
optIn("kotlin.ExperimentalUnsignedTypes") // annotation FQ-name
progressiveMode = true // false by default
}
}
}
kotlin {
sourceSets.all {
languageSettings {
languageVersion = '1.7' // possible values: '1.4', '1.5', '1.6', '1.7'
apiVersion = '1.7' // possible values: '1.3', '1.4', '1.5', '1.6', '1.7'
enableLanguageFeature('InlineClasses') // language feature name
optIn('kotlin.ExperimentalUnsignedTypes') // annotation FQ-name
progressiveMode = true // false by default
}
}
}
© 2010–2022 JetBrains s.r.o. and Kotlin Programming Language contributors
Licensed under the Apache License, Version 2.0.
https://kotlinlang.org/docs/multiplatform-dsl-reference.html