svn commit: r925719 - /buildr/trunk/doc/languages.textile

[dj...@apache.org]

Author: djspiewak
Date: Sun Mar 21 02:44:18 2010
New Revision: 925719

URL: http://svn.apache.org/viewvc?rev=925719&view=rev
Log:
Added documentation for Scala 2.8 change detection and enablement

Modified:
    buildr/trunk/doc/languages.textile

Modified: buildr/trunk/doc/languages.textile
URL: http://svn.apache.org/viewvc/buildr/trunk/doc/languages.textile?rev=925719&r1=925718&r2=925719&view=diff
==============================================================================
--- buildr/trunk/doc/languages.textile (original)
+++ buildr/trunk/doc/languages.textile Sun Mar 21 02:44:18 2010
@@ -226,6 +226,7 @@ The Scala compiler supports the followin
 | @:deprecation@  | If true, shows deprecation messages.  False by default. |
 | @:optimise@     | Generates faster bytecode by applying optimisations to the program. |
 | @:other@        | Array of options passed to the compiler (e.g. @:other=>'-Xprint-types'@). |
+| @:make@         | Make strategy to be used by the compiler (e.g. @:make=>'transitive'@).  *Scala 2.8 only* |
 | @:target@       | Bytecode compatibility (e.g. '1.4'). |
 | @:warnings@     | Issue warnings when compiling.  True when running in verbose mode. |
 | @:javac@        | A hash of options passed to the @javac@ compiler verbatim. |
@@ -236,10 +237,41 @@ You may use @fsc@, the Fast Scala Compil
 
 h4. Rebuild detection
 
-The Scala compiler task assumes that each @.scala@ source file generates a  corresponding @.class@ file under @target/classes@ (or @target/test/classses@  for tests). The source may generate more @.class@ files if it contains more than one class, object, trait or for anonymous functions and closures.
+The Scala 2.7 compiler task assumes that each @.scala@ source file generates a  corresponding @.class@ file under @target/classes@ (or @target/test/classses@  for tests). The source may generate more @.class@ files if it contains more than one class, object, trait or for anonymous functions and closures.
 
 For example, @src/main/scala/com/example/MyClass.scala@ should generate at least @target/classes/com/example/MyClass.class@. If that it not the case, Buildr will always recompile your sources because it will assume this is a new source file that has never been compiled before.
 
+Fortunately, Scala 2.8 provides a substantially better interface for implementing change detection.  Whenever you use Scala 2.8 (see below), Buildr will auto-detect the version and enable this feature dynamically.  After the @compile@ task runs, the relevant target directory will contain a @.scala-deps@ file, generated by the Scala compiler.  The manner in which this file is used can be configured using the @:make@ compiler option.  The following values are available:
+
+* @:all@ - Disables compiler-level change detection
+* @:changed@ - Only build changed files without considering file dependencies
+* @:immediate@ - *unknown*
+* @:transitive@ - Build changed files as well as their transitive file dependencies
+* @:transitivenocp@ - Build changed files as well as their transitive file dependencies (*default*)
+
+Please note that there are limits to compiler-level change detection.  Most notably, dependencies cannot be tracked across separate compilation targets.  This would cause problems in the case where an API has been changed in a main source file.  The test suite for the project will *not* be detected as requiring recompilation, potentially resulting in unexpected runtime exceptions.  When in doubt, run @clean@ to remove all dependency information.  In extreme cases, it is possible to completely disable compiler-level change detection by adding the following statement to your project definition:
+
+{% highlight ruby %}
+compile.using :make => :all
+{% endhighlight %}
+
+Effectively, this is telling the Scala compiler to ignore the information it has built up regarding source file dependencies.  When in this mode, only Buildr's change detection semantics remain in play (as described above).
+
+To avoid unusual behavior, compiler-level change detection is disabled whenever the joint Scala-Java compiler is used.  Thus, any @.java@ files in a project handled by the Scala compiler will cause the @:make@ option to be ignored and revert to the exclusive use of Buildr's change detection mechanism (as described above).
+
+h4. Scala 2.8
+
+As of version 1.4, Buildr has *non-default* support for Scala 2.8.  If your @SCALA_HOME@ environment variable is pointing to an installation of Scala 2.8, then Buildr will use that compiler and enable 2.8-specific features.
+
+As Scala 2.8 is currently pre-release, it is often desirable to maintain an installation of Scala 2.7 concurrently with Scala 2.8, defaulting to the former with the option to select the latter on a project-by-project basis.  This is most easily accomplished by setting @SCALA_HOME@ to point to the Scala 2.7 installation and @SCALA28_HOME@ to point to the Scala 2.8 installation.  With this configuration in place, Scala 2.8 can be selected for a specific project by dynamically reassigning @SCALA_HOME@ at the top of the buildfile (*before* @require 'buildr/scala'@):
+
+{% highlight ruby %}
+ENV['SCALA_HOME'] = ENV['SCALA28_HOME']
+
+require 'buildr/scala'
+...
+{% endhighlight %}
+
 h3. Testing with Scala
 
 Buildr supports two main Scala testing frameworks:   "ScalaTest":http://www.artima.com/scalatest and  "Specs":http://code.google.com/p/specs/.  "ScalaCheck":http://code.google.com/p/scalacheck/ is also supported within the confines of either of these two frameworks.  Thus, your Specs may use ScalaCheck properties, as may your ScalaTest suites.