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

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.thymeleaf:thymeleaf:3.1.1.RELEASE"
  )

  // 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)

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 Java compiler via javacOptions.

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

> ./mill run
hello WORLD

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
    )
  }
}

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 static org.junit.Assert.*;

import java.io.IOException;
import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.List;
import org.junit.Test;

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);
  }
}

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

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")
}

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 relocated under the `shade` package
    Rule.Relocate("shapeless.**", "shade.shapless.@1")
  )
}

object bar extends JavaModule {}

Custom Tasks

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()) }
}

> mill run --text hello
text: hello
MyDeps.value: net.sourceforge.argparse4j:argparse4j:0.9.0
my.line.count: 22

> mill show lineCount
22

> mill printLineCount
22

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)()
  }
}

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))
  }
}

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...
...