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

08-06 23:34:10.332 I/SHARED_KOTLIN: Database created: desktopApp-db
08-06 23:34:10.347 I/DESKTOP_APP: Created document :: 6ee12f44-d619-4c06-a52d-14ffaa6e5bee
08-06 23:34:10.350 I/SHARED_KOTLIN: Retrieved document:
08-06 23:34:10.350 I/SHARED_KOTLIN: Document ID :: 6ee12f44-d619-4c06-a52d-14ffaa6e5bee
08-06 23:34:10.350 I/SHARED_KOTLIN: Learning :: Kotlin
08-06 23:34:10.353 I/DESKTOP_APP: Updated document :: 6ee12f44-d619-4c06-a52d-14ffaa6e5bee
08-06 23:34:10.369 I/SHARED_KOTLIN: Number of rows :: 1
08-06 23:34:10.371 I/SHARED_KOTLIN: Document ID :: 6ee12f44-d619-4c06-a52d-14ffaa6e5bee
08-06 23:34:10.372 I/SHARED_KOTLIN: Document :: {"language":"Kotlin","version":2.0,"platform":"JVM 17.0.7","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 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.

Android App

The Android app uses XML views.

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 uses SwiftUI.

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 uses Compose UI.

Run

Run the desktopApp run configuration.

./gradlew :desktopApp:run

Native CLI App

The native app 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.

Android App

Run

Run the androidApp run configuration.

Install
./gradlew :androidApp: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 :desktopApp: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.

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.