EclipseEpicPerlDebug

Setting up an EPrints development environment using Eclipse, Epic and the Perl Debugger

This describes a way to implement Perl development within Eclipse, which will help enable code inspection, auto-completion (in some circumstances), and most importantly interactive debugging with running processes.

Set up the development environment

You will need to install Eclipse, which can be obtained from:

http://www.eclipse.org/

You should ensure that when Eclipse runs it runs using the Sun Java implementation, NOT the gcj, as there are bugs in the gcj which prevent Perl debugging from working correctly.

Once you have obtained Eclipse, you need to install the EPIC Perl development extension to the platform. Details for EPIC can be obtained at:

http://www.epic-ide.org/download.php

Go to:

  Help -> Software Updates -> Find and Install ...

Select the button: "Search for new features to install", and hit "Next"

Add a new remote site, using the url for epic:

http://e-p-i-c.sf.net/updates

Download and install the latest version of EPIC, and follow the on-screen instructions for running it.

You now have all the tools you need to develop with Perl.

Set up your code in the IDE

Start or open your project as a "Perl Project" in Eclipse

To set up any external libraries upon which your project is dependent, right click on the project name and select "Properties". Go to "Perl Include Path" and insert the path to the root of the perl modules which your code will depend on.

I have found it useful to import the entire EPrints perl module as another Perl Project in Eclipse, and to set that on the "Perl Include Path". In this way, when you ctrl-click on a package/module name, Eclipse will open the code in a new source tab.

Install Perl Modules for interactive debugging

You will need to ensure that 2 particular perl modules are installed to enable interactive debugging. Download and install the following modules from CPAN:

Apache::DB; this provies a wrapper for perldb to run in a web context:

http://search.cpan.org/~fwiles/Apache-DB-0.14/

PadWalker; this provides real time variable inspection and modification:

http://search.cpan.org/dist/PadWalker/

Set up Apache for interactive debugging

In your apache configuration, you need to include

• The include paths of your perl module
• The include path of the Eclipse debug code (which we will create in a section below, for the time being just trust me on the file paths)
• The auto-reload of changed files for our module (which saves us from having to restart apache all the time) (Reload configuration courtesy of Tim Brody)
• The perl options for debugging

You will need to include something like the following in your apache configuration (I have this in my /etc/apache2/httpd.conf file):

PerlSwitches -I/path/to/your/development/perl/module -I/path/to/your/development/perl/module/debug

PerlModule Apache2::Reload
PerlInitHandler Apache2::Reload
PerlSetVar ReloadAll Off
PerlSetVar ReloadModules "MyModule::*"

<IfDefine PERLDB>

    PerlSetEnv PERLDB_OPTS "RemotePort=127.0.1.1:5000 DumpReused ReadLine=0 PrintRet=0"
    PerlSetEnv PERL5DB "BEGIN { $DB::CreateTTY=0; require '/path/to/your/development/perl/module/debug/perl5db.pl'; }"
   
    <Perl>
      use Apache::DB ();
      Apache::DB->init;
    </Perl>
  
    <Location />
      PerlFixupHandler Apache::DB
    </Location>
  
</IfDefine>

The PerlSwitches line includes two module locations into the @INC configuration for the mod_perl environment. The first of these is the root of the directory where the perl modules that you are developing are located. This is only necessary if you are going to try to set up the debugger so that code in your dev environment will also run as part of the live application. If you will deploy your code to another application before execution, this include is not necessary.

The second of these is the location of the debug tools that EPIC will use to interrogate the Apache interactive debugger. I have placed these in the development environment here, so that we can manage them alongside our other code. We will come on to how to generate the content of this directory in the next point; for the time being just ensure that there is a place for it to go, and that the include points to it

In the conditional <IfDefine> we set the configuration to ensure that the interactive debugger can send information out to the EPIC debug environment, and that at can find the perl5db.pl script. Note that the perl5db.pl script is part of the EPIC debugger configuration, and will be created in the next step.

The rest of the configuration ensures that mod_perl is using Apache::DB. This will only happen when we pass -D PERLDB as an argument when we start apache.

Generating the EPIC debug configuration

In Eclipse, go to:

 Run -> Debug ...

Start a new "Perl Remote" configuration, specifying the project you wish to work with, and setting the "Target Host" path to the location of the perl module in your IDE. On the first execution of this configuration you must also specify that you want to create the debug package, and give it a path to save the file to. The other settings on this page should be fine as the default (assuming that you are running Eclipse and Apache on the same machine).

Run the configuration, which will attemt to connect to the debugger. At this stage it will fail, so stop the process and go and look for the debug package which was created where you requested. Unzip this file, and discard all content other than perl5db.pl and files of the form *epic*.pm. Place these remaining files into the "debug" directory specified in the apache configuration in the previous section.

Start apache in debug mode

We can now start apache in debug mode, using the following command:

sudo apache2ctl -k start -X -D PERLDB

This will start the apache web server in non-forking mode (-X), and will invoke the configuration in our <IfDefine> tag, enabling debugging.

You will find that the command line is not returned to you when this operation is complete, as the debugger retains control of it.

Issue debugger requests

In the EPIC configuration, ensure that "suspend at first line" is set, execute the debugger configuration and execute a web request to your application. The code should suspend at the first executable line, and you will be moved from the "Perl" perspective ofEclipse to the "Debug" perspective. The currently executing file will be opened in front of you, and the current line of the application will be highlighted. You should now be able to set breakpoints in this file, and to step through it line by line usign the Eclipse debugger controls.

I also find it convenient to set EPIC to show you the debugger console. This gives you another way of seeing what's going on inside the perl interpreter while your code is running.

Setting break points

With the code running from inside your development environment, you can simply open the file you wish to debug, and drop a breakpoint in on any active line of code by double clicking in the left margin of the code editor window.

When you make a request by, for example, loading the EPrints home page, the execution will suspend at first the very first line (assuming this is the first request) and then at your own breakpoint, and you will be brought into the "Debug" perspective in Eclipse if not already there.

It is worth reading the Eclipse documentation on how to use the debug environment, as it has a number of very useful features.

Terminating the process

You should not attempt to stop the process using the red "stop" button in the Eclipse debugger. This will cause Eclipse to hang until you then manually shut apache down from the command line. Instead, close down apache first, and then use the stop button in the eclispe debugger to terminate the debug listener. You can then start up both of these processes in either order.

Watching for Errors

Sometimes the process you execute will fail if there is a compile-time error. The debugger will not get a change to attach to a process, so it will not be able to show you what is wrong. It is therefore necessary to also attach to the apache log file to see what is going on. Look in /var/log/apache2/error.log for error messages. I use a command like:

 tail -f var/log/apache2/error.log

which allows me to watch the end of this file as errors scroll past.

Further Reading

Much of this How-To has been developed by extensive reference to this blog post:

http://plosquare.blogspot.com/2009/04/debugging-modperl-applications-with.html