Java Module Configuration

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

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

mill.javalib.JavaModule

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._, javalib._

object `package` extends RootModule with JavaModule {
  // You can have arbitrary numbers of third-party dependencies
  def ivyDeps = Agg(
    ivy"org.apache.commons:commons-text:1.12.0"
  )

  // Choose a main class to use for `.run` if there are multiple present
  def mainClass: T[Option[String]] = Some("foo.Foo2")

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

  // Add (or replace) resource folders for the module to use
  def resources = Task.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(
      Task.dest / s"Foo$name.java",
      s"""
package foo;
public class Foo$name {
  public static String value = "hello $name";
}
      """.stripMargin
    )

    Seq(PathRef(Task.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._, javalib._

object `package` extends RootModule with JavaModule {
  def ivyDeps = Agg(ivy"net.sourceforge.argparse4j:argparse4j:0.9.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(
      Task.dest / s"MyDeps.java",
      s"""
package foo;
public class MyDeps {
  public static String value =
    $ivyDepsString;
}
      """.stripMargin
    )

    Seq(PathRef(Task.dest))
  }

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

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

  def printLineCount() = Task.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: net.sourceforge.argparse4j:argparse4j:0.9.0
my.line.count: 24

> mill show lineCount
24

> mill printLineCount
24

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._, javalib._

object foo extends JavaModule {

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

public class Foo {
    public static void main(String[] args) {
        System.out.println("Hello World");
    }
}
      """.stripMargin
    )
    Seq(PathRef(Task.dest))
  }

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

  def run(args: Task[Args] = Task.Anon(Args())) = Task.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 JavaModule {
  def generatedSources = Task {
    os.write(Task.dest / "Foo.java", """...""")
    Seq(PathRef(Task.dest))
  }
}

object foo3 extends JavaModule {
  def sources = Task {
    os.write(Task.dest / "Foo.java", """...""")
    super.sources() ++ Seq(PathRef(Task.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._, javalib._

object `package` extends RootModule with JavaModule{
  def forkArgs = Seq("-Xmx4g", "-Dmy.jvm.property=hello")
  def forkEnv = Map("MY_ENV_VAR" -> "WORLD")
  def javacOptions = Seq("-deprecation")
}

You can pass flags to the Kotlin compiler via javacOptions.

> ./mill compile
.../src/foo/Foo.java:...: stop() in java.lang.Thread has been deprecated

> ./mill run
hello WORLD

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._, javalib._

object foo extends JavaModule {
  object test extends JavaTests with TestModule.Junit4 {
    def otherFiles = Task.Source(millSourcePath / "other-files")

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

> ./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.java (browse)

package foo;

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

public class Foo {

  // Read `file.txt` from classpath
  public static String classpathResourceText() throws IOException {
    // Get the resource as an InputStream
    try (InputStream inputStream = Foo.class.getClassLoader().getResourceAsStream("file.txt")) {
      return new String(inputStream.readAllBytes());
    }
  }
}

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

package foo;

import org.junit.Test;
import static org.junit.Assert.*;

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;

public class FooTests {

  @Test
  public void simple() throws IOException {
    // Reference app module's `Foo` class which reads `file.txt` from classpath
    String appClasspathResourceText = Foo.classpathResourceText();
    assertEquals("Hello World Resource File", appClasspathResourceText);

    // Read `test-file-a.txt` from classpath
    String testClasspathResourceText;
    try (InputStream inputStream = Foo.class.getClassLoader().getResourceAsStream("test-file-a.txt")) {
      testClasspathResourceText = new String(inputStream.readAllBytes());
    }
    assertEquals("Test Hello World Resource File A", testClasspathResourceText);

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

    // Use `MILL_TEST_RESOURCE_DIR` to list files available in resource folder
    List<Path> actualFiles = new ArrayList<>(Files.list(testFileResourceDir).toList());
    actualFiles.sort(Path::compareTo);
    List<Path> expectedFiles = List.of(
            testFileResourceDir.resolve("test-file-a.txt"),
            testFileResourceDir.resolve("test-file-b.txt")
    );
    assertEquals(expectedFiles, actualFiles);

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

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.

Annotation Processors

build.mill (download, browse)

package build
import mill._, javalib._
import java.io.File

object foo extends JavaModule {
  def compileIvyDeps = Agg(ivy"org.projectlombok:lombok:1.18.34")

  object test extends JavaTests with TestModule.Junit4
}

This is an example of how to use Mill to build Java projects using Java annotations and annotation processors. In this case, we use the annotations provided by Project Lombok to automatically generate getters and setters from class private fields

> ./mill foo.test
Test foo.HelloWorldTest.testSimple started
Test foo.HelloWorldTest.testSimple finished...
...

The Java compiler automatically discovers annotation processors based on the classes available during compilation, e.g. on compileIvyDeps or ivyDeps, which is what takes place in the example above.

In some cases, you may need to pass in the annotation processors manually, e.g. if you need annotation processors that are not on the compilation classpath, or you need finer control over exactly which annotation processors are active. To do this, you can define a module to contain the exact annotation processors you want, and pass in -processorpath to javacOptions explicitly:

object bar extends JavaModule {
  def compileIvyDeps = Agg(ivy"org.projectlombok:lombok:1.18.34")

  def processors = Task {
    defaultResolver().resolveDeps(Agg(ivy"org.projectlombok:lombok:1.18.34"))
  }

  def javacOptions = Seq(
    "-processorpath",
    processors().map(_.path).mkString(File.pathSeparator),
  )

  object test extends JavaTests with TestModule.Junit4
}

> ./mill bar.test
Test bar.HelloWorldTest.testSimple started
Test bar.HelloWorldTest.testSimple 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._, javalib._

object foo extends JavaModule {
  def javadocOptions = Seq("-quiet")
}

> ./mill show foo.docJar

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

Specifying the Main Class

build.mill (download, browse)

package build
import mill._, javalib._

object `package` extends RootModule with JavaModule {
  def mainClass = Some("foo.Qux")
}

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._, javalib._
import mill.javalib.Assembly._

object foo extends JavaModule {
  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 JavaModule {
}

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

This is an example of how use Mill to compile C code together with your Java code using JNI.

build.mill (download, browse)

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

object `package` extends RootModule with JavaModule {
  // Additional source folder to put C sources
  def nativeSources = Task.Sources(millSourcePath / "native-src")

  // Auto-generate JNI `.h` files from Java classes using Javac
  def nativeHeaders = Task {
    os.proc(Jvm.jdkTool("javac"), "-h", Task.dest, "-d", Task.dest.toString, allSourceFiles().map(_.path)).call()
    PathRef(Task.dest)
  }

  // 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" + nativeHeaders().path, //
        "-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", Task.dest / output,
        cSourceFiles
      )
      .call(stdout = os.Inherit)

    PathRef(Task.dest / output)
  }

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

  object test extends JavaTests with TestModule.Junit4{
    def forkEnv = Map("HELLO_WORLD_BINARY" -> nativeCompiled().path.toString)
  }
}

There are three main steps: defining the C source folder, generating the header files using javac, 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.java

native-src/
    HelloWorld.c

test/
    src/
        foo/
            HelloWorldTest.java

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 `JavaModule`s that need native C components

> ./mill run
Hello, World!

> ./mill test
Test foo.HelloWorldTest.testSimple started
Test foo.HelloWorldTest.testSimple finished...
...