Added: dev/buildr/1.5.0/site/projects.html
==============================================================================
--- dev/buildr/1.5.0/site/projects.html (added)
+++ dev/buildr/1.5.0/site/projects.html Sat Sep 17 06:23:20 2016
@@ -0,0 +1,257 @@
+<html>
+  <head>
+    <meta content='text/html;charset=UTF-8' http-equiv='Content-Type'>
+    <title>buildr &mdash; Projects</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='projects'>Projects</h1>
+        <ol class="toc"><li><a href="#starting">Starting Out</a></li><li>When 
defining your project, the order in which you place instructions 
matter.</li><li><a href="#dir_structure">The Directory Structure</a></li><li><a 
href="#naming">Naming And Finding Projects</a></li><li><a href="#tasks">Running 
Project Tasks</a></li><li><a href="#properties">Setting Project 
Properties</a></li><li><a href="#paths">Resolving Paths</a></li><li><a 
href="#defining">Defining The Project</a></li><li><a 
href="#your_own_tasks">Writing Your Own Tasks</a></li></ol>
+        <h2 id="starting">Starting Out</h2>
+<p>In Java, most projects are built the same way: compile source code, run 
test cases, package the code, release it.  Rinse, repeat.</p>
+<p>Feed it a project definition, and Buildr will set up all these tasks for 
you. The only thing you need to do is specify the parts that are specific to 
your project, like the classpath dependencies, whether you&#8217;re packaging a 
<span class="caps">JAR</span> or a <span class="caps">WAR</span>, etc.</p>
+<p>The remainder of this guide deals with what it takes to build a project.  
But first, let&#8217;s pick up a sample project to work with.  We&#8217;ll call 
it <em>killer-app</em>:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="nb">require</span> <span 
class="s2">&quot;buildr/openjpa&quot;</span>
+
+<span class="kp">include</span> <span class="no">Buildr</span><span 
class="o">::</span><span class="no">OpenJPA</span>
+
+<span class="no">VERSION_NUMBER</span> <span class="o">=</span> <span 
class="s1">&#39;1.0&#39;</span>
+
+<span class="no">AXIS2</span> <span class="o">=</span> <span 
class="s1">&#39;org.apache.axis2:axis2:jar:1.2&#39;</span>
+<span class="no">AXIOM</span> <span class="o">=</span> <span 
class="n">group</span><span class="p">(</span><span 
class="s1">&#39;axiom-api&#39;</span><span class="p">,</span> <span 
class="s1">&#39;axiom-impl&#39;</span><span class="p">,</span> <span 
class="s1">&#39;axiom-dom&#39;</span><span class="p">,</span>
+  <span class="ss">:under</span><span class="o">=&gt;</span><span 
class="s1">&#39;org.apache.ws.commons.axiom&#39;</span><span class="p">,</span> 
<span class="ss">:version</span><span class="o">=&gt;</span><span 
class="s1">&#39;1.2.4&#39;</span><span class="p">)</span>
+<span class="no">AXIS_OF_WS</span> <span class="o">=</span> <span 
class="o">[</span><span class="no">AXIOM</span><span class="p">,</span> <span 
class="no">AXIS2</span><span class="o">]</span>
+<span class="no">OPENJPA</span> <span class="o">=</span> <span 
class="o">[</span><span 
class="s1">&#39;org.apache.openjpa:openjpa:jar:1.2.0&#39;</span><span 
class="p">,</span>
+  <span class="s1">&#39;net.sourceforge.serp:serp:jar:1.12.0&#39;</span><span 
class="o">]</span>
+
+<span class="n">repositories</span><span class="o">.</span><span 
class="n">remote</span> <span class="o">&lt;&lt;</span> <span 
class="s1">&#39;http://www.ibiblio.org/maven2/&#39;</span>
+
+<span class="n">desc</span> <span class="s1">&#39;Code. Build. ??? 
Profit!&#39;</span>
+<span class="n">define</span> <span class="s1">&#39;killer-app&#39;</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="no">VERSION_NUMBER</span>
+  <span class="n">project</span><span class="o">.</span><span 
class="n">group</span> <span class="o">=</span> <span 
class="s1">&#39;acme&#39;</span>
+  <span class="n">manifest</span><span class="o">[</span><span 
class="s1">&#39;Copyright&#39;</span><span class="o">]</span> <span 
class="o">=</span> <span class="s1">&#39;Acme Inc (C) 2007&#39;</span>
+  <span class="n">compile</span><span class="o">.</span><span 
class="n">options</span><span class="o">.</span><span class="n">target</span> 
<span class="o">=</span> <span class="s1">&#39;1.5&#39;</span>
+
+  <span class="n">desc</span> <span class="s1">&#39;Abstract classes and 
interfaces&#39;</span>
+  <span class="n">define</span> <span class="s1">&#39;teh-api&#39;</span> 
<span class="k">do</span>
+    <span class="n">package</span> <span class="ss">:jar</span>
+  <span class="k">end</span>
+
+  <span class="n">desc</span> <span class="s1">&#39;All those implementation 
details&#39;</span>
+  <span class="n">define</span> <span class="s1">&#39;teh-impl&#39;</span> 
<span class="k">do</span>
+    <span class="n">compile</span><span class="o">.</span><span 
class="n">with</span> <span class="no">AXIS_OF_WS</span><span 
class="p">,</span> <span class="no">OPENJPA</span>
+    <span class="n">compile</span> <span class="p">{</span> <span 
class="n">open_jpa_enhance</span> <span class="p">}</span>
+    <span class="n">package</span> <span class="ss">:jar</span>
+  <span class="k">end</span>
+
+  <span class="n">desc</span> <span class="s1">&#39;What our users 
see&#39;</span>
+  <span class="n">define</span> <span class="s1">&#39;la-web&#39;</span> <span 
class="k">do</span>
+    <span class="nb">test</span><span class="o">.</span><span 
class="n">with</span> <span class="no">AXIS_OF_WS</span>
+    <span class="n">package</span><span class="p">(</span><span 
class="ss">:war</span><span class="p">)</span><span class="o">.</span><span 
class="n">with</span> <span class="ss">:libs</span><span 
class="o">=&gt;</span><span class="n">projects</span><span 
class="p">(</span><span class="s1">&#39;teh-api&#39;</span><span 
class="p">,</span> <span class="s1">&#39;teh-impl&#39;</span><span 
class="p">)</span>
+  <span class="k">end</span>
+
+  <span class="n">javadoc</span> <span class="n">projects</span>
+  <span class="n">package</span> <span class="ss">:javadoc</span>
+
+<span class="k">end</span></code></pre></figure><p>A project definition 
requires four pieces of information: the project name, group identifier, 
version number and base directory.  The project name &#8230; do we need to 
explain why its necessary?  The group identifier and version number are used 
for packaging and deployment, we&#8217;ll talk more about that in the <a 
href="packaging.html">Packaging</a> section.  The base directory lets you find 
files inside the project.</p>
+<p>Everything else depends on what that particular project is building.  And 
it all goes inside the project definition block, the piece of code that comes 
between <code>define &lt;name&gt; ..  do</code> and <code>end</code>.</p>
+<h2 id="instructions_order">Order is important<br />
+When defining your project, the order in which you place instructions 
matter.</h2>
+<p>For example, the project below will not pick up resources because they are 
defined after the package instruction.</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s1">&#39;testwar&#39;</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="mi">1</span><span class="o">.</span><span class="mi">0</span>
+<span class="n">package</span><span class="p">(</span><span 
class="ss">:war</span><span class="p">)</span>
+<span class="n">project</span><span class="o">.</span><span 
class="n">resources</span><span class="o">.</span><span 
class="n">from</span><span class="p">(</span><span class="n">_</span><span 
class="p">(</span><span class="s1">&#39;src/main/java&#39;</span><span 
class="p">))</span><span class="o">.</span><span class="n">exclude</span><span 
class="p">(</span><span class="s1">&#39;*.java&#39;</span><span 
class="p">)</span>
+<span class="k">end</span></code></pre></figure><h2 id="dir_structure">The 
Directory Structure</h2>
+<p>Buildr follows a convention we picked from years of working with Apache 
projects.</p>
+<p>Java projects are laid out so the source files are in the 
<code>src/main/java</code> directory and compile into the 
<code>target/classes</code> directory.  Resource files go in the 
<code>src/main/resources</code> directory, and copied over to 
<code>target/resources</code>. Likewise, tests come from 
<code>src/test/java</code> and <code>src/test/resources</code>, and end life in 
<code>target/test/classes</code> and <code>target/test/resources</code>, 
respectively.</p>
+<p><span class="caps">WAR</span> packages pick up additional files from the 
aptly named <code>src/main/webapp</code>. And most stuff, including generated 
source files are parked under the <code>target</code> directory.  Test cases 
and such may generate reports in the, you guessed it, <code>reports</code> 
directory.</p>
+<p>Other languages will use different directories, but following the same 
general conventions.  For example, Scala code compiles from the 
<code>src/main/scala</code> directory, RSpec tests are found in the 
<code>src/test/rspec</code> directory, and Flash will compile to 
<code>target/flash</code>.  Throughout this document we will show examples 
using mostly Java, but you can imagine how this pattern applies to other 
languages.</p>
+<p>When projects grow big, you split them into smaller projects by nesting 
projects inside each other.  Each sub-project has a sub-directory under the 
parent project and follows the same internal directory structure.  You can, of 
course, change all of that to suite your needs, but if you follow these 
conventions, Buildr will figure all the paths for you.</p>
+<p>Going back to the example above, the directory structure will look 
something like this:</p>
+<p style="text-align:center;"><img src="images/project-structure.png" alt="" 
/></p>
+<p>Notice the <code>buildfile</code> at the top.  That&#8217;s your project 
build script, the one Buildr runs.</p>
+<p>When you run the <code>buildr</code> command, it picks up the 
<code>buildfile</code> (which here we&#8217;ll just call <em>Buildfile</em>) 
from the current directory, or if not there, from the closest parent directory. 
 So you can run <code>buildr</code> from any directory inside your project, and 
it will always pick up the same Buildfile.  That also happens to be the base 
directory for the top project.  If you have any sub-projects, Buildr assumes 
they reflect sub-directories under their parent.</p>
+<p>And yes, you can have two top projects in the same Buildfile.  For example, 
you can use that to have one project that groups all the application modules 
(JARs, WARs, etc) and another project that groups all the distribution packages 
(binary, sources, javadocs).</p>
+<p>When you start with a new project you won&#8217;t see the 
<code>target</code> or <code>reports</code> directories.  Buildr creates these 
when it needs to.  Just know that they&#8217;re there.</p>
+<h2 id="naming">Naming And Finding Projects</h2>
+<p>Each project has a given name, the first argument you pass when calling 
<code>define</code>.  The project name is just a string, but we advise to stay 
clear of colon (<code>:</code>) and slashes (<code>/</code> and 
<code>\</code>), which could conflict with other task and file names.  Also, 
avoid using common Buildr task names, don&#8217;t pick <code>compile</code>, 
<code>build</code> or any existing task name for your project name.</p>
+<p>Since each project knows its parent project, child projects and siblings, 
you can reference them from within the project using just the given name.  In 
other cases, you&#8217;ll need to use the full name.  The full name is just 
<code>parent:child</code>. So if you wanted to refer to <em>teh-impl</em>, you 
could do so with either <code>project('killer-app:teh-impl')</code> or 
<code>project('killer-app').project('teh-impl')</code>.</p>
+<p>The <code>project</code> method is convenient when you have a dependency 
from one project to another, e.g. using the other project in the classpath, or 
accessing one of its source files.  Call it with a project name and it will 
return that object or raise an error.  You can also call it with no arguments 
and it will return the project itself.  It&#8217;s syntactic sugar that&#8217;s 
useful when accessing project properties.</p>
+<p>The <code>projects</code> method takes a list of names and returns a list 
of projects.  If you call it with no arguments on a project, it returns all its 
sub-projects.   If you call it with no argument in any other context, it 
returns all the projects defined so far.</p>
+<p>Let&#8217;s illustrate this with a few examples:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="nb">puts</span> <span 
class="n">projects</span><span class="o">.</span><span class="n">inspect</span>
+<span class="o">=&gt;</span> <span class="o">[</span><span 
class="n">project</span><span class="p">(</span><span 
class="s2">&quot;killer-app&quot;</span><span class="p">),</span> <span 
class="n">project</span><span class="p">(</span><span 
class="s2">&quot;killer-app:teh-api&quot;</span><span class="p">)</span> <span 
class="o">.</span><span class="n">.</span><span class="o">.</span> <span 
class="o">]</span>
+
+<span class="nb">puts</span> <span class="n">project</span><span 
class="p">(</span><span class="s1">&#39;killer-app&#39;</span><span 
class="p">)</span><span class="o">.</span><span class="n">projects</span><span 
class="o">.</span><span class="n">inspect</span>
+<span class="o">=&gt;</span> <span class="o">[</span><span 
class="n">project</span><span class="p">(</span><span 
class="s2">&quot;killer-app:teh-api&quot;</span><span class="p">),</span> <span 
class="n">project</span><span class="p">(</span><span 
class="s2">&quot;killer-app:teh-impl&quot;</span><span class="p">)</span> <span 
class="o">.</span><span class="n">.</span><span class="o">.</span> <span 
class="o">]</span>
+
+<span class="nb">puts</span> <span class="n">project</span><span 
class="p">(</span><span class="s1">&#39;teh-api&#39;</span><span 
class="p">)</span>
+<span class="o">=&gt;</span> <span class="no">No</span> <span 
class="n">such</span> <span class="n">project</span> <span 
class="n">teh</span><span class="o">-</span><span class="n">api</span>
+
+<span class="nb">puts</span> <span class="n">project</span><span 
class="p">(</span><span class="s1">&#39;killer-app:teh-api&#39;</span><span 
class="p">)</span><span class="o">.</span><span class="n">inspect</span>
+<span class="o">=&gt;</span> <span class="n">project</span><span 
class="p">(</span><span class="s2">&quot;killer-app:teh-api&quot;</span><span 
class="p">)</span>
+
+<span class="nb">puts</span> <span class="n">project</span><span 
class="p">(</span><span class="s1">&#39;killer-app&#39;</span><span 
class="p">)</span><span class="o">.</span><span class="n">project</span><span 
class="p">(</span><span class="s1">&#39;teh-api&#39;</span><span 
class="p">)</span><span class="o">.</span><span class="n">inspect</span>
+<span class="o">=&gt;</span> <span class="n">project</span><span 
class="p">(</span><span class="s2">&quot;killer-app:teh-api&quot;</span><span 
class="p">)</span></code></pre></figure><p>To see a list of all projects 
defined in your Buildfile run <code>buildr help:projects</code>.</p>
+<h2 id="tasks">Running Project Tasks</h2>
+<p>Most times, you run tasks like <code>build</code> or <code>package</code> 
that operate on the current project and recursively on its sub-projects.  The 
&#8220;current project&#8221; is the one that uses the current working 
directory.  So if you&#8217;re in the <code>la-web/src</code> directory looking 
at source files, <em>la-web</em> is the current project.  For example:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="c"># build killer-app and all its sub-projects</span>
+<span class="nv">$ </span>buildr build
+
+<span class="c"># switch to and test only teh-impl</span>
+<span class="nv">$ </span><span class="nb">cd </span>teh-impl
+<span class="nv">$ </span>buildr <span class="nb">test</span>
+
+<span class="c"># switch to and package only la-web</span>
+<span class="nv">$ </span><span class="nb">cd</span> ../la-web
+<span class="nv">$ </span>buildr package</code></pre></figure><p>You can use 
the project&#8217;s full name to invoke one of its tasks directly, and it 
doesn&#8217;t matter which directory you&#8217;re in.  For example:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="c"># build killer-app and all its sub-projects</span>
+<span class="nv">$ </span>buildr killer-app:build
+
+<span class="c"># test only teh-impl</span>
+<span class="nv">$ </span>buildr killer-app:teh-impl:test
+
+<span class="c"># package only la-web</span>
+<span class="nv">$ </span>buildr 
killer-app:la-web:package</code></pre></figure><p>Buildr provides the following 
tasks that you can run on the current project, or on a specific project by 
prefixing them with the project&#8217;s full name:</p>
+<figure class="highlight"><pre><code class="language-text" 
data-lang="text">clean     # Clean files generated during a build
+compile   # Compile all projects
+build     # Build the project
+upload    # Upload packages created by the project
+install   # Install packages created by the project
+javadoc   # Create the Javadocs for this project
+package   # Create packages
+test      # Run all test cases
+uninstall # Remove previously installed packages</code></pre></figure><p>To 
see a list of all the tasks provided by Buildr run <code>buildr 
help:tasks</code>.</p>
+<h2 id="properties">Setting Project Properties</h2>
+<p>We mentioned the group identifier, version number and base directory.  
These are project properties.  There are a few more properties we&#8217;ll 
cover later on.</p>
+<p>There are two ways to set project properties.  You can pass them as a hash 
when you call <code>define</code>, or use accessors to set them on the project 
directly.  For example:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s1">&#39;silly&#39;</span><span class="p">,</span> <span 
class="ss">:version</span><span class="o">=&gt;</span><span 
class="s1">&#39;1.0&#39;</span> <span class="k">do</span>
+  <span class="n">project</span><span class="o">.</span><span 
class="n">group</span> <span class="o">=</span> <span 
class="s1">&#39;acme&#39;</span>
+<span class="k">end</span>
+
+<span class="nb">puts</span> <span class="n">project</span><span 
class="p">(</span><span class="s1">&#39;silly&#39;</span><span 
class="p">)</span><span class="o">.</span><span class="n">version</span>
+<span class="o">=&gt;</span> <span class="mi">1</span><span 
class="o">.</span><span class="mi">0</span>
+<span class="nb">puts</span> <span class="n">project</span><span 
class="p">(</span><span class="s1">&#39;silly&#39;</span><span 
class="p">)</span><span class="o">.</span><span class="n">group</span>
+<span class="o">=&gt;</span> <span 
class="n">acme</span></code></pre></figure><p>Project properties are inherited. 
 You can specify them once in the parent project, and they&#8217;ll have the 
same value in all its sub-projects.  In the example, we only specify the 
version number once, for use in all sub-projects.</p>
+<h2 id="paths">Resolving Paths</h2>
+<p>You can run <code>buildr</code> from any directory in your project.  To 
keep tasks consistent and happy, it switches over to the Buildfile directory 
and executes all the tasks from there, before returning back to your working 
directory. Your tasks can all rely on relative paths that start from the same 
directory as the Buildfile.</p>
+<p>But in practice, you&#8217;ll want to use the <code>path_to</code> method.  
This method calculates a path relative to the project, a better way if you ever 
need to refactor your code, say turn a ad hoc task into a function you 
reuse.</p>
+<p>The <code>path_to</code> method takes an array of strings and concatenates 
them into a path.  Absolute paths are returned as they are, relative paths are 
expanded relative to the project&#8217;s base directory.  Slashes, if you 
don&#8217;t already know, work very well on both Windows, Linux and OS X.  And 
as a shortcut, you can use <code>_</code>.</p>
+<p>For example:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="c1"># Relative to the current project</span>
+<span class="n">path_to</span><span class="p">(</span><span 
class="s1">&#39;src&#39;</span><span class="p">,</span> <span 
class="s1">&#39;main&#39;</span><span class="p">,</span> <span 
class="s1">&#39;java&#39;</span><span class="p">)</span>
+
+<span class="c1"># the same using symbols</span>
+<span class="n">path_to</span><span class="p">(</span><span 
class="ss">:src</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="c1"># Exactly the same thing</span>
+<span class="n">_</span><span class="p">(</span><span 
class="s1">&#39;src/main/java&#39;</span><span class="p">)</span>
+
+<span class="c1"># Relative to the teh-impl project</span>
+<span class="n">project</span><span class="p">(</span><span 
class="s1">&#39;teh-impl&#39;</span><span class="p">)</span><span 
class="o">.</span><span class="n">_</span><span class="p">(</span><span 
class="s1">&#39;src/main/java&#39;</span><span 
class="p">)</span></code></pre></figure><h2 id="defining">Defining The 
Project</h2>
+<p>The project definition itself gives you a lot of pre-canned tasks to start 
with, but that&#8217;s not enough to build a project.  You need to specify what 
gets built and how, which dependencies to use, the packages you want to create 
and so forth.  You can configure existing tasks, extend them to do additional 
work, and create new tasks.  All that magic happens inside the project 
definition block.</p>
+<p>Since the project definition executes each time you run Buildr, you 
don&#8217;t want to perform any work directly inside the project definition 
block.  Rather, you want to use it to specify how different build task work 
when you invoke them. Here&#8217;s an example to illustrate the point:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s1">&#39;silly&#39;</span> <span class="k">do</span>
+  <span class="nb">puts</span> <span class="s1">&#39;Running buildr&#39;</span>
+
+  <span class="n">build</span> <span class="k">do</span>
+    <span class="nb">puts</span> <span class="s1">&#39;Building 
silly&#39;</span>
+  <span class="k">end</span>
+<span class="k">end</span></code></pre></figure><p>Each time you run Buildr, 
it will execute the project definition and print out &#8220;Running 
buildr&#8221;.  We also extend the <code>build</code> task, and whenever we run 
it, it will print &#8220;Building silly&#8221;.  Incidentally, 
<code>build</code> is the default task, so if you run Buildr with no arguments, 
it will print both messages while executing the build.  If you run Buildr with 
a different task, say <code>clean</code>, it will only print the first 
message.</p>
+<p>The <code>define</code> method gathers the project definition, but does not 
execute it immediately.  It executes the project definition the first time you 
reference that project, directly or indirectly, for example, by calling 
<code>project</code> with that project&#8217;s name, or calling 
<code>projects</code> to return a list of all projects. Executing a project 
definition will also execute all its sub-projects&#8217; definitions.  And, of 
course, all project definitions are executed once the Buildfile loads, so 
Buildr can determine how to execute each of the build tasks.</p>
+<p>If this sounds a bit complex, don&#8217;t worry.  In reality, it does the 
right thing.  A simple rule to remember is that each project definition is 
executed before you need it, lazy evaluation of sort.  The reason we do that?  
So you can write projects that depend on each other without worrying about 
their order.</p>
+<p>In our example, the <em>la-web</em> project depends on packages created by 
the <em>teh-api</em> and <em>teh-impl</em> projects, the later requiring 
<em>teh-api</em> to compile. That example is simple enough that we ended up 
specifying the projects in order of dependency.  But you don&#8217;t always 
want to do that.  For large projects, you may want to group sub-projects by 
logical units, or sort them alphabetically for easier editing.</p>
+<p>One project can reference another ahead of its definition.  If Buildr 
detects a cyclic dependency, it will let you know.</p>
+<p>In this example we define one project in terms of another, using the same 
dependencies, so we only need to specify them once:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s1">&#39;bar&#39;</span> <span class="k">do</span>
+  <span class="n">compile</span><span class="o">.</span><span 
class="n">with</span> <span class="n">project</span><span 
class="p">(</span><span class="s1">&#39;foo&#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>
+
+<span class="n">define</span> <span class="s1">&#39;foo&#39;</span> <span 
class="k">do</span>
+  <span class="n">compile</span><span class="o">.</span><span 
class="n">with</span> <span class="o">.</span><span class="n">.lots</span> 
<span class="n">of</span> <span class="n">stuff</span><span 
class="o">.</span><span class="n">.</span>
+<span class="k">end</span></code></pre></figure><p>One last thing to remember. 
 Actually three, but they all go hand in hand.</p>
+<p><strong>Self is project</strong> Each of these project definition blocks 
executes in the context of that project, just as if it was a method defined on 
the project.  So when you call the <code>compile</code> method, you&#8217;re 
essentially calling that method on the current project: <code>compile</code>, 
<code>self.compile</code> and <code>project.compile</code> are all the same.</p>
+<p><strong>Blocks are closures</strong> The project definition is also a 
closure, which can reference variables from enclosing scopes.  You can use 
that, for example, to define constants, variables and even functions in your 
Buildfile, and reference them from your project definition.  As you&#8217;ll 
see later on, in the <a href="artifacts.html">Artifacts</a> section, it will 
save you a lot of work.</p>
+<p><strong>Projects are namespaces</strong> While executing the project 
definition, Buildr switches the namespace to the project name.  If you define 
the task &#8220;do-this&#8221; inside the <em>teh-impl</em> project, the actual 
task name is &#8220;killer-app:teh-impl:do-this&#8221;.  Likewise, the 
<code>compile</code> task is actually 
&#8220;killer-app:teh-impl:compile&#8221;.</p>
+<p>From outside the project you can reference a task by its full name, either 
<code>task('foo:do')</code> or <code>project('foo').task('do')</code>.  If you 
need to reference a task defined outside the project from within the project, 
prefix it with &#8220;rake:&#8221;, for example, 
<code>task('rake:globally-defined')</code>.</p>
+<h2 id="your_own_tasks">Writing Your Own Tasks</h2>
+<p>Of all the features Buildr provide, it doesn&#8217;t have a task for making 
coffee. Yet.  If you need to write your own tasks, you get all the power of 
Rake: you can use regular tasks, file tasks, task rules and even write your own 
custom task classes.  Check out the <a href="http://docs.rubyrake.org/";>Rake 
documentation</a> for more information.</p>
+<p>We mentioned projects as namespaces before.  When you call 
<code>task</code> on a project, it finds or defines the task using the project 
namespace.  So given a project object, <code>task('do-this')</code> will return 
it&#8217;s &#8220;do-this&#8221; task.  If you lookup the source code for the 
<code>compile</code> method, you&#8217;ll find that it&#8217;s little more than 
a shortcut for <code>task('compile')</code>.</p>
+<p>Another shortcut is the <code>file</code> method.  When you call 
<code>file</code> on a project, Buildr uses the <code>path_to</code> method to 
expand relative paths using the project&#8217;s base directory.  If you call 
<code>file('src')</code> on <em>teh-impl</em>, it will return you a file task 
that points at the <code>teh-impl/src</code> directory.</p>
+<p>In the current implementation projects are also created as tasks, although 
you don&#8217;t invoke these tasks directly.  That&#8217;s the reason for not 
using a project name that conflicts with an existing task name.  If you do 
that, you&#8217;ll find quick enough, as the task will execute each time you 
run Buildr.</p>
+<p>So now that you know everything about projects and tasks, let&#8217;s go 
and <a href="building.html">build some code</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/quick_start.html
==============================================================================
--- dev/buildr/1.5.0/site/quick_start.html (added)
+++ dev/buildr/1.5.0/site/quick_start.html Sat Sep 17 06:23:20 2016
@@ -0,0 +1,179 @@
+<html>
+  <head>
+    <meta content='text/html;charset=UTF-8' http-equiv='Content-Type'>
+    <title>buildr &mdash; Quick Start</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='quick start'>Quick Start</h1>
+        <ol class="toc"><li><a href="#first-project">Your First 
Project</a></li><li><a href="#dependencies">Dependencies</a></li><li><a 
href="#testing">Testing</a></li><li><a href="#custom-tasks">Custom 
Tasks</a></li><li><a href="#summary">Summary</a></li></ol>
+        <p>This quick start guide is meant to be a <em>very</em> simple 
introduction to Buildr and its most basic concepts.  However, despite its basic 
level, we will still cover most of the concepts you will ever need to be 
productive with Buildr.  We will leave out some important things (like <a 
href="projects.html">sub-projects</a>), and we will over-simplify some other 
concepts (such as <a href="artifacts.html">artifacts</a>).  Nevertheless, most 
Buildr projects never need to go beyond the techniques contained within these 
pages.</p>
+<p><strong>No knowledge of Ruby is assumed.</strong>  Buildr is designed to be 
a very intuitive, very easy-to-use tool.  You can create buildfiles which 
describe incredibly intricate projects, write custom tasks which do things far 
beyond Ant, and still never need to pick up more than a smattering of Ruby 
syntax.  With that said, if you do know Ruby, Buildr&#8217;s <span 
class="caps">DSL</span> will seem very natural and welcoming.  We do assume 
that you have already <a href="installing.html">downloaded and installed</a> 
Buildr and are ready to put the tool to good use.</p>
+<h2 id="first-project">Your First Project</h2>
+<p>Much like Maven, Buildr is oriented around projects and tasks.  You define 
your project in a concise, declarative fashion and most common tasks (such as 
compilation and testing) will be made available to you &#8220;at no extra 
charge&#8221;.  Most of the project definition is contained within the 
<em>buildfile</em> &#8212; or <em>Buildfile</em>, if you&#8217;re really in 
love with the Make convention &#8212; a single file sitting at the root of your 
project.  A project definition does not need to be any more complicated than 
the following:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s1">&#39;killer-app&#39;</span></code></pre></figure><h3>Compiling</h3>
+<p>Of course, this isn&#8217;t really giving Buildr much information.  What it 
can&#8217;t learn from the buildfile, Buildr will figure out by inspecting your 
directory structure.  Java sources are expected to exist within the 
<code>src/main/java/</code> directory.  If Buildr finds these sources, it will 
automatically configure the compilation to source that directory, depositing 
the results in the <code>target/classes/</code> directory (all under the 
project directory of course).  We can run this compilation using the following 
command:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>buildr compile</code></pre></figure><p>Information about 
the classpath and dependencies is described <a href="#dependencies">later 
on</a>.</p>
+<p class="tip">By default, Buildr projects assume the Java language and the 
<code>src/main/java/</code> source directory.  You can also have projects in 
the Scala or Groovy language (both languages support joint compilation with 
Java).  To use Scala, place your <code>.scala</code> files in the 
<code>src/main/scala/</code> directory and include the following invocation at 
the head of your buildfile: <code>require 'buildr/scala'</code>  Similarly, 
Groovy expects sources in the <code>src/main/groovy/</code> directory and 
necessitates <code>require 'buildr/groovy'</code> (see <a 
href="languages.html">languages</a> for more information).</p>
+<p>The <code>compile</code> task will also detect <em>any</em> files which 
exist under the <code>src/main/resources/</code> directory.  These resources 
are copied verbatim to the <code>target/resources/</code> directory as part of 
the compilation task.  Buildr also performs some basic change detection to 
minimize compilation.  If your source files haven&#8217;t changed since the 
last compile, then they will not be recompiled.</p>
+<h3>Packaging</h3>
+<p>At some point, we&#8217;re going to want to wrap up our classes and produce 
a single <span class="caps">JAR</span> file for distribution.  Buildr can 
certainly help us with this, but we are going to need to provide it with a 
little bit more information.  Specifically, we need to say the type of package 
to produce (e.g. <code>:jar</code>, <code>:war</code>, etc) as well as the 
current version of our project.  This information is placed within the 
buildfile:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s1">&#39;killer-app&#39;</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="s1">&#39;0.1.0&#39;</span>
+  <span class="n">package</span> <span class="ss">:jar</span>
+<span class="k">end</span></code></pre></figure><p>The 
<code>project.version</code> attribute can be any value you like.  Even 
non-numeric versions are perfectly acceptable (e.g. 
<code>'ikj-0.3.1-E'</code>).  This version &#8212; coupled with the packaging 
information &#8212; will be used to generate a <span class="caps">JAR</span> 
file: <code>killer-app-0.1.0.jar</code>.  As would be expected, this file is 
placed within the <code>target/</code> directory when the following command is 
run:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>buildr package</code></pre></figure><p>The 
<code>package</code> task depends upon the <code>compile</code> task, so if a 
rebuild is necessary prior to the creation of the <span 
class="caps">JAR</span>, Buildr will see to it.</p>
+<p>We can also chain tasks together in a single invocation.  For example, we 
may want to clean all of the old compilation results prior to recompiling and 
generating a packaged result:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>buildr clean package</code></pre></figure><p>The 
<code>clean</code> task simply removes the <code>target/</code> directory, 
effectively wiping out any compilation results like class files or 
resources.</p>
+<h3>Directory Structure</h3>
+<p>As you may have noticed, Buildr does have some default notions about what a 
project should look like and how it should be organized.  We think that these 
defaults are quite nice and make for a more navigable project.  However, we do 
understand that not all projects are exactly alike.  Buildr&#8217;s <a 
href="extending.html#layouts">layouts</a> make it possible for any project to 
easily change these defaults.  For example, this would allow you to easily 
migrate a project that had been based on a different directory structure, such 
as the <code>src/</code> and <code>bin/</code> convention often used by Ant.</p>
+<h2 id="dependencies">Dependencies</h2>
+<p>So far, we have seen how Buildr can automatically infer what amounts to 
dozens of lines of <code>build.xml</code> contents, all based on a buildfile 
and a directory structure.  However, the best is yet to come.  Buildr also 
provides Maven-style dependency management (but without the long loading 
times!).  In other words, you specify each dependent library using a string 
descriptor and Buildr figures out how to download and configure your classpath 
(the library descriptors are just a Ruby array, therefore they are separated by 
commas (<code>,</code>)).  You must specify at least one remote repository so 
that Buildr knows from where to download these libraries.  For example, we can 
configure our project to reference the <a 
href="http://commons.apache.org/cli/";>Apache Commons <span 
class="caps">CLI</span></a> library and download libraries from the Ibiblio 
repository:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">repositories</span><span 
class="o">.</span><span class="n">remote</span> <span class="o">&lt;&lt;</span> 
<span class="s1">&#39;http://www.ibiblio.org/maven2&#39;</span>
+
+<span class="n">define</span> <span class="s1">&#39;killer-app&#39;</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="s1">&#39;0.1.0&#39;</span>
+  <span class="n">compile</span><span class="o">.</span><span 
class="n">with</span> <span 
class="s1">&#39;commons-cli:commons-cli:jar:1.2&#39;</span>
+  <span class="n">package</span> <span class="ss">:jar</span>
+<span class="k">end</span></code></pre></figure><p>This sort of dependency 
declaration should look quite familiar if you are at all familiar with Maven.  
The general format for an artifact descriptor is 
<em>groupId:artifactId:packageType:version</em>.  Any Maven artifacts included 
in this fashion will be retrieved from the <a 
href="artifacts.html#repositories">list of remote repositories</a> (in this 
case, Ibiblio) and installed in your local repository at 
<code>~/.m2/repository/</code>.</p>
+<p class="tip">You can search the global repository of artifacts at sites like 
<a href="http://www.mvnbrowser.com";>MvnBrowser</a>.  Simply enter the name of 
the library you are looking for, and the search should pull up the groupId, 
artifactId and a list of available versions.</p>
+<p>Unfortunately, not all libraries are quite as simple as Commons <span 
class="caps">CLI</span>.  Many libraries (such as Apache Wicket) have 
dependencies of their own.  While we may be able to <em>compile</em> against 
Apache Wicket without these extra libraries on our classpath, we cannot 
actually <em>run</em> our application without its transitive dependencies. To 
avoid tracking down each of these dependencies and adding them manually, we can 
simply use the <code>transitive</code> directive (this is how Maven behaves by 
default):</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">repositories</span><span 
class="o">.</span><span class="n">remote</span> <span class="o">&lt;&lt;</span> 
<span class="s1">&#39;http://www.ibiblio.org/maven2&#39;</span>
+
+<span class="n">define</span> <span class="s1">&#39;killer-app&#39;</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="s1">&#39;0.1.0&#39;</span>
+  <span class="n">compile</span><span class="o">.</span><span 
class="n">with</span> <span class="n">transitive</span><span 
class="p">(</span><span 
class="s1">&#39;org.apache.wicket:wicket:jar:1.4-rc6&#39;</span><span 
class="p">)</span>
+  <span class="n">package</span> <span class="ss">:jar</span>
+<span class="k">end</span></code></pre></figure><p>The 
<code>compile.with</code> property accepts a full array of comma-separated 
artifacts, making it possible to specify any number of dependencies as 
necessary.  Of course, such a long list of verbose string descriptors could get 
very tiresome and messy.  For this reason, it is conventional to assign each 
dependency to a constant (e.g. <code>WICKET</code>) which is declared just 
above the project in the buildfile and passed to <code>compile.with</code> in a 
clean, easy-to-read style:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">repositories</span><span 
class="o">.</span><span class="n">remote</span> <span class="o">&lt;&lt;</span> 
<span class="s1">&#39;http://www.ibiblio.org/maven2&#39;</span>
+
+<span class="no">WICKET</span> <span class="o">=</span> <span 
class="n">transitive</span><span class="p">(</span><span 
class="s1">&#39;org.apache.wicket:wicket:jar:1.4-rc6&#39;</span><span 
class="p">)</span>
+<span class="no">SLF4J</span> <span class="o">=</span> <span 
class="s1">&#39;org.slf4j:slf4j-jdk14:jar:1.5.8&#39;</span>
+
+<span class="n">define</span> <span class="s1">&#39;killer-app&#39;</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="s1">&#39;0.1.0&#39;</span>
+  <span class="n">compile</span><span class="o">.</span><span 
class="n">with</span> <span class="no">WICKET</span><span class="p">,</span> 
<span class="no">SLF4J</span>
+  <span class="n">package</span> <span class="ss">:jar</span>
+<span class="k">end</span></code></pre></figure><p>Unfortunate as it may seem, 
not all libraries are available in Maven repositories.  While most of the major 
libraries (e.g. Hibernate, Spring, etc) are kept updated by intrepid 
volunteers, some of the more obscure frameworks are left out in the cold.  An 
example of one such framework is <a 
href="http://www.snaq.net/java/DBPool";>DBPool</a>, a very fast connection pool 
designed to integrate with <span class="caps">JDBC</span>.  However, like most 
Java libraries, DBPool does provide a zip archive which contains the <span 
class="caps">JAR</span> file, as well as some documentation and perhaps a 
license or two.</p>
+<p>Almost magically, we can instruct Buildr to get the DBPool artifact from 
this <span class="caps">URL</span>.  Buildr will treat this download just like 
any other artifact, retrieving it when requried by the <code>compile</code> 
task.  However, unlike a normal Maven artifact, Buildr will do some extra 
processing once the download is complete.  It will actually dig into the 
downloaded archive, detect and extract the <span class="caps">JAR</span> file, 
installing it into the local repository just like any other artifact:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="no">DBPOOL</span> <span class="o">=</span> <span 
class="s1">&#39;net.snaq:dbpool:jar:4.8.3&#39;</span>
+<span class="n">download</span> <span class="n">artifact</span><span 
class="p">(</span><span class="no">DBPOOL</span><span class="p">)</span> <span 
class="o">=&gt;</span> <span 
class="s1">&#39;http://www.snaq.net/java/DBPool/DBPool_v4.8.3.zip&#39;</span>
+
+<span class="n">define</span> <span class="s1">&#39;killer-app&#39;</span> 
<span class="k">do</span>
+  <span class="n">project</span><span class="o">.</span><span 
class="n">version</span> <span class="s1">&#39;0.1.0&#39;</span>
+  <span class="n">compile</span><span class="o">.</span><span 
class="n">with</span> <span class="no">DBPool</span>
+  <span class="n">package</span> <span class="ss">:jar</span>
+<span class="k">end</span></code></pre></figure><p>This is one area where 
Buildr&#8217;s dependency management vastly excedes Maven&#8217;s.  With Maven, 
you would have to install the DBPool dependency manually.  Buildr&#8217;s 
auto-magical download and extraction keeps the dependency definitions 
centralized within the buildfile, available to your entire team and 
automatically resolved as needed by the compilation tasks.</p>
+<h2 id="testing">Testing</h2>
+<p>Buildr supports auto-magical integration with a number of mainstream 
testing frameworks.  For Java, this includes the ubiquitus JUnit4, as well as 
TestNG and a number of others.  Scala supports Specs and ScalaTest, while 
Groovy supports EasyB.  Configuration is as simple as placing your test sources 
in the appropriate directory.  In the case of JUnit or TestNG, this would be 
<code>src/test/java/</code>.  Once these tests are in place, we can run them 
using the <code>test</code> task:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>buildr <span 
class="nb">test</span></code></pre></figure><p>When the <code>test</code> task 
runs, it will ensure that your main sources are compiled, as well as the tests 
themselves.  In the case of JUnit4, test classes are auto-detected based on 
which base class they extend (<code>TestCase</code>).  These tests will be 
invoked using the special test classpath.  This classpath includes all of the 
dependencies passed to <code>compile.with</code> along with the dependencies 
required for testing.  Thus, Buildr will actually go out and download JUnit 4.5 
(if necessary) and place that <span class="caps">JAR</span> on the classpath in 
order to run your tests.  It is also possible to add artifacts specifically 
required for testing.  So, if your tests make use of the Commons Collections 
library, but your main sources do not, you can include that dependency only for 
the tests by using the <code>
 test.with</code> property.  This functions identically to 
<code>compile.with</code>:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s1">&#39;killer-app&#39;</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="s1">&#39;0.1.0&#39;</span>
+  <span class="n">compile</span><span class="o">.</span><span 
class="n">with</span> <span 
class="s1">&#39;commons-cli:commons-cli:jar:1.2&#39;</span>
+  <span class="nb">test</span><span class="o">.</span><span 
class="n">with</span> <span 
class="s1">&#39;commons-collections:commons-collections:jar:3.2&#39;</span>
+  <span class="n">package</span> <span class="ss">:jar</span>
+<span class="k">end</span></code></pre></figure><p>Of course, not everyone 
<em>likes</em> JUnit4.  As mentioned previously, Buildr supports a number of 
test frameworks.  It is possible to use TestNG instead of JUnit4 by setting the 
<code>test.using</code> property to <code>:testng</code>:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s1">&#39;killer-app&#39;</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="s1">&#39;0.1.0&#39;</span>
+  <span class="n">compile</span><span class="o">.</span><span 
class="n">with</span> <span 
class="s1">&#39;commons-cli:commons-cli:jar:1.2&#39;</span>
+  <span class="nb">test</span><span class="o">.</span><span 
class="n">with</span> <span 
class="s1">&#39;commons-collections:commons-collections:jar:3.2&#39;</span>
+  <span class="nb">test</span><span class="o">.</span><span 
class="n">using</span> <span class="ss">:testng</span>
+  <span class="n">package</span> <span class="ss">:jar</span>
+<span class="k">end</span></code></pre></figure><p>Note that only one test 
framework per-project may be used.  This may seem like an obvious restriction 
given that both frameworks introduced so far have used the same directory, but 
other frameworks such as Specs and EasyB do not follow the same convention.  In 
cases of ambiguity (for example, when tests are present in both 
<code>src/test/java/</code> <em>and</em> <code>src/spec/scala/</code>), only 
one test framework will be chosen, but this choice is not well-defined.  When 
in doubt, explicitly specify the test framework with the 
<code>test.using</code> property.  This overrides Buildr&#8217;s auto-detection 
and ensures sane behavior.</p>
+<p>Other test frameworks are documented <a href="testing.html">here</a> and <a 
href="languages.html">here</a>.</p>
+<h2 id="custom-tasks">Custom Tasks</h2>
+<p>If there is one area in which Buildr excels, it is defining custom tasks.  
This is something which is notoriously difficult in both Ant and Maven, often 
requiring separate Java plugins and mountains of code simply to perform basic 
tasks.  For example, let&#8217;s imagine that we wanted to define a 
<code>run</code> task which would compile and run our &#8220;killer-app&#8221; 
project.  This is a simple matter of invoking the <code>java</code> command 
against our main class:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">define</span> <span 
class="s1">&#39;killer-app&#39;</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="s1">&#39;0.1.0&#39;</span>
+  <span class="n">package</span> <span class="ss">:jar</span>
+
+  <span class="n">task</span> <span class="ss">:run</span> <span 
class="o">=&gt;</span> <span class="ss">:compile</span> <span 
class="k">do</span>
+    <span class="nb">system</span> <span class="s1">&#39;java -cp 
target/classes org.apache.killer.Main&#39;</span>
+  <span class="k">end</span>
+<span class="k">end</span></code></pre></figure><p>This code defines a new 
task, <code>run</code>, which depends upon the <code>compile</code> task.  This 
task only performs a single operation: it invokes the <code>system</code> 
method, passing the relevant command as a string.  Note that the 
<code>system</code> method documentation may be found <a 
href="http://www.ruby-doc.org/core/classes/Kernel.html#M005971";>here</a>.  
Tasks use real Ruby (actually, the entire buildfile is real Ruby too), so if 
you are familiar with that language, then you should be right at home writing 
custom tasks in Buildr.  We can invoke this task in the following way:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>buildr killer-app:run</code></pre></figure><p>This works, 
but it&#8217;s clumsy.  The reason we had to give the 
&#8220;<code>killer-app:</code>&#8221; prefix is because we defined the 
<code>run</code> task <em>within</em> our project, rather than outside of the 
<code>define</code> block.  However, if we define <code>run</code> outside of 
the project, then we don&#8217;t really have access to the <code>compile</code> 
task (which is project-specific).  The solution here is a bit of magic known as 
<code>local_task</code>.  This is how tasks like <code>compile</code> and 
<code>test</code>, which are technically project-specific (think: instance 
methods) can be invoked without the fully-qualified project name:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="no">Project</span><span class="o">.</span><span 
class="n">local_task</span> <span class="ss">:run</span>
+
+<span class="n">define</span> <span class="s1">&#39;killer-app&#39;</span> 
<span class="k">do</span>
+  <span class="n">project</span><span class="o">.</span><span 
class="n">version</span> <span class="s1">&#39;0.1.0&#39;</span>
+
+  <span class="n">package</span> <span class="ss">:jar</span>
+
+  <span class="n">task</span> <span class="ss">:run</span> <span 
class="o">=&gt;</span> <span class="ss">:compile</span> <span 
class="k">do</span>
+    <span class="nb">system</span> <span class="s1">&#39;java -cp 
target/classes org.apache.killer.Main&#39;</span>
+  <span class="k">end</span>
+<span class="k">end</span></code></pre></figure><p>Now, we can invoke 
<code>run</code> exactly the way we want, with a minimum of wasted 
characters:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>buildr run</code></pre></figure><h2 
id="summary">Summary</h2>
+<p>As long as this guide was, we have barely even scratched the surface of 
Buildr&#8217;s true power.  This was meant only to get you up and running as 
quickly as possible, exploiting some of Buildr&#8217;s unique features to ease 
your build process.  For more comprehensive documentation, start reading about 
<a href="projects.html">projects in Buildr</a> and work your way from there.</p>
+      </div>
+      <div id='footer'>Copyright &copy; 2007-2016 The Apache Software 
Foundation</div>
+    </div>
+  </body>
+</html>

Added: dev/buildr/1.5.0/site/rdoc/Buildr.html
==============================================================================
--- dev/buildr/1.5.0/site/rdoc/Buildr.html (added)
+++ dev/buildr/1.5.0/site/rdoc/Buildr.html Sat Sep 17 06:23:20 2016
@@ -0,0 +1,237 @@
+<!DOCTYPE html>
+
+<html>
+<head>
+<meta charset="UTF-8">
+
+<title>module Buildr - buildr</title>
+
+<script type="text/javascript">
+  var rdoc_rel_prefix = "./";
+</script>
+
+<script src="./js/jquery.js"></script>
+<script src="./js/darkfish.js"></script>
+
+<link href="./css/fonts.css" rel="stylesheet">
+<link href="./css/rdoc.css" rel="stylesheet">
+
+
+
+<body id="top" role="document" class="module">
+<nav role="navigation">
+  <div id="project-navigation">
+    <div id="home-section" role="region" title="Quick navigation" 
class="nav-section">
+  <h2>
+    <a href="./index.html" rel="home">Home</a>
+  </h2>
+
+  <div id="table-of-contents-navigation">
+    <a href="./table_of_contents.html#pages">Pages</a>
+    <a href="./table_of_contents.html#classes">Classes</a>
+    <a href="./table_of_contents.html#methods">Methods</a>
+  </div>
+</div>
+
+    <div id="search-section" role="search" class="project-section 
initially-hidden">
+  <form action="#" method="get" accept-charset="utf-8">
+    <div id="search-field-wrapper">
+      <input id="search-field" role="combobox" aria-label="Search"
+             aria-autocomplete="list" aria-controls="search-results"
+             type="text" name="search" placeholder="Search" spellcheck="false"
+             title="Type to search, Up and Down to navigate, Enter to load">
+    </div>
+
+    <ul id="search-results" aria-label="Search Results"
+        aria-busy="false" aria-expanded="false"
+        aria-atomic="false" class="initially-hidden"></ul>
+  </form>
+</div>
+
+  </div>
+
+  
+
+  <div id="class-metadata">
+    
+    
+    
+    
+    <!-- Method Quickref -->
+<div id="method-list-section" class="nav-section">
+  <h3>Methods</h3>
+
+  <ul class="link-list" role="directory">
+    
+    <li ><a href="#method-c-application">::application</a>
+    
+    <li ><a href="#method-c-environment">::environment</a>
+    
+    <li ><a href="#method-c-settings">::settings</a>
+    
+  </ul>
+</div>
+
+  </div>
+</nav>
+
+<main role="main" aria-labelledby="module-Buildr">
+  <h1 id="module-Buildr" class="module">
+    module Buildr
+  </h1>
+
+  <section class="description">
+    
+<p>Methods defined in <a href="Buildr.html">Buildr</a> are both instance
+methods (e.g. when included in <a href="Buildr/Project.html">Project</a>)
+and class methods when invoked like Buildr.artifacts().</p>
+
+<p>Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the <a href="NOTICE.html">NOTICE</a>
+file distributed with this work for additional information regarding
+copyright ownership.  The ASF licenses this file to you under the Apache
+License, Version 2.0 (the “License”); you may not use this file except in
+compliance with the License. You may obtain a copy of the License at</p>
+
+<pre class="ruby"><span class="ruby-identifier">http</span>:<span 
class="ruby-operator">/</span><span 
class="ruby-regexp">/www.apache.org/</span><span 
class="ruby-identifier">licenses</span><span 
class="ruby-operator">/</span><span class="ruby-constant">LICENSE</span><span 
class="ruby-operator">-</span><span class="ruby-value">2.0</span>
+</pre>
+
+<p>Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an “AS IS” BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+License for the specific language governing permissions and limitations
+under the License.</p>
+
+  </section>
+
+  
+  
+  
+  <section id="5Buntitled-5D" class="documentation-section">
+    
+
+    
+
+    
+
+    
+
+    
+     <section id="public-class-5Buntitled-5D-method-details" 
class="method-section">
+       <header>
+         <h3>Public Class Methods</h3>
+       </header>
+
+    
+      <div id="method-c-application" class="method-detail ">
+        
+        <div class="method-heading">
+          <span class="method-name">application</span><span
+            class="method-args">()</span>
+          
+          <span class="method-click-advice">click to toggle source</span>
+          
+        </div>
+        
+
+        <div class="method-description">
+          
+          <p>Returns the Buildr::Application object.</p>
+          
+          
+
+          
+          <div class="method-source-code" id="application-source">
+            <pre><span class="ruby-comment"># File 
lib/buildr/core/application.rb, line 575</span>
+<span class="ruby-keyword">def</span> <span 
class="ruby-identifier">application</span>
+  <span class="ruby-constant">Rake</span>.<span 
class="ruby-identifier">application</span>
+<span class="ruby-keyword">end</span></pre>
+          </div>
+          
+        </div>
+
+        
+
+        
+      </div>
+
+    
+      <div id="method-c-environment" class="method-detail ">
+        
+        <div class="method-heading">
+          <span class="method-name">environment</span><span
+            class="method-args">()</span>
+          
+          <span class="method-click-advice">click to toggle source</span>
+          
+        </div>
+        
+
+        <div class="method-description">
+          
+          <p>Copied from BUILD_ENV.</p>
+          
+          
+
+          
+          <div class="method-source-code" id="environment-source">
+            <pre><span class="ruby-comment"># File 
lib/buildr/core/application.rb, line 589</span>
+<span class="ruby-keyword">def</span> <span 
class="ruby-identifier">environment</span>
+  <span class="ruby-constant">Buildr</span>.<span 
class="ruby-identifier">application</span>.<span 
class="ruby-identifier">environment</span>
+<span class="ruby-keyword">end</span></pre>
+          </div>
+          
+        </div>
+
+        
+
+        
+      </div>
+
+    
+      <div id="method-c-settings" class="method-detail ">
+        
+        <div class="method-heading">
+          <span class="method-name">settings</span><span
+            class="method-args">()</span>
+          
+          <span class="method-click-advice">click to toggle source</span>
+          
+        </div>
+        
+
+        <div class="method-description">
+          
+          <p>Returns the <a href="Buildr/Settings.html">Settings</a> 
associated with
+this build.</p>
+          
+          
+
+          
+          <div class="method-source-code" id="settings-source">
+            <pre><span class="ruby-comment"># File 
lib/buildr/core/application.rb, line 584</span>
+<span class="ruby-keyword">def</span> <span 
class="ruby-identifier">settings</span>
+  <span class="ruby-constant">Buildr</span>.<span 
class="ruby-identifier">application</span>.<span 
class="ruby-identifier">settings</span>
+<span class="ruby-keyword">end</span></pre>
+          </div>
+          
+        </div>
+
+        
+
+        
+      </div>
+
+    
+    </section>
+  
+  </section>
+</main>
+
+
+<footer id="validator-badges" role="contentinfo">
+  <p><a href="http://validator.w3.org/check/referer";>Validate</a>
+  <p>Generated by <a href="http://docs.seattlerb.org/rdoc/";>RDoc</a> 4.2.2.
+  <p>Based on <a 
href="http://deveiate.org/projects/Darkfish-RDoc/";>Darkfish</a> by <a 
href="http://deveiate.org";>Michael Granger</a>.
+</footer>
+


Reply via email to