Skip to content

Commit

Permalink
Update -Xjvm-default description
Browse files Browse the repository at this point in the history 
(cherry picked from commit 40158d1)
  • Loading branch information
Mikhael Bogdanov authored and Space committed Nov 9, 2021
1 parent e8e3c72 commit 63044b1
Show file tree
Hide file tree
Showing 2 changed files with 38 additions and 28 deletions.
33 changes: 19 additions & 14 deletions ...er/cli/cli-common/src/org/jetbrains/kotlin/cli/common/arguments/K2JVMCompilerArguments.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -325,27 +325,32 @@ class K2JVMCompilerArguments : CommonCompilerArguments() {
value = "-Xjvm-default",
valueDescription = "{all|all-compatibility|disable|enable|compatibility}",
description = """Emit JVM default methods for interface declarations with bodies.
-Xjvm-default=all-compatibility Generate both a default method in the interface, and a compatibility accessor
in the DefaultImpls class.
In case of inheritance from a Kotlin interface compiled in the old scheme
(DefaultImpls, no default methods), the compatibility accessor in DefaultImpls
will delegate to the DefaultImpls method of the superinterface. Otherwise the
compatibility accessor will invoke the default method on the interface, with
standard JVM runtime resolution semantics.
Note that if interface delegation is used, all interface methods are delegated.
The only exception are methods annotated with the deprecated @JvmDefault annotation.
-Xjvm-default=all Generate default methods for all interface declarations with bodies.
Do not generate DefaultImpls classes at all.
-Xjvm-default=all Generate JVM default methods for all interface declarations with bodies in module.
Do not generate DefaultImpls stubs for such declarations (that is default behaviour of compiler in 'disable' mode).
If interface inherits such methods from interface compiled in 'disable' scheme
then implicit DefaultImpls stubs would be generated as there are no default method for it.
BREAKS BINARY COMPATIBILITY if some client code relies on the presence of
DefaultImpls classes. Also prohibits the produced binaries to be read by Kotlin
compilers earlier than 1.4.
Note that if interface delegation is used, all interface methods are delegated.
The only exception are methods annotated with the deprecated @JvmDefault annotation.
-Xjvm-default=disable Do not generate JVM default methods and prohibit @JvmDefault annotation usage.
-Xjvm-default=enable Allow usages of @JvmDefault; only generate the default method
-Xjvm-default=all-compatibility In addition to `all` mode generate compatibility stubs in the DefaultImpls classes.
Compatibility stubs could be useful for library and runtime authors
to keep backward binary compatibility for existing client compiled against previous library versions.
New 'all' and 'all-compatibility' modes are changing library ABI surface that will be used by client after their recompilation.
In that sense client might be incompatible with previous library versions that REQUIRE PROPER LIBRARY VERSIONING.
In case of inheritance from a Kotlin interface compiled in the old scheme
(DefaultImpls, no default methods), the implicit stubs in DefaultImpls
will delegate to the DefaultImpls method of the superinterface.
Otherwise the compatibility stubs in DefaultImpls would invoke the default method on the interface via special accessor in it,
with standard JVM runtime resolution semantics.
Perform additional compatibility checks for classes in case of implicit specialized override
presence in 'disable' scheme (See KT-39603 for more details)
-Xjvm-default=disable Default behaviour. Do not generate JVM default methods and prohibit @JvmDefault annotation usage.
-Xjvm-default=enable Deprecated. Allow usages of @JvmDefault; only generate the default method
for annotated method in the interface
(annotating an existing method can break binary compatibility)
-Xjvm-default=compatibility Allow usages of @JvmDefault; generate a compatibility accessor
-Xjvm-default=compatibility Deprecated. Allow usages of @JvmDefault; generate a compatibility accessor
in the 'DefaultImpls' class in addition to the default interface method"""
)
var jvmDefault: String by FreezableVar(JvmDefaultMode.DEFAULT.description)
Expand Down
33 changes: 19 additions & 14 deletions compiler/testData/cli/jvm/extraHelp.out
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,27 +53,32 @@ where advanced options include:
* warn (report a warning)
-Xjvm-default={all|all-compatibility|disable|enable|compatibility}
Emit JVM default methods for interface declarations with bodies.
-Xjvm-default=all-compatibility Generate both a default method in the interface, and a compatibility accessor
in the DefaultImpls class.
In case of inheritance from a Kotlin interface compiled in the old scheme
(DefaultImpls, no default methods), the compatibility accessor in DefaultImpls
will delegate to the DefaultImpls method of the superinterface. Otherwise the
compatibility accessor will invoke the default method on the interface, with
standard JVM runtime resolution semantics.
Note that if interface delegation is used, all interface methods are delegated.
The only exception are methods annotated with the deprecated @JvmDefault annotation.
-Xjvm-default=all Generate default methods for all interface declarations with bodies.
Do not generate DefaultImpls classes at all.
-Xjvm-default=all Generate JVM default methods for all interface declarations with bodies in module.
Do not generate DefaultImpls stubs for such declarations (that is default behaviour of compiler in 'disable' mode).
If interface inherits such methods from interface compiled in 'disable' scheme
then implicit DefaultImpls stubs would be generated as there are no default method for it.
BREAKS BINARY COMPATIBILITY if some client code relies on the presence of
DefaultImpls classes. Also prohibits the produced binaries to be read by Kotlin
compilers earlier than 1.4.
Note that if interface delegation is used, all interface methods are delegated.
The only exception are methods annotated with the deprecated @JvmDefault annotation.
-Xjvm-default=disable Do not generate JVM default methods and prohibit @JvmDefault annotation usage.
-Xjvm-default=enable Allow usages of @JvmDefault; only generate the default method
-Xjvm-default=all-compatibility In addition to `all` mode generate compatibility stubs in the DefaultImpls classes.
Compatibility stubs could be useful for library and runtime authors
to keep backward binary compatibility for existing client compiled against previous library versions.
New 'all' and 'all-compatibility' modes are changing library ABI surface that will be used by client after their recompilation.
In that sense client might be incompatible with previous library versions that REQUIRE PROPER LIBRARY VERSIONING.
In case of inheritance from a Kotlin interface compiled in the old scheme
(DefaultImpls, no default methods), the implicit stubs in DefaultImpls
will delegate to the DefaultImpls method of the superinterface.
Otherwise the compatibility stubs in DefaultImpls would invoke the default method on the interface via special accessor in it,
with standard JVM runtime resolution semantics.
Perform additional compatibility checks for classes in case of implicit specialized override
presence in 'disable' scheme (See KT-39603 for more details)
-Xjvm-default=disable Default behaviour. Do not generate JVM default methods and prohibit @JvmDefault annotation usage.
-Xjvm-default=enable Deprecated. Allow usages of @JvmDefault; only generate the default method
for annotated method in the interface
(annotating an existing method can break binary compatibility)
-Xjvm-default=compatibility Allow usages of @JvmDefault; generate a compatibility accessor
-Xjvm-default=compatibility Deprecated. Allow usages of @JvmDefault; generate a compatibility accessor
in the 'DefaultImpls' class in addition to the default interface method
-Xjvm-default-allow-non-default-inheritance
Allow inheritance from 'all*' modes for 'disable' one
Expand Down

0 comments on commit 63044b1

Please sign in to comment.