Build Tools API plan

[agluszak]

What BTAPI is: https://kotlinlang.org/docs/build-tools-api.html

"[Build Tools API] should be the preferred way to work with Kotlin compiler when integrating Kotlin builds into different build systems."

BTAPI unlocks:

• kotlinc-driven sub-target incremental compilation
• possibility to use any kotlin compiler version within BTAPI compatibility range
• simplification of the internal plumbing
• prevent leaking rules_kotlin-related classes into the user compilation classpath (BTAPI uses an isolated classloader)
• easier KMP integration ([kmp] Outline of a roadmap #1466)
• general futureproofing

BTAPI is split into two main artifacts. The build-tools-api is the one embedded into the build tool itself. Its version determines the compatibility range. Then there is the build-tools-impl artifact, which wraps around and calls the compiler. The impl artifact can be supplied by the users who want to customize the version being used. There's also the build-tools-compat artifact (see https://github.com/JetBrains/kotlin/tree/master/compiler/build-tools/kotlin-build-tools-compat)

BTAPI-related development will happen in the develop branch. The end result will be something along the lines of #1449.

The monster-PR is being split into smaller chunks, each of them reviewed separately and merged into the develop branch.

Roadmap:

• remove dead code from rules_kotlin
• drop WORKSPACE support
  • migration to BTAPI is a big task which requires a lot of internal changes and some breaking changes to the public api. WORKSPACE support gets in the way
  • WORKSPACE is deprecated as of Bazel 8 and removed in Bazel 9
  • rules_jvm_external will remove WORKSPACE support in the upcoming 7.0 release
• Use rules_jvm_external for dependency management - [maintenance] Use rules_jvm_external for getting dependencies #1470.
  • btapi jars have quite a lot of dependencies (which have their own dependencies). This set of dependencies is not stable and can change between versions. We want to avoid the pain of having to track and manually download all of them.
  • current implementation of rules_kotlin downloads a zipped kotlin distribution and does some introspection on it.
• replace the old kotlinc invocation and experimental last-mile-only BTAPI invoker with a proper integration
  • this is going to be split into smaller parts
• integrate BTAPI-based incremental compilation with rules_kotlin worker
  • leverage the IC test set from JetBrains-internal rules (https://github.com/JetBrains/intellij-community/tree/master/build/jvm-rules/jvm-inc-builder-tests/testData)

Breaking changes:

• Custom compiler version is now set by providing a btapi_impl.jar to the toolchain. See examples/btapi_compat.
• WORKSPACE support dropped (Drop WORKSPACE support #1480)
• All plugins must now target the embeddable compiler

TODO:

• final desired shape of the public API. Should the build-tools-impl jar (+ dependencies) be set as an attribute on the toolchain? Or do we prefer a bzlmod extension? Do we want to completely hide the fact that we're using rules_jvm_external?
• compiler options DSL. Should we rely on BTAPI directly? Or do we continue having kotlinc-versioned DSLs?
  • previous attempt to generate the DSL from kotlin-compiler-arguments-description Generate kotlinc options from kotlin-compiler-arguments-description #1406

Relevant YouTrack issues:

• BTAPI stability
• KAPT support in BTAPI
• typesafe BTAPI compiler arguments

[jdai8]

+1 on this project. We're interested especially in sub-target incremental compilation.

Here's a blog post showing some impressive results when doing this for Buck2 at Meta: https://engineering.fb.com/2025/08/26/open-source/enabling-kotlin-incremental-compilation-on-buck2/

[shalupov]

Could we document how to use a custom version of Kotlin which a company builds by itself, not in any available maven repository?

[restingbull]

Could we document how to use a custom version of Kotlin which a company builds by itself, not in any available maven repository?

... I think I need some details on this use-case.

What exactly do you need?

[shalupov]

Could we document how to use a custom version of Kotlin which a company builds by itself, not in any available maven repository?

... I think I need some details on this use-case.

What exactly do you need?

At JetBrains monorepo we frequently need to use custom-built versions of Kotlin because we need some fixes earlier than they make it to any official release. Ideally, we want to point rules_kotlin to some kotlin distribution and make use of it

We're working on it from Kotlin side too: https://youtrack.jetbrains.com/issue/KT-86306

cc @mfilippov