com-lihaoyi/mill: Your shiny new Java/Scala build tool!

= image:docs/logo.svg[Mill Logo] Mill :toc-placement: preamble :toc: :link-github: https://github.com/com-lihaoyi/mill :link-gitter: https://gitter.im/lihaoyi/mill :link-current-doc-site: http://com-lihaoyi.github.io/mill :link-milestone: https://github.com/com-lihaoyi/mill/milestone :link-compare: https://github.com/com-lihaoyi/mill/compare :link-pr: {link-github}/pull :link-issue: {link-github}/issues :example-scala-version: 3.0.2

{link-github}/actions/workflows/actions.yml[image:{link-github}/actions/workflows/actions.yml/badge.svg[Build and Release]] {link-gitter}?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge[image:https://badges.gitter.im/Join%20Chat.svg[Gitter Chat]] https://index.scala-lang.org/com-lihaoyi/mill/mill-main[image:https://index.scala-lang.org/com-lihaoyi/mill/mill-main/latest.svg[Mill]] https://www.patreon.com/lihaoyi[image:https://img.shields.io/badge/patreon-sponsor-ff69b4.svg[Patreon]]

Your shiny new Scala build tool! Confused by SBT? Frustrated by Maven? Perplexed by Gradle? Give Mill a try!

== Documentation

If you want to use Mill in your own projects, check out our documentation:

{link-current-doc-site}[Documentation]

Here is some quick example, so that you can imagine how it looks:

[source,scala,subs="verbatim,attributes"]

import mill., scalalib.

object foo extends ScalaModule { def scalaVersion = "{example-scala-version}" }

object bar extends ScalaModule { def moduleDeps = Seq(foo) def scalaVersion = "{example-scala-version}" }

If you use Mill and like it, you will probably enjoy the following book by the Author:

https://www.handsonscala.com/[Hands-on Scala Programming]

Hands-on Scala has a Chapter 10: Static Build Pipelines dedicated to Mill, but rest of the book introduces other libraries and tools in a similar style. Hands-on Scala is a great way to level up your skills in Scala in general and Mill in particular

The remainder of this readme is developer-documentation targeted at people who wish to work on Mill's own codebase. The developer docs assume you have read through the user-facing documentation linked above. It's also worth spending a few minutes reading the following blog posts to get a sense of Mill's design & motivation:

http://www.lihaoyi.com/post/SowhatswrongwithSBT.html["So, what's wrong with SBT?"]
http://www.lihaoyi.com/post/BuildToolsasPureFunctionalPrograms.html[Build Tools as Pure Functional Programs]
http://www.lihaoyi.com/post/MillBetterScalaBuilds.html[Mill: Better Scala Builds]

Mill is profiled using the https://www.ej-technologies.com/products/jprofiler/overview.html[JProfiler Java Profiler], by courtesy of EJ Technologies.

== How to build and test

Mill is built using Mill. To begin, first download & install Mill as described in the documentation above. As Mill is under active development, stable releases may not be able to build the current development branch of Mill. It is recommended to install the latest unstable release manually.

=== IntelliJ Setup

If you are using IntelliJ IDEA to edit Mill's Scala code, you can create the IntelliJ project files via:

[source,bash]

./mill mill.scalalib.GenIdea/idea

=== Automated Tests

To run test suites:

[source,bash]

./mill main.test ./mill scalalib.test ./mill scalajslib.test ./mill integration.test

=== Manual Testing

To manually test Mill on a small build, you can use the scratch folder:

[source,bash]

./mill -i dev.run scratch -w resolve _

This runs the task resolve _ with your current checkout of Mill on the trivial build defined in scratch/build.sc. You can modify that build file to add additional modules, files, etc. and see how it behaves.

More generally, you can use:

[source,bash]

./mill -i dev.run [target-dir] [...args]

To create run your current checkout of Mill in the given target-dir with the given args. This is useful e.g. to test a modified version of Mill on some other project's Mill build.

You can also create a launcher-script to let you run the current checkout of Mill without the bootstrap Mill process present:

[source,bash]

./mill dev.launcher

This creates the out/dev/launcher.dest/run launcher script, which you can then use to run your current checkout of Mill where-ever you'd like. Note that this script relies on the compiled code already present in the Mill out/ folder, and thus isn't suitable for testing on Mill's own Mill build since you would be over-writing the compiled code at the same time as the launcher script is using it.

You can also run your current checkout of Mill on the build in your scratch/ folder without the bootstrap Mill process being present via:

[source,bash]

./mill dev.launcher && (cd scratch && ../out/dev/launcher.dest/run -w show thingy)

=== Bootstrapping: Building Mill with your current checkout of Mill

To test bootstrapping of Mill's own Mill build using a version of Mill built from your checkout, you can run

[source,bash]

./mill installLocal

This creates a standalone assembly at target/mill-release you can use, which references jars published locally in your ~/.ivy2/local cache. You can then use this standalone assembly to build & re-build your current Mill checkout without worrying about stomping over compiled code that the assembly is using.

This assembly is design to work on bash, bash-like shells and Windows Cmd. If you have another default shell like zsh or fish, you probably need to invoke it with sh ~/mill-release or prepend the file with a proper shebang.

If you want to install into a different location or a different Ivy repository, you can set it's optional parameters

.Install into `/tmp` [source,bash]

$ ./mill inspect installLocal [1/1] inspect installLocal(build.sc:865) Build and install Mill locally. @param binFile The location where the Mill binary should be installed @param ivyRepo The local Ivy repository where Mill modules should be published to ... $ ./mill installLocal --binFile /tmp/mill --ivyRepo /tmp/millRepo ... Published 44 modules and installed /tmp/mill

=== Troubleshooting

In case of troubles with caching and/or incremental compilation, you can always restart from scratch removing the out directory:

[source,bash]

os.remove.all -rf out/

== Project Layout

The Mill project is organized roughly as follows:

=== Core modules that are included in the main assembly

core, main, main.client, scalalib, scalajslib.

These are general lightweight and dependency-free: mostly configuration & wiring of a Mill build and without the heavy lifting.

Heavy lifting is delegated to the worker modules (described below), which the core modules resolve from Maven Central (or from the local filesystem in dev) and load into isolated classloaders.

=== Worker modules that are resolved from Maven Central

scalalib.worker, scalajslib.worker[0.6], scalajslib.worker[1.0]

These modules are where the heavy-lifting happens, and include heavy dependencies like the Scala compiler, Scala.js optimizer, etc.. Rather than being bundled in the main assembly & classpath, these are resolved separately from Maven Central (or from the local filesystem in dev) and kept in isolated classloaders.

This allows a single Mill build to use multiple versions of e.g. the Scala.js optimizer without classpath conflicts.

=== Contrib modules

contrib/bloop/, contrib/flyway/, contrib/scoverage/, etc.

These are modules that help integrate Mill with the wide variety of different tools and utilities available in the JVM ecosystem.

These modules are not as stringently reviewed as the main Mill core/worker codebase, and are primarily maintained by their individual contributors. These are maintained as part of the primary Mill Github repo for easy testing/updating as the core Mill APIs evolve, ensuring that they are always tested and passing against the corresponding version of Mill.

== Changelog

=== 'main' branch :version: main :prev-version: 0.10.7 :milestone: 67 :milestone-name: after 0.10.7

Changes since {prev-version}: