What's Changed

Migrating Processors to Support Backing Fields

This release introduces support for explicit backing fields (#2873), which may now be returned by Resolver.getSymbolsWithAnnotation. To prevent breaking existing processors, new language features require an explicit opt-in.

More generally, the KSP API now explicitly models backing fields for properties. The following is an exhaustive list of functions in KSP API where processor may observe the change after opting in:

• Resolver.getSymbolsWithAnnotation: The function now returns a KSBackingField if the given annotation targeted a field. Previously, if a field were targeted, the function would return a KSProperty.
• Resolver.effectiveJavaModifiers: The function returns fewer modifiers for a KSPropertyDeclaration if it has a backing field, since most of the JVM-specific annotations apply to the backing field. If you are interested in the JVM modifiers, you should call the function with the KSBackingField obtained from the property instead.

Additionally, KSP now models Java fields as properties that always have backing fields. Some of the modifiers now apply to the backing field instead.

Processors adapting to new features must opt in via both of the following steps simultaneously (failing to do both may lead to undefined behavior):

1. The processor should call the registerProcessorForNewFeatures function in SymbolProcessorEnvironment immediately when created (and only once). Example: AbstractTestProcessor.kt#L30
2. All implementations of KSVisitor should move to KSVisitorNext. If their processor code does not directly implement the interface but instead extends one of the KSP-provided visitors (such as KSTopDownVisitor), they should instead extend KSTopDownVisitor(enableNewFeatures = true) and override visitBackingField depending on their code and needs.

Let us know if you run into unexpected behavior!

Bug Fixes

• Fix Resolver.getDeclarationsFromPackage returning incomplete declarations from KLibs in Kotlin Multiplatform (#2396)
• Fix KSP CLI process hanging indefinitely when a processor throws an unhandled exception (#3120)
• Fix implicit task dependency error between KSP and Android Lint in Android KMP (#3128)
• Fix NullPointerException by registering PluginProblemReporter as an application service (#3140)
• Do not mark companion objects as JAVA_STATIC in Resolver.effectiveJavaModifiers (#3125)
• Fix JAVA_STATIC modifier resolution for @JvmStatic members in Resolver.effectiveJavaModifiers (#3124)
• Update minimum supported Android Gradle Plugin (AGP) version to 8.12.0 (#3149)

New Contributors

Thanks to @KlyneChrysler, @budindepunk, and everyone who reported bugs and participated in discussions!

Full Changelog: 2.3.11...2.3.12

What's Changed

• Support org.gradle.isolated-projects for project isolation (#3051)
• Fix premature kspDebugAndroidTest task skipping on Android library modules (#3050)
• Fix missing parent declaration exception for @NotNull annotations during incremental compilation (#3030)
• Clean output directories instead of skipping tasks when processor classpath transitions to empty (#3046)
• Fix build cache misses by marking KspGradleConfig.logLevel as @Internal (#3039)
• Add org.gradle.isolated-projects=true to KSP Gradle properties reference table (#3076)
• Add KSP Gradle properties reference table to README documentation (#3070)
• Document collection values in KSValueArgument.value (#3069)
• Update error messaging for ksp.useKSP2 deprecation notice (#3066)

Contributors

• Thanks to @simonlebras, @ChristianKatzmann, @Yong-yuan-X, @bacecek, @KlyneChrysler, @Shaurya2k06, and everyone who reported bugs and participated in discussions!

Full Changelog: 2.3.10...2.3.11

What's Changed

• Fix OOMs caused by unstopped coroutine Dispatcher threads by moving KSP task cache to a gradle build service (#2817)
• Sanitize ':' in internal-name module suffix so KSP works with Kotlin 2.4.0 default module names (#2964)
• Filter source file trees in KspAATask to restore NO-SOURCE skipping behaviour (#2947)
• Fix R-class resolution in KSP when AGP 9 built-in Kotlin is enabled (#2857)
• Fix KSP2 incremental cache path normalization mismatch (#2854)
• Normalize line endings for KspAATask source roots to prevent cross-platform remote build cache misses (#2849)
• Fix bug where KSP incremental compilation does not consider library class references in annotations (#3011)
• Consume all Kotlin sources in KSP to support other code generators (#3001)
• Fix configuration cache invalidation in klib cross-compilation check (#3014)
• Memoized hash code for KSTypeImpl to speed up processing (#2896)
• Fix incorrect name generation for data classes annotated with @JvmRecord (#2813)
• Include kotlinx.coroutines in the distributed uber jar symbol-processing-aa-embeddable (#2938)
• New debugging features for incremental compilation, including additional logging and dependency graph visualization (#3015)
• Deprecate the ksp(...) Gradle configuration in Kotlin Multiplatform (KMP) projects in favor of target-specific configurations (#2956). Note: Non-KMP projects are also affected. For migration details, see the documentation.

Contributors

• Thanks to @mvanhorn, @Yong-yuan-X, @MariusVolkhart, @shmuelr and everyone who reported bugs and participated in discussions!

Full Changelog: 2.3.9...2.3.10

What's Changed

• Cleaned up native cross-compilation support checks to prevent Gradle Configuration Cache invalidation (#2953)
• Fixed a compilation performance regression in in PsiResolutionStrategy introduced in 2.3.8 (#2948)

Contributors

• Thanks to everyone who reported bugs and participated in discussions!

Full Changelog: 2.3.8...2.3.9

What's Changed

• Enabled new default annotation use-site rules in Kotlin's Analysis API (see KEEP 402) for more information. Note: KSP was already mostly compatible with KEEP 402, so there shouldn't be any visible changes for users. (#2888)
• Enabled ksp.project.isolation by default when Gradle isolated projects are enabled (#2866)
• Improved getSymbolsWithAnnotation performance by implementing a new PSI-based resolution strategy (#2816)

Contributors

• Thanks to @hugoncosta and everyone who reported bugs and participated in discussions!

Full Changelog: 2.3.7...2.3.8

What's Changed

• Bumped Kotlin target language version to 2.3 (#2821)
• Fixed crash caused by upstream dependency (#2856)
• Fixed support for Gradle Isolated Projects (#2844)

Contributors

• Thanks to everyone who reported bugs and participated in discussions!

Full Changelog: 2.3.6...2.3.7

What's Changed

• Fixed an issue where module recompilation would fail on Windows environments when KSP2 was enabled (#2774)
• Resolved an issue where generated Java sources were ignored when using Android Kotlin Multiplatform with IP-compatible paths (#2744)
• Fixed a KSP version 2.3.5 CI error exception that does not break build checks (#2763)
• Added symbol-processing-api and common-deps to compile dependencies (#2789)
• Improved the detection of built-in Kotlin by removing the reliance on KotlinBaseApiPlugin (#2772)
• A back-port of a performance optimization in the Intellij / Analysis API (2785 )
• Added support for nested typealias Kotlin language feature #2588
• Exclude jdbc package from log4j to prevent vulnerability issue #2651

Contributors

• Thanks to @salmanmkc, @jaschdoc, @gurusai-voleti and everyone who reported bugs and participated in discussions!

Full Changelog: 2.3.5...2.3.6

What's Changed

• A new Gradle property flag was added to mute the warnings about KSP1 usage. You can enable this by setting warn.on.ksp1.usage=false in your gradle.properties file.

Full Changelog: 2.2.21-2.0.4...2.2.21-2.0.5

What's Changed

• KSPCoreEnvironment.instance_prop leaks memory when used programmatically #2742
• Missing first annotation argument when toByte is used #2672
• Fix circular dependency between KSP and KAPT in AGP 9.0 #2743

Contributors

• Thanks to everyone who reported bugs and participated in discussions!

Full Changelog: 2.3.4...2.3.5

What's Changed

• KSP ignores sources in Kotlin directory #2730
• Avoid recording Java symbol lookups in non-incremental builds #2728
• Clean up ThreadLocals when processing is done #2709

Contributors

• Thanks to everyone who reported bugs and participated in discussions!

Full Changelog: 2.3.3...2.3.4