= Import Libraries and Plugins
:page-aliases: Import_File_And_Import_Ivy.adoc, Using_Plugins.adoc


This page illustrates usage of the `//| mvnDeps` syntax.
`//| mvnDeps` lets you import JVM dependencies into your `build.mill`, so
you can use arbitrary third-party libraries at build-time. This lets you perform computations at build-time rather than run-time,
speeding up your application start up. Unlike most other build tools that
require purpose-built plugins to extend them, Mill's `//| mvnDeps` can be used to pull
in any JVM library on Maven Central to use in your custom tasks, with
xref:extending/thirdparty-plugins.adoc[Third-Party Plugins] only necessary for
more sophisticated integrations.


[#_importing_java_libraries]
== Importing Java Libraries

include::partial$example/extending/imports/1-mvn-deps.adoc[]


[#_importing_scala_libraries]
== Importing Scala Libraries

include::partial$example/extending/imports/2-mvn-deps-scala.adoc[]

== Importing Plugins

Mill plugins are ordinary JVM libraries jars and are loaded as any other external dependency with
the `//| mvnDeps` mechanism.

There exist a large number of Mill plugins. Many of them are available on GitHub and via
Maven Central. We also have a list of plugins, which is most likely not complete, but it
might be a good start if you are looking for plugins: xref:Thirdparty_Plugins.adoc[].

Some plugin contributions are also hosted in Mill's own git tree as xref:Contrib_Plugins.adoc[].

Mill plugins are typically bound to a specific version range of Mill.
This is called the binary platform. To ease the use of the correct versions and avoid runtime
issues (caused by binary incompatible plugins, which are hard to debug) you can apply one of the
following techniques:

=== Use the specific Mill Binary Platform notation

[source,scala]
----
//| # for classic Scala dependencies
//| mvnDeps: ["<group>::<plugin>::<version>"]  // <1>
//| # for dependencies specific to the exact Scala version
//| mvnDeps: ["<group>:::<plugin>::<version>"] // <2>
----
<1> This is equivalent to
+
[source,scala]
----
//| mvnDeps: ["<group>::<plugin>_mill$MILL_BIN_PLATFORM:<version>"]  // <1>
----
<2> This is equivalent to
+
[source,scala]
----
//| mvnDeps: ["<group>:::<plugin>_mill$MILL_BIN_PLATFORM:<version>"]  // <1>
----


=== Use special placeholders in your `//| mvnDeps`

`$MILL_VERSION` ::
+
--
to substitute the currently used Mill version.
This is typical required for Mill contrib modules, which are developed in the Mill repository and highly bound to the current Mill version.

.Example: Use `mill-contrib-buildinfo` plugin matching the current Mill version
[source,scala]
----
//| mvnDeps: ["com.lihaoyi::mill-contrib-buildinfo:$MILL_VERSION"]
----

// There is the even more convenient option to leave the version completely empty.
// Mill will substitute it with its current version.
// But don't forget to provide the trailing colon!

// .Example: Use `mill-contrib-buildinfo` plugin matching the current Mill version
// [source,scala]
// ----
// //| mvnDeps: ["com.lihaoyi::mill-contrib-buildinfo:$MILL_VERSION"]
// ----
--

`$MILL_BIN_PLATFORM` ::
+
--
to substitute the currently used Mill binary platform.

.Example: Using `mill-vcs-version` plugin matching the current Mill Binary Platform
[source,scala]
----
//| mvnDeps: ["de.tototec::de.tobiasroeser.mill.vcs.version_mill$MILL_BIN_PLATFORM:0.1.2"]
----
--

TIP: If you want to publish re-usable libraries that _other_ people can use in their
builds, simply publish your code as a library to maven central.

The `//| mvnDeps` and `//| repositories` build headers are a shorthand for overriding
configuring on xref:extending/meta-build.adoc[].
