<commit_before>// Copyright 2017 the original author or authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[scala_plugin]]
= The Scala Plugin

The Scala plugin extends the <<java_plugin.adoc#,Java plugin>> to add support for https://www.scala-lang.org/[Scala] projects.
It can deal with Scala code, mixed Scala and Java code, and even pure Java code (although we don't necessarily recommend to use it for the latter).
The plugin supports _joint compilation_, which allows you to freely mix and match Scala and Java code, with dependencies in both directions.
For example, a Scala class can extend a Java class that in turn extends a Scala class.
This makes it possible to use the best language for the job, and to rewrite any class in the other language if needed.

Note that if you want to benefit from the <<java_library_plugin.adoc#sec:java_library_separation,API / implementation separation>>, you can also apply the `java-library` plugin to your Scala project.


[[sec:scala_usage]]
== Usage

To use the Scala plugin, include the following in your build script:

.Using the Scala plugin
====
include::sample[dir="scala/quickstart/groovy",files="build.gradle[tags=use-plugin]"]
include::sample[dir="scala/quickstart/kotlin",files="build.gradle.kts[tags=use-plugin]"]
====

[[sec:scala_tasks]]
== Tasks

The Scala plugin adds the following tasks to the project.

`compileScala` — link:{groovyDslPath}/org.gradle.api.tasks.scala.ScalaCompile.html[ScalaCompile]::
_Depends on_: `compileJava`
+
Compiles production Scala source files.

`compileTestScala` — link:{groovyDslPath}/org.gradle.api.tasks.scala.ScalaCompile.html[ScalaCompile]::
_Depends on_: `compileTestJava`
+
Compiles test Scala source files.

`compile__SourceSet__Scala` — link:{groovyDslPath}/org.gradle.api.tasks.scala.ScalaCompile.html[ScalaCompile]::
_Depends on_: `compile__SourceSet__Java`
+
Compiles the given source set's Scala source files.

`scaladoc` — link:{groovyDslPath}/org.gradle.api.tasks.scala.ScalaDoc.html[ScalaDoc]::
+
Generates API documentation for the production Scala source files.

The Scala plugin adds the following dependencies to tasks added by the Java plugin.

.Scala plugin - additional task dependencies
[cols="a,a", options="header"]
|===
| Task name
| Depends on
|  `classes`
|  `compileScala`

|  `testClasses`
|  `compileTestScala`

|  `__sourceSet__Classes`
|  `compile__SourceSet__Scala`
|===

.Scala plugin - tasks
image::scalaPluginTasks.png[]


[[sec:scala_project_layout]]
== Project layout

The Scala plugin assumes the project layout shown below. All the Scala source directories can contain Scala _and_ Java code. The Java source directories may only contain Java source code. None of these directories need to exist or have anything in them; the Scala plugin will simply compile whatever it finds.

[[scalalayout]]
include::javaProjectMainLayout.adoc[]

`src/main/scala`::
Production Scala source. May also contain Java source files for joint compilation.

include::javaProjectTestLayout.adoc[]

`src/test/scala`::
Test Scala source. May also contain Java source files for joint compilation.

include::javaProjectGenericLayout.adoc[]

`src/__sourceSet__/scala`::
Scala source files for the given source set. May also contain Java source files for joint compilation.


[[sec:changing_scala_project_layout]]
=== Changing the project layout

Just like the Java plugin, the Scala plugin allows you to configure custom locations for Scala production and test source files.

.Custom Scala source layout
====
include::sample[dir="scala/customizedLayout/groovy",files="build.gradle[tags=custom-source-locations]"]
include::sample[dir="scala/customizedLayout/kotlin",files="build.gradle.kts[tags=custom-source-locations]"]
====

[[sec:scala_dependency_management]]
== Dependency management

Scala projects need to declare a `scala-library` dependency. This dependency will then be used on compile and runtime class paths. It will also be used to get hold of the Scala compiler and Scaladoc tool, respectively.footnote:[See <<#sec:configure_scala_classpath,Automatic configuration of Scala classpath>>.]

If Scala is used for production code, the `scala-library` dependency should be added to the `compile` configuration:

.Declaring a Scala dependency for production code
====
include::sample[dir="scala/quickstart/groovy",files="build.gradle[tags=scala-dependency]"]
include::sample[dir="scala/quickstart/kotlin",files="build.gradle.kts[tags=scala-dependency]"]
====

If Scala is only used for test code, the `scala-library` dependency should be added to the `testCompile` configuration:

.Declaring a Scala dependency for test code
====
include::sample[dir="userguide/scala/scalaDependency/groovy",files="build.gradle[tags=scala-test-dependency]"]
include::sample[dir="userguide/scala/scalaDependency/kotlin",files="build.gradle.kts[tags=scala-test-dependency]"]
====

[[sec:configure_scala_classpath]]
== Automatic configuration of scalaClasspath

The `ScalaCompile` and `ScalaDoc` tasks consume Scala code in two ways: on their `classpath`, and on their `scalaClasspath`. The former is used to locate classes referenced by the source code, and will typically contain `scala-library` along with other libraries. The latter is used to load and execute the Scala compiler and Scaladoc tool, respectively, and should only contain the `scala-compiler` library and its dependencies.

Unless a task's `scalaClasspath` is configured explicitly, the Scala (base) plugin will try to infer it from the task's `classpath`. This is done as follows:

* If a `scala-library` jar is found on `classpath`, and the project has at least one repository declared, a corresponding `scala-compiler` repository dependency will be added to `scalaClasspath`.
* Otherwise, execution of the task will fail with a message saying that `scalaClasspath` could not be inferred.


[[sec:configure_zinc_compiler]]
== Configuring the Zinc compiler

The Scala plugin uses a configuration named `zinc` to resolve the https://github.com/typesafehub/zinc[Zinc compiler] and its dependencies.
Gradle will provide a default version of Zinc, but if you need to use a particular Zinc version, you can change it.
Gradle supports version 1.2.0 of Zinc and above.
footnote:[However Zinc 1.2.0 for Scala 2.11 is not supported.]

.Declaring a version of the Zinc compiler to use
====
include::sample[dir="userguide/scala/zincDependency/groovy",files="build.gradle[tags=zinc-dependency]"]
include::sample[dir="userguide/scala/zincDependency/kotlin",files="build.gradle.kts[tags=zinc-dependency]"]
====

The Zinc compiler itself needs a compatible version of `scala-library` that may be different from the version required by your application.
Gradle takes care of specifying a compatible version of `scala-library` for you.

You can diagnose problems with the version of the Zinc compiler selected by running <<viewing_debugging_dependencies.adoc#,dependencyInsight>> for the `zinc` configuration.

.Zinc compatibility table
[%header%autowidth,compact]
|===
| Gradle version    | Supported Zinc version                                                    | Supported scala version

| < 6.0             | `com.typesage.zinc:zinc:0.3.0`, with the exception of `[0.3.2, 0.3.5.2]`  | `2.10.x`
| 6+                | `org.scala-sbt:zinc_2.12:1.2+`                                            | `2.12.x`<commit_msg>Expand compatibility table in Scala plugin chapter<commit_after>// Copyright 2017 the original author or authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[scala_plugin]]
= The Scala Plugin

The Scala plugin extends the <<java_plugin.adoc#,Java plugin>> to add support for https://www.scala-lang.org/[Scala] projects.
It can deal with Scala code, mixed Scala and Java code, and even pure Java code (although we don't necessarily recommend to use it for the latter).
The plugin supports _joint compilation_, which allows you to freely mix and match Scala and Java code, with dependencies in both directions.
For example, a Scala class can extend a Java class that in turn extends a Scala class.
This makes it possible to use the best language for the job, and to rewrite any class in the other language if needed.

Note that if you want to benefit from the <<java_library_plugin.adoc#sec:java_library_separation,API / implementation separation>>, you can also apply the `java-library` plugin to your Scala project.


[[sec:scala_usage]]
== Usage

To use the Scala plugin, include the following in your build script:

.Using the Scala plugin
====
include::sample[dir="scala/quickstart/groovy",files="build.gradle[tags=use-plugin]"]
include::sample[dir="scala/quickstart/kotlin",files="build.gradle.kts[tags=use-plugin]"]
====

[[sec:scala_tasks]]
== Tasks

The Scala plugin adds the following tasks to the project.

`compileScala` — link:{groovyDslPath}/org.gradle.api.tasks.scala.ScalaCompile.html[ScalaCompile]::
_Depends on_: `compileJava`
+
Compiles production Scala source files.

`compileTestScala` — link:{groovyDslPath}/org.gradle.api.tasks.scala.ScalaCompile.html[ScalaCompile]::
_Depends on_: `compileTestJava`
+
Compiles test Scala source files.

`compile__SourceSet__Scala` — link:{groovyDslPath}/org.gradle.api.tasks.scala.ScalaCompile.html[ScalaCompile]::
_Depends on_: `compile__SourceSet__Java`
+
Compiles the given source set's Scala source files.

`scaladoc` — link:{groovyDslPath}/org.gradle.api.tasks.scala.ScalaDoc.html[ScalaDoc]::
+
Generates API documentation for the production Scala source files.

The Scala plugin adds the following dependencies to tasks added by the Java plugin.

.Scala plugin - additional task dependencies
[cols="a,a", options="header"]
|===
| Task name
| Depends on
|  `classes`
|  `compileScala`

|  `testClasses`
|  `compileTestScala`

|  `__sourceSet__Classes`
|  `compile__SourceSet__Scala`
|===

.Scala plugin - tasks
image::scalaPluginTasks.png[]


[[sec:scala_project_layout]]
== Project layout

The Scala plugin assumes the project layout shown below. All the Scala source directories can contain Scala _and_ Java code. The Java source directories may only contain Java source code. None of these directories need to exist or have anything in them; the Scala plugin will simply compile whatever it finds.

[[scalalayout]]
include::javaProjectMainLayout.adoc[]

`src/main/scala`::
Production Scala source. May also contain Java source files for joint compilation.

include::javaProjectTestLayout.adoc[]

`src/test/scala`::
Test Scala source. May also contain Java source files for joint compilation.

include::javaProjectGenericLayout.adoc[]

`src/__sourceSet__/scala`::
Scala source files for the given source set. May also contain Java source files for joint compilation.


[[sec:changing_scala_project_layout]]
=== Changing the project layout

Just like the Java plugin, the Scala plugin allows you to configure custom locations for Scala production and test source files.

.Custom Scala source layout
====
include::sample[dir="scala/customizedLayout/groovy",files="build.gradle[tags=custom-source-locations]"]
include::sample[dir="scala/customizedLayout/kotlin",files="build.gradle.kts[tags=custom-source-locations]"]
====

[[sec:scala_dependency_management]]
== Dependency management

Scala projects need to declare a `scala-library` dependency. This dependency will then be used on compile and runtime class paths. It will also be used to get hold of the Scala compiler and Scaladoc tool, respectively.footnote:[See <<#sec:configure_scala_classpath,Automatic configuration of Scala classpath>>.]

If Scala is used for production code, the `scala-library` dependency should be added to the `compile` configuration:

.Declaring a Scala dependency for production code
====
include::sample[dir="scala/quickstart/groovy",files="build.gradle[tags=scala-dependency]"]
include::sample[dir="scala/quickstart/kotlin",files="build.gradle.kts[tags=scala-dependency]"]
====

If Scala is only used for test code, the `scala-library` dependency should be added to the `testCompile` configuration:

.Declaring a Scala dependency for test code
====
include::sample[dir="userguide/scala/scalaDependency/groovy",files="build.gradle[tags=scala-test-dependency]"]
include::sample[dir="userguide/scala/scalaDependency/kotlin",files="build.gradle.kts[tags=scala-test-dependency]"]
====

[[sec:configure_scala_classpath]]
== Automatic configuration of scalaClasspath

The `ScalaCompile` and `ScalaDoc` tasks consume Scala code in two ways: on their `classpath`, and on their `scalaClasspath`. The former is used to locate classes referenced by the source code, and will typically contain `scala-library` along with other libraries. The latter is used to load and execute the Scala compiler and Scaladoc tool, respectively, and should only contain the `scala-compiler` library and its dependencies.

Unless a task's `scalaClasspath` is configured explicitly, the Scala (base) plugin will try to infer it from the task's `classpath`. This is done as follows:

* If a `scala-library` jar is found on `classpath`, and the project has at least one repository declared, a corresponding `scala-compiler` repository dependency will be added to `scalaClasspath`.
* Otherwise, execution of the task will fail with a message saying that `scalaClasspath` could not be inferred.


[[sec:configure_zinc_compiler]]
== Configuring the Zinc compiler

The Scala plugin uses a configuration named `zinc` to resolve the https://github.com/typesafehub/zinc[Zinc compiler] and its dependencies.
Gradle will provide a default version of Zinc, but if you need to use a particular Zinc version, you can change it.
Gradle supports version 1.2.0 of Zinc and above.

.Declaring a version of the Zinc compiler to use
====
include::sample[dir="userguide/scala/zincDependency/groovy",files="build.gradle[tags=zinc-dependency]"]
include::sample[dir="userguide/scala/zincDependency/kotlin",files="build.gradle.kts[tags=zinc-dependency]"]
====

The Zinc compiler itself needs a compatible version of `scala-library` that may be different from the version required by your application.
Gradle takes care of specifying a compatible version of `scala-library` for you.
footnote:[Gradle does not support running the Zinc compiler v1.2.0 with Scala 2.11.]

You can diagnose problems with the version of the Zinc compiler selected by running <<viewing_debugging_dependencies.adoc#,dependencyInsight>> for the `zinc` configuration.

.Zinc compatibility table
[%header%autowidth,compact]
|===
| Gradle version    | Supported Zinc versions | Zinc coordinates | Required Scala version | Supported Scala compilation version

| 6.0 and newer     | link:https://github.com/sbt/zinc[SBT Zinc]. Versions 1.2.0 and above. | `org.scala-sbt:zinc_2.12` | Scala `2.12.x` is required for _running_ Zinc. | Scala `2.10.x` through `2.12.x` can be compiled.
| 1.x trough 5.x    | link:https://github.com/typesafehub/zinc[**Deprecated** Typesafe Zinc compiler.] Versions 0.3.0 and above, except for 0.3.2 through 0.3.5.2. | `com.typesafe.zinc:zinc` | Scala `2.10.x` is required for _running_ Zinc. | Scala `2.9.x` through `2.12.x` can be compiled.

{'fraction_non_alphanumeric': 0.09729025857258014, 'fraction_numerical': 0.005890742233521424, 'mean_word_length': 5.167495219885277, 'pattern_counts': {'":': 0, '<': 20, '<?xml version=': 0, '>': 19, 'https://': 6, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6099681', 'n_tokens_mistral': 4761, 'n_tokens_neox': 4456, 'n_words': 1749}