JRuby, win32ole, and Vagrant on Windows

Note: Our guest post today hails from community contributor Mitchell Hashimoto. Mitchell has two important Ruby projects you may have heard of: VirtualBox and Vagrant. Mitchell lives in Seattle and loves open source. He is also a member of our Open Source Software Community Grant Program.

COM plays an important role for developers wishing to interact with other applications on Windows systems. Ruby provides a standard library known as win32ole which, although poorly documented, does its job to allow Ruby developers to access COM resources on Windows. Vagrant uses this library to interact with VirtualBox on Windows systems, where VirtualBox does not export a C-level API like it’s unix counterparts.

Unfortunately, 64-bit Windows users have been unable to use applications written in Ruby which use @win32ole@ since Ruby can only be compiled as a 32-bit application and is therefore unable to communicate over the 64-bit COM bridge. In fact, since the creation of Vagrant almost a year ago, I’ve had to tell users on 64-bit Windows that support is “seemingly impossible” until Ruby compiles to 64-bits, which doesn’t appear to be soon.

Enter: JRuby

In preparation for the Zero to Rails 3 course, which used Vagrant to provide students with identical learning environments, Matt Reider realized that Vagrant needed to support 64-bit Windows, and recommended JRuby as a means to achieve this compatibility.

In 2010, JRuby received a near fully API compliant @win32ole@ implementation in the form of the jruby-win32ole gem. Because JRuby can run on a 64-bit JVM on Windows, this allowed Ruby applications to use COM interfaces on 64-bit Windows.

The steps to installing a 64-bit JVM are covered in the “64-bit Windows setup guide for Vagrant.

Installing a 64-bit JVM and JRuby on Windows

Although a @win32ole@ introduction or tutorial is outside the scope of this post, a brief guide to installing the JVM and JRuby on 64-bit Windows is helpful, especially since even finding the 64-bit JRE can be difficult.

• Download the JRE from the download page at Oracle. Be sure to select Windows x64 as the platform. This will download the 64-bit JRE.
• Download JRuby from the JRuby downloads page, making sure to download the EXE installer for x64 Windows.
• Run and complete the JRE installer.
• Run and complete the JRuby installer.

At this point, JRuby should be setup to run on the 64-bit JVM. You can verify this by opening a command prompt and typing @jruby -v@. The output should be similar to that below. The important point is that it is running on a “64-bit Server VM.”

jruby 1.5.6 (ruby 1.8.7 patchlevel 249) (2010-12-03 9cf97c3) (Java HotSpot(TM) 64-Bit Server VM 1.6.0_23) [amd64-java]

Note: JRuby currently only provides a JRuby+JRE installer for the 32-bit JRE. They are working on a 64-bit version but its not quite ready yet, but the manual steps above to install each part separately will achieve the same result.

Open Source at Work

After learning about the JRuby compatibility, I got to work on testing Vagrant on Windows. Through this testing, some API incompatibilities were found. It should be noted that the date at this point was around December 20, 2010, in the middle of the holidays. But the JRuby team, always dedicated to maintaining top compatibility, went above and beyond to fix the outstanding issues, allowing for a Vagrant release on December 21st. And that Vagrant release was the first release supporting 64-bit Windows.

During the few days that the work to make this happen was occurring, the communication between open source entities, despite Vagrant being minuscule in comparison to JRuby, was heartening and showed the strength of the open source system. There was respect on both sides for the issues found, and seeing the JRuby team’s dedication to fixing the discovered bugs only strengthened my resolve to finish up Windows support that much faster. I like to think that this feeling was reciprocated multiple times.

Current Status

Since releasing the 64-bit Windows compatible version of Vagrant, there have been more API incompatibilities found in @win32ole@ for JRuby, but I’m confident over the coming months JRuby will have a truly 100% API-compliant @win32ole@ implementation, and Vagrant will work flawlessly on 64-bit Windows.

But despite some problems found, Vagrant does now work on 64-bit Windows with the exception of a couple features, which are entirely optional. I recommend viewing the setup guide for Vagrant on 64-bit Windows for those interested.

Once again, a big thanks needs to go out to the JRuby team and Engine Yard for pushing to make this happen. They’ve not only bettered a small open source project, but the entire Ruby community in the process by opening @win32ole@ to the masses on 64-bit Windows.