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

Settings/Profiles

1. Environment Variables
2. Personal Settings
3. Build Settings
4. Non constant settings
5. Environments
6. 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:

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:

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.