Building Java with Mill

The source code for this module lives in the src/ folder. Output for this module (compiled files, resolved dependency lists, ...​) lives in out/. A typical filesystem layout is shown below:

Typical usage from the command line is shown below:

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 print out the metadata output for a particular task, or inspect to print metadata about the task itself (docs, source location, etc.)

Additional Mill tasks you would likely need include:

You can start a JShell REPL attached to your foo module via:

You can also start a standalone JShell console via ./mill --jshell. This is useful if you just need a JShell console to experiment with at the command line without being attached to a particular project or module.

The most common tasks that Mill can run are cached tasks, such as compile, and un-cached commands such as 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.

This example uses Mill’s config-based YAML syntax, which is a good fit for simple builds where you are just setting some configuration keys. This is discussed more in the documentation for:

This example contains a simple Mill build with two modules, foo and bar, defined by their respective foo/package.mill.yaml and bar/package.mill.yaml config files, and on which you can run tasks on such as foo.run or bar.run. There is also a bar.test module defined by bar/test/package.mill.yaml.

Inter-module dependencies are defined by the moduleDeps key, and modules can also be nested within each other, as bar.test is nested within bar.

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:

MavenModule is a variant of JavaModule that uses the more verbose folder layout of Maven, sbt, and other tools:

Rather than Mill’s

This is especially useful if you are migrating to Mill, as during the migration a particular module may be built using both Maven/Gradle and Mill at the same time. That means that during migration, you can leave all your source files in place while setting up your Mill build, and do not need to invasively move them around to match the Mill default module layout.

Although the source layout of these compatibility modules is different from the default JavaModule, the command-line usage is the same:

For more details on migrating from other build tools, see Migrating to Mill

Script files can have test suites, usually written in a separate test script. The test script specifies what script it tests via moduleDeps, and can have its own mvnDeps in addition to those of the upstream script. The test script can then exercise functions from the upstream script as shown below:

Again, you can pass the name of the task explicitly via :, e.g. :testForked below

The testing framework used in a script is defined by the class specified in the extends clause. The different testing frameworks supported in Testing Java Projects can be used for your scripts: Junit4, Junit5, TestNg, Munit, ScalaTest, Specs2, Utest, Weaver, ZioTest. If you need something not on this list, you can define a Custom Script Module Class.

For scripts that grow larger than a single file, you should convert them to Simple Config-Based Modules.

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

This generated line-count.txt file can then be loaded and used at runtime, as see in the output of mill run below.

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.

Custom user-defined tasks in Mill such as def lineCount above benefit from all the same things that built-in tasks do: automatic caching (in the out/ folder), parallelism (configurable via -j/--jobs flag), inspectability (via show and 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.

This is similar to the Multi-Module Projects example above, but using Mill’s programmatic configuration syntax. 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 works like a class in Java, and lets us avoid the need to copy-paste common settings, while still letting us define any per-module configuration such as mvnDeps specific to a particular module. This is a common pattern within Mill builds.

You can also put the configuration for each submodule in it’s respective folder’s package.mill file, as described in Multi-File Builds. This can be helpful in larger projects to avoid having your build.mill grow large, and aid in discoverability by keeping the build configuration for each module close to the code it is configuring

This example is similar to the Maven-Compatible Modules above, but using Mill’s programmatic build.mill files. These are more flexible than the config-driven build.mill.yaml files, and can contain Custom Build Logic and other programmatic configuration