How To

Community Plug-in Development: Debugging with Eclipse


Follow these instructions to debug your plug-in using GroovyEclipse.

Install the GroovyEclipse plug-in (Groovy development only)

If you are developing with Groovy, install the GroovyEclipse plug-in. From the Eclipse Menu. Select Help | Eclipse Marketplace and search for “GroovyEclipse plugin.” Locate the plug-in and install.

Set up a debug configuration for your plug-in

    1. In the Eclipse Package Explorer tab, highlight your plug-in project, right-click and select DebugAs | DebugConfigurations.
      At the Debug Configurations dialog, select Remote Java Application, right-click and select New.

    1. Edit the fields for the new project on the Connect tab. Edit Host to reflect the IP address of the agent where your plug-in executes. If the agent is on your local machine, and not a VM, enter “localhost” in this field. In the Port field, enter “11000” or the port on the agent you will use to debug your plug-in.

    1. (Optional) If a “Source not found” error message appears on the Source tab, enable the Search for duplicate source files on the path checkbox.

  1. Click Apply , then click Close.

Set Breakpoints

Access Breakpoint properties in any of the following ways:

  • Double-click anywhere in the source code line, or right-click in that area and select Toggle Breakpoint.
  • Right-click and select Breakpoint Properties.

Make updates for debugging

Modify the Groovy script (Groovy development)

  1. In the install-directory of the target agent, modify the Groovy script at:
    <agent-install-dir>/opt/groovy-1.8.8/bin/groovy (for Linux)
    <agent-install-dir>\opt\grooy-1.8.8\bin\groovy.bat (for Microsoft Windows)

  2. Add the following script code (Linux and Microsoft Windows versions are shown). Edit DEBUG_PLUGIN_NAME with the name of your target plug-in. Put the script code anywhere in the file, before startGroovy… .
    -------- script code for Linux: --------
    DEBUG_PORT NUM=11000
    case "$@" in
        *"/$DEBUG_PLUGIN_NAME "*) JAVA_OPTS="$JAVA_OPTS -agentlib:jdwp=transport=dt_socket,address=$DEBUG_PROT_NUM,server=y,suspend=y" ;;
    -------- script code for Microsoft Windows: --------
    DEBUG_PORT NUM=11000
    echo %* | findstr "\%DEBUG_PLUGIN_NAME% "
    if ERRORLEVEL == 1 goto SKIP_DEBUG
    set "JAVA_OPTS=%JAVA_OPTS% -agentlib:jdwp=transport=dt_socket,address=%DEBUG_PROT_NUM%,server=y,suspend=y"

Note: If you do not know the name of the Groovy script for the plug-in you are debugging, you can look at the output for previous executions of your plug-in step. The output line that begins with plug-in command: (near the top of the output) contains the name of the plug-in Groovy script that is executed.

Modify the plugin.xml (Java development)

Java-based plugins don’t utilize the startGroovy script. For this reason, you to add the agentlib Java system property in the plugin.xml file of the plug-in step being debugged. You can pass the additional system property to the Java executable by modifying the step-type command as follows. In this example, the debug port is directly specified with the agentlib property.

Run the UCD process

Run the UCD process that invokes your plug-in on the target agent. When the plug-in is executed, it should wait for the debugger to attach to the agent’s process before it continues executing. At this point, you can launch the debugger to attach to this process. To do so, start debugging with the debug configuration you created.

Note: Make sure you have at least one breakpoint set that your code will hit, otherwise the process will run (and may complete) once the debugger is attached.

  1. Access the Debug Configurations dialog from the debug dropdown () or by selecting Run | Debug Configurations… from the menu.
  2. At the Debug Configurations menu, highlight the configuration you created, and click Debug.

Note: The next time you need to attach the debugger to the paused process, you can simply select to debug with this configuration from the debug icon, without accessing the Debug Configuration dialog.