h1. Recipes

Commond recipes for Buildr, collected from the mailing list.


h2.  Creating a classpath

For Java, the classpath argument is simply a list of paths joined with an
OS-specific path separator:

{{{!ruby
cp = paths.join(File::PATH_SEPARATOR)
}}}

This assumes @paths@ points to files and/or directories, but what if you have a
list of artifact specifications?  You can turn those into file names in two
steps.  First, use @artifacts@ to return a list of file tasks that point to the
local repository:

{{{!ruby
tasks = Buildr.artifacts(specs)
}}}

Next, map that list of tasks into list of file names (essentially calling
@name@ on each task):

{{{!ruby
paths = tasks.map(&:name)
}}}

This works as long as the artifacts are already in your local repository,
otherwise they can't be found, but you can ask Buildr to download them by
calling @invoke@ on each of these tasks:

{{{!ruby
tasks = Buildr.artifacts(specs).each(&:invoke)
}}}

So let's roll this all into a single line:

{{{!ruby
cp = Buildr.artifacts(specs).each(&:invoke).map(&:name).join(File::PATH_SEPARATOR)
}}}


h2.  Keeping your Profiles.yaml file DRY

YAML allows you to use anchors (@&@), similar to ID attributes in XML, and
reference them later on (@*@).  For example, if you have two profiles that are
identical, you can tell YAML that one is an alias for the other:

{{{!yaml
development: &common
  db: oracle
  port: 8080
test: *common
production: *common
}}}

If you have two elements that are almost identical, you can merge the values of
one element into another (@<<@), for example:

{{{!yaml
development: &common
  db: hsql
  jdbc: hsqldb:mem:devdb
test:
  <<: *common
  jdbc: hsqldb:file:testdb
}}}


h2.  Speeding JRuby

When using JRuby you will notice that Buildr takes a few seconds to start up.
To speed it up, we recommend switching to Java 1.6 and running the JVM in
client mode:

{{{!
$ export JAVA_OPTS=-client
}}}


h2.  Continuous Integration with Atlassian Bamboo

This recipe outlines how to configure a new Bamboo project to use Buildr.  The
following steps assume that you have logged-on to Bamboo as an Administrator.

*1. Configure a Builder*

* Select the Administration tab from the Bamboo toolbar.
* Select the Builders area (first option) from the Administration menu.
* Using the Add Builder dialog, configure a custom builder for Buildr with the
following options:
** Label: @buildr@
** Type:  @Custom Command@
** Path:  @/path/to/buildr@ (typically "/usr/bin/buildr")

*2. Create a Plan*

* Select the Create Plan tab from the Bamboo toolbar to enter the Create Plan
wizard.
* In "1. Plan Details", define your build plan including project name, project
key, build plan name and build plan key.
* In "2. Source Repository", specify your source code repository settings (CVS
or SVN).
* In "3. Builder Configuration", specify the "buildr" builder that you defined
above, along with the following:
** Argument: @"test=all"@ (ensures that all tests are run through even if
failures are encountered)
** Test Results Directory: @"**/reports/junit/*.xml"@ (or your path to test
results, if different).
* The remaining wizard sections may be either skipped or configured with your
preferred settings.

*3. Trigger a Build*

A build should occur automatically at the point of project creation. It can
also be manually triggered at any time

* Navigate to the project summary page (located at:
@http://YOUR_BAMBOO_URL/browse/PROJECTKEY-YOURPLAN@).
* Click on the small arrow to the left of the label "Build Actions"
* Select "Checkout and Build" from the pop-up menu to force a build.

The project page will contain full status information for previous builds and
the results tabs will integrate the results from your JUnit tests.