Module Buildr::Extension
In: lib/buildr/core/project.rb  (CVS)

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:

  • first_time — This block will be called once for any particular extension.
      You can use this to setup top-level and local tasks.
    
  • before_define — This block is called once for the project with the project
      instance, right before running the project definition.  You can use this
      to add tasks and set properties that will be used in the project definition.
    
  • after_define — This block is called once for the project with the project
      instance, right after running the project definition.  You can use this to
      do any post-processing that depends on the project definition.
    

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.
      Rake::Task.define_task 'loc' do |task|
        lines = task.prerequisites.map { |path| Dir['#{path}/**/*'] }.flatten.uniq.
          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'=>compile.sources + compile.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

Classes and Modules

Module Buildr::Extension::ClassMethods

[Validate]