{"id":19463746,"url":"https://github.com/adamko-dev/kotlin-binary-compatibility-validator-mu","last_synced_at":"2025-09-08T11:07:43.597Z","repository":{"id":94206258,"uuid":"607218787","full_name":"adamko-dev/kotlin-binary-compatibility-validator-mu","owner":"adamko-dev","description":"Kotlin Binary Compatibility Validator (Mirror Universe)","archived":false,"fork":false,"pushed_at":"2025-07-19T12:48:41.000Z","size":521,"stargazers_count":5,"open_issues_count":11,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-19T17:07:58.955Z","etag":null,"topics":["binary-compatibility","gradle-plugin","kotlin","validation"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adamko-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-02-27T14:59:47.000Z","updated_at":"2025-07-19T12:45:13.000Z","dependencies_parsed_at":"2024-01-26T16:24:34.582Z","dependency_job_id":"ec25bf79-81fd-43a6-aded-87b8036aab4c","html_url":"https://github.com/adamko-dev/kotlin-binary-compatibility-validator-mu","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/adamko-dev/kotlin-binary-compatibility-validator-mu","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adamko-dev%2Fkotlin-binary-compatibility-validator-mu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adamko-dev%2Fkotlin-binary-compatibility-validator-mu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adamko-dev%2Fkotlin-binary-compatibility-validator-mu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adamko-dev%2Fkotlin-binary-compatibility-validator-mu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adamko-dev","download_url":"https://codeload.github.com/adamko-dev/kotlin-binary-compatibility-validator-mu/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adamko-dev%2Fkotlin-binary-compatibility-validator-mu/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266618957,"owners_count":23957273,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["binary-compatibility","gradle-plugin","kotlin","validation"],"created_at":"2024-11-10T18:12:01.965Z","updated_at":"2025-07-23T04:35:48.169Z","avatar_url":"https://github.com/adamko-dev.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![GitHub license](https://img.shields.io/github/license/adamko-dev/kotlin-binary-compatibility-validator-mu?style=for-the-badge)](https://github.com/adamko-dev/kotlin-binary-compatibility-validator-mu/blob/main/LICENSE)\n[![Gradle Plugin Portal](https://img.shields.io/gradle-plugin-portal/v/dev.adamko.kotlin.binary-compatibility-validator?style=for-the-badge)](https://plugins.gradle.org/plugin/dev.adamko.kotlin.binary-compatibility-validator)\n[![Maven Central](https://img.shields.io/maven-central/v/dev.adamko.kotlin.binary-compatibility-validator/bcv-gradle-plugin?style=for-the-badge\u0026logo=apache-maven\u0026color=6545e7\u0026link=https%3A%2F%2Fsearch.maven.org%2Fsearch%3Fq%3Dg%3Adev.adamko.kotlin.binary-compatibility-validator)](https://search.maven.org/search?q=g:dev.adamko.kotlin.binary-compatibility-validator)\n[![Maven Central Snapshots](https://img.shields.io/maven-metadata/v?label=MAVEN%20SNAPSHOT\u0026metadataUrl=https%3A%2F%2Fs01.oss.sonatype.org%2Fcontent%2Frepositories%2Fsnapshots%2Fdev%2Fadamko%2Fkotlin%2Fbinary-compatibility-validator%2Fbcv-gradle-plugin%2Fmaven-metadata.xml\u0026style=for-the-badge\u0026logo=apache-maven)](https://s01.oss.sonatype.org/content/repositories/snapshots/dev/adamko/kotlin/binary-compatibility-validator/bcv-gradle-plugin/)\n\n# Kotlin Binary Compatibility Validator (Mirror Universe)\n\n[BCV-MU](https://github.com/adamko-dev/kotlin-binary-compatibility-validator-mu)\nis a [Gradle](https://gradle.org/) Plugin that validates the public JVM binary API of libraries, to\nmake sure that breaking changes are tracked.\n\nBCV-MU is based on\n[Kotlin/binary-compatibility-validator](https://github.com/Kotlin/binary-compatibility-validator),\nand contains improvements to better work with the Gradle API, especially in large projects.\n\nRead more about the validation of the public API in the BCV project:\n\n* [What constitutes the public API?](https://github.com/Kotlin/binary-compatibility-validator/#what-constitutes-the-public-api)\n* [What makes an incompatible change to the public binary API?](https://github.com/Kotlin/binary-compatibility-validator/#what-makes-an-incompatible-change-to-the-public-binary-api)\n\n(The MU tag was chosen because I hope to banish this plugin to the\n[Mirror Universe](https://en.wikipedia.org/wiki/Mirror_Universe)\nas soon the improvements here are merged upstream.)\n\n### Description\n\nUnder-the-hood BCV-MU still uses the signature-generation code from BCV, but the Gradle plugin has\nbeen refactored to better follow the Gradle API, and generate API signatures more flexibly.\n\nBCV-MU plugin can either be [applied as to a Project](#build-plugin) in any `build.gradle(.kts)`,\nor (**experimentally**) [as a Settings plugin](#settings-plugin) in `settings.gradle(.kts)`.\n\n#### Requirements\n\nThe minimal supported Gradle version is 7.6.\n\nBy default, BCV-MU uses BCV version `0.13.2`, which can be overridden, but may introduce runtime\nerrors.\n\n### Build plugin\n\nBCV-MU can be applied to each subproject as a standard Gradle plugin.\n\n```kotlin\n// build.gradle.kts\n\nplugins {\n  id(\"dev.adamko.kotlin.binary-compatibility-validator\") version \"$bcvMuVersion\"\n}\n```\n\nTo initialise the API declarations, run the Gradle task\n\n```shell\n./gradlew apiDump\n```\n\nThis will produce API files into the `./api` directory of subprojects with the BCV-MU plugin.\nThese API declarations files must be committed to the repository.\n\nTo verify that the API declarations is up-to-date, run the Gradle task\n\n```shell\n./gradlew apiCheck\n```\n\nThe `apiCheck` task will also be run whenever the `check` task is run.\n\n##### Configuration\n\nBCV-MU can be configured in a similar manner to BCV:\n\n```kotlin\n// build.gradle.kts\n\nplugins {\n  kotlin(\"jvm\") version \"1.8.10\"\n  id(\"dev.adamko.kotlin.binary-compatibility-validator\") version \"$bcvMuVersion\"\n}\n\nbinaryCompatibilityValidator {\n\n  // Explicitly include specific classes, markers, or packages.\n  // If any class, marker, or package is defined then all other declarations will be excluded.\n  // If no explicit public declarations are defined, then all declarations will be included by default.\n  publicClasses.add(\"com.company.api.FooPublicClass\")\n  publicMarkers.add(\"com.company.api.ExplicitApiAnnotation\")\n  publicPackages.add(\"com.company.api\")\n\n  // Packages that are excluded from public API dumps even if they contain public API.\n  ignoredPackages.add(\"kotlinx.coroutines.internal\")\n  // Classes (fully qualified) that are excluded from public API dumps even if they contain public API.\n  ignoredClasses.add(\"com.company.BuildConfig\")\n  // Set of annotations that exclude API from being public.\n  // Typically, it is all kinds of `@InternalApi` annotations that mark\n  // effectively private API that cannot be actually private for technical reasons.\n  ignoredMarkers.add(\"my.package.MyInternalApiAnnotation\")\n\n  // Disable or enable all BCV-MU tasks for this project\n  bcvEnabled.set(true)\n\n  // Override the default BCV version\n  kotlinxBinaryCompatibilityValidatorVersion.set(\"0.13.2\")\n}\n```\n\n##### Advanced configuration\n\nBCV automatically generates 'targets' for each Kotlin/JVM source set that it finds.\nthese `BCVTarget`s can be specifically modified, or manually defined, for fine-grained control.\n\n```kotlin\n// build.gradle.kts\n\nplugins {\n  kotlin(\"jvm\") version \"1.8.10\"\n  id(\"dev.adamko.kotlin.binary-compatibility-validator\") version \"$bcvMuVersion\"\n  `java-test-fixtures`\n}\n\nbinaryCompatibilityValidator {\n  // these are the default values that will be used in all Targets\n  ignoredMarkers.add(\"my.package.MyFirstInternalApiAnnotation\")\n  ignoredClasses.add(\"com.company.BuildConfig\")\n\n  // BCV will automatically generate targets for each Kotlin/JVM target,\n  // and each can be configured manually for fine-grained control. \n  targets.configureEach {\n    // values can be appended to the default values\n    ignoredMarkers.add(\"my.package.MySecondInternalApiAnnotation\")\n    // Or overridden\n    ignoredClasses.set(listOf())\n  }\n\n  // BCV will automatically register a target for testFixtures, but it must be enabled manually\n  targets.testFixtures {\n    enabled.set(true)\n  }\n\n  // BCV Targets can also be manually defined\n  targets.register(\"customTarget\") {\n    inputJar.set(tasks.customTargetJar.flatMap { it.archiveFile })\n  }\n}\n```\n\n##### Shared configuration with a convention plugin\n\nTo share common configuration it is best to set up a convention-plugin.\n\nIf you don't have any convention plugins already, then here's a quick guide.\n\nFirst, set-up\n[buildSrc](https://docs.gradle.org/current/userguide/organizing_gradle_projects.html#sec:build_sources)\nby creating a file `./buildSrc/build.gradle.kts`\n\nIn it, add the\n[`kotlin-dsl` plugin](https://docs.gradle.org/current/userguide/kotlin_dsl.html#sec:kotlin-dsl_plugin),\nand add the BCV-MU plugin as a dependency.\n\n```kotlin\n// ./buildSrc/build.gradle.kts\n\nplugins {\n  `kotlin-dsl`\n}\n\nrepositories {\n  mavenCentral()\n  gradlePluginPortal()\n}\n\ndependencies {\n  // add the *Maven coordinates* of the bcv-MU plugin, not the plugin ID, as a dependency\n  implementation(\"dev.adamko.kotlin.binary-compatibility-validator:bcv-gradle-plugin:$bcvMuVersion\")\n}\n```\n\nNext, create a convention plugin. This is where any shared configuration can be defined.\n\n```kotlin\n// buildSrc/src/main/kotlin/binary-compatibility-validator-convention.gradle.kts\n\nplugins {\n  id(\"dev.adamko.kotlin.binary-compatibility-validator\") // no version needed - it's defined in buildSrc/build.gradle.kts\n}\n\nbinaryCompatibilityValidator {\n  ignoredClasses.add(\"com.company.BuildConfig\")\n}\n```\n\nFinally, apply the convention plugin to subprojects. This will automatically re-use the same\nconfiguration.\n\n```kotlin\n// ./some/subproject/build.gradle.kts\nplugins {\n  id(\"binary-compatibility-validator-convention\")\n  kotlin(\"jvm\")\n}\n```\n\n#### Settings plugin\n\nThere is experimental support for applying BCV-MU as a Settings plugin.\n\nThis allows for applying BCV-MU to all subprojects in a Gradle-friendly way.\nAll subprojects are included by default, and can be excluded using BCV-MU config.\n\n```kotlin\n// settings.gradle.kts\n\nbuildscript {\n  dependencies {\n    // BCV-MU requires the Kotlin Gradle Plugin classes are present\n    classpath(\"org.jetbrains.kotlin:kotlin-gradle-plugin-api:1.8.10\")\n  }\n}\n\nplugins {\n  id(\"dev.adamko.kotlin.binary-compatibility-validator\") version \"$bcvMuVersion\"\n}\n\nbinaryCompatibilityValidator {\n  ignoredProjects.addAll(\n\n    \":\",                // ignore root project\n    \":some-subproject\", // ignore subprojects explicitly\n\n    // or ignore using a glob pattern\n    \":internal-dependencies:*\",\n    \":*-tasks:**\",\n  )\n\n  // set the default values for all targets in all enabled-subprojects \n  defaultTargetValues {\n    enabled.convention(true)\n    ignoredClasses.set(listOf(\"com.package.MyIgnoredClass\"))\n    ignoredMarkers.set(listOf(\"com.package.MyInternalApiAnnotationMarker\"))\n    ignoredPackages.set(listOf(\"com.package.my_ignored_package\"))\n  }\n}\n\ninclude(\n  // these projects will have BCV-MU automatically applied\n  \":common\",\n  \":internal-dependencies:alpha:nested\",\n  \":internal-dependencies:alpha:nested\",\n  \":a-task\",\n\n  // this subproject is explicitly excluded from BCV\n  \":some-subproject\",\n\n  // these subprojects will be excluded by glob pattern\n  \":internal-dependencies\",\n  \":internal-dependencies:alpha\",\n  \":internal-dependencies:beta\",\n  \":x-tasks\",\n  \":x-tasks:sub1\",\n  \":x-tasks:sub1:sub2\",\n  \":z-tasks\",\n  \":z-tasks:sub1\",\n  \":z-tasks:sub1:sub2\",\n)\n```\n\n## License\n\nThe code in this project is based on the code in the\n[Kotlin/binary-compatibility-validator](https://github.com/Kotlin/binary-compatibility-validator)\nproject.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadamko-dev%2Fkotlin-binary-compatibility-validator-mu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadamko-dev%2Fkotlin-binary-compatibility-validator-mu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadamko-dev%2Fkotlin-binary-compatibility-validator-mu/lists"}