diff --git a/MULTIPLATFORM.md b/MULTIPLATFORM.md index 3f16f18d25a55..6ca36f20625ab 100644 --- a/MULTIPLATFORM.md +++ b/MULTIPLATFORM.md @@ -1,9 +1,11 @@ ## General requirements + - Java 17 (should be specified in JAVA_HOME) - [macOs/Linux] Android SDK downloaded via `./jbdeps/android-sdk/downloadAndroidSdk` - [Windows] Android SDK downloaded from Android Studio and specified in ANDROID_SDK_ROOT ## Developing in IDE + 1. Download Android Studio from [the official site](https://developer.android.com/studio/archive) (it is mandatory to use the version, written [here](https://github.com/JetBrains/androidx/blob/jb-main/gradle/libs.versions.toml#L11)). As an alternative you can use IDEA, which is compatible with [this AGP version](https://github.com/JetBrains/androidx/blob/jb-main/gradle/libs.versions.toml#L5), or you can disable Android plugin in IDEA plugins, to develop non-Android targets. 2. [macOs/Linux] Download Android SDK via `./jbdeps/android-sdk/downloadAndroidSdk` 3. [Windows] Download Android SDK via [Android Studio](https://developer.android.com/studio/intro/update#sdk-manager) and specify it in ANDROID_SDK_ROOT environment variable. Components, their versions and folder structure should be the same as in downloaded via script `./jbdeps/android-sdk/downloadAndroidSdk` SDK for other platforms. @@ -12,21 +14,25 @@ ### Run tests Run tests for Desktop: + ```bash ./gradlew desktopTest ``` Run tests for Web: + ```bash ./gradlew :mpp:testWeb ``` Run tests for UIKit: + ```bash ./gradlew :mpp:testUIKit -PiosSimulatorName='iPhone 15' ``` ### API checks + Compose Multiplatform stores all public API in *.api files. If any API is added/changed, `./gradlew jbApiCheck` will fail with an error that API is changed (it runs on CI). Example: ``` @@ -51,124 +57,155 @@ Execution failed for task ':compose:material3:material3:desktopApiCheck'. ``` To fix this error: + 1. Run `./gradlew jbApiDump` or (for Linux/Window host) [CI task](https://teamcity.jetbrains.com/buildConfiguration/JetBrainsPublicProjects_Compose_CommitDumpApi) that creates a commit "Dump API" in a branch 2. See what has changed in *.api files. 3. If there are only additions - there is no binary incompatible change. 4. If there are some removals - most probably there is a binary incompatible change and it needs to be fixed before merging it to the main branch. ### Publishing + Compose Multiplatform core libraries can be published to local Maven with the following steps: + 1. Use these gradle properties to set the published libraries versions -`-Pjetbrains.publication.version.CORE_BUNDLE`, -`-Pjetbrains.publication.version.CORE_URI`, -`-Pjetbrains.publication.version.COMPOSE`, -`-Pjetbrains.publication.version.COMPOSE_MATERIAL_NAVIGATION`, -`-Pjetbrains.publication.version.COMPOSE_MATERIAL3_ADAPTIVE`, -`-Pjetbrains.publication.version.LIFECYCLE`, -`-Pjetbrains.publication.version.NAVIGATION`, -`-Pjetbrains.publication.version.SAVEDSTATE`, -`-Pjetbrains.publication.version.WINDOW`, + `-Pjetbrains.publication.version.CORE_BUNDLE`, + `-Pjetbrains.publication.version.CORE_URI`, + `-Pjetbrains.publication.version.COMPOSE`, + `-Pjetbrains.publication.version.COMPOSE_MATERIAL_NAVIGATION`, + `-Pjetbrains.publication.version.COMPOSE_MATERIAL3_ADAPTIVE`, + `-Pjetbrains.publication.version.LIFECYCLE`, + `-Pjetbrains.publication.version.NAVIGATION`, + `-Pjetbrains.publication.version.SAVEDSTATE`, + `-Pjetbrains.publication.version.WINDOW`, -The default value for the version is `0.0.0-SNAPSHOT` + The default value for the version is `0.0.0-SNAPSHOT` -And library groups: -`-Pjetbrains.publication.libraries=CORE_BUNDLE,CORE_URI,COMPOSE,COMPOSE_MATERIAL_NAVIGATION,COMPOSE_MATERIAL3_ADAPTIVE,LIFECYCLE,NAVIGATION,SAVEDSTATE,WINDOW` + And library groups: + `-Pjetbrains.publication.libraries=CORE_BUNDLE,CORE_URI,COMPOSE,COMPOSE_MATERIAL_NAVIGATION,COMPOSE_MATERIAL3_ADAPTIVE,LIFECYCLE,NAVIGATION,SAVEDSTATE,WINDOW` -The default value includes all libraries. + The default value includes all libraries. 2. Publish core libraries -```bash -./gradlew :mpp:publishComposeJbToMavenLocal -Pcompose.platforms=all -Pjetbrains.publication.version.COMPOSE=0.1.0-dev1000 -Pjetbrains.publication.version.LIFECYCLE=0.1.0-dev1000 -``` -`-Pcompose.platforms=all` could be replace with comma-separated list of platforms, such as `js,jvm,androidDebug,androidRelease,macosx64,uikit`. + + ```bash + ./gradlew :mpp:publishComposeJbToMavenLocal -Pcompose.platforms=all -Pjetbrains.publication.version.COMPOSE=0.1.0-dev1000 -Pjetbrains.publication.version.LIFECYCLE=0.1.0-dev1000 + ``` + + `-Pcompose.platforms=all` could be replace with comma-separated list of platforms, such as `js,jvm,androidDebug,androidRelease,macosx64,uikit`. 3. Publish extended icons -```bash -./gradlew :mpp:publishComposeJbExtendedIconsToMavenLocal -Pcompose.platforms=all --max-workers=1 -``` + + ```bash + ./gradlew :mpp:publishComposeJbExtendedIconsToMavenLocal -Pcompose.platforms=all --max-workers=1 + ``` 4. (Optional) Publish Gradle plugin using [instructions](https://github.com/JetBrains/compose-multiplatform/tree/master/compose#publishing) to check changes locally. ### Run samples + Run jvm desktop samples: + ```bash ./gradlew :compose:mpp:demo:runDesktop ``` + ```bash ./gradlew :compose:desktop:desktop:desktop-samples:run1 ``` + ```bash ./gradlew :compose:desktop:desktop:desktop-samples:run2 ``` + ```bash ./gradlew :compose:desktop:desktop:desktop-samples:run3 ``` + ```bash ./gradlew :compose:desktop:desktop:desktop-samples:runSwing ``` + ```bash ./gradlew :compose:desktop:desktop:desktop-samples:runWindowApi ``` + ```bash ./gradlew :compose:desktop:desktop:desktop-samples:runVsync ``` + ```bash ./gradlew :compose:desktop:desktop:desktop-samples:runLayout ``` + ```bash ./gradlew :compose:desktop:desktop:desktop-samples-material3:runScaffold ``` Run wasm sample: + ```bash ./gradlew :compose:mpp:demo:jsRun ``` Run native macos X64 sample: + ```bash ./gradlew :compose:mpp:demo:runDebugExecutableMacosX64 ``` Run native macos Arm64 sample: + ```bash ./gradlew :compose:mpp:demo:runDebugExecutableMacosArm64 ``` + ### Run in KMP Wizard project -- To use a locally built compose in [KMP with Compose wizard project](https://kmp.jetbrains.com) you need to perform some extra steps:-Checkout https://github.com/JetBrains/compose-multiplatform -- Open `gradle-plugins` in `compose-multiplatform` + +To use a locally built compose in [KMP with Compose wizard project](https://kmp.jetbrains.com) you need to perform some extra steps: + +- Checkout . +- Open `gradle-plugins` in `compose-multiplatform`. - Update `gradle.properties` by setting `compose.version` and `deploy.version` to the version you've published (`0.1.0-dev1000` in example above). -- Run `./gradlew publishToMavenLocal` -- Open `components` in `compose-multiplatform` +- Run `./gradlew publishToMavenLocal`. +- Open `components` in `compose-multiplatform`. - Update `gradle.properties` by setting `compose.useMavenLocal` to `true` and `compose.version` to the version you've published. -- Run `./gradlew publishToMavenLocal` +- Run `./gradlew publishToMavenLocal`. - Open KMP wizard project. - Update `settings.gradle.kts` by adding `mavenLocal()` to the end of both `repositories` blocks. - Update `gradle/libs.versions.toml` by setting `compose-plugin` to the version you've published. -- Sync gradle, now the project will build with the locally published Compose. +- Sync gradle. + +Now the project will build with the locally published Compose. ### Run mpp/demo-uikit sample on iOS - - Install plugin **Kotlin Multiplatform Mobile** for AppCode - - Disable Android Plugin in IDE preferences - - Open root of repository with AppCode - - Increase AppCode IDE memory more that 10GB - - Restart AppCode - - Wait while project synchronization with Gradle - - [Optional] To run on real iOS device - - Device should be at least with iOS 16.5. And Xcode should be at least 14.3 - - Find your TEAM_ID with instruction https://github.com/JetBrains/compose-multiplatform-template#running-on-a-real-ios-device - - Create file project.properties in the root of repository. Add property `TEAM_ID=[your team id]` without double quotes, for example `TEAM_ID=ABC123ABC1`. - - Choose run configuration **iOS App** + +- Install plugin **Kotlin Multiplatform Mobile** for AppCode +- Disable Android Plugin in IDE preferences +- Open root of repository with AppCode +- Increase AppCode IDE memory more that 10GB +- Restart AppCode +- Wait while project synchronization with Gradle +- [Optional] To run on real iOS device + - Device should be at least with iOS 16.5. And Xcode should be at least 14.3 + - Find your TEAM_ID with instruction + - Create file project.properties in the root of repository. Add property `TEAM_ID=[your team id]` without double quotes, for example `TEAM_ID=ABC123ABC1`. +- Choose run configuration **iOS App** ### Run mpp/demo sample on iOS with Xcode + Run script: -```bash + +```bash ./compose/mpp/demo/regenerate_xcode_project.sh - ``` +``` + Wait while Xcode is opening, and press run button. ### Clean IDE and Gradle cache - - Close project - - ```bash - ./cleanTempFiles.sh - ``` \ No newline at end of file + +- Close project + +- ```bash + ./cleanTempFiles.sh + ```