Building Java with Mill
This page contains a quick introduction to getting start with using Mill to build a simple Java program. We will walk through a series of Mill builds of increasing complexity to show you the key features and usage of the Mill build tool.
The other pages of this section on Java go into more depth into individual features, with more examples of how to use Mill for Java and more details of how the Mill build tool works. They aren’t intended to be read comprehensively top-to-bottom, but rather looked up when you have a particular interest e.g. in testing, linting, publishing, and so on.
Simple Java Module
package build
import mill._, javalib._
object foo extends JavaModule {
def ivyDeps = Agg(
ivy"net.sourceforge.argparse4j:argparse4j:0.9.0",
ivy"org.thymeleaf:thymeleaf:3.1.1.RELEASE"
)
object test extends JavaTests with TestModule.Junit4 {
def ivyDeps = super.ivyDeps() ++ Agg(
ivy"com.google.guava:guava:33.3.0-jre"
)
}
}
This is a basic Mill build for a single JavaModule
, with two
third-party dependencies and a test suite using the JUnit framework.
You can download this example project using the download link above
if you want to try out the commands below yourself, or browse the full sources
of the example (including supporting files) via the browse link. The only requirement is
that you have some version of the JVM installed; the ./mill
script
(./mill.bat
on windows) takes
care of any further dependencies that need to be downloaded. All examples
in this documentation site are executable and are continually exercised as
part of Mill’s CI workflows, and they range from the simple hello-world
projects on this page to more sophisticated
web build examples or
example
builds for real-world projects
The source code for this module lives in the src/
folder.
Output for this module (compiled files, resolved dependency lists, …)
lives in out/
.
build.mill foo/ src/ foo/Foo.java resources/ ... test/ src/ foo/FooTest.java out/foo/ compile.json compile.dest/ ... test/ compile.json compile.dest/ ...
The default Mill source folder layout foo/src/ differs from that of Maven/Gradle’s
foo/src/main/java/ .
If you wish to use the Maven source folder layout, e.g. for migrating
an existing codebase, you should use
Maven-Compatible Modules
|
This example project uses two third-party dependencies - ArgParse4J for CLI argument parsing, Thymeleaf for HTML rendering - and uses them to wrap a given input string in HTML templates with proper escaping.
Typical usage of a JavaModule
is shown below
> ./mill resolve foo._ # List what tasks are available to run
foo.assembly
...
foo.compile
...
foo.run
> ./mill inspect foo.compile # Show documentation and inputs of a task
foo.compile(JavaModule...)
Compiles the current module to generate compiled classfiles/bytecode.
Inputs:
foo.upstreamCompileOutput
foo.allSourceFiles
foo.compileClasspath
...
> ./mill foo.compile # compile sources into classfiles
...
compiling 1 Java source to...
> ./mill foo.run # run the main method, if any
error: argument -t/--text is required
...
> ./mill foo.run --text hello
<h1>hello</h1>
> ./mill foo.test
...
Test foo.FooTest.testEscaping finished, ...
Test foo.FooTest.testSimple finished, ...
Test run foo.FooTest finished: 0 failed, 0 ignored, 2 total, ...
> ./mill foo.assembly # bundle classfiles and libraries into a jar for deployment
> ./mill show foo.assembly # show the output of the assembly task
".../out/foo/assembly.dest/out.jar"
> java -jar ./out/foo/assembly.dest/out.jar --text hello
<h1>hello</h1>
> ./out/foo/assembly.dest/out.jar --text hello # mac/linux
<h1>hello</h1>
The output of every Mill task is stored in the out/
folder under a name
corresponding to the task that created it. e.g. The assembly
task puts its
metadata output in out/assembly.json
, and its output files in
out/assembly.dest
. You can also use show
to make Mill print out the
metadata output for a particular task.
Additional Mill tasks you would likely need include:
$ mill runBackground # run the main method in the background
$ mill clean <task> # delete the cached output of a task, terminate any runBackground
$ mill launcher # prepares a foo/launcher.dest/run you can run later
$ mill jar # bundle the classfiles into a jar suitable for publishing
$ mill -i console # start a Scala console within your project
$ mill -i repl # start an Ammonite Scala REPL within your project
$ mill -w compile # watch input files and re-compile whenever a file changes
You can run mill resolve __
to see a full list of the different tasks that
are available, mill resolve _
to see the tasks within foo
,
mill inspect compile
to inspect a task’s doc-comment documentation or what
it depends on, or mill show foo.scalaVersion
to show the output of any task.
The most common tasks that Mill can run are cached tasks, such as
compile
, and un-cached commands such as foo.run
. Cached tasks do not
re-evaluate unless one of their inputs changes, whereas commands re-run every
time. See the documentation for Tasks for
details on the different task types.
Mill build files are written in Scala, but you do not need to have prior experience in Scala to read or write them. Like Gradle Groovy or Maven XML, anyone can learn enough Scala for Mill without needing to become an expert in the language.
Custom Build Logic
Mill makes it very easy to customize your build graph, overriding portions
of it with custom logic. In this example, we override the JVM resources
of
our JavaModule
- normally the resources/
folder - to instead contain a
single generated text file containing the line count of all the source files
in that module
package build
import mill._, javalib._
object foo extends JavaModule {
/** Total number of lines in module source files */
def lineCount = Task {
allSourceFiles().map(f => os.read.lines(f.path).size).sum
}
/** Generate resources using lineCount of sources */
override def resources = Task {
os.write(Task.dest / "line-count.txt", "" + lineCount())
super.resources() ++ Seq(PathRef(Task.dest))
}
}
The addition of lineCount
and resources
overrides the previous resource
folder provided by JavaModule
(labelled resources.super
below), replacing
it with the destination folder of the new resources
task, which is wired
up to lineCount
:
> mill foo.run
...
Line Count: 17
> mill show foo.lineCount
17
> mill inspect foo.lineCount
foo.lineCount(build.mill:...)
Total number of lines in module source files
Inputs:
foo.allSourceFiles
Above, def lineCount
is a new build task we define, which makes use of
allSourceFiles
(an existing task) and is in-turn used in our override of
resources
(also an existing task). The override
keyword is optional in Mill.
This generated file can then be loaded and used at runtime, as see in the output
of mill run
.
If you’re not familiar with what tasks you can override
or how they are related,
you can explore the existing tasks via autocomplete in your IDE, or use the
mill visualize.
os.read.lines
and os.write
come
from the OS-Lib library, which is
one of Mill’s Bundled Libraries.
You can also import any other library you want from Maven Central using
import $ivy, so you are not limited
to what is bundled with Mill.
Custom user-defined tasks in Mill benefit from all the same things that built-in tasks do: automatic caching (in the out/ folder), parallelism (with the -j/--jobs flag), inspectability (via show/inspect), and so on. While these things may not matter for such a simple example that runs quickly, they ensure that custom build logic remains performant and maintainable even as the complexity of your project grows.
Multi-Module Project
package build
import mill._, javalib._
trait MyModule extends JavaModule {
object test extends JavaTests with TestModule.Junit4
}
object foo extends MyModule {
def moduleDeps = Seq(bar)
def ivyDeps = Agg(
ivy"net.sourceforge.argparse4j:argparse4j:0.9.0"
)
}
object bar extends MyModule {
def ivyDeps = Agg(
ivy"net.sourceforge.argparse4j:argparse4j:0.9.0",
ivy"org.thymeleaf:thymeleaf:3.1.1.RELEASE"
)
}
This example contains a simple Mill build with two modules, foo
and bar
,
which you can run tasks on such as foo.run
or
bar.run
. You can define multiple modules the same way you define a single
module, using def moduleDeps
to define the relationship between them. Modules
can also be nested within each other, as foo.test
and bar.test
are nested
within foo
and bar
respectively
Note that we split out the test
submodule configuration common to both
modules into a separate trait MyModule
. This Trait Module
lets us avoid the need to copy-paste common settings, while still letting
us define any per-module configuration such as ivyDeps
specific to a
particular module. This is a common pattern within Mill builds.
The above builds expect the following project layout:
build.mill foo/ src/ foo/Foo.java bar/ src/ bar/Bar.java test/ src/ bar/BarTests.java out/ foo/ compile.json compile.dest/ ... bar/ compile.json compile.dest/ ... test/ compile.json compile.dest/ ...
Typically, both source code and output files in Mill follow the module
hierarchy, so e.g. input to the foo
module lives in foo/src/
and
compiled output files live in out/foo/compile.dest
. You can use
mill resolve
to list out what tasks you can run, e.g. mill resolve __.run
below which lists out all the run
tasks:
> mill resolve __.run
foo.run
bar.run
> mill foo.run --foo-text hello --bar-text world
Foo.value: hello
Bar.value: <h1>world</h1>
> mill bar.run world
Bar.value: <h1>world</h1>
> mill bar.test
...
...bar.BarTests...simple...
...bar.BarTests...escaping...
Mill’s evaluator will ensure that the modules are compiled in the right order, and recompiled as necessary when source code in each module changes. The unique path on disk that Mill automatically assigns each task also ensures you do not need to worry about choosing a path on disk to cache outputs, or filesystem collisions if multiple tasks write to the same path.
You can use wildcards and brace-expansion to select multiple tasks at once or to shorten the path to deeply nested tasks. If you provide optional task arguments and your wildcard or brace-expansion is resolved to multiple tasks, the arguments will be applied to each of the tasks.
Wildcard |
Function |
|
matches a single segment of the task path |
|
matches arbitrary segments of the task path |
|
is equal to specifying two tasks |
You can use the + symbol to add another task with optional arguments.
If you need to feed a + as argument to your task, you can mask it by
preceding it with a backslash (\
).
> mill foo._.compile # Runs `compile` for all direct sub-modules of `foo`
> mill foo.__.test # Runs `test` for all transitive sub-modules of `foo`
> mill {foo,bar}.__.testCached # Runs `testCached` for all sub-modules of `foo` and `bar`
> mill __.compile + foo.__.test # Runs all `compile` tasks and all tests under `foo`.
For more details on the query syntax, check out the query syntax documentation
Maven-Compatible Modules
Mill’s default folder layout of foo/src/
and foo/test/src
differs from that
of Maven or Gradle’s foo/src/main/java/
and foo/src/test/java/
. If you are
migrating an existing codebase, you can use Mill’s MavenModule
and
MavenTests
as shown below to preserve filesystem compatibility with an existing
Maven or Gradle build:
package build
import mill._, javalib._
object foo extends MavenModule {
object test extends MavenTests with TestModule.Junit4
}
MavenModule
is a variant of JavaModule
that uses the more verbose folder layout of Maven, SBT, and other tools:
-
foo/src/main/java
-
foo/src/test/java
Rather than Mill’s
-
foo/src
-
foo/test/src
This is especially useful if you are migrating from Maven to Mill (or vice versa), during which a particular module may be built using both Maven and Mill at the same time
> mill foo.compile
compiling 1 Java source...
> mill foo.test.compile
compiling 1 Java source...
> mill foo.test.test
...foo.FooTests.hello ...
> mill foo.test
...foo.FooTests.hello ...
Realistic Java Example Project
Below, we should a realistic example of a build for a Java project. This example touches on library dependencies, testing, publishing, code generation, and other topics covered in more detail in the Java section of the Mill docs, and you can browse each respective page if you want to learn more.
package build
import mill._, javalib._, publish._
trait MyModule extends JavaModule with PublishModule {
def publishVersion = "0.0.1"
def pomSettings = PomSettings(
description = "Hello",
organization = "com.lihaoyi",
url = "https://github.com/lihaoyi/example",
licenses = Seq(License.MIT),
versionControl = VersionControl.github("lihaoyi", "example"),
developers = Seq(Developer("lihaoyi", "Li Haoyi", "https://github.com/lihaoyi"))
)
def ivyDeps = Agg(ivy"org.thymeleaf:thymeleaf:3.1.1.RELEASE")
object test extends JavaTests with TestModule.Junit4
}
object foo extends MyModule {
def moduleDeps = Seq(bar, qux)
def generatedSources = Task {
os.write(
Task.dest / "Version.java",
s"""
package foo;
public class Version {
public static String value() {
return "${publishVersion()}";
}
}
""".stripMargin
)
Seq(PathRef(Task.dest))
}
}
object bar extends MyModule {
def moduleDeps = Seq(qux)
}
object qux extends MyModule
A semi-realistic build setup, combining all the individual Mill concepts:
-
Three
JavaModule
s that depend on each other -
With unit testing and publishing set up
-
With generated sources to include the
publishVersion
as a string in the code, so it can be printed at runtime
Note that for multi-module builds like this, using queries to run tasks on multiple modules at once can be very convenient:
__.test __.publishLocal
Also note how you can use trait
s to bundle together common combinations of
modules: MyModule
not only defines a JavaModule
with some common
configuration, but it also defines a object test
module within it with its
own configuration. This is a very useful technique for managing the often
repetitive module structure in a typical project
> mill resolve __.run
bar.run
bar.test.run
foo.run
foo.test.run
qux.run
> mill foo.run
foo version 0.0.1
Foo.value: <h1>hello</h1>
Bar.value: <p>world</p>
Qux.value: 31337
> mill bar.test
...bar.BarTests.test ...
> mill qux.run
Qux.value: 31337
> mill __.compile
> mill __.test
...bar.BarTests.test ...
...foo.FooTests.test ...
> mill __.publishLocal
Publishing Artifact(com.lihaoyi,foo,0.0.1) to ivy repo...
Publishing Artifact(com.lihaoyi,bar,0.0.1) to ivy repo...
Publishing Artifact(com.lihaoyi,qux,0.0.1) to ivy repo...
...
> mill show foo.assembly # mac/linux
".../out/foo/assembly.dest/out.jar"
> ./out/foo/assembly.dest/out.jar # mac/linux
foo version 0.0.1
Foo.value: <h1>hello</h1>
Bar.value: <p>world</p>
Qux.value: 31337