Scala With Ant

2009-10-18

Although Scala is tool-agnostic, the Scala community seems to have a preference for the Apache Maven build tool. I am not quite sure why. Given that most people who learn Scala come from a Java background, what could be more natural than using Ant for Scala development? As a tried-and-true build solution, Ant avoids the headaches and additional learning curve that comes with an unfamiliar build tool. Although I have spent considerable time with Maven as part of my job, Maven and I haven’t become friends, and we probably never will. I won’t go into the details of the how and why. Instead I’m going to present and explain a few Ant scripts for Scala development. If you are new to Scala, I hope that this will give you a headstart with your new Scala projects. After all, you have a new language to learn and little time to bother with tools.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
<project default="run" name="helloworld">

<!-- root directory of this project -->
<property name="project.dir" value=".">

<!-- main class to run -->
<property name="main.class" value="app.HelloWorld">

<!-- root directory of Scala installation -->
<property name="scala.home"
  value="C:\\Program Files\\Scala">

<!-- location of scalatest.jar for unit testing -->
<property name="scalatest.jar"
  value="C:\\Program Files\\...\\scalatest-1.0.jar">

<target name="init">

  <!-- derived path names -->
  <property name="build.dir" value="${project.dir}/build">
  <property name="source.dir" value="${project.dir}/src">
  <property name="test.dir" value="${project.dir}/test">

  <!-- scala libraries for classpath definitions -->
  <property name="scala-library.jar"
    value="${scala.home}/lib/scala-library.jar">
  <property name="scala-compiler.jar"
    value="${scala.home}/lib/scala-compiler.jar">

  <!-- classpath for the compiler task definition -->
  <path id="scala.classpath">
    <pathelement location="${scala-compiler.jar}">
    <pathelement location="${scala-library.jar}">
  </pathelement>

  <!-- classpath for project build -->
  <path id="build.classpath">
    <pathelement location="${scala-library.jar}">
    <fileset dir="${project.dir}/lib">
      <include name="*.jar">
    </include>
    <pathelement location="${build.dir}/classes">
  </pathelement>

  <!-- classpath for unit test build  -->
  <path id="test.classpath">
    <pathelement location="${scala-library.jar}">
    <pathelement location="${scalatest.jar}">
    <pathelement location="${build.dir}/classes">
  </pathelement>

  <!-- definition for the "scalac" and
    "scaladoc" ant tasks -->
  <taskdef resource="scala/tools/ant/antlib.xml">
    <classpath refid="scala.classpath">
  </classpath>

  <!-- definition for the "scalatest" ant task -->
  <taskdef classname="org.scalatest.tools.ScalaTestTask"
    name="scalatest">
    <classpath refid="test.classpath">
  </classpath>

</taskdef>

<!-- delete compiled files -->
<target depends="init" description="clean" name="clean">
  <delete dir="${build.dir}">
  <delete dir="${project.dir}/doc">
  <delete file="${project.dir}/lib/scala-library.jar">
</delete>

<!-- compile project -->
<target depends="init" description="build" name="build">
  <buildnumber>
  <tstamp>
  <mkdir dir="${build.dir}/classes">
  <scalac classpathref="build.classpath" deprecation="on"
    destdir="${build.dir}/classes"
    force="never" srcdir="${source.dir}">
    <include name="**/*.scala">
  </include>
</scalac>

<!-- run program -->
<target depends="build" description="run" name="run">
  <java classname="${main.class}" classpathref="build.classpath">
</java>

<!-- build unit tests -->
<target depends="build" name="buildtest">
  <mkdir dir="${build.dir}/test">
  <scalac classpathref="test.classpath" deprecation="on"
    destdir="${build.dir}/test" force="never" srcdir="${test.dir}">
    <include name="**/*.scala">
  </include>
</scalac>

<!-- run unit tests -->
<target depends="buildtest" description="test" name="test">
  <scalatest runpath="${build.dir}/test">
    <reporter config="YFABRT" type="stdout">
    <membersonly package="suite">
    <!-- <reporter type="graphic" config="YFABRT"/> -->
    <!-- <suite classname="suite.TestSuite"/> -->
  </membersonly>
</reporter>

<!-- create a startable *.jar with proper
  classpath dependency definition -->
<target depends="build" description="jar" name="jar">
  <mkdir dir="${build.dir}/jar">
  <copy file="${scala-library.jar}" todir="${project.dir}/lib">
  <path id="jar.class.path">
    <fileset dir="${project.dir}">
      <include name="lib/**/*.jar">
    </include>
  </fileset>
  <pathconvert dirsep="/" pathsep=" " property="jar.classpath">
    <path refid="jar.class.path"></path>
    <map from="${basedir}${file.separator}lib" to="lib">
  </map></pathconvert>
  <jar basedir="${build.dir}/classes"
    destfile="${build.dir}/jar/${ant.project.name}.jar"
    duplicate="preserve">
    <manifest>
      <attribute name="Main-Class" value="${main.class}">
      <attribute name="Class-Path" value="${jar.classpath}">
      <section name="Program">
        <attribute name="Title" value="${ant.project.name}">
        <attribute name="Build" value="${build.number}">
        <attribute name="Date" value="${TODAY}">
      </attribute>
    </attribute>
  </attribute>
</section>

<!-- create API documentation in doc folder -->
<target depends="build" description="scaladoc"
  name="scaladoc">
  <mkdir dir="${project.dir}/doc">
  <scaladoc classpathref="build.classpath"
    destdir="${project.dir}/doc"
    doctitle="${ant.project.name}" srcdir="${source.dir}"
    windowtitle="${ant.project.name}">
</scaladoc>

<!-- create a zip file with binaries for distribution -->
<target depends="jar, scaladoc"
  description="package" name="package">
  <zip destfile="${build.dir}/${ant.project.name}.zip">
    <zipfileset dir="${build.dir}/jar"
      includes="${ant.project.name}.jar">
    <zipfileset dir="${project.dir}" includes="lib/*"/>
    <zipfileset dir="${project.dir}" includes="doc/*"/>
    <zipfileset dir="${project.dir}/txt" includes="*"/>
  </zip>
</target>

</project>

Download "helloworld.scala" with Ant build file. Fortunately, the designers of Scala provided built-in Ant tasks in the compiler library, which makes the integration of Ant straightforward. The XML code above shows the build.xml for a typical Scala standalone application, such as a GUI program or a console application. It is reasonably complete and it provides Ant targets for all common tasks:

  • build = compile your project and put class files into the ./build directory.
  • run = run program.
  • jar = create a startable jar archive from class files.
  • test = build and run unit tests (using Scalatest).
  • scaladoc = create API documentation from sources and put it into the in ./doc directory.
  • package = create a distributable zip archive that contains all dependencies plus Scaladocs.

The directory tree is kept as simple as possible:

skeleton-standalone
|
|--- build
|--- lib
|--- src
|    |--- app
|
|--- test
|    |--- suite
|
|--- txt
  • build - temporary directory for class files and other binaries
  • lib - contains external dependencies (*.jar files)
  • src - contains Scala source code tree
  • test - contains Scala unit tests
  • txt - contains files (such as license text) that are packaged with the distributable zip archive

If your project depends on external jars, all you have to do is to drop these into the ./lib folder. Ant will take care of creating appropriate class paths, entering them into the manifest of the startable jar file, and including them in the distribution package. The Scala library is packed automatically so that the resulting package can be deployed on computers that don’t have Scala installed (only a standard JRE is required). To use this Ant script on your computer, you need to change the values of the scala.home and scalatest.jar properties to match the location of your Scala and Scalatest installations (never mind the latter if you use another unit testing framework).

If you are working in a team, it is good practice to put Ant properties into a separate properties file, so that the build file can be checked into a source code management tool. I have included them here for simplicity. One of the advantages of using Ant is that it has very good integration with IDEs, such as Eclipse. The only twist is that Eclipse does not honour the classpaths defined in build.xml for its own incremental compilation process used to mark syntactical errors. Thus if you import the Ant project into Eclipse, you have to tell Eclipse about the dependencies using the Project/Properties/Java Build Path option.

scala ant XML