Comparison

A · AGENTS.md · JetBrains/kotlin B · AGENTS.md · JetBrains/kotlin

What each file covers, counted
Dimension	Shared	Only in A	Only in B	Overlap
Sections	0	8	19	0%
Commands	0	0	10	0%
Section tags	2	1	4	29%

What each file covers

Sections

0 shared · 8 only in A · 19 only in B

− Compiler Architecture
− Intro
− Two Frontends
− FIR Compilation Phases
− IR (Intermediate Representation)
− Inference
− Commit Guidelines
− Testing
+ Kotlin Build Tools API (BTA)
+ Modules
+ Architecture: ClassLoader Isolation
+ Key Abstractions
+ Generated Files
+ Regenerate generated sources (compiler argument classes and API version file; after changing compiler arguments in :compiler:arguments)
+ Regenerate API binary compatibility dump (after any public API change)
+ Compatibility Model
+ Running Tests
+ Run all tests (testExample is excluded from check — run it explicitly if needed)
+ Run against a specific BTA impl version (pattern: testCompatibility<version>)
+ Run against current snapshot impl
+ Classpath/module-path escaping edge cases
+ Verify restricted arguments are rejected correctly
+ Individual named test suites follow the pattern :test<SuiteName>
+ The full list is in `businessLogicTestSuits` in kotlin-build-tools-api-tests/build.gradle.kts
+ Forward compatibility tests
+ Writing Tests
+ Key Conventions and Pitfalls

Commands

0 shared · 0 only in A · 10 only in B

+ ./gradlew :compiler:build-tools:kotlin-build-tools-api:generateBtaSources
+ ./gradlew :compiler:build-tools:kotlin-build-tools-impl:generateBtaSources
+ ./gradlew :compiler:build-tools:kotlin-build-tools-compat:generateBtaSources
+ ./gradlew :compiler:build-tools:kotlin-build-tools-api:apiDump
+ ./gradlew :compiler:build-tools:kotlin-build-tools-api-tests:check
+ ./gradlew :compiler:build-tools:kotlin-build-tools-api-tests:testCompatibility2.3.20
+ ./gradlew :compiler:build-tools:kotlin-build-tools-api-tests:testCompatibilitySnapshot
+ ./gradlew :compiler:build-tools:kotlin-build-tools-api-tests:testEscapableCharacters
+ ./gradlew :compiler:build-tools:kotlin-build-tools-api-tests:testRestrictedArguments
+ ./gradlew :compiler:build-tools:kotlin-build-tools-api-forward-tests:check

Section tags

2 shared · 1 only in A · 4 only in B

− git-pr
+ code-style
+ architecture
+ api
+ deployment
build
test

Line diff

+104 added−26 removed16 unchanged13.3% identical

JetBrains/kotlin · compiler/AGENTS.md

@@ −1 @@

1# Compiler Architecture

3## Intro

5Consider reading [fir-basics.md](../docs/fir/fir-basics.md).

7## Two Frontends

91. **K1/FE 1.0 (Legacy)**: Located in `compiler/frontend/` - uses PSI and BindingContext

102. **K2/FIR (Current)**: Located in `compiler/fir/` - Frontend IR, the new compiler frontend

12## FIR Compilation Phases

14FIR processes code through sequential phases (see `FirResolvePhase.kt`).

16Key invariant: In phase B following phase A, all FIR elements visible in B are resolved to phase A.

18## IR (Intermediate Representation)

20Located in `compiler/ir/`. Backend IR is used by all targets for:

21- Lowering (transforming code to target-friendly form)

22- Optimization

23- Serialization to klibs

25Backend implementations:

26- `compiler/ir/backend.jvm/` - JVM backend

27- `compiler/ir/backend.js/` - JavaScript backend

28- `compiler/ir/backend.wasm/` - WebAssembly backend

29- `kotlin-native/backend.native/`, `native/` - Native backend

31## Inference

33For type inference implementation details, read [inference.md](../docs/fir/inference.md).

35## Commit Guidelines

37- **FIR prefix**: When changes are mostly related to FIR (`compiler/fir/`), use `FIR: ` prefix in the commit subject line.

38- **Test-before-fix**: When fixing an issue and adding a test, commit the test data as a separate commit **before** the fix. This helps reviewers see how the fix actually changes semantics (the test will show diagnostic differences in the fix commit).

40## Testing

42For FIR analysis test data format (directives, diagnostic markers, file structure), see [analysis-tests/AGENTS.md](fir/analysis-tests/AGENTS.md).

JetBrains/kotlin · compiler/build-tools/AGENTS.md

@@ +1 @@

1# Kotlin Build Tools API (BTA)

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.

7## Modules

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) |

22## Architecture: ClassLoader Isolation

24The impl JAR must be loaded in an isolated ClassLoader to prevent classpath conflicts with the consumer:

26```kotlin

27val toolchains = KotlinToolchains.loadImplementation(implClasspath) // implClasspath: List<Path>

28```

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)

38## Key Abstractions

40All in `kotlin-build-tools-api/src/main/kotlin/org/jetbrains/kotlin/buildtools/api/`:

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`)

49## Generated Files

51Do not edit generated files manually — regenerate them with the tasks below.

53Two kinds — both must be regenerated after relevant changes:

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

61# Regenerate API binary compatibility dump (after any public API change)

62./gradlew :compiler:build-tools:kotlin-build-tools-api:apiDump

63```

65## Compatibility Model

67```

68BTA version X is guaranteed to work with implementation versions [X-3, X+1]

69```

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

75## Running Tests

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

81# Run against a specific BTA impl version (pattern: testCompatibility<version>)

82./gradlew :compiler:build-tools:kotlin-build-tools-api-tests:testCompatibility2.3.20

84# Run against current snapshot impl

85./gradlew :compiler:build-tools:kotlin-build-tools-api-tests:testCompatibilitySnapshot

87# Classpath/module-path escaping edge cases

88./gradlew :compiler:build-tools:kotlin-build-tools-api-tests:testEscapableCharacters

90# Verify restricted arguments are rejected correctly

91./gradlew :compiler:build-tools:kotlin-build-tools-api-tests:testRestrictedArguments

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

96# Forward compatibility tests

97./gradlew :compiler:build-tools:kotlin-build-tools-api-forward-tests:check

98```

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

@@ −1 +1 @@

1−# Compiler Architecture

1+# Kotlin Build Tools API (BTA)

3−## Intro

3+An experimental interface for build systems (Gradle plugin, Maven plugin, etc.) to invoke Kotlin compilation without a direct compiler

4+dependency. Build systems should use the API from `kotlin-build-tools-api`, load the implementation in an isolated ClassLoader, and avoid

5+accessing compiler internals directly.

5−Consider reading [fir-basics.md](../docs/fir/fir-basics.md).

7+## Modules

7−## Two Frontends

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) |

821

9−1. **K1/FE 1.0 (Legacy)**: Located in `compiler/frontend/` - uses PSI and BindingContext

10−2. **K2/FIR (Current)**: Located in `compiler/fir/` - Frontend IR, the new compiler frontend

22+## Architecture: ClassLoader Isolation

1123

12−## FIR Compilation Phases

24+The impl JAR must be loaded in an isolated ClassLoader to prevent classpath conflicts with the consumer:

1325

14−FIR processes code through sequential phases (see `FirResolvePhase.kt`).

26+```kotlin

27+val toolchains = KotlinToolchains.loadImplementation(implClasspath) // implClasspath: List<Path>

28+```

1529

16−Key invariant: In phase B following phase A, all FIR elements visible in B are resolved to phase A.

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)

1737

18−## IR (Intermediate Representation)

38+## Key Abstractions

1939

20−Located in `compiler/ir/`. Backend IR is used by all targets for:

21−- Lowering (transforming code to target-friendly form)

22−- Optimization

23−- Serialization to klibs

40+All in `kotlin-build-tools-api/src/main/kotlin/org/jetbrains/kotlin/buildtools/api/`:

2441

25−Backend implementations:

26−- `compiler/ir/backend.jvm/` - JVM backend

27−- `compiler/ir/backend.js/` - JavaScript backend

28−- `compiler/ir/backend.wasm/` - WebAssembly backend

29−- `kotlin-native/backend.native/`, `native/` - Native backend

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`)

3048

31−## Inference

49+## Generated Files

3250

33−For type inference implementation details, read [inference.md](../docs/fir/inference.md).

51+Do not edit generated files manually — regenerate them with the tasks below.

3452

35−## Commit Guidelines

53+Two kinds — both must be regenerated after relevant changes:

3654

37−- **FIR prefix**: When changes are mostly related to FIR (`compiler/fir/`), use `FIR: ` prefix in the commit subject line.

38−- **Test-before-fix**: When fixing an issue and adding a test, commit the test data as a separate commit **before** the fix. This helps reviewers see how the fix actually changes semantics (the test will show diagnostic differences in the fix commit).

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

3960

40−## Testing

61+# Regenerate API binary compatibility dump (after any public API change)

62+./gradlew :compiler:build-tools:kotlin-build-tools-api:apiDump

63+```

4164

42−For FIR analysis test data format (directives, diagnostic markers, file structure), see [analysis-tests/AGENTS.md](fir/analysis-tests/AGENTS.md).

65+## Compatibility Model

66+

67+```

68+BTA 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+

102+See [`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+