Documentation on the development of the Scala compiler and standard library.
Run ant build-opt
to build an optimized version of the compiler.
Verify your build using ant test-opt
.
The Scala build system is based on Apache Ant. Most required pre-compiled libraries are part of the repository (in 'lib/'). The following however is assumed to be installed on the build machine:
We ask all contributors sign the Scala Contributor License Agreement, which allows us to ensure that all code submitted to the project is unencumbered by copyrights or patents.
Please follow the guidelines outlined in our (Pull Request Policy)[https://github.com/scala/scala/wiki/Pull-Request-Policy].
scala/
+--build.xml The main Ant build script, see also under src/build.
+--lib/ Pre-compiled libraries for the build.
+--pull-binary-libs.sh Pulls binary artifacts from remote repository.
+--src/ All the source files of Scala.
+--test/ The Scala test suite.
+--build/ [Generated] Build products output directory for ant.
+--dist/ [Generated] The destination folder for Scala distributions.
Here are some common commands. Most ant targets offer a -opt
variant that runs under -optimise
.
./pull-binary-libs.sh
downloads all binary artifacts associated with this commit.
This requires internet access to http://typesafe.artifactoryonline.com/typesafe.
ant -p
prints out information about the commonly used ant targets. The interested
developer can find the rest in the XML files.
ant
or ant build
: A quick compilation (to quick) of your changes using the locker compiler.
ln -s build/quick/bin qbin
(once):
ant && qbin/scalac -d sandbox sandbox/test.scala && qbin/scala -cp sandbox Test
Incrementally builds quick, and then uses it to compile and run the file
sandbox/test.scala
. This is a typical debug cycle.
ant test
tests that your code is working and fit to be committed.
ant docs
generates the HTML documentation for the library from the sources using the
scaladoc tool in quick. Note: on most machines this requires more heap than
is allocate by default. You can adjust the parameters with ANT_OPTS.
Example command line::
ANT_OPTS = "-Xms512M -Xmx2048M -Xss1M -XX:MaxPermSize=128M" ant docs
ant dist
builds a distribution in 'dists/latest'.
ant all.clean
Removes all build files and all distributions.
In order to guarantee the bootstrapping of the Scala compiler, SABBUS builds Scala in layers. Each layer is a complete compiled Scala compiler and library. A superior layer is always compiled by the layer just below it. Here is a short description of the four layers that SABBUS uses, from bottom to top:
starr
: the stable reference Scala release which is shared by all the
developers. It is found in the repository as 'lib/scala-compiler.jar' and
'lib/scala-library.jar'. Any committable source code must be compiled directly
by starr to guarantee the bootstrapping of the compiler.
locker
: the local reference which is compiled by starr and is the work
compiler in a typical development cycle. When it has been built once, it is
“frozen” in this state. Updating it to fit the current source code must be
explicitly requested (see below).
quick
: the layer which is incrementally built when testing changes in the
compiler or library. This is considered an actual new version when locker is
up-to-date in relation to the source code.
strap
: a test layer used to check stability of the build.
SABBUS compiles, for each layer, the Scala library first and the compiler next. That means that any changes in the library can immediately be used in the compiler without an intermediate build. On the other hand, if building the library requires changes in the compiler, a new locker must be built if bootstrapping is still possible, or a new starr if it is not.
Use ant replacelocker
to "unfreeze" locker by updating it to match the current source code.