novoda-buildr 1.4.0

data/doc/extending.textile

@@ -0,0 +1,205 @@
+---
+layout: default
+title: Extending Buildr
+---
+
+h2(#tasks). 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:
+
+{% highlight 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=>_('src/main/sql/derby.xml')
+        ant.classpath :path=>projects('store', 'utils' ).
+          flatten.map(&:to_s).join(File::PATH_SEPARATOR)
+    end
+  end
+end
+{% endhighlight %}
+
+To this:
+
+{% highlight ruby %}
+file('derby.sql') do
+  mapping_tool :action=>'build', :sql=>task.name,
+    :properties=>_('src/main/sql/derby.xml'),
+    :classpath=>projects('store', 'utils')
+end
+{% endhighlight %}
+
+I prefer the second.  It's easier to look at the Buildfile and understand what it does.  It's easier to maintain when you only have to look at the important information.
+
+But just using functions is not always enough.  You end up with a Buildfile containing a lot of code that clearly doesn't belong there.  For starters, I recommend putting it in the @tasks@ directory.  Write it into a file with a @.rake@ extension and place that in the @tasks@ directory next to the Buildfile.  Buildr will automatically pick it up and load it for you.
+
+If you want to share these pre-canned definitions between projects, you have a few more options.  You can share the @tasks@ directory using SVN externals, Git modules, or whichever cross-repository feature your source control system supports. Another mechanism with better version control is to package all these tasks, functions and modules into a "Gem":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:
+* Put them in the same place (e.g. @~/.buildr@) and require them from your
+@buildfile@
+* Put them directly in the project, typically under the @tasks@ directory.
+* Put them in a shared code repository, and link to them from your project's @tasks@ directory
+* As Ruby gems and specify which gems are used in the settings file
+
+You can also get creative and devise your own way to distribute extensions.
+"Sake":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 %}
+class Project
+  include MyExtension
+end
+{% endhighlight %}
+
+You can also extend a given project instance and only that instance by extending it with the module:
+
+{% highlight ruby %}
+define 'foo' do
+  extend MyExtension
+end
+{% endhighlight %}
+
+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:
+
+{% highlight 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
+{% 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.
+
+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:
+
+{% highlight ruby %}
+define 'foo', :layout=>my_layout do
+  ...
+end
+{% endhighlight %}
+
+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:
+
+{% highlight ruby %}
+my_layout = Layout.new
+my_layout[:source, :main, :java] = 'java'
+my_layout[:source, :main, :resources] = 'resources'
+{% endhighlight %}
+
+Partial expansion also works, so you can specify the above layout using:
+
+{% highlight ruby %}
+my_layout = Layout.new
+my_layout[:source, :main] = ''
+{% endhighlight %}
+
+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:
+
+{% highlight 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
+{% endhighlight %}

data/doc/index.textile

@@ -0,0 +1,69 @@
+---
+layout: default
+title: Apache Buildr
+---
+
+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 something that's simple and intuitive to use, so we only need to tell it what to do, and it takes care of the rest.  But also something we can easily extend for those one-off tasks, with a language that's a joy to use.  And of course, we wanted it to be fast, reliable and have outstanding dependency management.
+
+
+h2(#why).  Why Buildr Rocks
+
+"Daniel Spiewak":http://www.codecommit.com/blog:
+
+bq. If you think about it, the question isn’t “Why use Buildr?”, it’s really “Why use anything else?” The advantages afforded by Buildr are so substantial, I really can’t see myself going with any other tool, at least not when I have a choice.
+
+"Tristan Juricek":http://tristanhunt.com/:
+
+bq. That’s still the strongest sell: it builds everything I need, and as I’ve needed more, I just got things working without a lot of fuss.
+
+"Matthieu Riou":http://offthelip.org/:
+
+bq. We used to rely on Ant, with a fairly extensive set of scripts. It worked but was expensive to maintain. The biggest mistake afterward was to migrate to Maven2. I could write pages of rants explaining all the problems we ran into and we still ended up with thousands of lines of XML.
+
+"Martin Grotzke":http://www.javakaffee.de/blog/:
+
+bq. The positive side effect for me as a java user is that I learn a little ruby, and that’s easy but lots of fun… :-)
+
+"Ijonas Kisselbach":http://twitter.com/ijonas/statuses/4134103928:
+
+bq. I've cleaned up & migrated the Vamosa build process from 768 lines of Ant build.xml to 28 lines of Buildr.
+
+h2(#what).  What You Get
+
+* A simple way to specify projects, and build large projects out of smaller sub-projects.
+* Pre-canned tasks that require the least amount of configuration, keeping the build script DRY and simple.
+* Compiling, copying and filtering resources, JUnit/TestNG test cases, APT source code generation, Javadoc and more.
+* A dependency mechanism that only builds what has changed since the last release.
+* A drop-in replacement for Maven 2.0, Buildr uses the same file layout, artifact specifications, local and remote repositories.
+* All your Ant tasks are belong to us! Anything you can do with Ant, you can do with Buildr.
+* No overhead for building "plugins" or configuration. Just write new tasks or functions.
+* Buildr is Ruby all the way down.  No one-off task is too demanding when you write code using variables, functions and objects.
+* Simple way to upgrade to new versions.
+* Did we mention fast?
+
+So let's get started.  You can "read the documentation online":quick_start.html, or "download the PDF":buildr.pdf.
+
+
+h2(#news).  What's New
+
+New in Buildr 1.3.5:
+
+* Interactive shell (REPL) support, including BeanShell for Java projects
+* Scala libraries are automatically downloaded if not availabe locally
+* New 'cobertura:check' allows you to check for code coverage levels in your projects
+* Eclipse task is configurable to support various types of natures, builders, etc.
+* Dependency upgrades such as Net-SSH 2.0.15, JRuby 1.3.1, Rake 0.8.7, RSpec 1.2.8, easyb 0.9, TestNG 5.10
+* And 15+ bug fixes.
+
+See the "CHANGELOG":CHANGELOG for full details.
+
+
+h2(#notices).  Credits & Notices
+
+!http://www.apache.org/images/asf-logo.gif(A project of the Apache Software Foundation)!:http://www.apache.org
+
+The Apache Software Foundation is a non-profit organization, consider "sponsoring":http://www.apache.org/foundation/sponsorship.html and check the "thanks":http://www.apache.org/foundation/thanks.html page.
+
+"ColorCons":http://www.mouserunner.com/Spheres_ColoCons1_Free_Icons.html, copyright of Ken Saunders.  "DejaVu fonts":http://dejavu.sourceforge.net, copyright of Bitstream, Inc.
+
+Community member quotes from a thread on "Stack Overflow":http://stackoverflow.com/questions/1015525/why-use-buildr-instead-of-ant-or-maven/1055864.

data/doc/installing.textile

@@ -0,0 +1,265 @@
+---
+layout: default
+title: Installing and Running
+---
+
+
+*The easy way:*  We recommend you pick the platform you want to run Buildr on and then follow the _easy way_ instructions for that platform.  It could save you an hour or two struggling to install all the right dependencies.
+
+"Installing Buildr for JRuby":#jruby is the same on all operating systems.  Choose JRuby if you're working with Java 6 on OS X, developing with multiple JDKs, or just like JRuby better.
+
+If you are running behind a proxy server, make sure the environment variable @HTTP_PROXY@ is set, as many of these steps require HTTP access.
+
+<br>
+
+*In details:* The @gem install@ and @gem update@ commands install Buildr from a binary distribution provided through "RubyForge":http://rubyforge.org/projects/buildr. This distribution is maintained by contributors to this project, but is *not* an official Apache distribution.  You can obtain the official Apache distribution files from the "download page":download.html.
+
+Older versions of RubyGems are all kind of fail.  You want to avoid these unless you have the patience to install each Buildr dependency manually.  Get RubyGems 1.3.1 or later, and when using Debian packages (e.g. Ubuntu), make sure to get the unmolested RubyGems straight form the source.
+
+The Ruby interpreter and JVM must use compatible architectures.  For example, OS X comes with 32-bit version of Ruby, Java 1.5 in both 32-bit and 64-bit flavors, and 64-bit Java 6.  As a result you can run Ruby with Java 1.5 (32-bit), but to use Java 6 you either need to build Ruby from source for 64-bit, or use "Buildr for JRuby":#jruby.
+
+h2(#linux).  Installing on Linux
+
+*The easy way:* Use this bash script to "install Buildr on Linux":scripts/install-linux.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 (requires @apt-get@, @yum@ or @urpmi@) and upgrade to RubyGems 1.3.1 or later.
+
+p(note). At this time, the native Ruby-Java Bridge (RJB) does not work very well on Linux with JDK 1.6.  If you get Segmentation Fault errors with JDK 1.6, we recommend switching to JDK 1.5.
+
+<br>
+
+*In details:* 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:
+
+{% highlight sh %}
+$ sudo yum install ruby rubygems ruby-devel gcc
+$ sudo gem update --system
+{% endhighlight %}
+
+On *Ubuntu* you have to install several packages:
+
+{% highlight sh %}
+$ 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:
+
+{% highlight sh %}
+$ wget http://rubyforge.org/frs/download.php/45905/rubygems-1.3.1.tgz
+$ tar xzf rubygems-1.3.1.tgz
+$ cd rubygems-1.3.1
+$ sudo ruby setup.rb
+$ sudo ln -s /usr/bin/gem1.8 /usr/bin/gem
+{% endhighlight %}
+
+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 %}
+$ sudo env JAVA_HOME=$JAVA_HOME gem install buildr
+{% endhighlight %}
+
+To upgrade to a new version or install a specific version:
+
+{% highlight sh %}
+$ sudo env JAVA_HOME=$JAVA_HOME gem update buildr
+$ sudo env JAVA_HOME=$JAVA_HOME gem install buildr -v 1.3.4
+{% endhighlight %}
+
+
+
+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.
+
+<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.
+
+OS X 10.4 (Tiger) includes an older version of Ruby that is not compatible with Buildr.  You can 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:
+
+{% highlight sh %}
+$ sudo gem update --system
+{% endhighlight %}
+
+Before installing Buildr, please set the @JAVA_HOME@ environment variable to point to your JDK distribution:
+
+{% highlight sh %}
+$ export JAVA_HOME=/Library/Java/Home
+{% endhighlight %}
+
+To install Buildr:
+
+{% highlight sh %}
+$ sudo env JAVA_HOME=$JAVA_HOME gem install buildr
+{% endhighlight %}
+
+To upgrade to a new version or install a specific version:
+
+{% highlight sh %}
+$ sudo env JAVA_HOME=$JAVA_HOME gem update buildr
+$ sudo env JAVA_HOME=$JAVA_HOME gem install buildr -v 1.3.4
+{% endhighlight %}
+
+
+h2(#windows).  Installing on Windows
+
+*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>
+
+*In details:* We recommend you first upgrade to the latest version of Ruby gems:
+
+{% highlight sh %}
+> gem update --system
+{% endhighlight %}
+
+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 --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 --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@.
+
+<br>
+
+*In details:* If you don't already have JRuby 1.1.6 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:
+
+{% highlight sh %}
+$ export PATH=$PATH:[path to JRuby]/bin:$JAVA_HOME/bin
+$ jruby -S gem install buildr
+{% endhighlight %}
+
+For Windows:
+
+{% highlight sh %}
+> set PATH=%PATH%;[path to JRuby]/bin;%JAVA_HOME%/bin
+> jruby -S gem install buildr
+{% endhighlight %}
+
+To upgrade to a new version or install a specific version:
+
+{% highlight sh %}
+$ jruby -S gem update buildr
+$ jruby -S gem install buildr -v 1.3.4
+{% endhighlight %}
+
+
+*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:
+
+{% highlight sh %}
+$ # with Ruby
+$ ruby -S gem install buildr
+$ ruby -S buildr
+$ # with JRuby
+$ jruby -S gem install buildr
+$ jruby -S buildr
+{% endhighlight %}
+
+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(#running). 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 by running @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 use Buildr by running the @buildr@ command:
+
+{% highlight sh %}
+$ buildr [options] [tasks] [name=value]
+{% endhighlight %}
+
+There are several options you can use, for a full list of options type @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.                            |
+| @-P/--prereqs@            | Display tasks and dependencies, then exit.              |
+
+You can tell Buildr to run specific tasks and the order to run them.  For example:
+
+{% highlight sh %}
+# Clean and rebuild
+buildr clean build
+# Package and install
+buildr install
+{% endhighlight %}
+
+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#env_vars 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:
+
+{% highlight sh %}
+$ export JAVA_OPTS='-Xms1g -Xmx1g'
+$ buildr TEST=no
+{% endhighlight %}
+
+
+h2(#help). 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:
+
+{% highlight sh %}
+$ buildr help
+{% endhighlight %}
+
+You can list the name and description of all your projects using the @help:projects@ task.  For example:
+
+{% highlight 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
+{% endhighlight %}
+
+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). Learning More
+
+*Ruby*  It pays to pick up Ruby as a second (or first) programming language. It's fun, powerful and slightly addictive.  If you're interested in learning Ruby the language, a good place to start is "Programming Ruby: The Pragmatic Programmer's Guide":http://www.pragprog.com/titles/ruby/programming-ruby, fondly known as the _Pickaxe book_.
+
+For a quicker read (and much more humor), "Why’s (Poignant) Guide to Ruby":http://poignantguide.net/ruby/ is available online.  More resources are listed on the "ruby-lang web site":http://www.ruby-lang.org/en/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.