= Scala Module Configuration
:page-aliases: Configuring_Mill.adoc, Scala_Module_Config.adoc
:language: Scala
:language-small: scala
:language-doc: scaladoc

This page goes into more detail about the various configuration options
for `ScalaModule`.

Many of the APIs covered here are listed in the Scaladoc:

* {mill-doc-url}/api/latest/mill/scalalib/ScalaModule.html[mill.scalalib.ScalaModule]

== Declarative Configuration

include::partial$example/scalalib/module/1-basic-config.adoc[]

=== Scala Compiler Plugins

include::partial$example/scalalib/module/2-scala-compiler-plugins.adoc[]

=== Scaladoc Config

include::partial$example/scalalib/module/3-docjar.adoc[]

== Programmable Configuration

include::partial$example/scalalib/module/4-programmable-config.adoc[]

=== Custom Tasks

include::partial$example/scalalib/module/5-custom-tasks.adoc[]

=== Generated Sources

include::partial$example/scalalib/module/6-generated-sources.adoc[]

=== Classpath and Filesystem Resources

include::partial$example/scalalib/module/7-resources.adoc[]

=== Cross-Scala-Version Modules

include::partial$example/scalalib/module/14-cross-scala-version.adoc[]

=== Unidoc

include::partial$example/scalalib/module/15-unidoc.adoc[]


=== Using the Ammonite Repl / Scala console

All ``ScalaModule``s have a `console` and a `repl` task, to start a Scala console or an Ammonite Repl.

When using the `console`, you can configure its `scalac` options using the `consoleScalacOptions` task.

For example, you may want to inherit all of your regular `scalacOptions` but disable `-Xfatal-warnings`:

.Example: Using `consoleScalacOptions` to disable fatal warnings
[source,scala,subs="attributes,verbatim"]
----
import mill.*, scalalib.*

object foo extends ScalaModule {
  def consoleScalacOptions = scalacOptions().filterNot(o => o == "-Xfatal-warnings")
}
----

To use the `repl`, you can (and sometimes need to) customize the Ammonite version to work with your selected Scala version.
Mill provides a default Ammonite version,
but depending on the Scala version you are using, there may be no matching Ammonite release available.
In order to start the repl, you may have to specify a different available Ammonite version.

.Example: Overriding `ammoniteVersion` to select a release compatible to the `scalaVersion`
[source,scala,subs="attributes,verbatim"]
----
import mill.*, scalalib.*

object foo extends ScalaModule {
  def scalaVersion = "2.12.6"
  def ammoniteVersion = "2.4.0"
}
----

[TIP]
--
_Why is Ammonite tied to the exact Scala version?_

This is because Ammonite depends on the Scala compiler.
In contrast to the Scala library, compiler releases do not guarantee any binary compatibility between releases.
As a consequence, Ammonite needs full Scala version specific releases.

The older your used Mill version or the newer the Scala version you want to use, the higher is the risk that the default Ammonite version will not match.
--

=== Disabling incremental compilation with Zinc

By default all ``ScalaModule``s use incremental compilation via https://github.com/sbt/zinc[Zinc] to
only recompile sources that have changed since the last compile, or ones that have been invalidated
by changes to upstream sources.

If for any reason you want to disable incremental compilation for a module, you can override and set
`zincIncrementalCompilation` to `false`

.`build.mill`
[source,scala,subs="attributes,verbatim"]
----
import mill.*, scalalib.*

object foo extends ScalaModule {
  def zincIncrementalCompilation = false
}
----

=== Using a Scala nightly version

include::partial$example/scalalib/module/16-scala-nightlies.adoc[]

== Integrating Declarative and Programmatic Config

=== Custom Module Traits

include::partial$example/scalalib/module/17-custom-trait.adoc[]

=== Programmable `moduleDeps`

include::partial$example/scalalib/module/18-programmable-module-deps.adoc[]