# 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, …). | Attribute | Value | |-----------|-------| | Language / build | Kotlin + Java, built with Gradle (composite build) | | Repository shape | Monorepo, single `master` branch | | Default language version | `2.4` | | Supported JVM bytecode targets | `1.8` and `9`–`26` (default `1.8`) | | Compilation backends | JVM, JS, Native (LLVM), Wasm, Metadata | | License | Apache License 2.0 | | Issue tracking | YouTrack, `KT` project | | Auxiliary build | Some library artifacts (Maven plugin) built separately with Maven | > [!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/`: | Module | Responsibility | |--------|----------------| | `raw-fir` | Build the initial FIR tree from parsed source (PSI or LightTree) | | `tree` | The FIR node definitions (generated by a tree generator) | | `resolve` | Name resolution, type inference, call resolution | | `checkers` | Diagnostic checkers that produce warnings and errors | | `providers` | Symbol providers that supply declarations from dependencies | | `cones` | The cone type system (FIR's representation of Kotlin types) | | `semantics`, `diagnostic-renderers` | Semantic analysis and human-readable diagnostic text | | `fir2ir` | Translate resolved FIR into the common IR | | `fir-jvm`, `fir-js`, `fir-native`, `fir-serialization`, `fir-deserialization` | Platform-specific frontend behavior and metadata | > [!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/`): | Module | Responsibility | |--------|----------------| | `ir.tree` | The IR node hierarchy (generated by `ir.tree/tree-generator`) | | `ir.psi2ir` | The legacy K1 path from PSI to IR | | `ir.inline` | Function inlining, including the experimental first-stage KLIB IR inliner | | `ir.interpreter` | Compile-time constant evaluation | | `ir.validation` | IR verification (gated by `-Xverify-ir={none\|warning\|error}`) | | `ir.actualization` | Resolve `expect`/`actual` across multiplatform fragments | | `serialization.*` | Serialize IR into KLIBs (common, JS, Native, JVM, jklib) | 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=` dumps the IR after a named phase for inspection. These are debugging aids, not production flags. ### 2.3 The backends | Backend | Module | Output | |---------|--------|--------| | JVM | `compiler/ir/backend.jvm`, `compiler/backend.common.jvm` | `.class` files / JAR (`.kotlin_module` metadata) | | JS | `compiler/ir/backend.js` | JavaScript (`plain`/`commonjs`/`umd`/`amd`/`es` modules), optional `.d.ts` and source maps | | Native | `compiler/ir/backend.native` + `kotlin-native/` | LLVM bitcode → native executable/library/Apple framework | | Wasm | `compiler/ir/backend.wasm` | WebAssembly (`wasm-js`, `wasm-wasi`), optional `.wat`/DWARF | > [!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: | Component | Purpose | |-----------|---------| | `konan` | The Native compiler driver (`konanc`) and its configuration | | `backend.native` | IR → LLVM bitcode lowering | | `libllvmext`, `libclangInterop`, `libclangext` | Native C/C++ extensions bridging LLVM and Clang for C interop | | `Interop` | C and Objective-C interop tooling | | `endorsedLibraries` | Bundled libraries (for example `kotlinx.cli`) shipped with the Native dist | | `runtime`, `common` | The Native runtime, garbage collector, and memory model | 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=` 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. | Level | File | |-------|------| | Common tool | `CommonToolArguments.kt` (`-help`, `-version`, `-verbose`, `-nowarn`, `-Werror`, `-Wextra`) | | Common compiler | `CommonCompilerArguments.kt` (`-language-version`, `-api-version`, `-opt-in`, plugins, phases, language-feature flags) | | JVM | `JvmCompilerArguments.kt` (`-d`, `-classpath`, `-jvm-target`, `-jvm-default`, JSR-305/JSpecify, codegen schemes) | | JS | `JsCompilerArguments.kt` (`-target`, `-module-kind`, IR/ES options) | | Native | `NativeCompilerArguments.kt` (`-produce`, `-target`, `-library`, caching, GC, allocator) | | Wasm | `WasmCompilerArguments.kt` (`-Xwasm*`) | | Metadata | `MetadataCompilerArguments.kt` (`.kotlin_metadata` generation) | | KLIB-shared | `CommonKlibBasedCompilerArguments.kt`, `CommonJsAndWasmArguments.kt` | | Removed | `description/removed/*.kt` (negative knowledge — flags that no longer exist) | > [!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. | Module | Responsibility | |--------|----------------| | `analysis-api` | The public API surface (symbols, types, scopes, resolution) | | `analysis-api-fir` | The FIR-backed implementation (K2) | | `analysis-api-fe10` | The legacy K1 (FE 1.0) implementation | | `analysis-api-impl-base` | Shared implementation base | | `analysis-api-platform-interface` | The platform contract an IDE must implement | | `analysis-api-standalone` | A standalone session builder for using the API without an IDE | | `low-level-api-fir` | Lazy, on-demand FIR resolution that powers responsive IDE features | | `symbol-light-classes` | Present Kotlin declarations as Java light classes for Java tooling | | `decompiled`, `stubs`, `kt-references` | Decompilation, indexing stubs, and reference resolution | > [!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`: | Concern | Flag | |---------|------| | Partial linkage (tolerate ABI drift) | `-Xpartial-linkage={enable\|disable}`, `-Xpartial-linkage-loglevel` | | ABI version pinning | `-Xklib-abi-version=` | | Duplicate `unique_name` strategy | `-Xklib-duplicated-unique-name-strategy={deny\|allow-all-with-warning\|allow-first-with-warning}` | | Signature uniqueness checks | `-Xklib-enable-signature-clash-checks` | | Path normalization | `-Xklib-normalize-absolute-path`, `-Xklib-relative-path-base` | | First-stage IR inlining | `-Xklib-ir-inliner` | > [!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 `KSerializer`s 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=` and configured with `-P plugin::=`; 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: | Source set | Target | |------------|--------| | `common`, `common-non-jvm`, `common-js-wasmjs` | Shared declarations | | `jvm`, `jdk7`, `jdk8` | Kotlin/JVM, with JDK-version add-ons | | `js` | Kotlin/JS | | `native-wasm`, `wasm` | Kotlin/Native and Kotlin/Wasm | | `unsigned` | Unsigned integer types | | `samples`, `test` | API samples and the stdlib test suite | 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 ` (Unix/macOS) or `gradlew ` (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 | Task | Purpose | |------|---------| | `clean` | Clean build results | | `dist` | Assemble the compiler distribution into `dist/kotlinc/` | | `install` | Build and install public artifacts into the local Maven repository | | `coreLibsTest` | Build and run stdlib, reflect, and kotlin-test tests | | `gradlePluginTest` | Build and run Kotlin Gradle plugin tests | | `compilerTest` | Build and run all compiler tests | - 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 | Topic | Location | |-------|----------| | FIR basics & plugins | `docs/fir/fir-basics.md`, `docs/fir/fir-plugins.md` | | Inference / PCLA | `docs/fir/inference.md`, `docs/fir/pcla.md` | | Compiler structure | `docs/compiler/structure.md` | | KLIBs | `docs/klibs/` | | Native (build/hacking) | `kotlin-native/{README,HACKING,BUILDING_LLVM}.md` | | Swift export | `docs/swift-export/` | | Inlining | `docs/inlining/` | | Language specification | `spec-docs/` | --- ## 12. Quick Reference ### 12.1 Subsystem-to-directory map | Subsystem | Primary directories | |-----------|---------------------| | Frontend (K2/FIR) | `compiler/fir/*`, `core/*` | | Frontend (legacy K1) | `compiler/frontend*`, `compiler/resolution*`, `core/descriptors*` | | IR & lowerings | `compiler/ir/*` | | JVM backend | `compiler/ir/backend.jvm`, `compiler/backend.common.jvm` | | JS backend | `compiler/ir/backend.js`, `js/` | | Native backend | `compiler/ir/backend.native`, `kotlin-native/`, `native/` | | Wasm backend | `compiler/ir/backend.wasm`, `wasm/` | | CLI & launchers | `compiler/cli`, `compiler/cli/cli-runner` | | Arguments model | `compiler/arguments` | | Compile daemon | `compiler/daemon` | | Incremental compilation | `compiler/incremental-compilation-impl` | | KLIB format | `compiler/util-klib*`, `compiler/ir/serialization.*` | | Analysis API | `analysis/*` | | Standard library | `libraries/stdlib`, `libraries/reflect`, `libraries/kotlin.test` | | Build-tool plugins | `libraries/tools` | | Compiler plugins | `plugins/*` | | JPS integration | `jps/` | | Code generators | `generators/`, per-module `*-generator` | ### 12.2 Key build commands | Command | Purpose | |---------|---------| | `./gradlew dist` | Assemble `dist/kotlinc/` | | `./gradlew install` | Publish to local Maven | | `./gradlew compilerTest` | Run compiler tests | | `./gradlew coreLibsTest` | Run stdlib/reflect/kotlin-test tests | | `./gradlew gradlePluginTest` | Run Kotlin Gradle plugin tests | | `./gradlew --write-verification-metadata sha256 -Pkotlin.native.enabled=true resolveDependencies` | Regenerate dependency verification | ### 12.3 Diagnostic compiler flags | Flag | Purpose | |------|---------| | `-Xverify-ir={none\|warning\|error}` | Verify IR integrity | | `-Xlist-phases` | List backend phases | | `-Xphases-to-dump-after=` | Dump IR after a phase | | `-Xphases-to-validate=` | Validate IR around a phase | | `-Xprofile-phases`, `-Xreport-perf`, `-Xdetailed-perf` | Performance instrumentation | | `-Xdump-perf=` | Write perf stats (text/JSON/markdown by extension) | | `-Xrender-internal-diagnostic-names` | Show internal diagnostic identifiers | | `-Xprint-configuration` | Print the resolved compiler configuration | --- _Generated June 2026 from JetBrains/kotlin at 2a37504. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._