assaf-buildr 1.3.3

data/doc/pages/projects.textile

@@ -0,0 +1,274 @@
+h1. Projects
+
+h2. Starting Out
+
+In Java, most projects are built the same way: compile source code, run test cases, package the code, release it.  Rinse, repeat.
+
+Feed it a project definition, and Buildr will set up all these tasks for you. The only thing you need to do is specify the parts that are specific to your project, like the classpath dependencies, whether you're packaging a JAR or a WAR, etc.
+
+The remainder of this guide deals with what it takes to build a project.  But first, let's pick up a sample project to work with.  We'll call it _killer-app_:
+
+{{{!ruby
+require 'buildr'
+ 
+VERSION_NUMBER = '1.0'
+ 
+AXIS2 = 'org.apache.axis2:axis2:jar:1.2'
+AXIOM  = group('axiom-api', 'axiom-impl', 'axiom-dom',
+  :under=>'org.apache.ws.commons.axiom', :version=>'1.2.4')
+AXIS_OF_WS = [AXIOM, AXIS2]
+OPENJPA = ['org.apache.openjpa:openjpa-all:jar:0.9.7',
+  'net.sourceforge.serp:serp:jar:1.12.0']
+ 
+repositories.remote << 'http://www.ibiblio.org/maven2/'
+ 
+desc 'Code. Build. ??? Profit!'
+define 'killer-app' do
+ 
+  project.version = VERSION_NUMBER
+  project.group = 'acme'
+  manifest['Copyright'] = 'Acme Inc (C) 2007'
+  compile.options.target = '1.5'
+
+  desc 'Abstract classes and interfaces'
+  define 'teh-api' do
+    package :jar
+  end
+
+  desc 'All those implementation details'
+  define 'teh-impl' do
+    compile.with AXIS_OF_WS, OPENJPA
+    compile { open_jpa_enhance }
+    package :jar
+  end
+
+  desc 'What our users see'
+  define 'la-web' do
+    test.using AXIS_OF_WS
+    package(:war).with :libs=>projects('teh-api', 'teh-impl')
+  end
+
+  javadoc projects
+  package :javadoc
+
+end
+}}}
+
+A project definition requires four pieces of information: the project name, group identifier, version number and base directory.  The project name ... do we need to explain why its necessary?  The group identifier and version number are used for packaging and deployment, we'll talk more about that in the "Packaging":packaging.html section.  The base directory lets you find files inside the project.
+
+Everything else depends on what that particular project is building.  And it all goes inside the project definition block, the piece of code that comes between @define <name> ..  do@ and @end@.
+
+
+h2. The Directory Structure
+
+Buildr follows a convention we picked from years of working with Apache projects.
+
+Java projects are laid out so the source files are in the @src/main/java@ directory and compile into the @target/classes@ directory.  Resource files go in the @src/main/resources@ directory, and copied over to @target/resources@. Likewise, tests come from @src/test/java@ and @src/test/resources@, and end life in @target/test/classes@ and @target/test/resources@, respectively.
+
+WAR packages pick up additional files from the aptly named @src/main/webapp@. And most stuff, including generated source files are parked under the @target@ directory.  Test cases and such may generate reports in the, you guessed it, @reports@ directory.
+
+Other languages will use different directories, but following the same general conventions.  For example, Scala code compiles from the @src/main/scala@ directory, RSpec tests are found in the @src/test/rspec@ directory, and Flash will compile to @target/flash@.  Throughout this document we will show examples using mostly Java, but you can imagine how this pattern applies to other languages.
+
+When projects grow big, you split them into smaller projects by nesting projects inside each other.  Each sub-project has a sub-directory under the parent project and follows the same internal directory structure.  You can, of course, change all of that to suite your needs, but if you follow these conventions, Buildr will figure all the paths for you.
+
+Going back to the example above, the directory structure will look something like this:
+
+p=. !images/project-structure.png!
+
+Notice the @buildfile@ at the top.  That's your project build script, the one Buildr runs.
+
+When you run the @buildr@ command, it picks up the @buildfile@ (which here we'll just call _Buildfile_) from the current directory, or if not there, from the closest parent directory.  So you can run @buildr@ from any directory inside your project, and it will always pick up the same Buildfile.  That also happens to be the base directory for the top project.  If you have any sub-projects, Buildr assumes they reflect sub-directories under their parent.
+
+And yes, you can have two top projects in the same Buildfile.  For example, you can use that to have one project that groups all the application modules (JARs, WARs, etc) and another project that groups all the distribution packages (binary, sources, javadocs).
+
+When you start with a new project you won't see the @target@ or @reports@ directories.  Buildr creates these when it needs to.  Just know that they're there.
+
+
+h2. Naming And Finding Projects
+
+Each project has a given name, the first argument you pass when calling @define@.  The project name is just a string, but we advise to stay clear of colon (@:@) and slashes (@/@ and @\@), which could conflict with other task and file names.  Also, avoid using common Buildr task names, don't pick @compile@ or @build@ for your project name.
+
+Since each project knows its parent project, child projects and siblings, you can reference them from within the project using just the given name.  In other cases, you'll need to use the full name.  The full name is just @parent:child@. So if you wanted to refer to _teh-impl_, you could do so with either @project('killer-app:teh-impl')@ or @project('killer-app').project('teh-impl')@.
+
+The @project@ method is convenient when you have a dependency from one project to another, e.g. using the other project in the classpath, or accessing one of its source files.  Call it with a project name and it will return that object or raise an error.  You can also call it with no arguments and it will return the project itself.  It's syntactic sugar that's useful when accessing project properties.
+
+The @projects@ method takes a list of names and returns a list of projects.  If you call it with no arguments on a project, it returns all its sub-projects.   If you call it with no argument in any other context, it returns all the projects defined so far.
+
+Let's illustrate this with a few examples:
+
+{{{!ruby
+puts projects.inspect
+=> [project("killer-app"), project("killer-app:teh-api") ... ]
+
+puts project('killer-app').projects.inspect
+=> [project("killer-app:teh-api"), project("killer-app:teh-impl") ... ]
+
+puts project('teh-api')
+=> No such project teh-api
+
+puts project('killer-app:teh-api').inspect
+=> project("killer-app:teh-api")
+
+puts project('killer-app').project('teh-api').inspect
+=> project("killer-app:teh-api")
+}}}
+
+To see a list of all projects defined in your Buildfile:
+
+{{{!sh
+$ buildr help:projects
+}}}
+
+
+h2. Running Project Tasks
+
+Most times, you run tasks like @build@ or @package@ that operate on the current project and recursively on its sub-projects.  The "current project" is the one that uses the current working directory.  So if you're in the @la-web/src@ directory looking at source files, _la-web_ is the current project.  For example: 
+
+{{{!sh
+# build killer-app and all its sub-projects
+$ buildr build
+
+# switch to and test only teh-impl
+$ cd teh-impl
+$ buildr test
+
+# switch to and package only la-web
+$ cd ../la-web
+$ buildr package
+}}}
+
+You can use the project's full name to invoke one of its tasks directly, and it doesn't matter which directory you're in.  For example:
+
+{{{!sh
+# build killer-app and all its sub-projects
+$ buildr killer-app:build
+
+# test only teh-impl
+$ buildr killer-app:teh-impl:test
+
+# package only la-web
+$ buildr killer-app:la-web:package
+}}}
+
+Buildr provides the following tasks that you can run on the current project, or on a specific project by prefixing them with the project's full name:
+
+{{{
+clean     # Clean files generated during a build
+compile   # Compile all projects
+build     # Build the project
+upload    # Upload packages created by the project
+install   # Install packages created by the project
+javadoc   # Create the Javadocs for this project
+package   # Create packages
+test      # Run all test cases
+uninstall # Remove previously installed packages
+}}}
+
+To see a list of all the tasks provided by Buildr:
+
+{{{!sh
+$ buildr help:tasks
+}}}
+
+h2. Setting Project Properties
+
+We mentioned the group identifier, version number and base directory.  These are project properties.  There are a few more properties we'll cover later on.
+
+There are two ways to set project properties.  You can pass them as a hash when you call @define@, or use accessors to set them on the project directly.  For example:
+
+{{{!ruby
+define 'silly', :version=>'1.0' do
+  project.group = 'acme'
+end
+
+puts project('silly').version
+=> 1.0
+puts project('silly').group
+=> acme
+}}}
+
+Project properties are inherited.  You can specify them once in the parent project, and they'll have the same value in all its sub-projects.  In the example, we only specify the version number once, for use in all sub-projects.
+
+
+h2. Resolving Paths
+
+You can run @buildr@ from any directory in your project.  To keep tasks consistent and happy, it switches over to the Buildfile directory and executes all the tasks from there, before returning back to your working directory. Your tasks can all rely on relative paths that start from the same directory as the Buildfile.
+
+But in practice, you'll want to use the @path_to@ method.  This method calculates a path relative to the project, a better way if you ever need to refactor your code, say turn a ad hoc task into a function you reuse.
+
+The @path_to@ method takes an array of strings and concatenates them into a path.  Absolute paths are returned as they are, relative paths are expanded relative to the project's base directory.  Slashes, if you don't already know, work very well on both Windows, Linux and OS X.  And as a shortcut, you can use @_@.
+
+For example:
+
+{{{!ruby
+# Relative to the current project
+path_to('src', 'main', 'java')
+
+# Exactly the same thing
+_('src/main/java')
+
+# Relative to the teh-impl project
+project('teh-impl')._('src/main/java')
+}}}
+
+
+h2. Defining The Project
+
+The project definition itself gives you a lot of pre-canned tasks to start with, but that's not enough to build a project.  You need to specify what gets built and how, which dependencies to use, the packages you want to create and so forth.  You can configure existing tasks, extend them to do additional work, and create new tasks.  All that magic happens inside the project definition block.
+
+Since the project definition executes each time you run Buildr, you don't want to perform any work directly inside the project definition block.  Rather, you want to use it to specify how different build task work when you invoke them. Here's an example to illustrate the point:
+
+{{{!ruby
+define 'silly' do
+  puts 'Running buildr'
+
+  build do
+    puts 'Building silly'
+  end
+end
+}}}
+
+Each time you run Buildr, it will execute the project definition and print out "Running buildr".  We also extend the @build@ task, and whenever we run it, it will print "Building silly".  Incidentally, @build@ is the default task, so if you run Buildr with no arguments, it will print both messages while executing the build.  If you run Buildr with a different task, say @clean@, it will only print the first message.
+
+The @define@ method gathers the project definition, but does not execute it immediately.  It executes the project definition the first time you reference that project, directly or indirectly, for example, by calling @project@ with that project's name, or calling @projects@ to return a list of all projects. Executing a project definition will also execute all its sub-projects' definitions.  And, of course, all project definitions are executed once the Buildfile loads, so Buildr can determine how to execute each of the build tasks.
+
+If this sounds a bit complex, don't worry.  In reality, it does the right thing.  A simple rule to remember is that each project definition is executed before you need it, lazy evaluation of sort.  The reason we do that?  So you can write projects that depend on each other without worrying about their order.
+
+In our example, the _la-web_ project depends on packages created by the _teh-api_ and _teh-impl_ projects, the later requiring _teh-api_ to compile. That example is simple enough that we ended up specifying the projects in order of dependency.  But you don't always want to do that.  For large projects, you may want to group sub-projects by logical units, or sort them alphabetically for easier editing.
+
+One project can reference another ahead of its definition.  If Buildr detects a cyclic dependency, it will let you know.
+
+In this example we define one project in terms of another, using the same dependencies, so we only need to specify them once:
+
+{{{!ruby
+define 'bar' do
+  compile.with project('foo').compile.dependencies
+end
+
+define 'foo' do
+  compile.with ..lots of stuff..
+end
+}}}
+
+One last thing to remember.  Actually three, but they all go hand in hand.
+
+*Self is project* Each of these project definition blocks executes in the context of that project, just as if it was a method defined on the project.  So when you call the @compile@ method, you're essentially calling that method on the current project: @compile@, @self.compile@ and @project.compile@ are all the same.
+
+*Blocks are closures* The project definition is also a closure, which can reference variables from enclosing scopes.  You can use that, for example, to define constants, variables and even functions in your Buildfile, and reference them from your project definition.  As you'll see later on, in the "Artifacts":#artifacts section, it will save you a lot of work.
+
+*Projects are namespaces* While executing the project definition, Buildr switches the namespace to the project name.  If you define the task "do-this" inside the _teh-impl_ project, the actual task name is "killer-app:teh-impl:do-this".  Likewise, the @compile@ task is actually "killer-app:teh-impl:compile".
+
+From outside the project you can reference a task by its full name, either @task('foo:do')@ or @project('foo').task('do')@.  If you need to reference a task defined outside the project from within the project, prefix it with "rake:", for example, @task('rake:globally-defined')@.
+
+
+h2. Writing Your Own Tasks
+
+Of all the features Buildr provide, it doesn't have a task for making coffee. Yet.  If you need to write your own tasks, you get all the power of Rake: you can use regular tasks, file tasks, task rules and even write your own custom task classes.  Check out the "Rake documentation":http://docs.rubyrake.org/ for more information.
+
+We mentioned projects as namespaces before.  When you call @task@ on a project, it finds or defines the task using the project namespace.  So given a project object, @task('do-this')@ will return it's "do-this" task.  If you lookup the source code for the @compile@ method, you'll find that it's little more than a shortcut for @task('compile')@.
+
+Another shortcut is the @file@ method.  When you call @file@ on a project, Buildr uses the @path_to@ method to expand relative paths using the project's base directory.  If you call @file('src')@ on _teh-impl_, it will return you a file task that points at the @teh-impl/src@ directory.
+
+In the current implementation projects are also created as tasks, although you don't invoke these tasks directly.  That's the reason for not using a project name that conflicts with an existing task name.  If you do that, you'll find quick enough, as the task will execute each time you run Buildr.
+
+So now that you know everything about projects and tasks, let's go and "build some code":building.html.

data/doc/pages/recipes.textile

@@ -0,0 +1,103 @@
+h1. Recipes
+
+Commond recipes for Buildr, collected from the mailing list.
+
+
+h2.  Creating a classpath
+
+For Java, the classpath argument is simply a list of paths joined with an OS-specific path separator:
+
+{{{!ruby
+cp = paths.join(File::PATH_SEPARATOR)
+}}}
+
+This assumes @paths@ points to files and/or directories, but what if you have a list of artifact specifications?  You can turn those into file names in two steps.  First, use @artifacts@ to return a list of file tasks that point to the local repository:
+
+{{{!ruby
+tasks = Buildr.artifacts(specs)
+}}}
+
+Next, map that list of tasks into list of file names (essentially calling @name@ on each task):
+
+{{{!ruby
+paths = tasks.map(&:name)
+}}}
+
+This works as long as the artifacts are already in your local repository, otherwise they can't be found, but you can ask Buildr to download them by calling @invoke@ on each of these tasks:
+
+{{{!ruby
+tasks = Buildr.artifacts(specs).each(&:invoke)
+}}}
+
+So let's roll this all into a single line:
+
+{{{!ruby
+cp = Buildr.artifacts(specs).each(&:invoke).map(&:name).join(File::PATH_SEPARATOR)
+}}}
+
+
+h2.  Keeping your Profiles.yaml file DRY
+
+YAML allows you to use anchors (@&@), similar to ID attributes in XML, and reference them later on (@*@).  For example, if you have two profiles that are identical, you can tell YAML that one is an alias for the other:
+
+{{{!yaml
+development: &common
+  db: oracle
+  port: 8080
+test: *common
+production: *common
+}}}
+
+If you have two elements that are almost identical, you can merge the values of one element into another (@<<@), for example:
+
+{{{!yaml
+development: &common
+  db: hsql
+  jdbc: hsqldb:mem:devdb
+test:
+  <<: *common
+  jdbc: hsqldb:file:testdb
+}}}
+
+
+h2.  Speeding JRuby
+
+When using JRuby you will notice that Buildr takes a few seconds to start up. To speed it up, we recommend switching to Java 1.6 and running the JVM in client mode:
+
+{{{!
+$ export JAVA_OPTS=-client
+}}}
+
+
+h2.  Continuous Integration with Atlassian Bamboo
+
+This recipe outlines how to configure a new Bamboo project to use Buildr.  The following steps assume that you have logged-on to Bamboo as an Administrator.
+
+*1. Configure a Builder*
+
+* Select the Administration tab from the Bamboo toolbar.
+* Select the Builders area (first option) from the Administration menu.
+* Using the Add Builder dialog, configure a custom builder for Buildr with the following options:
+** Label: @buildr@
+** Type:  @Custom Command@
+** Path:  @/path/to/buildr@ (typically "/usr/bin/buildr")
+
+*2. Create a Plan*
+
+* Select the Create Plan tab from the Bamboo toolbar to enter the Create Plan wizard.
+* In "1. Plan Details", define your build plan including project name, project key, build plan name and build plan key.
+* In "2. Source Repository", specify your source code repository settings (CVS or SVN).
+* In "3. Builder Configuration", specify the "buildr" builder that you defined above, along with the following:
+** Argument: @"test=all"@ (ensures that all tests are run through even if failures are encountered)
+** Test Results Directory: @"**/reports/junit/*.xml"@ (or your path to test results, if different).
+* The remaining wizard sections may be either skipped or configured with your preferred settings.
+
+*3. Trigger a Build*
+
+A build should occur automatically at the point of project creation. It can also be manually triggered at any time
+
+* Navigate to the project summary page (located at: @http://YOUR_BAMBOO_URL/browse/PROJECTKEY-YOURPLAN@).
+* Click on the small arrow to the left of the label "Build Actions"
+* Select "Checkout and Build" from the pop-up menu to force a build.
+
+The project page will contain full status information for previous builds and the results tabs will integrate the results from your JUnit tests.

data/doc/pages/settings_profiles.textile

@@ -0,0 +1,274 @@
+h1. Settings/Profiles
+
+
+h2.  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:
+
+{{{!sh
+$ 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:
+
+{{{!sh
+$ buildr test=no
+}}}
+
+For convenience, when you set environment variables on the command line, the variable name is case insensitive, you can use either @test=no@ or @TEST=no@. Any other way (@export@, @ENV@, etc) the 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:
+
+{{{!ruby
+# 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@).
+
+p(tip).  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":building.html#compiling). |
+| @HOME@        | Your home directory. |
+| @HTTP_PROXY@  | URL for HTTP proxy server (see "Specifying Repositories":artifacts.html#specifying_repositories). |
+| @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":artifacts.html#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":testing.html#running_tests). |
+| @USER@        | Tasks that need your user name, for example to log to remote servers, will use this environment variable. |
+
+p(note). 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:
+
+{{{!ruby
+repositories.upload_to[:username] = ENV['USERNAME']
+repositories.upload_to[:password] = ENV['PASSWORD']
+}}}
+
+
+h2. 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@:
+
+{{{!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
+
+  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
+}}}
+
+Later your buildfile or addons can reference user preferences using the  hash returned by the @Buildr.settings.user@ accessor.
+
+{{{!ruby
+task 'relase-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
+}}}
+
+
+h2. 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.
+
+{{{!yaml
+# 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.
+
+{{{!ruby
+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.
+
+{{{!ruby
+ 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
+}}}
+
+h2. Non constant settings
+
+Before loading the Buildfile, Buildr will attempt to load two other files: the @buildr.rb@ file it finds in your home directory, followed by the @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 home directory's @buildr.rb@, but also over-ride those with settings for a given project.
+
+Here's an example @buildr.rb@:
+
+{{{!ruby
+# Only I should know that
+repositories.upload_to[:username] = 'assaf'
+repositories.upload_to[:password] = 'supersecret'
+# Search here first, it's faster
+repositories.remote << 'http://inside-the-firewall'
+}}} 
+
+
+h2. 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:
+
+{{{!sh
+$ 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:
+
+{{{!ruby
+project 'db-module' do
+  db = (environment == 'production' ? 'oracle' : 'hsql')
+  resources.from(_(:source, :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. |
+
+
+h2.  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:
+
+{{{!yaml
+# 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:
+
+{{{!ruby
+project 'db-module' do
+  # Copy SQL files specific for the database we're using,
+  # for example, everything under src/main/hsql.
+  resources.from(_(:source, :main, profile['db']))
+  # Set the JDBC URL in copied resource files (config.xml needs this).
+  resources.filter :jdbc=>profile['jdbc']
+end
+}}}
+
+The @profile@ method returns the current profile, selected based on the current "environment":#environments.  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:
+
+{{{!yaml
+# 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":http://www.yaml.org, and use this handy "YAML quick reference":http://www.yaml.org/refcard.html.