Forem: Thomas Künneth

Agentic interaction using AppFunctions

Thomas Künneth — Mon, 06 Apr 2026 06:49:26 +0000

Given the rise of agentic interaction on Android, we need a fast, reliable API to make app capabilities discoverable and executable by agents. Through the years, Google has introduced several native frameworks to bridge the gap between the operating system, its system-level assistants, and apps.

App Actions is the long-standing predecessor to AppFunctions. It uses shortcuts.xml and built-in intents to map specific user requests directly to app features. Android Slices were an attempt to surface interactive snippets of an app’s UI directly within the assistant or search interface; they have been effectively deprecated since 2021. Then there's the Direct Actions API, a framework introduced to allow voice assistants to query a foreground app for its specific capabilities in real-time. Gone too. Finally, the Assist API: the fundamental system-level hook that allows a native agent to read the screen context, providing the situational awareness necessary for agents to act on behalf of the user.

In retrospect, the failure of these predecessors likely wasn't due to a lack of vision, but rather a fundamental mismatch between static engineering and the needs of dynamic intelligence. App Actions relied on a rigid library of built-in intents. If an app feature didn't fit into one of Google’s binding categories, it effectively didn't exist to the assistant. Android Slices were killed by the UI maintenance trap. By forcing developers to build and maintain restricted, templated versions of their interface that often felt out of place, Google asked for too much effort for too little user engagement. The Direct Actions API failed because of its requirement that an app is actively running on the screen, which prevents the assistant from performing tasks autonomously. And while the Assist API provided the eyes for the system, it lacked the intelligence. It could scrape a messy tree of text and nodes from the screen, but it couldn't reliably parse that data into meaningful actions without massive compute power and significant privacy trade-offs. Ultimately, these frameworks offered narrow shortcuts when the ecosystem instead required a universal language.

AppFunctions

Unlike its predecessors, which tried to force apps into predefined boxes or complex UI mirrors, the AppFunctions model treats the app as a collection of capabilities to be indexed, rather than a destination to be visited. By shifting the focus from how the app looks to what the app can do, Google is moving toward a model where the agent doesn't just deep-link you into a screen, but picks up the tools to finish the job for you.

AppFunctions have been in the works since late 2024. Although the official android.app.appfunctions package didn't land in the core framework until API level 36, the missing link for developers was the appfunctions Jetpack library, which began its alpha rollout in May 2025. This library allowed early adopters to start wiring their apps for tool use before the corresponding platform APIs were finalized. At that stage, it was a framework waiting for a brain; Jetpack supplied the plumbing, but assistants such as Gemini were not consistently able to invoke those tools on every device or build. Android 16 adds the platform hooks for discovery and execution on supported hardware. As of today, Google still frames the overall agent push as early / beta and describes two parallel tracks:

AppFunctions as structured, self-describing entry points (what this article is about: discrete capabilities agents can call)
UI automation for longer flows when there is no tailored integration: previewed on devices such as the Galaxy S26 series and select Pixel 10 models, in limited verticals and regions, with multi-step delegation already part of that story

In Google’s February 2026 post on the intelligent OS, the Looking ahead section states that Android 17 is meant to broaden these same capabilities; that includes structured AppFunctions and the agentic UI automation previews already tied to hardware such as the Galaxy S26 series and select Pixel 10 models; the stated aim is to reach more users, more developers, and more device manufacturers.

Let's turn to the stack you can use today: Gradle, Kotlin, and the device-facing adb checks that validate a real APK against the current Jetpack and platform drops.

Implementing an AppFunction

To start implementing AppFunctions, your development environment might require a few specific upgrades. First, ensure you are running a recent version of Android Studio to access the latest Gemini-integrated testing tools. While the Jetpack library itself can target a lower minSdk where compatibility allows, you’ll want compileSdk 36 and typically targetSdk 36 so the Android 16 framework can index and run your AppFunctions on device. Next, declare the Jetpack coordinates in your version catalog, then wire plugins, SDK level, KSP, dependencies, and merge ordering in the app module.

Version catalog (`gradle/libs.versions.toml`)

[versions]
appFunctions = "1.0.0-alpha08"

[libraries]
androidx-appfunctions = {
 group = "androidx.appfunctions",
 name = "appfunctions",
 version.ref = "appFunctions"
}
androidx-appfunctions-service = {
 group = "androidx.appfunctions",
 name = "appfunctions-service",
 version.ref = "appFunctions" 
}
androidx-appfunctions-compiler = {
 group = "androidx.appfunctions",
 name = "appfunctions-compiler",
 version.ref = "appFunctions"
}

App module (`app/build.gradle.kts`)

plugins {
 alias(libs.plugins.android.application)
 alias(libs.plugins.kotlin.android)
 // Apply KSP to process the @AppFunction annotations
 alias(libs.plugins.google.devtools.ksp)
}

android {
 // compileSdk 36 aligns with Android 16, where platform AppFunctions APIs land
 compileSdk = 36    
 // ... rest of your config
}

ksp {
 arg("appfunctions:aggregateAppFunctions", "true")
}

dependencies {
 implementation(libs.androidx.appfunctions)
 implementation(libs.androidx.appfunctions.service)
 ksp(libs.androidx.appfunctions.compiler)
}

// Run each merge*Assets after its matching ksp*Kotlin so AppFunctions metadata is generated first
tasks.configureEach {
  if (!name.startsWith("merge") || !name.endsWith("Assets")) return@configureEach
  if (name.contains("ArtProfile")) return@configureEach
  val variant = name.removePrefix("merge").removeSuffix("Assets")
  val kspTask = "ksp${variant}Kotlin"
  if (tasks.names.contains(kspTask)) {
    dependsOn(kspTask)
  }
}

While the Jetpack library automates the plumbing (from generating schemas to registering them) the system fundamentally relies on AppSearch for on-device indexing. The beauty of the library is that it handles the AppSearch integration entirely behind the scenes; you don't need to manage sessions or write storage boilerplate yourself for your AppFunctions to become discoverable. With the environment ready, the next step is to spell out what distinguishes an AppFunction in source.

At its core, an AppFunction is a standard Kotlin function; but it carries a few specific decorations that turn it from a private app method into a public system tool:

The @AppFunction annotation signals to the compiler that a method should be exported as such a system-level tool. Use @AppFunction(isDescribedByKDoc = true) when you write a real KDoc block on that method; the compiler folds that documentation into the metadata agents and indexers consume, so parameter semantics (for example that app1 and app2 are package names) are not left implicit.
AppFunctionContext provides the function with essential situational awareness, such as information about the calling party or access to the app's own resources.
AppFunctionSerializable ensures your custom data classes are properly handled while they travel across process boundaries.

Let's see this in action in a real utility. In my app Be nice, a core feature is the ability to create app pairs (launching two apps in split-screen simultaneously). By exposing this as an AppFunction, we turn a sequence of UI interactions (opening a dialog, choosing apps, customizing parameters) into a single voice command. On eligible devices and assistant builds (as mentioned, Google’s rollout is still limited) you can ask Gemini to create an app pair for contacts and clock. The agent will call our AppFunction, passing the two apps’ package names as strings.

package de.thomaskuenneth.benice.appfunctions

import androidx.appfunctions.AppFunctionContext
import androidx.appfunctions.service.AppFunction
import de.thomaskuenneth.benice.R

class BeNiceFunctions {

  /**
   * Launches two installed apps together in split screen.
   *
   * @param context Execution context supplied by the AppFunctions runtime.
   * @param app1 Name of the first app in the pair.
   * @param app2 Name of the second app in the pair.
   * @return A localized message describing success or failure.
   */
  @AppFunction(isDescribedByKDoc = true)
  suspend fun createAppPair(
    context: AppFunctionContext,
    app1: String,
    app2: String
  ): String {
    val success = performPairing(app1, app2)
    return if (success) {
      context.context.getString(
        R.string.pair_created_success,
        app1, app2
      )
    } else {
      context.context.getString(
        R.string.pair_created_failure
      )
    }
  }

  private fun performPairing(a: String, b: String): Boolean {
    // Be Nice logic omitted for brevity
    return true
  }
}

I used suspend fun, like Google’s own AppFunctions examples do, so we can easily call other suspending APIs from the body whenever the implementation does real async work instead of returning immediately.

Writing a function with @AppFunction creates the capability. However, because AppFunctions are designed to be executed headlessly by the system (even if the app isn't in the foreground), the Android framework needs a static entry point to find and instantiate the code. Previous versions of the Jetpack library required quite a bit of additional boilerplate. Thankfully, most of that is now handled automatically through Manifest Merging and KSP: when you include the appfunctions-service dependency, a pre-built PlatformAppFunctionService is merged into your app's manifest, acting as the universal entry point for the system. The ksp { } block and tasks.configureEach section in the Gradle listing earlier connect your code to that service: appfunctions:aggregateAppFunctions tells the compiler to emit the aggregate inventory and related assets AppSearch reads, and the merge-after-KSP ordering ensures that output is packaged into the APK.

Testing AppFunctions

Next, let's check that your AppFunctions succeed on real setups.

adb shell cmd app_function list-app-functions | grep -F de.thomaskuenneth.benice

This command should print one or more lines that mention your package and expose each AppFunction’s stable id (often a ClassName#methodName form). This proves the OS indexer has picked up the app after install.

On some Android 16 emulator images that command may return No shell command implementation. In my case, updating the AVD to a system image at API level 36.1 brought the app_function shell path to life; Android Studio shows that revision when you choose the platform image, as in the screenshot below.

Executing an AppFunction on the command line can look frightening:

FID=$(adb shell cmd app_function list-app-functions | grep -F de.thomaskuenneth.benice | grep -oE '[A-Za-z0-9_.]+#[A-Za-z0-9_]+' | head -n1) && adb shell "cmd app_function execute-app-function --package de.thomaskuenneth.benice --function \"$FID\" --parameters '{\"app1\":[\"com.foo\"],\"app2\":[\"com.bar\"]}'"

This command prints a JSON payload: on success it is the AppFunction’s return value (here, the string that createAppPair builds); on failure you may see App function not found (wrong id) or a JSON parse error if --parameters does not use the same AppSearch-style encoding as the example; note how each string argument is passed as a one-element JSON array.

If listing or execution still fails, confirm the aggregate assets are actually packaged (for example unzip -l app/build/outputs/apk/debug/app-debug.apk | grep app_functions should list app_functions.xml and app_functions_v2.xml).

For automated tests, treat the layers separately: run the adb checks above on a device to verify that your metadata is packaged and the indexer has picked up your app. Jetpack’s AppFunctionTestRule is built for local JVM runs (the docs pair it with Robolectric-style environments) so you can exercise AppFunctionManager and your @AppFunction logic without a cable; Google explicitly says to prefer real system-level checks when you can. Add instrumented or integration coverage on an API 36+ image when you care about the full stack (AppSearch sync, shell availability, release vs debug). None of that replaces the device-facing section here; it complements it, and deserves its own write-up once you outgrow copy-paste snippets.

Wrap-up

To close this article, let's see the invocation of the Be nice AppFunction end to end:

AppFunctions sit at the intersection of Jetpack, KSP, manifest merging, and on-device indexing (messy in preview, powerful when the wiring is right). When you integrate them, you keep coming back to three things: platform context, a small Gradle and Kotlin surface that connects the aggregate compiler flag to PlatformAppFunctionService, and the device or APK checks that show whether packaging and indexing still line up.

On the official AppFunctions overview, Google only documents adb shell cmd app_function list-app-functions as a shell check; there is no second, documented adb path for the full schema text (including KDoc folded in via isDescribedByKDoc). For that, read assets/app_functions.xml / app_functions_v2.xml from the APK, or query metadata through AppFunctionManager-style APIs—the same place agents are expected to pull richer descriptions. Anything further that adb shell cmd app_function help shows on a given device is platform-specific and is not spelled out on that overview page.

One caveat worth carrying forward: in my project, making each merge*Assets task depend on the matching ksp*Kotlin task was necessary so KSP-generated AppFunctions assets were present before packaging. That ordering is not spelled out in every official sample, and it may stop being required as the Android Gradle Plugin, KSP, or the AppFunctions toolchain tightens its own task graph. Treat it as something to validate on your stack: if app_functions.xml / app_functions_v2.xml show up in the APK without the extra tasks.configureEach block, you can drop it; if they are missing at runtime, the dependency ordering is still a reliable fix.

If you ship with minify enabled (isMinifyEnabled / R8), the AppFunctions AndroidX artifacts ship consumer ProGuard rules that keep much of the generated and reflection-heavy surface for you. You should still smoke-test a release build on a device: if execution or discovery fails only after shrinking, inspect R8 output and add targeted -keep rules for your own @AppFunction classes or related types; start from what the library already merges rather than copying random snippets from older posts.

In this article, I showed you how to implement an AppFunction. As a publisher you expose AppFunctions in your APK and rely on indexing plus your own validation of arguments. Callers that discover or execute other apps’ functions go through AppFunctionManager-style APIs and sit behind platform rules; privileged assistants hold permissions such as EXECUTE_APP_FUNCTIONS that ordinary store apps do not get by declaring a line in the manifest. Google still describes much of the end-to-end agent path as experimental and capacity-limited, so assume your parameters can be reached only by trusted system-side callers today, and still treat them like untrusted input.

References

The Future of Android Apps with AppFunctions by fellow GDE Shreyas Patil goes deep on dependency injection with AppFunctionConfiguration, a note-taking sample, and adb-driven execution. Further reading beyond the links already woven through the article (overview, Jetpack release notes, platform android.app.appfunctions, intelligent-OS blog, Play listing, and AppFunctionTestRule):

AppFunction annotation (isDescribedByKDoc, compiler behavior, supported types)
AppFunctionManager (Jetpack discovery and execution APIs)
AppSearch (on-device indexing stack the runtime builds on)
Merge multiple manifest files (how library manifests contribute PlatformAppFunctionService and related entries)
EXECUTE_APP_FUNCTIONS (permission called out in the trust discussion)

From Vibe-Coding to Reality: Building MarvinSync

Thomas Künneth — Fri, 03 Apr 2026 13:17:03 +0000

If you saw my posts back in February on LinkedIn and Mastodon, you know I’ve been deep in a Cursor session. I promised to pull back the curtain on how MarvinSync—my new macOS utility for syncing local music to Android—came to life through the lens of AI-assisted development.

Before we get to the binaries (which are coming soon, I promise!), I want to share the vibe-coding post-mortem of how the first version actually took shape. If you want to follow along with the code as I describe it, the full project is already live on Codeberg.

What is MarvinSync? (And why Vibe-Code it?)

MarvinSync is a utility designed for a specific niche: people who still believe in local media ownership. It bridges the gap between a curated macOS music library and an Android device. No streaming, no cloud—just your folders, your metadata, and a clean sync via ADB (Android Debug Bridge).

But there’s a meta-story here. As an Android GDE, I spend my life deep in Kotlin, Compose, and Kotlin Multiplatform. Naturally, KMP would have been the logical choice for a cross-platform sync tool. However, I wanted to take this opportunity to go fully native on the Mac side using Swift and SwiftUI.

I’ll be the first to admit: I am no Swift expert. This is where vibe-coding comes in. I used Cursor to bridge the gap between my architectural knowledge and my lack of Swift syntax fluency. I provided the vibe—the logic, the structure, and the constraints—and the AI handled the boilerplate and the nuances of a language I’m still learning.

Trusting the folder, not the tag

One of the first big hurdles was handling music metadata. Initially, we tried the traditional route of scanning ID3 tags using standard APIs. The result was a mess of duplicates and wrong titles that didn't match how my files were actually organized.

The solution was to stop being smart with metadata and start being literal with the file system. We shifted to a strict folder-based hierarchy where the directory structure itself defines the library.

/// Inside `MusicFolderStore`. Structure: base / Artist / Album / tracks.
/// `extractArtworkFromFirstTrack` walks audio files and uses `AVMetadataItem` (identifier-based artwork only).
private func scanForAlbumsFolderBased(in baseURL: URL) -> [Album] {
    let artistURLs: [URL]
    do {
        let contents = try fileManager.contentsOfDirectory(
            at: baseURL,
            includingPropertiesForKeys: [.isDirectoryKey],
            options: [.skipsHiddenFiles]
        )
        artistURLs = contents.filter { url in
            (try? url.resourceValues(forKeys: [.isDirectoryKey]).isDirectory) == true
        }
    } catch {
        NSLog("MusicFolderStore: failed to list base folder: \(error.localizedDescription)")
        return []
    }

    var result: [Album] = []

    for artistURL in artistURLs {
        let artistName = artistURL.lastPathComponent

        let albumURLs: [URL]
        do {
            let contents = try fileManager.contentsOfDirectory(
                at: artistURL,
                includingPropertiesForKeys: [.isDirectoryKey],
                options: [.skipsHiddenFiles]
            )
            albumURLs = contents.filter { url in
                (try? url.resourceValues(forKeys: [.isDirectoryKey]).isDirectory) == true
            }
        } catch {
            continue
        }

        for albumURL in albumURLs {
            result.append(Album(
                title: albumURL.lastPathComponent,
                artist: artistName,
                artwork: extractArtworkFromFirstTrack(in: albumURL),
                albumURL: albumURL
            ))
        }
    }

    return result.sorted { ($0.artist, $0.title) < ($1.artist, $1.title) }
}

By using a non-recursive scan of the directory structure instead of metadata deep-dives, the app finally reflected the vibe of the actual library. It’s a reminder that sometimes the simplest architecture—the folder tree—is more robust than the most modern API.

Making Android Feel Native

A huge part of the session was dedicated to the handshake between macOS and Android. Making ADB feel like a native Mac service requires some plumbing. We built a ConnectedDeviceChecker that polls for devices every two seconds via ADB.

The checker publishes a @Published deviceStatus (ADBDeviceStatus) for the window’s status line; isDeviceConnected is simply deviceStatus == .oneDevice. The Sync button is context-aware: it only turns on when exactly one authorized device shows up in adb devices—because with two targets (say, a phone and an emulator), which device? is ambiguous until we teach the app to choose.

enum ADBDeviceStatus: Sendable {
    case adbNotSet
    case adbNotAccessible
    case noDevice
    case oneDevice
    case multipleDevices

    var statusMessage: String {
        switch self {
        case .adbNotSet: return "ADB not configured"
        case .adbNotAccessible: return "ADB not found or not accessible"
        case .noDevice: return "No device connected"
        case .oneDevice: return "One device connected"
        case .multipleDevices: return "More than one device connected"
        }
    }
}

/// Polls `adb devices` every 2s; updates `deviceStatus` from bookmarked `store.adbURL`.
final class ConnectedDeviceChecker: ObservableObject {
    @Published private(set) var deviceStatus: ADBDeviceStatus = .adbNotSet
    var isDeviceConnected: Bool { deviceStatus == .oneDevice }

    private weak var store: MusicFolderStore?
    private var timer: Timer?
    private let queue = DispatchQueue(label: "com.example.MarvinSync.adbCheck", qos: .utility)

    init(store: MusicFolderStore) {
        self.store = store
        timer = Timer.scheduledTimer(withTimeInterval: 2.0, repeats: true) { [weak self] _ in
            self?.check()
        }
        RunLoop.main.add(timer!, forMode: .common)
        check()
    }

    deinit { timer?.invalidate() }

    private func check() {
        guard let store = store else {
            DispatchQueue.main.async { [weak self] in self?.deviceStatus = .adbNotSet }
            return
        }
        guard let adbURL = store.adbURL else {
            DispatchQueue.main.async { [weak self] in self?.deviceStatus = .adbNotSet }
            return
        }
        queue.async { [weak self] in
            let status = Self.runADBDevices(executableURL: adbURL)
            DispatchQueue.main.async { self?.deviceStatus = status }
        }
    }

    private static func runADBDevices(executableURL: URL) -> ADBDeviceStatus {
        let process = Process()
        process.executableURL = executableURL
        process.arguments = ["devices"]
        let pipe = Pipe()
        process.standardOutput = pipe
        process.standardError = FileHandle.nullDevice
        do {
            try process.run()
            process.waitUntilExit()
        } catch {
            return .adbNotAccessible
        }
        let data = pipe.fileHandleForReading.readDataToEndOfFile()
        pipe.fileHandleForReading.closeFile()
        guard let output = String(data: data, encoding: .utf8) else { return .adbNotAccessible }
        let n = output.components(separatedBy: .newlines).filter { $0.contains("\tdevice") }.count
        switch n {
        case 0: return .noDevice
        case 1: return .oneDevice
        default: return .multipleDevices
        }
    }
}

Because MarvinSync is a well-behaved macOS citizen, it respects app sandboxing. However, a sandboxed app can't remember a file path after a reboot without help. To solve this, we implemented security-scoped bookmarks. This ensures that once you grant permission to access your Music folder (and separately the adb binary, often hiding under ~/Library), the app can resolve that permission on the next launch.

// Same pattern as `MusicFolderStore`: two bookmarks, two keys.
private enum Defaults {
    static let musicFolderBookmarkKey = "musicFolderBookmark"
    static let adbBookmarkKey = "adbBookmark"
}

private func saveBookmark(for url: URL) throws {
    let data = try url.bookmarkData(
        options: .withSecurityScope,
        includingResourceValuesForKeys: nil,
        relativeTo: nil
    )
    UserDefaults.standard.set(data, forKey: Defaults.musicFolderBookmarkKey)
}

private func saveADBBookmark(for url: URL) throws {
    let data = try url.bookmarkData(
        options: .withSecurityScope,
        includingResourceValuesForKeys: nil,
        relativeTo: nil
    )
    UserDefaults.standard.set(data, forKey: Defaults.adbBookmarkKey)
}

/// On startup: load `Data`, resolve, call `startAccessingSecurityScopedResource()`.
/// MarvinSync then checks `isStale` and, if needed, calls `saveBookmark` or `saveADBBookmark` again for that URL.
private func resolvedURL(bookmarkKey: String) -> URL? {
    guard let data = UserDefaults.standard.data(forKey: bookmarkKey) else { return nil }
    var isStale = false
    guard let url = try? URL(
        resolvingBookmarkData: data,
        options: .withSecurityScope,
        relativeTo: nil,
        bookmarkDataIsStale: &isStale
    ) else { return nil }
    guard url.startAccessingSecurityScopedResource() else { return nil }
    return url
}

Sync itself grew into a small pipeline: verify the Android base path, remove ignored albums on the device with carefully validated paths and shell-safe quoting (parentheses in folder names bite), then incremental adb push with size checks so we only transfer files that are missing or changed. All of that is more interesting in the repo than in a short essay—but it’s the kind of boring engineering AI accelerates when you already know what must be true.

What the code fences don’t show (but the session did)

The snippets above are the architectural spine. The rest of the Cursor log is mostly product and UX: a sectioned A–Z grid; tap an album to include or exclude it for sync, with a green checkmark when it will be copied and ignored paths persisted as relatives of the music folder. Sync opens a sheet with per-step spinners, checkmarks, and failures—errors stay on the row that broke, not in a separate alert. Removal runs only for ignored folders that still exist on the device; copy steps appear only when a size comparison shows something missing or stale, with human-readable labels (Album (Artist)) instead of raw paths. Cancel stops the pipeline; a Checking … line covers the otherwise silent do we need to copy? work. Fixing sheet height so the window stopped juddering as rows appeared took the same stubbornness as the Settings form. None of that required a fourth code listing for this post—the Codeberg tree is the ground truth—but it deserved ink here so the story matches the full chat, not only the plumbing.

The Friction of Vibe-Coding

People often ask if AI makes coding effortless. The chat log tells a different story. Cursor is excellent at bulk work and at iterating when you give crisp specs—but SwiftUI Form on macOS still caught me in a loop of almost-right layouts: labels, value columns, and path text fields that looked centered or pushed to the wrong edge no matter how many HIG-aligned refactors we tried.

At one point the chat reads like an argument, not a pull request. I wrote things I would not put in a colleague’s review—frustration that went personal (What is wrong with you?, and worse). The punchline is not that the model deserved it; it doesn’t have feelings or pride. The punchline is that I still needed to vent, then to stop accepting close enough. The fix, when it came, was almost embarrassingly small: in our case, making the Android base path TextField behave in the form the way Apple intends—.labelsHidden() so the field wasn’t fighting an implicit label column—and refusing another round of decorative layout hacks.

That friction is the human bit of AI-assisted development: not mistaking the chat for a person, but not mistaking plausible for shipped either. The best sessions, this one included, end with you back in control—exact snippet in hand, build green, behavior finally matching the picture in your head.

What’s Next?

The grid, sync sheet, and guardrails sketched above are in the repo; I even handcrafted the app icon myself (no AI involved there!).

As I mentioned in my February posts, the binaries are coming. But I wanted to document this journey first. Building MarvinSync hasn't just been about creating a tool I needed; it’s been an experiment in how a veteran Android dev can use AI to build natively for the Mac.

The source is open, the vibe is set, and soon, it'll be time to sync.

Refuelling your Jetpack

Thomas Künneth — Sun, 08 Mar 2026 11:36:03 +0000

If you are an Android developer, you know Jetpack. It changed how we build Android apps. But that was long ago. Today, the ecosystem is shifting again. We aren't just building for one platform anymore. We are building for the world. Let me show you how to take the Jetpack libraries you know and use them to fuel a new generation of applications that run everywhere.

From Jetpack to a unified architecture

First, let's ground ourselves. What exactly is Jetpack? It's more than just a bag of libraries. It is Google's opinionated answer to Android development. It unbundled features from the OS, so we could update our apps without waiting for Android system updates. It gave us backward compatibility. Most importantly, it gave us guidance. It stopped the wild west of Android development and brought us a standard way to build.

Before Jetpack, we lived in an era of fragmentation. New features were tied to the OS. If you wanted the latest UI on an older phone, you were out of luck. Eventually, Google introduced the Support Library to fix this. It sort of worked, but it was a mess. We had v4 support, v7 appcompat, v13... it was dependency hell. We needed a reboot.

That reboot came in two steps. In 2017, Google announced Android Architecture Components at I/O—ViewModel, Room, Lifecycle, LiveData—and they went 1.0 stable that November. That was the how to architect piece. Then, at I/O 2018, came Jetpack: the umbrella name and the migration to androidx.*. Eventually, everything moved to the new namespace. Libraries were strictly unbundled—own versions, own cycles, semantic versioning so we could reason about compatibility. So: Architecture Components in 2017, Jetpack and androidx in 2018.

Today, we have solved one problem but created another: The Jetpack Jungle. There are now over 130 artifacts in the suite. We have historical baggage. Deprecated libraries still sit next to modern ones—for example lifecycle-extensions, which Google deprecated and replaced with separate lifecycle-runtime, lifecycle-viewmodel, and so on, but it still turns up in old tutorials. Or security-crypto, deprecated with no clear official successor, but still in the docs. We have three different ways to do background work, two ways to do navigation, and endless UI helpers. The challenge is no longer how do I do this? but which of these 130 libraries should I actually use?

To survive the jungle, we need a map. A golden path, if you will. It's the curated, opinionated stack that Google actually recommends today. Stick to it and you avoid the jungle. UI: reactive, driven by state. Presentation: ViewModels that survive config changes. Navigation: a single graph defining your flow. Data: Room for database, DataStore for preferences. That stack is the gold standard for Android—but it no longer stops there. Everything on that list—Compose, ViewModels, Navigation, Room, DataStore—is available in Kotlin Multiplatform. You can keep the same architecture and the same APIs and compile them for iOS, Desktop, and the Web. One architecture, same code, everywhere.

That stack has a few key pieces. The UI layer is Compose Multiplatform. It is the exact same declarative, reactive paradigm you use on Android, just unbundled from the OS. You write composables, and they react to state. On Android, it's Jetpack Compose. On iOS and Desktop, it uses the Skia graphics engine to draw pixel-perfect UI while running natively on the hardware. This means you aren't learning three different UI frameworks. You aren't context-switching. You are taking your existing Android expertise and applying it to the entire world.

For state and lifecycle: Android didn't invent the ViewModel. Cross-platform frameworks like Xamarin were using the MVVM pattern to share logic between iOS and Android long before Jetpack existed. The good news is that Android and KMP have finally adapted this proven standard. You put your ViewModel in shared code. It survives configuration changes. It holds your state. It's the industry standard for a reason, and now it's the standard for our shared code, too.

Navigation is another piece. It used to be where cross-platform architectures fell apart. But not here. With Navigation Compose, your navigation graph travels with you. You declare your routes, your arguments, your back stack, and your deep links once in shared code. Type-safe. Whether it's an Android Activity, an iOS View Controller, or a Desktop Window, the platform code is just a thin container hosting your navigation. You aren't reimplementing routing logic three times. You define the flow once, and it drives the UI everywhere.

For local database storage, we use Room. If you haven't used it before, Room is a full Object-Relational Mapper (ORM) wrapping SQLite. It lets you define your data as simple Kotlin objects and maps them automatically to database tables. Its superpower is compile-time verification. Unlike many ORMs that fail at runtime, Room checks your SQL queries against your schema as you build. In this architecture, Room runs natively on iOS, Android, and Desktop, giving you a single, type-safe data layer with the performance of raw SQLite.

For configuration and preferences: every app needs to store something—whether it's a dark mode toggle, a session token, or feature flags. Usually, this means writing one implementation for iOS using UserDefaults and another for Android using SharedPreferences. With DataStore, we unify this. It is a modern, multiplatform key-value store built entirely on Kotlin coroutines. It is asynchronous by default, preventing UI freezes on any platform. You write your preference logic once in shared code, and it handles the native storage details for you.

How it fits together

So, how does this fit together? You have one shared core. This module contains almost everything: your Compose UI, your Navigation graph, your ViewModels, and your Database. Surrounding that, you have thin native shells. The Android app, the iOS app, and the Desktop app. They do little more than initialize the process and host the shared UI. They might add a splash screen or handle push notifications, but the actual application—the screens and the logic—is shared. This means no duplicate business logic and no synchronization issues between platforms.

The shared module is the structural center of your application. Inside commonMain, you place the core components we just went through. But when you need to interact with specific OS APIs—like file paths, Bluetooth, or system intents—you use the expect / actual pattern. You declare the interface in the shared code, and the platform module provides the implementation. This keeps your business logic pure and testable, ensuring platform details don't leak into your core architecture.

The platform modules are intentionally thin. On Android, you have a single Activity calling setContent. On iOS, you have a standard View Controller that hosts the shared Compose UI. On Desktop, it's just a main() function. Crucially, this is where you initialize your Dependency Injection—like Koin. You wire it up once at startup, and then the rest of the application logic is fully shared.

Dependency injection often raises a question: Isn't Hilt the recommended Jetpack DI? Yes, for Android it's fantastic. But Hilt relies heavily on Dagger and Java annotation processing, which simply does not work on iOS or Desktop. Critically, Google has not yet said anything about Hilt going multiplatform. There is no roadmap. So, to keep our shared code clean and compile-safe today, we use a pure Kotlin solution like Koin. You define your modules in shared code; each platform supplies the actuals (e.g. where's the data directory). One container, init once per platform. It effectively becomes the standard for this architecture by necessity.

To make this concrete: in CMP Unit Converter, the Koin module lives in commonMain. The database and ViewModels are provided there; the platform supplies the DB path via expect / actual:

// commonMain/.../di/AppModule.kt
val appModule = module {
    single<AppDatabase> { getRoomDatabase(getDatabaseBuilder()) }  // getDatabaseBuilder() is expect/actual
    viewModelOf(::AppViewModel)
    viewModelOf(::TemperatureViewModel)
    viewModelOf(::DistanceViewModel)
}

In practice: CMP Unit Converter

Enough theory—let's walk through the full picture. I built an app called CMP Unit Converter to prove this stack works. It converts temperatures and distances, stores your history, and remembers your preferences. It runs on Android, iOS, and Desktop, and it's built entirely on the stack we just went through: Compose for UI, ViewModels for state, Room for history, and Koin for injection. Let's tear it apart and see how it works.

When you open the project, you'll notice the structure right away. It follows the modern AGP 9 guidelines. Gradle 9.1 and AGP 9 are the baseline. In this repo the modules are: shared (the library), composeApp (the Android app), desktopApp, and iosApp is a separate Xcode project. Your Android app—here, composeApp—is its own module: just application code, no Kotlin Multiplatform plugin. The shared module uses the new com.android.kotlin.multiplatform.library plugin. In shared's build.gradle.kts you configure the Android target with androidLibrary { } inside the kotlin { } block, not the old top-level android { } block. The app module uses AGP's built-in Kotlin, so you don't apply the Kotlin Android plugin there. Android is just another target, like Desktop or iOS. This clean separation is key: the app is a thin shell, the library does the heavy lifting. It's a bit of a mental shift if you had one composeApp doing everything, but it pays off in clearer separation and faster builds.

In code it looks like this:

// shared/build.gradle.kts
plugins {
    alias(libs.plugins.androidKotlinMultiplatformLibrary)
    // ...
}
kotlin {
    androidLibrary { namespace = "..."; ... }
    // ...
}

// composeApp/build.gradle.kts
dependencies {
    implementation(project(":shared"))
    // ...
}

The shared UI lives in commonMain—for example, ConverterScreen.kt. That's the app's main screen: standard Compose code. But notice the resources—we don't have XML strings for Android and Localizable.strings for iOS. We put everything in the composeResources folder. We access them in Kotlin using the generated Res object—Res.string or Res.drawable. At compile time, CMP bundles these into the correct native format for each platform. You write the UI once, and it looks native everywhere.

// commonMain/.../ConverterScreen.kt
@Composable
fun ConverterScreen(
    navigationState: NavigationState,
    viewModel: AbstractConverterViewModel,
    scrollBehavior: TopAppBarScrollBehavior
) { ... }

// Res API (e.g. AppIcons.kt)
val Thermostat: DrawableResource get() = Res.drawable.ic_thermostat
// In composables: stringResource(Res.string.app_name)

The brain of the app is the converter ViewModels—we have TemperatureViewModel and DistanceViewModel, both in shared code and registered with Koin. When the UI loads, it asks for the ViewModel via koinViewModel(). It doesn't care if it's running on a Pixel or an iPhone. The ViewModels survive configuration changes on Android and manage state on iOS seamlessly. Same classes everywhere.

// commonMain/.../di/AppModule.kt
val appModule = module {
    single<AppDatabase> { getRoomDatabase(getDatabaseBuilder()) }
    viewModelOf(::TemperatureViewModel)
    viewModelOf(::DistanceViewModel)
}

// In a composable (e.g. App.kt)
viewModel = koinViewModel<TemperatureViewModel>()

For data, we use Room and DataStore. The app saves your conversion history in a SQLite database using Room. It remembers your last selected unit using DataStore. The only platform-specific code here is a tiny expect/actual function to tell the app where to save the file on disk (e.g. Application Support on iOS, getDatabasePath on Android). Everything else—the DAOs, the queries, the preference keys—is shared. We aren't fighting with CoreData or SharedPreferences.

// commonMain/Platform.kt
expect fun getDatabaseBuilder(): RoomDatabase.Builder<AppDatabase>

// androidMain: path from context.getDatabasePath("...")
actual fun getDatabaseBuilder() = Room.databaseBuilder<AppDatabase>(
    context = context,
    name = context.getDatabasePath("CMPUnitConverter.db").absolutePath
)
// iosMain: path from getDirectoryForType(DirectoryType.Database) → Application Support

The platform apps are just entry points. On Android, the Application class calls initKoin at startup (e.g. in CMPUnitConverterApp); MainActivity then calls setContent. On iOS, ComposeView inside a ViewController. On Desktop, main() launches the window. There's one little gotcha on iOS. When we export our Kotlin initKoin function to Swift, Kotlin/Native renames it to doInitKoin because it returns Unit. It's a small quirk, but knowing it saves you a "Method Not Found" error. Call doInitKoin in your Swift AppLifecycle and you're good to go.

In Kotlin we have:

// commonMain/.../di/KoinApp.kt
fun initKoin(config: KoinAppDeclaration? = null) {
    startKoin {
        includes(config)
        modules(appModule)
    }
}

On iOS, Swift sees the same function with the "do" prefix:

// iOS (Swift). Kotlin exports Unit-returning functions with "do" prefix:
KoinAppKt.doInitKoin()

Takeaways and resources

One of the most common pitfalls is version mismatch. Your shared module pulls in Compose Multiplatform and a specific Compose runtime. Your Android app uses activity-compose to call setContent. If activity-compose was built for a different Compose version, you get crashes like NoSuchMethodError at runtime. So align activity-compose with the Jetpack Compose version that Compose Multiplatform uses—there’s a compatibility table in the docs. Also keep the Compose Compiler plugin version in sync with your Kotlin Multiplatform plugin. When in doubt, check the Compose Multiplatform and AGP compatibility pages before you upgrade. That habit pays off.

A few other things help in practice. If you’re starting fresh, use the AGP 9 structure from day one. Migrating an old single-module app to the new structure works, but it’s more work. And expect / actual is your friend: put every platform quirk behind an expect declaration, implement it per platform, and document the odd ones—like doInitKoin on iOS—so your future self or your team don’t “fix” what isn’t broken. That keeps the shared code clean and the architecture solid.

To recap: the story—where Jetpack came from, the jungle of 130+ artifacts, the Golden Path map, and that it all runs beyond Android. The lineup—Compose Multiplatform, ViewModel, Navigation, Room, DataStore—all available in KMP. How it fits together: one shared module, thin platform shells, entry points, dependency injection. And the AGP 9 structure in a real project, CMP Unit Converter—one codebase, multiple binaries.

A few topics were left out of this overview. For example, testing: your shared module is highly testable. ViewModels, repositories, use cases—you can run them in commonTest or on the JVM. Room works with an in-memory database; same DAOs and entities. For expect/actual you supply test implementations. The Kotlin and Android docs and the CMP Unit Converter repo show how. Version alignment was mentioned above: when you upgrade, align activity-compose with the Compose version your shared module uses, and check the compatibility pages. And what's not in KMP yet: WorkManager, CameraX, a few others. For those you stay in the Android app module or look for community options. The stack we focused on is the part that's officially supported and where you'll spend most of your time.

Where is this going? Google and JetBrains are actively moving Jetpack beyond Android. We're not there yet for every library, but the trend is clear: the same APIs you use on Android are being made available in KMP. The Golden Path stack we've talked about is at the front of that wave. So investing in this architecture now—Compose, ViewModel, Navigation, Room, DataStore—is not a bet on a niche. It's aligning with where the ecosystem is headed. One architecture, many platforms.

For your own projects, here's a practical checklist. UI: Compose Multiplatform. State: ViewModel and Lifecycle Runtime in KMP. Navigation: Navigation Compose in KMP. Persistence: Room and DataStore in KMP. Structure: one shared module, thin Android, iOS, and Desktop apps—and if you're on Android, use the AGP 9 layout with the new KMP library plugin. Dependency injection: Koin or Hilt, init once at app startup on each platform. Stick to this stack and you avoid the jungle. You get one architecture that runs everywhere.

For more detail, the Kotlin and Compose Multiplatform docs on kotlinlang.org and jetbrains.com are the place to start. For the Android side—the new KMP library plugin, AGP 9, and the migration steps—developer.android.com has the official guides. The Compose Multiplatform compatibility page tells you which Jetpack Compose version lines up with which CMP version. When in doubt, check it before you upgrade—it saves head-scratching. And there are samples: CMP Unit Converter is one; the Kotlin and Android teams publish more. You're not on your own—the docs and the samples are there to back you up.

Setting up local Codeberg runners

Thomas Künneth — Mon, 02 Mar 2026 18:29:02 +0000

In my previous article, First steps towards Codeberg, we looked at how to get set up and comfortable on the platform. Now that your code has a new home, it’s time to level up your workflow with automation.

While Codeberg provides shared runners for CI/CD, there are plenty of reasons to run your own, among others,

performance
specific hardware requirements
avoiding queue times

In this guide , I'll show you how to use your local machine as a CI/CD runner for Codeberg. This works behind firewalls and home routers without needing to expose your IP address. Sounds cool, right?

Depending on your needs, you can choose between two setup methods: the containerized approach using Docker / OrbStack, or running the act_runner binary directly. Since I am on a Mac with Apple Silicon, the choice actually matters quite a bit. Docker on M-series chips runs Linux ARM64 images, and unfortunately, the standard Android build tools don't officially support that environment yet. If you are here for Android builds, you might want to look at the binary method; otherwise, Docker is a safe bet.

First, get your registration token.

On Codeberg, navigate to Settings > Actions > Runners
Click Create new runner
Copy the Registration Token

Next, prepare the workspace.

Docker / OrbStack

Open your terminal and create a folder to house the runner's identity and configuration.

mkdir codeberg-runner
cd codeberg-runner

After that, create the configuration by putting a file named docker-compose.yml in that folder:

code docker-compose.yml

Here's how that file should look like. Replace <TOKEN> and <name-of-your-runner> with your registration token and a name for your runner. <name-of-your-runner> will appear in the Codeberg dashboard.

services:
  runner:
    image: gitea/act_runner:latest
    container_name: codeberg_runner
    restart: always
    environment:
      - GITEA_INSTANCE_URL=https://codeberg.org
      - GITEA_RUNNER_REGISTRATION_TOKEN=<TOKEN>
      - GITEA_RUNNER_NAME=<name-of-your-runner>
      - ACT_RUNNER_DEFAULT_IMAGE=gitea/runner-images:ubuntu-22.04
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./data:/data
    command: daemon

Now we can launch and register our runner. Run the following command from inside the codeberg-runner folder. This will pull the image, register the runner automatically, and start the background service.

docker compose up -d

To verify the connection you can check the logs to ensure the registration was successful.

docker logs codeberg_runner

You should see Starting runner daemon.

You'll also see your runner in the Codeberg settings.

Once the initial setup is complete, use these commands to control your runner:

Action	Command	Result
Go Offline	`docker compose stop`	Safely pauses the runner; it will show as "Offline" on Codeberg
Go Online	`docker compose start`	Reconnects to Codeberg; the runner will show as "Idle" (ready)
View Live Logs	`docker compose logs -f`	Streams the activity; you'll see jobs being picked up in real-time.
Check Identity	`ls -la ./data`	Verifies the `.runner` file exists (your runner's "ID card")

That's it. Your Docker-based runner is now active and polling for jobs. To use it, you simply need to update your workflow file (usually in .gitea/workflows/) to target this specific runner.

jobs:
  test:
    runs-on: blackmac-runner
    steps:
      - run: echo "Hello from my local runner!"

In the next section, I'll show you an alternative method. act_runner is the lightweight binary that powers the Docker image we just used. By configuring it with a host label, we can run jobs directly on your machine without a container layer. This allows the runner to access your local tools (for example, Xcode or the Android SDK) directly. As mentioned earlier, this is the preferred method if you need to break out of the container's isolation or are dealing with architecture-specific limitations on Apple Silicon.

act_runner

First, let's install act_runner. We will also install node, which is required to run standard actions (like actions/checkout) directly on the host machine.

brew install act_runner node

Next, generate the default configuration file so we can customize the runner settings.

mkdir -p ~/.config/act_runner
act_runner generate-config > ~/.config/act_runner/config.yaml

Open ~/.config/act_runner/config.yaml and locate the runner section. Add your custom label ending in :host to ensure jobs run directly on your machine:

 runner:
   labels:
     - "blackmac-runner:host"

Now we can register the runner. Replace YOUR_REGISTRATION_TOKEN with the one you obtained from the Codeberg settings earlier. This command links your local machine to the instance using the configuration and label we just defined.

act_runner register --no-interactive \
  --instance https://codeberg.org \
  --token YOUR_REGISTRATION_TOKEN \
  --name blackmac-runner \
  --labels blackmac-runner:host \
  --config ~/.config/act_runner/config.yaml

Finally, start the runner daemon. It will connect to Codeberg and immediately begin listening for incoming jobs.

act_runner daemon --config ~/.config/act_runner/config.yaml

And we are live! The daemon is now connected to Codeberg and listening for jobs. To use it, simply reference the label we just registered (blackmac-runner) in your workflow file, exactly as shown earlier. The key difference here is that your jobs will now execute directly on your Mac's host system, bypassing the container layer and giving you full access to local tools like Xcode or the Android SDK.

F-Droid on ChromeOS: trying to get behind the road blocks

Thomas Künneth — Fri, 09 Jan 2026 12:43:52 +0000

F-Droid has been a trusted source for high-quality open-source Android apps for many years. While ChromeOS devices come with Google Play (provided it is enabled in Settings), also having F-Droid available offers a gateway to a vast ecosystem of privacy-respecting software.

F-Droid is not available on Google Play. Instead, you usually download it directly from the official project homepage at f-droid.org.

Once the download is complete, your first instinct would likely be to open the APK file using the Files app:

Unfortunately this would give you just a message saying Turn on Chrome OS Developer mode to install apps from sources other than the Play Store.

That sounds scary, doesn't it? What's more, it's simply not true. You do not need to enable the full-fledged Developer Mode, which in itself may open up more severe security issues. Instead, you can simply enable ADB debugging. You’ll find this toggle in Settings under the Develop Android apps section.

Once ADB debugging is toggled and an APK has been downloaded, a simple adb install triggers the installation. Let's use the internal Linux container (Crostini) to do so.

First, open your Chrome OS Terminal and install a few required tools

sudo apt update && sudo apt install android-tools-adb curl -y

Next, connect the Linux container to the Android subsystem

adb connect 100.115.92.2:5555

After running the adb connect command, keep your eyes on the Chromebook screen. You may need to manually authorize the debugging link and confirm the installation.

Finally, use curl to grab the latest version of F-Droid and install it

curl -L https://f-droid.org/F-Droid.apk -o fdroid.apk && adb install fdroid.apk

Once we have opened F-Droid, we can browse the catalogue. However, trying to install an app, shows an error saying we need to enable Developer mode.

Wait a minute. There's something in Settings, right?

Yes, Install unknown apps.

Unfortunately, enabling this does not change anything. What's more, trying to grant the permission on the command line gives us a little bit of an explanation.

adb shell pm grant org.fdroid.fdroid android.permission.REQUEST_INSTALL_PACKAGES

Conclusion

So, what can we make out of this? Well, this article clarifies that you do not need to bring your ChromeOS device into Developer mode to install Android apps (I guess most of us knew that 😅); even though Google tries hard to persuade you otherwise.

Next. Switching on developer mode is usually a bad idea. So, why does Google stick to it? Well, while I can certainly only speculate, tying the users to Google Play is in the interest of Google, whereas allowing alternative app stores definitely is not. We see the hesitation on plain Android - it took law suits and a lot of developer backlash to force Google into making the installation of Play Store alternatives less painful. And it will take Android 17.

Regarding ChromeOS, having apps download and install other apps seems, at least for now, impossible to do for ordinary users.

One final thought. Since F-Droid has been the hook for this article, I feel the need to praise them to as much extent as I possibly can. They continue to be a landmark institution for Android open source software since many years. It's certainly not their fault that they can't easily be used on ChromeOS.

First steps towards Codeberg

Thomas Künneth — Wed, 31 Dec 2025 11:43:33 +0000

A lot of Europeans are currently talking about Europe having to become more independent from US-based big tech. Being a European myself, I feel the need for this, too. However, just talking won't make a difference. So, why not make this our New Year's resolution? Here's mine: I love open source. Given GitHub's recent trajectory toward centralisation, I feel there are better-suited homes for my repositories. That's why I will start migrating them to Codeberg.

What is Codeberg?

Codeberg is a community-driven non-profit platform for hosting software projects. Many consider it the leading independent alternative to commercial services like GitHub and Bitbucket. While it looks and feels very similar to GitHub, its underlying philosophy and legal structure are fundamentally different: unlike GitHub, which is owned by Microsoft, Codeberg is run by a German non-profit organisation called Codeberg e.V.. It is funded by donations rather than venture capital or ads. The platform runs on Forgejo, which is a community-governed fork of Gitea. Therefore, the very software used to run the site is itself open source and transparent. And it is privacy-focused. Since Codeberg is hosted in the European Union (Germany), it adheres to strict GDPR standards. It does not track users for advertising and avoids black box AI features like GitHub Copilot.

Does this sound appealing? To me it certainly did. That's why I decided to jump right in. In this introductory article, I'll show you my first baby steps, that is, registering and migrating the first GitHub repository.

Signing up

Registering is a very quick and pleasant experience. Visit https://codeberg.org, find and click the Register button.

Just enter a username, your email address, a password, and the randomly generated number or word.

Once you click on Register Account, you should receive an email with the inevitable confirmation link.

Click on the link to verify your email address. You will be directed to your personal Codeberg landing page.

Next, you may want to update some settings.

While I won't walk you through the settings, I would like to encourage you to show your Codeberg account on Mastodon. First, add Mastodon to Codeberg. Look for the Website field or the Social Accounts section (if available in the current UI). Paste your full Mastodon profile URL (for example, https://mastodon.social/@tkuenneth) and click Update Profile at the bottom. Codeberg automatically adds the rel="me" attribute to the website link in your profile, which is exactly what Mastodon needs to verify you.

Next, open your Mastodon instance and visit your Profile page. Click Edit profile and find the Extra fields in Basic information. This is where you add labels and links. In the label column, type something like Codeberg. In the content column, paste your Codeberg profile URL (e.g., https://codeberg.org/tkuenneth).

Click Save Changes. It may take a short while until Mastodon detects that it's you, but in the end, it should look like this:

Migrating your first repository

To start a migration, click on the + symbol on the top right, and select New migration.

The next step is to select the Git host you want to migrate from. The migration tool can migrate your repository data, as well as metadata like issues, labels, wiki, releases, and milestones.

The most important piece of information is, of course, the url of the repository you want to migrate. To be able to also migrate metadata, you need to provide an access token.

Once you have specified the owner, the repository name, and the visibility, you can start the migration by clicking on Migrate repository. The following screenshot shows a freshly migrated repo.

Finalising the migration

Once the new repository has been set up, you may want to update the README of the old repo by mentioning its new home and then archive the content (on GitHub, this makes it read-only).

I strongly advise against deleting the old repo. It’s tempting to want a clean break, but there are two big reasons to keep it:

Broken Links: There are inevitably links to your code scattered across the web—in blog posts, old commits, or bookmarks—which you would render useless.
Security (Namespace Hijacking): This is a risk many people overlook. If you delete a repository, that specific URL becomes available again. Someone else could potentially register that same name and host malicious code where your project used to be. By keeping your old repository as a placeholder or a tombstone, you ensure that you still control that space and can point your users safely to Codeberg.

So, the best move is to add a clear migration notice to the top of the README, set the repository to Archived, and let it serve as a signpost.

To learn more about migrations to Codeberg, read the official guide at https://docs.codeberg.org/advanced/migrating-repos/.

Some thoughts on keyboard shortcuts on Android

Thomas Künneth — Fri, 01 Aug 2025 12:30:23 +0000

When you think about which cool new feature you may want to add to your app, you probably won't immediately shout Hell yes, my app desperately needs keyboard shortcut support. I mean, how often do we use physical keyboards with our mobile devices anyway? The days of Android phones having a keyboard built in are long gone, aren't they?

Well, not really. Chromebooks run Android apps. Many Android tablets are sold with physical keyboards. And Android's desktop mode, which hopefully will gain some traction eventually, allows us to connect our smartphone to big screens. This setup only makes sense when you also pair a mouse and keyboard. So, keyboards most certainly are not a thing of the past. They may not have been very common on Android in recent years, but other platforms have always relied on them. And still do. Why? Because physical keyboards are productivity boosters.

That's where keyboard shortcuts come in. They allow us to trigger an action by simultaneously pressing a few keys. Prime examples are the clipboard-related commands Cut (Control-X), Copy (Control-C), and Paste (Control-V). And yes, it's Command on the Mac.

Have you noticed that I said command? Keyboard shortcuts allow us to trigger an action or command fast. That's why they are called shortcuts. The important point here is: there should always be another way of executing that command. Typically, this other way also advertises the corresponding keyboard shortcut. Take a look:

When we open a menu, we see the command and its associated shortcut, which helps us remember it (eventually). Actually using the shortcut helps us remember it even better, but that's another topic.

But Android doesn't have a menu bar

Traditional menu bars work best with a mouse and a mouse pointer. That's why Android does not have one. However, Android most certainly allows apps to show menus. And these can contain keyboard shortcuts, too. We'll tackle this shortly. But first, let me show you how to define and consume keyboard shortcuts on an app level. The source code of my sample app KeyboardShortcutDemo is available on GitHub. It is a Compose Multiplatform project that targets Android, IOS, and the Desktop. In this article, I focus on Android.

Global shortcuts

Working with global keyboard shortcuts consists of two steps:

Defining the shortcuts
Receiving shortcut activations

Both can be implemented on an Activity level. Here's how to define a keyboard shortcut:

private lateinit var listKeyboardShortcutInfo: List<KeyboardShortcutInfo>

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    enableEdgeToEdge()
    listKeyboardShortcutInfo = globalShortcuts.map { shortcut ->
        KeyboardShortcutInfo(
            shortcut.label,
            shortcut.keyAsString.first(),
            shortcut.modifiers()
        )
    }
    …
    setContent {
        val hardKeyboardHidden by
                hardKeyboardHiddenFlow.collectAsStateWithLifecycle()
        val systemInDarkMode = isSystemInDarkTheme()
        var darkMode by rememberSaveable {
                mutableStateOf(systemInDarkMode)
        }
        MaterialTheme(colorScheme = if (darkMode)
                            darkColorScheme()
                        else
                            lightColorScheme()) {
            MainScreen(
                listKeyboardShortcuts = globalShortcuts,
                hardKeyboardHidden = hardKeyboardHidden ==
                    Configuration.HARDKEYBOARDHIDDEN_YES,
                darkMode = darkMode,
                showKeyboardShortcuts = {
                    requestShowKeyboardShortcuts()
                },
                toggleDarkMode = { darkMode = !darkMode }
            )
        }
    }
}

override fun onProvideKeyboardShortcuts(
    data: MutableList<KeyboardShortcutGroup>,
    menu: Menu?,
    deviceId: Int
) {
    super.onProvideKeyboardShortcuts(data, menu, deviceId)
    data.add(KeyboardShortcutGroup(
        getString(R.string.general), listKeyboardShortcutInfo)
    )
}

In onCreate(), we populate a list of KeyboardShortcutInfo instances and, inside onProvideKeyboardShortcuts(), add it to data, which has been passed to us by Android. Please notice the Menu which will usually be null in a Compose-only app.

But what is globalShortcuts? It's defined in GlobalShortcuts.kt.

val globalShortcuts = runBlocking {
    listOf(
        KeyboardShortcut(
            label = getString(Res.string.say_hello),
            key = Key.H,
            keyAsString = "H",
            ctrl = true
        )
    )
}

KeyboardShortcut is a cross-platform generalisation of KeyboardShortcutInfo, which I defined to be able to refer to keyboard shortcuts beyond Android activities. Have you spotted that I pass globalShortcuts to MainScreen()?

Next, let's look at how to receive keyboard shortcut presses.

override fun onKeyShortcut(
    keyCode: Int, event: KeyEvent
): Boolean {
    listKeyboardShortcutInfo.forEachIndexed { index, info ->
        if (info.keycode == keyCode &&
            event.hasModifiers(info.modifiers)) {
            globalShortcuts[index].triggerAction()
            return true
        }
    }
    return super.onKeyShortcut(keyCode, event)
}

The onKeyShortcut() function receives a keyCode and an event. Using both, it is simple to check if a shortcut defined by our app has been pressed. If this is the case, we return true, otherwise super.onKeyShortcut(keyCode, event).

But what does shortcut.triggerAction() do? Here's how it is implemented:

data class KeyboardShortcut(
    val label: String,
    val key: Key,
    val keyAsString: String,
    val ctrl: Boolean = false,
    val meta: Boolean = false,
    val alt: Boolean = false,
    val shift: Boolean = false,
) {
    private val channel = Channel<Unit>(Channel.CONFLATED)
    val flow = channel.receiveAsFlow()

    fun triggerAction() {
        channel.trySend(Unit)
    }

    val shortcutAsText: String
        get() {
            val parts = mutableListOf<String>()
            if (ctrl) {
                parts.add("Ctrl")
            }
            if (meta) {
                parts.add("Meta")
            }
            if (alt) {
                parts.add("Alt")
            }
            if (shift) {
                parts.add("Shift")
            }
            parts.add(keyAsString)
            return parts.joinToString("+")
        }
}

Since KeyboardShortcutInfo is specific to Android, it makes sense to provide an alternative that we can use across platforms. But even on Android we need a mechanism that allows us to trigger and consume keyboard shortcuts in a modern Kotlin way.

That's what KeyboardShortcut is for. label and shortcutAsText will be used by composables. flow allows us to react upon invocations of the keyboard shortcut. Finally, triggerAction(): as its name implies, it triggers an action by trying to send something to a channel. Kindly recall that we invoke this function inside onKeyShortcut(). What does this mean? Once we have determined that a keyboard shortcut has been invoked by pressing the corresponding keys, we make sure to notify everyone interested in the event. We'll, by the way, also call this function from inside our Compose hierarchy. I'll show you shortly.

But before that, let's take a user's perspective. Android and Chrome OS can display a list of available shortcuts. On most devices, this help screen can be opened by pressing Meta-/, which is known as Search-/ on Chromebooks.

Since not all users may be familiar with this system shortcut, consider allowing the user to summon it from within your app. Kindly recall what my sample app does inside setContent {}:

setContent {
    …
    MaterialTheme(colorScheme = …) {
        MainScreen(
            listKeyboardShortcuts = globalShortcuts,
            hardKeyboardHidden = …,
            darkMode = darkMode,
            showKeyboardShortcuts = {
                requestShowKeyboardShortcuts()
            },
            …
        )
    }
}

requestShowKeyboardShortcuts() (this method is defined in android.app.Activity) requests the Keyboard Shortcuts screen to show up. This will trigger onProvideKeyboardShortcuts() to retrieve the shortcuts for the foreground activity. KeyboardShortcutDemo just shows a Show keyboard shortcuts button. Certainly, there are more clever places to incorporate it.

Let's recap. I showed you how to provide keyboard shortcuts on an Activity level. We can even summon a system dialog that lists them. But how do we react to shortcut presses and how do we visualise the shortcut in our user interface? Finally, how do we mention the shortcut to the user so that they can remember it, similar to what I explained regarding classic menu bars?

@Composable
fun MainScreen(
    listKeyboardShortcuts: List<KeyboardShortcut>,
    hardKeyboardHidden: Boolean,
    darkMode: Boolean,
    showKeyboardShortcuts: () -> Unit,
    toggleDarkMode: () -> Unit,
) {
    var snackbarMessage by remember { mutableStateOf("") }
    val helloMessage = stringResource(Res.string.hello)
    LaunchedEffect(listKeyboardShortcuts) {
        listKeyboardShortcuts.forEach { shortcut ->
            launch {
                shortcut.flow.collectLatest {
                    snackbarMessage = helloMessage
                }
            }
        }
    }
    KeyboardShortcutDemo(
        hardwareKeyboardHidden = hardKeyboardHidden,
        snackbarMessage = snackbarMessage,
        shortcuts = listKeyboardShortcuts,
        darkMode = darkMode,
        showKeyboardShortcuts = showKeyboardShortcuts,
        clearSnackbarMessage = { snackbarMessage = "" },
        toggleDarkMode = toggleDarkMode,
    )
}

When a keyboard shortcut is invoked, the sample app shows a snackbar message. We keep the text in snackbarMessage. listKeyboardShortcuts is the list of keyboard shortcuts. KeyboardShortcutDemo() (this composable is invoked from MainScreen()) uses it to populate a menu. hardKeyboardHidden is used to determine if a physical keyboard is ready to use. Kindly just ignore it, I will detail on this in a follow-up article.

So far, I still haven't explained how we react to shortcut presses. The magic happens inside LaunchedEffect(). For each keyboard shortcut, we invoke shortcut.flow.collectLatest {}. In my example, we always set the snackbar message. Real-world apps would certainly provide different implementations, depending on the shortcut.

Menus and keyboard shortcuts in Jetpack Compose

When looking at the KeyboardShortcutDemo() composable, kindly recall the screenshot of the app to understand its structure:

an app bar at the top, including the app name and a menu
a text field (not further discussed in this article)
a switch with an accompanying label (not further discussed in this article)
a button to open the keyboard shortcuts dialog
(not visible in the screenshot) a text when no physical keyboard is ready to use

fun KeyboardShortcutDemo(
    hardwareKeyboardHidden: Boolean,
    shortcuts: List<KeyboardShortcut>,
    snackbarMessage: String,
    darkMode: Boolean,
    showKeyboardShortcuts: () -> Unit,
    clearSnackbarMessage: () -> Unit,
    toggleDarkMode: () -> Unit,
) {
    val snackBarHostState = remember { SnackbarHostState() }
    var showMenu by remember { mutableStateOf(false) }
    …
    Scaffold(
        modifier = Modifier.fillMaxSize()
        …,
        topBar = {
            TopAppBar(
                title = {
                    Text(stringResource(Res.string.app_name)) 
                },
                actions = {
                    IconButton(onClick = { showMenu = !showMenu }) {
                        Icon(
                            imageVector = Icons.Filled.MoreVert,
                            contentDescription = stringResource(
                                Res.string.more_options)
                        )
                    }
                    DropdownMenu(
                        expanded = showMenu,
                        onDismissRequest = { showMenu = false }
                    ) {
                        shortcuts.forEach { shortcut ->
                            DropdownMenuItemWithShortcut(
                                text = shortcut.label,
                                shortcut = shortcut.shortcutAsText,
                                onClick = {
                                    showMenu = false
                                    shortcut.triggerAction()
                                }
                            )
                        }
                    }
                }
            )
        },
        snackbarHost = { SnackbarHost(snackBarHostState) }
    ) { innerPadding ->
        Box(
            modifier = Modifier
                …
                .padding(innerPadding)
                .fillMaxSize(),
            contentAlignment = Alignment.Center
        ) {
            …
            Column(
                horizontalAlignment = Alignment.CenterHorizontally,
                verticalArrangement = Arrangement.spacedBy(16.dp)
            ) {
                …
                Button(
                    onClick = showKeyboardShortcuts,
                ) {
                    TextWithUnderlinedChar(stringResource(
                        Res.string.show_keyboard_shortcuts))
                }
            }
            if (hardwareKeyboardHidden) {
                Text(
                    text = stringResource(
                        Res.string.hardware_keyboard_hidden),
                    modifier = Modifier.align(Alignment.BottomCenter)
                                       .safeContentPadding(),
                    style = MaterialTheme.typography.headlineSmall,
                    color = MaterialTheme.colorScheme.error
                )
            }
        }
        LaunchedEffect(snackbarMessage) {
            if (snackbarMessage.isNotBlank()) {
                snackBarHostState.showSnackbar(snackbarMessage)
                clearSnackbarMessage()
            }
        }
    }
}

The menu will contain as many items as shortcuts has elements. When an element is selected, a snack bar will appear. That's because onClick() of each DropdownMenuItemWithShortcut() invokes shortcut.triggerAction(). The onClick() of the button just invokes the showKeyboardShortcuts lambda.

That's been quite a bit to digest, right? Fortunately, there is only one piece of the puzzle missing. What is DropdownMenuItemWithShortcut()?

Unlike the traditional Activity-level options menu, DropDownMenuItem() (which comes with Jetpack Compose) does not support shortcuts out of the box. This means we need to somehow add this to the Text() composable. The most basic approach is to just add the shortcut at the end of the String. While this works, this does not look particularly pleasing. Besides, that's not how we build UIs with Jetpack Compose.

Here's a composable that provides a DropDownMenuItem() with a shortcut at the end of the text:

@Composable
fun DropdownMenuItemWithShortcut(
    text: String,
    shortcut: String?,
    onClick: () -> Unit,
    modifier: Modifier = Modifier
) {
    DropdownMenuItem(
        text = { ShortcutText(text = text, shortcut = shortcut) },
        onClick = onClick,
        modifier = modifier
    )
}

@Composable
fun ShortcutText(
    text: String,
    shortcut: String?,
) {
    Row(
        modifier = Modifier.fillMaxWidth(),
        horizontalArrangement = Arrangement.SpaceBetween
    ) {
        Text(
            text = text,
            modifier = Modifier.alignByBaseline()
        )
        shortcut?.let { shortcut ->
            Text(
                text = shortcut,
                style = MaterialTheme.typography.bodyMedium,
                color = MaterialTheme.colorScheme.onSurface
                            .copy(alpha = 0.6f),
                modifier = Modifier
                    .alignByBaseline()
                    .padding(start = 16.dp)
            )
        }
    }
}

Have you spotted the alignByBaseline() modifier? While most examples using Row() just vertically center the children, this is a nightmare from a UX perspective. The texts have to be baseline-aligned to be readable nicely.

That looks pretty nice, doesn't it?

You may be wondering where the shortcut text is created. In the KeyboardShortcutDemo() composable, it's passed like this:

shortcuts.forEach { shortcut ->
    DropdownMenuItemWithShortcut(
        text = shortcut.label,
        shortcut = shortcut.shortcutAsText,
        onClick = {
            showMenu = false
            shortcut.triggerAction()
        }
    )
}

So, what is shortcut.shortcutAsText? Kindly recall my custom KeyboardShortcut class:

data class KeyboardShortcut(
    val label: String,
    val key: Key,
    val keyAsString: String,
    val ctrl: Boolean = false,
    val meta: Boolean = false,
    val alt: Boolean = false,
    val shift: Boolean = false,
) {
    …

    val shortcutAsText: String
        get() {
            val parts = mutableListOf<String>()
            if (ctrl) {
                parts.add("Ctrl")
            }
            if (meta) {
                parts.add("Meta")
            }
            if (alt) {
                parts.add("Alt")
            }
            if (shift) {
                parts.add("Shift")
            }
            parts.add(keyAsString)
            return parts.joinToString("+")
        }
}

I was surprised to learn that there seems to be no public-facing API in Android that provides a locale-aware String representation of KeyboardShortcutInfo. However, a function that achieves this must be around somewhere, since the often-mentioned keyboard shortcuts dialog needs something similar, too. Since I couldn't find one, I decided to write my own. Checking the modifiers and the key code isn't too difficult, but there are some nuances that need to be taken into account. For example, on Chromebooks, Meta should be Search or some corresponding symbol. I omitted this for brevity. In a real-world app, you would want to take the string from the resources and handle device-specific variations.

Conclusion

Adding keyboard shortcut support to your app may not sound particularly fancy at first sight, but in my opinion brings a lot of added value. Do your apps already support them? How did you handle the visual representation of the shortcuts? Please share your thoughts in the comments.

Quick tip: (sort of) using Quick Share on macOS

Thomas Künneth — Thu, 19 Jun 2025 10:32:45 +0000

At the time of writing this article, there (still) is no official Quick Share implementation for macOS. While there is an open source app that partially implements the underlying protocol, and while there certainly are quite a few excellent alternate file sharing solutions, you still may want (or have) to rely on Google's version.

The Windows version obviously won't work on your Mac, but it may very well work inside a virtualized Windows guest.

So what is happening there? I am using Parallels Desktop, which allows you to run an authorized (that is, licensed and activated) version of Windows 11 for ARM. Having a Windows environment available on your Mac may come in handy for several reasons. My personal favorites are:

testing Compose Desktop apps
occasionally play some PC-only games
use apps that are not available natively on macOS, which, at the time of writing, was the case for Quick Share

Testing Compose Desktop apps has been a game changer for me, and I will be writing about this, too. For now, let's focus on Quick Share. And virtualization. But first, a short disclaimer. I am not advocating a specific product. There are several virtualization packages on macOS. And they all have their strengths. It just happened that I once tried Parallels and liked it, so I stayed. But what I am going to describe, will likely be working on other products, too.

Before Apple switched to Apple Silicon, Macs were powered by Intel chips. Well, and before that, still others. Anyway, when a virtualization software virtualizes an environment with the same processor architecture, there, inevitably, is less emulation needed than when it also needs to simulate the processor. Those packages still have to do crazy, mind-blowing stuff. But a lot of code can run natively, given that the underlying processor supports virtualization. This is the case for modern Intel and AMD chips. However, current Apple Silicon chips have only limited support for running virtualized Intel/AMD operating systems. While Apple does provide a virtualization layer called Rosetta 2, running an x86/x64 version of Windows is - at the time of writing - not easily possible. That's why Parallels relies on Windows for ARM. This version is usually run on ARM-PCs. Now, you may be thinking: What about software compatibility? Windows for ARM has its own emulation layer, which allows users to run many x86/x64 programs.

Let's turn to Quick Share. The official Google Quick Share application for Windows is compatible with 64-bit versions of Windows 10 and up. Importantly, it also supports ARM-based PCs running Windows 11 and up. Since Quick Share leverages both Bluetooth and Wi-Fi for file transfer, you'll need to ensure both are enabled and working on your virtualized Windows PC and the Android device.

Using Parallels, Bluetooth is activated from the menu bar (Devices / USB & Bluetooth / Configure).

Next, check if Bluetooth is enabled and if your virtual machine is discoverable.

Wi-Fi required a little more thought to make Quick Share work. Specifically, the Network settings should look like this:

Source needs to be set to Wi-Fi rather than Shared Network, which is the default and recommended setting.

While that's basically it, let me show you a few screenshots from the Windows app:

In its settings, you can specify where received files are saved. Since you can share macOS folders with the virtual Windows, it may sound like a good idea to use such folders. Unfortunately, this did not work for me. While the file was briefly visible, it vanished shortly after. Using a folder inside the Windows guest fortunately works like a charm.

In the main section, you can easily change who can send you files. If the main window is closed, this setting is also available from the system tray:

Wrap-up

I have an instance of Windows basically running all the time, since I do a lot of Compose Multiplatform / Compose Desktop coding. No, it's not because of games 🤣. Anyway, for my setup, receiving Quick Share files there and moving them to native Mac folders manually is a decent enough workflow to keep it. Granted, a native macOS version is still overdue. At least, Google could fix the "not being able to save files in networked folders" issue.

What are your thoughts on this? Please share them in the comments.

Did you know … ? Android 16 edition

Thomas Künneth — Sun, 08 Jun 2025 19:30:33 +0000

The rollout of Android 16 is likely going to happen today (while today certainly depends on your time zone 😅). In anticipation of the new release, I made a series of social media posts highlighting changes and additions that may not make it to the front page. Here's a quick collection of these posts.

Testing Compose Desktop apps: preparations

Thomas Künneth — Mon, 12 May 2025 15:35:49 +0000

Welcome to the fifth article in a series of tips and tricks about Compose Multiplatform. The content is based on a sample app called CMP Unit Converter. It runs on Android, iOS, and the Desktop. As its name suggests, you can convert between various units and scales. While this may provide some value, the main goal of the app and this series is to show how to use Compose Multiplatform and a couple of other multiplatform libraries while focusing on platform integration. This time, we look at how to test Compose Multiplatform apps on one particular target: the desktop.

What is the Desktop anyway?

Kotlin Multiplatform is based on the idea of compiling for different targets. Targets are defined by an operating system or platform and, for native targets, a processor architecture. In the build.gradle.kts file inside the composeApp module, you can see a reference to the Desktop target inside the kotlin {} block: the invocation of jvm("desktop"). So, when referring to the Desktop, we mean the Java platform and its components.

Java's astonishing success lies in the ability to write code that can run on several operating systems; among others, macOS, Windows, Linux, AIX and z/OS. The key to this ability is the Java Virtual Machine, a runtime environment that executes programs represented in a machine language called bytecode. The JVM integrates the program into the host operating system and provides means for communicating with the system, and for using its resources.

The JVM allows us to run bytecode programs on any operating system or platform the JVM is available on. Compose Multiplatform narrows this down a little. Version 1.8.0 of the JetBrains framework supports macOS, Windows, Windows on ARM64, Linux, and Linux on ARM64. That's three operating systems. Each of them has - or had - support for Intel/AMD and ARM architectures.

Let that trickle in for a while.

Does that mean I should test my Compose Desktop app on each of these?

Glad you are asking. Well, in a way it's your choice, depending on how many users your app is targeting. At the time of writing, Apple still officially supports some Intel-based Macs with software updates. Therefore, if your app targets macOS, you may want to provide installation packages for both Intel and Apple Silicon Macs. And if you do that, you probably also want to test them.

The same is true for Windows. While Windows has been an Intel/AMD stronghold for decades, we have seen a significant increase in ARM-powered PCs in recent years. Many Copilot+ PCs run Windows for ARM, so, if your app targets Windows, you likely want your app to also run on them.

Finally, Linux. While I don't have statistics regarding the number of Linux for ARM installations, it feels safe to say that there aren't many. Therefore, if you want to provide your app for Linux, you might be tempted to focus on Intel/AMD. On the other hand, any additional user can make a difference, so you need to balance both costs and benefits of providing a Linux on ARM installation archive.

Before we look at what happens along the way of creating an installation archive, let's focus a little more on operating systems and processor architectures. Taking into account that the JVM is the runtime environment for your app, why would you need to worry about processor architectures? Isn't bytecode a machine language in its own right? And isn't the JVM isolating your app from the rest of the system? While the JVM executes the bytecode (or compiles it ahead of time to native code so that the physical processor can run it), it does not isolate your app from the rest of the system, but rather integrates it. For example, you can easily do native calls using JNI - which certainly depends on the processor architecture. Even if your app does no native calls directly, referenced libraries might. Jetpack Compose relies on Skia, after all.

Consequently, you should test your app on at least the primary processor architecture of an operating system or platform. If you provide versions of your app for additional processor architectures, you certainly need to test these, too. I'll return to this later.

How to create an installation archive

Kotlin and Compose Multiplatform projects heavily rely on Gradle. As you can see in the following screenshot, you can choose from quite a few tasks to create native installation archives.

Some of them can be used only on the platform you want to create an installation archive for, for example packageDmg on macOS, and packageMsi on Windows. Here's why: under the hood, the jpackage tool is executed. It invokes other executables from the Java Development Kit, like jlink, but also some native installer tools like the WiX Toolset on Windows (which is not supported on macOS and Linux).

jlink creates a minimal, application-specific Java runtime environment by including only the necessary modules from a full JDK. But which JDK is used? While there is a corresponding command line parameter, in a Kotlin Multiplatform project you can specify the JDK like this:

compose.desktop {
    application {
        mainClass = "your.main.Class"
        javaHome = …
    }
}

If you don't set the javaHome property explicitly, the jpackage tool which is invoked by, for example, the createMsi task, will typically use the JDK that Gradle itself is using.

Let's recap: to have your app using a particular Java Runtime, a straightforward way to achieve this is to set the javaHome property in the build.gradle.kts file of your composeApp module.

At this point, you may be asking yourself why this is important. Kindly recall that an operating system may support more than one processor architecture. You would then have two different JDKs, each of which you could easily select using the technique described above. Here's an example: Windows on ARM has a built-in emulation layer that allows the seamless execution of Intel/AMD-based apps although the primary processor architecture is ARM64. Consequently, you can install the JDK for ARM64 and Intel/AMD at the same time. To build your app, you need to specify which one to use.

macOS running on Apple Silicon and Linux on ARM also allow the execution of Intel/AMD-based apps, but through different mechanisms and with varying degrees of compatibility and performance. Apple uses a translation layer called Rosetta 2. On Linux you would likely be using QEMU User-Mode Emulation. ...or something else that I will be mentioning a little later...

How straightforward - or complicated - it is to install two JDKs with the same version number but a different processor architecture depends on the underlying operating system. On macOS, Java Development Kits are usually put inside /Library/Java/JavaVirtualMachines. Each version resides in a subdirectory, for example amazon-corretto-17.jdk. Since the name does not contain architecture-related information, you need to put the second one somewhere else, which implies that without further modifications, macOS won't know it's there. If that second version is only referenced in the build.gradle.kts file, that certainly does not matter.

Wrap-up

This has been quite a ride, hasn't it? Let's recap. Your developer machine is running an operating system that may or may not be able to run apps targeting a different processor architecture:

macOS on Intel hardware can only run apps made for macOS on Intel
macOS on Apple Silicon can run ARM64 and Intel apps (through Rosetta 2)
Windows on Intel/AMD can only run apps made for Intel/AMD
Windows on ARM can run both Intel/AMD (through emulation) and ARM64 apps natively
Linux on Intel/AMD can only run apps made for Intel/AMD
Linux on ARM can natively run ARM64 apps. Running Intel/AMD apps is possible through emulation, but this requires specific setup and may have performance implications

Regardless of the processor architecture, to test software made for a particular operating system, you need a box that runs this OS. That box can either be a physical or virtual one. Virtualization on Windows for Intel/AMD has come a long way. There are quite a few well-known products that allow you to virtualize both Windows and Linux. On Linux, the most common hypervisor is KVM (Kernel-based Virtual Machine). It allows you to easily and seamlessly virtualize both Windows and Linux. What about macOS - can it be virtualized, too? While technically possible, macOS must only be used on an Apple-branded computer.

On several occasions, I mentioned that, using Parallels Desktop, you can easily test your Compose Desktop app on macOS, Linux and Windows. Now that I have laid the theoretical groundwork, we'll get practical in the next installment of this series.

Android Manifest file checklist

Thomas Künneth — Sun, 06 Apr 2025 10:02:28 +0000

Welcome to the fourth article in a series of tips and tricks about Compose Multiplatform. The content is based on a sample app called CMP Unit Converter. It runs on Android, iOS, and the Desktop. As its name suggests, you can convert between various units and scales. While this may provide some value, the main goal of the app and this series is to show how to use Compose Multiplatform and a couple of other multiplatform libraries while focusing on platform integration. This time, we look at the Android manifest file.

The Kotlin Multiplatform wizard for sure is a great way to start your projects. The manifest file for a project I created on 2025-04-05 looks like this:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

  <application
    android:allowBackup="true"
    android:icon="@mipmap/ic_launcher"
    android:label="@string/app_name"
    android:roundIcon="@mipmap/ic_launcher_round"
    android:supportsRtl="true"
    android:theme=
      "@android:style/Theme.Material.Light.NoActionBar"
  >
    <activity
    android:exported="true"
    android:configChanges="orientation|screenSize|
                           screenLayout|keyboardHidden|
                           mnc|colorMode|density|fontScale|
                           fontWeightAdjustment|keyboard|
                           layoutDirection|locale|
                           mcc|navigation|
                           smallestScreenSize|touchscreen|uiMode"
    android:name=".MainActivity">
    <intent-filter>
      <action android:name="android.intent.action.MAIN" />
      <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
    </activity>
  </application>

</manifest>

The application

The purpose of a project wizard is to provide only a basic setup. Therefore, the manifest contains only what is absolutely necessary. Consequently, there are no entries for permissions, further activities, services, broadcast receivers, and content providers. All these are, by the way, called App components in the App manifest overview.

☑ Add required permissions and app components

The application element contains

the declaration of the application. This element contains subelements that declare each of the application's components and has attributes that can affect all the components.

One of its attributes, android:enableOnBackInvokedCallback (which can also be specified for an activity) is as of 2025-04-05 not set by the Kotlin Multiplatform wizard. The flag lets you opt out of predictive system animations at the activity level, which is something you should not do. Therefore:

☑ Set android:enableOnBackInvokedCallback to true

An attribute you should consider adding is android:appCategory. It declares the category of your app.

Categories are used to cluster multiple apps together into meaningful groups, such as when summarizing battery, network, or disk usage. Only define this value for apps that fit well into one of the specific categories.

☑ Consider adding android:appCategory

Did you know there is the android:hasFragileUserData attribute? It controls whether

to show the user a prompt to keep the app's data when the user uninstalls the app. The default value is false.

Now, I am not advocating to set it. But I feel it should be on a checklist.

☑ Carefully consider adding android:hasFragileUserData (you probably should not add it, after all)

android:theme is a

reference to a style resource defining a default theme for all activities in the application. Individual activities can override the default by setting their own theme attributes.

As of 2025-04-05, the Kotlin Multiplatform wizard sets it to @android:style/Theme.Material.Light.NoActionBar. If you run your Compose Multiplatform app, everything appears to work fine, including toggling between light and dark mode. However, there's a subtle issue. To understand which, let's remind ourselves what android:theme="@android:style/Theme.Material.Light.NoActionBar" does.

It sets the initial theme for your application (or activity) to light mode.
It makes sure there is no action bar. Having no action bar is likely what you want because a common Compose pattern is to have a Scaffold() with a top app bar.

The theme setting affects the activity window and how Android draws the initial UI before your Compose code or Android Views are inflated. A part of this initial user interface is the splash screen. Putting android:theme="@android:style/Theme.Material.Light.NoActionBar" in your manifest means the splash screen background will always appear light, regardless if the system is in light or dark mode. Since modern Android apps certainly should support light and dark mode, I encourage you to change the theme.

While there is no Theme.Material.DayNight.NoActionBar, you could use Theme.DeviceDefault.DayNight but would also need to remove the action bar (for example in a custom theme with Theme.DeviceDefault.DayNight as its parent). This feels unnecessarily complicated. The easiest way is to include Jetpack Appcompat and use android:theme="@style/Theme.AppCompat.DayNight.NoActionBar". While this works exactly as expected, please keep in mind that any library contributes to the overall app size.

Here's one final aspect: Do you need to use activities solely based on Views? Such activities may be your own or provided by a third party library like scanner or proprietary sign-in components. They deserve a proper theme treatment. That is, not being tied to light mode.

☑ Set a theme that supports light and dark mode in android:theme

Activities

The activity element declares

an activity (an Activity subclass) that implements part of the application's visual user interface. All activities must be represented by <activity> elements in the manifest file. Any that aren't declared there aren't seen by the system and never run.

One of its attributes, android:windowSoftInputMode, is as of 2025-04-05 not set by the Kotlin Multiplatform wizard. The attribute controls how

the main window of the activity interacts with the window containing the on-screen soft keyboard.

There are two things to consider:

Should the soft keyboard be visible when the activity becomes the focus of user attention?
Should the activity window become smaller to make room for the soft keyboard?

A couple of values control these aspects. They can be combined: stateUnspecified, stateUnchanged, stateHidden, stateAlwaysHidden, stateVisible, stateAlwaysVisible, adjustUnspecified, adjustResize, adjustPan, adjustNothing

stateUnspecified is the default setting for the behavior of the soft keyboard.

Whether the soft keyboard is hidden or visible isn't specified. The system chooses an appropriate state or relies on the setting in the theme.

adjustUnspecified is the default setting for the behavior of the main window.

Whether the activity's main window resizes to make room for the soft keyboard or the contents of the window pan to make the current focus visible on-screen is unspecified. The system automatically selects one of these modes depending on whether the content of the window has any layout views that can scroll their contents. If there is such a view, the window resizes, on the assumption that scrolling can make all of the window's contents visible within a smaller area.

Both defaults sound like a good choice for many apps. Therefore, it seems safe to just omit android:windowSoftInputMode. However, these mechanics had been designed for a View-based world. So, what does The system automatically selects one of these modes depending on whether the content of the window has any layout views that can scroll their contents mean in a Jetpack Compose app? Please recall that setContent {} just creates a ComposeView, which hosts the Compose hierarchy. In the document Display content edge-to-edge in your app and handle window insets in Compose, Google suggests to add android:windowSoftInputMode="adjustResize" to the manifest because this

setting allows your app to receive the size of the software IME as insets, which you can use to pad and lay out content appropriately when the IME appears and disappears in your app

In CMP Unit Converter, I have added this manifest attribute and made sure the content is scrollable. This results in a very nice user experience even on a smartphone in landscape mode, where space is notoriously scarce.

☑ Add android:windowSoftInputMode

The last item on my checklist is likely going to be controversial. android:configChanges lists configuration changes an activity wants to handle itself.

When a configuration change occurs at runtime, the activity shuts down and restarts by default, but declaring a configuration with this attribute prevents the activity from restarting. Instead, the activity remains running and its onConfigurationChanged() method is called.

As of 2025-04-05, the documentation lists 18 values; the Kotlin Multiplatform wizard requests to handle 17 through onConfigurationChanged(). The only one not being requested is grammaticalGender (which was introduced with API level 34). Here's a question: Why handling locale but not grammaticalGender? This omission may likely have been just a glitch, but it begs an important additional question: Why this long list?

The documentation clearly says:

Note: Use this attribute only in special cases to improve application performance and responsiveness. For more information, see Handle configuration changes.

The Handle configuration changes document is a must-read. Don't just take a glimpse, don't just browse through it. Read it. Read it again. Read it once more. Then, and only then, ask yourself which configuration changes you really want to opt out from. Below are some quotes from this document I find particularly important:

Note: Activity recreation due to configuration changes is only one of the cases in which the system might destroy an Activity and recreate it later. For more information, read about the Activity lifecycle.

This means, your app needs proper lifecycle management anyway. We have established patterns for this.

Warning: Even when you disable activity recreation for a given configuration change, the change itself continues to occur. Disabling Activity recreation transfers the responsibility of handling that configuration change to the Activity. If you disable Activity recreation, your app must appropriately handle the change when it does occur.

Section React to configuration changes in Jetpack Compose starts with

Jetpack Compose lets your app more easily react to configuration changes. However, if you disable Activity recreation for all configuration changes where it is possible to do so, your app still must correctly handle configuration changes.

So, how should android:configChanges look like? First, please make sure to also have read and understood paragraphs Avoid opting out as a quick fix and Don't avoid configuration changes. Now, there certainly is no definitive answer. But I firmly believe that a list as long as the one the Kotlin Multiplatform wizard creates, requires a lot of careful consideration. If in doubt, opt out from less, and let the system handle configuration changes by recreating the activity.

The Now on Android app source code is often cited as a great resource for learning how to do things. So, to conclude this, let's peek into its manifest file and seek inspiration.

That's not many, right?

☑ Carefully consider which values to set in android:configChanges

Conclusion

I would like to point out that I am neither saying nor implying that the long list the Kotlin Multiplatform wizard uses is wrong. What I definitively advocate is to carefully consider how the manifest file of your Compose Multiplatform app should look like. It's your obligation to make sure its content is correct. No wizard can provide more than a humble suggestion.

I do hope you find this checklist useful. Kindly share your thoughts in the comments.

Open the default browser across platforms

Thomas Künneth — Sat, 29 Mar 2025 11:18:43 +0000

Welcome to the third article in a series of tips and tricks about Compose Multiplatform. The content is based on a sample app called CMP Unit Converter. It runs on Android, iOS, and the Desktop. As its name suggests, you can convert between various units. While this may provide some value, the main goal is to show how to use Compose Multiplatform and a couple of other multiplatform libraries, focusing on platform integration. This time, we will be looking at opening the default browser across platforms.

So, why would you want to do that? Well, one obvious reason is that it's part of the app's purpose. For example, CMP Unit Converter shows some supporting information at the right hand side of the converter area. Which unit or scale was last selected? What's the essence of that unit or scale? To learn more, the user can get all insights about the unit or scale by clicking the Read more on Wikipedia button.

At this point, the app has two options:

Show the web page inside the app
Let the default browser do its job

Certainly, embedding the browser into the app offers a very cohesive experience. However, what happens if the user has more browsers installed? How do we handle navigation inside the browser? Are we sure the user wants to read the web page inside the app? A lot of apps try to solve this by adding a Show web pages inside the app toggle. But is that really necessary? Why not keeping things simple and just letting the app do its job that was made for showing web content?

Fire and forget

CMP Unit Converter does not interact with the web page. It relies on a simple fire and forget scenario. Let's define a simple expect function in commonMain:

expect fun openInBrowser(url: String, 
                         completionHandler: (Boolean) -> Unit = {})

We are passing the url as a String because it is easily usable on all platforms. If needed, more specific objects can be created from it by platform-specific code. completionHandler is something I borrowed from iOS. So, let's look at the corresponding implementation.

actual fun openInBrowser(url: String,
                         completionHandler: (Boolean) -> Unit) {
  NSURL.URLWithString(url)?.let {
    UIApplication.sharedApplication.openURL(
      url = it, 
      options = emptyMap<Any?, Any>(),
      completionHandler = completionHandler
    )
  }
}

openURL() is an asynchronous operation; the function returns immediately. Once the asynchronous task is finished (either successfully or not), the completion handler will be invoked. options allows you to configure how the url will be opened. For a list of possible keys to include in this map, see UIApplication.OpenExternalURLOptionsKey

Having a completion handler that tells us whether opening the web page was successful certainly is more than fire and forget, but on the other hand we want to notify our users if something went wrong. So let's see how we achieve this on Android.

actual fun openInBrowser(url: String,
                         completionHandler: (Boolean) -> Unit) {
  val result = try {
    context.startActivity(
      Intent(
        Intent.ACTION_VIEW, Uri.parse(url)
      ).apply { addFlags(Intent.FLAG_ACTIVITY_NEW_TASK) })
    true
  } catch (_: ActivityNotFoundException) {
    false
  }
  completionHandler(result)
}

Since we don't know which app will be reacting upon Intent.ACTION_VIEW, we need to use startActivity() which really means fire and forget. The only thing we can and should do is catch ActivityNotFoundException.

Finally, let's look at the Desktop.

actual fun openInBrowser(url: String,
                         completionHandler: (Boolean) -> Unit) =
  browse(url = url, completionHandler = completionHandler)

I maintain a file called DesktopHelpers.kt in desktopMain which heavily uses java.awt.Desktop. Sadly, this class has never been particularly well-known. It was first introduced all the way back in Java Platform, Standard Edition 6, and received major additions in Java 9.

fun browse(url: String, completionHandler: (Boolean) -> Unit = {}) {
  with(Desktop.getDesktop()) {
    val result = if (isSupported(Desktop.Action.BROWSE)) {
      try {
        browse(URI.create(url))
        true
      } catch (e: IOException) {
        false
      } catch (e: SecurityException) {
        false
      }
    } else false
    completionHandler(result)
  }
}

Using Desktop features always consists of these steps:

Get a Desktop instance by using Desktop.getDesktop()
Check if the required function is available using isSupported()
Invoke the function

So, the code snippet above invokes completionHandler() with a true value if Desktop.Action.BROWSE is a supported action and browse(URI.create(url)) does not throw an exception.

Wrap-up

Besides Desktop.Action.BROWSE there are a few other actions available. For example, you can invoke an email client and set Preferences, as well as, About handlers. I might return to this in future parts of this series.

Forem: Thomas Künneth

Agentic interaction using AppFunctions

AppFunctions

Implementing an AppFunction

Version catalog (gradle/libs.versions.toml)

App module (app/build.gradle.kts)

Testing AppFunctions

Wrap-up

References

From Vibe-Coding to Reality: Building MarvinSync

What is MarvinSync? (And why Vibe-Code it?)

Trusting the folder, not the tag

Making Android Feel Native

What the code fences don’t show (but the session did)

The Friction of Vibe-Coding

What’s Next?

Refuelling your Jetpack

From Jetpack to a unified architecture

How it fits together

In practice: CMP Unit Converter

Takeaways and resources

Setting up local Codeberg runners

Docker / OrbStack

act_runner

F-Droid on ChromeOS: trying to get behind the road blocks

Conclusion

First steps towards Codeberg

What is Codeberg?

Signing up

Migrating your first repository

Finalising the migration

Some thoughts on keyboard shortcuts on Android

Global shortcuts

Menus and keyboard shortcuts in Jetpack Compose

Conclusion

Quick tip: (sort of) using Quick Share on macOS

Wrap-up

Did you know … ? Android 16 edition

7 new services

Ignoring rotation and resizability change restrictions

Embedding the Android Photo Picker

A hint at virtual threads

Supplemental descriptions for views

New key codes

Elegant font APIs deprecated and disabled

Good vibrations

NoWritingToolsSpan

Testing Compose Desktop apps: preparations

What is the Desktop anyway?

How to create an installation archive

Wrap-up

Android Manifest file checklist

The application

Activities

Conclusion

Open the default browser across platforms

Fire and forget

Wrap-up

Version catalog (`gradle/libs.versions.toml`)

App module (`app/build.gradle.kts`)