Because OpenVox Server executes both Clojure and Ruby code, approaches to debugging differ depending on which part of the application you’re interested in.

Debugging Clojure Code

If you are interested in debugging the web service layer or other parts of the app that are written in Clojure, there are lots of options available. The Clojure REPL is often the most useful tool, as it makes it very easy to interact with individual functions and namespaces.

If you are looking for more traditional debugging capabilities, such as defining breakpoints and stepping through the lines of your source code, there are many options. Just about any Java debugging tool will work to some degree, but Clojure-specific tools such as CDT and debug-repl will have better integration with your Clojure source files.

For a more full-featured IDE, Cursive is a great option. It’s built on IntelliJ IDEA, and provides a debug REPL that supports all of the same debugging features that are available in Java; breakpoints, evaluating expressions in the local scope when stopped at a breakpoint, visual navigation of the call stack across threads, etc.

Debugging Ruby Code

Debugging the Ruby code running in OpenVox Server can be a bit trickier, because Java and Clojure debugging tools will only take you into the JRuby interpreter source code, not into the Ruby code that it is processing. So, if you wish to debug the Ruby code directly, you’ll need to install gems and take advantage of their capabilities (not unlike how you would debug Ruby code in the MRI interpreter).

For more info on installing gems for OpenVox Server, see OpenVox Server and Gems.

Ruby REPL incompatible with Lein REPL

Please note that a REPL running in Ruby is incompatible with lein repl because JRuby will not receive data from standard input when running inside of lein repl. To use a ruby REPL during development run puppetserver from source with lein run rather than lein repl:

lein run --config ~/.puppetserver/puppetserver.conf

The lein run command will start the server in the foreground as normal. pry or ruby-debug will display an input prompt when the relevant statement is reached. Expect to see the normal lein run output and then the Ruby REPL will present itself as compared to lein repl which presents a prompt early in the process lifecycle. In this way the “ruby repl” is more of a breakpoint than a REPL in the Clojure sense.

ruby-debug

Installation

There are many gems available that provide various ways of debugging Ruby code depending on what version of Ruby and which Ruby interpreter you’re running. One of the most common gems is ruby-debug, and there is a JRuby-compatible version available. To install it for use in OpenVox Server, run:

sudo puppetserver gem install ruby-debug

Or, if you’re running puppetserver from source:

lein gem -c /path/to/puppetserver.conf install ruby-debug

Usage

After installing the gem, you can trigger the debugger by adding a line like this to any of the Ruby code that is run in OpenVox Server (including the OpenVox Ruby code):

require 'ruby-debug'; debugger

pry

Installation

Pry is another popular gem for introspecting Ruby code. It is compatible with JRuby. Install pry when running a packaged version of puppetserver using:

sudo puppetserver gem install pry --no-ri --no-rdoc

Or, if you’re running puppetserver from source:

$ lein gem -c ~/puppetserver/puppetserver.conf -- install pry \
  --no-ri --no-rdoc

Usage

puppetserver should be run in the foreground to make use of the pry repl. This involves stopping the background service and starting the server in the foreground with the puppet foreground subcommand:

sudo service puppetserver stop
sudo puppetserver foreground

After installing, you can add a line like this to the Ruby code:

require 'pry'; binding.pry

This will give you an advanced interactive REPL at the line of code where you’ve called pry.

There are many other gems that are useful for debugging, and a large percentage of them are compatible with JRuby. If you have a favorite that is not mentioned here please let us know, and we will consider adding it to this documentation!

Limitations

We are aware that some favorite gems/tools/features for ruby debugging don’t currently work with JRuby/OpenVox Server. (For example, some things like color syntax highlighting in Pry.) It’s important to us to make sure that the Ruby developer experience is not degraded for developers working via OpenVox Server, so, if you run into issues like this, please file an issue on our Bug Tracker, and we will see if it’s possible to add support for things that we’re missing. In many cases it might be a matter of simply submitting a patch to JRuby, or submitting a JRuby-compatibility patch for an existing gem, and we’re interested in trying to help with those sorts of things whenever possible.

Tracing Code Events

OpenVox Server can utilize JRuby’s standard facilities for tracing events during code execution. For more information on these techniques, see the Tracing Code Events page.