Compiler

Active contributors: Dmitriy Novozhilov, Kirill Rakhman, Mikhail Glukhikh

The compiler/ directory holds the heart of the project: the lexer/parser, two frontends (K1 and K2/FIR), the backend IR, and code generators for the JVM, JS, and Wasm targets. Native code generation is a co-traveler in kotlin-native/ and native/. This page is the index of the compiler subtree; each major piece has its own page.

The compiler/AGENTS.md file gives a one-screen orientation; this wiki expands on it.

What lives where

graph TD
    subgraph Frontend
        PSI["compiler/psi<br/>(Lexer + Parser, KtFile)"]
        K1["compiler/frontend<br/>(K1, legacy)"]
        FIR["compiler/fir<br/>(K2, default)"]
    end
    subgraph IRLayer["IR layer"]
        Psi2Ir["compiler/ir/ir.psi2ir"]
        Fir2Ir["compiler/fir/fir2ir"]
        IR["compiler/ir/ir.tree<br/>(backend IR)"]
        Lower["compiler/ir/backend.common<br/>(shared lowerings)"]
    end
    subgraph Backends
        JVM["compiler/ir/backend.jvm<br/>(JVM)"]
        JS["compiler/ir/backend.js + js/<br/>(JS)"]
        Wasm["compiler/ir/backend.wasm + wasm/<br/>(Wasm)"]
        Native["kotlin-native/backend.native + native/<br/>(Native)"]
    end
    subgraph Drivers
        CLI["compiler/cli<br/>(kotlinc, kotlinc-jvm, ...)"]
        BTAPI["compiler/build-tools<br/>(Build Tools API)"]
        Daemon["compiler/daemon<br/>(compile daemon)"]
    end

    PSI --> K1
    PSI --> FIR
    K1 --> Psi2Ir
    FIR --> Fir2Ir
    Psi2Ir --> IR
    Fir2Ir --> IR
    IR --> Lower
    Lower --> JVM
    Lower --> JS
    Lower --> Wasm
    Lower --> Native

    CLI --> PSI
    BTAPI --> CLI
    Daemon --> CLI

Pages in this section

• Frontend (K2 / FIR) — the modern frontend in compiler/fir/
• Frontend (K1) — the legacy frontend in compiler/frontend/
• PSI and parser — compiler/psi/
• Backend IR — compiler/ir/ir.tree/ and shared lowering
• JVM backend — compiler/ir/backend.jvm/
• JS backend — compiler/ir/backend.js/ plus js/
• Wasm backend — compiler/ir/backend.wasm/ plus wasm/
• Native backend — kotlin-native/ and native/
• CLI — compiler/cli/ and compiler/arguments/
• Build Tools API — compiler/build-tools/
• Daemon — compiler/daemon/ and compiler/incremental-compilation-impl/

Key shared modules

Module	Role
compiler/util/, compiler/util-io/	Cross-cutting utilities.
compiler/util-klib*/	klib (Kotlin Library) format. Read/write/abi/metadata.
compiler/config/, compiler/config.jvm/	CompilerConfiguration — the central key-value bag of compiler options.
compiler/container/	Lightweight DI used inside the frontend.
compiler/serialization/	Kotlin metadata serialization.
compiler/light-classes/	Java PSI view of Kotlin declarations (used by Java-aware tooling).
compiler/multiplatform-parsing/	Parsing support for expect/actual.
compiler/plugin-api/	The compiler plugin extension points.
compiler/preloader/	Class-loading preloader for kotlinc.
compiler/javac-wrapper/	Wrapper around javac for mixed-source builds.
compiler/test-infrastructure*/, compiler/tests-common*/	The test framework all areas use.
compiler/arguments/	The single source of truth for compiler argument names, types, and defaults. Generates JSON and Kotlin model classes consumed by KGP, Maven, and BTAPI.

How a single file compiles

Roughly: a .kt file is parsed into a KtFile (PSI) by compiler/psi. K2 builds raw FIR via compiler/fir/raw-fir, then runs the resolution pipeline in compiler/fir/resolve through phases ending in body resolution. Checkers in compiler/fir/checkers produce diagnostics. compiler/fir/fir2ir converts the resolved FIR into backend IR (compiler/ir/ir.tree). The IR then runs through shared lowerings (compiler/ir/backend.common) and backend-specific lowerings, before the chosen backend (backend.jvm, backend.js, backend.wasm, or backend.native) emits target output. The K1 path replaces the FIR steps with compiler/frontend + compiler/resolution + compiler/ir/ir.psi2ir, but the backend IR onward is the same.

Generated outputs

The compiler subtree leans heavily on code generation. Generated classes live in gen/ siblings of src/. Key generators:

• compiler/fir/checkers/checkers-component-generator/ — FIR diagnostics
• compiler/ir/ir.tree/tree-generator/ — IR tree definitions
• compiler/arguments/ — compiler argument descriptions → JSON + impl classes
• generators/test-generator/ — *Generated.java test runners

Editing the generator and re-running it (via Gradle generate* tasks) is the right path; never edit gen/ files directly.