Setting Up a JRuby Environment with Netbeans
Notes on setting up a development environment for JRuby and JRuby on Rails. You can add JRuby to any existing Java configuration, but the instructions here are for a complete environment. All of the required software for JRuby is open source and cross-platform, so may be freely installed and used wherever you need.
JRuby provides a set of libraries to enhance a Java platform with support for the Ruby programming language and the associated tools, such as the Rake task automation utility, the RubyGems package manager, and the Rails Web application framework. This allows developers to write standard Ruby code and use the Ruby tools, whilst running the results on any Java platform. JRuby also provides full access to Java code. As a result, JRuby applications may use all of the features of the Java platform itself, as well as those offered by other installed Java libraries on the system.
To run Java and JRuby applications simply requires a JRE (Java Runtime Environment), such as the Sun JRE. In order to develop Java and JRuby applications you need to install a JDK (Java Development Kit), which includes both a JRE and additional libraries. Most Java developers use suites such as Netbeans and Eclipse, which build on a JDK to provide a complete graphical development and testing environment.
You may run Java and JRuby applications on a Java applications server of your choice, including Glassfish, JBoss, and Apache Tomcat. JRuby supplies and uses the WEBrick Web server, which enables you to develop and test your Web applications without needing to install a separate product.
Although JRuby may be used with any current Java platforms, the instructions below use Sun Java products, which are easy to install, open source, actively developed, and have excellent support for JRuby.
Java and JRuby can work with any database that has a JDBC driver, which includes every mainstream database in use today. You may access a even wider range of databases with the JDBC-ODBC driver.
The JRuby on Rails version of Active Record includes a JDBC adapter alongside the database-specific Rails adapters, but this does not provide any special support for legacy schema in existing databases, beyond the standard features of Active Record.
Popular choices for SQL database storage with Java applications today include MySQL, PostgreSQL, Oracle, and Apache Derby, a compact open source database that is written in pure Java.
Unusually, Apache Derby may either be used as small set of libraries that work with local database files, or deployed as a separate network service. JRuby on Rails supports both Derby network database servers, and embedded Derby databases. In the latter case, Derby works in the same way as SQLite works with the standard distribution of Rails – databases are generated as required inside the application itself.
Sun Microsystems supply Derby as part of their JDK, as well as integrating it into the Glassfish applications server. For various reasons, Sun use the brand name Java DB for their builds of Apache Derby, and Netbeans refers to all versions of Derby as Java DB. The Apache Derby and Sun Java DB software are identical.
To setup a JRuby development environment with Netbeans, you need:
You may either use the Netbeans Ruby Pack, which includes JRuby by default, or install another edition and add the required plugins later thorough the built-in plugin manager. The only difference between the Netbeans editions is the initial set of plugins.
You do not need to install Ruby or JRuby separately. If you set the environment variables as explained below, you can run all of the Ruby and Rails tools supplied with JRuby from the command-line, as well as through the Netbeans interface. Currently, these utilities include:
The Ruby Gems package manager enables you to install any additional Ruby software that you need.
Netbeans will also work with existing Ruby or JRuby installations. If you have multiple Ruby installations, you can specify the installation that Netbeans should use either globally, or for each project.
Netbeans integrates with a number of version control systems, including Subversion and Mercurial. Mercurial has several advantages over older systems, not least of which is that it does not require a separate repository or server. This means that if you install a copy of Mercurial on to your system you can have full version control with any Netbeans project, simply by using the Versioning options in the menus.
Tip: If you will be sharing your project with others, consider excluding the nbproject subdirectory from version control. Always exclude any embedded databases from version control.
Sun offers Netbeans and their own JDK as a single combined download, as well as standard installers for their JRE and JDK:
http://java.sun.com/javase/downloads/index.jsp
If you want to use Java DB to provide databases for your applications, choose the Java DB component from the list of options when you install the Sun JDK.
The Windows version of Java DB automatically installs HTML and PDF versions of the documentation into the folder:
C:\Program Files\Sun\JavaDB\docs\For example, to read the HTML version the Getting Started guide, enter this URL in the address bar of your Web browser:
file:///C:/Program%20Files/Sun/JavaDB/docs/html/getstart/index.html
The Mercurial version control software is cross-platform, but the Mercurial project itself does not provide a ready-to-run package for Windows. At the time of writing, you can get a Windows installer for Mercurial from here:
http://mercurial.berkwood.com/
Netbeans automatically finds the version of Mercurial installed by the above package, although it will complain about a mismatched version the first time that you use a Mercurial function.
Finally, to use Java DB and JRuby utilities outside Netbeans, add the bin directories to your PATH environment variable, and set up new JAVA_HOME, JRUBY_HOME, and DERBY_HOME variables.
To do this, choose Start > Control Panel > System > Advanced > Environment Variables, find path in the System Variables list, and Edit it to add:
C:\Program Files\Java\jdk1.6.0_06\bin;
C:\Program Files\Netbeans 6.1\ruby2\jruby-1.1\bin;
C:\Program Files\Sun\JavaDB\binSubstitute jdk1.6.0_06 with the correct directory name for your JDK version.
Items in the PATH must be separated by semi-colons.
On the same screen, set three New variables.
A DERBY_HOME environment variable as:
C:\Program Files\Sun\JavaDBA JAVA_HOME environment variable as:
C:\Program Files\Java\jdk1.6.0_06And a JRUBY_HOME variable as:
C:\Program Files\NetBeans 6.1\ruby2\jruby-1.1These settings will automatically apply to every new command prompt window.
If you need to run MySQL or PostgreSQL databases on your development system, simply visit the appropriate project Web site for the latest Windows installer, and use the program provided.
Sun now collaborates with other vendors and the community on a fully open source JDK (the OpenJDK). All of main Linux distributions provide packages for the OpenJDK. Although the OpenJDK itself does not include Java DB, you can run Java DB or another version of Derby with it.
On the latest versions of the main Linux distributions, we can set up a complete development environment in three steps:
To install the OpenJDK, Java DB, and Mercurial on an Ubuntu system, enter this in a terminal window (all on one line):
sudo apt-get install openjdk-6-jdk mercurial
sun-javadb-client sun-javadb-core sun-javadb-doc Note that the Ubuntu repositories include other, older Java DB packages. Use the sun-javadb-* packages with the OpenJDK, not the sun-java6-javadb or sunwderby packages.
The Ubuntu package sun-javadb-doc installs documentation to the directory /usr/share/doc/javadb/. Enter this URL in the address bar of your Web browser to see the documentation start page:
file:///usr/share/doc/javadb/index.html
Whichever Linux distribution you use, you should download a copy of the latest version of Netbeans from the Netbeans Web site. The version provided by your Linux distribution is likely to be a previous release. Simply download the Linux version of the Netbeans Ruby pack installer, then make the file executable, and run it:
chmod 700 netbeans-6.1-ruby-linux.sh
sudo ./netbeans-6.1-ruby-linux.shThe name of the configuration file used for the shell (command-line environment) varies slightly between distributions. On Ubuntu and Debian systems, add these lines to the end of the .bashrc file in your home directory:
export PATH=$PATH:/usr/local/netbeans-6.1/ruby2/jruby-1.1/bin:/usr/share/javadb/bin
export DERBY_HOME=/usr/share/javadb
export JRUBY_HOME=/usr/local/netbeans-6.1/ruby2/jruby-1.1These settings will automatically apply to every new terminal window.
If you need MySQL or PostgreSQL on your development system, install these through the package manager for your distribution as normal. Due to the separate releases schedules of the different projects, you may find that your distribution supplies the previous version of your preferred database, but third-parties will offer current packages.
You should set up you own personal gems directory and install any extra gems there. On Netbeans 6.1, choose Tools > Options > Ruby Platforms, and select Add, next to Gem Path. Specify a new directory within your home directory, e.g. /home/me/.gem. Choose Yes at the dialog box for Netbeans to prepare the new directory. Select Close.
To manage the gems in your personal gems directory from Netbeans, choose Tools > Ruby Gems. When the update completes, select the Browse option next to Gem Home, and specify your personal gems directory.
To manage these gems with the gem command-line utility, specify the directory path with the -i option:
jruby -S gem install activerecord-jdbcderby-adapter --include-dependencies
-i /home/me/.gemThe JRuby documentation recommends that utilities should always be run with jruby -S, rather than being invoked directly.
Unless your user account has write access to the gems directory within the Netbeans installation, any attempt to install or update the shared gems within the Netbeans gems directory will fail. For example, if you run gem update without specifying the name of a gem then the gem utility will automatically attempt to upgrade all of the installed gems on the system, including the shared gem packages, and the process will fail.
JRuby on Rails is identical to the standard distribution of Rails in almost every respect. The three major differences are the additional JDBC adapter, the support for Java applications servers, and the option to use Apache Derby (Java DB).
To use embedded Derby databases in your JRuby on Rails applications, you must first install the specific Derby adapter for Active Record. Install activerecord-jdbcderby-adapter to your own gems directory with Netbeans, or with the gem command-line utility:
jruby -S gem install activerecord-jdbcderby-adapter --include-dependencies
-i /home/me/.gemTo setup a new Ruby on Rails project with JRuby in Netbeans, choose File > New Project, and select Ruby on Rails Application. If you may be deploying your application to a Java applications server later, tick the box to Add Rake Targets to Support App Server Deployment. To use Derby databases, at the Database Configuration screen, choose Specify Database Information Directly, and select javadb from the drop-down list. To use embedded Derby databases, do not fill in any of the other database settings. Only use the other settings if you wish to access databases that are hosted by a separate Derby server.
Once you have created a Rails application, right-click on the root of your Rails application to access the standard Rails functions, such as Generate and the Rails Console.
Netbeans also has an interface for working with Rails application plugins. To use this, right-click on the root of your Rails application, select Rails Plugins…, and wait a moment for the process to complete. By default, this checks the Rails Subversion repository, and you will find that many popular plugins are hosted on other sites.
The Netbeans platform consists of a core, and number of plugins. Most functionality is implemented as a plugin, and so you may add or update features as you require, by selecting Tools > Plugins, and choosing what you need. By default, new Netbeans plugins are installed in the .netbeans directory within your home directory.
Netbeans also incorporates an upgrade system for itself. This means that if your account has administrative privileges you may upgrade an entire Netbeans installation using the built-in update facility. For security, most Linux distributions provide unprivileged accounts, and so this feature will not work with the standard Netbeans configuration.
To update your copy of Netbeans with the built-in update system, choose Help > Check For Updates.
For Netbeans tutorials and community support, visit the project Website:
The Wiki on the JRuby site provides useful notes and links for JRuby and JRuby on Rails:
For more on Mercurial, visit the project Website:
http://www.selenic.com/mercurial/
The front page of the site provides links for the HTML and PDF versions of Distributed Revision Control with Mercurial, a complete book on Mercurial for developers and administrators.
All original content is © 2010, Stuart Ellis.
This material is provided under the Creative Commons Attribution-Share Alike 3.0 License.