Navigation 3 is the next major release of the navigation library for Jetpack Compose, providing an API that has been redesigned from the ground up to be more flexible and open.

Typically, in both Navigation 3 and its older version (which I’ll refer to as Navigation 2), destinations are declared statically. This means all possible destinations must be specified upfront, at the moment their respective navigation container — NavDisplay in Navigation 3 or NavHost in Navigation 2—is used in code.

But what if you don’t know in advance what navigation destinations your app will have? While this is a less common use case, sometimes destinations will be known only at the moment the actual navigation happens. In this case, we need the ability to register destinations dynamically, outside of the navigation graph declaration.

In Navigation 2, there was no easy way to accomplish this. Its relatively closed and inflexible API required to make complex workarounds (e.g. 1, 2) to implement saveable dynamic destinations. In contrast, Navigation 3 offers a more open and adaptable API, making it well-suited for custom use cases that were not necessarily foreseen by its creators.

All the source code in this blog post could be found in compose-nav3-dynamic-sample GitHub repository.

Static destinations

First, let’s look at a basic example of declaring navigation destinations statically within the NavDisplay composable, as intended by the creators of Navigation 3.

Let’s start by declaring a data class for each destination in the navigation graph (e.g. an app screen). They will also serve as containers for the arguments of each destination.

@Serializable
data object DestinationA : NavKey

@Serializable
data class DestinationB(val number: Int) : NavKey

@Serializable
data class DestinationC(val number: Int) : NavKey

Next, build a navigation graph using Navigation 3 API.

// --(1)--
val backStack = rememberNavBackStack(DestinationA)

// --(2)--
NavDisplay(
  backStack = backStack,
  onBack = { backStack.removeLastOrNull() },
  // --(3)--
  entryProvider = { key ->
    when (key) {
      is DestinationA -> NavEntry(key) {
        ScreenA(onNextClick = { backStack.add(DestinationB(...)) })
      }
      is DestinationB -> NavEntry(key) {
        ScreenB(...)
      }
      is DestinationC -> NavEntry(key) {
        ScreenC(...)
      }
      else -> error("Unknown route: $key")
    }
  }
)

1. Create an instance of a back stack.
2. Use NavDisplay composable to build a navigation graph.
3. Inside the entryProvider, declare all the possible destinations the user might navigate to.

Dynamic destinations

Now, back to the topic of this blog post. Below is the example of how to use dynamic destinations with Navigation 3.

// --(1)--
val backStack = rememberDynamicNavBackStack(DestinationA)

NavDisplay(
  backStack = backStack,
  modifier = modifier,
  onBack = { backStack.removeLastOrNull() },
  entryProvider = { key ->
    when (key) {
      // --(2)--
      DestinationA -> ScreenAEntry().value(backStack)
      else -> {
        // --(3)--
        val entry = backStack.dynamicEntries[key]
        entry?.value(backStack) ?: error("Unknown route: $key")
      }
    }
  }
)

1. Create an instance of a DynamicNavBackStack that can handle destinations added dynamically. It is a custom component and we will look into its implementation later.
2. We still need to declare one destination statically, so that NavDisplay knows what screen to display first. You may notice that here instead of a generic NavEntry we’re using a specific ScreenAEntry. We will cover it later.
3. The rest of the destinations are extracted dynamically from the back stack instance.

A key difference with dynamic destinations here is that they need to be wrapped with a custom entry implementation rather than a generic NavEntry. This is needed to make sure the destinations added dynamically can survive configuration changes. Because these destinations are not declared inside NavDisplay, when the UI is being recreated, it would not know where to find all the composables added dynamically.

// --(1)--
@Serializable
class ScreenBEntry(
  // --(2)--
  override val key: DestinationB
) : DynamicNavEntry {

  // --(3)--
  override fun value(backStack: DynamicNavBackStack) = NavEntry<NavKey>(
    key = key,
    content = {
      ScreenB(
        number = key.number,
        onNext = {
          val screenCKey = DestinationC(number = key.number + 1)
          // --(4)--
          if (screenCKey !in backStack.dynamicEntries) {
            backStack.newEntry(ScreenCEntry(screenCKey))
          }
          // --(5)--
          backStack += screenCKey
        }
      )
    }
  )
}

1. As mentioned above, we’re creating an entry class the main purpose of which is to serve as an entry point to the composable UI of the corresponding navigation destination.
2. We map this entry class to the NavKey type that represents the destination and holds its arguments.
3. Each entry implements a function that contains the composable UI code of the destination and wraps it in a NavEntry instance to be supplied to a NavDisplay.
4. If this destination is not registered yet — we do that using a newEntry call.
5. Navigate to the next screen by appending its navigation key to the back stack.

You may have noticed the ScreenBEntry implements DynamicNavEntry interface. Here is how its declaration looks like.

interface DynamicNavEntry {
  val key: NavKey
  fun value(backStack: DynamicNavBackStack): NavEntry<NavKey>
}

Finally, let’s have a closer look at the DynamicNavBackStack implementation.

// --(1)--
class DynamicNavBackStack(
  private val internalBackStack: NavBackStack,
  private val entries: MutableMap<NavKey, DynamicNavEntry> = mutableMapOf()
) : MutableList<NavKey> by internalBackStack {

  // --(2)--
  val dynamicEntries: Map<NavKey, DynamicNavEntry>
    get() = entries

  // --(3)--
  fun newEntry(entry: DynamicNavEntry) {
    entries[entry.key] = entry
  }
}

1. The DynamicNavBackStack type actually implements MutableList interface and we’re delegating the implementation to the original NavBackStack provided by Navigation 3 as we don’t need much customization here.
2. We expose all the dynamically added destinations (or navigation entries which is the same in this context).
3. The newEntry call is what allows us to dynamically register navigation destinations.

All that’s left is to make sure the DynamicNavBackStack is saveable, so it can survive configuration changes.

// --(1)--
@Composable
fun <T : NavKey> rememberDynamicNavBackStack(
  vararg elements: T
): DynamicNavBackStack {
  val backStack = rememberNavBackStack(*elements)
  return rememberSaveable(saver = DynamicNavBackStackSaver(backStack)) {
    DynamicNavBackStack(backStack)
  }
}

// --(2)--
fun DynamicNavBackStackSaver(
  internalBackStack: NavBackStack
): Saver<DynamicNavBackStack, *> = Saver(
  save = { it.dynamicEntries.toMutableMap() },
  restore = { DynamicNavBackStack(internalBackStack, it) },
)

1. We create a simple remember function that helps to instantiate a DynamicNavBackStack.
2. Implement a Saver to make sure all destinations we added dynamically could survive configuration changes. That is why all the custom entry classes must be @Serializable as we’ve seen earlier.

Why dynamic destinations?

The official documentation and samples for Navigation 2 and Navigation 3 demonstrate only statically declared destinations. While in most cases this would work just fine, there are scenarios where this won’t be sufficient.

To make this more specific, I’ll use an example from a project I worked on some time ago. The goal was to adopt Jetpack Compose in an application that relied heavily on Fragments, which required a seamless migration path. You can learn more about it in this and this blog posts.

For that project, a navigation framework was built to serve as an abstraction layer. Under the hood, it automatically decided whether to use Fragment Transactions or Compose Navigation, depending on the destination screen type. The key was that the Compose Navigation API was never exposed to developers. It was treated as an implementation detail so that it could always be replaced with another solution for navigating between composables in the future.

In more general terms, dynamic destinations are ideal for situations where you want to avoid or limit a direct dependency on the Navigation library’s API. This approach allows you to build an abstraction layer, leveraging the library’s power “under the hood” while controlling how its API is exposed — either by hiding it completely as an implementation detail or by carefully limiting its direct use.

Sample app

The complete source code from this blog post is available in a sample Android app project on GitHub.

GitHub - Morfly/compose-nav3-dynamic-sample

References

• Announcing Jetpack Navigation 3 — android-developers.googleblog.com
• android/nav3-recipes — github.com
• Designing Jetpack Compose architecture for a gradual transition from fragments on Android — medium.com
• Introducing Nibel: A Navigation Library for Adopting Jetpack Compose in Fragment-Based Apps — medium.com

To resize or not to resize…

Maps and bottom sheets are a popular combination in Android apps because they work well together. Maps show you where things are, and bottom sheets give you extra details about those places. This saves screen space while keeping the map easy to see. Users can quickly switch between seeing the big picture on the map and getting more information from the bottom sheet.

When implementing a map and bottom sheet combination, there are a few considerations to keep in mind.

• Map controls position. Ensure map UI controls (e.g. zoom buttons, Google logo, etc) move along with the bottom sheet to prevent them from being covered.
• Map camera position. Adjust the camera focus when the map’s visible center changes due to bottom sheet movement. This ensures the previous center point remains centered after the bottom sheet’s state changes.

You might be wondering how to implement this functionality. Should the map be resized alongside the bottom sheet, as the title suggests, or is there a more efficient approach?

In a previous blog post, I detailed a custom bottom sheet implementation and how it overcomes limitations found in the official Material 3 version. At Turo, we utilize this enhanced bottom sheet to streamline the parking location experience for both hosts and guests at airport locations.

In this story, I’ll focus on the specifics of implementing interactions between maps and bottom sheets, particularly focusing on Google Maps.

You can find the sample source code in the advanced-bottomsheet-compose repository on GitHub.

Map controls position

When the bottom sheet moves and changes state, it’s crucial to adjust the Google Map’s UI overlay components (e.g., zoom buttons, Google logo) to prevent them from being obscured. This ensures compliance with Google Maps’ terms of service, which require the logo to remain visible. In the demo above, the Google logo is part of the map, so it moves along with the rest of the map content.

Let’s explore how to implement this behavior in practice. First, I’ll demonstrate how to achieve this using the standard Material 3 bottom sheet. Then, you’ll see a simpler approach using the advanced bottom sheet I described in the previous blog post.

Original Material 3 bottom sheet

Let’s start with the Material 3 bottom sheet. First, initialize SheetState and BottomSheetScaffoldState.

val sheetState = rememberStandardBottomSheetState(
  initialValue = SheetValue.PartiallyExpanded
)
val scaffoldState = rememberBottomSheetScaffoldState(sheetState)

Then create a composable hierarchy including BottomSheetScaffold and GoogleMap.

val density = LocalDensity.current

// --(1)--
BoxWithConstraints {
  val layoutHeightPx = constraints.maxHeight

  // --(2)--
  val sheetHeight by remember(layoutHeightPx) {
    derivedStateOf {
      val sheetVisibleHeightPx = layoutHeightPx - sheetState.requireOffset()
      with(density) { sheetVisibleHeightPx.roundToInt().toDp() }
    }
  }

  // --(3)--
  val paddingValues by remember {
    derivedStateOf { PaddingValues(bottom = sheetHeight) }
  }

  BottomSheetScaffold(
    scaffoldState = scaffoldState,
    sheetContent = {
      BottomSheetContent()
    },
    content = {
      val camera = rememberCameraPositionState {
        position = CameraPosition.fromLatLngZoom(LatLng(...), 13f)
      }
      // --(4)--
      GoogleMap(
        modifier = modifier.fillMaxSize(),
        cameraPositionState = camera,
        contentPadding = paddingValues
      )
    }
  )
}

1. We wrap everything with BoxWithConstraints so that we can measure the layout height of a screen.
2. Now for the crucial part — calculating the visible height of the bottom sheet. By wrapping this calculation in derivedStateOf, the value will update in real-time whenever the bottom sheet's offset changes.
3. To prevent the bottom sheet from covering the map UI controls, we need to add padding to the bottom of the map equal to the visible height of the bottom sheet. We achieve this by wrapping the calculated height value within PaddingValues, which is the required format for the GoogleMap composable.
4. Lastly, apply the calculated bottom padding to the GoogleMap composable using its contentPadding parameter.

In the image on the right, the bottom sheet is invisible for better demonstration purposes. Notice that when padding is applied to a GoogleMap, it affects only the UI overlay, not the entire map view. This is beneficial for performance, as the padding frequently changes during bottom sheet dragging. By repositioning only the UI overlay, we avoid the costly operation of resizing the entire map.

Advanced bottom sheet

In the previous blog post, you’ll find an advanced bottom sheet implementation that offers a more flexible API and overcomes the limitations of the original Material 3 bottom sheet. It also simplifies the retrieval of the visible height.

To begin, initialize both a BottomSheetState and a BottomSheetScaffoldState.

enum class SheetValue { PartiallyExpanded, Expanded }

val sheetState = rememberBottomSheetState(
  initialValue = SheetValue.PartiallyExpanded,
  defineValues = {
    SheetValue.Collapsed at height(100.dp)
    SheetValue.PartiallyExpanded at offset(percent = 60)
  }
)
val scaffoldState = rememberBottomSheetScaffoldState(sheetState)

In this case, you can directly retrieve requireSheetVisibleHeightDp from the BottomSheetState instead of using BoxWithConstraints.

// --(1)--
val sheetHeight by remember {
  derivedStateOf { sheetState.requireSheetVisibleHeightDp() }
}

// --(2)--
val paddingValues by remember {
  derivedStateOf { PaddingValues(bottom = sheetHeight) }
}

BottomSheetScaffold(
  scaffoldState = scaffoldState,
  sheetContent = {
    BottomSheetContent()
  },
  content = {
    val camera = rememberCameraPositionState {
      position = CameraPosition.fromLatLngZoom(LatLng(...), 13f)
    }
    // --(3)--
    GoogleMap(
      modifier = modifier.fillMaxSize(),
      cameraPositionState = camera,
      contentPadding = paddingValues
    )
  }
)

1. Unlike the original Material 3 bottom sheet, you can directly obtain the visible height from the BottomSheetState. Wrapping this value in derivedStateOf ensures that sheetHeight stays updated as the bottom sheet is dragged.
2. Next, we encapsulate the calculated bottom padding value within PaddingValues, which is the required format for the GoogleMap composable.
3. Lastly, we apply the calculated bottom padding to the GoogleMap composable.

Map camera position

Another feature you might want to implement is automatically refocusing the map’s camera to the center after the bottom sheet is dragged. Here is how it looks.

We’ll build upon the code from the previous section, omitting a few details for brevity. Assume these omitted parts are implemented exactly as described earlier.

val sheetState = ...
val scaffoldState = ...
val paddingValues = ...

// --(1)--
val isBottomSheetMoving by remember {
  derivedStateOf { sheetState.currentValue != sheetState.targetValue }
}

BottomSheetScaffold(
  scaffoldState = scaffoldState,
  sheetContent = {
    BottomSheetContent()
  },
  content = {
    // --(2)--
    val camera = rememberCameraPositionState {
      position = CameraPosition.fromLatLngZoom(LatLng(...), 13f)
    }

    // --(3)--
    AdjustedCameraPositionEffect(
        camera = camera,
        isBottomSheetMoving = isBottomSheetMoving,
        bottomPadding = paddingValues.calculateBottomPadding(),
    )

    GoogleMap(
      modifier = modifier.fillMaxSize(),
      cameraPositionState = camera,
      contentPadding = paddingValues
    )
  }
)

1. To determine if the bottom sheet is currently being dragged, we can compare its target state with its current state. If they differ, it indicates that the bottom sheet is in motion. Utilizing derivedStateOf guarantees real-time updates of this value, allowing us to track the bottom sheet's movement accurately
2. Next, initialize a CameraPositionState instance to adjust the camera focus later.
3. Finally, let’s dive into the core logic. The AdjustedCameraPositionEffect is a custom composable created for demonstration purposes, and its code will be explained further in this post.

The CameraPositionState instance relies on a target location that is at the center of the camera view. When you update the bottom padding of the map, the CameraPositionState will adjust to the new location as if the bottom part of the map does not exist. Because this new location is shifted due to the bottom sheet movement, we need to revert to the previous target location.

Therefore, the core idea behind the camera updates is simple. Before the bottom sheet starts moving, we check the camera’s target location. Once the bottom sheet has finished moving, we update the camera back to the previous location, restoring the original center.

@Composable
fun AdjustedCameraPositionEffect(
  camera: CameraPositionState,
  isBottomSheetMoving: Boolean,
  bottomPadding: Dp,
) {
  val density = LocalDensity.current

  // --(1)--
  var cameraLocation by remember { mutableStateOf(camera.position.target) }
  LaunchedEffect(camera.isMoving, camera.cameraMoveStartedReason) {
    if (!camera.isMoving && camera.cameraMoveStartedReason == CameraMoveStartedReason.GESTURE) {
      cameraLocation = camera.position.target
    }
  }

  // --(2)--
  var isCameraInitialized by remember { mutableStateOf(false) }
  LaunchedEffect(isBottomSheetMoving) {
    if (isBottomSheetMoving) return@LaunchedEffect

    if (!isCameraInitialized) {
      // --(3)--
      isCameraInitialized = true
      val verticalShiftPx = with(density) { bottomPadding.toPx() / 2 }
      val update = CameraUpdateFactory.scrollBy(0f, verticalShiftPx)
      camera.animate(update)
    } else {
      // --(4)--
      val update = CameraUpdateFactory.newLatLng(cameraLocation)
      camera.animate(update)
    }
  }
}

1. This precondition ensures we track the latest location on the map, which may have been changed by the user’s manual gestures. This is independent of any bottom sheet movement and simply helps the camera stay updated with the user’s chosen focus point.
2. This is the main block containing the logic. Every time the bottom sheet stops moving, we execute the camera adjustment logic detailed below.
3. First, we need to consider a workaround for a specific case when the GoogleMap composable is being initialized. At this stage, the camera focus will be set as if there is no bottom padding, even if you set it. To address this, we need to manually adjust the camera to account for the padding and ensure the target location is correctly positioned.
4. Finally, for the general case. After the bottom sheet moves, we animate the camera back to the last target location from before the bottom sheet started moving.

You can refer to the illustration for a visual representation of what was described above.

On a side note, if you know the height of the smallest bottom sheet state, you can set it as a static minimum bottom padding for the entire GoogleMap composable. This is represented with a blue dashed line in the diagram and helps to avoid stretching the map into areas of the screen that will never be visible to the user.

You can check the source code with full samples in the advanced-bottomsheet-compose repository on GitHub.

Adjusting Compose Google Map While Bottom Sheet Moves was originally published in Turo Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

Using AnchoredDraggable and SubcomposeLayout

Turo empowers users to rent cars for a wide variety of trips, from quick weekend getaways to epic cross-country adventures. Among such diverse journeys, those that originate at airport locations are particularly significant, representing approximately 36% of Turo’s total trip revenue.

Given the significant impact of airport trips, Turo has launched a major initiative to streamline airport pickups and returns, with a focus on enhancing the experience to make every step of the process seamless and stress-free. The feature is coming soon, so stay tuned for updates!

In the redesigned airport trip experience, bottom sheets play a crucial role in guiding Turo guests and hosts through the parking process. Although Google offers a Material 3 bottom sheet implementation for Jetpack Compose on Android, we encountered limitations that prevented us from fully realizing our design vision.

• More than 2 expanded states. We needed 3 expanded states which is not supported by the original bottom sheet implementation as it offers a maximum of 2.
• Dynamic state changes. We need to be able to dynamically change the number of bottom sheet states and their height while it is being used.

In this blog post, I’ll demonstrate a custom bottom sheet built for Compose. While leveraging the foundation of the original Material 3 implementation, it enhances functionality and flexibility, addressing the constraints above. We’ll explore its versatile API and the inner workings, which rely on low-level Compose components like AnchoredDraggable and SubcomposeLayout.

If you’d like to see the full source code from this post and use it in your project, check out the advanced-bottomsheet-compose repository on GitHub.

Overview

More than 2 expanded states

Below is an example of a bottom sheet with 3 states. We use it to display parking location details to Turo guests.

The API is very similar to the original BottomSheetScaffold but adds more flexibility during the configuration. Notably, it lifts the restriction of a maximum of 2 expanded states.

First, we declare an enum that represents each state of a bottom sheet.

enum class SheetValue { Collapsed, PartiallyExpanded, Expanded }

Bottom sheet state and value are used interchangeably in the context of this blog post.

Then we use a rememberBottomSheetState function to map bottom sheet states to their positions on the screen.

val sheetState = rememberBottomSheetState(
  initialValue = SheetValue.PartiallyExpanded,
  defineValues = {
    // Bottom sheet height is 100 dp.
    SheetValue.Collapsed at height(100.dp)
    // Bottom sheet offset is 60% meaning it takes 40% of the screen height.
    SheetValue.PartiallyExpanded at offset(percent = 60)
    // Bottom sheet wraps its content when expanded.
    SheetValue.Expanded at contentHeight
  }
)

Each bottom sheet state can be configured either by declaring its height or setting an offset from the top of the screen. It is allowed to use pixels, dp, or percentages during the configuration.

height(dp = 200.dp)
height(px = 550f)
height(percent = 45)

offset(dp = 200.dp)
offset(px = 550f)
offset(percent = 45)

contentHeight

In addition, there is a special contentHeight value that allows the bottom sheet to wrap its content.

The final step is identical to the one used with the original BottomSheetScaffold.

val scaffoldState = rememberBottomSheetScaffoldState(sheetState)

BottomSheetScaffold(
  scaffoldState = scaffoldState,
  sheetContent = {
    // Composable bottom sheet content.
  },
  content = {
    // Composable screen content.
  },
)

Adding or removing the bottom sheet states

A more advanced use case involves dynamically reconfiguring the bottom sheet while the user interacts with it, such as adding or removing states while it’s being dragged. Consider the example below.

// --(1)--
var isInitialState by remember { mutableStateOf(true) }

val state = rememberBottomSheetState(
  initialValue = SheetValue.PartiallyExpanded,
  defineValues = {
    SheetValue.Collapsed at height(200.dp)
    // --(2)--
    if (isInitialState) {
      SheetValue.PartiallyExpanded at height(percent = 50)
    }
    SheetValue.Expanded at contentHeight
  },
  confirmValueChange {
    if (isInitialState) {
      isInitialState = false
      // --(3)--
      refreshValues()
    }
    true
  }
)

1. We declare a mutable variable to determine when to include or exclude a specific bottom sheet state.
2. Then, add or skip a particular bottom sheet state based on the variable.
3. Finally, we call refreshValues to invoke defineValues lambda again and reconfigure the bottom sheet when needed. The refreshValues is a member function of a BottomSheetState.

In the code snippet above, the bottom sheet initially has 3 states and is set to PartiallyExpanded, but only the Collapsed or Expanded states are available once dragged by the user.

Changing the height of existing states.

While Turo guests can use the bottom sheet to view the vehicle parking location, hosts would use the bottom sheet to configure it. Consider the example below.

• Images 1 and 3 show the same PartiallyExpanded bottom sheet state. In image 1 the sheet occupies 40% of the screen while in image 3 it wraps the content height. The red banner in the UI is optional and may not always be present. Depending on the specific business logic, there can be at least 4 distinct states with varying heights.
• Image 2 illustrates the Expanded bottom sheet state, designed to be nearly full-screen with a slight offset at the top to provide a view of the map.

Upon a screen state change, we call BottomSheetState.refreshValues, which invokes the defineValues lambda and provides the updated dimensions of the bottom sheet content. These updated dimensions allow the height of the PartiallyExpanded state to be adjusted.

Implementation

Now, let’s talk about the technical details. If your primary goal is to use the bottom sheet in your project, refer to advanced-bottomsheet-compose GitHub repository as it contains the source code and the instructions for integrating it in your project. If you’d like to understand how it works under the hood, feel free to continue reading.

The core concept behind any bottom sheet implementation is straightforward. We manipulate the offset of its layout from the top of the screen. The larger the offset, the less of the bottom sheet is visible, and vice versa. Its height remains unchanged, while the visible portion of the bottom sheet’s layout depends on the offset.

The bottom sheet’s offset changes as the user drags it. However, instead of dragging freely, it snaps to specific positions corresponding to the defined bottom sheet states.

AnchoredDraggable

AnchoredDraggable — is a low-level component for building draggable components with anchored states in Compose. This is precisely what we need to leverage for implementing the concepts described above.

The code for the bottom sheet is pretty straightforward and comprises several steps. First, declare an enum that represents the states of a bottom sheet.

enum class SheetValue { Collapsed, PartiallyExpanded, Expanded }

Initialize AnchoredDraggableState that uses SheetValue as its T.

val state = remember {
  AnchoredDraggableState<SheetValue>(
    initialValue = SheetValue.PartiallyExpanded,
    positionalThreshold = { 0f },
    velocityThreshold = { 0f },
    animationSpec = SpringSpec(),
  )
}

Finally, define a composable hierarchy that implements a bottom sheet in Compose.

// --(1)--
BoxWithConstraints {
  val layoutHeight = constraints.maxHeight

  // --(2)--
  ScreenContent()

  Surface(
    modifier = Modifier
      .fillMaxWidth()
      // --(3)--
      .offset {
        val sheetOffsetY = state.requireOffset().toInt()
        IntOffset(x = 0, y = sheetOffsetY)
      }
      // --(4)--
      .anchoredDraggable(state, orientation = Orientation.Vertical)
      // --(5)--
      .onSizeChanged { sheetSize ->
        val sheetHeight = sheetSize.height
        val newAnchors = DraggableAnchors {
          with(density) {
            // Bottom sheet height is 56 dp.
            SheetValue.Collapsed at (layoutHeight - 56.dp.toPx())
            // Offset is 60% meaning the bottom sheet takes 40% of the screen height.
            SheetValue.PartiallyExpanded at (layoutHeight * 0.6f)
            // Bottom sheet height is equal to the height of its content.
            // If the height of the content is bigger than the screen - fill the entire screen.
            SheetValue.Expanded at maxOf(layoutHeight - sheetHeight, 0).toFloat()
          }
        }
        state.updateAnchors(newAnchors, state.targetValue)
      },
  ) {
    // --(6)--
    BottomSheetContent()
  }
}

Here is what’s going on in the code above.

1. We wrap everything with BoxWithConstraints so that we can measure the layoutHeight of a screen. This will be handy when calculating the positions of bottom sheet states further.
2. Render the ScreenContent behind the bottom sheet.
3. Apply the current bottom sheet offset to its layout using the AnchoredDraggableState.
4. Enable bottom sheet dragging by using anchoredDraggable modifier. This will update the offset as soon as the bottom sheet is dragged.
5. The crucial step is configuring the bottom sheet states and applying them to the AnchoredDraggableState. We do this in onSizeChanged, which conveniently provides the bottom sheet layout's height, essential for subsequent calculations. Compose calls onSizeChanged both when the screen first opens and whenever the bottom sheet content's size changes.
6. Finally, we render the actual BottomSheetContent.

This comprises most of the code required to implement a fully functional bottom sheet. The remaining step is to enable nested scrolling, which is detailed below. Everything else pertains to improvements for code organization and the public API.

Nested scrolling

If the content within your bottom sheet exceeds its height, you’ll need to implement nested scrolling. I won’t cover this in detail here, but we’re using a BottomSheetNestedScrollConnection, which is a slightly modified version of the code from the original Material 3 bottom sheet implementation.

// --(1)--
val scope = rememberCoroutineScope()

// --(2)--
val nestedScrollConnection = remember(state) {
  BottomSheetNestedScrollConnection(
    state = state,
    orientation = Orientation.Vertical,
    onFling = { velocity ->
      scope.launch { state.settle(velocity) }
    }
  )
}

Surface(
  modifier = Modifier
    // --(3)--
    .nestedScroll(nestedScrollConnection)
    .offset {...}
    .anchoredDraggable(...)
    .onSizeChanged {...}
) {
  ...
}

Enabling nested scrolling in the bottom sheet requires the following steps.

1. Create a coroutine scope instance.
2. Instantiate a BottomSheetNestedScrollConnection. Use the coroutine scope to help the anchored draggable settle into specific bottom sheet states during nested scrolling
3. Apply the nestedScroll modifier to the bottom sheet layout.

The code within the offset, anchoredDraggable, and onSizeChanged modifiers remains unchanged from the previous section.

SubcomposeLayout

SubcomposeLayout — is a layout in Compose that allows for the measurement of its child elements before using that data to compose other children. This makes it particularly useful for handling dynamic content, where the size of elements might not be known beforehand.

To be completely honest, SubcomposeLayout is not strictly necessary for the bottom sheet’s functionality. You can likely implement it without this component. However, it offers advantages in terms of code organization and overall scalability

@Composable
fun BottomSheetScaffold(
  state: AnchoredDraggableState<SheetValue>,
  sheetContent: @Composable () -> Unit,
  modifier: Modifier = Modifier,
  content: @Composable () -> Unit
) {
  // --(1)--
  SubcomposeLayout { constraints ->
    val layoutWidth = constraints.maxWidth
    val layoutHeight = constraints.maxHeight

    // --(2)--
    val sheetPlaceable = subcompose(slotId = "sheet") {
      Surface(
        modifier = Modifier
          .anchoredDraggable(...)
          .onSizeChanged {...}
          .nestedScroll(...)
      ) {
        sheetContent()
      }
    }[0].measure(constraints)

    val bodyPlaceable = subcompose(slotId = "body") {
      Surface(modifier = modifier) {
        content()
      }
    }[0].measure(constraints)

    // --(3)--
    layout(layoutWidth, layoutHeight) {
      val sheetOffsetY = state.requireOffset().roundToInt()
      val sheetOffsetX = 0

      bodyPlaceable.placeRelative(x = 0, y = 0)
      sheetPlaceable.placeRelative(sheetOffsetX, sheetOffsetY)
    }
  }
}

Here is how to implement a bottom sheet with a SubcomposeLayout.

1. Wrap everything with a SubcomposeLayout composable.
2. We measure the sheet content and screen content in their respective subcompose slots. Although subcompose returns a list of Measurable elements, we are using only a single top-level composable within each subcompose call. Therefore, we measure only the first element in each list, accessed with the index [0].
3. Place composables using the latest offset. The lambda in the layout function will be called every time the bottom sheet offset changes.

In the full implementation of a bottom sheet, the SubcomposeLayout manages the screen content, sheet content, top bar, and snackbar host. Using SubcomposeLayout in this scenario enables efficient measurement and placement of these 4 elements. The code for this implementation can be found here.

Organizing code

The final step involves organizing the code into distinct composable functions internally to achieve better separation of concerns, improve scalability, and provide more customizable public properties. The API of the resulting composables is designed to closely resemble the original BottomSheetScaffold implementation and can be found here.

You can access the bottom sheet’s source code and a sample project demonstrating the steps outlined in this article in the advanced-bottomsheet-compose GitHub repository.

Resources

• Bottom sheets — m3.material.io
• Migrate from Swipeable to AnchoredDraggable — developer.android.com
• Advanced Layout concepts — medium.com/androiddevelopers
• Jetpack Compose phases — developer.android.com
• Exploring Jetpack Compose Anchored Draggable Modifier — Francesc Vilarino Guell

Advanced Bottom Sheet With Flexible Configuration for Compose was originally published in Turo Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

Migrating Android apps from Gradle to Bazel

In recent years, Bazel has become a compelling alternative for large Android codebases as a build tool of choice. However, due to its relative newness and non-default status on Android, the Bazel ecosystem is not as mature as Gradle’s, making the adoption process more challenging and the learning curve steeper.

There are many great resources out there that may persuade you to migrate your codebase to Bazel. In this story, I will share Turo’s experience of Bazel adoption and show you how to configure a robust automation platform once you’ve decided to give Bazel a shot.

What does Bazel migration mean?

The migration process to Bazel essentially entails creating a set of Bazel files for your project and placing them in the appropriate locations, based on the Gradle project structure. Ultimately, the effort unfolds in two key parts.

1. Determining how to build each component of the app with Bazel. This is particularly relevant to custom Gradle tasks or plugins that do not have open-source Bazel alternatives.
2. Automating incremental adoption. For each build feature that necessitates the creation of custom Bazel rules, macros, etc, an automation tool is used to populate it with every related project module.

Why automation is needed?

Automatically generating Bazel build scripts is notably more efficient than manual creation, especially when dealing with codebases that comprise hundreds or even thousands of modules. Yet, the benefits of automation go beyond merely addressing this challenge.

Bazel adoption is not an overnight process. Throughout this transition, the build configuration of your project will continuously evolve, with modules and dependencies being added or removed, etc. Using automation tooling allows you to keep Gradle as the source of truth for as long as necessary without putting undue stress on the engineering team.

Furthermore, it offers flexibility and room for experimentation. Operating two build systems side by side, at least during the migration phase, enables precise evaluation and comparison of their performance. This approach also allows for the gradual integration of Bazel into selected CI workflows, providing the option to transition incrementally while retaining the old build system as a reliable backup for the remaining workflows.

Migration tooling overview

At Turo, Bazel adoption is powered by two open-source tools, Airin and Pendant. Airin, a Gradle plugin, scans the project structure, and Pendant is then utilized to generate Starlark scripts that replicate the same project configuration with Bazel.

You can streamline Bazel adoption for your codebase using Airin as well. To setup the automation tooling the Gradle plugin is applied in the root build.gradle.kts file.

// root build.gradle.kts
plugins {
  id("io.morfly.airin.android") version "x.y.z"
}

Then it is configured using airin extension as shown in the next example.

// root build.gradle.kts
airin {
  targets += setOf(":app", ":auth-feature")

  register<AndroidLibraryModule> {
    include<JetpackComposeFeature>()
    include<HiltFeature>()
    include<ParcelizeFeature>()
    ...
  }
  register<JvmLibraryModule>()

  register<RootModule> {
    include<AndroidToolchainFeature>()
  }
}

If looking at the code snippet above, you’ll notice that the plugin configuration comprises several key components.

• targets — specifying the migration targets. These modules allow initiation of Bazel adoption not only for themselves but also for all their dependencies, including the transitive ones. A migrateToBazel Gradle task is configured for each module declared here.
• register — registering types of project modules to be migrated to Bazel.
• include — including build features these modules might optionally employ.

The primary migration target in Android projects is usually the main app module, triggering the migration for every other module in the application.

./gradlew app:migrateToBazel

However, for incremental Bazel adoption, a partial migration is possible. For instance, one could start by migrating only the authentication feature and all its dependencies.

./gradlew auth-feature:migrateToBazel

Once invoked, the task generates a set of Bazel files for a migration target, all its dependencies and the root module. Consequently, all of them can be built with Bazel.

bazelisk build //app

In many scenarios, achieving a fully automatic migration from Gradle to Bazel may not be possible without additional work. This is particularly true if your project involves custom Gradle build logic, tasks, and plugins, or relies on components lacking open-source Bazel alternatives. In such cases, additional effort becomes inevitable for a successful transition.

Nevertheless, automation tooling remains crucial even in these situations. Every time you determine how to build the missing piece with Bazel, Airin provides an API to seamlessly incorporate the related custom scripts and rule sets into the automation pipeline.

Ultimately, the automation tool is agnostic to the specific contents of generated Bazel files. Its role is to provide a framework for efficient migration, allowing for either the use of predefined file configurations or full customization for more sophisticated use cases.

Understanding the project structure

A key aspect of modern Android codebases is their modular architecture. Despite the potential for hundreds or even thousands of modules in your project, they can all be categorized into a small number of groups or module types. In Android codebases, modules typically fall into, but are not limited to, the following types.

• Android module — a feature or library module that leverages the Android SDK. It relies on com.android.library or com.android.application Gradle plugins.
• Java/Kotlin module — a library module that exclusively depends on JVM APIs. Typically, it employs Gradle plugins such as java or org.jetbrains.kotlin.jvm.
• Root module —a module that serves as the foundation for the project, encompassing project-wide configuration settings.

The categorization into module types suggests that within each type, the build configuration for modules is nearly identical. However, individual modules within a category may still employ different sets of tools and technologies, leading to minor variations in the build configuration.

In other words, each module category is reinforced with a set of build features that may be optionally incorporated into each instance of the module.

• Android module
  ◦ Jetpack Compose feature
  ◦ Parcelize feature
  ◦ Hilt feature

For example, certain Android modules might utilize Jetpack Compose, while others may employ features like Parcelize or Hilt, etc. Although these features are optional, their integration into module configurations does not significantly alter the build script structure.

Automation tooling design

The aforementioned concepts form the foundation of a component-based architecture, representing module types and build features as components. Think of components as lightweight plugins that seamlessly integrate into your Gradle project configuration, offering a framework to replicate it using Bazel.

A typical configuration for an Android project can be illustrated with the following diagram.

To describe it more formally, the configuration of a Gradle plugin for automated migration to Bazel comprises two main component types.

• Module component — defines the Bazel files generated for each module type. It can optionally include a set of feature components.
• Feature component — contributes optional feature-related build configurations to the files generated by a related module component.

Typically, each feature component is associated with a module component. However, shared feature components have an additional role, contributing to every shared module component. We will take a closer look at shared components later.

For now, let’s examine how the migration tool operates. The Gradle to Bazel migration flow is depicted in the diagram below.

The migration process essentially involves 3 primary steps, performed for each module individually.

1. Pick a module component capable of migrating this specific module. Performed during the Gradle Configuration phase.
2. Pick feature component(s) for corresponding build features applied to the module. Performed during the Gradle Configuration phase.
3. Generate Bazel file(s) by utilizing the chosen components. Performed during the Gradle Execution phase.

Only one module component can be selected for the module, while multiple feature components are allowed.

Gradle task graph

During configuration, the Gradle plugin registers a series of tasks for all the modules involved in Bazel migration. Each task, at this point, is already aware of the components it should invoke. The dependency graph of these Gradle tasks is illustrated below.

• migrateToBazel — is registered for migration targets. Invokes migration for all direct and transitive dependencies as well as the root module.
• migrateProjectToBazel — is registered for every module that is a direct or a transitive dependency of a migration target. Invokes migration only for this particular module.
• migrateRootToBazelFor*** — is registered for a root module and complements the migration of a specific migration target where *** is its name.

As these tasks are executed, a corresponding set of components is invoked, leading to the generation of Bazel files.

The Airin Gradle plugin offers a set of ready-to-use components encompassing commonly used module types and build features. However, if additional flexibility and customization are needed, you can create custom components, as demonstrated in the following sections.

Module components

Every module component is an abstract class that extends the ModuleComponent base class and implements 2 functions, canProcess and onInvoke.

abstract class AndroidLibraryModule : ModuleComponent {

  override fun canProcess(project: Project): Boolean {...}

  override fun ModuleContext.onInvoke(module: GradleModule) {...}
}

The former is invoked during the Gradle Configuration phase and is aimed to filter Gradle modules to which this component is applicable.

The latter is invoked during the Gradle Execution phase and contains the main logic of the component the purpose of which is to generate Bazel files for the module.

The easiest way to determine the module type is by examining its applied plugins. For example, an Android library module in Gradle typically relies upon the com.android.library plugin.

abstract class AndroidLibraryModule : ModuleComponent {

  override fun canProcess(project: Project): Boolean =
    project.plugins.hasPlugin("com.android.library")
}

Now, it’s time to generate Bazel files. Here, we utilize a Kotlin DSL that enables the creation of various types of Starlark files in a declarative fashion.

abstract class AndroidLibraryModule : ModuleComponent {

  override fun ModuleContext.onInvoke(module: GradleModule) { 
    val file = BUILD.bazel {
        ...
    }
    generate(file)
  }
}

Depending on the called builder function, a file with a corresponding name will be generated. For instance, BUILD, BUILD.bazel, WORKSPACE, WORKSPACE.bazel, *.bzl.

val build = BUILD.bazel { ... }
val workspace = WORKSPACE { ... }
val mavenDependencies = "maven_dependencies".bzl { ... }

generate(build, workspace)
generate(mavenDependencies, relativePath = "third_party")

Files are generated in the module directory or a subdirectory if a relative path is specified.

Starlark code generation

In each builder block, the contents of Bazel files are crafted using a Kotlin DSL that mirrors the syntax of a Starlark language. Essentially, you’re writing Kotlin code that looks like Starlark. The code generator is type-safe, meaning many errors would be caught by the Kotlin compiler before running the program.

override fun ModuleContext.onInvoke(module: GradleModule) {
  val file = BUILD.bazel {
    load("@io_bazel_rules_kotlin//kotlin:android.bzl", "kt_android_library")
  
    kt_android_library {
      name = module.name
      srcs = glob("src/main/**/*.kt")
      custom_package = module.androidMetadata?.packageName
      manifest = "src/main/AndroidManifest.xml"
      resource_files = glob("src/main/res/**")
    }
  }

  generate(file)
}

When executed, it produces an abstract syntax tree similar to the one created by the original Starlark interpreter. This tree is subsequently leveraged to generate formatted Starlark code.

You can find an in-depth overview of a declarative Starlark code generator in the talk at droidcon NYC 2022.

The Starlark code generator is available as an open-source library Pendant and is bundled as part of the Airin plugin.

Dependencies

A Bazel target can possess various types of dependencies, each represented by different function parameters.

# BUILD.bazel
kt_android_library(
  ...
  deps = [...],
  exports = [...],
  plugins = [...],
)

A GradleModule instance provides dependencies mapped per configuration, represented with an argument name. To designate dependencies in the generated code, the `=` function (enclosed in backticks) is used to represent an argument passed to a function.

kt_android_library {
  ...
  for ((config, deps) in module.dependencies) {
    config `=` deps.map { it.asBazelLabel().toString() }
  }
}

As a result, the following Starlark code is generated.

# generated Bazel script
kt_android_library(
  ...
  plugins = [...],
  deps = [...],
  exports = [...],
)

To properly map Gradle configurations to respective function arguments in Bazel, we make use of feature components.

Feature components

Every feature component is an abstract class that extends the FeatureComponent base class and implements 2 functions, canProcess and onInvoke.

abstract class JetpackComposeFeature : FeatureComponent() {

  override fun canProcess(project: Project): Boolean {...}

  override fun FeatureContext.onInvoke(module: GradleModule) {...}
}

The former is invoked during the Gradle Configuration phase and is aimed to filter Gradle modules to which this component is applicable.

The latter is invoked during the Gradle Execution phase and contains the main logic of the component. Its purpose is to modify Bazel files generated by a related module component as well as manage the dependencies of the module.

Overriding dependencies

When migrating Gradle modules to Bazel, an obvious task is to preserve a correct dependency graph including internal module dependencies and third-party artifacts. As it turns out, the same module might have a different set of dependencies in Gradle and Bazel.

For example, let’s consider Hilt, a dependency injection library. In Gradle, your module would need to utilize a Hilt plugin and depend on two artifacts, one of which is a Kotlin symbol processor.

// build.gradle.kts
plugins {
  id("com.google.dagger.hilt.android")
}

dependencies {
  implementation("com.google.dagger:hilt-android:x.y.z")
  ksp("com.google.dagger:hilt-android-compiler:x.y.z")
}

However, in Bazel, it has a quite different way of usage.

# BUILD.bazel
kt_android_library {
  ...
  deps = ["//:hilt-android"]
}

To address this, a feature component offers a dependency override API. Here is how it looks for the Hilt example.

// FeatureComponent.onInvoke
onDependency(MavenCoordinates("com.google.dagger", "hilt-android")) {
  overrideWith(BazelLabel(path = "", target = "hilt-android"))
}

This implies that when applied to any module, the feature component will replace occurrences of the com.google.dagger:hilt-android artifact with the //:hilt-android Bazel target.

Since Hilt requires more than one dependency in Gradle, the remaining artifacts can be disregarded in Bazel.

// FeatureComponent.onInvoke
onDependency(MavenCoordinates("com.google.dagger", "hilt-android-compiler")) {
  // ignored
}

Overriding configurations

When setting up a Gradle module, it involves not only specifying dependencies but also assigning them to specific configurations, providing instructions to Gradle on how to treat each dependency.

// build.gradle.kts
dependencies {
  implementation(...)
  api(...)
  ksp(...)
  ...
}

In Bazel, targets are declared using function calls. As an analogue to Gradle configurations, we use specific function parameters for various types of dependencies.

# BUILD.bazel
kt_android_library(
  ...
  deps = [...],
  exports = [...],
  plugins = [...],
)

Similar to dependency overrides, feature components also allow the overriding of configurations. In the example below, all implementation dependencies will be declared as deps in Bazel.

// FeatureComponent.onInvoke
onConfiguration("implementation") {
  overrideWith("deps")
}

For exporting transitive dependencies, deps and exports are used as an equivalent to Gradle’s api configuration.

// FeatureComponent.onInvoke
onConfiguration("api") {
  overrideWith("deps")
  overrideWith("exports")
}

Modifying Bazel scripts

Beyond handling dependencies, feature components can also make contributions to the Bazel files generated by module components.

Let’s revisit the code snippet from the AndroidLibraryModule component that we used in the module components section, but this time, let’s slightly update it.

// ModuleComponent.onInvoke
val file = BUILD.bazel {
  _id = "build_file"

  load("@io_bazel_rules_kotlin//kotlin:android.bzl", "kt_android_library")

  kt_android_library {
    _id = "android_library_target"
    
    name = module.name
    srcs = glob("src/main/**/*.kt")
    custom_package = module.androidMetadata?.packageName
    manifest = "src/main/AndroidManifest.xml"
    resource_files = glob("src/main/res/**")
    for ((config, deps) in module.dependencies) {
      config `=` deps.map { it.asBazelLabel().toString() }
    }
  }
}

A notable addition here is the introduction of _id fields. These can be defined within any code block enclosed by curly brackets {}. Once defined, you gain the flexibility to edit the contents of these code blocks externally.

Let’s modify the contents of the generated Bazel file using our feature component. To achieve this, within the onInvoke function, use the onContext call, specifying the type of the context to be modified, along with its identifier.

// FeatureComponent.onInvoke
onContext<BuildContext>(id = "build_file") {
  `package`(default_visibility = list["//visibility:public"])
}

onContext<KtAndroidLibraryContext>(id = "android_library_target") {
  enable_data_binding = true
}

As a result, when the AndroidLibraryModule component is invoked, it will incorporate all the modifications, including the added enable_data_binding argument, as well as the top-level package function call.

load("@io_bazel_rules_kotlin//kotlin:android.bzl", "kt_android_library")
load("@rules_jvm_external//:defs.bzl", "artifact")

kt_android_library(
    name = "my-library",
    srcs = glob(["src/main/**/*.kt"]),
    custom_package = "com.turo.mylibrary",
    manifest = "src/main/AndroidManifest.xml",
    resource_files = glob(["src/main/res/**"]),
    deps = [...],
    enable_data_binding = True, # added by a feature component 
)

# added by a feature component
package(default_visibility = ["//visibility:public"])

Customizing components with properties

In many cases, there is no need to create new custom components. Instead, it’s often easier to configure existing ones.

For example, let’s examine the AndroidToolchainFeature included in the RootModule. Its purpose is to enable Kotlin, Java, and Android rules in the Bazel workspace and configure respective toolchains.

This component already generates all the necessary Starlark code. However, it exposes certain properties that allow you to specify versions of rule sets or toolchains.

// root build.gradle.kts
airin {
  register<RootModule> {
    include<AndroidToolchainFeature> {
      rulesKotlinVersion = "1.8.1"
      rulesKotlinSha = "a630cda9fdb4f56cf2dc20a4bf873765c41cf00e9379e8d59cd07b24730f4fde"
    }
  }
}

On the other side, within the component definition, the properties are declared using a property delegate.

abstract class AndroidToolchainFeature : FeatureComponent() {
  val rulesKotlinVersion: String by property(default = "1.8.1")
  val rulesKotlinSha: String by property(default = "a630cda9fdb4f56cf2dc20a4bf873765c41cf00e9379e8d59cd07b24730f4fde")

  override fun FeatureContext.onInvoke(module: GradleModule) {

    onContext<WorkspaceContext> {
      val RULES_KOTLIN_VERSION by rulesKotlinVersion
      val RULES_KOTLIN_SHA by rulesKotlinSha
  
      http_archive(
          name = "io_bazel_rules_kotlin",
          sha256 = RULES_KOTLIN_SHA,
          urls = list["https://github.com/bazelbuild/rules_kotlin/releases/download/v%s/rules_kotlin_release.tgz" `%` RULES_KOTLIN_VERSION],
      )
      ...
    }
  }
  ...
}

Shared components

Often, invoking a feature component solely for the module it belongs to is insufficient. Take the example of Hilt. Before including it as a dependency in any module, you need to configure Dagger in your Bazel workspace by following these two steps.

• Load Dagger rules in the WORKSPACE file and register artifacts in maven_install.
• Register Hilt rules in the root BUILD.bazel file.

Check official Dagger documentation to learn more about how to configure it in Bazel projects.

In addressing such scenarios, the automation tool employs the concept of shared components. Depending on the component type, the behavior can fall into one of three categories.

• Shared module component — receives contributions from every shared feature component, even if it is not directly included in it.
• Shared feature component — contributes to every shared module component.
• Top-level feature component — does not belong to any module component specifically and contributes to all module components, even non-shared ones.

This is how they are declared in a Gradle plugin.

// root build.gradle.kts
airin {
  register<AndroidLibraryModule> {
    // shared feature component
    include<HiltFeature> { shared = true }
  }

  // shared module component
  register<RootModule> { shared = true }

  // top-level feature component
  include<AllPublicFeature>()
}

Assume the RootModule component generates WORKSPACE and BUILD.bazel files.

abstract class RootModule : ModuleComponent() {
  ...

  override fun ModuleContext.onInvoke(module: GradleModule) {
    val workspace = WORKSPACE {
      _id = "workspace_file"
    }

    val build = BUILD.bazel {
      _id = "root_build_file"
    }

    generate(build, workspace)
  }
}

With this in mind, the HiltFeature component could contribute to modules that use Hilt as well as to the root module.

abstract class HiltFeature : FeatureComponent() {

  override fun canProcess(project: Project) = 
    hasPlugin("com.google.dagger.hilt.android") ||
    project.rootProject == project

  override fun FeatureContext.onInvoke(module: GradleModule) {

    // contributing to WORKSPACE file
    onContext<WorkspaceContext>(id = "workspace_file") {
      val DAGGER_VERSION by"..."
      val DAGGER_SHA by "..."

      http_archive(
        name = "dagger",
        strip_prefix = "dagger-dagger-%s" `%` DAGGER_VERSION,
        sha256 = DAGGER_SHA,
        urls = list["https://github.com/google/dagger/archive/dagger-%s.zip" `%` DAGGER_VERSION],
      )
    }

    // contributing to root BUILD.bazel file
    onContext<BuildContext>(id = "root_build_file") {
      load("@dagger//:workspace_defs.bzl", "hilt_android_rules")
      hilt_android_rules()
    }

    // contributing to modules that depend on Hilt
    onDependency(...) { ... }
    ...
  }
}

To conclude

There can be an infinite number of unique Gradle configurations relying on custom build logic, tasks, and plugins without available open-source Bazel alternatives.

That’s why it’s crucial for the Bazel migration tooling not to attempt to cover them all at once. Of course, due to its open-source nature, Airin provides a predefined set of components for a quick head start with Android projects. However, more importantly, it provides a framework that allows full customization and ability to adjust to the codebase it is applied to.

Use these links for complete examples of module and feature components as well as a sample project.

Boosting Bazel Adoption on Android With Automation was originally published in Turo Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

Adopting Jetpack Compose in existing codebases is a challenge many teams face nowadays. Recently, we published a story about how we designed a Jetpack Compose architecture for the Turo Android app that heavily relies on fragments. Today, we are excited to make it open-source as Nibel.

Nibel — is a type-safe navigation library that enables seamless adoption of Jetpack Compose in Android apps that rely on fragments. When we built it at Turo, our goal was to ensure a proper Jetpack Compose experience for the team when creating new features while keeping them compatible with the rest of the codebase automatically. By leveraging the power of a Kotlin Symbol Processor (KSP) Nibel provides a unified and type-safe way of navigating between screens in the following navigation scenarios:

• fragment → compose
• compose → compose
• compose → fragment

Nibel supports both single-module and multi-module navigation out-of-the-box. The latter is especially useful when navigating between feature modules that do not depend on each other directly.

You can find Nibel and the documentation on GitHub.

GitHub - open-turo/nibel: Type-safe navigation library for seamless adoption of Jetpack Compose in fragment-based Android apps.

In this story, you will see how you can start using Nibel in your project, the common scenarios of adopting Jetpack Compose, and the customization options Nibel provides.

How to use it?

Here are the basic steps for using Nibel in your project to start adopting Jetpack Compose.

1. Declare a screen. To start using Nibel, simply annotate your composable function with @UiEntry annotation. This will generate a {ComposableName}Entry class that is used to navigate to this screen.

@UiEntry(type = ImplementationType.Fragment)
@Composable
fun FooScreen(
  navigator: NavigationController // optional param
) { ... }

For screens with arguments just pass your Parcelable args class in the annotation.

@UiEntry(
  type = ImplementationType.Composable,
  args = BarScreenArgs::class
)
@Composable
fun BarScreen(
  args: BarScreenArgs, // optional param
  navigator: NavigationController // optional param
) { ... }

We’re going to take a closer look at ImplementationType later in this post.

2. Navigate between compose screens. Using NavigationController it is possible to navigate between annotated compose screens. Simply use a navigateTo function by passing an instance of a generated entry as an argument.

val args = BarScreenArgs(...)
navigator.navigateTo(BarScreenEntry.newInstance(args))

3. Navigate to a fragment. Similarly, a NavigationController can be used to navigate from compose screens to old fragments.

class BazFragment : Fragment() { ... }

Wrap a fragment instance with FragmentEntry and pass it to navigateTo function.

val fragment = BazFragment()
navigator.navigateTo(FragmentEntry(fragment))

4. Navigate from a fragment. Annotated compose screens appear as fragments to the outside non-compose world. Treat a generated entry class as a fragment and use a transaction for navigation.

class QuxFragment : Fragment() {
  ...
  requireActivity().supportFragmentManager.commit {
    replace(android.R.id.content, FooScreenEntry.newInstance().fragment)
  }
}

Multi-module navigation

In multi-module apps, it is common to have feature modules that do not depend on each other directly. In this case, it is impossible to obtain a direct reference to a generated entry class in another feature module.

Nibel provides an easy way of multi-module navigation in a type-safe manner using the concept of destinations. Destination — is a simple data type that serves as a navigation intent. It is located in a separate module available to other feature modules.

Each destination is associated with exactly one screen, so when navigation is required, the instance of a destination is used to reach the target screen.

There is no need to have a single navigation module per app. There can be many of them in the app. The key requirement though, is for the destination type to be available for both source and target screens.

1. Declare a destination. The most basic destination is an object that implements DestinationWithNoArgs an is declared in a separate navigation module, available to other feature modules.

// :navigation module
object FooScreenDestination : DestinationWithNoArgs

If you need a screen with args, inherit DestinationWithArgs instead.

// :feature module, depends on :navigation module
data class BarScreenDestination(
  override val args: BarScreenArgs // Parcelable args
) : DestinationWithArgs<BarScreenArgs>

2. Associate a destination with a screen. Each destination should be associated with exactly one screen using @UiExternalEntry annotation over a composable function.

@UiExternalEntry(
  type = ImplementationType.Fragment,
  destination = BarScreenDestination::class
)
@Composable
fun BarScreen(
  args: BarScreenArgs, // optional param
  navigator: NavigationController // optional param
) { ... }

If multi-module navigation from compose to an old fragment is needed, a @LegacyExternalEntry should be applied to the fragment.

@LegacyExternalEntry(destination = BasScreenDestination::class)
class BazScreenFragment : Fragment() { ... }

3. Navigate to a destination. Use NavigationController to navigate to a destination.

val args = BarScreenArgs(...)
navigator.navigateTo(BarScreenDestination(args))

@UiScreenEntry includes all the functionality of @UiEntry and therefore, if you have a direct reference to the generated entry class, the following code is valid for the same screen.

val args = BarScreenArgs(...)
navigator.navigateTo(BarScreenEntry.newInstance(args))

4. Navigate from a fragment. Finally, if a multi-module navigation is needed from an old fragment to a compose screen, a destination should be used to obtain a fragment instance and perform a transaction.

class QuxScreenFragment : Fragment() {
  ...
  requireActivity().supportFragmentManager.commit {
    val entry = Nibel.newFragmentEntry(BarScreenDestination)!!
    replace(android.R.id.content, entry.fragment)
  }
}

Composable function params

Composable functions annotated with @UiEntry or @UiExternalEntry can have any number of parameters as long as they have default values.

@UiEntry(type = ImplementationType.Fragment)
fun FooScreen(viewModel: FooViewModel = viewModel()) { ... }

In addition, there are special types of params that do not require default values, as Nibel can figure out how to provide corresponding instances. Among such params are NavigationController, ImplementationType and args of the same type as in the @UiEntry annotation or in the destination type.

@UiEntry(
  type = ImplementationType.Composable, 
  args = BarArgs::class
)
fun BarScreen(
  args: BarArgs,
  navigator: NavigationController,
  type: ImplementationType
) { ... }

If argument types do not match, a compile type error will be thrown.

Alternatively, the values above could be obtained as composition locals.

@UiEntry(
  type = ImplementationType.Composable, 
  args = BarArgs::class
)
fun BarScreen() {
  val args = LocalArgs.current as BarArgs
  val navigator = LocalNavigationController.current
  val type = LocalImplementationType.current
}

Common usage scenarios

The type of generated entries differs depending on the ImplementationType specified in the annotation of a target screen. Each type serves a specific scenario and can be one of:

• Fragment - generated entry is a fragment that uses the annotated composable as its content. It makes the compose screen appear as a fragment to other fragments and is crucial in fragment → compose navigation scenarios.
• Composable - generates a small wrapper class over a composable. It is normally used in compose → compose and compose → fragment navigation scenarios where the latter is marked with this implementation type.

Normally there are several scenarios for adding new Jetpack Compose screens to an existing codebase.

Scenario 1 — new feature

The easiest scenario is when you are creating a completely new feature in a separate module. In this case, all the screens of the feature will use Jetpack Compose.

The first screen of the feature serves as an external entry, as it allows entering the feature from other modules. It is crucial that it is marked with ImplementationType.Fragment. This will ensure it appears as a fragment to the non-compose code and thus, makes it easy to navigate from old fragments to this new feature.

All the subsequent screens in the feature should use ImplementationType.Composable. This will result in improved performance since no fragments are generated, leading to fewer class allocations per screen.

In some cases, you might need to navigate from the new feature back to an old one that relies on fragments. All you have to do is annotate a target fragment with @LegacyExternalEntry and use its associated destination for navigation through NavigationController.

Scenario 2 — expanding existing feature

Another scenario is when you need to insert a bunch of new consecutive screens in an existing feature. In this case, it is possible to have them as compose screens even though they’re placed in the middle of the flow of fragments.

The key rule here is the same. The first compose screen should be annotated with ImplementationType.Fragment and all the subsequent ones should use ImplementationType.Composable.

Scenario 3 — standalone screens

The third scenario is probably the most frequent during the first stages of Jetpack Compose adoption. In this case, standalone compose screens are placed in the middle of the old fragment flows.

All you need to do in this case is to annotate compose screens with ImplementationType.Fragment, and treat them as fragments outside of a compose code.

Customization

Nibel provides various customization options so that it can be adapted to the needs of a specific project.

Before proceeding with this section it is recommended to check our previous story which shows more details on Nibel’s internal components and the thought process behind their implementation.

Applying a theme

For every screen annotated with ImplementationType.Fragment Nibel generates an entry class which is a fragment that inherits a base ComposableFragment. When using Jetpack Compose with fragments, all the composable UI is set in onCreateView. This means that for every new fragment, a theme must be explicitly applied.

// base class for generated fragments
// (part of nibel-runtime library)
abstract class ComposableFragment : Fragment() {

  @Composable
  abstract fun ComposableContent()

  override fun onCreateView(
    ...
  ) = ComposeView(requireContext()).apply {
    setViewCompositionStrategy(ViewCompositionStrategy.DisposeOnViewTreeLifecycleDestroyed)
    setContent {
      AppTheme { // a theme should be applied here
        ...
      }
    }
  }
}

Since it’s a base class of a 3-rd party library, a custom theme of a specific app could not just be applied there.

To apply a theme you can implement a RootDelegate which will be just a class with a simple composable function. This function is called at the root of every screen annotated with ImplementationType.Fragment.

object CustomRootContent : RootDelegate {

  @Composable
  override fun Content(content: @Composable () -> Unit) {
    AppTheme { // applying a custom theme
      content()
    }
  }
}

Don’t forget to call content function, to proceed with the UI of your screen.

All that is left to do is apply the CustomRootContent when configuring Nibel.

Nibel.configure(rootDelegate = CustomRootContent)

Navigation specs

As we saw above, NavigationController is used to perform navigation between screens. However, the navigateTo function provides space for customization as well.

abstract class NavigationController(...) {
  ...

  fun navigateTo(
    entry: Entry,
    fragmentSpec: FragmentSpec<*>, // fragment navigation specification
    composeSpec: ComposeSpec<*> // compose navigation specification
  )
}

As we already know, Nibel enables navigation between fragments and compose screens in various scenarios. When navigating from a composable to a new screen, Nibel utilizes different tooling for navigation under the hood, depending on the target screen.

• If the next screen is a fragment or a composable with ImplementationType.Fragment there will be a fragment transaction performed implicitly.
• If the next screen is composable with ImplementationType.Composable Nibel will use compose navigation library implicitly to perform navigation.

At any moment, you could switch ImplementationType in the annotation of any screen, and the code will be still compilable. However, Nibel will use a different underlying tool to perform navigation. FragmentSpec is used when navigation between fragments happens under the hood, while ComposeSpec is used for direct navigation between composable functions, also implicitly.

When performing a fragment transaction under the hood, sometimes you might want to have more control over its specifics. For example, use add vs replace, select a custom container id for the transaction, etc.

The instance of each navigation spec holds inside implementation details of how the navigation should be performed. Therefore, it could be customized in multiple ways.

For example, for fragment transactions, you can use an instance of FragmentTransactionSpec and specify the details of a transaction.

navigator.navigateTo(
  entry = ..., 
  fragmentSpec = FragmentTransactionSpec(
    replace = true,
    addToBackStack = true,
    containerId = R.id.customContainerId
  )
)

If that’s not enough, you can completely override its behavior by writing the custom navigation logic.

class CustomTransactionSpec : FragmentTransactionSpec(...) {

  override fun FragmentTransactionContext.navigateTo(entry: FragmentEntry) {
    this.fragmentManager.commit {
      // custom fragment transaction logic
    }
  }
}

navigator.navigateTo(
  entry = ..., 
  fragmentSpec = CustomTransactionSpec()
)

As for compose specs, a compose navigation library is used under the hood. All the navigation destinations are being added dynamically in ComposeNavigationSpec. You can learn more about how the compose navigation library is used under the hood in our previous post.

Finally, when configuring Nibel you can set any navigation specification by default for all screens in the app.

Nibel.configure(
  fragmentSpec = CustomFragmentSpec(),
  composeSPec = CustomComposeSpec()
)

Compatibility with architecture components

Modern Android apps use various architecture components such as Hilt, ViewModel, etc. Let’s see how Nibel could be integrated with them.

You can declare a view model as a param of a composable function and use hiltViewModel to get its instance. Now, you can use a combination of a Nibel screen and a view model injected by Hilt.

@UiEntry(type = Composable, args = FooArgs::class)
@Composable
fun FooScreen(viewModel: FooViewModel = hiltViewModel()) { ... }

@HiltViewModel
class FooViewModel(handle: SavedStateHandle): ViewModel() {
  val args = handle.getNibelArgs<FooArgs>()
}

You can notice, that the screen arguments are automatically available in a SavedStateHandle in a view model.

To conclude

With Nibel, you can focus on writing new product features for your app with Jetpack Compose while having compatibility with the rest of the codebase, and fragments in particular, handled for you.

Nibel is highly customizable so it could be applied to various types of projects and navigation scenarios during adopting Jetpack Compose.

Feel free to check the repository for more documentation and a sample project with more details on how to use Nibel in practice.

GitHub - open-turo/nibel: Type-safe navigation library for seamless adoption of Jetpack Compose in fragment-based Android apps.

Give it a try and let us know what you think. We hope it will help you to make the process of Jetpack Compose adoption more smooth.

Introducing Nibel: A Navigation Library for Adopting Jetpack Compose in Fragment-Based Apps was originally published in Turo Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

Adopting Jetpack Compose at Turo

Jetpack Compose is a modern toolkit recommended for building native UI for Android apps. It provides a more intuitive developer experience helping engineers to write less UI code while making it more reliable.

The engineering team at Turo was excited about adopting Jetpack Compose in our Android app. However, as it usually happens, we have an existing codebase that heavily relies on fragment API. While Jetpack Compose has pretty good compatibility with a legacy UI stack out of the box, just including a new dependency in the project and starting to write composable functions was not enough.

An important task when integrating such a thing as a core UI toolkit is to make sure it fits well with the existing app architecture and APIs it relies on. More specifically, we wanted to find solutions to the following questions:

• How do we enable our team to write purely-compose features without bothering about compatibility with the rest of the app?
• How do we navigate from fragments to compose screens?
• How do we navigate from compose to fragments?
• How do we make the experience above simple and unified?

In this story, we will share our experience of adopting Jetpack Compose at Turo by designing the architecture that provides seamless and gradual integration of the modern UI toolkit into the existing codebase. We are going to talk about how we leveraged the power of Kotlin Symbol Processing API to provide a pure Jetpack Compose experience for our Android engineers while keeping the new product features fully compatible with the rest of the app automatically.

The content in this story is now available as an open-source navigation library — Nibel. You can find it on GitHub. In this post, you’ll see how it’s implemented under the hood, while the next one, describes how can you use it to migrate your project from fragments to Jetpack Compose.

Overview

Without further ado, let’s see what experience our engineers have when creating new UI features for the Turo Android app.

As you can see below, when we’re creating a UI screen, all we need to do is start writing @Composable functions. The only additional step is to annotate it with the @UiEntry annotation and declare a simple object or data class that will register this screen as a destination in a navigation graph.

@UiEntry(
  destination = VehicleSearchDestination::class,
  type = ImplementationType.Fragment
)
@Composable
fun VehicleSearchScreen(viewModel: VehicleSearchViewModel = ...) {
  SideEffectHandler(viewModel.sideEffects) {
    when (it) {
      // navigating to another screen
      is VehicleSearchSideEffect.ShowDetails -> navigateTo(
        VehicleDetailsDestination(VehicleDetailsArgs(it.vehicleId))
      )
    }
  }

  // the rest of the compose UI
  ...
}

That’s it. Now this screen is compatible with the rest of the app. You might have noticed we’re using ImplementationType param in the annotation that could be one of two values: Fragment or Composable.

But what does it mean? In order to keep the screen compatible with the legacy features the Fragment param will generate a corresponding fragment (so-called fragment entry) that will use the annotated compose function as its content. Of course, we can’t just migrate the entire app to compose at once. Therefore, this is helpful when navigating from the legacy screens to the new compose screens.

Let’s say you’re developing a new product feature with 10 screens using Jetpack Compose. One of those screens will be the external entry point of the feature, meaning that users will navigate to it from other parts of the app. In order for this screen to be compatible with the app codebase, it must also be wrapped in a fragment. This wrapper is generated automatically so that the rest of the app will see this new screen as a fragment and will navigate to it using fragment transactions as usual.

For the remaining 9 screens that are internal in the feature, there is no need to generate a separate fragment for each. Instead, ImplementationType.Composable is used to generate a thin compose wrapper around the screen (so-called composable entry). This way, navigation between screens inside the feature is done purely with compose.

Over time, when more compose screens are added to the app there will be more features that are navigated only from compose screens. These features could completely rely on ImplementationType.Composable even for their external entry points.

At any point in time, for any screen inside the feature, you could change the ImplementationType value and no other code changes would be required. The code will be still compilable including the navigation between screens.

Abstraction over navigation

This is possible due to the abstraction layer over the navigation we’ve built. Obviously, in order to navigate between fragments, transactions should be used. For composable screens, we’re using compose navigation library under the hood. Overall, there are 4 scenarios for navigation between screens that should be covered:

• fragment to fragment — using fragment transactions
• fragment to compose — using compose navigation
• compose to compose — using compose navigation
• compose to fragment — using fragment transactions

However, all of the above is an implementation detail and is hidden from the developer. Instead, we use navigateTo function (as shown in the code snippet above) that provides an abstraction over the navigation and figures out automatically under the hood, which tool for navigation to choose (we will cover it in more detail later in this post).

This means that compose navigation library for example could be replaced with any other solution at any point in time, and not a single code change in feature modules would be required.

This is also handy as we don’t have to reinvent the wheel by implementing a custom navigation graph, backstack, etc as everything is handled for us by the underlying tools.

The thought process

Now that we have seen a brief overview of the architecture, let’s take a closer look at its core components and the thought process behind their design.

The first question we needed to answer with a fragment-based codebase is what is the most straightforward way to start writing composable screens? One of the first solutions that comes to mind is to start wrapping every composable screen with a fragment as shown below.

class VehicleSearchFragment: Fragment() {

  override fun onCreateView(
    inflater: LayoutInflater,
    container: ViewGroup?,
    savedInstanceState: Bundle?
  ) = ComposeView(requireContext()).apply {
    setViewCompositionStrategy(ViewCompositionStrategy.DisposeOnViewTreeLifecycleDestroyed)
    setContent {
      AppTheme {
        VehicleSearchScreen(...)
      }
    }
  }
}

@Composable
fun VehicleSearchScreen(...) {
 ...
}

One great benefit such an approach provides is compatibility with the rest of the app. If there is a need to navigate to or from this screen you could use fragment transactions as you normally do.

Reducing the boilerplate

The example above contains a bunch of boilerplate code that could be moved to a base ComposableFragment class. Therefore, instead of overriding onCreateView every time, developers could just use ComposableContent function instead as shown below.

class VehicleSearchFragment: ComposableFragment() {
    
  @Composable
  override fun ComposableContent() {
    VehicleSearchScreen(...)
  }
}

Temptation to do it the old way

While this is already a solution that might serve the purpose, it has its flaws. Even though our fragment allows writing compose UI, it is still a fragment.

This leads to a temptation to do certain things in an old imperative way using APIs provided directly by fragments. Therefore, this is not quite a proper compose experience as it makes certain parts of the code less flexible and convenient to maintain or refactor.

Ensuring proper compose experience

However, fragments like VehicleSearchFragment could be easily autogenerated ensuring compatibility with other screens that rely on fragments as well as pure compose experience.

Instead of creating a custom fragment that extends ComposableFragment, all we need to do is just annotate a composable function with @UiEntry like shown in the example below.

@UiEntry
@Composable
fun VehicleSearchScreen(...) {
  ...
}

The custom Kotlin Symbol Processor generates the corresponding fragment class automatically providing a proper Jetpack Compose experience for the team.

Navigation

One of the most important aspects of any architecture on Android is navigation between product features and screens. This is especially challenging and important in multi-module projects as it has a direct impact on many aspects of the development process including build times.

Let’s take a look at how navigation between features in the Turo app looked before adopting Jetpack Compose architecture in the figure below.

There are a few key points here worth mentioning.

• The app consists of feature and library modules for the most part.
• No feature modules are not allowed to depend on each other.
• In order to navigate between features a navigation module is used. All features depend on navigation while the latter is not allowed to depend on any feature module.

One great benefit provided by this approach is better build times. This is because changes in a specific feature do not trigger incremental rebuilds of all modules that depend on it (since nothing depends on feature modules except the root app module).

On the other hand, there is still a flaw with this approach. As mentioned earlier, the navigation module cannot depend on any feature, which means that the navigation process lacks type safety.

Let’s have a look at how the feature navigation in the app was organized in the past.

// :navigation

object VehicleDetailsNavigation {
  const val FRAGMENT_NAME = "com.turo.vehicledetails.VehicleDetailsFragment"

  @Parcelize
  data class Args(val vehicleId: String): Parcelable

  fun newInstance(vehicleId: String): Fragment {
    // instantiate fragment using reflection
    val fragment = loadFragment(FRAGMENT_NAME)
    fragment.arguments = bundleOf(
      "args" to Args(vehicleId = vehicleId)
    )
    return fragment
  }
}

Since the navigation module does not depend on feature modules, it is not able to refer to fragments directly. Instead, the app was using a fully qualified name of fragment classes to instantiate them using reflection using a custom loadFragment utility function. Consequently, calling the newIntance factory function returned an instance of a fragment that feature modules could use for navigation.

Overall, as you can see in the snippet above, it was required to write a bunch of boilerplate code in order to navigate from one feature to another.

Destinations concept

When designing the new architecture we wanted to preserve the benefits of the existing navigation approach while mitigating its flaws.

Instead of a bunch of boilerplate code above that forces developers to manually instantiate screen entries, we now operate with the concept of destinations.

The destination is a type that represents a UI screen in a global navigation graph. They should be declared in a navigation module so that every feature could reference them.

// :navigation

@Parcelize
data class VehicleDetailsArgs(val vehicleId: String): Parcelable

class VehicleDetailsDestination(override val args: VehicleDetailsArgs): DestinationWithArgs<VehicleDetailsArgs>

Once declared, it needs to be explicitly connected to a certain UI screen using the @UiExternalEntry annotation as shown below.

// :features:vehicledetails

@UiExternalEntry(VehicleDetailsDestination::class)
@Composable
fun VehicleDetailsScreen(viewModel: VehicleDetailsViewModel = ...) {
  ...
}

It is worth admitting that one piece of information shared earlier in this blog post was not quite correct. We don’t actually use @UiEntry annotation but rather we have 2 its variations which are UiEntry and @UiExternalEntry. We will cover the difference between them shortly in this post.

As a result, a corresponding fragment class is generated.

// generated code

class VehicleDetailsScreenEntry: ComposableFragment() {

  @Composable
  override fun ComposableContent() = VehicleDetailsScreen()
  
  companion object: FragmentEntryFactory<VehicleDetailsDestination> {
    
    fun newInstance(destination: VehicleDetailsDestination): FragmentEntry {
      val fragment = VehicleDetailsScreenEntry
      fragment.arguments = bundleOf("args" to destination.args)
      return FragmentEntry(fragment)
    }
  }
}

From the code snippet above we can see that one of the important parts of each generated fragment is its companion object that serves as a factory for this fragment. On the other hand, a similar factory is being generated for screens that use ImplementationType.Composable along with a corresponding composable entry class, instead of a fragment.

// generated code

@Parcelize
class VehicleDetailsScreenEntry(
    override val args: Parcelable?,
    override val name: String,
) : ComposableEntry(args, name) {

    @Composable
    override fun ComposableContent() = VehicleDetailsScreen()

    companion object: ComposableEntryFactory<VehicleDetailsDestination> {

        override fun newInstance(destination: VehicleDetailsDestination): ComposableEntry {
            val entry = VehicleDetailsScreenEntry(
                args = destination.args,
                name = buildRouteName(VehicleDetailsScreenEntry::class.qualifiedName!!, destination.args),
            )
            return entry
        }
    }
}

Regardless of an implementation type if it is an external entry, its factory is injected to a map with Dagger, and Anvil in particular, using @IntoMap. Consequently, a corresponding Dagger module needs to be generated as shown below.

// generated code

@Module
@ContributesTo(AppScope::class)
object VehicleDetailsNavigationModule {

    @Provides
    @SingleIn(AppScope::class)
    @IntoMap
    @DestinationKey(VehicleDetailsDestination::class) // dagger map key
    fun provideVehicleDetailsEntry(): EntryFactory<*, *> {
        // returning a reference to a companion object.
        return VehicleDestinationEntry
    }
}

For navigation to another screen, a class of a destination is used as a key in order to retrieve a corresponding factory and instantiate the entry.

typealias DestinationsMap = Map<Class<out Destination>, @JvmSuppressWildcards EntryFactory<*, *>>

fun <D : ExternalDestination> DestinationsMap.findEntryFactory(destinationClass: Class<out D>): EntryFactory<D, *> {
    return this[destinationClass] as EntryFactory<D, *> 
}

As a result, when navigating to a destination, the following code should be used.

val destination = VehicleDetailsDestination(VehicleDetailsArgs(it.vehicleId))
navigateTo(destination)

It’s worth mentioning that for screens that don’t accept arguments only a single line is required for declaring a corresponding destination type for them.

// :navigation

object VehicleSearchDestination: DestinationWithNoArgs

Internal navigation

Creating destination types for feature entry points is required to mitigate the fact that the navigation module does not have direct references to specific classes from the feature modules.

In case we need to navigate between screens inside a specific feature module, we could just reference them directly as internal destinations. This also helps to avoid unnecessary code generation required to

In order to understand how internal and external navigation is organized, let’s take a look at the complete hierarchy of Destination types as core architecture components.

We’re already familiar with DestinationWithNoArgs and DestinationWithArgs types that are used to declare destinations for external navigation.

When navigating internally inside a single feature module, there is no need for declaring redundant destinations as all the respective classes could be referenced directly. Therefore, fragment or composable entries are serving as destinations themselves as they are both the descendants of an Entry interface.

For fragments, it's just a simple wrapper class as we want to avoid exposing the fragment instances directly in the feature code.

class FragmentEntry(val fragment: Fragment): Entry

Similarly, the base class for composable entries also inherits the Entry interface.

abstract class ComposableEntry(
  open val args: Parcelable?,
  open val name: String,
) : Entry, Parcelable {

  @Composable
  abstract fun ComposableContent()

  @Composable
  fun ComposableEntry(internalNavController: NavController) {
      ...
      CompositionLocalProvider(...) {
        ComposableContent()
      }
  }
}

As a result, when navigating to another screen inside the same feature module, the following code should be used.

val entry: FragmentEntry = VehicleDetailsEntry.newInstance(it.vehicleId)
navigateTo(entry)

Implementation

As we’ve discovered above, each screen is represented by an automatically generated underlying class that could be either a fragment entry or a composable entry. In general, we want to minimize the number of fragment entries in a codebase and use them only where it’s truly needed (E.g. when navigating from legacy fragment screens).

This means we need to make sure we are able to navigate between different types of entries in a seamless and unified way. Overall, the navigation on the UI level is performed using a concept of side effects which is a stream of the events that is consumed using SideEffectHandler composable function as shown below.

@UiEntry
@Composable
fun VehicleSearchScreen(viewModel: VehicleSearchViewModel = ...) {
  SideEffectHandler(viewModel.sideEffects) { [this: NavigationController]
    when (it) {
      // navigating to another screen
      is VehicleSearchSideEffect.ShowDetails -> navigateTo(
        VehicleDetailsDestination(VehicleDetailsArgs(it.vehicleId))
      )
    }
  }

  // the rest of the compose UI
  ...
}

The SideEffectHandler is a simple library function that consumes the side effects from the flow and emits them one by one.

@Composable
fun <SE> SideEffectHandler(
    sideEffects: Flow<SE>,
    key: Any = Unit,
    handle: NavigationController.(SE) -> Unit,
) {
    val navigationController = LocalNavigationController.current
    LaunchedEffect(key1 = key) {
        sideEffects.collectLatest { navigationController.handle(it) }
    }
}

The handle lambda above has a receiver of NavigationController type that provides an abstraction over the navigation layer in the app. This way, it is available as this context when subscribing to side effects on the UI layer.

The code snippet below provides a simplified version of a navigation controller which is able to handle 2 primary cases for navigation: external and internal. Each time it checks the type of next destination and performs the navigation accordingly.

class NavigationControllerImpl(...) : NavigationController {
  ...

  override fun navigateTo(externalDestination: ExternalDestination) {
      val destinationEntry = destinationsMap
        .findEntryFactory(externalDestination.javaClass)
        .newInstance(externalDestination)
      navigateTo(internalDestination = destinationEntry)
  }

  override fun navigateTo(internalDestination: Entry) {
    when (internalDestination) {
      is ComposableEntry -> navigateToComposable(internalDestination)
      is FragmentEntry -> navigateToFragment(internalDestination)
    }
  }

  // perform a fragment transaction
  private fun navigateToFragment(destinationFragment: Fragment) { 
    ... 
  }

  // add a new route with the compose navigation library,
  // and navigate to it at once.
  private fun navigateToComposable(destinationComposable: ComposableEntry) { 
    ... 
  }
}

With that being said, let’s take a look in more detail at each of the use cases for the navigation between the app screens.

Fragment to compose. Navigating between different types of screens is the most challenging part as it requires bridging two different tools. In our particular case, we’re using compose navigation library for this purpose. However, its API is not exposed directly to engineers, and thus, any navigation solution could be used in its place under the hood.

When we’re navigating from fragments to compose, we’re using compose navigation. This is possible by using a simple trick that sets up a NavHost composable for every fragment entry and has all its contents as a root destination by default.

abstract class ComposableFragment : Fragment() {

  @Composable
  abstract fun ComposableContent()

  override fun onCreateView(...) = ComposeView(...).apply {
    setViewCompositionStrategy(ViewCompositionStrategy.DisposeOnViewTreeLifecycleDestroyed)
    setContent {
      AppTheme {
        ...
        NavHost(..., startDestination = "@root") {
          composable("@root") {
            ComposableContent()
          }
        }
      }
    }
  }
}

When navigation to a composable screen is needed, a new destination is dynamically added to the NavHost inside of the NavigationController as shown in the example below.

import androidx.navigation.NavController

class NavigationControllerImpl(
  private val internalNavController: NavController,
  private val exploredEntries: MutableMap<String, ComposableEntry>
) : NavigationController {
  ...

  private fun navigateToComposable(destinationComposable: ComposableEntry) {
    val route = destinationComposable.name

    if (internalNavController.graph.findNode(route) == null) {
      // keeping track of dynamically added entries
      // will be handy later, when we will be talking
      // about handling configuration changes
      exploredEntries[route] = destinationComposable      

      val navigator = internalNavController.navigatorProvider
        .getNavigator(ComposeNavigator::class.java)

      val destination = ComposeNavigator.Destination(navigator) {
        destinationComposable.ComposableEntry(...)
      }
      destination.route = route
      internalNavController.graph.addDestination(destination)
    }

    internalNavController.navigate(route)
  }
}

In this context, a destination is not a concept we’ve discussed earlier but rather a class from the compose navigation library.

Compose to compose. This is a pretty straightforward case, as the navigation between composable screens would be done similarly as above using the compose navigation library under the hood.

When navigating to a compose screen a respective destination is being added to a navigation graph dynamically similarly to what was described above.

Compose to fragment. When navigation to a screen that uses legacy fragments is required, a fragment transaction is performed between the fragment that hosts the composable navigation graph (NavHost in our case) and the next destination fragment.

Handling configuration changes

Compose navigation library does not retain dynamically added destinations on configuration changes. However, this is how all the destinations are being added in the NavigationControllerImpl as we saw above. Therefore, every time the UI state is restored, all of them will be lost.

When restoring the state, NavHost will recreate only those destinations that are explicitly defined using a composable function in its builder. By default, our NavHost has only the original root destination declared, as we have already seen.

// inside onCreateView of ComposableFragment

NavHost(..., startDestination = "@root") {
  composable("@root") {
    ComposableContent()
  }
}

This means that all the dynamically added destinations will be lost after NavHost is recreated. This may cause the app to crash, as the navigation library will try to restore the back stack that remembers routes that no longer exist.

To solve this issue, every time NavHost is recreated, we need to ensure that we consider all the routes that were added dynamically by storing the respective ComposableEntry instances with rememberSaveable.

// survies configuration changes
val exploredEntries = rememberSaveable(...) { 
  mutableMapOf<String, ComposableEntry>() 
}

NavHost(..., startDestination = "@root") {
  composable("@root") {
    ComposableContent()
  }

  // restoring dynamically added routes
  for ((route: String, entry: ComposableEntry) in exploredEntries) {
    composable(route) {
      entry.ComposableEntry(...)
    }
  }
}

If you remember, we register each ComposableEntry in the exploredEntries every time we perform the navigateToComposable navigation in the NavigationControllerImpl.

All the instances of ComposableEntry type implement Parcelable which makes it easy to serialize/deserialize them during configuration changes.

To conclude

When discussing the architecture of Android apps, topics like dependency injection, view models, and domain/data layers often come up. However, this story intentionally avoids focusing on them, as they can all seamlessly integrate into the setup described here.

There are various libraries and patterns for implementing view models available out there. All of them could be integrated with the architecture described here. Similarly, if you need to configure the dependency injection tool of your choice, a corresponding setup could be made in the base classes like ComposableFragment, ComposableEntry and their specific descendants that are generated.

When migrating an Android codebase to Jetpack Compose it is crucial to provide a proper developer experience from day one. Continuing to rely on legacy APIs significantly prolongs their presence in the codebase, making development and maintenance more complex and less flexible. This can restrict the engineering team from fully experiencing the benefits of using Jetpack Compose.

A highly effective approach for achieving this goal is leveraging code generation. It serves the purpose of concealing a boilerplate code, primarily aimed at ensuring compatibility with the legacy stack. Another notable advantage of utilizing code generation is the flexibility it offers in modifying the implementation of a symbol processor or base architecture classes. Because the codebase relies on annotations, updates, and adjustments can be made to the underlying core components at any time, with minimal or no code changes required.

Adopting Jetpack Compose helped the engineering team at Turo to be much more efficient when working on product features while keeping the development process more enjoyable and less error-prone.

Designing Jetpack Compose architecture for a gradual transition from fragments on Android was originally published in Turo Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

Mobile performance at Turo

The startup time of a mobile app is one of the most important indicators of its performance and has a significant impact on the user experience. A fast-loading app not only provides a positive first impression, but also increases engagement and retention, reduces user churn, and can improve visibility in app store rankings.

In this story, we would like to share our experience of reducing the startup time of the Turo Android app. We are going to cover, what improvements we were able to achieve, what steps we performed and how are we measuring it.

We reduced the cold startup time of Turo Android app by 77% on average.

The same metric was improved by 84% at the 50th percentile. The figure below shows a comparison of reported metrics before and after we improved the startup time of Turo’s Android app. All the values are measured in milliseconds.

The illustration below demonstrates how the application looks and feels before and after the improvement that is already available for 50% of our users.

The duration of the startup before directly depended on the network connection. Therefore there might be cases where it was slightly faster but it could also take even longer to start the app. This is not the case after the improvement.

The improvement

Before jumping into the specifics of the improvements we’ve made, it’s worth examining the startup process of the Turo app prior to the optimization efforts.

The startup process of the app consisted of the following stages:

• App initialization. This includes the application process initialization which the developers have little control over. In addition, it includes all the code, the application runs before rendering the first UI frame. Android Vitals reported the end of this stage as startup complete.
• Synchronous network requests. The app was performing a number of network requests while showing a custom splash screen before allowing the user to see a home screen.
• Custom splash animation. After the network requests were completed, the app was running a custom splash animation that takes roughly 1 second. After that, the app navigated from SplashActivity to HomeActivity.
• Home skeleton. At this point, the user is able to partially interact with the app while waiting for the home content to load and seeing a shimmer animation. While this stage was already cacheable, there were some improvements required there as well.

Splash screen

One easy way we were able to improve the startup time of the app was by removing a custom splash animation that was displayed on each launch. While the animation was part of the design language, it was launched after all the synchronous network requests during startup, causing a delay in the overall startup time. By removing the animation, we were able to save approximately 1 second.

Now that we’ve tackled this item, let’s move on to more technically interesting aspects of startup improvement.

Initially, we used a dedicated SplashActivity to run all the startup work before routing the app to the HomeActivity. However, the latest guidelines advise against this approach. Therefore, we eliminated the redundant SplashActivity and transferred all the startup logic to our root activity by leveraging the Splash Screen API. This allowed for a unified experience across all Android versions and, as a bonus, improved our startup metrics in the Google Play Console’s Android Vitals as shown in a scheme below.

If an app displays a custom image or animation as a splash screen, the startup time metric in Android Vitals may not accurately reflect the actual startup time. This is because the time spent displaying the custom screen is not counted as part of the startup process. To address this issue, using a Splash Screen API can help explicitly define when the startup process is complete, resulting in more accurate reporting.

Deferring synchronous network requests

Our app was performing a series of network requests while displaying the splash screen in order to fetch the necessary data before users could interact with it. This led to a noticeable slowdown in the startup process of the app, particularly when the network connectivity was poor.

In addition, the app was performing a different number of startup network requests depending on whether the app is used in guest, host modes, or unauthenticated. This resulted in inconsistent experiences for different types of users.

As an example, if the app is used in guest mode, a few of the requests help to decide which screen should be shown after the splash screen. By default, it's the home screen. However, there are special cases where the user could be redirected either straight to an active vehicle reservation or to a feedback screen where they can rate their last experience booking a vehicle.

Since in the majority of cases, it will be a home screen, we don’t want to slow down every app startup by checking for a minority of scenarios. Therefore, we now open a home screen by default while making those network requests asynchronously. If any redirect is required, a corresponding screen is displayed on top of a home screen.

Fetching feature flags

While it’s a relatively straightforward optimization in many cases, there are network requests that require special handling. When fetching feature flags from the network, it is not sufficient just to run the network request asynchronously.

If no feature flag is requested immediately after the app startup, the home screen contents are displayed instantly with no issues.

However, what if we need to use a feature flag on a home screen? In this case, the network request won’t make it in most cases. This results in using the value from the cache which might be outdated or absent in many cases which in particular may lead to incorrect results for A/B tests.

To solve the problem, we’re starting to fetch feature flags in the background right on app launch. If any feature flag is required before the request is complete, such a call is suspended until they are fetched from the server. Meanwhile, we’re showing a home screen skeleton with a shimmer animation. All the subsequent feature flag reads in the app are instant as shown in the figure below.

In order to avoid showing the loading skeleton on each subsequent app startup, we’re using a short-term cache for feature flags. This could be a few hours, a day, or a few days. We are still experimenting with the exact cache expiration values.

Baseline Profiles

After we removed all the synchronous network requests our startup duration became more deterministic and now it makes sense to apply Baseline Profiles. This is the feature that helps to pre-compile startup code paths ahead of time and boost the app startup time.

Applying baseline profiles to our app resulted in approximately 15% of improvement according to Macrobenchmark results (when compared to the run with no compilation applied).

Optimizing disk I/O operations

When investigating the ways to improve startup times for our app, we noticed that it performs a bunch of disk I/O operations during the startup.

Strict mode violations. StrictMode is a tool that among other things helps to detect accidental disk I/O operations performed on a main thread. Such operations are especially unwelcome during the application’s startup and it is recommended to defer them or move to a background thread. This tool should be used for debug builds only. When configured, it will post events in logcat that look like the example below and include stack traces that help to identify the source of the issue.

StrictMode policy violation; ~duration=107 ms: android.os.strictmode.DiskReadViolation

This helped us to identify a bunch of reads from the local storage on the UI thread that could be moved to the background.

Shared preferences. When investigating logs from strict mode, we identified that a bunch of the issues, in particular, were caused by reads from SharedPreferences. Therefore, some of them were moved to a background thread. Others, however, needed to be performed before the home screen is displayed, so the code that accesses them was deferred until the very end of the app initialization.

It is important to emphasize, that SharedPreferences start reading from the disk the moment the object is initialized according to the documentation of context.getSharedPreferences

Retrieve and hold the contents of the preferences file ‘name’, returning a SharedPreferences through which you can retrieve and modify its values.

context.getSharedPreferences("my-prefs", Context.MODE_PRIVATE)

Often, these objects are eagerly initialized and injected into constructors using dependency injection, which can lead to early disk reads on the UI thread.

Lazy initialization

A quick solution for the issue with SharedPreferences is to ensure they are being initialized lazily. If Dagger is used as a dependency injection framework in a project, the dagger.Lazy could help to achieve this goal as shown in the example below.

class LocalDataSource(val prefs: dagger.Lazy<SharedPreferences>) { 
  
  fun getData(): String? {
    return prefs.get().getString("data", null)
  }
}

In addition, the lazy injection could be used for other types of classes that might perform extensive work on the UI thread during their initialization.

Application lifecycle callbacks

Another factor that could negatively impact the startup time is the callbacks that are tied to the app’s lifecycle:

• Application.ActivityLifecycleCallbacks — and especially its functions onActivityCreated, onActivityStarted, and onActivityResumed.
• FragmentManager.FragmentLifecycleCallbacks — and especially its functions onFragmentCreated, onFragmentViewCreated, and onFragmentResumed.

Those are easy to miss at the first glance but they could hold a heavy initialization code that would obviously, slow down the app startup time. Moreover, those callbacks could be implicitly used by other third-party SDKs.

Third-party SDKs

Speaking of third-party SDKs. Many of them suggest they should be initialized in the Application.onCreate. Unfortunately, in some cases, their initialization logic might not be the most efficient in terms of performance. While some of them are pretty easy to fix just by moving their initialization in a background thread or even deferring it until they are actually used, others might be more tricky and take more effort to remove or adapt them.

As an example, we’re using an SDK that needs to be tied to the lifecycle of every Activity. Moreover, it is implicitly initialized under the hood the first time onActivityCreated is called performing disk I/O and other operations in the UI thread slowing down the app startup. While it’s possible to improve its performance during the initialization it requires additional effort and such cases are something one should be prepared to deal with.

Home screen initialization

While the Turo Android app already used a local cache for the home screen contents we’ve found an issue that forced the app to show the loading skeleton on every app startup. It turned out one of the network requests at one point started to return a nullable value where a non-null field was expected on a client. This caused the serialization error but was suppressed by one of the RxJava operators like onErrorResumeNext. Eventually, this led to a portion of the home screen contents to be always requested from the network causing a loading delay, since it was always failing to be cached.

Measuring the improvement

Making performance improvements is surely an important task, but measuring it is essential.

Configuring an A/B test

The described startup improvement is already available to 50% of our users as part of the ongoing A/B test. Since we got rid of the old SplashActivity and moved all the startup logic to the HomeActivity, the legacy startup configuration is being simulated in the latter with the help of splash screen API which covers the screen while the old network requests and I/O operations are being performed.

In order to decide whether the user should be placed in control (slow startup) or treatment (fast startup) we don’t use a traditional feature flag requested from the remote server. This is due to the fact, that it should be requested very early in the app lifecycle which may lead to issues with consistency. Instead, we use a pretty straightforward method to divide users into experiment groups locally on the device, ensuring a 50/50 split as shown below.

val deviceId: String = <locally generated and cached UUID>

val variant = when (abs(deviceId.hashCode() % 2)) {
    0 -> Variant.SLOW_STARTUP
    1 -> Variant.FAST_STARTUP
    else -> error("unreachable branch")
}

This code narrows down a string into one of two possible numbers: 0 or 1 where each of them is associated with a corresponding variant. In case the string is a randomly generated UUID, the 50/50 split is guaranteed. In our case, we use a locally generated and cached deviceId.

The experiment is presently in progress, and we are actively gathering and assessing the data.

Measuring the startup time

In addition, we needed to measure the startup time of the app itself. We could not rely on tools like Android Vitals as we needed to have a clear distinction between both variants of an A/B test. Instead, we needed a simple tool that allows identifying a cold startup time and reporting it to our analytics under the corresponding experiment variant.

In order to measure the startup time, we needed to identify 2 points in time: startup beginning and end.

Startup beginning. We consider a time when the system calls ContentProvider.onCreate a starting point for measurements. Why content provider? Simply because content providers are one of the first things written by the developer that is initialized in the app, even before the application class.

We also track the time since the process started using Process.getStartUptimeMillis. However, the majority of the app process initialization is not under the developer’s control, so counting the startup time from this point might be slightly redundant. Therefore, we rely on the former value in the scope of this blog post.

Startup end. Since we’re using a splash screen API it might come in handy while identifying when a startup is complete. It has a setKeepOnScreenCondition callback that is called when a splash screen is about to be closed. Under the hood, it’s just OnPreDrawListener. The most straightforward way to do it is shown below.

class HomeActivity : AppCompatActivity() {
  
  override fun onCreate(...) {
    val splashScreen = installSplashScreen()
    super.onCreate(...)

    splashScreen.setKeepOnScreenCondition {
      handler.postAtFrontOfQueue {
        reportStartupComplete()
      }
      false
    }
  }
}

We report the app startup time as a difference between the end and beginning points while a timestamp value for each of them is measured using SystemClock.uptimeMillis call.

If you would like to know more about what metrics to pick in order to measure the Android app startup time or how to identify a cold startup, we highly recommend checking this series of blog posts from Pierre-Yves Ricau: 1, 2, 3.

The issue?

Regardless of what metric is being used as a startup beginning, after analyzing the reported data we’ve noticed that the app reported a bunch of enormously large values (e.g. in some cases the app reported startup to take minutes, hours, or even days). As it turns out, in some cases, the app process might be started way before the user clicks on the app icon to launch the app.

After analyzing the source code of existing startup monitoring solutions on Android like Firebase, we can see this issue is handled by simply ignoring any value that is greater than 60 seconds. Therefore, we followed a similar approach.

Verifying the data

But how can we confirm that filtering out all values greater than 60 seconds will keep the reported metrics precise?

What helped us to verify it is the fact we‘re running a startup A/B test in 2 iterations. The reader might remember, the first change we made was removing a custom splash animation that takes roughly 1 second. This was the only change for the first iteration of the experiment and it provided a static difference in startup time between the control and treatment.

We analyzed the reported metrics while filtering out all the values greater than 60 seconds. By doing so we observed a static 1-second difference at each percentile between experiment groups. On the other hand, when the filtering was not applied, the difference was growing noticeably the closer we moved to the 99th percentile. Therefore, we confirmed that filtering out values greater than 60 seconds produces the correct result.

Learnings

There are multiple reasons why the startup process of the app might be slowed down. It’s important to start the improvement with those tasks that require the least effort and produce the maximum result. When moving to the other side of the equation, it’s always important to evaluate each step and see if it is worth the effort as compared to the possible improvement it provides.

Due to the significant difference in performance metrics between before and after states, this project helped to ignite interest in other areas of mobile performance and developer productivity both on Android and iOS platforms at Turo.

While improving startup time is a challenging task, measuring it brings its own additional challenge. There is no simple API on Android that would provide it. Finding a proper way to report startup metrics requires trial and error while testing every idea or hypothesis is slowed down by the product release process and its gradual rollout to the users.

In many cases, engineering faces a conflict between allocating time and resources either on product work or performance optimization. However, treating performance as a standalone product feature is inevitable for its success.

Resources

• App startup time — developers.android.com
• Baseline Profiles — developers.android.com
• StrictMode — developers.android.com
• Android Vitals. Why did my process start? — blog by P.Y. Ricau
• Android Vitals. When did my app start? — blog by P.Y. Ricau
• Android Vitals. First draw time — blog by P.Y. Ricau
• firebase/firebase-android-sdk — github.com

How we reduced our Android startup time by 77% was originally published in Turo Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

Android developers have a number of tools in their arsenal for detecting memory leaks such as Android Studio Memory Profiler, LeakCanary, Perfetto, etc. These tools are useful when analyzing app builds locally. However, in production the app is running on a wide range of devices in different circumstances and it is hard to predict all of the edge cases when profiling the build locally.

At Lyft, we were curious about how our apps behave in production on users’ devices. Thus, we’ve decided to bring observability to various runtime performance metrics and see how it could improve the user experience.

We’ve already published a blog post about CPU usage monitoring and in this story, we will focus on the memory footprint of mobile apps. While the overall concept of monitoring the memory footprint is applicable to both Android and iOS platforms, we will focus on the former for implementation details.

Lyft relies on A/B testing when rolling out new features. When a feature is ready for production, it’s covered by a feature flag and is launched as part of an experiment. This experiment is run for a certain group of users in order to compare metrics against the standard version of the app.

When a large and complex feature is released, it is important to make sure it does not bring any regressions in terms of memory usage. This is especially important if the feature includes native C/C++ code which has a higher chance of introducing memory leaks.

Therefore, we wanted to test the following hypothesis. For each feature experiment, we measure its memory footprint across all users that have access to it (by reporting metrics to analytics at runtime). Then, we compare it to the standard version of the app. If the variant shows larger memory usage values, this is an indicator of a regression or memory leak.

Memory footprint metrics

First, we needed to identify the availability of memory metrics on Android, which are not as trivial to collect as one might think. We are interested in the memory usage by the application process or in other words the app’s memory footprint.

Android provides various APIs for retrieving memory usage metrics for apps. However, the hardest part is not retrieving the metrics but making sure they are suitable and provide meaningful data.

Since Android Studio has a built-in memory profiler, we decided to use it as a reference point. If we get the same value as the memory profiler, our data is correct.

One of the primary metrics the Android Studio memory profiler shows is called PSS.

PSS

Proportional set size (PSS) — the amount of private and shared memory used by the app where the amount of shared memory is proportional to the number of processes it is shared with.

For example, if 3 processes are sharing 3MB, each process gets 1MB in PSS.

Android exposes a Debug API for this data.

Debug.MemoryInfo includes PSS as well as the number of components it consists of. The easiest way to view the summary of the data it holds is by calling the getMemoryStats function. It yields key-value pairs with the metrics as shown in the example below.

These are the numbers Android Studio normally displays in the Memory Profiler.

In order to get the PSS value without any additional info, it is possible to use the call below.

USS

Unique set size (USS) — the amount of private memory used by the app excluding shared memory.

Its value can be derived from the PSS metrics we’ve seen above. In order to get it programmatically, we can again use Debug.MemoryInfo.

What’s wrong with PSS and USS?

PSS and USS are useful but calling Debug.getMemoryInfo and Debug.getPss can take at least 200ms and 100ms respectively.

We need to report memory metrics regularly, so it’s not the best idea to use time-consuming APIs for this.

There is a faster Android API for PSS, but there is a catch. It has a hard sample rate limit of 5 minutes. This means if called more frequently, it returns a cached value from a previous call. This won’t serve our use case well.

However, there is a similar metric called RSS.

RSS

Resident set size (RSS) — the amount of private and shared memory used by the app where all shared memory is included.

For example, if three processes are sharing 3MB, each process gets 3MB in RSS.

This means that RSS values are pessimistic as they show more memory than the application has actually used. This metric is much faster to retrieve compared to PSS. Moreover, it is fine to use RSS values because we are more interested in comparing variants of the A/B experiment so that we can sacrifice precision to some extent here as a tradeoff.

Overall, if comparing set size metrics at any given point in time, USS would always show the smallest value while RSS is the largest: RSS > PSS > USS.

In order to get RSS programmatically, we need to refer to a system file. This file is located at /proc/[pid]/statm, where [pid] is the ID of an application process. android.os.Process.myPid() can be used to get [pid] programmatically.

Reading this file yields something like this:

3693120 27503 18904 1 0 319129 0

Official Linux documentation helps to shed light on the meaning of these numbers. We are only interested in the second value.

• (2) resident — resident set size, represented in pages.

The default page size on Linux is 4 kB. Therefore, in order to calculate the RSS metric we use the simple formula below.

rssKb = resident * 4

We ended up using RSS as a primary metric for identifying the app’s memory footprint.

However, that is not all. Memory, private to the app process, includes many components and one of them is the heap.

In order to increase the precision of measurements, we can additionally report the amount of memory allocated by the app in the JVM and native heaps. This might come in handy when trying to narrow down a regression detected with the RSS metric.

JVM heap

The first metric will help us to identify the amount of memory allocated by the app in the JVM heap.

Native heap

The second metric shows the same but in the native heap. It is especially useful when the app includes custom native C/C++ libraries.

Detecting memory leaks

Now that we have identified memory usage metrics, let’s see how to use them to catch regressions.

First, we need to decide when and how often should we report memory metrics to the analytics. We have picked two scenarios:

• Report a snapshot with metrics every time a UI screen closes.
• Report a snapshot with metrics periodically if a user stays on a single UI screen for a long time. Normally, we use 1-minute intervals but this can be configured remotely.

Now, let’s see how to interpret the data.

A/B experiments allow us to compare reported values between two app variants:

• treatment — the group of users that use the app with the new feature enabled.
• control — the group of users that use the app in a normal state with the new feature disabled.

Example 1 — no regressions

First, as a baseline, we will take a look at a feature which has not introduced any regressions in terms of memory footprint.

This is an example of an experiment that adds a feature to the Lyft Android app for passengers.

As we can see above, both control (green line) and treatment (orange line) variants are the same. This means that the feature has not introduced any regressions and is safe to roll out to production from a memory usage perspective.

Example 2 — regression

Now let’s take a look at a feature that introduced a regression.

This is an example of an experiment that adds a feature to the Lyft Android app for drivers.

The new feature here has clearly increased the app’s memory footprint at each percentile. This is an indicator of a regression that allowed us to identify a memory leak.

This graph is based on the RSS metric. In order to narrow down the root cause of the issue similar graphs with JVM and native heap allocations were used.

Example 3 — memory leak at 99th percentile

The final example is the most important as it demonstrates the biggest advantage of this memory monitoring approach.

In the graph below both variants show almost the same values, except for a noticeable difference around the 99th percentile.

The memory footprint of the treatment variant has significantly increased at the 99th percentile.

This led to identifying a memory leak that occurred in very specific circumstances for a small number of users. However, when it occurred it significantly increased memory usage.

In the case of the second example, it is more likely to detect a memory leak that affects all usages of the app when profiling locally. However, it becomes a much harder task with the third example as the memory leak was related to an edge case which is easy to miss locally.

Learnings

One of the challenges with implementing such a memory monitoring tool is to pick the right metrics that show valid data. On the other hand, it is important that collecting those metrics is not time- or resource-consuming.

Another task is to visualize the data in an effective report. Comparing the average values between control and treatment variants on a daily basis does not produce meaningful data. A better approach is to use a percentile distribution from the very beginning of the experiment as shown in the examples above.

Overall, the longer the experiment runs the better data is. It requires a few days to start getting meaningful data after an experiment launch. There is also a dependency on how many users are exposed to the experiment.

This approach is especially useful when a memory leak appears around the 99th percentile. This means a memory leak happens due to a specific edge case that would be much harder to detect with local profiling.

Using tools for local memory leak detection is an important task to prevent promoting regressions to users. Reporting performance metrics at runtime shines a light on issues that would be much harder to detect otherwise.

Resources

• Memory allocation among processes — developers.android.com
• Understanding Android memory usage — Google I/O ‘18
• How do I discover memory usage of my application in Android? — stackoverflow.com
• proc(5) — Linux manual page

If you’re interested in working on tooling and performance at Lyft then take a look at our careers page.

Detecting Android memory leaks in production was originally published in Lyft Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

Bazel for Vulkan projects

This is the second part of a series of blog posts about building projects that use Vulkan graphics API with Bazel build system. In the first part, we performed an environment setup for a simple Vulkan project that uses GLM and GLFW libraries. In this blog post, we are going to expand our knowledge and see how to build GLSL shaders with Bazel and run a project that draws a triangle.

Be sure to check part 1 before proceeding with this blog post.

You can find a complete source code of a sample project on GitHub.

GitHub - Morfly/vulkan-bazel-samples: A sample repo for setting up an environment for applications that use Vulkan graphics API built with Bazel

Building shaders

OpenGL Shading Language (GLSL) — is a high-level shading language with a syntax based on the C programming language. It is also supported by Vulkan.

We are going to start with creating simple vector and fragment shaders for building a triangle. The source code was taken from the official Vulkan tutorial, so feel free to check it out for more details about the shaders code itself.

Create a shader.vert file and put it in the triangle/shaders directory in the project we used in part 1 of this series.

Similarly, create a file for a fragment shader called shader.frag under the triangle/shaders directory. Add there the code below.

Now, we are ready to create a Bazel target that is going to build our shaders. We are going to use a glsl_shader rule from rules_vulkan we previously included in the project. Create a BUILD file in the same directory and populate it with the following code.

To verify all was done correctly, run the following commands in the terminal and make sure shaders are built successfully.

bazel build //triangle/shaders:vert_shader

bazel build //triangle/shaders:frag_shader

Here is the directory structure we have so far.

vulkan-bazel-samples
├── triangle
│   └── shaders
│       ├── shader.frag
│       ├── shader.frag
│       └── BUILD
│
├── env_setup
├── third_party
└── WORKSPACE

Finally, we are ready to build our application that will use these shaders and draw a triangle.

Drawing a triangle

In order to build the app that draws a triangle, we will use a source code from an official Vulkan tutorial. Create a main.cpp file and place it in the triangle directory. Fill it with the source code copied from the Vulkan tutorial.

We won’t be focusing on the code itself as everything would be identical to the Vulkan tutorial. However, we would need to do a slight correction to the code for our project. Open main.cpp file and find a createGraphicsPipeline function declaration. Here, we would need to edit its first 2 lines where we change paths to our compiled shaders as shown below.

Now, the only thing left is to define a Bazel target that will build and run our program. To do so, create a BUILD file inside a triangle directory. We are going to use a standard cc_binary rule.

In the deps parameter we need to include glfw and glm libraries we defined in the previous blog post. In addition, we need to add a Vulkan library itself.

In the data parameter, we are referencing the shader targets we’ve just created.

Eventually, the final folder structure of our sample project looks like below.

vulkan-bazel-samples
├── triangle
│   ├── shaders
│.  │
│   ├── main.cpp
│   └── BUILD
│
├── env_setup
├── third_party
└── WORKSPACE

Running the app

This is all we need to run a triangle Vulkan app with Bazel.

Now, use the following command to build and launch our application.

bazel run //triangle

If all is done correctly, it will run an app that draws a triangle on the screen as shown below.

Conclusion

This is it! In this short series of blog posts, we’ve seen how to perform a basic setup to be able to use Bazel in projects with Vulkan graphics API.

In part 1 we performed an environment setup for the project and now we ran a basic triangle app built with Bazel.

All the source code from this blog post could be found on GitHub.

GitHub - Morfly/vulkan-bazel-samples: A sample repo for setting up an environment for applications that use Vulkan graphics API built with Bazel

References

• rules_vulkan — a repository that enables Bazel support for Vulkan projects, created by Juan David Adarve.

Bazel in Vulkan Projects. Part 2 — Shaders was originally published in CodeX on Medium, where people are continuing the conversation by highlighting and responding to this story.

Bazel for Vulkan projects

In this blog post, we will see how to set up an environment for Vulkan projects built with Bazel. Then, in the second part, we are going to see how Bazel can build GLSL shaders for Vulkan.

Vulkan — is an open standard for 3D graphics and computing that enables cross-platform access to GPUs. It targets high-performance real-time 3D graphics applications, such as video games and interactive media. You can learn more about Vulkan from its official page.

Bazel — is an open-source build system with advanced local and distributed caching, optimized dependency analysis, and parallel execution. It supports a wide variety of languages including C++. You can learn more about Bazel from its official page.

We will stick closely to Vulkan’s official environment setup guide but build everything with Bazel. To do this, we are going to use the rules_vulkan project.

In addition, we will set up tools that are usually used along with Vulkan such as:

• GLM — a library for linear algebra operations.
• GLFW — a cross-platform API for creating windows.

You can find a complete source code from this blog post on GitHub using the link below.

GitHub - Morfly/vulkan-bazel-samples: A sample repo for setting up an environment for applications that use Vulkan graphics API built with Bazel

Prerequisites

Installing Bazel

This blog post assumes you have a Bazel (or its wrapper, Bazelisk) installed on your machine. Visit the official documentation to learn how to do it.

Downloading Vulkan SDK

Before doing any Bazel setup, we must download and install Vulkan SDK to our machine. This step would be exactly the same as you would follow the official Vulkan documentation.

• macOS. Follow only the Vulkan SDK section from the official Vulkan tutorial for macOS.
• Linux. Follow only the Vulkan Package section from the official Vulkan tutorial for Linux.
• Windows. Follow only the Vulkan SDK section from the official Vulkan tutorial for Windows.

Setting up the project

As usually with Bazel projects, we must initialize the project workspace. To do this, in the root directory of the project (let’s call it vulkan-bazel-samples) we need to create a file named WORKSPACE.

vulkan-bazel-samples
└── WORKSPACE

Configuring Bazel for Vulkan

First, we need to add Vulkan support to our Bazel project. We are going to use the rules_vulkan repo for this. Open WORKSPACE file and fill it with the code below.

Here we are fetching rules_vulkan as a git_repository and configuring it in the project using vulkan_repositories macro.

We will see how to use it later in the blog post. However, before that, we need to configure additional third-party libraries that are usually used in Vulkan projects.

Configuring GLM

GLM — is a library for linear algebra operations.

First, we need to make it available in our project. To do this, we will use a http_archive build rule which will download the sources from a GitHub archive.

This way we are fetching the library sources in our project and we need to configure a BUILD file that will tell Bazel how to build it. We pass the path to this file as build_file parameter above. This file would be placed in the root directory of the fetched library.

Obviously, we would need to create this BUILD file. We will need to place it under the third_party/glm folder and call it glm.BUILD. Below are its contents.

Nothing fancy here, as we’re just telling Bazel where to get source files for the library.

After the actions above, the GLM library will be available as an external workspace @glm. For easier usage, we can create a simple alias for it. To do this, create a third_party/glm/BUILD file and populate it with the contents below.

Below is the file structure of the project so far.

vulkan-bazel-samples
├── third_party
│   └── glm
│       ├── glm.BUILD
│       └── BUILD
│
└── WORKSPACE

Next, we will include a GLFW library in the project.

Configuring GLFW

GLFW — is a cross-platform API for creating windows.

The algorithm for adding it to the project is similar to GLM. However, we would need to perform a bit more sophisticated configuration. Append the following code to the WORKSPACE file.

Similar to GLM, we need to specify a BUILD file for the GLFW library. To do this, under the third_party/glfw directory create a file named glfw.BUILD. Next, we will need to populate it with the contents.

First, for each of the supported operating systems, we need to pick the right set of implementation source files, define statements, and linker flags. For the sake of saving space, the below snippet defines the corresponding variables but omits their values. However, the full code for this file could be found on GitHub.

Next, we need to define a cc_library target that will build those sources either for Linux or Windows operating systems.

Similarly, to build the GLFW sources for macOS, we need to define an objc_library target.

Finally, we are defining a public Bazel target that links GLFW API headers with the implementations we defined before.

In addition, create a third_party/glfw/BUILD file that defines simple alias for the external @glfw repository.

Here is the updated file structure we have so far.

vulkan-bazel-samples
├── third_party
│   ├── glm
│   │
│   └── glfw
│       ├── glfw.BUILD
│       └── BUILD
│
└── WORKSPACE

Writing and building Vulkan code

Now, we are ready to add some C++ code that uses Vulkan API. It won’t do anything fancy, just show an empty window and print the list of Vulkan extensions. This is sufficient to demonstrate that the project was configured correctly.

Create a main.cpp file under the env_setup directory. Fill it with the code below, which is taken from the official Vulkan tutorial.

Next, we need to add a BUILD file for our source code under the env_setup directory.

We are defining an env_setup binary target that uses both glfw and glm libraries we configured before. In addition, it depends on vulkan_cc_library from the @rules_vulkan external workspace. This is how we enable Vulkan support for this target.

Below you can find the updated project structure.

vulkan-bazel-samples
├── env_setup
│   ├── main.cpp
│   └── BUILD
│
├── third_party
└── WORKSPACE

Running the code

Finally, we are ready to build and run the project with Bazel. To do so, run the following command in the terminal.

bazel run //env_setup

If all is done correctly, you should see an empty window and a bunch of Vulkan extensions printed in the console.

Conclusion

That’s it! In this blog post, we have seen how to set up a project that uses Vulkan graphics API and build it with Bazel using rules_vulkan repo. In addition, we have seen how to add GLM and GLFW libraries to such a project that serve as integral companions when working with graphics APIs.

In part 2 we will see how to build GLSL shaders with Bazel and apply this knowledge to run a project that draws a triangle.

All the source code from this blog post could be found on GitHub.

GitHub - Morfly/vulkan-bazel-samples: A sample repo for setting up an environment for applications that use Vulkan graphics API built with Bazel

References

• rules_vulkan — a repository that enables Bazel support for Vulkan projects, created by Juan David Adarve.

Bazel in Vulkan Projects. Part 1 — Environment Setup was originally published in CodeX on Medium, where people are continuing the conversation by highlighting and responding to this story.