Added: dev/buildr/1.5.0/site/extending.html
==============================================================================
--- dev/buildr/1.5.0/site/extending.html (added)
+++ dev/buildr/1.5.0/site/extending.html Sat Sep 17 06:18:39 2016
@@ -0,0 +1,258 @@
+<html>
+  <head>
+    <meta content='text/html;charset=UTF-8' http-equiv='Content-Type'>
+    <title>buildr &mdash; Extending Buildr</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='extending buildr'>Extending Buildr</h1>
+        <ol class="toc"><li><a href="#tasks">Organizing Tasks</a></li><li><a 
href="#extensions">Creating Extensions</a></li><li><a href="#layouts">Using 
Alternative Layouts</a></li></ol>
+        <h2 id="tasks">Organizing Tasks</h2>
+<p>A couple of things we learned while working on Buildr.  Being able to write 
your own Rake tasks is a very powerful feature.  But if you find yourself doing 
the same thing over and over, you might also want to consider functions. They 
give you a lot more power and easy abstractions.</p>
+<p>For example, we use OpenJPA in several projects.  It&#8217;s a very short 
task, but each time I have to go back to the OpenJPA documentation to figure 
out how to set the Ant MappingTool task, tell Ant how to define it.  After the 
second time, you&#8217;re recognizing a pattern and it&#8217;s just easier to 
write a function that does all that for you.</p>
+<p>Compare this:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">file</span><span class="p">(</span><span 
class="s1">&#39;derby.sql&#39;</span><span class="p">)</span> <span 
class="k">do</span>
+  <span class="no">REQUIRES</span> <span class="o">=</span> <span 
class="o">[</span>
+    <span 
class="s1">&#39;org.apache.openjpa:openjpa-all:jar:0.9.7-incubating&#39;</span><span
 class="p">,</span>
+    <span 
class="s1">&#39;commons-collections:commons-collections:jar:3.1&#39;</span><span
 class="p">,</span>
+    <span class="o">.</span> <span class="o">.</span> <span class="o">.</span>
+    <span class="s1">&#39;net.sourceforge.serp:serp:jar:1.11.0&#39;</span> 
<span class="o">]</span>
+  <span class="n">ant</span><span class="p">(</span><span 
class="s1">&#39;openjpa&#39;</span><span class="p">)</span> <span 
class="k">do</span> <span class="o">|</span><span class="n">ant</span><span 
class="o">|</span>
+    <span class="n">ant</span><span class="o">.</span><span 
class="n">taskdef</span> <span class="ss">:name</span><span 
class="o">=&gt;</span><span class="s1">&#39;mapping&#39;</span><span 
class="p">,</span>
+      <span class="ss">:classname</span><span class="o">=&gt;</span><span 
class="s1">&#39;org.apache.openjpa.jdbc.ant.MappingToolTask&#39;</span><span 
class="p">,</span>
+      <span class="ss">:classpath</span><span class="o">=&gt;</span><span 
class="no">REQUIRES</span><span class="o">.</span><span 
class="n">join</span><span class="p">(</span><span class="no">File</span><span 
class="o">::</span><span class="no">PATH_SEPARATOR</span><span 
class="p">)</span>
+    <span class="n">ant</span><span class="o">.</span><span 
class="n">mapping</span> <span class="ss">:schemaAction</span><span 
class="o">=&gt;</span><span class="s1">&#39;build&#39;</span><span 
class="p">,</span> <span class="ss">:sqlFile</span><span 
class="o">=&gt;</span><span class="n">task</span><span class="o">.</span><span 
class="n">name</span><span class="p">,</span>
+      <span class="ss">:ignoreErrors</span><span class="o">=&gt;</span><span 
class="kp">true</span> <span class="k">do</span>
+        <span class="n">ant</span><span class="o">.</span><span 
class="n">config</span> <span class="ss">:propertiesFile</span><span 
class="o">=&gt;</span><span class="n">_</span><span class="p">(</span><span 
class="s1">&#39;src/main/sql/derby.xml&#39;</span><span class="p">)</span>
+        <span class="n">ant</span><span class="o">.</span><span 
class="n">classpath</span> <span class="ss">:path</span><span 
class="o">=&gt;</span><span class="n">projects</span><span 
class="p">(</span><span class="s1">&#39;store&#39;</span><span 
class="p">,</span> <span class="s1">&#39;utils&#39;</span> <span 
class="p">)</span><span class="o">.</span>
+          <span class="n">flatten</span><span class="o">.</span><span 
class="n">map</span><span class="p">(</span><span class="o">&amp;</span><span 
class="ss">:to_s</span><span class="p">)</span><span class="o">.</span><span 
class="n">join</span><span class="p">(</span><span class="no">File</span><span 
class="o">::</span><span class="no">PATH_SEPARATOR</span><span 
class="p">)</span>
+    <span class="k">end</span>
+  <span class="k">end</span>
+<span class="k">end</span></code></pre></figure><p>To this:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">file</span><span class="p">(</span><span 
class="s1">&#39;derby.sql&#39;</span><span class="p">)</span> <span 
class="k">do</span>
+  <span class="n">mapping_tool</span> <span class="ss">:action</span><span 
class="o">=&gt;</span><span class="s1">&#39;build&#39;</span><span 
class="p">,</span> <span class="ss">:sql</span><span 
class="o">=&gt;</span><span class="n">task</span><span class="o">.</span><span 
class="n">name</span><span class="p">,</span>
+    <span class="ss">:properties</span><span class="o">=&gt;</span><span 
class="n">_</span><span class="p">(</span><span 
class="s1">&#39;src/main/sql/derby.xml&#39;</span><span class="p">),</span>
+    <span class="ss">:classpath</span><span class="o">=&gt;</span><span 
class="n">projects</span><span class="p">(</span><span 
class="s1">&#39;store&#39;</span><span class="p">,</span> <span 
class="s1">&#39;utils&#39;</span><span class="p">)</span>
+<span class="k">end</span></code></pre></figure><p>I prefer the second.  
It&#8217;s easier to look at the Buildfile and understand what it does.  
It&#8217;s easier to maintain when you only have to look at the important 
information.</p>
+<p>But just using functions is not always enough.  You end up with a Buildfile 
containing a lot of code that clearly doesn&#8217;t belong there.  For 
starters, I recommend putting it in the <code>tasks</code> directory.  Write it 
into a file with a <code>.rake</code> extension and place that in the 
<code>tasks</code> directory next to the Buildfile.  Buildr will automatically 
pick it up and load it for you.</p>
+<p>If you want to share these pre-canned definitions between projects, you 
have a few more options.  You can share the <code>tasks</code> directory using 
<span class="caps">SVN</span> externals, Git modules, or whichever 
cross-repository feature your source control system supports. Another mechanism 
with better version control is to package all these tasks, functions and 
modules into a <a href="http://rubygems.org/";>Gem</a> and require it from your 
Buildfile.  You can run your own internal Gem server for that.</p>
+<p>To summarize, there are several common ways to distribute extensions:</p>
+<ul>
+       <li>Put them in the same place (e.g. <code>~/.buildr</code>) and 
require them from your<br />
+<code>buildfile</code></li>
+       <li>Put them directly in the project, typically under the 
<code>tasks</code> directory.</li>
+       <li>Put them in a shared code repository, and link to them from your 
project&#8217;s <code>tasks</code> directory</li>
+       <li>As Ruby gems and specify which gems are used in the settings 
file</li>
+</ul>
+<p>You can also get creative and devise your own way to distribute 
extensions.<br />
+<a href="http://errtheblog.com/post/6069";>Sake</a> is a good example of such 
initiative that lets you deploy Rake tasks on a system-wide basis.</p>
+<h2 id="extensions">Creating Extensions</h2>
+<p>The basic mechanism for extending projects in Buildr are Ruby modules.  In 
fact, base features like compiling and testing are all developed in the form of 
modules, and then added to the core Project class.</p>
+<p>A module defines instance methods that are then mixed into the project and 
become instance methods of the project.  There are two general ways for 
extending projects.  You can extend all projects by including the module in 
Project:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="k">class</span> <span class="nc">Project</span>
+  <span class="kp">include</span> <span class="no">MyExtension</span>
+<span class="k">end</span></code></pre></figure><p>You can also extend a given 
project instance and only that instance by extending it with the module:</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="kp">extend</span> <span class="no">MyExtension</span>
+<span class="k">end</span></code></pre></figure><p>Some extensions require 
tighter integration with the project, specifically for setting up tasks and 
properties, or for configuring tasks based on the project definition.  You can 
do that by adding callbacks to the process.</p>
+<p>The easiest way to add callbacks is by incorporating the Extension module 
in your own extension, and using the various class methods to define callback 
behavior.</p>
+<table>
+       <tr>
+               <th>Method        </th>
+               <th>Usage </th>
+       </tr>
+       <tr>
+               <td> <code>first_time</code>    </td>
+               <td> This block will be called once for any particular 
extension.  You can use this to setup top-level and local tasks. </td>
+       </tr>
+       <tr>
+               <td> <code>before_define</code> </td>
+               <td> This block is called once for the project with the project 
instance, right before running the project definition.  You can use this to add 
tasks and set properties that will be used in the project definition. </td>
+       </tr>
+       <tr>
+               <td> <code>after_define</code>  </td>
+               <td> This block is called once for the project with the project 
instance, right after running the project definition.  You can use this to do 
any post-processing that depends on the project definition. </td>
+       </tr>
+</table>
+<p>This example illustrates how to write a simple extension:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="k">module</span> <span 
class="nn">LinesOfCode</span>
+
+  <span class="kp">include</span> <span class="no">Extension</span>
+
+  <span class="n">first_time</span> <span class="k">do</span>
+    <span class="c1"># Define task not specific to any projet.</span>
+    <span class="n">desc</span> <span class="s1">&#39;Count lines of code in 
current project&#39;</span>
+    <span class="no">Project</span><span class="o">.</span><span 
class="n">local_task</span><span class="p">(</span><span 
class="s1">&#39;loc&#39;</span><span class="p">)</span>
+  <span class="k">end</span>
+
+  <span class="n">before_define</span> <span class="k">do</span> <span 
class="o">|</span><span class="n">project</span><span class="o">|</span>
+    <span class="c1"># Define the loc task for this particular project.</span>
+    <span class="n">project</span><span class="o">.</span><span 
class="n">recursive_task</span> <span class="s1">&#39;loc&#39;</span> <span 
class="k">do</span> <span class="o">|</span><span class="n">task</span><span 
class="o">|</span>
+      <span class="n">lines</span> <span class="o">=</span> <span 
class="n">task</span><span class="o">.</span><span 
class="n">prerequisites</span><span class="o">.</span><span 
class="n">map</span> <span class="p">{</span> <span class="o">|</span><span 
class="n">path</span><span class="o">|</span>
+        <span class="no">Dir</span><span class="o">[</span><span 
class="s2">&quot;</span><span class="si">#{</span><span 
class="n">path</span><span class="si">}</span><span 
class="s2">/**/*&quot;</span><span class="o">]</span>
+      <span class="p">}</span><span class="o">.</span><span 
class="n">uniq</span><span class="o">.</span><span class="n">select</span> 
<span class="p">{</span> <span class="o">|</span><span 
class="n">file</span><span class="o">|</span>
+        <span class="no">File</span><span class="o">.</span><span 
class="n">file?</span><span class="p">(</span><span class="n">file</span><span 
class="p">)</span>
+      <span class="p">}</span><span class="o">.</span><span 
class="n">inject</span><span class="p">(</span><span class="mi">0</span><span 
class="p">)</span> <span class="p">{</span> <span class="o">|</span><span 
class="n">total</span><span class="p">,</span> <span class="n">file</span><span 
class="o">|</span>
+        <span class="n">total</span> <span class="o">+</span> <span 
class="no">File</span><span class="o">.</span><span 
class="n">readlines</span><span class="p">(</span><span 
class="n">file</span><span class="p">)</span><span class="o">.</span><span 
class="n">count</span>
+      <span class="p">}</span>
+      <span class="nb">puts</span> <span class="s2">&quot;Project </span><span 
class="si">#{</span><span class="n">project</span><span class="o">.</span><span 
class="n">name</span><span class="si">}</span><span class="s2"> has 
</span><span class="si">#{</span><span class="n">lines</span><span 
class="si">}</span><span class="s2"> lines of code&quot;</span>
+      <span class="k">end</span>
+  <span class="k">end</span>
+
+  <span class="n">after_define</span> <span class="k">do</span> <span 
class="o">|</span><span class="n">project</span><span class="o">|</span>
+    <span class="c1"># Now that we know all the source directories, add 
them.</span>
+    <span class="n">task</span><span class="p">(</span><span 
class="s1">&#39;loc&#39;</span> <span class="o">=&gt;</span> <span 
class="n">project</span><span class="o">.</span><span 
class="n">compile</span><span class="o">.</span><span class="n">sources</span> 
<span class="o">+</span> <span class="n">project</span><span 
class="o">.</span><span class="n">test</span><span class="o">.</span><span 
class="n">sources</span><span class="p">)</span>
+  <span class="k">end</span>
+
+  <span class="c1"># To use this method in your project:</span>
+  <span class="c1"># loc path_1, path_2</span>
+  <span class="k">def</span> <span class="nf">loc</span><span 
class="p">(</span><span class="o">*</span><span class="n">paths</span><span 
class="p">)</span>
+    <span class="n">task</span><span class="p">(</span><span 
class="s1">&#39;loc&#39;</span> <span class="o">=&gt;</span> <span 
class="n">paths</span><span class="p">)</span>
+  <span class="k">end</span>
+
+<span class="k">end</span>
+
+<span class="k">class</span> <span class="nc">Buildr</span><span 
class="o">::</span><span class="no">Project</span>
+    <span class="kp">include</span> <span class="no">LinesOfCode</span>
+<span class="k">end</span></code></pre></figure><p>You may find interesting 
that this Extension <span class="caps">API</span> is used pervasively inside 
Buildr itself.  Many of the standard tasks such as <code>compile</code>, 
<code>test</code>, <code>package</code>  are extensions to a very small 
core.</p>
+<p>Starting with Buildr 1.4, it&#8217;s possible to define ordering between 
<code>before_define</code> and <code>after_define</code> code blocks in a way 
similar to Rake&#8217;s dependencies.  For example, if you wanted to override 
<code>project.test.compile.from</code> in <code>after_define</code>, you could 
do so by in</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">after_define</span><span 
class="p">(</span><span class="ss">:functional_tests</span><span 
class="p">)</span> <span class="k">do</span> <span class="o">|</span><span 
class="n">project</span><span class="o">|</span>
+  <span class="c1"># Change project.test.compile.from if it&#39;s not already 
pointing</span>
+  <span class="c1"># to a location with Java sources</span>
+  <span class="k">if</span> <span class="no">Dir</span><span 
class="o">[</span><span class="s2">&quot;</span><span class="si">#{</span><span 
class="n">project</span><span class="o">.</span><span 
class="n">test</span><span class="o">.</span><span 
class="n">compile</span><span class="o">.</span><span 
class="n">from</span><span class="si">}</span><span 
class="s2">/**/*.java&quot;</span><span class="o">].</span><span 
class="n">size</span> <span class="o">==</span> <span class="mi">0</span> <span 
class="o">&amp;&amp;</span>
+     <span class="no">Dir</span><span class="o">[</span><span 
class="s2">&quot;</span><span class="si">#{</span><span 
class="n">project</span><span class="o">.</span><span class="n">_</span><span 
class="p">(</span><span class="ss">:src</span><span class="p">,</span> <span 
class="s1">&#39;test-functional&#39;</span><span class="p">,</span> <span 
class="ss">:java</span><span class="p">)</span><span class="si">}</span><span 
class="s2">/**/*.java&quot;</span><span class="o">].</span><span 
class="n">size</span> <span class="o">&gt;</span> <span class="mi">0</span>
+    <span class="n">project</span><span class="o">.</span><span 
class="n">test</span><span class="o">.</span><span 
class="n">compile</span><span class="o">.</span><span class="n">from</span> 
<span class="n">project</span><span class="o">.</span><span 
class="n">_</span><span class="p">(</span><span class="ss">:src</span><span 
class="p">,</span> <span class="s1">&#39;test-functional&#39;</span><span 
class="p">,</span> <span class="ss">:java</span><span class="p">)</span>
+  <span class="k">end</span>
+<span class="k">end</span>
+
+<span class="c1"># make sure project.test.compile.from is updated before 
the</span>
+<span class="c1"># compile extension picks up its value</span>
+<span class="n">after_define</span><span class="p">(</span><span 
class="ss">:compile</span> <span class="o">=&gt;</span> <span 
class="ss">:functional_test</span><span 
class="p">)</span></code></pre></figure><p>Core extensions provide the 
following named callbacks: <code>compile</code>, <code>test</code>, 
<code>build</code>, <code>package</code> and <code>check</code>.</p>
+<h2 id="layouts">Using Alternative Layouts</h2>
+<p>Buildr follows a common convention for project layouts: Java source files 
appear in <code>src/main/java</code> and compile to 
<code>target/classes</code>, resources are copied over from 
<code>src/main/resources</code> and so forth.  Not all projects follow this 
convention, so it&#8217;s now possible to specify an alternative project 
layout.</p>
+<p>The default layout is available in <code>Layout.default</code>, and all 
projects inherit it.  You can set <code>Layout.default</code> to your own 
layout, or define a project with a given layout (recommended) by setting the 
<code>:layout</code> property.  Projects inherit the layout from their parent 
projects.  For example:</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="p">,</span> <span 
class="ss">:layout</span><span class="o">=&gt;</span><span 
class="n">my_layout</span> <span class="k">do</span>
+  <span class="o">.</span><span class="n">.</span><span class="o">.</span>
+<span class="k">end</span></code></pre></figure><p>A layout is an object that 
implements the <code>expand</code> method.  The easiest way to define a custom 
layout is to create a new <code>Layout</code> object and specify mapping 
between names used by Buildr and actual paths within the project.  For 
example:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">my_layout</span> <span class="o">=</span> 
<span class="no">Layout</span><span class="o">.</span><span class="n">new</span>
+<span class="n">my_layout</span><span class="o">[</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="o">]</span> <span class="o">=</span> <span 
class="s1">&#39;java&#39;</span>
+<span class="n">my_layout</span><span class="o">[</span><span 
class="ss">:source</span><span class="p">,</span> <span 
class="ss">:main</span><span class="p">,</span> <span 
class="ss">:resources</span><span class="o">]</span> <span class="o">=</span> 
<span class="s1">&#39;resources&#39;</span></code></pre></figure><p>Partial 
expansion also works, so you can specify the above layout using:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">my_layout</span> <span class="o">=</span> 
<span class="no">Layout</span><span class="o">.</span><span class="n">new</span>
+<span class="n">my_layout</span><span class="o">[</span><span 
class="ss">:source</span><span class="p">,</span> <span 
class="ss">:main</span><span class="o">]</span> <span class="o">=</span> <span 
class="s1">&#39;&#39;</span></code></pre></figure><p>If you need anything more 
complex, you can always subclass <code>Layout</code> and add special handling 
in the <code>expand</code> method, you&#8217;ll find one such example in the 
<span class="caps">API</span> documentation.</p>
+<p>The built-in tasks expand lists of symbols into relative paths, using the 
following convention:</p>
+<table>
+       <tr>
+               <th>Path                          </th>
+               <th>Expands to </th>
+       </tr>
+       <tr>
+               <td> <code>:source, :main, &lt;lang/usage&gt;</code>  </td>
+               <td>  Directory containing source files for a given language or 
usage, for example, <code>:java</code>, <code>:resources</code>, 
<code>:webapp</code>. </td>
+       </tr>
+       <tr>
+               <td> <code>:source, :test, &lt;lang/usage&gt;</code>  </td>
+               <td> Directory containing test files for a given language or 
usage, for example, <code>:java</code>, <code>:resources</code>. </td>
+       </tr>
+       <tr>
+               <td> <code>:target, :generated</code>           </td>
+               <td> Target directory for generated code (typically source 
code). </td>
+       </tr>
+       <tr>
+               <td> <code>:target, :main, &lt;lang/usage&gt;</code>  </td>
+               <td> Target directory for compiled code, for example, 
<code>:classes</code>, <code>:resources</code>. </td>
+       </tr>
+       <tr>
+               <td> <code>:target, :test, &lt;lang/usage&gt;</code>  </td>
+               <td> Target directory for compile test cases, for example, 
<code>:classes</code>, <code>:resources</code>. </td>
+       </tr>
+       <tr>
+               <td> <code>:reports, &lt;framework/usage&gt;</code>   </td>
+               <td> Target directory for generated reports, for example, 
<code>:junit</code>, <code>:coverage</code>. </td>
+       </tr>
+</table>
+<p>All tasks are encouraged to use the same convention, and whenever possible, 
we recommend using the project&#8217;s <code>path_to</code> method to expand a 
list of symbols into a path, or use the appropriate path when available.  For 
example:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s1">&#39;bad&#39;</span> <span class="k">do</span>
+  <span class="c1"># This may not be the real target.</span>
+  <span class="nb">puts</span> <span class="s1">&#39;Compiling to &#39;</span> 
<span class="o">+</span> <span class="n">path_to</span><span 
class="p">(</span><span class="s1">&#39;target/classes&#39;</span><span 
class="p">)</span>
+  <span class="c1"># This will break with different layouts.</span>
+  <span class="n">package</span><span class="p">(</span><span 
class="ss">:jar</span><span class="p">)</span><span class="o">.</span><span 
class="n">include</span> <span class="s1">&#39;src/main/etc/*&#39;</span>
+<span class="k">end</span>
+
+<span class="n">define</span> <span class="s1">&#39;good&#39;</span> <span 
class="k">do</span>
+  <span class="c1"># This is always the compiler&#39;s target.</span>
+  <span class="nb">puts</span> <span class="s1">&#39;Compiling to &#39;</span> 
<span class="o">+</span> <span class="n">compile</span><span 
class="o">.</span><span class="n">target</span><span class="o">.</span><span 
class="n">to_s</span>
+  <span class="c1"># This will work with different layouts.</span>
+  <span class="n">package</span><span class="p">(</span><span 
class="ss">:jar</span><span class="p">)</span><span class="o">.</span><span 
class="n">include</span> <span class="n">path_to</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">:etc</span><span class="p">,</span> <span 
class="s1">&#39;*&#39;</span><span class="p">)</span>
+<span class="k">end</span></code></pre></figure>
+      </div>
+      <div id='footer'>Copyright &copy; 2007-2016 The Apache Software 
Foundation</div>
+    </div>
+  </body>
+</html>

Added: dev/buildr/1.5.0/site/images/asf-logo.gif
==============================================================================
Binary file - no diff available.

Propchange: dev/buildr/1.5.0/site/images/asf-logo.gif
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: dev/buildr/1.5.0/site/images/asf-logo.png
==============================================================================
Binary file - no diff available.

Propchange: dev/buildr/1.5.0/site/images/asf-logo.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: dev/buildr/1.5.0/site/images/buildr-hires.png
==============================================================================
Binary file - no diff available.

Propchange: dev/buildr/1.5.0/site/images/buildr-hires.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: dev/buildr/1.5.0/site/images/buildr.png
==============================================================================
Binary file - no diff available.

Propchange: dev/buildr/1.5.0/site/images/buildr.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: dev/buildr/1.5.0/site/images/favicon.png
==============================================================================
Binary file - no diff available.

Propchange: dev/buildr/1.5.0/site/images/favicon.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: dev/buildr/1.5.0/site/images/growl-icon.tiff
==============================================================================
Binary file - no diff available.

Propchange: dev/buildr/1.5.0/site/images/growl-icon.tiff
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: dev/buildr/1.5.0/site/images/note.png
==============================================================================
Binary file - no diff available.

Propchange: dev/buildr/1.5.0/site/images/note.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: dev/buildr/1.5.0/site/images/project-structure.png
==============================================================================
Binary file - no diff available.

Propchange: dev/buildr/1.5.0/site/images/project-structure.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: dev/buildr/1.5.0/site/images/tip.png
==============================================================================
Binary file - no diff available.

Propchange: dev/buildr/1.5.0/site/images/tip.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: dev/buildr/1.5.0/site/images/zbuildr.png
==============================================================================
Binary file - no diff available.

Propchange: dev/buildr/1.5.0/site/images/zbuildr.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: dev/buildr/1.5.0/site/images/zbuildr.tif
==============================================================================
Binary file - no diff available.

Propchange: dev/buildr/1.5.0/site/images/zbuildr.tif
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: dev/buildr/1.5.0/site/index.html
==============================================================================
--- dev/buildr/1.5.0/site/index.html (added)
+++ dev/buildr/1.5.0/site/index.html Sat Sep 17 06:18:39 2016
@@ -0,0 +1,143 @@
+<html>
+  <head>
+    <meta content='text/html;charset=UTF-8' http-equiv='Content-Type'>
+    <title>buildr &mdash; Apache Buildr</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='apache buildr'>Apache Buildr</h1>
+        <ol class="toc"><li><a href="#why">Why Buildr Rocks</a></li><li><a 
href="#what">What You Get</a></li><li><a href="#news">What&#8217;s 
New</a></li><li><a href="#notices">Credits &amp; Notices</a></li></ol>
+        <p>Apache Buildr is a build system for Java-based applications, 
including support for Scala, Groovy and a growing number of <span 
class="caps">JVM</span> languages and tools.  We wanted something that&#8217;s 
simple and intuitive to use, so we only need to tell it what to do, and it 
takes care of the rest.  But also something we can easily extend for those 
one-off tasks, with a language that&#8217;s a joy to use.  And of course, we 
wanted it to be fast, reliable and have outstanding dependency management.</p>
+<h2 id="why">Why Buildr Rocks</h2>
+<p><a href="http://www.codecommit.com/blog";>Daniel Spiewak</a>:</p>
+<blockquote>
+<p>If you think about it, the question isn’t “Why use Buildr?”, it’s 
really “Why use anything else?” The advantages afforded by Buildr are so 
substantial, I really can’t see myself going with any other tool, at least 
not when I have a choice.</p>
+</blockquote>
+<p><a href="http://tristanhunt.com/";>Tristan Juricek</a>:</p>
+<blockquote>
+<p>That’s still the strongest sell: it builds everything I need, and as 
I’ve needed more, I just got things working without a lot of fuss.</p>
+</blockquote>
+<p><a href="http://offthelip.org/";>Matthieu Riou</a>:</p>
+<blockquote>
+<p>We used to rely on Ant, with a fairly extensive set of scripts. It worked 
but was expensive to maintain. The biggest mistake afterward was to migrate to 
Maven2. I could write pages of rants explaining all the problems we ran into 
and we still ended up with thousands of lines of <span 
class="caps">XML</span>.</p>
+</blockquote>
+<p><a href="http://www.javakaffee.de/blog/";>Martin Grotzke</a>:</p>
+<blockquote>
+<p>The positive side effect for me as a java user is that I learn a little 
ruby, and that’s easy but lots of fun… :-)</p>
+</blockquote>
+<p><a href="http://twitter.com/ijonas/statuses/4134103928";>Ijonas 
Kisselbach</a>:</p>
+<blockquote>
+<p>I&#8217;ve cleaned up &amp; migrated the Vamosa build process from 768 
lines of Ant build.xml to 28 lines of Buildr.</p>
+</blockquote>
+<h2 id="what">What You Get</h2>
+<ul>
+       <li>A simple way to specify projects, and build large projects out of 
smaller sub-projects.</li>
+       <li>Pre-canned tasks that require the least amount of configuration, 
keeping the build script <span class="caps">DRY</span> and simple.</li>
+       <li>Compiling, copying and filtering resources, JUnit/TestNG test 
cases, <span class="caps">APT</span> source code generation, Javadoc and 
more.</li>
+       <li>A dependency mechanism that only builds what has changed since the 
last release.</li>
+       <li>A drop-in replacement for Maven 2.0, Buildr uses the same file 
layout, artifact specifications, local and remote repositories.</li>
+       <li>All your Ant tasks are belong to us! Anything you can do with Ant, 
you can do with Buildr.</li>
+       <li>No overhead for building &#8220;plugins&#8221; or configuration. 
Just write new tasks or functions.</li>
+       <li>Buildr is Ruby all the way down.  No one-off task is too demanding 
when you write code using variables, functions and objects.</li>
+       <li>Simple way to upgrade to new versions.</li>
+       <li>Did we mention fast?</li>
+</ul>
+<p>So let&#8217;s get started.  You can <a href="quick_start.html">read the 
documentation online</a>, or <a href="buildr.pdf">download the <span 
class="caps">PDF</span></a>.</p>
+<h2 id="news">What&#8217;s New</h2>
+<p>Highlights from Buildr 1.5.0 (2016-09-16)</p>
+<ul>
+       <li>Change: Move to default on Scala 2.11.</li>
+       <li>Added:  <span class="caps">BUILDR</span>-577 Allow remote repo to 
be added with http basic auth support. Submitted by Michael Guymon.</li>
+       <li>Added:  <span class="caps">BUILDR</span>-572 Allow to upload unique 
version (timestamp based) snapshot artifacts to a repository. Submitted by 
Brice Figureau.</li>
+       <li>Added:  <span class="caps">BUILDR</span>-703 release: allow 
THIS_VERSION to be defined in another file</li>
+       <li>Fixed:  <span class="caps">BUILDR</span>-565 resources are not 
included in the war if defined after package call</li>
+       <li>Fixed:  <span class="caps">BUILDR</span>-621 ZipTask creates zip 
file with entries not sorted by path causing very slow unzipping.</li>
+       <li>Fixed:  <span class="caps">BUILDR</span>-695 transitive 
doesn&#8217;t support ${project.parent.version} in <span 
class="caps">POM</span>.</li>
+       <li>Fixed:  <span class="caps">BUILDR</span>-653 Using Eclipse compiler 
(<span class="caps">ECJ</span>)</li>
+       <li>Fixed:  <span class="caps">BUILDR</span>-476 Buildr doesn&#8217;t 
respect company repository manager</li>
+       <li>Fixed:  <span class="caps">BUILDR</span>-454 Definition-level 
parent-child references-by-name fail in 1.4.0 but not in 1.3.5. Submitted by 
Rhett Sutphin.</li>
+       <li>Fixed:  <span class="caps">BUILDR</span>-620 resources.filter 
should not run on non-text files</li>
+       <li>Fixed:  <span class="caps">BUILDR</span>-486 Buildr-generated poms 
should include dependencies</li>
+       <li>Change: Update the custom_pom addon to generate poms with 
exclusions section that excludes<br />
+          all transitive dependencies. This is required as buildr dependencies 
are not<br />
+          transitive while Maven&#8217;s dependencies are transitive by 
default.</li>
+</ul>
+<p>This is a partial list &#8212; see the <a href="CHANGELOG"><span 
class="caps">CHANGELOG</span></a> for full details.</p>
+<h2 id="notices">Credits &amp; Notices</h2>
+<p><a href="http://www.apache.org";><img 
src="http://www.apache.org/images/asf-logo.gif"; title="A project of the Apache 
Software Foundation" alt="A project of the Apache Software Foundation" 
/></a></p>
+<p>The Apache Software Foundation is a non-profit organization, consider <a 
href="http://www.apache.org/foundation/sponsorship.html";>sponsoring</a> and 
check the <a href="http://www.apache.org/foundation/thanks.html";>thanks</a> 
page.</p>
+<p><a 
href="http://www.mouserunner.com/Spheres_ColoCons1_Free_Icons.html";>ColorCons</a>,
 copyright of Ken Saunders.  <a href="http://dejavu.sourceforge.net";>DejaVu 
fonts</a>, copyright of Bitstream, Inc.</p>
+<p>Community member quotes from a thread on <a 
href="http://stackoverflow.com/questions/1015525/why-use-buildr-instead-of-ant-or-maven/1055864";>Stack
 Overflow</a>.</p>
+<p>Developed with <a 
href="http://www.jetbrains.com/ruby/features?utm_source=RubyMineUser&amp;utm_medium=Banner&amp;utm_campaign=RubyMine";><img
 
src="http://www.jetbrains.com/ruby/features/ruby_banners/ruby1/ruby120x30_white.gif";
 title="Developed with RubyMine" alt="Developed with RubyMine" /></a></p>
+      </div>
+      <div id='footer'>Copyright &copy; 2007-2016 The Apache Software 
Foundation</div>
+    </div>
+  </body>
+</html>

Added: dev/buildr/1.5.0/site/installing.html
==============================================================================
--- dev/buildr/1.5.0/site/installing.html (added)
+++ dev/buildr/1.5.0/site/installing.html Sat Sep 17 06:18:39 2016
@@ -0,0 +1,233 @@
+<html>
+  <head>
+    <meta content='text/html;charset=UTF-8' http-equiv='Content-Type'>
+    <title>buildr &mdash; Installing and Running</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='installing and running'>Installing and Running</h1>
+        <ol class="toc"><li><a href="#linux">Installing on 
Linux</a></li><li><a href="#osx">Installing on OS X</a></li><li><a 
href="#windows">Installing on Windows</a></li><li><a href="#jruby">Installing 
for JRuby</a></li><li>Using multiple versions of Buildr</li><li><a 
href="#running">Running Buildr</a></li><li><a href="#help">Help 
Tasks</a></li><li><a href="#more">Learning More</a></li></ol>
+        <h1 id="all-in-one">All In One Bundle</h1>
+<p>Contributors to this project maintain a separate distribution over on <a 
href="http://rubyforge.org/projects/buildr";>RubyForge</a>. Using this 
distribution, it is possible to install Buildr just like you would install 
Apache Ant or Apache Maven. It comes bundled with JRuby and distributed as a 
cross-platform zip or tar.gz file.</p>
+<p>The RubyForge distribution is <strong>not</strong> an official Apache 
distribution. The all-in-one bundles are hosted on the <a 
href="http://rubyforge.org/frs/?group_id=3180";>Files page</a>.</p>
+<p><strong>In details:</strong> Navigate to <a 
href="http://rubyforge.org/frs/?group_id=3180";>Rubyforge&#8217;s buildr&#8217;s 
Files page</a> and download the all-in-one bundle for the latest version 
available.</p>
+<p>Unzip the bundle in a convenient location.</p>
+<p>You can execute the buildr executable under the bin directory directly.</p>
+<p>You should consider adding the bin directory of the result to the 
<code>PATH</code> global environment variable. See <a href="#jruby">Installing 
Buildr for JRuby</a> for instructions to update it.</p>
+<h1 id="the-gem">Installing the gem</h1>
+<p><strong>The easy way:</strong>  We recommend you pick the platform you want 
to run Buildr on and then follow the <em>easy way</em> instructions for that 
platform.  It could save you an hour or two struggling to install all the right 
dependencies.</p>
+<p><a href="#jruby">Installing Buildr for JRuby</a> is the same on all 
operating systems.  Choose JRuby if you&#8217;re working with Java 6 on OS X, 
developing with multiple JDKs, or just like JRuby better.</p>
+<p>If you are running behind a proxy server, make sure the environment 
variable <code>HTTP_PROXY</code> is set, as many of these steps require <span 
class="caps">HTTP</span> access.</p>
+<p><br></p>
+<p><strong>In details:</strong> The <code>gem install</code> and <code>gem 
update</code> commands install Buildr from a binary distribution provided 
through <a href="http://rubyforge.org/projects/buildr";>RubyForge</a>. This 
distribution is maintained by contributors to this project, but is 
<strong>not</strong> an official Apache distribution.  You can obtain the 
official Apache distribution files from the <a href="download.html">download 
page</a>.</p>
+<p>Older versions of RubyGems are all kind of fail.  You want to avoid these 
unless you have the patience to install each Buildr dependency manually.  Get 
RubyGems 1.3.1 or later, and when using Debian packages (e.g. Ubuntu), make 
sure to get the unmolested RubyGems straight form the source.</p>
+<p>The Ruby interpreter and <span class="caps">JVM</span> must use compatible 
architectures.  For example, OS X comes with 32-bit version of Ruby, Java 1.5 
in both 32-bit and 64-bit flavors, and 64-bit Java 6.  As a result you can run 
Ruby with Java 1.5 (32-bit), but to use Java 6 you either need to build Ruby 
from source for 64-bit, or use <a href="#jruby">Buildr for JRuby</a>.</p>
+<h2 id="linux">Installing on Linux</h2>
+<p><strong>The easy way:</strong> Use this bash script to <a 
href="scripts/install-linux.sh">install Buildr on Linux</a>.  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 <code>apt-get</code>, <code>yum</code> or 
<code>urpmi</code>) and upgrade to RubyGems 1.3.1 or later.</p>
+<p><br></p>
+<p><strong>In details:</strong> To get started you will need a recent version 
of Ruby, Ruby Gems and build tools for compiling native libraries 
(<code>make</code>, <code>gcc</code> and standard headers).</p>
+<p>On <strong>RedHat/Fedora</strong> you can use yum to install Ruby and 
RubyGems, and then upgrade to the most recent version of RubyGems:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>sudo yum install ruby rubygems ruby-devel gcc
+<span class="nv">$ </span>sudo gem update --system</code></pre></figure><p>On 
<strong>Ubuntu</strong> you have to install several packages:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>sudo apt-get install ruby-full ruby1.8-dev libopenssl-ruby 
build-essential</code></pre></figure><p>If using Ubuntu 9.10 or earlier, the 
Debian package for <code>rubygems</code> will not allow you to install Buildr, 
so you need to install RubyGems from source:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>wget 
http://rubyforge.org/frs/download.php/45905/rubygems-1.3.1.tgz
+<span class="nv">$ </span>tar xzf rubygems-1.3.1.tgz
+<span class="nv">$ </span><span class="nb">cd </span>rubygems-1.3.1
+<span class="nv">$ </span>sudo ruby setup.rb
+<span class="nv">$ </span>sudo ln -s /usr/bin/gem1.8 
/usr/bin/gem</code></pre></figure><p>Before installing Buildr, please set the 
<code>JAVA_HOME</code> environment variable to point to your <span 
class="caps">JDK</span> distribution.  Next, use Ruby Gem to install Buildr:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>sudo env <span class="nv">JAVA_HOME</span><span 
class="o">=</span><span class="nv">$JAVA_HOME</span> gem install 
buildr</code></pre></figure><p>To upgrade to a new version or install a 
specific version:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>sudo env <span class="nv">JAVA_HOME</span><span 
class="o">=</span><span class="nv">$JAVA_HOME</span> gem update buildr
+<span class="nv">$ </span>sudo env <span class="nv">JAVA_HOME</span><span 
class="o">=</span><span class="nv">$JAVA_HOME</span> gem install buildr -v 
1.4.3</code></pre></figure><h2 id="osx">Installing on OS X</h2>
+<p><strong>The easy way:</strong> Use this script to <a 
href="scripts/install-osx.sh">install Buildr on OS X</a>.  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.</p>
+<p>You need to have the Apple Development Tools installed.  They are available 
on the Mac <span class="caps">OSX</span> installation CD.</p>
+<p class="note">Java Update 3 for Snow Leopard removes header files necessary 
to compile the native Ruby-Java Bridge (<span class="caps">RJB</span>) 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 
<code>gem install</code>.</p>
+<p><strong>Using <span class="caps">RVM</span>?</strong> If you&#8217;re not 
using the built-in ruby on OS X (e.g., if you&#8217;re using <span 
class="caps">RVM</span>), you&#8217;ll need to force-install the 
platform-independent <span class="caps">RJB</span>:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>gem install rjb -v 1.3.3 --platform 
ruby</code></pre></figure><p>The darwin pre-built binary seems to only work 
with the built-in ruby.</p>
+<p><br></p>
+<p><strong>In details:</strong> 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.</p>
+<p>OS X 10.4 (Tiger) includes an older version of Ruby that is not compatible 
with Buildr.  You can install Ruby 1.8.6 using MacPorts (<code>sudo port 
install ruby rb-rubygems</code>), Fink or the <a 
href="http://rubyosx.rubyforge.org/";>Ruby One-Click Installer for OS X</a>.</p>
+<p>We recommend you first upgrade to the latest version of Ruby gems:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>sudo gem update --system</code></pre></figure><p>Before 
installing Buildr, please set the <code>JAVA_HOME</code> environment variable 
to point to your <span class="caps">JDK</span> distribution:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span><span class="nb">export </span><span 
class="nv">JAVA_HOME</span><span 
class="o">=</span>/Library/Java/Home</code></pre></figure><p>To install 
Buildr:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>sudo env <span class="nv">JAVA_HOME</span><span 
class="o">=</span><span class="nv">$JAVA_HOME</span> gem install 
buildr</code></pre></figure><p>To upgrade to a new version or install a 
specific version:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>sudo env <span class="nv">JAVA_HOME</span><span 
class="o">=</span><span class="nv">$JAVA_HOME</span> gem update buildr
+<span class="nv">$ </span>sudo env <span class="nv">JAVA_HOME</span><span 
class="o">=</span><span class="nv">$JAVA_HOME</span> gem install buildr -v 
1.3.4</code></pre></figure><h2 id="windows">Installing on Windows</h2>
+<p><strong>The easy way:</strong>  The easiest way to install Ruby is using 
the <a href="http://rubyinstaller.rubyforge.org/";>one-click installer</a>.  Be 
sure to install Ruby 1.8.6; support for Ruby 1.9.x is still a work in progress. 
 Once installed, set the <code>JAVA_HOME</code> environment variable and run 
<code>gem install buildr --platform mswin32</code>.</p>
+<p><br></p>
+<p><strong>In details:</strong> Before installing Buildr, please set the 
<code>JAVA_HOME</code> environment variable to point to your <span 
class="caps">JDK</span> distribution.  Next, use Ruby Gem to install Buildr:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh">&gt; 
gem install buildr --platform mswin32</code></pre></figure><p>To upgrade to a 
new version or install a specific version:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh">&gt; 
gem update buildr
+&gt; gem install buildr -v 1.3.4 --platform mswin32</code></pre></figure><h2 
id="jruby">Installing for JRuby</h2>
+<p><strong>The easy way:</strong> Use this bash script to <a 
href="scripts/install-jruby.sh">install Buildr on JRuby</a>.  This script will 
install the most recent version of Buildr, or if already installed, upgrade to 
the most recent version.  If necessary, it will also install JRuby 1.6.1 in 
<code>/opt/jruby</code> and update the <code>PATH</code> variable in 
<code>~/.bash_profile</code> or <code>~/.profile</code>.</p>
+<p><br></p>
+<p><strong>In details:</strong> If you don&#8217;t already have JRuby 1.5.1 or 
later installed, you can download it from the <a 
href="http://www.jruby.org/download";>JRuby site</a>.</p>
+<p>After uncompressing JRuby, update your <code>PATH</code> to include both 
<code>java</code> and <code>jruby</code> executables.</p>
+<p>For Linux and OS X:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span><span class="nb">export </span><span 
class="nv">PATH</span><span class="o">=</span><span 
class="nv">$PATH</span>:<span class="o">[</span>path to JRuby<span 
class="o">]</span>/bin:<span class="nv">$JAVA_HOME</span>/bin
+<span class="nv">$ </span>jruby -S gem install 
buildr</code></pre></figure><p>For Windows:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh">&gt; 
<span class="nb">set </span><span class="nv">PATH</span><span 
class="o">=</span>%PATH%<span class="p">;</span><span class="o">[</span>path to 
JRuby<span class="o">]</span>/bin<span class="p">;</span>%JAVA_HOME%/bin
+&gt; jruby -S gem install buildr</code></pre></figure><p>To upgrade to a new 
version or install a specific version:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>jruby -S gem update buildr
+<span class="nv">$ </span>jruby -S gem install buildr -v 
1.3.4</code></pre></figure><p><strong>Important: Running JRuby and Ruby side by 
side</strong></p>
+<p>Ruby and JRuby maintain separate Gem repositories, and in fact install 
slightly different versions of the Buildr Gem (same functionality, different 
dependencies).  Installing Buildr for Ruby does not install it for JRuby and 
vice versa.</p>
+<p>If you have JRuby installed but not Ruby, the <code>gem</code> and 
<code>buildr</code> commands will use JRuby.  If you have both JRuby and Ruby 
installed, follow the instructions below.  To find out if you have Ruby 
installed (some operating systems include it by default), run <code>ruby 
--version</code> from the command line.</p>
+<p>To work exclusively with JRuby, make sure it shows first on the path, for 
example, by setting <code>PATH=/opt/jruby/bin:$PATH</code>.</p>
+<p>You can use JRuby and Ruby side by side, by running scripts with the 
<code>-S</code> command line argument.  For example:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span><span class="c"># with Ruby</span>
+<span class="nv">$ </span>ruby -S gem install buildr
+<span class="nv">$ </span>ruby -S buildr
+<span class="nv">$ </span><span class="c"># with JRuby</span>
+<span class="nv">$ </span>jruby -S gem install buildr
+<span class="nv">$ </span>jruby -S buildr</code></pre></figure><p>Run 
<code>buildr --version</code> from the command line to find which version of 
Buildr you are using by default.  If you see <code>(JRuby ...)</code>, Buildr 
is running on that version of JRuby.</p>
+<h2>Using multiple versions of Buildr</h2>
+<p>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 (&#8216;_&#8217;) as 
the first command-line parameter.  For example,</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>buildr _1.3.4_ clean   <span class="c"># runs Buildr 
v1.3.4</span>
+
+<span class="nv">$ </span>buildr _1.4.4_ clean   <span class="c"># runs Buildr 
v1.4.4</span></code></pre></figure><p class="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 `<span class="caps">PATH</span>`.   The second script should not be 
called directly and should not be on your `<span class="caps">PATH</span>`.</p>
+<h2 id="running">Running Buildr</h2>
+<p>You need a <strong>Buildfile</strong>, a build script that tells Buildr all 
about the projects it&#8217;s building, what they contain, what to produce, and 
so on.  The Buildfile resides in the root directory of your project.  
We&#8217;ll talk more about it in <a href="projects.html">the next chapter</a>. 
 If you don&#8217;t already have one, ask Buildr to create it by running 
<code>buildr</code>.</p>
+<p class="tip">You&#8217;ll notice that Buildr creates a file called 
<code>buildfile</code>.  It&#8217;s case sensitive, but Buildr will look for 
either <code>buildfile</code> or <code>Buildfile</code>.</p>
+<p>You use Buildr by running the <code>buildr</code> command:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>buildr <span class="o">[</span>options<span 
class="o">]</span> <span class="o">[</span>tasks<span class="o">]</span> <span 
class="o">[</span><span class="nv">name</span><span 
class="o">=</span>value<span class="o">]</span></code></pre></figure><p>There 
are several options you can use, for a full list of options type <code>buildr 
--help</code>:</p>
+<table>
+       <tr>
+               <th>Option                  </th>
+               <th>Usage </th>
+       </tr>
+       <tr>
+               <td> <code>-f/--buildfile [file]</code>   </td>
+               <td> Specify the buildfile.                                  
</td>
+       </tr>
+       <tr>
+               <td> <code>-e/--environment [name]</code> </td>
+               <td> Environment name (e.g. development, test, production).  
</td>
+       </tr>
+       <tr>
+               <td> <code>-h/--help</code>               </td>
+               <td> Display this help message.                              
</td>
+       </tr>
+       <tr>
+               <td> <code>-n/--nosearch</code>           </td>
+               <td> Do not search parent directories for the buildfile.     
</td>
+       </tr>
+       <tr>
+               <td> <code>-q/--quiet</code>              </td>
+               <td> Do not log messages to standard output.                 
</td>
+       </tr>
+       <tr>
+               <td> <code>-r/--require [file]</code>     </td>
+               <td> Require <span class="caps">MODULE</span> before executing 
buildfile.              </td>
+       </tr>
+       <tr>
+               <td> <code>-t/--trace</code>              </td>
+               <td> Turn on invoke/execute tracing, enable full backtrace.  
</td>
+       </tr>
+       <tr>
+               <td> <code>-v/--verbose</code>            </td>
+               <td> Log message to standard output                          
</td>
+       </tr>
+       <tr>
+               <td> <code>-V/--version</code>            </td>
+               <td> Display the program version.                            
</td>
+       </tr>
+       <tr>
+               <td> <code>-P/--prereqs</code>            </td>
+               <td> Display tasks and dependencies, then exit.              
</td>
+       </tr>
+</table>
+<p>You can tell Buildr to run specific tasks and the order to run them.  For 
example:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="c"># Clean and rebuild</span>
+buildr clean build
+<span class="c"># Package and install</span>
+buildr install</code></pre></figure><p>If you don&#8217;t specify a task, 
Buildr will run the <a href="building.html"><code>build</code> task</a>, 
compiling source code and running test cases.  Running a task may run other 
tasks as well, for example, running the <code>install</code> task will also run 
<code>package</code>.</p>
+<p>There are several <a href="settings_profiles.html#env_vars">environment 
variables</a> that let you control how Buildr works, for example, to skip test 
cases during a build, or specify options for the <span class="caps">JVM</span>. 
 Depending on the variable, you may want to set it once in your environment, or 
set a different value each time you run Buildr.</p>
+<p>For example:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span><span class="nb">export </span><span 
class="nv">JAVA_OPTS</span><span class="o">=</span><span class="s1">&#39;-Xms1g 
-Xmx1g&#39;</span>
+<span class="nv">$ </span>buildr <span class="nv">TEST</span><span 
class="o">=</span>no</code></pre></figure><h2 id="help">Help Tasks</h2>
+<p>Buildr includes a number of informative tasks.  Currently that number 
stands at two, but we&#8217;ll be adding more tasks in future releases.  These 
tasks report information from the Buildfile, so you need one to run them.  For 
more general help (version number, command line arguments, etc) use 
<code>buildr --help</code>.</p>
+<p>To start with, type:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>buildr <span 
class="nb">help</span></code></pre></figure><p>You can list the name and 
description of all your projects using the <code>help:projects</code> task.  
For example:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>buildr <span class="nb">help</span>:projects
+killer-app                 <span class="c"># Code. Build. ??? Profit!</span>
+killer-app:teh-api         <span class="c"># Abstract classes and 
interfaces</span>
+killer-app:teh-impl        <span class="c"># All those implementation 
details</span>
+killer-app:la-web          <span class="c"># What our users 
see</span></code></pre></figure><p>You are, of course, describing your projects 
for the sake of those who will maintain your code, right?  To describe a 
project, or a task, call the <code>desc</code> method before the project or 
task definition.</p>
+<p>So next let&#8217;s talk about <a href="projects.html">projects</a>.</p>
+<h2 id="more">Learning More</h2>
+<p><strong>Ruby</strong>  It pays to pick up Ruby as a second (or first) 
programming language. It&#8217;s fun, powerful and slightly addictive.  If 
you&#8217;re interested in learning Ruby the language, a good place to start is 
<a href="http://www.pragprog.com/titles/ruby/programming-ruby";>Programming 
Ruby: The Pragmatic Programmer&#8217;s Guide</a>, fondly known as the 
<em>Pickaxe book</em>.</p>
+<p>For a quicker read (and much more humor), <a 
href="http://poignantguide.net/ruby/";>Why’s (Poignant) Guide to Ruby</a> is 
available online.  More resources are listed on the <a 
href="http://www.ruby-lang.org/en/documentation/";>ruby-lang web site</a>.</p>
+<p><strong>Rake</strong> Buildr is based on Rake, a Ruby build system that 
handles tasks and dependencies.  Check out the <a 
href="http://docs.rubyrake.org/";>Rake documentation</a> for more 
information.</p>
+<p><strong>AntWrap</strong> Buildr uses AntWrap, for configuring and running 
Ant tasks.  You can learn more from the <a 
href="https://rubygems.org/gems/Antwrap";>Antwrap documentation</a>.</p>
+<p><strong><span class="caps">YAML</span></strong> Buildr uses <span 
class="caps">YAML</span> for its profiles.  You can <a 
href="http://www.yaml.org";>learn more about <span class="caps">YAML</span> 
here</a>, and use this handy <a href="http://www.yaml.org/refcard.html";><span 
class="caps">YAML</span> quick reference</a>.</p>
+      </div>
+      <div id='footer'>Copyright &copy; 2007-2016 The Apache Software 
Foundation</div>
+    </div>
+  </body>
+</html>


Reply via email to