jruby-gradle-plugin

History

Uwe Kubosch 4fba3bb2b5 Bump version to 2.1.0-beta.1		2023-05-17 11:51:20 +02:00
..
src	Bump version to 2.1.0-beta.1	2023-05-17 11:51:20 +02:00
README.adoc	Remove all dependency on Torquebox (#388 )	2019-12-19 23:28:05 +01:00
build.gradle	(#386 ) Setup initial publishing from GH Actions	2021-05-02 21:43:57 +02:00

README.adoc

Getting Started

Compatibility

This plugin requires Gradle 4.9 or better

Installing

build.gradle

plugins {
  id 'com.github.jruby-gradle.base' version 'VERSION-OF-PLUGIN'
}

Adding gems

You can also add Ruby gem dependencies in your build.gradle file under the gems configuration which is provided by plugin, e.g.:

build.gradle

dependencies {
    gems group: 'rubygems', name: 'sinatra', version: '1.4.5'
    /* alternatively */
    gems 'rubygems:rake:10.3.+'
    /* prereleased gems needs to pick a specific version */
    gems 'rubygems:rails:4.2.3.rc1'
}

Important

Prereleased gems should only be a specific version due to limitations of mapping a rubygems repository to an Ivy repository.

Note	This functionality relies on an internal proxy which converts information from https://rubygems.org in to an Ivy repository service. this functionality is enabled by adding `ruby.gems()` to the `repositories` block. If you have a running Maven GEMs proxy you may use that too.

Tasks

JRubyExec

API docs

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

build.gradle

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.
jrubyArgs - List. List of arguments to be passed to JRuby itself.
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.
jruby - JRubyPluginExtension. Allows to override settigns from the global jruby extension.

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 to another task:

build.gradle

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 is strictly tied to the global jruby.jrubyVersion.
GEMs and additional JARs are only taken from the jruby.gemConfiguration configuration.

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

Running a Ruby PATH command

Because JRubyExec checks for the existence of the script, it might look at first whether running Ruby commands from PATH could be difficult. However, this is totally possible by utilising jrubyArgs and passing -S as one would do when using ruby or jruby on the command-line. Here is an example of running rake as task.

build.gradle

task rake(type : JRubyExec) {
    script 'rake'
    scriptArgs '/path/to/Rakefile', 'target1', 'target2'
}

or even

build.gradle

ext {
    rake = { String target ->
        jrubyexec {
            jrubyArgs '-S'
            script 'rake'
            scriptArgs '/path/to/Rakefile', target
        }
    }
}

JRubyPrepare

API docs

Unpacking occurs using the default JRuby version as set by jruby.jrubyVersion. This can be overridden within the task itself if required.

In most cases you do not have to do anything. The JRubyPrepare task will be created for you and associated with the appropriate configuration. If you customise configurations or use different configurations for different tasks, Gradle will useually create appropriate JRubyPrepare tasks for you and link the appropriate task dependencies.

You can also create your own custom JRubyPrepare tasks if required.

build.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)
  dependencies project.configurations.gems
}

Advanced Usage

Using the built-in Gem proxy

As of version 2.0, the JRuby/Gradle base plugin supports embedding a lightweight proxy inside* the Gradle process itself. This obviates the need for a third-party proxy to present the Maven-compatible dependency information that JRuby/Gradle relies on and it also supercedes the older rubygems-servlets process

build.gradle

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

/* Disable our default repositories */
jruby.defaultRepositories false

repositories {
    jcenter()
    ruby.gems() // (1)
    ruby.gems('https://your-own-server.org') // (2)
    ruby.gems('https://another-server.org', 'acmegems') // (3)
    ruby.torquebox() // (4)
}

dependencies {
    gems 'rubygems:sinatra:1.4.5' // (5)
    gems 'acmegems:some-gem:1.2.3' // (6)
}

Retrieve GEMs from https://rubygems.org
Retrieve GEMs from another server.
Retrieve GEMS from another server and associated a custom group name with that server.
Enabled the legacy Torquebox Maven proxy. Please note that this proxy server is unmaintained upstream and may lead to brittle builds in some cases.
Retrieve a GEM. rubygems is the default group for GEMs.
Retrieve a GEM using a custom group.

Note	If the version of Gradle supports the `content` DSL keyword for repositories, only requests dependencies with the specific groups will be sent to the GEM repositories.

Using the JRuby/Gradle without Gradle

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/gems/
vendored_gems = File.expand_path(File.dirname(__FILE__) + '/build/gems')
if File.exists?(vendored_gems)
  ENV['GEM_HOME'] = vendored_gems
end

Note	The `.rb` file is assuming it’s in the top level of the source tree, i.e. where `build.gradle` is located

Upgrading to 2.x from 1.7.x

If you are already using the base proxy for work, upgrading will yield a number of surprises. Hopefully they will come as nice wow factors once you have changed your build file.

Default repositories

Repositories are no longer added by default. You should explictly declare which repositories you require. If you still need the old behaviour, you can obtain that by

jruby {
    defaultRepositories = true // (1)
}

Adds ruby.gems() and jcenter().

This functionality is deprecated and will be removed in a future version.

jrubyExec configuration

The jrubyExec configuration is no longer added as the GEM configuration handling has been cleaned up and much improved in 2.x. If you have a number of instances relying on jrubyExec you can do

configurations {
    jrubyExec
}

and then enable this configuration either globally as your GEM configuration by doing

jruby {
    gemConfiguration 'jrubyExec'
}

or on a task-specific basis

task myRunner(type: JRubyExec) {
    jruby {
        gemConfiguration 'jrubyExec' // (1)
    }
}

Enables configuration only for the given task.

Note	If you set `gemConfiguration 'jrubyExec'` you will also notice that Gradle creates a `jrubyPrepareJrubyExec` tasks to unpack your GEMs in an isolated area.

Setting GEM & JAR installation directories

This behaviour was already deprecated in 1.7.x and has now been removed. Directories are now associated with specific configuration names. For the gems configuration this is in ${buildDir}/.gems. For other configurations it will be a different directory. You can obtain the directory, via the JRubyPrepare.getOutputDir() method.

Setting the JRuby version to use

jruby.defaultVersion is deprecated. Do this rather via

jruby {
    jrubyVersion = '9.1.2.3'
}

You can also override the JRuby version a per-task basis.

task myRunner(type: JRubyExec) {
    jruby {
        jrubyVersion = '9.1.2.3' // (1)
    }
}

Use a different version of JRuby only in a specific task, whilst using a globally configured version for everything else.

Changing the JRubyExec configuration

The configuration is deprecated. Use jruby.gemConfiguration on the task itself for a custom configuration.

Last updated 2024-04-29 12:57:42 UTC

</html>

README.adoc Unescape Escape

Getting Started

Compatibility

Installing

Adding gems

Tasks

JRubyExec

jrubyexec extension

Running a Ruby PATH command

JRubyPrepare

Advanced Usage

Using the built-in Gem proxy

Using the JRuby/Gradle without Gradle

Upgrading to 2.x from 1.7.x

Default repositories

jrubyExec configuration

Setting GEM & JAR installation directories

Setting the JRuby version to use

Changing the JRubyExec configuration

README.adoc