buildr 1.2.10 → 1.3.0

data/doc/pages/contributing.textile

@@ -0,0 +1,178 @@
+h1. Contributing
+
+Buildr is a community effort, and we welcome all contributors.  Here's your
+chance to get involved and help your fellow developers.
+
+
+h2.  Mailing Lists
+
+We run two mailing lists, the
+"buildr-user":http://mail-archives.apache.org/mod_mbox/incubator-buildr-user/
+mailing list for developers working with Buildr, that would be you if you're
+using Buildr or interested in using it.  There's the 
+"buildr-dev":http://mail-archives.apache.org/mod_mbox/incubator-buildr-dev/
+mailing list for talking about development of Buildr itself, and 
+"commits":http://mail-archives.apache.org/mod_mbox/incubator-buildr-commits/
+mailing list for following SVN commits and JIRA issues.
+
+Check the "mailing lists":mailing_lists.html page for more information on
+subscribing, searching and posting to the mailing list.
+
+
+h2.  Bugs (aka Issues)
+
+We really do try to keep bugs to a minimum, and anticipate everything you'll
+ever want to do with Buildr.  We're also, not perfect.  So you may have found a
+bug, or have an enhancement in mind, or better yet, a patch to contribute.
+Here's what you can do.
+
+If it's a bug, enhancement or patch, add it to
+"JIRA":http://issues.apache.org/jira/browse/Buildr.  For trivial stuff, that's
+good enough.
+
+If it needs more attention, start a discussion over on the mailing list.  We
+will still use JIRA to log the progress, but the mailing list is a better place
+for talking things through.
+
+When reporting a bug, please tell us which version of Ruby, Buildr and Java you
+are using, and also which operating system you are on:
+
+{{{!sh
+$ ruby --version
+$ buildr --version
+$ java --version
+}}}
+
+If you have a patch to submit, do it through
+"JIRA":http://issues.apache.org/jira/browse/Buildr.  We want to make sure
+Apache gets the right to use your contribution, and the JIRA upload form
+includes a simple contribution agreement.  Lawyer not included.
+
+
+h2.  Source Code
+
+Did we mention Buildr is an open source project?  In fact, when you install
+Buildr you get all the source code, documentation, test case and everything you
+need to use it, extend it and patch it.  Have a look in your Gem directory.
+
+But if you want to work with the latest and greatest, you'll want to check out
+"Buildr from SVN":http://svn.apache.org/repos/asf/incubator/buildr:
+
+{{{!sh
+$ svn co http://svn.apache.org/repos/asf/incubator/buildr/trunk buildr
+}}}
+
+You can also browse the "Buildr
+repository":http://svn.apache.org/repos/asf/incubator/buildr.
+
+Not a fan SVN?  We understand.  You can also grab a copy of "Buildr from
+Github":http://github.com/vic/buildr/tree/master:
+
+{{{!sh
+$ git clone git://github.com/vic/buildr.git
+}}}
+
+To install Buildr from the source directory:
+
+{{{!sh
+$ cd buildr
+$ rake setup install
+}}}
+
+When using Buildr for JRuby:
+
+{{{!sh
+$ cd buildr
+$ jruby -S rake setup install
+}}}
+
+
+h2.  Testing/Specs
+
+Obviously we won't turn down patches, but we'll love you even more if you
+include a test case.  One that will fail without the patch, and run
+successfully with it.  If not for our love, then think of the benefit to you:
+once we add that test case, we won't accidentally break that feature in the
+next release.
+
+We test using "RSpec":http://rspec.info/, a Behavior-Driven Development test
+framework.  The main difference between RSpec and xUnit is that RSpec helps you
+formulate test cases in terms of specifications: you describe how the code
+should behave, and run RSpec to make sure it matches that specification.
+
+You can run an individual specifications using the @spec@ command, for example:
+
+{{{!sh
+$ spec spec/compiler_spec.rb -l 409
+}}}
+
+To make sure your change did not break anything else, you can run all the
+specifications (be patient, we have a lot of these):
+
+{{{!sh
+$ rake spec
+}}}
+
+We always @rake spec@ before making a release.
+
+You can also check out the "RSpec report":report.html and "test coverage
+report":coverage/index.html for the current version of Buildr.  And if you want to help us on the journey to 100% test coverage, we'll be ever so grateful!
+
+
+h2.  Documentation
+
+Yes, we do make typos, spelling errors and sometimes we write things that don't
+make sense, so if you find a documentation bug, or want to help make the
+documentation even better, here's the way to do it.
+
+For simple typos and quick fixes, just send a message to the mailing list or
+log an issue in JIRA.
+
+If you end up rewriting a significant piece of text, or add new documentation
+(your rock!), send a patch.  Making documentation patches is fairly easy.  All
+the documentation is generated from text files in the @doc/pages@ directory, so
+all you need to do is check it out from SVN, edit, and @svn diff@ to create a
+patch.
+
+We use "Textile":http://www.textism.com/tools/textile/ as the markup language,
+it takes all of a few minutes to learn, it's intuitive to use, and produces
+clean HTML.  Also check out the "Textile Quick
+Reference":http://hobix.com/textile/quick.html.
+
+You can always check the documentation to see which conventions we use, and
+also a couple of extensions we have for styling source code (with syntax
+highlighting!) and handling footnotes.  The table of contents is auto-generated
+form H1/H2 headers.
+
+The tool we use for this is called Docter, which we developed specifically for
+Buildr, and use to create the Web site and printable PDF.  If you want to try
+it out you'll need to first @gem install docter@.  To generate a copy of the
+Web site, simple run @rake html@ .
+
+If you're thinking of editing the docs, and using @rake html@ to see what the
+HTML looks like, you may want to try something simpler.  Start by running the
+Docter Web server with @rake docter@ and then point your browser at
+@http://localhost:3000@.  To see your edits, simply refresh the page.
+
+Generating the PDF is a bit more tricky, we use the HTML in combination with
+print media CSS stylesheets and run them through the wonderful
+"PrinceXML":http://www.princexml.com/, so you'll need to install PrinceXML
+first before you can @rake pdf@.
+
+
+h2.  Contributors
+
+Here is the list of people who are actively working and committing on Buildr:
+
+*"Assaf Arkin":http://labnotes.org* (assaf at apache.org)
+
+*Alex Boisvert*
+
+*"Matthieu Riou":http://offthelip.org*
+
+*Victor Hugo Borja* (vborja at apache.org)
+
+Currently a Java Developer at
+"http://jwmsolutions.com":http://jwmsolutions.com, Victor has been enjoying and
+using Apache's software since 1999 when he started with Java, now he prefers
+programming Ruby and is happy to help on Apache's first ruby project. 

data/doc/pages/download.textile

@@ -0,0 +1,25 @@
+h1. Download
+
+
+h2.  Installing Buildr
+
+The easiest way to install Buildr is using the fabulous RubyGems package
+manager.  Of course, you will need either Ruby or JRuby, and we recommend a
+recent version of RubyGems and if this sounds foreign to you, don't worry.
+We'll show you how to install Buildr on Linux, OS/X, Windows and JRuby in the
+"Getting Started guide":getting_started.html, we even provide automated
+installation scripts.
+
+
+h2.  Binaries and Source Code
+
+
+p(note). When downloading from files please check the
+"md5sum":http://www.apache.org/dev/release-signing#md5 and verify the
+"OpenPGP":http://www.apache.org/dev/release-signing#openpgp compatible
+signature from the main Apache site. This
+"KEYS":http://www.apache.org/dist/incubator/buildr/KEYS file contains the
+public keys used for signing releases. It is recommended that (when possible) a
+web of trust is used to confirm the identity of these keys. For more
+information, please see the "Apache Release
+FAQ":http://www.apache.org/dev/release.html.

data/doc/pages/extending.textile

@@ -0,0 +1,229 @@
+h1. Extending Buildr
+
+h2. 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:
+
+{{{!ruby
+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=>_(:source, :main, :sql, 'derby.xml')
+        ant.classpath :path=>projects('store', 'utils' ).
+          flatten.map(&:to_s).join(File::PATH_SEPARATOR)
+    end
+  end
+end
+}}}
+
+To this:
+
+{{{!ruby
+file('derby.sql') do
+  mapping_tool :action=>'build', :sql=>task.name,
+    :properties=>_(:source, :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.
+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.
+
+For individual task files, you can also use
+"Sake":http://errtheblog.com/post/6069 for system-wide Rake tasks deployment.
+
+
+h2.  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:
+
+{{{!ruby
+class Project
+  include MyExtension
+end
+}}}
+
+You can also extend a given project instance and only that instance by
+extending it with the module:
+
+{{{!ruby
+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.
+
+|_. Method        |_. Usage |
+| @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:
+
+{{{!ruby
+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.
+    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
+}}}
+
+
+h2.  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:
+
+{{{!ruby
+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:
+
+{{{!ruby
+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:
+
+{{{!ruby
+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:
+
+|_. Path                          |_. Expands to |
+| @:source, :main, <lang/usage>@  |  Directory containing source files for a
+given language or usage, for example, @:java@, @:resources@, @:webapp@. |
+| @:source, :test, <lang/usage>@  | Directory containing test files for a given
+language or usage, for example, @:java@, @:resources@. |
+| @:target, :generated@           | Target directory for generated code
+(typically source code). |
+| @:target, :main, <lang/usage>@  | Target directory for compiled code, for
+example, @:classes@, @:resources@. |
+| @:target, :test, <lang/usage>@  | Target directory for compile test cases,
+for example, @:classes@, @:resources@. |
+| @:reports, <framework/usage>@   | Target directory for generated reports, for
+example, @:junit@, @:coverage@. |
+
+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:
+
+{{{!ruby
+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
+}}}

data/doc/pages/getting_started.textile

@@ -0,0 +1,337 @@
+h1. Getting Started
+
+h2.  Installing Buildr
+
+The installation instructions are slightly different for each operating system.
+If you are using Ruby, pick the one that best matches your operating system and
+target platform.
+
+p(note).  The current release of Buildr for Ruby does not work with Java 6 and
+can only be used with Java 1.5 or earlier.  "Buildr for JRuby":#jruby works
+nicely with Java 6, consider using that instead.
+
+
+h3.  Linux
+
+To get started you will need a recent version of Ruby, Ruby Gems and build
+tools for compiling native libraries (@make@, @gcc@ and standard headers).
+
+On *RedHat/Fedora* you can use yum to install Ruby and RubyGems, and then
+upgrade to the most recent version of RubyGems:
+
+{{{!sh
+$ sudo yum install ruby rubygems ruby-devel gcc
+$ sudo gem update --system
+}}}
+
+On *Ubuntu* you have to install several packages:
+
+{{{!sh
+$ sudo apt-get install ruby-full ruby1.8-dev libopenssl-ruby build-essential 
+}}}
+
+The Debian package for @rubygems@ will not allow you to install Buildr, so you
+need to install RubyGems from source:
+
+{{{!sh
+$ curl -OL http://rubyforge.org/frs/download.php/29548/rubygems-1.0.1.tgz
+$ tar xzf rubygems-1.0.1.tgz
+$ cd rubygems-1.0.1
+$ sudo ruby setup.rb
+$ sudo ln -s /usr/bin/gem1.8 /usr/bin/gem
+}}}
+
+Before installing Buildr, please set the @JAVA_HOME@ environment variable to
+point to your JDK distribution.  Next, use Ruby Gem to install Buildr:
+
+{{{!sh
+$ sudo env JAVA_HOME=$JAVA_HOME gem install buildr
+}}}
+
+To upgrade to a new version or install a specific version:
+
+{{{!sh
+$ sudo env JAVA_HOME=$JAVA_HOME gem update buildr
+$ sudo env JAVA_HOME=$JAVA_HOME gem install buildr -v 1.3.0
+}}}
+
+You can also use this script "to install Buildr on
+Linux":scripts/install-linux.sh.  This script will install Buildr or if already
+installed, upgrade to a more recent version.  It will also install Ruby 1.8.6
+if not already installed (using @yum@ or @apt-get@) and upgrage RubyGems to
+1.0.1.
+
+
+h3.  OS/X
+
+OS/X 10.5 (Leopard) comes with a recent version of Ruby 1.8.6.  OS/X 10.4
+(Tiger) includes an older version of Ruby, we recommend you first install Ruby
+1.8.6 using MacPorts (@sudo port install ruby rb-rubygems@), Fink or the
+"Ruby One-Click Installer for OS/X":http://rubyosx.rubyforge.org/.
+
+We recommend you first upgrade to the latest version of Ruby gems:
+
+{{{!sh
+$ sudo gem update --system
+}}}
+
+Before installing Buildr, please set the @JAVA_HOME@ environment variable to
+point to your JDK distribution:
+
+{{{!sh
+$ export JAVA_HOME=/Library/Java/Home
+}}}
+
+To install Buildr:
+
+{{{!sh
+$ sudo env JAVA_HOME=$JAVA_HOME gem install buildr
+}}}
+
+To upgrade to a new version or install a specific version:
+
+{{{!sh
+$ sudo env JAVA_HOME=$JAVA_HOME gem update buildr
+$ sudo env JAVA_HOME=$JAVA_HOME gem install buildr -v 1.3.0
+}}}
+
+You can also use this script "to install Buildr on
+OS/X":scripts/install-osx.sh.  This script will install Buildr or if already
+installed, upgrade to a more recent version.  It will also install Ruby 1.8.6
+if not already installed (using MacPorts) and upgrage RubyGems to 1.0.1.
+
+
+h3. Windows
+
+If you don't already have Ruby installed, now is the time to do it.  The
+easiest way to install Ruby is using the "one-click
+installer":http://rubyinstaller.rubyforge.org/.
+
+We recommend you first upgrade to the latest version of Ruby gems:
+
+{{{!sh
+> gem update --system
+}}}
+
+Before installing Buildr, please set the @JAVA_HOME@ environment variable to
+point to your JDK distribution.  Next, use Ruby Gem to install Buildr:
+
+{{{!sh
+> gem install buildr
+}}}
+
+Buildr uses several libraries that include native extensions.  During
+installation it will ask you to pick a platform for these libraries.  By
+selecting @mswin32@ it will download and install pre-compiled DLLs for these
+extensions.
+
+To upgrade to a new version or install a specific version:
+
+{{{!sh
+> gem update buildr
+> gem install buildr -v 1.3.0
+}}}
+
+
+h3. JRuby
+
+If you don't already have JRuby 1.1 or later installed, you can download it
+from the "JRuby site":http://dist.codehaus.org/jruby/.
+
+After uncompressing JRuby, update your @PATH@ to include both @java@ and @jruby@
+executables.
+
+For Linux and OS/X:
+
+{{{!sh
+$ export PATH=$PATH:[path to JRuby]/bin:$JAVA_HOME/bin
+$ gem install buildr
+}}}
+
+For Windows:
+
+{{{!sh
+> set PATH=%PATH%;[path to JRuby]/bin;%JAVA_HOME%/bin
+> gem install buildr
+}}}
+
+To upgrade to a new version or install a specific version:
+
+{{{!sh
+$ sudo gem update buildr
+$ sudo gem install buildr -v 1.3.0
+}}}
+
+You can also use this script "to install Buildr on
+JRuby":scripts/install-jruby.sh.  This script will install Buildr or if already
+installed, upgrade to a more recent version.  If necessary, it will also
+install JRuby 1.1 in @/opt/jruby@ and update the @PATH@ variable in
+@~/.bash_profile@ or @~/.profile@.
+
+*Important: Running JRuby and Ruby side by side*
+
+Ruby and JRuby maintain separate Gem repositories, and in fact install
+slightly different versions of the Buildr Gem (same functionality, different
+dependencies).  Installing Buildr for Ruby does not install it for JRuby and
+vice versa.
+
+If you have JRuby installed but not Ruby, the @gem@ and @buildr@ commands will
+use JRuby.  If you have both JRuby and Ruby installed, follow the instructions
+below.  To find out if you have Ruby installed (some operating systems include
+it by default), run @ruby --version@ from the command line.
+
+To work exclusively with JRuby, make sure it shows first on the path, for example,
+by setting @PATH=/opt/jruby/bin:$PATH@.
+
+You can use JRuby and Ruby side by side, by running scripts with the @-S@
+command line argument.  For example:
+
+{{{!
+$ # with Ruby
+$ ruby -S gem install buildr
+$ ruby -S buildr
+$ # with JRuby
+$ jruby -S gem install buildr
+$ jruby -S buildr
+}}}
+
+Run @buildr --version@ from the command line to find which version of Buildr
+you are using by default.  If you see @(JRuby ...)@, Buildr is running on that
+version of JRuby.
+
+
+h2. Conventions
+
+Lines that start with @$@ are command lines, for example:
+
+{{{!sh
+$ # Run Buildr
+$ buildr
+}}}
+
+Lines that start with @=>@ show output from the console or the result of a
+method, for example:
+
+{{{!sh
+puts 'Hello world'
+=> "Hello world"
+}}}
+
+And as you guessed, everything else is Buildfile Ruby or Java code.  You can
+figure out which language is which.
+
+
+
+h2. Running Buildr
+
+You need a *Buildfile*, a build script that tells Buildr all about the projects
+it's building, what they contain, what to produce, and so on.  The Buildfile
+resides in the root directory of your project.  We'll talk more about it in
+"the next chapter":projects.html.  If you don't already have one, ask Buildr to
+create it:
+
+{{{!sh
+$ buildr
+}}}
+
+p(tip). You'll notice that Buildr creates a file called @buildfile@.  It's
+case sensitive, but Buildr will look for either @buildfile@ or @Buildfile@.
+You can also use @Rakefile@ or @rakefile@ for compatibility with previous
+versions of Buildr.
+
+You use Buildr by running the @buildr@ command:
+
+{{{!sh
+$ buildr [options] [tasks] [name=value]
+}}}
+
+There are several options you can use, for a full list of options type:
+
+{{{!sh
+$ buildr --help
+}}}
+
+|_. Option                  |_. Usage |
+| @-f/--buildfile [file]@   | Specify the buildfile.                                  |
+| @-e/--environment [name]@ | Environment name (e.g. development, test, production).  |
+| @-h/--help@               | Display this help message.                              |
+| @-n/--nosearch@           | Do not search parent directories for the buildfile.     |
+| @-q/--quiet@              | Do not log messages to standard output.                 |
+| @-r/--require [file]@     | Require MODULE before executing buildfile.              |
+| @-t/--trace@              | Turn on invoke/execute tracing, enable full backtrace.  |
+| @-v/--version@            | Display the program version.                            |
+
+You can tell Buildr to run specific tasks and the order to run them.  For
+example:
+
+{{{!sh
+# Clean and rebuild
+buildr clean build
+# Package and install
+buildr install
+}}}
+
+If you don't specify a task, Buildr will run the "@build@ task":building.html,
+compiling source code and running test cases.  Running a task may run other
+tasks as well, for example, running the @install@ task will also run @package@.
+
+There are several "environment
+variables":settings_profiles.html#environment_variables that let you control
+how Buildr works, for example, to skip test cases during a build, or specify
+options for the JVM.  Depending on the variable, you may want to set it once in
+your environment, or set a different value each time you run Buildr.
+
+For example:
+
+{{{!sh
+$ export JAVA_OPTS='-Xms1g -Xmx1g'
+$ buildr TEST=no
+}}}
+
+
+h2. Help Tasks
+
+Buildr includes a number of informative tasks.  Currently that number stands at
+two, but we'll be adding more tasks in future releases.  These tasks report
+information from the Buildfile, so you need one to run them.  For more general
+help (version number, command line arguments, etc) use @buildr --help@.
+
+To start with, type:
+
+{{{!sh
+$ buildr help
+}}}
+
+You can list the name and description of all your projects using the
+@help:projects@ task.  For example:
+
+{{{!sh
+$ buildr help:projects
+killer-app                 # Code. Build. ??? Profit!
+killer-app:teh-api         # Abstract classes and interfaces
+killer-app:teh-impl        # All those implementation details
+killer-app:la-web          # What our users see
+}}}
+
+You are, of course, describing your projects for the sake of those who will
+maintain your code, right?  To describe a project, or a task, call the @desc@
+method before the project or task definition.
+
+So next let's talk about "projects":projects.html.
+
+
+h2. More Info
+
+*API* The "Buildr API":http://incubator.apache.org/buildr/rdoc/index.html
+documentation.
+
+*Rake* Buildr is based on Rake, a Ruby build system that handles tasks and
+dependencies.  Check out the "Rake documentation":http://docs.rubyrake.org/ for
+more information.
+
+*AntWrap* Buildr uses AntWrap, for configuring and running Ant tasks.  You can
+learn more from the "Antwrap documentation":http://antwrap.rubyforge.org/.
+
+*YAML* Buildr uses YAML for its profiles.  You can "learn more about YAML
+here":http://www.yaml.org, and use this handy "YAML quick
+reference":http://www.yaml.org/refcard.html.