Debugging Ruby

Komodo can debug Ruby programs locally or remotely. The instructions below describe how to configure Komodo and Ruby for debugging. For general information about using the Komodo debugger, see Komodo Debugger Functions.

Debugger commands can be accessed from the Debug menu, by shortcut keys, or from the Debug Toolbar. For a summary of debugger commands, see the Debugger Command List.

Tutorial

Configuring the Ruby Debugger

To specify which Ruby interpreter Komodo uses to debug and run Perl programs:

  1. Select Edit|Preferences (OS X: Komodo|Preferences).
  2. In the Preferences dialog box under Languages, click Ruby. Komodo searches for Ruby interpreters on your system and displays them in the drop-down list.
  3. If the preferred interpreter is in this list, click to select it. If not, click Browse to locate it.
  4. Click OK.

To start a local Ruby debugging session:

On the Debug menu or Debug Toolbar, click Go/Continue or Step In to invoke the debugging session. See Komodo Debugger Functions for full instructions on using Komodo's debugging functionality.

 

Debugging Ruby Remotely

When debugging a Ruby program remotely, the program is executed on the remote system and the debug output is sent to Komodo. Komodo controls the debugging session (e.g. stepping and breakpoints) once the session starts on the remote system.

  1. Install the Ruby debugger application and associated files on the remote machine. All of these files are included in /lib/support/dbgp/rubylib beneath the Komodo installation directory (/Contents/SharedSupport/dbgp/rubylib on ac OS X). Copy rdbgp.rb and the contents of the DB directory to a convenient location on the remote machine. Note:Some of these files are shared library files (.so), which are platform specific. If your Komodo installation is on a different platform, download the Komodo-PythonRemoteDebugging package for the appropriate platform and Komodo version from the Komodo Remote Debugging page.
  2. Start Komodo on the local machine.
  3. On the remote machine, set the dbgdir variable to specify the location of the remote mahcine directory where you copied rdbgp.rb and its associated files.

    Windows

        set dbgdir=<Path_To_rbdbgp.rb>
    

    Linux/Mac OS X

        dbgdir=<Path_To_rbdbgp.rb>
    
  4. On the remote machine, set the RUBYDB_OPTS variable his supplies the Ruby interpreter with the information that is necessary to connect to the Komodo appliction running on the local machine.

    Windows

        set RUBYDB_OPTS=remoteport=<ServerName>:<Port>
        set RUBYOPT=
    

    Linux/Mac OS X

        export RUBYDB_OPTS=remoteport=<Server_Name>:<Port>
        unset RUBYOPT
    
  5. Start the debugger and open the program that you want to debug.
  6. Windows

        ruby -I%dbgdir% -r %dbgdir%\rdbgp.rb <Program_To_Debug.rb>
    

    Linux/Mac OS X

        ruby -I"$dbgdir" -r "$dbgdir"/rdbgp.rb <Program_To_Debug.rb>
    
    The remote file will open in Komodo with the debugger stopped at the first line of executable code. A yellow arrow indicates the current position. You can now set breakpoints in this file, step through, and use other Komodo debugging features as if it were a local file. However, you cannot modify the file.

 

Dealing With Rubygems

Rubygems is the most commonly used framework for dealing with third-party Ruby modules. It helps Ruby programmers quickly and easily download new modules, grab all dependencies, deal with side-by-side installations of different versions, and load the appropriate versions of modules at runtime. It doesn't ship with standard Ruby (version 1.8.4 as of this writing), but will soon, given all that functionality.

Rubygems is included with the One-Click Installer (available at http://rubyforge.org/projects/rubyinstaller/),and is the easiest way to install Ruby on a Windows system. It has the side effect of adding the environment variable RUBYOPT=rubygems to the list of system variables (accessible via right-clicking My Computer, choosing Properties|Advanced|Environment Variables). This is usually correct behavior, as it automatically enables all your Ruby scripts to use rubygems to find modules. However it will cause the Ruby debugger to always step into a file called ubygems.rb when debugging. (The flag is shorthand for -r ubygems.rb, which is why it loads a file called ubygems.rb, a simple wrapper around rubygems.rb.

There are three approaches to dealing with this problem:

  1. Set a breakpoint on the first line of the main file, and start the debugger with the Go command instead of the Step Into command.
  2. Use the environment tab in Preferences to set the RUBYOPT environment variable to either rubygems or the empty string.
  3. When you start the debugger, choose the Environment tab in the Debugging Options dialog box, add a new entry for RUBYOPT in the User Environment Variables box, and leave its value empty.

 

Debugging Rails Applications

Ruby on Rails applications can be debugged locally or remotely just like any other ruby application. However, since much of the Rails framework has to run within the debugger, the process is normally slower than with a standalone ruby program.

Local Rails Debugging

  1. Load the pertinent app or controllers files in Komodo.
  2. Set breakpoints in the methods where you want to stop.
  3. Load the script/server file that you would normally run from the command-line.
  4. In the Debugging Configuration dialog, set the Directory field to the top-level directory containing the apps folder.
  5. With the script/server file active, start the debugger.

Remote Rails Debugging

  1. Follow the steps described above in Debugging Ruby Remotely to install the ruby debbugger and set the environment variables dbgdir and RUBYDB_OPTS.
  2. Start the Rails script/server with the ruby debugger from the top-level directory containing the apps folder:

    Windows

        ruby -I%dbgdir% -r %dbgdir%\rdbgp.rb script/server
    

    Linux/Mac OS X

        ruby -I"$dbgdir" -r "$dbgdir"/rdbgp.rb script/server
    
    The remote files will open in Komodo with the debugger stopped at the first line of executable code. A yellow arrow indicates the current position. You can now set breakpoints in this file, step through, and use other Komodo debugging features as if it were a local file. However, you cannot modify the file.