getting up and running with buildr

for the last couple of days i've been trying to get buildr running on my laptop to build an example project. i already had java 1.5 running on windows, with JAVA_HOME set accordingly, and i have installed ruby 1.8.6 via the one-click installer.

i decided to follow the buildr getting started guide and but i unfortunately had problems at the first hurdle - installation. the instruction was to run the following at the command line:

gem install buildr

however this would not run as expected and instead refused to install due to a missing dependent library as indicated here:

C:\dev\ruby\gems>gem install buildr
ERROR: While executing gem ... (RuntimeError)
Error instaling buildr:
Buildr requires rubyzip >= 0.9.0

i thought it may be due to my firewall, so after reading this post on ashish's blog, i decided to download the missing gem manually from the gems repository, installing that first in the same way, then continuing as above.

this worked at first, but then i was informed by gems of another dependency, and after following this process a couple of times i realised this may take a while and i had to find another way around.

i had a look at the gems user guide and looked up the section for installing a gem remotely and found that by adding a '-r' or '--remote' at the right place would force the install to fetch the gem libraries remotely. i believed this should have happened if they libraries weren't found locally anyway, so i'm not sure why this didn't work in the first place.

so i decided to proceed, and i had a brief look at the buildr help by running 'builder --help':

Usage:
buildr [-f buildfile] {options} targets...

Options:
--buildfile (-f)
Use FILE as the buildfile.
--freeze (-F)
Freezes the Buildfile so it always uses Buildr version 1.2.5
--help (-H)
Display this help message.
--nosearch (-N)
Do not search parent directories for the buildfile.
--quiet (-q)
Do not log messages to standard output.
--require=MODULE (-r)
Require MODULE before executing buildfile.
--trace (-t)
Turn on invoke/execute tracing, enable full backtrace.
--unfreeze (-U)
Unfreezes the Buildfile to use the latest version of Buildr
--verbose (-v)
Log message to standard output (default).
--version (-V)
Display the program version.

For help with your buildfile:
buildr help

then i needed to create a simple buildfile and i could do that by just creating a top level project directory, entering that directory in my console, and simply running the 'buildr' command on its own, followed by selecting option 1, to create a buildfile from the directory structure. this is what was created:

# Generated by Buildr 1.2.5, change to your liking
# Version number for this release
VERSION_NUMBER = "1.0.0"
# Version number for the next release
NEXT_VERSION = "1.0.1"
# Group identifier for your projects
GROUP = "dvdcat"
COPYRIGHT = ""

# Specify Maven 2.0 remote repositories here, like this:
repositories.remote << "http://www.ibiblio.org/maven2/"

desc "The Dvdcat project"
define "dvdcat" do

project.version = VERSION_NUMBER
project.group = GROUP
manifest["Implementation-Vendor"] = COPYRIGHT
end

i could then have a look at the buildfile help by running 'builder help':

Buildr 1.2.5

Usage:
buildr [-f buildfile] {options} targets...

Top-level projects (buildr help:projects for full list):
dvdcat # The Dvdcat project

Common tasks:
artifacts # Download all artifacts
build # Build the project
clean # Clean files generated during a build
compile # Compile all projects
default # The default task it build
eclipse # Generate Eclipse artifacts for all projects
help:projects # List all projects defined by this buildfile
help:tasks # List all tasks available from this buildfile
idea # Generate Idea artifacts for all projects
install # Install packages created by the project
javadoc # Create the Javadocs for this project
junit:report # Generate JUnit tests report in reports/junit
package # Create packages
release # Make a release
test # Run all test cases
uninstall # Remove previously installed packages
upload # Upload packages created by the project


For help on command line options:
buildr --help

Using Java 1.5.0_06, Ant 1.7.0.

To run a full build without running any test cases:
buildr test=no
To run specific test case:
buildr test:MyTest
To run integration tests:
buildr integration

The buildr RDoc is very useful too browse through, as is the code in SVN through FishEye. This book on Ruby Programming will be of help if you're not too offay with that yet, as is Dave Thomas and Andrew Hunt's pickaxe book.