Debugging Perl

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

Tutorial

Configuring the Perl Debugger

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

  1. On the Edit menu, click Preferences.
  2. In the Preferences dialog box under Languages, click Perl. Komodo searches for Perl 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 Perl debugging session:

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

 

Debugging Perl Remotely

When debugging a Perl 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.

Perl remote debugging works on any system that can run the version of perl5db.pl distributed with Komodo. ActivePerl and most other distributions of Perl (version 5.6 or greater) will work.

Note: If you have the ActiveState Perl Development Kit (PDK) installed, follow the instructions for PDK users to disable the PDK debugger before continuing.

To debug Perl programs remotely:

Step One: Configure the Remote Machine

  1. Log in to the remote machine.


  2. Copy Komodo's perl debugger and its associated libraries to the remote machine by copying the entire dbgp/perllib sub-directory of the Komodo installation to the new machine, or download a package from the Komodo Remote Debugging page.

    Note: Do not copy perl5db.pl to the Perl "lib" directory on the remote machine, as this will overwrite the standard perl5db.pl file.


  3. On the remote machine, set the PERL5LIB environment variable to the location of the new perl5db.pl and its libraries. For example, if the remote machine is running Windows and perllib directory was copied to C:\misc\perllib, set the variable as follows:
    set PERL5LIB=C:\misc\perllib

    For example, if the remote machine is running Linux and perllib was copied to the /home/me/perl/komodo_perl_debugging directory, set the variable as follows:

    export PERL5LIB=/home/me/perl/komodo_perl_debugging/perllib
  4. On the remote machine, set the PERLDB_OPTS and DBGP_IDEKEY variables. This tells the Perl interpreter on the remote machine where to connect to Komodo or the DBGP Proxy and how to identify itself.

    	PERLDB_OPTS=RemotePort=<hostname>:<port>
    	DBGP_IDEKEY=<ide_key>
    
    • The port number must match the port number specified in Edit|Preferences|Debugger. Click Debug|Listener Status to check the current port.
    • Replace <hostname> with the name or IP address of the machine running Komodo.
    • If DBGP_IDEKEY is unset, the USER or USERNAME environment variable is used as the IDE Key.
    • The variable definitions must be on one line.

    For example:

    Windows 2000, NT, XP

    	set PERLDB_OPTS=RemotePort=127.0.0.1:9000
    	set DBGP_IDEKEY=jdoe
    

    Windows Me

    Use the MSCONFIG utility (Start|Run|MSCONFIG). Select the Environment tab, and create a new variable with the Variable Name of PERLDB_OPTS, and the Variable Value of RemotePort=127.0.0.1:9000.

    Unix Systems

    	export PERLDB_OPTS="RemotePort=127.0.0.1:9000"
    	export DBGP_IDEKEY="jdoe"
    

Step Two: Listen for Remote Debugger

In Komodo, on the Debug menu, click Listen for Remote Debugger.

Step Three: Start the Perl Program on the Remote Machine

Start the debugging process using the "-d" flag:

perl -d program_name.pl

A Perl Debug tab is displayed in Komodo.

Step Four: Debug the Perl Program using Komodo

Use 'F11' to Step In, or 'F5' (Go) to run to the first breakpoint. See Komodo Debugger Functions for full instructions on using Komodo's debugging functionality.

 

Disabling and Enabling the Perl Dev Kit (PDK) Debugger

If you have installed the ActiveState Perl Development Kit (PDK) on the remote machine, the system may be configured to use the PDK debugger when a Perl debug session (perl -d) is launched. To use Komodo's debugger, disable the PDK debugger on the remote machine first. If necessary, you can re-enable the PDK debugger on the remote machine later.

 

Disabling the PDK Debugger on the Remote Machine

To disable the PDK debugger on the remote machine, perform one of the following three procedures:

Option 1: (Windows and Unix)

At the command shell, enter the following command (depending on your operating system):

Windows

  set PERL5DB=BEGIN { require 'perl5db.pl'; }

Unix

  export PERL5DB="BEGIN { require 'perl5db.pl'; }"

To re-enable the PDK debugger, set the PERL5DB variable to an empty string.

Option 2: (Windows)

  1. Right-click the My Computer icon and select Properties.
  2. Click the Advanced tab.
  3. Click Environment Variables.
  4. In the System variables section, click New.
  5. Set the Variable Name field to PERL5DB.
  6. Set the Variable Value field to BEGIN { require 'perl5db.pl'}.
  7. Click OK three times to exit.

These changes take effect only in new DOS windows. To re-enable the PDK debugger, delete the PERL5DB variable.

Option 3: (Windows)

Change the registry setting for HKEY_LOCAL_MACHINE\SOFTWARE\Perl. Rename the variable PERL5DB to xPERL5DB.

Warning: This registry setting is semi-permanent and persists through machine restarts.

This change takes effect only in new DOS windows. To re-enable the PDK debugger, rename the xPERL5DB registry variable back to PERL5DB.

 

Configuring Perl for CGI Debugging

Debugging CGI programs on live production servers can seriously impair performance. We recommend using a test server for CGI debugging. Instructions for configuring Microsoft IIS and Apache (Unix) servers are shown below; for other web servers, use these examples and the web server software documentation as a guide for modifying the server environment.

The settings and paths listed are examples only. Substitute these with the specific paths, hostnames and port numbers of your server as necessary

 

Configuring a Microsoft IIS Web Server

  • Modify the Server's Environment Variables: Right-click the My Computer icon on the desktop, and select Properties. On the Advanced tab, click the Environment Variables button. Add the following items to the System Variables pane:
      PERL5LIB="C:\Program Files\Komodo-x.x\dbgp\perllib-5.x"
      PERLDB_OPTS=RemotePort=<hostname>:<port>
      DBGP_IDEKEY="<ide_key>"
    
  • Modify the Internet Information Services Configuration: Open the Internet Information Services manager. Select the Home Directories tab, and click the Configuration button. Add (or modify) an entry for Perl with the following characteristics:
      Extension = .pl
      Executable Path = c:\perl\bin\perl.exe -d "%s" %s
    
  • Restart the Server You must restart the server in order for the above changes to take effect.

 

Configuring an Apache Web Server

Ensure that Perl CGI scripts are operating correctly on the Apache server before proceeding with CGI debugger configuration. If you are running Apache under Windows, disable the ScriptInterpreterSource registry in the httpd.conf file. Use a stand-alone Perl interpreter for remote debugging.

  • Modify the httpd.conf file: The following values can be configured for a specific virtual host or all hosts. Add the following values in the appropriate sections:
      SetEnv PERL5LIB "C:\Program Files\Komodo-x.x\dbgp\perllib-5.x"
      SetEnv PERLDB_OPTS "RemotePort=<hostname>:<port>"
      SetEnv DBGP_IDEKEY "<ide_key>"
    
    Note: You must enable the mod_env Apache module (see httpd.apache.org/docs/mod/mod_env.html) for the SetEnv directive to function.

  • Modify the Perl Script: Add the "-d" flag to the "shebang" line:
      #!/perl/bin/perl -d
    

 

Starting a CGI Debugging Session

After the configuration is complete, debug programs as follows:

  • In Komodo, on the Debug menu, click Listen for Remote Debugger.
  • Using a web browser, access your CGI script.
  • A Perl Debug tab is displayed in Komodo. See Komodo Debugger Functions for full instructions on using Komodo's debugging functionality.