assaf-buildr 1.3.3

data/doc/pages/index.textile

@@ -0,0 +1,42 @@
+h1. Welcome
+
+h2.  What is Buildr?
+
+Buildr is a build system for Java applications.  We wanted something that's simple and intuitive to use, so we only need to tell it what to do, and it takes care of the rest.  But also something we can easily extend for those one-off tasks, with a language that's a joy to use.  And of course, we wanted it to be fast, reliable and have outstanding dependency management.
+
+Here's what we got:
+
+* A simple way to specify projects, and build large projects out of smaller sub-projects.
+* Pre-canned tasks that require the least amount of configuration, keeping the build script DRY and simple.
+* Compiling, copying and filtering resources, JUnit/TestNG test cases, APT source code generation, Javadoc and more.
+* A dependency mechanism that only builds what has changed since the last release.
+* A drop-in replacement for Maven 2.0, Buildr uses the same file layout, artifact specifications, local and remote repositories.
+* All your Ant tasks belong to us! Anything you can do with Ant, you can do with Buildr.
+* No overhead for building "plugins" or configuration. Just write new tasks or functions.
+* Buildr is Ruby all the way down.  No one-off task is too demanding when you write code using variables, functions and objects.
+* Simple way to upgrade to new versions.
+* Did we mention fast?
+
+So let's get started.  You can "read the documentation online":getting_started.html, or "download the PDF":buildr.pdf.
+
+
+h2.  News
+
+Check out "all that's new in Buildr 1.3.3":whats_new.html.
+
+* Buildr 1.3 now runs on JRuby 1.1 and Ruby 1.8.6.
+* Support for building Scala and Groovy projects.
+* Behavior-Driven Development frameworks (RSpec, JBehave, etc).
+* Profiles and build.yml settings file.
+* New API for accessing Java libraries.
+* More documentation.
+* Other features and bug fixes.
+
+
+h2.  Notices
+
+The Apache Software Foundation is a non-profit organization, consider "sponsoring":http://www.apache.org/foundation/sponsorship.html and check the "thanks":http://www.apache.org/foundation/thanks.html page.
+
+Apache Buildr is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.
+
+"ColorCons":http://www.mouserunner.com/Spheres_ColoCons1_Free_Icons.html, copyright of Ken Saunders.  "DejaVu fonts":http://dejavu.sourceforge.net, copyright of Bitstream, Inc.

data/doc/pages/languages.textile

@@ -0,0 +1,407 @@
+h1. Languages
+
+
+h2. Java
+
+
+h3. Compiling Java
+
+The Java compiler looks for source files in the project's @src/main/java@ directory, and defaults to compiling them into the @target/classes@ directory. It looks for test cases in the project's @src/test/java@ and defaults to compile them into the @target/test/classes@ directory.
+
+If you point the @compile@ task at any other source directory, it will use the Java compiler if any of these directories contains files with the extension @.java@.
+
+When using the Java compiler, if you don't specify the packaging type, it defaults to JAR.  If you don't specify the test framework, it defaults to JUnit.
+
+The Java compiler supports the following options:
+
+|_. Option        |_. Usage |
+| @:debug@        | Generates bytecode with debugging information.  You can also override this by setting the environment variable @debug@ to @off@. |
+| @:deprecation@  | If true, shows deprecation messages.  False by default. |
+| @:lint@         | Defaults to false.  Set this option to true to use all lint options, or specify a specific lint option (e.g. @:lint=>'cast'@). |
+| @:other@        | Array of options passed to the compiler (e.g. @:other=>'-implicit:none'@). |
+| @:source@       | Source code compatibility (e.g. '1.5'). |
+| @:target@       | Bytecode compatibility (e.g. '1.4'). |
+| @:warnings@     | Issue warnings when compiling.  True when running in verbose mode. |
+
+
+h3.  Testing with Java
+
+h4. JUnit
+
+The default test framework for Java projects is "JUnit 4":http://www.junit.org.
+
+When you use JUnit, the dependencies includes JUnit and "JMock":http://www.jmock.org, and Buildr picks up all test classes from the project by looking for classes that either subclass  @junit.framework.TestCase@, include methods annotated with @org.junit.Test@, or test suites annotated with @org.org.junit.runner.RunWith@.
+
+The JUnit test framework supports the following options:
+
+|_. Option        |_. Value |
+| @:fork@         | VM forking, defaults to true. |
+| @:clonevm@      | If true clone the VM each time it is forked. |
+| @:properties@   | Hash of system properties available to the test case. |
+| @:environment@  | Hash of environment variables available to the test case. |
+| @:java_args@    | Arguments passed as is to the JVM. |
+
+For example, to pass properties to the test case:
+
+{{{!ruby
+test.using :properties=>{ :currency=>'USD' }
+}}}
+
+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.
+
+|_. :fork=> |_. Behavior |
+| @:once@   | Create one VM to run all test classes in the project, separate VMs for each project. |
+| @:each@   | Create one VM for each test case class.  Slow but provides the best isolation between test classes. |
+| @false@   | Without forking, Buildr runs all test cases in a single VM.  This option runs fastest, but at the risk of running out of memory and causing test cases to interfere with each other. |
+
+You can see your tests running in the console, and if any tests fail, Buildr will show a list of the failed test classes.  In addition, JUnit produces text and XML report files in the project's @reports/junit@ directory.  You can use that to get around too-much-stuff-in-my-console, or when using an automated test system.
+
+In addition, you can get a consolidated XML or HTML report by running the @junit:report@ task.  For example:
+
+{{{!sh
+$ buildr test junit:report test=all
+$ firefox report/junit/html/index.html
+}}}
+
+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:
+
+{{{!yaml
+junit: 4.4
+jmock: 2.0
+}}}
+
+
+h4. TestNG
+
+You can use "TestNG":http://testng.org instead of JUnit.  To select TestNG as the test framework, add this to your project:
+
+{{{!ruby
+test.using :testng
+}}}
+
+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)
+
+TestNG works much like JUnit, it gets included in the dependency list along with JMock, Buildr picks test classes that contain methods annotated with  @org.testng.annotations.Test@, and generates test reports in the @reports/testng@ directory.  At the moment we don't have consolidated HTML reports for TestNG.
+
+The TestNG test framework supports the following options:
+
+|_. Option        |_. Value |
+| @:properties@   | Hash of system properties available to the test case. |
+| @:java_args@    | Arguments passed as is to the JVM. |
+
+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:
+
+{{{!yaml
+testng: 5.7
+}}}
+
+
+h4. JBehave 
+
+"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@.
+
+This framework will search for the following patterns under your project:
+
+{{{
+src/spec/java/**/*Behaviour.java
+}}}
+
+Supports the following options:
+
+|_. Option        |_. Value |
+| @:properties@   | Hash of system properties available to the test case. |
+| @:java_args@    | Arguments passed as is to the JVM. |
+
+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:
+
+{{{!yaml
+jbehave: 1.0.1
+}}}
+
+
+h2. Scala
+
+Before using Scala features, you must first set the @SCALA_HOME@ environment variable to point to the root of your Scala distribution.
+
+On Windows:
+
+{{{!sh
+> set SCALA_HOME=C:\Path\To\Scala-2.7.1
+}}}
+
+On Linux and other Unix variants,
+
+{{{!sh
+> export SCALA_HOME=/path/to/scala-2.7.1
+}}}
+
+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.
+
+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.
+
+If you point the @compile@ task at any other source directory, it will use the  Scala compiler if any of these directories contains files with the extension @.scala@.
+
+When using the Scala compiler, if you don't specify the packaging type, it defaults to JAR.
+
+The Scala compiler supports the following options:
+
+|_. Option        |_. Usage |
+| @:debug@        | Generates bytecode with debugging information.  You can also override this by setting the environment variable @debug@ to @off@. |
+| @: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'@). |
+| @:target@       | Bytecode compatibility (e.g. '1.4'). |
+| @:warnings@     | Issue warnings when compiling.  True when running in verbose mode. |
+
+h4. Fast Scala Compiler
+
+You may use @fsc@, the Fast Scala Compiler, which submits compilation jobs to a  compilation daemon, by setting the environment variable @USE_FSC@ to @yes@. Note that @fsc@ _may_ cache class libraries -- don't forget to run @fsc -reset@ if  you upgrade a library.
+
+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.
+
+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.
+
+h3. Testing with Scala
+
+Buildr supports three Scala testing frameworks:   "ScalaTest":http://www.artima.com/scalatest,  "ScalaCheck":http://code.google.com/p/scalacheck/ and  "Specs":http://code.google.com/p/specs/.
+
+Scala testing is automatically enabled if you have any @.scala@ source files under @src/test/scala@.  If you are not using this convention, you can explicit set the test framework by doing,
+
+{{{!ruby
+test.using(:scalatest)
+}}}
+
+The @:scalatest@ test framework handles ScalaTest, Specs and ScalaCheck therefore all 3 frameworks may be used within the same project.
+
+h4. ScalaTest
+
+Buildr automatically detects and runs tests that extend the @org.scalatest.Suite@ interface.
+
+A very simplistic test class might look like,
+
+{{{!scala
+class MySuite extends org.scalatest.FunSuite {
+  test("addition") {
+    val sum = 1 + 1
+    assert(sum === 2)
+  }
+}
+}}}
+
+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:
+
+{{{!scala
+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], 
+    excludes: Set[String], properties: Map[String, Any])
+  {
+    this.properties = properties;                              
+    super.runTests(testName, reporter, stopper, 
+                   includes, excludes, properties)
+  }
+}
+}}}
+
+h4. Specs
+
+The @:scalatest@ framework currently recognizes specifications with class names ending with "Specs", e.g., org.example.StringSpecs.
+
+A simple specification might look like this:
+
+{{{!scala
+import org.specs._
+import org.specs.runner._
+
+object StringSpecs extends Specification {
+  "empty string" should {
+    "have a zero length" in {
+      ("".length) mustEqual(0)
+    }
+  }
+}
+}}}
+
+h4. ScalaCheck
+
+You may use ScalaCheck inside ScalaTest- and Specs-inherited classes.  Here is an example illustrating checks inside a ScalaTest suite,
+
+{{{!scala
+import org.scalatest.prop.PropSuite
+import org.scalacheck.Arbitrary._
+import org.scalacheck.Prop._
+
+class MySuite extends PropSuite {
+
+  test("list concatenation") {
+    val x = List(1, 2, 3)
+    val y = List(4, 5, 6)
+    assert(x ::: y === List(1, 2, 3, 4, 5, 6))
+    check((a: List[Int], b: List[Int]) => a.size + b.size == (a ::: b).size)
+  }
+
+  test(
+    "list concatenation using a test method",
+    (a: List[Int], b: List[Int]) => a.size + b.size == (a ::: b).size
+  )
+}
+}}}
+
+
+h2. Groovy
+
+h3. Compiling Groovy
+
+Before using the Groovy compiler, you must first require it on your buildfile:
+
+{{{!ruby
+require 'buildr/java/groovyc'
+}}}
+
+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.
+
+If the project has java sources in @src/main/java@ they will get compiled using the groovyc joint compiler.
+
+Sources found in @src/test/groovy@ are compiled into the @target/test/classes@.
+
+If you don't specify the packaging type, it defaults to JAR.
+
+The Groovy compiler supports the following options:
+
+|_. Option        |_. Usage |
+| @encoding@          | Encoding of source files. |
+| @verbose@           | Asks the compiler for verbose output, true when running in verbose mode. |
+| @fork@              | Whether to execute groovyc using a spawned instance of the JVM.  Defaults to no. |
+| @memoryInitialSize@ | The initial size of the memory for the underlying VM, if using fork mode, ignored otherwise.  Defaults to the standard VM memory setting. (Examples: @83886080@, @81920k@, or @80m@) |
+| @memoryMaximumSize@ | The maximum size of the memory for the underlying VM, if using fork mode, ignored otherwise.  Defaults to the standard VM memory setting. (Examples: @83886080@, @81920k@, or @80m@) |
+| @listfiles@         | Indicates whether the source files to be compiled will be listed.  Defaults to no. |
+| @stacktrace@        | If true each compile error message will contain a stacktrace. |
+| @warnings@          | Issue warnings when compiling.  True when running in verbose mode. |
+| @debug@             | Generates bytecode with debugging information.  Set from the debug environment variable/global option. |
+| @deprecation@       | If true, shows deprecation messages.  False by default. |
+| @optimise@          | Generates faster bytecode by applying optimisations to the program. |
+| @source@            | Source code compatibility. |
+| @target@            | Bytecode compatibility. |
+| @javac@             | Hash of options passed to the ant javac task. |
+
+
+h3. Testing with Groovy
+
+h4. EasyB
+
+"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. 
+
+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:
+
+{{{
+src/spec/groovy/**/*Behavior.groovy
+src/spec/groovy/**/*Story.groovy
+}}}
+
+Supports the following options:
+
+|_. Option        |_. Value |
+| @:properties@   | Hash of system properties available to the test case. |
+| @:java_args@    | Arguments passed as is to the JVM. |
+| @:format@       | Report format, either @:txt@ or @:xml@ |
+
+
+h2.  Ruby
+
+h3.  Testing with Ruby
+
+Buildr provides integration with some ruby testing frameworks, allowing you to test your Java code with state of the art tools.
+
+Testing code is written in "Ruby":http://www.ruby-lang.org/en/ language, and is run by using "JRuby":http://jruby.codehaus.org/.That means you have access to all your Java classes and any Java or Ruby tool out there.
+
+Because of the use of JRuby, you will notice that running ruby tests is faster when running Buildr on JRuby, as in this case there's no need to run another JVM.
+
+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:
+
+{{{!yaml
+jruby: 1.1.3
+}}}
+
+h4.  RSpec
+
+"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@.
+
+This framework will search for the following patterns under your project:
+
+{{{
+src/spec/ruby/**/*_spec.rb
+}}}
+
+Supports the following options:
+
+|_. Option        |_. Value |
+| @:gems@         | Hash of gems needed before running the tests. Keys are gem names, values are the required gem version. An example use of this option would be to require the ci_reporter gem to generate xml reports |
+| @:requires@     | Array of ruby files to require before running the specs |
+| @:format@       | Array of valid RSpec @--format@ option values. Defaults to html report on the @reports@ directory and text progress |
+| @:output@       | File path to output dump. @false@ to supress output |
+| @:fork@         | Run the tests on a new java vm. (enabled unless running on JRuby) |
+| @:properties@   | Hash of system properties available to the test case. |
+| @:java_args@    | Arguments passed as is to the JVM. (only when fork is enabled) |
+
+h4.  JtestR
+
+"JtestR":http://jtestr.codehaus.org is a tool that makes it easier to test Java code with state of the art Ruby tools. Using JtestR you can describe your application behaviour using many testing frameworks at the same time.
+
+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:
+
+{{{!yaml
+jtestr: 0.3.1
+}}}
+
+To customize TestNG/JUnit versions refer to their respective section.
+
+When selected, Buildr will configure JtestR to use your project/testing classpath and will search for the following test patterns for each framework supported by JtestR:
+
+|_. Framework                    |_. Patterns |
+| "RSpec":http://rspec.info      | Files in @src/spec/ruby@ ending with @*_spec.rb@ or @*_story.rb@ |
+| "TestUnit":http://ruby-doc.org/stdlib/libdoc/test/unit/rdoc/classes/Test/Unit.html | Files in @src/spec/ruby@ ending with @*_test.rb@, @*Test.rb@ |
+| "Expectations":http://expectations.rubyforge.org/ | Files in @src/spec/ruby@ ending with @*_expect.rb@ |
+| "JUnit":http://www.junit.org   | Classes from @src/test/java@ that either subclass @junit.framework.TestCase@, include methods annotated with @org.junit.Test@, or test suites annotated with @org.org.junit.runner.RunWith@. |
+| "TestNG":http://testng.org     | Classes from @src/test/java@ annotated with  @org.testng.annotations.Test@ |
+
+If you create a @src/spec/ruby/jtestr_config.rb@ file, it will be loaded by JtestR, just after being configured by Buildr, this way you can configure as described on "JtestR guide":http://jtestr.codehaus.org/Configuration.
+
+p(tip). If you have a @jtestr_config.rb@ file, don't set @JtestR::result_handler@. Buildr uses its (@RSpecResultHandler@)  so that it can know which tests succeeded/failed, this handler is capable of using RSpec formatter classes, so that you can obtain an html report or use a custom rspec formatter with @JtestR@. See the @format@ option.
+
+Supports the following options:
+
+|_. Option        |_. Value |
+| @:config@       | The JtestR config file to be loaded after being configured by Buildr. Defaults to @src/spec/ruby/jtestr_config.rb@. |
+| @:gems@         | Hash of gems needed before running the tests. Keys are gem names, values are the required gem version. An example use of this option would be to require the ci_reporter gem to generate xml reports |
+| @:requires@     | Array of ruby files to require before running the specs |
+| @:format@       | Array of valid RSpec @--format@ option values. Defaults to html report on the @reports@ directory and text progress |
+| @:output@       | File path to output dump. @false@ to supress output |
+| @:fork@         | Run the tests on a new java vm. (enabled unless running on JRuby) |
+| @:properties@   | Hash of system properties available to the test case. (only when fork is enabled) |
+| @:java_args@    | Arguments passed as is to the JVM. (only when fork is enabled) |

data/doc/pages/mailing_lists.textile

@@ -0,0 +1,17 @@
+h1. Mailing Lists
+
+
+|_. buildr-user |_. For developers working with Buildr |
+| Post          | "buildr-user@incubator.apache.org":mailto:buildr-user@incubator.apache.org |
+| Browse        | "buildr-user archives":http://mail-archives.apache.org/mod_mbox/incubator-buildr-user/ |
+| Subscribe     | "buildr-user-subscribe@incubator.apache.org":mailto:buildr-user-subscribe@incubator.apache.org |
+| Unsubscribe   | "buildr-user-unsubscribe@incubator.apache.org":mailto:buildr-user-unsubscribe@incubator.apache.org |
+|_. buildr-dev |_. For development of Buildr itself |
+| Post          | "buildr-dev@incubator.apache.org":mailto:buildr-dev@incubator.apache.org |
+| Browse        | "buildr-dev archives":http://mail-archives.apache.org/mod_mbox/incubator-buildr-dev/ |
+| Subscribe     | "buildr-dev-subscribe@incubator.apache.org":mailto:buildr-dev-subscribe@incubator.apache.org |
+| Unsubscribe   | "buildr-dev-unsubscribe@incubator.apache.org":mailto:buildr-dev-unsubscribe@incubator.apache.org |
+|_. buildr-commits |_. Commit messages and JIRA status |
+| Subscribe     | "buildr-commits-subscribe@incubator.apache.org":mailto:buildr-commits-subscribe@incubator.apache.org |
+| Unsubscribe   | "buildr-commits-unsubscribe@incubator.apache.org":mailto:buildr-commits-unsubscribe@incubator.apache.org |
+| Browse        | "buildr-commits archives":http://mail-archives.apache.org/mod_mbox/incubator-buildr-commits/ |