Changed the way properties are set.

Added improved comments to properties files.

6 files changed, 116 insertions, 29 deletions

diff --git a/build.xml b/build.xml
index f6cae98cb0..1bdcfac1ad 100644
--- a/build.xml
+++ b/build.xml
@@ -5,8 +5,8 @@
     <description>
       This build-file builds the Scala NSC compiler as well as various related
       tools. The 'build.TEMPLATE.properties' file must be customised for your
-      own particular system, no other customisation should be required. 
-      The build file expects the file structure of a Scala CVS distribution.
+      own particular system, no other customisation should be required. The
+      build file expects the file structure of a Scala CVS distribution.
     </description>
 
     <!-- The system classpath should not be used -->
@@ -15,14 +15,15 @@
     <!-- Properties in 'build.${user.name}.properties' take precedence over
          properties in 'build.default.properties'.
     -->
-    <echo level="verbose">Loading properties from '${basedir}/build.support/build.${user.name}.properties'</echo>
-    <property file="${basedir}/build.support/build.${user.name}.properties" />
-    <echo level="verbose">Loading properties from '${basedir}/build.support/build.default.properties'</echo>
-    <property file="${basedir}/build.support/build.default.properties" />
+    <echo level="verbose">Loading properties from '${basedir}/build.support/build.base.properties'</echo>
+    <property file="${basedir}/build.support/build.base.properties" />
+    <echo level="verbose">Loading properties from '${build.support.dir}/build.${user.name}.properties'</echo>
+    <property file="${build.support.dir}/build.${user.name}.properties" />
+    <echo level="verbose">Loading properties from '${build.support.dir}/build.default.properties'</echo>
+    <property file="${build.support.dir}/build.default.properties" />
     
     <!-- A path containing pre-compiled Scala libraries found typically
-         in a Scala distribution.
-    -->
+         in a Scala distribution. -->
     <path id="osc.classpath">
         <pathelement location="${oslib.jar}" />
         <pathelement location="${oslib.src}" />
@@ -68,13 +69,13 @@
                 <available classname="scala.tools.scalac.ant.Scalac" classpathref="osc.classpath" />
             </and></not></condition>
         </fail>
-        <fail message="Required classes for OSC are missing; check the 'fjbg.jar' property in 'build.${user.name}.properties'.">
+        <fail message="Required classes for FJBG are missing; check the 'fjbg.jar' property in 'build.${user.name}.properties'.">
             <condition><not><and>
                 <available classname="ch.epfl.lamp.fjbg.JField" classpathref="osc.classpath"/>
                 <available classname="ch.epfl.lamp.util.ByteArray" classpathref="osc.classpath"/>
             </and></not></condition>
         </fail>
-        <fail message="Required classes for OSC are missing; check the 'msil.jar' property in 'build.${user.name}.properties'.">
+        <fail message="Required classes for MSIL are missing; check the 'msil.jar' property in 'build.${user.name}.properties'.">
             <condition><not><and>
                 <available classname="ch.epfl.lamp.compiler.msil.Module" classpathref="osc.classpath"/>
                 <available classname="ch.epfl.lamp.compiler.msil.Type" classpathref="osc.classpath"/>
diff --git a/config/build.TEMPLATE.properties b/config/build.TEMPLATE.properties
index 5c22052057..09d5df423d 100644
--- a/config/build.TEMPLATE.properties
+++ b/config/build.TEMPLATE.properties
@@ -1,3 +1,13 @@
+################################################################################
+# USER PROPERTIES FOR SABBUS                                                   #
+################################################################################
+These are user-specific properties for SABBUS. Any property that has not been
+set here will take the value defined in 'build.default.properties' or 'build.
+base.properties'. Properties in the latter of these files can be refered to from
+within this file.
+# $Id$
+################################################################################
+
 # The path to the old Scala library JAR package and source directory.
 oslib.jar=
 oslib.src=
diff --git a/config/build.base.properties b/config/build.base.properties
new file mode 100644
index 0000000000..3681cf97d2
--- /dev/null
+++ b/config/build.base.properties
@@ -0,0 +1,14 @@
+################################################################################
+# BASE PROPERTIES FOR SABBUS                                                   #
+################################################################################
+These are properties specific to the layout of the Scala distribution. DO NOT
+CHANGE them unless one of the mentioned directory is changed.
+# $Id$
+################################################################################
+
+build.support.dir=${basedir}/build.support
+doc.dir=${basedir}/doc
+newsources.dir=${basedir}/newsources
+sources.dir=${basedir}/sources
+support.dir=${basedir}/build.support
+test.dir=${basedir}/test
diff --git a/config/build.default.properties b/config/build.default.properties
index 15b13e3371..cf9dd5513c 100644
--- a/config/build.default.properties
+++ b/config/build.default.properties
@@ -1,42 +1,96 @@
-# These are the default properties for the Scala build script.
+################################################################################
+# DEFAULT PROPERTIES FOR SABBUS                                                #
+################################################################################
+These are default values for all properties used by SABBUS. DO NOT CHANGE them
+in this file. All properties can be overriden in the build.USER_NAME.properties
+file.
 # $Id$
+################################################################################
 
-# DO NOT CHANGE THIS FILE!
-# Changes should be made in the 'build.USER_NAME.properties' file,
-# that will override the properties in this file.
+# CONFIGURATION OF NSC
+################################################################################
 
+# What NSC should output during compilation. Either 'none', 'verbose', 'debug'.
 nsc.logging=none
+
+# After which compile phase NSC should stop. This will induce build errors.
 nsc.stop=
+
+# A comma-separated list of compile phases that NSC should skip.
 nsc.skip=
+
+# A comma-separated list of compile phases which result should be checked for
+# consistency.
 nsc.check=
-nsc.nslib.excludes=${basedir}/build.support/nsc.nslib.excludes
-nsc.nstools.excludes=${basedir}/build.support/nsc.nstools.excludes
 
+# The name of a file that lists files that should be excluded when building
+# the new Scala library. This file MUST EXIST.
+nsc.nslib.excludes=${support.dir}/nsc.nslib.excludes
+
+# The name of a file that lists files that should be excluded when building
+# the new Scala tools. This file MUST EXIST.
+nsc.nstools.excludes=${support.dir}/nsc.nstools.excludes
+
+# LOCATION OF PRE-COMPILED LIBRARIES
+################################################################################
+
+# The path to the old Scala library ('scala.jar').
 oslib.jar=/usr/local/lib/scala.jar
+
+# The path to the old Scala library sources.
 oslib.src=/usr/local/share/scala/src
+
+# The path to the old Scala tools ('tools.jar').
 ostools.jar=/usr/local/lib/tools.jar
+
+# The path to the JaCo compiler ('jaco.jar).
 jaco.jar=/usr/local/lib/jaco.jar
+
+# The path to the FJBG byte-code generation library ('fjbg.jar').
 fjbg.jar=/usr/local/lib/fjbg.jar
+
+# The path to the MSIL byte-code generation library ('fjbg.jar').
 msil.jar=/usr/local/lib/msil.jar
+
+# The path to the Java base classes ('rt.jar' or 'classes.jar').
 java.jar=${java.home}/jre/lib/rt.jar
 
+# The path to the Ant base classes ('ant.jar').
 ant.jar=${ant.home}/lib/ant.jar
 
-doc.dir=${basedir}/doc
-newsources.dir=${basedir}/newsources
-sources.dir=${basedir}/sources
-support.dir=${basedir}/support
-test.dir=${basedir}/test
+# LOCATION OF BUILD PRODUCTS
+################################################################################
 
+# The directory in which all build products live.
 build.dir=${basedir}/build
+
+# The directory to which the new Scala library is compiled.
 build.nslib.dir=${build.dir}/nslib
+
+# The directory to which the new Scala tools (built with OSC) are compiled.
 build.osc-nstools.dir=${build.dir}/osc-nstools
+
+# The directory to which the new Scala tools are compiled.
 build.nstools.dir=${build.dir}/nstools
-build.oslib.dir=${build.dir}/oslib
-build.ostools.dir=${build.dir}/ostools
+
+# LOCATION AND STRUCTURE OF THE DISTRIBUTION
+# Overriding these properties will produce a non-standard distribution that
+# might not be useable.
+################################################################################
+
+# The directory to which a new distribution will be added.
 distrib.dir=${basedir}/dist
+
+# The prefix of the directory in which a distribution will reside. This will be
+# completed by the date of the distribution.
 distrib.current.prefix=nscala
 
+# The JAR file in which the new Scala library should be archived.
 distrib.nslib.jar=nslib.jar
+
+# The JAR file in which the new Scala tools should be archived.
 distrib.nstools.jar=nstools.jar
+
+# The JAR file in which the new Scala tools (built with OSC) should be archived.
 distrib.osc-nstools.jar=osc-nstools.jar
+
diff --git a/config/excludes/nsc.nslib.excludes b/config/excludes/nsc.nslib.excludes
index 5fb8fc55b6..8ce9b911c6 100644
--- a/config/excludes/nsc.nslib.excludes
+++ b/config/excludes/nsc.nslib.excludes
@@ -1,3 +1,8 @@
-# A list of files to exclude when compiling the Scala library with NSC.
-# All files can be defined using Ant's fileset wildcard notation;
-# one statement per line.
\ No newline at end of file
+################################################################################
+# NSLIB EXCLUDED FILES                                                         #
+################################################################################
+# A list of files to exclude when compiling the Scala library with NSC. All
+# files can be defined using Ant's fileset wildcard notation; one statement per
+# line.
+# $Id$
+################################################################################
diff --git a/config/excludes/nsc.nstools.excludes b/config/excludes/nsc.nstools.excludes
index 7eeaaf3167..90516e6d14 100644
--- a/config/excludes/nsc.nstools.excludes
+++ b/config/excludes/nsc.nstools.excludes
@@ -1,3 +1,6 @@
-# A list of files to exclude when compiling the Scala tools with NSC.
-# All files can be defined using Ant's fileset wildcard notation;
-# one statement per line.
\ No newline at end of file
+################################################################################
+# NSTOOLS EXCLUDED FILES                                                       #
+################################################################################
+# A list of files to exclude when compiling the Scala tools with NSC. All files # can be defined using Ant's fileset wildcard notation; one statement per line.
+# $Id$
+################################################################################