path: root/build.readme

BUILDING NEW SCALA WITH ANT
---------------------------

This is version 1.0 of the Scala Ant-based build system SABBUS.

QUICK START
-----------

- Copy the 'build.TEMPLATE.properties' file in 'build.support' to
  'build.USER_NAME.properties'. Set all properties in this file.

- In a terminal window, type:
  ANT_OPTS="-Xmx256M" ant distrib

USAGE GUIDE
-----------

PREREQUISITES

The new Scala Ant-based build system (SABBUS) requires the following elements:
  - An old Scala distribution. The Scala tools ('tools.jar' must be of a version
    that does contain the improved Scalac Ant task at
    'scala.tools.scalac.ant.Scalac'. The scala library ('scala.jar') must contain
    all classes required to build NSC.
  - A PiCo/JaCo distribution. It must contain the improved PiCo task at
    'jaco.pizza.ant.Pico'.
  - Ant version 1.6 or above.
  - Java version 1.4 or above (Java 1.5 might not be supported).

SETTING UP

The set-up of SABBUS is done entirely in the 'build.properties' file. Make sure
that all values in this file are set and correct.

Another configuration file exists ('build.support/build.default'). This file
should not be modified as any property declared in 'build.properties' will
override the value set in 'build.default'.

With a normal Java distribution, the standard memory allocated to the JVM in
insufficient for Scala compilation. The ANT_OPTS environment variable needs to
be set to increase the memory size (either each time as in the quick start
example above, or once and for all in the default shell environment).

Skipping parts of the build

In some cases, parts of the build process should be disabled for debug reasons:
  - skip.doc will not build the LaTeX documentation.
  - skip.nsc will not build anything with NSC. This will create a non-working
             distribution.

BUILDING NEW SCALA

The 'build' target builds all the Scala library and tools. It is composed of the
following sub-targets:
  - 'build.pico.nslib':
      Builds the Java files in Scala (runtime, tools and scala root) with PiCo.
      When both a Java file in sources and a Scala file in newsources exist, the
      Java file is not compiled (it is considered to have been superseeded by the
      Scala file).
  - 'build.osc.nstools':
      Builds NSC with an existing Scalac (found in path of property
      'ostools.jar').
  - 'build.nsc.nslib':
      Builds the new Scala library with the compiler built at target
      'build.osc.nstools'. Depends on 'build.osc.nstools' & 'build.pico.nslib'.
      If files should not be compiled at that stage, they can be specified in the
      'build.support/nsc.nslib.excludes'
  - 'build.nsc.nstools':
      Builds NSC with the compiler built at target 'build.osc.nstools'. Depends
      on 'build.osc.nstools' & 'build.pico.nslib'. If files should not be
      compiled at that stage, they can be specified in the
      'build.support/nsc.nstools.excludes'

CONSTRUCTING A DISTRIBUTION

The 'distrib' target constructs a simple distribution of new Scala from the
latest build. The following steps will be done:
  - Creates a standard distribution folder hierarchy.
  - Create JAR packages for the library ('nslib.jar'), and the tools, both
    compiled with Scalac ('osc-nstools.jar') and with NSC ('nstools.jar').
  - Create script files (bash and bat) to execute the new Scala compiler.
  - Adds man files and the documentation to the distribution.
  - Generates some symbolic links to simplify navigation (only on UNIX). Amongst
    other, a 'latest' link in the 'dist' folder will point to the latest
    distribution folder (useful to refer in a permanent way to the latest
    distribution on your system).

CLEANING

The 'clean' target removes all build and distribution files.
  - 'clean.build' only removes build files and does not touch distribution files.
  - 'clean.distrib' only removes distribution files.

DOCUMENTING

Not implemented yet

TESTING

Not implemented yet

KNOWN BUGS, LIMITATIONS AND PLANNED IMPROVEMENTS
------------------------------------------------

- Create NSC executable scripts for UNIX and Windows.
- Create Windows build system.
- Create documentation.
- Support testing.

HISTORY
-------

1.0
  First functioning version. Supports clean, build and a limited distrib.