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.
To specify which Perl interpreter Komodo uses to debug and run Perl programs:
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.
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.
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).
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
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.
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
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>
<hostname>
with the name or
IP address of the machine running Komodo.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.
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.
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)
PERL5DB
.BEGIN { require 'perl5db.pl'}
.PERLDB_OPTS
variable, click
Edit.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.
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
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.
Extension = .pl Executable Path = c:\perl\bin\perl.exe -d "%s" %s
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.
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.-d
" flag to the "shebang" line:
#!/perl/bin/perl -d
After the configuration is complete, debug programs as follows:
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:
$ cd Komodo/lib/support/dbgp/perllib $ mkdir Apache
$ cd Apache $ ln -s ../perl5db.pl .
$ cpan Apache::DB
<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).
<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>
apache -X
),
and open the page you wish to debug in a browser.