feat: allow passing KSP options via kt_ksp_plugin (#1478)

* feat: allow passing KSP options via kt_ksp_plugin

* test: add an integration test with a KSP plugin

* throw an error on duplicate option keys

* exclude test lib from wildcard build analysis

Author: monosoul

docs/kotlin.md

@@ -451,7 +451,7 @@ Define kotlin compiler options.
 <pre>
 load("@rules_kotlin//kotlin:core.bzl", "kt_ksp_plugin")
 
-kt_ksp_plugin(<a href="#kt_ksp_plugin-name">name</a>, <a href="#kt_ksp_plugin-deps">deps</a>, <a href="#kt_ksp_plugin-generates_java">generates_java</a>, <a href="#kt_ksp_plugin-processor_class">processor_class</a>, <a href="#kt_ksp_plugin-target_embedded_compiler">target_embedded_compiler</a>)
+kt_ksp_plugin(<a href="#kt_ksp_plugin-name">name</a>, <a href="#kt_ksp_plugin-deps">deps</a>, <a href="#kt_ksp_plugin-generates_java">generates_java</a>, <a href="#kt_ksp_plugin-options">options</a>, <a href="#kt_ksp_plugin-processor_class">processor_class</a>, <a href="#kt_ksp_plugin-target_embedded_compiler">target_embedded_compiler</a>)
 </pre>
 
 Define a KSP plugin for the Kotlin compiler to run. The plugin can then be referenced in the `plugins` attribute
@@ -485,6 +485,7 @@ kt_jvm_library(
 | <a id="kt_ksp_plugin-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
 | <a id="kt_ksp_plugin-deps"></a>deps |  The list of libraries to be added to the compiler's plugin classpath   | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional |  `[]`  |
 | <a id="kt_ksp_plugin-generates_java"></a>generates_java |  Runs Java compilation action for plugin generating Java output.   | Boolean | optional |  `False`  |
+| <a id="kt_ksp_plugin-options"></a>options |  Processor options passed to the KSP processor via SymbolProcessorEnvironment.options. Each entry is a key-value pair available to the processor at processing time.   | <a href="https://bazel.build/rules/lib/core/dict">Dictionary: String -> String</a> | optional |  `{}`  |
 | <a id="kt_ksp_plugin-processor_class"></a>processor_class |  The fully qualified class name that the Java compiler uses as an entry point to the annotation processor.   | String | required |  |
 | <a id="kt_ksp_plugin-target_embedded_compiler"></a>target_embedded_compiler |  Plugin was compiled against the embeddable kotlin compiler. These plugins expect shaded kotlinc dependencies, and will fail when running against a non-embeddable compiler.   | Boolean | optional |  `False`  |
 

kotlin/internal/jvm/compile.bzl

@@ -442,7 +442,8 @@ def _run_ksp_builder_actions(
         toolchains,
         srcs,
         compile_deps,
-        transitive_runtime_jars):
+        transitive_runtime_jars,
+        ksp_options = {}):
     """Runs KSP2 via a dedicated KSP2 worker.
 
     The worker handles all staging, KSP2 execution, and output packaging internally.
@@ -503,6 +504,10 @@ def _run_ksp_builder_actions(
     if transitive_runtime_jars:
         args.add_all("--processor_classpath", transitive_runtime_jars)
 
+    # Pass KSP processor options as key=value pairs
+    for key, value in ksp_options.items():
+        args.add("--ksp_options", "%s=%s" % (key, value))
+
     # Run KSP2 via dedicated worker (separate from kotlinc worker)
     # Single action: staging + KSP2 + packaging all happen in the worker
     ctx.actions.run(
@@ -736,6 +741,7 @@ def _kt_jvm_produce_output_jar_actions(
 
     annotation_processors = _plugin_mappers.targets_to_annotation_processors(ctx.attr.plugins + ctx.attr.deps)
     ksp_annotation_processors = _plugin_mappers.targets_to_ksp_annotation_processors(ctx.attr.plugins + ctx.attr.deps)
+    ksp_options = _plugin_mappers.targets_to_ksp_options(ctx.attr.plugins + ctx.attr.deps)
     transitive_runtime_jars = _plugin_mappers.targets_to_transitive_runtime_jars(ctx.attr.plugins + ctx.attr.deps)
     plugins = _new_plugins_from(ctx.attr.plugins + _exported_plugins(deps = ctx.attr.deps))
 
@@ -759,6 +765,7 @@ def _kt_jvm_produce_output_jar_actions(
         deps_artifacts = deps_artifacts,
         annotation_processors = annotation_processors,
         ksp_annotation_processors = ksp_annotation_processors,
+        ksp_options = ksp_options,
         transitive_runtime_jars = transitive_runtime_jars,
         plugins = plugins,
         compile_jar = compile_jar,
@@ -863,6 +870,7 @@ def _run_kt_java_builder_actions(
         deps_artifacts,
         annotation_processors,
         ksp_annotation_processors,
+        ksp_options,
         transitive_runtime_jars,
         plugins,
         compile_jar,
@@ -910,6 +918,7 @@ def _run_kt_java_builder_actions(
             srcs = srcs,
             compile_deps = compile_deps,
             transitive_runtime_jars = transitive_runtime_jars,
+            ksp_options = ksp_options,
         )
         ksp_generated_class_jar = ksp_outputs.ksp_generated_class_jar
         output_jars.append(ksp_generated_class_jar)

kotlin/internal/jvm/impl.bzl

@@ -596,5 +596,6 @@ def kt_ksp_plugin_impl(ctx):
                 ),
             ],
             generates_java = ctx.attr.generates_java,
+            options = ctx.attr.options,
         ),
     ]

kotlin/internal/jvm/jvm.bzl

@@ -678,6 +678,11 @@ kt_jvm_library(
             doc = """Runs Java compilation action for plugin generating Java output.""",
             default = False,
         ),
+        "options": attr.string_dict(
+            doc = """Processor options passed to the KSP processor via SymbolProcessorEnvironment.options.
+            Each entry is a key-value pair available to the processor at processing time.""",
+            default = {},
+        ),
         "processor_class": attr.string(
             doc = " The fully qualified class name that the Java compiler uses as an entry point to the annotation processor.",
             mandatory = True,

kotlin/internal/jvm/plugins.bzl

@@ -60,6 +60,16 @@ def _targets_to_ksp_annotation_processors(targets):
 def _targets_to_annotation_processors_java_plugin_info(targets):
     return [t[JavaPluginInfo] for t in targets if JavaPluginInfo in t]
 
+def _targets_to_ksp_options(targets):
+    options = {}
+    for t in targets:
+        if _KspPluginInfo in t:
+            for key, value in t[_KspPluginInfo].options.items():
+                if key in options:
+                    fail("Conflicting KSP option key '%s': defined in multiple plugins" % key)
+                options[key] = value
+    return options
+
 def _targets_to_transitive_runtime_jars(targets):
     transitive = []
     for t in targets:
@@ -74,6 +84,7 @@ def _targets_to_transitive_runtime_jars(targets):
 mappers = struct(
     targets_to_annotation_processors = _targets_to_annotation_processors,
     targets_to_ksp_annotation_processors = _targets_to_ksp_annotation_processors,
+    targets_to_ksp_options = _targets_to_ksp_options,
     targets_to_annotation_processors_java_plugin_info = _targets_to_annotation_processors_java_plugin_info,
     targets_to_transitive_runtime_jars = _targets_to_transitive_runtime_jars,
     kt_plugin_to_processor = _kt_plugin_to_processor,

src/main/kotlin/io/bazel/kotlin/builder/tasks/jvm/Ksp2Task.kt

@@ -65,7 +65,14 @@ class Ksp2Task : Work {
       API_VERSION("--api_version"),
       JVM_TARGET("--jvm_target"),
       JDK_HOME("--jdk_home"),
+      KSP_OPTIONS("--ksp_options"),
     }
+
+    fun parseKspOptions(entries: List<String>): Map<String, String> =
+      entries.associate { entry ->
+        val eqIdx = entry.indexOf('=')
+        if (eqIdx >= 0) entry.substring(0, eqIdx) to entry.substring(eqIdx + 1) else entry to ""
+      }
   }
 
   override fun invoke(
@@ -172,6 +179,8 @@ class Ksp2Task : Work {
       val processorUrls = processorClasspath.map { File(it).toURI().toURL() }.toTypedArray()
       val kspClassLoader = URLClassLoader(processorUrls, ClassLoader.getSystemClassLoader())
 
+      val processorOptions = parseKspOptions(argMap.optional(Ksp2Flags.KSP_OPTIONS) ?: emptyList())
+
       // Load Ksp2Invoker via reflection (it's compiled against KSP2 classes)
       val invokerClass = kspClassLoader.loadClass("io.bazel.kotlin.ksp2.Ksp2Invoker")
       val invoker =
@@ -196,6 +205,7 @@ class Ksp2Task : Work {
           String::class.java, // languageVersion
           String::class.java, // apiVersion
           File::class.java, // jdkHome
+          Map::class.java, // processorOptions
           Int::class.java, // logLevel
         )
 
@@ -218,6 +228,7 @@ class Ksp2Task : Work {
           argMap.optionalSingle(Ksp2Flags.LANGUAGE_VERSION),
           argMap.optionalSingle(Ksp2Flags.API_VERSION),
           argMap.optionalSingle(Ksp2Flags.JDK_HOME)?.let { File(it) },
+          processorOptions,
           1, // logLevel
         ) as Int
 

src/main/kotlin/io/bazel/kotlin/ksp2/Ksp2Invoker.kt

@@ -55,6 +55,7 @@ class Ksp2Invoker(
     languageVersion: String?,
     apiVersion: String?,
     jdkHome: File?,
+    processorOptions: Map<String, String> = emptyMap(),
     logLevel: Int = 1,
   ): Int {
     // Load processors via ServiceLoader from the provided classloader
@@ -81,6 +82,7 @@ class Ksp2Invoker(
           languageVersion?.let { this.languageVersion = it }
           apiVersion?.let { this.apiVersion = it }
           jdkHome?.let { this.jdkHome = it }
+          this.processorOptions = processorOptions
           this.mapAnnotationArgumentsInJava = true
         }.build()
 

src/main/starlark/core/plugin/providers.bzl

@@ -31,6 +31,7 @@ KtPluginConfiguration = provider(
 KspPluginInfo = provider(
     fields = {
         "generates_java": "Runs Java compilation action for this plugin",
+        "options": "Dict of processor options (key-value strings) passed to KSP via environment.options",
         "plugins": "List of JavaPluginInfo providers for the plugins to run with KSP",
     },
 )

src/test/data/jvm/ksp/optionsrecorder/BUILD.bazel

@@ -0,0 +1,49 @@
+load("//kotlin:core.bzl", "kt_ksp_plugin")
+load("//kotlin:jvm.bzl", "kt_jvm_library", "kt_jvm_test")
+
+package(default_visibility = ["//visibility:private"])
+
+# The processor itself
+kt_jvm_library(
+    name = "options_recorder_processor",
+    srcs = [
+        "OptionsRecorderProcessor.kt",
+        "OptionsRecorderProcessorProvider.kt",
+    ],
+    resource_strip_prefix = "src/test/data/jvm/ksp/optionsrecorder/resources",
+    resources = glob(["resources/META-INF/services/*"]),
+    deps = [
+        "//kotlin/compiler:symbol-processing-api",
+    ],
+)
+
+# KSP plugin with the test options
+kt_ksp_plugin(
+    name = "options_recorder_plugin",
+    options = {
+        "option_a": "value_a",
+        "option_b": "value_b",
+    },
+    processor_class = "com.example.optionsrecorder.OptionsRecorderProcessorProvider",
+    deps = [":options_recorder_processor"],
+)
+
+# Library compiled with the plugin — KSP generates generated.RecordedOptions
+kt_jvm_library(
+    name = "options_recorder_lib",
+    srcs = ["Subject.kt"],
+    plugins = [":options_recorder_plugin"],
+)
+
+# Integration test: verifies the processor actually received the options
+kt_jvm_test(
+    name = "OptionsRecorderTest",
+    srcs = ["OptionsRecorderTest.kt"],
+    test_class = "com.example.optionsrecorder.OptionsRecorderTest",
+    visibility = ["//src/test:__subpackages__"],
+    deps = [
+        ":options_recorder_lib",
+        "@kotlin_rules_maven//:com_google_truth_truth",
+        "@kotlin_rules_maven//:junit_junit",
+    ],
+)

src/test/data/jvm/ksp/optionsrecorder/OptionsRecorderProcessor.kt

@@ -0,0 +1,40 @@
+package com.example.optionsrecorder
+
+import com.google.devtools.ksp.processing.CodeGenerator
+import com.google.devtools.ksp.processing.Dependencies
+import com.google.devtools.ksp.processing.Resolver
+import com.google.devtools.ksp.processing.SymbolProcessor
+import com.google.devtools.ksp.symbol.KSAnnotated
+
+/**
+ * A minimal KSP processor that writes the options it received into a generated Kotlin file.
+ * Used by integration tests to verify that options are passed through correctly.
+ */
+class OptionsRecorderProcessor(
+    private val codeGenerator: CodeGenerator,
+    private val options: Map<String, String>,
+) : SymbolProcessor {
+    private var done = false
+
+    override fun process(resolver: Resolver): List<KSAnnotated> {
+        if (done) return emptyList()
+        done = true
+
+        val file = codeGenerator.createNewFile(
+            dependencies = Dependencies(false),
+            packageName = "generated",
+            fileName = "RecordedOptions",
+        )
+        file.bufferedWriter().use { writer ->
+            writer.write("package generated\n\n")
+            writer.write("object RecordedOptions {\n")
+            writer.write("    val options: Map<String, String> = mapOf(\n")
+            options.forEach { (k, v) ->
+                writer.write("        \"$k\" to \"$v\",\n")
+            }
+            writer.write("    )\n")
+            writer.write("}\n")
+        }
+        return emptyList()
+    }
+}