Modules

  1. As objects, they serve as namespaces that let you group related Tasks together to keep things neat and organized.

  2. As traits, they are re-usable templates that let you replicate groups of related Tasks and sub-Modules while allowing customizations

Mill’s comes with built in modules such as mill.scalalib.ScalaModule and mill.scalalib.CrossSbtModule, but you can also define your own modules to do things that are not built-in to Mill.

Simple Modules

The path to a Mill module from the root of your build file corresponds to the path you would use to run tasks within that module from the command line. e.g. for the following build.mill:

build.mill (download, browse)
package build
import mill._

object foo extends Module {
  def bar = Task { "hello" }
  object qux extends Module {
    def baz = Task { "world" }
  }
}
Diagram

You would be able to run the two tasks via mill foo.bar or mill foo.qux.baz. You can use mill show foo.bar or mill show foo.baz.qux to make Mill echo out the string value being returned by each Task. The two tasks will store their output metadata and files at ./out/foo/bar.{json,dest} and ./out/foo/baz/qux.{json,dest} respectively.

> ./mill foo.bar
> ./mill foo.qux.baz

> ./mill show foo.bar
"hello"

> ./mill show foo.qux.baz
"world"

> cat ./out/foo/bar.json # task output path follows module hierarchy
..."value": "hello"...

> cat ./out/foo/qux/baz.json
..."value": "world"...

Trait Modules

Modules also provide a way to define and re-use common collections of tasks, via Scala traits. Module traits support everything normal Scala traits do: abstract defs, overrides, super, extension with additional defs, etc.

trait FooModule extends Module {
  def bar: T[String] // required override
  def qux = Task { bar() + " world" }
}

object foo1 extends FooModule{
  def bar = "hello"
  def qux = super.qux().toUpperCase // refer to overriden value via super
}
object foo2 extends FooModule {
  def bar = "hi"
  def baz = Task { qux() + " I am Cow" } // add a new `def`
}

This generates the following module tree and task graph, with the dotted boxes and arrows representing the module tree, and the solid boxes and arrows representing the task graph

Diagram

Note that the override keyword is optional in mill, as is T{…​} wrapper.

> ./mill show foo1.bar
"hello"

> ./mill show foo1.qux
"HELLO WORLD"

> ./mill show foo2.bar
"hi"

> ./mill show foo2.qux
"hi world"

> ./mill show foo2.baz
"hi world I am Cow"

The built-in mill.scalalib package uses this to define ScalaModule, SbtModule and TestScalaModule, etc. which contain a set of "standard" operations such as compile, jar or assembly that you may expect from a typical Scala module.

When defining your own module abstractions, you should be using traits and not classes due to implementation limitations

millSourcePath

Each Module has a millSourcePath field that corresponds to the path that module expects its input files to be on disk.

trait MyModule extends Module{
  def sources = Task.Source(millSourcePath / "sources")
  def task = Task { "hello " + os.list(sources().path).map(os.read(_)).mkString(" ") }
}

object outer extends MyModule {
  object inner extends MyModule
}
Diagram

  • The outer module has a millSourcePath of outer/, and thus a outer.sources referencing outer/sources/

  • The inner module has a millSourcePath of outer/inner/, and thus a outer.inner.sources referencing outer/inner/sources/

> ./mill show outer.task
"hello contents of file inside outer/sources/"

> ./mill show outer.inner.task
"hello contents of file inside outer/inner/sources/"

You can use millSourcePath to automatically set the source folders of your modules to match the build structure. You are not forced to rigidly use millSourcePath to define the source folders of all your code, but it can simplify the common case where you probably want your build-layout and on-disk-layout to be the same.

E.g. for mill.scalalib.ScalaModule, the Scala source code is assumed by default to be in millSourcePath / "src" while resources are automatically assumed to be in millSourcePath / "resources".

You can override millSourcePath:

object outer2 extends MyModule {
  def millSourcePath = super.millSourcePath / "nested"
  object inner extends MyModule
}
> ./mill show outer2.task
"hello contents of file inside outer2/nested/sources/"

> ./mill show outer2.inner.task
"hello contents of file inside outer2/nested/inner/sources/"

Any overrides propagate down to the module’s children: in the above example, outer2 would have its millSourcePath be outer2/nested/ while outer.inner would have its millSourcePath be outer2/nested/inner/.

Note that millSourcePath is meant to be used for a module’s input source files: source code, config files, library binaries, etc. Output is always in the out/ folder and cannot be changed, e.g. even with the overridden millSourcePath the output paths are still the default ./out/outer2 and ./out/outer2/inner folders:

> cat ./out/outer2/task.json
..."value": "hello contents of file inside outer2/nested/sources/"...

> cat ./out/outer2/inner/task.json
..."value": "hello contents of file inside outer2/nested/inner/sources/"...

Note that os.pwd of the Mill process is set to an empty sandbox/ folder by default. When defining a module’s source files, you should always use millSourcePath to ensure the paths defined are relative to the module’s root folder, so the module logic can continue to work even if moved into a different subfolder. In the rare case where you need the Mill project root path, and you truly know what you are doing, you can call g`mill.api.WorkspaceRoot.workspaceRoot`.

Use Case: DIY Java Modules

This section puts together what we’ve learned about Tasks and Modules so far into a worked example: implementing our own minimal version of mill.scalalib.JavaModule from first principles.

build.mill (download, browse)
package build
import mill._

trait DiyJavaModule extends Module{
  def moduleDeps: Seq[DiyJavaModule] = Nil
  def mainClass: T[Option[String]] = None

  def upstream: T[Seq[PathRef]] = Task { Task.traverse(moduleDeps)(_.classPath)().flatten }
  def sources = Task.Source(millSourcePath / "src")

  def compile = Task {
    val allSources = os.walk(sources().path)
    val cpFlag = Seq("-cp", upstream().map(_.path).mkString(":"))
    os.proc("javac", cpFlag, allSources, "-d", Task.dest).call()
    PathRef(Task.dest)
  }

  def classPath = Task { Seq(compile()) ++ upstream() }

  def assembly = Task {
    for(cp <- classPath()) os.copy(cp.path, Task.dest, mergeFolders = true)

    val mainFlags = mainClass().toSeq.flatMap(Seq("-e", _))
    os.proc("jar", "-c", mainFlags, "-f", Task.dest / s"assembly.jar", ".")
      .call(cwd = Task.dest)

    PathRef(Task.dest / s"assembly.jar")
  }
}

This defines the following build graph for DiyJavaModule. Note that some of the edges (dashed) are not connected; that is because DiyJavaModule is abstract, and needs to be inherited by a concrete object before it can be used.

Diagram

Some notable things to call out:

  • def moduleDeps is not a Task. This is necessary because tasks cannot change the shape of the task graph during evaluation, whereas moduleDeps defines module dependencies that determine the shape of the graph.

  • Using Task.traverse to recursively gather the upstream classpath. This is necessary to convert the Seq[T[V]] into a T[Seq[V]] that we can work with inside our tasks

  • We use the millSourcePath together with Task.workspace to infer a default name for the jar of each module. Users can override it if they want, but having a default is very convenient

  • def cpFlag is not a task or task, it’s just a normal helper method.

Below, the inherit DiyJavaModule in three objects: foo, bar, and qux:

object foo extends DiyJavaModule {
  def moduleDeps = Seq(bar)
  def mainClass = Some("foo.Foo")

  object bar extends DiyJavaModule
}

object qux extends DiyJavaModule {
  def moduleDeps = Seq(foo)
  def mainClass = Some("qux.Qux")
}

This results in the following build graph, with the build graph for DiyJavaModule duplicated three times - once per module - with the tasks wired up between the modules according to our overrides for moduleDeps

Diagram

This simple set of DiyJavaModule can be used as follows:

> ./mill showNamed __.sources
{
  "foo.sources": ".../foo/src",
  "foo.bar.sources": ".../foo/bar/src",
  "qux.sources": ".../qux/src"
}

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

> java -jar out/qux/assembly.dest/assembly.jar
Foo.value: 31337
Bar.value: 271828
Qux.value: 9000

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

> java -jar out/foo/assembly.dest/assembly.jar
Foo.value: 31337
Bar.value: 271828

Like any other Tasks, the compilation and packaging of the Java code is incremental: if you change a file in foo/src/ and run qux.assembly, foo.compile and qux.compile will be re-computed, but bar.compile will not as it does not transitively depend on foo.sources. We did not need to build support for this caching and invalidation ourselves, as it is automatically done by Mill based on the structure of the build graph.

Note that this is a minimal example is meant for educational purposes: the mill.scalalib.JavaModule and ScalaModule that Mill provides is more complicated to provide additional flexibility and performance. Nevertheless, this example should give you a good idea of how Mill modules can be developed, so you can define your own custom modules when the need arises.

Backticked Names

build.mill (download, browse)
package build
import mill._
import mill.scalalib._

object `hyphenated-module` extends Module {
  def `hyphenated-task` = Task {
    println("hyphenated task in a hyphenated module.")
  }
}

object unhyphenatedModule extends Module {
  def unhyphenated_task = Task {
    println("unhyphenated task in an unhyphenated module.")
  }
}

Mill modules and tasks may be composed of the following character types:

  • Alphanumeric (A-Z, a-z, and 0-9)

  • Underscore (_)

  • Hyphen (-)

Due to Scala naming restrictions, module and task names with hyphens must be surrounded by back-ticks (`).

Using hyphenated names at the command line is unaffected by these restrictions.

> ./mill hyphenated-module.hyphenated-task
hyphenated task in a hyphenated module.

> ./mill unhyphenatedModule.unhyphenated_task
unhyphenated task in an unhyphenated module.

External Modules

Libraries for use in Mill can define ExternalModules: Modules which are shared between all builds which use that library:

package foo
import mill._

object Bar extends mill.define.ExternalModule {
  def baz = Task { 1 }
  def qux() = Task.Command { println(baz() + 1) }

  lazy val millDiscover = mill.define.Discover[this.type]
}

In the above example, Bar is an ExternalModule living within the foo Java package, containing the baz task and qux command. Those can be run from the command line via:

mill foo.Bar/baz
mill foo.Bar/qux

ExternalModules are useful for someone providing a library for use with Mill that is shared by the entire build: for example, mill.scalalib.ZincWorkerApi/zincWorker provides a shared Scala compilation service & cache that is shared between all ScalaModules, and mill.scalalib.GenIdea/idea lets you generate IntelliJ projects without needing to define your own Task.Command in your build.mill file