Installing and Running

Installing on Linux
Installing on OS X
Installing on Windows
Installing for JRuby
Using multiple versions of Buildr
Running Buildr
Help Tasks
Learning More

All In One Bundle

Contributors to this project maintain a separate distribution over on RubyForge. Using this distribution, it is possible to install Buildr just like you would install Apache Ant or Apache Maven. It comes bundled with JRuby and distributed as a cross-platform zip or tar.gz file.

The RubyForge distribution is not an official Apache distribution. The all-in-one bundles are hosted on the Files page.

In details: Navigate to Rubyforge’s buildr’s Files page and download the all-in-one bundle for the latest version available.

Unzip the bundle in a convenient location.

You can execute the buildr executable under the bin directory directly.

You should consider adding the bin directory of the result to the PATH global environment variable. See Installing Buildr for JRuby for instructions to update it.

Installing the gem

The easy way: We recommend you pick the platform you want to run Buildr on and then follow the easy way instructions for that platform. It could save you an hour or two struggling to install all the right dependencies.

Installing Buildr for JRuby is the same on all operating systems. Choose JRuby if you’re working with Java 6 on OS X, developing with multiple JDKs, or just like JRuby better.

If you are running behind a proxy server, make sure the environment variable HTTP_PROXY is set, as many of these steps require HTTP access.

In details: The gem install and gem update commands install Buildr from a binary distribution provided through RubyForge. This distribution is maintained by contributors to this project, but is not an official Apache distribution. You can obtain the official Apache distribution files from the download page.

Older versions of RubyGems are all kind of fail. You want to avoid these unless you have the patience to install each Buildr dependency manually. Get RubyGems 1.3.1 or later, and when using Debian packages (e.g. Ubuntu), make sure to get the unmolested RubyGems straight form the source.

The Ruby interpreter and JVM must use compatible architectures. For example, OS X comes with 32-bit version of Ruby, Java 1.5 in both 32-bit and 64-bit flavors, and 64-bit Java 6. As a result you can run Ruby with Java 1.5 (32-bit), but to use Java 6 you either need to build Ruby from source for 64-bit, or use Buildr for JRuby.

Installing on Linux

The easy way: Use this bash script to install Buildr on Linux. 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.

In details: To get started you will need a recent version of Ruby, Ruby Gems and build tools for compiling native libraries (make, gcc and standard headers).

On RedHat/Fedora you can use yum to install Ruby and RubyGems, and then upgrade to the most recent version of RubyGems:

$ sudo yum install ruby rubygems ruby-devel gcc
$ sudo gem update --system

On Ubuntu you have to install several packages:

$ sudo apt-get install ruby-full ruby1.8-dev libopenssl-ruby build-essential

If using Ubuntu 9.10 or earlier, the Debian package for rubygems will not allow you to install Buildr, so you need to install RubyGems from source:

$ wget http://rubyforge.org/frs/download.php/45905/rubygems-1.3.1.tgz
$ tar xzf rubygems-1.3.1.tgz
$ cd rubygems-1.3.1
$ sudo ruby setup.rb
$ sudo ln -s /usr/bin/gem1.8 /usr/bin/gem

Before installing Buildr, please set the JAVA_HOME environment variable to point to your JDK distribution. Next, use Ruby Gem to install Buildr:

$ sudo env JAVA_HOME=$JAVA_HOME gem install buildr

To upgrade to a new version or install a specific version:

$ sudo env JAVA_HOME=$JAVA_HOME gem update buildr
$ sudo env JAVA_HOME=$JAVA_HOME gem install buildr -v 1.4.3

Installing on OS X

The easy way: Use this script to install Buildr on OS X. 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 (using MacPorts/Fink) and upgrage RubyGems to 1.3.1 or later.

You need to have the Apple Development Tools installed. They are available on the Mac OSX installation CD.

Java Update 3 for Snow Leopard removes header files necessary to compile the native Ruby-Java Bridge (RJB) gem, so installing rjb gem may fail on OS X. The solution is to install Java for Mac OS X 10.6 Update 3 Developer Package from http://connect.apple.com before gem install.

Using RVM? If you’re not using the built-in ruby on OS X (e.g., if you’re using RVM), you’ll need to force-install the platform-independent RJB:

$ gem install rjb -v 1.3.3 --platform ruby

The darwin pre-built binary seems to only work with the built-in ruby.

In details: OS X 10.5 (Leopard) comes with a recent version of Ruby 1.8.6. You do not need to install a different version of Ruby when running OS X 10.5.

OS X 10.4 (Tiger) includes an older version of Ruby that is not compatible with Buildr. You can install Ruby 1.8.6 using MacPorts (sudo port install ruby rb-rubygems), Fink or the Ruby One-Click Installer for OS X.

We recommend you first upgrade to the latest version of Ruby gems:

$ sudo gem update --system

Before installing Buildr, please set the JAVA_HOME environment variable to point to your JDK distribution:

$ export JAVA_HOME=/Library/Java/Home

To install Buildr:

$ sudo env JAVA_HOME=$JAVA_HOME gem install buildr

To upgrade to a new version or install a specific version:

$ sudo env JAVA_HOME=$JAVA_HOME gem update buildr
$ sudo env JAVA_HOME=$JAVA_HOME gem install buildr -v 1.3.4

Installing on Windows

The easy way: The easiest way to install Ruby is using the one-click installer. Be sure to install Ruby 1.8.6; support for Ruby 1.9.x is still a work in progress. Once installed, set the JAVA_HOME environment variable and run gem install buildr --platform mswin32.

In details: Before installing Buildr, please set the JAVA_HOME environment variable to point to your JDK distribution. Next, use Ruby Gem to install Buildr:

> gem install buildr --platform mswin32

To upgrade to a new version or install a specific version:

> gem update buildr
> gem install buildr -v 1.3.4 --platform mswin32

Installing for JRuby

The easy way: Use this bash script to install Buildr on JRuby. This script will install the most recent version of Buildr, or if already installed, upgrade to the most recent version. If necessary, it will also install JRuby 1.6.1 in /opt/jruby and update the PATH variable in ~/.bash_profile or ~/.profile.

In details: If you don’t already have JRuby 1.5.1 or later installed, you can download it from the JRuby site.

After uncompressing JRuby, update your PATH to include both java and jruby executables.

For Linux and OS X:

$ export PATH=$PATH:[path to JRuby]/bin:$JAVA_HOME/bin
$ jruby -S gem install buildr

For Windows:

> set PATH=%PATH%;[path to JRuby]/bin;%JAVA_HOME%/bin
> jruby -S gem install buildr

To upgrade to a new version or install a specific version:

$ jruby -S gem update buildr
$ jruby -S gem install buildr -v 1.3.4

Important: Running JRuby and Ruby side by side

Ruby and JRuby maintain separate Gem repositories, and in fact install slightly different versions of the Buildr Gem (same functionality, different dependencies). Installing Buildr for Ruby does not install it for JRuby and vice versa.

If you have JRuby installed but not Ruby, the gem and buildr commands will use JRuby. If you have both JRuby and Ruby installed, follow the instructions below. To find out if you have Ruby installed (some operating systems include it by default), run ruby --version from the command line.

To work exclusively with JRuby, make sure it shows first on the path, for example, by setting PATH=/opt/jruby/bin:$PATH.

You can use JRuby and Ruby side by side, by running scripts with the -S command line argument. For example:

$ # with Ruby
$ ruby -S gem install buildr
$ ruby -S buildr
$ # with JRuby
$ jruby -S gem install buildr
$ jruby -S buildr

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.

Using multiple versions of Buildr

Rubygems makes it possible to install several versions of Buildr side-by-side on the same system. If you want to run a specific version, you can do so by adding the version number between underscores (‘_’) as the first command-line parameter. For example,

$ buildr _1.3.4_ clean   # runs Buildr v1.3.4

$ buildr _1.4.4_ clean   # runs Buildr v1.4.4

There are two `buildr` executables installed by Rubygems. One script serves to select the specified (or default) version of Buildr and is typically found under `/usr/bin/buildr` or `/var/lib/gems/1.8/bin/buildr`. The exact location will vary depending on your system. The other script is the Buildr bootstrap per se and can be found under the specific version of Buildr, e.g, `/var/lib/gems/1.8/gems/buildr-1.4.0/bin/buildr`. The first script should be on your `PATH`. The second script should not be called directly and should not be on your `PATH`.

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. If you don’t already have one, ask Buildr to create it by running buildr.

You’ll notice that Buildr creates a file called buildfile. It’s case sensitive, but Buildr will look for either buildfile or Buildfile.

You use Buildr by running the buildr command:

$ buildr [options] [tasks] [name=value]

There are several options you can use, for a full list of options type buildr --help:

Option	Usage
`-f/--buildfile [file]`	Specify the buildfile.
`-e/--environment [name]`	Environment name (e.g. development, test, production).
`-h/--help`	Display this help message.
`-n/--nosearch`	Do not search parent directories for the buildfile.
`-q/--quiet`	Do not log messages to standard output.
`-r/--require [file]`	Require MODULE before executing buildfile.
`-t/--trace`	Turn on invoke/execute tracing, enable full backtrace.
`-v/--verbose`	Log message to standard output
`-V/--version`	Display the program version.
`-P/--prereqs`	Display tasks and dependencies, then exit.

You can tell Buildr to run specific tasks and the order to run them. For example:

# Clean and rebuild
buildr clean build
# Package and install
buildr install

If you don’t specify a task, Buildr will run the build task, 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.

There are several environment variables that let you control how Buildr works, for example, to skip test cases during a build, or specify options for the JVM. Depending on the variable, you may want to set it once in your environment, or set a different value each time you run Buildr.

For example:

$ export JAVA_OPTS='-Xms1g -Xmx1g'
$ buildr TEST=no

Help Tasks

Buildr includes a number of informative tasks. Currently that number stands at two, but we’ll be adding more tasks in future releases. These tasks report information from the Buildfile, so you need one to run them. For more general help (version number, command line arguments, etc) use buildr --help.

To start with, type:

$ buildr help

You can list the name and description of all your projects using the help:projects task. For example:

$ buildr help:projects
killer-app                 # Code. Build. ??? Profit!
killer-app:teh-api         # Abstract classes and interfaces
killer-app:teh-impl        # All those implementation details
killer-app:la-web          # What our users see

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.

So next let’s talk about projects.

Learning More

Ruby It pays to pick up Ruby as a second (or first) programming language. It’s fun, powerful and slightly addictive. If you’re interested in learning Ruby the language, a good place to start is Programming Ruby: The Pragmatic Programmer’s Guide, fondly known as the Pickaxe book.

For a quicker read (and much more humor), Why’s (Poignant) Guide to Ruby is available online. More resources are listed on the ruby-lang web site.

Rake Buildr is based on Rake, a Ruby build system that handles tasks and dependencies. Check out the Rake documentation for more information.

AntWrap Buildr uses AntWrap, for configuring and running Ant tasks. You can learn more from the Antwrap documentation.

YAML Buildr uses YAML for its profiles. You can learn more about YAML here, and use this handy YAML quick reference.