JRuby

abevoelker edited this page Jan 21, 2012 · 2 revisions

Contribute To the JRuby Effort

Setting up the Test Environment

Setting up JRuby in your environment should not be difficult. This page contains sample instructions for installing JRuby, although you are advised to read the JRuby wiki for more comprehensive information.

You have a choice of downloading either the source or binary distributions (see download page). Provided you already have the JDK and Ant on your computer, building from source should take less than the time it takes to make a cup of coffee.

To install JRuby for all users on your system, these instructions assume /usr/local/jruby as the install destination. If you just want to install for your user account, replace with /Users/yourname/jruby as appropriate.

From Source

cd /usr/local
sudo wget http://dist.codehaus.org/jruby/1.3.1/jruby-src-1.3.1.tar.gz
sudo tar xvfz jruby-src-1.3.1.tar.gz
sudo rm jruby-src-1.3.1.tar.gz 
sudo chown -R yourname:admin jruby-1.3.1/
sudo ln -s jruby-1.3.1 jruby
cd jruby
ant

Other ways of installing JRuby

  • If you're using Windows, then a binary Installer is now available.
  • Binaries are also available for Linux and Mac OS X. Just unzip/untar and ensure your PATH is correctly configured.
  • You can also use the excellent "Ruby Version Manager":http://rvm.beginrescueend.com/ as follows
rvm install jruby; rvm use jruby
rvm install jruby-head; rvm use jruby-head

Configure your PATH

Then, you'll need to ensure your PATH is set up correctly.

vim -w ~/.bash_profile
export JRUBY_HOME=/usr/local/jruby
PATH=$PATH:$JRUBY_HOME/bin
export PATH

It's also a good idea to ensure the JAVA_HOME environment variable is properly set. Examples: Mac OS 10.5 Leopard Default Java/JDK 5

Also make sure the JDK and javac are in the PATH.

http://java.sun.com/javase/6/webnotes/install/jdk/install-windows.html

If you get the "not recognized as an internal or external command" error, add the path to the ruby bin directory(e.g. c:\ruby\bin) to the system PATH environment variable(Control Panel -> System -> Advanced System Settings).

export JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Versions/1.5/Home

Mac OS 10.5 with SoyLatte JDK 6

export JAVA_HOME=/usr/local/soylatte

Ubuntu 8.10 with Java/JDK 6

export JAVA_HOME=/usr/lib/jvm/java-6-sun

Test that it works:

$ jruby --version
jruby 1.3.1 (ruby 1.8.6p287) (2009-07-10 6586) (Java HotSpot(TM) Client VM 1.6.0_15) [i386-java]

Install Rake, full JRuby-OpenSSL support, RSpec and ZenTest:

jruby -S gem update --system
jruby -S gem install rake
jruby -S gem install jruby-openssl
jruby -S gem install rspec ZenTest

Optionally, install the buildr gem:

jruby -S gem install buildr

Create Test Databases

If you are going to run the spec tests several databases require manual creation of the database used when running the spec tests.

Database vendor test database name
MySQL do_test
Postgresql do_test

MySQL

mysql -uroot -p -e "create database do_test;"
mysql -uroot -p -e "GRANT ALL PRIVILEGES ON do_test.* TO 'dotester'@'localhost' IDENTIFIED BY 'do';"

Later when you run the tests you will need to specify the MySQL user and password:

DO_MYSQL_USER=dotester DO_MYSQL_PASS=do jruby -S rake spec

PostgreSQL

createdb -O do_test

Postgresql will use the logged in user by default and if you are the user who installed PostgreSQL you will not need to specify a username and password when running these tests.

Install JDBC Drivers

The ActiveRecord-JDBC project provides Gem wrappers for the various JDBC Driver JARs provided by database vendors. You'll need to install the appropriate one, depending on the database you wish to use.

sudo jruby -S gem install jdbc-[DBNAME]
jdbc-derby
jdbc-h2
jdbc-hsqldb
jdbc-mysql
jdbc-postgres
jdbc-sqlite3

Compiling DO

Then, go to the do/data_objects project:

cd data_objects/
jruby -S rake spec
jruby -S rake install

Then, compile the JDBC support:

cd ../do_jdbc
jruby -S rake compile

Testing against DO Specs

Go to the driver you wish to test:

cd ../do_mysql
jruby -S rake compile

and you should be able to run the specs:

jruby -S rake spec

For drivers that connect to client/server databases (as opposed to embedded/single-file databases), you should be able to override the connection parameters using the following environment variables:

DO_MYSQL_USER
DO_MYSQL_PASS
DO_MYSQL_HOST
DO_MYSQL_PORT
DO_MYSQL_DATABASE
DO_POSTGRES_USER
DO_POSTGRES_PASS
DO_POSTGRES_HOST
DO_POSTGRES_PORT
DO_POSTGRES_DATABASE

So, to run the specs with a different MySQL password:

DO_MYSQL_PASS=foobar jruby -S rake spec

Or, PostgreSQL on a different server:

DO_POSTGRES_HOST=ubuntu-box jruby -S rake spec

You can also override the entire connection string / URI with the following environment variables:

DO_MYSQL_SPEC_URI
DO_POSTGRES_SPEC_URI

Testing against DataMapper Specs

You can also attempt to run the DataMapper spec suite against DO. You'll want to test against the 'next' branch of DataMapper, so you'll need to clone the DataMapper git repository (http://github.com/datamapper/).

You'll then need DO, do_jdbc and the driver you wish to test against in your JRuby gems directory.

Go to the do/data_objects project and install:

cd data_objects/
jruby -S rake install

Then, compile and install the JDBC support:

cd ../do_jdbc
jruby -S rake compile
jruby -S rake install

Pick a driver and install:

cd ../do_mysql
jruby -S rake install
cd ../do_postgres
jruby -S rake install
cd ../do_sqlite3
jruby -S rake install

Go to your DataMapper clone and ensure you're on the next branch

cd ~/Code/dm-core
git branch --track next origin/next
git co next

Pick an adapter and run the specs as follows:

ADAPTERS=mysql jruby -S rake spec
ADAPTERS=sqlite3 jruby -S rake spec
ADAPTERS=postgres jruby -S rake spec

Override the connection strings if necessary using the following environment variables:

#   MYSQL_SPEC_URI
#   POSTGRES_SPEC_URI
#   SQLITE3_SPEC_URI

Debugging

Its possible to execute the specs and debug with the Java debugger:

Set the environment variable DO_JAVA_DEBUG to true, to ensure that debugging symbols are enabled during compilation.

Set breakpoints in the do_jdbc Java code in NetBeans or another IDE. Run the specs for the driver you are interested in, with the debugger:

jruby -J-Xdebug -J-Xrunjdwp:transport=dt_socket,address=9009,server=y,suspend=y -S rake spec

Back in NetBeans, click Debug > Attach Debugger…. Set the port to 9009, and accept the other defaults. You should now be able to step-through, over and into code. Where to Start

if you're interested in contributing, check out the todo.

Memory Profiling

First calibrate: Profile | Advanced Commands | Run Profiler Calibration

Then Profile > Attach Profiler...

Profile as an external application. The wizard will present you with a command option which you will need to prepend to attach the profiler:

jruby -J-agentpath:/var/folders/c0/c0jbFAI0FUuydYxeYJcG-++++TI/-Tmp-/NBProfiler5944349626242268481.link/deployed/jdk16/mac/libprofilerinterface.jnilib=/var/folders/c0/c0jbFAI0FUuydYxeYJcG-++++TI/-Tmp-/NBProfiler5944349626242268481.link,5140 -S rake spec

See http://netbeans.org/kb/articles/nb-profiler-uncoveringleaks_pt1.html