install.txt

.. meta::
   :robots: noindex, nosnippet

.. _kotlin-install:

======================
Install the Kotlin SDK
======================

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 2
   :class: singlecol

.. meta::
   :description: Learn how to install the Atlas Device SDK for Kotlin in your Android and Kotlin Multiplatform (KMP) projects.
   :keywords: code example

.. facet::
  :name: genre
  :values: tutorial

The Atlas Device SDK for Kotlin supports the following platforms. Each has its own installation
method and requirements:

- :ref:`Android <kotlin-install-android>`
- :ref:`Kotlin Multiplatform (KMP) <kotlin-install-kotlin-multiplatform>`

Prerequisites
-------------

Before getting started, ensure your development environment
meets the following prerequisites:

- :android:`Android Studio <studio/index.html>` Bumblebee 2021.1.1 or higher.
- JDK 11 or higher.
- Kotlin Plugin for Android Studio, version 1.6.10 or higher.
- An Android Virtual Device (AVD) using a supported CPU architecture.

For a list of supported target environments, refer to the :ref:`kotlin-supported-environments` section on this page.

Additionally, Kotlin Multiplatform (KMP) for mobile projects require the following:

- `Kotlin Multiplatform Mobile (KMM) Plugin
  <https://kotlinlang.org/docs/mobile/kmm-plugin-releases.html#release-details>`__
  for Android Studio, version 0.3.1 or higher.
- A Kotlin Multiplatform (KMP) App created using the "Kotlin Multiplatform App"
  template in Android Studio. Follow the instructions in the
  `Kotlin Multiplatform documentation
  <https://kotlinlang.org/docs/mobile/create-first-app.html>`__.

For more details on setting up your KMP environment, refer to the `official Kotlin
Kotlin Multiplatform for mobile
<https://kotlinlang.org/docs/multiplatform-mobile-setup.html>`__ documentation. To verify your
environment setup, follow Kotlin's `guide to checking your
environment
<https://kotlinlang.org/docs/multiplatform-mobile-setup.html#check-your-environment>`__.

.. tip:: Kotlin Plugin Version

   The Kotlin Multiplatform (KMP) ecosystem frequently changes. If you experience
   any issues installing the SDK, check your Kotlin Plugin version, since
   outdated plugins can lead to difficult to debug errors. To see which
   versions of the Kotlin Plugin are compatible with the SDK, refer to the
   `SDK changelog <https://github.com/realm/realm-kotlin/blob/master/CHANGELOG.md>`__.

.. _kotlin-install-kotlin-multiplatform:
.. _kotlin-install-android:

Installation
------------

.. tip:: Atlas Device SDK and Realm

   The SDK uses Realm Core database for device data persistence. When you
   install the Kotlin SDK, the package names reflect Realm naming.

.. procedure::

   .. step:: Add the SDK to the Project

      .. tabs::

         .. tab:: Android
            :tabid: android

            Add :file:`io.realm.kotlin`, specifying the library version and
            :file:`apply false`, to the list of plugins in your project-level Gradle
            build file, typically found at :file:`<project>/build.gradle`:

            .. code-block:: kotlin
               :caption: Global build.gradle

               plugins {
                  id 'io.realm.kotlin' version '{+kotlin-sdk-version+}' apply false
               }

            Add the following to your app-level Gradle build file, typically
            found at :file:`<project>/app/build.gradle`:

            - Add :file:`io.realm.kotlin` to the list of plugins.
            - Add the following to the list of dependencies:

              - Add :file:`io.realm.kotlin:library-base` to the dependencies block.
              - If using Device Sync in your application, add :file:`io.realm.kotlin:library-sync` to the dependencies block.

            - To use coroutines with the SDK, add :file:`org.jetbrains.kotlinx:kotlinx-coroutines-core` to the list of dependencies.

            .. code-block:: kotlin
               :caption: Module build.gradle
               :emphasize-lines: 4, 12-16

               plugins {
                  id 'com.android.application'
                  id 'org.jetbrains.kotlin.android'
                  id 'io.realm.kotlin'
               }

               android {
                  // ... build configuration settings
               }

               dependencies {
                  implementation 'io.realm.kotlin:library-base:{+kotlin-sdk-version+}'
                  // If using Device Sync
                  implementation 'io.realm.kotlin:library-sync:{+kotlin-sdk-version+}'
                  // If using coroutines with the SDK
                  implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:{+kotlinx-coroutines-version+}'
               }

         .. tab:: Kotlin Multiplatform (KMP)
            :tabid: kmp

            1. Add the following to your app-level Gradle build file, typically found at :file:`<project>/app/build.gradle`:

               - Add :file:`io.realm.kotlin` to the list of plugins.
               - Add the following to the list of dependencies:

                 - Add :file:`io.realm.kotlin:library-base` to the dependencies block.
                 - If using Device Sync in your application, add :file:`io.realm.kotlin:library-sync` to the dependencies block.

               - To use coroutines with the SDK, add :file:`org.jetbrains.kotlinx:kotlinx-coroutines-core` to the list of dependencies.

               .. code-block:: kotlin
                  :caption: App build.gradle
                  :emphasize-lines: 5, 18-22

                  plugins {
                     kotlin("multiplatform")
                     kotlin("native.cocoapods")
                     id("com.android.library")
                     id("io.realm.kotlin") version "{+kotlin-sdk-version+}"
                  }

                  version = "1.0"

                  kotlin {
                     android()
                     iosX64()
                     iosArm64()

                     sourceSets {
                        val commonMain by getting {
                           dependencies {
                              implementation("io.realm.kotlin:library-base:{+kotlin-sdk-version+}")
                              // If using Device Sync
                              implementation("io.realm.kotlin:library-sync:{+kotlin-sdk-version+}")
                              // If using coroutines with the SDK
                              implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:{+kotlinx-coroutines-version+}")
                           }
                        }
                     }
                  }

            2. If you use any part of the SDK inside the Android module, add the following compile-time dependencies to your module-level Gradle build file, typically found at :file:`<project>/module/build.gradle`:

               .. code-block:: kotlin
                  :caption: Android Module build.gradle

                  dependencies {
                     compileOnly("io.realm.kotlin:library-base:{+kotlin-sdk-version+}")
                  }
                  // If using Device Sync
                  dependencies {
                     compileOnly("io.realm.kotlin:library-sync:{+kotlin-sdk-version+}")
                  }

   .. step:: Sync Gradle Files

      After updating the Gradle configuration,
      resolve the dependencies by clicking :guilabel:`File` >
      :guilabel:`Sync Project with Gradle Files` in the Android Studio menu bar.
      You can now use the Kotlin SDK in your application.

.. _kotlin-supported-environments:

Supported Target Environments
-----------------------------

Kotlin Multiplatform (KMP) supports a wide range of application environments
Refer also to Kotlin's `Multiplatform Gradle DSL reference: Targets
<https://kotlinlang.org/docs/multiplatform-dsl-reference.html#targets>`__ documentation.

Supported Environments
~~~~~~~~~~~~~~~~~~~~~~

The Kotlin SDK supports the following environments:

- :file:`android`

- :file:`iosArm64`
- :file:`iosSimulatorArm64`
- :file:`iosX64`

- :file:`jvm`

- :file:`macosArm64`
- :file:`macosX64`

Unsupported Environments
~~~~~~~~~~~~~~~~~~~~~~~~

The Kotlin SDK does *not* support the following environments:

- :file:`androidNativeArm32`
- :file:`androidNativeArm64`
- :file:`androidNativeX86`
- :file:`androidNativeX64`

- :file:`iosArm32`

- :file:`js`

- :file:`linuxArm32Hfp`
- :file:`linuxArm64`
- :file:`linuxMips32`
- :file:`linuxMipsel32`
- :file:`linuxX64`

- :file:`mingwX64`
- :file:`mingwX86`

- :file:`tvosArm64`
- :file:`tvosSimulatorArm64`
- :file:`tvosX64`

- :file:`wasm32`

- :file:`watchosArm32`
- :file:`watchosArm64`
- :file:`watchosSimulatorArm64`
- :file:`watchosX86`
- :file:`watchosX64`