Skip to content

Commit 40158d1

Browse files
author
Mikhael Bogdanov
committed
Update -Xjvm-default description
1 parent 00d344d commit 40158d1

File tree

2 files changed

+38
-28
lines changed

2 files changed

+38
-28
lines changed

‎compiler/cli/cli-common/src/org/jetbrains/kotlin/cli/common/arguments/K2JVMCompilerArguments.kt‎

Lines changed: 19 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -312,27 +312,32 @@ class K2JVMCompilerArguments : CommonCompilerArguments() {
312312
value = "-Xjvm-default",
313313
valueDescription = "{all|all-compatibility|disable|enable|compatibility}",
314314
description = """Emit JVM default methods for interface declarations with bodies.
315-
-Xjvm-default=all-compatibility Generate both a default method in the interface, and a compatibility accessor
316-
in the DefaultImpls class.
317-
In case of inheritance from a Kotlin interface compiled in the old scheme
318-
(DefaultImpls, no default methods), the compatibility accessor in DefaultImpls
319-
will delegate to the DefaultImpls method of the superinterface. Otherwise the
320-
compatibility accessor will invoke the default method on the interface, with
321-
standard JVM runtime resolution semantics.
322-
Note that if interface delegation is used, all interface methods are delegated.
323-
The only exception are methods annotated with the deprecated @JvmDefault annotation.
324-
-Xjvm-default=all Generate default methods for all interface declarations with bodies.
325-
Do not generate DefaultImpls classes at all.
315+
-Xjvm-default=all Generate JVM default methods for all interface declarations with bodies in module.
316+
Do not generate DefaultImpls stubs for such declarations (that is default behaviour of compiler in 'disable' mode).
317+
If interface inherits such methods from interface compiled in 'disable' scheme
318+
then implicit DefaultImpls stubs would be generated as there are no default method for it.
326319
BREAKS BINARY COMPATIBILITY if some client code relies on the presence of
327320
DefaultImpls classes. Also prohibits the produced binaries to be read by Kotlin
328321
compilers earlier than 1.4.
329322
Note that if interface delegation is used, all interface methods are delegated.
330323
The only exception are methods annotated with the deprecated @JvmDefault annotation.
331-
-Xjvm-default=disable Do not generate JVM default methods and prohibit @JvmDefault annotation usage.
332-
-Xjvm-default=enable Allow usages of @JvmDefault; only generate the default method
324+
-Xjvm-default=all-compatibility In addition to `all` mode generate compatibility stubs in the DefaultImpls classes.
325+
Compatibility stubs could be useful for library and runtime authors
326+
to keep backward binary compatibility for existing client compiled against previous library versions.
327+
New 'all' and 'all-compatibility' modes are changing library ABI surface that will be used by client after their recompilation.
328+
In that sense client might be incompatible with previous library versions that REQUIRE PROPER LIBRARY VERSIONING.
329+
In case of inheritance from a Kotlin interface compiled in the old scheme
330+
(DefaultImpls, no default methods), the implicit stubs in DefaultImpls
331+
will delegate to the DefaultImpls method of the superinterface.
332+
Otherwise the compatibility stubs in DefaultImpls would invoke the default method on the interface via special accessor in it,
333+
with standard JVM runtime resolution semantics.
334+
Perform additional compatibility checks for classes in case of implicit specialized override
335+
presence in 'disable' scheme (See KT-39603 for more details)
336+
-Xjvm-default=disable Default behaviour. Do not generate JVM default methods and prohibit @JvmDefault annotation usage.
337+
-Xjvm-default=enable Deprecated. Allow usages of @JvmDefault; only generate the default method
333338
for annotated method in the interface
334339
(annotating an existing method can break binary compatibility)
335-
-Xjvm-default=compatibility Allow usages of @JvmDefault; generate a compatibility accessor
340+
-Xjvm-default=compatibility Deprecated. Allow usages of @JvmDefault; generate a compatibility accessor
336341
in the 'DefaultImpls' class in addition to the default interface method"""
337342
)
338343
var jvmDefault: String by FreezableVar(JvmDefaultMode.DEFAULT.description)

‎compiler/testData/cli/jvm/extraHelp.out‎

Lines changed: 19 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -49,27 +49,32 @@ where advanced options include:
4949
* warn (report a warning)
5050
-Xjvm-default={all|all-compatibility|disable|enable|compatibility}
5151
Emit JVM default methods for interface declarations with bodies.
52-
-Xjvm-default=all-compatibility Generate both a default method in the interface, and a compatibility accessor
53-
in the DefaultImpls class.
54-
In case of inheritance from a Kotlin interface compiled in the old scheme
55-
(DefaultImpls, no default methods), the compatibility accessor in DefaultImpls
56-
will delegate to the DefaultImpls method of the superinterface. Otherwise the
57-
compatibility accessor will invoke the default method on the interface, with
58-
standard JVM runtime resolution semantics.
59-
Note that if interface delegation is used, all interface methods are delegated.
60-
The only exception are methods annotated with the deprecated @JvmDefault annotation.
61-
-Xjvm-default=all Generate default methods for all interface declarations with bodies.
62-
Do not generate DefaultImpls classes at all.
52+
-Xjvm-default=all Generate JVM default methods for all interface declarations with bodies in module.
53+
Do not generate DefaultImpls stubs for such declarations (that is default behaviour of compiler in 'disable' mode).
54+
If interface inherits such methods from interface compiled in 'disable' scheme
55+
then implicit DefaultImpls stubs would be generated as there are no default method for it.
6356
BREAKS BINARY COMPATIBILITY if some client code relies on the presence of
6457
DefaultImpls classes. Also prohibits the produced binaries to be read by Kotlin
6558
compilers earlier than 1.4.
6659
Note that if interface delegation is used, all interface methods are delegated.
6760
The only exception are methods annotated with the deprecated @JvmDefault annotation.
68-
-Xjvm-default=disable Do not generate JVM default methods and prohibit @JvmDefault annotation usage.
69-
-Xjvm-default=enable Allow usages of @JvmDefault; only generate the default method
61+
-Xjvm-default=all-compatibility In addition to `all` mode generate compatibility stubs in the DefaultImpls classes.
62+
Compatibility stubs could be useful for library and runtime authors
63+
to keep backward binary compatibility for existing client compiled against previous library versions.
64+
New 'all' and 'all-compatibility' modes are changing library ABI surface that will be used by client after their recompilation.
65+
In that sense client might be incompatible with previous library versions that REQUIRE PROPER LIBRARY VERSIONING.
66+
In case of inheritance from a Kotlin interface compiled in the old scheme
67+
(DefaultImpls, no default methods), the implicit stubs in DefaultImpls
68+
will delegate to the DefaultImpls method of the superinterface.
69+
Otherwise the compatibility stubs in DefaultImpls would invoke the default method on the interface via special accessor in it,
70+
with standard JVM runtime resolution semantics.
71+
Perform additional compatibility checks for classes in case of implicit specialized override
72+
presence in 'disable' scheme (See KT-39603 for more details)
73+
-Xjvm-default=disable Default behaviour. Do not generate JVM default methods and prohibit @JvmDefault annotation usage.
74+
-Xjvm-default=enable Deprecated. Allow usages of @JvmDefault; only generate the default method
7075
for annotated method in the interface
7176
(annotating an existing method can break binary compatibility)
72-
-Xjvm-default=compatibility Allow usages of @JvmDefault; generate a compatibility accessor
77+
-Xjvm-default=compatibility Deprecated. Allow usages of @JvmDefault; generate a compatibility accessor
7378
in the 'DefaultImpls' class in addition to the default interface method
7479
-Xjvm-default-allow-non-default-inheritance
7580
Allow inheritance from 'all*' modes for 'disable' one

0 commit comments

Comments
 (0)