I recently learned about `org.jetbrains.kotlin:kotlin-gradle-plugin-api` artifact. Does it have dedi...

# gradle

[mateusz.kwiecinski]

I recently learned about org.jetbrains.kotlin:kotlin-gradle-plugin-api artifact. Does it have dedicated documentation page somewhere where one can learn more about it? Does -api come with extra stability? Should I aim to migrate my Gradle plugins to call only classes from -api (meaning it's worth reporting issues if some apis don't seem available?)

[mateusz.kwiecinski]

An example snippet that I wasn't able to replace using api classes is the block from documentation

kotlin {
    jvmToolchain(17)
}

In this case KotlinTopLevelExtension#jvmToolchain is not exposed in the api, which means it's required to either use java extension (so, not using -api at all) or configure all UsesKotlinJavaToolchain tasks manually

[tapchicoma]

Does it have dedicated documentation page somewhere where one can learn more about it?

We are aiming to publish KGP-API reference for 2.0.0 release on kotlinlang.org

Does -api come with extra stability?

Yes, for KGP-API we are running binary validator ensuring no breaking changes in minor releases (e.g. 2.0.x) and proper deprecation cycle in case we need to remove something.

Should I aim to migrate my Gradle plugins to call only classes from -api (meaning it's worth reporting issues if some apis don't seem available?)

Generally yes. It is known thing that this API for now still misses some useful API (like some extensions, plugins, etc.). If you need something from API - please open a new Kotlin issue

[mateusz.kwiecinski]

Thank you for the response 🙏 All clear now 👍