From 364a916740dc29b12434acff95b2d47dabe715c1 Mon Sep 17 00:00:00 2001 From: Sebastian Aigner Date: Mon, 6 Mar 2023 16:39:39 +0100 Subject: [PATCH] Various improvements for multiplatform template README (#2834) --- .../multiplatform-template/README.md | 82 +++++++++++++------ 1 file changed, 55 insertions(+), 27 deletions(-) diff --git a/experimental/templates/multiplatform-template/README.md b/experimental/templates/multiplatform-template/README.md index 6989d74f1a..b144f58546 100644 --- a/experimental/templates/multiplatform-template/README.md +++ b/experimental/templates/multiplatform-template/README.md @@ -1,70 +1,98 @@ # Compose Multiplatform Application -Сan run on desktop, Android and iOS. -Note that iOS target is experimental so far. +Use this template to start developing your own Compose Multiplatform application targeting desktop, Android, and iOS (experimental). ## Desktop -This template contains `desktopApp` run configuration that you can use to run the desktop target in Android Studio or Intellij IDEA. +This template contains `desktopApp` run configuration that you can use to run the desktop target in Android Studio or IntelliJ IDEA. Useful Gradle tasks: - `./gradlew run` - run application - `./gradlew package` - package native distribution into `build/compose/binaries` ## Android -To run on Android, use `androidApp` run configuration in [Android Studio](https://developer.android.com/studio) +To run on Android, use the `androidApp` run configuration in [Android Studio](https://developer.android.com/studio) or use Gradle: `./gradlew installDebug` - install Android application on an Android device (on a real device or on an emulator) ## iOS +Make sure you have set up your environment for mobile development with Kotlin Multiplatform. A detailed guide on how to set up your environment is available in the [Kotlin Multiplatform documentation](https://kotlinlang.org/docs/multiplatform-mobile-setup.html). + To work with the iOS target you need: -- [Xcode](https://developer.apple.com/xcode/) (to setup the environement) +- A machine running a recent version of macOS +- [Xcode](https://developer.apple.com/xcode/) (to setup the environment) - [Android Studio](https://developer.android.com/studio) -- ["Kotlin Multiplatform Mobile" plugin](https://plugins.jetbrains.com/plugin/14936-kotlin-multiplatform-mobile) (to work with all supported targets, including iOS) +- [Kotlin Multiplatform Mobile plugin](https://plugins.jetbrains.com/plugin/14936-kotlin-multiplatform-mobile) (to work with all supported targets, including iOS) - [CocoaPods](https://kotlinlang.org/docs/native-cocoapods.html) -Before trying to open the project in Android Studio, make sure that you have a correct environment for iOS development. -Try to follow official Apple tutorials how to create a sample project in Xcode -and register a simulator or a real device there. +**Before opening the project in Android Studio**, make sure that your environment is set up for iOS and Kotlin Multiplatform development. +Use [`kdoctor`](https://github.com/Kotlin/kdoctor) to ensure your development environment is configured correctly. + +We suggest going through the "Hello, World" steps of creating and deploying a sample project in Xcode to a simulator and/or your physical device. +A video tutorial for setting up Xcode and running your first "Hello, World" application is available in [this Standford CS193P lecture recording](https://youtu.be/bqu6BquVi2M?start=716&end=1399). ### Running on an iOS simulator -If you have a correct environment, Android Studio will show available iOS simulators on which you can run the application -in `iosApp` run configuration. +Once you have configured your environment correctly, you will be able to select which iOS simulator to run your application in Android Studio on by modifying the `iosApp` run configuration. + +Select "Run" | "Edit Configurations..." and navigate to the "iOS Application" | "iosApp" run configuration. In the "Execution target" drop-down, select your target device. ### Running on a real iOS device -To run on a real iOS device you need: -- [Team ID](https://developer.apple.com/help/account/manage-your-team/locate-your-team-id/#:~:text=A%20Team%20ID%20is%20a,developer%20in%20App%20Store%20Connect.) -- set this Team ID in `iosApp/Configuration/Config.xcconfig` in the `TEAM_ID` field +Running your Compose Multiplatform application on a physical device can be done for free. You need: +- an [Apple ID](https://support.apple.com/en-us/HT204316) - the registered iOS device in Xcode -After that you can open the project in Android Studio, and it will show the registered iOS device in `iosApp` +#### Running with a free Personal Team + +If you use a free Personal Team for signing applications to run on a real device, you'll have to find your team ID. + +The easiest way is to refer to your "Hello, World" project that you created while setting up your development environment. Use your terminal to navigate to the folder where you have created the Xcode project (`.xcodeproj`) and run the following command: + +```bash +grep -r "DEVELOPMENT_TEAM" +``` + +In your multiplatform project, navigate to `iosApp/Configuration/Config.xcconfig` and set the `TEAM_ID` to the value you've gotten from the previous command. + +
+Alternative approaches + +To see your local team ID, you try running `security find-certificate -c "Apple Development" -p | openssl x509 -noout -text | grep --color 'OU=\w\w\w\w*'` in your terminal. + +If you're running into trouble with the method described above, you can try this alternative method. +- Run the `iosApp` run configuration from Android Studio (it will fail) +- Open the `iosApp/iosApp.xcworkspace` in Xcode +- Select `iosApp` in the menu on the left side +- Navigate to "Signing & Capabilities" +- Select your Personal Team in the "Team" dropdown. If you haven't set up your team, use the "Add account..." option and follow the steps inside Xcode. +
+ +After that you can open the project in Android Studio, and it will show the registered iOS device in the `iosApp` run configuration. -**Hint:** -If you use a free Personal Team for signing applications to run on a real device, -and you do not have access to the link above to know your Team ID, you may still find your Team ID value, -using the following workaround: -- manage to run a sample iOS project in XCode on a real iOS device -- open XCode project in a text editor and search `DEVELOPMENT_TEAM` substring in it -- the value of `DEVELOPMENT_TEAM` property is your personal Team ID +#### Running with a paid Team +- Find your [Team ID](https://developer.apple.com/help/account/manage-your-team/locate-your-team-id/#:~:text=A%20Team%20ID%20is%20a,developer%20in%20App%20Store%20Connect.). +- set this Team ID in `iosApp/Configuration/Config.xcconfig` in the `TEAM_ID` field + +After that you can open the project in Android Studio, and it will show the registered iOS device in the `iosApp` +run configuration. ### Configuring the iOS application -This template contains `iosApp/Configuration/Config.xcconfig` that allows you to configure the most basic properties, without using Xcode. It contains: +This template contains a `iosApp/Configuration/Config.xcconfig` configuration file that allows you to configure most basic properties without having to move to Xcode. It contains: - `APP_NAME` - target executable and application bundle name - `BUNDLE_ID` - [bundle identifier](https://developer.apple.com/documentation/bundleresources/information_property_list/cfbundleidentifier#discussion) - `TEAM_ID` - [Team ID](https://developer.apple.com/help/account/manage-your-team/locate-your-team-id/#:~:text=A%20Team%20ID%20is%20a,developer%20in%20App%20Store%20Connect.) -Note, that to configure the `APP_NAME` setting, you should open `Config.xcconfig` in any text editor *before opening* the project in Android Studio and correct respective value. +Note: To configure the `APP_NAME` setting, open `Config.xcconfig` in any text editor *before opening* the project in Android Studio, and set the desired name. If you need to change this setting after you open the project in Android Studio, please do the following: - close the project in Android Studio -- run `./cleanup.sh` script in a terminal -- correct the setting +- run `./cleanup.sh` in your terminal +- change the setting - open the project in Android Studio again -To configure advanced settings you need to use Xcode. Open `iosApp/iosApp.xcworkspace` in Xcode after opening the project in Android Studio. +For configuring advanced settings, you can use Xcode. Open the `iosApp/iosApp.xcworkspace` in Xcode after opening the project in Android Studio, and use Xcode to make your changes. \ No newline at end of file