buildr 1.3.5 → 1.4.0

data/addon/buildr/protobuf.rb

@@ -0,0 +1,75 @@
+# 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.
+
+
+module Buildr
+  # Provides Protocol buffer code generation tasks. Require explicitly using <code>require "buildr/protobuf"</code>.
+  module Protobuf
+    class << self
+      def protoc(*args)
+        options = Hash === args.last ? args.pop : {}
+        rake_check_options options, :output, :lang, :include
+
+        options[:lang] ||= :java
+        options[:output] ||= File.expand_path "target/generated/protoc"
+        options[:include] ||= []
+
+        command_line = []
+
+        command_line << "--#{options[:lang]}_out=#{options[:output]}" if options[:output]
+
+        (paths_from_sources(*args) + options[:include]).each { |i| command_line << "-I#{i}" }
+
+        command_line += files_from_sources(*args)
+
+        mkdir_p( options[:output] )
+
+        system protoc_path, *command_line
+      end
+
+      def protoc_path
+        ENV['PROTOC'] || "protoc"
+      end
+
+      def files_from_sources(*args)
+        args.flatten.map(&:to_s).collect { |f| File.directory?(f) ? FileList[f + "/**/*.proto"] : f }.flatten
+      end
+
+      def paths_from_sources(*args)
+        args.flatten.map(&:to_s).collect { |f| File.directory?(f) ? f : File.dirname(f) }
+      end
+    end
+
+    def protoc(*args)
+      if Hash === args.last
+        options = args.pop
+      else
+        options = {}
+      end
+
+      options[:output] ||= path_to(:target, :generated, :protoc)
+      options[:lang] ||= compile.language if compile.language
+
+      file(options[:output]=>Protobuf.files_from_sources(*args)) do |task|
+        Protobuf.protoc task.prerequisites, options
+      end
+    end
+
+  end
+
+  class Project
+    include Protobuf
+  end
+end

data/addon/buildr/xmlbeans.rb

@@ -23,12 +23,12 @@ module Buildr
   # Provides XMLBeans schema compiler. Require explicitly using <code>require "buildr/xmlbeans"</code>.
   #
   #   require 'buildr/xmlbeans'
-  #   define 'some_proj' do 
+  #   define 'some_proj' do
   #      compile_xml_beans _(:source, :main, :xsd) # the directory with *.xsd
   #   end
   module XMLBeans
 
-    # You can use ArtifactNamespace to customize the versions of 
+    # You can use ArtifactNamespace to customize the versions of
     # <code>:xmlbeans</code> or <code>:stax</code> used by this module:
     #
     #   require 'buildr/xmlbeans'
@@ -37,7 +37,7 @@ module Buildr
       ns.xmlbeans! 'org.apache.xmlbeans:xmlbeans:jar:2.3.0', '>2'
       ns.stax_api! 'stax:stax-api:jar:>=1.0.1'
     end
-    
+
     class << self
 
       def compile(*args)
@@ -48,7 +48,7 @@ module Buildr
         Buildr.ant "xmlbeans" do |ant|
           ant.taskdef :name=>"xmlbeans", :classname=>"org.apache.xmlbeans.impl.tool.XMLBean",
             :classpath=>requires.join(File::PATH_SEPARATOR)
-          ant.xmlbeans :srconly=>"true", :srcgendir=>options[:output].to_s, :classgendir=>options[:output].to_s, 
+          ant.xmlbeans :srconly=>"true", :srcgendir=>options[:output].to_s, :classgendir=>options[:output].to_s,
             :javasource=>options[:javasource] do
             args.flatten.each { |file| ant.fileset File.directory?(file) ? { :dir=>file } : { :file=>file } }
           end
@@ -58,7 +58,7 @@ module Buildr
       end
 
       def requires()
-        @requires ||= REQUIRES.artifacts.each(&:invoke).map(&:to_s)
+        @requires ||= REQUIRES.artifacts
       end
     end
 

data/buildr.buildfile

@@ -22,14 +22,14 @@ repositories.remote << 'http://scala-tools.org/repo-releases/'
 
 
 define 'buildr' do
-  compile.using :source=>'1.4', :target=>'1.4', :debug=>false
+  compile.using :source=>'1.5', :target=>'1.5', :debug=>false
 
   define 'java' do
     compile.using(:javac).from(FileList['lib/buildr/java/**/*.java']).into('lib/buildr/java')
   end
 
   define 'scala' do
-    compile.using(:scalac).from(FileList['lib/buildr/scala/**/*.scala']).into('lib/buildr/scala')
+    compile.using(:javac).from(FileList['lib/buildr/scala/**/*.java']).into('lib/buildr/scala')
   end
 
   desc 'Buildr extra packages (Antlr, Cobertura, Hibernate, Javacc, JDepend, Jetty, OpenJPA, XmlBeans)'

data/buildr.gemspec

@@ -16,11 +16,11 @@
 
 Gem::Specification.new do |spec|
   spec.name           = 'buildr'
-  spec.version        = '1.3.5'
+  spec.version        = '1.4.0'
   spec.author         = 'Apache Buildr'
   spec.email          = "users@buildr.apache.org"
   spec.homepage       = "http://buildr.apache.org/"
-  spec.summary        = "A build system that doesn't suck"
+  spec.summary        = "Build like you code"
   spec.description    = <<-TEXT
 Apache Buildr is a build system for Java-based applications, including support
 for Scala, Groovy and a growing number of JVM languages and tools.  We wanted
@@ -33,7 +33,7 @@ for those one-off tasks, with a language that's a joy to use.
   # Rakefile needs to create spec for both platforms (ruby and java), using the
   # $platform global variable.  In all other cases, we figure it out from RUBY_PLATFORM.
   spec.platform       = $platform || RUBY_PLATFORM[/java/] || 'ruby'
-  
+
   spec.files          = Dir['{addon,bin,doc,etc,lib,rakelib,spec}/**/*', '*.{gemspec,buildfile}'] +
                         ['LICENSE', 'NOTICE', 'CHANGELOG', 'README.rdoc', 'Rakefile', '_buildr', '_jbuildr']
   spec.require_paths  = 'lib', 'addon'
@@ -53,12 +53,13 @@ for those one-off tasks, with a language that's a joy to use.
   spec.add_dependency 'net-sftp',             '2.0.2'
   spec.add_dependency 'rubyzip',              '0.9.1'
   spec.add_dependency 'highline',             '1.5.1'
-  spec.add_dependency 'rubyforge',            '1.0.5'
+  spec.add_dependency 'json_pure',            '1.4.0'
+  spec.add_dependency 'rubyforge',            '2.0.3'
   spec.add_dependency 'hoe',                  '2.3.3'
-  spec.add_dependency 'rjb',                  '1.1.9' if spec.platform.to_s == 'ruby'
-  spec.add_dependency 'rjb',                  '1.1.6' if spec.platform.to_s == 'x86-mswin32'
+  spec.add_dependency 'rjb',                  '1.2.5' if spec.platform.to_s == 'ruby'
+  spec.add_dependency 'rjb',                  '1.2.5' if spec.platform.to_s == 'x86-mswin32' 
   spec.add_dependency 'Antwrap',              '0.7.0'
-  spec.add_dependency 'rspec',                '1.2.8'
+  spec.add_dependency 'rspec',                '>= 1.2.9'
   spec.add_dependency 'xml-simple',           '1.0.12'
   spec.add_dependency 'archive-tar-minitar',  '0.5.2'
   spec.add_dependency 'jruby-openssl',        '0.5.2' if spec.platform.to_s == 'java'

data/doc/_layouts/default.html

@@ -15,8 +15,8 @@
   <body>
     <div id='wrap'>
       <div id='header'>
-        <a href='http://buildr.apache.org/' title="The build system that doesn't suck"><img alt='buildr' src='images/buildr.png'></a>
-        <div class='tagline'>The build system that doesn't suck</div>
+        <a href='http://buildr.apache.org/' title="Build like you code"><img alt='buildr' src='images/buildr.png'></a>
+        <div class='tagline'>Build like you code</div>
       </div>
       <div id='pages'>
         <ol class='toc'>

data/doc/artifacts.textile

@@ -52,7 +52,7 @@ p(note). Buildr projects also define a @group@ attribute which can lead to some
 If you have several artifacts you always use together, consider placing them in an array.  Methods that accept lists of artifacts also accept arrays.  For example:
 
 {% highlight ruby %}
-OPENJPA = ['org.apache.openjpa:openjpa-all:jar:0.9.7',
+OPENJPA = ['org.apache.openjpa:openjpa:jar:1.2.1',
   'net.sourceforge.serp:serp:jar:1.12.0']
 AXIS_OF_WS = [AXIS2, AXIOM]
 
@@ -125,7 +125,7 @@ You can choose to relocate the local repository by giving it a different path, f
 repositories.local = '/usr/local/maven/repository'
 {% endhighlight %}
 
-That's one change you don't want to commit into the Buildfile, so the best place to do it is in your home directory's @buildr.rb@ file.
+That's one change you don't want to commit into the Buildfile, so the best place to do it is in the @buildr.rb@ file in the @.buildr@ directory under your home directory.
 
 Buildr downloads artifacts when it needs to use them, for example, to compile a project.  You don't need to download artifacts directly.  Except when you do, for example, if you want to download all the latest artifacts and then go off-line.  It's as simple as:
 
@@ -139,7 +139,7 @@ h2(#downloading). Downloading Artifacts
 Within your buildfile you can download artifacts directly by invoking them, for example:
 
 {% highlight ruby %}
-artifact('org.apache.openjpa:openjpa-all:jar:0.9.7').invoke
+artifact('org.apache.openjpa:openjpa:jar:1.2.1').invoke
 artifacts(OPENJPA).each(&:invoke)
 {% endhighlight %}
 
@@ -208,4 +208,4 @@ upload bean
 p(tip).  Calling the @install@ (and likewise @upload@) method on an artifact run @buildr install@.  If you need to download and install an artifact, invoke the task directly with @install(<artifact>).invoke@.
 
 
-Next we're going to "package some artifacts":packaging.html.
+We'll talk more about installing and uploading in the next chapter, but right now we're going to "package some artifacts":packaging.html.

data/doc/building.textile

@@ -25,7 +25,7 @@ Buildr uses file tasks to handle dependencies, but here we're talking about the
 
 An easier way to specify dependencies is by calling the @compile.with@ method. It takes a list of arguments and adds them to the dependency list.  The @compile.with@ method is easier to use, it accepts several type of dependencies.  You can use file names, file tasks, projects, artifacts specifications and even pass arrays of dependencies.
 
-Most dependencies fall into the last three categories.  When you pass a project to @compile.with@, it picks up all the packages created by that project.  In doing so, it establishes an order of dependency between the two projects (see "Defining the Project":projects.html#defining).  For example, if you make a change in project _teh-api_ and build _teh-impl_, Buildr will detect that change, recompile and package _teh-api_ before compiling _teh-impl_.  You can also select a specific package using the @package@ or @packages@ methods (see "Packaging":packaging.html).
+Most dependencies fall into the last three categories.  When you pass a project to @compile.with@, it picks up all the packages created by that project.  In doing so, it establishes an order of dependency between the two projects (see "Defining the Project":projects.html#defining).  For example, if you make a change in project _teh-api_ and build _teh-impl_, Buildr will detect that change, recompile and package _teh-api_ before compiling _teh-impl_.  You can also select a specific package using the project's @package@ or @packages@ methods (see "Packaging":packaging.html).
 
 When you pass an artifact specification to @compile.with@, it creates an @Artifact@ task that will download that artifact from one of the remote repositories, install it in the local repository, and use it in your project. Rake's dependency mechanism is used here to make sure the artifact is downloaded once, when needed.  Check the "Artifacts":artifacts.html section for more information about artifact specification and repositories.
 
@@ -115,7 +115,7 @@ The default source and target directories, compiler settings and other options y
 h2(#resources). Resources
 
 
-The @compile@ task comes bundled with a @resources@ task.  It copies files from the @src/main/resources@ directory into @target/resources@.  Best used for copying files that you want to included in the generated code, like configuration files, i18n messages, images, etc.
+The @compile@ task comes bundled with a @resources@ task.  It copies files from the @src/main/resources@ directory into @target/resources@.  Best used for copying files that you want to include in the generated code, like configuration files, i18n messages, images, etc.
 
 The @resources@ task uses a filter that can change files as it copies them from source to destination.  The most common use is by mapping values using a hash. For example, to substitute "${version}" for the project's version number and "${copyright}" for "Acme Inc (C) 2007" :
 
@@ -140,9 +140,10 @@ test:
 You can specify a different format by passing it as the first argument. Supported formats include:
 
 |_. Format  |_. Usage |
-| @:ant@    | Map from @key@ to value. |
+| @:ant@    | Map from <code>@key@</code> to value. |
 | @:maven@  | Map from @${key}@ to value (default). |
 | @:ruby@   | Map from @#{key}@ to value. |
+| @:erb@    | Map from @<%=key%>@ to value. | 
 | @Regexp@  | Map using the matched value of the regular expression (e.g. @/=(.*?)=/@). |
 
 For example, using the @:ruby@ format instead of the default @:maven@ format:
@@ -241,4 +242,35 @@ clean { rm_rf _('staged') }
 
 The @rm_rf@ method deletes the directory and all files in it.  It's named after UNIX's infamous @rm -rf@.  Use it wisely.  This is also a good time to introduce you to @FileUtils@, a standard Ruby library that contains convenient methods for creating and deleting directories, copying and moving files, even comparing two files.  They're all free of charge when you use Buildr.
 
+
+h2(#continuous-compilation). Continuous Compilation
+
+And if all that weren't enough, Buildr also offers a time-saving feature called continuous compilation.  This feature, implemented by the @cc@ task, instructs Buildr to loop eternally, polling your project's source directories for changes.  Whenever a change is detected, Buildr immediately triggers the appropriate compilation step and goes right back to polling.  This allows you to reap many of the benefits of an incrementally compiling IDE like Eclipse without sacrificing your favorite build tool.
+
+To get started, simply invoke the @cc@ task at the command prompt:
+
+{% highlight sh %}
+$ buildr cc
+{% endhighlight %}
+
+This task will immediately invoke the @compile@ and @test:compile@ tasks on your project if necessary.  This ensures that your build is completely up to the minute before polling is initiated.  After this initial build (if required), Buildr will print a notification indicating which directories are being monitored.  By default, these directories will include any source folders (e.g. @src/main/java/@), any test directories (e.g. @src/spec/scala/@) as well as any resources (e.g. @src/main/resources/).  The Buildr process will remain running during this time, meaning that in order to test this functionality, we will need to open a new shell:
+
+{% highlight sh %}
+$ touch src/main/java/Test.java
+{% endhighlight %}
+
+The moment we run this command, Buildr will detect the change and invoke the @compile@ task.  It will *not* invoke the @test:compile@ task, since none of the test files were actually changed.  This ensures that potentially time-consuming tasks are avoided if possible.  Note that, unlike the @build@ task, the continuous compilation also does not actually run any of your tests.  Continuous compilation is designed to be a simple daemon which runs forever, quickly recompiling your project as soon as you save or delete a file.  We can terminate the continuous compilation task by pressing Ctrl-C.  Left to its own devices, the @cc@ task really will loop forever.
+
+There are several advantages to continuous compilation.  Number one is convenience.  Once you invoke the @cc@ task, you can focus exclusively on the code, editing and saving your files in an unbroken workflow.  There is no need to break your concentration to invoke Buildr manually unless you need to run the test suite, deploy the application or anything beyond compilation.  The second advantage is speed.  By using the continuous compilation process, you avoid repeatedly incurring Buildr's startup overhead.  While this startup time is kept to a minimum, it is still perceptable, particularly when running on JRuby.  Since the @cc@ task runs within a Buildr instance which has already been started, there is no need for repeated, inefficient load times.  Again, this allows you to focus more completely on what's really important: the code.
+
+By default, the @cc@ task will poll your sources once every 200 milliseconds.  We have found that this frequency strikes a nice balance between CPU load (which is insignificant) and nearly-instant detection.  However, you may wish to tune this value based on your own needs.  To do so, simply use the @cc.frequency@ property in your project definition:
+
+{% highlight ruby %}
+project 'foo' do
+  cc.frequency 1.5      # poll every one-and-a-half seconds
+end
+{% endhighlight %}
+
+If you find that the 200 ms default imposes too much overhead, try changing @cc.frequency@ to a higher value.  On the flip side, if you find that you're waiting too long for changes to be caught by the poll, tune the frequency lower.
+
 Now let's "talk about the artifacts":artifacts.html we mentioned before.

data/doc/contributing.textile

@@ -250,3 +250,8 @@ A test-infected developer since 2001, Lacton yearns for a development infrastruc
 *"Daniel Spiewak":http://www.codecommit.com/blog* (djspiewak at apache.org)
 
 Daniel originally came to Buildr in search of a Scala build tool which was better than Ant.  He got more than he bargained for.  Now, he works to advance Buildr as the absolute best tool for supporting Scala development.
+
+*"Antoine Toulme":http://www.lunar-ocean.com/* (toulmean at apache.org)
+
+Antoine used Buildr first as an excuse to evade in Ruby land, creating plugins for Debian packaging, GWT compilation, or the NSIS installer. His main area of interest is the resolving of dependencies in the OSGi world. He works on making Buildr a standalone rock solid tool.
+

data/doc/download.textile

@@ -20,15 +20,26 @@ The source code is included in both source and binary distribution, the Gem dist
 
 h2(#dist).  Binaries and Source Code
 
+h3. buildr 1.3.5 (2009-10-05)
+
+|_. Package |_. MD5 Checksum |_. PGP |
+| "buildr-1.3.5.gem":http://www.apache.org/dyn/closer.cgi/buildr/1.3.5/buildr-1.3.5.gem | "5a04d8593f98606f15dd589988afe24d":http://www.apache.org/dist/buildr/1.3.5/buildr-1.3.5.gem.md5 | "Sig":http://www.apache.org/dist/buildr/1.3.5/buildr-1.3.5.gem.asc |
+| "buildr-1.3.5-java.gem":http://www.apache.org/dyn/closer.cgi/buildr/1.3.5/buildr-1.3.5-java.gem | "d930c851196cd8f9ea66b7190d324dd4":http://www.apache.org/dist/buildr/1.3.5/buildr-1.3.5-java.gem.md5 | "Sig":http://www.apache.org/dist/buildr/1.3.5/buildr-1.3.5-java.gem.asc |
+| "buildr-1.3.5-x86-mswin32.gem":http://www.apache.org/dyn/closer.cgi/buildr/1.3.5/buildr-1.3.5-x86-mswin32.gem | "a6dfc07b4c22e1902de6269e5776a32c":http://www.apache.org/dist/buildr/1.3.5/buildr-1.3.5-x86-mswin32.gem.md5 | "Sig":http://www.apache.org/dist/buildr/1.3.5/buildr-1.3.5-x86-mswin32.gem.asc |
+| "buildr-1.3.5.tgz":http://www.apache.org/dyn/closer.cgi/buildr/1.3.5/buildr-1.3.5.tgz | "d246b84d70a5934536a3f0cd8de1abf7":http://www.apache.org/dist/buildr/1.3.5/buildr-1.3.5.tgz.md5 | "Sig":http://www.apache.org/dist/buildr/1.3.5/buildr-1.3.5.tgz.asc |
+| "buildr-1.3.5.zip":http://www.apache.org/dyn/closer.cgi/buildr/1.3.5/buildr-1.3.5.zip | "d05f9a24f488318d22964bd2f443a76c":http://www.apache.org/dist/buildr/1.3.5/buildr-1.3.5.zip.md5 | "Sig":http://www.apache.org/dist/buildr/1.3.5/buildr-1.3.5.zip.asc |
+
+p>. ("Release signing keys":http://www.apache.org/dist/buildr/1.3.5/KEYS)
+
 h3. buildr 1.3.4 (2009-04-21)
 
 |_. Package |_. MD5 Checksum |_. PGP |
-| "buildr-1.3.4.gem":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.gem | "34247286f910be1724f63b9e795e75ed":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.gem.md5 | "Sig":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.gem.asc |
-| "buildr-1.3.4-java.gem":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4-java.gem | "44ed67bf835cf2abdc2b6723b5eceadb":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4-java.gem.md5 | "Sig":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4-java.gem.asc |
-| "buildr-1.3.4.tgz":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.tgz | "7d918b88a3bb8139f28f6ff0b39d003c":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.tgz.md5 | "Sig":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.tgz.asc |
-| "buildr-1.3.4.zip":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.zip | "8f4cf84dc6e293aac5fba7e2a9cc0776":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.zip.md5 | "Sig":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.zip.asc |
+| "buildr-1.3.4.gem":http://www.apache.org/dyn/closer.cgi/buildr/1.3.4/buildr-1.3.4.gem | "34247286f910be1724f63b9e795e75ed":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.gem.md5 | "Sig":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.gem.asc |
+| "buildr-1.3.4-java.gem":http://www.apache.org/dyn/closer.cgi/buildr/1.3.4/buildr-1.3.4-java.gem | "44ed67bf835cf2abdc2b6723b5eceadb":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4-java.gem.md5 | "Sig":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4-java.gem.asc |
+| "buildr-1.3.4.tgz":http://www.apache.org/dyn/closer.cgi/buildr/1.3.4/buildr-1.3.4.tgz | "7d918b88a3bb8139f28f6ff0b39d003c":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.tgz.md5 | "Sig":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.tgz.asc |
+| "buildr-1.3.4.zip":http://www.apache.org/dyn/closer.cgi/buildr/1.3.4/buildr-1.3.4.zip | "8f4cf84dc6e293aac5fba7e2a9cc0776":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.zip.md5 | "Sig":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.zip.asc |
 
-p>. ("Release signing keys":http://www.apache.org/dist/buildr/1.3.4/KEYS)
+p>. ("Release signing keys":http://www.apache.org/dist/buildr/KEYS)
 
 
 h3. buildr 1.3.3-incubating (2008-10-08)

data/doc/extending.textile

@@ -16,7 +16,7 @@ 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',
@@ -48,20 +48,20 @@ But just using functions is not always enough.  You end up with a Buildfile cont
 
 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":http://rubygems.org/ 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: 
+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.  
+You can also get creative and devise your own way to distribute extensions.
 "Sake":http://errtheblog.com/post/6069 is a good example of such initiative that lets you deploy Rake tasks on a system-wide basis.
 
 h2(#extensions).  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:
 
 {% highlight ruby %}
@@ -91,6 +91,7 @@ This example illustrates how to write a simple extension:
 
 {% highlight ruby %}
 module LinesOfCode
+
   include Extension
 
   first_time do
@@ -101,33 +102,58 @@ module LinesOfCode
 
   before_define do |project|
     # Define the loc task for this particular project.
-    define_task 'loc' do |task|
-      lines = task.prerequisites.map { |path| Dir["#{path}/**/*"] }.flatten.uniq.
-        inject(0) { |total, file| total + File.readlines(file).count }
+    project.recursive_task 'loc' do |task|
+      lines = task.prerequisites.map { |path|
+        Dir["#{path}/**/*"]
+      }.flatten.uniq.inject(0) { |total, file|
+        total = 0 if total.nil?
+        if File.file? file then
+          total + File.readlines(file).count
+        end
+      }
       puts "Project #{project.name} has #{lines} lines of code"
-    end
+      end
   end
 
   after_define do |project|
     # Now that we know all the source directories, add them.
-    task('loc'=>compile.sources + compile.test.sources)
+    task('loc' => project.compile.sources + project.test.sources)
   end
 
   # To use this method in your project:
-  #   loc path_1, path_2
+  # loc path_1, path_2
   def loc(*paths)
-    task('loc'=>paths)
+    task('loc' => paths)
   end
 
 end
 
 class Buildr::Project
-  include LinesOfCode
+    include LinesOfCode
 end
 {% endhighlight %}
 
 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
+
+{% highlight ruby %}
+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)
+{% endhighlight %}
+
+Core extensions provide the following named callbacks: @compile@, @test@, @build@, @package@ and @check@.
+
 h2(#layouts).  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.

data/doc/installing.textile

@@ -38,7 +38,7 @@ $ sudo gem update --system
 On *Ubuntu* you have to install several packages:
 
 {% highlight sh %}
-$ sudo apt-get install ruby-full ruby1.8-dev libopenssl-ruby build-essential 
+$ sudo apt-get install ruby-full ruby1.8-dev libopenssl-ruby build-essential
 {% endhighlight %}
 
 The Debian package for @rubygems@ will not allow you to install Buildr, so you need to install RubyGems from source:
@@ -70,6 +70,8 @@ h2(#osx).  Installing on OS X
 
 *The easy way:* Use this script to "install Buildr on OS X":scripts/install-osx.sh.  This script will install the most recent version of Buildr, or if already installed, upgrade to the most recent version.  It will also install Ruby 1.8.6 if not already installed (using MacPorts/Fink) and upgrage RubyGems to 1.3.1 or later.
 
+You need to have the Apple Development Tools installed.  They are available on the Mac OSX installation CD.
+
 <br>
 
 *In details:* OS X 10.5 (Leopard) comes with a recent version of Ruby 1.8.6.  You do not need to install a different version of Ruby when running OS X 10.5.
@@ -104,7 +106,7 @@ $ sudo env JAVA_HOME=$JAVA_HOME gem install buildr -v 1.3.4
 
 h2(#windows).  Installing on Windows
 
-*The easy way:*  The easiest way to install Ruby is using the "one-click installer":http://rubyinstaller.rubyforge.org/.  Once installed, set the @JAVA_HOME@ environment variable and run @gem install buildr@.
+*The easy way:*  The easiest way to install Ruby is using the "one-click installer":http://rubyinstaller.rubyforge.org/.  Be sure to install Ruby 1.8.6; support for Ruby 1.9.x is still a work in progress.  Once installed, set the @JAVA_HOME@ environment variable and run @gem install buildr --platform mswin32@.
 
 <br>
 
@@ -117,17 +119,16 @@ h2(#windows).  Installing on Windows
 Before installing Buildr, please set the @JAVA_HOME@ environment variable to point to your JDK distribution.  Next, use Ruby Gem to install Buildr:
 
 {% highlight sh %}
-> gem install buildr
+> gem install buildr --platform mswin32
 {% endhighlight %}
 
 To upgrade to a new version or install a specific version:
 
 {% highlight sh %}
 > gem update buildr
-> gem install buildr -v 1.3.4
+> gem install buildr -v 1.3.4 --platform mswin32
 {% endhighlight %}
 
-
 h2(#jruby).  Installing for JRuby
 
 *The easy way:* Use this bash script to "install Buildr on JRuby":scripts/install-jruby.sh.  This script will install the most recent version of Buildr, or if already installed, upgrade to the most recent version.  If necessary, it will also install JRuby 1.1.6 in @/opt/jruby@ and update the @PATH@ variable in @~/.bash_profile@ or @~/.profile@.