First-class support for Kotlin compiler plugins (com-lihaoyi#4779)

Fix com-lihaoyi#4776

This introduces multiple new tasks, analog to the ones in `ScalaModule`.

* `kotlincPluginIvyDeps` - Dependencies resembling compiler plugins
* `kotlincPluginJars` - The coursier-resolved jars of the compiler
plugins; resolved intransitively; also usable to add plugins not
available via coursier/Maven
* `mandatoryKotlincOptions` - compiler options derived from other module
settings, like Kotlin versions and compiler plugin enablement
* `allKotlincOptions` - all compiler options

Revised the existing modules and used the new tasks to provide Kotlin
compiler plugins and their configuration. Removed `composeProcessor` and
`kotestProcessor` tasks.

Also added some comments for stuff that need further work like
hard-coded versions.

Pull request: com-lihaoyi#4779

Author: lefou

example/kotlinlib/basic/1-simple/build.mill

@@ -70,17 +70,14 @@ foo.run
 foo.compile(KotlinModule...)
     Compiles all the sources to JVM class files.
     Compiles the current module to generate compiled classfiles/bytecode.
-    When you override this, you probably also want/need to override [[bspCompileClassesPath]],
-    as that needs to point to the same compilation output path.
-    Keep in sync with [[bspCompileClassesPath]]
 Inputs:
     foo.allJavaSourceFiles
     foo.allKotlinSourceFiles
     foo.compileClasspath
     foo.upstreamCompileOutput
     foo.javacOptions
     foo.zincReportCachedProblems
-    foo.kotlincOptions
+    foo.allKotlincOptions
     foo.kotlinCompilerClasspath
 ...
 

example/kotlinlib/basic/6-realistic/build.mill

@@ -55,7 +55,7 @@ object qux extends MyModule {
 
 // A semi-realistic build setup, combining all the individual Mill concepts:
 //
-// - Three `KotlinModule`s that depend on each other
+// - Three ``KotlinModule``s that depend on each other
 //
 // - With unit testing and publishing set up
 //
@@ -65,9 +65,10 @@ object qux extends MyModule {
 // Note that for multi-module builds like this, using using xref:cli/query-syntax.adoc[queries] to run tasks on
 // multiple modules at once can be very convenient:
 //
+// [source,sh]
 // ----
-// __.test
-// __.publishLocal
+// > mill __.test
+// > mill __.publishLocal
 // ----
 //
 // Also note how you can use ``trait``s to bundle together common combinations of

kotlinlib/src/mill/kotlinlib/KotlinMavenModule.scala

@@ -7,23 +7,13 @@ import mill.javalib.MavenModule
  * A [[KotlinModule]] with a Maven compatible directory layout.
  */
 trait KotlinMavenModule extends KotlinModule with MavenModule {
-  override def sources = Task.Sources(
-    "src/main/java",
-    "src/main/kotlin"
-  )
-  override def resources = Task.Sources {
-    "src/main/resources"
-  }
+  private def sources0 = Task.Sources("src/main/kotlin")
+  override def sources = super.sources() ++ sources0()
 
   trait KotlinMavenTests extends KotlinTests with MavenTests {
     override def intellijModulePath: os.Path = moduleDir / "src/test"
 
-    override def sources = Task.Sources(
-      "src/test/java",
-      "src/test/kotlin"
-    )
-    override def resources = Task.Sources {
-      "src/test/resources"
-    }
+    private def sources0 = Task.Sources("src/test/kotlin")
+    override def sources = super.sources() ++ sources0()
   }
 }

kotlinlib/src/mill/kotlinlib/KotlinModule.scala

@@ -61,7 +61,9 @@ trait KotlinModule extends JavaModule { outer =>
   /**
    * The version of the Kotlin compiler to be used.
    * Default is derived from [[kotlinVersion]].
+   * This is deprecated, as it's identical to [[kotlinVersion]]
    */
+  @deprecated("Use kotlinVersion instead", "Mill 0.13.0-M1")
   def kotlinCompilerVersion: T[String] = Task { kotlinVersion() }
 
   /**
@@ -153,6 +155,23 @@ trait KotlinModule extends JavaModule { outer =>
       )
   }
 
+  /**
+   * Compiler Plugin dependencies.
+   */
+  def kotlincPluginIvyDeps: T[Seq[Dep]] = Task { Seq.empty[Dep] }
+
+  /**
+   * The resolved plugin jars
+   */
+  def kotlincPluginJars: T[Seq[PathRef]] = Task {
+    val jars = defaultResolver().resolveDeps(
+      kotlincPluginIvyDeps()
+        // Don't resolve transitive jars
+        .map(d => d.exclude("*" -> "*"))
+    )
+    jars.toSeq
+  }
+
   def kotlinWorkerTask: Task[KotlinWorker] = Task.Anon {
     kotlinWorkerRef().kotlinWorkerManager().get(kotlinCompilerClasspath())
   }
@@ -321,7 +340,7 @@ trait KotlinModule extends JavaModule { outer =>
           when(kotlinExplicitApi())(
             "-Xexplicit-api=strict"
           ),
-          kotlincOptions(),
+          allKotlincOptions(),
           extraKotlinArgs,
           // parameters
           (kotlinSourceFiles ++ javaSourceFiles).map(_.toString())
@@ -353,20 +372,29 @@ trait KotlinModule extends JavaModule { outer =>
   /**
    * Additional Kotlin compiler options to be used by [[compile]].
    */
-  def kotlincOptions: T[Seq[String]] = Task {
-    val options = Seq.newBuilder[String]
-    options += "-no-stdlib"
+  def kotlincOptions: T[Seq[String]] = Task { Seq.empty[String] }
+
+  /**
+   * Mandatory command-line options to pass to the Kotlin compiler
+   * that shouldn't be removed by overriding `scalacOptions`
+   */
+  protected def mandatoryKotlincOptions: T[Seq[String]] = Task {
     val languageVersion = kotlinLanguageVersion()
-    if (!languageVersion.isBlank) {
-      options += "-language-version"
-      options += languageVersion
-    }
     val kotlinkotlinApiVersion = kotlinApiVersion()
-    if (!kotlinkotlinApiVersion.isBlank) {
-      options += "-api-version"
-      options += kotlinkotlinApiVersion
-    }
-    options.result()
+    val plugins = kotlincPluginJars().map(_.path)
+
+    Seq("-no-stdlib") ++
+      when(!languageVersion.isBlank)("-language-version", languageVersion) ++
+      when(!kotlinkotlinApiVersion.isBlank)("-api-version", kotlinkotlinApiVersion) ++
+      plugins.map(p => s"-Xplugin=$p")
+  }
+
+  /**
+   * Aggregation of all the options passed to the Kotlin compiler.
+   * In most cases, instead of overriding this Target you want to override `kotlincOptions` instead.
+   */
+  def allKotlincOptions: T[Seq[String]] = Task {
+    mandatoryKotlincOptions() ++ kotlincOptions()
   }
 
   private[kotlinlib] def internalCompileJavaFiles(
@@ -408,12 +436,15 @@ trait KotlinModule extends JavaModule { outer =>
     override def kotlinExplicitApi: T[Boolean] = false
     override def kotlinVersion: T[String] = Task { outer.kotlinVersion() }
     override def kotlinCompilerVersion: T[String] = Task { outer.kotlinCompilerVersion() }
+    override def kotlincPluginIvyDeps: T[Seq[Dep]] =
+      Task { outer.kotlincPluginIvyDeps() }
+      // TODO: make Xfriend-path an explicit setting
     override def kotlincOptions: T[Seq[String]] = Task {
       outer.kotlincOptions().filterNot(_.startsWith("-Xcommon-sources")) ++
         Seq(s"-Xfriend-paths=${outer.compile().classes.path.toString()}")
     }
-
-    override def kotlinCompilerEmbeddable: Task[Boolean] = outer.kotlinCompilerEmbeddable
+    override def kotlinCompilerEmbeddable: Task[Boolean] =
+      Task.Anon { outer.kotlinCompilerEmbeddable() }
   }
 
 }

kotlinlib/src/mill/kotlinlib/android/AndroidAppKotlinModule.scala

@@ -54,26 +54,25 @@ trait AndroidAppKotlinModule extends AndroidAppModule with AndroidKotlinModule {
     /* There are no testclasses for screenshot tests, just the engine running a diff over the images */
     override def discoveredTestClasses: T[Seq[String]] = Task { Seq.empty[String] }
 
-    override def mapDependencies: Task[Dependency => Dependency] = outer.mapDependencies
+    override def mapDependencies: Task[Dependency => Dependency] =
+      Task.Anon(outer.mapDependencies())
 
-    override def androidCompileSdk: T[Int] = outer.androidCompileSdk
+    override def androidCompileSdk: T[Int] = outer.androidCompileSdk()
 
-    override def androidMergedManifest: T[PathRef] = outer.androidMergedManifest
+    override def androidMergedManifest: T[PathRef] = outer.androidMergedManifest()
 
     override def androidSdkModule: ModuleRef[AndroidSdkModule] = outer.androidSdkModule
 
+    // FIXME: avoid hardcoded version
     def layoutLibVersion: String = "14.0.9"
+    // FIXME: avoid hardcoded version
     def composePreviewRendererVersion: String = "0.0.1-alpha08"
 
     def namespace: String
 
     override def moduleDeps: Seq[JavaModule] = Seq(outer)
 
-    override final def kotlinVersion = outer.kotlinVersion
-
-    override def kotlincOptions = super.kotlincOptions() ++ Seq(
-      s"-Xplugin=${composeProcessor().path}"
-    )
+    override final def kotlinVersion = outer.kotlinVersion()
 
     override def sources: T[Seq[PathRef]] = Task.Sources(
       outer.moduleDir / "src/screenshotTest/kotlin",
@@ -125,6 +124,7 @@ trait AndroidAppKotlinModule extends AndroidAppModule with AndroidKotlinModule {
       PathRef(extractDestination)
     }
 
+    // FIXME: avoid hardcoded version
     def uiToolingVersion: String = "1.7.6"
 
     /*

kotlinlib/src/mill/kotlinlib/android/AndroidKotlinModule.scala

@@ -1,35 +1,33 @@
 package mill.kotlinlib.android
 
 import mill.{T, Task}
-import mill.api.PathRef
-import mill.kotlinlib.{DepSyntax, KotlinModule}
+import mill.api.Result
+import mill.kotlinlib.{Dep, DepSyntax, KotlinModule}
 
+// TODO expose Compose configuration options
+// https://kotlinlang.org/docs/compose-compiler-options.html possible options
 trait AndroidKotlinModule extends KotlinModule {
 
-  override def kotlincOptions = super.kotlincOptions() ++ {
-    if (androidEnableCompose()) {
-      Seq(
-        // TODO expose Compose configuration options
-        // https://kotlinlang.org/docs/compose-compiler-options.html possible options
-        s"-Xplugin=${composeProcessor().path}"
-      )
-    } else Seq.empty
-  }
-
   /**
    * Enable Jetpack Compose support in the module. Default is `false`.
    */
   def androidEnableCompose: T[Boolean] = false
 
-  def composeProcessor = Task {
-    // cut-off usages for Kotlin 1.x, because of the need to maintain the table of
-    // Compose compiler version -> Kotlin version
-    if (kotlinVersion().startsWith("1"))
-      throw new IllegalStateException("Compose can be used only with Kotlin version 2 or newer.")
-    defaultResolver().resolveDeps(
-      Seq(
-        ivy"org.jetbrains.kotlin:kotlin-compose-compiler-plugin:${kotlinVersion()}"
-      )
-    ).head
+  override def kotlincPluginIvyDeps: T[Seq[Dep]] = Task {
+    val kv = kotlinVersion()
+
+    val deps = super.kotlincPluginIvyDeps()
+
+    if (androidEnableCompose()) {
+      if (kv.startsWith("1")) {
+        // cut-off usages for Kotlin 1.x, because of the need to maintain the table of
+        // Compose compiler version -> Kotlin version
+        Result.Failure("Compose can be used only with Kotlin version 2 or newer.")
+      } else {
+        Result.Success(deps ++ Seq(
+          ivy"org.jetbrains.kotlin:kotlin-compose-compiler-plugin:${kotlinVersion()}"
+        ))
+      }
+    } else Result.Success(deps)
   }
 }

kotlinlib/src/mill/kotlinlib/js/KotlinJsModule.scala

@@ -25,9 +25,11 @@ trait KotlinJsModule extends KotlinModule { outer =>
   // region Kotlin/JS configuration
 
   /** The kind of JS module generated by the compiler */
+  // FIXME: Rename to kotlinKsModuleKind
   def moduleKind: T[ModuleKind] = ModuleKind.PlainModule
 
   /** Call main function upon execution. */
+  // FIXME: Rename to kotlinJsCallMain
   def callMain: T[Boolean] = true
 
   /** Binary type (if any) to produce. If [[BinaryKind.Executable]] is selected, then .js file(s) will be produced. */
@@ -49,6 +51,7 @@ trait KotlinJsModule extends KotlinModule { outer =>
   def kotlinJsSourceMapNamesPolicy: T[SourceMapNamesPolicy] = SourceMapNamesPolicy.No
 
   /** Split generated .js per-module. Effective only if [[BinaryKind.Executable]] is selected. */
+  // FIXME: rename to kotlinJsSplitPerModule
   def splitPerModule: T[Boolean] = true
 
   /** Run target for the executable (if [[BinaryKind.Executable]] is set). */
@@ -100,7 +103,7 @@ trait KotlinJsModule extends KotlinModule { outer =>
       destinationRoot = Task.dest,
       artifactId = artifactId(),
       explicitApi = kotlinExplicitApi(),
-      extraKotlinArgs = kotlincOptions(),
+      extraKotlinArgs = allKotlincOptions(),
       worker = kotlinWorkerTask()
     )
   }
@@ -200,7 +203,7 @@ trait KotlinJsModule extends KotlinModule { outer =>
       destinationRoot = Task.dest,
       artifactId = artifactId(),
       explicitApi = kotlinExplicitApi(),
-      extraKotlinArgs = kotlincOptions() ++ extraKotlinArgs,
+      extraKotlinArgs = allKotlincOptions() ++ extraKotlinArgs,
       worker = kotlinWorkerTask()
     )
   }
@@ -227,7 +230,7 @@ trait KotlinJsModule extends KotlinModule { outer =>
       destinationRoot = Task.dest,
       artifactId = artifactId(),
       explicitApi = kotlinExplicitApi(),
-      extraKotlinArgs = kotlincOptions(),
+      extraKotlinArgs = allKotlincOptions(),
       worker = kotlinWorkerTask()
     )
   }
@@ -670,7 +673,7 @@ trait KotlinJsModule extends KotlinModule { outer =>
    * Run tests for Kotlin/JS target using `kotlin.test` package.
    */
   trait KotlinTestPackageTests extends KotlinJsTests {
-    override def ivyDeps = Seq(
+    override def ivyDeps = super.ivyDeps() ++ Seq(
       ivy"org.jetbrains.kotlin:kotlin-test-js:${kotlinVersion()}"
     )
   }
@@ -680,21 +683,15 @@ trait KotlinJsModule extends KotlinModule { outer =>
    */
   trait KotestTests extends KotlinJsTests {
 
+    // FIXME: get this version from Mill build info
     def kotestVersion: T[String] = "5.9.1"
 
-    private def kotestProcessor = Task {
-      defaultResolver().resolveDeps(
-        Seq(
-          ivy"io.kotest:kotest-framework-multiplatform-plugin-embeddable-compiler-jvm:${kotestVersion()}"
-        )
-      ).head
-    }
-
-    override def kotlincOptions = super.kotlincOptions() ++ Seq(
-      s"-Xplugin=${kotestProcessor().path}"
-    )
+    override def kotlincPluginIvyDeps: T[Seq[Dep]] =
+      super.kotlincPluginIvyDeps() ++ Seq(
+        ivy"io.kotest:kotest-framework-multiplatform-plugin-embeddable-compiler-jvm:${kotestVersion()}"
+      )
 
-    override def ivyDeps = Seq(
+    override def ivyDeps = super.ivyDeps() ++ Seq(
       ivy"io.kotest:kotest-framework-engine-js:${kotestVersion()}",
       ivy"io.kotest:kotest-assertions-core-js:${kotestVersion()}"
     )

kotlinlib/src/mill/kotlinlib/ksp/KspModule.scala

@@ -130,7 +130,7 @@ trait KspModule extends KotlinModule { outer =>
         "-classpath",
         compileCp.iterator.mkString(File.pathSeparator)
       ),
-      kotlincOptions(),
+      allKotlincOptions(),
       kspCompilerArgs,
       // parameters
       sourceFiles.map(_.toString())

kotlinlib/test/src/mill/kotlinlib/js/KotlinJsKotestModuleTests.scala

@@ -9,18 +9,17 @@ import utest.{TestSuite, Tests, assert, test}
 
 object KotlinJsKotestModuleTests extends TestSuite {
 
-  private val resourcePath = os.Path(sys.env("MILL_TEST_RESOURCE_DIR")) / "kotlin-js"
-
-  private val kotlinVersion = "1.9.25"
+  private val testResourcePath = os.Path(sys.env("MILL_TEST_RESOURCE_DIR")) / "kotlin-js"
+  private val testKotlinVersion = "1.9.25"
 
   object module extends TestBaseModule {
 
     object bar extends KotlinJsModule {
-      def kotlinVersion = KotlinJsKotestModuleTests.kotlinVersion
+      def kotlinVersion = testKotlinVersion
     }
 
     object foo extends KotlinJsModule {
-      def kotlinVersion = KotlinJsKotestModuleTests.kotlinVersion
+      def kotlinVersion = testKotlinVersion
       override def kotlinJsRunTarget = Some(RunTarget.Node)
       override def moduleDeps = Seq(module.bar)
 
@@ -33,7 +32,7 @@ object KotlinJsKotestModuleTests extends TestSuite {
     lazy val millDiscover = Discover[this.type]
   }
 
-  private def testEval() = UnitTester(module, resourcePath)
+  private def testEval() = UnitTester(module, testResourcePath)
 
   def tests: Tests = Tests {