buildr 1.3.3-java → 1.3.4-java

data/doc/index.textile

@@ -0,0 +1,47 @@
+---
+layout: default
+title: Welcome
+---
+
+h2(#what_is_apache_buildr).  What is 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.
+
+Here's what we got:
+
+* 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":getting_started.html, or "download the PDF":buildr.pdf.
+
+
+h2(#news).  Project News
+
+New in Buildr 1.3.4:
+
+* We graduated from the Apache Incubator!  This is our first release as a top-level Apache project: http://buildr.apache.org.  New site, new mailing lists, SVN, Git, etc.
+* Support for Git version control system
+* Improved all-around Scala support, including joint Java-Scala compilation and upgraded to Scala 2.7.3 dependencies: ScalaSpecs 1.4.3, ScalaCheck 1.5 and ScalaTest 0.9.5
+* New 'artifacts:sources' task to download source code for artifact jars
+* Source code attachments for external dependencies in Eclipse and IDEA projects
+* Dependency upgrades such as Rake 0.8.4, Net-SSH 2.0.11, RSpec 1.2.2, JRuby 1.1.6.
+* Documentation now uses "Jekyll":http://github.com/mojombo/jekyll/ to generate web site and PDF document.  This replaces Docter so less code to
+maintain and the same Textile/Liquid mechanism as when using Github pages.
+* And 20 or so bug fixes.
+
+See the "CHANGELOG":CHANGELOG for full details.
+
+
+h2(#legal).  Legal Notices
+
+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.

data/doc/{pages/languages.textile → languages.textile}

@@ -1,7 +1,10 @@
-h1. Languages
+---
+layout: default
+title: Languages
+---
 
 
-h2. Java
+h2(#java). Java
 
 
 h3. Compiling Java
@@ -43,9 +46,11 @@ The JUnit test framework supports the following options:
 
 For example, to pass properties to the test case:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 test.using :properties=>{ :currency=>'USD' }
-}}}
+{% endhighlight %}
+</notextile>
 
 There are benefits to running test cases in separate VMs.  The default forking mode is @:once@, and you can change it by setting the @:fork@ option.
 
@@ -58,28 +63,34 @@ You can see your tests running in the console, and if any tests fail, Buildr wil
 
 In addition, you can get a consolidated XML or HTML report by running the @junit:report@ task.  For example:
 
-{{{!sh
+<notextile>
+{% highlight sh %}
 $ buildr test junit:report test=all
 $ firefox report/junit/html/index.html
-}}}
+{% endhighlight %}
+</notextile>
 
 The @junit:report@ task generates a report from all tests run so far.  If you run tests in a couple of projects, it will generate a report only for these two projects.  The example above runs tests in all the projects before generating the reports.
 
 You can use the @build.yaml@ settings file to specify a particular version of JUnit or JMock.  For example, to force your build to use JUnit version 4.4 and JMock 2.0:
 
-{{{!yaml
+<notextile>
+{% highlight yaml %}
 junit: 4.4
 jmock: 2.0
-}}}
+{% endhighlight %}
+</notextile>
 
 
 h4. TestNG
 
 You can use "TestNG":http://testng.org instead of JUnit.  To select TestNG as the test framework, add this to your project:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 test.using :testng
-}}}
+{% endhighlight %}
+</notextile>
 
 Like all other options you can set with @test.using@, it affects the projects and all its sub-projects, so you only need to do this once at the top-most project to use TestNG throughout.  You can also mix TestNG and JUnit by setting different projects to use different frameworks, but you can't mix both frameworks in the same project.  (And yes, @test.using :junit@ will switch a project back to using JUnit)
 
@@ -93,9 +104,11 @@ The TestNG test framework supports the following options:
 
 You can use the @build.yaml@ settings file to specify a particular version of TestNG, for example, to force your build to use TestNG 5.7:
 
-{{{!yaml
+<notextile>
+{% highlight yaml %}
 testng: 5.7
-}}}
+{% endhighlight %}
+</notextile>
 
 
 h4. JBehave 
@@ -106,9 +119,11 @@ To use JBehave in your project you can select it with @test.using :jbehave@.
 
 This framework will search for the following patterns under your project:
 
-{{{
+<notextile>
+{% highlight text %}
 src/spec/java/**/*Behaviour.java
-}}}
+{% endhighlight %}
+</notextile>
 
 Supports the following options:
 
@@ -118,34 +133,52 @@ Supports the following options:
 
 You can use the @build.yaml@ settings file to specify a particular version of JBehave, for example, to force your build to use JBehave 1.0.1:
 
-{{{!yaml
+<notextile>
+{% highlight yaml %}
 jbehave: 1.0.1
-}}}
+{% endhighlight %}
+</notextile>
 
 
-h2. Scala
+h2(#scala). Scala
 
 Before using Scala features, you must first set the @SCALA_HOME@ environment variable to point to the root of your Scala distribution.
 
 On Windows:
 
-{{{!sh
-> set SCALA_HOME=C:\Path\To\Scala-2.7.1
-}}}
+<notextile>
+{% highlight sh %}
+> set SCALA_HOME=C:\Path\To\Scala-2.7.3
+{% endhighlight %}
+</notextile>
 
 On Linux and other Unix variants,
 
-{{{!sh
-> export SCALA_HOME=/path/to/scala-2.7.1
-}}}
+<notextile>
+{% highlight sh %}
+> export SCALA_HOME=/path/to/scala-2.7.3
+{% endhighlight %}
+</notextile>
 
-The @SCALA_HOME@ base directory should be such that Scala core libraries are  located directly under the "lib" subdirectory, and Scala scripts are under the  "bin" directory.
+The @SCALA_HOME@ base directory should be such that Scala core libraries are located directly under the "lib" subdirectory, and Scala scripts are under the "bin" directory. This step is not necessary if you installed Scala using MacPorts (OS X).
+
+You must also require the Scala compiler in your buildfile:
+
+<notextile>
+{% highlight ruby %}
+require 'buildr/scala'
+{% endhighlight %}
+</notextile>
 
 h3. Compiling Scala
 
 The Scala compiler looks for source files in the project's @src/main/scala@  directory, and defaults to compiling them into the @target/classes@ directory.  It looks for test cases in the project's @src/test/scala@ and defaults to  compile them into the @target/test/classes@ directory.
 
-If you point the @compile@ task at any other source directory, it will use the  Scala compiler if any of these directories contains files with the extension @.scala@.
+Any Java source files found in the @src/main/java@ directory will be compiled using the Scala/Java joint compiler into the @target/classes@ directory.  Both the Java and the Scala sources are compiled with an inclusive classpath, meaning that you may have a Java class which depends upon a Scala class which depends upon a Java class, all within the same project.  The Java sources will be compiled with the same dependencies as the Scala sources with the addition of the @scala-library.jar@ file as required for Scala interop.
+
+Note that you cannot use the Groovy *and* the Scala joint compilers in the same project.  If both are required, the Groovy joint compiler will take precedence.
++
+If you point the @compile@ task at any other source directory, it will use the  Scala compiler if any of these directories contains files with the extension @.scala@.  The joint compilation of Java sources may only be pointed at an alternative directory using the feature to redefine the @_(:src, :main, :java)@ path.
 
 When using the Scala compiler, if you don't specify the packaging type, it defaults to JAR.
 
@@ -158,6 +191,7 @@ The Scala compiler supports the following options:
 | @:other@        | Array of options passed to the compiler (e.g. @:other=>'-Xprint-types'@). |
 | @:target@       | Bytecode compatibility (e.g. '1.4'). |
 | @:warnings@     | Issue warnings when compiling.  True when running in verbose mode. |
+| @:javac@        | A hash of options passed to the @javac@ compiler verbatim. |
 
 h4. Fast Scala Compiler
 
@@ -171,34 +205,37 @@ For example, @src/main/scala/com/example/MyClass.scala@ should generate at least
 
 h3. Testing with Scala
 
-Buildr supports three Scala testing frameworks:   "ScalaTest":http://www.artima.com/scalatest,  "ScalaCheck":http://code.google.com/p/scalacheck/ and  "Specs":http://code.google.com/p/specs/.
-
-Scala testing is automatically enabled if you have any @.scala@ source files under @src/test/scala@.  If you are not using this convention, you can explicit set the test framework by doing,
+Buildr supports two main Scala testing frameworks:   "ScalaTest":http://www.artima.com/scalatest and  "Specs":http://code.google.com/p/specs/.  "ScalaCheck":http://code.google.com/p/scalacheck/ is also supported within the confines of either of these two frameworks.  Thus, your Specs may use ScalaCheck properties, as may your ScalaTest suites.
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 test.using(:scalatest)
-}}}
-
-The @:scalatest@ test framework handles ScalaTest, Specs and ScalaCheck therefore all 3 frameworks may be used within the same project.
+{% endhighlight %}
+</notextile>
 
 h4. ScalaTest
 
+ScalaTest support is activated automatically when there are any @.scala@ source files contained in the @src/test/scala@ directory.  If you are not using this directory convention, you may force the test framework by using the @test.using :scalatest@ directive.
+
 Buildr automatically detects and runs tests that extend the @org.scalatest.Suite@ interface.
 
 A very simplistic test class might look like,
 
-{{{!scala
+<notextile>
+{% highlight scala %}
 class MySuite extends org.scalatest.FunSuite {
   test("addition") {
     val sum = 1 + 1
     assert(sum === 2)
   }
 }
-}}}
+{% endhighlight %}
+</notextile>
 
 You can also pass properties to your tests by doing @test.using :properties => { 'name'=>'value' }@, and by overriding the @Suite.runTests@ method in a manner similar to:
 
-{{{!scala
+<notextile>
+{% highlight scala %}
 import org.scalatest._
 
 class PropertyTestSuite extends FunSuite {
@@ -217,15 +254,19 @@ class PropertyTestSuite extends FunSuite {
                    includes, excludes, properties)
   }
 }
-}}}
+{% endhighlight %}
+</notextile>
 
 h4. Specs
 
-The @:scalatest@ framework currently recognizes specifications with class names ending with "Specs", e.g., org.example.StringSpecs.
+Specs is automatically selected whenever there are @.scala@ source files under the @src/spec/scala@ directory.  It is also possible to force selection of the test framework by using the @test.using :specs@ directive.  This can sometimes be useful when Scala sources may be found in *both* @src/test/scala@ and @src/spec/scala@.  Normally in such cases, ScalaTest will have selection precedence, meaning that in case of a conflict between it and Specs, ScalaTest will be chosen.
+
+Any objects which extend the @org.specs.Specification@ superclass will be automatically detected and run.  Note that any *classes* which extend @Specification@ will also be invoked.  As such classes will not have a @main@ method, such an invocation will raise an error.
 
 A simple specification might look like this:
 
-{{{!scala
+<notextile>
+{% highlight scala %}
 import org.specs._
 import org.specs.runner._
 
@@ -236,13 +277,15 @@ object StringSpecs extends Specification {
     }
   }
 }
-}}}
+{% endhighlight %}
+</notextile>
 
 h4. ScalaCheck
 
 You may use ScalaCheck inside ScalaTest- and Specs-inherited classes.  Here is an example illustrating checks inside a ScalaTest suite,
 
-{{{!scala
+<notextile>
+{% highlight scala %}
 import org.scalatest.prop.PropSuite
 import org.scalacheck.Arbitrary._
 import org.scalacheck.Prop._
@@ -261,18 +304,21 @@ class MySuite extends PropSuite {
     (a: List[Int], b: List[Int]) => a.size + b.size == (a ::: b).size
   )
 }
-}}}
+{% endhighlight %}
+</notextile>
 
 
-h2. Groovy
+h2(#groovy). Groovy
 
 h3. Compiling Groovy
 
 Before using the Groovy compiler, you must first require it on your buildfile:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 require 'buildr/java/groovyc'
-}}}
+{% endhighlight %}
+</notextile>
 
 Once loaded, the groovyc compiler will be automatically selected if any .groovy source files are found under @src/main/groovy@ directory, compiling them by default into the @target/classes@ directory.
 
@@ -313,10 +359,12 @@ To use this framework in your project you can select it with @test.using :easyb@
 
 This framework will search for the following patterns under your project:
 
-{{{
+<notextile>
+{% highlight text %}
 src/spec/groovy/**/*Behavior.groovy
 src/spec/groovy/**/*Story.groovy
-}}}
+{% endhighlight %}
+</notextile>
 
 Supports the following options:
 
@@ -326,13 +374,13 @@ Supports the following options:
 | @:format@       | Report format, either @:txt@ or @:xml@ |
 
 
-h2.  Ruby
+h2(#ruby).  Ruby
 
 h3.  Testing with Ruby
 
 Buildr provides integration with some ruby testing frameworks, allowing you to test your Java code with state of the art tools.
 
-Testing code is written in "Ruby":http://www.ruby-lang.org/en/ language, and is run by using "JRuby":http://jruby.codehaus.org/.That means you have access to all your Java classes and any Java or Ruby tool out there.
+Testing code is written in "Ruby":http://www.ruby-lang.org/en/ language, and is run by using "JRuby":http://jruby.codehaus.org/. That means you have access to all your Java classes and any Java or Ruby tool out there.
 
 Because of the use of JRuby, you will notice that running ruby tests is faster when running Buildr on JRuby, as in this case there's no need to run another JVM.
 
@@ -340,9 +388,11 @@ p(tip). When not running on JRuby, Buildr will use the @JRUBY_HOME@ environment
 
 You can use the @build.yaml@ settings file to specify a particular version of JRuby (defaults to @1.1.4@).  For example:
 
-{{{!yaml
+<notextile>
+{% highlight yaml %}
 jruby: 1.1.3
-}}}
+{% endhighlight %}
+</notextile>
 
 h4.  RSpec
 
@@ -352,9 +402,11 @@ To use this framework in your project you can select it with @test.using :rspec@
 
 This framework will search for the following patterns under your project:
 
-{{{
+<notextile>
+{% highlight text %}
 src/spec/ruby/**/*_spec.rb
-}}}
+{% endhighlight %}
+</notextile>
 
 Supports the following options:
 
@@ -375,9 +427,11 @@ To use this framework in your project you can select it with @test.using :jtestr
 
 You can use the @build.yaml@ settings file to specify a particular version of JtestR (defaults to @0.3.1@).  For example:
 
-{{{!yaml
+<notextile>
+{% highlight yaml %}
 jtestr: 0.3.1
-}}}
+{% endhighlight %}
+</notextile>
 
 To customize TestNG/JUnit versions refer to their respective section.
 

data/doc/mailing_lists.textile

@@ -0,0 +1,25 @@
+---
+layout: default
+title: Mailing Lists
+---
+
+<form action="http://buildr.markmail.org/search/">Search all Buildr archives: <input type="text" name="q" size="50"/> <input type="submit" value="Search"/></form><br/>
+
+|_. users       |_. For developers working with Buildr |
+| Post          | "users@buildr.apache.org":mailto:users@buildr.apache.org |
+| Search        | "http://buildr.markmail.org/search/list:users":http://buildr.markmail.org/search/list:users |
+| Subscribe     | "users-subscribe@buildr.apache.org":mailto:users-subscribe@buildr.apache.org |
+| Unsubscribe   | "users-unsubscribe@buildr.apache.org":mailto:users-unsubscribe@buildr.apache.org |
+|_. dev         |_. For development of Buildr itself |
+| Post          | "dev@buildr.apache.org":mailto:dev@buildr.apache.org |
+| Search        | "http://buildr.markmail.org/search/list:dev":http://buildr.markmail.org/search/list:dev |
+| Subscribe     | "dev-subscribe@buildr.apache.org":mailto:dev-subscribe@buildr.apache.org |
+| Unsubscribe   | "dev-unsubscribe@buildr.apache.org":mailto:dev-unsubscribe@buildr.apache.org |
+|_. commits     |_. Commit messages and JIRA status |
+| Search        | "http://buildr.markmail.org/search/list:commits":http://buildr.markmail.org/search/list:commits |
+| Subscribe     | "commits-subscribe@buildr.apache.org":mailto:commits-subscribe@buildr.apache.org |
+| Unsubscribe   | "commits-unsubscribe@buildr.apache.org":mailto:commits-unsubscribe@buildr.apache.org |
+
+
+
+

data/doc/{pages/more_stuff.textile → more_stuff.textile}

@@ -1,7 +1,10 @@
-h1. More Stuff
+---
+layout: default
+title: More Stuff
+---
 
 
-h2.  Using Gems
+h2(#gems).  Using Gems
 
 The purpose of the buildfile is to define your projects, and the various tasks and functions used for building them.  Some of these are specific to your projects, others are more general in nature, and you may want to share them across projects.
 
@@ -15,9 +18,10 @@ You can also set up your own private repository and use it instead or in additio
 
 If your build depends on other gems, you will want to specify these dependencies as part of your build and check that configuration into source control.  That way you can have a specific environment that will guarantee repeatable builds, whether you're building a particular version, moving between branches, or joining an existing project.  Buildr will take care of installing all the necessary dependencies, which you can then manage with the @gem@ command.
 
-Use the @build.yaml@ file to specify these dependencies (see "Build Settings":settings_profiles.html#build_settings for more information), for example:
+Use the @build.yaml@ file to specify these dependencies (see "Build Settings":settings_profiles.html#build for more information), for example:
 
-{{{!yaml
+<notextile>
+{% highlight yaml %}
 # This project requires the following gems
 gems: 
   # Suppose we want to notify developers when testcases fail.
@@ -25,7 +29,8 @@ gems:
   # we test with ruby mock objects
   - mocha
   - ci_reporter
-}}}
+{% endhighlight %}
+</notextile>
 
 Gems contain executable code, and for that reason Buildr will not install gems without your permission.  When you run a build that includes any dependencies that are not already installed on your machine, Buildr will ask for permission before installing them.  On Unix-based operating systems, you will also need sudo privileges and will be asked for your password before proceeding.
 
@@ -39,28 +44,32 @@ Buildr will install the latest version that matches the version requirement. To
 
 Most gems include documentation that you can access in several forms.  You can use the @ri@ command line tool to find out more about a class, module or specific method.  For example:
 
-{{{!sh
+<notextile>
+{% highlight sh %}
 $ ri Buildr::Jetty
 $ ri Buildr::Jetty.start
-}}}
+{% endhighlight %}
+</notextile>
 
 You can also access documentation from a Web browser by running @gem server@ and pointing your browser to "http://localhost:8808":http://localhost:8808. Note that after installing a new gem, you will need to restart the gem server to see its documentation.
 
 
-h2.  Using Java Libraries
+h2(#java).  Using Java Libraries
 
 Buildr runs along side a JVM, using either RJB or JRuby.  The Java module allows you to access Java classes and create Java objects.
 
 Java classes are accessed as static methods on the @Java@ module, for example:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 str = Java.java.lang.String.new('hai!')
 str.toUpperCase
 => 'HAI!'
 Java.java.lang.String.isInstance(str)
 => true
 Java.com.sun.tools.javac.Main.compile(args)
-}}}
+{% endhighlight %}
+</notextile>
 
 The @classpath@ attribute allows Buildr to add JARs and directories to the classpath, for example, we use it to load Ant and various Ant tasks, code generators, test frameworks, and so forth.
 
@@ -68,9 +77,11 @@ When using an artifact specification, Buildr will automatically download and ins
 
 For example, Ant is loaded as follows:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 Java.classpath << 'org.apache.ant:ant:jar:1.7.0'
-}}}
+{% endhighlight %}
+</notextile>
 
 Artifacts can only be downloaded after the Buildfile has loaded, giving it a chance to specify which remote repositories to use, so adding to classpath does not by itself load any libraries.  You must call @Java.load@ before accessing any Java classes to give Buildr a chance to load the libraries specified in the classpath.
 
@@ -82,39 +93,72 @@ When building an extension, make sure to follow these rules:
 # Check on a clean build with empty local repository.
 
 
-h2. Nailgun
+h2(#buildr-server). BuildrServer
 
-"Nailgun":http://www.martiansoftware.com/nailgun/index.html is a client, protocol, and server for running Java programs from the command line without  incurring the JVM startup overhead.  Nailgun integration is available only when running Buildr within JRuby.
+Buildr provides an addon that allows you start a "dRuby":http://www.ruby-doc.org/stdlib/libdoc/drb/rdoc/index.html server hosting a buildfile, so that you can later invoke tasks on it without having to load the complete buildr runtime again.
 
-Buildr provides a custom nailgun server, allowing you to start a single JVM and let buildr create a queue of runtimes. These JRuby runtimes can be cached (indexed by buildfile path) and are  automatically reloaded when the buildfile has been modified. Runtime caching allows you to execute tasks without spending time creating  the buildr environment. 
+Usage:
+
+<notextile>
+{% highlight sh %}
+buildr -r buildr/drb drb:start
+{% endhighlight %}
+</notextile>
+
+To stop the BuildrServer simply use Ctrl+C or kill the process.
+
+Once the server has been started you can invoke tasks using a simple script:
+
+<notextile>
+{% highlight ruby %}
+#!/usr/bin/env ruby
+require 'rubygems'
+require 'buildr/drb'
+Buildr::DRbApplication.run
+{% endhighlight %}
+</notextile>
+
+Save this script as @dbuildr@, make it executable and use it to invoke tasks.
+  
+<notextile>
+{% highlight sh %}
+$ dbuildr clean compile
+{% endhighlight %}
+</notextile>
+
+@dbuildr@ will start the BuildrServer if there isn't one already running.
+Subsequent calls to dbuildr will act as the client and invoke the tasks you
+provide to the server.
+If the buildfile has been modified it will be reloaded on the BuildrServer.
+
+h3(#nailgun). Nailgun
+
+"Nailgun":http://www.martiansoftware.com/nailgun/index.html is a client, protocol, and server for running Java programs from the command line without incurring the JVM startup overhead.  Nailgun integration is available only when running Buildr within JRuby.
+
+JRuby users need not to create the @dbuildr@ script listed on the previous section, as they can benefit from
+using a nailgun client to invoke tasks without having to wait for JVM+JRuby to load.
 
 Start the BuildrServer by executing
 
-{{{!ruby
+<notextile>
+{% highlight sh %}
 $ jruby -S buildr -rbuildr/nailgun nailgun:start
-}}}
+{% endhighlight %}
+</notextile>
 
-Server output will display a message when it becomes ready, you will also see messages when the JRuby runtimes are being created, or when a new buildr environment is being loaded on them. After the runtime queues have been populated, you can start calling buildr as you normally do, by invoking the $NAILGUN_HOME/ng binary:
+To stop the BuildrServer simply use Ctrl+C or kill the process.
 
-{{{!sh
-# on another terminal, change directory to a project.
-# if this project is the same nailgun:start was invoked on, it's 
-# runtime has been cached, so no loading is performed unless 
-# the buildfile has been modified. otherwise the buildfile 
-# will be loaded on a previously loaded fresh-buildr runtime
-# and it will be cached.
-cd /some/buildr/project
-ng nailgun:help                      # display nailgun help
-ng nailgun:tasks                     # display overview of ng tasks
-ng clean compile                # just invoke those two tasks
-}}}
+Once the server has been started you can invoke tasks using the nailgun client
+installed on @$JRUBY_HOME/tool/nailgun/ng@
 
-Some nailgun tasks have been provided to manage the cached runtimes,  to get an overview of them execute the @nailgun:tasks@ task.
+<notextile>
+{% highlight sh %}
+$ ng clean compile
+{% endhighlight %}
+</notextile>
 
-Be sure to read the nailgun help by executing the @nailgun:help@ task.
 
-
-h2. Growl, Qube
+h2(#growl). Growl, Qube
 
 For OS X users, Buildr supports "Growl":http://growl.info/ out of the box to send "completed and "failed" notifications to the user.
 
@@ -125,7 +169,8 @@ For other platforms or if you want to notify the user differently, Buildr offers
 
 Here is an example using these extension points to send notifications using "Qube":http://launchpad.net/qube:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 # Send notifications using Qube 
 notify = lambda do |type, title, message|
   param = case type
@@ -142,27 +187,40 @@ end
 Buildr.application.on_failure do |title, message, ex| 
   notify['failed', title, message] 
 end
-}}}
+{% endhighlight %}
+</notextile>
 
 You can place this code inside @buildr.rb@ in your home directory.
 
-h2. Eclipse, IDEA
+h2(#eclipse_idea). Eclipse, IDEA
 
 If you're using Eclipse, you can generate @.classpath@ and @.project@ from your Buildfile and use them to create a project in your workspace:
 
-{{{!sh
+<notextile>
+{% highlight sh %}
 $ buildr eclipse
-}}}
+{% endhighlight %}
+</notextile>
 
 The @eclipse@ task will generate a @.classpath@ and @.project@ file for each of projects (and sub-project) that compiles source code.  It will not generate files for other projects, for examples, projects you use strictly for packaging a distribution, or creating command line scripts, etc.
 
 If you add a new project, change the dependencies, or make any other change to your Buildfile, just run the @eclipse@ task again to re-generate the Eclipse project files.
 
+To have your libraries' source code available in Eclipse, run:
+ 
+<notextile>
+{% highlight sh %}
+$ buildr artifacts:sources
+{% endhighlight %}
+</notextile>
+
 If you prefer IntelliJ IDEA, you can always:
 
-{{{!sh
+<notextile>
+{% highlight sh %}
 $ buildr idea
-}}}
+{% endhighlight %}
+</notextile>
 
 It will generate a @.iml@ file for every project (or subproject) and a @.ipr@ that you can directly open for the root project.  To allow IntelliJ Idea to resolve external dependencies properly, you will need to add a @M2_REPO@ variable pointing to your Maven2 repository directory (@Settings / Path Variables@).
 
@@ -171,64 +229,78 @@ If you're using IDEA 7 or later, use the @buildr idea7x@ task instead.  This tas
 Also, check out the "Buildr plugin for IDEA":http://www.digitalsanctum.com/buildr-plug-in/ (IDEA 7 and later).  Once installed, open your project with IDEA.  If IDEA finds that you have Buildr installed and finds a buildfile in the project's directory, it will show all the tasks available for that project.  To run a task, double-click it.  When the task completes, IDEA will show the results in the Buildr Output window.
 
 
-h2. Cobertura, Emma, JDepend
+h2(#cobertura_emma_jdepend). Cobertura, Emma, JDepend
 
 You can use "Cobertura":http://cobertura.sourceforge.net/ or "Emma":http://emma.sourceforge.net/ to instrument your code, run the tests and create a test coverage report in either HTML or XML format.
 
 There are two tasks for each tool, both of which generate a test coverage report in the @reports/cobertura@ (respectively @reports/emma@) directory.  For example:
 
-{{{!sh
+<notextile>
+{% highlight sh %}
 $ buildr test cobertura:html
-}}}
+{% endhighlight %}
+</notextile>
 
 As you can guess, the other tasks are @cobertura:xml@, @emma:html@ and @emma:xml@.
 
 If you want to generate a test coverage report only for a specific project, you can do so by using the project name as prefix to the tasks. 
 
-{{{!sh
+<notextile>
+{% highlight sh %}
 $ buildr subModule:cobertura:html
-}}}
+{% endhighlight %}
+</notextile>
 
 Each project can specify which classes to include or exclude from cobertura instrumentation by giving a class-name regexp to the @cobertura.include@ or @cobertura.exclude@ methods:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 define 'someModule' do 
-  cobertura.include 'some.package.*'
-  cobertura.include /some.(foo|bar).*/
+  cobertura.include 'some.package.==*=='
+  cobertura.include /some.(foo|bar).==*==/
   cobertura.exclude 'some.foo.util.SimpleUtil'
-  cobertura.exclude /*.Const(ants)?/i
+  cobertura.exclude /==*==.Const(ants)?/i
 end
-}}}
+{% endhighlight %}
+</notextile>
 
 Emma has @include@ and @exclude@ methods too, but they take glob patterns instead of regexps.
 
 You can use "JDepend":http://clarkware.com/software/JDepend.html on to generate design quality metrics.  There are three tasks this time, the eye candy one:
 
-{{{!sh
+<notextile>
+{% highlight sh %}
 $ buildr jdepend:swing
-}}}
+{% endhighlight %}
+</notextile>
 
 The other two tasks are @jdepend:text@ and @jdepend:xml@.
 
 We want Buildr to load fast, and not everyone cares for these tasks, so we don't include them by default.  If you want to use one of them, you need to require it explicitly.  The proper way to do it in Ruby:
 
-{{{!ruby
-require 'buildr/cobertura'
-require 'buildr/emma'
+<notextile>
+{% highlight ruby %}
+require 'buildr/java/cobertura'
+require 'buildr/java/emma'
 require 'buildr/jdepend'
-}}}
+{% endhighlight %}
+</notextile>
 
 You may want to add those to the Buildfile.  Alternatively, you can use these tasks for all your projects without modifying the Buildfile.  One convenient method is to add these lines to the @buildr.rb@ file in your home directory.
 
 Another option is to require it from the command line (@--require@ or @-r@), for example:
 
-{{{!sh
+<notextile>
+<notextile>
+{% highlight sh %}
 $ buildr --require buildr/jdepend jdepend:swing
-$ buildr -rbuildr/cobertura cobertura:html
-}}}
+$ buildr -rbuildr/java/cobertura cobertura:html
+{% endhighlight %}
+</notextile>
+</notextile>
 
 
-h2. Anything Ruby Can Do
+h2(#anything_ruby). Anything Ruby Can Do
 
 Buildr is Ruby code.  That's an implementation detail for some, but a useful features for others.  You can use Ruby to keep your build scripts simple and DRY, tackle ad hoc tasks and write reusable features without the complexity of "plugins".
 
@@ -236,21 +308,24 @@ We already showed you one example where Ruby could help.  You can use Ruby to ma
 
 You can use Ruby to perform ad hoc tasks.  For example, Buildr doesn't have any pre-canned task for setting file permissions.  But Ruby has a method for that, so it's just a matter of writing a task:
 
-{{{!ruby
-bins = file('target/bin'=>FileList[_('src/main/dist/bin/*')]) do |task|
+<notextile>
+{% highlight ruby %}
+bins = file('target/bin'=>FileList[_('src/main/dist/bin/==*==')]) do |task|
   mkpath task.name
   cp task.prerequisites, task.name
-  chmod 0755, FileList[task.name + '/*.sh'], :verbose=>false
+  chmod 0755, FileList[task.name + '/==*==.sh'], :verbose=>false
 end
-}}}
+{% endhighlight %}
+</notextile>
 
 You can use functions to keep your code simple.  For example, in the ODE project we create two binary distributions, both of which contain a common set of files, and one additional file unique to each distribution.  We use a method to define the common distribution:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 def distro(project, id)
   project.package(:zip, :id=>id).path("#{id}-#{version}").tap do |zip|
     zip.include meta_inf + ['RELEASE_NOTES', 'README'].map { |f| path_to(f) }
-    zip.path('examples').include project.path_to(:source, :examples), :as=>'.'
+    zip.path('examples').include project.path_to('src/examples'), :as=>'.'
     zip.merge project('ode:tools-bin').package(:zip)
     zip.path('lib').include artifacts(COMMONS.logging, COMMONS.codec,
       COMMONS.httpclient, COMMONS.pool, COMMONS.collections, JAXEN, SAXON,
@@ -262,25 +337,29 @@ def distro(project, id)
     yield zip
   end
 end
-}}}
+{% endhighlight %}
+</notextile>
 
 And then use it in the project definition:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 define 'distro-axis2' do
   parent.distro(self, "#{parent.id}-war") { |zip|
     zip.include project('ode:axis2-war').package(:war), :as=>'ode.war' }
 end
-}}}
+{% endhighlight %}
+</notextile>
 
 Ruby's functional style and blocks make some task extremely easy.  For example, let's say we wanted to count how many source files we have, and total number of lines:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 sources = projects.map { |prj| prj.compile.sources.
   map { |src| FileList["#{src}/**/*.java"] } }.flatten
 puts "There are #{source.size} source files"
 lines = sources.inject(0) { |lines, src| lines += File.readlines(src).size }
 puts "That contain #{lines} lines"
-}}}
-
+{% endhighlight %}
+</notextile>