Kotlin ABI checks #919
Open
Kotlin ABI checks #919
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
sgammon
force-pushed
the
feat/kotlin-abi-checks
branch
3 times, most recently
from
5f9dd4b to
084ebbd
Compare
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
sgammon
force-pushed
the
feat/kotlin-abi-checks
branch
from
084ebbd to
dd85a2d
Compare
Signed-off-by: Sam Gammon <[email protected]>
Signed-off-by: Sam Gammon <[email protected]>
sgammon
force-pushed
the
feat/kotlin-abi-checks
branch
from
dd85a2d to
7058067
Compare
sgammon
commented
Feb 4, 2025
Comment on lines
+84
to
+89
| apiValidation { | ||
| ignoredProjects += listOf("bench", "docs") | ||
| nonPublicMarkers += "org.pkl.commons.annotations.PklExperimental" | ||
|
|
||
| @OptIn(kotlinx.validation.ExperimentalBCVApi::class) klib { enabled = true } | ||
| } |
There was a problem hiding this comment.
It's best to configure this plugin in the root build.gradle.kts, because then projects can be ignored by name. I've enabled experimental KLib validation since Pkl is well past the minimum of 1.9.20.
Comment on lines
+18
to
+25
| /** | ||
| * Marks experimental APIs in Kotlin or Java. Such APIs may be publicly exposed by the Pkl project, | ||
| * but are not provided with a stability guarantee, and require opt-in use from Kotlin. | ||
| */ | ||
| @RequiresOptIn(level = RequiresOptIn.Level.WARNING) | ||
| @Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY) | ||
| @Retention(AnnotationRetention.BINARY) | ||
| annotation class PklExperimental |
There was a problem hiding this comment.
this annotation is added as an escape hatch for public API pins. it can be used like this:
@PklExperimental
public class SomeClass {
// ...
}Then, in user code:
@OptIn(PklExperimental::class)
fun someUserFunction {
// usage of an experimental type
val x = SomeClass()
}Omission of the @OptIn generates a compile-time warning, and any type annotated with @PklExperimental is omitted from API pins.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Kotlin ABI Check: Checks Kotlin public library symbols for drift. Run
apiCheckto make sure a change does not break downstream Java/Kotlin library consumers; runapiDumpto re-seal public API lockfiles.Initial API lockfiles were generated as well.
apiCheckruns on./gradlew checkby default, preventing downstream API/ABI breakage when Pkl is used as a Maven library.PklExperimentalannotation for opt-out of API pinningPklExperimentalas Kotlin opt-in