Overview
Using the commercial application "Komodo IDE" from ActiveState, it is possible to debug a running ec-perl script from a remote machine. This technique allows most standard GUI debugging features including stepwise execution, variable inspection, and breakpoints.
| This technique is somewhat advanced, and is recommended only for those with some experience at IDE-based development and debugging. As this technique has the capability of damaging data and will almost certainly degrade system performance, it ++should not++ be used on production or high-availability installations except under extreme circumstances. This will only work with the commercial version of Komodo IDE — it will not work with the free "Komodo Edit" application as that edition lacks the debugger feature. These instructions were tested using the 5.2.4 version of Komodo IDE. Appropriate licenses are the responsibility of the user; no guarantees are given as to the fitness of this technique for any purpose. |
Preparation
The method involves applications running on up to three different machines (the Agent , the EC Server , and the Debugger). In practice, any or all of these applications may be running on the same machine.
The Agent: The machine running the CloudBees CD (CloudBees Flow) Agent process, where the target Step will actually execute.
The Agent machine requires a copy of the Komodo IDE debugger library. This is non-platform-specific Perl code, and can be found in the 'dbgp/perllib' sub-directory of the Komodo installation or downloaded from your ActiveState support account. More information can be found in the Komodo IDE help by searching for "debugging perl remotely".
Two "Environment Variables" must be set for the user under which the CloudBees CD (CloudBees Flow) Agent executes. These variables must be set before the script begins to execute, so the most straightforward method is to set the values in the general user’s environment. These are standard Perl environment variables; setting their values will affect the behavior of Perl in debug mode on this machine (perl -d). Note: There are other ways to have the variables set prior to execution, such as wrapper scripts.
| Variable | Value |
|---|---|
|
Path to Komodo Debugger Libraries on the Agent machine (e.g. "C:\Program Files (x86)\ActiveState Komodo IDE 5\lib\support\dbgp\perllib") |
|
Definition of the "RemotePort=" option; the value is the IP Address or name of the Debugger machine and the port number on which Komodo will be listening, separated by a colon (e.g., "RemotePort=192.168.2.17:9000"). The port number must match the port specified in the Komodo IDE; see ec:below. |
This figure shows the variables set on a Windows machine in the Agent machine’s standard Environment Variables management interface:
The EC Server: The CloudBees CD (CloudBees Flow) Server, where the target Step is defined.
The "Shell" option of the Step definition in CloudBees CD (CloudBees Flow)requires the "-d" option appended to the "ec-perl" command. This option turns on the actual debugging in Perl itself and can be used to switch debugging on and off.
The Debugger: The machine running the Komodo IDE application.
| See the help for the Komodo IDE for specifics on how to use the IDE and for debugger control details. |
On the Debug menu, the "Listen for Debugging Connections" must be checked (1).
Open the Edit/Preferences dialog, and in the Debugger category select "Connections". Set the port to a specific port (the common port to use is 9000). Using a debugger proxy to circumvent firewall issues is possible but is beyond the scope of this article; see the Komodo IDE help for details. This must be the same port number as set in the Agent’s PERLDB_OPTS environment variable (see ec:above).
Method
When the Step is run on the Agent machine, the ec-perl interpreter will pass the -d option to Perl itself, which will perform a number of setup activities. (For details on this, see the Perl manpage "perldebguts".) The Komodo debugging library uses HTTP to communicate with the Komodo debugger running on the Debugger machine over the specified port.
The target code is defined on the EF Server in the Step definition. CloudBees CD (CloudBees Flow) sends a copy of the code to Agent machine for execution, and the Komodo debugger library on the Agent sends an instrumented copy of the code to the Debugger machine.
If Komodo is not the current foreground application on the Debugger machine, it will use the system notification mechanism to attract the user’s attention (such as, a flashing icon). The debugger automatically breaks just before the first executable line of code.