= Automated Migration Tools
:icons: font



The Mill `init` command can be used to convert a Maven, Gradle, or SBT build to Mill.
This has xref:#limitations[limitations] and is not intended to reliably migrate 100% of
existing 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 Maven module with a `pom.xml`, Gradle module with a `.gradle` file, or SBT module
is converted to a Mill `build.mill`/`package.mill` file containing a top-level `MavenModule`
or `SbtModule`. A nested `test` module is defined, if `src/test` exists, and is configured
with a supported xref:javalib/testing.adoc[test framework], if found.

Again, note that `mill init` importing Maven builds is best-effort.
This means that while small projects can be expected to complete without issue:

**Maven**

include::partial$example/migrating/javalib/1-maven-complete.adoc[]

**Gradle**

include::partial$example/migrating/javalib/4-gradle-complete.adoc[]

**SBT**

include::partial$example/migrating/scalalib/1-sbt-complete.adoc[]

Larger projects often require some manual tweaking in order to work:

**Maven**

include::partial$example/migrating/javalib/2-maven-incomplete.adoc[]

**Gradle**

include::partial$example/migrating/javalib/5-gradle-incomplete.adoc[]

**SBT**

include::partial$example/migrating/scalalib/2-sbt-incomplete.adoc[]

Nevertheless, even for larger builds `mill init` automates most of the tedious
busy-work of writing `build.mill`/`package.mill` files, and makes it much quicker
to get a working Mill build for any existing  project. For example,
the `iluwatar/java-design-patterns` repo has 363 subprojects
(including test projects) and `./mill init` is able to get it imported,
compiling, and passing all tests in Mill:

include::partial$example/migrating/javalib/3-maven-complete-large.adoc[]

== Usage

xref:cli/installation-ide.adoc[Install] `mill` in your project directory and run:
[source,sh]
----
./mill init
----

This will generate Mill build files `build.mill` and `package.mill` for the root module and all nested modules, respectively. Additionally, meta-build files containing shared configurations are added in the `mill-build` directory.

To set a custom value for xref:cli/build-header.adoc#_mill_jvm_version[mill-jvm-version] in the generated `build.mill` file, run:
[source,sh]
----
./mill init --mill-jvm-id 25
----

The init command can be run multiple times with any combination of options. To list all available options, run:
[source,sh]
----
./mill init --help
----

[#limitations]
== Limitations

The conversion does not support

* build extensions
* build profiles
* non-Java sources

[TIP]
====
These limitations can be overcome by:

* configuring equivalent Mill xref:extending/contrib-plugins.adoc[contrib]
  or xref:extending/thirdparty-plugins.adoc[third party] plugins
* defining custom xref:extending/writing-plugins.adoc[plugins]
* defining custom xref:fundamentals/tasks.adoc[tasks]
* defining custom xref:fundamentals/cross-builds.adoc[cross modules]
====

== FAQ

=== How to fix compilation errors in generated build files?

This could happen if a module and task name collision occurs. Either rename the module or enclose the name in backticks.

=== How to fix JPMS `module not found` compilation errors?

Add https://github.com/tfesenko/Java-Modules-JPMS-CheatSheet#how-to-export-or-open-a-package[options]
for Java modules to `javacOptions`.

=== 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 `compileMvnDeps` dependencies to the transitive dependencies of the nested
test module; specify the dependencies again, in `mvnDeps` or `runMvnDeps`.

=== `java.io.IOError: java.lang.RuntimeException: /packages cannot be represented as URI`

This error:
`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.