Подключаемый модуль Kotlin/Native Gradle

С версии 1.3.40 отдельный плагин Gradle для Kotlin/Native устарел в пользу плагина kotlin-multiplatform. Этот плагин предоставляет поддержку IDE наряду с поддержкой новой модели многоплатформенных проектов, представленной в Kotlin 1.3.0. Ниже приведен краткий список различий между плагинами kotlin-platform-native и kotlin-muliplatform. Более подробную информацию см. на странице документации kotlin-muliplatform странице документации. Для справки kotlin-platform-native см. соответствующий раздел раздел.

Применение плагина multiplatform

Для применения плагина kotlin-multiplatform просто добавьте следующий фрагмент в ваш скрипт сборки:

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

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

С плагином kotlin-platform-native набор целевых платформ задаётся как список в свойствах основного компонента:

components.main {
    targets = ['macos_x64', 'linux_x64', 'mingw_x64']
}

С плагином kotlin-multiplatform целевые платформы можно добавить в проект, используя специальные методы, доступные в расширении kotlin. Каждый метод добавляет в проект одну целевую платформу, к которой можно получить доступ через свойство targets. Каждую целевую платформу можно настраивать независимо, включая типы выходных данных, дополнительные параметры компилятора и т.д. Подробности о целевых платформах см. на соответствующей странице.

import org.jetbrains.kotlin.gradle.plugin.mpp.KotlinNativeTarget

kotlin {
    // These targets are declared without any target-specific settings. 
    macosX64()
    linuxX64()
    
    // You can specify a custom name used to access the target.
    mingwX64("windows") 
    
    iosArm64 {
        // Additional settings for ios_arm64.
    }
    
    // You can access declared targets using the `targets` property.
    println(targets.macosX64)
    println(targets.windows)
    
    // You also can configure all native targets in a single block.
    targets.withType(KotlinNativeTarget) {
        // Native target configuration.
    }
}

Каждая целевая платформа включает две компиляции: main и test для компиляции кода продукта и кода тестов соответственно. Компиляция — это абстракция над вызовом компилятора, описанная на соответствующей странице.

Управление исходными файлами

С плагином kotlin-platform-native наборы исходных файлов используются для разделения исходных файлов тестов и продукта. Также вы можете указать разные исходные файлы для разных платформ в одном наборе исходных файлов:

sourceSets {
    // Adding target-independent sources.
    main.kotlin.srcDirs += 'src/main/mySources'
    
    // Adding Linux-specific code.
    main.target('linux_x64').srcDirs += 'src/main/linux'
}

С плагином kotlin-multiplatform также используются наборы исходных файлов для группировки исходных файлов, но исходные файлы для разных платформ находятся в разных наборах исходных файлов. Для каждой объявленной целевой платформы создаются два набора исходных файлов: <target-name>Main и <target-name>Test, содержащие исходные файлы продукта и тестов для этой платформы. Общие исходные файлы для всех платформ находятся в наборах исходных файлов commonMain и commonTest по умолчанию. Более подробную информацию о наборах исходных файлов можно найти здесь.

kotlin {
    sourceSets {
        // Adding target-independent sources.
        commonMain.kotlin.srcDirs += file("src/main/mySources")

        // Adding Linux-specific code.
        linuxX64Main.kotlin.srcDirs += file("src/main/linux")
    }
}

Управление зависимостями

С плагином kotlin-platform-native зависимости настраиваются традиционным для Gradle способом, группируя их в конфигурации с помощью блока проекта dependencies:

dependencies {
    implementation 'org.sample.test:mylibrary:1.0'
    testImplementation 'org.sample.test:testlibrary:1.0'
}

Плагин kotlin-multiplatform также использует конфигурации под капотом, но также предоставляет блок dependencies для каждого набора исходных файлов, позволяющий настраивать зависимости этого набора исходных файлов:

kotlin.sourceSets {
    commonMain {
        dependencies {
            implementation("org.sample.test:mylibrary:1.0")
        }
    }
    
    commonTest {
        dependencies {
            implementation("org.sample.test:testlibrary:1.0")
        }
    }
}

Обратите внимание, что модуль, на который ссылается зависимость, объявленная для набора исходных файлов commonMain или commonTest, должен быть опубликован с использованием плагина kotlin-multiplatform. Если вы хотите использовать библиотеки, опубликованные с помощью плагина kotlin-platform-native, вам необходимо объявить отдельный набор исходных файлов для общих исходных файлов нативного кода.

kotlin.sourceSets {
    // Create a common source set used by native targets only.
    nativeMain {
        dependsOn(commonMain)
        dependencies {
            // Depend on a library published by the kotlin-platform-naive plugin.
            implementation("org.sample.test:mylibrary:1.0")
        }
    }

    // Configure all native platform sources sets to use it as a common one.
    linuxX64Main.dependsOn(nativeMain)
    macosX64Main.dependsOn(nativeMain)
    //...
}

Дополнительную информацию о зависимостях см. на соответствующей странице.

Типы выходных данных

С плагином kotlin-platform-native типы выходных данных указываются как список в свойствах компонента:

components.main {
    // Compile the component into an executable and a Kotlin/Native library.
    outputKinds = [EXECUTABLE, KLIBRARY]
}

С плагином kotlin-multiplatform компиляция всегда генерирует файл *.klib. Отдельный блок binaries используется для настройки того, какие окончательные двоичные файлы нативного кода должны генерироваться каждой целевой платформой. Каждый двоичный файл можно настраивать независимо, включая параметры компоновщика, точку входа исполняемого файла и т.д.

kotlin {
    macosX64 {
        binaries {
            executable {
                // Binary configuration: linker options, name, etc.
            }
            framework {
                // ...
            }
            
        }
    }
}

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

Публикация

Плагины kotlin-platform-native и kotlin-multiplatform автоматически настраивают публикацию артефактов при применении плагина maven-publish. Подробности о публикации см. на соответствующей странице. Обратите внимание, что в настоящее время публиковать можно только библиотеки Kotlin/Native (*.klib) для нативных целевых платформ.

Поддержка Cinterop

С плагином kotlin-platform-native взаимодействие с нативной библиотекой может быть объявлено в зависимостях компонента:

components.main {
    dependencies {
        cinterop('mystdio') {
            // Cinterop configuration.
        }
    }
}

С плагином kotlin-multiplatform взаимодействия настраиваются как часть компиляции (см. подробности здесь). Остальная часть настройки взаимодействия такая же, как и для плагина kotlin-platform-native.

kotlin {
    macosX64 {
        compilations.main.cinterops {
            mystdio {
                // Cinterop configuration.
            }
        }
    }
}

Ссылка по плагину kotlin-platform-native

Обзор

Вы можете использовать плагин Gradle для сборки проектов Kotlin/Native. Сборки плагина доступны на портале плагинов Gradle здесь, поэтому вы можете применить его с помощью DSL Gradle:

plugins {
    id "org.jetbrains.kotlin.platform.native" version "1.3.0-rc-146"
}

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

buildscript {
   repositories {
       mavenCentral()
       maven {
           url "https://dl.bintray.com/jetbrains/kotlin-native-dependencies"
       }
   }

   dependencies {
       classpath "org.jetbrains.kotlin:kotlin-native-gradle-plugin:1.3.0-rc-146"
   }
}

apply plugin: 'org.jetbrains.kotlin.platform.native'

По умолчанию плагин загружает компилятор Kotlin/Native при первом запуске. Если вы уже загрузили компилятор вручную, вы можете указать путь к его корневому каталогу с помощью свойства проекта org.jetbrains.kotlin.native.home (например, в gradle.properties).

org.jetbrains.kotlin.native.home=/home/user/kotlin-native-0.8

В этом случае плагин не будет загружать компилятор.

Управление исходными файлами

Управление исходными файлами в плагине kotlin.platform.native унифицировано с другими плагинами Kotlin и основано на наборах исходных файлов. Набор исходных файлов — это группа исходных файлов Kotlin/Native, которые могут содержать как общий, так и платформенно-специфический код. Плагин предоставляет блок верхнего уровня sourceSets, позволяющий настроить наборы исходных файлов. Также он создаёт наборы исходных файлов main и test (для кода производства и тестирования соответственно).

По умолчанию исходные файлы производства находятся в src/main/kotlin, а исходные файлы тестов — в src/test/kotlin.

sourceSets {
    // Adding target-independent sources.
    main.kotlin.srcDirs += 'src/main/mySources'
    
    // Adding Linux-specific code. It will be compiled in Linux binaries only.
    main.target('linux_x64').srcDirs += 'src/main/linux'
}

Целевые платформы и типы выходных данных

По умолчанию плагин создаёт программные компоненты для основных и тестовых наборов исходных файлов. К ним можно получить доступ через контейнер components, предоставляемый Gradle, или через свойство component соответствующего набора исходных файлов:

// Main component.
components.main
sourceSets.main.component

// Test component.
components.test
sourceSets.test.component

Компоненты позволяют указывать:

• Целевые платформы (например, Linux/x64 или iOS/arm64 и т.д.)
• Типы выходных данных (например, исполняемый файл, библиотека, фреймворк и т.д.)
• Зависимости (включая зависимости для взаимодействия)

Целевые платформы можно указать, задав соответствующее свойство компонента:

components.main {
    // Compile this component for 64-bit MacOS, Linux and Windows.
    targets = ['macos_x64', 'linux_x64', 'mingw_x64']
}

Плагин использует ту же нотацию, что и компилятор. По умолчанию тестовый компонент использует те же целевые платформы, что и основной.

Типы выходных данных также можно указать, используя специальное свойство:

components.main {
    // Compile the component into an executable and a Kotlin/Native library.
    outputKinds = [EXECUTABLE, KLIBRARY]
}

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

• EXECUTABLE — исполняемый файл;
• KLIBRARY — библиотека Kotlin/Native (*.klib);
• FRAMEWORK — фреймворк Objective-C;
• DYNAMIC — динамическая библиотека нативного кода;
• STATIC — статическая библиотека нативного кода.

Кроме того, каждый нативный двоичный файл создаётся в двух вариантах (типах сборки): debug (отладочный, не оптимизированный) и release (неотладочный, оптимизированный). Обратите внимание, что для библиотек Kotlin/Native доступен только вариант debug, так как оптимизации выполняются только при компиляции конечного двоичного файла (исполняемого файла, статической библиотеки и т.д.) и влияют на все используемые библиотеки для его сборки.

Задачи компиляции

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

compile<ComponentName><BuildType><OutputKind><Target>KotlinNative

Например, compileDebugKlibraryMacos_x64KotlinNative, compileTestDebugKotlinNative.

Имя содержит следующие части (некоторые из них могут быть пустыми):

• <ComponentName> — имя компонента. Пустое для основного компонента.
• <BuildType> — Debug или Release.
• <OutputKind> — имя типа вывода, например Executabe или Dynamic. Пустое, если компонент имеет только один тип вывода.
• <Target> — целевая платформа для сборки компонента, например Macos_x64 или Wasm32. Пустое, если компонент собирается только для одной платформы.

Также плагин создаёт ряд агрегированных задач, позволяющих собрать все бинарные файлы для типа сборки (например, assembleAllDebug) или все бинарные файлы для конкретной платформы (например, assembleAllWasm32).

Также доступны базовые задачи жизненного цикла, такие как assemble, build, и clean.

Запуск тестов

Плагин создаёт исполняемый файл для тестов для всех платформ, указанных для компонента test. Если текущая платформа включена в этот список, создаются также задачи для запуска тестов. Для запуска тестов выполните стандартную задачу жизненного цикла check:

./gradlew check

Зависимости

Плагин позволяет объявлять зависимости от файлов и других проектов, используя традиционный механизм конфигураций Gradle. Плагин поддерживает проекты Kotlin multiplatform, позволяя объявлять зависимости expectedBy.

dependencies {
    implementation files('path/to/file/dependencies')
    implementation project('library')
    testImplementation project('testLibrary')
    expectedBy project('common')
}

Можно зависеть от библиотеки Kotlin/Native, опубликованной ранее в репозитории maven. Плагин использует поддержку метаданных Gradle (справка), поэтому соответствующая функция должна быть включена. Добавьте следующую строку в ваш settings.gradle:

enableFeaturePreview('GRADLE_METADATA')

Теперь можно объявить зависимость от библиотеки Kotlin/Native в традиционной group:artifact:version нотации:

dependencies {
    implementation 'org.sample.test:mylibrary:1.0'
    testImplementation 'org.sample.test:testlibrary:1.0'
}

Объявление зависимостей также возможно в блоке компонента:

components.main {
    dependencies {
        implementation 'org.sample.test:mylibrary:1.0'
    }
}

components.test {
    dependencies {
        implementation 'org.sample.test:testlibrary:1.0'
    }
}

Использование cinterop

Можно объявить зависимость cinterop для компонента:

components.main {
    dependencies {
        cinterop('mystdio') {
            // src/main/c_interop/mystdio.def is used as a def file.

            // Set up compiler options
            compilerOpts '-I/my/include/path'

            // It's possible to set up different options for different targets
            target('linux') {
                compilerOpts '-I/linux/include/path'
            }
        }
    }
}

Здесь будет построена и добавлена в зависимости компонента библиотека interop.

Часто необходимо указать платформоспецифичные опции линкера для бинарника Kotlin/Native, использующего interop. Это можно сделать, используя блок сценария target:

components.main {
    target('linux') {
        linkerOpts '-L/path/to/linux/libs'
    }
}

Также доступен блок allTargets.

components.main {
    // Configure all targets.
    allTargets {
        linkerOpts '-L/path/to/libs'
    }
}

Публикация

При наличии плагина maven-publish создаются публикации для всех скомпилированных бинарников. Плагин использует метаданные Gradle для публикации артефактов, поэтому эта функция должна быть включена (см. раздел зависимости).

Теперь можно опубликовать артефакты с помощью стандартной задачи Gradle publish:

./gradlew publish

В настоящее время публикуются только бинарники EXECUTABLE и KLIBRARY.

Плагин позволяет настраивать генерируемый pom-файл для публикации с помощью блока кода pom , доступного для каждого компонента:

components.main {
    pom {
        withXml {
            def root = asNode()
            root.appendNode('name', 'My library')
            root.appendNode('description', 'A Kotlin/Native library')
        }
    }
}

Плагин сериализации

Плагин поставляется с настраиваемой версией плагина kotlinx.serialization. Для его использования не нужно добавлять новые зависимости buildscript, достаточно применить плагины и добавить зависимость от библиотеки сериализации:

apply plugin: 'org.jetbrains.kotlin.platform.native'
apply plugin: 'kotlinx-serialization-native'

dependencies {
    implementation 'org.jetbrains.kotlinx:kotlinx-serialization-runtime-native'
}

См. пример проекта для получения дополнительных сведений.

Пример DSL

В этом разделе показан комментированный DSL. Также обратите внимание на примеры проектов, использующих этот плагин, например Kotlinx.coroutines, MPP http client

plugins {
    id "org.jetbrains.kotlin.platform.native" version "1.3.0-rc-146"
}

sourceSets.main {
    // Plugin uses Gradle's source directory sets here,
    // so all the DSL methods available in SourceDirectorySet can be called here.
    // Platform independent sources.
    kotlin.srcDirs += 'src/main/customDir'

    // Linux-specific sources
    target('linux').srcDirs += 'src/main/linux'
}

components.main {

    // Set up targets
    targets = ['linux_x64', 'macos_x64', 'mingw_x64']

    // Set up output kinds
    outputKinds = [EXECUTABLE, KLIBRARY, FRAMEWORK, DYNAMIC, STATIC]
    
    // Specify custom entry point for executables
    entryPoint = "org.test.myMain"

    // Target-specific options
    target('linux_x64') {
        linkerOpts '-L/linux/lib/path'
    }

    // Targets independent options
    allTargets {
        linkerOpts '-L/common/lib/path'
    }

    dependencies {

        // Dependency on a published Kotlin/Native library.
        implementation 'org.test:mylib:1.0'

        // Dependency on a project
        implementation project('library')

        // Cinterop dependency
        cinterop('interop-name') {
            // Def-file describing the native API.
            // The default path is src/main/c_interop/<interop-name>.def
            defFile project.file("deffile.def")

            // Package to place the Kotlin API generated.
            packageName 'org.sample'

            // Options to be passed to compiler and linker by cinterop tool.
            compilerOpts 'Options for native stubs compilation'
            linkerOpts 'Options for native stubs'

            // Additional headers to parse.
            headers project.files('header1.h', 'header2.h')

            // Directories to look for headers.
            includeDirs {
                // All objects accepted by the Project.file method may be used with both options.

                // Directories for header search (an analogue of the -I<path> compiler option).
                allHeaders 'path1', 'path2'

                // Additional directories to search headers listed in the 'headerFilter' def-file option.
                // -headerFilterAdditionalSearchPrefix command line option analogue.
                headerFilterOnly 'path1', 'path2'
            }
            // A shortcut for includeDirs.allHeaders.
            includeDirs "include/directory" "another/directory"

            // Pass additional command line options to the cinterop tool.
            extraOpts '-verbose'

            // Additional configuration for Linux.
            target('linux') {
                compilerOpts 'Linux-specific options'
            }
        }
    }

    // Additional pom settings for publication.
    pom {
        withXml {
            def root = asNode()
            root.appendNode('name', 'My library')
            root.appendNode('description', 'A Kotlin/Native library')
        }
    }

    // Additional options passed to the compiler.
    extraOpts '--time'
}