Metro Extensions

A Kotlin compiler plugin that extends Metro. It uses Metro's extension API to generate additional DI declarations at compile time, bridging Square-internal annotations with Metro's DI graph.

Note: This project is specific to Square's codebase and is not intended for external use. It serves as a reference for how to write compiler plugins that extend Metro. All APIs used — both Metro's extension API and Kotlin's compiler plugin API — are highly experimental and will break between versions. If you want to extend Metro for your own project, see the Generating Metro Code documentation.

What it does

For detailed descriptions of all annotations including generated output examples, see docs/use-cases.md.

Supported annotations

@ContributesMultibindingScoped(scope: KClass<*>)

Contributes a class as a scoped multibinding into a Metro dependency graph. The annotated class must implement mortar.Scoped. At compile time, the plugin generates a @ContributesMultibinding provider scoped with @SingleIn for the given scope, so the class is automatically included in Set<Scoped> within the target graph.

@ContributesRobot(scope: KClass<*>)

Contributes a UI test robot class to a Metro dependency graph. The annotated class must extend ScreenRobot or ComposeScreenRobot. At compile time, the plugin generates a nested @ContributesTo interface with an accessor function (get{ClassName}()), so the robot is automatically available on the @DependencyGraph without manually writing a component interface.

Usage

Apply the Gradle plugin to your project:

plugins {
  id 'com.squareup.metro.extensions'
}

Development

To build and test against a local checkout of Metro (expected at ../metro), pass the -PuseLocalMetro flag:

./gradlew :compiler:test -PuseLocalMetro

This includes the Metro project as a Gradle included build and substitutes the dev.zacsweers.metro:compiler, dev.zacsweers.metro:runtime, and dev.zacsweers.metro plugin dependencies with the local source. Without the flag, published Maven artifacts are used.

To use a different path for the Metro checkout, pass -PlocalMetroPath=<path>:

./gradlew :compiler:test -PuseLocalMetro -PlocalMetroPath=/path/to/metro

To test with a different Kotlin version than the one defined in the version catalog, pass -Pkotlin.version=<version>:

./gradlew :compiler:test -Pkotlin.version=2.3.20-RC

License

Copyright 2026 Square, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.