Starting The Debugger

The debugger is started from the command-line using the cdtdebug.sh script. The script contains the command-line needed to start Eclipse and to pass appropriate parameters at start-up. The following are the command-line options supported:

-a

This option specifies that you want to attach and debug an existing executable that is running on your system. The option will bring up a dialog which contains a list of current executables running and you may choose the executable(s) you wish to attach to. You also have the option of starting a new executable, if desired, but you cannot specify a build log using this method.

-b <build log>

This option specifies an optional build log to use for indexing the source. The build log is simply the output of a makefile build where the options used to compile the various source files are displayed. The indexer uses these options to figure out what flags and include paths were used and thus can properly parse the code to match the executable. The parsed tree is used to navigate within the code to search for C/C++ elements or to calculate a call hierarchy. If this log is not provided, the Stand-alone Debugger has only the compiler built-ins and default include paths to use which means it may not search properly.

-c <core file>

This option specifies a path to a core file to debug for an executable. The core file should have been created by the specified executable. The executable is specified using the -e option, which is later described. If the core file is invalid or no valid executable is also specified, a dialog will be brought up to allow you to enter the required information.

-e <executable> [args*]

This option specifies a path to an executable to be debugged. If the -c option is previously specified, the executable will be used in conjunction with the core file specified by the -c option. If the -c option is not used, then any additional arguments on the command line will be passed to the main method of the C/C++ application when it is debugged. If you do not specify any of the -a, -c, or -e options (e.g. starting up the Stand-alone Debugger with no arguments), the last valid executable used invoking the debugger (if this isn't the first invocation) will be offered to you via a dialog, which includes the original program arguments and build log. You then have the choice of simply hitting the OK button to debug the last executable again or to change the arguments as desired. If the executable location you specify is invalid or no executable is specified and no previous executable exists, a dialog will be brought up to allow you to enter the required information. The dialog will be appropriate to whether you have selected to debug a core file (-c specified) or not.

Automated Set-up

As mentioned, the Stand-alone Debugger will initialize Eclipse objects on your behalf on start-up so you can immediately start debugging. For starters, the executable you specify is is imported on your behalf into an Eclipse C/C++ project within the Workspace. An Eclipse project is a virtual container object that contains folders, files, etc. and has a particular nature. Folders and files may be virtual and may actually link to objects outside of the workspace. In this particular case, the debug info of the executable specified is used to determine the location of the source files. Each source file is imported in the project, virtually, via a link. This is done so that the C/C++ indexer, which usually works on a project being developed within Eclipse, has access to all code when it is parsing.

The nature of a project determines what menus, actions, and views are valid for that project. Menus, actions, and views that are not valid are not made visible. This helps to remove the clutter of all contributed plug-ins to what is pertinent to the task at hand (e.g. if the C/C++ and Java IDE plug-ins are both present, one does not want to see Java tasks when working on a C/C++ project). Many of the plug-ins being used in the Stand-alone debugger only work on C/C++ projects. In most cases, the name of the C/C++ project being used will be Executables. This project is reserved for importing executables into the CDT without creating a project first.

Another Eclipse concept is the Perspective. An Eclipse perspective is a set of views and the layout of the main Eclipse Window. A perspective will have a default layout and can be modified the end-user for future reference (e.g. adding or removing views). For the purposes of debugging, one should use the Debug Perspective. The Stand-alone Debugger opens the Debug Perspective by default for you which brings up the various views needed to debug your program.

To debug and executable, one needs to launch it via the debugger and to provide options both for the executable and the debugger (in this case, GDB). All the information required to launch and debug the executable is stored in an Eclipse object known as a Launch Configuration. Various plug-ins can contribute different forms of Launch Configuration which can in turn provide UI elements for settings. In the case of the Stand-alone Debugger, debugging an executable results in the automatic creation of a C/C++ Local Application Launch configuration. This just means that the particular launch configuration is meant to be used for a local application. This launch configuration is shared for debugging purposes and when debugging, additional parameters are available in the UI for gdb settings (e.g. gdb path, reverse debugging). You do not need to create a launch configuration yourself, but you may wish to edit the one created on your behalf.

Initial Debugger Layout

Stand-alone Debugger