Нативные дистрибутивы

Плагин Gradle

Это руководство посвящено прежде всего упаковке приложений Compose с помощью плагина Compose Multiplatform Gradle. Плагин org.jetbrains.compose предоставляет задачи для базовой упаковки, обфускации и подписания кода для macOS.

Плагин упрощает упаковку приложений в нативные дистрибутивы с помощью jpackage и локальный запуск приложения. Дистрибутивные приложения — это автономные устанавливаемые двоичные файлы, которые включают все необходимые компоненты среды выполнения Java, поэтому устанавливать JDK в целевой системе не требуется.

Чтобы уменьшить размер пакета, плагин Gradle использует инструмент jlink, который позволяет включить в дистрибутивный пакет только необходимые модули Java. Однако необходимо настроить плагин Gradle, указав нужные модули. Подробнее см. в разделе Подключение модулей JDK.

В качестве альтернативы можно использовать Conveyor — внешний инструмент, разработанный не JetBrains. Conveyor поддерживает онлайн-обновления, кросс-сборку и ряд других функций, но для проектов с закрытым исходным кодом требуется лицензия. Подробнее см. в документации Conveyor.

Основные задачи

Основная настраиваемая единица плагина Compose Multiplatform Gradle — application (не путайте его с плагином Gradle application, который устарел).

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

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

• macOS: .dmg (TargetFormat.Dmg), .pkg (TargetFormat.Pkg)

• Windows: .exe (TargetFormat.Exe), .msi (TargetFormat.Msi)

• Linux: .deb (TargetFormat.Deb), .rpm (TargetFormat.Rpm)

Ниже приведен пример файла build.gradle.kts с базовой конфигурацией настольного приложения:

При сборке проекта плагин создает следующие задачи:

Все доступные задачи перечислены в окне инструментов Gradle. После выполнения задачи Gradle создает выходные двоичные файлы в каталоге ${project.buildDir}/compose/binaries.

Подключение модулей JDK

Чтобы уменьшить размер дистрибутива, плагин Gradle использует jlink, который помогает включить только необходимые модули JDK.

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

Если при запуске упакованного приложения или задачи runDistributable возникает ClassNotFoundException, можно подключить дополнительные модули JDK с помощью метода DSL modules:

compose.desktop {
    application {
        nativeDistributions {
            modules("java.sql")
            // Alternatively: includeAllModules = true
        }
    }
}

Необходимые модули можно указать вручную или запустить suggestModules. Задача suggestModules использует инструмент статического анализа jdeps, чтобы определить возможные отсутствующие модули. Обратите внимание, что вывод инструмента может быть неполным или содержать ненужные модули.

Если размер дистрибутива не имеет принципиального значения и им можно пренебречь, можно включить все модули среды выполнения с помощью свойства DSL includeAllModules.

Настройка свойств дистрибутива

compose.desktop {
    application {
        nativeDistributions {
            outputBaseDir.set(project.layout.buildDirectory.dir("customOutputDir"))
        }
    }
}

compose.desktop {
    application {
        mainClass = "MainKt"
        args += listOf("-customArgument")
        jvmArgs += listOf("-Xmx2G")
    }
}

compose.desktop {
    application {
        nativeDistributions {
            packageName = "ExampleApp"
            packageVersion = "0.1-SNAPSHOT"
            description = "Compose Multiplatform App"
            copyright = "© 2024 My Name. All rights reserved."
            vendor = "Example vendor"
            licenseFile.set(project.file("LICENSE.txt"))
        }
    }
}

Управление ресурсами

Для упаковки и загрузки ресурсов можно использовать библиотеку ресурсов Compose Multiplatform, загрузку ресурсов JVM или добавлять файлы в упакованные приложения.

compose.desktop {
    application {
        mainClass = "MainKt"
        nativeDistributions {
            targetFormats(TargetFormat.Dmg, TargetFormat.Msi, TargetFormat.Deb)
            packageVersion = "1.0.0"

            appResourcesRootDir.set(project.layout.projectDirectory.dir("resources"))
        }
    }
}

import java.io.File

val resourcesDir = File(System.getProperty("compose.application.resources.dir"))

fun main() {
    println(resourcesDir.resolve("resource.txt").readText())
}

Пользовательские наборы исходного кода

Можно использовать конфигурацию по умолчанию, если вы применяете плагины org.jetbrains.kotlin.jvm или org.jetbrains.kotlin.multiplatform:

• Конфигурация с org.jetbrains.kotlin.jvm включает содержимое набора исходного кода main source set.

• Конфигурация с org.jetbrains.kotlin.multiplatform включает содержимое одной целевой платформы JVM. Если задать несколько целевых платформ JVM, конфигурация по умолчанию отключается. В этом случае плагин необходимо настроить вручную или указать одну целевую платформу (см. ниже).

Если конфигурация по умолчанию неоднозначна или недостаточна, ее можно настроить несколькими способами:

С помощью набора исходного кода Gradle:

plugins {
    kotlin("jvm")
    id("org.jetbrains.compose")
}
val customSourceSet = sourceSets.create("customSourceSet")
compose.desktop {
    application {
        from(customSourceSet)
    }
}

С помощью целевой платформы JVM Kotlin:

plugins {
    kotlin("multiplatform")
    id("org.jetbrains.compose")
} 
kotlin {
    jvm("customJvmTarget") {}
}
compose.desktop {
    application {
        from(kotlin.targets["customJvmTarget"])
    }
}

Вручную:

• Используйте disableDefaultConfiguration, чтобы отключить настройки по умолчанию.

• Используйте fromFiles, чтобы указать включаемые файлы.

• Укажите свойство файла mainJar, ссылающееся на файл .jar с главным классом.

• Используйте dependsOn, чтобы добавить зависимости задач ко всем задачам плагина.

compose.desktop {
    application {
        disableDefaultConfiguration()
        fromFiles(project.fileTree("libs/") { include("**/*.jar") })
        mainJar.set(project.file("main.jar"))
        dependsOn("mainJarTask")
    }
}

Значок приложения

Убедитесь, что значок приложения представлен в следующих форматах для соответствующих ОС:

• .icns для macOS

• .ico для Windows

• .png для Linux

compose.desktop {
    application {
        nativeDistributions {
            macOS {
                iconFile.set(project.file("icon.icns"))
            }
            windows {
                iconFile.set(project.file("icon.ico"))
            }
            linux {
                iconFile.set(project.file("icon.png"))
            }
        }
    }
}

Платформо-зависимые параметры

Платформо-зависимые настройки можно задать с помощью соответствующих блоков DSL:

compose.desktop {
    application {
        nativeDistributions {
            macOS {
                // Options for macOS
            }
            windows {
                // Options for Windows
            }
            linux {
                // Options for Linux
            }
        }
    }
}

В следующей таблице описаны все поддерживаемые платформо-зависимые параметры. Не рекомендуется использовать недокументированные свойства.

Конфигурация для macOS

Минификация и обфускация

Плагин Compose Multiplatform для Gradle включает встроенную поддержку ProGuard. ProGuard — это инструмент с открытым исходным кодом для минификации и обфускации кода.

Для каждой задачи упаковки по умолчанию (без ProGuard) плагин Gradle предоставляет задачу release (с ProGuard):

Конфигурация по умолчанию включает несколько предопределенных правил ProGuard:

• Образ приложения минифицируется, то есть неиспользуемые классы удаляются.

• В качестве точки входа используется compose.desktop.application.mainClass.

• Добавлено несколько правил keep, чтобы среда выполнения Compose продолжала работать.

В большинстве случаев для создания минифицированного приложения дополнительная конфигурация не требуется. Однако ProGuard может не отслеживать некоторые способы использования в байт-коде, например обращение к классу через рефлексию. Если проблемы возникают только после обработки ProGuard, может потребоваться добавить пользовательские правила.

Настроить ProGuard можно с помощью DSL Gradle в блоке buildTypes.release.proguard, используя следующие параметры:

• configurationFiles задает пользовательские файлы конфигурации ProGuard.

  compose.desktop { application { buildTypes.release.proguard { configurationFiles.from(project.file("compose-desktop.pro")) } } }

• obfuscate включает обфускацию кода. По умолчанию обфускация отключена.

  compose.desktop { application { buildTypes.release.proguard { obfuscate.set(true) } } }

• optimize управляет оптимизациями ProGuard. По умолчанию оптимизации включены.

  compose.desktop { application { buildTypes.release.proguard { optimize.set(false) } } }

• joinOutputJars создает один uber-JAR. По умолчанию ProGuard создает отдельный файл .jar для каждого входного .jar.

  compose.desktop { application { buildTypes.release.proguard { joinOutputJars.set(true) } } }

• version задает конкретную версию ProGuard. Для JDK 25 требуется ProGuard версии не ниже 7.8.0. Эта версия используется по умолчанию начиная с Compose Multiplatform 1.12.0. Если вы используете более раннюю версию Compose Multiplatform и выполняете сборку с JDK 25, явно задайте для этого свойства значение 7.8.0:

  compose.desktop { application { buildTypes.release.proguard { version.set("7.8.0") } } }

Полный список правил ProGuard и параметров конфигурации см. в руководстве по ProGuard от Guardsquare.

Что дальше?

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