JRuby Bridge Tutorial - Compiling and Running

For this description, it is assumed, that the source files are stored in the directories shown here, and that jruby, javac and java are in your PATH. It is also assumed that the commands are issued from your project directory. The example code displayed below is for Windows.

Environment variables

Name	Value	Meaning
CLASSPATH	.;c:\dl\jruby-complete-1.7.23.jar	(Example)
JAVA_TOOL_OPTIONS	-Dfile.encoding=UTF8	This is necessary, if the source files are UTF8 encoded. Annoying side effect: Compilation of a Java file produces the (harmless) warning Picked up JAVA_TOOL_OPTIONS. Alternatively specify `-encoding UTF-8` when invoking javac.

Compiling the files

The Ruby files don't need to be compiled, but a syntax check can be done by, i.e.

jruby -c rbsrc\asahi.rb

The Java files are compiled with

javac -d . jsrc\HE.java

This will generate the following class files:


.\Jmain.class
.\vp\VP.class
.\hostenv\HE.class

Creating the manifest

Create a file ./MANIFEST.MF - actually, any name is fine, but this name is commonly used - with the following content:

Manifest-Version: 1.0
Main-Class: Jmain

Creating the Jar

mkdir .\jars\vp.jar
jar cvfm .\jars\vp.jar .\MANIFEST.MF -C . .\Jmain.class .\vp\VP.class .\hostenv\HE.class .\rbsrc

This creates a file jars\vp.jar. Note that by virtue of the last argument, the complete JRuby source dir is included in the vp.jar.

Running the example program

Executing the program needs the Jar file which we just have created (vp.jar) and jruby-complete-xxx.jar, which contains all of JRuby. We have now two choices:

Run the application by specifying both Jar files
Run the application from a combined Jar file

Keeping the Jars apart

The example program can be run by executing (i.e.):

java -cp c:\dl\jruby-complete-1.7.23.jar;jars\vp.jar Jmain

Note that we have explicitly name the start class, Jmain, even though we have put it into the mainifest: Since we have two jar files, there are two manifests, and it would not be clear, which of those would be the one which names the start class. Also, -cp option is used.

Combining the Jar files

Since the jar command doesn't offer an easy way to merge two jar-files into one, you have to unpack them, merge the manifests, and pack everything together. Especially merging the manifests can, in theory, be tedious, but at least with the current JRuby versions, I found this unnecessary. Here is how to proceed:

mkdir jctemp
cd jctemp
jar -xf c:\dl\jruby-complete-1.7.23.jar
jar -xf ..\jars\vp.jar
cd ..
jar -cvfm .\jars\combined.jar .\jctemp\META-INF\MANIFEST.MF -C .\jctemp . >NUL

The redirection to the bit bucket in the combine-step is strongly recommended, otherwise you will be overwhelmed by the amount of what will be written to standard output (jruby-complete-xxx.jar contains many, really many elements).

To run the example, execute:

java -jar .\jars\combined.jar

Note that it is not necessary here to specify the start class. Since we have only one jar file, the start class is derived from the manifest. In this case, the -jar option is used.