buildr 1.3.4 → 1.3.5

data/doc/{getting_started.textile → installing.textile}

@@ -1,6 +1,6 @@
 ---
 layout: default
-title: Getting Started
+title: Installing and Running
 ---
 
 
@@ -20,7 +20,7 @@ The Ruby interpreter and JVM must use compatible architectures.  For example, OS
 
 h2(#linux).  Installing on Linux
 
-*The easy way:* Use this bash script to "install Buildr on Linux":scripts/install-linux.sh.  This script will install the most recent version of Buildr, or if already installed, upgrade to the most recent version.  It will also install Ruby 1.8.6 if not already installed (requires @apt-get@ or @yum@) and upgrade to RubyGems 1.3.1 or later.
+*The easy way:* Use this bash script to "install Buildr on Linux":scripts/install-linux.sh.  This script will install the most recent version of Buildr, or if already installed, upgrade to the most recent version.  It will also install Ruby 1.8.6 if not already installed (requires @apt-get@, @yum@ or @urpmi@) and upgrade to RubyGems 1.3.1 or later.
 
 p(note). At this time, the native Ruby-Java Bridge (RJB) does not work very well on Linux with JDK 1.6.  If you get Segmentation Fault errors with JDK 1.6, we recommend switching to JDK 1.5.
 
@@ -30,24 +30,19 @@ p(note). At this time, the native Ruby-Java Bridge (RJB) does not work very well
 
 On *RedHat/Fedora* you can use yum to install Ruby and RubyGems, and then upgrade to the most recent version of RubyGems:
 
-<notextile>
 {% highlight sh %}
 $ sudo yum install ruby rubygems ruby-devel gcc
 $ sudo gem update --system
 {% endhighlight %}
-</notextile>
 
 On *Ubuntu* you have to install several packages:
 
-<notextile>
 {% highlight sh %}
 $ sudo apt-get install ruby-full ruby1.8-dev libopenssl-ruby build-essential 
 {% endhighlight %}
-</notextile>
 
 The Debian package for @rubygems@ will not allow you to install Buildr, so you need to install RubyGems from source:
 
-<notextile>
 {% highlight sh %}
 $ wget http://rubyforge.org/frs/download.php/45905/rubygems-1.3.1.tgz
 $ tar xzf rubygems-1.3.1.tgz
@@ -55,24 +50,19 @@ $ cd rubygems-1.3.1
 $ sudo ruby setup.rb
 $ sudo ln -s /usr/bin/gem1.8 /usr/bin/gem
 {% endhighlight %}
-</notextile>
 
 Before installing Buildr, please set the @JAVA_HOME@ environment variable to point to your JDK distribution.  Next, use Ruby Gem to install Buildr:
 
-<notextile>
 {% highlight sh %}
 $ sudo env JAVA_HOME=$JAVA_HOME gem install buildr
 {% endhighlight %}
-</notextile>
 
 To upgrade to a new version or install a specific version:
 
-<notextile>
 {% highlight sh %}
 $ sudo env JAVA_HOME=$JAVA_HOME gem update buildr
 $ sudo env JAVA_HOME=$JAVA_HOME gem install buildr -v 1.3.4
 {% endhighlight %}
-</notextile>
 
 
 
@@ -88,36 +78,28 @@ OS X 10.4 (Tiger) includes an older version of Ruby that is not compatible with
 
 We recommend you first upgrade to the latest version of Ruby gems:
 
-<notextile>
 {% highlight sh %}
 $ sudo gem update --system
 {% endhighlight %}
-</notextile>
 
 Before installing Buildr, please set the @JAVA_HOME@ environment variable to point to your JDK distribution:
 
-<notextile>
 {% highlight sh %}
 $ export JAVA_HOME=/Library/Java/Home
 {% endhighlight %}
-</notextile>
 
 To install Buildr:
 
-<notextile>
 {% highlight sh %}
 $ sudo env JAVA_HOME=$JAVA_HOME gem install buildr
 {% endhighlight %}
-</notextile>
 
 To upgrade to a new version or install a specific version:
 
-<notextile>
 {% highlight sh %}
 $ sudo env JAVA_HOME=$JAVA_HOME gem update buildr
 $ sudo env JAVA_HOME=$JAVA_HOME gem install buildr -v 1.3.4
 {% endhighlight %}
-</notextile>
 
 
 h2(#windows).  Installing on Windows
@@ -128,28 +110,22 @@ h2(#windows).  Installing on Windows
 
 *In details:* We recommend you first upgrade to the latest version of Ruby gems:
 
-<notextile>
 {% highlight sh %}
 > gem update --system
 {% endhighlight %}
-</notextile>
 
 Before installing Buildr, please set the @JAVA_HOME@ environment variable to point to your JDK distribution.  Next, use Ruby Gem to install Buildr:
 
-<notextile>
 {% highlight sh %}
 > gem install buildr
 {% endhighlight %}
-</notextile>
 
 To upgrade to a new version or install a specific version:
 
-<notextile>
 {% highlight sh %}
 > gem update buildr
 > gem install buildr -v 1.3.4
 {% endhighlight %}
-</notextile>
 
 
 h2(#jruby).  Installing for JRuby
@@ -164,30 +140,24 @@ After uncompressing JRuby, update your @PATH@ to include both @java@ and @jruby@
 
 For Linux and OS X:
 
-<notextile>
 {% highlight sh %}
 $ export PATH=$PATH:[path to JRuby]/bin:$JAVA_HOME/bin
 $ jruby -S gem install buildr
 {% endhighlight %}
-</notextile>
 
 For Windows:
 
-<notextile>
 {% highlight sh %}
 > set PATH=%PATH%;[path to JRuby]/bin;%JAVA_HOME%/bin
 > jruby -S gem install buildr
 {% endhighlight %}
-</notextile>
 
 To upgrade to a new version or install a specific version:
 
-<notextile>
 {% highlight sh %}
 $ jruby -S gem update buildr
 $ jruby -S gem install buildr -v 1.3.4
 {% endhighlight %}
-</notextile>
 
 
 *Important: Running JRuby and Ruby side by side*
@@ -200,7 +170,6 @@ To work exclusively with JRuby, make sure it shows first on the path, for exampl
 
 You can use JRuby and Ruby side by side, by running scripts with the @-S@ command line argument.  For example:
 
-<notextile>
 {% highlight sh %}
 $ # with Ruby
 $ ruby -S gem install buildr
@@ -209,34 +178,10 @@ $ # with JRuby
 $ jruby -S gem install buildr
 $ jruby -S buildr
 {% endhighlight %}
-</notextile>
 
 Run @buildr --version@ from the command line to find which version of Buildr you are using by default.  If you see @(JRuby ...)@, Buildr is running on that version of JRuby.
 
 
-h2(#conventions). Document Conventions
-
-Lines that start with @$@ are command lines, for example:
-
-<notextile>
-{% highlight sh %}
-$ # Run Buildr
-$ buildr
-{% endhighlight %}
-</notextile>
-
-Lines that start with @=>@ show output from the console or the result of a method, for example:
-
-<notextile>
-{% highlight sh %}
-puts 'Hello world'
-=> "Hello world"
-{% endhighlight %}
-</notextile>
-
-And as you guessed, everything else is Buildfile Ruby or Java code.  You can figure out which language is which.
-
-
 h2(#running). Running Buildr
 
 You need a *Buildfile*, a build script that tells Buildr all about the projects it's building, what they contain, what to produce, and so on.  The Buildfile resides in the root directory of your project.  We'll talk more about it in "the next chapter":projects.html.  If you don't already have one, ask Buildr to create it by running @buildr@.
@@ -245,11 +190,9 @@ p(tip). You'll notice that Buildr creates a file called @buildfile@.  It's case
 
 You use Buildr by running the @buildr@ command:
 
-<notextile>
 {% highlight sh %}
 $ buildr [options] [tasks] [name=value]
 {% endhighlight %}
-</notextile>
 
 There are several options you can use, for a full list of options type @buildr --help@:
 
@@ -266,14 +209,12 @@ There are several options you can use, for a full list of options type @buildr -
 
 You can tell Buildr to run specific tasks and the order to run them.  For example:
 
-<notextile>
 {% highlight sh %}
 # Clean and rebuild
 buildr clean build
 # Package and install
 buildr install
 {% endhighlight %}
-</notextile>
 
 If you don't specify a task, Buildr will run the "@build@ task":building.html, compiling source code and running test cases.  Running a task may run other tasks as well, for example, running the @install@ task will also run @package@.
 
@@ -281,12 +222,10 @@ There are several "environment variables":settings_profiles.html#env_vars that l
 
 For example:
 
-<notextile>
 {% highlight sh %}
 $ export JAVA_OPTS='-Xms1g -Xmx1g'
 $ buildr TEST=no
 {% endhighlight %}
-</notextile>
 
 
 h2(#help). Help Tasks
@@ -295,15 +234,12 @@ Buildr includes a number of informative tasks.  Currently that number stands at
 
 To start with, type:
 
-<notextile>
 {% highlight sh %}
 $ buildr help
 {% endhighlight %}
-</notextile>
 
 You can list the name and description of all your projects using the @help:projects@ task.  For example:
 
-<notextile>
 {% highlight sh %}
 $ buildr help:projects
 killer-app                 # Code. Build. ??? Profit!
@@ -311,7 +247,6 @@ killer-app:teh-api         # Abstract classes and interfaces
 killer-app:teh-impl        # All those implementation details
 killer-app:la-web          # What our users see
 {% endhighlight %}
-</notextile>
 
 You are, of course, describing your projects for the sake of those who will maintain your code, right?  To describe a project, or a task, call the @desc@ method before the project or task definition.
 

data/doc/languages.textile

@@ -46,11 +46,9 @@ The JUnit test framework supports the following options:
 
 For example, to pass properties to the test case:
 
-<notextile>
 {% highlight ruby %}
 test.using :properties=>{ :currency=>'USD' }
 {% endhighlight %}
-</notextile>
 
 There are benefits to running test cases in separate VMs.  The default forking mode is @:once@, and you can change it by setting the @:fork@ option.
 
@@ -63,34 +61,28 @@ You can see your tests running in the console, and if any tests fail, Buildr wil
 
 In addition, you can get a consolidated XML or HTML report by running the @junit:report@ task.  For example:
 
-<notextile>
 {% highlight sh %}
 $ buildr test junit:report test=all
 $ firefox report/junit/html/index.html
 {% endhighlight %}
-</notextile>
 
 The @junit:report@ task generates a report from all tests run so far.  If you run tests in a couple of projects, it will generate a report only for these two projects.  The example above runs tests in all the projects before generating the reports.
 
 You can use the @build.yaml@ settings file to specify a particular version of JUnit or JMock.  For example, to force your build to use JUnit version 4.4 and JMock 2.0:
 
-<notextile>
 {% highlight yaml %}
 junit: 4.4
 jmock: 2.0
 {% endhighlight %}
-</notextile>
 
 
 h4. TestNG
 
 You can use "TestNG":http://testng.org instead of JUnit.  To select TestNG as the test framework, add this to your project:
 
-<notextile>
 {% highlight ruby %}
 test.using :testng
 {% endhighlight %}
-</notextile>
 
 Like all other options you can set with @test.using@, it affects the projects and all its sub-projects, so you only need to do this once at the top-most project to use TestNG throughout.  You can also mix TestNG and JUnit by setting different projects to use different frameworks, but you can't mix both frameworks in the same project.  (And yes, @test.using :junit@ will switch a project back to using JUnit)
 
@@ -104,11 +96,9 @@ The TestNG test framework supports the following options:
 
 You can use the @build.yaml@ settings file to specify a particular version of TestNG, for example, to force your build to use TestNG 5.7:
 
-<notextile>
 {% highlight yaml %}
 testng: 5.7
 {% endhighlight %}
-</notextile>
 
 
 h4. JBehave 
@@ -119,11 +109,9 @@ To use JBehave in your project you can select it with @test.using :jbehave@.
 
 This framework will search for the following patterns under your project:
 
-<notextile>
 {% highlight text %}
 src/spec/java/**/*Behaviour.java
 {% endhighlight %}
-</notextile>
 
 Supports the following options:
 
@@ -133,42 +121,55 @@ Supports the following options:
 
 You can use the @build.yaml@ settings file to specify a particular version of JBehave, for example, to force your build to use JBehave 1.0.1:
 
-<notextile>
 {% highlight yaml %}
 jbehave: 1.0.1
 {% endhighlight %}
-</notextile>
 
 
 h2(#scala). Scala
 
-Before using Scala features, you must first set the @SCALA_HOME@ environment variable to point to the root of your Scala distribution.
+Before using Scala, you must first @require@ the Scala compiler:
 
-On Windows:
-
-<notextile>
-{% highlight sh %}
-> set SCALA_HOME=C:\Path\To\Scala-2.7.3
+{% highlight ruby %}
+require 'buildr/scala'
 {% endhighlight %}
-</notextile>
 
-On Linux and other Unix variants,
+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.
+
+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.
+
+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:
 
-<notextile>
-{% highlight sh %}
-> export SCALA_HOME=/path/to/scala-2.7.3
+{% highlight ruby %}
+artifact_ns['Buildr::Compiler::Scalac'].library = '2.7.5'
+
+require 'buildr/scala'
 {% endhighlight %}
-</notextile>
 
-The @SCALA_HOME@ base directory should be such that Scala core libraries are located directly under the "lib" subdirectory, and Scala scripts are under the "bin" directory. This step is not necessary if you installed Scala using MacPorts (OS X).
+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.
 
-You must also require the Scala compiler in your buildfile:
+Regardless of how Scala has been obtained, you may determine the version in use
+by querying the @Scala.version@ attribute:
 
-<notextile>
 {% highlight ruby %}
-require 'buildr/scala'
+Scala.version       # => '2.7.5'
 {% endhighlight %}
-</notextile>
 
 h3. Compiling Scala
 
@@ -207,11 +208,9 @@ 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.
 
-<notextile>
 {% highlight ruby %}
 test.using(:scalatest)
 {% endhighlight %}
-</notextile>
 
 h4. ScalaTest
 
@@ -221,7 +220,6 @@ Buildr automatically detects and runs tests that extend the @org.scalatest.Suite
 
 A very simplistic test class might look like,
 
-<notextile>
 {% highlight scala %}
 class MySuite extends org.scalatest.FunSuite {
   test("addition") {
@@ -230,11 +228,9 @@ class MySuite extends org.scalatest.FunSuite {
   }
 }
 {% endhighlight %}
-</notextile>
 
 You can also pass properties to your tests by doing @test.using :properties => { 'name'=>'value' }@, and by overriding the @Suite.runTests@ method in a manner similar to:
 
-<notextile>
 {% highlight scala %}
 import org.scalatest._
 
@@ -255,7 +251,6 @@ class PropertyTestSuite extends FunSuite {
   }
 }
 {% endhighlight %}
-</notextile>
 
 h4. Specs
 
@@ -265,7 +260,6 @@ Any objects which extend the @org.specs.Specification@ superclass will be automa
 
 A simple specification might look like this:
 
-<notextile>
 {% highlight scala %}
 import org.specs._
 import org.specs.runner._
@@ -273,18 +267,33 @@ import org.specs.runner._
 object StringSpecs extends Specification {
   "empty string" should {
     "have a zero length" in {
-      ("".length) mustEqual(0)
+      "".length mustBe 0
     }
   }
 }
 {% endhighlight %}
-</notextile>
+
+ScalaCheck is automatically added to the classpath when Specs is used.  However, JMock, Mockito, CGlib and similar are _not_.  This is to avoid downloading extraneous artifacts which are only used by a small percentage of specifications.  To use Specs with Mockito (or any other library) in a Buildr project, simply add the appropriate dependencies to @test.with@:
+
+{% highlight ruby %}
+MOCKITO = 'org.mockito:mockito-all:jar:1.7'
+CGLIB = 'cglib:cglib:jar:2.1_3'
+ASM = 'asm:asm:jar:1.5.3'
+OBJENESIS = 'org.objenesis:objenesis:jar:1.1'
+
+define 'killer-app' do
+  ...
+  
+  test.with MOCKITO, CGLIB, ASM, OBJENESIS
+end
+{% endhighlight %}
+
+The dependencies for Specs's optional features are defined "here":http://code.google.com/p/specs/wiki/RunningSpecs#Dependencies.
 
 h4. ScalaCheck
 
 You may use ScalaCheck inside ScalaTest- and Specs-inherited classes.  Here is an example illustrating checks inside a ScalaTest suite,
 
-<notextile>
 {% highlight scala %}
 import org.scalatest.prop.PropSuite
 import org.scalacheck.Arbitrary._
@@ -305,7 +314,6 @@ class MySuite extends PropSuite {
   )
 }
 {% endhighlight %}
-</notextile>
 
 
 h2(#groovy). Groovy
@@ -314,11 +322,9 @@ h3. Compiling Groovy
 
 Before using the Groovy compiler, you must first require it on your buildfile:
 
-<notextile>
 {% highlight ruby %}
 require 'buildr/java/groovyc'
 {% endhighlight %}
-</notextile>
 
 Once loaded, the groovyc compiler will be automatically selected if any .groovy source files are found under @src/main/groovy@ directory, compiling them by default into the @target/classes@ directory.
 
@@ -359,12 +365,10 @@ To use this framework in your project you can select it with @test.using :easyb@
 
 This framework will search for the following patterns under your project:
 
-<notextile>
 {% highlight text %}
 src/spec/groovy/**/*Behavior.groovy
 src/spec/groovy/**/*Story.groovy
 {% endhighlight %}
-</notextile>
 
 Supports the following options:
 
@@ -388,11 +392,9 @@ p(tip). When not running on JRuby, Buildr will use the @JRUBY_HOME@ environment
 
 You can use the @build.yaml@ settings file to specify a particular version of JRuby (defaults to @1.1.4@).  For example:
 
-<notextile>
 {% highlight yaml %}
 jruby: 1.1.3
 {% endhighlight %}
-</notextile>
 
 h4.  RSpec
 
@@ -402,11 +404,9 @@ To use this framework in your project you can select it with @test.using :rspec@
 
 This framework will search for the following patterns under your project:
 
-<notextile>
 {% highlight text %}
 src/spec/ruby/**/*_spec.rb
 {% endhighlight %}
-</notextile>
 
 Supports the following options:
 
@@ -427,11 +427,9 @@ To use this framework in your project you can select it with @test.using :jtestr
 
 You can use the @build.yaml@ settings file to specify a particular version of JtestR (defaults to @0.3.1@).  For example:
 
-<notextile>
 {% highlight yaml %}
 jtestr: 0.3.1
 {% endhighlight %}
-</notextile>
 
 To customize TestNG/JUnit versions refer to their respective section.