# Debugging Perl Komodo IDE only

Tutorial

- Perl Tutorial

Komodo can debug Perl programs locally or remotely, including debugging in CGI and mod_perl 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.

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.

## 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 or Step In to invoke the debugging session. See Komodo Debugger Functions for full instructions on using Komodo's debugging functionality.

### Startng a Komodo debugging session with `perl -d`

You may wish to use the Komodo debugger when working at the command line instead of using perl's built-in debugger. To do this, configure the environment variables described in Debugging Perl Remotely on your local machine using `localhost` as the hostname. Running the comand '`perl -d`' will start a debugging session in Komodo.

### Enabling "Break Now"

By default, the Break Now function is disabled for Perl debugging because some programs and modules (e.g. LWP and WWW::Mechanize) are not compatible with asynchronous breaking.

To enable Break Now, include the setting '`async=1`' in the `PERLDB_OPTS` environment variable. This can be done in Komodo's Environment preferences (Edit|Preferences...|Environment).

## 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. 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 standard "lib" directory of the Perl installation on the remote machine, as this will overwrite the standard perl5db.pl file.

2. 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 CGI debugging with IIS, you would also need to set the PERL5DB environment variable as follows:

       set PERL5DB=BEGIN { require q(C:/misc/perllib/perl5db.pl) }

   Note the forward slashes "/" in place of the regular Windows backslash path separators. This is optional for PERL5LIB, but necessary for PERL5DB.

   Another example: If the remote machine is running Linux or Mac OS X 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

3. 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`.

   Linux and Mac OS X Systems

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

   Note: As with local debugging, the Break Now function is disabled by default. To enable this button and functionality, add the option '`async=1`' to the `PERLDB_OPTS` environment variable. For example, on Windows:

       set PERLDB_OPTS=RemotePort=127.0.0.1:9000 async=1

Step Two: Listen for Debugger Connections

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

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.

Note: For Komodo to open an editable copy of the file, a Mapped URI must be created to link the file on the remote filesystem with the URI Komodo receives from the remote debugger.

Step Four: Debug the Perl Program using Komodo

Click Step In, or Go/Continue 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 procedures:

Option 1:

At the command shell, enter the following command:

Windows

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

Linux

    export PERLDB_OPTS=

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

Option 2: (Windows)

1. Open System Properties:
2. - On Windows 9x/NT/2000, right-click the My Computer icon and select Properties.
   - On Windows XP, click Start | Control Panel | System
   - - Click the Advanced tab.
     - Click Environment Variables.
     - In the System variables section, click New.
     - Set the Variable Name field to `PERL5DB`.
     - Set the Variable Value field to `BEGIN { require 'perl5db.pl'}`.
     - Select the `PERLDB_OPTS` variable, click Edit.
     - Delete the contents of the Variable Value field.
     - Click OK three times to exit.

These changes take effect in new Command Prompt windows. To re-enable the PDK debugger, delete the `PERL5DB` variable, and change the `PERLDB_OPTS` variable back to its original value.

## 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 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\ActiveState Komodo x.x\lib\support\dbgp\perllib
      PERL5DB=BEGIN { require q(C:/Program Files/ActiveState Komodo x.x/lib/support/dbgp/perllib/perl5db.pl) }
      PERLDB_OPTS=RemotePort=<hostname>:<port>
      DBGP_IDEKEY="<ide_key>"

  Note: The path for the PERL5LIB directory shown above is the correct path in a default installation. That path must be changed if you have installed Komodo in a different location. Forward slashes, "/", are used in place of the normal Windows path separator, "\", in the PERL5DB environment variable.
- Modify the Internet Information Services Configuration: A "-d" option must be added to the Executable Path for the Perl CGI script mapping.
- - IIS 4 and 5:
    1. Open the Internet Information Services manager.
    2. Select one web site or the entire Web Sites node as desired.
    3. Click Action|Properties
    4. On the Home Directory tab, click the Configuration button.
    5. Add (or modify) an entry for Perl with the following characteristics:

           Extension = .pl
           Executable Path = c:\perl\bin\perl.exe -d "%s" %s

  - IIS 6:
    1. Open the Internet Information Services manager.
    2. Select the Web Service Extensions node.
    3. Add (or modify) the Web Service Extension for Perl CGI as above.
  - IIS 7:
    1. Open the Internet Information Services manager.
    2. Select the level at which you want the debugger configuration applied (e.g. at the host level for a specific website).
    3. In the center pane in the IIS section, double-click Handler Mappings
    4. Add (or modify) an entry for Perl CGI (ActivePerl adds one called "Perl CGI for .pl"). For example:
       - Request path: *.pl
       - Executable: C:\Perl\bin\perl.exe -d "%s" %s
- Reboot: The system must be rebooted for the changes to take effect. Environment variables are not updated by restarting the IIS service.

### 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\ActiveState Komodo x.x\lib\support\dbgp\perllib"
      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 Debugger Connections.
- 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.

## Debugging mod_perl

Debugging mod_perl handlers is similar to debugging any Perl program remotely (see Debugging Perl Remotely to familiarize yourself with the terminology). Debugging mod_perl is different in that you'll typically invoke the code indirectly with a web browser, and that the Perl code is running inside an Apache web server.

To configure Komodo debugging in mod_perl:

1. Copy the entire dbgp/perllib sub-directory of the Komodo installation to a convenient directory on the server, or download and unpack the Perl Remote Debugging package from the Komodo Remote Debugging page. If you are running Apache on your local workstation, you can use Komodo's copy directly (e.g. <Komodo-install-dir>/lib/support/dbgp/perllib ) for the following steps. Note: Do not copy perl5db.pl to the standard "lib" directory of the Perl installation on the remote machine, as this will overwrite the standard perl5db.pl file.
3. In the directory containing perl5db.pl, create a new directory called Apache. For example:

       $ cd Komodo/lib/support/dbgp/perllib
       $ mkdir Apache

4. Create a symlink or shortcut to perl5db.pl within the new Apache directory. For example:

       $ cd Apache
       $ ln -s ../perl5db.pl .

5. Install the Apache::DB perl module on the server:

       $ cpan Apache::DB

6. Add the following snippet to your httpd.conf file (replace "/path/to/dbgp/perllib" with the full path to the directory containing perl5db.pl):

       <Perl>
         use ModPerl::Registry;
         use lib qw(/path/to/dbgp/perllib);
         $ENV{PERLDB_OPTS} = "RemotePort=localhost:9000 LogFile=stderr";
         use Apache::DB ();
         Apache::DB->init;
       </Perl>

   Make sure that `RemotePort` is set to the hostname and port Komodo using to listen for debugger connections (see the PERLDB_OPTS setting in the "Configure the Remote Machine" section of Debugging Perl Remotely).

7. You will probably already have a `<Location>` section in httpd.conf (or apache.conf) for your perl scripts. Add the following line to that section:

       PerlFixupHandler Apache::DB

   For example:

       <Location /perl-bin>
         SetHandler perl-script
         PerlHandler ModPerl::Registry
         Options +ExecCGI
         PerlOptions +ParseHeaders
         PerlFixupHandler Apache::DB
       </Location>

8. Restart Apache in debug mode (e.g. `apache -X`), and open the page you wish to debug in a browser.