Mangled JVM names in public API
| Diagnostic | MANGLED_JVM_NAME_PUBLIC_API |
| Default severity | Error |
| Applies to | JVM compilations only |
| Gradle property | mangledJvmNamePublicApi |
| Exemption | @IntentionallyMangledJvmName |
What it reports
Functions, properties, and constructors in the public API whose JVM name changes because the signature uses a value class:
- In a value parameter, extension receiver, or context parameter.
- As a member's return type.
- As a mutable property's type, which affects its setter even at the top level.
@JvmInlinepublic value class UserId(public val raw: String,)public fun take(id: UserId) { }
Rationale
A mangled JVM method name such as take-<hash> is invalid in Java source.
For constructors with value-class parameters, the compiler generates a private constructor and a synthetic constructor that Java source can't call.
Use @JvmName to give the function a valid name in Java source.
Don't
public fun take(id: UserId) { }
Do
@JvmName("take")public fun take(id: UserId) { }
@JvmExposeBoxed generates boxed variants for Java callers alongside the mangled variants.
Constructors need this annotation because the compiler doesn't accept @JvmName on them.
Don't
public class Wallet(public val id: UserId)
Do
@OptIn(ExperimentalStdlibApi::class)@JvmExposeBoxedpublic class Wallet(public val id: UserId,)
Don't
public class Ledger {public fun current(): UserId = UserId("x")}
Do
public class Ledger {@JvmName("current")public fun current(): UserId = UserId("x")}
Notes
- Rename property accessors with
@get:JvmNameand@set:JvmName. The check treats each accessor separately. A rename or@JvmSyntheticon one accessor doesn't exempt the other. - Open and abstract members don't support
@JvmNameor boxed variants. If Java callers need access, remove the value class from the signature. - Value classes in type arguments, such as
List<UserId>, don't cause JVM name mangling. - If a top-level function or getter uses a value class only as its return type, its JVM name doesn't change.
- The check skips members and constructors of the value class itself.
- The plugin checks
suspendfunctions with Kotlin-only API without JvmSynthetic. - The check skips overrides,
@JvmSyntheticfunctions and accessors, and@PublishedApi internaldeclarations.
Exemption
If this is intended, apply @IntentionallyMangledJvmName to the declaration or an
enclosing class.
Use the exemption when the declaration is part of the API design or must stay for backwards compatibility.
@IntentionallyMangledJvmName(reason = ExemptionReason.API_DESIGN)public fun take(id: UserId) { }
Configuration
apiWatchdog {javaInterop {mangledJvmNamePublicApi = WatchdogSeverity.ERROR}}
javaInterop { enabled = false } disables all Java interop checks.
For a direct compiler call:
-P plugin:org.jetbrains.kotlinx.library.api.watchdog:diagnosticSeverity=MANGLED_JVM_NAME_PUBLIC_API:error