Kaluga

This project is named after the Kaluga, the world's biggest freshwater fish, which is found in the icy Amur river.

Kaluga's main goal is to provide access to common features used in cross-platform mobile app development, separated into modules such as architecture (MVVM), location, permissions, bluetooth etc.

To reach this goal it uses Kotlin, specifically Kotlin Multiplatform which allows running Kotlin code not just on JVM+Android, but also iOS/iPadOS, amongst others (inndeed some kaluga modules also work for Kotlin.js and/or JVM standalone).

Where appropriate coroutines and Flow are used in the API. This enables developers to use cold streams for a modern and efficient design.

While Kaluga modules can be used individually, together they form a comprehensive approach to cross-platform development with shared native code and native UIs, including SwiftUI and Compose.

Short examples

With Kaluga it is possible to create cross-platform functionality in a few lines of code, that would normally take many lines of code even on just one platform.

Below are some examples, using a commonMain source-set:

Scanning for nearby devices with Bluetooth LE:

// will auto request permissions and try to enable bluetooth
BluetoothBuilder().create().devices().collect {
    i("discovered device: $it") // log found device
}

Showing a spinner while doing some work:

suspend fun doWork(hudBuilder: HUD.Builder) {
    hudBuilder.presentDuring { // shows spinner while code in this block is running
        // simulate doing work
        delay(1000)
    }
}
    

in this case, since HUD is a UI component the builder needs to be configured on the platform side:

val builder = HUD.Builder() // same for iOS and Android
// ...
builder.subscribe(activity) // this needs be done in the Android source-set to bind the HUD to the lifecycle of the Activity
// ...
builder.unsubscribe(activity) // when the Activity is stopped

However Kaluga's architecture module offers a cross-platform LifecycleViewModel class (which extends androidx.lifecycle.ViewModel on Android) that will automatically bind the builder to its lifecycle:

// this can just be in the commonMain source
class HudViewModel(private val hudBuilder: HUD.Builder): BaseLifecycleViewModel(hudBuilder) {
    
    suspend fun doWork() = 
        hudBuilder.presentDuring {
            delay(1000)
        }
}

More examples

Kaluga contains an example project that is used to test the developed modules.

Using Kaluga

NOTE: Older versions of Kotlin may cause a Thread Deadlock when running some modules on iOS. For this reason, it is recommended to target Kotlin 2.2.21 or higher

For starting a new project based on Kaluga see the kaluga-starter repo, which shows how to do this step by step.

Kaluga is available on Maven Central. For example the Kaluga Alerts can be imported like this:

repositories {
    mavenCentral()
}
dependencies {
    implementation("com.splendo.kaluga:alerts:$kalugaVersion")
}

You can also use the SNAPSHOT version based on the latest in the develop branch:

repositories {
    maven("https://s01.oss.sonatype.org/content/repositories/snapshots/")
}
dependencies {
    implementation("com.splendo.kaluga:alerts:$kalugaDevelopVersion-SNAPSHOT")
}

To use kaluga with SwiftUI and/or Combine we have a repo with Sourcery templates to generate some Swift code to help get you started.

Available Modules

| Module | Usage | Artifact Name | |-------------------------------------------------------------|------------------------------------------------------------------------------------|------------------------------------------------| | alerts | Used for Showing Alert Dialogs | com.splendo.kaluga:alerts | | architecture | MVVM architecture | com.splendo.kaluga:architecture | | architecture-compose | Compose extensions for architecture | com.splendo.kaluga:architecture-compose | | base | Core components of Kaluga. Contains threading, flowables and localization features | com.splendo.kaluga:base | | beacons | Tracking the availability of Beacons using the Eddystone protocol | com.splendo.kaluga:beacons | | bluetooth | Scanning for and communicating with BLE devices | com.splendo.kaluga:bluetooth | | date-time | Contains multiplatform classes to work with date and time | com.splendo.kaluga:date-time | | date-timepicker | Used for showing a Date or Time Picker | com.splendo.kaluga:date-time-picker | | hud | Used for showing a Loading indicator HUD | com.splendo.kaluga:hud | | keyboard | Used for showing and hiding the keyboard | com.splendo.kaluga:keyboard | | keyboard-compose | Compose extensions for keyboard | com.splendo.kaluga:keyboard-compose | | links | Used for decoding url into an object | com.splendo.kaluga:links | | location | Provides the User' geolocation | com.splendo.kaluga:location | | logging | Shared console logging | com.splendo.kaluga:logging | | media | Playing audio/video | com.splendo.kaluga:media | | base-permissions | Managing permissions, used in conjunction with modules below | com.splendo.kaluga:base-permissions | | bluetooth-permissions | Managing bluetooth permissions | com.splendo.kaluga:bluetooth-permissions | | calendar-permissions | Managing calendar permissions | com.splendo.kaluga:calendar-permissions | | camera-permissions | Managing camera permissions | com.splendo.kaluga:camera-permissions | | contacts-permissions | Managing contacts permissions | com.splendo.kaluga:contacts-permissions | | location-permissions | Managing location permissions | com.splendo.kaluga:location-permissions | | microphone-permissions | Managing microphone permissions | com.splendo.kaluga:microphone-permissions | | notifications-permissions | Managing notifications permissions | com.splendo.kaluga:notifications-permissions | | storage-permissions | Managing storage permissions | com.splendo.kaluga:storage-permissions | | resources | Provides shared Strings, Images, Colors and Fonts | com.splendo.kaluga:resources | | resources-compose | Compose extensions for resources | com.splendo.kaluga:resources-compose | | resources-databinding | Data Binding extensions for resources | com.splendo.kaluga:resources-databinding | | review