buildr 1.4.4 → 1.4.5

data/doc/installing.textile

@@ -22,8 +22,6 @@ h2(#linux).  Installing on Linux
 
 *The easy way:* Use this bash script to "install Buildr on Linux":scripts/install-linux.sh.  This script will install the most recent version of Buildr, or if already installed, upgrade to the most recent version.  It will also install Ruby 1.8.6 if not already installed (requires @apt-get@, @yum@ or @urpmi@) and upgrade to RubyGems 1.3.1 or later.
 
-p(note). At this time, the native Ruby-Java Bridge (RJB) does not work very well on Linux with JDK 1.6.  If you get Segmentation Fault errors with JDK 1.6, we recommend switching to JDK 1.5.
-
 <br>
 
 *In details:* To get started you will need a recent version of Ruby, Ruby Gems and build tools for compiling native libraries (@make@, @gcc@ and standard headers).
@@ -41,7 +39,7 @@ On *Ubuntu* you have to install several packages:
 $ sudo apt-get install ruby-full ruby1.8-dev libopenssl-ruby build-essential
 {% endhighlight %}
 
-The Debian package for @rubygems@ will not allow you to install Buildr, so you need to install RubyGems from source:
+If using Ubuntu 9.10 or earlier, the Debian package for @rubygems@ will not allow you to install Buildr, so you need to install RubyGems from source:
 
 {% highlight sh %}
 $ wget http://rubyforge.org/frs/download.php/45905/rubygems-1.3.1.tgz
@@ -61,17 +59,26 @@ To upgrade to a new version or install a specific version:
 
 {% highlight sh %}
 $ sudo env JAVA_HOME=$JAVA_HOME gem update buildr
-$ sudo env JAVA_HOME=$JAVA_HOME gem install buildr -v 1.3.4
+$ sudo env JAVA_HOME=$JAVA_HOME gem install buildr -v 1.4.3
 {% endhighlight %}
 
 
-
 h2(#osx).  Installing on OS X
 
 *The easy way:* Use this script to "install Buildr on OS X":scripts/install-osx.sh.  This script will install the most recent version of Buildr, or if already installed, upgrade to the most recent version.  It will also install Ruby 1.8.6 if not already installed (using MacPorts/Fink) and upgrage RubyGems to 1.3.1 or later.
 
 You need to have the Apple Development Tools installed.  They are available on the Mac OSX installation CD.
 
+p(note). Java Update 3 for Snow Leopard removes header files necessary to compile the native Ruby-Java Bridge (RJB) gem, so installing rjb gem may fail on OS X.  The solution is to install Java for Mac OS X 10.6 Update 3 Developer Package from http://connect.apple.com before @gem install@.
+
+*Using RVM?* If you're not using the built-in ruby on OS X (e.g., if you're using RVM), you'll need to force-install the platform-independent RJB:
+
+{% highlight sh %}
+$ gem install rjb -v 1.3.3 --platform ruby
+{% endhighlight %}
+
+The darwin pre-built binary seems to only work with the built-in ruby.
+
 <br>
 
 *In details:* OS X 10.5 (Leopard) comes with a recent version of Ruby 1.8.6.  You do not need to install a different version of Ruby when running OS X 10.5.
@@ -103,7 +110,6 @@ $ sudo env JAVA_HOME=$JAVA_HOME gem update buildr
 $ sudo env JAVA_HOME=$JAVA_HOME gem install buildr -v 1.3.4
 {% endhighlight %}
 
-
 h2(#windows).  Installing on Windows
 
 *The easy way:*  The easiest way to install Ruby is using the "one-click installer":http://rubyinstaller.rubyforge.org/.  Be sure to install Ruby 1.8.6; support for Ruby 1.9.x is still a work in progress.  Once installed, set the @JAVA_HOME@ environment variable and run @gem install buildr --platform mswin32@.
@@ -182,6 +188,17 @@ $ jruby -S buildr
 
 Run @buildr --version@ from the command line to find which version of Buildr you are using by default.  If you see @(JRuby ...)@, Buildr is running on that version of JRuby.
 
+h2. Using multiple versions of Buildr
+
+Rubygems makes it possible to install several versions of Buildr side-by-side on the same system.  If you want to run a specific version, you can do so by adding the version number between underscores ('_') as the first command-line parameter.  For example,
+
+{% highlight sh %}
+$ buildr _1.3.4_ clean   # runs Buildr v1.3.4
+
+$ buildr _1.4.4_ clean   # runs Buildr v1.4.4
+{% endhighlight %}
+
+p(note). There are two `buildr` executables installed by Rubygems.  One script serves to select the specified (or default) version of Buildr and is typically found under `/usr/bin/buildr` or `/var/lib/gems/1.8/bin/buildr`. The exact location will vary depending on your system.   The other script is the Buildr bootstrap per se and can be found under the specific version of Buildr, e.g, `/var/lib/gems/1.8/gems/buildr-1.4.0/bin/buildr`.   The first script should be on your `PATH`.   The second script should not be called directly and should not be on your `PATH`.
 
 h2(#running). Running Buildr
 

data/doc/mailing_lists.textile

@@ -19,6 +19,10 @@ title: Mailing Lists
 | 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 |
+|_. ci          |_. Continuous integration status |
+| Search        | "http://buildr.markmail.org/search/list:ci":http://buildr.markmail.org/search/list:ci |
+| Subscribe     | "ci-subscribe@buildr.apache.org":mailto:ci-subscribe@buildr.apache.org |
+| Unsubscribe   | "ci-unsubscribe@buildr.apache.org":mailto:ci-unsubscribe@buildr.apache.org |
 
 
 

data/doc/more_stuff.textile

@@ -311,9 +311,13 @@ $ dbuildr clean compile
 
 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.
 
-h2(#growl). Growl, Qube
+h2(#notifications). Notifications: Growl, Libnotify, Qube
 
-For OS X users, Buildr supports "Growl":http://growl.info/ out of the box to send "completed" and "failed" notifications to the user.
+Buildr support sending notifications when the build completes or fails, such as displaying the outcome message in an overlaid window on top of other applications.
+
+For OS X users, Buildr supports "Growl":http://growl.info/ out of the box by using the Ruby Cocoa bindings.
+
+For Debian-based Linux users, Buildr supports notifications via the "notify-send":http://manpages.ubuntu.com/manpages/gutsy/man1/notify-send.1.html command which is part of the "libnotify-bin":"http://packages.debian.org/search?keywords=libnotify-bin" package.  Just make sure `notify-send` is installed and on your path is on your `PATH`.
 
 For other platforms or if you want to notify the user differently, Buildr offers two extension points:
 
@@ -380,15 +384,317 @@ h2(#idea). IntelliJ IDEA
 If you use IntelliJ IDEA, you can generate project files by issuing:
 
 {% highlight sh %}
-$ buildr idea
+$ buildr idea:generate
 {% endhighlight %}
 
-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@).
+This task will generate a @.iml@ file for every project (or subproject) and a @.ipr@ that you can directly open for the root project.
 
-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.
+The generated project files can be removed by issuing:
 
-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.
+{% highlight sh %}
+$ buildr idea:clean
+{% endhighlight %}
+
+The idea task generates the project files based on the settings of each project and idea extension specific settings. The main and test source trees are added to the @.iml@ file for each project as are the respective resource directories. The target and report directories are excluded from the project. If the project files exist on the file system the extension will replace specific component sections in the xml with the generated component configurations.
+
+Dependencies come in two forms. Dependencies on other projects and dependencies on external jars. Dependencies on other projects are added as module dependencies in the @.iml@ while jars are added as regular file dependencies. Dependencies are exported from the @.iml@ file if they are compile dependencies. If a artifact that matches dependency but has a classifier of 'sources' is present then it is configured as the source for the dependency. Note: Use "buildr artifacts:sources" to download the source for dependencies.
+
+h3. Idea Specific Directives
+
+The extension specific settings of sub-projects inherit the parent projects settings unless overwritten.
+
+h4. Project file naming
+
+The extension will use the last element of the projects name when generating the @.ipr@ and @.iml@ files. i.e. A project named "foo" will generate "foo.iml" and "foo.ipr" while a project named "foo:bar" will generate "bar/bar.iml" and no ipr. (The @.ipr@ project files are only generated for the base project). The name can be modified by setting the "ipr.suffix" or "iml.suffix" settings which specifies the suffix appended to the file names. The user can also override the name completely by setting "ipr.id" or "iml.id".
+
+h5. Example: Setting id
+
+{% highlight ruby %}
+define "foo" do
+  ipr.id = "beep"
+  define "bar" do
+    iml.id = "baz"
+  end
+end
+{% endhighlight %}
+
+Will generate:
+
+<pre>
+beep.ipr
+foo.iml
+bar/baz.iml
+</pre>
+
+h5. Example: Setting suffix
+
+{% highlight ruby %}
+define "foo" do
+  ipr.suffix = "-suffix1"
+  iml.suffix = "-suffix2"
+  define "bar"
+end
+{% endhighlight %}
+
+Will generate:
+
+<pre>
+foo-suffix1.ipr
+foo-suffix2.iml
+bar/bar-suffix2.iml
+</pre>
+
+h4. Disabling project file generation
+
+The extension will not generate an iml file for a project if the "project.no_iml" method is invoked. Generation of ipr files can be disabled by invoking the method "project.no_ipr".
+
+h5. Example
+
+{% highlight ruby %}
+define "foo" do
+  project.no_ipr
+  define "bar" do
+    project.no_iml
+  end
+end
+{% endhighlight %}
+
+Will generate:
+
+<pre>
+foo.iml
+</pre>
+
+h4. Disabling generation of content section in .iml file
+
+The extension will not generate a content section in an iml file if the "iml.skip_content!" method is invoked. This can be useful if a project is just exporting dependencies and has no associated source code. This may also be of use in scenarios where the build is repackaging an existing jar with more meta-data or the project is just a container for other projects.
+
+h5. Example
+
+{% highlight ruby %}
+define "foo" do
+  iml.skip_content!
+end
+{% endhighlight %}
+
+h4. VCS Integration
+
+The extension will attempt to guess the VCS type of the project by looking for a @.svn@ or @.git@ directory in the base projects directory. If either of these are set it will configure the component as appropriate. Otherwise the user will need to manually specify the project to one of either 'Git' or 'svn' using the ipr.vcs setting.
+
+h5. Example
+
+{% highlight ruby %}
+define "foo" do
+  ipr.vcs = 'Git'
+end
+{% endhighlight %}
+
+h4. Adding main, test or exclude paths to the .iml file
+
+The extension allows you to add source paths, test source paths or add paths to the excluded set by modifying the "iml.main_source_directories", "iml.test_source_directories" or "iml.excluded_directories" settings respectively. This is only needed when the defaults inherited from project.compile or project.test are not sufficient.
+
+h5. Example
+
+{% highlight ruby %}
+define "foo" do
+  # Add path for generated resources to .iml file
+  iml.main_source_directories << _("generated/main/resources")
+
+  # Add path for generated test resources to .iml file
+  iml.test_source_directories << _("generated/test/resources")
+
+  # Exclude the temp directory created during testing
+  iml.excluded_directories << _("tmp")
+
+  ...
+end
+{% endhighlight %}
+
+h4. Adding main or test dependencies to the .iml file
+
+The extension allows you to add main or test dependencies by modifying the "iml.main_dependencies" or "iml.test_dependencies" settings respectively. This is only needed when the defaults inherited from project.compile or project.test are not sufficient. Note: These dependencies are not included on compile path when running buildr.
+
+h5. Example
+
+{% highlight ruby %}
+define "foo" do
+  # Add idea specific jar dependency to .iml file
+  iml.main_dependencies << 'group:id:jar:1.0'
+
+  # Add idea specific test jar dependency to .iml file
+  iml.test_dependencies << 'group:id:jar:1.0'
+  ...
+end
+{% endhighlight %}
+
+h4. Dependency generation
+
+A file dependency that exists in the local maven 2 repository is stored in the IML file relative to the @$MAVEN_REPOSITORY$@ environment variable (that defaults to @~/.m2/repository@). The user can override the environment variable by setting the "iml.local_repository_env_override" setting. If the dependency does not exist in to maven repository or the "iml.local_repository_env_override" setting is set to nil, then the path stored in the IML is relative to the IML file.
+
+h5. Example: Setting local_repository_env_override
+
+{% highlight ruby %}
+define "foo" do
+  iml.local_repository_env_override = nil
+  compile.with 'group:id:jar:1.0'
+end
+{% endhighlight %}
 
+Will generate a dependency with a path like:
+
+<pre>
+jar:///home/peter/.m2/repository/group/id/1.0/id-1.0.jar!/
+</pre>
+
+rather than the default
+
+<pre>
+jar://$MAVEN_REPOSITORY$/group/id/1.0/id-1.0.jar!/
+</pre>
+
+h5. Example: A dependency outside the maven repository
+
+{% highlight ruby %}
+define "foo" do
+  compile.with _("foos-dep.jar")
+end
+{% endhighlight %}
+
+Will generate a dependency with a path like:
+
+<pre>
+jar://$MODULE_DIR$/foo-dep.jar!/
+</pre>
+
+h4. Module Facets
+
+Facets are IDEAs mechanism for adding support for languages, tools and frameworks other than core java. A facet can be added to a project so that it can be deployed as a web application or a hibernate application. A facet can also be used t provide support for other languages such as ruby and scala. The extension makes it possible to generate @.iml@ with the appropriate facets via the "iml.add_facet" method. It should be noted that facets are NOT inherited by sub-projects.
+
+h5. Example
+
+This example adds the web facet to a project.
+
+{% highlight ruby %}
+define "foo" do
+  iml.add_facet("Web","web") do |facet|
+    facet.configuration do |conf|
+      conf.descriptors do |desc|
+        desc.deploymentDescriptor :name => 'web.xml',
+          :url => "file://$MODULE_DIR$/src/main/webapp/WEB-INF/web.xml",
+          :optional => "false", :version => "2.4"
+      end
+      conf.webroots do |webroots|
+        webroots.root :url => "file://$MODULE_DIR$/src/main/webapp", :relative => "/"
+      end
+    end
+  end
+end
+{% endhighlight %}
+
+h4. Custom Component Sections
+
+If the extension does not provide capability to generate configuration for a particular IDEA plugin the user can provide their own configuration data via the "ipr.add_component" or "iml.add_component" methods.
+
+h5. Example: Adding .ipr specific component
+
+This example changes the compiler configuration for project.
+
+{% highlight ruby %}
+define "foo" do
+  ipr.add_component("CompilerConfiguration") do |component|
+    component.option :name => 'DEFAULT_COMPILER', :value => 'Javac'
+    component.option :name => 'DEPLOY_AFTER_MAKE', :value => '0'
+    component.resourceExtensions do |xml|
+      xml.entry :name => '.+\.nonexistent'
+    end
+    component.wildcardResourceExtensions do |xml|
+      xml.entry :name => '?*.nonexistent'
+    end
+  end
+end
+{% endhighlight %}
+
+h5. Example: Adding .iml specific component
+
+This example adds the web facet to a project. Note: This overrides the facets defined by the "iml.add_facet" method.
+
+{% highlight ruby %}
+define "foo" do
+  iml.add_component("FacetManager") do |component|
+    component.facet :type => 'web', :name => 'Web' do |facet|
+      facet.configuration do |conf|
+        conf.descriptors do |desc|
+          desc.deploymentDescriptor :name => 'web.xml',
+            :url => "file://$MODULE_DIR$/src/main/webapp/WEB-INF/web.xml",
+            :optional => "false", :version => "2.4"
+        end
+        conf.webroots do |webroots|
+          webroots.root :url => "file://$MODULE_DIR$/src/main/webapp", :relative => "/"
+        end
+      end
+    end
+  end
+end
+{% endhighlight %}
+
+h4. Templates
+
+The underlying project files are xml the contain elements for a number of "components". The extension will load any existing project files and replace or add any component elements that are generated by the extension. The extension also allows the user to specify a template with either "ipr.template" or "iml.template" settings. If a template is specified it will be loaded and any component elements in these documents will be merged into the base document prior to merging in generated sections. Templates are useful if you want to enforce certain configuration options (i.e. project specific code style).
+
+h5. Example
+
+{% highlight ruby %}
+define "foo" do
+  ipr.template = 'project.ipr.template'
+  iml.template = 'module.iml.template'
+end
+{% endhighlight %}
+
+h4. Groups
+
+IDEA provides the facility to organise modules into groups. By default the extension does not do this but it can be enabled by "iml.group" setting. If that setting is set to true then the @.iml@ file will be placed in a group based on the parent projects name. If the setting is a string then that is used as the name of the group.
+
+h5. Example
+
+{% highlight ruby %}
+define "foo" do
+  iml.group = true
+  define 'bar' do
+    define 'baz'
+  end
+  define 'rab' do
+    iml.group = "MyGroup"
+  end
+end
+{% endhighlight %}
+
+Will place the generated .imls in the following groups:
+
+<pre>
+foo.iml                => ''
+bar/bar.iml            => 'foo'
+bar/baz/baz.iml        => 'foo/bar'
+rab/rab.iml            => 'MyGroup'
+</pre>
+
+h4. Add Extra .iml files to .ipr
+
+The 'ipr.extra_modules' setting makes it possible to add extra modules to the generated iml file. The setting is an array of file names relative to the base project directory.
+
+h5. Example
+
+{% highlight ruby %}
+define "foo" do
+  ipr.extra_modules << 'other.iml'
+  ipr.extra_modules << 'other_other.iml'
+end
+{% endhighlight %}
+
+Will add the 'other.iml' and 'other_other.iml' files to the @.ipr@ project files.
+
+h4. Buildr plugin for IDEA
+
+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). Cobertura, Emma, JDepend
 
@@ -460,6 +766,27 @@ $ buildr --require buildr/jdepend jdepend:swing
 $ buildr -rbuildr/java/cobertura cobertura:html
 {% endhighlight %}
 
+h2(#jaxb_xjc). JAXB Xjc Compiler
+
+Buildr includes an extension that provides the ability to invoke jaxb xjc binding compiler. A typical project that uses the extension may look something like;
+
+{% highlight ruby %}
+require 'buildr/jaxb_xjc'
+
+define "foo" do
+  project.version = "1.0.0"
+  compile.from compile_jaxb(_('src/schemas/wildfire-1.3.xsd'),
+                            "-quiet",
+                            :package => "org.foo.api")
+  package :jar
+end
+{% endhighlight %}
+
+The method compile_jaxb accepts either an array of files or a single file as the first parameter. It then accepts 0 or more arguments that are passed to the underlying XJC compiler. The arguments are documented on the "jaxb site":https://jaxb.dev.java.net/nonav/2.2.1/docs/xjc.html. If the last argument is an options hash then the extension handles the options hash specially. The supported options include:
+
+* <tt>:directory</tt>: The directory to which source is generated. Defaults to <tt>_(:target, :generated, :jaxb)</tt>
+* <tt>:keep_content</tt>: By default the generated directory will be deleted. If <tt>true</tt> is specified for this parameter the directory will not be deleted.
+* <tt>:package</tt>: The package in which the source is generated.
 
 h2(#anything_ruby). Anything Ruby Can Do
 

data/doc/packaging.textile

@@ -314,17 +314,203 @@ EAR packages include an @application.xml@ file in the @META-INF@ directory that
 
 * *display-name* -- The application's display name defaults to the project's identifier.  You can change that by setting the @display_name@ attribute.
 
+* *description* -- The application's description defaults to the project's comment.  You can change that by setting the @description@ 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:
 
 {% highlight ruby %}
 package(:ear).display_name = 'MyCoolWebService'
-package(:ear).add project('coolWebService').package(:war), :context-root=>'coolness'
+package(:ear).description = 'MyCoolWebService: Making coolness kool again'
+package(:ear).add project('coolWebService').package(:war), :context_root=>'coolness'
 {% endhighlight %}
 
 If you need to disable the context root (e.g. for Portlets), set @context_root@ to @false@.
 
+It is also possible to add @security-role@ tags to the @application.xml@ file by appending a hash with @:id@, @:description@ and @:name@ to the @security_role@ array, like so:
+
+{% highlight ruby %}
+package(:ear).security_roles << {:id=>'SecurityRole_123',
+		:description=>'Read only user', :name=>'coolUser'}
+package(:ear).security_roles << {:id=>'SecurityRole_456',
+		:description=>'Super user', :name=>'superCoolUser'}
+{% endhighlight %}
+
+h2(#bundle).  Packaging OSGi Bundles
+
+OSGi bundles are jar files with additional metadata stored in the manifest. Buildr uses an external tool "Bnd":http://www.aqute.biz/Code/Bnd to create the package. Directives and properties can be explicitly passed to the build tool and buildr will provide reasonable defaults for properties that can be derived from the project model. Please see the bnd tool for documentation on the available properties.
+
+The bundle packaging format is included as an addon so the build file must explicitly require the addon using using <code>require "buildr/bnd"</code> and must add a remote repository from which the bnd can be downloaded. A typical project that uses the bundle packaging addon may look something like;
+
+{% highlight ruby %}
+require "buildr/bnd"
+
+repositories.remote << Buildr::Bnd.remote_repository
+
+define 'myProject' do
+  ...
+  package(:bundle).tap do |bnd|
+    bnd['Import-Package'] = "*;resolution:=optional"
+    bnd['Export-Package'] = "*;version=#{version}"
+  end
+  ...
+end
+{% endhighlight %}
+
+The @[]@ method on the bundle package is used to provide directives to the bnd tool that are not inherited by sub-projects while the standard 'manifest' setting is used to define properties that inherited by sub-projects.
+
+h3. Defaults
+
+The addon sets the following bnd parameters;
+
+* <tt>"Bundle-Version"</tt> defaults to the project version.
+* <tt>"Bundle-SymbolicName"</tt> defaults to the concatenation of the project group and project id, replacing ':' characters with '.'.
+* <tt>"Bundle-Name"</tt> defaults to the project description if present else the project name
+* <tt>"Bundle-Description"</tt> defaults to the project description.
+* <tt>"-classpath"</tt> is set to the compile target directory and any compile time dependencies.
+* <tt>"Include-Resource"</tt> defaults to the dir project.resources.target if it exists.
+
+h3. Parameters
+
+h4. classpath_element
+
+The user can also specify additional elements that are added to the classpath using the 'classpath_element' method. If the parameter to this element is a task, artifact, artifact namespace etc. then it will be resolved prior to invoking bnd.
+
+{% highlight ruby %}
+...
+define 'foo' do
+  ...
+  package(:bundle).tap do |bnd|
+    # This dependency will be added to classpath
+    bnd.classpath_element 'someOtherExistingFile.zip'
+    # All of these dependencies will be invoked and added to classpath
+    bnd.classpath_element artifact('com.sun.messaging.mq:imq:jar:4.4')
+    bnd.classpath_element project('bar') # Adds all the packages
+    bnd.classpath_element 'org.apache.ant:ant:jar:1.8.0'
+    bnd.classpath_element file('myLocalFile.jar')
+    ...
+  end
+
+  project 'bar' do
+    ...
+  end
+end
+{% endhighlight %}
+
+h4. classpath
+
+The user can specify the complete classpath using the 'classpath' method. The classpath should be an array of elements. If the element is a task, artifact, artifact namespace etc. then it will be resolved prior to invoking bnd.
+
+{% highlight ruby %}
+...
+define 'foo' do
+  ...
+  package(:bundle).tap do |bnd|
+    bnd.classpath [ project.compile.target,
+                    'someOtherExistingFile.zip',
+                    artifact('com.sun.messaging.mq:imq:jar:4.4'),
+                    project('bar'),
+                    'org.apache.ant:ant:jar:1.8.0',
+                    file('myLocalFile.jar') ]
+    ...
+  end
+
+  project 'bar' do
+    ...
+  end
+end
+{% endhighlight %}
+
+h3. Examples
+
+h4. Including non-class resources in a bundle
+
+Bnd can be used to include non-class resources in a bundle. The following example includes all resources in 'src/etc' into the bundle.
+
+{% highlight ruby %}
+define 'myproject' do
+  ...
+  package(:bundle).tap do |bnd|
+    bnd['Include-Resource'] = project._('src/etc') + '/'
+    ...
+  end
+end
+{% endhighlight %}
+
+h4. Using bnd to wrap an existing jar
+
+Bnd can be used to wrap an existing jar as an OSGi bundle. The following example wraps the OpenMQ JMS provider as an OSGi bundle.
+
+{% highlight ruby %}
+...
+# Add repository for OpenMQ
+repositories.remote << 'http://download.java.net/maven/2'
+
+desc 'OSGi bundle for OpenMQ JMS provider client library'
+define 'com.sun.messaging.mq.imq' do
+  project.version = '4.4'
+  project.group = 'iris'
+  package(:bundle).tap do |bnd|
+    bnd['Import-Package'] = "*;resolution:=optional"
+    bnd['Export-Package'] = "com.sun.messaging.*;version=#{version}"
+    bnd.classpath_element 'com.sun.messaging.mq:imq:jar:4.4'
+  end
+end
+{% endhighlight %}
+
+h4. Create an OSGi bundle with an Activator
+
+The following example presents a basic buildfile for building an OSGi bundle with an activator.
+
+{% highlight ruby %}
+...
+# repository for OSGi core bundle
+repositories.remote << 'https://repository.apache.org/content/repositories/releases'
+
+desc 'Hello World bundle'
+define 'helloworld' do
+  project.version = '1.0'
+  project.group = 'org.example'
+  compile.with 'org.apache.felix:org.osgi.core:jar:1.4.0'
+  package(:bundle).tap do |bnd|
+    bnd['Export-Package'] = "org.example.helloworld.api.*;version=#{version}"
+    bnd['Bundle-Activator'] = "org.example.helloworld.Activator"
+  end
+end
+{% endhighlight %}
+
+h4. Inheriting parameters for bnd tool
+
+The following example shows how you can use 'manifest' to define a bnd parameter that is inherited by all child sub-projects. The "Bundle-License" defined in the top level project is passed to the bnd tool when generating both the 'fe' and 'fi' sub-projects but the 'fo' sub-project overrides this parameter with a local value.
+
+{% highlight ruby %}
+...
+define 'myproject' do
+  manifest['Bundle-License'] = "http://www.apache.org/licenses/LICENSE-2.0"
+  ...
+  define 'fe' do
+    ...
+    package(:bundle).tap do |bnd|
+      ...
+    end
+  end
+
+  define 'fi' do
+    ...
+    package(:bundle).tap do |bnd|
+      ...
+    end
+  end
+
+  define 'fo' do
+    ...
+    package(:bundle).tap do |bnd|
+      bnd['Bundle-License'] = "http://www.apache.org/licenses/LICENSE-1.1"
+    end
+  end
+end
+{% endhighlight %}
 
 h2(#tar).  Packaging Tars and GZipped Tars