Kotlin Module Configuration

This page goes into more detail about the various configuration options for KotlinModule.

Many of the APIs covered here are listed in the API documentation:

mill.kotlinlib.KotlinModule

Common Configuration Overrides

This example shows some of the common tasks you may want to override on a {language}Module: specifying the mainClass, adding additional sources/resources, generating resources, and setting compilation/run options.

build.mill (download, browse)

package build
import mill._, kotlinlib._

object `package` extends RootModule with KotlinModule {
  // You can have arbitrary numbers of third-party dependencies
  def ivyDeps = Agg(
    ivy"org.jetbrains.kotlinx:kotlinx-html-jvm:0.11.0"
  )

  def kotlinVersion = "1.9.24"

  // Choose a main class to use for `.run` if there are multiple present
  def mainClass = Some("foo.Foo2Kt")

  // Add (or replace) source folders for the module to use
  def sources = T.sources{
    super.sources() ++ Seq(PathRef(millSourcePath / "custom-src"))
  }

  // Add (or replace) resource folders for the module to use
  def resources = T.sources{
    super.resources() ++ Seq(PathRef(millSourcePath / "custom-resources"))
  }

  // Generate sources at build time
  def generatedSources: T[Seq[PathRef]] = Task {
    for(name <- Seq("A", "B", "C")) os.write(
      T.dest / s"Foo$name.kt",
      s"""
package foo

object Foo$name {
  val VALUE: String = "hello $name"
}
      """.stripMargin
    )

    Seq(PathRef(T.dest))
  }

  // Pass additional JVM flags when `.run` is called or in the executable
  // generated by `.assembly`
  def forkArgs: T[Seq[String]] = Seq("-Dmy.custom.property=my-prop-value")

  // Pass additional environmental variables when `.run` is called. Note that
  // this does not apply to running externally via `.assembly
  def forkEnv: T[Map[String, String]] = Map("MY_CUSTOM_ENV" -> "my-env-value")
}

If you want to better understand how the various upstream tasks feed into a task of interest, such as run, you can visualize their relationships via

> mill visualizePlan run

(right-click open in new tab to see full sized)

Note the use of millSourcePath, Task.dest, and PathRef when preforming various filesystem operations:

millSourcePath refers to the base path of the module. For the root module, this is the root of the repo, and for inner modules it would be the module path e.g. for module foo.bar.qux the millSourcePath would be foo/bar/qux. This can also be overriden if necessary
Task.dest refers to the destination folder for a task in the out/ folder. This is unique to each task, and can act as both a scratch space for temporary computations as well as a place to put "output" files, without worrying about filesystem conflicts with other tasks
PathRef is a way to return the contents of a file or folder, rather than just its path as a string. This ensures that downstream tasks properly invalidate when the contents changes even when the path stays the same

> mill run
Foo2.value: <h1>hello2</h1>
Foo.value: <h1>hello</h1>
FooA.value: hello A
FooB.value: hello B
FooC.value: hello C
MyResource: My Resource Contents
MyOtherResource: My Other Resource Contents
my.custom.property: my-prop-value
MY_CUSTOM_ENV: my-env-value

> mill show assembly
".../out/assembly.dest/out.jar"

> ./out/assembly.dest/out.jar # mac/linux
Foo2.value: <h1>hello2</h1>
Foo.value: <h1>hello</h1>
FooA.value: hello A
FooB.value: hello B
FooC.value: hello C
MyResource: My Resource Contents
MyOtherResource: My Other Resource Contents
my.custom.property: my-prop-value

Custom Tasks

This example shows how to define task that depend on other tasks:

For generatedSources, we override an the task and make it depend directly on ivyDeps to generate its source files. In this example, to include the list of dependencies as tuples within a static object
For lineCount, we define a brand new task that depends on sources, and then override forkArgs to use it. That lets us access the line count at runtime using sys.props and print it when the program runs

build.mill (download, browse)

package build
import mill._, kotlinlib._

object `package` extends RootModule with KotlinModule {

  def kotlinVersion = "1.9.24"

  def mainClass = Some("foo.FooKt")

  def ivyDeps = Agg(ivy"com.github.ajalt.clikt:clikt-jvm:4.4.0")

  def generatedSources: T[Seq[PathRef]] = Task {
    val prettyIvyDeps = for(ivyDep <- ivyDeps()) yield {
      val org = ivyDep.dep.module.organization.value
      val name = ivyDep.dep.module.name.value
      val version = ivyDep.dep.version
      s""" "$org:$name:$version" """
    }
    val ivyDepsString = prettyIvyDeps.mkString(" + \"\\n\" + \n")
    os.write(
      T.dest / s"MyDeps.kt",
      s"""
package foo

object MyDeps {
  const val VALUE = $ivyDepsString;
}
      """.stripMargin
    )

    Seq(PathRef(T.dest))
  }

  def lineCount: T[Int] = Task {
    sources()
      .flatMap(pathRef => os.walk(pathRef.path))
      .filter(_.ext == "kt")
      .map(os.read.lines(_).size)
      .sum
  }

  def forkArgs: T[Seq[String]] = Seq(s"-Dmy.line.count=${lineCount()}")

  def printLineCount() = T.command { println(lineCount()) }
}

The above build defines the customizations to the Mill task graph shown below, with the boxes representing tasks defined or overriden above and the un-boxed labels representing existing Mill tasks:

Mill lets you define new cached Tasks using the Task {…} syntax, depending on existing Tasks e.g. foo.sources via the foo.sources() syntax to extract their current value, as shown in lineCount above. The return-type of a Task has to be JSON-serializable (using uPickle, one of Mill’s [Bundled Libraries]) and the Task is cached when first run until its inputs change (in this case, if someone edits the foo.sources files which live in foo/src. Cached Tasks cannot take parameters.

Note that depending on a task requires use of parentheses after the task name, e.g. ivyDeps(), sources() and lineCount(). This converts the task of type T[V] into a value of type V you can make use in your task implementation.

This example can be run as follows:

> mill run --text hello
text: hello
MyDeps.value: com.github.ajalt.clikt:clikt-jvm:4.4.0
my.line.count: 17

> mill show lineCount
17

> mill printLineCount
17

Custom tasks can contain arbitrary code. Whether you want to download files using requests.get, shell-out to Webpack to compile some Javascript, generate sources to feed into a compiler, or create some custom jar/zip assembly with the files you want , all of these can simply be custom tasks with your code running in the Task {…} block.

You can create arbitrarily long chains of dependent tasks, and Mill will handle the re-evaluation and caching of the tasks' output for you. Mill also provides you a Task.dest folder for you to use as scratch space or to store files you want to return: all files a task creates should live within Task.dest, and any files you want to modify should be copied into Task.dest before being modified. That ensures that the files belonging to a particular task all live in one place, avoiding file-name conflicts and letting Mill automatically invalidate the files when the task’s inputs change.

Overriding Tasks

build.mill (download, browse)

package build
import mill._, kotlinlib._

object foo extends KotlinModule {

  def kotlinVersion = "1.9.24"

  def mainClass = Some("foo.FooKt")

  def sources = Task {
    os.write(
      T.dest / "Foo.kt",
      """package foo

fun main() = println("Hello World")
      """.stripMargin
    )
    Seq(PathRef(T.dest))
  }

  def compile = Task {
    println("Compiling...")
    super.compile()
  }

  def run(args: Task[Args] = T.task(Args())) = T.command {
    println("Running..." + args().value.mkString(" "))
    super.run(args)()
  }
}

You can re-define tasks to override them, and use super if you want to refer to the originally defined task. The above example shows how to override compile and run to add additional logging messages, and we override sources which was Task.Sources for the src/ folder with a plain T{…} task that generates the necessary source files on-the-fly.

Note that this example replaces your src/ folder with the generated sources. If you want to add generated sources, you can either override generatedSources, or you can override sources and use super to include the original source folder:

object foo2 extends KotlinModule {

  def kotlinVersion = "1.9.24"

  def generatedSources = Task {
    os.write(T.dest / "Foo.kt", """...""")
    Seq(PathRef(T.dest))
  }
}

object foo3 extends KotlinModule {

  def kotlinVersion = "1.9.24"

  def sources = Task {
    os.write(T.dest / "Foo.kt", """...""")
    super.sources() ++ Seq(PathRef(T.dest))
  }
}

In Mill builds the override keyword is optional.

> mill foo.run
Compiling...
Running...
Hello World

Compilation & Execution Flags

build.mill (download, browse)

package build
import mill._, kotlinlib._

object `package` extends RootModule with KotlinModule {

  def kotlinVersion = "1.9.24"

  def mainClass = Some("foo.FooKt")

  def forkArgs = Seq("-Xmx4g", "-Dmy.jvm.property=hello")
  def forkEnv = Map("MY_ENV_VAR" -> "WORLD")

  def kotlincOptions = super.kotlincOptions() ++ Seq("-Werror")
}

You can pass flags to the Kotlin compiler via kotlincOptions.

> ./mill run
hello WORLD

> echo 'fun deprecatedMain(){Thread.currentThread().stop()}' >> src/foo/Foo.kt

> ./mill run
error: .../src/foo/Foo.kt:...: warning: 'stop(): Unit' is deprecated. Deprecated in Java

By default, run runs the compiled code in a subprocess, and you can pass in JVM flags via forkArgs or environment-variables via forkEnv.

You can also run your code via

mill foo.runLocal

Which runs it in-process within an isolated classloader. This may be faster since you avoid the JVM startup, but does not support forkArgs or forkEnv.

If you want to pass main-method arguments to run or runLocal, simply pass them after the foo.run/foo.runLocal:

mill foo.run arg1 arg2 arg3
mill foo.runLocal arg1 arg2 arg3

Classpath and Filesystem Resources

build.mill (download, browse)

package build
import mill._, kotlinlib._

object foo extends KotlinModule {

  def kotlinVersion = "1.9.24"

  object test extends KotlinTests with TestModule.Junit5 {
    def otherFiles = T.source(millSourcePath / "other-files")

    def forkEnv = super.forkEnv() ++ Map(
      "OTHER_FILES_DIR" -> otherFiles().path.toString
    )

    def ivyDeps = super.ivyDeps() ++ Agg(
      ivy"io.kotest:kotest-runner-junit5-jvm:5.9.1"
    )
  }
}

> ./mill foo.test
... foo.FooTests...simple ...
...

This section discusses how tests can depend on resources locally on disk. Mill provides two ways to do this: via the JVM classpath resources, and via the resource folder which is made available as the environment variable MILL_TEST_RESOURCE_DIR;

The classpath resources are useful when you want to fetch individual files, and are bundled with the application by the .assembly step when constructing an assembly jar for deployment. But they do not allow you to list folders or perform other filesystem operations.
The resource folder, available via MILL_TEST_RESOURCE_DIR, gives you access to the folder path of the resources on disk. This is useful in allowing you to list and otherwise manipulate the filesystem, which you cannot do with classpath resources. However, the MILL_TEST_RESOURCE_DIR only exists when running tests using Mill, and is not available when executing applications packaged for deployment via .assembly
Apart from resources/, you can provide additional folders to your test suite by defining a Task.Source (otherFiles above) and passing it to forkEnv. This provide the folder path as an environment variable that the test can make use of

Example application code demonstrating the techniques above can be seen below:

foo/test/resources/test-file-a.txt (browse)

Test Hello World Resource File A

foo/test/resources/test-file-b.txt (browse)

Test Hello World Resource File B

foo/test/other-files/other-file.txt (browse)

Other Hello World File

foo/src/Foo.kt (browse)

package foo

import java.io.IOException
import java.io.InputStream

object Foo {

    // Read `file.txt` from classpath
    fun classpathResourceText(): String {
        // Get the resource as an InputStream
        return Foo::class.java.classLoader.getResourceAsStream("file.txt").use {
            it.readAllBytes().toString(Charsets.UTF_8)
        }
    }
}

foo/test/src/FooTests.kt (browse)

package foo

import io.kotest.core.spec.style.FunSpec
import io.kotest.matchers.shouldBe

import java.io.InputStream
import java.io.IOException
import java.nio.file.Files
import java.nio.file.Paths
import java.nio.file.Path
import java.util.List
import java.util.ArrayList

class FooTests : FunSpec({

    test("simple") {
        // Reference app module's `Foo` class which reads `file.txt` from classpath
        val appClasspathResourceText = Foo.classpathResourceText()
        appClasspathResourceText shouldBe "Hello World Resource File"

        // Read `test-file-a.txt` from classpath
        val testClasspathResourceText = Foo::class.java.classLoader.getResourceAsStream("test-file-a.txt").use {
            it.readAllBytes().toString(Charsets.UTF_8)
        }
        testClasspathResourceText shouldBe "Test Hello World Resource File A"

        // Use `MILL_TEST_RESOURCE_DIR` to read `test-file-b.txt` from filesystem
        val testFileResourceDir = Paths.get(System.getenv("MILL_TEST_RESOURCE_DIR"))
        val testFileResourceText = Files.readString(
            testFileResourceDir.resolve("test-file-b.txt")
        )
        testFileResourceText shouldBe "Test Hello World Resource File B"

        // Use `MILL_TEST_RESOURCE_DIR` to list files available in resource folder
        val actualFiles = Files.list(testFileResourceDir).toList().sorted()
        val expectedFiles = listOf(
            testFileResourceDir.resolve("test-file-a.txt"),
            testFileResourceDir.resolve("test-file-b.txt")
        )
        actualFiles shouldBe expectedFiles

        // Use the `OTHER_FILES_DIR` configured in your build to access the
        // files in `foo/test/other-files/`.
        val otherFileText = Files.readString(
            Paths.get(System.getenv("OTHER_FILES_DIR"), "other-file.txt")
        )
        otherFileText shouldBe "Other Hello World File"
    }
})

Note that tests require that you pass in any files that they depend on explicitly. This is necessary so that Mill knows when a test needs to be re-run and when a previous result can be cached. This also ensures that tests reading and writing to the current working directory do not accidentally interfere with each others files, especially when running in parallel.

The test process runs in a sandbox/ folder, not in your project root folder, to prevent you from accidentally accessing files without explicitly passing them. If you have legacy tests that need to run in the project root folder to work, you can configure your test suite with def testSandboxWorkingDir = false to disable the sandbox and make the tests run in the project root.

Kotlin Compiler Plugins

The Kotlin compiler requires plugins to be passed explicitly. To do this, you can define a module to contain the exact annotation processors you want, and pass in -Xplugin to kotlincOptions:

build.mill (download, browse)

package build

import mill._, kotlinlib._
import java.io.File

object foo extends KotlinModule {

  def kotlinVersion = "1.9.24"

  def ivyDeps = super.ivyDeps() ++ Agg(
    ivy"org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.3"
  )

  def processors = Task {
    defaultResolver().resolveDeps(
      Agg(
        ivy"org.jetbrains.kotlin:kotlin-serialization-compiler-plugin:1.9.24"
      )
    )
  }

  def kotlincOptions = super.kotlincOptions() ++ Seq(
    s"-Xplugin=${processors().head.path}"
  )

  object test extends KotlinTests with TestModule.Junit5 {
    def ivyDeps = super.ivyDeps() ++ Agg(
      ivy"io.kotest:kotest-runner-junit5-jvm:5.9.1"
    )
  }
}

> ./mill foo.test
Test foo.ProjectTestsimple started
Test foo.ProjectTestsimple finished...
...

Javadoc Config

To generate API documenation you can use the docJar task on the module you’d like to create the documentation for, configured via scalaDocOptions or javadocOptions:

build.mill (download, browse)

package build
import mill._, kotlinlib._

object foo extends KotlinModule {

  def kotlinVersion = "1.9.24"

}

> ./mill show foo.docJar
...
...Generation completed successfully...

> unzip -p out/foo/docJar.dest/out.jar root/foo/index.html
...
...My Awesome Docs for class Foo...
...
...My Awesome Docs for class Bar...

Specifying the Main Class

build.mill (download, browse)

package build
import mill._, kotlinlib._

object `package` extends RootModule with KotlinModule {

  def kotlinVersion = "1.9.24"

  def mainClass = Some("foo.QuxKt")
}

Mill’s foo.run by default will discover which main class to run from your compilation output, but if there is more than one or the main class comes from some library you can explicitly specify which one to use. This also adds the main class to your foo.jar and foo.assembly jars.

> ./mill run
Hello Qux

Customizing the Assembly

build.mill (download, browse)

package build
import mill._, kotlinlib._
import mill.javalib.Assembly._

object foo extends KotlinModule {

  def kotlinVersion = "1.9.24"

  def mainClass = Some("foo.FooKt")

  def moduleDeps = Seq(bar)
  def assemblyRules = Seq(
    // all application.conf files will be concatenated into single file
    Rule.Append("application.conf"),
    // all *.conf files will be concatenated into single file
    Rule.AppendPattern(".*\\.conf"),
    // all *.temp files will be excluded from a final jar
    Rule.ExcludePattern(".*\\.temp"),
    // the `shapeless` package will be shaded under the `shade` package
    Rule.Relocate("shapeless.**", "shade.shapless.@1")
  )
}

object bar extends KotlinModule {
  def kotlinVersion = "1.9.24"
}

When you make a runnable jar of your project with assembly command, you may want to exclude some files from a final jar (like signature files, and manifest files from library jars), and merge duplicated files (for instance reference.conf files from library dependencies).

By default mill excludes all *.sf, *.dsa, *.rsa, and META-INF/MANIFEST.MF files from assembly, and concatenates all reference.conf files. You can also define your own merge/exclude rules.

> ./mill foo.assembly

> unzip -p ./out/foo/assembly.dest/out.jar application.conf || true
Bar Application Conf
Foo Application Conf

> java -jar ./out/foo/assembly.dest/out.jar
Loaded application.conf from resources:...
...Foo Application Conf
...Bar Application Conf

Native C Code with JNI

build.mill (download, browse)

package build
import mill._, kotlinlib._, util.Jvm

object `package` extends RootModule with KotlinModule {

  def mainClass = Some("foo.HelloWorldKt")

  def kotlinVersion = "1.9.24"

  // Additional source folder to put C sources
  def nativeSources = T.sources(millSourcePath / "native-src")

  // Compile C
  def nativeCompiled = Task {
    val cSourceFiles = nativeSources().map(_.path).flatMap(os.walk(_)).filter(_.ext == "c")
    val output = "libhelloworld.so"
    os.proc(
        "clang", "-shared", "-fPIC",
        "-I" + sys.props("java.home") + "/include/", // global JVM header files
        "-I" + sys.props("java.home") + "/include/darwin",
        "-I" + sys.props("java.home") + "/include/linux",
        "-o", T.dest / output,
        cSourceFiles
      )
      .call(stdout = os.Inherit)

    PathRef(T.dest / output)
  }

  def forkEnv = Map("HELLO_WORLD_BINARY" -> nativeCompiled().path.toString)

  object test extends KotlinTests with TestModule.Junit5 {
    def ivyDeps = super.ivyDeps() ++ Agg(
      ivy"io.kotest:kotest-runner-junit5-jvm:5.9.1"
    )
    def forkEnv = Map("HELLO_WORLD_BINARY" -> nativeCompiled().path.toString)
  }
}

This is an example of how use Mill to compile C code together with your Kotlin code using JNI. There are three two steps: defining the C source folder, and then compiling the C code using clang. After that we have the libhelloworld.so on disk ready to use, and in this example we use an environment variable to pass the path of that file to the application code to load it using System.load.

The above builds expect the following project layout:

build.mill
src/
    foo/
        HelloWorld.kt

native-src/
    HelloWorld.c

test/
    src/
        foo/
            HelloWorldTest.kt

This example is pretty minimal, but it demonstrates the core principles, and can be extended if necessary to more elaborate use cases. The native* tasks can also be extracted out into a trait for re-use if you have multiple `KotlinModule`s that need native C components.

> ./mill run
Hello, World!

> ./mill test
Test foo.HelloWorldTestsimple started
Test foo.HelloWorldTestsimple finished...
...