Added: dev/buildr/1.5.0/site/artifacts.html
==============================================================================
--- dev/buildr/1.5.0/site/artifacts.html (added)
+++ dev/buildr/1.5.0/site/artifacts.html Sat Sep 17 06:18:39 2016
@@ -0,0 +1,178 @@
+<html>
+  <head>
+    <meta content='text/html;charset=UTF-8' http-equiv='Content-Type'>
+    <title>buildr &mdash; Artifacts</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='artifacts'>Artifacts</h1>
+        <ol class="toc"><li><a href="#specifying">Specifying 
Artifacts</a></li><li><a href="#repositories">Specifying 
Repositories</a></li><li><a href="#downloading">Downloading 
Artifacts</a></li><li><a href="#install_upload">Install and Upload</a></li></ol>
+        <p>In Buildr, almost everything is a file or a file task. You compile 
source files that come from the file system using dependencies found on the 
file system, generating even more files. But how do you get these dependencies 
to start with, and how do you share them with others?</p>
+<p>Artifacts. We designed Buildr to work as a drop-in replacement for Maven 
2.0, and share artifacts through the same local and remote repositories. 
Artifact tasks know how to download a file from one of the remote repositories, 
and install it in the local repository, where Buildr can find it. Packages know 
how to create files and upload them to remote repositories.</p>
+<p>We&#8217;ll get into all of that in a second, but first, let&#8217;s 
introduce the artifact specification. It&#8217;s a simple string that takes one 
of two forms:</p>
+<figure class="highlight"><pre><code class="language-text" 
data-lang="text">group:id:type:version
+group:id:type:classifier:version</code></pre></figure><p>For example, 
<code>'org.apache.axis2:axis2:jar:1.2'</code> refers to an artifact with group 
identifier org.apache.axis2, artifact identifier axis2, a <span 
class="caps">JAR</span> file with version 1.2.  Classifiers are typically used 
to distinguish between similar file types, for example, a source distribution 
and a binary distribution that otherwise have the same identifier and are both 
<span class="caps">ZIP</span> files.</p>
+<h2 id="specifying">Specifying Artifacts</h2>
+<p>If your Buildfile spells out <code>'org.apache.axis2:axis2:jar:1.2'</code> 
more than once, you&#8217;re doing something wrong.  Repeating the same string 
over and over will make your code harder to maintain.  You&#8217;ll know that 
when you upgrade to a new version in one place, forget to do it in another, and 
end up with a mismatch.</p>
+<p>You can use Ruby&#8217;s syntax to do simple string substitution, for 
example:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="no">AXIS_VERSION</span> <span class="o">=</span> 
<span class="s1">&#39;1.2&#39;</span>
+
+<span class="n">compile</span><span class="o">.</span><span 
class="n">with</span> <span 
class="s2">&quot;org.apache.axis2:axis2:jar:</span><span 
class="si">#{</span><span class="no">AXIS_VERSION</span><span 
class="si">}</span><span 
class="s2">&quot;</span></code></pre></figure><p>Better yet, you can define all 
your artifacts at the top of the Buildfile and use constants to reference them 
in your project definition.  For example:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="no">AXIS2</span> <span class="o">=</span> <span 
class="s1">&#39;org.apache.axis2:axis2:jar:1.2&#39;</span>
+
+<span class="n">compile</span><span class="o">.</span><span 
class="n">with</span> <span 
class="no">AXIS2</span></code></pre></figure><p>Note that we&#8217;re not using 
a separate constant for the version number.  In our experience, it&#8217;s 
unnecessary.  The version number intentionally appears at the end of the 
string, where it stands out easily.</p>
+<p>If you have a set of artifacts that belong to the same group and version, 
and that&#8217;s quite common, you can use the <code>group</code> shortcut:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><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></code></pre></figure><p class="note">Buildr projects also 
define a <code>group</code> attribute which can lead to some confusion.  If you 
want to define an artifact group within a project definition, you should use 
the explicit qualifier <code>Buildr::group</code>.</p>
+<p>If you have several artifacts you always use together, consider placing 
them in an array.  Methods that accept lists of artifacts also accept arrays.  
For example:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="no">OPENJPA</span> <span class="o">=</span> <span 
class="o">[</span><span 
class="s1">&#39;org.apache.openjpa:openjpa:jar:1.2.1&#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="no">AXIS_OF_WS</span> <span class="o">=</span> <span 
class="o">[</span><span class="no">AXIS2</span><span class="p">,</span> <span 
class="no">AXIOM</span><span class="o">]</span>
+
+<span class="n">compile</span><span class="o">.</span><span 
class="n">with</span> <span class="no">OPENJPA</span><span class="p">,</span> 
<span class="no">AXIS_OF_WS</span></code></pre></figure><p>Another way to group 
related artifacts together and access them individually is using the 
<code>struct</code> shortcut.  For example:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="no">JAVAX</span> <span class="o">=</span> <span 
class="n">struct</span><span class="p">(</span>
+  <span class="ss">:activation</span>  <span class="o">=&gt;</span><span 
class="s1">&#39;javax.activation:activation:jar:1.1&#39;</span><span 
class="p">,</span>
+  <span class="ss">:persistence</span> <span class="o">=&gt;</span><span 
class="s1">&#39;javax.persistence:persistence-api:jar:1.0&#39;</span><span 
class="p">,</span>
+  <span class="ss">:stream</span>      <span class="o">=&gt;</span><span 
class="s1">&#39;stax:stax-api:jar:1.0.1&#39;</span><span class="p">,</span>
+<span class="p">)</span>
+
+<span class="n">compile</span><span class="o">.</span><span 
class="n">with</span> <span class="no">JAVAX</span><span 
class="o">.</span><span class="n">persistence</span><span class="p">,</span> 
<span class="no">OPENJPA</span></code></pre></figure><p>In our experience, 
using constants in this manner makes your Buildfile much easier to write and 
maintain.</p>
+<p>And, of course, you can always place your artifact specifications in a 
separate file and require it into your Buildfile.  For example, if you&#8217;re 
working on several different projects that all share the same artifacts:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="nb">require</span> <span 
class="s1">&#39;../shared/artifacts&#39;</span></code></pre></figure><p>When 
you use <code>require</code>, Ruby always looks for a filename with the 
<code>.rb</code> extension, so in this case it expects to find 
<code>artifacts.rb</code> in the <code>shared</code> directory.</p>
+<p>One last thing.  You can also treat artifact specifications as hashes.  For 
example:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="no">AXIS</span> <span class="o">=</span> <span 
class="p">{</span> <span class="ss">:group</span><span 
class="o">=&gt;</span><span class="s1">&#39;org.apache.axis2&#39;</span><span 
class="p">,</span> <span class="ss">:id</span><span class="o">=&gt;</span><span 
class="s1">&#39;axis2&#39;</span><span class="p">,</span> <span 
class="ss">:version</span><span class="o">=&gt;</span><span 
class="s1">&#39;1.2&#39;</span> <span class="p">}</span>
+<span class="n">compile</span><span class="o">.</span><span 
class="n">with</span> <span class="no">AXIS</span>
+<span class="nb">puts</span> <span class="n">compile</span><span 
class="o">.</span><span class="n">dependencies</span><span 
class="o">.</span><span class="n">first</span><span class="o">.</span><span 
class="n">to_hash</span>
+<span class="o">=&gt;</span> <span class="p">{</span> <span 
class="ss">:group</span><span class="o">=&gt;</span><span 
class="s1">&#39;org.apache.axis2&#39;</span><span class="p">,</span> <span 
class="ss">:id</span><span class="o">=&gt;</span><span 
class="s1">&#39;axis2&#39;</span><span class="p">,</span>
+     <span class="ss">:version</span><span class="o">=&gt;</span><span 
class="s1">&#39;1.2&#39;</span><span class="p">,</span> <span 
class="ss">:type</span><span class="o">=&gt;</span><span class="ss">:jar</span> 
<span class="p">}</span></code></pre></figure><h2 id="repositories">Specifying 
Repositories</h2>
+<p>Buildr can download artifacts for you, but only if you tell it where to 
find them.  You need to specify at least one remote repository, from which to 
download these artifacts.</p>
+<p>When you call <code>repositories.remote</code>, you get an array of URLs 
for the various remote repositories.  Initially, it&#8217;s an empty array, to 
which you can add new repositories.  For example:</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></code></pre></figure><p>If
 your repository requires <span class="caps">HTTP</span> authentication, you 
can write,</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="no">URI</span><span class="o">.</span><span 
class="n">parse</span><span class="p">(</span><span 
class="s2">&quot;http://user:passw...@repository.example.com&quot;</span><span 
class="p">)</span></code></pre></figure><p>or</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="p">{</span> <span class="ss">:url</span> <span 
class="o">=&gt;</span> <span 
class="s2">&quot;http://repository.example.com&quot;</span><span 
class="p">,</span> <span class="ss">:user</span> <span class="o">=&gt;</span> 
<span class="s2">&quot;user&quot;</span><span class="p">,</span> <span 
class="ss">:pass</span> <span class="o">=&gt;</span> <span 
class="s2">&quot;password&quot;</span> <span 
class="p">}</span></code></pre></figure><p>If you need to use a proxy server to 
access remote repositories, you can set the environment variable 
<code>HTTP_PROXY</code> to the proxy server <span class="caps">URL</span> (use 
<code>HTTPS_PROXY</code> for proxying <span class="caps">HTTPS</span> 
connections).  You can also work without a proxy for certain hosts by 
specifying the <code>NO_PROXY
 </code> environment variable.  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">HTTP_PROXY</span> <span class="o">=</span> <span 
class="s1">&#39;http://myproxy:8080&#39;</span>
+<span class="nv">$ </span><span class="nb">export </span><span 
class="nv">NO_PROXY</span> <span class="o">=</span> <span 
class="s1">&#39;*.mycompany.com,localhost,special:800&#39;</span></code></pre></figure><p>Alternatively
 you can use the Buildr options <code>proxy.http</code> and 
<code>proxy.exclude</code>:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">options</span><span class="o">.</span><span 
class="n">proxy</span><span class="o">.</span><span class="n">http</span> <span 
class="o">=</span> <span class="s1">&#39;http://myproxy:8080&#39;</span>
+<span class="n">options</span><span class="o">.</span><span 
class="n">proxy</span><span class="o">.</span><span class="n">exclude</span> 
<span class="o">&lt;&lt;</span> <span 
class="s1">&#39;*.mycompany.com&#39;</span>
+<span class="n">options</span><span class="o">.</span><span 
class="n">proxy</span><span class="o">.</span><span class="n">exclude</span> 
<span class="o">&lt;&lt;</span> <span 
class="s1">&#39;localhost&#39;</span></code></pre></figure><p>All the artifacts 
download into the local repository.  Since all your projects share the same 
local repository, you only need to download each artifact once. Buildr was 
designed to be used alongside Maven 2.0, for example, when migrating projects 
from Maven 2.0 over to Buildr.  By default it will share the same local 
repository, expecting the repository to be the <code>.m2/repository</code> 
directory inside your home directory.</p>
+<p>You can choose to relocate the local repository by giving it a different 
path, for example:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">repositories</span><span 
class="o">.</span><span class="n">local</span> <span class="o">=</span> <span 
class="s1">&#39;/usr/local/maven/repository&#39;</span></code></pre></figure><p>That&#8217;s
 one change you don&#8217;t want to commit into the Buildfile, so the best 
place to do it is in the <code>buildr.rb</code> file in the 
<code>.buildr</code> directory under your home directory.</p>
+<p>Buildr downloads artifacts when it needs to use them, for example, to 
compile a project.  You don&#8217;t need to download artifacts directly.  
Except when you do, for example, if you want to download all the latest 
artifacts and then go off-line.  It&#8217;s as simple as:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>buildr artifacts</code></pre></figure><h3 
id="mirrors">Mirrors</h3>
+<p>You can specify mirrors to override remote repositories. This is useful 
when you use a Nexus proxy or Artifactory, for example.</p>
+<p>You can use the same syntax as <code>repositories.remote</code>, for 
example:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">repositories</span><span 
class="o">.</span><span class="n">mirrors</span> <span 
class="o">&lt;&lt;</span> <span 
class="s1">&#39;http://corporateserver001.com/repository&#39;</span></code></pre></figure><p>This
 is even more useful when you place this in your user settings.</p>
+<p>See the <a href="/settings_profiles.html">Settings/Profiles section</a>.</p>
+<h2 id="downloading">Downloading Artifacts</h2>
+<p>Within your buildfile you can download artifacts directly by invoking them, 
for example:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">artifact</span><span class="p">(</span><span 
class="s1">&#39;org.apache.openjpa:openjpa:jar:1.2.1&#39;</span><span 
class="p">)</span><span class="o">.</span><span class="n">invoke</span>
+<span class="n">artifacts</span><span class="p">(</span><span 
class="no">OPENJPA</span><span class="p">)</span><span class="o">.</span><span 
class="n">each</span><span class="p">(</span><span class="o">&amp;</span><span 
class="ss">:invoke</span><span class="p">)</span></code></pre></figure><p>When 
you let Buildr download artifacts for you, or by invoking the artifact task 
yourself, it scans through the remote repositories assuming each repository 
follows the Maven 2 structure.  Starting from the root repository <span 
class="caps">URL</span>, it will look for each artifact using the path 
<code>group/id/version/id-version.type</code> (or 
&#8230;<code>/id-version-classifier.type</code>).  The group identifier becomes 
a path by turning periods (<code>.</code>) into slashes (<code>/</code>). So to 
find <code>org.apache.axis2:axis2:jar:1.2</code>, we&#8217;re going to look for 
<code>org/apache/axis2/axis2/1.2/axis2-1.2.jar</code>.</p>
+<p>You&#8217;ll find a lot of open source Java libraries in public 
repositories that support this structure (for example, the <a 
href="http://www.ibiblio.org/maven2/";>Ibiblio Maven</a> repository).  And, of 
course, every remote repository you setup for your projects.</p>
+<p>But there are exceptions to the rule.  Say we want to download the Dojo 
widget library and use it in our project.  It&#8217;s available from the Dojo 
Web site, but that site doesn&#8217;t follow the Maven repository conventions, 
so our feeble attempt to use existing remote repositories will fail.</p>
+<p>We can still treat Dojo as an artifact, by telling Buildr where to download 
it from:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="no">DOJO</span> <span class="o">=</span> <span 
class="s1">&#39;0.2.2&#39;</span>
+
+<span class="n">url</span> <span class="o">=</span> <span 
class="s2">&quot;http://download.dojotoolkit.org/release-</span><span 
class="si">#{</span><span class="no">DOJO</span><span class="si">}</span><span 
class="s2">/dojo-</span><span class="si">#{</span><span 
class="no">DOJO</span><span class="si">}</span><span 
class="s2">-widget.zip&quot;</span>
+<span class="n">download</span><span class="p">(</span><span 
class="n">artifact</span><span class="p">(</span><span 
class="s2">&quot;dojo:dojo:zip:widget:</span><span class="si">#{</span><span 
class="no">DOJO</span><span class="si">}</span><span 
class="s2">&quot;</span><span class="p">)</span><span 
class="o">=&gt;</span><span class="n">url</span><span 
class="p">)</span></code></pre></figure><p>Explaining how it works is tricky, 
skip if you don&#8217;t care for the details.  On the other hand, it will give 
you a better understanding of Buildr/Rake, so if not now, come back and read it 
later.</p>
+<p>We use the <code>artifact</code> method to create an <code>Artifact</code> 
task that references the Dojo widget in our local repository.  The 
<code>Artifact</code> task is a file task with some additional behavior added 
by Buildr.  When you call <code>compile.with</code>, that&#8217;s exactly what 
it does internally, turning each of your artifact specifications into an 
<code>Artifact</code> task.</p>
+<p>But the <code>Artifact</code> task doesn&#8217;t know how to download the 
Dojo widget, only how to handle conventional repositories.  So we&#8217;re 
going to create a download task as well.  We use the <code>download</code> 
method to create a file task that downloads the file from a remote <span 
class="caps">URL</span>.  (Of course, it will only download the file if it 
doesn&#8217;t already exist.)</p>
+<p>But which task gets used when?  We could have defined these tasks 
separately and used some glue code to make one use the other.  Instead, we call 
<code>download</code> with the results of <code>artifact</code>.  Essentially, 
we&#8217;re telling <code>download</code> to use the same file path as 
<code>artifact</code>.  So now we have two file tasks that point to the very 
same file.  We wired them together.</p>
+<p>You can&#8217;t have more than one task pointing to the same file.  
Rake&#8217;s rule of the road.  What Rake does is merge the tasks together, 
creating a single file task for <code>artifact</code>, and then enhancing it 
with another action from <code>download</code>. One task, two actions.  
Statistically, we&#8217;ve doubled the odds that at least one of these actions 
will manage to download the Dojo widget and install it in the local 
repository.</p>
+<p>Since we ordered the calls to <code>artifact</code> first and 
<code>download</code> second, we know the actions will execute in that order.  
But <code>artifact</code> is slightly devilish: when its action runs, it adds 
another action to the end of the list.  So the <code>artifact</code> action 
runs first, adds an action at the end, the <code>download</code> action runs 
second, and downloads the Dojo widget for us.  The second <code>artifact</code> 
action runs last, but checks that the file already exist and doesn&#8217;t try 
to download it again.</p>
+<p>Magic.</p>
+<h3 id="ssl"><span class="caps">SSL</span> and Self-signed certificates</h3>
+<p>There&#8217;s always that Maven repository you learnt to hate, because 
it&#8217;s using a faulty <span class="caps">SSL</span> certificate, or a 
self-signed one.</p>
+<p>On top of installing that certificate everywhere, it&#8217;s messing with 
your build!</p>
+<p>To get out of there, you can use the environment variable SSL_CA_CERTS to 
point at a folder containing your certificates.<br />
+For example:</p>
+<figure class="highlight"><pre><code class="language-bash" 
data-lang="bash"><span class="nb">export </span><span 
class="nv">SSL_CA_CERTS</span><span class="o">=</span>/Users/john/certs
+buildr package</code></pre></figure><p>You can also change the OpenSSL verify 
mode so it won&#8217;t barf on your certificate. Use the environment variable 
<code>SSL_VERIFY_MODE</code> to specify one of the following: 
<code>VERIFY_NONE</code>, <code>VERIFY_PEER</code>, 
<code>VERIFY_CLIENT_ONCE</code>, <code>VERIFY_FAIL_IF_NO_PEER_CERT</code>. See 
<code>OpenSSL::SSL</code> for more info.</p>
+<p>For example:<br />
+<figure class="highlight"><pre><code class="language-bash" 
data-lang="bash"><span class="c"># Don&#39;t verify certificates</span>
+<span class="nb">export </span><span class="nv">SSL_VERIFY_MODE</span><span 
class="o">=</span>VERIFY_NONE
+buildr package</code></pre></figure></p>
+<h2 id="install_upload">Install and Upload</h2>
+<p>Generally you use artifacts that download from remote repositories into the 
local repository, or artifacts packaged by the project itself (see <a 
href="packaging.html">Packaging</a>), which are then installed into the local 
repository and uploaded to the release server.</p>
+<p>Some artifacts do not fall into either category.  In this example 
we&#8217;re going to download a <span class="caps">ZIP</span> file, extract a 
<span class="caps">JAR</span> file from it, and use that <span 
class="caps">JAR</span> file as an artifact.  We would then expect to install 
this <span class="caps">JAR</span> in the local repository and upload it to the 
release server, where it can be shared with other projects.</p>
+<p>So let&#8217;s start by creating a task that downloads the <span 
class="caps">ZIP</span>, and another one to extract it and create the <span 
class="caps">JAR</span> file:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">app_zip</span> <span class="o">=</span> <span 
class="n">download</span><span class="p">(</span><span 
class="s1">&#39;target/app.zip&#39;</span><span class="o">=&gt;</span><span 
class="n">url</span><span class="p">)</span>
+<span class="n">bean_jar</span> <span class="o">=</span> <span 
class="n">file</span><span class="p">(</span><span 
class="s1">&#39;target/app/bean.jar&#39;</span><span 
class="o">=&gt;</span><span class="n">unzip</span><span class="p">(</span><span 
class="s1">&#39;target/app&#39;</span><span class="o">=&gt;</span><span 
class="n">app_zip</span><span class="p">))</span></code></pre></figure><p>When 
you call <code>artifact</code>, it returns an <code>Artifact</code> task that 
points to the artifact file in the local repository, downloading the file if it 
doesn&#8217;t already exist.  You can override this behavior by enhancing the 
task and creating the file yourself (you may also want to create a <span 
class="caps">POM</span> file).  Or much simpler, call the <code>from</code> 
method on the artifact and tell it where to find the source file.</p>
+<p>So the next step is to specify the artifact and tell it to use the 
extracted <span class="caps">JAR</span> file:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">bean</span> <span class="o">=</span> <span 
class="n">artifact</span><span class="p">(</span><span 
class="s1">&#39;example.com:beans:jar:1.0&#39;</span><span 
class="p">)</span><span class="o">.</span><span class="n">from</span><span 
class="p">(</span><span class="n">bean_jar</span><span 
class="p">)</span></code></pre></figure><p>The artifact still points to the 
local repository, but when we invoke the task it copies the source file over to 
the local repository, instead of attempting a download.</p>
+<p>Use the <code>install</code> method if you want the artifact and its <span 
class="caps">POM</span> installed in the local repository when you run the 
<code>install</code> task.  Likewise, use the <code>upload</code> method if you 
want the artifact uploaded to the release server when you run the 
<code>upload</code> task.  You do not need to do this on artifacts downloaded 
from a remote server, or created with the <code>package</code> method, the 
later are automatically added to the list of installed/uploaded artifacts.</p>
+<p>Our example ends by including the artifact in the <code>install</code> and 
<code>upload</code> tasks:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">install</span> <span class="n">bean</span>
+<span class="n">upload</span> <span 
class="n">bean</span></code></pre></figure><p class="tip">Calling the 
<code>install</code> (and likewise <code>upload</code>) method on an artifact 
run <code>buildr install</code>.  If you need to download and install an 
artifact, invoke the task directly with 
<code>install(&lt;artifact&gt;).invoke</code>.</p>
+<p>We&#8217;ll talk more about installing and uploading in the next chapter, 
but right now we&#8217;re going to <a href="packaging.html">package some 
artifacts</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/building.html
==============================================================================
--- dev/buildr/1.5.0/site/building.html (added)
+++ dev/buildr/1.5.0/site/building.html Sat Sep 17 06:18:39 2016
@@ -0,0 +1,205 @@
+<html>
+  <head>
+    <meta content='text/html;charset=UTF-8' http-equiv='Content-Type'>
+    <title>buildr &mdash; Building</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='building'>Building</h1>
+        <ol class="toc"><li><a href="#compiling">Compiling</a></li><li><a 
href="#resources">Resources</a></li><li><a href="#more">More On 
Building</a></li><li><a href="#cleaning">Cleaning</a></li><li><a 
href="#continuous-compilation">Continuous Compilation</a></li></ol>
+        <p>To remove any confusion, Buildr&#8217;s build task is actually 
called <code>build</code>.  It&#8217;s also the default task that executes when 
you run <code>buildr</code> without any task name.</p>
+<p>The <code>build</code> task runs two other tasks: <code>compile</code> and 
its associated tasks (that would be, <code>resources</code>) and 
<code>test</code> and its associated tasks (<code>test:compile</code>, 
<code>test:setup</code> and friends).  We&#8217;ll talk about 
<code>compile</code> more in this section, and <code>test</code> later on.  
We&#8217;ll also show you how to run <code>build</code> without testing, not 
something we recommend, but a necessary feature.</p>
+<p>Why <code>build</code> and not <code>compile</code>?  Some projects do more 
than just compiling. Other projects don&#8217;t compile at all, but perform 
other build tasks, for example, creating a database schema or command line 
scripts.  So we want you to get in the practice of running the 
<code>build</code> task, and help you by making it the default task.</p>
+<h2 id="compiling">Compiling</h2>
+<p>Each project has its own <code>compile</code> task you can invoke directly, 
by running <code>buildr compile</code> or as part of another build task.  (Yes, 
that <code>build</code>).</p>
+<p>The <code>compile</code> task looks for source files in well known 
directories, determines which compiler to use, and sets the target directory 
accordingly.  For example, if it finds any Java source files in the 
<code>src/main/java</code> directory, it selects the Javac compiler and 
generates bytecode in the <code>target/classes</code> directories. If it finds 
Scala source files in the <code>src/main/scala</code> directory it selects the 
Scalac compiler, and so forth.</p>
+<p>A single project cannot use multiple compilers at the same time, hence you 
may  prefer creating subprojects by programming language.  Some compilers like 
Groovy&#8217;s are joint-compilers, this means they can handle several 
languages. When the Groovy compiler is selected for a project, .groovy  and 
.java files are compiled by groovyc.</p>
+<p>Most often, that&#8217;s just good enough and the only change you need to 
make is adding compile dependencies.  You can use 
<code>compile.dependencies</code> to get the array of dependency file tasks.  
For Java, each of these tasks points to a <span class="caps">JAR</span> or a 
directory containing Java classes, and the entire set of dependencies is passed 
to Javac as the classpath.</p>
+<p>Buildr uses file tasks to handle dependencies, but here we&#8217;re talking 
about the Rake dependency mechanism.  It&#8217;s a double entendre.  It invokes 
these tasks before running the compiler.  Some of these tasks will download 
JARs from remote repositories, others will create them by compiling and 
packaging from a different project.  Using file task ensures all the 
dependencies exist before the compiler can use them.</p>
+<p>An easier way to specify dependencies is by calling the 
<code>compile.with</code> method. It takes a list of arguments and adds them to 
the dependency list.  The <code>compile.with</code> method is easier to use, it 
accepts several type of dependencies.  You can use file names, file tasks, 
projects, artifacts specifications and even pass arrays of dependencies.</p>
+<p>Most dependencies fall into the last three categories.  When you pass a 
project to <code>compile.with</code>, it picks up all the packages created by 
that project.  In doing so, it establishes an order of dependency between the 
two projects (see <a href="projects.html#defining">Defining the Project</a>).  
For example, if you make a change in project <em>teh-api</em> and build 
<em>teh-impl</em>, Buildr will detect that change, recompile and package 
<em>teh-api</em> before compiling <em>teh-impl</em>.  You can also select a 
specific package using the project&#8217;s <code>package</code> or 
<code>packages</code> methods (see <a href="packaging.html">Packaging</a>).</p>
+<p>When you pass an artifact specification to <code>compile.with</code>, it 
creates an <code>Artifact</code> task that will download that artifact from one 
of the remote repositories, install it in the local repository, and use it in 
your project. Rake&#8217;s dependency mechanism is used here to make sure the 
artifact is downloaded once, when needed.  Check the <a 
href="artifacts.html">Artifacts</a> section for more information about artifact 
specification and repositories.</p>
+<p>For now let&#8217;s just show a simple example:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">compile</span><span class="o">.</span><span 
class="n">with</span> <span 
class="s1">&#39;org.apache.axis2:axis2:jar:1.2&#39;</span><span 
class="p">,</span>
+  <span class="s1">&#39;org.apache.derby:derby:jar:10.1.2.1&#39;</span><span 
class="p">,</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></code></pre></figure><p>Passing arrays to 
<code>compile.with</code> is just a convenient for handling multiple 
dependencies, we&#8217;ll show more examples of that when we talk about <a 
href="artifacts.html">Artifacts</a>.</p>
+<p>Likewise, the <code>compile</code> task has an array of file tasks that 
point at the source directories you want to compile from.  You can access that 
array by calling <code>compile.sources</code>.  You can use 
<code>compile.from</code> to add new source directories by passing a file name 
or a file task.</p>
+<p>For example, let&#8217;s run the <span class="caps">APT</span> tool on our 
annotated source code before compiling it:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">compile</span><span class="o">.</span><span 
class="n">from</span> <span class="n">apt</span></code></pre></figure><p>When 
you call <code>apt</code> on a project, it returns a file task that points to 
the <code>target/generated/apt</code> directory.  This file task executes by 
running <span class="caps">APT</span>, using the same list of source 
directories, dependencies and compiler options. It then generates new source 
files in the target directory.  Calling <code>compile.from</code> with that 
file task includes those additional source files in the list of compiled 
sources.</p>
+<p>Here&#8217;s another example:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">jjtree</span> <span class="o">=</span> <span 
class="n">jjtree</span><span class="p">(</span><span class="n">_</span><span 
class="p">(</span><span class="s1">&#39;src/main/jjtree&#39;</span><span 
class="p">),</span> <span class="ss">:in_package</span><span 
class="o">=&gt;</span><span class="s1">&#39;com.acme&#39;</span><span 
class="p">)</span>
+<span class="n">compile</span><span class="o">.</span><span 
class="n">from</span> <span class="n">javacc</span><span 
class="p">(</span><span class="n">jjtree</span><span class="p">,</span> <span 
class="ss">:in_package</span><span class="o">=&gt;</span><span 
class="s1">&#39;com.acme&#39;</span><span class="p">),</span> <span 
class="n">jjtree</span></code></pre></figure><p>This time, the variable 
<code>jjtree</code> is a file task that reads a JJTree source file from the 
<code>src/main/jjtree</code> directory, and generates additional source files 
in the <code>target/generated/jjtree</code> directory.  The second line creates 
another file task that takes those source files, runs JavaCC on them, and 
generates yet more source files in <code>target/generated/javacc</code>.  
Finally, we include both sets of source files in addition to those already in 
<code>src/main/java</code>, and compile the lot.</p>
+<p>The interesting thing about these two examples is how you&#8217;re wiring 
file tasks together to create more complicated tasks, piping the output of one 
task into the inputs of another.  Wiring tasks this way is the most common way 
to handle complex builds, and uses Rake&#8217;s dependency mechanism to only 
run tasks when it detects a change to one of the source files.</p>
+<p>You can also control the target directory.  Use <code>compile.target</code> 
to get the target directory file task.  If you need to change the target 
directory, call the <code>compile.into</code> method with the new path.</p>
+<p>We use method pairs to give you finer control over the compiler, but also a 
way to easily configure it.  Methods like <code>dependencies</code> and 
<code>sources</code> give you a live array you can manipulate, or iterate over. 
 On the other hand, methods like <code>with</code> and <code>from</code> accept 
a wider set of arguments and clean them up for you.  They also all return the 
same task you&#8217;re calling, so you can chain methods together.</p>
+<p>For example:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">compile</span><span class="o">.</span><span 
class="n">from</span><span class="p">(</span><span 
class="s1">&#39;srcs&#39;</span><span class="p">)</span><span 
class="o">.</span><span class="n">with</span><span class="p">(</span><span 
class="s1">&#39;org.apache.axis2:axis2:jar:1.2&#39;</span><span 
class="p">)</span><span class="o">.</span>
+  <span class="n">into</span><span class="p">(</span><span 
class="s1">&#39;classes&#39;</span><span class="p">)</span><span 
class="o">.</span><span class="n">using</span><span class="p">(</span><span 
class="ss">:target</span><span class="o">=&gt;</span><span 
class="s1">&#39;1.4&#39;</span><span 
class="p">)</span></code></pre></figure><p>Buildr uses the method pair and 
method chaining idiom in many places to make your life easier without 
sacrificing flexibility.</p>
+<p>Occasionally, you&#8217;ll need to post-process the generated bytecode.  
Since you only want to do that after compiling, and let the compiler decide 
when to do that – only when changes require re-compiling – you&#8217;ll 
want to extend the <code>compile</code> task.  You can do that by calling 
<code>compile</code> with a block.</p>
+<p>For example, to run the OpenJPA bytecode enhancer after compiling the 
source files:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">compile</span> <span class="p">{</span> <span 
class="n">open_jpa_enhance</span> <span 
class="p">}</span></code></pre></figure><p>You can change various compile 
options by calling, you guessed, <code>compile.options</code>.  For example, to 
set the compiler to VM compatibility with Java 1.5 and turn on all Lint 
messages:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><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">compile</span><span class="o">.</span><span 
class="n">options</span><span class="o">.</span><span class="n">lint</span> 
<span class="o">=</span> <span 
class="s1">&#39;all&#39;</span></code></pre></figure><p>Or, if you want to 
chain methods together:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">compile</span><span class="o">.</span><span 
class="n">using</span> <span class="ss">:target</span><span 
class="o">=&gt;</span><span class="s1">&#39;1.5&#39;</span><span 
class="p">,</span> <span class="ss">:lint</span><span 
class="o">=&gt;</span><span 
class="s1">&#39;all&#39;</span></code></pre></figure><p>Sub-projects inherit 
compile options from their parent project, so you only need to change these 
settings once in the top project.  You can do so, even if the top project 
itself doesn&#8217;t compile anything.</p>
+<p>The options available to you depend on which compiler you are using for 
this particular project, obviously the options are not the same for Java and 
Flash. Two options are designed to work consistently across compilers.</p>
+<p>Buildr turns the <code>warning</code> option on by default, but turns it 
off when you run <code>buildr --silent</code>.  It also sets the 
<code>debug</code> option on, but turns it off when making a release.  You can 
also control the <code>debug</code> option from the command line, for 
example:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="c1"># When calling buildr</span>
+<span class="err">$</span> <span class="n">buildr</span> <span 
class="n">compile</span> <span class="n">debug</span><span 
class="o">=</span><span class="n">off</span>
+
+<span class="c1"># Once until we change the variable</span>
+<span class="err">$</span> <span class="n">export</span> <span 
class="no">DEBUG</span><span class="o">=</span><span class="n">off</span>
+<span class="err">$</span> <span class="n">buildr</span> <span 
class="n">compile</span></code></pre></figure><p>The default source and target 
directories, compiler settings and other options you can use depend on the 
specific language.  You can find more information in the <a 
href="languages.html">Languages</a> section.</p>
+<h2 id="resources">Resources</h2>
+<p>The <code>compile</code> task comes bundled with a <code>resources</code> 
task.  It copies files from the <code>src/main/resources</code> directory into 
<code>target/resources</code>.  Best used for copying files that you want to 
include in the generated code, like configuration files, i18n messages, images, 
etc.</p>
+<p>The <code>resources</code> task uses a filter that can change files as it 
copies them from source to destination.  The most common use is by mapping 
values using a hash. For example, to substitute &#8220;${version}&#8221; for 
the project&#8217;s version number and &#8220;${copyright}&#8221; for 
&#8220;Acme Inc &#169; 2007&#8221; :</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">resources</span><span class="o">.</span><span 
class="n">filter</span><span class="o">.</span><span class="n">using</span> 
<span class="s1">&#39;version&#39;</span><span class="o">=&gt;</span><span 
class="n">version</span><span class="p">,</span>
+  <span class="s1">&#39;copyright&#39;</span><span class="o">=&gt;</span><span 
class="s1">&#39;Acme Inc (C) 2007&#39;</span></code></pre></figure><p>You can 
also use <a href="settings_profiles.html#profiles">profiles</a> to supply a 
name/value map that all <code>resources</code> task should default to, by 
adding a <code>filter</code> element to each of the profiles.  The following 
examples shows a <code>profiles.yaml</code> file that applies the same filter 
in development and test environments:</p>
+<figure class="highlight"><pre><code class="language-yaml" 
data-lang="yaml"><span class="l-Scalar-Plain">filter</span><span 
class="p-Indicator">:</span> <span class="nl">&amp;alpha1</span>
+  <span class="l-Scalar-Plain">version</span><span 
class="p-Indicator">:</span> <span class="l-Scalar-Plain">experimental</span>
+  <span class="l-Scalar-Plain">copyright</span><span 
class="p-Indicator">:</span> <span class="l-Scalar-Plain">Acme Inc (C) 
2007</span>
+
+<span class="l-Scalar-Plain">development</span><span 
class="p-Indicator">:</span>
+  <span class="l-Scalar-Plain">filter</span><span class="p-Indicator">:</span> 
<span class="nv">*alpha1</span>
+<span class="l-Scalar-Plain">test</span><span class="p-Indicator">:</span>
+  <span class="l-Scalar-Plain">filter</span><span class="p-Indicator">:</span> 
<span class="nv">*alpha1</span></code></pre></figure><p>You can specify a 
different format by passing it as the first argument. Supported formats 
include:</p>
+<table>
+       <tr>
+               <th>Format  </th>
+               <th>Usage </th>
+       </tr>
+       <tr>
+               <td> <code>:ant</code>    </td>
+               <td> Map from <code>@key@</code> to value. </td>
+       </tr>
+       <tr>
+               <td> <code>:maven</code>  </td>
+               <td> Map from <code>${key}</code> to value (default). </td>
+       </tr>
+       <tr>
+               <td> <code>:ruby</code>   </td>
+               <td> Map from <code>#{key}</code> to value. </td>
+       </tr>
+       <tr>
+               <td> <code>:erb</code>    </td>
+               <td> Map from <code>&lt;%=key%&gt;</code> to value. </td>
+       </tr>
+       <tr>
+               <td> <code>Regexp</code>  </td>
+               <td> Map using the matched value of the regular expression 
(e.g. <code>/=(.*?)=/</code>). </td>
+       </tr>
+</table>
+<p>For example, using the <code>:ruby</code> format instead of the default 
<code>:maven</code> format:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">resources</span><span class="o">.</span><span 
class="n">filter</span><span class="o">.</span><span class="n">using</span> 
<span class="ss">:ruby</span><span class="p">,</span> <span 
class="s1">&#39;version&#39;</span><span class="o">=&gt;</span><span 
class="n">version</span><span class="p">,</span>
+  <span class="s1">&#39;copyright&#39;</span><span class="o">=&gt;</span><span 
class="s1">&#39;Acme Inc (C) 2007&#39;</span></code></pre></figure><p>For more 
complicated mapping you can also pass a method or a proc.  The filter will call 
it once for each file with the file name and content.</p>
+<p>If you need to copy resource files from other directories, add these source 
directories by calling the <code>from</code> method, for example:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">resources</span><span class="o">.</span><span 
class="n">from</span> <span class="n">_</span><span class="p">(</span><span 
class="s1">&#39;src/etc&#39;</span><span 
class="p">)</span></code></pre></figure><p>You can select to copy only specific 
files using common file matching patterns. For example, to include only <span 
class="caps">HTML</span> files:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">resources</span><span class="o">.</span><span 
class="n">include</span> <span 
class="s1">&#39;*.html&#39;</span></code></pre></figure><p>To include all 
files, except for files in the <code>scratch</code> directory:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">resources</span><span class="o">.</span><span 
class="n">exclude</span> <span 
class="s1">&#39;scratch/*&#39;</span></code></pre></figure><p>The filter always 
excludes the <code>CVS</code> and <code>.svn</code> directories, and all files 
ending with <code>.bak</code> or <code>~</code>, so no need to worry about 
these.</p>
+<p>A file pattern can match any file name or part of a file name using an 
asterisk (<code>*</code>).  Double asterisk (<code>**</code>) matches 
directories recursively, for example, <code>'src/main/java/**/*.java'</code>.  
You can match any character using a question mark (<code>?</code>), or a set of 
characters using square brackets (<code>[]</code>), similar to regular 
expressions, for example, <code>'[Rr]eadme'</code>. You can also match from a 
set of names using curly braces (<code>{}</code>), for example, 
<code>'*.{html,css}'</code>.</p>
+<p>You can use filters elsewhere.  The <code>filter</code> method creates a 
filter, the <code>into</code> method sets the target directory, and 
<code>using</code> specifies the mapping. Last, you call <code>run</code> on 
the filter to activate it.</p>
+<p>For example:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">filter</span><span class="p">(</span><span 
class="s1">&#39;src/specs&#39;</span><span class="p">)</span><span 
class="o">.</span><span class="n">into</span><span class="p">(</span><span 
class="s1">&#39;target/specs&#39;</span><span class="p">)</span><span 
class="o">.</span>
+  <span class="n">using</span><span class="p">(</span><span 
class="s1">&#39;version&#39;</span><span class="o">=&gt;</span><span 
class="n">version</span><span class="p">,</span> <span 
class="s1">&#39;created&#39;</span><span class="o">=&gt;</span><span 
class="no">Time</span><span class="o">.</span><span class="n">now</span><span 
class="p">)</span><span class="o">.</span><span 
class="n">run</span></code></pre></figure><p>The <code>resources</code> task 
is, in fact, just a wrapper around such a filter that automatically adds the 
<code>src/main/resources</code> directory as one of the source directories.</p>
+<h2 id="more">More On Building</h2>
+<p>The <code>build</code> task runs the <code>compile</code> (and 
<code>resources</code>) tasks as prerequisites, followed by any actions you add 
to it, and completes by running the <code>test</code> task.  The 
<code>build</code> task itself is a prerequisite to other tasks, for example, 
<code>package</code> and <code>upload</code>.</p>
+<p>You can extend the <code>build</code> task in two ways.  You can add more 
prerequisites that will execute before the task itself, or you can add actions 
that will execute as part of the task.  Which one you choose is up to you, 
we&#8217;ll show you how they differ in a second.  If you call 
<code>build</code> with a list of tasks, it adds these tasks as prerequisites.  
Call <code>build</code> with a block, and it adds that block as an action.  
Again, a common idiom you&#8217;ll see elsewhere in Buildr and Rake.</p>
+<p>Let&#8217;s look at a simple example.  Say we want to generate a Derby 
database from an <span class="caps">SQL</span> file and include it in the <span 
class="caps">ZIP</span> package:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">db</span> <span class="o">=</span> <span 
class="no">Derby</span><span class="o">.</span><span 
class="n">create</span><span class="p">(</span><span class="n">_</span><span 
class="p">(</span><span class="s1">&#39;target/derby/db&#39;</span><span 
class="p">)</span><span class="o">=&gt;</span><span class="n">_</span><span 
class="p">(</span><span class="s1">&#39;src/main/sql/derby.sql&#39;</span><span 
class="p">))</span>
+<span class="n">package</span><span class="p">(</span><span 
class="ss">:zip</span><span class="p">)</span><span class="o">.</span><span 
class="n">include</span> <span 
class="n">db</span></code></pre></figure><p>There&#8217;s nothing fundamentally 
wrong with this code, if that&#8217;s what you intend to do.  But in practice, 
you don&#8217;t always run the <code>package</code> task during development, so 
you won&#8217;t notice if something is wrong with this task when you build.  
For example, if it fails to generate the <span class="caps">SQL</span> file.  
In addition, the <code>package</code> task runs after <code>build</code>, so 
you can&#8217;t use the database in your test cases.</p>
+<p>So let&#8217;s refactor it.  We&#8217;re going to use the variable 
<code>db</code> to reference the file task that creates the database, and make 
it a prerequisite of the <code>build</code> task.  And use that same variable 
again to include the database in the <span class="caps">ZIP</span> package:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">db</span> <span class="o">=</span> <span 
class="no">Derby</span><span class="o">.</span><span 
class="n">create</span><span class="p">(</span><span class="n">_</span><span 
class="p">(</span><span class="s1">&#39;target/derby/db&#39;</span><span 
class="p">)</span><span class="o">=&gt;</span><span class="n">_</span><span 
class="p">(</span><span class="s1">&#39;src/main/sql/derby.sql&#39;</span><span 
class="p">))</span>
+<span class="n">build</span> <span class="n">db</span>
+<span class="n">package</span><span class="p">(</span><span 
class="ss">:zip</span><span class="p">)</span><span class="o">.</span><span 
class="n">include</span> <span class="n">db</span></code></pre></figure><p>Much 
better.  We&#8217;re using the same task twice, but since we&#8217;re using 
Rake here, it will only execute once.  In fact, it will only execute if we 
don&#8217;t already have a Derby database, or if it detects a change to the 
<span class="caps">SQL</span> file and needs to recreate the database.</p>
+<p class="tip"><code>Derby.create</code> is not part of Buildr, you can get <a 
href="http://svn.apache.org/repos/asf/ode/trunk/tasks/derby.rake";>derby.rake</a>
 here.</p>
+<p>Here&#8217;s another example.  We want to copy some files over as part of 
the build, and apply a filter to them.  This time, we&#8217;re going to extend 
the <code>build</code> task:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">build</span> <span class="k">do</span>
+  <span class="n">filter</span><span class="p">(</span><span 
class="s1">&#39;src/specs&#39;</span><span class="p">)</span><span 
class="o">.</span><span class="n">into</span><span class="p">(</span><span 
class="s1">&#39;target/specs&#39;</span><span class="p">)</span><span 
class="o">.</span>
+    <span class="n">using</span><span class="p">(</span><span 
class="s1">&#39;version&#39;</span><span class="o">=&gt;</span><span 
class="n">version</span><span class="p">,</span> <span 
class="s1">&#39;created&#39;</span><span class="o">=&gt;</span><span 
class="no">Time</span><span class="o">.</span><span class="n">now</span><span 
class="p">)</span><span class="o">.</span><span class="n">run</span>
+<span class="k">end</span></code></pre></figure><p>The <code>build</code> task 
is recursive, so running <code>buildr build</code> picks the current project 
and runs its <code>build</code> task, which in turn runs the <code>build</code> 
task on each of its sub-projects.  One <code>build</code> task to rule them 
all.</p>
+<h2 id="cleaning">Cleaning</h2>
+<p>The <code>build</code> task has an evil twin, the <code>clean</code> task.  
It&#8217;s the task you use to remove all the files created during the build, 
especially when you mess things up and want to start all over.</p>
+<p>It basically erases the target directories, the one called 
<code>target</code>, and if you get creative and change the target directory 
for tasks like <code>compile</code>, it will also erase those.  If you decide 
to generate files outside the target directory and want to cleanup after 
yourself, just extend the <code>clean</code> task.</p>
+<p>For example:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">clean</span> <span class="p">{</span> <span 
class="n">rm_rf</span> <span class="n">_</span><span class="p">(</span><span 
class="s1">&#39;staged&#39;</span><span class="p">)</span> <span 
class="p">}</span></code></pre></figure><p>The <code>rm_rf</code> method 
deletes the directory and all files in it.  It&#8217;s named after UNIX&#8217;s 
infamous <code>rm -rf</code>.  Use it wisely.  This is also a good time to 
introduce you to <code>FileUtils</code>, a standard Ruby library that contains 
convenient methods for creating and deleting directories, copying and moving 
files, even comparing two files.  They&#8217;re all free of charge when you use 
Buildr.</p>
+<h2 id="continuous-compilation">Continuous Compilation</h2>
+<p>And if all that weren&#8217;t enough, Buildr also offers a time-saving 
feature called continuous compilation.  This feature, implemented by the 
<code>cc</code> task, instructs Buildr to loop eternally, polling your 
project&#8217;s source directories for changes.  Whenever a change is detected, 
Buildr immediately triggers the appropriate compilation step and goes right 
back to polling.  This allows you to reap many of the benefits of an 
incrementally compiling <span class="caps">IDE</span> like Eclipse without 
sacrificing your favorite build tool.</p>
+<p>To get started, simply invoke the <code>cc</code> task at the command 
prompt:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>buildr cc</code></pre></figure><p>This task will 
immediately invoke the <code>compile</code> and <code>test:compile</code> tasks 
on your project if necessary.  This ensures that your build is completely up to 
the minute before polling is initiated.  After this initial build (if 
required), Buildr will print a notification indicating which directories are 
being monitored.  By default, these directories will include any source folders 
(e.g. <code>src/main/java/</code>), any test directories (e.g. 
<code>src/spec/scala/</code>) as well as any resources (e.g. 
@src/main/resources/).  The Buildr process will remain running during this 
time, meaning that in order to test this functionality, we will need to open a 
new shell:</p>
+<figure class="highlight"><pre><code class="language-sh" data-lang="sh"><span 
class="nv">$ </span>touch src/main/java/Test.java</code></pre></figure><p>The 
moment we run this command, Buildr will detect the change and invoke the 
<code>compile</code> task.  It will <strong>not</strong> invoke the 
<code>test:compile</code> task, since none of the test files were actually 
changed.  This ensures that potentially time-consuming tasks are avoided if 
possible.  Note that, unlike the <code>build</code> task, the continuous 
compilation also does not actually run any of your tests.  Continuous 
compilation is designed to be a simple daemon which runs forever, quickly 
recompiling your project as soon as you save or delete a file.  We can 
terminate the continuous compilation task by pressing Ctrl-C.  Left to its own 
devices, the <code>cc</code> task really will loop forever.</p>
+<p>There are several advantages to continuous compilation.  Number one is 
convenience.  Once you invoke the <code>cc</code> task, you can focus 
exclusively on the code, editing and saving your files in an unbroken workflow. 
 There is no need to break your concentration to invoke Buildr manually unless 
you need to run the test suite, deploy the application or anything beyond 
compilation.  The second advantage is speed.  By using the continuous 
compilation process, you avoid repeatedly incurring Buildr&#8217;s startup 
overhead.  While this startup time is kept to a minimum, it is still 
perceptable, particularly when running on JRuby.  Since the <code>cc</code> 
task runs within a Buildr instance which has already been started, there is no 
need for repeated, inefficient load times.  Again, this allows you to focus 
more completely on what&#8217;s really important: the code.</p>
+<p>By default, the <code>cc</code> task will poll your sources once every 200 
milliseconds.  We have found that this frequency strikes a nice balance between 
<span class="caps">CPU</span> load (which is insignificant) and nearly-instant 
detection.  However, you may wish to tune this value based on your own needs.  
To do so, simply use the <code>cc.frequency</code> property in your project 
definition:</p>
+<figure class="highlight"><pre><code class="language-ruby" 
data-lang="ruby"><span class="n">project</span> <span 
class="s1">&#39;foo&#39;</span> <span class="k">do</span>
+  <span class="n">cc</span><span class="o">.</span><span 
class="n">frequency</span> <span class="mi">1</span><span 
class="o">.</span><span class="mi">5</span>      <span class="c1"># poll every 
one-and-a-half seconds</span>
+<span class="k">end</span></code></pre></figure><p>If you find that the 200 ms 
default imposes too much overhead, try changing <code>cc.frequency</code> to a 
higher value.  On the flip side, if you find that you&#8217;re waiting too long 
for changes to be caught by the poll, tune the frequency lower.</p>
+<p>Now let&#8217;s <a href="artifacts.html">talk about the artifacts</a> we 
mentioned before.</p>
+      </div>
+      <div id='footer'>Copyright &copy; 2007-2016 The Apache Software 
Foundation</div>
+    </div>
+  </body>
+</html>


Reply via email to