Library Dependencies in Mill

Mill dependencies have the form:

When working in other Java and Scala projects, you will find some synonyms, which typically all mean the same.

For example in the Maven ecosystem, the organization is called the group and the name is called the artifact. The whole tripplet is ofthe called GAV.

In Mill we use the additional term artifactId which is identical to the name when used in the normal form shown above. When a different form is used, e.g. some double-colons are used between the parts, the artifactId typically contains suffixes, but the name doesn’t.

Scala major releases up until version 2.13 are binary incompatible. That means, mixing dependencies of different binary platforms will result in non-working runtimes and obscure and hard to debug issues.

To easily pick only a compatible version, a convention was established to append the scala major version as a suffix to the package name.^[1] E.g. to select the Scala 2.13 version of a library foo, the final artifactId will contain the additional suffix _2.13, such that the final artifactId is foo_2.13.

To always pick the right version and support cross compiling, you can omit the scala version and instead use a double colon (::) between the organization and the name, e.g. ivy"com.typesafe.akka:akka-actor_2.12:2.5.25". Your module needs to extends ScalaModule though.

If you want to use dependencies that are cross-published against the full Scala version, e.g. 2.12.12, you can use three colons (:::) between organization and name, e.g.: ivy"org.scalamacros:::paradise:2.1.1".

Since the release of Scala 3, the binary compatibility story for Scala has changed. That means, Scala 3 dependencies can be mixed with Scala 2.13 dependencies. In fact, the Scala 3 standard library is the same as for Scala 2.13.

One difference between Mill and other build tools like sbt or Maven is the fact, that tests are ordinary submodules on their own. For convenience, most modules already come with a pre-configured trait for a test submodule, which already inherits all dependencies of their parent module. If you need additional test dependencies, you simply add them by overriding def ivyDeps, as you would do with normal library dependencies.

When migrating a sbt project and seeing a dependency like this: "ch.qos.logback" % "logback-classic" % "1.2.3" % "test", simply add it to the test module’s ivyDeps as ordinary dependency. There is no special test scope in Mill.

If you want to use a dependency only at compile time, you can declare it with the compileIvyDeps target.

When Mill generated file to interact with package manager like pom.xml for Maven repositories, such compile-only dependencies are mapped to the provided scope.

Please note, that dependencies with provided scope will never be resolved transitively. Hence, the name "provided", as the target runtime needs to "provide" them, if they are needed.

If you want to declare dependencies to be used at runtime (but not at compile time), you can use the runIvyDeps targets.

It is also possible to use a higher version of the same library dependencies already defined in ivyDeps, to ensure you compile against a minimal API version, but actually run with the latest available version.

To render a tree of dependencies (transitive included) you can run mill myModule.ivyDepsTree. Here is how the start of ./mill __.ivyDepsTree looks like in the mill project itself:

After compiling your module(s) you can find and examine files such as ivyDeps.json and transitiveIvyDeps.json in your out build’s folder for a given module. After running the ivyDepsTree command you’ll also find the ivyDepsTree.json and ivyDepsTree.log file that contain the output of the above ivyDepsTree command.

You can observe the actual version being used by running mill show myModule.resolvedIvyDeps. If you run mill myModule.resolvedIvyDeps, the same information is available in out/myModule/resolvedIvyDeps.json.

You can use the .exclude method on a dependency. It accepts organization and name tuples, to be excluded. Use the special name * to match all organizations or names.

You can also use .excludeOrg or excludeName:

Note: You can chain multiple exclusions with exclude, excludeOrg, and excludeName.

You can use the forceVersion method to ensure the used version of a dependency is what you have declared.

Scala.js introduces an additional binary platform axis. To the already required Scala version, there comes the Scala.js version.

You can use two colons (::) between name and version to define a Scala.js dependency. Your module needs to extends ScalaJSModule to accept Scala.js dependencies.

Scala Native introduces an additional binary platform axis. To the already required Scala version, there comes the Scala Native version.

You can use two colons (::) between name and version to define a Scala Native dependency. Your module needs to extends ScalaNativeModule to accept Scala Native dependencies.