Spec-Zone.ru › Kotlin 1.9

Справочник по Gradle DSL для многоплатформенных проектов

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

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

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

Полное имя плагина Kotlin Multiplatform Gradle — org.jetbrains.kotlin.multiplatform. Если вы используете Kotlin Gradle DSL, вы можете применить плагин с помощью kotlin("multiplatform"). Версии плагина соответствуют версиям Kotlin. Последняя версия — 1.9.0.

plugins {
    kotlin("multiplatform") version "1.9.0"
}
plugins {
    id 'org.jetbrains.kotlin.multiplatform' version '1.9.0'
}

Основные блоки

kotlin — это основной блок для конфигурации многоплатформенного проекта в скрипте сборки Gradle. Внутри kotlin, вы можете написать следующие блоки:

Блок

Описание

<targetName>

Объявляет конкретную цель проекта. Названия доступных целей перечислены в разделе Цели.

targets

Все цели проекта.

presets

Все предварительно определённые цели. Используйте для настройки нескольких предварительно определённых целей одновременно.

sourceSets

Настраивает предварительно определённые и объявляет пользовательские наборы исходных файлов проекта.

END_OF_DOCUMENT_MARKER

Цели

Цель — часть сборки, отвечающая за компиляцию, тестирование и создание пакета программного обеспечения, предназначенного для одной из поддерживаемых платформ. Kotlin предоставляет шаблоны целей для каждой платформы. Узнайте, как использовать шаблон цели.

Каждая цель может иметь одну или несколько компиляций. В дополнение к стандартным компиляциям для тестирования и производства, вы можете создать пользовательские компиляции.

Цели многоплатформенного проекта описаны в соответствующих блоках внутри kotlin, например, jvm, android, iosArm64. Полный список доступных целей следующий:

Платформа цели

Шаблон цели

Комментарии

Kotlin/JVM

jvm

Kotlin/JS

js

Выберите среду выполнения:

  • browser {} для приложений, работающих в браузере.

  • nodejs {} для приложений, работающих в Node.js.

Подробнее в Настройка проекта Kotlin/JS.

Kotlin/Native

Узнайте о поддерживаемых в настоящее время целях для хостов macOS, Linux и Windows в Поддержка целей Kotlin/Native.

Приложения и библиотеки Android

android

Вручную примените плагин Android Gradle: com.android.application или com.android.library.

Вы можете создать только одну цель Android на подпроект Gradle.

Цель, не поддерживаемая текущим хостом, игнорируется во время сборки и, следовательно, не публикуется.

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 { /* ... */ }
    }
}

Нативные целевые платформы

Для нативных целевых платформ доступны следующие специфические блоки:

Имя

Описание

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", 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 и определите её параметры:

Имя

Описание

defFile

Файл def описывающий нативный API.

packageName

Префикс пакета для сгенерированного Kotlin API.

compilerOpts

Параметры для передачи компилятору через инструмент cinterop.

includeDirs

Директории для поиска заголовков.

Подробнее о том, как настроить взаимодействие с нативными языками.

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. Две функции помогают настроить наборы вариантов сборки:

Имя

Описание

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 {
        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.srcDir

Расположение Kotlin-исходных файлов внутри каталога набора исходных файлов.

resources.srcDir

Расположение ресурсов внутри каталога набора исходных файлов.

dependsOn

Связь с другим набором исходных файлов.

dependencies

Зависимости набора исходных файлов.

languageSettings

Языковые настройки, применяемые к набору исходных файлов.

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. Доступные предварительно заданные сборки следующие:

Имя

Описание

main

Сборка для исходных кодов производства.

test

Сборка для тестов.

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) {
                /* ... */
            }
        }
    }
}

Параметры сборки

У сборки есть следующие параметры:

Имя

Описание

defaultSourceSet

Набор исходных кодов по умолчанию для сборки.

kotlinSourceSets

Наборы исходных кодов, участвующих в сборке.

allKotlinSourceSets

Наборы исходных кодов, участвующие в сборке, и их связи через dependsOn().

compilerOptions

Параметры компилятора, применяемые к сборке. Список доступных параметров см. в Параметрах компилятора.

compileKotlinTask

Задача Gradle для компиляции Kotlin исходных кодов.

compileKotlinTaskName

Имя compileKotlinTask.

compileAllTaskName

Имя задачи Gradle для компиляции всех исходных кодов сборки.

output

Вывод сборки.

compileDependencyFiles

Файлы зависимостей времени компиляции (classpath) сборки.

runtimeDependencyFiles

Файлы зависимостей времени выполнения (classpath) сборки.

kotlin {
    jvm {
        val main by compilations.getting {
            compilerOptions.configure { 
                // Set up 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

Зависимости, используемые в API текущего модуля.

implementation

Зависимости, используемые в модуле, но не экспортируемые за его пределы.

compileOnly

Зависимости, используемые только для компиляции текущего модуля.

runtimeOnly

Зависимости, доступные во время выполнения, но не видимые во время компиляции любого модуля.

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 набора исходных данных определяет некоторые аспекты анализа проекта и сборки. Доступны следующие настройки языка:

Имя

Описание

languageVersion

Обеспечивает совместимость исходного кода с указанной версией Kotlin.

apiVersion

Разрешает использование объявлений только из указанной версии связанных библиотек Kotlin.

enableLanguageFeature

Включает указанную языковую возможность. Доступные значения соответствуют языковым возможностям, которые в настоящее время являются экспериментальными или были введены как таковые в какой-то момент.

optIn

Разрешает использование указанной аннотации opt-in.

progressiveMode

Включает постепенный режим.

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
        }
    }
}

Spec-Zone.ru

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