buildr 1.2.10 → 1.3.0

data/lib/buildr/core/progressbar.rb

@@ -0,0 +1,156 @@
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with this
+# work for additional information regarding copyright ownership.  The ASF
+# licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations under
+# the License.
+
+
+class ProgressBar
+
+  class << self
+
+    def start(args, &block)
+      new(args).start &block
+    end
+
+    def width
+      @width ||= $terminal.output_cols || 80
+    end
+
+  end
+
+  def initialize(args = {})
+    @title = args[:title] || ''
+    @total = args[:total] || 0
+    @mark = args[:mark] || '.'
+    @format = args[:format] || default_format
+    @output = args[:output] || $stderr unless args[:hidden] || !$stdout.isatty
+    clear
+  end
+
+  def start
+    @start = @last_time = Time.now
+    @count = 0
+    @finished = false
+    render
+    if block_given?
+      result = yield(self) if block_given?
+      finish
+      result
+    else
+      self
+    end
+  end
+
+  def inc(count)
+    set @count + count
+  end
+
+  def <<(bytes)
+    inc bytes.size
+  end
+
+  def set(count)
+    @count = [count, 0].max
+    @count = [count, @total].min unless @total == 0
+    render if changed?
+  end
+
+  def title
+    @title.size > ProgressBar.width / 5 ? (@title[0, ProgressBar.width / 5 - 2] + '..') : @title 
+  end
+
+  def count
+    human(@count)
+  end
+
+  def total
+    human(@total)
+  end
+
+  def percentage
+    '%3d%%' % (@total == 0 ? 100 : (@count * 100 / @total))
+  end
+
+  def time
+    @finished ? elapsed : eta
+  end
+
+  def eta
+    return 'ETA:  --:--:--' if @count == 0
+    elapsed = Time.now - @start
+    eta = elapsed * @total / @count - elapsed
+    'ETA:  %s' % duration(eta.ceil)
+  end
+
+  def elapsed
+    'Time: %s' % duration(Time.now - @start) 
+  end
+
+  def rate
+    '%s/s' % human(@count / (Time.now - @start))
+  end
+
+  def progress(width)
+    width -= 2
+    marks = @total == 0 ? width : (@count * width / @total)
+    "|%-#{width}s|" % (@mark * marks)
+  end
+
+  def human(bytes)
+    magnitude = (0..3).find { |i| bytes < (1024 << i * 10) } || 3
+    return '%dB' % bytes if magnitude == 0
+    return '%.1f%s' % [ bytes.to_f / (1 << magnitude * 10), [nil, 'KB', 'MB', 'GB'][magnitude] ]
+  end
+
+  def duration(seconds)
+    '%02d:%02d:%02d' % [seconds / 3600, (seconds / 60) % 60, seconds % 60]
+  end
+
+  def finish
+    unless @finished
+      @finished = true
+      render
+    end
+  end
+
+protected
+
+  def clear
+    return unless @output
+    @output.print "\r", " " * (ProgressBar.width - 1), "\r"
+    @output.flush
+  end
+    
+  def render
+    return unless @output
+    format, *args = @format
+    line = format % args.map { |arg| send(arg) }
+    @output.print line.sub('|--|') { progress(ProgressBar.width - line.size + 3) }
+    @output.print @finished ? "\n" : "\r"
+    @output.flush
+    @previous = @count
+    @last_time = Time.now
+  end
+
+  def changed?
+    return false unless @output
+    return human(@count) != human(@previous) if @total == 0
+    return true if (@count - @previous) >= @total / 100
+    return Time.now - @last_time > 1
+  end
+
+  def default_format
+    @total == 0 ? ['%s %8s %s', :title, :count, :elapsed] : ['%s: %s |--| %8s/%s %s', :title, :percentage, :count, :total, :time]
+  end
+
+end

data/lib/{core → buildr/core}/project.rb

@@ -1,46 +1,107 @@
-require "core/rake_ext"
-require "core/common"
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with this
+# work for additional information regarding copyright ownership.  The ASF
+# licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations under
+# the License.
+
+
+require 'buildr/core/util'
+
 
 module Buildr
 
-  # An inherited attribute gets its value an accessor with the same name.
-  # But if the value is not set, it will obtain a value from the parent,
-  # so setting the value in the parent make it accessible to all the children
-  # that did not override it.
-  module InheritedAttributes
+  # Symbolic mapping for directory layout.  Used for both the default and custom layouts.
+  #
+  # For example, the default layout maps [:source, :main, :java] to 'src/main/java', and
+  # [:target, :main, :classes] to 'target/classes'.  You can use this to change the layout
+  # of your projects.
+  #
+  # To map [:source, :main] into the 'sources' directory:
+  #   my_layout = Layout.new
+  #   my_layout[:source, :main] = 'sources'
+  #
+  #   define 'foo', :layout=>my_layout do
+  #     ...
+  #   end
+  #
+  # To map [:source, :main, :java] to 'java/main':
+  #   class MainLast < Layout
+  #     def expand(*args)
+  #       if args[0..1] == [:source, :main]
+  #         super args[2], :main, *args[3,]
+  #       else
+  #         super
+  #       end
+  #     end
+  #   end
+  #
+  #   define 'foo', :layout=>MainLast do
+  #     ...
+  #   end
+  class Layout
 
     class << self
-    private
-      def included(mod)
-        mod.extend(self)
-      end
+
+      # Default layout used by new projects.
+      attr_accessor :default
+
     end
 
-    # :call-seq:
-    #    inherited_attr(symbol, default?)
-    #    inherited_attr(symbol) { |obj| ... }
-    #
-    # Defines an inherited attribute. The first form can provide a default value
-    # for the top-level object, used if the attribute was not set. The second form
-    # provides a default value by calling the block.
-    #
-    # For example:
-    #   inherited_attr :version
-    #   inherited_attr :src_dir, "src"
-    #   inherited_attr(:created_on) { Time.now }
-    def inherited_attr(symbol, default = nil, &block)
-      block ||= proc { default }
-      attr_accessor symbol
-      define_method "#{symbol}_with_inheritence" do
-        value = send("#{symbol}_without_inheritence")
-        if value.nil?
-          value = parent ? parent.send(symbol) : self.instance_eval(&block)
-          send "#{symbol}=", value
-        end
-        value
+    def initialize #:nodoc:
+      @mapping = {}
+    end
+
+    # Expands list of symbols and path names into a full path, for example:
+    #   puts default.expand(:source, :main, :java)
+    #   => "src/main/java"
+    def expand(*args)
+      return '' if args.empty?
+      @mapping[args] ||= File.join(*[expand(*args[0..-2]), args.last.to_s].reject(&:empty?)) if args.size > 1
+      return @mapping[args] || args.first.to_s
+    end
+
+    # Resolves a list of symbols into a path.
+    def [](*args)
+      @mapping[args.map(&:to_sym)]
+    end
+
+    # Specifies the path resolved from a list of symbols.
+    def []=(*args)
+      @mapping[args[0...-1].map(&:to_sym)] = args.last
+    end
+
+    def initialize_copy(copy)
+      copy.instance_variable_set :@mapping, @mapping.clone
+    end
+
+    # Default layout has the following properties:
+    # * :source maps to the 'src' directory.
+    # * Anything under :source maps verbatim (e.g. :source, :main becomes 'src/main')
+    # * :target maps to the 'target' directory.
+    # * :target, :main maps to the 'target' directory as well.
+    # * Anything under :target, :main maps verbatim (e.g. :target, :main, :classes becomes 'target/classes')
+    # * Anything else under :target also maps verbatim (e.g. :target, :test becomes 'target/test')
+    class Default < Layout
+
+      def initialize
+        super
+        self[:source] = 'src'
+        self[:target, :main] = 'target'
       end
-      alias_method_chain symbol, :inheritence
+
     end
+
+    self.default = Default.new
+
   end
 
 
@@ -89,34 +150,39 @@ module Buildr
   #   |  |__resources      <-- Resources to copy (tests)
   #   |__target            <-- Packages created here
   #   |  |__classes        <-- Generated when compiling
-  #   |  |__test-classes   <-- Generated when compiling tests
+  #   |  |__resources      <-- Copied (and filtered) from resources
+  #   |  |__test/classes   <-- Generated when compiling tests
+  #   |  |__test/resources <-- Copied (and filtered) from resources
+  #   |__reports           <-- Test, coverage and other reports
+  #
+  # You can change the project layout by passing a new Layout to the project definition.
   #
   # You can only define a project once using #define. Afterwards, you can obtain the project
   # definition using #project. The order in which you define projects is not important,
   # project definitions are evaluated when you ask for them. Circular dependencies will not
   # work. Rake tasks are only created after the project is evaluated, so if you need to access
-  # a task (e.g. compile) use <code>project("foo").compile</code> instead of <code>task("foo:compile")</code>.
+  # a task (e.g. compile) use <code>project('foo').compile</code> instead of <code>task('foo:compile')</code>.
   #
   # For example:
-  #   define "myapp", :version=>"1.1" do
+  #   define 'myapp', :version=>'1.1' do
   #
-  #     define "wepapp" do
-  #       compile.with project("myapp:beans")
+  #     define 'wepapp' do
+  #       compile.with project('myapp:beans')
   #       package :war
   #     end
   #
-  #     define "beans" do
+  #     define 'beans' do
   #       compile.with DEPENDS
   #       package :jar
   #     end
   #   end
   #
   #   puts projects.map(&:name)
-  #   => [ "myapp", "myapp:beans", "myapp:webapp" ]
-  #   puts project("myapp:webapp").parent.name
-  #   => "myapp"
-  #   puts project("myapp:webapp").compile.classpath.map(&:to_spec)
-  #   => "myapp:myapp-beans:jar:1.1"
+  #   => [ 'myapp', 'myapp:beans', 'myapp:webapp' ]
+  #   puts project('myapp:webapp').parent.name
+  #   => 'myapp'
+  #   puts project('myapp:webapp').compile.classpath.map(&:to_spec)
+  #   => 'myapp:myapp-beans:jar:1.1'
   class Project < Rake::Task
 
     class << self
@@ -129,16 +195,28 @@ module Buildr
         # Make sure a sub-project is only defined within the parent project,
         # to prevent silly mistakes that lead to inconsistencies (e.g.
         # namespaces will be all out of whack).
-        Rake.application.current_scope == name.split(":")[0...-1] or
+        Buildr.application.current_scope == name.split(':')[0...-1] or
           raise "You can only define a sub project (#{name}) within the definition of its parent project"
 
         @projects ||= {}
         raise "You cannot define the same project (#{name}) more than once" if @projects[name]
+        # Projects with names like: compile, test, build are invalid, so we have
+        # to make sure the project has not the name of an already defined task
+        raise "Invalid project name: #{name.inspect} is already used for a task" if Buildr.application.lookup(name)
+
         Project.define_task(name).tap do |project|
           # Define the project to prevent duplicate definition.
           @projects[name] = project
           # Set the project properties first, actions may use them.
           properties.each { |name, value| project.send "#{name}=", value } if properties
+          # Instantiate callbacks for this project, and setup to call before/after define.
+          # Don't cache list of callbacks, since project may add new callbacks.
+          project.enhance do |project|
+            project.send :call_callbacks, :before_define
+            project.enhance do |project|
+              project.send :call_callbacks, :after_define
+            end
+          end
           project.enhance do |project|
             @on_define.each { |callback| callback[project] }
           end if @on_define
@@ -146,7 +224,7 @@ module Buildr
           project.enhance { project.instance_eval &block } if block
 
           # Top-level project? Invoke the project definition. Sub-project? We don't invoke
-          # the project definiton yet (allow project() calls to establish order of evaluation),
+          # the project definiton yet (allow project calls to establish order of evaluation),
           # but must do so before the parent project's definition is done. 
           project.parent.enhance { project.invoke } if project.parent
         end
@@ -159,18 +237,18 @@ module Buildr
       def project(*args) #:nodoc:
         options = args.pop if Hash === args.last
         rake_check_options options, :scope if options
-        raise ArgumentError, "Only one project name at a time" unless args.size == 1
+        raise ArgumentError, 'Only one project name at a time' unless args.size == 1
         @projects ||= {}
         name = args.first
         if options && options[:scope]
           # We assume parent project is evaluated.
-          project = options[:scope].split(":").inject([[]]) { |scopes, scope| scopes << (scopes.last + [scope]) }.
-            map { |scope| @projects[(scope + [name]).join(":")] }.
+          project = options[:scope].split(':').inject([[]]) { |scopes, scope| scopes << (scopes.last + [scope]) }.
+            map { |scope| @projects[(scope + [name]).join(':')] }.
             select { |project| project }.last
         end
         unless project
           # Parent project not evaluated.
-          name.split(":").tap { |parts| @projects[parts.first].invoke if parts.size > 1 }
+          name.split(':').tap { |parts| @projects[parts.first].invoke if parts.size > 1 }
           project = @projects[name]
         end
         raise "No such project #{name}" unless project
@@ -202,16 +280,16 @@ module Buildr
           @projects.keys.map { |name| project(name) or raise "No such project #{name}" }.sort_by(&:name)
         else
           # Parent project(s) not evaluated, for the sub-projects we may need to find.
-          names.map { |name| name.split(":") }.select { |name| name.size > 1 }.map(&:first).uniq.each { |name| project(name) }
+          names.map { |name| name.split(':') }.select { |name| name.size > 1 }.map(&:first).uniq.each { |name| project(name) }
           names.uniq.map { |name| project(name) or raise "No such project #{name}" }.sort_by(&:name)
         end
       end
 
       # :call-seq:
-      #   clear()
+      #   clear
       #
       # Discard all project definitions.
-      def clear()
+      def clear
         @projects.clear if @projects
       end
 
@@ -246,21 +324,9 @@ module Buildr
         end
       end
 
-      # :call-seq:
-      #   on_define() { |project| ... }
-      #
-      # The Project class defines minimal behavior, only what is documented here.
-      # To extend its definition, other modules use Project#on_define to incorporate
-      # code called during a new project's definition.
-      #
-      # For example:
-      #   # Set the default version of each project to "1.0".
-      #   Project.on_define { |project| project.version ||= "1.0" }
-      #
-      # Since each project definition is essentially a task, if you need to do work
-      # at the end of the project definition (after the block is executed), you can
-      # enhance it from within #on_define.
+      # *Deprecated* Check the Extension module to see how extensions are handled.
       def on_define(&block)
+        Buildr.application.deprecated 'This method is deprecated, see Extension'
         (@on_define ||= []) << block if block
       end
 
@@ -269,13 +335,13 @@ module Buildr
       end
 
       def local_projects(dir = nil, &block) #:nodoc:
-        dir = File.expand_path(dir || Rake.application.original_dir)
+        dir = File.expand_path(dir || Buildr.application.original_dir)
         projects = Project.projects.select { |project| project.base_dir == dir }
         if projects.empty? && dir != Dir.pwd && File.dirname(dir) != dir
           local_projects(File.dirname(dir), &block)
         elsif block
           if projects.empty?
-            warn "No projects defined for directory #{Rake.application.original_dir}" if verbose
+            warn "No projects defined for directory #{Buildr.application.original_dir}" if verbose
           else
             projects.each { |project| block[project] }
           end
@@ -285,23 +351,38 @@ module Buildr
       end
 
       # :call-seq:
-      #   task_in_parent_project(task_name) => task_name or nil
+      #   parent_task(task_name) => task_name or nil
       #
-      # Assuming the task name is prefixed with the current project, finds and returns a task with the
-      # same name in a parent project.  Call this with "foo:bar:test" will return "foo:test", but call
-      # this with "foo:test" will return nil.
-      def task_in_parent_project(task_name)
-        namespace = task_name.split(":")
+      # Returns a parent task, basically a task in a higher namespace.  For example, the parent
+      # of 'foo:test:compile' is 'foo:compile' and the parent of 'foo:compile' is 'compile'.
+      def parent_task(task_name) #:nodoc:
+        namespace = task_name.split(':')
         last_name = namespace.pop
         namespace.pop
-        Rake.application.lookup((namespace + [last_name]).join(":"), []) unless namespace.empty?
+        Buildr.application.lookup((namespace + [last_name]).join(':'), []) unless namespace.empty?
+      end
+
+      # :call-seq:
+      #   project_from_task(task) => project
+      #
+      # Figure out project associated to this task and return it.
+      def project_from_task(task) #:nodoc:
+        project = Buildr.application.lookup('rake:' + task.to_s.gsub(/:[^:]*$/, ''))
+        project if Project === project
+      end
+
+      # Callback classes.
+      def callbacks #:nodoc:
+        @callbacks ||= []
       end
 
     end
 
-    include InheritedAttributes
 
-    # The project name. For example, "foo" for the top-level project, and "foo:bar"
+    # Project has visibility to everything in the Buildr namespace.
+    include Buildr
+
+    # The project name. For example, 'foo' for the top-level project, and 'foo:bar'
     # for its sub-project.
     attr_reader :name
 
@@ -310,17 +391,22 @@ module Buildr
 
     def initialize(*args) #:nodoc:
       super
-      split = name.split(":")
+      split = name.split(':')
       if split.size > 1
         # Get parent project, but do not invoke it's definition to prevent circular
-        # dependencies (it's being invoked right now, so calling project() will fail).
-        @parent = task(split[0...-1].join(":"))
-        raise "No parent project #{split[0...-1].join(":")}" unless @parent && Project === parent
+        # dependencies (it's being invoked right now, so calling project will fail).
+        @parent = task(split[0...-1].join(':'))
+        raise "No parent project #{split[0...-1].join(':')}" unless @parent && Project === parent
+      end
+      callbacks = Project.callbacks.uniq.map(&:new)
+      @callbacks = [:before_define, :after_define].inject({}) do |hash, state|
+        methods = callbacks.select { |callback| callback.respond_to?(state) }.map { |callback| callback.method(state) }
+        hash.update(state=>methods)
       end
     end
 
     # :call-seq:
-    #   base_dir() => path
+    #   base_dir => path
     #
     # Returns the project's base directory.
     #
@@ -329,15 +415,15 @@ module Buildr
     # a base directory that is one level down, with the same name as the sub-project.
     #
     # For example:
-    #   /home/foo/          <-- base_directory of project "foo"
-    #   /home/foo/Buildfile <-- builds "foo"
-    #   /home/foo/bar       <-- sub-project "foo:bar"
-    def base_dir()
+    #   /home/foo/          <-- base_directory of project 'foo'
+    #   /home/foo/Buildfile <-- builds 'foo'
+    #   /home/foo/bar       <-- sub-project 'foo:bar'
+    def base_dir
       if @base_dir.nil?
         if parent
           # For sub-project, a good default is a directory in the parent's base_dir,
           # using the same name as the project.
-          @base_dir = File.join(parent.base_dir, name.split(":").last)
+          @base_dir = File.expand_path(name.split(':').last, parent.base_dir)
         else
           # For top-level project, a good default is the directory where we found the Buildfile.
           @base_dir = Dir.pwd
@@ -346,20 +432,9 @@ module Buildr
       @base_dir
     end
 
-    # :call-seq:
-    #   base_dir = dir
-    #
-    # Sets the project's base directory. Allows you to specify a base directory by calling
-    # this accessor, or with the :base_dir property when calling #define.
-    #
-    # You can only set the base directory once for a given project, and only before accessing
-    # the base directory (for example, by calling #file or #path_to).
-    # Set the base directory. Note: you can only do this once for a project,
-    # and only before accessing the base directory. If you try reading the
-    # value with #base_dir, the base directory cannot be set again.
-    def base_dir=(dir)
-      raise "Cannot set base directory twice, or after reading its value" if @base_dir
-      @base_dir = File.expand_path(dir)
+    # Returns the layout associated with this project.
+    def layout
+      @layout ||= (parent ? parent.layout : Layout.default).clone
     end
 
     # :call-seq:
@@ -367,29 +442,102 @@ module Buildr
     #
     # Returns a path from a combination of name, relative to the project's base directory.
     # Essentially, joins all the supplied names and expands the path relative to #base_dir.
-    # Symbol arguments are converted to paths by calling the attribute accessor on the project.
+    # Symbol arguments are converted to paths based on the layout, so whenever possible stick
+    # to these.  For example:
+    #   path_to(:source, :main, :java)
+    #   => 'src/main/java'
     #
     # Keep in mind that all tasks are defined and executed relative to the Buildfile directory,
     # so you want to use #path_to to get the actual path within the project as a matter of practice.
     #
     # For example:
-    #   path_to("foo", "bar")
-    #   => /home/project1/foo/bar
-    #   path_to("/tmp")
+    #   path_to('foo', 'bar')
+    #   => foo/bar
+    #   path_to('/tmp')
     #   => /tmp
-    #   path_to(:base_dir, "foo") # same as path_to("foo")
+    #   path_to(:base_dir, 'foo') # same as path_to('foo")
     #   => /home/project1/foo
     def path_to(*names)
-      File.expand_path(File.join(names.map { |name| Symbol === name ? send(name) : name.to_s }), base_dir)
+      File.expand_path(layout.expand(*names), base_dir)
     end
     alias :_ :path_to
 
     # :call-seq:
-    #   define(name, properties?) { |project| ... } => project
+    #   file(path) => Task
+    #   file(path=>prereqs) => Task
+    #   file(path) { |task| ... } => Task
     #
-    # Define a new sub-project within this project. See Buildr#define.
-    def define(name, properties = nil, &block)
-      Project.define "#{self.name}:#{name}", properties, &block
+    # Creates and returns a new file task in the project. Similar to calling Rake's
+    # file method, but the path is expanded relative to the project's base directory,
+    # and the task executes in the project's base directory.
+    #
+    # For example:
+    #   define 'foo' do
+    #     define 'bar' do
+    #       file('src') { ... }
+    #     end
+    #   end
+    #
+    #   puts project('foo:bar').file('src').to_s
+    #   => '/home/foo/bar/src'
+    def file(*args, &block)
+      task_name, arg_names, deps = Buildr.application.resolve_args(args)
+      task = Rake::FileTask.define_task(path_to(task_name))
+      task.set_arg_names(arg_names) unless arg_names.empty?
+      task.enhance Array(deps), &block
+    end
+
+    # :call-seq:
+    #   task(name) => Task
+    #   task(name=>prereqs) => Task
+    #   task(name) { |task| ... } => Task
+    #
+    # Creates and returns a new task in the project. Similar to calling Rake's task
+    # method, but prefixes the task name with the project name and executes the task
+    # in the project's base directory.
+    #
+    # For example:
+    #   define 'foo' do
+    #     task 'doda'
+    #   end
+    #
+    #   puts project('foo').task('doda').name
+    #   => 'foo:doda'
+    #
+    # When called from within the project definition, creates a new task if the task
+    # does not already exist. If called from outside the project definition, returns
+    # the named task and raises an exception if the task is not defined.
+    #
+    # As with Rake's task method, calling this method enhances the task with the
+    # prerequisites and optional block.
+    def task(*args, &block)
+      task_name, arg_names, deps = Buildr.application.resolve_args(args)
+      if task_name =~ /^:/
+        Buildr.application.switch_to_namespace [] do
+          task = Rake::Task.define_task(task_name[1..-1])
+        end
+      elsif Buildr.application.current_scope == name.split(':')
+        task = Rake::Task.define_task(task_name)
+      else
+        unless task = Buildr.application.lookup(task_name, name.split(':'))
+          raise "You cannot define a project task outside the project definition, and no task #{name}:#{task_name} defined in the project"
+        end
+      end
+      task.set_arg_names(arg_names) unless arg_names.empty?
+      task.enhance Array(deps), &block
+    end
+
+    # :call-seq:
+    #   recursive_task(name=>prereqs) { |task| ... }
+    #
+    # Define a recursive task. A recursive task executes itself and the same task
+    # in all the sub-projects.
+    def recursive_task(*args, &block)
+      task_name, arg_names, deps = Buildr.application.resolve_args(args)
+      task = Buildr.options.parallel ? multitask(task_name) : task(task_name)
+      parent.task(task_name).enhance [task] if parent
+      task.set_arg_names(arg_names) unless arg_names.empty?
+      task.enhance Array(deps), &block
     end
 
     # :call-seq:
@@ -401,8 +549,8 @@ module Buildr
     #
     # When called on a project without a name, returns the project itself. You can use that when
     # setting project properties, for example:
-    #   define "foo" do
-    #     project.version = "1.0"
+    #   define 'foo' do
+    #     project.version = '1.0'
     #   end
     def project(*args)
       if Hash === args.last
@@ -431,101 +579,186 @@ module Buildr
       Project.projects *(args + [{ :scope=>self.name }.merge(options)])
     end
 
+    def inspect #:nodoc:
+      %Q{project(#{name.inspect})}
+    end
+
+  protected
+
     # :call-seq:
-    #   file(path) => Task
-    #   file(path=>prereqs) => Task
-    #   file(path) { |task| ... } => Task
-    #
-    # Creates and returns a new file task in the project. Similar to calling Rake's
-    # file method, but the path is expanded relative to the project's base directory,
-    # and the task executes in the project's base directory.
+    #   base_dir = dir
     #
-    # For example:
-    #   define "foo" do
-    #     define "bar" do
-    #       file("src") { ... }
-    #     end
-    #   end
+    # Sets the project's base directory. Allows you to specify a base directory by calling
+    # this accessor, or with the :base_dir property when calling #define.
     #
-    #   puts project("foo:bar").file("src").to_s
-    #   => "/home/foo/bar/src"
-    def file(args, &block)
-      task_name, deps = Rake.application.resolve_args(args)
-      deps = [deps] unless deps.respond_to?(:to_ary)
-      Rake::FileTask.define_task(path_to(task_name)=>deps, &block)
+    # You can only set the base directory once for a given project, and only before accessing
+    # the base directory (for example, by calling #file or #path_to).
+    # Set the base directory. Note: you can only do this once for a project,
+    # and only before accessing the base directory. If you try reading the
+    # value with #base_dir, the base directory cannot be set again.
+    def base_dir=(dir)
+      raise 'Cannot set base directory twice, or after reading its value' if @base_dir
+      @base_dir = File.expand_path(dir)
+    end
+
+    # Sets the project layout.  Accepts Layout object or class (or for that matter, anything
+    # that can expand).
+    def layout=(layout)
+      raise 'Cannot set directory layout twice, or after reading its value' if @layout
+      @layout = layout.is_a?(Class) ? layout.new : layout
     end
 
     # :call-seq:
-    #   task(name) => Task
-    #   task(name=>prereqs) => Task
-    #   task(name) { |task| ... } => Task
-    #
-    # Creates and returns a new task in the project. Similar to calling Rake's task
-    # method, but prefixes the task name with the project name and executes the task
-    # in the project's base directory.
-    #
-    # For example:
-    #   define "foo" do
-    #     task "doda"
-    #   end
-    #
-    #   puts project("foo").task("doda").name
-    #   => "foo:doda"
-    #
-    # When called from within the project definition, creates a new task if the task
-    # does not already exist. If called from outside the project definition, returns
-    # the named task and raises an exception if the task is not defined.
+    #   define(name, properties?) { |project| ... } => project
     #
-    # As with Rake's task method, calling this method enhances the task with the
-    # prerequisites and optional block.
-    def task(args, &block)
-      task_name, deps = Rake.application.resolve_args(args)
-      if task_name =~ /^:/
-        Rake.application.instance_eval do
-          scope, @scope = @scope, []
-          begin
-            Rake::Task.define_task(task_name[1..-1]=>deps, &block)
-          ensure
-            @scope = scope
-          end
-        end
-      elsif Rake.application.current_scope == name.split(":")
-        Rake::Task.define_task(task_name=>deps, &block)
-      else
-        if task = Rake.application.lookup(task_name, name.split(":"))
-          deps = [deps] unless deps.respond_to?(:to_ary)
-          task.enhance deps, &block
-        else
-          full_name = "#{name}:#{task_name}"
-          raise "You cannot define a project task outside the project definition, and no task #{full_name} defined in the project"
-        end
+    # Define a new sub-project within this project. See Buildr#define.
+    def define(name, properties = nil, &block)
+      Project.define "#{self.name}:#{name}", properties, &block
+    end
+
+    def execute(args) #:nodoc:
+      Buildr.application.switch_to_namespace name.split(':') do
+        super
       end
     end
 
-    # :call-seq:
-    #   recursive_task(name=>prereqs) { |task| ... }
-    #
-    # Define a recursive task. A recursive task executes itself and the same task
-    # in all the sub-projects.
-    def recursive_task(args, &block)
-      task_name, deps = Rake.application.resolve_args(args)
-      deps = [deps] unless deps.respond_to?(:to_ary)
-      task = Buildr.options.parallel ? multitask(task_name) : task(task_name)
-      parent.task(task_name).enhance [task] if parent
-      task.enhance deps, &block
+    # Call all callbacks for a particular state, e.g. :before_define, :after_define.
+    def call_callbacks(state) #:nodoc:
+      methods = @callbacks.delete(state) || []
+      methods.each { |method| method.call(project) }
     end
 
-    def execute() #:nodoc:
-      # Reset the namespace, so all tasks are automatically defined in the project's namespace.
-      Rake.application.in_namespace(":#{name}") { super }
+    def add_callback(callback)
+      @callbacks[:after_define] << callback.method(:after_define) if callback.respond_to?(:after_define)
     end
 
-    def inspect() #:nodoc:
-      %Q{project(#{name.inspect})}
+  end
+
+
+  # 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
+  module Extension
+
+    def self.included(base) #:nodoc:
+      base.extend ClassMethods
+    end
+
+    # Methods added to the extension module when including Extension.
+    module ClassMethods
+
+      def included(base) #:nodoc:
+        # When included in Project, add callback and call first_time.
+        if Project == base && !base.callbacks.include?(callbacks)
+          base.callbacks << callbacks
+          callbacks.first_time if callbacks.respond_to?(:first_time)
+        end
+      end
+
+      def extended(base) #:nodoc:
+        # When extending project, add instance and call before_define.
+        if Project === base
+          callbacks = self.send(:callbacks).new
+          callbacks.before_define(base) if callbacks.respond_to?(:before_define)
+          base.send :add_callback, callbacks
+        end
+      end
+
+      # This block will be called once for any particular extension.
+      # You can use this to setup top-level and local tasks.
+      def first_time(&block)
+        meta = class << callbacks ; self ; end
+        meta.send :define_method, :first_time, &block
+      end
+
+      # 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.
+      def before_define(&block)
+        callbacks.send :define_method, :before_define, &block
+      end
+
+      # 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.
+      def after_define(&block)
+        callbacks.send :define_method, :after_define, &block
+      end
+
+    private
+
+      def callbacks
+        const_get('Callbacks') rescue const_set('Callbacks', Class.new)
+      end
+
     end
 
   end
 
+
   # :call-seq:
   #   define(name, properties?) { |project| ... } => project
   #
@@ -547,17 +780,17 @@ module Buildr
   # related to the project.
   #
   # For example:
-  #   define "foo", :version=>"1.0" do
+  #   define 'foo', :version=>'1.0' do
   #
-  #     define "bar" do
-  #       compile.with "org.apache.axis2:axis2:jar:1.1"
+  #     define 'bar' do
+  #       compile.with 'org.apache.axis2:axis2:jar:1.1'
   #     end
   #   end
   #
-  #   puts project("foo").version
-  #   => "1.0"
-  #   puts project("foo:bar").compile.classpath.map(&:to_spec)
-  #   => "org.apache.axis2:axis2:jar:1.1"
+  #   puts project('foo').version
+  #   => '1.0'
+  #   puts project('foo:bar').compile.classpath.map(&:to_spec)
+  #   => 'org.apache.axis2:axis2:jar:1.1'
   #   % buildr build
   #   => Compiling 14 source files in foo:bar
   def define(name, properties = nil, &block) #:yields:project
@@ -570,9 +803,9 @@ module Buildr
   # Returns a project definition.
   #
   # When called from outside a project definition, must reference the project by its
-  # full name, e.g. "foo:bar" to access the sub-project "bar" in "foo". When called
-  # from inside a project, relative names are sufficient, e.g. <code>project("foo").project("bar")</code>
-  # will find the sub-project "bar" in "foo".
+  # full name, e.g. 'foo:bar' to access the sub-project 'bar' in 'foo'. When called
+  # from inside a project, relative names are sufficient, e.g. <code>project('foo').project('bar')</code>
+  # will find the sub-project 'bar' in 'foo'.
   #
   # You cannot reference a project before the project is defined. When working with
   # sub-projects, the project definition is stored by calling #define, and evaluated
@@ -584,21 +817,21 @@ module Buildr
   # or packages created by that project).
   #
   # For example:
-  #   define "myapp" do
-  #     self.version = "1.1"
+  #   define 'myapp' do
+  #     self.version = '1.1'
   #
-  #     define "webapp" do
+  #     define 'webapp' do
   #       # webapp is defined first, but beans is evaluated first
-  #       compile.with project("beans")
+  #       compile.with project('beans')
   #       package :war
   #     end
   #
-  #     define "beans" do
+  #     define 'beans' do
   #       package :jar
   #     end
   #   end
   #
-  #   puts project("myapp:beans").version
+  #   puts project('myapp:beans').version
   def project(*args)
     Project.project *args
   end
@@ -616,20 +849,42 @@ module Buildr
   # Be advised of circular dependencies.
   #
   # For example:
-  #   files = projects.map { |prj| FileList[prj.path_to("src/**/*.java") }.flatten
+  #   files = projects.map { |prj| FileList[prj.path_to('src/**/*.java') }.flatten
   #   puts "There are #{files.size} source files in #{projects.size} projects"
   #
-  #   puts projects("myapp:beans", "myapp:webapp").map(&:name)
+  #   puts projects('myapp:beans', 'myapp:webapp').map(&:name)
   # Same as:
-  #   puts project("myapp").projects.map(&:name)
+  #   puts project('myapp').projects.map(&:name)
   def projects(*args)
     Project.projects *args
   end
 
   # Forces all the projects to be evaluated before executing any other task.
   # If we don't do that, we don't get to have tasks available when running Rake.
-  task "buildr:initialize" do
-    projects
+  namespace 'buildr' do
+    task 'initialize' do
+      projects
+    end
+
+    desc "Freezes the Buildfile so it always uses Buildr version #{Buildr::VERSION}"
+    task 'freeze' do
+      puts "Freezing the Buildfile so it always uses Buildr version #{Buildr::VERSION}"
+      original = File.read(Buildr.application.buildfile)
+      if original =~ /gem\s*(["'])buildr\1/
+        modified = original.sub(/gem\s*(["'])buildr\1\s*,\s*(["']).*\2/, %{gem "buildr", "#{Buildr::VERSION}"})
+      else
+        modified = %{gem "buildr", "#{Buildr::VERSION}"\n} + original
+      end
+      File.open(Buildr.application.buildfile, "w") { |file| file.write modified }
+    end
+
+    desc 'Unfreezes the Buildfile to use the latest version of Buildr'
+    task 'unfreeze' do
+      puts 'Unfreezing the Buildfile to use the latest version of Buildr from your Gems repository.'
+      modified = File.read(Buildr.application.buildfile).sub(/^\s*gem\s*(["'])buildr\1.*\n/, "")
+      File.open(Buildr.application.buildfile, "w") { |file| file.write modified }
+    end
   end
 
+
 end