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. 

Extending Buildr

1. Organizing Tasks
2. Creating Extensions
3. Using Alternative Layouts

Organizing Tasks

A couple of things we learned while working on Buildr. Being able to write your own Rake tasks is a very powerful feature. But if you find yourself doing the same thing over and over, you might also want to consider functions. They give you a lot more power and easy abstractions.

For example, we use OpenJPA in several projects. It’s a very short task, but each time I have to go back to the OpenJPA documentation to figure out how to set the Ant MappingTool task, tell Ant how to define it. After the second time, you’re recognizing a pattern and it’s just easier to write a function that does all that for you.

Compare this:

file('derby.sql') do
  REQUIRES = [
    'org.apache.openjpa:openjpa-all:jar:0.9.7-incubating',
    'commons-collections:commons-collections:jar:3.1',
    . . .
    'net.sourceforge.serp:serp:jar:1.11.0' ]
  ant('openjpa') do |ant|
    ant.taskdef :name=>'mapping',
      :classname=>'org.apache.openjpa.jdbc.ant.MappingToolTask',
      :classpath=>REQUIRES.join(File::PATH_SEPARATOR)
    ant.mapping :schemaAction=>'build', :sqlFile=>task.name,
      :ignoreErrors=>true do
        ant.config :propertiesFile=>_('src/main/sql/derby.xml')
        ant.classpath :path=>projects('store', 'utils' ).
          flatten.map(&:to_s).join(File::PATH_SEPARATOR)
    end
  end
end

To this:

file('derby.sql') do
  mapping_tool :action=>'build', :sql=>task.name,
    :properties=>_('src/main/sql/derby.xml'),
    :classpath=>projects('store', 'utils')
end

I prefer the second. It’s easier to look at the Buildfile and understand what it does. It’s easier to maintain when you only have to look at the important information.

But just using functions is not always enough. You end up with a Buildfile containing a lot of code that clearly doesn’t belong there. For starters, I recommend putting it in the tasks directory. Write it into a file with a .rake extension and place that in the tasks directory next to the Buildfile. Buildr will automatically pick it up and load it for you.

If you want to share these pre-canned definitions between projects, you have a few more options. You can share the tasks directory using SVN externals, Git modules, or whichever cross-repository feature your source control system supports. Another mechanism with better version control is to package all these tasks, functions and modules into a Gem and require it from your Buildfile. You can run your own internal Gem server for that.

To summarize, there are several common ways to distribute extensions:

• Put them in the same place (e.g. ~/.buildr) and require them from your
  buildfile
• Put them directly in the project, typically under the tasks directory.
• Put them in a shared code repository, and link to them from your project’s tasks directory
• As Ruby gems and specify which gems are used in the settings file

You can also get creative and devise your own way to distribute extensions.
Sake is a good example of such initiative that lets you deploy Rake tasks on a system-wide basis.

Creating Extensions

The basic mechanism for extending projects in Buildr are Ruby modules. In fact, base features like compiling and testing are all developed in the form of modules, and then added to the core Project class.

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

class Project
  include MyExtension
end

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

define 'foo' do
  extend MyExtension
end

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

The easiest way to add callbacks is by incorporating the Extension module in your own extension, and using the various class methods to define callback behavior.

This example illustrates how to write a simple extension:

module LinesOfCode

  include Extension

  first_time do
    # Define task not specific to any projet.
    desc 'Count lines of code in current project'
    Project.local_task('loc')
  end

  before_define do |project|
    # Define the loc task for this particular project.
    project.recursive_task 'loc' do |task|
      lines = task.prerequisites.map { |path|
        Dir["#{path}/**/*"]
      }.uniq.select { |file|
        File.file?(file)
      }.inject(0) { |total, file|
        total + File.readlines(file).count
      }
      puts "Project #{project.name} has #{lines} lines of code"
      end
  end

  after_define do |project|
    # Now that we know all the source directories, add them.
    task('loc' => project.compile.sources + project.test.sources)
  end

  # To use this method in your project:
  # loc path_1, path_2
  def loc(*paths)
    task('loc' => paths)
  end

end

class Buildr::Project
    include LinesOfCode
end

You may find interesting that this Extension API is used pervasively inside Buildr itself. Many of the standard tasks such as compile, test, package are extensions to a very small core.

Starting with Buildr 1.4, it’s possible to define ordering between before_define and after_define code blocks in a way similar to Rake’s dependencies. For example, if you wanted to override project.test.compile.from in after_define, you could do so by in

after_define(:functional_tests) do |project|
  # Change project.test.compile.from if it's not already pointing
  # to a location with Java sources
  if Dir["#{project.test.compile.from}/**/*.java"].size == 0 &&
     Dir["#{project._(:src, 'test-functional', :java)}/**/*.java"].size > 0
    project.test.compile.from project._(:src, 'test-functional', :java)
  end
end

# make sure project.test.compile.from is updated before the
# compile extension picks up its value
after_define(:compile => :functional_test)

Core extensions provide the following named callbacks: compile, test, build, package and check.

Using Alternative Layouts

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

The default layout is available in Layout.default, and all projects inherit it. You can set Layout.default to your own layout, or define a project with a given layout (recommended) by setting the :layout property. Projects inherit the layout from their parent projects. For example:

define 'foo', :layout=>my_layout do
  ...
end

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

my_layout = Layout.new
my_layout[:source, :main, :java] = 'java'
my_layout[:source, :main, :resources] = 'resources'

Partial expansion also works, so you can specify the above layout using:

my_layout = Layout.new
my_layout[:source, :main] = ''

If you need anything more complex, you can always subclass Layout and add special handling in the expand method, you’ll find one such example in the API documentation.

The built-in tasks expand lists of symbols into relative paths, using the following convention:

All tasks are encouraged to use the same convention, and whenever possible, we recommend using the project’s path_to method to expand a list of symbols into a path, or use the appropriate path when available. For example:

define 'bad' do
  # This may not be the real target.
  puts 'Compiling to ' + path_to('target/classes')
  # This will break with different layouts.
  package(:jar).include 'src/main/etc/*'
end

define 'good' do
  # This is always the compiler's target.
  puts 'Compiling to ' + compile.target.to_s
  # This will work with different layouts.
  package(:jar).include path_to(:source, :main, :etc, '*')
end