Kotlin — Administrator & Architecture Guide

This guide is for engineers who build the Kotlin compiler from source, integrate against its internals, write compiler plugins, or need to understand how the toolchain is structured. It covers the repository layout, the compilation pipeline (K2/FIR frontend through the IR backends), the public-facing subsystems (CLI, build tooling, Analysis API, KLIB format), the build system, security posture, and contributor operations.

Note

Scope and version: this guide describes JetBrains/kotlin on the development branch for Kotlin 2.4.0 (commit 2a37504b2, 2026-06-03). The repository is a Gradle monorepo of ~104,500 files and ~69 MB of source across Kotlin and Java, organized into the compiler, standard library, Native toolchain, build-tool plugins, and IDE-facing analysis layers. Because Kotlin is the canonical implementation of the language, this document is grounded directly in the repository's own source — chiefly the declarative compiler-arguments model, the compiler module tree, and the build scripts.

1. Executive Summary

Kotlin is a statically typed, multiplatform programming language. This repository contains the entire toolchain, not a single artifact:

• The compiler — a frontend (the K2/FIR analyzer) and four backends (JVM, JS, Native, Wasm) connected by a shared intermediate representation (IR).
• The standard library (kotlin-stdlib) and companion libraries (kotlin-reflect, kotlin.test, scripting, metadata).
• The Kotlin/Native toolchain, which lowers IR to LLVM and links native binaries and Apple frameworks.
• Build-tool integrations — the Kotlin Gradle plugin and Kotlin Maven plugin.
• The Analysis API, the stable surface that powers IntelliJ IDEA's Kotlin support and standalone code analysis.
• 18 bundled compiler plugins (serialization, kapt, allopen, compose, parcelize, …).

Important

The single most authoritative non-fabricatable artifact in this repository is the declarative compiler-arguments model under compiler/arguments/src/org/jetbrains/kotlin/arguments/description/. Every kotlinc flag is declared there with its name, value type, description, and a lifecycle (introduced/stabilized/deprecated/removed version). Treat these files as the source of truth for the CLI surface; do not infer flags from anywhere else.

2. Architecture: The Compilation Pipeline

Kotlin compilation flows through a frontend, a shared IR, and a platform backend:

            ┌─────────────────────────────────────────────────────────┐
            │                     Kotlin source (.kt/.kts)              │
            └───────────────────────────┬─────────────────────────────┘
                                         ▼
                         ┌───────────────────────────────┐
   FRONTEND (K2 / FIR)   │  Parsing → raw FIR → resolve  │  compiler/fir/*
                         │  → checkers (diagnostics)     │  core/* (descriptors,
                         └───────────────┬───────────────┘  names, metadata)
                                         ▼
                         ┌───────────────────────────────┐
   FIR → IR              │   fir2ir: build common IR     │  compiler/fir/fir2ir
                         └───────────────┬───────────────┘
                                         ▼
                         ┌───────────────────────────────┐
   IR + lowerings        │  ir.tree, ir.inline,          │  compiler/ir/*
   (phased)              │  ir.interpreter, validation   │
                         └───────────────┬───────────────┘
                  ┌──────────────┬───────┴───────┬───────────────┐
                  ▼              ▼               ▼               ▼
            ┌──────────┐  ┌───────────┐  ┌────────────┐  ┌────────────┐
   BACKENDS │ JVM      │  │ JS (IR)   │  │ Native     │  │ Wasm       │
            │ bytecode │  │ JavaScript│  │ LLVM → bin │  │ WebAssembly│
            └──────────┘  └───────────┘  └────────────┘  └────────────┘
   backend.jvm        backend.js      backend.native    backend.wasm

2.1 The frontend: K2 / FIR

The modern frontend is FIR (Frontend Intermediate Representation), introduced as the default with the K2 compiler. It lives under compiler/fir/:

Note

The legacy K1 frontend (descriptor/PSI-based) still exists under compiler/frontend*, compiler/resolution*, and core/descriptors* for compatibility and for tooling that has not yet migrated. New work targets FIR. The -Xuse-fir-* advanced flags (-Xuse-fir-ic, -Xuse-fir-lt) toggle FIR-specific behaviors; -Xuse-fir-experimental-checkers is deprecated.

2.2 The intermediate representation and lowerings

After fir2ir, compilation operates on a common IR (compiler/ir/):

The backend runs as a sequence of phases. Phase machinery is observable and controllable through common advanced flags: -Xlist-phases, -Xdisable-phases, -Xphases-to-dump[-before|-after], -Xphases-to-validate, and -Xprofile-phases.

Tip

When diagnosing a backend miscompilation, -Xverify-ir=error plus -Xphases-to-validate will surface the first phase that produces invalid IR. -Xphases-to-dump-after=<phase> dumps the IR after a named phase for inspection. These are debugging aids, not production flags.

2.3 The backends

Note

JVM codegen schemes are tunable: -Xstring-concat, -Xlambdas, -Xsam-conversions, and -Xwhen-expressions choose between invokedynamic-based and class-based generation. The indy schemes require higher -jvm-target levels (9+ for string concat/lambdas, 21+ for when type switches).

2.4 Kotlin/Native internals

kotlin-native/ contains the LLVM-based native toolchain:

The sibling native/ directory holds higher-level Native tooling: commonizer (unifies platform-dependent declarations across Apple/Linux targets), swift / objcexport-header-generator (Swift export and Objective-C header generation), and executors.

Note

Native runtime behavior is configured through advanced flags: -Xgc selects the garbage collector (noop, stms, cms), -Xallocator selects the allocator (std, mimalloc, custom), and -Xbinary=<option=value> sets binary options. Native caching (-Xauto-cache-from, -Xic-cache-dir, -Xcache-directory) is what makes incremental Native builds tolerable; the Gradle plugin manages it.

3. Repository Structure

kotlin/
├── compiler/          The compiler: frontend, IR, backends, CLI, daemon, args
│   ├── arguments/         Declarative compiler-arguments model (CLI source of truth)
│   ├── fir/               K2 frontend (raw-fir, resolve, checkers, fir2ir, ...)
│   ├── frontend*/         Legacy K1 frontend (PSI/descriptor based)
│   ├── ir/                Common IR + JVM/JS/Native/Wasm backends + serialization
│   ├── cli/               kotlinc / kotlinc-js / kotlin launchers and pipeline
│   ├── daemon/            Compile daemon for warm, incremental builds
│   ├── backend.common.jvm Shared JVM backend support
│   ├── resolution*/       Call/overload resolution (K1)
│   ├── serialization/     Metadata serialization
│   ├── util-klib*/        KLIB reading/writing, ABI, metadata
│   └── tests*/            Compiler test suites
├── core/              Descriptors, deserialization, metadata, names, reflection
├── analysis/          The Analysis API (IDE-facing, stable surface)
├── libraries/         stdlib, reflect, kotlin.test, scripting, metadata, tools
│   ├── stdlib/            Multiplatform standard library (jvm/js/native-wasm/...)
│   ├── reflect/           kotlin-reflect (JVM)
│   ├── kotlin.test/       Multiplatform test assertions
│   └── tools/             Kotlin Gradle plugin, Maven plugin, abi-validation, ...
├── kotlin-native/     LLVM-based Native compiler (konan), runtime, C interop
├── native/            Commonizer, Swift export, Obj-C header gen, executors
├── plugins/           18 bundled compiler plugins
├── js/                Kotlin/JS support code
├── wasm/              Kotlin/Wasm support code
├── jps/               IntelliJ JPS (build-server) integration
├── generators/        Code generators (FIR tree, IR tree, checkers, args, ...)
├── compiler/config*/  Compiler configuration keys
├── docs/              Architecture docs (FIR, backend, klibs, native, ...)
├── spec-docs/         Language specification documents
├── gradle/            Build logic, version catalogs, dependency verification
└── gradle.properties  Versions, language version, bootstrap config

Important

Much of the file count is test data, not product code. The repository reports thousands of "high-priority" folders, but the vast majority are tiny per-test-case directories under compiler/testData/, */testData/, and integration-test fixtures (each a small Kotlin program used as a compiler input). When mapping the codebase, treat the testData and tests* trees as a corpus, not as subsystems to document folder by folder. The genuine product surface is the compiler/{fir,ir,cli,arguments}, core/, libraries/stdlib, kotlin-native/konan, and analysis/ trees.

3.1 Code generation

Several parts of the compiler are generated from declarative descriptions (under generators/ and per-module tree-generator/*-generator directories):

• The FIR tree (compiler/fir/tree/tree-generator)
• The IR tree (compiler/ir/ir.tree/tree-generator)
• FIR checker components (compiler/fir/checkers/checkers-component-generator)
• CLI argument classes (compiler/cli/cli-arguments-generator, derived from compiler/arguments)
• Configuration keys (compiler/config/configuration-keys-generator)
• The Build Tools API arguments (compiler/build-tools/kotlin-build-tools-generator)

Note

Because these are generated, never edit the generated output (often under gen/ directories) directly — edit the generator input and re-run the generator. For arguments specifically, the human-authored source is compiler/arguments/src/.../description/*.kt; the generated CLI classes live under compiler/cli/cli-base/gen/.../arguments/.

4. The Compiler-Arguments Model

The arguments model is both the CLI's source of truth and a useful integration point. Each option is declared as a compilerArgument { … } with:

• name (the flag, without the leading -), optional shortName, optional deprecatedName
• description and valueDescription
• valueType (BooleanType, StringType, IntType, array/list types, enum types)
• lifecycle(introducedVersion, stabilizedVersion, deprecatedVersion, removedVersion)
• optional additionalAnnotations(Enables(LanguageFeature.X)) linking a flag to a language feature
• affectsCompilationOutcome — whether the flag changes output (vs. diagnostics/reporting only)

Arguments are organized into levels (CompilerArgumentsLevelNames): common tool arguments → common compiler arguments → per-platform arguments (JVM, JS, Native, Wasm, Metadata) → KLIB-based shared arguments.

Tip

The removed/ subdirectory is the project's own negative-knowledge record: it lists arguments that have been deleted per platform. When validating that a flag exists, check both the active description and the removed/ list — a flag present in old documentation may have been removed.

4.1 The Build Tools API

compiler/build-tools/kotlin-build-tools-api exposes a stable, versioned API for build systems to invoke the compiler without depending on internal classes. Its argument classes (gen/.../arguments/*.kt) mirror the arguments model. Build-tool integrations (Gradle, Maven) target this API so they remain compatible across compiler releases.

5. The Analysis API

analysis/ provides the Analysis API — the stable, public surface for analyzing Kotlin code outside of compilation, used by IntelliJ IDEA and by standalone tools.

Note

The Analysis API is what you integrate against to build linters, code generators, refactoring tools, or documentation tooling over Kotlin. Use analysis-api-standalone to construct a session outside IntelliJ. The bulk of issues in ChangeLog.md under "Analysis API" headings concern this surface — it is actively stabilized and a primary external integration point.

6. The KLIB Format

KLIBs (.klib) are Kotlin's platform-independent library format, carrying serialized IR and metadata for multiplatform and Native/JS compilation. Support is spread across compiler/util-klib*, compiler/ir/serialization.*, and the common KLIB arguments.

Key operational concerns are controlled by CommonKlibBasedCompilerArguments:

Important

Partial linkage lets a binary that depends on a KLIB keep working when the KLIB's ABI changes in compatible ways (the compiler patches over removed/changed declarations with deferred errors). It is central to Kotlin's multiplatform binary-compatibility story. Leave it enabled unless you are deliberately enforcing strict ABI matching.

7. Compiler Plugins (Extension Mechanism)

The 18 plugins under plugins/ extend the compiler through documented extension points (the plugin API lives in compiler/plugin-api and FIR plugin hooks in compiler/fir/plugin-utils). They fall into three categories:

Declaration-generating plugins (synthesize members/classes):

• kotlinx-serialization — generate KSerializers for @Serializable types
• noarg — synthesize no-arg constructors (JPA)
• parcelize — generate Android Parcelable implementations
• js-plain-objects — generate plain JS objects from interfaces
• compose — the Compose compiler plugin (state tracking, recomposition)

Declaration-modifying plugins:

• allopen — make annotated classes open (Spring, mocking)
• sam-with-receiver — treat a SAM's first parameter as a receiver
• lombok — interoperate with Lombok-generated Java members
• assign-plugin — operator-style assignment for Gradle DSL types

Tooling / codegen plugins:

• kapt — run Java annotation processors over Kotlin
• power-assert — rich assertion failure messages
• atomicfu — efficient compilation of kotlinx.atomicfu atomics
• jvm-abi-gen — produce ABI-only JARs for faster incremental builds
• kotlin-dataframe — compile-time DataFrame support
• scripting — the scripting support plugin (enabled by default)

Tip

To write a plugin, register a CompilerPluginRegistrar (and, for K2, the FIR extension registrars under compiler/fir/plugin-utils). Plugins are loaded with -Xplugin=<jar> and configured with -P plugin:<id>:<opt>=<value>; the modern -Xcompiler-plugin flag registers a plugin with inline options and -Xcompiler-plugin-order constrains execution order. Use plugins/plugin-sandbox as a working reference.

8. The Standard Library

libraries/stdlib/ is a multiplatform library compiled for every target from largely shared sources:

The current standard-library version is written into libraries/stdlib/src/kotlin/util/KotlinVersion.kt automatically during the build; at runtime KotlinVersion.CURRENT reports it.

Companion libraries:

• libraries/reflect — kotlin-reflect (full reflection on the JVM)
• libraries/kotlin.test — multiplatform assertions delegating to JUnit/Mocha/etc.
• libraries/kotlinx-metadata — read/write .kotlin_module metadata (kotlin-metadata-jvm)
• libraries/scripting — the scripting host and definitions
• libraries/tools — the Kotlin Gradle plugin, Maven plugin, and abi-validation

Caution

Building the standard library is a special case: it compiles code in the kotlin package and may use API ahead of the language version. The flags -Xstdlib-compilation, -Xallow-kotlin-package, and -Xsuppress-api-version-greater-than-language-version-error exist for this purpose. Application code must never use them.

9. Build System

The project builds with Gradle as a composite build. Key facts from ReadMe.md and gradle.properties:

• Build with ./gradlew <tasks-and-options> (Unix/macOS) or gradlew <tasks-and-options> (Windows).
• JDKs are auto-provisioned via Gradle toolchains from Eclipse Adoptium; you can instead supply JDKs via environment variables and disable auto-detection with -Porg.gradle.java.installations.auto-detect=false.
• First configuration downloads large dependencies (intellij-core, idea-full); raise timeouts on slow links with -Dhttp.socketTimeout=60000 -Dhttp.connectionTimeout=60000.

9.1 Important Gradle tasks

• Use -Pteamcity=true to reproduce the CI build. Local builds skip ProGuard and disable JAR compression by default.
• Kotlin/Native is built separately; see kotlin-native/README.md (#building-from-source).
• Some artifacts (chiefly the Maven plugin) are built with Maven — see libraries/ReadMe.md.

9.2 Dependency verification

Warning

Gradle dependency verification is enabled for all builds. Gradle checks md5/sha256 hashes against gradle/verification-metadata.xml and fails with Dependency verification failed when an artifact is missing or mismatched. Only update verification-metadata.xml in commits that change the build. Regenerate it with ./gradlew --write-verification-metadata sha256 -Pkotlin.native.enabled=true resolveDependencies (or ./scripts/update-verification-metadata.sh), and ensure local.properties does not set kotlin.native.enabled=false, or native-only dependencies will be omitted.

9.3 Bootstrapping

Kotlin is self-hosted: the compiler is built by a previously released bootstrap compiler. gradle.properties records the bootstrap configuration (bootstrap.kotlin.default.version, with options for using a local build via bootstrap.local=true). New language features must keep a corresponding compiler argument available between stabilization and the next bootstrap.

Note

Frequent -dev builds are published. To consume them, add the bootstrap Maven repository https://redirector.kotlinlang.org/maven/bootstrap and select a version from its maven-metadata.xml.

10. Security

Kotlin is a compiler and language toolchain; its security surface differs from a networked application.

• License & provenance — Apache 2.0. Releases are published to Maven Central under org.jetbrains.kotlin. Verify artifact signatures and coordinates when depending on the compiler or stdlib.
• Dependency integrity — the build's dependency-verification feature (Section 9.2) protects the build itself against tampered or substituted dependencies via pinned hashes.
• Vulnerability reporting — handled through the repository's SECURITY.md policy; report privately rather than via public issues.
• Preview & unstable features — -Xjvm-enable-preview marks output as compiled with JDK preview features, which is explicitly not suitable for release environments. -Xskip-prerelease-check and -Xskip-metadata-version-check relax safety checks on dependency metadata and should not be used routinely, as they can let incompatible or pre-release binaries link silently.
• Scripting — Kotlin scripts execute arbitrary code at compile/eval time. Treat .kts/.main.kts files from untrusted sources as you would any executable, and be deliberate about -Xallow-any-scripts-in-source-roots and custom -Xscript-resolver-environment values.
• Test isolation — the repository includes compiler/test-security-manager and a tests-permissions.template.policy, reflecting that compiler tests run untrusted generated code under constrained permissions.

Important

The riskiest operational toggles are the metadata/prerelease skip flags (-Xskip-metadata-version-check, -Xskip-prerelease-check, -Xallow-unstable-dependencies). They suppress exactly the checks that prevent linking against binaries built by an incompatible compiler. Keep them off outside of deliberate bootstrap/experimentation scenarios.

11. Operations & Contributor Workflow

11.1 Building from source

• [ ] Install a recent IntelliJ IDEA (Community or Ultimate).
• [ ] On Windows, enable long paths: git config core.longpaths true.
• [ ] Import the project directory in IntelliJ; let Gradle toolchains provision JDKs.
• [ ] Run ./gradlew dist to assemble a local dist/kotlinc/.
• [ ] Run targeted tests (compilerTest, coreLibsTest, gradlePluginTest) for the area you changed.
• [ ] For Native work, follow kotlin-native/README.md and keep kotlin.native.enabled=true.

Tip

For compiler test work, the community Kotlin Compiler Test Helper IntelliJ plugin streamlines running and regenerating test data. Test-data regeneration conventions are documented in docs/updating_test_data.md.

11.2 The compile daemon

compiler/daemon implements a long-lived compiler process that keeps the JVM warm and caches analysis between invocations. Build tools use it to avoid paying JVM startup and warmup on every compile. Incremental compilation is implemented in compiler/incremental-compilation-impl and toggled with -Xenable-incremental-compilation.

11.3 Governance & contribution

• Contribution guidelines: docs/contributing.md. Project-wide AI/agent guidelines: AGENTS.md → .ai/guidelines.md.
• Code of conduct: CODE_OF_CONDUCT.md. Security policy: SECURITY.md.
• The Kotlin Foundation (kotlinfoundation.org) is the non-profit steward of the language.
• Issues and feature requests are tracked in YouTrack (KT); ChangeLog.md is the per-release record of fixed issues, organized by subsystem (Analysis API, Compiler, IR, Native, JS, Tools, etc.).

11.4 Documentation map

12. Quick Reference

12.1 Subsystem-to-directory map

12.2 Key build commands

12.3 Diagnostic compiler flags