AGENTS.md

1# Kotlin Build Tools API (BTA)
2 
3An experimental interface for build systems (Gradle plugin, Maven plugin, etc.) to invoke Kotlin compilation without a direct compiler
4dependency. Build systems should use the API from `kotlin-build-tools-api`, load the implementation in an isolated ClassLoader, and avoid
5accessing compiler internals directly.
6 
7## Modules
8 
9| Module                                                                                                     | Purpose                                                                                                             |
10|------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
11| [`kotlin-build-tools-api`](kotlin-build-tools-api)                                                         | Public interfaces only; no implementation; `explicitApi()`; API dump checked in                                     |
12| [`kotlin-build-tools-impl`](kotlin-build-tools-impl)                                                       | Default implementation; version-coupled to the compiler; must run in isolated ClassLoader                           |
13| [`kotlin-build-tools-compat`](kotlin-build-tools-compat)                                                   | Adapter for compilers < 2.3.0 (wraps deprecated `CompilationService`)                                               |
14| [`kotlin-build-tools-cri-impl`](kotlin-build-tools-cri-impl)                                               | Protobuf serialization for Compiler Reference Index; shipped as shadow JAR                                          |
15| [`kotlin-build-tools-jdk-utils`](kotlin-build-tools-jdk-utils)                                             | Internal utility for Java 9+ platform ClassLoader detection; do not use outside BTA modules                         |
16| [`kotlin-build-tools-generator`](kotlin-build-tools-generator)                                             | KotlinPoet-based code generator producing compiler argument classes from `:compiler:arguments` and API version file |
17| [`kotlin-build-statistics`](kotlin-build-statistics)                                                       | Shared library for build metric collection (times, performance, GC, attributes); used by impl and KGP               |
18| [`util-kotlinpoet`](util-kotlinpoet)                                                                       | KotlinPoet utility helpers shared by code generators in the BTA area                                                |
19| [`kotlin-build-tools-api-tests`](kotlin-build-tools-api-tests)                                             | Main integration test suite (JUnit 5, multiple named test suites)                                                   |
20| [`kotlin-build-tools-api-forward-tests`](kotlin-build-tools-api-forward-tests) | Tests the forward compatibility guarantee (X+1)                                                                     |
21 
22## Architecture: ClassLoader Isolation
23 
24The impl JAR must be loaded in an isolated ClassLoader to prevent classpath conflicts with the consumer:
25 
26```kotlin
27val toolchains = KotlinToolchains.loadImplementation(implClasspath)  // implClasspath: List<Path>
28```
29 
30- `loadImplementation(List<Path>)` — preferred API; wraps the classpath in a `URLClassLoader` backed by `SharedApiClassesClassLoader`
31  automatically
32- `loadImplementation(ClassLoader)` — lower-level overload for custom ClassLoader setups; the ClassLoader's parent should be
33  `SharedApiClassesClassLoader`
34- The impl JAR version must match the compiler version (`kotlin-build-tools-impl` is version-coupled to the compiler)
35- For compilers < 2.3.0, include `kotlin-build-tools-compat` in the impl classpath → see [
36  `kotlin-build-tools-compat/README.md`](kotlin-build-tools-compat/README.md)
37 
38## Key Abstractions
39 
40All in `kotlin-build-tools-api/src/main/kotlin/org/jetbrains/kotlin/buildtools/api/`:
41 
42- `KotlinToolchains` — factory entry point; creates `BuildSession` instances (`KotlinToolchains.kt`)
43- `BuildSession` (`AutoCloseable`) — manages caches, thread pools, and daemon connections
44- `Toolchain` (sealed interface) — `JvmPlatformToolchain`, `CriToolchain`, `AbiValidationToolchain`
45- `BuildOperation<R>` / `BuildOperation.Builder` — type-safe operation configuration (`BuildOperation.kt`)
46- `ExecutionPolicy` — `InProcess` vs `WithDaemon` (`ExecutionPolicy.kt`)
47- `KotlinLogger` — pluggable logging interface (`KotlinLogger.kt`)
48 
49## Generated Files
50 
51Do not edit generated files manually — regenerate them with the tasks below.
52 
53Two kinds — both must be regenerated after relevant changes:
54 
55```bash
56# Regenerate generated sources (compiler argument classes and API version file; after changing compiler arguments in :compiler:arguments)
57./gradlew :compiler:build-tools:kotlin-build-tools-api:generateBtaSources
58./gradlew :compiler:build-tools:kotlin-build-tools-impl:generateBtaSources
59./gradlew :compiler:build-tools:kotlin-build-tools-compat:generateBtaSources
60 
61# Regenerate API binary compatibility dump (after any public API change)
62./gradlew :compiler:build-tools:kotlin-build-tools-api:apiDump
63```
64 
65## Compatibility Model
66 
67```
68BTA version X is guaranteed to work with implementation versions [X-3, X+1]
69```
70 
71- **Backward compat (X-3):** tested in `kotlin-build-tools-api-tests` compatibility suites (one suite per listed version)
72- **Forward compat (X+1):** tested in `kotlin-build-tools-api-forward-tests`
73- When adding an API change that may break compatibility, add tests to both modules and run locally to verify
74 
75## Running Tests
76 
77```bash
78# Run all tests (testExample is excluded from check — run it explicitly if needed)
79./gradlew :compiler:build-tools:kotlin-build-tools-api-tests:check
80 
81# Run against a specific BTA impl version (pattern: testCompatibility<version>)
82./gradlew :compiler:build-tools:kotlin-build-tools-api-tests:testCompatibility2.3.20
83 
84# Run against current snapshot impl
85./gradlew :compiler:build-tools:kotlin-build-tools-api-tests:testCompatibilitySnapshot
86 
87# Classpath/module-path escaping edge cases
88./gradlew :compiler:build-tools:kotlin-build-tools-api-tests:testEscapableCharacters
89 
90# Verify restricted arguments are rejected correctly
91./gradlew :compiler:build-tools:kotlin-build-tools-api-tests:testRestrictedArguments
92 
93# Individual named test suites follow the pattern :test<SuiteName>
94# The full list is in `businessLogicTestSuits` in kotlin-build-tools-api-tests/build.gradle.kts
95 
96# Forward compatibility tests
97./gradlew :compiler:build-tools:kotlin-build-tools-api-forward-tests:check
98```
99 
100## Writing Tests
101 
102See [`kotlin-build-tools-api-tests/README.md`](kotlin-build-tools-api-tests/README.md) for full conventions. Key rules:
103 
104- All tests extend `BaseTest` (`src/main/kotlin/BaseTest.kt`)
105- All compilation tests extend `BaseCompilationTest` (`src/main/kotlin/compilation/BaseCompilationTest.kt`)
106- Add `@DisplayName` to both test class and methods
107- Add `@TestMetadata` pointing to the relevant test data directory for IDE navigation
108- Keep test classes small — tests run in parallel
109- Use the scenario DSL for incremental compilation tests; see `src/testExample/kotlin/ExampleIncrementalScenarioTest.kt`
110- Annotate strategy-agnostic tests with `@DefaultStrategyAgnosticCompilationTest`
111- Add a new test suite by appending its name to `businessLogicTestSuits` in `build.gradle.kts`
112- Compatibility suites (`testCompatibility*`): add tests sparingly — they run once per listed version
113 
114## Key Conventions and Pitfalls
115 
116- Every public API addition in `kotlin-build-tools-api` must include KDoc documentation
117- Do not add implementation dependencies to `kotlin-build-tools-api` — it must stay implementation-free
118- Do not use `kotlin-build-tools-jdk-utils` outside BTA modules (requires `@KotlinBuildToolsInternalJdkUtils` opt-in)
119- After changing compiler arguments, always regenerate both `generateBtaSources` and `apiDump`
120