March 2012
Using PGDBG to Debug Programs on Remote Systems
Until now, the PGI debugger PGDBG®, has only supported debugging a program that is running on the same system as the debugger. We call this local debugging.
Local Debugging with PGDBG
The PGI 2012 release of PGDBG introduces support for debugging a program that is running on a different system than the debugger. Remote debugging enables one to use the debugger locally to launch and debug an application remotely.
Remote Debugging with PGDBG
Introducing Connections
Interaction with remote debugging—and local debugging—starts with PGDBG's new Connections tab. A connection is defined as the information the debugger needs to begin debugging a program. The Connections tab is the interface for specifying this information. The Connections tab is also used to manage multiple connections.
If the Connections tab isn't visible, use the View menu to show it.
Setting Up a Remote Connection
When first launched, PGDBG creates a Default connection. If it's launched with an executable, the Default connection's Program field is filled in automatically with the name of the executable.
Let's walk through the process of setting up a connection to debug an application on a remote system. For this example, we'll start with an empty Default connection. The first step is to specify our interest in Remote debugging instead of Local debugging by selecting the Remote option:
Enabling Remote Debugging
Next, specify the path to the program to debug on the remote system:
Setting the Program to Debug Path
Note that only some fields are required as denoted by bold labels. The required fields change based on a combination of Local/Remote and Attach/Core/MPI debugging options.
When the Remote option is selected, the Remote section fields are enabled. Let's take a closer look at this section.
Setting the PGI Path
The PGI Bin Dir field specifies the location of the PGI compilers and tools on the remote system. PGDBG fills in this value for you using its best guess based on the default installation location and current version of the PGI products. You will need to modify this path if your system setup differs from the default. Note that the debugger has no knowledge of your remote system nor does it have any ability to interrogate or exchange configuration information prior to a connection being established.
Both the Host and User fields are required for a remote debugging connection:
Setting Remote Host and User
Depending upon how PGI products are licensed on the remote host, the License Keys field may or may not be required. For example, if the PGI license key file, typically named license.dat, is located in the pgi directory as specified in the PGI Bin Dir field (in our example this would be the /opt/pgi directory), then the License Keys field can be left blank. Such a setup would be representative of a typical PGI Workstation installation.
If the PGI license.dat file is in a directory on the remote system other than the pgi directory, then enter the full path on the remote system to the license key file in the License Keys field.
Setting License Key File Path
If the license.dat file isn't on the remote system at all which is likely the case with a PGI Server or PGI CDK installation, then enter the address, in FlexNet's port@host syntax, to your PGI license server.
Specifying a Floating License Server
We now have enough information entered to launch our smag_ls executable for debugging on the remote host named bd03. But before we do, let's save this connection. To do this, select Save from the Connections menu in the main toolbar, enter a name (such as the name of the executable) and click OK. You can also bring up the Connections menu by right-clicking in the Connections list on the left hand side of the Connections tab. Saved connections persist from one invocation of the debugger to the next.
Saving a Connection
Launching Remote Debugging
To launch debugging, select the desired connection in the Connections list and then click the Open button on the Connections tab. PGDBG then launches an ssh session on the remote system. Depending upon the remote system configuration, you'll next see some kind of authentication request. In our case, we need to specify a password:
Authenticating a Remote Connection
Note that currently, PGDBG supports remote debugging using single-hop ssh only.
Once we are connected to the remote system and the program has launched, the word "active" is appended to the connection name. At this point, debugging proceeds just like it does when you're debugging locally.
Active Connection Designation
Configuring MPI Debugging
Our smag_ls executable can be run serially or in multi-process mode. Let's take a look at how to enable MPI debugging. We'll continue at this point with our remote debugging example but the steps for local MPI debugging are identical. The first step is to check the MPI box to enable the MPI-specific fields in the Connection tab:
Enabling Multi-process Mode
The first MPI-specific field, Command, is required and indicates the full path to the MPI launch executable on the remote system. We built smag_ls with MPICH-2, so we'll use mpiexec:
Setting the MPI Launch Path
The optional Arguments field provides a means for passing arguments to the MPI launch command. For example, use this field to specify the number of processes to launch:
Specifying MPI Launch Options
MPI debugging is launched the same way as serial debugging by clicking the Open button. Be aware that the normal MPI requirements for execution hold whether running on the local or remote systems. For example, if mpdboot must be running on the host machine, that means in our example here we'll need to manually start this program on the remote system before launching our debug session.
The changes we have made to the smag_ls connection haven't been saved yet. This changed-but-not-saved status is reflected by the presence of an asterisk after the connection name in the Connections list. Unsaved changes are just that—unsaved. They won't exist the next time PGDBG is started.
Unsaved Connection Indication
System Requirements
In the PGI 2012 release, the debugger can launch a remote debug session from any PGI-supported platform including Linux, OS X and Windows. The remote system must be running Linux.
Platform Options
Licensing
Using PGDBG to debug a program requires a PGI license on the system where the program being debugged is running. Local debugging requires a local PGI license. Remote debugging requires a freely available license on your local system and a PGI license on the remote system.
Licensing Requirements
Setup
The remote debugging feature is new in PGI 2012. Be sure you have the latest version installed on both your local system and the remote systems on which you want to debug programs. If you don't already have permanent PGI license keys, trial keys are available. PGDBG is included with all PGI Workstation, PGI Server and PGI CDK software installation packages. Debugger-only installers are also available separately on the PGI download page.