docs/ksp2.md - third_party/github/google/ksp - Git at Google

 # Introduction to KSP2

 KSP2 is a new implementation of the KSP API. Unlike KSP 1.x, it is no longer a compiler plugin and is built on the same
 set of Kotlin compiler APIs shared with IntelliJ IDEA, Android Lint, etc. Compared to the compiler-plugin approach, this
 allows a finer control of the program life cycle, simplifies KSP’s implementation and is more efficient. It is also a
 response to the compiler migration to K2, whose compiler plugin API is different from the one KSP1 uses.

 Not being a compiler plugin and having a better control of the program life cycles means that it’s straightforward to
 provide an entry point that can be called by other programs. This is especially convenient for testing processors
 as a processor author.
 KSP2 also provides a new command line tool that has its own main function, instead of being part of the compiler
 invocation.

 With the new implementation, it is also a great opportunity to introduce some refinements in the API behavior so that
 developers building on KSP will be more productive, have better debuggability and error recovery. For example, when
 resolving `Map<String, NonExistentType>`, KSP1 simply returns an error type. In KSP2, `Map<String, ErrorType>` will be
 returned instead.

 ## API Changes

 Please refer to [KSP2 API Changes](ksp2api.md) to see more details.

 ## Debugging

 Unlike KSP1, which runs in `KotlinCompileDaemon`, KSP2 runs in Gradle daemon. This has 2 implications:
 1. Gradle daemon usually has a lower default heap limit. You may need to increase it by the following Gradle property,
 for example: `org.gradle.jvmargs=-Xmx4096M -XX:MaxMetaspaceSize=1024m`
 2. The debug flags now need to be passed to Gradle rather than `KotlinCompileDaemon`. To debug KSP2 and/or processors,
    pass the system property `-Dorg.gradle.debug=true` in the Gradle command line.

 ## Using KSP 2 from command line and in program
 Please refer to [Using KSP2 command line](ksp2cmdline.md) and [Calling KSP2 in program](ksp2entrypoints.md).

 ## Known Issues
 The main gaps between KSP2 Beta and KSP2 Stable are:
 * Support of mangled (for `inline` and `internal`) JVM names in `Resolver.getJvmWildcard` and
   `Resolver.mapToJvmSignature`
 * Support of synthesized Java getters and setters for Kotlin properties in `Resolver.findOverridee` and
   `Resolver.asMemberOf`.
 * Performance and memory footage are not fully taken care of yet.
 * Some type of annotation values are not supported (e.g. nested annotations)

 Please check the KSP [2.0](https://github.com/google/ksp/issues?q=is%3Aopen+is%3Aissue+milestone%3A2.0) and
 [2.1](https://github.com/google/ksp/issues?q=is%3Aopen+is%3Aissue+milestone%3A2.1) milestones on GitHub for the complete
 lists of known issues.

 ## Feedback
 If you find any bugs that are not included in the above milestones, or if you have any concerns or ideas on API changes,
 [please let us know](https://github.com/google/ksp/issues)!
	# Introduction to KSP2

	KSP2 is a new implementation of the KSP API. Unlike KSP 1.x, it is no longer a compiler plugin and is built on the same
	set of Kotlin compiler APIs shared with IntelliJ IDEA, Android Lint, etc. Compared to the compiler-plugin approach, this
	allows a finer control of the program life cycle, simplifies KSP’s implementation and is more efficient. It is also a
	response to the compiler migration to K2, whose compiler plugin API is different from the one KSP1 uses.

	Not being a compiler plugin and having a better control of the program life cycles means that it’s straightforward to
	provide an entry point that can be called by other programs. This is especially convenient for testing processors
	as a processor author.
	KSP2 also provides a new command line tool that has its own main function, instead of being part of the compiler
	invocation.

	With the new implementation, it is also a great opportunity to introduce some refinements in the API behavior so that
	developers building on KSP will be more productive, have better debuggability and error recovery. For example, when
	resolving `Map<String, NonExistentType>`, KSP1 simply returns an error type. In KSP2, `Map<String, ErrorType>` will be
	returned instead.

	## API Changes

	Please refer to [KSP2 API Changes](ksp2api.md) to see more details.

	## Debugging

	Unlike KSP1, which runs in `KotlinCompileDaemon`, KSP2 runs in Gradle daemon. This has 2 implications:
	1. Gradle daemon usually has a lower default heap limit. You may need to increase it by the following Gradle property,
	for example: `org.gradle.jvmargs=-Xmx4096M -XX:MaxMetaspaceSize=1024m`
	2. The debug flags now need to be passed to Gradle rather than `KotlinCompileDaemon`. To debug KSP2 and/or processors,
	pass the system property `-Dorg.gradle.debug=true` in the Gradle command line.

	## Using KSP 2 from command line and in program
	Please refer to [Using KSP2 command line](ksp2cmdline.md) and [Calling KSP2 in program](ksp2entrypoints.md).

	## Known Issues
	The main gaps between KSP2 Beta and KSP2 Stable are:
	* Support of mangled (for `inline` and `internal`) JVM names in `Resolver.getJvmWildcard` and
	`Resolver.mapToJvmSignature`
	* Support of synthesized Java getters and setters for Kotlin properties in `Resolver.findOverridee` and
	`Resolver.asMemberOf`.
	* Performance and memory footage are not fully taken care of yet.
	* Some type of annotation values are not supported (e.g. nested annotations)

	Please check the KSP [2.0](https://github.com/google/ksp/issues?q=is%3Aopen+is%3Aissue+milestone%3A2.0) and
	[2.1](https://github.com/google/ksp/issues?q=is%3Aopen+is%3Aissue+milestone%3A2.1) milestones on GitHub for the complete
	lists of known issues.

	## Feedback
	If you find any bugs that are not included in the above milestones, or if you have any concerns or ideas on API changes,
	[please let us know](https://github.com/google/ksp/issues)!