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

Compilation & Execution Flags

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

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

> ./mill run
hello WORLD

Adding Ivy Dependencies

build.mill (download, browse)

package build
import mill._, javalib._

object `package` extends RootModule with JavaModule {
  def ivyDeps = Agg(
    ivy"com.fasterxml.jackson.core:jackson-databind:2.13.4",
  )
}

You can define the ivyDeps field to add ivy dependencies to your module.

Single : syntax (e.g. "ivy"org.testng:testng:6.11") defines Java dependencies

To select the test-jars from a dependency use the following syntax:

ivy"org.apache.spark::spark-sql:2.4.0;classifier=tests.

Please consult the Library Dependencies in Mill section for even more details.

> ./mill run i am cow
JSONified using Jackson: ["i","am","cow"]

Runtime and Compile-time Dependencies

If you want to use additional dependencies at runtime or override dependencies and their versions at runtime, you can do so with runIvyDeps.

build.mill (download, browse)

package build
import mill._, javalib._

object foo extends JavaModule {
  def moduleDeps = Seq(bar)
  def runIvyDeps = Agg(
    ivy"javax.servlet:servlet-api:2.5",
    ivy"org.eclipse.jetty:jetty-server:9.4.42.v20210604",
    ivy"org.eclipse.jetty:jetty-servlet:9.4.42.v20210604"
  )
  def mainClass = Some("bar.Bar")
}

You can also declare compile-time-only dependencies with compileIvyDeps. These are present in the compile classpath, but will not propagated to the transitive dependencies.

object bar extends JavaModule {
  def compileIvyDeps = Agg(
    ivy"javax.servlet:servlet-api:2.5",
    ivy"org.eclipse.jetty:jetty-server:9.4.42.v20210604",
    ivy"org.eclipse.jetty:jetty-servlet:9.4.42.v20210604"
  )
}

Typically, Mill assumes that a module with compile-time dependencies will only be run after someone includes the equivalent run-time dependencies in a later build step. e.g. in the case above, bar defines the compile-time dependencies, and foo then depends on bar and includes the runtime dependencies. That is why we can run foo as show below:

> ./mill foo.runBackground

> curl http://localhost:8079
<html><body>Hello World!</body></html>

Compile-time dependencies are translated to provided-scoped dependencies when publish to Maven or Ivy-Repositories.

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_FOLDER" -> 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_FOLDER;

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_FOLDER, 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_FOLDER 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_FOLDER` to read `test-file-b.txt` from filesystem
    Path testFileResourceDir = Paths.get(System.getenv("MILL_TEST_RESOURCE_FOLDER"));
    String testFileResourceText = Files.readString(
        testFileResourceDir.resolve("test-file-b.txt")
    );
    assertEquals("Test Hello World Resource File B", testFileResourceText);

    // Use `MILL_TEST_RESOURCE_FOLDER` 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_FOLDER` configured in your build to access the
    // files in `foo/test/other-files/`.
    String otherFileText = Files.readString(
        Paths.get(System.getenv("OTHER_FILES_FOLDER"), "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 = T{
    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 documenation 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...

Unmanaged Jars

build.mill (download, browse)

package build
import mill._, javalib._

object `package` extends RootModule with JavaModule {
  def unmanagedClasspath = Task {
    if (!os.exists(millSourcePath / "lib")) Agg()
    else Agg.from(os.list(millSourcePath / "lib").map(PathRef(_)))
  }
}

You can override unmanagedClasspath to point it at any jars you place on the filesystem, e.g. in the above snippet any jars that happen to live in the lib/ folder.

> ./mill run '{"name":"John","age":30}'     # mac/linux
Key: name, Value: John
Key: age, Value: 30

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

Downloading Non-Maven Jars

build.mill (download, browse)

package build
import mill._, javalib._

object `package` extends RootModule with JavaModule {
  def unmanagedClasspath = Task {
    os.write(
      Task.dest / "fastjavaio.jar",
      requests.get.stream(
        "https://github.com/williamfiset/FastJavaIO/releases/download/1.1/fastjavaio.jar"
      )
    )
    Agg(PathRef(Task.dest / "fastjavaio.jar"))
  }
}

You can also override unmanagedClasspath to point it at jars that you want to download from arbitrary URLs. Note that targets like unmanagedClasspath are cached, so your jar is downloaded only once and re-used indefinitely after that. requests.get comes from the Requests-Scala library, which is bundled with Mill

> ./mill run "textfile.txt" # mac/linux
I am cow
hear me moo
I weigh twice as much as you

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

Repository Config

By default, dependencies are resolved from maven central, but you can add your own resolvers by overriding the repositoriesTask task in the module:

build.mill (download, browse)

package build
import mill._, javalib._
import mill.define.ModuleRef
import coursier.maven.MavenRepository

val sonatypeReleases = Seq(
  MavenRepository("https://oss.sonatype.org/content/repositories/releases")
)

object foo extends JavaModule {

  def ivyDeps = Agg(
    ivy"net.sourceforge.argparse4j:argparse4j:0.9.0",
    ivy"org.apache.commons:commons-text:1.12.0"
  )

  def repositoriesTask = Task.Anon { super.repositoriesTask() ++ sonatypeReleases }
}

Mill read coursier config files automatically.

It is possible to setup mirror with mirror.properties

central.from=https://repo1.maven.org/maven2
central.to=http://example.com:8080/nexus/content/groups/public

Note theses default config file locatations:

Linux: ~/.config/coursier/mirror.properties
MacOS: ~/Library/Preferences/Coursier/mirror.properties
Windows: C:\Users\<user_name>\AppData\Roaming\Coursier\config\mirror.properties

You can also set the environment variable COURSIER_MIRRORS or the jvm property coursier.mirrors to specify config file location.

To add custom resolvers to the initial bootstrap of the build, you can create a custom ZincWorkerModule, and override the zincWorker method in your ScalaModule by pointing it to that custom object:

object CustomZincWorkerModule extends ZincWorkerModule with CoursierModule {
  def repositoriesTask = Task.Anon { super.repositoriesTask() ++ sonatypeReleases }
}

object bar extends JavaModule {
  def zincWorker = ModuleRef(CustomZincWorkerModule)
  // ... rest of your build definitions

  def repositoriesTask = Task.Anon { super.repositoriesTask() ++ sonatypeReleases }
}

> ./mill foo.run --text hello

> ./mill bar.compile

Maven Central: Blocked!

Under some circumstances (e.g. corporate firewalls), you may not have access maven central. The typical symptom will be error messages which look like this;

1 targets failed
mill.scalalib.ZincWorkerModule.classpath
Resolution failed for 1 modules:
--------------------------------------------
  com.lihaoyi:mill-scalalib-worker_2.13:0.11.1
        not found: C:\Users\partens\.ivy2\local\com.lihaoyi\mill-scalalib-worker_2.13\0.11.1\ivys\ivy.xml
        download error: Caught java.io.IOException (Server returned HTTP response code: 503 for URL: https://repo1.maven.org/maven2/com/lihaoyi/mill-scalalib-worker_2.13/0.11.1/mill-scalalib-worker_2.13-0.11.1.pom) while downloading https://repo1.maven.org/maven2/com/lihaoyi/mill-scalalib-worker_2.13/0.11.1/mill-scalalib-worker_2.13-0.11.1.pom

It is expected that basic commands (e.g. clean) will not work, as Mill saying it is unable to resolve it’s own, fundamental, dependencies. Under such circumstances, you will normally have access to some proxy, or other corporate repository which resolves maven artefacts. The strategy is simply to tell mill to use that instead.

The idea is to set an environment variable COURSIER_REPOSITORIES (see coursier docs). The below command should set the environment variable for the current shell, and then run the mill command.

 COURSIER_REPOSITORIES=https://packages.corp.com/artifactory/maven/ mill resolve _

If you are using millw, a more permanent solution could be to set the environment variable at the top of the millw script, or as a user environment variable etc.

Native C Code with 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 = T{
    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)
  }
}

This is an example of how use Mill to compile C code together with your Java code using JNI. 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...
...