Справочник по Gradle DSL для многоплатформенных проектов
Плагин Kotlin Multiplatform Gradle предназначен для создания многоплатформенных проектов Kotlin. Здесь представлен справочник по его содержимому; используйте его в качестве напоминания при написании скриптов сборки Gradle для многоплатформенных проектов Kotlin. Изучите концепции многоплатформенных проектов Kotlin, как их создавать и настраивать.
Идентификатор и версия
Полное имя плагина Kotlin Multiplatform Gradle — org.jetbrains.kotlin.multiplatform. Если вы используете Kotlin Gradle DSL, вы можете применить плагин с помощью kotlin("multiplatform"). Версии плагина соответствуют версиям Kotlin. Самая последняя версия — 1.8.0.
plugins {
kotlin("multiplatform") version "1.8.0"
}
plugins {
id 'org.jetbrains.kotlin.multiplatform' version '1.8.0'
}
Основные блоки
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 { /* ... */ }
}
}
Цели 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-источников, которые участвуют в компиляции вместе, а также их ресурсы, зависимости и параметры языка.
Многоплатформенный проект содержит предопределенные наборы исходных файлов для своих целей; разработчики также могут создавать настраиваемые наборы исходных файлов для своих нужд.
Предопределенные наборы исходных файлов
Предопределенные наборы исходных файлов настраиваются автоматически при создании многоплатформенного проекта. Доступные предопределенные наборы исходных файлов следующие:
Имя |
Описание |
|---|---|
|
Код и ресурсы, общие для всех платформ. Доступны во всех многоплатформенных проектах. Используются во всех основных компиляциях проекта. |
|
Тестовый код и ресурсы, общие для всех платформ. Доступны во всех многоплатформенных проектах. Используются во всех тестовых компиляциях проекта. |
<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 {
compilerOptions.configure {
// Setup 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:
targets.all {
compilations.all {
compilerOptions.configure {
allWarningsAsErrors.set(true)
}
}
}
}
kotlin {
jvm {
compilations.main.compilerOptions.configure {
// Setup the Kotlin compiler options for the 'main' compilation:
jvmTarget.set(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:
targets.all {
compilations.all {
compilerOptions.configure {
allWarningsAsError.set(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.8" // possible values: "1.4", "1.5", "1.6", "1.7", "1.8", "1.9"
apiVersion = "1.8" // possible values: "1.3", "1.4", "1.5", "1.6", "1.7", "1.8", "1.9"
enableLanguageFeature("InlineClasses") // language feature name
optIn("kotlin.ExperimentalUnsignedTypes") // annotation FQ-name
progressiveMode = true // false by default
}
}
}
kotlin {
sourceSets.all {
languageSettings {
languageVersion = '1.8' // possible values: '1.4', '1.5', '1.6', '1.7', '1.8', '1.9'
apiVersion = '1.8' // possible values: '1.3', '1.4', '1.5', '1.6', '1.7', '1.8', '1.9'
enableLanguageFeature('InlineClasses') // language feature name
optIn('kotlin.ExperimentalUnsignedTypes') // annotation FQ-name
progressiveMode = true // false by default
}
}
}
© 2010–2023 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