buildr 1.3.5 → 1.4.0

data/doc/languages.textile

@@ -101,9 +101,9 @@ testng: 5.7
 {% endhighlight %}
 
 
-h4. JBehave 
+h4. JBehave
 
-"JBehave":http://jbehave.org/ is a pure Java BDD framework, stories and behaviour specifications are written in the Java language. 
+"JBehave":http://jbehave.org/ is a pure Java BDD framework, stories and behaviour specifications are written in the Java language.
 
 To use JBehave in your project you can select it with @test.using :jbehave@.
 
@@ -126,51 +126,75 @@ jbehave: 1.0.1
 {% endhighlight %}
 
 
-h2(#scala). Scala
+h3. Documentation
 
-Before using Scala, you must first @require@ the Scala compiler:
+Buildr offers support for using JavaDoc to generate documentation from any Java sources in a project.  This is done using the @doc@ task:
 
-{% highlight ruby %}
-require 'buildr/scala'
+{% highlight sh %}
+$ buildr doc
 {% endhighlight %}
 
-By default, Buildr will attempt to use any version of Scala which is already
-installed on your system.  However, Buildr isn't *quite* smart enough to intuit
-such things on its own, so for most cases, it requires the @SCALA_HOME@
-environment variable to be set pointing to the root of the Scala installation
-(e.g. @/usr/local/scala-2.7.5.final@).  The only exception to this is if you have
-installed Scala via "MacPorts":http://www.macports.org/  Buildr will look in the
-@/opt/local/share/scala/@ directory *before* it uses the @SCALA_HOME@ envar.
+This will use the same @.java@ sources used by the @compile@ task to produce JavaDoc results in the @target/doc/@ directory.  By default, these sources are chosen only from the current project.  However, it is possible to override this and generate documentation from the sources in a sub-project (potentially more than one):
+
+{% highlight ruby %}
+define 'foo' do
+  # ...
+
+  doc.from projects('foo:bar', 'foo')
+
+  define 'bar' do
+    # ...
+  end
+end
+{% endhighlight %}
 
-However, if @SCALA_HOME@ is not set, or if it points to an invalid Scala
-installation, then Buildr has a fallback option.  The Scala compiler and standard
-library are both available from the "Scala Tools repository":http://scala-tools.org/.
-If no other Scala installation can be found, Buildr will download the appropriate
-artifacts and use them instead of a full install.  The only drawback to this
-approach is the FSC compiler is *not* available when Scala has been downloaded
-in this fashion.
+With this configuration, the @doc@ task will use sources from both @foo:bar@ and
+@foo@.
 
-When Scala is downloaded from the Maven2 repository, Buildr will attempt to use
-the very latest version (starting from version 2.7.5).  If you wish to override
-this default, you will need to make use of the @artifact_ns@ construct *before*
-you @require@ Scala support in your buildfile:
+The @doc@ task supports any option that the @javadoc@ command does (e.g. @-windowtitle@).  To pass an option to the JavaDoc generator, simply specify it using the @doc@ method:
 
 {% highlight ruby %}
-artifact_ns['Buildr::Compiler::Scalac'].library = '2.7.5'
+define 'foo' do
+  # ...
+
+  doc :windowtitle => 'Abandon All Hope, Ye Who Enter Here', :private => true
+end
+{% endhighlight %}
+
+
+h2(#scala). Scala
+
+Before using Scala, you must first @require@ the Scala compiler:
 
+{% highlight ruby %}
 require 'buildr/scala'
 {% endhighlight %}
 
-This snippet tells Buildr to use exactly version 2.7.5 of Scala when it downloads
-the JARs from Scala-Tools, regardless of what the latest version may be.
+By default, Buildr will attempt to use the latest stable release of Scala, which is currently Scala 2.7.7 as of April 2010.  Of course you can configure a specific version of Scala for your project by adding the following entry in @build.yaml@:
+
+{% highlight yaml %}
+scala.version: 2.8.0.Beta1  # Pick your version
+{% endhighlight %}
+
+Or, you can do the same programmatically:
 
-Regardless of how Scala has been obtained, you may determine the version in use
-by querying the @Scala.version@ attribute:
+{% highlight yaml %}
+# Must be placed before require 'buildr/scala'
+Buildr.settings.build['scala.version'] = "2.8.0.Beta1"
+{% endhighlight %}
+
+You may also determine the version in use by querying the @Scala.version@ attribute:
 
 {% highlight ruby %}
-Scala.version       # => '2.7.5'
+Scala.version       # => '2.7.7'
 {% endhighlight %}
 
+Regardless of how the Scala version is determined, if you have the same Scala version installed on your system and the SCALA_HOME environment variable points to it, then your local installation will be used.   Otherwise, Buildr will download it from the "Scala Tools repository":http://scala-tools.org/ which is automatically enlisted when you @require@ Scala.  The only drawback if you don't have a local installation is the FSC compiler won't be available.
+
+p(tip). For Mac users, if you have installed Scala via "MacPorts":http://www.macports.org/  Buildr will look in the
+@/opt/local/share/scala/@ directory if you have not set @SCALA_HOME@.
+
+
 h3. Compiling Scala
 
 The Scala compiler looks for source files in the project's @src/main/scala@  directory, and defaults to compiling them into the @target/classes@ directory.  It looks for test cases in the project's @src/test/scala@ and defaults to  compile them into the @target/test/classes@ directory.
@@ -190,6 +214,7 @@ The Scala compiler supports the following options:
 | @: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. |
@@ -200,10 +225,41 @@ You may use @fsc@, the Fast Scala Compiler, which submits compilation jobs to a
 
 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.
@@ -236,17 +292,17 @@ import org.scalatest._
 
 class PropertyTestSuite extends FunSuite {
   var properties = Map[String, Any]()
-  
+
   test("testProperty") {
     assert(properties("name") === "value")
   }
 
-  protected override def runTests(testName: Option[String], 
-    reporter: Reporter, stopper: Stopper, includes: Set[String], 
+  protected override def runTests(testName: Option[String],
+    reporter: Reporter, stopper: Stopper, includes: Set[String],
     excludes: Set[String], properties: Map[String, Any])
   {
-    this.properties = properties;                              
-    super.runTests(testName, reporter, stopper, 
+    this.properties = properties;
+    super.runTests(testName, reporter, stopper,
                    includes, excludes, properties)
   }
 }
@@ -283,7 +339,7 @@ OBJENESIS = 'org.objenesis:objenesis:jar:1.1'
 
 define 'killer-app' do
   ...
-  
+
   test.with MOCKITO, CGLIB, ASM, OBJENESIS
 end
 {% endhighlight %}
@@ -316,6 +372,52 @@ class MySuite extends PropSuite {
 {% endhighlight %}
 
 
+h3. Documentation
+
+Buildr offers support for using ScalaDoc or VScalaDoc to generate documentation from any Scala sources in a project.  This is done using the @doc@ task:
+
+{% highlight sh %}
+$ buildr doc
+{% endhighlight %}
+
+This will use the same @.scala@ sources used by the @compile@ task to produce ScalaDoc results in the @target/doc/@ directory.  By default, these sources are chosen only from the current project.  However, it is possible to override this and generate documentation from the sources in a sub-project (potentially more than one):
+
+{% highlight ruby %}
+define 'foo' do
+  # ...
+
+  doc.from projects('foo:bar', 'foo')
+
+  define 'bar' do
+    # ...
+  end
+end
+{% endhighlight %}
+
+With this configuration, the @doc@ task will use sources from both @foo:bar@ and
+@foo@.
+
+The @doc@ task supports any option that the @scaladoc@ command does (e.g. @-windowtitle@).  To pass an option to the ScalaDoc (or VScalaDoc) generator, simply specify it using the @doc@ method:
+
+{% highlight ruby %}
+define 'foo' do
+  # ...
+
+  doc :windowtitle => 'Abandon All Hope, Ye Who Enter Here', :private => true
+end
+{% endhighlight %}
+
+By default, the @doc@ task will use the ScalaDoc generator on Scala projects.  To select the VScalaDoc generator, you must use the @doc.using@ invocation:
+
+{% highlight ruby %}
+define 'foo' do
+  doc.using :vscaladoc
+end
+{% endhighlight %}
+
+The @doc@ task is *not* joint-compilation aware.  Thus, it will only generate ScalaDoc for mixed-source projects, it will not attempt to generate both JavaDoc and ScalaDoc.
+
+
 h2(#groovy). Groovy
 
 h3. Compiling Groovy
@@ -357,9 +459,9 @@ h3. Testing with Groovy
 
 h4. EasyB
 
-"EasyB":http://www.easyb.org/ is a BDD framework using "Groovy":http://groovy.codehaus.org/. 
+"EasyB":http://www.easyb.org/ is a BDD framework using "Groovy":http://groovy.codehaus.org/.
 
-Specifications are written in the Groovy language, of course you get seamless Java integration as with all things groovy. 
+Specifications are written in the Groovy language, of course you get seamless Java integration as with all things groovy.
 
 To use this framework in your project you can select it with @test.using :easyb@.
 
@@ -378,6 +480,44 @@ Supports the following options:
 | @:format@       | Report format, either @:txt@ or @:xml@ |
 
 
+h3. Documentation
+
+Buildr offers support for using GroovyDoc to generate documentation from any Groovy sources in a project.  This is done using the @doc@ task:
+
+{% highlight sh %}
+$ buildr doc
+{% endhighlight %}
+
+This will use the same @.groovy@ sources used by the @compile@ task to produce GroovyDoc results in the @target/doc/@ directory.  By default, these sources are chosen only from the current project.  However, it is possible to override this and generate documentation from the sources in a sub-project (potentially more than one):
+
+{% highlight ruby %}
+define 'foo' do
+  # ...
+
+  doc.from projects('foo:bar', 'foo')
+
+  define 'bar' do
+    # ...
+  end
+end
+{% endhighlight %}
+
+With this configuration, the @doc@ task will use sources from both @foo:bar@ and
+@foo@.
+
+The @doc@ task supports any option that the @groovydoc@ command does (e.g. @-windowtitle@).  To pass an option to the GroovyDoc generator, simply specify it using the @doc@ method:
+
+{% highlight ruby %}
+define 'foo' do
+  # ...
+
+  doc :windowtitle => 'Abandon All Hope, Ye Who Enter Here', :private => true
+end
+{% endhighlight %}
+
+The @doc@ task is *not* joint-compilation aware.  Thus, it will only generate GroovyDoc for mixed-source projects, it will not attempt to generate both JavaDoc and GroovyDoc.
+
+
 h2(#ruby).  Ruby
 
 h3.  Testing with Ruby
@@ -390,15 +530,15 @@ Because of the use of JRuby, you will notice that running ruby tests is faster w
 
 p(tip). When not running on JRuby, Buildr will use the @JRUBY_HOME@ environment variable to find the JRuby installation directory.  If no @JRUBY_HOME@ is set or it points to an empty directory, Buildr will prompt you to either install JRuby manually or let it  extract it for you.
 
-You can use the @build.yaml@ settings file to specify a particular version of JRuby (defaults to @1.1.4@).  For example:
+You can use the @build.yaml@ settings file to specify a particular version of JRuby (defaults to @1.4.0@ as of Buildr 1.3.5).  For example:
 
 {% highlight yaml %}
-jruby: 1.1.3
+jruby: 1.3.1
 {% endhighlight %}
 
 h4.  RSpec
 
-"RSpec":http://rspec.info/ is the de-facto BDD framework for ruby. It's the framework used to test Buildr itself. 
+"RSpec":http://rspec.info/ is the de-facto BDD framework for ruby. It's the framework used to test Buildr itself.
 
 To use this framework in your project you can select it with @test.using :rspec@.
 

data/doc/more_stuff.textile

@@ -280,7 +280,7 @@ Buildr.application.on_failure do |title, message, ex|
 end
 {% endhighlight %}
 
-You can place this code inside @buildr.rb@ in your home directory.
+You can place this code inside @buildr.rb@ in the @.buildr@ directory under your home directory.
 
 h2(#eclipse). Eclipse
 
@@ -390,7 +390,7 @@ require 'buildr/java/emma'
 require 'buildr/jdepend'
 {% endhighlight %}
 
-You may want to add those to the Buildfile.  Alternatively, you can use these tasks for all your projects without modifying the Buildfile.  One convenient method is to add these lines to the @buildr.rb@ file in your home directory.
+You may want to add those to the Buildfile.  Alternatively, you can use these tasks for all your projects without modifying the Buildfile.  One convenient method is to add these lines to the @buildr.rb@ file in the @.buildr@ directory under your home directory.
 
 Another option is to require it from the command line (@--require@ or @-r@), for example:
 

data/doc/packaging.textile

@@ -101,22 +101,21 @@ The @include@ method accepts files, directories and file tasks.  You can also us
 And the same way you @include@, you can also @exclude@ specific files you don't want showing up in the ZIP.  For example, to exclude @.draft@ and @.raw@ files:
 
 {% highlight ruby %}
-package(:zip).include('target/docs').
-  exclude('target/docs/**/*.{draft,raw}')
+package(:zip).include(_('target/docs')).exclude('*.draft', '*.raw')
 {% endhighlight %}
 
 So far we've included files under the root of the ZIP.  Let's include some files under a given path using the @:path@ option:
 
 {% highlight ruby %}
-package(:zip).include 'target/docs', :path=>"#{id}-#{version}"
+package(:zip).include _('target/docs'), :path=>"#{id}-#{version}"
 {% endhighlight %}
 
 If you need to use the @:path@ option repeatedly, consider using the @tap@ method instead.  For example:
 
 {% highlight ruby %}
 package(:zip).path("#{id}-#{version}").tap do |path|
-  path.include 'target/docs'
-  path.include 'README'
+  path.include _('target/docs')
+  path.include _('README')
 end
 {% endhighlight %}
 
@@ -127,33 +126,33 @@ p(note). To allow you to spread files across different paths, the include/exclud
 If you need to include a file or directory under a different name, use the @:as@ option.  For example:
 
 {% highlight ruby %}
-package(:zip).include('corporate-logo-350x240.png', :as=>'logo.png')
+package(:zip).include(_('corporate-logo-350x240.png'), :as=>'logo.png')
 {% endhighlight %}
 
 You can also use @:as=>'.'@ to include all files from the given directory.  For example:
 
 {% highlight ruby %}
-package(:zip).include 'target/docs/*'
-package(:zip).include 'target/docs', :as=>'.'
+package(:zip).include _('target/docs/*')
+package(:zip).include _('target/docs'), :as=>'.'
 {% endhighlight %}
 
-These two are almost identical.  They both include all the files from the @target/docs@ directory, but not the directory itself.  But they operate differently.  The first line expands to include all the files in @target/docs@. If you don't already have files in @target/docs@, well, then it won't do anything interesting.  Your ZIP will come up empty.  The second file includes the directory itself, but strips the path during inclusion.  You can define it now, create these files later, and then ZIP them all up.
+These two perform identically.  They both include all the files from the @target/docs@ directory, but not the directory itself, and they are both lazy, meaning that the files can be created later and they will still get packaged into the zip package.
 
-For example, when @package :jar@ decides to include all the files from @target/classes@, it's still working on the project definition, and has yet to compile anything.  Since @target/classes@ may be empty, may not even exist, it uses @:as=>'.'@.
+For example, when you use @package :jar@, under the hood it specifies to include all the files from @target/classes@ with @:as=>'.'@.  Even though this happens during project definition and nothing has been compiled yet (and in fact @target/classes@ may not even exist yet), the .class files generated during compilation are still packaged in the .jar file, as expected.
 
 If you need to get rid of all the included files, call the @clean@ method. Some packaging types default to adding various files and directories, for example, JAR packaging will include all the compiled classes and resources.
 
 You can also merge two ZIP files together, expanding the content of one ZIP into the other.  For example:
 
 {% highlight ruby %}
-package(:zip).merge 'part1.zip', 'part2.zip'
+package(:zip).merge _('part1.zip'), _('part2.zip')
 {% endhighlight %}
 
 If you need to be more selective, you can apply the include/exclude pattern to the expanded ZIP.  For example:
 
 {% highlight ruby %}
 # Everything but the libs
-package(:zip).merge('bigbad.war').exclude('libs/**/*')
+package(:zip).merge(_('bigbad.war')).exclude('libs/**/*')
 {% endhighlight %}
 
 
@@ -257,7 +256,7 @@ If you already have WSDL files in the @src/main/axis2@ directory but would like
 {% highlight ruby %}
 # Host name depends on environment.
 host = ENV['ENV'] == 'test' ? 'test.host' : 'ws.example.com'
-filter.from('src/main/axis2').into('target').
+filter.from(_('src/main/axis2')).into(_(:target)).
   include('services.xml', '==*==.wsdl').using('http_port'=>'8080', 'http_host'=>host)
 package(:aar).wsdls.clear
 package(:aar).with(:services_xml=>_('target/services.xml'), :wsdls=>_('target/==*==.wsdl'))
@@ -404,11 +403,11 @@ package :sources
 
 This one creates a ZIP package with the classifier "sources" that will contain all the source directories in that project, typically @src/main/java@, but also other sources generated from Apt, JavaCC, XMLBeans and friends.
 
-You can also generate a ZIP package with the classifier "javadoc" that contains the JavaDoc documentation for the project.  It uses the same set of documentation files generated by the project's @javadoc@ task, so you can use it in combination with the @javadoc@ method.  For example:
+You can also generate a ZIP package with the classifier "javadoc" that contains the JavaDoc documentation for the project.  It uses the same set of documentation files generated by the project's @doc@ task, so you can use it in combination with the @doc@ method.  For example:
 
 {% highlight ruby %}
 package :javadoc
-javadoc :windowtitle=>'Buggy but Works'
+doc :windowtitle=>'Buggy but Works'
 {% endhighlight %}
 
 By default Buildr picks the project's description for the window title.

data/doc/projects.textile

@@ -13,7 +13,9 @@ Feed it a project definition, and Buildr will set up all these tasks for you. Th
 The remainder of this guide deals with what it takes to build a project.  But first, let's pick up a sample project to work with.  We'll call it _killer-app_:
 
 {% highlight ruby %}
-require 'buildr'
+require "buildr/openjpa"
+
+include Buildr::OpenJPA
  
 VERSION_NUMBER = '1.0'
  
@@ -90,7 +92,7 @@ When you start with a new project you won't see the @target@ or @reports@ direct
 
 h2(#naming). Naming And Finding Projects
 
-Each project has a given name, the first argument you pass when calling @define@.  The project name is just a string, but we advise to stay clear of colon (@:@) and slashes (@/@ and @\@), which could conflict with other task and file names.  Also, avoid using common Buildr task names, don't pick @compile@ or @build@ for your project name.
+Each project has a given name, the first argument you pass when calling @define@.  The project name is just a string, but we advise to stay clear of colon (@:@) and slashes (@/@ and @\@), which could conflict with other task and file names.  Also, avoid using common Buildr task names, don't pick @compile@, @build@ or any existing task name for your project name.
 
 Since each project knows its parent project, child projects and siblings, you can reference them from within the project using just the given name.  In other cases, you'll need to use the full name.  The full name is just @parent:child@. So if you wanted to refer to _teh-impl_, you could do so with either @project('killer-app:teh-impl')@ or @project('killer-app').project('teh-impl')@.
 
@@ -201,6 +203,9 @@ For example:
 # Relative to the current project
 path_to('src', 'main', 'java')
 
+# the same using symbols
+path_to(:src, :main, :java)
+
 # Exactly the same thing
 _('src/main/java')
 

data/doc/quick_start.textile

@@ -169,7 +169,7 @@ If there is one area in which Buildr excels, it is defining custom tasks.  This
 define 'killer-app' do
   project.version = '0.1.0'
   package :jar
-  
+
   task :run => :compile do
     system 'java -cp target/classes org.apache.killer.Main'
   end
@@ -185,13 +185,13 @@ $ buildr killer-app:run
 This works, but it's clumsy.  The reason we had to give the "@killer-app:@" prefix is because we defined the @run@ task _within_ our project, rather than outside of the @define@ block.  However, if we define @run@ outside of the project, then we don't really have access to the @compile@ task (which is project-specific).  The solution here is a bit of magic known as @local_task@.  This is how tasks like @compile@ and @test@, which are technically project-specific (think: instance methods) can be invoked without the fully-qualified project name:
 
 {% highlight ruby %}
-local_task :run
+Project.local_task :run
 
 define 'killer-app' do
   project.version '0.1.0'
-  
+
   package :jar
-  
+
   task :run => :compile do
     system 'java -cp target/classes org.apache.killer.Main'
   end