<!--
  ~ Copyright 2009 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.
  -->
<chapter id="scala_plugin" xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>The Scala Plugin</title>

    <para>The Scala plugin extends the Java plugin to add support for Scala projects. It can deal with Scala-only
        projects and with mixed Java/Scala projects. It can even deal with Java-only projects.
        The Scala plugin supports joint compilation of Java and Scala source. This means your project can contain
        Scala classes which use Java classes, and vice versa.
    </para>

    <section>
        <title>Usage</title>
        <para>To use the Scala plugin, include in your build script:</para>
        <sample id="useScalaPlugin" dir="scala/quickstart" title="Using the Scala plugin">
            <sourcefile file="build.gradle" snippet="use-plugin"/>
        </sample>
    </section>

    <section>
        <title>Tasks</title>
        <para>The Scala plugin adds the following tasks to the project.</para>
        <table>
            <title>Scala plugin - tasks</title>
            <thead>
                <tr>
                    <td>Task name</td>
                    <td>Depends on</td>
                    <td>Type</td>
                    <td>Description</td>
                </tr>
            </thead>
            <tr>
                <td><literal>compileScala</literal></td>
                <td><literal>compileJava</literal></td>
                <td><apilink class="org.gradle.api.tasks.scala.ScalaCompile"/></td>
                <td>Compiles production Scala source files using scalac.</td>
            </tr>
            <tr>
                <td><literal>compileTestScala</literal></td>
                <td><literal>compileTestJava</literal></td>
                <td><apilink class="org.gradle.api.tasks.scala.ScalaCompile"/></td>
                <td>Compiles test Scala source files using scalac.</td>
            </tr>
            <tr>
                <td><literal>compile<replaceable>SourceSet</replaceable>Scala</literal></td>
                <td><literal>compile<replaceable>SourceSet</replaceable>Java</literal></td>
                <td><apilink class="org.gradle.api.tasks.scala.ScalaCompile"/></td>
                <td>Compiles the given source set's Scala source files using scalac.</td>
            </tr>
            <tr>
                <td><literal>scaladoc</literal></td>
                <td>-</td>
                <td><apilink class="org.gradle.api.tasks.scala.ScalaDoc"/></td>
                <td>Generates API documentation for the production Scala source files using scaladoc.</td>
            </tr>
        </table>
        <para>The Scala plugin adds the following dependencies to tasks added by the Java plugin.</para>
        <table>
            <title>Scala plugin - additional task dependencies</title>
            <thead>
                <td>Task name</td>
                <td>Depends on</td>
            </thead>
            <tr>
                <td>
                    <literal>classes</literal>
                </td>
                <td>
                    <literal>compileScala</literal>
                </td>
            </tr>
            <tr>
                <td>
                    <literal>testClasses</literal>
                </td>
                <td>
                    <literal>compileTestScala</literal>
                </td>
            </tr>
            <tr>
                <td>
                    <literal><replaceable>sourceSet</replaceable>Classes</literal>
                </td>
                <td>
                    <literal>compile<replaceable>SourceSet</replaceable>Scala</literal>
                </td>
            </tr>
        </table>
        <figure>
            <title>Scala plugin - tasks</title>
            <imageobject>
                <imagedata fileref="img/scalaPluginTasks.png"/>
            </imageobject>
        </figure>
    </section>

    <section>
        <title>Project layout</title>
        <para>The Scala plugin assumes the project layout shown below.  All the Scala source directories can contain
            Scala <emphasis>and</emphasis> Java code. The Java source directories may only contain Java source code.
            None of these directories need exist or have anything in them. The Scala plugin will compile whatever it
            finds, and handles anything which is missing.</para>
        <table id='scalalayout'>
            <title>Scala plugin - project layout</title>
            <thead>
                <tr>
                    <td>Directory</td>
                    <td>Meaning</td>
                </tr>
            </thead>
            <xi:include href="javaProjectMainLayout.xml"/>
            <tr>
                <td>
                    <filename>src/main/scala</filename>
                </td>
                <td>Production Scala source. May also contain Java source for joint compilation.</td>
            </tr>
            <xi:include href="javaProjectTestLayout.xml"/>
            <tr>
                <td>
                    <filename>src/test/scala</filename>
                </td>
                <td>Test Scala source. May also contain Java source for joint compilation.</td>
            </tr>
            <xi:include href="javaProjectGenericLayout.xml"/>
            <tr>
                <td>
                    <filename>src/<replaceable>sourceSet</replaceable>/scala</filename>
                </td>
                <td>Scala source for the given source set. May also contain Java source for joint compilation.</td>
            </tr>
        </table>

        <section>
            <title>Changing the project layout</title>
            <para>TBD</para>
            <sample id="customScalaSourceLayout" dir="scala/customizedLayout" title="Custom Scala source layout">
                <sourcefile file="build.gradle" snippet="define-main"/>
            </sample>
        </section>

    </section>

    <section>
        <title>Dependency Management</title>
        <para>The Scala plugin adds a <literal>scalaTools</literal> configuration, which it uses to locate the Scala
            tools, such as scalac, to use. You must specify the version of Scala to use. Below is an example.
        </para>
        <sample id="declareScalaTools" dir="scala/quickstart" title="Declaring the Scala version to use">
            <sourcefile file="build.gradle" snippet="declare-scala-version"/>
        </sample>
    </section>

    <section>
        <title>Convention Properties</title>
        <para>The Scala plugin does not add any convention properties to the project.</para>
    </section>
    
    <section>
        <title>Source set properties</title>
        <para>The Scala plugin adds the following convention properties to each source set in the project. You can
            use these properties in your build script as though they were properties of the source set object (see
            <xref linkend="sub:more_about_convention_objects"/>).</para>
        <table>
            <title>Scala plugin - source set properties</title>
            <thead>
                <tr>
                    <td>Property name</td>
                    <td>Type</td>
                    <td>Default value</td>
                    <td>Description</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <literal>scala</literal>
                </td>
                <td>
                    <apilink class="org.gradle.api.file.SourceDirectorySet"/> (read-only)
                </td>
                <td>
                    Not null
                </td>
                <td>
                    The Scala source files of this source set. Contains all <filename>.scala</filename> and
                    <filename>.java</filename> files found in the Scala source directories, and excludes all other
                    types of files.
                </td>
            </tr>
            <tr>
                <td>
                    <literal>scala.srcDirs</literal>
                </td>
                <td>
                    <classname>Set&lt;File></classname>. Can set using anything described in <xref linkend="sec:specifying_multiple_files"/>.
                </td>
                <td>
                    <literal>[<replaceable>projectDir</replaceable>/src/<replaceable>name</replaceable>/scala]</literal>
                </td>
                <td>
                    The source directories containing the Scala source files of this source set. May also contain
                    Java source files for joint compilation.
                </td>
            </tr>
            <tr>
                <td>
                    <literal>allScala</literal>
                </td>
                <td>
                    <apilink class="org.gradle.api.file.FileTree"/> (read-only)
                </td>
                <td>
                    Not null
                </td>
                <td>
                    All Scala source files of this source set. Contains only the <filename>.scala</filename> files
                    found in the Scala source directories.
                </td>
            </tr>
        </table>

        <para>These convention properties are provided by a convention object of type <apilink class="org.gradle.api.tasks.ScalaSourceSet"/>.</para>
        <para>The Scala plugin also modifies some source set properties:</para>
        <table>
            <title>Scala plugin - source set properties</title>
            <thead>
                <tr>
                    <td>Property name</td>
                    <td>Change</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <literal>allJava</literal>
                </td>
                <td>Adds all <filename>.java</filename> files found in the Scala source directories.</td>
            </tr>
            <tr>
                <td>
                    <literal>allSource</literal>
                </td>
                <td>Adds all source files found in the Scala source directories.</td>
            </tr>
        </table>
    </section>

    <section>
        <title>Fast Scala Compiler</title>
        <para>The Scala plugin includes support for <ulink url="http://www.scala-lang.org/docu/files/tools/fsc.html">fsc</ulink>,
            the Fast Scala Compiler. <literal>fsc</literal> runs in a separate daemon process and can speed up
            compilation significantly.
            <sample id="fsc" dir="scala/fsc" title="Enabling the Fast Scala Compiler">
                <sourcefile file="build.gradle" snippet="use-fsc"/>
            </sample>
            Note that <literal>fsc</literal> expects to be restarted whenever the <emphasis>contents</emphasis> of its
            compile class path change. (It does detect changes to the compile class path itself.) This makes it
            less suitable for multi-project builds.
        </para>
    </section>

</chapter>