Gradle build config: Replace hard dependency on JVM 11 with Java Toolchain

[aSemy]

What do we have now?

The Gradle config adds a hard dependency on JVM 11

kotlinx.coroutines/buildSrc/src/main/kotlin/jdk-convention.gradle.kts

Lines 7 to 14 in 4116d4a

	if (!JavaVersion.current().isJava11Compatible) {
	val message = "Project required JDK 11+, but found ${JavaVersion.current()}"
	if (Idea.active) {
	logger.error(message)
	} else {
	throw GradleException(message)
	}
	}

This caused an error in the Dokka integration tests when Dokka migrated to use Gradle Toolchains.

What should be instead?

Gradle introduced Java Toolchains in version 6.7. This will automatically detect and configure a compatible Java version.

https://github.com/Kotlin/dokka/blob/14c05d70b52814fe48e930b3f61fed5e8586718c/buildSrc/src/main/kotlin/org/jetbrains/conventions/base-java.gradle.kts

// buildSrc/src/main/kotlin/conventions/java-base.gradle.kts
java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(8))
    }
}

Why?

https://docs.gradle.org/current/userguide/toolchains.html

• Follow Gradle best practices
• Better compatibility with Dokka integration tests
• Better error messages if a Java version is not available
• The Java Toolchain can be set on a task-by-task basis
• Simpler build config (no more Java source/target compatibility)

Why not?

• Setting a Gradle Toolchain is not compatible with setting Java source/target compatibility
  

  kotlinx.coroutines/buildSrc/src/main/kotlin/kotlin-jvm-conventions.gradle.kts

  Lines 13 to 16 in 4116d4a

  	java {
  	sourceCompatibility = JavaVersion.VERSION_1_8
  	targetCompatibility = JavaVersion.VERSION_1_8
  	}

• The existing kotlinx.coroutines Gradle config does not currently follow Gradle best practices and so this might cause issues. It could do with a big ol' refactor

[qwwdfsad]

Setting a Gradle Toolchain is not compatible with setting Java source/target compatibility

Could you please elaborate on what it means in detail? I would expect setting toolchain to 8 to be more or less identical to having source/target compatibility being 8 as well.

Refactoring of scripts is welcome, but it might bring quite a lot of trouble. For various reasons, both its structure and artifacts layout are quite non-standard and consist of tweaks that might be already unneeded (as coroutines were one of the earliest adopters of MPP and HMPP plugins)

[aSemy]

Could you please elaborate on what it means in detail? I would expect setting toolchain to 8 to be more or less identical to having source/target compatibility being 8 as well.

It's a hard limit that causes a Gradle error.

For example, this build config

// build.gradle.kts
plugins {
  kotlin("jvm") version "1.8.10"
}

kotlin {
  jvmToolchain(11)
}

java {
  sourceCompatibility = JavaVersion.VERSION_1_8
  targetCompatibility = JavaVersion.VERSION_1_8
}

Causes

org.gradle.api.InvalidUserDataException: The new Java toolchain feature cannot be used at the project level in combination with source and/or target compatibility

Instead it would have to be

plugins {
  kotlin("jvm") version "1.8.10"
}

kotlin {
  jvmToolchain(8)
}

It might be possible to work around it by setting the toolchain only at the task level, but I'm not certain.

[qwwdfsad]

Fixed in d12eb45