Migrate to KSP 2 and Kotlin 2.2.21 by martinbirn · Pull Request #1393 · airbnb/epoxy

martinbirn · 2025-11-04T21:02:10Z

Summary

This PR migrates Epoxy to KSP 2.0 (version 2.3.3) and Kotlin 2.2.21, bringing compatibility with the latest Kotlin toolchain and fixing multiple issues that arose during the migration.

Key Changes:

Kotlin 2.2.21, KSP 2.3.3, AGP 8.13.0, Gradle 8.13, Java 17
Migration from deprecated KSP APIs to new XProcessing APIs
Fixed critical type resolution and code generation issues
Updated all dependencies for KSP 2 compatibility
All tests passing with KSP 2

Fixes:

Requirements

Java 17 is now required (upgraded from Java 8 due to AGP 8.13.0 databinding compilation requirements)
minSdk 21 for modules using Paris library (upgraded from minSdk 16 due to Paris 2.1.0 requirements)

Changes

Dependency Updates

Kotlin: 1.8.21 → 2.2.21
KSP: 1.8.21-1.0.11 → 2.3.3
AGP: 7.4.0 → 8.13.0
Gradle: 7.6.1 → 8.13
Java: 8 → 17
Paris: 2.0.2 → 2.2.1
Mockito: 3.7.7 → 5.20.0
google-compile-testing: 0.19 → 0.23.0
kotlin-compile-testing: 1.5.0 → dev.zacsweers.kctfork: 0.11.0 (replacement for KSP 2 support)
Added: com.google.devtools.ksp:symbol-processing-aa-embeddable (required for KSP2 annotation types)

Build Configuration Updates

Added Compose Compiler Gradle plugin for Kotlin 2.0+ compatibility
Migrated to namespace in build.gradle
Replaced compileOptions/kotlinOptions with unified kotlin { jvmToolchain(17) }
Removed deprecated android.databinding.incremental and dexOptions
Migrated from deprecated @Xopt-in flags to @opt-in

KSP API Migration

Migrated from XAnnotationBox to direct XAnnotation API (use getAsBoolean(), getAsInt(), getAsString(), getAsEnumList() instead of accessing .value property)
Added support for KSAnnotationResolvedImpl annotation types in KSP2
Updated KSP internal class imports: com.google.devtools.ksp.symbol.impl.* → com.google.devtools.ksp.impl.symbol.* (e.g., KSAnnotationJavaImpl)
Updated Kotlin/IntelliJ imports: classes moved to ksp.* package prefixes (e.g., org.jetbrains.kotlin.psi.* → ksp.org.jetbrains.kotlin.psi.*)
Updated resource scanning to use new XProcessing APIs
Updated test utilities to use configureKsp extension (kotlin-compile-testing → kctfork migration)

Critical Bug Fixes

Type Name Resolution

In KSP 2.0, types with different wildcards (e.g., List<CharSequence> vs List<? extends CharSequence>) have identical equals()/hashHash() but different TypeName, causing cache collisions. Changed memoization cache key from XType to TypeName to restore proper handling of variance projections.

kotlin.Unit Mapping

Added support for JVM signature 'V' to fix IllegalStateException: unexpected jvm signature V. The implementation preserves kotlin.Unit instead of converting it to java.lang.Void.

Non-Deterministic Annotation Generation

XProcessing's XAnnotation.annotationValues exhibited non-deterministic behavior in KSP, causing test flakiness. Switched to declaredAnnotationValues which consistently returns only explicitly declared values (following Room's approach).

Invalid Lifetime Access in Error Logging

In KSP2, PSI elements become invalid after a processing round. Fixed by extracting element location info immediately when exception is created and embedding it in the exception message instead of passing XElement to messager.

Paris KSP2 Compatibility

Updated Paris to 2.2.1 to fix NoSuchMethodError caused by outdated XProcessing API (airbnb/paris#183).

Test & Lint Fixes

Updated tests to reflect KSP 2.0 behavior changes (variance handling, private field generation)
Updated expected generated models in tests to match new code generation
Fixed missing imports and dependencies in test resources

Documentation

Add README with KSP documentation

Checklist

…a 17 - Add Compose Compiler Gradle plugin for Kotlin 2.0+ compatibility - Migrate to namespaces in build.gradle (remove package from AndroidManifest) - Replace compileOptions/kotlinOptions with kotlin { jvmToolchain(17) } - Remove deprecated android.databinding.incremental and dexOptions

- Update Paris to 2.1.0 - Update Mockito to 5.20.0 - Update google-compile-testing to 0.23.0 - Replace kotlin-compile-testing with kctfork - Add KSP AA Embeddable dependency - Migrate from deprecated KSP APIs to new ConfigureKsp extension - Replace legacy @Xopt-in flags with @Opt-in - Migrate from XAnnotationBox to direct XAnnotation API - Update minSdkVersion - Fix resource references to use fully qualified names - Remove unused BuildConfig imports from tests - Update annotation processing to use new XProcessing APIs

Two critical bugs were fixed to make KSP 2.0 compatible: 1. Fixed memoization cache key collision - Problem: In KSP 2.0, types with different wildcards (e.g., List<CharSequence> vs List<? extends CharSequence>) have identical equals()/hashCode() but different typeName - Solution: Changed cache key from XType to TypeName in Memoizer - Files: Memoizer.kt 2. Fixed kotlin.Unit being mapped to java.lang.Void - Problem: kotlin.Unit was converted to java.lang.Void via JVM signature 'V' - Solution: Added special case to preserve kotlin.Unit before JVM signature conversion - Files: TypeNameWorkaround.kt These fixes restore compatibility with variance projections (? extends, ? super) and Kotlin function types in KSP 2.0.

Updated two tests that were failing due to changes in KSP 2.0 code generation: - defaults_kspDoesNotThrowForPrivateValue → defaults_kspGeneratesCodeForPrivateValue - testFieldPropNotThrowsIfPrivate_ksp → testFieldPropGeneratesCodeForPrivate_ksp Previously (KSP 1.x), no code was generated for private fields and tests passed. Now (KSP 2.x), code is generated that references private fields, causing compilation errors. The code generation itself works correctly, so we ignore the compilation error with ignoreCompilationError = true.

Updated TestManyTypesView to use proper contravariant types for Function3 parameters, matching how Kotlin stdlib defines Function3<in P1, in P2, in P3, out R>. KSP 2.x correctly reads declaration-site variance from Kotlin types and generates `? super` wildcards for contravariant parameters. The test source and expected outputs now reflect this correct behavior. Changes: - TestManyTypesView.java: Updated setFunction signature to use Function3<? super Integer, ? super Integer, ? super Integer, Integer> - TestManyTypesViewModel_.java: Updated expected output to match

…ency Resolves "Symbol not found for /AirEpoxyModel" error in wildcardHandling test. The test was failing because it referenced AirEpoxyModel as the base class but the required class file was not included in the test inputs. Added AirEpoxyModel.java to test resources and updated test to include it in input files.

The testStyleableViewKotlinSources_ksp test was failing because the Paris extension function modelViewWithParisStyle is generated in the com.airbnb.paris.extensions package, but the test source file was missing the required import statement. Added the import to fix the "Unresolved reference" compilation error.

The MutableCollectionMutableStateDetector from androidx.compose.runtime.lint crashes with NullPointerException when trying to access KotlinUastResolveProviderService during lint analysis. This is a compatibility issue with the current KSP/Kotlin setup.

@deprecated

…n format - Add tools:targetApi="28" to AndroidManifest to suppress CoreComponentFactory API level warning - Update @deprecated annotation in ModelWithAnnotation_ to include since and forRemoval parameters

In KSP2, PSI elements become invalid after a processing round completes. When Logger.writeExceptions() tried to pass XElement to messager during error reporting, it crashed with KaInvalidLifetimeOwnerAccessException. Solution inspired by paris-processor approach: - Extract element location info immediately when exception is created (while PSI is still valid) - Store location details as string in exception message - Don't pass XElement to messager, only print the formatted message Changes: - EpoxyProcessorException: Extract element name and enclosing element info in constructor and append to message - Logger.writeExceptions(): Remove element parameter from messager call, rely on location info already embedded in exception message

@deprecated

…onValues The xprocessing library's XAnnotation.annotationValues property exhibits non-deterministic behavior in KSP, sometimes returning annotation values with defaults and sometimes returning an empty list. This caused tests to fail randomly depending on which values were returned during processing. Switched to using declaredAnnotationValues instead, which consistently returns only explicitly declared values (excluding defaults). This approach mirrors Room's implementation in JavaPoetExt.kt. This fix eliminates the flakiness where @deprecated would sometimes be generated as @deprecated and sometimes as @deprecated(since = "", forRemoval = false).

Paris 2.1.0 used an outdated XProcessing API that caused NoSuchMethodError when processing @Styleable annotations with KSP2. Paris 2.2.1 updates XProcessing to a compatible version, fixing crashes in all modules using Paris. Fixes: airbnb/paris#183

martinbirn · 2025-11-04T21:19:45Z

@elihart This addresses the KSP2 compatibility issues. Ready for review when you have time!

elihart · 2025-11-17T22:43:01Z

Thanks for the contribution @martinbirn ! I have been PTO the last few weeks and will now try to review this soon 🙏

epoxy-adapter/build.gradle

blessedDeps.gradle

build.gradle

elihart

Thanks! Overall looks good - my only concern is the change in target compatibility.

Epoxy's test suite is fairly comprehensive, so if that passes we should have reasonable confidence, however, I can't guarantee this works (in terms of generating the exact same code without issues) until we attempt to use it within our project at Airbnb at which point we can ensure that behavior is identical (since we have a very large code base using it, with screenshot tests). We won't be able to do that for a while yet though, as we need to make some changes to our other processors first.

However, this should be safe to merge for now, once the compatibility is addressed, and I can cut a release for people to try.

Addresses PR feedback to upgrade dependencies: - KSP_VERSION: 2.2.21-2.0.4 → 2.3.3 (decouples KSP from Kotlin version) - XPROCESSING_VERSION: 2.8.3 → 2.8.4 (latest stable release) KSP 2.3.0 removed KSClassDeclarationJavaImpl, requiring updates to KspResourceScanner.getImports() implementation. Changes to KspResourceScanner: - Replace direct access to KSClassDeclarationJavaImpl with navigation through containingFile property to KSFileImpl/KSFileJavaImpl - Improve getFieldWithReflection() error handling to try getDeclaredMethod() as fallback when getMethod() fails Note: getImports() is primarily used when fieldType.isError() in ControllerProcessor, which occurs in KAPT/JavaAP but not in KSP due to deferred symbol validation. These changes ensure correctness if the architecture changes or the method is reused elsewhere.

This change minimizes breaking changes for consumers by reverting most modules back to Java 8/11, keeping Java 17 only where strictly required. Background: - AGP 8.13.0's DataBinding parser classes are compiled with Java 17 - When KAPT is used with DataBinding, KAPT loads these parser classes - KAPT runs in a JVM specified by kotlin.jvmToolchain() - If jvmToolchain < 17, loading fails with UnsupportedClassVersionError Why modules were reverted: - Modules WITHOUT KAPT process DataBinding via AGP directly in Gradle daemon, so they don't need jvmToolchain(17) - Pure library modules without DataBinding layouts never load parser classes, so they can safely use Java 8/11 Modules keeping Java 17 (KAPT + DataBinding): - epoxy-integrationtest - epoxy-processortest - epoxy-sample - kotlinsample Modules reverted to Java 8/11: - epoxy-annotations: Java 8 - epoxy-compose: Java 8 - epoxy-databinding: Java 8 - epoxy-modelfactory: Java 8 - epoxy-processortest2: Java 8 - epoxy-adapter: Java 11 (epoxy-processor) - epoxy-glide-preloader: Java 11 (epoxy-processor) - epoxy-paging3: Java 11 (epoxy-processor) - epoxy-viewbinder: Java 11 (epoxy-processor) - epoxy-processor: Java 11 (xProcessing) - epoxy-composeinterop-maverickssample: Java 11 (paris/epoxy-processor) - epoxy-composesample: Java 11 (paris/epoxy-processor) - epoxy-kspsample: Java 11 (paris/epoxy-processor) - epoxy-modelfactorytest: Java 11 (epoxy-processor) - epoxy-preloadersample: Java 11 (epoxy-processor)

elihart

The jvm/compatibility configuration looks good now, thank you. I've having trouble getting the CI checks to run - they are stalled in a queue for some reason. Once those all pass though I will merge this

martinbirn · 2025-11-21T18:31:07Z

Got it, thanks!

elihart · 2025-11-22T01:33:41Z

I merged a PR to master that fixes the CI workflow configuration, which is why the checks weren't working on this PR. This PR would need to be rebased in order for them to run correctly, but I ran them locally to verify it and will merge as is.

martinbirn added 13 commits October 29, 2025 00:24

Fix lint NewApi error in epoxy-sample and update Deprecated annotatio…

4cf36e2

…n format - Add tools:targetApi="28" to AndroidManifest to suppress CoreComponentFactory API level warning - Update @deprecated annotation in ModelWithAnnotation_ to include since and forRemoval parameters

Add KSP documentation to README

550955a

elihart reviewed Nov 20, 2025

View reviewed changes

epoxy-adapter/build.gradle Show resolved Hide resolved

elihart reviewed Nov 20, 2025

View reviewed changes

blessedDeps.gradle Outdated Show resolved Hide resolved

elihart reviewed Nov 20, 2025

View reviewed changes

build.gradle Outdated Show resolved Hide resolved

elihart reviewed Nov 20, 2025

View reviewed changes

martinbirn added 2 commits November 21, 2025 00:32

elihart approved these changes Nov 21, 2025

View reviewed changes

elihart merged commit 0824c31 into airbnb:master Nov 22, 2025
0 of 2 checks passed

martinbirn deleted the ksp2 branch November 22, 2025 15:06

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Migrate to KSP 2 and Kotlin 2.2.21#1393

Migrate to KSP 2 and Kotlin 2.2.21#1393
elihart merged 15 commits intoairbnb:masterfrom
martinbirn:ksp2

martinbirn commented Nov 4, 2025 •

edited

Loading

Uh oh!

martinbirn commented Nov 4, 2025

Uh oh!

elihart commented Nov 17, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

elihart left a comment •

edited

Loading

Uh oh!

elihart left a comment •

edited

Loading

Uh oh!

martinbirn commented Nov 21, 2025

Uh oh!

elihart commented Nov 22, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

martinbirn commented Nov 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Requirements

Changes

Dependency Updates

Build Configuration Updates

KSP API Migration

Critical Bug Fixes

Type Name Resolution

kotlin.Unit Mapping

Non-Deterministic Annotation Generation

Invalid Lifetime Access in Error Logging

Paris KSP2 Compatibility

Test & Lint Fixes

Documentation

Checklist

Uh oh!

martinbirn commented Nov 4, 2025

Uh oh!

elihart commented Nov 17, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

elihart left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

elihart left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

martinbirn commented Nov 21, 2025

Uh oh!

elihart commented Nov 22, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

martinbirn commented Nov 4, 2025 •

edited

Loading

elihart left a comment •

edited

Loading

elihart left a comment •

edited

Loading