Migrating From sbt to Mill

The Mill init command can be used to convert an sbt build to Mill. This has limitations and is not intended to reliably migrate 100% of sbt builds out there in the wild, but is instead meant to provide the basic scaffolding of a Mill build for you to further refine and update manually.

Each sbt project in a build tree is converted to a Mill module. A nested test module is defined, if src/test exists, and is configured with a supported test framework, if found.

Again, note that mill init imports an sbt build on a best-effort basis. This means that while simple projects can be expected to complete without issue:

> rm build.mill # remove any existing build file

> git init .
> git remote add -f origin https://github.com/scala/scala3-example-project.git
> git checkout 853808c50601e88edaa7272bcfb887b96be0e22a

> ./mill init
converting sbt build
Running the added `millInitExportBuild` sbt task to export the build
converting module scala3-example-project
generated 1 Mill build file(s)
removing existing Mill build files
writing Mill build file to build.mill
converted sbt build to Mill
formatting Mill build files
Formatting 1 Scala sources
parsed config (v3.8.4): ...
init completed, run "mill resolve _" to list available tasks

> ./mill compile
compiling 13 Scala sources to ...

> ./mill test
MySuite:
  + example test that succeeds ...

Projects with a complex build often require some manual tweaking in order to work:

> rm build.mill # remove any existing build file

> git init .
> git remote add -f origin https://github.com/tototoshi/scala-csv.git
> git checkout 2.0.0

> ./mill init
converting sbt build
Running the added `millInitExportBuild` sbt task to export the build
converting module scala-csv
generated 1 Mill build file(s)
removing existing Mill build files
writing Mill build file to build.mill
converted sbt build to Mill
formatting Mill build files
Formatting 1 Scala sources
parsed config (v3.8.4): ...
init completed, run "mill resolve _" to list available tasks

> ./mill compile # You will have to further configure the `CrossScalaModule` for different Scala versions
compiling 7 Scala sources and 3 Java sources to ...
error: class CSVReader protected (private val lineReader: LineReader)(implicit format: CSVFormat) extends Closeable with CSVReaderCompat {
error:                                                                                                                   ^
error: one error found

Capabilities

The conversion

  • handles deeply nested modules

  • captures publish settings

  • configures dependencies for configurations:

    • no configuration

    • Compile

    • Test

    • Runtime

    • Provided

    • Optional

  • configures testing frameworks:

    • Java:

      • JUnit 4

      • JUnit 5

      • TestNG

    • Scala:

      • ScalaTest

      • Specs2

      • µTest

      • MUnit

      • Weaver

      • ZIOTest

      • ScalaCheck

Command line arguments

The conversion and its output (the generated Mill build files) can be customized using

  • --base-module (-b): name of generated base module trait defining shared settings

    ./mill init --base-module MyModule

  • --test-module (-t): name of generated nested test module (defaults to test)

    ./mill init --test-module test

  • --deps-object (-d): name of generated companion object defining dependency constants

    ./mill init --deps-object Deps

  • --merge (-m): merge build files generated for a multi-module build

    ./mill init --merge
You can run mill init multiple times. It is recommended to run it first without any options.

Limitations

The conversion does not support:

  • custom dependency configurations

  • custom settings including custom tasks

  • sources other than Scala on JVM and Java, such as Scala.js and Scala Native

  • cross builds

sbt plugin support is limited to:

These limitations can be overcome by:

FAQ

How to fix errors such as java.lang.UnsupportedOperationException: The Security Manager is deprecated and will be removed in a future release, java.io.IOError: java.lang.RuntimeException: /packages cannot be represented as URI, and java.lang.RuntimeException: java.lang.reflect.InvocationTargetException thrown by the sbt command invoked by mill init?

Update the project’s sbt version to the latest or our tested version v1.10.10, and check whether you have the appropriate Java version, and try again.

How to fix test compilation errors?

  • The test framework configured may be for an unsupported version; try upgrading the corresponding dependencies.

  • Mill does not add compileIvyDeps dependencies to the transitive dependencies of the nested test module; specify the dependencies again, in ivyDeps or runIvyDeps.