I recently learned about friendPaths as part of the Kotlin Gradle Plugin while browsing an Android Slack group. From the documentation on friendPaths: "Paths to the output directories of the friend modules whose internal declarations should be visible."

This struck some joy in me when I thought about modules being 'friends' and allowing one friend to have visibility into internal members. Additionally, its use case within my project became immediately obvious. First, some backstory on the setup of the project.

We use a modularization strategy roughly outlined in this talk titled "Android At Scale @Square" from Ralf Wondratschek.

For the purpose of this post, the modularization strategy can be summarized by every logical module having 3 actual modules.

1. A public facing API module

2. An internal implementation module

3. A wiring / glue module to bind the API with the implementation

The wiring module depends on the public module via the api Gradle configuration and depends on the impl module via the implementation Gradle configuration. The app module then depends on the wiring module.

This simplified strategy is perfectly reasonable but has one caveat. In order for the wiring module to bind the public API and the internal impl modules, the members of impl actually can't be internal because the wiring module needs visibility into them.

Befriending wiring and impl

In this setup, wiring and impl have a special relationship. One could describe this relationship as friendly even! The ideal state would allow impl to have its members be internal while still allowing wiring to peek at them to bind them in our DI graph.

Show Me The Code

The context of the below code occurs in the assorted configuration of our Gradle Plugin.

To wire up this friendly relationship, I first created a new Gradle configuration that I've called friendlyImplementation (The idea for this was shamelessly borrowed from Aurimas Liutikas)

val friendlyImplementation =  
    configurations.create("friendlyImplementation") {  
        isCanBeResolved = true  
        isCanBeConsumed = false  
        isTransitive = false  
    }  

// Make implementation extend from friendlyImplementation so dependencies are available  
configurations.findByName("implementation")?.extendsFrom(friendlyImplementation)

Now that we have this new configuration, we can have our wiring module depend on our impl module via this new friendlyImplementation configuration

This will work to add a module as a dependency but won't actually do anything for us yet. If we try to access an internal property within impl, we will see both an error in Android Studio and we will see an error from the Kotlin compiler

Configuring friendlyImplementation

private fun Project.configureFriendModules() {  
    val friendlyImplementation =  
        configurations.create("friendlyImplementation") {  
            isCanBeResolved = true  
            isCanBeConsumed = false  
            isTransitive = false  
        }  

    // Make implementation extend from friendlyImplementation so dependencies are available  
    configurations.findByName("implementation")?.extendsFrom(friendlyImplementation)  

    friendlyImplementation.dependencies.configureEach {  
        // assume any friendlyImplementation dependency is within same parent project  
        val friendlyPath = this@configureFriendModules.path.substringBeforeLast(":") + ":$name"  

        val friendlyProjectPath =  
            rootProject  
                .findProject(friendlyPath)  
                ?.layout  
                ?.buildDirectory  
                ?.get()  
                ?.asFile  
                ?.absolutePath  

        if (friendlyProjectPath != null) {  
            this@configureFriendModules.tasks  
                .withType(KotlinCompile::class.java)  
                .configureEach { friendPaths.from(files(friendlyProjectPath)) }  
        } else {  
            logger.error(  
                "Attempting to configure friendly project failed for project ${this@configureFriendModules.name} with dependency $name"  
            )  
        }  
    }  
}

When going to configure our friendlyImplementation configuration, the goal is to look at all of the dependencies included under friendlyImplementation, get that dependency's build directory, and add it as a friend via friendPaths

Battling Android Studio

After adding this to our Gradle plugin, this setup allows us to get successful compilations! But presents one annoying developer experience issue: Android Studio still presents the error in the screenshot above. This experience is not ideal for developers on the team who usually have high trust when Android Studio tells them something is wrong (issue filed)

Luckily for me, we have the infrastructure in place already for a custom Android Studio plugin that is distributed internally and installed on our developers machines. Having a distributed internal Android Studio plugin is a great tool in an arsenal to help with the developer experience of a team.

IntelliJ exposes the ability for us to interact with this error via HighlightInfoFilter. The gist of the API of this filter is given some information about HighlightInfo should that highlight display. In our implementation, we will look at the HighlightInfos description, do some fuzzy matching against our INVISIBLE_REFERENCE from earlier, and hide that error if its in a module that has friendlyImplementation dependencies (I'm waving my hand at the exactness of this algorithm. The eagle eyed amongst anyone reading this can point out a case in which this algorithm fails, because for example we don't match the member to a given friendlyImplementation dependency.)

public class FriendPathHighlightInfoFilter : HighlightInfoFilter {  

    override fun accept(highlightInfo: HighlightInfo, psiFile: PsiFile?): Boolean {  
        // Only process error-level highlights  
        if (highlightInfo.severity != HighlightSeverity.ERROR) {  
            return true  
        }  

        // Check if this is an internal visibility error  
        val description = highlightInfo.description ?: return true  
        val isInternalError = description.contains("[INVISIBLE_REFERENCE]", ignoreCase = true)  

        if (!isInternalError) {  
            return true  
        }  

        // Check if we're in a glue module (which has friend path access)  
        if (psiFile == null) {  
            return true  
        }  

        val module = ModuleUtilCore.findModuleForFile(psiFile.virtualFile, psiFile.project)  
            ?: return true  

        // Check if this module has friendlyImplementation dependencies  
        val detector = FriendModuleDetector.getInstance(psiFile.project)  
        if (detector.hasFriendlyImplementation(module)) {  
            // Return false to suppress (hide) this error  
            return false  
        }  

        // Allow the error to be shown in other modules  
        return true  
    }  
}

We then create a service that has a cache of module's build files so we can check to see if a module has dependencies via friendlyImplementation

@Service(Service.Level.PROJECT)  
public class FriendModuleDetector {  

    private val cache = ConcurrentHashMap<String, Boolean>()  

    public companion object {  
        public fun getInstance(project: Project): FriendModuleDetector = project.service()  

           private val FRIENDLY_IMPL_PATTERNS = listOf(  
            "friendlyImplementation",  
            "friendlyImplementation(",  
            "friendlyImplementation (",  
        )  
    }  
  public fun hasFriendlyImplementation(module: Module): Boolean {  
        val moduleName = module.name  

        // Check cache first  
        cache[moduleName]?.let { return it }  

        // Check if module name suggests it's a friend module (fast path)  
        if (moduleName.contains(".glue")) {  
            cache[moduleName] = true  
            return true        
            }  

        // Check the build file for friendlyImplementation  
        val hasFriendlyImpl = checkBuildFileForFriendlyImplementation(module)  
        cache[moduleName] = hasFriendlyImpl  

        return hasFriendlyImpl  
    }  

  private fun checkBuildFileForFriendlyImplementation(module: Module): Boolean {  
        val buildFile = GradleUtil.getGradleBuildScriptSource(module)  

        return buildFile != null && containsFriendlyImplementation(buildFile)  
    }  

private fun containsFriendlyImplementation(buildFile: VirtualFile): Boolean {  
        try {  
            val content = String(buildFile.contentsToByteArray())  

            return FRIENDLY_IMPL_PATTERNS.any { pattern ->  
                content.contains(pattern)  
            }  
        } catch (e: Exception) {  
            // If we can't read the file, assume no friendly implementation  
            return false  
        }  
    }  

   public fun clearCache() {  
        cache.clear()  
    }  

    public fun clearCacheForModule(moduleName: String) {  
            cache.remove(moduleName)  
        }  
    }

and lastly, a startup to listen for file changes on build files so we can invalidate our build file cache when a build file changes

public class FriendModuleStartupActivity : ProjectActivity {  

    override suspend fun execute(project: Project) {  
        // Register the build file listener  
        val connection = project.messageBus.connect()  
        connection.subscribe(  
            com.intellij.openapi.vfs.VirtualFileManager.VFS_CHANGES,  
            FriendModuleBuildFileListener(project),  
        )  
    }  
}

public class FriendModuleBuildFileListener(private val project: Project) : BulkFileListener {  

    override fun after(events: MutableList<out VFileEvent>) {  
        val detector = FriendModuleDetector.getInstance(project)  

        for (event in events) {  
            if (event is VFileContentChangeEvent) {  
                val file = event.file  
                if (isBuildFile(file)) {  
                    // Find the module for this build file and clear its cache  
                    val module = ModuleUtilCore.findModuleForFile(file, project)  
                    if (module != null) {  
                        detector.clearCacheForModule(module.name)  
                    }  
                }  
            }  
        }  
    }  

    private fun isBuildFile(file: VirtualFile): Boolean {  
        return file.name.endsWith(".gradle.kts")  
    }  
}

And after all of that, Android Studio no longer yells at us!

Outro

After adding support for a new Gradle configuration in our Gradle plugin and coercing Android Studio to not care about INVISIBLE_MEMBERS, we have a solution that allows wiring and glue modules to be friends where there is minimal impact to the developer experience!

I also later learned this concept of friendPaths is what allows test source sets to see internal members inside the main source set. I had sort of just taken this functionality for granted and never thought about how or why this works.

Lastly, if this 3 module system is anything you're interested in, I have a shameless plug for an IntelliJ plugin I maintain called Module Maker that helps streamline the creation of this 3 module systems: JetBrains Marketplace and Github and my blog post on the topic

Cover photo by fredrikwandem

First, let's take a look at how HStack renders two long text elements.

We can see SwiftUi has a fairly sane implementation. HStack does its best to try and render the two long text elements.

Now, let's take a look at how web handles the same situation.

Also, a fairly sane implementation. We can see that our similar implementation in web does its best to render both text elements.

Lastly, let's take a look at how Jetpack Compose handles a similar situation

Hmm, that's not similar to other platforms out of the box behavior. We see the first text image completely render, but the second one is pushed off the screen and has a width of 0.

The expert Android developers out there are probably saying, just apply a weight to each element!

Okay, now we are getting somewhere. But what if the text elements aren't roughly the same size?

Obviously that doesn't work the way we want. The reality is, in most scenarios with static layouts, using weights will be fine enough to get you the layouts you want.

What if our layouts are dynamic though? How can we achieve a similar behavior to SwiftUi and web?

Custom Layouts For Fun And For Profit

Before we dive into the solution that worked for me in my situation, let's examine prior art.

Here is an example from Hedvig Insurance of a custom layout that allows two items to take up the amount of space that they want while still respecting the other element.

From the documentation:

When two items need to be laid out horizontally in a row, they can't know how much space they need to take out, which more often than not results in the starting item taking up all the width it needs, squeezing the end item. This layout makes sure to measure their max intrinsic width and give as much space as possible to each item, without squeezing the other one. If both of them were to need more than half of the space, or less than half of the space, they're simply given half of the width each.

This solution works perfectly fine if that is exactly your requirement, but in my particular use case, I still needed to support all of the fun things a normal Row did: weight, alignment, arrangement, etc.

So, for better or worse, the solution I landed on was to copy the Row implementation and make changes to the measure policy of Row to add the behavior I wanted to create.

Examine The Problem

The behavior that is problematic lies in this line of code.

When a child element in the Row is asking for how much room it can have, it takes the remaining amount (forcing it to be at least 0). This exactly describes the problematic behavior from the examples in our intro. When the first element lays out, it takes up as much room as it wants, and then when the second element gets its constraints, the remaining amount of space left is 0, so it doesn't have anywhere to go in the layout.

This area will be our main focus point for our custom solution.

The logic I wanted to follow was something like this:

Grab the max width the current element want to use

Then, calculate the largest part an element could possibly occupy, which is proportional to the max width of the container divided by the number of elements. For example, if you have a Row and there are 5 elements, then assuming all 5 elements want to render at their max width, the largest part an element could take up is 1/5 of the container size (also accounts for elements with a weight)

If the max width that I want to take up is larger than the largest part that I could take up, then I need to calculate how much space I can take up (assuming the other elements don't want max space)

This is done by subtracting the remaining desired width of the other elements, and the elements that have already been laid out, from the max width I want to take up.

In code form, that translates to the following:

// grab the max intrinsix width of elements
val results = IntArray(measurables.size) { 0 }
for (i in startIndex until endIndex) {
    results[i] = measurables[i].maxIntrinsicWidth(0).coerceAtMost(mainAxisMax)
}

val maxWidthIWant = results[i]
val largestPartDividend =
    if (results.all { it == 0 }) {
        // if row is all images or something that has no intrinsic size
        // and we don't know it ahead of time
        measurables.size.coerceAtLeast(1)
    } else {
        measurables.filter { it.rowColumnParentData.weight <= 0f }.size.coerceAtLeast(1)
    }
// largest part is determined by the max width of the container divided by the number of elements that don't have weight
val largestPart = mainAxisMax / largestPartDividend

if (maxWidthIWant > largestPart) {
    val remainingDesiredWidthAfterThisElement = results.drop(i + 1).sum()
    val alreadyConsumedWidth = mainAxisMax - remaining
    val maxWidthICanTakeUp =
        (
            maxWidthIWant - remainingDesiredWidthAfterThisElement -
                alreadyConsumedWidth
        ).coerceAtLeast(
            largestPart,
        )
    remaining.coerceAtLeast(0).coerceAtMost(maxWidthICanTakeUp)
} else {
    remaining.coerceAtLeast(0).coerceAtMost(largestPart)
}

Please note, I haven't fully benchmarked this solution (yet). At best, it's the same as row, but at worse, it's performing additional maxIntrinsicWidth() calls, so I'd imagine there is a performance hit that I haven’t had a chance to fully benchmark yet. If performance is critical, I'd verify it works for your use case first.

Wrapping Up

After implementing my custom row which I called AdaptiveRow, we are now able to layout elements in our row with behavior similar to other platforms.

Prior Art

1. https://github.com/HedvigInsurance/android/blob/develop/app%2Fdesign-system%2Fdesign-system-hedvig%2Fsrc%2Fmain%2Fkotlin%2Fcom%2Fhedvig%2Fandroid%2Fdesign%2Fsystem%2Fhedvig%2FHorizontalItems.kt#L10-L100

Cover Photo by Karsten Winegeart on Unsplash

As Android developers, we're constantly looking for ways to streamline our workflow.

One often-overlooked tool that can significantly boost your development process is the debug drawer.

In this post, we'll explore how to implement and leverage debug drawers to take your Android app development to the next level.

What is a Debug Drawer?

A debug drawer is a hidden panel in your app that contains various tools and information useful during development and testing.

Think of it as a Swiss Army knife for developers – always there when you need it, but invisible to regular users.

Adding A Debug Drawer To Your App

The concept we are going to employ to add a debug drawer to your app is to use debug and release configurations in Gradle to include different modules depending on the build.

To add a debug drawer to your app, we will first start by creating a new module.

In this example, I'll call it :debug-drawer

We are also going to want to create a no-op release implementation of this module so we can have different behaviors in debug vs. release builds.

In this example, I'll call it :debug-drawer-release

Lastly, we are going to create a :debug-drawer-api module for common configurations of our debug drawer feature.

In our :app module, I'm going to add :debug-drawer to the :app module as a dependency via the debugImplementation Gradle configuration.

I'm also going to add the :debug-drawer-release to the :app module as a dependency via the releaseImplementation Gradle configuration.

Lastly, I'm going to add :debug-drawer-api to the :app module as a dependency via the regular implementation Gradle configuration

Now comes the actual implementation of opening the debug drawer!

In this example, we will be opening the debug drawer by pressing the volume down key two times.

The main reason for this is most developers on our team use emulators, where sliding to open can be awkward.

Add the following code to the :debug-drawer-api module:

interface DebugOnlyKeyListener {
  fun onKeyDown(event: KeyEvent)
}

Then, we will modify the :debug-drawer and :debug-drawer-release modules to both depend on the :debug-drawer-api module via the implementation Gradle configuration.

Now, we can move on to actually creating debug and release implementations of DebugOnlyKeyListener

We will create classes with the same name that implement the DebugOnlyKeyListener.

The one that lives under :debug-drawer-release will have a no-op implementation, while the one that lives under :debug-drawer will have an actual implementation.

Now, let's create the actual implementation for DebugOnlyKeyListener in the :debug-drawer module!

import android.app.Application
import android.view.KeyEvent
import com.example.debugdrawer.debug.drawer.api.DebugOnlyKeyListener

class DebugOnlyKeyListenerImpl(val application: Application) : DebugOnlyKeyListener {
    private var count = 0

    override fun onKeyDown(event: KeyEvent) {
        if (event.isVolumeDownPressed()) {
            count++
        } else {
            count = 0
        }
        // Look for volume down twice in a row.
        if (count >= 2) {
            count = 0

            // start the debug activity
            val intent = Intent(application, DebugDrawerActivity::class.java)
            intent.flags += Intent.FLAG_ACTIVITY_NEW_TASK
            application.startActivity(intent)
        }
    }

    private fun KeyEvent.isVolumeDownPressed(): Boolean {
        return keyCode == KeyEvent.KEYCODE_VOLUME_DOWN &&
                (action == KeyEvent.ACTION_DOWN || action == KeyEvent.ACTION_UP)
    }
}

While a fairly trivial implementation, we are just listening for 2 consecutive volume down presses to trigger some functionality.

Now, we can add an Activity to the :debug-drawer module.

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.material3.Text

class DebugDrawerActivity : ComponentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            Text("Hello from debug drawer!")
        }
    }
}

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application>
        <activity
            android:name=".DebugDrawerActivity"
            android:launchMode="singleInstance" />
    </application>
</manifest>

Lastly, this can all be tied together in the main Activity that you want to trigger the debug drawer from.

Now, to test a debug build!

The debug Activity correctly opens in a debug build!

Now to test a release build.

In a release build, nothing happens after pressing the volume down two times.

At this point, you can add any functionality you want to your DebugDrawerActivity like listing feature flags, modifying and viewing network requests, etc.

These types of regressions are helpful to catch for a multitude of reasons. More context can be found here, but below are a few high level reasons:

1. If you see a function that is restartable but not skippable, it’s not always a bad sign, but it sometimes is an opportunity to do one of two things:

   1. Make the function skippable by ensuring all of its parameters are stable

   2. Make the function not restartable by marking it as a @NonRestartableComposable

2. Default expressions should be @static in every case except for the following two cases:

   1. You are explicitly reading an observable dynamic variable. Composition Locals and state variables are an important example of this. In these cases, you need to rely on the fact that the default expression will be re-executed when the value changes

   2. You are explicitly calling a composable function, such as remember. The most common use case for this is state hoisting

3. Not all classes need to be stable, but a class being stable unlocks a lot of flexibility for the compose compiler to make optimizations when a stable type is being used in places, which is why it is such an important concept for compose.

To help detect regressions via tooling, you can utilize a new Gradle Plugin called Compose Guard. Compose Guard allows you to generate compose compiler metrics and detect regressions to those metrics on PRs or release builds on CI.

Compose Guard currently checks for numerous regressions that would be useful to a team:

• New restartable but not skippable @Composables are added

• New unstable classes are added (only triggers if they are used as a @Composable parameter)

• New @dynamic properties are added to a @Composable

• New unstable parameters are added to a @Composable

By being able catch these regressions to the UI layer in PRs, you can ensure better performance without developers having to manually catch these types of issues in a PR review.

Adding Compose Guard To Your Project

Compose Guard is available via Maven Central. To start, add the plugin to your root build.gradle.kts file.

plugins {
    id("com.joetr.compose.guard") version "<latest version>" apply false
}

Then, you can apply the plugin to any subsequent modules that contain your Compose code. This can be simplified by utilizing convention plugins as well. I will use Now In Android as an example:

AndroidApplicationComposeConventionPlugin.kt

import com.android.build.api.dsl.ApplicationExtension
import com.google.samples.apps.nowinandroid.configureAndroidCompose
import org.gradle.api.Plugin
import org.gradle.api.Project
import org.gradle.kotlin.dsl.getByType

class AndroidApplicationComposeConventionPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        with(target) {
            pluginManager.apply("com.android.application")

            // apply Compose Guard Plugin
            pluginManager.apply("com.joetr.compose.guard")

            val extension = extensions.getByType<ApplicationExtension>()
            configureAndroidCompose(extension)
        }
    }
}

AndroidLibraryComposeConventionPlugin.kt

import com.android.build.gradle.LibraryExtension
import com.google.samples.apps.nowinandroid.configureAndroidCompose
import org.gradle.api.Plugin
import org.gradle.api.Project
import org.gradle.kotlin.dsl.dependencies
import org.gradle.kotlin.dsl.getByType
import org.gradle.kotlin.dsl.kotlin

class AndroidLibraryComposeConventionPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        with(target) {
            pluginManager.apply("com.android.library")

            // apply Compose Guard Plugin
            pluginManager.apply("com.joetr.compose.guard")

            val extension = extensions.getByType<LibraryExtension>()
            configureAndroidCompose(extension)
        }
    }
}

Now that you've applied the plugin, you will notice new Gradle tasks appear for the project. Compose Guard adds two new tasks for each variant as well as one 'clean' task.

• <variant>ComposeCompilerGenerate (example releaseComposeCompilerGenerate)

  • Generate golden compose metrics to compare against

• <variant>ComposeCompilerCheck (example releaseComposeCompilerCheck)

  • Generates new metrics and compares against golden values

• composeCompilerClean

  • Deletes all golden and check compiler metrics

You can execute a root level prodReleaseComposeCompilerGenerate task to generate the metrics for every module in Now In Android (but you can also just run :app:prodReleaseComposeCompilerGenerate to generate the the metrics for just the :app module.

After running the above task, you should now see metrics generated for every module under the compose_reports folder of that module.

The folder name can be customized via Kotlin DSL in the module's build file.

composeGuard {
    outputDirectory = layout.projectDirectory.dir("custom_dir").asFile
}

Now that the golden metrics are generated, let's add an unstable class to a @Composable! I picked a random @Composable in the NIA app to demo this feature.

data class NewUnstableClass(var unstableParameter: Int)

@Composable
private fun LoadingState(modifier: Modifier = Modifier, unstableParameter: NewUnstableClass) {
    NiaLoadingWheel(
        modifier = modifier
            .fillMaxWidth()
            .wrapContentSize()
            .testTag("forYou:loading"),
        contentDesc = stringResource(id = R.string.feature_bookmarks_loading),
    )
}

Now, if I run ./gradlew prodReleaseComposeCompilerCheck, you should see the build fail!

* What went wrong:
Execution failed for task ':feature:bookmarks:prodReleaseComposeCompilerCheck'.
> New unstable classes were added! 
  ClassDetail(className=NewUnstableClass, stability=UNSTABLE, runtimeStability=UNSTABLE, fields=[Field(status=stable, details=var unstableParameter: Int)], rawContent=RawContent(content=unstable class NewUnstableClass {
    stable var unstableParameter: Int
    <runtime stability> = Unstable
  }))
  More info: https://github.com/androidx/androidx/blob/androidx-main/compose/compiler/design/compiler-metrics.md#classes-that-are-unstable

By adding this check to PR and release build jobs on CI, you can start to detect these types of UI regressions!

Summary

By adding Compose Guard to your project, you can start to detect UI regressions via tooling. These UI regressions have a multitude of performance implications for a project, so it's important to try and catch issues as early as possible.

Notice

I, Joseph Roskopf, am one of the authors of this Gradle Plugin along with Joshua Swigut.

When you add an Android module as a dependency in a JVM module, you are left with a fairly confusing error message.

I wanted to intercept this and provide a more friendly error message to developers on the team who might run into this issue. We have an internally managed IntelliJ / Android Studio plugin that we use that I thought I could tie into to help with this situation.

There are many solutions to listen to build / sync / compilation status from within an IntelliJ plugin: GradleSyncListener, ExternalSystemExecutionAware, GradleBuildListener, CompilationStatusListener, ProjectTaskListener, and ExecutionListener . However, the issue I was running into was that when I added an Android library / module to a JVM module in my project, it was being reported as a successful build / sync.

(:coroutines is a sample Android module being added to a JVM module in my project)

My plan was to manually parse build files looking for our internal JVM + Android plugin identifiers and parsing through each module's dependencies if I couldn't find a way to accomplish this via IntelliJ / Gradle APIs.

Luckily, after some more digging, I came across the GradleIssueChecker extension point. Using the GradleIssueChecker, we can be alerted when a build fails with a useful error message and report a BuildIssue on top of the original Gradle issue.

To start using the GradleIssueChecker API, there were some dependencies I needed to add to the existing project.

In the build.gradle.kts file for the project I added:

plugins {
    ...
    id("idea") // added "idea" plugin
}

intellij {
    pluginName = properties("pluginName")
    version = properties("platformVersion")
    type = properties("platformType")

    plugins = "android" // added "android" plugin
}

In the resources/META_INF/plugin.xml I added:

<idea-plugin>
    <!-- Added -->
    <depends>com.intellij.gradle</depends>
    <depends>org.jetbrains.android</depends>

    <!-- Added -->
    <extensions defaultExtensionNs="org.jetbrains.plugins.gradle">
        <!--suppress PluginXmlValidity -->
        <issueChecker implementation="path to class that implements GradleIssueChecker"/>
    </extensions>
</idea-plugin>

Finally, to implement our own GradleIssueChecker class:

import com.intellij.build.issue.BuildIssue
import com.intellij.build.issue.BuildIssueQuickFix
import com.intellij.openapi.project.Project
import com.intellij.pom.Navigatable
import org.gradle.internal.component.NoMatchingConfigurationSelectionException
import org.jetbrains.plugins.gradle.issue.GradleIssueChecker
import org.jetbrains.plugins.gradle.issue.GradleIssueData
import org.jetbrains.plugins.gradle.service.execution.GradleExecutionErrorHandler

/**
 * Checks for [NoMatchingConfigurationSelectionException] which is often a confusing error
 * and tries to offer a more straight forward error message to developers.
 */
@Suppress("UnstableApiUsage")
public class CustomGradleIssueChecker : GradleIssueChecker {

    override fun check(issueData: GradleIssueData): BuildIssue? {
        val throwable = GradleExecutionErrorHandler.getRootCauseAndLocation(issueData.error).first
        val throwableMessage = throwable.message
        val throwableName = throwable::class.qualifiedName
        val exceptionName = NoMatchingConfigurationSelectionException::class.qualifiedName
        // unsure why a type check of throwable is NoMatchingConfigurationSelectionException does not work
        if (throwableName == exceptionName && throwableMessage != null) {
            // matching some error messaging referring to (I think) the JVM module importing an Android module
            if (throwableMessage.contains("attribute 'org.jetbrains.kotlin.platform.type' with value 'jvm'")) {
                val moduleRegex = Regex("""project\s*:\s*(\S+)""")
                val moduleMatches = moduleRegex.find(throwableMessage)
                val dependencyName = if (moduleMatches != null && moduleMatches.groupValues.isNotEmpty()) {
                    moduleMatches.groupValues[0]
                } else {
                    // If we cannot match a module, try matching the more generic artifact
                    val libraryRegex = Regex("""No matching variant of (\S+)""")
                    val libraryMatches = libraryRegex.find(throwableMessage)
                    if (libraryMatches != null && libraryMatches.groupValues.size >= 2) {
                        libraryMatches.groupValues[1]
                    } else {
                        "Unknown"
                    }
                }
                return object : BuildIssue {
                    override val description: String
                        get() = """
                            The dependency ('$dependencyName') looks to be an Android dependency added to a JVM only module.
                        """.trimIndent()
                    override val quickFixes: List<BuildIssueQuickFix>
                        get() = emptyList()
                    override val title: String
                        get() = "Android Dependency '$dependencyName' Detected In JVM Only Module"

                    override fun getNavigatable(project: Project): Navigatable? {
                        return null
                    }
                }
            }
        }

        // not an error we care about
        return null
    }
}

In our custom checker, we start at the main entry point of the GradleIssueChecker API - fun check(issueData: GradleIssueData): BuildIssue?. The main API gives us GradleIssueData and it is our job to return an optional BuildIssue to report.

The first thing I want to do is to try and match the error (NoMatchingConfigurationSelectionException) that occurs when an Android module is added to a JVM module. After we match that error, we can do some (probably brittle 😁) string matching on the error message to make sure we are specifically in the scenario we want to match. The last part tries to match either the internal module, project :coroutines , or the Android artifact, No matching variant of androidx.activity:activity:1.8.2, that triggered the error so we can include it in our error message.

This pattern has more examples throughout the Android Studio plugin that can be found on Github here. For example, if you have ever seen the error message Disable Gradle 'offline mode' and sync project - here is that implementation.

I hope you found this interesting Intellij plugin API as useful as I did!

The Dagger Service Provider Interface (SPI) is a mechanism to hook into Dagger’s annotation processor and access the same binding graph model that Dagger uses. With the SPI, you can write a plugin that

• adds project-specific errors and warnings, e.g. Bindings for android.content.Context must have a @Qualifier or Bindings that implement DatabaseRelated must be scoped

• generates extra Java source files

• serializes the Dagger model to a resource file

• builds visualizations of the Dagger model

• and more!

The first bullet point is what we are after today.

Moving as many checks as possible to static analysis tools like Lint, Detekt, and SPI plugins is a great way to Shift Left and fix these types of issues before a PR is ever raised.

Rules

Let's start first by defining the custom behavior we want to validate with our plugins, and then we will get to writing tests and incorporating the plugins into our project.

The three plugins we will be writing in this post are:

1. Make sure no un-qualified primitives are provided into the Dagger graph. Something like this would be flagged with the plugin:

   1.   @Module
        class PrimitiveModule {
          // should have a qualifier to provide a primitive
          @Provides
          fun provideString(): String {
            return "test"
          }
        }
      

2. Make sure classes that extend from a single interface are added to the Dagger graph via @Binds instead of @Provides Something like this would not be allowed:

   1.   interface TestInterface {
          fun hello()
        }
      
        class TestClass : TestInterface {
          override fun hello() {
            TODO("Not yet implemented")
          }
        }
      
        @Singleton @Component(modules = [MyModule::class])
        interface MyComponent {
          fun testClass(): TestClass
        }
      
        @Module object MyModule {
          // should be added via @Binds instead
          @Provides @Singleton fun providesTestClass() = TestClass()
        }
      

3. Lastly, we want to make sure classes are provided uniquely into the graph between @Inject constructors and @Provides :

   1.   @Singleton @Component
        interface MyComponent {
          fun dependency(): Dependency
          fun subcomponent(): MySubcomponent
        }
      
        @Subcomponent(modules = [MySubmodule::class])
        interface MySubcomponent {
          fun dependency(): Dependency
        }
      
        @Module object MySubmodule {
          @Provides fun providesDependency() = Dependency("Provides")
        }
      
        // Already added via @Provides, no need for @Inject constructor
        class Dependency @Inject constructor(dep: String)
      

Setup

To start, we will want to create a JVM module to host our new plugins. We will also need KSP and the following dependencies:

plugins {
    id("org.jetbrains.kotlin.jvm")
    id("com.google.devtools.ksp")
}

dependencies {
    val daggerVersion = "2.48"
    val autoServiceKspVersion = "1.1.0"
    val googleAutoServiceVersion = "1.1.1"
    val kctVersion = "0.4.0"

    implementation("com.google.dagger:dagger-spi:$daggerVersion")
    ksp("dev.zacsweers.autoservice:auto-service-ksp:$autoServiceKspVersion")
    compileOnly("com.google.auto.service:auto-service:$googleAutoServiceVersion")

    // for testing our SPI plugins
    testImplementation("dev.zacsweers.kctfork:core:$kctVersion")
    testImplementation("dev.zacsweers.kctfork:ksp:$kctVersion")
    testImplementation("com.google.dagger:dagger-compiler:$daggerVersion")
}

Within our newly created module, assuming it was called :dagger-spi-plugins , we will want to add our first plugin.

The following plugin makes sure all primitive types are provided with a qualifier:

import com.google.auto.service.AutoService
import dagger.spi.model.BindingGraph
import dagger.spi.model.BindingGraphPlugin
import dagger.spi.model.DiagnosticReporter
import javax.tools.Diagnostic

// list of class types we are interested in
private val PRIMITIVES =
  listOf(
    Integer::class.java.name,
    String::class.java.name,
    Boolean::class.java.name,
    Float::class.java.name,
    Double::class.java.name
  )

// Adds the plugin via a Service Loader with Zac Sweer's fork of auto-service
@AutoService(BindingGraphPlugin::class)
class PrimitiveValidator : BindingGraphPlugin {

  override fun visitGraph(bindingGraph: BindingGraph, diagnosticReporter: DiagnosticReporter) {
    bindingGraph
       // grab all bindings
      .bindings()
       // filter the types if they are contained in our primitives list and don't have a qualifier
      .filter { binding ->
        val key = binding.key()
        PRIMITIVES.contains(key.type().toString()) && !key.qualifier().isPresent
      }
      .forEach { binding ->
        // report an error for any present binding
        diagnosticReporter.reportBinding(
          Diagnostic.Kind.ERROR,
          binding,
          "Primitives should be annotated with any qualifier"
        )
      }
  }
}

Now we can add our 2nd plugin. This plugin will make sure classes that extend from a single interface are added to the Dagger graph via @Binds instead of @Provides :

import com.google.auto.service.AutoService
import com.google.devtools.ksp.closestClassDeclaration
import com.google.devtools.ksp.symbol.ClassKind
import dagger.spi.model.Binding
import dagger.spi.model.BindingGraph
import dagger.spi.model.BindingGraphPlugin
import dagger.spi.model.BindingKind
import dagger.spi.model.DaggerProcessingEnv
import dagger.spi.model.DiagnosticReporter
import javax.tools.Diagnostic

@AutoService(BindingGraphPlugin::class)
class BindsValidator : BindingGraphPlugin {

  override fun visitGraph(bindingGraph: BindingGraph, diagnosticReporter: DiagnosticReporter) {
    // grab all bindings
    bindingGraph.bindings()
      .asSequence()
      // filter for things being provided via @Provides
      .filter { it.kind() == BindingKind.PROVISION }
      .forEach { provisionedBinding ->
        // grab all classes with a single super type that is an interface
        val classBindingsWithInterfaceSuperTypes = bindingGraph
          .bindings(provisionedBinding.key())
          .asSequence()
          .filter { binding ->
            // we are only interested in the KSP pass, not javac
            if (binding.key().type().backend() == DaggerProcessingEnv.Backend.KSP) {
              binding.key().type().ksp().declaration.closestClassDeclaration()?.let { closestClassDeclaration ->
                // if the binding we are visiting is a class
                closestClassDeclaration.classKind == ClassKind.CLASS &&
                  // extending from exactly 1 thing
                  closestClassDeclaration.superTypes.count() == 1 &&
                  // and that thing is an interface
                  closestClassDeclaration.superTypes.first().resolve().declaration.closestClassDeclaration()?.classKind == ClassKind.INTERFACE
              } ?: false
            } else {
              false
            }
          }
          .toList()

        if (classBindingsWithInterfaceSuperTypes.isNotEmpty()) {
          // report an error for each instance
          classBindingsWithInterfaceSuperTypes.forEach {
            diagnosticReporter.reportBinding(
              Diagnostic.Kind.ERROR,
              it,
              "${it.key().type().ksp().declaration.simpleName.getShortName()} should be added to the graph via @Binds instead of @Provides since it extends a single interface"
            )
          }
        }
      }
  }
}

The last plugin we want to add is one that makes sure classes are provided uniquely into the graph between @Inject constructors and @Provides :

import com.google.auto.service.AutoService
import dagger.spi.model.Binding
import dagger.spi.model.BindingGraph
import dagger.spi.model.BindingGraphPlugin
import dagger.spi.model.BindingKind
import dagger.spi.model.DiagnosticReporter
import javax.tools.Diagnostic

@AutoService(BindingGraphPlugin::class)
class UniqueInjectBindingValidator : BindingGraphPlugin {

  override fun visitGraph(bindingGraph: BindingGraph, diagnosticReporter: DiagnosticReporter) {
    bindingGraph
      // grab all bindings
      .bindings()
      .asSequence()
      // filter for bindings being added via @Inject constructors
      .filter { it.kind() == BindingKind.INJECTION }
      .forEach { injectBinding: Binding ->
        // grab other bindings that are not @Inject consturcotrs or member injection
        val otherBindings =
          bindingGraph
            .bindings(injectBinding.key())
            .asSequence()
            // Filter out other @Inject bindings
            .filter { it.kind() != BindingKind.INJECTION }
            // Filter out other member injection sites
            .filter { it.kind() != BindingKind.MEMBERS_INJECTION }
            .toList()

        // we are left with a list of bindings provided via @Provides
        // report an error for each one
        if (otherBindings.isNotEmpty()) {
          diagnosticReporter.reportBinding(
            Diagnostic.Kind.ERROR,
            injectBinding,
            "@Inject constructor has duplicates other bindings: ${otherBindings.joinToString()}"
          )
        }
      }
  }
}

Phew, I'm a little tired after writing those plugins. Let's take a a small break and look at a cute puppy.

Now that we are feeling refreshed, let's write some unit tests for our plugins! In the test source set for our :dagger-spi-plugins module, we will first add some utility methods to better facilitate our testing.

We will be using Zac Sweer's fork of the Kotlin Compile Testing library to test our code output, and these utility functions just make our test setup easier.

import com.tschuchort.compiletesting.JvmCompilationResult
import com.tschuchort.compiletesting.KotlinCompilation
import com.tschuchort.compiletesting.SourceFile
import com.tschuchort.compiletesting.kspArgs
import com.tschuchort.compiletesting.kspSourcesDir
import com.tschuchort.compiletesting.kspWithCompilation
import com.tschuchort.compiletesting.symbolProcessorProviders
import dagger.internal.codegen.KspComponentProcessor
import org.intellij.lang.annotations.Language
import java.io.File
import org.jetbrains.kotlin.compiler.plugin.ExperimentalCompilerApi

internal interface KotlinCompiler {
  fun compile(vararg sourceFiles: SourceFile): CompilationResult
}

@OptIn(ExperimentalCompilerApi::class)
internal class KspKotlinCompiler(tempDir: File) : KotlinCompiler {

  private val compiler =
    KotlinCompilation().apply {
      inheritClassPath = true
      symbolProcessorProviders =
        listOf(
          KspComponentProcessor.Provider.withTestPlugins(
            // our 3 custom plugins written earlier
            BindsValidator(),
            PrimitiveValidator(),
            UniqueInjectBindingValidator()
          ),
        )
      kspArgs = getKspArguments()
      kspWithCompilation = true
      verbose = false
      workingDir = tempDir
    }

  override fun compile(vararg sourceFiles: SourceFile): CompilationResult {
    compiler.sources = sourceFiles.asList()
    return CompilationResult(
      compiler.compile(),
      findGeneratedFiles(compiler.kspSourcesDir),
      compiler.workingDir.resolve("sources"),
    )
  }
}

internal data class CompilationResult
@OptIn(ExperimentalCompilerApi::class)
constructor(
  val result: JvmCompilationResult,
  val generatedFiles: List<File>,
  val sourcesDir: File,
)

private fun findGeneratedFiles(file: File): List<File> {
  return file.walkTopDown().filter { it.isFile }.toList()
}

private fun getKspArguments() =
  mutableMapOf(
    "dagger.fullBindingGraphValidation" to "ERROR",
  )

internal fun createSource(@Language("kotlin") code: String): SourceFile {
  return SourceFile.kotlin("${code.findFullQualifiedName()}.kt", code)
}

private fun String.findFullQualifiedName(): String {
  val packageRegex = "package (.*)".toRegex()
  val packageName = packageRegex.find(this)?.groupValues?.get(1)?.trim()
  val objectRegex = "(abstract )?(class|interface|object) ([^ ]*)".toRegex()
  val objectMatcher = checkNotNull(objectRegex.find(this)) { "No class/interface/object found" }
  val objectName = objectMatcher.groupValues[3]
  return if (packageName != null) {
    "${packageName.replace(".", "/")}/$objectName"
  } else {
    objectName
  }
}

Now that we have some helper functions, let's write the first test for the PrimitiveValidator plugin:

import com.tschuchort.compiletesting.KotlinCompilation
import org.jetbrains.kotlin.compiler.plugin.ExperimentalCompilerApi
import org.junit.Rule
import org.junit.Test
import org.junit.rules.TemporaryFolder

@OptIn(ExperimentalCompilerApi::class)
class PrimitiveValidatorTest {

  @JvmField @Rule var folder = TemporaryFolder()

  @Test
  fun `primitives should not be provided without a qualifier`() {
    val compiler = KspKotlinCompiler(tempDir = folder.root)

    val component =
      createSource(
        """
            package test

            import dagger.Module
            import dagger.Provides

            @Module
            class PrimitiveModule {

              @Provides
              fun provideString(): String {
                return "test"
              }
            }
            """
          .trimIndent(),
      )

    val compilation = compiler.compile(component)

    assert(compilation.result.exitCode == KotlinCompilation.ExitCode.COMPILATION_ERROR)
    assert(
      compilation.result.messages.contains("Primitives should be annotated with any qualifier")
    )
  }

  @Test
  fun `primitives can be provided with a qualifier`() {
    val compiler = KspKotlinCompiler(tempDir = folder.root)

    val component =
      createSource(
        """
            package test

            import dagger.Module
            import dagger.Provides
            import javax.inject.Qualifier

            @Qualifier annotation class PrimitiveQualifier

            @Module
            class PrimitiveModule {

              @Provides
              @PrimitiveQualifier
              fun provideString(): String {
                return "test"
              }
            }
            """
          .trimIndent(),
      )

    val compilation = compiler.compile(component)

    assert(compilation.result.exitCode == KotlinCompilation.ExitCode.OK)
  }
}

The second test is our happy path - showing a primitive being provided with a qualifier does not trigger any errors. The first test is demonstrating that an error is thrown with our custom message when a primitive is provided.

The second test we will write is for our BindsValidator plugin:

import com.tschuchort.compiletesting.KotlinCompilation
import org.jetbrains.kotlin.compiler.plugin.ExperimentalCompilerApi
import org.junit.Rule
import org.junit.Test
import org.junit.rules.TemporaryFolder

@OptIn(ExperimentalCompilerApi::class)
class BindsValidatorTest {

  @JvmField @Rule var folder = TemporaryFolder()

  @Test
  fun `items should not be provided if they can be bound instead`() {
    val compiler = KspKotlinCompiler(tempDir = folder.root)

    val component =
      createSource(
        """
        package com.example

        import dagger.Component
        import dagger.Module
        import dagger.Provides
        import javax.inject.Inject
        import javax.inject.Singleton

          interface TestInterface {
            fun hello()
          }

          class TestClass : TestInterface {
            override fun hello() {
              TODO("Not yet implemented")
            }
          }

          @Singleton @Component(modules = [MyModule::class])
          interface MyComponent {
            fun testClass(): TestClass
          }

          @Module object MyModule {
            @Provides
            @Singleton fun providesTestClass() = TestClass()
          }
            """
          .trimIndent(),
      )

    val compilation = compiler.compile(component)

    assert(compilation.result.exitCode == KotlinCompilation.ExitCode.COMPILATION_ERROR)
    assert(
      compilation.result.messages.contains(
        "TestClass should be added to the graph via @Binds instead of @Provides since it extends a single interface"
      )
    )
  }

  @Test
  fun `binds work as intended`() {
    val compiler = KspKotlinCompiler(tempDir = folder.root)

    val component =
      createSource(
        """
        package com.example

        import dagger.Component
        import dagger.Module
        import dagger.Binds
        import javax.inject.Inject
        import javax.inject.Singleton

          interface TestInterface {
            fun hello()
          }

          class TestClass @Inject constructor() : TestInterface {
            override fun hello() {
              TODO("Not yet implemented")
            }
          }

          @Singleton @Component(modules = [MyModule::class])
          interface MyComponent {
            fun testClass(): TestClass
          }

          @Module interface MyModule {
            @Binds
            @Singleton fun bindsTestClass(testClass: TestClass) : TestInterface
          }
            """
          .trimIndent(),
      )

    val compilation = compiler.compile(component)

    assert(compilation.result.exitCode == KotlinCompilation.ExitCode.OK)
  }
}

The second test is our happy path showing that TestClass is successfully bound to TestInterface and no errors are thrown while the first test, which @Provides TestClass instead, shows that our plugin is successfully throwing an error.

Our last test will be for the unique binding plugin.

import com.tschuchort.compiletesting.KotlinCompilation
import org.jetbrains.kotlin.compiler.plugin.ExperimentalCompilerApi
import org.junit.Rule
import org.junit.Test
import org.junit.rules.TemporaryFolder

@OptIn(ExperimentalCompilerApi::class)
class UniqueInjectBindingValidatorTest {

  @JvmField @Rule var folder = TemporaryFolder()

  @Test
  fun `items should not be bound in multiple ways`() {
    val compiler = KspKotlinCompiler(tempDir = folder.root)

    val component =
      createSource(
        """
        package com.example

        import dagger.Component
        import dagger.Module
        import dagger.Provides
        import dagger.Subcomponent
        import javax.inject.Inject
        import javax.inject.Singleton

        @Singleton @Component
        interface MyComponent {
          fun dependency(): Dependency
          fun subcomponent(): MySubcomponent
        }

        @Subcomponent(modules = [MySubmodule::class])
        interface MySubcomponent {
          fun dependency(): Dependency
        }

        @Module object MySubmodule {
          @Provides fun providesDependency() = Dependency("Provides")
        }

        class Dependency @Inject constructor(dep: String)            
          """
          .trimIndent(),
      )

    val compilation = compiler.compile(component)

    assert(compilation.result.exitCode == KotlinCompilation.ExitCode.COMPILATION_ERROR)
    assert(compilation.result.messages.contains("com.example.Dependency is bound multiple times"))
  }

  @Test
  fun `no errors when bound once`() {
    val compiler = KspKotlinCompiler(tempDir = folder.root)

    val component =
      createSource(
        """
        package com.example

        import dagger.Component
        import dagger.Module
        import dagger.Provides
        import javax.inject.Inject
        import javax.inject.Singleton

        @Singleton @Component(modules = [MyModule::class])
        interface MyComponent {
          fun dependency(): Dependency
        }

        @Module object MyModule {
          @Provides fun providesDependency() = Dependency("Provides")
        }

        class Dependency(dep: String)
            """
          .trimIndent(),
      )

    val compilation = compiler.compile(component)

    assert(compilation.result.exitCode == KotlinCompilation.ExitCode.OK)
  }
}

Similarly, the second test is our happy path showing no errors, while the first test shows an error when Dependency is added via both @Inject constructor as well as @Provides .

Consuming Plugins In Your App

Now that we've written our plugins and the accompanying tests, we want to actually consume them in our project.

To do that, we need to add the following to our app's build file:

android {
    defaultConfig {
        ...
        ksp { arg("dagger.fullBindingGraphValidation", "WARNING") }
    }
}

dependencies {
    ksp(project(":dagger-spi-plugins"))
}

After doing so, if we add some test module that violates one of our rules and run ./gradlew :app:kspDebugKotlin, we should see the build fail successfully!

@Module
class PrimitiveModule {
  @Provides
  fun provideString(): String {
    return "test"
  }
}

Please note, the ksp argument dagger.fullBindingGraphValidation and :dagger-spi-plugins dependency need to be added to every module you want the validation to occur in! So if you have a custom plugin setup, you may want to add the dependencies to your library module setup.

Conclusion

Developing custom Dagger SPI plugins has been fun! It not only allowed us to tailor dependency injection to our specific needs but also significantly enhanced our development workflow. By writing tests for our plugins, we ensured their reliability and robustness, providing a safety net that encourages innovation without the fear of regression. Furthermore, our support for Kotlin Symbol Processing (KSP) marked a significant step forward, leveraging the power of Kotlin's tooling to streamline and optimize our build processes.

This is not just about enhancing our tooling; it's about embracing a "shift left" mindset. By moving more checks closer to the compiler and integrating static code analysis tools, we've managed to catch potential issues much earlier in the development cycle. This approach not only saves time and resources but also fosters a culture of quality and responsibility across a team.

First, we define an EventProcessor interface. The concrete implementation will be responsible for debouncing our clicks.

internal interface EventProcessor {
    fun processEvent(event: () -> Unit)

    companion object {
        val buttonClickMap = mutableMapOf<String, EventProcessor>()
    }
}

The implementation:

private const val DEBOUNCE_TIME_MILLIS = 1000L

private class EventProcessorImpl : EventProcessor {
    private val now: Long
        // this is being used in Compose multiplatform 
        // switch out with whatever millisecond provider you want
        get() = Clock.System.now().toEpochMilliseconds()

    private var lastEventTimeMs: Long = 0

    override fun processEvent(event: () -> Unit) {
        if (now - lastEventTimeMs >= DEBOUNCE_TIME_MILLIS) {
            event.invoke()
        }
        lastEventTimeMs = now
    }
}

The Composable function where our EventProcessor will be used and a helper function for getting this button's EventProcessor

internal fun EventProcessor.Companion.get(id: String): EventProcessor {
    return buttonClickMap.getOrPut(
        id
    ) {
        EventProcessorImpl()
    }
}

@Composable
fun debouncedClick(
    id: String = randomUUID(),
    onClick: () -> Unit,
): () -> Unit {
    val multipleEventsCutter = remember { EventProcessor.get(id) }
    val newOnClick: () -> Unit = {
        multipleEventsCutter.processEvent { onClick() }
    }
    return newOnClick
}

Here is an example of it being used:

PrimaryButton(
    onClick = debouncedClick {
        // handle click
    },
) {
    Text("Button")
}

Full code:

https://gist.github.com/j-roskopf/990baa5beef767fbb2fae8cce33e2529

When debugging (which I mean to be developing locally), I wanted to target a different table for my remote database, so I wasn't cluttering up production data with all of my local development data.

The solution wasn't super obvious to me when I originally set out to solve this problem, so I wanted to share what ended up working for me.

In my commonMain, I defined a BuildConfig interface and an expect declaration for my BuildConfigImpl

interface BuildConfig {
    fun isDebug(): Boolean
}

expect class BuildConfigImpl : BuildConfig

In my androidMain src set, it looks pretty familiar to an Android developer:

actual class BuildConfigImpl(private val applicationContext: Context) : BuildConfig {
    override fun isDebug(): Boolean {
        return 0 != applicationContext.applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE
    }
}

In my iosMain src set, it looks pretty familiar to an iOS developer. (I think at least, I'm not a good iOS developer 😅)

import kotlin.experimental.ExperimentalNativeApi

actual class BuildConfigImpl() : BuildConfig {

    @OptIn(ExperimentalNativeApi::class)
    override fun isDebug(): Boolean {
        return Platform.isDebugBinary
    }
}

In my Desktop target and src set, desktopMain , I use System Properties to define a local debug flag to pass along to my application so it can be flagged true when I'm working locally.

First, I added a new property to my local gradle.properties located in my Gradle home directory (~/.gradle/gradle.properties)

systemProp.syncSphereDebug=true

Then, in my desktopApp build file, I added the following code:

tasks.withType<JavaExec>().configureEach {
    systemProperty("syncSphereDebug", System.getProperty("syncSphereDebug"))
}

This allows me to now have an implementation for BuildConfigImpl for Desktop that looks like:

actual class BuildConfigImpl() : BuildConfig {
    override fun isDebug(): Boolean {
        val debugSystemProperty = System.getProperty("syncSphereDebug")
        return debugSystemProperty?.toBoolean() ?: false
    }
}

I hope this post was helpful where I covered enabling some sort of debug / local environment for providing different behavior when developing your Compose Multiplatform project!

One solution is to have the code duplicated and live under androidMain and iosMain under the shared module. However, duplicating code like that isn't a good path forward for a multitude of reasons.

Adding a shared source set between Android and iOS was a perfect solution for me here, allowing me to have one definition for both mobile platforms.

Starting with the interface and class definitions in commonMain

interface RoomRepository {
    ...
}

expect class RoomRepositoryImpl(
    dictionary: Dictionary,
    // CrashReporting is also an interface that has expect / actual
    // implementations that are the same on mobile, but differ on Desktop
    crashReporting: CrashReporting,
) : RoomRepository

In desktopMain, I can define my RoomRepositoryImpl like normal

actual class RoomRepositoryImpl actual constructor(
    dictionary: Dictionary,
    crashReporting: CrashReporting,
) : RoomRepository {
    ... Desktop specific implementation
}

Now on the mobile side, I created a new folder under the shared module called mobileMain

I register mobileMain as a source set in the shared module's build file like so:

        val mobileMain by creating {
            androidMain.dependsOn(this)
            iosMain.dependsOn(this)
            dependencies {
                dependsOn(commonMain)

                .. other dependencies
            }
        }

And now, I am able to put my common mobile implementation for RoomRepository that can be shared between Android and iOS!

First, we need to add a font to commonMain/resources/font

For this example, I have gone with dancingscript_regular.ttf The resource name should follow android resource conventions and be all lowercase with underscores if necessary.

I am adding this font to part of an app theme, but this part is optional.

@Composable
fun AppTheme(
    content:
    @Composable()
        () -> Unit,
) {

    MaterialTheme(
        content = content,
        typography = appTypography,
    )
}

appTypography is defined as a variable that creates a custom typography.

val appTypography : Typography
    @Composable
    get() {
        return Typography(
            defaultFontFamily = dancingScriptRegular
        )
    }

dancingScriptRegular is a custom font that we use expect/actual to get a different platform implementation.

val dancingScriptRegular: FontFamily
    @Composable
    get() {
        return FontFamily(
            font(
                "DancingScript",
                "dancingscript_regular",
                FontWeight.Normal,
                FontStyle.Normal,
            ),
        )
    }

The font function is the main bread and butter of our solution here. This is where we use expect/actual to give Android / iOS / Desktop implementations.

Under shared/src/commonMain/kotlin, I created a FontResource.kt class that looks like

import androidx.compose.runtime.Composable
import androidx.compose.ui.text.font.Font
import androidx.compose.ui.text.font.FontStyle
import androidx.compose.ui.text.font.FontWeight

@Composable
expect fun font(name: String, res: String, weight: FontWeight, style: FontStyle): Font

Under androidMain, iosMain, and desktopMain we will define our actual implemetations.

androidMain:

import androidx.compose.runtime.Composable
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.text.font.Font
import androidx.compose.ui.text.font.FontStyle
import androidx.compose.ui.text.font.FontWeight

@Composable
actual fun font(name: String, res: String, weight: FontWeight, style: FontStyle): Font {
    val context = LocalContext.current
    val id = context.resources.getIdentifier(res, "font", context.packageName)
    return Font(id, weight, style)
}

iosMain:

import androidx.compose.runtime.Composable
import androidx.compose.ui.text.font.Font
import androidx.compose.ui.text.font.FontStyle
import androidx.compose.ui.text.font.FontWeight
import kotlinx.coroutines.runBlocking
import org.jetbrains.compose.resources.ExperimentalResourceApi
import org.jetbrains.compose.resources.resource

private val cache: MutableMap<String, Font> = mutableMapOf()

@OptIn(ExperimentalResourceApi::class)
@Composable
actual fun font(name: String, res: String, weight: FontWeight, style: FontStyle): Font {
    // use a cache to store fonts and re-use 
    return cache.getOrPut(res) {
        val byteArray = runBlocking {
            resource("font/$res.ttf").readBytes()
        }
        androidx.compose.ui.text.platform.Font(res, byteArray, weight, style)
    }
}

desktopMain:

import androidx.compose.runtime.Composable
import androidx.compose.ui.text.font.Font
import androidx.compose.ui.text.font.FontStyle
import androidx.compose.ui.text.font.FontWeight

@Composable
actual fun font(name: String, res: String, weight: FontWeight, style: FontStyle): Font =
    androidx.compose.ui.text.platform.Font("font/$res.ttf", weight, style)

Lastly, in your shared module build.gradle.kts under the android block, you'll have to add this line so that the Android app will know to use commonMain/resources and a res src directory.

    android {
    compileSdk = (findProperty("android.compileSdk") as String).toInt()
    namespace = "com.myapplication.common"

    sourceSets["main"].manifest.srcFile("src/androidMain/AndroidManifest.xml")
    sourceSets["main"].res.srcDirs("src/androidMain/res")

    // This is the line to add
    sourceSets["main"].res.srcDirs("src/commonMain/resources") // <=== This is the line to add
    // This is the line to add

    sourceSets["main"].resources.srcDirs("src/commonMain/resources")

    defaultConfig {
        minSdk = (findProperty("android.minSdk") as String).toInt()
    }
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    kotlin {
        jvmToolchain(17)
    }
}

And then you should be able to run your project on iOS, Android, and Desktop using a common font.

CocoaPods

A finishing note about CocoaPods. When I was writing this article, I was using the most up-to-date version of the Compose Multiplatform template on Github from JetBrains as a demo. When I was adding this to my project Sync Sphere, I had to do some additional work to get fonts working on iOS. After doing all of the steps listed above, I also had to run ./gradlew :shared:podInstall to get the fonts copied over to iOS, otherwise I was running into a resource not found exception.

Conclusion

I hope these series of code snippets can prove helpful to someone implementing custom typography in their Compose Multiplatform app.

With Kotlin Multiplatform 1.5.10 going stable, now is as good of a time as any to dive into Compose Multiplatform.

With my background in Android development and some familiarity with Jetpack Compose, Compose Multiplatform is a great solution for when I need a cross-platform solution for UI + business logic to be shared across the targets that I'm interested in; Android, iOS, and Desktop.

However, my unfamiliarity with the intricacies of iOS and XCode has left me scratching my head from time to time. Don't get me wrong, general development using Compose Multiplatform has been great! I am usually working within Android Studio writing Kotlin, two tools I am extremely familiar with, but recently I wanted to distribute a test version of my iOS app on Firebase for friends and family to test, and that process took some time for me to understand. Today, I wanted to document some of my learnings so it can be helpful for others as well.

Problem

Using my Android knowledge and some Googling, I have found the generally accepted version of how to generate an IPA file is to open XCode, select your relevant destination (in this example, I am choosing any iOS device, arm64) and select Product -> Archive.

However, when I do that, I receive an error message about needing Java 17 when I am using Java 16. As an Android engineer, I am aware that projects using AGP 8.0+ are required to use Java 17, however, I am never install Java 16 on my system. I am truly baffled by where that error was coming from. My guess is that XCode must ship with some internal version of Java? What is even more confusing is that I have my Java home set correctly in my .zshrc file and when I input java -version in the terminal, I am met with what I expect to see, Java 17.

joe@Joes-MacBook-Pro ~ % java -version
openjdk version "17.0.7" 2023-04-18 LTS
OpenJDK Runtime Environment Corretto-17.0.7.7.1 (build 17.0.7+7-LTS)
OpenJDK 64-Bit Server VM Corretto-17.0.7.7.1 (build 17.0.7+7-LTS, mixed mode, sharing)

I had a hunch that for some reason, XCode wasn't aware of my path variables.

Solution

I've run into situations before with GIT GUI clients where opening them via the finder/dock doesn't allow for the application to be aware of your environment/path variables. To work around that, from previous issues, I've learned that opening your program via the command line with make the application aware of your environment/path variables.

So in the root of my project I executed open iosApp/iosApp.xcodeproj which should open XCode with your iOS project. After selecting Product -> Archive again, I was finally able to generate the archive for my project.

I hope this helps!

The Traditional Challenge

Android's default build system, Gradle, creates a build file for each module in the project, typically named build.gradle or build.gradle.kts for Kotlin. This convention is straightforward for smaller projects, but in larger, more complex projects with nested modules, locating the correct build file can become cumbersome.

The Solution

To simplify this process, we introduce the includeProject function. This function allows us to include a project into the build by its name and specifies an optional file path.

Here's how it works:

/**
 * Include module within the current project. Allows for specifying an optional file path
 */
fun includeProject(name: String, filePath: String? = null) {
    settings.include(name)
    val project = project(name)
    project.configureProjectDir(filePath)
    project.configureBuildFileName(name)
}

In the includeProject function, we have two parameters: name and an optional filepath. The name argument is used to include the module and then to obtain the project. The project's directory and build file are then configured. The optional parameter for specifying a custom file path can be included when you have a module name that does not follow the file system.

The configureProjectDir function sets the project directory and checks if the directory exists and is indeed a directory (and not a file). If not, a GradleException will be thrown and the build will fail to sync.

/**
 * Configures the project directory
 */
fun ProjectDescriptor.configureProjectDir(filePath: String? = null) {
    if (filePath != null) {
        projectDir = File(rootDir, filePath)
    }
    if (!projectDir.exists()) {
        throw GradleException("Path: $projectDir does not exist. Cannot include project: $name")
    }
    if (!projectDir.isDirectory) {
        throw GradleException("Path: $projectDir is a file instead of a directory. Cannot include project: $name")
    }
}

Meanwhile, the configureBuildFileName function is the heart of what we are wanting to accomplsh. It sets the build file name based on the module name and checks if the file exists. If not, again, a GradleException is thrown.

/**
 * Searches for all of the relevant module names we want allowed. 
 * For example, if we have a file structure:
 * 
 * ├── grandparent
 *    ├── parent
 *       ├── module
 *
 * where `grandparent` and `parent` are just folders and not logical modules, and `module` is a Gradle module,
 * we'd want to allow the following entries for `module`
 * 
 * 1. includeProject(":module")
 * 2. includeProject(":parent-module")
 * 3. includeProject(":grandparent-module")
 * 
 * In slightly more realistic example, let's say you have the following file structure:
 * ├── repository
 *    ├── fake
 *    ├── api
 *    ├── impl
 * 
 * We would want to allow the following names for including the 3 logical modules here, fake, api, and impl:
 * 
 * 1. includeProject(":repository-fake")
 * 2. includeProject(":repository-api")
 * 3. includeProject(":repository-impl")
 */
fun ProjectDescriptor.configureBuildFileName(projectName: String) {
    val name = projectName.substringAfterLast(":")
    val thirdToLastIndex = lastOrdinalIndexOf(projectName, ':', 3)
    val secondToLastIndex = lastOrdinalIndexOf(projectName, ':', 2)
    val lastIndex = lastOrdinalIndexOf(projectName, ':', 1)
    val directParentModule = projectName.substring(secondToLastIndex, lastIndex).trim(':')
    val thirdLevelParentModule = projectName.substring(thirdToLastIndex, lastIndex).trim(':').replace(":","-")

    val filesToCheck = listOf(
        "$name.gradle.kts",
        "$directParentModule-$name.gradle.kts",
        "$thirdLevelParentModule-$name.gradle.kts",
        // any other files you wish to be named
        // potentially still allow for build.gradle.kts
    )

    filesToCheck.firstOrNull {
        buildFileName = it
        buildFile.exists()
    } ?: throw GradleException("None of the following build files exist: ${filesToCheck.joinToString(", ")}. Cannot include project: $name")
}

/**
 * Finds the n-th last index within a String
 */
fun lastOrdinalIndexOf(string: String, searchChar: Char, ordinal: Int): Int {
    val numberOfOccurrences = string.count { it == searchChar }

    if(numberOfOccurrences <= ordinal) {
        return 0
    }
    var found = 0
    var index = string.length
    do {
        index = string.lastIndexOf(searchChar, index - 1)
        if (index < 0) {
            return index
        }
        found++
    } while (found < ordinal)
    return index
}

This function also handles different naming formats based on the module's hierarchy. So, for instance, if we have a file structure like this:

├── repository
   ├── fake
   ├── api
   ├── impl

Where fake, api, and impl are all logical modules, we can now include them in our Android project in the following way:

includeProject(":repository-fake")
includeProject(":repository-api")
includeProject(":repository-impl")

This flexibility allows you to maintain a naming pattern that matches your project's module hierarchy.

Wrapping Up

The includeProject function can be a huge timesaver in managing large, multi-module projects. Not only does it ensure that your project adheres to a logical, hierarchical naming convention, but it also reduces the risk of errors from manually entering project names and paths.

By enforcing a more systematic naming convention for your build files, you can navigate and manage your codebase more efficiently, especially when your project continues to scale. As a result, you'll spend less time searching for the correct build files and more time on what matters most - writing quality code for your Android application.

While the default New Module wizard does its job, it often falls short when aligning with specific project standards. It doesn't allow for much customization, leading to tedious and time-consuming manual adjustments. But, fret not! There's a new player in town, ready to streamline your module creation - introducing the Module Maker plugin.

Meet the Module Maker Plugin

The Module Maker plugin for Android Studio is an IntelliJ / Android Studio plugin for those looking to tailor their new modules to their project-specific standards. The plugin extends beyond the limitations of Android Studio's built-in tools, allowing for a more streamlined and customizable module creation experience.

Let's take a look at some of the unique features that make this plugin a must-have in your development toolkit.

1. 3 Module Creation Structure: Following the structure highlighted in this talk from Ralf Wondratschek at Square, the plugin allows you to create three modules at a time with customizable names. By default, the three module structure is composed of an API, Glue, and Impl module, helping you maintain cleaner and more manageable codebases.

2. Kotlin and Groovy Build Files: You can choose to have build files for each module generated as either Kotlin or Groovy. This flexibility ensures you can stick with your preferred language and keep your project's standards consistent.

3. Customizable Build File Names: Either stick with the default name ( build.gradle or build.gradle.kts ) or have your build file name follow the module. Tailoring the build file names to the module can help streamline the identification process and improve project organization.

4. Optional README and .gitignore Files: Upon creating your modules, the plugin can generate an optional README and .gitignore file, helping you jumpstart your module documentation and version control settings.

5. Android or JVM Only Module: Whether your module is meant for Android or just JVM, the plugin has got you covered.

6. Package Structure Specification: Specify your package structure and have the folders created directly on the filesystem, eliminating the need for manual creation and organization.

7. Automatic Settings Update and Sync: Once your new modules are ready, the plugin automatically adds them to your settings.gradle(.kts) file and syncs your project, sparing you the hassle of manual updates and syncs.

Customize Modules to Your Heart's Content

The Module Maker plugin understands that every project is unique, and therefore, it offers a robust settings page where you can specify a range of options to suit your project's specific needs. You can:

1. Specify different Android and JVM build file templates.

2. Define different API, Glue, and Impl build file templates.

3. Customize API, Glue, and Impl module names.

4. Specify a custom .gitignore template.

5. Specify a default package name to persist across usages of the plugin

The Wrap Up

In the dynamic landscape of Android development, maintaining a consistent and efficient project structure can often be challenging. The built-in New Module wizard, while helpful, may not always align with your project's specific standards. This is where the Module Maker plugin comes in - designed as a practical solution to enhance your module creation process.

With a wide range of features, from allowing a 3-module creation structure to offering customization options for your build files, the Module Maker plugin equips you with the tools to tailor your project to your preferences. Its ability to generate optional README and .gitignore files, automatic project sync, and customizable settings, all work towards a more streamlined and personalized Android project setup.

As the author of the Module Maker plugin, I aimed to provide a tool that could simplify and adapt to the unique needs of each Android project. I hope you find this plugin helpful and that it can assist in enhancing your workflow, saving time, and maintaining project consistency. After all, development should be more about solving complex problems and less about wrestling with project setup and organization.

Links

Github - https://github.com/j-roskopf/ModuleMakerPlugin

Plugin - https://plugins.jetbrains.com/plugin/21724-module-maker

One solution to this problem is to use a version catalog. A version catalog is a file that defines the versions of your project's dependencies, making it easier to manage and update them. In this blog post, we'll take a look at how to migrate an Android project to using a version catalog.

Step 1: Create a Version Catalog

The first step in migrating your Android project to use a version catalog is to create the catalog file. The version catalog is a simple TOML (more info about TOML files can be found here) file that lists the dependencies and their respective versions. You can create the file manually by right-clicking on your gradle folder and selecting New -> File and adding libs.versions.toml. It is possible to change the catalog file name, however, this requires changing your build files so it is not recommended at the current time.

Step 2: Adding dependencies to the .toml file

In your libs.versions.toml file, add these sections:

[versions]

[libraries]

[plugins]

We will be migrating the following dependency to being defined in the version catalog.

This can be defined in the .toml file by adding a version and a library like so:

[versions]
core-ktx = "1.10.0"

[libraries]
androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "core-ktx" }

[plugins]

Step 3: Use the Version Catalog in Your Dependencies

Finally, you need to update your project's dependencies to use the version catalog. You can do this by replacing the first line with a reference to the version catalog. For example:

implementation 'androidx.core:core-ktx:1.10.0'

can be replaced with:

implementation(libs.androidx.core.ktx)

Step 5: Plugins

In the root build.gradle file of your project, numerous plugins are defined. Using a version catalog also allows you to define these plugin versions as well.

First, you will add the plugin versions and definitions to the .toml file.

[versions]
core-ktx = "1.10.0"

# Plugin versions
androidGradlePlugin = "7.4.2"
kotlin = "1.8.0"

[libraries]
androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "core-ktx" }

[plugins]
android-application = { id = "com.android.application", version.ref = "androidGradlePlugin" }
android-library = { id = "com.android.library", version.ref = "androidGradlePlugin" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }

Then, you can change your root build.gradle file to use the newly defined plugins like so:

plugins {
    alias libs.plugins.android.application apply false
    alias libs.plugins.android.library apply false
    alias libs.plugins.kotlin.android apply false
}

Conclusion

By using a version catalog, you can easily manage your project's dependencies across modules and ensure that you are using the latest versions. You can update the versions in the catalog file, and have a single source of truth for versions of dependencies in your application.

In conclusion, migrating an Android project to use a version catalog is a simple process that can save you a lot of time and effort in managing your dependencies. By following the steps outlined in this blog post, you can easily migrate your project to use a version catalog and enjoy the benefits of easier dependency management.

First, let's define what we mean by "staged files." In Git, a staged file has been modified and added to the Git index, which means it is ready to be committed. This is different from an unstaged file, which has been modified but not yet added to the index.

With definitions out of the way, we then want to create a bash script that will invoke Spotless (this assumes you already have Spotless set up in your project). In this setup, the script will be invoked as a pre-commit Git hook. The script also presumes the presence of a .zshrc file. Some slight modifications would be needed to make this compatible with bash.

This script will do the following:

1. Stash any unstaged files

2. Apply Spotless to the remaining files

3. Add any modified files from Spotless to the git index

4. Cleanup the stash from step 1

#!/bin/zsh

# Workaround for Git GUI users to have environment variables available (https://community.atlassian.com/t5/Bitbucket-questions/SourceTree-Hook-failing-because-paths-don-t-seem-to-be-set/qaq-p/274792)
source ~/.zshrc

# Immediately exit if any command has a non-zero exit status
set -e

echo "Running formatter..."

# Creaate a patch file
GIT_STASH_FILE="stash.patch"

# Stash unstaged changes
git diff > "$GIT_STASH_FILE"

# add the patch so it is not stashed
git add "$GIT_STASH_FILE"

# stash untracked files
git stash -k

# apply spotless
./gradlew spotlessApply --daemon

# re-add any changes that spotless created
git add -u

# store the last exit code
RESULT=$?

if test -f "$GIT_STASH_FILE";
then
  echo "$GIT_STASH_FILE has been found"

    # apply the patch
    git apply stash.patch --allow-empty

    # delete the patch and re-add that to the index
    rm -f stash.patch
    git add stash.patch
else
    echo "$GIT_STASH_FILE has not been found"
fi

# delete the WIP stash
git stash drop

# return the exit code
exit $RESULT

That's it! Now, whenever you commit changes to your Git repository, Spotless will be applied to only the staged files. This ensures that your code is always clean and consistent, which can save you time and headaches down the line.

In conclusion, applying Spotless to only the staged files in your Git repository via a bash script in a pre-commit hook is a straightforward process that can improve the quality and consistency of the code that you want to commit, while leaving unstaged code alone. By following the steps outlined in this blog post, you can easily integrate Spotless into your development workflow and enjoy the benefits of clean code.

That's where Gradle Profiler comes in. Gradle Profiler is a tool that can help you measure and analyze your Gradle builds, so you can identify bottlenecks and speed up your build times. In this post, we'll walk through how to install and use Gradle Profiler, and we'll show you how to use it to test different scenarios to optimize your build times.

Step 1: Installing Gradle Profiler

The first step in using Gradle Profiler is to install it via SDKMAN. SDKMAN is a tool for managing software development kits, making it easy to install and manage Gradle Profiler.

To install SDKMAN on a Unix-based system, open up your terminal and run the following command:

curl -s "https://get.sdkman.io" | bash

Once you've installed SDKMAN, you can use it to install Gradle Profiler by running the following command (you may need to restart your terminal first):

sdk install gradleprofiler

Step 2: Running Gradle Profiler

Once you've installed Gradle Profiler, you can start using it to analyze your builds. To do this, you'll first create a .scenarios file. This is where you will define the different scenarios you want to profile. A sample profiling.scenarios file might look like this:

AssembleDebug8G {
    title = "assembleDebug with 8 gigs"
    tasks = ["assembleDebug"]
    warm-ups: 2
    iterations: 5
    cleanup-tasks = ["clean"]
    jvm-args = ["-Xmx8g", "-XX:MaxPermSize=1024m", "-XX:+HeapDumpOnOutOfMemoryError", "-XX:+UseParallelGC"]
}

AssembleDebug6G {
    title = "assembleDebug with 6 gigs"
    tasks = ["assembleDebug"]
    warm-ups: 2
    iterations: 5
    cleanup-tasks = ["clean"]
    jvm-args = ["-Xmx6g", "-XX:MaxPermSize=1024m", "-XX:+HeapDumpOnOutOfMemoryError", "-XX:+UseParallelGC"]
}

AssembleDebugParallel {
    title = "assembleDebug with 8 gigs and gradle parallel execution"
    tasks = ["assembleDebug"]
    warm-ups: 2
    iterations: 5
    gradle-args = ["--parallel"]
    cleanup-tasks = ["clean"]
    jvm-args = ["-Xmx8g", "-XX:MaxPermSize=1024m", "-XX:+HeapDumpOnOutOfMemoryError", "-XX:+UseParallelGC"]
}

3 different scenarios are defined in this file, all centered around the assembleDebug Gradle task. One with 8 gigs to the JVM args, one with 6 gigs, and one enabling Gradle parallel execution. We have also defined some additional information like the number of warm-ups and iterations to go through, as well as some clean-up tasks. Full documentation can be found on the Gradle Profiler Github.

To now execute one of these scenarios, we can use the following command in the terminal (assuming the file created above is in the root directory of your project and named profiling.scenarios). With the following command, we are running the AssembleDebug6G scenario that we defined earlier.

gradle-profiler --benchmark --project-dir . --scenario-file profiling.scenarios AssembleDebug6G

Note - You may want to add the following to your .gitignore

/profile-out/
/profile-out-*/
/gradle-user-home/

Step 3: Analyzing the Gradle Profiler Report

Once your build has been completed, Gradle will generate a report file that contains all of the information that was collected during the build. With the command above, this report file is saved in the root directory of your project.

To analyze the report, we can open up the .html file found in profile-out in this example. In this report, we can see fields like the mean, median, 25th, and 75th percentiles as well as the runtimes of each iteration.

Step 4: Testing Different Scenarios

Now that you've got Gradle Profiler set up, you can start testing different scenarios to see how they affect your build times. One common scenario that you might want to test is increasing the JVM args to see if that helps speed up your build.

To test this scenario, we can instead run the AssembleDebug8G scenario that we defined earlier. This will increase the maximum heap size that Gradle is allowed to use during the build, which can help speed up the build by reducing the amount of time spent on garbage collecting.

We can see that when we compare the results between using 6 gigs and 8 gigs, there isn't a ton of difference in mean execution time across the five iterations. That's okay though! Now we know! Increasing past 6 gigs for the Now In Android project doesn't give us much benefit.

Conclusion

In this post, we've shown you how to use Gradle Profiler to analyze your Gradle builds and identify bottlenecks that are slowing down your build times. By testing different scenarios, such as increasing the JVM args or switching to a different version of Gradle, you can optimize your builds and reduce your overall development time.

By taking the time to profile your builds with Gradle Profiler, you can save yourself a lot of frustration and make your development process smoother and more efficient. So give it a try, and see how much time you can save!

Have you ever noticed the output of a build, how some tasks have UP-TO-DATE next to the task and some don't? The Gradle build system provides a powerful mechanism for defining and executing custom tasks. However, when we define a custom task, it is often necessary to ensure that it only runs when something has changed. If a task is executed every time we build our project, it can significantly slow down our build process and waste valuable time.

Usecase for a Custom Gradle Task

On a recent project I was working on, there was a bash script that was executed before every commit. Git's pre-commit hook was utilized for this task and it worked well. However, for this to work on a developer's machine, they had to manually symlink the bash script to the pre-commit hook.

import org.gradle.api.Plugin
import org.gradle.api.Project

class PreCommitPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        with(target) {
            tasks.register("installPreCommitHook") {

                doLast {
                    exec {
                        // make the bash script executable
                        commandLine("chmod", "+x", "../pre-commit.sh")
                    }
                    exec {
                        // sym link it to the the pre-commit hook
                        commandLine("ln", "-s", "-f", "../../pre-commit.sh", "../.git/hooks/pre-commit")
                    }
                    exec {
                        // make the symlink executable
                        commandLine("chmod", "+x", "../.git/hooks/pre-commit")
                    }
                }
            }

            // execute every time `preBuild` runs
         tasks.getByPath(":app:preBuild").dependsOn("installFormattingPreCommitHook")
        }
    }
}

On a first pass, the custom Gradle plugin I wrote worked very well. However, after a few weeks in the wild, one of the developers pointed out to me that the task was running every build. Using Android Studio's Build Analyzer, I could confirm it was indeed running every build when it didn't necessarily need to.

(Of course, in the grand scheme of things, <0.1s isn't a huge concern, but an app's poor build time is often the result of a death by a thousand cuts)

To avoid this, we need to define the outputs for our custom Gradle tasks so that they are cacheable. This means that if the inputs for a task have not changed since the last time it was run, Gradle can skip the task and use the cached output instead. This can save us a lot of time and speed up our builds.

For this particular use case, the output of the task is the existence of the pre-commit hook. To define the outputs for a custom Gradle task, we need to use the outputs property of the Task object. We can define the output files, directories, or even properties that our task generates. Here is an example of how to define the output files for our custom task:

val gitHookPreCommitFile = file("../.git/hooks/pre-commit")
outputs.file(gitHookPreCommitFile.absolutePath)

By defining the outputs for our task in this way, Gradle can automatically check whether the input file has changed since the last time the task was run. If the input file has not changed, Gradle can skip the task (and mark it UP-TO-DATE) and use the cached output file instead. This can significantly speed up our builds and make our build process more efficient.

In addition to defining output files, we can also define output directories and properties for our custom Gradle tasks. This allows us to cache more complex data structures from our custom Gradle tasks and avoid executing our tasks unnecessarily.

In conclusion, defining outputs for custom Gradle tasks is an important step in optimizing our build processes. By doing so, we can make our tasks cacheable and avoid executing them unnecessarily on every incremental build. This can save us time and make our build process more efficient by not wasting CPU cycles on unnecessary tasks.

Full source code:

import org.gradle.api.Plugin
import org.gradle.api.Project

class PreCommitPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        with(target) {
            tasks.register("installPreCommitHook") {

                // define outputs of this task so that it is not executed every time
                val gitHookPreCommitFile = file("../.git/hooks/pre-commit")
                outputs.file(gitHookPreCommitFile.absolutePath)

                doLast {
                    exec {
                        // make the bash script executable
                        commandLine("chmod", "+x", "../pre-commit.sh")
                    }
                    exec {
                        // sym link it to the the pre-commit hook
                        commandLine("ln", "-s", "-f", "../../pre-commit.sh", "../.git/hooks/pre-commit")
                    }
                    exec {
                        // make the symlink executable
                        commandLine("chmod", "+x", "../.git/hooks/pre-commit")
                    }
                }
            }

            // execute every time `preBuild` runs
            tasks.getByPath(":app:preBuild").dependsOn("installPreCommitHookmai")
        }
    }
}

First, let's start with a quick overview of what coroutines are. Coroutines are a type of concurrency primitive that allow you to write asynchronous code in a synchronous style. In other words, you can write code that looks like it's running synchronously, but it's actually running asynchronously under the hood.

One of the benefits of coroutines is that they can simplify asynchronous code by eliminating the need for callbacks or promises. However, coroutines can also make stack traces more complicated because they involve multiple points of suspension and resumption. This can make it difficult to trace the path of execution through your code.

To make stack traces involving coroutines easier to understand, you can use a custom coroutine exception handler. A coroutine exception handler is a mechanism that allows you to intercept and handle exceptions that occur within coroutines. By default, when an exception is thrown in a coroutine, it will propagate up the call stack until it reaches the top-level coroutine, where it will be re-thrown as an unhandled exception. This can make it difficult to pinpoint the exact location where the exception occurred.

With a custom coroutine exception handler, you can intercept the exception as soon as it occurs and take action to handle it. This allows you to add additional context to the exception, such as the coroutine stack trace, which can make it much easier to understand what went wrong.

Here's an example of how you can use a custom coroutine exception handler with a custom exception postpended to the original exception to improve stack traces involving coroutines:

    internal fun createBreadcrumbsExceptionHandler(): CoroutineExceptionHandler {
        val breadcrumbsException = createBreadcrumbsException()

        return CoroutineExceptionHandler { _, throwable ->
            val currentThread = Thread.currentThread()
            run {
                currentThread.uncaughtExceptionHandler ?: Thread.getDefaultUncaughtExceptionHandler()
            }.uncaughtException(
                currentThread,
                throwable.addBreadcrumbs(breadcrumbsException),
            )
        }
    }

    private fun Throwable.addBreadcrumbs(
        breadcrumbsException: BreadcrumbException,
    ): Throwable {
    val capturedThrowable = this

    // create a new instance of the breadcrumb exception with the original breadcrumb message
    // but with the cause of the throwable we are adding the breadcrumb to
    val newBreadcrumbWithOriginalThrowable =
      breadcrumbsException::class
        .java
        .getDeclaredConstructor(String::class.java, Throwable::class.java)
        .newInstance(breadcrumbsException.message, capturedThrowable.cause)
        .apply { stackTrace = breadcrumbsException.stackTrace }

    // create a new instance of the original throwable but with the breadcrumb exception as the cause
    return this::class
      .java
      .getDeclaredConstructor(String::class.java, Throwable::class.java)
      .newInstance(message, newBreadcrumbWithOriginalThrowable)
      .apply { stackTrace = capturedThrowable.stackTrace }
    }

In the code above, we've declared a method for creating a custom coroutine exception handler where we add a custom BreadcrumbException to the original uncaught exception. This custom BreadcrumbException will be responsible for adding additional information to the stack trace that will better point us to the problem code in our stack trace.

The BreadcrumbException is defined as follows:

    private fun createBreadcrumbsException() =
        BreadcrumbException()
            .apply {
                val queue: Queue<StackTraceElement> = LinkedList(stackTrace.asList())

                val iterator = queue.iterator()
                while (iterator.hasNext()) {
                    val next = iterator.next()

                    // we need to remove all of the 'helper' classes from the stack trace
                    // as that really just adds noise and isn't overly helpful
                    // `CoroutinesBreadcrumbExceptionHandler` is the object containing all of the functions listed so far. `FlowExtensions` and `CoroutineScopeExtensions` will make their appearance later on. 
                    if (next.className == CoroutinesBreadcrumbExceptionHandler::class.qualifiedName ||
                        next.className == FlowExtensions::class.qualifiedName ||
                        next.className == CoroutineScopeExtensions::class.qualifiedName
                    ) {
                        iterator.remove()
                    } else {
                        break
                    }
                }
                stackTrace = queue.toTypedArray()
            }

class BreadcrumbException : RuntimeException("More details about the original stack trace:")

After defining all of the code to add our custom BreadcrumbException via a custom CoroutineExceptionHandler, how do we actually use them? The first way we can use them is by creating an extension function for launching a coroutine.

object CoroutineScopeExtensions {
    fun CoroutineScope.launchWithBreadcrumbs(
        context: CoroutineContext = EmptyCoroutineContext,
        start: CoroutineStart = CoroutineStart.DEFAULT,
        block: suspend CoroutineScope.() -> Unit,
    ): Job {
        return this.launch(
            context = context + createBreadcrumbsExceptionHandler(),
            start = start,
            block = block,
        )
    }
}

This has been a lot to setup, but what does it get us? We are going to look at some code that throws an exception and some before/after comparisons of the stack traces.

First, the code:

class MainActivity : AppCompatActivity() {
    private val viewModel : MainViewModel by viewModels()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        viewModel.testException()
    }
}

class MainViewModel : ViewModel() {

    fun testException() {
        viewModelScope.launch {
            throwException1()
        }
    }

    private suspend fun throwException1() {
        delay(300)
        throwException2()
    }

    private suspend fun throwException2() {
        delay(300)
        throwException3()
    }

    private suspend fun throwException3() {
        delay(300)
        throw IllegalArgumentException("oh no")
    }
}

The code above provides the following stack trace:

E/AndroidRuntime: FATAL EXCEPTION: main
    Process: com.joetr.coroutines, PID: 11825
    java.lang.IllegalArgumentException: oh no
        at com.joetr.coroutines.MainViewModel.throwException3(MainViewModel.kt:36)
        at com.joetr.coroutines.MainViewModel.access$throwException3(MainViewModel.kt:16)
        at com.joetr.coroutines.MainViewModel$throwException3$1.invokeSuspend(Unknown Source:14)
        at kotlin.coroutines.jvm.internal.BaseContinuationImpl.resumeWith(ContinuationImpl.kt:33)
        at kotlinx.coroutines.DispatchedTaskKt.resume(DispatchedTask.kt:234)
        at kotlinx.coroutines.DispatchedTaskKt.dispatch(DispatchedTask.kt:166)
        at kotlinx.coroutines.CancellableContinuationImpl.dispatchResume(CancellableContinuationImpl.kt:397)
        at kotlinx.coroutines.CancellableContinuationImpl.resumeImpl(CancellableContinuationImpl.kt:431)
        at kotlinx.coroutines.CancellableContinuationImpl.resumeImpl$default(CancellableContinuationImpl.kt:420)
        at kotlinx.coroutines.CancellableContinuationImpl.resumeUndispatched(CancellableContinuationImpl.kt:518)
        at kotlinx.coroutines.android.HandlerContext$scheduleResumeAfterDelay$$inlined$Runnable$1.run(Runnable.kt:19)
        at android.os.Handler.handleCallback(Handler.java:942)
        at android.os.Handler.dispatchMessage(Handler.java:99)
        at android.os.Looper.loopOnce(Looper.java:201)
        at android.os.Looper.loop(Looper.java:288)
        at android.app.ActivityThread.main(ActivityThread.java:7898)
        at java.lang.reflect.Method.invoke(Native Method)
        at com.android.internal.os.RuntimeInit$MethodAndArgsCaller.run(RuntimeInit.java:548)
        at com.android.internal.os.ZygoteInit.main(ZygoteInit.java:936)
        Suppressed: kotlinx.coroutines.DiagnosticCoroutineContextException: [StandaloneCoroutine{Cancelling}@37c4392, Dispatchers.Main.immediate]

But when we modify the code that launches the coroutine to:

    fun testException() {
        // using our custom `launchWithBreadcrumbs` method
        viewModelScope.launchWithBreadcrumbs {
            throwException1()
        }
    }

We get a stack trace with a good bit more information in it. When we examine the following stack trace, we can see references to MainActivity's onCreate and MainViewModel's testException method, which were both originally missing in the first stack trace.

E/AndroidRuntime: FATAL EXCEPTION: main
    Process: com.joetr.coroutines, PID: 12126
    java.lang.IllegalArgumentException: oh no
        at com.joetr.coroutines.MainViewModel.throwException3(MainViewModel.kt:36)
        at com.joetr.coroutines.MainViewModel.access$throwException3(MainViewModel.kt:16)
        at com.joetr.coroutines.MainViewModel$throwException3$1.invokeSuspend(Unknown Source:14)
        at kotlin.coroutines.jvm.internal.BaseContinuationImpl.resumeWith(ContinuationImpl.kt:33)
        at kotlinx.coroutines.DispatchedTaskKt.resume(DispatchedTask.kt:234)
        at kotlinx.coroutines.DispatchedTaskKt.dispatch(DispatchedTask.kt:166)
        at kotlinx.coroutines.CancellableContinuationImpl.dispatchResume(CancellableContinuationImpl.kt:397)
        at kotlinx.coroutines.CancellableContinuationImpl.resumeImpl(CancellableContinuationImpl.kt:431)
        at kotlinx.coroutines.CancellableContinuationImpl.resumeImpl$default(CancellableContinuationImpl.kt:420)
        at kotlinx.coroutines.CancellableContinuationImpl.resumeUndispatched(CancellableContinuationImpl.kt:518)
        at kotlinx.coroutines.android.HandlerContext$scheduleResumeAfterDelay$$inlined$Runnable$1.run(Runnable.kt:19)
        at android.os.Handler.handleCallback(Handler.java:942)
        at android.os.Handler.dispatchMessage(Handler.java:99)
        at android.os.Looper.loopOnce(Looper.java:201)
        at android.os.Looper.loop(Looper.java:288)
        at android.app.ActivityThread.main(ActivityThread.java:7898)
        at java.lang.reflect.Method.invoke(Native Method)
        at com.android.internal.os.RuntimeInit$MethodAndArgsCaller.run(RuntimeInit.java:548)
        at com.android.internal.os.ZygoteInit.main(ZygoteInit.java:936)
     Caused by: com.joetr.coroutines.BreadcrumbException: More details about the original stack trace:
        at com.joetr.coroutines.MainViewModel.testException(MainViewModel.kt:19)
        at com.joetr.coroutines.MainActivity.onCreate(MainActivity.kt:21)
        at android.app.Activity.performCreate(Activity.java:8290)
        at android.app.Activity.performCreate(Activity.java:8269)
        at android.app.Instrumentation.callActivityOnCreate(Instrumentation.java:1384)
        at android.app.ActivityThread.performLaunchActivity(ActivityThread.java:3657)
        at android.app.ActivityThread.handleLaunchActivity(ActivityThread.java:3813)
        at android.app.servertransaction.LaunchActivityItem.execute(LaunchActivityItem.java:101)
        at android.app.servertransaction.TransactionExecutor.executeCallbacks(TransactionExecutor.java:135)
        at android.app.servertransaction.TransactionExecutor.execute(TransactionExecutor.java:95)
        at android.app.ActivityThread$H.handleMessage(ActivityThread.java:2308)
        at android.os.Handler.dispatchMessage(Handler.java:106)
        at android.os.Looper.loopOnce(Looper.java:201) 
        at android.os.Looper.loop(Looper.java:288) 
        at android.app.ActivityThread.main(ActivityThread.java:7898) 
        at java.lang.reflect.Method.invoke(Native Method) 
        at com.android.internal.os.RuntimeInit$MethodAndArgsCaller.run(RuntimeInit.java:548) 
        at com.android.internal.os.ZygoteInit.main(ZygoteInit.java:936)

StateFlow

A common pattern in the Android world is to expose the state of your feature from your ViewModel to be collected in your Fragment / Activity. The second way we can use our custom exception handler is via an extension on the stateIn function provided via the Coroutines package.

object FlowExtensions {
    fun <T> Flow<T>.stateInWithBreadcrumbs(
        scope: CoroutineScope,
        started: SharingStarted,
        initialValue: T,
    ): StateFlow<T> {
        return stateIn(
            scope = scope + createBreadcrumbsExceptionHandler(),
            started = started,
            initialValue = initialValue,
        )
    }
}

When we use the standard stateIn method, there is a lot to be desired about the stack trace.

class MainViewModel : ViewModel() {
    val state = flow<String> {
        throw IllegalArgumentException("oh no")
    }.stateIn(
        scope = viewModelScope,
        started = SharingStarted.Eagerly,
        initialValue = "",
    )
}

class MainActivity : AppCompatActivity() {
    private val viewModel : MainViewModel by viewModels()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        lifecycleScope.launch {
            viewModel.state.collect {
                Log.d("MainActivity", it)
            }
        }
    }
}

The code above provides the following stack trace:

E/AndroidRuntime: FATAL EXCEPTION: main
    Process: com.joetr.coroutines, PID: 12872
    java.lang.IllegalArgumentException: oh no
        at com.joetr.coroutines.MainViewModel$state$1.invokeSuspend(MainViewModel.kt:19)
        at com.joetr.coroutines.MainViewModel$state$1.invoke(Unknown Source:8)
        at com.joetr.coroutines.MainViewModel$state$1.invoke(Unknown Source:4)
        at kotlinx.coroutines.flow.SafeFlow.collectSafely(Builders.kt:61)
        at kotlinx.coroutines.flow.AbstractFlow.collect(Flow.kt:230)
        at kotlinx.coroutines.flow.FlowKt__ShareKt$launchSharing$1.invokeSuspend(Share.kt:214)
        at kotlin.coroutines.jvm.internal.BaseContinuationImpl.resumeWith(ContinuationImpl.kt:33)
        at kotlinx.coroutines.DispatchedTask.run(DispatchedTask.kt:106)
        at kotlinx.coroutines.EventLoop.processUnconfinedEvent(EventLoop.common.kt:69)
        at kotlinx.coroutines.internal.DispatchedContinuationKt.resumeCancellableWith(DispatchedContinuation.kt:376)
        at kotlinx.coroutines.intrinsics.CancellableKt.startCoroutineCancellable(Cancellable.kt:30)
        at kotlinx.coroutines.intrinsics.CancellableKt.startCoroutineCancellable$default(Cancellable.kt:25)
        at kotlinx.coroutines.CoroutineStart.invoke(CoroutineStart.kt:110)
        at kotlinx.coroutines.AbstractCoroutine.start(AbstractCoroutine.kt:126)
        at kotlinx.coroutines.BuildersKt__Builders_commonKt.launch(Builders.common.kt:56)
        at kotlinx.coroutines.BuildersKt.launch(Unknown Source:1)
        at kotlinx.coroutines.BuildersKt__Builders_commonKt.launch$default(Builders.common.kt:47)
        at kotlinx.coroutines.BuildersKt.launch$default(Unknown Source:1)
        at com.joetr.coroutines.MainActivity.onCreate(MainActivity.kt:22)
        at android.app.Activity.performCreate(Activity.java:8290)
        at android.app.Activity.performCreate(Activity.java:8269)
        at android.app.Instrumentation.callActivityOnCreate(Instrumentation.java:1384)
        at android.app.ActivityThread.performLaunchActivity(ActivityThread.java:3657)
        at android.app.ActivityThread.handleLaunchActivity(ActivityThread.java:3813)
        at android.app.servertransaction.LaunchActivityItem.execute(LaunchActivityItem.java:101)
        at android.app.servertransaction.TransactionExecutor.executeCallbacks(TransactionExecutor.java:135)
        at android.app.servertransaction.TransactionExecutor.execute(TransactionExecutor.java:95)
        at android.app.ActivityThread$H.handleMessage(ActivityThread.java:2308)
        at android.os.Handler.dispatchMessage(Handler.java:106)
        at android.os.Looper.loopOnce(Looper.java:201)
        at android.os.Looper.loop(Looper.java:288)
        at android.app.ActivityThread.main(ActivityThread.java:7898)
        at java.lang.reflect.Method.invoke(Native Method)
        at com.android.internal.os.RuntimeInit$MethodAndArgsCaller.run(RuntimeInit.java:548)
        at com.android.internal.os.ZygoteInit.main(ZygoteInit.java:936)
        Suppressed: kotlinx.coroutines.DiagnosticCoroutineContextException: [StandaloneCoroutine{Cancelling}@a43f471, Dispatchers.Main.immediate]

When we use our custom stateInWithBreadcrumb function, we can see that we again get some more information in our stack trace.

FATAL EXCEPTION: main                                                                              Process: com.joetr.dynamicproxies, PID: 13069                                                                               java.lang.IllegalArgumentException: oh no
    at com.joetr.coroutines.MainViewModel$state$1.invokeSuspend(MainViewModel.kt:19)
    at com.joetr.coroutines.MainViewModel$state$1.invoke(Unknown Source:8)
    at com.joetr.coroutines.MainViewModel$state$1.invoke(Unknown Source:4)
    at kotlinx.coroutines.flow.SafeFlow.collectSafely(Builders.kt:61)
    at kotlinx.coroutines.flow.AbstractFlow.collect(Flow.kt:230)
    at kotlinx.coroutines.flow.FlowKt__ShareKt$launchSharing$1.invokeSuspend(Share.kt:214)
    at kotlin.coroutines.jvm.internal.BaseContinuationImpl.resumeWith(ContinuationImpl.kt:33)
    at kotlinx.coroutines.DispatchedTask.run(DispatchedTask.kt:106)
    at kotlinx.coroutines.EventLoop.processUnconfinedEvent(EventLoop.common.kt:69)
    at kotlinx.coroutines.internal.DispatchedContinuationKt.resumeCancellableWith(DispatchedContinuation.kt:376)
    at kotlinx.coroutines.intrinsics.CancellableKt.startCoroutineCancellable(Cancellable.kt:30)
    at kotlinx.coroutines.intrinsics.CancellableKt.startCoroutineCancellable$default(Cancellable.kt:25)
    at kotlinx.coroutines.CoroutineStart.invoke(CoroutineStart.kt:110)
    at kotlinx.coroutines.AbstractCoroutine.start(AbstractCoroutine.kt:126)
    at kotlinx.coroutines.BuildersKt__Builders_commonKt.launch(Builders.common.kt:56)
    at kotlinx.coroutines.BuildersKt.launch(Unknown Source:1)
    at kotlinx.coroutines.BuildersKt__Builders_commonKt.launch$default(Builders.common.kt:47)
    at kotlinx.coroutines.BuildersKt.launch$default(Unknown Source:1)
    at com.joetr.coroutines.MainActivity.onCreate(MainActivity.kt:22)
    at android.app.Activity.performCreate(Activity.java:8290)
    at android.app.Activity.performCreate(Activity.java:8269)
    at android.app.Instrumentation.callActivityOnCreate(Instrumentation.java:1384)
    at android.app.ActivityThread.performLaunchActivity(ActivityThread.java:3657)
    at android.app.ActivityThread.handleLaunchActivity(ActivityThread.java:3813)
    at android.app.servertransaction.LaunchActivityItem.execute(LaunchActivityItem.java:101)
    at android.app.servertransaction.TransactionExecutor.executeCallbacks(TransactionExecutor.java:135)
    at android.app.servertransaction.TransactionExecutor.execute(TransactionExecutor.java:95)
    at android.app.ActivityThread$H.handleMessage(ActivityThread.java:2308)
    at android.os.Handler.dispatchMessage(Handler.java:106)
    at android.os.Looper.loopOnce(Looper.java:201)
    at android.os.Looper.loop(Looper.java:288)
    at android.app.ActivityThread.main(ActivityThread.java:7898)
    at java.lang.reflect.Method.invoke(Native Method)
    at com.android.internal.os.RuntimeInit$MethodAndArgsCaller.run(RuntimeInit.java:548)
    at com.android.internal.os.ZygoteInit.main(ZygoteInit.java:936)
Caused by: com.joetr.coroutines.BreadcrumbException: More details about the original stack trace:
    at com.joetr.coroutines.MainViewModel.<init>(MainViewModel.kt:20)
    at java.lang.reflect.Constructor.newInstance0(Native Method)
    at java.lang.reflect.Constructor.newInstance(Constructor.java:343)
    at androidx.lifecycle.ViewModelProvider$NewInstanceFactory.create(ViewModelProvider.kt:202)
    at androidx.lifecycle.ViewModelProvider$AndroidViewModelFactory.create(ViewModelProvider.kt:324)
    at androidx.lifecycle.ViewModelProvider$AndroidViewModelFactory.create(ViewModelProvider.kt:306)
    at androidx.lifecycle.ViewModelProvider$AndroidViewModelFactory.create(ViewModelProvider.kt:280)
    at androidx.lifecycle.SavedStateViewModelFactory.create(SavedStateViewModelFactory.kt:128)
    at dagger.hilt.android.internal.lifecycle.HiltViewModelFactory.create(HiltViewModelFactory.java:118)
    at androidx.lifecycle.ViewModelProvider.get(ViewModelProvider.kt:187)
    at androidx.lifecycle.ViewModelProvider.get(ViewModelProvider.kt:153)
    at androidx.lifecycle.ViewModelLazy.getValue(ViewModelLazy.kt:53)
    at androidx.lifecycle.ViewModelLazy.getValue(ViewModelLazy.kt:35)
    at com.joetr.coroutines.MainActivity.getViewModel(MainActivity.kt:16)
2023-04-09 19:37:10.303 13069-13069 AndroidRuntime          com.joetr.dynamicproxies             E      at com.joetr.coroutines.MainActivity.access$getViewModel(MainActivity.kt:14)
    at com.joetr.coroutines.MainActivity$onCreate$1.invokeSuspend(MainActivity.kt:23)
    at kotlin.coroutines.jvm.internal.BaseContinuationImpl.resumeWith(ContinuationImpl.kt:33)
    at kotlinx.coroutines.internal.DispatchedContinuationKt.resumeCancellableWith(DispatchedContinuation.kt:367)
                                                                                                        ... 25 more

By using a custom coroutine exception handler, we can improve the readability of stack traces involving coroutines. This allows us to quickly and easily identify the location of the exception and the path of execution leading up to it.

In conclusion, coroutines can make stack traces more complicated, but with the right approach, you can make them much easier to understand. By using a custom coroutine exception handler, you can intercept exceptions as soon as they occur and add additional context to the exception, such as the coroutine stack trace. This can make it much easier to identify the location of the exception and the path of execution leading up to it.

Gist with all relevant code can be found here.

One of the challenges of working with coroutines in Android is how to properly manage their lifecycle in a testable way. One popular approach is to use the ViewModelScope, which is a lifecycle-aware scope that automatically cancels all coroutines when the associated ViewModel is destroyed. However, using ViewModelScope can make it difficult to test coroutine code in isolation because the coroutines are tightly coupled to the lifecycle of the ViewModel and the ViewModelScope isn't aware about the structured concurrency within your runTest block (from the coroutines-test package).

In this blog post, we'll discuss why replacing ViewModelScope within AAC ViewModels with a custom solution may be a good idea, and how you can implement a better solution that allows for better testing of coroutine code (which also allows us to move away from having to set Dispatchers.setMain().

The Problem with ViewModelScope

When you use ViewModelScope to launch a coroutine, the coroutine is automatically tied to the lifecycle of the ViewModel. This means that if the ViewModel is destroyed, all running coroutines are canceled. While this behavior is useful in many cases, it can also make it difficult to test coroutine code in isolation. Additionally, the ViewModelScope isn't aware of the structured concurrency that exists within your runTest block, which can make it difficult to define the behavior we want for testing coroutines.

A Custom Solution

The solution we will be striving towards today involves using the ViewModelScope via Hilt in production code, and using the backgroundScope provided to us via TestScope.

The first thing we need to do is create the CoroutineScope we will be providing via Hilt to use in our ViewModel. This CloseableCoroutineScope's Job still needs to be canceled when the ViewModelScope is cleared, which is why we cancel it in onCleared()

class CloseableCoroutineScope(context: CoroutineContext) : CoroutineScope, RetainedLifecycle.OnClearedListener {
    override val coroutineContext: CoroutineContext = context

    override fun onCleared() {
        coroutineContext.cancel()
    }
}

Then, via our Hilt module, we can provide this scope in the ViewModelComponent. It is important to note, that we are also calling addOnClearedListener here, so the scope is canceled within the ViewModelLifecycle

@Module
@InstallIn(ViewModelComponent::class)
internal object ViewModelScopeModule {
    @Provides
    @ViewModelScoped
    fun provideViewModelCoroutineScope(lifecycle: ViewModelLifecycle): CoroutineScope {
        return CloseableCoroutineScope(SupervisorJob()).also { closeableCoroutineScope ->
            lifecycle.addOnClearedListener(closeableCoroutineScope)
        }
    }
}

Testing

Now that we have the basic setup in place, we can finally use it! First, we will create a ViewModel that takes in our new scope.

@HiltViewModel
class MainViewModel @Inject constructor(
    private val scope: CoroutineScope,
) : ViewModel()

Then, when we want to use that scope, we can do so via:

@HiltViewModel
class MainViewModel @Inject constructor(
    private val scope: CoroutineScope,
    private val apiService: ApiService,
) : ViewModel() {

    private val _result = MutableSharedFlow<Int>()
    val result = _result.asSharedFlow()

    fun getResult() {
        scope.launch {
            _result.emit(apiService.getResult())
        }
    }
}

The testing of this is really the impetus behind why we want to avoid ViewModelScope. Now that we are no longer using ViewModelScope, our testing setup becomes simpler. In this example, I am using Turbine for testing.

class MainViewModelTest {

    private val fakeApiService = object : ApiService {
        override suspend fun getResult() = 42
    }

    @Test
    fun `result is emitted after fetching`() {
        runTest {
            val viewModel = MainViewModel(
                scope = this.backgroundScope,
                apiService = fakeApiService,
            )

            viewModel.result.test {
                viewModel.getResult()
                assertEquals(42, awaitItem())
            }
        }
    }
}

From this sample code, we can see that we didn't have to set the main dispatcher anywhere, and we were able to use the backgroundScope provided via TestScope in our ViewModel.

Let's now compare this test code to what we would have to write if we instead used viewModelScope to launch the coroutine in the ViewModel.

fun getResult() {
        viewModelScope.launch {
            _result.emit(apiService.getResult())
        }
    }

Unfortunately, when we run our test now, we get an error. Referring to the docs, we can see "If your code under test references the main thread, it’ll throw an exception during unit tests.". To get around this, we can create a JUnit Test Rule to automatically set the main dispatcher.

class MainDispatcherRule(
    private val testDispatcher: TestDispatcher = UnconfinedTestDispatcher(),
) : TestWatcher() {
    override fun starting(description: Description) {
        Dispatchers.setMain(testDispatcher)
    }

    override fun finished(description: Description) {
        Dispatchers.resetMain()
    }
}

This test rule can now be used to get our tests to pass as expected

class MainViewModelTest {

    @get:Rule
    val mainDispatcherRule = MainDispatcherRule()

    private val fakeApiService = object : ApiService {
        override suspend fun getResult() = 42
    }

    @Test
    fun `result is emitted after fetching`() {
        runTest {
            val viewModel = MainViewModel(
                scope = this.backgroundScope,
                apiService = fakeApiService,
            )

            viewModel.result.test {
                viewModel.getResult()
                assertEquals(42, awaitItem())
            }
        }
    }
}

class MainDispatcherRule(
    private val testDispatcher: TestDispatcher = UnconfinedTestDispatcher(),
) : TestWatcher() {
    override fun starting(description: Description) {
        Dispatchers.setMain(testDispatcher)
    }

    override fun finished(description: Description) {
        Dispatchers.resetMain()
    }
}

While we were still able to get a working solution by setting the main dispatcher, that is ultimately an undesirable workaround because for everything to play together nicely, we'd have to pass the TestDispatcher around for anything that wanted to know about it so that the structured concurrency in our runTest block will play nicely.

Conclusion

Using ViewModelScope to launch coroutines can be convenient, but it can also make it difficult to test coroutine code in isolation. By creating a custom scope that's decoupled from the lifecycle of the `ViewModel`, as well as that's managed in isolation in your test, you can launch coroutines in a way that's more testable and easier to manage.

In this blog post, we discussed how to create a custom scope and use it in a ViewModel to launch coroutines. We also showed how to write a unit test for coroutine code that uses a custom scope.

Looking at the docs, there was no reference to what the schemes were, so I thought I'd do a little digging myself to see if I could infer what the value was for this field.

Setup

The first step of the process was to create a new Android application that include the dependency I wanted to look at, namely BrazeFileUtils. This can be accomplished by bringing the Braze SDK into our application via

    implementation 'com.appboy:android-sdk-ui:24.3.0'
    implementation 'com.appboy:android-sdk-location:24.3.0'

After that, I generated a debuggable apk via ./gradlew :app:assembleDebug. Once I had a debug APK in hand, the next tool I brought in to help was Apktool, a tool for reverse engineering Android apk files.

Decompiling

1. By following the instructions on the site, and downloading the latest Apktool JAR file, we are ready to decompile the debug APK we generated earlier. I decompiled the apk via java -jar apktool.jar d app-debug.apk where apktool.jar is the jar downloaded from the Apktool website and app-debug.apk is the debug APK generated from the previous step.

2. After decompilng via Apktool, we are ultimately left with .smali files, the assembly language used by the Android Dalvik Virtual Machine; usually created by decompiling. We are getting close though! If we open up the new app-debug folder created from Apktool, we can look inside /smali/com/braze/support/BrazeFileUtils.smali and see the field we want! Unfortunately, we don't see the values for it yet.

1. The next step is to use a Dex (Smali) to Java decompiler to get the code in a format a little more digestible by a human. For this, we will use jadx. Following the instructions in the readme, and installing jadx via brew (brew install jadx), we are ready for the next step.

2. After installing jadx, we can finally get the Java code from the .smali files generated earlier via jadx -d out app-debug/smali/com/braze/support/BrazeFileUtils.smali. Usage is from the docs on the site as follows:

    jadx[-gui] [options] <input files> (.apk, .dex, .jar, .class, .smali, .zip, .aar, .arsc, .aab)
    options:
      -d, --output-dir                    - output directory
   

After opening up the Java file, we can finally see what the remote schemes are!

In conclusion, we utilized Apktool and jadx to reverse engineer source from a debug apk. This can be useful when a 3rd party tool that you have to utilize doesn't expose certain things about their SDK.