Spec-Zone.ru › Kotlin 1.4

Справочник Kotlin Multiplatform Gradle DSL

Многоплатформенные проекты находятся в альфа-стадии. Функциональные возможности языка и инструменты могут измениться в будущих версиях Kotlin.

Плагин Kotlin Multiplatform Gradle предназначен для создания многоплатформенных проектов Kotlin. Здесь представлена справка по его содержимому; используйте её в качестве напоминания при написании скриптов сборки Gradle для многоплатформенных проектов Kotlin. Ознакомьтесь с концепциями многоплатформенных проектов Kotlin, а также с их созданием и настройкой.

Содержание

  • Идентификатор и версия
  • Блоки верхнего уровня
  • Цели
    • Настройка общей цели
    • Цели JVM
    • Цели JavaScript
    • Цели Native
    • Цели Android
  • Наборы исходных кодов
    • Предопределённые наборы исходных кодов
    • Настраиваемые наборы исходных кодов
    • Параметры наборов исходных кодов
  • Сборки
    • Предопределённые сборки
    • Настраиваемые сборки
    • Параметры сборки
  • Зависимости
  • Настройки языка

Идентификатор и версия

Полное квалифицированное имя плагина 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

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API