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:
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
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
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
)
}
}
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());
}
}
}
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
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...
...
Custom Tasks
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
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.
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...
...