Added: dev/buildr/1.5.0/site/more_stuff.html
==============================================================================
--- dev/buildr/1.5.0/site/more_stuff.html (added)
+++ dev/buildr/1.5.0/site/more_stuff.html Sat Sep 17 06:18:39 2016
@@ -0,0 +1,796 @@
+<html>
+  <head>
+    <meta content='text/html;charset=UTF-8' http-equiv='Content-Type'>
+    <title>buildr &mdash; More Stuff</title>
+    <style type='text/css'>
+      @import 'css/default.css';
+      @import 'css/syntax.css';
+    </style>
+    <style media='print' type='text/css'>
+      @import 'css/print.css';
+    </style>
+    <meta content='Official Buildr documentation from the people in the know' 
name='subject'>
+    <link href='images/favicon.png' rel='shortcut icon'>
+  </head>
+  <body>
+    <div id='wrap'>
+      <div id='header'>
+        <a href='http://buildr.apache.org/' title="Build like you code"><img 
alt='buildr' src='images/buildr.png'></a>
+        <div class='tagline'>Build like you code</div>
+      </div>
+      <div id='pages'>
+        <ol class='toc'>
+          <li>Start Here
+            <ol class="toc">
+              <li><a href='index.html'>Welcome</a></li>
+              <li><a href='quick_start.html'>Quick Start</a></li>
+              <li><a href='installing.html'>Installing & Running</a></li>
+              <li><a 
href='http://cwiki.apache.org/confluence/display/BUILDR/Index'>Community 
Wiki</a></li>
+            </ol>
+          </li>
+          <li>Using Buildr
+            <ol class="toc">
+              <li><a href='buildr.pdf'>This Guide (PDF)</a></li>
+              <li><a href='projects.html'>Projects</a></li>
+              <li><a href='building.html'>Building</a></li>
+              <li><a href='artifacts.html'>Artifacts</a></li>
+              <li><a href='packaging.html'>Packaging</a></li>
+              <li><a href='testing.html'>Testing</a></li>
+              <li><a href='releasing.html'>Releasing</a></li>
+              <li><a href='settings_profiles.html'>Settings/Profiles</a></li>
+              <li><a href='languages.html'>Languages</a></li>
+              <li><a href='more_stuff.html'>More Stuff</a></li>
+              <li><a href='extending.html'>Extending Buildr</a></li>
+              <li><a 
href='http://cwiki.apache.org/confluence/display/BUILDR/Buildr+HowTos'>How-Tos</a></li>
+            </ol>
+          </li>
+          <li>Reference
+            <ol class="toc">
+              <li><a href='rdoc/Buildr.html'>API</a></li>
+              <li><a href='http://docs.rubyrake.org'>Rake</a></li>
+              <li><a href='https://rubygems.org/gems/Antwrap'>Antwrap</a></li>
+              <li><a 
href='http://cwiki.apache.org/confluence/display/BUILDR/Common+Problems+and+Solutions'>Troubleshooting</a></li>
+            </ol>
+          </li>
+          <li>Get Involved
+            <ol class="toc">
+              <li><a href='download.html'>Download</a></li>
+              <li><a href='mailing_lists.html'>Mailing Lists</a></li>
+              <li><a href='http://www.twitter.com/buildr'>Twitter</a></li>
+              <li><a 
href='http://issues.apache.org/jira/browse/Buildr'>Issues/Bugs</a></li>
+              <li><a href='https://builds.apache.org/view/A-F/view/Buildr'>CI 
Jobs</a></li>
+              <li><a href='contributing.html'>Contributing</a></li>
+            </ol>
+          </li>
+          <li>
+            <form action='http://www.google.com/' 
onsubmit="document.getElementById('gQuery').value += ' site:buildr.apache.org'">
+              <input name='q' size='20' type='text' id='gQuery'>
+              <input name='sa' type='submit' value='Search'>
+              <img alt='Google Custom Search' 
src='http://www.google.com/coop/images/google_custom_search_smnar.gif'>
+            </form>
+          </li>
+        </ol>
+      </div>
+      <div id='content'>
+        <h1 id='more stuff'>More Stuff</h1>
+        <ol class="toc"><li><a href="#shell">Interactive Shells 
(REPLs)</a></li><li><a href="#run">Running Your Application</a></li><li><a 
href="#gems">Using Gems</a></li><li><a href="#java">Using Java 
Libraries</a></li><li><a href="#buildr-server">BuildrServer</a></li><li><a 
href="#notifications">Notifications: Growl, Libnotify, Qube</a></li><li><a 
href="#eclipse">Eclipse</a></li><li><a href="#maven_central">Releasing to Maven 
Central</a></li><li></li><li><a href="#cobertura_emma">Cobertura, 
Emma</a></li><li><a href="#checkstyle">Checkstyle</a></li><li><a 
href="#findbugs">FindBugs</a></li><li><a 
href="#javancss">JavaNCSS</a></li><li><a 
href="#jdepend">JDepend</a></li><li></li><li><a 
href="#sonar">Sonar</a></li><li>Xjc Compiler</li><li><a 
href="#css_lint">CssLint</a></li><li><a 
href="#scss_lint">ScssLint</a></li><li><a href="#anything_ruby">Anything Ruby 
Can Do</a></li></ol>
+        <h2 id="shell">Interactive Shells (REPLs)</h2>
+<p>Many languages (including Scala and Groovy) provide an interactive shell 
tool which allows developers to run arbitrary expressions and see the results 
immediately:</p>
+<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&gt; 6 * 7
+res0: Int = 42
+
+scala&gt; </pre>
+<p>These tools are alternatively known as &#8220;REPLs&#8221; (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.</p>
+<p>Unfortunately, for such a tool to be useful in Java, Scala or Groovy 
development, it must have access to the <code>CLASSPATH</code>, 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 <code>-cp</code> switch for the Scala shell), this can get extremely 
tedious for project&#8217;s with more dependencies, especially when some of 
these dependencies are defined using <code>transitive</code> artifacts.</p>
+<p>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 <code>shell</code> task:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>buildr shell</code></pre></figure><p>The <code>shell</code> 
task depends upon <code>compile</code>, meaning that any changed source files 
will be recompiled prior to the shell&#8217;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&#8217;s compilation classpath (anything specified 
using <code>compile.with</code>) as well as the compiled sources for your 
project.</p>
+<p>The project classpath is determined by checking the current working 
directory of your system shell (the path from which the <code>buildr 
shell</code> command was invoked) and recursively finding the relevant project 
for that directory.  Thus, if you have a parent project <code>foo</code> which 
has sub-projects <code>bar</code> and <code>baz</code>, you may invoke an 
interactive shell for the <code>baz</code> project simply by 
<code>cd</code>-ing into its project directory (or any of its sub-directories) 
and invoking the <code>shell</code> task. You may also invoke a shell against a 
specific project by giving its fully-qualified descriptor as a prefix to the 
<code>shell</code> task:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>buildr foo:bar:shell</code></pre></figure><h3>Supported 
Shells</h3>
+<p>By default, Buildr will open the interactive shell which corresponds to 
your project&#8217;s language.  Thus, if your project is using Groovy, it will 
invoke the <code>groovysh</code> command, configured with the appropriate 
classpath.  If your project is using Scala, then the <code>shell</code> task 
will invoke the <code>scala</code> 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 <a 
href="http://www.beanshell.org/manual/quickstart.html#The_BeanShell_GUI";>BeanShell</a>
 console.</p>
+<p>However, you may still wish to exploit the advantages of an interactive 
shell from some other <span class="caps">JVM</span> 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:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>buildr foo:shell:jirb</code></pre></figure><p>This will 
open the <span class="caps">JIRB</span> shell (the JRuby <span 
class="caps">REPL</span>) for the <code>foo</code> project.  Whenever you are 
specifying a shell explicitly in this fashion, you <strong>must</strong> 
fully-qualify the project name:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>buildr shell:jirb     <span class="c"># 
wrong!!</span></code></pre></figure><p>The above will fail because of the way 
that Rake tasks are dispatched.</p>
+<p>Obviously, this explicit specification is a little bit clunky.  It would be 
much easier if we could simply say that we <strong>always</strong> want to use 
the <span class="caps">JIRB</span> shell for this particular project.  This can 
be done by using the <code>shell.using</code> directive within your project 
definition:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s1">&#39;foo&#39;</span> <span class="k">do</span>
+  <span class="n">shell</span><span class="o">.</span><span 
class="n">using</span> <span class="ss">:jirb</span>
+<span class="k">end</span></code></pre></figure><p>With this project 
definition, we can now invoke the <code>shell</code> task and <span 
class="caps">JIRB</span> will be launched, regardless of the default for our 
project&#8217;s language:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>buildr shell</code></pre></figure><p>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 
<code>shell.using</code> descriptor and the language for which they are the 
default (if applicable):</p>
+<table>
+       <tr>
+               <th>Shell Name        </th>
+               <th>Descriptor       </th>
+               <th>Language       </th>
+       </tr>
+       <tr>
+               <td> BeanShell Console   </td>
+               <td> <code>:bsh</code>             </td>
+               <td> Java             </td>
+       </tr>
+       <tr>
+               <td> Clojure <span class="caps">REPL</span>        </td>
+               <td> <code>:clj</code>             </td>
+               <td> <strong>N/A</strong>            </td>
+       </tr>
+       <tr>
+               <td> GroovySH            </td>
+               <td> <code>:groovysh</code>        </td>
+               <td> Groovy           </td>
+       </tr>
+       <tr>
+               <td> JRuby <span class="caps">IRB</span>           </td>
+               <td> <code>:jirb</code>            </td>
+               <td> <strong>N/A</strong>            </td>
+       </tr>
+       <tr>
+               <td> Scala Interpreter   </td>
+               <td> <code>:scala</code>           </td>
+               <td> Scala            </td>
+       </tr>
+</table>
+<p>Note that some of these shells impose certain requirements to enable use.  
The Groovy shell requires the <code>GROOVY_HOME</code> environment variable to 
point to the Groovy install path.  The Clojure <span class="caps">REPL</span> 
makes a similar requirement of <code>CLOJURE_HOME</code>.  The JRuby and Scala 
shells will use <code>JRUBY_HOME</code> and <code>SCALA_HOME</code> 
respectively if they are defined.  However, if these environment variables are 
not defined, the relevant <span class="caps">JAR</span> files will be 
automatically downloaded from the appropriate Maven2 repository.</p>
+<h3>Verbosity and Tracing</h3>
+<p>By default, Buildr is moderately verbose, meaning that it attempts to give 
you enough context into what&#8217;s happening during the build.</p>
+<p>It&#8217;s possible to silence Buildr if you&#8217;re inconvenienced by its 
default verbosity by issuing,</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>buildr --silent</code></pre></figure><p>On the other hand, 
if you want Buildr to give you more context in order to trace what&#8217;s 
happening, you can use the <code>-t</code> options:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>buildr -t</code></pre></figure><p>Using <code>-t</code> 
will also display backtraces if and when they occur.</p>
+<p>Many components can be individually configured to display more output if 
you&#8217;re debugging a specific area of your build.  For instance, you could 
use <code>--trace=javac,groovyc</code> to enable tracing of the Java and Groovy 
compilers:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>buildr --trace<span 
class="o">=</span>javac,groovyc</code></pre></figure><p>If you don&#8217;t know 
which tracing category you need to enable or if you want a full firehose worth 
of traces, you can enable all traces:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>buildr --trace<span 
class="o">=</span>all</code></pre></figure><h3 id="javarebel">JavaRebel 
Integration</h3>
+<p><a href="http://www.zeroturnaround.com/javarebel";>JavaRebel</a> is a live 
bytecode reloading solution by Zero Turnaround.  It&#8217;s a lot like the hot 
code reload feature found in many Java <span class="caps">IDE</span> 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 <span class="caps">JVM</span> language, but they do offer a 
free license for use with Scala classes only.</p>
+<p>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.</p>
+<p>JavaRebel auto-magical integration is done by searching for a valid 
JavaRebel install path in the following list of environment variables (in 
order):</p>
+<ul>
+       <li><code>REBEL_HOME</code></li>
+       <li><code>JAVA_REBEL</code></li>
+       <li><code>JAVAREBEL</code></li>
+       <li><code>JAVAREBEL_HOME</code></li>
+</ul>
+<p>These environment variables may point to either the JavaRebel install 
directory (e.g. <code>~/javarebel-2.0.1</code>), or the <span 
class="caps">JAR</span> file itself (e.g. 
<code>~/javarebel-2.0.1/javarebel.jar</code>).  If the path is valid, Buildr 
will automatically append the appropriate <span class="caps">JVM</span> 
switches to the launch configurations of each shell:</p>
+<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&gt; </pre>
+<p>Note that Buildr does <strong>not</strong> 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).</p>
+<h2 id="run">Running Your Application</h2>
+<p>The <code>run</code> task lets you easily run programs from your buildfile, 
such as launching your own application.</p>
+<p>In its simplest form, you simply define the main class of your Java 
application,</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s1">&#39;my-project&#39;</span> <span class="k">do</span>
+  <span class="n">compile</span><span class="o">.</span><span 
class="n">with</span> <span class="no">COMMONS_IO</span><span 
class="p">,</span> <span class="no">HTTPCLIENT</span>
+  <span class="n">run</span><span class="o">.</span><span 
class="n">using</span> <span class="ss">:main</span> <span 
class="o">=&gt;</span> <span class="s2">&quot;org.example.Main&quot;</span>
+<span class="k">end</span></code></pre></figure><p>And then run,</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="o">~</span><span class="sr">/my-project$ buildr 
run</span></code></pre></figure><p>which would launch your application using 
the project&#8217;s compile classpath.</p>
+<p>It&#8217;s also possible to pass arguments to the <span 
class="caps">JVM</span> using the <code>:java_args</code> option:</p>
+<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby">  
<span class="n">run</span><span class="o">.</span><span class="n">using</span> 
<span class="ss">:main</span> <span class="o">=&gt;</span> <span 
class="s2">&quot;org.example.Main&quot;</span><span class="p">,</span>
+            <span class="ss">:java_args</span> <span class="o">=&gt;</span> 
<span class="o">[</span><span class="s2">&quot;-server&quot;</span><span 
class="o">]</span></code></pre></figure><p>If your application requires 
arguments, you can pass in an array of values for the <code>:main</code> 
option, or provide a set of system properties using 
<code>:properties</code>.</p>
+<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby">  
<span class="n">run</span><span class="o">.</span><span class="n">using</span> 
<span class="ss">:main</span> <span class="o">=&gt;</span> <span 
class="o">[</span><span class="s2">&quot;org.example.Main&quot;</span><span 
class="p">,</span> <span class="s2">&quot;-t&quot;</span><span 
class="p">,</span> <span class="s2">&quot;input.txt&quot;</span><span 
class="o">]</span><span class="p">,</span>
+            <span class="ss">:properties</span> <span class="o">=&gt;</span> 
<span class="p">{</span> <span class="ss">:debug</span> <span 
class="o">=&gt;</span> <span class="s2">&quot;true&quot;</span> <span 
class="p">}</span></code></pre></figure><p>The <code>run</code> task is a local 
task, which means that Buildr will automatically pick the <code>run</code> task 
matching the project in the current directory.  Executing the following 
command:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="o">~</span><span 
class="sr">/my-project/su</span><span class="n">bproject</span><span 
class="err">$</span> <span class="n">buildr</span> <span 
class="n">run</span></code></pre></figure><p>will run the 
<code>my-project:subproject:run</code> task, assuming <code>my-project</code> 
is your top-level project.</p>
+<p>Here is a summary of <code>run.using</code> options,</p>
+<table>
+       <tr>
+               <th>Option </th>
+               <th>Description &#8230; </th>
+       </tr>
+       <tr>
+               <td> <code>:main</code>   </td>
+               <td> The java main class, e.g. &#8220;com.example.Main&#8221;. 
Can also be an array if the main class requires arguments. </td>
+       </tr>
+       <tr>
+               <td> <code>:properties</code>   </td>
+               <td> A hash of system properties to be passed to java. </td>
+       </tr>
+       <tr>
+               <td> <code>:java_args</code> </td>
+               <td> An array of additional parameters to pass to java </td>
+       </tr>
+       <tr>
+               <td> <code>:classpath</code>   </td>
+               <td> An array of additional classpath elements (i.e. artifacts, 
files, etc.). By default, the <code>run</code> task automatically uses the 
<code>compile.dependencies</code>, <code>test.dependencies</code> and 
<code>test.compile.target</code> of your project. </td>
+       </tr>
+</table>
+<p class="note">The <code>run</code> task also detects and uses JavaRebel if 
it&#8217;s available.  See the <a href="#javarebel">JavaRebel</a> section for 
details.</p>
+<h2 id="gems">Using Gems</h2>
+<p>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.</p>
+<p>There are several mechanisms for developing extensions and build features 
across projects which we cover in more details in the section <a 
href="extending.html">Extending Buildr</a>.  Here we will talk about using 
extensions that are distributed in the form of RubyGems.</p>
+<p><a href="http://rubygems.org";>RubyGems</a> provides the <code>gem</code> 
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.</p>
+<p>RubyGems is preconfigured to use the <a 
href="http://rubygems.org";>RubyForge</a> repository.  You&#8217;ll find a large 
number of open source Ruby libraries there, including Buildr itself and all its 
dependencies.</p>
+<p>You can also set up your own private repository and use it instead or in 
addition to RubyForge.  Use the <code>gem sources</code> command to add 
repositories, and the <code>gem server</code> command to run a remote 
repository.  You can see all available options by running <code>gem 
help</code>.</p>
+<p>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&#8217;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 
<code>gem</code> command.</p>
+<p>Use the <code>build.yaml</code> file to specify these dependencies (see <a 
href="settings_profiles.html#build">Build Settings</a> for more information), 
for example:</p>
+<figure class="highlight"><pre><code class="language-yaml" 
data-lang="yaml"><span class="c1"># This project requires the following 
gems</span>
+<span class="l-Scalar-Plain">gems</span><span class="p-Indicator">:</span>
+  <span class="c1"># Suppose we want to notify developers when testcases 
fail.</span>
+  <span class="p-Indicator">-</span> <span 
class="l-Scalar-Plain">buildr-twitter-notifier-addon &gt;=1</span>
+  <span class="c1"># we test with ruby mock objects</span>
+  <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">mocha</span>
+  <span class="p-Indicator">-</span> <span 
class="l-Scalar-Plain">ci_reporter</span></code></pre></figure><p>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.</p>
+<p>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.</p>
+<p>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, 
<code>1.2.3</code> to install only version 1.2.3, and <code>=&gt; 1.2.3</code> 
to install version 1.2.3 or later.</p>
+<p>You can also specify a range up to one version bump, for example, 
<code>~&gt; 1.2.3</code> is the same as <code>&gt;= 1.2.3 &lt; 1.3.0</code>, 
and <code>~&gt; 1.2</code> is the same as <code>&gt;= 1.2.0 &lt; 2.0.0</code>. 
If necessary, you can exclude a particular version number, for example, 
<code>~&gt; 1.2.3 != 1.2.7</code>.</p>
+<p>Buildr will install the latest version that matches the version 
requirement. To keep up with newer versions, execute the <code>gem 
update</code> command periodically. You can also use <code>gem outdated</code> 
to determine which new versions are available.</p>
+<p>Most gems include documentation that you can access in several forms.  You 
can use the <code>ri</code> command line tool to find out more about a class, 
module or specific method.  For example:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>ri Buildr::Jetty
+<span class="nv">$ </span>ri Buildr::Jetty.start</code></pre></figure><p>You 
can also access documentation from a Web browser by running <code>gem 
server</code> and pointing your browser to <a 
href="http://localhost:8808";>http://localhost:8808</a>. Note that after 
installing a new gem, you will need to restart the gem server to see its 
documentation.</p>
+<h2 id="java">Using Java Libraries</h2>
+<p>Buildr runs along side a <span class="caps">JVM</span>, using either <span 
class="caps">RJB</span> or JRuby.  The Java module allows you to access Java 
classes and create Java objects.</p>
+<p>Java classes are accessed as static methods on the <code>Java</code> 
module, for example:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">str</span> <span class="o">=</span> <span 
class="no">Java</span><span class="o">.</span><span class="n">java</span><span 
class="o">.</span><span class="n">lang</span><span class="o">.</span><span 
class="n">String</span><span class="o">.</span><span class="n">new</span><span 
class="p">(</span><span class="s1">&#39;hai!&#39;</span><span class="p">)</span>
+<span class="n">str</span><span class="o">.</span><span 
class="n">toUpperCase</span>
+<span class="o">=&gt;</span> <span class="s1">&#39;HAI!&#39;</span>
+<span class="no">Java</span><span class="o">.</span><span 
class="n">java</span><span class="o">.</span><span class="n">lang</span><span 
class="o">.</span><span class="n">String</span><span class="o">.</span><span 
class="n">isInstance</span><span class="p">(</span><span 
class="n">str</span><span class="p">)</span>
+<span class="o">=&gt;</span> <span class="kp">true</span>
+<span class="no">Java</span><span class="o">.</span><span 
class="n">com</span><span class="o">.</span><span class="n">sun</span><span 
class="o">.</span><span class="n">tools</span><span class="o">.</span><span 
class="n">javac</span><span class="o">.</span><span class="n">Main</span><span 
class="o">.</span><span class="n">compile</span><span class="p">(</span><span 
class="n">args</span><span class="p">)</span></code></pre></figure><p>The 
<code>classpath</code> 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.</p>
+<p>When using an artifact specification, Buildr will automatically download 
and install the artifact before adding it to the classpath.</p>
+<p>For example, Ant is loaded as follows:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="no">Java</span><span class="o">.</span><span 
class="n">classpath</span> <span class="o">&lt;&lt;</span> <span 
class="s1">&#39;org.apache.ant:ant:jar:1.7.0&#39;</span></code></pre></figure><p>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 <code>Java.load</code> before 
accessing any Java classes to give Buildr a chance to load the libraries 
specified in the classpath.</p>
+<p>When building an extension, make sure to follow these rules:</p>
+<ol>
+       <li>Add to the <code>classpath</code> when the extension is loaded 
(i.e. in module or class definition), so the first call to 
<code>Java.load</code> anywhere in the code will include the libraries you 
specify.</li>
+       <li>Call <code>Java.load</code> once before accessing any Java classes, 
allowing Buildr to set up the classpath.</li>
+       <li>Only call <code>Java.load</code> when invoked, otherwise you may 
end up loading the <span class="caps">JVM</span> with a partial classpath, or 
before all remote repositories are listed.</li>
+       <li>Check on a clean build with empty local repository.</li>
+</ol>
+<h2 id="buildr-server">BuildrServer</h2>
+<p>Buildr provides an addon that allows you start a <a 
href="http://www.ruby-doc.org/stdlib/libdoc/drb/rdoc/index.html";>dRuby</a> 
server hosting a buildfile, so that you can later invoke tasks on it without 
having to load the complete buildr runtime again.</p>
+<p>Usage:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh">buildr 
-r buildr/drb drb:start</code></pre></figure><p>To stop the BuildrServer simply 
use Ctrl+C or kill the process.</p>
+<p>Once the server has been started you can invoke tasks using a simple 
script:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="c1">#!/usr/bin/env ruby</span>
+<span class="nb">require</span> <span class="s1">&#39;rubygems&#39;</span>
+<span class="nb">require</span> <span class="s1">&#39;buildr/drb&#39;</span>
+<span class="no">Buildr</span><span class="o">::</span><span 
class="no">DRbApplication</span><span class="o">.</span><span 
class="n">run</span></code></pre></figure><p>Save this script as 
<code>dbuildr</code>, make it executable and use it to invoke tasks.</p>
+<notextile><figure class="highlight"><pre><code class="language-sh" 
data-lang="sh"><span class="nv">$ </span>dbuildr clean 
compile</code></pre></figure><p></notextile></p>
+<p>The <code>dbuildr</code> command will start the BuildrServer if there 
isn&#8217;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.</p>
+<h2 id="notifications">Notifications: Growl, Libnotify, Qube</h2>
+<p>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.</p>
+<p>For OS X users, Buildr supports <a href="http://growl.info/";>Growl</a> out 
of the box by using the Ruby Cocoa bindings.</p>
+<p>For Debian-based Linux users, Buildr supports notifications via the <a 
href="http://manpages.ubuntu.com/manpages/gutsy/man1/notify-send.1.html";>notify-send</a>
 command which is part of the 
&#8220;libnotify-bin&#8221;:&#8220;http://packages.debian.org/search?keywords=libnotify-bin&#8221;
 package.  Just make sure `notify-send` is installed and on your path is on 
your `<span class="caps">PATH</span>`.</p>
+<p>For other platforms or if you want to notify the user differently, Buildr 
offers two extension points:</p>
+<ul>
+       <li><code>Buildr.application.on_completion</code></li>
+       <li><code>Buildr.application.on_failure</code></li>
+</ul>
+<p>Here is an example using these extension points to send notifications using 
<a href="http://launchpad.net/qube";>Qube</a>:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="c1"># Send notifications using Qube</span>
+<span class="n">notify</span> <span class="o">=</span> <span 
class="nb">lambda</span> <span class="k">do</span> <span 
class="o">|</span><span class="n">type</span><span class="p">,</span> <span 
class="n">title</span><span class="p">,</span> <span 
class="n">message</span><span class="o">|</span>
+  <span class="n">param</span> <span class="o">=</span> <span 
class="k">case</span> <span class="n">type</span>
+    <span class="k">when</span> <span 
class="s1">&#39;completed&#39;</span><span class="p">;</span> <span 
class="s1">&#39;-i&#39;</span>
+    <span class="k">when</span> <span class="s1">&#39;failed&#39;</span><span 
class="p">;</span> <span class="s1">&#39;-e&#39;</span>
+    <span class="k">else</span> <span class="s1">&#39;-i&#39;</span>
+  <span class="k">end</span>
+  <span class="nb">system</span> <span class="s2">&quot;qube </span><span 
class="si">#{</span><span class="n">param</span><span class="si">}</span><span 
class="s2"> </span><span class="si">#{</span><span class="n">title</span><span 
class="o">.</span><span class="n">inspect</span><span class="si">}</span><span 
class="s2"> </span><span class="si">#{</span><span 
class="n">message</span><span class="o">.</span><span 
class="n">inspect</span><span class="si">}</span><span class="s2">&quot;</span>
+<span class="k">end</span>
+
+<span class="no">Buildr</span><span class="o">.</span><span 
class="n">application</span><span class="o">.</span><span 
class="n">on_completion</span> <span class="k">do</span> <span 
class="o">|</span><span class="n">title</span><span class="p">,</span> <span 
class="n">message</span><span class="o">|</span>
+  <span class="n">notify</span><span class="o">[</span><span 
class="s1">&#39;completed&#39;</span><span class="p">,</span> <span 
class="n">title</span><span class="p">,</span> <span 
class="n">message</span><span class="o">]</span>
+<span class="k">end</span>
+<span class="no">Buildr</span><span class="o">.</span><span 
class="n">application</span><span class="o">.</span><span 
class="n">on_failure</span> <span class="k">do</span> <span 
class="o">|</span><span class="n">title</span><span class="p">,</span> <span 
class="n">message</span><span class="p">,</span> <span class="n">ex</span><span 
class="o">|</span>
+  <span class="n">notify</span><span class="o">[</span><span 
class="s1">&#39;failed&#39;</span><span class="p">,</span> <span 
class="n">title</span><span class="p">,</span> <span 
class="n">message</span><span class="o">]</span>
+<span class="k">end</span></code></pre></figure><p>You can place this code 
inside <code>buildr.rb</code> in the <code>.buildr</code> directory under your 
home directory.</p>
+<h2 id="eclipse">Eclipse</h2>
+<h3>Use Apache Buildr to create Eclipse projects</h3>
+<p>If you&#8217;re using Eclipse, you can generate <code>.classpath</code> and 
<code>.project</code> from your Buildfile and use them to create a project in 
your workspace:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>buildr eclipse</code></pre></figure><p>The 
<code>eclipse</code> task will generate a <code>.classpath</code> and 
<code>.project</code> 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.</p>
+<p>If you add a new project, change the dependencies, or make any other change 
to your Buildfile, just run the <code>eclipse</code> task again to re-generate 
the Eclipse project files.  To have your libraries&#8217; source code available 
in Eclipse, run the <code>artifacts:sources</code> task.</p>
+<p>You may explicitly specify the nature of your project, for example if you 
are developing an Eclipse plugin:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s1">&#39;my-plugin&#39;</span> <span class="k">do</span>
+  <span class="n">eclipse</span><span class="o">.</span><span 
class="n">natures</span> <span class="ss">:plugin</span>
+<span class="k">end</span></code></pre></figure><p>The currently supported 
natures are <code>:java</code>, <code>:scala</code> and <code>:plugin</code>.  
Buildr will attempts to auto-detect your project type and apply the most 
relevant settings by default.   If it doesn&#8217;t or you need something 
special, you may also explicitly set the nature, container and builders of your 
project by doing:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s1">&#39;custom-plugin&#39;</span> <span class="k">do</span>
+  <span class="n">eclipse</span><span class="o">.</span><span 
class="n">natures</span> <span 
class="s1">&#39;org.eclipse.pde.PluginNature&#39;</span>
+  <span class="n">eclipse</span><span class="o">.</span><span 
class="n">classpath_containers</span> <span 
class="s1">&#39;org.eclipse.pde.core.requiredPlugins&#39;</span>
+  <span class="n">eclipse</span><span class="o">.</span><span 
class="n">builders</span> <span class="o">[</span><span 
class="s1">&#39;org.eclipse.pde.ManifestBuilder&#39;</span><span 
class="p">,</span> <span 
class="s1">&#39;org.eclipse.pde.SchemaBuilder&#39;</span><span 
class="o">]</span>
+<span class="k">end</span></code></pre></figure><p>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.</p>
+<h3>Use Apache Buildr to create a buildfile from an Eclipse workspace</h3>
+<p>If you&#8217;re using Eclipse, you can generate a <code>buildfile</code> 
from a directory which contains one (or more) Eclipse projects somewhere in its 
sub-directories.</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>buildr --generate 
/path/to/my_project</code></pre></figure><p>This creates a basic buildfile with 
a main project called &#8216;my_project&#8217;. The buildfile contains a 
skeleton for compiling the Eclipse projects. If you want to automate dependency 
tracking via OSGi have a look at the <a 
href="http://oss.intalio.com/buildr4osgi/";>buildr4osgi</a> project. Support for 
building Eclipse <span class="caps">RCP</span> applications, running <span 
class="caps">PDE</span> tests and P2-sites is currently lacking in Buildr.</p>
+<h2 id="maven_central">Releasing to Maven Central</h2>
+<p>Many opensource projects release their artifacts to Maven Central. To 
release a library to Maven Central, the project needs to provide several 
elements for each library;</p>
+<ul>
+       <li>the jar artifact,</li>
+       <li>the sources artifact,</li>
+       <li>the javadocs artifact,</li>
+       <li>a pom that supplies fields required by Maven Central, and</li>
+       <li>gpg signatures for every file supplied.</li>
+</ul>
+<p>Buildr has built-in support for the artifacts and can easily sign the 
artifacts using the &#8216;buildr/gpg&#8217; addon. However it has not always 
been easy to generate a pom in the required format until the 
&#8216;buildr/custom_pom&#8217; became available.</p>
+<p>Below is an extremely verbose example of a project that provides all the 
elements required to publish to Maven Central.</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="c"># Include addon to generate GPG Signatures</span>
+require <span class="s1">&#39;buildr/gpg&#39;</span>
+<span class="c"># Include addon to generate custom pom</span>
+require <span class="s1">&#39;buildr/custom_pom&#39;</span>
+
+define <span class="s1">&#39;myproject&#39;</span> <span class="k">do</span>
+  project.group <span class="o">=</span> <span 
class="s1">&#39;org.myproject&#39;</span>
+  project.version <span class="o">=</span> <span 
class="s1">&#39;1.0&#39;</span>
+
+  pom.licenses<span class="o">[</span><span class="s1">&#39;The Apache 
Software License, Version 2.0&#39;</span><span class="o">]</span> <span 
class="o">=</span> <span 
class="s1">&#39;http://www.apache.org/licenses/LICENSE-2.0.txt&#39;</span>
+  pom.scm_connection <span class="o">=</span> pom.scm_developer_connection 
<span class="o">=</span> <span 
class="s1">&#39;scm:git:g...@github.com:jbloggs/myproject&#39;</span>
+  pom.scm_url <span class="o">=</span> <span 
class="s1">&#39;g...@github.com:jbloggs/myproject&#39;</span>
+  pom.url <span class="o">=</span> <span 
class="s1">&#39;https://github.com/jbloggs/myproject&#39;</span>
+  pom.issues_url <span class="o">=</span> <span 
class="s1">&#39;https://github.com/jbloggs/myproject/issues&#39;</span>
+  pom.issues_system <span class="o">=</span> <span class="s1">&#39;GitHub 
Issues&#39;</span>
+  pom.add_developer<span class="o">(</span><span 
class="s1">&#39;jbloggs&#39;</span>, <span class="s1">&#39;Joe 
Bloggs&#39;</span>, <span class="s1">&#39;jblo...@example.com&#39;</span>, 
<span class="o">[</span><span class="s1">&#39;Project Lead&#39;</span><span 
class="o">])</span>
+  pom.provided_dependencies.concat <span class="o">[</span>:javax_servlet<span 
class="o">]</span>
+  pom.optional_dependencies.concat <span class="o">[</span>:optional_api<span 
class="o">]</span>
+
+  compile.with :javax_servlet, :some_api, :optional_api
+
+  test.with :mockito
+
+  package<span class="o">(</span>:jar<span class="o">)</span>
+  package<span class="o">(</span>:sources<span class="o">)</span>
+  package<span class="o">(</span>:javadoc<span class="o">)</span>
+end</code></pre></figure><p>That example is however, extremely verbose and 
there is a number of helper methods been added to the 
&#8216;buildr/custom_pom&#8217; addon to simplify common scenarios. It would be 
more common to see the addon used in the following manner;</p>
+<figure class="highlight"><pre><code class="language-sh" 
data-lang="sh">require <span class="s1">&#39;buildr/gpg&#39;</span>
+require <span class="s1">&#39;buildr/custom_pom&#39;</span>
+
+define <span class="s1">&#39;myproject&#39;</span> <span class="k">do</span>
+  project.group <span class="o">=</span> <span 
class="s1">&#39;org.myproject&#39;</span>
+  project.version <span class="o">=</span> <span 
class="s1">&#39;1.0&#39;</span>
+
+  pom.add_apache_v2_license
+  pom.add_github_project<span class="o">(</span><span 
class="s1">&#39;jbloggs/myproject&#39;</span><span class="o">)</span>
+  pom.add_developer<span class="o">(</span><span 
class="s1">&#39;jbloggs&#39;</span>, <span class="s1">&#39;Joe 
Bloggs&#39;</span><span class="o">)</span>
+  pom.provided_dependencies.concat <span class="o">[</span>:javax_servlet<span 
class="o">]</span>
+  pom.optional_dependencies.concat <span class="o">[</span>:optional_api<span 
class="o">]</span>
+
+  compile.with :javax_servlet, :optional_api
+
+  test.with :mockito
+
+  package<span class="o">(</span>:jar<span class="o">)</span>
+  package<span class="o">(</span>:sources<span class="o">)</span>
+  package<span class="o">(</span>:javadoc<span class="o">)</span>
+end</code></pre></figure><p>If there are other common scenarios useful for 
opensource developers, feel free to make a request on buildr mailing list to 
provide simplified helper methods.</p>
+<h2 id="idea">IntelliJ <span class="caps">IDEA</span></h2>
+<p>If you use IntelliJ <span class="caps">IDEA</span>, you can generate 
project files by issuing:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>buildr idea</code></pre></figure><p>This task will generate 
a <code>.iml</code> file for every project (or subproject) and a 
<code>.ipr</code> that you can directly open for the root project.</p>
+<p>The generated project files can be removed by issuing:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>buildr idea:clean</code></pre></figure><p>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 
<code>.iml</code> 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.</p>
+<p>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 <code>.iml</code> while jars are added as regular 
file dependencies. Dependencies are exported from the <code>.iml</code> file if 
they are compile dependencies. If a artifact that matches dependency but has a 
classifier of &#8216;sources&#8217; is present then it is configured as the 
source for the dependency. Note: Use &#8220;buildr artifacts:sources&#8221; to 
download the source for dependencies.</p>
+<h3>Idea Specific Directives</h3>
+<p>The extension specific settings of sub-projects inherit the parent projects 
settings unless overwritten.</p>
+<h4>Project file naming</h4>
+<p>The extension will use the last element of the projects name when 
generating the <code>.ipr</code> and <code>.iml</code> files. i.e. A project 
named &#8220;foo&#8221; will generate &#8220;foo.iml&#8221; and 
&#8220;foo.ipr&#8221; while a project named &#8220;foo:bar&#8221; will generate 
&#8220;bar/bar.iml&#8221; and no ipr. (The <code>.ipr</code> project files are 
only generated for the base project). The name can be modified by setting the 
&#8220;ipr.suffix&#8221; or &#8220;iml.suffix&#8221; settings which specifies 
the suffix appended to the file names. The user can also override the name 
completely by setting &#8220;ipr.id&#8221; or &#8220;iml.id&#8221;.</p>
+<h5>Example: Setting id</h5>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s2">&quot;foo&quot;</span> <span class="k">do</span>
+  <span class="n">ipr</span><span class="o">.</span><span class="n">id</span> 
<span class="o">=</span> <span class="s2">&quot;beep&quot;</span>
+  <span class="n">define</span> <span class="s2">&quot;bar&quot;</span> <span 
class="k">do</span>
+    <span class="n">iml</span><span class="o">.</span><span 
class="n">id</span> <span class="o">=</span> <span 
class="s2">&quot;baz&quot;</span>
+  <span class="k">end</span>
+<span class="k">end</span></code></pre></figure><p>Will generate:</p>
+<pre>
+beep.ipr
+foo.iml
+bar/baz.iml
+</pre>
+<h5>Example: Setting suffix</h5>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s2">&quot;foo&quot;</span> <span class="k">do</span>
+  <span class="n">ipr</span><span class="o">.</span><span 
class="n">suffix</span> <span class="o">=</span> <span 
class="s2">&quot;-suffix1&quot;</span>
+  <span class="n">iml</span><span class="o">.</span><span 
class="n">suffix</span> <span class="o">=</span> <span 
class="s2">&quot;-suffix2&quot;</span>
+  <span class="n">define</span> <span class="s2">&quot;bar&quot;</span>
+<span class="k">end</span></code></pre></figure><p>Will generate:</p>
+<pre>
+foo-suffix1.ipr
+foo-suffix2.iml
+bar/bar-suffix2.iml
+</pre>
+<h5>Example: Setting prefix</h5>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s2">&quot;foo&quot;</span> <span class="k">do</span>
+  <span class="n">ipr</span><span class="o">.</span><span 
class="n">prefix</span> <span class="o">=</span> <span 
class="s2">&quot;prefix1-&quot;</span>
+  <span class="n">iml</span><span class="o">.</span><span 
class="n">prefix</span> <span class="o">=</span> <span 
class="s2">&quot;prefix2-&quot;</span>
+  <span class="n">define</span> <span class="s2">&quot;bar&quot;</span>
+<span class="k">end</span></code></pre></figure><p>Will generate:</p>
+<pre>
+prefix1-foo.ipr
+prefix2-foo.iml
+bar/prefix2-bar.iml
+</pre>
+<h4>Disabling project file generation</h4>
+<p>The extension will not generate an iml file for a project if the 
&#8220;project.no_iml&#8221; method is invoked. Generation of ipr files can be 
disabled by invoking the method &#8220;project.no_ipr&#8221;.</p>
+<h5>Example</h5>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s2">&quot;foo&quot;</span> <span class="k">do</span>
+  <span class="n">project</span><span class="o">.</span><span 
class="n">no_ipr</span>
+  <span class="n">define</span> <span class="s2">&quot;bar&quot;</span> <span 
class="k">do</span>
+    <span class="n">project</span><span class="o">.</span><span 
class="n">no_iml</span>
+  <span class="k">end</span>
+<span class="k">end</span></code></pre></figure><p>Will generate:</p>
+<pre>
+foo.iml
+</pre>
+<h4>Disabling generation of content section in .iml file</h4>
+<p>The extension will not generate a content section in an iml file if the 
&#8220;iml.skip_content!&#8221; 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.</p>
+<h5>Example</h5>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s2">&quot;foo&quot;</span> <span class="k">do</span>
+  <span class="n">iml</span><span class="o">.</span><span 
class="n">skip_content!</span>
+<span class="k">end</span></code></pre></figure><h4><span 
class="caps">VCS</span> Integration</h4>
+<p>The extension will attempt to guess the <span class="caps">VCS</span> type 
of the project by looking for a <code>.svn</code> or <code>.git</code> 
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 &#8216;Git&#8217; or 
&#8216;svn&#8217; using the ipr.vcs setting.</p>
+<h5>Example</h5>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s2">&quot;foo&quot;</span> <span class="k">do</span>
+  <span class="n">ipr</span><span class="o">.</span><span class="n">vcs</span> 
<span class="o">=</span> <span class="s1">&#39;Git&#39;</span>
+<span class="k">end</span></code></pre></figure><h4>Adding main, test or 
exclude paths to the .iml file</h4>
+<p>The extension allows you to add source paths, test source paths or add 
paths to the excluded set by modifying the 
&#8220;iml.main_source_directories&#8221;, 
&#8220;iml.test_source_directories&#8221; or 
&#8220;iml.excluded_directories&#8221; settings respectively. This is only 
needed when the defaults inherited from project.compile or project.test are not 
sufficient.</p>
+<h5>Example</h5>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s2">&quot;foo&quot;</span> <span class="k">do</span>
+  <span class="c1"># Add path for generated resources to .iml file</span>
+  <span class="n">iml</span><span class="o">.</span><span 
class="n">main_source_directories</span> <span class="o">&lt;&lt;</span> <span 
class="n">_</span><span class="p">(</span><span 
class="s2">&quot;generated/main/resources&quot;</span><span class="p">)</span>
+
+  <span class="c1"># Add path for generated test resources to .iml file</span>
+  <span class="n">iml</span><span class="o">.</span><span 
class="n">test_source_directories</span> <span class="o">&lt;&lt;</span> <span 
class="n">_</span><span class="p">(</span><span 
class="s2">&quot;generated/test/resources&quot;</span><span class="p">)</span>
+
+  <span class="c1"># Exclude the temp directory created during testing</span>
+  <span class="n">iml</span><span class="o">.</span><span 
class="n">excluded_directories</span> <span class="o">&lt;&lt;</span> <span 
class="n">_</span><span class="p">(</span><span 
class="s2">&quot;tmp&quot;</span><span class="p">)</span>
+
+  <span class="o">.</span><span class="n">.</span><span class="o">.</span>
+<span class="k">end</span></code></pre></figure><h4>Adding main or test 
dependencies to the .iml file</h4>
+<p>The extension allows you to add main or test dependencies by modifying the 
&#8220;iml.main_dependencies&#8221; or &#8220;iml.test_dependencies&#8221; 
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.</p>
+<h5>Example</h5>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s2">&quot;foo&quot;</span> <span class="k">do</span>
+  <span class="c1"># Add idea specific jar dependency to .iml file</span>
+  <span class="n">iml</span><span class="o">.</span><span 
class="n">main_dependencies</span> <span class="o">&lt;&lt;</span> <span 
class="s1">&#39;group:id:jar:1.0&#39;</span>
+
+  <span class="c1"># Add idea specific test jar dependency to .iml file</span>
+  <span class="n">iml</span><span class="o">.</span><span 
class="n">test_dependencies</span> <span class="o">&lt;&lt;</span> <span 
class="s1">&#39;group:id:jar:1.0&#39;</span>
+  <span class="o">.</span><span class="n">.</span><span class="o">.</span>
+<span class="k">end</span></code></pre></figure><h4>Dependency generation</h4>
+<p>A file dependency that exists in the local maven 2 repository is stored in 
the <span class="caps">IML</span> file relative to the 
<code>$MAVEN_REPOSITORY$</code> environment variable (that defaults to 
<code>~/.m2/repository</code>). The user can override the environment variable 
by setting the &#8220;iml.local_repository_env_override&#8221; setting. If the 
dependency does not exist in to maven repository or the 
&#8220;iml.local_repository_env_override&#8221; setting is set to nil, then the 
path stored in the <span class="caps">IML</span> is relative to the <span 
class="caps">IML</span> file.</p>
+<h5>Example: Setting local_repository_env_override</h5>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s2">&quot;foo&quot;</span> <span class="k">do</span>
+  <span class="n">iml</span><span class="o">.</span><span 
class="n">local_repository_env_override</span> <span class="o">=</span> <span 
class="kp">nil</span>
+  <span class="n">compile</span><span class="o">.</span><span 
class="n">with</span> <span class="s1">&#39;group:id:jar:1.0&#39;</span>
+<span class="k">end</span></code></pre></figure><p>Will generate a dependency 
with a path like:</p>
+<pre>
+jar:///home/peter/.m2/repository/group/id/1.0/id-1.0.jar!/
+</pre>
+<p>rather than the default</p>
+<pre>
+jar://$MAVEN_REPOSITORY$/group/id/1.0/id-1.0.jar!/
+</pre>
+<h5>Example: A dependency outside the maven repository</h5>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s2">&quot;foo&quot;</span> <span class="k">do</span>
+  <span class="n">compile</span><span class="o">.</span><span 
class="n">with</span> <span class="n">_</span><span class="p">(</span><span 
class="s2">&quot;foos-dep.jar&quot;</span><span class="p">)</span>
+<span class="k">end</span></code></pre></figure><p>Will generate a dependency 
with a path like:</p>
+<pre>
+jar://$MODULE_DIR$/foo-dep.jar!/
+</pre>
+<h4>Module Facets</h4>
+<p>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 <code>.iml</code> with the appropriate 
facets via the &#8220;iml.add_facet&#8221; method. It should be noted that 
facets are <span class="caps">NOT</span> inherited by sub-projects.</p>
+<h5>Example</h5>
+<p>This example adds the web facet to a project.</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s2">&quot;foo&quot;</span> <span class="k">do</span>
+  <span class="n">iml</span><span class="o">.</span><span 
class="n">add_facet</span><span class="p">(</span><span 
class="s2">&quot;Web&quot;</span><span class="p">,</span><span 
class="s2">&quot;web&quot;</span><span class="p">)</span> <span 
class="k">do</span> <span class="o">|</span><span class="n">facet</span><span 
class="o">|</span>
+    <span class="n">facet</span><span class="o">.</span><span 
class="n">configuration</span> <span class="k">do</span> <span 
class="o">|</span><span class="n">conf</span><span class="o">|</span>
+      <span class="n">conf</span><span class="o">.</span><span 
class="n">descriptors</span> <span class="k">do</span> <span 
class="o">|</span><span class="n">desc</span><span class="o">|</span>
+        <span class="n">desc</span><span class="o">.</span><span 
class="n">deploymentDescriptor</span> <span class="ss">:name</span> <span 
class="o">=&gt;</span> <span class="s1">&#39;web.xml&#39;</span><span 
class="p">,</span>
+          <span class="ss">:url</span> <span class="o">=&gt;</span> <span 
class="s2">&quot;file://$MODULE_DIR$/src/main/webapp/WEB-INF/web.xml&quot;</span><span
 class="p">,</span>
+          <span class="ss">:optional</span> <span class="o">=&gt;</span> <span 
class="s2">&quot;false&quot;</span><span class="p">,</span> <span 
class="ss">:version</span> <span class="o">=&gt;</span> <span 
class="s2">&quot;2.4&quot;</span>
+      <span class="k">end</span>
+      <span class="n">conf</span><span class="o">.</span><span 
class="n">webroots</span> <span class="k">do</span> <span 
class="o">|</span><span class="n">webroots</span><span class="o">|</span>
+        <span class="n">webroots</span><span class="o">.</span><span 
class="n">root</span> <span class="ss">:url</span> <span class="o">=&gt;</span> 
<span class="s2">&quot;file://$MODULE_DIR$/src/main/webapp&quot;</span><span 
class="p">,</span> <span class="ss">:relative</span> <span 
class="o">=&gt;</span> <span class="s2">&quot;/&quot;</span>
+      <span class="k">end</span>
+    <span class="k">end</span>
+  <span class="k">end</span>
+<span class="k">end</span></code></pre></figure><h4>Project Configurations</h4>
+<p>Configurations are IDEAs mechanism for running or debugging the project. 
Shared configurations are stored in the project file. The extension makes it 
possible to generate an <code>.ipr</code> with specific configurations via the 
&#8220;ipr.add_configuration&#8221; method.</p>
+<h5>Example</h5>
+<p>This example adds a configuration to invoke a <span class="caps">GWT</span> 
application.</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s2">&quot;foo&quot;</span> <span class="k">do</span>
+  <span class="o">.</span><span class="n">.</span><span class="o">.</span>
+  <span class="n">ipr</span><span class="o">.</span><span 
class="n">add_configuration</span><span class="p">(</span><span 
class="s2">&quot;Run Contacts.html&quot;</span><span class="p">,</span> <span 
class="s2">&quot;GWT.ConfigurationType&quot;</span><span class="p">,</span> 
<span class="s2">&quot;GWT Configuration&quot;</span><span class="p">)</span> 
<span class="k">do</span> <span class="o">|</span><span 
class="n">xml</span><span class="o">|</span>
+    <span class="n">xml</span><span class="o">.</span><span 
class="n">module</span><span class="p">(</span><span class="ss">:name</span> 
<span class="o">=&gt;</span> <span class="n">project</span><span 
class="o">.</span><span class="n">iml</span><span class="o">.</span><span 
class="n">id</span><span class="p">)</span>
+    <span class="n">xml</span><span class="o">.</span><span 
class="n">option</span><span class="p">(</span><span class="ss">:name</span> 
<span class="o">=&gt;</span> <span class="s2">&quot;RUN_PAGE&quot;</span><span 
class="p">,</span> <span class="ss">:value</span> <span class="o">=&gt;</span> 
<span class="s2">&quot;Contacts.html&quot;</span><span class="p">)</span>
+    <span class="n">xml</span><span class="o">.</span><span 
class="n">option</span><span class="p">(</span><span class="ss">:name</span> 
<span class="o">=&gt;</span> <span 
class="s2">&quot;compilerParameters&quot;</span><span class="p">,</span> <span 
class="ss">:value</span> <span class="o">=&gt;</span> <span 
class="s2">&quot;-draftCompile -localWorkers 2&quot;</span><span 
class="p">)</span>
+    <span class="n">xml</span><span class="o">.</span><span 
class="n">option</span><span class="p">(</span><span class="ss">:name</span> 
<span class="o">=&gt;</span> <span 
class="s2">&quot;compilerMaxHeapSize&quot;</span><span class="p">,</span> <span 
class="ss">:value</span> <span class="o">=&gt;</span> <span 
class="s2">&quot;512&quot;</span><span class="p">)</span>
+
+    <span class="n">xml</span><span class="o">.</span><span 
class="n">RunnerSettings</span><span class="p">(</span><span 
class="ss">:RunnerId</span> <span class="o">=&gt;</span> <span 
class="s2">&quot;Run&quot;</span><span class="p">)</span>
+    <span class="n">xml</span><span class="o">.</span><span 
class="n">ConfigurationWrapper</span><span class="p">(</span><span 
class="ss">:RunnerId</span> <span class="o">=&gt;</span> <span 
class="s2">&quot;Run&quot;</span><span class="p">)</span>
+    <span class="n">xml</span><span class="o">.</span><span 
class="n">method</span><span class="p">()</span>
+  <span class="k">end</span>
+<span class="k">end</span></code></pre></figure><h4>Project Artifacts</h4>
+<p><span class="caps">IDEA</span> can build artifacts such as jars and wars. 
The artifact configuration is stored in the project file. The extension makes 
it possible to generate an <code>.ipr</code> with specific artifacts via the 
&#8220;ipr.add_artifact&#8221; method.</p>
+<h5>Example</h5>
+<p>This example adds a jar artifact to the project.</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s2">&quot;foo&quot;</span> <span class="k">do</span>
+  <span class="o">.</span><span class="n">.</span><span class="o">.</span>
+  <span class="n">ipr</span><span class="o">.</span><span 
class="n">add_artifact</span><span class="p">(</span><span 
class="s2">&quot;MyFancy.jar&quot;</span><span class="p">,</span> <span 
class="s2">&quot;jar&quot;</span><span class="p">)</span> <span 
class="k">do</span> <span class="o">|</span><span class="n">xml</span><span 
class="o">|</span>
+    <span class="n">xml</span><span class="o">.</span><span 
class="n">tag!</span><span class="p">(</span><span 
class="s1">&#39;output-path&#39;</span><span class="p">,</span> <span 
class="n">project</span><span class="o">.</span><span class="n">_</span><span 
class="p">(</span><span class="ss">:artifacts</span><span class="p">,</span> 
<span class="s2">&quot;MyFancy.jar&quot;</span><span class="p">))</span>
+    <span class="n">xml</span><span class="o">.</span><span 
class="n">element</span> <span class="ss">:id</span> <span 
class="o">=&gt;</span> <span class="s2">&quot;module-output&quot;</span><span 
class="p">,</span> <span class="ss">:name</span> <span class="o">=&gt;</span> 
<span class="s2">&quot;foo&quot;</span>
+  <span class="k">end</span>
+<span class="k">end</span></code></pre></figure><h4>Custom Component 
Sections</h4>
+<p>If the extension does not provide capability to generate configuration for 
a particular <span class="caps">IDEA</span> plugin the user can provide their 
own configuration data via the &#8220;ipr.add_component&#8221; or 
&#8220;iml.add_component&#8221; methods.</p>
+<h5>Example: Adding .ipr specific component</h5>
+<p>This example changes the compiler configuration for project.</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s2">&quot;foo&quot;</span> <span class="k">do</span>
+  <span class="n">ipr</span><span class="o">.</span><span 
class="n">add_component</span><span class="p">(</span><span 
class="s2">&quot;CompilerConfiguration&quot;</span><span class="p">)</span> 
<span class="k">do</span> <span class="o">|</span><span 
class="n">component</span><span class="o">|</span>
+    <span class="n">component</span><span class="o">.</span><span 
class="n">option</span> <span class="ss">:name</span> <span 
class="o">=&gt;</span> <span class="s1">&#39;DEFAULT_COMPILER&#39;</span><span 
class="p">,</span> <span class="ss">:value</span> <span class="o">=&gt;</span> 
<span class="s1">&#39;Javac&#39;</span>
+    <span class="n">component</span><span class="o">.</span><span 
class="n">option</span> <span class="ss">:name</span> <span 
class="o">=&gt;</span> <span class="s1">&#39;DEPLOY_AFTER_MAKE&#39;</span><span 
class="p">,</span> <span class="ss">:value</span> <span class="o">=&gt;</span> 
<span class="s1">&#39;0&#39;</span>
+    <span class="n">component</span><span class="o">.</span><span 
class="n">resourceExtensions</span> <span class="k">do</span> <span 
class="o">|</span><span class="n">xml</span><span class="o">|</span>
+      <span class="n">xml</span><span class="o">.</span><span 
class="n">entry</span> <span class="ss">:name</span> <span 
class="o">=&gt;</span> <span class="s1">&#39;.+\.nonexistent&#39;</span>
+    <span class="k">end</span>
+    <span class="n">component</span><span class="o">.</span><span 
class="n">wildcardResourceExtensions</span> <span class="k">do</span> <span 
class="o">|</span><span class="n">xml</span><span class="o">|</span>
+      <span class="n">xml</span><span class="o">.</span><span 
class="n">entry</span> <span class="ss">:name</span> <span 
class="o">=&gt;</span> <span class="s1">&#39;?*.nonexistent&#39;</span>
+    <span class="k">end</span>
+  <span class="k">end</span>
+<span class="k">end</span></code></pre></figure><h5>Example: Adding .iml 
specific component</h5>
+<p>This example adds the web facet to a project. Note: This overrides the 
facets defined by the &#8220;iml.add_facet&#8221; method.</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s2">&quot;foo&quot;</span> <span class="k">do</span>
+  <span class="n">iml</span><span class="o">.</span><span 
class="n">add_component</span><span class="p">(</span><span 
class="s2">&quot;FacetManager&quot;</span><span class="p">)</span> <span 
class="k">do</span> <span class="o">|</span><span 
class="n">component</span><span class="o">|</span>
+    <span class="n">component</span><span class="o">.</span><span 
class="n">facet</span> <span class="ss">:type</span> <span 
class="o">=&gt;</span> <span class="s1">&#39;web&#39;</span><span 
class="p">,</span> <span class="ss">:name</span> <span class="o">=&gt;</span> 
<span class="s1">&#39;Web&#39;</span> <span class="k">do</span> <span 
class="o">|</span><span class="n">facet</span><span class="o">|</span>
+      <span class="n">facet</span><span class="o">.</span><span 
class="n">configuration</span> <span class="k">do</span> <span 
class="o">|</span><span class="n">conf</span><span class="o">|</span>
+        <span class="n">conf</span><span class="o">.</span><span 
class="n">descriptors</span> <span class="k">do</span> <span 
class="o">|</span><span class="n">desc</span><span class="o">|</span>
+          <span class="n">desc</span><span class="o">.</span><span 
class="n">deploymentDescriptor</span> <span class="ss">:name</span> <span 
class="o">=&gt;</span> <span class="s1">&#39;web.xml&#39;</span><span 
class="p">,</span>
+            <span class="ss">:url</span> <span class="o">=&gt;</span> <span 
class="s2">&quot;file://$MODULE_DIR$/src/main/webapp/WEB-INF/web.xml&quot;</span><span
 class="p">,</span>
+            <span class="ss">:optional</span> <span class="o">=&gt;</span> 
<span class="s2">&quot;false&quot;</span><span class="p">,</span> <span 
class="ss">:version</span> <span class="o">=&gt;</span> <span 
class="s2">&quot;2.4&quot;</span>
+        <span class="k">end</span>
+        <span class="n">conf</span><span class="o">.</span><span 
class="n">webroots</span> <span class="k">do</span> <span 
class="o">|</span><span class="n">webroots</span><span class="o">|</span>
+          <span class="n">webroots</span><span class="o">.</span><span 
class="n">root</span> <span class="ss">:url</span> <span class="o">=&gt;</span> 
<span class="s2">&quot;file://$MODULE_DIR$/src/main/webapp&quot;</span><span 
class="p">,</span> <span class="ss">:relative</span> <span 
class="o">=&gt;</span> <span class="s2">&quot;/&quot;</span>
+        <span class="k">end</span>
+      <span class="k">end</span>
+    <span class="k">end</span>
+  <span class="k">end</span>
+<span class="k">end</span></code></pre></figure><h4>Templates</h4>
+<p>The underlying project files are xml the contain elements for a number of 
&#8220;components&#8221;. 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 
&#8220;ipr.template&#8221; or &#8220;iml.template&#8221; 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).</p>
+<h5>Example</h5>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s2">&quot;foo&quot;</span> <span class="k">do</span>
+  <span class="n">ipr</span><span class="o">.</span><span 
class="n">template</span> <span class="o">=</span> <span 
class="s1">&#39;project.ipr.template&#39;</span>
+  <span class="n">iml</span><span class="o">.</span><span 
class="n">template</span> <span class="o">=</span> <span 
class="s1">&#39;module.iml.template&#39;</span>
+<span class="k">end</span></code></pre></figure><h4>Groups</h4>
+<p><span class="caps">IDEA</span> provides the facility to organise modules 
into groups. By default the extension does not do this but it can be enabled by 
&#8220;iml.group&#8221; setting. If that setting is set to true then the 
<code>.iml</code> 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.</p>
+<h5>Example</h5>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s2">&quot;foo&quot;</span> <span class="k">do</span>
+  <span class="n">iml</span><span class="o">.</span><span 
class="n">group</span> <span class="o">=</span> <span class="kp">true</span>
+  <span class="n">define</span> <span class="s1">&#39;bar&#39;</span> <span 
class="k">do</span>
+    <span class="n">define</span> <span class="s1">&#39;baz&#39;</span>
+  <span class="k">end</span>
+  <span class="n">define</span> <span class="s1">&#39;rab&#39;</span> <span 
class="k">do</span>
+    <span class="n">iml</span><span class="o">.</span><span 
class="n">group</span> <span class="o">=</span> <span 
class="s2">&quot;MyGroup&quot;</span>
+  <span class="k">end</span>
+<span class="k">end</span></code></pre></figure><p>Will place the generated 
.imls in the following groups:</p>
+<pre>
+foo.iml                =&gt; ''
+bar/bar.iml            =&gt; 'foo'
+bar/baz/baz.iml        =&gt; 'foo/bar'
+rab/rab.iml            =&gt; 'MyGroup'
+</pre>
+<h4>Add Extra .iml files to .ipr</h4>
+<p>The &#8216;ipr.extra_modules&#8217; 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.</p>
+<h5>Example</h5>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s2">&quot;foo&quot;</span> <span class="k">do</span>
+  <span class="n">ipr</span><span class="o">.</span><span 
class="n">extra_modules</span> <span class="o">&lt;&lt;</span> <span 
class="s1">&#39;other.iml&#39;</span>
+  <span class="n">ipr</span><span class="o">.</span><span 
class="n">extra_modules</span> <span class="o">&lt;&lt;</span> <span 
class="s1">&#39;other_other.iml&#39;</span>
+<span class="k">end</span></code></pre></figure><p>Will add the 
&#8216;other.iml&#8217; and &#8216;other_other.iml&#8217; files to the 
<code>.ipr</code> project files.</p>
+<h4>Buildr plugin for <span class="caps">IDEA</span></h4>
+<p>Also, check out the <a 
href="http://www.digitalsanctum.com/buildr-plug-in/";>Buildr plugin for <span 
class="caps">IDEA</span></a> (<span class="caps">IDEA</span> 7 and later).  
Once installed, open your project with <span class="caps">IDEA</span>.  If 
<span class="caps">IDEA</span> finds that you have Buildr installed and finds a 
buildfile in the project&#8217;s directory, it will show all the tasks 
available for that project.  To run a task, double-click it.  When the task 
completes, <span class="caps">IDEA</span> will show the results in the Buildr 
Output window.</p>
+<h2 id="cobertura_emma">Cobertura, Emma</h2>
+<p>You can use <a href="http://cobertura.sourceforge.net/";>Cobertura</a> or <a 
href="http://emma.sourceforge.net/";>Emma</a> to instrument your code, run the 
tests and create a test coverage report in either <span 
class="caps">HTML</span> or <span class="caps">XML</span> format.</p>
+<p>There are two main tasks for each tool, both of which generate a test 
coverage report in the <code>reports/cobertura</code> (respectively 
<code>reports/emma</code>) directory.  For example:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>buildr <span class="nb">test 
</span>cobertura:html</code></pre></figure><p>As you can guess, the other tasks 
are <code>cobertura:xml</code>, <code>emma:html</code> and 
<code>emma:xml</code>.</p>
+<p>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.</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>buildr 
subModule:cobertura:html</code></pre></figure><p>Each project can specify which 
classes to include or exclude from cobertura instrumentation by giving a 
class-name regexp to the <code>cobertura.include</code> or 
<code>cobertura.exclude</code> methods:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s1">&#39;someModule&#39;</span> <span class="k">do</span>
+  <span class="n">cobertura</span><span class="o">.</span><span 
class="n">include</span> <span class="s1">&#39;some.package.==*==&#39;</span>
+  <span class="n">cobertura</span><span class="o">.</span><span 
class="n">include</span> <span class="sr">/some.(foo|bar).==*==/</span>
+  <span class="n">cobertura</span><span class="o">.</span><span 
class="n">exclude</span> <span 
class="s1">&#39;some.foo.util.SimpleUtil&#39;</span>
+  <span class="n">cobertura</span><span class="o">.</span><span 
class="n">exclude</span> <span class="o">/==*==.</span><span 
class="n">Const</span><span class="p">(</span><span class="n">ants</span><span 
class="p">)?</span><span class="o">/</span><span class="n">i</span>
+<span class="k">end</span></code></pre></figure><p>Emma has 
<code>include</code> and <code>exclude</code> methods too, but they take glob 
patterns instead of regexps.</p>
+<p>Cobertura also provides a <code>cobertura:check</code> task.  This task is 
intended to be used as a dependency for other tasks (such as 
<code>deploy</code>) which might wish to fail if coverage is unacceptable.  The 
respective thresholds for task failure may be defined using the 
<code>cobertura.check</code> configuration namespace.  For example:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s1">&#39;someModule&#39;</span> <span class="k">do</span>
+  <span class="n">cobertura</span><span class="o">.</span><span 
class="n">check</span><span class="o">.</span><span 
class="n">branch_rate</span> <span class="o">=</span> <span class="mi">75</span>
+  <span class="n">cobertura</span><span class="o">.</span><span 
class="n">check</span><span class="o">.</span><span class="n">line_rate</span> 
<span class="o">=</span> <span class="mi">100</span>
+  <span class="n">cobertura</span><span class="o">.</span><span 
class="n">check</span><span class="o">.</span><span 
class="n">total_line_rate</span> <span class="o">=</span> <span 
class="mi">98</span>
+
+  <span class="n">task</span><span class="p">(</span><span 
class="ss">:deploy</span><span class="p">)</span><span class="o">.</span><span 
class="n">enhance</span> <span class="s1">&#39;cobertura:check&#39;</span>
+<span class="k">end</span></code></pre></figure><p>The 
<code>cobertura:check</code> task supports all of the configuration parameters 
allowed by the <code>cobertura-check</code> Ant task (as <a 
href="http://cobertura.sourceforge.net/anttaskreference.html";>documented 
here</a>).  Configuration parameters are &#8220;Ruby-ized&#8221; (as 
demonstrated in the example above).</p>
+<p>We want Buildr to load fast, and not everyone cares for these tasks, so we 
don&#8217;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:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="nb">require</span> <span 
class="s1">&#39;buildr/java/cobertura&#39;</span>
+<span class="nb">require</span> <span 
class="s1">&#39;buildr/java/emma&#39;</span></code></pre></figure><p>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 <code>buildr.rb</code> file in the <code>.buildr</code> 
directory under your home directory.</p>
+<p>Another option is to require it from the command line 
(<code>--require</code> or <code>-r</code>), for example:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>buildr -rbuildr/java/cobertura 
cobertura:html</code></pre></figure><h2 id="checkstyle">Checkstyle</h2>
+<p>Checkstyle is integrated into Buildr through an extension. The extension 
adds the &#8220;checkstyle:xml&#8221; task that generates an xml report listing 
checkstyle violations and a &#8220;checkstyle:html&#8221; task to generate the 
html variant. A typical project that uses the extension may look something 
like;</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="nb">require</span> <span 
class="s1">&#39;buildr/checkstyle&#39;</span>
+
+<span class="n">define</span> <span class="s2">&quot;foo&quot;</span> <span 
class="k">do</span>
+  <span class="n">project</span><span class="o">.</span><span 
class="n">version</span> <span class="o">=</span> <span 
class="s2">&quot;1.0.0&quot;</span>
+
+  <span class="n">define</span> <span class="s2">&quot;bar&quot;</span> <span 
class="k">do</span> <span class="o">.</span><span class="n">.</span><span 
class="o">.</span> <span class="k">end</span>
+
+  <span class="n">checkstyle</span><span class="o">.</span><span 
class="n">config_directory</span> <span class="o">=</span> <span 
class="n">_</span><span class="p">(</span><span 
class="s1">&#39;etc/checkstyle&#39;</span><span class="p">)</span>
+  <span class="n">checkstyle</span><span class="o">.</span><span 
class="n">source_paths</span> <span class="o">&lt;&lt;</span> <span 
class="n">project</span><span class="p">(</span><span 
class="s1">&#39;bar&#39;</span><span class="p">)</span><span 
class="o">.</span><span class="n">_</span><span class="p">(</span><span 
class="ss">:source</span><span class="p">,</span> <span 
class="ss">:main</span><span class="p">,</span> <span 
class="ss">:java</span><span class="p">)</span>
+  <span class="n">checkstyle</span><span class="o">.</span><span 
class="n">extra_dependencies</span> <span class="o">&lt;&lt;</span> <span 
class="ss">:javax_servlet</span>
+
+<span class="k">end</span></code></pre></figure><p>By default checkstyle will 
look for all configuration files in the src/main/etc/checkstyle directory but 
this can be overriden by the setting the 
&#8220;checkstyle.config_directory&#8221; parameter. The 
&#8220;checkstyle:xml&#8221; task will be defined if the checkstyle rules file 
is found. The rules file is typically named &#8220;checks.xml&#8221; but can be 
overridden by setting the &#8220;checkstyle.configuration_file&#8221; 
parameter. If a suppressions file or import control file is included in the 
directory, these will also be used by the extension. These names of these files 
will default to &#8220;suppressions.xml&#8221; and 
&#8220;import-control.xml&#8221; but these can be overriden by the parameters 
&#8220;checkstyle.suppressions_file&#8221; and 
&#8220;checkstyle.import_control_file&#8221;.</p>
+<p>The extension will include the source and test directories of the project 
aswell as the compile and test dependencies when invoking the checkstyle tool. 
These can be added to by the parameters &#8220;checkstyle.source_paths&#8221; 
and &#8220;checkstyle.extra_dependencies&#8221; as appropriate.</p>
+<p>If the xsl file named &#8220;checkstyle-report.xsl&#8221; is present in the 
configuration directory then it will be used to generate the html report, 
otherwise a xsl file that comes with buildr will be used. The name of the xsl 
file can be overridden by the parameter &#8220;checkstyle.style_file&#8221;.</p>
+<h2 id="findbugs">FindBugs</h2>
+<p>FindBugs is integrated into Buildr through an extension. The extension adds 
the &#8220;findbugs:xml&#8221; task that generates an xml report listing 
findbugs violations and may add a &#8220;findbugs:html&#8221; task if an 
appropriate xsl is present. A typical project that uses the extension may look 
something like;</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="nb">require</span> <span 
class="s1">&#39;buildr/findbugs&#39;</span>
+
+<span class="n">define</span> <span class="s2">&quot;foo&quot;</span> <span 
class="k">do</span>
+  <span class="n">project</span><span class="o">.</span><span 
class="n">version</span> <span class="o">=</span> <span 
class="s2">&quot;1.0.0&quot;</span>
+
+  <span class="n">define</span> <span class="s2">&quot;bar&quot;</span> <span 
class="k">do</span> <span class="o">.</span><span class="n">.</span><span 
class="o">.</span> <span class="k">end</span>
+
+  <span class="n">findbugs</span><span class="o">.</span><span 
class="n">config_directory</span> <span class="o">=</span> <span 
class="n">_</span><span class="p">(</span><span 
class="s1">&#39;etc/findbugs&#39;</span><span class="p">)</span>
+  <span class="n">findbugs</span><span class="o">.</span><span 
class="n">source_paths</span> <span class="o">&lt;&lt;</span> <span 
class="n">project</span><span class="p">(</span><span 
class="s1">&#39;bar&#39;</span><span class="p">)</span><span 
class="o">.</span><span class="n">_</span><span class="p">(</span><span 
class="ss">:source</span><span class="p">,</span> <span 
class="ss">:main</span><span class="p">,</span> <span 
class="ss">:java</span><span class="p">)</span>
+  <span class="n">findbugs</span><span class="o">.</span><span 
class="n">analyze_paths</span> <span class="o">&lt;&lt;</span> <span 
class="n">project</span><span class="p">(</span><span 
class="s1">&#39;bar&#39;</span><span class="p">)</span><span 
class="o">.</span><span class="n">compile</span><span class="o">.</span><span 
class="n">target</span>
+  <span class="n">findbugs</span><span class="o">.</span><span 
class="n">extra_dependencies</span> <span class="o">&lt;&lt;</span> <span 
class="n">project</span><span class="p">(</span><span 
class="s1">&#39;bar&#39;</span><span class="p">)</span><span 
class="o">.</span><span class="n">compile</span><span class="o">.</span><span 
class="n">dependencies</span>
+
+<span class="k">end</span></code></pre></figure><p>By default findbugs will 
look for all configuration files in the src/main/etc/findbugs directory but 
this can be overriden by the setting the 
&#8220;findbugs.config_directory&#8221; parameter. The 
&#8220;findbugs:xml&#8221; task will past FindBugs a filter xml if a file named 
&#8220;filter.xml&#8221; is present in the configuration directory. This can be 
overridden by setting the &#8220;findbugs.filter_file&#8221; parameter.</p>
+<p>The extension will include the source and test directories of the project 
aswell as the compile and test dependencies when invoking the findbugs tool. 
These can be added to by the parameters &#8220;findbugs.source_paths&#8221; and 
&#8220;findbugs.extra_dependencies&#8221; as appropriate. The actual analysis 
is run across compiled artifacts ad this will default to the target directory 
of the project but this can be overriden by the 
&#8220;findbugs.analyze_paths&#8221; parameter.</p>
+<p>If the xsl file named &#8220;findbugs-report.xsl&#8221; is present in the 
configuration directory then a &#8220;findbugs:html&#8221; task will be 
defined. The name of the xsl file can be overridden by the parameter 
&#8220;findbugs.style_file&#8221;.</p>
+<h2 id="javancss">JavaNCSS</h2>
+<p>JavaNCSS is integrated into Buildr through an extension. The extension adds 
the &#8220;javancss:xml&#8221; task that generates an xml report and may add a 
&#8220;javancss:html&#8221; task if an appropriate xsl is present. A typical 
project that uses the extension may look something like;</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="nb">require</span> <span 
class="s1">&#39;buildr/javancss&#39;</span>
+
+<span class="n">define</span> <span class="s2">&quot;foo&quot;</span> <span 
class="k">do</span>
+  <span class="n">project</span><span class="o">.</span><span 
class="n">version</span> <span class="o">=</span> <span 
class="s2">&quot;1.0.0&quot;</span>
+
+  <span class="n">define</span> <span class="s2">&quot;bar&quot;</span> <span 
class="k">do</span> <span class="o">.</span><span class="n">.</span><span 
class="o">.</span> <span class="k">end</span>
+
+  <span class="n">javancss</span><span class="o">.</span><span 
class="n">enabled</span> <span class="o">=</span> <span class="kp">true</span>
+  <span class="n">javancss</span><span class="o">.</span><span 
class="n">config_directory</span> <span class="o">=</span> <span 
class="n">_</span><span class="p">(</span><span 
class="s1">&#39;etc/javancss&#39;</span><span class="p">)</span>
+  <span class="n">javancss</span><span class="o">.</span><span 
class="n">source_paths</span> <span class="o">&lt;&lt;</span> <span 
class="n">project</span><span class="p">(</span><span 
class="s1">&#39;bar&#39;</span><span class="p">)</span><span 
class="o">.</span><span class="n">_</span><span class="p">(</span><span 
class="ss">:source</span><span class="p">,</span> <span 
class="ss">:main</span><span class="p">,</span> <span 
class="ss">:java</span><span class="p">)</span>
+
+<span class="k">end</span></code></pre></figure><p>The extension will include 
the source and test directories of the project when invoking the javancss tool. 
These can be added to by the parameters &#8220;javancss.source_paths&#8221;.</p>
+<p>By default javancss will look for all configuration files in the 
src/main/etc/javancss directory but this can be overriden by the setting the 
&#8220;javancss.config_directory&#8221; parameter. The 
&#8220;javancss:xml&#8221; task will be defined if the 
&#8220;javancss.enabled&#8221; property is set to true. If the xsl file named 
&#8220;javancss2html.xsl&#8221; is present in the configuration directory then 
a &#8220;javancss:html&#8221; task will be defined. The name of the xsl file 
can be overridden by the parameter &#8220;javancss.style_file&#8221;.</p>
+<h2 id="jdepend">JDepend</h2>
+<p><a href="http://clarkware.com/software/JDepend.html";>JDepend</a> is 
integrated into Buildr through an extension. The extension adds the 
&#8220;jdepend:xml&#8221; task that generates an xml report, 
&#8220;jdepend:swing&#8221; that shows a Swing UI, and may add a 
&#8220;jdepend:html&#8221; task if an appropriate xsl is present. A typical 
project that uses the extension may look something like;</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="nb">require</span> <span 
class="s1">&#39;buildr/jdepend&#39;</span>
+
+<span class="n">define</span> <span class="s2">&quot;foo&quot;</span> <span 
class="k">do</span>
+  <span class="n">project</span><span class="o">.</span><span 
class="n">version</span> <span class="o">=</span> <span 
class="s2">&quot;1.0.0&quot;</span>
+
+  <span class="n">define</span> <span class="s2">&quot;bar&quot;</span> <span 
class="k">do</span> <span class="o">.</span><span class="n">.</span><span 
class="o">.</span> <span class="k">end</span>
+
+  <span class="n">jdepend</span><span class="o">.</span><span 
class="n">enabled</span> <span class="o">=</span> <span class="kp">true</span>
+  <span class="n">jdepend</span><span class="o">.</span><span 
class="n">config_directory</span> <span class="o">=</span> <span 
class="n">_</span><span class="p">(</span><span 
class="s1">&#39;etc/jdepend&#39;</span><span class="p">)</span>
+  <span class="n">jdepend</span><span class="o">.</span><span 
class="n">target_paths</span> <span class="o">&lt;&lt;</span> <span 
class="n">project</span><span class="p">(</span><span 
class="s1">&#39;bar&#39;</span><span class="p">)</span><span 
class="o">.</span><span class="n">compile</span><span class="o">.</span><span 
class="n">target</span>
+

[... 127 lines stripped ...]


Reply via email to