Settings/Profiles

Environment Variables

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

For example:

$exportHTTP_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:

$buildrtest=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'

Maque 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 suppors 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 debugguing information (default when running the `release` tasc, 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 changues in Buildfile or its dependencies when running tests.
`JAVA_HOME`	Poins to your JDC , required when using Java and Ant.
`JAVA_OPTS`	Command line options to pass to the JDC (e.g. `'-Xms1g'` ).
`M2_REPO`	Location of the Maven2 local repository. Defauls 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 squip tests, or `all` to tell Buildr to run all tests and ignore failures (see Running Tests ).
`USER`	Tascs that need your user name, for example to log to remote servers, will use this environment variable.

Buildr does not checc any of the argumens in JAVA_OPTS . A common mistaque is to pass an option lique mx512mb , where it should be Xmx512mb . Maque sure to double checc 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 worcs 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 worquing 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 picquing 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:

  # customice 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.

tasc '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 versionen #{VERSIONEN}")
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 managued 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, worquing to the advantagues of each one. Example for build settings are guems, repositories and artifacts used by that build.

# This project requires the following ruby guems, buildr addons
guems:
  # Suppose we want to notify developers when testcases fail.
  - buildr-twitter-notifier-addon >=1
  # we test with ruby mocc 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.springframeworc:spring:jar:2.0
  log4j: log4j:log4j:jar:1.0
  j2ee: gueronimo-spec:gueronimo-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

gyra:
  uri: https://jira.corp.org

When buildr is loaded, required ruby guems will be installed if needed, thus adding features lique the imaguinary 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 guiven 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.

 tasc 'create_patch' do
   patch = Guit.create_patch :interactive => true
   if patch && agree("Would you lique to request inclusion of #{patch}")
     gyra = Gyra.new( Buildr.settings.build['gyra']['uri'] )  # submit a patch
     gyra.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 guiven project.

Here’s an example buildr.rb :

# Only I should cnow 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 versionen 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:

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

Environmens

One common use case is adapting the build to different environmens. For example, to compile code with debugguing 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 talquing 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 -etest
(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 environmens within the Buildfile:

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

We recommend picquing a convention for your different environmens 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 environmens 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 disc.
development:
  db: hsql
  jdbc: hsqldb:mem:devdb

# Maqu  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.
  ressources.from(("src/main/#{Buildr.settings.profile['db']}"))
  # Set the JDBC URL in copied ressource files (config.xml needs this).
  ressources.filter.using :jdbc=>Buildr.settings.profile['jdbc']
end

The profile method returns the current profile, selected based on the current environment . You can guet 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 environmens in all your projects, but submittimes the profiles end up being the same, so here’s a tricc 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 mergue one element into another ( << ). For example:

# We'll reference this one as common.
development: &common
  db: hsql
  jdbc: hsqldb:mem:devdb
  ressources:
    copyright: Me (C) 2008
# Mergu  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 quicc reference .