build: Move from the binary-compatibility-validator plugin to KGP ABI validation

Author: markushi

.cursor/rules/api.mdc

@@ -6,7 +6,7 @@ description: Public API surface, binary compatibility, and common classes to mod
 
 ## API Compatibility
 
-Public API is tracked via `.api` files generated by the [Binary Compatibility Validator](https://github.com/Kotlin/binary-compatibility-validator) Gradle plugin. Each module has its own file at `<module>/api/<module>.api`.
+Public API is tracked via `.api` files generated by the [ABI validation](https://kotlinlang.org/docs/gradle-binary-compatibility-validation.html) built into the Kotlin Gradle plugin. Each module has its own file at `<module>/api/<module>.api`.
 
 - **Never edit `.api` files manually.** Run `./gradlew apiDump` to regenerate them.
 - `./gradlew check` validates current code against `.api` files and fails on unintended changes.

CONTRIBUTING.md

@@ -76,7 +76,7 @@ or
 
 # Binary compatibility validation
 
-To prevent breaking ABI changes and exposing things we should not, we make use of https://github.com/Kotlin/binary-compatibility-validator. If your change intended to introduce a new public method/property or modify the existing one you can overwrite the API declarations to make CI happy as follows (overwrites them from scratch):
+To prevent breaking ABI changes and exposing things we should not, we make use of https://kotlinlang.org/docs/gradle-binary-compatibility-validation.html. If your change intended to introduce a new public method/property or modify the existing one you can overwrite the API declarations to make CI happy as follows (overwrites them from scratch):
 
 ```shell
 make api

build-logic/build.gradle.kts

@@ -15,6 +15,10 @@ gradlePlugin {
       id = "io.sentry.jdk-target"
       implementationClass = "io.sentry.gradle.JdkTargetConvention"
     }
+    register("sentryApiValidation") {
+      id = "io.sentry.api-validation"
+      implementationClass = "io.sentry.gradle.SentryApiValidationPlugin"
+    }
     register("sentryAnimalSniffer") {
       id = "io.sentry.animalsniffer"
       implementationClass = "io.sentry.gradle.SentryAnimalSnifferPlugin"

build-logic/src/main/kotlin/io/sentry/gradle/ApiValidationExtension.kt

@@ -0,0 +1,12 @@
+package io.sentry.gradle
+
+import org.gradle.api.provider.SetProperty
+
+/** Configuration for the `io.sentry.api-validation` convention plugin. */
+abstract class ApiValidationExtension {
+  /**
+   * Packages that are public to the JVM but not part of the SDK's API, and so are left out of the
+   * dump. Subpackages are left out too.
+   */
+  abstract val ignoredPackages: SetProperty<String>
+}

build-logic/src/main/kotlin/io/sentry/gradle/SentryApiValidationPlugin.kt

@@ -0,0 +1,53 @@
+package io.sentry.gradle
+
+import org.gradle.api.GradleException
+import org.gradle.api.Plugin
+import org.gradle.api.Project
+import org.gradle.api.plugins.ExtensionAware
+import org.gradle.kotlin.dsl.create
+import org.jetbrains.kotlin.gradle.dsl.abi.AbiValidationExtension
+import org.jetbrains.kotlin.gradle.dsl.abi.AbiValidationMultiplatformExtension
+import org.jetbrains.kotlin.gradle.dsl.abi.AbiValidationVariantSpec
+import org.jetbrains.kotlin.gradle.dsl.abi.ExperimentalAbiValidation
+
+private val KOTLIN_PLUGIN_IDS =
+  listOf(
+    "org.jetbrains.kotlin.jvm",
+    "org.jetbrains.kotlin.android",
+    "org.jetbrains.kotlin.multiplatform",
+  )
+
+/**
+ * Checks the public ABI of a module against the dump checked into its `api` directory, using the
+ * Kotlin Gradle plugin's own ABI validation. Adds `checkKotlinAbi`, which `check` depends on, and
+ * `updateKotlinAbi`, which rewrites the dump.
+ */
+@OptIn(ExperimentalAbiValidation::class)
+class SentryApiValidationPlugin : Plugin<Project> {
+  override fun apply(project: Project) {
+    val extension = project.extensions.create<ApiValidationExtension>("sentryApiValidation")
+
+    // The abiValidation extension only exists once a Kotlin plugin has been applied, and a module
+    // may list this plugin before that one.
+    KOTLIN_PLUGIN_IDS.forEach {
+      project.pluginManager.withPlugin(it) { enable(project, extension) }
+    }
+
+    // Aliases for backwards compat with the old binary-compatibility-validator plugin.
+    project.tasks.register("apiDump") { dependsOn("updateKotlinAbi") }
+    project.tasks.register("apiCheck") { dependsOn("checkKotlinAbi") }
+  }
+
+  private fun enable(project: Project, extension: ApiValidationExtension) {
+    val kotlin = project.extensions.getByName("kotlin") as ExtensionAware
+    val spec: AbiValidationVariantSpec =
+      when (val abi = kotlin.extensions.getByName("abiValidation")) {
+        is AbiValidationMultiplatformExtension -> abi.also { it.enabled.set(true) }
+        is AbiValidationExtension -> abi.also { it.enabled.set(true) }
+        else -> throw GradleException("Unexpected abiValidation extension: ${abi.javaClass.name}")
+      }
+    // Lazy, because the module configures the extension after this plugin has been applied.
+    val ignored = extension.ignoredPackages.map { packages -> packages.map { "$it.**" } }
+    spec.filters { exclude { byNames.addAll(ignored) } }
+  }
+}

build.gradle.kts

@@ -11,7 +11,6 @@ plugins {
     alias(libs.plugins.spotless) apply false
     alias(libs.plugins.detekt)
     `maven-publish`
-    alias(libs.plugins.binary.compatibility.validator)
     alias(libs.plugins.vanniktech.maven.publish) apply false
     alias(libs.plugins.kotlin.android) apply false
     alias(libs.plugins.kotlin.multiplatform) apply false
@@ -47,52 +46,6 @@ buildscript {
     }
 }
 
-apiValidation {
-    ignoredPackages.addAll(
-        setOf(
-            "io.sentry.android.core.internal"
-        )
-    )
-    ignoredProjects.addAll(
-        listOf(
-            "sentry-samples-android",
-            "sentry-samples-console",
-            "sentry-samples-console-opentelemetry-noagent",
-            "sentry-samples-jul",
-            "sentry-samples-log4j2",
-            "sentry-samples-logback",
-            "sentry-samples-openfeign",
-            "sentry-samples-servlet",
-            "sentry-samples-spring",
-            "sentry-samples-spring-jakarta",
-            "sentry-samples-spring-7",
-            "sentry-samples-spring-boot",
-            "sentry-samples-spring-boot-opentelemetry",
-            "sentry-samples-spring-boot-opentelemetry-noagent",
-            "sentry-samples-spring-boot-jakarta",
-            "sentry-samples-spring-boot-jakarta-log4j2",
-            "sentry-samples-spring-boot-jakarta-opentelemetry",
-            "sentry-samples-spring-boot-jakarta-opentelemetry-noagent",
-            "sentry-samples-spring-boot-webflux",
-            "sentry-samples-spring-boot-webflux-jakarta",
-            "sentry-samples-spring-boot-4",
-            "sentry-samples-spring-boot-4-log4j2",
-            "sentry-samples-spring-boot-4-opentelemetry",
-            "sentry-samples-spring-boot-4-opentelemetry-noagent",
-            "sentry-samples-spring-boot-4-otlp",
-            "sentry-samples-spring-boot-4-webflux",
-            "sentry-samples-ktor-client",
-            "sentry-uitest-android",
-            "sentry-uitest-android-critical",
-            "test-app-size",
-            "sentry-samples-netflix-dgs",
-            "sentry-samples-console-otlp",
-            "sentry-test-support",
-            "sentry-system-test-support"
-        )
-    )
-}
-
 allprojects {
     group = Config.Sentry.group
     version = providers.gradleProperty(Config.Sentry.versionNameProp).get()

gradle/libs.versions.toml

@@ -66,7 +66,6 @@ ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
 buildconfig = { id = "com.github.gmazzo.buildconfig", version = "5.6.5" }
 dokka = { id = "org.jetbrains.dokka", version = "2.0.0" }
 dokka-javadoc = { id = "org.jetbrains.dokka-javadoc", version = "2.0.0" }
-binary-compatibility-validator = { id = "org.jetbrains.kotlinx.binary-compatibility-validator", version = "0.13.0" }
 errorprone = { id = "net.ltgt.errorprone", version = "5.1.1" }
 gradle-versions = { id = "com.github.ben-manes.versions", version = "0.42.0" }
 spotless = { id = "com.diffplug.spotless", version.ref = "spotless" }

sentry-android-core/build.gradle.kts

@@ -8,6 +8,7 @@ plugins {
   alias(libs.plugins.kotlin.compose)
   alias(libs.plugins.errorprone)
   alias(libs.plugins.gradle.versions)
+  id("io.sentry.api-validation")
 }
 
 android {
@@ -135,3 +136,5 @@ dependencies {
   testRuntimeOnly(libs.androidx.fragment.ktx)
   testRuntimeOnly(libs.timber)
 }
+
+sentryApiValidation { ignoredPackages.add("io.sentry.android.core.internal") }

sentry-android-distribution/build.gradle.kts

@@ -5,6 +5,7 @@ plugins {
   id("com.android.library")
   alias(libs.plugins.kotlin.android)
   alias(libs.plugins.detekt)
+  id("io.sentry.api-validation")
 }
 
 android {

sentry-android-fragment/build.gradle.kts

@@ -7,6 +7,7 @@ plugins {
   alias(libs.plugins.kotlin.android)
   alias(libs.plugins.gradle.versions)
   alias(libs.plugins.detekt)
+  id("io.sentry.api-validation")
 }
 
 android {