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:
- On the Edit menu, click Preferences.
- 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.
- If the preferred interpreter is in this list, click to select it. If not,
click Browse to locate it.
- 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.
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
- Log in to 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.
- 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 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
- 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 and Mac OS X 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
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 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)
- Right-click the My Computer icon and select Properties.
- 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'} .
- 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 .
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
- 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"
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. Also, the debugger doesn't seem to be able to find the libraries
if any directories in the path contain spaces. You should copy the perllib directory to
another location in which there are no spaces in the path to overcome this problem
and use that path in the PERL5LIB system variable described above.
- 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.
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.
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.
Debugging mod_perl handlers is similar to debugging any
Perl program remotely. For this reason, it is recommended that you first read
on debugging Perl remotely to familiarize
yourself with the terminology. Debugging mod_perl is different in that
you'll typically invoke the code indirectly, usually with a
web browser, and that the Perl code is running inside an Apache
web server. Successfully debugging mod_perl code is a matter
of correctly setting a few environment variables.
Apache can be running on the same machine as Komodo, or a different
one. These instructions assume that you'll be running a separate
instance of Apache on the development machine.
Requirements for Debugging mod_perl
- If Apache is not running on the machine where Komodo is
installed, put Komodo's Perl debugger and its associated
libraries in a convenient directory. Copy the entire
dbgp/perllib sub-directory of the Komodo installation to
the server 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.
- Make sure you have installed
Apache::DB from CPAN (version
0.10 or better). If you don't have root access to the standard
Perl library directories, you can place it in the same directory as
Komodo's Perl debugger; the PERL5LIB variable will point to
this location.
- Create a new window you intend to start the Apache server in,
and set the Komodo debugging environment variables in it. This procedure assumes
that the Komodo debugger files are in
/home/me/perl/komodo_perl_debugging on Unix and C:\misc\perllib
on Linux.
- Continue directions at the appropriate section for configuring
mod_perl for debugging on either Windows
or Linux and Mac OS X.
Perform the following procedures to configure and execute mod_perl debugging on Windows.
- Set the following environment variables in the command window from which
Apache will be launched (do not place quotes around the values, or the quote
characters will be picked up as part of the variables' values):
set PERL5DB=BEGIN { require q(c:/misc/perllib/perl5db.pl) }
set PERL5LIB=c:/misc/perllib;c:/perl/lib;c:/perl/site/lib
set PERLDB_OPTS=RemotePort=localhost:2345
Note: For verbose logging output from the debugger,
add a LogFile directive to the PERLDB_OPTS variable.
set PERLDB_OPTS=RemotePort=localhost:2345 LogFile=stderr
- Set up the configuration file mp1.conf (with Apache installed in
C:/apps/apache-1-3-33) as follows:
ServerType standalone
ServerRoot "C:/apps/apache-1-3-33/Apache"
PidFile logs/httpd.pid
Timeout 300
KeepAlive On
MaxKeepAliveRequests 100
KeepAliveTimeout 15
MaxRequestsPerChild 0
ThreadsPerChild 50
LoadModule perl_module modules/mod_perl.so
ClearModuleList
AddModule mod_env.c
AddModule mod_log_config.c
AddModule mod_mime.c
AddModule mod_negotiation.c
AddModule mod_include.c
AddModule mod_autoindex.c
AddModule mod_dir.c
AddModule mod_isapi.c
AddModule mod_cgi.c
AddModule mod_asis.c
AddModule mod_imap.c
AddModule mod_actions.c
AddModule mod_userdir.c
AddModule mod_alias.c
AddModule mod_access.c
AddModule mod_auth.c
AddModule mod_so.c
AddModule mod_setenvif.c
AddModule mod_perl.c
Port 80
ServerAdmin komodo-joe@example.com
ServerName server.example.com
DocumentRoot "C:/apps/apache-1-3-33/Apache/htdocs/mp1"
<Directory />
Options FollowSymLinks
AllowOverride None
</Directory>
<Directory "C:/apps/apache-1-3-33/Apache/htdocs/mp1">
Options Indexes FollowSymLinks MultiViews
AllowOverride None
Order allow,deny
Allow from all
</Directory>
ErrorLog logs/error.log
LogLevel warn
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined
LogFormat "%h %l %u %t \"%r\" %>s %b" common
LogFormat "%{Referer}i -> %U" referer
LogFormat "%{User-agent}i" agent
<IfModule mod_alias.c>
ScriptAlias /cgi-bin/ "C:/apps/apache-1-3-33/Apache/cgi-bin/"
<Directory "C:/apps/apache-1-3-33/Apache/cgi-bin">
AllowOverride None
Options None
Order allow,deny
Allow from all
</Directory>
</IfModule>
# mod_perl setup
Alias /mod_perl/ "c:/apps/apache-1-3-33/Apache/mod_perl/"
<Location /mod_perl>
SetHandler perl-script
PerlHandler Apache::Registry
Options +ExecCGI
allow from all
PerlSendHeader On
</Location>
# mod_perl debugging setup
<IfDefine PERLDB>
<Perl>
use Apache::DB ();
Apache::DB->init;
</Perl>
<Location />
PerlFixupHandler Apache::DB
</Location>
</IfDefine>
<Location /perl-status>
PerlHandler Apache::Status
SetHandler perl-script
</Location>
For this example, there are two files (test.pl and printenv.pl)
in the mod_perl directory (c:/apps/apache-1-3-33/Apache/mod_perl/):
test.pl :
use strict;
our $counter;
$counter = defined $counter ? $counter + 1 : 0;
my $r = shift;
$r->send_http_header('text/plain');
$r->print("" . localtime(time()) . ", counter=$counter\n");
print "This is written with a plain print stmt -- the others use \$r->print\n";
printenv.pl :
#!c:/perl/bin/perl.exe
## printenv.pl -- demo CGI program which just prints its environment -*- perl -*-
##
use strict;
print "Content-type: text/html\n\n";
print "<HTML><BODY><H3>Environment variables</H3>";
$a = '' . localtime(time());
print "<h3>Date: $a</h3>\n";
print "<UL>";
foreach (sort keys %ENV) {
my $val = $ENV{$_};
$val =~ s|\n|\\n|g;
$val =~ s|"|\\"|g;
print "<LI>$_ = \"${val}\"</LI>\n";
}
print "</UL></BODY></HTML>";
You will start by debugging a standard CGI Perl script, which is running with
Apache::Registry to benefit from mod_perl 's code-caching.
Complete the following steps to debug test.pl. Use the same procedure
to debug printenv.pl.
Navigate to the directory containing Apache.exe, and start the
server with this command, ensuring that no other server is running on the same port:
Apache.exe -f conf/mp1.conf -X -D PERLDB
- Start Komodo, listening on port 2345.
- Load test.pl with this URL in the web browser's address bar:
http://localhost/mod_perl/test.pl
The Komodo debugger stops at the first line of the handler sub
in Apache/Registry.pm.
- Step into the code. Do this by finding the
eval line that evaluates
the compiled script code and setting a breakpoint there. It will look similar
to this:
eval { &{$cv}($r, @_) } if $r->seqno;
- Click Go/Continue to continue to that point, and then
click Step In three times. Notice that instead of stepping into
test.pl, Komodo has stepped into a similar buffer with a Perl "(eval...)"
name. This is the code that
Apache::Registry generates from the original
script and then runs. You can set breakpoints in this code, and examine and modify
variables just as if you were debugging a standalone Perl file. The difference is
that, when you reach the end of the outer handler, you must instruct Komodo to
stop debugging.
- Click the Stop button. When you try debugging test.pl
again by, for example, refreshing the browser, Komodo will stop at a line in
IO::Handle.pm. This is a bug.
- Click Go/Continue, followed by Stop, and
refresh the browser again. Komodo returns to the
Apache::Registry
handler.
- Click Go/Continue to move to the breakpoint where your own
handler is entered, and step into it.The
$counter variable value is
preserved from the previous call, and is incremented from 1 to 2. An entry was
added to debug a mod_perl handler outside Apache::Registry . This time
enter http://localhost/perl-status in the browser address bar. Barring
an extra step through IO::Handle::DESTROY (that same bug), the debugger
stops at the first line of the handler sub in Apache::Status .
Again, you can continue to step through, examine and modify variables as in any
other debug session.
If the debugger doesn't launch, add logging to the session by adding something
like LogFile=stderr with this setting:
set PERLDB_OPTS=RemotePort=localhost:2345 LogFile=stderr
These strings will be written to Apache's error.log file. If you haven't
already, install cygwin or google for another implementation of tail
so you can watch this file easily in another window.
If the debugger is working (you'll see many messages in error.log
referring to breakpoints if it is), you might need to clear all the breakpoints
from Komodo and restart it, especially if there are breakpoints pointing to eval-type
buffers that no longer exist. This is another bug in Komodo.
Perform the following procedures to configure and execute mod_perl debugging
on Linux and Mac OS X.
If your system meets the requirements outlined at the beginning of
this section, you are ready to build your
own version of Apache with mod_perl.
- Use the "All-In-One" installation technique
described in
the mod_perl documentation. This example assumes use of
Apache 1.3.33
and mod_perl 1.29 , with the following settings:
$ cat makepl_args.mod_perl
DO_HTTPD=1
APACHE_SRC=../apache_1.3.33/src
EVERYTHING=1
ALL_HOOKS=1
USE_APACI=1
APACI_ARGS=--prefix=/usr/local/httpd_perl
- Set the following environment variables in the command window you'll be
launching Apache from. Users of csh and tcsh can make the usual substitutions
for setting environment variables.
export PERL5DB='BEGIN { require q(/home/me/perl/komodo_perl_debugging/perllib/perl5db.pl) }'
export PERL5LIB="/home/me/perl/komodo_perl_debugging/perllib"
export PERLDB_OPTS="RemotePort=localhost:2345"
Note: For verbose logging output from the debugger,
add a LogFile directive to the PERLDB_OPTS variable. For
example:
set PERLDB_OPTS=RemotePort=localhost:2345 LogFile=stderr
- Set up the configuration file mp1.conf (with Apache
installed in /usr/local/httpd_perl/bin) as follows:
ServerType standalone
ServerRoot "/usr/local/httpd_perl/"
PidFile logs/httpd.pid
Timeout 300
KeepAlive On
MaxKeepAliveRequests 100
KeepAliveTimeout 15
MaxRequestsPerChild 0
ThreadsPerChild 50
Port 80
ServerAdmin komodo-joe@example.com
ServerName server.example.com
DocumentRoot "/usr/local/httpd_perl/htdocs/mp1"
<Directory />
Options FollowSymLinks
AllowOverride None
</Directory>
<Directory "/usr/local/httpd_perl/htdocs/mp1">
Options Indexes FollowSymLinks MultiViews
AllowOverride None
Order allow,deny
Allow from all
</Directory>
PerlPassEnv PERL5DB
PerlPassEnv PERL5LIB
PerlPassEnv PERLDB_OPTS
ErrorLog logs/error.log
LogLevel warn
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined
LogFormat "%h %l %u %t \"%r\" %>s %b" common
LogFormat "%{Referer}i -> %U" referer
LogFormat "%{User-agent}i" agent
<IfModule mod_alias.c>
ScriptAlias /cgi-bin/ "/usr/local/httpd_perl/cgi-bin/"
<Directory "/usr/local/httpd_perl/cgi-bin">
AllowOverride None
Options None
Order allow,deny
Allow from all
</Directory>
</IfModule>
# mod_perl setup
Alias /mod_perl/ "/usr/local/httpd_perl/mod_perl/"
<Location /mod_perl>
SetHandler perl-script
PerlHandler Apache::Registry
Options +ExecCGI
allow from all
PerlSendHeader On
</Location>
# mod_perl debugging setup
<IfDefine PERLDB>
<Perl>
use Apache::DB ();
Apache::DB->init;
</Perl>
<Location />
PerlFixupHandler Apache::DB
</Location>
</IfDefine>
<Location /perl-status>
PerlHandler Apache::Status
SetHandler perl-script
</Location>
For this example, there are two files in the mod_perl directory
(/usr/local/httpd_perl/mod_perl/):
test.pl :
use strict;
our $counter;
$counter = defined $counter ? $counter + 1 : 0;
my $r = shift;
$r->send_http_header('text/plain');
$r->print("" . localtime(time()) . ", counter=$counter\n");
print "This is written with a plain print stmt -- the others use \$r->print\n";
$r->post_connection(sub {$r->child_terminate});
printenv.pl :
#!/usr/local/bin/perl
## printenv.pl -- demo CGI program which just prints its environment -*- perl -*-
##
use strict;
print "Content-type: text/html\n\n";
print "<HTML><BODY><H3>Environment variables</H3>";
$a = '' . localtime(time());
print "<h3>Date: $a</h3>\n";
print "<UL>";
foreach (sort keys %ENV) {
my $val = $ENV{$_};
$val =~ s|\n|\\n|g;
$val =~ s|"|\\"|g;
print "<LI>$_ = \"${val}\"</LI>\n";
}
print "</UL></BODY></HTML>";
If you compare this section of the documentation with the same section of the
mod_perl debugging instructions for Windows, you'll notice that the Linux/OS X
version of test.pl contains an extra line:
$r->post_connection(sub {$r->child_terminate});
There are different ways to run Perl in Apache. In this example, you will
debug the scripts in two different environments. First, debug the printenv.pl
snippet with Apache running in single-process mode. Then, debug the test.pl
program in a more standard mode, where Apache spawns child processes.
To debug printenv.pl:
- Start Komodo, listening on port 2345.
- Move to the server root and start the server with this command:
bin/httpd -f conf/mp1.conf -D PERLDB -X
- In the browser, go to
http://localhost/mod_perl/printenv.pl . The Komodo
debugger should now be at the first line of the handler sub
in Apache/Registry.pm.
- Step into the code. Do this by finding the
eval line that evaluates
the compiled script code and setting a breakpoint there. It should look something
like this:
eval { &{$cv}($r, @_) } if $r->seqno;
- Set a breakpoint there, click Go/Continue, and then click
Step In. Notice that instead of stepping into test.pl,
Komodo has stepped into a similar buffer with a Perl "(eval...)" name. This is the
code that
Apache::Registry generates from the original script, and then runs.
You can step through the wrapped code for printenv.pl and return to
Apache::Registry::handler , or click Go/Continue. Notice
that the Komodo debug session ends.
As with Windows, the combination of Komodo, mod_perl in debugging mode, and
Apache in single-server mode tends to break down unpredicatably after each single
debug session, and you must restart both Komodo and Apache.
By adding the one line to end child requests, this tells Komodo when to
end a debug session, and you'll get more iterations.
For the second part of this example, you will debug test.pl.
- Start Apache with this command:
bin/httpd -f conf/mp1.conf -D PERLDB
- In the browser, go to
http://localhost/mod_perl/test.pl .
Now you should be able to debug repeated requests, and Komodo will
end each debug session automatically. Notice that, in test.pl,
the variable $counter is now behaving like a true local variable.
If you run with debug mode off, $counter is repeatedly incremented,
but not each request resets it to 0. This is not how your code will
behave in production mode. By putting the child_terminate
request at the end of the handler, you're guaranteed to have a fresh Perl
interpreter for each request. This makes for a cleaner debugger session, but
defeats the reason for using mod_perl in the first place.
Also, if you try loading a different script that is processed by Apache::Registry ,
Komodo will have difficulty with it, because the new instance of the Perl interpreter assigns
the code the same eval # as the previous one. This is a bug.
An entry was added to debug a mod_perl handler outside Apache::Registry .
This time enter http://localhost/perl-status in the browser address bar.
Barring an extra step through IO::Handle::DESTROY (that same bug), the
debugger stops at the first line of the handler sub in Apache::Status .
Again, you can continue to step through, examine and modify variables as in any other
debug session.
If the debugger doesn't launch, first add logging to the session, by adding
something like "LogFile=stderr" with this setting:
set PERLDB_OPTS=RemotePort=localhost:2345
These strings are written to Apache's error.log file. If you haven't
already, install cygwin or google for another implementation of tail
so you can watch this file easily in another window.
If the debugger is working (you'll see many messages in error.log
referring to breakpoints if it is), you might need to clear all the breakpoints out
of Komodo and restart it, especially if there are breakpoints pointing to eval-type
buffers that no longer exist. This is another bug in Komodo.
If the debugger is not launching, as a last resort try setting the three
Perl-related environment variables in Apache/DB.pm. If the
debugger fires then, verify that you included the PlPassEnv
directives in the conf file.
|