Skip to content

update BCV to 0.13.1 #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 27, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 22 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,22 @@

# Kotlin Binary Compatibility Validator (Mirror Universe)

[BCV-MU](https://github.com/adamko-dev/kotlin-binary-compatibility-validator-mu) is a
re-imagined [Gradle](https://gradle.org/) Plugin for
[Kotlin/binary-compatibility-validator](https://github.com/Kotlin/binary-compatibility-validator).
[BCV-MU](https://github.com/adamko-dev/kotlin-binary-compatibility-validator-mu)
is a [Gradle](https://gradle.org/) Plugin that validates the public JVM binary API of libraries, to
make sure that breaking changes are tracked.

This plugin validates the public JVM binary API of libraries to make sure that breaking changes are
tracked.
BCV-MU is based on
[Kotlin/binary-compatibility-validator](https://github.com/Kotlin/binary-compatibility-validator),
and contains improvements to better work with the Gradle API, especially in large projects.

Read more in the BCV project:
Read more about the validation of the public API in the BCV project:

* [What constitutes the public API?](https://github.com/Kotlin/binary-compatibility-validator/#what-constitutes-the-public-api)
* [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)

(The [Mirror Universe](https://en.wikipedia.org/wiki/Mirror_Universe) tag was chosen because I hope
to banish this plugin as soon the improvements here are merged upstream.)
(The MU tag was chosen because I hope to banish this plugin to the
[Mirror Universe](https://en.wikipedia.org/wiki/Mirror_Universe)
as soon the improvements here are merged upstream.)

### Description

Expand All @@ -30,7 +32,7 @@ or (**experimentally**) [as a Settings plugin](#settings-plugin) in `settings.gr

The minimal supported Gradle version is 7.6.

By default, BCV-MU uses BCV version `0.13.0`, which can be overridden, but may introduce runtime
By default, BCV-MU uses BCV version `0.13.1`, which can be overridden, but may introduce runtime
errors.

### Build plugin
Expand Down Expand Up @@ -75,6 +77,14 @@ plugins {
}

binaryCompatibilityValidator {

// Explicitly include specific classes, markers, or packages.
// If any class, marker, or package is defined then all other declarations will be excluded.
// If no explicit public declarations are defined, then all declarations will be included by default.
publicClasses.add("com.company.api.FooPublicClass")
publicMarkers.add("com.company.api.ExplicitApiAnnotation")
publicPackages.add("com.company.api")

// Packages that are excluded from public API dumps even if they contain public API.
ignoredPackages.add("kotlinx.coroutines.internal")
// Classes (fully qualified) that are excluded from public API dumps even if they contain public API.
Expand All @@ -88,14 +98,14 @@ binaryCompatibilityValidator {
bcvEnabled.set(true)

// Override the default BCV version
kotlinxBinaryCompatibilityValidatorVersion.set("0.13.0")
kotlinxBinaryCompatibilityValidatorVersion.set("0.13.1")
}
```

##### Advanced configuration

BCV automatically generates 'targets' for each Kotlin/JVM target that it finds.
These targets can be specifically modified, or manually defined, for fine-grained control.
BCV automatically generates 'targets' for each Kotlin/JVM source set that it finds.
these `BCVTarget`s can be specifically modified, or manually defined, for fine-grained control.

```kotlin
// build.gradle.kts
Expand Down
2 changes: 1 addition & 1 deletion gradle/libs.versions.toml
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ kotlinGradle = "1.6.0"
javaDiffUtils = "4.12"
junit = "5.9.2"
kotest = "5.5.5"
kotlinx-bcv = "0.13.0"
kotlinx-bcv = "0.13.1"

gradlePluginPublishPlugin = "1.1.0"
shadowPlugin = "8.1.0"
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,6 @@ dependencies {
testFixturesApi(testFixtures(projects.modules.bcvGradlePlugin))
}


@Suppress("UnstableApiUsage")
testing.suites {
withType<JvmTestSuite>().configureEach {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ private fun FunSpec.createTestFixturesProject(
buildGradleKts = """
|plugins {
| kotlin("jvm") version "1.7.10"
| id("dev.adamko.kotlin.binary-compatibility-validator") version "0.0.4-SNAPSHOT"
| id("dev.adamko.kotlin.binary-compatibility-validator") version "0.0.5-SNAPSHOT"
| `java-test-fixtures`
|}
|
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
package kotlinx.validation.test

import dev.adamko.kotlin.binary_compatibility_validator.test.utils.api.*
import dev.adamko.kotlin.binary_compatibility_validator.test.utils.build
import dev.adamko.kotlin.binary_compatibility_validator.test.utils.shouldHaveTaskWithOutcome
import org.gradle.testkit.runner.TaskOutcome.SUCCESS
import org.junit.jupiter.api.Test

class MixedMarkersTest : BaseKotlinGradleTest() {

@Test
fun testMixedMarkers() {
val runner = test {
buildGradleKts {
resolve("/examples/gradle/base/withPlugin.gradle.kts")
resolve("/examples/gradle/configuration/publicMarkers/mixedMarkers.gradle.kts")
}

kotlin("MixedAnnotations.kt") {
resolve("/examples/classes/MixedAnnotations.kt")
}

apiFile(projectName = rootProjectDir.name) {
resolve("/examples/classes/MixedAnnotations.dump")
}

runner {
arguments.add(":apiCheck")
}
}

runner.build {
shouldHaveTaskWithOutcome(":apiCheck", SUCCESS)
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,6 @@ package kotlinx.validation.test

import dev.adamko.kotlin.binary_compatibility_validator.test.utils.api.*
import dev.adamko.kotlin.binary_compatibility_validator.test.utils.build
import dev.adamko.kotlin.binary_compatibility_validator.test.utils.shouldHaveOutcome
import dev.adamko.kotlin.binary_compatibility_validator.test.utils.shouldHaveTaskWithOutcome
import org.gradle.testkit.runner.TaskOutcome.SUCCESS
import org.junit.jupiter.api.Test
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
package kotlinx.validation.test

import dev.adamko.kotlin.binary_compatibility_validator.test.utils.api.*
import dev.adamko.kotlin.binary_compatibility_validator.test.utils.build
import dev.adamko.kotlin.binary_compatibility_validator.test.utils.shouldHaveTaskWithOutcome
import org.gradle.testkit.runner.TaskOutcome.SUCCESS
import org.junit.jupiter.api.Test

class PublicMarkersTest : BaseKotlinGradleTest() {

@Test
fun testPublicMarkers() {
val runner = test {
buildGradleKts {
resolve("/examples/gradle/base/withPlugin.gradle.kts")
resolve("/examples/gradle/configuration/publicMarkers/markers.gradle.kts")
}

kotlin("ClassWithPublicMarkers.kt") {
resolve("/examples/classes/ClassWithPublicMarkers.kt")
}

kotlin("ClassInPublicPackage.kt") {
resolve("/examples/classes/ClassInPublicPackage.kt")
}

apiFile(projectName = rootProjectDir.name) {
resolve("/examples/classes/ClassWithPublicMarkers.dump")
}

runner {
arguments.add(":apiCheck")
}
}

runner.build {
shouldHaveTaskWithOutcome(":apiCheck", SUCCESS)
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -154,7 +154,7 @@ buildscript {


plugins {
id("dev.adamko.kotlin.binary-compatibility-validator") version "0.0.4-SNAPSHOT"
id("dev.adamko.kotlin.binary-compatibility-validator") version "0.0.5-SNAPSHOT"
}

include(
Expand Down
Original file line number Diff line number Diff line change
@@ -1,12 +1,7 @@
/*
* Copyright 2016-2020 JetBrains s.r.o.
* Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
*/

package org.different.pack

public class BuildConfig {
public val p1 = 1
public val p1 = 1

public fun f1() = p1
}
public fun f1() = p1
}
Original file line number Diff line number Diff line change
@@ -1,12 +1,7 @@
/*
* Copyright 2016-2020 JetBrains s.r.o.
* Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
*/

package com.company

public class BuildConfig {
public val property = 1
public val property = 1

public fun function() = property
}
public fun function() = property
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
package foo.api

class ClassInPublicPackage {
class Inner
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
public final class foo/ClassWithPublicMarkers {
public final fun getBar1 ()I
public final fun getBar2 ()I
public final fun setBar1 (I)V
public final fun setBar2 (I)V
}

public final class foo/ClassWithPublicMarkers$MarkedClass {
public fun <init> ()V
public final fun getBar1 ()I
}

public abstract interface annotation class foo/PublicClass : java/lang/annotation/Annotation {
}

public final class foo/api/ClassInPublicPackage {
public fun <init> ()V
}

public final class foo/api/ClassInPublicPackage$Inner {
public fun <init> ()V
}

Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
package foo

@Target(AnnotationTarget.CLASS)
annotation class PublicClass

@Target(AnnotationTarget.FIELD)
annotation class PublicField

@Target(AnnotationTarget.PROPERTY)
annotation class PublicProperty

public class ClassWithPublicMarkers {
@PublicField
var bar1 = 42

@PublicProperty
var bar2 = 42

@PublicClass
class MarkedClass {
val bar1 = 41
}

var notMarkedPublic = 42

class NotMarkedClass
}
Original file line number Diff line number Diff line change
@@ -1,8 +1,3 @@
/*
* Copyright 2016-2022 JetBrains s.r.o.
* Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
*/

package examples.classes;

public final class JavaLib {
Expand Down
Original file line number Diff line number Diff line change
@@ -1,13 +1,8 @@
/*
* Copyright 2016-2022 JetBrains s.r.o.
* Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
*/

package examples.classes

class KotlinLib {

fun foo(): String = "foo"
internal fun bar(): String = "bar"
fun foo(): String = "foo"
internal fun bar(): String = "bar"

}
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
public final class mixed/MarkedPublicWithPrivateMembers {
public fun <init> ()V
public final fun otherFun ()V
}

Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
package mixed

@Target(
AnnotationTarget.CLASS,
AnnotationTarget.PROPERTY,
AnnotationTarget.FIELD,
AnnotationTarget.FUNCTION
)
annotation class PublicApi

@Target(
AnnotationTarget.CLASS,
AnnotationTarget.PROPERTY,
AnnotationTarget.FIELD,
AnnotationTarget.FUNCTION
)
annotation class PrivateApi

@PublicApi
class MarkedPublicWithPrivateMembers {
@PrivateApi
var private1 = 42

@field:PrivateApi
var private2 = 15

@PrivateApi
fun privateFun() = Unit

@PublicApi
@PrivateApi
fun privateFun2() = Unit

fun otherFun() = Unit
}

// Member annotations should be ignored in explicitly private classes
@PrivateApi
class MarkedPrivateWithPublicMembers {
@PublicApi
var public1 = 42

@field:PublicApi
var public2 = 15

@PublicApi
fun publicFun() = Unit

fun otherFun() = Unit
}

@PrivateApi
@PublicApi
class PublicAndPrivateFilteredOut
Original file line number Diff line number Diff line change
@@ -1,7 +1,3 @@
/*
* Copyright 2016-2022 JetBrains s.r.o.
* Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
*/
package foo

@Target(AnnotationTarget.FIELD)
Expand All @@ -11,10 +7,9 @@ annotation class HiddenField
annotation class HiddenProperty

public class ClassWithProperties {
@HiddenField
var bar1 = 42
@HiddenField
var bar1 = 42

@HiddenProperty
var bar2 = 42
@HiddenProperty
var bar2 = 42
}

Loading