What’s New

Buildr 1.3

Buildr 1.3

Multiple Languages

The main focus of this release is supporting multiple languages for compiling and testing.

For each project, Buildr will attempt to infer which compiler to use based on the source files it finds, for example, if it finds .java files in the src/main/java directory, it will switch to the javac compiler, if it finds .scala files in the src/main/scala directory, to the scalac compiler and so forth.

Different compilers may use different target directory, target/classes is picked for JVM compilers (Java, Scala, Groovy, etc), so resources are not copied to their own directory, target/resources. The prepare task has been removed.

Not all languages have classpaths, so compile.classpath is now known as compile.dependencies, but the old attribute still exists for backward compatibility.

Also, for consistency, the test target directories have changed to target/test/classes and target/test/resources, respectively.

Speaking of tests, you can compile code in one language and use a different language to test it, say, if you’re interested in compiling Java code and testing it with Ruby, or compiling Flash and running a Java test suite.

As before, you can pick the test framework by calling test.using(<framework>). Buildr will attempt to pick one by default, for example, if the tests are written in Java, it will default to JUnit.

And, since not all languages package to JARs, the default packaging is either inferred from the compiler (so :jar when compiling Java code), otherwise to :zip. All this defaulting means that package() with no arguments does the right thing in more cases, and most probably won’t break anyone’s buildfiles.

I’ve tried to keep the compiler API as simple as possible, making it easy to add new compilers; however, I had to change the test framework API to accommodate the new features, so old test frameworks will not work on 1.3.

Scala Support

Buildr now supports Scala, using both native and fast Scala compiler.

Groovy Support

Buildr now supports Groovy, using the Groovyc Ant task.

Packaging Files

The package method is convenient enough that you can now use it to generate artifacts, an in addition to generate regular file tasks, specifying the file name using the :file attribute. For example:

package :zip, :file=>_('target/interesting.zip')

Since this package is not an artifact and does not have a specification, it will not automatically install itself in the local repository or upload to a remote repository. For these, use the package method as before.

Packaging EARs

EAR packages support four component types:

Argument	Component
`:war`	J2EE Web Application (WAR).
`:ejb`	Enterprise Java Bean (JAR).
`:jar`	J2EE Application Client (JAR).
`:lib`	Shared library (JAR).

This example shows two ways for adding components built by other projects:

package(:ear) << project('coolWebService').package(:war)
package(:ear).add project('commonLib') # By default, the JAR package

EAR packages include an application.xml file in the META-INF directory that describes the application and its component. This file is created for you during packaging, by referencing all the components added to the EAR. There are a couple of things you will typically want to change.

display-name—The application’s display name defaults to the project’s identifier. You can change that by setting the display_name attribute.

context-root—WAR components specify a context root, based on the package identifier, for example, “cool-web-1.0.war” will have the context root “cool-web”. To specify a different context root, add the WAR package with the context_root option.

JRuby Support

We now offer two versions of Buildr, one for Ruby and one for JRuby. They’re exactly the same, except the Ruby version will also install RJB (Ruby Java Bridge), the JRuby version obviously can do well without it.

Buildr provides a Nailgun server when running on JRuby. Using the integrated BuildrServer allows for faster task execution and avoid frequent JVM startup overhead.

Behaviour-Driven Development

Given that many languages are now supported by Buildr, the same is true for testing, the convention is to store BDD files under the src/spec/{lang} directory. The following table shows the framework’s name you can use to select them for your projects. Buildr follows each framework’s naming convention.

test.using	Test file name convention
`:jbehave`	`src/spec/java/*/Behaviour.java`
`:rspec`	`src/spec/ruby/*/_spec.rb`
`:easyb`	`src/spec/groovy/*/{Story,Behavior}.groovy`

Profiles

Different environments may require different configurations, some you will want to control with code, others you will want to specify in the profiles file.

The profiles file is a YAML file called profiles.yaml that you place in the same directory as the Buildfile. We selected YAML because it’s easier to read and edit than XML.

For example, to support three different database configurations, we could write:

# HSQL, don't bother storing to disk.
development:
  db: hsql
  jdbc: hsqldb:mem:devdb

# Make sure we're not messing with bigstrong.
test:
  db: oracle
  jdbc: oracle:thin:@localhost:1521:test

# The real deal.
production:
  db: oracle
  jdbc: oracle:thin:@bigstrong:1521:mighty

You can also use profiles to specify default filters for the resources task.

Settings and build YAML files

In addition to profiles, we also allow you to specify personal and build settings using two YAML files.

Personal settings are placed in the .buildr/settings.yaml file under your home directory. Settings stored there will be applied the same across all builds.

For example:

# The repositories hash is read automatically by buildr.
repositories:

  # customize user local maven2 repository location
  local: some/path/to/my_repo

  relase_to:
    url: http://intra.net/maven2
    username: john
    password: secret

# You can place settings of your own, and reference them 
# on buildfiles. 
im:
  server: jabber.company.com
  usr: notifier@company-jabber.com
  pwd: secret

Build settings are placed in the build.yaml file located in the same directory that the buildfile. Normally this file would be managed by the project revision control system, so settings here are shared between developers.

For example:

# This project requires the following ruby gems, buildr addons
gems: 
  # Suppose we want to notify developers when testcases fail.
  - buildr-twitter-notifier-addon >=1
  # we test with ruby mock objects
  - mocha
  - ci_reporter

# The artifact declarations will be automatically loaded by buildr, so that
# you can reference artifacts by name (a ruby-symbol) on your buildfile.
artifacts:
  spring: org.springframework:spring:jar:2.0
  log4j: log4j:log4j:jar:1.0
  j2ee: geronimo-spec:geronimo-spec:j2ee:jar:1.4-rc4

# Of course project settings can be defined here
jira: 
  uri: https://jira.corp.org

Using Gems for extensions and 3rd party libraries

RubyGems provides the gem command line tool that you can use to search, install, upgrade, package and distribute gems. It installs all gems into a local repository that is shared across your builds and all other Ruby applications you may have running. You can install a gem from a local file, or download and install it from any number of remote repositories.

If your build depends on other gems, you will want to specify these dependencies as part of your build and check that configuration into source control. That way you can have a specific environment that will guarantee repeatable builds, whether you’re building a particular version, moving between branches, or joining an existing project. Buildr will take care of installing all the necessary dependencies, which you can then manage with the gem command.

Use the build.yaml file to specify these dependencies (see Build Settings for more information), for example:

# This project requires the following gems
gems: 
  # Suppose we want to notify developers when testcases fail.
  - buildr-twitter-notifier-addon >=1
  # we test with ruby mock objects
  - mocha
  - ci_reporter

New API for accessing Java libraries

Java classes are accessed as static methods on the Java module, for example:

str = Java.java.lang.String.new('hai!')
str.toUpperCase
=> 'HAI!'
Java.java.lang.String.isInstance(str)
=> true
Java.com.sun.tools.javac.Main.compile(args)

The classpath attribute allows Buildr to add JARs and directories to the classpath, for example, we use it to load Ant and various Ant tasks, code generators, test frameworks, and so forth.

For example, Ant is loaded as follows:

Java.classpath << 'org.apache.ant:ant:jar:1.7.0'

Artifacts can only be downloaded after the Buildfile has loaded, giving it a chance to specify which remote repositories to use, so adding to classpath does not by itself load any libraries. You must call Java.load before accessing any Java classes to give Buildr a chance to load the libraries specified in the classpath.

Creating Extensions

A module defines instance methods that are then mixed into the project and become instance methods of the project. There are two general ways for extending projects. You can extend all projects by including the module in Project:

class Project
  include MyExtension
end

You can also extend a given project instance and only that instance by extending it with the module:

define 'foo' do
  extend MyExtension
end

Some extensions require tighter integration with the project, specifically for setting up tasks and properties, or for configuring tasks based on the project definition. You can do that by adding callbacks to the process.

Using Alternative Layouts

Buildr follows a common convention for project layouts: Java source files appear in src/main/java and compile to target/classes, resources are copied over from src/main/resources and so forth. Not all projects follow this convention, so it’s now possible to specify an alternative project layout.

A layout is an object that implements the expand method. The easiest way to define a custom layout is to create a new Layout object and specify mapping between names used by Buildr and actual paths within the project.

Other

Buildr 1.3 upgrades to Rake 0.8, RSpec 1.1, RJB 1.1 and OpenJPA 1.0.1. Buildr no longer includes or uses Facets.

JUnit tests now operate on all compiled test classes that extend junit.framework.TestCase or use the Test annotation; TestNG test cases are filtered by annotation. Test cases no longer have to use a specific file name.

Remote repositories now support HTTP Basic Authentication.

The prepare task has been removed, if you need to, simply add a prerequisite to the compile task.

Documentation

The What’s new? page (this one, actually), summarizes all the important new features and changes in each release.

The Recipes page (also available in the PDF) lists recipes for using Buildr, collected from the mailing list. Feel free to contribute tips, tricks and techniques.

The Troubleshooting page (also available in the PDF) collects troubleshooting ideas from the mailing list.

The Getting Started has been rewritten to cover all you need to know about downloading and installing Buildr on Linux, OS/X, Windows and with JRuby (1.1 or later).

A new Contributing page has more details on how to file bugs, policy for submitting patches, running Buildr test cases, and helping with the documentation.

A new page for Settings and Profiles.

The Extending Buildr page that deals with writing your own tasks, creating extensions and specifying alternative layouts.

The site also includes RSpec report which provides the official specification against which we test each release.