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

import mill._, javalib._

object foo 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.sc (download, browse)

import mill._, javalib._

object foo 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

build.sc (download, browse)

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.

Test Dependencies

build.sc (download, browse)

import mill._, javalib._

object qux extends JavaModule {
  def moduleDeps = Seq(baz)

  object test extends JavaTests with TestModule.Junit4 {
    def moduleDeps = super.moduleDeps ++ Seq(baz.test)
    def ivyDeps = super.ivyDeps() ++ Agg(ivy"com.google.guava:guava:33.2.1-jre")
  }
}


object baz extends JavaModule {
  object test extends JavaTests with TestModule.Junit4{
    def ivyDeps = super.ivyDeps() ++ Agg(ivy"com.google.guava:guava:33.2.1-jre")
  }
}

In this example, not only does qux depend on baz, but we also make qux.test depend on baz.test. That lets qux.test make use of the BazTestUtils class that baz.test defines, allowing us to re-use this test helper throughout multiple modules' test suites

> ./mill qux.test
Using BazTestUtils.bazAssertEquals
... qux.QuxTests.simple ...
...

> ./mill baz.test
Using BazTestUtils.bazAssertEquals
... baz.BazTests.simple ...
...

Javadoc Config

build.sc (download, browse)

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.sc (download, browse)

import mill._, javalib._

object foo extends RootModule with JavaModule {
  def unmanagedClasspath = T {
    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.sc (download, browse)

import mill._, javalib._

object foo 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.sc (download, browse)

import mill._, javalib._

object foo extends RootModule with JavaModule {
  def unmanagedClasspath = T {
    os.write(
      T.dest / "fastjavaio.jar",
      requests.get.stream(
        "https://github.com/williamfiset/FastJavaIO/releases/download/1.1/fastjavaio.jar"
      )
    )
    Agg(PathRef(T.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.sc (download, browse)

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

build.sc (download, browse)

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 = T.task { 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 = T.task { super.repositoriesTask() ++ sonatypeReleases }
}

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

  def repositoriesTask = T.task { 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.sc (download, browse)

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

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

  // Auto-generate JNI `.h` files from Java classes using Javac
  def nativeHeaders = T {
    os.proc(Jvm.jdkTool("javac"), "-h", T.dest, "-d", T.dest.toString, allSourceFiles().map(_.path)).call()
    PathRef(T.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", T.dest / output,
        cSourceFiles
      )
      .call(stdout = os.Inherit)

    PathRef(T.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.sc
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...
...

Annotation Processors with Lombok

build.sc (download, browse)

import mill._, javalib._


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(":"),
  )

  object test extends JavaTests with TestModule.Junit4
}

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