Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "CDT/StandaloneDebugger"

< CDT
(Feb 07, 2014)
(Try out Standalone Eclipse Installation)
(13 intermediate revisions by 3 users not shown)
Line 1: Line 1:
This page details the effort to create a stand-alone Debugger using Eclipse.
+
This page details the effort to create a stand-alone C/C++ Debugger using Eclipse.
  
[[Image:StandaloneDebuggerScreenshot.png]]
+
== What is it? ==
  
 +
The Standalone Debugger is an Eclipse application that starts up a subset of the Eclipse CDT (C/C++ Development Tooling)
 +
plug-ins that pertain
 +
specifically to C/C++ debugging.  The application has an accompanying command-line script which allows an end-user to
 +
start up the debugger from the command-line and pass arguments that will start the debugger for the appropriate task.
  
== How to try it out ==
+
The end-user can specify either to debug an application, to attach to an existing process, or to debug a core-file.
 +
In addition, a build log can be specified to aid the Debugger in locating include files and calculate what flags were
 +
used to compile the source code.  This allows the CDT indexer to parse the code properly which is needed for tasks such
 +
as searching code for C/C++ constructs and locating declarations and implementation of C/C++ methods and functions.
  
# Get the CPP EPP Luna M6 product for Linux (either x86_64 or x86)
+
The following details the help text of the downloaded version of the script:
#* (x86_64) http://mirrors.xmission.com/eclipse/technology/epp/downloads/release/luna/M6/eclipse-cpp-luna-M6-linux-gtk-x86_64.tar.gz
+
#* (x86) http://mirrors.xmission.com/eclipse/technology/epp/downloads/release/luna/M6/eclipse-cpp-luna-M6-linux-gtk-x86.tar.gz
+
# Untar the CPP EPP into $HOME/eclipse-cpp-luna-m6 or create a link with that name to where ever you place it
+
# Get the GDBStandalone jars and copy them into the dropins folder of the Eclipse CPP
+
#* cd $HOME/eclipse-cpp-luna-m6/eclipse/dropins
+
#* wget http://download.eclipse.org/linuxtools/gdbstandalone/*.jar
+
# Get the gdbstandalone command (either for x86_64 linux or x86 linux)
+
#* (x86_64 linux) wget http://download.eclipse.org/linuxtools/gdbstandalone/gdbstandalone.zip
+
#* (x86 linux) wget http://download.eclipse.org/linuxtools/gdbstandalone/gdbstandalonex86.zip
+
#* unzip gdbstandalone.zip or gdbstandalonex86.zip into your $HOME directory
+
# Run the command
+
#* $HOME/run-gdbstandalone.sh [-b build_log_location] -e executable_path [arg1 ... argn]
+
#* this will default to workspace-gdbstandalone
+
#* if you run with no arguments, it will debug the same executable you ran the last time
+
  
== Status ==
+
Usage: <nowiki>cdtdebug.sh [ECLIPSE_OPTIONS] [-b BUILD_LOG] [TARGET_OPTION]</nowiki>
  
=== Sept 17, 2013 ===
+
Debug an executable, core-file, or an existing process using the Eclipse
 +
C/C++ Stand-alone Debugger.  Eclipse command-line options may be passed
 +
except for -vmargs which is being used to start up the Eclipse Debugger.
  
* first pass at standalone GDB debugger using CDT components
+
Operation modes:
* using Eclipse application and restricting plug-ins used
+
  -h, --help                print this help, then exit
* debugger is working but indexer is not being invoked
+
* header files not being recognized
+
  
=== Sept 23, 2013 ===
+
Indexing assist options:
 +
  -b BUILD_LOG              build log to use for compiler includes/flags
  
* added default GCC spec file LanguageSettingsProvider
+
Target options:
* this gets standard header files to open in Outline view
+
  -a [pid]                  attach using the optional pid or prompt for a pid
 +
  -c COREFILE              debug core-file (should also specify executable)
 +
  -e EXECUTABLE [ARGS...]  debug given executable (passing ARGS to main)
 +
  -r ADDRESS:PORT          debug toward the specified remote server. Can be
 +
                            combined with the -a option.
  
=== Sept 30, 2013 ===
+
The -e option must be used last as subsequent options are passed to main.
  
* added code to add all source files specified as Project resources
+
Specifying insufficient arguments for a particular target will result in a
* this gets indexer to work and adds non-C-standard header file support
+
dialog displayed to enter the required values for that target.  Specifying
 +
no target option brings up a dialog for debugging an executable with the
 +
executable path, program arguments, and build log filled in from the last -e
 +
invocation, if one exists.
  
=== Oct 07, 2013 ===
+
Wiki page: <http://wiki.eclipse.org/CDT/StandaloneDebugger>
  
* Removed Source and Refactoring menus using IActivity filters
+
The Standalone Debugger is designed to make debugging easier for the C/C++ developer that has little to no experience with Eclipse.
  
=== Oct 14, 2013 ===
+
Normally, to use the C/C++ tools in Eclipse, a user needs to set up an Eclipse project.  An Eclipse project has natures which dictates various menus and actions
 +
that are appropriate for the project.  For example, one might have Eclipse loaded with Java and C/C++ support, but a user does not
 +
want to see Java-specific menu items for a project that has been designated C/C++.  For C/C++, there are multiple natures that may apply due to the fact that there are multiple types of C/C++ projects based on how the project is built (e.g. an Autotools project vs a project which maintains its own Makefile).  Rather than impose the Eclipse project model on the end-user that just wishes
 +
to debug, the Standalone Debugger automatically creates a C/C++ project on behalf of the end-user.  As mentioned, the Standalone Debugger only loads a subset of the all the CDT plug-ins pertaining
 +
to debugging and build plug-ins are not included in this list.  Thus, the Standalone debugger does not have to be concerned with adding natures pertaining
 +
to build.
  
* added support for reading .debug_macro section to find command-line flags
+
To debug an application, attached process, or core-file, in Eclipse, a user would normally have to set up
** currently not being picked up by indexer for header files
+
an Eclipse launch configuration. Launch configurations store all the information required to launch an application such as
 +
what application is being launched, parameters passed, environment variables, etc... In the case of a debug launch configuration this
 +
includes what debugger is used and parameters to the debugger itself.  At present, the debugger used is gdb.  Launch configurations can have different types based on what
 +
is being launched.  This allows the UI to request the appropriate info from the user (e.g. if launching a core-file, the core-file location plus the executable location is needed).  Rather than force an end-user to learn how to use launch configurations, the Standalone Debugger creates an Eclipse launch configuration on behalf of
 +
the end-user based on the parameters used.  The debug session is automatically started so the end-user basically
 +
just has to start debugging which is fairly intuitive in the Eclipse IDE.
  
=== Oct 21, 2013 ===
+
While knowledge of Eclipse launch configurations and projects are not required for users of the Standalone Debugger, they still exist and experienced Eclipse users can manipulate the default projects and launch configurations created if so desired.
  
* added Dwarf4 support to CDT
+
Once the IDE is started, a user may debug other executables, attached processes, or core-files manually. These actions are provided under the top-level File menu and each action will prompt the user for the required information.
** code submitted upstream for review
+
* solved issue with indexer using data discovered from .debug_macro
+
** command line macros now discovered from modules compiled with -g3
+
  
=== Oct 28, 2013 ===
 
  
* changed code to clean-up if an executable is specified
+
The following shows the debugger once started:
** running again with no executable specified will use the last launch
+
* added support for specifying build console
+
** build console is parsed for flags and include path settings
+
  
=== Nov 18, 2013 ===
+
[[Image:StandaloneDebuggerScreenshot.png]]
  
* added progress dialog
+
== How to try it out ==
* added support for running via command-line script
+
** fixed program argument parsing
+
** figured out what minimally is needed to reuse repository
+
* fixed some warnings and errors
+
  
=== Dec 20, 2013 ===
+
There are three flavours of the Standalone Debugger:
  
* added gdbstandalone.zip to run from command line with Luna M4 CPP EPP
+
# Downloaded from eclipse.org as part of a full Eclipse installation
* added default jar to use with Eclipse Luna M4 CPP EPP
+
# Downloaded from eclipse.org as a standalone installation
* completed GDBStandalone.product which contains icons
+
# Installed as part of a Linux distro
* added check for invalid executable
+
** special dialog brought up to fix executable location and enter arguments
+
* fixed NPE issue when running debugger 2nd time on same workspace
+
  
=== Jan 15, 2014 ===
+
=== Try out Full Eclipse Installation ===
 +
To try out the Standalone Debugger from eclipse.org as part of a full Eclipse installation:
  
* added New Executable dialog off of File menu to allow specification of different executable to debug
+
# Download the IDE for C/C++ Developers tar file for your platform
* added Help doc support, but no docs enabled as of yet
+
#* https://www.eclipse.org/downloads
* added Customize Perspective from Window menu to allow enablement of Reverse Debugging and C/C++ Tracepoint support
+
# Untar the C/C++ IDE into a local directory (let's call this $CDT_DIR)
 +
# cd $CDT_DIR/eclipse/plugins/org.eclipse.cdt.debug.application_*/scripts
 +
# There, run the command:
 +
#* /bin/sh ./install.sh
 +
#* this will create the directory: $HOME/cdtdebugger for you where the cdtdebug.sh script will be installed
 +
# To run the debugger:
 +
#* $HOME/cdtdebugger/cdtdebug.sh ... (see above or use --help option for arguments)
 +
#* this will default to use the workspace: workspace-cdtdebug if you do not specifiy a workspace via the -data option
  
=== Jan 17, 2014 ===
+
=== Try out Standalone Eclipse Installation ===
  
* added Help menu which contains Help Contents, Search, Dynamic Help, and About Eclipse items
+
# Download the Standalone Debugger from the CDT Downloads page https://eclipse.org/cdt/downloads.php
 +
# Untar the C/C++ Standalone Debugger into a local directory (let's call this $CDT_DEBUG_DIR)
 +
# To run the debugger:
 +
#* $CDT_DEBUG_DIR/cdtdebug ... (see above or use --help option for arguments [[#Command Line Help|--help Not Yet Supported]])
 +
#* this will default to use the workspace: workspace-cdtdebug if you do not specifiy a workspace via the -data option
  
=== Feb 07, 2014 ===
+
=== Try out Linux Distro ===
 +
 
 +
To try out the Standalone Debugger on a Linux distro:
 +
 
 +
# Install or update the eclipse-cdt package to 8.4.0-1 or higher
 +
# The installation of the package will install a cdtdebug script for you in a shared folder (e.g. /usr/bin/cdtdebug)
 +
# Running the cdtdebug binary will create a unique folder for you in your $HOME directory (e.g. $HOME/fcdtdebugger for Fedora)
 +
#* This enables you to have both the downloaded version and installed distro version at the same time
 +
# cdtdebug .... (see above or use --help option for arguments)
 +
 
 +
The two versions are essentially the same except for the config.ini files that are used in start-up.  For a distro version
 +
of eclipse-cdt, CDT plug-ins and features need to be specified as file locations whereas in the download case, it is sufficient
 +
to specify Eclipse bundle names.
 +
 
 +
In the case of the downloaded version, updating some plug-ins and features is fine since the bundle names do not change.
 +
For the distro version, the CDT is updated by updating the entire eclipse-cdt package at once and this will update the
 +
cdtdebug script and its accompanying config.ini file.
 +
 
 +
Mixing the two types of CDT is not supported for the Standalone Debugger.  This can occur if the user installs a distro version
 +
of the Eclipse platform and then uses the Eclipse Update within the IDE to download the CDT Standalone Debugger from eclipse.org.
 +
This installs the feature and plug-ins into the user's local $HOME/.eclipse folder.  Running the install.sh script from there
 +
will check for this and give an error.
 +
 
 +
== Status ==
  
* added User Guide which is transformed CDT guide
+
The Standalone Debugger is released with the Eclipse Mars which is available from the Eclipse downloads URL.  It is part of the
* added mnemonics for menus
+
Eclipse IDE for C/C++ Developers download and can also be downloaded via the Eclipse Mars site using the Eclipse Update facility (under the
* updated for Luna M5
+
top-level Help menu).  Some fixes have already been made to the Debugger and these are found at the CDT nightly download site:
 +
http://download.eclipse.org/tools/cdt/builds/master/nightly
 +
For the standalone debugger installation, the update site is: http://download.eclipse.org/tools/cdt/builds/master/nightly/rcp-repository/
  
=== May 09, 2014 ===
+
=== Command Line Help ===
  
* Standalone debugger is part of Luna M7!
+
In the case of the standalone install --help is not supported yet, please see [https://bugs.eclipse.org/469660 Bug 469660]
* includes core-file debugging support
+
* includes attach to executable debugging support
+

Revision as of 16:23, 3 March 2016

This page details the effort to create a stand-alone C/C++ Debugger using Eclipse.

What is it?

The Standalone Debugger is an Eclipse application that starts up a subset of the Eclipse CDT (C/C++ Development Tooling) plug-ins that pertain specifically to C/C++ debugging. The application has an accompanying command-line script which allows an end-user to start up the debugger from the command-line and pass arguments that will start the debugger for the appropriate task.

The end-user can specify either to debug an application, to attach to an existing process, or to debug a core-file. In addition, a build log can be specified to aid the Debugger in locating include files and calculate what flags were used to compile the source code. This allows the CDT indexer to parse the code properly which is needed for tasks such as searching code for C/C++ constructs and locating declarations and implementation of C/C++ methods and functions.

The following details the help text of the downloaded version of the script:

Usage: cdtdebug.sh [ECLIPSE_OPTIONS] [-b BUILD_LOG] [TARGET_OPTION]
Debug an executable, core-file, or an existing process using the Eclipse
C/C++ Stand-alone Debugger.  Eclipse command-line options may be passed
except for -vmargs which is being used to start up the Eclipse Debugger.
Operation modes:
  -h, --help                print this help, then exit
Indexing assist options:
  -b BUILD_LOG              build log to use for compiler includes/flags
Target options:
  -a [pid]                  attach using the optional pid or prompt for a pid 
  -c COREFILE               debug core-file (should also specify executable)
  -e EXECUTABLE [ARGS...]   debug given executable (passing ARGS to main)
  -r ADDRESS:PORT           debug toward the specified remote server. Can be
                            combined with the -a option.
The -e option must be used last as subsequent options are passed to main.
Specifying insufficient arguments for a particular target will result in a
dialog displayed to enter the required values for that target.  Specifying
no target option brings up a dialog for debugging an executable with the
executable path, program arguments, and build log filled in from the last -e
invocation, if one exists.
Wiki page: <http://wiki.eclipse.org/CDT/StandaloneDebugger>

The Standalone Debugger is designed to make debugging easier for the C/C++ developer that has little to no experience with Eclipse.

Normally, to use the C/C++ tools in Eclipse, a user needs to set up an Eclipse project. An Eclipse project has natures which dictates various menus and actions that are appropriate for the project. For example, one might have Eclipse loaded with Java and C/C++ support, but a user does not want to see Java-specific menu items for a project that has been designated C/C++. For C/C++, there are multiple natures that may apply due to the fact that there are multiple types of C/C++ projects based on how the project is built (e.g. an Autotools project vs a project which maintains its own Makefile). Rather than impose the Eclipse project model on the end-user that just wishes to debug, the Standalone Debugger automatically creates a C/C++ project on behalf of the end-user. As mentioned, the Standalone Debugger only loads a subset of the all the CDT plug-ins pertaining to debugging and build plug-ins are not included in this list. Thus, the Standalone debugger does not have to be concerned with adding natures pertaining to build.

To debug an application, attached process, or core-file, in Eclipse, a user would normally have to set up an Eclipse launch configuration. Launch configurations store all the information required to launch an application such as what application is being launched, parameters passed, environment variables, etc... In the case of a debug launch configuration this includes what debugger is used and parameters to the debugger itself. At present, the debugger used is gdb. Launch configurations can have different types based on what is being launched. This allows the UI to request the appropriate info from the user (e.g. if launching a core-file, the core-file location plus the executable location is needed). Rather than force an end-user to learn how to use launch configurations, the Standalone Debugger creates an Eclipse launch configuration on behalf of the end-user based on the parameters used. The debug session is automatically started so the end-user basically just has to start debugging which is fairly intuitive in the Eclipse IDE.

While knowledge of Eclipse launch configurations and projects are not required for users of the Standalone Debugger, they still exist and experienced Eclipse users can manipulate the default projects and launch configurations created if so desired.

Once the IDE is started, a user may debug other executables, attached processes, or core-files manually. These actions are provided under the top-level File menu and each action will prompt the user for the required information.


The following shows the debugger once started:

StandaloneDebuggerScreenshot.png

How to try it out

There are three flavours of the Standalone Debugger:

  1. Downloaded from eclipse.org as part of a full Eclipse installation
  2. Downloaded from eclipse.org as a standalone installation
  3. Installed as part of a Linux distro

Try out Full Eclipse Installation

To try out the Standalone Debugger from eclipse.org as part of a full Eclipse installation:

  1. Download the IDE for C/C++ Developers tar file for your platform
  2. Untar the C/C++ IDE into a local directory (let's call this $CDT_DIR)
  3. cd $CDT_DIR/eclipse/plugins/org.eclipse.cdt.debug.application_*/scripts
  4. There, run the command:
    • /bin/sh ./install.sh
    • this will create the directory: $HOME/cdtdebugger for you where the cdtdebug.sh script will be installed
  5. To run the debugger:
    • $HOME/cdtdebugger/cdtdebug.sh ... (see above or use --help option for arguments)
    • this will default to use the workspace: workspace-cdtdebug if you do not specifiy a workspace via the -data option

Try out Standalone Eclipse Installation

  1. Download the Standalone Debugger from the CDT Downloads page https://eclipse.org/cdt/downloads.php
  2. Untar the C/C++ Standalone Debugger into a local directory (let's call this $CDT_DEBUG_DIR)
  3. To run the debugger:
    • $CDT_DEBUG_DIR/cdtdebug ... (see above or use --help option for arguments --help Not Yet Supported)
    • this will default to use the workspace: workspace-cdtdebug if you do not specifiy a workspace via the -data option

Try out Linux Distro

To try out the Standalone Debugger on a Linux distro:

  1. Install or update the eclipse-cdt package to 8.4.0-1 or higher
  2. The installation of the package will install a cdtdebug script for you in a shared folder (e.g. /usr/bin/cdtdebug)
  3. Running the cdtdebug binary will create a unique folder for you in your $HOME directory (e.g. $HOME/fcdtdebugger for Fedora)
    • This enables you to have both the downloaded version and installed distro version at the same time
  4. cdtdebug .... (see above or use --help option for arguments)

The two versions are essentially the same except for the config.ini files that are used in start-up. For a distro version of eclipse-cdt, CDT plug-ins and features need to be specified as file locations whereas in the download case, it is sufficient to specify Eclipse bundle names.

In the case of the downloaded version, updating some plug-ins and features is fine since the bundle names do not change. For the distro version, the CDT is updated by updating the entire eclipse-cdt package at once and this will update the cdtdebug script and its accompanying config.ini file.

Mixing the two types of CDT is not supported for the Standalone Debugger. This can occur if the user installs a distro version of the Eclipse platform and then uses the Eclipse Update within the IDE to download the CDT Standalone Debugger from eclipse.org. This installs the feature and plug-ins into the user's local $HOME/.eclipse folder. Running the install.sh script from there will check for this and give an error.

Status

The Standalone Debugger is released with the Eclipse Mars which is available from the Eclipse downloads URL. It is part of the Eclipse IDE for C/C++ Developers download and can also be downloaded via the Eclipse Mars site using the Eclipse Update facility (under the top-level Help menu). Some fixes have already been made to the Debugger and these are found at the CDT nightly download site: http://download.eclipse.org/tools/cdt/builds/master/nightly For the standalone debugger installation, the update site is: http://download.eclipse.org/tools/cdt/builds/master/nightly/rcp-repository/

Command Line Help

In the case of the standalone install --help is not supported yet, please see Bug 469660

Back to the top