Kotlin Multiplatform Introduces More Reliable Separate Compilation
New experimental feature aligns compiler behavior with IDE analysis for predictable multiplatform development.
1Current 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.
2The 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.
3Impact 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.
4Overload 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.
5Type 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.
6Implementation 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.
7Adoption 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.
8Long-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.