Scala Ant Tasks

The Scala distribution contains several tasks for building software projects using Apache Ant [1], a Java-based build tool. The tasks described below require Apache Ant version 1.6 or newer.

The Scala tasks are: scalac [2], fsc [3] and scaladoc [4]

Compiles a Scala source tree.

The source and destination directory will be recursively scanned for Scala source files to compile. Only Scala files that have no corresponding .class file or where the class file is older than the .scala file will be compiled.

Note: Ant uses only the names of the source and class files to find the classes that need a rebuild. It will not scan the source and therefore will have no knowledge about nested classes, classes that are named different from the source file, and so on.

It is possible to refine the set of files that are being compiled. This can be done with the includes, includesfile, excludes, and excludesfile attributes. With the includesor includesfile attribute, you specify the files you want to have included. The exclude or excludesfile attribute is used to specify the files you want to have excluded. In both cases, the list of files can be specified by either the filename, relative to the directory(s) specified in the srcdir attribute or nested <src> element(s), or by using wildcard patterns. See the Ant documentation on directory-based tasks, for information on how the inclusion/exclusion of files works, and how to write wildcard patterns.

Attribute	Description	Required
srcdir	Location of the Scala files.	Yes, unless nested <src>elements or srcref are present.
srcref	Location of the Scala files, given as a reference to a path defined elsewhere.	Yes, unless nested <src>elements or srcdir are present.
destdir	Location to store the class files.	No
classpath	The classpath to use.	No
classpathref	The classpath to use, given as a reference to a path defined elsewhere.	No
sourcepath	The sourcepath to use; defaults to the value of the srcdir attribute (or nested <src> elements). To suppress the sourcepath switch, use sourcepath="".	No
sourcepathref	The sourcepath to use, given as a reference to a path defined elsewhere.	No
bootclasspath	Location of bootstrap class files.	No
bootclasspathref	Location of bootstrap class files, given as a reference to a path defined elsewhere.	No
extdirs	Location of installed extensions.	No
extdirsref	Location of installed extensions, given as a reference to a path defined elsewhere.	No
target	Specifies which backend to use; defaults to jvm-1.4 (accepted values are: jvm-1.5, jvm-1.4, msil).	No
deprecation	Indicates whether source should be compiled with deprecation information; defaults to no (accepted values are: on, off,yes and no). Available since Scala version 2.3.	No
unchecked	Indicates whether source should be compiled with unchecked information; defaults to no (accepted values are: on, off, yesand no). Available since Scala version 2.3.	No
encoding	Encoding of source files.	No
logging	Asks the compiler for verbose output; defaults to none (accepted values are: none, verbose, and debug).	No
usepredefs	Asks the compiler to use predefined values for compilation; defaults to yes.	No
force	Whether to force the compilation of all files; possible values are false (only compile modified files), and true (always recompile all files); defaults to false.	No
addparams	Specifies additional command line arguments to be passed to the Scala tool. The user may for example specify advanced options (eg. -Xresident) as well as private options (eg. -Ydebug) not available as Ant attributes.	No
failonerror	Indicates whether compilation errors will fail the build; defaults to true. Available since Scala version 2.6.	No
scalacdebugging	If set to true, the scalac Ant taks will print the filenames being compiled, instead of only the number of files.	No
assemname	The assembly name. Only relevant if the target is "msil".	No
assemrefs	References to external assemblies. Only relevat if the target is "msil"	No

This task forms an implicit FileSet and supports all attributes of <fileset> (dir becomes srcdir) as well as the nested <include>, <exclude> and <patternset> elements.

src, classpath, sourcepath, bootclasspath and extdirs

Scalac's srcdir, classpath, sourcepath, bootclasspath, and extdirs attributes are path-like structures and can also be set via nested <src>, <classpath>, <sourcepath>,<bootclasspath> and <extdirs> elements, respectively.

• Ant 1.6 or higher
• Scala 2.2 or higher

  <property
    name="sources.dir"
    value="${base.dir}/sources"
     />
  <property
    name="build.dir"
    value="${base.dir}/build"
     />
  <target name="init">
    <property
      name="scala-library.jar"
      value="${scala.home}/lib/scala-library.jar"
       />
    <path id="build.classpath">
      <pathelement location="${scala-library.jar}"   />
      <!--<pathelement location="${your.path}"   />-->
      <pathelement location="${build.dir}"   />
    </path>
    <taskdef resource="scala/tools/ant/antlib.xml">
      <classpath>
        <pathelement location="${scala.home}/lib/scala-compiler.jar"   />
        <pathelement location="${scala-library.jar}"   />
      </classpath>
    </taskdef>
  </target>

In the above target "init" the task taskdef defines the Scala ant tasks fsc, sbaz, scalac and scalascript.

  <target name="build" depends="init">
    <mkdir dir="${build.dir}"   />
    <scalac srcdir="${sources.dir}"
            destdir="${build.dir}"
            classpathref="build.classpath">
      <include name="compile/**/*.scala"   />
      <exclude name="forget/**/*.scala"   />
    </scalac>
  </target>

Compiles all Scala files in sources/compile/ (not in sources/forget) to build/ with given classpath. Files in sources/forget/ will not necessarily be compiled, but might be as they are in the sourcepath. All modified files are re-compiled.

Compiles a Scala source tree.

The fsc Ant task supports the same set of parameters as the scalac Ant task with the following additional parameters:

Attribute	Description	Required
reset	Reset compile server caches.	No
shutdown	Shutdown compile server.	No
server	Specify compile server host and port number. Usually this option is not needed. Note that the hostname must be for a host that shares the same filesystem.	No

• Ant 1.6 or higher
• Scala 2.2 or higher

Generates the API documentation in HTML format for the given source files.

The scaladoc Ant task supports the same set of parameters as the scalac Ant task with the following additional parameters:

Attribute	Description	Required
windowtitle	Specify the text to appear in the window title. Default value: "Scala 2".	No
doctitle	Specify the text to appear in the main frame title. Default value: "Scala 2<br />API Specification"	No, HTML code is supported.
stylesheetfile	File to change style of the generated documentation. NB. The file name is system-dependent. Available since Scala version 2.5.	No
header	Include header text for each page. Available since Scala version 2.5.	No, HTML code is supported.
footer	Include footer text for each page. Available since Scala version 2.5.	No, HTML code is supported.
top	Include top text for each page. Available since Scala version 2.5.	No, HTML code is supported.
bottom	Include bottom text for each page. Available since Scala version 2.5.	No, HTML code is supported.

• Ant 1.6 or higher
• Scala 2.2 or higher

  <target name="docs" depends="init">
    <mkdir dir="${docs.dir}"   />
    <scaladoc
      srcdir="${sources.dir}"
      destdir="${docs.dir}"
      deprecation="yes" unchecked="yes"
      windowtitle="liftweb Library Documentation"
      doctitle="&lt;div&gt;liftweb 0.1.0&lt;/div&gt;"
      classpathref="build.classpath">
        <include name="compile/**/*.scala"   />
    </scaladoc>
  </target>

Executes a Java class within the running (Ant) VM or forks another VM if specified.

The task java [5] belongs the core tasks of the Ant [1] distribution.

Note: The Scala library scala-library.jar must be present in the Java class path. The actors and dbc libraries are available as separate JAR files: scala-actors.jarand scala-dbc.jar.

  <target name="run" depends="build">
    <java classname="examples.sort"
          classpathref="build.classpath">
    </java>
  </target>