Added: dev/buildr/1.5.0/site/rdoc/Buildr/TestTask.html ============================================================================== --- dev/buildr/1.5.0/site/rdoc/Buildr/TestTask.html (added) +++ dev/buildr/1.5.0/site/rdoc/Buildr/TestTask.html Sat Sep 17 06:23:20 2016 @@ -0,0 +1,1375 @@ +<!DOCTYPE html> + +<html> +<head> +<meta charset="UTF-8"> + +<title>class Buildr::TestTask - buildr</title> + +<script type="text/javascript"> + var rdoc_rel_prefix = "../"; +</script> + +<script src="../js/jquery.js"></script> +<script src="../js/darkfish.js"></script> + +<link href="../css/fonts.css" rel="stylesheet"> +<link href="../css/rdoc.css" rel="stylesheet"> + + + +<body id="top" role="document" class="class"> +<nav role="navigation"> + <div id="project-navigation"> + <div id="home-section" role="region" title="Quick navigation" class="nav-section"> + <h2> + <a href="../index.html" rel="home">Home</a> + </h2> + + <div id="table-of-contents-navigation"> + <a href="../table_of_contents.html#pages">Pages</a> + <a href="../table_of_contents.html#classes">Classes</a> + <a href="../table_of_contents.html#methods">Methods</a> + </div> +</div> + + <div id="search-section" role="search" class="project-section initially-hidden"> + <form action="#" method="get" accept-charset="utf-8"> + <div id="search-field-wrapper"> + <input id="search-field" role="combobox" aria-label="Search" + aria-autocomplete="list" aria-controls="search-results" + type="text" name="search" placeholder="Search" spellcheck="false" + title="Type to search, Up and Down to navigate, Enter to load"> + </div> + + <ul id="search-results" aria-label="Search Results" + aria-busy="false" aria-expanded="false" + aria-atomic="false" class="initially-hidden"></ul> + </form> +</div> + + </div> + + + + <div id="class-metadata"> + + <div id="parent-class-section" class="nav-section"> + <h3>Parent</h3> + + + <p class="link">Rake::Task + +</div> + + + + <!-- Method Quickref --> +<div id="method-list-section" class="nav-section"> + <h3>Methods</h3> + + <ul class="link-list" role="directory"> + + <li ><a href="#method-c-clear">::clear</a> + + <li ><a href="#method-c-exclude">::exclude</a> + + <li ><a href="#method-c-include">::include</a> + + <li ><a href="#method-i-associate_with">#associate_with</a> + + <li ><a href="#method-i-classes">#classes</a> + + <li ><a href="#method-i-classpath">#classpath</a> + + <li ><a href="#method-i-classpath-3D">#classpath=</a> + + <li ><a href="#method-i-clear">#clear</a> + + <li ><a href="#method-i-compile">#compile</a> + + <li ><a href="#method-i-default_options">#default_options</a> + + <li ><a href="#method-i-exclude">#exclude</a> + + <li ><a href="#method-i-failures_to">#failures_to</a> + + <li ><a href="#method-i-framework">#framework</a> + + <li ><a href="#method-i-framework-3D">#framework=</a> + + <li ><a href="#method-i-include">#include</a> + + <li ><a href="#method-i-include-3F">#include?</a> + + <li ><a href="#method-i-last_failures">#last_failures</a> + + <li ><a href="#method-i-only_run">#only_run</a> + + <li ><a href="#method-i-only_run_failed">#only_run_failed</a> + + <li ><a href="#method-i-report_to">#report_to</a> + + <li ><a href="#method-i-resources">#resources</a> + + <li ><a href="#method-i-run_tests">#run_tests</a> + + <li ><a href="#method-i-setup">#setup</a> + + <li ><a href="#method-i-teardown">#teardown</a> + + <li ><a href="#method-i-using">#using</a> + + <li ><a href="#method-i-with">#with</a> + + </ul> +</div> + + </div> +</nav> + +<main role="main" aria-labelledby="class-Buildr::TestTask"> + <h1 id="class-Buildr::TestTask" class="class"> + class Buildr::TestTask + </h1> + + <section class="description"> + +<p>The test task controls the entire test lifecycle.</p> + +<p>You can use the test task in three ways. You can access and configure +specific test tasks, e.g. enhance the <a +href="TestTask.html#method-i-compile">compile</a> task, or run code during +<a href="TestTask.html#method-i-setup">setup</a>/#teardown.</p> + +<p>You can use convenient methods that handle the most common settings. For +example, add dependencies using <a +href="TestTask.html#method-i-with">with</a>, or include only specific tests +using <a href="TestTask.html#method-i-include">include</a>.</p> + +<p>You can also enhance this task directly. This task will first execute the +<a href="TestTask.html#method-i-compile">compile</a> task, followed by the +<a href="TestTask.html#method-i-setup">setup</a> task, run the unit tests, +any other enhancements, and end by executing <a +href="TestTask.html#method-i-teardown">teardown</a>.</p> + +<p>The test framework is determined based on the available test files, for +example, if the test cases are written in <a href="../Java.html">Java</a>, +then <a href="JUnit.html">JUnit</a> is selected as the test framework. You +can also select a specific test framework, for example, to use <a +href="TestNG.html">TestNG</a> instead of JUnit:</p> + +<pre class="ruby"><span class="ruby-identifier">test</span>.<span class="ruby-identifier">using</span> :<span class="ruby-identifier">testng</span> +</pre> + + </section> + + + + + <section id="5Buntitled-5D" class="documentation-section"> + + + + + + + + <section class="attribute-method-details" class="method-section"> + <header> + <h3>Attributes</h3> + </header> + + + <div id="attribute-i-dependencies" class="method-detail"> + <div class="method-heading attribute-method-heading"> + <span class="method-name">dependencies</span><span + class="attribute-access-type">[RW]</span> + </div> + + <div class="method-description"> + + <p>The dependencies used for running the tests. Includes the compiled files +(compile.target) and their dependencies. Will also include anything you +pass to <a href="TestTask.html#method-i-with">with</a>, shared between the +testing compile and run dependencies.</p> + + </div> + </div> + + <div id="attribute-i-failed_tests" class="method-detail"> + <div class="method-heading attribute-method-heading"> + <span class="method-name">failed_tests</span><span + class="attribute-access-type">[R]</span> + </div> + + <div class="method-description"> + + <p>After running the task, returns all the tests that failed, empty array if +all tests passed.</p> + + </div> + </div> + + <div id="attribute-i-forced_need" class="method-detail"> + <div class="method-heading attribute-method-heading"> + <span class="method-name">forced_need</span><span + class="attribute-access-type">[RW]</span> + </div> + + <div class="method-description"> + + <p>Whether the tests are forced</p> + + </div> + </div> + + <div id="attribute-i-options" class="method-detail"> + <div class="method-heading attribute-method-heading"> + <span class="method-name">options</span><span + class="attribute-access-type">[R]</span> + </div> + + <div class="method-description"> + + <p>Returns various test options.</p> + + </div> + </div> + + <div id="attribute-i-passed_tests" class="method-detail"> + <div class="method-heading attribute-method-heading"> + <span class="method-name">passed_tests</span><span + class="attribute-access-type">[R]</span> + </div> + + <div class="method-description"> + + <p>After running the task, returns all the tests that passed, empty array if +no tests passed.</p> + + </div> + </div> + + <div id="attribute-i-project" class="method-detail"> + <div class="method-heading attribute-method-heading"> + <span class="method-name">project</span><span + class="attribute-access-type">[R]</span> + </div> + + <div class="method-description"> + + <p>The project this task belongs to.</p> + + </div> + </div> + + <div id="attribute-i-tests" class="method-detail"> + <div class="method-heading attribute-method-heading"> + <span class="method-name">tests</span><span + class="attribute-access-type">[R]</span> + </div> + + <div class="method-description"> + + <p>After running the task, returns all tests selected to run, based on +availability and include/exclude pattern.</p> + + </div> + </div> + + </section> + + + + <section id="public-class-5Buntitled-5D-method-details" class="method-section"> + <header> + <h3>Public Class Methods</h3> + </header> + + + <div id="method-c-clear" class="method-detail "> + + <div class="method-heading"> + <span class="method-name">clear</span><span + class="method-args">()</span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + + <div class="method-description"> + + <p>Used by the test/integration rule to clear all previously included/excluded +tests.</p> + + + + + <div class="method-source-code" id="clear-source"> + <pre><span class="ruby-comment"># File lib/buildr/core/test.rb, line 187</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">clear</span>() + <span class="ruby-constant">Project</span>.<span class="ruby-identifier">projects</span>.<span class="ruby-identifier">each</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">project</span><span class="ruby-operator">|</span> + <span class="ruby-identifier">project</span>.<span class="ruby-identifier">test</span>.<span class="ruby-identifier">send</span> <span class="ruby-value">:clear</span> + <span class="ruby-keyword">end</span> +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + <div id="method-c-exclude" class="method-detail "> + + <div class="method-heading"> + <span class="method-name">exclude</span><span + class="method-args">(excludes)</span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + + <div class="method-description"> + + <p>Used by the test/integration to exclude specific tests</p> + + + + + <div class="method-source-code" id="exclude-source"> + <pre><span class="ruby-comment"># File lib/buildr/core/test.rb, line 203</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">exclude</span>(<span class="ruby-identifier">excludes</span>) + <span class="ruby-identifier">excludes</span> = <span class="ruby-identifier">wildcardify</span>(<span class="ruby-constant">Array</span>(<span class="ruby-identifier">excludes</span>)) + <span class="ruby-constant">Project</span>.<span class="ruby-identifier">projects</span>.<span class="ruby-identifier">each</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">project</span><span class="ruby-operator">|</span> + <span class="ruby-identifier">project</span>.<span class="ruby-identifier">test</span>.<span class="ruby-identifier">send</span> <span class="ruby-value">:exclude</span>, <span class="ruby-operator">*</span><span class="ruby-identifier">excludes</span> <span class="ruby-keyword">if</span> <span class="ruby-identifier">excludes</span>.<span class="ruby-identifier">size</span> <span class="ruby-operator">></span> <span class="ruby-value">0</span> + <span class="ruby-identifier">project</span>.<span class="ruby-identifier">test</span>.<span class="ruby-identifier">send</span> <span class="ruby-value">:forced_need=</span>, <span class="ruby-keyword">true</span> + <span class="ruby-keyword">end</span> +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + <div id="method-c-include" class="method-detail "> + + <div class="method-heading"> + <span class="method-name">include</span><span + class="method-args">(includes)</span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + + <div class="method-description"> + + <p>Used by the test/integration to include specific tests</p> + + + + + <div class="method-source-code" id="include-source"> + <pre><span class="ruby-comment"># File lib/buildr/core/test.rb, line 194</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">include</span>(<span class="ruby-identifier">includes</span>) + <span class="ruby-identifier">includes</span> = <span class="ruby-identifier">wildcardify</span>(<span class="ruby-constant">Array</span>(<span class="ruby-identifier">includes</span>)) + <span class="ruby-constant">Project</span>.<span class="ruby-identifier">projects</span>.<span class="ruby-identifier">each</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">project</span><span class="ruby-operator">|</span> + <span class="ruby-identifier">project</span>.<span class="ruby-identifier">test</span>.<span class="ruby-identifier">send</span> <span class="ruby-value">:include</span>, <span class="ruby-operator">*</span><span class="ruby-identifier">includes</span> <span class="ruby-keyword">if</span> <span class="ruby-identifier">includes</span>.<span class="ruby-identifier">size</span> <span class="ruby-operator">></span> <span class="ruby-value">0</span> + <span class="ruby-identifier">project</span>.<span class="ruby-identifier">test</span>.<span class="ruby-identifier">send</span> <span class="ruby-value">:forced_need=</span>, <span class="ruby-keyword">true</span> + <span class="ruby-keyword">end</span> +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + </section> + + <section id="public-instance-5Buntitled-5D-method-details" class="method-section"> + <header> + <h3>Public Instance Methods</h3> + </header> + + + <div id="method-i-classes" class="method-detail "> + + <div class="method-heading"> + <span class="method-name">classes</span><span + class="method-args">()</span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + + <div class="method-description"> + + <p><strong>Deprecated</strong>: Use tests instead.</p> + + + + + <div class="method-source-code" id="classes-source"> + <pre><span class="ruby-comment"># File lib/buildr/core/test.rb, line 406</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">classes</span> + <span class="ruby-constant">Buildr</span>.<span class="ruby-identifier">application</span>.<span class="ruby-identifier">deprecated</span> <span class="ruby-string">'Call tests instead of classes'</span> + <span class="ruby-identifier">tests</span> +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + <div id="method-i-classpath" class="method-detail "> + + <div class="method-heading"> + <span class="method-name">classpath</span><span + class="method-args">()</span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + + <div class="method-description"> + + <p><strong>Deprecated</strong>: Use dependencies instead.</p> + + + + + <div class="method-source-code" id="classpath-source"> + <pre><span class="ruby-comment"># File lib/buildr/core/test.rb, line 251</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">classpath</span> + <span class="ruby-constant">Buildr</span>.<span class="ruby-identifier">application</span>.<span class="ruby-identifier">deprecated</span> <span class="ruby-string">'Use dependencies instead.'</span> + <span class="ruby-ivar">@dependencies</span> +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + <div id="method-i-classpath-3D" class="method-detail "> + + <div class="method-heading"> + <span class="method-name">classpath=</span><span + class="method-args">(artifacts)</span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + + <div class="method-description"> + + <p><strong>Deprecated</strong>: Use dependencies= instead.</p> + + + + + <div class="method-source-code" id="classpath-3D-source"> + <pre><span class="ruby-comment"># File lib/buildr/core/test.rb, line 257</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">classpath=</span>(<span class="ruby-identifier">artifacts</span>) + <span class="ruby-constant">Buildr</span>.<span class="ruby-identifier">application</span>.<span class="ruby-identifier">deprecated</span> <span class="ruby-string">'Use dependencies= instead.'</span> + <span class="ruby-ivar">@dependencies</span> = <span class="ruby-identifier">artifacts</span> +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + <div id="method-i-clear" class="method-detail "> + + <div class="method-heading"> + <span class="method-name">clear</span><span + class="method-args">()</span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + + <div class="method-description"> + + <p>Clear all test includes and excludes and returns self</p> + + + + + <div class="method-source-code" id="clear-source"> + <pre><span class="ruby-comment"># File lib/buildr/core/test.rb, line 399</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">clear</span> + <span class="ruby-ivar">@include</span> = [] + <span class="ruby-ivar">@exclude</span> = [] + <span class="ruby-keyword">self</span> +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + <div id="method-i-compile" class="method-detail "> + + + <div class="method-heading"> + <span class="method-callseq"> + compile(*sources) → CompileTask + </span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + <div class="method-heading"> + <span class="method-callseq"> + compile(*sources) { |task| .. } → CompileTask + </span> + + </div> + + + + <div class="method-description"> + + <p>The compile task is similar to the Project's compile task. However, it +compiles all files found in the src/test/{source} directory into the +target/test/{code} directory. This task is executed by the test task before +running any tests.</p> + +<p>Once the project definition is complete, all dependencies from the regular +compile task are copied over, so you only need to specify dependencies +specific to your tests. You can do so by calling <a +href="TestTask.html#method-i-with">with</a> on the test task. The +dependencies used here are also copied over to the junit task.</p> + + + + + <div class="method-source-code" id="compile-source"> + <pre><span class="ruby-comment"># File lib/buildr/core/test.rb, line 289</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">compile</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">sources</span>, <span class="ruby-operator">&</span><span class="ruby-identifier">block</span>) + <span class="ruby-ivar">@project</span>.<span class="ruby-identifier">task</span>(<span class="ruby-string">'test:compile'</span>).<span class="ruby-identifier">from</span>(<span class="ruby-identifier">sources</span>).<span class="ruby-identifier">enhance</span> <span class="ruby-operator">&</span><span class="ruby-identifier">block</span> +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + <div id="method-i-default_options" class="method-detail "> + + <div class="method-heading"> + <span class="method-name">default_options</span><span + class="method-args">()</span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + + <div class="method-description"> + + <p>Default options already set on each test task.</p> + + + + + <div class="method-source-code" id="default_options-source"> + <pre><span class="ruby-comment"># File lib/buildr/core/test.rb, line 219</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">default_options</span> + { <span class="ruby-value">:fail_on_failure=</span><span class="ruby-operator">></span><span class="ruby-keyword">true</span>, <span class="ruby-value">:fork=</span><span class="ruby-operator">></span><span class="ruby-value">:once</span>, <span class="ruby-value">:properties=</span><span class="ruby-operator">></span>{}, <span class="ruby-value">:environment=</span><span class="ruby-operator">></span>{} } +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + <div id="method-i-exclude" class="method-detail "> + + + <div class="method-heading"> + <span class="method-callseq"> + exclude(*names) → self + </span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + + + <div class="method-description"> + + <p>Exclude the specified tests. This method accepts multiple arguments and +returns self. See <a href="TestTask.html#method-i-include">include</a> for +the type of arguments you can use.</p> + + + + + <div class="method-source-code" id="exclude-source"> + <pre><span class="ruby-comment"># File lib/buildr/core/test.rb, line 393</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">exclude</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">names</span>) + <span class="ruby-ivar">@exclude</span> <span class="ruby-operator">+=</span> <span class="ruby-identifier">names</span> + <span class="ruby-keyword">self</span> +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + <div id="method-i-failures_to" class="method-detail "> + + + <div class="method-heading"> + <span class="method-callseq"> + failures_to → file + </span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + + + <div class="method-description"> + + <p>We record the list of failed tests for the current framework in this file.</p> + + + + + <div class="method-source-code" id="failures_to-source"> + <pre><span class="ruby-comment"># File lib/buildr/core/test.rb, line 451</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">failures_to</span> + <span class="ruby-ivar">@failures_to</span> <span class="ruby-operator">||=</span> <span class="ruby-identifier">file</span>(<span class="ruby-ivar">@project</span>.<span class="ruby-identifier">path_to</span>(<span class="ruby-value">:target</span>, <span class="ruby-node">"#{framework}-failed"</span>)=<span class="ruby-operator">></span><span class="ruby-keyword">self</span>) +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + <div id="method-i-framework" class="method-detail "> + + + <div class="method-heading"> + <span class="method-callseq"> + framework → symbol + </span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + + + <div class="method-description"> + + <p>Returns the test framework, e.g. :junit, :testng.</p> + + + + + <div class="method-source-code" id="framework-source"> + <pre><span class="ruby-comment"># File lib/buildr/core/test.rb, line 422</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">framework</span> + <span class="ruby-keyword">unless</span> <span class="ruby-ivar">@framework</span> + <span class="ruby-comment"># Start with all frameworks that apply (e.g. JUnit and TestNG for Java),</span> + <span class="ruby-comment"># and pick the first (default) one, unless already specified in parent project.</span> + <span class="ruby-identifier">candidates</span> = <span class="ruby-constant">TestFramework</span>.<span class="ruby-identifier">frameworks</span>.<span class="ruby-identifier">select</span> { <span class="ruby-operator">|</span><span class="ruby-identifier">cls</span><span class="ruby-operator">|</span> <span class="ruby-identifier">cls</span>.<span class="ruby-identifier">applies_to?</span>(<span class="ruby-ivar">@project</span>) } + <span class="ruby-identifier">candidate</span> = <span class="ruby-ivar">@project</span>.<span class="ruby-identifier">parent</span> <span class="ruby-operator">&&</span> <span class="ruby-identifier">candidates</span>.<span class="ruby-identifier">detect</span> { <span class="ruby-operator">|</span><span class="ruby-identifier">framework</span><span class="ruby-operator">|</span> <span class="ruby-identifier">framework</span>.<span class="ruby-identifier">to_sym</span> <span class="ruby-operator">==</span> <span class="ruby-ivar">@project</span>.<span class="ruby-identifier">parent</span>.<span class="ruby-identifier">test</span>.<span class="ruby-identifier">framework</span> } <span class="ruby-operator">||</span> + <span class="ruby-identifier">candidates</span>.<span class="ruby-identifier">first</span> + <span class="ruby-keyword">self</span>.<span class="ruby-identifier">framework</span> = <span class="ruby-identifier">candidate</span> <span class="ruby-keyword">if</span> <span class="ruby-identifier">candidate</span> + <span class="ruby-keyword">end</span> + <span class="ruby-ivar">@framework</span> <span class="ruby-operator">&&</span> <span class="ruby-ivar">@framework</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">to_sym</span> +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + <div id="method-i-include" class="method-detail "> + + + <div class="method-heading"> + <span class="method-callseq"> + include(*names) → self + </span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + + + <div class="method-description"> + + <p>Include only the specified tests. Unless specified, the default is to +include all tests identified by the test framework. This method accepts +multiple arguments and returns self.</p> + +<p>Tests are specified by their full name, but you can use glob patterns to +select multiple tests, for example:</p> + +<pre class="ruby"><span class="ruby-identifier">test</span>.<span class="ruby-identifier">include</span> <span class="ruby-string">'com.example.FirstTest'</span> <span class="ruby-comment"># FirstTest only</span> +<span class="ruby-identifier">test</span>.<span class="ruby-identifier">include</span> <span class="ruby-string">'com.example.*'</span> <span class="ruby-comment"># All tests under com/example</span> +<span class="ruby-identifier">test</span>.<span class="ruby-identifier">include</span> <span class="ruby-string">'com.example.Module*'</span> <span class="ruby-comment"># All tests starting with Module</span> +<span class="ruby-identifier">test</span>.<span class="ruby-identifier">include</span> <span class="ruby-string">'*.{First,Second}Test'</span> <span class="ruby-comment"># FirstTest, SecondTest</span> +</pre> + + + + + <div class="method-source-code" id="include-source"> + <pre><span class="ruby-comment"># File lib/buildr/core/test.rb, line 383</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">include</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">names</span>) + <span class="ruby-ivar">@include</span> <span class="ruby-operator">+=</span> <span class="ruby-identifier">names</span> + <span class="ruby-keyword">self</span> +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + <div id="method-i-last_failures" class="method-detail "> + + + <div class="method-heading"> + <span class="method-callseq"> + last_failures → array + </span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + + + <div class="method-description"> + + <p>We read the last test failures if any and return them.</p> + + + + + <div class="method-source-code" id="last_failures-source"> + <pre><span class="ruby-comment"># File lib/buildr/core/test.rb, line 460</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">last_failures</span> + <span class="ruby-ivar">@last_failures</span> <span class="ruby-operator">||=</span> <span class="ruby-identifier">failures_to</span>.<span class="ruby-identifier">exist?</span> <span class="ruby-operator">?</span> <span class="ruby-constant">File</span>.<span class="ruby-identifier">read</span>(<span class="ruby-identifier">failures_to</span>.<span class="ruby-identifier">to_s</span>).<span class="ruby-identifier">split</span>(<span class="ruby-string">"\n"</span>) <span class="ruby-operator">:</span> [] +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + <div id="method-i-report_to" class="method-detail "> + + + <div class="method-heading"> + <span class="method-callseq"> + report_to → file + </span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + + + <div class="method-description"> + + <p><a href="Test.html">Test</a> frameworks that can produce reports, will +write them to this directory.</p> + +<p>This is framework dependent, so unless you use the default test framework, +call this method after setting the test framework.</p> + + + + + <div class="method-source-code" id="report_to-source"> + <pre><span class="ruby-comment"># File lib/buildr/core/test.rb, line 441</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">report_to</span> + <span class="ruby-ivar">@report_to</span> <span class="ruby-operator">||=</span> <span class="ruby-identifier">file</span>(<span class="ruby-ivar">@project</span>.<span class="ruby-identifier">path_to</span>(<span class="ruby-value">:reports</span>, <span class="ruby-identifier">framework</span>)=<span class="ruby-operator">></span><span class="ruby-keyword">self</span>) +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + <div id="method-i-resources" class="method-detail "> + + + <div class="method-heading"> + <span class="method-callseq"> + resources(*prereqs) → ResourcesTask + </span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + <div class="method-heading"> + <span class="method-callseq"> + resources(*prereqs) { |task| .. } → ResourcesTask + </span> + + </div> + + + + <div class="method-description"> + + <p>Executes by the <a href="TestTask.html#method-i-compile">compile</a> task +to copy resource files over. See <a +href="Compile.html#method-i-resources">Buildr::Compile#resources</a>.</p> + + + + + <div class="method-source-code" id="resources-source"> + <pre><span class="ruby-comment"># File lib/buildr/core/test.rb, line 298</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">resources</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">prereqs</span>, <span class="ruby-operator">&</span><span class="ruby-identifier">block</span>) + <span class="ruby-ivar">@project</span>.<span class="ruby-identifier">task</span>(<span class="ruby-string">'test:resources'</span>).<span class="ruby-identifier">enhance</span> <span class="ruby-identifier">prereqs</span>, <span class="ruby-operator">&</span><span class="ruby-identifier">block</span> +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + <div id="method-i-setup" class="method-detail "> + + + <div class="method-heading"> + <span class="method-callseq"> + setup(*prereqs) → task + </span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + <div class="method-heading"> + <span class="method-callseq"> + setup(*prereqs) { |task| .. } → task + </span> + + </div> + + + + <div class="method-description"> + + <p>Returns the setup task. The setup task is executed at the beginning of the +test task, after compiling the test files.</p> + + + + + <div class="method-source-code" id="setup-source"> + <pre><span class="ruby-comment"># File lib/buildr/core/test.rb, line 308</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">setup</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">prereqs</span>, <span class="ruby-operator">&</span><span class="ruby-identifier">block</span>) + <span class="ruby-ivar">@project</span>.<span class="ruby-identifier">task</span>(<span class="ruby-string">'test:setup'</span>).<span class="ruby-identifier">enhance</span> <span class="ruby-identifier">prereqs</span>, <span class="ruby-operator">&</span><span class="ruby-identifier">block</span> +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + <div id="method-i-teardown" class="method-detail "> + + + <div class="method-heading"> + <span class="method-callseq"> + teardown(*prereqs) → task + </span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + <div class="method-heading"> + <span class="method-callseq"> + teardown(*prereqs) { |task| .. } → task + </span> + + </div> + + + + <div class="method-description"> + + <p>Returns the teardown task. The teardown task is executed at the end of the +test task.</p> + + + + + <div class="method-source-code" id="teardown-source"> + <pre><span class="ruby-comment"># File lib/buildr/core/test.rb, line 317</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">teardown</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">prereqs</span>, <span class="ruby-operator">&</span><span class="ruby-identifier">block</span>) + <span class="ruby-ivar">@project</span>.<span class="ruby-identifier">task</span>(<span class="ruby-string">'test:teardown'</span>).<span class="ruby-identifier">enhance</span> <span class="ruby-identifier">prereqs</span>, <span class="ruby-operator">&</span><span class="ruby-identifier">block</span> +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + <div id="method-i-using" class="method-detail "> + + + <div class="method-heading"> + <span class="method-callseq"> + using(options) → self + </span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + + + <div class="method-description"> + + <p>Sets various test options from a hash and returns self. For example:</p> + +<pre class="ruby"><span class="ruby-identifier">test</span>.<span class="ruby-identifier">using</span> :<span class="ruby-identifier">fork=</span><span class="ruby-operator">></span>:<span class="ruby-identifier">each</span>, :<span class="ruby-identifier">properties=</span><span class="ruby-operator">></span>{ <span class="ruby-string">'url'</span>=<span class="ruby-operator">></span><span class="ruby-string">'http://localhost:8080'</span> } +</pre> + +<p>Can also be used to select the test framework, or to run these tests as +integration tests. For example:</p> + +<pre class="ruby"><span class="ruby-identifier">test</span>.<span class="ruby-identifier">using</span> :<span class="ruby-identifier">testng</span> +<span class="ruby-identifier">test</span>.<span class="ruby-identifier">using</span> :<span class="ruby-identifier">integration</span> +</pre> + +<p>The :fail_on_failure option specifies whether the task should fail if any +of the tests fail (default), or should report the failures but continue +running the build (when set to false).</p> + +<p>All other options depend on the capability of the test framework. These +options should be used the same way across all frameworks that support +them:</p> +<ul><li> +<p>:fork â Fork once for each project (:once, default), for each test in each</p> + +<pre>project (:each), or don't fork at all (false).</pre> +</li><li> +<p>:properties â Properties pass to the test, e.g. in <a +href="../Java.html">Java</a> as system properties.</p> +</li><li> +<p>:environment â Environment variables. This hash is made available in the</p> + +<pre>form of environment variables.</pre> +</li></ul> + + + + + <div class="method-source-code" id="using-source"> + <pre><span class="ruby-comment"># File lib/buildr/core/test.rb, line 357</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">using</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">args</span>) + <span class="ruby-identifier">args</span>.<span class="ruby-identifier">pop</span>.<span class="ruby-identifier">each</span> { <span class="ruby-operator">|</span><span class="ruby-identifier">key</span>, <span class="ruby-identifier">value</span><span class="ruby-operator">|</span> <span class="ruby-identifier">options</span>[<span class="ruby-identifier">key</span>.<span class="ruby-identifier">to_sym</span>] = <span class="ruby-identifier">value</span> } <span class="ruby-keyword">if</span> <span class="ruby-constant">Hash</span> <span class="ruby-operator">===</span> <span class="ruby-identifier">args</span>.<span class="ruby-identifier">last</span> + <span class="ruby-identifier">args</span>.<span class="ruby-identifier">each</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">name</span><span class="ruby-operator">|</span> + <span class="ruby-identifier">info</span> <span class="ruby-identifier">name</span> + <span class="ruby-keyword">if</span> <span class="ruby-constant">TestFramework</span>.<span class="ruby-identifier">has?</span>(<span class="ruby-identifier">name</span>) + <span class="ruby-keyword">self</span>.<span class="ruby-identifier">framework</span> = <span class="ruby-identifier">name</span> + <span class="ruby-keyword">elsif</span> <span class="ruby-identifier">name</span> <span class="ruby-operator">==</span> <span class="ruby-value">:integration</span> + <span class="ruby-identifier">options</span>[<span class="ruby-value">:integration</span>] = <span class="ruby-keyword">true</span> + <span class="ruby-keyword">end</span> + <span class="ruby-keyword">end</span> + <span class="ruby-keyword">self</span> +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + <div id="method-i-with" class="method-detail "> + + + <div class="method-heading"> + <span class="method-callseq"> + with(*specs) → self + </span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + + + <div class="method-description"> + + <p>Specify artifacts (specs, tasks, files, etc) to include in the dependencies +list when compiling and running tests.</p> + + + + + <div class="method-source-code" id="with-source"> + <pre><span class="ruby-comment"># File lib/buildr/core/test.rb, line 326</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">with</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">artifacts</span>) + <span class="ruby-ivar">@dependencies</span> <span class="ruby-operator">|=</span> <span class="ruby-constant">Buildr</span>.<span class="ruby-identifier">artifacts</span>(<span class="ruby-identifier">artifacts</span>.<span class="ruby-identifier">flatten</span>).<span class="ruby-identifier">uniq</span> + <span class="ruby-identifier">compile</span>.<span class="ruby-identifier">with</span> <span class="ruby-identifier">artifacts</span> + <span class="ruby-keyword">self</span> +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + </section> + + <section id="protected-instance-5Buntitled-5D-method-details" class="method-section"> + <header> + <h3>Protected Instance Methods</h3> + </header> + + + <div id="method-i-associate_with" class="method-detail "> + + <div class="method-heading"> + <span class="method-name">associate_with</span><span + class="method-args">(project)</span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + + <div class="method-description"> + + + + + + + <div class="method-source-code" id="associate_with-source"> + <pre><span class="ruby-comment"># File lib/buildr/core/test.rb, line 482</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">associate_with</span>(<span class="ruby-identifier">project</span>) + <span class="ruby-ivar">@project</span> = <span class="ruby-identifier">project</span> +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + <div id="method-i-framework-3D" class="method-detail "> + + <div class="method-heading"> + <span class="method-name">framework=</span><span + class="method-args">(name)</span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + + <div class="method-description"> + + + + + + + <div class="method-source-code" id="framework-3D-source"> + <pre><span class="ruby-comment"># File lib/buildr/core/test.rb, line 486</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">framework=</span>(<span class="ruby-identifier">name</span>) + <span class="ruby-identifier">cls</span> = <span class="ruby-constant">TestFramework</span>.<span class="ruby-identifier">select</span>(<span class="ruby-identifier">name</span>) <span class="ruby-keyword">or</span> <span class="ruby-identifier">raise</span> <span class="ruby-constant">ArgumentError</span>, <span class="ruby-node">"No #{name} test framework available. Did you install it?"</span> + <span class="ruby-comment">#cls.inherit_options.reject { |name| options.has_key?(name) }.</span> + <span class="ruby-comment"># each { |name| options[name] = @parent_task.options[name] } if @parent_task.respond_to?(:options)</span> + <span class="ruby-ivar">@framework</span> = <span class="ruby-identifier">cls</span>.<span class="ruby-identifier">new</span>(<span class="ruby-keyword">self</span>, <span class="ruby-identifier">options</span>) + <span class="ruby-comment"># Test framework dependency.</span> + <span class="ruby-identifier">with</span> <span class="ruby-ivar">@framework</span>.<span class="ruby-identifier">dependencies</span> +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + <div id="method-i-include-3F" class="method-detail "> + + + <div class="method-heading"> + <span class="method-callseq"> + include?(name) → boolean + </span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + + + <div class="method-description"> + + <p>Returns true if the specified test name matches the inclusion/exclusion +pattern. Used to determine which tests to execute.</p> + + + + + <div class="method-source-code" id="include-3F-source"> + <pre><span class="ruby-comment"># File lib/buildr/core/test.rb, line 500</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">include?</span>(<span class="ruby-identifier">name</span>) + ((<span class="ruby-ivar">@include</span>.<span class="ruby-identifier">empty?</span> <span class="ruby-operator">&&</span> <span class="ruby-operator">!</span><span class="ruby-ivar">@forced_need</span>)<span class="ruby-operator">||</span> <span class="ruby-ivar">@include</span>.<span class="ruby-identifier">any?</span> { <span class="ruby-operator">|</span><span class="ruby-identifier">pattern</span><span class="ruby-operator">|</span> <span class="ruby-constant">File</span>.<span class="ruby-identifier">fnmatch</span>(<span class="ruby-identifier">pattern</span>, <span class="ruby-identifier">name</span>) }) <span class="ruby-operator">&&</span> + <span class="ruby-operator">!</span><span class="ruby-ivar">@exclude</span>.<span class="ruby-identifier">any?</span> { <span class="ruby-operator">|</span><span class="ruby-identifier">pattern</span><span class="ruby-operator">|</span> <span class="ruby-constant">File</span>.<span class="ruby-identifier">fnmatch</span>(<span class="ruby-identifier">pattern</span>, <span class="ruby-identifier">name</span>) } +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + <div id="method-i-only_run" class="method-detail "> + + <div class="method-heading"> + <span class="method-name">only_run</span><span + class="method-args">(tests)</span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + + <div class="method-description"> + + <p>Limit running tests to specific list.</p> + + + + + <div class="method-source-code" id="only_run-source"> + <pre><span class="ruby-comment"># File lib/buildr/core/test.rb, line 541</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">only_run</span>(<span class="ruby-identifier">tests</span>) + <span class="ruby-ivar">@include</span> = <span class="ruby-constant">Array</span>(<span class="ruby-identifier">tests</span>) + <span class="ruby-ivar">@exclude</span>.<span class="ruby-identifier">clear</span> + <span class="ruby-ivar">@forced_need</span> = <span class="ruby-keyword">true</span> +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + <div id="method-i-only_run_failed" class="method-detail "> + + <div class="method-heading"> + <span class="method-name">only_run_failed</span><span + class="method-args">()</span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + + <div class="method-description"> + + <p>Limit running tests to those who failed the last time.</p> + + + + + <div class="method-source-code" id="only_run_failed-source"> + <pre><span class="ruby-comment"># File lib/buildr/core/test.rb, line 548</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">only_run_failed</span>() + <span class="ruby-ivar">@include</span> = <span class="ruby-constant">Array</span>(<span class="ruby-identifier">last_failures</span>) + <span class="ruby-ivar">@forced_need</span> = <span class="ruby-keyword">true</span> +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + <div id="method-i-run_tests" class="method-detail "> + + <div class="method-heading"> + <span class="method-name">run_tests</span><span + class="method-args">()</span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + + <div class="method-description"> + + <p>Runs the tests using the selected test framework.</p> + + + + + <div class="method-source-code" id="run_tests-source"> + <pre><span class="ruby-comment"># File lib/buildr/core/test.rb, line 506</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">run_tests</span> + <span class="ruby-identifier">dependencies</span> = (<span class="ruby-constant">Buildr</span>.<span class="ruby-identifier">artifacts</span>(<span class="ruby-keyword">self</span>.<span class="ruby-identifier">dependencies</span> <span class="ruby-operator">+</span> <span class="ruby-identifier">compile</span>.<span class="ruby-identifier">dependencies</span>) <span class="ruby-operator">+</span> [<span class="ruby-identifier">compile</span>.<span class="ruby-identifier">target</span>]).<span class="ruby-identifier">map</span>(<span class="ruby-operator">&</span><span class="ruby-value">:to_s</span>).<span class="ruby-identifier">uniq</span> + <span class="ruby-identifier">rm_rf</span> <span class="ruby-identifier">report_to</span>.<span class="ruby-identifier">to_s</span> + <span class="ruby-identifier">rm_rf</span> <span class="ruby-identifier">failures_to</span>.<span class="ruby-identifier">to_s</span> + <span class="ruby-ivar">@tests</span> = <span class="ruby-ivar">@framework</span>.<span class="ruby-identifier">tests</span>(<span class="ruby-identifier">dependencies</span>).<span class="ruby-identifier">select</span> { <span class="ruby-operator">|</span><span class="ruby-identifier">test</span><span class="ruby-operator">|</span> <span class="ruby-identifier">include?</span>(<span class="ruby-identifier">test</span>) }.<span class="ruby-identifier">sort</span> + <span class="ruby-keyword">if</span> <span class="ruby-ivar">@tests</span>.<span class="ruby-identifier">empty?</span> + <span class="ruby-ivar">@passed_tests</span>, <span class="ruby-ivar">@failed_tests</span> = [], [] + <span class="ruby-keyword">else</span> + <span class="ruby-identifier">info</span> <span class="ruby-node">"Running tests in #{@project.name}"</span> + <span class="ruby-keyword">begin</span> + <span class="ruby-comment"># set the baseDir system property if not set</span> + <span class="ruby-ivar">@framework</span>.<span class="ruby-identifier">options</span>[<span class="ruby-value">:properties</span>] = { <span class="ruby-string">'baseDir'</span> =<span class="ruby-operator">></span> <span class="ruby-identifier">compile</span>.<span class="ruby-identifier">target</span>.<span class="ruby-identifier">to_s</span> }.<span class="ruby-identifier">merge</span>(<span class="ruby-ivar">@framework</span>.<span class="ruby-identifier">options</span>[<span class="ruby-value">:properties</span>] <span class="ruby-operator">||</span> {}) + <span class="ruby-ivar">@passed_tests</span> = <span class="ruby-ivar">@framework</span>.<span class="ruby-identifier">run</span>(<span class="ruby-ivar">@tests</span>, <span class="ruby-identifier">dependencies</span>) + <span class="ruby-keyword">rescue</span> <span class="ruby-constant">Exception</span>=<span class="ruby-operator">></span><span class="ruby-identifier">ex</span> + <span class="ruby-identifier">error</span> <span class="ruby-node">"Test framework error: #{ex.message}"</span> + <span class="ruby-identifier">error</span> <span class="ruby-identifier">ex</span>.<span class="ruby-identifier">backtrace</span>.<span class="ruby-identifier">join</span>(<span class="ruby-string">"\n"</span>) <span class="ruby-keyword">if</span> <span class="ruby-identifier">trace?</span> + <span class="ruby-ivar">@passed_tests</span> = [] + <span class="ruby-keyword">end</span> + <span class="ruby-ivar">@failed_tests</span> = <span class="ruby-ivar">@tests</span> <span class="ruby-operator">-</span> <span class="ruby-ivar">@passed_tests</span> + <span class="ruby-keyword">unless</span> <span class="ruby-ivar">@failed_tests</span>.<span class="ruby-identifier">empty?</span> + <span class="ruby-constant">Buildr</span><span class="ruby-operator">::</span><span class="ruby-identifier">write</span>(<span class="ruby-identifier">failures_to</span>.<span class="ruby-identifier">to_s</span>, <span class="ruby-ivar">@failed_tests</span>.<span class="ruby-identifier">join</span>(<span class="ruby-string">"\n"</span>)) + <span class="ruby-identifier">error</span> <span class="ruby-node">"The following tests failed:\n#{@failed_tests.join("\n")}"</span> + <span class="ruby-identifier">fail</span> <span class="ruby-string">'Tests failed!'</span> + <span class="ruby-keyword">end</span> + <span class="ruby-keyword">end</span> + <span class="ruby-identifier">record_successful_run</span> <span class="ruby-keyword">unless</span> <span class="ruby-ivar">@forced_need</span> +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + </section> + + </section> +</main> + + +<footer id="validator-badges" role="contentinfo"> + <p><a href="http://validator.w3.org/check/referer">Validate</a> + <p>Generated by <a href="http://docs.seattlerb.org/rdoc/">RDoc</a> 4.2.2. + <p>Based on <a href="http://deveiate.org/projects/Darkfish-RDoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>. +</footer> +
Added: dev/buildr/1.5.0/site/rdoc/Buildr/Unzip.html ============================================================================== --- dev/buildr/1.5.0/site/rdoc/Buildr/Unzip.html (added) +++ dev/buildr/1.5.0/site/rdoc/Buildr/Unzip.html Sat Sep 17 06:23:20 2016 @@ -0,0 +1,645 @@ +<!DOCTYPE html> + +<html> +<head> +<meta charset="UTF-8"> + +<title>class Buildr::Unzip - buildr</title> + +<script type="text/javascript"> + var rdoc_rel_prefix = "../"; +</script> + +<script src="../js/jquery.js"></script> +<script src="../js/darkfish.js"></script> + +<link href="../css/fonts.css" rel="stylesheet"> +<link href="../css/rdoc.css" rel="stylesheet"> + + + +<body id="top" role="document" class="class"> +<nav role="navigation"> + <div id="project-navigation"> + <div id="home-section" role="region" title="Quick navigation" class="nav-section"> + <h2> + <a href="../index.html" rel="home">Home</a> + </h2> + + <div id="table-of-contents-navigation"> + <a href="../table_of_contents.html#pages">Pages</a> + <a href="../table_of_contents.html#classes">Classes</a> + <a href="../table_of_contents.html#methods">Methods</a> + </div> +</div> + + <div id="search-section" role="search" class="project-section initially-hidden"> + <form action="#" method="get" accept-charset="utf-8"> + <div id="search-field-wrapper"> + <input id="search-field" role="combobox" aria-label="Search" + aria-autocomplete="list" aria-controls="search-results" + type="text" name="search" placeholder="Search" spellcheck="false" + title="Type to search, Up and Down to navigate, Enter to load"> + </div> + + <ul id="search-results" aria-label="Search Results" + aria-busy="false" aria-expanded="false" + aria-atomic="false" class="initially-hidden"></ul> + </form> +</div> + + </div> + + + + <div id="class-metadata"> + + <div id="parent-class-section" class="nav-section"> + <h3>Parent</h3> + + + <p class="link"><a href="../Object.html">Object</a> + +</div> + + + + <!-- Method Quickref --> +<div id="method-list-section" class="nav-section"> + <h3>Methods</h3> + + <ul class="link-list" role="directory"> + + <li ><a href="#method-c-new">::new</a> + + <li ><a href="#method-i-add">#add</a> + + <li ><a href="#method-i-exclude">#exclude</a> + + <li ><a href="#method-i-extract">#extract</a> + + <li ><a href="#method-i-from_path">#from_path</a> + + <li ><a href="#method-i-include">#include</a> + + <li ><a href="#method-i-included-3F">#included?</a> + + <li ><a href="#method-i-path">#path</a> + + <li ><a href="#method-i-root">#root</a> + + <li ><a href="#method-i-to_s">#to_s</a> + + </ul> +</div> + + </div> +</nav> + +<main role="main" aria-labelledby="class-Buildr::Unzip"> + <h1 id="class-Buildr::Unzip" class="class"> + class Buildr::Unzip + </h1> + + <section class="description"> + +<p>An object for unzipping/untarring a file into a target directory. You can +tell it to include or exclude only specific files and directories, and also +to map files from particular paths inside the zip file into the target +directory. Once ready, call <a +href="Unzip.html#method-i-extract">extract</a>.</p> + +<p>Usually it is more convenient to create a file task for extracting the zip +file (see unzip) and pass this object as a prerequisite to other tasks.</p> + +<p>See Buildr#unzip.</p> + + </section> + + + + + <section id="5Buntitled-5D" class="documentation-section"> + + + + + + + + <section class="attribute-method-details" class="method-section"> + <header> + <h3>Attributes</h3> + </header> + + + <div id="attribute-i-target" class="method-detail"> + <div class="method-heading attribute-method-heading"> + <span class="method-name">target</span><span + class="attribute-access-type">[RW]</span> + </div> + + <div class="method-description"> + + <p>The target directory to extract to.</p> + + </div> + </div> + + <div id="attribute-i-zip_file" class="method-detail"> + <div class="method-heading attribute-method-heading"> + <span class="method-name">zip_file</span><span + class="attribute-access-type">[RW]</span> + </div> + + <div class="method-description"> + + <p>The zip file to extract.</p> + + </div> + </div> + + </section> + + + + <section id="public-class-5Buntitled-5D-method-details" class="method-section"> + <header> + <h3>Public Class Methods</h3> + </header> + + + <div id="method-c-new" class="method-detail "> + + <div class="method-heading"> + <span class="method-name">new</span><span + class="method-args">(args)</span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + + <div class="method-description"> + + <p>Initialize with hash argument of the form target=>zip_file.</p> + + + + + <div class="method-source-code" id="new-source"> + <pre><span class="ruby-comment"># File lib/buildr/packaging/ziptask.rb, line 126</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">initialize</span>(<span class="ruby-identifier">args</span>) + <span class="ruby-ivar">@target</span>, <span class="ruby-identifier">arg_names</span>, <span class="ruby-identifier">zip_file</span> = <span class="ruby-constant">Buildr</span>.<span class="ruby-identifier">application</span>.<span class="ruby-identifier">resolve_args</span>([<span class="ruby-identifier">args</span>]) + <span class="ruby-ivar">@zip_file</span> = <span class="ruby-identifier">zip_file</span>.<span class="ruby-identifier">first</span> + <span class="ruby-ivar">@paths</span> = {} +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + </section> + + <section id="public-instance-5Buntitled-5D-method-details" class="method-section"> + <header> + <h3>Public Instance Methods</h3> + </header> + + + <div id="method-i-add" class="method-detail method-alias"> + + <div class="method-heading"> + <span class="method-name">add</span><span + class="method-args">(*files)</span> + + </div> + + + <div class="method-description"> + + + + + + + </div> + + + + + <div class="aliases"> + Alias for: <a href="Unzip.html#method-i-include">include</a> + </div> + + </div> + + + <div id="method-i-exclude" class="method-detail "> + + + <div class="method-heading"> + <span class="method-callseq"> + exclude(*files) → self + </span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + + + <div class="method-description"> + + <p>Exclude all files that match the patterns and return self.</p> + +<p>Use exclude to unzip all files except those that match the pattern. You can +use <a href="Unzip.html#method-i-exclude">exclude</a> in combination with +<a href="Unzip.html#method-i-include">include</a>.</p> + + + + + <div class="method-source-code" id="exclude-source"> + <pre><span class="ruby-comment"># File lib/buildr/packaging/ziptask.rb, line 233</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">exclude</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">files</span>) + <span class="ruby-keyword">if</span> <span class="ruby-constant">Hash</span> <span class="ruby-operator">===</span> <span class="ruby-identifier">files</span>.<span class="ruby-identifier">last</span> + <span class="ruby-identifier">from_path</span>(<span class="ruby-identifier">files</span>.<span class="ruby-identifier">pop</span>[<span class="ruby-value">:path</span>]).<span class="ruby-identifier">exclude</span> <span class="ruby-operator">*</span><span class="ruby-identifier">files</span> + <span class="ruby-keyword">else</span> + <span class="ruby-identifier">from_path</span>(<span class="ruby-keyword">nil</span>).<span class="ruby-identifier">exclude</span> <span class="ruby-operator">*</span><span class="ruby-identifier">files</span> + <span class="ruby-keyword">end</span> + <span class="ruby-keyword">self</span> +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + <div id="method-i-extract" class="method-detail "> + + + <div class="method-heading"> + <span class="method-callseq"> + extract + </span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + + + <div class="method-description"> + + <p>Extract the zip/tgz file into the target directory.</p> + +<p>You can call this method directly. However, if you are using the unzip +method, it creates a file task for the target directory: use that task +instead as a prerequisite. For example:</p> + +<pre class="ruby"><span class="ruby-identifier">build</span> <span class="ruby-identifier">unzip</span>(<span class="ruby-identifier">dir</span>=<span class="ruby-operator">></span><span class="ruby-identifier">zip_file</span>) +</pre> + +<p>Or:</p> + +<pre class="ruby"><span class="ruby-identifier">unzip</span>(<span class="ruby-identifier">dir</span>=<span class="ruby-operator">></span><span class="ruby-identifier">zip_file</span>).<span class="ruby-identifier">target</span>.<span class="ruby-identifier">invoke</span> +</pre> + + + + + <div class="method-source-code" id="extract-source"> + <pre><span class="ruby-comment"># File lib/buildr/packaging/ziptask.rb, line 143</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">extract</span> + <span class="ruby-comment"># If no paths specified, then no include/exclude patterns</span> + <span class="ruby-comment"># specified. Nothing will happen unless we include all files.</span> + <span class="ruby-keyword">if</span> <span class="ruby-ivar">@paths</span>.<span class="ruby-identifier">empty?</span> + <span class="ruby-ivar">@paths</span>[<span class="ruby-keyword">nil</span>] = <span class="ruby-constant">FromPath</span>.<span class="ruby-identifier">new</span>(<span class="ruby-keyword">self</span>, <span class="ruby-keyword">nil</span>) + <span class="ruby-keyword">end</span> + + <span class="ruby-comment"># Otherwise, empty unzip creates target as a file when touching.</span> + <span class="ruby-identifier">mkpath</span> <span class="ruby-identifier">target</span>.<span class="ruby-identifier">to_s</span> + <span class="ruby-keyword">if</span> <span class="ruby-identifier">zip_file</span>.<span class="ruby-identifier">to_s</span>.<span class="ruby-identifier">match</span> <span class="ruby-regexp">/\.t?gz$/</span> + <span class="ruby-comment">#un-tar.gz</span> + <span class="ruby-constant">Zlib</span><span class="ruby-operator">::</span><span class="ruby-constant">GzipReader</span>.<span class="ruby-identifier">open</span>(<span class="ruby-identifier">zip_file</span>.<span class="ruby-identifier">to_s</span>) { <span class="ruby-operator">|</span><span class="ruby-identifier">tar</span><span class="ruby-operator">|</span> + <span class="ruby-constant">Archive</span><span class="ruby-operator">::</span><span class="ruby-constant">Tar</span><span class="ruby-operator">::</span><span class="ruby-constant">Minitar</span><span class="ruby-operator">::</span><span class="ruby-constant">Input</span>.<span class="ruby-identifier">open</span>(<span class="ruby-identifier">tar</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">inp</span><span class="ruby-operator">|</span> + <span class="ruby-identifier">inp</span>.<span class="ruby-identifier">each</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">tar_entry</span><span class="ruby-operator">|</span> + <span class="ruby-ivar">@paths</span>.<span class="ruby-identifier">each</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">path</span>, <span class="ruby-identifier">patterns</span><span class="ruby-operator">|</span> + <span class="ruby-identifier">patterns</span>.<span class="ruby-identifier">map</span>([<span class="ruby-identifier">tar_entry</span>]).<span class="ruby-identifier">each</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">dest</span>, <span class="ruby-identifier">entry</span><span class="ruby-operator">|</span> + <span class="ruby-keyword">next</span> <span class="ruby-keyword">if</span> <span class="ruby-identifier">entry</span>.<span class="ruby-identifier">directory?</span> + <span class="ruby-identifier">dest</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">expand_path</span>(<span class="ruby-identifier">dest</span>, <span class="ruby-identifier">target</span>.<span class="ruby-identifier">to_s</span>) + <span class="ruby-identifier">trace</span> <span class="ruby-node">"Extracting #{dest}"</span> + <span class="ruby-identifier">mkpath</span> <span class="ruby-constant">File</span>.<span class="ruby-identifier">dirname</span>(<span class="ruby-identifier">dest</span>) <span class="ruby-keyword">rescue</span> <span class="ruby-keyword">nil</span> + <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-identifier">dest</span>, <span class="ruby-string">'wb'</span>, <span class="ruby-identifier">entry</span>.<span class="ruby-identifier">mode</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">write</span> <span class="ruby-identifier">entry</span>.<span class="ruby-identifier">read</span>} + <span class="ruby-constant">File</span>.<span class="ruby-identifier">chmod</span>(<span class="ruby-identifier">entry</span>.<span class="ruby-identifier">mode</span>, <span class="ruby-identifier">dest</span>) + <span class="ruby-keyword">end</span> + <span class="ruby-keyword">end</span> + <span class="ruby-keyword">end</span> + <span class="ruby-keyword">end</span> + } + <span class="ruby-keyword">else</span> + <span class="ruby-constant">Zip</span><span class="ruby-operator">::</span><span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-identifier">zip_file</span>.<span class="ruby-identifier">to_s</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">zip</span><span class="ruby-operator">|</span> + <span class="ruby-identifier">entries</span> = <span class="ruby-identifier">zip</span>.<span class="ruby-identifier">collect</span> + <span class="ruby-ivar">@paths</span>.<span class="ruby-identifier">each</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">path</span>, <span class="ruby-identifier">patterns</span><span class="ruby-operator">|</span> + <span class="ruby-identifier">patterns</span>.<span class="ruby-identifier">map</span>(<span class="ruby-identifier">entries</span>).<span class="ruby-identifier">each</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">dest</span>, <span class="ruby-identifier">entry</span><span class="ruby-operator">|</span> + <span class="ruby-keyword">next</span> <span class="ruby-keyword">if</span> <span class="ruby-identifier">entry</span>.<span class="ruby-identifier">directory?</span> + <span class="ruby-identifier">dest</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">expand_path</span>(<span class="ruby-identifier">dest</span>, <span class="ruby-identifier">target</span>.<span class="ruby-identifier">to_s</span>) + <span class="ruby-identifier">trace</span> <span class="ruby-node">"Extracting #{dest}"</span> + <span class="ruby-identifier">mkpath</span> <span class="ruby-constant">File</span>.<span class="ruby-identifier">dirname</span>(<span class="ruby-identifier">dest</span>) <span class="ruby-keyword">rescue</span> <span class="ruby-keyword">nil</span> + <span class="ruby-identifier">entry</span>.<span class="ruby-identifier">restore_permissions</span> = <span class="ruby-keyword">true</span> + <span class="ruby-identifier">entry</span>.<span class="ruby-identifier">extract</span>(<span class="ruby-identifier">dest</span>) { <span class="ruby-keyword">true</span> } + <span class="ruby-keyword">end</span> + <span class="ruby-keyword">end</span> + <span class="ruby-keyword">end</span> + <span class="ruby-keyword">end</span> + <span class="ruby-comment"># Let other tasks know we updated the target directory.</span> + <span class="ruby-identifier">touch</span> <span class="ruby-identifier">target</span>.<span class="ruby-identifier">to_s</span> +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + <div id="method-i-from_path" class="method-detail "> + + + <div class="method-heading"> + <span class="method-callseq"> + from_path(name) → Path + </span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + + + <div class="method-description"> + + <p>Allows you to unzip from a path. Returns an object you can use to specify +which files to include/exclude relative to that path. Expands the file +relative to that path.</p> + +<p>For example:</p> + +<pre class="ruby"><span class="ruby-identifier">unzip</span>(<span class="ruby-constant">Dir</span>.<span class="ruby-identifier">pwd</span>=<span class="ruby-operator">></span><span class="ruby-string">'test.jar'</span>).<span class="ruby-identifier">from_path</span>(<span class="ruby-string">'etc'</span>).<span class="ruby-identifier">include</span>(<span class="ruby-string">'LICENSE'</span>) +</pre> + +<p>will unzip etc/LICENSE into ./LICENSE.</p> + +<p>This is different from:</p> + +<pre class="ruby"><span class="ruby-identifier">unzip</span>(<span class="ruby-constant">Dir</span>.<span class="ruby-identifier">pwd</span>=<span class="ruby-operator">></span><span class="ruby-string">'test.jar'</span>).<span class="ruby-identifier">include</span>(<span class="ruby-string">'etc/LICENSE'</span>) +</pre> + +<p>which unzips etc/LICENSE into ./etc/LICENSE.</p> + + + + + <div class="method-source-code" id="from_path-source"> + <pre><span class="ruby-comment"># File lib/buildr/packaging/ziptask.rb, line 256</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">from_path</span>(<span class="ruby-identifier">name</span>) + <span class="ruby-ivar">@paths</span>[<span class="ruby-identifier">name</span>] <span class="ruby-operator">||=</span> <span class="ruby-constant">FromPath</span>.<span class="ruby-identifier">new</span>(<span class="ruby-keyword">self</span>, <span class="ruby-identifier">name</span>) +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + <div class="aliases"> + Also aliased as: <a href="Unzip.html#method-i-path">path</a> + </div> + + + + </div> + + + <div id="method-i-include" class="method-detail "> + + + <div class="method-heading"> + <span class="method-callseq"> + include(*files) → self + </span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + <div class="method-heading"> + <span class="method-callseq"> + include(*files, :path=>name) → self + </span> + + </div> + + + + <div class="method-description"> + + <p>Include all files that match the patterns and returns self.</p> + +<p>Use include if you only want to unzip some of the files, by specifying them +instead of using exclusion. You can use <a +href="Unzip.html#method-i-include">include</a> in combination with <a +href="Unzip.html#method-i-exclude">exclude</a>.</p> + + + + + <div class="method-source-code" id="include-source"> + <pre><span class="ruby-comment"># File lib/buildr/packaging/ziptask.rb, line 216</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">include</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">files</span>) + <span class="ruby-keyword">if</span> <span class="ruby-constant">Hash</span> <span class="ruby-operator">===</span> <span class="ruby-identifier">files</span>.<span class="ruby-identifier">last</span> + <span class="ruby-identifier">from_path</span>(<span class="ruby-identifier">files</span>.<span class="ruby-identifier">pop</span>[<span class="ruby-value">:path</span>]).<span class="ruby-identifier">include</span> <span class="ruby-operator">*</span><span class="ruby-identifier">files</span> + <span class="ruby-keyword">else</span> + <span class="ruby-identifier">from_path</span>(<span class="ruby-keyword">nil</span>).<span class="ruby-identifier">include</span> <span class="ruby-operator">*</span><span class="ruby-identifier">files</span> + <span class="ruby-keyword">end</span> + <span class="ruby-keyword">self</span> +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + <div class="aliases"> + Also aliased as: <a href="Unzip.html#method-i-add">add</a> + </div> + + + + </div> + + + <div id="method-i-included-3F" class="method-detail "> + + <div class="method-heading"> + <span class="method-name">included?</span><span + class="method-args">(entry_name)</span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + + <div class="method-description"> + + <p>reads the includes/excludes and apply them to the entry_name</p> + + + + + <div class="method-source-code" id="included-3F-source"> + <pre><span class="ruby-comment"># File lib/buildr/packaging/ziptask.rb, line 190</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">included?</span>(<span class="ruby-identifier">entry_name</span>) + <span class="ruby-ivar">@paths</span>.<span class="ruby-identifier">each</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">path</span>, <span class="ruby-identifier">patterns</span><span class="ruby-operator">|</span> + <span class="ruby-keyword">return</span> <span class="ruby-keyword">true</span> <span class="ruby-keyword">if</span> <span class="ruby-identifier">path</span>.<span class="ruby-identifier">nil?</span> + <span class="ruby-keyword">if</span> <span class="ruby-identifier">entry_name</span> <span class="ruby-operator">=~</span> <span class="ruby-node">/^#{path}/</span> + <span class="ruby-identifier">short</span> = <span class="ruby-identifier">entry_name</span>.<span class="ruby-identifier">sub</span>(<span class="ruby-identifier">path</span>, <span class="ruby-string">''</span>) + <span class="ruby-keyword">if</span> <span class="ruby-identifier">patterns</span>.<span class="ruby-identifier">include</span>.<span class="ruby-identifier">any?</span> { <span class="ruby-operator">|</span><span class="ruby-identifier">pattern</span><span class="ruby-operator">|</span> <span class="ruby-constant">File</span>.<span class="ruby-identifier">fnmatch</span>(<span class="ruby-identifier">pattern</span>, <span class="ruby-identifier">entry_name</span>) } <span class="ruby-operator">&&</span> + <span class="ruby-operator">!</span><span class="ruby-identifier">patterns</span>.<span class="ruby-identifier">exclude</span>.<span class="ruby-identifier">any?</span> { <span class="ruby-operator">|</span><span class="ruby-identifier">pattern</span><span class="ruby-operator">|</span> <span class="ruby-constant">File</span>.<span class="ruby-identifier">fnmatch</span>(<span class="ruby-identifier">pattern</span>, <span class="ruby-identifier">entry_name</span>) } + <span class="ruby-comment"># trace "tar_entry.full_name " + entry_name + " is included"</span> + <span class="ruby-keyword">return</span> <span class="ruby-keyword">true</span> + <span class="ruby-keyword">end</span> + <span class="ruby-keyword">end</span> + <span class="ruby-keyword">end</span> + <span class="ruby-comment"># trace "tar_entry.full_name " + entry_name + " is excluded"</span> + <span class="ruby-keyword">return</span> <span class="ruby-keyword">false</span> +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + <div id="method-i-path" class="method-detail method-alias"> + + <div class="method-heading"> + <span class="method-name">path</span><span + class="method-args">(name)</span> + + </div> + + + <div class="method-description"> + + + + + + + </div> + + + + + <div class="aliases"> + Alias for: <a href="Unzip.html#method-i-from_path">from_path</a> + </div> + + </div> + + + <div id="method-i-root" class="method-detail "> + + + <div class="method-heading"> + <span class="method-callseq"> + root → Unzip + </span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + + + <div class="method-description"> + + <p>Returns the root path, essentially the <a href="Unzip.html">Unzip</a> +object itself. In case you are wondering down paths and want to go back.</p> + + + + + <div class="method-source-code" id="root-source"> + <pre><span class="ruby-comment"># File lib/buildr/packaging/ziptask.rb, line 266</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">root</span> + <span class="ruby-keyword">self</span> +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + <div id="method-i-to_s" class="method-detail "> + + <div class="method-heading"> + <span class="method-name">to_s</span><span + class="method-args">()</span> + + <span class="method-click-advice">click to toggle source</span> + + </div> + + + <div class="method-description"> + + <p>Returns the path to the target directory.</p> + + + + + <div class="method-source-code" id="to_s-source"> + <pre><span class="ruby-comment"># File lib/buildr/packaging/ziptask.rb, line 271</span> +<span class="ruby-keyword">def</span> <span class="ruby-identifier">to_s</span> + <span class="ruby-identifier">target</span>.<span class="ruby-identifier">to_s</span> +<span class="ruby-keyword">end</span></pre> + </div> + + </div> + + + + + </div> + + + </section> + + </section> +</main> + + +<footer id="validator-badges" role="contentinfo"> + <p><a href="http://validator.w3.org/check/referer">Validate</a> + <p>Generated by <a href="http://docs.seattlerb.org/rdoc/">RDoc</a> 4.2.2. + <p>Based on <a href="http://deveiate.org/projects/Darkfish-RDoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>. +</footer> +