Browse Source

Various improvements for multiplatform template README (#2834)

pull/2838/head
Sebastian Aigner 2 years ago committed by GitHub
parent
commit
364a916740
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
  1. 82
      experimental/templates/multiplatform-template/README.md

82
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.
<details>
<summary>Alternative approaches</summary>
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.
</details>
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.
Loading…
Cancel
Save