Installation & IDE Support
The standard method of installing Mill is to install a ./mill
bootstrap script,
similar to ./gradlew
or ./mvnw
in other build tools.
This script can determine the best version to be used by a project (e.g. by
reading a .mill-version
) and will use this exact Mill version.
If the determined Mill version is not installed locally, it will be downloaded automatically.
For all the examples in this documentation, there is a download
link that provides
a zip file containing the full example ready to use. These examples come with a ./mill
script you can use to immediately begin working with the project, needing only a JVM installed
globally.
Bootstrap Scripts
Although the Mill example projects come with their own ./mill
bootstrap script,
you can also download it manually:
curl -L https://github.com/com-lihaoyi/mill/releases/download/0.12.3/0.12.3 > mill && chmod +x mill
echo 0.12.3 > .mill-version
Downloading a mill
bootstrap script to the root of your project repository helps make it easier for
new contributors to build your project, as they don’t have to install Mill before they can start.
Anyone who wants to work with the project can simply use the ./mill
script directly.
./mill --version
./mill __.compile # double underscore
In general, bootstrap scripts are the recommended way of installing Mill.
Similar to ./gradlew
or ./mvnw
, the ./mill
bootstrap script
reduces the chance of errors due to the installed version of Mill
being incompatible with the version expected by your build.
In-project bootstrap scripts are also useful for running Mill in CI/CD, ensuring
that your build server like Jenkins or Github Actions has the correct version of Mill
present to build, compile or test your code.
If you are starting a new project using a Mill bootstrap script, you can use the mill init to initialize the project folder with one of the Mill example projects. There are a wide range of example projects, from hello-world to multi-module libraries to client-server web applications, and you can pick one most similar to what you are doing so you can hit the ground running working.
Windows
If you are running on Windows, you should use lefou/millw
as a drop-in replacement for ./mill
that supports running on all major platforms including MS Windows.
./millw
will likely be merged into ./mill
in the near future.
IDE Support
Mill supports IntelliJ and VSCode and in general any client of the standard Build Server Protocol (BSP).
To prepare your project for IDEs, and in general any BSP client, you can run this command to generate the BSP configuration files:
./mill mill.bsp.BSP/install
Your IDEs may already auto-detect the Mill project and run this command on behalf of you, when opening/importing the project.
IntelliJ
To use Mill with IntelliJ, first ensure you have the free IntelliJ Scala Plugin installed. This is necessary as Mill build files are written in Scala, even if you are using it to build a Java or Kotlin project.
Once you have the plugin installed, you can use IntelliJ to open any project
containing a Mill build.mill
file, and IntelliJ will automatically load the
Mill build. If you have multiple build systems installed, Intellij may give you
choice which build system configuration to use for the import, which case select BSP
:
This will provide support both for your application code,
as well as the code in the build.mill
:
If IntelliJ does not highlight the .mill
files correctly, you can explicitly enable
it by adding *.mill
to the Scala
file type:
If you make changes to your Mill build.mill
, you can ask Intellij to load
those updates by opening the "BSP" tab and clicking the "Refresh" button
IntelliJ IDEA XML Support
Apart from using the Build Server Protocol, you can also generate IDEA project files directly with Mill. This is probably the preferred way if you work on polyglot projects and need support for frameworks like AspectJ, which are currently not specifically configured over BSP.
To generate IntelliJ IDEA project files into .idea/
, run:
./mill mill.idea.GenIdea/
This will generate the XML files IntelliJ uses to configure your project
.idea
.idea/scala_settings.xml
.idea/mill_modules
.idea/mill_modules/.iml
.idea/mill_modules/mill-build.iml
.idea/mill_modules/test.iml
.idea/libraries
.idea/libraries/mill_scalalib_2_13_0_11_10_jar.xml
...
.idea/workspace.xml
.idea/modules.xml
.idea/scala_compiler.xml
.idea/misc.xml
After the files are generated, you can open the folder in IntelliJ to load the project
into your IDE. If you make changes to your Mill build.mill
, you can update the project config
those updates by running ./mill mill.idea.GenIdea/
again.
VSCode
To use Mill with VSCode, first ensure you have the free Metals VSCode Scala language server installed. This is necessary as Mill build files are written in Scala, even if you are using it to build a Java project.
Mill in VSCode only supports Java and Scala. Kotlin users are advised to use the free IntelliJ IDEA Community Edition |
Once you have the language server installed, you can ask VSCode to open any folder
containing a Mill build.mill
file, and VSCode will ask you to import your
Mill build. This will provide support both for your application code,
as well as the code in the build.mill
:
If you make changes to your Mill build.mill
, you can ask VSCode to load
those updates by opening the "BSP" tab and clicking the "Refresh" button
Other Editors / Metals
A lot of other editors may work too, since Metals, the Language Server for Scala has built-in support for BSP. See the general instructions above.
Debugging IDE issues
Mill’s BSP IDE integration writes to a log file under
.bsp/mill-bsp.stderr
, where you can find various information about what’s
going on. It contains regular Mill output accompanied by additional BSP
client-server communication details. This can be useful to look at if your
IDE fails to import your Mill project
Updating Mill
Typically, most Mill projects use a .mill-version
file to configure what version
to use. You can update the version specified in this file in order to change the version
of Mill. The file path .config/mill-version
is also supported. If neither is provided,
the ./mill
bootstrap script will use the DEFAULT_MILL_VERSION
it has built in.
To choose a different Mill version on an ad-hoc basis, e.g. for experimentation, you can pass
in a MILL_VERSION
environment variable, e.g.
MILL_VERSION=0.5.0-3-4faefb mill __.compile
or
MILL_VERSION=0.5.0-3-4faefb ./mill __.compile
to override the Mill version manually. This takes precedence over the version
specified in ./mill
, .config/mill-version
or .mill-version
Working without access to Maven Central
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 tasks 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 artifacts. 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 pass the environment variable to the mill
command.
COURSIER_REPOSITORIES=https://packages.corp.com/artifactory/maven/ mill resolve _
If you are using bootstrap script, a more permanent solution could be to set the environment variable at the top of the bootstrap script, or as a user environment variable etc.
Automatic Mill updates
If your project is hosted on GitHub, GitLab, or Bitbucket, you can use
Scala Steward to
automatically open a pull request to update your Mill version (in
.mill-version
or .config/mill-version
file), whenever there is a newer version available.
Scala Steward can also scan your project dependencies and keep them up-to-date. |
Development Releases
In case you want to try out the latest features and improvements that are
currently in the main branch, unstable versions of Mill
are
available as binaries named
#.#.#-n-hash
linked to the latest tag.
The easiest way to use a development release is to use one of the
Bootstrap Scripts, which support overriding Mill versions via an
MILL_VERSION
environment variable or a .mill-version
or .config/mill-version
file.
Other installation methods
The installation methods listed below are maintained outside of Mill and may not have the same features as the bootstrap scripts. You can try using them, but the officially supported way to use Mill is via the bootstrap script above, so the Mill maintainers may be unable to help you if you have issues with some alternate installation method. |
Some of the installations via package managers install a fixed version of Mill and
do not support project-specific selection of the preferred Mill version. If you want to use
the MILL_VERSION environment variable or need support for .mill-version or
.config/mill-version files to control the actual used Mill version, please use
a bootstrap script instead.
|
Windows
To get started, download Mill from
Github releases, and save it as mill.bat
.
If you’re using Scoop you can install Mill via
scoop install mill
WSL / MSYS2 / Cycgin / Git-Bash
Mill also works on "sh" environments on Windows (e.g., MSYS2, Cygwin, Git-Bash, WSL); to get started, follow the instructions in the Manual section. Note that:
-
In some environments (such as WSL), Mill might have to be run without a server (using
-i
,--interactive
, or--no-server
.) -
On Cygwin, run the following after downloading mill:
sed -i '0,/-cp "\$0"/{s/-cp "\$0"/-cp `cygpath -w "\$0"`/}; 0,/-cp "\$0"/{s/-cp "\$0"/-cp `cygpath -w "\$0"`/}' /usr/local/bin/mill
Docker
You can download and run a "Docker image containing OpenJDK, Scala and Mill" using
docker pull nightscape/scala-mill
docker run -it nightscape/scala-mill
Manual
To get started, download Mill and install it into your HOME ".local/bin" via the following
curl
/chmod
command:
sh -c "curl -L https://github.com/com-lihaoyi/mill/releases/download/0.12.3/0.12.3 > ~/.local/bin/mill && chmod +x ~/.local/bin/mill"
Coursier (unsupported)
Installing mill via coursier
or cs
is currently not officially supported.
There are various issues, especially with interactive mode.
Asdf (unsupported)
You can install and manage Mill via the Multiple Runtime Version Manager - asdf
.
Support by asdf
is currently possible by using the asdf-mill
plugin:
mill
plugin and Mill with asdf
---
asdf plugin add mill
asdf install mill latest
asdf global mill latest
---