You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@buildr.apache.org by do...@apache.org on 2013/10/06 09:17:12 UTC
svn commit: r1529576 [5/18] - in /buildr/site: ./ rdoc/ rdoc/Benchmark/
rdoc/Buildr/ rdoc/Buildr/ArchiveTask/ rdoc/Buildr/ArtifactNamespace/
rdoc/Buildr/Assets/ rdoc/Buildr/Checks/ rdoc/Buildr/Cobertura/
rdoc/Buildr/Cobertura/CoberturaExtension/ rdoc/B...
Modified: buildr/site/packaging.html
URL: http://svn.apache.org/viewvc/buildr/site/packaging.html?rev=1529576&r1=1529575&r2=1529576&view=diff
==============================================================================
--- buildr/site/packaging.html (original)
+++ buildr/site/packaging.html Sun Oct 6 07:17:05 2013
@@ -83,32 +83,22 @@
<ol class="toc"><li><a href="#referencing">Specifying And Referencing Packages</a></li><li><a href="#zip">Packaging ZIPs</a></li><li><a href="#jar">Packaging JARs</a></li><li><a href="#war">Packaging WARs</a></li><li><a href="#aar">Packaging AARs</a></li><li><a href="#ear">Packaging EARs</a></li><li><a href="#bundle">Packaging OSGi Bundles</a></li><li><a href="#tar">Packaging Tars and GZipped Tars</a></li><li><a href="#install_upload">Installing and Uploading</a></li><li><a href="#source_javadoc">Packaging Sources and JavaDocs</a></li></ol>
<p>For our next trick, we’re going to try and create an artifact ourselves. We’re going to start with:</p>
<div class="highlight"><pre><code class="ruby"><span class="n">package</span> <span class="ss">:jar</span>
-</code></pre>
-</div>
-<p>We just told the project to create a <span class="caps">JAR</span> file in the <code>target</code> directory, including all the classes (and resources) that we previously compiled into <code>target/classes</code>. Or we can create a <span class="caps">WAR</span> file:</p>
+</code></pre></div><p>We just told the project to create a <span class="caps">JAR</span> file in the <code>target</code> directory, including all the classes (and resources) that we previously compiled into <code>target/classes</code>. Or we can create a <span class="caps">WAR</span> file:</p>
<div class="highlight"><pre><code class="ruby"><span class="n">package</span> <span class="ss">:war</span>
-</code></pre>
-</div>
-<p>The easy case is always easy, but sometimes we have more complicated use cases which we’ll address through the rest of this section.</p>
+</code></pre></div><p>The easy case is always easy, but sometimes we have more complicated use cases which we’ll address through the rest of this section.</p>
<p>Now let’s run the build, test cases and create these packages:</p>
<div class="highlight"><pre><code class="sh"><span class="nv">$ </span>buildr package
-</code></pre>
-</div>
-<p>The <code>package</code> task runs the <code>build</code> task (remember: <code>compile</code> and <code>test</code>) and then runs each of the packaging tasks, creating packages in the projects’ target directories.</p>
+</code></pre></div><p>The <code>package</code> task runs the <code>build</code> task (remember: <code>compile</code> and <code>test</code>) and then runs each of the packaging tasks, creating packages in the projects’ target directories.</p>
<p class="tip">The <code>package</code> task and <code>package</code> methods are related, but that relation is different from other task/method pairs. The <code>package</code> method creates a file task that points to the package in the <code>target</code> directory and knows how to create it. It then adds itself as a prerequisite to the <code>package</code> task. Translation: you can create multiple packages from the same project.</p>
<h2 id="referencing">Specifying And Referencing Packages</h2>
<p>Buildr supports several packaging types, and so when dealing with packages, you have to indicate the desired package type. The packaging type can be the first argument, or the value of the <code>:type</code> argument. The following two are equivalent:</p>
<div class="highlight"><pre><code class="ruby"><span class="n">package</span> <span class="ss">:jar</span>
<span class="n">package</span> <span class="ss">:type</span><span class="o">=></span><span class="ss">:jar</span>
-</code></pre>
-</div>
-<p>If you do not specify a package type, Buildr will attempt to infer one.</p>
+</code></pre></div><p>If you do not specify a package type, Buildr will attempt to infer one.</p>
<p>In the documentation you will find a number of tasks dealing with specific packaging types (<code>ZipTask</code>, <code>JarTask</code>, etc). The <code>package</code> method is a convenience mechanism that sets up the package for you associates it with various project life cycle tasks.</p>
<p>To package a particular file, use the <code>:file</code> argument, for example:</p>
<div class="highlight"><pre><code class="ruby"><span class="n">package</span> <span class="ss">:zip</span><span class="p">,</span> <span class="ss">:file</span><span class="o">=></span><span class="n">_</span><span class="p">(</span><span class="s1">'target/interesting.zip'</span><span class="p">)</span>
-</code></pre>
-</div>
-<p>This returns a file task that will run as part of the project’s <code>package</code> task (generating all packages). It will invoke the <code>build</code> task to generate any necessary prerequisites, before creating the specified file.</p>
+</code></pre></div><p>This returns a file task that will run as part of the project’s <code>package</code> task (generating all packages). It will invoke the <code>build</code> task to generate any necessary prerequisites, before creating the specified file.</p>
<p>The package type does not have to be the same as the file name extension, but if you don’t specify the package type, it will be inferred from the extension.</p>
<p>Most often you will want to use the second form to generate packages that are also artifacts. These packages have an artifact specification, which you can use to reference them from other projects (and buildfiles). They are also easier to share across projects: artifacts install themselves in the local repository when running the <code>install</code> task, and upload to the remote repository when running the <code>upload</code> task (see <a href="#install_upload">Installing and Uploading</a>).</p>
<p>The artifact specification is based on the project name (using dashes instead of colons), group identifier and version number, all three obtained from the project definition. You can specify different values using the <code>:id</code>, <code>:group</code>, <code>:version</code> and <code>:classifier</code> arguments. For example:</p>
@@ -126,102 +116,66 @@
<span class="n">package</span> <span class="ss">:zip</span><span class="p">,</span> <span class="ss">:classifier</span><span class="o">=></span><span class="s1">'sources'</span>
<span class="k">end</span>
<span class="k">end</span>
-</code></pre>
-</div>
-<p>The file name is determined from the identifier, version number, classifier and extension associated with that packaging type.</p>
+</code></pre></div><p>The file name is determined from the identifier, version number, classifier and extension associated with that packaging type.</p>
<p>If you do not specify the packaging type, Buildr attempt to infer it from the project definition. In the general case it will use the default packaging type, <span class="caps">ZIP</span>. A project that compiles Java classes will default to <span class="caps">JAR</span> packaging; for other languages, consult the specific documentation.</p>
<p>A single project can create multiple packages. For example, a Java project may generate a <span class="caps">JAR</span> package for the runtime library and another <span class="caps">JAR</span> containing just the <span class="caps">API</span>; a <span class="caps">ZIP</span> file for the source code and another <span class="caps">ZIP</span> for the documentation. Make sure to always call <code>package</code> with enough information to identify the specific package you are referencing. Even if the project only defines a single package, calling the <code>package</code> method with no arguments does not necessarily refer to that one.</p>
<p>You can use the <code>packages</code> method to obtain a list of all packages defined in the project, for example:</p>
<div class="highlight"><pre><code class="ruby"><span class="n">project</span><span class="p">(</span><span class="s1">'killer-app:teh-impl'</span><span class="p">)</span><span class="o">.</span><span class="n">packages</span><span class="o">.</span><span class="n">first</span>
<span class="n">project</span><span class="p">(</span><span class="s1">'killer-app:teh-impl'</span><span class="p">)</span><span class="o">.</span><span class="n">packages</span><span class="o">.</span><span class="n">select</span> <span class="p">{</span> <span class="o">|</span><span class="n">pkg</span><span class="o">|</span> <span class="n">pkg</span><span class="o">.</span><span class="n">type</span> <span class="o">==</span> <span class="ss">:zip</span> <span class="p">}</span>
-</code></pre>
-</div>
-<h2 id="zip">Packaging ZIPs</h2>
+</code></pre></div><h2 id="zip">Packaging ZIPs</h2>
<p><span class="caps">ZIP</span> is the most common form of packaging, used by default when no other packaging type applies. It also forms the basis for many other packaging types (e.g. <span class="caps">JAR</span> and <span class="caps">WAR</span>). Most of what you’ll find here applies to other packaging types.</p>
<p>Let’s start by including additional files in the <span class="caps">ZIP</span> package. We’re going to include the <code>target/docs</code> directory and <code>README</code> file:</p>
<div class="highlight"><pre><code class="ruby"><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">_</span><span class="p">(</span><span class="s1">'target/docs'</span><span class="p">),</span> <span class="s1">'README'</span>
-</code></pre>
-</div>
-<p>The <code>include</code> method accepts files, directories and file tasks. You can also use file pattern to match multiple files and directories. File patterns include asterisk (<code>*</code>) to match any file name or part of a file name, double asterisk (<code>**</code>) to match directories recursively, question mark (<code>?</code>) to match any character, square braces (<code>[]</code>) to match a set of characters, and curly braces (<code>{}</code>) to match one of several names.</p>
+</code></pre></div><p>The <code>include</code> method accepts files, directories and file tasks. You can also use file pattern to match multiple files and directories. File patterns include asterisk (<code>*</code>) to match any file name or part of a file name, double asterisk (<code>**</code>) to match directories recursively, question mark (<code>?</code>) to match any character, square braces (<code>[]</code>) to match a set of characters, and curly braces (<code>{}</code>) to match one of several names.</p>
<p>And the same way you <code>include</code>, you can also <code>exclude</code> specific files you don’t want showing up in the <span class="caps">ZIP</span>. For example, to exclude <code>.draft</code> and <code>.raw</code> files:</p>
<div class="highlight"><pre><code class="ruby"><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="p">(</span><span class="n">_</span><span class="p">(</span><span class="s1">'target/docs'</span><span class="p">))</span><span class="o">.</span><span class="n">exclude</span><span class="p">(</span><span class="s1">'*.draft'</span><span class="p">,</span> <span class="s1">'*.raw'</span><span class="p">)</span>
-</code></pre>
-</div>
-<p>So far we’ve included files under the root of the <span class="caps">ZIP</span>. Let’s include some files under a given path using the <code>:path</code> option:</p>
+</code></pre></div><p>So far we’ve included files under the root of the <span class="caps">ZIP</span>. Let’s include some files under a given path using the <code>:path</code> option:</p>
<div class="highlight"><pre><code class="ruby"><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">_</span><span class="p">(</span><span class="s1">'target/docs'</span><span class="p">),</span> <span class="ss">:path</span><span class="o">=></span><span class="s2">"</span><span class="si">#{</span><span class="nb">id</span><span class="si">}</span><span class="s2">-</span><span class="si">#{</span><span class="n">version</span><span class="si">}</span><span class="s2">"</span>
-</code></pre>
-</div>
-<p>If you need to use the <code>:path</code> option repeatedly, consider using the <code>tap</code> method instead. For example:</p>
+</code></pre></div><p>If you need to use the <code>:path</code> option repeatedly, consider using the <code>tap</code> method instead. For example:</p>
<div class="highlight"><pre><code class="ruby"><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">path</span><span class="p">(</span><span class="s2">"</span><span class="si">#{</span><span class="nb">id</span><span class="si">}</span><span class="s2">-</span><span class="si">#{</span><span class="n">version</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span><span class="o">.</span><span class="n">tap</span> <span class="k">do</span> <span class="o">|</span><span class="n">path</span><span class="o">|</span>
<span class="n">path</span><span class="o">.</span><span class="n">include</span> <span class="n">_</span><span class="p">(</span><span class="s1">'target/docs'</span><span class="p">)</span>
<span class="n">path</span><span class="o">.</span><span class="n">include</span> <span class="n">_</span><span class="p">(</span><span class="s1">'README'</span><span class="p">)</span>
<span class="k">end</span>
-</code></pre>
-</div>
-<p class="tip">The <code>tap</code> method is not part of the core library, but a very useful extension. It takes an object, yields to the block with that object, and then returns that object.</p>
+</code></pre></div><p class="tip">The <code>tap</code> method is not part of the core library, but a very useful extension. It takes an object, yields to the block with that object, and then returns that object.</p>
<p class="note">To allow you to spread files across different paths, the include/exclude patterns are specific to a path. So in the above example, if you want to exclude some files from the “target/docs” directory, make sure to call <code>exclude</code> on the path, not on the <span class="caps">ZIP</span> task itself.</p>
<p>If you need to include a file or directory under a different name, use the <code>:as</code> option. For example:</p>
<div class="highlight"><pre><code class="ruby"><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="p">(</span><span class="n">_</span><span class="p">(</span><span class="s1">'corporate-logo-350x240.png'</span><span class="p">),</span> <span class="ss">:as</span><span class="o">=></span><span class="s1">'logo.png'</span><span class="p">)</span>
-</code></pre>
-</div>
-<p>You can also use <code>:as=>'.'</code> to include all files from the given directory. For example:</p>
+</code></pre></div><p>You can also use <code>:as=>'.'</code> to include all files from the given directory. For example:</p>
<div class="highlight"><pre><code class="ruby"><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">_</span><span class="p">(</span><span class="s1">'target/docs/*'</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">_</span><span class="p">(</span><span class="s1">'target/docs'</span><span class="p">),</span> <span class="ss">:as</span><span class="o">=></span><span class="s1">'.'</span>
-</code></pre>
-</div>
-<p>These two perform identically. They both include all the files from the <code>target/docs</code> directory, but not the directory itself, and they are both lazy, meaning that the files can be created later and they will still get packaged into the zip package.</p>
+</code></pre></div><p>These two perform identically. They both include all the files from the <code>target/docs</code> directory, but not the directory itself, and they are both lazy, meaning that the files can be created later and they will still get packaged into the zip package.</p>
<p>For example, when you use <code>package :jar</code>, under the hood it specifies to include all the files from <code>target/classes</code> with <code>:as=>'.'</code>. Even though this happens during project definition and nothing has been compiled yet (and in fact <code>target/classes</code> may not even exist yet), the .class files generated during compilation are still packaged in the .jar file, as expected.</p>
<p>If you need to get rid of all the included files, call the <code>clean</code> method. Some packaging types default to adding various files and directories, for example, <span class="caps">JAR</span> packaging will include all the compiled classes and resources.</p>
<p>You can also merge two <span class="caps">ZIP</span> files together, expanding the content of one <span class="caps">ZIP</span> into the other. For example:</p>
<div class="highlight"><pre><code class="ruby"><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">merge</span> <span class="n">_</span><span class="p">(</span><span class="s1">'part1.zip'</span><span class="p">),</span> <span class="n">_</span><span class="p">(</span><span class="s1">'part2.zip'</span><span class="p">)</span>
-</code></pre>
-</div>
-<p>If you need to be more selective, you can apply the include/exclude pattern to the expanded <span class="caps">ZIP</span>. For example:</p>
+</code></pre></div><p>If you need to be more selective, you can apply the include/exclude pattern to the expanded <span class="caps">ZIP</span>. For example:</p>
<div class="highlight"><pre><code class="ruby"><span class="c1"># Everything but the libs</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">merge</span><span class="p">(</span><span class="n">_</span><span class="p">(</span><span class="s1">'bigbad.war'</span><span class="p">))</span><span class="o">.</span><span class="n">exclude</span><span class="p">(</span><span class="s1">'libs/**/*'</span><span class="p">)</span>
-</code></pre>
-</div>
-<h2 id="jar">Packaging JARs</h2>
+</code></pre></div><h2 id="jar">Packaging JARs</h2>
<p><span class="caps">JAR</span> packages extend <span class="caps">ZIP</span> packages with support for Manifest files and the <span class="caps">META</span>-<span class="caps">INF</span> directory. They also default to include the class files found in the <code>target/classes</code> directory.</p>
<p>You can tell the <span class="caps">JAR</span> package to include a particular Manifest file:</p>
<div class="highlight"><pre><code class="ruby"><span class="n">package</span><span class="p">(</span><span class="ss">:jar</span><span class="p">)</span><span class="o">.</span><span class="n">with</span> <span class="ss">:manifest</span><span class="o">=></span><span class="n">_</span><span class="p">(</span><span class="s1">'src/main/MANIFEST.MF'</span><span class="p">)</span>
-</code></pre>
-</div>
-<p>Or generate a manifest from a hash:</p>
+</code></pre></div><p>Or generate a manifest from a hash:</p>
<div class="highlight"><pre><code class="ruby"><span class="n">package</span><span class="p">(</span><span class="ss">:jar</span><span class="p">)</span><span class="o">.</span><span class="n">with</span> <span class="ss">:manifest</span><span class="o">=></span><span class="p">{</span> <span class="s1">'Copyright'</span><span class="o">=></span><span class="s1">'Acme Inc (C) 2007'</span> <span class="p">}</span>
-</code></pre>
-</div>
-<p>You can also generate a <span class="caps">JAR</span> with no manifest with the value <code>false</code>, create a manifest with several sections using an array of hashes, or create it from a proc.</p>
+</code></pre></div><p>You can also generate a <span class="caps">JAR</span> with no manifest with the value <code>false</code>, create a manifest with several sections using an array of hashes, or create it from a proc.</p>
<p>In large projects, where all the packages use the same manifest, it’s easier to set it once on the top project using the <code>manifest</code> project property. Sub-projects inherit the property from their parents, and the <code>package</code> method uses that property if you don’t override it, as we do above.</p>
<p>For example, we can get the same result by specifying this at the top project:</p>
<div class="highlight"><pre><code class="ruby"><span class="n">manifest</span><span class="o">[</span><span class="s1">'Copyright'</span><span class="o">]</span> <span class="o">=</span> <span class="s1">'Acme Inc (C) 2007'</span>
-</code></pre>
-</div>
-<p>If you need to mix-in the project’s manifest with values that only one package uses, you can do so easily:</p>
+</code></pre></div><p>If you need to mix-in the project’s manifest with values that only one package uses, you can do so easily:</p>
<div class="highlight"><pre><code class="ruby"><span class="n">package</span><span class="p">(</span><span class="ss">:jar</span><span class="p">)</span><span class="o">.</span><span class="n">with</span> <span class="ss">:manifest</span><span class="o">=></span><span class="n">manifest</span><span class="o">.</span><span class="n">merge</span><span class="p">(</span><span class="s1">'Main-Class'</span><span class="o">=></span><span class="s1">'com.acme.Main'</span><span class="p">)</span>
-</code></pre>
-</div>
-<p>If you need to include more files in the <code>META-INF</code> directory, you can use the <code>:meta_inf</code> option. You can give it a file, or array of files. And yes, there is a <code>meta_inf</code> project property you can set once to include the same set of file in all the JARs. It works like this:</p>
+</code></pre></div><p>If you need to include more files in the <code>META-INF</code> directory, you can use the <code>:meta_inf</code> option. You can give it a file, or array of files. And yes, there is a <code>meta_inf</code> project property you can set once to include the same set of file in all the JARs. It works like this:</p>
<div class="highlight"><pre><code class="ruby"><span class="n">meta_inf</span> <span class="o"><<</span> <span class="n">file</span><span class="p">(</span><span class="s1">'DISCLAIMER'</span><span class="p">)</span> <span class="o"><<</span> <span class="n">file</span><span class="p">(</span><span class="s1">'NOTICE'</span><span class="p">)</span>
-</code></pre>
-</div>
-<p>If you have a <code>LICENSE</code> file, it’s already included in the <code>meta_inf</code> list of files.</p>
+</code></pre></div><p>If you have a <code>LICENSE</code> file, it’s already included in the <code>meta_inf</code> list of files.</p>
<p>Other than that, <code>package :jar</code> includes the contents of the compiler’s target directory and resources, which most often is exactly what you intend it to do. If you want to include other files in the <span class="caps">JAR</span>, instead or in addition, you can do so using the <code>include</code> and <code>exclude</code> methods. If you do not want the target directory included in your <span class="caps">JAR</span>, simply call the <code>clean</code> method on it:</p>
<div class="highlight"><pre><code class="ruby"><span class="n">package</span><span class="p">(</span><span class="ss">:jar</span><span class="p">)</span><span class="o">.</span><span class="n">clean</span><span class="o">.</span><span class="n">include</span><span class="p">(</span> <span class="n">only_these_files</span> <span class="p">)</span>
-</code></pre>
-</div>
-<h2 id="war">Packaging WARs</h2>
+</code></pre></div><h2 id="war">Packaging WARs</h2>
<p>Pretty much everything you know about JARs works the same way for WARs, so let’s just look at the differences.</p>
<p>Without much prompting, <code>package :war</code> picks the contents of the <code>src/main/webapp</code> directory and places it at the root of the <span class="caps">WAR</span>, copies the compiler target directory into the <code>WEB-INF/classes</code> path, and copies any compiled dependencies into the <code>WEB-INF/libs</code> paths.</p>
<p>Again, you can use the <code>include</code> and <code>exclude</code> methods to change the contents of the <span class="caps">WAR</span>. There are two convenience options you can use to make the more common changes. If you need to include a classes directory other than the default:</p>
<div class="highlight"><pre><code class="ruby"><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">:classes</span><span class="o">=></span><span class="n">_</span><span class="p">(</span><span class="s1">'target/additional'</span><span class="p">)</span>
-</code></pre>
-</div>
-<p>If you want to include a different set of libraries other than the default:</p>
+</code></pre></div><p>If you want to include a different set of libraries other than the default:</p>
<div class="highlight"><pre><code class="ruby"><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">=></span><span class="no">MYSQL_JDBC</span>
-</code></pre>
-</div>
-<p>Both options accept a single value or an array. The <code>:classes</code> option accepts the name of a directory containing class files, initially set to <code>compile.target</code> and <code>resources.target</code>. The <code>:libs</code> option accepts artifact specifications, file names and tasks, initially set to include everything in <code>compile.dependencies</code>.</p>
+</code></pre></div><p>Both options accept a single value or an array. The <code>:classes</code> option accepts the name of a directory containing class files, initially set to <code>compile.target</code> and <code>resources.target</code>. The <code>:libs</code> option accepts artifact specifications, file names and tasks, initially set to include everything in <code>compile.dependencies</code>.</p>
<p>As you can guess, the package task has two attributes called <code>classes</code> and <code>libs</code>; the <code>with</code> method merely sets their value. If you need more precise control over these arrays, you can always work with them directly, for example:</p>
<div class="highlight"><pre><code class="ruby"><span class="c1"># Add an artifact to the existing set:</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">libs</span> <span class="o">+=</span> <span class="n">artifacts</span><span class="p">(</span><span class="no">MYSQL_JDBC</span><span class="p">)</span>
@@ -230,16 +184,32 @@
<span class="c1"># List all the artifacts:</span>
<span class="nb">puts</span> <span class="s1">'Artifacts included in WAR package:'</span>
<span class="nb">puts</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">libs</span><span class="o">.</span><span class="n">map</span><span class="p">(</span><span class="o">&</span><span class="ss">:to_spec</span><span class="p">)</span>
-</code></pre>
-</div>
-<h2 id="aar">Packaging AARs</h2>
+</code></pre></div><h3 id="war_extra_assets">Compiling Assets</h3>
+<p>In modern web applications, it is common to use tools that compile and compress assets. i.e. <a href="http://coffeescript.org/">Coffeescript</a> is compiled into javascript and <a href="http://sass-lang.com/">Sass</a> compiles into <span class="caps">CSS</span>. Buildr provides support using a simple <code>assets</code> abstraction. Directory or file tasks can be added to the <code>assets.paths</code> configuration variable for a project and the contents will be included in the package.</p>
+<h4 id="coffeescript">Integrating CoffeeScript</h4>
+<div class="highlight"><pre><code class="ruby"><span class="n">target_dir</span> <span class="o">=</span> <span class="n">_</span><span class="p">(</span><span class="ss">:target</span><span class="p">,</span> <span class="ss">:generated</span><span class="p">,</span> <span class="s2">"coffee/main/webapp"</span><span class="p">)</span>
+<span class="n">source_dir</span> <span class="o">=</span> <span class="n">_</span><span class="p">(</span><span class="ss">:source</span><span class="p">,</span> <span class="ss">:main</span><span class="p">,</span> <span class="ss">:coffee</span><span class="p">)</span>
+
+<span class="n">assets</span><span class="o">.</span><span class="n">paths</span> <span class="o"><<</span> <span class="n">file</span><span class="p">(</span><span class="n">target_dir</span> <span class="o">=></span> <span class="o">[</span><span class="no">FileList</span><span class="o">[</span><span class="s2">"</span><span class="si">#{</span><span class="n">source_dir</span><span class="si">}</span><span class="s2">/**/*.coffee"</span><span class="o">]]</span><span class="p">)</span> <span class="k">do</span>
+ <span class="nb">puts</span> <span class="s2">"Compiling coffeescript"</span>
+ <span class="n">sh</span> <span class="s2">"coffee --bare --compile --output </span><span class="si">#{</span><span class="n">target_dir</span><span class="si">}</span><span class="s2"> </span><span class="si">#{</span><span class="n">source_dir</span><span class="si">}</span><span class="s2">"</span>
+ <span class="n">touch</span> <span class="n">target_dir</span>
+<span class="k">end</span>
+</code></pre></div><h4 id="sass">Integrating Sass</h4>
+<div class="highlight"><pre><code class="ruby"><span class="n">target_dir</span> <span class="o">=</span> <span class="n">_</span><span class="p">(</span><span class="ss">:target</span><span class="p">,</span> <span class="ss">:generated</span><span class="p">,</span> <span class="s2">"sass/main/webapp"</span><span class="p">)</span>
+<span class="n">source_dir</span> <span class="o">=</span> <span class="n">_</span><span class="p">(</span><span class="ss">:source</span><span class="p">,</span> <span class="ss">:main</span><span class="p">,</span> <span class="ss">:sass</span><span class="p">)</span>
+
+<span class="n">assets</span><span class="o">.</span><span class="n">paths</span> <span class="o"><<</span> <span class="n">file</span><span class="p">(</span><span class="n">target_dir</span> <span class="o">=></span> <span class="o">[</span><span class="no">FileList</span><span class="o">[</span><span class="s2">"</span><span class="si">#{</span><span class="n">source_dir</span><span class="si">}</span><span class="s2">/**/*.scss"</span><span class="o">]]</span><span class="p">)</span> <span class="k">do</span>
+ <span class="nb">puts</span> <span class="s2">"Compiling scss"</span>
+ <span class="n">sh</span> <span class="s2">"scss -q --update </span><span class="si">#{</span><span class="n">source_dir</span><span class="si">}</span><span class="s2">:</span><span class="si">#{</span><span class="n">target_dir</span><span class="si">}</span><span class="s2">"</span>
+ <span class="n">touch</span> <span class="n">target_dir</span>
+<span class="k">end</span>
+</code></pre></div><h2 id="aar">Packaging AARs</h2>
<p>Axis2 service archives are similar to JAR’s (compiled classes go into the root of the archive) but they can embed additional libraries under /lib and include <code>services.xml</code> and <span class="caps">WSDL</span> files.</p>
<div class="highlight"><pre><code class="ruby"><span class="n">package</span><span class="p">(</span><span class="ss">:aar</span><span class="p">)</span><span class="o">.</span><span class="n">with</span><span class="p">(</span><span class="ss">:libs</span><span class="o">=></span><span class="s1">'log4j:log4j:jar:1.1'</span><span class="p">)</span>
<span class="n">package</span><span class="p">(</span><span class="ss">:aar</span><span class="p">)</span><span class="o">.</span><span class="n">with</span><span class="p">(</span><span class="ss">:services_xml</span><span class="o">=></span><span class="n">_</span><span class="p">(</span><span class="s1">'target/services.xml'</span><span class="p">),</span>
<span class="ss">:wsdls</span><span class="o">=></span><span class="n">_</span><span class="p">(</span><span class="s1">'target/*.wsdl'</span><span class="p">))</span>
-</code></pre>
-</div>
-<p>The <code>libs</code> attribute is a list of .jar artifacts to be included in the archive under /lib. The default is no artifacts; compile dependencies are not included by default.</p>
+</code></pre></div><p>The <code>libs</code> attribute is a list of .jar artifacts to be included in the archive under /lib. The default is no artifacts; compile dependencies are not included by default.</p>
<p>The <code>services_xml</code> attribute points to an Axis2 services configuration file called <code>services.xml</code> that will be placed in the <code>META-INF</code> directory inside the archive. The default behavior is to point to the <code>services.xml</code> file in the project’s <code>src/main/axis2</code> directory. In the second example above we set it explicitly.</p>
<p>The <code>wsdls</code> attribute is a collection of file names or glob patterns for <span class="caps">WSDL</span> files that get included in the <code>META-INF</code> directory. In the second example we include <span class="caps">WSDL</span> files from the <code>target</code> directory, presumably created by an earlier build task. In addition, <span class="caps">AAR</span> packaging will include all files ending with <code>.wsdl</code> from the <code>src/main/axis2</code> directory.</p>
<p>If you already have <span class="caps">WSDL</span> files in the <code>src/main/axis2</code> directory but would like to perform some filtering, for example, to set the <span class="caps">HTTP</span> port number, consider ignoring the originals and including only the filtered files, for example:</p>
@@ -251,9 +221,7 @@
<span class="n">package</span><span class="p">(</span><span class="ss">:aar</span><span class="p">)</span><span class="o">.</span><span class="n">wsdls</span><span class="o">.</span><span class="n">clear</span>
<span class="n">package</span><span class="p">(</span><span class="ss">:aar</span><span class="p">)</span><span class="o">.</span><span class="n">with</span><span class="p">(</span><span class="ss">:services_xml</span><span class="o">=></span><span class="n">_</span><span class="p">(</span><span class="s1">'target/services.xml'</span><span class="p">),</span>
<span class="ss">:wsdls</span><span class="o">=></span><span class="n">_</span><span class="p">(</span><span class="s1">'target/==*==.wsdl'</span><span class="p">))</span>
-</code></pre>
-</div>
-<h2 id="ear">Packaging EARs</h2>
+</code></pre></div><h2 id="ear">Packaging EARs</h2>
<p><span class="caps">EAR</span> packaging is slightly different from <span class="caps">JAR</span>/<span class="caps">WAR</span> packaging. It’s main purpose is to package components together, and so it includes special methods for handling component inclusion that take care to update application.xml and the component’s classpath.</p>
<p><span class="caps">EAR</span> packages support four component types:</p>
<table>
@@ -281,9 +249,7 @@
<p>This example shows two ways for adding components built by other projects:</p>
<div class="highlight"><pre><code class="ruby"><span class="n">package</span><span class="p">(</span><span class="ss">:ear</span><span class="p">)</span> <span class="o"><<</span> <span class="n">project</span><span class="p">(</span><span class="s1">'coolWebService'</span><span class="p">)</span><span class="o">.</span><span class="n">package</span><span class="p">(</span><span class="ss">:war</span><span class="p">)</span>
<span class="n">package</span><span class="p">(</span><span class="ss">:ear</span><span class="p">)</span><span class="o">.</span><span class="n">add</span> <span class="n">project</span><span class="p">(</span><span class="s1">'commonLib'</span><span class="p">)</span> <span class="c1"># By default, the JAR package</span>
-</code></pre>
-</div>
-<p>Adding a <span class="caps">WAR</span> package assumes it’s a <span class="caps">WAR</span> component and treats it as such, but <span class="caps">JAR</span> packages can be any of three component types, so by default they are all treated as shared libraries. If you want to add an <span class="caps">EJB</span> or Application Client component, you need to say so explicitly, either passing <code>:type=>package</code>, or by passing the component type in the <code>:type</code> option.</p>
+</code></pre></div><p>Adding a <span class="caps">WAR</span> package assumes it’s a <span class="caps">WAR</span> component and treats it as such, but <span class="caps">JAR</span> packages can be any of three component types, so by default they are all treated as shared libraries. If you want to add an <span class="caps">EJB</span> or Application Client component, you need to say so explicitly, either passing <code>:type=>package</code>, or by passing the component type in the <code>:type</code> option.</p>
<p>Here are three examples:</p>
<div class="highlight"><pre><code class="ruby"><span class="c1"># Assumed to be a shared library.</span>
<span class="n">package</span><span class="p">(</span><span class="ss">:ear</span><span class="p">)</span><span class="o">.</span><span class="n">add</span> <span class="s1">'org.springframework:spring:jar:2.6'</span>
@@ -291,18 +257,14 @@
<span class="n">package</span><span class="p">(</span><span class="ss">:ear</span><span class="p">)</span><span class="o">.</span><span class="n">add</span> <span class="ss">:ejb</span><span class="o">=></span><span class="n">project</span><span class="p">(</span><span class="s1">'beanery'</span><span class="p">)</span>
<span class="c1"># Adding component with specific package type.</span>
<span class="n">package</span><span class="p">(</span><span class="ss">:ear</span><span class="p">)</span><span class="o">.</span><span class="n">add</span> <span class="n">project</span><span class="p">(</span><span class="s1">'client'</span><span class="p">),</span> <span class="ss">:type</span><span class="o">=></span><span class="ss">:jar</span>
-</code></pre>
-</div>
-<p>By default, <span class="caps">WAR</span> components are all added under the <code>/war</code> path, and likewise, <span class="caps">EJB</span> components are added under the <code>/ejb</code> path, shared libraries under <code>/lib</code> and Application Client components under <code>/jar</code>.</p>
+</code></pre></div><p>By default, <span class="caps">WAR</span> components are all added under the <code>/war</code> path, and likewise, <span class="caps">EJB</span> components are added under the <code>/ejb</code> path, shared libraries under <code>/lib</code> and Application Client components under <code>/jar</code>.</p>
<p>If you want to place components in different locations you can do so using the <code>:path</code> option, or by specifying a different mapping between component types and their destination directory. The following two examples are equivalent:</p>
<div class="highlight"><pre><code class="ruby"><span class="c1"># Specify once per component.</span>
<span class="n">package</span><span class="p">(</span><span class="ss">:ear</span><span class="p">)</span><span class="o">.</span><span class="n">add</span> <span class="n">project</span><span class="p">(</span><span class="s1">'coolWebService'</span><span class="p">)</span><span class="o">.</span><span class="n">package</span><span class="p">(</span><span class="ss">:war</span><span class="p">),</span> <span class="ss">:path</span><span class="o">=></span><span class="s1">'coolServices'</span>
<span class="c1"># Configure once and apply to all added components.</span>
<span class="n">package</span><span class="p">(</span><span class="ss">:ear</span><span class="p">)</span><span class="o">.</span><span class="n">dirs</span><span class="o">[</span><span class="ss">:war</span><span class="o">]</span> <span class="o">=</span> <span class="s1">'coolServices'</span>
<span class="n">package</span><span class="p">(</span><span class="ss">:ear</span><span class="p">)</span> <span class="o"><<</span> <span class="n">project</span><span class="p">(</span><span class="s1">'coolWebService'</span><span class="p">)</span><span class="o">.</span><span class="n">package</span><span class="p">(</span><span class="ss">:war</span><span class="p">)</span>
-</code></pre>
-</div>
-<p><span class="caps">EAR</span> packages include an <code>application.xml</code> file in the <code>META-INF</code> directory that describes the application and its components. This file is created for you during packaging, by referencing all the components added to the <span class="caps">EAR</span>. There are a couple of things you will typically want to change.</p>
+</code></pre></div><p><span class="caps">EAR</span> packages include an <code>application.xml</code> file in the <code>META-INF</code> directory that describes the application and its components. This file is created for you during packaging, by referencing all the components added to the <span class="caps">EAR</span>. There are a couple of things you will typically want to change.</p>
<ul>
<li><strong>display-name</strong> — The application’s display name defaults to the project’s identifier. You can change that by setting the <code>display_name</code> attribute.</li>
</ul>
@@ -316,22 +278,18 @@
<div class="highlight"><pre><code class="ruby"><span class="n">package</span><span class="p">(</span><span class="ss">:ear</span><span class="p">)</span><span class="o">.</span><span class="n">display_name</span> <span class="o">=</span> <span class="s1">'MyCoolWebService'</span>
<span class="n">package</span><span class="p">(</span><span class="ss">:ear</span><span class="p">)</span><span class="o">.</span><span class="n">description</span> <span class="o">=</span> <span class="s1">'MyCoolWebService: Making coolness kool again'</span>
<span class="n">package</span><span class="p">(</span><span class="ss">:ear</span><span class="p">)</span><span class="o">.</span><span class="n">add</span> <span class="n">project</span><span class="p">(</span><span class="s1">'coolWebService'</span><span class="p">)</span><span class="o">.</span><span class="n">package</span><span class="p">(</span><span class="ss">:war</span><span class="p">),</span> <span class="ss">:context_root</span><span class="o">=></span><span class="s1">'coolness'</span>
-</code></pre>
-</div>
-<p>If you need to disable the context root (e.g. for Portlets), set <code>context_root</code> to <code>false</code>.</p>
+</code></pre></div><p>If you need to disable the context root (e.g. for Portlets), set <code>context_root</code> to <code>false</code>.</p>
<p>It is also possible to add <code>security-role</code> tags to the <code>application.xml</code> file by appending a hash with <code>:id</code>, <code>:description</code> and <code>:name</code> to the <code>security_role</code> array, like so:</p>
<div class="highlight"><pre><code class="ruby"><span class="n">package</span><span class="p">(</span><span class="ss">:ear</span><span class="p">)</span><span class="o">.</span><span class="n">security_roles</span> <span class="o"><<</span> <span class="p">{</span><span class="ss">:id</span><span class="o">=></span><span class="s1">'SecurityRole_123'</span><span class="p">,</span>
<span class="ss">:description</span><span class="o">=></span><span class="s1">'Read only user'</span><span class="p">,</span> <span class="ss">:name</span><span class="o">=></span><span class="s1">'coolUser'</span><span class="p">}</span>
<span class="n">package</span><span class="p">(</span><span class="ss">:ear</span><span class="p">)</span><span class="o">.</span><span class="n">security_roles</span> <span class="o"><<</span> <span class="p">{</span><span class="ss">:id</span><span class="o">=></span><span class="s1">'SecurityRole_456'</span><span class="p">,</span>
<span class="ss">:description</span><span class="o">=></span><span class="s1">'Super user'</span><span class="p">,</span> <span class="ss">:name</span><span class="o">=></span><span class="s1">'superCoolUser'</span><span class="p">}</span>
-</code></pre>
-</div>
-<h2 id="bundle">Packaging OSGi Bundles</h2>
+</code></pre></div><h2 id="bundle">Packaging OSGi Bundles</h2>
<p>OSGi bundles are jar files with additional metadata stored in the manifest. Buildr uses an external tool <a href="http://www.aqute.biz/Code/Bnd">Bnd</a> to create the package. Directives and properties can be explicitly passed to the build tool and buildr will provide reasonable defaults for properties that can be derived from the project model. Please see the bnd tool for documentation on the available properties.</p>
<p>The bundle packaging format is included as an addon so the build file must explicitly require the addon using using <code>require "buildr/bnd"</code> and must add a remote repository from which the bnd can be downloaded. A typical project that uses the bundle packaging addon may look something like;</p>
<div class="highlight"><pre><code class="ruby"><span class="nb">require</span> <span class="s2">"buildr/bnd"</span>
-<span class="n">repositories</span><span class="o">.</span><span class="n">remote</span> <span class="o"><<</span> <span class="no">Buildr</span><span class="o">::</span><span class="no">Bnd</span><span class="o">.</span><span class="n">remote_repository</span>
+<span class="n">repositories</span><span class="o">.</span><span class="n">remote</span> <span class="o"><<</span> <span class="ss">Buildr</span><span class="p">:</span><span class="ss">:Bnd</span><span class="o">.</span><span class="n">remote_repository</span>
<span class="c1"># uncomment the next version to override the version of bnd</span>
<span class="c1"># Buildr::Bnd.version = '0.0.384'</span>
@@ -343,9 +301,7 @@
<span class="k">end</span>
<span class="o">.</span><span class="n">.</span><span class="o">.</span>
<span class="k">end</span>
-</code></pre>
-</div>
-<p>The <code>[]</code> method on the bundle package is used to provide directives to the bnd tool that are not inherited by sub-projects while the standard ‘manifest’ setting is used to define properties that inherited by sub-projects.</p>
+</code></pre></div><p>The <code>[]</code> method on the bundle package is used to provide directives to the bnd tool that are not inherited by sub-projects while the standard ‘manifest’ setting is used to define properties that inherited by sub-projects.</p>
<h3>Defaults</h3>
<p>The addon sets the following bnd parameters;</p>
<ul>
@@ -377,9 +333,7 @@
<span class="o">.</span><span class="n">.</span><span class="o">.</span>
<span class="k">end</span>
<span class="k">end</span>
-</code></pre>
-</div>
-<h4>classpath</h4>
+</code></pre></div><h4>classpath</h4>
<p>The user can specify the complete classpath using the ‘classpath’ method. The classpath should be an array of elements. If the element is a task, artifact, artifact namespace etc. then it will be resolved prior to invoking bnd.</p>
<div class="highlight"><pre><code class="ruby"><span class="o">.</span><span class="n">.</span><span class="o">.</span>
<span class="n">define</span> <span class="s1">'foo'</span> <span class="k">do</span>
@@ -398,9 +352,7 @@
<span class="o">.</span><span class="n">.</span><span class="o">.</span>
<span class="k">end</span>
<span class="k">end</span>
-</code></pre>
-</div>
-<h3>Examples</h3>
+</code></pre></div><h3>Examples</h3>
<h4>Including non-class resources in a bundle</h4>
<p>Bnd can be used to include non-class resources in a bundle. The following example includes all resources in ‘src/etc’ into the bundle.</p>
<div class="highlight"><pre><code class="ruby"><span class="n">define</span> <span class="s1">'myproject'</span> <span class="k">do</span>
@@ -410,9 +362,7 @@
<span class="o">.</span><span class="n">.</span><span class="o">.</span>
<span class="k">end</span>
<span class="k">end</span>
-</code></pre>
-</div>
-<h4>Using bnd to wrap an existing jar</h4>
+</code></pre></div><h4>Using bnd to wrap an existing jar</h4>
<p>Bnd can be used to wrap an existing jar as an OSGi bundle. The following example wraps the OpenMQ <span class="caps">JMS</span> provider as an OSGi bundle.</p>
<div class="highlight"><pre><code class="ruby"><span class="o">.</span><span class="n">.</span><span class="o">.</span>
<span class="c1"># Add repository for OpenMQ</span>
@@ -428,9 +378,7 @@
<span class="n">bnd</span><span class="o">.</span><span class="n">classpath_element</span> <span class="s1">'com.sun.messaging.mq:imq:jar:4.4'</span>
<span class="k">end</span>
<span class="k">end</span>
-</code></pre>
-</div>
-<h4>Create an OSGi bundle with an Activator</h4>
+</code></pre></div><h4>Create an OSGi bundle with an Activator</h4>
<p>The following example presents a basic buildfile for building an OSGi bundle with an activator.</p>
<div class="highlight"><pre><code class="ruby"><span class="o">.</span><span class="n">.</span><span class="o">.</span>
<span class="c1"># repository for OSGi core bundle</span>
@@ -446,9 +394,7 @@
<span class="n">bnd</span><span class="o">[</span><span class="s1">'Bundle-Activator'</span><span class="o">]</span> <span class="o">=</span> <span class="s2">"org.example.helloworld.Activator"</span>
<span class="k">end</span>
<span class="k">end</span>
-</code></pre>
-</div>
-<h4>Inheriting parameters for bnd tool</h4>
+</code></pre></div><h4>Inheriting parameters for bnd tool</h4>
<p>The following example shows how you can use ‘manifest’ to define a bnd parameter that is inherited by all child sub-projects. The “Bundle-License” defined in the top level project is passed to the bnd tool when generating both the ‘fe’ and ‘fi’ sub-projects but the ‘fo’ sub-project overrides this parameter with a local value.</p>
<div class="highlight"><pre><code class="ruby"><span class="o">.</span><span class="n">.</span><span class="o">.</span>
<span class="n">define</span> <span class="s1">'myproject'</span> <span class="k">do</span>
@@ -475,35 +421,23 @@
<span class="k">end</span>
<span class="k">end</span>
<span class="k">end</span>
-</code></pre>
-</div>
-<h2 id="tar">Packaging Tars and GZipped Tars</h2>
+</code></pre></div><h2 id="tar">Packaging Tars and GZipped Tars</h2>
<p>Everything you know about working with <span class="caps">ZIP</span> files translates to Tar files, the two tasks are identical in more respect, so here we’ll just go over the differences.</p>
<div class="highlight"><pre><code class="ruby"><span class="n">package</span><span class="p">(</span><span class="ss">:tar</span><span class="p">)</span><span class="o">.</span><span class="n">include</span> <span class="n">_</span><span class="p">(</span><span class="s1">'target/docs'</span><span class="p">),</span> <span class="s1">'README'</span>
<span class="n">package</span><span class="p">(</span><span class="ss">:tgz</span><span class="p">)</span><span class="o">.</span><span class="n">include</span> <span class="n">_</span><span class="p">(</span><span class="s1">'target/docs'</span><span class="p">),</span> <span class="s1">'README'</span>
-</code></pre>
-</div>
-<p>The first line creates a Tar archive with the extension <code>.tar</code>, the second creates a GZipped Tar archive with the extension <code>.tgz</code>.</p>
+</code></pre></div><p>The first line creates a Tar archive with the extension <code>.tar</code>, the second creates a GZipped Tar archive with the extension <code>.tgz</code>.</p>
<p>In addition to packaging that includes the archive in the list of installed/released files, you can use the method <code>tar</code> to create a <code>TarTask</code>. This task is similar to <code>ZipTask</code>, and introduces the <code>gzip</code> attribute, which you can use to tell it whether to create a regular file, or GZip it. By default the attribute it set to true (GZip) if the file name ends with either <code>.gz</code> or <code>.tgz</code>.</p>
<h2 id="install_upload">Installing and Uploading</h2>
<p>You can bring in the artifacts you need from remote repositories and install them in the local repositories. Other projects have the same expectation, that your packages be their artifacts.</p>
<p>So let’s create these packages and install them in the local repository where other projects can access them:</p>
<div class="highlight"><pre><code class="sh"><span class="nv">$ </span>buildr install
-</code></pre>
-</div>
-<p>If you changes your mind you can always:</p>
+</code></pre></div><p>If you changes your mind you can always:</p>
<div class="highlight"><pre><code class="sh"><span class="nv">$ </span>buildr uninstall
-</code></pre>
-</div>
-<p>That works between projects you build on the same machine. Now let’s share these artifacts with other developers through a remote repository:</p>
+</code></pre></div><p>That works between projects you build on the same machine. Now let’s share these artifacts with other developers through a remote repository:</p>
<div class="highlight"><pre><code class="sh"><span class="nv">$ </span>buildr upload
-</code></pre>
-</div>
-<p>Of course, you’ll need to tell Buildr about the release server:</p>
+</code></pre></div><p>Of course, you’ll need to tell Buildr about the release server:</p>
<div class="highlight"><pre><code class="ruby"><span class="n">repositories</span><span class="o">.</span><span class="n">release_to</span> <span class="o">=</span> <span class="s1">'sftp://john:secret@release/usr/share/repo'</span>
-</code></pre>
-</div>
-<p>This example uses the <span class="caps">SFTP</span> protocol. In addition, you can use the <span class="caps">HTTP</span> protocol — Buildr supports <span class="caps">HTTP</span> and <span class="caps">HTTPS</span>, Basic Authentication and uploads using <span class="caps">PUT</span> — or point to a directory on your file system.</p>
+</code></pre></div><p>This example uses the <span class="caps">SFTP</span> protocol. In addition, you can use the <span class="caps">HTTP</span> protocol — Buildr supports <span class="caps">HTTP</span> and <span class="caps">HTTPS</span>, Basic Authentication and uploads using <span class="caps">PUT</span> — or point to a directory on your file system.</p>
<p>The <span class="caps">URL</span> in this example contains the release server (“release”), path to repository (“user/share/repo”) and username/password for access. The way <span class="caps">SFTP</span> works, you specify the path on the release server, and give the user permissions to create directories and files inside the repository. The file system path is different from the path you use to download these artifacts through an <span class="caps">HTTP</span> server, and starts at the root, not the user’s home directory.</p>
<p>Of course, you’ll want to specify the release server <span class="caps">URL</span> in the Buildfile, but leave the username/password settings private in your local <code>buildr.rb</code> file. Let’s break up the release server settings:</p>
<div class="highlight"><pre><code class="ruby"><span class="c1"># build.rb, loaded first</span>
@@ -512,47 +446,33 @@
<span class="c1"># Buildfile, loaded next</span>
<span class="n">repositories</span><span class="o">.</span><span class="n">release_to</span><span class="o">[</span><span class="ss">:url</span><span class="o">]</span> <span class="o">=</span> <span class="s1">'sftp://release/usr/share/repo'</span>
-</code></pre>
-</div>
-<p>The <code>upload</code> task takes care of uploading all the packages created by your project, along with their associated <span class="caps">POM</span> files and MD5/SHA1 signatures (Buildr creates these for you).</p>
+</code></pre></div><p>The <code>upload</code> task takes care of uploading all the packages created by your project, along with their associated <span class="caps">POM</span> files and MD5/SHA1 signatures (Buildr creates these for you).</p>
<p>If you need to upload other files, you can always extend the <code>upload</code> task and use <code>repositories.release_to</code> in combination with <code>URI.upload</code>. You can also extend it to upload to different servers, for example, to publish the documentation and test coverage reports to your site:</p>
<div class="highlight"><pre><code class="ruby"><span class="c1"># We'll let some other task decide how to create 'docs'</span>
<span class="n">task</span> <span class="s1">'upload'</span><span class="o">=></span><span class="s1">'docs'</span> <span class="k">do</span>
<span class="n">uri</span> <span class="o">=</span> <span class="no">URI</span><span class="p">(</span><span class="s2">"sftp://</span><span class="si">#{</span><span class="n">username</span><span class="si">}</span><span class="s2">:</span><span class="si">#{</span><span class="n">password</span><span class="si">}</span><span class="s2">@var/www/docs"</span><span class="p">)</span>
<span class="n">uri</span><span class="o">.</span><span class="n">upload</span> <span class="n">file</span><span class="p">(</span><span class="s1">'docs'</span><span class="p">)</span>
<span class="k">end</span>
-</code></pre>
-</div>
-<h3 id="uploading-options">Uploading Options</h3>
+</code></pre></div><h3 id="uploading-options">Uploading Options</h3>
<p>For convenience, you can also pass <a href="http://net-ssh.github.com/ssh/v2/api/classes/Net/SSH.html#M000002">any option of Net::<span class="caps">SSH</span></a> when configuring the remote repository.</p>
<p>If you need to enforce to use password-only authentication for example, you can set this option:</p>
<div class="highlight"><pre><code class="ruby"><span class="c1"># Set password authentication only</span>
<span class="n">repositories</span><span class="o">.</span><span class="n">release_to</span><span class="o">[</span><span class="ss">:options</span><span class="o">]</span> <span class="o">=</span> <span class="p">{</span><span class="ss">:ssh_options</span><span class="o">=></span><span class="p">{</span><span class="ss">:auth_methods</span><span class="o">=></span> <span class="s1">'password'</span><span class="p">}}</span>
-</code></pre>
-</div>
-<h2 id="source_javadoc">Packaging Sources and JavaDocs</h2>
+</code></pre></div><h2 id="source_javadoc">Packaging Sources and JavaDocs</h2>
<p>IDEs can take advantage of source packages to help you debug and trace through compiled code. We’ll start with a simple example:</p>
<div class="highlight"><pre><code class="ruby"><span class="n">package</span> <span class="ss">:sources</span>
-</code></pre>
-</div>
-<p>This one creates a <span class="caps">ZIP</span> package with the classifier “sources” that will contain all the source directories in that project, typically <code>src/main/java</code>, but also other sources generated from Apt, JavaCC, XMLBeans and friends.</p>
+</code></pre></div><p>This one creates a <span class="caps">ZIP</span> package with the classifier “sources” that will contain all the source directories in that project, typically <code>src/main/java</code>, but also other sources generated from Apt, JavaCC, XMLBeans and friends.</p>
<p>You can also generate a <span class="caps">ZIP</span> package with the classifier “javadoc” that contains the JavaDoc documentation for the project. It uses the same set of documentation files generated by the project’s <code>doc</code> task, so you can use it in combination with the <code>doc</code> method. For example:</p>
<div class="highlight"><pre><code class="ruby"><span class="n">package</span> <span class="ss">:javadoc</span>
<span class="n">doc</span> <span class="ss">:windowtitle</span><span class="o">=></span><span class="s1">'Buggy but Works'</span>
-</code></pre>
-</div>
-<p>By default Buildr picks the project’s description for the window title.</p>
+</code></pre></div><p>By default Buildr picks the project’s description for the window title.</p>
<p>You can also tell Buildr to automatically create sources and JavaDoc packages in all the sub-projects that have any source files to package or document. Just add either or both of these methods in the top-level project:</p>
<div class="highlight"><pre><code class="ruby"><span class="n">package_with_sources</span>
<span class="n">package_with_javadoc</span>
-</code></pre>
-</div>
-<p>You can also tell it to be selective using the <code>:only</code> and <code>:except</code> options.<br />
+</code></pre></div><p>You can also tell it to be selective using the <code>:only</code> and <code>:except</code> options.<br />
For example:</p>
<div class="highlight"><pre><code class="ruby"><span class="n">package_with_javadoc</span> <span class="ss">:except</span><span class="o">=></span><span class="s1">'la-web'</span>
-</code></pre>
-</div>
-<p>We packaged the code, but will it actually work? Let’s see <a href="testing.html">what the tests say</a>.</p>
+</code></pre></div><p>We packaged the code, but will it actually work? Let’s see <a href="testing.html">what the tests say</a>.</p>
</div>
<div id='footer'>Copyright © 2007-2010 The Apache Software Foundation</div>
</div>
Modified: buildr/site/projects.html
URL: http://svn.apache.org/viewvc/buildr/site/projects.html?rev=1529576&r1=1529575&r2=1529576&view=diff
==============================================================================
--- buildr/site/projects.html (original)
+++ buildr/site/projects.html Sun Oct 6 07:17:05 2013
@@ -87,7 +87,7 @@
<p>The remainder of this guide deals with what it takes to build a project. But first, let’s pick up a sample project to work with. We’ll call it <em>killer-app</em>:</p>
<div class="highlight"><pre><code class="ruby"><span class="nb">require</span> <span class="s2">"buildr/openjpa"</span>
-<span class="kp">include</span> <span class="no">Buildr</span><span class="o">::</span><span class="no">OpenJPA</span>
+<span class="kp">include</span> <span class="ss">Buildr</span><span class="p">:</span><span class="ss">:OpenJPA</span>
<span class="no">VERSION_NUMBER</span> <span class="o">=</span> <span class="s1">'1.0'</span>
@@ -130,9 +130,7 @@
<span class="n">package</span> <span class="ss">:javadoc</span>
<span class="k">end</span>
-</code></pre>
-</div>
-<p>A project definition requires four pieces of information: the project name, group identifier, version number and base directory. The project name … do we need to explain why its necessary? The group identifier and version number are used for packaging and deployment, we’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>
+</code></pre></div><p>A project definition requires four pieces of information: the project name, group identifier, version number and base directory. The project name … do we need to explain why its necessary? The group identifier and version number are used for packaging and deployment, we’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 <name> .. do</code> and <code>end</code>.</p>
<h2 id="dir_structure">The Directory Structure</h2>
<p>Buildr follows a convention we picked from years of working with Apache projects.</p>
@@ -166,9 +164,7 @@
<span class="nb">puts</span> <span class="n">project</span><span class="p">(</span><span class="s1">'killer-app'</span><span class="p">)</span><span class="o">.</span><span class="n">project</span><span class="p">(</span><span class="s1">'teh-api'</span><span class="p">)</span><span class="o">.</span><span class="n">inspect</span>
<span class="o">=></span> <span class="n">project</span><span class="p">(</span><span class="s2">"killer-app:teh-api"</span><span class="p">)</span>
-</code></pre>
-</div>
-<p>To see a list of all projects defined in your Buildfile run <code>buildr help:projects</code>.</p>
+</code></pre></div><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 “current project” is the one that uses the current working directory. So if you’re in the <code>la-web/src</code> directory looking at source files, <em>la-web</em> is the current project. For example:</p>
<div class="highlight"><pre><code class="sh"><span class="c"># build killer-app and all its sub-projects</span>
@@ -181,9 +177,7 @@
<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>
-</div>
-<p>You can use the project’s full name to invoke one of its tasks directly, and it doesn’t matter which directory you’re in. For example:</p>
+</code></pre></div><p>You can use the project’s full name to invoke one of its tasks directly, and it doesn’t matter which directory you’re in. For example:</p>
<div class="highlight"><pre><code class="sh"><span class="c"># build killer-app and all its sub-projects</span>
<span class="nv">$ </span>buildr killer-app:build
@@ -192,9 +186,7 @@
<span class="c"># package only la-web</span>
<span class="nv">$ </span>buildr killer-app:la-web:package
-</code></pre>
-</div>
-<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’s full name:</p>
+</code></pre></div><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’s full name:</p>
<div class="highlight"><pre><code class="text">clean # Clean files generated during a build
compile # Compile all projects
build # Build the project
@@ -204,9 +196,7 @@ javadoc # Create the Javadocs for this
package # Create packages
test # Run all test cases
uninstall # Remove previously installed packages
-</code></pre>
-</div>
-<p>To see a list of all the tasks provided by Buildr run <code>buildr help:tasks</code>.</p>
+</code></pre></div><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’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>
@@ -218,9 +208,7 @@ uninstall # Remove previously installed
<span class="o">=></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">'silly'</span><span class="p">)</span><span class="o">.</span><span class="n">group</span>
<span class="o">=></span> <span class="n">acme</span>
-</code></pre>
-</div>
-<p>Project properties are inherited. You can specify them once in the parent project, and they’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>
+</code></pre></div><p>Project properties are inherited. You can specify them once in the parent project, and they’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’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>
@@ -237,9 +225,7 @@ uninstall # Remove previously installed
<span class="c1"># Relative to the teh-impl project</span>
<span class="n">project</span><span class="p">(</span><span class="s1">'teh-impl'</span><span class="p">)</span><span class="o">.</span><span class="n">_</span><span class="p">(</span><span class="s1">'src/main/java'</span><span class="p">)</span>
-</code></pre>
-</div>
-<h2 id="defining">Defining The Project</h2>
+</code></pre></div><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’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’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’s an example to illustrate the point:</p>
<div class="highlight"><pre><code class="ruby"><span class="n">define</span> <span class="s1">'silly'</span> <span class="k">do</span>
@@ -249,9 +235,7 @@ uninstall # Remove previously installed
<span class="nb">puts</span> <span class="s1">'Building silly'</span>
<span class="k">end</span>
<span class="k">end</span>
-</code></pre>
-</div>
-<p>Each time you run Buildr, it will execute the project definition and print out “Running buildr”. We also extend the <code>build</code> task, and whenever we run it, it will print “Building silly”. 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>
+</code></pre></div><p>Each time you run Buildr, it will execute the project definition and print out “Running buildr”. We also extend the <code>build</code> task, and whenever we run it, it will print “Building silly”. 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’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’ 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’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’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>
@@ -264,9 +248,7 @@ uninstall # Remove previously installed
<span class="n">define</span> <span class="s1">'foo'</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>
-</div>
-<p>One last thing to remember. Actually three, but they all go hand in hand.</p>
+</code></pre></div><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’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’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 “do-this” inside the <em>teh-impl</em> project, the actual task name is “killer-app:teh-impl:do-this”. Likewise, the <code>compile</code> task is actually “killer-app:teh-impl:compile”.</p>