Skip to content

feat(compiler): add KSP2 support with compatibility and performance validation - #1088

Merged
zhi1ong merged 5 commits into
developfrom
codex/ksp2-support
Sep 12, 2026
Merged

zhi1ong merged 5 commits into
developfrom
codex/ksp2-support

Conversation

@zhi1ong

@zhi1ong zhi1ong commented Sep 12, 2026 •

Copy link
Copy Markdown
Member

Summary / 变更说明

Add a standalone KSP2 compiler so Android modules can generate ARouter route/provider registries, injection helpers, interceptor registries and route documentation without running ARouter through KAPT. Keep the existing APT/KAPT compiler and runtime contracts intact; mixed applications can use different backends in separate modules, including precompiled KAPT parents.

The implementation includes deferred symbol handling, explicit diagnostics for unsupported Kotlin fields, inherited/generic field mapping, and incremental deletion/ancestor-change coverage. Round-scoped analysis and narrower aggregate dependencies reduce redundant compiler work while preserving generated output.

Related issue / 关联 Issue

Related to #959. The new artifact is a local development snapshot; publishing a release is outside this PR.

Compatibility / 兼容性

  • KSP 2.3.12, Kotlin 2.3.20 and JDK 17; the standalone producer uses Gradle 9.5 and emits Java 8 bytecode.
  • Consumer matrix: AGP 8.12.0 / Gradle 8.13 / API 34; AGP 9.0.0 / Gradle 9.1.0 / API 34; AGP 9.3.2 / Gradle 9.5 / API 21 and 34. The AGP 9.3 row is empirical compatibility coverage beyond Kotlin 2.3.20's officially documented full-support range.
  • No Android runtime/public API change. Generated names and registration contracts remain compatible with the existing plugin/manual registration paths.
  • One ARouter backend per module. Kotlin injection supports accessible mutable @JvmField and lateinit fields; ordinary properties and other unsupported cases receive documented diagnostics.

Validation / 验证

  • Added focused regressions: 35 real KSP/JVM tests pass on the final implementation.
  • Final optimized sources pass the AGP 8.12/API 34 consumer verifier, Debug and Release/R8 emulator tests, and incremental route deletion, unannotated-ancestor and inherited-field changes.
  • All four consumer matrix rows passed in GitHub Actions on final head c8e7b528b6ea53f4621670b173ff4479214637e3, including the analysis optimization, Debug/Release-R8 device tests and incremental mutation checks.
  • Existing APT tests and the legacy Kotlin 1.4.10/JDK 8 KAPT compilation chain passed during development. The complete legacy build, four Gradle plugin compatibility rows, six device test rows, IDE navigation tests, wrapper validation, CodeQL and CLA also passed in PR CI.
  • Controlled KAPT/KSP benchmark: 140 measured samples plus warmups across seven scenarios. Optimization comparison: 100 measured samples plus warmups across five scenarios, with all 134 generated Java files byte-identical before/after. Improvements and remaining tradeoffs are documented in BENCHMARK.md and OPTIMIZATION.md; no universal speedup is claimed.
  • No generated consumer sources, build reports, credentials or unrelated formatting are included. The standalone Gradle wrapper JAR is intentionally tracked.
  • The pull request targets develop.
  • All commit authors have completed the required CLA check (license/cla passed on this PR).

Final CI: all 20 checks passed. Build run: https://github.com/alibaba/ARouter/actions/runs/34693662788

Preserve the runtime registration ABI while adding a standalone KSP2 build, mixed APT/KSP Android consumer, incremental checks, and CI. The first milestone explicitly diagnoses source injection and interceptor annotations.

Validated 15 KSP integration tests, 7 existing compiler tests, the legacy KAPT compilation chain, and API 34 Debug/Release R8 navigation.
Preserve field defaults, explicit nulls, provider requirements and concrete generic type tokens. Support writable JVM fields and nested injector names with coordinated multi-round validation and explicit diagnostics for unsupported Kotlin property shapes.

Validated 27 real KSP integration tests and mixed KAPT/KSP Android injection, inheritance, interception, cancellation and incremental cleanup on API 34 Debug and Release/R8.
Match JVM field wildcard variance and recursively preserve parameterized Java owners. Add reflection-based coverage for raw/star/wildcard types, arrays, providers and nested owners.

Validate exact AGP 8.12, 9.0 and 9.3 toolchains with observed version fingerprints, isolated artifact snapshots, 33 JVM regressions and eight Debug/Release R8 device executions on API 21 and 34.
Use identical generated sources, frozen artifacts, isolated Gradle homes and verified K2 compiler options. Measure seven scenarios with two warmups and ten paired samples per backend, with post-timing bytecode and route output checks.

Validated 140 measured samples plus 28 warmups and both backend device preflights. Record scenario-specific results without claiming a universal speedup.
Share round-local ancestry results, stop at known routing roots, and avoid provider traversal for JVM scalars and arrays. Associate aggregate registries only with their annotated roots while retaining traced parent and field dependencies.

Validated 35 KSP tests, inherited-dependency mutation builds, Debug/Release R8 navigation, and 100 paired before/after measurements with 134 byte-identical generated Java files.
@zhi1ong
zhi1ong merged commit 08b926a into develop Sep 12, 2026
20 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant