buildr-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From djspie...@apache.org
Subject svn commit: r925719 - /buildr/trunk/doc/languages.textile
Date Sun, 21 Mar 2010 02:44:18 GMT
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.



Mime
View raw message