JPS integration

Active contributors: Ilya Chernikov, Alexander Udalov, Yahor Berdnikau

JPS (JetBrains Project System) is the build system that IntelliJ IDEA uses for in-IDE incremental builds when you click "Build Project" or "Run". The jps/ directory at the repo root, together with compiler/incremental-compilation-impl/, is the Kotlin team's contribution to JPS — without it, IDEA would have no way to compile Kotlin code as part of an IDEA-managed project (i.e., one that doesn't fall back to Gradle for builds).

Purpose

Wire Kotlin into JPS so that IDEA-managed projects (the older "iml + library entries" model, plus the Bazel/Pants-style Kotlin-aware ImporterAPI used internally) can compile Kotlin sources alongside Java. Provide accurate incremental compilation: the JPS engine asks "what changed?" and the Kotlin contribution must answer "these files need to recompile, and here's why".

Directory layout

jps/
├── jps-common/                  Shared types between IDE and JPS contexts
├── jps-plugin/                  The actual JPS plugin (Kotlin builder)
├── kotlin-jps-plugin-tests/     Tests
├── kotlin-jps-protocol/         Protocol used between IDE and the JPS process
└── kotlin-jps-test/             Test fixtures

compiler/incremental-compilation-impl/  The incremental compilation engine (shared with daemon)

Key abstractions

Type	Where	Role
KotlinBuilder	jps/jps-plugin/.../KotlinBuilder.kt	The JPS Builder registered for Kotlin sources.
KotlinModuleBuilderTarget	jps/jps-plugin/...	Per-module-per-target build context.
IncrementalCompiler	compiler/incremental-compilation-impl/...	The cross-tool incremental engine.
LookupTracker	compiler/incremental-compilation-impl/...	Records which symbols a file looked up — used to compute dirty sets.
IncrementalJvmCachesManager	compiler/incremental-compilation-impl/...	Persistent caches of compilation state.

How JPS builds a Kotlin module

graph LR
    JPS["JPS engine<br/>(IDEA)"] --> Builder["KotlinBuilder"]
    Builder --> Inc["IncrementalCompiler"]
    Inc --> Caches["Persistent caches<br/>(.kotlin/...)"]
    Inc --> Compiler["Kotlin compiler<br/>(in-process)"]
    Compiler --> Cls["class files"]
    Cls --> JpsCaches["JPS caches"]

JPS calls into Kotlin's KotlinBuilder for any file under a Kotlin source root. The builder consults IncrementalCompiler to figure out which files actually need to compile, runs the embedded Kotlin compiler over those files, and persists caches that record what changed.

Incremental compilation details

The same incremental engine in compiler/incremental-compilation-impl/ is used by:

• The Kotlin Compile Daemon (compiler/daemon/) — the path KGP uses by default.
• This JPS plugin (jps/jps-plugin/).

The engine tracks:

• Symbol → file lookups ("which files mentioned Foo.bar?") — used to compute downstream dirty files when Foo.bar changes.
• ABI snapshots — hashes of declarations so a body-only change doesn't trigger downstream rebuilds.
• Removed declarations — an explicit signal that downstream files need to recompile because something they used is gone.

compiler/incremental-compilation-impl/ is the most intricate piece of build-time bookkeeping in the repo, and it is shared. Bug fixes there improve KGP and JPS simultaneously.

Tests

jps/kotlin-jps-plugin-tests/ runs JPS builds against fixture projects. They mock the JPS engine so they're faster than real IDEA builds.

Integration points

• Consumer: IntelliJ IDEA's JPS engine. The Kotlin plugin in JetBrains/intellij-community registers this builder.
• Talks to: the in-process Kotlin compiler (compiler/cli/).
• Shares: incremental engine with the Compile Daemon.

When you don't see JPS

If your IDEA project uses Gradle for builds (the default for new projects since IDEA 2021), JPS is bypassed entirely and IDEA delegates to Gradle. JPS still applies if you've selected "Build with IDEA" in Settings → Build, Execution, Deployment → Gradle.

Where to start

For incremental-compilation behavior: compiler/incremental-compilation-impl/. For JPS-specific wiring (e.g., a new build-event message): jps/jps-plugin/.

See Daemon for the other big consumer of the incremental engine.