buildr 1.2.10 → 1.3.0

data/doc/pages/index.textile

@@ -0,0 +1,63 @@
+h1. Welcome
+
+Buildr is a build system for Java applications.  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 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?
+
+
+h2.  News
+
+Check out "all that's new in Buildr 1.3":whats_new.html.
+
+* Buildr 1.3 now runs on JRuby 1.1
+* Support for building Scala projects
+* Support for building Groovy projects
+* EAR packages
+* Behaviour-Driven Development frameworks
+* Profiles
+* New API for accessing Java libraries
+* Alternative source layouts
+* More documentation
+* Other features and bug fixes.
+
+
+h2.  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.
+
+Apache Buildr is an effort undergoing incubation at The Apache Software
+Foundation (ASF), sponsored by the Apache Incubator. Incubation is required of
+all newly accepted projects until a further review indicates that the
+infrastructure, communications, and decision making process have stabilized in
+a manner consistent with other successful ASF projects. While incubation status
+is not necessarily a reflection of the completeness or stability of the code,
+it does indicate that the project has yet to be fully endorsed by the ASF.
+
+"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/mailing_lists.textile

@@ -0,0 +1,17 @@
+h1. Mailing Lists
+
+
+|_. buildr-user |_. For developers working with Buildr |
+| Post          | "buildr-user@incubator.apache.org":mailto:buildr-user@incubator.apache.org |
+| Browse        | "buildr-user archives":http://mail-archives.apache.org/mod_mbox/incubator-buildr-user/ |
+| Subscribe     | "buildr-user-subscribe@incubator.apache.org":mailto:buildr-user-subscribe@incubator.apache.org |
+| Unsubscribe   | "buildr-user-unsubscribe@incubator.apache.org":mailto:buildr-user-unsubscribe@incubator.apache.org |
+|_. buildr-dev |_. For development of Buildr itself |
+| Post          | "buildr-dev@incubator.apache.org":mailto:buildr-dev@incubator.apache.org |
+| Browse        | "buildr-dev archives":http://mail-archives.apache.org/mod_mbox/incubator-buildr-dev/ |
+| Subscribe     | "buildr-dev-subscribe@incubator.apache.org":mailto:buildr-dev-subscribe@incubator.apache.org |
+| Unsubscribe   | "buildr-dev-unsubscribe@incubator.apache.org":mailto:buildr-dev-unsubscribe@incubator.apache.org |
+|_. buildr-commits |_. Commit messages and JIRA status |
+| Subscribe     | "buildr-commits-subscribe@incubator.apache.org":mailto:buildr-commits-subscribe@incubator.apache.org |
+| Unsubscribe   | "buildr-commits-unsubscribe@incubator.apache.org":mailto:buildr-commits-unsubscribe@incubator.apache.org |
+| Browse        | "buildr-commits archives":http://mail-archives.apache.org/mod_mbox/incubator-buildr-commits/ |

data/doc/pages/more_stuff.textile

@@ -0,0 +1,367 @@
+h1. More Stuff
+
+
+h2.  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.
+
+There are several mechanisms for developing extensions and build features
+across projects which we cover in more details in the section "Extending
+Buildr":extending.html.  Here we will talk about using extensions that are
+distributed in the form of RubyGems.
+
+"RubyGems":http://rubygems.rubyforge.org provides the @gem@ command line tool
+that you can use to search, install, upgrade, package and distribute gems. It
+installs all gems into a local repository that is shared across your builds and
+all other Ruby applications you may have running.  You can install a gem from a
+local file, or download and install it from any number of remote repositories.
+
+RubyGems is preconfigured to use the "RubyForge":http://rubyforge.org
+repository.  You'll find a large number of open source Ruby libraries there,
+including Buildr itself and all its dependencies.  RubyForge provides a free
+account that you can use to host your projects and distribute your gems (you
+can use RubyForge strictly for distribution, as we do with Buildr).
+
+You can also set up your own private repository and use it instead or in
+addition to RubyForge.  Use the @gem sources@ command to add repositories, and
+the @gem server@ command to run a remote repository.  You can see all available
+options by running @gem help@.
+
+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:
+
+{{{!yaml
+# This project requires the following gems
+gems: 
+  # Suppose we want to notify developers when testcases fail.
+  - buildr-twitter-notifier-addon >=1
+  # we test with ruby mock objects
+  - mocha
+  - ci_reporter
+}}}
+
+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.
+
+Since this step requires your input, it will only happen when running Buildr
+interactively from the command line.  In all other cases, Buildr will fail and
+report the missing dependencies.  If you have an automated build environment,
+make sure to run the build once manually to install all the necessary
+dependencies.
+
+When installing a gem for the first time, Buildr will automatically look for
+the latest available version.  You can specify a particular version number, or
+a set of version numbers known to work with that build.  You can use equality
+operations to specify a range of versions, for example, @1.2.3@ to install only
+version 1.2.3, and @=> 1.2.3@ to install version 1.2.3 or later.
+
+You can also specify a range up to one version bump, for example, @~> 1.2.3@ is
+the same as @>= 1.2.3 < 1.3.0@, and @~> 1.2@ is the same as @>= 1.2.0 < 2.0.0@.
+If necessary, you can exclude a particular version number, for example, @~>
+1.2.3 != 1.2.7@.
+
+Buildr will install the latest version that matches the version requirement.
+To keep up with newer versions, execute the @gem update@ command periodically.
+You can also use @gem outdated@ to determine which new versions are available.
+
+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
+$ ri Buildr::Jetty
+$ ri Buildr::Jetty.start
+}}}
+
+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
+
+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
+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)
+}}}
+
+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.
+
+When using an artifact specification, Buildr will automatically download and
+install the artifact before adding it to the classpath.
+
+For example, Ant is loaded as follows:
+
+{{{!ruby
+Java.classpath << 'org.apache.ant:ant:jar:1.7.0'
+}}}
+
+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.
+
+When building an extension, make sure to follow these rules:
+
+# Add to the @classpath@ when the extension is loaded (i.e. in module or class
+definition), so the first call to @Java.load@ anywhere in the code will include
+the libraries you specify.
+# Call @Java.load@ once before accessing any Java classes, allowing Buildr to
+set up the classpath.
+# Only call @Java.load@ when invoked, otherwise you may end up loading the JVM
+with a partial classpath, or before all remote repositories are listed.
+# Check on a clean build with empty local repository.
+
+
+h2. 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.
+
+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. 
+
+Start the BuildrServer by executing
+
+{{{!ruby
+$ jruby -S buildr -rbuildr/nailgun nailgun:start
+}}}
+
+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:
+
+{{{!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
+}}}
+
+Some nailgun tasks have been provided to manage the cached runtimes, 
+to get an overview of them execute the @nailgun:tasks@ task.
+
+Be sure to read the nailgun help by executing the @nailgun:help@ task.
+
+
+h2. 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
+$ buildr eclipse
+}}}
+
+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 prefer IntelliJ IDEA, you can always:
+
+{{{!sh
+$ buildr idea
+}}}
+
+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@).
+
+If you're using IDEA 7 or later, use the @buildr idea7x@ task instead.  This
+task creates the proper @.ipr@ and @.iml@ files for IDEA version 7.  It
+includes the @-7x@ suffix in the generated files, so you can use the @idea@ and
+@idea7x@ tasks side by side on the same project.
+
+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, JDepend
+
+You can use "Cobertura":http://cobertura.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, both of which generate a test coverage report in the
+@reports/cobertura@ directory.  For example:
+
+{{{!sh
+$ buildr test cobertura:html
+}}}
+
+As you can guess, the other task is @cobertura:xml@.
+
+If you want to generate cobertura reports only for a specific project, you
+can do so by using the project name as prefix to cobertura tasks. 
+
+{{{!sh
+$ buildr subModule:cobertura:html
+}}}
+
+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
+define 'someModule' do 
+  cobertura.include 'some.package.*'
+  cobertura.include /some.(foo|bar).*/
+  cobertura.exclude 'some.foo.util.SimpleUtil'
+  cobertura.exclude /*.Const(ants)?/i
+end
+}}}
+
+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
+$ buildr jdepend:swing
+}}}
+
+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 either one, you need to
+require it explicitly.  The proper way to do it in Ruby:
+
+{{{!ruby
+require 'buildr/cobertura'
+require 'buildr/jdepend'
+}}}
+
+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 two likes 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
+$ buildr --require buildr/jdepend jdepend:swing
+$ buildr -rbuildr/cobertura cobertura:html
+}}}
+
+
+h2. 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".
+
+We already showed you one example where Ruby could help.  You can use Ruby to
+manage dependency by setting constants and reusing them, grouping related
+dependencies into arrays and structures.
+
+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|
+  mkpath task.name
+  cp task.prerequisites, task.name
+  chmod 0755, FileList[task.name + '/*.sh'], :verbose=>false
+end
+}}}
+
+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
+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.merge project('ode:tools-bin').package(:zip)
+    zip.path('lib').include artifacts(COMMONS.logging, COMMONS.codec,
+      COMMONS.httpclient, COMMONS.pool, COMMONS.collections, JAXEN, SAXON,
+      LOG4J, WSDL4J, XALAN, XERCES)
+    project('ode').projects('utils', 'tools', 'bpel-compiler', 'bpel-api',
+      'bpel-obj', 'bpel-schemas').map(&:packages).flatten.each do |pkg|
+        zip.include(pkg.to_s, :as=>"#{pkg.id}.#{pkg.type}", :path=>'lib')
+      end
+    yield zip
+  end
+end
+}}}
+
+And then use it in the project definition:
+
+{{{!ruby
+define 'distro-axis2' do
+  parent.distro(self, "#{parent.id}-war") { |zip|
+    zip.include project('ode:axis2-war').package(:war), :as=>'ode.war' }
+end
+}}}
+
+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
+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"
+}}}
+
+

data/doc/pages/packaging.textile

@@ -0,0 +1,592 @@
+h1. Packaging
+
+For our next trick, we're going to try and create an artifact ourselves.  We're
+going to start with:
+
+{{{!ruby
+package :jar
+}}}
+
+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:
+
+{{{!ruby
+package :war
+}}}
+
+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:
+
+{{{!sh
+$ buildr package
+}}}
+
+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.
+
+p(tip). The @package@ task and @package@ methods are related, but that relation is
+different from other task/method pairs.  The @package@ method creates a file
+task that points to the package in the @target@ directory and knows how to
+create it.  It then adds itself as a prerequisite to the @package@ task.
+Translation: you can create multiple packages from the same project.
+
+
+h2. 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:
+
+{{{!ruby
+package :jar
+package :type=>:jar
+}}}
+
+If you do not specify a package type, Buildr will attempt to infer one.
+
+In the documentation you will find a number of tasks dealing with specific
+packaging types (@ZipTask@, @JarTask@, etc).  The @package@ method is a
+convenience mechanism that sets up the package for you associates it with
+various project life cycle tasks.
+
+To package a particular file, use the @:file@ argument, for example:
+
+{{{!ruby
+package :zip, :file=>_('target/interesting.zip')
+}}}
+
+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.
+
+The package type does not have to be the same as the file name extension, but
+if you don't specify the package type, it will be inferred from the extension.
+
+Most often you will want to use the second form to generate packages that are
+also artifacts.  These packages have an artifact specification, which you can
+use to reference them from other projects (and buildfiles).  They are also
+easier to share across projects: artifacts install themselves in the local
+repository when running the @install@ task, and upload to the remote repository
+when running the @upload@ task (see "Installing and
+Uploading":#installing_and_uploading).
+
+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:
+
+{{{!ruby
+define 'killer-app', :version=>'1.0' do
+  # Generates silly-1.0.jar
+  package :jar, :id=>'silly'
+
+  # Generates killer-app-la-web-1.x.war
+  project 'la-web' do
+    package :war, :version=>'1.x'
+  end
+
+  # Generates killer-app-the-api-1.0-sources.zip
+  project 'teh-api' do
+    package :zip, :classifier=>'sources'
+  end
+end
+}}}
+
+The file name is determined from the identifier, version number, classifier and
+extension associated with that packaging type.
+
+If you do not specify the packaging type, Buildr attempt to infer it from the
+project definition.  In the general case it will use the default packaging
+type, ZIP.  A project that compiles Java classes will default to JAR packaging;
+for other languages, consult the specific documentation.
+
+A single project can create multiple packages.  For example, a Java project may
+generate a JAR package for the runtime library and another JAR containing just
+the API; a ZIP file for the source code and another ZIP for the documentation.
+Make sure to always call @package@ with enough information to identify the
+specific package you are referencing.  Even if the project only defines a
+single package, calling the @package@ method with no arguments does not
+necessarily refer to that one.
+
+You can use the @packages@ method to obtain a list of all packages defined in
+the project, for example:
+
+{{{!ruby
+project('killer-app:teh-impl').packages.first
+project('killer-app:teh-impl').packages.select { |pkg| pkg.type == :zip }
+}}}
+
+
+h2. Packaging ZIPs
+
+ZIP is the most common form of packaging, used by default when no other
+packaging type applies.  It also forms the basis for many other packaging types
+(e.g. JAR and WAR).  Most of what you'll find here applies to other packaging
+types.
+
+Let's start by including additional files in the ZIP package.  We're going to
+include the @target/docs@ directory and @README@ file:
+
+{{{!ruby
+package(:zip).include _('target/docs'), 'README'
+}}}
+
+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:
+
+{{{!ruby
+package(:zip).include('target/docs').
+  exclude('target/docs/**/*.{draft,raw}')
+}}}
+
+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:
+
+{{{!ruby
+package(:zip).include 'target/docs', :path=>"#{id}-#{version}"
+}}}
+
+If you need to use the @:path@ option repeatedly, consider using the @tap@
+method instead.  For example:
+
+{{{!ruby
+package(:zip).path("#{id}-#{version}").tap do |path|
+  path.include 'target/docs'
+  path.include 'README'
+end
+}}}
+
+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.
+
+p(note). To allow you to spread files across different paths, the
+include/exclude patterns are specific to a path.  So in the above example, if
+you want to exclude some files from the "target/docs" directory, make sure to
+call @exclude@ on the path, not on the ZIP task itself.
+
+If you need to include a file or directory under a different name, use the
+@:as@ option.  For example:
+
+{{{!ruby
+package(:zip).include('corporate-logo-350x240.png', :as=>'logo.png')
+}}}
+
+You can also use @:as=>'.'@ to include all files from the given directory.  For
+example:
+
+{{{!ruby
+package(:zip).include 'target/docs/*'
+package(:zip).include 'target/docs', :as=>'.'
+}}}
+
+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.
+
+For example, when @package :jar@ decides to include all the files from
+@target/classes@, it's still working on the project definition, and has yet to
+compile anything.  Since @target/classes@ may be empty, may not even exist, it
+uses @:as=>'.'@.
+
+If you need to get rid of all the included files, call the @clean@ method.
+Some packaging types default to adding various files and directories, for
+example, JAR packaging will include all the compiled classes and resources.
+
+You can also merge two ZIP files together, expanding the content of one ZIP
+into the other.  For example:
+
+{{{!ruby
+package(:zip).merge 'part1.zip', 'part2.zip'
+}}}
+
+If you need to be more selective, you can apply the include/exclude pattern to
+the expanded ZIP.  For example:
+
+{{{!ruby
+# Everything but the libs
+package(:zip).merge('bigbad.war').exclude('libs/**/*')
+}}}
+
+
+h2. Packaging JARs
+
+JAR packages extend ZIP packages with support for Manifest files and the
+META-INF directory.  They also default to include the class files found in the
+@target/classes@ directory.
+
+You can tell the JAR package to include a particular Manifest file:
+
+{{{!ruby
+package(:jar).with :manifest=>_('src/main/MANIFEST.MF')
+}}}
+
+Or generate a manifest from a hash:
+
+{{{!ruby
+package(:jar).with :manifest=>{ 'Copyright'=>'Acme Inc (C) 2007' }
+}}}
+
+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.
+
+In large projects, where all the packages use the same manifest, it's easier to
+set it once on the top project using the @manifest@ project property.
+Sub-projects inherit the property from their parents, and the @package@ method
+uses that property if you don't override it, as we do above.
+
+For example, we can get the same result by specifying this at the top project:
+
+{{{!ruby
+manifest['Copyright'] = 'Acme Inc (C) 2007'
+}}}
+
+If you need to mix-in the project's manifest with values that only one package
+uses, you can do so easily:
+
+{{{!ruby
+package(:jar).with :manifest=>manifest.merge('Main-Class'=>'com.acme.Main')
+}}}
+
+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:
+
+{{{!ruby
+meta_inf << file('DISCLAIMER') << file('NOTICE')
+}}}
+
+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:
+
+{{{!ruby
+package(:jar).clean.include( only_these_files )
+}}}
+
+
+h2. Packaging WARs
+
+Pretty much everything you know about JARs works the same way for WARs, so
+let's just look at the differences.
+
+Without much prompting, @package :war@ picks the contents of the
+@src/main/webapp@ directory and places it at the root of the WAR, copies the
+compiler target directory into the @WEB-INF/classes@ path, and copies any
+compiled dependencies into the @WEB-INF/libs@ paths.
+
+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:
+
+{{{!ruby
+package(:war).with :classes=>_('target/additional')
+}}}
+
+If you want to include a different set of libraries other than the default:
+
+{{{!ruby
+package(:war).with :libs=>MYSQL_JDBC
+}}}
+
+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:
+
+{{{!ruby
+# Add an artifact to the existing set:
+package(:war).libs += artifacts(MYSQL_JDBC)
+# Remove an artifact from the existing set:
+package(:war).libs -= artifacts(LOG4J)
+# List all the artifacts:
+puts 'Artifacts included in WAR package:'
+puts package(:war).libs.map(&:to_spec)
+}}}
+
+
+h2. 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.
+
+{{{!ruby
+package(:aar).with(:libs=>'log4j:log4j:jar:1.1')
+package(:aar).with(:services_xml=>_('target/services.xml'), :wsdls=>_('target/*.wsdl'))
+}}}
+
+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.
+
+The @services_xml@ attribute points to an Axis2 services configuration file
+called @services.xml@ that will be placed in the @META-INF@ directory inside
+the archive.  The default behavior is to point to the @services.xml@ file in
+the project's @src/main/axis2@ directory.  In the second example above we set
+it explicitly.
+
+The @wsdls@ attribute is a collection of file names or glob patterns for WSDL
+files that get included in the @META-INF@ directory.  In the second example we
+include WSDL files from the @target@ directory, presumably created by an
+earlier build task.  In addition, AAR packaging will include all files ending
+with @.wsdl@ from the @src/main/axis2@ directory.
+
+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:
+
+{{{!ruby
+# Host name depends on environment.
+host = ENV['ENV'] == 'test' ? 'test.host' : 'ws.example.com'
+filter.from('src/main/axis2').into('target').
+  include('services.xml', '*.wsdl').using('http_port'=>'8080', 'http_host'=>host)
+package(:aar).wsdls.clear
+package(:aar).with(:services_xml=>_('target/services.xml'), :wsdls=>_('target/*.wsdl'))
+}}}
+
+
+h2.  Packaging EARs
+
+EAR packaging is slightly different from JAR/WAR packaging.  It's main purpose
+is to package components together, and so it includes special methods for
+handling component inclusion that take care to update application.xml and the
+component's classpath.
+
+EAR packages support four component types:
+
+|_. Argument  |_. Component                     |
+| @:war@      | J2EE Web Application (WAR).     |
+| @:ejb@      | Enterprise Java Bean (JAR).     |
+| @:jar@      | J2EE Application Client (JAR).  |
+| @:lib@      | Shared library (JAR).           |
+
+This example shows two ways for adding components built by other projects:
+
+{{{!ruby
+package(:ear) << project('coolWebService').package(:war)
+package(:ear).add project('commonLib') # By default, the JAR package
+}}}
+
+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:
+
+{{{!ruby
+# Assumed to be a shared library.
+package(:ear).add 'org.springframework:spring:jar:2.6'
+# Component type mapped to package.
+package(:ear).add :ejb=>project('beanery')
+# Adding component with specific package type.
+package(:ear).add project('client'), :type=>:jar
+}}}
+
+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:
+
+{{{!ruby
+# Specify once per component.
+package(:ear).add project('coolWebService').package(:war), :path=>'coolServices'
+# Configure once and apply to all added components.
+package(:ear).dirs[:war] = 'coolServices'
+package(:ear) << project('coolWebService').package(:war)
+}}}
+
+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.
+
+* *display-name* -- The application's display name defaults to the project's
+identifier.  You can change that by setting the @display_name@ attribute.
+
+* *context-root* -- WAR components specify a context root, based on the package
+identifier, for example, "cool-web-1.0.war" will have the context root
+"cool-web".  To specify a different context root, add the WAR package with the
+@context_root@ option.
+
+Again, by example:
+
+{{{!ruby
+package(:ear).display_name = 'MyCoolWebService'
+package(:ear).add project('coolWebService').package(:war), :context-root=>'coolness'
+}}}
+
+If you need to disable the context root (e.g. for Portlets), set @context_root@
+to @false@.
+
+
+h2.  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.
+
+{{{!ruby
+package(:tar).include _('target/docs'), 'README'
+package(:tgz).include _('target/docs'), 'README'
+}}}
+
+The first line creates a Tar archive with the extension @.tar@, the second
+creates a GZipped Tar archive with the extension @.tgz@.
+
+In addition to packaging that includes the archive in the list of
+installed/released files, you can use the method @tar@ to create a @TarTask@.
+This task is similar to @ZipTask@, and introduces the @gzip@ attribute, which
+you can use to tell it whether to create a regular file, or GZip it.  By
+default the attribute it set to true (GZip) if the file name ends with either
+@.gz@ or @.tgz@.
+
+
+h2. Installing and Uploading
+
+You can bring in the artifacts you need from remote repositories and install
+them in the local repositories.  Other projects have the same expectation, that
+your packages be their artifacts.
+
+So let's create these packages and install them in the local repository where
+other projects can access them:
+
+{{{!sh
+$ buildr install
+}}}
+
+If you changes your mind you can always:
+
+{{{!sh
+$ buildr uninstall
+}}}
+
+That works between projects you build on the same machine.  Now let's share
+these artifacts with other developers through a remote repository:
+
+{{{!sh
+$ buildr upload
+}}}
+
+Of course, you'll need to tell Buildr about the release server:
+
+{{{!ruby
+repositories.release_to = 'sftp://john:secret@release/usr/share/repo'
+}}}
+
+We're using the SFTP protocol, currently the only protocol Buildr uses for
+uploads.  The URL contains the release server ("release"), path to repository
+("user/share/repo") and username/password for access.  The way SFTP works, you
+specify the path on the release server, and give the user permissions to create
+directories and files inside the repository.  The file system path is different
+from the path you use to download these artifacts through an HTTP server, and
+starts at the root, not the user's home directory.
+
+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:
+
+{{{!ruby
+# build.rb, loaded first
+repositories.release_to[:username] = 'john'
+repositories.release_to[:password] = 'secret'
+
+# Buildfile, loaded next
+repositories.release_to[:url] = 'sftp://release/usr/share/repo'
+}}}
+
+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:
+
+{{{!ruby
+# We'll let some other task decide how to create 'docs'
+task 'deploy'=>'docs' do
+  uri = URI("sftp://#{username}:#{password}@var/www/docs")
+  uri.upload file('docs')
+end
+}}}
+
+
+h2. 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:
+
+{{{!ruby
+package :sources
+}}}
+
+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:
+
+{{{!ruby
+package :javadoc
+javadoc :windowtitle=>'Buggy but Works'
+}}}
+
+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:
+
+{{{!ruby
+package_with_sources
+package_with_javadoc
+}}}
+
+You can also tell it to be selective using the @:only@ and @:except@ options.
+For example:
+
+{{{!ruby
+package_with_javadoc :except=>'la-web'
+}}}
+
+We packaged the code, but will it actually work? Let's see "what the tests
+say":testing.html.