Guide가이드
Choosing a runtime path런타임 경로 고르기
One Python package, three ways the host can run it: default Compose JVM, GraalVM native-image, or Kotlin/Native desktop.하나의 파이썬 패키지를 세 가지 호스트 경로에서 그대로 실행합니다: 기본 Compose JVM, GraalVM 네이티브 이미지, Kotlin/Native 데스크톱.
partial · #110부분 · #110
pythonx-compose is pure Python 3.11+ with zero JVM reflection or AWT calls (tests/test_legacy_modules.py). It runs unchanged on the default JVM desktop path and on the extended fork's GraalVM native-image path (both verified across all 20 UI.ipynb scenarios in CI). On Kotlin/Native desktop, the binder supports macosArm64 and linuxX64 (python-multiplatform #370); the Compose host module for those targets is in progress.
pythonx-compose 는 JVM 리플렉션이나 AWT 호출이 전혀 없는 순수 파이썬 3.11+ 패키지입니다(tests/test_legacy_modules.py). 기본 JVM 데스크톱 경로와 extended 포크의 GraalVM 네이티브 이미지 경로에서 수정 없이 그대로 동작하며, 두 경로 모두 CI 에서 20 개 UI.ipynb 시나리오를 통과합니다. Kotlin/Native 데스크톱은 바인더가 macosArm64 와 linuxX64 를 지원하며(python-multiplatform #370), 해당 타겟의 Compose 호스트 모듈은 진행 중입니다.
Why the Python code never changes파이썬 코드가 바뀌지 않는 이유
Every widget, modifier, object and state in pythonx.compose resolves through the build-time table that python-multiplatform generates and registers under androidx.compose.*. Because nothing in pythonx/ calls jclass, JNI reflection, or AWT directly, your Python files and the installed pythonx-compose wheel stay identical whichever host path you pick.
pythonx.compose 의 모든 위젯, 모디파이어, 객체, 상태는 python-multiplatform 이 빌드 타임에 생성해 androidx.compose.* 아래에 등록하는 테이블을 통해 해석됩니다. pythonx/ 안의 어떤 코드도 jclass, JNI 리플렉션, AWT 를 직접 부르지 않으므로, 어느 호스트 경로를 고르든 파이썬 코드와 설치된 pythonx-compose wheel 은 똑같습니다.
# 1. Add pythonx-compose to your Python environment with uv:
uv add --prerelease allow pythonx-compose
# 2. Or, in a pypackpack workspace:
ppp core add "pythonx-compose==0.1.0a2"
# 3. Or, with toolchain-lite:
tcl install pythonx-compose
Comparing the three paths세 경로 비교
| Path경로 | Gradle pluginGradle 플러그인 | Host runtime호스트 런타임 | When to choose언제 고르는가 |
|---|---|---|---|
| 1. Default Compose JVM1. 기본 Compose JVM | org.thisisthepy.compose | JVM + embedded CPythonJVM + 임베딩된 CPython | Fastest edit-run cycle, full JVM ecosystem, and live notebook reloading.가장 빠른 수정·실행 주기, 전체 JVM 생태계, 라이브 노트북 리로딩. |
| 2. Extended GraalVM native-image2. Extended GraalVM 네이티브 이미지 | org.thisisthepy.compose | Ahead-of-time native binary (no libjvm, -Dcompose.awt=false) + embedded CPythonAOT 네이티브 바이너리 (libjvm 없음, -Dcompose.awt=false) + 임베딩된 CPython | Single desktop binary with instant startup and no JDK required on the user's machine.사용자 기기에 JDK 없이 즉시 시작되는 단일 데스크톱 바이너리. |
| 3. Extended Kotlin/Native desktop3. Extended Kotlin/Native 데스크톱 | org.thisisthepy.kotlin.native.desktop | Kotlin/Native (macosArm64, linuxX64) + embedded CPython via cinteropKotlin/Native (macosArm64, linuxX64) + cinterop CPython 임베딩 | Native compilation without a JVM or GraalVM toolchain; shares Kotlin/Native targets with iOS/desktop libraries.JVM 이나 GraalVM 툴체인 없는 네이티브 컴파일; iOS·데스크톱 라이브러리와 Kotlin/Native 타겟 공유. |
Path 1: Default Compose JVM경로 1: 기본 Compose JVM
The snippets below use python-multiplatform 3.15.0-alpha03, its first Maven Central release. It is not published yet (python-multiplatform #377), so org.thisisthepy.python.multiplatform.bindings does not resolve from mavenCentral() until that release lands.
아래 예시는 python-multiplatform 의 첫 Maven Central 릴리스인 3.15.0-alpha03 을 씁니다. 아직 배포되지 않았으므로(python-multiplatform #377), 그 릴리스가 나오기 전까지 org.thisisthepy.python.multiplatform.bindings 는 mavenCentral() 에서 해석되지 않습니다.
The standard desktop JVM target uses the extended Compose plugin (org.thisisthepy.compose:1.11.1-ext.3) and libraries (org.thisisthepy.compose.*:1.11.1-ext.2) from Maven Central, or upstream JetBrains Compose where native-image is not needed. All 20 scenarios of UI.ipynb pass on this path in CI (:python-multiplatform-compose:fixtures:notebook-e2e:desktopTest).
표준 데스크톱 JVM 타겟은 Maven Central 의 extended Compose 플러그인(org.thisisthepy.compose:1.11.1-ext.3)과 라이브러리(org.thisisthepy.compose.*:1.11.1-ext.2), 또는 네이티브 이미지가 필요 없는 곳에서는 업스트림 JetBrains Compose 를 씁니다. UI.ipynb 의 20 개 시나리오 전체가 이 경로의 CI(:python-multiplatform-compose:fixtures:notebook-e2e:desktopTest)에서 통과합니다.
// settings.gradle.kts
pluginManagement {
repositories {
mavenCentral()
google()
gradlePluginPortal()
}
}
// build.gradle.kts
plugins {
kotlin("multiplatform")
id("org.thisisthepy.compose") version "1.11.1-ext.3"
id("org.jetbrains.kotlin.plugin.compose")
id("org.thisisthepy.python.multiplatform.bindings") version "3.15.0-alpha03"
}
kotlin {
jvm("desktop")
}
Path 2: Extended GraalVM native-image경로 2: Extended GraalVM 네이티브 이미지
Setting output.set(ApplicationOutput.NativeImage) on compose.desktop.application switches the desktop target from a JAR to a GraalVM native-image executable. On the extended fork, passing -Dcompose.awt=false and -Dcompose.main.dispatcher=coroutines runs Compose Desktop without AWT/Swing initialization, while python-multiplatform stages python-multiplatform-home/ (including pythonx-compose) beside the binary so it starts with JAVA_HOME and PYTHONHOME unset. Verified in CI by :python-multiplatform-compose:fixtures:notebook-e2e:notebookE2eNativeRun (20/20 scenarios, no libjvm).
compose.desktop.application 에 output.set(ApplicationOutput.NativeImage) 를 설정하면 데스크톱 타겟이 JAR 대신 GraalVM native-image 실행 파일로 빌드됩니다. extended 포크에서 -Dcompose.awt=false 와 -Dcompose.main.dispatcher=coroutines 를 넘기면 AWT/Swing 초기화 없이 Compose Desktop 이 실행되며, python-multiplatform 이 바이너리 옆에 python-multiplatform-home/(설치된 pythonx-compose 포함)을 배치해 JAVA_HOME 과 PYTHONHOME 없이도 바로 시작됩니다. CI 의 :python-multiplatform-compose:fixtures:notebook-e2e:notebookE2eNativeRun 에서 검증됩니다(20/20 시나리오 통과, libjvm 없음).
import org.jetbrains.compose.desktop.application.dsl.ApplicationOutput
compose.desktop {
application {
mainClass = "my.app.MainKt"
output.set(ApplicationOutput.NativeImage)
nativeImage {
buildArgs.addAll(
"--no-fallback",
"-Dcompose.awt=false",
"-Dcompose.main.dispatcher=coroutines",
)
}
}
}
Path 3: Extended Kotlin/Native desktop경로 3: Extended Kotlin/Native 데스크톱
The extended fork also ships org.thisisthepy.kotlin.native.desktop, which compiles Kotlin directly to a native binary on macosArm64() and linuxX64() using GLFW and Skia without a JVM. python-multiplatform supports both targets via CPython cinterop (python-multiplatform #370, 496/496 binder tests passing in CI). Because pythonx-compose imports only the binder's androidx.compose.* modules, your Python UI code needs no changes; adding the macosArm64 and linuxX64 targets to :python-multiplatform-compose is the remaining host-side step (python-multiplatform #191 Phase B).
extended 포크는 JVM 없이 GLFW 와 Skia 로 Kotlin 을 macosArm64() 및 linuxX64() 네이티브 바이너리로 직접 컴파일하는 org.thisisthepy.kotlin.native.desktop 플러그인도 제공합니다. python-multiplatform 은 CPython cinterop 으로 두 타겟을 모두 지원합니다(python-multiplatform #370, CI 에서 496/496 바인더 테스트 통과). pythonx-compose 는 바인더의 androidx.compose.* 모듈만 import 하므로 파이썬 UI 코드는 바꿀 것이 없으며, :python-multiplatform-compose 에 macosArm64 와 linuxX64 타겟을 여는 것이 남은 호스트 쪽 단계입니다(python-multiplatform #191 Phase B).
plugins {
kotlin("multiplatform")
id("org.thisisthepy.compose") version "1.11.1-ext.3"
id("org.thisisthepy.kotlin.native.desktop") version "1.11.1-ext.3"
id("org.jetbrains.kotlin.plugin.compose")
id("org.thisisthepy.python.multiplatform.bindings") version "3.15.0-alpha03"
}
kotlin {
macosArm64()
linuxX64()
}