Spec-Zone.ru › Kotlin 1.7

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

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

Плагин 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>

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

targets

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

presets

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

sourceSets

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

END_OF_DOCUMENT_MARKER

Цели

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

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

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

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

Предустановка цели

Комментарии

Kotlin/JVM

jvm

Kotlin/JS

js

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

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

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

Узнайте больше в Настройка проекта Kotlin/JS.

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

android

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

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

Android NDK

  • androidNativeArm32 — Android NDK на платформах ARM (ARM32)

  • androidNativeArm64 — Android NDK на платформах ARM64

  • androidNativeX86 — Android NDK на платформах x86

  • androidNativeX64 — Android NDK на платформах x86_64

Для 64-разрядной цели требуется хост Linux или macOS.

Вы можете собрать 32-разрядную цель на любом поддерживаемом хосте.

iOS

  • iosArm32 — Apple iOS на платформах ARM (ARM32) (Apple iPhone 5 и старше)

  • iosArm64 — Apple iOS на платформах ARM64 (Apple iPhone 5s и новее)

  • iosX64 — Симулятор Apple iOS на платформах x86_64

  • iosSimulatorArm64 — Симулятор Apple iOS на платформах Apple Silicon

Требуется хост macOS с установленным Xcode и его инструментами командной строки.

watchOS

  • watchosArm32 — Apple watchOS на платформах ARM (ARM32) (Apple Watch Series 3 и старше)

  • watchosArm64 — Apple watchOS на платформах ARM64_32 (Apple Watch Series 4 и новее)

  • watchosX86 — 32-разрядный симулятор Apple watchOS (watchOS 6.3 и старше) на платформах x86_64

  • watchosX64 — 64-разрядный симулятор Apple watchOS (watchOS 7.0 и новее) на платформах x86_64

  • watchosSimulatorArm64 — Симулятор Apple watchOS на платформах Apple Silicon

Требуется хост macOS с установленным Xcode и его инструментами командной строки.

tvOS

  • tvosArm64 — Apple tvOS на платформах ARM64 (Apple TV 4-го поколения и новее)

  • tvosX64 — Симулятор Apple tvOS на платформах x86_64

  • tvosSimulatorArm64 — Симулятор Apple tvOS на платформах Apple Silicon

Требуется хост macOS с установленным Xcode и его инструментами командной строки.

macOS

  • macosX64 — Apple macOS на платформах x86_64

  • macosArm64 — Apple macOS на платформах Apple Silicon

Требуется хост macOS с установленным Xcode и его инструментами командной строки.

Linux

  • linuxArm64 — Linux на платформах ARM64, например, Raspberry Pi

  • linuxArm32Hfp — Linux на платформах ARM (ARM32) с плавающей точкой

  • linuxMips32 — Linux на платформах MIPS

  • linuxMipsel32 — Linux на платформах MIPS с малым порядком байтов (mipsel)

  • linuxX64 — Linux на платформах x86_64

Для целей Linux MIPS (linuxMips32 и linuxMipsel32) требуется хост Linux.

Вы можете собрать другие цели Linux на любом поддерживаемом хосте.

Windows

  • mingwX64 — 64-разрядная Microsoft Windows

  • mingwX86 — 32-разрядная Microsoft Windows

WebAssembly

wasm32

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

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 исходного кода, которые участвуют в компиляции вместе, а также их ресурсы, зависимости и параметры языка.

Проект multiplatform содержит предопределенные наборы исходных кодов для своих целей; разработчики также могут создавать пользовательские наборы исходных кодов для своих нужд.

Предопределенные наборы исходных кодов

Предопределенные наборы исходных кодов автоматически настраиваются при создании проекта multiplatform. Доступные предопределенные наборы исходных кодов:

Имя

Описание

commonMain

Код и ресурсы, общие для всех платформ. Доступны во всех проектах multiplatform. Используются во всех основных компиляциях проекта.

commonTest

Тестовый код и ресурсы, общие для всех платформ. Доступны во всех проектах multiplatform. Используются во всех тестовых компиляциях проекта.

<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().

kotlinOptions

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

compileKotlinTask

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

compileKotlinTaskName

Имя compileKotlinTask.

compileAllTaskName

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

output

Вывод компиляции.

compileDependencyFiles

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

runtimeDependencyFiles

Файлы зависимостей времени выполнения (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

Зависимости, используемые в 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

Позволяет использовать указанный атрибут включения.

progressiveMode

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

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
        }
    }
}
Последнее изменение: 27 сентября 2022 г.
Сборка конечных нативных библиотек Примеры

© 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

Spec-Zone.ru

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