buildr 1.3.4 → 1.3.5

data/doc/more_stuff.textile

@@ -3,6 +3,118 @@ layout: default
 title: More Stuff
 ---
 
+h2(#shell).  Interactive Shells (REPLs)
+
+Many languages (including Scala and Groovy) provide an interactive shell tool which allows developers to run arbitrary expressions and see the results immediately:
+
+<pre>$ scala
+Welcome to Scala version 2.7.4.final (Java HotSpot(TM) 64-Bit Server VM, Java 1.6.0_03-p3).
+Type in expressions to have them evaluated.
+Type :help for more information.
+
+scala> 6 * 7
+res0: Int = 42
+
+scala> </pre>
+
+These tools are alternatively known as "REPLs" (Read, Eval, Print Loop), a term which originally comes from Lisp.  This sort of interactive shell can be an invaluable asset when developing frameworks or other non-UI-oriented modules.  A common use-case is running a quick, manual test to make sure that the framework is functioning properly.  It is faster and easier to do this in a shell, and also averts the need for extra test cases to be developed just to check simple things during development.
+
+Unfortunately, for such a tool to be useful in Java, Scala or Groovy development, it must have access to the @CLASSPATH@, not only the compiled project binaries, but also its full list of dependencies.  While it is usually possible with such tools to specify the classpath upon startup (e.g. the @-cp@ switch for the Scala shell), this can get extremely tedious for project's with more dependencies, especially when some of these dependencies are defined using @transitive@ artifacts.
+
+Buildr is capable of easing this workflow by providing full support for the configuration and launch of interactive shells, the relevant shell may be launched simply by invoking the @shell@ task:
+
+{% highlight sh %}
+$ buildr shell
+{% endhighlight %}
+
+The @shell@ task depends upon @compile@, meaning that any changed source files will be recompiled prior to the shell's launch.  Tests will not be run, nor will test files be recompiled.  From within the shell itself, you should have access to your project's compilation classpath (anything specified using @compile.with@) as well as the compiled sources for your project.
+
+The project classpath is determined by checking the current working directory of your system shell (the path from which the @buildr shell@ command was invoked) and recursively finding the relevant project for that directory.  Thus, if you have a parent project @foo@ which has sub-projects @bar@ and @baz@, you may invoke an interactive shell for the @baz@ project simply by @cd@-ing into its project directory (or any of its sub-directories) and invoking the @shell@ task. You may also invoke a shell against a specific project by giving its fully-qualified descriptor as a prefix to the @shell@ task:
+
+{% highlight sh %}
+$ buildr foo:bar:shell
+{% endhighlight %}
+
+h3. Supported Shells
+
+By default, Buildr will open the interactive shell which corresponds to your project's language.  Thus, if your project is using Groovy, it will invoke the @groovysh@ command, configured with the appropriate classpath.  If your project is using Scala, then the @shell@ task will invoke the @scala@ command.  Unfortunately, the Java language does not define an interactive shell of any kind, however for those projects using exclusively the Java language, Buildr will use the "BeanShell":http://www.beanshell.org/manual/quickstart.html#The_BeanShell_GUI console.
+
+However, you may still wish to exploit the advantages of an interactive shell from some other JVM language even while working in Java.  Alternatively, you may want to use some shell other than the default even when working in a language which has its own.  There are two ways to acheive this aim.  The quickest way is to explicitly specify the relevant shell at the call-site:
+
+{% highlight sh %}
+$ buildr foo:shell:jirb
+{% endhighlight %}
+
+This will open the JIRB shell (the JRuby REPL) for the @foo@ project.  Whenever you are specifying a shell explicitly in this fashion, you *must* fully-qualify the project name:
+
+{% highlight sh %}
+$ buildr shell:jirb     # wrong!!
+{% endhighlight %}
+
+The above will fail because of the way that Rake tasks are dispatched.
+
+Obviously, this explicit specification is a little bit clunky.  It would be much easier if we could simply say that we *always* want to use the JIRB shell for this particular project.  This can be done by using the @shell.using@ directive within your project definition:
+
+{% highlight ruby %}
+define 'foo' do
+  shell.using :jirb
+end
+{% endhighlight %}
+
+With this project definition, we can now invoke the @shell@ task and JIRB will be launched, regardless of the default for our project's language:
+
+{% highlight sh %}
+$ buildr shell
+{% endhighlight %}
+
+Buildr supports several different shell providers, and the framework is flexible enough that additional support can be added almost trivially.  The following table gives the complete list of supported shells, their corresponding @shell.using@ descriptor and the language for which they are the default (if applicable):
+
+|_. Shell Name        |_. Descriptor       |_. Language       |
+| BeanShell Console   | @:bsh@             | Java             |
+| Clojure REPL        | @:clj@             | *N/A*            |
+| GroovySH            | @:groovysh@        | Groovy           |
+| JRuby IRB           | @:jirb@            | *N/A*            |
+| Scala Interpreter   | @:scala@           | Scala            |
+
+Note that some of these shells impose certain requirements to enable use.  The Groovy shell requires the @GROOVY_HOME@ environment variable to point to the Groovy install path.  The Clojure REPL makes a similar requirement of @CLOJURE_HOME@.  The JRuby and Scala shells will use @JRUBY_HOME@ and @SCALA_HOME@ respectively if they are defined.  However, if these environment variables are not defined, the relevant JAR files will be automatically downloaded from the appropriate Maven2 repository.
+
+h3. JavaRebel Integration
+
+"JavaRebel":http://www.zeroturnaround.com/javarebel is a live bytecode reloading solution by Zero Turnaround.  It's a lot like the hot code reload feature found in many Java IDE debuggers (like Eclipse and IntelliJ), but capable of handling things like member addition or removal and new class definition.  The tool itself is commercial and works with any JVM language, but they do offer a free license for use with Scala classes only.
+
+If available, Buildr will use JavaRebel when configuring the launch for each interactive shell.  Shells launched with JavaRebel integration will automatically receive recompiled changes on the fly without any need to restart the shell.  There are some limitations to this which are specific to the shell in question, but for the most part, things Just Work.
+
+JavaRebel auto-magical integration is done by searching for a valid JavaRebel install path in the following list of environment variables (in order):
+
+* @REBEL_HOME@
+* @JAVA_REBEL@
+* @JAVAREBEL@
+* @JAVAREBEL_HOME@
+
+These environment variables may point to either the JavaRebel install directory (e.g. @~/javarebel-2.0.1@), or the JAR file itself (e.g. @~/javarebel-2.0.1/javarebel.jar@).  If the path is valid, Buildr will automatically append the appropriate JVM switches to the launch configurations of each shell:
+
+<pre>$ buildr shell
+(in ~/foo, development)
+Compiling foo into ~/foo/target/classes
+Running java scala.tools.nsc.MainGenericRunner
+
+#############################################################
+
+ ZeroTurnaround JavaRebel 2.0.1 (200905251513)
+ (c) Copyright Webmedia, Ltd, 2007-2009. All rights reserved.
+
+ This product is licensed to Daniel Spiewak
+ for personal use only. 
+
+#############################################################
+
+Welcome to Scala version 2.7.4.final (Java HotSpot(TM) 64-Bit Server VM, Java 1.6.0_03-p3).
+Type in expressions to have them evaluated.
+Type :help for more information.
+
+scala> </pre>
+
+Note that Buildr does *not* check to make sure that you have a valid JavaRebel license, so you may end up launching with JavaRebel configured but without the ability to use it (in which case, JavaRebel will print a notification). 
 
 h2(#gems).  Using Gems
 
@@ -20,7 +132,6 @@ If your build depends on other gems, you will want to specify these dependencies
 
 Use the @build.yaml@ file to specify these dependencies (see "Build Settings":settings_profiles.html#build for more information), for example:
 
-<notextile>
 {% highlight yaml %}
 # This project requires the following gems
 gems: 
@@ -30,7 +141,6 @@ gems:
   - 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.
 
@@ -44,12 +154,10 @@ 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:
 
-<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.
 
@@ -60,7 +168,6 @@ Buildr runs along side a JVM, using either RJB or JRuby.  The Java module allows
 
 Java classes are accessed as static methods on the @Java@ module, for example:
 
-<notextile>
 {% highlight ruby %}
 str = Java.java.lang.String.new('hai!')
 str.toUpperCase
@@ -69,7 +176,6 @@ 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.
 
@@ -77,11 +183,9 @@ When using an artifact specification, Buildr will automatically download and ins
 
 For example, Ant is loaded as follows:
 
-<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.
 
@@ -99,68 +203,56 @@ Buildr provides an addon that allows you start a "dRuby":http://www.ruby-doc.org
 
 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.
+The @dbuildr@ command 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.
+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
 
-<notextile>
 {% highlight sh %}
 $ jruby -S buildr -rbuildr/nailgun nailgun: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 the nailgun client
 installed on @$JRUBY_HOME/tool/nailgun/ng@
 
-<notextile>
 {% highlight sh %}
 $ ng clean compile
 {% endhighlight %}
-</notextile>
 
 
 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.
+For OS X users, Buildr supports "Growl":http://growl.info/ out of the box to send "completed" and "failed" notifications to the user.
 
 For other platforms or if you want to notify the user differently, Buildr offers two extension points:
 
@@ -169,7 +261,6 @@ 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:
 
-<notextile>
 {% highlight ruby %}
 # Send notifications using Qube 
 notify = lambda do |type, title, message|
@@ -188,39 +279,48 @@ 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). Eclipse, IDEA
+h2(#eclipse). Eclipse
 
 If you're using Eclipse, you can generate @.classpath@ and @.project@ from your Buildfile and use them to create a project in your workspace:
 
-<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.
+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 the @artifacts:sources@ task.
 
-To have your libraries' source code available in Eclipse, run:
- 
-<notextile>
-{% highlight sh %}
-$ buildr artifacts:sources
+You may explicitly specify the nature of your project, for example if you are developing an Eclipse plugin:
+
+{% highlight ruby %}
+define 'my-plugin' do
+  eclipse.natures :plugin
+end
 {% endhighlight %}
-</notextile>
 
-If you prefer IntelliJ IDEA, you can always:
+The currently supported natures are @:java@, @:scala@ and @:plugin@.  Buildr will attempts to auto-detect your project type and apply the most relevant settings by default.   If it doesn't or you need something special, you may also explicitly set the nature, container and builders of your project by doing:
+
+{% highlight ruby %}
+define 'custom-plugin' do
+  eclipse.natures 'org.eclipse.pde.PluginNature'
+  eclipse.classpath_containers 'org.eclipse.pde.core.requiredPlugins'
+  eclipse.builders ['org.eclipse.pde.ManifestBuilder', 'org.eclipse.pde.SchemaBuilder']
+end
+{% endhighlight %}
+
+One more thing; these settings are inherited hierarchically so you may set them on a parent project if you want to share them across different projects.
+
+h2(#idea). IntelliJ IDEA
+
+If you use IntelliJ IDEA, you can generate project files by issuing:
 
-<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@).
 
@@ -233,27 +333,22 @@ 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:
+There are two main tasks for each tool, both of which generate a test coverage report in the @reports/cobertura@ (respectively @reports/emma@) directory.  For example:
 
-<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. 
 
-<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:
 
-<notextile>
 {% highlight ruby %}
 define 'someModule' do 
   cobertura.include 'some.package.==*=='
@@ -262,42 +357,47 @@ define 'someModule' do
   cobertura.exclude /==*==.Const(ants)?/i
 end
 {% endhighlight %}
-</notextile>
 
 Emma has @include@ and @exclude@ methods too, but they take glob patterns instead of regexps.
 
+Cobertura also provides a @cobertura:check@ task.  This task is intended to be used as a dependency for other tasks (such as @deploy@) which might wish to fail if coverage is unacceptable.  The respective thresholds for task failure may be defined using the @cobertura.check@ configuration namespace.  For example:
+
+{% highlight ruby %}
+define 'someModule' do
+  cobertura.check.branch_rate = 75
+  cobertura.check.line_rate = 100
+  cobertura.check.total_line_rate = 98
+  
+  task(:deploy).enhance 'cobertura:check'
+end
+{% endhighlight %}
+
+The @cobertura:check@ task supports all of the configuration parameters allowed by the @cobertura-check@ Ant task (as "documented here":http://cobertura.sourceforge.net/anttaskreference.html).  Configuration parameters are "Ruby-ized" (as demonstrated in the example above).
+
 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:
 
-<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:
 
-<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:
 
-<notextile>
-<notextile>
 {% highlight sh %}
 $ buildr --require buildr/jdepend jdepend:swing
 $ buildr -rbuildr/java/cobertura cobertura:html
 {% endhighlight %}
-</notextile>
-</notextile>
 
 
 h2(#anything_ruby). Anything Ruby Can Do
@@ -308,7 +408,6 @@ 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:
 
-<notextile>
 {% highlight ruby %}
 bins = file('target/bin'=>FileList[_('src/main/dist/bin/==*==')]) do |task|
   mkpath task.name
@@ -316,11 +415,9 @@ bins = file('target/bin'=>FileList[_('src/main/dist/bin/==*==')]) do |task|
   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:
 
-<notextile>
 {% highlight ruby %}
 def distro(project, id)
   project.package(:zip, :id=>id).path("#{id}-#{version}").tap do |zip|
@@ -338,22 +435,18 @@ def distro(project, id)
   end
 end
 {% endhighlight %}
-</notextile>
 
 And then use it in the project definition:
 
-<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:
 
-<notextile>
 {% highlight ruby %}
 sources = projects.map { |prj| prj.compile.sources.
   map { |src| FileList["#{src}/**/*.java"] } }.flatten
@@ -361,5 +454,4 @@ 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>
 

data/doc/packaging.textile

@@ -5,29 +5,23 @@ title: Packaging
 
 For our next trick, we're going to try and create an artifact ourselves.  We're going to start with:
 
-<notextile>
 {% highlight ruby %}
 package :jar
 {% endhighlight %}
-</notextile>
 
 We just told the project to create a JAR file in the @target@ directory, including all the classes (and resources) that we previously compiled into @target/classes@.  Or we can create a WAR file:
 
-<notextile>
 {% highlight ruby %}
 package :war
 {% endhighlight %}
-</notextile>
 
 The easy case is always easy, but sometimes we have more complicated use cases which we'll address through the rest of this section.
 
 Now let's run the build, test cases and create these packages:
 
-<notextile>
 {% highlight sh %}
 $ buildr package
 {% endhighlight %}
-</notextile>
 
 The @package@ task runs the @build@ task (remember: @compile@ and @test@) and then runs each of the packaging tasks, creating packages in the projects' target directories.
 
@@ -38,12 +32,10 @@ h2(#referencing). Specifying And Referencing Packages
 
 Buildr supports several packaging types, and so when dealing with packages, you have to indicate the desired package type.  The packaging type can be the first argument, or the value of the @:type@ argument.  The following two are equivalent:
 
-<notextile>
 {% highlight ruby %}
 package :jar
 package :type=>:jar
 {% endhighlight %}
-</notextile>
 
 If you do not specify a package type, Buildr will attempt to infer one.
 
@@ -51,11 +43,9 @@ In the documentation you will find a number of tasks dealing with specific packa
 
 To package a particular file, use the @:file@ argument, for example:
 
-<notextile>
 {% highlight ruby %}
 package :zip, :file=>_('target/interesting.zip')
 {% endhighlight %}
-</notextile>
 
 This returns a file task that will run as part of the project's @package@ task (generating all packages).  It will invoke the @build@ task to generate any necessary prerequisites, before creating the specified file.
 
@@ -65,7 +55,6 @@ Most often you will want to use the second form to generate packages that are al
 
 The artifact specification is based on the project name (using dashes instead of colons), group identifier and version number, all three obtained from the project definition.  You can specify different values using the @:id@, @:group@, @:version@ and @:classifier@ arguments.  For example:
 
-<notextile>
 {% highlight ruby %}
 define 'killer-app', :version=>'1.0' do
   # Generates silly-1.0.jar
@@ -82,7 +71,6 @@ define 'killer-app', :version=>'1.0' do
   end
 end
 {% endhighlight %}
-</notextile>
 
 The file name is determined from the identifier, version number, classifier and extension associated with that packaging type.
 
@@ -92,12 +80,10 @@ A single project can create multiple packages.  For example, a Java project may
 
 You can use the @packages@ method to obtain a list of all packages defined in the project, for example:
 
-<notextile>
 {% highlight ruby %}
 project('killer-app:teh-impl').packages.first
 project('killer-app:teh-impl').packages.select { |pkg| pkg.type == :zip }
 {% endhighlight %}
-</notextile>
 
 
 h2(#zip). Packaging ZIPs
@@ -106,41 +92,33 @@ ZIP is the most common form of packaging, used by default when no other packagin
 
 Let's start by including additional files in the ZIP package.  We're going to include the @target/docs@ directory and @README@ file:
 
-<notextile>
 {% highlight ruby %}
 package(:zip).include _('target/docs'), 'README'
 {% endhighlight %}
-</notextile>
 
 The @include@ method accepts files, directories and file tasks.  You can also use file pattern to match multiple files and directories.  File patterns include asterisk (@*@) to match any file name or part of a file name, double asterisk (@**@) to match directories recursively, question mark (@?@) to match any character, square braces (@[]@) to match a set of characters, and curly braces (@{}@) to match one of several names.
 
 And the same way you @include@, you can also @exclude@ specific files you don't want showing up in the ZIP.  For example, to exclude @.draft@ and @.raw@ files:
 
-<notextile>
 {% highlight ruby %}
 package(:zip).include('target/docs').
   exclude('target/docs/**/*.{draft,raw}')
 {% endhighlight %}
-</notextile>
 
 So far we've included files under the root of the ZIP.  Let's include some files under a given path using the @:path@ option:
 
-<notextile>
 {% highlight ruby %}
 package(:zip).include 'target/docs', :path=>"#{id}-#{version}"
 {% endhighlight %}
-</notextile>
 
 If you need to use the @:path@ option repeatedly, consider using the @tap@ method instead.  For example:
 
-<notextile>
 {% highlight ruby %}
 package(:zip).path("#{id}-#{version}").tap do |path|
   path.include 'target/docs'
   path.include 'README'
 end
 {% endhighlight %}
-</notextile>
 
 p(tip). The @tap@ method is not part of the core library, but a very useful extension.  It takes an object, yields to the block with that object, and then returns that object.
 
@@ -148,20 +126,16 @@ p(note). To allow you to spread files across different paths, the include/exclud
 
 If you need to include a file or directory under a different name, use the @:as@ option.  For example:
 
-<notextile>
 {% highlight ruby %}
 package(:zip).include('corporate-logo-350x240.png', :as=>'logo.png')
 {% endhighlight %}
-</notextile>
 
 You can also use @:as=>'.'@ to include all files from the given directory.  For example:
 
-<notextile>
 {% highlight ruby %}
 package(:zip).include 'target/docs/*'
 package(:zip).include 'target/docs', :as=>'.'
 {% endhighlight %}
-</notextile>
 
 These two are almost identical.  They both include all the files from the @target/docs@ directory, but not the directory itself.  But they operate differently.  The first line expands to include all the files in @target/docs@. If you don't already have files in @target/docs@, well, then it won't do anything interesting.  Your ZIP will come up empty.  The second file includes the directory itself, but strips the path during inclusion.  You can define it now, create these files later, and then ZIP them all up.
 
@@ -171,20 +145,16 @@ If you need to get rid of all the included files, call the @clean@ method. Some
 
 You can also merge two ZIP files together, expanding the content of one ZIP into the other.  For example:
 
-<notextile>
 {% highlight ruby %}
 package(:zip).merge 'part1.zip', 'part2.zip'
 {% endhighlight %}
-</notextile>
 
 If you need to be more selective, you can apply the include/exclude pattern to the expanded ZIP.  For example:
 
-<notextile>
 {% highlight ruby %}
 # Everything but the libs
 package(:zip).merge('bigbad.war').exclude('libs/**/*')
 {% endhighlight %}
-</notextile>
 
 
 h2(#jar). Packaging JARs
@@ -193,19 +163,15 @@ JAR packages extend ZIP packages with support for Manifest files and the META-IN
 
 You can tell the JAR package to include a particular Manifest file:
 
-<notextile>
 {% highlight ruby %}
 package(:jar).with :manifest=>_('src/main/MANIFEST.MF')
 {% endhighlight %}
-</notextile>
 
 Or generate a manifest from a hash:
 
-<notextile>
 {% highlight ruby %}
 package(:jar).with :manifest=>{ 'Copyright'=>'Acme Inc (C) 2007' }
 {% endhighlight %}
-</notextile>
 
 You can also generate a JAR with no manifest with the value @false@, create a manifest with several sections using an array of hashes, or create it from a proc.
 
@@ -213,37 +179,29 @@ In large projects, where all the packages use the same manifest, it's easier to
 
 For example, we can get the same result by specifying this at the top project:
 
-<notextile>
 {% highlight ruby %}
 manifest['Copyright'] = 'Acme Inc (C) 2007'
 {% endhighlight %}
-</notextile>
 
 If you need to mix-in the project's manifest with values that only one package uses, you can do so easily:
 
-<notextile>
 {% highlight ruby %}
 package(:jar).with :manifest=>manifest.merge('Main-Class'=>'com.acme.Main')
 {% endhighlight %}
-</notextile>
 
 If you need to include more files in the @META-INF@ directory, you can use the @:meta_inf@ option.  You can give it a file, or array of files.  And yes, there is a @meta_inf@ project property you can set once to include the same set of file in all the JARs.  It works like this:
 
-<notextile>
 {% highlight ruby %}
 meta_inf << file('DISCLAIMER') << file('NOTICE')
 {% endhighlight %}
-</notextile>
 
 If you have a @LICENSE@ file, it's already included in the @meta_inf@ list of files.
 
 Other than that, @package :jar@ includes the contents of the compiler's target directory and resources, which most often is exactly what you intend it to do. If you want to include other files in the JAR, instead or in addition, you can do so using the @include@ and @exclude@ methods.  If you do not want the target directory included in your JAR, simply call the @clean@ method on it:
 
-<notextile>
 {% highlight ruby %}
 package(:jar).clean.include( only_these_files )
 {% endhighlight %}
-</notextile>
 
 
 h2(#war). Packaging WARs
@@ -254,25 +212,20 @@ Without much prompting, @package :war@ picks the contents of the @src/main/webap
 
 Again, you can use the @include@ and @exclude@ methods to change the contents of the WAR.  There are two convenience options you can use to make the more common changes.  If you need to include a classes directory other than the default:
 
-<notextile>
 {% highlight ruby %}
 package(:war).with :classes=>_('target/additional')
 {% endhighlight %}
-</notextile>
 
 If you want to include a different set of libraries other than the default:
 
-<notextile>
 {% highlight ruby %}
 package(:war).with :libs=>MYSQL_JDBC
 {% endhighlight %}
-</notextile>
 
 Both options accept a single value or an array.  The @:classes@ option accepts the name of a directory containing class files, initially set to @compile.target@ and @resources.target@.  The @:libs@ option accepts artifact specifications, file names and tasks, initially set to include everything in @compile.dependencies@.
 
 As you can guess, the package task has two attributes called @classes@ and @libs@; the @with@ method merely sets their value.  If you need more precise control over these arrays, you can always work with them directly, for example:
 
-<notextile>
 {% highlight ruby %}
 # Add an artifact to the existing set:
 package(:war).libs += artifacts(MYSQL_JDBC)
@@ -282,19 +235,16 @@ package(:war).libs -= artifacts(LOG4J)
 puts 'Artifacts included in WAR package:'
 puts package(:war).libs.map(&:to_spec)
 {% endhighlight %}
-</notextile>
 
 
 h2(#aar). Packaging AARs
 
 Axis2 service archives are similar to JAR's (compiled classes go into the root of the archive) but they can embed additional libraries under /lib and include @services.xml@ and WSDL files.
 
-<notextile>
 {% highlight ruby %}
 package(:aar).with(:libs=>'log4j:log4j:jar:1.1')
 package(:aar).with(:services_xml=>_('target/services.xml'), :wsdls=>_('target/*.wsdl'))
 {% endhighlight %}
-</notextile>
 
 The @libs@ attribute is a list of .jar artifacts to be included in the archive under /lib.  The default is no artifacts; compile dependencies are not included by default.
 
@@ -304,7 +254,6 @@ The @wsdls@ attribute is a collection of file names or glob patterns for WSDL fi
 
 If you already have WSDL files in the @src/main/axis2@ directory but would like to perform some filtering, for example, to set the HTTP port number, consider ignoring the originals and including only the filtered files, for example:
 
-<notextile>
 {% highlight ruby %}
 # Host name depends on environment.
 host = ENV['ENV'] == 'test' ? 'test.host' : 'ws.example.com'
@@ -313,7 +262,6 @@ filter.from('src/main/axis2').into('target').
 package(:aar).wsdls.clear
 package(:aar).with(:services_xml=>_('target/services.xml'), :wsdls=>_('target/==*==.wsdl'))
 {% endhighlight %}
-</notextile>
 
 
 h2(#ear).  Packaging EARs
@@ -330,18 +278,15 @@ EAR packages support four component types:
 
 This example shows two ways for adding components built by other projects:
 
-<notextile>
 {% highlight ruby %}
 package(:ear) << project('coolWebService').package(:war)
 package(:ear).add project('commonLib') # By default, the JAR package
 {% endhighlight %}
-</notextile>
 
 Adding a WAR package assumes it's a WAR component and treats it as such, but JAR packages can be any of three component types, so by default they are all treated as shared libraries.  If you want to add an EJB or Application Client component, you need to say so explicitly, either passing @:type=>package@, or by passing the component type in the @:type@ option.
 
 Here are three examples:
 
-<notextile>
 {% highlight ruby %}
 # Assumed to be a shared library.
 package(:ear).add 'org.springframework:spring:jar:2.6'
@@ -350,13 +295,11 @@ package(:ear).add :ejb=>project('beanery')
 # Adding component with specific package type.
 package(:ear).add project('client'), :type=>:jar
 {% endhighlight %}
-</notextile>
 
 By default, WAR components are all added under the @/war@ path, and likewise, EJB components are added under the @/ejb@ path, shared libraries under @/lib@ and Application Client components under @/jar@.
 
 If you want to place components in different locations you can do so using the @:path@ option, or by specifying a different mapping between component types and their destination directory.  The following two examples are equivalent:
 
-<notextile>
 {% highlight ruby %}
 # Specify once per component.
 package(:ear).add project('coolWebService').package(:war), :path=>'coolServices'
@@ -364,7 +307,6 @@ package(:ear).add project('coolWebService').package(:war), :path=>'coolServices'
 package(:ear).dirs[:war] = 'coolServices'
 package(:ear) << project('coolWebService').package(:war)
 {% endhighlight %}
-</notextile>
 
 EAR packages include an @application.xml@ file in the @META-INF@ directory that describes the application and its components.  This file is created for you during packaging, by referencing all the components added to the EAR.  There are a couple of things you will typically want to change.
 
@@ -374,12 +316,10 @@ EAR packages include an @application.xml@ file in the @META-INF@ directory that
 
 Again, by example:
 
-<notextile>
 {% highlight ruby %}
 package(:ear).display_name = 'MyCoolWebService'
 package(:ear).add project('coolWebService').package(:war), :context-root=>'coolness'
 {% endhighlight %}
-</notextile>
 
 If you need to disable the context root (e.g. for Portlets), set @context_root@ to @false@.
 
@@ -388,12 +328,10 @@ h2(#tar).  Packaging Tars and GZipped Tars
 
 Everything you know about working with ZIP files translates to Tar files, the two tasks are identical in more respect, so here we'll just go over the differences.
 
-<notextile>
 {% highlight ruby %}
 package(:tar).include _('target/docs'), 'README'
 package(:tgz).include _('target/docs'), 'README'
 {% endhighlight %}
-</notextile>
 
 The first line creates a Tar archive with the extension @.tar@, the second creates a GZipped Tar archive with the extension @.tgz@.
 
@@ -406,35 +344,27 @@ You can bring in the artifacts you need from remote repositories and install the
 
 So let's create these packages and install them in the local repository where other projects can access them:
 
-<notextile>
 {% highlight sh %}
 $ buildr install
 {% endhighlight %}
-</notextile>
 
 If you changes your mind you can always:
 
-<notextile>
 {% highlight sh %}
 $ buildr uninstall
 {% endhighlight %}
-</notextile>
 
 That works between projects you build on the same machine.  Now let's share these artifacts with other developers through a remote repository:
 
-<notextile>
 {% highlight sh %}
 $ buildr upload
 {% endhighlight %}
-</notextile>
 
 Of course, you'll need to tell Buildr about the release server:
 
-<notextile>
 {% highlight ruby %}
 repositories.release_to = 'sftp://john:secret@release/usr/share/repo'
 {% endhighlight %}
-</notextile>
 
 This example uses the SFTP protocol.  In addition, you can use the HTTP protocol -- Buildr supports HTTP and HTTPS, Basic Authentication and uploads using PUT -- or point to a directory on your file system.
 
@@ -442,7 +372,6 @@ The URL in this example contains the release server ("release"), path to reposit
 
 Of course, you'll want to specify the release server URL in the Buildfile, but leave the username/password settings private in your local @buildr.rb@ file. Let's break up the release server settings:
 
-<notextile>
 {% highlight ruby %}
 # build.rb, loaded first
 repositories.release_to[:username] = 'john'
@@ -451,13 +380,11 @@ repositories.release_to[:password] = 'secret'
 # Buildfile, loaded next
 repositories.release_to[:url] = 'sftp://release/usr/share/repo'
 {% endhighlight %}
-</notextile>
 
 The @upload@ task takes care of uploading all the packages created by your project, along with their associated POM files and MD5/SHA1 signatures (Buildr creates these for you).
 
 If you need to upload other files, you can always extend the @upload@ task and use @repositories.release_to@ in combination with @URI.upload@.  You can also extend it to upload to different servers, for example, to publish the documentation and test coverage reports to your site:
 
-<notextile>
 {% highlight ruby %}
 # We'll let some other task decide how to create 'docs'
 task 'upload'=>'docs' do
@@ -465,48 +392,39 @@ task 'upload'=>'docs' do
   uri.upload file('docs')
 end
 {% endhighlight %}
-</notextile>
 
 
 h2(#source_javadoc). Packaging Sources and JavaDocs
 
 IDEs can take advantage of source packages to help you debug and trace through compiled code.  We'll start with a simple example:
 
-<notextile>
 {% highlight ruby %}
 package :sources
 {% endhighlight %}
-</notextile>
 
 This one creates a ZIP package with the classifier "sources" that will contain all the source directories in that project, typically @src/main/java@, but also other sources generated from Apt, JavaCC, XMLBeans and friends.
 
 You can also generate a ZIP package with the classifier "javadoc" that contains the JavaDoc documentation for the project.  It uses the same set of documentation files generated by the project's @javadoc@ task, so you can use it in combination with the @javadoc@ method.  For example:
 
-<notextile>
 {% highlight ruby %}
 package :javadoc
 javadoc :windowtitle=>'Buggy but Works'
 {% endhighlight %}
-</notextile>
 
 By default Buildr picks the project's description for the window title.
 
 You can also tell Buildr to automatically create sources and JavaDoc packages in all the sub-projects that have any source files to package or document. Just add either or both of these methods in the top-level project:
 
-<notextile>
 {% highlight ruby %}
 package_with_sources
 package_with_javadoc
 {% endhighlight %}
-</notextile>
 
 You can also tell it to be selective using the @:only@ and @:except@ options.
 For example:
 
-<notextile>
 {% highlight ruby %}
 package_with_javadoc :except=>'la-web'
 {% endhighlight %}
-</notextile>
 
 We packaged the code, but will it actually work? Let's see "what the tests say":testing.html.