Справочник по Gradle DSL для многоплатформенных проектов
Плагин Kotlin Multiplatform Gradle предназначен для создания проектов Kotlin Multiplatform. Здесь вы найдете справочник по его содержанию; используйте его как напоминание при написании скриптов конфигурации Gradle для проектов Kotlin Multiplatform. Изучите концепции проектов Kotlin Multiplatform, как их создать и настроить.
Идентификатор и версия
Полное имя плагина Kotlin Multiplatform Gradle — org.jetbrains.kotlin.multiplatform. Если вы используете Kotlin Gradle DSL, вы можете применить плагин с помощью kotlin(“multiplatform”). Версии плагина соответствуют версиям Kotlin. Наиболее последняя версия — 1.6.20.
plugins {
kotlin("multiplatform") version "1.6.20"
}
plugins {
id 'org.jetbrains.kotlin.multiplatform' version '1.6.20'
}
Блоки верхнего уровня
kotlin — это блок верхнего уровня для конфигурации проекта Multiplatform в скрипте конфигурации 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 { /* ... */ }
}
}
Цели native
Для целей native доступны следующие специфические блоки:
Имя |
Описание |
|---|---|
|
Конфигурация создаваемых библиотек. |
|
Настройка взаимодействия с 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
}
}
Подробнее о создании native библиотек.
CInterops
cinterops — это набор описаний для взаимодействия с native библиотеками. Для обеспечения взаимодействия с библиотекой добавьте запись в cinterops и определите её параметры:
Имя |
Описание |
|---|---|
|
Файл |
|
Префикс пакета для сгенерированного Kotlin API. |
|
Параметры для передачи компилятору инструментом cinterop. |
|
Каталоги для поиска заголовков. |
Подробнее о конфигурации взаимодействия с native языками.
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, которые участвуют в компиляции вместе, а также их ресурсы, зависимости и параметры языка.
Многоплатформенный проект содержит предварительно определенные наборы исходных файлов для своих целей; разработчики также могут создавать пользовательские наборы исходных файлов для своих нужд.
Предварительно определенные наборы исходных файлов
Предварительно определенные наборы исходных файлов настраиваются автоматически при создании многоплатформенного проекта. Доступные предварительно определенные наборы исходных файлов следующие:
Имя |
Описание |
|---|---|
|
Код и ресурсы, общие для всех платформ. Доступен во всех многоплатформенных проектах. Используется во всех основных компиляциях проекта. |
|
Тестовый код и ресурсы, общие для всех платформ. Доступен во всех многоплатформенных проектах. Используется во всех тестовых компиляциях проекта. |
<имя_цели><имя_компиляции> |
Источники, специфичные для цели, для компиляции. <имя_цели> — имя предварительно определенной цели, а <имя_компиляции> — имя компиляции для этой цели. Примеры: |
В 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. |
|
Включает указанную функцию языка. Доступные значения соответствуют функциям языка, которые в настоящее время являются экспериментальными или были представлены как таковые на каком-то этапе. |
|
Позволяет использовать указанную аннотацию opt-in. |
|
Включает прогрессивный режим. |
kotlin {
sourceSets.all {
languageSettings.apply {
languageVersion = "1.4" // possible values: "1.0", "1.1", "1.2", "1.3", "1.4", "1.5", "1.6", "1.7"
apiVersion = "1.4" // possible values: "1.0", "1.1", "1.2", "1.3", "1.4", "1.5"
enableLanguageFeature("InlineClasses") // language feature name
optIn("kotlin.ExperimentalUnsignedTypes") // annotation FQ-name
progressiveMode = true // false by default
}
}
}
kotlin {
sourceSets.all {
languageSettings {
languageVersion = '1.4' // possible values: '1.0', '1.1', '1.2', '1.3', '1.4', '1.5', '1.6', '1.7'
apiVersion = '1.4' // possible values: '1.0', '1.1', '1.2', '1.3', '1.4', '1.5'
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