mirror of https://github.com/sbt/sbt.git
168 lines
7.2 KiB
ReStructuredText
168 lines
7.2 KiB
ReStructuredText
=================
|
|
Configuring Scala
|
|
=================
|
|
|
|
sbt needs to obtain Scala for a project and it can do this automatically or you can configure it explicitly.
|
|
The Scala version that is configured for a project will compile, run, document, and provide a REPL for the project code.
|
|
When compiling a project, sbt needs to run the Scala compiler as well as provide the compiler with a classpath, which may include several Scala jars, like the reflection jar.
|
|
|
|
Automatically managed Scala
|
|
===========================
|
|
|
|
The most common case is when you want to use a version of Scala that is available in a repository.
|
|
The only required configuration is the Scala version you want to use.
|
|
For example,
|
|
|
|
::
|
|
|
|
scalaVersion := "2.10.0"
|
|
|
|
This will retrieve Scala from the repositories configured via the :key:`resolvers` setting.
|
|
It will use this version for building your project: compiling, running, scaladoc, and the REPL.
|
|
|
|
Configuring the scala-library dependency
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
By default, the standard Scala library is automatically added as a dependency.
|
|
If you want to configure it differently than the default or you have a project with only Java sources, set:
|
|
|
|
::
|
|
|
|
autoScalaLibrary := false
|
|
|
|
In order to compile Scala sources, the Scala library needs to be on the classpath.
|
|
When :key:`autoScalaLibrary` is true, the Scala library will be on all classpaths: test, runtime, and compile.
|
|
Otherwise, you need to add it like any other dependency.
|
|
For example, the following dependency definition uses Scala only for tests:
|
|
|
|
::
|
|
|
|
autoScalaLibrary := false
|
|
|
|
libraryDependencies += "org.scala-lang" % "scala-library" % scalaVersion.value % "test"
|
|
|
|
Configuring additional Scala dependencies
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
When using a Scala dependency other than the standard library, add it as a normal managed dependency.
|
|
For example, to depend on the Scala compiler,
|
|
|
|
::
|
|
|
|
libraryDependencies += "org.scala-lang" % "scala-compiler" % scalaVersion.value
|
|
|
|
Note that this is necessary regardless of the value of the :key:`autoScalaLibrary` setting described in the previous section.
|
|
|
|
Configuring Scala tool dependencies
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
In order to compile Scala code, run scaladoc, and provide a Scala REPL, sbt needs the `scala-compiler` jar.
|
|
This should not be a normal dependency of the project, so sbt adds a dependency on `scala-compiler` in the special, private `scala-tool` configuration.
|
|
It may be desirable to have more control over this in some situations.
|
|
Disable this automatic behavior with the :key:`managedScalaInstance` key:
|
|
|
|
::
|
|
|
|
managedScalaInstance := false
|
|
|
|
This will also disable the automatic dependency on `scala-library`.
|
|
If you do not need the Scala compiler for anything (compiling, the REPL, scaladoc, etc...), you can stop here.
|
|
sbt does not need an instance of Scala for your project in that case.
|
|
Otherwise, sbt will still need access to the jars for the Scala compiler for compilation and other tasks.
|
|
You can provide them by either declaring a dependency in the `scala-tool` configuration or by explicitly defining :key:`scalaInstance`.
|
|
|
|
In the first case, add the `scala-tool` configuration and add a dependency on `scala-compiler` in this configuration.
|
|
The organization is not important, but sbt needs the module name to be `scala-compiler` and `scala-library` in order to handle those jars appropriately.
|
|
For example,
|
|
|
|
::
|
|
|
|
managedScalaInstance := false
|
|
|
|
// Add the configuration for the dependencies on Scala tool jars
|
|
// You can also use a manually constructed configuration like:
|
|
// config("scala-tool").hide
|
|
ivyConfigurations += Configurations.ScalaTool
|
|
|
|
// Add the usual dependency on the library as well on the compiler in the
|
|
// 'scala-tool' configuration
|
|
libraryDependencies ++= Seq(
|
|
"org.scala-lang" % "scala-library" % scalaVersion.value,
|
|
"org.scala-lang" % "scala-compiler" % scalaVersion.value % "scala-tool"
|
|
)
|
|
|
|
In the second case, directly construct a value of type `ScalaInstance <../../api/sbt/ScalaInstance.html>`_, typically using a method in the `companion object <../../api/sbt/ScalaInstance$.html>`_, and assign it to :key:`scalaInstance`.
|
|
You will also need to add the `scala-library` jar to the classpath to compile and run Scala sources.
|
|
For example,
|
|
|
|
::
|
|
|
|
managedScalaInstance := false
|
|
|
|
scalaInstance := ...
|
|
|
|
unmanagedJars in Compile += scalaInstance.value.libraryJar
|
|
|
|
Switching to a local Scala version
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
To use a locally built Scala version, configure Scala home as described in the following section.
|
|
Scala will still be resolved as before, but the jars will come from the configured Scala home directory.
|
|
|
|
|
|
Using Scala from a local directory
|
|
==================================
|
|
|
|
The result of building Scala from source is a Scala home directory `<base>/build/pack/` that contains a subdirectory `lib/` containing the Scala library, compiler, and other jars.
|
|
The same directory layout is obtained by downloading and extracting a Scala distribution.
|
|
Such a Scala home directory may be used as the source for jars by setting :key:`scalaHome`.
|
|
For example,
|
|
|
|
::
|
|
|
|
scalaHome := Some(file("/home/user/scala-2.10/"))
|
|
|
|
By default, `lib/scala-library.jar` will be added to the unmanaged classpath and `lib/scala-compiler.jar` will be used to compile Scala sources and provide a Scala REPL.
|
|
No managed dependency is recorded on `scala-library`.
|
|
This means that Scala will only be resolved from a repository if you explicitly define a dependency on Scala or if Scala is depended on indirectly via a dependency.
|
|
In these cases, the artifacts for the resolved dependencies will be substituted with jars in the Scala home `lib/` directory.
|
|
|
|
Mixing with managed dependencies
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
As an example, consider adding a dependency on `scala-reflect` when :key:`scalaHome` is configured:
|
|
|
|
::
|
|
|
|
scalaHome := Some(file("/home/user/scala-2.10/"))
|
|
|
|
libraryDependencies += "org.scala-lang" % "scala-reflect" % scalaVersion.value
|
|
|
|
This will be resolved as normal, except that sbt will see if `/home/user/scala-2.10/lib/scala-reflect.jar` exists.
|
|
If it does, that file will be used in place of the artifact from the managed dependency.
|
|
|
|
Using unmanaged dependencies only
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Instead of adding managed dependencies on Scala jars, you can directly add them.
|
|
The :key:`scalaInstance` task provides structured access to the Scala distribution.
|
|
For example, to add all jars in the Scala home `lib/` directory,
|
|
|
|
::
|
|
|
|
scalaHome := Some(file("/home/user/scala-2.10/"))
|
|
|
|
unmanagedJars in Compile ++= scalaInstance.value.jars
|
|
|
|
To add only some jars, filter the jars from :key:`scalaInstance` before adding them.
|
|
|
|
sbt's Scala version
|
|
===================
|
|
|
|
sbt needs Scala jars to run itself since it is written in Scala.
|
|
sbt uses that same version of Scala to compile the build definitions that you write for your project because they use sbt APIs.
|
|
This version of Scala is fixed for a specific sbt release and cannot be changed.
|
|
For sbt |version|, this version is Scala |scalaVersion|.
|
|
Because this Scala version is needed before sbt runs, the repositories used to retrieve this version are configured in the sbt :doc:`launcher </Detailed-Topics/Launcher>`.
|
|
|