Getting started

This page covers cloning the repository, building the compiler, running tests, and producing a usable kotlinc. The information here is condensed from ReadMe.md, docs/contributing.md, and .ai/guidelines.md in the repository root.

Prerequisites

• A JDK. The build uses Gradle toolchains (docs.gradle.org/current/userguide/toolchains.html) and will auto-provision the required JDKs from Eclipse Adoptium. JDK versions are also configurable via environment variables — see gradle.properties for the supported names. To force only environment-variable JDKs, pass -Porg.gradle.java.installations.auto-detect=false.
• Git, with core.longpaths=true on Windows.
• A reasonably fast network connection — first-time Gradle configuration downloads intellij-core and idea-full (large), and verifies dependency hashes against gradle/verification-metadata.xml.
• For Kotlin/Native development, additional tools are documented in kotlin-native/README.md and kotlin-native/HACKING.md (notably LLVM and a host C/C++ toolchain).

Cloning

git clone https://github.com/JetBrains/kotlin.git
cd kotlin
git config core.longpaths true   # Windows only

Building the compiler

The project uses Gradle. The wrapper script lives at the repo root:

# macOS / Linux
./gradlew <tasks-and-options>

# Windows
gradlew <tasks-and-options>

Key tasks (from ReadMe.md):

Task	Purpose
clean	Clean build outputs
dist	Assemble the compiler distribution into dist/kotlinc/
install	Build and install all public artifacts into the local Maven repository
coreLibsTest	Build and run stdlib, reflect, and kotlin-test tests
gradlePluginTest	Run the Kotlin Gradle Plugin tests
compilerTest	Build and run all compiler tests
generateTests	Regenerate JUnit runner classes from testData/ directories

Use -Pteamcity=true to reproduce TeamCity-style builds (proguard + jar compression). Local builds skip both for speed.

If first-run downloads time out, increase the timeout:

./gradlew -Dhttp.socketTimeout=60000 -Dhttp.connectionTimeout=60000

Running the compiler

After ./gradlew dist, a working compiler distribution is in dist/kotlinc/. The CLI entry point is the kotlinc script:

./dist/kotlinc/bin/kotlinc Hello.kt -include-runtime -d Hello.jar
java -jar Hello.jar

The CLI implementation lives in compiler/cli/. Subcommands and modes (compile-jvm, compile-js, compile-native, daemon) are dispatched from compiler/cli/cli-base/ and compiler/cli/cli-common/.

Running tests

For a generic compiler test:

./gradlew :compiler:test --tests "org.jetbrains.kotlin.codegen.BlackBoxCodegenTestGenerated" -q

For a single method:

./gradlew :compiler:test --tests "org.jetbrains.kotlin.codegen.BlackBoxCodegenTestGenerated.testSomeTest"

For FIR-specific compiler tests:

./gradlew :compiler:fir:fir2ir:test --tests "org.jetbrains.kotlin.test.runners.ir.FirLightTreeJvmIrTextTestGenerated"

To regenerate snapshot test data after changing diagnostics:

./gradlew :compiler:test --tests "TestClassName" -Pkotlin.test.update.test.data=true --continue

After adding a new testData/*.kt file, regenerate the JUnit runners:

./gradlew generateTests

Some areas (Analysis API, Build Tools API, KGP integration tests) have specialized tooling — see the per-area AGENTS.md files (e.g., analysis/AGENTS.md, compiler/build-tools/AGENTS.md, libraries/tools/kotlin-gradle-plugin-integration-tests/AGENTS.md).

Working in IntelliJ IDEA

The recommended way to edit the project is the latest IntelliJ IDEA (Community or Ultimate). Open the project root and let IDEA import the Gradle project.

For compiler-test data editing, the test-data-helper-plugin is recommended.

Dependency verification

Gradle dependency verification is enabled. The hash file is gradle/verification-metadata.xml. To regenerate it after changing dependencies:

./scripts/update-verification-metadata.sh

The script clears the <components> section and re-runs Gradle's --write-verification-metadata sha256 for the resolveDependencies task with -Pkotlin.native.enabled=true. If you add a platform-specific dependency, also update the implicitDependencies configuration (see ReadMe.md).

Building Kotlin/Native

Kotlin/Native has its own build instructions in kotlin-native/README.md and kotlin-native/HACKING.md. It depends on a vendored LLVM and additional native toolchains. The bulk of the source lives under kotlin-native/ (LLVM-based backend, runtime in C/C++) and native/ (frontend, commonizer, Swift export, tests).

Maven-based libraries

Some artifacts (mainly the Maven plugin family) are built with Maven instead of Gradle. See libraries/ReadMe.md and libraries/pom.xml for that path. The Maven wrapper is libraries/mvnw.

Bootstrap and -dev versions

The project compiles itself with a previously released Kotlin compiler (the bootstrap). -dev snapshots are published frequently and listed at:

https://redirector.kotlinlang.org/maven/bootstrap/org/jetbrains/kotlin/kotlin-compiler/maven-metadata.xml

Add this Maven repository when consuming -dev builds:

maven("https://redirector.kotlinlang.org/maven/bootstrap")