Tooling

The Kotlin repository's tooling is itself a substantial subject. The main build is Gradle, but a Maven-based path also exists for some library artifacts, and the Native backend has its own build configuration. Code generation, dependency verification, ABI dumps, and CI integration round out the toolchain.

The Gradle build

Configuration entry points:

File	Role
settings.gradle.kts (root)	Enumerates modules and included builds. ~52KB of hand-written DSL.
build.gradle.kts (root)	Cross-cutting subproject configuration. ~50KB of DSL.
gradle.properties	Build flags, JDK selection, bootstrap version pin.
gradle/verification-metadata.xml	Dependency hash verification.
gradle/libs.versions.toml, gradle/cacheRedirector.settings.gradle.kts	Version catalog and dependency redirector.
repo/gradle-build-conventions/	Convention plugins (included builds).
repo/gradle-settings-conventions/	Settings-level convention plugins.

The repository does not use a single subprojects { ... } block to configure everything; instead it composes per-area convention plugins from repo/gradle-build-conventions/ (e.g., common-configuration.gradle.kts — one of the most-modified files in the project). This keeps each area's configuration locally readable.

Common Gradle commands

Task	Purpose
./gradlew dist	Assemble the compiler distribution at dist/kotlinc/.
./gradlew install	Install all artifacts to ~/.m2/repository.
./gradlew generateTests	Regenerate *Generated.java test runners from testData/.
./gradlew compilerTest	Run all compiler tests.
./gradlew coreLibsTest	Run stdlib, reflect, kotlin-test tests.
./gradlew gradlePluginTest	Run KGP unit tests (not integration).
./gradlew :compiler:test --tests "<FQCN>"	Run a specific test class.

Use -Pteamcity=true to enable proguard/jar compression as on CI. Pass -Pkotlin.native.enabled=true to include Native targets in resolution.

Code generation

Generators are scattered, but the patterns are consistent. Each one reads structured input (often Kotlin or JSON) and writes Kotlin/Java source into a gen/ directory.

Generator	Reads	Writes
compiler/fir/checkers/checkers-component-generator/	FirDiagnosticsList.kt	compiler/fir/checkers/gen/.../FirErrors.kt, FirErrorsDefaultMessages.kt
compiler/ir/ir.tree/tree-generator/	tree definitions	compiler/ir/ir.tree/gen/...
analysis/analysis-api-fir/analysis-api-fir-generator/ (logical name)	FIR diagnostics list	analysis/analysis-api-fir/gen/.../KaFirDiagnostics*
compiler/arguments/.../	argument descriptions	compiler/arguments/resources/kotlin-compiler-arguments.json, compiler/build-tools/.../*ArgumentsImpl.kt
generators/test-generator/	testData/ directories	tests-gen/.../*Generated.java

Run generators via Gradle tasks named generate* (e.g., generateTests, generateFirCheckers). When in doubt, search Gradle for register("generate".

Dependency verification

Gradle dependency verification is enabled. The hash file at gradle/verification-metadata.xml contains md5/sha256 hashes for every artifact resolved by the build. To regenerate after dependency changes:

./scripts/update-verification-metadata.sh

This script clears the <components> section and re-runs Gradle's --write-verification-metadata sha256 for the resolveDependencies task with -Pkotlin.native.enabled=true. If your dependency includes platform-specific artifacts (darwin, linux, windows, osx, mac), also update implicitDependencies in the corresponding build script.

API dumps and ABI validation

Public surfaces commit dumps that CI verifies against:

• KGP .api dumps — per-target files under libraries/tools/kotlin-gradle-plugin/api/.
• Build Tools API .api dumps — compiler/build-tools/kotlin-build-tools-api/api/.
• klib ABI dumps — produced and verified by libraries/tools/abi-validation/ and compiler/util-klib-abi/. Stdlib changes that affect klibs require updated dumps.

The kotlinx.binary-compatibility-validator project under libraries/tools/binary-compatibility-validator/ provides the underlying tooling.

The Maven-based build

Some libraries (mainly the Maven plugin family) build with Maven, not Gradle. The wrapper is libraries/mvnw, the parent POM is libraries/pom.xml, and the per-library POMs live under libraries/kotlin-maven-*/. The Gradle build can call Maven for these.

CI

Public CI runs on TeamCity at https://teamcity.jetbrains.com/project.html?projectId=Kotlin. Build configurations:

• Compiler — full compiler test matrix.
• Libraries — stdlib, reflect, kotlin-test, kotlinx-metadata across JVM/JS/Native/Wasm.
• Gradle Plugin — KGP unit + integration tests.
• Native — Kotlin/Native build and tests on multiple host OSes.

The configurations are stored in .teamcity/ (Kotlin DSL — see intellij.yaml for the IDE config used). External GitHub PRs trigger a status check pipeline.

IDE settings

The repository ships IDEA project files under .idea/. Code style, run configurations, inspections, and copyright notices are version-controlled. Don't replace them on import — the inspections in particular catch project-specific rules. The Native subtree has its own .idea/ under kotlin-native/.

Editorconfig

Two .editorconfig files:

• Root .editorconfig — minimal, covers Kotlin/Java sources.
• kotlin-native/.editorconfig — much larger; covers C/C++ and Kotlin in the Native subtree.

Combined with kotlin-native/.clang-format, these enforce style across the multiple languages in the repo.

License headers

License headers are checked by a Gradle test task. The header text is in license/COPYRIGHT.txt. New .kt and .java files should start with the standard Apache 2.0 header.

CODEOWNERS

.space/CODEOWNERS (Space syntax — see comments in the file) maps directories to teams and individuals. The format is checked at build time by org.jetbrains.kotlin.code.SpaceCodeOwnersTest. Don't edit without understanding the directives (SPACE_OWNER, USER_OWNER, SPACE_TO_GITHUB_OWNER, etc.).

Local IDE/AI configuration

Two Kotlin-conscious AI assistants leave hooks in this repository:

• AGENTS.md (root and per-area) — guidance for code-generating agents (used by various AI tools).
• CLAUDE.md (root and per-area) — project guidelines for Claude. Mostly point at AGENTS.md.
• .ai/guidelines.md — the canonical agent guideline file referenced from both.
• .junie/ — JetBrains' Junie agent configuration.
• .claude/local.md — user-local Claude preferences (gitignored).