네이티브 배포

여기서는 네이티브 배포에 대해 알아봅니다. 지원되는 모든 시스템에 대한 설치 프로그램 및 패키지를 생성하는 방법과 배포와 동일한 설정으로 애플리케이션을 로컬에서 실행하는 방법을 다룹니다.

다음 주제에 대한 자세한 내용은 계속해서 읽어보십시오.

• Compose Multiplatform Gradle 플러그인이란 무엇인가요?
• 애플리케이션을 로컬에서 실행하는 것과 같은 기본 태스크와 코드 압축 및 난독화와 같은 고급 태스크에 대한 세부 정보.
• JDK 모듈을 포함하는 방법 및 ClassNotFoundException 처리.
• 배포 속성을 지정하는 방법: 패키지 버전, JDK 버전, 출력 디렉터리, 런처 속성 및 메타데이터.
• 리소스 라이브러리, JVM 리소스 로딩, 또는 패키지된 애플리케이션에 파일을 추가하여 리소스를 관리하는 방법.
• Gradle 소스 세트, Kotlin JVM 타겟, 또는 수동으로 사용자 지정 소스 세트를 설정하는 방법.
• 각 OS에 대해 애플리케이션 아이콘을 지정하는 방법.
• Linux에서 패키지 관리자의 이메일, macOS에서 Apple App Store의 앱 카테고리와 같은 플랫폼별 옵션.
• macOS별 구성: 코드 서명, 공증 및 Info.plist.

Gradle 플러그인

이 가이드는 주로 Compose Multiplatform Gradle 플러그인을 사용하여 Compose 애플리케이션을 패키징하는 데 중점을 둡니다. org.jetbrains.compose 플러그인은 기본 패키징, 난독화 및 macOS 코드 서명 작업을 제공합니다.

이 플러그인은 jpackage를 사용하여 애플리케이션을 네이티브 배포로 패키징하고 애플리케이션을 로컬에서 실행하는 프로세스를 단순화합니다. 배포 가능한 애플리케이션은 자체 포함된(self-contained) 설치 가능한 바이너리로, 대상 시스템에 JDK가 설치되어 있지 않아도 필요한 모든 Java 런타임 구성 요소를 포함합니다.

패키지 크기를 최소화하기 위해 Gradle 플러그인은 jlink 도구를 사용하여 배포 가능한 패키지에 필요한 Java 모듈만 번들링하도록 합니다. 그러나 필요한 모듈을 지정하려면 Gradle 플러그인을 구성해야 합니다. 자세한 내용은 JDK 모듈 포함 섹션을 참조하십시오.

대안으로 JetBrains에서 개발하지 않은 외부 도구인 Conveyor를 사용할 수 있습니다. Conveyor는 온라인 업데이트, 교차 빌딩 및 기타 다양한 기능을 지원하지만, 오픈 소스가 아닌 프로젝트에는 라이선스가 필요합니다. 자세한 내용은 Conveyor 문서를 참조하십시오.

기본 태스크

Compose Multiplatform Gradle 플러그인의 기본 구성 가능 단위는 application입니다 (더 이상 사용되지 않는 Gradle application 플러그인과 혼동하지 마십시오).

application DSL 메서드는 최종 바이너리 세트에 대한 공유 구성을 정의합니다. 이는 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 파일의 예시입니다.

import org.jetbrains.compose.desktop.application.dsl.TargetFormat

plugins {
    kotlin("jvm")
    id("org.jetbrains.compose")
}

dependencies {
    implementation(compose.desktop.currentOs)
}

compose.desktop {
    application {
        mainClass = "example.MainKt"

        nativeDistributions {
            targetFormats(TargetFormat.Dmg, TargetFormat.Msi, TargetFormat.Exe)
        }
    }
}

프로젝트를 빌드하면 플러그인은 다음 태스크를 생성합니다.

Gradle 태스크	설명
package<FormatName>	애플리케이션을 해당 FormatName 바이너리로 패키징합니다. 교차 컴파일은 현재 지원되지 않으므로, 호환되는 OS를 사용해야만 특정 형식을 빌드할 수 있습니다. 예를 들어, .dmg 바이너리를 빌드하려면 macOS에서 packageDmg 태스크를 실행해야 합니다. 만약 현재 OS와 호환되지 않는 태스크가 있다면, 기본적으로 건너뛰어집니다.
packageDistributionForCurrentOS	애플리케이션에 대한 모든 패키지 태스크를 집계합니다. 이는 수명 주기 태스크입니다.
packageUberJarForCurrentOS	현재 운영 체제에 대한 모든 의존성을 포함하는 단일 JAR 파일을 생성합니다. 이 태스크는 compose.desktop.currentOS가 compile, implementation, 또는 runtime 의존성으로 사용될 것을 예상합니다.
run	mainClass에 지정된 진입점에서 애플리케이션을 로컬에서 실행합니다. run 태스크는 전체 런타임을 사용하여 비패키지 JVM 애플리케이션을 시작합니다. 이 접근 방식은 압축된 런타임으로 컴팩트 바이너리 이미지를 생성하는 것보다 빠르고 디버깅하기 쉽습니다. 최종 바이너리 이미지를 실행하려면 대신 runDistributable 태스크를 사용하십시오.
createDistributable	설치 프로그램을 생성하지 않고 최종 애플리케이션 이미지를 생성합니다.
runDistributable	사전 패키지된 애플리케이션 이미지를 실행합니다.

사용 가능한 모든 태스크는 Gradle 도구 창에 나열됩니다. 태스크를 실행하면 Gradle은 ${project.buildDir}/compose/binaries 디렉터리에 출력 바이너리를 생성합니다.

JDK 모듈 포함

배포 가능한 크기를 줄이기 위해 Gradle 플러그인은 필요한 JDK 모듈만 번들링하는 데 도움이 되는 jlink를 사용합니다.

현재 Gradle 플러그인은 필요한 JDK 모듈을 자동으로 결정하지 않습니다. 이는 컴파일 문제를 일으키지 않지만, 필요한 모듈을 제공하지 않으면 런타임에 ClassNotFoundException이 발생할 수 있습니다.

패키지된 애플리케이션 또는 runDistributable 태스크를 실행할 때 ClassNotFoundException이 발생하면, modules DSL 메서드를 사용하여 추가 JDK 모듈을 포함할 수 있습니다.

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

필요한 모듈을 수동으로 지정하거나 suggestModules를 실행할 수 있습니다. suggestModules 태스크는 jdeps 정적 분석 도구를 사용하여 누락될 수 있는 모듈을 결정합니다. 이 도구의 출력이 불완전하거나 불필요한 모듈을 나열할 수 있다는 점에 유의하십시오.

배포 가능 파일의 크기가 중요한 요소가 아니고 무시할 수 있다면, includeAllModules DSL 속성을 사용하여 모든 런타임 모듈을 포함하도록 선택할 수 있습니다.

배포 속성 지정

패키지 버전

네이티브 배포 패키지에는 특정 패키지 버전이 있어야 합니다. 패키지 버전을 지정하려면 다음 DSL 속성을 가장 높은 우선순위부터 가장 낮은 우선순위 순으로 사용할 수 있습니다.

• nativeDistributions.<os>.<packageFormat>PackageVersion은 단일 패키지 형식에 대한 버전을 지정합니다.
• nativeDistributions.<os>.packageVersion은 단일 대상 OS에 대한 버전을 지정합니다.
• nativeDistributions.packageVersion은 모든 패키지에 대한 버전을 지정합니다.

macOS에서는 다음 DSL 속성을 사용하여 빌드 버전을 지정할 수도 있습니다(다시 가장 높은 우선순위부터 가장 낮은 우선순위 순으로 나열됨).

• nativeDistributions.macOS.<packageFormat>PackageBuildVersion은 단일 패키지 형식에 대한 빌드 버전을 지정합니다.
• nativeDistributions.macOS.packageBuildVersion은 모든 macOS 패키지에 대한 빌드 버전을 지정합니다.

빌드 버전을 지정하지 않으면 Gradle은 패키지 버전을 대신 사용합니다. macOS 버전 관리에 대한 자세한 내용은 CFBundleShortVersionString 및 CFBundleVersion 문서를 참조하십시오.

다음은 우선순위 순으로 패키지 버전을 지정하기 위한 템플릿입니다.

compose.desktop {
    application {
        nativeDistributions {
            // Version for all packages
            packageVersion = "..." 
          
            macOS {
              // Version for all macOS packages
              packageVersion = "..."
              // Version for the dmg package only
              dmgPackageVersion = "..." 
              // Version for the pkg package only
              pkgPackageVersion = "..." 
              
              // Build version for all macOS packages
              packageBuildVersion = "..."
              // Build version for the dmg package only
              dmgPackageBuildVersion = "..." 
              // Build version for the pkg package only
              pkgPackageBuildVersion = "..." 
            }
            windows {
              // Version for all Windows packages
              packageVersion = "..."  
              // Version for the msi package only
              msiPackageVersion = "..."
              // Version for the exe package only
              exePackageVersion = "..." 
            }
            linux {
              // Version for all Linux packages
              packageVersion = "..."
              // Version for the deb package only
              debPackageVersion = "..."
              // Version for the rpm package only
              rpmPackageVersion = "..."
            }
        }
    }
}

패키지 버전을 정의하려면 다음 규칙을 따르십시오.

파일 형식	버전 형식	세부 정보
dmg, pkg	MAJOR[.MINOR][.PATCH]	MAJOR는 0보다 큰 정수입니다. MINOR는 선택적 음이 아닌 정수입니다. PATCH는 선택적 음이 아닌 정수입니다.
msi, exe	MAJOR.MINOR.BUILD	MAJOR는 최대값 255를 가진 음이 아닌 정수입니다. MINOR는 최대값 255를 가진 음이 아닌 정수입니다. BUILD는 최대값 65535를 가진 음이 아닌 정수입니다.
deb	[EPOCH:]UPSTREAM_VERSION[-DEBIAN_REVISION]	EPOCH는 선택적 음이 아닌 정수입니다. UPSTREAM_VERSION: 영숫자와 ., +, -, ~ 문자만 포함할 수 있습니다. 숫자로 시작해야 합니다. DEBIAN_REVISION: 선택 사항 영숫자와 ., +, ~ 문자만 포함할 수 있습니다. 자세한 내용은 Debian 문서를 참조하십시오.
rpm	모든 형식	버전은 - (대시) 문자를 포함해서는 안 됩니다.

JDK 버전

플러그인은 JDK 17 이상 버전을 요구하는 jpackage를 사용합니다. JDK 버전을 지정할 때는 다음 요구 사항 중 하나 이상을 충족하는지 확인하십시오.

• JAVA_HOME 환경 변수가 호환되는 JDK 버전을 가리킵니다.
• javaHome 속성이 DSL을 통해 설정됩니다.

compose.desktop {
    application {
        javaHome = System.getenv("JDK_17")
    }
}

출력 디렉터리

네이티브 배포판에 사용자 지정 출력 디렉터리를 사용하려면 다음과 같이 outputBaseDir 속성을 구성하십시오.

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

런처 속성

애플리케이션 시작 프로세스를 사용자 지정하려면 다음 속성을 구성할 수 있습니다.

속성	설명
mainClass	main 메서드를 포함하는 클래스의 정규화된 이름입니다.
args	애플리케이션의 main 메서드에 대한 인수입니다.
jvmArgs	애플리케이션의 JVM에 대한 인수입니다.

다음은 구성 예시입니다.

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

메타데이터

nativeDistributions DSL 블록 내에서 다음 속성을 구성할 수 있습니다.

속성	설명	기본값
packageName	애플리케이션 이름입니다.	Gradle 프로젝트의 이름
packageVersion	애플리케이션 버전입니다.	Gradle 프로젝트의 버전
description	애플리케이션 설명입니다.	없음
copyright	애플리케이션의 저작권 정보입니다.	없음
vendor	애플리케이션 공급업체입니다.	없음
licenseFile	애플리케이션의 라이선스 파일입니다.	없음

다음은 구성 예시입니다.

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 리소스 로딩, 또는 패키지된 애플리케이션에 파일을 추가하는 방법을 사용할 수 있습니다.

리소스 라이브러리

프로젝트에 리소스를 설정하는 가장 간단한 방법은 리소스 라이브러리를 사용하는 것입니다. 리소스 라이브러리를 사용하면 지원되는 모든 플랫폼에서 공통 코드 내 리소스에 접근할 수 있습니다. 자세한 내용은 멀티플랫폼 리소스를 참조하십시오.

JVM 리소스 로딩

데스크톱용 Compose Multiplatform은 JVM 플랫폼에서 작동하므로 java.lang.Class API를 사용하여 .jar 파일에서 리소스를 로드할 수 있습니다. src/main/resources 디렉터리에 있는 파일은 Class::getResource 또는 Class::getResourceAsStream을 통해 접근할 수 있습니다.

패키지된 애플리케이션에 파일 추가

.jar 파일에서 리소스를 로드하는 것이 덜 실용적인 시나리오가 있습니다. 예를 들어, 대상별 자산이 있어서 macOS 패키지에만 파일을 포함하고 Windows 패키지에는 포함하지 않으려는 경우입니다.

이러한 경우 Gradle 플러그인을 구성하여 설치 디렉터리에 추가 리소스 파일을 포함할 수 있습니다. 다음과 같이 DSL을 사용하여 루트 리소스 디렉터리를 지정하십시오.

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

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

위 예시에서 루트 리소스 디렉터리는 <PROJECT_DIR>/resources로 정의됩니다.

Gradle 플러그인은 다음과 같이 리소스 하위 디렉터리에서 파일을 포함합니다.

1. 공통 리소스:<RESOURCES_ROOT_DIR>/common에 있는 파일은 대상 OS나 아키텍처에 관계없이 모든 패키지에 포함됩니다.

2. OS별 리소스:<RESOURCES_ROOT_DIR>/<OS_NAME>에 있는 파일은 특정 운영 체제용으로 빌드된 패키지에만 포함됩니다. <OS_NAME>에 유효한 값은 windows, macos, linux입니다.

3. OS 및 아키텍처별 리소스:<RESOURCES_ROOT_DIR>/<OS_NAME>-<ARCH_NAME>에 있는 파일은 특정 운영 체제 및 CPU 아키텍처 조합용으로 빌드된 패키지에만 포함됩니다. <ARCH_NAME>에 유효한 값은 x64와 arm64입니다. 예를 들어, <RESOURCES_ROOT_DIR>/macos-arm64의 파일은 Apple Silicon Mac용 패키지에만 포함됩니다.

포함된 리소스는 compose.application.resources.dir 시스템 속성을 사용하여 접근할 수 있습니다.

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 소스 세트의 내용을 포함합니다.
• org.jetbrains.kotlin.multiplatform을 사용한 구성은 단일 JVM 타겟의 내용을 포함합니다. 여러 JVM 타겟을 정의하는 경우 기본 구성은 비활성화됩니다. 이 경우 플러그인을 수동으로 구성하거나 단일 타겟을 지정해야 합니다(아래 참조).

기본 구성이 모호하거나 불충분한 경우 여러 가지 방법으로 사용자 지정할 수 있습니다.

Gradle 소스 세트 사용:

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

Kotlin JVM 타겟 사용:

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")
    }
}

애플리케이션 아이콘

앱 아이콘이 다음 OS별 형식으로 사용 가능한지 확인하십시오.

• macOS용 .icns
• Windows용 .ico
• Linux용 .png

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
            }
        }
    }
}

다음 표는 지원되는 모든 플랫폼별 옵션을 설명합니다. 문서화되지 않은 속성은 사용하지 않는 것이 좋습니다.

플랫폼	옵션	설명
모든 플랫폼	iconFile.set(File("PATH_TO_ICON"))	애플리케이션에 대한 플랫폼별 아이콘 경로를 지정합니다. 자세한 내용은 애플리케이션 아이콘 섹션을 참조하십시오.
	packageVersion = "1.0.0"	플랫폼별 패키지 버전을 설정합니다. 자세한 내용은 패키지 버전 섹션을 참조하십시오.
	installationPath = "PATH_TO_INST_DIR"	기본 설치 디렉터리에 대한 절대 또는 상대 경로를 지정합니다. Windows에서는 dirChooser = true를 사용하여 설치 중 경로 사용자 지정을 활성화할 수도 있습니다.
Linux	packageName = "custom-package-name"	기본 애플리케이션 이름을 재정의합니다.
	debMaintainer = "[email protected]"	패키지 관리자의 이메일을 지정합니다.
	menuGroup = "my-example-menu-group"	애플리케이션에 대한 메뉴 그룹을 정의합니다.
	appRelease = "1"	rpm 패키지의 릴리스 값 또는 deb 패키지의 개정(revision) 값을 설정합니다.
	appCategory = "CATEGORY"	rpm 패키지의 그룹 값 또는 deb 패키지의 섹션 값을 할당합니다.
	rpmLicenseType = "TYPE_OF_LICENSE"	rpm 패키지의 라이선스 유형을 나타냅니다.
	debPackageVersion = "DEB_VERSION"	deb 특정 패키지 버전을 설정합니다. 자세한 내용은 패키지 버전 섹션을 참조하십시오.
	rpmPackageVersion = "RPM_VERSION"	rpm 특정 패키지 버전을 설정합니다. 자세한 내용은 패키지 버전 섹션을 참조하십시오.
macOS	bundleID	영숫자(A-Z, a-z, 0-9), 하이픈(-), 그리고 점(.)만 포함할 수 있는 고유한 애플리케이션 식별자를 지정합니다. 역방향 DNS 표기법(com.mycompany.myapp)을 사용하는 것이 좋습니다.
	packageName	애플리케이션 이름입니다.
	dockName	메뉴 바, "About <App>" 메뉴 항목, 및 독(dock)에 표시되는 애플리케이션 이름입니다. 기본값은 packageName입니다.
	minimumSystemVersion	애플리케이션을 실행하는 데 필요한 최소 macOS 버전입니다. 자세한 내용은 LSMinimumSystemVersion을 참조하십시오.
	signing, notarization, provisioningProfile, runtimeProvisioningProfile	macOS용 배포판 서명 및 공증 튜토리얼을 참조하십시오.
	appStore = true	Apple App Store용으로 앱을 빌드하고 서명할지 여부를 지정합니다. JDK 17 이상이 필요합니다.
	appCategory	Apple App Store용 앱 카테고리입니다. App Store용으로 빌드할 때 기본값은 public.app-category.utilities이고, 그렇지 않으면 Unknown입니다. 유효한 카테고리 목록은 LSApplicationCategoryType를 참조하십시오.
	entitlementsFile.set(File("PATH_ENT"))	서명 시 사용되는 권한(entitlements)이 포함된 파일의 경로를 지정합니다. 사용자 지정 파일을 제공할 때, Java 애플리케이션에 필요한 권한을 추가해야 합니다. App Store용으로 빌드할 때 사용되는 기본 파일은 sandbox.plist를 참조하십시오. 이 기본 파일은 JDK 버전에 따라 다를 수 있습니다. 파일을 지정하지 않으면 플러그인은 jpackage가 제공하는 기본 권한을 사용합니다. 자세한 내용은 macOS용 배포판 서명 및 공증 튜토리얼을 참조하십시오.
	runtimeEntitlementsFile.set(File("PATH_R_ENT"))	JVM 런타임 서명 시 사용되는 권한이 포함된 파일의 경로를 지정합니다. 사용자 지정 파일을 제공할 때, Java 애플리케이션에 필요한 권한을 추가해야 합니다. App Store용으로 빌드할 때 사용되는 기본 파일은 sandbox.plist를 참조하십시오. 이 기본 파일은 JDK 버전에 따라 다를 수 있습니다. 파일을 지정하지 않으면 플러그인은 jpackage가 제공하는 기본 권한을 사용합니다. 자세한 내용은 macOS용 배포판 서명 및 공증 튜토리얼을 참조하십시오.
	dmgPackageVersion = "DMG_VERSION"	DMG 특정 패키지 버전을 설정합니다. 자세한 내용은 패키지 버전 섹션을 참조하십시오.
	pkgPackageVersion = "PKG_VERSION"	PKG 특정 패키지 버전을 설정합니다. 자세한 내용은 패키지 버전 섹션을 참조하십시오.
	packageBuildVersion = "DMG_VERSION"	패키지 빌드 버전을 설정합니다. 자세한 내용은 패키지 버전 섹션을 참조하십시오.
	dmgPackageBuildVersion = "DMG_VERSION"	DMG 특정 패키지 빌드 버전을 설정합니다. 자세한 내용은 패키지 버전 섹션을 참조하십시오.
	pkgPackageBuildVersion = "PKG_VERSION"	PKG 특정 패키지 빌드 버전을 설정합니다. 자세한 내용은 패키지 버전 섹션을 참조하십시오.
	infoPlist	macOS의 Info.plist 섹션을 참조하십시오.
Windows	console = true	애플리케이션에 콘솔 런처를 추가합니다.
	dirChooser = true	설치 중 설치 경로 사용자 지정을 활성화합니다.
	perUserInstall = true	애플리케이션을 사용자별로 설치하는 것을 활성화합니다.
	menuGroup = "start-menu-group"	지정된 시작 메뉴 그룹에 애플리케이션을 추가합니다.
	upgradeUuid = "UUID"	사용자가 설치된 버전보다 최신 버전이 있을 때 설치 프로그램을 통해 애플리케이션을 업데이트할 수 있도록 하는 고유 ID를 지정합니다. 이 값은 단일 애플리케이션에 대해 일정하게 유지되어야 합니다. 자세한 내용은 How To: GUID 생성을 참조하십시오.
	msiPackageVersion = "MSI_VERSION"	MSI 특정 패키지 버전을 설정합니다. 자세한 내용은 패키지 버전 섹션을 참조하십시오.
	exePackageVersion = "EXE_VERSION"	EXE 특정 패키지 버전을 설정합니다. 자세한 내용은 패키지 버전 섹션을 참조하십시오.

macOS별 구성

macOS에서 코드 서명 및 공증

최신 macOS 버전은 인터넷에서 다운로드한 서명되지 않은 애플리케이션의 실행을 허용하지 않습니다. 이러한 애플리케이션을 실행하려고 하면 다음과 같은 오류가 발생합니다. "YourApp is damaged and can't be open. You should eject the disk image" (YourApp이 손상되어 열 수 없습니다. 디스크 이미지를 추출해야 합니다).

애플리케이션을 서명하고 공증하는 방법은 튜토리얼을 참조하십시오.

macOS의 정보 속성 목록

DSL은 필수적인 플랫폼별 사용자 지정을 지원하지만, 제공되는 기능을 넘어설 수 있는 경우가 여전히 있을 수 있습니다. DSL에 표현되지 않은 Info.plist 값을 지정해야 하는 경우, 원시 XML 스니펫을 해결 방법으로 포함할 수 있습니다. 이 XML은 애플리케이션의 Info.plist에 추가됩니다.

예시: 딥 링크

1. build.gradle.kts 파일에 사용자 지정 URL 스키마를 정의합니다.

compose.desktop {
    application {
        mainClass = "MainKt"
        nativeDistributions {
            targetFormats(TargetFormat.Dmg)
            packageName = "Deep Linking Example App"
            macOS {
                bundleID = "org.jetbrains.compose.examples.deeplinking"
                infoPlist {
                    extraKeysRawXml = macExtraPlistKeys
                }
            }
        }
    }
}

val macExtraPlistKeys: String
    get() = """
      <key>CFBundleURLTypes</key>
      <array>
        <dict>
          <key>CFBundleURLName</key>
          <string>Example deep link</string>
          <key>CFBundleURLSchemes</key>
          <array>
            <string>compose</string>
          </array>
        </dict>
      </array>
    """

2. src/main/main.kt 파일에서 java.awt.Desktop 클래스를 사용하여 URI 핸들러를 설정합니다.

import androidx.compose.material.MaterialTheme
import androidx.compose.material.Text
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.setValue
import androidx.compose.ui.window.singleWindowApplication
import java.awt.Desktop

fun main() {
    var text by mutableStateOf("Hello, World!")

    try {
        Desktop.getDesktop().setOpenURIHandler { event ->
            text = "Open URI: " + event.uri
        }
    } catch (e: UnsupportedOperationException) {
        println("setOpenURIHandler is unsupported")
    }

    singleWindowApplication {
        MaterialTheme {
            Text(text)
        }
    }
}

3. runDistributable 태스크를 실행합니다. ./gradlew runDistributable.

결과적으로 compose://foo/bar와 같은 링크는 이제 브라우저에서 애플리케이션으로 리디렉션될 수 있습니다.

코드 압축 및 난독화

Compose Multiplatform Gradle 플러그인에는 ProGuard에 대한 내장 지원이 포함되어 있습니다. ProGuard는 코드 압축 및 난독화를 위한 오픈 소스 도구입니다.

각 기본 (ProGuard 없음) 패키징 태스크에 대해 Gradle 플러그인은 릴리스 (ProGuard 포함) 태스크를 제공합니다.

Gradle 태스크	설명
기본: createDistributable 릴리스: createReleaseDistributable	번들된 JDK 및 리소스를 사용하여 애플리케이션 이미지를 생성합니다.
기본: runDistributable 릴리스: runReleaseDistributable	번들된 JDK 및 리소스를 사용하여 애플리케이션 이미지를 실행합니다.
기본: run 릴리스: runRelease	Gradle JDK를 사용하여 비패키지 애플리케이션 .jar를 실행합니다.
기본: package<FORMAT_NAME> 릴리스: packageRelease<FORMAT_NAME>	애플리케이션 이미지를 <FORMAT_NAME> 파일로 패키징합니다.
기본: packageDistributionForCurrentOS 릴리스: packageReleaseDistributionForCurrentOS	애플리케이션 이미지를 현재 OS와 호환되는 형식으로 패키징합니다.
기본: packageUberJarForCurrentOS 릴리스: packageReleaseUberJarForCurrentOS	애플리케이션 이미지를 우버 (팻) .jar로 패키징합니다.
기본: notarize<FORMAT_NAME> 릴리스: notarizeRelease<FORMAT_NAME>	공증을 위해 <FORMAT_NAME> 애플리케이션 이미지를 업로드합니다 (macOS 전용).
기본: checkNotarizationStatus 릴리스: checkReleaseNotarizationStatus	공증 성공 여부를 확인합니다 (macOS 전용).

기본 구성은 미리 정의된 일부 ProGuard 규칙을 활성화합니다.

• 애플리케이션 이미지는 코드 압축되어 사용되지 않는 클래스가 제거됩니다.
• compose.desktop.application.mainClass가 진입점으로 사용됩니다.
• Compose 런타임이 계속 작동하도록 여러 keep 규칙이 포함됩니다.

대부분의 경우, 압축된 애플리케이션을 얻기 위해 추가 구성은 필요하지 않습니다. 그러나 ProGuard는 리플렉션을 통해 클래스가 사용되는 경우와 같이 특정 사용을 바이트코드에서 추적하지 못할 수 있습니다. ProGuard 처리 후에만 발생하는 문제가 발생하면 사용자 지정 규칙을 추가해야 할 수 있습니다.

사용자 지정 구성 파일을 지정하려면 다음과 같이 DSL을 사용하십시오.

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

ProGuard 규칙 및 구성 옵션에 대한 자세한 내용은 Guardsquare 매뉴얼을 참조하십시오.

난독화는 기본적으로 비활성화되어 있습니다. 활성화하려면 Gradle DSL을 통해 다음 속성을 설정하십시오.

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

ProGuard의 최적화는 기본적으로 활성화되어 있습니다. 비활성화하려면 Gradle DSL을 통해 다음 속성을 설정하십시오.

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

우버 JAR 생성은 기본적으로 비활성화되어 있으며, ProGuard는 각 입력 .jar에 대해 해당하는 .jar 파일을 생성합니다. 활성화하려면 Gradle DSL을 통해 다음 속성을 설정하십시오.

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

다음 단계는?

데스크톱 구성 요소에 대한 튜토리얼을 살펴보십시오.