Extending_Mill.adoc

Extending Mill

There are different ways of extending Mill, depending on how much customization and flexibility you need. This page will go through your options from the easiest/least-flexible to the hardest/most-flexible.

Custom Targets & Commands

The simplest way of adding custom functionality to Mill is to define a custom Target or Command:

def foo = T { ... }
def bar(x: Int, s: String) = T.command { ... }

These can depend on other Targets, contain arbitrary code, and be placed top-level or within any module. If you have something you just want to do that isn’t covered by the built-in ScalaModules/ScalaJSModules, simply write a custom Target (for cached computations) or Command (for un-cached actions) and you’re done.

For subprocess/filesystem operations, you can use the os-lib library that comes bundled with Mill, or even plain java.nio/java.lang.Process. Each target gets its own T.dest folder that you can use to place files without worrying about colliding with other targets.

This covers use cases like:

Compile some Javascript with Webpack and put it in your runtime classpath:

def doWebpackStuff(sources: Seq[PathRef]): PathRef = ???

def javascriptSources = T.sources { millSourcePath / "js" }
def compiledJavascript = T { doWebpackStuff(javascriptSources()) }
object foo extends ScalaModule {
  def runClasspath = T { super.runClasspath() ++ compiledJavascript() }
}

Deploy your compiled assembly to AWS

object foo extends ScalaModule {}

def deploy(assembly: PathRef, credentials: String) = ???

def deployFoo(credentials: String) = T.command {
  deploy(foo.assembly(), credentials)
}

Custom Workers

[_custom_targets_commands] are re-computed from scratch each time; sometimes you want to keep values around in-memory when using --watch or the Build REPL.

In such a case, you can use a Worker. Workers keep their state between multiple runs. Workers are created with the T.worker macro.

Example: Keep a webpack process running so webpack’s own internal caches are hot and compilation is fast

def webpackWorker = T.worker {
  // Spawn a process using java.lang.Process and return it
}

def javascriptSources = T.sources { millSourcePath / "js" }

def doWebpackStuff(webpackProcess: Process, sources: Seq[PathRef]): PathRef =
  ???

def compiledJavascript = T {
  doWebpackStuff(webpackWorker(), javascriptSources())
}

Mill itself uses T.workers for its built-in Scala support: we keep the Scala compiler in memory between compilations, rather than discarding it each time, in order to improve performance.

Custom Modules

trait FooModule extends mill.Module {
  def bar = T { "hello" }
  def baz = T { "world" }
}

Custom modules are useful if you have a common set of tasks that you want to re-use across different parts of your build. You simply define a trait inheriting from mill.Module, and then use that trait as many times as you want in various objects:

object foo1 extends FooModule
object foo2 extends FooModule {
  def qux = T { "I am Cow" }
}

You can also define a trait extending the built-in ScalaModule if you have common configuration you want to apply to all your ScalaModules:

trait FooModule extends ScalaModule {
  def scalaVersion = "2.11.11"
  object test extends Tests with TestModule.ScalaTest {
    def ivyDeps = Agg(ivy"org.scalatest::scalatest:3.0.4")
  }
}

In fact, the above example of a configuration trait is so convenient, that it is found in almost any non-trivial Mill project, in once form or another.

import $file

If you want to define some functionality that can be used both inside and outside the build, you can create a new foo.sc file next to your build.sc, import $file.foo, and use it in your build.sc file:

foo.sc

def fooValue() = 31337

build.sc

import $file.foo
def printFoo() = T.command { println(foo.fooValue()) }

Mill’s import $file syntax supports the full functionality of Ammonite Scripts

import $ivy

If you want to pull in artifacts from the public repositories (e.g. Maven Central) for use in your build, you can simply use import $ivy.

Example build.sc: Using scalatags library to generate HTML

import $ivy.`com.lihaoyi::scalatags:0.6.2` // (1)

def generatedHtml = T {
  import scalatags.Text.all._ // (2)
  html(
    head(),
    body(
      h1("Hello"),
      p("World")
    )
  ).render
}

1. Import the scalatags library from Mavel Central repository.

2. Creates the generatedHtml target which is used here to generate a simple Hello World HTML document. It can be used however you would like: written to a file, further processed, etc.

Please also read the section Using_Plugins.adoc.

For more information about this special import syntax, read the Ammonite Documentation for Ivy Dependencies.

Evaluator Commands (experimental)

Evaluator Command are experimental and suspected to change. See {mill-github-url}/issues/502[issue #502] for details.

You can define a command that takes in the current Evaluator as an argument, which you can use to inspect the entire build, or run arbitrary tasks. For example, here is the mill.scalalib.GenIdea/idea command which uses this to traverse the module-tree and generate an Intellij project config for your build.

def idea(ev: Evaluator) = T.command {
  mill.scalalib.GenIdea(
    implicitly,
    ev.rootModule,
    ev.discover
  )
}

Many built-in tools are implemented as custom evaluator commands: inspect, resolve, show. If you want a way to run Mill commands and programmatically manipulate the tasks and outputs, you do so with your own evaluator command.