Launcher for KMP on Android: a complete guide to creating from scratch

Creating your own launcher for Kotlin Multiplatform (KMP) on Android - a task that combines user interface development, work with KMP modules and a deep dive into operating system architecture. Such a launcher can become a convenient shell for launching cross-platform applications, testing modules, or even the basis for a custom desktop. But where to start if you have never done such projects?

In this article we will analyze the process from idea to implementation: we will select tools, set up the environment, write basic code and optimize performance. Let's pay special attention KMP integration to it - after all, it is what distinguishes such a launcher from standard solutions. You will learn how to avoid common mistakes when working with Gradledeclarations, how to correctly process expect/actualdeclarations, and why some functions may not work on all versions of Android. Are you ready to dive into the details?

Before we get into the technical details, let's answer a key question: why do you need a launcher for KMP at all? First, it makes it easy to run cross-platform modules on mobile devices without having to deploy a full application. Secondly, it allows you to test general logic (common-code) directly to Android, saving time on switching between platforms. Thirdly, such a launcher can become part of a more complex ecosystem - for example, for managing microservices or plugins.

1. Preparing the development environment

The first step is setting up the tools. Without a properly configured environment, even the simplest launcher will not work. You will need:

• 📱 Android Studio version Giraffe (2022.3.1) or later (check compatibility with the latest versions Kotlin and Gradle).
• 🔧 Kotlin Multiplatform Plugin (version 1.9.20 or higher). Outdated versions may not support current features. Android.
• 📦 Java Development Kit (JDK) version 17 is a mandatory requirement for modern projects on Kotlin.
• 🔄 Gradle 8.2+ with support version catalogs (simplifies dependency management).

Install Android Studio from the official website, then open SDK Manager and download:

• 📱 Android 13 (API 33) or newer (recommended for testing the latest features).
• 🛠️ Build tools Android SDK Build-Tools versions 34.0.0.
• 🔍 Android Emulator with image Google Play (for testing on a virtual device).

After installation, check the versions in the terminal:

kotlin -version
gradle -v
java -version

⚠️ Attention: If you use MacOS with a chip Apple Silicon (M1/M2), install Rosetta 2 for correct operation Android EmulatorWithout this, the emulator may not start. or work with errors.

2. Creating a basic KMP project

Now let's move on to creating the project. Android Studio select New Project → Kotlin Multiplatform App. Set up the structure as follows:

After generating the project, open the file build.gradle.kts in the root folder and add dependencies for Android:

kotlin {
android {
publishLibraryVariants("release", "debug")
}
sourceSets {
val commonMain by getting {
dependencies {
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
}
}
val androidMain by getting {
dependencies {
implementation("androidx.activity:activity-compose:1.8.0")
implementation("androidx.compose.material3:material3:1.2.0")
}
}
}
}

Synchronize project with Gradle (button Sync Now in the upper right corner). If errors occur, check:

• 🔌 Correct Internet connection (dependencies are downloaded from Maven Central).
• 📝 No typos in build.gradle.kts.
• 🔄 Version compatibility Kotlin i Gradle (see official documentation).

- All dependencies installed in build.gradle.kts

- Gradle synchronization completed without errors

- Emulator selected or physical device connected

- Developer mode is enabled on the Android device-->

3. Development of the user interface

The launcher interface should be minimalistic but functional. We will use Jetpack Compose a modern framework for building the UI on Kotlin. Open the file androidApp/src/main/AndroidManifest.xml and add permissions:

<uses-permission android:name="android.permission.QUERY_ALL_PACKAGES" />
<uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />

Now create a file MainActivity.kt in the package androidApp:

class MainActivity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContent {
KMPLauncherTheme {
Surface(modifier = Modifier.fillMaxSize()) {
LauncherScreen()
}
}
}
}
}

@Composable
fun LauncherScreen() {
val context = LocalContext.current
val packageManager = context.packageManager
val packages = remember { mutableStateListOf<ApplicationInfo>() }

LaunchedEffect(Unit) {
packages.addAll(
packageManager.getInstalledApplications(PackageManager.GET_META_DATA)
.filter { it.flags and ApplicationInfo.FLAG_SYSTEM == 0 }
)
}

LazyColumn {
items(packages) { app ->
Card(
onClick = { / Launch application / },
modifier = Modifier.padding(8.dp)
) {
Text(app.loadLabel(packageManager).toString())
}
}
}
}

This code:

• 📱 Gets a list of installed applications (excluding system ones).
• 🖼️ Displays them in the form of cards with the ability to launch.
• 🔄 Uses LaunchedEffect for asynchronous data loading.

⚠️ Attention: Starting from Android 11 (API 30), access to the list of applications is limited. For the code to work, add to AndroidManifest.xml parameter android:requestLegacyExternalStorage="true" or request permission QUERY_ALL_PACKAGES via Google Play Console (for publication in the store).

4. Integration of KMP modules

The main difference between our launcher and the usual one is support Kotlin Multiplatform. Create a common module (common) for logic that will work on all platforms. For example, let's add a function for checking application compatibility with KMP:

In file common/src/commonMain/kotlin/Common.kt:

expect class Platform() {
fun isKMPCompatible(appPackage: String): Boolean
}

fun checkCompatibility(appPackage: String): Boolean {
return Platform().isKMPCompatible(appPackage)
}

Implement actual-class for Android in androidApp/src/main/kotlin/Platform.android.kt:

actual class Platform actual constructor() {
actual fun isKMPCompatible(appPackage: String): Boolean {
// Check logic (for example, by signature or manifest)
return appPackage.contains("kmp") || appPackage.contains("multiplatform")
}
}

Now in LauncherScreen you can use general logic:

Card(
onClick = {
if (checkCompatibility(app.packageName)) {
// Launching a KMP application
} else {
// Standard launch
}
}
) { ... }

Critical detail: if your launcher will launch KMP modules dynamically (via ClassLoader), ensure that all dependencies match the target application's dependencies. Otherwise, there may be ClassNotFoundException or version conflicts.

5. Handling application launch

To launch applications from the launcher, add the following code to the handler onClick:

val intent = packageManager.getLaunchIntentForPackage(app.packageName)
if (intent != null) {
startActivity(intent)
} else {
Toast.makeText(context, "Could not launch ${app.loadLabel(packageManager)}", Toast.LENGTH_SHORT).show()
}

For KMP applications may require additional logic:

• 🔗 Checking the presence of KMP_MANIFEST in assets target APK.
• 📦 Loading dynamic libraries via System.loadLibrary.
• 🔄 Restarting the activity after loading modules (sometimes required for initializing nativecode).

Example of manifest verification:

fun hasKMPManifest(context: Context, packageName: String): Boolean {
return try {
val ai = context.packageManager.getApplicationInfo(packageName, 0)
context.assets.open("${ai.sourceDir}/assets/KMP_MANIFEST").use { true }
} catch (e: Exception) {
false
}
}

⚠️ Attention: The launch of third-party APKs with dynamic code loading may be blocked Google Play Protect as a potentially dangerous action. For commercial use, obtain a certificate Android App Bundle and go through moderation.

6. Optimization and testing

Before release, optimize the launcher:

• 🚀 Performance: Use LazyColumn to display the list of applications (saves memory).
• 🔍 Security: Request permissions only when necessary (for example QUERY_ALL_PACKAGES only for Android 11+).
• 📦 Size APK: Enable minifyEnabled true i shrinkResources true in build.gradle.
• 🛠️ Errors: Test on devices with different versions of Android (from 9 to 14).

To test KMP functionality:

1. Build a test KMP application with a simple common-module.
2. Install it on the device next to the launcher.
3. Check whether the launcher correctly identifies it as KMP-compatible.
4. Run the application through the launcher and make sure that the general logic works.

Example of a KMP test module (commonTest):

class CommonTest {
@Test
fun testCompatibilityCheck() {
assertTrue(checkCompatibility("com.example.kmpapp"))
assertFalse(checkCompatibility("com.android.settings"))
}
}

adb devices

<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>

7. Publishing on Google Play

If you plan to distribute the launcher via Google Play, prepare the following materials:

• 📝 Description: Indicate that the launcher supports KMP (this will highlight your application).
• 🖼️ Screenshots: Show the interface with running KMP applications.
• 🎥 Video: Short demonstration of work (optional, but increases conversion).
• 📋 Privacy Policy: Required for all applications in Google Play.

Features of KMP launcher publication:

• 🔗 In release-build, disable debug logs (isDebuggable = false).
• 🛡️ Sign the APK using keytool and jarsigner (or use Android App Bundle).
• 📦 Make sure that all nativelibraries (.so-files) are included in the assembly.

An example command for generating a key:

keytool -genkey -v -keystore kmp_launcher.keystore -alias KMPLauncher -keyalg RSA -keysize 2048 -validity 10000

⚠️ Attention: If your launcher uses dynamic code loading (for example, it loads KMP modules from the network), Google Play may require additional moderation. In this case, prepare technical support in advance. justification (in English).

8. Further development of the project

The basic launcher is ready, but it can be expanded:

• 📊 Statistics: Add data collection about launched KMP applications (with the user's consent).
• 🔄 Updates: Implement update checking for KMP modules via GitHub Releases or Firebase.
• 🎨 Customization: Allow users to change themes, icons and layout of elements.
• 🤖 Automation: Integrate CI/CD (for example, GitHub Actions) for automatic build and testing.

Example of adding themes (in androidApp/src/main/kotlin/Theme.kt):

private val DarkColorPalette = darkColors(
primary = Purple200,
secondary = Purple700
)

private val LightColorPalette = lightColors(
primary = Purple500,
secondary = Purple700
)

@Composable
fun KMPLauncherTheme(darkTheme: Boolean = isSystemInDarkTheme(), content: @Composable () -> Unit) {
val colors = if (darkTheme) DarkColorPalette else LightColorPalette
MaterialTheme(colors = colors, content = content)
}

To integrate with GitHub Actions create a file .github/workflows/android.yml:

name: Android CI
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up JDK 17
uses: actions/setup-java@v3
with:
java-version: '17'
distribution: 'temurin'
- name: Build with Gradle
run: ./gradlew build

This will automatically check the build with each commit.

FAQ: Frequently asked questions

val loader = URLClassLoader(
arrayOf(File(moduleDir, "common.jar").toURI().toURL()),
javaClass.classLoader
)
val kmpClass = loader.loadClass("com.example.CommonKt")
val method = kmpClass.getMethod("someFunction")
method.invoke(null)