Spec-Zone.ru › Kotlin 1.6

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

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

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

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

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

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

Блоки верхнего уровня

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

Блок

Описание

<targetName>

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

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) с hard-float

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

  • linuxMipsel32 — Linux на платформах MIPS с little-endian (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 { /* ... */ }
    }
}

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

Имя

Описание

defFile

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

packageName

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

compilerOpts

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

includeDirs

Каталоги для поиска заголовков.

Подробнее о конфигурации взаимодействия с 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. Эти две функции помогут вам настроить варианты сборки:

Имя

Описание

publishLibraryVariants()

Указывает варианты сборки для публикации. Подробнее об публикации библиотек Android.

publishAllLibraryVariants()

Опубликовывает все варианты сборки.

kotlin {
    android {
        publishLibraryVariants("release", "debug")
    }
}

Подробнее о компиляции для Android.

Конфигурация android внутри kotlin не заменяет конфигурацию сборки любого проекта Android. Подробнее о написании скриптов сборки для проектов Android в документации по разработке приложений Android.

Наборы исходных файлов

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

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

Предварительно определенные наборы исходных файлов

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

Имя

Описание

commonMain

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

commonTest

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

<имя_цели><имя_компиляции>

Источники, специфичные для цели, для компиляции. <имя_цели> — имя предварительно определенной цели, а <имя_компиляции> — имя компиляции для этой цели. Примеры: 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

Позволяет использовать указанную аннотацию opt-in.

progressiveMode

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

kotlin {
    sourceSets.all {
        languageSettings.apply {
            languageVersion = "1.4" // possible values: "1.0", "1.1", "1.2", "1.3", "1.4", "1.5", "1.6", "1.7"
            apiVersion = "1.4" // possible values: "1.0", "1.1", "1.2", "1.3", "1.4", "1.5"
            enableLanguageFeature("InlineClasses") // language feature name
            optIn("kotlin.ExperimentalUnsignedTypes") // annotation FQ-name
            progressiveMode = true // false by default
        }
    }
}
kotlin {
    sourceSets.all {
        languageSettings {
            languageVersion = '1.4' // possible values: '1.0', '1.1', '1.2', '1.3', '1.4', '1.5', '1.6', '1.7'
            apiVersion = '1.4' // possible values: '1.0', '1.1', '1.2', '1.3', '1.4', '1.5'
            enableLanguageFeature('InlineClasses') // language feature name
            optIn('kotlin.ExperimentalUnsignedTypes') // annotation FQ-name
            progressiveMode = true // false by default
        }
    }
}
Последнее изменение: 07 апреля 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