Building Kotlin with Mill

The source code for this module lives in the src/ folder. Output for this module (compiled files, resolved dependency lists, …​) lives in out/. A typical filesystem layout is shown below:

Typical usage of this example project from the command line is shown below:

The output of every Mill task is stored in the out/ folder under a name corresponding to the task that created it. e.g. The assembly task puts its metadata output in out/assembly.json, and its output files in out/assembly.dest. You can also use show to print out the metadata output for a particular task, or inspect to print metadata about the task itself (docs, source location, etc.)

Additional Mill tasks you would likely need include:

The most common tasks that Mill can run are cached tasks, such as compile, and un-cached commands such as run. Cached tasks do not re-evaluate unless one of their inputs changes, whereas commands re-run every time. See the documentation for Tasks for details on the different task types.

This example uses Mill’s config-based YAML syntax, which is a good fit for simple builds where you are just setting some configuration keys. This is discussed more in the documentation for:

This example contains a simple Mill build with two modules, foo and bar, defined by their respective package.mill.yaml config files, and on which you can run tasks on such as foo.run or bar.run. There is also a bar.test module defined by bar/test/package.mill.yaml.

Inter-module dependencies are defined by the moduleDeps key, and modules can also be nested within each other, as bar.test is nested within bar.

Mill’s default folder layout of src/ and test/src differs from the src/main/scala/ and src/test/scala/ common in Maven, Gradle, or SBT. If you are adopting Mill in an existing codebase, you can use Mill’s KotlinMavenModule and KotlinMavenTests as shown below to preserve filesystem compatibility with an existing build:

Note the object test: and object integration: keys in the above file: these allow you to define submodules in the same build.mill.yaml file as the parent module without needing a separate package.mill.yaml in a subfolder. This is necessary in scenarios like this one where we want test and integration submodules but the filesystem layout means we do not have test/ or integration/ folders to put a package.mill.yaml in.

KotlinMavenModule is a variant of KotlinModule that uses the more verbose folder layout of Maven, SBT, and other tools:

Rather than Mill’s

One use case of these compatibility modules is migrations: while migrating to Mill, a project may be built using your previous build tool and Mill at the same time. Using KotlinMavenModules means that during migration, you can leave all your source files in place while setting up your Mill build, and do not need to invasively move them around to match the Mill default module layout.

Although the source layout of these compatibility modules is different from the default KotlinModule, the command-line usage is the same:

For more details on migrating from other build tools, see Migrating to Mill

Script files can have test suites, usually written in a separate test script. The test script configuration specifies

The test script can then run tests that exercise the upstream script as shown below:

Again, you can pass the name of the task explicitly via :, e.g. :testForked below

The testing framework used in a script is defined by the class specified in the extends clause. The different testing frameworks supported in Testing Kotlin Projects can be used for your scripts: Junit4, Junit5, TestNg, Munit, ScalaTest, Specs2, Utest, Weaver, ZioTest. If you need something not on this list, you can define a Custom Script Module Class.

For scripts that grow larger than a single file, you should convert them to Config-Based Modules.

Programmatic Mill builds make it very easy to customize your build graph, overriding portions of it with custom logic. In this example, we override the JVM resources of our KotlinModule - normally the resources/ folder - to also contain a single generated text file containing the line count of all the source files in that module

In general, this use of method defs, method calls, override, and super should be very familiar to anyone with prior experience working in Kotlin. These are the same concepts that have underpinned object-oriented programming for decades, and work exactly the same here as they work anywhere else.

This generated line-count.txt file can then be loaded and used at runtime, as see in the output of mill run below.

If you’re not familiar with what tasks you can override or how they are related, you can explore the existing tasks via autocomplete in your IDE, or use the mill visualize.

Custom user-defined tasks in Mill such as def lineCount above benefit from all the same things that built-in tasks do: automatic caching (in the out/ folder), parallelism (configurable via -j/--jobs flag), inspectability (via show and inspect), and so on. While these things may not matter for such a simple example that runs quickly, they ensure that custom build logic remains performant and maintainable even as the complexity of your project grows.

This is similar to the Multi-Module Projects example above, but using Mill’s programmatic configuration syntax. You can define multiple modules the same way you define a single module, using def moduleDeps to define the relationship between them. Modules can also be nested within each other, as foo.test and bar.test are nested within foo and bar respectively

Note that we split out the test submodule configuration common to both modules into a separate trait MyModule. This Trait Module works like a class in Java, and lets us avoid the need to copy-paste common settings, while still letting us define any per-module configuration such as mvnDeps specific to a particular module. This is a common pattern within Mill builds.

You can also put the configuration for each submodule in it’s respective folder’s package.mill file, as described in Multi-File Builds. This can be helpful in larger projects to avoid having your build.mill grow large, and aid in discoverability by keeping the build configuration for each module close to the code it is configuring

This example is similar to the Maven-Compatible Modules above, but using Mill’s programmatic build.mill files. These are more flexible than the config-driven build.mill.yaml files, and can contain Custom Build Logic and other programmatic configuration