# Kotlin Multiplatform Introduces More Reliable Separate Compilation

New experimental feature aligns compiler behavior with IDE analysis for predictable multiplatform development.

- **Source:** [The JetBrains Blog](https://brifing.si/source/782eebd1-7be8-49cc-b27c-e552516691b2)
- **Published:** 2026-09-28
- **Topic:** [Software & Engineering](https://brifing.si/c/engineering)
- **Original article:** <https://blog.jetbrains.com/kotlin/2026/09/a-more-reliable-compilation-scheme-for-kotlin-multiplatform-modules/>
- **On Brifing:** https://brifing.si/s/158944dc-a7b6-4865-a910-daf09bd3f6b8

## Current compilation inconsistencies

The existing Kotlin Multiplatform compilation scheme creates discrepancies between IDE analysis and actual compilation. While the IDE strictly follows metadata KLIB declarations, the compiler may resolve common code against platform artifacts. This leads to situations where code that shows as errors in the IDE compiles successfully, or where type inference differs between analysis and runtime. These inconsistencies particularly affect commonTest source sets and overload resolution.

## The separate compilation solution

Kotlin 2.5.0-Beta1 introduces an experimental separate compilation mode that enforces stricter resolution rules. When enabled via kotlin.kmp.separateCompilation=true in gradle.properties, the compiler will only resolve common code calls against metadata KLIB declarations, matching the IDE's behavior. This eliminates surprises where platform-specific code gets called from common sources and ensures consistent overload resolution and type inference across all platforms.

## Impact on commonTest behavior

Separate compilation significantly changes how commonTest interacts with platform code. Previously, test code could implicitly call platform-specific declarations from jvmMain or other platform sources. The new approach requires explicit expect/actual declarations for any platform functionality needed in tests. This makes test dependencies more transparent but may require adjustments to existing test suites that relied on implicit platform access.

## Overload resolution alignment

The new compilation scheme fixes a subtle bug where the IDE and compiler disagreed on overload selection. When multiple overloads exist in both common and platform code, the IDE would always select the common declaration while the compiler might choose a platform-specific version. Separate compilation ensures both tools consistently use the common declaration, preventing runtime behavior that contradicts IDE analysis.

## Type inference improvements

Separate compilation resolves a tricky type inference issue involving actual classes with additional supertypes. Previously, platform-specific superinterfaces could cause the compiler to infer Any instead of the expected common type. The new approach maintains proper type information through compilation phases, ensuring consistent behavior between common code analysis and platform-specific compilation.

## Implementation mechanism

The solution works by changing how common source sets are compiled against dependencies. Instead of compiling against platform artifacts, common code now strictly uses metadata KLIB declarations. This architectural change also enables future improvements like incremental compilation for common source sets. The compiler first resolves common code independently before proceeding with platform-specific compilation.

## Adoption requirements

For separate compilation to work effectively, multiplatform library authors must publish metadata KLIBs. While this is already the default behavior for KMP Gradle publishing tasks, some older libraries might need updates. The feature currently has known limitations with C interoperability and single-target modules. Developers should test thoroughly when enabling the flag and report any issues through Kotlin's YouTrack.

## Long-term benefits

Beyond fixing immediate inconsistencies, separate compilation establishes a more maintainable foundation for Kotlin Multiplatform. The stricter resolution rules encourage better architecture by making dependencies explicit. Future enhancements can build on this to improve compilation performance and enable more sophisticated cross-platform code analysis tools. This represents a significant step toward production-grade multiplatform development.

## Sources covering this story

- https://blog.jetbrains.com/kotlin/2026/09/a-more-reliable-compilation-scheme-for-kotlin-multiplatform-modules/ — 

---

_Summary written by Brifing from the original reporting. Copyright in the original article belongs to its publisher; read the full piece at the link above._