compusition

[NOTE: This info is out of date. You should check out the Embedding Ruby in Java page on the official JRuby wiki. It's now recommended you use the "core" (built in) embedding API instead of BSF as explained below.]

This article describes how to setup Eclipse to develop Java+Ruby applications using JRuby, a Java wrapper for Ruby that can be embedded anywhere Java runs (which is just about everywhere!). I am use this setup to develop the MaxObject "ruby" for running Ruby inside of Max/MSP.

Prerequisites

If you do not already have Eclipse setup, see these instructions (if you don't have Max/MSP stop after step 4 of those instructions)

Although this article describes the setup in Eclipse, the steps should be easily adapted to other IDEs. Note the Ruby Developer Tools plugin is specifically for Eclipse. Hopefully your IDE already has Ruby support, otherwise why not use Eclipse?

Conventions

When I say "right click", OS X users should understand this is the same as ctrl+click.

Setup

1. Download JRuby. Get the latest jruby-bin distribution
2. Install the jars. Inside the distribution there is a lib folder with two jar files: bsf.jar and jruby.jar. Add both these jars to your Eclipse project. You can do that the same way as max.jar
3. Install Ruby Development Tools for Eclipse to get standard niceties like syntax highlighting and code completion for your Ruby code. The easiest way to do this is with the Eclipse Update Manager:
   • In Eclipse go to Help -> Software Updates -> Find and Install...
   • Select "Search for new features to install" and click Next
   • Click "New Remote Site"
   • Enter the name Ruby Development Tools and the URL http://updatesite.rubypeople.org/release
   • Click OK. Ruby Development Tools should be the only thing checked in the "Sites to include in search" box. Click Finish.
   • A Search Results window opens. Expand Ruby Development Tools and select the inner "Ruby Development Tools" option (feel free to install the Integration Plugins too but you probably don't need them). Click Next. Accept the license. Finish.
   • An installation window opens. Select Install All. Restart Eclipse when prompted. Close the welcome tab to get your workbench back.
   • On Windows, you may be prompted to install Ruby or use JRuby. It's fine to use JRuby, which requires no further setup.
4. Test your setup. You should now be ready to start coding in Ruby.
   • Create a folder called "ruby" under your Eclipse project (right click the project folder -> New -> Folder)
   • Create a file called "test.rb" (right click the ruby folder -> New -> File) with the following contents: puts "hello from a file";
   • Create a new Java class named JRubyTest (right click the src folder -> New -> Class. Enter the name and click Finish) with the following contents: import java.io.*; import org.apache.bsf.*; import org.apache.bsf.util.IOUtils; public class JRubyTest { BSFManager manager; public static void main(String[] args) throws Exception { JRubyTest jruby = new JRubyTest(); jruby.eval("puts 'hello from a string of ruby code'"); File f = new File("ruby/test.rb"); jruby.exec(f); jruby.eval("$out.println('hello System.out')"); } public JRubyTest() throws BSFException { BSFManager.registerScriptingEngine("ruby", "org.jruby.javasupport.bsf.JRubyEngine", new String[] { "rb" }); manager = new BSFManager(); manager.declareBean("out", System.out, PrintStream.class); } public Object eval(String script) throws BSFException { return manager.eval("ruby", "(java)", 1, 1, script); } public void exec(File file) throws BSFException, IOException { FileReader in = new FileReader(file); String script = IOUtils.getStringFromReader(in); manager.exec("ruby", file.getName(), 1, 1, script); } }
   • Click the Run button . You should see this in your console:

     hello from a string of ruby code
     hello from a file
     hello System.out
           

Next Steps

http://ruby-lang.org is a great resource for learning Ruby. The Ruby Cheatsheet is a nice quick reference.

The JRuby distribution has samples and docs if you want to know more about JRuby.

JRuby runs on the Bean Scripting Framework (BSF), which also supports things like Python, Groovy, and even scripted Java (BeanShell). Python is supported "out of the box", so you already have everything you need to run Python inside Java and Java-based Max externals. Check out the BSF website for more info. The BSF download comes with the API documentation, which is useful for working with JRuby.

For running Ruby inside Max/MSP, try my ajm.ruby max object. Source code is included so you can see how I dealt with the "glue" between Max and Ruby.

Adam Murray, 2008
contact the author...