Build Tools API

Active contributors: Yahor Berdnikau, Andrey Yastrebov, Timofey Solonin

The Build Tools API (BTAPI) is a stable, in-process API for invoking the Kotlin compiler from build tools. It lives in compiler/build-tools/ and was introduced to give KGP, the Maven plugin, JPS, and external tools a versioned API surface that does not depend on internal compiler details. Files under this tree are among the most frequently modified in the repository — BTAPI has been on a sustained iteration path since 2024.

Purpose

Replace ad-hoc, version-coupled access to the compiler internals with a small, stable, evolution-friendly API. Build tools call into BTAPI to compile Kotlin code; BTAPI delegates to the underlying compiler, but its shape is independent of the compiler's internal version.

Directory layout

compiler/build-tools/
├── kotlin-build-tools-api/                   The public API (interfaces, data classes)
├── kotlin-build-tools-impl/                  Default implementation backed by the in-tree compiler
├── kotlin-build-tools-cri-impl/              Compile request infrastructure
├── kotlin-build-tools-compat/                Compatibility shims for older build-tool versions
├── kotlin-build-tools-api-tests/             API smoke tests
├── kotlin-build-tools-api-forward-compatibility-tests/  Test that newer impl works for older API
├── kotlin-build-tools-generator/             Generates impl classes from argument descriptions
├── kotlin-build-tools-jdk-utils/             JDK selection and toolchain helpers
├── kotlin-build-statistics/                  Build metrics collection
├── util-kotlinpoet/                          Internal helper around KotlinPoet
├── AGENTS.md                                 Onboarding for BTAPI developers
└── README.md

Key abstractions

Type	Where	Role
KotlinToolchain	kotlin-build-tools-api/.../KotlinToolchain.kt	Top-level entry point; opens compilation sessions.
CompilationService	kotlin-build-tools-api/.../CompilationService.kt	Service that runs an actual compile.
JvmCompilerArguments, CommonCompilerArguments, ...	kotlin-build-tools-api/.../arguments	Strongly typed argument classes.
CompilationResult	kotlin-build-tools-api/.../CompilationResult.kt	Outcome (success, errors, warnings).
*ArgumentsImpl	kotlin-build-tools-impl/gen/.../*ArgumentsImpl.kt	Generated implementation classes.
KotlinWrapperPre2_4_0	kotlin-build-tools-api/.../internal/wrappers/KotlinWrapperPre2_4_0.kt	Compatibility layer for compilers older than Kotlin 2.4.
CompilerArgumentValueAdapter	kotlin-build-tools-impl/.../CompilerArgumentValueAdapter.kt	Translates BTAPI argument values to compiler-internal values.

How the API is generated

A large portion of kotlin-build-tools-api/ and kotlin-build-tools-impl/ is generated from argument descriptions in compiler/arguments/. The generator (kotlin-build-tools-generator/ plus compiler/arguments/) reads the argument list and produces:

• Public interfaces and value classes in kotlin-build-tools-api/.../arguments/.
• Internal impl classes in kotlin-build-tools-impl/gen/.../arguments/.
• Compatibility wrappers (KotlinWrapperPreX_Y_Z) for older compiler versions.
• API dump files (kotlin-build-tools-api/api/kotlin-build-tools-api.api) — checked into git so CI can verify API stability.

Compatibility model

BTAPI is unusual in that it is forward-compatible: a newer BTAPI impl can be loaded into an older client jar. This is achieved by versioned wrappers (KotlinWrapperPreX_Y_Z) that adapt the modern compiler to the surface an older client expects. The compatibility tests under kotlin-build-tools-api-forward-compatibility-tests/ exercise this.

The kotlin-build-tools-compat/ module ships compatibility shims and is itself rebuilt continuously — its gen/.../JvmCompilerArgumentsImpl.kt shows up among the most-modified files in the repo.

How a build tool uses BTAPI

graph LR
    KGP["KGP / Maven / JPS"] -->|loads| API["kotlin-build-tools-api jar"]
    API -->|delegates to| Impl["kotlin-build-tools-impl jar"]
    Impl -->|invokes| Compiler["In-tree compiler<br/>(compiler/cli)"]
    Compiler --> Out["Class files / klibs / ..."]

The build tool depends on kotlin-build-tools-api, configures arguments via the typed classes, and asks the impl jar to perform a compile. The impl jar bundles the actual compiler.

Build statistics

kotlin-build-statistics/ collects build metrics (compilation time, cache hits, daemon usage) that the build tool can forward to telemetry or display to users. KGP integrates with it to power the --scan Build Scan output.

Integration points

• Consumers: KGP (libraries/tools/kotlin-gradle-plugin*/), Maven plugin (libraries/kotlin-maven-plugin/), JPS (jps/), external IDEs and build tools.
• Producers: the in-tree Kotlin compiler (compiler/cli/).
• Versioning: each BTAPI release carries a stable interface version; older clients work against newer impls via wrappers.

Where to start

For a new compiler flag exposed to build tools: start in compiler/arguments/, regenerate, and confirm the new field appears in kotlin-build-tools-api/.../arguments/ and kotlin-build-tools-impl/gen/.../arguments/.

For a change that affects API stability: read kotlin-build-tools-api/api/kotlin-build-tools-api.api first; check that your change does not break the dump or that you update it intentionally. The compiler/build-tools/AGENTS.md document is required reading.

See cli.md for the underlying CLI and tools/kotlin-gradle-plugin.md for the primary BTAPI consumer.