jruby-gradle.github.io/base/index.html

452 lines
19 KiB
HTML

<html>
<head>
<link href='/stylesheets/foundation.css' rel='stylesheet'>
<link href='/stylesheets/jrubygradle.css' rel='stylesheet'>
<link href='/news.atom' rel='alternate' title='JRuby/Gradle News' type='application/atom+xml'>
<title>
Base plugin
</title>
</head>
<body>
<a href='https://github.com/jruby-gradle'>
<img alt='Fork me on GitHub' data-canonical-src='https://s3.amazonaws.com/github/ribbons/forkme_right_red_aa0000.png' src='https://camo.githubusercontent.com/365986a132ccd6a44c23a9169022c0b5c890c387/68747470733a2f2f73332e616d617a6f6e6177732e636f6d2f6769746875622f726962626f6e732f666f726b6d655f72696768745f7265645f6161303030302e706e67' style='position: absolute; top: 0; right: 0; border: 0;'>
</a>
<div id='main_nav'>
<ul>
<li>
<a href='/'>
Home
</a>
</li>
<li>
<a href='/docs/'>
Documentation
</a>
</li>
<li>
<a href='/community/'>
Community
</a>
</li>
<li>
<a href='/news/'>
News
</a>
</li>
<li>
<a href='/download/'>
Download
</a>
</li>
<li>
<a href='https://travis-ci.org/jruby-gradle/jruby-gradle-plugin'>
<img src='https://travis-ci.org/jruby-gradle/jruby-gradle-plugin.svg?branch=master'>
</a>
</li>
<li>
<a href='https://bintray.com/jruby-gradle/plugins'>
<img src='https://api.bintray.com/packages/jruby-gradle/plugins/jruby-gradle-plugin/images/download.svg'>
</a>
</li>
</ul>
</div>
<div id='content'>
<h1>
Base plugin
</h1>
<div id="preamble">
<div class="sectionbody">
<div class="imageblock">
<div class="content">
<a class="image" href="https://travis-ci.org/jruby-gradle/jruby-gradle-plugin"><img src="https://travis-ci.org/jruby-gradle/jruby-gradle-plugin.svg?branch=master" alt="Build Status"></a>
</div>
</div>
<div class="imageblock">
<div class="content">
<a class="image" href="https://bintray.com/jruby-gradle/plugins/jruby-gradle-plugin/_latestVersion"><img src="https://api.bintray.com/packages/jruby-gradle/plugins/jruby-gradle-plugin/images/download.svg" alt="download"></a>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="getting-started"><a class="anchor" href="#getting-started"></a>Getting Started</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="compatibility"><a class="anchor" href="#compatibility"></a>Compatibility</h3>
<div class="paragraph">
<p>This plugin requires <a href="http://gradle.org">Gradle</a> 2.0 or better</p>
</div>
</div>
<div class="sect2">
<h3 id="installing"><a class="anchor" href="#installing"></a>Installing</h3>
<div class="listingblock">
<div class="title">build.gradle</div>
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="groovy">buildscript {
repositories { jcenter() }
dependencies {
<span class="comment">/* check jruby-gradle.org for the latest release */</span>
classpath <span class="string"><span class="delimiter">&quot;</span><span class="content">com.github.jruby-gradle:jruby-gradle-plugin:1.1.0</span><span class="delimiter">&quot;</span></span>
}
}
apply <span class="key">plugin</span>: <span class="string"><span class="delimiter">'</span><span class="content">com.github.jruby-gradle.base</span><span class="delimiter">'</span></span></code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="adding-gems"><a class="anchor" href="#adding-gems"></a>Adding gems</h3>
<div class="paragraph">
<p>You can also add Ruby gem dependencies in your <code>build.gradle</code> file under the
<code>gems</code> <a href="https://docs.gradle.org/current/dsl/org.gradle.api.artifacts.Configuration.html">configuration</a> which is provided by plugin, e.g.:</p>
</div>
<div class="listingblock">
<div class="title">build.gradle</div>
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="groovy">dependencies {
gems <span class="key">group</span>: <span class="string"><span class="delimiter">'</span><span class="content">rubygems</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">sinatra</span><span class="delimiter">'</span></span>, <span class="key">version</span>: <span class="string"><span class="delimiter">'</span><span class="content">1.4.5</span><span class="delimiter">'</span></span>
<span class="comment">/* alternatively */</span>
gems <span class="string"><span class="delimiter">'</span><span class="content">rubygems:rake:10.3.+</span><span class="delimiter">'</span></span>
<span class="comment">/* prereleased gems needs to pick a specific version */</span>
gems <span class="string"><span class="delimiter">'</span><span class="content">rubygems:rails:4.2.3.rc1</span><span class="delimiter">'</span></span>
}</code></pre>
</div>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
Prereleased gems can only be a specific version due to limitations of mapping a rubygems repository to a maven repository.
</td>
</tr>
</table>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
This functionality currently relies on a deployed version of the
<a href="https://github.com/torquebox/rubygems-servlets">rubygems-servlets</a>
software to help proxy a Rubygem repository into a Maven repository format.
This ensures that Gradle can resolve gem-based dependencies. <em>Currently</em> the
plugin release on <a href="http://rubygems.lasagna.io/proxy/maven/releases">a
Rubygems Maven proxy</a> operated by <a href="https://github.com/rtyler">R. Tyler
Croy</a>
</td>
</tr>
</table>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="tasks"><a class="anchor" href="#tasks"></a>Tasks</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="jrubyexec"><a class="anchor" href="#jrubyexec"></a>JRubyExec</h3>
<div class="paragraph">
<p><a href="/groovydoc/jruby-gradle-base-plugin/com/github/jrubygradle/JRubyExec.html">API docs</a></p>
</div>
<div class="paragraph">
<p>In a similar vein to <code>JavaExec</code> and <code>RhinoShellExec</code>, the <code>JRubyExec</code> allows
for Ruby scripts to be executed in a Gradle script using JRuby.</p>
</div>
<div class="listingblock">
<div class="title">build.gradle</div>
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">com.github.jrubygradle.JRubyExec</span>
dependencies {
jrubyExec <span class="string"><span class="delimiter">'</span><span class="content">rubygems:credit_card_validator:1.2.0</span><span class="delimiter">'</span></span>
}
task runMyScript(<span class="key">type</span>: JRubyExec) {
script <span class="string"><span class="delimiter">'</span><span class="content">scripts/runme.rb</span><span class="delimiter">'</span></span>
scriptArgs <span class="string"><span class="delimiter">'</span><span class="content">-x</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">-y</span><span class="delimiter">'</span></span>
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Common methods for <code>JRubyExec</code> for executing a script</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>script</code> - <code>Object</code> (Usually File or String). Path to the script.</p>
</li>
<li>
<p><code>scriptArgs</code> - <code>List</code>. List of arguments to pass to script.</p>
</li>
<li>
<p><code>workingDir</code> - <code>Object</code> (Usually File or String). Working directory for script.</p>
</li>
<li>
<p><code>environment</code> - <code>Map</code>. Environment to be set. Do not set <code>GEM_HOME</code> or <code>GEM_PATH</code> with this method.</p>
</li>
<li>
<p><code>standardInput</code> - <code>InputStream</code>. Set an input stream to be read by the script.</p>
</li>
<li>
<p><code>standardOutput</code> - <code>OutputStream</code>. Capture the output of the script.</p>
</li>
<li>
<p><code>errorOutput</code> - <code>OutputStream</code>. Capture the error output of the script.</p>
</li>
<li>
<p><code>ignoreExitValue</code> - <code>Boolean</code>. Ignore the JVm exit value. Exit values are only effective if the exit value of the Ruby script is correctly communicated back to the JVM.</p>
</li>
<li>
<p><code>configuration</code> - <code>String</code>. Configuration to copy gems from. (*)</p>
</li>
<li>
<p><code>classpath</code> - <code>List</code>. Additional Jars/Directories to place on classpath.</p>
</li>
<li>
<p><code>jrubyVersion</code> - <code>String</code>. JRuby version to use if not the same as ```project.jruby.execVersion```.</p>
</li>
<li>
<p><code>gemWorkDir</code> - <code>File</code>. Provide a custom working directory for unpacking GEMs. By default each <code>JRubyExec</code> task
uses it&#8217;s own work directory. Use this to set a common work directory for a number of tasks.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>(*) If <code>jrubyVersion</code> has not been set, <code>jrubyExec</code> will used as configuration.
However, if <code>jrubyVersion</code> has been set, a configuration must also be provded
to maintain dependency isolation, see
<a href="http://jruby-gradle.org/errors/jrubyexec-version-conflict/">this page</a> for more details.</p>
</div>
<div class="paragraph">
<p>Additional <code>JRubyExec</code> methods for controlling the JVM instance</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>jvmArgs</code> - <code>List</code>. See <a href="http://www.gradle.org/docs/current/dsl/org.gradle.api.tasks.JavaExec.html#org.gradle.api.tasks.JavaExec:jvmArgs">jvmArgs</a></p>
</li>
<li>
<p><code>allJvmArgs</code> - <code>List</code>. See <a href="http://www.gradle.org/docs/current/dsl/org.gradle.api.tasks.JavaExec.html#org.gradle.api.tasks.JavaExec:allJvmArgs">allJvmArgs</a></p>
</li>
<li>
<p><code>systemProperties</code> - <code>Map</code>. See <a href="http://www.gradle.org/docs/current/dsl/org.gradle.api.tasks.JavaExec.html#org.gradle.api.tasks.JavaExec:systemProperties">systemProperties</a></p>
</li>
<li>
<p><code>bootstrapClassPath</code> - <code>FileCollection</code> or <code>List</code>. See <a href="http://www.gradle.org/docs/current/dsl/org.gradle.api.tasks.JavaExec.html#org.gradle.api.tasks.JavaExec:bootstrapClasspath">bootstrapClasspath</a></p>
</li>
<li>
<p><code>minHeapSize</code> - <code>String</code>. See <a href="http://www.gradle.org/docs/current/dsl/org.gradle.api.tasks.JavaExec.html:minHeapSize">minHeapSize</a></p>
</li>
<li>
<p><code>maxHeapSize</code> - <code>String</code>. See <a href="http://www.gradle.org/docs/current/dsl/org.gradle.api.tasks.JavaExec.html#org.gradle.api.tasks.JavaExec:maxHeapSize">maxHeapSize</a></p>
</li>
<li>
<p><code>defaultCharacterEncoding</code> - <code>String</code>. See <a href="http://www.gradle.org/docs/current/dsl/org.gradle.api.tasks.JavaExec.html:defaultCharacterEncoding">defaultCharacterEncoding</a></p>
</li>
<li>
<p><code>enableAssertions</code> - <code>Boolean</code>. See <a href="http://www.gradle.org/docs/current/dsl/org.gradle.api.tasks.JavaExec.html#org.gradle.api.tasks.JavaExec:enableAssertions">enableAssertions</a></p>
</li>
<li>
<p><code>debug</code> - <code>Boolean</code>. See <a href="http://www.gradle.org/docs/current/dsl/org.gradle.api.tasks.JavaExec.html#org.gradle.api.tasks.JavaExec:debug">debug</a></p>
</li>
<li>
<p><code>copyTo</code> - <code>JavaForkOptions</code>. See <a href="http://www.gradle.org/docs/current/dsl/org.gradle.api.tasks.JavaExec.html:copyTo">copyTo</a></p>
</li>
<li>
<p><code>executable</code> - <code>Object</code> (Usually <code>File</code> or <code>String</code>). See <a href="http://www.gradle.org/docs/current/dsl/org.gradle.api.tasks.JavaExec.html#org.gradle.api.tasks.JavaExec:executable">executable</a></p>
</li>
</ul>
</div>
<div class="sect3">
<h4 id="jrubyexec-extension"><a class="anchor" href="#jrubyexec-extension"></a>jrubyexec extension</h4>
<div class="paragraph">
<p>Similar to
<a href="https://docs.gradle.org/current/dsl/org.gradle.api.Project.html#org.gradle.api.Project:javaexec(groovy.lang.Closure)">javaexec</a>
and
<a href="https://docs.gradle.org/current/dsl/org.gradle.api.Project.html#org.gradle.api.Project:exec(org.gradle.api.Action)">exec</a>
it is possible to add the execution of a JRuby script to another task:</p>
</div>
<div class="listingblock">
<div class="title">build.gradle</div>
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="gradle">task needSomeRubyLove {
jrubyexec {
script 'scripts/runme.rb'
scriptArgs '-x', '-y'
}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The behaviour of <code>project.jrubyexec</code> is slightly different to that of <code>JRubyExec</code>.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>The version of <code>jruby-complete</code> is strictly tied to the <code>jruby.execVersion</code>. Therefore trying to set <code>jrubyVersion</code>
in the ```jrubyexec``` closure will cause a failure</p>
</li>
<li>
<p>GEMs and additional JARs are only taken from the <code>jrubyExec</code> configuration.</p>
</li>
<li>
<p>It is not possible to supply a <code>configuration</code> parameter to the <code>jrubyexec</code> closure.</p>
</li>
<li>
<p>GEMs will be installed to <code>jruby.gemInstallDir</code>. Existing gems will not be overwritten.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>As with <code>JRubyExec</code>, <code>args</code>, <code>setArgs</code> and <code>main</code> are illegal within the <code>jrubyexec</code> closure.
All other methods should work.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="running-a-ruby-path-command"><a class="anchor" href="#running-a-ruby-path-command"></a>Running a Ruby PATH command</h3>
<div class="paragraph">
<p>Because <code>JRubyExec</code> checks for the existence of the script, it might look at first whether running Ruby commands from
<code>PATH</code> could be difficult. However, this is totally possible by utilising <code>jrubyArgs</code> and passing <code>-S</code> as one would do
when using <code>ruby</code> or <code>jruby</code> on the command-line. Here is an example of running
<code>rake</code> as task.</p>
</div>
<div class="listingblock">
<div class="title">build.gradle</div>
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="gradle">task rake(type : JRubyExec) {
script 'rake'
scriptArgs '/path/to/Rakefile', 'target1', 'target2'
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>or even</p>
</div>
<div class="listingblock">
<div class="title">build.gradle</div>
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="gradle">ext {
rake = { String target -&gt;
jrubyexec {
jrubyArgs '-S'
script 'rake'
scriptArgs '/path/to/Rakefile', target
}
}
}</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="jrubyprepare"><a class="anchor" href="#jrubyprepare"></a>JRubyPrepare</h2>
<div class="sectionbody">
<div class="paragraph">
<p><a href="/groovydoc/jruby-gradle-base-plugin/com/github/jrubygradle/JRubyPrepare.html">API docs</a></p>
</div>
<div class="paragraph">
<p>Unpacking occurs using the default <code>jruby</code> version as set by <code>jruby.execVersion</code>.</p>
</div>
<div class="listingblock">
<div class="title">build.gradle</div>
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="gradle">import com.github.jrubygradle.JRubyPrepare
task unpackMyGems(type : JRubyPrepare) {
// Parent directory for unpacking GEMs.
// Gems will end up in a subdirectory 'gems/GemName-GemVersion'
outputDir buildDir
// Add one or more gems
// Can be String(s), File(s), FileCollection(s) or Configuration(s)
gems project.configuration.gems
}</code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="advanced-usage"><a class="anchor" href="#advanced-usage"></a>Advanced Usage</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="using-a-custom-gem-repository"><a class="anchor" href="#using-a-custom-gem-repository"></a>Using a custom Gem repository</h3>
<div class="paragraph">
<p>By default the jruby plugin will use
[rubygems-proxy.torquebox.org](<a href="http://rubygems-proxy.torquebox.org" class="bare">http://rubygems-proxy.torquebox.org</a>) as its
source of Ruby gems. This is a server operated by the Torquebox project which
presents [rubygems.org](<a href="https://rubygems.org" class="bare">https://rubygems.org</a>) as a Maven repository.</p>
</div>
<div class="paragraph">
<p>If you <strong>do not</strong> wish to use this repository, you can run your own Maven
proxy repository for either rubygems.org or your own gem repository by
running the [rubygems-servlets](<a href="https://github.com/torquebox/rubygems-servlets" class="bare">https://github.com/torquebox/rubygems-servlets</a>)
server.</p>
</div>
<div class="paragraph">
<p>You can then use that custom Gem repository with:</p>
</div>
<div class="listingblock">
<div class="title">build.gradle</div>
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="gradle">jruby {
defaultRepositories = false
}
repositories {
maven { url 'http://localhost:8989/releases' }
}
dependencies {
gems group: 'com.lookout', name: 'custom-gem', version: '1.0.+'
}</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="using-the-jruby-gradle-without-gradle"><a class="anchor" href="#using-the-jruby-gradle-without-gradle"></a>Using the JRuby/Gradle without Gradle</h3>
<div class="paragraph">
<p>There are still plenty of cases, such as for local development, when you might
not want to create a full <code>.war</code> file to run some tests. In order to use the
same gems and <code>.jar</code> based dependencies, add the following to the entry point
for your application:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="ruby"><span class="comment"># Hack our GEM_HOME to make sure that the `rubygems` support can find our</span>
<span class="comment"># unpacked gems in build/gems/</span>
vendored_gems = <span class="constant">File</span>.expand_path(<span class="constant">File</span>.dirname(<span class="predefined-constant">__FILE__</span>) + <span class="string"><span class="delimiter">'</span><span class="content">/build/gems</span><span class="delimiter">'</span></span>)
<span class="keyword">if</span> <span class="constant">File</span>.exists?(vendored_gems)
<span class="predefined-constant">ENV</span>[<span class="string"><span class="delimiter">'</span><span class="content">GEM_HOME</span><span class="delimiter">'</span></span>] = vendored_gems
<span class="keyword">end</span></code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The <code>.rb</code> file is assuming it&#8217;s in the top level of the source tree, i.e.
where <code>build.gradle</code> is located
</td>
</tr>
</table>
</div>
</div>
</div>
</div>
</div>
<hr>
</body>
</html>