Build Header Config
Mill supports a YAML comment block at the top of the build.mill
file to configure
your project. This must be at the very top of the build.mill
file in YAML 1.2
syntax, with every line prepended with //|
, with YAML comments and newlines
allowed. This contains Mill configuration that needs to take effect before the
body of the build.mill
file has been compiled and loaded.
For example, a build header may look something like:
//| mill-version: {mill-version}
//| # yaml comments are allowed in the build header
//| mill-opts: ["--jobs=0.5C"]
//| mill-jvm-version: temurin:11
//| mill-jvm-opts: ["-XX:NonProfiledCodeHeapSize=250m", "-XX:ReservedCodeCacheSize=500m"]
//| # newlines are allowed too
//|
//| repositories:
//| - https://oss.sonatype.org/content/repositories/snapshots
//| mvnDeps:
//| - com.goyeau::mill-scalafix::0.5.1-14-4d3f5ea-SNAPSHOT
package build
...
Mill’s build headers can contain the following keys:
-
mill-version: this must be unquoted in the first line of the build header, and specifies the version of Mill used in this project.
-
mill-opts: flags to pass to Mill by default, useful for flags that you want everyone to use so they don’t need to always remember to type them at the command line
-
mill-jvm-version: specifies an explicit JVM version to use, useful to help keep the build reproducible even when run on different machines.
-
mill-jvm-opts: flags to pass to Mill’s background daemon JVM process, e.g. to configure how much memory to give it
-
mvnDeps
andrepositories
: these allow you to define dependencies for usage in yourbuild.mill
, and are described in more detail in the Import Libraries and Plugins page. Other keys are allowed as well, and these are uniformly treated as overrides for tasks on The Mill Meta-Build
mill-version
, mill-opts
, mill-jvm-version
, and mill-jvm-opts
can also be
provided as standalone files on disk (e.g. .mill-version
) for compatibility with
older versions of Mill, or the .config
folder (e.g. .config/mill-version
)
following the .config
XDG Base Directory Standard
mill-opts
Mill supports mill-opts
for passing a default set of command line
options to Mill itself. For example, if your project’s tasks are CPU heavy, you
may want everyone using your project to run only 0.5 concurrent tasks per CPU. This
can be done by adding your build header:
build.mill
//| mill-opts: ["--jobs=0.5C"]
The file name .mill-opts
can be overridden via the MILL_OPTS_PATH
environment variable.
You can also pass in flags like --jobs=10
explicitly to override the value passed in
.mill-opts
. See Mill Command-Line Flags for documentation on what
flags the Mill executable can take.
.mill-opts is for passing options to Mill itself, and .mill-jvm-opts is for passing
JVM options to the JVM running Mill. If you want to pass JVM options to the project that Mill
is building and running, see the section on
Compilation and Execution Flags.
|
mill-jvm-version
Mill allows you to specify the exact JVM version you want to use to run the build tool
via a mill-jvm-version
key in the build header, which also becomes the default
version used for any JVMs spawned by Mill to run
or test
your project:
build.mill
//| mill-jvm-version: temurin:17.0.6
An explicit mill-jvm-version
can help ensure your project uses a consistent JVM version and
behaves identically regardless of what the developer may have installed on their laptop
or dev environment. If mill-jvm-version
is not provided, Mill uses the globally-installed
java
installation if there is one present on your PATH
, and otherwise will download and
cache a default version of Java for usage.
For configuring different JVM versions for individual modules within your build, see Configuring JVM Versions.
mill-jvm-opts
Mill supports mill-jvm-opts
to set JVM-level flags
It’s possible to pass JVM options to the Mill launcher.To do this you can either set
the JAVA_OPTS
environment variable, Build Header Config, or create a .mill-jvm-opts
file in your project’s
root that contains JVM options one per line.
For example, if your build requires a lot of memory and bigger stack size, you could run
> JAVA_OPTS='-Xss10m -Xmx10G' ./mill __.compile
Build header metadata:
build.mill
//| mill-jvm-opts: ["-Xss10m", "-Xmx10G"]
mill-jvm-opts
also supports environment variable interpolation, e.g.
-Dmy.jvm.property=${PWD}
Missing environment variables are converted to the empty string.
Meta-build Task Overrides
You can use the build header to override arbitrary tasks in The Mill Meta-Build,
which is responsible for compiling your build.mill
file. Apart from customizing
mvnDeps
and repositories
to make libraries available in your build.mill
,
you can also override other tasks such as scalacOptions
which in this example
is used to turn on fatal warnings for unused private methods:
//| scalacOptions: ["-Wunused:privates", "-Xfatal-warnings"]
package build
import mill.*, javalib.*
private def foo = 1
> ./mill version
error: ...unused private member
...No warnings can be incurred under -Werror (or -Xfatal-warnings)
As the build.mill
file is written in Scala, most tasks you override on
ScalaModule
can be set in the build header to apply to your build.mill
.