This tool allows to dump binary API of a Kotlin library that is public in sense of Kotlin visibilities and ensure that the public binary API wasn't changed in a way that make this change binary incompatible.
Compile and run tests. CasesPublicAPITest
verifies the tool itself,
and RuntimePublicAPITest
dumps the public API of kotlin-stdlib
,
kotlin-stdlib-jdk7/8
, kotlin-reflect
and kotlin-gradle-plugin-idea
jars,
which must be built beforehand with gradle. Use clean assemble
tasks,
since the incremental compilation currently doesn't produce all the required output.
When substantial changes are made to the public API, it may be convenient to overwrite
the entire dump and compare changes later before committing: pass -Doverwrite.output=true
property to the test to do so.
Also you can use shared run configuration "Binary compatibility tests", which also overwrites the results when they differ.
A class is considered to be effectively public if all of the following conditions are met:
- it has public or protected JVM access (
ACC_PUBLIC
orACC_PROTECTED
) - it has one of the following visibilities in Kotlin:
- no visibility (means no Kotlin declaration corresponds to this compiled class)
- public
- protected
- internal, only in case if the class is annotated with
PublishedApi
- it isn't a local class
- it isn't a synthetic class with mappings for
when
tableswitches ($WhenMappings
) - it contains at least one effectively public member, in case if the class corresponds to a kotlin file with top-level members or a multifile facade
- in case if the class is a member in another class, it is contained in the effectively public class
- in case if the class is a protected member in another class, it is contained in the non-final class
A member of the class (i.e. a field or a method) is considered to be effectively public if all of the following conditions are met:
-
it has public or protected JVM access (
ACC_PUBLIC
orACC_PROTECTED
) -
it has one of the following visibilities in Kotlin:
- no visibility (means no Kotlin declaration corresponds to this class member)
- public
- protected
- internal, only in case if the class is annotated with
PublishedApi
Note that Kotlin visibility of a field exposed by
lateinit
property is the visibility of its setter. -
in case if the member is protected, it is contained in non-final class
-
it isn't a synthetic access method for a private field
For a class a binary incompatible change is:
- changing the full class name (including package and containing classes)
- changing the superclass, so that the class no longer has the previous superclass in the inheritance chain
- changing the set of implemented interfaces so that the class no longer implements interfaces it had implemented before
- changing one of the following access flags:
ACC_PUBLIC
,ACC_PROTECTED
,ACC_PRIVATE
— lessening the class visibilityACC_FINAL
— making non-final class finalACC_ABSTRACT
— making non-abstract class abstractACC_INTERFACE
— changing class to interface and vice versaACC_ANNOTATION
— changing annotation to interface and vice versa
For a class member a binary incompatible change is:
- changing its name
- changing its descriptor (erased return type and parameter types for methods); this includes changing field to method and vice versa
- changing one of the following access flags:
ACC_PUBLIC
,ACC_PROTECTED
,ACC_PRIVATE
— lessening the member visibilityACC_FINAL
— making non-final field or method finalACC_ABSTRACT
— making non-abstract method abstractACC_STATIC
— changing instance member to static and vice versa