In the previous post Kotlin Pitfalls: FunctionReference, I covered how to solve the compatibility issue caused by FunctionReference when upgrading Kotlin from 1.3 to 1.5. But that’s far from the only compatibility issue in Kotlin. How do we address Kotlin’s compatibility problems systematically?

What Are Compatibility Issues

Software compatibility issues can be broadly divided into two categories: API compatibility and ABI compatibility.

API (Application Programming Interface) Compatibility

In short, this is about interface-level compatibility, which itself falls into two subcategories:

API Deprecation

For example, Kotlin 1.5 deprecated the String.toUpperCase() API in favor of String.uppercase(). Although the API is deprecated, you can still use it – the compiler will issue a warning but won’t halt compilation.

API Removal

For example, JDK 11 removed the Thread.destroy() and Thread.stop(Throwable) APIs. If your project uses Thread.destroy(), upgrading to JDK 11 will break the build. You either find an alternative or rewrite the implementation.

ABI (Application Binary Interface) Compatibility

In short, this is about binary-level compatibility. For languages running on the JVM, binary compatibility mainly concerns bytecode compatibility, which also has two subcategories:

JVM Bytecode Version Compatibility

A typical example is the major version of class files.

Language Runtime Version Compatibility

Some Kotlin language features are implemented at the compiler level. Different versions of the Kotlin compiler may implement things differently. While Kotlin developers all call the Kotlin standard library, the compiler generates additional bytecode and even classes to implement the syntactic sugar that makes Kotlin look elegant – for instance, the ubiquitous Function types.

The Real Headache

Incompatible Bytecode

Remember the issue from Kotlin Pitfalls: FunctionReference?

1
2
3
4
5
fun f(fn: (Any) -> Unit) {}

fun ff() {
    f(::println)
}

If we compile the above code with org.jetbrains.kotlin:kotlin-gradle-plugin:1.5.31, we get the following bytecode:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
final synthetic class io/johnsonlee/kotlin/TestKt$ff$1 extends kotlin/jvm/internal/FunctionReferenceImpl implements kotlin/jvm/functions/Function1 {

  // access flags 0x0
  <init>()V
    ALOAD 0
    ICONST_1
    LDC Lkotlin/io/ConsoleKt;.class
    LDC "println"
    LDC "println(Ljava/lang/Object;)V"
    LDC 1
    INVOKESPECIAL kotlin/jvm/internal/FunctionReferenceImpl.<init> (ILjava/lang/Class;Ljava/lang/String;Ljava/lang/String;I)V
    RETURN
    MAXSTACK = 6
    MAXLOCALS = 1

}

The bytecode generated by the Kotlin compiler contains content that doesn’t exist in older versions. As a result, other projects using Kotlin below 1.4 will encounter a NoSuchMethodError at runtime when they consume this bytecode.

Incompatible Metadata

Beyond class bytecode, Kotlin also generates other binary content:

  1. Metadata (@Metadata)
  2. Module mapping (*.kotlin_module)
  3. ……

All of these binary artifacts contain version information and version compatibility constraints.

Taking @Metadata as an example, the default compatibility strategy is that x.y is compatible with x.{y + 1}, unless versions have strict semantics.

So how are the version numbers for these binary artifacts determined?

Metadata Version

The @Metadata version is determined by the Kotlin Compiler version. For Gradle projects, this is effectively the kotlin-gradle-plugin version. Changing the kotlin-gradle-plugin version will affect the @Metadata version.

Module Mapping Version

The *.kotlin_module version is also determined by the Kotlin Compiler version and matches the @Metadata version. If there’s a version incompatibility, compilation will fail with:

1
Module was compiled with an incompatible version of Kotlin. The binary version of its metadata is a.b.c, expected version is x.y.z.

Java’s Solution

Java has a systematic solution for compatibility issues. If you’ve used Gradle, you’ll remember that Java compile tasks can be configured with these two parameters:

  1. sourceCompatibility
  2. targetCompatibility

For example:

1
2
3
4
java {
    sourceCompatibility = JavaVersion.VERSION_1_8
    targetComaptibility = JavaVersion.VERSION_1_8
}

These correspond to the API and ABI levels mentioned earlier:

# Java Compiler Options Gradle Compiler Task Options
API -source sourceCompatibility
ABI -target targetCompatibility

Kotlin’s Solution

Kotlin also provides compiler options to specify versions:

# Kotlin Compiler Options Gradle Compiler Task Options
API -api-version apiVersion
ABI -language-version languageVersion

Usage:

1
2
3
4
5
6
tasks.withType<KotlinCompile> {
    kotlinOptions {
        apiVersion = "1.5"
        languageVersion = "1.5"
    }
}

Important notes:

  1. -api-version cannot be greater than -language-version
  2. Restricting -language-version implicitly restricts -api-version as well

The correspondence between Kotlin and Java compiler options:

# Kotlin Compiler Options Java Compiler Options
API -api-version -source
ABI -language-version -target

So Kotlin’s compatibility management is just as straightforward as Java’s. But how exactly should you use these two compiler options?

Best Practices

Unify the Kotlin Version

Your project’s Kotlin version should ideally use embeddedKotlinVersion (the version of Kotlin embedded in Gradle). For example:

1
2
3
4
5
6
7
8
9
buildscript {
    repositories {
        mavenCentral()
        gradlePluginPortal()
    }
    dependencies {
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:${embeddedKotlinVersion}")
    }
}

Or:

1
2
3
plugins {
    kotlin("jvm") version embeddedKotlinVersion
}

Specify -language-version or -api-version

Using the FunctionReference issue as an example, our goal is backward compatibility at the bytecode level – the ABI level. To ensure the generated bytecode doesn’t contain content from Kotlin 1.4 (i.e., backward compatible with Kotlin 1.3), you can specify either -language-version or -api-version:

1
2
3
4
5
tasks.withType<KotlinCompile> {
    kotlinOptions {
        languageVersion = "1.3"
    }
}

Or:

1
2
3
4
5
tasks.withType<KotlinCompile> {
    kotlinOptions {
        apiVersion = "1.3"
    }
}

With either option, the compiled bytecode becomes:

1
2
3
4
5
6
7
8
9
io.johnsonlee.kotlin.TestKt$ff$1();
    descriptor: ()V
    flags: (0x0000)
    Code:
      stack=2, locals=1, args_size=1
         0: aload_0
         1: iconst_1
         2: invokespecial #57 // Method kotlin/jvm/internal/FunctionReference."<init>":(I)V
         5: return

Notice that the FunctionReference bytecode representation has changed.

Since both options work, what’s the actual difference between -language-version and -api-version?

The difference is:

Bytecode compiled with -language-version will have a @Metadata version of 1.1.18, while bytecode compiled with -api-version will still have a @Metadata version of 1.5.1.

This tells us that -api-version doesn’t achieve full ABI-level compatibility. -language-version has a broader impact – it not only restricts language features across versions but also constrains the versions of binary artifacts including metadata.

Although -language-version and -api-version affect the compiled bytecode content, they do not change the version of the Kotlin stdlib that your project depends on. Even with the 1.5 kotlin-gradle-plugin, if you set -language-version or -api-version to 1.3, the project’s dependencies won’t change. This is why Kotlin can achieve backward compatibility – even when some APIs are disallowed in higher versions (e.g., toLowerCase() is disallowed from 1.5 onward), the API hasn’t actually been removed. The compiler simply won’t let you use it:

1
2
3
4
@DeprecatedSinceKotlin(
    warningSince = "1.3",
    errorSince = "1.5"
)

If a class has already been compiled with -language-version="1.3", it will work perfectly fine with the 1.5 stdlib.