Q: The Max objects in my patch don't understand the output coming from my [mxj jruby] object

A: In most cases, you want to send a single "word" per argument to the outlet() (and out0, out1, etc) methods in your Ruby code. For example, if you want to add the option 'foo' to a umenu, instead of doing: out0 'append foo' You need to do this instead: out0 'append', 'foo' In general, I recommend forming the message you want inside the Max patcher with a message box. Then figure out how to get [mxj jruby] to send the exact same message from its outlet.

Q: How do I install gems?

A: I hope to have a much easier way to install gems in a future version. For now, you have to follow these steps:

0. Download and unpack the latest JRuby 1.6.x binary distribution from http://jruby.org/download
1. Go to JRuby's bin folder on the command line
2. Install your gem with the jgem command:
   ./jgem install <gem_name>
3. Add the gem to the LOAD_PATH

For that last step, you have a few options.

Simply add the absolute path to the gem's lib folder to the $LOAD_PATH:

 $: << '/Users/adam/jruby-1.6.2/lib/ruby/gems/1.8/gems/<gem_name>/lib'
 require '<gem_name>'

This is perhaps the easiest option, but it requires you to know the absolute path to every gem you want to use. Using absolute paths like this also makes your scripts less portable across machines.

See the file jruby_for_max.properties.example that came with JRuby for Max. It explains how to set jruby.home. As explained in the file, rename it to jruby_for_max.properties and put it on the Max search path (for example, you can put it in Max5/Cycling '74/java/lib, next to the jar files).

Then set jruby.home to your the location where you unpacked JRuby, for example:

 jruby.home = /Users/adam/jruby-1.6.2

Restart Max, and then you can load any gems you install with that JRuby like this:

 require 'rubygems'
 require '<gem_name>'

This is a good option if you plan on installing many gems.

Copy the gem's lib folder to a folder next to your Max patcher file (let's call that "relative_gem_lib_folder"). Then you can require it using a relative path:

 require '<relative_gem_lib_folder>/<gem_name>.rb'

This approach makes it easy to share your Max project with other people, because they won't need to worry about installing the gem. Basically, you are "vendoring" the gem, as is often done in Rails development.

The downside to this approach is you have to duplicate the gem's code for every Max patch that uses it.

Q: I can't get the nokogiri gem (or some other gem with native dependencies) to work!

A: Gems with native dependencies are unfortunately not supported. Luckily, some gems like nokogiri now have a pure Java version available (https://github.com/tenderlove/nokogiri/wiki/pure-java-nokogiri-for-jruby). By installing the pure Java version, you can use it with JRuby for Max.

Q: Why does my ruby script keep giving bogus errors after saving my ruby file when using the @autowatch feature?

A: There is currently a bug where if a message is sent to the object while @autowatch is reloading your code, it can get stuck in a bad state and nothing will work (I typically encounter this problem when having a metro banging the object quickly while using @autowatch). If this happens to you, stop input to the JRuby for Max object (e.g. by turning off the metros/transport or temporarily removing a patch cable), and then force the code to reload again.

I will try to fix this bug in an upcoming version.

Q: Ableton Live freezes or crashes during launch when I double click (in Finder or Windows Explorer) a Live set that uses JRuby for Max.

A: Live may not successfully open when you try to launch Live, Max, and JRuby for Max all at the same time. To avoid the problem, first launch Live, then open your Live set.

Q: I get periodic audio drop-outs when using JRuby for Max

A: Increase your audio buffer size in Live preferences to compensate for the overhead of running JRuby inside of Ableton Live. Also try to optimize your Ruby code to not create too many new objects or perform too many heavy operations in realtime. You can also get a faster processor ;)

Q: Tracks that use JRuby for Max are out of sync with my other tracks.

A: Use Live's track delay feature to compensate for any delay caused by JRuby (I'll try to provide more detailed tips on how to do this later, in the meantime RTFM and experiment to see what settings work best for your Live set)