Создание конечных нативных библиотек (экспериментальный DSL)

[//]: # (title: Build final native binaries (Experimental DSL))

Цели Kotlin/Native компилируются в библиотечные артефакты *.klib, которые могут потребляться самим Kotlin/Native в качестве зависимости, но не могут использоваться как нативные библиотеки.

Для объявления конечных нативных библиотек используйте новый формат библиотек с помощью DSL kotlinArtifacts. Он представляет собой набор нативных библиотек, созданных для данной цели, в дополнение к стандартному артефакту *.klib и предоставляет набор методов для их объявления и настройки.

DSL артефактов Kotlin может помочь решить распространённую проблему: когда необходимо получить доступ к нескольким модулям Kotlin из вашего приложения. Поскольку использование нескольких артефактов Kotlin/Native ограничено, вы можете экспортировать несколько модулей Kotlin в один артефакт с помощью нового DSL.

Объявление библиотек

Элемент kotlinArtifacts является блоком верхнего уровня для конфигурации артефактов в скрипте сборки Gradle. Используйте следующие виды библиотек для объявления элементов DSL kotlinArtifacts.

Метод фабрики	Тип библиотеки	Доступно для
`sharedLib`	Нативная библиотека динамической загрузки	Все нативные цели, кроме `WebAssembly`
`staticLib`	Нативная библиотека статической загрузки	Все нативные цели, кроме `WebAssembly`
`framework`	Фреймворк Objective-C	Только цели macOS, iOS, watchOS и tvOS
`fatFramework`	Универсальный фреймворк	Только цели macOS, iOS, watchOS и tvOS
`XCFramework`	Фреймворк XCFramework	Только цели macOS, iOS, watchOS и tvOS

Внутри элемента kotlinArtifacts вы можете написать следующие блоки:

Native.Library
Native.Framework
Native.FatFramework
Native.XCFramework

Самый простой вариант требует параметра target (или targets) для выбранного типа сборки. В настоящее время доступны два типа сборки:

DEBUG — создаёт не оптимизированную библиотеку с информацией об отладке
RELEASE — создаёт оптимизированную библиотеку без информации об отладке

В параметре modes можно указать типы сборки, для которых необходимо создать библиотеки. По умолчанию включаются как DEBUG, так и RELEASE исполняемые файлы:

kotlinArtifacts {
    Native.Library {
        target = iosX64 // Define your target instead
        modes(DEBUG, RELEASE)
        // Binary configuration
    }
}

kotlinArtifacts {
    it.native.Library {
        target = iosX64 // Define your target instead
        modes(DEBUG, RELEASE)
        // Binary configuration
    }
}

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

kotlinArtifacts {
    Native.Library("mylib") {
        // Binary configuration
    }
}

kotlinArtifacts {
    it.native.Library("mylib") {
        // Binary configuration
    }
}

Аргумент задаёт префикс имени, который является стандартным именем для файла библиотеки. Например, для Windows код создаёт файл mylib.dll.

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

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

Имя	Описание
`isStatic`	Дополнительный тип связывания, определяющий тип библиотеки. По умолчанию, это `false`, и библиотека является динамической.
`modes`	Дополнительные типы сборки, `DEBUG` и `RELEASE`.
`kotlinOptions`	Дополнительные параметры компилятора, применяемые к компиляции. См. список доступных параметров компилятора.
`addModule`	В дополнение к текущему модулю, вы можете добавить другие модули к результирующему артефакту.
`setModules`	Вы можете переопределить список всех модулей, которые будут добавлены в результирующий артефакт.

Библиотеки и фреймворки

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

Библиотека

Для конфигурации библиотеки доступен дополнительный параметр target:

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

kotlinArtifacts {
    Native.Library("myslib") {
        target = linuxX64
        isStatic = false
        modes(DEBUG)
        addModule(project(":lib"))
        kotlinOptions {
            verbose = false
            freeCompilerArgs += "-Xmen=pool"
        }
    }
}

kotlinArtifacts {
    it.native.Library("myslib") {
        target = linuxX64
        it.static = false
        modes(DEBUG)
        addModule(project(":lib"))
        kotlinOptions {
            verbose = false
            freeCompilerArgs += "-Xmen=pool"
        }
    }
}

Зарегистрированная задача Gradle — assembleMyslibSharedLibrary — собирает все типы зарегистрированных "myslib" в динамическую библиотеку.

Фреймворк

Для конфигурации фреймворка доступны следующие дополнительные параметры:

Имя	Описание
`target`	Объявляет конкретную цель проекта. Названия доступных целей перечислены в разделе Цели.
`embedBitcode`	Объявляет режим встраивания bitcode. Используйте `MARKER` для встраивания маркера bitcode (для отладочных сборок) или `DISABLE` для отключения встраивания. Встраивание bitcode не требуется для Xcode 14 и более поздних версий.

kotlinArtifacts {
    Native.Framework("myframe") {
        modes(DEBUG, RELEASE)
        target = iosArm64
        isStatic = false
        embedBitcode = EmbedBitcodeMode.MARKER
        kotlinOptions {
            verbose = false
        }
    }
}

kotlinArtifacts {
    it.native.Framework("myframe") {
        modes(DEBUG, RELEASE)
        target = iosArm64
        it.static = false
        embedBitcode = EmbedBitcodeMode.MARKER
        kotlinOptions {
            verbose = false
        }
    }
}

Зарегистрированная задача Gradle — assembleMyframeFramework — собирает все типы зарегистрированных фреймворков "myframe".

Фреймворки FAT

По умолчанию, фреймворк Objective-C, созданный с помощью Kotlin/Native, поддерживает только одну платформу. Однако вы можете объединить такие фреймворки в единый универсальный (FAT) бинарник. Это особенно полезно для iOS-фреймворков 32-разрядной и 64-разрядной архитектуры. В этом случае вы можете использовать полученный универсальный фреймворк как на устройствах с 32-разрядной, так и с 64-разрядной архитектурой.

Для конфигурации FAT-фреймворка доступны следующие дополнительные параметры:

Имя	Описание
`targets`	Объявляет все цели проекта.
`embedBitcode`	Объявляет режим встраивания bitcode. Используйте `MARKER` для встраивания маркера bitcode (для отладочных сборок) или `DISABLE` для отключения встраивания. Встраивание bitcode не требуется для Xcode 14 и более поздних версий.

kotlinArtifacts {
    Native.FatFramework("myfatframe") {
        targets(iosX32, iosX64)
        embedBitcode = EmbedBitcodeMode.DISABLE
        kotlinOptions {
            suppressWarnings = false
        }
    }
}

kotlinArtifacts {
    it.native.FatFramework("myfatframe") {
        targets(iosX32, iosX64)
        embedBitcode = EmbedBitcodeMode.DISABLE
        kotlinOptions {
            suppressWarnings = false
        }
    }
}

Зарегистрированная задача Gradle — assembleMyfatframeFatFramework — собирает все типы зарегистрированных FAT-фреймворков "myfatframe".

XCFrameworks

Все проекты Kotlin Multiplatform могут использовать XCFrameworks в качестве результата, чтобы собрать логику для всех целевых платформ и архитектур в одном пакете. В отличие от универсальных (FAT) фреймворков, вам не нужно удалять все ненужные архитектуры перед публикацией приложения в App Store.

Для конфигурации XCFrameworks доступны следующие дополнительные параметры:

Имя	Описание
`targets`	Объявляет все цели проекта.
`embedBitcode`	Объявляет режим встраивания bitcode. Используйте `MARKER` для встраивания маркера bitcode (для отладочных сборок) или `DISABLE` для отключения встраивания. Встраивание bitcode не требуется для Xcode 14 и более поздних версий.

kotlinArtifacts {
    Native.XCFramework("sdk") {
        targets(iosX64, iosArm64, iosSimulatorArm64)
        setModules(
            project(":shared"),
            project(":lib")
        )
    }
}

kotlinArtifacts {
    it.native.XCFramework("sdk") {
        targets(iosX64, iosArm64, iosSimulatorArm64)
        setModules(
            project(":shared"), 
            project(":lib")
        )
    }
}

Зарегистрированная задача Gradle — assembleSdkXCFramework — собирает все типы зарегистрированных "sdk" XCFrameworks.

Последнее изменение: 10 января 2023

© 2010–2023 JetBrains s.r.o. and Kotlin Programming Language contributors
Licensed under the Apache License, Version 2.0.
https://kotlinlang.org/docs/multiplatform-native-artifacts.html