JRuby Gradle plugin

The purpose of plugin is to encapsulate useful Gradle functionality for JRuby projects. Use of this plugin replaces the need for both Bundler and Warbler in JRuby projects.

The Ruby gem dependency code for this project relies on the Rubygems Maven proxy provided by the Torquebox project.

This is the base plugin. If you are interesting in doing the following then consult the pages for the appropriate plugins:

Building JRuby-based Java JARs, including making them executable - jruby-gradle-jar-plugin
Building JRuby-based Java Web Applications (WARs), - jruby-gradle-war-plugin

Compatilibity

This plugin requires Gradle 2.0 or better

Getting Started

buildscript {
    repositories { jcenter() }

    dependencies {
      classpath group: 'com.github.jruby-gradle', name: 'jruby-gradle-plugin', version: '0.1.2'
    }
}

apply plugin: 'com.github.jruby-gradle.base'

Adding gems

You can also add Ruby gem dependencies in your build.gradle file under the gem configuration, e.g.:

dependencies {
    gems group: 'rubygems', name: 'sinatra', version: '1.4.5'
    gems group: 'rubygems', name: 'rake', version: '10.3.+'
}

Default Tasks

The plugin provides the following tasks:

jrubyPrepareGems - Extract GEMs declared as dependencies under gems to jruby.gemInstallDir. This is as instance of JRubyPrepareGems.
jrubyPrepare - Call jrubyPrepareGems. Also copies the content of Java-based dependencies into .jarcache/ for interpreted use

JRubyExec - Task for Executing a Ruby Script

In a similar vein to JavaExec and RhinoShellExec, the JRubyExec allows for Ruby scripts to be executed in a Gradle script using JRuby.

import com.github.jrubygradle.JRubyExec

dependencies {
    jrubyExec 'rubygems:credit_card_validator:1.2.0'
}

task runMyScript( type: JRubyExec ) {
    script 'scripts/runme.rb'
    scriptArgs '-x', '-y'
}

Common methods for JRubyExec for executing a script

script - Object (Usually File or String). Path to the script.
scriptArgs - List. List of arguments to pass to script.
workingDir - Object (Usually File or String). Working directory for script.
environment - Map. Environment to be set. Do not set GEM_HOME or GEM_PATH with this method.
standardInput - InputStream. Set an input stream to be read by the script.
standardOutput - OutputStream. Capture the output of the script.
errorOutput - OutputStream. Capture the error output of the script.
ignoreExitValue - Boolean. 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.
configuration - String. Configuration to copy gems from. (*)
classpath - List. Additional Jars/Directories to place on classpath.
jrubyVersion - String. JRuby version to use if not the same as project.jruby.execVersion.

(*) If jRubyVersion has not been set, jrubyExec will used as configuration. However, if jRubyVersion has been set, no gems will be used unless an explicit configuration has been provided

Additional JRubyExec methods for controlling the JVM instance

jvmArgs - List. See jvmArgs
allJvmArgs - List. See allJvmArgs
systemProperties - Map. See systemProperties
bootstrapClassPath - FileCollection or List. See bootstrapClassPath
minHeapSize - String. See minHeapSize
maxHeapSize - String. See maxHeapSize
defaultCharacterEncoding - String. See defaultCharacterEncoding
enableAssertions - Boolean. See enableAssertions
debug - Boolean. See debug
copyTo - JavaForkOptions. See copyTo
executable - Object (Usually File or String). See executable

jrubyexec extension

Similar to javaexec and exec it is possible to add the execution of a jruby script within another task

task needSomeRubyLove {
  jrubyexec {
    script 'scripts/runme.rb'
    scriptArgs '-x', '-y'  
  }
}

The behaviour of project.jrubyexec is slightly different to that of JRubyExec.

The version of jruby-complete is strictly tied to the jruby.execVersion. Therefore trying to set jrubyVersion in the jrubyexec closure will cause a failure
GEMs and additional JARs are only taken from the jrubyExec configuration.
It is not possible to supply a configuration parameter to the jrubyexec closure.
GEMs will be installed to jruby.gemInstallDir. Existing gems will not be overwritten.

As with JRubyExec, args, setArgs and main are illegal within the jrubyexec closure. All other methods should work.

JRubyPrepareGems - A task for unpacking GEMs

Unpacking occurs using the default jruby version as set by jruby.execVersion.

import com.github.jrubygradle.JRubyPrepareGems

task unpackMyGems( type : JRubyPrepareGems ) {

  // 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
  
}

Advanced Usage

Using a custom Gem repository

By default the jruby plugin will use rubygems-proxy.torquebox.org as its source of Ruby gems. This is a server operated by the Torquebox project which presents rubygems.org as a Maven repository.

If you do not 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 server.

You can then use that custom Gem repository with:

jruby {
    defaultRepositories = false
}

repositories {
    maven { url : 'http://localhost:8989/releases' }
}

dependencies {
    gems group: 'com.lookout', name: 'custom-gem', version: '1.0.+'
}

Using the Ruby interpreter

There are still plenty of cases, such as for local development, when you might not want to create a full .war file to run some tests. In order to use the same gems and .jar based dependencies, add the following to the entry point for your application:

# Hack our GEM_HOME to make sure that the `rubygems` support can find our
# unpacked gems in build/vendor/
vendored_gems = File.expand_path(File.dirname(__FILE__) + '/build/vendor')
if File.exists?(vendored_gems)
  ENV['GEM_HOME'] = vendored_gems
end

jar_cache = File.expand_path(File.dirname(__FILE__) + '/.jarcache/')
if File.exists?(jar_cache)
  # Under JRuby `require`ing a `.jar` file will result in it being added to the
  # classpath for easy importing
  Dir["#{jar_cache}/*.jar"].each { |j| require j }
end

Note: in the example above, the .rb file is assuming it's in the top level of the source tree, i.e. where build.gradle is located

Quickstart for those unfamiliar with Gradle

Note: This assumes you already have Gradle installed. If you are not on Windows it is recommended that you use GVM to install Gradle

% mkdir fancy-webapp
% cd fancy-webapp
% git init
Initialized empty Git repository in /usr/home/tyler/source/github/fancy-webapp/.git/
% gradle wrapper init  # Create the wrappers to easily bootstrap others
:wrapper
:init 

BUILD SUCCESSFUL

Total time: 6.411 secs
% git add gradle gradlew gradlew.bat
% git commit -m "Initial commit with gradle wrappers"

Edit the created build.gradle file in the root of fancy-webapp/ as above

bbradbury/jruby-gradle-plugin