1. Start Here
   1. Welcome
   2. Quick Start
   3. Installing & Running
   4. Community Wiki
2. Using Buildr
   1. This Guide (PDF)
   2. Projects
   3. Building
   4. Artifacts
   5. Packaging
   6. Testing
   7. Releasing
   8. Settings/Profiles
   9. Languages
   10. More Stuff
   11. Extending Buildr
   12. How-Tos
3. Reference
   1. API
   2. Rake
   3. Antwrap
   4. Troubleshooting
4. Get Involved
   1. Download
   2. Mailing Lists
   3. Twitter
   4. Issues/Bugs
   5. CI Jobs
   6. Contributing
5. 

Languages

1. Java
2. Scala
3. Groovy
4. Ruby

Java

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:

ECJ

You can use the ECJ compiler instead of javac. ECJ abides to the same options as javac.
For example, to configure the project to use ECJ:

compile.using :ecj

To use a custom version of ECJ, add an entry to your settings.
For example, to set the version of ECJ to 3.5.1, add an entry to your project’s buildr.yml:

ecj: 3.5.1

Testing with Java

JUnit

The default test framework for Java projects is JUnit 4.

When you use JUnit, the dependencies includes JUnit and JMock, 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:

For example, to pass properties to the test case:

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.

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:

$ 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:

junit: 4.4
jmock: 2.0

TestNG

You can use TestNG instead of JUnit. To select TestNG as the test framework, add this to your project:

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:

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:

testng: 5.7

JBehave

JBehave 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:

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:

jbehave: 1.0.1

Documentation

Buildr offers support for using JavaDoc to generate documentation from any Java sources in a project. This is done using the doc task:

$ buildr doc

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):

define 'foo' do
  # ...

  doc.from projects('foo:bar', 'foo')

  define 'bar' do
    # ...
  end
end

With this configuration, the doc task will use sources from both foo:bar and
foo.

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:

define 'foo' do
  # ...

  doc :windowtitle => 'Abandon All Hope, Ye Who Enter Here', :private => true
end

Scala

Before using Scala, you must first require the Scala compiler:

require 'buildr/scala'

By default, Buildr will attempt to use the latest stable release of Scala, which is currently Scala 2.9.0 as of May 2011. Of course you can configure a specific version of Scala for your project by adding the following entry in build.yaml:

scala.version: 2.8.0.Beta1  # Pick your version

Or, you can do the same programmatically:

# Must be placed before require 'buildr/scala'
Buildr.settings.build['scala.version'] = "2.8.0.Beta1"

You may also determine the version in use by querying the Scala.version attribute:

Scala.version       # => '2.8.0'

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 Sonatype repository 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.

For Mac users, if you have installed Scala via MacPorts Buildr will look in the
/opt/local/share/scala/ directory if you have not set SCALA_HOME.

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.

Any Java source files found in the src/main/java directory will be compiled using the Scala/Java joint compiler into the target/classes directory. Both the Java and the Scala sources are compiled with an inclusive classpath, meaning that you may have a Java class which depends upon a Scala class which depends upon a Java class, all within the same project. The Java sources will be compiled with the same dependencies as the Scala sources with the addition of the scala-library.jar file as required for Scala interop.

Note that you cannot use the Groovy and the Scala joint compilers in the same project. If both are required, the Groovy joint compiler will take precedence.

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. The joint compilation of Java sources may only be pointed at an alternative directory using the feature to redefine the _(:src, :main, :java) path.

When using the Scala compiler, if you don’t specify the packaging type, it defaults to JAR.

The Scala compiler supports the following options:

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.

(Note fsc is not compatible with zinc incremental compilation.)

Rebuild detection

Scala 2.7

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.

Scala 2.8

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:

compile.using :make => :all

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).

Scala 2.9 and later

Starting with Buildr 1.4.8, Buildr integrates with the Zinc incremental compilation wrapper for scalac. Incremental compilation can be enabled 3 ways,

1) By setting the compiler’s option directly,

compile.using :incremental => true

compile.options.incremental = true  # same as above

Note that this won’t enable incremental compilation for both compile and test.compile, you would have to set options on both. For this reason, it’s recommended that you set the option on the project instead (see below).

2) By setting the project’s scalac_options.incremental,

project.scalac_options.incremental = true

3) By setting the global scalac.incremental option,

in your buildfile:

Buildr.settings.build['scalac.incremental'] = true

or in your build.yaml:

scalac.incremental: true

Support for different Scala versions

Buildr defaults to the latest stable Scala version available at the time of the release if neither SCALA_HOME nor the scala.version build property are set.

If your SCALA_HOME environment variable points to an installation of Scala (2.7, 2.8, 2.9, …), then Buildr will use that compiler and enable version-specific features.

You may select the Scala version by dynamically in different ways,

1) By reassigning SCALA_HOME at the top of the buildfile (before require 'buildr/scala'):

ENV['SCALA_HOME'] = ENV['SCALA28_HOME']

require 'buildr/scala'
...

2) By setting the scala.version build property in your build.yaml file:

scala.version: 2.9.1.RC1

3) By setting the scala.version build property in your buildfile:

require 'buildr/scala'
...
Buildr.settings.build['scala.version'] = '2.10-M6'

Testing with Scala

Buildr supports two main Scala testing frameworks: ScalaTest and Specs. 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.

test.using(:scalatest)

ScalaTest

ScalaTest support is activated automatically when there are any .scala source files contained in the src/test/scala directory. If you are not using this directory convention, you may force the test framework by using the test.using :scalatest directive.

Buildr automatically detects and runs tests that extend the org.scalatest.Suite interface.

A very simplistic test class might look like,

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:

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)
  }
}

Specs

Specs is automatically selected whenever there are .scala source files under the src/spec/scala directory. It is also possible to force selection of the test framework by using the test.using :specs directive. This can sometimes be useful when Scala sources may be found in both src/test/scala and src/spec/scala. Normally in such cases, ScalaTest will have selection precedence, meaning that in case of a conflict between it and Specs, ScalaTest will be chosen.

Any objects which extend the org.specs.Specification or org.specs2.Specification superclass will be automatically detected and run. Note that any classes which extend Specification will also be invoked. As such classes will not have a main method, such an invocation will raise an error.

A simple specification might look like this:

import org.specs._
import org.specs.runner._

object StringSpecs extends Specification {
  "empty string" should {
    "have a zero length" in {
      "".length mustBe 0
    }
  }
}

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:

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

The dependencies for Specs’s optional features are defined here.

ScalaCheck

You may use ScalaCheck inside ScalaTest- and Specs-inherited classes. Here is an example illustrating checks inside a ScalaTest suite,

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
  )
}

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:

$ buildr doc

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):

define 'foo' do
  # ...

  doc.from projects('foo:bar', 'foo')

  define 'bar' do
    # ...
  end
end

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:

define 'foo' do
  # ...

  doc :windowtitle => 'Abandon All Hope, Ye Who Enter Here', :private => true
end

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:

define 'foo' do
  doc.using :vscaladoc
end

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.

Groovy

Compiling Groovy

Before using the Groovy compiler, you must first require it on your buildfile:

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:

Testing with Groovy

EasyB

EasyB is a BDD framework using 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.

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:

Documentation

Buildr offers support for using GroovyDoc to generate documentation from any Groovy sources in a project. This is done using the doc task:

$ buildr doc

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):

define 'foo' do
  # ...

  doc.from projects('foo:bar', 'foo')

  define 'bar' do
    # ...
  end
end

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:

define 'foo' do
  # ...

  doc :windowtitle => 'Abandon All Hope, Ye Who Enter Here', :private => true
end

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.

Ruby

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 language, and is run by using JRuby. 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.

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.4.0 as of Buildr 1.3.5). For example:

jruby: 1.3.1

RSpec

RSpec 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: