; Sat, 24 Sep 2016 05:13:54 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r15509 [43/43] - in /dev/buildr/1.5.0.RC2: ./ dist/ site/ site/css/ site/images/ site/rdoc/ site/rdoc/Buildr/ site/rdoc/Buildr/ArchiveTask/ site/rdoc/Buildr/ArtifactNamespace/ site/rdoc/Buildr/Assets/ site/rdoc/Buildr/Checks/ site/rdoc/Buil... Date: Sat, 24 Sep 2016 05:13:51 -0000 To: commits@buildr.apache.org From: toulmean@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20160924051354.2C70B3A0248@svn01-us-west.apache.org> archived-at: Sat, 24 Sep 2016 05:14:32 -0000 Added: dev/buildr/1.5.0.RC2/site/releasing.html ============================================================================== --- dev/buildr/1.5.0.RC2/site/releasing.html (added) +++ dev/buildr/1.5.0.RC2/site/releasing.html Sat Sep 24 05:13:50 2016 @@ -0,0 +1,158 @@ + + + + buildr — Releasing + + + + + + +

+ +

Start Here +
1. Welcome
2. Quick Start
3. Installing & Running
4. Community Wiki
+
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
+
Reference +
1. API
2. Rake
3. Antwrap
4. Troubleshooting
+
Get Involved +
1. Download
2. Mailing Lists
3. Twitter
4. Issues/Bugs
5. CI Jobs
6. Contributing
+
+
+ + + +
+

Releasing

What does a release do?
How to specify my own version number scheme?
How to specify my own tag name and commit message?

Now that we built and tested our awesome software, let’s tell the world and release it.

Each buildfile can specify the current version with a constant named VERSION_NUMBER or THIS_VERSION.

THIS_VERSION = "1.0.0-SNAPSHOT"
+
+define 'killer-app' do
+
+  project.version = THIS_VERSION
+
+  # ...
+end

What does a release do?

The default behavior of the Release task is the following:

Check that the version to be released and the next version are different
Check that the project is being tracked by Git or Subversion
Package, test and deploy the artifacts using THIS_VERSION value minus the -SNAPSHOT suffix (if any)
Tag the repository with the released version number
Update the value of THIS_VERSION in the buildfile with the next version number

Buildr will increment the last digit of the 3-digit versioni number if THIS_VERSION ends with -SNAPSHOT.
+So, at the end of a release, the buildfile now looks like this:

THIS_VERSION = "1.0.1-SNAPSHOT"
+
+define 'killer-app' do
+
+  project.version = THIS_VERSION
+
+  # ...
+end

And the Git repository now contains two new commits and a new tag.

~/w/killer-app[master]$git ol -4
+c1af3d5  (HEAD, origin/master, master) Changed version number to 1.0.1-SNAPSHOT
+dd35015  (tag: 1.0.0) Changed version number to 1.0.0
+76c96e7  Last fix before the release

How to specify my own version number scheme?

If THIS_VERSION does not contain -SNAPSHOT, Buildr delegates the resolution of the next version number to the user which has 2 differents ways to express her wishes: Release.next_version or the environment variable NEXT_VERSION.

Using Release.next_version

The Release class can receive the next version of the buildfile. This could be a string or a proc that would receive the current version and return the next version.

THIS_VERSION = "1.0.0-SNAPSHOT"
+
+# a string
+Release.next_version = "2.0.0-SNAPSHOT"
+
+# or a proc - equivalent result
+Release.next_version = lambda do |this_version| # 2.0.0-SNAPSHOT
+    new_version = THIS_VERSION.split /\./
+    new_version[0] = new_version[0].to_i + 1
+    new_version[1] = 0
+    new_version[2] = '0-SNAPSHOT'
+    new_version.join '.'
+end
+
+define 'killer-app' do
+
+  project.version = THIS_VERSION
+
+  # ...
+end

Using the environment variable NEXT_VERSION

If the environment variable NEXT_VERSION is set, Buildr will use this value to update THIS_VERSION at the end of the release.

For conveniency, this variable is case insensitive.

So, all 3 following commands will run a release with a custom new version:

$ buildr release next_version="1.0.0-rc1"
+$ env next_version="1.0.0-rc1" buildr release
+$ env NEXT_VERSION="1.0.0-rc1" buildr release

Those commands will generate the Buildfile below:

THIS_VERSION = "1.0.0-rc1"
+
+define 'killer-app' do
+
+  project.version = THIS_VERSION
+
+  # ...
+end

The environment variable NEXT_VERSION has precedence over Release.next_version.

Using an alternate version file

To avoid dealing with conflicts over the Buildfile, you can store the version inside version.rb next to it.

version.rb:
+

THIS_VERSION = "1.0.0-rc1"

Your Buildfile should import version.rb like so:
+

require File.join(File.dirname(__FILE__), 'version.rb')

How to specify my own tag name and commit message?

As explained earlier, Buildr will create two new commits and a new tag in the version control system. Similarly to Release.next_version, the commit message and the tag name can be customized with Release.message and Release.tag_name. Both could be strings or procs that would receive the released version THIS_VERSION without -SNAPSHOT.

+ +

+ + Added: dev/buildr/1.5.0.RC2/site/scripts/install-jruby.sh ============================================================================== --- dev/buildr/1.5.0.RC2/site/scripts/install-jruby.sh (added) +++ dev/buildr/1.5.0.RC2/site/scripts/install-jruby.sh Sat Sep 24 05:13:50 2016 @@ -0,0 +1,44 @@ +#!/bin/sh +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with this +# work for additional information regarding copyright ownership. The ASF +# licenses this file to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations under +# the License. +if [ -z `which jruby` ] ; then + version=1.6.2 + target=/opt/jruby + echo "Installing JRuby ${version} in ${target}" + sudo mkdir -p $(dirname ${target}) + wget http://jruby.org.s3.amazonaws.com/downloads/${version}/jruby-bin-${version}.tar.gz + tar -xz < jruby-bin-${version}.tar.gz + sudo mv jruby-${version} ${target} + rm jruby-bin-${version}.tar.gz + export PATH=$PATH:${target} + if [ -e ~/.bash_profile ] ; then + echo "export PATH=${target}/bin:\$PATH" >> ~/.bash_profile + elif [ -e ~/.profile ] ; then + echo "export PATH=${target}/bin:\$PATH" >> ~/.profile + else + echo "You need to add ${target}/bin to the PATH" + fi +fi + +if [ `which buildr` ] ; then + echo "Updating to the latest version of Buildr" + sudo jruby -S gem update buildr +else + echo "Installing the latest version of Buildr" + sudo jruby -S gem install buildr +fi +echo + +jruby -S buildr --version Propchange: dev/buildr/1.5.0.RC2/site/scripts/install-jruby.sh ------------------------------------------------------------------------------ svn:executable = * Added: dev/buildr/1.5.0.RC2/site/scripts/install-linux.sh ============================================================================== --- dev/buildr/1.5.0.RC2/site/scripts/install-linux.sh (added) +++ dev/buildr/1.5.0.RC2/site/scripts/install-linux.sh Sat Sep 24 05:13:50 2016 @@ -0,0 +1,73 @@ +#!/bin/sh +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with this +# work for additional information regarding copyright ownership. The ASF +# licenses this file to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations under +# the License. +if [ -z `which ruby` ] ; then + echo "You do not have Ruby 1.8.6 ..." + # yum comes first since some people have apt-get installed in addition to yum. + # urpmi is added in case of mandriva : apt-get or yum are working for mandriva too + if [ `which yum` ] ; then + echo "Installing Ruby using yum" + sudo yum install ruby rubygems ruby-devel gcc + elif [ `which apt-get` ] ; then + echo "Installing Ruby using apt-get" + # ruby package does not contain RDoc, IRB, etc; ruby-full is a meta-package. + # build-essentials not installed by default in Ubuntu, required for C extensions. + sudo apt-get install ruby-full ruby1.8-dev libopenssl-ruby build-essential + # RubyGems broken on Ubuntu, installing directly from source. + echo "Installing RubyGems from RubyForge" + wget http://production.cf.rubygems.org/rubygems/rubygems-1.3.7.tgz + tar xzf rubygems-1.3.7.tgz + cd rubygems-1.3.7 + sudo ruby setup.rb + cd .. + rm -rf rubygems-1.3.7 + # ruby is same as ruby1.8, we need gem that is same as gem1.8 + sudo ln -s /usr/bin/gem1.8 /usr/bin/gem + elif [ `which urpmi` ] ; then + echo "Installing Ruby using urpmi" + sudo urpmi ruby rubygems ruby-devel gcc + if [ $? -ne 0 ] ; then + echo "URPMI install error" + exit 1 + fi + else + echo "Can only install Ruby 1.8.6 using apt-get, yum or urpmi, and can't find any of them" + exit 1 + fi + echo +fi + +if [ -z $JAVA_HOME ] ; then + echo "Please set JAVA_HOME before proceeding" + exit 1 +fi + +if [ $(gem --version) \< '1.3.7' ] ; then + echo "Upgrading to latest version of RubyGems" + sudo gem update --system + sudo update_rubygems + echo +fi + +if [ `which buildr` ] ; then + echo "Updating to the latest version of Buildr" + sudo env JAVA_HOME=$JAVA_HOME gem update buildr +else + echo "Installing the latest version of Buildr" + sudo env JAVA_HOME=$JAVA_HOME gem install buildr +fi +echo + +buildr --version Propchange: dev/buildr/1.5.0.RC2/site/scripts/install-linux.sh ------------------------------------------------------------------------------ svn:executable = * Added: dev/buildr/1.5.0.RC2/site/scripts/install-osx.sh ============================================================================== --- dev/buildr/1.5.0.RC2/site/scripts/install-osx.sh (added) +++ dev/buildr/1.5.0.RC2/site/scripts/install-osx.sh Sat Sep 24 05:13:50 2016 @@ -0,0 +1,52 @@ +#!/bin/sh +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with this +# work for additional information regarding copyright ownership. The ASF +# licenses this file to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations under +# the License. +version=$(ruby --version) +if [ ${version:5:5} \< '1.8.6' ] ; then + echo "You do not have Ruby 1.8.6 or later, attempting to install a newer version." + if [ `which port` ] ; then + echo "Installing Ruby using MacPorts" + sudo port install ruby rb-rubygems + elif [ `which fink` ] ; then + echo "Installing Ruby using Fink" + sudo fink install ruby ruby18-dev rubygems-rb18 + else + echo "Can only upgrade to Ruby 1.8.6 using either MacPorts or Fink, and can't find either one" + exit 1 + fi + echo +fi + +if [ -z $JAVA_HOME ] ; then + echo "Setting JAVA_HOME" + export JAVA_HOME=/Library/Java/Home +fi + +if [ $(gem --version) \< '1.3.1' ] ; then + echo "Upgrading to latest version of RubyGems" + sudo gem update --system + echo +fi + +if [ `which buildr` ] ; then + echo "Updating to the latest version of Buildr" + sudo env JAVA_HOME=$JAVA_HOME gem update buildr +else + echo "Installing the latest version of Buildr" + sudo env JAVA_HOME=$JAVA_HOME gem install buildr +fi +echo + +buildr --version Propchange: dev/buildr/1.5.0.RC2/site/scripts/install-osx.sh ------------------------------------------------------------------------------ svn:executable = * Added: dev/buildr/1.5.0.RC2/site/settings_profiles.html ============================================================================== --- dev/buildr/1.5.0.RC2/site/settings_profiles.html (added) +++ dev/buildr/1.5.0.RC2/site/settings_profiles.html Sat Sep 24 05:13:50 2016 @@ -0,0 +1,303 @@ + + + + buildr — Settings/Profiles + + + + + + +

+ +

Start Here +
1. Welcome
2. Quick Start
3. Installing & Running
4. Community Wiki
+
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
+
Reference +
1. API
2. Rake
3. Antwrap
4. Troubleshooting
+
Get Involved +
1. Download
2. Mailing Lists
3. Twitter
4. Issues/Bugs
5. CI Jobs
6. Contributing
+
+
+ + + +
+

Settings/Profiles

Environment Variables
Personal Settings
Build Settings
Non constant settings
Environments
Profiles

Environment Variables

Buildr uses several environment variables that help you control how it works. Some environment variables you will only set once or change infrequently. You can set these in your profile, OS settings or any tool you use to launch Buildr (e.g. continuous integration).

For example:

$ export HTTP_PROXY=http://myproxy:8080

There are other environment variables you will want to set when running Buildr, for example, to do a full build without running the tests:

$ buildr test=no

For convenience, the environment variables TEST and DEBUG are case insensitive, you can use either test=no or TEST=no. Any other environment variable names are case sensitive.

You can also set environment variables from within your Buildfile. For example, if you discover that building your project requires gobs of JVM heap space, and you want all other team members to run with the same settings:

# This project builds a lot of code.
+ENV['JAVA_OPTS'] ||= '-Xms1g -Xmx1g'

Make sure to set any environment variables at the very top of the Buildfile, above any Ruby statement (even require).

Using ||= sets the environment variable, if not already set, so it’s still possible for other developers to override this environment variable without modifying the Buildfile.

Buildr supports the following environment variables:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Variable	Description
`BUILDR_ENV`	Environment name (development, production, test, etc). Another way to set this is using the `-e` command line option.
`DEBUG`	Set to `no/off` if you want Buildr to compile without debugging information (default when running the `release` task, see Compiling).
`HOME`	Your home directory.
`HTTP_PROXY`	URL for HTTP proxy server (see Specifying Repositories).
`HTTPS_PROXY`	URL for HTTPS proxy server (see Specifying Repositories).
`IGNORE_BUILDFILE`	Set to “true” or “yes” to ignore changes in Buildfile or its dependencies when running tests.
`JAVA_HOME`	Points to your JDK, required when using Java and Ant.
`JAVA_OPTS`	Command line options to pass to the JDK (e.g. `'-Xms1g'`).
`M2_REPO`	Location of the Maven2 local repository. Defaults to the `.m2` directory in your home directory (`ENV['HOME']`).
`NO_PROXY`	Comma separated list of hosts and domain that should not be proxied (see Specifying Repositories).
`TEST`	Set to `no/off` to tell Buildr to skip tests, or `all` to tell Buildr to run all tests and ignore failures (see Running Tests).
`USER`	Tasks that need your user name, for example to log to remote servers, will use this environment variable.

Buildr does not check any of the arguments in JAVA_OPTS. A common mistake is to pass an option like mx512mb, where it should be Xmx512mb. Make sure to double check JAVA_OPTS.

Some extensions may use additional environment variables, and of course, you can always add your own. This example uses two environment variables for specifying the username and password:

repositories.release_to[:username] = ENV['USERNAME']
+repositories.release_to[:password] = ENV['PASSWORD']

The same works for the repositories.snapshot_to hash.

Personal Settings

Some things clearly do not belong in the Buildfile. For example, the username and password you use to upload releases. If you’re working in a team or on an open source project, you’d want to keep these in a separate place.

You may want to use personal settings for picking up a different location for the local repository, or use a different set of preferred remote repositories, and so forth.

The prefered way to store personal settings is to create a .buildr/settings.yaml file under your home directory. Settings stored there will be applied the same across all builds.

Here’s an example settings.yaml:

# The repositories hash is read automatically by buildr.
+repositories:
+
+  # customize user local maven2 repository location
+  local: some/path/to/my_repo
+
+  # prefer the local or nearest mirrors
+  remote:
+   - https://intra.net/maven2
+   - http://example.com
+   
+  # specify the corporate mirror
+  mirrors:
+   - http://www.corporateserver001.com/repo
+
+  release_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

Later your buildfile or addons can reference user preferences using the hash returned by the Buildr.settings.user accessor.

task 'release-notification' do
+ usr, pwd, server = settings.user['im'].values_at('usr', 'pwd', 'server')
+ jabber = JabberAPI.new(server, usr, pwd)
+ jabber.msg("We are pleased to announce the last stable version #{VERSION}")
+end

Build Settings

Build settings are local to the project being built, and 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.

They help keep the buildfile and build.yaml file simple and readable, working to the advantages of each one. Example for build settings are gems, repositories and artifacts used by that build.

# 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
+twitter:
+  notify:
+    test_failure: unless-modified
+    compile_failure: never
+  developers:
+    - joe
+    - jane
+
+jira:
+  uri: https://jira.corp.org

When buildr is loaded, required ruby gems will be installed if needed, thus adding features like the imaginary twitter notifier addon.

Artifacts defined on build.yaml can be referenced on your buildfile by supplying the ruby symbol to the Buildr.artifact and Buildr.artifacts methods. The compile.with, test.with methods can also be given these names.

define 'my_project' do
+  compile.with artifacts(:log4j, :j2ee)
+  test.with :spring, :j2ee
+end

Build settings can be retreived using the Buildr.settings.build accessor.

 task 'create_patch' do
+   patch = Git.create_patch :interactive => true
+   if patch && agree("Would you like to request inclusion of #{patch}")
+     jira = Jira.new( Buildr.settings.build['jira']['uri'] )  # submit a patch
+     jira.create(:improvement, patch.summary, :attachment => patch.blob)
+   end
+ end

Non constant settings

Before loading the Buildfile, Buildr will attempt to load two other files: the buildr.rb file in the .buildr directory under your home directory, followed by the _buildr.rb (or .buildr.rb) file it finds in the build directory.

The loading order allows you to place global settings that affect all your builds in your buildr.rb, but also over-ride those with settings for a given project.

Here’s an example buildr.rb:

# Only I should know that
+repositories.release_to[:username] = 'assaf'
+repositories.release_to[:password] = 'supersecret'
+# Search here first, it's faster
+repositories.remote << 'http://inside-the-firewall'

Buildr 1.3 and earlier used the file buildr.rb directly in your home directory. Starting with version 1.4, Buildr loads buildr.rb from the .buildr directory under your home directory in preference. If you use Buildr 1.3 and earlier and don’t want to duplicate your settings, you can move you existing buildr.rb under the .buildr directory and create a new buildr.rb in your home directory containing:

# Backward compatibility:  Buildr 1.4+ uses $HOME/.buildr/buildr.rb
+load File.expand_path('buildr.rb', Buildr.application.home_dir)

Environments

One common use case is adapting the build to different environments. For example, to compile code with debugging information during development and testing, but strip it for production. Another example is using different databases for development, testing and production, or running services at different URLs.

So let’s start by talking about the build environment. Buildr has a global attributes that indicates which environment it’s running in, accessible from the environment method. You can set the current build environment in one of two ways. Using the -e/--environment command line option:

$ buildr -e test
+(in /home/john/project, test)

Or by setting the environment variable BUILDR_ENV:

$ export BUILDR_ENV=production
+$ buildr
+(in /home/john/project, production)

Unless you tell it otherwise, Buildr assumes you’re developing and sets the environment to development.

Here’s a simple example for handling different environments within the Buildfile:

project 'db-module' do
+  db = (Buildr.environment == 'production' ? 'oracle' : 'hsql')
+  resources.from(_("src/main/#{db}"))
+end

We recommend picking a convention for your different environments and following it across all your projects. For example:

+ + + + + + + + + + + + + + + + + +

Environment	Use when …
development	Developing on your machine.
test	Running in test environment, continuous integration.
production	Building for release/production.

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

Here’s a simple example for a buildfile that uses the profile information:

project 'db-module' do
+  # Copy SQL files specific for the database we're using,
+  # for example, everything under src/main/hsql.
+  resources.from(_("src/main/#{Buildr.settings.profile['db']}"))
+  # Set the JDBC URL in copied resource files (config.xml needs this).
+  resources.filter.using :jdbc=>Buildr.settings.profile['jdbc']
+end

The profile method returns the current profile, selected based on the current environment. You can get a list of all profiles by calling profiles.

When you run the above example in development, the current profile will return the hash { 'db'=>'hsql', 'jdbc'=>'hsqldb:mem:devdb' }.

We recommend following conventions and using the same environments in all your projects, but sometimes the profiles end up being the same, so here’s a trick you can use to keep your profiles DRY.

YAML allows you to use anchors (&), similar to ID attributes in XML, reference the anchored element (*) elsewhere, and merge one element into another (<<). For example:

# We'll reference this one as common.
+development: &common
+  db: hsql
+  jdbc: hsqldb:mem:devdb
+  resources:
+    copyright: Me (C) 2008
+# Merge the values from common, override JDBC URL.
+test:
+  <<: *common
+  jdbc: hsqldb:file:testdb

You can learn more about YAML here, and use this handy YAML quick reference.

+ +

+ + Added: dev/buildr/1.5.0.RC2/site/testing.html ============================================================================== --- dev/buildr/1.5.0.RC2/site/testing.html (added) +++ dev/buildr/1.5.0.RC2/site/testing.html Sat Sep 24 05:13:50 2016 @@ -0,0 +1,185 @@ + + + + buildr — Testing + + + + + + +

+ +

Start Here +
1. Welcome
2. Quick Start
3. Installing & Running
4. Community Wiki
+
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
+
Reference +
1. API
2. Rake
3. Antwrap
4. Troubleshooting
+
Get Involved +
1. Download
2. Mailing Lists
3. Twitter
4. Issues/Bugs
5. CI Jobs
6. Contributing
+
+
+ + + +
+

Testing

Writing Tests
Excluding Tests and Ignoring Failures
Running Tests
Integration Tests
Using Setup and Teardown
Testing Your Build
Behaviour-Driven Development

Untested code is broken code, so we take testing seriously. Off the bat you get to use either JUnit or TestNG for writing unit tests and integration tests. And you can also add your own framework, or even script tests using Ruby. But first, let’s start with the basics.

Writing Tests

Each project has a TestTask that you can access using the test method. TestTask reflects on the fact that each project has one task responsible for getting the tests to run and acting on the results. But in fact there are several tasks that do all the work, and a test task coordinates all of that.

The first two tasks to execute are test.compile and test.resources. They work similar to compile and resources, but uses a different set of directories. For example, Java tests compile from the src/test/java directory into the target/test/classes directory, while resources are copied from src/test/resources into target/test/resources.

The test.compile task will run the compile task first, then use the same dependencies to compile the test classes. That much you already assumed. It also adds the test framework (e.g. JUnit, TestNG) and JMock to the dependency list. Less work for you.

If you need more dependencies, the best way to add them is by calling test.with. This method adds dependencies to both compile.dependencies (for compiling) and test.dependencies (for running). You can manage these two dependency lists separately, but using test.with is good enough in more cases.

Once compiled, the test task runs all the tests.

Different languages use different test frameworks. You can find out more about available test frameworks in the Languages section.

Excluding Tests and Ignoring Failures

If you have a lot of tests that are failing or just hanging there collecting dusts, you can tell Buildr to ignore them. You can either tell Buildr to only run specific tests, for example:

test.include 'com.acme.tests.passing.*'

Or tell it to exclude specific tests, for example:

test.exclude '*FailingTest', '*FailingWorseTest'

Note that we’re always using the package qualified class name, and you can use star (*) to substitute for any set of characters.

When tests fail, Buildr fails the test task. This is usually a good thing, but you can also tell Buildr to ignore failures by resetting the :fail_on_failure option:

test.using :fail_on_failure=>false

Besides giving you a free pass to ignore failures, you can use it for other causes, for example, as a gentle reminder:

test do
+  warn "Did you forget something?" if test.tests.nil? || test.tests.empty?
+end

The tests collection holds the names of all classes with tests, if any. And there’s classes, which holds the names of all test classes. We’ll let you imagine creative use for these two.

Running Tests

It’s a good idea to run tests every time you change the source code, so we wired the build task to run the test task at the end of the build. And conveniently enough, the build task is the default task, so another way to build changes in your code and run your tests:

$ buildr

That only works with the local build task and any local task that depends on it, like package, install and upload. Each project also has its own build task that does not invoke the test task, so buildr build will run the tests cases, but buildr foo:build will not.

While it’s a good idea to always run your tests, it’s not always possible. There are two ways you can get build to not run the test task. You can set the environment variable test to no (but skip and off will also work). You can do that when running Buildr:

$ buildr test=no

Or set it once in your environment:

$ export TEST=no
+$ buildr

If you’re feeling really adventurous, you can also disable tests from your Buildfile or buildr.rb file, by setting options.test = false. We didn’t say it’s a good idea, we’re just giving you the option.

The test task is just smart enough to run all the tests it finds, but will accept include/exclude patterns. Often enough you’re only working on one broken test and you only want to run that one test. Better than changing your Buildfile, you can run the test task with a pattern. For example:

$ buildr test:KillerAppTest

Buildr will then run only tests that match the pattern KillerAppTest. It uses pattern matching, so test:Foo will run com.acme.FooTest and com.acme.FooBarTest. With Java, you can use this to pick a class name, or a package name to run all tests in that package, or any such combination. In fact, you can specify several patterns separated with commas. For example:

$ buildr test:FooTest,BarTest

Buildr forcefully runs all tests that match the pattern. If you want to re-run all tests even if your sources have not changed, you can execute:

$ buildr test:*

You can exclude tests by preceeding them with a minus sign (‘-’):

$ buildr test:-Bar

The above would run all tests except those with a name containing Bar. Exclusions can be combined with inclusions:

$ buildr test:Foo,-Bar

Buildr would then run tests with names containing Foo but not Bar.

As you probably noticed, Buildr will stop your build at the first test that fails. We think it’s a good idea, except when it’s not. If you’re using a continuous build system, you’ll want a report of all the failed tests without stopping at the first failure. To make that happen, set the environment variable test to “all”, or the Buildr options.test option to :all. For example:

$ buildr package test=all

We’re using package and not build above. When using a continuous build system, you want to make sure that packages are created, contain the right files, and also run the integration tests.

During development, if you want to re-run only tests that have failed during the last test execution, you can execute:

$ buildr test:failed

One last note on running tests. By default when you run tests, Buildr will automatically run all transitive test dependencies. This mean if you run “buildr test” inside project bar and bar depends on project foo, Buildr will first run tests in project foo if there have been any changes affecting foo that haven’t been taken into account yet. This behavior often surprises people, especially when they are trying to get things done and only care about tests in bar at that moment. For those times when you’d like to focus your testing on specific projects, Buildr has the only option that will only run tests for projects specified on the command line,

$ buildr test=only bar:test

Integration Tests

So far we talked about unit tests. Unit tests are run in isolation on the specific project they test, in an isolated environment, generally with minimal setup and teardown. You get a sense of that when we told you tests run after the build task, and include JMock in the dependency list.

In contrast, integration tests are run with a number of components, in an environment that resembles production, often with more complicates setup and teardown procedures. In this section we’ll talk about the differences between running unit and integration tests.

You write integration tests much the same way as you write unit tests, using test.compile and test.resources. However, you need to tell Buildr that your tests will execute during integration test. To do so, add the following line in your project definition:

test.using :integration

Typically you’ll use unit tests in projects that create internal modules, such as JARs, and integration tests in projects that create components, such as WARs and EARs. You only need to use the :integration option with the later.

To run integration tests on the current project:

$ buildr integration

You can also run specific tests cases, for example:

$ buildr integration:ClientTest

If you run the package task (or any task that depends on it, like install and upload), Buildr will first run the build task and all its unit tests, and then create the packages and run the integration tests. That gives you full coverage for your tests and ready to release packages. As with unit tests, you can set the environment variable test to “no” to skip integration tests, or “all” to ignore failures.

Using Setup and Teardown

Some tests need you to setup an environment before they run, and tear it down afterwards. The test frameworks (JUnit, TestNG) allow you to do that for each test. Buildr provides two additional mechanisms for dealing with more complicated setup and teardown procedures.

Integration tests run a setup task before the tests, and a teardown task afterwards. You can use this task to setup a Web server for testing your Web components, or a database server for testing persistence. You can access either task by calling integration.setup and integration.teardown. For example:

integration.setup { server.start ; server.deploy }
+integration.teardown { server.stop }

Depending on your build, you may want to enhance the setup/teardown tasks from within a project, for example, to populate the database with data used by that project’s test, or from outside the project definition, for example, to start and stop the Web server.

Likewise, each project has its own setup and teardown tasks that are run before and after tests for that specific project. You can access these tasks using test.setup and test.teardown.

Testing Your Build

So you got the build running and all the tests pass, binaries are shipping when you find out some glaring omissions. The license file is empty, the localized messages for Japanese are missing, the CSS files are not where you expect them to be. The fact is, some errors slip by unit and integration tests. So how do we make sure the same mistake doesn’t happen again?

Each project has a check task that runs just after packaging. You can use this task to verify that your build created the files you wanted it to create. And to make it extremely convenient, we introduced the notion of expectations.

You use the check method to express and expectation. Buildr will then run all these expectations against your project, and fail at the first expectation that doesn’t match. An expectation says three things. Let’s look at a few examples:

check package(:war), 'should exist' do
+  it.should exist
+end
+check package(:war), 'should contain a manifest' do
+  it.should contain('META-INF/MANIFEST.MF')
+end
+check package(:war).path('WEB-INF'), 'should contain files' do
+  it.should_not be_empty
+end
+check package(:war).path('WEB-INF/classes'), 'should contain classes' do
+  it.should contain('**/*.class')
+end
+check package(:war).entry('META-INF/MANIFEST'), 'should have license' do
+  it.should contain(/Copyright (C) 2007/)
+end
+check file('target/classes'), 'should contain class files' do
+  it.should contain('**/*.class')
+end
+check file('target/classes/killerapp/Code.class'), 'should exist' do
+  it.should exist
+end

The first argument is the subject, or the project if you skip the first argument. The second argument is the description, optional, but we recommend using it. The method it returns the subject.

You can also write the first expectation like this:

check do
+  package(:jar).should exist
+end

We recommend using the subject and description, they make your build easier to read and maintain, and produce better error messages.

There are two methods you can call on just about any object, called should and should_not. Each method takes an argument, a matcher, and executes that matcher. If the matcher returns false, should fails. You can figure out what should_not does in the same case.

Buildr provides the following matchers:

+ + + + + + + + + + + + + + + + + +

Method	Checks that …
`exist`	Given a file task checks that the file (or directory) exists.
`empty`	Given a file task checks that the file (or directory) is empty.
`contain`	Given a file task referencing a file, checks its contents, using string or regular expression. For a file task referencing a directory, checks that it contains the specified files; global patterns using `` and `*` are allowed.

All these matchers operate against a file task. If you run them against a ZipTask (including JAR, WAR, etc) or a TarTask, they can also check the contents of the archive. And as you can see in the examples above, you can also run them against a path in an archive, checking its contents as if it was a directory, or against an entry in an archive, checking the content of that file.

The package method returns a package task based on packaging type, identifier, group, version and classifier. The last four are inferred, but if you create a package with different specifications (for example, you specify a classifier) your checks must call package with the same qualifying arguments to return the very same package task.

Buildr expectations are based on RSpec. RSpec is the behavior-driven development framework we use to test Buildr itself. Check the RSpec documentation if want to see all the supported matchers, or want to write your own.

Behaviour-Driven Development

Buildr supports several Behaviour-Driven Development(BDD) frameworks for testing your projects. Buildr follows each framework naming conventions, searching for files under the src/spec/{lang} directory.

You can learn more about each BDD framework in the Languages section.

Next, let’s talk about customizing your environment and using profiles

+ +