README.md
1# X Processing
2
3This module (room-compiler-processing) provides an abstraction over Java Annotation Processing
4(JavaAP) and Kotlin Symbol Processing (KSP) for Room's annotation processor.
5
6If you are an annotation processor author and want to add KSP support to your project (while still
7supporting Java AP), this library might be useful to get ideas or even directly use it in your
8project.
9
10**DISCLAIMER**
11This is NOT a public Jetpack library and it will NOT have any of the API guarantees that Jetpack
12Libraries provide (e.g. no semantic versioning). That being said, if it is useful for your use
13case, feel free to use it. If you include it in your project, please `jarjar` it to avoid classpath
14conflicts with Room.
15This library is still expected to be a production quality abstraction because Room relies on it.
16
17## Project Goals
18This is **not** a general purpose abstraction over JavaAP(JSR 269) and KSP. Instead, it is designed
19to support what Room needs (and only what Room needs). Despite this goal, it ended up covering most
20use cases hence the library can be used as a general purpose abstraction and it also includes a
21testing artifact (room-compiler-processing-testing).
22
23If this abstraction turns out to be useful to enough people, we are open to unbundling it
24from Room as an independent library.
25
26### Want to make changes?
27As long as it does not break Room, we are happy to expand the library to cover your use case. If you
28would like a change:
29
30* File a bug. [example](https://issuetracker.google.com/issues/182195680)
31* Once the bug is acknowledged by the Room team, send a PR.
32[example](https://github.com/androidx/androidx/pull/137)
33 * Make sure to add good tests coveraging the change in the PR. Not only it is mandatory for
34 AndroidX submissions, but will also help us ensure we don't break it.
35
36
37## How To Use It
38
39The entry API is the [XProcessingEnv](src/main/java/androidx/room/compiler/processing/XProcessingEnv.kt)
40which has the necessary API's to access types etc.
41
42To find annotated elements, you need to subclass the
43[XProcessingStep](src/main/java/androidx/room/compiler/processing/XProcessingStep.kt).
44It is very similar to the
45[BasicAnnotationProcessor](https://github.com/google/auto/blob/master/common/src/main/java/com/google/auto/common/BasicAnnotationProcessor.java)
46API in [Google Auto](https://github.com/google/auto) and you can find Room's implementation
47[here](../compiler/src/main/kotlin/androidx/room/DatabaseProcessingStep.kt).
48
49To initialize your `XProcessingStep` implementation, you still need to create your own
50 AnnotationProcessor (JavaAP) or SymbolProcessor (KSP) implementations and tie it to the
51 `XProcessingStep`.
52* Room's [KSP processor](../compiler/src/main/kotlin/androidx/room/RoomKspProcessor.kt)
53* Room's [JavaAP processor](../compiler/src/main/kotlin/androidx/room/RoomProcessor.kt)
54
55For everything else, the API docs in the library should be sufficient and if not, feel free to file
56bugs for more explanations.
57
58## Main Classes
59### XTypeElement
60This is analogous to JavaAP's `TypeElement` or KSP's `KSClassDeclaration`.
61It can be used to get methods, fields etc declared in a class declaration.
62### XType
63This is analogous to JavaAP's `TypeMirror` or KSP's `KSType`. For convenience, each
64`XType` has a `typeName` property that convert it to JavaPoet's `TypeName`. For types that do not
65match 1-1 between Kotlin and Java (e.g. Kotlin `Int` maps to `java.lang.Integer` or primitive `int
66`), Room will do a best effort conversion based on the information avaiable from the use site.
67### XFieldElement
68Represents a field in Java. Might be driven from a kotlin property.
69You can obtain them via `XTypeElement`.
70### XMethodElement
71Represents a Java method or Kotlin function. They can be obtained from `XTypeElement`.
72### XConstructorElement
73Similar to `XMethodElement` but only represents constructor functions.
74### XMethodType
75Represents an `XMethodElement` as member of an `XType`. Notice that when a method is resolved as
76a member of an `XType`, all available type arguments will be resolved based on the type
77declaration.
78
79## Known Caveats (a.k.a. hacks)
80XProcessing assumes it is being used to generate Java code and tries to optimize for that. Chances
81are, if you are converting a Java AP to support KSP, your annotation processor expects what
82XProcessing does.
83Caveats listed here are subject to change if/when Room supports generating Kotlin code but it is
84very likely that we'll make it an argument to XProcessing.
85
86### Suspend Methods
87For suspend methods, it will synthesize an additional `Continuation` parameter.
88
89### Properties
90XProcessing will synthesize `getter`/`setter` methods for Kotlin properties.
91
92### Overrides
93When checking if a method overrides another, XProcessing [checks its JVM declaration as well
94](https://android-review.googlesource.com/c/platform/frameworks/support/+/1564504/11/room/compiler-processing/src/main/java/androidx/room/compiler/processing/ksp/ResolverExt.kt#68),
95which may not be what you see in Kotlin sources but this is exactly what an Annotation Processor
96would see when used via KAPT.
97
98### Internal Modifier
99When an internal modifier is used in Kotlin code, its binary representation has a mangled name.
100XProcessing automatically checks for it and the `name` property of a method/property will include
101that conversion.
102