Создание конечных нативных библиотек

По умолчанию, целевой объект Kotlin/Native компилируется в библиотеку *.klib артефакт, который может быть использован Kotlin/Native как зависимость, но не может быть запущен или использован как нативная библиотека.

Для объявления конечных нативных библиотек, таких как исполняемые файлы или динамические библиотеки, используйте свойство binaries целевого нативного объекта. Это свойство представляет собой набор нативных библиотек, построенных для этой цели дополнительно к стандартному *.klib артефакту и предоставляет набор методов для их объявления и настройки.

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

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

Используйте следующие фабричные методы для объявления элементов коллекции binaries.

Фабричный метод	Тип библиотеки	Доступно для
`executable`	Исполняемый файл продукта	Все нативные цели
`test`	Исполняемый файл теста	Все нативные цели
`sharedLib`	Динамическая нативная библиотека	Все нативные цели, кроме `WebAssembly`
`staticLib`	Статическая нативная библиотека	Все нативные цели, кроме `WebAssembly`
`framework`	Фреймворк Objective-C	Только цели macOS, iOS, watchOS и tvOS

Самый простой вариант не требует дополнительных параметров и создаёт одну библиотеку для каждого типа сборки. В настоящее время доступны два типа сборки:

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

Следующий фрагмент кода создаёт две исполняемые библиотеки, для отладки и релизной сборки:

kotlin {
    linuxX64 { // Define your target instead.
        binaries {
            executable {
                // Binary configuration.
            }
        }
    }
}

Вы можете убрать лямбда-выражение, если дополнительная настройка не требуется:

binaries {
    executable()
}

Вы можете указать, для каких типов сборки создавать библиотеки. В следующем примере создаётся только исполняемый файл debug.

binaries {
    executable(listOf(DEBUG)) {
        // Binary configuration.
    }
}

binaries {
    executable([DEBUG]) {
        // Binary configuration.
    }
}

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

binaries {
    executable("foo", listOf(DEBUG)) {
        // Binary configuration.
    }

    // It's possible to drop the list of build types
    // (in this case, all the available build types will be used).
    executable("bar") {
        // Binary configuration.
    }
}

binaries {
    executable('foo', [DEBUG]) {
        // Binary configuration.
    }

    // It's possible to drop the list of build types
    // (in this case, all the available build types will be used).
    executable('bar') {
        // Binary configuration.
    }
}

Первый аргумент задаёт префикс имени, который является стандартным именем для файла библиотеки. Например, для Windows код создаёт файлы foo.exe и bar.exe. Вы также можете использовать префикс имени для доступа к библиотеке в скрипте сборки.

Доступ к библиотекам

Вы можете получить доступ к библиотекам, чтобы настроить их или получить их свойства (например, путь к выходному файлу).

Вы можете получить доступ к библиотеке по её уникальному имени. Это имя основано на префиксе имени (если он указан), типе сборки и типу библиотеки, следуя шаблону: <optional-name-prefix><build-type><binary-kind>, например, releaseFramework или testDebugExecutable.

// Fails if there is no such binary.
binaries["fooDebugExecutable"]
binaries.getByName("fooDebugExecutable")

// Returns null if there is no such binary.
binaries.findByName("fooDebugExecutable")

// Fails if there is no such binary.
binaries['fooDebugExecutable']
binaries.fooDebugExecutable
binaries.getByName('fooDebugExecutable')

// Returns null if there is no such binary.
binaries.findByName('fooDebugExecutable')

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

// Fails if there is no such binary.
binaries.getExecutable("foo", DEBUG)
binaries.getExecutable(DEBUG)          // Skip the first argument if the name prefix isn't set.
binaries.getExecutable("bar", "DEBUG") // You also can use a string for build type.

// Similar getters are available for other binary kinds:
// getFramework, getStaticLib and getSharedLib.

// Returns null if there is no such binary.
binaries.findExecutable("foo", DEBUG)

// Similar getters are available for other binary kinds:
// findFramework, findStaticLib and findSharedLib.

// Fails if there is no such binary.
binaries.getExecutable('foo', DEBUG)
binaries.getExecutable(DEBUG)          // Skip the first argument if the name prefix isn't set.
binaries.getExecutable('bar', 'DEBUG') // You also can use a string for build type.

// Similar getters are available for other binary kinds:
// getFramework, getStaticLib and getSharedLib.

// Returns null if there is no such binary.
binaries.findExecutable('foo', DEBUG)

// Similar getters are available for other binary kinds:
// findFramework, findStaticLib and findSharedLib.

Экспорт зависимостей в библиотеки

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

kotlin {
    sourceSets {
        macosMain.dependencies {
            // Will be exported.
            api(project(":dependency"))
            api("org.example:exported-library:1.0")
            // Will not be exported.
            api("org.example:not-exported-library:1.0")
        }
    }
    macosX64("macos").binaries {
        framework {
            export(project(":dependency"))
            export("org.example:exported-library:1.0")
        }
        sharedLib {
            // It's possible to export different sets of dependencies to different binaries.
            export(project(':dependency'))
        }
    }
}

kotlin {
    sourceSets {
        macosMain.dependencies {
            // Will be exported.
            api project(':dependency')
            api 'org.example:exported-library:1.0'
            // Will not be exported.
            api 'org.example:not-exported-library:1.0'
        }
    }
    macosX64("macos").binaries {
        framework {
            export project(':dependency')
            export 'org.example:exported-library:1.0'
        }
        sharedLib {
            // It's possible to export different sets of dependencies to different binaries.
            export project(':dependency')
        }
    }
}

Например, вы реализуете несколько модулей на Kotlin и хотите получить к ним доступ из Swift. Использование нескольких Kotlin/Native фреймворков в приложении Swift ограничено, но вы можете создать фреймворк «зонт» и экспортировать все эти модули в него.

При экспорте зависимости, её весь API включается в API фреймворка. Компилятор добавляет код из этой зависимости в фреймворк, даже если вы используете только небольшую его часть. Это отключает удаление неиспользуемого кода для экспортируемой зависимости (и для зависимостей от неё, до некоторой степени).

По умолчанию, экспорт работает не транзитивно. Это означает, что если вы экспортируете библиотеку foo, зависящую от библиотеки bar, только методы foo будут добавлены в выходной фреймворк.

Вы можете изменить это поведение, используя опцию transitiveExport. Если она установлена в true, объявления библиотеки bar также будут экспортированы.

binaries {
    framework {
        export(project(":dependency"))
        // Export transitively.
        transitiveExport = true
    }
}

binaries {
    framework {
        export project(':dependency')
        // Export transitively.
        transitiveExport = true
    }
}

Создание универсальных фреймворков

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

import org.jetbrains.kotlin.gradle.tasks.FatFrameworkTask

kotlin {
    // Create and configure the targets.
    val ios32 = watchosArm32("watchos32")
    val ios64 = watchosArm64("watchos64")
    configure(listOf(watchos32, watchos64)) {
        binaries.framework {
            baseName = "my_framework"
        }
    }
    // Create a task to build a fat framework.
    tasks.register<FatFrameworkTask>("debugFatFramework") {
        // The fat framework must have the same base name as the initial frameworks.
        baseName = "my_framework"
        // The default destination directory is "<build directory>/fat-framework".
        destinationDir = buildDir.resolve("fat-framework/debug")
        // Specify the frameworks to be merged.
        from(
            ios32.binaries.getFramework("DEBUG"),
            ios64.binaries.getFramework("DEBUG")
        )
    }
}

import org.jetbrains.kotlin.gradle.tasks.FatFrameworkTask

kotlin {
    // Create and configure the targets.
    targets {
        watchosArm32("watchos32")
        watchosArm64("watchos64")
        configure([watchos32, watchos64]) {
            binaries.framework {
                baseName = "my_framework"
            }
        }
    }
    // Create a task building a fat framework.
    tasks.register("debugFatFramework", FatFrameworkTask) {
        // The fat framework must have the same base name as the initial frameworks.
        baseName = "my_framework"
        // The default destination directory is "<build directory>/fat-framework".
        destinationDir = file("$buildDir/fat-framework/debug")
        // Specify the frameworks to be merged.
        from(
            targets.ios32.binaries.getFramework("DEBUG"),
            targets.ios64.binaries.getFramework("DEBUG")
        )
    }
}

Создание XCFrameworks

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

import org.jetbrains.kotlin.gradle.plugin.mpp.apple.XCFramework

plugins {
    kotlin("multiplatform")
}

kotlin {
    val xcf = XCFramework()
    val iosTargets = listOf(iosX64(), iosArm64(), iosSimulatorArm64())
    
    iosTargets.forEach {
        it.binaries.framework {
            baseName = "shared"
            xcf.add(this)
        }
    }
}

import org.jetbrains.kotlin.gradle.plugin.mpp.apple.XCFrameworkConfig

plugins {
    id 'org.jetbrains.kotlin.multiplatform'
}

kotlin {
    def xcf = new XCFrameworkConfig(project)
    def iosTargets = [iosX64(), iosArm64(), iosSimulatorArm64()]
    
    iosTargets.forEach {
        it.binaries.framework {
            baseName = 'shared'
            xcf.add(it)
        }
    }
}

При объявлении XCFrameworks плагин Kotlin Gradle зарегистрирует три задачи Gradle:

assembleXCFramework
assembleDebugXCFramework (дополнительно артефакт отладки, содержащий dSYMs)
assembleReleaseXCFramework

Если вы используете интеграцию CocoaPods в своих проектах, вы можете создать XCFrameworks с помощью плагина Kotlin CocoaPods Gradle. Он включает в себя следующие задачи, которые создают XCFrameworks со всеми зарегистрированными целями и генерируют файлы podspec:

podPublishReleaseXCFramework, который генерирует релизный XCFramework вместе с файлом podspec.
podPublishDebugXCFramework, который генерирует отладочный XCFramework вместе с файлом podspec.
podPublishXCFramework, который генерирует как отладочный, так и релизный XCFrameworks вместе с файлом podspec.

Это может помочь вам распространять общие части вашего проекта отдельно от мобильных приложений через CocoaPods. Вы также можете использовать XCFrameworks для публикации в частных или публичных репозиториях podspec.

Настройка файла Info.plist

При создании фреймворка компилятор Kotlin/Native генерирует файл информации свойств Info.plist. Вы можете настроить его свойства с помощью соответствующего двоичного параметра:

Свойство	Двоичный параметр
`CFBundleIdentifier`	`bundleId`
`CFBundleShortVersionString`	`bundleShortVersionString`
`CFBundleVersion`	`bundleVersion`

Чтобы включить эту функцию, передайте флаг компилятора -Xbinary=$option=$value или установите Gradle DSL binaryOption("option", "value") для конкретного фреймворка:

binaries {
    framework {
        binaryOption("bundleId", "com.example.app")
        binaryOption("bundleVersion", "2")
    }
}

Последнее изменение: 24 мая 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-build-native-binaries.html