Kotlin K2 and Standalone Supply Generator

Posted by Ting-Yuan Huang – Software program Engineer, and Jiaxiang Chen – Software program Engineer

The Kotlin Image Processing (KSP) instrument gives a high-level API for doing meta-programming in Kotlin. Many instruments have been constructed on KSP, enabling Kotlin code to be generated at compile time. For instance, Jetpack Room makes use of KSP to generate code for accessing the database, primarily based on an interface offered by the developer, like:

@Dao
interface UserDao {
    @Question("SELECT * FROM consumer")
    enjoyable getAll(): Record<Consumer>
}

KSP gives the API to the Kotlin code in order that Room on this case can generate the precise implementation of that interface. Whereas KSP has grow to be a core basis for meta-programing in Kotlin, its present implementation has some gaps which we’re aiming to resolve with a brand new KSP2 structure. This weblog particulars these architectural modifications and the influence for plugins constructed on KSP.

As well as, KSP2 has preview assist for:

• The brand new Kotlin compiler (code-named K2)
• A brand new standalone supply generator that gives extra flexibility and options than the present Kotlin compiler plugin

After getting suggestions on the brand new structure and persevering with to deal with gaps we are going to work in the direction of releasing KSP 2.0 the place these modifications would be the default.

Enabling the KSP2 Preview

The brand new preview modifications will be enabled in KSP 1.0.14 or newer utilizing a flag in gradle.properties:

Notice: You may have to enlarge the heap measurement of the Gradle daemon now that KSP and processors run within the Gradle daemon as an alternative of the Kotlin compiler’s daemon (which has bigger default heap measurement), e.g. org.gradle.jvmargs=-Xmx4096M -XX:MaxMetaspaceSize=1024m

KSP2 and K2

Internally KSP2 makes use of the Beta Kotlin K2 compiler (which would be the default compiler in Kotlin 2.0). You should utilize KSP2 earlier than switching your Kotlin compiler to K2 (through the languageVersion setting) however if you wish to use K2 for compiling your code, try: Attempt the K2 compiler in your Android tasks.

Standalone Supply Generator

KSP1 is carried out as a Kotlin 1.x compiler plugin. Operating KSP requires operating the compiler and specifying KSP and its plugin choices. In Gradle, KSP’s duties are personalized compilation duties, which dispatch actual work to KotlinCompileDaemon by default. This makes debugging and testing considerably tough, as a result of KotlinCompileDaemon runs in its personal course of, exterior of Gradle.

In KSP2, the implementation will be regarded as a library with a predominant entry level. Construct programs and instruments can name KSP with this entry level, with out establishing the compiler. This makes it very simple to name KSP programmatically and may be very helpful particularly for debugging and testing. With KSP2 you’ll be able to set breakpoints in KSP processors with out having to carry out every other / irregular setup duties to allow debugging.

The whole lot turns into a lot simpler as a result of KSP2 now controls its lifecycle and will be known as as a standalone program or programmatically, like:

val kspConfig = KSPJvmConfig.Builder().apply {
  // All configurations occur right here.
}.construct()
val exitCode = KotlinSymbolProcessing(kspConfig, listOfProcessors, kspLoggerImpl).execute()

KSP2 API Habits Modifications

With the brand new implementation, it’s also a terrific alternative to introduce some refinements within the API conduct in order that builders constructing on KSP shall be extra productive, have higher debuggability and error restoration. For instance, when resolving Map<String, NonExistentType>, KSP1 merely returns an error sort. In KSP2, Map<String, ErrorType> shall be returned as an alternative. Here’s a checklist of the present API conduct modifications we plan on making in KSP2:

1. Resolve implicit sort from operate name: val error = mutableMapOf<String, NonExistType>()

   KSP1: The entire sort shall be an error sort on account of failed sort decision

   KSP2: It is going to efficiently resolve the container sort, and for the non-existent sort within the sort argument, it’ll appropriately report errors on the precise sort argument.

2. Unbounded sort parameter

   KSP1: No bounds

   KSP2: An higher sure of Any? is all the time inserted for consistency

3. Resolving references to sort aliases in operate sorts and annotations

   KSP1: Expanded to the underlying, non-alias sort

   KSP2: Not expanded, like makes use of somewhere else.

4. Totally certified names

   KSP1: Constructors have FQN if the constructor is from supply, however not if the constructor is from a library.

   KSP2: Constructors do not need FQN

5. Kind arguments of interior sorts

   KSP1: Internal sorts has arguments from outer sorts

   KSP2: Internal sorts has no arguments from outer sorts

6. Kind arguments of star projections

   KSP1: Star projections have sort arguments which can be expanded to the efficient variances in keeping with the declaration websites.

   KSP2: No growth. Star projections have nulls of their sort arguments.

7. Variance of Java Array

   KSP1: Java Array has a invariant higher sure

   KSP2: Java Array has a covariant higher sure

8. Enum entries

   KSP1: An enum entry has its personal subtype with a supertype of the enum class (incorrect conduct from language standpoint)

   KSP2: An enum entry’s sort is the kind of the enclosing enum class

9. Multi-override situation

   For instance

   interface GrandBaseInterface1 {
       enjoyable foo(): Unit
   }
   
   interface GrandBaseInterface2 {
       enjoyable foo(): Unit
   }
   
   interface BaseInterface1 : GrandBaseInterface1 {
   }
   
   interface BaseInterface2 : GrandBaseInterface2 {
   }
   
   class OverrideOrder1 : BaseInterface1, GrandBaseInterface2 {
       override enjoyable foo() = TODO()
   }
   class OverrideOrder2 : BaseInterface2, GrandBaseInterface1 {
       override enjoyable foo() = TODO()
   }
   

   KSP1:

   Discover overridden symbols in BFS order, first tremendous sort discovered on direct tremendous sort checklist that comprises overridden image is returned
   For the instance, KSP will say OverrideOrder1.foo() overrides GrandBaseInterface2.foo() and OverrideOrder2.foo() overrides GrandBaseInterface1.foo()

   KSP2:

   DFS order, first tremendous sort discovered overridden symbols (with recursive tremendous sort search for) in direct tremendous sort checklist is returned.

   For the instance, KSP will say OverrideOrder1.foo() overrides GrandBaseInterface1.foo() and OverrideOrder2.foo() overrides GrandBaseInterface2.foo()

10. Java modifier

    KSP1: Transient/risky fields are closing by default

    KSP2: Transient/risky fields are open by default

11. Kind annotations

    KSP1: Kind annotations on a sort argument is barely mirrored on the sort argument image

    KSP2: Kind annotations on a sort argument now current within the resolved sort as effectively

12. vararg parameters

    KSP1: Thought of an Array sort

    KSP2: Not thought-about an Array sort

13. Synthesized members of Enums

    KSP1: values and valueOf are lacking if the enum is outlined in Kotlin sources

    KSP2: values and valueOf are all the time current

14. Synthesized members of information lessons

    KSP1: componentN and copy are lacking if the information class is outlined in Kotlin sources

    KSP2: componentN and copy are all the time current

New Multiplatform Processing Scheme

With regards to the processing scheme, i.e. what sources are processed when, the precept of KSP is to be in keeping with the construct’s present compilation scheme. In different phrases, what the compiler sees is what processors see, plus the supply code that’s generated by processors.

In KSP1’s present compilation scheme, widespread / shared supply units are processed and compiled a number of instances, with every goal. For instance, commonMain is processed and compiled 3 instances within the following venture format. With the ability to course of all of the sources from dependencies is handy with one exception: Processors don’t see the sources generated from commonMain when processing jvmMain and jsMain. The whole lot should be re-processed and that may be inefficient.

In KSP2, we plan so as to add an experimental mode that tries to align to how supply units are compiled in K2 higher. All sources will be processed solely as soon as with the out there new processing scheme:

Please word that Kotlin 2.0 remains to be in beta and the compilation mannequin is topic to alter. Please tell us how this works for you and provides us suggestions.

KSP2 Preview Suggestions

KSP2 is in preview however there’s nonetheless extra work to be accomplished earlier than a secure launch. We hope these new options will finally allow you to be extra productive when utilizing KSP! Please present us together with your suggestions so we are able to make these enhancements superior as they progress in the direction of being secure.