Skip to content

Build and Run

Build and run a starter app using Kotbase

Introduction

The Getting Started app is a very basic Kotlin Multiplatform app that demonstrates using Kotbase in a shared Kotlin module with native apps on each of the supported platforms.

You can access the getting-started and getting-started-compose projects in the git repository under examples.

Quick Steps

  1. Get the project and open it in Android Studio
  2. Build it
  3. Run any of the platform apps
  4. Enter some input and press "Run database work"
    The log output, in the app's UI or console panel, will show output similar to that in Figure 1
  5. That’s it.

Figure 1: Example app output

01-13 11:35:03.733 I/SHARED_KOTLIN: Database created: Database{@@0x9645222: 'desktopApp-db'}
01-13 11:35:03.742 I/SHARED_KOTLIN: Collection created: desktopApp-db@@x7fba7630dcb0._default.example-coll
01-13 11:35:03.764 I/DESKTOP_APP: Created document :: 83b6acb4-21ba-4834-aee4-2419dcea1114
01-13 11:35:03.767 I/SHARED_KOTLIN: Retrieved document:
01-13 11:35:03.767 I/SHARED_KOTLIN: Document ID :: 83b6acb4-21ba-4834-aee4-2419dcea1114
01-13 11:35:03.767 I/SHARED_KOTLIN: Learning :: Kotlin
01-13 11:35:03.768 I/DESKTOP_APP: Updated document :: 83b6acb4-21ba-4834-aee4-2419dcea1114
01-13 11:35:03.785 I/SHARED_KOTLIN: Number of rows :: 1
01-13 11:35:03.789 I/SHARED_KOTLIN: Document ID :: 83b6acb4-21ba-4834-aee4-2419dcea1114
01-13 11:35:03.790 I/SHARED_KOTLIN: Document :: {"language":"Kotlin","version":2.0,"platform":"JVM 21.0.1","input":"Hello, Kotbase!"}

Getting Started App

The Getting Started app shows examples of the essential Couchbase Lite CRUD operations, including:

  • Create a database
  • Create a collection
  • Create a document
  • Retrieve a document
  • Update a document
  • Query documents
  • Create and run a replicator

Whilst no exemplar of a real application, it will give you a good idea how to get started using Kotbase and Kotlin Multiplatform.

Shared Kotlin + Native UI

The getting-started version demonstrates using shared Kotlin code using Kotbase together with native app UIs.

The Kotbase database examples are in the shared module, which is shared between each of the platform apps.

Android App

The Android app is in the androidApp module. It uses XML views for its UI.

Run

Run the androidApp run configuration.

Install
./gradlew :androidApp:installDebug
Run
adb shell am start -n dev.kotbase.gettingstarted/.MainActivity

iOS App

The iOS app is in the iosApp directory. It is an Xcode project and uses SwiftUI for its UI.

Run

With the Kotlin Multiplatform Mobile plugin run the iosApp run configuration.

Open iosApp/iosApp.xcodeproj and run the iosApp scheme.

JVM Desktop App

The JVM desktop app is in the desktopApp module. It uses Compose UI for its UI.

Run

Run the desktopApp run configuration.

./gradlew :desktopApp:run

Native CLI App

The native app is in the cliApp module. It uses a command-line interface (CLI) on macOS, Linux, and Windows.

The app takes two command-line arguments, first the "input" value, written to the document on update, and second true or false for whether to run the replicator. These arguments can also be passed as gradle properties.

Run

Run the cliApp run configuration.

./gradlew :cliApp:runDebugExecutableNative -PinputValue="" -Preplicate=false
or
Build
./gradlew :cliApp:linkDebugExecutableNative
Run
cliApp/build/bin/native/debugExecutable/cliApp.kexe "<input value>" <true|false>

Share Everything in Kotlin

The getting-started-compose version demonstrates sharing the entirety of the application code in Kotlin, including the UI with Compose Multiplatform.

The entire compose app is a single Kotlin multiplatform module, encompassing all platforms, with an additional Xcode project for the iOS app.

Android App

Run

Run the androidApp run configuration.

Install
./gradlew :composeApp:installDebug
Start
adb shell am start -n dev.kotbase.gettingstarted.compose/.MainActivity

iOS App

Run

With the Kotlin Multiplatform Mobile plugin run the iosApp run configuration.

Open iosApp/iosApp.xcworkspace and run the iosApp scheme.

Important

Be sure to open iosApp.xcworkspace and not iosApp.xcodeproj. The getting-started-compose iosApp uses CocoaPods and the CocoaPods Gradle plugin to add the shared library dependency. The .xcworkspace includes the CocoaPods dependencies.

Note

Compose Multiplatform no longer requires CocoaPods for copying resources since version 1.5.0. However, the getting-started-compose example still uses CocoaPods for linking the Couchbase Lite framework. See the getting-started version for an example of how to link the Couchbase Lite framework without using CocoaPods.

JVM Desktop App

Run

Run the desktopApp run configuration.

./gradlew :composeApp:run

Sync Gateway Replication

Using the apps with Sync Gateway and Couchbase Server obviously requires you have, or install, working versions of both. See also — Install Sync Gateway

Once you have Sync Gateway configured, update the ReplicatorConfiguration in the app with the server's URL endpoint and authentication credentials.

Kotlin Multiplatform Tips

Calling Platform-specific APIs

The apps utilize the Kotlin Multiplatform expect/actual feature to populate the created document with the platform the app is running on.

See common expect fun getPlatform() and actual fun getPlatform() for Android, iOS, JVM, Linux, macOS, and Windows.

Using Coroutines in Swift

The getting-started app uses KMP-NativeCoroutines to consume Kotlin Flows in Swift. See @NativeCoroutines annotation in Kotlin and asyncSequence(for:) in Swift code.

SKIE is another solution, which generates Swift code for enhanced Swift–Kotlin interop, including coroutines. It's used in the Kotbase Notes example app described below.

Going Further

For an example of a full-featured MVVM architected Kotlin Multiplatform app, including data synchronization, see the Kotbase Notes app. This example includes:

  • Support for Android, iOS, and JVM desktop platforms.
  • Shared data, domain, presentation, and UI logic.
  • Platform-specific utility functions via expect/actual.
  • Platform-specific lifecycle management for data sync.
  • Dependency injection via Koin.
  • JSON serialization via kotlinx-serialization.
  • HTTP client via Ktor.
  • Enhanced Swift interoperability via SKIE.

Kotbase Library Source

The apps can get the Kotbase library dependency either from its published Maven artifact or build the library locally from the source repository. Set the useLocalLib property in gradle.properties to true to build the library from source, otherwise the published artifact from Maven Central will be used.